codictator 0.0.0 → 0.1.2

package/dist/cli/plan.js

@@ -0,0 +1,121 @@
+// SPEC §4.14.1 + §4.14.5: guardrail plan builders. The file list (config,
+// steering block, CI workflow, hooks, launcher) and the manifest write are
+// shared by init and regen, so regeneration stays byte-identical.
+import { renderWorkflow } from "../features/ci/index.js";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { buildManifest, EXPECTED_HOOKS_PATH, HOOK_NAMES, hookInstallPlan, renderHookScript, } from "../features/integrity/index.js";
+import { buildManagedBlock, MANAGED_BEGIN, MANAGED_END, } from "../features/steering/index.js";
+import { err, normalizeText, ok, sha256Text, stableStringify, } from "../kernel/index.js";
+import { LAUNCHER_TEXT } from "./plan-launcher.js";
+import { portsFor } from "./shared.js";
+function encode(text) {
+    return new TextEncoder().encode(text);
+}
+// SPEC §4.4.5 + §4.6.6: init proposals for helper tools. The entry carries
+// the role, the binary, the exact pin from the human's registry lookup, and
+// a probe matching any semver in the tool's --version output whose capture
+// must equal the pin (external-probe.ts). Helpers never back enforcers, so
+// the probe runs only when a pack binds the tool.
+export const KNOWN_HELPER_ROLES = new Set([
+    "knowledge-graph",
+    "token-saver",
+    "dependency-bot",
+    "other",
+]);
+const SEMVER_CAPTURE = "(\\d+\\.\\d+\\.\\d+)";
+export function buildHelperTool(proposal) {
+    return {
+        id: proposal.command,
+        command: [proposal.command],
+        version: {
+            pin: proposal.pin,
+            probe: [proposal.command, "--version"],
+            pattern: SEMVER_CAPTURE,
+        },
+        role: proposal.role,
+    };
+}
+function configText(harnesses, profile, extras = {}, engineVersion = ENGINE_VERSION) {
+    const sorted = [...harnesses].sort();
+    const architecture = extras.architecture ?? (profile === "" ? undefined : { profile });
+    const config = {
+        version: 1,
+        codictator: engineVersion,
+        packs: extras.packs ?? [],
+        harnesses: sorted,
+        tunables: extras.tunables ?? {},
+        ...(architecture === undefined ? {} : { architecture }),
+        ...(extras.tools === undefined ? {} : { tools: extras.tools }),
+    };
+    return `${stableStringify(config)}\n`;
+}
+// SPEC §4.14.1: user text outside the managed block survives regen; a
+// malformed block is replaced rather than duplicated (CDX-E501 avoided).
+function withManagedBlock(existing) {
+    const block = buildManagedBlock();
+    if (existing === undefined) {
+        return `${block}\n`;
+    }
+    const start = existing.indexOf(MANAGED_BEGIN);
+    const end = existing.indexOf(MANAGED_END);
+    if (start < 0 || end < 0 || end < start) {
+        const trimmed = existing.endsWith("\n") ? existing : `${existing}\n`;
+        return `${trimmed}\n${block}\n`;
+    }
+    const after = end + MANAGED_END.length;
+    return `${existing.slice(0, start)}${block}${existing.slice(after)}`;
+}
+export function guardrailPlan(harnesses, profile, repoName, existingAgents, extras = {}, engineVersion = ENGINE_VERSION) {
+    const files = [];
+    files.push({
+        path: ".codictator/config.json",
+        content: configText(harnesses, profile, extras, engineVersion),
+    });
+    files.push({ path: "AGENTS.md", content: withManagedBlock(existingAgents) });
+    const workflow = renderWorkflow(repoName);
+    files.push({
+        path: ".github/workflows/codictator.yml",
+        content: workflow.text ?? "",
+    });
+    for (const hook of HOOK_NAMES) {
+        files.push({
+            path: `${EXPECTED_HOOKS_PATH}/${hook}`,
+            content: renderHookScript(hook),
+        });
+    }
+    const plan = hookInstallPlan({});
+    files.push({
+        path: `${EXPECTED_HOOKS_PATH}/.gitattributes`,
+        content: plan.gitattributes,
+    });
+    files.push({ path: ".codictator/bin/run.mjs", content: LAUNCHER_TEXT });
+    return { files };
+}
+export async function writePlan(root, plan, engineVersion = ENGINE_VERSION) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return err(ports.error);
+    }
+    const written = [];
+    for (const file of plan.files) {
+        const done = await ports.value.fs.write(file.path, encode(file.content));
+        if (!done.ok) {
+            return err(done.error);
+        }
+        written.push({
+            path: file.path,
+            hash: sha256Text(normalizeText(file.content)),
+        });
+    }
+    const manifest = buildManifest(engineVersion, written.map((entry) => ({
+        path: entry.path,
+        owner: "codictator",
+        mode: "file",
+        hash: entry.hash,
+    })));
+    const saved = await ports.value.fs.write(".codictator/manifest.json", encode(`${stableStringify(manifest)}\n`));
+    if (!saved.ok) {
+        return err(saved.error);
+    }
+    return ok(written);
+}

