om-memory-system 3.4.0-next.23 → 3.4.0-next.26

package/dist/services/ai/live-model-choice.js

@@ -33,12 +33,21 @@ function getManualProviderStatus(config) {
         issues,
     };
 }
+/** The host chose the external API: it is the primary call, so there is no fallback. */
+function externalChoiceStatus(config) {
+    const manual = getManualProviderStatus(config);
+    return manual.ready
+        ? { ready: true, mode: "manual", issues: [] }
+        : { ready: false, issues: manual.issues };
+}
 export function getAutoCaptureProviderStatus(config) {
     const hasOpencodeProvider = hasValue(config.opencodeProvider);
     const hasOpencodeModel = hasValue(config.opencodeModel);
     if (config.opencodeModel?.trim() === "inherit") {
         return { ready: true, mode: "session", issues: [] };
     }
+    if (config.opencodeModel?.trim() === "external")
+        return externalChoiceStatus(config);
     if (hasOpencodeProvider && hasOpencodeModel) {
         return { ready: true, mode: "opencode", issues: [] };
     }
@@ -70,6 +79,10 @@ export function resolveOpencodeHostModel(config) {
 export function resolvePiLiveModel(config) {
     if (config.piModel?.trim() === "inherit")
         return { kind: "session" };
+    if (config.piModel?.trim() === "external") {
+        const status = externalChoiceStatus(config);
+        return status.ready ? { kind: "manual" } : { kind: "unready", issues: status.issues };
+    }
     if (hasValue(config.piProvider) && hasValue(config.piModel)) {
         return { kind: "pi", provider: config.piProvider.trim(), model: config.piModel.trim() };
     }
@@ -84,3 +97,8 @@ export function resolvePiLiveModel(config) {
 export function isExternalModelReady(config) {
     return getManualProviderStatus(config).ready;
 }
+/** Why the external API cannot be used as a host's chosen model, or an empty list. */
+export function externalModelIssues(config) {
+    const manual = getManualProviderStatus(config);
+    return manual.ready ? [] : manual.issues;
+}

package/dist/services/api-handlers.d.ts

@@ -41,7 +41,7 @@ interface PaginatedResponse<T> {
 export declare function handleListTags(): Promise<ApiResponse<{
     project: TagInfo[];
 }>>;
-export declare function handleListMemories(tag?: string, page?: number, pageSize?: number, includePrompts?: boolean): Promise<ApiResponse<PaginatedResponse<Memory | any>>>;
+export declare function handleListMemories(tag?: string, page?: number, pageSize?: number, includePrompts?: boolean, keyword?: string): Promise<ApiResponse<PaginatedResponse<Memory | any>>>;
 export declare function handleAddMemory(data: {
     content: string;
     containerTag: string;
@@ -178,6 +178,11 @@ interface MigrationProgress {
     errors: string[];
 }
 export declare function handleGetTagMigrationProgress(): Promise<ApiResponse<MigrationProgress>>;
+/**
+ * Tag the memories that have no tags, a few per request. Only untagged
+ * memories are touched: tagged ones keep their vectors. A memory that fails
+ * is recorded and passed over, so one bad row cannot stall the run.
+ */
 export declare function handleRunTagMigrationBatch(batchSize?: number): Promise<ApiResponse<{
     processed: number;
     total: number;

package/dist/services/api-handlers.js

@@ -98,7 +98,7 @@ export async function handleListTags() {
         return { success: false, error: String(error) };
     }
 }
-export async function handleListMemories(tag, page = 1, pageSize = 20, includePrompts = true) {
+export async function handleListMemories(tag, page = 1, pageSize = 20, includePrompts = true, keyword) {
     try {
         await ensureTursoReady();
         // Listing only reads SQLite rows; no vector ops happen here.
@@ -151,11 +151,21 @@ export async function handleListMemories(tag, page = 1, pageSize = 20, includePr
                 isPinned: r.is_pinned === 1,
             };
         });
-        let timeline = memoriesWithType;
+        // A keyword filter keeps memories carrying that keyword (case-insensitive)
+        // and only the prompts linked to them.
+        const wanted = keyword?.trim().toLowerCase();
+        const keptMemories = wanted
+            ? memoriesWithType.filter((m) => m.tags.some((t) => t.toLowerCase() === wanted))
+            : memoriesWithType;
+        const keptIds = new Set(keptMemories.map((m) => m.id));
+        let timeline = keptMemories;
         if (includePrompts) {
             const projectPath = tag ? await getProjectPathFromTag(tag) : undefined;
             const prompts = await userPromptManager.getCapturedPrompts(projectPath);
-            const promptsWithType = prompts.map((p) => ({
+            const visiblePrompts = wanted
+                ? prompts.filter((p) => p.linkedMemoryId && keptIds.has(p.linkedMemoryId))
+                : prompts;
+            const promptsWithType = visiblePrompts.map((p) => ({
                 type: "prompt",
                 id: p.id,
                 sessionId: p.sessionId,
@@ -164,7 +174,7 @@ export async function handleListMemories(tag, page = 1, pageSize = 20, includePr
                 projectPath: p.projectPath,
                 linkedMemoryId: p.linkedMemoryId,
             }));
-            timeline = [...memoriesWithType, ...promptsWithType];
+            timeline = [...keptMemories, ...promptsWithType];
         }
         const linkedPairs = new Map();
         const standalone = [];
@@ -1181,17 +1191,25 @@ export async function handleDetectTagMigration() {
         return { success: false, error: String(error) };
     }
 }
-const migrationProgress = {
+const idleMigration = () => ({
     processed: 0,
     total: 0,
     currentBatch: 0,
     totalBatches: 0,
     isComplete: true,
     errors: [],
-};
+});
+let migrationProgress = idleMigration();
+/** The untagged memories this migration run covers, fixed when the run starts. */
+let migrationQueue = [];
 export async function handleGetTagMigrationProgress() {
     return { success: true, data: migrationProgress };
 }
+/**
+ * Tag the memories that have no tags, a few per request. Only untagged
+ * memories are touched: tagged ones keep their vectors. A memory that fails
+ * is recorded and passed over, so one bad row cannot stall the run.
+ */
 export async function handleRunTagMigrationBatch(batchSize = 5) {
     try {
         await ensureTursoReady();
@@ -1202,77 +1220,68 @@ export async function handleRunTagMigrationBatch(batchSize = 5) {
             iterationTimeout: 30000,
         });
         const provider = AIProviderFactory.createProvider(CONFIG.memoryProvider, providerConfig);
-        const projectShards = await tursoShardManager.getAllShards("project", "");
-        const allMemories = [];
-        for (const shard of projectShards) {
-            const db = await tursoConnectionManager.getConnection(shard.dbPath);
-            const memories = await db.all("SELECT * FROM memories");
-            for (const m of memories) {
-                allMemories.push({ memory: m, shard });
+        if (migrationProgress.isComplete) {
+            migrationQueue = [];
+            for (const shard of await tursoShardManager.getAllShards("project", "")) {
+                const db = await tursoConnectionManager.getConnection(shard.dbPath);
+                const rows = await db.all("SELECT id FROM memories WHERE tags IS NULL OR tags = '' ORDER BY id");
+                for (const row of rows)
+                    migrationQueue.push({ id: String(row.id), dbPath: shard.dbPath });
             }
+            migrationProgress = {
+                ...idleMigration(),
+                total: migrationQueue.length,
+                totalBatches: Math.ceil(migrationQueue.length / batchSize),
+                isComplete: migrationQueue.length === 0,
+            };
         }
-        if (migrationProgress.total === 0) {
-            migrationProgress.total = allMemories.length;
-            migrationProgress.totalBatches = Math.ceil(allMemories.length / batchSize);
-            migrationProgress.isComplete = false;
-        }
-        const startIdx = migrationProgress.processed;
-        const endIdx = Math.min(startIdx + batchSize, allMemories.length);
-        for (let i = startIdx; i < endIdx; i++) {
-            const item = allMemories[i];
-            if (!item)
-                continue;
-            const { memory: m, shard } = item;
-            const db = await tursoConnectionManager.getConnection(shard.dbPath);
+        const batch = migrationQueue.slice(migrationProgress.processed, migrationProgress.processed + batchSize);
+        for (const item of batch) {
             try {
-                let currentTags = m.tags
-                    ? m.tags
-                        .split(",")
-                        .map((t) => t.trim().toLowerCase())
-                        .filter((t) => t)
-                    : [];
-                if (currentTags.length === 0) {
-                    const prompt = `Generate 2-4 short technical tags for this memory content:\n\n${m.content}\n\nReturn ONLY a comma-separated list of tags.`;
-                    const result = await provider.executeToolCall("You are a technical tagger.", prompt, {
-                        type: "function",
-                        function: {
-                            name: "save_tags",
-                            description: "Save generated tags",
-                            parameters: {
-                                type: "object",
-                                properties: { tags: { type: "array", items: { type: "string" } } },
-                                required: ["tags"],
-                            },
+                const db = await tursoConnectionManager.getConnection(item.dbPath);
+                const m = await db.get("SELECT * FROM memories WHERE id = ?", [item.id]);
+                // Tagged or deleted since the run started: nothing to do.
+                if (!m || (m.tags && String(m.tags).trim()))
+                    continue;
+                const prompt = `Generate 2-4 short technical tags for this memory content:\n\n${m.content}\n\nReturn ONLY a comma-separated list of tags.`;
+                const result = await provider.executeToolCall("You are a technical tagger.", prompt, {
+                    type: "function",
+                    function: {
+                        name: "save_tags",
+                        description: "Save generated tags",
+                        parameters: {
+                            type: "object",
+                            properties: { tags: { type: "array", items: { type: "string" } } },
+                            required: ["tags"],
                         },
-                    }, `migration_${m.id}`);
-                    if (result.success && result.data?.tags) {
-                        currentTags = result.data.tags;
-                        await db.run("UPDATE memories SET tags = ? WHERE id = ?", [
-                            currentTags.join(","),
-                            m.id,
-                        ]);
-                    }
+                    },
+                }, `migration_${m.id}`);
+                const tags = Array.isArray(result.data?.tags)
+                    ? result.data.tags.map((t) => String(t).trim().toLowerCase()).filter(Boolean)
+                    : [];
+                if (!result.success || tags.length === 0) {
+                    throw new Error(result.error ?? "The model returned no tags");
                 }
                 const vector = await embeddingService.embedWithTimeout(m.content, { task: "document" });
-                const tagsVector = currentTags.length
-                    ? await embeddingService.embedWithTimeout(formatTagsForEmbedding(currentTags), {
-                        task: "document",
-                    })
-                    : undefined;
-                await tursoVectorSearch.updateVector(db, m.id, vector, tagsVector);
-                migrationProgress.processed++;
+                const tagsVector = await embeddingService.embedWithTimeout(formatTagsForEmbedding(tags), {
+                    task: "document",
+                });
+                // One statement, so a memory never ends up tagged with stale vectors.
+                await tursoVectorSearch.updateVector(db, m.id, vector, tagsVector, tags.join(","));
             }
             catch (e) {
                 const errorMsg = String(e);
                 migrationProgress.errors.push(errorMsg);
-                log("Migration error for memory", { id: m.id, error: errorMsg });
+                log("Migration error for memory", { id: item.id, error: errorMsg });
+            }
+            finally {
+                migrationProgress.processed++;
             }
         }
         migrationProgress.currentBatch++;
         const hasMore = migrationProgress.processed < migrationProgress.total;
-        if (!hasMore) {
+        if (!hasMore)
             migrationProgress.isComplete = true;
-        }
         return {
             success: true,
             data: { processed: migrationProgress.processed, total: migrationProgress.total, hasMore },

package/dist/services/backfill-state.d.ts

@@ -14,10 +14,40 @@ export type BackfillStatus = {
     error: string | null;
     updatedAt: number;
 };
+export type UnresolvedDirectory = {
+    directory: string;
+    sessions: number;
+};
+export declare const MAX_UNRESOLVED_DIRECTORIES = 200;
 /** Record a fixed per-host cutoff before the first import. */
 export declare function getBackfillCutoff(host: BackfillHost, now?: number): Promise<number>;
 /** Read progress without creating a store or a ledger table. */
 export declare function readBackfillStatus(host: BackfillHost): Promise<BackfillStatus | null>;
+/**
+ * Group unresolved sessions by directory, most sessions first, capped so the
+ * row stays small. Sessions with no recorded directory are left out.
+ */
+export declare function summarizeUnresolvedDirectories(sessions: ReadonlyArray<{
+    directory: string | null;
+    sessions?: number;
+}>): UnresolvedDirectory[];
+/** Unresolved directories of an import report with session counts. */
+export declare function unresolvedDirectoriesOf(report: {
+    unresolvedProjects?: ReadonlyArray<{
+        directory: string;
+        sessions: number;
+    }>;
+    unresolvableSessions: ReadonlyArray<{
+        cwd: string | null;
+    }>;
+}): UnresolvedDirectory[];
+/**
+ * Save the unresolved directories of a host's latest listing or run. They
+ * live in their own table, so recording them never sets a backfill cutoff.
+ */
+export declare function recordUnresolvedDirectories(host: BackfillHost, directories: UnresolvedDirectory[], now?: number): Promise<void>;
+/** A host's latest unresolved directories, without creating a store or table. */
+export declare function readUnresolvedDirectories(host: BackfillHost): Promise<UnresolvedDirectory[]>;
 /** Save only numeric counts and a redacted error, never report units or prompts. */
 export declare function updateBackfillStatus(host: BackfillHost, update: Pick<BackfillStatus, "state" | "model" | "counts"> & {
     error?: unknown;

package/dist/services/backfill-state.js

@@ -4,6 +4,7 @@ import { CONFIG } from "../config.js";
 import { tursoConnectionManager } from "./turso/connection-manager.js";
 import { safeHealthError } from "./safe-health-error.js";
 const importLedgerDbPath = () => join(CONFIG.storagePath, "import-ledger.db");
+export const MAX_UNRESOLVED_DIRECTORIES = 200;
 const emptyCounts = () => ({ imported: 0, skipped: 0, failed: 0, pending: 0, unresolved: 0 });
 async function table() {
     const db = await tursoConnectionManager.getConnection(importLedgerDbPath());
@@ -48,6 +49,52 @@ export async function readBackfillStatus(host) {
         updatedAt: Number(row.updated_at),
     };
 }
+/**
+ * Group unresolved sessions by directory, most sessions first, capped so the
+ * row stays small. Sessions with no recorded directory are left out.
+ */
+export function summarizeUnresolvedDirectories(sessions) {
+    const byDirectory = new Map();
+    for (const item of sessions) {
+        if (!item.directory)
+            continue;
+        byDirectory.set(item.directory, (byDirectory.get(item.directory) ?? 0) + (item.sessions ?? 1));
+    }
+    return [...byDirectory]
+        .map(([directory, count]) => ({ directory, sessions: count }))
+        .sort((a, b) => b.sessions - a.sessions || a.directory.localeCompare(b.directory))
+        .slice(0, MAX_UNRESOLVED_DIRECTORIES);
+}
+/** Unresolved directories of an import report with session counts. */
+export function unresolvedDirectoriesOf(report) {
+    return summarizeUnresolvedDirectories([
+        ...(report.unresolvedProjects ?? []),
+        ...report.unresolvableSessions.map((session) => ({ directory: session.cwd })),
+    ]);
+}
+/**
+ * Save the unresolved directories of a host's latest listing or run. They
+ * live in their own table, so recording them never sets a backfill cutoff.
+ */
+export async function recordUnresolvedDirectories(host, directories, now = Date.now()) {
+    const db = await tursoConnectionManager.getConnection(importLedgerDbPath());
+    await db.run(`CREATE TABLE IF NOT EXISTS unresolved_directories (
+    host TEXT PRIMARY KEY, directories TEXT NOT NULL, updated_at INTEGER NOT NULL
+  )`);
+    await db.run(`INSERT INTO unresolved_directories (host, directories, updated_at) VALUES (?, ?, ?)
+     ON CONFLICT(host) DO UPDATE SET directories = excluded.directories, updated_at = excluded.updated_at`, [host, JSON.stringify(directories.slice(0, MAX_UNRESOLVED_DIRECTORIES)), now]);
+}
+/** A host's latest unresolved directories, without creating a store or table. */
+export async function readUnresolvedDirectories(host) {
+    if (!existsSync(importLedgerDbPath()))
+        return [];
+    const db = await tursoConnectionManager.getConnection(importLedgerDbPath());
+    const exists = await db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'unresolved_directories'");
+    if (!exists)
+        return [];
+    const row = await db.get("SELECT directories FROM unresolved_directories WHERE host = ?", [host]);
+    return row ? JSON.parse(String(row.directories)) : [];
+}
 /** Save only numeric counts and a redacted error, never report units or prompts. */
 export async function updateBackfillStatus(host, update) {
     const counts = Object.fromEntries(Object.keys(emptyCounts()).map((key) => [

package/dist/services/capture-diagnostics.d.ts

@@ -1,5 +1,6 @@
 import type { CaptureAttemptDiagnostics, CaptureAttemptOutcome, CaptureExtractionPath, CaptureFailureReason } from "../core/host.js";
 import type { MemoryHost, MemorySourceType } from "../types/index.js";
+import { restrictToCurrentUser } from "./private-path.js";
 /**
  * The config fields this module reads. Callers pass `CONFIG`; tests pass a
  * plain object, so no import of `../config.js` is needed here.
@@ -52,14 +53,8 @@ export declare function getTraceDirectory(): string;
  * that do not match the trace name pattern are never touched.
  */
 export declare function pruneTraces(config: CaptureDiagnosticsConfig, now?: Date): number;
-type WindowsAclRunner = (command: string, args: string[], options: {
-    env: NodeJS.ProcessEnv;
-    timeout: number;
-    windowsHide: boolean;
-    stdio: "ignore";
-}) => void;
 /** Restrict a trace path to the current user on both Windows and POSIX. */
-export declare function protectTracePath(path: string, mode: number, platform?: NodeJS.Platform, run?: WindowsAclRunner): void;
+export declare const protectTracePath: typeof restrictToCurrentUser;
 /**
  * Append one trace entry to the day's JSON Lines file. A single append per
  * entry keeps lines whole when Pi and OpenCode write at the same time.
@@ -72,4 +67,3 @@ export declare function writeTraceEntry(record: CaptureAttemptRecord, diagnostic
 export declare function emitCaptureAttempt(record: CaptureAttemptRecord, diagnostics: CaptureAttemptDiagnostics, config: CaptureDiagnosticsConfig, now?: Date): void;
 /** Test hook: forget which day the last trace was written. */
 export declare function resetTraceStateForTests(): void;
-export {};

package/dist/services/capture-diagnostics.js

@@ -1,8 +1,8 @@
-import { execFileSync } from "node:child_process";
-import { appendFileSync, chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, unlinkSync, } from "fs";
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readdirSync, unlinkSync } from "fs";
 import { join } from "path";
 import { getLogDirPath } from "./log-path.js";
 import { log } from "./logger.js";
+import { restrictToCurrentUser } from "./private-path.js";
 import { stripPrivateContent } from "./privacy.js";
 export const DEFAULT_CAPTURE_TRACE_RETENTION_DAYS = 7;
 const TRACE_SCHEMA_VERSION = 1;
@@ -113,54 +113,8 @@ export function pruneTraces(config, now = new Date()) {
     return removed;
 }
 let lastTraceDate = null;
-const WINDOWS_TRACE_ACL = `$ErrorActionPreference = 'Stop'
-$path = $env:OMMS_TRACE_ACL_PATH
-$isDirectory = [System.IO.Directory]::Exists($path)
-$acl = if ($isDirectory) {
-  [System.IO.Directory]::GetAccessControl($path)
-} else {
-  [System.IO.File]::GetAccessControl($path)
-}
-$currentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
-$owner = $acl.GetOwner([System.Security.Principal.SecurityIdentifier])
-if ($owner.Value -ne $currentUser.Value) {
-  throw 'Trace path has a different owner'
-}
-$acl.SetAccessRuleProtection($true, $false)
-foreach ($rule in @($acl.Access)) {
-  [void]$acl.RemoveAccessRuleSpecific($rule)
-}
-$inheritance = if ($isDirectory) {
-  [System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'
-} else {
-  [System.Security.AccessControl.InheritanceFlags]::None
-}
-$rule = [System.Security.AccessControl.FileSystemAccessRule]::new(
-  $currentUser,
-  [System.Security.AccessControl.FileSystemRights]::FullControl,
-  $inheritance,
-  [System.Security.AccessControl.PropagationFlags]::None,
-  [System.Security.AccessControl.AccessControlType]::Allow
-)
-$acl.AddAccessRule($rule)
-if ($isDirectory) {
-  [System.IO.Directory]::SetAccessControl($path, $acl)
-} else {
-  [System.IO.File]::SetAccessControl($path, $acl)
-}`;
 /** Restrict a trace path to the current user on both Windows and POSIX. */
-export function protectTracePath(path, mode, platform = process.platform, run = execFileSync) {
-    if (platform !== "win32") {
-        chmodSync(path, mode);
-        return;
-    }
-    run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", WINDOWS_TRACE_ACL], {
-        env: { ...process.env, OMMS_TRACE_ACL_PATH: path },
-        timeout: 10_000,
-        windowsHide: true,
-        stdio: "ignore",
-    });
-}
+export const protectTracePath = restrictToCurrentUser;
 /**
  * Append one trace entry to the day's JSON Lines file. A single append per
  * entry keeps lines whole when Pi and OpenCode write at the same time.

package/dist/services/global-config-writer.d.ts

@@ -1,3 +1,5 @@
+/** The page may point `memoryApiKey` at a source, never store the key itself. */
+export declare function isSecretReference(value: unknown): value is string;
 export declare class ConfigConflictError extends Error {
     readonly status = 409;
     constructor();

package/dist/services/global-config-writer.js

@@ -15,7 +15,39 @@ const keys = new Set([
     "opencodeBackfillModel",
     "piBackfillModel",
     "webServerAutoStart",
+    "memoryProvider",
+    "memoryApiUrl",
+    "memoryModel",
+    "memoryApiKey",
+    "importPathMaps",
 ]);
+const MEMORY_PROVIDERS = [
+    "openai-chat",
+    "openai-responses",
+    "anthropic",
+    "minimax",
+    "orcarouter",
+    "google-gemini",
+];
+/** The page may point `memoryApiKey` at a source, never store the key itself. */
+export function isSecretReference(value) {
+    return (typeof value === "string" && /^(env:\/\/[A-Za-z_][A-Za-z0-9_]*|file:\/\/.+)$/.test(value.trim()));
+}
+function isValidEdit(key, value) {
+    if (key === "captureTrace" || key === "autoBackfill" || key === "webServerAutoStart") {
+        return typeof value === "boolean";
+    }
+    if (key.endsWith("RetentionDays"))
+        return Number.isSafeInteger(value) && value >= 1;
+    if (key === "memoryApiKey")
+        return isSecretReference(value);
+    if (key === "memoryProvider")
+        return MEMORY_PROVIDERS.includes(value);
+    // Entries are checked by the startup validation below.
+    if (key === "importPathMaps")
+        return Array.isArray(value);
+    return typeof value === "string" && value.trim().length > 0;
+}
 export class ConfigConflictError extends Error {
     status = 409;
     constructor() {
@@ -50,12 +82,11 @@ export async function writeGlobalConfigKeys(edits, expectedRevision) {
     for (const [key, value] of Object.entries(edits)) {
         if (!keys.has(key))
             throw new Error(`Setting ${key} cannot be edited here`);
-        if (key === "captureTrace" || key === "autoBackfill" || key === "webServerAutoStart"
-            ? typeof value !== "boolean"
-            : key.endsWith("RetentionDays")
-                ? !Number.isSafeInteger(value) || value < 1
-                : typeof value !== "string" || !value.trim()) {
-            throw new Error(`Invalid ${key} setting`);
+        if (!isValidEdit(key, value)) {
+            // Never echo the value: a rejected memoryApiKey may be a literal key.
+            throw new Error(key === "memoryApiKey"
+                ? "memoryApiKey must be an env:// or file:// reference"
+                : `Invalid ${key} setting`);
         }
     }
     const wasQueued = pending > 0;

package/dist/services/global-version.d.ts

@@ -0,0 +1,31 @@
+export interface GlobalCommandVersion {
+    /** The version the global `om-memory-system --version` printed, or null when not installed. */
+    version: string | null;
+    path: string | null;
+    error?: "timeout" | "failed";
+}
+type Runner = (file: string, args: string[], options: {
+    timeout: number;
+    windowsHide: boolean;
+    shell: false;
+}) => Promise<string>;
+/** The first `om-memory-system` on PATH; on Windows npm installs a `.cmd` wrapper. */
+export declare function findGlobalCommand(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, exists?: (path: string) => boolean): string | null;
+/**
+ * The command and arguments that print the version without a user-controlled
+ * shell. A Windows `.cmd` wrapper can only run through cmd.exe, so it runs
+ * through the system's own cmd.exe with fixed arguments.
+ */
+export declare function versionInvocation(path: string, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): {
+    file: string;
+    args: string[];
+};
+/** Look up the global command's version, at most once every 10 minutes. */
+export declare function globalCommandVersion(options?: {
+    now?: () => number;
+    runner?: Runner;
+    find?: () => string | null;
+    platform?: NodeJS.Platform;
+}): Promise<GlobalCommandVersion>;
+export declare function resetGlobalVersionCache(): void;
+export {};

package/dist/services/global-version.js

@@ -0,0 +1,78 @@
+import { execFile } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { delimiter, isAbsolute, join } from "node:path";
+const TIMEOUT_MS = 3_000;
+const CACHE_MS = 10 * 60_000;
+const run = (file, args, options) => new Promise((resolve, reject) => {
+    execFile(file, args, { ...options, encoding: "utf8" }, (error, stdout) => error ? reject(error) : resolve(String(stdout)));
+});
+function executable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The first `om-memory-system` on PATH; on Windows npm installs a `.cmd` wrapper. */
+export function findGlobalCommand(env = process.env, platform = process.platform, exists = executable) {
+    const names = platform === "win32" ? ["om-memory-system.exe", "om-memory-system.cmd"] : ["om-memory-system"];
+    const pathValue = env.PATH ?? env.Path ?? "";
+    for (const raw of pathValue.split(platform === "win32" ? ";" : delimiter)) {
+        const entry = raw.trim().replace(/^"(.*)"$/, "$1");
+        if (!entry || !(platform === "win32" ? /^[A-Za-z]:[\\/]|^\\\\/.test(entry) : isAbsolute(entry)))
+            continue;
+        for (const name of names) {
+            const candidate = platform === "win32" ? `${entry.replace(/[\\/]+$/, "")}\\${name}` : join(entry, name);
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * The command and arguments that print the version without a user-controlled
+ * shell. A Windows `.cmd` wrapper can only run through cmd.exe, so it runs
+ * through the system's own cmd.exe with fixed arguments.
+ */
+export function versionInvocation(path, platform = process.platform, env = process.env) {
+    if (platform === "win32" && path.toLowerCase().endsWith(".cmd")) {
+        const cmd = env.SystemRoot ? `${env.SystemRoot}\\System32\\cmd.exe` : "cmd.exe";
+        return { file: cmd, args: ["/d", "/s", "/c", `"${path}" --version`] };
+    }
+    return { file: path, args: ["--version"] };
+}
+let cached = null;
+/** Look up the global command's version, at most once every 10 minutes. */
+export async function globalCommandVersion(options = {}) {
+    const now = (options.now ?? Date.now)();
+    if (cached && now - cached.at < CACHE_MS)
+        return cached.value;
+    const path = (options.find ?? (() => findGlobalCommand()))();
+    let value;
+    if (!path) {
+        value = { version: null, path: null };
+    }
+    else {
+        const { file, args } = versionInvocation(path, options.platform);
+        try {
+            const output = await (options.runner ?? run)(file, args, {
+                timeout: TIMEOUT_MS,
+                windowsHide: true,
+                shell: false,
+            });
+            const version = /\d+\.\d+\.\d+(?:[-+][\w.]+)?/.exec(output)?.[0] ?? null;
+            value = version ? { version, path } : { version: null, path, error: "failed" };
+        }
+        catch (error) {
+            const killed = error.killed;
+            value = { version: null, path, error: killed ? "timeout" : "failed" };
+        }
+    }
+    cached = { at: now, value };
+    return value;
+}
+export function resetGlobalVersionCache() {
+    cached = null;
+}