brainclaw 0.19.2

package/dist/commands/enable-agent.js

@@ -0,0 +1,63 @@
+import { registerAgentIdentity, setCurrentAgentIdentity } from '../core/agent-registry.js';
+import { loadConfig, saveConfig } from '../core/config.js';
+import { describeAutoConfigWrite, writeDetectedAgentAutoConfig } from '../core/agent-files.js';
+import { isAgentIntegrationName, upsertAgentIntegrationDeclaration } from '../core/agent-integrations.js';
+import { memoryExists } from '../core/io.js';
+import { writeAgentExportForAgent } from './export.js';
+import { writeDetectedAgentHooks } from './hooks.js';
+export function runEnableAgent(agentName, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    if (!isAgentIntegrationName(agentName)) {
+        console.error(`Error: unsupported agent '${agentName}'. Use \`brainclaw register-agent\` for identity-only registration.`);
+        process.exit(1);
+    }
+    const agent = registerAgentIdentity({
+        agentName,
+        kind: options.kind ?? 'agent',
+        capabilities: options.capability,
+        replaceCapabilities: options.replaceCapabilities,
+        generateFingerprint: options.generateFingerprint,
+        cwd,
+    });
+    if (options.setCurrent) {
+        setCurrentAgentIdentity(agent, cwd);
+    }
+    const config = loadConfig(cwd);
+    upsertAgentIntegrationDeclaration(config, agentName, 'manual');
+    saveConfig(config, cwd);
+    const exportResult = writeAgentExportForAgent(agentName, cwd);
+    // Windsurf uses .windsurfrules for both native rules and session hooks.
+    // Avoid clobbering the exported rules file during activation.
+    const hookResults = agentName === 'windsurf'
+        ? []
+        : writeDetectedAgentHooks(agentName, config.project_name, cwd)
+            .filter((hook) => hook.relativePath !== exportResult?.relativePath);
+    const autoConfigResults = writeDetectedAgentAutoConfig(agentName, cwd);
+    const messages = autoConfigResults.map(describeAutoConfigWrite).filter((message) => Boolean(message));
+    if (options.json) {
+        console.log(JSON.stringify({
+            agent,
+            current: options.setCurrent ?? false,
+            declaration_added: true,
+            export: exportResult,
+            hooks: hookResults,
+            auto_config: autoConfigResults,
+        }, null, 2));
+        return;
+    }
+    console.log(`✔ Agent enabled: ${agent.agent_name} (${agent.agent_id})${options.setCurrent ? ' [current]' : ''}`);
+    if (exportResult) {
+        console.log(`✔ Agent instructions written to ${exportResult.relativePath} (${exportResult.created ? 'created' : 'updated'})`);
+    }
+    for (const hook of hookResults) {
+        console.log(`✔ Session hook written to ${hook.relativePath} (${hook.created ? 'created' : 'updated'})`);
+    }
+    for (const message of messages) {
+        console.log(message);
+    }
+}
+//# sourceMappingURL=enable-agent.js.map

package/dist/commands/env.js

@@ -0,0 +1,46 @@
+import { memoryExists } from '../core/io.js';
+import { loadConfig } from '../core/config.js';
+import { assessAgentIntegrationReadiness } from '../core/agent-integrations.js';
+import { assessBrainclawVersion } from '../core/brainclaw-version.js';
+import { buildExecutionContext, compactExecutionContext, renderExecutionContextSummary } from '../core/execution-context.js';
+import { buildAgentToolingContext, renderAgentToolingSummary } from '../core/agent-context.js';
+export function runEnv(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    const executionContext = buildExecutionContext({ cwd });
+    const config = loadConfig(cwd);
+    const integrationReadiness = assessAgentIntegrationReadiness(config, cwd);
+    const brainclawVersion = assessBrainclawVersion(config);
+    const agentTooling = options.agentTooling ? buildAgentToolingContext({ cwd }) : undefined;
+    if (options.json) {
+        console.log(JSON.stringify({
+            execution_context: executionContext,
+            brainclaw_version: brainclawVersion,
+            declared_agent_integrations: config.agent_integrations,
+            integration_readiness: integrationReadiness,
+            ...(agentTooling ? { agent_tooling: agentTooling } : {}),
+        }, null, 2));
+        return;
+    }
+    console.log(renderExecutionContextSummary(compactExecutionContext(executionContext), false));
+    console.log(`Brainclaw CLI: ${brainclawVersion.cli_version}`);
+    if (brainclawVersion.status !== 'ok') {
+        console.log(brainclawVersion.message);
+        if (brainclawVersion.upgrade_message) {
+            console.log(`Upgrade benefits: ${brainclawVersion.upgrade_message}`);
+        }
+    }
+    console.log(`Declared agent integrations: ${config.agent_integrations.declarations.length}`);
+    const missingDeclarations = integrationReadiness.filter((entry) => !entry.ready);
+    if (missingDeclarations.length > 0) {
+        console.log(`Integrations missing activation: ${missingDeclarations.length}`);
+    }
+    if (agentTooling) {
+        console.log('');
+        console.log(renderAgentToolingSummary(agentTooling));
+    }
+}
+//# sourceMappingURL=env.js.map

