brainclaw 0.28.0 → 1.5.3

package/dist/commands/repair.js

@@ -0,0 +1,210 @@
+/**
+ * `brainclaw repair` — safe, non-destructive repair flow built on doctor's
+ * structured repair candidates (pln#397 stp_b31fbe23 + stp_7ad66f68).
+ *
+ * Design:
+ *   1. Run the doctor JSON output and capture `repair_candidates[]`.
+ *   2. Split into `safe` and `unsafe`.
+ *   3. Execute safe candidates by default; unsafe stay deferred unless the
+ *      caller passes `includeUnsafe`.
+ *
+ * Preservation guarantees (stp_7ad66f68):
+ *   - NO action in this module deletes files. Lossy-looking actions
+ *     (quarantine, archive) always rename into a clearly-labelled parking
+ *     directory so operators can recover. Enforced by a source-level
+ *     invariant test in tests/unit/repair-preservation.test.ts.
+ *   - Before executing any unsafe candidate, a highlighted warning prints
+ *     exactly what will be moved and where it will land — operators get
+ *     full visibility before data relocates.
+ *   - Memory entities (plans, decisions, constraints, traps, claims,
+ *     handoffs) are never touched by any current action. Only inbox
+ *     hygiene and filesystem-shape candidates are wired.
+ *
+ * Exposed via CLI (`brainclaw repair`) and MCP (`bclaw_repair`). Always
+ * returns a structured summary so agents can inspect what changed.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { memoryExists, memoryDir } from '../core/io.js';
+import { runDoctor } from './doctor.js';
+/**
+ * Execute a single repair candidate. Returns the outcome; never throws.
+ * Safe actions are pure creation / rename operations — see the switch cases.
+ */
+function executeCandidate(candidate, cwd) {
+    try {
+        switch (candidate.action) {
+            case 'mkdir': {
+                const target = path.resolve(cwd, candidate.target);
+                if (!fs.existsSync(target)) {
+                    fs.mkdirSync(target, { recursive: true });
+                }
+                return { action: candidate.action, target: candidate.target, status: 'applied' };
+            }
+            case 'move_inbox_message': {
+                // Orphaned messages stored under the wrong agent directory. Read the
+                // message, resolve the correct destination from message.to, and
+                // rename. Source file already exists; target dir is auto-created.
+                const sourceAbs = path.resolve(cwd, candidate.target);
+                if (!fs.existsSync(sourceAbs)) {
+                    return { action: candidate.action, target: candidate.target, status: 'skipped', reason: 'source file no longer exists' };
+                }
+                const parsed = JSON.parse(fs.readFileSync(sourceAbs, 'utf-8'));
+                const recipient = parsed.document?.to ?? parsed.to;
+                if (!recipient) {
+                    return { action: candidate.action, target: candidate.target, status: 'skipped', reason: 'message has no recipient (to) field' };
+                }
+                const normalizedAgent = recipient.toLowerCase().replace(/[^a-z0-9_-]/g, '_');
+                const inboxRoot = path.join(memoryDir(cwd), 'coordination', 'inbox', normalizedAgent);
+                if (!fs.existsSync(inboxRoot)) {
+                    fs.mkdirSync(inboxRoot, { recursive: true });
+                }
+                const destAbs = path.join(inboxRoot, path.basename(sourceAbs));
+                if (fs.existsSync(destAbs) && path.resolve(destAbs) !== path.resolve(sourceAbs)) {
+                    return { action: candidate.action, target: candidate.target, status: 'skipped', reason: `destination already exists: ${destAbs}` };
+                }
+                fs.renameSync(sourceAbs, destAbs);
+                return { action: candidate.action, target: candidate.target, status: 'applied' };
+            }
+            case 'quarantine_inbox_message': {
+                // Unsafe: move malformed message to a quarantine directory so a human
+                // can inspect it. Never deletes. Requires includeUnsafe.
+                const sourceAbs = path.resolve(cwd, candidate.target);
+                if (!fs.existsSync(sourceAbs)) {
+                    return { action: candidate.action, target: candidate.target, status: 'skipped', reason: 'source file no longer exists' };
+                }
+                const quarantineDir = path.join(memoryDir(cwd), 'coordination', 'inbox', '.quarantine');
+                if (!fs.existsSync(quarantineDir)) {
+                    fs.mkdirSync(quarantineDir, { recursive: true });
+                }
+                const destAbs = path.join(quarantineDir, `${Date.now()}-${path.basename(sourceAbs)}`);
+                fs.renameSync(sourceAbs, destAbs);
+                return { action: candidate.action, target: candidate.target, status: 'applied' };
+            }
+            default:
+                return {
+                    action: candidate.action,
+                    target: candidate.target,
+                    status: 'skipped',
+                    reason: `unknown action: ${candidate.action}`,
+                };
+        }
+    }
+    catch (err) {
+        return {
+            action: candidate.action,
+            target: candidate.target,
+            status: 'failed',
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Collect repair candidates by running doctor with JSON output captured.
+ * We re-run doctor instead of accepting them via an argument so the caller
+ * always sees the current state of the store.
+ */
+function collectCandidates(cwd) {
+    const originalLog = console.log;
+    let captured = '';
+    console.log = (...args) => { captured += args.map(String).join(' '); };
+    try {
+        runDoctor({ cwd, json: true });
+    }
+    finally {
+        console.log = originalLog;
+    }
+    try {
+        const parsed = JSON.parse(captured);
+        return Array.isArray(parsed.repair_candidates) ? parsed.repair_candidates : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function runRepair(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    const candidates = collectCandidates(cwd);
+    const safe = candidates.filter((c) => c.safe);
+    const unsafe = candidates.filter((c) => !c.safe);
+    const applied = [];
+    const skipped = [];
+    const failed = [];
+    const toRun = [...safe, ...(options.includeUnsafe ? unsafe : [])];
+    const deferred = options.includeUnsafe ? [] : unsafe;
+    // pln#397 stp_7ad66f68: explicit warning banner whenever we're about to
+    // touch existing files. Operators see exactly what moves and where
+    // before any rename executes. No JSON noise.
+    if (!options.json && !options.dryRun && options.includeUnsafe && unsafe.length > 0) {
+        console.warn('');
+        console.warn('⚠ Preservation notice — the following unsafe actions will RELOCATE files (never delete):');
+        for (const candidate of unsafe) {
+            console.warn(`  • ${candidate.action} → ${candidate.target}`);
+            console.warn(`    ${candidate.description}`);
+        }
+        console.warn('Files are moved to labelled parking directories (e.g. inbox/.quarantine/) so you can recover them manually.');
+        console.warn('');
+    }
+    for (const candidate of toRun) {
+        if (options.dryRun) {
+            skipped.push({
+                action: candidate.action,
+                target: candidate.target,
+                status: 'skipped',
+                reason: 'dry-run',
+            });
+            continue;
+        }
+        const outcome = executeCandidate(candidate, cwd);
+        if (outcome.status === 'applied')
+            applied.push(outcome);
+        else if (outcome.status === 'failed')
+            failed.push(outcome);
+        else
+            skipped.push(outcome);
+    }
+    for (const candidate of deferred) {
+        skipped.push({
+            action: candidate.action,
+            target: candidate.target,
+            status: 'skipped',
+            reason: 'unsafe — pass --include-unsafe to execute (preserves data, but requires confirmation)',
+        });
+    }
+    const result = {
+        ok: failed.length === 0,
+        dry_run: Boolean(options.dryRun),
+        candidates_total: candidates.length,
+        candidates_safe: safe.length,
+        candidates_unsafe: unsafe.length,
+        applied,
+        skipped,
+        failed,
+    };
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return result;
+    }
+    if (candidates.length === 0) {
+        console.log('Nothing to repair — doctor surfaced no candidates.');
+        return result;
+    }
+    if (options.dryRun) {
+        console.log(`Dry-run: ${candidates.length} candidate(s) (${safe.length} safe, ${unsafe.length} unsafe)`);
+    }
+    else {
+        console.log(`Repair complete: ${applied.length} applied, ${skipped.length} skipped, ${failed.length} failed`);
+    }
+    for (const o of applied)
+        console.log(`  ✔ ${o.action} → ${o.target}`);
+    for (const o of skipped)
+        console.log(`  ○ ${o.action} → ${o.target}${o.reason ? ` (${o.reason})` : ''}`);
+    for (const o of failed)
+        console.log(`  ✗ ${o.action} → ${o.target}${o.reason ? ` (${o.reason})` : ''}`);
+    return result;
+}
+//# sourceMappingURL=repair.js.map

package/dist/commands/run-profile.js

@@ -0,0 +1,57 @@
+/**
+ * CLI command: brainclaw run <profile-name>
+ *
+ * Loads an agent profile, resolves the invoke template, and spawns the agent.
+ *
+ * @module
+ */
+import { execSync } from 'node:child_process';
+import { loadProfile, listProfiles } from '../core/agent-profiles.js';
+import { getDefaultInvokeTemplate } from '../core/agent-capability.js';
+import { requireInitialized } from '../core/guards.js';
+export function runRunProfile(profileName, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    requireInitialized(cwd);
+    // List mode: no profile name
+    if (!profileName) {
+        const profiles = listProfiles(cwd);
+        if (profiles.length === 0) {
+            console.log('No agent profiles found. Add .yaml files to .brainclaw/agents/profiles/');
+            return;
+        }
+        console.log('Available profiles:');
+        for (const p of profiles) {
+            console.log(`  ${p.name}  — ${p.description} [${p.trigger}]`);
+        }
+        return;
+    }
+    const profile = loadProfile(profileName, cwd);
+    // Resolve invoke template: --agent override replaces the profile's invoke
+    let invoke = profile.invoke;
+    if (options.agent) {
+        const template = getDefaultInvokeTemplate(options.agent);
+        if (template) {
+            invoke = template.command;
+        }
+        else {
+            console.error(`Unknown agent: ${options.agent}. Using profile invoke template.`);
+        }
+    }
+    // Replace {prompt} placeholder with the profile prompt
+    const command = invoke.replace(/\{prompt\}/g, profile.prompt.replace(/"/g, '\\"'));
+    if (options.dry) {
+        console.log(`[dry-run] Profile: ${profile.name}`);
+        console.log(`[dry-run] Command: ${command}`);
+        return;
+    }
+    console.log(`Running profile: ${profile.name}`);
+    console.log(`Command: ${command}`);
+    try {
+        execSync(command, { cwd, stdio: 'inherit' });
+    }
+    catch (err) {
+        const code = err.status ?? 1;
+        process.exit(code);
+    }
+}
+//# sourceMappingURL=run-profile.js.map

package/dist/commands/sequence.js

@@ -0,0 +1,113 @@
+import { resolveCurrentAgentName } from '../core/agent-registry.js';
+import { requireInitialized } from '../core/guards.js';
+import { validateCliInput } from '../core/input-validation.js';
+import { createSequence, listSequences, loadSequence, updateSequence } from '../core/sequence.js';
+const KNOWN_SUBCOMMANDS = new Set(['create', 'list', 'ls', 'show', 'update']);
+function parseItems(raw) {
+    if (!raw)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Invalid --items JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('Invalid --items JSON: expected an array');
+    }
+    return parsed;
+}
+export function runSequenceResource(subcommand, args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    requireInitialized(cwd);
+    const normalized = subcommand.trim().toLowerCase();
+    if (!KNOWN_SUBCOMMANDS.has(normalized)) {
+        console.error(`Error: unknown sequence subcommand "${subcommand}".`);
+        console.error('  Available: create, list, show, update');
+        process.exit(1);
+    }
+    if (normalized === 'create') {
+        const name = args.join(' ').trim();
+        if (!name) {
+            console.error('Error: sequence create requires <name>');
+            process.exit(1);
+        }
+        validateCliInput(name, options.tag);
+        const items = parseItems(options.items);
+        const result = createSequence({
+            name,
+            description: options.description,
+            status: options.status,
+            owner: options.owner,
+            items,
+            author: options.author ?? resolveCurrentAgentName(cwd),
+            tags: options.tag,
+        }, cwd);
+        console.log(`✔ Sequence added: [${result.id}] ${name}`);
+        return;
+    }
+    if (normalized === 'list' || normalized === 'ls') {
+        const sequences = listSequences(cwd).filter((sequence) => !options.status || sequence.status === options.status);
+        if (options.json) {
+            console.log(JSON.stringify(sequences, null, 2));
+            return;
+        }
+        if (sequences.length === 0) {
+            console.log('No sequences found.');
+            return;
+        }
+        console.log(`${sequences.length} sequence(s):`);
+        for (const sequence of sequences) {
+            console.log(`[${sequence.id}] ${sequence.name} (${sequence.status}, items=${sequence.items.length})`);
+        }
+        return;
+    }
+    if (normalized === 'show') {
+        const id = args[0];
+        if (!id) {
+            console.error('Error: sequence show requires <id>.');
+            process.exit(1);
+        }
+        const sequence = loadSequence(id, cwd);
+        if (options.json) {
+            console.log(JSON.stringify(sequence, null, 2));
+            return;
+        }
+        console.log(`Sequence: ${sequence.id}`);
+        console.log(`  Name:        ${sequence.name}`);
+        console.log(`  Status:      ${sequence.status}`);
+        if (sequence.owner)
+            console.log(`  Owner:       ${sequence.owner}`);
+        if (sequence.description)
+            console.log(`  Description: ${sequence.description}`);
+        console.log(`  Updated:     ${sequence.updated_at}`);
+        if (sequence.items.length > 0) {
+            console.log('  Items:');
+            for (const item of sequence.items) {
+                const lane = item.lane ? ` lane=${item.lane}` : '';
+                const hardAfter = item.hard_after.length ? ` hard_after=${item.hard_after.join(',')}` : '';
+                const softAfter = item.soft_after.length ? ` soft_after=${item.soft_after.join(',')}` : '';
+                console.log(`    #${item.rank} ${item.planId}${lane}${hardAfter}${softAfter}`);
+            }
+        }
+        return;
+    }
+    const id = args[0];
+    if (!id) {
+        console.error('Error: sequence update requires <id>.');
+        process.exit(1);
+    }
+    const items = options.items ? parseItems(options.items) : undefined;
+    const sequence = updateSequence({
+        id,
+        name: options.name,
+        description: options.description,
+        status: options.status,
+        owner: options.owner,
+        items,
+        tags: options.tag,
+    }, cwd);
+    console.log(`✔ Sequence updated: [${sequence.id}] ${sequence.name}`);
+}
+//# sourceMappingURL=sequence.js.map