codictator 0.0.0 → 0.1.3

package/dist/cli/guardrail.js

@@ -0,0 +1,190 @@
+// SPEC §4.14.4 + §4.14.5 + §4.19.2: regen, install-hooks and uninstall.
+// Regen re-renders guardrails from config and rewrites the manifest;
+// install-hooks writes the hooks and points core.hooksPath at them;
+// uninstall removes generated files with the CI warning.
+import { parseArgs } from "node:util";
+import { renderCustomRegenFragment } from "../features/adapters/index.js";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { EXPECTED_HOOKS_PATH, HOOK_NAMES, hookInstallPlan, renderHookScript, } from "../features/integrity/index.js";
+import { err, ok, resolveRepoRoot } from "../kernel/index.js";
+import { guardrailPlan, writePlan } from "./plan.js";
+import { checkHuman, commandEnv, fail, loadRepoConfig, portsFor, printHuman, printJson, readStateText, usageError, } from "./shared.js";
+function repoNameOf(root) {
+    return root.replaceAll("\\", "/").split("/").pop() ?? "repo";
+}
+// SPEC §4.14.5: regen re-renders from config, so a profile chosen at init
+// survives regeneration instead of being dropped from the rewritten config.
+function profileOf(architecture) {
+    if (typeof architecture === "object" && architecture !== null) {
+        const profile = architecture.profile;
+        if (typeof profile === "string" && profile !== "") {
+            return profile;
+        }
+    }
+    return "";
+}
+// SPEC §4.14.5: regen re-renders guardrails from config and rewrites the
+// manifest; user text outside managed regions survives.
+// Regen, install-hooks and uninstall reject positionals the same way.
+function rejectPositionals(args, usage) {
+    try {
+        const parsed = parseArgs({
+            args: [...args],
+            options: {},
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return usageError(usage);
+        }
+    }
+    catch {
+        return usageError(usage);
+    }
+    return undefined;
+}
+export async function handleRegen(req) {
+    const rejected = rejectPositionals(req.args, "usage: codictator regen");
+    if (rejected !== undefined) {
+        return rejected;
+    }
+    const root = await resolveRepoRoot(req.cwd);
+    if (!root.ok) {
+        return fail("CDX-E703", root.error.message, root.error.remediation, req.json);
+    }
+    const loaded = await loadRepoConfig(root.value, undefined, req.engineVersion ?? ENGINE_VERSION);
+    if (!loaded.ok) {
+        return fail(loaded.error.code, loaded.error.message, "Fix .codictator/config.json, then retry.", req.json);
+    }
+    const agents = await readStateText(root.value, "AGENTS.md");
+    const configured = loaded.value.effective.config;
+    const profile = profileOf(configured.architecture);
+    const customFiles = await renderCustomRegenFragment(root.value, configured);
+    if (!customFiles.ok) {
+        return fail(customFiles.error.code, customFiles.error.message, customFiles.error.remediation, req.json);
+    }
+    const plan = guardrailPlan(loaded.value.effective.config.harnesses, profile, repoNameOf(root.value), agents, {
+        packs: configured.packs,
+        tunables: configured.tunables,
+        architecture: configured.architecture,
+        tools: configured.tools,
+    }, req.engineVersion ?? ENGINE_VERSION);
+    const wrote = await writePlan(root.value, { files: [...plan.files, ...customFiles.value] }, req.engineVersion ?? ENGINE_VERSION);
+    if (!wrote.ok) {
+        return fail("CDX-E903", wrote.error.message, wrote.error.remediation, req.json);
+    }
+    if (req.json) {
+        printJson({
+            regenerated: true,
+            root: root.value,
+            files: wrote.value.map((entry) => entry.path),
+        });
+    }
+    else {
+        for (const entry of wrote.value) {
+            printHuman(`regenerated ${entry.path}`, req.quiet);
+        }
+    }
+    return ok(0);
+}
+function encode(text) {
+    return new TextEncoder().encode(text);
+}
+async function writeHookFiles(root) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return err(ports.error);
+    }
+    for (const hook of HOOK_NAMES) {
+        const done = await ports.value.fs.write(`${EXPECTED_HOOKS_PATH}/${hook}`, encode(renderHookScript(hook)));
+        if (!done.ok) {
+            return err(done.error);
+        }
+    }
+    const plan = hookInstallPlan({});
+    const attrs = await ports.value.fs.write(`${EXPECTED_HOOKS_PATH}/.gitattributes`, encode(plan.gitattributes));
+    if (!attrs.ok) {
+        return err(attrs.error);
+    }
+    return ok(true);
+}
+async function configureHooksPath(root, req) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return;
+    }
+    const plan = hookInstallPlan({});
+    const set = await ports.value.proc.run(["git", "config", "core.hooksPath", plan.hooksPath], { cwd: root, env: {}, timeoutMs: 15000, maxOutputBytes: 65536 });
+    if (set.code !== 0) {
+        printHuman("warn: git config core.hooksPath failed; set it by hand", req.quiet);
+    }
+}
+// SPEC §4.14.4: install-hooks writes the hooks and points core.hooksPath
+// at them; the npm prepare script and gitattributes remediation ship too.
+export async function handleInstallHooks(req) {
+    const rejected = rejectPositionals(req.args, "usage: codictator install-hooks");
+    if (rejected !== undefined) {
+        return rejected;
+    }
+    const root = await resolveRepoRoot(req.cwd);
+    if (!root.ok) {
+        return fail("CDX-E703", root.error.message, root.error.remediation, req.json);
+    }
+    const written = await writeHookFiles(root.value);
+    if (!written.ok) {
+        return fail("CDX-E903", written.error.message, written.error.remediation, req.json);
+    }
+    await configureHooksPath(root.value, req);
+    const plan = hookInstallPlan({});
+    if (req.json) {
+        printJson({ installed: true, hooksPath: plan.hooksPath, root: root.value });
+    }
+    else {
+        printHuman(`hooks installed at ${plan.hooksPath}; prepare script: ${plan.prepareScript}`, req.quiet);
+    }
+    return ok(0);
+}
+async function removeGuardrails(root) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return;
+    }
+    const targets = [
+        ".codictator/config.json",
+        ".codictator/manifest.json",
+        ".github/workflows/codictator.yml",
+        ...HOOK_NAMES.map((hook) => `${EXPECTED_HOOKS_PATH}/${hook}`),
+    ];
+    for (const target of targets) {
+        const seen = await ports.value.fs.exists(target);
+        if (seen.ok && seen.value) {
+            await ports.value.fs.remove(target);
+        }
+    }
+}
+// SPEC §4.19.2: uninstall removes generated files, records a guardrail
+// entry, and prints that CI fails until its workflow and required check
+// are removed too. Human-only.
+export async function handleUninstall(req) {
+    const rejected = rejectPositionals(req.args, "usage: codictator uninstall");
+    if (rejected !== undefined) {
+        return rejected;
+    }
+    const human = checkHuman(commandEnv(), []);
+    if (!human.ok) {
+        return fail("CDX-E107", human.error.message, human.error.remediation, req.json);
+    }
+    const root = await resolveRepoRoot(req.cwd);
+    if (!root.ok) {
+        return fail("CDX-E703", root.error.message, root.error.remediation, req.json);
+    }
+    await removeGuardrails(root.value);
+    const note = "CI will fail until its workflow and required check are removed too.";
+    if (req.json) {
+        printJson({ uninstalled: true, root: root.value, note });
+    }
+    else {
+        printHuman(`uninstalled guardrails from ${root.value}`, req.quiet);
+        printHuman(note, req.quiet);
+    }
+    return ok(0);
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,12 @@
+import type { CdxError, Result } from "../kernel/index.ts";
+export interface CliOptions {
+    readonly argv: ReadonlyArray<string>;
+    readonly cwd: string;
+    readonly stdinText?: string;
+    readonly nodeVersion?: string;
+    readonly engineVersion?: string;
+}
+export declare function runHook(options: CliOptions): Promise<number>;
+export declare function runCommand(options: CliOptions): Promise<Result<number>>;
+export declare function runServer(options: CliOptions): Promise<number>;
+export type { CdxError };

package/dist/cli/index.js

@@ -0,0 +1,198 @@
+// SPEC §4.19: composition root. Commands, hook entry, server. May import
+// everything (§3.3); owns no §7 format.
+import { HOOK_PAYLOAD_MAX_BYTES, hookBudgetMs, runHookEvent, staticBlock, supportedHarness, } from "../features/adapters/index.js";
+import { appendEvent } from "../features/audit/index.js";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { err, NodeEnv, NodeFs, NodeGit, NodeNet, NodeProc, ok, readStdinText, SystemClock, } from "../kernel/index.js";
+import { COMMANDS, USAGE } from "./commands.js";
+import { loadEvalEnforcers } from "./evaluate.js";
+import { startStdioServer } from "./serve-server.js";
+import { MIN_NODE_MAJOR, nodeMajor, nodeTooOldMessage, printHuman, usageError, } from "./shared.js";
+// SPEC §4.19.3 steps 3 and 5: the verdict line lands in the resolved repo's
+// event log. An append failure is the engine's CDX-E801 path, never a throw
+// here, so writer faults stay fail-closed without crashing the hook.
+// SPEC §4.1.1: the Fs is already confined to root, so the logical root is
+// "." and every audit path stays repo-relative.
+async function appendLine(root, event, ports) {
+    const fsMade = await NodeFs.create({ root });
+    if (!fsMade.ok) {
+        return fsMade;
+    }
+    return appendEvent({
+        fs: fsMade.value,
+        proc: ports.proc,
+        net: ports.net,
+        clock: ports.clock,
+        git: new NodeGit(ports.proc, root),
+        env: ports.env,
+    }, ".", event);
+}
+// The old-node rejection: a static block when the harness has one,
+// stderr plus exit 6 otherwise.
+function oldNodeExit(harness, version) {
+    const staticReply = harness === ""
+        ? undefined
+        : staticBlock(harness, "CDX-E002", nodeTooOldMessage(version));
+    if (staticReply === undefined) {
+        process.stderr.write(`${nodeTooOldMessage(version)}\n`);
+        return 6;
+    }
+    return emitReply(staticReply.stdout, staticReply.stderr, staticReply.exitCode);
+}
+// A failed stdin wait fails closed: a static block when the harness has
+// one, stderr plus exit 1 otherwise.
+function blockedStdinExit(harness, code, message) {
+    const blocked = staticBlock(harness, code, message);
+    if (blocked === undefined) {
+        process.stderr.write(`${code} ${message}\n`);
+        return 1;
+    }
+    return emitReply(blocked.stdout, blocked.stderr, blocked.exitCode);
+}
+// The hook invocation resolves its stdin first: an idle pipe fails closed
+// with CDX-E902 instead of hanging past the time limit (§4.5.5), while an
+// unknown harness never had a payload and answers without I/O.
+async function invokeHookEvent(harness, event, stdinText, cwd, ports, append, engineVersion) {
+    let text = stdinText;
+    if (text === undefined && supportedHarness(harness)) {
+        const stdin = await readStdinText(HOOK_PAYLOAD_MAX_BYTES, hookBudgetMs(harness));
+        if (!stdin.ok) {
+            return blockedStdinExit(harness, stdin.error.code, stdin.error.message);
+        }
+        text = stdin.value;
+    }
+    const reply = await runHookEvent({
+        harness,
+        event,
+        stdinText: text ?? "",
+        cwd,
+        ports,
+        append,
+        engineVersion,
+        // SPEC §4.19.3 step 5: the hook evaluates the same pack enforcers
+        // the verify path loads (core plus the configured builtin packs),
+        // resolved against the runtime's root-confined ports.
+        loadEnforcers: loadEvalEnforcers,
+    });
+    return emitReply(reply.stdout, reply.stderr, reply.exitCode);
+}
+function emitReply(stdout, stderr, exitCode) {
+    if (stdout !== "") {
+        process.stdout.write(stdout);
+    }
+    if (stderr !== "") {
+        process.stderr.write(stderr);
+    }
+    return exitCode;
+}
+// SPEC §4.19.3: hook runtime entry; an uncaught error becomes a block. The
+// reply goes to stdout verbatim (the harness parses it; golden EC-14 pins
+// stdout exactly), diagnostics to stderr, and the harness exit code returns.
+// Nothing reads the disk before the runtime resolves the repo root, so
+// unknown harnesses and empty payloads answer without I/O.
+export async function runHook(options) {
+    const harness = options.argv[1] ?? "";
+    const event = options.argv[2] ?? "";
+    const version = options.nodeVersion ?? process.version;
+    if (nodeMajor(version) < MIN_NODE_MAJOR) {
+        return oldNodeExit(harness, version);
+    }
+    const ports = {
+        proc: new NodeProc(),
+        net: new NodeNet(),
+        clock: new SystemClock(),
+        env: new NodeEnv(),
+    };
+    const append = (root, line) => appendLine(root, line, ports);
+    return invokeHookEvent(harness, event, options.stdinText, options.cwd, ports, append, options.engineVersion ?? ENGINE_VERSION);
+}
+function scanGlobals(argv, cwd) {
+    let json = false;
+    let quiet = false;
+    let help = false;
+    let override;
+    const rest = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index] ?? "";
+        if (token === "--json") {
+            json = true;
+        }
+        else if (token === "--quiet") {
+            quiet = true;
+        }
+        else if (token === "--help" || token === "-h") {
+            help = true;
+        }
+        else if (token === "--cwd") {
+            const next = argv[index + 1];
+            if (next === undefined) {
+                return undefined;
+            }
+            override = next;
+            index += 1;
+        }
+        else if (token.startsWith("--cwd=")) {
+            override = token.slice("--cwd=".length);
+        }
+        else {
+            rest.push(token);
+        }
+    }
+    return { json, quiet, cwd: override ?? cwd, help, rest };
+}
+// SPEC §4.19 + §8.2: the command entry. The node floor fails as CDX-E002
+// (exit 6); unknown commands or flags are usage errors (exit 2, no code).
+async function runCommandImpl(options) {
+    const version = options.nodeVersion ?? process.version;
+    if (nodeMajor(version) < MIN_NODE_MAJOR) {
+        process.stderr.write(`${nodeTooOldMessage(version)}\n`);
+        return err({
+            code: "CDX-E002",
+            message: nodeTooOldMessage(version),
+            remediation: "Install a newer Node, then retry the tool call.",
+        });
+    }
+    const globals = scanGlobals(options.argv, options.cwd);
+    if (globals === undefined) {
+        return usageError(USAGE);
+    }
+    if (globals.help) {
+        printHuman(USAGE, globals.quiet);
+        return ok(0);
+    }
+    if (globals.rest.length === 0) {
+        return usageError(USAGE);
+    }
+    const [command, ...args] = globals.rest;
+    const handler = COMMANDS[command];
+    if (handler === undefined) {
+        return usageError(`${USAGE}\nunknown command "${command}"`);
+    }
+    return handler({
+        args,
+        json: globals.json,
+        quiet: globals.quiet,
+        cwd: globals.cwd,
+        nodeVersion: options.nodeVersion,
+        stdinText: undefined,
+        engineVersion: options.engineVersion ?? ENGINE_VERSION,
+    });
+}
+// SPEC §4.19: command dispatch (init, regen, verify, task, review, ...).
+// The hook word routes back through the hook runtime; every other word
+// goes through the command table in commands.ts. The hook reply is already emitted
+// by runHook, so its harness exit code passes through as the value.
+export function runCommand(options) {
+    if (options.argv[0] === "hook") {
+        return runHook(options).then((exitCode) => ({ ok: true, value: exitCode }));
+    }
+    return runCommandImpl(options);
+}
+// SPEC §7.15 + §4.19.5: stdio server entry for the vscode extension. The
+// loop serves one NDJSON session on this process's stdio; commands run
+// through the same table with per-call output capture (see serve-run.ts),
+// so frames stay the only stdout bytes. A closed stdin (no piped client)
+// exits 0 without serving.
+export function runServer(options) {
+    return startStdioServer(options, runCommand);
+}

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

