claude-dev-env 2.4.0 → 2.7.0

package/bin/codex-compat.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const materializerPath = path.join(packageRoot, "scripts", "codex_compat_materializer.py");
+const bridgePath = path.join(packageRoot, "scripts", "codex_capability_bridge.py");
+const pythonNames = process.platform === "win32" ? ["py", "python"] : ["python3", "python"];
+
+export function createHelpText() {
+    return [
+        "Usage: codex-compat <command> [options]",
+        "",
+        "Commands:",
+        "  materialize  Plan or apply Claude agents into an explicit Codex root",
+        "  bridge       Translate a Claude capability request to a declarative record",
+        "",
+        "Materialize options:",
+        "  --source-root <path>  Claude source root (required)",
+        "  --target-root <path>  Codex target root (required)",
+        "  --apply               Write changes; default is dry-run",
+        "  --allow-prune-all     Permit an empty plan to delete every managed file",
+        "  --python <command>    Python interpreter override",
+        "",
+        "Bridge options:",
+        "  --surface <name>      Capability surface (required)",
+        "  --payload <json>      JSON object payload (required)",
+        "  --python <command>    Python interpreter override",
+        "",
+        "Python may also be selected with CODEX_COMPAT_PYTHON. Roots are never inferred or written automatically.",
+    ].join("\n");
+}
+
+function readOption(argumentsList, optionName) {
+    const optionIndex = argumentsList.indexOf(optionName);
+    if (optionIndex < 0) return undefined;
+    return argumentsList[optionIndex + 1];
+}
+
+function requireOption(argumentsList, optionName) {
+    const optionValue = readOption(argumentsList, optionName);
+    if (!optionValue || optionValue.startsWith("--")) throw new Error(`Missing required option: ${optionName}`);
+    return optionValue;
+}
+
+function writeErrorRecord(errorCode, errorMessage) {
+    process.stderr.write(`${JSON.stringify({ error: { code: errorCode, message: errorMessage } })}\n`);
+}
+
+export function buildCommand(commandName, argumentsList, interpreter) {
+    if (commandName === "materialize") {
+        const sourceRoot = requireOption(argumentsList, "--source-root");
+        const targetRoot = requireOption(argumentsList, "--target-root");
+        const materializerArguments = [materializerPath, sourceRoot, targetRoot];
+        if (argumentsList.includes("--apply")) materializerArguments.push("--apply");
+        if (argumentsList.includes("--allow-prune-all")) materializerArguments.push("--allow-prune-all");
+        return { executable: interpreter, arguments: materializerArguments };
+    }
+    if (commandName === "bridge") {
+        const surface = requireOption(argumentsList, "--surface");
+        const payload = requireOption(argumentsList, "--payload");
+        return { executable: interpreter, arguments: [bridgePath, surface, payload] };
+    }
+    throw new Error(`Unknown command: ${commandName}`);
+}
+
+export function findPython(commandNames = pythonNames, canRun = (command) => spawnSync(command, ["--version"], { stdio: "ignore" }).status === 0) {
+    for (const eachCommand of commandNames) {
+        if (canRun(eachCommand)) return eachCommand;
+    }
+    return undefined;
+}
+
+export function runCommand(command, runChild = spawn) {
+    return new Promise((resolve) => {
+        const childProcess = runChild(command.executable, command.arguments, { stdio: "inherit" });
+        childProcess.on("close", (exitCode, signal) => resolve(exitCode ?? 1 + (signal ? 1 : 0)));
+        childProcess.on("error", () => resolve(1));
+    });
+}
+
+export async function main(argumentsList = process.argv.slice(2), dependencies = {}) {
+    if (argumentsList.length === 0 || argumentsList.includes("--help") || argumentsList.includes("-h")) {
+        process.stdout.write(`${createHelpText()}\n`);
+        return 0;
+    }
+    const [commandName, ...commandArguments] = argumentsList;
+    try {
+        const interpreter = readOption(commandArguments, "--python") ?? process.env.CODEX_COMPAT_PYTHON ?? await (dependencies.findPython ?? findPython)();
+        if (!interpreter) {
+            writeErrorRecord("python_unavailable", "No usable Python interpreter found. Use --python or CODEX_COMPAT_PYTHON.");
+            return 1;
+        }
+        const command = buildCommand(commandName, commandArguments, interpreter);
+        return await (dependencies.runCommand ?? runCommand)(command, dependencies.runChild);
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "Unknown compatibility command error";
+        writeErrorRecord("invalid_command", errorMessage);
+        return 2;
+    }
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) process.exitCode = await main();

package/bin/codex-compat.test.mjs

