@kitlangton/motel 0.1.0 → 0.1.1

package/README.md

@@ -1,199 +1,106 @@
 # motel
 
-A local OpenTelemetry ingest + TUI viewer for development, backed by SQLite.
-Point your app's OTLP/HTTP exporters at the local motel server and browse
-traces, spans, and logs from a terminal or the built-in web UI.
+A local OpenTelemetry ingest + TUI viewer for development, backed by
+SQLite. Point your app's OTLP/HTTP exporters at the local motel server
+and debug with real runtime evidence — from a terminal, the built-in web
+UI, or directly from an AI coding agent.
 
-## Install
+## For agents: install the motel-debug skill
 
-```bash
-bun add -g @kitlangton/motel
-motel
-```
-
-(or `bunx @kitlangton/motel` for a one-off run without installing.)
-
-## Requirements
-
-- [Bun](https://bun.sh/) — v1.1 or newer
-
-## Install the motel-debug skill
-
-`motel` ships a companion skill that teaches agents (Claude Code, OpenCode,
-Cursor, Codex, and 40+ others) how to debug with runtime evidence by
-querying motel's local OTLP store. Install it with a one-liner via
-[`npx skills`](https://github.com/vercel-labs/skills):
+`motel` ships a companion skill that teaches Claude Code, OpenCode,
+Cursor, Codex, and 40+ other agents how to debug with runtime evidence
+by querying motel's local OTLP store. Install it once and any future
+agent session in the project will know how to use it.
 
 ```bash
 # Project-local (adds to .claude/skills, .agents/skills, etc.)
 npx skills add kitlangton/motel --skill motel-debug
 
-# Globally, available in every project
+# Or globally, for every project
 npx skills add kitlangton/motel --skill motel-debug -g
-
-# Target a specific agent only
-npx skills add kitlangton/motel --skill motel-debug -a claude-code
 ```
 
-The skill lives at [`skills/motel-debug/`](skills/motel-debug/) in this repo.
-
-## Quick start
+See the full skill at [`skills/motel-debug/SKILL.md`](skills/motel-debug/SKILL.md).
 
-```bash
-bun install
-bun run dev
-```
-
-`bun run dev` starts the local OTLP ingest server (on `http://127.0.0.1:27686`)
-and launches the TUI. Press `?` once inside for the keyboard cheat sheet, or
-`c` to copy paste-ready setup instructions for another Effect/OTEL app.
+## For humans: install and run the TUI
 
-If you just want the server without the TUI (for example, to run it in the
-background and browse the web UI):
+motel is distributed on npm as `@kitlangton/motel`. The binary is a Bun
+script, so Bun must be on your `PATH` at runtime:
 
 ```bash
-bun run server
-# then in another terminal
-bun run web:dev
-```
-
-## Commands
-
-- `bun install`
-- `bun run server`
-- `bun run dev`
-- `bun run test`
-- `bun run cli services`
-- `bun run cli traces <service>`
-- `bun run cli span <span-id>`
-- `bun run cli search-traces <service> [operation]`
-- `bun run cli trace-stats <groupBy> <agg> [service]`
-- `bun run cli logs <service>`
-- `bun run cli search-logs <service> [body]`
-- `bun run cli log-stats <groupBy> [service]`
-- `bun run cli trace-logs <trace-id>`
-- `bun run cli facets <traces|logs> <field>`
-- `bun run instructions`
-- `bun run typecheck`
+# one-off (no install)
+bunx @kitlangton/motel
 
-## Local ports
-
-This repo uses one local Bun server with SQLite storage. No Docker is required.
-
-- motel local API / UI base: `http://127.0.0.1:27686`
-- OTLP HTTP traces: `http://127.0.0.1:27686/v1/traces`
-- OTLP HTTP logs: `http://127.0.0.1:27686/v1/logs`
-- health: `http://127.0.0.1:27686/api/health`
-
-Other local apps can send telemetry to:
+# or install globally
+bun add -g @kitlangton/motel
+motel
 
-```bash
-http://127.0.0.1:27686/v1/traces
-http://127.0.0.1:27686/v1/logs
+# npm also works (Bun still required to run it)
+npm install -g @kitlangton/motel
 ```
 
-Agents and scripts can query traces and logs from the local API:
+Don't have Bun?
 
 ```bash
-http://127.0.0.1:27686/api/services
-http://127.0.0.1:27686/api/traces?service=<service>&limit=20&lookback=1h
-http://127.0.0.1:27686/api/traces/search?service=<service>&operation=proxy&status=error&attr.sessionID=<session-id>
-http://127.0.0.1:27686/api/traces/stats?groupBy=operation&agg=p95_duration&service=<service>
-http://127.0.0.1:27686/api/spans/<span-id>
-http://127.0.0.1:27686/api/spans/<span-id>/logs
-http://127.0.0.1:27686/api/spans/search?service=<service>&operation=Format.file&parentOperation=Tool.write&attr.sessionID=<session-id>
-http://127.0.0.1:27686/api/traces/<trace-id>/spans
-http://127.0.0.1:27686/api/logs?service=<service>&body=proxy_request
-http://127.0.0.1:27686/api/logs?service=<service>&attr.service.name=<service>
-http://127.0.0.1:27686/api/logs/stats?groupBy=severity&agg=count&service=<service>
-http://127.0.0.1:27686/api/facets?type=logs&field=severity
-http://127.0.0.1:27686/openapi.json
-http://127.0.0.1:27686/docs
+curl -fsSL https://bun.sh/install | bash
 ```
 
-## TUI keys
-
-- `?`: show or hide keyboard shortcut help
-- `j` / `k` or `up` / `down`: move selection
-- `ctrl-n` / `ctrl-p`: switch traces even while in trace details
-- `gg` or `home`: jump to the first trace or first span
-- `G` or `end`: jump to the last trace or last span
-- `ctrl-u` / `pageup`: move up by one page
-- `ctrl-d` / `pagedown`: move down by one page
-- `l`: toggle service logs mode
-- `[` / `]`: switch service
-- `enter`: enter span navigation or open selected span detail
-- `esc`: leave span detail or span navigation
-- `r`: refresh
-- `c`: copy a paste-ready Effect setup prompt for another app
-- `o`: open selected trace in browser
-- `q`: quit
-
-## How It Works
-
-`motel` now has one local service process:
-
-- the local Bun server receives OTLP traces and logs on `http://127.0.0.1:27686`
-- it stores telemetry in SQLite at `.motel-data/telemetry.sqlite`
-- it exposes query endpoints on the same base URL
-
-So yes: another service has to point its OTEL exporters at this local motel instance.
-
-## Privacy Note
-
-`motel` is a local observability tool, and it can store sensitive telemetry content if the upstream app emits it.
+`motel` starts the local OTLP ingest server on
+`http://127.0.0.1:27686` and launches the TUI. Press `?` once inside for
+the keyboard cheat sheet, or `c` to copy paste-ready setup instructions
+for any Effect/OTEL app you want to trace.
 
-- correlated logs may include secrets, tokens, or PII if your app logs them
-- AI call data may include prompt previews, response previews, full prompt content, response text, tool metadata, and provider metadata
-- treat the local SQLite store as sensitive development data when using motel against real workloads
+Requirements: [Bun](https://bun.sh/) v1.1 or newer.
 
-The easiest flow is:
+## How your app connects
 
-1. Run `bun run dev` here. That starts the local server if needed and then launches the TUI.
-2. In `motel`, press `c`.
-3. Paste the copied instructions into an agent working in the other service.
-4. Have that service export OTEL traces to `http://127.0.0.1:27686/v1/traces` and OTEL logs to `http://127.0.0.1:27686/v1/logs`.
-5. Refresh `motel`, switch to that service with `[` / `]`, and use `l` or `enter` to inspect logs under a trace or span.
+Once motel is running, point your app's OTLP/HTTP exporters at these
+local endpoints:
 
-## For Agents
-
-An agent does not need to talk to the TUI.
+```
+http://127.0.0.1:27686/v1/traces
+http://127.0.0.1:27686/v1/logs
+```
 
-List and search endpoints now return a `meta` object with `limit`, `lookback`, `returned`, `truncated`, and `nextCursor` so callers can page safely instead of assuming they received all results.
+Motel keeps everything in a local SQLite database at
+`.motel-data/telemetry.sqlite`. No Docker, no cloud account.
 
-Use one of these:
+## How agents connect
 
-1. motel HTTP API directly
+Agents with the `motel-debug` skill installed will automatically use
+motel's HTTP API. The full OpenAPI spec is at
+`http://127.0.0.1:27686/openapi.json` — the key endpoints are:
 
-```bash
-curl http://127.0.0.1:27686/api/services
-curl "http://127.0.0.1:27686/api/traces?service=my-service&limit=20&lookback=1h"
-curl http://127.0.0.1:27686/api/traces/<trace-id>
 ```
-
-2. The local CLI wrapper in this repo
-
-```bash
-bun run cli services
-bun run cli traces my-service 20
-bun run cli span <span-id>
-bun run cli trace-spans <trace-id>
-bun run cli search-spans my-service Format.file parent=Tool.write attr.sessionID=sess_123
-bun run cli search-traces my-service proxy attr.sessionID=sess_123
-bun run cli trace-stats operation p95_duration my-service attr.modelID=gpt-5.4
-bun run cli trace <trace-id>
-bun run cli logs my-service
-bun run cli search-logs my-service timeout attr.tool=search
-bun run cli log-stats severity my-service attr.tool=search
-bun run cli trace-logs <trace-id>
-bun run cli span-logs <span-id>
-bun run cli facets logs severity
-bun run instructions
+GET /api/health                              liveness check
+GET /api/services                            services reporting telemetry
+GET /api/traces?service=<service>            recent traces for a service
+GET /api/traces/<trace-id>                   full trace tree
+GET /api/spans/<span-id>                     single span + logs
+GET /api/logs?service=<service>              recent logs
+GET /api/traces/search?...                   structured trace search
+GET /api/logs/search?...                     structured log search
+GET /api/ai/calls                            AI SDK call inspector
 ```
 
-Recommended shape going forward:
+## TUI keys
 
-1. Keep motel as the single ingest point for apps.
-2. Keep SQLite as the local source of truth.
-3. Keep `motel` as the interactive viewer.
-4. Keep the CLI and HTTP API as the agent/script interfaces.
+- `?` — keyboard cheat sheet
+- `j` / `k` or `↑` / `↓` — move selection
+- `enter` / `esc` — drill in / back out (trace → waterfall → span detail)
+- `[` / `]` — switch service
+- `tab` — toggle service logs
+- `/` — filter traces
+- `s` — cycle sort (recent → slowest → errors)
+- `t` — cycle theme
+- `c` — copy paste-ready setup instructions for another app
+- `o` — open selected trace in the browser
+- `q` — quit
+
+## Privacy note
+
+motel is a local development tool, but your app can emit sensitive
+telemetry. Correlated logs may include secrets, tokens, or PII if your
+app logs them; AI call traces may include full prompt content and
+response text. Treat the local SQLite store as sensitive development
+data when pointing motel at real workloads.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitlangton/motel",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A local OpenTelemetry ingest + TUI viewer for development, backed by SQLite.",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,9 @@
     "effect",
     "opentui"
   ],
-  "workspaces": ["web"],
+  "workspaces": [
+    "web"
+  ],
   "engines": {
     "bun": ">=1.1.0"
   },

package/src/ui/Waterfall.tsx

@@ -169,16 +169,16 @@ const durationColor = (durationMs: number) => {
 	return colors.muted
 }
 
-export const getWaterfallLayout = (contentWidth: number, traceDurationMs: number, includeLogs = true) => {
+export const getWaterfallLayout = (contentWidth: number, traceDurationMs: number) => {
 	const labelMaxWidth = Math.min(Math.floor(contentWidth * 0.4), 32)
 	const durationWidth = Math.max(8, formatDuration(traceDurationMs).length + 1)
-	const logWidth = includeLogs ? 5 : 0
+	const logWidth = 5
 	const barWidth = Math.max(6, contentWidth - labelMaxWidth - durationWidth - logWidth - 2)
 	return { labelMaxWidth, durationWidth, logWidth, barWidth } as const
 }
 
-export const getWaterfallColumns = (contentWidth: number, traceDurationMs: number, durationMs: number, logCount: number, includeLogs = true) => {
-	const { labelMaxWidth, durationWidth, logWidth, barWidth } = getWaterfallLayout(contentWidth, traceDurationMs, includeLogs)
+export const getWaterfallColumns = (contentWidth: number, traceDurationMs: number, durationMs: number, logCount: number) => {
+	const { labelMaxWidth, durationWidth, logWidth, barWidth } = getWaterfallLayout(contentWidth, traceDurationMs)
 	const durationCell = formatDuration(Math.max(0, durationMs)).padStart(durationWidth)
 	const logText = logCount > 0 ? `${logCount}lg` : ""
 	const logCell = logText.padStart(logWidth)
@@ -219,7 +219,6 @@ const WaterfallRow = memo(({
 	collapsed,
 	hasChildSpans,
 	onSelect,
-	includeLogs,
 }: {
 	span: TraceSpanItem
 	logCount: number
@@ -231,14 +230,13 @@ const WaterfallRow = memo(({
 	collapsed: boolean
 	hasChildSpans: boolean
 	onSelect: () => void
-	includeLogs: boolean
 }) => {
 	const prefix = buildTreePrefix(spans, index)
 	// Match the trace list indicator: `!` on error, chevron on collapsible parents, `·` on leaves.
 	const indicator = span.status === "error" ? "!" : hasChildSpans ? (collapsed ? "\u25b8" : "\u25be") : "\u00b7"
 	const opName = span.isRunning ? `${span.operationName} [${lifecycleLabel(span)}]` : span.operationName
 
-	const { labelMaxWidth, barWidth, durationCell, logCell } = getWaterfallColumns(contentWidth, trace.durationMs, span.durationMs, logCount, includeLogs)
+	const { labelMaxWidth, barWidth, durationCell, logCell } = getWaterfallColumns(contentWidth, trace.durationMs, span.durationMs, logCount)
 
 	const opMaxWidth = Math.max(4, labelMaxWidth - prefix.length - 2)
 	const opTruncated = opName.length > opMaxWidth ? `${opName.slice(0, opMaxWidth - 1)}\u2026` : opName
@@ -248,7 +246,7 @@ const WaterfallRow = memo(({
 	const isError = span.status === "error"
 	const barColor = selected ? (isError ? waterfallColors.barSelectedError : waterfallColors.barSelected) : isError ? waterfallColors.barError : waterfallColors.bar
 	const laneColor = selected ? waterfallColors.barLane : waterfallColors.barBg
-	const { segments, afterCells } = renderWaterfallBar(span, trace, barWidth, barColor, laneColor)
+	const { segments } = renderWaterfallBar(span, trace, barWidth, barColor, laneColor)
 	const bg = selected ? colors.selectedBg : undefined
 	const treeColor = selected ? colors.separator : colors.treeLine
 	const indicatorColor = isError ? colors.error : hasChildSpans ? (selected ? colors.selectedText : colors.muted) : colors.passing
@@ -268,10 +266,9 @@ const WaterfallRow = memo(({
 				{segments.map((segment, index) => (
 					<span key={`${span.spanId}-bar-${index}`} fg={segment.fg} bg={segment.bg}>{segment.text}</span>
 				))}
-				{afterCells > 0 ? <span fg={laneColor} bg={laneColor}>{" ".repeat(afterCells)}</span> : null}
 				<span> </span>
 				<span fg={durationFg}>{durationCell}</span>
-				{logCell.length > 0 ? <span fg={logFg}>{logCell}</span> : null}
+				<span fg={logFg}>{logCell}</span>
 			</TextLine>
 		</box>
 	)
@@ -349,7 +346,8 @@ export const WaterfallTimeline = ({
 	onSelectSpan: (index: number) => void
 }) => {
 	const selectedSpan = selectedSpanIndex !== null ? filteredSpans[selectedSpanIndex] ?? null : null
-	const includeLogs = filteredSpans.some((span) => (spanLogCounts.get(span.spanId) ?? 0) > 0)
+
+	const { labelMaxWidth, durationWidth, barWidth } = getWaterfallLayout(contentWidth, trace.durationMs)
 
 	const spanIndexById = new Map<string, number>()
 	for (let i = 0; i < trace.spans.length; i++) {
@@ -399,7 +397,6 @@ export const WaterfallTimeline = ({
 						selected={selectedSpanIndex === actualIndex}
 						collapsed={collapsedSpanIds.has(span.spanId)}
 						hasChildSpans={fullIndex >= 0 && findFirstChildIndex(trace.spans, fullIndex) !== null}
-						includeLogs={includeLogs}
 						onSelect={() => onSelectSpan(actualIndex)}
 					/>
 				)

package/src/ui/traceSortNav.repro.test.ts

@@ -60,8 +60,9 @@ const listRows = (snap: string): { readonly rows: readonly string[]; readonly se
 		const leftHalf = raw.split("\u2502")[0] ?? raw
 		const rightHalf = raw.includes("\u2502") ? raw.split("\u2502").slice(1).join("\u2502") : ""
 
-		// Trace rows: left pane, `·` then `op #hash`.
-		const rowMatch = leftHalf.match(/^\s+\u00b7\s+(\S+)\s+#/)
+		// Trace rows: left pane, `·` then the operation name as the first
+		// token. (Earlier versions appended `#<hash>`; that's been removed.)
+		const rowMatch = leftHalf.match(/^\s+\u00b7\s+(op[A-Z])\b/)
 		if (rowMatch) rows.push(rowMatch[1]!)
 
 		// Selected trace: right pane, line immediately after `TRACE DETAILS`

package/src/ui/traceDetailsWidth.repro.test.ts

@@ -1,115 +0,0 @@
-/**
- * End-to-end reproducer for waterfall underfilling the trace-details pane.
- *
- * Strategy:
- * 1. Seed a deterministic trace into a fresh SQLite database.
- * 2. Launch the motel TUI under tuistory in narrow mode so trace details take
- *    the full screen width.
- * 3. Drill into the trace details view.
- * 4. Assert the root waterfall row reaches the right-side duration column
- *    instead of stopping several cells early.
- */
-
-import { afterAll, beforeAll, describe, expect, it } from "bun:test"
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs"
-import { tmpdir } from "node:os"
-import { join } from "node:path"
-
-const TUISTORY_BIN = "tuistory"
-const SESSION = `motel-trace-width-${Date.now()}`
-
-const hasTuistory = async () => {
-	try {
-		const proc = Bun.spawn({ cmd: ["which", TUISTORY_BIN], stdout: "pipe", stderr: "ignore" })
-		return (await proc.exited) === 0
-	} catch {
-		return false
-	}
-}
-
-const tui = async (args: readonly string[]) => {
-	const proc = Bun.spawn({ cmd: [TUISTORY_BIN, ...args], stdout: "pipe", stderr: "pipe" })
-	const [stdout, stderr] = await Promise.all([
-		new Response(proc.stdout).text(),
-		new Response(proc.stderr).text(),
-	])
-	return { code: await proc.exited, stdout, stderr }
-}
-
-const snapshot = async () => (await tui(["snapshot", "--session", SESSION])).stdout
-
-const press = async (...keys: string[]) => {
-	await tui(["press", "--session", SESSION, ...keys])
-	await Bun.sleep(120)
-}
-
-const dividerWidth = (snap: string) =>
-	snap.split("\n").find((line) => line.startsWith("─"))?.length ?? 0
-
-const rootWaterfallRow = (snap: string) =>
-	snap.split("\n").find((line) => line.startsWith(" ▾ root.op") || line.startsWith(" ▸ root.op") || line.startsWith(" · root.op")) ?? null
-
-describe("trace details waterfall width (end-to-end TUI)", () => {
-	const tempDir = mkdtempSync(join(tmpdir(), "motel-trace-width-"))
-	const dbPath = join(tempDir, "telemetry.sqlite")
-	const lastServicePath = join(tempDir, "last-service.txt")
-	let canRun = false
-
-	beforeAll(async () => {
-		canRun = await hasTuistory()
-		if (!canRun) return
-
-		writeFileSync(lastServicePath, "waterfall-repro")
-
-		const seed = Bun.spawn({
-			cmd: ["bun", "run", "src/ui/waterfallNav.repro.seed.ts"],
-			cwd: process.cwd(),
-			env: {
-				...process.env,
-				MOTEL_OTEL_DB_PATH: dbPath,
-				MOTEL_OTEL_ENABLED: "false",
-			},
-			stdout: "pipe",
-			stderr: "pipe",
-		})
-		const seedCode = await seed.exited
-		if (seedCode !== 0) {
-			const err = await new Response(seed.stderr).text()
-			throw new Error(`seed failed: ${err}`)
-		}
-
-		await tui(["close", "--session", SESSION])
-		const launch = await tui([
-			"launch",
-			"bun run src/index.tsx",
-			"--session", SESSION,
-			"--cols", "96",
-			"--rows", "40",
-			"--cwd", process.cwd(),
-			"--env", `MOTEL_OTEL_DB_PATH=${dbPath}`,
-			"--env", "MOTEL_OTEL_ENABLED=false",
-			"--timeout", "15000",
-		])
-		if (launch.code !== 0) throw new Error(`launch failed: ${launch.stderr}`)
-		await tui(["wait", "root.op", "--session", SESSION, "--timeout", "10000"])
-		await tui(["wait-idle", "--session", SESSION, "--timeout", "5000"])
-	}, 60_000)
-
-	afterAll(async () => {
-		if (canRun) await tui(["close", "--session", SESSION])
-		try { rmSync(tempDir, { recursive: true, force: true }) } catch {}
-	})
-
-	it("fills the full-width trace details pane in narrow mode", async () => {
-		if (!canRun) return
-
-		await press("return")
-		const snap = await snapshot()
-		const divider = dividerWidth(snap)
-		const row = rootWaterfallRow(snap)
-
-		expect(divider).toBe(96)
-		expect(row).not.toBeNull()
-		expect(row!.length).toBeGreaterThanOrEqual(divider - 1)
-	}, 60_000)
-})