codictator 0.1.3 → 0.2.0

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

@@ -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/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>>;

package/dist/cli/setup.js

@@ -0,0 +1,143 @@
+// SPEC §4.19.6: one-shot adoption. Flags mirror init (§4.19.2); the run
+// is the init path (or regen over an existing config) plus install, hooks
+// and verify, ending at the extension handoff (§4.20.1). Every step
+// delegates to the existing init, guardrail and verify handlers; no step
+// logic is duplicated here.
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { err, ok } from "../kernel/index.js";
+import { configureHooksPath, handleRegen, writeHookFiles, } from "./guardrail.js";
+import { parseInitFlags } from "./init.js";
+import { defaultHarnesses, initPreamble, runInitSequence, } from "./init-plan.js";
+import { handleVerify } from "./inspect.js";
+import { setupGitignoreStep } from "./setup-gitignore.js";
+import { hasEffectivePacks, SETUP_EXTENSION_ID, SETUP_EXTENSION_INSTALL, setupHandoffLines, } from "./setup-handoff.js";
+import { setupInstallHere, setupInstallLayout } from "./setup-install.js";
+import { fail, MIN_NODE_MAJOR, nodeMajor, nodeTooOldMessage, printHuman, printJson, readStateText, usageError, } from "./shared.js";
+export const SETUP_USAGE = "usage: codictator setup [--harness <id> ...] [--profile <app|library|cli|service>] [--pack <id> ...] [--tool <role>=<command>@<pin> ...] [--repair]";
+// SPEC §4.19.6 step 1: the Node floor, the human gate and the repo root.
+async function setupPreflight(req) {
+    const version = req.nodeVersion ?? process.version;
+    if (nodeMajor(version) < MIN_NODE_MAJOR) {
+        return fail("CDX-E002", nodeTooOldMessage(version), "Install a newer Node, then retry the tool call.", req.json);
+    }
+    return initPreamble(req);
+}
+// SPEC §4.19.6 step 2: the adoption path. An existing config without
+// --repair re-renders from config; otherwise the init path runs.
+async function setupRegenPath(req, steps) {
+    const regen = await handleRegen({ ...req, args: [] });
+    if (!regen.ok) {
+        return regen;
+    }
+    steps.push({ step: "init", ok: true, detail: { mode: "regen" } });
+    printHuman("setup: guardrails regenerated from the existing config", req.quiet);
+    return ok(0);
+}
+async function setupInitPath(req, root, flags, steps) {
+    const engineVersion = req.engineVersion ?? ENGINE_VERSION;
+    const sequenced = await runInitSequence(root, req, flags, defaultHarnesses(flags), engineVersion);
+    if (!sequenced.ok) {
+        return sequenced;
+    }
+    steps.push({
+        step: "init",
+        ok: true,
+        detail: {
+            mode: flags.repair ? "repair" : "fresh",
+            files: sequenced.value.written.map((entry) => entry.path),
+        },
+    });
+    printHuman("setup: guardrails written from the init path", req.quiet);
+    return ok(0);
+}
+async function setupAdopt(req, root, flags, steps) {
+    const existing = await readStateText(root, ".codictator/config.json");
+    if (existing !== undefined && !flags.repair) {
+        return setupRegenPath(req, steps);
+    }
+    return setupInitPath(req, root, flags, steps);
+}
+// SPEC §4.19.6 step 6: hooks via the install-hooks writers.
+async function setupHooksStep(req, root, steps) {
+    const written = await writeHookFiles(root);
+    if (!written.ok) {
+        return fail("CDX-E903", written.error.message, written.error.remediation, req.json);
+    }
+    await configureHooksPath(root, req);
+    steps.push({ step: "hooks", ok: true });
+    printHuman("setup: hooks installed", req.quiet);
+    return ok(0);
+}
+// SPEC §4.19.6 step 7: the first evaluation over the adopted repo. A
+// blocking verdict stops the run with verify's own mapping (exit 1).
+async function setupVerifyStep(req, steps) {
+    const verdict = await handleVerify({ ...req, args: [] });
+    if (!verdict.ok || verdict.value !== 0) {
+        return verdict;
+    }
+    steps.push({ step: "verify", ok: true });
+    return ok(0);
+}
+// SPEC §4.19.6 step 8 + §4.20.1: the views connect once a config exists;
+// the human installs the extension with the printed command.
+function setupHandoff(req, root, steps, emptyPacks) {
+    steps.push({
+        step: "handoff",
+        ok: true,
+        detail: { extension: SETUP_EXTENSION_ID },
+    });
+    if (req.json) {
+        printJson({
+            setup: true,
+            root,
+            steps,
+            extension: { id: SETUP_EXTENSION_ID, install: SETUP_EXTENSION_INSTALL },
+        });
+    }
+    else {
+        for (const line of setupHandoffLines(emptyPacks)) {
+            printHuman(line, req.quiet);
+        }
+    }
+    return ok(0);
+}
+// SPEC §4.19.6: the eight adoption steps in order; a step failure stops
+// the run with that step's §8.2 mapping.
+export async function handleSetup(req) {
+    const flags = parseInitFlags(req.args);
+    if (flags === undefined) {
+        return usageError(SETUP_USAGE);
+    }
+    const preflight = await setupPreflight(req);
+    if (typeof preflight !== "string") {
+        return preflight;
+    }
+    const root = preflight;
+    const steps = [{ step: "preflight", ok: true }];
+    const adopted = await setupAdopt(req, root, flags, steps);
+    if (!adopted.ok) {
+        return adopted;
+    }
+    const ignored = await setupGitignoreStep(req, root, steps);
+    if (!ignored.ok) {
+        return ignored;
+    }
+    const layout = await setupInstallLayout(req, root, steps);
+    if (!layout.ok) {
+        return err(layout.error);
+    }
+    const installed = await setupInstallHere(req, root, layout.value, steps);
+    if (!installed.ok) {
+        return installed;
+    }
+    const hooked = await setupHooksStep(req, root, steps);
+    if (!hooked.ok) {
+        return hooked;
+    }
+    const verified = await setupVerifyStep(req, steps);
+    if (!verified.ok) {
+        return verified;
+    }
+    const emptyPacks = !(await hasEffectivePacks(root, flags));
+    return setupHandoff(req, root, steps, emptyPacks);
+}