@ouro.bot/cli 0.1.0-alpha.500 → 0.1.0-alpha.501

package/changelog.json

@@ -1,6 +1,14 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.501",
+      "changes": [
+        "New `ouro nerves-review` CLI for tailing the agent's nerves ndjson with structured filters. Read-only. Operators previously had to grep raw ndjson by hand to track down something like 'how many heartbeat-recursion-suspected events fired today' or 'show me the last hour of senses warnings'.",
+        "Filters: `--component <substr>`, `--event <substr>`, `--level <level>`, `--since <duration>` (e.g. 5m, 2h, 1d), `--limit <N>`, `--process <name>` (default: daemon), `--agent <name>` (default: current). Output modes: human-readable text (`<time> [<level>] <component>/<event> — <message>`) and `--json` (one parsed object per line for piping to jq).",
+        "Pure `reviewNerveEvents(filePath, filter)` core in `src/nerves/review/core.ts` reads the tail of the ndjson (8 MB cap, walks last 200+ lines) and applies in-memory filters; testable without filesystem mocks beyond a temp file. 12 tests cover all six filter dimensions plus duration parsing edge cases (ms/s/m/h/d, malformed inputs), missing-file handling, and the two CLI flag paths (--help, invalid --since). Wired as `npm run nerves:review -- <flags>` and `dist/nerves/review/cli-main.js`."
+      ]
+    },
     {
       "version": "0.1.0-alpha.500",
       "changes": [

package/dist/nerves/coverage/file-completeness.js

@@ -120,6 +120,11 @@ const DISPATCH_EXEMPT_PATTERNS = [
     "heart/session-playback-cli-main",
     "heart/session-playback-cli",
     "heart/session-playback",
+    // Nerves review: read-only NDJSON tail/filter CLI for debugging.
+    // Diagnostics-only utility; the running daemon owns observability.
+    "nerves/review/cli-main",
+    "nerves/review/cli",
+    "nerves/review/core",
 ];
 function isDispatchExempt(filePath) {
     return DISPATCH_EXEMPT_PATTERNS.some((pattern) => filePath.includes(pattern));

package/dist/nerves/review/cli-main.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cli_1 = require("./cli");
+const code = (0, cli_1.runNervesReviewCli)(process.argv.slice(2));
+process.exit(code);

package/dist/nerves/review/cli.js

@@ -0,0 +1,156 @@
+"use strict";
+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.runNervesReviewCli = runNervesReviewCli;
+const path = __importStar(require("node:path"));
+const identity_1 = require("../../heart/identity");
+const core_1 = require("./core");
+function parseArgs(argv) {
+    const args = { process: "daemon", json: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        const next = argv[i + 1];
+        switch (token) {
+            case "--help":
+            case "-h":
+                args.help = true;
+                break;
+            case "--process":
+                if (next)
+                    args.process = next;
+                i++;
+                break;
+            case "--agent":
+                if (next)
+                    args.agent = next;
+                i++;
+                break;
+            case "--component":
+                if (next)
+                    args.componentSubstring = next;
+                i++;
+                break;
+            case "--event":
+                if (next)
+                    args.eventSubstring = next;
+                i++;
+                break;
+            case "--level":
+                if (next)
+                    args.level = next;
+                i++;
+                break;
+            case "--since":
+                if (next)
+                    args.since = next;
+                i++;
+                break;
+            case "--limit":
+                if (next) {
+                    const parsed = Number.parseInt(next, 10);
+                    if (Number.isFinite(parsed) && parsed > 0)
+                        args.limit = parsed;
+                }
+                i++;
+                break;
+            case "--json":
+                args.json = true;
+                break;
+        }
+    }
+    return args;
+}
+function printHelp() {
+    // eslint-disable-next-line no-console -- meta-tooling
+    console.log([
+        "usage: ouro nerves-review [options]",
+        "",
+        "Tail the agent's nerves ndjson and filter recent events. Read-only.",
+        "",
+        "options:",
+        "  --process <name>      log stream to read (default: daemon)",
+        "  --agent <name>        agent bundle to read from (default: current)",
+        "  --component <substr>  filter by component substring (case-insensitive)",
+        "  --event <substr>      filter by event-name substring (case-insensitive)",
+        "  --level <level>       filter by exact level (debug|info|warn|error)",
+        "  --since <duration>    only events newer than e.g. 5m, 2h, 1d",
+        "  --limit <N>           cap returned events (default: 50)",
+        "  --json                output one JSON object per line",
+    ].join("\n"));
+}
+function runNervesReviewCli(argv) {
+    const args = parseArgs(argv);
+    if (args.help) {
+        printHelp();
+        return 0;
+    }
+    let sinceMs;
+    if (args.since) {
+        const parsed = (0, core_1.parseDuration)(args.since);
+        if (parsed === null) {
+            // eslint-disable-next-line no-console -- meta-tooling
+            console.error(`nerves-review: --since '${args.since}' is not a valid duration (e.g. 5m, 2h, 1d)`);
+            return 2;
+        }
+        sinceMs = parsed;
+    }
+    const logsDir = (0, identity_1.getAgentDaemonLogsDir)(args.agent);
+    const filePath = path.join(logsDir, `${args.process}.ndjson`);
+    const filter = {
+        componentSubstring: args.componentSubstring,
+        eventSubstring: args.eventSubstring,
+        level: args.level,
+        sinceMs,
+        limit: args.limit,
+        nowMs: Date.now(),
+    };
+    const entries = (0, core_1.reviewNerveEvents)(filePath, filter);
+    if (entries.length === 0) {
+        // eslint-disable-next-line no-console -- meta-tooling
+        console.log(`(no matching nerves events in ${filePath})`);
+        return 0;
+    }
+    for (const entry of entries) {
+        if (args.json) {
+            // eslint-disable-next-line no-console -- meta-tooling
+            console.log(entry.raw);
+        }
+        else {
+            // eslint-disable-next-line no-console -- meta-tooling
+            console.log((0, core_1.formatNerveEntry)(entry));
+        }
+    }
+    return 0;
+}

package/dist/nerves/review/core.js

@@ -0,0 +1,152 @@
+"use strict";
+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.parseDuration = parseDuration;
+exports.reviewNerveEvents = reviewNerveEvents;
+exports.formatNerveEntry = formatNerveEntry;
+const fs = __importStar(require("node:fs"));
+const DURATION_PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/;
+function parseDuration(value) {
+    const match = DURATION_PATTERN.exec(value.trim().toLowerCase());
+    if (!match)
+        return null;
+    const amount = Number.parseFloat(match[1]);
+    if (!Number.isFinite(amount) || amount < 0)
+        return null;
+    switch (match[2]) {
+        case "ms": return amount;
+        case "s": return amount * 1_000;
+        case "m": return amount * 60_000;
+        case "h": return amount * 3_600_000;
+        case "d": return amount * 86_400_000;
+        /* v8 ignore start -- exhaustive switch over the regex group; unreachable */
+        default: return null;
+        /* v8 ignore stop */
+    }
+}
+function entryTimeMs(parsed) {
+    if (!parsed)
+        return null;
+    const time = parsed.time;
+    if (typeof time === "string") {
+        const ms = Date.parse(time);
+        return Number.isFinite(ms) ? ms : null;
+    }
+    return null;
+}
+function readLastNLines(filePath, maxLines, maxBytes = 8 * 1024 * 1024) {
+    let text;
+    try {
+        const stat = fs.statSync(filePath);
+        if (stat.size > maxBytes) {
+            const fd = fs.openSync(filePath, "r");
+            try {
+                const buf = Buffer.alloc(maxBytes);
+                fs.readSync(fd, buf, 0, maxBytes, stat.size - maxBytes);
+                text = buf.toString("utf-8");
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        else {
+            text = fs.readFileSync(filePath, "utf-8");
+        }
+    }
+    catch {
+        return [];
+    }
+    const lines = text.split("\n").filter((line) => line.length > 0);
+    return lines.slice(-maxLines);
+}
+function reviewNerveEvents(filePath, filter = {}) {
+    const limit = filter.limit ?? 50;
+    const candidateLineCount = Math.max(limit * 4, 200);
+    const lines = readLastNLines(filePath, candidateLineCount);
+    const cutoffMs = filter.sinceMs !== undefined && filter.nowMs !== undefined
+        ? filter.nowMs - filter.sinceMs
+        : null;
+    const matched = [];
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const raw = lines[i];
+        let parsed = null;
+        try {
+            const value = JSON.parse(raw);
+            if (value && typeof value === "object" && !Array.isArray(value)) {
+                parsed = value;
+            }
+        }
+        catch {
+            parsed = null;
+        }
+        if (!parsed)
+            continue;
+        if (filter.componentSubstring) {
+            const component = String(parsed.component ?? "");
+            if (!component.toLowerCase().includes(filter.componentSubstring.toLowerCase()))
+                continue;
+        }
+        if (filter.eventSubstring) {
+            const event = String(parsed.event ?? "");
+            if (!event.toLowerCase().includes(filter.eventSubstring.toLowerCase()))
+                continue;
+        }
+        if (filter.level) {
+            const level = String(parsed.level ?? "info");
+            if (level !== filter.level)
+                continue;
+        }
+        if (cutoffMs !== null) {
+            const eventMs = entryTimeMs(parsed);
+            if (eventMs === null || eventMs < cutoffMs)
+                continue;
+        }
+        matched.push({ raw, parsed });
+        if (matched.length >= limit)
+            break;
+    }
+    return matched.reverse();
+}
+function formatNerveEntry(entry) {
+    const parsed = entry.parsed;
+    if (!parsed)
+        return entry.raw;
+    const time = String(parsed.time ?? "");
+    const level = String(parsed.level ?? "info");
+    const component = String(parsed.component ?? "?");
+    const event = String(parsed.event ?? "?");
+    const message = String(parsed.message ?? "");
+    return `${time} [${level.padEnd(5)}] ${component}/${event} — ${message}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.500",
+  "version": "0.1.0-alpha.501",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",
@@ -37,7 +37,8 @@
     "lint": "eslint src/",
     "release:preflight": "node scripts/release-preflight.cjs",
     "release:smoke": "node scripts/release-smoke.cjs",
-    "audit:nerves": "npm run build && node dist/nerves/coverage/cli-main.js"
+    "audit:nerves": "npm run build && node dist/nerves/coverage/cli-main.js",
+    "nerves:review": "npm run build && node dist/nerves/review/cli-main.js"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",