@poa-box/agent 0.1.0

package/dist/commands/brain/migrate.js

@@ -0,0 +1,306 @@
+"use strict";
+/**
+ * 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.
+ */
+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.migrateHandler = void 0;
+exports.computeMergeDelta = computeMergeDelta;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const brain_1 = require("../../lib/brain");
+const brain_migrate_1 = require("../../lib/brain-migrate");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+/**
+ * Banner injected at the top of the source hand-written file after a
+ * successful migration. Keeps the original content below so git
+ * history + human review are preserved; future hand-edits still
+ * survive but are flagged as out-of-sync with the CRDT.
+ */
+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. -->
+
+`;
+/**
+ * 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.
+ */
+function computeMergeDelta(existing, parsed) {
+    const existingIds = new Set(existing
+        .map((e) => e?.id)
+        .filter((id) => typeof id === 'string'));
+    const toAdd = [];
+    let skippedCount = 0;
+    for (const entry of parsed) {
+        if (entry.id && existingIds.has(entry.id)) {
+            skippedCount += 1;
+            continue;
+        }
+        toAdd.push(entry);
+    }
+    return { toAdd, skippedCount };
+}
+exports.migrateHandler = {
+    builder: (yargs) => yargs
+        .option('from', {
+        describe: 'Path to the hand-written markdown file to migrate',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('doc', {
+        describe: 'Target brain document ID (e.g. pop.brain.shared)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('force', {
+        describe: 'Re-migrate even if the target doc already has content (DESTRUCTIVE: clears existing lessons/rules before re-seeding)',
+        type: 'boolean',
+        default: false,
+    })
+        .option('merge', {
+        describe: 'Non-destructive append: migrate new entries into an existing doc, deduping by id (mutually exclusive with --force)',
+        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 270)',
+        type: 'number',
+        default: 270,
+    })
+        .option('author', {
+        describe: 'Default author for sections 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 (argv.force && argv.merge) {
+                output.error('--force and --merge are mutually exclusive. --force clears and re-seeds; ' +
+                    '--merge appends dedup-by-id into existing content. Pick one.');
+                process.exitCode = 1;
+                return;
+            }
+            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 ?? 270;
+            const ctx = {
+                defaultAuthor: argv.author ?? 'migration',
+                defaultTimestamp: now,
+                timestampForHB: (hb) => now - (currentHB - hb) * 15 * 60,
+            };
+            const parsed = (0, brain_migrate_1.parseSharedMarkdown)(raw, ctx);
+            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(`  Rules:   ${parsed.rules.length}`);
+                    console.log(`  Lessons: ${parsed.lessons.length}`);
+                    console.log('');
+                    console.log('  First 3 rules:');
+                    for (const r of parsed.rules.slice(0, 3)) {
+                        console.log(`    - ${r.id}: ${(r.text ?? '').slice(0, 80).replace(/\n/g, ' ')}...`);
+                    }
+                    console.log('  First 3 lessons:');
+                    for (const l of parsed.lessons.slice(0, 3)) {
+                        console.log(`    - ${l.id}: ${(l.title ?? '').slice(0, 80)}`);
+                    }
+                    console.log('');
+                    console.log('  No changes persisted (--dry-run).');
+                    console.log('');
+                }
+                return;
+            }
+            // Refuse to overwrite an existing doc unless --force or --merge.
+            const existing = await (0, brain_1.openBrainDoc)(docId);
+            const alreadyHasContent = existing.headCid !== null &&
+                existing.doc &&
+                (Object.keys(existing.doc).length > 0);
+            if (alreadyHasContent && !argv.force && !argv.merge) {
+                output.error(`Target doc "${docId}" already has content at head ${existing.headCid}. ` +
+                    'Re-run with --merge to append new entries non-destructively (dedup by id), ' +
+                    'or --force to clear-and-reseed (DESTRUCTIVE).');
+                process.exitCode = 1;
+                return;
+            }
+            // Merge-mode stats: set in the change callback, read after the apply.
+            let lessonsAdded = 0;
+            let lessonsSkipped = 0;
+            let rulesAdded = 0;
+            let rulesSkipped = 0;
+            // Apply the parsed state in a single Automerge change so the
+            // entire migration lands as one content-addressed snapshot.
+            const result = await (0, brain_1.applyBrainChange)(docId, (doc) => {
+                if (!doc.rules)
+                    doc.rules = [];
+                if (!doc.lessons)
+                    doc.lessons = [];
+                if (argv.force) {
+                    // Force re-migration: clear existing and re-seed.
+                    doc.rules.splice(0, doc.rules.length);
+                    doc.lessons.splice(0, doc.lessons.length);
+                }
+                if (argv.merge) {
+                    // Non-destructive append: dedup by id against existing entries.
+                    const rulesDelta = computeMergeDelta(doc.rules, parsed.rules);
+                    const lessonsDelta = computeMergeDelta(doc.lessons, parsed.lessons);
+                    for (const r of rulesDelta.toAdd)
+                        doc.rules.push({ ...r });
+                    for (const l of lessonsDelta.toAdd)
+                        doc.lessons.push({ ...l });
+                    rulesAdded = rulesDelta.toAdd.length;
+                    rulesSkipped = rulesDelta.skippedCount;
+                    lessonsAdded = lessonsDelta.toAdd.length;
+                    lessonsSkipped = lessonsDelta.skippedCount;
+                    return;
+                }
+                // Legacy / --force path: append everything unconditionally.
+                for (const r of parsed.rules) {
+                    doc.rules.push({ ...r });
+                    rulesAdded += 1;
+                }
+                for (const l of parsed.lessons) {
+                    doc.lessons.push({ ...l });
+                    lessonsAdded += 1;
+                }
+            });
+            // Write the deprecated banner to the source file unless
+            // explicitly suppressed. Keep the original content below.
+            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,
+                    mode: argv.merge ? 'merge' : argv.force ? 'force' : 'fresh',
+                    rulesAdded,
+                    rulesSkipped,
+                    lessonsAdded,
+                    lessonsSkipped,
+                    // Back-compat keys — total parsed, not added.
+                    rulesMigrated: parsed.rules.length,
+                    lessonsMigrated: parsed.lessons.length,
+                    sourceFile: srcPath,
+                    bannerWritten: !argv.noBanner,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Migration complete: ${srcPath} → ${docId}`);
+                console.log(`  Mode: ${argv.merge ? 'merge' : argv.force ? 'force' : 'fresh'}`);
+                console.log(`  New head CID: ${result.headCid}`);
+                if (argv.merge) {
+                    console.log(`  Rules:   +${rulesAdded} added, ${rulesSkipped} skipped (dup id)`);
+                    console.log(`  Lessons: +${lessonsAdded} added, ${lessonsSkipped} skipped (dup id)`);
+                }
+                else {
+                    console.log(`  Rules:   ${rulesAdded}`);
+                    console.log(`  Lessons: ${lessonsAdded}`);
+                }
+                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/new-project.d.ts

