@jamie-tam/forge 6.0.0 → 6.2.0

package/dist/active-manifest.js

@@ -1,229 +0,0 @@
-/**
- * Active manifest pointer — `.forge/state/active-manifest.json`.
- *
- * Records which manifest the current session "owns". Used by:
- *   - `telemetry.sh` to tag every Skill/Agent invocation with a slice context
- *     captured AT INVOCATION TIME (per Codex round-1 #3 — race semantics).
- *   - `gate-enforcer.sh` (via `gate-check` CLI) to confirm a gate edit
- *     targets the same manifest as the active pointer; otherwise refuses.
- *
- * Write semantics: atomic rename. The pointer is tiny and infrequently
- * written; full `flock(2)` is overkill. `O_EXCL`-style temp + atomic
- * `rename(2)` is sufficient for the single-agent-multiple-tab footgun.
- *
- * Read semantics: missing file → null. Corrupt JSON → throw. The system
- * should never silently degrade enforcement on corruption.
- */
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
-import { execSync } from "node:child_process";
-/** Resolve the project's `.forge/state/` directory. Mirrors telemetry.sh /
- *  session-start.sh resolution: prefer `git rev-parse --show-toplevel`,
- *  fall back to cwd. */
-export function getStateDir(cwd = process.cwd()) {
-    let projectRoot = cwd;
-    try {
-        const out = execSync("git rev-parse --show-toplevel", {
-            cwd,
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        projectRoot = out.toString().trim() || cwd;
-    }
-    catch {
-        // Not a git repo; fall back to cwd. Same behavior as the bash hooks.
-    }
-    return resolve(projectRoot, ".forge", "state");
-}
-export function getActivePointerPath(cwd) {
-    return resolve(getStateDir(cwd), "active-manifest.json");
-}
-/** Read the active pointer. Returns null if not set; throws on corruption. */
-export function getActiveManifest(cwd) {
-    const path = getActivePointerPath(cwd);
-    if (!existsSync(path))
-        return null;
-    let raw;
-    try {
-        raw = readFileSync(path, "utf-8");
-    }
-    catch (e) {
-        throw new Error(`active-manifest pointer at ${path} cannot be read: ${e.message}`);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (e) {
-        throw new Error(`active-manifest pointer at ${path} is corrupt JSON: ${e.message}. ` +
-            `Either fix the file by hand or run 'aideas-forge active-manifest clear'.`);
-    }
-    if (!parsed || typeof parsed !== "object") {
-        throw new Error(`active-manifest pointer at ${path} is not a JSON object`);
-    }
-    const p = parsed;
-    if (typeof p.manifest_path !== "string" ||
-        typeof p.set_at !== "string" ||
-        typeof p.set_by !== "string") {
-        throw new Error(`active-manifest pointer at ${path} is missing required fields or has wrong types ` +
-            `(manifest_path, set_at, set_by all required, all strings); content: ${raw.slice(0, 200)}`);
-    }
-    if (!isAbsolute(p.manifest_path)) {
-        throw new Error(`active-manifest pointer manifest_path "${p.manifest_path}" must be absolute. ` +
-            `Re-run 'aideas-forge active-manifest set <path>' or 'clear'.`);
-    }
-    // Stale-pointer detection: the pointed-to manifest must still exist as a
-    // regular file. Otherwise enforcement would silently skip slice context.
-    let stat;
-    try {
-        stat = statSync(p.manifest_path);
-    }
-    catch (e) {
-        throw new Error(`active-manifest pointer references a manifest that cannot be read: ` +
-            `${p.manifest_path} (${e.message}). ` +
-            `Run 'aideas-forge active-manifest clear' or set a valid manifest.`);
-    }
-    if (!stat.isFile()) {
-        throw new Error(`active-manifest pointer references "${p.manifest_path}" which is not a regular file ` +
-            `(directory or other). Run 'aideas-forge active-manifest clear'.`);
-    }
-    return {
-        manifest_path: p.manifest_path,
-        set_at: p.set_at,
-        set_by: p.set_by,
-    };
-}
-/** Write the active pointer atomically. Verifies the manifest path exists
- *  unless `skipExistsCheck` is true. */
-export function setActiveManifest(manifestPath, opts = {}) {
-    const absManifest = isAbsolute(manifestPath)
-        ? manifestPath
-        : resolve(opts.cwd ?? process.cwd(), manifestPath);
-    if (!opts.skipExistsCheck) {
-        let stat;
-        try {
-            stat = statSync(absManifest);
-        }
-        catch (e) {
-            throw new Error(`manifest does not exist: ${absManifest} (${e.message})`);
-        }
-        if (!stat.isFile()) {
-            throw new Error(`manifest path is not a regular file: ${absManifest} (got ${stat.isDirectory() ? "directory" : "other"})`);
-        }
-    }
-    const stateDir = getStateDir(opts.cwd);
-    mkdirSync(stateDir, { recursive: true });
-    const pointer = {
-        manifest_path: absManifest,
-        set_at: new Date().toISOString(),
-        set_by: opts.setBy ?? "manual",
-    };
-    const finalPath = getActivePointerPath(opts.cwd);
-    // Atomic write: write to .tmp, rename. POSIX rename(2) is atomic on the
-    // same filesystem; the .tmp suffix avoids torn reads if the writer dies
-    // mid-write or another tab races us. Always clean up the tmp file on
-    // failure — orphans would confuse later operators.
-    const tmpPath = `${finalPath}.${process.pid}.tmp`;
-    let renamed = false;
-    try {
-        writeFileSync(tmpPath, JSON.stringify(pointer, null, 2) + "\n", { mode: 0o644 });
-        renameSync(tmpPath, finalPath);
-        renamed = true;
-    }
-    finally {
-        if (!renamed) {
-            try {
-                rmSync(tmpPath, { force: true });
-            }
-            catch {
-                /* best-effort cleanup */
-            }
-        }
-    }
-    return pointer;
-}
-/** Delete the active pointer. Idempotent — no error if already absent.
- *  Returns true if a pointer existed before this call and was cleared,
- *  false if there was nothing to clear. Concurrent-safe: uses force:true
- *  so a racing clear does not throw. */
-export function clearActiveManifest(cwd) {
-    const path = getActivePointerPath(cwd);
-    const existedBefore = existsSync(path);
-    rmSync(path, { force: true });
-    return existedBefore;
-}
-export async function activeManifestCli(args) {
-    const subcommand = args[0];
-    switch (subcommand) {
-        case "set": {
-            // Parse --set-by flag (supports `--set-by foo` and `--set-by=foo bar`).
-            let setBy = "manual";
-            const positionals = [];
-            for (let i = 1; i < args.length; i++) {
-                const tok = args[i];
-                if (tok === "--set-by") {
-                    setBy = args[++i] ?? "";
-                    if (!setBy) {
-                        console.error("--set-by requires a value");
-                        return { exitCode: 1 };
-                    }
-                }
-                else if (tok.startsWith("--set-by=")) {
-                    setBy = tok.slice("--set-by=".length);
-                    if (!setBy) {
-                        console.error("--set-by requires a value");
-                        return { exitCode: 1 };
-                    }
-                }
-                else if (tok.startsWith("--")) {
-                    console.error(`unknown flag: ${tok}`);
-                    return { exitCode: 1 };
-                }
-                else {
-                    positionals.push(tok);
-                }
-            }
-            const path = positionals[0];
-            if (!path) {
-                console.error("Usage: aideas-forge active-manifest set <path-to-manifest.yaml> [--set-by <label>]");
-                return { exitCode: 1 };
-            }
-            if (positionals.length > 1) {
-                console.error(`unexpected extra arguments: ${positionals.slice(1).join(" ")}. ` +
-                    `Use --set-by "your label" for multi-word labels.`);
-                return { exitCode: 1 };
-            }
-            try {
-                const ptr = setActiveManifest(path, { setBy });
-                console.log(`Active manifest set:\n  ${ptr.manifest_path}\n  (set_by: ${ptr.set_by}, at ${ptr.set_at})`);
-                return { exitCode: 0 };
-            }
-            catch (e) {
-                console.error(`active-manifest set failed: ${e.message}`);
-                return { exitCode: 1 };
-            }
-        }
-        case "get": {
-            try {
-                const ptr = getActiveManifest();
-                if (!ptr) {
-                    console.log("(no active manifest)");
-                    return { exitCode: 0 };
-                }
-                console.log(`${ptr.manifest_path}\n  set_by: ${ptr.set_by}\n  set_at: ${ptr.set_at}`);
-                return { exitCode: 0 };
-            }
-            catch (e) {
-                console.error(`active-manifest get failed: ${e.message}`);
-                return { exitCode: 2 };
-            }
-        }
-        case "clear": {
-            const cleared = clearActiveManifest();
-            console.log(cleared ? "Active manifest cleared." : "(no active manifest to clear)");
-            return { exitCode: 0 };
-        }
-        default:
-            console.error("Usage: aideas-forge active-manifest <set <path> [set_by] | get | clear>");
-            return { exitCode: 1 };
-    }
-}

package/dist/gate-check.js

@@ -1,326 +0,0 @@
-/**
- * gate-check CLI — diffs an in-flight manifest edit and reports gate
- * transitions for downstream enforcement (gate-enforcer.sh).
- *
- * Replaces hand-rolled YAML grepping in bash. Reads a Claude Code hook
- * payload from stdin, applies the proposed Edit/Write to the on-disk
- * manifest, and emits the list of gates whose `gate-passed` field is
- * transitioning. Each transition includes its scope (slice vs manifest)
- * and the containing slice ID where applicable.
- *
- * Per Codex Phase 2 design review: the bash hook MUST NOT hand-roll
- * YAML path tracking. This is the helper.
- *
- * Spec:
- *   - Input (stdin, JSON): { tool_name: "Edit"|"Write", tool_input: {...} }
- *   - Edit input:  { file_path, old_string, new_string }
- *   - Write input: { file_path, content }
- *   - Ambiguous Edit (old_string matches 0 or >1 times): fail-closed exit 1.
- *   - YAML parse error in old or new: emitted as error; exit 2.
- *
- * Output (JSON when --json):
- *   { ok: true, transitions: [{gate, scope, slice_id?, transition, path}, ...] }
- *   { ok: false, error: "..." }
- *
- * Exit codes:
- *   0 — transitions extracted (list may be empty)
- *   1 — bad payload, ambiguous edit, or unable to compute new content
- *   2 — internal/file/YAML error
- */
-import { existsSync, readFileSync } from "node:fs";
-import { load as yamlLoad } from "js-yaml";
-// ============================================================================
-// Public API
-// ============================================================================
-export function gateCheck(payload) {
-    // Defend against malformed payloads: stdin can deliver `null`, an array,
-    // or a primitive (`JSON.parse("42") === 42`). Reject before dereferencing.
-    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
-        return {
-            ok: false,
-            error: "payload must be a JSON object (got null, array, or primitive)",
-            exitCode: 1,
-        };
-    }
-    const tool = payload.tool_name;
-    const input = payload.tool_input ?? {};
-    if (tool !== "Edit" && tool !== "Write") {
-        return {
-            ok: true,
-            transitions: [],
-        }; // not a manifest edit; no-op
-    }
-    const filePath = input.file_path;
-    if (!filePath) {
-        return { ok: false, error: "tool_input.file_path is required", exitCode: 1 };
-    }
-    // Read current content (may not exist yet for first Write).
-    let oldContent = "";
-    if (existsSync(filePath)) {
-        try {
-            oldContent = readFileSync(filePath, "utf-8");
-        }
-        catch (e) {
-            return {
-                ok: false,
-                error: `cannot read current file ${filePath}: ${e.message}`,
-                exitCode: 2,
-            };
-        }
-    }
-    // Compute proposed new content.
-    let newContent;
-    if (tool === "Write") {
-        if (typeof input.content !== "string") {
-            return { ok: false, error: "Write requires tool_input.content (string)", exitCode: 1 };
-        }
-        newContent = input.content;
-    }
-    else {
-        // Edit
-        if (typeof input.old_string !== "string" || typeof input.new_string !== "string") {
-            return {
-                ok: false,
-                error: "Edit requires tool_input.old_string and tool_input.new_string (strings)",
-                exitCode: 1,
-            };
-        }
-        if (input.old_string === "") {
-            return { ok: false, error: "Edit old_string must not be empty", exitCode: 1 };
-        }
-        const occurrences = countOccurrences(oldContent, input.old_string);
-        if (occurrences === 0) {
-            return {
-                ok: false,
-                error: `Edit old_string not found in ${filePath}; cannot compute proposed content`,
-                exitCode: 1,
-            };
-        }
-        if (occurrences > 1) {
-            return {
-                ok: false,
-                error: `Edit old_string is ambiguous (${occurrences} occurrences in ${filePath}); broaden the match before retrying`,
-                exitCode: 1,
-            };
-        }
-        newContent = oldContent.replace(input.old_string, input.new_string);
-    }
-    // Parse both as YAML. Use raw js-yaml; gate-check only needs the
-    // structural shape, not v5 invariants (those are verify-manifest's job).
-    let oldParsed;
-    let newParsed;
-    try {
-        oldParsed = oldContent ? yamlLoad(oldContent) : {};
-    }
-    catch (e) {
-        return {
-            ok: false,
-            error: `current file ${filePath} is not valid YAML: ${e.message}`,
-            exitCode: 2,
-        };
-    }
-    try {
-        newParsed = yamlLoad(newContent);
-    }
-    catch (e) {
-        return {
-            ok: false,
-            error: `proposed content is not valid YAML: ${e.message}`,
-            exitCode: 2,
-        };
-    }
-    if (newParsed === null || newParsed === undefined) {
-        return { ok: false, error: "proposed content is empty", exitCode: 1 };
-    }
-    if (!isPlainObject(newParsed)) {
-        return {
-            ok: false,
-            error: "proposed content is not a YAML mapping (got array, scalar, or non-plain object like Date)",
-            exitCode: 1,
-        };
-    }
-    // Walk both manifests for gates; diff.
-    let oldGates;
-    let newGates;
-    try {
-        oldGates = collectGates(oldParsed);
-        newGates = collectGates(newParsed);
-    }
-    catch (e) {
-        // collectGates throws on non-boolean gate-passed (per Codex round-2 #1):
-        // strings/numbers/arrays must fail closed, not silently coerce to truthy.
-        return { ok: false, error: e.message, exitCode: 1 };
-    }
-    const transitions = [];
-    // Iterate paths in sorted order so output is deterministic across runs.
-    const allPaths = [...new Set([...oldGates.keys(), ...newGates.keys()])].sort();
-    for (const yamlPath of allPaths) {
-        const oldVal = oldGates.get(yamlPath);
-        const newVal = newGates.get(yamlPath);
-        const oldPassed = oldVal?.gatePassed ?? false;
-        const newPassed = newVal?.gatePassed ?? false;
-        if (oldPassed === newPassed)
-            continue;
-        const ref = newVal ?? oldVal;
-        // Scope is position-derived (structural truth, per Codex round-2 #4).
-        // The bash hook reads gate-requirements.json for skill/agent lookups;
-        // gate-check does not — that avoided a precedence inversion where a
-        // mis-configured `scope: manifest` on a slice gate could emit a
-        // contradictory `{scope: "manifest", slice_id: "..."}`.
-        const scope = ref.sliceId ? "slice" : "manifest";
-        transitions.push({
-            gate: ref.gate,
-            scope,
-            ...(ref.sliceId ? { slice_id: ref.sliceId } : {}),
-            transition: oldPassed ? "true-to-false" : "false-to-true",
-            path: yamlPath,
-        });
-    }
-    return { ok: true, transitions };
-}
-// ============================================================================
-// Helpers
-// ============================================================================
-function countOccurrences(haystack, needle) {
-    if (needle === "")
-        return 0;
-    let count = 0;
-    let idx = 0;
-    while (true) {
-        const found = haystack.indexOf(needle, idx);
-        if (found === -1)
-            return count;
-        count++;
-        idx = found + needle.length;
-    }
-}
-/** Walk a parsed manifest tree and collect every gate location. Returns a
- *  map keyed by full YAML path → { gate, sliceId, gatePassed }. */
-function collectGates(manifest) {
-    const out = new Map();
-    if (!manifest || typeof manifest !== "object")
-        return out;
-    const m = manifest;
-    // Phase gates: phases.<phase>.<gate-name> = { status, gate-passed }
-    const phases = m.phases;
-    if (phases && typeof phases === "object" && !Array.isArray(phases)) {
-        for (const [phaseName, phaseBlock] of Object.entries(phases)) {
-            if (!phaseBlock || typeof phaseBlock !== "object" || Array.isArray(phaseBlock))
-                continue;
-            for (const [gateName, gateVal] of Object.entries(phaseBlock)) {
-                if (isGateObject(gateVal)) {
-                    const ymlPath = `phases.${phaseName}.${gateName}`;
-                    out.set(ymlPath, {
-                        gate: gateName,
-                        gatePassed: extractGatePassed(gateVal, ymlPath),
-                    });
-                }
-            }
-        }
-    }
-    // Slice gates: slice_graph.slices.<id>.gates.<gate-name> = { status, gate-passed }
-    const sg = m.slice_graph;
-    if (sg && typeof sg === "object" && !Array.isArray(sg)) {
-        const slices = sg.slices;
-        if (slices && typeof slices === "object" && !Array.isArray(slices)) {
-            for (const [sliceId, slice] of Object.entries(slices)) {
-                if (!slice || typeof slice !== "object" || Array.isArray(slice))
-                    continue;
-                const gates = slice.gates;
-                if (!gates || typeof gates !== "object" || Array.isArray(gates))
-                    continue;
-                for (const [gateName, gateVal] of Object.entries(gates)) {
-                    if (isGateObject(gateVal)) {
-                        const ymlPath = `slice_graph.slices.${sliceId}.gates.${gateName}`;
-                        out.set(ymlPath, {
-                            gate: gateName,
-                            sliceId,
-                            gatePassed: extractGatePassed(gateVal, ymlPath),
-                        });
-                    }
-                }
-            }
-        }
-    }
-    return out;
-}
-/** Strict boolean extraction — fail closed on non-boolean gate-passed.
- *  Per Codex round-2 #1: `Boolean("false")` is truthy, which would suppress
- *  expected false→true transitions. Strings, numbers, arrays must throw. */
-function extractGatePassed(gateVal, yamlPath) {
-    const raw = gateVal["gate-passed"];
-    if (raw === true)
-        return true;
-    if (raw === false)
-        return false;
-    throw new Error(`gate-passed at ${yamlPath} must be a boolean (got ${typeof raw}: ${JSON.stringify(raw)})`);
-}
-/** A plain object (not array, not Date, not RegExp, not null). js-yaml will
- *  happily return a Date for a bare YAML timestamp at the document root —
- *  that passes `typeof === "object"` and would slip through naive checks. */
-function isPlainObject(v) {
-    return Object.prototype.toString.call(v) === "[object Object]";
-}
-function isGateObject(v) {
-    return Boolean(v &&
-        typeof v === "object" &&
-        !Array.isArray(v) &&
-        "gate-passed" in v);
-}
-// ============================================================================
-// CLI entry point — `aideas-forge gate-check [--json]`
-// ============================================================================
-export async function gateCheckCli(args) {
-    const json = args.includes("--json");
-    // Read JSON payload from stdin.
-    let stdin;
-    try {
-        stdin = await readStdin();
-    }
-    catch (e) {
-        return emitError(json, `failed to read stdin: ${e.message}`, 2);
-    }
-    let payload;
-    try {
-        payload = JSON.parse(stdin);
-    }
-    catch (e) {
-        return emitError(json, `stdin is not valid JSON: ${e.message}`, 1);
-    }
-    const result = gateCheck(payload);
-    if (!result.ok) {
-        return emitError(json, result.error, result.exitCode);
-    }
-    if (json) {
-        process.stdout.write(JSON.stringify({ ok: true, transitions: result.transitions }) + "\n");
-    }
-    else if (result.transitions.length === 0) {
-        console.log("No gate transitions detected.");
-    }
-    else {
-        console.log(`${result.transitions.length} gate transition(s):`);
-        for (const t of result.transitions) {
-            const where = t.slice_id ? ` (slice: ${t.slice_id})` : "";
-            console.log(`  ${t.transition.padEnd(13)}  ${t.gate}${where}  [${t.scope}]  @ ${t.path}`);
-        }
-    }
-    return 0;
-}
-function emitError(json, message, exitCode) {
-    if (json) {
-        process.stdout.write(JSON.stringify({ ok: false, error: message }) + "\n");
-    }
-    else {
-        console.error(message);
-    }
-    return exitCode;
-}
-function readStdin() {
-    return new Promise((res, rej) => {
-        let data = "";
-        process.stdin.setEncoding("utf-8");
-        process.stdin.on("data", (chunk) => (data += chunk));
-        process.stdin.on("end", () => res(data));
-        process.stdin.on("error", rej);
-    });
-}