package/dist/cli/proofs-test.d.ts

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

package/dist/cli/proofs-test.js

@@ -0,0 +1,77 @@
+// SPEC §4.10.2: red and green proofs attach the HEAD commit and tree to the
+// task; the declared tests must have executed (titles listed on the command).
+import { parseArgs } from "node:util";
+import { ok } from "../kernel/index.js";
+import { fail, needTaskRoot, portsFor, printHuman, usageError, } from "./shared.js";
+import { readTask, writeTask } from "./tasks.js";
+async function recordProof(req, root, kind, titles, task) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return fail("CDX-E903", ports.error.message, ports.error.remediation, req.json);
+    }
+    const head = await ports.value.proc.run(["git", "rev-parse", "HEAD"], {
+        cwd: root,
+        env: {},
+        timeoutMs: 15000,
+        maxOutputBytes: 4096,
+    });
+    const tree = await ports.value.proc.run(["git", "rev-parse", "HEAD^{tree}"], {
+        cwd: root,
+        env: {},
+        timeoutMs: 15000,
+        maxOutputBytes: 4096,
+    });
+    if (head.code !== 0 || tree.code !== 0) {
+        return fail("CDX-E703", "cannot read the HEAD commit or tree", "Commit first, then retry.", req.json);
+    }
+    const now = ports.value.clock.now();
+    const proved = kind === "red"
+        ? {
+            ...task,
+            redProof: {
+                commit: head.stdout.trim(),
+                tree: tree.stdout.trim(),
+                failing: [...titles],
+                at: now,
+            },
+        }
+        : { ...task, greenProof: { at: now, tree: tree.stdout.trim() } };
+    const saved = await writeTask(root, proved);
+    if (!saved.ok) {
+        return saved;
+    }
+    printHuman(`recorded ${kind} proof for ${task.id}`, req.quiet);
+    return ok(0);
+}
+export async function handleTestCmd(req) {
+    const kind = req.args[0] ?? "";
+    if (kind !== "red" && kind !== "green") {
+        return usageError("usage: codictator test <red|green> --task <T-####> [<test title> ...]");
+    }
+    let taskId = "";
+    let titles = [];
+    try {
+        const parsed = parseArgs({
+            args: [...req.args.slice(1)],
+            options: { task: { type: "string" } },
+            allowPositionals: true,
+        });
+        taskId = parsed.values.task ?? "";
+        titles = [...parsed.positionals];
+        if (taskId === "" || titles.length === 0) {
+            return usageError("usage: codictator test <red|green> --task <T-####> [<test title> ...]");
+        }
+    }
+    catch {
+        return usageError("usage: codictator test <red|green> --task <T-####> [<test title> ...]");
+    }
+    const root = await needTaskRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    const task = await readTask(root, taskId);
+    if (task === undefined) {
+        return fail("CDX-E903", `no task record for "${taskId}"`, "Create it with codictator task new, then retry.", req.json);
+    }
+    return recordProof(req, root, kind, titles, task);
+}

package/dist/cli/proofs.d.ts

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

package/dist/cli/proofs.js

