codictator 0.0.0 → 0.1.3

package/dist/cli/serve-status.js

@@ -0,0 +1,130 @@
+// SPEC §7.15 + §4.18.3: the stdio `status` row. Answers the §4.18.3 JSON
+// over the same inputs the `status` command renders: engine, packs,
+// harness states, helper tools, event counts and the pending sections.
+import { CLAUDE_CODE_CAPABILITIES, CODEX_CAPABILITIES, COPILOT_CAPABILITIES, MUSE_CAPABILITIES, OPENCODE_CAPABILITIES, UNIVERSAL_CAPABILITIES, } from "../features/adapters/index.js";
+import { buildStatusJson, 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 { readLogEvents } from "./inspect.js";
+import { field, isRecord, methodOk, resolveRoot, } from "./serve-shared.js";
+import { loadRepoConfig, portsFor } from "./shared.js";
+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 matchHelper(entry, role) {
+    const entryId = field(entry, "id");
+    const entryRole = field(entry, "role");
+    if (entryId !== role && entryRole !== role) {
+        return undefined;
+    }
+    const version = field(entry, "version");
+    const versionPin = isRecord(version) ? field(version, "pin") : undefined;
+    const pin = typeof versionPin === "string" ? versionPin : undefined;
+    if (typeof entryId === "string" && pin !== undefined && pin !== "") {
+        return { role, present: true, detail: `${entryId} ${pin}` };
+    }
+    return { role, present: false };
+}
+function helperDetail(tools, role) {
+    if (!Array.isArray(tools)) {
+        return { role, present: false };
+    }
+    for (const entry of tools) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        const matched = matchHelper(entry, role);
+        if (matched !== undefined) {
+            return matched;
+        }
+    }
+    return { role, present: false };
+}
+function requiredRoles(steering) {
+    if (isRecord(steering)) {
+        const found = field(steering, "requiredHelpers");
+        if (Array.isArray(found) &&
+            found.every((entry) => typeof entry === "string")) {
+            return [...found];
+        }
+    }
+    return [...REQUIRED_HELPERS_DEFAULT];
+}
+async function collectStatusParts(root, engineVersion) {
+    const log = await readLogEvents(root);
+    const events = log?.events ?? [];
+    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: events.length,
+        corrupt: log?.corrupt ?? 0,
+        gap: events.length === 0,
+        observed: new Set(events.map((event) => event.harness ?? "").filter((h) => h !== "")),
+        packs,
+        helpers,
+    };
+}
+export async function statusMethod(ctx) {
+    const root = await resolveRoot(ctx.root);
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return {
+            ok: false,
+            error: {
+                code: -32000,
+                message: `${ports.error.code} ${ports.error.message}`,
+                data: {
+                    code: ports.error.code,
+                    remediation: ports.error.remediation,
+                },
+            },
+        };
+    }
+    const parts = await collectStatusParts(root, ctx.engineVersion ?? ENGINE_VERSION);
+    return methodOk(buildStatusJson({
+        engineVersion: ctx.engineVersion ?? ENGINE_VERSION,
+        packs: parts.packs,
+        harnesses: harnessStates(parts.observed),
+        helpers: parts.helpers,
+        events: parts.events,
+        corrupt: parts.corrupt,
+        gap: parts.gap,
+        task: undefined,
+        waivers: undefined,
+        ratchet: undefined,
+        deps: undefined,
+        integrity: undefined,
+        escalations: undefined,
+        remediation: undefined,
+        now: ports.value.clock.now(),
+    }));
+}

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

@@ -0,0 +1,2 @@
+import type { StdioServerStdin } from "./serve-shared.ts";
+export declare function openLinePump(stdin: StdioServerStdin, initial: Promise<void>, handleLine: (line: string) => Promise<void>, done: (code: number) => void): void;

package/dist/cli/serve-transport.js

