projscan 1.2.1 → 1.4.0

package/dist/mcp/sessionTouchScanner.js

@@ -0,0 +1,112 @@
+/**
+ * Walk an arbitrary tool-result value and pull out repo-relative file
+ * paths. Used by the MCP server dispatcher to auto-record session
+ * touches after every tools/call response.
+ *
+ * Heuristic: collect string values found under any of TOUCH_KEYS, in
+ * arrays whose keys are TOUCH_KEYS, or as top-level entries in objects
+ * keyed by TOUCH_KEYS. Filter out paths that look absolute, contain
+ * `..`, are URLs, or are clearly not source files (no `/` and no
+ * recognized extension).
+ *
+ * The goal isn't to find *every* mention — it's to recognize the file
+ * paths that projscan tools structurally surface (relativePath fields,
+ * `paths` arrays from notifications, importer lists, etc.).
+ */
+const TOUCH_KEYS = new Set([
+    'file',
+    'files',
+    'filePath',
+    'path',
+    'paths',
+    'relativePath',
+    'relativePaths',
+    'from',
+    'to',
+    'definitions',
+    'importers',
+    'reachable',
+    'changed',
+    'added',
+    'removed',
+    'modified',
+]);
+const KNOWN_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.mts',
+    '.cts',
+    '.py',
+    '.go',
+    '.java',
+    '.rb',
+    '.rs',
+    '.php',
+    '.cs',
+    '.json',
+    '.yaml',
+    '.yml',
+    '.toml',
+    '.md',
+]);
+const MAX_DEPTH = 8;
+const MAX_PATHS = 200;
+export function extractTouchedPaths(value) {
+    const out = new Set();
+    walk(value, /* keyHint */ null, /* depth */ 0, out);
+    return [...out].slice(0, MAX_PATHS);
+}
+function walk(value, keyHint, depth, out) {
+    if (out.size >= MAX_PATHS)
+        return;
+    if (depth > MAX_DEPTH)
+        return;
+    if (value == null)
+        return;
+    if (typeof value === 'string') {
+        if (keyHint && TOUCH_KEYS.has(keyHint) && looksLikePath(value)) {
+            out.add(value);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        // For an array, propagate the parent's key hint so `paths: [...]`
+        // captures every entry.
+        for (const item of value)
+            walk(item, keyHint, depth + 1, out);
+        return;
+    }
+    if (typeof value === 'object') {
+        for (const [k, v] of Object.entries(value)) {
+            walk(v, k, depth + 1, out);
+        }
+    }
+}
+function looksLikePath(s) {
+    if (s.length === 0 || s.length > 1024)
+        return false;
+    if (s.includes('..'))
+        return false;
+    if (s.startsWith('/'))
+        return false;
+    if (s.startsWith('http://') || s.startsWith('https://'))
+        return false;
+    if (s.startsWith('file://'))
+        return false;
+    // Disallow shell control chars and newlines.
+    if (/[\n\r\t]/.test(s))
+        return false;
+    // Accept either: contains `/` (suggests a path) OR has a known extension.
+    const dot = s.lastIndexOf('.');
+    const hasKnownExt = dot >= 0 && KNOWN_EXTENSIONS.has(s.slice(dot).toLowerCase());
+    if (hasKnownExt)
+        return true;
+    if (s.includes('/') && /^[A-Za-z0-9._/@-]+$/.test(s))
+        return true;
+    return false;
+}
+//# sourceMappingURL=sessionTouchScanner.js.map

package/dist/mcp/sessionTouchScanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionTouchScanner.js","sourceRoot":"","sources":["../../src/mcp/sessionTouchScanner.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/session.d.ts

@@ -0,0 +1,22 @@
+import type { McpTool } from './_shared.js';
+import { type SessionTouch } from '../../core/session.js';
+/**
+ * `projscan_session` (1.4+) — surface the current durable session so an
+ * agent (or a coordinated swarm of agents) can ask "what's been touched
+ * since I arrived?" without re-running git status / grep.
+ *
+ * Subactions:
+ *   - "current" (default): session metadata (id, age, touched-file count, event count).
+ *   - "touched": list of files touched in the current session. Sorted by
+ *     last-touched descending. Filterable by source (`tool-result` /
+ *     `fs-watch` / `explicit`) and supports cursor pagination.
+ *   - "events": chronological event log. Bounded to the most recent 500.
+ *   - "reset": discard the current session and start a fresh one. Useful
+ *     when the agent is starting a new task and wants a clean slate.
+ *
+ * The session itself is populated by other paths in projscan (tool-call
+ * dispatcher records auto-touches; `mcp --watch` records fs.watch events).
+ * This tool is read-only except for the `reset` subaction.
+ */
+export declare const sessionTool: McpTool;
+export type { SessionTouch };

package/dist/mcp/tools/session.js

@@ -0,0 +1,140 @@
+import { loadSession, resetSession, saveSession, } from '../../core/session.js';
+/**
+ * `projscan_session` (1.4+) — surface the current durable session so an
+ * agent (or a coordinated swarm of agents) can ask "what's been touched
+ * since I arrived?" without re-running git status / grep.
+ *
+ * Subactions:
+ *   - "current" (default): session metadata (id, age, touched-file count, event count).
+ *   - "touched": list of files touched in the current session. Sorted by
+ *     last-touched descending. Filterable by source (`tool-result` /
+ *     `fs-watch` / `explicit`) and supports cursor pagination.
+ *   - "events": chronological event log. Bounded to the most recent 500.
+ *   - "reset": discard the current session and start a fresh one. Useful
+ *     when the agent is starting a new task and wants a clean slate.
+ *
+ * The session itself is populated by other paths in projscan (tool-call
+ * dispatcher records auto-touches; `mcp --watch` records fs.watch events).
+ * This tool is read-only except for the `reset` subaction.
+ */
+export const sessionTool = {
+    name: 'projscan_session',
+    description: 'Inspect the durable cross-invocation session: which files have been touched in this session, by what (tool result / fs watch / explicit), and the event log. Use to coordinate across multi-agent setups without re-querying git.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['current', 'touched', 'events', 'reset'],
+                description: 'Subaction. Default "current" returns session metadata. "touched" returns the touched-file list. "events" returns the event log. "reset" discards the current session and starts a fresh one.',
+            },
+            source: {
+                type: 'string',
+                enum: ['tool-result', 'fs-watch', 'explicit'],
+                description: '"touched" only — restrict to files added by this source. Omit for all sources.',
+            },
+            cursor: {
+                type: 'string',
+                description: 'Opaque cursor for pagination (touched / events lists).',
+            },
+            page_size: {
+                type: 'integer',
+                description: 'Page size for paginated lists. Default 50, max 500.',
+            },
+        },
+    },
+    handler: async (args, rootPath) => {
+        const action = typeof args.action === 'string' ? args.action : 'current';
+        const { session } = await loadSession(rootPath);
+        switch (action) {
+            case 'current':
+                return summarizeSession(session);
+            case 'touched':
+                return touchedView(session, args);
+            case 'events':
+                return eventsView(session, args);
+            case 'reset': {
+                const fresh = await resetSession(rootPath);
+                return {
+                    action: 'reset',
+                    previousSessionId: session.id,
+                    newSession: summarizeSession(fresh),
+                };
+            }
+            default:
+                throw new Error(`Unknown action "${action}". Valid actions: current, touched, events, reset.`);
+        }
+        // Unreachable, but keeps the path that may add a `saveSession` later
+        // explicit. The current handler reads only; nothing to persist.
+        void saveSession;
+    },
+};
+function summarizeSession(session) {
+    const startedAtMs = Date.parse(session.startedAt);
+    const lastActivityMs = Date.parse(session.lastActivityAt);
+    const ageMs = Number.isFinite(lastActivityMs) ? Date.now() - startedAtMs : null;
+    return {
+        id: session.id,
+        startedAt: session.startedAt,
+        lastActivityAt: session.lastActivityAt,
+        ageMs,
+        touchedFileCount: Object.keys(session.touchedFiles).length,
+        eventCount: session.events.length,
+    };
+}
+function touchedView(session, args) {
+    const sourceFilter = typeof args.source === 'string' ? args.source : undefined;
+    const all = Object.values(session.touchedFiles);
+    const filtered = sourceFilter ? all.filter((t) => t.source === sourceFilter) : all;
+    // Sort by lastTouchedAt descending (most recently touched first).
+    filtered.sort((a, b) => b.lastTouchedAt.localeCompare(a.lastTouchedAt));
+    const { items, nextCursor } = paginate(filtered, args);
+    return {
+        sessionId: session.id,
+        total: filtered.length,
+        touched: items,
+        ...(nextCursor ? { nextCursor } : {}),
+    };
+}
+function eventsView(session, args) {
+    // Newest-first for the consumer; the underlying log is append-order.
+    const reversed = [...session.events].reverse();
+    const { items, nextCursor } = paginate(reversed, args);
+    return {
+        sessionId: session.id,
+        total: reversed.length,
+        events: items,
+        ...(nextCursor ? { nextCursor } : {}),
+    };
+}
+function paginate(arr, args) {
+    const pageSize = clampPageSize(args.page_size);
+    const offset = decodeOffset(args.cursor);
+    const slice = arr.slice(offset, offset + pageSize);
+    const next = offset + pageSize;
+    const nextCursor = next < arr.length ? encodeOffset(next) : undefined;
+    return { items: slice, nextCursor };
+}
+function clampPageSize(raw) {
+    if (typeof raw !== 'number' || !Number.isFinite(raw))
+        return 50;
+    return Math.max(1, Math.min(500, Math.floor(raw)));
+}
+function encodeOffset(offset) {
+    return Buffer.from(JSON.stringify({ offset }), 'utf-8').toString('base64');
+}
+function decodeOffset(cursor) {
+    if (typeof cursor !== 'string' || cursor.length === 0)
+        return 0;
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, 'base64').toString('utf-8'));
+        if (parsed && typeof parsed.offset === 'number' && Number.isFinite(parsed.offset)) {
+            return Math.max(0, Math.floor(parsed.offset));
+        }
+    }
+    catch {
+        // Bad cursor — restart from offset 0.
+    }
+    return 0;
+}
+//# sourceMappingURL=session.js.map

