codictator 0.1.3 → 0.2.1

package/dist/cli/commands.d.ts

@@ -2,4 +2,4 @@ import type { Result } from "../kernel/index.ts";
 import type { CommandRequest } from "./shared.ts";
 export type Handler = (req: CommandRequest) => Promise<Result<number>>;
 export declare const COMMANDS: Readonly<Record<string, Handler>>;
-export declare const USAGE = "usage: codictator <init|install-hooks|regen|uninstall|verify|status|explain|replay|report|context|hook|task|test|review|waive|baseline|deps|remediate|ci|generate|pack|adapter|serve> [--json] [--cwd <path>] [--quiet]";
+export declare const USAGE = "usage: codictator <init|setup|install-hooks|regen|uninstall|verify|status|explain|replay|report|context|hook|task|test|review|waive|baseline|deps|remediate|ci|generate|pack|adapter|serve> [--json] [--cwd <path>] [--quiet]";

package/dist/cli/commands.js

@@ -9,11 +9,13 @@ import { handleReview } from "./proofs.js";
 import { handleTestCmd } from "./proofs-test.js";
 import { handleRemediate } from "./remediation.js";
 import { handleContext, handleReport } from "./report.js";
+import { handleSetup } from "./setup.js";
 import { handleTask } from "./task-advance.js";
 import { handleExplain, handleReplay } from "./transparency.js";
 import { handleWaive } from "./waivers.js";
 export const COMMANDS = {
     init: handleInit,
+    setup: handleSetup,
     "install-hooks": handleInstallHooks,
     regen: handleRegen,
     uninstall: handleUninstall,
@@ -36,4 +38,4 @@ export const COMMANDS = {
     adapter: handleAdapter,
     serve: handleServe,
 };
-export const USAGE = "usage: codictator <init|install-hooks|regen|uninstall|verify|status|explain|replay|report|context|hook|task|test|review|waive|baseline|deps|remediate|ci|generate|pack|adapter|serve> [--json] [--cwd <path>] [--quiet]";
+export const USAGE = "usage: codictator <init|setup|install-hooks|regen|uninstall|verify|status|explain|replay|report|context|hook|task|test|review|waive|baseline|deps|remediate|ci|generate|pack|adapter|serve> [--json] [--cwd <path>] [--quiet]";

package/dist/cli/guardrail.d.ts

@@ -1,5 +1,7 @@
 import type { Result } from "../kernel/index.ts";
 import type { CommandRequest } from "./shared.ts";
 export declare function handleRegen(req: CommandRequest): Promise<Result<number>>;
+export declare function writeHookFiles(root: string): Promise<Result<true>>;
+export declare function configureHooksPath(root: string, req: CommandRequest): Promise<void>;
 export declare function handleInstallHooks(req: CommandRequest): Promise<Result<number>>;
 export declare function handleUninstall(req: CommandRequest): Promise<Result<number>>;

package/dist/cli/guardrail.js

@@ -3,12 +3,13 @@
 // 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 { renderCustomRegenFragment, withCodictatorOwner, } 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 { initPreamble } from "./init-plan.js";
 import { guardrailPlan, writePlan } from "./plan.js";
-import { checkHuman, commandEnv, fail, loadRepoConfig, portsFor, printHuman, printJson, readStateText, usageError, } from "./shared.js";
+import { fail, loadRepoConfig, portsFor, printHuman, printJson, readStateText, usageError, } from "./shared.js";
 function repoNameOf(root) {
     return root.replaceAll("\\", "/").split("/").pop() ?? "repo";
 }
@@ -67,8 +68,12 @@ export async function handleRegen(req) {
         tunables: configured.tunables,
         architecture: configured.architecture,
         tools: configured.tools,
+    }, req.engineVersion ?? ENGINE_VERSION, root.value);
+    // SPEC §4.14.1: custom fragments keep the historical codictator owner.
+    const customOwned = withCodictatorOwner(customFiles.value);
+    const wrote = await writePlan(root.value, {
+        files: [...plan.files, ...customOwned],
     }, 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);
     }
