@poa-box/agent 0.1.0

package/dist/commands/brain/list.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * pop brain list — enumerate all known brain docs with their current head CIDs.
+ *
+ * Thin wrapper over listBrainDocs() which reads the manifest file directly
+ * (no Helia process required). Useful for:
+ *
+ *   - Discovering what docs an agent has locally without knowing the ID
+ *   - Sanity-checking that a subscribe session actually merged a remote head
+ *   - Feeding `pop brain read --doc <id>` for any doc returned here
+ *
+ * Implementation intentionally avoids spinning up a Helia node — listing
+ * is a pure manifest read.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listHandler = void 0;
+const brain_1 = require("../../lib/brain");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+exports.listHandler = {
+    builder: (yargs) => yargs,
+    handler: async (_argv) => {
+        try {
+            const docs = (0, brain_1.listBrainDocs)();
+            if (output.isJsonMode()) {
+                output.json({ count: docs.length, docs });
+                return;
+            }
+            console.log('');
+            if (docs.length === 0) {
+                console.log('  No brain docs found in local manifest.');
+                console.log('  (Write one via applyBrainChange or sync via `pop brain subscribe`.)');
+                console.log('');
+                return;
+            }
+            console.log(`  Brain docs (${docs.length}):`);
+            console.log('  ' + '─'.repeat(60));
+            for (const { docId, headCid } of docs) {
+                console.log(`  ${docId}`);
+                console.log(`    head: ${headCid}`);
+            }
+            console.log('');
+            console.log('  Inspect any doc: pop brain read --doc <docId>');
+            console.log('');
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+    },
+};

package/dist/commands/brain/migrate-projects.d.ts

@@ -0,0 +1,44 @@
+/**
+ * pop brain migrate-projects — one-shot import of a hand-written
+ * projects.md file into a brain projects doc. Same shape as
+ * `pop brain migrate` (#296) but for pop.brain.projects instead of
+ * pop.brain.shared. Parses the "Active Projects" H2 section only.
+ *
+ * Usage:
+ *   pop brain migrate-projects \
+ *     --from agent/brain/Knowledge/projects.md \
+ *     --doc pop.brain.projects.test \
+ *     --dry-run
+ *
+ * Dry-run reports parse results without persisting. Without --dry-run,
+ * refuses to write if the target doc already has content unless --force.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface MigrateProjectsArgs {
+    from: string;
+    doc: string;
+    force?: boolean;
+    dryRun?: boolean;
+    author?: string;
+    currentHb?: number;
+    noBanner?: boolean;
+}
+export declare const migrateProjectsHandler: {
+    builder: (yargs: Argv) => Argv<{
+        from: string;
+    } & {
+        doc: string;
+    } & {
+        force: boolean;
+    } & {
+        "dry-run": boolean;
+    } & {
+        "current-hb": number;
+    } & {
+        author: string;
+    } & {
+        "no-banner": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<MigrateProjectsArgs>) => Promise<void>;
+};
+export {};

package/dist/commands/brain/migrate-projects.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * pop brain migrate-projects — one-shot import of a hand-written
+ * projects.md file into a brain projects doc. Same shape as
+ * `pop brain migrate` (#296) but for pop.brain.projects instead of
+ * pop.brain.shared. Parses the "Active Projects" H2 section only.
+ *
+ * Usage:
+ *   pop brain migrate-projects \
+ *     --from agent/brain/Knowledge/projects.md \
+ *     --doc pop.brain.projects.test \
+ *     --dry-run
+ *
+ * Dry-run reports parse results without persisting. Without --dry-run,
+ * refuses to write if the target doc already has content unless --force.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrateProjectsHandler = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const brain_1 = require("../../lib/brain");
+const brain_migrate_projects_1 = require("../../lib/brain-migrate-projects");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+const DEPRECATED_BANNER = (docId, headCid) => `<!-- DEPRECATED: migrated to ${docId} at CID ${headCid} -->
+<!-- Source of truth is now agent/brain/Knowledge/${docId}.generated.md -->
+<!-- regenerated by \`pop brain snapshot --doc ${docId}\` at end of every heartbeat. -->
+<!-- Edit via \`pop brain\` CLI; hand-edits here will NOT propagate. -->
+
+`;
+exports.migrateProjectsHandler = {
+    builder: (yargs) => yargs
+        .option('from', {
+        describe: 'Path to the hand-written projects.md to migrate',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('doc', {
+        describe: 'Target brain document ID (typically pop.brain.projects)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('force', {
+        describe: 'Re-migrate even if the target doc already has live projects',
+        type: 'boolean',
+        default: false,
+    })
+        .option('dry-run', {
+        describe: 'Parse and print the structured output without persisting',
+        type: 'boolean',
+        default: false,
+    })
+        .option('current-hb', {
+        describe: 'Current heartbeat number for HB#→timestamp estimation (default 285)',
+        type: 'number',
+        default: 285,
+    })
+        .option('author', {
+        describe: 'Default author for projects without explicit attribution',
+        type: 'string',
+        default: 'migration',
+    })
+        .option('no-banner', {
+        describe: 'Do NOT write a DEPRECATED banner to the source file after migration',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: async (argv) => {
+        const srcPath = (0, path_1.resolve)(argv.from);
+        const docId = argv.doc;
+        try {
+            if (!(0, fs_1.existsSync)(srcPath)) {
+                output.error(`Source file not found: ${srcPath}`);
+                process.exitCode = 1;
+                return;
+            }
+            const raw = (0, fs_1.readFileSync)(srcPath, 'utf8');
+            const now = Math.floor(Date.now() / 1000);
+            const currentHB = argv.currentHb ?? 285;
+            const ctx = {
+                defaultAuthor: argv.author ?? 'migration',
+                defaultTimestamp: now,
+                timestampForHB: (hb) => now - (currentHB - hb) * 15 * 60,
+            };
+            const parsed = (0, brain_migrate_projects_1.parseProjectsMarkdown)(raw, ctx);
+            const projects = parsed.projects ?? [];
+            if (argv.dryRun) {
+                if (output.isJsonMode()) {
+                    output.json({ status: 'dry-run', docId, parsed });
+                }
+                else {
+                    console.log('');
+                    console.log(`  Dry-run migration: ${srcPath}`);
+                    console.log(`  Target doc:        ${docId}`);
+                    console.log('  ' + '─'.repeat(60));
+                    console.log(`  Projects parsed:   ${projects.length}`);
+                    console.log('');
+                    const stageCounts = {};
+                    for (const p of projects) {
+                        stageCounts[p.stage] = (stageCounts[p.stage] ?? 0) + 1;
+                    }
+                    console.log('  Stage counts:');
+                    for (const [stage, n] of Object.entries(stageCounts)) {
+                        console.log(`    ${stage}: ${n}`);
+                    }
+                    console.log('');
+                    console.log('  First 5 projects:');
+                    for (const p of projects.slice(0, 5)) {
+                        console.log(`    - ${p.id}  ${p.name.slice(0, 60)}  [${p.stage}]`);
+                    }
+                    console.log('');
+                    console.log('  No changes persisted (--dry-run).');
+                    console.log('');
+                }
+                return;
+            }
+            // Refuse to overwrite an existing doc unless --force. Count only
+            // LIVE projects (not tombstoned) when deciding "has content".
+            const existing = await (0, brain_1.openBrainDoc)(docId);
+            const existingLiveCount = Array.isArray(existing.doc?.projects)
+                ? existing.doc.projects.filter((p) => p?.removed !== true).length
+                : 0;
+            if (existingLiveCount > 0 && !argv.force) {
+                output.error(`Target doc "${docId}" already has ${existingLiveCount} live project(s) at head ${existing.headCid}. ` +
+                    'Re-run with --force to re-migrate (will merge via Automerge).');
+                process.exitCode = 1;
+                return;
+            }
+            const result = await (0, brain_1.applyBrainChange)(docId, (doc) => {
+                if (!Array.isArray(doc.projects))
+                    doc.projects = [];
+                if (argv.force) {
+                    // Force re-migration: clear existing and re-seed.
+                    doc.projects.splice(0, doc.projects.length);
+                }
+                for (const p of projects)
+                    doc.projects.push({ ...p });
+            });
+            if (!argv.noBanner) {
+                const banner = DEPRECATED_BANNER(docId, result.headCid);
+                if (!raw.includes('DEPRECATED: migrated to')) {
+                    (0, fs_1.writeFileSync)(srcPath, banner + raw);
+                }
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId,
+                    headCid: result.headCid,
+                    projectsMigrated: projects.length,
+                    sourceFile: srcPath,
+                    bannerWritten: !argv.noBanner,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Migration complete: ${srcPath} → ${docId}`);
+                console.log(`  New head CID: ${result.headCid}`);
+                console.log(`  Projects:     ${projects.length}`);
+                if (!argv.noBanner) {
+                    console.log(`  Banner written to source file.`);
+                }
+                console.log('');
+                console.log(`  Run \`pop brain read --doc ${docId}\` to inspect.`);
+                console.log(`  Run \`pop brain snapshot --doc ${docId}\` to produce the .generated.md.`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

package/dist/commands/brain/migrate.d.ts

@@ -0,0 +1,74 @@
+/**
+ * pop brain migrate — one-shot import of a hand-written brain knowledge
+ * file into a CRDT Automerge doc. Step 8 of the brain plan.
+ *
+ * Usage:
+ *   pop brain migrate --from agent/brain/Knowledge/shared.md \
+ *                     --doc pop.brain.shared
+ *
+ * Flow:
+ *   1. Read the markdown file from disk.
+ *   2. parseSharedMarkdown → SharedBrainDoc (rules + lessons).
+ *   3. --dry-run: print the parsed structure and exit.
+ *   4. Otherwise: check that the target doc is empty (or --force),
+ *      then apply the parsed content via applyBrainChange. This
+ *      auto-signs + auto-publishes via the step 5 gossipsub layer
+ *      so any live subscriber picks up the migration immediately.
+ *   5. Write a DEPRECATED banner to the top of the source file
+ *      pointing agents at <docId>.generated.md as the new source
+ *      of truth. Original content is preserved below the banner
+ *      for historical reference — the banner is opt-in.
+ *
+ * Idempotence: running the command twice on a doc that already has
+ * content errors out unless --force is supplied. This protects
+ * against accidental clobbering during a fumbled migration.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface MigrateArgs {
+    from: string;
+    doc: string;
+    force?: boolean;
+    merge?: boolean;
+    dryRun?: boolean;
+    currentHb?: number;
+    author?: string;
+    noBanner?: boolean;
+}
+/**
+ * Pure helper: compute which parsed entries should be appended to an
+ * existing list vs skipped because an entry with the same `id` already
+ * exists. Extracted so the --merge dedup logic is unit-testable
+ * independent of the brain daemon / Automerge doc layer.
+ *
+ * Entries without an `id` are ALWAYS added (we can't dedup what has no
+ * key). Callers should ensure parsed entries have ids if they want
+ * dedup semantics — parseSharedMarkdown always assigns an id via
+ * slugify fallback, so in practice every parsed lesson has an id.
+ */
+export declare function computeMergeDelta<T extends {
+    id?: string;
+}>(existing: readonly T[], parsed: readonly T[]): {
+    toAdd: T[];
+    skippedCount: number;
+};
+export declare const migrateHandler: {
+    builder: (yargs: Argv) => Argv<{
+        from: string;
+    } & {
+        doc: string;
+    } & {
+        force: boolean;
+    } & {
+        merge: boolean;
+    } & {
+        "dry-run": boolean;
+    } & {
+        "current-hb": number;
+    } & {
+        author: string;
+    } & {
+        "no-banner": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<MigrateArgs>) => Promise<void>;
+};
+export {};