@ran-sh/dsh-crew 0.3.3 → 0.3.5

package/README.md

@@ -40,21 +40,33 @@ Codex Desktop / Claude Code
 
 Prerequisites: **Node.js** (Git is needed only for coding-worker isolation).
 
-Recommended: manage DSH Crew directly through npm/npx — no clone required:
+Recommended: install a stable, package-manager-installed launcher and manage DSH Crew with it:
 
 ```bash
-npx @ran-sh/dsh-crew@latest install
+npm install -g @ran-sh/dsh-crew@latest
+dsh-crew install
 ```
 
 Manage the installation later with the same CLI:
 
 ```bash
-npx @ran-sh/dsh-crew@latest status
-npx @ran-sh/dsh-crew@latest update
-npx @ran-sh/dsh-crew@latest uninstall        # add --purge to also remove config/backups
+dsh-crew status
+dsh-crew update
+dsh-crew uninstall        # add --purge to also remove config/backups
 ```
 
-An npx install persists the already-built package under Crew-owned state (`~/.config/dsh-crew/app`) before registering it, so the installation never depends on a transient npx cache and does not require pnpm, a lockfile, or rebuilding anything.
+The globally installed package is only the launcher/manager. The actual Crew runtime/plugin payload is persisted under Crew-owned state (`~/.config/dsh-crew/app`) before Harness registration, so runtime behavior never depends on npm cache paths.
+
+> Known compatibility issue: transient `npx @ran-sh/dsh-crew …` execution is currently unreliable on some npm versions (npm/cli#9870: the npx cache bin is not put on the spawned command PATH). Until that upstream fix reaches your npm, use the global-launcher flow above instead.
+
+An update of the managed payload does not require a clone or rebuild. When the launcher and payload versions match, `dsh-crew update` resolves the newest permitted package from your configured npm registry (or an explicit `--candidate <path>` override). When the running launcher is newer, its validated package payload is used first to converge the older managed payload. Every path stages and validates before switching. If the managed payload is newer than the launcher, it is never downgraded and the CLI prints the exact launcher-refresh command.
+
+> Migration boundary for legacy `<= 0.3.3`: those immutable launchers cannot discover newer registry versions, so their old update behavior cannot be retroactively fixed. Refresh the launcher first, then converge the managed payload—no source checkout is required:
+>
+> ```bash
+> npm install -g @ran-sh/dsh-crew@latest
+> dsh-crew update
+> ```
 
 Developer / source setup (alternative path):
 
@@ -113,16 +125,16 @@ A coding worker receives a temporary git worktree at the requested revision, so
 
 ## Update / uninstall
 
-npx-managed installs update in place (config, credentials, and backups are preserved; the candidate is staged and validated before switching):
+The managed Crew payload updates in place (config, credentials, and backups are preserved; the candidate is staged and validated before switching):
 
 ```bash
-npx @ran-sh/dsh-crew@latest update
+dsh-crew update
 ```
 
-Uninstall an npx-managed install:
+Uninstall the managed payload and integrations:
 
 ```bash
-npx @ran-sh/dsh-crew@latest uninstall
+dsh-crew uninstall
 ```
 
 Update a source install instead with:

package/README.zh.md

@@ -40,21 +40,33 @@ Codex Desktop / Claude Code
 
 需要：**Node.js**（编码 worker 隔离需要 **Git**）。
 
-推荐直接通过 npm/npx 管理，无需克隆仓库：
+推荐安装稳定的包管理器全局启动器，并用它管理 DSH Crew：
 
 ```bash
-npx @ran-sh/dsh-crew@latest install
+npm install -g @ran-sh/dsh-crew@latest
+dsh-crew install
 ```
 
 后续管理使用同一 CLI：
 
 ```bash
-npx @ran-sh/dsh-crew@latest status
-npx @ran-sh/dsh-crew@latest update
-npx @ran-sh/dsh-crew@latest uninstall        # 加 --purge 才会同时删除配置/备份
+dsh-crew status
+dsh-crew update
+dsh-crew uninstall        # 加 --purge 才会同时删除配置/备份
 ```
 
-npx 安装会把已构建好的包持久化到 Crew 自有状态（`~/.config/dsh-crew/app`）后再注册，安装不依赖临时的 npx 缓存，也不需要 pnpm、lockfile 或任何构建步骤。
+全局安装的包只是启动器/管理器；真正的 Crew 运行时/插件载荷会先持久化到 Crew 自有状态（`~/.config/dsh-crew/app`）再注册，运行时行为不依赖 npm 缓存路径。
+
+> 已知兼容性问题：部分 npm 版本下，临时 `npx @ran-sh/dsh-crew …` 执行不可靠（npm/cli#9870：npx 缓存中的 bin 未加入子进程 PATH）。在该上游修复可用之前，请使用上面的全局启动器方式。
+
+托管载荷的更新无需克隆或构建。启动器与载荷版本相同时，`dsh-crew update` 会从你配置的 npm registry 解析最新允许版本（或用 `--candidate <path>` 显式指定）；当前启动器较新时，会优先用这个已校验的启动器包收敛旧载荷。所有路径都会先暂存、校验，再切换。托管载荷较新时绝不降级，CLI 会打印刷新启动器的准确命令。
+
+> 旧版 `<= 0.3.3` 的迁移边界：这些不可变的旧启动器无法发现更新的 registry 版本，其旧 update 行为无法被追溯修复。受支持的迁移方式是先刷新启动器，再收敛托管载荷；无需源码检出：
+>
+> ```bash
+> npm install -g @ran-sh/dsh-crew@latest
+> dsh-crew update
+> ```
 
 开发者 / 源码安装（备选路径）：
 
@@ -113,16 +125,16 @@ Use ds-reviewer to review the implementation.
 
 ## 更新 / 卸载
 
-npx 安装使用 update 原地升级（配置、凭据和备份保留；候选包先暂存校验再切换）：
+托管 Crew 载荷使用 update 原地升级（配置、凭据和备份保留；候选包先暂存校验再切换）：
 
 ```bash
-npx @ran-sh/dsh-crew@latest update
+dsh-crew update
 ```
 
-卸载 npx 安装：
+卸载托管载荷与集成：
 
 ```bash
-npx @ran-sh/dsh-crew@latest uninstall
+dsh-crew uninstall
 ```
 
 源码安装的更新方式：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ran-sh/dsh-crew",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "main": "./src/hub/entry.mjs",
   "bin": {

package/src/install/npx-lifecycle.mjs

@@ -1,10 +1,11 @@
-// v0.3.3 npx-managed lifecycle: install / status / update / uninstall.
+// Packaged global-launcher lifecycle: install / status / update / uninstall.
 //
 // Public UX:
-//   npx @ran-sh/dsh-crew@latest install|status|update|uninstall
+//   npm install -g @ran-sh/dsh-crew@latest
+//   dsh-crew install|status|update|uninstall
 //
-// An npx invocation runs from a transient package-manager extraction/cache
-// path. This module therefore persists the already-built package payload into
+// A package-manager launcher may run from a replaceable global/cache path.
+// This module therefore persists the already-built package payload into
 // Crew-owned state BEFORE registering it with the Harness profile, so the
 // registration never depends on the cache, tarball, or temp extraction dir:
 //
@@ -565,57 +566,252 @@ export async function npxInstall({
   return { ok: true, version: manifest.version, path: releaseDir };
 }
 
+export const UPDATE_PACKAGE_NAME = '@ran-sh/dsh-crew';
+export const UPDATE_DEFAULT_SPEC = `${UPDATE_PACKAGE_NAME}@latest`;
+
+/**
+ * Extract a packed npm tarball with the platform `tar` binary (bsdtar ships
+ * with Windows 10+, macOS, and Linux) into destDir; npm tarballs always root
+ * at `package/`.
+ */
+export function extractPackageTarball(tgzPath, destDir, { runner = spawnSync } = {}) {
+  mkdirSync(destDir, { recursive: true });
+  const result = runner('tar', ['-xzf', String(tgzPath), '-C', destDir], {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true,
+  });
+  const root = join(destDir, 'package');
+  if (result.status !== 0 || !existsSync(join(root, 'package.json'))) {
+    return { ok: false, detail: `tar extract failed (${result.status}): ${(result.stderr || result.stdout || '').trim().slice(-200)}` };
+  }
+  return { ok: true, sourceRoot: root };
+}
+
+/**
+ * The globally installed launcher intentionally does not self-replace. When
+ * the payload is newer, keep it authoritative and give the exact launcher
+ * refresh command. A newer launcher is handled by npxUpdate before this point.
+ */
+function noteLauncherDivergence({ log, home = homedir() }) {
+  const launcherVersion = readManifest(runningPackageRoot())?.version ?? null;
+  let installedVersion = null;
+  try { installedVersion = readCurrentPointer({ home }).version ?? null; } catch { installedVersion = null; }
+  if (launcherVersion && installedVersion && compareVersions(installedVersion, launcherVersion) > 0) {
+    log('');
+    log(`- note: managed payload ${installedVersion} is newer than the global launcher ${launcherVersion}; the payload remains authoritative.`);
+    log(`  Refresh the launcher when convenient: npm install -g ${UPDATE_PACKAGE_NAME}@${installedVersion}`);
+  }
+}
+
+/**
+ * Resolve an update candidate WITHOUT a source checkout:
+ *  - explicit candidate path: a payload directory or a packed .tgz file;
+ *  - otherwise npm registry mode: `npm pack <spec>` using the user's own
+ *    configured registry/auth (no policy or config mutation), extracted to a
+ *    disposable directory the caller cleans up via returned cleanup().
+ */
+export function resolveUpdateCandidate({
+  candidate,
+  spec = UPDATE_DEFAULT_SPEC,
+  home = homedir(),
+  log = () => {},
+  runner = spawnSync,
+} = {}) {
+  const candidateValue = candidate ?? process.env.DSH_CREW_CANDIDATE ?? undefined;
+  if (candidateValue !== undefined && typeof candidateValue !== 'string') {
+    return { ok: false, code: 'INVALID_CANDIDATE', detail: 'candidate must be a directory or .tgz path' };
+  }
+  if (typeof candidateValue === 'string' && candidateValue.trim()) {
+    const value = resolve(candidateValue.trim());
+    if (!existsSync(value)) return { ok: false, code: 'CANDIDATE_NOT_FOUND', detail: value };
+    if (existsSync(join(value, 'package.json'))) {
+      const manifest = readManifest(value);
+      if (!manifest?.name || !manifest?.version) return { ok: false, code: 'CANDIDATE_MANIFEST_INVALID', detail: value };
+      return { ok: true, sourceRoot: value, version: manifest.version, cleanup: null };
+    }
+    if (/\.tgz$/i.test(value)) {
+      const tmpRoot = join(crewReleasesDir({ home }), `.candidate-${timestampStamp()}-${process.pid}`);
+      const extracted = extractPackageTarball(value, tmpRoot, { runner });
+      if (!extracted.ok) {
+        rmSync(tmpRoot, { recursive: true, force: true });
+        return { ok: false, code: 'CANDIDATE_EXTRACT_FAILED', detail: extracted.detail };
+      }
+      const manifest = readManifest(extracted.sourceRoot);
+      if (!manifest?.name || !manifest?.version) {
+        rmSync(tmpRoot, { recursive: true, force: true });
+        return { ok: false, code: 'CANDIDATE_MANIFEST_INVALID', detail: value };
+      }
+      return {
+        ok: true,
+        sourceRoot: extracted.sourceRoot,
+        version: manifest.version,
+        cleanup: () => rmSync(tmpRoot, { recursive: true, force: true }),
+      };
+    }
+    return { ok: false, code: 'UNSUPPORTED_CANDIDATE', detail: value };
+  }
+
+  // Registry mode.
+  const tmpDir = join(crewReleasesDir({ home }), `.candidate-${timestampStamp()}-${process.pid}`);
+  mkdirSync(tmpDir, { recursive: true });
+  try {
+    const effectiveSpec = process.env.DSH_CREW_UPDATE_SPEC ?? spec;
+    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const packArgs = ['pack', effectiveSpec, '--pack-destination', tmpDir, '--json', '--loglevel=error'];
+    log(`- resolving update candidate from the configured npm registry (${effectiveSpec})`);
+    const packed = runner(npm, packArgs, {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], shell: process.platform === 'win32',
+      timeout: 600_000, windowsHide: true, env: sanitizedPackageManagerEnv(),
+    });
+    if (packed.status !== 0) {
+      return { ok: false, code: 'REGISTRY_PACK_FAILED', detail: `${effectiveSpec}: ${(packed.stderr || packed.stdout || '').trim().slice(-300)}` };
+    }
+    let info;
+    try { info = JSON.parse(packed.stdout)[0]; } catch {
+      return { ok: false, code: 'REGISTRY_PACK_UNPARSEABLE', detail: String(packed.stdout).slice(-200) };
+    }
+    if (!info?.filename) return { ok: false, code: 'REGISTRY_PACK_UNPARSEABLE', detail: 'pack output missing filename' };
+    const tgzPath = join(tmpDir, info.filename);
+    const extracted = extractPackageTarball(tgzPath, join(tmpDir, 'x'), { runner });
+    if (!extracted.ok) {
+      return { ok: false, code: 'CANDIDATE_EXTRACT_FAILED', detail: extracted.detail };
+    }
+    const manifest = readManifest(extracted.sourceRoot);
+    if (!manifest?.name || !manifest?.version) {
+      return { ok: false, code: 'CANDIDATE_MANIFEST_INVALID', detail: info.filename };
+    }
+    if (info.name !== manifest.name || info.version !== manifest.version) {
+      return { ok: false, code: 'CANDIDATE_IDENTITY_MISMATCH', detail: `pack ${info.name}@${info.version} vs manifest ${manifest.name}@${manifest.version}` };
+    }
+    return {
+      ok: true,
+      sourceRoot: extracted.sourceRoot,
+      version: manifest.version,
+      cleanup: () => rmSync(tmpDir, { recursive: true, force: true }),
+    };
+  } catch (error) {
+    rmSync(tmpDir, { recursive: true, force: true });
+    return { ok: false, code: 'REGISTRY_PACK_FAILED', detail: String(error?.message ?? error).slice(-300) };
+  }
+}
+
 export async function npxUpdate({
   home = homedir(),
   log = console.log,
   sourceRoot,
+  candidate,
+  spec,
   installer = realInstaller,
   ensureRuntime,
   npmInstaller,
+  runner = spawnSync,
 } = {}) {
-  log('DSH Crew updater (npx-managed)');
-  const candidateRoot = sourceRoot ?? runningPackageRoot();
-  const manifest = readManifest(candidateRoot);
-  if (!manifest?.name || !manifest?.version) return { ok: false, error: 'candidate package manifest invalid' };
+  log('DSH Crew updater');
+  // Candidate resolution: explicit path/dir override > a newer validated
+  // running launcher > configured npm registry (@latest). This makes the
+  // supported legacy bootstrap (`npm install -g ...@latest`, then `update`)
+  // independent of registry propagation after the launcher refresh.
+  const explicitCandidate = candidate ?? sourceRoot;
+  const initialHealth = currentInstallationHealth({ home });
+  const launcherRoot = runningPackageRoot();
+  const launcherManifest = readManifest(launcherRoot);
+  const launcherCanConverge = explicitCandidate === undefined
+    && initialHealth.pointer?.version
+    && launcherManifest?.name === UPDATE_PACKAGE_NAME
+    && launcherManifest?.version
+    && compareVersions(launcherManifest.version, initialHealth.pointer.version) > 0;
+  let resolved;
+  if (launcherCanConverge) {
+    log(`- newer launcher ${launcherManifest.version}; converging managed payload ${initialHealth.pointer.version} before registry resolution`);
+    resolved = { ok: true, sourceRoot: launcherRoot, version: launcherManifest.version, cleanup: null };
+  } else {
+    resolved = resolveUpdateCandidate({ candidate: explicitCandidate, spec, home, log, runner });
+  }
+  if (!resolved.ok) {
+    log(`✗ candidate resolution failed (${resolved.code})${resolved.detail ? `: ${resolved.detail}` : ''}`);
+    return { ok: false, error: `candidate resolution failed (${resolved.code})` };
+  }
+  try {
+    const manifest = readManifest(resolved.sourceRoot);
+    if (!manifest?.name || !manifest?.version) return { ok: false, error: 'candidate package manifest invalid' };
+
+    const health = currentInstallationHealth({ home });
+
+    if (health.installed && health.healthy && health.pointer.version === manifest.version) {
+      log(`- already current (${manifest.version}); repairing registration/integrations idempotently`);
+      const activated = await activateRelease({ home, releaseDir: health.pointer.path, manifest, log, installer });
+      if (!activated) return { ok: false, error: 'activation failed' };
+      if (!await ensureRuntimeStep({ home, log, ensureRuntime })) return { ok: false, error: 'Crew DSH runtime bootstrap failed' };
+      log('');
+      log('Done.');
+      return { ok: true, idempotent: true, version: manifest.version, path: health.pointer.path };
+    }
 
-  const health = currentInstallationHealth({ home });
+    if (health.installed && health.healthy && compareVersions(manifest.version, health.pointer.version) < 0) {
+      const source = explicitCandidate === undefined && !launcherCanConverge ? 'registry latest' : 'candidate';
+      log(`- ${source} (${manifest.version}) is not newer than the installed payload (${health.pointer.version}); nothing to update`);
+      const activated = await activateRelease({ home, releaseDir: health.pointer.path, manifest: readManifest(health.pointer.path), log, installer });
+      if (!activated) return { ok: false, error: 'activation failed' };
+      return { ok: true, idempotent: true, version: health.pointer.version, path: health.pointer.path };
+    }
 
-  if (health.installed && health.healthy && health.pointer.version === manifest.version) {
-    log(`- already current (${manifest.version}); repairing registration/integrations idempotently`);
-    const activated = await activateRelease({ home, releaseDir: health.pointer.path, manifest, log, installer });
+    // Stale, unhealthy, older, or missing installation: stage the candidate
+    // fully and validate it before switching. The previous usable release is
+    // left in place until the replacement has been committed and activated.
+    if (health.installed && !health.healthy) {
+      log('- existing installation is stale or incomplete; repairing via fresh candidate staging');
+    } else if (health.installed) {
+      log(`- updating managed payload ${health.pointer.version} -> ${manifest.version}`);
+    }
+
+    const staged = stageCandidatePayload({ sourceRoot: resolved.sourceRoot, home, log, npmInstaller });
+    if (!staged.ok) {
+      log(`✗ staging failed (${staged.code})${staged.detail ? `: ${staged.detail.join('; ')}` : ''}`);
+      return { ok: false, error: `staging failed (${staged.code})` };
+    }
+    log(`✓ candidate payload staged and validated (${manifest.version})`);
+
+    const releaseDir = commitStagedRelease({ stageDir: staged.stageDir, manifest, home });
+    log('✓ durable release committed under Crew-owned state');
+
+    const activated = await activateRelease({ home, releaseDir, manifest, log, installer });
     if (!activated) return { ok: false, error: 'activation failed' };
+
     if (!await ensureRuntimeStep({ home, log, ensureRuntime })) return { ok: false, error: 'Crew DSH runtime bootstrap failed' };
+
+    noteLauncherDivergence({ log, home });
     log('');
     log('Done.');
-    return { ok: true, idempotent: true, version: manifest.version, path: health.pointer.path };
-  }
-
-  // Stale, unhealthy, or missing installation: stage the candidate fully and
-  // validate it before switching. The previous usable release is left in place
-  // until the replacement has been committed and activated successfully.
-  if (health.installed && !health.healthy) {
-    log('- existing installation is stale or incomplete; repairing via fresh candidate staging');
+    log('Restart DeepSeek Harness and Codex Desktop.');
+    return { ok: true, updated: true, version: manifest.version, path: releaseDir };
+  } finally {
+    resolved.cleanup?.();
   }
+}
 
-  const staged = stageCandidatePayload({ sourceRoot: candidateRoot, home, log, npmInstaller });
-  if (!staged.ok) {
-    log(`✗ staging failed (${staged.code})${staged.detail ? `: ${staged.detail.join('; ')}` : ''}`);
-    return { ok: false, error: `staging failed (${staged.code})` };
+/**
+ * Compare dotted numeric versions; returns -1/0/1. Non-numeric segments fall
+ * back to string comparison so prerelease identifiers stay deterministic.
+ */
+export function compareVersions(left, right) {
+  const asParts = (value) => String(value ?? '').split('.');
+  const a = asParts(left);
+  const b = asParts(right);
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    const x = a[index] ?? '0';
+    const y = b[index] ?? '0';
+    const xn = /^\d+$/.test(x);
+    const yn = /^\d+$/.test(y);
+    if (xn && yn) {
+      const diff = Number(x) - Number(y);
+      if (diff !== 0) return diff < 0 ? -1 : 1;
+    } else if (xn !== yn) {
+      // npm semantics: a numeric release segment outranks a prerelease segment.
+      return xn ? 1 : -1;
+    } else if (x !== y) {
+      return x < y ? -1 : 1;
+    }
   }
-  log(`✓ candidate payload staged and validated (${manifest.version})`);
-
-  const releaseDir = commitStagedRelease({ stageDir: staged.stageDir, manifest, home });
-  log('✓ durable release committed under Crew-owned state');
-
-  const activated = await activateRelease({ home, releaseDir, manifest, log, installer });
-  if (!activated) return { ok: false, error: 'activation failed' };
-
-  if (!await ensureRuntimeStep({ home, log, ensureRuntime })) return { ok: false, error: 'Crew DSH runtime bootstrap failed' };
-
-  log('');
-  log('Done.');
-  log('Restart DeepSeek Harness and Codex Desktop.');
-  return { ok: true, updated: true, version: manifest.version, path: releaseDir };
+  return 0;
 }
 
 export function npxStatus({
@@ -664,8 +860,18 @@ export function npxStatus({
   const codex = st?.codex?.installed ? 'installed' : 'not installed';
   const claude = st?.claude?.installed ? 'installed' : 'not installed';
 
-  log(`DSH Crew CLI (npx candidate): ${candidateVersion ?? 'unknown'}`);
-  log(`Installed DSH Crew: ${installedLine}`);
+  log(`DSH Crew launcher/candidate: ${candidateVersion ?? 'unknown'}`);
+  log(`Installed DSH Crew payload: ${installedLine}`);
+  if (candidateVersion && installedVersion && candidateVersion !== installedVersion) {
+    const direction = compareVersions(candidateVersion, installedVersion);
+    if (direction > 0) {
+      log(`- launcher ${candidateVersion} is newer than the managed payload ${installedVersion}.`);
+      log('  Run: dsh-crew update');
+    } else {
+      log(`- managed payload ${installedVersion} is newer than the launcher ${candidateVersion}; the payload remains authoritative.`);
+      log(`  Refresh the launcher with: npm install -g ${UPDATE_PACKAGE_NAME}@${installedVersion}`);
+    }
+  }
   log(`DSH plugin: ${dshPlugin} (dedicated dsh-crew profile; official web profile ignored)`);
   log(`Codex Desktop integration: ${codex}`);
   log(`Claude Code integration: ${claude}`);
@@ -736,25 +942,40 @@ export async function npxUninstall({
 
 // ---- CLI dispatch --------------------------------------------------------------
 
-export const USAGE = `usage: dsh-crew <command> [--purge]
+export const USAGE = `usage: dsh-crew <command> [--purge] [--candidate <path>]
 
 Commands:
   install     persist the candidate package into Crew-owned state and register it
-  status      read-only report of candidate/installed versions and integrations
-  update      upgrade-aware update: stages/validates first, repairs, idempotent when current
+  status      read-only report of launcher/installed versions and integrations
+  update      resolve the newest permitted package from the configured npm registry (or
+              --candidate), stage and validate it, then activate; idempotent when current
   uninstall   remove the Crew-managed payload, registration, and integrations (config kept)
 
 Options:
-  --purge     with uninstall: also remove ~/.config/dsh-crew config/backups (destructive)
-  --help      show this help
+  --candidate <path>  update from a local payload directory or packed .tgz instead of the registry
+  --purge             with uninstall: also remove ~/.config/dsh-crew config/backups (destructive)
+  --help              show this help
 
+Primary install: npm install -g @ran-sh/dsh-crew   (then run: dsh-crew install)
 Source checkouts use scripts/setup.mjs instead.`;
 
 function normalizeCommand(argv) {
   const flags = argv.slice(1);
+  let candidate;
+  for (let index = 0; index < flags.length; index += 1) {
+    if (flags[index] === '--candidate') {
+      candidate = flags[index + 1];
+      flags.splice(index, 2);
+      index -= 1;
+    } else if (flags[index]?.startsWith('--candidate=')) {
+      candidate = flags[index].slice('--candidate='.length);
+      flags.splice(index, 1);
+      index -= 1;
+    }
+  }
   const knownFlags = new Set(['--purge']);
   const unknown = flags.filter((f) => f.startsWith('--') && !knownFlags.has(f));
-  return { command: argv[0], purge: flags.includes('--purge'), unknown };
+  return { command: argv[0], purge: flags.includes('--purge'), candidate, unknown };
 }
 
 /**
@@ -766,7 +987,7 @@ export async function runNpxCli({
   error = console.error,
   commands = {},
 } = {}) {
-  const { command, purge, unknown } = normalizeCommand(argv);
+  const { command, purge, candidate, unknown } = normalizeCommand(argv);
   if (command === '--help' || command === '-h' || command === 'help') {
     log(USAGE);
     return 0;
@@ -786,9 +1007,10 @@ export async function runNpxCli({
       update: commands.update ?? npxUpdate,
       uninstall: commands.uninstall ?? npxUninstall,
     };
-    const result = command === 'uninstall'
-      ? await actions.uninstall({ purge, log })
-      : await actions[command]({ log });
+    let result;
+    if (command === 'uninstall') result = await actions.uninstall({ purge, log });
+    else if (command === 'update') result = await actions.update({ candidate, log });
+    else result = await actions[command]({ log });
     return result?.ok === false ? 1 : 0;
   } catch (err) {
     error(`dsh-crew ${command} failed: ${err?.message ?? err}`);

package/src/runtime-identity.mjs

@@ -8,7 +8,7 @@
 // Keep this module pure and dependency-free so Hub, MCP and tests all use the
 // exact same compatibility rules.
 
-export const RUNTIME_VERSION = '0.3.3';
+export const RUNTIME_VERSION = '0.3.5';
 export const HUB_PROTOCOL_VERSION = 1;
 
 export const HUB_CAPABILITIES = Object.freeze([