inspeffct 1.0.5 → 1.0.7

package/dist/bin.js

@@ -2,7 +2,7 @@
 import * as NodeRuntime from '@effect/platform-node/NodeRuntime';
 import * as NodeServices from '@effect/platform-node/NodeServices';
 import * as Effect10 from 'effect/Effect';
-import * as Command6 from 'effect/unstable/cli/Command';
+import * as Command5 from 'effect/unstable/cli/Command';
 import * as Argument3 from 'effect/unstable/cli/Argument';
 import * as Context4 from 'effect/Context';
 import * as Fiber from 'effect/Fiber';
@@ -30,14 +30,14 @@ import * as SchemaGetter from 'effect/SchemaGetter';
 import { flow } from 'effect/Function';
 import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem';
 import * as NodePath from '@effect/platform-node/NodePath';
-import * as Flag3 from 'effect/unstable/cli/Flag';
+import * as Flag from 'effect/unstable/cli/Flag';
 import * as NodeSocketServer from '@effect/platform-node/NodeSocketServer';
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as Console2 from 'effect/Console';
-import * as Option3 from 'effect/Option';
+import * as Option4 from 'effect/Option';
 import * as ChildProcess from 'effect/unstable/process/ChildProcess';
 import * as Duration from 'effect/Duration';
 import * as Graph from 'effect/Graph';
@@ -1110,18 +1110,18 @@ Effect10.map(IpcServer, (server) => server.messages);
 Effect10.flatMap(IpcServer, (server) => server.subscribe);
 
 // src/cli/options.ts
