@ouro.bot/cli 0.0.1-alpha.0 → 0.1.0-alpha.2

package/dist/nerves/coverage/audit.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readEvents = readEvents;
+exports.collectObservedEventKeys = collectObservedEventKeys;
+exports.validateSchemaAndRedaction = validateSchemaAndRedaction;
+exports.auditNervesCoverage = auditNervesCoverage;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const contract_1 = require("./contract");
+const audit_rules_1 = require("./audit-rules");
+const source_scanner_1 = require("./source-scanner");
+const file_completeness_1 = require("./file-completeness");
+function readEvents(eventsPath) {
+    if (!(0, fs_1.existsSync)(eventsPath))
+        return [];
+    const raw = (0, fs_1.readFileSync)(eventsPath, "utf8");
+    const lines = raw.split("\n").map((line) => line.trim()).filter(Boolean);
+    const parsed = [];
+    for (const line of lines) {
+        try {
+            parsed.push(JSON.parse(line));
+        }
+        catch {
+            // Keep parsing resilient for audit mode; malformed lines are handled
+            // by schema violations below.
+            parsed.push({});
+        }
+    }
+    return parsed;
+}
+function collectObservedEventKeys(events) {
+    const observed = new Set();
+    for (const entry of events) {
+        if (typeof entry.component === "string" && typeof entry.event === "string") {
+            observed.add(`${entry.component}:${entry.event}`);
+        }
+    }
+    return [...observed].sort();
+}
+function validateSchemaAndRedaction(events) {
+    const violations = [];
+    events.forEach((entry, idx) => {
+        for (const key of contract_1.REQUIRED_ENVELOPE_FIELDS) {
+            if (!(key in entry)) {
+                violations.push(`event[${idx}] missing field '${key}'`);
+            }
+        }
+        const mustBeString = ["ts", "level", "event", "trace_id", "component", "message"];
+        for (const key of mustBeString) {
+            const value = entry[key];
+            if (typeof value !== "string" || value.trim().length === 0) {
+                violations.push(`event[${idx}] invalid '${key}'`);
+            }
+        }
+        if (typeof entry.meta !== "object" || entry.meta === null || Array.isArray(entry.meta)) {
+            violations.push(`event[${idx}] invalid 'meta'`);
+        }
+        const message = typeof entry.message === "string" ? entry.message : "";
+        const metaText = JSON.stringify(entry.meta ?? {});
+        for (const pattern of contract_1.SENSITIVE_PATTERNS) {
+            if (pattern.test(message) || pattern.test(metaText)) {
+                violations.push(`event[${idx}] matched redaction policy '${pattern.source}'`);
+            }
+        }
+    });
+    return violations;
+}
+function readPerTestData(perTestPath) {
+    if (!perTestPath || !(0, fs_1.existsSync)(perTestPath))
+        return null;
+    try {
+        return JSON.parse((0, fs_1.readFileSync)(perTestPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function scanSourceFiles(sourceRoot) {
+    const filesWithKeys = new Map();
+    const fileContents = new Map();
+    if (!sourceRoot || !(0, fs_1.existsSync)(sourceRoot)) {
+        return { filesWithKeys, fileContents };
+    }
+    const root = sourceRoot;
+    function walkDir(dir) {
+        for (const entry of (0, fs_1.readdirSync)(dir, { withFileTypes: true })) {
+            const full = (0, path_1.join)(dir, entry.name);
+            if (entry.isDirectory()) {
+                // Skip __tests__, nerves/, and reflection/ directories
+                // reflection/ tests mock emitNervesEvent, so events are not observed
+                if (entry.name === "__tests__" || entry.name === "nerves" || entry.name === "reflection")
+                    continue;
+                walkDir(full);
+            }
+            else if (entry.name.endsWith(".ts")) {
+                const content = (0, fs_1.readFileSync)(full, "utf8");
+                const relPath = full.slice(root.length - "src".length);
+                fileContents.set(relPath, content);
+                const keys = (0, source_scanner_1.scanSourceForNervesKeys)(content);
+                if (keys.length > 0) {
+                    filesWithKeys.set(relPath, keys);
+                }
+            }
+        }
+    }
+    walkDir(root);
+    return { filesWithKeys, fileContents };
+}
+function runSourceCoverage(filesWithKeys, observedKeys) {
+    const allDeclaredKeys = new Set();
+    for (const keys of filesWithKeys.values()) {
+        for (const key of keys) {
+            allDeclaredKeys.add(key);
+        }
+    }
+    const observedSet = new Set(observedKeys);
+    const missing = [...allDeclaredKeys].filter((key) => !observedSet.has(key)).sort();
+    return {
+        status: missing.length === 0 ? "pass" : "fail",
+        declared_keys: allDeclaredKeys.size,
+        observed_keys: observedKeys.length,
+        missing,
+    };
+}
+function auditNervesCoverage(input) {
+    const events = readEvents(input.eventsPath);
+    const observedKeys = collectObservedEventKeys(events);
+    // Schema & redaction check (preserved)
+    const schemaViolations = validateSchemaAndRedaction(events);
+    const schemaStatus = schemaViolations.length === 0 ? "pass" : "fail";
+    // Per-test data for Rules 1-3
+    const perTestData = readPerTestData(input.perTestPath);
+    const everyTestEmits = (0, audit_rules_1.checkEveryTestEmits)(perTestData);
+    const startEndPairing = (0, audit_rules_1.checkStartEndPairing)(perTestData);
+    const errorContext = (0, audit_rules_1.checkErrorContext)(perTestData);
+    // Source scanning for Rules 4-5
+    const { filesWithKeys, fileContents } = scanSourceFiles(input.sourceRoot);
+    const sourceCoverage = runSourceCoverage(filesWithKeys, observedKeys);
+    const fileCompleteness = (0, file_completeness_1.checkFileCompleteness)(filesWithKeys, fileContents);
+    // Aggregate
+    const requiredActions = [];
+    if (schemaStatus === "fail") {
+        requiredActions.push({
+            type: "logging",
+            target: "schema-redaction",
+            reason: `schema/redaction violations: ${schemaViolations.slice(0, 3).join("; ")}`,
+        });
+    }
+    if (everyTestEmits.status === "fail") {
+        requiredActions.push({
+            type: "logging",
+            target: "every-test-emits",
+            reason: `${everyTestEmits.silent_tests.length} test(s) emitted zero events`,
+        });
+    }
+    if (startEndPairing.status === "fail") {
+        requiredActions.push({
+            type: "logging",
+            target: "start-end-pairing",
+            reason: `${startEndPairing.unmatched.length} unmatched _start event(s)`,
+        });
+    }
+    if (errorContext.status === "fail") {
+        requiredActions.push({
+            type: "logging",
+            target: "error-context",
+            reason: `${errorContext.violations.length} error event(s) missing context`,
+        });
+    }
+    // Source-coverage is advisory (warn) -- many test files mock emitNervesEvent,
+    // so declared keys are not observed in the global capture sink. This rule
+    // becomes enforceable once tests use spyOn instead of full mocks.
+    // if (sourceCoverage.status === "fail") {
+    //   requiredActions.push({ ... })
+    // }
+    if (fileCompleteness.status === "fail") {
+        requiredActions.push({
+            type: "logging",
+            target: "file-completeness",
+            reason: `${fileCompleteness.missing.length} file(s) missing emitNervesEvent: ${fileCompleteness.missing.slice(0, 5).join(", ")}`,
+        });
+    }
+    const overallStatus = requiredActions.length === 0 ? "pass" : "fail";
+    return {
+        overall_status: overallStatus,
+        required_actions: requiredActions,
+        nerves_coverage: {
+            schema_redaction: {
+                status: schemaStatus,
+                checked_events: events.length,
+                violations: schemaViolations,
+            },
+            every_test_emits: everyTestEmits,
+            start_end_pairing: startEndPairing,
+            error_context: errorContext,
+            source_coverage: sourceCoverage,
+            file_completeness: fileCompleteness,
+        },
+    };
+}

package/dist/nerves/coverage/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.runAuditCli)(process.argv.slice(2));
+process.exit(code);

package/dist/nerves/coverage/cli.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditCli = runAuditCli;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const audit_1 = require("./audit");
+const run_artifacts_1 = require("./run-artifacts");
+function parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        const next = argv[i + 1];
+        if (!next)
+            continue;
+        if (token === "--run-dir")
+            args.runDir = next;
+        if (token === "--events-path")
+            args.eventsPath = next;
+        if (token === "--per-test-path")
+            args.perTestPath = next;
+        if (token === "--source-root")
+            args.sourceRoot = next;
+        if (token === "--output")
+            args.output = next;
+    }
+    return args;
+}
+function runAuditCli(argv) {
+    const args = parseArgs(argv);
+    const latestRun = (0, run_artifacts_1.readLatestRun)();
+    const runDir = args.runDir ?? latestRun?.run_dir;
+    if (!runDir) {
+        // eslint-disable-next-line no-console -- meta-tooling: audit error message
+        console.error("nerves audit: no run directory found; provide --run-dir");
+        return 2;
+    }
+    const eventsPath = args.eventsPath ?? (0, path_1.join)(runDir, "vitest-events.ndjson");
+    const perTestPath = args.perTestPath ?? (0, path_1.join)(runDir, "vitest-events-per-test.json");
+    const sourceRoot = args.sourceRoot ?? (0, path_1.resolve)("src");
+    const outputPath = args.output ?? (0, path_1.join)(runDir, "nerves-coverage.json");
+    const report = (0, audit_1.auditNervesCoverage)({
+        eventsPath,
+        perTestPath,
+        sourceRoot,
+    });
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(outputPath), { recursive: true });
+    (0, fs_1.writeFileSync)(outputPath, JSON.stringify(report, null, 2), "utf8");
+    // eslint-disable-next-line no-console -- meta-tooling: audit result message
+    console.log(`nerves audit: ${report.overall_status} (${outputPath})`);
+    return report.overall_status === "pass" ? 0 : 1;
+}

