projscan 1.2.1 → 1.4.0

package/README.md

@@ -20,7 +20,7 @@
 
 AI coding agents are becoming the primary interface to code. Today, when you ask your agent *"which files implement auth?"* or *"what breaks if I bump React from 18 to 19?"* - it either guesses from names, or it shells out to grep and reads raw output not built for it.
 
-**projscan is the first code-intelligence tool built for agents, not for humans.** Your agent gets a fast, AST-accurate, context-budget-aware view of your codebase through 20 structured MCP tools. It can query the import graph, find symbol definitions, preview upgrades, rank hotspots, diff structural changes between refs, surface coupling/cycle hotspots, get a one-call PR review, request structured fix-action prompts for any open issue, and ask "what breaks if I change this?" via transitive blast-radius analysis - without loading the file tree into its context.
+**projscan is the first code-intelligence tool built for agents, not for humans.** Your agent gets a fast, AST-accurate, context-budget-aware view of your codebase through 21 structured MCP tools. It can query the import graph, find symbol definitions, preview upgrades, rank hotspots, diff structural changes between refs, surface coupling/cycle hotspots, get a one-call PR review, request structured fix-action prompts for any open issue, ask "what breaks if I change this?" via transitive blast-radius analysis, and share a durable session across multiple agent invocations - without loading the file tree into its context.
 
 Humans get the same thing through the CLI.
 
