codictator 0.0.0 → 0.1.2

package/dist/kernel/errors.d.ts

@@ -0,0 +1,7 @@
+export interface CdxError {
+    readonly code: string;
+    readonly message: string;
+    readonly detail?: string;
+    readonly remediation: string;
+}
+export declare function makeError(code: string, message: string, remediation: string, detail?: string): CdxError;

package/dist/kernel/errors.js

@@ -0,0 +1,6 @@
+export function makeError(code, message, remediation, detail) {
+    if (detail === undefined) {
+        return { code, message, remediation };
+    }
+    return { code, message, detail, remediation };
+}

package/dist/kernel/fs-confine.d.ts

@@ -0,0 +1,14 @@
+import { type Result } from "./result.ts";
+export interface ConfinedPath {
+    readonly real: string;
+    readonly rel: string;
+}
+export declare function confinePath(input: string, root: string, tempRoot: string): Promise<Result<ConfinedPath>>;
+export declare class Confiner {
+    private readonly cached;
+    private readonly rootDir;
+    private readonly tempDir;
+    constructor(rootDir: string, tempDir: string);
+    confine(input: string): Promise<Result<ConfinedPath>>;
+    clear(): void;
+}

package/dist/kernel/fs-confine.js

@@ -0,0 +1,129 @@
+// SPEC §4.1.1: symlink-aware confinement for the Fs port. Every path is
+// resolved lexically with toRepoPath (EC-2), then the nearest existing prefix
+// is resolved with realpath and the remainder re-attached, so a write whose
+// real path leaves the repo root and the OS temp dir fails CDX-E701 with
+// nothing written (EC-1). On Windows and macOS default volumes the on-disk
+// case is canonical when the exact spelling is absent (EC-3).
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { ioError, outsideError } from "./fs-errors.js";
+import { toRepoPath } from "./path.js";
+import { pathExists } from "./repo-root.js";
+import { err, ok } from "./result.js";
+function isWithin(child, parent) {
+    const rel = path.relative(parent, child);
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+function isAllowed(real, root, tempRoot) {
+    return (real === root ||
+        real === tempRoot ||
+        isWithin(real, root) ||
+        isWithin(real, tempRoot));
+}
+// SPEC §4.1.2: case-sensitive except on Windows and macOS default volumes,
+// where the repo case is canonical. Missing segments stay missing so writes
+// to new files keep the caller's spelling.
+async function canonicalizeCase(logical, root) {
+    if (process.platform !== "win32" && process.platform !== "darwin") {
+        return logical;
+    }
+    const rel = path.relative(root, logical);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+        return logical;
+    }
+    const parts = rel.split(path.sep);
+    let built = root;
+    let index = 0;
+    while (index < parts.length) {
+        const part = parts[index];
+        if (part === undefined || part === "") {
+            index += 1;
+            continue;
+        }
+        if (await pathExists(path.join(built, part))) {
+            built = path.join(built, part);
+            index += 1;
+            continue;
+        }
+        let entries;
+        try {
+            entries = await fsp.readdir(built);
+        }
+        catch {
+            break;
+        }
+        const folded = part.toLowerCase();
+        const match = entries.find((entry) => entry.toLowerCase() === folded);
+        if (match === undefined) {
+            break;
+        }
+        built = path.join(built, match);
+        index += 1;
+    }
+    if (index >= parts.length) {
+        return built;
+    }
+    return path.join(built, ...parts.slice(index));
+}
+async function nearestExisting(target, root) {
+    let current = target;
+    while (true) {
+        if (await pathExists(current)) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return root;
+        }
+        current = parent;
+    }
+}
+export async function confinePath(input, root, tempRoot) {
+    const rel = toRepoPath(input);
+    if (!rel.ok) {
+        return err(rel.error);
+    }
+    const logical = rel.value === "." ? root : path.join(root, rel.value);
+    const cased = await canonicalizeCase(logical, root);
+    const base = await nearestExisting(cased, root);
+    let realBase;
+    try {
+        realBase = await fsp.realpath(base);
+    }
+    catch (cause) {
+        return err(ioError("resolve", rel.value, cause));
+    }
+    const rest = path.relative(base, cased);
+    const real = rest === "" ? realBase : path.join(realBase, rest);
+    if (!isAllowed(real, root, tempRoot)) {
+        return err(outsideError());
+    }
+    return ok({ real, rel: rel.value });
+}
+// Per-port confinement cache: one verify evaluation pays the case-fold,
+// nearest-existing and realpath chain once per path instead of once per
+// op, which is what pushed wide evaluations past every guard budget
+// (CDX-E902). The cache lives on the owning port (cleared on write,
+// append and remove, the only tree changes the port can see), never as
+// module state, and shares nothing across evaluations.
+export class Confiner {
+    cached = new Map();
+    rootDir;
+    tempDir;
+    constructor(rootDir, tempDir) {
+        this.rootDir = rootDir;
+        this.tempDir = tempDir;
+    }
+    confine(input) {
+        const hit = this.cached.get(input);
+        if (hit !== undefined) {
+            return hit;
+        }
+        const pending = confinePath(input, this.rootDir, this.tempDir);
+        this.cached.set(input, pending);
+        return pending;
+    }
+    clear() {
+        this.cached.clear();
+    }
+}