@@ -0,0 +1,168 @@
+// SPEC §4.12.4: review rounds. Submit validates the findings file and
+// verdicts it; resolve reports the still-open blockers and majors. Rounds
+// bind the staged tree and the reviewer session on the task record.
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { checkReview } from "../features/workflow/index.js";
+import { NodeFs, ok, parseJson } from "../kernel/index.js";
+import { fail, loadRepoConfig, needTaskRoot, portsFor, printHuman, printJson, readStateText, usageError, } from "./shared.js";
+import { readTask, writeTask } from "./tasks.js";
+function parseReviewArgs(req) {
+    try {
+        const parsed = parseArgs({
+            args: [...req.args.slice(1)],
+            options: { file: { type: "string" }, task: { type: "string" } },
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return undefined;
+        }
+        if ((parsed.values.file ?? "") === "") {
+            return undefined;
+        }
+        return { file: parsed.values.file ?? "", taskId: parsed.values.task };
+    }
+    catch {
+        return undefined;
+    }
+}
+// SPEC §4.12.4: absolute --file inputs are canonicalized before the
+// root-prefix comparison, so symlinked checkouts (macOS /var to
+// /private/var, Windows SUBST drives) compare canonical against canonical.
+// The root is already canonical via resolveRepoRoot; only the kernel
+// touches node:fs (§10.3 item 3), so the input goes through NodeFs the same
+// way the hook runtime's canonicalRoot does. Inputs that do not resolve
+// keep their spelling and fail closed downstream as CDX-E607.
+async function canonicalDir(dir) {
+    const made = await NodeFs.create({ root: dir });
+    if (!made.ok) {
+        return dir;
+    }
+    const real = await made.value.realpath(".");
+    if (!real.ok) {
+        return dir;
+    }
+    return real.value;
+}
+async function readFindingsFile(root, file) {
+    if (!path.isAbsolute(file)) {
+        return readStateText(root, file);
+    }
+    const realRoot = await canonicalDir(root);
+    const realFile = path.join(await canonicalDir(path.dirname(file)), path.basename(file));
+    const rel = path.relative(realRoot, realFile);
+    if (rel === "" ||
+        rel === ".." ||
+        rel.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(rel)) {
+        return undefined;
+    }
+    return readStateText(root, rel);
+}
+function validateFindingsFile(text, file, req) {
+    const parsedJson = parseJson(text);
+    if (!parsedJson.ok ||
+        typeof parsedJson.value !== "object" ||
+        parsedJson.value === null) {
+        return fail("CDX-E607", `review findings file "${file}" is not JSON`, "Fix the file so it matches schema/review-findings.schema.json, then retry.", req.json);
+    }
+    const shaped = parsedJson.value;
+    if (shaped.version !== 1 || !Array.isArray(shaped.findings)) {
+        return fail("CDX-E607", `review findings file "${file}" is invalid`, "Fix the file so it matches schema/review-findings.schema.json, then retry.", req.json);
+    }
+    return {
+        version: 1,
+        findings: shaped.findings,
+        tree: shaped.tree,
+        reviewerSession: shaped.reviewerSession,
+    };
+}
+async function loadFindingsShape(req, root, file) {
+    const loaded = await readFindingsFile(root, file);
+    if (loaded === undefined) {
+        return fail("CDX-E607", `review findings file "${file}" unreadable`, "Point --file at the findings JSON, then retry.", req.json);
+    }
+    return validateFindingsFile(loaded, file, req);
+}
+function printReviewVerdict(req, sub, file, verdict, blockers) {
+    if (req.json) {
+        printJson({ file, findings: verdict.length, blockers });
+        return;
+    }
+    for (const finding of verdict) {
+        printHuman(`${finding.ruleId}  ${finding.message}`, req.quiet);
+    }
+    if (verdict.length === 0) {
+        printHuman(sub === "submit" ? "review submitted: pass" : "review resolved: clean", req.quiet);
+    }
+}
+async function submitReviewRound(root, taskId, shaped, openBlockers, openMajors, now) {
+    const task = await readTask(root, taskId);
+    if (task === undefined) {
+        return;
+    }
+    const rounds = task.reviews ?? [];
+    await writeTask(root, {
+        ...task,
+        reviews: [
+            ...rounds,
+            {
+                round: rounds.length + 1,
+                tree: typeof shaped.tree === "string" ? shaped.tree : "unknown",
+                reviewerSession: typeof shaped.reviewerSession === "string"
+                    ? shaped.reviewerSession
+                    : "cli",
+                identity: "observed",
+                openBlockers,
+                openMajors,
+                acknowledgedExceptions: [],
+                at: now,
+            },
+        ],
+    });
+}
+// SPEC §4.12.4: review rounds bind the staged tree and the reviewer
+// session; submit validates the findings file and verdicts it, resolve
+// reports the still-open blockers and majors.
+export async function handleReview(req) {
+    const sub = req.args[0] ?? "";
+    if (sub !== "submit" && sub !== "resolve") {
+        return usageError("usage: codictator review <submit|resolve> --file <path> [--task <T-####>]");
+    }
+    const parsed = parseReviewArgs(req);
+    if (parsed === undefined) {
+        return usageError("usage: codictator review <submit|resolve> --file <path> [--task <T-####>]");
+    }
+    const root = await needTaskRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    const shaped = await loadFindingsShape(req, root, parsed.file);
+    if (!("version" in shaped)) {
+        return shaped;
+    }
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return fail("CDX-E903", ports.error.message, ports.error.remediation, req.json);
+    }
+    let configHash = "unknown";
+    const configured = await loadRepoConfig(root, undefined, req.engineVersion ?? ENGINE_VERSION);
+    if (configured.ok) {
+        configHash = configured.value.effective.configHash;
+    }
+    const verdict = await checkReview({
+        trigger: "pre-tool",
+        scope: { files: [] },
+        now: ports.value.clock.now(),
+        configHash,
+    }, shaped, {});
+    const blockers = verdict.filter((finding) => finding.ruleId === "core/review-blockers" || finding.code === "CDX-E605");
+    printReviewVerdict(req, sub, parsed.file, verdict, blockers.length);
+    if (parsed.taskId !== undefined &&
+        sub === "submit" &&
+        blockers.length === 0) {
+        await submitReviewRound(root, parsed.taskId, shaped, 0, 0, ports.value.clock.now());
+    }
+    return verdict.length === 0 ? ok(0) : ok(1);
+}

