gitnexus 1.6.3-rc.30 → 1.6.3-rc.31

package/dist/cli/clean.js

@@ -5,7 +5,7 @@
  * Also unregisters it from the global registry.
  */
 import fs from 'fs/promises';
-import { findRepo, unregisterRepo, listRegisteredRepos } from '../storage/repo-manager.js';
+import { findRepo, unregisterRepo, listRegisteredRepos, assertSafeStoragePath, UnsafeStoragePathError, } from '../storage/repo-manager.js';
 export const cleanCommand = async (options) => {
     // --all flag: clean all indexed repos
     if (options?.all) {
@@ -24,6 +24,24 @@ export const cleanCommand = async (options) => {
         }
         const entries = await listRegisteredRepos();
         for (const entry of entries) {
+            // Safety guard (#1003 review — @magyargergo): same rationale as
+            // remove.ts. `~/.gitnexus/registry.json` is user-writable, so a
+            // corrupted or hand-edited entry could point storagePath at the
+            // repo root, an empty string, or anywhere else — and
+            // fs.rm(recursive: true) on any of those would be catastrophic.
+            // Skip poisoned entries without touching disk, but keep going
+            // through the rest of the registry (preserves the existing
+            // per-repo error-tolerance semantics of `clean --all`).
+            try {
+                assertSafeStoragePath(entry);
+            }
+            catch (err) {
+                if (err instanceof UnsafeStoragePathError) {
+                    console.error(`Refusing to clean ${entry.name}: ${err.message}`);
+                    continue;
+                }
+                throw err;
+            }
             try {
                 await fs.rm(entry.storagePath, { recursive: true, force: true });
                 await unregisterRepo(entry.path);

package/dist/cli/index.js

@@ -59,6 +59,12 @@ program
     .option('-f, --force', 'Skip confirmation prompt')
     .option('--all', 'Clean all indexed repos')
     .action(createLazyAction(() => import('./clean.js'), 'cleanCommand'));
+program
+    .command('remove <target>')
+    .description('Delete the GitNexus index for a registered repo (by alias, name, or absolute path). ' +
+    'Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.')
+    .option('-f, --force', 'Skip confirmation prompt')
+    .action(createLazyAction(() => import('./remove.js'), 'removeCommand'));
 program
     .command('wiki [path]')
     .description('Generate repository wiki from knowledge graph')

package/dist/cli/remove.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Remove Command (#664)
+ *
+ * Delete the `.gitnexus/` index for a registered repo and unregister it
+ * from the global registry (~/.gitnexus/registry.json). The target is
+ * identified by alias / basename-derived name / remote-inferred name /
+ * absolute path — no `--repo` flag, just a positional argument so the
+ * destructive-command ergonomics match `clean` (which is also
+ * destructive but scoped to `process.cwd()`).
+ *
+ * Compared to `clean`:
+ *   - `clean`  acts on the repo discovered by walking up from cwd.
+ *   - `remove` acts on any registered repo identified by name or path.
+ *
+ * Behaviour notes:
+ *   - Idempotent on unknown targets: exits 0 with a warning so that
+ *     `remove X && analyze Y` keeps working in scripts. Per #664:
+ *     "behave atomically and idempotently so retries are safe".
+ *   - Atomic order mirrors `clean`: fs.rm FIRST, then unregister. A
+ *     partial failure leaves the registry pointing at a missing dir
+ *     (recoverable by `listRegisteredRepos({ validate: true })` on
+ *     next read) rather than the opposite, which would orphan
+ *     .gitnexus/ directories on disk.
+ *   - `-f` / `--force` matches the confirmation-skip semantics of
+ *     `clean -f`. (Distinct from `analyze --force`, which re-indexes;
+ *     here there is no pipeline, so no conflation.)
+ */
+export declare const removeCommand: (target: string, options?: {
+    force?: boolean;
+}) => Promise<void>;

package/dist/cli/remove.js

@@ -0,0 +1,99 @@
+/**
+ * Remove Command (#664)
+ *
+ * Delete the `.gitnexus/` index for a registered repo and unregister it
+ * from the global registry (~/.gitnexus/registry.json). The target is
+ * identified by alias / basename-derived name / remote-inferred name /
+ * absolute path — no `--repo` flag, just a positional argument so the
+ * destructive-command ergonomics match `clean` (which is also
+ * destructive but scoped to `process.cwd()`).
+ *
+ * Compared to `clean`:
+ *   - `clean`  acts on the repo discovered by walking up from cwd.
+ *   - `remove` acts on any registered repo identified by name or path.
+ *
+ * Behaviour notes:
+ *   - Idempotent on unknown targets: exits 0 with a warning so that
+ *     `remove X && analyze Y` keeps working in scripts. Per #664:
+ *     "behave atomically and idempotently so retries are safe".
+ *   - Atomic order mirrors `clean`: fs.rm FIRST, then unregister. A
+ *     partial failure leaves the registry pointing at a missing dir
+ *     (recoverable by `listRegisteredRepos({ validate: true })` on
+ *     next read) rather than the opposite, which would orphan
+ *     .gitnexus/ directories on disk.
+ *   - `-f` / `--force` matches the confirmation-skip semantics of
+ *     `clean -f`. (Distinct from `analyze --force`, which re-indexes;
+ *     here there is no pipeline, so no conflation.)
+ */
+import fs from 'fs/promises';
+import { readRegistry, resolveRegistryEntry, assertSafeStoragePath, unregisterRepo, RegistryNotFoundError, RegistryAmbiguousTargetError, UnsafeStoragePathError, } from '../storage/repo-manager.js';
+export const removeCommand = async (target, options) => {
+    // Read the registry snapshot once and pass it to the resolver — this
+    // lets us render the "before" state in the dry-run path without a
+    // second disk read.
+    const entries = await readRegistry();
+    let entry;
+    try {
+        entry = resolveRegistryEntry(entries, target);
+    }
+    catch (err) {
+        if (err instanceof RegistryNotFoundError) {
+            // Idempotent: missing target is a no-op warning, not an error.
+            // The `availableNames` hint comes from the error itself so users
+            // can see what they might have meant.
+            console.warn(`Nothing to remove: ${err.message}`);
+            return;
+        }
+        if (err instanceof RegistryAmbiguousTargetError) {
+            // Duplicate aliases are allowed via --allow-duplicate-name (#829);
+            // refuse to guess which one the user meant — surface the full list
+            // and exit non-zero so scripts don't silently pick the wrong repo.
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    // Confirmation gate — same shape as `clean`. Default is a dry-run
+    // that describes what would be deleted; `--force` actually deletes.
+    if (!options?.force) {
+        console.log(`This will delete the GitNexus index for: ${entry.name}`);
+        console.log(`   Path:    ${entry.path}`);
+        console.log(`   Storage: ${entry.storagePath}`);
+        console.log('\nRun with --force to confirm deletion.');
+        return;
+    }
+    // Safety guard (#1003 review — @magyargergo): refuse to proceed if
+    // the registry entry's `storagePath` isn't the canonical
+    // `<entry.path>/.gitnexus` subfolder. `~/.gitnexus/registry.json` is
+    // user-writable, so a corrupted or hand-edited entry could point
+    // storagePath at the repo root, an empty string (→ cwd), a parent
+    // dir, or anywhere else; `fs.rm(recursive: true, force: true)` on
+    // any of those would be a runtime disaster. Bail before touching
+    // disk, with an actionable hint for recovering a broken registry.
+    try {
+        assertSafeStoragePath(entry);
+    }
+    catch (err) {
+        if (err instanceof UnsafeStoragePathError) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    // Deletion order: fs.rm first, then unregister. If fs.rm fails mid-way,
+    // the registry entry stays so the user can retry. If fs.rm succeeds but
+    // unregister throws (e.g. ENOSPC on registry write), the entry becomes
+    // orphaned — `listRegisteredRepos({ validate: true })` prunes those on
+    // next read, so the failure is self-healing.
+    try {
+        await fs.rm(entry.storagePath, { recursive: true, force: true });
+        await unregisterRepo(entry.path);
+        console.log(`Removed: ${entry.name}`);
+        console.log(`   Path:    ${entry.path}`);
+        console.log(`   Storage: ${entry.storagePath}`);
+    }
+    catch (err) {
+        console.error(`Failed to remove ${entry.name}:`, err);
+        process.exit(1);
+    }
+};

package/dist/core/group/cross-impact.js

@@ -283,24 +283,13 @@ export async function runGroupImpact(deps, params) {
     }
     const localObj = local;
     if (localObj?.error && typeof localObj.error === 'string') {
-        const empty = {
-            local,
-            group: name,
-            cross: [],
-            outOfScope: [],
-            truncated: false,
-            truncatedRepos: [],
-            summary: {
-                direct: 0,
-                processes_affected: 0,
-                modules_affected: 0,
-                cross_repo_hits: 0,
-            },
-            risk: 'UNKNOWN',
-            timeoutMs,
-            crossDepthWarning,
-        };
-        return empty;
+        // Fail closed: the local-impact phase errored (missing symbol, graph-load
+        // failure, thrown exception wrapped by safeLocalImpact, or port-returned
+        // `{ error }`). Do NOT wrap it into a zero-hit success payload — callers
+        // branch on top-level `error`, and a blast-radius tool reporting "no
+        // impact" on the failure path is a false negative on a safety-critical
+        // signal. Bubble the error so consumers treat it as a failure.
+        return { error: `Local impact failed for ${repoPath}: ${localObj.error}` };
     }
     if (servicePrefix) {
         const tf = localObj?.target?.filePath;

package/dist/storage/repo-manager.d.ts

@@ -5,6 +5,37 @@
  * Also maintains a global registry at ~/.gitnexus/registry.json
  * so the MCP server can discover indexed repos from any cwd.
  */
+/**
+ * Normalise a repo path for registry comparison across platforms
+ * (#664 review feedback from @evander-wang).
+ *
+ * Why this exists: `path.resolve` alone is NOT enough for
+ * cross-platform registry stability.
+ *   - **macOS**: tmpdirs and `/var` are symlinks to `/private/var`.
+ *     A child process that stored `/private/var/folders/.../repo` in
+ *     the registry cannot later be matched by an outer caller that
+ *     supplies the symlink form `/var/folders/.../repo`. `path.resolve`
+ *     does not follow symlinks; `realpathSync.native` does.
+ *   - **Windows**: GitHub runners surface tmpdirs in 8.3 short-name
+ *     form (`RUNNERA~1\...`), but `process.cwd()` often returns the
+ *     long form (`runneradmin\...`). `realpathSync.native` normalises
+ *     both sides to the long-name canonical path.
+ *
+ * Fallback behaviour: if the path does not exist on disk (e.g. a user
+ * passed `gitnexus remove some-alias` and the alias misses every
+ * registry entry, or the caller is resolving a path that was deleted
+ * after registration), we return `path.resolve(p)` rather than
+ * throwing. This preserves the idempotent-on-missing semantics of
+ * `resolveRegistryEntry` / `remove`.
+ *
+ * Backwards compatibility: this function is applied to BOTH the
+ * caller-supplied input AND each stored `entry.path` at compare time
+ * inside `resolveRegistryEntry`, so registries written by older
+ * versions (where `registerRepo` only ran `path.resolve`) still match
+ * correctly. Newly-written entries are canonicalised at write time too
+ * so the registry stabilises over analyze/re-analyze cycles.
+ */
+export declare const canonicalizePath: (p: string) => string;
 export interface RepoMeta {
     repoPath: string;
     lastCommit: string;
@@ -181,6 +212,108 @@ export declare const registerRepo: (repoPath: string, meta: RepoMeta, opts?: Reg
  * Called after `gitnexus clean`.
  */
 export declare const unregisterRepo: (repoPath: string) => Promise<void>;
+/**
+ * Thrown by {@link resolveRegistryEntry} when no registered repo matches
+ * the caller's target string (by alias, basename, remote-inferred name,
+ * or resolved path). CLI callers that want idempotent "remove" semantics
+ * should catch this and exit 0 with a warning; non-idempotent callers
+ * (e.g. MCP tools) can surface the error directly.
+ */
+export declare class RegistryNotFoundError extends Error {
+    readonly target: string;
+    readonly availableNames: string[];
+    readonly kind: "RegistryNotFoundError";
+    constructor(target: string, availableNames: string[]);
+}
+/**
+ * Thrown by {@link resolveRegistryEntry} when the target string matches
+ * the `name` of two or more entries — only possible when the user
+ * previously registered duplicates via `analyze --name X
+ * --allow-duplicate-name` (#829). The error carries enough information
+ * for the caller to render an actionable disambiguation hint without
+ * string-matching on `.message`.
+ *
+ * `kind` is a string literal discriminant (same pattern as
+ * {@link RegistryNameCollisionError}) so callers can narrow via
+ * `err.kind === 'RegistryAmbiguousTargetError'` without importing the
+ * class.
+ */
+export declare class RegistryAmbiguousTargetError extends Error {
+    readonly target: string;
+    readonly matches: RegistryEntry[];
+    readonly kind: "RegistryAmbiguousTargetError";
+    constructor(target: string, matches: RegistryEntry[]);
+}
+/**
+ * Thrown by {@link assertSafeStoragePath} when a registry entry's
+ * `storagePath` does NOT point at the expected `<entry.path>/.gitnexus`
+ * subfolder. CLI destructive commands (`remove`, `clean --all`) should
+ * catch this and exit non-zero without deleting anything — the usual
+ * cause is a corrupted or hand-edited `~/.gitnexus/registry.json`, and
+ * proceeding would mean `fs.rm(recursive: true)` on whatever odd path
+ * the entry is pointing at.
+ */
+export declare class UnsafeStoragePathError extends Error {
+    readonly entry: RegistryEntry;
+    readonly expectedStoragePath: string;
+    readonly actualStoragePath: string;
+    readonly kind: "UnsafeStoragePathError";
+    constructor(entry: RegistryEntry, expectedStoragePath: string, actualStoragePath: string);
+}
+/**
+ * Guard rail for destructive CLI paths (`remove` #664,
+ * `clean --all` #258, future MCP `remove` tool): verify that a
+ * registry entry's `storagePath` is the canonical `<repo>/.gitnexus`
+ * subfolder of its `path`. If not, throw {@link UnsafeStoragePathError}
+ * so the caller exits without touching disk.
+ *
+ * Why this exists (#1003 review — @magyargergo):
+ *   - `~/.gitnexus/registry.json` is a plain-text user-writable file.
+ *     A corrupted, hand-edited, or downgrade/upgrade-racing entry
+ *     could plausibly end up with `storagePath === ""` (resolves to
+ *     cwd), `storagePath === path` (the repo root!), `storagePath`
+ *     equal to a parent/sibling of the repo, or simply any arbitrary
+ *     filesystem path.
+ *   - `fs.rm(recursive: true, force: true)` on ANY of those would be
+ *     a runtime disaster — at best delete the user's working tree, at
+ *     worst nuke an unrelated directory tree they happen to own.
+ *   - `clean` (default, cwd-scoped) is safe by construction — it
+ *     re-derives storagePath from `findRepo(cwd)` and never trusts
+ *     the registry field. But `clean --all` DOES iterate the registry
+ *     and trust each entry's stored storagePath (same shape as
+ *     `remove`), so this helper must be wired into that loop too.
+ *   - `server/api.ts` recomputes storagePath from `getStoragePath(entry.path)`
+ *     and so is likewise safe-by-construction.
+ *
+ * Pure string check — does NOT require the paths to exist on disk.
+ * Windows: case-insensitive; POSIX: case-sensitive. Matches the
+ * comparison shape used elsewhere in this module.
+ */
+export declare const assertSafeStoragePath: (entry: RegistryEntry) => void;
+/**
+ * Resolve a user-supplied target string (from `gitnexus remove <target>`
+ * or equivalent MCP tool argument) to a single registry entry.
+ *
+ * Match precedence (first hit wins, subsequent tiers are only tried if
+ * the prior tier produces zero matches):
+ *   1. Exact resolved-path match (Windows: case-insensitive).
+ *      Paths are unique by registry construction, so a path match can
+ *      never be ambiguous.
+ *   2. Exact `name` match (case-insensitive). If ≥ 2 entries share the
+ *      name — only possible via `--allow-duplicate-name` (#829) —
+ *      throws {@link RegistryAmbiguousTargetError}.
+ *
+ * No fuzzy / partial matching — unambiguous, scriptable behaviour is
+ * more important than convenience for destructive commands.
+ *
+ * Throws {@link RegistryNotFoundError} if no entry matches.
+ *
+ * `entries` is passed in (rather than re-read) so callers that already
+ * hold the registry snapshot (e.g. to print a "before" state) can avoid
+ * a second disk read, and so tests can inject fixtures without touching
+ * `GITNEXUS_HOME`.
+ */
+export declare const resolveRegistryEntry: (entries: RegistryEntry[], target: string) => RegistryEntry;
 /**
  * List all registered repos from the global registry.
  * Optionally validates that each entry's .gitnexus/ still exists.

package/dist/storage/repo-manager.js

@@ -6,9 +6,49 @@
  * so the MCP server can discover indexed repos from any cwd.
  */
 import fs from 'fs/promises';
+import { realpathSync } from 'fs';
 import path from 'path';
 import os from 'os';
 import { getInferredRepoName } from './git.js';
+/**
+ * Normalise a repo path for registry comparison across platforms
+ * (#664 review feedback from @evander-wang).
+ *
+ * Why this exists: `path.resolve` alone is NOT enough for
+ * cross-platform registry stability.
+ *   - **macOS**: tmpdirs and `/var` are symlinks to `/private/var`.
+ *     A child process that stored `/private/var/folders/.../repo` in
+ *     the registry cannot later be matched by an outer caller that
+ *     supplies the symlink form `/var/folders/.../repo`. `path.resolve`
+ *     does not follow symlinks; `realpathSync.native` does.
+ *   - **Windows**: GitHub runners surface tmpdirs in 8.3 short-name
+ *     form (`RUNNERA~1\...`), but `process.cwd()` often returns the
+ *     long form (`runneradmin\...`). `realpathSync.native` normalises
+ *     both sides to the long-name canonical path.
+ *
+ * Fallback behaviour: if the path does not exist on disk (e.g. a user
+ * passed `gitnexus remove some-alias` and the alias misses every
+ * registry entry, or the caller is resolving a path that was deleted
+ * after registration), we return `path.resolve(p)` rather than
+ * throwing. This preserves the idempotent-on-missing semantics of
+ * `resolveRegistryEntry` / `remove`.
+ *
+ * Backwards compatibility: this function is applied to BOTH the
+ * caller-supplied input AND each stored `entry.path` at compare time
+ * inside `resolveRegistryEntry`, so registries written by older
+ * versions (where `registerRepo` only ran `path.resolve`) still match
+ * correctly. Newly-written entries are canonicalised at write time too
+ * so the registry stabilises over analyze/re-analyze cycles.
+ */
+export const canonicalizePath = (p) => {
+    const resolved = path.resolve(p);
+    try {
+        return realpathSync.native(resolved);
+    }
+    catch {
+        return resolved;
+    }
+};
 const GITNEXUS_DIR = '.gitnexus';
 // ─── Local Storage Helpers ─────────────────────────────────────────────
 /**
@@ -265,12 +305,31 @@ const hasCustomAlias = (entry, inferredName) => {
  * MCP-visible repo name (#979).
  */
 export const registerRepo = async (repoPath, meta, opts) => {
+    // Preserve the caller's chosen path form in the registry — don't
+    // canonicalise at write time. This matters for two reasons:
+    //   1. `list` and error messages show the path the user actually
+    //      knows (e.g. the 8.3 short form they typed), not a runtime-
+    //      resolved long form they've never seen.
+    //   2. Keeps pre-existing #829 test assertions that compare
+    //      `err.existingPath` against `path.resolve(tmpPath)` stable.
+    // Canonicalisation is applied at COMPARE points only (see below),
+    // which is where the cross-platform divergence actually matters.
     const resolved = path.resolve(repoPath);
     const { storagePath } = getStoragePaths(resolved);
+    // Canonical form used strictly for comparison — `realpathSync.native`
+    // expands macOS /var → /private/var and Windows 8.3 → long-name,
+    // falling back to `path.resolve` when the path doesn't exist.
+    const canonicalInput = canonicalizePath(repoPath);
     const entries = await readRegistry();
     const existingIdx = entries.findIndex((e) => {
-        const a = path.resolve(e.path);
-        const b = resolved;
+        // Canonicalise the STORED entry too so pre-canonicalisation
+        // registries (written by older versions, or paths passed in a
+        // different form) still match correctly. `canonicalizePath` falls
+        // back to `path.resolve` when the path no longer exists on disk,
+        // so stale entries that have been rm'd externally still resolve
+        // to a stable key instead of throwing.
+        const a = canonicalizePath(e.path);
+        const b = canonicalInput;
         return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
     });
     const existing = existingIdx >= 0 ? entries[existingIdx] : null;
@@ -304,9 +363,12 @@ export const registerRepo = async (repoPath, meta, opts) => {
     // messages and list output #829 ships).
     const explicitName = opts?.name !== undefined || isPreservedAlias;
     if (explicitName && !opts?.allowDuplicateName) {
+        // Compare canonical-vs-canonical here too so `/var/foo` and
+        // `/private/var/foo` (same repo, different form) aren't treated as
+        // two colliding paths.
         const collidingEntry = entries.find((e, i) => i !== existingIdx &&
             e.name.toLowerCase() === name.toLowerCase() &&
-            path.resolve(e.path) !== resolved);
+            canonicalizePath(e.path) !== canonicalInput);
         if (collidingEntry) {
             throw new RegistryNameCollisionError(name, collidingEntry.path, resolved);
         }
@@ -333,11 +395,193 @@ export const registerRepo = async (repoPath, meta, opts) => {
  * Called after `gitnexus clean`.
  */
 export const unregisterRepo = async (repoPath) => {
-    const resolved = path.resolve(repoPath);
+    // Canonicalise BOTH sides so an unregister call issued with the
+    // symlink form (`/var/folders/.../repo`) still matches an entry
+    // written with the realpath form (`/private/var/folders/.../repo`),
+    // and vice versa. Matches the semantics of `registerRepo` and
+    // `resolveRegistryEntry` post-#1003 review.
+    const resolved = canonicalizePath(repoPath);
     const entries = await readRegistry();
-    const filtered = entries.filter((e) => path.resolve(e.path) !== resolved);
+    const matches = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+    const filtered = entries.filter((e) => !matches(canonicalizePath(e.path), resolved));
     await writeRegistry(filtered);
 };
+/**
+ * Thrown by {@link resolveRegistryEntry} when no registered repo matches
+ * the caller's target string (by alias, basename, remote-inferred name,
+ * or resolved path). CLI callers that want idempotent "remove" semantics
+ * should catch this and exit 0 with a warning; non-idempotent callers
+ * (e.g. MCP tools) can surface the error directly.
+ */
+export class RegistryNotFoundError extends Error {
+    target;
+    availableNames;
+    kind = 'RegistryNotFoundError';
+    constructor(target, availableNames) {
+        const hint = availableNames.length > 0
+            ? ` Available: ${availableNames.join(', ')}.`
+            : ' No repositories are currently registered.';
+        super(`No registered repo matches "${target}".${hint}`);
+        this.target = target;
+        this.availableNames = availableNames;
+        this.name = 'RegistryNotFoundError';
+    }
+}
+/**
+ * Thrown by {@link resolveRegistryEntry} when the target string matches
+ * the `name` of two or more entries — only possible when the user
+ * previously registered duplicates via `analyze --name X
+ * --allow-duplicate-name` (#829). The error carries enough information
+ * for the caller to render an actionable disambiguation hint without
+ * string-matching on `.message`.
+ *
+ * `kind` is a string literal discriminant (same pattern as
+ * {@link RegistryNameCollisionError}) so callers can narrow via
+ * `err.kind === 'RegistryAmbiguousTargetError'` without importing the
+ * class.
+ */
+export class RegistryAmbiguousTargetError extends Error {
+    target;
+    matches;
+    kind = 'RegistryAmbiguousTargetError';
+    constructor(target, matches) {
+        const listing = matches.map((m) => `  - ${m.name}  (${m.path})`).join('\n');
+        super(`Multiple registered repos match "${target}":\n${listing}\n` +
+            `Pass the absolute path instead to disambiguate.`);
+        this.target = target;
+        this.matches = matches;
+        this.name = 'RegistryAmbiguousTargetError';
+    }
+}
+/**
+ * Thrown by {@link assertSafeStoragePath} when a registry entry's
+ * `storagePath` does NOT point at the expected `<entry.path>/.gitnexus`
+ * subfolder. CLI destructive commands (`remove`, `clean --all`) should
+ * catch this and exit non-zero without deleting anything — the usual
+ * cause is a corrupted or hand-edited `~/.gitnexus/registry.json`, and
+ * proceeding would mean `fs.rm(recursive: true)` on whatever odd path
+ * the entry is pointing at.
+ */
+export class UnsafeStoragePathError extends Error {
+    entry;
+    expectedStoragePath;
+    actualStoragePath;
+    kind = 'UnsafeStoragePathError';
+    constructor(entry, expectedStoragePath, actualStoragePath) {
+        super(`Refusing to remove storage path for safety: expected ` +
+            `"${expectedStoragePath}" under the repo's .gitnexus subfolder, ` +
+            `but the registry entry has "${actualStoragePath}". ` +
+            `This usually means the registry entry is corrupted or was ` +
+            `hand-edited. Delete the entry manually from ~/.gitnexus/registry.json ` +
+            `and re-run analyze.`);
+        this.entry = entry;
+        this.expectedStoragePath = expectedStoragePath;
+        this.actualStoragePath = actualStoragePath;
+        this.name = 'UnsafeStoragePathError';
+    }
+}
+/**
+ * Guard rail for destructive CLI paths (`remove` #664,
+ * `clean --all` #258, future MCP `remove` tool): verify that a
+ * registry entry's `storagePath` is the canonical `<repo>/.gitnexus`
+ * subfolder of its `path`. If not, throw {@link UnsafeStoragePathError}
+ * so the caller exits without touching disk.
+ *
+ * Why this exists (#1003 review — @magyargergo):
+ *   - `~/.gitnexus/registry.json` is a plain-text user-writable file.
+ *     A corrupted, hand-edited, or downgrade/upgrade-racing entry
+ *     could plausibly end up with `storagePath === ""` (resolves to
+ *     cwd), `storagePath === path` (the repo root!), `storagePath`
+ *     equal to a parent/sibling of the repo, or simply any arbitrary
+ *     filesystem path.
+ *   - `fs.rm(recursive: true, force: true)` on ANY of those would be
+ *     a runtime disaster — at best delete the user's working tree, at
+ *     worst nuke an unrelated directory tree they happen to own.
+ *   - `clean` (default, cwd-scoped) is safe by construction — it
+ *     re-derives storagePath from `findRepo(cwd)` and never trusts
+ *     the registry field. But `clean --all` DOES iterate the registry
+ *     and trust each entry's stored storagePath (same shape as
+ *     `remove`), so this helper must be wired into that loop too.
+ *   - `server/api.ts` recomputes storagePath from `getStoragePath(entry.path)`
+ *     and so is likewise safe-by-construction.
+ *
+ * Pure string check — does NOT require the paths to exist on disk.
+ * Windows: case-insensitive; POSIX: case-sensitive. Matches the
+ * comparison shape used elsewhere in this module.
+ */
+export const assertSafeStoragePath = (entry) => {
+    const expected = path.join(path.resolve(entry.path), '.gitnexus');
+    const actual = path.resolve(entry.storagePath);
+    const matches = process.platform === 'win32'
+        ? expected.toLowerCase() === actual.toLowerCase()
+        : expected === actual;
+    if (!matches) {
+        throw new UnsafeStoragePathError(entry, expected, actual);
+    }
+};
+/**
+ * Resolve a user-supplied target string (from `gitnexus remove <target>`
+ * or equivalent MCP tool argument) to a single registry entry.
+ *
+ * Match precedence (first hit wins, subsequent tiers are only tried if
+ * the prior tier produces zero matches):
+ *   1. Exact resolved-path match (Windows: case-insensitive).
+ *      Paths are unique by registry construction, so a path match can
+ *      never be ambiguous.
+ *   2. Exact `name` match (case-insensitive). If ≥ 2 entries share the
+ *      name — only possible via `--allow-duplicate-name` (#829) —
+ *      throws {@link RegistryAmbiguousTargetError}.
+ *
+ * No fuzzy / partial matching — unambiguous, scriptable behaviour is
+ * more important than convenience for destructive commands.
+ *
+ * Throws {@link RegistryNotFoundError} if no entry matches.
+ *
+ * `entries` is passed in (rather than re-read) so callers that already
+ * hold the registry snapshot (e.g. to print a "before" state) can avoid
+ * a second disk read, and so tests can inject fixtures without touching
+ * `GITNEXUS_HOME`.
+ */
+export const resolveRegistryEntry = (entries, target) => {
+    // Tier 1: path match. Canonicalise BOTH sides so symlink and
+    // Windows-8.3 quirks don't cause a false miss — e.g. the caller
+    // passes `/var/folders/.../repo` while the registry has
+    // `/private/var/folders/.../repo` (both resolve to the same
+    // `realpath.native`). See `canonicalizePath` for the rationale.
+    //
+    // Canonicalising the STORED entry (not just the input) is what gives
+    // us backward-compat for registries written by versions that only
+    // ran `path.resolve` — both get canonicalised here at compare time.
+    const canonicalTarget = canonicalizePath(target);
+    const pathMatch = entries.find((e) => {
+        const a = canonicalizePath(e.path);
+        const b = canonicalTarget;
+        return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+    });
+    if (pathMatch)
+        return pathMatch;
+    // Tier 2: name match. Case-insensitive on all platforms — registry
+    // name collisions are already filtered case-insensitively in
+    // `registerRepo`, so "APP" vs "app" are considered the same key.
+    const targetLower = target.toLowerCase();
+    const nameMatches = entries.filter((e) => e.name.toLowerCase() === targetLower);
+    if (nameMatches.length === 1)
+        return nameMatches[0];
+    if (nameMatches.length > 1) {
+        throw new RegistryAmbiguousTargetError(target, nameMatches);
+    }
+    // Tier 3: miss. Build the available-names hint ONCE; resolveRepo-style
+    // disambiguated labels (`app (/path)`) are applied when the same name
+    // appears in multiple entries so the user sees the same hint shape as
+    // `-r <name>` errors.
+    const nameCounts = new Map();
+    for (const e of entries) {
+        const key = e.name.toLowerCase();
+        nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
+    }
+    const availableNames = entries.map((e) => (nameCounts.get(e.name.toLowerCase()) ?? 0) > 1 ? `${e.name} (${e.path})` : e.name);
+    throw new RegistryNotFoundError(target, availableNames);
+};
 /**
  * List all registered repos from the global registry.
  * Optionally validates that each entry's .gitnexus/ still exists.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.3-rc.30",
+  "version": "1.6.3-rc.31",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",