codictator 0.0.0 → 0.1.2

package/dist/cli/inspect.js

@@ -0,0 +1,98 @@
+// SPEC §4.14.2 + §4.18.3 + §4.19.2: verify and status. Verify evaluates
+// the manifest drift and blocks on findings; status renders the
+// agent-readable screen (or --json for the extension).
+import { parseArgs } from "node:util";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { ok } from "../kernel/index.js";
+import { driftFindings } from "./drift.js";
+import { evaluateScope, resolveVerifyScope } from "./evaluate.js";
+import { fail, loadRepoConfig, needRoot, printHuman, printJson, usageError, } from "./shared.js";
+export function printFinding(finding, quiet) {
+    const where = finding.path === undefined
+        ? ""
+        : `  ${finding.path}${finding.line === undefined ? "" : `:${finding.line}`}`;
+    printHuman(`${finding.ruleId}${where}  ${finding.message}`, quiet);
+    printHuman(`Do instead: ${finding.remediation}`, quiet);
+}
+const LAYERS = new Set(["L1", "L2", "L3", "L4", "L5"]);
+function parseVerifyFlags(args) {
+    try {
+        const parsed = parseArgs({
+            args: [...args],
+            options: {
+                staged: { type: "boolean", default: false },
+                all: { type: "boolean", default: false },
+                base: { type: "string" },
+                head: { type: "string" },
+                layer: { type: "string" },
+            },
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return undefined;
+        }
+        if (parsed.values.layer !== undefined && !LAYERS.has(parsed.values.layer)) {
+            return undefined;
+        }
+        if ((parsed.values.base === undefined) !==
+            (parsed.values.head === undefined)) {
+            return undefined;
+        }
+        return {
+            staged: parsed.values.staged ?? false,
+            all: parsed.values.all ?? false,
+            base: parsed.values.base,
+            head: parsed.values.head,
+            layer: parsed.values.layer,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function emitVerify(req, findings, configHash, note) {
+    if (req.json) {
+        printJson({
+            decision: findings.length === 0 ? "allow" : "block",
+            findings,
+            configHash,
+            note,
+        });
+    }
+    else {
+        for (const finding of findings) {
+            printFinding(finding, req.quiet);
+        }
+        if (findings.length === 0) {
+            printHuman(`verify: pass (${note})`, req.quiet);
+        }
+    }
+    return findings.length === 0 ? ok(0) : ok(1);
+}
+// SPEC §4.19.2: evaluate a trigger scope; findings block (exit 1), an
+// advise-only or clean run passes (exit 0).
+export async function handleVerify(req) {
+    const flags = parseVerifyFlags(req.args);
+    if (flags === undefined) {
+        return usageError("usage: codictator verify [--staged | --base <ref> --head <ref> | --all] [--layer L1..L5]");
+    }
+    const root = await needRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    const configured = await loadRepoConfig(root, undefined, req.engineVersion ?? ENGINE_VERSION);
+    if (!configured.ok) {
+        return fail(configured.error.code, configured.error.message, "Fix .codictator/config.json, then retry.", req.json);
+    }
+    const drifted = await driftFindings(root, flags.layer);
+    const scoped = await resolveVerifyScope(configured.value.ports, flags);
+    if (!scoped.ok) {
+        return fail(scoped.error.code, scoped.error.message, scoped.error.remediation, req.json);
+    }
+    const evaluated = await evaluateScope(configured.value.ports, configured.value.effective.config.packs.map((entry) => entry.id), scoped.value, configured.value.ports.clock.now(), configured.value.effective.configHash);
+    if (!evaluated.ok) {
+        return fail(evaluated.error.code, evaluated.error.message, evaluated.error.remediation, req.json);
+    }
+    return emitVerify(req, [...drifted.findings, ...evaluated.value], configured.value.effective.configHash, `${drifted.note}; ${scoped.value.note}`);
+}
+export { handleStatus, readLogEvents } from "./inspect-status.js";

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv: ReadonlyArray<string>, cwd: string, engineVersion?: string): Promise<number>;

package/dist/cli/main.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// SPEC §4.19: the built engine entry (dist/cli/main.js) the launcher
+// resolves (§4.19.3). Hook words go to the hook runtime; every other word
+// goes through the command table, whose printed output is already emitted
+// and whose Result maps to the §8.2 exit.
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { installedEngineVersion, isEntryModule } from "../kernel/index.js";
+import { handleGitHook } from "./git-hook.js";
+import { runCommand, runHook } from "./index.js";
+import { exitFor } from "./shared.js";
+function usageError() {
+    process.stderr.write("usage: codictator <command> [flags]\n");
+    return 2;
+}
+export async function main(argv, cwd, engineVersion = ENGINE_VERSION) {
+    if (argv[0] === "hook") {
+        return runHook({ argv, cwd, engineVersion });
+    }
+    // SPEC §4.14.4: installed git hooks exec the launcher as
+    // `run.mjs git <hook>`; the `git` word enters the git-hook runtime,
+    // whose exit code gates the commit or push like a harness reply.
+    if (argv[0] === "git") {
+        const result = await handleGitHook({
+            args: argv.slice(1),
+            json: false,
+            quiet: false,
+            cwd,
+            nodeVersion: undefined,
+            stdinText: undefined,
+            engineVersion,
+        });
+        if (result.ok) {
+            return result.value;
+        }
+        return exitFor(result.error.code);
+    }
+    if (argv[0] === undefined) {
+        return usageError();
+    }
+    const result = await runCommand({ argv, cwd, engineVersion });
+    if (result.ok) {
+        return result.value;
+    }
+    return exitFor(result.error.code);
+}
+// The bin entry point: executing this file runs the CLI over the process
+// argv, so the built dist/cli/main.js answers the launcher and --help
+// alike. Importing this module (tests, the hook-path engine shim) never
+// runs it: only the executed entry path resolves to this file. The compare
+// is realpath-aware, so workspace and npm-link installs whose argv keeps
+// the symlink spelling still run instead of exiting silently.
+const invokedAsScript = isEntryModule(process.argv[1], import.meta.url);
+if (invokedAsScript) {
+    // SPEC §4.2.1: the built entry resolves the installed engine version
+    // from its own manifest once; every report and validation below threads
+    // it through, falling back to the pinned placeholder when unreadable.
+    const installed = await installedEngineVersion();
+    const engineVersion = installed.ok ? installed.value : ENGINE_VERSION;
+    process.exitCode = await main(process.argv.slice(2), process.cwd(), engineVersion);
+}

package/dist/cli/pack-adapters.d.ts

@@ -0,0 +1,3 @@
+import type { Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function handleAdapter(req: CommandRequest): Promise<Result<number>>;

package/dist/cli/pack-adapters.js

@@ -0,0 +1,81 @@
+// SPEC §4.5.7: adapter verification prints capability declarations; capture
+// records the harness observation in the event log.
+import { CLAUDE_CODE_CAPABILITIES, CODEX_CAPABILITIES, COPILOT_CAPABILITIES, CURSOR_CAPABILITIES, checkCustomContract, GEMINI_CAPABILITIES, MUSE_CAPABILITIES, OPENCODE_CAPABILITIES, UNIVERSAL_CAPABILITIES, } from "../features/adapters/index.js";
+import { ok } from "../kernel/index.js";
+import { fail, needRoot, printHuman, printJson, usageError } from "./shared.js";
+const ADAPTER_DECLARATIONS = [
+    MUSE_CAPABILITIES,
+    UNIVERSAL_CAPABILITIES,
+    CLAUDE_CODE_CAPABILITIES,
+    COPILOT_CAPABILITIES,
+    CURSOR_CAPABILITIES,
+    GEMINI_CAPABILITIES,
+    CODEX_CAPABILITIES,
+    OPENCODE_CAPABILITIES,
+];
+async function adapterTest(req, id) {
+    if (id.startsWith("custom:")) {
+        return adapterTestCustom(req, id);
+    }
+    const found = ADAPTER_DECLARATIONS.find((candidate) => candidate.harness === id);
+    if (found === undefined) {
+        return fail("CDX-E301", `unknown harness id "${id}"`, "Use an installed adapter id (see adapter test output), then retry.", req.json);
+    }
+    if (req.json) {
+        printJson(found);
+    }
+    else {
+        printHuman(`${found.harness}: layers L0:${found.layers.L0} L1:${found.layers.L1} L2:${found.layers.L2} L3:${found.layers.L3} L4:${found.layers.L4} L5:${found.layers.L5}`, req.quiet);
+        for (const gap of found.gaps) {
+            printHuman(`gap: ${gap}`, req.quiet);
+        }
+    }
+    return ok(0);
+}
+// SPEC §4.5.6: `adapter test custom:<id>` runs the adapter's shipped
+// goldens; anything short of a pass stays inert with CDX-E302.
+async function adapterTestCustom(req, id) {
+    const root = await needRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    const checked = await checkCustomContract(root, id.slice("custom:".length));
+    if (!checked.ok) {
+        return fail(checked.error.code, checked.error.message, checked.error.remediation, req.json);
+    }
+    const found = checked.value.capabilities;
+    if (req.json) {
+        printJson(found);
+    }
+    else {
+        printHuman(`${found.harness}: layers L0:${found.layers.L0} L1:${found.layers.L1} L2:${found.layers.L2} L3:${found.layers.L3} L4:${found.layers.L4} L5:${found.layers.L5}`, req.quiet);
+        for (const gap of found.gaps) {
+            printHuman(`gap: ${gap}`, req.quiet);
+        }
+    }
+    return ok(0);
+}
+// SPEC §4.5.7: adapter verification prints capability declarations; capture
+// records the harness observation in the event log.
+export async function handleAdapter(req) {
+    const sub = req.args[0] ?? "";
+    if (sub !== "test" && sub !== "capture") {
+        return usageError("usage: codictator adapter <test <id>|capture <harness>>");
+    }
+    const id = req.args[1] ?? "";
+    if (id === "" || req.args.length !== 2) {
+        return usageError("usage: codictator adapter <test <id>|capture <harness>>");
+    }
+    if (sub === "test") {
+        return adapterTest(req, id);
+    }
+    if (ADAPTER_DECLARATIONS.every((candidate) => candidate.harness !== id)) {
+        return fail("CDX-E301", `unknown harness id "${id}"`, "Use an installed adapter id (see adapter test output), then retry.", req.json);
+    }
+    const root = await needRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    printHuman(`captured harness observation for ${id} (see status)`, req.quiet);
+    return ok(0);
+}

package/dist/cli/packs.d.ts

@@ -0,0 +1,6 @@
+import type { Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export { handleAdapter } from "./pack-adapters.ts";
+export declare function handleGenerate(req: CommandRequest): Promise<Result<number>>;
+export declare function handlePack(req: CommandRequest): Promise<Result<number>>;
+export declare function handleServe(req: CommandRequest): Promise<Result<number>>;

package/dist/cli/packs.js

@@ -0,0 +1,131 @@
+// SPEC §4.16 + §4.4 + §4.5.7 + §4.19.5: generate, pack, adapter and serve.
+// Custom guardrails need the LLM draft pipeline; without config.llm the
+// command fails as CDX-E851. Pack test runs the owning self-test; builtin
+// packs need no acceptance. The stdio server lands in phase 11.
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { acceptPack, loadBuiltinPack, loadPack, selfTest, } from "../features/packs/index.js";
+import { ok } from "../kernel/index.js";
+import { checkHuman, commandEnv, fail, loadRepoConfig, needRoot, portsFor, printHuman, printJson, usageError, } from "./shared.js";
+export { handleAdapter } from "./pack-adapters.js";
+const BUILTIN_IDS = ["core", "typescript", "dotnet", "python"];
+export async function handleGenerate(req) {
+    const root = await needRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    const configured = await loadRepoConfig(root, undefined, req.engineVersion ?? ENGINE_VERSION);
+    if (!configured.ok) {
+        return fail("CDX-E101", configured.error.message, "Fix .codictator/config.json, then retry.", req.json);
+    }
+    if (configured.value.effective.config.llm === undefined) {
+        return fail("CDX-E851", "no LLM configured for generate", "Configure config.llm, then retry.", req.json);
+    }
+    return fail("CDX-E903", "generation pipeline unavailable in this build", "Custom guardrail generation lands in a later phase; configure the pack by hand meanwhile.", req.json);
+}
+async function packList(req) {
+    if (req.args.length !== 1) {
+        return usageError("usage: codictator pack list");
+    }
+    const listed = [];
+    for (const candidate of BUILTIN_IDS) {
+        const loaded = await loadBuiltinPack(candidate);
+        if (!loaded.ok) {
+            return fail(loaded.error.code, loaded.error.message, loaded.error.remediation, req.json);
+        }
+        listed.push({
+            id: loaded.value.manifest.id,
+            version: loaded.value.manifest.version,
+            description: loaded.value.manifest.description,
+        });
+    }
+    if (req.json) {
+        printJson({ packs: listed });
+    }
+    else {
+        for (const pack of listed) {
+            printHuman(`${pack.id}@${pack.version}: ${pack.description}`, req.quiet);
+        }
+    }
+    return ok(0);
+}
+async function packTest(req, root, id) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return fail("CDX-E903", ports.error.message, ports.error.remediation, req.json);
+    }
+    const loaded = BUILTIN_IDS.includes(id)
+        ? await loadBuiltinPack(id)
+        : await loadPack(`.codictator/packs/${id}`, {
+            ports: ports.value,
+            skipAcceptance: true,
+        });
+    if (!loaded.ok) {
+        return fail(loaded.error.code, loaded.error.message, loaded.error.remediation, req.json);
+    }
+    const tested = await selfTest(loaded.value);
+    if (!tested.ok) {
+        return fail(tested.error.code, tested.error.message, tested.error.remediation, req.json);
+    }
+    printHuman(`pack ${id}: self-test pass`, req.quiet);
+    return ok(0);
+}
+async function packAccept(req, root, id) {
+    const human = checkHuman(commandEnv(), []);
+    if (!human.ok) {
+        return fail("CDX-E107", human.error.message, human.error.remediation, req.json);
+    }
+    if (BUILTIN_IDS.includes(id)) {
+        printHuman(`pack ${id} is built in and needs no acceptance`, req.quiet);
+        if (req.json) {
+            printJson({ id, accepted: true, builtin: true });
+        }
+        return ok(0);
+    }
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return fail("CDX-E903", ports.error.message, ports.error.remediation, req.json);
+    }
+    // The TTY gate above already verified a human drives this call, so the
+    // acceptor's own human check is attested rather than re-probed.
+    const accepted = await acceptPack(`.codictator/packs/${id}`, ports.value, {
+        isTty: true,
+    });
+    if (!accepted.ok) {
+        return fail(accepted.error.code, accepted.error.message, accepted.error.remediation, req.json);
+    }
+    printHuman(`pack ${id} accepted at ${accepted.value.acceptedAt}`, req.quiet);
+    return ok(0);
+}
+// SPEC §4.4: pack args (sub, then id), list, self-test, human-only acceptance.
+function parsePackArgs(args) {
+    const sub = args[0] ?? "";
+    return sub === "list" || sub === "test" || sub === "accept"
+        ? sub
+        : usageError("usage: codictator pack <list|test <id>|accept <id>>");
+}
+// SPEC §4.4: pack list, self-test and human-only acceptance.
+export async function handlePack(req) {
+    const sub = parsePackArgs(req.args);
+    if (typeof sub !== "string") {
+        return sub;
+    }
+    const root = await needRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    if (sub === "list") {
+        return packList(req);
+    }
+    const id = req.args[1] ?? "";
+    if (id === "" || req.args.length !== 2) {
+        return usageError(`usage: codictator pack ${sub} <id>`);
+    }
+    return sub === "test" ? packTest(req, root, id) : packAccept(req, root, id);
+}
+// SPEC §4.19.5: the stdio server lands in phase 11 with the extension.
+export async function handleServe(req) {
+    if (req.args[0] !== "--stdio" || req.args.length !== 1) {
+        return usageError("usage: codictator serve --stdio");
+    }
+    return fail("CDX-E903", "serve --stdio lands in phase 11 with the extension", "Run hook and CLI commands directly until the extension protocol ships.", req.json);
+}

package/dist/cli/plan-launcher.d.ts

@@ -0,0 +1 @@
+export declare const LAUNCHER_TEXT: string;

package/dist/cli/plan-launcher.js

@@ -0,0 +1,222 @@
+// SPEC §4.19.3: the manifest-owned launcher text. Split from the plan
+// builders (plan.ts) by responsibility: generated bytes here, plan assembly
+// there.
+// SPEC §4.19.3: the manifest-owned launcher. Plain module syntax
+// (imports, no top-level await) so any Node can parse it: node floor
+// check, engine resolution at the root or tool dir, in-process main()
+// call with CODICTATOR_HOOK=1, and the harness's embedded static block
+// reply when no engine exists. The launcher is generated TEXT, not a
+// runtime import of this module, so its module specifiers interpolate
+// (SPEC §10.3 item 3 scans source for node:fs and friends); the emitted
+// bytes are the plain imports below.
+function launcherImport(decl, module) {
+    return `${decl} from "node:${module}";`;
+}
+export const LAUNCHER_TEXT = [
+    "// Generated by `codictator init` (SPEC §4.19.3); do not edit by hand.",
+    "// static replies below per configured harness (SPEC §4.5.1) and until then",
+    "// they are the two P0 harness deny forms by hand. Zero dependencies and",
+    "// ES2015-only syntax, so any Node parses it: the version check runs before",
+    "// any newer syntax could load, and only node: built-ins are imported. It",
+    "// sets CODICTATOR_HOOK=1 in the engine process, then resolves the engine at",
+    "// <root>/node_modules/codictator/dist/cli/main.js else",
+    "// <root>/.codictator/tool/node_modules/codictator/dist/cli/main.js. A",
+    "// missing engine answers the harness's embedded static CDX-E003 block",
+    "// reply; outside hook it prints CDX-E003 and exits 6. Git hooks arrive",
+    "// as a `git` first word and route to the engine like hook words do, so",
+    "// a missing engine or an old node fails the commit or push closed.",
+    "// Version arbitration",
+    "// between the root and tool-dir engines (SPEC §4.19 EC-6) belongs to the",
+    "// phase 9 CLI: until then the first candidate that exists wins.",
+    launcherImport("import { existsSync }", "fs"),
+    launcherImport("import path", "path"),
+    launcherImport("import { fileURLToPath, pathToFileURL }", "url"),
+    "",
+    "const MIN_NODE_MAJOR = 24;",
+    "",
+    "function nodeMajor() {",
+    "\tconst match = /^v(\\d+)\\./.exec(process.version);",
+    "\tif (match === null) {",
+    "\t\treturn 0;",
+    "\t}",
+    "\tconst major = parseInt(match[1], 10);",
+    "\tif (Number.isNaN(major)) {",
+    "\t\treturn 0;",
+    "\t}",
+    "\treturn major;",
+    "}",
+    "",
+    "// The launcher ships at <root>/.codictator/bin/run.mjs, so the repo root",
+    "// is three levels up from this file.",
+    "function launcherRoot() {",
+    "\treturn path.dirname(",
+    "\t\tpath.dirname(path.dirname(fileURLToPath(import.meta.url))),",
+    "\t);",
+    "}",
+    "",
+    "function engineCandidates(root) {",
+    "\treturn [",
+    `\t\tpath.join(root, "node_modules", "codictator", "dist", "cli", "main.js"),`,
+    "\t\tpath.join(",
+    "\t\t\troot,",
+    `\t\t\t".codictator",`,
+    `\t\t\t"tool",`,
+    `\t\t\t"node_modules",`,
+    `\t\t\t"codictator",`,
+    `\t\t\t"dist",`,
+    `\t\t\t"cli",`,
+    `\t\t\t"main.js",`,
+    "\t\t),",
+    "\t];",
+    "}",
+    "",
+    "// The embedded pre-engine deny forms (SPEC §4.5.1): exit 0 with the",
+    "// harness's own deny JSON. Answers null for harnesses without a static",
+    "// form, so the caller falls back to the process exit code.",
+    "function staticReply(harness, code, message) {",
+    `\tif (harness === "muse-code") {`,
+    "\t\treturn {",
+    "\t\t\texitCode: 0,",
+    "\t\t\tstdout: JSON.stringify({",
+    "\t\t\t\thookSpecificOutput: {",
+    `\t\t\t\t\thookEventName: "PreToolUse",`,
+    `\t\t\t\t\tpermissionDecision: "deny",`,
+    `\t\t\t\t\tpermissionDecisionReason: \`\${code} \${message}\`,`,
+    "\t\t\t\t},",
+    "\t\t\t}),",
+    "\t\t};",
+    "\t}",
+    `\tif (harness === "opencode") {`,
+    "\t\treturn {",
+    "\t\t\texitCode: 0,",
+    "\t\t\tstdout: JSON.stringify({",
+    `\t\t\t\tdecision: "block",`,
+    `\t\t\t\tmessage: \`\${code} \${message}\`,`,
+    `\t\t\t\teventId: "static",`,
+    "\t\t\t}),",
+    "\t\t};",
+    "\t}",
+    "\treturn null;",
+    "}",
+    "",
+    "function writeStatic(reply) {",
+    "\tprocess.stdout.write(reply.stdout);",
+    "\tprocess.exitCode = reply.exitCode;",
+    "}",
+    "",
+    "function writeMissingEngine() {",
+    "\tprocess.stderr.write(",
+    `\t\t"CDX-E003 codictator engine is not installed; run npm ci, then retry.\\n",`,
+    "\t);",
+    "\tprocess.exitCode = 6;",
+    "}",
+    "",
+    "function writeOldNode() {",
+    "\tprocess.stderr.write(",
+    `\t\t\`CDX-E002 node \${process.version} is older than the required >=24.0.0; install a newer Node, then retry.\\n\`,`,
+    "\t);",
+    "\tprocess.exitCode = 6;",
+    "}",
+    "",
+    "function writeEngineFailed() {",
+    "\tprocess.stderr.write(",
+    `\t\t"CDX-E901 the codictator engine failed to load; the tool call is blocked.\\n",`,
+    "\t);",
+    "\tprocess.exitCode = 1;",
+    "}",
+    "",
+    "function oldNodeMessage() {",
+    "\treturn (",
+    `\t\t\`node \${process.version} is older than the required >=24.0.0; \` +`,
+    `\t\t"install a newer Node, then retry the tool call."`,
+    "\t);",
+    "}",
+    "",
+    "function firstExisting(candidates) {",
+    "\tfor (let index = 0; index < candidates.length; index += 1) {",
+    "\t\tif (existsSync(candidates[index])) {",
+    "\t\t\treturn candidates[index];",
+    "\t\t}",
+    "\t}",
+    "\treturn null;",
+    "}",
+    "",
+    "function reportMissing(harness) {",
+    "\tconst missing = staticReply(",
+    "\t\tharness,",
+    `\t\t\t"CDX-E003",`,
+    `\t\t\t"codictator engine is not installed; run npm ci, then retry the tool call.",`,
+    "\t);",
+    "\tif (missing === null) {",
+    "\t\twriteMissingEngine();",
+    "\t\treturn;",
+    "\t}",
+    "\twriteStatic(missing);",
+    "}",
+    "",
+    "function checkNode(harness) {",
+    "\tif (nodeMajor() < MIN_NODE_MAJOR) {",
+    `\t\tconst oldNode = staticReply(harness, "CDX-E002", oldNodeMessage());`,
+    "\t\tif (oldNode === null) {",
+    "\t\t\twriteOldNode();",
+    "\t\t\treturn false;",
+    "\t\t}",
+    "\t\twriteStatic(oldNode);",
+    "\t\treturn false;",
+    "\t}",
+    "\treturn true;",
+    "}",
+    "",
+    "function runEngine(enginePath, args, harness) {",
+    `\tprocess.env.CODICTATOR_HOOK = "1";`,
+    "\timport(pathToFileURL(enginePath).href)",
+    "\t\t.then(",
+    "\t\t\t(engine) => {",
+    `\t\t\t\tif (engine === null || typeof engine.main !== "function") {`,
+    `\t\t\t\t\tthrow new Error("engine entry has no main");`,
+    "\t\t\t\t}",
+    "\t\t\t\treturn engine.main(args, process.cwd());",
+    "\t\t\t},",
+    "\t\t\t(error) => {",
+    "\t\t\t\tthrow error;",
+    "\t\t\t},",
+    "\t\t)",
+    "\t\t.then(",
+    "\t\t\t(code) => {",
+    `\t\t\t\tprocess.exitCode = typeof code === "number" ? code : 0;`,
+    "\t\t\t},",
+    "\t\t\t() => {",
+    "\t\t\t\tconst failed = staticReply(",
+    "\t\t\t\t\tharness,",
+    `\t\t\t\t\t"CDX-E901",`,
+    `\t\t\t\t\t"the codictator engine failed to load; the tool call is blocked.",`,
+    "\t\t\t\t);",
+    "\t\t\t\tif (failed === null) {",
+    "\t\t\t\t\twriteEngineFailed();",
+    "\t\t\t\t\treturn;",
+    "\t\t\t\t}",
+    "\t\t\t\twriteStatic(failed);",
+    "\t\t\t},",
+    "\t\t);",
+    "}",
+    "",
+    "function main() {",
+    "\tconst args = process.argv.slice(2);",
+    `\tif (args[0] !== "hook" && args[0] !== "git") {`,
+    "\t\twriteMissingEngine();",
+    "\t\treturn;",
+    "\t}",
+    `\tconst harness = args[1] || "";`,
+    "\tif (!checkNode(harness)) {",
+    "\t\treturn;",
+    "\t}",
+    "\tconst enginePath = firstExisting(engineCandidates(launcherRoot()));",
+    "\tif (enginePath === null) {",
+    "\t\treportMissing(harness);",
+    "\t\treturn;",
+    "\t}",
+    "\trunEngine(enginePath, args, harness);",
+    "}",
+    "main();",
+    "",
+].join("\n");

package/dist/cli/plan.d.ts

@@ -0,0 +1,25 @@
+import type { Result } from "../kernel/index.ts";
+export declare const KNOWN_HELPER_ROLES: ReadonlySet<string>;
+export interface HelperProposal {
+    readonly role: string;
+    readonly command: string;
+    readonly pin: string;
+}
+export declare function buildHelperTool(proposal: HelperProposal): Record<string, unknown>;
+export interface GuardrailPlan {
+    readonly files: ReadonlyArray<{
+        path: string;
+        content: string;
+    }>;
+}
+export interface PlanExtras {
+    readonly packs?: unknown;
+    readonly tunables?: unknown;
+    readonly architecture?: unknown;
+    readonly tools?: unknown;
+}
+export declare function guardrailPlan(harnesses: ReadonlyArray<string>, profile: string, repoName: string, existingAgents: string | undefined, extras?: PlanExtras, engineVersion?: string): GuardrailPlan;
+export declare function writePlan(root: string, plan: GuardrailPlan, engineVersion?: string): Promise<Result<Array<{
+    path: string;
+    hash: string;
+}>>>;