@aixle/insights 0.2.0 → 0.2.2-staging

package/dist/install/cursor.js

@@ -0,0 +1,193 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, copyFileSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { randomBytes } from "node:crypto";
+import { desiredAixleInsightsEntry, aixleInsightsEntryMatchesDesired } from "./claude.js";
+export function defaultCursorUserConfigPath() {
+    return join(homedir(), ".cursor", "mcp.json");
+}
+/**
+ * Legacy keys to clean up on install: "db90" (pre-rebrand) and "insights" (an
+ * earlier local-dev-only convention documented in scripts/reset-local-env.mjs,
+ * never the production installer's key — see DB90DV-560 orientation.md).
+ */
+const LEGACY_MCP_KEYS = ["db90", "insights"];
+const AIXLE_INSIGHTS_MCP_KEY = "aixle-insights";
+const BACKUP_SUFFIX = ".aixle-insights-backup";
+function readRootObject(path) {
+    if (!existsSync(path)) {
+        return {};
+    }
+    try {
+        const raw = readFileSync(path, "utf-8");
+        if (!raw.trim()) {
+            return {};
+        }
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return {
+                kind: "error",
+                message: `${path}: top-level JSON value must be an object.`,
+            };
+        }
+        return parsed;
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { kind: "error", message: `Cannot read ${path}: ${msg}` };
+    }
+}
+function atomicWriteJson(path, data) {
+    try {
+        const dir = dirname(path);
+        mkdirSync(dir, { recursive: true });
+        const serialized = `${JSON.stringify(data, null, 2)}\n`;
+        const tmpPath = join(dir, `.aixle-insights-cursor-json-${randomBytes(8).toString("hex")}.tmp`);
+        writeFileSync(tmpPath, serialized, "utf-8");
+        renameSync(tmpPath, path);
+        return { kind: "installed" };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { kind: "error", message: `Failed to write ${path}: ${msg}` };
+    }
+}
+/** Copy the current file to a backup path, unless a backup already exists (never clobber the user's original). */
+function backupIfNeeded(path) {
+    if (!existsSync(path))
+        return;
+    const backupPath = path + BACKUP_SUFFIX;
+    if (existsSync(backupPath))
+        return;
+    copyFileSync(path, backupPath);
+}
+/**
+ * Merges top-level `mcpServers.aixle-insights` into ~/.cursor/mcp.json (or overridden path).
+ * Preserves all other keys and MCP server entries. Backs up the existing file
+ * (once) before the first write, and removes legacy "db90"/"insights" keys so
+ * Cursor does not spawn duplicate aixle-insights servers.
+ */
+export function installCursorUserMcp(options = {}) {
+    const path = options.cursorConfigPath ?? defaultCursorUserConfigPath();
+    const force = options.force === true;
+    const desired = desiredAixleInsightsEntry();
+    const rootRead = readRootObject(path);
+    if ("kind" in rootRead && typeof rootRead.kind === "string" && rootRead.kind === "error") {
+        return rootRead;
+    }
+    const root = {
+        ...rootRead,
+    };
+    const rawServers = root["mcpServers"];
+    let mcpServers;
+    if (rawServers === undefined) {
+        mcpServers = {};
+    }
+    else if (typeof rawServers === "object" &&
+        rawServers !== null &&
+        !Array.isArray(rawServers)) {
+        mcpServers = { ...rawServers };
+    }
+    else {
+        return {
+            kind: "error",
+            message: `Invalid Cursor MCP config at ${path}: "mcpServers" must be an object when present.`,
+        };
+    }
+    const existing = mcpServers[AIXLE_INSIGHTS_MCP_KEY];
+    const hasLegacyKey = LEGACY_MCP_KEYS.some((k) => mcpServers[k] !== undefined);
+    if (existing !== undefined && aixleInsightsEntryMatchesDesired(existing, desired)) {
+        if (!hasLegacyKey) {
+            return { kind: "already-configured" };
+        }
+        backupIfNeeded(path);
+        for (const key of LEGACY_MCP_KEYS)
+            delete mcpServers[key];
+        root["mcpServers"] = mcpServers;
+        return atomicWriteJson(path, root);
+    }
+    if (existing !== undefined && !force) {
+        return {
+            kind: "requires-force",
+            detail: 'A different "aixle-insights" MCP server entry already exists in ~/.cursor/mcp.json. Re-run with `init --force` to replace only that entry.',
+        };
+    }
+    backupIfNeeded(path);
+    for (const key of LEGACY_MCP_KEYS)
+        delete mcpServers[key];
+    mcpServers[AIXLE_INSIGHTS_MCP_KEY] = { command: desired.command, args: desired.args };
+    root["mcpServers"] = mcpServers;
+    return atomicWriteJson(path, root);
+}
+/**
+ * Removes the aixle-insights entry from ~/.cursor/mcp.json without disturbing any
+ * other server entry — including ones the user or Cursor added after install.
+ * Works on the CURRENT file (never a full-file revert to the backup). If a
+ * pre-install backup exists, the user's ORIGINAL aixle-insights entry (if any)
+ * is restored from it; otherwise our key is simply removed. The backup file is
+ * cleaned up either way.
+ */
+export function uninstallCursorUserMcp(options = {}) {
+    const path = options.cursorConfigPath ?? defaultCursorUserConfigPath();
+    const backupPath = path + BACKUP_SUFFIX;
+    const hasBackup = existsSync(backupPath);
+    const cleanupBackup = () => {
+        if (hasBackup) {
+            try {
+                unlinkSync(backupPath);
+            }
+            catch {
+                /* non-fatal */
+            }
+        }
+    };
+    if (!existsSync(path)) {
+        cleanupBackup();
+        return { kind: "noop" };
+    }
+    const rootRead = readRootObject(path);
+    if ("kind" in rootRead && typeof rootRead.kind === "string" && rootRead.kind === "error") {
+        return rootRead;
+    }
+    const root = { ...rootRead };
+    const rawServers = root["mcpServers"];
+    if (typeof rawServers !== "object" || rawServers === null || Array.isArray(rawServers)) {
+        cleanupBackup();
+        return { kind: "noop" };
+    }
+    const mcpServers = { ...rawServers };
+    // If a backup exists, recover the user's ORIGINAL aixle-insights entry (if they
+    // had one we overwrote) rather than just deleting ours — but only that one key,
+    // leaving every current sibling entry intact.
+    let restoredPrior = false;
+    if (hasBackup) {
+        const backupRead = readRootObject(backupPath);
+        const backupIsObject = !("kind" in backupRead &&
+            typeof backupRead.kind === "string" &&
+            backupRead.kind === "error");
+        if (backupIsObject) {
+            const backupServers = backupRead["mcpServers"];
+            if (typeof backupServers === "object" && backupServers !== null && !Array.isArray(backupServers)) {
+                const priorEntry = backupServers[AIXLE_INSIGHTS_MCP_KEY];
+                if (priorEntry !== undefined) {
+                    mcpServers[AIXLE_INSIGHTS_MCP_KEY] = priorEntry;
+                    restoredPrior = true;
+                }
+            }
+        }
+    }
+    if (!restoredPrior) {
+        if (mcpServers[AIXLE_INSIGHTS_MCP_KEY] === undefined) {
+            cleanupBackup();
+            return { kind: "noop" };
+        }
+        delete mcpServers[AIXLE_INSIGHTS_MCP_KEY];
+    }
+    root["mcpServers"] = mcpServers;
+    const writeResult = atomicWriteJson(path, root);
+    if (writeResult.kind === "error") {
+        return writeResult;
+    }
+    cleanupBackup();
+    return restoredPrior ? { kind: "restored", backupPath } : { kind: "removed" };
+}

