codictator 0.0.0-stage → 0.1.2

package/dist/cli/ci.js

@@ -0,0 +1,195 @@
+// SPEC §4.15: CI verify, sweep and bot-change recording. Verify fails
+// closed on an unreachable base (CDX-E503) and advises where protection
+// reads are unavailable; sweep plans the single codictator/sweep PR.
+import { checkCi, planSweep, readProtection, renderWorkflow, } from "../features/ci/index.js";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { checkCommitTrailers } from "../features/integrity/index.js";
+import { ok } from "../kernel/index.js";
+import { ciRecordBotChange } from "./ci-bot-change.js";
+import { ciPackIds, parseCiVerifyFlags, rangeCommits, rangeMessages, resolveCiRange, trailerExemptFrom, } from "./ci-range.js";
+import { ciSummaryFor, isUnverifiableFinding } from "./ci-summary.js";
+import { resolveVerifyScope } from "./evaluate.js";
+import { evaluateGateScope } from "./gate-scope.js";
+import { printFinding } from "./inspect.js";
+import { fail, loadRepoConfig, needRoot, portsFor, printHuman, printJson, usageError, } from "./shared.js";
+// SPEC §8.2 + §4.15.1: ci verify exits per §8 — 0 on allow or advise only.
+// Advise findings are exactly the unverifiable ones the summary already
+// separates (unreadable protection, fork read-only); anything else blocks.
+export function ciVerifyExit(findings) {
+    return findings.some((finding) => !isUnverifiableFinding(finding)) ? 1 : 0;
+}
+// The verify change scope (flags, event path, commit messages) lives in
+// ci-range.ts and the summary shaping in ci-summary.ts; ciVerify only
+// folds its findings into the verdict.
+async function ciVerify(req, root, configHash, now, trailerExempt, engineVersion) {
+    const flags = parseCiVerifyFlags(req.args.slice(1));
+    if (flags === undefined) {
+        return usageError("usage: codictator ci verify [--base <sha> --head <sha>]");
+    }
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return fail("CDX-E903", ports.error.message, ports.error.remediation, req.json);
+    }
+    const repoName = root.replaceAll("\\", "/").split("/").pop() ?? "repo";
+    const workflow = renderWorkflow(repoName);
+    const shallow = await ports.value.fs.exists(".git/shallow");
+    const baseReachable = !(shallow.ok && shallow.value);
+    // SPEC §4.15.2: the live read runs only in Actions with a token, so
+    // local runs keep no protection evidence and degrade exactly as before.
+    let protection;
+    const inActions = ports.value.env.get("GITHUB_ACTIONS") === "true";
+    const token = ports.value.env.get("GITHUB_TOKEN");
+    if (inActions && token !== undefined && token !== "") {
+        protection = await readProtection(ports.value.net, ports.value.env);
+    }
+    const checks = checkCi({ trigger: "pre-tool", scope: { files: [] }, now, configHash }, workflow, {
+        baseReachable,
+        ...(protection === undefined ? {} : { protection }),
+    });
+    // SPEC §4.3.2 + §4.15.1 + §4.7.1: L4 judges the change with the gate
+    // rule subset (pre-tool plus diff-sound review, BUG-0014), so ci verify
+    // also evaluates those enforcers over the change: the base..head diff
+    // plus every commit message in range. Without a range there is no
+    // change to judge, so the repo-wide rules judge alone, exactly as
+    // before. A committed secret in range blocks here, not just at L3.
+    const ranged = await resolveCiRange(ports.value, flags);
+    if (!ranged.ok) {
+        return fail(ranged.error.code, ranged.error.message, ranged.error.remediation, req.json);
+    }
+    let evaluated = [];
+    let trailered = [];
+    if (ranged.value !== undefined) {
+        // BUG-0014 + SPEC §4.3.2: the L4 gate judges pre-tool plus the
+        // diff-sound review subset, the phase-5 finer trigger as a rule
+        // subset. The diff-unsound rules (spec-trace, dead-code) stay on
+        // the human `review` command over the tree; they need full-tree
+        // context the range does not carry or test-title inputs, and once
+        // blocked every normally-commented file.
+        const scoped = await resolveVerifyScope(ports.value, {
+            staged: false,
+            all: false,
+            base: ranged.value.base,
+            head: ranged.value.head,
+            layer: undefined,
+        });
+        if (!scoped.ok) {
+            if (ciVerifyExit(checks) !== 0) {
+                // SPEC §4.15.7 EC-2: the base is unreachable, which already
+                // blocks via CDX-E503; the diff scope is unreachable too,
+                // so the checks verdict stands instead of erroring.
+            }
+            else {
+                return fail(scoped.error.code, scoped.error.message, scoped.error.remediation, req.json);
+            }
+        }
+        else {
+            const commitText = await rangeMessages(ports.value, ranged.value.base, ranged.value.head);
+            const judged = await evaluateGateScope(ports.value, await ciPackIds(root, engineVersion), commitText === ""
+                ? {
+                    files: [...scoped.value.files],
+                    note: scoped.value.note,
+                }
+                : {
+                    files: [...scoped.value.files],
+                    note: scoped.value.note,
+                    proposedContent: commitText,
+                }, now, configHash);
+            if (!judged.ok) {
+                return fail(judged.error.code, judged.error.message, judged.error.remediation, req.json);
+            }
+            evaluated = judged.value;
+        }
+        // SPEC §4.14.2 core/no-bypass at L4: every non-merge commit in range
+        // carries the Codictator-L3 trailer. An unreadable range fails
+        // closed: skipping the gate would let a trailer-less commit
+        // through (EC-3, EC-4).
+        const commits = await rangeCommits(ports.value, ranged.value.base, ranged.value.head);
+        if (!commits.ok) {
+            if (ciVerifyExit(checks) !== 0) {
+                // SPEC §4.15.7 EC-2: the base is unreachable, which already
+                // blocks via CDX-E503; the trailer gate is unverifiable too,
+                // so its error folds into the findings verdict (ok(1))
+                // instead of erroring, exactly like the diff scope above.
+                trailered = [
+                    {
+                        ruleId: "core/no-bypass",
+                        code: commits.error.code,
+                        message: commits.error.message,
+                        remediation: commits.error.remediation,
+                    },
+                ];
+            }
+            else {
+                return fail(commits.error.code, commits.error.message, commits.error.remediation, req.json);
+            }
+        }
+        else {
+            trailered = checkCommitTrailers(commits.value, trailerExempt);
+        }
+    }
+    const findings = [...checks, ...evaluated, ...trailered];
+    const summary = ciSummaryFor(findings);
+    if (req.json) {
+        printJson({ findings, summary });
+    }
+    else {
+        for (const finding of findings) {
+            printFinding(finding, req.quiet);
+        }
+        if (findings.length === 0) {
+            printHuman("ci verify: pass", req.quiet);
+        }
+        printHuman(summary, req.quiet);
+    }
+    return ok(ciVerifyExit(findings));
+}
+function ciSweep(req) {
+    if (req.args.length !== 1) {
+        return usageError("usage: codictator ci sweep");
+    }
+    const planned = planSweep({ sweepPrOpen: false, floorFindings: [] });
+    if (req.json) {
+        printJson(planned);
+    }
+    else {
+        printHuman(`sweep ${planned.action}: ${planned.pr}`, req.quiet);
+    }
+    return ok(0);
+}
+// The verify evaluation inputs (the stored config hash plus the trailer
+// exemption list) load together: one repo-config read serves both, and the
+// handleCi dispatch stays under the complexity gate.
+async function verifyInputs(root, engineVersion) {
+    let configHash = "unknown";
+    let trailerExempt = [];
+    const configured = await loadRepoConfig(root, undefined, engineVersion);
+    if (configured.ok) {
+        configHash = configured.value.effective.configHash;
+        trailerExempt = trailerExemptFrom(configured.value.effective.config);
+    }
+    return { configHash, trailerExempt };
+}
+export async function handleCi(req) {
+    const sub = req.args[0] ?? "";
+    if (sub !== "verify" && sub !== "sweep" && sub !== "record-bot-change") {
+        return usageError("usage: codictator ci <verify|sweep|record-bot-change ...>");
+    }
+    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 now = ports.value.clock.now();
+    if (sub === "verify") {
+        const engineVersion = req.engineVersion ?? ENGINE_VERSION;
+        const inputs = await verifyInputs(root, engineVersion);
+        return ciVerify(req, root, inputs.configHash, now, inputs.trailerExempt, engineVersion);
+    }
+    if (sub === "sweep") {
+        return ciSweep(req);
+    }
+    return ciRecordBotChange(req);
+}

