codictator 0.0.0-stage → 0.1.2

package/dist/kernel/shell-scan.js

@@ -0,0 +1,226 @@
+// SPEC §4.7.2: the shell parser driver. The main loop dispatches each
+// position to the word scanners (shell-word.ts) or a boundary; finished
+// word lists become commands through the elaborator (shell-cmd.ts).
+// Pipelines split on ;, &&, ||, |, & and newlines; $(…), backticks,
+// groupings and heredocs descend inline.
+import { makeError } from "./errors.js";
+import { err, ok } from "./result.js";
+import { ParseFailure, } from "./shell.js";
+import { buildShellCommand } from "./shell-cmd.js";
+import { readShellBalanced, readShellHeredoc, readShellOperator, readShellQuoted, readShellWord, skipShellComment, } from "./shell-word.js";
+function unparseable() {
+    return err(makeError("CDX-E306", "shell command is unparseable (unbalanced quote or unfinished construct)", "Rewrite the command with balanced quotes and no heredoc without a terminator, then retry."));
+}
+function newCollector() {
+    return { pipelines: [], writeTargets: [], inputs: [] };
+}
+class ShellParser {
+    index = 0;
+    current = [];
+    commandStart = 0;
+    pipeline = [];
+    heredocBodies = [];
+    text;
+    collect;
+    constructor(text, collect) {
+        this.text = text;
+        this.collect = collect;
+    }
+    parse() {
+        this.commandStart = 0;
+        while (this.index < this.text.length) {
+            this.parseStep();
+        }
+        this.endCommand();
+        this.endPipeline();
+    }
+    parseStep() {
+        const char = this.text[this.index];
+        if (char === " " || char === "\t") {
+            this.index += 1;
+            return;
+        }
+        if (char === "#") {
+            this.index = skipShellComment(this.text, this.index);
+            return;
+        }
+        if (char !== undefined && this.parseQuotedStart(char)) {
+            return;
+        }
+        if (char !== undefined && this.parseBoundaryStart(char)) {
+            return;
+        }
+        if (char !== undefined && this.parseGroupStart(char)) {
+            return;
+        }
+        this.parseWordOrOperator();
+    }
+    parseSubstitutionStart(char) {
+        const next = this.text[this.index + 1];
+        if (next !== "(" || (char !== "$" && char !== "<" && char !== ">")) {
+            return false;
+        }
+        const inner = readShellBalanced(this.text, this.index + 2, ")");
+        ShellParser.descendText(inner.value, this.collect);
+        this.current.push(inner.value);
+        this.index = inner.next;
+        return true;
+    }
+    parseQuotedStart(char) {
+        if (char === "'" || char === '"' || char === "`") {
+            const read = readShellQuoted(this.text, this.index, (inner) => ShellParser.descendText(inner, this.collect));
+            this.current.push(read.value);
+            this.index = read.next;
+            return true;
+        }
+        return this.parseSubstitutionStart(char);
+    }
+    endBoundary(pipelineToo, skip) {
+        this.endCommand();
+        if (pipelineToo) {
+            this.endPipeline();
+        }
+        this.index += skip;
+        this.commandStart = this.index;
+    }
+    parseBoundaryStart(char) {
+        if (char === "\n") {
+            this.endBoundary(true, 1);
+            return true;
+        }
+        if (char === "&" && this.text[this.index + 1] === "&") {
+            this.endBoundary(true, 2);
+            return true;
+        }
+        if (char === "|" && this.text[this.index + 1] === "|") {
+            this.endBoundary(true, 2);
+            return true;
+        }
+        if (char === "|" && this.text[this.index + 1] === "&") {
+            this.endBoundary(false, 2);
+            return true;
+        }
+        if (char === "|") {
+            this.endBoundary(false, 1);
+            return true;
+        }
+        if (char === ";" || char === "&") {
+            const skip = char === ";" && this.text[this.index + 1] === ";" ? 2 : 1;
+            this.endBoundary(true, skip);
+            return true;
+        }
+        return false;
+    }
+    parseGroupStart(char) {
+        if (char === "(" || char === "{") {
+            const close = char === "(" ? ")" : "}";
+            const inner = readShellBalanced(this.text, this.index + 1, close);
+            if (char === "(" && this.current.length === 0) {
+                this.endPipeline();
+            }
+            ShellParser.descendText(inner.value, this.collect);
+            this.index = inner.next;
+            this.commandStart = this.index;
+            return true;
+        }
+        if (char === ")" || char === "}") {
+            throw new ParseFailure();
+        }
+        return false;
+    }
+    parseWordOrOperator() {
+        const last = this.current.length > 0
+            ? this.current[this.current.length - 1]
+            : undefined;
+        const operator = readShellOperator(this.text, this.index, last);
+        if (operator === undefined) {
+            const word = readShellWord(this.text, this.index, (inner) => ShellParser.descendText(inner, this.collect));
+            this.current.push(word.value);
+            this.index = word.next;
+            return;
+        }
+        if (operator.dropFd) {
+            this.current.pop();
+        }
+        this.index = operator.next;
+        this.handleRedirection(operator.operator);
+    }
+    handleRedirection(operator) {
+        while (this.index < this.text.length &&
+            (this.text[this.index] === " " || this.text[this.index] === "\t")) {
+            this.index += 1;
+        }
+        if (this.index >= this.text.length) {
+            throw new ParseFailure();
+        }
+        const char = this.text[this.index];
+        let target;
+        if (char === "'" || char === '"') {
+            const read = readShellQuoted(this.text, this.index, (inner) => ShellParser.descendText(inner, this.collect));
+            target = read.value;
+            this.index = read.next;
+        }
+        else {
+            const word = readShellWord(this.text, this.index, (inner) => ShellParser.descendText(inner, this.collect));
+            target = word.value;
+            this.index = word.next;
+        }
+        if (target === "") {
+            throw new ParseFailure();
+        }
+        if (operator === "<<" || operator === "<<-") {
+            const body = readShellHeredoc(this.text, this.index, target, operator === "<<-");
+            this.heredocBodies.push(body.value);
+            this.index = body.next;
+        }
+        else if (operator === "<") {
+            this.collect.inputs.push(target);
+        }
+        else if (operator !== "<<<") {
+            this.collect.writeTargets.push(target);
+        }
+    }
+    endCommand() {
+        const words = this.current;
+        this.current = [];
+        const bodies = this.heredocBodies;
+        this.heredocBodies = [];
+        if (words.length === 0) {
+            return;
+        }
+        const raw = this.text.slice(this.commandStart, this.index).trim();
+        this.commandStart = this.index;
+        buildShellCommand(this.pipeline, words, raw, false, bodies, (inner) => ShellParser.descendText(inner, this.collect));
+    }
+    endPipeline() {
+        if (this.pipeline.length > 0) {
+            this.collect.pipelines.push({ commands: this.pipeline });
+            this.pipeline = [];
+        }
+    }
+    static descendText(inner, collect) {
+        const nested = new ShellParser(inner, collect);
+        nested.parse();
+    }
+}
+// SPEC §4.7.2: tokenise without executing; unbalanced quotes, heredocs
+// without a terminator and other unfinished constructs fail CDX-E306.
+export function analyseShell(command) {
+    const collect = newCollector();
+    try {
+        const parser = new ShellParser(command.replace(/\r\n?/g, "\n"), collect);
+        parser.parse();
+    }
+    catch (error) {
+        if (error instanceof ParseFailure) {
+            return unparseable();
+        }
+        throw error;
+    }
+    const pipelines = collect.pipelines.filter((pipeline) => pipeline.commands.length > 0);
+    return ok({
+        pipelines,
+        writeTargets: [...collect.writeTargets],
+        inputs: [...collect.inputs],
+    });
+}

