@4da/mcp-server 6.0.2 → 6.1.0

package/dist/sqlite-driver.js

@@ -0,0 +1,359 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The SQLite driver: Node's built-in `node:sqlite` when the runtime has it,
+ * otherwise better-sqlite3, behind one interface.
+ *
+ * Why: npm 12 blocks dependency install scripts unless allowed, so a default
+ * `npx @4da/mcp-server` or `npm install` left better-sqlite3's native module
+ * unbuilt and every tool failed (measured 2026-10-03 on npm 12.2.0, see
+ * native-bindings.ts). `node:sqlite` ships inside Node: no install script, no
+ * native download. It is available without a flag from Node 22.13.0 (and
+ * 23.4.0); npm 12 itself requires Node ^22.22.2 || ^24.15.0 || >=26, so every
+ * npm 12 install has it. better-sqlite3 is an optional dependency now, used on
+ * Node 22.0-22.12 where it builds (npm 10 and 11 run its install script).
+ *
+ * The interface is the subset of better-sqlite3 this server uses: open
+ * options `readonly` / `fileMustExist`, prepare().get/all/run (positional
+ * parameters, arrays flattened, or one object of named parameters), exec,
+ * pragma (incl. `{ simple: true }`), transaction (nested calls become
+ * savepoints), close, and the `open` / `readonly` / `name` properties.
+ * better-sqlite3's Database satisfies it as is; node:sqlite is adapted
+ * (NodeSqliteDatabase) so that rows, BLOBs, error codes and the 5 s busy
+ * timeout match what the server's code already expects.
+ *
+ * `FOURDA_SQLITE_DRIVER=node|better` forces one driver (tests, diagnostics):
+ * a forced driver that cannot load is reported, never silently replaced.
+ * `none` simulates a host where neither works.
+ */
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import { checkNativeBindings, NATIVE_BINDING_FIX } from "./native-bindings.js";
+/** Thrown by sqliteDriver() when neither driver can open a database here. */
+export class SqliteUnavailableError extends Error {
+    code = "FOURDA_NO_SQLITE";
+}
+/** The first Node release with `node:sqlite` unflagged on the 22 line. */
+export const NODE_SQLITE_MIN = "22.13.0";
+// ---------------------------------------------------------------------------
+// node:sqlite adapter
+// ---------------------------------------------------------------------------
+/** Primary and extended SQLite result codes, by number, as better-sqlite3 names them. */
+const SQLITE_CODES = {
+    1: "SQLITE_ERROR", 2: "SQLITE_INTERNAL", 3: "SQLITE_PERM", 4: "SQLITE_ABORT", 5: "SQLITE_BUSY",
+    6: "SQLITE_LOCKED", 7: "SQLITE_NOMEM", 8: "SQLITE_READONLY", 9: "SQLITE_INTERRUPT", 10: "SQLITE_IOERR",
+    11: "SQLITE_CORRUPT", 12: "SQLITE_NOTFOUND", 13: "SQLITE_FULL", 14: "SQLITE_CANTOPEN", 15: "SQLITE_PROTOCOL",
+    16: "SQLITE_EMPTY", 17: "SQLITE_SCHEMA", 18: "SQLITE_TOOBIG", 19: "SQLITE_CONSTRAINT", 20: "SQLITE_MISMATCH",
+    21: "SQLITE_MISUSE", 22: "SQLITE_NOLFS", 23: "SQLITE_AUTH", 24: "SQLITE_FORMAT", 25: "SQLITE_RANGE",
+    26: "SQLITE_NOTADB",
+    261: "SQLITE_BUSY_RECOVERY", 517: "SQLITE_BUSY_SNAPSHOT", 773: "SQLITE_BUSY_TIMEOUT",
+    262: "SQLITE_LOCKED_SHAREDCACHE", 264: "SQLITE_READONLY_RECOVERY", 520: "SQLITE_READONLY_CANTLOCK",
+    776: "SQLITE_READONLY_ROLLBACK", 1032: "SQLITE_READONLY_DBMOVED", 267: "SQLITE_CORRUPT_VTAB",
+    275: "SQLITE_CONSTRAINT_CHECK", 787: "SQLITE_CONSTRAINT_FOREIGNKEY", 1299: "SQLITE_CONSTRAINT_NOTNULL",
+    1555: "SQLITE_CONSTRAINT_PRIMARYKEY", 2067: "SQLITE_CONSTRAINT_UNIQUE", 2579: "SQLITE_CONSTRAINT_ROWID",
+};
+/** better-sqlite3's error code for a SQLite result code (extended when known, else primary). */
+export function sqliteCodeName(errcode) {
+    return SQLITE_CODES[errcode] ?? SQLITE_CODES[errcode & 0xff] ?? `SQLITE_UNKNOWN_${errcode}`;
+}
+/**
+ * node:sqlite errors carry `code: "ERR_SQLITE_ERROR"` and the SQLite result
+ * code in `errcode`; the server's checks (unreadable database, BUSY/LOCKED
+ * retry) read better-sqlite3's `code: "SQLITE_BUSY"` form. Rewrite it in place.
+ */
+function normaliseError(error) {
+    const e = error;
+    if (e && typeof e === "object" && typeof e.errcode === "number") {
+        try {
+            Object.defineProperty(e, "code", { value: sqliteCodeName(e.errcode), writable: true, enumerable: true, configurable: true });
+        }
+        catch {
+            // A frozen error keeps its own code.
+        }
+    }
+    return error;
+}
+function guarded(fn) {
+    try {
+        return fn();
+    }
+    catch (error) {
+        throw normaliseError(error);
+    }
+}
+function isPlainParamObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) && !ArrayBuffer.isView(value) && !(value instanceof ArrayBuffer);
+}
+/** better-sqlite3's argument forms -> node:sqlite's (named object first, then positionals). */
+function bindArgs(params) {
+    let named = null;
+    const positional = [];
+    const add = (value) => {
+        if (Array.isArray(value))
+            value.forEach(add);
+        else if (isPlainParamObject(value))
+            named = { ...(named ?? {}), ...value };
+        else
+            positional.push(value);
+    };
+    params.forEach(add);
+    return named ? [named, ...positional] : positional;
+}
+function toNumber(value) {
+    // better-sqlite3 returns integers past 2^53 as (inexact) numbers; so do we.
+    return typeof value === "bigint" ? Number(value) : value;
+}
+/** A row as better-sqlite3 returns it: a plain object, BLOBs as Buffers. */
+function plainRow(row, bigints) {
+    if (row === undefined || row === null || typeof row !== "object")
+        return row;
+    const out = {};
+    for (const [key, value] of Object.entries(row)) {
+        out[key] =
+            value instanceof Uint8Array && !Buffer.isBuffer(value)
+                ? Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+                : bigints
+                    ? toNumber(value)
+                    : value;
+    }
+    return out;
+}
+function isOutOfRange(error) {
+    return error?.code === "ERR_OUT_OF_RANGE";
+}
+class NodeSqliteStatement {
+    stmt;
+    constructor(stmt) {
+        this.stmt = stmt;
+    }
+    /** Read once as numbers; an integer past 2^53 makes node:sqlite throw, so re-read as BigInts and convert. */
+    read(fn, args) {
+        const bound = bindArgs(args);
+        try {
+            return { value: fn(bound), bigints: false };
+        }
+        catch (error) {
+            if (!isOutOfRange(error))
+                throw normaliseError(error);
+            this.stmt.setReadBigInts(true);
+            try {
+                return { value: guarded(() => fn(bound)), bigints: true };
+            }
+            finally {
+                this.stmt.setReadBigInts(false);
+            }
+        }
+    }
+    run(...params) {
+        const result = guarded(() => this.stmt.run(...bindArgs(params)));
+        return { changes: Number(result.changes), lastInsertRowid: result.lastInsertRowid };
+    }
+    get(...params) {
+        const { value, bigints } = this.read((a) => this.stmt.get(...a), params);
+        return plainRow(value, bigints);
+    }
+    all(...params) {
+        const { value, bigints } = this.read((a) => this.stmt.all(...a), params);
+        return value.map((row) => plainRow(row, bigints));
+    }
+}
+/** better-sqlite3's default busy timeout, which the server's retry logic assumes. */
+const BUSY_TIMEOUT_MS = 5000;
+export class NodeSqliteDatabase {
+    name;
+    readonly;
+    db;
+    isOpen = true;
+    depth = 0;
+    savepoints = 0;
+    constructor(Ctor, file, options = {}) {
+        this.name = file;
+        this.readonly = options.readonly === true;
+        const inMemory = file === ":memory:" || file === "";
+        if (!inMemory && (options.fileMustExist || this.readonly) && !fs.existsSync(file)) {
+            // better-sqlite3's error for the same case.
+            throw Object.assign(new Error("unable to open database file"), { code: "SQLITE_CANTOPEN", errcode: 14 });
+        }
+        this.db = guarded(() => new Ctor(file, { readOnly: this.readonly }));
+        try {
+            this.db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+            // Belt and braces for the read-only contract on the desktop app's
+            // database: refused writes even if a runtime ignored `readOnly`.
+            if (this.readonly)
+                this.db.exec("PRAGMA query_only = ON");
+        }
+        catch (error) {
+            this.db.close();
+            throw normaliseError(error);
+        }
+    }
+    get open() {
+        return this.isOpen;
+    }
+    assertOpen() {
+        if (!this.isOpen)
+            throw new TypeError("The database connection is not open");
+    }
+    prepare(source) {
+        this.assertOpen();
+        return new NodeSqliteStatement(guarded(() => this.db.prepare(source)));
+    }
+    exec(source) {
+        this.assertOpen();
+        guarded(() => this.db.exec(source));
+        return this;
+    }
+    pragma(source, options) {
+        const rows = this.prepare(`PRAGMA ${source}`).all();
+        if (options?.simple) {
+            const first = rows[0];
+            return first ? Object.values(first)[0] : undefined;
+        }
+        return rows;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    transaction(fn) {
+        return (...args) => {
+            this.assertOpen();
+            const nested = this.depth > 0;
+            const savepoint = nested ? `fourda_sp_${++this.savepoints}` : null;
+            this.exec(savepoint ? `SAVEPOINT ${savepoint}` : "BEGIN");
+            this.depth++;
+            try {
+                const result = fn(...args);
+                this.exec(savepoint ? `RELEASE ${savepoint}` : "COMMIT");
+                return result;
+            }
+            catch (error) {
+                try {
+                    this.exec(savepoint ? `ROLLBACK TO ${savepoint}; RELEASE ${savepoint}` : "ROLLBACK");
+                }
+                catch {
+                    // SQLite already rolled back (e.g. after SQLITE_FULL); the original error matters.
+                }
+                throw error;
+            }
+            finally {
+                this.depth--;
+            }
+        };
+    }
+    close() {
+        if (this.isOpen) {
+            this.isOpen = false;
+            this.db.close();
+        }
+        return this;
+    }
+}
+// ---------------------------------------------------------------------------
+// Selection
+// ---------------------------------------------------------------------------
+const require = createRequire(import.meta.url);
+/** Load node:sqlite without its one-time "SQLite is an experimental feature" warning; every other warning passes. */
+export function loadNodeSqlite() {
+    const original = process.emitWarning;
+    process.emitWarning = function (warning, ...rest) {
+        const message = typeof warning === "string" ? warning : warning?.message;
+        const opt = rest[0];
+        const type = typeof opt === "string" ? opt : opt?.type ?? warning?.name;
+        if (type === "ExperimentalWarning" && /^SQLite is an experimental feature/.test(String(message)))
+            return;
+        return original.call(process, warning, ...rest);
+    };
+    try {
+        const mod = require("node:sqlite");
+        if (typeof mod.DatabaseSync !== "function")
+            throw new Error("node:sqlite has no DatabaseSync");
+        return mod.DatabaseSync;
+    }
+    finally {
+        process.emitWarning = original;
+    }
+}
+export function loadBetterSqlite3() {
+    const mod = require("better-sqlite3");
+    return typeof mod === "function" ? mod : mod.default;
+}
+function firstLine(error) {
+    return (error instanceof Error ? error.message : String(error)).split("\n")[0].trim();
+}
+function forcedDriver(env) {
+    const raw = env.FOURDA_SQLITE_DRIVER?.trim().toLowerCase();
+    if (!raw)
+        return null;
+    if (raw === "node" || raw === "node:sqlite")
+        return "node:sqlite";
+    if (raw === "better" || raw === "better-sqlite3")
+        return "better-sqlite3";
+    if (raw === "none")
+        return "none";
+    return null;
+}
+/**
+ * Pick the driver: node:sqlite, then better-sqlite3 if its native module
+ * actually opens a database (importing it succeeds without one). Pure apart
+ * from the loaders, so tests can make either one fail.
+ */
+export function resolveSqliteDriver(loaders = { node: loadNodeSqlite, better: loadBetterSqlite3 }, env = process.env) {
+    const forced = forcedDriver(env);
+    // "none" simulates a host where neither driver works (tests, diagnostics).
+    const order = forced === "none" ? [] : forced ? [forced] : ["node:sqlite", "better-sqlite3"];
+    const rejected = [];
+    for (const name of order) {
+        if (name === "node:sqlite") {
+            try {
+                const Ctor = loaders.node();
+                new NodeSqliteDatabase(Ctor, ":memory:").close();
+                return { driver: { name, open: (file, options) => new NodeSqliteDatabase(Ctor, file, options) }, rejected, problem: null };
+            }
+            catch (error) {
+                rejected.push({ name, reason: `not available in Node ${process.versions.node} (${firstLine(error)})` });
+            }
+        }
+        else {
+            let Ctor;
+            try {
+                Ctor = loaders.better();
+            }
+            catch (error) {
+                rejected.push({ name, reason: `not installed (${firstLine(error)})` });
+                continue;
+            }
+            const problem = checkNativeBindings(Ctor);
+            if (problem) {
+                rejected.push({ name, reason: problem });
+                continue;
+            }
+            return { driver: { name, open: (file, options) => new Ctor(file, options) }, rejected, problem: null };
+        }
+    }
+    const tried = rejected.map((r) => `${r.name}: ${r.reason}`).join("; ");
+    const problem = forced === "none"
+        ? "FOURDA_SQLITE_DRIVER=none disables SQLite: the database tools are unavailable. Unset it to let the server choose a driver."
+        : forced
+            ? `FOURDA_SQLITE_DRIVER=${env.FOURDA_SQLITE_DRIVER} forces ${forced}, which cannot be used here (${tried}). Unset it to let the server choose.`
+            : `No SQLite driver is usable (${tried}). Fix either one: upgrade Node.js to ${NODE_SQLITE_MIN} or later ` +
+                `(its built-in node:sqlite needs no install step), or let better-sqlite3 build: ${NATIVE_BINDING_FIX}`;
+    return { driver: null, rejected, problem };
+}
+let resolved = null;
+/** The resolution for this process (computed once). */
+export function sqliteDriverStatus() {
+    resolved ??= resolveSqliteDriver();
+    return resolved;
+}
+/** The driver in use; throws SqliteUnavailableError with the fix when there is none. */
+export function sqliteDriver() {
+    const status = sqliteDriverStatus();
+    if (!status.driver)
+        throw new SqliteUnavailableError(status.problem ?? "No SQLite driver is usable.");
+    return status.driver;
+}
+/** Open a database with the driver in use. */
+export function openDatabase(file, options) {
+    return sqliteDriver().open(file, options);
+}
+/** Forget the cached resolution (tests that change FOURDA_SQLITE_DRIVER). */
+export function resetSqliteDriver() {
+    resolved = null;
+}

package/dist/tool-dispatch.d.ts

@@ -11,6 +11,13 @@ import type { FourDADatabase } from "./db.js";
  * Awaiting a sync return resolves immediately, so we can await uniformly.
  */
 export type ToolExecutor = (db: FourDADatabase, params: any) => unknown | Promise<unknown>;
+/**
+ * Tools that answer from the project's lockfiles and the registries alone, so
+ * they still run when no SQLite driver is usable at all (sqlite-driver.ts:
+ * Node < 22.13 with better-sqlite3 unbuilt). Their executors accept a null
+ * database; every other tool needs one.
+ */
+export declare const DATABASE_FREE_TOOLS: ReadonlySet<string>;
 /**
  * Dispatch a tool call by name. Awaits uniformly (no-op for sync executors).
  * Returns MCP-formatted response with JSON-serialized result.
@@ -19,7 +26,7 @@ export type ToolExecutor = (db: FourDADatabase, params: any) => unknown | Promis
  * every tool call passes through. Stdio callers are unaffected (no auth
  * context; the host already owns the process).
  */
-export declare function dispatchTool(name: string, db: FourDADatabase, args: Record<string, unknown> | undefined): Promise<CallToolResult>;
+export declare function dispatchTool(name: string, db: FourDADatabase | null, args: Record<string, unknown> | undefined): Promise<CallToolResult>;
 /** What a desktop-only tool says when no desktop app database was found. */
 export declare function desktopAppNote(name: string): string;
 /** Check if a tool exists in the dispatch map */

package/dist/tool-dispatch.js

@@ -37,6 +37,18 @@ const DISPATCH_MAP = {
     // Identity
     developer_dna: executeDeveloperDna,
 };
+/**
+ * Tools that answer from the project's lockfiles and the registries alone, so
+ * they still run when no SQLite driver is usable at all (sqlite-driver.ts:
+ * Node < 22.13 with better-sqlite3 unbuilt). Their executors accept a null
+ * database; every other tool needs one.
+ */
+export const DATABASE_FREE_TOOLS = new Set([
+    "vulnerability_scan",
+    "dependency_health",
+    "dependency_check",
+    "upgrade_impact",
+]);
 /**
  * DB-backed tools whose payload reflects the curated feed and can therefore go stale. The MCP
  * server reads `4da.db` but cannot fetch or score, so these get a `data_freshness` annotation that
@@ -62,6 +74,9 @@ export async function dispatchTool(name, db, args) {
     if (!executor) {
         throw new Error(`Unknown tool: ${name}`);
     }
+    if (!db && !DATABASE_FREE_TOOLS.has(name)) {
+        throw new Error(`${name} needs a database, and none is open.`);
+    }
     assertToolPermission(name);
     // BUSY/LOCKED retry at the single choke point every tool passes through.
     // The desktop engine writes to the same database every 30 minutes; a read
@@ -86,11 +101,11 @@ export async function dispatchTool(name, db, args) {
     }
     // Feed freshness describes the desktop app's feed; a standalone install has
     // none, and telling it to "run fourda-engine" is noise.
-    const withFreshness = FRESHNESS_TOOLS.has(name) && !db.isStandalone;
+    const withFreshness = db !== null && FRESHNESS_TOOLS.has(name) && !db.isStandalone;
     // A desktop-only tool called without the desktop app's database (tools/list
     // hides these in standalone mode, but a host can call one by name) used to
     // answer `[]`, which reads as "nothing relevant" rather than "no app".
-    const desktopOnly = db.isStandalone && TOOL_REGISTRY[name]?.standalone === false;
+    const desktopOnly = db !== null && db.isStandalone && TOOL_REGISTRY[name]?.standalone === false;
     const payload = cleanStrings(withFreshness ? attachFreshness(db, result) : desktopOnly ? attachDesktopAppNote(name, result) : result);
     // An executor that returns `{ error: "<message>" }` failed: say so in the
     // protocol, not only in the body, so the host and model treat it as an error.

package/dist/tools/agent-memory.js

@@ -5,6 +5,7 @@
  * Cross-agent persistent memory. What Claude Code learns, Cursor can access.
  * Enables AI agents to store and recall memories across sessions and tools.
  */
+import { writeMeta, writerOf } from "../memory-store.js";
 import { rankRowsByRecall } from "./recall.js";
 import { getEmbeddingConfig, semanticScores, } from "../embeddings.js";
 // ============================================================================
@@ -149,8 +150,14 @@ export function executeAgentMemory(db, params) {
             }
             // --- Storage quota: max 1000 entries per agent ---
             const agentType = params.agent_type || "unknown";
+            // The app's own agent_memory table (separate write connection), or the
+            // server's store when the app's schema cannot hold the row.
+            const to = writerOf(db, "agent_memory", [
+                "session_id", "agent_type", "memory_type", "subject", "content", "context_tags", "expires_at",
+            ]);
             try {
-                const countRow = rawDb
+                // Counted where the row will go.
+                const countRow = (to.target === "server_store" ? to.raw : rawDb)
                     .prepare(`SELECT COUNT(*) as cnt FROM agent_memory WHERE agent_type = ?`)
                     .get(agentType);
                 const currentCount = countRow?.cnt ?? 0;
@@ -166,7 +173,7 @@ export function executeAgentMemory(db, params) {
                 };
             }
             try {
-                const stmt = rawDb.prepare(`INSERT INTO agent_memory
+                const stmt = to.raw.prepare(`INSERT INTO agent_memory
              (session_id, agent_type, memory_type, subject, content, context_tags, expires_at)
            VALUES (?, ?, ?, ?, ?, ?, ?)`);
                 const result = stmt.run(params.session_id || "unknown", params.agent_type || "unknown", params.memory_type || "context", params.subject, params.content, JSON.stringify(params.context_tags || []), params.expires_at || null);
@@ -174,6 +181,7 @@ export function executeAgentMemory(db, params) {
                     success: true,
                     id: result.lastInsertRowid,
                     message: `Memory stored: ${params.subject}`,
+                    ...writeMeta(to),
                 };
             }
             catch (error) {

package/dist/tools/app-plan.d.ts

@@ -76,12 +76,22 @@ export interface AppPlanResult {
     totalSteps: number;
     steps: AppPlanStepView[];
     summary: string;
+    /** The project the steps were narrowed to, or null for every project in the plan. */
+    projectScope: string | null;
+    /** Steps of the full plan that only touch other projects (left out by projectScope). */
+    otherProjectSteps?: number;
     snapshot: Omit<AppPlanSnapshot, "steps" | "generatedAt" | "expiresAt">;
     provenance: {
         mode: "app_plan";
         note: string;
     };
 }
+/**
+ * The steps that touch `scope` (a project directory): each step keeps only the
+ * installed lines with a site in that project, and those lines keep only
+ * those sites. Null keeps everything.
+ */
+export declare function scopeAppPlanSteps(steps: AppPlanStepView[], scope: string | null): AppPlanStepView[];
 /** Shape the app's plan as the tool result; `risk_threshold` / `max_recommendations` narrow it. */
 export declare function formatAppPlan(read: Extract<AppPlanRead, {
     kind: "plan";
@@ -89,4 +99,4 @@ export declare function formatAppPlan(read: Extract<AppPlanRead, {
     risk_threshold?: string;
     max_recommendations?: number;
     package?: string;
-}): AppPlanResult;
+}, scope?: string | null): AppPlanResult;

package/dist/tools/app-plan.js

@@ -14,6 +14,7 @@
  * APP_PLAN_SCHEMA_VERSION is treated as absent and the caller falls back to
  * its standalone heuristic.
  */
+import { isWithin } from "./project-scope.js";
 /** The snapshot schema this reader understands (Rust `PLAN_SCHEMA_VERSION`). */
 export const APP_PLAN_SCHEMA_VERSION = 4;
 const PLAN_KV_KEY = "upgrade_plan_snapshot";
@@ -93,13 +94,32 @@ export function readAppPlan(db, now = new Date()) {
 }
 const URGENCY_RISK = { critical: 3, high: 2, medium: 1, watch: 0 };
 const RISK_LEVELS = { low: 0, medium: 1, high: 2, critical: 3 };
+/**
+ * The steps that touch `scope` (a project directory): each step keeps only the
+ * installed lines with a site in that project, and those lines keep only
+ * those sites. Null keeps everything.
+ */
+export function scopeAppPlanSteps(steps, scope) {
+    if (!scope)
+        return steps;
+    const out = [];
+    for (const step of steps) {
+        const lines = step.lines
+            .map((line) => ({ ...line, sites: line.sites.filter((s) => isWithin(s.project, scope)) }))
+            .filter((line) => line.sites.length > 0);
+        if (lines.length > 0)
+            out.push({ ...step, lines });
+    }
+    return out;
+}
 const APP_PROVENANCE_NOTE = "The 4DA desktop app's own cross-project, version-confirmed Upgrade Plan, read from its database " +
     "(the same plan the app shows and `4da plan --json` prints). Each step is keyed by the app's item id.";
 /** Shape the app's plan as the tool result; `risk_threshold` / `max_recommendations` narrow it. */
-export function formatAppPlan(read, params) {
+export function formatAppPlan(read, params, scope = null) {
     const { snapshot, stale } = read;
     const threshold = params.risk_threshold ?? "all";
-    let steps = snapshot.steps;
+    const scoped = scopeAppPlanSteps(snapshot.steps, scope);
+    let steps = scoped;
     // `package` narrows the app's plan the same way it narrows the standalone one.
     const wanted = params.package?.trim().toLowerCase();
     if (wanted)
@@ -113,8 +133,9 @@ export function formatAppPlan(read, params) {
     const count = (m) => selected.filter((s) => s.mechanism === m).length;
     const majors = selected.filter((s) => s.lines.some((l) => l.upgrade_type === "major")).length;
     const parts = [
-        `${selected.length} step${selected.length !== 1 ? "s" : ""} from the 4DA app's plan (generated ${snapshot.generatedAt})`,
+        `${selected.length} step${selected.length !== 1 ? "s" : ""} from the 4DA app's plan (generated ${snapshot.generatedAt})${scope ? ` for ${scope}` : " across every project it tracks"}`,
     ];
+    const otherProjectSteps = snapshot.steps.length - scoped.length;
     if (count("manifest_bump") > 0)
         parts.push(`${count("manifest_bump")} manifest bump(s)`);
     if (count("lockfile_or_parent_update") > 0) {
@@ -126,8 +147,11 @@ export function formatAppPlan(read, params) {
         parts.push(`${count("no_fix")} with no fix published`);
     if (majors > 0)
         parts.push(`${majors} cross a major version`);
-    if (selected.length < snapshot.steps.length) {
-        parts.push(`${snapshot.steps.length} in the full plan (raise max_recommendations for the rest)`);
+    if (selected.length < scoped.length) {
+        parts.push(`${scoped.length} in ${scope ? "the plan for this project" : "the full plan"} (raise max_recommendations for the rest)`);
+    }
+    if (scope && otherProjectSteps > 0) {
+        parts.push(`${otherProjectSteps} step${otherProjectSteps !== 1 ? "s" : ""} only touch other projects (project_path "*" lists every project)`);
     }
     const staleness = stale
         ? `STALE: past its freshness horizon (${snapshot.expiresAt}). The advisories or installs may have changed since; open the 4DA app to recompute.`
@@ -139,9 +163,11 @@ export function formatAppPlan(read, params) {
         expiresAt: snapshot.expiresAt,
         stale,
         staleness,
-        totalSteps: snapshot.steps.length,
+        totalSteps: scoped.length,
         steps: selected,
         summary: parts.join(". ") + ".",
+        projectScope: scope,
+        ...(scope ? { otherProjectSteps } : {}),
         snapshot: {
             schemaVersion: snapshot.schemaVersion,
             generatorVersion: snapshot.generatorVersion,

package/dist/tools/briefing-task-scope.d.ts

@@ -23,6 +23,8 @@ export interface TaskPackage {
     /** Versions the task text names after the package ("5.x to 7.x" -> from 5.x, to 7.x). */
     requested_from: string | null;
     requested_to: string | null;
+    /** Set when the package was found through a family the task names ("all tauri plugins" -> "tauri"). */
+    family?: string;
 }
 /**
  * Package names that are also everyday words. One of these counts as named
@@ -36,8 +38,25 @@ export declare const COMMON_WORDS: Set<string>;
  * Direct dependencies first; at most `limit` packages.
  */
 export declare function detectTaskPackages(task: string, files: string[], deps: ResolvedDependency[], limit?: number): TaskPackage[];
-/** Major version of a version or a `7.x` / `v7` request; null when unreadable. */
-export declare function majorOf(version: string | null): number | null;
+/**
+ * The package families a task names, as base names: "all tauri plugins",
+ * "tauri and its plugins", "@tauri-apps packages", "tauri-plugin-*",
+ * "@tauri-apps/*". A name alone ("bump tauri") is not a family.
+ */
+export declare function detectFamilyBases(task: string, files?: string[]): string[];
+/** True when `name` belongs to the family of `base`: base-*, base_*, @base/*, @base-apps/*. */
+export declare function inFamily(name: string, base: string): boolean;
+/**
+ * The direct dependencies in the families the task names, other than the
+ * packages it names exactly. Only packages this project actually declares:
+ * a family is expanded against the lockfiles, never guessed. Measured
+ * 2026-10-07: "bump tauri and all tauri plugins" matched only `tauri`.
+ */
+export declare function detectFamilyPackages(task: string, files: string[], deps: ResolvedDependency[], exact: TaskPackage[], limit?: number): TaskPackage[];
+/** True when the task asks for the newest release ("to latest", "newest major"). */
+export declare function wantsLatest(task: string): boolean;
+/** The caret line a version sits on: "2" for 2.12.1, "0.13" for 0.13.5. */
+export declare function caretLine(version: string | null): string | null;
 /** Actionable advisories on the installed copies of one package, highest presented severity first. */
 export declare function advisoriesFor(pkg: TaskPackage, vulns: VulnerabilityEntry[]): {
     id: string;