decode-codex Documentation

Pages

1. OverviewWhat decode-codex exposes: two agent skills (codex-app-ref-refresh and deobfuscate-javascript), the ./ref and ./restored artifact roots, runtime prerequisites, and the shortest end-to-end path from installed Codex.app to readable source.
2. InstallationPrerequisites and first-time setup: macOS Codex.app at /Applications/Codex.app, Node.js for asar extraction, Bun for deobfuscation scripts, and bun install inside the deobfuscate-javascript skill directory.
3. QuickstartFirst successful run: refresh ./ref from Codex.app, invoke deobfuscate-javascript on ref/webview/assets, and verify formatted output under restored/ with expected log lines and directory layout.
4. Restoration pipelineStage 1 deobfuscation, Stage 2 rename and polish, and Stage 3 semantic finalize; readable vs deep depth; whole-tree vs single-file scope; and the restoration contract that defines done.
5. Workspace and output conventionsPer-chunk staging under restored/.deobfuscate-javascript/, the promote bar for deliverables, semantic-domain subfolders, kebab-case filenames, provenance headers, and the shared restored/IMPORT_MAP.json contract.
6. Import graph and boundariesmanifest.json and ledger.json orchestration, terminal chunk kinds (npm-leaf, oversized-local, external, faced-boundary), facade lifecycle, and quality-gate coverage rules for whole-tree restores.
7. Codex project profileLayout of the extracted openai-codex-electron bundle: ref/webview/index.html entry discovery, ref/webview/assets chunk root, npm-leaf and Pierre vendor boundaries, and default deep-restore command frame for this repository.
8. Refresh Codex reference sourceRun codex-app-ref-refresh to delete and recreate ./ref from Codex.app Contents/Resources/app.asar, format extracted JS/CSS with Prettier, and verify completion signals before deobfuscation.
9. Deobfuscate a single fileReadable-tier workflow for lone minified snippets or isolated chunks: sourcemap-check, wakaru-normalize, extract, smart-rename, polish --fast, format, and promote a single deliverable without import-graph orchestration.
10. Full tree restorationDeep default workflow for index.html plus asset trees: entry discovery, build-import-graph, build-symbol-ledger, auto-restore-full checkpoints, plan-organize, promote-organized, and quality-gate over the whole target.
11. Handle obfuscated inputStage 1 workflow for packed, encoded, or Obfuscator.IO input: detect, unpack, string-array, decode-strings, simplify, control-flow-report, and critical ordering before Stage 2 rename.
12. Delta restore and resumeContinue an in-progress restoration: inspect manifest.json, ledger.json, and IMPORT_MAP.json; run delta/boundary replacement for a scoped chunk; and avoid rebuilding the whole reachable graph.
13. Refresh script referencerefresh-codex-ref.mjs flags (--dry-run, --skip-format), CODEX_APP_ASAR override, safety guards on ./ref replacement, Prettier verification passes, and expected stdout completion lines.
14. Stage 1 scripts referenceCLI signatures and behavior for detect, unpack, string-array, decode-strings, simplify, control-flow-report, and the deobfuscate.ts orchestrator with --skip and --stop-after controls.
15. Stage 2 scripts referenceRename and polish script reference: sourcemap-check, wakaru-normalize, extract filters, smart-rename, apply, polish flags (--rename, --fast, --format), and deep-mode import-resolution passes.
16. Orchestration scripts referenceFull-restoration CLI reference: check-entry exit codes, build-import-graph flags, ledger subcommands, auto-restore-full, plan-organize, promote-organized, quality-gate checks, and semantic-finalize recipes.
17. External tools and dependenciesBun and Babel package dependencies, subprocess tools (@electron/asar, prettier, @wakaru/cli, webcrack, source-map-explorer), BSD-style script exit codes, and graceful degradation when binaries are absent.
18. Quality bar and anti-patternsReadable and deep-tier completion criteria, naming anti-patterns (program-scope-only rename, mechanical fallback names, checkpoint promotion), Stage 3 acceptance categories E1–E4, and quality-gate failure modes.
19. Pipeline caveatsOrdering rules, eval safety in unpack, sourcemap precedence, polish tier differences, Prettier gitignore traps, wakaru caveats, vendor-leaf entry misidentification, and other documented failure modes with recovery steps.
20. Maintaining the skillSelf-improvement protocol for deobfuscate-javascript: when to update CHUNK_NAME_REGISTRY, fix scripts with tests, append caveats or codex-ref notes, commit discipline, and legal constraints on extracted Codex source.