brainclaw 0.19.2

package/dist/commands/export.js

@@ -0,0 +1,381 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { memoryExists } from '../core/io.js';
+import { loadState } from '../core/state.js';
+import { loadConfig, saveConfig } from '../core/config.js';
+import { isAgentIntegrationName, upsertAgentIntegrationDeclaration } from '../core/agent-integrations.js';
+import { resolveInstructions, loadInstructions } from '../core/instructions.js';
+import { detectAiAgent } from '../core/ai-agent-detection.js';
+import { resolveExportTarget, resolveExportTargetByFormat, writeExportFile, buildHygieneSection, describeAutoConfigWrite, writeExportCompanionFiles, collectExportGitignoreEntries, ensureGitignoreEntries, } from '../core/agent-files.js';
+import { logger } from '../core/logger.js';
+export function runExport(options) {
+    const cwd = options.cwd ?? process.cwd();
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    if (options.detect) {
+        if (options.shared) {
+            console.error('Error: --shared cannot be used with --detect. Use `brainclaw export --format <format> --write --shared` to publish a specific instruction file.');
+            process.exit(1);
+        }
+        runExportDetect(cwd, options);
+        return;
+    }
+    if (!options.format) {
+        console.error('Error: --format or --detect is required.');
+        process.exit(1);
+    }
+    const content = generateExport(options.format, options, cwd);
+    if (options.write) {
+        const target = resolveExportTargetByFormat(options.format);
+        const result = writeExportFile(content, target.relativePath, cwd);
+        const autoConfigs = writeExportCompanionFiles(options.format, cwd);
+        const gitignoreEntries = collectExportGitignoreEntries(cwd, target.relativePath, autoConfigs, {
+            includeTarget: !options.shared,
+        });
+        if (gitignoreEntries.length > 0) {
+            ensureGitignoreEntries(cwd, gitignoreEntries);
+        }
+        declareAgentIntegrationFromTarget(cwd, target.agentName, 'manual');
+        console.log(`✔ Written to ${target.relativePath} (${result.created ? 'created' : 'updated'})`);
+        if (options.shared) {
+            console.log(`✔ Left ${target.relativePath} versionable (--shared); local companion config remains gitignored`);
+        }
+        else if (gitignoreEntries.length > 0) {
+            console.log('✔ Added generated local agent files to .gitignore');
+        }
+        for (const autoConfig of autoConfigs) {
+            const message = describeAutoConfigWrite(autoConfig);
+            if (message) {
+                console.log(message);
+            }
+        }
+    }
+    else if (options.output) {
+        const dir = path.dirname(options.output);
+        if (dir && !fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(options.output, content, 'utf-8');
+        console.log(`✔ Exported to ${options.output}`);
+    }
+    else {
+        console.log(content);
+    }
+}
+function runExportDetect(cwd, options) {
+    const detected = detectAiAgent();
+    const target = detected ? resolveExportTarget(detected.name) : resolveExportTarget('unknown');
+    const content = generateExport(target.format, options, cwd);
+    const result = writeExportFile(content, target.relativePath, cwd);
+    const autoConfigs = writeExportCompanionFiles(target.format, cwd);
+    const gitignoreEntries = collectExportGitignoreEntries(cwd, target.relativePath, autoConfigs);
+    if (gitignoreEntries.length > 0) {
+        ensureGitignoreEntries(cwd, gitignoreEntries);
+    }
+    declareAgentIntegrationFromTarget(cwd, target.agentName, detected ? 'detected' : 'manual');
+    const source = detected ? `${detected.name} [${detected.detection_source}]` : 'fallback (no agent detected)';
+    console.log(`✔ Detected: ${source}`);
+    console.log(`✔ Written to ${target.relativePath} (${result.created ? 'created' : 'updated'})`);
+    if (gitignoreEntries.length > 0) {
+        console.log('✔ Added generated local agent files to .gitignore');
+    }
+    for (const autoConfig of autoConfigs) {
+        const message = describeAutoConfigWrite(autoConfig);
+        if (message) {
+            console.log(message);
+        }
+    }
+}
+export function writeAgentExportForAgent(agentName, cwd) {
+    const rendered = renderAgentExportForAgent(agentName, cwd);
+    if (!rendered) {
+        return undefined;
+    }
+    const result = writeExportFile(rendered.content, rendered.relativePath, cwd);
+    declareAgentIntegrationFromTarget(cwd, rendered.agentName, 'manual');
+    return { relativePath: rendered.relativePath, created: result.created, updated: result.updated };
+}
+export function renderAgentExportForAgent(agentName, cwd) {
+    const target = resolveExportTarget(agentName);
+    if (target.agentName === 'unknown') {
+        return undefined;
+    }
+    const content = generateExport(target.format, {}, cwd);
+    return { agentName: target.agentName, relativePath: target.relativePath, content };
+}
+export function writeDetectedAgentExport(detectedAgentName, cwd) {
+    const rendered = renderAgentExportForAgent(detectedAgentName, cwd);
+    if (!rendered) {
+        return undefined;
+    }
+    // Skip if this is the fallback and AGENTS.md is already handled by ensureAgentFiles
+    if (rendered.relativePath === 'AGENTS.md' || rendered.relativePath === '.github/copilot-instructions.md') {
+        return undefined;
+    }
+    const result = writeExportFile(rendered.content, rendered.relativePath, cwd);
+    return { relativePath: rendered.relativePath, created: result.created };
+}
+function declareAgentIntegrationFromTarget(cwd, agentName, declarationSource) {
+    if (!isAgentIntegrationName(agentName)) {
+        return;
+    }
+    const config = loadConfig(cwd);
+    if (upsertAgentIntegrationDeclaration(config, agentName, declarationSource)) {
+        saveConfig(config, cwd);
+    }
+}
+function generateExport(format, options, cwd) {
+    switch (format) {
+        case 'copilot-instructions': return generateCopilotInstructions(options, cwd);
+        case 'cursor-rules': return generateCursorRules(options, cwd);
+        case 'agents-md': return generateAgentsMd(options, cwd);
+        case 'claude-md': return generateClaudeMd(options, cwd);
+        case 'windsurf': return generateWindsurf(options, cwd);
+        case 'cline': return generateCline(options, cwd);
+        case 'roo': return generateRoo(options, cwd);
+        case 'continue': return generateContinueRules(options, cwd);
+        case 'gemini-md': return generateGeminiMd(options, cwd);
+        default:
+            throw new Error(`Unknown export format: ${format}`);
+    }
+}
+function getInstructionText(options, cwd) {
+    try {
+        const all = loadInstructions(cwd);
+        const resolved = resolveInstructions(all, {
+            project: options.project,
+            agent: options.agent,
+        });
+        return resolved.filter(i => i.active).map(i => i.text);
+    }
+    catch (err) {
+        logger.debug('Failed to resolve instructions for export:', err);
+        return [];
+    }
+}
+function getConstraintsSummary(cwd) {
+    try {
+        const state = loadState(cwd);
+        const active = state.active_constraints.filter(c => c.status === 'active');
+        if (active.length === 0)
+            return '';
+        return '## Active Constraints\n\n' + active.map(c => `- ${c.text}`).join('\n');
+    }
+    catch (err) {
+        logger.debug('Failed to load constraints for export:', err);
+        return '';
+    }
+}
+function getDecisionsSummary(cwd) {
+    try {
+        const state = loadState(cwd);
+        if (state.recent_decisions.length === 0)
+            return '';
+        return '## Key Decisions\n\n' + state.recent_decisions.slice(-10).map(d => `- ${d.text}`).join('\n');
+    }
+    catch {
+        return '';
+    }
+}
+function getTrapsSummary(cwd) {
+    try {
+        const state = loadState(cwd);
+        const traps = state.known_traps.filter(t => t.visibility === 'shared');
+        if (traps.length === 0)
+            return '';
+        return '## Known Traps\n\n' + traps.map(t => `- [${t.severity}] ${t.text}`).join('\n');
+    }
+    catch {
+        return '';
+    }
+}
+// buildHygieneSection is imported from ../core/agent-files.js
+function generateCopilotInstructions(options, cwd) {
+    const config = loadConfig(cwd);
+    const lines = [
+        `# Copilot Instructions — ${config.project_name}`,
+        '',
+        '> Generated by brainclaw. Do not edit manually — run `brainclaw export --format copilot-instructions --write` to regenerate.',
+        '',
+    ];
+    const instructions = getInstructionText(options, cwd);
+    if (instructions.length > 0) {
+        lines.push('## Instructions\n');
+        for (const inst of instructions)
+            lines.push(`- ${inst}`);
+        lines.push('');
+    }
+    const constraints = getConstraintsSummary(cwd);
+    if (constraints) {
+        lines.push(constraints);
+        lines.push('');
+    }
+    const decisions = getDecisionsSummary(cwd);
+    if (decisions) {
+        lines.push(decisions);
+        lines.push('');
+    }
+    const traps = getTrapsSummary(cwd);
+    if (traps) {
+        lines.push(traps);
+        lines.push('');
+    }
+    lines.push(buildHygieneSection());
+    return lines.join('\n');
+}
+function generateCursorRules(options, cwd) {
+    const instructions = getInstructionText(options, cwd);
+    const state = loadState(cwd);
+    const lines = ['# Cursor rules — generated by brainclaw', ''];
+    if (instructions.length > 0) {
+        lines.push('## Instructions');
+        for (const inst of instructions)
+            lines.push(`- ${inst}`);
+        lines.push('');
+    }
+    const constraints = state.active_constraints.filter(c => c.status === 'active');
+    if (constraints.length > 0) {
+        lines.push('## Constraints');
+        for (const c of constraints)
+            lines.push(`- ${c.text}`);
+        lines.push('');
+    }
+    lines.push(buildHygieneSection());
+    return lines.join('\n');
+}
+function generateAgentsMd(options, cwd) {
+    const config = loadConfig(cwd);
+    const instructions = getInstructionText(options, cwd);
+    const state = loadState(cwd);
+    const lines = [
+        `# AGENTS.md — ${config.project_name}`,
+        '',
+        '> Generated by brainclaw.',
+        '',
+        '## Project Instructions',
+        '',
+    ];
+    if (instructions.length > 0) {
+        for (const inst of instructions)
+            lines.push(`- ${inst}`);
+    }
+    else {
+        lines.push('_No project instructions defined._');
+    }
+    lines.push('');
+    const activePlans = state.plan_items.filter(p => p.status === 'todo' || p.status === 'in_progress');
+    if (activePlans.length > 0) {
+        lines.push('## Active Plan Items\n');
+        for (const p of activePlans.slice(0, 10)) {
+            lines.push(`- [${p.status}] ${p.text}${p.assignee ? ` (@${p.assignee})` : ''}`);
+        }
+        lines.push('');
+    }
+    const traps = state.known_traps.filter(t => t.visibility === 'shared');
+    if (traps.length > 0) {
+        lines.push('## Known Traps\n');
+        for (const t of traps.slice(0, 10)) {
+            lines.push(`- [${t.severity}] ${t.text}`);
+        }
+        lines.push('');
+    }
+    lines.push(buildHygieneSection());
+    return lines.join('\n');
+}
+function generateClaudeMd(options, cwd) {
+    const config = loadConfig(cwd);
+    const instructions = getInstructionText(options, cwd);
+    const state = loadState(cwd);
+    const lines = [
+        `# ${config.project_name}`,
+        '',
+        '> This file is generated by brainclaw. Run `brainclaw export --format claude-md --write` to regenerate.',
+        '',
+    ];
+    if (instructions.length > 0) {
+        lines.push('## Project Instructions\n');
+        for (const inst of instructions)
+            lines.push(`- ${inst}`);
+        lines.push('');
+    }
+    const constraints = state.active_constraints.filter(c => c.status === 'active');
+    if (constraints.length > 0) {
+        lines.push('## Active Constraints\n');
+        for (const c of constraints)
+            lines.push(`- ${c.text}`);
+        lines.push('');
+    }
+    const traps = state.known_traps.filter(t => t.visibility === 'shared');
+    if (traps.length > 0) {
+        lines.push('## Known Traps\n');
+        for (const t of traps)
+            lines.push(`- [${t.severity}] ${t.text}`);
+        lines.push('');
+    }
+    lines.push(buildHygieneSection());
+    return lines.join('\n');
+}
+function generateWindsurf(options, cwd) {
+    const instructions = getInstructionText(options, cwd);
+    const state = loadState(cwd);
+    const lines = ['# Windsurf rules — generated by brainclaw', ''];
+    if (instructions.length > 0) {
+        lines.push('## Instructions');
+        for (const inst of instructions)
+            lines.push(`- ${inst}`);
+        lines.push('');
+    }
+    const constraints = state.active_constraints.filter(c => c.status === 'active');
+    if (constraints.length > 0) {
+        lines.push('## Constraints');
+        for (const c of constraints)
+            lines.push(`- ${c.text}`);
+        lines.push('');
+    }
+    lines.push(buildHygieneSection());
+    return lines.join('\n');
+}
+function generateCline(options, cwd) {
+    return generateWindsurf(options, cwd).replace('Windsurf rules', 'Cline rules');
+}
+function generateRoo(options, cwd) {
+    return generateWindsurf(options, cwd).replace('Windsurf rules', 'Roo rules');
+}
+function generateContinueRules(options, cwd) {
+    return generateWindsurf(options, cwd).replace('Windsurf rules', 'Continue rules');
+}
+function generateGeminiMd(options, cwd) {
+    const config = loadConfig(cwd);
+    const instructions = getInstructionText(options, cwd);
+    const state = loadState(cwd);
+    const lines = [
+        `# ${config.project_name}`,
+        '',
+        '> Generated by brainclaw. Run `brainclaw export --format gemini-md --write` to regenerate.',
+        '',
+    ];
+    if (instructions.length > 0) {
+        lines.push('## Project Instructions\n');
+        for (const inst of instructions)
+            lines.push(`- ${inst}`);
+        lines.push('');
+    }
+    const constraints = state.active_constraints.filter(c => c.status === 'active');
+    if (constraints.length > 0) {
+        lines.push('## Active Constraints\n');
+        for (const c of constraints)
+            lines.push(`- ${c.text}`);
+        lines.push('');
+    }
+    const traps = state.known_traps.filter(t => t.visibility === 'shared');
+    if (traps.length > 0) {
+        lines.push('## Known Traps\n');
+        for (const t of traps)
+            lines.push(`- [${t.severity}] ${t.text}`);
+        lines.push('');
+    }
+    lines.push(buildHygieneSection());
+    return lines.join('\n');
+}
+//# sourceMappingURL=export.js.map

package/dist/commands/handoff.js

@@ -0,0 +1,63 @@
+import { execSync } from 'node:child_process';
+import { loadState, saveState } from '../core/state.js';
+import { resolveCurrentAgentName } from '../core/agent-registry.js';
+import { loadConfig } from '../core/config.js';
+import { generateMarkdown } from '../core/markdown.js';
+import { generateIdWithLabel, nowISO } from '../core/ids.js';
+import { scanText } from '../core/security.js';
+import { memoryExists, memoryPath, writeFileAtomic } from '../core/io.js';
+import { validateCliInput } from '../core/input-validation.js';
+import { resolveTargetStore } from '../core/store-resolution.js';
+export function runHandoff(text, options) {
+    const cwd = resolveTargetStore(options.cwd ?? process.cwd(), options.store ?? 'local');
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    validateCliInput(text, options.tag);
+    const config = loadConfig(cwd);
+    const warnings = scanText(text, config);
+    for (const w of warnings) {
+        console.warn(`⚠ ${w.message}`);
+        if (w.level === 'block') {
+            console.error('Blocked: strict redaction is enabled. Entry not added.');
+            process.exit(1);
+        }
+    }
+    const state = loadState(cwd);
+    const plan = options.plan ? state.plan_items.find((item) => item.id === options.plan) : undefined;
+    if (options.plan && !plan) {
+        console.error(`Error: Plan item '${options.plan}' not found.`);
+        process.exit(1);
+    }
+    const { id, short_label } = generateIdWithLabel('open_handoffs');
+    let diff;
+    if (options.captureDiff) {
+        try {
+            diff = execSync('git diff HEAD', { encoding: 'utf-8' });
+        }
+        catch {
+            diff = "Could not capture git diff.";
+        }
+    }
+    const entry = {
+        id,
+        short_label,
+        from: options.from,
+        to: options.to,
+        text,
+        created_at: nowISO(),
+        author: options.author ?? resolveCurrentAgentName(cwd),
+        status: 'open',
+        project: options.project ?? plan?.project,
+        plan_id: options.plan,
+        tags: options.tag ?? [],
+        related_paths: options.path,
+        snapshot: diff ? { diff } : undefined,
+    };
+    state.open_handoffs.push(entry);
+    saveState(state, cwd);
+    writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(state, cwd));
+    console.log(`✔ Handoff added: [${id}] ${options.from} → ${options.to}: ${text}`);
+}
+//# sourceMappingURL=handoff.js.map