@@ -0,0 +1,23 @@
+import type { Result } from "../kernel/index.ts";
+import { guardrailPlan } from "./plan.ts";
+import type { CommandRequest } from "./shared.ts";
+export interface InitFlags {
+    readonly harnesses: Array<string>;
+    readonly profile: string;
+    readonly packs: Array<string>;
+    readonly tools: Array<{
+        role: string;
+        command: string;
+        pin: string;
+    }>;
+    readonly repair: boolean;
+}
+export declare function ensureBaseline(root: string, req: CommandRequest): Promise<Result<boolean>>;
+export declare function defaultHarnesses(flags: InitFlags): Array<string>;
+export declare function reportExisting(req: CommandRequest, root: string): Result<number>;
+export declare function checkFreshConfig(root: string, req: CommandRequest): Promise<Result<number>>;
+export declare function emitInitResult(req: CommandRequest, root: string, written: ReadonlyArray<{
+    path: string;
+}>, baselineWritten: boolean): Result<number>;
+export declare function initPreamble(req: CommandRequest): Promise<string | Result<number>>;
+export declare function buildGuardrailPlan(root: string, flags: InitFlags, planned: ReadonlyArray<string>, engineVersion?: string): Promise<ReturnType<typeof guardrailPlan>>;

package/dist/cli/init-plan.js