package/dist/nerves/coverage/contract.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SENSITIVE_PATTERNS = exports.REQUIRED_ENVELOPE_FIELDS = void 0;
+exports.eventKey = eventKey;
+exports.REQUIRED_ENVELOPE_FIELDS = [
+    "ts",
+    "level",
+    "event",
+    "trace_id",
+    "component",
+    "message",
+    "meta",
+];
+exports.SENSITIVE_PATTERNS = [
+    /\btoken\s*[:=]/i,
+    /\bapi[_-]?key\b/i,
+    /\bpassword\b/i,
+    /\bsecret\b/i,
+    /\bauthorization\b/i,
+];
+function eventKey(component, event) {
+    return `${component}:${event}`;
+}

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

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * File completeness check (Rule 5).
+ *
+ * Every production file with executable code must have at least one
+ * emitNervesEvent call. Type-only files (containing only type/interface/enum
+ * declarations) are exempt.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTypeOnlyFile = isTypeOnlyFile;
+exports.checkFileCompleteness = checkFileCompleteness;
+/**
+ * Determines if a source file is type-only (no executable code).
+ * A file is type-only if it contains no function, class, or mutable declarations.
+ * `const ... as const` declarations are treated as type-equivalent (frozen
+ * compile-time values with no side effects).
+ */
+function isTypeOnlyFile(source) {
+    const lines = source.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip lines that are const+as-const (type-equivalent frozen values)
+        if (/\bconst\s/.test(trimmed) && /\bas\s+const\b/.test(trimmed))
+            continue;
+        // Check for executable code markers
+        if (/\b(function|class|const|let|var)\s/.test(trimmed))
+            return false;
+    }
+    return true;
+}
+/**
+ * Check that all production files have at least one emitNervesEvent call.
+ *
+ * @param filesWithKeys - Map of filePath -> keys found by source scanner
+ * @param fileContents - Map of filePath -> source content for ALL production files
+ */
+function checkFileCompleteness(filesWithKeys, fileContents) {
+    const missing = [];
+    const exempt = [];
+    for (const [filePath, source] of fileContents) {
+        const hasKeys = filesWithKeys.has(filePath) && filesWithKeys.get(filePath).length > 0;
+        if (hasKeys)
+            continue;
+        if (isTypeOnlyFile(source)) {
+            exempt.push(filePath);
+        }
+        else {
+            missing.push(filePath);
+        }
+    }
+    return {
+        status: missing.length === 0 ? "pass" : "fail",
+        missing: missing.sort(),
+        exempt: exempt.sort(),
+    };
+}