@@ -515,25 +515,104 @@ Coverage is also automatically joined into `projscan hotspots` when one of those
 
 **This is the primary way to use projscan.** `projscan mcp` starts an [MCP](https://modelcontextprotocol.io) server over stdio so AI coding agents can query your codebase with real structural accuracy - not regex, not grep.
 
+<img src="docs/projscan-agent-demo.gif" alt="projscan answering two agent questions: what breaks if I rename buildCodeGraph (impact analysis with definitions, direct callers, transitive reach), and where should I fix first (ranked hotspots with cyclomatic complexity)" width="700">
+
+Two questions an agent asks; structural answers in milliseconds. *"What breaks if I rename `buildCodeGraph`?"* → 31 direct callers, 97 files reachable. *"Where should I fix first?"* → ranked hotspots with AST cyclomatic complexity, churn, and ownership signals.
+
 ### Claude Code
 
+One-liner — adds projscan as an MCP server in the current project:
+
 ```bash
-claude mcp add projscan -- npx projscan mcp
+claude mcp add projscan -- npx -y projscan mcp
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):
+
+```json
+{
+  "mcpServers": {
+    "projscan": {
+      "command": "npx",
+      "args": ["-y", "projscan", "mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "projscan": {
+      "command": "npx",
+      "args": ["-y", "projscan", "mcp"]
+    }
+  }
+}
 ```
 
-### Cursor / Windsurf / any MCP client
+### Cline (VS Code extension)
+
+In Cline's MCP settings panel (or the underlying `cline_mcp_settings.json`):
 
 ```json
 {
   "mcpServers": {
     "projscan": {
       "command": "npx",
-      "args": ["projscan", "mcp"]
+      "args": ["-y", "projscan", "mcp"]
     }
   }
 }
 ```
 
+### Continue.dev
+
+Add to `~/.continue/config.yaml`:
+
+```yaml
+mcpServers:
+  - name: projscan
+    command: npx
+    args:
+      - -y
+      - projscan
+      - mcp
+```
+
+### Zed
+
+Add to `~/.config/zed/settings.json` under `context_servers`:
+
+```json
+{
+  "context_servers": {
+    "projscan": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "projscan", "mcp"]
+      }
+    }
+  }
+}
+```
+
+### Any other MCP-aware client
+
+The transport is **stdio**. Wire your client to invoke `npx -y projscan mcp` as a subprocess; the server speaks JSON-RPC 2.0 over stdin/stdout. If your client wants `notifications/file_changed` push notifications when the repo changes, append `--watch`:
+
+```bash
+npx -y projscan mcp --watch
+```
+
+Capability is advertised under `experimental.fileChanged` on `initialize` so clients can detect support.
+
 ### What agents can ask
 
 - *"Who imports `src/auth/jwt.ts`?"* → `projscan_graph { file, direction: "importers" }`
@@ -543,7 +622,7 @@ claude mcp add projscan -- npx projscan mcp
 - *"What breaks if I bump chalk to 6?"* → `projscan_upgrade { package: "chalk" }`
 - *"Where should I refactor first?"* → `projscan_hotspots`
 
-### The 20 MCP tools
+### The 21 MCP tools
 
 **Structural (0.6.0 / 0.11 / 0.13 / 0.14 / 0.15 - agent-native):**
 - **`projscan_graph`** - query the AST-based code graph. Directions: `imports`, `exports`, `importers`, `symbol_defs`, `package_importers`. Millisecond responses on a warm cache.
@@ -573,6 +652,9 @@ claude mcp add projscan -- npx projscan mcp
 **Workspace (0.11):**
 - `projscan_workspaces` - list monorepo packages (npm/yarn/pnpm/Nx/Turbo/Lerna). Use the `name` as the `package` arg on `projscan_hotspots` / `projscan_coupling` to scope.
 
+**Session (1.4):**
+- **`projscan_session`** *(1.4)* - durable cross-invocation session. Subactions: `current` (id + counts), `touched` (files touched this session, sorted by recency, filterable by source: `tool-result` / `fs-watch` / `explicit`), `events` (chronological log), `reset` (start a fresh session). Auto-populated from every tool result and from `notifications/file_changed` push events when `--watch` is on. Lets multiple agents in the same project see "what's been touched here" without re-running git.
+
 ### Context-window budgeting
 
 **Every MCP tool accepts an optional `max_tokens` argument.** Set it and projscan serializes the result, and - if over budget - truncates the largest array field record-by-record until it fits. Responses include a `_budget` sidecar when truncated so your agent knows it got a partial view.

package/dist/cli/commands/mcp.js

@@ -6,11 +6,12 @@ export function registerMcp() {
     program
         .command('mcp')
         .description('Run projscan as an MCP server (stdio) for AI coding agents')
-        .action(async () => {
+        .option('--watch', "emit notifications/file_changed when source files change (1.3+; off by default — agents that subscribe stop polling)")
+        .action(async (opts) => {
         setLogLevel('quiet');
         const rootPath = getRootPath();
         try {
-            await runMcpServer(rootPath);
+            await runMcpServer(rootPath, { watch: opts.watch === true });
         }
         catch (error) {
             console.error(chalk.red(error instanceof Error ? error.message : String(error)));

package/dist/cli/commands/mcp.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../../src/cli/commands/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,UAAU,WAAW;IACzB,OAAO;SACJ,OAAO,CAAC,KAAK,CAAC;SACd,WAAW,CAAC,4DAA4D,CAAC;SACzE,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,WAAW,CAAC,OAAO,CAAC,CAAC;QACrB,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACjF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../../src/cli/commands/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,UAAU,WAAW;IACzB,OAAO;SACJ,OAAO,CAAC,KAAK,CAAC;SACd,WAAW,CAAC,4DAA4D,CAAC;SACzE,MAAM,CACL,SAAS,EACT,sHAAsH,CACvH;SACA,MAAM,CAAC,KAAK,EAAE,IAAyB,EAAE,EAAE;QAC1C,WAAW,CAAC,OAAO,CAAC,CAAC;QACrB,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,YAAY,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACjF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/commands/session.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `projscan session` — inspect the durable cross-invocation session that
+ * the MCP server populates as agents work. Mirrors the `projscan_session`
+ * MCP tool but for terminal use.
+ *
+ * Subcommands:
+ *   projscan session                  — current session summary (default)
+ *   projscan session touched          — list files touched this session
+ *   projscan session events           — chronological event log
+ *   projscan session reset            — discard the current session
+ */
+export declare function registerSession(): void;

package/dist/cli/commands/session.js

@@ -0,0 +1,200 @@
+import chalk from 'chalk';
+import { program, getRootPath, getFormat, setupLogLevel, maybeCompactBanner } from '../_shared.js';
+import { loadSession, resetSession, } from '../../core/session.js';
+/**
+ * `projscan session` — inspect the durable cross-invocation session that
+ * the MCP server populates as agents work. Mirrors the `projscan_session`
+ * MCP tool but for terminal use.
+ *
+ * Subcommands:
+ *   projscan session                  — current session summary (default)
+ *   projscan session touched          — list files touched this session
+ *   projscan session events           — chronological event log
+ *   projscan session reset            — discard the current session
+ */
+export function registerSession() {
+    const session = program
+        .command('session')
+        .description('Inspect or reset the durable cross-invocation session (1.4+)')
+        .action(async () => {
+        await runSummary();
+    });
+    session
+        .command('touched')
+        .description('List files touched this session (sorted by last-touched desc)')
+        .option('--source <source>', 'restrict to tool-result | fs-watch | explicit')
+        .option('--limit <n>', 'show at most N entries', (v) => parseInt(v, 10))
+        .action(async (opts) => {
+        await runTouched(opts);
+    });
+    session
+        .command('events')
+        .description('Show the session event log, newest first')
+        .option('--limit <n>', 'show at most N entries', (v) => parseInt(v, 10))
+        .action(async (opts) => {
+        await runEvents(opts);
+    });
+    session
+        .command('reset')
+        .description('Discard the current session and start a fresh one')
+        .action(async () => {
+        await runReset();
+    });
+}
+async function runSummary() {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    try {
+        const { session: sess, created } = await loadSession(rootPath);
+        if (format === 'json') {
+            console.log(JSON.stringify({ session: sess, created }, null, 2));
+            return;
+        }
+        printSummary(sess, created);
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
+async function runTouched(opts) {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    try {
+        const { session: sess } = await loadSession(rootPath);
+        const all = Object.values(sess.touchedFiles);
+        const filtered = opts.source ? all.filter((t) => t.source === opts.source) : all;
+        filtered.sort((a, b) => b.lastTouchedAt.localeCompare(a.lastTouchedAt));
+        const limited = typeof opts.limit === 'number' && opts.limit > 0 ? filtered.slice(0, opts.limit) : filtered;
+        if (format === 'json') {
+            console.log(JSON.stringify({ sessionId: sess.id, total: filtered.length, touched: limited }, null, 2));
+            return;
+        }
+        printTouched(sess, limited, filtered.length);
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
+async function runEvents(opts) {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    try {
+        const { session: sess } = await loadSession(rootPath);
+        const reversed = [...sess.events].reverse();
+        const limited = typeof opts.limit === 'number' && opts.limit > 0 ? reversed.slice(0, opts.limit) : reversed;
+        if (format === 'json') {
+            console.log(JSON.stringify({ sessionId: sess.id, total: reversed.length, events: limited }, null, 2));
+            return;
+        }
+        printEvents(sess, limited, reversed.length);
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
+async function runReset() {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    try {
+        const fresh = await resetSession(rootPath);
+        if (format === 'json') {
+            console.log(JSON.stringify({ reset: true, session: fresh }, null, 2));
+            return;
+        }
+        console.log(chalk.green('✓ Session reset.'));
+        console.log(`  New session id: ${fresh.id}`);
+        console.log(`  Started at: ${fresh.startedAt}`);
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
+function printSummary(session, created) {
+    const startedAtMs = Date.parse(session.startedAt);
+    const ageMs = Number.isFinite(startedAtMs) ? Date.now() - startedAtMs : null;
+    console.log('');
+    console.log(chalk.bold('Session'));
+    console.log(chalk.dim('────────────────────────────────────────'));
+    console.log(`  id:           ${session.id}`);
+    console.log(`  status:       ${created ? chalk.cyan('fresh (just created)') : chalk.green('active')}`);
+    console.log(`  started:      ${session.startedAt}`);
+    console.log(`  last activity: ${session.lastActivityAt}`);
+    if (ageMs !== null) {
+        console.log(`  age:          ${formatDuration(ageMs)}`);
+    }
+    console.log('');
+    console.log(`  touched files: ${Object.keys(session.touchedFiles).length}`);
+    console.log(`  events:        ${session.events.length}`);
+    console.log('');
+    console.log(chalk.dim('  Tip: run `projscan session touched` for the file list.'));
+}
+function printTouched(session, items, total) {
+    console.log('');
+    console.log(chalk.bold(`Touched files (${session.id.slice(0, 8)})`));
+    console.log(chalk.dim('────────────────────────────────────────'));
+    if (items.length === 0) {
+        console.log(chalk.dim('  No files touched in this session yet.'));
+        return;
+    }
+    for (const t of items) {
+        const sourceTag = formatSourceTag(t.source);
+        console.log(`  ${sourceTag} ${t.file}  ${chalk.dim(`(×${t.count}, ${t.lastTouchedAt})`)}`);
+    }
+    if (items.length < total) {
+        console.log('');
+        console.log(chalk.dim(`  ${total - items.length} more — pass --limit ${total} to see all.`));
+    }
+}
+function printEvents(session, items, total) {
+    console.log('');
+    console.log(chalk.bold(`Events (${session.id.slice(0, 8)})`));
+    console.log(chalk.dim('────────────────────────────────────────'));
+    if (items.length === 0) {
+        console.log(chalk.dim('  No events recorded in this session yet.'));
+        return;
+    }
+    for (const e of items) {
+        console.log(`  ${chalk.dim(e.at)}  ${e.kind}`);
+    }
+    if (items.length < total) {
+        console.log('');
+        console.log(chalk.dim(`  ${total - items.length} more — pass --limit ${total} to see all.`));
+    }
+}
+function formatSourceTag(source) {
+    switch (source) {
+        case 'tool-result':
+            return chalk.cyan('[tool]    ');
+        case 'fs-watch':
+            return chalk.yellow('[fs-watch]');
+        case 'explicit':
+            return chalk.magenta('[explicit]');
+        default:
+            return chalk.dim('[unknown] ');
+    }
+}
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ${seconds % 60}s`;
+    const hours = Math.floor(minutes / 60);
+    return `${hours}h ${minutes % 60}m`;
+}
+//# sourceMappingURL=session.js.map

