brainclaw 0.19.2

package/dist/core/migration.js

@@ -0,0 +1,247 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { memoryDir, memoryPath, readFileSync, writeFileAtomic, resolveEntityDir } from './io.js';
+import { AgentIdentityDocumentSchema, BootstrapProfileDocumentSchema, CandidateSchema, ClaimSchema, ConfigSchema, MemorySeedDocumentSchema, ConstraintSchema, CurrentSessionStateSchema, DecisionSchema, HandoffSchema, InstructionEntrySchema, PlanItemSchema, ProjectIdentityDocumentSchema, RuntimeNoteSchema, SessionSnapshotSchema, TrapSchema, } from './schema.js';
+export class MigrationError extends Error {
+    kind;
+    documentType;
+    constructor(kind, message, documentType) {
+        super(message);
+        this.kind = kind;
+        this.documentType = documentType;
+        this.name = 'MigrationError';
+    }
+}
+const CURRENT_SCHEMA_VERSION = 2;
+const registry = {
+    agent_identity: createRegistryEntry(AgentIdentityDocumentSchema),
+    bootstrap_profile: createRegistryEntry(BootstrapProfileDocumentSchema),
+    candidate: createRegistryEntry(CandidateSchema),
+    claim: createRegistryEntry(ClaimSchema),
+    config: createRegistryEntry(ConfigSchema),
+    constraint: createRegistryEntry(ConstraintSchema),
+    current_session: createRegistryEntry(CurrentSessionStateSchema),
+    decision: createRegistryEntry(DecisionSchema),
+    handoff: createRegistryEntry(HandoffSchema),
+    instruction: createRegistryEntry(InstructionEntrySchema),
+    memory_seed: createRegistryEntry(MemorySeedDocumentSchema),
+    plan: createRegistryEntry(PlanItemSchema),
+    project_identity: createRegistryEntry(ProjectIdentityDocumentSchema),
+    runtime_note: createRegistryEntry(RuntimeNoteSchema),
+    session_snapshot: createRegistryEntry(SessionSnapshotSchema),
+    trap: createRegistryEntry(TrapSchema),
+};
+function createRegistryEntry(schema) {
+    return {
+        currentVersion: CURRENT_SCHEMA_VERSION,
+        schema,
+        detectVersion: detectDocumentVersion,
+        migrate(raw, fromVersion, toVersion) {
+            let current = raw;
+            for (let version = fromVersion; version < toVersion; version += 1) {
+                if (version === 1) {
+                    current = addSchemaVersion(current, version + 1);
+                    continue;
+                }
+                throw new Error(`No migration path from v${version} to v${version + 1}`);
+            }
+            return current;
+        },
+    };
+}
+export function currentDocumentVersion(documentType) {
+    return registry[documentType].currentVersion;
+}
+export function detectDocumentVersion(raw) {
+    if (!isRecord(raw)) {
+        return 1;
+    }
+    if (typeof raw.schema_version === 'number' && Number.isFinite(raw.schema_version)) {
+        return raw.schema_version;
+    }
+    if (typeof raw.version === 'number' && Number.isFinite(raw.version)) {
+        return raw.version;
+    }
+    return 1;
+}
+export function migrateVersionedDocument(documentType, raw) {
+    const entry = registry[documentType];
+    const detectedVersion = entry.detectVersion(raw);
+    if (detectedVersion > entry.currentVersion) {
+        throw new MigrationError('unknown_version', `${documentType} uses unsupported schema version ${detectedVersion} (current ${entry.currentVersion})`, documentType);
+    }
+    let migratedRaw = raw;
+    if (detectedVersion < entry.currentVersion) {
+        try {
+            migratedRaw = entry.migrate(raw, detectedVersion, entry.currentVersion);
+        }
+        catch (error) {
+            throw new MigrationError('migration_failed', error instanceof Error ? error.message : String(error), documentType);
+        }
+    }
+    try {
+        return {
+            document: entry.schema.parse(migratedRaw),
+            metadata: {
+                detectedVersion,
+                currentVersion: entry.currentVersion,
+                migrated: detectedVersion < entry.currentVersion,
+            },
+        };
+    }
+    catch (error) {
+        throw new MigrationError('validation_failed', error instanceof Error ? error.message : String(error), documentType);
+    }
+}
+export function parseVersionedJsonDocumentFromString(documentType, rawText) {
+    try {
+        return migrateVersionedDocument(documentType, JSON.parse(rawText));
+    }
+    catch (error) {
+        if (error instanceof MigrationError) {
+            throw error;
+        }
+        throw new MigrationError('parse', error instanceof Error ? error.message : String(error), documentType);
+    }
+}
+export function parseVersionedYamlDocumentFromString(documentType, rawText) {
+    try {
+        return migrateVersionedDocument(documentType, YAML.parse(rawText));
+    }
+    catch (error) {
+        if (error instanceof MigrationError) {
+            throw error;
+        }
+        throw new MigrationError('parse', error instanceof Error ? error.message : String(error), documentType);
+    }
+}
+export function loadVersionedJsonFile(documentType, filepath) {
+    return parseVersionedJsonDocumentFromString(documentType, readFileSync(filepath));
+}
+export function loadVersionedYamlFile(documentType, filepath) {
+    return parseVersionedYamlDocumentFromString(documentType, readFileSync(filepath));
+}
+export function preparePersistedDocument(documentType, document) {
+    return {
+        ...(isRecord(document) ? document : {}),
+        schema_version: currentDocumentVersion(documentType),
+    };
+}
+export function saveVersionedJsonFile(documentType, filepath, document) {
+    writeFileAtomic(filepath, `${JSON.stringify(preparePersistedDocument(documentType, document), null, 2)}\n`);
+}
+export function saveVersionedYamlFile(documentType, filepath, document) {
+    const yaml = YAML.stringify(preparePersistedDocument(documentType, document), { lineWidth: 0 });
+    writeFileAtomic(filepath, yaml);
+}
+export function scanMigrationStatus(cwd) {
+    const baseDir = memoryDir(cwd);
+    if (!fs.existsSync(baseDir)) {
+        return [];
+    }
+    const entries = [];
+    collectSingle(entries, memoryPath('config.yaml', cwd), 'config', 'yaml');
+    collectSingle(entries, memoryPath('project.identity.json', cwd), 'project_identity');
+    collectSingle(entries, memoryPath('.current-session', cwd), 'current_session');
+    collectSingle(entries, memoryPath(path.join('bootstrap', 'profile.json'), cwd), 'bootstrap_profile');
+    const effectiveCwd = cwd ?? process.cwd();
+    collectDirectory(entries, resolveEntityDir('constraints', effectiveCwd, 'read'), 'constraint');
+    collectDirectory(entries, resolveEntityDir('decisions', effectiveCwd, 'read'), 'decision');
+    collectDirectory(entries, resolveEntityDir('traps', effectiveCwd, 'read'), 'trap');
+    collectDirectory(entries, resolveEntityDir('traps-hosts', effectiveCwd, 'read'), 'trap', true);
+    collectDirectory(entries, resolveEntityDir('traps-private', effectiveCwd, 'read'), 'trap', true);
+    collectDirectory(entries, resolveEntityDir('handoffs', effectiveCwd, 'read'), 'handoff');
+    collectDirectory(entries, resolveEntityDir('plans', effectiveCwd, 'read'), 'plan');
+    collectDirectory(entries, resolveEntityDir('inbox', effectiveCwd, 'read'), 'candidate');
+    collectDirectory(entries, resolveEntityDir('inbox/accepted', effectiveCwd, 'read'), 'candidate');
+    collectDirectory(entries, resolveEntityDir('inbox/rejected', effectiveCwd, 'read'), 'candidate');
+    collectDirectory(entries, resolveEntityDir('claims', effectiveCwd, 'read'), 'claim');
+    collectDirectory(entries, resolveEntityDir('runtime', effectiveCwd, 'read'), 'runtime_note', true);
+    collectDirectory(entries, resolveEntityDir('runtime-hosts', effectiveCwd, 'read'), 'runtime_note', true);
+    collectDirectory(entries, resolveEntityDir('runtime-private', effectiveCwd, 'read'), 'runtime_note', true);
+    collectDirectory(entries, resolveEntityDir('instructions', effectiveCwd, 'read'), 'instruction');
+    collectDirectory(entries, resolveEntityDir('bootstrap', effectiveCwd, 'read'), 'memory_seed');
+    collectDirectory(entries, resolveEntityDir('agents', effectiveCwd, 'read'), 'agent_identity');
+    collectDirectory(entries, resolveEntityDir('sessions', effectiveCwd, 'read'), 'session_snapshot');
+    return entries.sort((a, b) => a.path.localeCompare(b.path));
+}
+function collectSingle(entries, filepath, documentType, format = 'json') {
+    if (!fs.existsSync(filepath)) {
+        return;
+    }
+    entries.push(buildCheckEntry(filepath, documentType, format));
+}
+function collectDirectory(entries, dirPath, documentType, recursive = false) {
+    if (!fs.existsSync(dirPath)) {
+        return;
+    }
+    for (const filepath of listJsonFiles(dirPath, recursive)) {
+        entries.push(buildCheckEntry(filepath, documentType));
+    }
+}
+function listJsonFiles(dirPath, recursive) {
+    if (!fs.existsSync(dirPath)) {
+        return [];
+    }
+    const files = [];
+    for (const entry of fs.readdirSync(dirPath).sort()) {
+        const fullPath = path.join(dirPath, entry);
+        const stat = fs.statSync(fullPath);
+        if (stat.isDirectory()) {
+            if (recursive) {
+                files.push(...listJsonFiles(fullPath, true));
+            }
+            continue;
+        }
+        if (entry.endsWith('.json')) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function buildCheckEntry(filepath, documentType, format = 'json') {
+    const relativePath = path.relative(process.cwd(), filepath).replace(/\\/g, '/');
+    const currentVersion = currentDocumentVersion(documentType);
+    try {
+        const rawText = readFileSync(filepath);
+        const rawValue = format === 'yaml' ? YAML.parse(rawText) : JSON.parse(rawText);
+        const detectedVersion = detectDocumentVersion(rawValue);
+        if (detectedVersion > currentVersion) {
+            return {
+                documentType,
+                path: relativePath,
+                status: 'invalid',
+                detectedVersion,
+                currentVersion,
+                error: `unsupported schema version ${detectedVersion}`,
+            };
+        }
+        return {
+            documentType,
+            path: relativePath,
+            status: detectedVersion < currentVersion ? 'outdated' : 'ok',
+            detectedVersion,
+            currentVersion,
+        };
+    }
+    catch (error) {
+        return {
+            documentType,
+            path: relativePath,
+            status: 'invalid',
+            currentVersion,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function addSchemaVersion(raw, schemaVersion) {
+    if (!isRecord(raw)) {
+        throw new Error('document is not an object');
+    }
+    return { ...raw, schema_version: schemaVersion };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=migration.js.map

package/dist/core/project-registry.js

@@ -0,0 +1,64 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { loadConfig } from './config.js';
+import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
+import { nowISO } from './ids.js';
+import { MEMORY_DIR, memoryPath } from './io.js';
+import { ProjectIdentityDocumentSchema } from './schema.js';
+const PROJECT_IDENTITY_FILE = 'project.identity.json';
+export function generateProjectId() {
+    return `prj_${crypto.randomUUID().replace(/-/g, '')}`;
+}
+export function loadProjectIdentity(cwd, preferredDirName) {
+    const filepath = memoryPath(PROJECT_IDENTITY_FILE, cwd, preferredDirName);
+    return loadVersionedJsonFile('project_identity', filepath).document;
+}
+export function saveProjectIdentity(identity, cwd, preferredDirName) {
+    const filepath = memoryPath(PROJECT_IDENTITY_FILE, cwd, preferredDirName);
+    saveVersionedJsonFile('project_identity', filepath, ProjectIdentityDocumentSchema.parse(identity));
+}
+export function projectIdentityExists(cwd, preferredDirName) {
+    return fs.existsSync(memoryPath(PROJECT_IDENTITY_FILE, cwd, preferredDirName));
+}
+export function resolveExistingProjectIdentity(cwd) {
+    for (const dirName of [MEMORY_DIR]) {
+        try {
+            return loadProjectIdentity(cwd, dirName);
+        }
+        catch {
+            // Ignore missing or malformed identity docs and keep searching.
+        }
+    }
+    for (const dirName of [MEMORY_DIR]) {
+        try {
+            const config = loadConfig(cwd, dirName);
+            if (config.project_id) {
+                return {
+                    schema_version: 2,
+                    version: 1,
+                    project_id: config.project_id,
+                    project_name: config.project_name,
+                    created_at: nowISO(),
+                    storage_dir: config.storage_dir,
+                    topology: config.topology,
+                };
+            }
+        }
+        catch {
+            // Ignore missing or malformed config and keep searching.
+        }
+    }
+    return undefined;
+}
+export function buildProjectIdentity(input) {
+    return {
+        schema_version: 2,
+        version: 1,
+        project_id: input.existing?.project_id ?? generateProjectId(),
+        project_name: input.projectName,
+        created_at: input.existing?.created_at ?? nowISO(),
+        storage_dir: input.storageDir,
+        topology: input.topology,
+    };
+}
+//# sourceMappingURL=project-registry.js.map

package/dist/core/reflection-safety.js

@@ -0,0 +1,21 @@
+import { loadState } from './state.js';
+import { detectNewItemContradictions, hasBlockingContradictions, summarizeContradictions } from './contradictions.js';
+export function evaluateReflectionSafety(input) {
+    if (input.type === 'handoff') {
+        return {};
+    }
+    const contradictions = detectNewItemContradictions(input.text, input.tags, input.relatedPaths, loadState(input.cwd), input.projectId);
+    if (contradictions.length === 0) {
+        return {};
+    }
+    const contradictionSummary = summarizeContradictions(contradictions);
+    const promotionBlockedReason = input.automation && hasBlockingContradictions(contradictions)
+        ? 'contradiction_detected'
+        : undefined;
+    return {
+        contradictions_detected: contradictions,
+        contradiction_summary: contradictionSummary,
+        promotion_blocked_reason: promotionBlockedReason,
+    };
+}
+//# sourceMappingURL=reflection-safety.js.map

package/dist/core/repo-analysis.js

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { MEMORY_DIR } from './io.js';
+const MULTI_PROJECT_MARKERS = [
+    'pnpm-workspace.yaml',
+    'turbo.json',
+    'nx.json',
+    'lerna.json',
+    'rush.json',
+];
+const MULTI_PROJECT_DIRS = ['apps', 'packages', 'services'];
+export function analyzeRepository(cwd) {
+    const reasons = [];
+    for (const marker of MULTI_PROJECT_MARKERS) {
+        if (fs.existsSync(path.join(cwd, marker))) {
+            reasons.push(`Found workspace marker: ${marker}`);
+        }
+    }
+    const matchedDirs = MULTI_PROJECT_DIRS.filter((dirName) => {
+        const dirPath = path.join(cwd, dirName);
+        return fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory();
+    });
+    if (matchedDirs.length > 0) {
+        reasons.push(`Found top-level project folders: ${matchedDirs.join(', ')}`);
+    }
+    const packageJsonPath = path.join(cwd, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+        try {
+            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+            if (packageJson.workspaces) {
+                reasons.push('Found workspace configuration in package.json');
+            }
+        }
+        catch {
+            // Ignore package.json parse errors during advisory analysis.
+        }
+    }
+    if (reasons.length > 0) {
+        return {
+            recommendedMode: 'multi-project',
+            reasons,
+        };
+    }
+    return {
+        recommendedMode: 'single-project',
+        reasons: ['No monorepo or multi-project markers detected'],
+    };
+}
+/** Markers whose presence indicates a service/project boundary worth initialising. */
+const SERVICE_MARKERS = [
+    'package.json',
+    'Dockerfile',
+    'docker-compose.yml',
+    'docker-compose.yaml',
+    'go.mod',
+    'requirements.txt',
+    'pyproject.toml',
+    'Cargo.toml',
+    'pom.xml',
+    'build.gradle',
+    'build.gradle.kts',
+];
+/** Directories to skip when scanning for service boundaries. */
+const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'dist-test',
+    'build',
+    '.brainclaw',
+    '__pycache__',
+    '.venv',
+    'venv',
+    'target',
+    'vendor',
+    '.next',
+    '.nuxt',
+    'coverage',
+]);
+/**
+ * Walk up to `maxDepth` levels below `rootDir`, find subdirectories that
+ * contain service markers but no `.brainclaw/` yet.
+ *
+ * `rootDir` itself is excluded (the caller is presumably about to `init` it).
+ */
+export function scanWorkspaceBoundaries(rootDir, maxDepth = 3) {
+    const suggestions = [];
+    const alreadyInitialised = [];
+    function walk(dir, depth) {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (SKIP_DIRS.has(entry.name))
+                continue;
+            if (entry.name.startsWith('.') && entry.name !== '.brainclaw')
+                continue;
+            const childDir = path.join(dir, entry.name);
+            const childEntries = (() => {
+                try {
+                    return fs.readdirSync(childDir).map((n) => n);
+                }
+                catch {
+                    return [];
+                }
+            })();
+            const hasMemory = childEntries.includes(MEMORY_DIR);
+            const foundMarkers = SERVICE_MARKERS.filter((m) => childEntries.includes(m));
+            const relPath = path.relative(rootDir, childDir);
+            if (hasMemory) {
+                alreadyInitialised.push({ dir: childDir, relativePath: relPath });
+            }
+            else if (foundMarkers.length > 0) {
+                suggestions.push({ dir: childDir, relativePath: relPath, markers: foundMarkers });
+            }
+            // Only recurse into dirs that didn't already match a boundary
+            if (!hasMemory && foundMarkers.length === 0) {
+                walk(childDir, depth + 1);
+            }
+        }
+    }
+    walk(rootDir, 1);
+    return { suggestions, alreadyInitialised };
+}
+//# sourceMappingURL=repo-analysis.js.map