@kitlangton/motel 0.2.1 → 0.2.5

package/AGENTS.md

@@ -31,6 +31,18 @@
 - Effect LSP diagnostics over the whole project: `bunx effect-language-service diagnostics --project tsconfig.json --format text`
 - Effect LSP interactive setup wizard: `bunx effect-language-service setup`
 
+## Release Strategy
+- npm package: `@kitlangton/motel`
+- Current published npm `latest`: `0.2.4` (`npm view @kitlangton/motel dist-tags --json`)
+- Tags are versioned as `vX.Y.Z` (`git tag --sort=-version:refname` shows `v0.2.4`, `v0.2.3`, ...)
+- Publishing is handled by GitHub Actions in `.github/workflows/publish.yml`, not by local manual `npm publish`
+- The publish workflow triggers on `git push` of tags matching `v*` or via manual `workflow_dispatch`
+- The workflow runs `bun install --frozen-lockfile`, `bun run typecheck`, `bun run test`, then `npm publish --provenance`
+- `npm publish` runs `prepublishOnly`, which builds the web UI via `bun run web:build`
+- Before tagging a release, make sure the committed `package.json` version matches the intended git tag exactly
+- Preferred release flow: update `package.json` version, commit the release changes, create tag `v<package.json version>`, push the commit and tag, then verify the GitHub Actions publish and npm dist-tags
+- Do not create or push release tags from a dirty worktree with unrelated uncommitted changes; ask before including unrelated edits in a release
+
 ## Effect LSP
 The repo is wired up with `@effect/language-service` as a `tsconfig.json` `plugins` entry. Editors that pick up the TypeScript workspace plugin (Zed, VSCode, Cursor, NVim via vtsls) will surface Effect-specific diagnostics, quick fixes, and refactors inline. In Zed this requires selecting the workspace TypeScript version — it does so automatically when `node_modules/typescript` is present.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitlangton/motel",
-  "version": "0.2.1",
+  "version": "0.2.5",
   "description": "A local OpenTelemetry ingest + TUI viewer for development, backed by SQLite.",
   "type": "module",
   "license": "MIT",
@@ -65,9 +65,13 @@
     "search-spans": "bun run src/cli.ts search-spans",
     "trace-stats": "bun run src/cli.ts trace-stats",
     "log-stats": "bun run src/cli.ts log-stats",
-    "web:dev": "cd web && npx vite",
-    "web:build": "cd web && npx vite build",
+    "web:dev": "bun run --cwd web dev",
+    "web:build": "bun run --cwd web build",
     "story:chat": "bun run src/storybook/aiChatStory.tsx",
+    "bench:motel-cold-start": "bun run scripts/bench-motel-cold-start.ts",
+    "bench:ingest-logs": "bun run scripts/bench-ingest-logs.ts",
+    "bench:ingest-traces": "bun run scripts/bench-ingest-traces.ts",
+    "bench:search-spans": "bun run scripts/bench-search-spans.ts",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "bun run web:build"
   },

package/src/App.tsx

@@ -7,6 +7,7 @@ import { Divider, FooterHints, HelpModal, PlainLine, SplitDivider, TextLine } fr
 import { useAppLayout } from "./ui/app/useAppLayout.ts"
 import { useTraceScreenData } from "./ui/app/useTraceScreenData.ts"
 import { TraceWorkspace } from "./ui/app/TraceWorkspace.tsx"