package/dist/install/index.d.ts

@@ -1,8 +1,10 @@
 import { type InstallClaudeUserMcpOptions, type InstallResult } from "./claude.js";
-export type SupportedEditor = "claude";
-export type { InstallClaudeUserMcpOptions, InstallResult };
+import { type InstallCursorUserMcpOptions, type UninstallResult } from "./cursor.js";
+export type SupportedEditor = "claude" | "cursor";
+export type { InstallClaudeUserMcpOptions, InstallCursorUserMcpOptions, InstallResult, UninstallResult, };
 /**
- * Editor dispatch for MCP install hooks. Only Claude Code is supported in this story.
+ * Editor dispatch for MCP install hooks.
  */
-export declare function installEditorMcp(editor: SupportedEditor, options?: InstallClaudeUserMcpOptions): InstallResult;
+export declare function installEditorMcp(editor: SupportedEditor, options?: InstallClaudeUserMcpOptions & InstallCursorUserMcpOptions): InstallResult;
 export { installClaudeUserMcp, defaultClaudeUserConfigPath, desiredAixleInsightsEntry, aixleInsightsEntryMatchesDesired, } from "./claude.js";
+export { installCursorUserMcp, uninstallCursorUserMcp, defaultCursorUserConfigPath, } from "./cursor.js";

