@poa-box/agent 0.1.0

package/dist/commands/brain/daemon.js

@@ -0,0 +1,348 @@
+"use strict";
+/**
+ * pop brain daemon — process control for the persistent brain daemon
+ * (HB#322 architecture: go-ds-crdt-shaped rebroadcast + keepalive loop,
+ * see src/lib/brain-daemon.ts for the full design rationale).
+ *
+ * Subcommands:
+ *   start    spawn a detached daemon child
+ *   stop     signal a running daemon to shut down gracefully
+ *   status   print daemon stats (peer count, topics, uptime, rebroadcast
+ *            counts) via IPC
+ *   logs     tail the daemon log file
+ *   __run    internal — the actual daemon entrypoint. Never call directly
+ *            from the shell; start uses this.
+ */
+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.daemonHandler = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const brain_daemon_1 = require("../../lib/brain-daemon");
+const brain_1 = require("../../lib/brain");
+const output = __importStar(require("@poa-box/cli/lib/output"));
+async function handleStart() {
+    const existing = (0, brain_daemon_1.getRunningDaemonPid)();
+    if (existing !== null) {
+        if (output.isJsonMode()) {
+            output.json({
+                status: 'already-running',
+                pid: existing,
+                pidPath: (0, brain_daemon_1.getDaemonPidPath)(),
+            });
+        }
+        else {
+            console.log(`Brain daemon already running with PID ${existing}`);
+            console.log(`  pid file: ${(0, brain_daemon_1.getDaemonPidPath)()}`);
+            console.log(`  socket:   ${(0, brain_daemon_1.getDaemonSockPath)()}`);
+            console.log(`  log:      ${(0, brain_daemon_1.getDaemonLogPath)()}`);
+        }
+        return;
+    }
+    // Determine the path to our own CLI entrypoint so the detached child
+    // can run the __run subcommand. We use process.argv[1] when it points
+    // at dist/index.js, else fall back to the canonical path.
+    const selfScript = process.argv[1];
+    const child = (0, child_process_1.spawn)(process.execPath, // node itself
+    [selfScript, 'brain', 'daemon', '__run'], {
+        detached: true,
+        stdio: 'ignore',
+        // Forward critical env so the child has the same wallet / brain home.
+        env: process.env,
+    });
+    child.unref();
+    // Poll the PID file for up to 5s to confirm the daemon actually came up.
+    // Without this the user gets "started" for a process that crashed at init.
+    const pidPath = (0, brain_daemon_1.getDaemonPidPath)();
+    const startedAt = Date.now();
+    let pid = null;
+    while (Date.now() - startedAt < 5000) {
+        if ((0, fs_1.existsSync)(pidPath)) {
+            try {
+                pid = parseInt((0, fs_1.readFileSync)(pidPath, 'utf8').trim(), 10);
+                if (Number.isFinite(pid) && pid > 0)
+                    break;
+            }
+            catch { }
+        }
+        await new Promise(r => setTimeout(r, 100));
+    }
+    if (!pid) {
+        if (output.isJsonMode()) {
+            output.json({
+                status: 'error',
+                reason: 'daemon did not write PID file within 5s — check log',
+                logPath: (0, brain_daemon_1.getDaemonLogPath)(),
+            });
+        }
+        else {
+            console.error(`Brain daemon failed to start within 5s.`);
+            console.error(`Check the log: ${(0, brain_daemon_1.getDaemonLogPath)()}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (output.isJsonMode()) {
+        output.json({
+            status: 'started',
+            pid,
+            pidPath,
+            sockPath: (0, brain_daemon_1.getDaemonSockPath)(),
+            logPath: (0, brain_daemon_1.getDaemonLogPath)(),
+            rebroadcastIntervalMs: brain_daemon_1.REBROADCAST_INTERVAL_MS,
+            keepaliveIntervalMs: brain_daemon_1.KEEPALIVE_INTERVAL_MS,
+        });
+    }
+    else {
+        console.log(`Brain daemon started`);
+        console.log(`  PID:             ${pid}`);
+        console.log(`  brain home:      ${(0, brain_1.getBrainHome)()}`);
+        console.log(`  pid file:        ${pidPath}`);
+        console.log(`  socket:          ${(0, brain_daemon_1.getDaemonSockPath)()}`);
+        console.log(`  log:             ${(0, brain_daemon_1.getDaemonLogPath)()}`);
+        console.log(`  rebroadcast:     ${brain_daemon_1.REBROADCAST_INTERVAL_MS / 1000}s`);
+        console.log(`  keepalive:       ${brain_daemon_1.KEEPALIVE_INTERVAL_MS / 1000}s`);
+        console.log(``);
+        console.log(`Verify with: pop brain daemon status`);
+    }
+}
+async function handleStop() {
+    const pid = (0, brain_daemon_1.getRunningDaemonPid)();
+    if (pid === null) {
+        if (output.isJsonMode()) {
+            output.json({ status: 'not-running' });
+        }
+        else {
+            console.log('Brain daemon is not running.');
+        }
+        return;
+    }
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch (err) {
+        if (output.isJsonMode()) {
+            output.json({ status: 'error', reason: err.message, pid });
+        }
+        else {
+            console.error(`Failed to signal PID ${pid}: ${err.message}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // Wait up to 10s for the PID file to disappear (daemon's own cleanup).
+    const started = Date.now();
+    while (Date.now() - started < 10_000) {
+        if ((0, brain_daemon_1.getRunningDaemonPid)() === null)
+            break;
+        await new Promise(r => setTimeout(r, 100));
+    }
+    const stillRunning = (0, brain_daemon_1.getRunningDaemonPid)();
+    if (stillRunning !== null) {
+        if (output.isJsonMode()) {
+            output.json({
+                status: 'error',
+                reason: `daemon still running after SIGTERM + 10s — may need SIGKILL`,
+                pid: stillRunning,
+            });
+        }
+        else {
+            console.error(`Daemon still running after SIGTERM + 10s (PID ${stillRunning}).`);
+            console.error(`Force-kill with: kill -9 ${stillRunning}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (output.isJsonMode()) {
+        output.json({ status: 'stopped', pid });
+    }
+    else {
+        console.log(`Brain daemon stopped (was PID ${pid}).`);
+    }
+}
+async function handleStatus() {
+    const pid = (0, brain_daemon_1.getRunningDaemonPid)();
+    if (pid === null) {
+        if (output.isJsonMode()) {
+            output.json({ status: 'not-running' });
+        }
+        else {
+            console.log('Brain daemon is not running.');
+            console.log('Start it with: pop brain daemon start');
+        }
+        return;
+    }
+    let ipcResult;
+    try {
+        ipcResult = await (0, brain_daemon_1.sendIpcRequest)('status', {}, 3000);
+    }
+    catch (err) {
+        if (output.isJsonMode()) {
+            output.json({
+                status: 'ipc-error',
+                pid,
+                reason: err.message,
+            });
+        }
+        else {
+            console.error(`Daemon PID ${pid} is alive but IPC failed: ${err.message}`);
+            console.error(`Check log: ${(0, brain_daemon_1.getDaemonLogPath)()}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (output.isJsonMode()) {
+        output.json({
+            status: 'running',
+            pid,
+            ...ipcResult,
+        });
+        return;
+    }
+    const lastRebroadcast = ipcResult.lastRebroadcastAt
+        ? new Date(ipcResult.lastRebroadcastAt).toISOString()
+        : 'never';
+    const lastKeepalive = ipcResult.lastKeepaliveAt
+        ? new Date(ipcResult.lastKeepaliveAt).toISOString()
+        : 'never';
+    console.log(`Brain daemon running`);
+    console.log(`  PID:                  ${pid}`);
+    console.log(`  peer ID:              ${ipcResult.peerId}`);
+    console.log(`  uptime:               ${ipcResult.uptime}s`);
+    console.log(`  connections:          ${ipcResult.connections}`);
+    console.log(`  known peers:          ${ipcResult.knownPeerCount}`);
+    console.log(`  subscribed topics:    ${ipcResult.topics?.length ?? 0}`);
+    if (ipcResult.topics?.length) {
+        for (const t of ipcResult.topics) {
+            console.log(`    - ${t}`);
+        }
+    }
+    console.log(`  subscribed docs:      ${ipcResult.subscribedDocs?.length ?? 0}`);
+    if (ipcResult.subscribedDocs?.length) {
+        for (const d of ipcResult.subscribedDocs) {
+            console.log(`    - ${d}`);
+        }
+    }
+    console.log(`  rebroadcast count:    ${ipcResult.rebroadcastCount}`);
+    console.log(`  last rebroadcast:     ${lastRebroadcast}`);
+    console.log(`  keepalive count:      ${ipcResult.keepaliveCount}`);
+    console.log(`  last keepalive:       ${lastKeepalive}`);
+    console.log(`  incoming announces:   ${ipcResult.incomingAnnouncements}`);
+    console.log(`  incoming merges:      ${ipcResult.incomingMerges}`);
+    console.log(`  incoming rejects:     ${ipcResult.incomingRejects || 0}`);
+    console.log(`  brain home:           ${ipcResult.brainHome}`);
+    console.log(`  log:                  ${ipcResult.logPath}`);
+}
+async function handleLogs(tail, follow) {
+    const logPath = (0, brain_daemon_1.getDaemonLogPath)();
+    if (!(0, fs_1.existsSync)(logPath)) {
+        console.error(`No daemon log at ${logPath}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Minimal implementation: print last N lines. --follow uses tail -F.
+    if (follow) {
+        const { spawn: spawnFollow } = await Promise.resolve().then(() => __importStar(require('child_process')));
+        const proc = spawnFollow('tail', ['-F', '-n', String(tail), logPath], {
+            stdio: 'inherit',
+        });
+        await new Promise(r => proc.on('close', r));
+        return;
+    }
+    const content = (0, fs_1.readFileSync)(logPath, 'utf8');
+    const lines = content.split('\n');
+    const slice = lines.slice(Math.max(0, lines.length - tail - 1));
+    console.log(slice.join('\n'));
+}
+async function handleRun() {
+    // This is the child process entrypoint. It blocks forever.
+    try {
+        await (0, brain_daemon_1.runDaemon)();
+    }
+    catch (err) {
+        // Write the error to the log file if we can; the parent process
+        // watches the PID file to detect failures.
+        const logPath = (0, brain_daemon_1.getDaemonLogPath)();
+        try {
+            const { appendFileSync } = await Promise.resolve().then(() => __importStar(require('fs')));
+            appendFileSync(logPath, `${new Date().toISOString()} FATAL ${err.stack ?? err.message}\n`);
+        }
+        catch { }
+        process.exit(1);
+    }
+}
+exports.daemonHandler = {
+    builder: (yargs) => yargs
+        .positional('action', {
+        describe: 'Daemon action',
+        type: 'string',
+        choices: ['start', 'stop', 'status', 'logs', '__run'],
+    })
+        .option('follow', {
+        alias: 'f',
+        describe: 'Follow the log file (logs subcommand only)',
+        type: 'boolean',
+        default: false,
+    })
+        .option('tail', {
+        alias: 'n',
+        describe: 'Number of log lines to print (logs subcommand only)',
+        type: 'number',
+        default: 50,
+    }),
+    handler: async (argv) => {
+        const action = argv.action;
+        switch (action) {
+            case 'start':
+                await handleStart();
+                return;
+            case 'stop':
+                await handleStop();
+                return;
+            case 'status':
+                await handleStatus();
+                return;
+            case 'logs':
+                await handleLogs(argv.tail ?? 50, argv.follow ?? false);
+                return;
+            case '__run':
+                await handleRun();
+                return;
+            default:
+                output.error(`Unknown daemon action: ${action}`);
+                process.exitCode = 1;
+        }
+    },
+};

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

@@ -0,0 +1,27 @@
+/**
+ * pop brain doctor — single-command health check for brain layer setup.
+ *
+ * Answers "is my brain setup healthy?" in one invocation. Complements
+ * `docs/agents/brain-layer-setup.md` (setup doc tells you HOW; doctor tells
+ * you IF the setup is actually working).
+ *
+ * Output shape:
+ *   ✓ check name      — pass
+ *   ⚠ check name      — warn (not fatal, but worth knowing)
+ *   ✗ check name      — fail (exit 1)
+ *
+ * Exit codes:
+ *   0 — all pass or pass+warn (warnings don't fail the run)
+ *   1 — any ✗ fail
+ *
+ * --json returns { checks: [{name, status, detail, elapsed?}], summary }
+ *
+ * Design: every check is self-contained and independent. A failure in
+ * one check does NOT stop later checks from running — the operator
+ * wants the full picture, not the first stumble.
+ */
+import type { Argv, ArgumentsCamelCase } from 'yargs';
+export declare const doctorHandler: {
+    builder: (yargs: Argv) => Argv<{}>;
+    handler: (_argv: ArgumentsCamelCase<{}>) => Promise<void>;
+};