@theholocron/cli 4.10.3 → 4.12.0

package/README.md

@@ -133,6 +133,29 @@ Writes `"holocron": "<holocronScript ?? 'holocron'>"` plus one
 `"<task>": "holocron run <task>"` per runnable task. `syncScripts: false`
 opts out entirely.
 
+### `holocron run`
+
+```bash
+holocron run <task> [job] [--required] [--filter <pkg>] [--dry-run] [-- <passthrough>]
+```
+
+Runs one task locally — resolving turbo vs the package manager vs the tool
+itself. A `job` argument targets a sub-job of tasks that have them: `holocron
+run audit performance` runs Lighthouse CI, `holocron run audit knip` runs Knip,
+`holocron run audit` (no job) runs every audit sub-job in declared order. A
+sub-job whose tool isn't installed, or that has no local equivalent
+(`bundle-size`), is skipped with a note — `--required` makes that a failure. For
+a task with no sub-jobs the `job` slot is the first passthrough arg
+(`holocron run build src/`).
+
+**CI runs the identical command.** The reusable `typecheck` / `test` / `audit`
+workflows call the `holocron` composite action
+(`theholocron/.github/.github/actions/holocron@main`), whose body is
+`holocron run <task> [job]`. So `holocron run test` locally and the `Test` CI
+job execute the same thing — at a turbo root both are
+`turbo run test -- --coverage` (the registry's org-default flags flow through
+turbo's `--`).
+
 ### `holocron ci`
 
 ```bash
@@ -146,7 +169,9 @@ first failure — the "will my PR be green?" pre-flight, and what the
 `--all` forces the full set; `--filter` is a `turbo --filter=` passthrough.
 Order comes from the `CI_ORDER` constant in `@theholocron/astromech`
 (`typecheck → lint → test → build → …`). Tasks with no local equivalent
-(`audit`, `codeql`, `deploy`) are reported as enforced-in-CI, never failures.
+(`codeql`, `deploy`) are reported as enforced-in-CI, never failures; `audit`
+expands into its sub-jobs (each under its own `audit / …` check context)
+unless the repo ships its own `"audit"` script.
 
 ### Lint parity
 

package/dist/cli.mjs

@@ -6935,10 +6935,13 @@ try {
 			},
 			...argv.steps && argv.steps.length > 0 ? { steps: argv.steps } : {}
 		})).summary.fail > 0) process.exitCode = 1;
-	}).command("run <task> [passthrough..]", "Run a task locally (test, typecheck, lint, build) — figures out turbo / the tool / the package manager", (y) => y.positional("task", {
+	}).command("run <task> [job] [passthrough..]", "Run a task locally (test, typecheck, lint, build, audit) — figures out turbo / the tool / the package manager", (y) => y.positional("task", {
 		type: "string",
 		demandOption: true,
-		describe: "Task name (test, typecheck, lint, build). See `holocron run --help`."
+		describe: "Task name (test, typecheck, lint, build, audit). See `holocron run --help`."
+	}).positional("job", {
+		type: "string",
+		describe: "Sub-job within the task (e.g. `holocron run audit performance`). Omit to run every job. Only `audit` has jobs today."
 	}).positional("passthrough", {
 		type: "string",
 		array: true,
@@ -6958,6 +6961,7 @@ try {
 			logger,
 			config
 		}).run(argv.task, {
+			...argv.job !== void 0 ? { job: argv.job } : {},
 			passthrough: argv.passthrough ?? [],
 			dryRun: argv.dryRun,
 			required: argv.required,
@@ -7376,8 +7380,8 @@ try {
 		let extra = [];
 		try {
 			const raw = readFileSync(join(argv.cwd, "holocron.config.json"), "utf8");
-			const upgradeNode = JSON.parse(raw).upgrade?.node;
-			if (Array.isArray(upgradeNode?.extra)) extra = upgradeNode.extra;
+			const extraRaw = JSON.parse(raw).upgrade?.node?.extra;
+			if (Array.isArray(extraRaw)) extra = extraRaw;
 		} catch {}
 		const report = await runUpgradeNode({
 			to: argv.to,