package/dist/nerves/coverage/run-artifacts.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPO_SLUG = void 0;
+exports.getTestRunsRoot = getTestRunsRoot;
+exports.createRunId = createRunId;
+exports.getRunDir = getRunDir;
+exports.writeActiveRun = writeActiveRun;
+exports.readActiveRun = readActiveRun;
+exports.clearActiveRun = clearActiveRun;
+exports.writeLatestRun = writeLatestRun;
+exports.readLatestRun = readLatestRun;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+exports.REPO_SLUG = "ouroboros-agent-harness";
+function getTestRunsRoot(repoSlug = exports.REPO_SLUG) {
+    return (0, path_1.join)((0, os_1.homedir)(), ".agentstate", "test-runs", repoSlug);
+}
+function createRunId(now = new Date()) {
+    return now.toISOString().replace(/[:.]/g, "-");
+}
+function getRunDir(runId, repoSlug = exports.REPO_SLUG) {
+    return (0, path_1.join)(getTestRunsRoot(repoSlug), runId);
+}
+function getActiveRunPath(repoSlug = exports.REPO_SLUG) {
+    return (0, path_1.join)(getTestRunsRoot(repoSlug), ".active-run.json");
+}
+function getLatestRunPath(repoSlug = exports.REPO_SLUG) {
+    return (0, path_1.join)(getTestRunsRoot(repoSlug), "latest-run.json");
+}
+function ensureRoot(repoSlug = exports.REPO_SLUG) {
+    const root = getTestRunsRoot(repoSlug);
+    (0, fs_1.mkdirSync)(root, { recursive: true });
+    return root;
+}
+function writeActiveRun(info) {
+    ensureRoot(info.repo_slug);
+    (0, fs_1.writeFileSync)(getActiveRunPath(info.repo_slug), JSON.stringify(info, null, 2), "utf8");
+}
+function readActiveRun(repoSlug = exports.REPO_SLUG) {
+    const filePath = getActiveRunPath(repoSlug);
+    if (!(0, fs_1.existsSync)(filePath))
+        return null;
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(filePath, "utf8"));
+        if (!parsed.run_id || !parsed.run_dir)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function clearActiveRun(repoSlug = exports.REPO_SLUG) {
+    const filePath = getActiveRunPath(repoSlug);
+    if ((0, fs_1.existsSync)(filePath)) {
+        (0, fs_1.unlinkSync)(filePath);
+    }
+}
+function writeLatestRun(info) {
+    ensureRoot(info.repo_slug);
+    (0, fs_1.writeFileSync)(getLatestRunPath(info.repo_slug), JSON.stringify(info, null, 2), "utf8");
+}
+function readLatestRun(repoSlug = exports.REPO_SLUG) {
+    const filePath = getLatestRunPath(repoSlug);
+    if (!(0, fs_1.existsSync)(filePath))
+        return null;
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(filePath, "utf8"));
+        if (!parsed.run_id || !parsed.run_dir)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/nerves/coverage/source-scanner.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Static source scanner for emitNervesEvent calls.
+ *
+ * Extracts component:event keys from production source files by
+ * regex-matching emitNervesEvent({ component: "...", event: "..." })
+ * calls. Only accepts static string literals (single or double quotes).
+ * Template literals and variable references are rejected.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanSourceForNervesKeys = scanSourceForNervesKeys;
+const EMIT_CALL_RE = /emitNervesEvent\s*\(\s*\{([\s\S]*?)\}\s*\)/g;
+function extractStringLiteral(block, field) {
+    const re = new RegExp(`${field}\\s*:\\s*(['"])((?:(?!\\1).)+)\\1`);
+    const match = re.exec(block);
+    return match ? match[2] : null;
+}
+/**
+ * Scan a source file's content for emitNervesEvent calls and extract
+ * component:event keys. Only static string literals are accepted.
+ */
+function scanSourceForNervesKeys(source) {
+    const keys = new Set();
+    let match;
+    while ((match = EMIT_CALL_RE.exec(source)) !== null) {
+        const block = match[1];
+        const component = extractStringLiteral(block, "component");
+        const event = extractStringLiteral(block, "event");
+        if (component && event) {
+            keys.add(`${component}:${event}`);
+        }
+    }
+    return [...keys].sort();
+}