package/dist/cli/commands.d.ts

@@ -0,0 +1,5 @@
+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]";

package/dist/cli/commands.js

@@ -0,0 +1,39 @@
+import { handleBaseline } from "./baseline.js";
+import { handleCi } from "./ci.js";
+import { handleDeps } from "./deps.js";
+import { handleInstallHooks, handleRegen, handleUninstall, } from "./guardrail.js";
+import { handleInit } from "./init.js";
+import { handleStatus, handleVerify } from "./inspect.js";
+import { handleAdapter, handleGenerate, handlePack, handleServe, } from "./packs.js";
+import { handleReview } from "./proofs.js";
+import { handleTestCmd } from "./proofs-test.js";
+import { handleRemediate } from "./remediation.js";
+import { handleContext, handleReport } from "./report.js";
+import { handleTask } from "./task-advance.js";
+import { handleExplain, handleReplay } from "./transparency.js";
+import { handleWaive } from "./waivers.js";
+export const COMMANDS = {
+    init: handleInit,
+    "install-hooks": handleInstallHooks,
+    regen: handleRegen,
+    uninstall: handleUninstall,
+    verify: handleVerify,
+    status: handleStatus,
+    explain: handleExplain,
+    replay: handleReplay,
+    report: handleReport,
+    context: handleContext,
+    task: handleTask,
+    test: handleTestCmd,
+    review: handleReview,
+    waive: handleWaive,
+    baseline: handleBaseline,
+    deps: handleDeps,
+    remediate: handleRemediate,
+    ci: handleCi,
+    generate: handleGenerate,
+    pack: handlePack,
+    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]";