package/dist/cli/remediation.d.ts

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

package/dist/cli/remediation.js

@@ -0,0 +1,107 @@
+// SPEC §4.13: remediation plan, next step, single-step run and status.
+// The plan generates from the baseline through the owning planner;
+// single steps run behind their gate evidence (CDX-E608 without it).
+import { planRemediation, runStep, } from "../features/remediation/index.js";
+import { ok, parseJson, stableStringify } from "../kernel/index.js";
+import { fail, needRoot, printHuman, printJson, readStateText, usageError, writeStateText, } from "./shared.js";
+function toBaseline(value) {
+    const fallback = { version: 1, entries: {} };
+    if (typeof value !== "object" || value === null) {
+        return fallback;
+    }
+    const entries = value.entries;
+    if (typeof entries !== "object" || entries === null) {
+        return fallback;
+    }
+    return { version: 1, entries: entries };
+}
+function toPlan(value) {
+    if (typeof value !== "object" || value === null) {
+        return undefined;
+    }
+    const steps = value.steps;
+    if (!Array.isArray(steps)) {
+        return undefined;
+    }
+    return value;
+}
+async function remediatePlan(req, root) {
+    if (req.args.length !== 1) {
+        return usageError("usage: codictator remediate plan");
+    }
+    const baselineText = await readStateText(root, ".codictator/baseline.json");
+    const parsedBaseline = baselineText === undefined ? undefined : parseJson(baselineText);
+    const baseline = parsedBaseline?.ok === true
+        ? toBaseline(parsedBaseline.value)
+        : { version: 1, entries: {} };
+    const planned = await planRemediation(baseline, []);
+    if (!planned.ok) {
+        return fail("CDX-E903", planned.error.message, planned.error.remediation, req.json);
+    }
+    const saved = await writeStateText(root, ".codictator/remediation-plan.json", `${stableStringify(planned.value)}\n`);
+    if (!saved.ok) {
+        return fail("CDX-E903", saved.error.message, saved.error.remediation, req.json);
+    }
+    printHuman(`planned ${planned.value.steps.length} step(s)`, req.quiet);
+    return ok(0);
+}
+function remediateStatus(plan, req) {
+    const done = plan.steps.filter((step) => step.status === "done").length;
+    if (req.json) {
+        printJson({ done, total: plan.steps.length });
+    }
+    else {
+        printHuman(`remediation progress: ${done}/${plan.steps.length} done`, req.quiet);
+    }
+    return ok(0);
+}
+function remediateNext(plan, req) {
+    const next = plan.steps.find((step) => step.status !== "done");
+    if (next === undefined) {
+        printHuman("remediation plan complete", req.quiet);
+        return ok(0);
+    }
+    printHuman(`next step: ${String(next.id ?? "unknown")}`, req.quiet);
+    return ok(0);
+}
+async function remediateRun(plan, req) {
+    const id = req.args[1] ?? "";
+    if (id === "" || req.args.length !== 2) {
+        return usageError("usage: codictator remediate run <id>");
+    }
+    const ran = await runStep(plan, id);
+    if (!ran.ok) {
+        return fail(ran.error.code, ran.error.message, ran.error.remediation, req.json);
+    }
+    printHuman(`ran step ${id}: gate evidence required before completion`, req.quiet);
+    return ok(1);
+}
+export async function handleRemediate(req) {
+    const sub = req.args[0] ?? "";
+    if (sub !== "plan" && sub !== "next" && sub !== "run" && sub !== "status") {
+        return usageError("usage: codictator remediate <plan|next|run <id>|status>");
+    }
+    const root = await needRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    if (sub === "plan") {
+        return remediatePlan(req, root);
+    }
+    const planText = await readStateText(root, ".codictator/remediation-plan.json");
+    if (planText === undefined) {
+        return fail("CDX-E903", "no remediation plan", "Run codictator remediate plan first, then retry.", req.json);
+    }
+    const plan = parseJson(planText);
+    const shaped = plan.ok ? toPlan(plan.value) : undefined;
+    if (!plan.ok || shaped === undefined) {
+        return fail("CDX-E903", "remediation plan is not a plan", "Rerun codictator remediate plan, then retry.", req.json);
+    }
+    if (sub === "status") {
+        return remediateStatus(shaped, req);
+    }
+    if (sub === "next") {
+        return remediateNext(shaped, req);
+    }
+    return remediateRun(shaped, req);
+}

