shoe-box-spanoptic 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,194 @@
-# Temporary Holding Version
+# shoe-box-spanoptic
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TUI OTEL visualizer for Effect programs. Visualize your Effect traces in real-time with a terminal UI.
+
+Inspired by [Kit Langton's spanoptic](https://x.com/kitlangton/status/1994799261406695946).
+
+## Features
+
+- Real-time trace visualization with animated spinners
+- Interactive span navigation with arrow keys
+- Span details panel showing attributes and logs
+- Live logs panel at the bottom of the screen
+- Export traces to JSON for later replay
+- Replay previously exported traces
+
+## Installation
+
+```bash
+bun add shoe-box-spanoptic
+```
+
+## Usage
+
+### Programmatic API
+
+Wrap your Effect program with `traceVisualize` to visualize traces:
+
+```typescript
+import { BunRuntime } from '@effect/platform-bun';
+import { Effect } from 'effect';
+import { traceVisualize, withTracedSpan } from 'shoe-box-spanoptic';
+import type { TraceExport } from 'shoe-box-spanoptic';
+
+let lastExport: TraceExport | undefined;
+
+const program = Effect.gen(function* () {
+  yield* Effect.log('Starting...');
+
+  yield* Effect.gen(function* () {
+    yield* Effect.log('Fetching data');
+    yield* Effect.annotateCurrentSpan('user.id', 123);
+    yield* Effect.sleep('500 millis');
+    yield* Effect.log('Data fetched');
+    return { id: 123, name: 'Alice' };
+  }).pipe(withTracedSpan('fetchUser'));
+
+  yield* Effect.log('Done!');
+}).pipe(withTracedSpan('main'));
+
+// Run with trace visualization
+traceVisualize(program, {
+  serviceName: 'my-app',
+  // Called when the user presses 'e' to export
+  onExport: (data) => {
+    lastExport = data;
+  },
+}).pipe(BunRuntime.runMain);
+```
+
+### CLI
+
+The package includes a CLI for running demos and replaying traces:
+
+```bash
+# Run the built-in demo
+bunx shoe-box-spanoptic demo
+
+# Run demo and export to a specific file
+bunx shoe-box-spanoptic demo --output trace.json
+
+# Replay a previously exported trace
+bunx shoe-box-spanoptic replay trace.json
+```
+
+## TUI Layout
+
+- **Left panel**: Trace tree with spans and spinners for running operations
+- **Right panel**: Details for the selected span (attributes, status, duration)
+- **Bottom panel**: Logs for the selected span (updates as you navigate)
+
+## TUI Controls
+
+| Key            | Action                                     |
+| -------------- | ------------------------------------------ |
+| `↑` / `k`      | Move selection up                          |
+| `↓` / `j`      | Move selection down                        |
+| `e`            | Export trace (calls `onExport`)            |
+| `q` / `Escape` | Quit (once the program has finished)       |
+| `Ctrl+C`       | Exit immediately                           |
+
+## API Reference
+
+### `traceVisualize(effect, options)`
+
+Runs an Effect program with OTEL tracing and visualizes it in a TUI. The
+returned effect succeeds with the program's result once the user quits.
+
+```typescript
+const traceVisualize: <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  options: TraceVisualizeOptions,
+) => Effect.Effect<A, E, Exclude<R, Scope.Scope>>;
+
+type TraceVisualizeOptions = {
+  readonly serviceName: string;
+  readonly onExport?: (data: TraceExport) => void;
+};
+```
+
+Logs are attached to the tracing span that is current when they are emitted,
+so both `Effect.withSpan` and `withTracedSpan` spans collect logs.
+
+### `withTracedSpan(name, options?)`
+
+Wraps an effect in a tracing span and an Effect log span of the same name. The
+log span adds the span name to console log output when the program runs
+outside the TUI.
+
+```typescript
+import { withTracedSpan } from 'shoe-box-spanoptic';
+
+const myEffect = Effect.gen(function* () {
+  yield* Effect.log('This log will be associated with mySpan');
+  return 'result';
+}).pipe(withTracedSpan('mySpan'));
+```
+
+### `replayVisualize(data, options?)`
+
+Replays a previously exported trace in the TUI.
+
+```typescript
+const replayVisualize: (
+  data: TraceExport,
+  options?: { readonly onExport?: (data: TraceExport) => void },
+) => Effect.Effect<void>;
+```
+
+### `encodeTraceExport` / `decodeTraceExport`
+
+Convert a `TraceExport` to and from the pretty-printed JSON file the CLI writes
+(`TraceExportJson` is the underlying `Schema`):
+
+```typescript
+import { decodeTraceExport, replayVisualize } from 'shoe-box-spanoptic';
+
+const program = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const data = yield* decodeTraceExport(yield* fs.readFileString('trace.json'));
+  yield* replayVisualize(data);
+});
+```
+
+### Types
+
+`LogEntry`, `SpanInfo` and `TraceExport` are exported both as Effect `Schema`s
+and as their (readonly) types:
+
+```typescript
+type TraceExport = {
+  readonly version: 1;
+  readonly serviceName: string;
+  readonly exportedAt: number;
+  readonly spans: ReadonlyArray<SpanInfo>;
+};
+
+type SpanInfo = {
+  readonly spanId: string;
+  readonly parentSpanId?: string | undefined;
+  readonly name: string;
+  readonly startTime: number;
+  readonly endTime: number | null;
+  readonly status: 'running' | 'ok' | 'error';
+  readonly errorMessage?: string | undefined;
+  readonly attributes: { readonly [key: string]: unknown };
+  readonly logs: ReadonlyArray<LogEntry>;
+};
+
+type LogEntry = {
+  readonly timestamp: number;
+  readonly level: string; // 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | ...
+  readonly message: string;
+  readonly spanName: string | null;
+};
+```
+
+## Requirements
+
+- Effect 4 (`effect` and `@effect/opentelemetry` 4.0.6)
+- Bun (`@opentui/core` loads its native renderer through `bun:ffi`)
+
+## License
+
+MIT

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/cli.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env bun
+import { c as decodeTraceExport, l as encodeTraceExport, n as traceVisualize, r as withTracedSpan, t as replayVisualize } from "./src-Cnnn7RBN.mjs";
+import { Clock, Console, Effect, FileSystem, Option, Random, References } from "effect";
+import { BunRuntime, BunServices } from "@effect/platform-bun";
+import { Argument, Command, Flag } from "effect/cli";
+// src/demo-program.ts
+const randomDelay = (min, max) => Effect.flatMap(Random.nextIntBetween(min, max), (ms) => Effect.sleep(ms));
+const fetchUser = Effect.gen(function* () {
+	yield* Effect.log("Fetching user from database...");
+	yield* Effect.annotateCurrentSpan("user.id", 1);
+	yield* Effect.annotateCurrentSpan("user.role", "admin");
+	yield* randomDelay(300, 600);
+	yield* Effect.log("User fetched successfully");
+	return {
+		id: 1,
+		name: "Alice"
+	};
+}).pipe(withTracedSpan("fetchUser"));
+const processData = Effect.gen(function* () {
+	yield* Effect.log("Starting data processing");
+	yield* randomDelay(200, 400);
+	yield* Effect.logDebug("Processed 42 records");
+	yield* Effect.log("Data processing complete");
+}).pipe(withTracedSpan("processData"));
+const connectToDatabase = Effect.gen(function* () {
+	yield* Effect.log("Establishing database connection");
+	yield* randomDelay(100, 200);
+	yield* Effect.log("Connected to PostgreSQL");
+}).pipe(withTracedSpan("connectToDatabase"));
+const queryUsers = Effect.gen(function* () {
+	yield* Effect.log("Executing query: SELECT * FROM users");
+	yield* Effect.annotateCurrentSpan("db.table", "users");
+	yield* Effect.annotateCurrentSpan("db.rows_returned", 42);
+	yield* randomDelay(250, 500);
+	yield* Effect.logDebug("Query returned 42 rows in 234ms");
+}).pipe(withTracedSpan("queryUsers"));
+const queryOrders = Effect.gen(function* () {
+	yield* Effect.log("Executing query: SELECT * FROM orders");
+	yield* Effect.annotateCurrentSpan("db.table", "orders");
+	yield* Effect.annotateCurrentSpan("db.rows_returned", 156);
+	yield* randomDelay(300, 600);
+	yield* Effect.logDebug("Query returned 156 rows in 412ms");
+	yield* Effect.logWarning("Large result set - consider pagination");
+}).pipe(withTracedSpan("queryOrders"));
+const databaseOperations = Effect.gen(function* () {
+	yield* Effect.log("Starting database operations");
+	yield* connectToDatabase;
+	yield* queryUsers;
+	yield* queryOrders;
+	yield* Effect.log("Database operations complete");
+}).pipe(withTracedSpan("databaseOperations"));
+const sendNotifications = Effect.gen(function* () {
+	yield* Effect.log("Sending notifications to 3 users");
+	yield* randomDelay(400, 800);
+	yield* Effect.logInfo("Email sent to user@example.com");
+	yield* Effect.logInfo("Push notification sent");
+}).pipe(withTracedSpan("sendNotifications"));
+const updateCache = Effect.gen(function* () {
+	yield* Effect.log("Invalidating cache entries");
+	yield* randomDelay(150, 300);
+	yield* Effect.logDebug("Cache key: user:1 invalidated");
+}).pipe(withTracedSpan("updateCache"));
+const trackAnalytics = Effect.gen(function* () {
+	yield* Effect.log("Recording analytics event");
+	yield* randomDelay(200, 500);
+	yield* Effect.logDebug("Event: page_view recorded");
+}).pipe(withTracedSpan("trackAnalytics"));
+const generateReport = Effect.gen(function* () {
+	yield* Effect.log("Generating monthly report");
+	yield* randomDelay(400, 700);
+	yield* Effect.logInfo("Report generated: report_2024_01.pdf");
+	yield* Effect.log("Report saved to S3");
+}).pipe(withTracedSpan("generateReport"));
+/** A simulated API request handler: sequential, nested and parallel spans. */
+const demoProgram = Effect.gen(function* () {
+	yield* Effect.log("Starting API request handler");
+	const user = yield* fetchUser;
+	yield* processData;
+	yield* databaseOperations;
+	yield* Effect.all([
+		sendNotifications,
+		updateCache,
+		trackAnalytics
+	], { concurrency: "unbounded" }).pipe(withTracedSpan("sideEffects"));
+	yield* generateReport;
+	yield* Effect.sleep("200 millis").pipe(withTracedSpan("finalize"));
+	yield* Effect.log("Request completed successfully");
+	return user;
+}).pipe(withTracedSpan("main"));
+// src/cli.ts
+/**
+* Spanoptic CLI - TUI OTEL visualizer for Effect programs
+*
+* Usage:
+*   spanoptic demo [--output <file>]  - Run a demo trace visualization
+*   spanoptic replay <file>           - Replay a previously exported trace
+*/
+const writeTrace = Effect.fnUntraced(function* (data, output) {
+	const fs = yield* FileSystem.FileSystem;
+	const now = yield* Clock.currentTimeMillis;
+	const filename = Option.getOrElse(output, () => `trace-${now}.json`);
+	yield* fs.writeFileString(filename, yield* encodeTraceExport(data));
+	yield* Console.log(`\nTrace exported to ${filename}`);
+});
+const exportHandler = Effect.fnUntraced(function* (output) {
+	const context = yield* Effect.context();
+	return (data) => {
+		Effect.runForkWith(context)(writeTrace(data, output).pipe(Effect.catch((error) => Console.error(String(error)))));
+	};
+});
+const demoCommand = Command.make("demo", { output: Flag.File("output").pipe(Flag.withAlias("o"), Flag.withDescription("Where to write the trace when you press e"), Flag.optional) }, Effect.fnUntraced(function* ({ output }) {
+	yield* traceVisualize(demoProgram, {
+		serviceName: "spanoptic-demo",
+		onExport: yield* exportHandler(output)
+	});
+})).pipe(Command.withDescription("Run a demo trace visualization"));
+const replayCommand = Command.make("replay", { file: Argument.File("file", { mustExist: true }).pipe(Argument.withDescription("A trace exported with e")) }, Effect.fnUntraced(function* ({ file }) {
+	const fs = yield* FileSystem.FileSystem;
+	const data = yield* decodeTraceExport(yield* fs.readFileString(file));
+	yield* Console.log(`Replaying trace from ${file}`);
+	yield* Console.log(`Service: ${data.serviceName}`);
+	yield* Console.log(`Spans: ${data.spans.length}`);
+	yield* Console.log("");
+	yield* Effect.sleep("500 millis");
+	yield* replayVisualize(data, { onExport: yield* exportHandler(Option.none()) });
+})).pipe(Command.withDescription("Replay a previously exported trace"));
+const spanoptic = Command.make("spanoptic", {}, () => Console.log("Spanoptic - TUI OTEL visualizer for Effect programs\n\nUse --help to see available commands.")).pipe(Command.withDescription("TUI OTEL visualizer for Effect programs"), Command.withSubcommands([demoCommand, replayCommand]));
+Command.run(spanoptic, { version: "0.0.1" }).pipe(Effect.provideService(References.MinimumLogLevel, "None"), Effect.provide(BunServices.layer), BunRuntime.runMain);
+export {};
+
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/demo-program.ts","../src/cli.ts"],"sourcesContent":["import { Effect, Random } from 'effect';\n\nimport { withTracedSpan } from './index.ts';\n\nconst randomDelay = (min: number, max: number) =>\n  Effect.flatMap(Random.nextIntBetween(min, max), (ms) => Effect.sleep(ms));\n\nconst fetchUser = Effect.gen(function* () {\n  yield* Effect.log('Fetching user from database...');\n  yield* Effect.annotateCurrentSpan('user.id', 1);\n  yield* Effect.annotateCurrentSpan('user.role', 'admin');\n  yield* randomDelay(300, 600);\n  yield* Effect.log('User fetched successfully');\n  return { id: 1, name: 'Alice' };\n}).pipe(withTracedSpan('fetchUser'));\n\nconst processData = Effect.gen(function* () {\n  yield* Effect.log('Starting data processing');\n  yield* randomDelay(200, 400);\n  yield* Effect.logDebug('Processed 42 records');\n  yield* Effect.log('Data processing complete');\n}).pipe(withTracedSpan('processData'));\n\nconst connectToDatabase = Effect.gen(function* () {\n  yield* Effect.log('Establishing database connection');\n  yield* randomDelay(100, 200);\n  yield* Effect.log('Connected to PostgreSQL');\n}).pipe(withTracedSpan('connectToDatabase'));\n\nconst queryUsers = Effect.gen(function* () {\n  yield* Effect.log('Executing query: SELECT * FROM users');\n  yield* Effect.annotateCurrentSpan('db.table', 'users');\n  yield* Effect.annotateCurrentSpan('db.rows_returned', 42);\n  yield* randomDelay(250, 500);\n  yield* Effect.logDebug('Query returned 42 rows in 234ms');\n}).pipe(withTracedSpan('queryUsers'));\n\nconst queryOrders = Effect.gen(function* () {\n  yield* Effect.log('Executing query: SELECT * FROM orders');\n  yield* Effect.annotateCurrentSpan('db.table', 'orders');\n  yield* Effect.annotateCurrentSpan('db.rows_returned', 156);\n  yield* randomDelay(300, 600);\n  yield* Effect.logDebug('Query returned 156 rows in 412ms');\n  yield* Effect.logWarning('Large result set - consider pagination');\n}).pipe(withTracedSpan('queryOrders'));\n\nconst databaseOperations = Effect.gen(function* () {\n  yield* Effect.log('Starting database operations');\n  yield* connectToDatabase;\n  yield* queryUsers;\n  yield* queryOrders;\n  yield* Effect.log('Database operations complete');\n}).pipe(withTracedSpan('databaseOperations'));\n\nconst sendNotifications = Effect.gen(function* () {\n  yield* Effect.log('Sending notifications to 3 users');\n  yield* randomDelay(400, 800);\n  yield* Effect.logInfo('Email sent to user@example.com');\n  yield* Effect.logInfo('Push notification sent');\n}).pipe(withTracedSpan('sendNotifications'));\n\nconst updateCache = Effect.gen(function* () {\n  yield* Effect.log('Invalidating cache entries');\n  yield* randomDelay(150, 300);\n  yield* Effect.logDebug('Cache key: user:1 invalidated');\n}).pipe(withTracedSpan('updateCache'));\n\nconst trackAnalytics = Effect.gen(function* () {\n  yield* Effect.log('Recording analytics event');\n  yield* randomDelay(200, 500);\n  yield* Effect.logDebug('Event: page_view recorded');\n}).pipe(withTracedSpan('trackAnalytics'));\n\nconst generateReport = Effect.gen(function* () {\n  yield* Effect.log('Generating monthly report');\n  yield* randomDelay(400, 700);\n  yield* Effect.logInfo('Report generated: report_2024_01.pdf');\n  yield* Effect.log('Report saved to S3');\n}).pipe(withTracedSpan('generateReport'));\n\n/** A simulated API request handler: sequential, nested and parallel spans. */\nexport const demoProgram = Effect.gen(function* () {\n  yield* Effect.log('Starting API request handler');\n  const user = yield* fetchUser;\n  yield* processData;\n  yield* databaseOperations;\n  yield* Effect.all([sendNotifications, updateCache, trackAnalytics], {\n    concurrency: 'unbounded',\n  }).pipe(withTracedSpan('sideEffects'));\n  yield* generateReport;\n  yield* Effect.sleep('200 millis').pipe(withTracedSpan('finalize'));\n  yield* Effect.log('Request completed successfully');\n  return user;\n}).pipe(withTracedSpan('main'));\n","#!/usr/bin/env bun\n/**\n * Spanoptic CLI - TUI OTEL visualizer for Effect programs\n *\n * Usage:\n *   spanoptic demo [--output <file>]  - Run a demo trace visualization\n *   spanoptic replay <file>           - Replay a previously exported trace\n */\n\nimport { BunRuntime, BunServices } from '@effect/platform-bun';\nimport { Clock, Console, Effect, FileSystem, Option, References } from 'effect';\nimport { Argument, Command, Flag } from 'effect/cli';\n\nimport { demoProgram } from './demo-program.ts';\nimport {\n  decodeTraceExport,\n  encodeTraceExport,\n  replayVisualize,\n  traceVisualize,\n} from './index.ts';\nimport type { TraceExport } from './index.ts';\n\nconst writeTrace = Effect.fnUntraced(function* (\n  data: TraceExport,\n  output: Option.Option<string>,\n) {\n  const fs = yield* FileSystem.FileSystem;\n  const now = yield* Clock.currentTimeMillis;\n  const filename = Option.getOrElse(output, () => `trace-${now}.json`);\n  yield* fs.writeFileString(filename, yield* encodeTraceExport(data));\n  yield* Console.log(`\\nTrace exported to ${filename}`);\n});\n\n// onExport is a plain callback fired from a key press, so the write is\n// forked with the command's services rather than awaited by the TUI.\nconst exportHandler = Effect.fnUntraced(function* (\n  output: Option.Option<string>,\n) {\n  const context = yield* Effect.context<FileSystem.FileSystem>();\n  return (data: TraceExport) => {\n    Effect.runForkWith(context)(\n      writeTrace(data, output).pipe(\n        Effect.catch((error) => Console.error(String(error))),\n      ),\n    );\n  };\n});\n\nconst demoCommand = Command.make(\n  'demo',\n  {\n    output: Flag.File('output').pipe(\n      Flag.withAlias('o'),\n      Flag.withDescription('Where to write the trace when you press e'),\n      Flag.optional,\n    ),\n  },\n  Effect.fnUntraced(function* ({ output }) {\n    yield* traceVisualize(demoProgram, {\n      serviceName: 'spanoptic-demo',\n      onExport: yield* exportHandler(output),\n    });\n  }),\n).pipe(Command.withDescription('Run a demo trace visualization'));\n\nconst replayCommand = Command.make(\n  'replay',\n  {\n    file: Argument.File('file', { mustExist: true }).pipe(\n      Argument.withDescription('A trace exported with e'),\n    ),\n  },\n  Effect.fnUntraced(function* ({ file }) {\n    const fs = yield* FileSystem.FileSystem;\n    const data = yield* decodeTraceExport(yield* fs.readFileString(file));\n\n    yield* Console.log(`Replaying trace from ${file}`);\n    yield* Console.log(`Service: ${data.serviceName}`);\n    yield* Console.log(`Spans: ${data.spans.length}`);\n    yield* Console.log('');\n    // Leave the summary on screen briefly before the TUI takes over.\n    yield* Effect.sleep('500 millis');\n\n    yield* replayVisualize(data, {\n      onExport: yield* exportHandler(Option.none()),\n    });\n  }),\n).pipe(Command.withDescription('Replay a previously exported trace'));\n\nconst spanoptic = Command.make('spanoptic', {}, () =>\n  Console.log(\n    'Spanoptic - TUI OTEL visualizer for Effect programs\\n\\nUse --help to see available commands.',\n  ),\n).pipe(\n  Command.withDescription('TUI OTEL visualizer for Effect programs'),\n  Command.withSubcommands([demoCommand, replayCommand]),\n);\n\nCommand.run(spanoptic, { version: '0.0.1' }).pipe(\n  // Effect logs would paint over the TUI; traceVisualize captures its own.\n  Effect.provideService(References.MinimumLogLevel, 'None'),\n  // oxlint-disable-next-line effecttsgo/strict-effect-provide -- this is the entry point\n  Effect.provide(BunServices.layer),\n  BunRuntime.runMain,\n);\n"],"mappings":";;;;;;AAIA,MAAM,eAAe,KAAa,QAChC,OAAO,QAAQ,OAAO,eAAe,KAAK,GAAG,IAAI,OAAO,OAAO,MAAM,EAAE,CAAC;AAE1E,MAAM,YAAY,OAAO,IAAI,aAAa;CACxC,OAAO,OAAO,IAAI,gCAAgC;CAClD,OAAO,OAAO,oBAAoB,WAAW,CAAC;CAC9C,OAAO,OAAO,oBAAoB,aAAa,OAAO;CACtD,OAAO,YAAY,KAAK,GAAG;CAC3B,OAAO,OAAO,IAAI,2BAA2B;CAC7C,OAAO;EAAE,IAAI;EAAG,MAAM;CAAQ;AAChC,CAAC,CAAC,CAAC,KAAK,eAAe,WAAW,CAAC;AAEnC,MAAM,cAAc,OAAO,IAAI,aAAa;CAC1C,OAAO,OAAO,IAAI,0BAA0B;CAC5C,OAAO,YAAY,KAAK,GAAG;CAC3B,OAAO,OAAO,SAAS,sBAAsB;CAC7C,OAAO,OAAO,IAAI,0BAA0B;AAC9C,CAAC,CAAC,CAAC,KAAK,eAAe,aAAa,CAAC;AAErC,MAAM,oBAAoB,OAAO,IAAI,aAAa;CAChD,OAAO,OAAO,IAAI,kCAAkC;CACpD,OAAO,YAAY,KAAK,GAAG;CAC3B,OAAO,OAAO,IAAI,yBAAyB;AAC7C,CAAC,CAAC,CAAC,KAAK,eAAe,mBAAmB,CAAC;AAE3C,MAAM,aAAa,OAAO,IAAI,aAAa;CACzC,OAAO,OAAO,IAAI,sCAAsC;CACxD,OAAO,OAAO,oBAAoB,YAAY,OAAO;CACrD,OAAO,OAAO,oBAAoB,oBAAoB,EAAE;CACxD,OAAO,YAAY,KAAK,GAAG;CAC3B,OAAO,OAAO,SAAS,iCAAiC;AAC1D,CAAC,CAAC,CAAC,KAAK,eAAe,YAAY,CAAC;AAEpC,MAAM,cAAc,OAAO,IAAI,aAAa;CAC1C,OAAO,OAAO,IAAI,uCAAuC;CACzD,OAAO,OAAO,oBAAoB,YAAY,QAAQ;CACtD,OAAO,OAAO,oBAAoB,oBAAoB,GAAG;CACzD,OAAO,YAAY,KAAK,GAAG;CAC3B,OAAO,OAAO,SAAS,kCAAkC;CACzD,OAAO,OAAO,WAAW,wCAAwC;AACnE,CAAC,CAAC,CAAC,KAAK,eAAe,aAAa,CAAC;AAErC,MAAM,qBAAqB,OAAO,IAAI,aAAa;CACjD,OAAO,OAAO,IAAI,8BAA8B;CAChD,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO,OAAO,IAAI,8BAA8B;AAClD,CAAC,CAAC,CAAC,KAAK,eAAe,oBAAoB,CAAC;AAE5C,MAAM,oBAAoB,OAAO,IAAI,aAAa;CAChD,OAAO,OAAO,IAAI,kCAAkC;CACpD,OAAO,YAAY,KAAK,GAAG;CAC3B,OAAO,OAAO,QAAQ,gCAAgC;CACtD,OAAO,OAAO,QAAQ,wBAAwB;AAChD,CAAC,CAAC,CAAC,KAAK,eAAe,mBAAmB,CAAC;AAE3C,MAAM,cAAc,OAAO,IAAI,aAAa;CAC1C,OAAO,OAAO,IAAI,4BAA4B;CAC9C,OAAO,YAAY,KAAK,GAAG;CAC3B,OAAO,OAAO,SAAS,+BAA+B;AACxD,CAAC,CAAC,CAAC,KAAK,eAAe,aAAa,CAAC;AAErC,MAAM,iBAAiB,OAAO,IAAI,aAAa;CAC7C,OAAO,OAAO,IAAI,2BAA2B;CAC7C,OAAO,YAAY,KAAK,GAAG;CAC3B,OAAO,OAAO,SAAS,2BAA2B;AACpD,CAAC,CAAC,CAAC,KAAK,eAAe,gBAAgB,CAAC;AAExC,MAAM,iBAAiB,OAAO,IAAI,aAAa;CAC7C,OAAO,OAAO,IAAI,2BAA2B;CAC7C,OAAO,YAAY,KAAK,GAAG;CAC3B,OAAO,OAAO,QAAQ,sCAAsC;CAC5D,OAAO,OAAO,IAAI,oBAAoB;AACxC,CAAC,CAAC,CAAC,KAAK,eAAe,gBAAgB,CAAC;;AAGxC,MAAa,cAAc,OAAO,IAAI,aAAa;CACjD,OAAO,OAAO,IAAI,8BAA8B;CAChD,MAAM,OAAO,OAAO;CACpB,OAAO;CACP,OAAO;CACP,OAAO,OAAO,IAAI;EAAC;EAAmB;EAAa;CAAc,GAAG,EAClE,aAAa,YACf,CAAC,CAAC,CAAC,KAAK,eAAe,aAAa,CAAC;CACrC,OAAO;CACP,OAAO,OAAO,MAAM,YAAY,CAAC,CAAC,KAAK,eAAe,UAAU,CAAC;CACjE,OAAO,OAAO,IAAI,gCAAgC;CAClD,OAAO;AACT,CAAC,CAAC,CAAC,KAAK,eAAe,MAAM,CAAC;;;;;;;;;ACvE9B,MAAM,aAAa,OAAO,WAAW,WACnC,MACA,QACA;CACA,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,MAAM,OAAO,MAAM;CACzB,MAAM,WAAW,OAAO,UAAU,cAAc,SAAS,IAAI,MAAM;CACnE,OAAO,GAAG,gBAAgB,UAAU,OAAO,kBAAkB,IAAI,CAAC;CAClE,OAAO,QAAQ,IAAI,uBAAuB,UAAU;AACtD,CAAC;AAID,MAAM,gBAAgB,OAAO,WAAW,WACtC,QACA;CACA,MAAM,UAAU,OAAO,OAAO,QAA+B;CAC7D,QAAQ,SAAsB;EAC5B,OAAO,YAAY,OAAO,CAAC,CACzB,WAAW,MAAM,MAAM,CAAC,CAAC,KACvB,OAAO,OAAO,UAAU,QAAQ,MAAM,OAAO,KAAK,CAAC,CAAC,CACtD,CACF;CACF;AACF,CAAC;AAED,MAAM,cAAc,QAAQ,KAC1B,QACA,EACE,QAAQ,KAAK,KAAK,QAAQ,CAAC,CAAC,KAC1B,KAAK,UAAU,GAAG,GAClB,KAAK,gBAAgB,2CAA2C,GAChE,KAAK,QACP,EACF,GACA,OAAO,WAAW,WAAW,EAAE,UAAU;CACvC,OAAO,eAAe,aAAa;EACjC,aAAa;EACb,UAAU,OAAO,cAAc,MAAM;CACvC,CAAC;AACH,CAAC,CACH,CAAC,CAAC,KAAK,QAAQ,gBAAgB,gCAAgC,CAAC;AAEhE,MAAM,gBAAgB,QAAQ,KAC5B,UACA,EACE,MAAM,SAAS,KAAK,QAAQ,EAAE,WAAW,KAAK,CAAC,CAAC,CAAC,KAC/C,SAAS,gBAAgB,yBAAyB,CACpD,EACF,GACA,OAAO,WAAW,WAAW,EAAE,QAAQ;CACrC,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,OAAO,OAAO,kBAAkB,OAAO,GAAG,eAAe,IAAI,CAAC;CAEpE,OAAO,QAAQ,IAAI,wBAAwB,MAAM;CACjD,OAAO,QAAQ,IAAI,YAAY,KAAK,aAAa;CACjD,OAAO,QAAQ,IAAI,UAAU,KAAK,MAAM,QAAQ;CAChD,OAAO,QAAQ,IAAI,EAAE;CAErB,OAAO,OAAO,MAAM,YAAY;CAEhC,OAAO,gBAAgB,MAAM,EAC3B,UAAU,OAAO,cAAc,OAAO,KAAK,CAAC,EAC9C,CAAC;AACH,CAAC,CACH,CAAC,CAAC,KAAK,QAAQ,gBAAgB,oCAAoC,CAAC;AAEpE,MAAM,YAAY,QAAQ,KAAK,aAAa,CAAC,SAC3C,QAAQ,IACN,8FACF,CACF,CAAC,CAAC,KACA,QAAQ,gBAAgB,yCAAyC,GACjE,QAAQ,gBAAgB,CAAC,aAAa,aAAa,CAAC,CACtD;AAEA,QAAQ,IAAI,WAAW,EAAE,SAAS,QAAQ,CAAC,CAAC,CAAC,KAE3C,OAAO,eAAe,WAAW,iBAAiB,MAAM,GAExD,OAAO,QAAQ,YAAY,KAAK,GAChC,WAAW,OACb"}

package/dist/index.d.mts

@@ -0,0 +1,177 @@
+import * as OtelTracer from "@effect/opentelemetry/OtelTracer";
+import { Effect, Schema, Tracer } from "effect";
+export declare const LogEntry: Schema.Struct<{
+  readonly timestamp: Schema.Finite;
+  readonly level: Schema.String;
+  readonly message: Schema.String;
+  readonly spanName: Schema.NullOr<Schema.String>;
+}>;
+export type LogEntry = typeof LogEntry.Type;
+export declare const SpanInfo: Schema.Struct<{
+  readonly spanId: Schema.String;
+  readonly parentSpanId: Schema.optional<Schema.String>;
+  readonly name: Schema.String;
+  readonly startTime: Schema.Finite;
+  readonly endTime: Schema.NullOr<Schema.Finite>;
+  readonly status: Schema.Literals<readonly ["running", "ok", "error"]>;
+  readonly errorMessage: Schema.optional<Schema.String>;
+  readonly attributes: Schema.$Record<Schema.String, Schema.Unknown>;
+  readonly logs: Schema.$Array<Schema.Struct<{
+    readonly timestamp: Schema.Finite;
+    readonly level: Schema.String;
+    readonly message: Schema.String;
+    readonly spanName: Schema.NullOr<Schema.String>;
+  }>>;
+}>;
+export type SpanInfo = typeof SpanInfo.Type;
+/** Exported trace data for replay. */
+export declare const TraceExport: Schema.Struct<{
+  readonly version: Schema.Literal<1>;
+  readonly serviceName: Schema.String;
+  readonly exportedAt: Schema.Finite;
+  readonly spans: Schema.$Array<Schema.Struct<{
+    readonly spanId: Schema.String;
+    readonly parentSpanId: Schema.optional<Schema.String>;
+    readonly name: Schema.String;
+    readonly startTime: Schema.Finite;
+    readonly endTime: Schema.NullOr<Schema.Finite>;
+    readonly status: Schema.Literals<readonly ["running", "ok", "error"]>;
+    readonly errorMessage: Schema.optional<Schema.String>;
+    readonly attributes: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly logs: Schema.$Array<Schema.Struct<{
+      readonly timestamp: Schema.Finite;
+      readonly level: Schema.String;
+      readonly message: Schema.String;
+      readonly spanName: Schema.NullOr<Schema.String>;
+    }>>;
+  }>>;
+}>;
+export type TraceExport = typeof TraceExport.Type;
+/** A trace export as the pretty-printed JSON file the CLI writes and replays. */
+export declare const TraceExportJson: Schema.fromJsonString<Schema.Struct<{
+  readonly version: Schema.Literal<1>;
+  readonly serviceName: Schema.String;
+  readonly exportedAt: Schema.Finite;
+  readonly spans: Schema.$Array<Schema.Struct<{
+    readonly spanId: Schema.String;
+    readonly parentSpanId: Schema.optional<Schema.String>;
+    readonly name: Schema.String;
+    readonly startTime: Schema.Finite;
+    readonly endTime: Schema.NullOr<Schema.Finite>;
+    readonly status: Schema.Literals<readonly ["running", "ok", "error"]>;
+    readonly errorMessage: Schema.optional<Schema.String>;
+    readonly attributes: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly logs: Schema.$Array<Schema.Struct<{
+      readonly timestamp: Schema.Finite;
+      readonly level: Schema.String;
+      readonly message: Schema.String;
+      readonly spanName: Schema.NullOr<Schema.String>;
+    }>>;
+  }>>;
+}>>;
+export declare const encodeTraceExport: (input: {
+  readonly version: 1;
+  readonly serviceName: string;
+  readonly exportedAt: number;
+  readonly spans: readonly {
+    readonly spanId: string;
+    readonly parentSpanId?: string | undefined;
+    readonly name: string;
+    readonly startTime: number;
+    readonly endTime: number | null;
+    readonly status: "error" | "ok" | "running";
+    readonly errorMessage?: string | undefined;
+    readonly attributes: {
+      readonly [x: string]: unknown;
+    };
+    readonly logs: readonly {
+      readonly timestamp: number;
+      readonly level: string;
+      readonly message: string;
+      readonly spanName: string | null;
+    }[];
+  }[];
+}, options?: import("effect/SchemaAST").ParseOptions) => import("effect/Effect").Effect<string, Schema.SchemaError, never>;
+export declare const decodeTraceExport: (input: string, options?: import("effect/SchemaAST").ParseOptions) => import("effect/Effect").Effect<{
+  readonly version: 1;
+  readonly serviceName: string;
+  readonly exportedAt: number;
+  readonly spans: readonly {
+    readonly spanId: string;
+    readonly parentSpanId?: string | undefined;
+    readonly name: string;
+    readonly startTime: number;
+    readonly endTime: number | null;
+    readonly status: "error" | "ok" | "running";
+    readonly errorMessage?: string | undefined;
+    readonly attributes: {
+      readonly [x: string]: unknown;
+    };
+    readonly logs: readonly {
+      readonly timestamp: number;
+      readonly level: string;
+      readonly message: string;
+      readonly spanName: string | null;
+    }[];
+  }[];
+}, Schema.SchemaError, never>;
+export type TraceVisualizeOptions = {
+  readonly serviceName: string;
+  /** Called when the user presses `e` to export the trace. */
+  readonly onExport?: (data: TraceExport) => void;
+};
+/**
+ * Wraps an Effect program with OTEL tracing and visualizes the trace
+ * in a real-time TUI with spinners for active spans.
+ *
+ * @example
+ * ```ts
+ * import { BunRuntime } from "@effect/platform-bun"
+ * import { Effect } from "effect"
+ * import { traceVisualize, withTracedSpan } from "shoe-box-spanoptic"
+ *
+ * const program = Effect.gen(function* () {
+ *   yield* Effect.log("Starting...")
+ *   yield* Effect.sleep("100 millis")
+ *   yield* Effect.log("Done!")
+ *   return "done"
+ * }).pipe(withTracedSpan("main"))
+ *
+ * BunRuntime.runMain(traceVisualize(program, { serviceName: "my-app" }))
+ * ```
+ */
+export declare const traceVisualize: <A, E, R>(effect: Effect.Effect<A, E, R>, options: TraceVisualizeOptions) => Effect.Effect<A, E, Exclude<Exclude<Exclude<R, OtelTracer.OtelTracer>, never>, import("effect/Scope").Scope>>;
+/**
+ * Replays a previously exported trace in the TUI.
+ *
+ * @example
+ * ```ts
+ * import { BunRuntime, BunServices } from "@effect/platform-bun"
+ * import { Effect, FileSystem } from "effect"
+ * import { decodeTraceExport, replayVisualize } from "shoe-box-spanoptic"
+ *
+ * const program = Effect.gen(function* () {
+ *   const fs = yield* FileSystem.FileSystem
+ *   const data = yield* decodeTraceExport(yield* fs.readFileString("trace.json"))
+ *   yield* replayVisualize(data)
+ * })
+ * BunRuntime.runMain(program.pipe(Effect.provide(BunServices.layer)))
+ * ```
+ */
+export declare const replayVisualize: (data: TraceExport, options?: Pick<TraceVisualizeOptions, 'onExport'>) => Effect.Effect<void, never, never>;
+/**
+ * Wraps an effect in an Effect log span and a tracing span of the same name.
+ * The TUI attaches logs to the current tracing span, so plain
+ * `Effect.withSpan` works too; the log span adds the span name to console
+ * log output when the program runs outside the TUI.
+ *
+ * @example
+ * ```ts
+ * const myEffect = Effect.gen(function* () {
+ *   yield* Effect.log("This log will be associated with mySpan");
+ *   return "result";
+ * }).pipe(withTracedSpan("mySpan"));
+ * ```
+ */
+export declare const withTracedSpan: (name: string, options?: Tracer.SpanOptionsNoTrace) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Tracer.ParentSpan>>;
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/trace.ts","../src/index.ts"],"mappings":";;qBAEa,UAAQ,OAAA;;;;;;YAMT,kBAAkB,SAAS;qBAK1B,UAAQ,OAAA;;;;;;;;;;;;;;;;YAYT,kBAAkB,SAAS;;qBAG1B,aAAW,OAAA;;;;;;;;;;;;;;;;;;;;;YAMZ,qBAAqB,YAAY;;qBAGhC,iBAAe,OAAA,eAAA,OAAA;;;;;;;;;;;;;;;;;;;;;qBAEf,oBAAiB;;;;;;;;;;;;;;;;;;;;;;GAAuC,qCAAA,yCAAA,eAAA,OAAA;qBACxD,oBAAiB,eAAA,qCAAA,yCAAA;;;;;;;;;;;;;;;;;;;;;;GAAuC,OAAA;YCiBzD;WACD;;WAEA,YAAY,MAAM;;;;;;;;;;;;;;;;;;;;;;qBA2lBhB,iBAAkB,GAAG,GAAG,GAAC,QAC5B,OAAO,OAAO,GAAG,GAAG,IAAE,SACrB,0BAAqB,OAAA,OAAA,GAAA,GAAA,QAAA,QAAA,QAAA,GAAA,WAAA,4CAAA;;;;;;;;;;;;;;;;;;qBAyDnB,kBAAe,MACpB,aAAW,UACP,KAAK,uCAAkC,OAAA;;;;;;;;;;;;;;;qBA0BtC,iBAAc,cACZ,UAAY,OAAO,wBAC/B,GAAG,GAAG,GAAC,QAAU,OAAO,OAAO,GAAG,GAAG,OAAE,OAAA,OAAA,GAAA,GAAA,QAAA,GAAA,OAAA"}

package/dist/index.mjs

@@ -0,0 +1 @@
+export { i as LogEntry, a as SpanInfo, o as TraceExport, s as TraceExportJson, c as decodeTraceExport, l as encodeTraceExport, t as replayVisualize, n as traceVisualize, r as withTracedSpan } from "./src-Cnnn7RBN.mjs";