@@ -0,0 +1,135 @@
+// SPEC §4.13.1 + §4.14.1: init execution. Split from the init command
+// (init.ts) by responsibility: flag parsing stays on the command, module
+// detection, baseline, guards and plan assembly live here.
+import { CODICTATOR_MODULES } from "../features/arch/index.js";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { captureBaseline } from "../features/remediation/index.js";
+import { ok, parseJson, resolveRepoRoot, stableStringify, } from "../kernel/index.js";
+import { buildHelperTool, guardrailPlan } from "./plan.js";
+import { checkHuman, commandEnv, fail, loadRepoConfig, printHuman, printJson, readStateText, writeStateText, } from "./shared.js";
+// SPEC §4.19.2: a helper tool proposal names the helper role, the binary
+// and the exact pin from the human's registry lookup: role=command@pin.
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// SPEC §4.11.2 + §3.3: on the Codictator repo itself, init proposes the
+// canonical module map the arch guard dogfoods (profiles.ts), rewritten to
+// repo-relative paths. Any other repo gets no modules; the human adds them.
+async function detectCodictatorModules(root) {
+    const text = await readStateText(root, "packages/codictator/package.json");
+    if (text === undefined) {
+        return undefined;
+    }
+    const parsed = parseJson(text);
+    if (!parsed.ok || !isRecord(parsed.value)) {
+        return undefined;
+    }
+    const nameKey = "name";
+    if (parsed.value[nameKey] !== "codictator") {
+        return undefined;
+    }
+    return CODICTATOR_MODULES.map((mod) => ({
+        name: mod.name,
+        path: `packages/codictator/${mod.path}`,
+        ...(mod.kind === undefined ? {} : { kind: mod.kind }),
+        ...(mod.entry === undefined ? {} : { entry: mod.entry }),
+        dependsOn: [...mod.dependsOn],
+    }));
+}
+// SPEC §4.13.1 step 3: init captures the baseline. On a greenfield repo the
+// first verify has no findings, so the capture is the empty ratchet. An
+// existing baseline (repair, L3 tighten, capture) is never overwritten.
+export async function ensureBaseline(root, req) {
+    const existing = await readStateText(root, ".codictator/baseline.json");
+    if (existing !== undefined) {
+        return ok(false);
+    }
+    const captured = await captureBaseline(root, []);
+    if (!captured.ok) {
+        return fail("CDX-E903", captured.error.message, captured.error.remediation, req.json);
+    }
+    const saved = await writeStateText(root, ".codictator/baseline.json", `${stableStringify(captured.value)}\n`);
+    if (!saved.ok) {
+        return fail("CDX-E903", saved.error.message, saved.error.remediation, req.json);
+    }
+    return ok(true);
+}
+// SPEC §4.19.2: init harnesses default to every known adapter id when no
+// --harness flag is given; unknown ids fail as CDX-E301 via config
+// validation, never silently.
+const DEFAULT_HARNESSES = [
+    "muse-code",
+    "universal",
+    "claude-code",
+    "copilot",
+    "codex-cli",
+    "cursor",
+    "gemini-cli",
+    "opencode",
+];
+export function defaultHarnesses(flags) {
+    return flags.harnesses.length > 0 ? flags.harnesses : [...DEFAULT_HARNESSES];
+}
+export function reportExisting(req, root) {
+    printHuman("already a Codictator repo; rerun with --repair to regenerate", req.quiet);
+    if (req.json) {
+        printJson({ initialized: false, reason: "exists", root });
+    }
+    return ok(0);
+}
+export async function checkFreshConfig(root, req) {
+    const fresh = await loadRepoConfig(root, undefined, req.engineVersion ?? ENGINE_VERSION);
+    if (!fresh.ok) {
+        return fail("CDX-E901", fresh.error.message, "Rerun codictator init --repair; report the mismatch.", req.json, fresh.error.detail);
+    }
+    return ok(0);
+}
+export function emitInitResult(req, root, written, baselineWritten) {
+    const files = baselineWritten === false
+        ? written
+        : [...written, { path: ".codictator/baseline.json" }];
+    if (req.json) {
+        printJson({
+            initialized: true,
+            root,
+            files: files.map((entry) => entry.path),
+        });
+    }
+    else {
+        for (const entry of files) {
+            printHuman(`wrote ${entry.path}`, req.quiet);
+        }
+        printHuman("init: run npm ci, then codictator install-hooks", req.quiet);
+    }
+    return ok(0);
+}
+export async function initPreamble(req) {
+    const human = checkHuman(commandEnv(), []);
+    if (!human.ok) {
+        return fail("CDX-E107", human.error.message, human.error.remediation, req.json);
+    }
+    const root = await resolveRepoRoot(req.cwd);
+    if (!root.ok) {
+        return fail("CDX-E703", root.error.message, root.error.remediation, req.json);
+    }
+    return root.value;
+}
+// The plan assembly handleInit writes: read-only inputs in, GuardrailPlan
+// out. Writing stays on the command so the plan builder never touches
+// the disk.
+export async function buildGuardrailPlan(root, flags, planned, engineVersion = ENGINE_VERSION) {
+    const agents = await readStateText(root, "AGENTS.md");
+    const repoName = root.replaceAll("\\", "/").split("/").pop() ?? "repo";
+    const modules = await detectCodictatorModules(root);
+    const architecture = modules === undefined
+        ? undefined
+        : {
+            ...(flags.profile === "" ? {} : { profile: flags.profile }),
+            modules,
+        };
+    return guardrailPlan(planned, flags.profile, repoName, agents, {
+        packs: flags.packs.map((id) => ({ id, version: engineVersion })),
+        tools: flags.tools.map((tool) => buildHelperTool(tool)),
+        ...(architecture === undefined ? {} : { architecture }),
+    }, engineVersion);
+}

