codictator 0.0.0 → 0.1.3

package/dist/cli/inspect-status.d.ts

@@ -0,0 +1,8 @@
+import type { EventLogLine } from "../features/audit/index.ts";
+import type { Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function readLogEvents(root: string): Promise<{
+    events: ReadonlyArray<EventLogLine>;
+    corrupt: number;
+} | undefined>;
+export declare function handleStatus(req: CommandRequest): Promise<Result<number>>;

package/dist/cli/inspect-status.js

@@ -0,0 +1,164 @@
+// SPEC §4.18.3: the status screen. Split from the verify command
+// (inspect.ts) by responsibility: read-only screen here, trigger evaluation
+// there. The event log, config and ports stay caller-owned.
+import { parseArgs } from "node:util";
+import { CLAUDE_CODE_CAPABILITIES, CODEX_CAPABILITIES, COPILOT_CAPABILITIES, MUSE_CAPABILITIES, OPENCODE_CAPABILITIES, UNIVERSAL_CAPABILITIES, } from "../features/adapters/index.js";
+import { buildStatusJson, buildStatusText, readEvents, summarizeTokenSaverEvidence, tokenSaverHelper, } from "../features/audit/index.js";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { REQUIRED_HELPERS_DEFAULT } from "../features/steering/index.js";
+import { ok } from "../kernel/index.js";
+import { fail, loadRepoConfig, needRoot, portsFor, printHuman, printJson, usageError, } from "./shared.js";
+// SPEC §4.18.1: the repo's event lines through caller-owned ports against
+// the logical root "." (the Fs port takes repo-relative paths only).
+export async function readLogEvents(root) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return undefined;
+    }
+    const read = await readEvents(ports.value, ".");
+    return read.ok ? read.value : undefined;
+}
+function harnessStates(observed) {
+    const declarations = [
+        MUSE_CAPABILITIES,
+        UNIVERSAL_CAPABILITIES,
+        CLAUDE_CODE_CAPABILITIES,
+        COPILOT_CAPABILITIES,
+        CODEX_CAPABILITIES,
+        OPENCODE_CAPABILITIES,
+    ];
+    return declarations.map((candidate) => ({
+        harness: candidate.harness,
+        state: observed.has(candidate.harness)
+            ? "active"
+            : "unverified",
+        layers: `L0:${candidate.layers.L0} L1:${candidate.layers.L1} L2:${candidate.layers.L2} L3:${candidate.layers.L3} L4:${candidate.layers.L4} L5:${candidate.layers.L5}`,
+    }));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// SPEC §4.6.6: the required helper roles come from config.steering, falling
+// back to the pack default; a role is present when config.tools declares it
+// (by role or id) at an exact pin.
+function requiredRoles(steering) {
+    if (isRecord(steering)) {
+        const key = "requiredHelpers";
+        const found = steering[key];
+        if (Array.isArray(found) &&
+            found.every((entry) => typeof entry === "string")) {
+            return [...found];
+        }
+    }
+    return [...REQUIRED_HELPERS_DEFAULT];
+}
+function matchHelper(entry, role) {
+    if (!isRecord(entry)) {
+        return undefined;
+    }
+    const idKey = "id";
+    const roleKey = "role";
+    const versionKey = "version";
+    const pinKey = "pin";
+    const id = entry[idKey];
+    if (typeof id !== "string" || id === "") {
+        return undefined;
+    }
+    if (entry[roleKey] !== role && id !== role) {
+        return undefined;
+    }
+    const version = entry[versionKey];
+    const pin = isRecord(version) ? version[pinKey] : undefined;
+    if (typeof pin === "string" && pin !== "") {
+        return { role, present: true, detail: `${id} ${pin}` };
+    }
+    return { role, present: false };
+}
+function helperDetail(tools, role) {
+    if (!Array.isArray(tools)) {
+        return { role, present: false };
+    }
+    for (const entry of tools) {
+        const matched = matchHelper(entry, role);
+        if (matched !== undefined) {
+            return matched;
+        }
+    }
+    return { role, present: false };
+}
+async function collectStatusParts(root, engineVersion) {
+    const log = await readLogEvents(root);
+    const events = log?.events ?? [];
+    const observed = new Set(events.map((event) => event.harness ?? "").filter((h) => h !== ""));
+    const packs = {};
+    let helpers = [];
+    const configured = await loadRepoConfig(root, undefined, engineVersion);
+    if (configured.ok) {
+        for (const pack of configured.value.effective.config.packs) {
+            packs[pack.id] =
+                typeof pack.version === "string" ? pack.version : "unpinned";
+        }
+        helpers = requiredRoles(configured.value.effective.config.steering).map((role) => helperDetail(configured.value.effective.config.tools, role));
+        // SPEC §4.6.6 + §4.18.3: the token-saver role is satisfied by the
+        // engine itself, so with no external pin the row carries live
+        // evidence instead of probing a binary. All-absent evidence reads
+        // missing: a finding, not a pass.
+        helpers = helpers.map((helper) => helper.role === "token-saver" && !helper.present
+            ? tokenSaverHelper(summarizeTokenSaverEvidence(events))
+            : helper);
+    }
+    return { events, corrupt: log?.corrupt ?? 0, observed, packs, helpers };
+}
+function terseArgs(args, count) {
+    try {
+        const parsed = parseArgs({
+            args: [...args],
+            options: {},
+            allowPositionals: true,
+        });
+        return parsed.positionals.length === count;
+    }
+    catch {
+        return false;
+    }
+}
+// SPEC §4.18.3: one screen with engine, packs, harness states, task, waivers,
+// ratchet, deps, integrity, escalations and remediation progress.
+export async function handleStatus(req) {
+    if (!terseArgs(req.args, 0)) {
+        return usageError("usage: codictator status");
+    }
+    const root = await needRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return fail("CDX-E903", ports.error.message, ports.error.remediation, req.json);
+    }
+    const parts = await collectStatusParts(root, req.engineVersion ?? ENGINE_VERSION);
+    const input = {
+        engineVersion: req.engineVersion ?? ENGINE_VERSION,
+        packs: parts.packs,
+        harnesses: harnessStates(parts.observed),
+        helpers: parts.helpers,
+        events: parts.events.length,
+        corrupt: parts.corrupt,
+        gap: parts.events.length === 0,
+        task: undefined,
+        waivers: undefined,
+        ratchet: undefined,
+        deps: undefined,
+        integrity: undefined,
+        escalations: undefined,
+        remediation: undefined,
+        now: ports.value.clock.now(),
+    };
+    if (req.json) {
+        printJson(buildStatusJson(input));
+    }
+    else {
+        printHuman(buildStatusText(input), req.quiet);
+    }
+    return ok(0);
+}

package/dist/cli/inspect.d.ts

@@ -0,0 +1,5 @@
+import type { Finding, Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function printFinding(finding: Finding, quiet: boolean): void;
+export declare function handleVerify(req: CommandRequest): Promise<Result<number>>;
+export { handleStatus, readLogEvents } from "./inspect-status.ts";

package/dist/cli/inspect.js

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

package/dist/cli/main.d.ts

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

package/dist/cli/main.js

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

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

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

package/dist/cli/pack-adapters.js

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

package/dist/cli/packs.d.ts

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

package/dist/cli/packs.js

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

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

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