@akira-tl/forgerelay 0.1.0

package/dist/process-sessions.js

@@ -0,0 +1,337 @@
+import { spawn } from "node:child_process";
+import { resolveShellCommand, terminateProcessTree } from "./process-platform.js";
+const DEFAULT_EXEC_YIELD_MS = 10_000;
+const DEFAULT_INTERACTIVE_YIELD_MS = 250;
+const DEFAULT_POLL_YIELD_MS = 5_000;
+const MAX_COMMAND_YIELD_MS = 30_000;
+const MAX_POLL_YIELD_MS = 110_000;
+const DEFAULT_MAX_OUTPUT_TOKENS = 10_000;
+const DEFAULT_BUFFER_CHARACTERS = 1_000_000;
+const COMPLETED_SESSION_TTL_MS = 5 * 60 * 1_000;
+const DEFAULT_COLUMNS = 80;
+const DEFAULT_ROWS = 24;
+function boundedInteger(value, fallback, maximum) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error("Duration and output limits must be non-negative.");
+    }
+    return Math.min(Math.floor(value), maximum);
+}
+function terminalSize(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < 1 || value > 1_000) {
+        throw new Error("Terminal dimensions must be integers between 1 and 1000.");
+    }
+    return value;
+}
+function processEnvironment(input) {
+    return {
+        ...Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined)),
+        NO_COLOR: "1",
+        TERM: "dumb",
+        PAGER: "cat",
+        GIT_PAGER: "cat",
+        GH_PAGER: "cat",
+        CODEX_CI: "1",
+        LANG: process.env.LANG ?? "C.UTF-8",
+        LC_ALL: process.env.LC_ALL ?? "C.UTF-8",
+        ...(input?.workspaceId ? { FORGERELAY_WORKSPACE_ID: input.workspaceId, DEVSPACE_WORKSPACE_ID: input.workspaceId } : {}),
+        ...(input?.workspaceRoot ? { FORGERELAY_WORKSPACE_ROOT: input.workspaceRoot, DEVSPACE_WORKSPACE_ROOT: input.workspaceRoot } : {}),
+    };
+}
+function codePointLength(value) {
+    return Array.from(value).length;
+}
+function sliceCodePoints(value, start, end) {
+    return Array.from(value).slice(start, end).join("");
+}
+function takeHead(value, count) {
+    if (count <= 0)
+        return "";
+    return sliceCodePoints(value, 0, count);
+}
+function takeTail(value, count) {
+    if (count <= 0)
+        return "";
+    const characters = Array.from(value);
+    return characters.slice(Math.max(0, characters.length - count)).join("");
+}
+function splitBudget(maxCharacters) {
+    return {
+        head: Math.ceil(maxCharacters / 2),
+        tail: Math.floor(maxCharacters / 2),
+    };
+}
+function formatHeadTail(head, tail, omittedCharacters) {
+    if (omittedCharacters <= 0)
+        return head + tail;
+    return `${head}\n... output truncated (${omittedCharacters} characters omitted) ...\n${tail}`;
+}
+export class HeadTailBuffer {
+    maxCharacters;
+    head = "";
+    tail = "";
+    totalCharacters = 0;
+    constructor(maxCharacters) {
+        this.maxCharacters = maxCharacters;
+        if (!Number.isInteger(maxCharacters) || maxCharacters < 1) {
+            throw new Error("Head/tail buffer limit must be a positive integer.");
+        }
+    }
+    append(output) {
+        if (!output)
+            return;
+        const previousTotal = this.totalCharacters;
+        this.totalCharacters += codePointLength(output);
+        if (this.totalCharacters <= this.maxCharacters) {
+            this.head += output;
+            return;
+        }
+        const budget = splitBudget(this.maxCharacters);
+        if (previousTotal <= this.maxCharacters) {
+            const fullOutput = this.head + output;
+            this.head = takeHead(fullOutput, budget.head);
+            this.tail = takeTail(fullOutput, budget.tail);
+            return;
+        }
+        this.tail = takeTail(this.tail + output, budget.tail);
+    }
+    hasOutput() {
+        return this.totalCharacters > 0;
+    }
+    drain(maxCharacters) {
+        if (!Number.isInteger(maxCharacters) || maxCharacters < 1) {
+            throw new Error("Output limit must be a positive integer.");
+        }
+        const omittedByBuffer = Math.max(0, this.totalCharacters - codePointLength(this.head) - codePointLength(this.tail));
+        const retained = formatHeadTail(this.head, this.tail, omittedByBuffer);
+        const output = truncateOutput(retained, maxCharacters);
+        const truncated = omittedByBuffer > 0 || output.truncated;
+        this.head = "";
+        this.tail = "";
+        this.totalCharacters = 0;
+        return { output: output.output, truncated };
+    }
+}
+function truncateOutput(output, maxCharacters) {
+    const outputCharacters = codePointLength(output);
+    if (outputCharacters <= maxCharacters)
+        return { output, truncated: false };
+    const marker = "\n... output truncated ...\n";
+    const markerCharacters = codePointLength(marker);
+    const available = Math.max(0, maxCharacters - markerCharacters);
+    const budget = splitBudget(available);
+    return {
+        output: takeHead(output, budget.head) + marker + takeTail(output, budget.tail),
+        truncated: true,
+    };
+}
+export class ProcessSessionManager {
+    sessions = new Map();
+    maxBufferCharacters;
+    completedSessionTtlMs;
+    nextSessionId = 1;
+    constructor(options = {}) {
+        this.maxBufferCharacters = options.maxBufferCharacters ?? DEFAULT_BUFFER_CHARACTERS;
+        this.completedSessionTtlMs = options.completedSessionTtlMs ?? COMPLETED_SESSION_TTL_MS;
+    }
+    async start(input) {
+        const session = this.createSession(input);
+        this.sessions.set(session.id, session);
+        try {
+            if (input.tty && process.platform !== "win32")
+                await this.startPty(session, input);
+            else
+                this.startPipe(session, input);
+        }
+        catch (error) {
+            this.sessions.delete(session.id);
+            throw error;
+        }
+        const yieldTimeMs = boundedInteger(input.yieldTimeMs, DEFAULT_EXEC_YIELD_MS, MAX_COMMAND_YIELD_MS);
+        await this.waitForExit(session, yieldTimeMs);
+        const snapshot = this.consume(session, input.maxOutputTokens);
+        if (!session.running)
+            this.removeSession(session.id);
+        return snapshot;
+    }
+    async write(input) {
+        const session = this.getOwnedSession(input.workspaceId, input.sessionId);
+        const chars = input.chars ?? "";
+        const interactionRequested = chars.length > 0 || input.columns !== undefined || input.rows !== undefined;
+        if (input.columns !== undefined || input.rows !== undefined) {
+            session.columns = terminalSize(input.columns, session.columns);
+            session.rows = terminalSize(input.rows, session.rows);
+            if (!session.process?.resize) {
+                throw new Error(`Process session ${session.id} is not a PTY and cannot be resized.`);
+            }
+            session.process.resize(session.columns, session.rows);
+        }
+        const interruptRequested = chars.includes("\u0003") && session.running;
+        if (interruptRequested) {
+            session.process?.kill("SIGINT");
+        }
+        const writableChars = chars.replaceAll("\u0003", "");
+        if (writableChars && session.running)
+            session.process?.write(writableChars);
+        if ((interactionRequested || !session.buffer.hasOutput()) && session.running) {
+            const fallback = interactionRequested ? DEFAULT_INTERACTIVE_YIELD_MS : DEFAULT_POLL_YIELD_MS;
+            const maximum = interactionRequested ? MAX_COMMAND_YIELD_MS : MAX_POLL_YIELD_MS;
+            const yieldTimeMs = boundedInteger(input.yieldTimeMs, fallback, maximum);
+            await this.waitForExit(session, yieldTimeMs);
+        }
+        const snapshot = this.consume(session, input.maxOutputTokens);
+        if (!session.running)
+            this.removeSession(session.id);
+        return snapshot;
+    }
+    terminate(workspaceId, sessionId) {
+        const session = this.getOwnedSession(workspaceId, sessionId);
+        if (session.running)
+            session.process?.kill("SIGTERM");
+    }
+    shutdown() {
+        for (const session of this.sessions.values()) {
+            if (session.cleanupTimer)
+                clearTimeout(session.cleanupTimer);
+            if (session.running)
+                session.process?.kill("SIGTERM");
+        }
+        this.sessions.clear();
+    }
+    async waitForExit(session, yieldTimeMs) {
+        let timer;
+        try {
+            await Promise.race([
+                session.exitPromise,
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, yieldTimeMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    createSession(input) {
+        let resolveExit = () => undefined;
+        const exitPromise = new Promise((resolve) => {
+            resolveExit = resolve;
+        });
+        return {
+            id: this.nextSessionId++,
+            workspaceId: input.workspaceId,
+            startedAt: Date.now(),
+            columns: terminalSize(input.columns, DEFAULT_COLUMNS),
+            rows: terminalSize(input.rows, DEFAULT_ROWS),
+            buffer: new HeadTailBuffer(this.maxBufferCharacters),
+            running: true,
+            exitPromise,
+            resolveExit,
+        };
+    }
+    startPipe(session, input) {
+        const shell = resolveShellCommand(input.command);
+        const detached = process.platform !== "win32";
+        const child = spawn(input.command, {
+            cwd: input.cwd,
+            env: processEnvironment({
+                workspaceId: input.workspaceId,
+                workspaceRoot: input.workspaceRoot,
+            }),
+            stdio: "pipe",
+            windowsHide: true,
+            detached,
+            shell: shell.executable,
+        });
+        session.process = {
+            write: (data) => child.stdin.write(data),
+            kill: (signal = "SIGTERM") => terminateProcessTree(child, signal, detached),
+            resize: input.tty ? () => undefined : undefined,
+        };
+        child.stdout.on("data", (data) => this.append(session, data.toString("utf8")));
+        child.stderr.on("data", (data) => this.append(session, data.toString("utf8")));
+        child.on("error", (error) => this.append(session, `${error.message}\n`));
+        child.on("close", (code, signal) => this.finish(session, code ?? undefined, signal ?? undefined));
+    }
+    async startPty(session, input) {
+        let nodePty;
+        try {
+            nodePty = await import("node-pty");
+        }
+        catch {
+            throw new Error("PTY support requires the optional node-pty dependency.");
+        }
+        const shell = resolveShellCommand(input.command);
+        let pty;
+        try {
+            pty = nodePty.spawn(shell.executable, shell.args, {
+                cwd: input.cwd,
+                env: processEnvironment({
+                    workspaceId: input.workspaceId,
+                    workspaceRoot: input.workspaceRoot,
+                }),
+                name: "xterm-256color",
+                cols: session.columns,
+                rows: session.rows,
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+        session.process = {
+            write: (data) => pty.write(data),
+            kill: (signal) => pty.kill(signal),
+            resize: (columns, rows) => pty.resize(columns, rows),
+        };
+        pty.onData((data) => this.append(session, data));
+        pty.onExit(({ exitCode, signal }) => {
+            this.finish(session, exitCode, signal === 0 ? undefined : String(signal));
+        });
+    }
+    finish(session, exitCode, signal) {
+        if (!session.running)
+            return;
+        session.running = false;
+        session.exitCode = exitCode;
+        session.signal = signal;
+        session.resolveExit();
+        session.cleanupTimer = setTimeout(() => this.sessions.delete(session.id), this.completedSessionTtlMs);
+        session.cleanupTimer.unref();
+    }
+    append(session, output) {
+        session.buffer.append(output);
+    }
+    consume(session, maxOutputTokens) {
+        const limit = boundedInteger(maxOutputTokens, DEFAULT_MAX_OUTPUT_TOKENS, 100_000);
+        const maxCharacters = Math.max(256, limit * 4);
+        const buffered = session.buffer.drain(maxCharacters);
+        return {
+            sessionId: session.running ? session.id : undefined,
+            output: buffered.output,
+            outputTruncated: buffered.truncated,
+            running: session.running,
+            exitCode: session.exitCode,
+            signal: session.signal,
+            wallTimeMs: Date.now() - session.startedAt,
+        };
+    }
+    getOwnedSession(workspaceId, sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            throw new Error(`Unknown process session: ${sessionId}`);
+        if (session.workspaceId !== workspaceId) {
+            throw new Error(`Process session ${sessionId} does not belong to workspace ${workspaceId}.`);
+        }
+        return session;
+    }
+    removeSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session?.cleanupTimer)
+            clearTimeout(session.cleanupTimer);
+        this.sessions.delete(sessionId);
+    }
+}

package/dist/request-meta.js

@@ -0,0 +1,9 @@
+function metadataString(meta, key) {
+    if (typeof meta !== "object" || meta === null)
+        return undefined;
+    const value = meta[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+export function openAiConversationScopeId(meta) {
+    return metadataString(meta, "openai/session");
+}

package/dist/review-checkpoints.js

@@ -0,0 +1,219 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { git, getGitEligibility, safeWorkspaceRefSegment } from "./git.js";
+const REVIEW_REF_PREFIX = "refs/devspace/review";
+export function createReviewCheckpointManager() {
+    const states = new Map();
+    const initializations = new Map();
+    return {
+        async initializeWorkspace({ workspaceId, root }) {
+            const existingState = states.get(workspaceId);
+            assertWorkspaceRoot(existingState, workspaceId, root);
+            if (existingState?.root === root && existingState.gitRoot !== undefined) {
+                return;
+            }
+            const pending = initializations.get(workspaceId);
+            if (pending) {
+                await pending;
+                assertWorkspaceRoot(states.get(workspaceId), workspaceId, root);
+                return;
+            }
+            const initialize = initializeWorkspaceState(states, workspaceId, root);
+            initializations.set(workspaceId, initialize);
+            try {
+                await initialize;
+            }
+            finally {
+                if (initializations.get(workspaceId) === initialize) {
+                    initializations.delete(workspaceId);
+                }
+            }
+        },
+        async reviewChanges({ workspaceId, root, since = "last_shown", markReviewed = true }) {
+            let state = states.get(workspaceId);
+            assertWorkspaceRoot(state, workspaceId, root);
+            if (!isReadyState(state)) {
+                await this.initializeWorkspace({ workspaceId, root });
+                state = states.get(workspaceId);
+            }
+            assertWorkspaceRoot(state, workspaceId, root);
+            if (!state?.gitRoot) {
+                throw new Error(state?.diagnostic ?? "show_changes requires a Git workspace in this version.");
+            }
+            let effectiveSince = since;
+            let usedWorkspaceOpenFallback = false;
+            if (since === "last_shown" && !state.baselineRefAvailable) {
+                if (!state.openRefAvailable) {
+                    throw new Error("Review checkpoints are missing; show_changes cannot reconstruct that history safely.");
+                }
+                effectiveSince = "workspace_open";
+                usedWorkspaceOpenFallback = true;
+            }
+            else if (since === "workspace_open" && !state.openRefAvailable) {
+                throw new Error("The workspace-open review checkpoint is missing; show_changes cannot reconstruct that history safely.");
+            }
+            const baselineRef = effectiveSince === "workspace_open" ? state.openRef : state.baselineRef;
+            const baseline = (await git(state.gitRoot, ["rev-parse", "--verify", `${baselineRef}^{commit}`])).stdout.trim();
+            const current = await createWorkingTreeSnapshot(state.gitRoot);
+            const patch = (await git(state.gitRoot, ["diff", "--binary", "--no-color", baseline, current], {
+                maxBuffer: 50 * 1024 * 1024,
+            })).stdout;
+            const numstat = (await git(state.gitRoot, ["diff", "--numstat", "-z", baseline, current], {
+                maxBuffer: 50 * 1024 * 1024,
+            })).stdout;
+            const files = parseNumstat(numstat);
+            const summary = summarizeFiles(files);
+            if (markReviewed) {
+                await git(state.gitRoot, ["update-ref", state.baselineRef, current]);
+                state.baselineRefAvailable = true;
+            }
+            const fallbackNote = usedWorkspaceOpenFallback
+                ? ` The last-shown checkpoint was missing, so changes were compared from workspace open${markReviewed ? " and the baseline was re-established" : ""}.`
+                : "";
+            return {
+                result: `${summary.files === 0
+                    ? `No changes since ${effectiveSince === "workspace_open" ? "workspace open" : "last shown changes"}.`
+                    : `Changed ${summary.files} ${summary.files === 1 ? "file" : "files"} (+${summary.additions} -${summary.removals}).`}${fallbackNote}`,
+                summary,
+                files,
+                patch,
+            };
+        },
+    };
+}
+function assertWorkspaceRoot(state, workspaceId, root) {
+    if (state && state.root !== root) {
+        throw new Error(`Review checkpoint workspace root mismatch for ${workspaceId}.`);
+    }
+}
+async function initializeWorkspaceState(states, workspaceId, root) {
+    const refs = reviewRefs(workspaceId);
+    const state = {
+        root,
+        ...refs,
+        openRefAvailable: false,
+        baselineRefAvailable: false,
+    };
+    try {
+        const eligibility = await getGitEligibility(root);
+        if (!eligibility.ok || !eligibility.gitRoot) {
+            state.diagnostic = eligibility.message ?? "show_changes requires a Git workspace in this version.";
+            return;
+        }
+        const [openCommit, baselineCommit] = await Promise.all([
+            commitForRef(eligibility.gitRoot, state.openRef),
+            commitForRef(eligibility.gitRoot, state.baselineRef),
+        ]);
+        if (!openCommit && !baselineCommit) {
+            const initialCommit = await createWorkingTreeSnapshot(eligibility.gitRoot);
+            await git(eligibility.gitRoot, ["update-ref", state.openRef, initialCommit]);
+            await git(eligibility.gitRoot, ["update-ref", state.baselineRef, initialCommit]);
+            state.openRefAvailable = true;
+            state.baselineRefAvailable = true;
+        }
+        else {
+            state.openRefAvailable = openCommit !== undefined;
+            state.baselineRefAvailable = baselineCommit !== undefined;
+        }
+        state.gitRoot = eligibility.gitRoot;
+    }
+    catch (error) {
+        state.diagnostic = error instanceof Error ? error.message : String(error);
+    }
+    finally {
+        states.set(workspaceId, state);
+    }
+}
+function isReadyState(state) {
+    return state?.gitRoot !== undefined;
+}
+async function commitForRef(gitRoot, ref) {
+    try {
+        return (await git(gitRoot, ["rev-parse", "--verify", `${ref}^{commit}`])).stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function reviewRefs(workspaceId) {
+    const segment = safeWorkspaceRefSegment(workspaceId);
+    return {
+        openRef: `${REVIEW_REF_PREFIX}/${segment}/open`,
+        baselineRef: `${REVIEW_REF_PREFIX}/${segment}/baseline`,
+    };
+}
+async function createWorkingTreeSnapshot(gitRoot) {
+    const tempDir = await mkdtemp(join(tmpdir(), "forgerelay-review-index-"));
+    const indexPath = join(tempDir, "index");
+    const env = checkpointEnv(indexPath);
+    try {
+        await git(gitRoot, ["read-tree", "HEAD"], { env });
+        await git(gitRoot, ["add", "-A", "--", "."], { env });
+        const tree = (await git(gitRoot, ["write-tree"], { env })).stdout.trim();
+        const parent = (await git(gitRoot, ["rev-parse", "--verify", "HEAD^{commit}"])).stdout.trim();
+        return (await git(gitRoot, ["commit-tree", tree, "-p", parent, "-m", "ForgeRelay review snapshot"], { env })).stdout.trim();
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+function checkpointEnv(indexPath) {
+    return {
+        GIT_INDEX_FILE: indexPath,
+        GIT_AUTHOR_NAME: "ForgeRelay",
+        GIT_AUTHOR_EMAIL: "forgerelay@users.noreply.local",
+        GIT_COMMITTER_NAME: "ForgeRelay",
+        GIT_COMMITTER_EMAIL: "forgerelay@users.noreply.local",
+    };
+}
+function parseNumstat(output) {
+    const fields = output.split("\0").filter((field) => field.length > 0);
+    const files = [];
+    for (let index = 0; index < fields.length;) {
+        const header = fields[index++] ?? "";
+        const parts = header.split("\t");
+        const additions = parseStatNumber(parts[0]);
+        const removals = parseStatNumber(parts[1]);
+        if (parts.length >= 3) {
+            const path = parts[2] ?? "";
+            if (path)
+                files.push({ path, type: fileType(path, undefined, additions, removals), additions, removals });
+            continue;
+        }
+        const previousPath = fields[index++];
+        const path = fields[index++];
+        if (!path)
+            continue;
+        files.push({
+            path,
+            previousPath,
+            type: fileType(path, previousPath, additions, removals),
+            additions,
+            removals,
+        });
+    }
+    return files;
+}
+function parseStatNumber(value) {
+    if (!value || value === "-")
+        return 0;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function fileType(path, previousPath, additions, removals) {
+    if (previousPath)
+        return additions === 0 && removals === 0 ? "rename-pure" : "rename-changed";
+    if (additions > 0 && removals === 0)
+        return "new";
+    if (additions === 0 && removals > 0)
+        return "deleted";
+    return "change";
+}
+function summarizeFiles(files) {
+    return files.reduce((summary, file) => ({
+        files: summary.files + 1,
+        additions: summary.additions + file.additions,
+        removals: summary.removals + file.removals,
+    }), { files: 0, additions: 0, removals: 0 });
+}

package/dist/roots.js

@@ -0,0 +1,37 @@
+import { homedir } from "node:os";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+export class AccessDeniedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AccessDeniedError";
+    }
+}
+export function expandHomePath(path) {
+    if (path === "~")
+        return homedir();
+    if (path.startsWith("~/") || path.startsWith("~\\")) {
+        return resolve(homedir(), path.slice(2));
+    }
+    return path;
+}
+export function isPathInsideRoot(path, root) {
+    const resolvedPath = resolve(expandHomePath(path));
+    const resolvedRoot = resolve(expandHomePath(root));
+    const relationship = relative(resolvedRoot, resolvedPath);
+    return (relationship === "" ||
+        (!isAbsolute(relationship) &&
+            !relationship.startsWith("..") &&
+            relationship !== ".." &&
+            !relationship.includes(`..${sep}`)));
+}
+export function assertAllowedPath(path, allowedRoots) {
+    const resolvedPath = resolve(expandHomePath(path));
+    if (allowedRoots.some((root) => isPathInsideRoot(resolvedPath, root))) {
+        return resolvedPath;
+    }
+    throw new AccessDeniedError(`Path is outside allowed roots: ${path}`);
+}
+export function resolveAllowedPath(inputPath, cwd, allowedRoots) {
+    const absolutePath = resolve(cwd, inputPath);
+    return assertAllowedPath(absolutePath, allowedRoots);
+}

package/dist/server-shutdown.js

@@ -0,0 +1,12 @@
+export async function shutdownHttpServer(httpServer, closeApplication) {
+    const httpClosed = new Promise((resolve, reject) => {
+        httpServer.close((error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+    await closeApplication();
+    await httpClosed;
+}