package/dist/mcp/tools/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/mcp/tools/session.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/upgrade.js

@@ -3,7 +3,7 @@ import { previewUpgrade } from '../../core/upgradePreview.js';
 import { isPythonDominated } from './_shared.js';
 export const upgradeTool = {
     name: 'projscan_upgrade',
-    description: 'Preview the impact of upgrading a package: semver drift, breaking-change markers from the local CHANGELOG, and the files in your repo that import it. Offline.',
+    description: 'Preview the impact of upgrading a package: semver drift, breaking-change markers from the local CHANGELOG, and the files in your repo that import it. Offline by default; pass `check_registry: true` (1.3+) to fetch the actual latest version from npm.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -11,6 +11,10 @@ export const upgradeTool = {
                 type: 'string',
                 description: 'Name of the package to preview.',
             },
+            check_registry: {
+                type: 'boolean',
+                description: '1.3+ — when true, fetch the latest version from registry.npmjs.org (network-required). Default false: latest is treated as the installed version.',
+            },
         },
         required: ['package'],
     },
@@ -18,6 +22,7 @@ export const upgradeTool = {
         const pkgName = typeof args.package === 'string' ? args.package : '';
         if (!pkgName)
             throw new Error('package argument is required');
+        const checkRegistry = args.check_registry === true;
         const scan = await scanRepository(rootPath);
         if (await isPythonDominated(rootPath, scan.files)) {
             return {
@@ -32,7 +37,7 @@ export const upgradeTool = {
                 importers: [],
             };
         }
-        return await previewUpgrade(rootPath, pkgName, scan.files);
+        return await previewUpgrade(rootPath, pkgName, scan.files, { checkRegistry });
     },
 };
 //# sourceMappingURL=upgrade.js.map