package/dist/kernel/shell-word.d.ts

@@ -0,0 +1,15 @@
+export interface WordRead {
+    readonly value: string;
+    readonly next: number;
+}
+export declare function skipShellComment(text: string, index: number): number;
+export declare function readShellQuoted(text: string, index: number, descend: (inner: string) => void): WordRead;
+export declare function readShellBalanced(text: string, index: number, close: string): WordRead;
+export declare function readShellWord(text: string, index: number, descend: (inner: string) => void): WordRead;
+export interface OperatorRead {
+    readonly operator: string;
+    readonly next: number;
+    readonly dropFd: boolean;
+}
+export declare function readShellOperator(text: string, index: number, lastWord: string | undefined): OperatorRead | undefined;
+export declare function readShellHeredoc(text: string, index: number, delimiter: string, stripTabs: boolean): WordRead;

package/dist/kernel/shell-word.js

@@ -0,0 +1,216 @@
+// SPEC §4.7.2: word-level lexing for the shell analyser. Pure scanners
+// over (text, index): quotes with $(…) and backtick descent, balanced
+// groups, bare words, redirection operators and heredoc bodies. The parser
+// feeds nested command text back through a descend callback, so this file
+// never imports the parser.
+import { ParseFailure } from "./shell.js";
+export function skipShellComment(text, index) {
+    let at = index;
+    while (at < text.length && text[at] !== "\n") {
+        at += 1;
+    }
+    return at;
+}
+function descendQuoted(text, index, descend) {
+    let at = index + 1;
+    const start = at;
+    while (at < text.length) {
+        const innerChar = text[at];
+        if (innerChar === "\\") {
+            at += 2;
+            continue;
+        }
+        if (innerChar === "`") {
+            break;
+        }
+        at += 1;
+    }
+    if (at >= text.length) {
+        throw new ParseFailure();
+    }
+    const inner = text.slice(start, at);
+    descend(inner);
+    return { value: inner, next: at + 1 };
+}
+// SPEC §4.7.2: single quotes are literal; double quotes keep $() and
+// backtick descent; an unclosed quote fails CDX-E306 upstream.
+export function readShellQuoted(text, index, descend) {
+    const quote = text[index];
+    if (quote === "`") {
+        const inner = readShellBalanced(text, index + 1, "`");
+        descend(inner.value);
+        return inner;
+    }
+    const out = [];
+    let at = index + 1;
+    while (at < text.length) {
+        const char = text[at];
+        if (char === quote) {
+            return { value: out.join(""), next: at + 1 };
+        }
+        if (char === "\\" && quote === '"') {
+            const next = text[at + 1];
+            if (next === "\n") {
+                at += 2;
+                continue;
+            }
+            if (next !== undefined) {
+                out.push(next);
+                at += 2;
+                continue;
+            }
+            throw new ParseFailure();
+        }
+        if (quote === '"' && char === "$" && text[at + 1] === "(") {
+            const inner = readShellBalanced(text, at + 2, ")");
+            descend(inner.value);
+            out.push(inner.value);
+            at = inner.next;
+            continue;
+        }
+        if (quote === '"' && char === "`") {
+            const inner = descendQuoted(text, at, descend);
+            out.push(inner.value);
+            at = inner.next;
+            continue;
+        }
+        out.push(char ?? "");
+        at += 1;
+    }
+    throw new ParseFailure();
+}
+// SPEC §4.7.2: quote-aware extent scan for $(…), `…`, (…) and {…}. Only
+// the extent is found here; descent happens at the call site.
+export function readShellBalanced(text, index, close) {
+    let depth = 1;
+    let at = index;
+    const start = at;
+    let quote;
+    while (at < text.length) {
+        const char = text[at];
+        if (quote !== undefined) {
+            if (char === "\\") {
+                at += 2;
+                continue;
+            }
+            if (char === quote) {
+                quote = undefined;
+            }
+            at += 1;
+            continue;
+        }
+        if (char === close) {
+            depth -= 1;
+            if (depth === 0) {
+                return { value: text.slice(start, at), next: at + 1 };
+            }
+            at += 1;
+            continue;
+        }
+        if (char === "'" || char === '"' || char === "`") {
+            quote = char;
+            at += 1;
+            continue;
+        }
+        if (char === "$" && text[at + 1] === "(" && close === ")") {
+            depth += 1;
+            at += 2;
+            continue;
+        }
+        if (char === "(" && close === ")") {
+            depth += 1;
+            at += 1;
+            continue;
+        }
+        at += 1;
+    }
+    throw new ParseFailure();
+}
+const WORD_STOPS = new Set([
+    " ",
+    "\t",
+    "\n",
+    ";",
+    "&",
+    "|",
+    "(",
+    ")",
+    "{",
+    "}",
+    "<",
+    ">",
+    "'",
+    '"',
+    "`",
+    "#",
+]);
+export function readShellWord(text, index, descend) {
+    const out = [];
+    let at = index;
+    while (at < text.length) {
+        const char = text[at];
+        if (char === undefined || WORD_STOPS.has(char)) {
+            break;
+        }
+        if (char === "\\") {
+            const next = text[at + 1];
+            if (next === "\n") {
+                at += 2;
+                continue;
+            }
+            if (next !== undefined) {
+                out.push(next);
+                at += 2;
+                continue;
+            }
+            throw new ParseFailure();
+        }
+        if (char === "$" && text[at + 1] === "(") {
+            const inner = readShellBalanced(text, at + 2, ")");
+            descend(inner.value);
+            out.push(inner.value);
+            at = inner.next;
+            continue;
+        }
+        out.push(char);
+        at += 1;
+    }
+    return { value: out.join(""), next: at };
+}
+const REDIRECT_WORDS = new Set(["<<-", "<<<", "<<", ">>", ">|", "&>", ">&"]);
+export function readShellOperator(text, index, lastWord) {
+    const rest = text.slice(index);
+    for (const operator of REDIRECT_WORDS) {
+        if (rest.startsWith(operator)) {
+            return { operator, next: index + operator.length, dropFd: false };
+        }
+    }
+    const char = text[index];
+    if (char === ">" || char === "<") {
+        const dropFd = char === ">" && lastWord !== undefined && /^\d+$/.test(lastWord);
+        return { operator: char, next: index + 1, dropFd };
+    }
+    return undefined;
+}
+// SPEC §4.7.2: a heredoc without a terminator is unparseable (CDX-E306).
+export function readShellHeredoc(text, index, delimiter, stripTabs) {
+    let at = index;
+    if (text[at] === "\n") {
+        at += 1;
+    }
+    const body = [];
+    while (at < text.length) {
+        const end = text.indexOf("\n", at);
+        const line = end < 0 ? text.slice(at) : text.slice(at, end);
+        const compared = stripTabs ? line.replace(/^\t+/, "") : line;
+        if (compared === delimiter) {
+            return { value: body.join("\n"), next: end < 0 ? text.length : end + 1 };
+        }
+        body.push(line);
+        if (end < 0) {
+            throw new ParseFailure();
+        }
+        at = end + 1;
+    }
+    throw new ParseFailure();
+}