package/dist/cli/deps.d.ts

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

package/dist/cli/deps.js

@@ -0,0 +1,115 @@
+// SPEC §4.8 + §4.13.1: offline dependency analysis over manifests and
+// lockfiles; registry data needs a snapshot or the network (CDX-E401).
+import { parseArgs } from "node:util";
+import { detectBrownfield } from "../features/remediation/index.js";
+import { ok } from "../kernel/index.js";
+import { printFinding } from "./inspect.js";
+import { fail, needRoot, portsFor, printHuman, printJson, readStateText, usageError, } from "./shared.js";
+async function collectManifests(root) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return undefined;
+    }
+    const found = await ports.value.fs.glob("package.json", ".");
+    const manifests = found.ok ? found.value : [];
+    const texts = [];
+    for (const manifest of manifests.slice(0, 20)) {
+        const seen = await ports.value.fs.exists(manifest);
+        if (!seen.ok || !seen.value) {
+            continue;
+        }
+        const text = await ports.value.fs.readText(manifest);
+        if (text.ok) {
+            texts.push({ path: manifest, text: text.value });
+        }
+    }
+    if (texts.length === 0) {
+        return undefined;
+    }
+    const lockfiles = {};
+    for (const input of texts) {
+        const lock = input.path.replace(/package\.json$/, "package-lock.json");
+        lockfiles[input.path] = (await readStateText(root, lock)) ?? null;
+    }
+    return { paths: texts.map((input) => input.path), texts, lockfiles };
+}
+async function depsCheck(req, root, now) {
+    const inputs = await collectManifests(root);
+    if (inputs === undefined) {
+        return fail("CDX-E903", "no package manifests found", "Run in a repo with manifests, then retry.", req.json);
+    }
+    const detection = detectBrownfield({
+        files: inputs.paths,
+        manifests: inputs.texts,
+        lockfiles: inputs.lockfiles,
+        now,
+    });
+    if (req.json) {
+        printJson({ findings: detection.findings, loosePins: detection.loosePins });
+    }
+    else {
+        for (const finding of detection.findings) {
+            printFinding(finding, req.quiet);
+        }
+        if (detection.findings.length === 0) {
+            printHuman("deps: no loose pins or missing lockfiles", req.quiet);
+        }
+    }
+    return detection.findings.length === 0 ? ok(0) : ok(1);
+}
+async function depsUpgrade(req, root, now) {
+    let pr = false;
+    try {
+        const parsed = parseArgs({
+            args: [...req.args.slice(1)],
+            options: { pr: { type: "boolean", default: false } },
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return usageError("usage: codictator deps upgrade [--pr]");
+        }
+        pr = parsed.values.pr ?? false;
+    }
+    catch {
+        return usageError("usage: codictator deps upgrade [--pr]");
+    }
+    const inputs = await collectManifests(root);
+    if (inputs === undefined) {
+        return fail("CDX-E903", "no package manifests found", "Run in a repo with manifests, then retry.", req.json);
+    }
+    const snapshot = await readStateText(root, ".codictator/registry-snapshot.json");
+    if (snapshot === undefined) {
+        return fail("CDX-E401", "registry data unavailable and no usable snapshot", "Retry with network access, or record .codictator/registry-snapshot.json first.", req.json);
+    }
+    const detection = detectBrownfield({
+        files: inputs.paths,
+        manifests: inputs.texts,
+        lockfiles: inputs.lockfiles,
+        now,
+    });
+    if (req.json) {
+        printJson({ planned: detection.loosePins.length, pr });
+    }
+    else {
+        printHuman(`deps upgrade planned for ${detection.loosePins.length} loose pin(s)${pr ? " with --pr" : ""}`, req.quiet);
+    }
+    return ok(0);
+}
+export async function handleDeps(req) {
+    const sub = req.args[0] ?? "";
+    if (sub !== "check" && sub !== "upgrade") {
+        return usageError("usage: codictator deps <check|upgrade [--pr]>");
+    }
+    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 now = ports.value.clock.now();
+    return sub === "check"
+        ? depsCheck(req, root, now)
+        : depsUpgrade(req, root, now);
+}

package/dist/cli/drift.d.ts

@@ -0,0 +1,11 @@
+import type { Finding } from "../kernel/index.ts";
+export interface ManifestRecord {
+    readonly artifacts: ReadonlyArray<{
+        path: string;
+        hash: string;
+    }>;
+}
+export declare function driftFindings(root: string, layer: string | undefined): Promise<{
+    findings: Array<Finding>;
+    note: string;
+}>;

package/dist/cli/drift.js

@@ -0,0 +1,91 @@
+// SPEC §4.14.2: manifest drift findings. The manifest self-hash is verified
+// first (an edit outside regen fails closed); then every artifact hash is
+// recomputed and compared, so drift names its file.
+import { verifyManifest } from "../features/integrity/index.js";
+import { normalizeText, parseJson, sha256Text } from "../kernel/index.js";
+import { portsFor } from "./shared.js";
+function manifestProblem(message, remediation, path) {
+    return {
+        ruleId: "core/guardrail-manifest",
+        ...(path === undefined ? {} : { path }),
+        message,
+        remediation,
+    };
+}
+function readManifestRecord(text) {
+    const parsed = parseJson(text);
+    if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null) {
+        return { problem: "manifest is not JSON" };
+    }
+    const record = parsed.value;
+    if (!verifyManifest(record)) {
+        return { problem: "manifest edited outside regen" };
+    }
+    const artifacts = Array.isArray(record.artifacts) ? record.artifacts : [];
+    const kept = [];
+    for (const artifact of artifacts) {
+        if (typeof artifact !== "object" || artifact === null) {
+            continue;
+        }
+        const entry = artifact;
+        if (typeof entry.path !== "string" || typeof entry.hash !== "string") {
+            continue;
+        }
+        if (entry.path !== ".codictator/manifest.json") {
+            kept.push({ path: entry.path, hash: entry.hash });
+        }
+    }
+    return { record: { artifacts: kept } };
+}
+async function checkArtifactHashes(root, artifacts) {
+    const ports = await portsFor(root);
+    const findings = [];
+    if (!ports.ok) {
+        findings.push(manifestProblem("guardrail manifest unreadable", "Restore it with `codictator regen` (EC-4)."));
+        return findings;
+    }
+    for (const artifact of artifacts) {
+        const content = await ports.value.fs.readText(artifact.path);
+        if (!content.ok) {
+            findings.push(manifestProblem("guardrail artifact missing or unreadable", "Restore it with `codictator regen`; delete it only by dropping its owner from config first.", artifact.path));
+            continue;
+        }
+        if (sha256Text(normalizeText(content.value)) !== artifact.hash) {
+            findings.push(manifestProblem("guardrail artifact differs from its manifest entry", "Restore it with `codictator regen`; never hand-edit generated artifacts.", artifact.path));
+        }
+    }
+    return findings;
+}
+// SPEC §4.14.2 + §4.19.6 EC-7: manifest drift findings plus the
+// effective-config cache round-trip (key mismatch re-resolves).
+export async function driftFindings(root, layer) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return { findings: [], note: "unverified (ports failed)" };
+    }
+    const seen = await ports.value.fs.exists(".codictator/manifest.json");
+    if (!seen.ok || !seen.value) {
+        return { findings: [], note: "unverified (no manifest)" };
+    }
+    const text = await ports.value.fs.readText(".codictator/manifest.json");
+    if (!text.ok) {
+        return {
+            findings: [
+                manifestProblem("guardrail manifest unreadable", "Restore it with `codictator regen` (EC-4)."),
+            ],
+            note: "manifest unreadable",
+        };
+    }
+    const loaded = readManifestRecord(text.value);
+    if (loaded.record === undefined) {
+        return {
+            findings: [
+                manifestProblem(`guardrail ${loaded.problem ?? "manifest invalid"}`, "Restore it with `codictator regen`; change config and regen instead."),
+            ],
+            note: loaded.problem ?? "manifest invalid",
+        };
+    }
+    const findings = await checkArtifactHashes(root, loaded.record.artifacts);
+    const scoped = layer === undefined ? "" : ` scoped to ${layer}`;
+    return { findings, note: `manifest checked${scoped}` };
+}

package/dist/cli/evaluate.d.ts

@@ -0,0 +1,20 @@
+import type { Enforcer, Finding, Ports, Result, Trigger } from "../kernel/index.ts";
+import type { CommandPorts } from "./shared.ts";
+export interface VerifyScope {
+    readonly trigger: Trigger;
+    readonly files: ReadonlyArray<string>;
+    readonly note: string;
+    readonly proposedContent?: string;
+}
+export declare function triggerForLayer(layer: string | undefined): Trigger;
+export declare function resolveVerifyScope(ports: CommandPorts, flags: {
+    readonly staged: boolean;
+    readonly all: boolean;
+    readonly base: string | undefined;
+    readonly head: string | undefined;
+    readonly layer: string | undefined;
+}): Promise<Result<VerifyScope>>;
+export declare function loadEvalEnforcers(ports: Ports, packIds: ReadonlyArray<string>, excludeRuleIds?: ReadonlySet<string>): Promise<Result<Array<Enforcer>>>;
+export declare function evaluateScope(ports: CommandPorts, packIds: ReadonlyArray<string>, scope: VerifyScope, now: string, configHash: string, options?: {
+    readonly excludeRuleIds?: ReadonlySet<string>;
+}): Promise<Result<Array<Finding>>>;