codictator 0.0.0 → 0.1.2

package/dist/kernel/repo-root.js

@@ -0,0 +1,29 @@
+// SPEC §4.1.1: repo-root resolution for the Fs port. Walks up from a start
+// directory to the nearest ancestor holding a `.git` entry and returns its
+// canonical (symlink-resolved) path. Anything else is CDX-E703, never a guess.
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { makeError } from "./errors.js";
+import { err, ok } from "./result.js";
+export async function pathExists(target) {
+    try {
+        await fsp.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function resolveRepoRoot(startDir) {
+    let dir = path.resolve(startDir);
+    while (true) {
+        if (await pathExists(path.join(dir, ".git"))) {
+            return ok(await fsp.realpath(dir));
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            return err(makeError("CDX-E703", `no git repository above ${startDir}`, "Run inside a git repository so paths resolve against its root."));
+        }
+        dir = parent;
+    }
+}

package/dist/kernel/result.d.ts

@@ -0,0 +1,10 @@
+import type { CdxError } from "./errors.ts";
+export type Result<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: CdxError;
+};
+export declare function ok<T>(value: T): Result<T>;
+export declare function err<T>(error: CdxError): Result<T>;

package/dist/kernel/result.js

@@ -0,0 +1,6 @@
+export function ok(value) {
+    return { ok: true, value };
+}
+export function err(error) {
+    return { ok: false, error };
+}

package/dist/kernel/schema-helpers.d.ts

@@ -0,0 +1,11 @@
+import { type Result } from "./result.ts";
+export declare const SUPPORTED_KEYWORDS: ReadonlySet<string>;
+export declare const MAX_REF_DEPTH: number;
+export declare function isObjectRecord(value: unknown): value is Record<string, unknown>;
+export declare function field(schema: Record<string, unknown>, name: string): unknown;
+export declare function jsonType(value: unknown): string;
+export declare function mismatch(path: string, expected: string, detail?: string): Result<void>;
+export declare function unsupported(keyword: string): Result<void>;
+export declare function resolvePointer(root: unknown, pointer: string): unknown;
+export declare function checkType(expected: unknown, value: unknown, path: string): Result<void> | undefined;
+export declare function checkRange(schema: Record<string, unknown>, value: number, path: string): Result<void> | undefined;

package/dist/kernel/schema-helpers.js

@@ -0,0 +1,101 @@
+// SPEC §4.1.2: primitives for the JSON Schema 2020-12 subset validator.
+// Keyword policy, JSON typing, diagnostics, $ref pointer resolution and the
+// non-recursive scalar checks live here. Nothing here recurses into
+// validateAgainst, so schema.ts can import this file without a cycle.
+import { makeError } from "./errors.js";
+import { err } from "./result.js";
+export const SUPPORTED_KEYWORDS = new Set([
+    "type",
+    "properties",
+    "required",
+    "additionalProperties",
+    "items",
+    "enum",
+    "const",
+    "pattern",
+    "minimum",
+    "maximum",
+    "minLength",
+    "maxLength",
+    "minItems",
+    "maxItems",
+    "oneOf",
+    "$ref",
+    "$defs",
+    "definitions",
+]);
+export const MAX_REF_DEPTH = 32;
+export function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Bracket access through a variable keeps noPropertyAccessFromIndexSignature
+// (tsconfig.base.json) satisfied without tripping useLiteralKeys.
+export function field(schema, name) {
+    return schema[name];
+}
+export function jsonType(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (Array.isArray(value)) {
+        return "array";
+    }
+    if (typeof value === "number") {
+        return Number.isInteger(value) ? "integer" : "number";
+    }
+    return typeof value;
+}
+export function mismatch(path, expected, detail) {
+    return err(makeError("CDX-E101", `value at ${path} is invalid: expected ${expected}`, "Fix the value so it matches the schema, then retry.", detail));
+}
+export function unsupported(keyword) {
+    return err(makeError("CDX-E201", `schema uses unsupported keyword "${keyword}"`, "Remove the keyword or teach the kernel validator about it (SPEC §4.1.2)."));
+}
+export function resolvePointer(root, pointer) {
+    if (pointer === "#") {
+        return root;
+    }
+    if (!pointer.startsWith("#/")) {
+        return undefined;
+    }
+    let current = root;
+    for (const raw of pointer.slice(2).split("/")) {
+        const part = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (isObjectRecord(current)) {
+            current = current[part];
+        }
+        else if (Array.isArray(current)) {
+            const index = Number.parseInt(part, 10);
+            current = Number.isSafeInteger(index) ? current[index] : undefined;
+        }
+        else {
+            return undefined;
+        }
+        if (current === undefined) {
+            return undefined;
+        }
+    }
+    return current;
+}
+export function checkType(expected, value, path) {
+    if (typeof expected !== "string") {
+        return unsupported("type");
+    }
+    const actual = jsonType(value);
+    const matches = actual === expected || (expected === "number" && actual === "integer");
+    if (!matches) {
+        return mismatch(path, `type ${expected}`);
+    }
+    return undefined;
+}
+export function checkRange(schema, value, path) {
+    const minimum = field(schema, "minimum");
+    if (typeof minimum === "number" && value < minimum) {
+        return mismatch(path, `minimum ${minimum}`);
+    }
+    const maximum = field(schema, "maximum");
+    if (typeof maximum === "number" && value > maximum) {
+        return mismatch(path, `maximum ${maximum}`);
+    }
+    return undefined;
+}

package/dist/kernel/schema.d.ts

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

package/dist/kernel/schema.js

@@ -0,0 +1,203 @@
+// SPEC §4.1.2: JSON Schema 2020-12 subset validator. Unsupported keywords
+// in a schema are a load error (CDX-E201), never ignored (EC-10). Value
+// mismatches fail with CDX-E101 naming the JSON-pointer path, never the
+// value itself. Primitives and scalar checks live in schema-helpers.ts;
+// the composite checks, $ref orchestration and entry live here.
+import { makeError } from "./errors.js";
+import { parseJson, stableStringify } from "./json.js";
+import { checkPattern } from "./pattern.js";
+import { err, ok } from "./result.js";
+import { checkRange, checkType, field, isObjectRecord, MAX_REF_DEPTH, mismatch, resolvePointer, SUPPORTED_KEYWORDS, unsupported, } from "./schema-helpers.js";
+function checkString(schema, value, path) {
+    const minLength = field(schema, "minLength");
+    if (typeof minLength === "number" && value.length < minLength) {
+        return mismatch(path, `minLength ${minLength}`);
+    }
+    const maxLength = field(schema, "maxLength");
+    if (typeof maxLength === "number" && value.length > maxLength) {
+        return mismatch(path, `maxLength ${maxLength}`);
+    }
+    const pattern = field(schema, "pattern");
+    if (typeof pattern === "string") {
+        const safe = checkPattern(pattern);
+        if (!safe.ok) {
+            return err(safe.error);
+        }
+        let expression;
+        try {
+            expression = new RegExp(pattern);
+        }
+        catch {
+            return unsupported("pattern");
+        }
+        if (!expression.test(value)) {
+            return mismatch(path, `pattern ${pattern}`);
+        }
+    }
+    return undefined;
+}
+function checkArray(schema, root, value, path, depth) {
+    const minItems = field(schema, "minItems");
+    if (typeof minItems === "number" && value.length < minItems) {
+        return mismatch(path, `minItems ${minItems}`);
+    }
+    const maxItems = field(schema, "maxItems");
+    if (typeof maxItems === "number" && value.length > maxItems) {
+        return mismatch(path, `maxItems ${maxItems}`);
+    }
+    const items = field(schema, "items");
+    if (items !== undefined) {
+        if (Array.isArray(items)) {
+            return unsupported("prefixItems");
+        }
+        for (let index = 0; index < value.length; index += 1) {
+            const checked = validateAgainst(items, value[index], root, `${path}/${index}`, depth + 1);
+            if (!checked.ok) {
+                return checked;
+            }
+        }
+    }
+    return undefined;
+}
+function checkObject(schema, root, value, path, depth) {
+    const required = field(schema, "required");
+    if (Array.isArray(required)) {
+        for (const name of required) {
+            if (typeof name !== "string") {
+                return unsupported("required");
+            }
+            if (value[name] === undefined) {
+                return mismatch(path, `required property "${name}"`);
+            }
+        }
+    }
+    const properties = field(schema, "properties");
+    if (isObjectRecord(properties)) {
+        for (const key of Object.keys(properties)) {
+            if (value[key] !== undefined) {
+                const checked = validateAgainst(properties[key], value[key], root, `${path}/${key}`, depth + 1);
+                if (!checked.ok) {
+                    return checked;
+                }
+            }
+        }
+    }
+    const additional = field(schema, "additionalProperties");
+    const declared = properties !== undefined && isObjectRecord(properties)
+        ? new Set(Object.keys(properties))
+        : new Set();
+    if (additional === false) {
+        for (const key of Object.keys(value)) {
+            if (!declared.has(key)) {
+                return mismatch(path, `no additional property "${key}"`);
+            }
+        }
+    }
+    else if (additional !== undefined && additional !== true) {
+        for (const key of Object.keys(value)) {
+            if (!declared.has(key)) {
+                const checked = validateAgainst(additional, value[key], root, `${path}/${key}`, depth + 1);
+                if (!checked.ok) {
+                    return checked;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+function validateAgainst(schema, value, root, path, depth) {
+    if (depth > MAX_REF_DEPTH) {
+        return err(makeError("CDX-E902", "schema $ref nesting exceeds the validator budget", "Flatten the schema so $ref chains stay shallow, then retry."));
+    }
+    if (typeof schema === "boolean") {
+        return schema ? ok(undefined) : mismatch(path, "a value the schema allows");
+    }
+    if (!isObjectRecord(schema)) {
+        return unsupported("$ref");
+    }
+    for (const keyword of Object.keys(schema)) {
+        if (!SUPPORTED_KEYWORDS.has(keyword)) {
+            return unsupported(keyword);
+        }
+    }
+    const reference = field(schema, "$ref");
+    if (typeof reference === "string") {
+        const target = resolvePointer(root, reference);
+        if (target === undefined) {
+            return unsupported("$ref");
+        }
+        const resolved = validateAgainst(target, value, root, path, depth + 1);
+        if (!resolved.ok) {
+            return resolved;
+        }
+    }
+    const enumeration = field(schema, "enum");
+    if (Array.isArray(enumeration)) {
+        const wanted = stableStringify(value);
+        const found = enumeration.some((candidate) => stableStringify(candidate) === wanted);
+        if (!found) {
+            return mismatch(path, "one of the enum values");
+        }
+    }
+    if ("const" in schema) {
+        if (stableStringify(field(schema, "const")) !== stableStringify(value)) {
+            return mismatch(path, "the const value");
+        }
+    }
+    const expectedType = field(schema, "type");
+    if (expectedType !== undefined) {
+        const checked = checkType(expectedType, value, path);
+        if (checked !== undefined) {
+            return checked;
+        }
+    }
+    if (typeof value === "number") {
+        const checked = checkRange(schema, value, path);
+        if (checked !== undefined) {
+            return checked;
+        }
+    }
+    if (typeof value === "string") {
+        const checked = checkString(schema, value, path);
+        if (checked !== undefined) {
+            return checked;
+        }
+    }
+    if (Array.isArray(value)) {
+        const checked = checkArray(schema, root, value, path, depth);
+        if (checked !== undefined) {
+            return checked;
+        }
+    }
+    if (isObjectRecord(value)) {
+        const checked = checkObject(schema, root, value, path, depth);
+        if (checked !== undefined) {
+            return checked;
+        }
+    }
+    const branches = field(schema, "oneOf");
+    if (Array.isArray(branches)) {
+        let matches = 0;
+        let firstFailure;
+        for (const branch of branches) {
+            const checked = validateAgainst(branch, value, root, path, depth + 1);
+            if (checked.ok) {
+                matches += 1;
+            }
+            else if (firstFailure === undefined) {
+                firstFailure = checked;
+            }
+        }
+        if (matches !== 1) {
+            return firstFailure ?? mismatch(path, "exactly one oneOf branch");
+        }
+    }
+    return ok(undefined);
+}
+export function validateSchema(schemaText, value) {
+    const parsed = parseJson(schemaText);
+    if (!parsed.ok) {
+        return err(parsed.error);
+    }
+    return validateAgainst(parsed.value, value, parsed.value, "#", 0);
+}

package/dist/kernel/secret-paths.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_FIXTURE_GLOBS: ReadonlyArray<string>;
+export declare function isSecretReadPath(path: string): boolean;
+export declare function isFixturePath(path: string, globs?: ReadonlyArray<string>): boolean;

package/dist/kernel/secret-paths.js

@@ -0,0 +1,56 @@
+// SPEC §4.7.1 secret-read guard: the paths that must never reach the
+// agent context (tool.pre.read and shell commands that print files). The
+// .env family exempts .env.example; dotfiles with auth lines (.npmrc,
+// .pypirc, nuget.config) block as whole files; home-relative secret dirs
+// match lexically. Also owns the default fixture-glob exemption: values
+// under fixture dirs are test vectors, never live credentials.
+import { globMatch } from "./glob.js";
+const SECRET_BASENAMES = new Set([".npmrc", ".pypirc", "nuget.config"]);
+const SECRET_DIR_SEGMENTS = new Set([".ssh", ".aws", ".gnupg"]);
+export const DEFAULT_FIXTURE_GLOBS = [
+    "**/fixtures/**",
+    "**/fixture/**",
+    "**/__fixtures__/**",
+    "**/testdata/**",
+    "**/test-data/**",
+    "**/*.fixture.*",
+];
+// SPEC §4.7.1: the secret-read guard paths.
+export function isSecretReadPath(path) {
+    const slashed = path.replace(/\\/g, "/");
+    const base = slashed.split("/").pop() ?? "";
+    if (base === ".env" ||
+        (base.startsWith(".env.") && base !== ".env.example")) {
+        return true;
+    }
+    if (base.endsWith(".pem") ||
+        base.endsWith(".key") ||
+        base.endsWith(".p12") ||
+        base.endsWith(".pfx") ||
+        base.startsWith("id_rsa") ||
+        base.startsWith("id_ed25519")) {
+        return true;
+    }
+    if (SECRET_BASENAMES.has(base)) {
+        return true;
+    }
+    const lowered = slashed.toLowerCase();
+    const homeRelative = lowered
+        .replace(/^~[/\\]?/, "")
+        .replace(/^\$home[/\\]?/, "")
+        .replace(/^\$\{home\}[/\\]?/, "")
+        .replace(/^%userprofile%[/\\]?/, "");
+    const segments = homeRelative.split("/");
+    if (segments.some((segment) => SECRET_DIR_SEGMENTS.has(segment)) ||
+        (segments[0] === ".config" && segments[1] === "gh")) {
+        return true;
+    }
+    return false;
+}
+// SPEC §4.7.1: placeholder credentials and test vectors under a declared
+// fixture glob are allowlisted. The kernel default covers the common
+// fixture layouts; the check takes configured globs when the caller has
+// them (phase 4 config), so the default never silently widens.
+export function isFixturePath(path, globs = DEFAULT_FIXTURE_GLOBS) {
+    return globs.some((glob) => globMatch(glob, path));
+}

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

@@ -0,0 +1,4 @@
+import type { SimpleCommand } from "./shell.ts";
+export declare function isProtectedPath(path: string): boolean;
+export declare function matchBypassCommand(cmd: SimpleCommand): string | undefined;
+export declare function scanBypassRawText(text: string): string | undefined;

package/dist/kernel/shell-bypass.js

@@ -0,0 +1,151 @@
+// SPEC §4.19.2 human-only commands: blocked for agents by the shell guard.
+const HUMAN_ONLY = new Set([
+    "init",
+    "uninstall",
+    "waive",
+    "pack accept",
+    "task ack",
+    "baseline capture",
+]);
+function normalizePath(path) {
+    const forward = path.replaceAll("\\", "/");
+    return forward.startsWith("./") ? forward.slice(2) : forward;
+}
+// SPEC §4.14.3 target rows: every generated state path plus the generated
+// CI workflow. Harness config files are entries-mode (drift, EC-6), so user
+// additions there stay allowed and are not protected here.
+export function isProtectedPath(path) {
+    const target = normalizePath(path);
+    if (target === ".codictator" || target.startsWith(".codictator/")) {
+        return true;
+    }
+    if (target === ".githooks" || target.startsWith(".githooks/")) {
+        return true;
+    }
+    if (target === ".husky" || target.startsWith(".husky/")) {
+        return true;
+    }
+    return (target.startsWith(".github/workflows/codictator") &&
+        (target.endsWith(".yml") || target.endsWith(".yaml")));
+}
+function matchGitHooksPath(args) {
+    if (args[0] === "-c" && args[1]?.includes("core.hooksPath") === true) {
+        return "git -c core.hooksPath overrides the installed hooks";
+    }
+    if (args[0] === "config" && args.some((a) => a.includes("core.hooksPath"))) {
+        return "git config core.hooksPath moves hooks away from the installed dir";
+    }
+    return undefined;
+}
+function matchGitNoVerify(args) {
+    if (args[0] === "commit" &&
+        args.some((a) => a === "-n" || a === "--no-verify")) {
+        return "git commit --no-verify skips the pre-commit and commit-msg gates";
+    }
+    if (args[0] === "push" && args.includes("--no-verify")) {
+        return "git push --no-verify skips the pre-push gate";
+    }
+    return undefined;
+}
+function matchGitRm(args) {
+    if (args[0] === "rm" && args.some((a) => isProtectedPath(a))) {
+        return "git rm on a protected guardrail path";
+    }
+    return undefined;
+}
+function matchGit(cmd) {
+    if (cmd.name !== "git") {
+        return undefined;
+    }
+    return (matchGitHooksPath(cmd.argv) ??
+        matchGitNoVerify(cmd.argv) ??
+        matchGitRm(cmd.argv));
+}
+function matchDestructive(cmd) {
+    if (cmd.name === "chmod" &&
+        cmd.argv.includes("-x") &&
+        cmd.argv.some((a) => a === ".githooks" ||
+            a.startsWith(".githooks/") ||
+            a.startsWith(".husky/"))) {
+        return "chmod -x on hooks disables the git gates";
+    }
+    if ((cmd.name === "rm" || cmd.name === "mv") &&
+        cmd.argv.some((a) => isProtectedPath(a))) {
+        return `${cmd.name} on a protected guardrail path`;
+    }
+    return undefined;
+}
+function matchHost(cmd) {
+    if (cmd.name !== "gh") {
+        return undefined;
+    }
+    const args = cmd.argv;
+    if (args[0] === "workflow" && args[1] === "disable") {
+        return "gh workflow disable turns off the merge gate";
+    }
+    if (args[0] === "api" &&
+        args.some((a) => /rules|protection|rulesets/.test(a))) {
+        const flagAt = args.findIndex((a) => a === "-X" || a === "--method");
+        const method = flagAt >= 0 ? args[flagAt + 1] : undefined;
+        if (method !== undefined && method !== "GET") {
+            return "gh api writes to branch protection or rulesets";
+        }
+    }
+    return undefined;
+}
+function matchNpm(cmd) {
+    if (cmd.name === "npm" &&
+        ["uninstall", "remove", "un", "rm"].includes(cmd.argv[0] ?? "") &&
+        cmd.argv.some((a) => a === "codictator")) {
+        return "npm uninstall codictator removes the engine the gates run on";
+    }
+    return undefined;
+}
+function matchHumanOnly(cmd) {
+    const at = cmd.argv.findIndex((a) => a === "codictator" || a.endsWith("/codictator"));
+    const base = at >= 0
+        ? cmd.argv.slice(at + 1)
+        : cmd.name === "codictator"
+            ? cmd.argv
+            : [];
+    if (base.length === 0) {
+        return undefined;
+    }
+    const head = `${base[0]}${base[1] === undefined ? "" : ` ${base[1]}`}`;
+    if (HUMAN_ONLY.has(base[0] ?? "") || HUMAN_ONLY.has(head)) {
+        return `human-only codictator command \`${head}\` invoked by an agent`;
+    }
+    return undefined;
+}
+// SPEC §4.14.3 command table: the bypass shapes matched against each
+// parsed command. The caller collects the commands so wrappers (bash -c,
+// env, $(…)) are analysed, not trusted.
+export function matchBypassCommand(cmd) {
+    return (matchGit(cmd) ??
+        matchDestructive(cmd) ??
+        matchHost(cmd) ??
+        matchNpm(cmd) ??
+        matchHumanOnly(cmd));
+}
+// SPEC §4.7.2 backstop: raw tokens catch bypass shapes the structured parse
+// missed; parse failure alone never becomes an allow.
+export function scanBypassRawText(text) {
+    const lowered = ` ${text.toLowerCase()} `;
+    if (lowered.includes("--no-verify")) {
+        return "raw --no-verify flag bypasses the git gates";
+    }
+    if (/(^|\s)git\s.*\scommit\s.*\s-n(\s|$)/.test(`${text} `)) {
+        return "raw git commit -n bypasses the git gates";
+    }
+    if (lowered.includes("core.hookspath")) {
+        return "raw core.hooksPath override moves hooks away from the installed dir";
+    }
+    if (/(^|\s)husky=0(\s|;|$)/.test(lowered) ||
+        /(^|\s)skip=[^\s]+/.test(lowered)) {
+        return "raw HUSKY=0/SKIP= assignment disables the hooks";
+    }
+    if (lowered.includes("workflow disable")) {
+        return "raw workflow disable turns off the merge gate";
+    }
+    return undefined;
+}

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

@@ -0,0 +1,6 @@
+import type { SimpleCommand } from "./shell.ts";
+export declare function commandName(command: SimpleCommand): string;
+export declare function nonFlagArgs(command: SimpleCommand): Array<string>;
+export declare const SCRIPT_NAMES: Set<string>;
+export declare function baseName(word: string): string;
+export declare function buildShellCommand(pipeline: Array<SimpleCommand>, words: ReadonlyArray<string>, raw: string, raised: boolean, scripts: ReadonlyArray<string>, descend: (inner: string) => void): void;