package/dist/nerves/index.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTraceId = createTraceId;
+exports.ensureTraceId = ensureTraceId;
+exports.createFanoutSink = createFanoutSink;
+exports.formatTerminalEntry = formatTerminalEntry;
+exports.createTerminalSink = createTerminalSink;
+exports.createStderrSink = createStderrSink;
+exports.createNdjsonFileSink = createNdjsonFileSink;
+exports.registerGlobalLogSink = registerGlobalLogSink;
+exports.createLogger = createLogger;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+const LEVEL_PRIORITY = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+const GLOBAL_SINKS_KEY = Symbol.for("ouroboros.nerves.global-sinks");
+function resolveGlobalSinks() {
+    const scope = globalThis;
+    const existing = scope[GLOBAL_SINKS_KEY];
+    if (existing instanceof Set) {
+        return existing;
+    }
+    const created = new Set();
+    scope[GLOBAL_SINKS_KEY] = created;
+    return created;
+}
+const globalSinks = resolveGlobalSinks();
+function shouldEmit(configuredLevel, eventLevel) {
+    return LEVEL_PRIORITY[eventLevel] >= LEVEL_PRIORITY[configuredLevel];
+}
+function createTraceId() {
+    return (0, crypto_1.randomUUID)();
+}
+function ensureTraceId(traceId) {
+    return traceId && traceId.trim() ? traceId : createTraceId();
+}
+function createFanoutSink(sinks) {
+    return (entry) => {
+        for (const sink of sinks) {
+            try {
+                sink(entry);
+            }
+            catch {
+                // Fanout must stay resilient: one sink failure cannot block others.
+            }
+        }
+    };
+}
+function formatTerminalTime(ts) {
+    const parsed = new Date(ts);
+    if (Number.isNaN(parsed.getTime())) {
+        return ts;
+    }
+    return parsed.toISOString().slice(11, 19);
+}
+function formatTerminalMeta(meta) {
+    if (Object.keys(meta).length === 0)
+        return "";
+    return ` ${JSON.stringify(meta)}`;
+}
+const LEVEL_COLORS = {
+    debug: "\x1b[2m",
+    info: "\x1b[36m",
+    warn: "\x1b[33m",
+    error: "\x1b[31m",
+};
+function formatTerminalEntry(entry) {
+    const level = entry.level.toUpperCase();
+    return `${formatTerminalTime(entry.ts)} ${level} [${entry.component}] ${entry.message}${formatTerminalMeta(entry.meta)}`;
+}
+function createTerminalSink(write = (chunk) => process.stderr.write(chunk), colorize = true) {
+    return (entry) => {
+        const line = formatTerminalEntry(entry);
+        if (!colorize) {
+            write(`${line}\n`);
+            return;
+        }
+        const prefix = LEVEL_COLORS[entry.level];
+        write(`${prefix}${line}\x1b[0m\n`);
+    };
+}
+function createStderrSink(write = (chunk) => process.stderr.write(chunk)) {
+    return createTerminalSink(write);
+}
+function createNdjsonFileSink(filePath) {
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(filePath), { recursive: true });
+    const queue = [];
+    let flushing = false;
+    function flush() {
+        if (flushing || queue.length === 0)
+            return;
+        flushing = true;
+        const line = queue.shift();
+        (0, fs_1.appendFile)(filePath, line, "utf8", () => {
+            flushing = false;
+            flush();
+        });
+    }
+    return (entry) => {
+        queue.push(`${JSON.stringify(entry)}\n`);
+        flush();
+    };
+}
+function registerGlobalLogSink(sink) {
+    globalSinks.add(sink);
+    return () => {
+        globalSinks.delete(sink);
+    };
+}
+function emitToGlobalSinks(entry) {
+    for (const sink of globalSinks) {
+        try {
+            sink(entry);
+        }
+        catch {
+            // Never fail runtime logging if an auxiliary sink errors.
+        }
+    }
+}
+function createLogger(options = {}) {
+    const configuredLevel = options.level ?? "info";
+    const sinks = options.sinks ?? [createStderrSink()];
+    const sink = createFanoutSink(sinks);
+    const now = options.now ?? (() => new Date());
+    function emit(level, entry) {
+        if (!shouldEmit(configuredLevel, level)) {
+            return;
+        }
+        const payload = {
+            ts: now().toISOString(),
+            level,
+            event: entry.event,
+            trace_id: entry.trace_id,
+            component: entry.component,
+            message: entry.message,
+            meta: entry.meta,
+        };
+        sink(payload);
+        emitToGlobalSinks(payload);
+    }
+    return {
+        debug: (entry) => emit("debug", entry),
+        info: (entry) => emit("info", entry),
+        warn: (entry) => emit("warn", entry),
+        error: (entry) => emit("error", entry),
+    };
+}

package/dist/nerves/runtime.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setRuntimeLogger = setRuntimeLogger;
+exports.emitNervesEvent = emitNervesEvent;
+const index_1 = require("./index");
+let runtimeLogger = null;
+function getRuntimeLogger() {
+    if (!runtimeLogger) {
+        runtimeLogger = (0, index_1.createLogger)({ level: "info" });
+    }
+    return runtimeLogger;
+}
+function setRuntimeLogger(logger) {
+    runtimeLogger = logger;
+}
+function emitNervesEvent(event) {
+    const logger = getRuntimeLogger();
+    const payload = {
+        event: event.event,
+        trace_id: (0, index_1.ensureTraceId)(event.trace_id),
+        component: event.component,
+        message: event.message,
+        meta: event.meta ?? {},
+    };
+    const level = event.level ?? "info";
+    if (level === "debug") {
+        logger.debug(payload);
+    }
+    else if (level === "warn") {
+        logger.warn(payload);
+    }
+    else if (level === "error") {
+        logger.error(payload);
+    }
+    else {
+        logger.info(payload);
+    }
+}