codictator 0.0.0 → 0.1.3

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

package/dist/cli/serve-eval.js

@@ -0,0 +1,165 @@
+// SPEC §7.15: stdio evaluation rows. `findings/list` and `verify` run
+// the same engine evaluation the `verify` command uses; log and budget
+// rows live in serve-log.ts.
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { isFixturePath } from "../kernel/index.js";
+import { evaluateScope, resolveVerifyScope, triggerForLayer, } from "./evaluate.js";
+import { dispatchLogMethod } from "./serve-log.js";
+import { invalidParamsError } from "./serve-protocol.js";
+import { field, isRecord, methodOk, resolveRoot, } from "./serve-shared.js";
+import { loadRepoConfig } from "./shared.js";
+function methodFail(code, message, remediation) {
+    return {
+        ok: false,
+        error: {
+            code: -32000,
+            message: `${code} ${message}`,
+            data: { code, remediation },
+        },
+    };
+}
+function stringArrayField(params, name) {
+    if (!isRecord(params)) {
+        return undefined;
+    }
+    const found = field(params, name);
+    if (!Array.isArray(found)) {
+        return undefined;
+    }
+    const files = [];
+    for (const entry of found) {
+        if (typeof entry !== "string") {
+            return undefined;
+        }
+        files.push(entry);
+    }
+    return files;
+}
+// The shared scope-and-evaluate flow: files when named, else the tracked
+// tree plus staged edits like the bare `verify` command; pack fixtures
+// stay out of every scope (§4.4.1). Answers findings with the config hash.
+async function evaluateFiles(ctx, files, layer) {
+    const root = await resolveRoot(ctx.root);
+    const configured = await loadRepoConfig(root, undefined, ctx.engineVersion ?? ENGINE_VERSION);
+    if (!configured.ok) {
+        return methodFail(configured.error.code, configured.error.message, "Fix .codictator/config.json, then retry.");
+    }
+    const scoped = files === undefined
+        ? await resolveVerifyScope(configured.value.ports, {
+            staged: false,
+            all: true,
+            base: undefined,
+            head: undefined,
+            layer,
+        })
+        : {
+            ok: true,
+            value: {
+                trigger: triggerForLayer(layer),
+                files: [...new Set(files)]
+                    .sort()
+                    .filter((file) => !isFixturePath(file)),
+                note: "stdio files",
+            },
+        };
+    if (!scoped.ok) {
+        return methodFail(scoped.error.code, scoped.error.message, scoped.error.remediation);
+    }
+    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 methodFail(evaluated.error.code, evaluated.error.message, evaluated.error.remediation);
+    }
+    return methodOk({
+        findings: evaluated.value,
+        configHash: configured.value.effective.configHash,
+    });
+}
+function evaluatedParts(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    return {
+        findings: field(value, "findings"),
+        configHash: field(value, "configHash"),
+    };
+}
+// SPEC §7.15: `findings/list { files? }` answers findings with remediation.
+async function findingsListMethod(params, ctx) {
+    const files = stringArrayField(params, "files");
+    if (params !== undefined && !isRecord(params)) {
+        return {
+            ok: false,
+            error: invalidParamsError("findings/list params must be { files? }"),
+        };
+    }
+    if (isRecord(params) &&
+        field(params, "files") !== undefined &&
+        files === undefined) {
+        return {
+            ok: false,
+            error: invalidParamsError("findings/list files must be an array of strings"),
+        };
+    }
+    const evaluated = await evaluateFiles(ctx, files, undefined);
+    if (!evaluated.ok) {
+        return evaluated;
+    }
+    const parts = evaluatedParts(evaluated.value);
+    const findings = Array.isArray(parts?.findings) ? parts?.findings : [];
+    return methodOk({
+        decision: findings.length === 0 ? "allow" : "block",
+        findings,
+        configHash: parts?.configHash ?? "",
+    });
+}
+const LAYERS = new Set(["L1", "L2", "L3", "L4", "L5"]);
+// SPEC §7.15: `verify { layer, files? }` answers a verdict for the layer.
+async function verifyMethod(params, ctx) {
+    if (!isRecord(params)) {
+        return {
+            ok: false,
+            error: invalidParamsError("verify params must be { layer, files? }"),
+        };
+    }
+    const layer = field(params, "layer");
+    if (typeof layer !== "string" || !LAYERS.has(layer)) {
+        return {
+            ok: false,
+            error: invalidParamsError("verify layer must be one of L1..L5"),
+        };
+    }
+    const files = stringArrayField(params, "files");
+    if (field(params, "files") !== undefined && files === undefined) {
+        return {
+            ok: false,
+            error: invalidParamsError("verify files must be an array of strings"),
+        };
+    }
+    const evaluated = await evaluateFiles(ctx, files, layer);
+    if (!evaluated.ok) {
+        return evaluated;
+    }
+    const parts = evaluatedParts(evaluated.value);
+    const findings = Array.isArray(parts?.findings) ? parts?.findings : [];
+    return methodOk({
+        verdict: findings.length === 0 ? "allow" : "block",
+        layer,
+        findings,
+        configHash: parts?.configHash ?? "",
+    });
+}
+// SPEC §7.15 rows owned here; the log rows by serve-log.ts; unknown names
+// return undefined so the caller answers method-not-found.
+export async function dispatchEvalMethod(method, params, ctx) {
+    switch (method) {
+        case "findings/list": {
+            return findingsListMethod(params, ctx);
+        }
+        case "verify": {
+            return verifyMethod(params, ctx);
+        }
+        default: {
+            return dispatchLogMethod(method, params, ctx);
+        }
+    }
+}

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

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

