claude-dev-env 2.14.1 → 2.15.1

package/_shared/advisor/scripts/tier_model_ids.py

@@ -30,8 +30,12 @@ from collections.abc import Mapping
 from pathlib import Path
 
 _config_directory = str(Path(__file__).resolve().parent / "config")
-if _config_directory not in sys.path:
-    sys.path.insert(0, _config_directory)
+sys.path[:] = [
+    each_existing_entry
+    for each_existing_entry in sys.path
+    if each_existing_entry != _config_directory
+]
+sys.path[:0] = [_config_directory]
 
 from advisor_scripts_constants.model_tier_run_validator_constants import (  # noqa: E402
     ALL_CLI_MODEL_ID_BY_TIER,

package/bin/AGENTS.md

@@ -1,20 +1,22 @@
 # bin
 
-The installer and its companion modules. Running `npx claude-dev-env` (or `node bin/install.mjs`) copies package files into the managed root (`~/.claude/` by default; `CLAUDE_CONFIG_DIR` or `--target` selects another), merges hook entries into that root's `settings.json`, installs Git hooks, and writes `~/.mypy.ini` under the process home.
+The installer and its companion modules. Running `npx claude-dev-env` (or `node bin/install.mjs`) copies package files into the managed root (`~/.claude/` by default; `CLAUDE_CONFIG_DIR` or `--target` selects another), merges hook entries into that root's `settings.json`, installs Git hooks, writes `~/.mypy.ini` under the process home, and copies Codex exec-policy files into `~/.codex/rules` (`CODEX_HOME/rules` when that variable is set), and generates Cursor `.mdc` files into `~/.cursor/rules` from the installed Claude rules.
 
 ## Files
 
 | File | Purpose |
 |---|---|
 | `install.mjs` | Main installer: builds a read-only plan via `install-plan.mjs`, then runs mutations inside `install-transaction.mjs` recovery (copy content directories, merge hooks, install skills, prune, git hooks, mypy.ini); routes `CLAUDE_HOME`, the manifest path, and `~/.mypy.ini` through `resolve-install-root.mjs`; resolves single or multi-profile targets before mutation and writes one ownership manifest per target |
-| `resolve-install-root.mjs` | Pure install-root resolver: precedence `--target` > `CLAUDE_CONFIG_DIR` > `~/.claude`, separator-boundary containment, and the declared external allowlist for `~/.mypy.ini` |
+| `resolve-install-root.mjs` | Pure install-root resolver: precedence `--target` > `CLAUDE_CONFIG_DIR` > `~/.claude`, separator-boundary containment, and the declared external allowlist for `~/.mypy.ini` plus files under the Codex rules directory and the Cursor home |
 | `select-install-targets.mjs` | Pure target selection for main-default, explicit `--target`, and `--profile`/`--profiles`; rejects ambiguous or duplicate targets; builds per-target manifest records with `targetIdentity` and `managedRoot` |
 | `install-plan.mjs` | Read-only install and uninstall plans: install preflight (managed root, source conflicts, Python, settings when hooks install) and uninstall preflight (settings JSON before removal, removable vs skipped manifest records), freezes plans E2/F execute |
 | `install-transaction.mjs` | Install, update, and uninstall transaction journal: captures prior settings, manifest, managed files, and `core.hooksPath`, restores them on failure, and supports fault injection phases for recovery tests |
 | `install.transaction.test.mjs` | Unit and sandbox installer tests for snapshot/restore and fault phases (`after_file_staging`, `after_settings_write`, `after_git_config`, `after_manifest_write`) |
 | `install.uninstall-transaction.test.mjs` | Uninstall plan preflight and recovery: malformed/non-object settings fail before removal, each fault phase restores files/settings/manifest/`core.hooksPath`, retry succeeds, selected-root containment |
 | `install.profile-root.test.mjs` | Contract tests for the install-root resolver: precedence, containment boundary, external allowlist, and the install.mjs import smoke check |
-| `install-constants.mjs` | The named values `install.mjs` reads: `SKIPPED_SOURCE_ENTRY_NAMES` and `SKIPPED_SOURCE_FILE_EXTENSIONS` for the build artifacts the source walk leaves behind, `RUN_BACKUP_DIRECTORY_NAME_PATTERN` for the timestamp shape a run backup directory carries, `MANAGED_SKILLS_DIRECTORY_NAME` and `MANAGED_HOOKS_DIRECTORY_NAME` for the directory name each of those trees carries in a package source and under `~/.claude` — read by the copy loops, the hooks.json reads, the git-hook shims, the mypy configuration, and the prunes alike — `SETTINGS_FILE_NAME` for the settings file the merge, the retired-hook prune, and the uninstall purge share, and `MYPY_INI_FILE_NAME` for the home-directory file `install_mypy_ini.mjs` writes (also imported by `resolve-install-root.mjs`) |
+| `install.codex-rules.test.mjs` | Tests that Codex exec-policy files copy to `~/.codex/rules`, honor `CODEX_HOME`, skip `--only journal`, and uninstall without touching `default.rules` |
+| `install.cursor-rules.test.mjs` | Tests that Cursor `.mdc` files generate into `~/.cursor/rules` from Claude rules, skip `--only journal`, and leave a local extra `.mdc` in place |
+| `install-constants.mjs` | The named values `install.mjs` reads: `SKIPPED_SOURCE_ENTRY_NAMES` and `SKIPPED_SOURCE_FILE_EXTENSIONS` for the build artifacts the source walk leaves behind, `RUN_BACKUP_DIRECTORY_NAME_PATTERN` for the timestamp shape a run backup directory carries, `MANAGED_SKILLS_DIRECTORY_NAME` and `MANAGED_HOOKS_DIRECTORY_NAME` for the directory name each of those trees carries in a package source and under `~/.claude` — read by the copy loops, the hooks.json reads, the git-hook shims, the mypy configuration, and the prunes alike — `SETTINGS_FILE_NAME` for the settings file the merge, the retired-hook prune, and the uninstall purge share, and `MYPY_INI_FILE_NAME` for the home-directory file `install_mypy_ini.mjs` writes, plus the Codex home and rules directory names `resolve-install-root.mjs` uses |
 | `ever-shipped-skills.mjs` | Static `EVER_SHIPPED_SKILL_NAMES` set of every top-level skill directory name the package has shipped; the installer subtracts the current skill set from it to prune retired skills left under `~/.claude/skills` |
 | `expand_home_directory_tokens.mjs` | Expands residual `$HOME` / `${HOME}` / `~/` tokens in settings.json hook and statusLine commands to absolute home paths at install time (literal-safe for homes that contain `$`) |
 | `git_hooks_installer.mjs` | Installs or updates the `pre-commit`, `pre-push`, and `post-commit` Git hooks in the user's git config; writes hook scripts that delegate to the installed Python hooks |
@@ -78,7 +80,7 @@ A run that moves nothing sweeps nothing, so every recovery point the user holds
 
 `--uninstall` builds a read-only uninstall plan, captures a recovery snapshot, then removes each file the plan lists.
 
-Settings JSON is validated before any removal. A malformed or non-object `settings.json` fails closed with the managed files still on disk. Each manifest record passes a containment guard: the path resolves under `~/.claude`, or it names the `~/.mypy.ini` the install writes in the home directory. Every other record is skipped with a warning and counted. Skipping keeps one malformed record — hand-edited, or written by an installer that ran against a different home — from stranding the user with a half-removed install. The purge removes every legitimate record, clears the manifest, and reports the skipped count.
+Settings JSON is validated before any removal. A malformed or non-object `settings.json` fails closed with the managed files still on disk. Each manifest record passes a containment guard: the path resolves under `~/.claude`, or it names the `~/.mypy.ini` the install writes in the home directory, or it sits under the Codex rules directory. Every other record is skipped with a warning and counted. Skipping keeps one malformed record — hand-edited, or written by an installer that ran against a different home — from stranding the user with a half-removed install. The purge removes every legitimate record, clears the manifest, and reports the skipped count.
 
 The uninstall runs inside the same snapshot/restore journal as install: prior settings, manifest, managed files, and `core.hooksPath` restore when a later phase fails, so a retry starts from a complete ownership record. The journal is discarded only after a successful commit.
 

package/bin/install-constants.mjs

@@ -85,3 +85,54 @@ export const SETTINGS_FILE_NAME = 'settings.json';
  * removes the file the install created.
  */
 export const MYPY_INI_FILE_NAME = '.mypy.ini';
+
+/**
+ * Environment variable Codex uses for its config home. When unset, Codex reads
+ * `~/.codex`. The installer copies shipped exec-policy files into
+ * `<that home>/rules`.
+ */
+export const CODEX_HOME_ENVIRONMENT_VARIABLE = 'CODEX_HOME';
+
+/**
+ * Directory name Codex uses under the user home when `CODEX_HOME` is unset.
+ */
+export const DEFAULT_CODEX_DIRECTORY_NAME = '.codex';
+
+/**
+ * Directory name under the Codex home that holds `*.rules` exec-policy files.
+ * Codex loads every file in that directory; see `load_exec_policy` in Codex.
+ */
+export const CODEX_RULES_DIRECTORY_NAME = 'rules';
+
+/**
+ * Package subdirectory that holds the shipped Codex exec-policy files. The
+ * installer copies this tree into the Codex rules directory, not into
+ * `~/.claude/`.
+ */
+export const CODEX_RULES_PACKAGE_DIRECTORY_NAME = 'codex-rules';
+
+/**
+ * Shipped exec-policy file name. A distinct name keeps a local `default.rules`
+ * file in place.
+ */
+export const CODEX_RULES_SHIPPED_FILE_NAME = 'claude-dev-env.rules';
+
+/**
+ * Directory name Cursor uses under the user home for editor config.
+ */
+export const DEFAULT_CURSOR_DIRECTORY_NAME = '.cursor';
+
+/**
+ * Directory name under the Cursor home that holds generated `.mdc` rule files.
+ */
+export const CURSOR_RULES_DIRECTORY_NAME = 'rules';
+
+/**
+ * Installed script that writes Cursor `.mdc` files from Claude rules.
+ */
+export const CURSOR_SYNC_SCRIPT_FILE_NAME = 'sync_to_cursor.py';
+
+/**
+ * Windows Python launcher command the installer may bake into hook settings.
+ */
+export const WINDOWS_PYTHON_LAUNCHER_COMMAND = 'py -3';

package/bin/install.codex-rules.test.mjs

@@ -0,0 +1,173 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import {
+    mkdtempSync,
+    mkdirSync,
+    writeFileSync,
+    readFileSync,
+    existsSync,
+    rmSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+    resolveInstallRoot,
+    isAllowedInstallDestination,
+} from './resolve-install-root.mjs';
+import {
+    CODEX_HOME_ENVIRONMENT_VARIABLE,
+    CODEX_RULES_DIRECTORY_NAME,
+    CODEX_RULES_PACKAGE_DIRECTORY_NAME,
+    CODEX_RULES_SHIPPED_FILE_NAME,
+    DEFAULT_CODEX_DIRECTORY_NAME,
+} from './install-constants.mjs';
+import { CONTENT_DIRECTORIES, INSTALL_GROUPS } from './install.mjs';
+
+const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const INSTALLER_PATH = join(THIS_DIRECTORY, 'install.mjs');
+const PACKAGE_DIRECTORY = dirname(THIS_DIRECTORY);
+const SHIPPED_RULES_SOURCE_PATH = join(
+    PACKAGE_DIRECTORY,
+    CODEX_RULES_PACKAGE_DIRECTORY_NAME,
+    CODEX_RULES_SHIPPED_FILE_NAME,
+);
+
+function runInstaller(homeDirectory, extraArguments) {
+    return execFileSync('node', [INSTALLER_PATH, ...extraArguments], {
+        cwd: PACKAGE_DIRECTORY,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+            [CODEX_HOME_ENVIRONMENT_VARIABLE]: join(homeDirectory, DEFAULT_CODEX_DIRECTORY_NAME),
+        },
+    });
+}
+
+test('CONTENT_DIRECTORIES omits codex-rules because that tree installs to the Codex home', () => {
+    assert.equal(CONTENT_DIRECTORIES.includes(CODEX_RULES_PACKAGE_DIRECTORY_NAME), false);
+});
+
+test('the core group installs Codex exec-policy files', () => {
+    assert.equal(INSTALL_GROUPS.core.includeCodexRules, true);
+});
+
+test('resolveInstallRoot names ~/.codex/rules and allows files under it', () => {
+    const homeDirectory = join(tmpdir(), 'cdev-codex-rules-home');
+    const resolution = resolveInstallRoot({
+        homeDirectory,
+        environment: {},
+        explicitTarget: null,
+    });
+    const expectedDirectory = join(homeDirectory, DEFAULT_CODEX_DIRECTORY_NAME, CODEX_RULES_DIRECTORY_NAME);
+    assert.equal(resolution.codexRulesInstallDirectory, expectedDirectory);
+    assert.equal(
+        isAllowedInstallDestination(join(expectedDirectory, CODEX_RULES_SHIPPED_FILE_NAME), resolution),
+        true,
+    );
+    assert.equal(
+        isAllowedInstallDestination(join(homeDirectory, '.ssh', 'id_rsa'), resolution),
+        false,
+    );
+});
+
+test('CODEX_HOME relocates the Codex rules destination', () => {
+    const homeDirectory = join(tmpdir(), 'cdev-codex-home-default');
+    const relocatedHome = join(tmpdir(), 'cdev-codex-home-relocated');
+    const resolution = resolveInstallRoot({
+        homeDirectory,
+        environment: { [CODEX_HOME_ENVIRONMENT_VARIABLE]: relocatedHome },
+        explicitTarget: null,
+    });
+    assert.equal(
+        resolution.codexRulesInstallDirectory,
+        join(relocatedHome, CODEX_RULES_DIRECTORY_NAME),
+    );
+});
+
+test('a full install copies shipped Codex rules and leaves a local default.rules in place', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-codex-install-'));
+    try {
+        const userRulesPath = join(
+            homeDirectory,
+            DEFAULT_CODEX_DIRECTORY_NAME,
+            CODEX_RULES_DIRECTORY_NAME,
+            'default.rules',
+        );
+        mkdirSync(dirname(userRulesPath), { recursive: true });
+        writeFileSync(userRulesPath, 'prefix_rule(pattern=["echo", "hi"], decision="allow")\n');
+
+        runInstaller(homeDirectory, []);
+
+        const installedRulesPath = join(
+            homeDirectory,
+            DEFAULT_CODEX_DIRECTORY_NAME,
+            CODEX_RULES_DIRECTORY_NAME,
+            CODEX_RULES_SHIPPED_FILE_NAME,
+        );
+        assert.equal(existsSync(installedRulesPath), true);
+        assert.equal(
+            readFileSync(installedRulesPath, 'utf8'),
+            readFileSync(SHIPPED_RULES_SOURCE_PATH, 'utf8'),
+        );
+        assert.equal(
+            readFileSync(userRulesPath, 'utf8'),
+            'prefix_rule(pattern=["echo", "hi"], decision="allow")\n',
+        );
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a full install Codex rules file contains no personal home path', () => {
+    const shippedText = readFileSync(SHIPPED_RULES_SOURCE_PATH, 'utf8');
+    assert.equal(shippedText.includes('Users\\jon'), false);
+    assert.equal(shippedText.includes('Users/jon'), false);
+    assert.equal(shippedText.includes('JonEcho'), false);
+});
+
+test('--only journal skips Codex rules; --only core copies them', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-codex-groups-'));
+    try {
+        const installedRulesPath = join(
+            homeDirectory,
+            DEFAULT_CODEX_DIRECTORY_NAME,
+            CODEX_RULES_DIRECTORY_NAME,
+            CODEX_RULES_SHIPPED_FILE_NAME,
+        );
+        runInstaller(homeDirectory, ['--only', 'journal']);
+        assert.equal(existsSync(installedRulesPath), false);
+
+        runInstaller(homeDirectory, ['--only', 'core']);
+        assert.equal(existsSync(installedRulesPath), true);
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('uninstall removes the shipped Codex rules file and leaves default.rules', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-codex-uninstall-'));
+    try {
+        const rulesDirectory = join(
+            homeDirectory,
+            DEFAULT_CODEX_DIRECTORY_NAME,
+            CODEX_RULES_DIRECTORY_NAME,
+        );
+        const userRulesPath = join(rulesDirectory, 'default.rules');
+        mkdirSync(rulesDirectory, { recursive: true });
+        writeFileSync(userRulesPath, 'keep-me\n');
+
+        runInstaller(homeDirectory, []);
+        runInstaller(homeDirectory, ['--uninstall']);
+
+        const installedRulesPath = join(rulesDirectory, CODEX_RULES_SHIPPED_FILE_NAME);
+        assert.equal(existsSync(installedRulesPath), false);
+        assert.equal(readFileSync(userRulesPath, 'utf8'), 'keep-me\n');
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});

package/bin/install.cursor-rules.test.mjs

@@ -0,0 +1,103 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import {
+    resolveInstallRoot,
+    isAllowedInstallDestination,
+} from './resolve-install-root.mjs';
+import {
+    DEFAULT_CURSOR_DIRECTORY_NAME,
+    CURSOR_RULES_DIRECTORY_NAME,
+} from './install-constants.mjs';
+
+const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const INSTALLER_PATH = join(THIS_DIRECTORY, 'install.mjs');
+const PACKAGE_DIRECTORY = dirname(THIS_DIRECTORY);
+
+function runInstaller(homeDirectory, extraArguments) {
+    return execFileSync('node', [INSTALLER_PATH, ...extraArguments], {
+        cwd: PACKAGE_DIRECTORY,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+        },
+    });
+}
+
+test('resolveInstallRoot names ~/.cursor/rules and allows generated mdc files under it', () => {
+    const homeDirectory = join(tmpdir(), 'cdev-cursor-rules-home');
+    const resolution = resolveInstallRoot({
+        homeDirectory,
+        environment: {},
+        explicitTarget: null,
+    });
+    const expectedDirectory = join(
+        homeDirectory,
+        DEFAULT_CURSOR_DIRECTORY_NAME,
+        CURSOR_RULES_DIRECTORY_NAME,
+    );
+    assert.equal(resolution.cursorRulesInstallDirectory, expectedDirectory);
+    assert.equal(
+        isAllowedInstallDestination(join(expectedDirectory, 'plain-language.mdc'), resolution),
+        true,
+    );
+    assert.equal(
+        isAllowedInstallDestination(join(homeDirectory, '.ssh', 'id_rsa'), resolution),
+        false,
+    );
+});
+
+test('a full install writes stem-named Cursor rules and leaves a local extra mdc in place', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-cursor-install-'));
+    try {
+        const extraRulePath = join(
+            homeDirectory,
+            DEFAULT_CURSOR_DIRECTORY_NAME,
+            CURSOR_RULES_DIRECTORY_NAME,
+            'user-local.mdc',
+        );
+        mkdirSync(dirname(extraRulePath), { recursive: true });
+        writeFileSync(extraRulePath, 'keep-me\n');
+
+        runInstaller(homeDirectory, []);
+
+        const generatedPath = join(
+            homeDirectory,
+            DEFAULT_CURSOR_DIRECTORY_NAME,
+            CURSOR_RULES_DIRECTORY_NAME,
+            'plain-language.mdc',
+        );
+        assert.equal(existsSync(generatedPath), true);
+        const generatedText = readFileSync(generatedPath, 'utf8');
+        assert.equal(generatedText.includes('alwaysApply: true'), true);
+        assert.equal(readFileSync(extraRulePath, 'utf8'), 'keep-me\n');
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('--only journal skips Cursor rule generation; --only core writes them', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-cursor-groups-'));
+    try {
+        const generatedPath = join(
+            homeDirectory,
+            DEFAULT_CURSOR_DIRECTORY_NAME,
+            CURSOR_RULES_DIRECTORY_NAME,
+            'plain-language.mdc',
+        );
+        runInstaller(homeDirectory, ['--only', 'journal']);
+        assert.equal(existsSync(generatedPath), false);
+
+        runInstaller(homeDirectory, ['--only', 'core']);
+        assert.equal(existsSync(generatedPath), true);
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});