codex-plus-patcher 0.2.1 → 0.3.0

package/README.md

@@ -21,7 +21,8 @@
 
 Codex Plus is an experimental local demonstrator for changes that can be layered onto an installed Codex desktop app without redistributing the app itself. The patcher is meant for technically curious users who want to inspect, test, or iterate on small binary patch sets against their own local copy.
 
-The current built-in patches:
+The current built-in Codex Plus features are delivered by versioned ASAR
+patches plus readable runtime plugins:
 
 - rename the copied app and add patch provenance to the About dialog
 - expose nested repositories in the Review pane
@@ -30,11 +31,21 @@ The current built-in patches:
 - add adaptive project colors for sidebar projects, grouped threads, pinned threads, user-message accents, and the composer
 - add the `Toggle sidebar blur` command palette entry to blur sidebar chat and project names for the current session
 
+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.
+
 ## How It Works
 
 The patcher reads the installed `Codex.app`, verifies the exact Codex version, bundle version, and original `Contents/Resources/app.asar` SHA-256, then selects the matching patch queue. Unsupported app versions fail closed so a patch written for one bundle is not applied to a different bundle by accident.
 
-When applying patches, the tool copies `Codex.app` to the target `Codex Plus.app`, rewrites selected packed ASAR files with ordered text transforms, updates bundle metadata such as the app name and identifier, refreshes Electron ASAR integrity metadata, and signs the copied app ad hoc. The source app is not modified.
+When applying patches, the tool copies `Codex.app` to the target `Codex Plus.app`, rewrites selected packed ASAR files with ordered text transforms, adds Codex Plus runtime/plugin assets, updates bundle metadata such as the app name and identifier, refreshes Electron ASAR integrity metadata, and signs the copied app ad hoc. The source app is not modified.
+
+The patch transforms should stay small where possible: their job is increasingly
+to add reusable plugin interfaces and hook those interfaces into Codex core
+surfaces, while feature behavior lives in readable runtime/plugin files.
 
 ## Disclaimer
 
@@ -115,6 +126,8 @@ Patch queues export `patchSets` from `index.js`. Each patch set declares:
 - an ordered `patches` array with stable patch IDs
 - optional bundle metadata updates for the copied app
 - ordered file transforms applied to packed ASAR files
+- optional `assetFiles` entries added to the packed ASAR, used for runtime code,
+  built-in plugins, and plugin interface assets
 
 Unsupported app versions fail closed.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plus-patcher",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "private": false,
   "description": "Patch queue tool for building a local Codex Plus.app from an installed Codex.app.",
   "repository": {
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "check": "node --check src/cli.js && node --check src/core/asar.js && node --check src/core/patch-engine.js && node --check src/core/plist.js && node --check src/core/release.js && node --check src/patches/index.js && node --check src/patches/26.616.41845-4198.js && node --check src/patches/26.616.51431-4212.js && node --check src/patches/26.616.71553-4265.js && node --check src/plus/repositories.js"
+    "check": "node scripts/check-syntax.js"
   },
   "engines": {
     "node": ">=20"

package/src/cli.js

@@ -2,6 +2,7 @@
 const os = require("node:os");
 const path = require("node:path");
 
+const { readAsar, walkFiles } = require("./core/asar");
 const { patchCodexApp } = require("./core/patch-engine");
 const { resolveReleasePatchDirectory } = require("./core/release");
 const { patchSets: builtInPatchSets } = require("./patches");
@@ -35,6 +36,9 @@ 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 === "--asar") args.asar = path.resolve(expandPath(next()));
+    else if (arg === "--file") args.file = next();
+    else if (arg === "--contains") args.contains = next();
     else if (arg === "--mode") args.mode = next();
     else if (arg === "--patch-dir") args.patchDir = path.resolve(expandPath(next()));
     else if (arg === "--github-repo") args.githubRepo = next();
