@aaac/observability 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,425 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_DB_PATH,
+  SqliteQueryAdapter,
+  createPipeline,
+  generateId,
+  isoToUnixNano
+} from "../chunk-FVFGVBXM.js";
+
+// src/cli/index.ts
+import { readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+
+// src/generated/program.ts
+import { Command } from "commander";
+
+// src/generated/contract.ts
+var CONTRACT_YAML = `# yaml-language-server: $schema=./node_modules/cli-contracts/schemas/cli-contract.schema.json
+cli_contracts: 0.1.0
+
+info:
+  title: AaaC Observability CLI
+  version: 0.1.0
+  description: aaac-observ \u2014 external event registration and query for @aaac/observability
+
+command_sets:
+  aaac-observ:
+    summary: aaac-observ \u2014 register external events and query the observability store
+    executable: aaac-observ
+    commands:
+      record:
+        summary: Register an external event into the observability pipeline (thin entrypoint for EventCollector.registerExternalEvent)
+        options:
+          - name: event-type
+            aliases: [t]
+            schema: { type: string }
+            description: "Event type (e.g. promotion.commit, process.edit, agent.session)"
+          - name: lifecycle
+            aliases: [l]
+            schema:
+              type: string
+              enum: [open, close, event, instant]
+            description: "Event lifecycle phase: open | close | event | instant"
+          - name: span-id
+            aliases: [s]
+            schema: { type: string }
+            description: Span ID (auto-generated if omitted)
+          - name: parent-span-id
+            schema: { type: string }
+            description: Parent span ID for hierarchy
+          - name: session-id
+            schema: { type: string }
+            description: Session ID to associate with the event
+          - name: trace-id
+            schema: { type: string }
+            description: Trace ID for distributed tracing
+          - name: source
+            schema: { type: string }
+            description: "Event source identifier (default: external)"
+          - name: attr
+            schema:
+              type: array
+              items: { type: string }
+            description: "Attribute as key=value (repeatable, e.g. --attr git.commit=abc123)"
+          - name: link
+            schema:
+              type: array
+              items: { type: string }
+            description: "Cross-axis link as targetSpanId:linkType[:targetTraceId] (repeatable)"
+          - name: db
+            schema: { type: string }
+            description: Path to observability SQLite database (overrides default)
+        exits:
+          '0':
+            description: Event registered successfully
+            stdout:
+              format: json
+              schema:
+                type: object
+                properties:
+                  eventId:
+                    type: string
+                  spanId:
+                    type: string
+          '1':
+            description: Registration failed (validation error or write error)
+            stderr:
+              format: text
+
+      query:
+        summary: Query the observability store via QueryAdapter
+        options:
+          - name: kind
+            aliases: [k]
+            schema:
+              type: string
+              enum: [trace, span, search, links]
+            description: "Query kind: trace | span | search | links"
+          - name: trace-id
+            schema: { type: string }
+            description: Trace ID for trace queries (--kind trace)
+          - name: span-id
+            aliases: [s]
+            schema: { type: string }
+            description: Span ID for span/links queries (--kind span or --kind links)
+          - name: event-type
+            schema: { type: string }
+            description: Event type filter for search queries (--kind search)
+          - name: task-id
+            schema: { type: string }
+            description: Task ID filter for search queries (--kind search)
+          - name: from
+            schema: { type: string }
+            description: Start time in ISO 8601 format for search queries (--kind search)
+          - name: to
+            schema: { type: string }
+            description: End time in ISO 8601 format for search queries (--kind search)
+          - name: direction
+            aliases: [d]
+            schema:
+              type: string
+              enum: [forward, reverse, both]
+            description: "Link traversal direction for links queries (default: both)"
+          - name: db
+            schema: { type: string }
+            description: Path to observability SQLite database (overrides default)
+        exits:
+          '0':
+            description: Query succeeded \u2014 results as JSON array
+            stdout:
+              format: json
+              schema:
+                type: object
+          '1':
+            description: Query failed
+            stderr:
+              format: text
+`;
+var CONTRACT_JSON_STR = '{\n  "cli_contracts": "0.1.0",\n  "info": {\n    "title": "AaaC Observability CLI",\n    "version": "0.1.0",\n    "description": "aaac-observ \u2014 external event registration and query for @aaac/observability"\n  },\n  "command_sets": {\n    "aaac-observ": {\n      "summary": "aaac-observ \u2014 register external events and query the observability store",\n      "executable": "aaac-observ",\n      "commands": {\n        "record": {\n          "summary": "Register an external event into the observability pipeline (thin entrypoint for EventCollector.registerExternalEvent)",\n          "options": [\n            {\n              "name": "event-type",\n              "aliases": [\n                "t"\n              ],\n              "schema": {\n                "type": "string"\n              },\n              "description": "Event type (e.g. promotion.commit, process.edit, agent.session)"\n            },\n            {\n              "name": "lifecycle",\n              "aliases": [\n                "l"\n              ],\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "open",\n                  "close",\n                  "event",\n                  "instant"\n                ]\n              },\n              "description": "Event lifecycle phase: open | close | event | instant"\n            },\n            {\n              "name": "span-id",\n              "aliases": [\n                "s"\n              ],\n              "schema": {\n                "type": "string"\n              },\n              "description": "Span ID (auto-generated if omitted)"\n            },\n            {\n              "name": "parent-span-id",\n              "schema": {\n                "type": "string"\n              },\n              "description": "Parent span ID for hierarchy"\n            },\n            {\n              "name": "session-id",\n              "schema": {\n                "type": "string"\n              },\n              "description": "Session ID to associate with the event"\n            },\n            {\n              "name": "trace-id",\n              "schema": {\n                "type": "string"\n              },\n              "description": "Trace ID for distributed tracing"\n            },\n            {\n              "name": "source",\n              "schema": {\n                "type": "string"\n              },\n              "description": "Event source identifier (default: external)"\n            },\n            {\n              "name": "attr",\n              "schema": {\n                "type": "array",\n                "items": {\n                  "type": "string"\n                }\n              },\n              "description": "Attribute as key=value (repeatable, e.g. --attr git.commit=abc123)"\n            },\n            {\n              "name": "link",\n              "schema": {\n                "type": "array",\n                "items": {\n                  "type": "string"\n                }\n              },\n              "description": "Cross-axis link as targetSpanId:linkType[:targetTraceId] (repeatable)"\n            },\n            {\n              "name": "db",\n              "schema": {\n                "type": "string"\n              },\n              "description": "Path to observability SQLite database (overrides default)"\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Event registered successfully",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "type": "object",\n                  "properties": {\n                    "eventId": {\n                      "type": "string"\n                    },\n                    "spanId": {\n                      "type": "string"\n                    }\n                  }\n                }\n              }\n            },\n            "1": {\n              "description": "Registration failed (validation error or write error)",\n              "stderr": {\n                "format": "text"\n              }\n            }\n          }\n        },\n        "query": {\n          "summary": "Query the observability store via QueryAdapter",\n          "options": [\n            {\n              "name": "kind",\n              "aliases": [\n                "k"\n              ],\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "trace",\n                  "span",\n                  "search",\n                  "links"\n                ]\n              },\n              "description": "Query kind: trace | span | search | links"\n            },\n            {\n              "name": "trace-id",\n              "schema": {\n                "type": "string"\n              },\n              "description": "Trace ID for trace queries (--kind trace)"\n            },\n            {\n              "name": "span-id",\n              "aliases": [\n                "s"\n              ],\n              "schema": {\n                "type": "string"\n              },\n              "description": "Span ID for span/links queries (--kind span or --kind links)"\n            },\n            {\n              "name": "event-type",\n              "schema": {\n                "type": "string"\n              },\n              "description": "Event type filter for search queries (--kind search)"\n            },\n            {\n              "name": "task-id",\n              "schema": {\n                "type": "string"\n              },\n              "description": "Task ID filter for search queries (--kind search)"\n            },\n            {\n              "name": "from",\n              "schema": {\n                "type": "string"\n              },\n              "description": "Start time in ISO 8601 format for search queries (--kind search)"\n            },\n            {\n              "name": "to",\n              "schema": {\n                "type": "string"\n              },\n              "description": "End time in ISO 8601 format for search queries (--kind search)"\n            },\n            {\n              "name": "direction",\n              "aliases": [\n                "d"\n              ],\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "forward",\n                  "reverse",\n                  "both"\n                ]\n              },\n              "description": "Link traversal direction for links queries (default: both)"\n            },\n            {\n              "name": "db",\n              "schema": {\n                "type": "string"\n              },\n              "description": "Path to observability SQLite database (overrides default)"\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Query succeeded \u2014 results as JSON array",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "type": "object"\n                }\n              }\n            },\n            "1": {\n              "description": "Query failed",\n              "stderr": {\n                "format": "text"\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}';
+
+// src/generated/program.ts
+function createProgram(handlers2, version) {
+  const program2 = new Command();
+  program2.name("aaac-observ").version(version, "-V, --version").description("aaac-observ \u2014 register external events and query the observability store");
+  program2.command("record").description("Register an external event into the observability pipeline (thin entrypoint for EventCollector.registerExternalEvent)").option("-t, --event-type <value>", "Event type (e.g. promotion.commit, process.edit, agent.session)").option("-l, --lifecycle <value>", "Event lifecycle phase: open | close | event | instant").option("-s, --span-id <value>", "Span ID (auto-generated if omitted)").option("--parent-span-id <value>", "Parent span ID for hierarchy").option("--session-id <value>", "Session ID to associate with the event").option("--trace-id <value>", "Trace ID for distributed tracing").option("--source <value>", "Event source identifier (default: external)").option("--attr <value>", "Attribute as key=value (repeatable, e.g. --attr git.commit=abc123)").option("--link <value>", "Cross-axis link as targetSpanId:linkType[:targetTraceId] (repeatable)").option("--db <value>", "Path to observability SQLite database (overrides default)").action(async (opts, cmd) => {
+    await handlers2.record(opts, cmd.optsWithGlobals());
+  });
+  program2.command("query").description("Query the observability store via QueryAdapter").option("-k, --kind <value>", "Query kind: trace | span | search | links").option("--trace-id <value>", "Trace ID for trace queries (--kind trace)").option("-s, --span-id <value>", "Span ID for span/links queries (--kind span or --kind links)").option("--event-type <value>", "Event type filter for search queries (--kind search)").option("--task-id <value>", "Task ID filter for search queries (--kind search)").option("--from <value>", "Start time in ISO 8601 format for search queries (--kind search)").option("--to <value>", "End time in ISO 8601 format for search queries (--kind search)").option("-d, --direction <value>", "Link traversal direction for links queries (default: both)").option("--db <value>", "Path to observability SQLite database (overrides default)").action(async (opts, cmd) => {
+    await handlers2.query(opts, cmd.optsWithGlobals());
+  });
+  program2.command("extract").description("Extract contract specification for this CLI tool.").argument("[commands...]", "Command IDs to extract. Use dot notation.").option("-a, --all", "Extract all commands.", false).option("--include-meta", "Include extraction metadata.", true).option("-F, --format <format>", "Output format (yaml or json).", "yaml").action(async (commands, opts, cmd) => {
+    if (commands.length === 0 && !opts.all) {
+      process.stderr.write(JSON.stringify({ code: "INVALID_ARGS", message: "Specify command IDs or use --all" }) + "\n");
+      process.exit(2);
+    }
+    const format = opts.format || "yaml";
+    const doc = JSON.parse(CONTRACT_JSON_STR);
+    const cmdIds = opts.all ? [] : commands;
+    if (cmdIds.length === 0) {
+      if (format === "json") {
+        const out = {};
+        if (opts.includeMeta) {
+          out._meta = {
+            source: "embedded",
+            type: "cli-contracts/extract",
+            extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            specVersion: doc.cli_contracts ?? "0.1.0",
+            commands: ["aaac-observ.record", "aaac-observ.query"]
+          };
+        }
+        Object.assign(out, doc);
+        process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+      } else {
+        const yamlLines = [];
+        yamlLines.push("# aaac-observ extract");
+        yamlLines.push("# source: embedded");
+        yamlLines.push("# type: cli-contracts/command-extract");
+        if (opts.includeMeta) {
+          yamlLines.push("---");
+          yamlLines.push("source: embedded");
+          yamlLines.push("type: cli-contracts/command-extract");
+          yamlLines.push("extractedAt: " + (/* @__PURE__ */ new Date()).toISOString());
+          yamlLines.push("spec_version: " + (doc.cli_contracts ?? "0.1.0"));
+          yamlLines.push("commands:");
+          for (const id of ["aaac-observ.record", "aaac-observ.query"]) {
+            yamlLines.push("  - " + id);
+          }
+        }
+        yamlLines.push("---");
+        yamlLines.push(CONTRACT_YAML);
+        process.stdout.write(yamlLines.join("\n") + "\n");
+      }
+    } else {
+      const filtered = {
+        cli_contracts: doc.cli_contracts,
+        info: doc.info,
+        command_sets: {}
+      };
+      const fcs = filtered.command_sets;
+      for (const [setId, cs] of Object.entries(doc.command_sets ?? {})) {
+        const cmds = cs.commands;
+        if (!cmds) continue;
+        const matched = {};
+        for (const [cmdId, cmdDef] of Object.entries(cmds)) {
+          const fullId = setId + "." + cmdId;
+          if (cmdIds.some((id) => id === cmdId || id === fullId || cmdId.startsWith(id + "."))) {
+            matched[cmdId] = cmdDef;
+          }
+        }
+        if (Object.keys(matched).length > 0) {
+          const setCopy = { ...cs };
+          setCopy.commands = matched;
+          fcs[setId] = setCopy;
+        }
+      }
+      if (doc.components) filtered.components = doc.components;
+      process.stdout.write(JSON.stringify(filtered, null, 2) + "\n");
+    }
+    process.exit(0);
+  });
+  return program2;
+}
+
+// src/cli/record.ts
+function parseAttr(attrStr) {
+  if (!attrStr) return {};
+  const trimmed = attrStr.trim();
+  if (trimmed.startsWith("{")) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+    }
+  }
+  const result = {};
+  for (const pair of trimmed.split(",")) {
+    const eqIdx = pair.indexOf("=");
+    if (eqIdx > 0) {
+      const key = pair.slice(0, eqIdx).trim();
+      const val = pair.slice(eqIdx + 1).trim();
+      result[key] = val;
+    }
+  }
+  return result;
+}
+function parseLinks(linkStr) {
+  if (!linkStr) return [];
+  const links = [];
+  for (const item of linkStr.split(",")) {
+    const parts = item.trim().split(":");
+    if (parts.length >= 2) {
+      const targetSpanId = parts[0].trim();
+      const linkType = parts[1].trim();
+      const targetTraceId = parts[2]?.trim() || void 0;
+      if (targetSpanId && linkType) {
+        links.push({ targetSpanId, linkType, targetTraceId });
+      }
+    }
+  }
+  return links;
+}
+async function handleRecord(options, _parentOpts) {
+  if (!options.eventType) {
+    process.stderr.write("Error: --event-type (-t) is required\n");
+    process.exit(1);
+  }
+  const validLifecycles = ["open", "close", "event", "instant"];
+  if (!options.lifecycle) {
+    process.stderr.write(
+      `Error: --lifecycle (-l) is required (${validLifecycles.join("|")})
+`
+    );
+    process.exit(1);
+  }
+  if (!validLifecycles.includes(options.lifecycle)) {
+    process.stderr.write(
+      `Error: --lifecycle must be one of: ${validLifecycles.join("|")}
+`
+    );
+    process.exit(1);
+  }
+  const dbPath = options.db ?? DEFAULT_DB_PATH;
+  const spanId = options.spanId ?? generateId();
+  const attributes = parseAttr(options.attr);
+  const links = parseLinks(options.link);
+  if (options.sessionId) {
+    attributes["session_id"] = options.sessionId;
+  }
+  if (options.traceId) {
+    attributes["trace_id"] = options.traceId;
+  }
+  let capturedEventId;
+  const { collector, sink } = createPipeline({
+    dbPath,
+    // Use afterCorrelate to capture the event id before it is written
+    afterCorrelate: (event) => {
+      capturedEventId = event.id;
+      return event;
+    },
+    // Disable enrichment rules for external CLI events to keep the write
+    // path lightweight (no Enricher cache, no artifact lookups, no derived events)
+    enrichRules: []
+  });
+  try {
+    collector.registerExternalEvent({
+      source: options.source ?? "external",
+      eventType: options.eventType,
+      lifecycle: options.lifecycle,
+      spanId,
+      parentSpanId: options.parentSpanId,
+      attributes,
+      links
+    });
+  } catch (err) {
+    process.stderr.write(
+      `Error: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    sink.close();
+    process.exit(1);
+  }
+  sink.close();
+  const result = { eventId: capturedEventId, spanId };
+  process.stdout.write(JSON.stringify(result) + "\n");
+}
+
+// src/cli/query.ts
+function bigIntReplacer(_key, value) {
+  return typeof value === "bigint" ? value.toString() : value;
+}
+async function handleQuery(options, _parentOpts) {
+  const validKinds = ["trace", "span", "search", "links"];
+  if (!options.kind) {
+    process.stderr.write(
+      `Error: --kind (-k) is required (${validKinds.join("|")})
+`
+    );
+    process.exit(1);
+  }
+  if (!validKinds.includes(options.kind)) {
+    process.stderr.write(
+      `Error: --kind must be one of: ${validKinds.join("|")}
+`
+    );
+    process.exit(1);
+  }
+  const kind = options.kind;
+  if (kind === "trace" && !options.traceId) {
+    process.stderr.write("Error: --trace-id is required for --kind trace\n");
+    process.exit(1);
+  }
+  if (kind === "span" && !options.spanId) {
+    process.stderr.write("Error: --span-id is required for --kind span\n");
+    process.exit(1);
+  }
+  if (kind === "links" && !options.spanId) {
+    process.stderr.write("Error: --span-id is required for --kind links\n");
+    process.exit(1);
+  }
+  const dbPath = options.db ?? DEFAULT_DB_PATH;
+  const adapter = new SqliteQueryAdapter(dbPath);
+  try {
+    let result;
+    switch (kind) {
+      // ── trace: all spans in a trace ─────────────────────────────────────
+      case "trace": {
+        result = adapter.getTrace(options.traceId);
+        break;
+      }
+      // ── span: single span + its events ──────────────────────────────────
+      case "span": {
+        const span = adapter.getSpan(options.spanId);
+        const events = adapter.getSpanEvents(options.spanId);
+        result = span !== void 0 ? { span, events } : null;
+        break;
+      }
+      // ── search: spans matching event-type / task-id / time range ─────────
+      case "search": {
+        const filter = {};
+        if (options.eventType) filter.eventType = options.eventType;
+        if (options.taskId) filter.taskId = options.taskId;
+        if (options.from) filter.fromTimeUnixNano = isoToUnixNano(options.from);
+        if (options.to) filter.toTimeUnixNano = isoToUnixNano(options.to);
+        result = adapter.querySpans(filter);
+        break;
+      }
+      // ── links: link traversal ─────────────────────────────────────────────
+      case "links": {
+        const validDirections = ["forward", "reverse", "both"];
+        const dir = options.direction !== void 0 && validDirections.includes(options.direction) ? options.direction : "both";
+        result = adapter.getLinks(options.spanId, dir);
+        break;
+      }
+    }
+    process.stdout.write(JSON.stringify(result, bigIntReplacer) + "\n");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("no such table") || msg.includes("no such column")) {
+      const emptyResult = kind === "span" ? null : [];
+      process.stdout.write(JSON.stringify(emptyResult, bigIntReplacer) + "\n");
+      adapter.close();
+      return;
+    }
+    process.stderr.write(`Error: ${msg}
+`);
+    adapter.close();
+    process.exit(1);
+  }
+  adapter.close();
+}
+
+// src/cli/handlers.ts
+var handlers = {
+  record: handleRecord,
+  query: handleQuery
+};
+
+// src/cli/index.ts
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(
+  readFileSync(resolve(__dirname, "../../package.json"), "utf8")
+);
+var program = createProgram(handlers, pkg.version);
+await program.parseAsync();
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cli/index.ts","../../src/generated/program.ts","../../src/generated/contract.ts","../../src/cli/record.ts","../../src/cli/query.ts","../../src/cli/handlers.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * aaac-observ CLI entry point.\n *\n * Reads the version from package.json, creates the generated Commander\n * program with hand-written handlers, and executes it.\n */\nimport { readFileSync } from \"node:fs\";\nimport { dirname, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { createProgram } from \"../generated/program.js\";\nimport { handlers } from \"./handlers.js\";\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\nconst pkg = JSON.parse(\n  readFileSync(resolve(__dirname, \"../../package.json\"), \"utf8\"),\n) as { version: string };\n\nconst program = createProgram(handlers, pkg.version);\nawait program.parseAsync();\n","// Auto-generated by cli-contracts. Do not edit.\nimport { Command } from \"commander\";\nimport { CONTRACT_YAML, CONTRACT_JSON_STR } from \"./contract.js\";\n\nexport interface CommandHandlers {\n  record: (options: { eventType?: string; lifecycle?: string; spanId?: string; parentSpanId?: string; sessionId?: string; traceId?: string; source?: string; attr?: string; link?: string; db?: string }, parentOpts: Record<string, unknown>) => Promise<void>;\n  query: (options: { kind?: string; traceId?: string; spanId?: string; eventType?: string; taskId?: string; from?: string; to?: string; direction?: string; db?: string }, parentOpts: Record<string, unknown>) => Promise<void>;\n}\n\nexport function createProgram(\n  handlers: CommandHandlers,\n  version: string,\n): Command {\n  const program = new Command();\n  program\n    .name(\"aaac-observ\")\n    .version(version, \"-V, --version\")\n    .description(\"aaac-observ — register external events and query the observability store\");\n\n\n  program\n    .command(\"record\")\n    .description(\"Register an external event into the observability pipeline (thin entrypoint for EventCollector.registerExternalEvent)\")\n    .option(\"-t, --event-type <value>\", \"Event type (e.g. promotion.commit, process.edit, agent.session)\")\n    .option(\"-l, --lifecycle <value>\", \"Event lifecycle phase: open | close | event | instant\")\n    .option(\"-s, --span-id <value>\", \"Span ID (auto-generated if omitted)\")\n    .option(\"--parent-span-id <value>\", \"Parent span ID for hierarchy\")\n    .option(\"--session-id <value>\", \"Session ID to associate with the event\")\n    .option(\"--trace-id <value>\", \"Trace ID for distributed tracing\")\n    .option(\"--source <value>\", \"Event source identifier (default: external)\")\n    .option(\"--attr <value>\", \"Attribute as key=value (repeatable, e.g. --attr git.commit=abc123)\")\n    .option(\"--link <value>\", \"Cross-axis link as targetSpanId:linkType[:targetTraceId] (repeatable)\")\n    .option(\"--db <value>\", \"Path to observability SQLite database (overrides default)\")\n    .action(async (opts, cmd) => {\n      await handlers.record(opts, cmd.optsWithGlobals());\n    });\n\n  program\n    .command(\"query\")\n    .description(\"Query the observability store via QueryAdapter\")\n    .option(\"-k, --kind <value>\", \"Query kind: trace | span | search | links\")\n    .option(\"--trace-id <value>\", \"Trace ID for trace queries (--kind trace)\")\n    .option(\"-s, --span-id <value>\", \"Span ID for span/links queries (--kind span or --kind links)\")\n    .option(\"--event-type <value>\", \"Event type filter for search queries (--kind search)\")\n    .option(\"--task-id <value>\", \"Task ID filter for search queries (--kind search)\")\n    .option(\"--from <value>\", \"Start time in ISO 8601 format for search queries (--kind search)\")\n    .option(\"--to <value>\", \"End time in ISO 8601 format for search queries (--kind search)\")\n    .option(\"-d, --direction <value>\", \"Link traversal direction for links queries (default: both)\")\n    .option(\"--db <value>\", \"Path to observability SQLite database (overrides default)\")\n    .action(async (opts, cmd) => {\n      await handlers.query(opts, cmd.optsWithGlobals());\n    });\n\n\n  // Built-in extract command (auto-injected by cli-contracts)\n  program\n    .command(\"extract\")\n    .description(\"Extract contract specification for this CLI tool.\")\n    .argument(\"[commands...]\", \"Command IDs to extract. Use dot notation.\")\n    .option(\"-a, --all\", \"Extract all commands.\", false)\n    .option(\"--include-meta\", \"Include extraction metadata.\", true)\n    .option(\"-F, --format <format>\", \"Output format (yaml or json).\", \"yaml\")\n    .action(async (commands: string[], opts: { all?: boolean; includeMeta?: boolean; format?: string }, cmd: Command) => {\n      if (commands.length === 0 && !opts.all) {\n        process.stderr.write(JSON.stringify({ code: \"INVALID_ARGS\", message: \"Specify command IDs or use --all\" }) + \"\\n\");\n        process.exit(2);\n      }\n\n      const format = opts.format || \"yaml\";\n      const doc = JSON.parse(CONTRACT_JSON_STR);\n      const cmdIds = opts.all ? [] : commands;\n\n      if (cmdIds.length === 0) {\n        // --all: output full contract\n        if (format === \"json\") {\n          const out: Record<string, unknown> = {};\n          if (opts.includeMeta) {\n            out._meta = {\n              source: \"embedded\",\n              type: \"cli-contracts/extract\",\n              extractedAt: new Date().toISOString(),\n              specVersion: doc.cli_contracts ?? \"0.1.0\",\n              commands: [\"aaac-observ.record\",\"aaac-observ.query\"],\n            };\n          }\n          Object.assign(out, doc);\n          process.stdout.write(JSON.stringify(out, null, 2) + \"\\n\");\n        } else {\n          // YAML output\n          const yamlLines: string[] = [];\n          yamlLines.push(\"# aaac-observ extract\");\n          yamlLines.push(\"# source: embedded\");\n          yamlLines.push(\"# type: cli-contracts/command-extract\");\n          if (opts.includeMeta) {\n            yamlLines.push(\"---\");\n            yamlLines.push(\"source: embedded\");\n            yamlLines.push(\"type: cli-contracts/command-extract\");\n            yamlLines.push(\"extractedAt: \" + new Date().toISOString());\n            yamlLines.push(\"spec_version: \" + (doc.cli_contracts ?? \"0.1.0\"));\n            yamlLines.push(\"commands:\");\n            for (const id of [\"aaac-observ.record\",\"aaac-observ.query\"]) {\n              yamlLines.push(\"  - \" + id);\n            }\n          }\n          yamlLines.push(\"---\");\n          yamlLines.push(CONTRACT_YAML);\n          process.stdout.write(yamlLines.join(\"\\n\") + \"\\n\");\n        }\n      } else {\n        // Filter specific commands\n        const filtered: Record<string, unknown> = {\n          cli_contracts: doc.cli_contracts,\n          info: doc.info,\n          command_sets: {},\n        };\n        const fcs = filtered.command_sets as Record<string, Record<string, unknown>>;\n        for (const [setId, cs] of Object.entries(doc.command_sets ?? {})) {\n          const cmds = (cs as Record<string, unknown>).commands as Record<string, unknown> | undefined;\n          if (!cmds) continue;\n          const matched: Record<string, unknown> = {};\n          for (const [cmdId, cmdDef] of Object.entries(cmds)) {\n            const fullId = setId + \".\" + cmdId;\n            if (cmdIds.some((id) => id === cmdId || id === fullId || cmdId.startsWith(id + \".\"))) {\n              matched[cmdId] = cmdDef;\n            }\n          }\n          if (Object.keys(matched).length > 0) {\n            const setCopy = { ...(cs as Record<string, unknown>) };\n            setCopy.commands = matched;\n            fcs[setId] = setCopy;\n          }\n        }\n        if (doc.components) filtered.components = doc.components;\n        process.stdout.write(JSON.stringify(filtered, null, 2) + \"\\n\");\n      }\n      process.exit(0);\n    });\n  return program;\n}\n","// Auto-generated by cli-contracts. Do not edit.\n// Embedded contract for the extract subcommand.\n\nexport const CONTRACT_YAML: string = \"# yaml-language-server: $schema=./node_modules/cli-contracts/schemas/cli-contract.schema.json\\ncli_contracts: 0.1.0\\n\\ninfo:\\n  title: AaaC Observability CLI\\n  version: 0.1.0\\n  description: aaac-observ — external event registration and query for @aaac/observability\\n\\ncommand_sets:\\n  aaac-observ:\\n    summary: aaac-observ — register external events and query the observability store\\n    executable: aaac-observ\\n    commands:\\n      record:\\n        summary: Register an external event into the observability pipeline (thin entrypoint for EventCollector.registerExternalEvent)\\n        options:\\n          - name: event-type\\n            aliases: [t]\\n            schema: { type: string }\\n            description: \\\"Event type (e.g. promotion.commit, process.edit, agent.session)\\\"\\n          - name: lifecycle\\n            aliases: [l]\\n            schema:\\n              type: string\\n              enum: [open, close, event, instant]\\n            description: \\\"Event lifecycle phase: open | close | event | instant\\\"\\n          - name: span-id\\n            aliases: [s]\\n            schema: { type: string }\\n            description: Span ID (auto-generated if omitted)\\n          - name: parent-span-id\\n            schema: { type: string }\\n            description: Parent span ID for hierarchy\\n          - name: session-id\\n            schema: { type: string }\\n            description: Session ID to associate with the event\\n          - name: trace-id\\n            schema: { type: string }\\n            description: Trace ID for distributed tracing\\n          - name: source\\n            schema: { type: string }\\n            description: \\\"Event source identifier (default: external)\\\"\\n          - name: attr\\n            schema:\\n              type: array\\n              items: { type: string }\\n            description: \\\"Attribute as key=value (repeatable, e.g. --attr git.commit=abc123)\\\"\\n          - name: link\\n            schema:\\n              type: array\\n              items: { type: string }\\n            description: \\\"Cross-axis link as targetSpanId:linkType[:targetTraceId] (repeatable)\\\"\\n          - name: db\\n            schema: { type: string }\\n            description: Path to observability SQLite database (overrides default)\\n        exits:\\n          '0':\\n            description: Event registered successfully\\n            stdout:\\n              format: json\\n              schema:\\n                type: object\\n                properties:\\n                  eventId:\\n                    type: string\\n                  spanId:\\n                    type: string\\n          '1':\\n            description: Registration failed (validation error or write error)\\n            stderr:\\n              format: text\\n\\n      query:\\n        summary: Query the observability store via QueryAdapter\\n        options:\\n          - name: kind\\n            aliases: [k]\\n            schema:\\n              type: string\\n              enum: [trace, span, search, links]\\n            description: \\\"Query kind: trace | span | search | links\\\"\\n          - name: trace-id\\n            schema: { type: string }\\n            description: Trace ID for trace queries (--kind trace)\\n          - name: span-id\\n            aliases: [s]\\n            schema: { type: string }\\n            description: Span ID for span/links queries (--kind span or --kind links)\\n          - name: event-type\\n            schema: { type: string }\\n            description: Event type filter for search queries (--kind search)\\n          - name: task-id\\n            schema: { type: string }\\n            description: Task ID filter for search queries (--kind search)\\n          - name: from\\n            schema: { type: string }\\n            description: Start time in ISO 8601 format for search queries (--kind search)\\n          - name: to\\n            schema: { type: string }\\n            description: End time in ISO 8601 format for search queries (--kind search)\\n          - name: direction\\n            aliases: [d]\\n            schema:\\n              type: string\\n              enum: [forward, reverse, both]\\n            description: \\\"Link traversal direction for links queries (default: both)\\\"\\n          - name: db\\n            schema: { type: string }\\n            description: Path to observability SQLite database (overrides default)\\n        exits:\\n          '0':\\n            description: Query succeeded — results as JSON array\\n            stdout:\\n              format: json\\n              schema:\\n                type: object\\n          '1':\\n            description: Query failed\\n            stderr:\\n              format: text\\n\";\n\nexport const CONTRACT_JSON_STR: string = \"{\\n  \\\"cli_contracts\\\": \\\"0.1.0\\\",\\n  \\\"info\\\": {\\n    \\\"title\\\": \\\"AaaC Observability CLI\\\",\\n    \\\"version\\\": \\\"0.1.0\\\",\\n    \\\"description\\\": \\\"aaac-observ — external event registration and query for @aaac/observability\\\"\\n  },\\n  \\\"command_sets\\\": {\\n    \\\"aaac-observ\\\": {\\n      \\\"summary\\\": \\\"aaac-observ — register external events and query the observability store\\\",\\n      \\\"executable\\\": \\\"aaac-observ\\\",\\n      \\\"commands\\\": {\\n        \\\"record\\\": {\\n          \\\"summary\\\": \\\"Register an external event into the observability pipeline (thin entrypoint for EventCollector.registerExternalEvent)\\\",\\n          \\\"options\\\": [\\n            {\\n              \\\"name\\\": \\\"event-type\\\",\\n              \\\"aliases\\\": [\\n                \\\"t\\\"\\n              ],\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\"\\n              },\\n              \\\"description\\\": \\\"Event type (e.g. promotion.commit, process.edit, agent.session)\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"lifecycle\\\",\\n              \\\"aliases\\\": [\\n                \\\"l\\\"\\n              ],\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\",\\n                \\\"enum\\\": [\\n                  \\\"open\\\",\\n                  \\\"close\\\",\\n                  \\\"event\\\",\\n                  \\\"instant\\\"\\n                ]\\n              },\\n              \\\"description\\\": \\\"Event lifecycle phase: open | close | event | instant\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"span-id\\\",\\n              \\\"aliases\\\": [\\n                \\\"s\\\"\\n              ],\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\"\\n              },\\n              \\\"description\\\": \\\"Span ID (auto-generated if omitted)\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"parent-span-id\\\",\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\"\\n              },\\n              \\\"description\\\": \\\"Parent span ID for hierarchy\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"session-id\\\",\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\"\\n              },\\n              \\\"description\\\": \\\"Session ID to associate with the event\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"trace-id\\\",\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\"\\n              },\\n              \\\"description\\\": \\\"Trace ID for distributed tracing\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"source\\\",\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\"\\n              },\\n              \\\"description\\\": \\\"Event source identifier (default: external)\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"attr\\\",\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"array\\\",\\n                \\\"items\\\": {\\n                  \\\"type\\\": \\\"string\\\"\\n                }\\n              },\\n              \\\"description\\\": \\\"Attribute as key=value (repeatable, e.g. --attr git.commit=abc123)\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"link\\\",\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"array\\\",\\n                \\\"items\\\": {\\n                  \\\"type\\\": \\\"string\\\"\\n                }\\n              },\\n              \\\"description\\\": \\\"Cross-axis link as targetSpanId:linkType[:targetTraceId] (repeatable)\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"db\\\",\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\"\\n              },\\n              \\\"description\\\": \\\"Path to observability SQLite database (overrides default)\\\"\\n            }\\n          ],\\n          \\\"exits\\\": {\\n            \\\"0\\\": {\\n              \\\"description\\\": \\\"Event registered successfully\\\",\\n              \\\"stdout\\\": {\\n                \\\"format\\\": \\\"json\\\",\\n                \\\"schema\\\": {\\n                  \\\"type\\\": \\\"object\\\",\\n                  \\\"properties\\\": {\\n                    \\\"eventId\\\": {\\n                      \\\"type\\\": \\\"string\\\"\\n                    },\\n                    \\\"spanId\\\": {\\n                      \\\"type\\\": \\\"string\\\"\\n                    }\\n                  }\\n                }\\n              }\\n            },\\n            \\\"1\\\": {\\n              \\\"description\\\": \\\"Registration failed (validation error or write error)\\\",\\n              \\\"stderr\\\": {\\n                \\\"format\\\": \\\"text\\\"\\n              }\\n            }\\n          }\\n        },\\n        \\\"query\\\": {\\n          \\\"summary\\\": \\\"Query the observability store via QueryAdapter\\\",\\n          \\\"options\\\": [\\n            {\\n              \\\"name\\\": \\\"kind\\\",\\n              \\\"aliases\\\": [\\n                \\\"k\\\"\\n              ],\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\",\\n                \\\"enum\\\": [\\n                  \\\"trace\\\",\\n                  \\\"span\\\",\\n                  \\\"search\\\",\\n                  \\\"links\\\"\\n                ]\\n              },\\n              \\\"description\\\": \\\"Query kind: trace | span | search | links\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"trace-id\\\",\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\"\\n              },\\n              \\\"description\\\": \\\"Trace ID for trace queries (--kind trace)\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"span-id\\\",\\n              \\\"aliases\\\": [\\n                \\\"s\\\"\\n              ],\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\"\\n              },\\n              \\\"description\\\": \\\"Span ID for span/links queries (--kind span or --kind links)\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"event-type\\\",\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\"\\n              },\\n              \\\"description\\\": \\\"Event type filter for search queries (--kind search)\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"task-id\\\",\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\"\\n              },\\n              \\\"description\\\": \\\"Task ID filter for search queries (--kind search)\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"from\\\",\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\"\\n              },\\n              \\\"description\\\": \\\"Start time in ISO 8601 format for search queries (--kind search)\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"to\\\",\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\"\\n              },\\n              \\\"description\\\": \\\"End time in ISO 8601 format for search queries (--kind search)\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"direction\\\",\\n              \\\"aliases\\\": [\\n                \\\"d\\\"\\n              ],\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\",\\n                \\\"enum\\\": [\\n                  \\\"forward\\\",\\n                  \\\"reverse\\\",\\n                  \\\"both\\\"\\n                ]\\n              },\\n              \\\"description\\\": \\\"Link traversal direction for links queries (default: both)\\\"\\n            },\\n            {\\n              \\\"name\\\": \\\"db\\\",\\n              \\\"schema\\\": {\\n                \\\"type\\\": \\\"string\\\"\\n              },\\n              \\\"description\\\": \\\"Path to observability SQLite database (overrides default)\\\"\\n            }\\n          ],\\n          \\\"exits\\\": {\\n            \\\"0\\\": {\\n              \\\"description\\\": \\\"Query succeeded — results as JSON array\\\",\\n              \\\"stdout\\\": {\\n                \\\"format\\\": \\\"json\\\",\\n                \\\"schema\\\": {\\n                  \\\"type\\\": \\\"object\\\"\\n                }\\n              }\\n            },\\n            \\\"1\\\": {\\n              \\\"description\\\": \\\"Query failed\\\",\\n              \\\"stderr\\\": {\\n                \\\"format\\\": \\\"text\\\"\\n              }\\n            }\\n          }\\n        }\\n      }\\n    }\\n  }\\n}\";\n","/**\n * record handler — thin entrypoint for EventCollector.registerExternalEvent.\n *\n * Wires the CLI options to the write pipeline:\n *   options → EventCollector.registerExternalEvent\n *   → Normalizer → Correlator → Enricher → SqliteSink + OtelEmitter\n *\n * architecture.md §9 / OBSERVABILITY_TASKS.md Phase 3-2\n * shift-left-event-mapping.md: aaac-observ record is the thin entrypoint\n */\nimport { createPipeline, generateId, DEFAULT_DB_PATH } from \"../index.js\";\nimport type { CanonicalLink, AttrValue, Lifecycle } from \"../types/canonical-event.js\";\n\n// ── Parsers ──────────────────────────────────────────────────────────────────\n\n/**\n * Parse comma-separated key=value attribute string into a Record.\n * Also accepts a JSON object string.\n *\n * Examples:\n *   \"git.commit=abc123,git.branch=main\"\n *   '{\"git.commit\":\"abc123\",\"git.branch\":\"main\"}'\n */\nexport function parseAttr(attrStr: string | undefined): Record<string, AttrValue> {\n  if (!attrStr) return {};\n  const trimmed = attrStr.trim();\n  if (trimmed.startsWith(\"{\")) {\n    try {\n      return JSON.parse(trimmed) as Record<string, AttrValue>;\n    } catch {\n      // fall through to key=value parsing\n    }\n  }\n  const result: Record<string, AttrValue> = {};\n  for (const pair of trimmed.split(\",\")) {\n    const eqIdx = pair.indexOf(\"=\");\n    if (eqIdx > 0) {\n      const key = pair.slice(0, eqIdx).trim();\n      const val = pair.slice(eqIdx + 1).trim();\n      result[key] = val;\n    }\n  }\n  return result;\n}\n\n/**\n * Parse comma-separated link string into a CanonicalLink array.\n * Format per item: targetSpanId:linkType[:targetTraceId]\n *\n * Example: \"spanId123:materializes_as_commit,spanId456:contains_change:traceId789\"\n */\nexport function parseLinks(linkStr: string | undefined): CanonicalLink[] {\n  if (!linkStr) return [];\n  const links: CanonicalLink[] = [];\n  for (const item of linkStr.split(\",\")) {\n    const parts = item.trim().split(\":\");\n    if (parts.length >= 2) {\n      const targetSpanId = parts[0].trim();\n      const linkType = parts[1].trim();\n      const targetTraceId = parts[2]?.trim() || undefined;\n      if (targetSpanId && linkType) {\n        links.push({ targetSpanId, linkType, targetTraceId });\n      }\n    }\n  }\n  return links;\n}\n\n// ── Handler ──────────────────────────────────────────────────────────────────\n\n/**\n * Options as parsed from the generated CommandHandlers interface.\n * NOTE: attr and link are strings (last value from --option) not arrays,\n * because the generated Commander program does not use a collector.\n * Comma-separate multiple values: --attr \"key1=val1,key2=val2\"\n */\nexport interface RecordHandlerOptions {\n  eventType?: string;\n  lifecycle?: string;\n  spanId?: string;\n  parentSpanId?: string;\n  sessionId?: string;\n  traceId?: string;\n  source?: string;\n  attr?: string;\n  link?: string;\n  db?: string;\n}\n\n/**\n * Handle `aaac-observ record`.\n *\n * Required options: --event-type, --lifecycle\n * On success: writes the event through the full pipeline and prints\n *   { eventId, spanId } to stdout.\n * On error: writes to stderr and exits with code 1.\n */\nexport async function handleRecord(\n  options: RecordHandlerOptions,\n  _parentOpts: Record<string, unknown>,\n): Promise<void> {\n  // ── Validate required options ──────────────────────────────────────────────\n  if (!options.eventType) {\n    process.stderr.write(\"Error: --event-type (-t) is required\\n\");\n    process.exit(1);\n  }\n  const validLifecycles: readonly string[] = [\"open\", \"close\", \"event\", \"instant\"];\n  if (!options.lifecycle) {\n    process.stderr.write(\n      `Error: --lifecycle (-l) is required (${validLifecycles.join(\"|\")})\\n`,\n    );\n    process.exit(1);\n  }\n  if (!validLifecycles.includes(options.lifecycle)) {\n    process.stderr.write(\n      `Error: --lifecycle must be one of: ${validLifecycles.join(\"|\")}\\n`,\n    );\n    process.exit(1);\n  }\n\n  // ── Build event payload ────────────────────────────────────────────────────\n  const dbPath = options.db ?? DEFAULT_DB_PATH;\n  const spanId = options.spanId ?? generateId();\n  const attributes = parseAttr(options.attr);\n  const links = parseLinks(options.link);\n\n  // Inject well-known scalars into attributes so the Normalizer picks them up\n  if (options.sessionId) {\n    attributes[\"session_id\"] = options.sessionId;\n  }\n  // trace_id stored as attribute for user reference; canonical traceId is\n  // managed by Normalizer/Correlator (propagated via parentSpanId chain)\n  if (options.traceId) {\n    attributes[\"trace_id\"] = options.traceId;\n  }\n\n  // ── Build & execute pipeline ───────────────────────────────────────────────\n  let capturedEventId: string | undefined;\n\n  const { collector, sink } = createPipeline({\n    dbPath,\n    // Use afterCorrelate to capture the event id before it is written\n    afterCorrelate: (event) => {\n      capturedEventId = event.id;\n      return event;\n    },\n    // Disable enrichment rules for external CLI events to keep the write\n    // path lightweight (no Enricher cache, no artifact lookups, no derived events)\n    enrichRules: [],\n  });\n\n  try {\n    collector.registerExternalEvent({\n      source: options.source ?? \"external\",\n      eventType: options.eventType,\n      lifecycle: options.lifecycle as Lifecycle,\n      spanId,\n      parentSpanId: options.parentSpanId,\n      attributes,\n      links,\n    });\n  } catch (err) {\n    process.stderr.write(\n      `Error: ${err instanceof Error ? err.message : String(err)}\\n`,\n    );\n    sink.close();\n    process.exit(1);\n  }\n\n  sink.close();\n\n  const result = { eventId: capturedEventId, spanId };\n  process.stdout.write(JSON.stringify(result) + \"\\n\");\n}\n","/**\n * query handler — read path via QueryAdapter.\n *\n * Routes --kind to the appropriate SqliteQueryAdapter method and emits\n * results as JSON to stdout.\n *\n * Supported kinds:\n *   trace   → QueryAdapter.getTrace(--trace-id)\n *   span    → QueryAdapter.getSpan(--span-id)  [+ QueryAdapter.getSpanEvents]\n *   search  → QueryAdapter.querySpans({ eventType, taskId, from, to })\n *   links   → QueryAdapter.getLinks(--span-id, --direction)\n *\n * architecture.md §12 / OBSERVABILITY_TASKS.md Phase 3-2 (record CLI + query)\n */\nimport { SqliteQueryAdapter, DEFAULT_DB_PATH } from \"../index.js\";\nimport { isoToUnixNano } from \"../types/ids.js\";\nimport type { LinkDirection } from \"../query/models.js\";\n\n// ── Handler ───────────────────────────────────────────────────────────────────\n\n/**\n * Options as parsed from the generated CommandHandlers interface.\n */\nexport interface QueryHandlerOptions {\n  kind?: string;\n  traceId?: string;\n  spanId?: string;\n  eventType?: string;\n  taskId?: string;\n  from?: string;\n  to?: string;\n  direction?: string;\n  db?: string;\n}\n\n/** JSON replacer that serialises BigInt as a string. */\nfunction bigIntReplacer(_key: string, value: unknown): unknown {\n  return typeof value === \"bigint\" ? value.toString() : value;\n}\n\n/**\n * Handle `aaac-observ query`.\n *\n * Required option: --kind (trace|span|search|links)\n * On success: writes a JSON array/object to stdout.\n * On error: writes to stderr and exits with code 1.\n *\n * DESIGN NOTE: all required-arg validation happens BEFORE the adapter is\n * created, so that when process.exit is mocked to throw in tests there is no\n * risk of a double-close on the database connection.\n */\nexport async function handleQuery(\n  options: QueryHandlerOptions,\n  _parentOpts: Record<string, unknown>,\n): Promise<void> {\n  const validKinds = [\"trace\", \"span\", \"search\", \"links\"] as const;\n  type QueryKind = (typeof validKinds)[number];\n\n  // ── Validate options (before opening the adapter) ─────────────────────────\n  if (!options.kind) {\n    process.stderr.write(\n      `Error: --kind (-k) is required (${validKinds.join(\"|\")})\\n`,\n    );\n    process.exit(1);\n  }\n  if (!validKinds.includes(options.kind as QueryKind)) {\n    process.stderr.write(\n      `Error: --kind must be one of: ${validKinds.join(\"|\")}\\n`,\n    );\n    process.exit(1);\n  }\n\n  const kind = options.kind as QueryKind;\n\n  // Validate sub-command required args (before adapter creation)\n  if (kind === \"trace\" && !options.traceId) {\n    process.stderr.write(\"Error: --trace-id is required for --kind trace\\n\");\n    process.exit(1);\n  }\n  if (kind === \"span\" && !options.spanId) {\n    process.stderr.write(\"Error: --span-id is required for --kind span\\n\");\n    process.exit(1);\n  }\n  if (kind === \"links\" && !options.spanId) {\n    process.stderr.write(\"Error: --span-id is required for --kind links\\n\");\n    process.exit(1);\n  }\n\n  // ── Open adapter ──────────────────────────────────────────────────────────\n  const dbPath = options.db ?? DEFAULT_DB_PATH;\n  const adapter = new SqliteQueryAdapter(dbPath);\n\n  try {\n    let result: unknown;\n\n    switch (kind) {\n      // ── trace: all spans in a trace ─────────────────────────────────────\n      case \"trace\": {\n        // options.traceId is guaranteed by pre-validation above\n        result = adapter.getTrace(options.traceId!);\n        break;\n      }\n\n      // ── span: single span + its events ──────────────────────────────────\n      case \"span\": {\n        // options.spanId is guaranteed by pre-validation above\n        const span = adapter.getSpan(options.spanId!);\n        const events = adapter.getSpanEvents(options.spanId!);\n        result = span !== undefined ? { span, events } : null;\n        break;\n      }\n\n      // ── search: spans matching event-type / task-id / time range ─────────\n      case \"search\": {\n        const filter: Parameters<typeof adapter.querySpans>[0] = {};\n        if (options.eventType) filter.eventType = options.eventType;\n        if (options.taskId) filter.taskId = options.taskId;\n        if (options.from) filter.fromTimeUnixNano = isoToUnixNano(options.from);\n        if (options.to) filter.toTimeUnixNano = isoToUnixNano(options.to);\n        result = adapter.querySpans(filter);\n        break;\n      }\n\n      // ── links: link traversal ─────────────────────────────────────────────\n      case \"links\": {\n        const validDirections = [\"forward\", \"reverse\", \"both\"] as const;\n        type Dir = (typeof validDirections)[number];\n        const dir: Dir =\n          options.direction !== undefined &&\n          validDirections.includes(options.direction as Dir)\n            ? (options.direction as Dir)\n            : \"both\";\n        result = adapter.getLinks(options.spanId!, dir as LinkDirection);\n        break;\n      }\n    }\n\n    process.stdout.write(JSON.stringify(result, bigIntReplacer) + \"\\n\");\n  } catch (err) {\n    const msg = err instanceof Error ? err.message : String(err);\n\n    // Graceful handling: an un-initialised (fresh empty) database has no\n    // tables yet.  Return an empty / null result rather than an error so that\n    // `aaac-observ query` on a machine with no recorded events behaves\n    // predictably.\n    if (msg.includes(\"no such table\") || msg.includes(\"no such column\")) {\n      const emptyResult = kind === \"span\" ? null : [];\n      process.stdout.write(JSON.stringify(emptyResult, bigIntReplacer) + \"\\n\");\n      adapter.close();\n      return;\n    }\n\n    process.stderr.write(`Error: ${msg}\\n`);\n    adapter.close();\n    process.exit(1);\n  }\n\n  adapter.close();\n}\n","/**\n * CLI command handlers for aaac-observ.\n *\n * Implements the CommandHandlers interface generated by cli-contracts and\n * delegates to the domain-specific handler modules.\n *\n * Usage (in index.ts):\n *   import { handlers } from './handlers.js';\n *   import { createProgram } from '../generated/program.js';\n *   const program = createProgram(handlers, version);\n *   await program.parseAsync();\n */\nimport type { CommandHandlers } from \"../generated/program.js\";\nimport { handleRecord } from \"./record.js\";\nimport { handleQuery } from \"./query.js\";\n\nexport const handlers: CommandHandlers = {\n  record: handleRecord,\n  query: handleQuery,\n};\n"],"mappings":"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","names":["handlers","program"]}