codex-snapshots 0.1.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "codex-snapshots",
+  "version": "0.1.0",
+  "description": "Local-first read-only snapshots for Codex, Claude Code, and Trae sessions.",
+  "type": "module",
+  "packageManager": "pnpm@10.20.0",
+  "bin": {
+    "codex-snapshot": "bin/codex-snapshot.mjs",
+    "codex-snapshots": "bin/codex-snapshot.mjs",
+    "codex-snapshot-share": "server/share-api.mjs",
+    "codex-snapshots-site": "scripts/serve-site.mjs"
+  },
+  "keywords": [
+    "codex",
+    "claude",
+    "trae",
+    "agent",
+    "snapshot",
+    "sessions",
+    "redaction"
+  ],
+  "homepage": "https://ffffhx.github.io/codex-snapshots/",
+  "bugs": {
+    "url": "https://github.com/ffffhx/codex-snapshots/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ffffhx/codex-snapshots.git"
+  },
+  "author": "ffffhx",
+  "files": [
+    "bin",
+    "server",
+    "scripts",
+    "site",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "dev": "node bin/codex-snapshot.mjs serve --port 4321",
+    "snapshot": "node bin/codex-snapshot.mjs",
+    "snapshot:daemon": "node bin/codex-snapshot.mjs serve --port 4321",
+    "snapshot:install-daemon": "node scripts/launch-agent.mjs install",
+    "snapshot:uninstall-daemon": "node scripts/launch-agent.mjs uninstall",
+    "snapshot:daemon:status": "node scripts/launch-agent.mjs status",
+    "snapshot:daemon:logs": "node scripts/launch-agent.mjs logs",
+    "site:dev": "node scripts/serve-site.mjs",
+    "share:server": "node server/share-api.mjs",
+    "test:smoke": "node bin/codex-snapshot.mjs --help && node server/share-api.mjs --help && node scripts/serve-site.mjs --help && node --check bin/codex-snapshot.mjs && node --check server/share-api.mjs && node --check scripts/launch-agent.mjs && node --check scripts/serve-site.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "highlight.js": "^11.11.1",
+    "markdown-it": "^14.1.1"
+  }
+}