-var dataOption = Flag3.string("data").pipe(
-  Flag3.withDescription("Path to SQLite database file"),
-  Flag3.withDefault(".inspeffct.db")
+var dataOption = Flag.string("data").pipe(
+  Flag.withDescription("Path to SQLite database file"),
+  Flag.withDefault(".inspeffct.db")
 );
-var jsonOption = Flag3.boolean("json").pipe(
-  Flag3.withDescription("Output as JSON"),
-  Flag3.withDefault(false)
+var jsonOption = Flag.boolean("json").pipe(
+  Flag.withDescription("Output as JSON"),
+  Flag.withDefault(false)
 );
-var limitOption = Flag3.integer("limit").pipe(
-  Flag3.withAlias("n"),
-  Flag3.withDescription("Maximum number of results"),
-  Flag3.optional
+var limitOption = Flag.integer("limit").pipe(
+  Flag.withAlias("n"),
+  Flag.withDescription("Maximum number of results"),
+  Flag.optional
 );
 var buildEnv = (bootloaderPath, ipcPath) => {
   const requireFlag = `--require "${bootloaderPath}"`;
@@ -1163,7 +1163,7 @@ var makeServicesLayer = (dataPath) => {
 var makeReadOnlyLayer = (dataPath) => layer5({ filename: dataPath });
 
 // src/cli/connect.ts
-var command = Command6.make(
+var command = Command5.make(
   "connect",
   {
     data: dataOption,
@@ -1182,7 +1182,19 @@ var command = Command6.make(
     Effect10.scoped,
     Effect10.provide(makeServicesLayer(data))
   )
-).pipe(Command6.withDescription("Connect to an existing CDP inspector endpoint"));
+).pipe(
+  Command5.withDescription("Connect to an existing CDP inspector endpoint"),
+  Command5.withExamples([
+    {
+      command: "inspeffct connect ws://127.0.0.1:9229/<id>",
+      description: "Connect to a running Node.js inspector endpoint"
+    },
+    {
+      command: "inspeffct connect --data .inspeffct.db ws://127.0.0.1:9229/<id>",
+      description: "Persist captured data to a specific SQLite database"
+    }
+  ])
+);
 var NODE_INSPECTOR_REGEX = /Debugger listening on (ws:\/\/[^\s]+)/;
 var BUN_INSPECTOR_REGEX = /https:\/\/debug\.bun\.sh\/#([^\s]+)/;
 var parseInspectorUrl = (chunk, decoder) => {
@@ -1197,13 +1209,13 @@ var parseInspectorUrl = (chunk, decoder) => {
   }
   return void 0;
 };
-var command2 = Command6.make(
+var command2 = Command5.make(
   "run",
   {
     data: dataOption,
-    encodedCommand: Flag3.string("encoded-command").pipe(
-      Flag3.optional,
-      Flag3.withHidden
+    encodedCommand: Flag.string("encoded-command").pipe(
+      Flag.optional,
+      Flag.withHidden
     ),
     args: Argument3.string("command").pipe(
       Argument3.withDescription("The command to run"),
@@ -1211,11 +1223,11 @@ var command2 = Command6.make(
     )
   },
   ({ args, data, encodedCommand }) => Effect10.gen(function* () {
-    const resolvedArgs = Option3.isSome(encodedCommand) ? JSON.parse(Buffer.from(encodedCommand.value, "base64url").toString("utf8")) : args;
+    const resolvedArgs = Option4.isSome(encodedCommand) ? JSON.parse(Buffer.from(encodedCommand.value, "base64url").toString("utf8")) : args;
     const [rawExecutable, ...commandArgs] = resolvedArgs;
     const executable = rawExecutable === "node" ? process.execPath : rawExecutable;
     const runId = yield* RunId;
-    yield* Console2.log(`Run ID: ${runId}`);
+    yield* Console2.log(`Inspeffct Run ID: ${runId}`);
     yield* Effect10.logDebug(`Running: ${executable} ${commandArgs.join(" ")}`);
     yield* Effect10.logDebug(`Data file: ${data}`);
     const bootloaderPath = yield* getPath;
@@ -1268,7 +1280,19 @@ var command2 = Command6.make(
     Effect10.scoped,
     Effect10.provide(makeServicesLayer(data))
   )
-).pipe(Command6.withDescription("Run a command with Effect instrumentation"));
+).pipe(
+  Command5.withDescription("Run a command with Effect instrumentation"),
+  Command5.withExamples([
+    {
+      command: "inspeffct run -- node app.js",
+      description: "Run a Node.js application with instrumentation"
+    },
+    {
+      command: "inspeffct run --data .inspeffct.db -- node --inspect app.js",
+      description: "Capture data in a specific SQLite database"
+    }
+  ])
+);
 var getSpanId = (span) => span.spanId;
 var getTraceId = (span) => span.traceId;
 var getParentSpanId = (span) => span._tag === "Span" ? span.parentSpanId : null;
@@ -1321,6 +1345,7 @@ var formatStatusDoc = (status) => {
   }
 };
 var field = (label, value) => `${label}: ${value}`;
+var dim = (text) => `\x1B[2m${text}\x1B[22m`;
 var renderDoc = (doc) => doc;
 var statusSymbol = (status, hasEndTime) => {
   if (!hasEndTime) {
@@ -1360,14 +1385,29 @@ var formatSpanLine = (span) => {
   const duration = endTime !== null ? formatDuration(endTime - startTime) : "running";
   return `${symbol} ${getSpanName(span)} (${duration}) [${getSpanId(span)}]`;
 };
+var formatAttributeValue = (value) => {
+  const json = JSON.stringify(value);
+  return json === void 0 ? "undefined" : json;
+};
+var formatSpanAttributesLine = (span) => {
+  const attributes = Object.entries(getAttributes(span));
+  if (attributes.length === 0) {
+    return null;
+  }
+  const rendered = attributes.slice(0, 3).map(([key, value]) => `${key}=${formatAttributeValue(value)}`);
+  if (attributes.length > 3) {
+    rendered.push("...");
+  }
+  return rendered.join(", ");
+};
 var renderGraphNode = (graph, nodeIndex, prefix, isLast, isRoot) => {
   const spanOpt = Graph.getNode(graph, nodeIndex);
-  if (Option3.isNone(spanOpt)) return "";
+  if (Option4.isNone(spanOpt)) return "";
   const span = spanOpt.value;
   const children = [];
   for (const childIndex of Graph.neighbors(graph, nodeIndex)) {
     const childSpanOpt = Graph.getNode(graph, childIndex);
-    if (Option3.isSome(childSpanOpt)) {
+    if (Option4.isSome(childSpanOpt)) {
       children.push({ index: childIndex, span: childSpanOpt.value });
     }
   }
@@ -1375,10 +1415,13 @@ var renderGraphNode = (graph, nodeIndex, prefix, isLast, isRoot) => {
   const connector = isRoot ? "" : isLast ? "\u2514\u2500 " : "\u251C\u2500 ";
   const line = `${prefix}${connector}${formatSpanLine(span)}`;
   const childPrefix = isRoot ? "" : prefix + (isLast ? "   " : "\u2502  ");
+  const attributePrefix = isRoot ? "  " : `${childPrefix}   `;
+  const attributesLine = formatSpanAttributesLine(span);
+  const attributeDoc = attributesLine === null ? [] : [`${attributePrefix}${dim(attributesLine)}`];
   const childDocs = children.map(
     (child, i) => renderGraphNode(graph, child.index, childPrefix, i === children.length - 1, false)
   );
-  return [line, ...childDocs.filter((doc) => doc.length > 0)].join("\n");
+  return [line, ...attributeDoc, ...childDocs.filter((doc) => doc.length > 0)].join("\n");
 };
 var renderSpanGraph = (graph) => {
   const roots = [];
@@ -1395,7 +1438,10 @@ var renderSpanGraph = (graph) => {
 
 // src/cli/span.ts
 var attributesToObject = (attributes) => Object.fromEntries(attributes);
-var command3 = Command6.make(
+var getSpanExit = (span) => span._tag === "Span" && span.status._tag === "Ended" ? span.status.exit : null;
+var stringifyJson = (value) => JSON.stringify(value, (_key, value2) => typeof value2 === "bigint" ? value2.toString() : value2, 2);
+var formatExitBlock = (exit) => ["Exit:", ...stringifyJson(exit).split("\n").map((line) => `  ${line}`)].join("\n");
+var command3 = Command5.make(
   "span",
   {
     data: dataOption,
@@ -1420,6 +1466,7 @@ var command3 = Command6.make(
     const startTime = getStartTime(span);
     const endTime = getEndTime(span);
     const durationNanos = endTime !== null ? endTime - startTime : null;
+    const exit = getSpanExit(span);
     if (json) {
       const output = {
         span: {
@@ -1434,6 +1481,7 @@ var command3 = Command6.make(
           endTime: endTime !== null ? formatTimestamp(endTime) : null,
           durationMs: durationNanos !== null ? Number(durationNanos / 1000000n) : null,
           attributes: getAttributes(span),
+          exit,
           isExternal: isExternalSpan(span)
         },
         events: events.map((event) => ({
@@ -1473,6 +1521,9 @@ var command3 = Command6.make(
       if (Object.keys(attrs).length > 0) {
         fields.push(field("Attrs", JSON.stringify(attrs)));
       }
+      if (exit !== null) {
+        fields.push(formatExitBlock(exit));
+      }
       const eventDocs = events.length === 0 ? ["Events: none"] : [
         `Events (${events.length}):`,
         ...events.map((event) => {
@@ -1501,128 +1552,20 @@ var command3 = Command6.make(
     Effect10.scoped,
     Effect10.provide(makeReadOnlyLayer(data))
   )
-).pipe(Command6.withDescription("Show detailed span information"));
-var command4 = Command6.make(
-  "spans",
-  {
-    data: dataOption,
-    runId: Flag3.string("run-id").pipe(
-      Flag3.withDescription("Filter by run ID"),
-      Flag3.optional
-    ),
-    json: jsonOption,
-    limit: limitOption,
-    minDuration: Flag3.string("min-duration").pipe(
-      Flag3.withDescription("Filter by minimum duration (e.g., '100ms', '1s')"),
-      Flag3.optional
-    ),
-    name: Flag3.string("name").pipe(
-      Flag3.withDescription("Filter by span name (use % for wildcards)"),
-      Flag3.optional
-    ),
-    spanId: Flag3.string("span-id").pipe(
-      Flag3.withDescription("Filter by span ID"),
-      Flag3.optional
-    ),
-    status: Flag3.string("status").pipe(
-      Flag3.withDescription("Filter by status: ok, error, unset"),
-      Flag3.optional
-    ),
-    trace: Flag3.string("trace-id").pipe(
-      Flag3.withAlias("t"),
-      Flag3.withDescription("Filter by trace ID"),
-      Flag3.optional
-    )
-  },
-  ({ data, json, limit, minDuration, name, runId, spanId, status, trace }) => Effect10.gen(function* () {
-    const storage = yield* Storage;
-    let statusCode;
-    if (Option3.isSome(status)) {
-      switch (status.value) {
-        case "ok":
-          statusCode = 1;
-          break;
-        case "error":
-          statusCode = 2;
-          break;
-        case "unset":
-          statusCode = 0;
-          break;
-        default:
-          yield* Effect10.logWarning(`Unknown status: ${status.value}, ignoring filter`);
-      }
-    }
-    const filters = {
-      ...Option3.isSome(runId) ? { runId: runId.value } : {},
-      ...Option3.isSome(spanId) ? { spanId: spanId.value } : {},
-      ...Option3.isSome(trace) ? { traceId: trace.value } : {},
-      ...Option3.isSome(name) ? { name: name.value } : {},
-      ...statusCode !== void 0 ? { status: statusCode } : {},
-      ...Option3.isSome(minDuration) ? { minDuration: parseDurationToNanos(minDuration.value) } : {},
-      ...Option3.isSome(limit) ? { limit: limit.value } : {}
-    };
-    const spans = yield* storage.getSpans(filters);
-    if (json) {
-      const output = spans.map((s) => {
-        const endTime = getEndTime(s);
-        const startTime = getStartTime(s);
-        return {
-          spanId: getSpanId(s),
-          traceId: getTraceId(s),
-          parentSpanId: getParentSpanId(s),
-          name: getSpanName(s),
-          kind: getSpanKind(s),
-          statusCode: getStatusCode(s),
-          statusMessage: getStatusMessage(s),
-          startTime: formatTimestamp(startTime),
-          endTime: endTime !== null ? formatTimestamp(endTime) : null,
-          durationMs: endTime !== null ? Number((endTime - startTime) / 1000000n) : null,
-          attributes: getAttributes(s),
-          isExternal: isExternalSpan(s)
-        };
-      });
-      yield* Console2.log(JSON.stringify(output, null, 2));
-    } else {
-      if (spans.length === 0) {
-        yield* Console2.log("No spans found.");
-      } else {
-        const spanItems = spans.map((s) => {
-          const endTime = getEndTime(s);
-          const startTime = getStartTime(s);
-          const duration = endTime !== null ? formatDuration(endTime - startTime) : "running";
-          const fields = [
-            field("Name", getSpanName(s)),
-            field("Trace", getTraceId(s))
-          ];
-          const parentSpanId = getParentSpanId(s);
-          if (parentSpanId) {
-            fields.push(field("Parent", parentSpanId));
-          }
-          fields.push(
-            field("Status", formatStatusDoc(getStatusCode(s))),
-            field("Started", formatTimestamp(startTime)),
-            field("Duration", duration)
-          );
-          const attrs = getAttributes(s);
-          if (Object.keys(attrs).length > 0) {
-            fields.push(field("Attrs", JSON.stringify(attrs)));
-          }
-          return [getSpanId(s), ...fields.map((field2) => `  ${field2}`)].join("\n");
-        });
-        const doc = [
-          `Found ${spans.length} span(s):`,
-          "",
-          ...spanItems
-        ].join("\n");
-        yield* Console2.log(renderDoc(doc));
-      }
+).pipe(
+  Command5.withDescription("Show detailed span information"),
+  Command5.withExamples([
+    {
+      command: "inspeffct span <trace-id> <span-id>",
+      description: "Show span details with events and links"
+    },
+    {
+      command: "inspeffct span --json <trace-id> <span-id>",
+      description: "Print span details as JSON"
     }
-  }).pipe(
-    Effect10.scoped,
-    Effect10.provide(makeReadOnlyLayer(data))
-  )
-).pipe(Command6.withDescription("List spans with optional filters"));
-var command5 = Command6.make(
+  ])
+);
+var command4 = Command5.make(
   "trace",
   {
     data: dataOption,
@@ -1644,7 +1587,7 @@ var command5 = Command6.make(
     if (json) {
       const buildJsonTree = (g, nodeIndex) => {
         const spanOpt = Graph.getNode(g, nodeIndex);
-        if (Option3.isNone(spanOpt)) return {};
+        if (Option4.isNone(spanOpt)) return {};
         const span = spanOpt.value;
         const endTime = getEndTime(span);
         const startTime = getStartTime(span);
@@ -1652,7 +1595,7 @@ var command5 = Command6.make(
         const children = [];
         for (const childIndex of Graph.neighbors(g, nodeIndex)) {
           const childSpanOpt = Graph.getNode(g, childIndex);
-          if (Option3.isSome(childSpanOpt)) {
+          if (Option4.isSome(childSpanOpt)) {
             children.push({ index: childIndex, span: childSpanOpt.value });
           }
         }
@@ -1691,30 +1634,42 @@ var command5 = Command6.make(
     Effect10.scoped,
     Effect10.provide(makeReadOnlyLayer(data))
   )
-).pipe(Command6.withDescription("Show a trace as a tree view"));
-var command6 = Command6.make(
+).pipe(
+  Command5.withDescription("Show a trace and all spans related to that trace as a tree view"),
+  Command5.withExamples([
+    {
+      command: "inspeffct trace <trace-id>",
+      description: "Show the trace tree with related spans"
+    },
+    {
+      command: "inspeffct trace --json <trace-id>",
+      description: "Print the trace tree as JSON"
+    }
+  ])
+);
+var command5 = Command5.make(
   "traces",
   {
     data: dataOption,
     json: jsonOption,
-    runId: Flag3.string("run-id").pipe(
-      Flag3.withDescription("Filter by run ID"),
-      Flag3.optional
+    runId: Flag.string("run-id").pipe(
+      Flag.withDescription("Filter by run ID"),
+      Flag.optional
     ),
     limit: limitOption,
-    since: Flag3.string("since").pipe(
-      Flag3.withDescription("Filter by time range (e.g., '1h', '30m')"),
-      Flag3.optional
+    since: Flag.string("since").pipe(
+      Flag.withDescription("Filter by time range (e.g., '1h', '30m')"),
+      Flag.optional
     ),
-    status: Flag3.string("status").pipe(
-      Flag3.withDescription("Filter by status: ok, error, unset"),
-      Flag3.optional
+    status: Flag.string("status").pipe(
+      Flag.withDescription("Filter by status: ok, error, unset"),
+      Flag.optional
     )
   },
   ({ data, json, limit, runId, since, status }) => Effect10.gen(function* () {
     const storage = yield* Storage;
     let statusCode;
-    if (Option3.isSome(status)) {
+    if (Option4.isSome(status)) {
       switch (status.value) {
         case "ok":
           statusCode = 1;
@@ -1730,16 +1685,16 @@ var command6 = Command6.make(
       }
     }
     let sinceNanos;
-    if (Option3.isSome(since)) {
+    if (Option4.isSome(since)) {
       const nowNanos = BigInt(Date.now()) * 1000000n;
       const durationNanos = parseDurationToNanos(since.value);
       sinceNanos = nowNanos - durationNanos;
     }
     const filters = {
-      ...Option3.isSome(runId) ? { runId: runId.value } : {},
+      ...Option4.isSome(runId) ? { runId: runId.value } : {},
       ...statusCode !== void 0 ? { status: statusCode } : {},
       ...sinceNanos !== void 0 ? { since: sinceNanos } : {},
-      ...Option3.isSome(limit) ? { limit: limit.value } : {}
+      ...Option4.isSome(limit) ? { limit: limit.value } : {}
     };
     const traces = yield* storage.getTraces(filters);
     if (json) {
@@ -1780,17 +1735,35 @@ var command6 = Command6.make(
     Effect10.scoped,
     Effect10.provide(makeReadOnlyLayer(data))
   )
-).pipe(Command6.withDescription("List traces with optional filters"));
+).pipe(
+  Command5.withDescription("List traces with optional filters"),
+  Command5.withExamples([
+    {
+      command: "inspeffct traces",
+      description: "List recent traces"
+    },
+    {
+      command: "inspeffct traces --run-id <run-id>",
+      description: "List traces captured during a specific run"
+    },
+    {
+      command: "inspeffct traces --status error --since 1h",
+      description: "List recent traces that contain errors"
+    }
+  ])
+);
 
 // src/cli.ts
-var command7 = Command6.make("inspeffct").pipe(
-  Command6.withDescription("Inspect Effect applications without code changes"),
-  Command6.withSubcommands([
+var command6 = Command5.make("inspeffct").pipe(
+  Command5.withDescription(
+    "Run your Effect application with `npx inspeffct run ...` to start capturing data, and then inspect data with the CLI."
+  ),
+  Command5.withSubcommands([
     { group: "Capture", commands: [command2, command] },
-    { group: "Inspect", commands: [command6, command5, command4, command3] }
+    { group: "Inspect", commands: [command5, command4, command3] }
   ])
 );
-var cli = Command6.runWith(command7, {
+var cli = Command5.runWith(command6, {
   version: "0.0.1"
 });
 var encodeRunSeparator = (args) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inspeffct",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "type": "module",
   "description": "A CLI to help agents and humans inspect Effect applications",
   "license": "MIT",