package/dist/commands/history.js

@@ -0,0 +1,22 @@
+import { readAuditLog } from '../core/audit.js';
+import { memoryExists } from '../core/io.js';
+export function runHistory(id) {
+    if (!memoryExists()) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    const entries = readAuditLog({ itemId: id });
+    if (entries.length === 0) {
+        console.log(`No history found for item '${id}'.`);
+        return;
+    }
+    console.log(`History for ${id} — ${entries.length} event(s):`);
+    console.log('');
+    for (const entry of entries) {
+        const parts = [`  ${entry.timestamp}`, `[${entry.actor}]`, entry.action];
+        if (entry.reason)
+            parts.push(`| ${entry.reason}`);
+        console.log(parts.join(' '));
+    }
+}
+//# sourceMappingURL=history.js.map

package/dist/commands/hooks.js

@@ -0,0 +1,123 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { memoryExists } from '../core/io.js';
+import { loadConfig } from '../core/config.js';
+import { BRAINCLAW_SECTION_START, BRAINCLAW_SECTION_END, upsertBrainclawSection } from '../core/agent-files.js';
+/**
+ * Generate the Cursor MDC hook file content.
+ * Uses MDC frontmatter with `alwaysApply: true` so Cursor injects it
+ * deterministically into every agent conversation.
+ */
+export function generateCursorHook(projectName) {
+    return `---
+description: brainclaw session bootstrap for ${projectName}
+alwaysApply: true
+---
+
+# Brainclaw session bootstrap
+
+**At the start of every session, before doing anything else:**
+
+\`\`\`bash
+brainclaw context
+\`\`\`
+
+This loads the shared project memory: active constraints, recent decisions, known traps,
+open plan items, active claims, and the last handoff.
+
+**Before finishing any session:**
+
+\`\`\`bash
+brainclaw claim release <id>               # release claims you opened
+brainclaw plan update <id> --status done   # close plan items you completed
+# or in one shot:
+brainclaw session-end --auto-release
+\`\`\`
+`;
+}
+/**
+ * Generate the Windsurf session-trigger section.
+ * Windsurf reads .windsurfrules on every Cascade activation — a clearly
+ * delimited "SESSION START" block acts as a deterministic trigger.
+ */
+export function generateWindsurfHook(projectName) {
+    return `# Brainclaw session trigger — ${projectName}
+# This block is always active. Windsurf Cascade reads .windsurfrules on every activation.
+
+## SESSION START (always run first)
+
+Before responding to any request, execute:
+
+\`\`\`bash
+brainclaw context
+\`\`\`
+
+This gives you: active constraints, recent decisions, known traps, open plans, active claims,
+and the last handoff note. Do not skip this step.
+
+## SESSION END (before finishing)
+
+\`\`\`bash
+brainclaw claim release <id>               # for each claim you hold
+brainclaw plan update <id> --status done   # for each plan item you completed
+# or:
+brainclaw session-end --auto-release
+\`\`\`
+`;
+}
+export function writeHook(content, relativePath, cwd) {
+    const fullPath = path.join(cwd, relativePath);
+    const dir = path.dirname(fullPath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    const existed = fs.existsSync(fullPath);
+    if (relativePath.endsWith('.mdc')) {
+        // MDC files: write as-is (frontmatter must be preserved verbatim)
+        fs.writeFileSync(fullPath, content, 'utf-8');
+    }
+    else {
+        // Plain markdown rules files: use brainclaw sentinel markers
+        const section = `${BRAINCLAW_SECTION_START}\n${content}\n${BRAINCLAW_SECTION_END}`;
+        const existing = existed ? fs.readFileSync(fullPath, 'utf-8') : '';
+        fs.writeFileSync(fullPath, upsertBrainclawSection(existing, section), 'utf-8');
+    }
+    return { target: path.basename(relativePath, path.extname(relativePath)), relativePath, created: !existed };
+}
+export function runHooks(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    const config = loadConfig(cwd);
+    const target = options.target ?? 'all';
+    const results = [];
+    if (target === 'cursor' || target === 'all') {
+        const content = generateCursorHook(config.project_name);
+        results.push(writeHook(content, '.cursor/rules/brainclaw-session.mdc', cwd));
+    }
+    if (target === 'windsurf' || target === 'all') {
+        const content = generateWindsurfHook(config.project_name);
+        results.push(writeHook(content, '.windsurfrules', cwd));
+    }
+    for (const r of results) {
+        console.log(`✔ Hook written to ${r.relativePath} (${r.created ? 'created' : 'updated'})`);
+    }
+}
+/**
+ * Called from `brainclaw init` when an agent is detected.
+ * Writes hooks relevant to the detected agent, silently on success.
+ */
+export function writeDetectedAgentHooks(agentName, projectName, cwd) {
+    const results = [];
+    if (agentName === 'cursor') {
+        const content = generateCursorHook(projectName);
+        results.push(writeHook(content, '.cursor/rules/brainclaw-session.mdc', cwd));
+    }
+    if (agentName === 'windsurf') {
+        const content = generateWindsurfHook(projectName);
+        results.push(writeHook(content, '.windsurfrules', cwd));
+    }
+    return results;
+}
+//# sourceMappingURL=hooks.js.map