package/scripts/launch-agent.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const label = process.env.SNAPSHOT_LAUNCH_AGENT_LABEL || "com.codex-snapshots.viewer";
+const uid = process.getuid?.() ?? Number.parseInt(process.env.UID || "", 10);
+const homeDir = os.homedir();
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(scriptDir, "..");
+const launchAgentsDir = path.join(homeDir, "Library", "LaunchAgents");
+const logsDir = path.join(homeDir, "Library", "Logs", "codex-snapshots");
+const plistPath = path.join(launchAgentsDir, `${label}.plist`);
+const stdoutPath = path.join(logsDir, "codex-snapshot.out.log");
+const stderrPath = path.join(logsDir, "codex-snapshot.err.log");
+const defaultApiUrl = "http://127.0.0.1:8787";
+const defaultSiteUrl = "http://127.0.0.1:8787";
+
+const command = process.argv[2] || "status";
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});
+
+async function main() {
+  if (command === "install") {
+    await install();
+    return;
+  }
+  if (command === "uninstall") {
+    await uninstall();
+    return;
+  }
+  if (command === "status") {
+    await status();
+    return;
+  }
+  if (command === "logs") {
+    await logs();
+    return;
+  }
+  printHelp();
+  process.exitCode = 1;
+}
+
+async function install() {
+  const pnpmPath = await resolvePnpmPath();
+  await mkdir(launchAgentsDir, { recursive: true });
+  await mkdir(logsDir, { recursive: true });
+
+  const plist = renderPlist({
+    pnpmPath,
+    apiUrl: process.env.SNAPSHOT_SHARE_API_URL || defaultApiUrl,
+    siteUrl: process.env.SNAPSHOT_SHARE_SITE_URL || defaultSiteUrl,
+  });
+
+  await writeFile(plistPath, plist, "utf8");
+  await bootoutIfLoaded();
+  await execLaunchctl(["bootstrap", guiDomain(), plistPath]);
+  await execLaunchctl(["kickstart", "-k", `${guiDomain()}/${label}`]);
+
+  console.log(`Installed ${label}`);
+  console.log(`Plist: ${plistPath}`);
+  console.log(`Logs: ${stdoutPath}`);
+  console.log(`Preview: http://127.0.0.1:4321/`);
+}
+
+async function uninstall() {
+  await bootoutIfLoaded();
+  await rm(plistPath, { force: true });
+  console.log(`Uninstalled ${label}`);
+}
+
+async function status() {
+  if (!existsSync(plistPath)) {
+    console.log(`Not installed: ${plistPath}`);
+    return;
+  }
+  try {
+    const { stdout } = await execLaunchctl(["print", `${guiDomain()}/${label}`]);
+    const state = stdout.match(/state = ([^\n]+)/)?.[1]?.trim() || "unknown";
+    const pid = stdout.match(/pid = (\d+)/)?.[1] || "";
+    console.log(`${label}: ${state}${pid ? `, pid=${pid}` : ""}`);
+    console.log(`Plist: ${plistPath}`);
+    console.log(`Preview: http://127.0.0.1:4321/`);
+  } catch (error) {
+    console.log(`${label}: installed but not loaded`);
+    console.log(`Plist: ${plistPath}`);
+    if (error instanceof Error && error.message) {
+      console.log(error.message);
+    }
+  }
+}
+
+async function logs() {
+  console.log(`==> ${stdoutPath}`);
+  console.log(await tailFile(stdoutPath));
+  console.log(`==> ${stderrPath}`);
+  console.log(await tailFile(stderrPath));
+}
+
+async function bootoutIfLoaded() {
+  try {
+    await execLaunchctl(["bootout", guiDomain(), plistPath]);
+  } catch {}
+  try {
+    await execLaunchctl(["bootout", `${guiDomain()}/${label}`]);
+  } catch {}
+}
+
+async function resolvePnpmPath() {
+  if (process.env.PNPM_EXECUTABLE) {
+    return process.env.PNPM_EXECUTABLE;
+  }
+  try {
+    const { stdout } = await execFileAsync("/bin/zsh", ["-lc", "command -v pnpm"], {
+      cwd: repoRoot,
+      maxBuffer: 1024 * 1024,
+    });
+    const pnpmPath = stdout.trim().split("\n")[0];
+    if (pnpmPath) {
+      return pnpmPath;
+    }
+  } catch {}
+  throw new Error("Cannot find pnpm. Install pnpm first, or run with PNPM_EXECUTABLE=/absolute/path/to/pnpm.");
+}
+
+function renderPlist({ pnpmPath, apiUrl, siteUrl }) {
+  const shellCommand = `cd ${shellQuote(repoRoot)} && exec ${shellQuote(pnpmPath)} snapshot:daemon`;
+  const stablePath = [
+    path.dirname(pnpmPath),
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+    "/usr/sbin",
+    "/sbin",
+  ].join(":");
+  const env = {
+    PATH: process.env.SNAPSHOT_DAEMON_PATH || stablePath,
+    SNAPSHOT_SHARE_API_URL: apiUrl,
+    SNAPSHOT_SHARE_SITE_URL: siteUrl,
+    SNAPSHOT_VIEWER_ALLOWED_ORIGINS:
+      process.env.SNAPSHOT_VIEWER_ALLOWED_ORIGINS ||
+      "http://127.0.0.1:3000,http://localhost:3000",
+  };
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xmlEscape(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/zsh</string>
+    <string>-lc</string>
+    <string>${xmlEscape(shellCommand)}</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(repoRoot)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${Object.entries(env)
+  .map(([key, value]) => `    <key>${xmlEscape(key)}</key>\n    <string>${xmlEscape(value)}</string>`)
+  .join("\n")}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(stdoutPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(stderrPath)}</string>
+</dict>
+</plist>
+`;
+}
+
+function guiDomain() {
+  if (!Number.isFinite(uid)) {
+    throw new Error("Cannot determine current macOS user id.");
+  }
+  return `gui/${uid}`;
+}
+
+async function execLaunchctl(args) {
+  return execFileAsync("/bin/launchctl", args, {
+    cwd: repoRoot,
+    maxBuffer: 1024 * 1024,
+  });
+}
+
+async function tailFile(filePath, lines = 80) {
+  try {
+    const text = await readFile(filePath, "utf8");
+    return text.split(/\r?\n/).slice(-lines).join("\n").trimEnd() || "(empty)";
+  } catch {
+    return "(missing)";
+  }
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+function xmlEscape(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function printHelp() {
+  console.log(`Usage:
+  pnpm snapshot:install-daemon
+  pnpm snapshot:daemon:status
+  pnpm snapshot:daemon:logs
+  pnpm snapshot:uninstall-daemon
+
+Environment:
+  PNPM_EXECUTABLE=/absolute/path/to/pnpm
+  SNAPSHOT_SHARE_API_URL=${defaultApiUrl}
+  SNAPSHOT_SHARE_SITE_URL=${defaultSiteUrl}
+  SNAPSHOT_VIEWER_ALLOWED_ORIGINS=http://127.0.0.1:3000,http://localhost:3000
+`);
+}

package/scripts/serve-site.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "site");
+const parsed = parseArgs(process.argv.slice(2));
+const host = parsed.host || "127.0.0.1";
+const port = Number(parsed.port || 4323);
+
+if (parsed.help) {
+  printHelp();
+  process.exit(0);
+}
+
+const server = http.createServer(async (request, response) => {
+  try {
+    const url = new URL(request.url || "/", `http://${request.headers.host || `${host}:${port}`}`);
+    const filePath = await resolveFile(url.pathname);
+    response.writeHead(200, {
+      "content-type": contentType(filePath),
+      "cache-control": "no-store",
+    });
+    createReadStream(filePath).pipe(response);
+  } catch {
+    response.writeHead(404, {
+      "content-type": "text/plain; charset=utf-8",
+      "cache-control": "no-store",
+    });
+    response.end("not found");
+  }
+});
+
+await new Promise((resolve, reject) => {
+  server.once("error", reject);
+  server.listen(port, host, resolve);
+});
+
+console.log(`Codex Snapshots website is running at http://${host}:${port}`);
+
+async function resolveFile(pathname) {
+  const decoded = decodeURIComponent(pathname);
+  const normalized = path.normalize(decoded).replace(/^(\.\.[/\\])+/, "");
+  const requested = path.join(root, normalized);
+  const safePath = requested.startsWith(root) ? requested : root;
+  const info = await stat(safePath);
+
+  if (info.isDirectory()) {
+    return path.join(safePath, "index.html");
+  }
+
+  return safePath;
+}
+
+function contentType(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === ".html") return "text/html; charset=utf-8";
+  if (ext === ".css") return "text/css; charset=utf-8";
+  if (ext === ".js") return "application/javascript; charset=utf-8";
+  if (ext === ".svg") return "image/svg+xml";
+  if (ext === ".png") return "image/png";
+  if (ext === ".jpg" || ext === ".jpeg") return "image/jpeg";
+  return "application/octet-stream";
+}
+
+function parseArgs(args) {
+  const options = {
+    help: false,
+    host: "",
+    port: "",
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--") continue;
+    if (arg === "-h" || arg === "--help") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "--host") {
+      options.host = String(args[++index] || "");
+      continue;
+    }
+    if (arg === "--port" || arg === "-p") {
+      options.port = String(args[++index] || "");
+      continue;
+    }
+    throw new Error(`unknown option: ${arg}`);
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log(`codex-snapshots site server
+
+Usage:
+  node scripts/serve-site.mjs [--host 127.0.0.1] [--port 4323]
+`);
+}