feat(hooks): defineHook — typed hook authoring with ctx payload/wrap/abort

[edusperoni]

Stacked on #6099 (feat/di-modernization-phase1).

PR Checklist

• The PR title follows our guidelines: https://github.com/NativeScript/NativeScript/blob/master/tools/notes/CONTRIBUTING.md#commit-messages.
• There is an issue for the bug/feature this PR is for. To avoid wasting your time, it's best to open a suggestion issue first and wait for approval before working on it.
• You have signed the CLA.
• All existing tests are passing: https://github.com/NativeScript/nativescript-cli/blob/master/CONTRIBUTING.md#contribute-to-the-code-base
• Tests for the changes are included.

What is the current behavior?

Hooks are plain functions whose shape the CLI infers at runtime: services arrive via parameter-name injection (deprecated, runtime-traced), the payload via a magic hookArgs parameter, middleware by returning a function (implicit and undocumented), and aborting by throwing an error carrying stopExecution/errorAsWarning fields.

What is the new behavior?

A typed, explicit hook-authoring API — fully additive; every existing hook keeps working unchanged.

const { defineHook, inject, DoctorService } = require("nativescript/contracts");

module.exports = defineHook("before-prepare", async (ctx) => {
	const doctorService = inject(DoctorService);   // services via inject(), as everywhere else
	ctx.payload.args.push("--offline");            // the operation payload, mutable as before
	ctx.wrap(async (args, next) => next(...args)); // explicit middleware (was: return a function)
	ctx.abort("reason", { asWarning: true });      // explicit abort (was: throw + stopExecution)
});

• lib/common/define-hook.ts is import-free (loading it can never boot a second CLI runtime) and re-exported from nativescript/contracts; definitions carry a Symbol.for marker so duplicated CLI copies in an extension tree recognize each other's definitions.
• hooks-service runs definition modules on a dedicated path: no parameter-name parsing, no projectData promotion hack, no deprecation report. Plain-function hooks are untouched. .mjs default exports are recognized.
• wrap() middlewares feed the exact channel legacy returned-functions use, so they compose with the @hook decorator chain identically (11 new tests pin payload identity/mutation, inject-in-handler, middleware wrap + short-circuit, abort both ways, legacy coexistence + tracer isolation, .mjs, and name-mismatch tracing).
• One deliberate edge: per-directory hook results are now flattened once so multi-middleware hooks surface correctly. A legacy hook that returned an array of functions was silently dropped before and becomes middleware now — returning anything was always outside the documented contract (fulfillment values are ignored), so this is considered theoretical.
• extending-cli.md now leads with defineHook; plain-function hooks and parameter-name injection remain documented as the transitional and legacy tiers.

Full suite: 110 files, 1609 passed / 38 skipped; the yok oracle, public-API test, and compat fixtures are untouched.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 287a7505-c08f-45cf-a659-2535538e6a9b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}