+import { startupBenchMark } from "./startupBench.js"
 import {
 	type AttrFacetState,
 	attrPickerIndexAtom,
@@ -28,10 +29,12 @@ import { applyTheme, colors, SEPARATOR, themeLabel } from "./ui/theme.ts"
 import { useKeyboardNav } from "./ui/useKeyboardNav.ts"
 import { AttrFilterModal } from "./ui/AttrFilterModal.tsx"
 import { useAttrFilterPicker } from "./ui/useAttrFilterPicker.ts"
-import { getVisibleSpans } from "./ui/Waterfall.tsx"
+import { getVisibleSpans } from "./ui/waterfallModel.ts"
 
 const NOTICE_TIMEOUT_MS = 2500
 
+startupBenchMark("app_module_loaded")
+
 const buildHeaderModel = ({
 	headerFooterWidth,
 	selectedTraceService,
@@ -177,6 +180,7 @@ const AppOverlays = ({
 )
 
 export const App = () => {
+	startupBenchMark("app_render_started")
 	const { width, height } = useTerminalDimensions()
 	const [notice, setNotice] = useAtom(noticeAtom)
 	const [selectedTheme] = useAtom(selectedThemeAtom)
@@ -261,6 +265,10 @@ export const App = () => {
 		persistSelectedTheme(selectedTheme)
 	}, [selectedTheme])
 
+	useEffect(() => {
+		startupBenchMark("app_effects_committed")
+	}, [])
+
 	const { spanNavActive } = useKeyboardNav({
 		selectedTrace,
 		filteredTraces,
@@ -337,6 +345,7 @@ export const App = () => {
 	// above an empty column and leaves a visible stale sliver when
 	// toggling tab back and forth with the trace view.
 	const showSplit = isWideLayout && detailView !== "service-logs"
+	startupBenchMark("app_render_ready")
 
 	return (
 		<box width={width ?? 100} height={height ?? 24} flexGrow={1} flexDirection="column" backgroundColor={RGBA.fromHex(colors.screenBg)}>

package/src/StartupGate.tsx

@@ -0,0 +1,291 @@
+import { Effect } from "effect"
+import { RGBA, TextAttributes } from "@opentui/core"
+import { useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react"
+import { useEffect, useMemo, useState } from "react"
+import { App } from "./App.js"
+import { createDaemonManager, ensureManagedDaemon, getManagedDaemonStatus, type DaemonStatus } from "./daemon.js"
+import { MOTEL_SERVICE_ID } from "./registry.js"
+import { Divider, PlainLine, TextLine } from "./ui/primitives.tsx"
+import { colors } from "./ui/theme.ts"
+
+type ConflictStatus = DaemonStatus & {
+	readonly service: typeof MOTEL_SERVICE_ID
+	readonly pid: number
+	readonly workdir: string
+	readonly reason: string
+	readonly sameWorkdir: false
+}
+
+type ConflictScreenState = {
+	kind: "conflict"
+	message: string
+	status: ConflictStatus
+	busy: boolean
+	notice: string | null
+}
+
+type ErrorScreenState = {
+	kind: "error"
+	message: string
+	busy: boolean
+	notice: string | null
+}
+
+type StartupState =
+	| { kind: "loading"; message: string }
+	| { kind: "ready" }
+	| ConflictScreenState
+	| ErrorScreenState
+
+type RecoveryAction = {
+	readonly key: string
+	readonly label: string
+	readonly run: () => Promise<void>
+	readonly disabled?: boolean
+}
+
+const readStatus = () => Effect.runPromise(getManagedDaemonStatus)
+const startDaemon = () => Effect.runPromise(ensureManagedDaemon)
+
+const parsePort = (url: string) => {
+	try {
+		const port = Number(new URL(url).port)
+		return Number.isFinite(port) && port > 0 ? port : undefined
+	} catch {
+		return undefined
+	}
+}
+
+const isRecoverableConflict = (status: DaemonStatus | null): status is ConflictStatus =>
+	status !== null &&
+	status.service === MOTEL_SERVICE_ID &&
+	status.pid !== null &&
+	status.workdir !== null &&
+	status.reason !== null &&
+	!status.sameWorkdir
+
+const stopConflictingDaemon = async (status: ConflictStatus) => {
+	const port = parsePort(status.url)
+	const manager = createDaemonManager({
+		workdir: status.workdir ?? undefined,
+		databasePath: status.databasePath,
+		port,
+	})
+	await Effect.runPromise(manager.stop)
+}
+
+const LoadingScreen = ({ width, height, message }: { width: number; height: number; message: string }) => {
+	const panelWidth = Math.min(76, Math.max(50, width - 8))
+	const left = Math.max(0, Math.floor((width - panelWidth) / 2))
+	const top = Math.max(0, Math.floor((height - 5) / 2))
+
+	return (
+		<box width={width} height={height} backgroundColor={RGBA.fromHex(colors.screenBg)}>
+			<box position="absolute" left={left} top={top} width={panelWidth} flexDirection="column">
+				<TextLine>
+					<span fg={colors.accent} attributes={TextAttributes.BOLD}>MOTEL</span>
+					<span fg={colors.separator}>{" · "}</span>
+					<span fg={colors.muted}>starting up...</span>
+				</TextLine>
+				<Divider width={panelWidth} />
+				<box paddingTop={1}>
+					<PlainLine text={message} fg={colors.count} />
+				</box>
+			</box>
+		</box>
+	)
+}
+
+const RecoveryScreen = ({
+	title,
+	message,
+	width,
+	height,
+	detailLines,
+	actions,
+	selectedIndex,
+	notice,
+	busy,
+}: {
+	readonly title: string
+	readonly message: string
+	readonly width: number
+	readonly height: number
+	readonly detailLines: readonly string[]
+	readonly actions: readonly RecoveryAction[]
+	readonly selectedIndex: number
+	readonly notice: string | null
+	readonly busy: boolean
+}) => {
+	const panelWidth = Math.min(96, Math.max(64, width - 8))
+	const left = Math.max(0, Math.floor((width - panelWidth) / 2))
+	const bodyHeight = 9 + detailLines.length + actions.length + (notice ? 2 : 0)
+	const top = Math.max(0, Math.floor((height - bodyHeight) / 2))
+
+	return (
+		<box width={width} height={height} backgroundColor={RGBA.fromHex(colors.screenBg)}>
+			<box position="absolute" left={left} top={top} width={panelWidth} flexDirection="column">
+				<TextLine>
+					<span fg={colors.accent} attributes={TextAttributes.BOLD}>MOTEL</span>
+					<span fg={colors.separator}>{" · "}</span>
+					<span fg={colors.error} attributes={TextAttributes.BOLD}>{title}</span>
+				</TextLine>
+				<Divider width={panelWidth} />
+				<box paddingTop={1} paddingBottom={1} flexDirection="column">
+					<PlainLine text={message} fg={colors.text} />
+				</box>
+				{detailLines.map((line, index) => (
+					<PlainLine key={`${index}:${line}`} text={line} fg={colors.muted} />
+				))}
+				<box paddingTop={1} flexDirection="column">
+					{actions.map((action, index) => {
+						const selected = index === selectedIndex
+						const prefix = selected ? ">" : " "
+						const text = `${prefix} [${action.key}] ${action.label}${action.disabled ? " (unavailable)" : ""}`
+						return (
+							<TextLine key={action.key} bg={selected ? colors.selectedBg : undefined}>
+								<span fg={selected ? colors.selectedText : colors.text}>{text}</span>
+							</TextLine>
+						)
+					})}
+				</box>
+				<box paddingTop={1} flexDirection="column">
+					{notice ? <PlainLine text={notice} fg={busy ? colors.warning : colors.count} /> : null}
+					<PlainLine text={busy ? "Working..." : "j/k or ↑↓ select · enter run · r retry · k kill conflicting daemon · q quit"} fg={colors.count} />
+				</box>
+			</box>
+		</box>
+	)
+}
+
+export const StartupGate = () => {
+	const renderer = useRenderer()
+	const { width = 100, height = 24 } = useTerminalDimensions()
+	const [startupState, setStartupState] = useState<StartupState>({ kind: "loading", message: "Checking managed daemon..." })
+	const [selectedIndex, setSelectedIndex] = useState(0)
+
+	const attemptStart = async () => {
+		setStartupState({ kind: "loading", message: "Checking managed daemon..." })
+		try {
+			await startDaemon()
+			setStartupState({ kind: "ready" })
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error)
+			const status = await readStatus().catch(() => null)
+			if (isRecoverableConflict(status)) {
+				setSelectedIndex(0)
+				setStartupState({ kind: "conflict", message, status, busy: false, notice: null })
+				return
+			}
+			setSelectedIndex(0)
+			setStartupState({ kind: "error", message, busy: false, notice: null })
+		}
+	}
+
+	useEffect(() => {
+		void attemptStart()
+	}, [])
+
+	const actions = useMemo<readonly RecoveryAction[]>(() => {
+		if (startupState.kind === "conflict") {
+			return [
+				{ key: "r", label: "Retry startup", run: attemptStart },
+				{
+					key: "k",
+					label: `Stop conflicting daemon (${startupState.status.pid})`,
+					run: async () => {
+						setStartupState((current) => current.kind === "conflict"
+							? { ...current, busy: true, notice: `Stopping daemon ${current.status.pid}...` }
+							: current)
+						try {
+							await stopConflictingDaemon(startupState.status)
+							await attemptStart()
+						} catch (error) {
+							const message = error instanceof Error ? error.message : String(error)
+							setStartupState((current) => current.kind === "conflict"
+								? { ...current, busy: false, notice: message }
+								: current)
+						}
+					},
+				},
+				{ key: "q", label: "Quit", run: async () => { renderer.destroy() } },
+			]
+		}
+		if (startupState.kind === "error") {
+			return [
+				{ key: "r", label: "Retry startup", run: attemptStart },
+				{ key: "q", label: "Quit", run: async () => { renderer.destroy() } },
+			]
+		}
+		return []
+	}, [renderer, startupState])
+
+	useKeyboard((key) => {
+		if (startupState.kind === "ready" || startupState.kind === "loading" || key.repeated) return
+		if (key.name === "q" || (key.ctrl && key.name === "c")) {
+			renderer.destroy()
+			return
+		}
+		if (key.name === "up" || key.name === "k") {
+			setSelectedIndex((current) => (current + actions.length - 1) % actions.length)
+			return
+		}
+		if (key.name === "down" || key.name === "j") {
+			setSelectedIndex((current) => (current + 1) % actions.length)
+			return
+		}
+		if (key.name === "r") {
+			void actions.find((action) => action.key === "r")?.run()
+			return
+		}
+		if (key.name === "k") {
+			void actions.find((action) => action.key === "k")?.run()
+			return
+		}
+		if (key.name === "return" || key.name === "enter") {
+			void actions[selectedIndex]?.run()
+		}
+	})
+
+	if (startupState.kind === "ready") return <App />
+	if (startupState.kind === "loading") return <LoadingScreen width={width} height={height} message={startupState.message} />
+	if (startupState.kind === "conflict") {
+		const status = startupState.status
+		const detailLines = [
+			`Port: ${status.url}`,
+			`Conflicting workdir: ${status.workdir}`,
+			`Conflicting pid: ${status.pid}`,
+			`Database: ${status.databasePath}`,
+			status.workdir.startsWith("/tmp") || status.workdir.startsWith("/private/tmp")
+				? "This looks like a temp/test daemon."
+				: "This looks like a real motel daemon started from another project.",
+		]
+		return (
+			<RecoveryScreen
+				title="Daemon Conflict"
+				message={startupState.message}
+				width={width}
+				height={height}
+				detailLines={detailLines}
+				actions={actions}
+				selectedIndex={selectedIndex}
+				notice={startupState.notice}
+				busy={startupState.busy}
+			/>
+		)
+	}
+
+	return (
+		<RecoveryScreen
+			title="Startup Error"
+			message={startupState.message}
+			width={width}
+			height={height}
+			detailLines={["Retry startup or quit the TUI."]}
+			actions={actions}
+			selectedIndex={selectedIndex}
+			notice={startupState.notice}
+			busy={startupState.busy}
+		/>
+	)
+}

package/src/daemon.test.ts

@@ -1,3 +1,4 @@
+import { Database } from "bun:sqlite"
 import { afterEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
 import * as fs from "node:fs"
@@ -30,6 +31,16 @@ const makeHarness = (): Harness => {
 	return { runtimeDir, port, databasePath, manager }
 }
 
+const withCwd = async <A>(cwd: string, f: () => Promise<A>): Promise<A> => {
+	const previous = process.cwd()
+	process.chdir(cwd)
+	try {
+		return await f()
+	} finally {
+		process.chdir(previous)
+	}
+}
+
 /**
  * Start a motel-shaped HTTP server on a test port that answers
  * /api/health with an arbitrary delay. Used to simulate a real daemon
@@ -193,4 +204,63 @@ describe("daemon manager", () => {
 		const finalStatus = await Effect.runPromise(harness.manager.getStatus)
 		expect(finalStatus.running).toBe(false)
 	})
+
+	test("becomes healthy even if trace summary rebuild hits a write lock", async () => {
+		const harness = makeHarness()
+		activeHarnesses.push(harness)
+
+		const firstStart = await Effect.runPromise(harness.manager.ensure)
+		expect(firstStart.running).toBe(true)
+		await Effect.runPromise(harness.manager.stop)
+
+		const locker = new Database(harness.databasePath)
+		locker.exec("BEGIN IMMEDIATE")
+		try {
+			const startedAt = performance.now()
+			const restarted = await Effect.runPromise(harness.manager.ensure)
+			const elapsed = performance.now() - startedAt
+			expect(restarted.running).toBe(true)
+			expect(restarted.managed).toBe(true)
+			expect(elapsed).toBeLessThan(10_000)
+		} finally {
+			locker.exec("ROLLBACK")
+			locker.close()
+		}
+	}, 20_000)
+
+	test("starts for the caller cwd even when motel is installed elsewhere", async () => {
+		const projectDir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "motel-daemon-project-")))
+		const databasePath = path.join(projectDir, ".motel-data", "telemetry.sqlite")
+		let manager: ReturnType<typeof createDaemonManager> | null = null
+
+		try {
+			await withCwd(projectDir, async () => {
+				manager = createDaemonManager({
+					repoRoot,
+					port: randomPort(),
+				})
+
+				const started = await Effect.runPromise(manager.ensure)
+				expect(started.running).toBe(true)
+				expect(started.managed).toBe(true)
+				expect(started.workdir).toBe(projectDir)
+				expect(started.sameWorkdir).toBe(true)
+				expect(started.databasePath).toBe(databasePath)
+				expect(started.logPath).toBe(path.join(projectDir, ".motel-data", "daemon.log"))
+
+				const reused = await Effect.runPromise(manager.ensure)
+				expect(reused.pid).toBe(started.pid)
+
+				const stopped = await Effect.runPromise(manager.stop)
+				expect(stopped.running).toBe(false)
+			})
+		} finally {
+			await withCwd(projectDir, async () => {
+				if (manager) {
+					await Effect.runPromise(manager.stop).catch(() => undefined)
+				}
+			})
+			fs.rmSync(projectDir, { recursive: true, force: true })
+		}
+	})
 })