@contorium/mcp 0.8.1

package/node_modules/@contora/state-core/dist/understanding/symbolValidator.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSymbols = validateSymbols;
+exports.validateCalls = validateCalls;
+exports.refineExtraction = refineExtraction;
+const NOISE_NAMES = new Set([
+    'constructor', 'toString', 'valueOf', 'then', 'catch', 'finally', 'map', 'filter', 'reduce',
+    'forEach', 'push', 'pop', 'slice', 'join', 'length', 'log', 'error', 'warn',
+]);
+const TS_TYPE_LIKE = /^[A-Z][A-Z0-9_]*$/;
+/**
+ * Hybrid precision layer (V3.1) — post-filters regex noise.
+ * Tree-sitter can replace/enhance this module later without changing the pipeline.
+ */
+function validateSymbols(symbols) {
+    const seen = new Set();
+    const out = [];
+    for (const sym of symbols) {
+        if (sym.kind === 'import') {
+            if (sym.name.startsWith('.') || sym.name.includes('/')) {
+                out.push(sym);
+            }
+            continue;
+        }
+        if (sym.name.length < 2 || NOISE_NAMES.has(sym.name)) {
+            continue;
+        }
+        if (sym.kind === 'function' && TS_TYPE_LIKE.test(sym.name) && sym.name.length <= 3) {
+            continue;
+        }
+        const key = `${sym.kind}::${sym.name}::${sym.line}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        out.push(sym);
+    }
+    return out;
+}
+function validateCalls(calls, symbols) {
+    const fnNames = new Set(symbols.filter((s) => s.kind === 'function').map((s) => s.name));
+    return calls.filter((c) => fnNames.has(c) || (!NOISE_NAMES.has(c) && c.length > 2));
+}
+function refineExtraction(ext) {
+    const symbols = validateSymbols(ext.symbols);
+    return {
+        file: ext.file,
+        symbols,
+        calls: validateCalls(ext.calls, symbols),
+    };
+}

package/node_modules/@contora/state-core/dist/understanding/timelineTracker.d.ts

@@ -0,0 +1,3 @@
+import type { ChangeArtifact, ProjectGraph, ProjectTimeline } from './types.js';
+export declare function buildProjectTimeline(workspaceRoot: string, changedFiles: string[], change: ChangeArtifact, graph: ProjectGraph, now?: number, maxCommits?: number): Promise<ProjectTimeline>;
+//# sourceMappingURL=timelineTracker.d.ts.map

package/node_modules/@contora/state-core/dist/understanding/timelineTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timelineTracker.d.ts","sourceRoot":"","sources":["../../src/understanding/timelineTracker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAa,YAAY,EAAE,eAAe,EAA4B,MAAM,YAAY,CAAC;AA4FrH,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EAAE,EACtB,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,YAAY,EACnB,GAAG,SAAa,EAChB,UAAU,SAAI,GACb,OAAO,CAAC,eAAe,CAAC,CAsD1B"}

package/node_modules/@contora/state-core/dist/understanding/timelineTracker.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildProjectTimeline = buildProjectTimeline;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+function norm(p) {
+    return p.replace(/\\/g, '/');
+}
+function graphRef(kind, name) {
+    return `${kind}:${name}`;
+}
+function riskFromChangeCount(n) {
+    if (n >= 4) {
+        return 'high';
+    }
+    if (n >= 2) {
+        return 'medium';
+    }
+    return 'low';
+}
+async function recentGitCommits(workspaceRoot, max = 5) {
+    try {
+        const { stdout } = await execFileAsync('git', ['-C', workspaceRoot, 'log', `-${max}`, '--pretty=format:---%n%H|%ct', '--name-status'], { timeout: 15_000, maxBuffer: 2 * 1024 * 1024 });
+        const rows = [];
+        let current;
+        for (const line of stdout.split('\n')) {
+            if (line === '---') {
+                current = undefined;
+                continue;
+            }
+            const header = line.match(/^([0-9a-f]{7,40})\|(\d+)$/);
+            if (header) {
+                current = { hash: header[1], timestamp: Number(header[2]) * 1000 };
+                continue;
+            }
+            if (!current || line.length < 2) {
+                continue;
+            }
+            const status = line[0];
+            const file = norm(line.slice(1).trim().split('\t').pop() ?? line.slice(2).trim());
+            if (!file) {
+                continue;
+            }
+            let type = 'modify';
+            if (status === 'A') {
+                type = 'add';
+            }
+            else if (status === 'D') {
+                type = 'delete';
+            }
+            else if (status === 'R') {
+                type = 'rename';
+            }
+            rows.push({ hash: current.hash, timestamp: current.timestamp, type, file });
+        }
+        return rows;
+    }
+    catch {
+        return [];
+    }
+}
+function keyChangesForFile(change, file) {
+    return change.key_changes.filter((k) => (k.kind === 'file' && k.symbol === file) || k.symbol.startsWith(`${file}::`));
+}
+function linkedNodes(graph, file, keyChanges) {
+    const names = new Set(keyChanges.map((k) => k.symbol.split('::').pop() ?? k.symbol));
+    const refs = [];
+    for (const n of graph.nodes) {
+        if (n.file !== file) {
+            continue;
+        }
+        if (names.has(n.name)) {
+            refs.push(graphRef(n.kind, n.name));
+        }
+    }
+    return refs.slice(0, 8);
+}
+async function buildProjectTimeline(workspaceRoot, changedFiles, change, graph, now = Date.now(), maxCommits = 5) {
+    const commits = await recentGitCommits(workspaceRoot, maxCommits);
+    const watch = new Set(changedFiles.map(norm));
+    const byFile = new Map();
+    for (const row of commits) {
+        if (!watch.has(row.file) && !changedFiles.some((f) => row.file.startsWith(f))) {
+            continue;
+        }
+        const kc = keyChangesForFile(change, row.file);
+        const entry = {
+            commit: row.hash.slice(0, 7),
+            timestamp: row.timestamp,
+            type: row.type,
+            file: row.file,
+            changes: kc.map((k) => ({
+                symbol: k.symbol.split('::').pop() ?? k.symbol,
+                change: k.change_type === 'added' ? 'symbol_added' : 'logic_modified',
+            })),
+            impact_level: riskFromChangeCount(kc.length),
+            linked_graph_nodes: linkedNodes(graph, row.file, kc),
+        };
+        const list = byFile.get(row.file) ?? [];
+        list.push(entry);
+        byFile.set(row.file, list);
+    }
+    const files = [...byFile.entries()].map(([file, history]) => ({ file, history }));
+    const recent = commits
+        .filter((r) => watch.has(r.file))
+        .slice(0, maxCommits)
+        .map((row) => {
+        const kc = keyChangesForFile(change, row.file);
+        return {
+            commit: row.hash.slice(0, 7),
+            timestamp: row.timestamp,
+            type: row.type,
+            file: row.file,
+            changes: kc.map((k) => ({
+                symbol: k.symbol.split('::').pop() ?? k.symbol,
+                change: k.change_type === 'added' ? 'symbol_added' : 'logic_modified',
+            })),
+            impact_level: riskFromChangeCount(kc.length),
+            linked_graph_nodes: linkedNodes(graph, row.file, kc),
+        };
+    });
+    return {
+        version: 1,
+        generatedAt: now,
+        files,
+        recent,
+    };
+}

package/node_modules/@contora/state-core/dist/understanding/treeSitterParser.d.ts

@@ -0,0 +1,24 @@
+import type { FileExtraction } from './extractor.js';
+export type ParseBackend = 'regex' | 'tree-sitter';
+export interface ParseFileOptions {
+    content?: string;
+    /** Reserved for tree-sitter incremental parse (previous AST snapshot). */
+    previous?: FileExtraction;
+}
+/**
+ * Hybrid parser adapter (V3.1).
+ * Default: regex fast path. Tree-sitter activates when `web-tree-sitter` is installed.
+ */
+export declare function parseFileWithAdapter(workspaceRoot: string, relFile: string, options?: ParseFileOptions): Promise<{
+    extraction: FileExtraction;
+    backend: ParseBackend;
+} | undefined>;
+/** In-memory incremental parse cache for IDE live edits. */
+export declare class IncrementalParseCache {
+    private readonly byFile;
+    get(file: string): FileExtraction | undefined;
+    set(file: string, extraction: FileExtraction): void;
+    invalidate(file: string): void;
+    clear(): void;
+}
+//# sourceMappingURL=treeSitterParser.d.ts.map

package/node_modules/@contora/state-core/dist/understanding/treeSitterParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeSitterParser.d.ts","sourceRoot":"","sources":["../../src/understanding/treeSitterParser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIrD,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,aAAa,CAAC;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC;IAAE,UAAU,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAAG,SAAS,CAAC,CAqB5E;AAeD,4DAA4D;AAC5D,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAE5D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,GAAG,IAAI;IAInD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,KAAK,IAAI,IAAI;CAGd"}

package/node_modules/@contora/state-core/dist/understanding/treeSitterParser.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IncrementalParseCache = void 0;
+exports.parseFileWithAdapter = parseFileWithAdapter;
+const extractor_js_1 = require("./extractor.js");
+const symbolValidator_js_1 = require("./symbolValidator.js");
+/**
+ * Hybrid parser adapter (V3.1).
+ * Default: regex fast path. Tree-sitter activates when `web-tree-sitter` is installed.
+ */
+async function parseFileWithAdapter(workspaceRoot, relFile, options = {}) {
+    const normalized = relFile.replace(/\\/g, '/');
+    if (!(0, extractor_js_1.isCodeFile)(normalized)) {
+        return undefined;
+    }
+    const ts = await tryTreeSitterParse(normalized, options.content, workspaceRoot);
+    if (ts) {
+        return { extraction: (0, symbolValidator_js_1.refineExtraction)(ts), backend: 'tree-sitter' };
+    }
+    let raw;
+    if (options.content !== undefined) {
+        raw = (0, extractor_js_1.extractFromSource)(normalized, options.content);
+    }
+    else {
+        raw = await (0, extractor_js_1.extractFile)(workspaceRoot, normalized);
+    }
+    if (!raw) {
+        return undefined;
+    }
+    return { extraction: (0, symbolValidator_js_1.refineExtraction)(raw), backend: 'regex' };
+}
+async function tryTreeSitterParse(relFile, content, workspaceRoot) {
+    // V3.2: wire web-tree-sitter + language grammars here (optional peer dependency).
+    // Until then, incremental live edits use regex extractFromSource via parseFileWithAdapter.
+    void relFile;
+    void content;
+    void workspaceRoot;
+    return undefined;
+}
+/** In-memory incremental parse cache for IDE live edits. */
+class IncrementalParseCache {
+    byFile = new Map();
+    get(file) {
+        return this.byFile.get(file.replace(/\\/g, '/'));
+    }
+    set(file, extraction) {
+        this.byFile.set(file.replace(/\\/g, '/'), extraction);
+    }
+    invalidate(file) {
+        this.byFile.delete(file.replace(/\\/g, '/'));
+    }
+    clear() {
+        this.byFile.clear();
+    }
+}
+exports.IncrementalParseCache = IncrementalParseCache;

package/node_modules/@contora/state-core/dist/understanding/types.d.ts

@@ -0,0 +1,136 @@
+/** V3.1 Project Understanding — 3+1 artifacts: graph, change, handoff, timeline. */
+export type GraphNodeKind = 'function' | 'class' | 'module' | 'import';
+export interface GraphNode {
+    id: string;
+    kind: GraphNodeKind;
+    name: string;
+    file: string;
+    line?: number;
+}
+export type GraphEdgeKind = 'calls' | 'imports' | 'contains';
+export interface GraphEdge {
+    from: string;
+    to: string;
+    kind: GraphEdgeKind;
+}
+export interface ProjectGraph {
+    version: 2;
+    generatedAt: number;
+    scope: 'change-neighborhood';
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+export type RiskLevel = 'low' | 'medium' | 'high';
+export type ChangeType = 'added' | 'modified' | 'removed' | 'unknown';
+export interface KeyChange {
+    symbol: string;
+    kind: 'function' | 'class' | 'file';
+    change_type: ChangeType;
+}
+export interface ChangeArtifact {
+    version: 2;
+    generatedAt: number;
+    changed_files: string[];
+    key_changes: KeyChange[];
+}
+export type HandoffActionKind = 'refactor' | 'fix' | 'extend' | 'review' | 'continue';
+export interface HandoffNextAction {
+    action: HandoffActionKind;
+    target: string;
+    reason: string;
+}
+export interface HandoffImpactSummary {
+    risk: RiskLevel;
+    affected_modules: string[];
+    affected_functions: string[];
+    details: string[];
+}
+/** V3.1 — sole AI entry point; intent + impact merged here. */
+export interface HandoffArtifact {
+    version: 2;
+    generatedAt: number;
+    goal: string;
+    current_focus: string;
+    key_changes: KeyChange[];
+    impact_summary: HandoffImpactSummary;
+    next_actions: HandoffNextAction[];
+    context_graph_refs: string[];
+    summary: string;
+}
+export interface TimelineSymbolChange {
+    symbol: string;
+    change: string;
+}
+export interface TimelineEntry {
+    commit: string;
+    timestamp: number;
+    type: 'modify' | 'add' | 'delete' | 'rename';
+    file: string;
+    changes: TimelineSymbolChange[];
+    impact_level: RiskLevel;
+    linked_graph_nodes: string[];
+}
+export interface FileTimeline {
+    file: string;
+    history: TimelineEntry[];
+}
+export interface ProjectTimeline {
+    version: 1;
+    generatedAt: number;
+    files: FileTimeline[];
+    /** Last N commits flattened for quick AI scan */
+    recent: TimelineEntry[];
+}
+/** Internal — used during pipeline, not persisted as separate artifact. */
+export interface ImpactAnalysis {
+    affected_functions: string[];
+    affected_modules: string[];
+    risk: RiskLevel;
+    details: string[];
+}
+export interface IntentFusion {
+    focus: string;
+    confidence: number;
+    signals: string[];
+}
+export declare const UNDERSTANDING_VERSION: 2;
+/** @deprecated V3.0 standalone artifact — read from handoff in V3.1 */
+export interface ImpactArtifact {
+    version: 1;
+    generatedAt: number;
+    affected_functions: string[];
+    affected_modules: string[];
+    risk: RiskLevel;
+    risk_level: RiskLevel;
+    details: string[];
+}
+/** @deprecated V3.0 standalone artifact — read from handoff in V3.1 */
+export interface IntentArtifact {
+    version: 1;
+    generatedAt: number;
+    intent: string;
+    confidence: number;
+    signals: string[];
+}
+/** @deprecated V3.0 handoff shape — normalized on read */
+export interface HandoffArtifactV1 {
+    version: 1;
+    generatedAt: number;
+    goal: string;
+    intent: string;
+    changed: {
+        changedFiles: string[];
+        changed_functions: string[];
+        changed_classes: string[];
+    };
+    impact: {
+        affected_functions: string[];
+        affected_modules: string[];
+        risk_level: RiskLevel;
+        details: string[];
+    };
+    next_actions: string[];
+    summary: string;
+}
+export type AnyHandoffArtifact = HandoffArtifact | HandoffArtifactV1;
+//# sourceMappingURL=types.d.ts.map

package/node_modules/@contora/state-core/dist/understanding/types.d.ts.map

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

package/node_modules/@contora/state-core/dist/understanding/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/** V3.1 Project Understanding — 3+1 artifacts: graph, change, handoff, timeline. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNDERSTANDING_VERSION = void 0;
+exports.UNDERSTANDING_VERSION = 2;

package/node_modules/@contora/state-core/dist/understanding/understandingGraphBuilder.d.ts

@@ -0,0 +1,23 @@
+import type { AdapterKind } from '../types.js';
+import type { ChangeArtifact, HandoffArtifact, ProjectGraph } from './types.js';
+/** Runtime Understanding Graph — call chains + impact from recent changes. */
+export interface UnderstandingGraph {
+    version: 1;
+    generatedAt: number;
+    recent_change: {
+        name: string;
+        file?: string;
+        change_type?: string;
+    };
+    call_chain: string[];
+    affected: string[];
+    agent: string;
+}
+export declare function buildUnderstandingGraph(args: {
+    graph: ProjectGraph;
+    change: ChangeArtifact;
+    handoff: HandoffArtifact;
+    agent?: AdapterKind | string;
+    now?: number;
+}): UnderstandingGraph | undefined;
+//# sourceMappingURL=understandingGraphBuilder.d.ts.map

package/node_modules/@contora/state-core/dist/understanding/understandingGraphBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"understandingGraphBuilder.d.ts","sourceRoot":"","sources":["../../src/understanding/understandingGraphBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhF,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAoCD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,eAAe,CAAC;IACzB,KAAK,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,kBAAkB,GAAG,SAAS,CAwCjC"}

package/node_modules/@contora/state-core/dist/understanding/understandingGraphBuilder.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUnderstandingGraph = buildUnderstandingGraph;
+function nodeName(graph, id) {
+    return graph.nodes.find((n) => n.id === id)?.name;
+}
+function buildCallChain(graph, seedSymbol, maxDepth = 6) {
+    const seed = graph.nodes.find((n) => n.name === seedSymbol && (n.kind === 'function' || n.kind === 'class'));
+    if (!seed) {
+        return [seedSymbol];
+    }
+    const chain = [seed.name];
+    const callEdges = graph.edges.filter((e) => e.kind === 'calls');
+    let current = seed.id;
+    const visited = new Set([current]);
+    for (let depth = 0; depth < maxDepth; depth++) {
+        const edge = callEdges.find((e) => e.from === current);
+        if (!edge || visited.has(edge.to)) {
+            break;
+        }
+        visited.add(edge.to);
+        const name = nodeName(graph, edge.to);
+        if (!name) {
+            break;
+        }
+        chain.push(name);
+        current = edge.to;
+    }
+    return chain;
+}
+function buildUnderstandingGraph(args) {
+    const fnChange = args.handoff.key_changes.find((k) => k.kind === 'function' || k.kind === 'class') ??
+        args.change.key_changes.find((k) => k.kind === 'function' || k.kind === 'class');
+    if (!fnChange) {
+        const affected = args.handoff.impact_summary.affected_functions.slice(0, 8);
+        if (!affected.length) {
+            return undefined;
+        }
+        return {
+            version: 1,
+            generatedAt: args.now ?? Date.now(),
+            recent_change: { name: '(file-level)', change_type: 'modified' },
+            call_chain: affected.slice(0, 4),
+            affected,
+            agent: String(args.agent ?? 'runtime'),
+        };
+    }
+    const displayName = fnChange.kind === 'function' ? `${fnChange.symbol}()` : fnChange.symbol;
+    const call_chain = buildCallChain(args.graph, fnChange.symbol);
+    const affected = [
+        ...new Set([
+            ...args.handoff.impact_summary.affected_functions,
+            ...call_chain.map((n) => (n.endsWith('()') ? n : `${n}()`)),
+        ]),
+    ].slice(0, 12);
+    return {
+        version: 1,
+        generatedAt: args.now ?? Date.now(),
+        recent_change: {
+            name: displayName,
+            change_type: fnChange.change_type,
+        },
+        call_chain: call_chain.map((n) => (n.endsWith('()') ? n : `${n}()`)),
+        affected,
+        agent: String(args.agent ?? 'runtime'),
+    };
+}

package/node_modules/@contora/state-core/dist/version.d.ts

@@ -0,0 +1,3 @@
+/** Read @contora/state-core version from package.json (not hardcoded). */
+export declare function getContoriumPackageVersion(): string;
+//# sourceMappingURL=version.d.ts.map

package/node_modules/@contora/state-core/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAKA,0EAA0E;AAC1E,wBAAgB,0BAA0B,IAAI,MAAM,CAYnD"}

package/node_modules/@contora/state-core/dist/version.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getContoriumPackageVersion = getContoriumPackageVersion;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+let cachedVersion;
+/** Read @contora/state-core version from package.json (not hardcoded). */
+function getContoriumPackageVersion() {
+    if (cachedVersion) {
+        return cachedVersion;
+    }
+    try {
+        const pkgPath = (0, node_path_1.join)(__dirname, '..', 'package.json');
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)(pkgPath, 'utf8'));
+        cachedVersion = pkg.version ?? '0.0.0';
+    }
+    catch {
+        cachedVersion = '0.0.0';
+    }
+    return cachedVersion;
+}

package/node_modules/@contora/state-core/dist/workspaceScanner.d.ts

@@ -0,0 +1,4 @@
+import type { WorkspaceScanFacts } from './types.js';
+/** Mode B — workspace filesystem scan (no IDE required). */
+export declare function scanWorkspace(workspaceRoot: string): Promise<WorkspaceScanFacts>;
+//# sourceMappingURL=workspaceScanner.d.ts.map

package/node_modules/@contora/state-core/dist/workspaceScanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceScanner.d.ts","sourceRoot":"","sources":["../src/workspaceScanner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA6FrD,4DAA4D;AAC5D,wBAAsB,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAmBtF"}

package/node_modules/@contora/state-core/dist/workspaceScanner.js

@@ -0,0 +1,112 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { scanGitPorcelain } from './gitScan.js';
+const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '.contora',
+    '.context-recall',
+    'dist',
+    'out',
+    '.vscode',
+    'coverage',
+]);
+const SKIP_EXT = /\.(png|jpg|jpeg|gif|ico|woff2?|ttf|eot|zip|vsix|map)$/i;
+async function readReadmeHint(root) {
+    for (const name of ['README.md', 'readme.md', 'Readme.md']) {
+        try {
+            const text = await fs.readFile(path.join(root, name), 'utf8');
+            for (const line of text.split('\n')) {
+                const t = line.replace(/^#+\s*/, '').trim();
+                if (t.length >= 12 && !/^contorium|table of contents/i.test(t)) {
+                    return t.length > 160 ? t.slice(0, 157) + '…' : t;
+                }
+            }
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return undefined;
+}
+async function listTopLevelModules(root) {
+    const out = [];
+    try {
+        const entries = await fs.readdir(root, { withFileTypes: true });
+        for (const e of entries) {
+            if (!e.isDirectory() || e.name.startsWith('.') || SKIP_DIRS.has(e.name)) {
+                continue;
+            }
+            out.push(e.name);
+        }
+    }
+    catch {
+        return out;
+    }
+    return out.slice(0, 12);
+}
+async function collectRecentFiles(root, maxFiles, maxDepth) {
+    const scored = [];
+    async function walk(dir, depth) {
+        if (depth > maxDepth || scored.length >= maxFiles * 3) {
+            return;
+        }
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const name = e.name;
+            if (name.startsWith('.') && name !== '.env') {
+                if (SKIP_DIRS.has(name)) {
+                    continue;
+                }
+            }
+            const full = path.join(dir, name);
+            const rel = path.relative(root, full).replace(/\\/g, '/');
+            if (e.isDirectory()) {
+                if (!SKIP_DIRS.has(name)) {
+                    await walk(full, depth + 1);
+                }
+                continue;
+            }
+            if (SKIP_EXT.test(name)) {
+                continue;
+            }
+            try {
+                const st = await fs.stat(full);
+                scored.push({ rel, mtime: st.mtimeMs });
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    await walk(root, 0);
+    scored.sort((a, b) => b.mtime - a.mtime);
+    return scored.slice(0, maxFiles).map((s) => s.rel);
+}
+/** Mode B — workspace filesystem scan (no IDE required). */
+export async function scanWorkspace(workspaceRoot) {
+    const root = path.resolve(workspaceRoot);
+    const now = Date.now();
+    const [git, topLevelModules, recentFiles, readmeHint] = await Promise.all([
+        scanGitPorcelain(root),
+        listTopLevelModules(root),
+        collectRecentFiles(root, 24, 5),
+        readReadmeHint(root),
+    ]);
+    return {
+        workspaceRoot: root,
+        scannedAt: now,
+        topLevelModules,
+        recentFiles,
+        gitStaged: git.staged,
+        gitWorking: git.working,
+        readmeHint,
+        isGitRepo: git.isRepo,
+    };
+}