codictator 0.1.2 → 0.2.0

package/dist/builtin-packs/core/fixtures/conventional-commit/passing/basic/case.json

@@ -5,6 +5,6 @@
 	"trigger": "commit subject with no type prefix",
 	"expectRules": [],
 	"files": {
-		"commit.txt": "subject: fix(core): drop dead export\n"
+		"sample.txt": "subject: fix(core): drop dead export\n"
 	}
 }

package/dist/builtin-packs/core/fixtures/conventional-commit/violating/basic/case.json

@@ -5,6 +5,6 @@
 	"trigger": "commit subject with no type prefix",
 	"expectRules": ["core/conventional-commit"],
 	"files": {
-		"commit.txt": "subject: fixed stuff\n"
+		"sample.txt": "subject: fixed stuff\n"
 	}
 }

package/dist/builtin-packs/typescript/fixtures/lint/passing/exported/case.json

@@ -0,0 +1,8 @@
+{
+	"expectation": "passing",
+	"expectRules": [],
+	"files": { "sample.ts": "export const MS_PER_DAY = 86_400_000;\n" },
+	"rule": "ts/lint",
+	"section": "§6.1",
+	"trigger": "exported binding used cross-file, not in its own file"
+}

package/dist/builtin-packs/typescript/pack.json

@@ -31,7 +31,7 @@
 			"params": {},
 			"ratchet": false,
 			"measureVersion": 1,
-			"fixtures": { "violating": ["basic"], "passing": ["basic"] }
+			"fixtures": { "violating": ["basic"], "passing": ["basic", "exported"] }
 		},
 		{
 			"id": "ts/no-phantom-import",

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/gate-scope.d.ts

@@ -7,4 +7,5 @@ export interface GateScope {
     readonly note: string;
     readonly proposedContent?: string;
 }
+export declare function addedLines(diff: string): string;
 export declare function evaluateGateScope(ports: CommandPorts, packIds: ReadonlyArray<string>, scope: GateScope, now: string, configHash: string): Promise<Result<Array<Finding>>>;

package/dist/cli/gate-scope.js

@@ -51,6 +51,17 @@ function mergeGateFindings(first, second) {
     }
     return merged.sort(compareGateFindings);
 }
+// BUG-0022 + SPEC §4.7.1: the L3 gate judges added lines only, so a commit
+// deleting a flagged literal passes while staging one still blocks. A diff
+// carries its removed lines as `-` rows; scanning the raw diff would match
+// those and make the removal uncommittable.
+export function addedLines(diff) {
+    return diff
+        .split("\n")
+        .filter((line) => line.startsWith("+") && !line.startsWith("+++"))
+        .map((line) => line.slice(1))
+        .join("\n");
+}
 // BUG-0014 + SPEC §4.3.2: the gate evaluation over a diff scope. The
 // pre-tool leg keeps today's fail-closed local verdict byte for byte; the
 // review leg adds the diff-sound review subset over the same files, so the

package/dist/cli/git-hook.js

@@ -4,9 +4,10 @@
 // the change with the gate rule subset `verify` loads over staged scopes —
 // new scope plumbing, no new detection logic. commit-msg appends
 // the Codictator-L3 trailer §4.14.2 checks at L4.
+import path from "node:path";
 import { ENGINE_VERSION, HOOK_MARKER } from "../features/config/index.js";
 import { err, makeError, ok, readHostText, writeHostText, } from "../kernel/index.js";
-import { evaluateGateScope } from "./gate-scope.js";
+import { addedLines, evaluateGateScope } from "./gate-scope.js";
 import { printFinding } from "./inspect.js";
 import { commandEnv, fail, loadRepoConfig, MIN_NODE_MAJOR, needRoot, nodeMajor, nodeTooOldMessage, printHuman, printJson, reportError, usageError, } from "./shared.js";
 const GIT_TIMEOUT_MS = 30000;
