codictator 0.0.0 → 0.1.2

package/dist/cli/serve-run.js

@@ -0,0 +1,135 @@
+import { invalidParamsError, serverError } from "./serve-protocol.js";
+import { field, isRecord } from "./serve-shared.js";
+import { exitFor } from "./shared.js";
+// SPEC §4.19.2 H rows: commands (and subcommands) the human-only change
+// path reserves. The table keeps the predicate flat; the server refuses
+// these before invoking anything.
+const ALWAYS_HUMAN = new Set([
+    "init",
+    "uninstall",
+    "waive",
+]);
+const HUMAN_SUBCOMMANDS = [
+    ["baseline", "capture"],
+    ["pack", "accept"],
+    ["task", "ack"],
+];
+function isHumanOnly(argv) {
+    const command = argv[0] ?? "";
+    if (ALWAYS_HUMAN.has(command)) {
+        return true;
+    }
+    const sub = argv[1] ?? "";
+    return HUMAN_SUBCOMMANDS.some(([name, gated]) => name === command && gated === sub);
+}
+function commandLine(argv) {
+    return `codictator ${argv.join(" ")}`;
+}
+// The CLI handlers print through process.stdout/stderr, so `run` captures
+// those process-global writes per call and restores them in a finally. The
+// scope is the process, not the connection: frames stay the only stdout
+// bytes while one connection serves (each server serializes requests on
+// its pump chain), but overlapping `run` calls in one process would share
+// the globals. Same-process concurrency therefore stays sequential by
+// construction; true parallelism stays across OS processes, one server per
+// VS Code window (SPEC §4.19.6 EC-10).
+async function executeCaptured(ctx, argv) {
+    let stdout = "";
+    let stderr = "";
+    const originalStdout = process.stdout.write;
+    const originalStderr = process.stderr.write;
+    const collectStdout = (chunk, encoding, callback) => {
+        if (typeof chunk === "string") {
+            stdout += chunk;
+        }
+        else {
+            stdout += new TextDecoder().decode(chunk);
+        }
+        if (typeof encoding === "function") {
+            encoding();
+        }
+        else if (typeof callback === "function") {
+            callback();
+        }
+        return true;
+    };
+    const collectStderr = (chunk, encoding, callback) => {
+        if (typeof chunk === "string") {
+            stderr += chunk;
+        }
+        else {
+            stderr += new TextDecoder().decode(chunk);
+        }
+        if (typeof encoding === "function") {
+            encoding();
+        }
+        else if (typeof callback === "function") {
+            callback();
+        }
+        return true;
+    };
+    process.stdout.write = collectStdout;
+    process.stderr.write = collectStderr;
+    try {
+        const result = await ctx.execute(ctx.engineVersion === undefined
+            ? { argv: [...argv], cwd: ctx.root }
+            : { argv: [...argv], cwd: ctx.root, engineVersion: ctx.engineVersion });
+        if (result.ok) {
+            return { exitCode: result.value, stdout, stderr };
+        }
+        return {
+            exitCode: exitFor(result.error.code),
+            stdout,
+            stderr,
+            code: result.error.code,
+            remediation: result.error.remediation,
+        };
+    }
+    catch {
+        return {
+            exitCode: 7,
+            stdout,
+            stderr,
+            code: "CDX-E901",
+            remediation: "Retry the command; if it keeps failing, report the stall.",
+        };
+    }
+    finally {
+        process.stdout.write = originalStdout;
+        process.stderr.write = originalStderr;
+    }
+}
+// SPEC §7.15: `run { argv }` answers the CLI result; human-only argv
+// answers CDX-E107 with data.commandLine and never runs.
+export async function handleRun(params, ctx) {
+    if (!isRecord(params)) {
+        return {
+            ok: false,
+            error: invalidParamsError("run params must be { argv }"),
+        };
+    }
+    const raw = field(params, "argv");
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return {
+            ok: false,
+            error: invalidParamsError("run argv must be a non-empty array of strings"),
+        };
+    }
+    const argv = [];
+    for (const entry of raw) {
+        if (typeof entry !== "string") {
+            return {
+                ok: false,
+                error: invalidParamsError("run argv must be a non-empty array of strings"),
+            };
+        }
+        argv.push(entry);
+    }
+    if (isHumanOnly(argv)) {
+        return {
+            ok: false,
+            error: serverError("CDX-E107", "human-only command refused: no interactive TTY on the server", "Run this command yourself in an interactive terminal, not through an agent or hook.", { commandLine: commandLine(argv) }),
+        };
+    }
+    return { ok: true, value: await executeCaptured(ctx, argv) };
+}

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

@@ -0,0 +1,5 @@
+import type { Result } from "../kernel/index.ts";
+import type { CliOptions } from "./index.ts";
+import type { StdioServerStreams } from "./serve-shared.ts";
+export type ServeExecute = (options: CliOptions) => Promise<Result<number>>;
+export declare function startStdioServer(options: CliOptions, execute: ServeExecute, streams?: StdioServerStreams): Promise<number>;

package/dist/cli/serve-server.js

