@kici-dev/compiler 0.1.15 → 0.1.16

package/dist/cli.d.ts

@@ -1,3 +1,11 @@
 #!/usr/bin/env node
-export {};
+import { Command } from 'commander';
+/**
+ * Build the kici Commander program with every command registered. Exported so
+ * the surface registry can walk the real command tree without parsing argv (no
+ * action runs during a tree walk).
+ */
+export declare function buildProgram(): Command;
+/** Build the program and parse argv — the bin-shim entry point. */
+export declare function runCli(argv?: string[]): void;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -1,100 +1,108 @@
 #!/usr/bin/env node
 import "./chunk-gOLHoazu.js";
 import { shouldSuppressBanner } from "./cli-banner.js";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
 import { Argument, Command, Option } from "commander";
 import pc from "picocolors";
 //#region src/cli.ts
-const version = "0.1.15";
-const program = new Command();
-program.name("kici").description("KiCI workflow compiler").version(version);
-program.hook("preAction", (_thisCommand, actionCommand) => {
-	if (shouldSuppressBanner(actionCommand)) return;
-	console.log(pc.gray(`kici v${version}`));
-});
-program.configureOutput({ outputError: (str, write) => {
-	write(pc.red(str));
-} });
-program.command("compile").description("Compile workflows from .kici/workflows/ to kici.lock.json").option("--check", "Validate workflows without writing lock file", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--verbose", "Detailed output", false).option("--watch", "Watch for changes and recompile", false).action(async (options) => {
-	const { compileCommand, watchCommand } = await import("./commands/index.js");
-	if (options.watch) await watchCommand({
-		kiciDir: options.kiciDir,
-		verbose: options.verbose
-	});
-	else {
-		const success = await compileCommand({
+const version = "0.1.16";
+/**
+* Build the kici Commander program with every command registered. Exported so
+* the surface registry can walk the real command tree without parsing argv (no
+* action runs during a tree walk).
+*/
+function buildProgram() {
+	const program = new Command();
+	program.name("kici").description("KiCI workflow compiler").version(version);
+	program.hook("preAction", (_thisCommand, actionCommand) => {
+		if (shouldSuppressBanner(actionCommand)) return;
+		console.log(pc.gray(`kici v${version}`));
+	});
+	program.configureOutput({ outputError: (str, write) => {
+		write(pc.red(str));
+	} });
+	program.command("compile").description("Compile workflows from .kici/workflows/ to kici.lock.json").option("--check", "Validate workflows without writing lock file", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--verbose", "Detailed output", false).option("--watch", "Watch for changes and recompile", false).action(async (options) => {
+		const { compileCommand, watchCommand } = await import("./commands/index.js");
+		if (options.watch) await watchCommand({
 			kiciDir: options.kiciDir,
-			check: options.check,
 			verbose: options.verbose
 		});
+		else {
+			const success = await compileCommand({
+				kiciDir: options.kiciDir,
+				check: options.check,
+				verbose: options.verbose
+			});
+			process.exit(success ? 0 : 1);
+		}
+	});
+	const fixtureEventArg = new Argument("<event>", "Event to generate fixture for (e.g., pr:open, push, schedule, lifecycle:workflow_complete)");
+	program.command("fixture").addArgument(fixtureEventArg).description("Generate fixture template for event type").option("--output <path>", "Write to file instead of stdout").action(async (event, options) => {
+		const { fixtureCommand } = await import("./commands/index.js");
+		await fixtureCommand(event, options);
+	});
+	const runCommand = program.command("run").description("Execute workflows locally or remotely");
+	runCommand.command("local").argument("[event]", "Event type (e.g., push, pr:open, schedule) — optional with --pick").description("Execute workflows locally without orchestrator infrastructure").option("-p, --pick", "Interactively pick a workflow and trigger to simulate", false).option("--workflow <name>", "Run only the specified workflow").option("--job <name>", "Run only the specified job (and its dependencies)").option("--branch <name>", "Override detected git branch").option("--sha <hash>", "Override detected git SHA").option("--payload <path>", "Path to explicit event payload JSON file").option("--concurrency <n>", "Max parallel jobs (default: CPU cores)", parseInt).option("--keep-going", "Continue after job failure", false).option("--container", "Use Podman container isolation", false).option("--env <KEY=VALUE>", "Environment variable override (repeatable)", (val, prev) => [...prev, val], []).option("--quiet", "Suppress streaming output", false).option("--json", "Output structured JSON result", false).option("--junit <path>", "Output JUnit XML result").option("--files <path>", "Override changed file paths (repeatable, default: git diff)", (val, prev) => [...prev, val], []).option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--in-place", "Run against the real working directory instead of an isolated tmp checkout", false).option("--keep", "Always retain the isolated tmp checkout (default: keep only on failure)", false).action(async (event, options) => {
+		if (options.pick && options.workflow) {
+			console.error("Error: --pick is mutually exclusive with --workflow.");
+			process.exit(2);
+		}
+		if (!options.pick && !event) {
+			console.error("Error: missing event argument. Pass an event or use --pick.");
+			process.exit(2);
+		}
+		const { runLocalCommand } = await import("./commands/index.js");
+		const success = await runLocalCommand({
+			event,
+			pick: options.pick,
+			workflow: options.workflow,
+			job: options.job,
+			branch: options.branch,
+			sha: options.sha,
+			payload: options.payload,
+			concurrency: options.concurrency,
+			keepGoing: options.keepGoing,
+			container: options.container,
+			env: options.env,
+			quiet: options.quiet,
+			json: options.json,
+			junit: options.junit,
+			files: options.files,
+			debug: options.debug,
+			kiciDir: options.kiciDir,
+			inPlace: options.inPlace,
+			keep: options.keep
+		});
+		process.exit(success ? 0 : 1);
+	});
+	runCommand.command("remote").argument("[fixture]", "Fixture name or glob pattern (omit to list available)").description("Execute fixtures remotely via orchestrator").option("--workflow <name>", "Run a specific workflow directly (bypass triggers)").option("--all", "Run all available fixtures", false).option("--parallel", "Run matching fixtures concurrently", false).option("--no-wait", "Fire and forget (print runIds, don't stream)").option("--quiet", "Suppress output except final result", false).option("--json", "Output structured JSON result", false).option("--junit <path>", "Output JUnit XML result").option("--history", "Show recent run history", false).option("--routing-key <key>", "Override routing key for this run").option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--context <ctx.key=value>", "Inject a namespaced context secret, uploaded encrypted to the orchestrator (repeatable)", (val, prev) => [...prev, val], []).option("--env <KEY=VALUE>", "Provide a per-run secret (repeatable); uploaded encrypted to the orchestrator", (val, prev) => [...prev, val], []).action(async (fixture, options) => {
+		const { runRemoteCommand } = await import("./commands/index.js");
+		const success = await runRemoteCommand(fixture, {
+			...options,
+			envFlags: options.env
+		});
+		process.exit(success ? 0 : 1);
+	});
+	program.command("test").argument("[event]", "Event type to preview (e.g., push, pr:open, schedule)").description("Preview which workflows match a trigger event (dry-run)").option("--branch <name>", "Override target branch for trigger matching (default: main)").option("--sha <hash>", "Override commit SHA").option("--workflow <name>", "Filter to specific workflow in display").option("--job <name>", "Filter to specific job in display").option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--files <path>", "Simulate changed file path for trigger matching (repeatable)", (val, prev) => [...prev, val], []).option("--secret <key=value>", "Inject flat secret (repeatable)", (val, prev) => [...prev, val], []).option("--context <ctx.key=value>", "Inject context secret (repeatable)", (val, prev) => [...prev, val], []).action(async (event, options) => {
+		const { testCommand } = await import("./commands/index.js");
+		const success = await testCommand(event, options);
+		process.exit(success ? 0 : 1);
+	});
+	program.command("init").description("Initialize .kici/ directory with default workflows").option("--force", "Overwrite existing .kici/ directory", false).option("--skip-install", "Create files without installing dependencies", false).option("--package-manager <npm|pnpm|yarn>", "Force a package manager for the install step (default: auto-detect)").option("--mjs", "JavaScript-only mode (no TypeScript, no dependencies)", false).option("--no-agents-md", "Skip writing .kici/AGENTS.md (LLM authoring context)").option("--private-registry <url>", "Scaffold a workflow registries: entry pointing at <url>").option("--private-registry-scope <scope>", "Optional npm package scope (e.g. @my-org) for the private registry").option("--private-registry-secret <ref>", "Qualified secret reference (env:NAME) the private registry token comes from", "production:NPM_TOKEN").addOption(new Option("--use-verdaccio-local").default(false).hideHelp()).action(async (options) => {
+		const { initCommand } = await import("./commands/index.js");
+		const success = await initCommand({
+			...options,
+			noAgentsMd: options.agentsMd === false
+		});
+		process.exit(success ? 0 : 1);
+	});
+	program.command("hook").description("Manage pre-commit hooks").command("install").description("Install kici compile pre-commit hook").option("--git", "Use raw git hook (.git/hooks/pre-commit)", false).action(async (options) => {
+		const { hookInstallCommand } = await import("./commands/index.js");
+		const success = await hookInstallCommand({ git: options.git });
 		process.exit(success ? 0 : 1);
-	}
-});
-const fixtureEventArg = new Argument("<event>", "Event to generate fixture for (e.g., pr:open, push, schedule, lifecycle:workflow_complete)");
-program.command("fixture").addArgument(fixtureEventArg).description("Generate fixture template for event type").option("--output <path>", "Write to file instead of stdout").action(async (event, options) => {
-	const { fixtureCommand } = await import("./commands/index.js");
-	await fixtureCommand(event, options);
-});
-const runCommand = program.command("run").description("Execute workflows locally or remotely");
-runCommand.command("local").argument("[event]", "Event type (e.g., push, pr:open, schedule) — optional with --pick").description("Execute workflows locally without orchestrator infrastructure").option("-p, --pick", "Interactively pick a workflow and trigger to simulate", false).option("--workflow <name>", "Run only the specified workflow").option("--job <name>", "Run only the specified job (and its dependencies)").option("--branch <name>", "Override detected git branch").option("--sha <hash>", "Override detected git SHA").option("--payload <path>", "Path to explicit event payload JSON file").option("--concurrency <n>", "Max parallel jobs (default: CPU cores)", parseInt).option("--keep-going", "Continue after job failure", false).option("--container", "Use Podman container isolation", false).option("--env <KEY=VALUE>", "Environment variable override (repeatable)", (val, prev) => [...prev, val], []).option("--quiet", "Suppress streaming output", false).option("--json", "Output structured JSON result", false).option("--junit <path>", "Output JUnit XML result").option("--files <path>", "Override changed file paths (repeatable, default: git diff)", (val, prev) => [...prev, val], []).option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--in-place", "Run against the real working directory instead of an isolated tmp checkout", false).option("--keep", "Always retain the isolated tmp checkout (default: keep only on failure)", false).action(async (event, options) => {
-	if (options.pick && options.workflow) {
-		console.error("Error: --pick is mutually exclusive with --workflow.");
-		process.exit(2);
-	}
-	if (!options.pick && !event) {
-		console.error("Error: missing event argument. Pass an event or use --pick.");
-		process.exit(2);
-	}
-	const { runLocalCommand } = await import("./commands/index.js");
-	const success = await runLocalCommand({
-		event,
-		pick: options.pick,
-		workflow: options.workflow,
-		job: options.job,
-		branch: options.branch,
-		sha: options.sha,
-		payload: options.payload,
-		concurrency: options.concurrency,
-		keepGoing: options.keepGoing,
-		container: options.container,
-		env: options.env,
-		quiet: options.quiet,
-		json: options.json,
-		junit: options.junit,
-		files: options.files,
-		debug: options.debug,
-		kiciDir: options.kiciDir,
-		inPlace: options.inPlace,
-		keep: options.keep
-	});
-	process.exit(success ? 0 : 1);
-});
-runCommand.command("remote").argument("[fixture]", "Fixture name or glob pattern (omit to list available)").description("Execute fixtures remotely via orchestrator").option("--workflow <name>", "Run a specific workflow directly (bypass triggers)").option("--all", "Run all available fixtures", false).option("--parallel", "Run matching fixtures concurrently", false).option("--no-wait", "Fire and forget (print runIds, don't stream)").option("--quiet", "Suppress output except final result", false).option("--json", "Output structured JSON result", false).option("--junit <path>", "Output JUnit XML result").option("--history", "Show recent run history", false).option("--routing-key <key>", "Override routing key for this run").option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--context <ctx.key=value>", "Inject a namespaced context secret, uploaded encrypted to the orchestrator (repeatable)", (val, prev) => [...prev, val], []).option("--env <KEY=VALUE>", "Provide a per-run secret (repeatable); uploaded encrypted to the orchestrator", (val, prev) => [...prev, val], []).action(async (fixture, options) => {
-	const { runRemoteCommand } = await import("./commands/index.js");
-	const success = await runRemoteCommand(fixture, {
-		...options,
-		envFlags: options.env
-	});
-	process.exit(success ? 0 : 1);
-});
-program.command("test").argument("[event]", "Event type to preview (e.g., push, pr:open, schedule)").description("Preview which workflows match a trigger event (dry-run)").option("--branch <name>", "Override target branch for trigger matching (default: main)").option("--sha <hash>", "Override commit SHA").option("--workflow <name>", "Filter to specific workflow in display").option("--job <name>", "Filter to specific job in display").option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--files <path>", "Simulate changed file path for trigger matching (repeatable)", (val, prev) => [...prev, val], []).option("--secret <key=value>", "Inject flat secret (repeatable)", (val, prev) => [...prev, val], []).option("--context <ctx.key=value>", "Inject context secret (repeatable)", (val, prev) => [...prev, val], []).action(async (event, options) => {
-	const { testCommand } = await import("./commands/index.js");
-	const success = await testCommand(event, options);
-	process.exit(success ? 0 : 1);
-});
-program.command("init").description("Initialize .kici/ directory with default workflows").option("--force", "Overwrite existing .kici/ directory", false).option("--skip-install", "Create files without installing dependencies", false).option("--package-manager <npm|pnpm|yarn>", "Force a package manager for the install step (default: auto-detect)").option("--mjs", "JavaScript-only mode (no TypeScript, no dependencies)", false).option("--no-agents-md", "Skip writing .kici/AGENTS.md (LLM authoring context)").option("--private-registry <url>", "Scaffold a workflow registries: entry pointing at <url>").option("--private-registry-scope <scope>", "Optional npm package scope (e.g. @my-org) for the private registry").option("--private-registry-secret <ref>", "Qualified secret reference (env:NAME) the private registry token comes from", "production:NPM_TOKEN").addOption(new Option("--use-verdaccio-local").default(false).hideHelp()).action(async (options) => {
-	const { initCommand } = await import("./commands/index.js");
-	const success = await initCommand({
-		...options,
-		noAgentsMd: options.agentsMd === false
-	});
-	process.exit(success ? 0 : 1);
-});
-program.command("hook").description("Manage pre-commit hooks").command("install").description("Install kici compile pre-commit hook").option("--git", "Use raw git hook (.git/hooks/pre-commit)", false).action(async (options) => {
-	const { hookInstallCommand } = await import("./commands/index.js");
-	const success = await hookInstallCommand({ git: options.git });
-	process.exit(success ? 0 : 1);
-});
-program.command("login").description("Authenticate with KiCI via browser OAuth (default) or API key (--token)").option("--token <key>", "API key for direct authentication (legacy)").option("--device", "Force device authorization flow (for headless/SSH environments)").option("--endpoint <url>", "Orchestrator URL for direct connection").option("--platform-endpoint <url>", "Platform relay URL").option("--routing-key <key>", "Routing key for webhook source identification").addHelpText("after", `
+	});
+	program.command("login").description("Authenticate with KiCI via browser OAuth (default) or API key (--token)").option("--token <key>", "API key for direct authentication (legacy)").option("--device", "Force device authorization flow (for headless/SSH environments)").option("--endpoint <url>", "Orchestrator URL for direct connection").option("--platform-endpoint <url>", "Platform relay URL").option("--routing-key <key>", "Routing key for webhook source identification").addHelpText("after", `
 Environment variables:
   KICI_BROWSER_CMD     Custom browser command (use {url} placeholder, or 'none' to suppress)
   KICI_CALLBACK_PORT   Fixed port for OAuth PKCE callback server (default: random)
@@ -102,101 +110,124 @@ Environment variables:
   KICI_OIDC_ISSUER     Override OIDC issuer URL
   KICI_OIDC_CLIENT_ID  Override OIDC client ID
 `).action(async (options) => {
-	const { loginCommand } = await import("./commands/index.js");
-	const success = await loginCommand({
-		token: options.token,
-		device: options.device,
-		endpoint: options.endpoint,
-		platformEndpoint: options.platformEndpoint,
-		routingKey: options.routingKey
-	});
-	process.exit(success ? 0 : 1);
-});
-program.command("logout").description("Revoke PAT and clear local credentials").action(async () => {
-	const { logoutCommand } = await import("./commands/index.js");
-	const success = await logoutCommand();
-	process.exit(success ? 0 : 1);
-});
-const orgCommand = program.command("org").description("Manage organizations");
-orgCommand.command("list").description("List organizations you belong to").action(async () => {
-	const { orgListCommand } = await import("./commands/index.js");
-	const success = await orgListCommand();
-	process.exit(success ? 0 : 1);
-});
-orgCommand.command("use").argument("<name>", "Organization name or ID").description("Switch active organization").action(async (name) => {
-	const { orgUseCommand } = await import("./commands/index.js");
-	const success = await orgUseCommand(name);
-	process.exit(success ? 0 : 1);
-});
-orgCommand.command("current").description("Show current active organization").action(async () => {
-	const { orgCurrentCommand } = await import("./commands/index.js");
-	const success = await orgCurrentCommand();
-	process.exit(success ? 0 : 1);
-});
-program.command("secrets").description("Manage secrets").command("list").description("List test-available secret contexts").option("--endpoint <url>", "Orchestrator URL override").action(async (options) => {
-	const { secretsListCommand } = await import("./commands/index.js");
-	const success = await secretsListCommand({ endpoint: options.endpoint });
-	process.exit(success ? 0 : 1);
-});
-program.command("status").argument("<run-id>", "Run ID to inspect").description("Show status and details of a test run").option("--logs", "Stream full log replay", false).option("--job <name>", "Filter logs to specific job").option("--json", "Output raw JSON", false).action(async (runId, options) => {
-	const { statusCommand } = await import("./commands/index.js");
-	const success = await statusCommand(runId, {
-		logs: options.logs,
-		job: options.job,
-		json: options.json
-	});
-	process.exit(success ? 0 : 1);
-});
-program.command("cancel").argument("[run-id]", "Run ID to cancel").description("Cancel a running workflow or all runs on a branch").option("--force", "Force cancel (kill immediately, skip hooks)", false).option("--branch <name>", "Cancel all in-progress runs on this branch").action(async (runId, options) => {
-	const { cancelCommand } = await import("./commands/index.js");
-	const success = await cancelCommand(runId, {
-		force: options.force,
-		branch: options.branch
-	});
-	process.exit(success ? 0 : 1);
-});
-program.command("types").description("Generate TypeScript declarations for secret contexts").option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--endpoint <url>", "Orchestrator URL override").action(async (options) => {
-	const { typesCommand } = await import("./commands/index.js");
-	const success = await typesCommand({
-		kiciDir: options.kiciDir,
-		endpoint: options.endpoint
-	});
-	process.exit(success ? 0 : 1);
-});
-program.command("endpoints").description("List all webhook entrypoints for the current project").option("--kici-dir <path>", "Path to .kici directory", ".kici").action(async (options) => {
-	const { endpointsCommand } = await import("./commands/index.js");
-	const success = await endpointsCommand({ kiciDir: options.kiciDir });
-	process.exit(success ? 0 : 1);
-});
-program.command("workflows").description("Manage workflow registrations").command("list").description("List permanently registered workflows").option("--json", "Output as JSON", false).option("--stale <duration>", "Filter stale registrations (e.g., 30d, 7d)").option("--trigger-type <type>", "Filter by trigger type").option("--repo <repo>", "Filter by repository").action(async (options) => {
-	const { workflowsListCommand } = await import("./commands/index.js");
-	const success = await workflowsListCommand({
-		json: options.json,
-		stale: options.stale,
-		triggerType: options.triggerType,
-		repo: options.repo
-	});
-	process.exit(success ? 0 : 1);
-});
-program.command("docs").description("Open the KiCI documentation site in the default browser").option("--no-open", "Print the docs URL instead of opening a browser").action(async (options) => {
-	const { docsCommand } = await import("./commands/index.js");
-	const success = await docsCommand({ open: options.open });
-	process.exit(success ? 0 : 1);
-}).command("llm").description("Print the bundled LLM context (llms-full.txt) to stdout").option("--index", "Print the curated llms.txt index instead of the full bundle", false).option("--out <path>", "Write the bundle to a file instead of stdout").action(async (options) => {
-	const { docsLlmCommand } = await import("./commands/index.js");
-	const success = await docsLlmCommand({
-		index: options.index,
-		out: options.out
-	});
-	process.exit(success ? 0 : 1);
-});
-program.command("admin").description("Operator-facing commands for running instances").command("drain-worker").description("Trigger graceful drain on a worker instance").requiredOption("--url <url>", "Worker URL (e.g., http://worker-host:<port>)").action(async (options) => {
-	const { drainWorkerCommand } = await import("./commands/index.js");
-	const success = await drainWorkerCommand({ url: options.url });
-	process.exit(success ? 0 : 1);
-});
-program.parse();
+		const { loginCommand } = await import("./commands/index.js");
+		const success = await loginCommand({
+			token: options.token,
+			device: options.device,
+			endpoint: options.endpoint,
+			platformEndpoint: options.platformEndpoint,
+			routingKey: options.routingKey
+		});
+		process.exit(success ? 0 : 1);
+	});
+	program.command("logout").description("Revoke PAT and clear local credentials").action(async () => {
+		const { logoutCommand } = await import("./commands/index.js");
+		const success = await logoutCommand();
+		process.exit(success ? 0 : 1);
+	});
+	const orgCommand = program.command("org").description("Manage organizations");
+	orgCommand.command("list").description("List organizations you belong to").action(async () => {
+		const { orgListCommand } = await import("./commands/index.js");
+		const success = await orgListCommand();
+		process.exit(success ? 0 : 1);
+	});
+	orgCommand.command("use").argument("<name>", "Organization name or ID").description("Switch active organization").action(async (name) => {
+		const { orgUseCommand } = await import("./commands/index.js");
+		const success = await orgUseCommand(name);
+		process.exit(success ? 0 : 1);
+	});
+	orgCommand.command("current").description("Show current active organization").action(async () => {
+		const { orgCurrentCommand } = await import("./commands/index.js");
+		const success = await orgCurrentCommand();
+		process.exit(success ? 0 : 1);
+	});
+	program.command("secrets").description("Manage secrets").command("list").description("List test-available secret contexts").option("--endpoint <url>", "Orchestrator URL override").action(async (options) => {
+		const { secretsListCommand } = await import("./commands/index.js");
+		const success = await secretsListCommand({ endpoint: options.endpoint });
+		process.exit(success ? 0 : 1);
+	});
+	program.command("status").argument("<run-id>", "Run ID to inspect").description("Show status and details of a test run").option("--logs", "Stream full log replay", false).option("--job <name>", "Filter logs to specific job").option("--json", "Output raw JSON", false).action(async (runId, options) => {
+		const { statusCommand } = await import("./commands/index.js");
+		const success = await statusCommand(runId, {
+			logs: options.logs,
+			job: options.job,
+			json: options.json
+		});
+		process.exit(success ? 0 : 1);
+	});
+	program.command("cancel").argument("[run-id]", "Run ID to cancel").description("Cancel a running workflow or all runs on a branch").option("--force", "Force cancel (kill immediately, skip hooks)", false).option("--branch <name>", "Cancel all in-progress runs on this branch").action(async (runId, options) => {
+		const { cancelCommand } = await import("./commands/index.js");
+		const success = await cancelCommand(runId, {
+			force: options.force,
+			branch: options.branch
+		});
+		process.exit(success ? 0 : 1);
+	});
+	program.command("approve").argument("<run-id>", "Run ID whose approval gate to approve").description("Approve a held approval gate for a run").option("--job <name>", "Approve the hold for a specific job").option("--step <index>", "Approve a step-scoped hold (requires --job)").action(async (runId, options) => {
+		const { approveCommand } = await import("./commands/index.js");
+		const success = await approveCommand(runId, {
+			job: options.job,
+			step: options.step
+		});
+		process.exit(success ? 0 : 1);
+	});
+	program.command("reject").argument("<run-id>", "Run ID whose approval gate to reject").description("Reject a held approval gate for a run").option("--job <name>", "Reject the hold for a specific job").option("--step <index>", "Reject a step-scoped hold (requires --job)").requiredOption("--reason <text>", "Reason for the rejection").action(async (runId, options) => {
+		const { rejectCommand } = await import("./commands/index.js");
+		const success = await rejectCommand(runId, {
+			job: options.job,
+			step: options.step,
+			reason: options.reason
+		});
+		process.exit(success ? 0 : 1);
+	});
+	program.command("types").description("Generate TypeScript declarations for secret contexts").option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--endpoint <url>", "Orchestrator URL override").action(async (options) => {
+		const { typesCommand } = await import("./commands/index.js");
+		const success = await typesCommand({
+			kiciDir: options.kiciDir,
+			endpoint: options.endpoint
+		});
+		process.exit(success ? 0 : 1);
+	});
+	program.command("endpoints").description("List all webhook entrypoints for the current project").option("--kici-dir <path>", "Path to .kici directory", ".kici").action(async (options) => {
+		const { endpointsCommand } = await import("./commands/index.js");
+		const success = await endpointsCommand({ kiciDir: options.kiciDir });
+		process.exit(success ? 0 : 1);
+	});
+	program.command("workflows").description("Manage workflow registrations").command("list").description("List permanently registered workflows").option("--json", "Output as JSON", false).option("--stale <duration>", "Filter stale registrations (e.g., 30d, 7d)").option("--trigger-type <type>", "Filter by trigger type").option("--repo <repo>", "Filter by repository").action(async (options) => {
+		const { workflowsListCommand } = await import("./commands/index.js");
+		const success = await workflowsListCommand({
+			json: options.json,
+			stale: options.stale,
+			triggerType: options.triggerType,
+			repo: options.repo
+		});
+		process.exit(success ? 0 : 1);
+	});
+	program.command("docs").description("Open the KiCI documentation site in the default browser").option("--no-open", "Print the docs URL instead of opening a browser").action(async (options) => {
+		const { docsCommand } = await import("./commands/index.js");
+		const success = await docsCommand({ open: options.open });
+		process.exit(success ? 0 : 1);
+	}).command("llm").description("Print the bundled LLM context (llms-full.txt) to stdout").option("--index", "Print the curated llms.txt index instead of the full bundle", false).option("--out <path>", "Write the bundle to a file instead of stdout").action(async (options) => {
+		const { docsLlmCommand } = await import("./commands/index.js");
+		const success = await docsLlmCommand({
+			index: options.index,
+			out: options.out
+		});
+		process.exit(success ? 0 : 1);
+	});
+	program.command("admin").description("Operator-facing commands for running instances").command("drain-worker").description("Trigger graceful drain on a worker instance").requiredOption("--url <url>", "Worker URL (e.g., http://worker-host:<port>)").action(async (options) => {
+		const { drainWorkerCommand } = await import("./commands/index.js");
+		const success = await drainWorkerCommand({ url: options.url });
+		process.exit(success ? 0 : 1);
+	});
+	return program;
+}
+/** Build the program and parse argv — the bin-shim entry point. */
+function runCli(argv = process.argv) {
+	buildProgram().parse(argv);
+}
+if (resolve(process.argv[1] ?? "") === fileURLToPath(import.meta.url)) runCli();
 //#endregion
-export {};
+export { buildProgram, runCli };
 
 //# sourceMappingURL=cli.js.map

package/dist/commands/approve.d.ts

@@ -0,0 +1,23 @@
+/**
+ * kici approve command
+ *
+ * Approves a held approval gate for a run. Resolves the held element by
+ * `--job` / `--step` (or the sole pending hold), then records the approval via
+ * the Platform dashboard API (PAT auth).
+ */
+/** Options for the approve command. */
+export interface ApproveOptions {
+    /** Match a hold by its job name. */
+    job?: string;
+    /** Match a step-scoped hold by its step index. */
+    step?: string;
+}
+/**
+ * Approve a held approval gate.
+ *
+ * @param runId - The run whose hold to approve.
+ * @param options - Job/step filters to disambiguate the held element.
+ * @returns true on success, false on error.
+ */
+export declare function approveCommand(runId: string, options?: ApproveOptions): Promise<boolean>;
+//# sourceMappingURL=approve.d.ts.map

package/dist/commands/approve.js

@@ -0,0 +1,46 @@
+import "../chunk-gOLHoazu.js";
+import { listHeldRunsForRun, postApprove, resolveHeldRunContext } from "./held-run-client.js";
+import { resolveHeldRunId } from "./held-run-resolve.js";
+import pc from "picocolors";
+import { logger, toErrorMessage } from "@kici-dev/core";
+//#region src/commands/approve.ts
+/**
+* kici approve command
+*
+* Approves a held approval gate for a run. Resolves the held element by
+* `--job` / `--step` (or the sole pending hold), then records the approval via
+* the Platform dashboard API (PAT auth).
+*/
+/**
+* Approve a held approval gate.
+*
+* @param runId - The run whose hold to approve.
+* @param options - Job/step filters to disambiguate the held element.
+* @returns true on success, false on error.
+*/
+async function approveCommand(runId, options = {}) {
+	try {
+		const ctx = await resolveHeldRunContext();
+		if (!ctx) return false;
+		const resolution = resolveHeldRunId(await listHeldRunsForRun(ctx, runId), {
+			job: options.job,
+			step: options.step
+		});
+		if (!resolution.ok) {
+			logger.error(pc.red(resolution.error));
+			return false;
+		}
+		logger.info(`Approving held run ${pc.cyan(resolution.heldRunId)} for run ${pc.cyan(runId)}...`);
+		if (!await postApprove(ctx, resolution.heldRunId)) return false;
+		logger.info(pc.green("Approval recorded."));
+		logger.info(pc.dim("If the requirement still has unsatisfied clauses, the run stays held until they are."));
+		return true;
+	} catch (error) {
+		logger.error(pc.red(`Error: ${toErrorMessage(error)}`));
+		return false;
+	}
+}
+//#endregion
+export { approveCommand };
+
+//# sourceMappingURL=approve.js.map

package/dist/commands/compile.js

@@ -7,10 +7,10 @@ import { validateConfig } from "../validation/validator.js";
 import "../validation/index.js";
 import { computeLockfileHash, detectGitRoot, generateLockFile, serializeLockFile } from "../lockfile/generator.js";
 import "../lockfile/index.js";
+import path from "node:path";
 import pc from "picocolors";
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
-import path from "node:path";
 import { logger, toErrorMessage } from "@kici-dev/core";
 import { execSync } from "node:child_process";
 //#region src/commands/compile.ts

package/dist/commands/docs.js

@@ -1,8 +1,8 @@
 import "../chunk-gOLHoazu.js";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
 import pc from "picocolors";
 import { readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { logger, toErrorMessage } from "@kici-dev/core";
 import open from "open";
 //#region src/commands/docs.ts

package/dist/commands/endpoints.js

@@ -2,9 +2,9 @@ import "../chunk-gOLHoazu.js";
 import { resolveKiciDir } from "../execution/executor.js";
 import "../execution/index.js";
 import { loadGlobalConfig } from "../remote/config.js";
+import path from "node:path";
 import pc from "picocolors";
 import { readFile } from "node:fs/promises";
-import path from "node:path";
 import { logger, toErrorMessage } from "@kici-dev/core";
 //#region src/commands/endpoints.ts
 /**

package/dist/commands/held-run-client.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared HTTP plumbing for the `kici approve` / `kici reject` held-run
+ * commands. Resolves auth + endpoint from the global config (PAT preferred,
+ * API key fallback; Platform endpoint preferred, orchestrator fallback) and
+ * exposes thin list / approve / reject helpers against the Platform dashboard
+ * API.
+ */
+import type { HeldRunSummary } from './held-run-resolve.js';
+/** Resolved auth context for a held-run command. */
+export interface HeldRunContext {
+    endpoint: string;
+    token: string;
+    orgId: string;
+}
+/**
+ * Resolve the auth context, printing a clear error and returning null when the
+ * CLI is not authenticated / no active org is set.
+ */
+export declare function resolveHeldRunContext(): Promise<HeldRunContext | null>;
+/** List the held runs for a single run id. */
+export declare function listHeldRunsForRun(ctx: HeldRunContext, runId: string): Promise<HeldRunSummary[]>;
+/** POST an approve decision for a held run. Returns true on success. */
+export declare function postApprove(ctx: HeldRunContext, heldRunId: string): Promise<boolean>;
+/** POST a reject decision (with reason) for a held run. Returns true on success. */
+export declare function postReject(ctx: HeldRunContext, heldRunId: string, reason: string): Promise<boolean>;
+//# sourceMappingURL=held-run-client.d.ts.map