@@ -0,0 +1,51 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildCommand, createHelpText, main } from "./codex-compat.mjs";
+
+test("help describes both compatibility commands", () => {
+    assert.match(createHelpText(), /materialize/);
+    assert.match(createHelpText(), /bridge/);
+});
+
+test("missing required arguments returns a usage error", async () => {
+    const messages = [];
+    const originalWrite = process.stderr.write;
+    process.stderr.write = (message) => messages.push(message);
+    try { assert.equal(await main(["materialize"], { findPython: async () => "python" }), 2); } finally { process.stderr.write = originalWrite; }
+    assert.equal(JSON.parse(messages.join("")).error.code, "invalid_command");
+    assert.match(messages.join(""), /--source-root/);
+});
+
+test("unknown command returns structured error without running a child", async () => {
+    const messages = [];
+    let wasRun = false;
+    const originalWrite = process.stderr.write;
+    process.stderr.write = (message) => messages.push(message);
+    try {
+        const exitCode = await main(["unknown"], {
+            findPython: async () => "python",
+            runCommand: async () => { wasRun = true; return 0; },
+        });
+        assert.equal(exitCode, 2);
+    } finally { process.stderr.write = originalWrite; }
+    assert.equal(JSON.parse(messages.join("")).error.code, "invalid_command");
+    assert.equal(wasRun, false);
+});
+
+test("commands use safe argv and forward dry-run and apply", () => {
+    const dryRun = buildCommand("materialize", ["--source-root", "source root", "--target-root", "target;root"], "python");
+    const apply = buildCommand("materialize", ["--source-root", "source", "--target-root", "target", "--apply"], "python");
+    assert.equal(dryRun.arguments.at(-1), "target;root");
+    assert.equal(apply.arguments.at(-1), "--apply");
+});
+
+test("bridge forwarding and child status use injected runners", async () => {
+    let receivedCommand;
+    const exitCode = await main(["bridge", "--surface", "TaskCreate", "--payload", '{"name":"ship","status":"pending"}'], {
+        findPython: async () => "python-test",
+        runCommand: async (command) => { receivedCommand = command; return 7; },
+    });
+    assert.equal(exitCode, 7);
+    assert.equal(receivedCommand.executable, "python-test");
+    assert.equal(receivedCommand.arguments.at(-1), '{"name":"ship","status":"pending"}');
+});

package/bin/ever-shipped-skills.mjs

@@ -39,6 +39,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'grok-spawn',
     'grokify',
     'implement',
+    'issue-tracker',
     'log-audit',
     'logifix',
     'monitor-open-prs',

package/bin/install-constants.mjs

@@ -0,0 +1,88 @@
+/**
+ * Named values the installer reads, kept out of the code that uses them.
+ *
+ * `install.mjs` holds the install pipeline; the tables below hold the data that
+ * pipeline compares against, so a value has one home and one spelling.
+ */
+
+/**
+ * Entry names the source walk leaves behind, whatever directory they sit in.
+ *
+ * Each name belongs to a tool that writes beside the source it reads: Python
+ * bytecode caches, the ruff, pytest, and mypy caches, an installed
+ * `node_modules` tree, and the macOS Finder's `.DS_Store` marker. A contributor
+ * who runs the test suites and then runs `node bin/install.mjs` copies from a
+ * source tree carrying all of them, so skipping the names at the walk keeps them
+ * out of `~/.claude` and out of the install manifest.
+ */
+export const SKIPPED_SOURCE_ENTRY_NAMES = new Set([
+    '__pycache__',
+    '.ruff_cache',
+    '.pytest_cache',
+    '.mypy_cache',
+    'node_modules',
+    '.DS_Store',
+]);
+
+/**
+ * File extensions the source walk leaves behind, compared in lower case.
+ *
+ * Python writes a `.pyc` beside a module inside `__pycache__` and a `.pyo` under
+ * an optimized run, and either can land outside a cache directory, so the
+ * extension check stands alongside the name check.
+ */
+export const SKIPPED_SOURCE_FILE_EXTENSIONS = new Set(['.pyc', '.pyo']);
+
+/**
+ * The name shape a run backup directory carries under
+ * `~/.claude/.claude-dev-env-pruned/`.
+ *
+ * The installer names each run backup from an ISO timestamp with every `:` and
+ * `.` rewritten as `-`, for example `2026-07-25T18-04-11-923Z`. The retention
+ * sweep removes only a direct child matching this shape, so a directory any
+ * other tool or person left in the backup directory stays where it is.
+ */
+export const RUN_BACKUP_DIRECTORY_NAME_PATTERN =
+    /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z$/;
+
+/**
+ * The directory name skill directories carry in a package source and under
+ * `~/.claude`.
+ *
+ * The copy loop reads `<package-root>/skills` and writes `~/.claude/skills`, the
+ * dependency walk reads `<dependency-root>/skills`, the retired-skill prune reads
+ * the installed directory, and the per-root stale-file prune names it as one of
+ * its roots. One spelling serves every one of them, so the copy destination and
+ * the prune target stay the same directory.
+ */
+export const MANAGED_SKILLS_DIRECTORY_NAME = 'skills';
+
+/**
+ * The directory name hook scripts carry in a package source and under
+ * `~/.claude`.
+ *
+ * The copy loop reads `<package-root>/hooks` and writes `~/.claude/hooks`, the
+ * hooks.json reads sit under the same name in each package source, the git-hook
+ * shims and the mypy configuration point at the installed directory, the
+ * retired-hook diff takes its relative paths against it, and the per-root
+ * stale-file prune names it as one of its roots.
+ */
+export const MANAGED_HOOKS_DIRECTORY_NAME = 'hooks';
+
+/**
+ * The `~/.claude` file name that holds the user's harness settings.
+ *
+ * The hook merge writes it, the retired-hook prune rewrites it, and the uninstall
+ * purge rewrites it, so all three reach the file through one name.
+ */
+export const SETTINGS_FILE_NAME = 'settings.json';
+
+/**
+ * The home-directory file name `install_mypy_ini.mjs` writes.
+ *
+ * mypy reads its configuration from the home directory, so this is the one file
+ * the installer writes outside `~/.claude`. The install records the path and the
+ * uninstall containment guard names it as a permitted location, so `--uninstall`
+ * removes the file the install created.
+ */
+export const MYPY_INI_FILE_NAME = '.mypy.ini';