codex-imagegen-mcp 0.1.2

package/dist/src/util/fs.js

@@ -0,0 +1,117 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ImagegenError } from "../errors.js";
+import { sleep } from "./http.js";
+export async function ensureDir(dir, mode = 0o700) {
+    await fs.mkdir(dir, { recursive: true, mode });
+}
+export async function pathExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write a file atomically: write a temp file in the same directory, fsync, then rename over the
+ * target. Readers (including other processes) never observe a half-written credentials file.
+ */
+export async function writeFileAtomic(file, data, mode = 0o600) {
+    const dir = path.dirname(file);
+    await ensureDir(dir);
+    const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    const handle = await fs.open(tmp, "w", mode);
+    try {
+        await handle.writeFile(data);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await fs.rename(tmp, file);
+        await fs.chmod(file, mode).catch(() => undefined);
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true }).catch(() => undefined);
+        throw err;
+    }
+}
+/** Parse a JSON file; `undefined` if it does not exist. Throws on malformed JSON. */
+export async function readJsonFile(file) {
+    let text;
+    try {
+        text = await fs.readFile(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+    return JSON.parse(text);
+}
+export function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/**
+ * Cross-process mutex based on an exclusively-created lock file. Used around token refresh so
+ * several server processes (e.g. one per opencode project) never spend the same single-use
+ * refresh token twice.
+ */
+export async function withFileLock(lockPath, fn, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 20_000;
+    const staleMs = options.staleMs ?? 60_000;
+    const deadline = Date.now() + timeoutMs;
+    await ensureDir(path.dirname(lockPath));
+    for (;;) {
+        try {
+            const handle = await fs.open(lockPath, "wx", 0o600);
+            try {
+                await handle.writeFile(JSON.stringify({ pid: process.pid, at: Date.now() }));
+            }
+            finally {
+                await handle.close();
+            }
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            const stat = await fs.stat(lockPath).catch(() => undefined);
+            if (!stat)
+                continue;
+            let stale = Date.now() - stat.mtimeMs > staleMs;
+            if (!stale) {
+                const owner = (await readJsonFile(lockPath).catch(() => undefined));
+                if (typeof owner?.pid === "number" && !isPidAlive(owner.pid))
+                    stale = true;
+            }
+            if (stale) {
+                await fs.rm(lockPath, { force: true });
+                continue;
+            }
+            if (Date.now() > deadline) {
+                throw new ImagegenError("internal", `Timed out waiting for the credentials lock (${lockPath}). If no other process is signing in, delete that file.`);
+            }
+            await sleep(40 + Math.floor(Math.random() * 80));
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await fs.rm(lockPath, { force: true }).catch(() => undefined);
+    }
+}
+//# sourceMappingURL=fs.js.map

package/dist/src/util/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../../src/util/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAElC,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW,EAAE,IAAI,GAAG,KAAK;IACvD,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,CAAS;IACxC,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,IAAyB,EAAE,IAAI,GAAG,KAAK;IACzF,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;IACrB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3G,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC7B,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;IACtB,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IACD,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC3B,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACzD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY;IAC7C,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACvE,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACrD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAQ,GAA6B,CAAC,IAAI,KAAK,OAAO,CAAC;IACzD,CAAC;AACH,CAAC;AAQD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,QAAgB,EAAE,EAAoB,EAAE,OAAO,GAAgB,EAAE;IACrG,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;IAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACxC,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxC,SAAS,CAAC;QACR,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;YACpD,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;YAC/E,CAAC;oBAAS,CAAC;gBACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACvB,CAAC;YACD,MAAM;QACR,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,GAAG,CAAC;YAChE,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC5D,IAAI,CAAC,IAAI;gBAAE,SAAS;YACpB,IAAI,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;YAChD,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,KAAK,GAAG,CAAC,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAkC,CAAC;gBACrG,IAAI,OAAO,KAAK,EAAE,GAAG,KAAK,QAAQ,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC;oBAAE,KAAK,GAAG,IAAI,CAAC;YAC7E,CAAC;YACD,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACvC,SAAS;YACX,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;gBAC1B,MAAM,IAAI,aAAa,CAAC,UAAU,EAAE,+CAA+C,QAAQ,yDAAyD,CAAC,CAAC;YACxJ,CAAC;YACD,MAAM,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAChE,CAAC;AACH,CAAC"}

package/dist/src/util/http.js

@@ -0,0 +1,65 @@
+/** Promise-based sleep that rejects with the signal's reason when aborted. */
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason ?? new DOMException("Aborted", "AbortError"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Combine optional abort signals (undefined entries are ignored). */
+export function anySignal(...signals) {
+    const present = signals.filter((s) => s !== undefined);
+    if (present.length === 0)
+        return undefined;
+    if (present.length === 1)
+        return present[0];
+    return AbortSignal.any(present);
+}
+/** Read a response body once, parsing JSON when possible (never throws on bad JSON). */
+export async function readBody(res) {
+    let text = "";
+    try {
+        text = await res.text();
+    }
+    catch {
+        return { text: "", json: undefined };
+    }
+    let json;
+    try {
+        json = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        json = undefined;
+    }
+    return { text, json };
+}
+export function snippet(text, max = 300) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function str(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+export function num(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim() !== "") {
+        const n = Number(value);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    return undefined;
+}
+//# sourceMappingURL=http.js.map

package/dist/src/util/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/util/http.ts"],"names":[],"mappings":"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"}

package/dist/src/util/invocation.js

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PACKAGE_NAME } from "../constants.js";
+function realpathOrSelf(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+function quoteArg(arg) {
+    return /^[\w@%+=:,./-]+$/.test(arg) ? arg : JSON.stringify(arg);
+}
+/** Figure out how this CLI was launched so hints and installers can reproduce it. */
+export function detectInvocation(argv = process.argv) {
+    const script = argv[1] ?? "";
+    const real = script ? realpathOrSelf(script) : "";
+    if (real.split(path.sep).includes("_npx"))
+        return { kind: "npx", script: real };
+    if (script && path.basename(script) === PACKAGE_NAME)
+        return { kind: "global", script: real };
+    return { kind: "local", script: real };
+}
+/** Command prefix for user-facing hints, e.g. `codex-imagegen-mcp` or `node "/abs/dist/src/cli.js"`. */
+export function cliInvocation(argv = process.argv) {
+    const { kind, script } = detectInvocation(argv);
+    if (kind === "npx")
+        return `npx -y ${PACKAGE_NAME}`;
+    if (kind === "global" || !script.endsWith(".js"))
+        return PACKAGE_NAME;
+    return `node ${quoteArg(script)}`;
+}
+/** argv an MCP client should spawn to start this server over stdio. */
+export function serverCommand(argv = process.argv) {
+    const { kind, script } = detectInvocation(argv);
+    if (kind === "npx")
+        return ["npx", "-y", `${PACKAGE_NAME}@latest`, "serve"];
+    if (kind === "global")
+        return [PACKAGE_NAME, "serve"];
+    return ["node", script, "serve"];
+}
+//# sourceMappingURL=invocation.js.map

package/dist/src/util/invocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation.js","sourceRoot":"","sources":["../../../src/util/invocation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,SAAS,cAAc,CAAC,CAAS;IAC/B,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW;IAC3B,OAAO,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;AAClE,CAAC;AAID,qFAAqF;AACrF,MAAM,UAAU,gBAAgB,CAAC,IAAI,GAAsB,OAAO,CAAC,IAAI;IACrE,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClD,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAChF,IAAI,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,YAAY;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC9F,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACzC,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,aAAa,CAAC,IAAI,GAAsB,OAAO,CAAC,IAAI;IAClE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAChD,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,UAAU,YAAY,EAAE,CAAC;IACpD,IAAI,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,YAAY,CAAC;IACtE,OAAO,QAAQ,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;AACpC,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,aAAa,CAAC,IAAI,GAAsB,OAAO,CAAC,IAAI;IAClE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAChD,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,YAAY,SAAS,EAAE,OAAO,CAAC,CAAC;IAC5E,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACtD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACnC,CAAC"}

package/dist/src/util/open.js

@@ -0,0 +1,41 @@
+import { spawn } from "node:child_process";
+/**
+ * Best-effort: open a URL in the user's default browser. Resolves `true` if a launcher process
+ * started. Honors $BROWSER. Never throws.
+ */
+export function openInBrowser(url, env = process.env) {
+    let command;
+    let args;
+    const custom = env.BROWSER?.trim();
+    if (custom) {
+        command = custom;
+        args = [url];
+    }
+    else if (process.platform === "darwin") {
+        command = "open";
+        args = [url];
+    }
+    else if (process.platform === "win32") {
+        // rundll32 avoids cmd.exe re-parsing the `&` characters in OAuth URLs.
+        command = "rundll32";
+        args = ["url.dll,FileProtocolHandler", url];
+    }
+    else {
+        command = "xdg-open";
+        args = [url];
+    }
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(command, args, { detached: true, stdio: "ignore" });
+            child.once("error", () => resolve(false));
+            child.once("spawn", () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+//# sourceMappingURL=open.js.map

package/dist/src/util/open.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open.js","sourceRoot":"","sources":["../../../src/util/open.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,GAAG,GAAsB,OAAO,CAAC,GAAG;IAC7E,IAAI,OAAe,CAAC;IACpB,IAAI,IAAc,CAAC;IACnB,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC;IACnC,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,GAAG,MAAM,CAAC;QACjB,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;SAAM,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACzC,OAAO,GAAG,MAAM,CAAC;QACjB,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;SAAM,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACxC,uEAAuE;QACvE,OAAO,GAAG,UAAU,CAAC;QACrB,IAAI,GAAG,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC;IAC9C,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,UAAU,CAAC;QACrB,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;IACD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;YACxE,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;YAC1C,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;gBACvB,KAAK,CAAC,KAAK,EAAE,CAAC;gBACd,OAAO,CAAC,IAAI,CAAC,CAAC;YAChB,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,123 @@
+<p align="center">
+  <img src="assets/banner-architecture.jpg" width="100%" alt="Architecture — a travel-poster illustration of a three-tier stone viaduct spanning a canyon, its central arch framing a sun rising behind a peak">
+</p>
+
+# Architecture
+
+A small, layered codebase: two entry points, a shared engine, and three focused subsystems for auth, the backend and images. This page maps the modules, traces one request end to end, and explains the decisions behind the design.
+
+**On this page:** [Module map](#module-map) · [Modules](#modules) · [Request flow](#request-flow-generate_image) · [Design decisions](#design-decisions)
+
+## Module map
+
+```mermaid
+flowchart TB
+    client(["MCP client<br/>opencode · Claude Code · …"]):::ink
+    term(["terminal"]):::ink
+    subgraph entry ["entry points"]
+        server["src/server/<br/>tools · resources · prompts<br/>progress · roots · background sign-in"]:::rust
+        cli["src/cli.ts<br/>login · status · generate · install · doctor"]:::rust
+    end
+    subgraph engine ["shared engine"]
+        gen["generation.ts · remove-background.ts · status.ts"]:::ochre
+    end
+    subgraph subsystems ["subsystems"]
+        backend["src/backend/<br/>images-client · ratelimits"]:::teal
+        auth["src/auth/<br/>manager · oauth · browser/device login<br/>store (own) · borrowed (read-only)"]:::teal
+        images["src/images/<br/>codec · resize · preview · chroma<br/>inputs · output"]:::teal
+    end
+    chatgpt[("chatgpt.com/backend-api<br/>codex/images · wham/usage")]:::cream
+    openai[("auth.openai.com<br/>oauth · deviceauth")]:::cream
+    client -- "stdio JSON-RPC" --> server
+    term --> cli
+    server --> gen
+    cli --> gen
+    gen --> backend
+    gen --> images
+    backend --> auth
+    backend --> chatgpt
+    auth --> openai
+    classDef ink fill:#2A2523,stroke:#9A8C76,color:#E4D9C6
+    classDef rust fill:#A6553B,stroke:#7E3F2B,color:#FFFFFF
+    classDef ochre fill:#D9A05B,stroke:#B5813F,color:#2A2523
+    classDef teal fill:#4E6E63,stroke:#3A544B,color:#FFFFFF
+    classDef cream fill:#E4D9C6,stroke:#A89A80,color:#2A2523
+    style entry fill:#D9A05B1F,stroke:#B5813F,color:#B5813F
+    style engine fill:#D9A05B1F,stroke:#B5813F,color:#B5813F
+    style subsystems fill:#D9A05B1F,stroke:#B5813F,color:#B5813F
+```
+
+## Modules
+
+| Path | Responsibility |
+|---|---|
+| `src/constants.ts` | Protocol constants (issuer, client id, ports, endpoints, limits), each with the reason it has that value |
+| `src/config.ts` | Resolves the environment into a `RuntimeConfig`: paths, URLs, mode, timeouts |
+| `src/auth/` | Sign-in flows, the token store, refresh, and credential source resolution |
+| `src/backend/` | The ChatGPT image and usage HTTP client, error mapping, rate-limit parsing |
+| `src/images/` | Pure-JS image handling: sniffing, codec, resampling, previews, chroma key, I/O |
+| `src/generation.ts` | One generate/edit operation: load inputs → *n* concurrent requests → save → history → previews |
+| `src/remove-background.ts` | One chroma-key operation |
+| `src/status.ts` | Collects and formats sign-in, source and usage status |
+| `src/history.ts` | The append-only `history.jsonl` |
+| `src/server/` | MCP wiring: tools, resources, prompts, instructions, progress, roots, background sign-in |
+| `src/install/` | The opencode installer (JSONC edits, skill copy) and snippets for other clients |
+| `src/doctor.ts` | Environment diagnostics |
+| `src/cli.ts` | The command-line entry point; `serve` is the MCP entry |
+| `skill/imagegen/` | The Agent Skill shipped with the server |
+| `upstream/` | Byte-exact copy of Codex's original skill, for provenance and diffing |
+| `scripts/compose-doc-art.py` | Builds the documentation artwork from raw generations |
+
+## Request flow: `generate_image`
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant T as tool handler
+    participant G as runGeneration
+    participant I as ImagesClient
+    participant A as AuthManager
+    participant B as ChatGPT backend
+    T->>T: start progress heartbeats, resolve workspace (MCP root → cwd)
+    T->>G: request
+    G->>G: validate, load inputs, add the aspect-ratio line, plan output paths
+    par one per variant (n = 1–4)
+        G->>I: createImage
+        I->>A: getCredentials (refresh under the lock if needed)
+        A-->>I: bearer token + account id
+        I->>B: POST Codex-identical body
+        alt 401
+            I->>A: recoverFromUnauthorized (refresh, re-read or next source)
+            I->>B: retry once
+        else 5xx or network error
+            I->>B: retry after 1 s, then 3 s
+        end
+        B-->>I: PNG
+        I-->>G: bytes + metadata
+        G->>G: convert if JPEG, write without overwriting, verify alpha, preview, append history
+    end
+    G-->>T: saved images + partial failures
+    T-->>T: text + preview images + structuredContent (or isError with the next step)
+```
+
+Each variant is saved **as soon as it arrives**, so partial success is kept even if another variant fails.
+
+## Design decisions
+
+- **ChatGPT sign-in only, no API key.** The goal is to use the subscription people already pay for, exactly like Codex. The Platform API needs separate billing and is deliberately out of scope.
+- **The same request as Codex.** Endpoints, body and auth match `codex-rs` byte for byte, so the server behaves like Codex and inherits OpenAI's server-side model upgrades.
+- **Borrowing is read-only.** Refresh tokens are single-use, so a second refresher would sign the owning app out. Borrowed tokens are used until they expire, and are never refreshed or written.
+- **Refresh is lock-serialized.** Clients spawn several server processes (opencode runs one per project). A lock file plus a re-read under the lock means exactly one refresh per rotation.
+- **Honest parameters.** The service ignores model, size, quality, count and format, so the tools don't pretend otherwise. `aspect_ratio` is a prompt line, which the service measurably honors; `n` is fan-out; JPEG is a local conversion.
+- **Previews, not full images, in tool results.** A 1024 px JPEG goes to the model and the full-resolution file goes to disk. That keeps results far below the MCP SDK's 10 MB stdio limit and clients' attachment limits (opencode: 5 MiB, 2000 px), while still letting the model check its work.
+- **No `resource_link` content.** Older clients reject unknown content types, and opencode drops them. Paths go in text and `structuredContent` instead.
+- **Constraints repeated in descriptions.** opencode strips `min`, `max` and `default` from JSON Schemas for OpenAI models, so every limit is also written in the parameter description.
+- **Progress heartbeats.** opencode resets its per-request timeout on progress, so long generations survive its 60 s default without special configuration.
+- **Background sign-in inside the server.** `sign_in` can hand the user a link at once. MCP elicitation isn't widely supported (opencode lacks it), so returning the link as text is the portable choice.
+- **Pure-JS image handling.** `pngjs` and `jpeg-js` mean no native dependencies, so it installs everywhere, which matters because MCP servers are launched from many environments.
+- **Never overwrite.** This mirrors the Codex skill's save policy, and it's enforced in code (`wx` exclusive create with versioned siblings) rather than merely requested of the model.
+- **stdout hygiene.** In `serve`, `console.log`, `console.info` and `console.debug` are redirected to stderr, and logs go to stderr plus `server.log`. The server exits when stdin closes, which is how clients stop stdio servers.
+
+---
+
+<p align="center"><a href="BACKEND.md">← Backend</a> &nbsp;·&nbsp; <a href="README.md">Docs home</a> &nbsp;·&nbsp; <a href="DEVELOPMENT.md">Development →</a></p>