package/dist/kernel/fs-errors.d.ts

@@ -0,0 +1,8 @@
+import { type CdxError } from "./errors.ts";
+import { type Result } from "./result.ts";
+export declare function outsideError(): CdxError;
+export declare function notFoundError(rel: string): CdxError;
+export declare function encodingError(rel: string): CdxError;
+export declare function ioError(op: string, rel: string, cause: unknown): CdxError;
+export declare function mapReadError(rel: string, cause: unknown): CdxError;
+export declare function readFailure(rel: string, cause: unknown): Result<never>;

package/dist/kernel/fs-errors.js

@@ -0,0 +1,37 @@
+// SPEC §8: the Fs port's error vocabulary. Expected I/O failures are Results
+// carrying real error codes, never throws: CDX-E701 for confinement, CDX-E903
+// for missing or unreadable data. Messages name the repo-relative path (never
+// file content) so they are safe for logs and events (§9.2).
+import { makeError } from "./errors.js";
+import { err } from "./result.js";
+export function outsideError() {
+    return makeError("CDX-E701", "path escapes the repo root", "Keep the path inside the repo root or the OS temp dir.");
+}
+export function notFoundError(rel) {
+    return makeError("CDX-E903", `no file at ${rel}`, "Create the file first or check the path spelling.");
+}
+export function encodingError(rel) {
+    return makeError("CDX-E903", `file at ${rel} is binary-or-unknown-encoding`, "Read the file with read (bytes) instead of readText.");
+}
+export function ioError(op, rel, cause) {
+    const reason = cause instanceof Error ? cause.message : "unknown failure";
+    return makeError("CDX-E903", `cannot ${op} ${rel}: ${reason}`, "Check permissions and disk space, then retry.");
+}
+function errorCode(cause) {
+    if (typeof cause === "object" &&
+        cause !== null &&
+        "code" in cause &&
+        typeof cause.code === "string") {
+        return cause.code;
+    }
+    return undefined;
+}
+export function mapReadError(rel, cause) {
+    if (errorCode(cause) === "ENOENT") {
+        return notFoundError(rel);
+    }
+    return ioError("read", rel, cause);
+}
+export function readFailure(rel, cause) {
+    return err(mapReadError(rel, cause));
+}

package/dist/kernel/fs.d.ts

@@ -0,0 +1,28 @@
+import type { Fs, FsStat } from "./index.ts";
+import { type Result } from "./result.ts";
+export interface NodeFsOptions {
+    readonly root?: string;
+    readonly startDir?: string;
+    readonly tempDir?: string;
+}
+export declare class NodeFs implements Fs {
+    private readonly root;
+    private readonly tempRoot;
+    private readonly confiner;
+    private constructor();
+    static create(options?: NodeFsOptions): Promise<Result<NodeFs>>;
+    private confine;
+    private loadFile;
+    read(input: string): Promise<Result<Uint8Array>>;
+    readText(input: string): Promise<Result<string>>;
+    private writeAtomic;
+    write(input: string, content: Uint8Array): Promise<Result<void>>;
+    append(input: string, content: Uint8Array): Promise<Result<void>>;
+    stat(input: string): Promise<Result<FsStat>>;
+    list(dir: string): Promise<Result<Array<string>>>;
+    private collectGlob;
+    glob(pattern: string, dir: string): Promise<Result<Array<string>>>;
+    exists(input: string): Promise<Result<boolean>>;
+    realpath(input: string): Promise<Result<string>>;
+    remove(input: string): Promise<Result<void>>;
+}

package/dist/kernel/fs.js