package/dist/mcp/tools/upgrade.js.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../../../src/mcp/tools/upgrade.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAgB,MAAM,cAAc,CAAC;AAE/D,MAAM,CAAC,MAAM,WAAW,GAAY;IAClC,IAAI,EAAE,kBAAkB;IACxB,WAAW,EACT,gKAAgK;IAClK,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,iCAAiC;aAC/C;SACF;QACD,QAAQ,EAAE,CAAC,SAAS,CAAC;KACtB;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;QAChC,MAAM,OAAO,GAAG,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAC9D,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC;QAE5C,IAAI,MAAM,iBAAiB,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAClD,OAAO;gBACL,SAAS,EAAE,KAAK;gBAChB,MAAM,EACJ,mHAAmH;gBACrH,IAAI,EAAE,OAAO;gBACb,QAAQ,EAAE,IAAI;gBACd,SAAS,EAAE,IAAI;gBACf,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE,SAAS;gBAChB,eAAe,EAAE,EAAE;gBACnB,SAAS,EAAE,EAAE;aACd,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7D,CAAC;CACF,CAAC"}
+{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../../../src/mcp/tools/upgrade.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAgB,MAAM,cAAc,CAAC;AAE/D,MAAM,CAAC,MAAM,WAAW,GAAY;IAClC,IAAI,EAAE,kBAAkB;IACxB,WAAW,EACT,2PAA2P;IAC7P,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,iCAAiC;aAC/C;YACD,cAAc,EAAE;gBACd,IAAI,EAAE,SAAS;gBACf,WAAW,EACT,mJAAmJ;aACtJ;SACF;QACD,QAAQ,EAAE,CAAC,SAAS,CAAC;KACtB;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;QAChC,MAAM,OAAO,GAAG,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAC9D,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,KAAK,IAAI,CAAC;QACnD,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC;QAE5C,IAAI,MAAM,iBAAiB,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAClD,OAAO;gBACL,SAAS,EAAE,KAAK;gBAChB,MAAM,EACJ,mHAAmH;gBACrH,IAAI,EAAE,OAAO;gBACb,QAAQ,EAAE,IAAI;gBACd,SAAS,EAAE,IAAI;gBACf,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE,SAAS;gBAChB,eAAe,EAAE,EAAE;gBACnB,SAAS,EAAE,EAAE;aACd,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC;IAChF,CAAC;CACF,CAAC"}

package/dist/mcp/tools.js

@@ -28,6 +28,7 @@ import { fixSuggestTool } from './tools/fixSuggest.js';
 import { explainIssueTool } from './tools/explainIssue.js';
 import { impactTool } from './tools/impact.js';
 import { searchTool } from './tools/search.js';
+import { sessionTool } from './tools/session.js';
 const tools = [
     analyzeTool,
     doctorTool,
@@ -49,6 +50,7 @@ const tools = [
     explainIssueTool,
     impactTool,
     searchTool,
+    sessionTool,
 ];
 export function getToolDefinitions() {
     return tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema }));

