@contorium/mcp 0.8.1

package/node_modules/@contora/state-core/dist/state-builder/snapshot.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatProjectSnapshotMarkdown = formatProjectSnapshotMarkdown;
+exports.projectSnapshotBulletLines = projectSnapshotBulletLines;
+function section(title, items, empty = '(none yet)') {
+    const lines = [title + ':'];
+    if (!items.length) {
+        lines.push(empty);
+        return lines;
+    }
+    for (const item of items) {
+        lines.push(`- ${item}`);
+    }
+    return lines;
+}
+/** Human-readable PROJECT SNAPSHOT — shared by IDE, MCP, and CLI. */
+function formatProjectSnapshotMarkdown(state) {
+    const lines = ['PROJECT SNAPSHOT', ''];
+    lines.push('Goal:');
+    lines.push(state.project_goal.trim() ||
+        '(not inferred from events yet — add README or continue editing)');
+    lines.push('');
+    lines.push('Current Stage:');
+    lines.push(state.current_stage.trim() || '(undetermined)');
+    lines.push('');
+    lines.push(...section('Active Modules', state.active_modules));
+    lines.push('');
+    lines.push(...section('Recent Decisions', state.recent_decisions));
+    lines.push('');
+    lines.push(...section('Open Problems', state.open_problems));
+    lines.push('');
+    lines.push(...section('Completed Milestones', state.completed_milestones));
+    lines.push('');
+    lines.push(...section('Next Actions', state.next_actions));
+    lines.push('');
+    return lines.join('\n');
+}
+function projectSnapshotBulletLines(state) {
+    const out = [];
+    if (state.project_goal) {
+        out.push(`Goal: ${state.project_goal}`);
+    }
+    if (state.current_stage) {
+        out.push(`Stage: ${state.current_stage}`);
+    }
+    for (const p of state.open_problems.slice(0, 2)) {
+        out.push(`Problem: ${p}`);
+    }
+    for (const a of state.next_actions.slice(0, 2)) {
+        out.push(`Next: ${a}`);
+    }
+    return out;
+}

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

@@ -0,0 +1,7 @@
+import { type ProjectBuiltState } from './types.js';
+export declare function builderDir(workspaceRoot: string): string;
+export declare function parseProjectBuiltState(raw: unknown): ProjectBuiltState | undefined;
+export declare function readProjectBuiltState(workspaceRoot: string): Promise<ProjectBuiltState | undefined>;
+export declare function readProjectSnapshotMarkdown(workspaceRoot: string): Promise<string | undefined>;
+export declare function writeProjectBuiltState(workspaceRoot: string, built: ProjectBuiltState, snapshotMarkdown?: string): Promise<void>;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/state-builder/store.ts"],"names":[],"mappings":"AAGA,OAAO,EAA+B,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAIjF,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAwBlF;AAED,wBAAsB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAOzG;AAED,wBAAsB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAOpG;AAED,wBAAsB,sBAAsB,CAC1C,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,iBAAiB,EACxB,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/node_modules/@contora/state-core/dist/state-builder/store.js

