codictator 0.0.0 → 0.1.2

package/dist/cli/shared.js

@@ -0,0 +1,181 @@
+// SPEC §4.19: shared CLI plumbing. The command tables in commands.ts and
+// the handlers beside it build on this: global flags, ports, output and
+// the §8.2 exit mapping. Emits to stdout/stderr like runHook does; TAP
+// parsers skip non-TAP lines, so test output stays parseable.
+import { errorRowFor } from "../features/audit/index.js";
+import { ENGINE_VERSION, loadConfig as loadConfigImpl, requireHuman, } from "../features/config/index.js";
+import { err, makeError, NodeEnv, NodeFs, NodeGit, NodeNet, NodeProc, ok, resolveRepoRoot, SystemClock, stableStringify, } from "../kernel/index.js";
+// SPEC §2.3 with §4.19.4: the engine's node floor. The launcher enforces it
+// before the engine starts; the CLI start path enforces it here, so a
+// direct dist invocation fails the same way.
+export const MIN_NODE_MAJOR = 24;
+export function nodeMajor(version) {
+    const match = /^v(\d+)\.[0-9]+\.[0-9]+/.exec(version);
+    if (match === null) {
+        return 0;
+    }
+    const major = Number.parseInt(match[1] ?? "0", 10);
+    return Number.isSafeInteger(major) ? major : 0;
+}
+export function nodeTooOldMessage(version) {
+    return `CDX-E002 node ${version} is older than the required >=${MIN_NODE_MAJOR}.0.0.0; install a newer Node, then retry the tool call.`;
+}
+// SPEC §4.19.1: human output is terse; `--quiet` suppresses human lines
+// (errors still land on stderr, `--json` output is unaffected).
+export function printHuman(text, quiet) {
+    if (!quiet) {
+        process.stdout.write(`${text}\n`);
+    }
+}
+export function printJson(value) {
+    process.stdout.write(`${stableStringify(value)}\n`);
+}
+// SPEC §8.2: the exit for an error code; unknown codes are internal (7).
+export function exitFor(code) {
+    return errorRowFor(code)?.exit ?? 7;
+}
+// Every error path prints before returning, so the built entry only maps
+// the Result to its exit code. `--json` renders the error envelope.
+export function reportError(error, json) {
+    if (json) {
+        printJson({
+            code: error.code,
+            message: error.message,
+            ...(error.detail === undefined ? {} : { detail: error.detail }),
+            remediation: error.remediation,
+        });
+    }
+    else {
+        process.stderr.write(`${error.code} ${error.message}\n`);
+        process.stderr.write(`Do instead: ${error.remediation}\n`);
+    }
+    return err(error);
+}
+export function fail(code, message, remediation, json, detail) {
+    return reportError(makeError(code, message, remediation, detail), json);
+}
+// SPEC §4.19.6 EC-1: unknown command or flag is a usage error, not a
+// CdxError row: usage line on stderr, exit 2.
+export function usageError(text) {
+    process.stderr.write(`${text}\n`);
+    return ok(2);
+}
+export function isTty() {
+    return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+// SPEC §4.2.3: human-only commands refuse agents and non-TTYs with
+// CDX-E107; requireHuman throws, so this narrows it to a Result.
+export function checkHuman(env, agentMarkers) {
+    try {
+        requireHuman(env, isTty(), agentMarkers);
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            typeof error.code === "string") {
+            const coded = error;
+            return err(coded);
+        }
+        return err(makeError("CDX-E901", "human gate failed without a coded error", "Retry in an interactive terminal."));
+    }
+    return ok(undefined);
+}
+// Ports for command handlers: kernel-owned live ports; the Fs stays
+// per-root and is created after the repo root resolves.
+export function commandEnv() {
+    return new NodeEnv();
+}
+export async function portsFor(root, env = commandEnv()) {
+    const made = await NodeFs.create({ root });
+    if (!made.ok) {
+        return err(made.error);
+    }
+    const proc = new NodeProc();
+    return ok({
+        fs: made.value,
+        proc,
+        net: new NodeNet(),
+        clock: new SystemClock(),
+        git: new NodeGit(proc, root),
+        env,
+        root,
+    });
+}
+// CLI-owned state helpers. Command state (tasks, checkpoints, waivers,
+// baselines, plans) lives in repo-relative JSON the owning module's
+// validator approves; the CLI never invents a §7 format here.
+export async function readStateText(root, rel) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return undefined;
+    }
+    const seen = await ports.value.fs.exists(rel);
+    if (!seen.ok || !seen.value) {
+        return undefined;
+    }
+    const text = await ports.value.fs.readText(rel);
+    return text.ok ? text.value : undefined;
+}
+function encodeState(text) {
+    return new TextEncoder().encode(text);
+}
+export async function needRoot(req) {
+    const root = await resolveRepoRoot(req.cwd);
+    if (!root.ok) {
+        return fail("CDX-E703", root.error.message, root.error.remediation, req.json);
+    }
+    return root.value;
+}
+export async function needTaskRoot(req) {
+    return needRoot(req);
+}
+export async function writeStateText(root, rel, text) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return err(ports.error);
+    }
+    const done = await ports.value.fs.write(rel, encodeState(text));
+    if (!done.ok) {
+        return err(done.error);
+    }
+    return ok(undefined);
+}
+// SPEC §4.2.1 + §4.1.1: config loads through caller-owned ports against
+// the logical root ".", so every audit path stays repo-relative and the
+// confinement check never sees an absolute path (the hook runtime's own
+// pattern). Throws become Results carrying their SPEC row.
+export async function loadRepoConfig(root, env = commandEnv(), engineVersion = ENGINE_VERSION) {
+    const ports = await portsFor(root, env);
+    if (!ports.ok) {
+        return err(ports.error);
+    }
+    try {
+        const effective = await loadConfigImpl(".", ports.value, engineVersion);
+        return ok({ ports: ports.value, effective });
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            typeof error.code === "string" &&
+            "message" in error &&
+            typeof error.message === "string" &&
+            "remediation" in error &&
+            typeof error.remediation === "string") {
+            const coded = error;
+            return err({
+                code: coded.code,
+                message: coded.message,
+                remediation: coded.remediation,
+                ...(typeof coded.detail === "string" ? { detail: coded.detail } : {}),
+            });
+        }
+        const message = error instanceof Error ? error.message : "config unreadable";
+        return err({
+            code: "CDX-E101",
+            message,
+            remediation: "Fix .codictator/config.json, then retry.",
+        });
+    }
+}