package/dist/commands/estimation-report.js

@@ -0,0 +1,167 @@
+import { loadState } from '../core/state.js';
+import { memoryExists } from '../core/io.js';
+/** Parse legacy actual_effort strings ("30min", "2h", "1h30m", "1d", "45m") → minutes.
+ *  Still needed for actual_effort which remains a free string. */
+export function parseEffortMinutes(effort) {
+    const s = effort.trim().toLowerCase();
+    let total = 0;
+    let matched = false;
+    const days = s.match(/(\d+(?:\.\d+)?)\s*d/);
+    if (days) {
+        total += parseFloat(days[1]) * 8 * 60;
+        matched = true;
+    }
+    const hours = s.match(/(\d+(?:\.\d+)?)\s*h/);
+    if (hours) {
+        total += parseFloat(hours[1]) * 60;
+        matched = true;
+    }
+    const mins = s.match(/(\d+(?:\.\d+)?)\s*m(?:in)?/);
+    if (mins) {
+        total += parseFloat(mins[1]);
+        matched = true;
+    }
+    if (!matched) {
+        const bare = parseFloat(s);
+        if (!isNaN(bare))
+            return bare;
+        return undefined;
+    }
+    return total > 0 ? total : undefined;
+}
+function median(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+function mean(values) {
+    return values.reduce((a, b) => a + b, 0) / values.length;
+}
+export function buildCalibrationHint(medianRatio) {
+    if (medianRatio < 0.5)
+        return `You tend to underestimate by ~${(1 / medianRatio).toFixed(1)}x — pad estimates up`;
+    if (medianRatio < 0.8)
+        return `You slightly underestimate — add ~${Math.round((1 - medianRatio) * 100)}% to estimates`;
+    if (medianRatio <= 1.25)
+        return 'Estimates are well-calibrated';
+    if (medianRatio <= 2.0)
+        return `You tend to overestimate by ~${medianRatio.toFixed(1)}x — cut estimates by ~${Math.round((1 - 1 / medianRatio) * 100)}%`;
+    return `You significantly overestimate by ~${medianRatio.toFixed(1)}x — estimates should be ~${medianRatio.toFixed(1)}x smaller`;
+}
+/** Render a ratio bar (40 chars wide, 1.0x at the midpoint). */
+export function renderRatioBar(ratio, width = 40) {
+    const pivot = Math.floor(width / 2); // position of 1.0x
+    const filled = Math.min(Math.round(ratio * pivot), width);
+    const bar = Array.from({ length: width }, (_, i) => {
+        if (i < filled)
+            return '█';
+        if (i === pivot && filled < pivot)
+            return '│';
+        return '░';
+    }).join('');
+    return bar;
+}
+export function buildEstimationReport(options = {}) {
+    const state = loadState(options.cwd);
+    const done = state.plan_items.filter((p) => p.status === 'done' && (!options.agent || p.author === options.agent));
+    const entries = done.map((p) => {
+        const entry = {
+            id: p.id,
+            text: p.text,
+            author: p.author,
+            estimated_minutes: p.estimated_effort, // already a number after schema coercion
+            actual_effort: p.actual_effort,
+            completed_at: p.completed_at,
+        };
+        // Compute elapsed from wall-clock timestamps
+        const endTime = p.completed_at ?? p.updated_at;
+        const startTime = p.started_at ?? p.created_at;
+        if (endTime && startTime) {
+            const elapsed = (new Date(endTime).getTime() - new Date(startTime).getTime()) / 60000;
+            if (elapsed > 0)
+                entry.elapsed_minutes = Math.round(elapsed);
+        }
+        // Resolve actual minutes: explicit actual_effort string > elapsed wall-clock
+        const actualMinutes = p.actual_effort
+            ? parseEffortMinutes(p.actual_effort)
+            : entry.elapsed_minutes;
+        if (actualMinutes !== undefined)
+            entry.elapsed_minutes = Math.round(actualMinutes);
+        if (entry.estimated_minutes !== undefined && actualMinutes !== undefined && actualMinutes > 0) {
+            entry.ratio = parseFloat((entry.estimated_minutes / actualMinutes).toFixed(2));
+        }
+        return entry;
+    });
+    const withBoth = entries.filter((e) => e.ratio !== undefined);
+    const ratios = withBoth.map((e) => e.ratio);
+    const medianRatio = ratios.length > 0 ? parseFloat(median(ratios).toFixed(2)) : undefined;
+    const meanRatio = ratios.length > 0 ? parseFloat(mean(ratios).toFixed(2)) : undefined;
+    return {
+        entries,
+        summary: {
+            total: entries.length,
+            with_estimate: entries.filter((e) => e.estimated_minutes !== undefined).length,
+            with_both: withBoth.length,
+            median_ratio: medianRatio,
+            mean_ratio: meanRatio,
+            calibration_hint: medianRatio !== undefined ? buildCalibrationHint(medianRatio) : undefined,
+        },
+    };
+}
+export function runEstimationReport(options = {}) {
+    if (!memoryExists(options.cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    const report = buildEstimationReport(options);
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    const { summary, entries } = report;
+    if (summary.total === 0) {
+        console.log('No completed plans found.');
+        return;
+    }
+    console.log(`\nEstimation Report — ${summary.total} completed plan(s)`);
+    console.log(`With estimates: ${summary.with_estimate} · With both: ${summary.with_both}`);
+    if (summary.median_ratio !== undefined) {
+        console.log(`\nMedian ratio (estimated÷actual): ${summary.median_ratio}x · Mean: ${summary.mean_ratio}x`);
+        console.log(`→ ${summary.calibration_hint}`);
+    }
+    // Chart — only plans with ratio data
+    const chartable = entries.filter((e) => e.ratio !== undefined);
+    if (chartable.length > 0) {
+        console.log('\n— Accuracy chart (ratio = estimated ÷ actual) —');
+        console.log('  < 1.0 = went over estimate   │   > 1.0 = finished early\n');
+        // Header scale
+        const W = 40;
+        const pivot = W / 2;
+        const scaleTop = '  ' + '0.0x' + ' '.repeat(pivot - 4) + '1.0x' + ' '.repeat(W - pivot - 4) + '2.0x+';
+        const scaleLine = '  ├' + '─'.repeat(pivot - 1) + '┼' + '─'.repeat(W - pivot - 1) + '┤';
+        console.log(scaleTop);
+        console.log(scaleLine);
+        for (const e of chartable) {
+            const label = (e.text.length > 35 ? e.text.slice(0, 32) + '…' : e.text).padEnd(35);
+            const bar = renderRatioBar(e.ratio);
+            const pct = e.ratio >= 1
+                ? ` EARLY -${Math.round((1 - 1 / e.ratio) * 100)}%`
+                : ` OVER  +${Math.round((1 / e.ratio - 1) * 100)}%`;
+            const est = e.estimated_minutes !== undefined ? `${e.estimated_minutes}min` : '?';
+            const act = e.elapsed_minutes !== undefined ? `${e.elapsed_minutes}min` : '?';
+            console.log(`  ${label} ${bar} ${e.ratio}x  ${est}→${act}${pct}`);
+        }
+        console.log('');
+    }
+    // Detail table for plans with estimate but no actual
+    const estimateOnly = entries.filter((e) => e.estimated_minutes !== undefined && e.ratio === undefined);
+    if (estimateOnly.length > 0) {
+        console.log('— Estimated but no elapsed time —');
+        for (const e of estimateOnly) {
+            const short = e.text.length > 60 ? e.text.slice(0, 57) + '…' : e.text;
+            console.log(`  [${e.id.slice(-8)}] ${short} — est:${e.estimated_minutes}min`);
+        }
+        console.log('');
+    }
+}
+//# sourceMappingURL=estimation-report.js.map

package/dist/commands/explore.js

@@ -0,0 +1,47 @@
+import { loadState } from '../core/state.js';
+import { memoryExists } from '../core/io.js';
+export function runExplore(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    const state = loadState(cwd);
+    const capabilities = state.recent_decisions.filter((d) => d.tags.includes('capability'));
+    const tools = state.recent_decisions.filter((d) => d.tags.includes('tool'));
+    console.log('\n╔════════════════════════════════════════════════════════╗');
+    console.log('║          Project Capabilities & Tools                   ║');
+    console.log('╚════════════════════════════════════════════════════════╝\n');
+    console.log(`📦 Capabilities (${capabilities.length}):\n`);
+    if (capabilities.length === 0) {
+        console.log('   No capabilities registered yet.\n');
+    }
+    else {
+        capabilities.forEach((cap) => {
+            const category = cap.tags.find((t) => t !== 'capability') || 'general';
+            console.log(`   [${cap.id}] ${cap.text.split('\n')[0]}`);
+            console.log(`       Category: ${category}\n`);
+        });
+    }
+    console.log(`🔧 Tools (${tools.length}):\n`);
+    if (tools.length === 0) {
+        console.log('   No tools registered yet.\n');
+    }
+    else {
+        tools.forEach((tool) => {
+            const type = tool.tags.find((t) => t !== 'tool') || 'utility';
+            console.log(`   [${tool.id}] ${tool.text.split('\n')[0]}`);
+            console.log(`       Type: ${type}\n`);
+        });
+    }
+    if (capabilities.length === 0 && tools.length === 0) {
+        console.log('💡 Tip: Register your first capability or tool with:');
+        console.log('   brainclaw capability add <name> <description>');
+        console.log('   brainclaw tool add <name> <description>\n');
+    }
+    else {
+        console.log('💡 Tip: Use `brainclaw capability describe <id>` or `brainclaw tool describe <id>` for details');
+        console.log('   Use `brainclaw tool search <query>` to find tools\n');
+    }
+}
+//# sourceMappingURL=explore.js.map