brainclaw 0.19.2

package/dist/core/security.js

@@ -0,0 +1,66 @@
+/**
+ * Scan a text string for sensitive patterns defined in the config.
+ * Returns a list of warnings.
+ */
+export function scanText(text, config) {
+    const warnings = [];
+    if (!config.redaction.enabled)
+        return warnings;
+    const isStrict = config.security?.strict_redaction ?? false;
+    const level = isStrict ? 'block' : 'warn';
+    for (const pattern of config.redaction.patterns) {
+        try {
+            // Strip Python-style inline flags (?i) etc. since we always use 'i' flag
+            const cleanPattern = pattern.replace(/^\(\?[gimsuy]+\)/g, '');
+            const re = new RegExp(cleanPattern, 'i');
+            if (re.test(text)) {
+                warnings.push({
+                    level,
+                    message: `Possible sensitive content matching pattern '${pattern}' found in text`,
+                });
+            }
+        }
+        catch {
+            // skip invalid regex patterns
+        }
+    }
+    const blockPaths = config.security?.block_sensitive_paths ?? true;
+    if (blockPaths) {
+        for (const sp of config.sensitive_paths) {
+            if (text.includes(sp)) {
+                warnings.push({
+                    level: 'warn',
+                    message: `Sensitive path '${sp}' mentioned in text`,
+                });
+            }
+        }
+    }
+    return warnings;
+}
+/**
+ * Run doctor checks on the full state.
+ */
+export function doctorCheck(state, config) {
+    const warnings = [];
+    const sections = [
+        { name: 'active_constraints', items: state.active_constraints },
+        { name: 'recent_decisions', items: state.recent_decisions },
+        { name: 'known_traps', items: state.known_traps },
+        { name: 'open_handoffs', items: state.open_handoffs },
+    ];
+    for (const section of sections) {
+        for (let i = 0; i < section.items.length; i++) {
+            const item = section.items[i];
+            const text = 'text' in item ? item.text : '';
+            const textWarnings = scanText(text, config);
+            for (const w of textWarnings) {
+                warnings.push({
+                    level: w.level,
+                    message: `${w.message} in ${section.name}[${i}] (${item.id})`,
+                });
+            }
+        }
+    }
+    return warnings;
+}
+//# sourceMappingURL=security.js.map