package/dist/mcp/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAM/C,MAAM,KAAK,GAAc;IACvB,WAAW;IACX,UAAU;IACV,YAAY;IACZ,WAAW;IACX,QAAQ;IACR,aAAa;IACb,gBAAgB;IAChB,YAAY;IACZ,SAAS;IACT,WAAW;IACX,YAAY;IACZ,SAAS;IACT,YAAY;IACZ,cAAc;IACd,UAAU;IACV,UAAU;IACV,cAAc;IACd,gBAAgB;IAChB,UAAU;IACV,UAAU;CACX,CAAC;AAEF,MAAM,UAAU,kBAAkB;IAChC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;AACjG,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,OAAO,CAAC;AACrD,CAAC"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMjD,MAAM,KAAK,GAAc;IACvB,WAAW;IACX,UAAU;IACV,YAAY;IACZ,WAAW;IACX,QAAQ;IACR,aAAa;IACb,gBAAgB;IAChB,YAAY;IACZ,SAAS;IACT,WAAW;IACX,YAAY;IACZ,SAAS;IACT,YAAY;IACZ,cAAc;IACd,UAAU;IACV,UAAU;IACV,cAAc;IACd,gBAAgB;IAChB,UAAU;IACV,UAAU;IACV,WAAW;CACZ,CAAC;AAEF,MAAM,UAAU,kBAAkB;IAChC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;AACjG,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,OAAO,CAAC;AACrD,CAAC"}