@@ -58,10 +62,15 @@ function helpText() {
   return `Usage:
   codex-plus-patcher
   codex-plus-patcher apply [options]
+  codex-plus-patcher asar-list --asar <path> [--contains <text>] [--json]
+  codex-plus-patcher asar-cat --asar <path> --file <asar-path> [--json]
 
 Options:
   --source <path>          Source Codex.app. Default: /Applications/Codex.app
   --target <path>          Target Codex Plus.app. Default: ~/Applications/Codex Plus.app
+  --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
   --mode <builtin|dev|release>
   --patch-dir <path>       Dev mode patch directory containing index.js
   --github-repo <owner/repo>
@@ -125,6 +134,36 @@ function formatResult(result) {
   return `${lines.join("\n")}\n`;
 }
 
+function listAsarFiles({ asar, contains }) {
+  if (!asar) throw new Error("--asar is required");
+  const archive = readAsar(asar);
+  const files = walkFiles(archive.header)
+    .map(([file]) => file)
+    .filter((file) => contains == null || file.includes(contains));
+  return { asar, files };
+}
+
+function readAsarFile({ asar, file }) {
+  if (!asar) throw new Error("--asar is required");
+  if (!file) throw new Error("--file is required");
+  const archive = readAsar(asar);
+  const node = new Map(walkFiles(archive.header)).get(file);
+  if (!node) throw new Error(`Could not find ${file} in ${asar}`);
+  if (node.unpacked) throw new Error(`Cannot read unpacked ASAR file ${file} from ${asar}`);
+  const size = Number(node.size || 0);
+  const start = archive.dataStart + Number(node.offset || 0);
+  const content = archive.buffer.subarray(start, start + size).toString("utf8");
+  return { asar, file, size, content };
+}
+
+function formatAsarListResult(result) {
+  return result.files.length > 0 ? `${result.files.join("\n")}\n` : "";
+}
+
+function formatAsarCatResult(result) {
+  return result.content;
+}
+
 function formatError(error, { debug = false } = {}) {
   if (debug || process.env.CODEX_PLUS_PATCHER_DEBUG === "1") return error.stack || error.message || String(error);
   return `Error: ${error.message || String(error)}`;
@@ -183,6 +222,16 @@ async function main() {
     printHelp();
     return;
   }
+  if (args.command === "asar-list") {
+    const result = listAsarFiles(args);
+    process.stdout.write(args.json ? `${JSON.stringify(result, null, 2)}\n` : formatAsarListResult(result));
+    return;
+  }
+  if (args.command === "asar-cat") {
+    const result = readAsarFile(args);
+    process.stdout.write(args.json ? `${JSON.stringify(result, null, 2)}\n` : formatAsarCatResult(result));
+    return;
+  }
   if (args.command !== "apply") throw new Error(`Unknown command: ${args.command}`);
 
   const patchSets = await loadPatchSets(args);
@@ -214,11 +263,15 @@ if (require.main === module) {
 module.exports = {
   createApplyProgress,
   expandPath,
+  formatAsarCatResult,
+  formatAsarListResult,
   formatError,
   formatResult,
   helpText,
+  listAsarFiles,
   loadPatchSets,
   parseArgs,
+  readAsarFile,
   requirePatchSetModule,
   shouldShowApplyProgress,
 };

package/src/core/asar.js

@@ -26,6 +26,26 @@ function walkFiles(node, prefix = "", out = []) {
   return out;
 }
 
+function ensureFileEntry(header, filePath) {
+  const parts = filePath.split("/").filter(Boolean);
+  if (parts.length === 0) throw new Error("Cannot add an empty ASAR path");
+
+  let node = header;
+  for (const part of parts.slice(0, -1)) {
+    node.files ||= {};
+    node.files[part] ||= { files: {} };
+    if (!node.files[part].files) throw new Error(`Cannot add ${filePath}: ${part} is already a file`);
+    node = node.files[part];
+  }
+
+  node.files ||= {};
+  const fileName = parts.at(-1);
+  const existing = node.files[fileName];
+  if (existing?.files) throw new Error(`Cannot add ${filePath}: path is already a directory`);
+  node.files[fileName] = existing || {};
+  return node.files[fileName];
+}
+
 function fileIntegrity(buffer) {
   const blockSize = 4 * 1024 * 1024;
   const blocks = [];
@@ -42,6 +62,9 @@ function fileIntegrity(buffer) {
 
 function patchAsar(asarPath, fileTransforms, transformContext = {}) {
   const archive = readAsar(asarPath);
+  const assetFiles = transformContext.assetFiles || [];
+  for (const [filePath] of assetFiles) ensureFileEntry(archive.header, filePath);
+
   const entries = walkFiles(archive.header);
   const contents = new Map();
 
@@ -58,6 +81,11 @@ function patchAsar(asarPath, fileTransforms, transformContext = {}) {
     contents.set(filePath, Buffer.from(patched, "utf8"));
   }
 
+  for (const [filePath, content] of assetFiles) {
+    if (!contents.has(filePath)) throw new Error(`Could not add ${filePath} to app.asar`);
+    contents.set(filePath, Buffer.isBuffer(content) ? content : Buffer.from(String(content), "utf8"));
+  }
+
   let dataOffset = 0;
   const dataBuffers = [];
   for (const [filePath, node] of entries) {
@@ -82,6 +110,7 @@ function patchAsar(asarPath, fileTransforms, transformContext = {}) {
 }
 
 module.exports = {
+  ensureFileEntry,
   patchAsar,
   readAsar,
   sha256,

package/src/core/patch-engine.js

@@ -89,6 +89,13 @@ function collectFileTransforms(patchSet) {
   return collectPatchQueue(patchSet).flatMap((patch) => patch.fileTransforms || []);
 }
 
+function collectAssetFiles(patchSet) {
+  return [
+    ...(patchSet.assetFiles || []),
+    ...collectPatchQueue(patchSet).flatMap((patch) => patch.assetFiles || []),
+  ];
+}
+
 function collectInfoPlistStrings(patchSet) {
   return Object.assign(
     {},
@@ -139,6 +146,7 @@ async function applyPatchSet({
   const setPlistBuddyStringValue = operations.setPlistBuddyValue || setPlistBuddyValue;
   const patchQueue = collectPatchQueue(patchSet);
   const fileTransforms = collectFileTransforms(patchSet);
+  const assetFiles = collectAssetFiles(patchSet);
   if (dryRun) {
     return {
       sourceApp,
@@ -146,6 +154,7 @@ async function applyPatchSet({
       patchSet: patchSet.id,
       patches: patchQueue.map((patch) => patch.id),
       patchedFiles: fileTransforms.map(([filePath]) => filePath),
+      addedFiles: assetFiles.map(([filePath]) => filePath),
       dryRun: true,
     };
   }
@@ -162,7 +171,7 @@ async function applyPatchSet({
   const targetAsar = path.join(targetApp, ASAR_PATH_IN_BUNDLE);
   const patchContext = buildPatchContext(patchSet, patchQueue, operations);
   const patchedAsarSha = await withProgress(progress, progressOffset + 3, progressTotal, "Patch app.asar", () =>
-    patchAsarFile(targetAsar, fileTransforms, patchContext),
+    patchAsarFile(targetAsar, fileTransforms, { ...patchContext, assetFiles }),
   );
 
   const plistPath = path.join(targetApp, "Contents/Info.plist");
@@ -185,6 +194,7 @@ async function applyPatchSet({
     patchSet: patchSet.id,
     patches: patchQueue.map((patch) => patch.id),
     patchedFiles: fileTransforms.map(([filePath]) => filePath),
+    addedFiles: assetFiles.map(([filePath]) => filePath),
     patchedAsarSha,
     dryRun: false,
   };
@@ -210,6 +220,7 @@ module.exports = {
   ASAR_PATH_IN_BUNDLE,
   applyPatchSet,
   collectFileTransforms,
+  collectAssetFiles,
   collectInfoPlistStrings,
   collectPatchQueue,
   getPatcherGitSha,