brainclaw 0.22.0 → 0.23.0

package/dist/cli.js

@@ -78,6 +78,8 @@ import { runExplore } from './commands/explore.js';
 import { getInstalledBrainclawVersion } from './core/brainclaw-version.js';
 import { cleanOrphanFiles, memoryDir } from './core/io.js';
 import { initLogLevel, logger } from './core/logger.js';
+import { resolveEffectiveCwd } from './core/store-resolution.js';
+import { runSwitch } from './commands/switch.js';
 const program = new Command();
 function collect(value, previous) {
     return [...previous, value];
@@ -88,12 +90,19 @@ program
     .version(getInstalledBrainclawVersion())
     .option('--verbose', 'Show info-level log messages on stderr')
     .option('--debug', 'Show debug-level log messages on stderr')
+    .option('--cwd <path>', 'Override working directory for this invocation')
     .hook('preAction', (_thisCommand, actionCommand) => {
     const root = actionCommand.optsWithGlobals();
     initLogLevel({ verbose: root.verbose, debug: root.debug });
-    const removed = cleanOrphanFiles(memoryDir());
+    // Resolve effective cwd (--cwd > BRAINCLAW_PROJECT > active-project > process.cwd)
+    const effectiveCwd = resolveEffectiveCwd({ explicitCwd: root.cwd });
+    if (effectiveCwd !== process.cwd()) {
+        // Store resolved cwd so commands can read it via optsWithGlobals().cwd
+        actionCommand.setOptionValue('cwd', effectiveCwd);
+    }
+    const removed = cleanOrphanFiles(memoryDir(effectiveCwd));
     if (removed > 0) {
-        logger.info(`Cleaned ${removed} orphan lock/tmp file(s) in ${memoryDir()}`);
+        logger.info(`Cleaned ${removed} orphan lock/tmp file(s) in ${memoryDir(effectiveCwd)}`);
     }
 });
 // --- init ---
@@ -1090,6 +1099,21 @@ program
     .action((options) => {
     runExplore({ query: options.query });
 });
+program
+    .command('switch [project]')
+    .description('Set the active project for subsequent commands')
+    .option('--list', 'List available projects in the workspace')
+    .option('--clear', 'Clear the active project (revert to cwd)')
+    .option('--json', 'Output as JSON')
+    .action((project, options) => {
+    const globalOpts = options.parent?.parent ? program.opts() : {};
+    runSwitch(project, {
+        list: options.list,
+        clear: options.clear,
+        json: options.json,
+        cwd: globalOpts.cwd,
+    });
+});
 program.parseAsync(process.argv).catch((err) => {
     console.error(err);
     process.exit(1);

package/dist/commands/mcp.js

@@ -29,7 +29,7 @@ import { validateMcpInput, validateMcpField } from '../core/input-validation.js'
 import { buildEstimationReport } from './estimation-report.js';
 import { detectAiAgent } from '../core/ai-agent-detection.js';
 import { checkGitPresence, scanGitRepos, parseRoots, parseRepoSelection, parseAgentSelection, runGlobalInstall, initReposAndConfigureAgents, readSetupState, ALL_KNOWN_AGENTS, } from './setup.js';
-import { resolveTargetStore, resolveStoreChain } from '../core/store-resolution.js';
+import { resolveEffectiveCwd, resolveTargetStore, resolveStoreChain } from '../core/store-resolution.js';
 import { probeForQuickSetup, buildQuickSetupProbeResponse, buildOnboardingPreview } from '../core/setup-flow.js';
 import { ensureUserStore } from '../core/setup-state.js';
 import { readUnseenEvents, buildNotificationSummary } from '../core/event-log.js';
@@ -888,7 +888,7 @@ export class McpServerConnection {
     }
 }
 export function runMcp() {
-    const cwd = process.cwd();
+    const cwd = resolveEffectiveCwd();
     if (!memoryExists(cwd)) {
         console.error('Project memory not initialized. Run `brainclaw init` first.');
         process.exit(1);
@@ -991,7 +991,7 @@ function getReviewAssignee(tags) {
     return undefined;
 }
 export function handleMcpReadToolCall(name, args = {}, context = {}) {
-    const cwd = context.cwd ?? process.cwd();
+    const cwd = context.cwd ?? resolveEffectiveCwd();
     if (name === 'bclaw_get_context') {
         const result = buildContext({
             target: args.path,

package/dist/commands/switch.js

@@ -0,0 +1,141 @@
+import path from 'node:path';
+import { loadActiveProject, saveActiveProject, clearActiveProject } from '../core/active-project.js';
+import { memoryExists } from '../core/io.js';
+import { resolveProjectRef, resolveWorkspaceRoot } from '../core/store-resolution.js';
+import { scanNestedBrainclawProjects } from '../core/workspace-projects.js';
+import { loadConfig } from '../core/config.js';
+export function runSwitch(projectRef, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const wsRoot = resolveWorkspaceRoot(cwd);
+    if (!wsRoot) {
+        console.error('Error: no brainclaw workspace found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    // --list: show available projects
+    if (options.list) {
+        listProjects(wsRoot, options.json ?? false);
+        return;
+    }
+    // --clear: remove active project
+    if (options.clear) {
+        clearActiveProject(wsRoot);
+        if (options.json) {
+            console.log(JSON.stringify({ cleared: true }));
+        }
+        else {
+            console.log('✔ Active project cleared. Commands will use current directory.');
+        }
+        return;
+    }
+    // No argument: show current active project
+    if (!projectRef) {
+        showCurrent(wsRoot, 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
+    }
+    saveActiveProject(wsRoot, {
+        path: resolved,
+        name: projectName,
+        switched_at: new Date().toISOString(),
+        switched_by: process.env.BRAINCLAW_AGENT_NAME ?? process.env.USER ?? 'unknown',
+    });
+    if (options.json) {
+        console.log(JSON.stringify({ switched: true, path: resolved, name: projectName }));
+    }
+    else {
+        const rel = path.relative(wsRoot, resolved) || '.';
+        console.log(`✔ Switched to ${projectName ? `"${projectName}" (${rel})` : rel}`);
+    }
+}
+function showCurrent(wsRoot, json) {
+    const active = loadActiveProject(wsRoot);
+    if (!active) {
+        if (json) {
+            console.log(JSON.stringify({ active: false }));
+        }
+        else {
+            console.log('No active project. Commands use current directory.');
+            console.log('Use `brainclaw switch <project>` to set one.');
+        }
+        return;
+    }
+    const rel = path.relative(wsRoot, active.path) || '.';
+    if (json) {
+        console.log(JSON.stringify({ active: true, ...active, relative_path: rel }));
+    }
+    else {
+        console.log(`Active project: ${active.name ? `"${active.name}" (${rel})` : rel}`);
+        console.log(`  switched at: ${active.switched_at}`);
+        if (active.switched_by)
+            console.log(`  switched by: ${active.switched_by}`);
+    }
+}
+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
+    const children = scanNestedBrainclawProjects(wsRoot, 4);
+    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,
+        });
+    }
+    if (json) {
+        console.log(JSON.stringify({ workspace: wsRoot, projects }, null, 2));
+        return;
+    }
+    if (projects.length === 0) {
+        console.log('No brainclaw projects found in this workspace.');
+        return;
+    }
+    console.log(`Projects in ${wsRoot}:\n`);
+    for (const p of projects) {
+        const marker = p.active ? '→ ' : '  ';
+        const name = p.name ? `${p.name} (${p.relative_path})` : p.relative_path;
+        console.log(`${marker}${name}`);
+    }
+    if (!active) {
+        console.log('\nNo active project. Use `brainclaw switch <project>` to set one.');
+    }
+}
+//# sourceMappingURL=switch.js.map

package/dist/core/active-project.js

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { MEMORY_DIR } from './io.js';
+const ACTIVE_PROJECT_FILE = 'active-project.json';
+/**
+ * Load the active project for a workspace.
+ * Returns undefined when no active project is set or the file is unreadable.
+ */
+export function loadActiveProject(workspaceRoot) {
+    const filePath = path.join(workspaceRoot, MEMORY_DIR, ACTIVE_PROJECT_FILE);
+    if (!fs.existsSync(filePath)) {
+        return undefined;
+    }
+    try {
+        const raw = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        if (typeof raw.path !== 'string' || !raw.path) {
+            return undefined;
+        }
+        return {
+            path: raw.path,
+            name: typeof raw.name === 'string' ? raw.name : undefined,
+            switched_at: typeof raw.switched_at === 'string' ? raw.switched_at : new Date().toISOString(),
+            switched_by: typeof raw.switched_by === 'string' ? raw.switched_by : undefined,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Persist the active project for a workspace.
+ */
+export function saveActiveProject(workspaceRoot, project) {
+    const dir = path.join(workspaceRoot, MEMORY_DIR);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const filePath = path.join(dir, ACTIVE_PROJECT_FILE);
+    fs.writeFileSync(filePath, JSON.stringify(project, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Clear the active project (revert to process.cwd() default).
+ */
+export function clearActiveProject(workspaceRoot) {
+    const filePath = path.join(workspaceRoot, MEMORY_DIR, ACTIVE_PROJECT_FILE);
+    if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+    }
+}
+//# sourceMappingURL=active-project.js.map

package/dist/core/repo-analysis.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import YAML from 'yaml';
 import { MEMORY_DIR } from './io.js';
 const MULTI_PROJECT_MARKERS = [
     'pnpm-workspace.yaml',
@@ -11,6 +12,32 @@ const MULTI_PROJECT_MARKERS = [
 const MULTI_PROJECT_DIRS = ['apps', 'packages', 'services'];
 export function analyzeRepository(cwd) {
     const reasons = [];
+    // ── Signal 1: Existing brainclaw config already declares multi-project ──
+    const configPath = path.join(cwd, MEMORY_DIR, 'config.yaml');
+    if (fs.existsSync(configPath)) {
+        try {
+            const raw = YAML.parse(fs.readFileSync(configPath, 'utf-8'));
+            if (raw) {
+                const mode = raw.project_mode;
+                const projects = raw.projects;
+                const strategy = projects?.strategy ?? 'manual';
+                const knownCount = Array.isArray(projects?.known) ? projects.known.length : 0;
+                if (mode === 'multi-project' || strategy === 'folder' || knownCount > 0) {
+                    reasons.push(`Existing brainclaw config: project_mode=${mode ?? 'auto'}, strategy=${strategy}` +
+                        (knownCount > 0 ? `, ${knownCount} known project(s)` : ''));
+                }
+            }
+        }
+        catch {
+            // Config unreadable — fall through to heuristic detection.
+        }
+    }
+    // ── Signal 2: Child brainclaw stores (subdirectories with .brainclaw/) ──
+    const scan = scanChildStoresShallow(cwd);
+    if (scan.length > 0) {
+        reasons.push(`Found ${scan.length} child brainclaw store(s): ${scan.join(', ')}`);
+    }
+    // ── Signal 3: Classic monorepo / workspace markers ──
     for (const marker of MULTI_PROJECT_MARKERS) {
         if (fs.existsSync(path.join(cwd, marker))) {
             reasons.push(`Found workspace marker: ${marker}`);
@@ -46,6 +73,33 @@ export function analyzeRepository(cwd) {
         reasons: ['No monorepo or multi-project markers detected'],
     };
 }
+/**
+ * Quick depth-1 scan for subdirectories that contain a .brainclaw/ store.
+ * Returns relative paths of child stores found.
+ */
+function scanChildStoresShallow(cwd) {
+    const childStores = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(cwd, { withFileTypes: true });
+    }
+    catch {
+        return childStores;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (SKIP_DIRS.has(entry.name))
+            continue;
+        if (entry.name.startsWith('.'))
+            continue;
+        const childBrainclaw = path.join(cwd, entry.name, MEMORY_DIR);
+        if (fs.existsSync(childBrainclaw)) {
+            childStores.push(entry.name);
+        }
+    }
+    return childStores;
+}
 /** Markers whose presence indicates a service/project boundary worth initialising. */
 const SERVICE_MARKERS = [
     'package.json',

package/dist/core/store-resolution.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { loadActiveProject } from './active-project.js';
 import { loadConfig } from './config.js';
 import { MEMORY_DIR } from './io.js';
 import { summarizeWorkspaceProjects } from './workspace-projects.js';
@@ -84,6 +85,98 @@ export function resolveTargetStore(cwd = process.cwd(), target = 'local', option
     const match = chain.find((s) => s.role === 'user');
     return match?.cwd ?? os.homedir();
 }
+/**
+ * Single source of truth for the effective working directory.
+ *
+ * Priority:
+ * 1. explicitCwd (--cwd flag)
+ * 2. BRAINCLAW_PROJECT env var → resolved by name/path from workspace
+ * 3. active-project.json in workspace root
+ * 4. process.cwd()
+ */
+export function resolveEffectiveCwd(options = {}) {
+    // 1. Explicit --cwd flag
+    if (options.explicitCwd) {
+        return path.resolve(options.explicitCwd);
+    }
+    // 2. BRAINCLAW_PROJECT env var
+    const envProject = process.env.BRAINCLAW_PROJECT;
+    if (envProject) {
+        const resolved = resolveProjectRef(envProject, process.cwd(), options.storeChainOptions);
+        if (resolved)
+            return resolved;
+    }
+    // 3. active-project.json from workspace root
+    const wsRoot = resolveWorkspaceRoot(process.cwd(), options.storeChainOptions);
+    if (wsRoot) {
+        const active = loadActiveProject(wsRoot);
+        if (active && fs.existsSync(path.join(active.path, MEMORY_DIR, 'config.yaml'))) {
+            return active.path;
+        }
+    }
+    // 4. Default
+    return process.cwd();
+}
+/**
+ * Find the workspace root (farthest store in the chain, or the one with
+ * role=workspace). Returns undefined when no store exists.
+ */
+export function resolveWorkspaceRoot(cwd = process.cwd(), options = {}) {
+    const chain = resolveStoreChain(cwd, options);
+    if (chain.length === 0)
+        return undefined;
+    const ws = chain.find((s) => s.role === 'workspace');
+    return ws?.cwd ?? chain[chain.length - 1].cwd;
+}
+/**
+ * Resolve a project reference (name or relative path) to an absolute path.
+ * Returns undefined when the reference cannot be resolved to a valid brainclaw project.
+ */
+export function resolveProjectRef(ref, cwd = process.cwd(), storeChainOptions) {
+    const wsRoot = resolveWorkspaceRoot(cwd, storeChainOptions);
+    if (!wsRoot)
+        return undefined;
+    // Try as absolute path
+    if (path.isAbsolute(ref)) {
+        return fs.existsSync(path.join(ref, MEMORY_DIR, 'config.yaml')) ? ref : undefined;
+    }
+    // Try as relative path from workspace root
+    const asPath = path.resolve(wsRoot, ref);
+    if (fs.existsSync(path.join(asPath, MEMORY_DIR, 'config.yaml'))) {
+        return asPath;
+    }
+    // Try by project name: scan child stores for matching project_name
+    const chain = resolveStoreChain(wsRoot, storeChainOptions);
+    for (const store of chain) {
+        if (store.cwd === wsRoot)
+            continue; // skip workspace itself
+        try {
+            const config = loadConfig(store.cwd);
+            if (config.project_name === ref)
+                return store.cwd;
+        }
+        catch {
+            // skip unreadable configs
+        }
+    }
+    // Try discovering child projects by scanning filesystem
+    try {
+        const wsConfig = loadConfig(wsRoot);
+        const summary = summarizeWorkspaceProjects(wsRoot, wsConfig);
+        for (const project of summary.discovered_projects) {
+            const projectPath = path.resolve(wsRoot, project.path);
+            if (project.project_name === ref) {
+                if (fs.existsSync(path.join(projectPath, MEMORY_DIR, 'config.yaml'))) {
+                    return projectPath;
+                }
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    return undefined;
+}
 /**
  * Resolve the most specific child store that should answer a context request.
  *
@@ -104,6 +197,13 @@ export function resolveContextStoreCwd(cwd = process.cwd(), target) {
     if (!absoluteTarget) {
         return cwd;
     }
+    // ── Fast path: walk from target upward to cwd looking for a child store ──
+    // This works regardless of project_mode or strategy configuration.
+    const childStore = findClosestStoreBelow(absoluteTarget, primary.cwd);
+    if (childStore) {
+        return childStore;
+    }
+    // ── Fallback: use workspace project discovery (folder mode, registry, etc.) ──
     let config;
     try {
         config = loadConfig(primary.cwd);
@@ -127,6 +227,37 @@ export function resolveContextStoreCwd(cwd = process.cwd(), target) {
     }
     return cwd;
 }
+/**
+ * Walk from `target` upward toward `ceiling` (exclusive), returning the first
+ * directory that contains a `.brainclaw/config.yaml`.  Returns undefined when
+ * no child store is found between target and ceiling.
+ *
+ * This deliberately bypasses workspace project discovery so that child stores
+ * are resolved even when the parent config is set to auto/manual mode.
+ */
+function findClosestStoreBelow(target, ceiling) {
+    const resolvedCeiling = path.resolve(ceiling);
+    // If target is a file, start from its parent directory
+    let current;
+    try {
+        current = fs.statSync(target).isDirectory() ? path.resolve(target) : path.resolve(path.dirname(target));
+    }
+    catch {
+        // Target doesn't exist on disk — try its parent as a directory
+        current = path.resolve(path.dirname(target));
+    }
+    while (current !== resolvedCeiling) {
+        const configPath = path.join(current, MEMORY_DIR, 'config.yaml');
+        if (fs.existsSync(configPath)) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break; // filesystem root
+        current = parent;
+    }
+    return undefined;
+}
 /**
  * Return true if `dir` is at or below `ancestor` in the filesystem hierarchy.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {