@c9up/helix 0.1.8 → 0.1.10

package/README.md

@@ -16,12 +16,242 @@ their own integration packages, not here — helix stays dependency-light.
 ## CLI
 
 ```sh
-helix test [paths...]            # run a one-shot suite (e.g. `helix test app`)
+helix test [paths...|suites...]  # run paths, or suites named in helix.config
 helix test --watch               # re-run on file changes
 helix test --coverage            # V8 coverage + LCOV + thresholds
 helix test --diff-cov            # diff coverage vs main branch
+helix test --bail                # stop at the first failure
+helix test --failed              # re-run what failed last time
+helix test --list-pinned         # print the .pin()ed tests, run nothing
 ```
 
+## Suites
+
+Declare named suites and `helix test unit` runs one, the AdonisJS way.
+With no positional, every suite runs, in order:
+
+```ts
+// helix.config.ts
+export default {
+  timeout: 2_000,          // AdonisJS `tests.timeout`
+  forceExit: false,        // AdonisJS `tests.forceExit`
+  suites: [
+    { name: "unit", files: ["tests/unit/**/*.spec.(js|ts)"] },
+    { name: "functional", files: ["tests/functional/**/*.spec.ts"], timeout: 30_000 },
+  ],
+}
+```
+
+A suite's name reaches the tests as `ctx.test.options.meta.suite.name`
+and rides on the `suite:*` events — `meta.suite` is the suite object, as
+in Japa, not the bare string. Without a config file — or when a
+positional is not a suite name — positionals stay paths, exactly as
+before.
+
+A suite may carry `configure(suite)` — Japa's `TestSuite.configure` — which
+gets the same handle as the bootstrap's `configureSuite` and runs after it.
+It costs an import of the config module in EVERY worker, because a function
+cannot cross the process boundary: `configureSuite` in `tests/bootstrap.ts`
+does the same job for free, and is what AdonisJS itself uses. Nothing is
+imported when no suite declares one.
+
+Suites run one after another, and the sequence is what the run-wide
+flags act on: `--watch` re-runs every selected suite on each change (one
+watcher for the whole sequence), `--bail` stops at the suite that failed,
+and the `--failed` cache holds every suite's failures.
+
+`files` takes Japa's three forms — one pattern, an array of them, or a
+callback returning the URLs (`files: () => [pathToFileURL(…)]`), which
+runs in the CLI process and can therefore reach files no suffix-based
+discovery would find.
+
+Pattern entries are plain paths (a directory is walked with helix's
+suffix discovery) or globs — `*`, `**`, `?`, `{a,b}`, `(a|b)`, `[abc]`
+and the extglob quantifiers `@(a|b)`, `?(a|b)`, `*(a|b)`, `+(a|b)`,
+which covers AdonisJS's own defaults verbatim
+(`tests/unit/**/*.spec.(js|ts)`). An entry starting with `!` subtracts
+from what the others selected (`"!tests/unit/slow/**"`).
+
+One form is refused rather than approximated: the negated extglob GROUP
+`!(a|b)`. Its semantics have no faithful regex rendering, and a
+near-miss would silently select the wrong files — the one thing a file
+selector must not do. Write a `!pattern` entry instead.
+
+Filters follow Japa: `--tests` and `--groups` take exact titles,
+`--files` matches path segments (`--files=user`, `--files=unit/*`),
+`--tags` matches ANY of the given tags (`--match-all`, spelled
+`--matchAll` too, requires every one), and a `~@tag` / `!@tag` entry
+excludes. `--suite=<name>` names the suite the files belong to
+(`"default"` otherwise, like Japa's implicit suite). `--grep` is a helix
+extra: a regex or substring over the full test name.
+
+`--bail` stops at the first failure; `--bail-layer=group|suite|runner`
+says how far that reaches. Within a file the remaining tests are
+reported as SKIPPED, like Japa. Files not yet started are dropped
+rather than skipped — a named deviation that follows from per-file
+process isolation: reporting them as skipped would mean spawning every
+remaining file just to collect names.
+
+`--list-pinned` collects the files, prints the tests marked `.pin()` and
+runs nothing — the global `setup` hooks are skipped too, as in Japa,
+since nothing they would open gets used. It stays on the TypeScript
+pool: it prints a list rather than executing, so the native engine's
+fast path buys nothing.
+
+`--failed` re-runs only what failed last time, from the cache each run
+writes to `node_modules/.cache/helix/summary.json` (same `{ tests }`
+shape as Japa). `--reporters=spec,json` activates several reporters at
+once. `--force-exit` (or `forceExit` in the config) calls
+`process.exit()` as soon as the run ends; without it the process exits
+on its own once the event loop drains, as in Japa — so a resource a test
+left open surfaces as a diagnosable hang instead of being swallowed.
+
+All of these work on BOTH orchestrators: the native (Rust) engine
+serializes the full per-test summary and implements bail and the
+reporter chain itself. Only coverage, diff coverage and a pluggable
+reporter instance keep a run on the TypeScript pool.
+
+## Bootstrap
+
+`tests/bootstrap.ts` is the AdonisJS bootstrap module, with the same three
+exports — an Adonis one ports over unchanged:
+
+```ts
+// tests/bootstrap.ts
+export const plugins = [apiClient({ baseUrl })]
+export const runnerHooks = {
+  setup: [(runner) => migrate()],   // may resolve to its own undo
+  teardown: [() => closePool()],
+}
+export const configureSuite = (suite) => {
+  if (["functional", "e2e"].includes(suite.name)) {
+    return suite.setup(() => httpServer.start())
+  }
+}
+```
+
+It is picked up automatically (`helix.config`'s `bootstrap` overrides the
+path) and imported by each worker before its test file, so a plugin's
+context macros exist by the time the first test declares itself.
+
+A `setup` hook receives the `runner` and may RESOLVE TO ITS OWN UNDO —
+the AdonisJS idiom (`setup: [() => testUtils.db().migrate()]`, where
+`migrate()` resolves to the rollback). Returned undos unwind first, then
+the declared teardowns, both in reverse order.
+
+`configureSuite` receives Japa's `Suite` surface: `name`, `setup`,
+`teardown`, `bail`, and the `onTest` / `onGroup` taps — each mapped onto
+the node the runtime actually reads, so `suite.onTest(t => t.timeout(30_000))`
+really does change the timeout. What a callback cannot get is what only
+the owner of execution has (`add`, `stack`, `exec`, `failed`): helix
+builds the tree from the file's own `describe`/`test` and runs it itself.
+
+Two more Japa `Config` fields live here too, since helix has no
+`bin/test.ts` to put them in: `filters` (`{ tests, groups, tags, matchAll }`
+— the CLI flags still win over them) and `importer`, the hook that replaces
+the plain dynamic import of a test file. Japa's `filters.files` /
+`filters.suites` stay CLI-side (`--files`, a suite positional): helix
+settles the file list before any worker — and so any bootstrap — exists,
+and filtering there still avoids the spawn.
+
+`runnerHooks` run ONCE for the whole run, in the process that spawns the
+workers — Japa's semantics. A migration in `setup` migrates once, not once
+per test file. Everything else in the bootstrap is per worker because it has
+to be: a context macro, a filter, an importer only mean anything in the
+process that loads the test file, which is why `plugins` are where an
+in-memory resource belongs.
+
+## Official Japa plugins
+
+`japaPlugins: true` in `helix.config` points `@japa/runner/core` at a helix
+shim in every worker, so a plugin written for Japa instruments helix:
+
+```ts
+// helix.config.ts
+export default { japaPlugins: true }
+
+// tests/bootstrap.ts
+import { assert } from "@japa/assert"
+export const plugins = [assert()]
+```
+
+This is what "not drop-in" meant for the whole of this package's life, and
+it was never an API-shape problem: a plugin does not talk to the runner
+through an interface, it imports `Test` / `TestContext` and mutates them.
+Nothing helix does at runtime can change what that import already resolved
+to — module resolution can.
+
+Off by default: redirecting a package specifier is not something to do
+behind a user's back, and a project with no Japa plugin gains nothing. The
+shim exports every name the real module does — a missing one is an
+ImportError before any test runs, not a degraded experience. `Emitter` is
+helix's own and `Refiner` collects for real; `BaseReporter`, `Group`,
+`Suite` and `Runner` exist so imports resolve and `instanceof` answers
+`false` (a helix group is not a Japa `Group`), and throw on construction
+with the reason. `Test.isHelixShim` answers "which module did this import
+resolve to?", a question that otherwise costs an afternoon.
+
+The alias goes into the PARENT too, not just the workers: the parent
+imports the bootstrap for `runnerHooks`, and two processes resolving that
+specifier differently is how a top-level registration lands on a class
+nothing reads. It is switched off again when the run ends —
+`node:module.register()` has no counterpart, so a host running twice in one
+process would otherwise keep resolving to the shim after asking for the
+real module. ESM only — under a CJS build the import is a `require`, which an ESM
+resolve hook never sees.
+
+A `Test.executed` hook is a VERDICT: what it throws fails the test, which is
+how `@japa/assert` enforces `assert.plan(n)`. And a plugin may replace
+`assert` — helix ships one, but a project installing `@japa/assert` is
+asking for that one. `cleanup` and `test` stay helix's: the runtime hands
+them to the body, and a test with someone else's `cleanup` is not a test.
+
+## Plugins
+
+A plugin is a function run once at `configure()` time, handed the same
+object Japa hands its plugins — plus two helix extras:
+
+```ts
+await configure({
+  plugins: [
+    ({ config, cliArgs, runner, emitter, context, cleanup }) => {
+      context.macro("greeting", "hello")       // extend the test context
+      emitter.on("test:end", (t) => { … })     // observe the run
+      cleanup(async () => server.close())      // close resources afterwards
+    },
+  ],
+})
+```
+
+- `config` — Japa's `BaseConfig`, filled in with what this run actually is:
+  `cwd`, `timeout`, `retries`, `filters`, `configureSuite`, `reporters`,
+  `plugins`, `importer`, `refiner`, `forceExit`, `setup`, `teardown`. What a
+  plugin can STEER is marked as such below; `filters.files` / `filters.suites`
+  and `reporters.activated` report what the CLI decided, because the file list
+  and the reporter chain are settled before a worker exists
+- `cliArgs` — every flag the CLI forwarded to this worker (Japa's set:
+  `tags`, `tests`, `groups`, `files`, `matchAll`, `timeout`, `retries`,
+  `reporters`, `bail`, `bailLayer`, `failed`, `forceExit`, `suite`)
+- `runner` — `getSummary()`, `failed`, `bail()`, `onSuite()`, `suites`,
+  and `registerReporter()`, which hands a Japa reporter this worker's
+  runner and emitter. It observes THIS FILE; run-wide output is the CLI's
+  (`--reporters`, `run({ reporterInstance })`). `add` / `start` / `exec` /
+  `end` throw a `RunnerNotDrivableError` explaining that the CLI owns
+  discovery and execution — a sentence rather than the missing-property
+  crash they would otherwise be
+- `emitter` — `runner:start` / `suite:*` / `group:*` / `test:*`, with
+  `errors[].error` the thrown `Error` itself
+- `context` — `macro` / `getter` (also on the `TestContext` class, as
+  in Japa)
+- `cleanup` — a teardown run once the file's tests finish
+
+`config` and `cliArgs` are handed over MUTABLE and read back once every
+plugin has run, so a plugin can raise `config.timeout`, push a `setup`
+hook, narrow `cliArgs.tags`, call `config.refiner.add("tags", […])` or
+replace `config.configureSuite` and have the run follow — Japa's contract.
+Plugins therefore run BEFORE both the run's `setup` hooks and
+`configureSuite`, as in Japa.
+
 In `package.json`, call the `helix` bin directly — in npm scripts it resolves to
 `node_modules/.bin/helix` and bootstraps the TS loader itself, so the verbose
 `node --import tsx node_modules/@c9up/helix/bin/helix.js …` form is unnecessary:
@@ -50,7 +280,47 @@ Both commands run independently in CI. Stage 2b will retire vitest
 once the helix self-test corpus reaches parity coverage with the
 vitest suite.
 
-### Parity proofs
+### Japa parity proofs (golden tests)
+
+`tests/golden/` runs helix against the **real `@japa/runner`**. Every
+spec under `specs/helix/` has a byte-identical twin under
+`specs/japa/` — only the runner import differs. Each pair is executed
+by its own runner; both harnesses write the same event
+journal (`runner:start`, `group:start`, `test:start`, `test:end`, …)
+and the journals must match event for event:
+
+| Spec | What it pins down |
+| --- | --- |
+| `lifecycle` | group `setup`/`teardown`/`each.*` order |
+| `outcomes` | pass / fail / `.skip()` / todo / tags, as reported |
+| `dataset` | `.with()` expansion and `{prop}` / `{$i}` titles |
+| `retries` | one start/end pair per test, 1-based `retryAttempt` |
+| `macros` | `test.macro(callback)` + `t.cleanup` |
+| `group_identity` | `test.group()` returns the instance its hooks get |
+| `filters` | `--tags` (OR), `--match-all`, `~@tag`, `--tests`, `--groups` |
+
+Each journal entry also carries the payload's RAW key set, so the
+comparison is not "the two runners agree on the fields we chose to look
+at" but "they hand a reporter the same object". That is what pinned
+`isTodo`/`retries` to always-present, `isSkipped`/`isFailing`/
+`skipReason` to only-when-set, and the bail skip reason to Japa's own
+wording.
+
+The filter matrix runs the same flags through both runners, including
+the rules that a group — or a whole suite — with no runnable test
+announces nothing.
+
+`tests/golden/assert-surface.test.ts` does the same for assertions: it
+asserts helix exposes every public assertion of the installed
+`@japa/assert`, then runs a battery of inputs through BOTH
+implementations and requires the same verdict (this is what pinned
+`sameMembers` to strict equality and `sameDeepMembers` to structural).
+
+Since helix runs one process per FILE, `suite:*` fires once per file
+rather than once for a multi-file suite. That is the only deviation the
+golden journals still carry.
+
+### Vitest parity proofs
 
 A handful of identical test bodies live in BOTH directories
 (`tests/selftest/parity-*.test.ts` and
@@ -64,10 +334,9 @@ currently cover:
 - assertion failure shapes (`AssertionError` thrown, message contains
   both received and expected values)
 
-What the parity proofs do **NOT** cover today:
+What the VITEST parity proofs do **NOT** cover today (the Japa golden
+tests above cover the runner semantics):
 
-- Lifecycle hook semantics across runners (`beforeEach`/`afterEach`
-  behaviour is exercised in `tests/selftest/lifecycle.test.ts` only).
 - Spy / fake-timer parity (`vi.fn`, `vi.spyOn`, `vi.useFakeTimers`).
 - Failure-pipeline parity (i.e. that both runners REPORT a failed
   test the same way, at the runner level). The current parity-fail

package/bin/helix.js

@@ -43,7 +43,57 @@ const FLAG_SPEC = {
 		help: "Only run tests whose full name matches (regex or substring)",
 	},
 	retries: { kind: "number", help: "Extra attempts on failure (default 0)" },
-	tags: { kind: "string", help: "Comma-separated tag filter (@fast, !@slow)" },
+	tags: {
+		kind: "string",
+		help: "Comma-separated tag filter (@fast, ~@slow to exclude); OR by default",
+	},
+	"match-all": {
+		kind: "boolean",
+		help: "Require ALL --tags instead of any (Japa parity)",
+	},
+	// Japa's parser accepts both spellings (`matchAll` with `match-all` as its
+	// alias), so both work here too.
+	matchAll: {
+		kind: "boolean",
+		help: "Alias of --match-all",
+	},
+	tests: {
+		kind: "string",
+		help: "Comma-separated exact test titles to run (Japa --tests)",
+	},
+	groups: {
+		kind: "string",
+		help: "Comma-separated exact group titles to run (Japa --groups)",
+	},
+	suite: {
+		kind: "string",
+		help: "Name of the suite these files belong to (Japa meta.suite)",
+	},
+	files: {
+		kind: "string",
+		help: "Comma-separated substrings matched against test file paths (Japa --files)",
+	},
+	reporters: {
+		kind: "string",
+		help: "Comma-separated reporters to activate, e.g. spec,json (Japa --reporters)",
+	},
+	bail: { kind: "boolean", help: "Stop at the first failure (Japa --bail)" },
+	"bail-layer": {
+		kind: "string",
+		help: "How far a bail reaches: group|suite|runner (Japa --bail-layer)",
+	},
+	failed: {
+		kind: "boolean",
+		help: "Re-run only the tests that failed last run (Japa --failed)",
+	},
+	"list-pinned": {
+		kind: "boolean",
+		help: "Print the tests marked .pin() and run nothing (Japa --list-pinned)",
+	},
+	"force-exit": {
+		kind: "boolean",
+		help: "process.exit() as soon as the run ends, without draining the event loop (Japa --force-exit)",
+	},
 	watch: { kind: "boolean", help: "Watch mode — re-run on file changes" },
 	"watch-debounce": {
 		kind: "number",
@@ -193,12 +243,50 @@ function findTsxLoader() {
 	return undefined;
 }
 
+/** Trailing `.test.ts` / `.spec.js` / … stripped, so `--files=user` matches `user.test.ts`. */
+const TEST_SUFFIX = /(\.(test|spec))?\.[cm]?[jt]sx?$/;
+
+/**
+ * Japa's `--files` rule: keep a file when its path ENDS WITH the filter, or
+ * when every segment of the filter (read right-to-left, `*` matching anything)
+ * matches the corresponding path segment of the file minus its test suffix.
+ * `--files=user` keeps `tests/unit/user.test.ts`; `--files=unit/*` keeps
+ * everything under a `unit` directory.
+ */
+function filterByFileFilters(files, raw) {
+	if (raw === undefined) return files;
+	const filters = String(raw)
+		.split(",")
+		.map((f) => f.trim())
+		.filter((f) => f.length > 0);
+	if (filters.length === 0) return files;
+	return files.filter((file) => {
+		const unix = file.split(path.sep).join("/");
+		const withoutSuffix = unix.replace(TEST_SUFFIX, "");
+		return filters.some((filter) => {
+			if (unix.endsWith(filter)) return true;
+			const filterSegments = filter.split("/").reverse();
+			const fileSegments = withoutSuffix.split("/").reverse();
+			return filterSegments.every(
+				(segment, i) =>
+					fileSegments[i] !== undefined &&
+					(segment === "*" || fileSegments[i].endsWith(segment)),
+			);
+		});
+	});
+}
+
 function printHelp() {
 	const lines = [
 		"helix — Vitest-compatible test runner",
 		"",
 		"Usage:",
-		"  helix test [files...|dirs...]",
+		"  helix test [files...|dirs...|suites...]",
+		"",
+		"  Positionals name test files or directories. When every one of them",
+		"  matches a suite declared in helix.config.*, they name SUITES instead",
+		"  (AdonisJS `node ace test unit functional`). With no positional and a",
+		"  config present, every suite runs, in order.",
 		"",
 		"Flags:",
 	];
@@ -295,15 +383,66 @@ async function main() {
 	).href;
 	try {
 		// Probe by resolving through dynamic import; Node throws synchronously.
-		const { run } = await import(runModule);
+		const { run, runSuites } = await import(runModule);
 		const discoverModule = pathToFileURL(
 			useDist
 				? path.resolve(here, "../dist/cli/discover.js")
 				: path.resolve(here, "../src/cli/discover.ts"),
 		).href;
 		const { discover } = await import(discoverModule);
+		const suitesModule = pathToFileURL(
+			useDist
+				? path.resolve(here, "../dist/cli/suites.js")
+				: path.resolve(here, "../src/cli/suites.ts"),
+		).href;
+		const {
+			loadHelixConfig,
+			resolveHelixConfig,
+			resolveSuiteFiles,
+			selectSuites,
+		} = await import(suitesModule);
 
-		const expanded = await expandPositionals(parsed.positional, discover);
+		// AdonisJS parity: positionals may name SUITES declared in
+		// `helix.config.*` (`helix test unit`). When they don't — or there is no
+		// config — they stay what they have always been: paths.
+		const helixConfig = await loadHelixConfig(process.cwd());
+		const selectedSuites = selectSuites(helixConfig, parsed.positional);
+
+		// AdonisJS `tests/bootstrap.ts`: resolved once here, imported by every
+		// worker before its test file. Forwarded through the env so it reaches
+		// the worker under BOTH orchestrators.
+		const bootstrapModule = pathToFileURL(
+			useDist
+				? path.resolve(here, "../dist/runtime/bootstrap.js")
+				: path.resolve(here, "../src/runtime/bootstrap.ts"),
+		).href;
+		const { resolveBootstrap } = await import(bootstrapModule);
+		const { runGlobalHooks } = await import(
+			pathToFileURL(
+				useDist
+					? path.resolve(here, "../dist/runtime/global-hooks.js")
+					: path.resolve(here, "../src/runtime/global-hooks.ts"),
+			).href
+		);
+		process.env.HELIX_BOOTSTRAP =
+			resolveBootstrap(process.cwd(), helixConfig.bootstrap) ?? "";
+		// A `suites[].configure` callback lives in the config module; the worker
+		// re-imports it by path, since the function itself cannot be forwarded.
+		// Only named when a suite actually declares one, so a project without any
+		// pays nothing.
+		const declaresConfigure = (helixConfig.suites ?? []).some(
+			(suite) => typeof suite.configure === "function",
+		);
+		process.env.HELIX_SUITE_CONFIG = declaresConfigure
+			? (resolveHelixConfig(process.cwd()) ?? "")
+			: "";
+
+		const expanded = selectedSuites
+			? []
+			: filterByFileFilters(
+					await expandPositionals(parsed.positional, discover),
+					parsed.flags.files,
+				);
 		const tsxLoader = findTsxLoader();
 		if (parsed.flags.tsx !== false && !tsxLoader) {
 			process.stderr.write(
@@ -345,17 +484,41 @@ async function main() {
 			root: process.cwd(),
 			files: expanded,
 			threads: parsed.flags.threads,
-			timeoutMs: parsed.flags.timeout,
+			timeoutMs: parsed.flags.timeout ?? helixConfig.timeout,
 			reporter: parsed.flags.reporter,
+			reporters: parsed.flags.reporters
+				? String(parsed.flags.reporters)
+						.split(",")
+						.map((r) => r.trim())
+						.filter((r) => r.length > 0)
+				: undefined,
+			bail: parsed.flags.bail === true,
+			listPinned: parsed.flags["list-pinned"] === true,
+			failed: parsed.flags.failed === true,
 			useColors: parsed.flags.colors,
 			discovery: {
 				suffixes: parsed.flags.include,
 				hardExcludes: parsed.flags.exclude,
 			},
-			nodeArgs:
-				parsed.flags.tsx === false || !tsxLoader
-					? undefined
-					: ["--import", tsxLoader],
+			// `japaPlugins` points `@japa/runner/core` at helix's shim in every
+			// worker, so an official Japa plugin instruments helix. Appended to
+			// the loader list rather than replacing it: the test files still need
+			// their TS loader.
+			nodeArgs: [
+				...(parsed.flags.tsx === false || !tsxLoader
+					? []
+					: ["--import", tsxLoader]),
+				...(helixConfig.japaPlugins === true
+					? [
+							"--import",
+							pathToFileURL(
+								useDist
+									? path.resolve(here, "../dist/japa/japa-alias.mjs")
+									: path.resolve(here, "../src/japa/japa-alias.mjs"),
+							).href,
+						]
+					: []),
+			],
 			coverage: parsed.flags.coverage
 				? {
 						enabled: true,
@@ -387,11 +550,131 @@ async function main() {
 		if (parsed.flags.retries !== undefined) {
 			process.env.HELIX_RETRIES = String(parsed.flags.retries);
 		}
+		// Not used to resolve the timeout (the orchestrator carries it in the
+		// run instruction) — exported so a plugin can read it off `api.cliArgs`.
+		if (parsed.flags.timeout !== undefined) {
+			process.env.HELIX_TIMEOUT = String(parsed.flags.timeout);
+		}
 		if (parsed.flags.tags !== undefined) {
 			process.env.HELIX_TAGS = String(parsed.flags.tags);
 		}
-		const outcome = await run(cfg);
-		return outcome.exitCode;
+		if (parsed.flags["match-all"] === true || parsed.flags.matchAll === true) {
+			process.env.HELIX_MATCH_ALL = "1";
+		}
+		if (parsed.flags.tests !== undefined) {
+			process.env.HELIX_TESTS = String(parsed.flags.tests);
+		}
+		if (parsed.flags.groups !== undefined) {
+			process.env.HELIX_GROUPS = String(parsed.flags.groups);
+		}
+		if (parsed.flags.suite !== undefined) {
+			process.env.HELIX_SUITE = String(parsed.flags.suite);
+		}
+		if (parsed.flags.files !== undefined) {
+			process.env.HELIX_FILES = String(parsed.flags.files);
+		}
+		if (parsed.flags.bail === true) {
+			process.env.HELIX_BAIL = "1";
+		}
+		// Flags a plugin reads off `api.cliArgs` but the runtime itself doesn't
+		// act on — forwarded for the same reason as the filters: Japa hands its
+		// plugins the whole flag set.
+		if (cfg.reporters !== undefined) {
+			process.env.HELIX_REPORTERS = cfg.reporters.join(",");
+		} else if (parsed.flags.reporter !== undefined) {
+			process.env.HELIX_REPORTERS = String(parsed.flags.reporter);
+		}
+		if (parsed.flags.failed === true) {
+			process.env.HELIX_FAILED = "1";
+		}
+		// `--force-exit`, or `forceExit` in the config (AdonisJS `tests.forceExit`).
+		// Read back by `finish()` below, and by a plugin off `api.cliArgs`.
+		if (parsed.flags["list-pinned"] === true) {
+			process.env.HELIX_LIST_PINNED = "1";
+		}
+		// Positionals reach a plugin as `api.cliArgs._`, like Japa's.
+		if (parsed.positional.length > 0) {
+			process.env.HELIX_POSITIONALS = parsed.positional.join(",");
+		}
+		if (parsed.flags["force-exit"] === true || helixConfig.forceExit === true) {
+			process.env.HELIX_FORCE_EXIT = "1";
+		}
+		if (parsed.flags["bail-layer"] !== undefined) {
+			process.env.HELIX_BAIL_LAYER = String(parsed.flags["bail-layer"]);
+		}
+		// `--failed` replays the previous run's failures as a `--tests` filter,
+		// exactly like Japa's retry plugin.
+		if (parsed.flags.failed === true) {
+			const failedModule = pathToFileURL(
+				useDist
+					? path.resolve(here, "../dist/cli/failed-cache.js")
+					: path.resolve(here, "../src/cli/failed-cache.ts"),
+			).href;
+			const { readFailedCache } = await import(failedModule);
+			const failedTests = await readFailedCache(process.cwd());
+			if (failedTests.length === 0) {
+				process.stdout.write(
+					"helix: no failing tests cached — running all of them\n",
+				);
+			} else {
+				process.env.HELIX_TESTS = failedTests.join(",");
+			}
+		}
+
+		// `runnerHooks` run ONCE around the whole run, here, and the workers are
+		// told to skip them — Japa's semantics, and the difference between
+		// migrating once and migrating once per test file.
+		const dropGlobalHooks = await runGlobalHooks(process.env.HELIX_BOOTSTRAP, {
+			japaPlugins: helixConfig.japaPlugins === true,
+		});
+
+		if (!selectedSuites) {
+			try {
+				const outcome = await run(cfg);
+				return outcome.exitCode;
+			} finally {
+				await dropGlobalHooks();
+			}
+		}
+
+		// Suites run one after another (Japa runs them in sequence too), each
+		// with its own files, timeout, retries and `meta.suite` name. The
+		// sequence is handed to the orchestrator as a whole so watch mode
+		// wraps ALL of it in one watcher and the `--failed` cache holds every
+		// suite's failures.
+		const steps = [];
+		for (const suite of selectedSuites) {
+			const suiteFiles = filterByFileFilters(
+				await resolveSuiteFiles(suite, process.cwd(), cfg.discovery),
+				parsed.flags.files,
+			);
+			if (suiteFiles.length === 0) {
+				process.stderr.write(`helix: suite "${suite.name}": no test files\n`);
+				continue;
+			}
+			// A suite's `retries` overrides `--retries` for that suite only. Set
+			// on EVERY step (empty = unset, see `envCount`) so a suite that
+			// declares none doesn't inherit the previous suite's value.
+			const retries = suite.retries ?? parsed.flags.retries;
+			const env = {
+				HELIX_SUITE: suite.name,
+				HELIX_RETRIES: retries === undefined ? "" : String(retries),
+			};
+			steps.push({
+				env,
+				config: {
+					...cfg,
+					files: suiteFiles,
+					timeoutMs: cfg.timeoutMs ?? suite.timeout,
+				},
+			});
+		}
+		try {
+			const outcome = await runSuites(steps, cfg);
+			return outcome.exitCode;
+		} finally {
+			await dropGlobalHooks();
+		}
 	} catch (err) {
 		// Re-exec under tsx when Node can't satisfy the TS-source imports
 		// natively. Two failure shapes seen in the wild:
@@ -441,9 +724,25 @@ async function main() {
 	}
 }
 
+/**
+ * Japa semantics: the process exits on its own once the event loop drains, so a
+ * resource a test left open surfaces as a hang you can diagnose — rather than
+ * being swallowed by an unconditional `process.exit`, which also truncates
+ * pending stdout writes. `--force-exit` is the escape hatch, exactly as in Japa.
+ */
+function finish(code) {
+	process.exitCode = code;
+	// The env var carries the config-declared `forceExit`; the argv check also
+	// covers a failure that happened before the config was ever read.
+	const forced =
+		process.env.HELIX_FORCE_EXIT === "1" ||
+		process.argv.includes("--force-exit");
+	if (forced) process.exit(code);
+}
+
 main()
-	.then((code) => process.exit(code))
+	.then(finish)
 	.catch((err) => {
 		process.stderr.write(`helix: ${err instanceof Error ? err.stack : err}\n`);
-		process.exit(2);
+		finish(2);
 	});