package/dist/kernel/shell.d.ts

@@ -0,0 +1,22 @@
+export interface SimpleCommand {
+    readonly name: string;
+    readonly argv: ReadonlyArray<string>;
+    readonly raw: string;
+    readonly elevated: boolean;
+    readonly embedded: ReadonlyArray<string>;
+}
+export interface ShellPipeline {
+    readonly commands: ReadonlyArray<SimpleCommand>;
+}
+export interface ShellAnalysis {
+    readonly pipelines: ReadonlyArray<ShellPipeline>;
+    readonly writeTargets: ReadonlyArray<string>;
+    readonly inputs: ReadonlyArray<string>;
+}
+export interface Collector {
+    readonly pipelines: Array<ShellPipeline>;
+    readonly writeTargets: Array<string>;
+    readonly inputs: Array<string>;
+}
+export declare class ParseFailure extends Error {
+}

package/dist/kernel/shell.js

@@ -0,0 +1,2 @@
+export class ParseFailure extends Error {
+}

package/dist/kernel/stdin.d.ts

@@ -0,0 +1,2 @@
+import { type Result } from "./result.ts";
+export declare function readStdinText(maxBytes: number, deadlineMs: number): Promise<Result<string>>;

package/dist/kernel/stdin.js

@@ -0,0 +1,59 @@
+// SPEC §4.19.3 step 1 with §4.5.5: stdin read for the hook entry. The
+// kernel owns the OS read; the byte cap and the arrival deadline arrive
+// as data. A TTY stdin means no harness piped a payload, so it answers
+// empty without waiting. Past the cap the payload is CDX-E305; past the
+// deadline the wait is CDX-E902, so an idle pipe fails closed instead of
+// hanging the hook past its time limit. A closed or unreadable stdin is
+// no payload at all, and the caller maps that to its own empty-payload
+// error (CDX-E303 for hooks).
+import { makeError } from "./errors.js";
+import { err, ok } from "./result.js";
+function overCapError(maxBytes) {
+    return err(makeError("CDX-E305", `hook payload over ${maxBytes} bytes is refused`, "Write the file in smaller edits, then retry the tool call."));
+}
+function pastDeadlineError() {
+    return err(makeError("CDX-E902", "hook input did not arrive within the hook time limit", "Retry the tool call; if the harness stalls its hook input, report the stall."));
+}
+export function readStdinText(maxBytes, deadlineMs) {
+    if (process.stdin.isTTY === true) {
+        return Promise.resolve(ok(""));
+    }
+    return new Promise((resolve) => {
+        const chunks = [];
+        let total = 0;
+        let settled = false;
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            process.stdin.removeListener("data", onData);
+            process.stdin.removeListener("end", onEnd);
+            process.stdin.removeListener("error", onError);
+            process.stdin.pause();
+            resolve(result);
+        };
+        const onData = (chunk) => {
+            total += chunk.length;
+            if (total > maxBytes) {
+                finish(overCapError(maxBytes));
+                return;
+            }
+            chunks.push(chunk);
+        };
+        const onEnd = () => {
+            finish(ok(Buffer.concat(chunks).toString("utf8")));
+        };
+        const onError = () => {
+            finish(ok(""));
+        };
+        const timer = setTimeout(() => {
+            finish(pastDeadlineError());
+        }, deadlineMs);
+        process.stdin.on("data", onData);
+        process.stdin.on("end", onEnd);
+        process.stdin.on("error", onError);
+        process.stdin.resume();
+    });
+}