@@ -0,0 +1,53 @@
+/**
+ * pop brain new-project — create a project entry in pop.brain.projects.
+ *
+ * First write command for the pop.brain.projects doc shape introduced
+ * in #306. Thin wrapper over applyBrainChange that pushes a new
+ * BrainProject onto doc.projects and auto-publishes via the existing
+ * gossipsub hook. Validates stage against the ProjectStage union so
+ * typos get caught at the CLI boundary.
+ *
+ * Out of scope for this command (each is a separate follow-up):
+ * - advance-stage (advance a project to the next lifecycle stage)
+ * - post-discussion (append a discussion entry)
+ * - add-task-plan (attach a task plan block)
+ * - stage-transition validation (currently any stage is accepted as
+ *   the starting stage; the PROPOSE → DISCUSS → PLAN order is a soft
+ *   convention, not a hard constraint)
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+import type { ProjectStage } from '../../lib/brain-projections';
+interface NewProjectArgs {
+    doc: string;
+    name: string;
+    stage?: ProjectStage;
+    proposedBy?: string;
+    brief?: string;
+    briefFile?: string;
+    id?: string;
+    'idempotency-key'?: string;
+    'no-idempotency'?: boolean;
+}
+export declare const newProjectHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        name: string;
+    } & {
+        stage: ProjectStage;
+    } & {
+        "proposed-by": string | undefined;
+    } & {
+        brief: string | undefined;
+    } & {
+        "brief-file": string | undefined;
+    } & {
+        id: string | undefined;
+    } & {
+        "idempotency-key": string | undefined;
+    } & {
+        "no-idempotency": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<NewProjectArgs>) => Promise<void>;
+};
+export {};

package/dist/commands/brain/new-project.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * pop brain new-project — create a project entry in pop.brain.projects.
+ *
+ * First write command for the pop.brain.projects doc shape introduced
+ * in #306. Thin wrapper over applyBrainChange that pushes a new
+ * BrainProject onto doc.projects and auto-publishes via the existing
+ * gossipsub hook. Validates stage against the ProjectStage union so
+ * typos get caught at the CLI boundary.
+ *
+ * Out of scope for this command (each is a separate follow-up):
+ * - advance-stage (advance a project to the next lifecycle stage)
+ * - post-discussion (append a discussion entry)
+ * - add-task-plan (attach a task plan block)
+ * - stage-transition validation (currently any stage is accepted as
+ *   the starting stage; the PROPOSE → DISCUSS → PLAN order is a soft
+ *   convention, not a hard constraint)
+ */
+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.newProjectHandler = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const ethers_1 = require("ethers");
+const brain_1 = require("../../lib/brain");
+const brain_ops_1 = require("../../lib/brain-ops");
+const idempotency_1 = require("@poa-box/cli/lib/idempotency");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+const VALID_STAGES = [
+    'propose', 'discuss', 'plan', 'vote', 'execute', 'review', 'ship',
+];
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60);
+}
+exports.newProjectHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Target brain document ID (typically pop.brain.projects)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('name', {
+        describe: 'Project name (used as the markdown header + default id base)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('stage', {
+        describe: 'Starting lifecycle stage',
+        type: 'string',
+        choices: VALID_STAGES,
+        default: 'propose',
+    })
+        .option('proposed-by', {
+        describe: 'Override the proposer label (default: signing wallet address)',
+        type: 'string',
+    })
+        .option('brief', {
+        describe: 'Inline project brief (short form)',
+        type: 'string',
+    })
+        .option('brief-file', {
+        describe: 'Path to a file whose contents are used as the brief',
+        type: 'string',
+    })
+        .option('id', {
+        describe: 'Override the auto-generated project id',
+        type: 'string',
+    })
+        .option('idempotency-key', {
+        type: 'string',
+        describe: 'Task #375 (HB#217) idempotency cache. Agent-scoped.',
+    })
+        .option('no-idempotency', {
+        type: 'boolean',
+        default: false,
+        describe: 'Bypass the idempotency cache.',
+    }),
+    handler: async (argv) => {
+        try {
+            // Resolve brief content.
+            let brief;
+            if (argv.briefFile) {
+                const p = (0, path_1.resolve)(argv.briefFile);
+                if (!(0, fs_1.existsSync)(p)) {
+                    output.error(`--brief-file not found: ${p}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                brief = (0, fs_1.readFileSync)(p, 'utf8').replace(/\s+$/, '');
+            }
+            else if (argv.brief !== undefined) {
+                brief = argv.brief.trim();
+            }
+            // Resolve proposedBy label up front — matches the append-lesson
+            // pattern. Default: lowercased wallet address from POP_PRIVATE_KEY.
+            let proposedBy;
+            if (argv.proposedBy) {
+                proposedBy = argv.proposedBy;
+            }
+            else {
+                const key = process.env.POP_PRIVATE_KEY;
+                if (!key) {
+                    output.error('POP_PRIVATE_KEY not set — cannot derive default proposedBy. Pass --proposed-by explicitly.');
+                    process.exitCode = 1;
+                    return;
+                }
+                proposedBy = new ethers_1.ethers.Wallet(key).address.toLowerCase();
+            }
+            // Compute the id. Default is slugify(name); on collision with
+            // an existing project, append a unix-seconds suffix so a second
+            // caller with the same --name still succeeds.
+            const { doc: currentDoc } = await (0, brain_1.openBrainDoc)(argv.doc);
+            const existing = Array.isArray(currentDoc?.projects) ? currentDoc.projects : [];
+            const baseId = argv.id ?? (slugify(argv.name) || 'project');
+            let id = baseId;
+            if (existing.some(p => p?.id === id)) {
+                id = `${baseId}-${Math.floor(Date.now() / 1000)}`;
+            }
+            const now = Math.floor(Date.now() / 1000);
+            const stage = (argv.stage ?? 'propose');
+            // Task #375 (HB#217): idempotency check, agent-scoped
+            const idempKey = argv.idempotencyKey || (0, idempotency_1.argvToIdempotencyString)(argv);
+            if (!argv.noIdempotency) {
+                const cached = (0, idempotency_1.checkIdempotencyCache)(proposedBy, 'brain.newProject', idempKey);
+                if (cached) {
+                    if (output.isJsonMode()) {
+                        output.json({ status: 'ok', cached: true, ...cached });
+                    }
+                    else {
+                        console.log('');
+                        console.log(`  Project already created (idempotency cache hit)`);
+                        console.log(`  id:     ${cached.projectId}`);
+                        console.log(`  head:   ${cached.headCid}`);
+                        console.log('');
+                    }
+                    return;
+                }
+            }
+            // Route through the unified dispatcher (HB#324 ship-2).
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'newProject',
+                docId: argv.doc,
+                projectId: id,
+                name: argv.name,
+                brief,
+                stage,
+                proposedBy,
+                proposedAt: now,
+            });
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(proposedBy, 'brain.newProject', idempKey, {
+                    docId: argv.doc,
+                    projectId: id,
+                    headCid: result.headCid,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    projectId: id,
+                    name: argv.name,
+                    stage,
+                    proposedBy,
+                    headCid: result.headCid,
+                    envelopeAuthor: result.envelopeAuthor,
+                    routedViaDaemon: result.routedViaDaemon,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Project created in ${argv.doc}`);
+                console.log(`  id:          ${id}`);
+                console.log(`  name:        ${argv.name}`);
+                console.log(`  stage:       ${stage}`);
+                console.log(`  proposedBy:  ${proposedBy}`);
+                console.log(`  head:        ${result.headCid}`);
+                console.log(`  routed:      ${result.routedViaDaemon ? 'via brain daemon' : 'in-process (no daemon)'}`);
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};

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

@@ -0,0 +1,24 @@
+/**
+ * pop brain read — project a brain doc to JSON (or human-readable text).
+ *
+ * This is the read side of the brain CRDT substrate. Loads the Automerge
+ * doc identified by the current head CID in the manifest, verifies the
+ * signed envelope, and prints the current state. Useful for:
+ *
+ *   - Verifying that a subscriber successfully synced a remote write
+ *     (step 6 acceptance)
+ *   - Inspecting the state of any local brain doc from the shell
+ *   - Feeding the projection layer (step 7) when it replaces the
+ *     hand-written shared.md / projects.md files
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface ReadArgs {
+    doc: string;
+}
+export declare const readHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    }>;
+    handler: (argv: ArgumentsCamelCase<ReadArgs>) => Promise<void>;
+};
+export {};

package/dist/commands/brain/read.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * pop brain read — project a brain doc to JSON (or human-readable text).
+ *
+ * This is the read side of the brain CRDT substrate. Loads the Automerge
+ * doc identified by the current head CID in the manifest, verifies the
+ * signed envelope, and prints the current state. Useful for:
+ *
+ *   - Verifying that a subscriber successfully synced a remote write
+ *     (step 6 acceptance)
+ *   - Inspecting the state of any local brain doc from the shell
+ *   - Feeding the projection layer (step 7) when it replaces the
+ *     hand-written shared.md / projects.md files
+ */
+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.readHandler = void 0;
+const brain_1 = require("../../lib/brain");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+exports.readHandler = {
+    builder: (yargs) => yargs.option('doc', {
+        describe: 'Brain document ID (e.g. pop.brain.shared)',
+        type: 'string',
+        demandOption: true,
+    }),
+    handler: async (argv) => {
+        try {
+            const { doc, headCid } = await (0, brain_1.readBrainDoc)(argv.doc);
+            if (output.isJsonMode()) {
+                output.json({ docId: argv.doc, headCid, doc });
+            }
+            else {
+                console.log('');
+                console.log(`  Brain doc: ${argv.doc}`);
+                console.log(`  Head CID:  ${headCid ?? '(none — empty doc)'}`);
+                console.log('  ' + '─'.repeat(60));
+                console.log(JSON.stringify(doc, null, 2));
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+        finally {
+            await (0, brain_1.stopBrainNode)();
+        }
+    },
+};