@@ -0,0 +1,114 @@
+// How long a piped stdin may stay silent before the server concludes no
+// piped client exists (a harness call with no input, like the red-proof
+// tests) and exits 0. Spawned clients write `initialize` in milliseconds;
+// a TTY waits indefinitely instead, since a human types at human pace.
+const FIRST_BYTE_GRACE_MS = 1000;
+function pumpFinish(pump, code) {
+    if (pump.settled) {
+        return;
+    }
+    pump.settled = true;
+    const settle = () => {
+        pumpCleanup(pump);
+        pump.done(code);
+    };
+    pump.chain.then(settle, settle);
+}
+function pumpCleanup(pump) {
+    pump.clearGrace?.();
+    if (pump.boundData !== undefined) {
+        pump.stdin.removeListener("data", pump.boundData);
+    }
+    if (pump.boundEnd !== undefined) {
+        pump.stdin.removeListener("end", pump.boundEnd);
+    }
+    if (pump.boundError !== undefined) {
+        pump.stdin.removeListener("error", pump.boundError);
+    }
+    pump.stdin.pause();
+}
+// Split complete lines off the buffer, feeding each to the queue; the
+// remainder stays buffered for the next chunk.
+function drainLines(buffer, feed) {
+    let rest = buffer;
+    let at = rest.indexOf("\n");
+    while (at !== -1) {
+        feed(rest.slice(0, at));
+        rest = rest.slice(at + 1);
+        at = rest.indexOf("\n");
+    }
+    return rest;
+}
+function pumpOnData(pump, chunk) {
+    pump.clearGrace?.();
+    pump.buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    pump.buffer = drainLines(pump.buffer, (line) => {
+        chainLine(pump, line);
+    });
+}
+function pumpOnEnd(pump) {
+    pump.clearGrace?.();
+    if (pump.buffer.trim() !== "") {
+        const pending = pump.buffer;
+        pump.buffer = "";
+        chainLine(pump, pending);
+    }
+    pumpFinish(pump, 0);
+}
+// A rejected step must never silence later lines: the chain always
+// continues with the next line.
+function chainLine(pump, line) {
+    const pending = line;
+    const run = () => pump.handleLine(pending);
+    pump.chain = pump.chain.then(run, run);
+}
+// A silent pipe past the grace is a harness call with no client: the
+// caller clears the timer on the first byte, end or error.
+function armFirstByteGrace(stdin, onSilent) {
+    if (stdin.isTTY === true) {
+        return undefined;
+    }
+    const timer = setTimeout(onSilent, FIRST_BYTE_GRACE_MS);
+    return () => {
+        clearTimeout(timer);
+    };
+}
+// The stdin subscription for one session: the initial read (usually the
+// watcher baseline) runs first and may never reject, then every line is
+// queued in order behind it.
+export function openLinePump(stdin, initial, handleLine, done) {
+    const pump = {
+        buffer: "",
+        chain: initial.then(() => undefined, () => undefined),
+        settled: false,
+        clearGrace: armFirstByteGrace(stdin, () => {
+            pumpFinish(pump, 0);
+        }),
+        boundData: undefined,
+        boundEnd: undefined,
+        boundError: undefined,
+        stdin,
+        handleLine,
+        done,
+    };
+    pump.boundData = (chunk) => {
+        pumpOnData(pump, chunk);
+    };
+    pump.boundEnd = () => {
+        pumpOnEnd(pump);
+    };
+    pump.boundError = () => {
+        pump.clearGrace?.();
+        pumpFinish(pump, 0);
+    };
+    if (pump.boundData !== undefined) {
+        stdin.on("data", pump.boundData);
+    }
+    if (pump.boundEnd !== undefined) {
+        stdin.on("end", pump.boundEnd);
+    }
+    if (pump.boundError !== undefined) {
+        stdin.on("error", pump.boundError);
+    }
+    stdin.resume();
+}

package/dist/cli/shared.d.ts

@@ -0,0 +1,35 @@
+import { type EffectiveConfig } from "../features/config/index.ts";
+import type { CdxError, Env, Ports, Result } from "../kernel/index.ts";
+export declare const MIN_NODE_MAJOR = 24;
+export interface CommandRequest {
+    readonly args: ReadonlyArray<string>;
+    readonly json: boolean;
+    readonly quiet: boolean;
+    readonly cwd: string;
+    readonly nodeVersion: string | undefined;
+    readonly stdinText: string | undefined;
+    readonly engineVersion?: string;
+}
+export declare function nodeMajor(version: string): number;
+export declare function nodeTooOldMessage(version: string): string;
+export declare function printHuman(text: string, quiet: boolean): void;
+export declare function printJson(value: unknown): void;
+export declare function exitFor(code: string): number;
+export declare function reportError<T = number>(error: CdxError, json: boolean): Result<T>;
+export declare function fail<T = number>(code: string, message: string, remediation: string, json: boolean, detail?: string): Result<T>;
+export declare function usageError(text: string): Result<number>;
+export declare function isTty(): boolean;
+export declare function checkHuman(env: Env, agentMarkers: ReadonlyArray<string>): Result<void>;
+export declare function commandEnv(): Env;
+export interface CommandPorts extends Ports {
+    readonly root: string;
+}
+export declare function portsFor(root: string, env?: Env): Promise<Result<CommandPorts>>;
+export declare function readStateText(root: string, rel: string): Promise<string | undefined>;
+export declare function needRoot(req: CommandRequest): Promise<string | Result<number>>;
+export declare function needTaskRoot(req: CommandRequest): Promise<string | Result<number>>;
+export declare function writeStateText(root: string, rel: string, text: string): Promise<Result<void>>;
+export declare function loadRepoConfig(root: string, env?: Env, engineVersion?: string): Promise<Result<{
+    ports: CommandPorts;
+    effective: EffectiveConfig;
+}>>;

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);
+}
+const SINGLE_SUBCOMMANDS = {
+    new: (req, root) => taskNew(req, root),
+    show: (req, root) => taskShow(req, root),
+    checkpoint: (req, root) => taskCheckpoint(req, root),
+};
+async function runTaskSub(req, root, sub) {
+    if (sub === "phase" && req.args[1] === "next") {
+        return taskPhaseNext(req, root);
+    }
+    const single = SINGLE_SUBCOMMANDS[sub];
+    if (single !== undefined) {
+        return single(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> ...");
+}
+export async function handleTask(req) {
+    const root = await needTaskRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    return runTaskSub(req, root, req.args[0] ?? "");
+}
+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>>;