package/dist/cli/report.d.ts

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

package/dist/cli/report.js

@@ -0,0 +1,93 @@
+// SPEC §4.18.5 + §4.19.2: report and context. Report computes PRD §10
+// metrics from local sources only; context prints the current scoped
+// injection (§4.6.3), with --all adding config hash and harness list.
+import { parseArgs } from "node:util";
+import { buildReportText } from "../features/audit/index.js";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { buildManagedBlock, PRECEDENCE_STATEMENT, } from "../features/steering/index.js";
+import { ok } from "../kernel/index.js";
+import { readLogEvents } from "./inspect.js";
+import { fail, loadRepoConfig, needRoot, portsFor, printHuman, printJson, usageError, } from "./shared.js";
+// SPEC §4.18.5: PRD §10 metrics from local sources only.
+export async function handleReport(req) {
+    try {
+        const parsed = parseArgs({
+            args: [...req.args],
+            options: {},
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return usageError("usage: codictator report");
+        }
+    }
+    catch {
+        return usageError("usage: codictator report");
+    }
+    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 log = await readLogEvents(root);
+    if (log === undefined) {
+        return fail("CDX-E903", "event log unreadable", "Fix permissions on .codictator/state/, then retry.", req.json);
+    }
+    const text = buildReportText({
+        events: log.events,
+        corrupt: log.corrupt,
+        now: ports.value.clock.now(),
+    });
+    if (req.json) {
+        printJson({
+            now: ports.value.clock.now(),
+            events: log.events.length,
+            corrupt: log.corrupt,
+            text,
+        });
+    }
+    else {
+        printHuman(text, req.quiet);
+    }
+    return ok(0);
+}
+// SPEC §4.19.2: the current scoped injection (§4.6.3); --all adds config
+// hash and harness list.
+export async function handleContext(req) {
+    let all = false;
+    try {
+        const parsed = parseArgs({
+            args: [...req.args],
+            options: { all: { type: "boolean", default: false } },
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return usageError("usage: codictator context [--all]");
+        }
+        all = parsed.values.all ?? false;
+    }
+    catch {
+        return usageError("usage: codictator context [--all]");
+    }
+    const root = await needRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    let extra = "";
+    if (all) {
+        const configured = await loadRepoConfig(root, undefined, req.engineVersion ?? ENGINE_VERSION);
+        extra = configured.ok
+            ? `\nconfig ${configured.value.effective.configHash} harnesses ${configured.value.effective.config.harnesses.join(",")}`
+            : "\nconfig unknown (unreadable)";
+    }
+    const text = `${PRECEDENCE_STATEMENT}\n\n${buildManagedBlock()}${extra}`;
+    if (req.json) {
+        printJson({ context: text });
+    }
+    else {
+        printHuman(text, req.quiet);
+    }
+    return ok(0);
+}

package/dist/cli/serve-eval.d.ts

@@ -0,0 +1,2 @@
+import { type MethodContext, type MethodOutcome } from "./serve-shared.ts";
+export declare function dispatchEvalMethod(method: string, params: unknown, ctx: MethodContext): Promise<MethodOutcome | undefined>;