claude-use 2.1.0 → 2.2.0

package/README.md

@@ -363,6 +363,14 @@ In both modes, *where* a toggle is written depends on `$PWD` at invocation time,
 
 `claude-use check` (below) shows you which of the three would apply before you commit to a change, if you're unsure.
 
+#### Which `claude-use` a bare command name resolves to
+
+`doctor`'s PATH-resolution check answers a question no other check does: is the `claude-use` your shell runs the same executable as the one producing this report? It scans PATH for the filename a bare `claude-use` would resolve to, using the same `findPathShadow` scan `shim enable` already uses for `claude`, and compares the first hit against the running executable's own PATH-visible location — collapsing the verdict back to a pass when both names turn out to be the same real file reached through a symlink.
+
+An earlier PATH entry winning is a **failure**, not a warning, because it invalidates the rest of the report rather than sitting alongside it: every other finding describes the binary that produced it, which in that state is not the binary your commands reach. The failure mode it exists to catch is entirely silent otherwise — a wrapper script or an abandoned install directory from an earlier channel keeps working at whatever version it was frozen at, so nothing looks broken until a config file written by the newer version trips the older one's own validation. That is not hypothetical: a hand-written wrapper from an earlier install channel, sitting ahead of `~/.local/bin` on PATH, kept re-execing a month-old binary whose copy of `IdentitySchema` predated the naming rule widening to allow `@` — so an `identity.json` a current claude-use had written was rejected outright, with nothing anywhere reporting that the running binary was not the installed one.
+
+The two softer verdicts are warnings rather than failures. The running executable's own directory not being on PATH at all is legitimate (an absolute-path invocation, or `npx`), and an enabled `claude` shim being shadowed still leaves the launcher reachable as `claude-use run`.
+
 ### Debugging: `claude-use check`
 
 `claude-use check [path] [--identity <name>]` resolves the full cascade for the given path (default `$PWD`) and identity (default the active one), and prints the result — every entry's resolved state, which layer decided it, and which condition (if any) was evaluated and how — without touching the farm or spawning `claude` at all. This is the primary way to answer "why is X shared/hidden here" without launching a session to find out. For any `history/projects/` glob override in scope, it also flags whenever the pattern's encoded form could plausibly match more than one real path (see [Pattern matching](#pattern-matching-against-claudeprojects)), rather than resolving that ambiguity silently.
@@ -375,7 +383,7 @@ It also runs three checks that don't depend on `path` at all, every time, so a r
 
 ### Debugging: `claude-use doctor`
 
-Where `claude-use check` resolves one directory+identity's cascade in detail, `claude-use doctor` audits the whole `~/.claude-use` config graph at once — identity/directory-agnostic, no arguments needed. It validates every identity's `identity.json`, every configuration profile's own `extends` chain (catching a missing profile name or a circular `extends` before a launch would), `directory-rules.json`, `config.json`, `categories.local.json`, and `active-identity`, each against its own Zod schema and cross-referenced against each other (an identity's `defaultConfigProfile`, a directory rule's `identity`/`configProfile`, actually pointing at something real) — plus whether a real Claude Code binary is discoverable at all, whether the `claude` command shim is enabled and its recorded location still exists, and the same ambient-credential check `check` runs. One malformed file is reported as its own failure rather than aborting the rest of the audit, and the command exits non-zero if anything failed — useful as a scriptable "is everything still consistent" gate, not just an interactive debugging aid.
+Where `claude-use check` resolves one directory+identity's cascade in detail, `claude-use doctor` audits the whole `~/.claude-use` config graph at once — identity/directory-agnostic, no arguments needed. It validates every identity's `identity.json`, every configuration profile's own `extends` chain (catching a missing profile name or a circular `extends` before a launch would), `directory-rules.json`, `config.json`, `categories.local.json`, and `active-identity`, each against its own Zod schema and cross-referenced against each other (an identity's `defaultConfigProfile`, a directory rule's `identity`/`configProfile`, actually pointing at something real) — plus whether a real Claude Code binary is discoverable at all, whether the `claude` command shim is enabled and its recorded location still exists, **which `claude-use` a bare command name actually resolves to** (below), and the same ambient-credential check `check` runs. One malformed file is reported as its own failure rather than aborting the rest of the audit, and the command exits non-zero if anything failed — useful as a scriptable "is everything still consistent" gate, not just an interactive debugging aid.
 
 ## Examples
 
@@ -490,7 +498,7 @@ src/
   directoryRules.ts       # `claude-use rules` subcommands
   configure.ts            # `claude-use configure` interactive picker (@clack/prompts)
   check.ts                # `claude-use check` dry-run inspector — cascade resolution, ambient-credential/Keychain/settings-secrets diagnostics — no farm writes, no spawn
-  doctor.ts                # `claude-use doctor` whole-tree audit — every identity/profile/extends-chain/directory-rules/config.json/categories.local.json/active-identity, aggregating rather than throwing on a broken file
+  doctor.ts                # `claude-use doctor` whole-tree audit — every identity/profile/extends-chain/directory-rules/config.json/categories.local.json/active-identity, plus which `claude-use` PATH actually resolves to, aggregating rather than throwing on a broken file
   claudeShim.ts            # `claude-use shim enable`/`disable` — the one explicit action that creates/removes a `claude`-named hardlink of the running executable; records claude-shim.json
   cli/
     parsers.ts            # shared CLI-flag parsing helpers (splitTopLevelCommas, parsePair, repeatable-flag collectors)
@@ -617,11 +625,11 @@ the resolver's cascade and materialisation logic is exactly the kind of thing th
 - Conditional entries with injectable/fake mtimes, a fake resolved branch, and a fake env snapshot (never real filesystem/git/environment state, so tests aren't time-dependent, git-dependent, or slow) — a `newerThan` condition including a fresh file and excluding a stale one under the same glob, a `branch` condition applying only on a matching branch, an `env` condition applying only when the right variable is set, and a conditionally-matched subtree always being materialised rather than symlinked
 - A materialised directory reconciling any real (non-symlink) children written since the last resync back into `~/.claude` before re-deciding, and collapsing back into a plain symlink once its split condition no longer holds
 
-`identityManager.ts`, `configProfiles.ts`, `directoryRules.ts`, and `configure.ts` stay thin adapters over the resolver, so most of their correctness rides on the resolver's own test coverage above. `launcher.ts` carries three separately-testable responsibilities of its own that aren't covered by the resolver's purity, and need their own coverage: translating a resolved `Map<path, boolean>` into real filesystem side effects (creating/removing symlinks, materialising/collapsing directories, diffing against the farm's prior state, the per-identity lock and atomic-swap behaviour from [Directory rules](#directory-rules)) against a fake/in-memory filesystem; invoking the real `claude` binary via an injected `spawn` function (argv/env construction, exit-code propagation), never a real subprocess in a unit test; and the ambient-credential guard — given a fake `process.env`, refusing to proceed when any of the six named variables is set and the active identity's `allowAmbientCredential` is unset/false, proceeding when it's true, and proceeding when `CLAUDE_USE_ALLOW_AMBIENT_CREDENTIAL=1` is set for that one call regardless of the identity's own setting.
+`identityManager.ts`, `configProfiles.ts`, `directoryRules.ts`, and `configure.ts` stay thin adapters over the resolver, so most of their correctness rides on the resolver's own test coverage above. The one exception is `listIdentities`, whose own tests cover a deliberate departure from the "throw a validation error and let it propagate" convention: an `identity.json` that is present but unreadable — malformed JSON, or valid JSON this version's `IdentitySchema` rejects — is reported as that one identity's own unreadable entry, so a single bad file never hides every *other* identity from `claude-use identity list` at the moment they most need to be visible. Only those two content-shaped failures are absorbed; a permission error still propagates. A wholly *absent* `identity.json` remains a silent skip rather than a problem, and both it and `doctor`'s own enumeration filter out directories whose name starts with `.`, since `IdentitySchema` requires an identity name to start with a letter or digit and a resync's own `.<identity>.scratch.<suffix>`/`.<identity>.previous.<suffix>` directories are therefore never identities to report on. `launcher.ts` carries three separately-testable responsibilities of its own that aren't covered by the resolver's purity, and need their own coverage: translating a resolved `Map<path, boolean>` into real filesystem side effects (creating/removing symlinks, materialising/collapsing directories, diffing against the farm's prior state, the per-identity lock and atomic-swap behaviour from [Directory rules](#directory-rules)) against a fake/in-memory filesystem; invoking the real `claude` binary via an injected `spawn` function (argv/env construction, exit-code propagation), never a real subprocess in a unit test; and the ambient-credential guard — given a fake `process.env`, refusing to proceed when any of the six named variables is set and the active identity's `allowAmbientCredential` is unset/false, proceeding when it's true, and proceeding when `CLAUDE_USE_ALLOW_AMBIENT_CREDENTIAL=1` is set for that one call regardless of the identity's own setting.
 
 `check.ts`'s three always-on diagnostics get their own tests too, independent of path/cascade resolution: the ambient-credential check against a fake `process.env` (same fixture as `launcher.ts`'s guard, since they share the same detection logic); the settings-secrets advisory against a fake settings.json with populated `env`/`hooks` fields, confirming it reports counts and key names only, never values; and — since Keychain access is real OS state, not something to fake — a manual/integration-only note that the Keychain-name lookup is exercised against a real `security` call in CI on macOS runners, not unit-tested with a mock.
 
-`doctor.ts` deliberately breaks the "throw a validation error and let it propagate" convention every other command file follows, since aggregating every check into one report — rather than aborting on the first broken file — is the whole point of the command. Its own tests cover this directly: every input (identities, configuration profiles, `directory-rules.json`, `config.json`, `categories.local.json`, `active-identity`) fed simultaneously malformed at once, asserting `runDoctor` still returns a full report with one `fail` finding per broken input rather than throwing, plus a genuine `extends` cycle correctly failing and a genuine diamond correctly not being mistaken for one. Its wiring layer sets `process.exitCode` rather than throwing or calling `process.exit()` when the report contains any failure — this is new to the codebase and not unit-tested, matching `registerCheckCommand`'s own I/O wiring being untested for the same reason.
+`doctor.ts` deliberately breaks the "throw a validation error and let it propagate" convention every other command file follows, since aggregating every check into one report — rather than aborting on the first broken file — is the whole point of the command. Its own tests cover this directly: every input (identities, configuration profiles, `directory-rules.json`, `config.json`, `categories.local.json`, `active-identity`) fed simultaneously malformed at once, asserting `runDoctor` still returns a full report with one `fail` finding per broken input rather than throwing, plus a genuine `extends` cycle correctly failing and a genuine diamond correctly not being mistaken for one. The PATH-resolution section gets its own coverage for each of its three verdicts at each of the two names it reports on (a shadowed `claude-use` failing and naming both paths, a not-on-PATH executable warning instead, and an enabled-but-shadowed `claude` shim warning rather than failing), alongside `refinePathShadow`'s own unit tests for the symlink case a directory comparison alone would misreport as a shadow of itself. Its wiring layer sets `process.exitCode` rather than throwing or calling `process.exit()` when the report contains any failure — this is new to the codebase and not unit-tested, matching `registerCheckCommand`'s own I/O wiring being untested for the same reason.
 
 `claudeShim.test.ts` follows `identityManager.test.ts`'s real-temp-directory convention (a fake "own executable" file standing in for the running `claude-use` binary), rather than `doctor.ts`'s pure-function style, since `enableClaudeShim`/`disableClaudeShim` are themselves real filesystem operations, not something to keep separate from a thin wiring layer. Coverage includes the version-drift case that motivates persisting `claude-shim.json` at all (the source file overwritten in place between two `shim enable` runs, proving the marker — not the inode — is what lets the second run refresh cleanly instead of refusing), a foreign file at the target being refused without `--force` and accepted with it, and the cross-device (`EXDEV`) copy-fallback path via a small injectable `LinkFs` seam (mirroring `config/store.ts`'s own `StoreFs`/`nodeStoreFs` pattern), since a real cross-filesystem rig isn't practical in CI. One test also reproduces Homebrew's actual layout (a symlink into a separate "Cellar" directory) to confirm the shim lands next to the symlink users invoke, not buried in the directory its realpath resolves to.
 

package/dist/cli.cjs

@@ -221874,7 +221874,7 @@ var categories_default_default = {
 // package.json
 var package_default = {
   name: "claude-use",
-  version: "2.1.0",
+  version: "2.2.0",
   description: "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   license: "Apache-2.0",
   author: "Joseph Mearman <joseph@mearman.co.uk>",
@@ -245804,18 +245804,33 @@ function readActiveIdentity(paths) {
   const raw = import_node_fs5.default.readFileSync(paths.activeIdentityFile, "utf8").trim();
   return raw === "" ? void 0 : raw;
 }
+function isIdentityDirectoryName(name) {
+  return !name.startsWith(".");
+}
+function readIdentityForListing(paths, name) {
+  try {
+    return readIdentity(paths, name);
+  } catch (error62) {
+    if (error62 instanceof ConfigValidationError || error62 instanceof SyntaxError) {
+      return { problem: error62.message.replace(/\s*\n\s*/g, " ") };
+    }
+    throw error62;
+  }
+}
 function listIdentities(paths) {
   if (!import_node_fs5.default.existsSync(paths.identitiesDir)) {
     return [];
   }
   const active = readActiveIdentity(paths);
-  const names = import_node_fs5.default.readdirSync(paths.identitiesDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  const names = import_node_fs5.default.readdirSync(paths.identitiesDir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && isIdentityDirectoryName(entry.name)).map((entry) => entry.name).sort();
   const result = [];
   for (const name of names) {
-    const identity = readIdentity(paths, name);
-    if (identity !== void 0) {
-      result.push({ name, identity, isActive: name === active });
+    const read = readIdentityForListing(paths, name);
+    if (read === void 0) {
+      continue;
     }
+    const isActive = name === active;
+    result.push("problem" in read ? { name, isActive, problem: read.problem } : { name, identity: read, isActive });
   }
   return result;
 }
@@ -245888,10 +245903,17 @@ function registerIdentityCommand(program2, paths) {
     }
     for (const entry of entries) {
       const marker = entry.isActive ? "* " : "  ";
+      if (entry.problem !== void 0) {
+        console.log(`${marker}${entry.name} [unreadable: ${entry.problem}]`);
+        continue;
+      }
       const defaultProfile = entry.identity.defaultConfigProfile !== void 0 ? ` (default profile: ${entry.identity.defaultConfigProfile})` : "";
       const ambient = entry.identity.allowAmbientCredential ? " [allows ambient credential]" : "";
       console.log(`${marker}${entry.name}${defaultProfile}${ambient}`);
     }
+    if (entries.some((entry) => entry.problem !== void 0)) {
+      console.log("\nRun `claude-use doctor` for the full detail on every unreadable entry.");
+    }
   });
   identity.command("set-default-profile <identity> <profile>").description("Set an identity's default configuration profile.").action(async (identityName, profileName) => {
     if (readProfile(paths, profileName) === void 0) {
@@ -246526,7 +246548,10 @@ var UnsupportedShimSourceError = class extends CliError {
   contentSourcePath;
 };
 function claudeTargetFilename(ownExecutablePath) {
-  return ownExecutablePath.toLowerCase().endsWith(".exe") ? "claude.exe" : "claude";
+  return commandFilename(ownExecutablePath, "claude");
+}
+function commandFilename(ownExecutablePath, commandName) {
+  return ownExecutablePath.toLowerCase().endsWith(".exe") ? `${commandName}.exe` : commandName;
 }
 function isInvokedAsClaude(invokedName) {
   return invokedName === "claude" || invokedName.toLowerCase() === "claude.exe";
@@ -246674,6 +246699,12 @@ function registerShimCommand(program2, paths) {
 // src/doctor.ts
 var import_node_fs8 = __toESM(require("node:fs"), 1);
 var import_node_path19 = __toESM(require("node:path"), 1);
+function refinePathShadow(status, ownExecutablePath, realpath) {
+  if (status.status !== "shadowed") {
+    return status;
+  }
+  return realpath(status.by) === realpath(ownExecutablePath) ? { status: "ok" } : status;
+}
 function validateJson(schema, input2) {
   if (input2.raw === void 0) {
     return { ok: false, message: `${input2.path} is missing.` };
@@ -246690,6 +246721,49 @@ function validateJson(schema, input2) {
   }
   return { ok: true, data: result.data };
 }
+function pushPathResolution(push, resolution) {
+  const ownDir = import_node_path19.default.dirname(resolution.ownExecutablePath);
+  switch (resolution.claudeUse.status) {
+    case "ok":
+      push("path-resolution", "pass", `\`claude-use\` on PATH resolves to this running executable, ${resolution.ownExecutablePath}.`, "claude-use");
+      break;
+    case "not-on-path":
+      push(
+        "path-resolution",
+        "warn",
+        `${ownDir} is not on PATH, so a bare \`claude-use\` does not reach ${resolution.ownExecutablePath}. Add it to PATH, or keep invoking this executable by its full path.`,
+        "claude-use"
+      );
+      break;
+    case "shadowed":
+      push(
+        "path-resolution",
+        "fail",
+        `\`claude-use\` on PATH resolves to ${resolution.claudeUse.by}, not this running executable, ${resolution.ownExecutablePath}. Every command you type runs that one instead, at whatever version it happens to be \u2014 including the checks in this report, which describe this executable. Remove ${resolution.claudeUse.by}, repoint it at ${resolution.ownExecutablePath}, or put ${ownDir} ahead of it on PATH.`,
+        "claude-use"
+      );
+      break;
+  }
+  if (resolution.claude === void 0) {
+    return;
+  }
+  switch (resolution.claude.status) {
+    case "ok":
+      push("path-resolution", "pass", "`claude` on PATH resolves to the enabled shim.", "claude");
+      break;
+    case "not-on-path":
+      push("path-resolution", "warn", "The enabled `claude` shim's directory is not on PATH \u2014 add it, or use `claude-use run` instead.", "claude");
+      break;
+    case "shadowed":
+      push(
+        "path-resolution",
+        "warn",
+        `\`claude\` on PATH resolves to ${resolution.claude.by}, not the enabled shim. Put the shim's directory ahead of it on PATH, or run \`claude-use shim disable\` if you meant to launch that one directly.`,
+        "claude"
+      );
+      break;
+  }
+}
 function runDoctor(params) {
   const findings = [];
   const push = (section, severity, message, subject) => {
@@ -246723,6 +246797,7 @@ function runDoctor(params) {
       `\`claude\` is enabled at ${params.claudeShim.state.targetPath} (${params.claudeShim.state.method}). If you've upgraded claude-use since, re-run \`claude-use shim enable\` to refresh it.`
     );
   }
+  pushPathResolution(push, params.pathResolution);
   const profileSources = /* @__PURE__ */ new Map();
   for (const entry of params.configProfiles) {
     const validated = validateJson(ConfigProfileSchema, entry);
@@ -246843,6 +246918,7 @@ var SECTION_TITLES = {
   "ambient-credential": "Ambient-credential exposure",
   "binary-discovery": "Claude Code binary discovery",
   "claude-shim": "`claude` command shim",
+  "path-resolution": "PATH resolution",
   "config-profile": "Configuration profiles",
   identity: "Identities",
   keychain: "macOS Keychain",
@@ -246855,6 +246931,7 @@ var SECTION_ORDER = [
   "ambient-credential",
   "binary-discovery",
   "claude-shim",
+  "path-resolution",
   "config-profile",
   "identity",
   "keychain",
@@ -246890,11 +246967,18 @@ function formatDoctorReport(report) {
   lines.push("", report.ok ? "All checks passed." : `${failCount} check(s) failed.`);
   return lines;
 }
+function realpathOrSelf(target) {
+  try {
+    return import_node_fs8.default.realpathSync(target);
+  } catch {
+    return target;
+  }
+}
 function registerDoctorCommand(program2, paths) {
   program2.command("doctor").description(
     "Audit the whole ~/.claude-use config graph -- every identity, every configuration profile's extends chain, directory-rules.json, config.json, categories.local.json, active-identity, and real Claude Code binary discoverability. Identity/directory-agnostic, unlike `check`."
   ).action(() => {
-    const identityNames = import_node_fs8.default.existsSync(paths.identitiesDir) ? import_node_fs8.default.readdirSync(paths.identitiesDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort() : [];
+    const identityNames = import_node_fs8.default.existsSync(paths.identitiesDir) ? import_node_fs8.default.readdirSync(paths.identitiesDir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && isIdentityDirectoryName(entry.name)).map((entry) => entry.name).sort() : [];
     const identities = identityNames.map((name) => {
       const farmRoot = import_node_path19.default.join(paths.identitiesDir, name);
       const identityPath = import_node_path19.default.join(farmRoot, "identity.json");
@@ -246914,6 +246998,17 @@ function registerDoctorCommand(program2, paths) {
       binaryDiscovery = { ok: false, message: error62 instanceof Error ? error62.message : String(error62) };
     }
     const shimState = readJson(paths.claudeShimFile, ClaudeShimStateSchema);
+    const pathDirs = (process.env.PATH ?? "").split(import_node_path19.default.delimiter).filter((dir) => dir !== "");
+    const claudeShimShadow = shimState === void 0 ? void 0 : refinePathShadow(
+      findPathShadow({
+        pathDirs,
+        targetDir: import_node_path19.default.dirname(shimState.targetPath),
+        targetFilename: import_node_path19.default.basename(shimState.targetPath),
+        findExecutableInDir
+      }),
+      shimState.targetPath,
+      realpathOrSelf
+    );
     const report = runDoctor({
       env: process.env,
       identities,
@@ -246924,6 +247019,20 @@ function registerDoctorCommand(program2, paths) {
       activeIdentity: { path: paths.activeIdentityFile, raw: realFsPort.readFileUtf8(paths.activeIdentityFile) },
       binaryDiscovery,
       claudeShim: { state: shimState, targetExists: shimState !== void 0 && import_node_fs8.default.existsSync(shimState.targetPath) },
+      pathResolution: {
+        ownExecutablePath,
+        claudeUse: refinePathShadow(
+          findPathShadow({
+            pathDirs,
+            targetDir: import_node_path19.default.dirname(ownExecutablePath),
+            targetFilename: commandFilename(ownExecutablePath, "claude-use"),
+            findExecutableInDir
+          }),
+          ownExecutablePath,
+          realpathOrSelf
+        ),
+        ...claudeShimShadow === void 0 ? {} : { claude: claudeShimShadow }
+      },
       run: realRunPort,
       platform: process.platform
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-use",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   "license": "Apache-2.0",
   "author": "Joseph Mearman <joseph@mearman.co.uk>",