claude-dev-env 7.7.1 → 8.1.0

package/bin/install-pstack-plugin.mjs

@@ -0,0 +1,192 @@
+import { spawnSync } from 'node:child_process';
+
+export const PSTACK_MARKETPLACE_REPOSITORY = 'michael-denyer/pstack-claude';
+export const PSTACK_MARKETPLACE_NAME = 'pstack-claude';
+export const PSTACK_PLUGIN_IDENTIFIER = `pstack@${PSTACK_MARKETPLACE_NAME}`;
+export const PSTACK_PLUGIN_HOSTS = Object.freeze(['claude', 'codex']);
+
+export const PSTACK_PLUGIN_OPT_OUT_FLAG = '--no-pstack';
+export const PSTACK_PLUGIN_OPT_OUT_VARIABLE = 'CDE_INSTALL_PSTACK';
+
+const HOST_PLANS = Object.freeze({
+    claude: Object.freeze({
+        executable: 'claude',
+        executableVariable: 'CDE_CLAUDE_EXECUTABLE',
+        homeVariable: 'CLAUDE_CONFIG_DIR',
+        commands: Object.freeze([
+            Object.freeze(['plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY]),
+            Object.freeze(['plugin', 'install', PSTACK_PLUGIN_IDENTIFIER]),
+        ]),
+    }),
+    codex: Object.freeze({
+        executable: 'codex',
+        executableVariable: 'CDE_CODEX_EXECUTABLE',
+        homeVariable: 'CODEX_HOME',
+        commands: Object.freeze([
+            Object.freeze(['plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY]),
+            Object.freeze(['plugin', 'add', PSTACK_PLUGIN_IDENTIFIER]),
+        ]),
+    }),
+});
+
+/**
+ * Read the marketplace and plugin commands one host installs pstack with.
+ *
+ * Claude Code and Codex publish the same marketplace under different plugin
+ * verbs, so the command list belongs to the host rather than to the caller.
+ *
+ * @param {string} host Either `claude` or `codex`.
+ * @returns {{executable: string, executableVariable: string, homeVariable: string,
+ *   commands: ReadonlyArray<ReadonlyArray<string>>}} The host's install plan.
+ */
+export function pstackPluginPlan(host) {
+    const plan = HOST_PLANS[host];
+    if (!plan) {
+        throw new Error(
+            `Unsupported pstack plugin host ${host}: this installer knows ${PSTACK_PLUGIN_HOSTS.join(', ')}.`,
+        );
+    }
+    return plan;
+}
+
+/**
+ * Decide whether a full install also installs the pstack plugin.
+ *
+ * The step reaches the network for the marketplace repository. `--no-pstack`
+ * on the command line, or `CDE_INSTALL_PSTACK=0` in the environment, turns it
+ * off for an air-gapped or offline run.
+ *
+ * @param {string[]} [argumentList] The command-line arguments after the script.
+ * @param {Record<string, string|undefined>} [environment] The process environment.
+ * @returns {boolean} True when this run installs the pstack plugin.
+ */
+export function shouldInstallPstackPlugin(
+    argumentList = process.argv.slice(2),
+    environment = process.env,
+) {
+    if (argumentList.includes(PSTACK_PLUGIN_OPT_OUT_FLAG)) return false;
+    return environment[PSTACK_PLUGIN_OPT_OUT_VARIABLE] !== '0';
+}
+
+/**
+ * Build the process launch one platform needs to run a host command.
+ *
+ * Both hosts ship on Windows as a `.cmd` shim, and Node's synchronous spawn
+ * rejects a batch file with `EINVAL` unless a shell runs it, so Windows goes
+ * through `cmd.exe /d /s /c` with the whole command line as one verbatim
+ * argument. The executable carries its own quotes inside that line, which is
+ * why the line is passed verbatim rather than quoted again by Node. Every
+ * other platform launches the executable directly.
+ *
+ * @param {string} executable The host command, a bare name or a path.
+ * @param {string[]} commandArguments The arguments after the executable.
+ * @param {string} [platform] The platform to build for.
+ * @param {Record<string, string|undefined>} [environment] Supplies `ComSpec`.
+ * @returns {{file: string, args: string[], windowsVerbatimArguments: boolean}} The launch.
+ */
+export function hostCommandInvocation(
+    executable,
+    commandArguments,
+    platform = process.platform,
+    environment = process.env,
+) {
+    if (platform !== 'win32') {
+        return { file: executable, args: [...commandArguments], windowsVerbatimArguments: false };
+    }
+    const commandLine = [`"${executable}"`, ...commandArguments].join(' ');
+    return {
+        file: environment.ComSpec || 'cmd.exe',
+        args: ['/d', '/s', '/c', `"${commandLine}"`],
+        windowsVerbatimArguments: true,
+    };
+}
+
+function runHostCommand(executable, commandArguments, options) {
+    const invocation = hostCommandInvocation(executable, commandArguments);
+    const spawned = spawnSync(invocation.file, invocation.args, {
+        encoding: 'utf8',
+        env: { ...process.env, ...options.environment },
+        windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+    });
+    return { status: spawned.status, stderr: spawned.stderr ?? '', error: spawned.error };
+}
+
+const COMMAND_NOT_FOUND_EXIT_CODE = 9009;
+const COMMAND_NOT_FOUND_PATTERN = /is not recognized as an internal or external command/;
+
+function namesAnAbsentCommand(outcome) {
+    if (outcome.error?.code === 'ENOENT') return true;
+    return outcome.status === COMMAND_NOT_FOUND_EXIT_CODE
+        && COMMAND_NOT_FOUND_PATTERN.test(outcome.stderr ?? '');
+}
+
+function firstLine(text) {
+    const trimmed = (text ?? '').trim();
+    if (!trimmed) return '';
+    return trimmed.split(/\r?\n/).filter(Boolean).at(-1);
+}
+
+function installForHost(host, homeDirectory, environment, runCommand) {
+    const plan = pstackPluginPlan(host);
+    const executable = environment[plan.executableVariable] || plan.executable;
+    const commandEnvironment = { [plan.homeVariable]: homeDirectory };
+    for (const commandArguments of plan.commands) {
+        const outcome = runCommand(executable, [...commandArguments], {
+            environment: commandEnvironment,
+        });
+        if (namesAnAbsentCommand(outcome)) {
+            return {
+                host,
+                executable,
+                status: 'skipped',
+                warning: `${executable} is not on PATH, so pstack was not installed for ${host}.`,
+            };
+        }
+        if (outcome.status !== 0 || outcome.error) {
+            const detail = firstLine(outcome.stderr) || outcome.error?.message || `exit ${outcome.status}`;
+            return {
+                host,
+                executable,
+                status: 'failed',
+                warning: `${executable} ${commandArguments.join(' ')} failed: ${detail}`,
+            };
+        }
+    }
+    return { host, executable, status: 'installed', warning: null };
+}
+
+/**
+ * Install the pstack plugin from its marketplace into each host's own home.
+ *
+ * Each host is one member of the batch. A host without its command-line tool
+ * is skipped and a host whose command fails is reported, so the rules, hooks,
+ * and skills this run already wrote still reach their durable places. An
+ * absent tool arrives as a spawn `ENOENT` on other platforms and as
+ * `cmd.exe`'s command-not-found exit code on Windows, and both read as
+ * skipped.
+ *
+ * @param {object} [options] Install targets.
+ * @param {string} [options.claudeRoot] The managed Claude root to install into.
+ * @param {string} [options.codexHome] The Codex home to install into.
+ * @param {string[]} [options.hosts] The hosts to install. Defaults to both.
+ * @param {Record<string, string|undefined>} [options.environment] The process environment.
+ * @param {object} [dependencies] Seams for the command runner.
+ * @returns {{status: string, hosts: object[], warning: string|null}} The outcome per host.
+ */
+export function installPstackPlugin(options = {}, dependencies = {}) {
+    const environment = options.environment ?? process.env;
+    const runCommand = dependencies.runCommand ?? runHostCommand;
+    const homeDirectories = { claude: options.claudeRoot, codex: options.codexHome };
+    const hosts = options.hosts ?? PSTACK_PLUGIN_HOSTS;
+    const hostOutcomes = hosts.map(host => installForHost(
+        host,
+        homeDirectories[host],
+        environment,
+        runCommand,
+    ));
+    const failedCount = hostOutcomes.filter(outcome => outcome.status === 'failed').length;
+    const installedCount = hostOutcomes.filter(outcome => outcome.status === 'installed').length;
+    const status = failedCount > 0 ? 'failed' : (installedCount > 0 ? 'installed' : 'skipped');
+    const warnings = hostOutcomes.map(outcome => outcome.warning).filter(Boolean);
+    return { status, hosts: hostOutcomes, warning: warnings.join(' ') || null };
+}

package/bin/install-pstack-plugin.test.mjs

@@ -0,0 +1,181 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import {
+    PSTACK_MARKETPLACE_REPOSITORY,
+    PSTACK_PLUGIN_HOSTS,
+    PSTACK_PLUGIN_IDENTIFIER,
+    hostCommandInvocation,
+    installPstackPlugin,
+    pstackPluginPlan,
+    shouldInstallPstackPlugin,
+} from './install-pstack-plugin.mjs';
+
+function recordingRunner(outcomeForCommand = () => ({ status: 0, stderr: '' })) {
+    const calls = [];
+    return {
+        calls,
+        runCommand(executable, commandArguments, options) {
+            calls.push({ executable, commandArguments, environment: options.environment });
+            return outcomeForCommand(executable, commandArguments);
+        },
+    };
+}
+
+const ROOTS = Object.freeze({
+    claudeRoot: '/managed/.claude',
+    codexHome: '/managed/.codex',
+    environment: {},
+});
+
+const WINDOWS_ENVIRONMENT = Object.freeze({ ComSpec: 'C:\\Windows\\system32\\cmd.exe' });
+
+test('the Claude plan carries the two documented plugin commands', () => {
+    const plan = pstackPluginPlan('claude');
+    assert.equal(plan.executable, 'claude');
+    assert.deepEqual(plan.commands, [
+        ['plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY],
+        ['plugin', 'install', PSTACK_PLUGIN_IDENTIFIER],
+    ]);
+});
+
+test('the Codex plan adds the plugin with the Codex verb', () => {
+    const plan = pstackPluginPlan('codex');
+    assert.equal(plan.executable, 'codex');
+    assert.deepEqual(plan.commands, [
+        ['plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY],
+        ['plugin', 'add', PSTACK_PLUGIN_IDENTIFIER],
+    ]);
+});
+
+test('an unsupported host names the hosts this installer knows', () => {
+    assert.throws(() => pstackPluginPlan('cursor'), /cursor/);
+    assert.deepEqual(PSTACK_PLUGIN_HOSTS, ['claude', 'codex']);
+});
+
+test('each host installs into the managed root this run wrote', () => {
+    const runner = recordingRunner();
+    const outcome = installPstackPlugin(ROOTS, runner);
+    assert.equal(outcome.status, 'installed');
+    assert.deepEqual(runner.calls.map(call => [call.executable, ...call.commandArguments]), [
+        ['claude', 'plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY],
+        ['claude', 'plugin', 'install', PSTACK_PLUGIN_IDENTIFIER],
+        ['codex', 'plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY],
+        ['codex', 'plugin', 'add', PSTACK_PLUGIN_IDENTIFIER],
+    ]);
+    assert.equal(runner.calls[0].environment.CLAUDE_CONFIG_DIR, ROOTS.claudeRoot);
+    assert.equal(runner.calls[2].environment.CODEX_HOME, ROOTS.codexHome);
+});
+
+test('an absent host command skips that host and leaves the other installed', () => {
+    const runner = recordingRunner((executable) => (executable === 'codex'
+        ? { status: null, error: Object.assign(new Error('spawn codex ENOENT'), { code: 'ENOENT' }) }
+        : { status: 0, stderr: '' }));
+    const outcome = installPstackPlugin(ROOTS, runner);
+    assert.equal(outcome.hosts.find(host => host.host === 'claude').status, 'installed');
+    const codex = outcome.hosts.find(host => host.host === 'codex');
+    assert.equal(codex.status, 'skipped');
+    assert.match(codex.warning, /codex/);
+    assert.equal(runner.calls.filter(call => call.executable === 'codex').length, 1);
+});
+
+test('a failing command reports that host and still installs the next one', () => {
+    const runner = recordingRunner((executable, commandArguments) => (
+        executable === 'claude' && commandArguments[1] === 'marketplace'
+            ? { status: 1, stderr: 'marketplace unreachable' }
+            : { status: 0, stderr: '' }));
+    const outcome = installPstackPlugin(ROOTS, runner);
+    assert.equal(outcome.status, 'failed');
+    const claude = outcome.hosts.find(host => host.host === 'claude');
+    assert.equal(claude.status, 'failed');
+    assert.match(claude.warning, /marketplace unreachable/);
+    assert.equal(outcome.hosts.find(host => host.host === 'codex').status, 'installed');
+    assert.equal(runner.calls.filter(call => call.executable === 'claude').length, 1);
+});
+
+test('an executable override replaces the host command for that host only', () => {
+    const runner = recordingRunner();
+    installPstackPlugin(
+        { ...ROOTS, environment: { CDE_CODEX_EXECUTABLE: '/opt/codex/bin/codex' } },
+        runner,
+    );
+    assert.deepEqual([...new Set(runner.calls.map(call => call.executable))], [
+        'claude',
+        '/opt/codex/bin/codex',
+    ]);
+});
+
+test('the opt-out flag and variable both turn the step off', () => {
+    assert.equal(shouldInstallPstackPlugin([], {}), true);
+    assert.equal(shouldInstallPstackPlugin(['--no-pstack'], {}), false);
+    assert.equal(shouldInstallPstackPlugin([], { CDE_INSTALL_PSTACK: '0' }), false);
+    assert.equal(shouldInstallPstackPlugin([], { CDE_INSTALL_PSTACK: '1' }), true);
+});
+
+test('a selected host list installs only that host', () => {
+    const runner = recordingRunner();
+    const outcome = installPstackPlugin({ ...ROOTS, hosts: ['codex'] }, runner);
+    assert.deepEqual(outcome.hosts.map(host => host.host), ['codex']);
+    assert.deepEqual([...new Set(runner.calls.map(call => call.executable))], ['codex']);
+});
+
+test('a non-Windows platform launches the host command directly', () => {
+    const invocation = hostCommandInvocation('claude', ['plugin', 'install', PSTACK_PLUGIN_IDENTIFIER], 'linux');
+    assert.deepEqual(invocation, {
+        file: 'claude',
+        args: ['plugin', 'install', PSTACK_PLUGIN_IDENTIFIER],
+        windowsVerbatimArguments: false,
+    });
+});
+
+test('Windows launches the host command through cmd.exe, which alone can run a .cmd shim', () => {
+    const invocation = hostCommandInvocation(
+        'claude', ['plugin', 'install', PSTACK_PLUGIN_IDENTIFIER], 'win32', WINDOWS_ENVIRONMENT,
+    );
+    assert.equal(invocation.file, WINDOWS_ENVIRONMENT.ComSpec);
+    assert.deepEqual(invocation.args, [
+        '/d',
+        '/s',
+        '/c',
+        `""claude" plugin install ${PSTACK_PLUGIN_IDENTIFIER}"`,
+    ]);
+    assert.equal(invocation.windowsVerbatimArguments, true);
+});
+
+test('a Windows executable path holding a space stays one quoted token', () => {
+    const invocation = hostCommandInvocation(
+        'C:\\Program Files\\nodejs\\claude.cmd',
+        ['plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY],
+        'win32',
+        WINDOWS_ENVIRONMENT,
+    );
+    assert.equal(
+        invocation.args.at(-1),
+        `""C:\\Program Files\\nodejs\\claude.cmd" plugin marketplace add ${PSTACK_MARKETPLACE_REPOSITORY}"`,
+    );
+});
+
+test('a Windows environment without ComSpec falls back to the bare shell name', () => {
+    const invocation = hostCommandInvocation('claude', ['plugin'], 'win32', {});
+    assert.equal(invocation.file, 'cmd.exe');
+});
+
+test("cmd.exe's command-not-found exit code reads as an absent host, not a failure", () => {
+    const runner = recordingRunner((executable) => (executable === 'codex'
+        ? {
+            status: 9009,
+            stderr: "'codex' is not recognized as an internal or external command,\noperable program or batch file.",
+        }
+        : { status: 0, stderr: '' }));
+    const outcome = installPstackPlugin(ROOTS, runner);
+    const codex = outcome.hosts.find(host => host.host === 'codex');
+    assert.equal(codex.status, 'skipped');
+    assert.equal(outcome.status, 'installed');
+    assert.equal(runner.calls.filter(call => call.executable === 'codex').length, 1);
+});
+
+test('a non-zero exit that is not command-not-found still reads as a failure', () => {
+    const runner = recordingRunner(() => ({ status: 9009, stderr: 'the marketplace rejected the catalog' }));
+    const outcome = installPstackPlugin({ ...ROOTS, hosts: ['claude'] }, runner);
+    assert.equal(outcome.hosts[0].status, 'failed');
+    assert.match(outcome.hosts[0].warning, /rejected the catalog/);
+});

package/bin/install.agents-home.test.mjs

@@ -53,10 +53,6 @@ const CLEAN_CODER_POLICY_REFERENCES = [
         '<managed-root>/rules/code-standards.md',
         'packages/claude-dev-env/rules/code-standards.md',
     ],
-    [
-        '<managed-root>/rules/file-global-constants.md',
-        'packages/claude-dev-env/rules/file-global-constants.md',
-    ],
     [
         '<managed-root>/rules/windows-filesystem-safe.md',
         'packages/claude-dev-env/rules/windows-filesystem-safe.md',

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

@@ -118,6 +118,11 @@ test('resolveInstallRoot names ~/.codex/rules and allows files under it', () =>
     });
     const expectedDirectory = join(homeDirectory, DEFAULT_CODEX_DIRECTORY_NAME, CODEX_RULES_DIRECTORY_NAME);
     assert.equal(resolution.codexRulesInstallDirectory, expectedDirectory);
+    assert.equal(
+        resolution.codexHomeDirectory,
+        join(homeDirectory, DEFAULT_CODEX_DIRECTORY_NAME),
+        'the pstack plugin step installs into this Codex home',
+    );
     assert.equal(
         isAllowedInstallDestination(join(expectedDirectory, CODEX_RULES_SHIPPED_FILE_NAME), resolution),
         true,
@@ -140,6 +145,7 @@ test('CODEX_HOME relocates the Codex rules destination', () => {
         resolution.codexRulesInstallDirectory,
         join(relocatedHome, CODEX_RULES_DIRECTORY_NAME),
     );
+    assert.equal(resolution.codexHomeDirectory, relocatedHome);
 });
 
 test('a full install copies shipped Codex rules and leaves a local default.rules in place', () => {