@@ -0,0 +1,120 @@
+import { readLogEvents } from "./inspect.js";
+import { dispatchMethod } from "./serve-methods.js";
+import { decodeLine, errorFrame, invalidRequestFrame, notificationFrame, parseErrorFrame, successFrame, } from "./serve-protocol.js";
+import { handleRun } from "./serve-run.js";
+import { openLinePump } from "./serve-transport.js";
+function writeFrame(stdout, text) {
+    stdout.write(text);
+}
+function writeDiagnostic(stderr, text) {
+    stderr.write(`${text}\n`);
+}
+// The Fs-port watcher: the baseline is set at startup with no notify; after
+// each request new lines push one `events/appended` notification carrying
+// the new event lines.
+async function pollAppended(state) {
+    const log = await readLogEvents(state.root);
+    if (log === undefined) {
+        return;
+    }
+    const total = log.events.length + log.corrupt;
+    if (!state.seen.started) {
+        state.seen.count = total;
+        state.seen.started = true;
+        return;
+    }
+    if (total <= state.seen.count) {
+        state.seen.count = total;
+        return;
+    }
+    const fresh = log.events.slice(state.seen.count);
+    state.seen.count = total;
+    if (fresh.length > 0) {
+        writeFrame(state.io.stdout, notificationFrame("events/appended", { events: fresh }));
+    }
+}
+// One request answered with exactly one frame; a throw inside a method
+// can never escape the loop (EC-9 survival).
+async function answerRequest(id, method, params, state) {
+    try {
+        const runCtx = state.engineVersion === undefined
+            ? { root: state.root, execute: state.execute }
+            : {
+                root: state.root,
+                engineVersion: state.engineVersion,
+                execute: state.execute,
+            };
+        const methodCtx = state.engineVersion === undefined
+            ? { root: state.root }
+            : { root: state.root, engineVersion: state.engineVersion };
+        const outcome = method === "run"
+            ? await handleRun(params, runCtx)
+            : await dispatchMethod(method, params, methodCtx);
+        writeFrame(state.io.stdout, outcome.ok
+            ? successFrame(id, outcome.value)
+            : errorFrame(id, outcome.error));
+    }
+    catch {
+        writeFrame(state.io.stdout, errorFrame(id, {
+            code: -32603,
+            message: "Internal error: the method failed to complete",
+        }));
+    }
+}
+async function handleLine(line, state) {
+    if (line.trim() === "") {
+        return;
+    }
+    const decoded = decodeLine(line);
+    if (decoded.kind === "syntax") {
+        writeFrame(state.io.stdout, parseErrorFrame());
+        return;
+    }
+    if (decoded.kind === "bad") {
+        writeFrame(state.io.stdout, invalidRequestFrame(decoded.id));
+        return;
+    }
+    if (decoded.kind === "notification") {
+        return;
+    }
+    const { id, method, params } = decoded.request;
+    await answerRequest(id, method, params, state);
+    try {
+        await pollAppended(state);
+    }
+    catch {
+        // The watcher is best-effort: the request was already answered, and
+        // a watcher failure must never break the loop (EC-9 survival).
+    }
+}
+// SPEC §7.15: serve one NDJSON session on this process's stdio. The loop
+// ends on stdin EOF (the client disconnected) or a stdin error; the exit
+// is always 0 so harness tests observe a clean shutdown. A silent pipe
+// past the first-byte grace is a harness call with no client: exit 0
+// without serving, so `node --test` and coverage runs never hang.
+export function startStdioServer(options, execute, streams = {
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+}) {
+    const argv = options.argv;
+    if (argv[0] !== "serve" || argv[1] !== "--stdio" || argv.length !== 2) {
+        writeDiagnostic(streams.stderr, "usage: codictator serve --stdio");
+        return Promise.resolve(2);
+    }
+    const state = {
+        root: options.cwd,
+        ...(options.engineVersion === undefined
+            ? {}
+            : { engineVersion: options.engineVersion }),
+        execute,
+        io: streams,
+        seen: { count: 0, started: false },
+    };
+    if (streams.stdin.readableEnded || streams.stdin.readable !== true) {
+        return Promise.resolve(0);
+    }
+    return new Promise((resolve) => {
+        openLinePump(streams.stdin, pollAppended(state), (line) => handleLine(line, state), resolve);
+    });
+}

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

@@ -0,0 +1,34 @@
+import type { RpcErrorShape } from "./serve-protocol.ts";
+export interface MethodContext {
+    readonly root: string;
+    readonly engineVersion?: string;
+}
+export type MethodOutcome = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly error: RpcErrorShape;
+};
+export declare function methodOk(value: unknown): MethodOutcome;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function field(record: Record<string, unknown>, name: string): unknown;
+export interface StdioServerStdin {
+    readonly readable: boolean;
+    readonly readableEnded: boolean;
+    readonly isTTY?: boolean | undefined;
+    on(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    on(event: "end" | "error", listener: () => void): unknown;
+    removeListener(event: "data" | "end" | "error", listener: (...args: Array<never>) => void): unknown;
+    resume(): unknown;
+    pause(): unknown;
+}
+export interface StdioServerStdout {
+    write(chunk: string | Uint8Array): boolean;
+}
+export interface StdioServerStreams {
+    readonly stdin: StdioServerStdin;
+    readonly stdout: StdioServerStdout;
+    readonly stderr: StdioServerStdout;
+}
+export declare function resolveRoot(cwd: string): Promise<string>;

package/dist/cli/serve-shared.js

@@ -0,0 +1,20 @@
+// SPEC §7.15: shared stdio plumbing. Method results, unknown narrowing
+// and root resolution for the read, evaluation and run rows; framing stays
+// in serve-protocol.ts. Imports kernel only, so every serve module builds
+// on this without cycles.
+import { resolveRepoRoot } from "../kernel/index.js";
+export function methodOk(value) {
+    return { ok: true, value };
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Bracket access through a variable keeps noPropertyAccessFromIndexSignature
+// satisfied without tripping useLiteralKeys (kernel schema.ts pattern).
+export function field(record, name) {
+    return record[name];
+}
+export async function resolveRoot(cwd) {
+    const root = await resolveRepoRoot(cwd);
+    return root.ok ? root.value : cwd;
+}

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

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

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