@@ -53,7 +54,7 @@ async function evaluateGitChange(ports, req, hook, packIds, files, content, now,
     const evaluated = await evaluateGateScope(ports, packIds, {
         files: [...files],
         note: hook,
-        ...(content === "" ? {} : { proposedContent: content }),
+        ...(content === "" ? {} : { proposedContent: addedLines(content) }),
     }, now, configHash);
     if (!evaluated.ok) {
         return reportError(evaluated.error, req.json);
@@ -77,16 +78,20 @@ async function runPreCommit(req, ports, packIds, now, configHash) {
     }
     return evaluateGitChange(ports, req, "pre-commit", packIds, staged.value, diff.value, now, configHash);
 }
-// SPEC §4.14.4: git hands commit-msg an absolute COMMIT_EDITMSG path, which
-// in a linked worktree lives under the main repo's .git/worktrees/<name>/
-// dir, outside the worktree root. The confined Fs port rejects absolute
-// paths (CDX-E701), so the hook uses kernel-owned host I/O; an unreadable
-// or unwritable message file blocks fail-closed.
+// SPEC §4.14.4: git hands commit-msg the COMMIT_EDITMSG path, absolute in a
+// linked worktree (under the main repo's .git/worktrees/<name>/ dir, outside
+// the worktree root) but relative to the repo root (`.git/COMMIT_EDITMSG`)
+// in the main worktree. The confined Fs port rejects absolute paths
+// (CDX-E701), so the hook uses kernel-owned host I/O — which itself
+// requires absolute paths — resolving a relative handoff against the
+// invocation cwd first; an unreadable or unwritable message file blocks
+// fail-closed.
 async function runCommitMsg(req, configHash) {
     if (req.args.length !== 2 || req.args[1] === undefined) {
         return usageError("usage: codictator git commit-msg <file>");
     }
-    const file = req.args[1];
+    const raw = req.args[1];
+    const file = path.isAbsolute(raw) ? raw : path.resolve(req.cwd, raw);
     const trailer = `Codictator-L3: ${configHash.slice(0, 12)}`;
     const read = await readHostText(file);
     if (!read.ok) {

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

@@ -7,8 +7,9 @@ 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 { 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";
 }
@@ -89,7 +90,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 +108,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 +170,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-launcher.d.ts

@@ -1 +1,2 @@
 export declare const LAUNCHER_TEXT: string;
+export type LauncherText = typeof LAUNCHER_TEXT;

package/dist/cli/plan-launcher.js

@@ -20,7 +20,11 @@ export const LAUNCHER_TEXT = [
     "// 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",
+    "// <root>/.codictator/tool/node_modules/codictator/dist/cli/main.js. The",
+    "// launcher reads the resolved engine's manifest version and passes it",
+    "// as main's third argument, so hook validation sees the installed",
+    "// version (SPEC §4.2.1 EC-11); an unreadable manifest falls back to",
+    "// the two-argument call. 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",
@@ -28,7 +32,7 @@ export const LAUNCHER_TEXT = [
     "// 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 { existsSync, readFileSync }", "fs"),
     launcherImport("import path", "path"),
     launcherImport("import { fileURLToPath, pathToFileURL }", "url"),
     "",
@@ -141,6 +145,48 @@ export const LAUNCHER_TEXT = [
     "\treturn null;",
     "}",
     "",
+    "// SPEC §4.2.1 EC-11: the engine entry validates config.codictator",
+    "// against the installed engine version, so the launcher extracts it",
+    "// from the resolved engine's own manifest text and passes it as",
+    "// main's third argument. A version-field scan keeps JSON parsing in",
+    "// the kernel per §10.3 item 6 (and a regex literal would confuse the",
+    "// blankCode lexer the ts/lint gate runs on); any unreadable or",
+    "// version-less manifest answers null and the caller falls back to",
+    "// the two-argument call, which keeps the pinned placeholder —",
+    "// fail-closed downstream, never an allow.",
+    "function installedEngineVersion(enginePath) {",
+    "\ttry {",
+    "\t\tconst manifestPath = path.join(",
+    "\t\t\tpath.dirname(path.dirname(path.dirname(enginePath))),",
+    `\t\t\t"package.json",`,
+    "\t\t);",
+    `\t\tconst text = readFileSync(manifestPath, "utf8");`,
+    '\t\tconst marker = "\\"version\\":";',
+    "\t\tconst at = text.indexOf(marker);",
+    "\t\tif (at === -1) {",
+    "\t\t\treturn null;",
+    "\t\t}",
+    "\t\tlet index = at + marker.length;",
+    '\t\twhile (text[index] === " " || text[index] === "\\t" || text[index] === "\\n" || text[index] === "\\r") {',
+    "\t\t\tindex += 1;",
+    "\t\t}",
+    '\t\tif (text[index] !== "\\"") {',
+    "\t\t\treturn null;",
+    "\t\t}",
+    '\t\tconst end = text.indexOf("\\"", index + 1);',
+    "\t\tif (end === -1) {",
+    "\t\t\treturn null;",
+    "\t\t}",
+    "\t\tconst version = text.slice(index + 1, end);",
+    '\t\tif (version === "") {',
+    "\t\t\treturn null;",
+    "\t\t}",
+    "\t\treturn version;",
+    "\t} catch (ignored) {",
+    "\t\treturn null;",
+    "\t}",
+    "}",
+    "",
     "function reportMissing(harness) {",
     "\tconst missing = staticReply(",
     "\t\tharness,",
@@ -175,7 +221,11 @@ export const LAUNCHER_TEXT = [
     `\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\tconst version = installedEngineVersion(enginePath);",
+    "\t\t\t\tif (version === null) {",
+    "\t\t\t\t\treturn engine.main(args, process.cwd());",
+    "\t\t\t\t}",
+    "\t\t\t\treturn engine.main(args, process.cwd(), version);",
     "\t\t\t},",
     "\t\t\t(error) => {",
     "\t\t\t\tthrow 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>>;