claude-dev-env 8.42.6 → 8.43.1

package/bin/install-pstack-plugin.mjs

@@ -1,6 +1,8 @@
 import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
 
-export const PSTACK_MARKETPLACE_REPOSITORY = 'michael-denyer/pstack-claude';
+export const PSTACK_MARKETPLACE_REPOSITORY = 'jl-cmd/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']);
@@ -12,6 +14,7 @@ export const PSTACK_PLUGIN_SPEC = Object.freeze({
     name: 'pstack',
     label: 'Pstack',
     marketplaceRepository: PSTACK_MARKETPLACE_REPOSITORY,
+    marketplaceName: PSTACK_MARKETPLACE_NAME,
     marketplaceAddArguments: Object.freeze([]),
     pluginIdentifier: PSTACK_PLUGIN_IDENTIFIER,
     hosts: PSTACK_PLUGIN_HOSTS,
@@ -23,6 +26,7 @@ export const USAGE_WRAPUP_PLUGIN_SPEC = Object.freeze({
     name: 'usage-wrapup',
     label: 'Usage-wrapup',
     marketplaceRepository: 'jl-cmd/claude-dev-env',
+    marketplaceName: 'claude-dev-env',
     marketplaceAddArguments: Object.freeze(['--sparse', '.claude-plugin']),
     pluginIdentifier: 'usage-wrapup@claude-dev-env',
     hosts: Object.freeze(['claude']),
@@ -35,19 +39,28 @@ const HOST_DEFINITIONS = Object.freeze({
         executable: 'claude',
         executableVariable: 'CDE_CLAUDE_EXECUTABLE',
         homeVariable: 'CLAUDE_CONFIG_DIR',
+        orphanedVersionsDirectory: (homeDirectory, spec) => join(
+            homeDirectory, 'plugins', 'cache', spec.marketplaceName, spec.name,
+        ),
         installVerb: 'install',
+        uninstallVerb: 'uninstall',
     }),
     codex: Object.freeze({
         executable: 'codex',
         executableVariable: 'CDE_CODEX_EXECUTABLE',
         homeVariable: 'CODEX_HOME',
         installVerb: 'add',
+        uninstallVerb: 'remove',
     }),
 });
 
 /**
  * Read the marketplace and plugin commands one host installs a plugin with.
  *
+ * The removal commands run first and take out the installed plugin, its
+ * cached versions, and the marketplace clone, so the install commands that
+ * follow fetch the newest published version into an empty slot.
+ *
  * Claude Code and Codex publish a marketplace under different plugin verbs, so
  * the install verb belongs to the host and the marketplace and identifier
  * belong to the plugin spec. A spec whose marketplace is a large repository
@@ -57,6 +70,7 @@ const HOST_DEFINITIONS = Object.freeze({
  * @param {typeof PSTACK_PLUGIN_SPEC} spec The plugin to install.
  * @param {string} host A host the spec names, `claude` or `codex`.
  * @returns {{executable: string, executableVariable: string, homeVariable: string,
+ *   removalCommands: ReadonlyArray<ReadonlyArray<string>>,
  *   commands: ReadonlyArray<ReadonlyArray<string>>}} The host's install plan.
  */
 export function marketplacePluginPlan(spec, host) {
@@ -70,6 +84,10 @@ export function marketplacePluginPlan(spec, host) {
         executable: hostDefinition.executable,
         executableVariable: hostDefinition.executableVariable,
         homeVariable: hostDefinition.homeVariable,
+        removalCommands: [
+            ['plugin', hostDefinition.uninstallVerb, spec.pluginIdentifier],
+            ['plugin', 'marketplace', 'remove', spec.marketplaceName],
+        ],
         commands: [
             ['plugin', 'marketplace', 'add', spec.marketplaceRepository, ...spec.marketplaceAddArguments],
             ['plugin', hostDefinition.installVerb, spec.pluginIdentifier],
@@ -156,22 +174,54 @@ function firstLine(text) {
     return trimmed.split(/\r?\n/).filter(Boolean).at(-1);
 }
 
+const ORPHANED_VERSION_MARKER = '.orphaned_at';
+
+/**
+ * Delete each cached plugin version the host marked as orphaned.
+ *
+ * Claude Code keeps an uninstalled version in its plugin cache with an
+ * `.orphaned_at` marker, so the clean install deletes those versions and
+ * leaves the version it just installed.
+ *
+ * @param {string|undefined} versionsDirectory The plugin's cache directory.
+ * @returns {string[]} The version directories removed.
+ */
+export function removeOrphanedPluginVersions(versionsDirectory) {
+    if (!versionsDirectory || !existsSync(versionsDirectory)) return [];
+    const removedPaths = [];
+    for (const versionName of readdirSync(versionsDirectory)) {
+        const versionPath = join(versionsDirectory, versionName);
+        if (!existsSync(join(versionPath, ORPHANED_VERSION_MARKER))) continue;
+        rmSync(versionPath, { recursive: true, force: true });
+        removedPaths.push(versionPath);
+    }
+    return removedPaths;
+}
+
+function absentHostOutcome(spec, host, executable) {
+    return {
+        host,
+        executable,
+        status: 'skipped',
+        warning: `${executable} is not on PATH, so ${spec.name} was not installed for ${host}.`,
+    };
+}
+
 function installForHost(spec, host, homeDirectory, environment, runCommand) {
     const plan = marketplacePluginPlan(spec, host);
     const executable = environment[plan.executableVariable] || plan.executable;
     const commandEnvironment = { [plan.homeVariable]: homeDirectory };
+    for (const commandArguments of plan.removalCommands) {
+        const outcome = runCommand(executable, [...commandArguments], {
+            environment: commandEnvironment,
+        });
+        if (namesAnAbsentCommand(outcome)) return absentHostOutcome(spec, host, executable);
+    }
     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 ${spec.name} was not installed for ${host}.`,
-            };
-        }
+        if (namesAnAbsentCommand(outcome)) return absentHostOutcome(spec, host, executable);
         if (outcome.status !== 0 || outcome.error) {
             const detail = firstLine(outcome.stderr) || outcome.error?.message || `exit ${outcome.status}`;
             return {
@@ -182,12 +232,20 @@ function installForHost(spec, host, homeDirectory, environment, runCommand) {
             };
         }
     }
+    const hostDefinition = HOST_DEFINITIONS[host];
+    if (hostDefinition.orphanedVersionsDirectory && homeDirectory) {
+        removeOrphanedPluginVersions(hostDefinition.orphanedVersionsDirectory(homeDirectory, spec));
+    }
     return { host, executable, status: 'installed', warning: null };
 }
 
 /**
  * Install one plugin from its marketplace into each host's own home.
  *
+ * Each host first removes the plugin and its marketplace, so an older
+ * version never survives beside the new one. A removal that finds nothing
+ * to remove exits non-zero on a fresh home, and the install goes on.
+ *
  * 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

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

@@ -1,6 +1,8 @@
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
-import { readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import {
     PSTACK_MARKETPLACE_REPOSITORY,
     PSTACK_PLUGIN_HOSTS,
@@ -10,6 +12,7 @@ import {
     hostCommandInvocation,
     installMarketplacePlugin,
     marketplacePluginPlan,
+    removeOrphanedPluginVersions,
     shouldInstallMarketplacePlugin,
 } from './install-pstack-plugin.mjs';
 
@@ -60,13 +63,38 @@ test('each host installs into the managed root this run wrote', () => {
     const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, ROOTS, runner);
     assert.equal(outcome.status, 'installed');
     assert.deepEqual(runner.calls.map(call => [call.executable, ...call.commandArguments]), [
+        ['claude', 'plugin', 'uninstall', PSTACK_PLUGIN_IDENTIFIER],
+        ['claude', 'plugin', 'marketplace', 'remove', 'pstack-claude'],
         ['claude', 'plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY],
         ['claude', 'plugin', 'install', PSTACK_PLUGIN_IDENTIFIER],
+        ['codex', 'plugin', 'remove', PSTACK_PLUGIN_IDENTIFIER],
+        ['codex', 'plugin', 'marketplace', 'remove', 'pstack-claude'],
         ['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);
+    assert.equal(runner.calls[4].environment.CODEX_HOME, ROOTS.codexHome);
+});
+
+test('each host removes the installed plugin and marketplace before it installs', () => {
+    assert.deepEqual(marketplacePluginPlan(PSTACK_PLUGIN_SPEC, 'claude').removalCommands, [
+        ['plugin', 'uninstall', PSTACK_PLUGIN_IDENTIFIER],
+        ['plugin', 'marketplace', 'remove', 'pstack-claude'],
+    ]);
+    assert.deepEqual(marketplacePluginPlan(PSTACK_PLUGIN_SPEC, 'codex').removalCommands, [
+        ['plugin', 'remove', PSTACK_PLUGIN_IDENTIFIER],
+        ['plugin', 'marketplace', 'remove', 'pstack-claude'],
+    ]);
+});
+
+test('a removal that finds nothing installed still lets the install run', () => {
+    const runner = recordingRunner((executable, commandArguments) => (
+        commandArguments.includes('uninstall') || commandArguments.includes('remove')
+            ? { status: 1, stderr: 'not installed' }
+            : { status: 0, stderr: '' }));
+    const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, { ...ROOTS, hosts: ['claude'] }, runner);
+    assert.equal(outcome.status, 'installed');
+    assert.deepEqual(runner.calls.at(-1).commandArguments, ['plugin', 'install', PSTACK_PLUGIN_IDENTIFIER]);
 });
 
 test('an absent host command skips that host and leaves the other installed', () => {
@@ -83,7 +111,7 @@ test('an absent host command skips that host and leaves the other installed', ()
 
 test('a failing command reports that host and still installs the next one', () => {
     const runner = recordingRunner((executable, commandArguments) => (
-        executable === 'claude' && commandArguments[1] === 'marketplace'
+        executable === 'claude' && commandArguments[2] === 'add'
             ? { status: 1, stderr: 'marketplace unreachable' }
             : { status: 0, stderr: '' }));
     const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, ROOTS, runner);
@@ -92,7 +120,8 @@ test('a failing command reports that host and still installs the next one', () =
     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);
+    assert.deepEqual(runner.calls.filter(call => call.executable === 'claude').at(-1).commandArguments,
+        ['plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY]);
 });
 
 test('an executable override replaces the host command for that host only', () => {
@@ -207,6 +236,8 @@ test('installing usage-wrapup runs only the Claude commands, inside the managed
     assert.equal(outcome.status, 'installed');
     assert.deepEqual(outcome.hosts.map(host => host.host), ['claude']);
     assert.deepEqual(runner.calls.map(call => [call.executable, ...call.commandArguments]), [
+        ['claude', 'plugin', 'uninstall', 'usage-wrapup@claude-dev-env'],
+        ['claude', 'plugin', 'marketplace', 'remove', 'claude-dev-env'],
         ['claude', 'plugin', 'marketplace', 'add', 'jl-cmd/claude-dev-env', '--sparse', '.claude-plugin'],
         ['claude', 'plugin', 'install', 'usage-wrapup@claude-dev-env'],
     ]);
@@ -255,3 +286,20 @@ test('the repository marketplace lists usage-wrapup from the fork, pinned to the
         sha: USAGE_WRAPUP_PINNED_COMMIT,
     });
 });
+
+test('a clean install deletes the orphaned pstack versions and keeps the installed one', () => {
+    const claudeRoot = mkdtempSync(join(tmpdir(), 'pstack-orphans-'));
+    const versionsDirectory = join(claudeRoot, 'plugins', 'cache', 'pstack-claude', 'pstack');
+    mkdirSync(join(versionsDirectory, '0.9.55'), { recursive: true });
+    writeFileSync(join(versionsDirectory, '0.9.55', '.orphaned_at'), '1');
+    mkdirSync(join(versionsDirectory, '0.9.64'), { recursive: true });
+    const outcome = installMarketplacePlugin(
+        PSTACK_PLUGIN_SPEC,
+        { claudeRoot, hosts: ['claude'], environment: {} },
+        recordingRunner(),
+    );
+    assert.equal(outcome.status, 'installed');
+    assert.equal(existsSync(join(versionsDirectory, '0.9.55')), false);
+    assert.equal(existsSync(join(versionsDirectory, '0.9.64')), true);
+    assert.deepEqual(removeOrphanedPluginVersions(versionsDirectory), []);
+});

package/bin/install.test.mjs

@@ -3110,9 +3110,13 @@ test('a full install adds the pstack marketplace and plugin on both hosts', t =>
     const installerOutput = runPstackInstaller(sandbox.homeDirectory, [], sandbox.environment);
 
     assert.deepEqual(sandbox.recordedCommands(), [
-        'claude plugin marketplace add michael-denyer/pstack-claude',
+        'claude plugin uninstall pstack@pstack-claude',
+        'claude plugin marketplace remove pstack-claude',
+        'claude plugin marketplace add jl-cmd/pstack-claude',
         'claude plugin install pstack@pstack-claude',
-        'codex plugin marketplace add michael-denyer/pstack-claude',
+        'codex plugin remove pstack@pstack-claude',
+        'codex plugin marketplace remove pstack-claude',
+        'codex plugin marketplace add jl-cmd/pstack-claude',
         'codex plugin add pstack@pstack-claude',
     ]);
     assert.match(installerOutput, /Pstack \(claude\): installed/);
@@ -3311,6 +3315,8 @@ test('a pstack install after a --no-pstack install seeds the Codex model sheet',
 });
 
 const USAGE_WRAPUP_CLAUDE_COMMANDS = Object.freeze([
+    'claude plugin uninstall usage-wrapup@claude-dev-env',
+    'claude plugin marketplace remove claude-dev-env',
     'claude plugin marketplace add jl-cmd/claude-dev-env --sparse .claude-plugin',
     'claude plugin install usage-wrapup@claude-dev-env',
 ]);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.42.6",
+    "version": "8.43.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/tests/test_rules.py

@@ -13,7 +13,7 @@ def _comment_policy_phrases() -> tuple[str, ...]:
         "leave comments tied to untouched code unchanged",
         "keep comment cleanup inside the requested task",
         "production and tests follow one rule",
-        "changed directive, todo, fixme, hack, xxx, and type-ignore comments are removed rather than added or justified",
+        "changed directive, todo, fixme, hack, xxx, and type-ignore comments are removed",
     )