@poa-box/agent 0.1.0

package/dist/commands/brain/advance-stage.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * pop brain advance-stage — move a project through the lifecycle.
+ *
+ * Second write command for the pop.brain.projects doc shape. Finds a
+ * project by id, advances its stage to either an explicit --to target
+ * or the next stage in the canonical PROPOSE → DISCUSS → PLAN → VOTE
+ * → EXECUTE → REVIEW → SHIP sequence, and records a lastStageAdvanceAt
+ * timestamp. Short-circuits no-op transitions, errors cleanly on
+ * not-found, and refuses to advance past 'ship'.
+ *
+ * Design note: the canonical order is a SOFT convention at the data
+ * layer — any stage string is accepted on disk (so legacy / scripted
+ * writes can use custom stages). advance-stage enforces the order
+ * only for the --to-omitted "next stage" case. Passing --to <stage>
+ * sets the stage directly without checking that the transition makes
+ * sense (this allows 'discuss → ship' when the operator knows what
+ * they're doing, at the cost of letting a typo jump over stages).
+ */
+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.advanceStageHandler = void 0;
+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 STAGE_ORDER = [
+    'propose', 'discuss', 'plan', 'vote', 'execute', 'review', 'ship',
+];
+function nextStage(current) {
+    const idx = STAGE_ORDER.indexOf(current);
+    if (idx === -1)
+        return null; // Unknown current stage — caller errors.
+    if (idx === STAGE_ORDER.length - 1)
+        return null; // Already at ship.
+    return STAGE_ORDER[idx + 1];
+}
+exports.advanceStageHandler = {
+    builder: (yargs) => yargs
+        .option('doc', {
+        describe: 'Brain document ID (typically pop.brain.projects)',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('project-id', {
+        describe: 'The project.id to advance',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('to', {
+        describe: 'Explicit target stage (default: next stage in canonical order)',
+        type: 'string',
+        choices: STAGE_ORDER,
+    })
+        .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 {
+            // Pre-flight: locate the project, emit actionable not-found error.
+            const { doc: currentDoc } = await (0, brain_1.openBrainDoc)(argv.doc);
+            const projects = Array.isArray(currentDoc?.projects) ? currentDoc.projects : [];
+            const target = projects.find((p) => p?.id === argv.projectId);
+            if (!target) {
+                const candidates = projects
+                    .map((p) => p?.id)
+                    .filter((id) => typeof id === 'string')
+                    .slice(0, 8);
+                output.error(`Project "${argv.projectId}" not found in ${argv.doc}. ` +
+                    `Available ids (first 8): ${candidates.join(', ') || '(none)'}`);
+                process.exitCode = 1;
+                return;
+            }
+            // Resolve the target stage.
+            let nextStageValue;
+            if (argv.to) {
+                nextStageValue = argv.to;
+            }
+            else {
+                const computed = nextStage(target.stage ?? '');
+                if (!computed) {
+                    if (target.stage === 'ship') {
+                        output.error(`Project "${argv.projectId}" is already at stage 'ship' — no next stage. ` +
+                            `Use --to <stage> if you need to override.`);
+                    }
+                    else {
+                        output.error(`Project "${argv.projectId}" has unknown current stage "${target.stage}" — ` +
+                            `cannot compute next stage automatically. Pass --to <stage> to set explicitly.`);
+                    }
+                    process.exitCode = 1;
+                    return;
+                }
+                nextStageValue = computed;
+            }
+            // Short-circuit: stage is already the target.
+            if (target.stage === nextStageValue) {
+                if (output.isJsonMode()) {
+                    output.json({
+                        status: 'noop',
+                        docId: argv.doc,
+                        projectId: argv.projectId,
+                        stage: nextStageValue,
+                    });
+                }
+                else {
+                    console.log(`Project "${argv.projectId}" is already at stage '${nextStageValue}'. No-op.`);
+                }
+                return;
+            }
+            const now = Math.floor(Date.now() / 1000);
+            const priorStage = target.stage;
+            // Task #375 (HB#217): agent-scoped idempotency cache
+            const signerKey = process.env.POP_PRIVATE_KEY;
+            const authorScope = signerKey ? new ethers_1.ethers.Wallet(signerKey).address.toLowerCase() : 'anonymous';
+            const idempKey = argv.idempotencyKey || (0, idempotency_1.argvToIdempotencyString)(argv);
+            if (!argv.noIdempotency) {
+                const cached = (0, idempotency_1.checkIdempotencyCache)(authorScope, 'brain.advanceStage', idempKey);
+                if (cached) {
+                    if (output.isJsonMode()) {
+                        output.json({ status: 'ok', cached: true, ...cached });
+                    }
+                    else {
+                        console.log(`  Project "${argv.projectId}" stage already advanced (idempotency cache hit). head: ${cached.headCid}`);
+                    }
+                    return;
+                }
+            }
+            // Route through the unified dispatcher (HB#324 ship-2).
+            const result = await (0, brain_ops_1.routedDispatch)({
+                type: 'advanceStage',
+                docId: argv.doc,
+                projectId: argv.projectId,
+                newStage: nextStageValue,
+                lastStageAdvanceAt: now,
+            });
+            if (!argv.noIdempotency) {
+                (0, idempotency_1.recordIdempotentResult)(authorScope, 'brain.advanceStage', idempKey, {
+                    docId: argv.doc,
+                    projectId: argv.projectId,
+                    stage: nextStageValue,
+                    headCid: result.headCid,
+                });
+            }
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    docId: argv.doc,
+                    projectId: argv.projectId,
+                    priorStage,
+                    stage: nextStageValue,
+                    lastStageAdvanceAt: now,
+                    headCid: result.headCid,
+                    routedViaDaemon: result.routedViaDaemon,
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Project "${argv.projectId}" advanced in ${argv.doc}`);
+                console.log(`  ${priorStage} → ${nextStageValue}`);
+                console.log(`  lastStageAdvanceAt: ${new Date(now * 1000).toISOString()}`);
+                console.log(`  new 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/allowlist.d.ts

@@ -0,0 +1,30 @@
+/**
+ * pop brain allowlist — list/add/remove operator commands for the
+ * agent/brain/Config/brain-allowlist.json file.
+ *
+ * These are thin CLI wrappers over direct JSON writes. The security
+ * boundary stays at git: the file is git-tracked, changes land via
+ * PR + review, and the current 3-agent Argus setup treats any write
+ * as needing peer approval. The commands just reduce friction vs
+ * hand-editing JSON.
+ *
+ * Runtime vs build-time: the allowlist is read via `readFileSync`
+ * on every `isAllowedAuthor` call (see `brain-signing.ts loadAllowlist`).
+ * A git pull is enough to pick up new entries — agents do NOT need
+ * to rebuild dist/ just because an address was added. Rebuild only
+ * matters when `brain-signing.ts` itself changes.
+ *
+ * Not in scope for this command:
+ * - `pop brain allowlist sync` — propagating changes via the brain
+ *   layer itself (chicken-and-egg: the allowlist change would need
+ *   to come from an allowlisted author, which gives you zero benefit
+ *   over the current git flow for a new-agent onboarding).
+ * - Governance-backed allowlist changes — each edit going through a
+ *   formal `pop vote` would be a clean pattern but is heavy for MVP.
+ *   Current review-via-git approximates it.
+ */
+import type { Argv } from 'yargs';
+export declare const allowlistHandler: {
+    builder: (yargs: Argv) => Argv<{}>;
+    handler: () => void;
+};

package/dist/commands/brain/allowlist.js

@@ -0,0 +1,274 @@
+"use strict";
+/**
+ * pop brain allowlist — list/add/remove operator commands for the
+ * agent/brain/Config/brain-allowlist.json file.
+ *
+ * These are thin CLI wrappers over direct JSON writes. The security
+ * boundary stays at git: the file is git-tracked, changes land via
+ * PR + review, and the current 3-agent Argus setup treats any write
+ * as needing peer approval. The commands just reduce friction vs
+ * hand-editing JSON.
+ *
+ * Runtime vs build-time: the allowlist is read via `readFileSync`
+ * on every `isAllowedAuthor` call (see `brain-signing.ts loadAllowlist`).
+ * A git pull is enough to pick up new entries — agents do NOT need
+ * to rebuild dist/ just because an address was added. Rebuild only
+ * matters when `brain-signing.ts` itself changes.
+ *
+ * Not in scope for this command:
+ * - `pop brain allowlist sync` — propagating changes via the brain
+ *   layer itself (chicken-and-egg: the allowlist change would need
+ *   to come from an allowlisted author, which gives you zero benefit
+ *   over the current git flow for a new-agent onboarding).
+ * - Governance-backed allowlist changes — each edit going through a
+ *   formal `pop vote` would be a clean pattern but is heavy for MVP.
+ *   Current review-via-git approximates it.
+ */
+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.allowlistHandler = void 0;
+const fs_1 = require("fs");
+const ethers_1 = require("ethers");
+const brain_signing_1 = require("../../lib/brain-signing");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+/**
+ * Normalize an address input: must match the standard hex format, and
+ * gets lowercased before storage/comparison. Throws with a clean error
+ * message on malformed input (yargs catches and reports).
+ */
+function normalizeAddress(raw) {
+    if (!ADDRESS_RE.test(raw)) {
+        throw new Error(`Invalid address "${raw}" — must be a 0x-prefixed 40-character hex string.`);
+    }
+    return raw.toLowerCase();
+}
+/**
+ * Read the full allowlist file (not just via loadAllowlist which
+ * normalizes the shape). Preserves every field that's on disk,
+ * including any addedNote / future extensions. Returns an empty
+ * array if the file doesn't exist yet.
+ */
+function readRawAllowlist() {
+    const p = (0, brain_signing_1.getAllowlistPath)();
+    if (!(0, fs_1.existsSync)(p))
+        return [];
+    try {
+        const raw = JSON.parse((0, fs_1.readFileSync)(p, 'utf8'));
+        if (Array.isArray(raw))
+            return raw;
+        if (Array.isArray(raw?.entries))
+            return raw.entries;
+        return [];
+    }
+    catch (err) {
+        throw new Error(`Failed to read allowlist at ${p}: ${err.message}`);
+    }
+}
+function writeAllowlist(entries) {
+    (0, fs_1.writeFileSync)((0, brain_signing_1.getAllowlistPath)(), JSON.stringify(entries, null, 2) + '\n');
+}
+const listHandler = {
+    builder: (yargs) => yargs,
+    handler: async (_argv) => {
+        const entries = (0, brain_signing_1.loadAllowlist)();
+        if (output.isJsonMode()) {
+            output.json({ status: 'ok', count: entries.length, entries });
+            return;
+        }
+        console.log('');
+        console.log(`  Brain allowlist (${entries.length} entr${entries.length === 1 ? 'y' : 'ies'})`);
+        console.log('  ' + '─'.repeat(70));
+        if (entries.length === 0) {
+            console.log('  (empty)');
+            console.log('');
+            return;
+        }
+        for (const e of entries) {
+            const name = e.name ?? '(no name)';
+            console.log(`  ${e.address}  ${name}`);
+            if (e.addedAt)
+                console.log(`    addedAt: ${e.addedAt}`);
+            if (e.addedBy)
+                console.log(`    addedBy: ${e.addedBy}`);
+        }
+        console.log('');
+        console.log(`  File: ${(0, brain_signing_1.getAllowlistPath)()}`);
+        console.log('');
+    },
+};
+const addHandler = {
+    builder: (yargs) => yargs
+        .option('address', {
+        describe: '0x-prefixed 40-char hex address to allowlist',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('name', {
+        describe: 'Human label (e.g. agent username)',
+        type: 'string',
+    })
+        .option('note', {
+        describe: 'Optional addedNote field recorded on the entry',
+        type: 'string',
+    }),
+    handler: async (argv) => {
+        try {
+            const address = normalizeAddress(argv.address);
+            const entries = readRawAllowlist();
+            if (entries.some(e => String(e.address).toLowerCase() === address)) {
+                output.error(`Address ${address} is already in the allowlist.`);
+                process.exitCode = 1;
+                return;
+            }
+            // Derive addedBy from POP_PRIVATE_KEY if available so the entry
+            // records WHICH existing allowlisted agent is performing the
+            // add. Falls back to 'unknown' if no key is set (e.g. running
+            // the command on a fresh machine that hasn't configured a key
+            // yet — legitimate during bootstrap).
+            let addedBy;
+            const key = process.env.POP_PRIVATE_KEY;
+            if (key) {
+                try {
+                    addedBy = new ethers_1.ethers.Wallet(key).address.toLowerCase();
+                }
+                catch {
+                    addedBy = 'unknown';
+                }
+            }
+            else {
+                addedBy = 'unknown';
+            }
+            const entry = {
+                address,
+                name: argv.name,
+                addedAt: new Date().toISOString().slice(0, 10), // YYYY-MM-DD
+                addedBy,
+            };
+            if (argv.note)
+                entry.addedNote = argv.note;
+            entries.push(entry);
+            writeAllowlist(entries);
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    added: entry,
+                    count: entries.length,
+                    path: (0, brain_signing_1.getAllowlistPath)(),
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Added ${address} to the allowlist.`);
+                if (entry.name)
+                    console.log(`  name:    ${entry.name}`);
+                console.log(`  addedAt: ${entry.addedAt}`);
+                console.log(`  addedBy: ${entry.addedBy}`);
+                if (entry.addedNote)
+                    console.log(`  note:    ${entry.addedNote}`);
+                console.log('');
+                console.log('  The change is local until committed. Next:');
+                console.log('    git add agent/brain/Config/brain-allowlist.json');
+                console.log(`    git commit -m "Allowlist ${entry.name ?? address}"`);
+                console.log('    git push  # PR for review');
+                console.log('');
+                console.log('  Once other agents git pull, the new address is live —');
+                console.log('  no rebuild required (loadAllowlist reads the file at runtime).');
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+    },
+};
+const removeHandler = {
+    builder: (yargs) => yargs.option('address', {
+        describe: '0x-prefixed 40-char hex address to remove',
+        type: 'string',
+        demandOption: true,
+    }),
+    handler: async (argv) => {
+        try {
+            const address = normalizeAddress(argv.address);
+            const entries = readRawAllowlist();
+            const idx = entries.findIndex(e => String(e.address).toLowerCase() === address);
+            if (idx === -1) {
+                const existing = entries.map(e => String(e.address).toLowerCase()).slice(0, 8);
+                output.error(`Address ${address} not in allowlist. Existing (first 8): ${existing.join(', ') || '(empty)'}`);
+                process.exitCode = 1;
+                return;
+            }
+            const removed = entries.splice(idx, 1)[0];
+            writeAllowlist(entries);
+            if (output.isJsonMode()) {
+                output.json({
+                    status: 'ok',
+                    removed,
+                    count: entries.length,
+                    path: (0, brain_signing_1.getAllowlistPath)(),
+                });
+            }
+            else {
+                console.log('');
+                console.log(`  Removed ${address} from the allowlist.`);
+                if (removed.name)
+                    console.log(`  was: ${removed.name}`);
+                console.log(`  ${entries.length} entries remain.`);
+                console.log('');
+                console.log('  The change is local until committed. Next:');
+                console.log('    git add agent/brain/Config/brain-allowlist.json');
+                console.log(`    git commit -m "Remove ${removed.name ?? address} from allowlist"`);
+                console.log('    git push  # PR for review');
+                console.log('');
+            }
+        }
+        catch (err) {
+            output.error(err.message);
+            process.exitCode = 1;
+        }
+    },
+};
+exports.allowlistHandler = {
+    builder: (yargs) => yargs
+        .command('list', 'Show current brain allowlist entries', listHandler.builder, listHandler.handler)
+        .command('add', 'Add an address to the brain allowlist', addHandler.builder, addHandler.handler)
+        .command('remove', 'Remove an address from the brain allowlist', removeHandler.builder, removeHandler.handler)
+        .demandCommand(1, 'Please specify a brain allowlist action (list/add/remove)'),
+    handler: () => {
+        // Top-level dispatch — the subcommand handlers do the actual work.
+    },
+};

package/dist/commands/brain/append-lesson.d.ts

@@ -0,0 +1,55 @@
+/**
+ * pop brain append-lesson — user-facing write path into the CRDT brain
+ * substrate. Thin wrapper over applyBrainChange that pushes a lesson
+ * object onto `doc.lessons` and auto-publishes the new head via
+ * gossipsub (step 5) + seeds it for Bitswap (step 6).
+ *
+ * Before this command, writing a lesson required a Node script that
+ * imported dist/lib/brain.js and called applyBrainChange manually.
+ * This command closes the last ergonomic gap before the brain
+ * substrate is day-to-day usable for heartbeat work.
+ *
+ * Usage:
+ *   pop brain append-lesson --doc pop.brain.shared \
+ *     --title "Don't upgrade libp2p past 2.x" \
+ *     --body "gossipsub 14 crashes on libp2p 3+ ... "
+ *
+ *   pop brain append-lesson --doc pop.brain.shared \
+ *     --title "Long form lesson" \
+ *     --body-file /tmp/lesson.md
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+interface AppendArgs {
+    doc: string;
+    title: string;
+    body?: string;
+    bodyFile?: string;
+    author?: string;
+    id?: string;
+    allowInvalidShape?: boolean;
+    'idempotency-key'?: string;
+    'no-idempotency'?: boolean;
+}
+export declare const appendLessonHandler: {
+    builder: (yargs: Argv) => Argv<{
+        doc: string;
+    } & {
+        title: string;
+    } & {
+        body: string | undefined;
+    } & {
+        "body-file": string | undefined;
+    } & {
+        author: string | undefined;
+    } & {
+        id: string | undefined;
+    } & {
+        "allow-invalid-shape": boolean;
+    } & {
+        "idempotency-key": string | undefined;
+    } & {
+        "no-idempotency": boolean;
+    }>;
+    handler: (argv: ArgumentsCamelCase<AppendArgs>) => Promise<void>;
+};
+export {};