package/dist/cli/serve-log.js

@@ -0,0 +1,150 @@
+// SPEC §7.15: stdio log and budget rows. Event tails and steering
+// history page the same event log the audit surfaces read; the budget row
+// answers per-session bands, or unavailable when no usage applies.
+import { currentBand } from "../features/steering/index.js";
+import { readLogEvents } from "./inspect.js";
+import { invalidParamsError } from "./serve-protocol.js";
+import { field, isRecord, methodOk, resolveRoot, } from "./serve-shared.js";
+function numberField(params, name) {
+    if (!isRecord(params)) {
+        return undefined;
+    }
+    const found = field(params, name);
+    return typeof found === "number" ? found : undefined;
+}
+// SPEC §7.15: `events/tail { since?, limit }` pages the event log.
+async function eventsTailMethod(params, ctx) {
+    if (params !== undefined && !isRecord(params)) {
+        return {
+            ok: false,
+            error: invalidParamsError("events/tail params must be { since?, limit? }"),
+        };
+    }
+    const root = await resolveRoot(ctx.root);
+    const log = await readLogEvents(root);
+    if (log === undefined) {
+        return {
+            ok: false,
+            error: {
+                code: -32000,
+                message: "CDX-E903 event log unreadable",
+                data: {
+                    code: "CDX-E903",
+                    remediation: "Fix permissions on .codictator/state/, then retry.",
+                },
+            },
+        };
+    }
+    let since;
+    let limit = 100;
+    if (isRecord(params)) {
+        const rawSince = field(params, "since");
+        if (rawSince !== undefined && typeof rawSince !== "string") {
+            return {
+                ok: false,
+                error: invalidParamsError("events/tail since must be an event id string"),
+            };
+        }
+        since = typeof rawSince === "string" ? rawSince : undefined;
+        const rawLimit = numberField(params, "limit");
+        if (field(params, "limit") !== undefined) {
+            if (rawLimit === undefined ||
+                !Number.isSafeInteger(rawLimit) ||
+                rawLimit <= 0) {
+                return {
+                    ok: false,
+                    error: invalidParamsError("events/tail limit must be a positive integer"),
+                };
+            }
+            limit = Math.min(rawLimit, 1000);
+        }
+    }
+    let start = 0;
+    if (since !== undefined) {
+        const at = log.events.findIndex((event) => event.id === since);
+        start = at === -1 ? log.events.length : at + 1;
+    }
+    return methodOk({
+        events: log.events.slice(start, start + limit),
+        corrupt: log.corrupt,
+    });
+}
+// SPEC §7.15: `steering/history { sessionId? }` answers injections,
+// optionally for one session.
+async function steeringHistoryMethod(params, ctx) {
+    if (params !== undefined && !isRecord(params)) {
+        return {
+            ok: false,
+            error: invalidParamsError("steering/history params must be { sessionId? }"),
+        };
+    }
+    let sessionId;
+    if (isRecord(params)) {
+        const raw = field(params, "sessionId");
+        if (raw !== undefined && typeof raw !== "string") {
+            return {
+                ok: false,
+                error: invalidParamsError("steering/history sessionId must be a string"),
+            };
+        }
+        sessionId = typeof raw === "string" ? raw : undefined;
+    }
+    const root = await resolveRoot(ctx.root);
+    const log = await readLogEvents(root);
+    if (log === undefined) {
+        return methodOk({ injections: [] });
+    }
+    return methodOk({
+        injections: log.events.filter((event) => event.kind === "injection" &&
+            (sessionId === undefined || event.sessionId === sessionId)),
+    });
+}
+// SPEC §7.15: `budget/current` answers per-session bands, or unavailable
+// when no usage applies (§4.6.7 EC-4).
+async function budgetCurrentMethod(params) {
+    if (params !== undefined && !isRecord(params)) {
+        return {
+            ok: false,
+            error: invalidParamsError("budget/current params must be { sessionId? }"),
+        };
+    }
+    let sessionId = "stdio";
+    if (isRecord(params)) {
+        const raw = field(params, "sessionId");
+        if (raw !== undefined && typeof raw !== "string") {
+            return {
+                ok: false,
+                error: invalidParamsError("budget/current sessionId must be a string"),
+            };
+        }
+        if (typeof raw === "string" && raw !== "") {
+            sessionId = raw;
+        }
+    }
+    const band = await currentBand(sessionId);
+    return methodOk({
+        available: band.available,
+        status: band.available ? band.band : "unavailable",
+        band: band.band,
+        contextWindow: band.contextWindow,
+        usedTokens: band.usedTokens,
+    });
+}
+// SPEC §7.15 log rows owned here; unknown names return undefined so the
+// caller answers method-not-found.
+export async function dispatchLogMethod(method, params, ctx) {
+    switch (method) {
+        case "events/tail": {
+            return eventsTailMethod(params, ctx);
+        }
+        case "steering/history": {
+            return steeringHistoryMethod(params, ctx);
+        }
+        case "budget/current": {
+            return budgetCurrentMethod(params);
+        }
+        default: {
+            return undefined;
+        }
+    }
+}

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

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