codex-plus-patcher 0.6.0 → 0.7.1

package/README.md

@@ -39,7 +39,9 @@ The generated app includes a readable Codex Plus runtime under
 `webview/assets/codex-plus/`. Versioned ASAR patches install the runtime,
 built-in plugins, and the small Codex core hooks those plugins use. See
 [Runtime Plugin Support](docs/plugin-support.md) for the currently supported
-plugin interfaces.
+plugin interfaces and [Plugin Architecture](docs/plugin-architecture.md) for
+the layer rules. Use [Plugin Debugging](docs/plugin-debugging.md) for the
+side-by-side dev launch and live proof workflow.
 
 ## How It Works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plus-patcher",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "private": false,
   "description": "Patch queue tool for building a local Codex Plus.app from an installed Codex.app.",
   "repository": {
@@ -20,8 +20,10 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test",
-    "check": "node scripts/check-syntax.js"
+    "test": "node --test tests/*.test.js",
+    "check": "node scripts/check-syntax.js",
+    "check:pr": "node scripts/safe-automerge-pr.js --check",
+    "pr:automerge": "node scripts/safe-automerge-pr.js"
   },
   "engines": {
     "node": ">=20"

package/src/cli.js

@@ -2,7 +2,23 @@
 const os = require("node:os");
 const path = require("node:path");
 
+const {
+  createAuditProgress,
+  DEFAULT_PORT: DEFAULT_AUDIT_PORT,
+  DEFAULT_TARGET: DEFAULT_AUDIT_TARGET,
+  formatAuditJson,
+  formatAuditResult,
+  runAudit,
+} = require("./core/plugin-audit");
 const { readAsar, walkFiles } = require("./core/asar");
+const {
+  DEFAULT_DEV_HOME,
+  DEFAULT_ELECTRON_USER_DATA,
+  formatLaunchDevResult,
+  formatSyncDevHomeResult,
+  launchDevApp,
+  syncDevHome,
+} = require("./core/dev-mode");
 const { patchCodexApp } = require("./core/patch-engine");
 const { resolveReleasePatchDirectory } = require("./core/release");
 const { patchSets: builtInPatchSets } = require("./patches");
@@ -18,15 +34,28 @@ function parseArgs(argv) {
     command: argv.length === 0 ? "help" : "apply",
     source: "/Applications/Codex.app",
     target: path.join(os.homedir(), "Applications", "Codex Plus.app"),
+    sourceHome: path.join(os.homedir(), ".codex"),
+    devHome: DEFAULT_DEV_HOME,
+    electronUserDataPath: DEFAULT_ELECTRON_USER_DATA,
     mode: "builtin",
     releaseAsset: "codex-plus-patches.tgz",
     releaseTag: "latest",
     dryRun: false,
     json: false,
     debug: false,
+    apply: true,
+    launch: true,
+    keepOpen: false,
+    includeNativeOpenProbes: false,
+    noProgress: false,
+    quiet: false,
   };
   const rest = [...argv];
   if (rest[0] && !rest[0].startsWith("--")) args.command = rest.shift();
+  if (args.command === "audit-plugins") {
+    args.target = DEFAULT_AUDIT_TARGET;
+    args.remoteDebuggingPort = DEFAULT_AUDIT_PORT;
+  }
   for (let index = 0; index < rest.length; index += 1) {
     const arg = rest[index];
     const next = () => {
@@ -36,6 +65,13 @@ function parseArgs(argv) {
     };
     if (arg === "--source") args.source = path.resolve(expandPath(next()));
     else if (arg === "--target") args.target = path.resolve(expandPath(next()));
+    else if (arg === "--source-home") args.sourceHome = path.resolve(expandPath(next()));
+    else if (arg === "--dev-home") args.devHome = path.resolve(expandPath(next()));
+    else if (arg === "--electron-user-data") args.electronUserDataPath = path.resolve(expandPath(next()));
+    else if (arg === "--remote-debugging-port" || arg === "--port") {
+      const value = next();
+      args.remoteDebuggingPort = args.command === "audit-plugins" ? Number(value) : value;
+    }
     else if (arg === "--asar") args.asar = path.resolve(expandPath(next()));
     else if (arg === "--file") args.file = next();
     else if (arg === "--contains") args.contains = next();
@@ -45,6 +81,12 @@ function parseArgs(argv) {
     else if (arg === "--release-tag") args.releaseTag = next();
     else if (arg === "--release-asset") args.releaseAsset = next();
     else if (arg === "--dry-run") args.dryRun = true;
+    else if (arg === "--no-apply") args.apply = false;
+    else if (arg === "--no-launch") args.launch = false;
+    else if (arg === "--keep-open") args.keepOpen = true;
+    else if (arg === "--include-native-open-probes") args.includeNativeOpenProbes = true;
+    else if (arg === "--no-progress") args.noProgress = true;
+    else if (arg === "--quiet") args.quiet = true;
     else if (arg === "--debug") args.debug = true;
     else if (arg === "--json" || arg === "--format=json") args.json = true;
     else if (arg === "--format") {
@@ -62,6 +104,9 @@ function helpText() {
   return `Usage:
   codex-plus-patcher
   codex-plus-patcher apply [options]
+  codex-plus-patcher audit-plugins [--json] [--quiet] [--no-progress] [--keep-open] [--include-native-open-probes]
+  codex-plus-patcher dev-sync [--source-home <path>] [--dev-home <path>] [--json]
+  codex-plus-patcher launch-dev --target <path> [--dev-home <path>] [--electron-user-data <path>] [--remote-debugging-port <port>] [--json]
   codex-plus-patcher menu-diagnostics --asar <path> [--json]
   codex-plus-patcher asar-list --asar <path> [--contains <text>] [--json]
   codex-plus-patcher asar-cat --asar <path> --file <asar-path> [--json]
@@ -69,6 +114,12 @@ function helpText() {
 Options:
   --source <path>          Source Codex.app. Default: /Applications/Codex.app
   --target <path>          Target Codex Plus.app. Default: ~/Applications/Codex Plus.app
+  --source-home <path>     Original Codex home for dev-sync. Default: ~/.codex
+  --dev-home <path>        Isolated CODEX_HOME for dev mode. Default: ./work/codex-plus-dev-home
+  --electron-user-data <path>
+                           Isolated Electron userData for launch-dev. Default: ./work/codex-plus-electron-user-data
+  --remote-debugging-port <port>
+                           Remote debugging port passed to launch-dev or audit-plugins
   --asar <path>            app.asar path for ASAR readback commands
   --file <asar-path>       Packed file path for asar-cat
   --contains <text>        Filter asar-list paths by substring
@@ -78,6 +129,13 @@ Options:
   --release-tag <tag>      Release mode tag. Default: latest
   --release-asset <name>   Release mode asset. Default: codex-plus-patches.tgz
   --dry-run                Select and report the patch without copying/signing
+  --no-apply               Reuse an existing audit target without applying patches
+  --no-launch              Attach to an existing audit app instead of launching
+  --keep-open              Leave the audit-launched app open after probes finish
+  --include-native-open-probes
+                           Also open DevTools and Mermaid viewer windows during audit probes
+  --no-progress            Suppress audit progress and print only the final summary
+  --quiet                  Print minimal audit output
   --debug                  Print stack traces for CLI errors
   --json                   Print the machine-readable result
 `;
@@ -327,6 +385,28 @@ async function main() {
     process.stdout.write(args.json ? `${JSON.stringify(result, null, 2)}\n` : formatMenuDiagnosticsResult(result));
     return;
   }
+  if (args.command === "dev-sync") {
+    const result = syncDevHome(args);
+    process.stdout.write(args.json ? `${JSON.stringify(result, null, 2)}\n` : formatSyncDevHomeResult(result));
+    return;
+  }
+  if (args.command === "launch-dev") {
+    const result = launchDevApp({
+      targetApp: args.target,
+      devHome: args.devHome,
+      electronUserDataPath: args.electronUserDataPath,
+      remoteDebuggingPort: args.remoteDebuggingPort,
+    });
+    process.stdout.write(args.json ? `${JSON.stringify(result, null, 2)}\n` : formatLaunchDevResult(result));
+    return;
+  }
+  if (args.command === "audit-plugins") {
+    const progress = await createAuditProgress(args);
+    const result = await runAudit(args, { progress });
+    process.stdout.write(args.json ? formatAuditJson(result) : formatAuditResult(result, args));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
   if (args.command !== "apply") throw new Error(`Unknown command: ${args.command}`);
 
   const patchSets = await loadPatchSets(args);
@@ -357,18 +437,26 @@ if (require.main === module) {
 
 module.exports = {
   createApplyProgress,
+  createAuditProgress,
   expandPath,
   formatAsarCatResult,
   formatAsarListResult,
+  formatAuditJson,
+  formatAuditResult,
   formatError,
+  formatLaunchDevResult,
   formatMenuDiagnosticsResult,
   formatResult,
+  formatSyncDevHomeResult,
   helpText,
   listAsarFiles,
   loadPatchSets,
+  launchDevApp,
   menuDiagnostics,
   parseArgs,
   readAsarFile,
   requirePatchSetModule,
+  runAudit,
   shouldShowApplyProgress,
+  syncDevHome,
 };

package/src/core/dev-mode.js

@@ -0,0 +1,274 @@
+const childProcess = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const { patchAsar } = require("./asar");
+const { setPlistBuddyValue } = require("./plist");
+
+const ASAR_PATH_IN_BUNDLE = "Contents/Resources/app.asar";
+const RUNTIME_MANIFEST_FILE = "webview/assets/codex-plus/runtime-manifest.js";
+const DEFAULT_DEV_HOME = path.resolve("work/codex-plus-dev-home");
+const DEFAULT_ELECTRON_USER_DATA = path.resolve("work/codex-plus-electron-user-data");
+const DEV_MODE_WARNING =
+  "Dev mode shares the original Codex worktrees. Use it for UI/plugin validation; do not edit the same checkout from regular Codex and Codex Plus at the same time.";
+
+const COPY_ENTRIES = [
+  "config.toml",
+  "auth.json",
+  ".codex-global-state.json",
+  "models_cache.json",
+  "version.json",
+  "installation_id",
+  "history.jsonl",
+  "session_index.jsonl",
+  "AGENTS.md",
+  "rules",
+  "skills",
+  "plugins",
+  "vendor_imports",
+  "chrome-native-hosts.json",
+  "chrome-native-hosts-v2.json",
+  "computer-use/config.json",
+];
+const SQLITE_SNAPSHOT_ENTRIES = ["state_5.sqlite", "sqlite/state_5.sqlite"];
+const EXCLUDED_DEV_STATE_ENTRIES = [
+  "sqlite",
+  "cache",
+  "log",
+  "tmp",
+  "process_manager",
+  "generated_images",
+  "attachments",
+  "shell_snapshots",
+];
+
+function isSqlitePath(filePath) {
+  const base = path.basename(filePath);
+  return base.includes(".sqlite") || base.endsWith(".sqlite-wal") || base.endsWith(".sqlite-shm");
+}
+
+function assertSafeDevHome(devHome, sourceHome) {
+  const resolvedDevHome = path.resolve(devHome);
+  const resolvedSourceHome = path.resolve(sourceHome);
+  if (resolvedDevHome === resolvedSourceHome) throw new Error("--dev-home must not be the same as --source-home");
+  if (resolvedDevHome === os.homedir() || resolvedDevHome === path.join(os.homedir(), ".codex")) {
+    throw new Error("--dev-home must not point at the user's real home or ~/.codex");
+  }
+}
+
+function copyEntry({ sourceHome, devHome, relativePath, fsImpl = fs }) {
+  const source = path.join(sourceHome, relativePath);
+  const target = path.join(devHome, relativePath);
+  if (!fsImpl.existsSync(source)) return null;
+  if (isSqlitePath(source) || relativePath.split(path.sep).includes("sqlite")) return null;
+  fsImpl.mkdirSync(path.dirname(target), { recursive: true });
+  fsImpl.rmSync(target, { recursive: true, force: true });
+  fsImpl.cpSync(source, target, { recursive: true, force: true, dereference: false });
+  return relativePath;
+}
+
+function scrubDevGlobalState(devHome, fsImpl = fs) {
+  const statePath = path.join(devHome, ".codex-global-state.json");
+  if (!fsImpl.existsSync(statePath)) return false;
+  const state = JSON.parse(fsImpl.readFileSync(statePath, "utf8"));
+  const atomState = state["electron-persisted-atom-state"];
+  if (atomState == null || typeof atomState !== "object") return false;
+  if (!Object.prototype.hasOwnProperty.call(atomState, "composer-prompt-drafts-v1")) return false;
+  delete atomState["composer-prompt-drafts-v1"];
+  fsImpl.writeFileSync(statePath, `${JSON.stringify(state)}\n`);
+  return true;
+}
+
+function cleanExcludedDevState(devHome, fsImpl = fs) {
+  for (const relativePath of EXCLUDED_DEV_STATE_ENTRIES) {
+    fsImpl.rmSync(path.join(devHome, relativePath), { recursive: true, force: true });
+  }
+  if (!fsImpl.existsSync(devHome)) return;
+  for (const entry of fsImpl.readdirSync(devHome)) {
+    if (isSqlitePath(entry) || entry.endsWith(".db")) {
+      fsImpl.rmSync(path.join(devHome, entry), { recursive: true, force: true });
+    }
+  }
+}
+
+function sqliteLiteral(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function snapshotSqlite({ sourceHome, devHome, relativePath, fsImpl = fs, execFileSync = childProcess.execFileSync }) {
+  const source = path.join(sourceHome, relativePath);
+  const target = path.join(devHome, relativePath);
+  if (!fsImpl.existsSync(source)) return null;
+  fsImpl.mkdirSync(path.dirname(target), { recursive: true });
+  fsImpl.rmSync(target, { force: true });
+  fsImpl.rmSync(`${target}-wal`, { force: true });
+  fsImpl.rmSync(`${target}-shm`, { force: true });
+  execFileSync("sqlite3", [source, `VACUUM INTO ${sqliteLiteral(target)}`], { stdio: "pipe" });
+  return relativePath;
+}
+
+function linkSharedDirectory({ sourceHome, devHome, relativePath, fsImpl = fs }) {
+  const source = path.join(sourceHome, relativePath);
+  const target = path.join(devHome, relativePath);
+  fsImpl.rmSync(target, { recursive: true, force: true });
+  if (!fsImpl.existsSync(source)) return null;
+  fsImpl.symlinkSync(source, target, "dir");
+  return { source, target };
+}
+
+function syncDevHome({
+  sourceHome = path.join(os.homedir(), ".codex"),
+  devHome = DEFAULT_DEV_HOME,
+  fsImpl = fs,
+  execFileSync = childProcess.execFileSync,
+} = {}) {
+  const resolvedSourceHome = path.resolve(sourceHome);
+  const resolvedDevHome = path.resolve(devHome);
+  assertSafeDevHome(resolvedDevHome, resolvedSourceHome);
+
+  fsImpl.mkdirSync(resolvedDevHome, { recursive: true });
+  cleanExcludedDevState(resolvedDevHome, fsImpl);
+
+  const copied = [];
+  for (const relativePath of COPY_ENTRIES) {
+    const copiedPath = copyEntry({
+      sourceHome: resolvedSourceHome,
+      devHome: resolvedDevHome,
+      relativePath,
+      fsImpl,
+    });
+    if (copiedPath) copied.push(copiedPath);
+  }
+  const scrubbedGlobalState = scrubDevGlobalState(resolvedDevHome, fsImpl);
+
+  const sqliteSnapshots = [];
+  for (const relativePath of SQLITE_SNAPSHOT_ENTRIES) {
+    const snapshotPath = snapshotSqlite({
+      sourceHome: resolvedSourceHome,
+      devHome: resolvedDevHome,
+      relativePath,
+      fsImpl,
+      execFileSync,
+    });
+    if (snapshotPath) sqliteSnapshots.push(snapshotPath);
+  }
+
+  const worktrees = linkSharedDirectory({
+    sourceHome: resolvedSourceHome,
+    devHome: resolvedDevHome,
+    relativePath: "worktrees",
+    fsImpl,
+  });
+  const sessions = linkSharedDirectory({
+    sourceHome: resolvedSourceHome,
+    devHome: resolvedDevHome,
+    relativePath: "sessions",
+    fsImpl,
+  });
+
+  return {
+    sourceHome: resolvedSourceHome,
+    devHome: resolvedDevHome,
+    copied,
+    scrubbedGlobalState,
+    sqliteSnapshots,
+    worktrees,
+    sessions,
+    warning: DEV_MODE_WARNING,
+  };
+}
+
+function buildLaunchDev({ targetApp, devHome = DEFAULT_DEV_HOME, electronUserDataPath = DEFAULT_ELECTRON_USER_DATA, remoteDebuggingPort } = {}) {
+  if (!targetApp) throw new Error("--target is required");
+  const appBinary = path.join(path.resolve(targetApp), "Contents/MacOS/Codex");
+  const resolvedDevHome = path.resolve(devHome);
+  const resolvedElectronUserDataPath = path.resolve(electronUserDataPath);
+  const args = [`--user-data-dir=${resolvedElectronUserDataPath}`];
+  if (remoteDebuggingPort != null) args.push(`--remote-debugging-port=${remoteDebuggingPort}`);
+  return {
+    command: appBinary,
+    args,
+    env: {
+      CODEX_HOME: resolvedDevHome,
+      CODEX_ELECTRON_USER_DATA_PATH: resolvedElectronUserDataPath,
+    },
+    warning: DEV_MODE_WARNING,
+  };
+}
+
+function markDevRuntimeConfig(targetApp, { patchAsarImpl = patchAsar, setPlistBuddyValueImpl = setPlistBuddyValue } = {}) {
+  const target = path.resolve(targetApp);
+  const asarPath = path.join(target, ASAR_PATH_IN_BUNDLE);
+  const patchedAsarSha = patchAsarImpl(asarPath, [
+    [RUNTIME_MANIFEST_FILE, (text) => {
+      const match = text.match(/^window\.__CodexPlusRuntimeConfig=({.*?});/);
+      if (!match) throw new Error("Could not find Codex Plus runtime config in runtime manifest");
+      const config = JSON.parse(match[1]);
+      config.devModeStatsigFallback = true;
+      return text.replace(match[0], `window.__CodexPlusRuntimeConfig=${JSON.stringify(config)};`);
+    }],
+  ]);
+  setPlistBuddyValueImpl(
+    path.join(target, "Contents/Info.plist"),
+    ":ElectronAsarIntegrity:Resources/app.asar:hash",
+    patchedAsarSha,
+  );
+  return { asar: asarPath, patchedAsarSha };
+}
+
+function launchDevApp({ spawn = childProcess.spawn, env = process.env, markDevRuntimeConfigImpl = markDevRuntimeConfig, ...options } = {}) {
+  const launch = buildLaunchDev(options);
+  fs.mkdirSync(launch.env.CODEX_HOME, { recursive: true });
+  fs.mkdirSync(launch.env.CODEX_ELECTRON_USER_DATA_PATH, { recursive: true });
+  const devRuntimeConfig = markDevRuntimeConfigImpl(options.targetApp);
+  const child = spawn(launch.command, launch.args, {
+    detached: true,
+    env: { ...env, ...launch.env },
+    stdio: "ignore",
+  });
+  child.unref();
+  return { ...launch, devRuntimeConfig, pid: child.pid };
+}
+
+function formatSyncDevHomeResult(result) {
+  const lines = [
+    "Codex Plus dev home synced.",
+    `Source home: ${result.sourceHome}`,
+    `Dev home: ${result.devHome}`,
+    `Copied: ${result.copied.length === 0 ? "(none)" : result.copied.join(", ")}`,
+    `Scrubbed writable state: ${result.scrubbedGlobalState ? "composer prompt drafts" : "(none)"}`,
+    `SQLite snapshots: ${result.sqliteSnapshots?.length ? result.sqliteSnapshots.join(", ") : "(none)"}`,
+    result.worktrees ? `Worktrees: ${result.worktrees.target} -> ${result.worktrees.source}` : "Worktrees: (missing)",
+    result.sessions ? `Sessions: ${result.sessions.target} -> ${result.sessions.source}` : "Sessions: (missing)",
+    `Warning: ${result.warning}`,
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+function formatLaunchDevResult(result) {
+  const lines = [
+    "Codex Plus dev app launched.",
+    `Command: ${result.command}`,
+    `Args: ${result.args.length === 0 ? "(none)" : result.args.join(" ")}`,
+    `CODEX_HOME: ${result.env.CODEX_HOME}`,
+    `CODEX_ELECTRON_USER_DATA_PATH: ${result.env.CODEX_ELECTRON_USER_DATA_PATH}`,
+  ];
+  if (result.pid != null) lines.push(`PID: ${result.pid}`);
+  lines.push(`Warning: ${result.warning}`);
+  return `${lines.join("\n")}\n`;
+}
+
+module.exports = {
+  COPY_ENTRIES,
+  DEFAULT_DEV_HOME,
+  DEFAULT_ELECTRON_USER_DATA,
+  DEV_MODE_WARNING,
+  SQLITE_SNAPSHOT_ENTRIES,
+  buildLaunchDev,
+  formatLaunchDevResult,
+  formatSyncDevHomeResult,
+  launchDevApp,
+  markDevRuntimeConfig,
+  syncDevHome,
+};