brainclaw 0.28.0 → 1.5.3

package/dist/core/duplicates.js

@@ -36,13 +36,13 @@ export function detectDuplicates(candidateText, candidateType, state, pendingCan
     }
     return matches;
 }
-function normalise(text) {
+export function normalise(text) {
     return text.toLowerCase().replace(/[^a-z0-9\s]/g, '').replace(/\s+/g, ' ').trim();
 }
 /**
  * Bigram-based similarity (Dice coefficient). Fast, no dependencies.
  */
-function similarity(a, b) {
+export function similarity(a, b) {
     if (a === b)
         return 1;
     if (a.length < 2 || b.length < 2)

package/dist/core/entity-operations.js

@@ -0,0 +1,450 @@
+/**
+ * Entity Operations — dispatch layer between the canonical CRUD verbs
+ * (bclaw_find/get/create/update/remove/transition) and the entity-specific
+ * code in src/core/*.
+ *
+ * Phase 3 slice 3b (pln_c6472192). Keeps imperative code where it lives
+ * (per P6.2) — this module only routes.
+ *
+ * MVP wiring (this landing): plan, decision, constraint, trap,
+ * runtime_note, candidate. Other entities throw
+ * `EntityOperationUnsupportedError` with a pointer at the legacy tool
+ * until later slices wire them in.
+ */
+import path from 'node:path';
+import { loadState, persistState } from './state.js';
+import { archiveCandidate, listCandidates, loadCandidate, saveCandidate, } from './candidates.js';
+import { addCrossProjectLink, removeCrossProjectLink, resolveCrossProjectLinks, } from './cross-project.js';
+import { listClaims } from './claims.js';
+import { listActionRequired } from './actions.js';
+import { listAssignments } from './assignments.js';
+import { listAgentRuns } from './agentruns.js';
+import { deleteRuntimeNote, listRuntimeNotes, saveRuntimeNote, } from './runtime.js';
+import { createConstraint, createDecision, createTrap, } from './operations/memory-write.js';
+import { deleteMemoryItem, findMemoryItemInChain, updateMemoryItem, } from './operations/memory-mutation.js';
+import { createPlan, deletePlan, updatePlan, } from './operations/plan.js';
+import { ENTITY_REGISTRY, isValidTransition, } from './entity-registry.js';
+import { generateId } from './ids.js';
+/**
+ * Default provenance stamp applied on create when the caller does not
+ * supply one. `user` kind with whatever author is in the payload; the
+ * caller can override to 'agent', 'auto_reflect', etc. at write time.
+ */
+function defaultProvenance(data) {
+    const author = typeof data.author === 'string' ? data.author : undefined;
+    if (author)
+        return { kind: 'user', author };
+    return { kind: 'user' };
+}
+/**
+ * Default read filter: exclude legacy provenance and low-confidence
+ * auto_reflect records below 0.6. Override via `includeLegacy` /
+ * `minAutoReflectConfidence` in the filter.
+ */
+const DEFAULT_MIN_AUTO_REFLECT_CONFIDENCE = 0.6;
+function passesProvenanceFilter(item, filter) {
+    const provenance = item.provenance;
+    if (!provenance)
+        return true; // pre-provenance record — never filter out.
+    if (provenance.kind === 'legacy') {
+        return filter.includeLegacy === true;
+    }
+    if (provenance.kind === 'auto_reflect') {
+        const threshold = typeof filter.minAutoReflectConfidence === 'number'
+            ? filter.minAutoReflectConfidence
+            : DEFAULT_MIN_AUTO_REFLECT_CONFIDENCE;
+        const confidence = provenance.confidence ?? 0;
+        return confidence >= threshold;
+    }
+    return true;
+}
+/** Thrown when a verb is not yet wired for a given entity. */
+export class EntityOperationUnsupportedError extends Error {
+    constructor(entity, verb, hint) {
+        super(`bclaw_${verb}(entity='${entity}') is not yet wired.` +
+            (hint ? ` ${hint}` : ' Use the legacy tool for now.'));
+        this.name = 'EntityOperationUnsupportedError';
+    }
+}
+export class EntityNotFoundError extends Error {
+    constructor(entity, id) {
+        super(`${entity} with id '${id}' not found`);
+        this.name = 'EntityNotFoundError';
+    }
+}
+export class InvalidTransitionError extends Error {
+    constructor(entity, from, to) {
+        super(`Invalid transition for ${entity}: ${from} -> ${to}`);
+        this.name = 'InvalidTransitionError';
+    }
+}
+// ─── FIND ─────────────────────────────────────────────────────────────
+export function listEntities(name, cwd, filter = {}) {
+    const all = loadAll(name, cwd);
+    const filtered = applyFilter(all, filter);
+    const paged = applyPaging(filtered, filter);
+    return { entity: name, total: filtered.length, items: paged };
+}
+function loadAll(name, cwd) {
+    switch (name) {
+        case 'plan': return loadState(cwd).plan_items;
+        case 'decision': return loadState(cwd).recent_decisions;
+        case 'constraint': return loadState(cwd).active_constraints;
+        case 'trap': return loadState(cwd).known_traps;
+        case 'handoff': return loadState(cwd).open_handoffs;
+        case 'candidate': return listCandidates(undefined, cwd);
+        case 'runtime_note': return listRuntimeNotes(undefined, cwd);
+        case 'claim': return listClaims(cwd);
+        case 'action': return listActionRequired(cwd);
+        case 'assignment': return listAssignments(cwd);
+        case 'agent_run': return listAgentRuns(cwd);
+        case 'cross_project_link': return resolveCrossProjectLinks(cwd);
+        default:
+            throw new EntityOperationUnsupportedError(name, 'find');
+    }
+}
+function applyFilter(items, filter) {
+    let result = items;
+    result = result.filter((item) => passesProvenanceFilter(item, filter));
+    if (filter.status) {
+        result = result.filter((item) => item.status === filter.status);
+    }
+    if (filter.tag) {
+        result = result.filter((item) => Array.isArray(item.tags) && item.tags.includes(filter.tag));
+    }
+    if (filter.author) {
+        result = result.filter((item) => item.author === filter.author);
+    }
+    if (filter.plan_id) {
+        result = result.filter((item) => item.plan_id === filter.plan_id);
+    }
+    if (filter.source) {
+        result = result.filter((item) => item.source === filter.source);
+    }
+    if (typeof filter.auto_generated === 'boolean') {
+        result = result.filter((item) => {
+            const source = typeof item.source === 'string' ? item.source : undefined;
+            const origin = typeof item.origin === 'string' ? item.origin : undefined;
+            const isAuto = source === 'auto' || origin?.startsWith('session-end') === true;
+            return filter.auto_generated ? isAuto : !isAuto;
+        });
+    }
+    return result;
+}
+function applyPaging(items, filter) {
+    const offset = Math.max(0, filter.offset ?? 0);
+    const limit = filter.limit ?? 50;
+    return items.slice(offset, offset + limit);
+}
+// ─── GET ───────────────────────────────────────────────────────────────
+export function getEntity(name, idOrShortLabel, cwd) {
+    if (name === 'cross_project_link') {
+        const links = resolveCrossProjectLinks(cwd);
+        const hit = links.find((l) => l.name === idOrShortLabel ||
+            l.projectName === idOrShortLabel ||
+            l.path === idOrShortLabel ||
+            l.absolutePath === idOrShortLabel ||
+            path.basename(l.absolutePath) === idOrShortLabel);
+        if (!hit)
+            throw new EntityNotFoundError(name, idOrShortLabel);
+        return hit;
+    }
+    const items = loadAll(name, cwd);
+    const hit = items.find((item) => item.id === idOrShortLabel || item.short_label === idOrShortLabel);
+    if (!hit)
+        throw new EntityNotFoundError(name, idOrShortLabel);
+    return hit;
+}
+// ─── CREATE ────────────────────────────────────────────────────────────
+export function createEntity(name, data, cwd) {
+    switch (name) {
+        case 'plan': {
+            // Explicit field whitelist + required-author check brings plan create in line
+            // with decision/constraint/trap above. Previous behaviour (`data as CreatePlanInput`)
+            // bypassed validation and allowed schema-invalid plan files on disk, which
+            // were then silently GC'd at the next state mutation. See fix plan pln_5f44426c.
+            const res = createPlan({
+                text: requireString(data, 'text'),
+                author: requireString(data, 'author'),
+                type: data.type,
+                priority: data.priority,
+                assignee: data.assignee,
+                project: data.project,
+                tags: data.tags,
+                relatedPaths: data.related_paths,
+                dependsOn: data.depends_on,
+                estimatedEffort: data.estimated_effort,
+            }, cwd);
+            stampProvenanceOnStateItem('plan', res.id, defaultProvenance(data), cwd);
+            return { entity: name, id: res.id, short_label: res.shortLabel };
+        }
+        case 'decision': {
+            const res = createDecision({
+                text: requireString(data, 'text'),
+                author: requireString(data, 'author'),
+                outcome: data.outcome,
+                tags: data.tags,
+                relatedPaths: data.related_paths,
+                planId: data.plan_id,
+            }, cwd);
+            stampProvenanceOnStateItem('decision', res.id, defaultProvenance(data), cwd);
+            return { entity: name, id: res.id, short_label: res.shortLabel };
+        }
+        case 'constraint': {
+            const res = createConstraint({
+                text: requireString(data, 'text'),
+                author: requireString(data, 'author'),
+                category: data.category,
+                tags: data.tags,
+                relatedPaths: data.related_paths,
+            }, cwd);
+            stampProvenanceOnStateItem('constraint', res.id, defaultProvenance(data), cwd);
+            return { entity: name, id: res.id, short_label: res.shortLabel };
+        }
+        case 'trap': {
+            const res = createTrap({
+                text: requireString(data, 'text'),
+                author: requireString(data, 'author'),
+                severity: (data.severity ?? 'medium'),
+                tags: data.tags,
+                relatedPaths: data.related_paths,
+            }, cwd);
+            stampProvenanceOnStateItem('trap', res.id, defaultProvenance(data), cwd);
+            return { entity: name, id: res.id, short_label: res.shortLabel };
+        }
+        case 'runtime_note': {
+            const id = generateId('runtime_note');
+            const note = {
+                id,
+                agent: requireString(data, 'agent'),
+                text: requireString(data, 'text'),
+                created_at: new Date().toISOString(),
+                tags: data.tags ?? [],
+                visibility: data.visibility ?? 'shared',
+                note_type: data.note_type ?? 'observation',
+                provenance: defaultProvenance(data),
+                ...(data.agent_id ? { agent_id: data.agent_id } : {}),
+                ...(data.project_id ? { project_id: data.project_id } : {}),
+                ...(data.session_id ? { session_id: data.session_id } : {}),
+                ...(data.plan_id ? { plan_id: data.plan_id } : {}),
+            };
+            saveRuntimeNote(note, cwd);
+            return { entity: name, id };
+        }
+        case 'candidate': {
+            const id = generateId('candidate');
+            const candidate = {
+                id,
+                type: requireString(data, 'type'),
+                text: requireString(data, 'text'),
+                created_at: new Date().toISOString(),
+                author: requireString(data, 'author'),
+                tags: data.tags ?? [],
+                status: 'pending',
+                star_count: 0,
+                starred_by: [],
+                usage_count: 0,
+                usage_events: [],
+                source: data.source,
+                origin: data.origin,
+                provenance: defaultProvenance(data),
+            };
+            saveCandidate(candidate, cwd);
+            return { entity: name, id };
+        }
+        case 'cross_project_link': {
+            const link = addCrossProjectLink({
+                path: requireString(data, 'path'),
+                name: data.name,
+                role: data.role,
+                channels: data.channels,
+                force: data.force === true,
+                cwd,
+            });
+            return { entity: name, id: link.name ?? link.path };
+        }
+        default:
+            throw new EntityOperationUnsupportedError(name, 'create');
+    }
+}
+// ─── UPDATE ────────────────────────────────────────────────────────────
+export function updateEntity(name, id, patch, cwd) {
+    const spec = ENTITY_REGISTRY[name];
+    const invalidFields = Object.keys(patch).filter((field) => !spec.updatable.includes(field));
+    if (invalidFields.length > 0) {
+        throw new Error(`Fields not updatable on ${name}: [${invalidFields.join(', ')}]. ` +
+            `Use bclaw_transition for status changes.`);
+    }
+    switch (name) {
+        case 'plan': {
+            // Pass the whole patch through the generic escape-hatch so EntityRegistry-
+            // declared updatable fields (text, tags, estimated_effort, depends_on)
+            // actually land. The typed surface still covers status/assignee/priority/
+            // actualEffort for legacy CLI callers — see UpdatePlanInput.
+            updatePlan({
+                id,
+                patch: patch,
+            }, cwd);
+            return { entity: name, id };
+        }
+        case 'decision':
+        case 'constraint':
+        case 'trap': {
+            // Same generic-patch escape-hatch for memory items. Registry declares
+            // severity, scope, related_paths, expires_at, etc. as updatable; the
+            // legacy explicit text/tags whitelist silently dropped them.
+            updateMemoryItem({
+                id,
+                type: name,
+                patch: patch,
+            }, cwd);
+            return { entity: name, id };
+        }
+        case 'runtime_note': {
+            const notes = listRuntimeNotes(undefined, cwd);
+            const note = notes.find((n) => n.id === id);
+            if (!note)
+                throw new EntityNotFoundError(name, id);
+            const patched = { ...note, ...patch };
+            saveRuntimeNote(patched, cwd);
+            return { entity: name, id };
+        }
+        case 'candidate': {
+            const candidate = loadCandidate(id, cwd);
+            const patched = { ...candidate, ...patch };
+            saveCandidate(patched, cwd);
+            return { entity: name, id };
+        }
+        case 'cross_project_link': {
+            // In-place patch: find by id (= name/path), remove, re-add with merged
+            // fields. Same path semantics as resolveCrossProjectTarget so callers can
+            // pass either the link `name` or the original `path`.
+            const current = getEntity(name, id, cwd);
+            removeCrossProjectLink(current.name ?? current.path, cwd);
+            const merged = addCrossProjectLink({
+                path: current.path,
+                name: patch.name ?? current.name,
+                role: (patch.role ?? current.role),
+                channels: patch.channels ?? current.channels,
+                cwd,
+                force: true,
+            });
+            return { entity: name, id: merged.name ?? merged.path };
+        }
+        default:
+            throw new EntityOperationUnsupportedError(name, 'update');
+    }
+}
+// ─── REMOVE ────────────────────────────────────────────────────────────
+export function removeEntity(name, id, cwd, purge = false) {
+    switch (name) {
+        case 'plan': {
+            deletePlan(id, cwd);
+            return { entity: name, id, archived: !purge, purged: purge };
+        }
+        case 'decision':
+        case 'constraint':
+        case 'trap': {
+            const found = findMemoryItemInChain(id, name, cwd);
+            if (!found)
+                throw new EntityNotFoundError(name, id);
+            deleteMemoryItem(id, name, cwd);
+            return { entity: name, id, archived: false, purged: true };
+        }
+        case 'runtime_note': {
+            const notes = listRuntimeNotes(undefined, cwd);
+            const note = notes.find((n) => n.id === id);
+            if (!note)
+                throw new EntityNotFoundError(name, id);
+            const ok = deleteRuntimeNote(note, cwd);
+            if (!ok)
+                throw new EntityNotFoundError(name, id);
+            return { entity: name, id, archived: false, purged: true };
+        }
+        case 'candidate': {
+            // Remove = archive to rejected. `purge` would delete the file; not exposed yet.
+            const candidate = loadCandidate(id, cwd);
+            archiveCandidate(candidate, 'rejected', cwd);
+            return { entity: name, id, archived: true, purged: false };
+        }
+        case 'cross_project_link': {
+            const removed = removeCrossProjectLink(id, cwd);
+            return { entity: name, id: removed.name ?? removed.path, archived: false, purged: true };
+        }
+        default:
+            throw new EntityOperationUnsupportedError(name, 'remove');
+    }
+}
+// ─── TRANSITION ───────────────────────────────────────────────────────
+export function transitionEntity(name, id, to, cwd, _reason) {
+    const spec = ENTITY_REGISTRY[name];
+    if (!spec.statusField) {
+        throw new Error(`${name} has no lifecycle (statusField is undefined)`);
+    }
+    const current = getEntity(name, id, cwd);
+    const from = current[spec.statusField];
+    if (!from) {
+        throw new Error(`${name} '${id}' has no '${spec.statusField}' field set`);
+    }
+    if (!isValidTransition(name, from, to)) {
+        throw new InvalidTransitionError(name, from, to);
+    }
+    const key = `${from}->${to}`;
+    const sideEffects = spec.sideEffects[key] ?? [];
+    switch (name) {
+        case 'plan': {
+            updatePlan({ id, status: to }, cwd);
+            return { entity: name, id, from, to, side_effects: sideEffects };
+        }
+        case 'decision':
+        case 'constraint':
+        case 'trap': {
+            const state = loadState(cwd);
+            const bucket = name === 'decision' ? state.recent_decisions
+                : name === 'constraint' ? state.active_constraints
+                    : state.known_traps;
+            const item = bucket.find((x) => x.id === id);
+            if (!item)
+                throw new EntityNotFoundError(name, id);
+            item[spec.statusField] = to;
+            persistState(state, cwd);
+            return { entity: name, id, from, to, side_effects: sideEffects };
+        }
+        case 'candidate': {
+            const candidate = loadCandidate(id, cwd);
+            if (to === 'accepted' || to === 'rejected') {
+                archiveCandidate(candidate, to, cwd);
+                return { entity: name, id, from, to, side_effects: sideEffects };
+            }
+            throw new InvalidTransitionError(name, from, to);
+        }
+        default:
+            throw new EntityOperationUnsupportedError(name, 'transition', `Lifecycle transitions for ${name} not yet wired.`);
+    }
+}
+// ─── Helpers ──────────────────────────────────────────────────────────
+/**
+ * Stamp provenance on a state-resident record (plan, decision, constraint, trap)
+ * immediately after create. Writes one extra persistState call; acceptable for
+ * v1 since create is infrequent compared to reads.
+ */
+function stampProvenanceOnStateItem(name, id, provenance, cwd) {
+    const state = loadState(cwd);
+    const bucket = name === 'plan' ? state.plan_items
+        : name === 'decision' ? state.recent_decisions
+            : name === 'constraint' ? state.active_constraints
+                : state.known_traps;
+    const item = bucket.find((x) => x.id === id);
+    if (!item)
+        return;
+    item.provenance = provenance;
+    persistState(state, cwd);
+}
+function requireString(data, field) {
+    const value = data[field];
+    if (typeof value !== 'string' || !value) {
+        throw new Error(`Missing required field: ${field}`);
+    }
+    return value;
+}
+//# sourceMappingURL=entity-operations.js.map