package/dist/core/setup-state.js

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeFileAtomic } from './io.js';
+export function resolveHomeDir(env = process.env) {
+    return env.HOME?.trim() || env.USERPROFILE?.trim() || undefined;
+}
+export function setupStatePath(env = process.env) {
+    const home = resolveHomeDir(env);
+    if (!home)
+        return undefined;
+    return path.join(home, '.brainclaw', 'setup.json');
+}
+export function userStoreConfigPath(env = process.env) {
+    const home = resolveHomeDir(env);
+    if (!home)
+        return undefined;
+    return path.join(home, '.brainclaw', 'config.yaml');
+}
+export function readSetupState(env = process.env) {
+    const statePath = setupStatePath(env);
+    if (!statePath)
+        return undefined;
+    try {
+        if (!fs.existsSync(statePath))
+            return undefined;
+        const raw = fs.readFileSync(statePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeSetupState(state, env = process.env) {
+    const statePath = setupStatePath(env);
+    if (!statePath)
+        return;
+    const dir = path.dirname(statePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    writeFileAtomic(statePath, JSON.stringify(state, null, 2) + '\n');
+}
+export function hasCompletedSetup(env = process.env) {
+    if (readSetupState(env)) {
+        return true;
+    }
+    const configPath = userStoreConfigPath(env);
+    return configPath ? fs.existsSync(configPath) : false;
+}
+//# sourceMappingURL=setup-state.js.map

package/dist/core/state.js

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ConstraintSchema, DecisionSchema, TrapSchema, HandoffSchema, PlanItemSchema } from './schema.js';
+import { ensureMemoryDir, resolveEntityDir } from './io.js';
+import { commitMemoryChange } from './memory-git.js';
+import { appendEvent } from './event-log.js';
+import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
+export function emptyState() {
+    return {
+        version: 1,
+        write_version: 1,
+        active_constraints: [],
+        recent_decisions: [],
+        known_traps: [],
+        open_handoffs: [],
+        plan_items: [],
+    };
+}
+function loadDirectoryItems(dirPath, schema, documentType) {
+    if (!fs.existsSync(dirPath))
+        return [];
+    const files = fs.readdirSync(dirPath).filter(f => f.endsWith('.json'));
+    const items = [];
+    for (const file of files) {
+        try {
+            items.push(schema.parse(loadVersionedJsonFile(documentType, path.join(dirPath, file)).document));
+        }
+        catch {
+            // skip invalid files
+        }
+    }
+    return items;
+}
+export function loadState(cwd) {
+    // Load from entity-aligned directories (with legacy fallback)
+    const effectiveCwd = cwd ?? process.cwd();
+    const state = emptyState();
+    state.active_constraints = loadDirectoryItems(resolveEntityDir('constraints', effectiveCwd, 'read'), ConstraintSchema, 'constraint');
+    state.recent_decisions = loadDirectoryItems(resolveEntityDir('decisions', effectiveCwd, 'read'), DecisionSchema, 'decision');
+    state.known_traps = loadDirectoryItems(resolveEntityDir('traps', effectiveCwd, 'read'), TrapSchema, 'trap');
+    state.open_handoffs = loadDirectoryItems(resolveEntityDir('handoffs', effectiveCwd, 'read'), HandoffSchema, 'handoff');
+    state.plan_items = loadDirectoryItems(resolveEntityDir('plans', effectiveCwd, 'read'), PlanItemSchema, 'plan');
+    // Sort them by creation date for consistency
+    state.active_constraints.sort((a, b) => a.created_at.localeCompare(b.created_at));
+    state.recent_decisions.sort((a, b) => a.created_at.localeCompare(b.created_at));
+    state.known_traps.sort((a, b) => a.created_at.localeCompare(b.created_at));
+    state.open_handoffs.sort((a, b) => a.created_at.localeCompare(b.created_at));
+    state.plan_items.sort((a, b) => a.created_at.localeCompare(b.created_at));
+    return state;
+}
+function syncDirectory(dirPath, items, documentType) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+    // Write all current items
+    const currentIds = new Set();
+    for (const item of items) {
+        currentIds.add(item.id);
+        const filepath = path.join(dirPath, `${item.id}.json`);
+        saveVersionedJsonFile(documentType, filepath, item);
+    }
+    // Remove files that are no longer in the state (e.g. if deleted/pruned)
+    const files = fs.readdirSync(dirPath).filter(f => f.endsWith('.json'));
+    for (const file of files) {
+        const id = file.replace('.json', '');
+        if (!currentIds.has(id)) {
+            fs.unlinkSync(path.join(dirPath, file));
+        }
+    }
+}
+export function saveState(state, cwd) {
+    ensureMemoryDir(cwd);
+    const effectiveCwd = cwd ?? process.cwd();
+    // Write to entity-aligned directories
+    syncDirectory(resolveEntityDir('constraints', effectiveCwd, 'write'), state.active_constraints, 'constraint');
+    syncDirectory(resolveEntityDir('decisions', effectiveCwd, 'write'), state.recent_decisions, 'decision');
+    syncDirectory(resolveEntityDir('traps', effectiveCwd, 'write'), state.known_traps, 'trap');
+    syncDirectory(resolveEntityDir('handoffs', effectiveCwd, 'write'), state.open_handoffs, 'handoff');
+    syncDirectory(resolveEntityDir('plans', effectiveCwd, 'write'), state.plan_items, 'plan');
+    appendEvent({ action: 'update', item_type: 'state', agent: 'system' }, cwd);
+    commitMemoryChange('state update', cwd);
+}
+//# sourceMappingURL=state.js.map

package/dist/core/store-resolution.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { MEMORY_DIR } from './io.js';
+/**
+ * Walk up the filesystem from `cwd`, collecting every `.brainclaw/` directory
+ * found along the way, up to (and including) `boundary`.
+ *
+ * The returned array is ordered from closest to farthest (index 0 = highest
+ * priority). Returns an empty array when no store is found.
+ */
+export function resolveStoreChain(cwd = process.cwd(), options = {}) {
+    const dirName = options.dirName ?? MEMORY_DIR;
+    const boundary = options.boundary ?? process.env.BRAINCLAW_STORE_BOUNDARY ?? os.homedir();
+    const includePartial = options.includePartial ?? false;
+    const results = [];
+    let current = path.resolve(cwd);
+    const boundaryResolved = path.resolve(boundary);
+    let depth = 0;
+    while (true) {
+        const candidate = path.join(current, dirName);
+        if (fs.existsSync(candidate)) {
+            const configPath = path.join(candidate, 'config.yaml');
+            const hasConfig = fs.existsSync(configPath);
+            if (hasConfig || includePartial) {
+                results.push({
+                    storePath: candidate,
+                    cwd: current,
+                    depth,
+                    role: inferRole(candidate, configPath, hasConfig),
+                });
+            }
+        }
+        // Stop at boundary (inclusive — we already checked it above if applicable)
+        if (current === boundaryResolved)
+            break;
+        const parent = path.dirname(current);
+        // Stop if we've hit the filesystem root (dirname returns same path)
+        if (parent === current)
+            break;
+        // Stop if we'd go above the boundary
+        if (!isAtOrBelow(parent, boundaryResolved))
+            break;
+        current = parent;
+        depth++;
+    }
+    return results;
+}
+/**
+ * Return the single "primary" store for a given cwd — the closest one.
+ * Returns undefined when no store exists in the chain.
+ */
+export function resolvePrimaryStore(cwd = process.cwd(), options = {}) {
+    return resolveStoreChain(cwd, options)[0];
+}
+/**
+ * Resolve the effective cwd for a write operation targeting a specific store level.
+ *
+ * - `local`     → the closest store (default, current behaviour)
+ * - `repo`      → the first store with role='repo' in the chain; falls back to closest
+ * - `workspace` → the first store with role='workspace', or the farthest store found
+ * - `user`      → the first store with role='user' in the chain; falls back to os.homedir()
+ *
+ * Returns the original cwd unchanged when no chain exists or when target='local'.
+ */
+export function resolveTargetStore(cwd = process.cwd(), target = 'local', options = {}) {
+    if (target === 'local')
+        return cwd;
+    const chain = resolveStoreChain(cwd, options);
+    if (chain.length === 0)
+        return cwd;
+    if (target === 'repo') {
+        const match = chain.find((s) => s.role === 'repo');
+        return match?.cwd ?? chain[0].cwd;
+    }
+    if (target === 'workspace') {
+        // workspace: prefer declared role, otherwise take farthest
+        const match = chain.find((s) => s.role === 'workspace');
+        return match?.cwd ?? chain[chain.length - 1].cwd;
+    }
+    // user: prefer declared role, otherwise os.homedir()
+    const match = chain.find((s) => s.role === 'user');
+    return match?.cwd ?? os.homedir();
+}
+/**
+ * Return true if `dir` is at or below `ancestor` in the filesystem hierarchy.
+ */
+function isAtOrBelow(dir, ancestor) {
+    const rel = path.relative(ancestor, dir);
+    // If relative path starts with '..', dir is above ancestor
+    return !rel.startsWith('..');
+}
+/**
+ * Infer the store role from config.yaml store_type field, or fall back to
+ * heuristics (presence of .git sibling = repo, no parent store = workspace).
+ */
+function inferRole(storePath, configPath, hasConfig) {
+    if (hasConfig) {
+        try {
+            const raw = fs.readFileSync(configPath, 'utf-8');
+            const match = raw.match(/store_type:\s*(\S+)/);
+            if (match) {
+                const val = match[1].trim();
+                if (val === 'workspace' || val === 'repo' || val === 'service' || val === 'user') {
+                    return val;
+                }
+            }
+        }
+        catch {
+            // non-fatal — fall through to heuristics
+        }
+    }
+    // Heuristic: if a .git directory lives alongside .brainclaw/, treat as repo
+    const siblingGit = path.join(path.dirname(storePath), '.git');
+    if (fs.existsSync(siblingGit))
+        return 'repo';
+    return 'unknown';
+}
+//# sourceMappingURL=store-resolution.js.map

package/dist/core/sync-remote.js

@@ -0,0 +1,83 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { memoryDir } from './io.js';
+function runGit(args, cwd) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf-8' });
+    return {
+        ok: result.status === 0,
+        stdout: result.stdout?.trim() ?? '',
+        stderr: result.stderr?.trim() ?? '',
+    };
+}
+function hasGitRemote(remoteName, cwd) {
+    const result = runGit(['remote', 'get-url', remoteName], cwd);
+    return result.ok;
+}
+export function pullRemoteMemory(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const remote = options.remote ?? 'origin';
+    if (!hasGitRemote(remote, cwd)) {
+        return { success: false, message: `Git remote '${remote}' not found. Add it with: git remote add ${remote} <url>` };
+    }
+    const branch = runGit(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+    if (!branch.ok) {
+        return { success: false, message: 'Could not determine current branch.' };
+    }
+    const result = runGit(['pull', '--no-rebase', remote, branch.stdout], cwd);
+    if (!result.ok) {
+        return { success: false, message: `git pull failed: ${result.stderr}`, details: result.stderr };
+    }
+    return { success: true, message: `Pulled from ${remote}/${branch.stdout}`, details: result.stdout };
+}
+export function pushRemoteMemory(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const remote = options.remote ?? 'origin';
+    const memDir = memoryDir(cwd);
+    const relativeMemDir = path.relative(cwd, memDir);
+    if (!hasGitRemote(remote, cwd)) {
+        return { success: false, message: `Git remote '${remote}' not found.` };
+    }
+    const branch = runGit(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+    if (!branch.ok) {
+        return { success: false, message: 'Could not determine current branch.' };
+    }
+    // Stage only the memory directory (shared content only — machine/private-specific dirs excluded)
+    const addResult = runGit(['add', relativeMemDir], cwd);
+    if (!addResult.ok) {
+        return { success: false, message: `git add failed: ${addResult.stderr}` };
+    }
+    // Check if there's anything to commit
+    const statusResult = runGit(['diff', '--cached', '--quiet'], cwd);
+    if (statusResult.ok) {
+        return { success: true, message: 'Nothing to push — memory is already in sync with last commit.' };
+    }
+    const commitMsg = options.message ?? 'chore: sync brainclaw memory';
+    const commitResult = runGit(['commit', '-m', commitMsg], cwd);
+    if (!commitResult.ok) {
+        return { success: false, message: `git commit failed: ${commitResult.stderr}` };
+    }
+    const pushResult = runGit(['push', remote, branch.stdout], cwd);
+    if (!pushResult.ok) {
+        return { success: false, message: `git push failed: ${pushResult.stderr}`, details: pushResult.stderr };
+    }
+    return { success: true, message: `Pushed to ${remote}/${branch.stdout}`, details: pushResult.stdout };
+}
+export function diffRemoteMemory(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const remote = options.remote ?? 'origin';
+    if (!hasGitRemote(remote, cwd)) {
+        return { success: false, message: `Git remote '${remote}' not found.` };
+    }
+    // Fetch to update remote refs without merging
+    runGit(['fetch', remote], cwd);
+    const branch = runGit(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+    const diffResult = runGit(['diff', `${remote}/${branch.stdout}`, '--', memoryDir(cwd)], cwd);
+    if (!diffResult.ok) {
+        return { success: false, message: `git diff failed: ${diffResult.stderr}` };
+    }
+    if (!diffResult.stdout) {
+        return { success: true, message: 'Memory is in sync with remote — no differences.' };
+    }
+    return { success: true, message: 'Differences found with remote:', details: diffResult.stdout };
+}
+//# sourceMappingURL=sync-remote.js.map

package/dist/core/traps.js

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveCurrentHostId, sanitizeHostId } from './host.js';
+import { generateId, generateIdWithLabel } from './ids.js';
+import { resolveEntityDir } from './io.js';
+import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
+import { TrapSchema } from './schema.js';
+export function isTrapExpired(trap, nowIso = new Date().toISOString()) {
+    return trap.status === 'expired' || (!!trap.expires_at && trap.expires_at < nowIso);
+}
+export function isTrapActive(trap, nowIso = new Date().toISOString()) {
+    return trap.status === 'active' && !isTrapExpired(trap, nowIso);
+}
+function machineTrapsDir(cwd) {
+    return resolveEntityDir('traps-hosts', cwd ?? process.cwd(), 'read');
+}
+function privateTrapsDir(cwd) {
+    return resolveEntityDir('traps-private', cwd ?? process.cwd(), 'read');
+}
+function hostTrapDir(visibility, hostId, cwd) {
+    const baseDir = visibility === 'machine' ? machineTrapsDir(cwd) : privateTrapsDir(cwd);
+    return path.join(baseDir, sanitizeHostId(hostId));
+}
+function ensureHostTrapDir(visibility, hostId, cwd) {
+    const dir = hostTrapDir(visibility, hostId, cwd);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+function readTrapFiles(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const traps = [];
+    for (const file of fs.readdirSync(dir).filter((entry) => entry.endsWith('.json')).sort()) {
+        try {
+            traps.push(loadVersionedJsonFile('trap', path.join(dir, file)).document);
+        }
+        catch {
+            // Ignore malformed files.
+        }
+    }
+    return traps;
+}
+function resolveHostIds(rootDir, options) {
+    if (!fs.existsSync(rootDir))
+        return [];
+    if (options.includeAllHosts) {
+        return fs.readdirSync(rootDir)
+            .filter((entry) => fs.statSync(path.join(rootDir, entry)).isDirectory())
+            .map((entry) => sanitizeHostId(entry));
+    }
+    return [sanitizeHostId(options.hostId ?? resolveCurrentHostId())];
+}
+export function listOperationalTraps(options = {}, cwd) {
+    const visibility = options.visibility;
+    const traps = [];
+    if (!visibility || visibility === 'machine' || visibility === 'all') {
+        for (const hostId of resolveHostIds(machineTrapsDir(cwd), options)) {
+            traps.push(...readTrapFiles(hostTrapDir('machine', hostId, cwd)));
+        }
+    }
+    if (visibility === 'private' || visibility === 'all') {
+        for (const hostId of resolveHostIds(privateTrapsDir(cwd), options)) {
+            traps.push(...readTrapFiles(hostTrapDir('private', hostId, cwd)));
+        }
+    }
+    return traps.sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+export function saveOperationalTrap(trap, cwd) {
+    const visibility = trap.visibility === 'private' ? 'private' : 'machine';
+    const hostId = sanitizeHostId(trap.host_id ?? resolveCurrentHostId());
+    ensureHostTrapDir(visibility, hostId, cwd);
+    const persisted = {
+        ...trap,
+        visibility,
+        host_id: hostId,
+    };
+    saveVersionedJsonFile('trap', path.join(hostTrapDir(visibility, hostId, cwd), `${trap.id}.json`), TrapSchema.parse(persisted));
+}
+export function generateTrapId() {
+    return generateId('known_traps');
+}
+export function generateTrapIdWithLabel(cwd) {
+    return generateIdWithLabel('known_traps', cwd);
+}
+//# sourceMappingURL=traps.js.map

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "brainclaw",
+  "version": "0.19.2",
+  "description": "Shared project memory for humans and coding agents.",
+  "type": "module",
+  "bin": {
+    "brainclaw": "dist/cli.js",
+    "bclaw": "dist/cli.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc && node dist/cli.js",
+    "build:test": "tsc -p tsconfig.test.json",
+    "pack:check": "node scripts/check-pack.mjs",
+    "test": "npm run build:test && node scripts/run-tests.mjs default",
+    "test:unit": "npm run build:test && node scripts/run-tests.mjs unit",
+    "test:smoke": "npm run build:test && node scripts/run-tests.mjs smoke",
+    "test:e2e": "npm run build:test && node scripts/run-tests.mjs e2e",
+    "test:all": "npm run build:test && node scripts/run-tests.mjs all",
+    "test:coverage": "npm run build:test && c8 --all --src dist-test/src --reporter=text-summary --reporter=lcov --exclude=dist-test/tests/** --exclude=dist-test/scripts/** node scripts/run-tests.mjs default",
+    "test:coverage:check": "npm run build:test && c8 --all --check-coverage --lines 55 --functions 60 --branches 65 --statements 55 --src dist-test/src --reporter=text-summary --exclude=dist-test/tests/** --exclude=dist-test/scripts/** node scripts/run-tests.mjs default",
+    "prepublishOnly": "npm run build && npm run pack:check"
+  },
+  "keywords": [
+    "cli",
+    "memory",
+    "agents",
+    "coding-agents",
+    "project-context",
+    "handoff",
+    "local-first"
+  ],
+  "license": "BUSL-1.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jberdah/brainclaw.git"
+  },
+  "homepage": "https://github.com/jberdah/brainclaw",
+  "bugs": {
+    "url": "https://github.com/jberdah/brainclaw/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "yaml": "^2.7.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "c8": "^11.0.0",
+    "typescript": "^5.8.3"
+  }
+}