gnosys 5.9.5 → 5.11.0

package/dist/lib/llm.d.ts

@@ -3,13 +3,15 @@
  * Supports Anthropic (cloud) and Ollama (local). Clean factory pattern enables
  * future providers (Groq, OpenAI, LM Studio) with zero changes to call sites.
  */
-import { GnosysConfig, LLMProviderName } from "./config.js";
-export interface LLMGenerateOptions {
+import { type GnosysConfig, type LLMProviderName } from "./config.js";
+/** Strip literal API keys and known key-prefix patterns from provider error text. */
+export declare function redactKey(text: string, apiKey?: string): string;
+interface LLMGenerateOptions {
     system?: string;
     maxTokens?: number;
     stream?: boolean;
 }
-export interface LLMStreamCallbacks {
+interface LLMStreamCallbacks {
     onToken: (token: string) => void;
 }
 /**
@@ -35,47 +37,6 @@ export interface LLMProvider {
      */
     testConnection(): Promise<boolean>;
 }
-export declare class AnthropicProvider implements LLMProvider {
-    readonly name: LLMProviderName;
-    readonly model: string;
-    private client;
-    private config;
-    private apiKey;
-    private clientPromise;
-    constructor(model: string, apiKey: string, config?: GnosysConfig);
-    private getClient;
-    generate(prompt: string, options?: LLMGenerateOptions, streamCallbacks?: LLMStreamCallbacks): Promise<string>;
-    private streamGenerate;
-    generateWithImage(prompt: string, imageBase64: string, mimeType: string, options?: LLMGenerateOptions): Promise<string>;
-    testConnection(): Promise<boolean>;
-}
-export declare class OllamaProvider implements LLMProvider {
-    readonly name: LLMProviderName;
-    readonly model: string;
-    private baseUrl;
-    private config;
-    constructor(model: string, baseUrl: string, config?: GnosysConfig);
-    generate(prompt: string, options?: LLMGenerateOptions, streamCallbacks?: LLMStreamCallbacks): Promise<string>;
-    private readStream;
-    generateWithImage(prompt: string, imageBase64: string, _mimeType: string, options?: LLMGenerateOptions): Promise<string>;
-    testConnection(): Promise<boolean>;
-}
-/**
- * Generic OpenAI-compatible provider. Works with any service that implements
- * the OpenAI /v1/chat/completions API: OpenAI, Groq, LM Studio, etc.
- */
-export declare class OpenAICompatibleProvider implements LLMProvider {
-    readonly name: LLMProviderName;
-    readonly model: string;
-    private baseUrl;
-    private apiKey;
-    private config;
-    constructor(name: LLMProviderName, model: string, baseUrl: string, apiKey: string, config?: GnosysConfig);
-    generate(prompt: string, options?: LLMGenerateOptions, streamCallbacks?: LLMStreamCallbacks): Promise<string>;
-    private readSSEStream;
-    generateWithImage(prompt: string, imageBase64: string, mimeType: string, options?: LLMGenerateOptions): Promise<string>;
-    testConnection(): Promise<boolean>;
-}
 /**
  * Create an LLM provider for a specific task.
  * Resolves provider + model from config's taskModels or defaultProvider.
@@ -93,4 +54,4 @@ export declare function isProviderAvailable(config: GnosysConfig, provider?: LLM
     available: boolean;
     error?: string;
 };
-//# sourceMappingURL=llm.d.ts.map
+export {};

package/dist/lib/llm.js

@@ -5,8 +5,20 @@
  */
 import { DEFAULT_CONFIG, resolveTaskModel, getAnthropicApiKey, getOllamaBaseUrl, getGroqApiKey, getOpenAIApiKey, getOpenAIBaseUrl, getLMStudioBaseUrl, getXAIApiKey, getMistralApiKey, getCustomApiKey, getProviderModel, ALL_PROVIDERS, } from "./config.js";
 import { withRetry, isTransientError } from "./retry.js";
+/** Per-request timeout for LLM generation calls (ms). */
+const LLM_TIMEOUT_MS = 60_000;
+/** Shorter timeout for connectivity probes (testConnection, model lists). */
+const PROBE_TIMEOUT_MS = 10_000;
+/** Strip literal API keys and known key-prefix patterns from provider error text. */
+export function redactKey(text, apiKey) {
+    let out = text;
+    if (apiKey && apiKey.length >= 8) {
+        out = out.split(apiKey).join("***");
+    }
+    return out.replace(/(?:sk-ant-|sk-|gsk_|xai-|Bearer\s+)[^\s"']+/g, "***");
+}
 // ─── Anthropic Provider ──────────────────────────────────────────────────
-export class AnthropicProvider {
+class AnthropicProvider {
     name = "anthropic";
     model;
     client = null; // Anthropic SDK client (lazy-initialized)
@@ -24,7 +36,7 @@ export class AnthropicProvider {
         if (!this.clientPromise) {
             this.clientPromise = import("@anthropic-ai/sdk").then((mod) => {
                 const Anthropic = mod.default || mod;
-                this.client = new Anthropic({ apiKey: this.apiKey });
+                this.client = new Anthropic({ apiKey: this.apiKey, timeout: LLM_TIMEOUT_MS });
                 return this.client;
             });
         }
@@ -111,12 +123,12 @@ export class AnthropicProvider {
         catch (err) {
             // Sanitize error message to prevent API key leakage
             const msg = err instanceof Error ? err.message : String(err);
-            throw new Error(`Anthropic connection failed: ${msg.replace(/sk-ant-[^\s"']+/g, "sk-ant-***")}`);
+            throw new Error(`Anthropic connection failed: ${redactKey(msg, this.apiKey)}`);
         }
     }
 }
 // ─── Ollama Provider ─────────────────────────────────────────────────────
-export class OllamaProvider {
+class OllamaProvider {
     name = "ollama";
     model;
     baseUrl;
@@ -147,6 +159,7 @@ export class OllamaProvider {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(body),
+            signal: AbortSignal.timeout(LLM_TIMEOUT_MS),
         }), {
             maxAttempts: this.config.llmRetryAttempts,
             baseDelayMs: this.config.llmRetryBaseDelayMs,
@@ -211,6 +224,7 @@ export class OllamaProvider {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(body),
+            signal: AbortSignal.timeout(LLM_TIMEOUT_MS),
         }), {
             maxAttempts: this.config.llmRetryAttempts,
             baseDelayMs: this.config.llmRetryBaseDelayMs,
@@ -225,7 +239,9 @@ export class OllamaProvider {
     }
     async testConnection() {
         try {
-            const response = await fetch(`${this.baseUrl}/api/tags`);
+            const response = await fetch(`${this.baseUrl}/api/tags`, {
+                signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+            });
             if (!response.ok) {
                 throw new Error(`HTTP ${response.status}`);
             }
@@ -257,7 +273,7 @@ export class OllamaProvider {
  * Generic OpenAI-compatible provider. Works with any service that implements
  * the OpenAI /v1/chat/completions API: OpenAI, Groq, LM Studio, etc.
  */
-export class OpenAICompatibleProvider {
+class OpenAICompatibleProvider {
     name;
     model;
     baseUrl;
@@ -291,6 +307,7 @@ export class OpenAICompatibleProvider {
                 ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
             },
             body: JSON.stringify(body),
+            signal: AbortSignal.timeout(LLM_TIMEOUT_MS),
         }), {
             maxAttempts: this.config.llmRetryAttempts,
             baseDelayMs: this.config.llmRetryBaseDelayMs,
@@ -299,7 +316,7 @@ export class OpenAICompatibleProvider {
         if (!response.ok) {
             const errorText = await response.text();
             // Sanitize error text to prevent API key leakage
-            const safeText = errorText.replace(/(?:sk-|gsk_|Bearer\s+)[^\s"']+/g, "***");
+            const safeText = redactKey(errorText, this.apiKey);
             throw new Error(`${this.name} request failed (${response.status}): ${safeText}`);
         }
         if (shouldStream && streamCallbacks) {
@@ -368,6 +385,7 @@ export class OpenAICompatibleProvider {
                 messages,
                 max_tokens: maxTokens,
             }),
+            signal: AbortSignal.timeout(LLM_TIMEOUT_MS),
         }), {
             maxAttempts: this.config.llmRetryAttempts,
             baseDelayMs: this.config.llmRetryBaseDelayMs,
@@ -375,7 +393,7 @@ export class OpenAICompatibleProvider {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            const safeText = errorText.replace(/(?:sk-|gsk_|Bearer\s+)[^\s"']+/g, "***");
+            const safeText = redactKey(errorText, this.apiKey);
             throw new Error(`${this.name} vision request failed (${response.status}): ${safeText}`);
         }
         const data = (await response.json());
@@ -387,6 +405,7 @@ export class OpenAICompatibleProvider {
                 headers: {
                     ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
                 },
+                signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
             });
             if (!response.ok) {
                 throw new Error(`HTTP ${response.status}`);
@@ -550,4 +569,3 @@ export function isProviderAvailable(config, provider) {
             return { available: false, error: `Unknown provider: ${target}` };
     }
 }
-//# sourceMappingURL=llm.js.map

package/dist/lib/lock.d.ts

@@ -30,4 +30,3 @@ export declare function acquireWriteLock(storePath: string, operation?: string):
  * 4MB+ WAL files in the wild with no checkpoint cadence in v5.4.0.
  */
 export declare function enableWAL(db: any): void;
-//# sourceMappingURL=lock.d.ts.map

package/dist/lib/lock.js

@@ -151,4 +151,3 @@ export function enableWAL(db) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-//# sourceMappingURL=lock.js.map

package/dist/lib/log.d.ts

@@ -0,0 +1,4 @@
+export declare function logError(err: unknown, ctx?: object): void;
+export declare function logWarn(message: string, ctx?: object): void;
+export declare function logInfo(message: string, ctx?: object): void;
+export declare function logDebug(message: string, ctx?: object): void;

package/dist/lib/log.js

@@ -0,0 +1,85 @@
+import fs from "fs";
+const LEVEL_ORDER = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+function configuredLevel() {
+    const raw = (process.env.GNOSYS_LOG_LEVEL || "info").toLowerCase();
+    if (raw === "debug" || raw === "info" || raw === "warn" || raw === "error")
+        return raw;
+    return "info";
+}
+function shouldEmit(level) {
+    return LEVEL_ORDER[level] >= LEVEL_ORDER[configuredLevel()];
+}
+function normalizeError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+function buildRecord(level, message, err, ctx) {
+    const record = {
+        timestamp: new Date().toISOString(),
+        level,
+        message,
+        ...(ctx ?? {}),
+    };
+    if (err) {
+        record.error = {
+            name: err.name,
+            message: err.message,
+            stack: err.stack,
+        };
+    }
+    return record;
+}
+function formatText(level, message, err) {
+    const prefix = level === "error"
+        ? message.startsWith("gnosys:")
+            ? message
+            : `gnosys: ${message}`
+        : `gnosys: ${level}: ${message}`;
+    if (err?.stack && level === "error") {
+        return `${prefix}\n${err.stack}\n`;
+    }
+    return `${prefix}\n`;
+}
+function writeJsonLine(line) {
+    const logFile = process.env.GNOSYS_LOG_FILE;
+    if (logFile) {
+        fs.appendFileSync(logFile, line, "utf8");
+    }
+}
+function emit(level, message, err, ctx) {
+    if (!shouldEmit(level))
+        return;
+    try {
+        const jsonLine = `${JSON.stringify(buildRecord(level, message, err, ctx))}\n`;
+        const useJson = process.env.GNOSYS_LOG_FORMAT === "json";
+        if (useJson) {
+            process.stderr.write(jsonLine);
+        }
+        else {
+            process.stderr.write(formatText(level, message, err));
+        }
+        if (process.env.GNOSYS_LOG_FILE) {
+            writeJsonLine(jsonLine);
+        }
+    }
+    catch {
+        // Best-effort logging must never throw.
+    }
+}
+export function logError(err, ctx) {
+    const error = normalizeError(err);
+    emit("error", error.message, error, ctx);
+}
+export function logWarn(message, ctx) {
+    emit("warn", message, undefined, ctx);
+}
+export function logInfo(message, ctx) {
+    emit("info", message, undefined, ctx);
+}
+export function logDebug(message, ctx) {
+    emit("debug", message, undefined, ctx);
+}

package/dist/lib/machineConfig.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Machine-local configuration — `~/.config/gnosys/machine.json`.
+ *
+ * This is the single home for everything specific to THIS physical machine,
+ * and it must NEVER be synced to the shared brain or to other machines:
+ *
+ *   - `machineId`  — a stable random UUID identifying this machine. Used to
+ *                    key per-machine rows (e.g. project_locations) so two
+ *                    machines never clobber each other's data.
+ *   - `roots`      — named project roots whose ABSOLUTE paths differ per
+ *                    machine (e.g. { dev: "/Users/edward/MSDev/projects" } on
+ *                    the Studio, "/Users/edward/MBPDev/projects" on the MBP).
+ *                    A project stores a machine-INDEPENDENT `rel_path` + the
+ *                    `root_id`; its absolute path is reconstructed at runtime.
+ *   - `remote`     — the per-machine remote-sync connection (NAS mount path on
+ *                    one machine, a Tailscale URL on another). Previously this
+ *                    lived in the synced `gnosys_meta` table, which is itself
+ *                    the multi-machine bug in miniature — every machine
+ *                    overwrote the others' value.
+ *
+ * The central DB at `~/.gnosys/gnosys.db` is the synced source of truth;
+ * machine.json is its machine-local counterpart. Resolution of a project's
+ * absolute path on a given machine is: `join(roots[root_id], rel_path)` (or a
+ * per-machine override row for projects that live outside any root).
+ */
+interface MachineRemoteConfig {
+    /** Whether remote sync is configured/active on this machine. */
+    enabled: boolean;
+    /** Absolute path or URL to the remote DB on this machine (NAS mount / Tailscale). */
+    path?: string;
+}
+export interface MachineConfig {
+    /** Stable random UUID for this machine. Never shared/synced. */
+    machineId: string;
+    /** os.hostname() at write time — used to detect a synced-in foreign file. */
+    hostname: string;
+    /** Named root → absolute path on THIS machine. */
+    roots: Record<string, string>;
+    /** Per-machine remote-sync connection. */
+    remote: MachineRemoteConfig;
+    schemaVersion: number;
+}
+/** A fresh machine config for the current host. */
+export declare function defaultMachineConfig(): MachineConfig;
+/** Read machine.json, or null if it doesn't exist / is unreadable. */
+export declare function readMachineConfig(): MachineConfig | null;
+/** Persist machine.json (creates the config dir if needed). */
+export declare function writeMachineConfig(cfg: MachineConfig): void;
+export interface EnsureResult {
+    config: MachineConfig;
+    /** True if a new config was created on disk. */
+    created: boolean;
+    /**
+     * True if the existing config's hostname did not match the current host —
+     * a strong signal it was synced in from another machine, so machineId was
+     * regenerated to keep machine identities distinct.
+     */
+    regenerated: boolean;
+}
+/**
+ * Load machine.json, creating it on first run. If the persisted config's
+ * hostname does not match the current host, it was almost certainly synced in
+ * from another machine by mistake; regenerate `machineId` and refresh
+ * `hostname` so two machines never share an identity. Named roots and the
+ * remote block are preserved (a benign hostname rename keeps them valid; a
+ * genuine foreign file gets corrected when the user re-runs `projects scan`).
+ */
+export declare function ensureMachineConfig(): EnsureResult;
+/** Convenience: this machine's stable id (creating machine.json if needed). */
+export declare function getMachineId(): string;
+/**
+ * Reconstruct an absolute path on this machine from a (root_id, rel_path)
+ * pair, using the machine's named roots. Returns null when the root is not
+ * configured on this machine (i.e. the project is "not on this machine").
+ */
+export declare function absPathFromRoot(cfg: MachineConfig, rootId: string | null | undefined, relPath: string | null | undefined): string | null;
+/**
+ * Given an absolute path on this machine, find the named root that contains
+ * it and return { rootId, relPath }. Picks the deepest (most specific) root
+ * when several match. Returns null when no configured root contains the path.
+ */
+export declare function relPathUnderRoot(cfg: MachineConfig, absPath: string): {
+    rootId: string;
+    relPath: string;
+} | null;
+export {};

package/dist/lib/machineConfig.js

@@ -0,0 +1,157 @@
+/**
+ * Machine-local configuration — `~/.config/gnosys/machine.json`.
+ *
+ * This is the single home for everything specific to THIS physical machine,
+ * and it must NEVER be synced to the shared brain or to other machines:
+ *
+ *   - `machineId`  — a stable random UUID identifying this machine. Used to
+ *                    key per-machine rows (e.g. project_locations) so two
+ *                    machines never clobber each other's data.
+ *   - `roots`      — named project roots whose ABSOLUTE paths differ per
+ *                    machine (e.g. { dev: "/Users/edward/MSDev/projects" } on
+ *                    the Studio, "/Users/edward/MBPDev/projects" on the MBP).
+ *                    A project stores a machine-INDEPENDENT `rel_path` + the
+ *                    `root_id`; its absolute path is reconstructed at runtime.
+ *   - `remote`     — the per-machine remote-sync connection (NAS mount path on
+ *                    one machine, a Tailscale URL on another). Previously this
+ *                    lived in the synced `gnosys_meta` table, which is itself
+ *                    the multi-machine bug in miniature — every machine
+ *                    overwrote the others' value.
+ *
+ * The central DB at `~/.gnosys/gnosys.db` is the synced source of truth;
+ * machine.json is its machine-local counterpart. Resolution of a project's
+ * absolute path on a given machine is: `join(roots[root_id], rel_path)` (or a
+ * per-machine override row for projects that live outside any root).
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { randomUUID } from "crypto";
+import { getMachineConfigPath } from "./paths.js";
+import { atomicWriteFileSync } from "./atomicWrite.js";
+const MACHINE_CONFIG_VERSION = 1;
+/** A fresh machine config for the current host. */
+export function defaultMachineConfig() {
+    return {
+        machineId: randomUUID(),
+        hostname: os.hostname(),
+        roots: {},
+        remote: { enabled: false },
+        schemaVersion: MACHINE_CONFIG_VERSION,
+    };
+}
+/** Coerce an arbitrary parsed object into a well-formed MachineConfig. */
+function normalize(parsed) {
+    const base = defaultMachineConfig();
+    if (!parsed || typeof parsed !== "object")
+        return base;
+    const roots = {};
+    if (parsed.roots && typeof parsed.roots === "object") {
+        for (const [k, v] of Object.entries(parsed.roots)) {
+            if (typeof v === "string" && v.length > 0)
+                roots[k] = path.resolve(v);
+        }
+    }
+    const remote = {
+        enabled: Boolean(parsed.remote?.enabled),
+        ...(typeof parsed.remote?.path === "string" ? { path: parsed.remote.path } : {}),
+    };
+    return {
+        machineId: typeof parsed.machineId === "string" && parsed.machineId ? parsed.machineId : base.machineId,
+        hostname: typeof parsed.hostname === "string" && parsed.hostname ? parsed.hostname : base.hostname,
+        roots,
+        remote,
+        schemaVersion: typeof parsed.schemaVersion === "number" ? parsed.schemaVersion : MACHINE_CONFIG_VERSION,
+    };
+}
+/** Read machine.json, or null if it doesn't exist / is unreadable. */
+export function readMachineConfig() {
+    try {
+        const raw = fs.readFileSync(getMachineConfigPath(), "utf-8");
+        return normalize(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist machine.json (creates the config dir if needed). */
+export function writeMachineConfig(cfg) {
+    const p = getMachineConfigPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    atomicWriteFileSync(p, JSON.stringify(cfg, null, 2) + "\n");
+}
+/**
+ * Load machine.json, creating it on first run. If the persisted config's
+ * hostname does not match the current host, it was almost certainly synced in
+ * from another machine by mistake; regenerate `machineId` and refresh
+ * `hostname` so two machines never share an identity. Named roots and the
+ * remote block are preserved (a benign hostname rename keeps them valid; a
+ * genuine foreign file gets corrected when the user re-runs `projects scan`).
+ */
+export function ensureMachineConfig() {
+    const override = process.env.GNOSYS_MACHINE_ID?.trim();
+    const existing = readMachineConfig();
+    const host = os.hostname();
+    if (override) {
+        const base = existing ?? defaultMachineConfig();
+        const cfg = {
+            ...base,
+            machineId: override,
+            hostname: host,
+        };
+        writeMachineConfig(cfg);
+        return { config: cfg, created: !existing, regenerated: false };
+    }
+    if (!existing) {
+        const fresh = defaultMachineConfig();
+        writeMachineConfig(fresh);
+        return { config: fresh, created: true, regenerated: false };
+    }
+    if (existing.hostname !== host) {
+        const regenerated = {
+            ...existing,
+            machineId: randomUUID(),
+            hostname: host,
+        };
+        writeMachineConfig(regenerated);
+        return { config: regenerated, created: false, regenerated: true };
+    }
+    return { config: existing, created: false, regenerated: false };
+}
+/** Convenience: this machine's stable id (creating machine.json if needed). */
+export function getMachineId() {
+    return ensureMachineConfig().config.machineId;
+}
+/**
+ * Reconstruct an absolute path on this machine from a (root_id, rel_path)
+ * pair, using the machine's named roots. Returns null when the root is not
+ * configured on this machine (i.e. the project is "not on this machine").
+ */
+export function absPathFromRoot(cfg, rootId, relPath) {
+    if (!rootId || !relPath)
+        return null;
+    const root = cfg.roots[rootId];
+    if (!root)
+        return null;
+    return path.join(root, relPath);
+}
+/**
+ * Given an absolute path on this machine, find the named root that contains
+ * it and return { rootId, relPath }. Picks the deepest (most specific) root
+ * when several match. Returns null when no configured root contains the path.
+ */
+export function relPathUnderRoot(cfg, absPath) {
+    const target = path.resolve(absPath);
+    let best = null;
+    for (const [rootId, rootPath] of Object.entries(cfg.roots)) {
+        const root = path.resolve(rootPath);
+        const rel = path.relative(root, target);
+        // Inside the root iff rel doesn't escape upward and isn't absolute.
+        if (rel && !rel.startsWith("..") && !path.isAbsolute(rel)) {
+            if (!best || root.length > best.rootLen) {
+                best = { rootId, relPath: rel, rootLen: root.length };
+            }
+        }
+    }
+    return best ? { rootId: best.rootId, relPath: best.relPath } : null;
+}

package/dist/lib/machineMigrate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * v5.11 one-time migration to machine-portable project paths.
+ *
+ * Run once per machine. It:
+ *   1. Ensures machine.json exists (machineId, hostname).
+ *   2. Adopts machine-LOCAL values that were wrongly living in the SYNCED
+ *      gnosys_meta — `machine_id` (for continuity) and `remote_path` — into
+ *      machine.json, then deletes them from meta so they stop syncing and
+ *      clobbering other machines.
+ *   3. Sets the `dev` root (explicit --root, else derived from the registry).
+ *   4. Scans to backfill machine-independent root_id/rel_path on projects.
+ *
+ * It operates on the LOCAL DB (GnosysDB.openLocal), never a remote, because it
+ * moves machine-local state out of the shared store.
+ */
+import type { GnosysDB } from "./db.js";
+import { type ScanResult } from "./projectScan.js";
+export interface MigrateResult {
+    machineId: string;
+    hostname: string;
+    rootsConfigured: Record<string, string>;
+    adoptedMachineId: boolean;
+    adoptedRemotePath: boolean;
+    regeneratedMachineId: boolean;
+    scan?: ScanResult;
+}
+export declare function migrateMachine(localDb: GnosysDB, opts?: {
+    root?: string;
+    rootName?: string;
+    scan?: boolean;
+}): Promise<MigrateResult>;
+/**
+ * Derive the most likely `dev` root: the directory that is the parent of the
+ * most registered projects. Picking the most-common parent (rather than the
+ * global common prefix) avoids collapsing to `/Users/<name>` when a few
+ * outlier projects live elsewhere.
+ */
+export declare function deriveCommonRoot(): string | null;