@vibecodr/cli 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Pre-1.0.0 history for the `@vibecodr/cli@0.2.x` and `0.1.x` lines lives at [`docs/legacy/CHANGELOG-mcp-cli.md`](docs/legacy/CHANGELOG-mcp-cli.md). The `@vibecodr/vc-tools@0.1.x` line was the other half of the May 2026 merge; its source history is preserved in the archived [`BradenHartsell/vc-tools`](https://github.com/BradenHartsell/vc-tools) repository.
 
+## 1.0.2
+
+Hardens `preinstall-check.mjs` to also catch the **orphan-bin-shim** case that the 1.0.1 check missed.
+
+When an earlier `npm install -g @vibecodr/cli` (or `@vibecodr/vc-tools`) was aborted mid-flight on Windows — typically because antivirus or an IDE held a file handle on the just-extracted tree during npm's cleanup — npm leaves the bin shim files (`vc-tools`, `vc-tools.cmd`, `vc-tools.ps1`, the `vibecodr` and `vibecodr-mcp` triples) at the global bin dir but the package itself isn't fully registered. The retry trips the same EEXIST because npm refuses to overwrite shim files it didn't write in the current install run.
+
+The preinstall now:
+
+- Inspects the global bin dir (`%APPDATA%\npm\` on Windows, `<prefix>/bin/` on POSIX) for any of the nine Windows shim names or three POSIX shim names.
+- Cross-references against the global node_modules tree: if `<global-root>/@vibecodr/cli/package.json` doesn't exist or doesn't name `@vibecodr/cli`, the shim files are orphans.
+- Prints an actionable cleanup recipe (`Remove-Item ... -Force` on Windows, `rm -f ...` on POSIX) listing the exact files to delete plus the half-installed package directory if present, then `npm install -g @vibecodr/cli`.
+
+The check still bails for non-global installs, local dev installs from the source repo, and `VIBECDR_SKIP_PREINSTALL_CHECK=1` opt-outs, and false-positive-proofs itself: a clean re-install / upgrade of `@vibecodr/cli` (shims present + valid `@vibecodr/cli/package.json` present) passes through silently.
+
+- `preinstall-check.mjs`: orphan-shim detection on top of the existing legacy-package check.
+- `test/preinstall-check.test.ts`: 2 new cases (orphan-blocks, upgrade-passes-through) on top of the original 4.
+
 ## 1.0.1
 
 Fixes the global-install collision for users who already had `@vibecodr/vc-tools@0.1.x` installed globally. Both packages register a `vc-tools` bin under the same path; npm refuses to overwrite a bin owned by a different package, so the install fails with `EEXIST: file already exists`.

package/dist/legacy/core/version.d.ts

@@ -1,3 +1,3 @@
-export declare const CLI_VERSION = "1.0.1";
-export declare const VC_TOOLS_VERSION = "1.0.1";
+export declare const CLI_VERSION = "1.0.2";
+export declare const VC_TOOLS_VERSION = "1.0.2";
 //# sourceMappingURL=version.d.ts.map

package/dist/legacy/core/version.js

@@ -1,3 +1,3 @@
-export const CLI_VERSION = "1.0.1";
+export const CLI_VERSION = "1.0.2";
 export const VC_TOOLS_VERSION = CLI_VERSION;
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecodr/cli",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "The official Vibecodr CLI: hosted browser, hosted computer, capsule uploads, Pulse operations, and agent-client MCP setup under one command.",
   "license": "Apache-2.0",
   "type": "module",

package/preinstall-check.mjs

@@ -1,20 +1,29 @@
-// Runs as the npm `preinstall` lifecycle script before file copy. Detects the
-// global-install collision where a pre-merger @vibecodr/vc-tools@0.1.x owns
-// the `vc-tools` bin shim and would block npm from writing the
-// @vibecodr/cli@1.x version of the same bin (npm refuses to overwrite a bin
-// owned by a different package; the user otherwise sees an unhelpful EEXIST
-// pointing at a file in the global bin dir). Exits non-zero with an
-// actionable message so npm aborts cleanly with our text instead of npm's.
+// Runs as the npm `preinstall` lifecycle script before file copy. Catches two
+// install-blocking scenarios for `npm install -g @vibecodr/cli` and exits
+// with an actionable message instead of leaving the user staring at npm's
+// bare EEXIST:
+//
+//   1. Legacy install: @vibecodr/vc-tools@0.1.x is globally installed. That
+//      package and @vibecodr/cli@1.x both register a `vc-tools` bin under
+//      the same path; npm refuses to overwrite a bin owned by a different
+//      package.
+//   2. Orphan shims from a prior aborted install: an earlier `npm install
+//      -g @vibecodr/cli` (or @vibecodr/vc-tools) wrote some of the
+//      `vc-tools` / `vibecodr` / `vibecodr-mcp` shim files at the global
+//      bin dir then died on Windows-handle-locked file cleanup. The
+//      orphan files block the retry with EEXIST even though no package
+//      currently claims them.
 //
 // Bail-outs (the check is a no-op in any of these cases):
 //   - VIBECDR_SKIP_PREINSTALL_CHECK=1 (operator opt-out)
 //   - not a global install (the conflict is global-bin-only)
 //   - running from inside this source repo (npm install / npm ci during
 //     local dev shouldn't trip the check)
-//   - npm ls fails for any other reason (we don't want a transient npm
-//     error to block legitimate installs)
+//   - any inspection failure (`npm ls`, fs access) -- we never block a
+//     legitimate install on a transient diagnostic error
 
 import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -23,9 +32,10 @@ const here = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = here;
 
 function isLocalDevInstall() {
-  // The npm lifecycle sets npm_config_local_prefix (or PROJECT) to the
-  // directory holding the package.json being installed FROM. For npm ci/install
-  // run inside this repo, that prefix equals our repo root.
+  // The npm lifecycle sets npm_config_local_prefix (or INIT_CWD) to the
+  // directory holding the package.json being installed FROM. For
+  // npm ci / npm install run inside this repo, that prefix equals our
+  // repo root.
   const localPrefix = process.env["npm_config_local_prefix"] ?? process.env["INIT_CWD"];
   if (!localPrefix) return false;
   try {
@@ -49,6 +59,10 @@ if (isLocalDevInstall()) {
   process.exit(0);
 }
 
+// ---------------------------------------------------------------------------
+// Scenario 1: legacy @vibecodr/vc-tools@0.1.x globally installed
+// ---------------------------------------------------------------------------
+
 let collidingVersion;
 try {
   const output = execSync("npm ls -g --depth 0 --json @vibecodr/vc-tools", {
@@ -70,38 +84,160 @@ try {
   // conflict.
 }
 
-if (!collidingVersion) {
-  process.exit(0);
+if (collidingVersion) {
+  printLegacyConflictMessage(collidingVersion);
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Scenario 2: orphan vc-tools / vibecodr / vibecodr-mcp shims at the global
+// bin dir with no @vibecodr/cli package currently installed to own them
+// ---------------------------------------------------------------------------
+
+function npmGlobalBinDir() {
+  // Windows: <prefix>/. POSIX: <prefix>/bin.
+  const prefix = process.env["npm_config_prefix"];
+  if (!prefix) return undefined;
+  return process.platform === "win32" ? prefix : path.join(prefix, "bin");
+}
+
+function npmGlobalRoot() {
+  const prefix = process.env["npm_config_prefix"];
+  if (!prefix) return undefined;
+  return process.platform === "win32"
+    ? path.join(prefix, "node_modules")
+    : path.join(prefix, "lib", "node_modules");
 }
 
-console.error("");
-console.error("==========================================================================");
-console.error("  @vibecodr/cli install blocked: legacy @vibecodr/vc-tools is in the way");
-console.error("==========================================================================");
-console.error("");
-console.error(`  You have @vibecodr/vc-tools@${collidingVersion} installed globally. That`);
-console.error("  package and @vibecodr/cli@1.x both claim the `vc-tools` bin name on");
-console.error("  disk, and npm refuses to overwrite a bin owned by a different package");
-console.error("  (you would otherwise see a cryptic EEXIST pointing at the global bin");
-console.error("  dir).");
-console.error("");
-console.error("  The merged @vibecodr/cli replaces the legacy @vibecodr/vc-tools. The");
-console.error("  legacy line is preserved on npm under explicit version pins; nothing");
-console.error("  about your stored credentials, OS keychain entries, or config dirs is");
-console.error("  removed by the uninstall below.");
-console.error("");
-console.error("  To unblock, in this order:");
-console.error("");
-console.error("    npm uninstall -g @vibecodr/vc-tools");
-console.error("    npm install -g @vibecodr/cli");
-console.error("");
-console.error("  After install, all three bin names work and resolve to the same");
-console.error("  dispatcher: vibecodr, vibecodr-mcp, vc-tools.");
-console.error("");
-console.error("  Advanced opt-out (not recommended): set VIBECDR_SKIP_PREINSTALL_CHECK=1");
-console.error("  and retry. The collision still trips an EEXIST inside npm; the env var");
-console.error("  only silences this preflight check.");
-console.error("");
-console.error("==========================================================================");
-console.error("");
-process.exit(1);
+function vibecodrCliInstalledAndValid() {
+  const root = npmGlobalRoot();
+  if (!root) return true; // can't determine -> don't block
+  const pkgPath = path.join(root, "@vibecodr", "cli", "package.json");
+  if (!existsSync(pkgPath)) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return pkg?.name === "@vibecodr/cli";
+  } catch {
+    return false;
+  }
+}
+
+const SHIM_NAMES_WIN = ["vc-tools", "vc-tools.cmd", "vc-tools.ps1", "vibecodr", "vibecodr.cmd", "vibecodr.ps1", "vibecodr-mcp", "vibecodr-mcp.cmd", "vibecodr-mcp.ps1"];
+const SHIM_NAMES_POSIX = ["vc-tools", "vibecodr", "vibecodr-mcp"];
+
+function detectOrphanShims() {
+  const dir = npmGlobalBinDir();
+  if (!dir) return [];
+  const candidates = process.platform === "win32" ? SHIM_NAMES_WIN : SHIM_NAMES_POSIX;
+  return candidates.filter((name) => existsSync(path.join(dir, name)));
+}
+
+const presentShims = detectOrphanShims();
+if (presentShims.length > 0 && !vibecodrCliInstalledAndValid()) {
+  // Shim files exist at the global bin dir but no @vibecodr/cli package
+  // exists in global node_modules to own them. They're either from an
+  // earlier aborted install of @vibecodr/cli or a manually-deleted
+  // package that didn't clean its shims. Either way, the retry will
+  // EEXIST unless the user removes them first.
+  printOrphanShimMessage(npmGlobalBinDir(), npmGlobalRoot(), presentShims);
+  process.exit(1);
+}
+
+// No conflict detected; let npm proceed.
+process.exit(0);
+
+// ---------------------------------------------------------------------------
+// Message helpers (separated so the test file can exercise the gate logic
+// without diffing the multi-line console output)
+// ---------------------------------------------------------------------------
+
+function printLegacyConflictMessage(version) {
+  console.error("");
+  console.error("==========================================================================");
+  console.error("  @vibecodr/cli install blocked: legacy @vibecodr/vc-tools is in the way");
+  console.error("==========================================================================");
+  console.error("");
+  console.error(`  You have @vibecodr/vc-tools@${version} installed globally. That`);
+  console.error("  package and @vibecodr/cli@1.x both claim the `vc-tools` bin name on");
+  console.error("  disk, and npm refuses to overwrite a bin owned by a different package");
+  console.error("  (you would otherwise see a cryptic EEXIST pointing at the global bin");
+  console.error("  dir).");
+  console.error("");
+  console.error("  The merged @vibecodr/cli replaces the legacy @vibecodr/vc-tools. The");
+  console.error("  legacy line is preserved on npm under explicit version pins; nothing");
+  console.error("  about your stored credentials, OS keychain entries, or config dirs is");
+  console.error("  removed by the uninstall below.");
+  console.error("");
+  console.error("  To unblock, in this order:");
+  console.error("");
+  console.error("    npm uninstall -g @vibecodr/vc-tools");
+  console.error("    npm install -g @vibecodr/cli");
+  console.error("");
+  console.error("  After install, all three bin names work and resolve to the same");
+  console.error("  dispatcher: vibecodr, vibecodr-mcp, vc-tools.");
+  console.error("");
+  console.error("  Advanced opt-out (not recommended): set VIBECDR_SKIP_PREINSTALL_CHECK=1");
+  console.error("  and retry. The collision still trips an EEXIST inside npm; the env var");
+  console.error("  only silences this preflight check.");
+  console.error("");
+  console.error("==========================================================================");
+  console.error("");
+}
+
+function printOrphanShimMessage(binDir, root, shims) {
+  console.error("");
+  console.error("==========================================================================");
+  console.error("  @vibecodr/cli install blocked: orphan bin shims from a prior install");
+  console.error("==========================================================================");
+  console.error("");
+  console.error("  These bin shim files exist in your global npm bin directory but no");
+  console.error("  @vibecodr/cli package is currently installed to own them:");
+  console.error("");
+  for (const name of shims) {
+    console.error(`    ${path.join(binDir, name)}`);
+  }
+  console.error("");
+  console.error("  They are typically left behind when an earlier global install of");
+  console.error("  @vibecodr/cli or @vibecodr/vc-tools was aborted mid-flight (Windows");
+  console.error("  file-handle locks during npm cleanup are the common cause). npm");
+  console.error("  refuses to overwrite shim files it didn't create in the current");
+  console.error("  install run, so the retry trips the same EEXIST every time.");
+  console.error("");
+  console.error("  To unblock on Windows (PowerShell):");
+  console.error("");
+  for (const name of shims) {
+    console.error(`    Remove-Item "${path.join(binDir, name)}" -Force`);
+  }
+  if (root) {
+    const halfInstall = path.join(root, "@vibecodr", "cli");
+    if (existsSync(halfInstall)) {
+      console.error(`    Remove-Item "${halfInstall}" -Recurse -Force`);
+    }
+  }
+  console.error("    npm install -g @vibecodr/cli");
+  console.error("");
+  console.error("  On macOS / Linux (bash):");
+  console.error("");
+  for (const name of shims) {
+    console.error(`    rm -f "${path.join(binDir, name)}"`);
+  }
+  if (root) {
+    const halfInstall = path.join(root, "@vibecodr", "cli");
+    if (existsSync(halfInstall)) {
+      console.error(`    rm -rf "${halfInstall}"`);
+    }
+  }
+  console.error("    npm install -g @vibecodr/cli");
+  console.error("");
+  console.error("  If the rm or Remove-Item fails with EPERM/locked-file errors, close");
+  console.error("  any IDE / terminal that has run vibecodr, vibecodr-mcp, or vc-tools");
+  console.error("  recently (the OS may still hold handles on the shim files), then");
+  console.error("  retry.");
+  console.error("");
+  console.error("  Advanced opt-out (not recommended): set VIBECDR_SKIP_PREINSTALL_CHECK=1");
+  console.error("  and retry. The shim collision still trips an EEXIST inside npm; the");
+  console.error("  env var only silences this preflight check.");
+  console.error("");
+  console.error("==========================================================================");
+  console.error("");
+}