@@ -0,0 +1,245 @@
+// SPEC §4.1.1: the real Fs port. All paths resolve against the repo root
+// (explicit, CODICTATOR_ROOT, or .git find-up from cwd); a write whose real
+// path after symlink resolution leaves the repo root or the OS temp dir fails
+// CDX-E701 with nothing written. Writes are atomic (temp file + rename) and
+// never executable (§9.2); appends are a single O_APPEND appendFile so
+// concurrent hook processes never interleave lines (§4.18.1). Text is UTF-8
+// with the BOM stripped; non-UTF-8 stays bytes and readText reports
+// binary-or-unknown-encoding (EC-12).
+import { randomBytes } from "node:crypto";
+import { promises as fsp } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { makeError } from "./errors.js";
+import { Confiner } from "./fs-confine.js";
+import { encodingError, ioError, outsideError, readFailure, } from "./fs-errors.js";
+import { globMatch } from "./glob.js";
+import { pathExists, resolveRepoRoot } from "./repo-root.js";
+import { err, ok } from "./result.js";
+const WRITE_SUFFIX_BYTES = 8;
+function isRootPath(real, root, tempRoot) {
+    return real === root || real === tempRoot;
+}
+export class NodeFs {
+    root;
+    tempRoot;
+    confiner;
+    constructor(root, tempRoot) {
+        this.root = root;
+        this.tempRoot = tempRoot;
+        this.confiner = new Confiner(root, tempRoot);
+    }
+    static async create(options = {}) {
+        const { CODICTATOR_ROOT } = process.env;
+        const explicit = options.root ?? CODICTATOR_ROOT;
+        try {
+            const tempRoot = await fsp.realpath(options.tempDir ?? tmpdir());
+            if (explicit !== undefined) {
+                const real = await fsp.realpath(explicit);
+                const st = await fsp.stat(real);
+                if (!st.isDirectory()) {
+                    return err(makeError("CDX-E903", `repo root ${explicit} is not a directory`, "Point the root at a directory holding the repo."));
+                }
+                return ok(new NodeFs(real, tempRoot));
+            }
+        }
+        catch (cause) {
+            return err(ioError("resolve root", explicit ?? tmpdir(), cause));
+        }
+        const resolved = await resolveRepoRoot(options.startDir ?? process.cwd());
+        if (!resolved.ok) {
+            return err(resolved.error);
+        }
+        try {
+            const tempRoot = await fsp.realpath(options.tempDir ?? tmpdir());
+            return ok(new NodeFs(resolved.value, tempRoot));
+        }
+        catch (cause) {
+            return err(ioError("resolve temp", tmpdir(), cause));
+        }
+    }
+    confine(input) {
+        return this.confiner.confine(input);
+    }
+    loadFile(real, rel) {
+        return fsp.readFile(real).then((data) => ok(new Uint8Array(data.buffer, data.byteOffset, data.byteLength)), (cause) => readFailure(rel, cause));
+    }
+    async read(input) {
+        const confined = await this.confine(input);
+        if (!confined.ok) {
+            return err(confined.error);
+        }
+        return this.loadFile(confined.value.real, confined.value.rel);
+    }
+    async readText(input) {
+        const confined = await this.confine(input);
+        if (!confined.ok) {
+            return err(confined.error);
+        }
+        const loaded = await this.loadFile(confined.value.real, confined.value.rel);
+        if (!loaded.ok) {
+            return err(loaded.error);
+        }
+        const bytes = loaded.value;
+        const body = bytes.length >= 3 &&
+            bytes[0] === 0xef &&
+            bytes[1] === 0xbb &&
+            bytes[2] === 0xbf
+            ? bytes.subarray(3)
+            : bytes;
+        try {
+            return ok(new TextDecoder("utf-8", { fatal: true }).decode(body));
+        }
+        catch {
+            return err(encodingError(confined.value.rel));
+        }
+    }
+    async writeAtomic(real, rel, content) {
+        const dir = path.dirname(real);
+        const tmp = path.join(dir, `.codictator-${randomBytes(WRITE_SUFFIX_BYTES).toString("hex")}.tmp`);
+        try {
+            await fsp.mkdir(dir, { recursive: true });
+            await fsp.writeFile(tmp, content, { mode: 0o666 });
+            await fsp.rename(tmp, real);
+            return ok(undefined);
+        }
+        catch (cause) {
+            await fsp.rm(tmp, { force: true }).catch(() => undefined);
+            return err(ioError("write", rel, cause));
+        }
+    }
+    async write(input, content) {
+        this.confiner.clear();
+        const confined = await this.confine(input);
+        if (!confined.ok) {
+            return err(confined.error);
+        }
+        if (isRootPath(confined.value.real, this.root, this.tempRoot)) {
+            return err(outsideError());
+        }
+        return this.writeAtomic(confined.value.real, confined.value.rel, content);
+    }
+    async append(input, content) {
+        this.confiner.clear();
+        const confined = await this.confine(input);
+        if (!confined.ok) {
+            return err(confined.error);
+        }
+        if (isRootPath(confined.value.real, this.root, this.tempRoot)) {
+            return err(outsideError());
+        }
+        // SPEC §4.18.1: one O_APPEND appendFile per call, never
+        // read-modify-write, so concurrent hook processes keep whole lines.
+        try {
+            await fsp.mkdir(path.dirname(confined.value.real), { recursive: true });
+            await fsp.appendFile(confined.value.real, content);
+            return ok(undefined);
+        }
+        catch (cause) {
+            return err(ioError("append", confined.value.rel, cause));
+        }
+    }
+    async stat(input) {
+        const confined = await this.confine(input);
+        if (!confined.ok) {
+            return err(confined.error);
+        }
+        try {
+            const st = await fsp.stat(confined.value.real);
+            return ok({
+                isFile: st.isFile(),
+                isDirectory: st.isDirectory(),
+                size: st.size,
+            });
+        }
+        catch (cause) {
+            return readFailure(confined.value.rel, cause);
+        }
+    }
+    async list(dir) {
+        const confined = await this.confine(dir);
+        if (!confined.ok) {
+            return err(confined.error);
+        }
+        try {
+            const names = await fsp.readdir(confined.value.real);
+            names.sort();
+            return ok(names);
+        }
+        catch (cause) {
+            return readFailure(confined.value.rel, cause);
+        }
+    }
+    async collectGlob(root, current, pattern, found) {
+        const entries = await fsp.readdir(current, { withFileTypes: true });
+        const names = entries.map((entry) => entry.name);
+        names.sort();
+        for (const name of names) {
+            const full = path.join(current, name);
+            found.push(path.relative(root, full).split(path.sep).join("/"));
+            // SPEC §4.1.1: lstat, never stat, so a symlinked directory is
+            // listed but never descended into (cycle guard).
+            if ((await fsp.lstat(full)).isDirectory()) {
+                await this.collectGlob(root, full, pattern, found);
+            }
+        }
+    }
+    async glob(pattern, dir) {
+        const confined = await this.confine(dir);
+        if (!confined.ok) {
+            return err(confined.error);
+        }
+        const found = [];
+        try {
+            await this.collectGlob(confined.value.real, confined.value.real, pattern, found);
+        }
+        catch (cause) {
+            return err(ioError("glob", confined.value.rel, cause));
+        }
+        const matched = found.filter((rel) => globMatch(pattern, rel));
+        matched.sort();
+        const prefix = confined.value.rel === "." ? "" : `${confined.value.rel}/`;
+        return ok(matched.map((rel) => `${prefix}${rel}`));
+    }
+    async exists(input) {
+        const confined = await this.confine(input);
+        if (!confined.ok) {
+            return err(confined.error);
+        }
+        return ok(await pathExists(confined.value.real));
+    }
+    async realpath(input) {
+        const confined = await this.confine(input);
+        if (!confined.ok) {
+            return err(confined.error);
+        }
+        try {
+            const real = await fsp.realpath(confined.value.real);
+            const rel = path.relative(this.root, real).split(path.sep).join("/");
+            if (rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel)) {
+                return ok(rel);
+            }
+            return ok(real);
+        }
+        catch (cause) {
+            return readFailure(confined.value.rel, cause);
+        }
+    }
+    async remove(input) {
+        this.confiner.clear();
+        const confined = await this.confine(input);
+        if (!confined.ok) {
+            return err(confined.error);
+        }
+        if (isRootPath(confined.value.real, this.root, this.tempRoot)) {
+            return err(outsideError());
+        }
+        try {
+            await fsp.rm(confined.value.real, { recursive: true, force: true });
+            return ok(undefined);
+        }
+        catch (cause) {
+            return err(ioError("remove", confined.value.rel, cause));
+        }
+    }
+}

