brainclaw 1.9.1 → 1.10.0

package/dist/commands/switch.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { loadActiveProject, saveActiveProject, clearActiveProject } from '../core/active-project.js';
-import { buildOperationalIdentity, loadCurrentSession, loadSessionById, saveCurrentSession } from '../core/identity.js';
+import { buildOperationalIdentity, loadCurrentSession, loadSessionById, resolveCurrentSessionId, saveCurrentSession } from '../core/identity.js';
 import { memoryExists } from '../core/io.js';
 import { resolveProjectRef } from '../core/store-resolution.js';
 import { resolveCrossProjectLinks, resolveProjectCwd } from '../core/cross-project.js';
@@ -160,59 +160,70 @@ export function runSwitch(projectRef, options = {}) {
     }
     // --list: show available projects
     if (options.list) {
-        listProjects(wsRoot, options.json ?? false);
+        listProjects(wsRoot, cwd, options.json ?? false);
         return;
     }
-    // --clear: remove active project
+    // --clear: remove active project. Session-scoped by default (F3) — clearing
+    // the SHARED global pointer is an opt-in (--global) so one agent's clear no
+    // longer wipes every other agent's resolution.
     if (options.clear) {
-        const session = loadCurrentSession(cwd);
-        if (session?.active_project) {
-            const { active_project: _removed, ...rest } = session;
-            saveCurrentSession(rest, cwd);
+        let scope;
+        if (options.global) {
+            clearActiveProject(wsRoot);
+            scope = 'global';
+        }
+        else {
+            const session = loadCurrentSession(cwd);
+            if (session?.active_project) {
+                const { active_project: _removed, ...rest } = session;
+                saveCurrentSession(rest, cwd);
+            }
+            scope = 'session';
         }
-        clearActiveProject(wsRoot);
         if (options.json) {
-            console.log(JSON.stringify({ cleared: true }));
+            console.log(JSON.stringify({ cleared: true, scope }));
         }
         else {
-            console.log('✔ Active project cleared. Commands will use current directory.');
+            const hint = scope === 'session' ? ' (session-scoped)' : ' (global)';
+            console.log(`✔ Active project cleared${hint}. Commands will use current directory.`);
         }
         return;
     }
     // No argument: show current active project
     if (!projectRef) {
-        showCurrent(wsRoot, options.json ?? false);
+        showCurrent(wsRoot, cwd, options.json ?? false);
         return;
     }
     // Switch to project
-    const resolved = resolveProjectRef(projectRef, cwd);
-    if (!resolved) {
-        console.error(`Error: cannot resolve project "${projectRef}".`);
-        console.error('Use `brainclaw switch --list` to see available projects.');
-        process.exit(1);
-    }
-    let projectName;
-    try {
-        const config = loadConfig(resolved);
-        projectName = config.project_name;
-    }
-    catch {
-        // name is optional
-    }
     const now = new Date().toISOString();
-    const session = loadCurrentSession(cwd);
-    const scopedToSession = options.session ?? !!session;
     let scope;
-    if (scopedToSession && session) {
-        // Write to session state — only this agent sees this switch
-        saveCurrentSession({
-            ...session,
-            active_project: { path: resolved, name: projectName, switched_at: now },
-        }, cwd);
-        scope = 'session';
-    }
-    else {
-        // Fall back to global active-project.json
+    let switchedPath;
+    let switchedName;
+    if (options.global) {
+        // Opt-in, audited: set the SHARED workspace default for every agent on the
+        // host. Bypasses the session entirely (an operator setting a default).
+        // Resolve store-chain children AND cross-project links (mirror switchProject)
+        // so `switch <linked> --global` matches what --list shows and what the
+        // session path can target (Codex final review F3-F5 finding).
+        let resolved = resolveProjectRef(projectRef, cwd);
+        if (!resolved) {
+            try {
+                const linkResolved = resolveProjectCwd(projectRef, cwd);
+                if (linkResolved !== cwd)
+                    resolved = linkResolved;
+            }
+            catch { /* falls through to the error below */ }
+        }
+        if (!resolved) {
+            console.error(`Error: cannot resolve project "${projectRef}".`);
+            console.error('Use `brainclaw switch --list` to see available projects.');
+            process.exit(1);
+        }
+        let projectName;
+        try {
+            projectName = loadConfig(resolved).project_name;
+        }
+        catch { /* name is optional */ }
         saveActiveProject(wsRoot, {
             path: resolved,
             name: projectName,
@@ -220,21 +231,47 @@ export function runSwitch(projectRef, options = {}) {
             switched_by: process.env.BRAINCLAW_AGENT_NAME ?? process.env.USER ?? 'unknown',
         });
         scope = 'global';
+        switchedPath = resolved;
+        switchedName = projectName;
+    }
+    else {
+        // F3 default: session-scoped + isolated. Delegate to switchProject — the
+        // safe model that auto-creates the session, honours an explicit
+        // BRAINCLAW_SESSION_ID (resolveCurrentSessionId returns it WITHOUT
+        // persisting, so the session file must be created), resolves cross-project
+        // links, and never touches the shared global pointer.
+        try {
+            const explicitSessionId = resolveCurrentSessionId(process.env, cwd) || undefined;
+            const result = switchProject(projectRef, { cwd, sessionOnly: true, sessionId: explicitSessionId });
+            scope = 'session';
+            switchedPath = result.path;
+            switchedName = result.name;
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}`);
+            console.error('Use `brainclaw switch --list` to see available projects.');
+            process.exit(1);
+        }
     }
     if (options.json) {
-        console.log(JSON.stringify({ switched: true, path: resolved, name: projectName, scope }));
+        console.log(JSON.stringify({ switched: true, path: switchedPath, name: switchedName, scope }));
     }
     else {
-        const rel = path.relative(wsRoot, resolved) || '.';
-        const scopeHint = scope === 'session' ? ' (session-scoped)' : '';
-        console.log(`✔ Switched to ${projectName ? `"${projectName}" (${rel})` : rel}${scopeHint}`);
+        const rel = path.relative(wsRoot, switchedPath) || '.';
+        const scopeHint = scope === 'session' ? ' (session-scoped)' : ' (global — all agents)';
+        console.log(`✔ Switched to ${switchedName ? `"${switchedName}" (${rel})` : rel}${scopeHint}`);
     }
 }
-function showCurrent(wsRoot, json) {
-    const active = loadActiveProject(wsRoot);
+function showCurrent(wsRoot, cwd, json) {
+    // F5: prefer the session's own active project so an agent sees its own
+    // session-scoped switch, not just the shared global pointer.
+    const sessionActive = loadCurrentSession(cwd)?.active_project;
+    const globalActive = loadActiveProject(wsRoot);
+    const active = sessionActive ?? globalActive;
+    const source = sessionActive ? 'session' : globalActive ? 'global' : 'none';
     if (!active) {
         if (json) {
-            console.log(JSON.stringify({ active: false }));
+            console.log(JSON.stringify({ active: false, scope: 'none' }));
         }
         else {
             console.log('No active project. Commands use current directory.');
@@ -243,67 +280,41 @@ function showCurrent(wsRoot, json) {
         return;
     }
     const rel = path.relative(wsRoot, active.path) || '.';
+    const switchedBy = 'switched_by' in active ? active.switched_by : undefined;
     if (json) {
-        console.log(JSON.stringify({ active: true, ...active, relative_path: rel }));
+        console.log(JSON.stringify({ active: true, ...active, relative_path: rel, scope: source }));
     }
     else {
-        console.log(`Active project: ${active.name ? `"${active.name}" (${rel})` : rel}`);
+        const scopeHint = source === 'session' ? ' (session-scoped)' : ' (global — all agents)';
+        console.log(`Active project: ${active.name ? `"${active.name}" (${rel})` : rel}${scopeHint}`);
         console.log(`  switched at: ${active.switched_at}`);
-        if (active.switched_by)
-            console.log(`  switched by: ${active.switched_by}`);
+        if (switchedBy)
+            console.log(`  switched by: ${switchedBy}`);
     }
 }
-function listProjects(wsRoot, json) {
-    const active = loadActiveProject(wsRoot);
-    const projects = [];
-    // Add workspace root itself
-    if (memoryExists(wsRoot)) {
-        try {
-            const config = loadConfig(wsRoot);
-            projects.push({
-                name: config.project_name,
-                path: wsRoot,
-                relative_path: '.',
-                active: active?.path === wsRoot,
-            });
-        }
-        catch {
-            projects.push({
-                path: wsRoot,
-                relative_path: '.',
-                active: active?.path === wsRoot,
-            });
-        }
-    }
-    // Discover child projects (depth 7 covers deep workspace layouts like /srv/dev/repos/global/applications/*/...)
-    const children = scanNestedBrainclawProjects(wsRoot, 7);
-    for (const child of children) {
-        const childPath = path.resolve(child.path);
-        if (childPath === wsRoot)
-            continue;
-        const rel = path.relative(wsRoot, childPath) || '.';
-        projects.push({
-            name: child.project_name,
-            path: childPath,
-            relative_path: rel,
-            active: active?.path === childPath,
-        });
-    }
+function listProjects(wsRoot, cwd, json) {
+    // F5: delegate to the session-aware lister so the active marker reflects the
+    // agent's own session active project, falling back to the global pointer.
+    const result = listAvailableProjectsForSession(cwd);
     if (json) {
-        console.log(JSON.stringify({ workspace: wsRoot, projects }, null, 2));
+        console.log(JSON.stringify({
+            workspace: result.workspace_root,
+            active_source: result.active_source,
+            projects: result.projects,
+        }, null, 2));
         return;
     }
-    if (projects.length === 0) {
+    if (result.projects.length === 0) {
         console.log('No brainclaw projects found in this workspace.');
         return;
     }
-    console.log(`Projects in ${wsRoot}:\n`);
-    for (const p of projects) {
+    console.log(`Projects in ${result.workspace_root}:\n`);
+    for (const p of result.projects) {
         const marker = p.active ? '→ ' : '  ';
         const name = p.name ? `${p.name} (${p.relative_path})` : p.relative_path;
         console.log(`${marker}${name}`);
     }
-    if (!active) {
+    if (result.active_source === 'none') {
         console.log('\nNo active project. Use `brainclaw switch <project>` to set one.');
     }
 }

package/dist/core/agent-files.js

@@ -24,6 +24,18 @@ This project uses brainclaw for shared coordination between humans and agents.
 2. Check **Your open work** for active claims and in-progress plans assigned to you
 3. Respect active claims from other agents — check \`brainclaw claim list\` before editing a claimed scope
 
+### Before editing unfamiliar code (Code Map)
+
+Don't grep the repo blind. Orient with the Code Map first:
+
+\`\`\`bash
+brainclaw code-map brief <symbol-or-path>   # ranked reading list + related decisions/traps (MCP: bclaw_code_brief)
+brainclaw code-map find <name>              # locate a symbol/class/component (MCP: bclaw_code_find)
+brainclaw code-map status                   # freshness
+brainclaw code-map refresh --all            # when status is missing_index
+brainclaw code-map refresh --changed        # when status is stale_*
+\`\`\`
+
 ### Before finishing (required)
 
 1. Release claims you opened: \`brainclaw claim release <id>\` — or \`brainclaw session-end --auto-release\`

package/dist/core/code-map/backend.js

@@ -0,0 +1,123 @@
+/**
+ * CodeQueryBackend — the agent-facing query contract (spec §8).
+ *
+ * Introduced in P0 so a future Memgraph (or other) backend can be added without
+ * changing the agent-facing APIs. P0 ships exactly one implementation:
+ * `JsonlBackend`. In this sprint, `status()` and `refresh()` are minimally real
+ * (they read/init the durable store and report freshness); `find()`/`brief()`
+ * return not-yet-implemented placeholders that still carry a real
+ * `freshness_badge`, locking the response shape for later sprints.
+ */
+import path from 'node:path';
+import { readManifest, storeExists } from './store.js';
+import { refresh as runRefresh } from './refresh.js';
+import { brief as runBrief, find as runFind } from './query.js';
+import { defaultMemoryReader } from './memory-reader.js';
+/** spec §9 caps the brief reading list at 12 files. */
+export const BRIEF_FILE_CAP = 12;
+function badge(status, details = {}) {
+    return { status, details };
+}
+/**
+ * P0 JSONL-backed query backend. Reads the durable file store (manifest +
+ * shards + indexes); no graph DB. find()/brief() are stubbed for Sprint 1.
+ */
+export class JsonlBackend {
+    /**
+     * Related-memory read seam (spec §11). Defaults to the canonical entity read
+     * path; tests inject an in-memory reader to assert attachment without a store.
+     */
+    memoryReader;
+    constructor(opts = {}) {
+        this.memoryReader = opts.memoryReader ?? defaultMemoryReader;
+    }
+    async status(input) {
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        if (!manifest) {
+            return {
+                store_exists: storeExists(input.cwd, input.preferredDirName),
+                freshness_badge: badge('missing_index'),
+                stats: null,
+            };
+        }
+        return {
+            store_exists: true,
+            freshness_badge: badge(manifest.freshness.status, {
+                stale_file_count: manifest.freshness.stale_file_count,
+                partial_reason: manifest.freshness.partial_reason,
+            }),
+            stats: {
+                files_indexed: manifest.stats.files_indexed,
+                nodes: manifest.stats.nodes,
+                edges: manifest.stats.edges,
+            },
+        };
+    }
+    /**
+     * Real refresh (spec §7): resolves project identity (input -> manifest ->
+     * cwd-derived default), then runs the Tree-sitter parse + index + materialize
+     * pipeline behind the project lock. A live competing lock fails fast with a
+     * clear status — refresh never blocks bclaw_work (rule 8).
+     */
+    async refresh(input) {
+        const scope = input.scope ?? 'changed';
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const projectRoot = input.projectRoot ?? manifest?.project_root ?? input.cwd ?? process.cwd();
+        const projectId = input.projectId ?? manifest?.project_id ?? `prj_${path.basename(path.resolve(projectRoot))}`;
+        const result = await runRefresh({
+            projectId,
+            projectRoot,
+            scope,
+            cwd: input.cwd,
+            preferredDirName: input.preferredDirName,
+            ownerAgent: input.ownerAgent ?? null,
+            ownerAgentId: input.ownerAgentId ?? null,
+        });
+        return {
+            ran: result.ran,
+            scope,
+            lock_acquired: result.lock_acquired,
+            freshness_badge: badge(result.freshness.status, {
+                stale_file_count: result.freshness.stale_file_count,
+                partial_reason: result.freshness.partial_reason,
+                files_parsed: result.files_parsed,
+                files_compacted: result.files_compacted,
+                duration_ms: result.duration_ms,
+            }),
+            ...(result.lock_status ? { lock_status: result.lock_status } : {}),
+        };
+    }
+    /**
+     * Agent-facing symbol search (spec §12.1). Ranks symbols-index matches and
+     * lazily validates each backing shard against the live file before serving it
+     * as confident (§6.1); the response badge reflects any detected drift.
+     */
+    async find(input) {
+        const ctx = this.queryContext(input);
+        const out = runFind(input.query, input.limit, ctx);
+        return {
+            query: out.query,
+            matches: out.matches,
+            freshness_badge: { status: out.freshness_badge.status, details: out.freshness_badge.details },
+        };
+    }
+    /**
+     * Agent-facing reading list (spec §9, §11). Produces a ranked
+     * suggested_files_to_read (cap 12), attaches related brainclaw memory (cap 5),
+     * and carries a §6.1 lazy-validated freshness badge.
+     */
+    async brief(input) {
+        const ctx = this.queryContext(input);
+        const out = runBrief(input.target, input.limit, ctx, this.memoryReader);
+        return {
+            target: out.target,
+            suggested_files_to_read: out.suggested_files_to_read,
+            related_memory: out.related_memory,
+            freshness_badge: { status: out.freshness_badge.status, details: out.freshness_badge.details },
+        };
+    }
+    queryContext(input) {
+        return { cwd: input.cwd, preferredDirName: input.preferredDirName };
+    }
+}
+//# sourceMappingURL=backend.js.map

package/dist/core/code-map/core.js

@@ -0,0 +1,81 @@
+import { finalize } from './finalizer.js';
+import { defaultRegistry } from './lang/providers.js';
+/**
+ * The default registry is constructed + registered in `lang/providers.ts` (P1b
+ * §3.2) — the declared extension point for "which providers ship by default".
+ * Re-exported here so existing importers (`core.js`) keep working unchanged.
+ */
+export { defaultRegistry };
+const SERVICES = { version: '0.1.0' };
+function fileOnlyResult(input, parseStatus) {
+    // Reuse the finalizer over an empty draft so the file node id matches exactly.
+    return finalize({
+        file: { path: input.path },
+        definitions: [],
+        imports: [],
+        exports: [],
+        tests: [],
+        facts: [{ code: 'skipped_unsupported', message: `no provider for ${input.path}` }],
+        attributes: { parseStatus },
+    }, input);
+}
+/** Delete the retained parse tree (best-effort). */
+function releaseTree(draft) {
+    const tree = draft.attributes?.__tree;
+    if (tree) {
+        try {
+            tree.delete();
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}
+/**
+ * Extract a single file via the provider pipeline. Signature-compatible with the
+ * legacy `extractor.ts:extractFile`. Resolves the provider by path; an unsupported
+ * extension yields a `skipped_unsupported` file-only result (never throws).
+ */
+export async function extractFile(input, registry = defaultRegistry) {
+    const resolved = registry.providerForPath(input.path);
+    if (!resolved) {
+        return fileOnlyResult(input, 'skipped_unsupported');
+    }
+    const { provider, lang } = resolved;
+    // The caller's `input.lang` is authoritative for identity (it matches what the
+    // refresh pipeline resolved + what the oracle froze). We pass it through; the
+    // resolved `lang` is used only as a cross-check / for providers that re-resolve.
+    const providerInput = {
+        projectId: input.projectId,
+        path: input.path,
+        lang: input.lang,
+        source: input.source,
+        sizeBytes: input.sizeBytes,
+        maxParseFileBytes: input.maxParseFileBytes,
+        maxQueryWaitMs: input.maxQueryWaitMs,
+    };
+    void lang;
+    let draft = await provider.extractDraft(providerInput, SERVICES);
+    if (provider.refine) {
+        try {
+            draft = await provider.refine(draft, { input: providerInput, lang: input.lang });
+        }
+        catch (err) {
+            // Fall back to the pre-refine draft + a loud diagnostic (never drop the file).
+            draft = {
+                ...draft,
+                facts: [
+                    ...draft.facts,
+                    { code: 'refine_error', message: err instanceof Error ? err.message : String(err) },
+                ],
+            };
+        }
+    }
+    try {
+        return finalize(draft, input);
+    }
+    finally {
+        releaseTree(draft);
+    }
+}
+//# sourceMappingURL=core.js.map

package/dist/core/code-map/drafts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=drafts.js.map

package/dist/core/code-map/extractor.js

@@ -0,0 +1,29 @@
+/**
+ * Code Map extractor — THIN backward-compat surface (spec §3, §9 cutover).
+ *
+ * P1a cutover (Sprint 4): the legacy 540-line imperative extractor has been
+ * replaced by the query-driven provider pipeline. The real `extractFile` now
+ * lives on the CORE (`core.ts` → registry → provider.extractDraft → refine →
+ * finalize). This module keeps the historical import surface stable:
+ *
+ *  - `extractFile`            re-exported from `core.ts` (provider pipeline).
+ *  - `ExtractInput` / `ExtractResult`  the public extraction shapes (owned here so
+ *                            `core.ts`, `finalizer.ts`, and the oracle tests keep
+ *                            importing them from this module).
+ *  - `hashContent`           sha256 of file contents (used by refresh.ts + query.ts).
+ *
+ * The legacy imperative bodies (handleFunctionDeclaration / handleClassDeclaration
+ * / classifySubtype / returnsJsx / handleImport / markOrAddExport / …) are GONE.
+ * The oracle (`oracle.test.ts`) now exercises this re-export and so doubles as a
+ * provider-path regression guard against the frozen `oracle-golden.json`.
+ */
+import crypto from 'node:crypto';
+// The query-driven CORE entrypoint, re-exported under the historical name so all
+// existing importers (refresh.ts, oracle.test.ts, …) keep resolving `extractFile`
+// here. core.ts imports the types above (type-only → erased, so no runtime cycle).
+export { extractFile } from './core.js';
+/** sha256 of file contents (file_hash on the shard). */
+export function hashContent(source) {
+    return `sha256:${crypto.createHash('sha256').update(source, 'utf-8').digest('hex')}`;
+}
+//# sourceMappingURL=extractor.js.map