package/dist/cli/task-advance.d.ts

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

package/dist/cli/task-advance.js

@@ -0,0 +1,144 @@
+// SPEC §4.12.2: task advancement. Phase order follows the seven mandatory
+// phases through the owning gate; checkpoint and close are cache state,
+// while ack clears an escalation and stays human-only.
+import { parseArgs } from "node:util";
+import { ok } from "../kernel/index.js";
+import { checkHuman, commandEnv, fail, needTaskRoot, printHuman, printJson, usageError, } from "./shared.js";
+import { taskPhaseNext } from "./task-phases.js";
+import { listTaskIds, readTask, taskCheckpoint, taskClose, taskLine, taskNew, writeTask, } from "./tasks.js";
+async function taskAck(req, root, task, id, note) {
+    const human = checkHuman(commandEnv(), []);
+    if (!human.ok) {
+        return fail("CDX-E107", human.error.message, human.error.remediation, req.json);
+    }
+    if (note === "") {
+        return usageError("usage: codictator task ack --id <T-####> --note <text>");
+    }
+    const open = (task.escalations ?? []).filter((entry) => entry.ackedBy === undefined);
+    if (open.length === 0) {
+        printHuman(`no open escalations on ${id}`, req.quiet);
+        return ok(0);
+    }
+    const acked = {
+        ...task,
+        escalations: (task.escalations ?? []).map((entry) => entry.ackedBy === undefined
+            ? { ...entry, ackedBy: "human", note }
+            : entry),
+    };
+    const saved = await writeTask(root, acked);
+    if (!saved.ok) {
+        return saved;
+    }
+    printHuman(`acked ${open.length} escalation(s) on ${id}`, req.quiet);
+    return ok(0);
+}
+async function taskAmend(req, root, task, title, type) {
+    if (title === undefined && type === undefined) {
+        return usageError("usage: codictator task amend --id <T-####> [--title <t>] [--type <t>]");
+    }
+    const amended = {
+        ...task,
+        ...(title === undefined ? {} : { title }),
+        ...(type === undefined ? {} : { type }),
+    };
+    const saved = await writeTask(root, amended);
+    if (!saved.ok) {
+        return saved;
+    }
+    printHuman(`amended ${taskLine(amended)}`, req.quiet);
+    return ok(0);
+}
+async function taskMutate(req, root, sub) {
+    let id = "";
+    let title;
+    let type;
+    let note = "";
+    try {
+        const parsed = parseArgs({
+            args: [...req.args.slice(1)],
+            options: {
+                id: { type: "string" },
+                title: { type: "string" },
+                type: { type: "string" },
+                note: { type: "string", default: "" },
+            },
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return usageError(`usage: codictator task ${sub} --id <T-####> ...`);
+        }
+        id = parsed.values.id ?? "";
+        title = parsed.values.title;
+        type = parsed.values.type;
+        note = parsed.values.note ?? "";
+    }
+    catch {
+        return usageError(`usage: codictator task ${sub} --id <T-####> ...`);
+    }
+    const task = await readTask(root, id);
+    if (task === undefined) {
+        return fail("CDX-E903", `no task record for "${id}"`, "List tasks with codictator task show, then retry.", req.json);
+    }
+    if (sub === "ack") {
+        return taskAck(req, root, task, id, note);
+    }
+    if (sub === "amend") {
+        return taskAmend(req, root, task, title, type);
+    }
+    return taskClose(req, root, id);
+}
+// SPEC §4.19.2 + §4.12: task lifecycle reads and writes; only ack is
+// human-only, and only it clears an escalation.
+export async function handleTask(req) {
+    const root = await needTaskRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    const sub = req.args[0] ?? "";
+    if (sub === "new") {
+        return taskNew(req, root);
+    }
+    if (sub === "show") {
+        return taskShow(req, root);
+    }
+    if (sub === "phase" && req.args[1] === "next") {
+        return taskPhaseNext(req, root);
+    }
+    if (sub === "checkpoint") {
+        return taskCheckpoint(req, root);
+    }
+    if (sub === "ack" || sub === "amend" || sub === "close") {
+        return taskMutate(req, root, sub);
+    }
+    return usageError("usage: codictator task <new|show|amend|phase next|checkpoint|close|ack> ...");
+}
+async function taskShow(req, root) {
+    const ids = await listTaskIds(root);
+    if (req.args.length === 1) {
+        if (req.json) {
+            printJson({ tasks: ids });
+        }
+        else if (ids.length === 0) {
+            printHuman("no tasks recorded", req.quiet);
+        }
+        else {
+            for (const id of ids) {
+                const task = await readTask(root, id);
+                printHuman(task === undefined ? id : taskLine(task), req.quiet);
+            }
+        }
+        return ok(0);
+    }
+    const id = req.args[1] ?? "";
+    const task = await readTask(root, id);
+    if (task === undefined) {
+        return fail("CDX-E903", `no task record for "${id}"`, "List tasks with codictator task show, then retry.", req.json);
+    }
+    if (req.json) {
+        printJson(task);
+    }
+    else {
+        printHuman(taskLine(task), req.quiet);
+    }
+    return ok(0);
+}

package/dist/cli/task-phases.d.ts

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

package/dist/cli/task-phases.js

@@ -0,0 +1,77 @@
+// SPEC §4.12.2: task phase advancement. The next-phase gate check and the
+// phase entry write live here; dispatch stays in task-advance.ts.
+import { parseArgs } from "node:util";
+import { checkPhaseGate, MANDATORY_PHASES, } from "../features/workflow/index.js";
+import { ok } from "../kernel/index.js";
+import { fail, portsFor, printHuman, printJson, usageError } from "./shared.js";
+import { readTask, writeTask } from "./tasks.js";
+async function gateForNextPhase(task, next) {
+    const gate = await checkPhaseGate(task, next, {});
+    return gate.map((finding) => ({
+        ruleId: finding.ruleId,
+        message: finding.message,
+        remediation: finding.remediation,
+    }));
+}
+async function applyPhaseEntry(root, task, next, now) {
+    const moved = {
+        ...task,
+        phase: next,
+        phases: [
+            ...task.phases,
+            { name: next, enteredAt: now, evidence: "codictator task phase next" },
+        ],
+    };
+    return writeTask(root, moved);
+}
+export async function taskPhaseNext(req, root) {
+    let id = "";
+    try {
+        const parsed = parseArgs({
+            args: [...req.args.slice(2)],
+            options: { id: { type: "string" } },
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return usageError("usage: codictator task phase next --id <T-####>");
+        }
+        id = parsed.values.id ?? "";
+    }
+    catch {
+        return usageError("usage: codictator task phase next --id <T-####>");
+    }
+    const task = await readTask(root, id);
+    if (task === undefined) {
+        return fail("CDX-E903", `no task record for "${id}"`, "List tasks with codictator task show, then retry.", req.json);
+    }
+    const at = MANDATORY_PHASES.indexOf(task.phase);
+    const next = at >= 0 ? MANDATORY_PHASES[at + 1] : undefined;
+    if (next === undefined) {
+        return fail("CDX-E604", `task ${id} is past its last phase`, "Close the task instead.", req.json);
+    }
+    const blocked = await gateForNextPhase(task, next);
+    if (blocked.length > 0) {
+        if (req.json) {
+            printJson({ id, phase: task.phase, blocked });
+        }
+        else {
+            for (const finding of blocked) {
+                printHuman(`${finding.ruleId}  ${finding.message}`, req.quiet);
+                printHuman(`Do instead: ${finding.remediation}`, req.quiet);
+            }
+        }
+        return ok(1);
+    }
+    const ports = await portsFor(root);
+    const saved = await applyPhaseEntry(root, task, next, ports.ok ? ports.value.clock.now() : "");
+    if (!saved.ok) {
+        return saved;
+    }
+    if (req.json) {
+        printJson({ id, phase: next });
+    }
+    else {
+        printHuman(`task ${id} entered ${next}`, req.quiet);
+    }
+    return ok(0);
+}

package/dist/cli/tasks.d.ts

@@ -0,0 +1,12 @@
+import { type TaskRecord } from "../features/workflow/index.ts";
+import type { Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare const TASKS_DIR = ".codictator/tasks";
+export declare function listTaskIds(root: string): Promise<Array<string>>;
+export declare function readTask(root: string, id: string): Promise<TaskRecord | undefined>;
+export declare function writeTask(root: string, task: TaskRecord): Promise<Result<number>>;
+export declare function taskLine(task: TaskRecord): string;
+export declare function branchOf(root: string): Promise<string | undefined>;
+export declare function taskNew(req: CommandRequest, root: string): Promise<Result<number>>;
+export declare function taskCheckpoint(req: CommandRequest, root: string): Promise<Result<number>>;
+export declare function taskClose(req: CommandRequest, root: string, id: string): Promise<Result<number>>;

package/dist/cli/tasks.js

@@ -0,0 +1,176 @@
+// SPEC §4.12: task records. State lives in repo-relative JSON the workflow
+// module validates; creation binds the branch, and listing surfaces every
+// record through the same terse line.
+import { parseArgs } from "node:util";
+import { isTaskId, taskIdFor, validateTaskRecord, } from "../features/workflow/index.js";
+import { ok, parseJson, stableStringify } from "../kernel/index.js";
+import { fail, portsFor, printHuman, printJson, usageError, writeStateText, } from "./shared.js";
+export const TASKS_DIR = ".codictator/tasks";
+export async function listTaskIds(root) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return [];
+    }
+    const listed = await ports.value.fs.list(TASKS_DIR);
+    if (!listed.ok) {
+        return [];
+    }
+    return listed.value
+        .filter((name) => name.endsWith(".json"))
+        .map((name) => name.slice(0, -".json".length))
+        .filter((id) => isTaskId(id))
+        .sort();
+}
+export async function readTask(root, id) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return undefined;
+    }
+    const seen = await ports.value.fs.exists(`${TASKS_DIR}/${id}.json`);
+    if (!seen.ok || !seen.value) {
+        return undefined;
+    }
+    const text = await ports.value.fs.readText(`${TASKS_DIR}/${id}.json`);
+    if (!text.ok) {
+        return undefined;
+    }
+    const parsed = parseJson(text.value);
+    if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null) {
+        return undefined;
+    }
+    return parsed.value;
+}
+export async function writeTask(root, task) {
+    const problems = validateTaskRecord(task);
+    if (problems.length > 0) {
+        return fail("CDX-E604", `task record invalid: ${problems.join("; ")}`, "Fix the record fields, then retry.", false);
+    }
+    const saved = await writeStateText(root, `${TASKS_DIR}/${task.id}.json`, `${stableStringify(task)}\n`);
+    if (!saved.ok) {
+        return fail("CDX-E903", saved.error.message, saved.error.remediation, false);
+    }
+    return ok(0);
+}
+export function taskLine(task) {
+    return `${task.id} [${task.type}] ${task.phase}: ${task.title}`;
+}
+export async function branchOf(root) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return undefined;
+    }
+    const result = await ports.value.proc.run(["git", "branch", "--show-current"], {
+        cwd: root,
+        env: {},
+        timeoutMs: 15000,
+        maxOutputBytes: 4096,
+    });
+    const branch = result.stdout.trim();
+    return result.code === 0 && branch !== "" ? branch : undefined;
+}
+export async function taskNew(req, root) {
+    let type = "";
+    let title = "";
+    try {
+        const parsed = parseArgs({
+            args: [...req.args.slice(1)],
+            options: { type: { type: "string" }, title: { type: "string" } },
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return usageError("usage: codictator task new --type <t> --title <t>");
+        }
+        type = parsed.values.type ?? "";
+        title = parsed.values.title ?? "";
+    }
+    catch {
+        return usageError("usage: codictator task new --type <t> --title <t>");
+    }
+    if (type === "" || title === "") {
+        return usageError("usage: codictator task new --type <t> --title <t>");
+    }
+    const branch = await branchOf(root);
+    if (branch === undefined) {
+        return fail("CDX-E903", "cannot read the current branch", "Run on a git branch, then retry.", req.json);
+    }
+    const ids = await listTaskIds(root);
+    const task = {
+        version: 1,
+        id: taskIdFor(ids.length + 1),
+        type,
+        title,
+        branch,
+        phase: "discovery",
+        phases: [],
+        spec: [],
+        acceptanceCriteria: [],
+        files: { allow: [] },
+    };
+    const saved = await writeTask(root, task);
+    if (!saved.ok) {
+        return saved;
+    }
+    if (req.json) {
+        printJson({ id: task.id, phase: task.phase, branch });
+    }
+    else {
+        printHuman(`created ${taskLine(task)}`, req.quiet);
+    }
+    return ok(0);
+}
+export async function taskCheckpoint(req, root) {
+    let id = "";
+    let note = "";
+    try {
+        const parsed = parseArgs({
+            args: [...req.args.slice(1)],
+            options: {
+                id: { type: "string" },
+                note: { type: "string", default: "" },
+            },
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return usageError("usage: codictator task checkpoint --id <T-####> [--note <t>]");
+        }
+        id = parsed.values.id ?? "";
+        note = parsed.values.note ?? "";
+    }
+    catch {
+        return usageError("usage: codictator task checkpoint --id <T-####> [--note <t>]");
+    }
+    const task = await readTask(root, id);
+    if (task === undefined) {
+        return fail("CDX-E903", `no task record for "${id}"`, "List tasks with codictator task show, then retry.", req.json);
+    }
+    const ports = await portsFor(root);
+    const now = ports.ok ? ports.value.clock.now() : "";
+    const saved = await writeStateText(root, `.codictator/state/task-${id}.checkpoint.json`, `${stableStringify({ version: 1, id, at: now, phase: task.phase, branch: task.branch, note })}\n`);
+    if (!saved.ok) {
+        return fail("CDX-E903", saved.error.message, saved.error.remediation, req.json);
+    }
+    if (req.json) {
+        printJson({ id, checkpoint: true });
+    }
+    else {
+        printHuman(`checkpoint recorded for ${id}`, req.quiet);
+    }
+    return ok(0);
+}
+export async function taskClose(req, root, id) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return fail("CDX-E903", ports.error.message, ports.error.remediation, req.json);
+    }
+    const bytes = await ports.value.fs.read(`${TASKS_DIR}/${id}.json`);
+    if (!bytes.ok) {
+        return fail("CDX-E903", bytes.error.message, bytes.error.remediation, req.json);
+    }
+    const moved = await ports.value.fs.write(`.codictator/state/closed-tasks/${id}.json`, bytes.value);
+    if (!moved.ok) {
+        return fail("CDX-E903", moved.error.message, moved.error.remediation, req.json);
+    }
+    await ports.value.fs.remove(`${TASKS_DIR}/${id}.json`);
+    printHuman(`closed ${id}`, req.quiet);
+    return ok(0);
+}

package/dist/cli/transparency.d.ts

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