package/dist/kernel/git.d.ts

@@ -0,0 +1,16 @@
+import type { Git, Proc } from "./index.ts";
+import { type Result } from "./result.ts";
+export declare class NodeGit implements Git {
+    private readonly proc;
+    private readonly cwd;
+    constructor(proc: Proc, cwd: string);
+    private exec;
+    root(): Promise<Result<string>>;
+    head(): Promise<Result<string>>;
+    stagedFiles(): Promise<Result<Array<string>>>;
+    diff(base: string, head: string): Promise<Result<string>>;
+    show(rev: string, path: string): Promise<Result<string>>;
+    config(key: string): Promise<Result<string>>;
+    log(range: string): Promise<Result<string>>;
+    isClean(): Promise<Result<boolean>>;
+}

package/dist/kernel/git.js

@@ -0,0 +1,125 @@
+// SPEC §4.1.1: the real Git port, implemented over the Proc port running
+// `git`, never mutating history. Every failure is CDX-E703 (SPEC §8: git
+// missing or not a git repository); messages name the operation, never file
+// content or command output (SPEC §9.2, CONVENTIONS).
+import { makeError } from "./errors.js";
+import { err, ok } from "./result.js";
+// Git answers quickly or not at all; a hung git never blocks the hook path
+// past its harness timeout (SPEC §9.3).
+const GIT_TIMEOUT_MS = 30_000;
+// Diffs can be large, but an unbounded child can wedge the hook; past the
+// cap the caller retries a narrower range.
+const GIT_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+function gitMissingError() {
+    return makeError("CDX-E703", "git executable not found on PATH", "Install git and ensure it is on PATH.");
+}
+function gitOpError(op, reason) {
+    return makeError("CDX-E703", `git ${op} ${reason}`, "Install git and run inside a git repository with git on PATH.");
+}
+function procFailure(op, result) {
+    if (result.timedOut) {
+        return gitOpError(op, "timed out");
+    }
+    if (result.truncated) {
+        return gitOpError(op, "output exceeded the size cap");
+    }
+    if (result.code === -1) {
+        return gitMissingError();
+    }
+    if (result.code !== 0) {
+        return gitOpError(op, "failed");
+    }
+    return undefined;
+}
+export class NodeGit {
+    proc;
+    cwd;
+    constructor(proc, cwd) {
+        this.proc = proc;
+        this.cwd = cwd;
+    }
+    exec(argv) {
+        return this.proc.run(argv, {
+            cwd: this.cwd,
+            env: {},
+            timeoutMs: GIT_TIMEOUT_MS,
+            maxOutputBytes: GIT_MAX_OUTPUT_BYTES,
+        });
+    }
+    async root() {
+        const result = await this.exec(["git", "rev-parse", "--show-toplevel"]);
+        const failure = procFailure("rev-parse", result);
+        if (failure !== undefined) {
+            return err(failure);
+        }
+        return ok(result.stdout.trim());
+    }
+    async head() {
+        const result = await this.exec(["git", "rev-parse", "HEAD"]);
+        const failure = procFailure("rev-parse", result);
+        if (failure !== undefined) {
+            return err(failure);
+        }
+        return ok(result.stdout.trim());
+    }
+    async stagedFiles() {
+        const result = await this.exec(["git", "diff", "--name-only", "--cached"]);
+        const failure = procFailure("staged files", result);
+        if (failure !== undefined) {
+            return err(failure);
+        }
+        const files = result.stdout
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line !== "");
+        files.sort();
+        return ok(files);
+    }
+    async diff(base, head) {
+        const result = await this.exec(["git", "diff", base, head]);
+        const failure = procFailure("diff", result);
+        if (failure !== undefined) {
+            return err(failure);
+        }
+        return ok(result.stdout);
+    }
+    async show(rev, path) {
+        const result = await this.exec(["git", "show", `${rev}:${path}`]);
+        const failure = procFailure("show", result);
+        if (failure !== undefined) {
+            return err(failure);
+        }
+        return ok(result.stdout);
+    }
+    async config(key) {
+        const result = await this.exec(["git", "config", "--get", key]);
+        // An unset key exits 1 with no output; like the port fake, unset
+        // text queries answer empty instead of failing.
+        if (result.code === 1 && !result.timedOut && !result.truncated) {
+            return ok("");
+        }
+        const failure = procFailure("config", result);
+        if (failure !== undefined) {
+            return err(failure);
+        }
+        return ok(result.stdout.trim());
+    }
+    async log(range) {
+        // Fixed format: default log output carries locale-dependent dates,
+        // which would break byte-identical replay (CONVENTIONS).
+        const result = await this.exec(["git", "log", "--format=%H %s", range]);
+        const failure = procFailure("log", result);
+        if (failure !== undefined) {
+            return err(failure);
+        }
+        return ok(result.stdout);
+    }
+    async isClean() {
+        const result = await this.exec(["git", "status", "--porcelain"]);
+        const failure = procFailure("status", result);
+        if (failure !== undefined) {
+            return err(failure);
+        }
+        return ok(result.stdout.trim() === "");
+    }
+}

package/dist/kernel/glob.d.ts

@@ -0,0 +1 @@
+export declare function globMatch(pattern: string, path: string): boolean;