package/dist/install/index.js

@@ -1,11 +1,16 @@
 import { installClaudeUserMcp, } from "./claude.js";
+import { installCursorUserMcp, } from "./cursor.js";
 /**
- * Editor dispatch for MCP install hooks. Only Claude Code is supported in this story.
+ * Editor dispatch for MCP install hooks.
  */
 export function installEditorMcp(editor, options = {}) {
     if (editor === "claude") {
         return installClaudeUserMcp(options);
     }
+    if (editor === "cursor") {
+        return installCursorUserMcp(options);
+    }
     return { kind: "error", message: `Unsupported editor for MCP install: ${String(editor)}` };
 }
 export { installClaudeUserMcp, defaultClaudeUserConfigPath, desiredAixleInsightsEntry, aixleInsightsEntryMatchesDesired, } from "./claude.js";
+export { installCursorUserMcp, uninstallCursorUserMcp, defaultCursorUserConfigPath, } from "./cursor.js";

package/dist/lib/client.d.ts

@@ -8,6 +8,13 @@ export interface IngestPayload {
     [key: string]: unknown;
 }
 export interface PostEventOptions {
+    /**
+     * Skip the HTTPS-or-loopback gate for this host. Only ever set this to
+     * `true` when the caller has independently confirmed the user explicitly
+     * consented via `init --insecure` for this exact credential (see
+     * `StoredCredentials.insecureHttpAllowed`). Defaults to `false`.
+     */
+    allowInsecureHttp?: boolean;
     /** Override default console.error on non-ok HTTP response. */
     onHttpError?: (status: number, statusText: string, body: string) => void;
     /** Override default console.error on network-level failure. */

package/dist/lib/client.js

@@ -1,3 +1,4 @@
+import { evaluateTransportSecurity } from "./transport-security.js";
 /**
  * POST a single event payload to the db90 ingest endpoint.
  *
@@ -10,6 +11,22 @@
  * Never throws — callers can rely on Promise.allSettled-style aggregation.
  */
 export async function postEvent(payload, host, token, options = {}) {
+    const transportSecurity = evaluateTransportSecurity(host, {
+        allowInsecureHttp: options.allowInsecureHttp === true,
+        label: "DB90 ingest host",
+    });
+    if (!transportSecurity.ok) {
+        // Deliberately does NOT call options.onNetworkError/onHttpError: the retry
+        // wrapper in src/client.ts treats those as transient and retries with
+        // backoff. A scheme rejection is permanent — retrying wastes ~21s per
+        // event for nothing. Bare console.error mirrors this file's existing
+        // unrecoverable-failure logging style.
+        console.error(`Blocked event send — ${transportSecurity.error}`);
+        return false;
+    }
+    if (transportSecurity.warning) {
+        console.error(`Warning: ${transportSecurity.warning}`);
+    }
     const url = `${host.replace(/\/$/, "")}/api/v1/ingest/events`;
     const headers = {
         "Content-Type": "application/json",

package/dist/lib/config.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { mcpLog } from "../log.js";
 /**
  * Load a connector's `config.json` from disk. Returns `{}` on missing or
  * malformed files — callers fall back to env vars / CLI flags / defaults.
@@ -32,8 +33,12 @@ export function loadBaseConfig(configDir, parsePricing) {
             return result;
         }
     }
-    catch {
-        // missing or invalid config — fall through
+    catch (err) {
+        const code = err?.code;
+        if (code !== "ENOENT") {
+            // Config file exists but failed to parse — distinguishes tampering from "never created".
+            mcpLog.warn("config_parse_failed", { path: configPath, error: err instanceof Error ? err.message : String(err) }, false);
+        }
     }
     return {};
 }

package/dist/lib/project-resolver.d.ts

@@ -6,8 +6,8 @@ export interface LookupResult {
     project_id: string;
     name: string;
 }
-export declare function resolveProjectId(flagValue: string | undefined, configValue: string | undefined, host: string, token: string, verbose: boolean): Promise<ProjectResolution>;
-export declare function resolveProjectIdForRepoPath(repoPath: string, host: string, token: string, verbose: boolean): Promise<ProjectResolution>;
+export declare function resolveProjectId(flagValue: string | undefined, configValue: string | undefined, host: string, token: string, verbose: boolean, allowInsecureHttp?: boolean): Promise<ProjectResolution>;
+export declare function resolveProjectIdForRepoPath(repoPath: string, host: string, token: string, verbose: boolean, allowInsecureHttp?: boolean): Promise<ProjectResolution>;
 export declare function getGitRemote(verbose: boolean): string | null;
 export declare function getGitRemoteForPath(repoPath: string, verbose: boolean): string | null;
 /**
@@ -24,7 +24,7 @@ export declare function canonicalizeGitRemote(remote: string, verbose: boolean):
  * git remote. Expand to remotes the API lookup understands (`Project.normalize_git_remote`).
  */
 export declare function repoNameToGitRemoteCandidates(repoName: string): string[];
-export declare function lookupProjectByRepoName(repoName: string, host: string, token: string, verbose: boolean): Promise<LookupResult | "not-found" | null>;
+export declare function lookupProjectByRepoName(repoName: string, host: string, token: string, verbose: boolean, allowInsecureHttp?: boolean): Promise<LookupResult | "not-found" | null>;
 /** Payload shape shared by db90-cursor and telemetry-mcp commit mappers. */
 export interface CommitAttributionPayload {
     event_type?: string;
@@ -44,5 +44,6 @@ export declare function enrichCommitProjectAttribution(payloads: CommitAttributi
     host: string;
     token: string;
     verbose?: boolean;
+    allowInsecureHttp?: boolean;
 }): Promise<void>;
-export declare function lookupProjectByRemote(gitRemote: string, host: string, token: string, verbose: boolean): Promise<LookupResult | "not-found" | null>;
+export declare function lookupProjectByRemote(gitRemote: string, host: string, token: string, verbose: boolean, allowInsecureHttp?: boolean): Promise<LookupResult | "not-found" | null>;

package/dist/lib/project-resolver.js

@@ -1,9 +1,12 @@
 import { execFileSync } from "node:child_process";
+import { evaluateTransportSecurity } from "./transport-security.js";
+import { isSafeSshHost } from "./spawn-arg-safety.js";
+import { safeGitRepoPath } from "./repo-path-safety.js";
 /** Coerce empty string to undefined so "" is treated as "not set" */
 function coerce(val) {
     return val === "" ? undefined : val;
 }
-export async function resolveProjectId(flagValue, configValue, host, token, verbose) {
+export async function resolveProjectId(flagValue, configValue, host, token, verbose, allowInsecureHttp = false) {
     const flag = coerce(flagValue);
     const config = coerce(configValue);
     if (flag !== undefined)
@@ -13,18 +16,18 @@ export async function resolveProjectId(flagValue, configValue, host, token, verb
     const gitRemote = getGitRemote(verbose);
     if (gitRemote === null)
         return { projectId: null, source: "none" };
-    const result = await lookupProjectByRemote(gitRemote, host, token, verbose);
+    const result = await lookupProjectByRemote(gitRemote, host, token, verbose, allowInsecureHttp);
     if (result === "not-found")
         return { projectId: null, source: "auto-detect-not-found" };
     if (result !== null)
         return { projectId: result.project_id, source: "auto-detect" };
     return { projectId: null, source: "none" };
 }
-export async function resolveProjectIdForRepoPath(repoPath, host, token, verbose) {
+export async function resolveProjectIdForRepoPath(repoPath, host, token, verbose, allowInsecureHttp = false) {
     const gitRemote = getGitRemoteForPath(repoPath, verbose);
     if (gitRemote === null)
         return { projectId: null, source: "none" };
-    const result = await lookupProjectByRemote(gitRemote, host, token, verbose);
+    const result = await lookupProjectByRemote(gitRemote, host, token, verbose, allowInsecureHttp);
     if (result === "not-found")
         return { projectId: null, source: "auto-detect-not-found" };
     if (result !== null)
@@ -47,8 +50,19 @@ export function getGitRemote(verbose) {
     }
 }
 export function getGitRemoteForPath(repoPath, verbose) {
+    // The spawn boundary. `repoPath` is untrusted (Cursor workspace.json, a
+    // composer uri.fsPath, a hook workspace_root, or a Claude transcript cwd), so
+    // it must resolve to a real directory before git reads its .git/config.
+    // Supersedes the isSafeSpawnPathArg check from DB90DV-546, which this
+    // subsumes. See DB90DV-547.
+    const safePath = safeGitRepoPath(repoPath);
+    if (safePath === null) {
+        if (verbose)
+            console.log(`[verbose] Refusing git for unsafe repo path: ${repoPath}`);
+        return null;
+    }
     try {
-        const out = execFileSync("git", ["-C", repoPath, "remote", "get-url", "origin"], {
+        const out = execFileSync("git", ["-C", safePath, "remote", "get-url", "origin"], {
             encoding: "utf-8",
             stdio: ["ignore", "pipe", "pipe"],
             timeout: 5000,
@@ -74,12 +88,21 @@ export function canonicalizeGitRemote(remote, verbose) {
     if (!trimmed)
         return remote;
     const scp = trimmed.match(/^([\w.-]+)@([^:/]+):(.+)$/);
+    /* eslint-disable-next-line security/detect-unsafe-regex -- Flagged only
+       because safe-regex counts `?` as a repetition. Every group is separated by
+       a literal delimiter (`@`, `:`, `/`) that its neighbours exclude, so there
+       is no backtracking ambiguity. Input is a git remote URL, bounded length. */
     const sshUrl = trimmed.match(/^ssh:\/\/(?:([\w.-]+)@)?([^:/]+)(?::\d+)?\/(.+)$/i);
     const host = scp?.[2] ?? sshUrl?.[2];
-    if (!host)
+    // An unvalidated host would be parsed by ssh as an option (DB90DV-546); an
+    // unvalidated `resolved` would be spliced back into the remote and sent to
+    // the lookup endpoint. Both fail open — the remote is returned unchanged.
+    if (!host || !isSafeSshHost(host))
         return trimmed;
     const resolved = resolveSshHostName(host, verbose);
-    if (!resolved || resolved.toLowerCase() === host.toLowerCase())
+    if (!resolved || !isSafeSshHost(resolved))
+        return trimmed;
+    if (resolved.toLowerCase() === host.toLowerCase())
         return trimmed;
     if (verbose)
         console.log(`[verbose] Resolved SSH host alias ${host} -> ${resolved}`);
@@ -89,6 +112,13 @@ export function canonicalizeGitRemote(remote, verbose) {
     return `ssh://${user}${resolved}/${sshUrl[3]}`;
 }
 function resolveSshHostName(host, verbose) {
+    // Defense in depth: the only caller already checks, but this function is the
+    // spawn boundary and must not depend on callers getting it right.
+    if (!isSafeSshHost(host)) {
+        if (verbose)
+            console.log(`[verbose] Refusing ssh -G for option-shaped host: ${host}`);
+        return null;
+    }
     try {
         const out = execFileSync("ssh", ["-G", host], {
             encoding: "utf-8",
@@ -128,12 +158,17 @@ export function repoNameToGitRemoteCandidates(repoName) {
     if (trimmed.includes("://") || trimmed.includes("@")) {
         return [trimmed];
     }
+    /* eslint-disable-next-line security/detect-unsafe-regex -- Star height 2
+       (`+` inside `(…)*`), but the inner group is prefixed by `/`, which is not
+       in [\w.-]. There is no ambiguous overlap, so matching stays linear. The
+       input is a short `owner/repo` slug that already failed the "://" and "@"
+       checks above. */
     if (/^[\w.-]+\/[\w.-]+(\/[\w.-]+)*$/.test(trimmed)) {
         return [`https://github.com/${trimmed}`, `git@github.com:${trimmed}.git`];
     }
     return [];
 }
-export async function lookupProjectByRepoName(repoName, host, token, verbose) {
+export async function lookupProjectByRepoName(repoName, host, token, verbose, allowInsecureHttp = false) {
     const candidates = repoNameToGitRemoteCandidates(repoName);
     if (candidates.length === 0) {
         if (verbose)
@@ -141,7 +176,7 @@ export async function lookupProjectByRepoName(repoName, host, token, verbose) {
         return "not-found";
     }
     for (const candidate of candidates) {
-        const result = await lookupProjectByRemote(candidate, host, token, verbose);
+        const result = await lookupProjectByRemote(candidate, host, token, verbose, allowInsecureHttp);
         if (result === "not-found")
             continue;
         return result;
@@ -164,7 +199,7 @@ export async function enrichCommitProjectAttribution(payloads, options) {
         const repoName = payload.metadata?.repo_name;
         if (!repoName)
             continue;
-        const result = await lookupProjectByRepoName(repoName, options.host, options.token, options.verbose ?? false);
+        const result = await lookupProjectByRepoName(repoName, options.host, options.token, options.verbose ?? false, options.allowInsecureHttp === true);
         if (result && typeof result === "object" && "project_id" in result) {
             payload.project_id = result.project_id;
             if (options.verbose) {
@@ -173,7 +208,18 @@ export async function enrichCommitProjectAttribution(payloads, options) {
         }
     }
 }
-export async function lookupProjectByRemote(gitRemote, host, token, verbose) {
+export async function lookupProjectByRemote(gitRemote, host, token, verbose, allowInsecureHttp = false) {
+    const transportSecurity = evaluateTransportSecurity(host, {
+        allowInsecureHttp,
+        label: "DB90 project-lookup host",
+    });
+    if (!transportSecurity.ok) {
+        console.error(`Blocked project lookup — ${transportSecurity.error}`);
+        return null;
+    }
+    if (transportSecurity.warning) {
+        console.error(`Warning: ${transportSecurity.warning}`);
+    }
     const url = `${host.replace(/\/$/, "")}/api/v1/projects/lookup?git_remote=${encodeURIComponent(gitRemote)}`;
     try {
         const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });

package/dist/lib/repo-path-safety.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Normalize an untrusted repo-path candidate. Pure — never touches the
+ * filesystem, so it is safe to call on every payload in a sync.
+ *
+ * Returns an absolute, `..`-collapsed path, or null when the value cannot be a
+ * legitimate workspace path. Rejecting relative values is deliberate: `git -C`
+ * would resolve a relative path against *this* process's cwd, which has nothing
+ * to do with where the value came from. It also rejects Cursor's literal
+ * `"unknown"` placeholder for global hook events.
+ */
+export declare function normalizeRepoPathCandidate(value: string | undefined | null): string | null;
+/**
+ * True when `candidate` is `root` itself or lives beneath it.
+ *
+ * Compares with a trailing `sep` so `/repos/project-evil` is not treated as
+ * inside `/repos/project`, and resolves symlinks so a link inside the root
+ * cannot point out of it.
+ *
+ * When either side does not exist, `realpathSync` throws and the normalized
+ * paths are compared instead. That loses nothing — a path that does not exist
+ * cannot be a symlink, and `resolve()` has already collapsed `..` — and it keeps
+ * containment usable for scope filtering, which legitimately runs against
+ * payload paths naming directories this machine no longer has.
+ */
+export declare function isRepoPathWithinRoot(candidate: string, root: string): boolean;
+/**
+ * The last check before `git -C <path>` runs. Requires the value to resolve to a
+ * real directory: a missing path, a dangling symlink, or a regular file is not a
+ * workspace. (Cursor's `metadata.workspace` is often the `state.vscdb` file
+ * itself, which git would only error on anyway.)
+ *
+ * Returns the canonical real path so `git` runs against exactly what was
+ * checked, narrowing the window between the check and the spawn.
+ */
+export declare function safeGitRepoPath(value: string | undefined | null): string | null;

package/dist/lib/repo-path-safety.js

@@ -0,0 +1,102 @@
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute, resolve, sep } from "node:path";
+import { isSafeSpawnPathArg } from "./spawn-arg-safety.js";
+/**
+ * Containment for untrusted filesystem paths that end up in `git -C <path>`.
+ *
+ * Every repo path this package resolves is untrusted text: Cursor's
+ * `workspace.json` `folder`, a composer's `workspaceIdentifier.uri.fsPath`, a
+ * hook's `workspace_roots[0]`, or a Claude transcript's `cwd`. None is validated
+ * by its producer — `fileUriToPath` (`readers/cursor.ts:189`) even passes a
+ * non-`file://` value straight through.
+ *
+ * `execFileSync` stops shell injection, but not `git -C ../../../elsewhere`: git
+ * would read that directory's `.git/config` and this package would ship the
+ * remote it found to the DB90 API. See DB90DV-547.
+ *
+ * Semantics are ported from `validatedRealPathWithinRoot`
+ * (`readers/cursor-sqlite.ts:23`), which already guards the Cursor SQLite
+ * reader the same way.
+ */
+function realPathOrNull(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Normalize an untrusted repo-path candidate. Pure — never touches the
+ * filesystem, so it is safe to call on every payload in a sync.
+ *
+ * Returns an absolute, `..`-collapsed path, or null when the value cannot be a
+ * legitimate workspace path. Rejecting relative values is deliberate: `git -C`
+ * would resolve a relative path against *this* process's cwd, which has nothing
+ * to do with where the value came from. It also rejects Cursor's literal
+ * `"unknown"` placeholder for global hook events.
+ */
+export function normalizeRepoPathCandidate(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    // Rejects empty, NUL-containing, and option-shaped values (DB90DV-546).
+    if (!isSafeSpawnPathArg(trimmed))
+        return null;
+    if (!isAbsolute(trimmed))
+        return null;
+    return resolve(trimmed);
+}
+/**
+ * True when `candidate` is `root` itself or lives beneath it.
+ *
+ * Compares with a trailing `sep` so `/repos/project-evil` is not treated as
+ * inside `/repos/project`, and resolves symlinks so a link inside the root
+ * cannot point out of it.
+ *
+ * When either side does not exist, `realpathSync` throws and the normalized
+ * paths are compared instead. That loses nothing — a path that does not exist
+ * cannot be a symlink, and `resolve()` has already collapsed `..` — and it keeps
+ * containment usable for scope filtering, which legitimately runs against
+ * payload paths naming directories this machine no longer has.
+ */
+export function isRepoPathWithinRoot(candidate, root) {
+    const normalizedCandidate = resolve(candidate);
+    const normalizedRoot = resolve(root);
+    const realCandidate = realPathOrNull(normalizedCandidate);
+    const realRoot = realPathOrNull(normalizedRoot);
+    // Compare like with like: mixing a realpath against a normalized path would
+    // false-negative on macOS, where /var is a symlink to /private/var.
+    const bothResolve = realCandidate !== null && realRoot !== null;
+    const left = bothResolve ? realCandidate : normalizedCandidate;
+    const right = bothResolve ? realRoot : normalizedRoot;
+    if (left === right)
+        return true;
+    const rootWithSep = right.endsWith(sep) ? right : `${right}${sep}`;
+    return left.startsWith(rootWithSep);
+}
+/**
+ * The last check before `git -C <path>` runs. Requires the value to resolve to a
+ * real directory: a missing path, a dangling symlink, or a regular file is not a
+ * workspace. (Cursor's `metadata.workspace` is often the `state.vscdb` file
+ * itself, which git would only error on anyway.)
+ *
+ * Returns the canonical real path so `git` runs against exactly what was
+ * checked, narrowing the window between the check and the spawn.
+ */
+export function safeGitRepoPath(value) {
+    const normalized = normalizeRepoPathCandidate(value);
+    if (normalized === null)
+        return null;
+    const real = realPathOrNull(normalized);
+    if (real === null)
+        return null;
+    try {
+        if (!statSync(real).isDirectory())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return real;
+}

package/dist/lib/spawn-arg-safety.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Guards for untrusted values that end up in the argv of a spawned process.
+ *
+ * `execFileSync` prevents *shell* injection but not *argv-option* injection: a
+ * value beginning with `-` is parsed by the child as a command-line option. Git
+ * remotes and workspace paths are untrusted text — they come from a repo the
+ * developer cloned, from Cursor's `workspace.json`, or from a Claude transcript
+ * — so every value derived from them must be checked before it reaches `git`
+ * or `ssh`. See DB90DV-546.
+ */
+/**
+ * True when `host` is safe to pass as an argv element to `ssh`. Accepts real
+ * hostnames, IPv4 literals, and `~/.ssh/config` host aliases.
+ */
+export declare function isSafeSshHost(host: string): boolean;
+/**
+ * True when `value` is safe to pass as a filesystem-path argv element (e.g.
+ * after `git -C`). Deliberately permissive about path *content* — real
+ * workspace paths contain spaces, dashes and drive letters. It only rejects
+ * what makes the child misread the value as an option, plus embedded NUL.
+ *
+ * This is an argv guard, not a containment check: verifying the path points
+ * somewhere legitimate is DB90DV-547.
+ */
+export declare function isSafeSpawnPathArg(value: string): boolean;