@jamie-tam/forge 6.0.0

package/dist/wiki.js

@@ -0,0 +1,364 @@
+// Pure wiki review operations: list, detail, accept, reject pending dreams.
+// Used by both the CLI subcommands (forge wiki status/accept/reject) and the
+// local web UI (forge wiki ui). One implementation, two interfaces.
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+// ---- Public API ------------------------------------------------------------
+export async function listDreams(root) {
+    const proposedDir = path.join(root, "aiwiki", "proposed");
+    if (!fs.existsSync(proposedDir))
+        return [];
+    const dreams = [];
+    for (const entry of fs.readdirSync(proposedDir)) {
+        const manifestPath = path.join(proposedDir, entry, ".dream-manifest.json");
+        if (!fs.existsSync(manifestPath))
+            continue;
+        try {
+            const m = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+            if (m.review_status !== "pending")
+                continue;
+            dreams.push({
+                dream_id: m.dream_id,
+                trigger: m.trigger,
+                trigger_detail: m.trigger_detail,
+                created_at: m.created_at,
+                age_human: humanAge(m.created_at),
+                changed_pages: m.changed_pages,
+                new_pages: m.new_pages,
+                deleted_pages: m.deleted_pages,
+                lint_status: m.lint_status,
+                scope: m.scope ?? [],
+            });
+        }
+        catch {
+            // Skip malformed manifests; surface in CLI as a warning later if needed.
+        }
+    }
+    return dreams.sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+export async function getDreamDetails(dreamId, root) {
+    const proposedRoot = path.join(root, "aiwiki", "proposed", dreamId);
+    const manifestPath = path.join(proposedRoot, ".dream-manifest.json");
+    if (!fs.existsSync(manifestPath))
+        return null;
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    const files = [];
+    // Walk proposed/ for new + changed files (anything that exists in proposed)
+    for (const proposedFile of walkFiles(proposedRoot)) {
+        if (path.basename(proposedFile) === ".dream-manifest.json")
+            continue;
+        const relPath = path.relative(proposedRoot, proposedFile);
+        const currentPath = path.join(root, "aiwiki", relPath);
+        const kind = fs.existsSync(currentPath)
+            ? "changed"
+            : "new";
+        const diff = await runGitDiff(fs.existsSync(currentPath) ? currentPath : "/dev/null", proposedFile, root);
+        files.push({ path: relPath, kind, diff });
+    }
+    // Find deletions from manifest's prune operations
+    for (const op of manifest.operations ?? []) {
+        if (op.op === "prune" && op.file) {
+            const currentPath = path.join(root, op.file);
+            if (!fs.existsSync(currentPath))
+                continue;
+            const aiwikiPath = path.join(root, "aiwiki");
+            const relToAiwiki = path.relative(aiwikiPath, currentPath);
+            const diff = await runGitDiff(currentPath, "/dev/null", root);
+            files.push({ path: relToAiwiki, kind: "deleted", diff });
+        }
+    }
+    // Sort: new first, then changed, then deleted; alphabetical within each group
+    files.sort((a, b) => {
+        const order = { new: 0, changed: 1, deleted: 2 };
+        const cmp = order[a.kind] - order[b.kind];
+        return cmp !== 0 ? cmp : a.path.localeCompare(b.path);
+    });
+    // Detect concurrent changes: for each file the dream proposes to change/delete,
+    // compare base hash (recorded at dream-creation) to current aiwiki/ state.
+    // A mismatch means something else edited the file between dream creation and now —
+    // accept would silently overwrite that change, so we flag the conflict here.
+    const baseHashes = manifest.base_file_hashes ?? {};
+    for (const f of files) {
+        if (f.kind === "new")
+            continue; // no base content to compare against
+        const aiwikiPath = path.join(root, "aiwiki", f.path);
+        const recordedHash = baseHashes[`aiwiki/${f.path}`];
+        if (!recordedHash)
+            continue; // older dreams without per-file hashes — skip the check
+        const currentHash = fs.existsSync(aiwikiPath)
+            ? sha256File(aiwikiPath)
+            : ""; // file deleted by something else; that's also a conflict
+        if (currentHash !== recordedHash) {
+            f.conflict = { expected_hash: recordedHash, actual_hash: currentHash };
+        }
+    }
+    const hasConflicts = files.some((f) => f.conflict !== undefined);
+    return { manifest, files, has_conflicts: hasConflicts };
+}
+export async function acceptDream(dreamId, root) {
+    // Path containment: resolve root once and require every constructed path
+    // to stay inside it. dreamId and manifest op fields are untrusted inputs —
+    // a malicious dream-manifest could otherwise read or overwrite files
+    // outside aiwiki/ via `..` or absolute paths. Use path.resolve (not
+    // path.join) when combining root with an untrusted segment: resolve honors
+    // an absolute segment by replacing the base, which then trips the
+    // containment check; join would silently treat the absolute segment as
+    // relative.
+    const rootAbs = path.resolve(root);
+    const proposedRoot = assertInsideRoot(rootAbs, path.resolve(rootAbs, "aiwiki", "proposed", dreamId));
+    const manifestPath = path.join(proposedRoot, ".dream-manifest.json");
+    if (!fs.existsSync(manifestPath)) {
+        throw new Error(`Dream not found: ${dreamId}`);
+    }
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    if (manifest.review_status !== "pending") {
+        throw new Error(`Dream ${dreamId} already ${manifest.review_status}; cannot accept`);
+    }
+    // Conflict check: detect any concurrent edits to files this dream touches.
+    // Refuses with structured error so the user can rerun the dream against current
+    // state rather than silently overwriting whatever changed.
+    const conflicts = [];
+    const baseHashes = manifest.base_file_hashes ?? {};
+    for (const [key, expectedHash] of Object.entries(baseHashes)) {
+        const filePath = assertInsideRoot(rootAbs, path.resolve(rootAbs, key));
+        const currentHash = fs.existsSync(filePath) ? sha256File(filePath) : "";
+        if (currentHash !== expectedHash) {
+            conflicts.push(key);
+        }
+    }
+    if (conflicts.length > 0) {
+        throw new Error(`Concurrent changes detected on ${conflicts.length} file(s):\n` +
+            conflicts.map((f) => `  - ${f}`).join("\n") +
+            `\n\nThe wiki state changed between when this dream was created and now. ` +
+            `Either rerun the dream to incorporate the new state, or reject this dream and create a fresh one.`);
+    }
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    // Timestamp is internally generated, but resolve to stay consistent with
+    // the surrounding containment checks.
+    const archiveRoot = assertInsideRoot(rootAbs, path.resolve(rootAbs, ".forge", "wiki-history", ts));
+    fs.mkdirSync(archiveRoot, { recursive: true });
+    const acceptedFiles = [];
+    // Apply prune operations: delete from aiwiki/, archive originals
+    for (const op of manifest.operations ?? []) {
+        if (op.op === "prune" && op.file) {
+            const currentPath = assertInsideRoot(rootAbs, path.resolve(rootAbs, op.file));
+            if (!fs.existsSync(currentPath))
+                continue;
+            const archiveDest = assertInsideRoot(rootAbs, path.resolve(archiveRoot, op.file));
+            fs.mkdirSync(path.dirname(archiveDest), { recursive: true });
+            fs.copyFileSync(currentPath, archiveDest);
+            fs.unlinkSync(currentPath);
+            acceptedFiles.push(op.file);
+        }
+    }
+    // Apply file replacements: copy proposed/{id}/* to aiwiki/*; archive originals.
+    // relPath is computed from already-validated paths inside proposedRoot, but we
+    // keep the containment check as defense-in-depth.
+    for (const proposedFile of walkFiles(proposedRoot)) {
+        if (path.basename(proposedFile) === ".dream-manifest.json")
+            continue;
+        const relPath = path.relative(proposedRoot, proposedFile);
+        const targetPath = assertInsideRoot(rootAbs, path.resolve(rootAbs, "aiwiki", relPath));
+        if (fs.existsSync(targetPath)) {
+            const archiveDest = assertInsideRoot(rootAbs, path.resolve(archiveRoot, "aiwiki", relPath));
+            fs.mkdirSync(path.dirname(archiveDest), { recursive: true });
+            fs.copyFileSync(targetPath, archiveDest);
+        }
+        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+        fs.copyFileSync(proposedFile, targetPath);
+        acceptedFiles.push(path.join("aiwiki", relPath));
+    }
+    // Update manifest with accepted state, then move proposed dir to archive
+    manifest.review_status = "accepted";
+    manifest.reviewed_at = new Date().toISOString();
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    // dreamId is untrusted — route through the containment helper. archiveRoot
+    // is already validated, but `proposed-${dreamId}` could embed traversal.
+    const archivedProposedDest = assertInsideRoot(rootAbs, path.resolve(archiveRoot, `proposed-${dreamId}`));
+    fs.renameSync(proposedRoot, archivedProposedDest);
+    appendDreamHistory(root, {
+        dream_id: dreamId,
+        action: "accepted",
+        timestamp: new Date().toISOString(),
+        files_count: acceptedFiles.length,
+        archived_to: path.relative(root, archiveRoot),
+    });
+    return {
+        dream_id: dreamId,
+        accepted_files: acceptedFiles,
+        archived_to: path.relative(root, archiveRoot),
+    };
+}
+export async function rejectDream(dreamId, reason, root) {
+    const proposedRoot = path.join(root, "aiwiki", "proposed", dreamId);
+    if (!fs.existsSync(proposedRoot)) {
+        throw new Error(`Dream not found: ${dreamId}`);
+    }
+    const manifestPath = path.join(proposedRoot, ".dream-manifest.json");
+    if (fs.existsSync(manifestPath)) {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        manifest.review_status = "rejected";
+        manifest.reviewed_at = new Date().toISOString();
+        manifest.rejection_reason = reason;
+        fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    }
+    appendDreamHistory(root, {
+        dream_id: dreamId,
+        action: "rejected",
+        timestamp: new Date().toISOString(),
+        reason,
+    });
+    fs.rmSync(proposedRoot, { recursive: true, force: true });
+    return { dream_id: dreamId, reason };
+}
+// ---- Helpers ---------------------------------------------------------------
+/**
+ * Asserts that `candidate` resolves to a path inside `rootAbs`. Returns the
+ * resolved absolute path on success. Throws on traversal attempts (absolute
+ * paths pointing elsewhere, `..` escapes, NUL byte injection, or symlinks
+ * pointing outside the root).
+ *
+ * `rootAbs` MUST already be absolute (use `path.resolve()` on the caller side
+ * exactly once). The check is `resolved === rootAbs || resolved.startsWith(rootAbs + sep)`
+ * so siblings like `/foo-bar` vs root `/foo` cannot slip through a prefix match.
+ *
+ * Symlink handling: lexical resolution (path.resolve) is not enough — an
+ * attacker can plant a symlink at `aiwiki/target.md` → `/etc/passwd` and
+ * fs.copyFileSync will follow it. We resolve symlinks before re-asserting
+ * containment:
+ *   - If `candidate` exists, realpath the candidate itself.
+ *   - If `candidate` doesn't exist yet (e.g. archive destination), realpath
+ *     its closest existing ancestor and rebuild the path. This catches the
+ *     case where the *parent* directory is a symlink pointing outside root.
+ *
+ * NUL bytes are rejected early — Node string paths can be smuggled with `\0`
+ * to truncate at the syscall layer, bypassing whatever lexical checks ran first.
+ */
+export function assertInsideRoot(rootAbs, candidate) {
+    if (candidate.includes("\0")) {
+        throw new Error(`Path contains NUL byte (potential truncation attack): "${candidate}"`);
+    }
+    const resolved = path.resolve(candidate);
+    if (resolved !== rootAbs && !resolved.startsWith(rootAbs + path.sep)) {
+        throw new Error(`Path containment violation: "${candidate}" resolves to "${resolved}", ` +
+            `which is outside root "${rootAbs}".`);
+    }
+    // Symlink check: resolve any symlinks in the path components, then re-assert.
+    // We compare against the realpath of rootAbs — on platforms like macOS,
+    // /var is itself a symlink to /private/var, so a lexical rootAbs would
+    // false-positive against a realpath'd candidate.
+    let realRootAbs;
+    try {
+        realRootAbs = fs.realpathSync.native(rootAbs);
+    }
+    catch {
+        // rootAbs doesn't exist — caller hands us a path under a yet-to-be-
+        // created root; trust the lexical check above.
+        return resolved;
+    }
+    // For a path that exists, realpathSync the path itself. For a nonexistent
+    // path, realpath the closest existing ancestor — that catches a symlinked
+    // parent directory even if the final segment hasn't been written yet.
+    let realResolved;
+    try {
+        realResolved = fs.realpathSync.native(resolved);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT")
+            throw err;
+        // Walk up until we hit an existing ancestor, then re-append the
+        // non-existent tail. If every ancestor is fine, the only sneaky symlink
+        // would have to be the path itself — which doesn't exist yet, so it
+        // can't be followed by a copyFileSync until something creates it.
+        let parent = path.dirname(resolved);
+        const tailSegments = [path.basename(resolved)];
+        while (parent !== path.dirname(parent)) {
+            try {
+                const realParent = fs.realpathSync.native(parent);
+                const rebuilt = path.join(realParent, ...tailSegments.reverse());
+                if (rebuilt !== realRootAbs &&
+                    !rebuilt.startsWith(realRootAbs + path.sep)) {
+                    throw new Error(`Path containment violation via symlinked parent: "${candidate}" ` +
+                        `resolves through realpath to "${rebuilt}", outside root "${realRootAbs}".`);
+                }
+                return resolved;
+            }
+            catch (e2) {
+                const c2 = e2.code;
+                if (c2 !== "ENOENT")
+                    throw e2;
+                tailSegments.push(path.basename(parent));
+                parent = path.dirname(parent);
+            }
+        }
+        // Couldn't find any existing ancestor (path is fully fresh, e.g. inside
+        // rootAbs which we trust). Return the lexical resolution.
+        return resolved;
+    }
+    if (realResolved !== realRootAbs &&
+        !realResolved.startsWith(realRootAbs + path.sep)) {
+        throw new Error(`Path containment violation via symlink: "${candidate}" realpath ` +
+            `resolves to "${realResolved}", outside root "${realRootAbs}".`);
+    }
+    return resolved;
+}
+async function runGitDiff(a, b, cwd) {
+    try {
+        const { stdout } = await execFileAsync("git", ["diff", "--no-index", "--no-color", "--", a, b], { cwd, maxBuffer: 10 * 1024 * 1024 });
+        return stdout;
+    }
+    catch (err) {
+        // git diff exits 1 when there are differences — that's expected; capture stdout.
+        const e = err;
+        if (e.code === 1 && typeof e.stdout === "string") {
+            return e.stdout;
+        }
+        return null;
+    }
+}
+function appendDreamHistory(root, entry) {
+    const historyPath = path.join(root, ".forge", "dream-history.jsonl");
+    fs.mkdirSync(path.dirname(historyPath), { recursive: true });
+    fs.appendFileSync(historyPath, `${JSON.stringify(entry)}\n`);
+}
+function walkFiles(dir) {
+    const out = [];
+    function walk(d) {
+        if (!fs.existsSync(d) || !fs.statSync(d).isDirectory())
+            return;
+        for (const entry of fs.readdirSync(d)) {
+            const full = path.join(d, entry);
+            const stat = fs.statSync(full);
+            if (stat.isDirectory())
+                walk(full);
+            else
+                out.push(full);
+        }
+    }
+    walk(dir);
+    return out;
+}
+function sha256File(filePath) {
+    const content = fs.readFileSync(filePath);
+    return `sha256:${crypto.createHash("sha256").update(content).digest("hex")}`;
+}
+function humanAge(iso) {
+    const ms = Date.now() - new Date(iso).getTime();
+    if (Number.isNaN(ms))
+        return "?";
+    const minutes = Math.floor(ms / 60000);
+    if (minutes < 1)
+        return "just now";
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    const days = Math.floor(hours / 24);
+    return `${days}d`;
+}