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

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,46 @@
+"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 const declarations.
+ */
+function isTypeOnlyFile(source) {
+    // Look for executable code markers: function, class, const/let/var declarations
+    const executablePattern = /\b(function|class|const|let|var)\s/;
+    return !executablePattern.test(source);
+}
+/**
+ * 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);
+    }
+}

package/dist/repertoire/ado-client.js

@@ -0,0 +1,211 @@
+"use strict";
+// Azure DevOps API client.
+// Provides a generic adoRequest() for arbitrary endpoints
+// and a thin queryWorkItems() wrapper for backward compatibility.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adoRequest = adoRequest;
+exports.queryWorkItems = queryWorkItems;
+exports.discoverOrganizations = discoverOrganizations;
+exports.discoverProjects = discoverProjects;
+const api_error_1 = require("../heart/api-error");
+const runtime_1 = require("../nerves/runtime");
+const ADO_BASE = "https://dev.azure.com";
+const VSSPS_BASE = "https://app.vssps.visualstudio.com";
+const DEFAULT_API_VERSION = "api-version=7.1";
+// Append api-version=7.1 to the URL if not already present.
+function ensureApiVersion(path) {
+    if (path.includes("api-version="))
+        return path;
+    return path.includes("?") ? `${path}&${DEFAULT_API_VERSION}` : `${path}?${DEFAULT_API_VERSION}`;
+}
+// Determine correct Content-Type for ADO requests.
+function resolveContentType(method, path) {
+    const upper = method.toUpperCase();
+    const isWorkItemMutation = (upper === "POST" || upper === "PATCH") &&
+        path.toLowerCase().includes("/_apis/wit/workitems/");
+    return isWorkItemMutation
+        ? "application/json-patch+json"
+        : "application/json";
+}
+// Generic ADO API request. Returns response body as pretty-printed JSON string.
+async function adoRequest(token, method, org, path, body) {
+    try {
+        (0, runtime_1.emitNervesEvent)({
+            event: "client.request_start",
+            component: "clients",
+            message: "starting ADO request",
+            meta: { client: "ado", method, org, path },
+        });
+        const fullPath = ensureApiVersion(path);
+        const url = `${ADO_BASE}/${org}${fullPath}`;
+        const contentType = resolveContentType(method, path);
+        const opts = {
+            method,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": contentType,
+            },
+        };
+        if (body)
+            opts.body = body;
+        const res = await fetch(url, opts);
+        if (!res.ok) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                event: "client.error",
+                component: "clients",
+                message: "ADO request failed",
+                meta: { client: "ado", method, org, path, status: res.status },
+            });
+            return (0, api_error_1.handleApiError)(res, "ADO", "ado");
+        }
+        const data = await res.json();
+        (0, runtime_1.emitNervesEvent)({
+            event: "client.request_end",
+            component: "clients",
+            message: "ADO request completed",
+            meta: { client: "ado", method, org, path, success: true },
+        });
+        return JSON.stringify(data, null, 2);
+    }
+    catch (err) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            event: "client.error",
+            component: "clients",
+            message: "ADO request threw exception",
+            meta: {
+                client: "ado",
+                method,
+                org,
+                path,
+                reason: err instanceof Error ? err.message : String(err),
+            },
+        });
+        return (0, api_error_1.handleApiError)(err, "ADO", "ado");
+    }
+}
+// Backward-compatible thin wrapper: runs WIQL query and returns formatted work items.
+async function queryWorkItems(token, org, query) {
+    try {
+        (0, runtime_1.emitNervesEvent)({
+            event: "client.request_start",
+            component: "clients",
+            message: "starting ADO work item query",
+            meta: { client: "ado", org, operation: "queryWorkItems" },
+        });
+        // Step 1: Run WIQL query to get work item IDs
+        const wiqlRes = await fetch(`${ADO_BASE}/${org}/_apis/wit/wiql?${DEFAULT_API_VERSION}`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ query }),
+        });
+        if (!wiqlRes.ok) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                event: "client.error",
+                component: "clients",
+                message: "ADO WIQL query failed",
+                meta: { client: "ado", org, operation: "queryWorkItems", stage: "wiql", status: wiqlRes.status },
+            });
+            return (0, api_error_1.handleApiError)(wiqlRes, "ADO", "ado");
+        }
+        const wiqlData = (await wiqlRes.json());
+        if (!wiqlData.workItems || wiqlData.workItems.length === 0) {
+            (0, runtime_1.emitNervesEvent)({
+                event: "client.request_end",
+                component: "clients",
+                message: "ADO work item query returned no results",
+                meta: { client: "ado", org, operation: "queryWorkItems", count: 0 },
+            });
+            return "No work items found matching the query.";
+        }
+        // Step 2: Fetch work item details (batch, max 200)
+        const ids = wiqlData.workItems.slice(0, 200).map((wi) => wi.id);
+        const detailRes = await fetch(`${ADO_BASE}/${org}/_apis/wit/workitems?ids=${ids.join(",")}&${DEFAULT_API_VERSION}`, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+            },
+        });
+        if (!detailRes.ok) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                event: "client.error",
+                component: "clients",
+                message: "ADO work item details fetch failed",
+                meta: { client: "ado", org, operation: "queryWorkItems", stage: "details", status: detailRes.status },
+            });
+            return (0, api_error_1.handleApiError)(detailRes, "ADO", "ado");
+        }
+        const detailData = (await detailRes.json());
+        // Format results
+        const lines = detailData.value.map((wi) => {
+            const assignedTo = wi.fields["System.AssignedTo"]?.displayName || "Unassigned";
+            return `#${wi.id}: ${wi.fields["System.Title"]} [${wi.fields["System.State"]}] (${assignedTo})`;
+        });
+        (0, runtime_1.emitNervesEvent)({
+            event: "client.request_end",
+            component: "clients",
+            message: "ADO work item query completed",
+            meta: { client: "ado", org, operation: "queryWorkItems", count: lines.length },
+        });
+        return lines.join("\n");
+    }
+    catch (err) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            event: "client.error",
+            component: "clients",
+            message: "ADO work item query threw exception",
+            meta: {
+                client: "ado",
+                org,
+                operation: "queryWorkItems",
+                reason: err instanceof Error ? err.message : String(err),
+            },
+        });
+        return (0, api_error_1.handleApiError)(err, "ADO", "ado");
+    }
+}
+// Discover ADO organizations accessible by the authenticated user.
+// 1. Fetches user profile to get publicAlias (member ID)
+// 2. Uses Accounts API to list organizations for that member
+// Throws on API errors (callers handle error presentation).
+async function discoverOrganizations(token) {
+    // Step 1: Get the user's publicAlias from their profile
+    const profileRes = await fetch(`${VSSPS_BASE}/_apis/profile/profiles/me?${DEFAULT_API_VERSION}`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!profileRes.ok) {
+        throw new Error(`ADO profile request failed: ${profileRes.status} ${profileRes.statusText}`);
+    }
+    const profile = (await profileRes.json());
+    const memberId = profile.publicAlias;
+    if (!memberId) {
+        throw new Error("ADO profile response missing publicAlias");
+    }
+    // Step 2: List organizations for this member
+    const accountsRes = await fetch(`${VSSPS_BASE}/_apis/accounts?memberId=${memberId}&${DEFAULT_API_VERSION}`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!accountsRes.ok) {
+        throw new Error(`ADO accounts request failed: ${accountsRes.status} ${accountsRes.statusText}`);
+    }
+    const data = (await accountsRes.json());
+    return (data.value ?? []).map((a) => a.accountName);
+}
+// Discover projects within an ADO organization.
+// Throws on API errors (callers handle error presentation).
+async function discoverProjects(token, org) {
+    const res = await fetch(`${ADO_BASE}/${org}/_apis/projects?${DEFAULT_API_VERSION}`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+        throw new Error(`ADO projects request failed: ${res.status} ${res.statusText}`);
+    }
+    const data = (await res.json());
+    return (data.value ?? []).map((p) => p.name);
+}