package/dist/tool-manifest.json

@@ -1,9 +1,9 @@
 {
   "name": "projscan",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "mcpProtocolVersion": "2025-03-26",
-  "generatedAt": "2026-05-05T03:34:00.203Z",
-  "toolCount": 20,
+  "generatedAt": "2026-05-05T10:19:16.805Z",
+  "toolCount": 21,
   "tools": [
     {
       "name": "projscan_analyze",
@@ -182,13 +182,17 @@
     },
     {
       "name": "projscan_upgrade",
-      "description": "Preview the impact of upgrading a package: semver drift, breaking-change markers from the local CHANGELOG, and the files in your repo that import it. Offline.",
+      "description": "Preview the impact of upgrading a package: semver drift, breaking-change markers from the local CHANGELOG, and the files in your repo that import it. Offline by default; pass `check_registry: true` (1.3+) to fetch the actual latest version from npm.",
       "inputSchema": {
         "type": "object",
         "properties": {
           "package": {
             "type": "string",
             "description": "Name of the package to preview."
+          },
+          "check_registry": {
+            "type": "boolean",
+            "description": "1.3+ — when true, fetch the latest version from registry.npmjs.org (network-required). Default false: latest is treated as the installed version."
           }
         },
         "required": [
@@ -478,6 +482,42 @@
           "query"
         ]
       }
+    },
+    {
+      "name": "projscan_session",
+      "description": "Inspect the durable cross-invocation session: which files have been touched in this session, by what (tool result / fs watch / explicit), and the event log. Use to coordinate across multi-agent setups without re-querying git.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": [
+              "current",
+              "touched",
+              "events",
+              "reset"
+            ],
+            "description": "Subaction. Default \"current\" returns session metadata. \"touched\" returns the touched-file list. \"events\" returns the event log. \"reset\" discards the current session and starts a fresh one."
+          },
+          "source": {
+            "type": "string",
+            "enum": [
+              "tool-result",
+              "fs-watch",
+              "explicit"
+            ],
+            "description": "\"touched\" only — restrict to files added by this source. Omit for all sources."
+          },
+          "cursor": {
+            "type": "string",
+            "description": "Opaque cursor for pagination (touched / events lists)."
+          },
+          "page_size": {
+            "type": "integer",
+            "description": "Page size for paginated lists. Default 50, max 500."
+          }
+        }
+      }
     }
   ]
 }

package/dist/types.d.ts

@@ -298,6 +298,15 @@ export interface UpgradePreview {
     breakingMarkers: string[];
     changelogExcerpt?: string;
     importers: string[];
+    /**
+     * 1.3+ — set when `previewUpgrade` was called with `checkRegistry: true`.
+     * "registry" if the latest came from npm; "installed" if we fell back to
+     * the locally-installed version (either offline mode or a registry fetch
+     * that failed). Absent when no registry attempt was made.
+     */
+    latestSource?: 'registry' | 'installed';
+    /** 1.3+ — set when a registry fetch was attempted and failed. */
+    registryError?: string;
 }
 export type CoverageSource = 'lcov' | 'coverage-final' | 'coverage-summary';
 export interface FileCoverage {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "projscan",
   "mcpName": "io.github.abhiyoheswaran1/projscan",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Agent-first code intelligence. MCP server (2025-03-26) with AST parsing for JavaScript, TypeScript, Python, Go, Java, Ruby, Rust, PHP, and C#; code graph, file + per-function AST cyclomatic complexity, per-function fan-in + fan-out, coupling + cycle detection, structural PR diff with HTML reporter, coverage report with HTML reporter, one-call PR review (projscan_review), rule-driven fix suggestions (projscan_fix_suggest, projscan_explain_issue) closing the diagnose-fix loop, transitive blast-radius analysis (projscan_impact for files and symbols), per-function semantic search chunks (sub-file embeddings), monorepo workspace awareness with cross-package import policy + per-package dependencies / outdated / audit, BM25 + optional semantic search, cursor pagination, progress notifications, context-budgeted output, and a stable-surface CI guard. CLI on the side.",
   "type": "module",
   "main": "./dist/index.js",