package/dist/cli/init.d.ts

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

package/dist/cli/init.js

@@ -0,0 +1,122 @@
+// SPEC §4.19.2 + §4.13.1: human-only adoption. Writes config, steering
+// block, manifest, CI workflow, hooks and launcher; existing config needs
+// --repair, unknown harnesses fail as CDX-E301 via validation.
+import { parseArgs } from "node:util";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { isBuiltinPackId } from "../features/packs/index.js";
+import { buildGuardrailPlan, checkFreshConfig, defaultHarnesses, emitInitResult, ensureBaseline, initPreamble, reportExisting, } from "./init-plan.js";
+import { KNOWN_HELPER_ROLES, writePlan } from "./plan.js";
+import { fail, readStateText, usageError } from "./shared.js";
+const KNOWN_PROFILES = new Set([
+    "app",
+    "library",
+    "cli",
+    "service",
+]);
+function parseToolSpec(spec) {
+    const eq = spec.indexOf("=");
+    if (eq < 0) {
+        return undefined;
+    }
+    const role = spec.slice(0, eq).trim();
+    const rest = spec.slice(eq + 1);
+    const at = rest.lastIndexOf("@");
+    if (at < 0) {
+        return undefined;
+    }
+    const command = rest.slice(0, at).trim();
+    const pin = rest.slice(at + 1).trim();
+    if (!KNOWN_HELPER_ROLES.has(role) || command === "" || pin === "") {
+        return undefined;
+    }
+    return { role, command, pin };
+}
+function narrowInitProfile(profile) {
+    if (profile !== undefined && profile !== "" && !KNOWN_PROFILES.has(profile)) {
+        return undefined;
+    }
+    return profile ?? "";
+}
+function narrowInitPacks(packs) {
+    const ids = [...(packs ?? [])];
+    if (ids.some((id) => !isBuiltinPackId(id))) {
+        return undefined;
+    }
+    return ids;
+}
+function narrowInitTools(specs) {
+    const tools = [];
+    for (const spec of specs ?? []) {
+        const tool = parseToolSpec(spec);
+        if (tool === undefined) {
+            return undefined;
+        }
+        tools.push(tool);
+    }
+    return tools;
+}
+function parseInitFlags(args) {
+    try {
+        const parsed = parseArgs({
+            args: [...args],
+            options: {
+                harness: { type: "string", multiple: true, default: [] },
+                profile: { type: "string", default: "" },
+                pack: { type: "string", multiple: true, default: [] },
+                tool: { type: "string", multiple: true, default: [] },
+                repair: { type: "boolean", default: false },
+            },
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return undefined;
+        }
+        const profile = narrowInitProfile(parsed.values.profile);
+        const packs = narrowInitPacks(parsed.values.pack);
+        const tools = narrowInitTools(parsed.values.tool);
+        if (profile === undefined || packs === undefined || tools === undefined) {
+            return undefined;
+        }
+        return {
+            harnesses: [...(parsed.values.harness ?? [])],
+            profile,
+            packs,
+            tools,
+            repair: parsed.values.repair ?? false,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+const INIT_USAGE = "usage: codictator init [--harness <id> ...] [--profile <app|library|cli|service>] [--pack <id> ...] [--tool <role>=<command>@<pin> ...] [--repair]";
+export async function handleInit(req) {
+    const flags = parseInitFlags(req.args);
+    if (flags === undefined) {
+        return usageError(INIT_USAGE);
+    }
+    const root = await initPreamble(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    const planned = defaultHarnesses(flags);
+    const engineVersion = req.engineVersion ?? ENGINE_VERSION;
+    const existing = await readStateText(root, ".codictator/config.json");
+    if (existing !== undefined && !flags.repair) {
+        return reportExisting(req, root);
+    }
+    const plan = await buildGuardrailPlan(root, flags, planned, engineVersion);
+    const wrote = await writePlan(root, plan, engineVersion);
+    if (!wrote.ok) {
+        return fail("CDX-E903", wrote.error.message, wrote.error.remediation, req.json);
+    }
+    const fresh = await checkFreshConfig(root, req);
+    if (!fresh.ok) {
+        return fresh;
+    }
+    const baseline = await ensureBaseline(root, req);
+    if (!baseline.ok) {
+        return fail(baseline.error.code, baseline.error.message, baseline.error.remediation, req.json);
+    }
+    return emitInitResult(req, root, wrote.value, baseline.value);
+}