@@ -0,0 +1,99 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.builderDir = builderDir;
+exports.parseProjectBuiltState = parseProjectBuiltState;
+exports.readProjectBuiltState = readProjectBuiltState;
+exports.readProjectSnapshotMarkdown = readProjectSnapshotMarkdown;
+exports.writeProjectBuiltState = writeProjectBuiltState;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const snapshot_js_1 = require("./snapshot.js");
+const types_js_1 = require("./types.js");
+const BUILDER_REL = ['.contora', 'state-builder'];
+function builderDir(workspaceRoot) {
+    return path.join(workspaceRoot, ...BUILDER_REL);
+}
+function parseProjectBuiltState(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return undefined;
+    }
+    const o = raw;
+    if (o.version !== types_js_1.PROJECT_BUILT_STATE_VERSION) {
+        return undefined;
+    }
+    const strList = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string') : [];
+    return {
+        version: types_js_1.PROJECT_BUILT_STATE_VERSION,
+        generatedAt: typeof o.generatedAt === 'number' ? o.generatedAt : Date.now(),
+        task_anchor: typeof o.task_anchor === 'string' ? o.task_anchor : undefined,
+        engine_version: typeof o.engine_version === 'number' ? o.engine_version : undefined,
+        project_goal: typeof o.project_goal === 'string' ? o.project_goal : '',
+        current_stage: typeof o.current_stage === 'string' ? o.current_stage : '',
+        active_modules: strList(o.active_modules),
+        recent_decisions: strList(o.recent_decisions),
+        open_problems: strList(o.open_problems),
+        completed_milestones: strList(o.completed_milestones),
+        next_actions: strList(o.next_actions),
+        confidence: typeof o.confidence === 'number' ? o.confidence : 0,
+    };
+}
+async function readProjectBuiltState(workspaceRoot) {
+    try {
+        const text = await fs.readFile(path.join(builderDir(workspaceRoot), 'project-state.json'), 'utf8');
+        return parseProjectBuiltState(JSON.parse(text));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readProjectSnapshotMarkdown(workspaceRoot) {
+    try {
+        const text = (await fs.readFile(path.join(builderDir(workspaceRoot), 'project-snapshot.md'), 'utf8')).trim();
+        return text.length ? text : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeProjectBuiltState(workspaceRoot, built, snapshotMarkdown) {
+    const dir = builderDir(workspaceRoot);
+    await fs.mkdir(dir, { recursive: true });
+    const md = snapshotMarkdown ?? (0, snapshot_js_1.formatProjectSnapshotMarkdown)(built);
+    await Promise.all([
+        fs.writeFile(path.join(dir, 'project-state.json'), JSON.stringify(built, null, 2), 'utf8'),
+        fs.writeFile(path.join(dir, 'project-snapshot.md'), md, 'utf8'),
+    ]);
+}

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

@@ -0,0 +1,18 @@
+/** State Builder — AI-agnostic project state (`.contora/state-builder/project-state.json`). */
+export interface ProjectBuiltState {
+    version: 1;
+    engine_version?: number;
+    generatedAt: number;
+    task_anchor?: string;
+    project_goal: string;
+    current_stage: string;
+    active_modules: string[];
+    recent_decisions: string[];
+    open_problems: string[];
+    completed_milestones: string[];
+    next_actions: string[];
+    confidence: number;
+}
+export declare const PROJECT_BUILT_STATE_VERSION: 1;
+export declare function emptyProjectBuiltState(now?: number): ProjectBuiltState;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/state-builder/types.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAE/F,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,CAAC,CAAC;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,2BAA2B,EAAG,CAAU,CAAC;AAEtD,wBAAgB,sBAAsB,CAAC,GAAG,SAAa,GAAG,iBAAiB,CAa1E"}

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

@@ -0,0 +1,20 @@
+"use strict";
+/** State Builder — AI-agnostic project state (`.contora/state-builder/project-state.json`). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROJECT_BUILT_STATE_VERSION = void 0;
+exports.emptyProjectBuiltState = emptyProjectBuiltState;
+exports.PROJECT_BUILT_STATE_VERSION = 1;
+function emptyProjectBuiltState(now = Date.now()) {
+    return {
+        version: exports.PROJECT_BUILT_STATE_VERSION,
+        generatedAt: now,
+        project_goal: '',
+        current_stage: '',
+        active_modules: [],
+        recent_decisions: [],
+        open_problems: [],
+        completed_milestones: [],
+        next_actions: [],
+        confidence: 0,
+    };
+}

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

@@ -0,0 +1,42 @@
+/** Tool-agnostic workspace facts (filesystem is source of truth). */
+export type StateEngineMode = 'event-driven' | 'scan-driven' | 'merged';
+export type AdapterKind = 'ide' | 'mcp' | 'cli';
+export interface StateSourceMetadata {
+    mode: StateEngineMode;
+    lastWriter: AdapterKind;
+    /** ISO-8601 timestamp */
+    lastUpdated: string;
+}
+export interface WorkspaceScanFacts {
+    workspaceRoot: string;
+    scannedAt: number;
+    topLevelModules: string[];
+    recentFiles: string[];
+    gitStaged: string[];
+    gitWorking: string[];
+    readmeHint?: string;
+    isGitRepo: boolean;
+}
+/** Minimal state.json shape — backward compatible; `source` is v2.2 additive. */
+export interface BootstrapStateJson {
+    sessionId: string;
+    currentTask: string;
+    openFiles: string[];
+    recentFiles: string[];
+    gitStaged: string[];
+    gitWorking: string[];
+    notes: string;
+    lastUpdated: number;
+    source?: StateSourceMetadata;
+}
+export interface DualModeInput {
+    mode: StateEngineMode;
+    state: BootstrapStateJson;
+    eventCount: number;
+    scan?: WorkspaceScanFacts;
+}
+export interface WriteStateOptions {
+    mode: StateEngineMode;
+    writer: AdapterKind;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,qEAAqE;AAErE,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,aAAa,GAAG,QAAQ,CAAC;AAExE,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAEhD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,UAAU,EAAE,WAAW,CAAC;IACxB,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,kBAAkB,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,WAAW,CAAC;CACrB"}

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

@@ -0,0 +1,3 @@
+"use strict";
+/** Tool-agnostic workspace facts (filesystem is source of truth). */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,22 @@
+import type { BootstrapStateJson, WorkspaceScanFacts } from '../types.js';
+import type { ProjectBuiltState } from '../state-builder/types.js';
+import type { ProjectKnowledgeGraph } from './knowledgeGraph/types.js';
+import type { ChangeArtifact, HandoffArtifact, ProjectGraph, ProjectTimeline } from './types.js';
+export interface UnderstandingBuildInput {
+    workspaceRoot: string;
+    state?: BootstrapStateJson;
+    built?: ProjectBuiltState | null;
+    scan?: WorkspaceScanFacts;
+    extraChangedPaths?: string[];
+}
+export interface UnderstandingBuildResult {
+    graph: ProjectGraph;
+    change: ChangeArtifact;
+    handoff: HandoffArtifact;
+    timeline: ProjectTimeline;
+    knowledge: ProjectKnowledgeGraph;
+}
+export declare function buildUnderstandingArtifacts(input: UnderstandingBuildInput): Promise<UnderstandingBuildResult | undefined>;
+/** Build and persist V3.1 understanding artifacts (graph + change + handoff + timeline). */
+export declare function buildAndWriteUnderstandingArtifacts(input: UnderstandingBuildInput): Promise<UnderstandingBuildResult | undefined>;
+//# sourceMappingURL=buildUnderstanding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"buildUnderstanding.d.ts","sourceRoot":"","sources":["../../src/understanding/buildUnderstanding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAWnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAMvE,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEjG,MAAM,WAAW,uBAAuB;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,KAAK,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,qBAAqB,CAAC;CAClC;AAED,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,wBAAwB,GAAG,SAAS,CAAC,CA2D/C;AAED,4FAA4F;AAC5F,wBAAsB,mCAAmC,CACvD,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,wBAAwB,GAAG,SAAS,CAAC,CAe/C"}

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

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUnderstandingArtifacts = buildUnderstandingArtifacts;
+exports.buildAndWriteUnderstandingArtifacts = buildAndWriteUnderstandingArtifacts;
+const store_js_1 = require("../state-builder/store.js");
+const bootstrapState_js_1 = require("../bootstrap/bootstrapState.js");
+const changeDetector_js_1 = require("./changeDetector.js");
+const graphBuilder_js_1 = require("./graphBuilder.js");
+const impactAnalyzer_js_1 = require("./impactAnalyzer.js");
+const intentFusion_js_1 = require("./intentFusion.js");
+const handoffBuilder_js_1 = require("./handoffBuilder.js");
+const timelineTracker_js_1 = require("./timelineTracker.js");
+const gitFrequency_js_1 = require("./knowledgeGraph/gitFrequency.js");
+const knowledgeGraphBuilder_js_1 = require("./knowledgeGraph/knowledgeGraphBuilder.js");
+const store_js_2 = require("./knowledgeGraph/store.js");
+const rebuildTrigger_js_1 = require("./knowledgeGraph/rebuildTrigger.js");
+const understandingGraphBuilder_js_1 = require("./understandingGraphBuilder.js");
+const store_js_3 = require("./store.js");
+const version_js_1 = require("../version.js");
+async function buildUnderstandingArtifacts(input) {
+    const root = input.workspaceRoot;
+    const state = input.state ?? (await (0, bootstrapState_js_1.readStateJson)(root));
+    if (!state) {
+        return undefined;
+    }
+    const changedFiles = await (0, changeDetector_js_1.resolveChangedFiles)(root, state, input.scan, input.extraChangedPaths ?? []);
+    if (!changedFiles.length) {
+        return undefined;
+    }
+    const now = Date.now();
+    const built = input.built ?? (await (0, store_js_1.readProjectBuiltState)(root));
+    const { graph, extractions } = await (0, graphBuilder_js_1.buildChangeNeighborhoodGraph)(root, changedFiles, now);
+    const change = (0, graphBuilder_js_1.deriveChangeArtifact)(changedFiles, extractions, now);
+    const impact = (0, impactAnalyzer_js_1.analyzeImpact)(graph, change);
+    const intent = (0, intentFusion_js_1.fuseIntent)({ state, change, built });
+    const goal = built?.project_goal?.trim() || state.currentTask.trim();
+    const handoff = (0, handoffBuilder_js_1.buildHandoff)({ goal, intent, change, impact, graph, built, now });
+    const timeline = await (0, timelineTracker_js_1.buildProjectTimeline)(root, changedFiles, change, graph, now);
+    const editCounts = new Map();
+    for (const p of [...changedFiles, ...(input.extraChangedPaths ?? [])]) {
+        const k = p.replace(/\\/g, '/');
+        editCounts.set(k, (editCounts.get(k) ?? 0) + 1);
+    }
+    const gitFrequency = (0, gitFrequency_js_1.buildGitFrequency)(timeline, state);
+    const existing = await (0, store_js_2.readProjectKnowledgeGraph)(root);
+    const latestCommit = timeline.recent[0]?.commit;
+    const rebuildTrigger = (0, rebuildTrigger_js_1.resolveKnowledgeRebuildTrigger)({
+        changedFileCount: changedFiles.length,
+        intentChanged: goal !== (existing?.nodes.find((n) => n.type === 'intent')?.name ?? ''),
+        lastBuildAt: existing?.meta.generatedAt,
+        now,
+        hasNewCommit: !!latestCommit && latestCommit !== existing?.meta.lastCommitHash,
+        isInitial: !existing,
+    });
+    const knowledge = (0, knowledgeGraphBuilder_js_1.buildProjectKnowledgeGraph)({
+        graph,
+        change,
+        intent,
+        built,
+        goal,
+        workspaceRoot: root,
+        sourceVersion: (0, version_js_1.getContoriumPackageVersion)(),
+        now,
+        editCounts,
+        gitFrequency,
+        rebuildTrigger,
+        lastCommitHash: latestCommit,
+    });
+    return { graph, change, handoff, timeline, knowledge };
+}
+/** Build and persist V3.1 understanding artifacts (graph + change + handoff + timeline). */
+async function buildAndWriteUnderstandingArtifacts(input) {
+    const result = await buildUnderstandingArtifacts(input);
+    if (!result) {
+        return undefined;
+    }
+    const understandingGraph = (0, understandingGraphBuilder_js_1.buildUnderstandingGraph)({
+        graph: result.graph,
+        change: result.change,
+        handoff: result.handoff,
+        agent: input.state?.source?.lastWriter ?? 'runtime',
+        now: Date.now(),
+    });
+    await (0, store_js_3.writeUnderstandingArtifacts)(input.workspaceRoot, { ...result, understandingGraph });
+    await (0, store_js_2.writeProjectKnowledgeGraph)(input.workspaceRoot, result.knowledge);
+    return result;
+}

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

@@ -0,0 +1,7 @@
+import type { BootstrapStateJson, WorkspaceScanFacts } from '../types.js';
+/** Collect candidate changed files from state + optional scan facts. */
+export declare function collectChangedFiles(state: BootstrapStateJson, extraPaths?: string[], max?: number): string[];
+/** Git diff names (staged + unstaged vs HEAD) — best-effort. */
+export declare function gitDiffChangedFiles(workspaceRoot: string, max?: number): Promise<string[]>;
+export declare function resolveChangedFiles(workspaceRoot: string, state: BootstrapStateJson, scan?: WorkspaceScanFacts, extraPaths?: string[]): Promise<string[]>;
+//# sourceMappingURL=changeDetector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"changeDetector.d.ts","sourceRoot":"","sources":["../../src/understanding/changeDetector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAuB1E,wEAAwE;AACxE,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EACzB,UAAU,GAAE,MAAM,EAAO,EACzB,GAAG,SAAK,GACP,MAAM,EAAE,CAQV;AAED,gEAAgE;AAChE,wBAAsB,mBAAmB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiB5F;AAED,wBAAsB,mBAAmB,CACvC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,kBAAkB,EACzB,IAAI,CAAC,EAAE,kBAAkB,EACzB,UAAU,GAAE,MAAM,EAAO,GACxB,OAAO,CAAC,MAAM,EAAE,CAAC,CAoBnB"}

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

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectChangedFiles = collectChangedFiles;
+exports.gitDiffChangedFiles = gitDiffChangedFiles;
+exports.resolveChangedFiles = resolveChangedFiles;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const extractor_js_1 = require("./extractor.js");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+function norm(p) {
+    return p.replace(/\\/g, '/');
+}
+function uniqueCodeFiles(paths) {
+    const out = [];
+    const seen = new Set();
+    for (const p of paths) {
+        const n = norm(p);
+        if (!n || seen.has(n) || !(0, extractor_js_1.isCodeFile)(n)) {
+            continue;
+        }
+        seen.add(n);
+        out.push(n);
+    }
+    return out;
+}
+/** Collect candidate changed files from state + optional scan facts. */
+function collectChangedFiles(state, extraPaths = [], max = 32) {
+    const merged = [
+        ...state.gitStaged,
+        ...state.gitWorking,
+        ...state.recentFiles.slice(0, 16),
+        ...extraPaths,
+    ];
+    return uniqueCodeFiles(merged).slice(0, max);
+}
+/** Git diff names (staged + unstaged vs HEAD) — best-effort. */
+async function gitDiffChangedFiles(workspaceRoot, max = 32) {
+    try {
+        const { stdout: unstaged } = await execFileAsync('git', ['-C', workspaceRoot, 'diff', '--name-only', 'HEAD'], { timeout: 12_000, maxBuffer: 2 * 1024 * 1024 });
+        const { stdout: staged } = await execFileAsync('git', ['-C', workspaceRoot, 'diff', '--name-only', '--cached', 'HEAD'], { timeout: 12_000, maxBuffer: 2 * 1024 * 1024 });
+        const all = [...unstaged.split('\n'), ...staged.split('\n')].map((l) => l.trim()).filter(Boolean);
+        return uniqueCodeFiles(all).slice(0, max);
+    }
+    catch {
+        return [];
+    }
+}
+async function resolveChangedFiles(workspaceRoot, state, scan, extraPaths = []) {
+    const fromGit = await gitDiffChangedFiles(workspaceRoot);
+    const fromState = collectChangedFiles(state, extraPaths);
+    const fromScan = scan
+        ? uniqueCodeFiles([...scan.gitStaged, ...scan.gitWorking, ...scan.recentFiles.slice(0, 12)])
+        : [];
+    const merged = [...fromGit, ...fromState, ...fromScan];
+    const seen = new Set();
+    const out = [];
+    for (const f of merged) {
+        if (seen.has(f)) {
+            continue;
+        }
+        seen.add(f);
+        out.push(f);
+        if (out.length >= 32) {
+            break;
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,49 @@
+import type { AdapterKind } from '../types.js';
+import type { ChangeArtifact, HandoffArtifact, KeyChange, ProjectTimeline } from './types.js';
+/** Contorium Handoff Protocol v1 — shared AI state shape. */
+export declare const CHP_VERSION: 1;
+export interface ChpRecentChange {
+    type: 'function_update' | 'class_update' | 'file_update';
+    name: string;
+    file?: string;
+    timestamp?: string;
+    change_type?: KeyChange['change_type'];
+}
+export interface ChpAgentContext {
+    active_agent: string;
+    last_action: string;
+}
+export interface ChpHandoffState {
+    version: typeof CHP_VERSION;
+    project: string;
+    workspace_root: string;
+    current_task: string;
+    goal: string;
+    recent_changes: ChpRecentChange[];
+    agent_context: ChpAgentContext;
+    summary: string;
+    last_updated: string;
+}
+export type ChpHandoffFormat = 'json' | 'markdown' | 'compact';
+export interface BuildChpHandoffInput {
+    workspaceRoot: string;
+    handoff?: HandoffArtifact | null;
+    change?: ChangeArtifact | null;
+    currentTask?: string;
+    lastWriter?: AdapterKind | string;
+}
+/** Build CHP v1 from in-memory runtime slices (sync — dashboard / IDE status bar). */
+export declare function buildChpHandoffStateSync(input: BuildChpHandoffInput): ChpHandoffState | null;
+/** Build CHP v1 state from runtime artifacts (single read model). */
+export declare function buildChpHandoffState(input: BuildChpHandoffInput): Promise<ChpHandoffState | null>;
+/** CHP compact one-liner for Passive CLI / IDE status bar. */
+export declare function formatChpCompact(state: ChpHandoffState, filter?: string): string;
+/** CHP markdown — AI chat injection (wraps V3.1 handoff block when available). */
+export declare function formatChpMarkdown(chp: ChpHandoffState, handoff?: HandoffArtifact | null, timeline?: ProjectTimeline): string;
+/** Unified get_handoff — read runtime artifacts and format. */
+export declare function getProjectHandoff(workspaceRoot: string, format?: ChpHandoffFormat, filter?: string): Promise<{
+    found: boolean;
+    text?: string;
+    state?: ChpHandoffState;
+}>;
+//# sourceMappingURL=chpHandoff.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chpHandoff.d.ts","sourceRoot":"","sources":["../../src/understanding/chpHandoff.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI/C,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE9F,6DAA6D;AAC7D,eAAO,MAAM,WAAW,EAAG,CAAU,CAAC;AAEtC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,iBAAiB,GAAG,cAAc,GAAG,aAAa,CAAC;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,WAAW,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,eAAe,EAAE,CAAC;IAClC,aAAa,EAAE,eAAe,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IACjC,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;CACnC;AA6CD,sFAAsF;AACtF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,oBAAoB,GAAG,eAAe,GAAG,IAAI,CAmC5F;AAED,qEAAqE;AACrE,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAejC;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAMhF;AASD,kFAAkF;AAClF,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,eAAe,EACpB,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,EAChC,QAAQ,CAAC,EAAE,eAAe,GACzB,MAAM,CAoCR;AAED,+DAA+D;AAC/D,wBAAsB,iBAAiB,CACrC,aAAa,EAAE,MAAM,EACrB,MAAM,GAAE,gBAA4B,EACpC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,eAAe,CAAA;CAAE,CAAC,CAiCrE"}