package/dist/cli/commands/session.js.map

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

package/dist/cli/commands/upgrade.js

@@ -9,8 +9,9 @@ import { reportUpgradeMarkdown } from '../../reporters/markdownReporter.js';
 export function registerUpgrade() {
     program
         .command('upgrade <package>')
-        .description('Preview the impact of upgrading a package (offline - reads local CHANGELOG + importers)')
-        .action(async (pkgName) => {
+        .description('Preview the impact of upgrading a package (offline by default - reads local CHANGELOG + importers)')
+        .option('--check-registry', 'fetch the actual latest version from npm (1.3+; otherwise latest = installed)')
+        .action(async (pkgName, opts) => {
         setupLogLevel();
         maybeCompactBanner();
         const rootPath = getRootPath();
@@ -19,7 +20,9 @@ export function registerUpgrade() {
         const spinner = format === 'console' ? ora(`Previewing ${pkgName}...`).start() : null;
         try {
             const scan = await scanRepository(rootPath, { ignore: config.ignore });
-            const preview = await previewUpgrade(rootPath, pkgName, scan.files);
+            const preview = await previewUpgrade(rootPath, pkgName, scan.files, {
+                checkRegistry: opts.checkRegistry === true,
+            });
             if (spinner)
                 spinner.stop();
             switch (format) {

package/dist/cli/commands/upgrade.js.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../../../src/cli/commands/upgrade.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,KAAK,CAAC;AACtB,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EACL,OAAO,EACP,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAE5E,MAAM,UAAU,eAAe;IAC7B,OAAO;SACJ,OAAO,CAAC,mBAAmB,CAAC;SAC5B,WAAW,CAAC,yFAAyF,CAAC;SACtG,MAAM,CAAC,KAAK,EAAE,OAAe,EAAE,EAAE;QAChC,aAAa,EAAE,CAAC;QAChB,kBAAkB,EAAE,CAAC;QACrB,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,MAAM,iBAAiB,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,OAAO,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAEtF,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;YACvE,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YACpE,IAAI,OAAO;gBAAE,OAAO,CAAC,IAAI,EAAE,CAAC;YAE5B,QAAQ,MAAM,EAAE,CAAC;gBACf,KAAK,MAAM;oBACT,iBAAiB,CAAC,OAAO,CAAC,CAAC;oBAC3B,MAAM;gBACR,KAAK,UAAU;oBACb,qBAAqB,CAAC,OAAO,CAAC,CAAC;oBAC/B,MAAM;gBACR;oBACE,aAAa,CAAC,OAAO,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,OAAO;gBAAE,OAAO,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;YACpD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACjF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../../../src/cli/commands/upgrade.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,KAAK,CAAC;AACtB,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EACL,OAAO,EACP,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAE5E,MAAM,UAAU,eAAe;IAC7B,OAAO;SACJ,OAAO,CAAC,mBAAmB,CAAC;SAC5B,WAAW,CAAC,oGAAoG,CAAC;SACjH,MAAM,CAAC,kBAAkB,EAAE,+EAA+E,CAAC;SAC3G,MAAM,CAAC,KAAK,EAAE,OAAe,EAAE,IAAiC,EAAE,EAAE;QACnE,aAAa,EAAE,CAAC;QAChB,kBAAkB,EAAE,CAAC;QACrB,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,MAAM,iBAAiB,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,OAAO,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAEtF,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;YACvE,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE;gBAClE,aAAa,EAAE,IAAI,CAAC,aAAa,KAAK,IAAI;aAC3C,CAAC,CAAC;YACH,IAAI,OAAO;gBAAE,OAAO,CAAC,IAAI,EAAE,CAAC;YAE5B,QAAQ,MAAM,EAAE,CAAC;gBACf,KAAK,MAAM;oBACT,iBAAiB,CAAC,OAAO,CAAC,CAAC;oBAC3B,MAAM;gBACR,KAAK,UAAU;oBACb,qBAAqB,CAAC,OAAO,CAAC,CAAC;oBAC/B,MAAM;gBACR;oBACE,aAAa,CAAC,OAAO,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,OAAO;gBAAE,OAAO,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;YACpD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACjF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/index.js

@@ -25,6 +25,7 @@ import { registerUpgrade } from './commands/upgrade.js';
 import { registerSearch } from './commands/search.js';
 import { registerCoverage } from './commands/coverage.js';
 import { registerMcp } from './commands/mcp.js';
+import { registerSession } from './commands/session.js';
 import { registerBadge } from './commands/badge.js';
 import { registerHelp } from './commands/help.js';
 registerAnalyze();
@@ -52,6 +53,7 @@ registerUpgrade();
 registerSearch();
 registerCoverage();
 registerMcp();
+registerSession();
 registerBadge();
 registerHelp();
 program.parse();

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,eAAe,EAAE,CAAC;AAClB,cAAc,EAAE,CAAC;AACjB,UAAU,EAAE,CAAC;AACb,YAAY,EAAE,CAAC;AACf,WAAW,EAAE,CAAC;AACd,YAAY,EAAE,CAAC;AACf,eAAe,EAAE,CAAC;AAClB,eAAe,EAAE,CAAC;AAClB,iBAAiB,EAAE,CAAC;AACpB,oBAAoB,EAAE,CAAC;AACvB,gBAAgB,EAAE,CAAC;AACnB,gBAAgB,EAAE,CAAC;AACnB,cAAc,EAAE,CAAC;AACjB,cAAc,EAAE,CAAC;AACjB,kBAAkB,EAAE,CAAC;AACrB,oBAAoB,EAAE,CAAC;AACvB,cAAc,EAAE,CAAC;AACjB,aAAa,EAAE,CAAC;AAChB,kBAAkB,EAAE,CAAC;AACrB,gBAAgB,EAAE,CAAC;AACnB,aAAa,EAAE,CAAC;AAChB,eAAe,EAAE,CAAC;AAClB,cAAc,EAAE,CAAC;AACjB,gBAAgB,EAAE,CAAC;AACnB,WAAW,EAAE,CAAC;AACd,aAAa,EAAE,CAAC;AAChB,YAAY,EAAE,CAAC;AAEf,OAAO,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,eAAe,EAAE,CAAC;AAClB,cAAc,EAAE,CAAC;AACjB,UAAU,EAAE,CAAC;AACb,YAAY,EAAE,CAAC;AACf,WAAW,EAAE,CAAC;AACd,YAAY,EAAE,CAAC;AACf,eAAe,EAAE,CAAC;AAClB,eAAe,EAAE,CAAC;AAClB,iBAAiB,EAAE,CAAC;AACpB,oBAAoB,EAAE,CAAC;AACvB,gBAAgB,EAAE,CAAC;AACnB,gBAAgB,EAAE,CAAC;AACnB,cAAc,EAAE,CAAC;AACjB,cAAc,EAAE,CAAC;AACjB,kBAAkB,EAAE,CAAC;AACrB,oBAAoB,EAAE,CAAC;AACvB,cAAc,EAAE,CAAC;AACjB,aAAa,EAAE,CAAC;AAChB,kBAAkB,EAAE,CAAC;AACrB,gBAAgB,EAAE,CAAC;AACnB,aAAa,EAAE,CAAC;AAChB,eAAe,EAAE,CAAC;AAClB,cAAc,EAAE,CAAC;AACjB,gBAAgB,EAAE,CAAC;AACnB,WAAW,EAAE,CAAC;AACd,eAAe,EAAE,CAAC;AAClB,aAAa,EAAE,CAAC;AAChB,YAAY,EAAE,CAAC;AAEf,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/core/session.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Session — durable cross-invocation state for projscan (1.4+).
+ *
+ * Persisted at `.projscan-cache/session.json`. A new session starts when
+ * the previous session has been idle for longer than `IDLE_TIMEOUT_MS`
+ * (default 1 hour) or when none exists. Multiple agents calling the MCP
+ * server against the same project share the same session as long as
+ * they're within the idle window.
+ *
+ * Session purpose: let one agent answer "what has been touched since I
+ * arrived?" without having to call git or grep. Touched files come from
+ * (a) tool results that surface file paths, and (b) `notifications/file_changed`
+ * push events from `projscan mcp --watch`.
+ *
+ * Schema is versioned (`schemaVersion`) so future evolution can detect
+ * and migrate older session files instead of crashing.
+ */
+export declare const SESSION_SCHEMA_VERSION = 1;
+export declare const DEFAULT_IDLE_TIMEOUT_MS: number;
+export type TouchSource = 'tool-result' | 'fs-watch' | 'explicit';
+export interface SessionTouch {
+    /** Repo-relative path. Always POSIX-separator (`/`). */
+    file: string;
+    /** Where the touch came from. */
+    source: TouchSource;
+    /** ISO 8601 timestamp of the most recent touch. */
+    lastTouchedAt: string;
+    /** Total times this file has been touched in this session. */
+    count: number;
+}
+export interface SessionEvent {
+    /** ISO 8601 timestamp. */
+    at: string;
+    /** Free-form kind tag (e.g., "tool-call:projscan_hotspots"). */
+    kind: string;
+    /** Optional structured payload. */
+    data?: Record<string, unknown>;
+}
+export interface Session {
+    schemaVersion: number;
+    /** UUID assigned at session creation. Stable until idle expiry. */
+    id: string;
+    /** ISO 8601. */
+    startedAt: string;
+    /** ISO 8601. Updated on every recordTouch / recordEvent / save. */
+    lastActivityAt: string;
+    /** Map keyed by repo-relative file path. */
+    touchedFiles: Record<string, SessionTouch>;
+    /** Bounded event log. Caps at MAX_EVENTS most-recent. */
+    events: SessionEvent[];
+}
+/**
+ * Load the session for `rootPath`. If the on-disk session has been idle
+ * for longer than `idleTimeoutMs`, returns a fresh session. If no session
+ * exists, returns a fresh session. Failures to read or parse the file
+ * (corruption, schema mismatch) also produce a fresh session — this
+ * function never throws under normal operation.
+ *
+ * Returns the session object PLUS a `created` flag so the caller can tell
+ * whether they're attaching to an existing session or starting a new one.
+ */
+export declare function loadSession(rootPath: string, idleTimeoutMs?: number): Promise<{
+    session: Session;
+    created: boolean;
+}>;
+/**
+ * Record a file touch in-place on the session. Updates the per-file
+ * count + lastTouchedAt and the session's lastActivityAt. Caller is
+ * responsible for `saveSession()` afterwards (batched persist).
+ *
+ * `file` should be repo-relative POSIX-separator. Paths with `..` or
+ * absolute paths are silently ignored — sessions only track in-repo state.
+ */
+export declare function recordTouch(session: Session, file: string, source: TouchSource): void;
+/**
+ * Append an event to the session's bounded log. The log keeps the last
+ * MAX_EVENTS entries and drops the oldest when over capacity.
+ */
+export declare function recordEvent(session: Session, kind: string, data?: Record<string, unknown>): void;
+/**
+ * Persist the session to disk. Best-effort; failures are swallowed so
+ * a transient write error doesn't break the calling tool.
+ *
+ * Last-write-wins semantics for now. If two MCP servers run against the
+ * same repo concurrently, the later writer overwrites the earlier; this
+ * is acceptable for the v1 scope (the multi-process case is rare and the
+ * downside is just a slightly stale touched-file count, not corruption).
+ */
+export declare function saveSession(rootPath: string, session: Session): Promise<void>;
+/**
+ * Reset the session: discard the on-disk file and return a fresh one.
+ * Useful for the `projscan_session { action: "reset" }` MCP path.
+ */
+export declare function resetSession(rootPath: string): Promise<Session>;