@@ -89,7 +94,7 @@ export async function handleRegen(req) {
 function encode(text) {
     return new TextEncoder().encode(text);
 }
-async function writeHookFiles(root) {
+export async function writeHookFiles(root) {
     const ports = await portsFor(root);
     if (!ports.ok) {
         return err(ports.error);
@@ -107,7 +112,7 @@ async function writeHookFiles(root) {
     }
     return ok(true);
 }
-async function configureHooksPath(root, req) {
+export async function configureHooksPath(root, req) {
     const ports = await portsFor(root);
     if (!ports.ok) {
         return;
@@ -169,21 +174,18 @@ export async function handleUninstall(req) {
     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 preamble = await initPreamble(req);
+    if (typeof preamble !== "string") {
+        return preamble;
     }
-    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 root = preamble;
+    await removeGuardrails(root);
     const note = "CI will fail until its workflow and required check are removed too.";
     if (req.json) {
-        printJson({ uninstalled: true, root: root.value, note });
+        printJson({ uninstalled: true, root, note });
     }
     else {
-        printHuman(`uninstalled guardrails from ${root.value}`, req.quiet);
+        printHuman(`uninstalled guardrails from ${root}`, req.quiet);
         printHuman(note, req.quiet);
     }
     return ok(0);

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

@@ -20,4 +20,11 @@ export declare function emitInitResult(req: CommandRequest, root: string, writte
     path: string;
 }>, baselineWritten: boolean): Result<number>;
 export declare function initPreamble(req: CommandRequest): Promise<string | Result<number>>;
+export interface InitSequence {
+    readonly written: ReadonlyArray<{
+        path: string;
+    }>;
+    readonly baseline: boolean;
+}
+export declare function runInitSequence(root: string, req: CommandRequest, flags: InitFlags, planned: ReadonlyArray<string>, engineVersion: string): Promise<Result<InitSequence>>;
 export declare function buildGuardrailPlan(root: string, flags: InitFlags, planned: ReadonlyArray<string>, engineVersion?: string): Promise<ReturnType<typeof guardrailPlan>>;

package/dist/cli/init-plan.js

@@ -4,8 +4,8 @@
 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 { err, ok, parseJson, resolveRepoRoot, stableStringify, } from "../kernel/index.js";
+import { buildHelperTool, guardrailPlan, writePlan } 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.
@@ -114,6 +114,25 @@ export async function initPreamble(req) {
     }
     return root.value;
 }
+// SPEC §4.13.1: the shared write-then-guard tail of the init path: plan,
+// write, fresh-config guard, baseline guard. init and setup run the same
+// tail; one helper owns it.
+export async function runInitSequence(root, req, flags, planned, engineVersion) {
+    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 err(fresh.error);
+    }
+    const baseline = await ensureBaseline(root, req);
+    if (!baseline.ok) {
+        return fail(baseline.error.code, baseline.error.message, baseline.error.remediation, req.json);
+    }
+    return ok({ written: wrote.value, baseline: baseline.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.

package/dist/cli/init.d.ts

@@ -1,3 +1,5 @@
 import type { Result } from "../kernel/index.ts";
+import { type InitFlags } from "./init-plan.ts";
 import type { CommandRequest } from "./shared.ts";
+export declare function parseInitFlags(args: ReadonlyArray<string>): InitFlags | undefined;
 export declare function handleInit(req: CommandRequest): Promise<Result<number>>;

package/dist/cli/init.js

@@ -4,9 +4,9 @@
 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";
+import { defaultHarnesses, emitInitResult, initPreamble, reportExisting, runInitSequence, } from "./init-plan.js";
+import { KNOWN_HELPER_ROLES } from "./plan.js";
+import { readStateText, usageError } from "./shared.js";
 const KNOWN_PROFILES = new Set([
     "app",
     "library",
@@ -55,7 +55,7 @@ function narrowInitTools(specs) {
     }
     return tools;
 }
-function parseInitFlags(args) {
+export function parseInitFlags(args) {
     try {
         const parsed = parseArgs({
             args: [...args],
@@ -105,18 +105,9 @@ export async function handleInit(req) {
     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 sequenced = await runInitSequence(root, req, flags, planned, engineVersion);
+    if (!sequenced.ok) {
+        return sequenced;
     }
-    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);
+    return emitInitResult(req, root, sequenced.value.written, sequenced.value.baseline);
 }

package/dist/cli/plan.d.ts

@@ -10,6 +10,8 @@ export interface GuardrailPlan {
     readonly files: ReadonlyArray<{
         path: string;
         content: string;
+        owner: string;
+        mode: "file";
     }>;
 }
 export interface PlanExtras {
@@ -18,7 +20,7 @@ export interface PlanExtras {
     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 guardrailPlan(harnesses: ReadonlyArray<string>, profile: string, repoName: string, existingAgents: string | undefined, extras?: PlanExtras, engineVersion?: string, root?: string): GuardrailPlan;
 export declare function writePlan(root: string, plan: GuardrailPlan, engineVersion?: string): Promise<Result<Array<{
     path: string;
     hash: string;

package/dist/cli/plan.js

@@ -1,6 +1,7 @@
 // SPEC §4.14.1 + §4.14.5: guardrail plan builders. The file list (config,
 // steering block, CI workflow, hooks, launcher) and the manifest write are
 // shared by init and regen, so regeneration stays byte-identical.
+import { renderHarnessFiles } from "../features/adapters/index.js";
 import { renderWorkflow } from "../features/ci/index.js";
 import { ENGINE_VERSION } from "../features/config/index.js";
 import { buildManifest, EXPECTED_HOOKS_PATH, HOOK_NAMES, hookInstallPlan, renderHookScript, } from "../features/integrity/index.js";
@@ -65,30 +66,65 @@ function withManagedBlock(existing) {
     const after = end + MANAGED_END.length;
     return `${existing.slice(0, start)}${block}${existing.slice(after)}`;
 }
-export function guardrailPlan(harnesses, profile, repoName, existingAgents, extras = {}, engineVersion = ENGINE_VERSION) {
+export function guardrailPlan(harnesses, profile, repoName, existingAgents, extras = {}, engineVersion = ENGINE_VERSION, root = ".") {
     const files = [];
     files.push({
         path: ".codictator/config.json",
         content: configText(harnesses, profile, extras, engineVersion),
+        owner: "codictator",
+        mode: "file",
+    });
+    files.push({
+        path: "AGENTS.md",
+        content: withManagedBlock(existingAgents),
+        owner: "codictator",
+        mode: "file",
     });
-    files.push({ path: "AGENTS.md", content: withManagedBlock(existingAgents) });
     const workflow = renderWorkflow(repoName);
     files.push({
         path: ".github/workflows/codictator.yml",
         content: workflow.text ?? "",
+        owner: "codictator",
+        mode: "file",
     });
     for (const hook of HOOK_NAMES) {
         files.push({
             path: `${EXPECTED_HOOKS_PATH}/${hook}`,
             content: renderHookScript(hook),
+            owner: "codictator",
+            mode: "file",
         });
     }
     const plan = hookInstallPlan({});
     files.push({
         path: `${EXPECTED_HOOKS_PATH}/.gitattributes`,
         content: plan.gitattributes,
+        owner: "codictator",
+        mode: "file",
+    });
+    files.push({
+        path: ".codictator/bin/run.mjs",
+        content: LAUNCHER_TEXT,
+        owner: "codictator",
+        mode: "file",
     });
-    files.push({ path: ".codictator/bin/run.mjs", content: LAUNCHER_TEXT });
+    // SPEC §4.13.1 step 2 + §4.5: every configured built-in harness owns
+    // its rendered files; universal renders nothing, custom:* stays with
+    // renderCustomHarnessFiles. Renders ignore the input, so the "." default
+    // keeps the init path working unchanged. SPEC §4.6.2 + core/guardrail-manifest:
+    // one row per path, first occurrence wins: base files go first so the
+    // plan's managed AGENTS.md beats any harness-rendered AGENTS.md, then
+    // harness files follow in sorted harness-id order, skipping paths
+    // already emitted (cursor/gemini-cli AGENTS.md, codex-cli/muse-code
+    // .agents/skills overlap), so writePlan writes each path once.
+    const seen = new Set(files.map((entry) => entry.path));
+    const sortedHarnesses = [...new Set(harnesses)].sort();
+    for (const artifact of renderHarnessFiles(sortedHarnesses, root)) {
+        if (!seen.has(artifact.path)) {
+            seen.add(artifact.path);
+            files.push({ ...artifact, mode: "file" });
+        }
+    }
     return { files };
 }
 export async function writePlan(root, plan, engineVersion = ENGINE_VERSION) {
@@ -107,12 +143,15 @@ export async function writePlan(root, plan, engineVersion = ENGINE_VERSION) {
             hash: sha256Text(normalizeText(file.content)),
         });
     }
-    const manifest = buildManifest(engineVersion, written.map((entry) => ({
-        path: entry.path,
-        owner: "codictator",
-        mode: "file",
-        hash: entry.hash,
-    })));
+    const manifest = buildManifest(engineVersion, written.map((entry, index) => {
+        const planned = plan.files[index];
+        return {
+            path: entry.path,
+            owner: planned === undefined ? "codictator" : planned.owner,
+            mode: planned === undefined ? "file" : planned.mode,
+            hash: entry.hash,
+        };
+    }));
     const saved = await ports.value.fs.write(".codictator/manifest.json", encode(`${stableStringify(manifest)}\n`));
     if (!saved.ok) {
         return err(saved.error);

package/dist/cli/serve-run.js

@@ -6,6 +6,7 @@ import { exitFor } from "./shared.js";
 // these before invoking anything.
 const ALWAYS_HUMAN = new Set([
     "init",
+    "setup",
     "uninstall",
     "waive",
 ]);

package/dist/cli/setup-gitignore.d.ts

@@ -0,0 +1,7 @@
+import type { Result } from "../kernel/index.ts";
+import type { SetupStep } from "./setup.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function ensureGitignoreEntries(root: string): Promise<Result<{
+    added: Array<string>;
+}>>;
+export declare function setupGitignoreStep(req: CommandRequest, root: string, steps: Array<SetupStep>): Promise<Result<number>>;

package/dist/cli/setup-gitignore.js

@@ -0,0 +1,41 @@
+import { err, ok } from "../kernel/index.js";
+import { fail, printHuman, readStateText, writeStateText } from "./shared.js";
+const SETUP_GITIGNORE_ENTRIES = [
+    ".codictator/state/",
+    ".codictator/cache/",
+    ".codictator/tool/node_modules/",
+];
+export async function ensureGitignoreEntries(root) {
+    const existing = await readStateText(root, ".gitignore");
+    const present = new Set((existing ?? "").split("\n").map((line) => line.trim()));
+    const missing = SETUP_GITIGNORE_ENTRIES.filter((entry) => !present.has(entry));
+    if (missing.length === 0) {
+        return ok({ added: [] });
+    }
+    const base = existing === undefined || existing === ""
+        ? ""
+        : existing.endsWith("\n")
+            ? existing
+            : `${existing}\n`;
+    const saved = await writeStateText(root, ".gitignore", `${base}${missing.join("\n")}\n`);
+    if (!saved.ok) {
+        return err(saved.error);
+    }
+    return ok({ added: [...missing] });
+}
+// SPEC §4.19.6 step 3: guarantee the manifest-owned .gitignore entries.
+export async function setupGitignoreStep(req, root, steps) {
+    const ensured = await ensureGitignoreEntries(root);
+    if (!ensured.ok) {
+        return fail("CDX-E903", ensured.error.message, ensured.error.remediation, req.json);
+    }
+    steps.push({
+        step: "gitignore",
+        ok: true,
+        detail: { added: ensured.value.added },
+    });
+    if (ensured.value.added.length > 0) {
+        printHuman(`setup: added ${String(ensured.value.added.length)} .gitignore entries`, req.quiet);
+    }
+    return ok(0);
+}

package/dist/cli/setup-handoff.d.ts

@@ -0,0 +1,7 @@
+import type { InitFlags } from "./init-plan.ts";
+export declare const SETUP_EXTENSION_ID = "codictator.codictator-vscode";
+export declare const SETUP_EXTENSION_INSTALL = "code --install-extension codictator.codictator-vscode";
+export declare const SETUP_PACK_REPAIR = "npx codictator setup --repair --pack typescript";
+export declare const SETUP_PACK_FRESH = "npx codictator setup --pack typescript";
+export declare function setupHandoffLines(emptyPacks: boolean): Array<string>;
+export declare function hasEffectivePacks(root: string, flags: InitFlags): Promise<boolean>;

package/dist/cli/setup-handoff.js

@@ -0,0 +1,44 @@
+// SPEC §4.19.6 step 8: pack-less handoff text. Split from setup.ts
+// (orchestration) by responsibility so setup.ts stays below the
+// core/file-size 300 cap; the effective pack list mirrors the plan data.
+import { parseJson } from "../kernel/index.js";
+import { readStateText } from "./shared.js";
+// The extension empty-state lives on the vscode branch (§4.20.1);
+// handoff here only prints the install command.
+export const SETUP_EXTENSION_ID = "codictator.codictator-vscode";
+export const SETUP_EXTENSION_INSTALL = "code --install-extension codictator.codictator-vscode";
+export const SETUP_PACK_REPAIR = "npx codictator setup --repair --pack typescript";
+export const SETUP_PACK_FRESH = "npx codictator setup --pack typescript";
+export function setupHandoffLines(emptyPacks) {
+    if (!emptyPacks) {
+        return [
+            "setup complete: open this folder in VS Code to see the Codictator views",
+            `extension: ${SETUP_EXTENSION_INSTALL}`,
+        ];
+    }
+    return [
+        "Setup complete — core rules only. No language packs installed.",
+        "To add a language pack, run exactly one line and press Enter:",
+        `  ${SETUP_PACK_REPAIR}`,
+        "To install the VS Code extension, run:",
+        `  ${SETUP_EXTENSION_INSTALL}`,
+        `Fresh adoption omits --repair: ${SETUP_PACK_FRESH}`,
+    ];
+}
+// SPEC §4.19.6 step 8: the effective pack list mirrors the plan data:
+// explicit --pack flags win, otherwise the written config owns it.
+export async function hasEffectivePacks(root, flags) {
+    if (flags.packs.length > 0) {
+        return true;
+    }
+    const text = await readStateText(root, ".codictator/config.json");
+    if (text === undefined) {
+        return false;
+    }
+    const parsed = parseJson(text);
+    if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null) {
+        return false;
+    }
+    const packs = parsed.value.packs;
+    return Array.isArray(packs) && packs.length > 0;
+}

package/dist/cli/setup-install.d.ts

@@ -0,0 +1,11 @@
+import type { Result } from "../kernel/index.ts";
+import type { SetupStep } from "./setup.ts";
+import type { CommandRequest } from "./shared.ts";
+export interface SetupInstallTarget {
+    readonly dir: string;
+    readonly lockRel: string;
+    readonly dirRel: string;
+}
+export declare function setupInstallLayout(req: CommandRequest, root: string, steps: Array<SetupStep>): Promise<Result<SetupInstallTarget>>;
+export declare function setupNpmArgv(platform?: string, execPath?: string): ReadonlyArray<string>;
+export declare function setupInstallHere(req: CommandRequest, root: string, target: SetupInstallTarget, steps: Array<SetupStep>): Promise<Result<number>>;

package/dist/cli/setup-install.js

@@ -0,0 +1,84 @@
+// SPEC §4.19.4 + §4.19.6 steps 4-5: the engine install layout and the
+// clean install here. npm repos install at the root; other repos get
+// .codictator/tool/package.json pinning the engine exactly, then npm ci
+// runs in the directory owning the lockfile. A registry or network outage
+// maps to CDX-E401 (exit 5); any other install failure is a missing
+// engine, CDX-E003 (exit 6).
+import path from "node:path";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { err, ok, stableStringify } from "../kernel/index.js";
+import { fail, portsFor, printHuman, readStateText, writeStateText, } from "./shared.js";
+export async function setupInstallLayout(req, root, steps) {
+    const rootManifest = await readStateText(root, "package.json");
+    if (rootManifest !== undefined) {
+        steps.push({ step: "install", ok: true, detail: { dir: "." } });
+        return ok({ dir: root, lockRel: "package-lock.json", dirRel: "." });
+    }
+    const toolManifest = await readStateText(root, ".codictator/tool/package.json");
+    if (toolManifest === undefined) {
+        const engineVersion = req.engineVersion ?? ENGINE_VERSION;
+        const saved = await writeStateText(root, ".codictator/tool/package.json", `${stableStringify({
+            name: "codictator-tool",
+            private: true,
+            dependencies: { codictator: engineVersion },
+        })}\n`);
+        if (!saved.ok) {
+            return err(saved.error);
+        }
+    }
+    steps.push({
+        step: "install",
+        ok: true,
+        detail: { dir: ".codictator/tool" },
+    });
+    return ok({
+        dir: `${root}/.codictator/tool`,
+        lockRel: ".codictator/tool/package-lock.json",
+        dirRel: ".codictator/tool",
+    });
+}
+function looksLikeRegistryOutage(output) {
+    return /ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ECONNRESET|ECONNREFUSED|registry/i.test(output);
+}
+// SPEC §4.1.1: the child spawns with shell:false always, so on win32 the
+// bare `npm` shim never resolves: it is an npm.cmd batch file, which the
+// shell-less spawn cannot execute (ENOENT without, EINVAL with, the
+// extension). The fix stays shell-free by exec'ing the real entry beside
+// the running node: node <node-dir>/node_modules/npm/bin/npm-cli.js ci.
+// POSIX keeps `npm` from PATH. Pure in platform and execPath so tests pin
+// the exact proc argv without spawning anything.
+export function setupNpmArgv(platform = process.platform, execPath = process.execPath) {
+    if (platform !== "win32") {
+        return ["npm", "ci"];
+    }
+    return [
+        execPath,
+        path.join(path.dirname(execPath), "node_modules", "npm", "bin", "npm-cli.js"),
+        "ci",
+    ];
+}
+export async function setupInstallHere(req, root, target, steps) {
+    const lock = await readStateText(root, target.lockRel);
+    if (lock === undefined) {
+        return fail("CDX-E003", `no lockfile at ${target.lockRel}, so npm ci cannot run`, `Run npm install in ${target.dirRel} (needs network access), then rerun codictator setup.`, req.json);
+    }
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return fail("CDX-E903", ports.error.message, ports.error.remediation, req.json);
+    }
+    const ran = await ports.value.proc.run(setupNpmArgv(), {
+        cwd: target.dir,
+        env: {},
+        timeoutMs: 300000,
+        maxOutputBytes: 4 * 1024 * 1024,
+    });
+    if (!ran.timedOut && !ran.truncated && ran.code === 0) {
+        steps.push({ step: "install-here", ok: true });
+        printHuman(`setup: npm ci passed in ${target.dirRel}`, req.quiet);
+        return ok(0);
+    }
+    if (ran.timedOut || looksLikeRegistryOutage(`${ran.stdout}\n${ran.stderr}`)) {
+        return fail("CDX-E401", "registry or network unavailable during install", "Retry with network access, then rerun codictator setup.", req.json);
+    }
+    return fail("CDX-E003", `engine install failed in ${target.dirRel} (npm ci exit ${String(ran.code)})`, `Run npm ci in ${target.dirRel}, then rerun codictator setup.`, req.json);
+}

package/dist/cli/setup.d.ts

@@ -0,0 +1,9 @@
+import type { Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare const SETUP_USAGE = "usage: codictator setup [--harness <id> ...] [--profile <app|library|cli|service>] [--pack <id> ...] [--tool <role>=<command>@<pin> ...] [--repair]";
+export interface SetupStep {
+    readonly step: string;
+    readonly ok: boolean;
+    readonly detail?: Record<string, unknown>;
+}
+export declare function handleSetup(req: CommandRequest): Promise<Result<number>>;