claude-flow 3.57.2 → 3.58.1

package/v3/@claude-flow/cli/dist/src/memory/memory-peek.js

@@ -0,0 +1,222 @@
+/**
+ * #3508: read-only memory route/peek.
+ *
+ * A health check needs to know which memory store files a cwd resolves to,
+ * and what is in them, without changing anything to find out. `memory stats`
+ * (even after #3463/#3448) still calls `ensureInitialized()` when no explicit
+ * path is given, and answers for one file per call. This module reports
+ * BOTH files — the sql.js `memory.db` the CLI writes and its native
+ * `agentdb-memory.db` sibling the MCP/bridge path writes — in one read-only
+ * pass, and says which resolution rule picked the root.
+ *
+ * Contract (do not relax without re-reading #3508):
+ *   - never creates, initializes, or migrates anything;
+ *   - never opens a file that does not exist (`existsSync` gated before any
+ *     open attempt, for both engines);
+ *   - every open is `readonly`/`fileMustExist` (native) or a one-shot byte
+ *     buffer handed to sql.js, which is never written back to disk;
+ *   - `rows: null` means "could not read" and is never a count of 0, so an
+ *     empty store and an unreadable one never look the same;
+ *   - an encrypted-at-rest `memory.db` reports `encrypted: true` and
+ *     `rows: null`, but its size is still reported.
+ */
+import { closeSync, existsSync, openSync, readFileSync, readSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { getMemoryRoot, resolveDbPath } from './memory-initializer.js';
+import { siblingAgentDbPath } from './memory-bridge.js';
+import { isEncryptedBlob } from '../encryption/vault.js';
+// Mirrors the `ACTIVE_MEMORY_ROW_SQL` convention in memory-initializer.ts:
+// legacy rows with a NULL status predate soft-delete semantics and count.
+const ACTIVE_ROW_SQL = `(status = 'active' OR status IS NULL)`;
+const ENCRYPTION_SNIFF_LEN = 64; // RFE1 magic(4)+iv(12)+tag(16); 64 gives headroom.
+function safeStatSize(filePath) {
+    try {
+        return statSync(filePath).size;
+    }
+    catch {
+        return null;
+    }
+}
+function readHeaderBytes(filePath, len) {
+    const fd = openSync(filePath, 'r');
+    try {
+        const buf = Buffer.alloc(len);
+        const bytesRead = readSync(fd, buf, 0, len, 0);
+        return buf.subarray(0, bytesRead);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function latestMillis(values) {
+    let latest = -Infinity;
+    for (const raw of values) {
+        const millis = typeof raw === 'number' ? raw : Number(raw);
+        if (Number.isFinite(millis))
+            latest = Math.max(latest, millis);
+    }
+    return latest;
+}
+/** sql.js is read as a one-shot in-memory byte buffer — nothing is ever
+ * written back, so reading this file has no on-disk side effect. */
+async function probeSqlJsStore(dbPath) {
+    try {
+        if (isEncryptedBlob(readHeaderBytes(dbPath, ENCRYPTION_SNIFF_LEN))) {
+            return { rows: null, lastWrite: null, keys: null, encrypted: true };
+        }
+    }
+    catch {
+        /* header read failed (permissions/race) — fall through to the open attempt */
+    }
+    try {
+        const initSqlJs = (await import('sql.js')).default ?? (await import('sql.js'));
+        const SQL = await (typeof initSqlJs === 'function' ? initSqlJs() : initSqlJs.default());
+        const buf = readFileSync(dbPath);
+        const db = new SQL.Database(new Uint8Array(buf));
+        try {
+            const tables = db.exec("SELECT name FROM sqlite_master WHERE type='table' AND name='memory_entries'");
+            if (!tables.length)
+                return { rows: null, lastWrite: null, keys: null };
+            const result = db.exec(`SELECT namespace, key, created_at, updated_at FROM memory_entries WHERE ${ACTIVE_ROW_SQL}`);
+            const values = result[0]?.values ?? [];
+            const keys = new Set();
+            let last = -Infinity;
+            for (const [namespace, key, createdAt, updatedAt] of values) {
+                keys.add(`${String(namespace)}\u0000${String(key)}`);
+                last = Math.max(last, latestMillis([createdAt, updatedAt]));
+            }
+            return {
+                rows: values.length,
+                lastWrite: Number.isFinite(last) ? new Date(last).toISOString() : null,
+                keys,
+            };
+        }
+        finally {
+            try {
+                db.close();
+            }
+            catch { /* best effort */ }
+        }
+    }
+    catch {
+        return { rows: null, lastWrite: null, keys: null };
+    }
+}
+/** better-sqlite3 is an optional native dependency — absence must degrade
+ * to "could not read", never throw. Opened `readonly`/`fileMustExist`, same
+ * as `countSiblingStoreRows` in sibling-store.ts. */
+async function probeNativeStore(dbPath) {
+    try {
+        const require = (await import('node:module')).createRequire(import.meta.url);
+        const Database = require('better-sqlite3');
+        const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+        try {
+            const table = db
+                .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='memory_entries'")
+                .get();
+            if (!table)
+                return { rows: null, lastWrite: null, keys: null };
+            const rows = db
+                .prepare(`SELECT namespace, key, created_at, updated_at FROM memory_entries WHERE ${ACTIVE_ROW_SQL}`)
+                .all();
+            const keys = new Set();
+            let last = -Infinity;
+            for (const row of rows) {
+                keys.add(`${String(row.namespace)}\u0000${String(row.key)}`);
+                last = Math.max(last, latestMillis([row.created_at, row.updated_at]));
+            }
+            return {
+                rows: rows.length,
+                lastWrite: Number.isFinite(last) ? new Date(last).toISOString() : null,
+                keys,
+            };
+        }
+        finally {
+            try {
+                db.close();
+            }
+            catch { /* best effort */ }
+        }
+    }
+    catch {
+        return { rows: null, lastWrite: null, keys: null };
+    }
+}
+/** Same precedence `getMemoryRoot()`/`resolveDbPath()` already own — this
+ * only *labels* which rule decided, it never re-derives the path itself. */
+function decideSource(cliFlag) {
+    if (cliFlag && cliFlag.trim().length > 0)
+        return 'path';
+    if (process.env.CLAUDE_FLOW_DB_PATH && process.env.CLAUDE_FLOW_DB_PATH.trim().length > 0) {
+        return 'CLAUDE_FLOW_DB_PATH';
+    }
+    if (process.env.CLAUDE_FLOW_MEMORY_PATH && process.env.CLAUDE_FLOW_MEMORY_PATH.trim().length > 0) {
+        return 'CLAUDE_FLOW_MEMORY_PATH';
+    }
+    const configCandidates = [
+        path.resolve(process.cwd(), 'claude-flow.config.json'),
+        path.resolve(process.cwd(), '.claude-flow', 'config.json'),
+    ];
+    for (const configPath of configCandidates) {
+        if (!existsSync(configPath))
+            continue;
+        try {
+            const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+            const fromConfig = raw?.memory?.persistPath ?? raw?.memory?.path;
+            if (typeof fromConfig === 'string' && fromConfig.trim().length > 0)
+                return 'config';
+        }
+        catch {
+            /* malformed config — getMemoryRoot() falls through to default too */
+        }
+    }
+    return 'default';
+}
+async function describeStore(role, storePath, probe) {
+    if (!existsSync(storePath)) {
+        return {
+            store: { role, path: storePath, exists: false, rows: null, lastWrite: null, sizeBytes: null, walBytes: null },
+            keys: null,
+        };
+    }
+    const result = await probe(storePath);
+    const sizeBytes = safeStatSize(storePath);
+    const walBytes = safeStatSize(`${storePath}-wal`) ?? 0;
+    return {
+        store: {
+            role,
+            path: storePath,
+            exists: true,
+            rows: result.rows,
+            lastWrite: result.lastWrite,
+            sizeBytes,
+            walBytes,
+            ...(result.encrypted ? { encrypted: true } : {}),
+        },
+        keys: result.keys,
+    };
+}
+/**
+ * Resolve the route and report both stores, read-only. Never creates,
+ * initializes, or migrates anything, on an empty project or any other.
+ */
+export async function memoryPeek(opts) {
+    const cliFlag = opts?.path;
+    const cliPath = resolveDbPath(cliFlag);
+    const mcpPath = siblingAgentDbPath(cliPath);
+    const root = { path: cliFlag ? path.dirname(cliPath) : getMemoryRoot(), source: decideSource(cliFlag) };
+    const cliDescribed = await describeStore('cli', cliPath, probeSqlJsStore);
+    const stores = [cliDescribed.store];
+    let mcpKeys = null;
+    if (mcpPath) {
+        const mcpDescribed = await describeStore('mcp', mcpPath, probeNativeStore);
+        stores.push(mcpDescribed.store);
+        mcpKeys = mcpDescribed.keys;
+    }
+    const cliKeys = cliDescribed.keys;
+    const sharedKeys = cliKeys && mcpKeys
+        ? [...cliKeys].filter((key) => mcpKeys.has(key)).length
+        : null;
+    return { cwd: process.cwd(), root, stores, sharedKeys };
+}
+//# sourceMappingURL=memory-peek.js.map

package/v3/@claude-flow/cli/dist/src/memory/model-cache-dir.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolve a writable cache directory for ONNX model downloads.
+ *
+ * ADR-454: duplicated intentionally from
+ * `@claude-flow/embeddings/src/transformers-loader.ts`'s
+ * `resolveModelCacheDir()` rather than imported, since `@claude-flow/cli`
+ * has no dependency on `@claude-flow/embeddings` (see the circular
+ * optional-dep note in `memory-initializer.ts`).
+ */
+export declare function resolveModelCacheDir(): string;
+//# sourceMappingURL=model-cache-dir.d.ts.map

package/v3/@claude-flow/cli/dist/src/memory/model-cache-dir.js

@@ -0,0 +1,17 @@
+import * as os from 'node:os';
+import * as path from 'node:path';
+/**
+ * Resolve a writable cache directory for ONNX model downloads.
+ *
+ * ADR-454: duplicated intentionally from
+ * `@claude-flow/embeddings/src/transformers-loader.ts`'s
+ * `resolveModelCacheDir()` rather than imported, since `@claude-flow/cli`
+ * has no dependency on `@claude-flow/embeddings` (see the circular
+ * optional-dep note in `memory-initializer.ts`).
+ */
+export function resolveModelCacheDir() {
+    return (process.env.TRANSFORMERS_CACHE ||
+        process.env.HF_HOME ||
+        path.join(os.homedir(), '.cache', 'ruflo', 'models'));
+}
+//# sourceMappingURL=model-cache-dir.js.map

package/v3/@claude-flow/cli/dist/src/parser.js

@@ -184,8 +184,9 @@ export class CommandParser {
         let commandSlotAvailable = true;
         while (i < args.length) {
             const arg = args[i];
-            // Check for end of flags marker
-            if (arg === '--') {
+            // Check for end of flags marker. Only the first "--" changes parser
+            // state; a later literal "--" is an ordinary positional (#4310).
+            if (parsingFlags && arg === '--') {
                 parsingFlags = false;
                 i++;
                 continue;

package/v3/@claude-flow/cli/dist/src/ruvector/task-embedder.js

@@ -19,6 +19,8 @@
  *
  * @module task-embedder
  */
+import * as fs from 'node:fs';
+import { resolveModelCacheDir } from '../memory/model-cache-dir.js';
 // ============================================================================
 // FNV-1a-32 hash (matches scripts/gen-seed-corpus.mjs + router-trajectory.ts)
 // ============================================================================
@@ -38,18 +40,48 @@ function cacheKey(task) {
 // same function (xenova's pipeline returns a callable that accepts either),
 // so we don't pay the ONNX model-load cost twice.
 let _extractorPromise = null;
+/**
+ * ADR-454: distinguishes a null-extractor result caused by a genuinely
+ * missing dependency (permanent — nothing changes without a reinstall) from
+ * one caused by an environmental/fixable failure during `pipeline(...)`
+ * init, such as EACCES on the model cache dir (retryable).
+ */
+let _extractorDegradedReason = null;
+let _extractorLastAttemptAt = 0;
+const EXTRACTOR_RETRY_INTERVAL_MS = 60_000;
 function loadExtractor() {
-    if (_extractorPromise !== null)
-        return _extractorPromise;
+    if (_extractorPromise !== null) {
+        const isRetryableDue = _extractorDegradedReason === 'retryable' &&
+            Date.now() - _extractorLastAttemptAt >= EXTRACTOR_RETRY_INTERVAL_MS;
+        if (!isRetryableDue)
+            return _extractorPromise;
+        // Fall through to re-attempt — the retryable failure may now be fixed.
+    }
+    _extractorLastAttemptAt = Date.now();
     _extractorPromise = (async () => {
+        let packageImportable = false;
         try {
             const specifier = '@xenova/transformers';
             const mod = await import(/* @vite-ignore */ specifier).catch(() => null);
-            if (!mod || typeof mod.pipeline !== 'function')
+            if (!mod || typeof mod.pipeline !== 'function') {
+                _extractorDegradedReason = 'permanent';
                 return null;
-            return await mod.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { quantized: true });
+            }
+            packageImportable = true;
+            // ADR-454: route model downloads to a user-writable cache dir — the
+            // package-relative default is root-owned under a system-prefix
+            // global install, which throws EACCES for the runtime user.
+            const cacheDir = resolveModelCacheDir();
+            fs.mkdirSync(cacheDir, { recursive: true });
+            const env = mod.env;
+            if (env)
+                env.cacheDir = cacheDir;
+            const extractor = await mod.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { quantized: true });
+            _extractorDegradedReason = null;
+            return extractor;
         }
         catch {
+            _extractorDegradedReason = packageImportable ? 'retryable' : 'permanent';
             return null;
         }
     })();
@@ -233,5 +265,7 @@ export function __resetTaskEmbedderForTests() {
     _hits = 0;
     _misses = 0;
     _extractorPromise = null;
+    _extractorDegradedReason = null;
+    _extractorLastAttemptAt = 0;
 }
 //# sourceMappingURL=task-embedder.js.map

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.57.2",
+  "version": "3.58.1",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",