package/dist/kernel/test-report.d.ts

@@ -0,0 +1,7 @@
+import { type Result } from "./result.ts";
+export interface TestCaseResult {
+    readonly id: string;
+    readonly title: string;
+    readonly outcome: "passed" | "failed" | "skipped";
+}
+export declare function readTestReport(xml: string): Result<Array<TestCaseResult>>;

package/dist/kernel/test-report.js

@@ -0,0 +1,112 @@
+// SPEC §4.1.2: minimal reader for JUnit XML and TRX so red and green
+// proofs need no runner-specific parsing (SPEC §4.10.2). No XML library is
+// used; the reader matches only the elements it owns and fails closed on
+// anything else.
+import { makeError } from "./errors.js";
+import { err, ok } from "./result.js";
+function malformed() {
+    return err(makeError("CDX-E101", "test report XML is unparseable", "Regenerate the report as JUnit or TRX XML, then retry."));
+}
+function decodeEntities(text) {
+    return text
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+function attributes(tag) {
+    const found = new Map();
+    const pattern = /([\w:.-]+)\s*=\s*("([^"]*)"|'([^']*)')/g;
+    let match = pattern.exec(tag);
+    while (match !== null) {
+        const name = match[1] ?? "";
+        const value = match[3] ?? match[4] ?? "";
+        if (!found.has(name)) {
+            found.set(name, decodeEntities(value));
+        }
+        match = pattern.exec(tag);
+    }
+    return found;
+}
+function junitOutcome(inner) {
+    if (/<skipped(?:[\s>/])/.test(inner)) {
+        return "skipped";
+    }
+    if (/<failure(?:[\s>/])/.test(inner) || /<error(?:[\s>/])/.test(inner)) {
+        return "failed";
+    }
+    return "passed";
+}
+function readJUnit(xml) {
+    const cases = [];
+    const selfClosed = /<testcase\b([^>]*?)\/>/g;
+    for (const match of xml.matchAll(selfClosed)) {
+        const attrs = attributes(match[1] ?? "");
+        const name = attrs.get("name") ?? "";
+        const classname = attrs.get("classname") ?? "";
+        cases.push({
+            id: classname === "" ? name : `${classname}#${name}`,
+            title: name,
+            outcome: "passed",
+        });
+    }
+    const stripped = xml.replace(selfClosed, "");
+    const paired = /<testcase\b([^>]*)>([\s\S]*?)<\/testcase>/g;
+    for (const match of stripped.matchAll(paired)) {
+        const attrs = attributes(match[1] ?? "");
+        const name = attrs.get("name") ?? "";
+        const classname = attrs.get("classname") ?? "";
+        cases.push({
+            id: classname === "" ? name : `${classname}#${name}`,
+            title: name,
+            outcome: junitOutcome(match[2] ?? ""),
+        });
+    }
+    return cases;
+}
+function trxOutcome(raw) {
+    const outcome = raw.toLowerCase();
+    if (outcome === "passed") {
+        return "passed";
+    }
+    if (outcome === "failed") {
+        return "failed";
+    }
+    if (outcome === "skipped" || outcome === "notexecuted") {
+        return "skipped";
+    }
+    return undefined;
+}
+function readTrx(xml) {
+    if (!/<TestRun\b/.test(xml)) {
+        return undefined;
+    }
+    const cases = [];
+    const pattern = /<UnitTestResult\b([^>]*?)\/>/g;
+    for (const match of xml.matchAll(pattern)) {
+        const attrs = attributes(match[1] ?? "");
+        const name = attrs.get("testName") ?? "";
+        const id = attrs.get("testId") ?? name;
+        const outcome = trxOutcome(attrs.get("outcome") ?? "");
+        if (outcome === undefined) {
+            return undefined;
+        }
+        cases.push({ id, title: name, outcome });
+    }
+    return cases;
+}
+export function readTestReport(xml) {
+    const text = xml.trim();
+    if (text === "") {
+        return malformed();
+    }
+    const trx = readTrx(text);
+    if (trx !== undefined) {
+        return ok(trx);
+    }
+    if (!/<testsuite\b/.test(text) && !/<testsuites\b/.test(text)) {
+        return malformed();
+    }
+    return ok(readJUnit(text));
+}

package/dist/kernel/version.d.ts

@@ -0,0 +1,2 @@
+import { type Result } from "./result.ts";
+export declare function installedEngineVersion(): Promise<Result<string>>;