@rikalabs/logpoint 0.0.2

package/README.md

@@ -0,0 +1,104 @@
+# @rikalabs/logpoint
+
+`@rikalabs/logpoint` is a Bun + Effect CLI for runtime debugging with non-breaking HTTP logpoints.
+
+It injects temporary logpoints into source files, collects snapshots over HTTP, summarizes anomalies, and removes instrumentation cleanly.
+
+## Install
+
+```bash
+bun add -g @rikalabs/logpoint
+```
+
+If you do not install globally, use `bunx @rikalabs/logpoint <command>`.
+
+### One-Line Skill Install (Claude, Codex, OpenCode, Amp)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rika-Labs/logpoint/main/scripts/install-skill.sh | bash
+```
+
+This installs `SKILL.md` and `agents/debugger.md` into:
+
+- `~/.claude/skills/debug-logpoints/`
+- `~/.agents/skills/debug-logpoints/`
+- `~/.config/opencode/skills/debug-logpoints/`
+- `~/.config/agents/skills/debug-logpoints/`
+
+## Commands
+
+```bash
+logpoint collector [--port 9111] [--timeout 300] [--output /tmp/debug-logpoints.jsonl] [--cors-origin *]
+logpoint inject --manifest /tmp/logpoints.json [--project-root .] [--language <lang>] [--dry-run]
+logpoint analyze [--input /tmp/debug-logpoints.jsonl] [--format markdown|json]
+logpoint cleanup [--dir .] [--ids hp1,hp2] [--dry-run] [--verify]
+logpoint validate --manifest /tmp/logpoints.json
+logpoint doctor
+```
+
+## Supported Languages
+
+- JavaScript
+- TypeScript
+- Python
+- Go
+- Ruby
+- Shell (sh/bash/zsh/ksh)
+- Java
+- C#
+- PHP
+- Rust
+- Kotlin
+
+## Manifest Example
+
+```json
+{
+  "port": 9111,
+  "projectRoot": ".",
+  "language": "typescript",
+  "logpoints": [
+    {
+      "id": "hp1",
+      "file": "src/cart.ts",
+      "line": 42,
+      "label": "cart total",
+      "hypothesis": "tax applied twice",
+      "capture": ["total", "tax", "items"],
+      "maxHits": 100
+    }
+  ]
+}
+```
+
+## Safety Guarantees
+
+- Logpoint snippets are wrapped in language-specific error guards so app flow is not interrupted.
+- Sensitive variable names are blocked before injection.
+- Each logpoint enforces `maxHits` locally, and the collector enforces hit limits server-side.
+- Cleanup supports verification to ensure markers are fully removed.
+
+## Architecture Notes
+
+- Runtime: Bun CLI and HTTP server.
+- Core framework: Effect (typed errors, services, schema decoding, composable effects).
+- Architecture guardrails: `repo-lint` in strict mode.
+- Type safety: `tsgo` + `tsc` in strict mode.
+- Linting/formatting: `oxlint`.
+
+## Testing and Coverage
+
+```bash
+bun run test
+bun run coverage
+bun run coverage:check
+```
+
+`coverage:check` enforces a minimum of `95%` line coverage.
+
+## Skill Packaging
+
+The repo includes a portable `SKILL.md` workflow and `agents/debugger.md` persona.
+
+See `docs/cli-compatibility.md` for installation paths and behavior across Claude Code, OpenAI Codex, OpenCode, and Amp.
+See `docs/testing-and-quality.md` for the quality gate and coverage workflow.

package/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: debug-logpoints
+description: >
+  Debug runtime bugs using HTTP logpoints that capture variable state
+  without breakpoints. Use when the user describes a bug involving wrong
+  values, race conditions, unexpected state, timing issues, or says
+  "debug this", "why is this value wrong", "trace this", or "instrument
+  this code". Works with JavaScript, TypeScript, Python, Go, Ruby, Shell,
+  Java, C#, PHP, Rust, and Kotlin.
+disable-model-invocation: true
+compatibility:
+  - claude-code
+  - codex
+  - opencode
+  - amp
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+  - Write
+---
+
+## Phase 1 - Hypothesize
+1. Read files mentioned by the user.
+2. Compare expected behavior with observed behavior.
+3. Produce 3 to 5 ranked hypotheses.
+4. For each hypothesis identify file, line, and variable captures.
+5. Confirm the proposed manifest with the user.
+
+## Phase 2 - Instrument
+1. Write `/tmp/logpoints.json` manifest from hypotheses.
+2. Start collector: `logpoint collector --port 9111 --timeout 300 --output /tmp/debug-logpoints.jsonl`.
+3. Inject logpoints: `logpoint inject --manifest /tmp/logpoints.json`.
+4. Show an injection summary and touched files.
+5. Ask the user to reproduce and confirm when complete.
+
+## Phase 3 - Analyze
+1. Run: `logpoint analyze --input /tmp/debug-logpoints.jsonl --format markdown`.
+2. Read markdown results.
+3. Confirm or refute each hypothesis with direct evidence.
+4. Present findings with hit-by-hit data.
+
+## Phase 4 - Fix
+1. Propose the smallest fix supported by evidence.
+2. Show diff and apply on confirmation.
+
+## Phase 5 - Verify
+1. Reproduce again with collector running.
+2. Confirm the anomaly no longer appears.
+3. If unresolved, return to Phase 2 with updated hypotheses.
+
+## Phase 6 - Cleanup
+1. Run: `logpoint cleanup --dir . --verify`.
+2. Stop collector with PID file or by port.
+3. Remove `/tmp/debug-logpoints.jsonl`, `/tmp/logpoints.json`, `/tmp/debug-logpoints.port`, `/tmp/debug-logpoints.pid`.
+4. Verify no `LOGPOINT_START` or `LOGPOINT_END` markers remain.
+5. Summarize root cause, fix, and validating evidence.
+
+## Error Playbooks
+- `PortInUse`: increment port and retry up to 10 times.
+- `SecretVarBlocked`: warn, drop that variable, continue.
+- `FileNotFound`: ask user to verify path.
+- `InjectionError`: show file, line, and reason; skip failed item and continue.
+- `CollectorTimeout`: restart collector with higher timeout if needed.
+
+## Runtime Fallback
+- Preferred runtime is Bun.
+- If `logpoint` is not on PATH, run `bunx @rikalabs/logpoint <command>`.

package/agents/debugger.md

@@ -0,0 +1,13 @@
+You are the debugger subagent for logpoint workflows.
+
+Responsibilities:
+1. Build ranked hypotheses from observed behavior.
+2. Produce precise logpoint manifests with low-noise variable captures.
+3. Interpret analysis results and tie evidence to hypotheses.
+4. Keep instrumentation minimal and reversible.
+
+Rules:
+1. Do not propose fixes before evidence is collected.
+2. Avoid capturing known sensitive variables.
+3. Favor a small number of high-signal logpoints.
+4. Keep line-level targeting explicit and verifiable.

package/docs/cli-compatibility.md

@@ -0,0 +1,65 @@
+# Skill Compatibility Across Claude Code, Codex, OpenCode, and Amp
+
+This package is designed so one `SKILL.md` workflow can be reused across major agent CLIs.
+
+The workflow calls the global `logpoint` command, so the Skill file does not need local script paths or symlinks.
+
+## Compatibility Matrix
+
+| CLI | `SKILL.md` support | Skill directories | `AGENTS.md` support | Notes |
+| --- | --- | --- | --- | --- |
+| Claude Code | Yes | `.claude/skills/<name>/SKILL.md`, `~/.claude/skills/<name>/SKILL.md` | Project guidance uses Claude docs conventions; Skill system is separate | Model-invoked skills; Claude decides when to load skill instructions. |
+| OpenAI Codex | Yes | Repo and user skill scan includes `.agents/skills` and `$HOME/.agents/skills` | Yes (`AGENTS.md` layering from global and project scopes) | Skills are available in CLI, IDE extension, and Codex app. |
+| OpenCode | Yes | `.opencode/skill`, `~/.config/opencode/skills`, plus `.claude/skills` and `.agents/skills` compatibility paths | Yes (`AGENTS.md` in repo and home) | OpenCode loads skills via its native `skill` tool. |
+| Amp | Yes | `.agents/skills`, `~/.config/agents/skills`, and compatible `.claude/skills` / `.opencode/skill` | Yes | Amp documents both AGENTS and SKILL.md compatibility modes. |
+
+## Installation Without File Linking
+
+Copy, do not symlink:
+
+```bash
+# from this package root
+mkdir -p ~/.claude/skills/debug-logpoints
+cp SKILL.md ~/.claude/skills/debug-logpoints/SKILL.md
+
+mkdir -p ~/.agents/skills/debug-logpoints
+cp SKILL.md ~/.agents/skills/debug-logpoints/SKILL.md
+
+mkdir -p ~/.config/opencode/skills/debug-logpoints
+cp SKILL.md ~/.config/opencode/skills/debug-logpoints/SKILL.md
+
+mkdir -p ~/.config/agents/skills/debug-logpoints
+cp SKILL.md ~/.config/agents/skills/debug-logpoints/SKILL.md
+```
+
+Optional:
+
+```bash
+cp -R agents ~/.claude/skills/debug-logpoints/
+cp -R agents ~/.agents/skills/debug-logpoints/
+cp -R agents ~/.config/opencode/skills/debug-logpoints/
+cp -R agents ~/.config/agents/skills/debug-logpoints/
+```
+
+One-line installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rika-Labs/logpoint/main/scripts/install-skill.sh | bash
+```
+
+## Recommended Project Layout
+
+- Keep one canonical `SKILL.md` in this package.
+- Keep CLI behavior in the `logpoint` binary (`@rikalabs/logpoint`) instead of hardcoded filesystem paths.
+- Use project `AGENTS.md` only for repository-specific policy and constraints, not for duplicating the full debugging workflow.
+
+## Primary References
+
+- Claude Code Skill docs: https://docs.claude.com/en/docs/claude-code/skills
+- OpenAI Codex Skills docs: https://developers.openai.com/codex/skills
+- OpenAI Codex AGENTS docs: https://developers.openai.com/codex/guides/agents-md
+- OpenAI skills catalog (`openai/skills`): https://github.com/openai/skills
+- OpenCode Skills docs: https://opencode.ai/docs/skills/
+- OpenCode Agents docs: https://opencode.ai/docs/agents/
+- Amp AGENTS docs: https://ampcode.com/manual#agentsmd
+- Amp Skills docs: https://ampcode.com/reference/skills

package/docs/testing-and-quality.md

@@ -0,0 +1,40 @@
+# Testing and Quality Gates
+
+## Local Quality Pipeline
+
+Run the full project gate:
+
+```bash
+bun run check
+```
+
+This runs:
+
+1. `oxlint` for lint + formatting policy.
+2. `tsgo` and `tsc` for strict type checks.
+3. Coverage gate with minimum line coverage of `95%`.
+4. `repo-lint` strict architecture validation.
+
+## Coverage Commands
+
+```bash
+bun run coverage
+bun run coverage:check
+```
+
+`coverage:check` generates LCOV and fails if combined line coverage is below `95%`.
+
+## Test Scope
+
+Current tests cover:
+
+- schema decoding and defaulting behavior
+- CLI argument parsing edge cases
+- JSONL append/read failure paths
+- injection and cleanup logic (including Go import mutation paths)
+- anomaly detection and markdown/json rendering
+- service layer behavior (`FileSystem`, `Logger`, `Clock`, `RuntimeEnv`)
+
+## CI Recommendation
+
+Use `bun run check` as the required CI status for pull requests.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@rikalabs/logpoint",
+  "version": "0.0.2",
+  "description": "HTTP logpoint debugger CLI built with Bun and Effect",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Rika-Labs/logpoint"
+  },
+  "homepage": "https://github.com/Rika-Labs/logpoint#readme",
+  "bugs": {
+    "url": "https://github.com/Rika-Labs/logpoint/issues"
+  },
+  "license": "MIT",
+  "author": "Rika Labs",
+  "type": "module",
+  "bin": {
+    "logpoint": "src/cli.ts"
+  },
+  "files": [
+    "src",
+    "SKILL.md",
+    "agents",
+    "README.md",
+    "docs"
+  ],
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "collector": "bun run src/collector.ts",
+    "inject": "bun run src/inject.ts",
+    "cleanup": "bun run src/cleanup.ts",
+    "analyze": "bun run src/analyze.ts",
+    "validate": "bun run src/validate.ts",
+    "doctor": "bun run src/doctor.ts",
+    "lint": "oxlint -c oxlint.json src test --deny-warnings",
+    "lint:fix": "oxlint -c oxlint.json src test --fix",
+    "typecheck": "tsgo --noEmit && tsc --noEmit",
+    "test": "bun test",
+    "coverage": "bun test --coverage",
+    "coverage:check": "bun test --coverage --coverage-reporter=lcov > /dev/null && bun -e \"const fs=require('node:fs');const lines=fs.readFileSync('coverage/lcov.info','utf8').split('\\\\n');let lf=0;let lh=0;for(const line of lines){if(line.startsWith('LF:'))lf+=Number(line.slice(3));if(line.startsWith('LH:'))lh+=Number(line.slice(3));}const pct=lf===0?0:lh/lf*100;console.log('line coverage: '+pct.toFixed(2)+'% ('+lh+'/'+lf+')');if(pct<95){console.error('Expected at least 95% line coverage.');process.exit(1);}\"",
+    "check:arch": "repo-lint check --config repo-lint.config.yaml",
+    "check": "bun run lint && bun run typecheck && bun run coverage:check && bun run check:arch"
+  },
+  "dependencies": {
+    "@effect/schema": "^0.75.5",
+    "effect": "^3.19.14"
+  },
+  "devDependencies": {
+    "@rikalabs/repo-lint": "^2.1.3",
+    "@types/bun": "latest",
+    "@typescript/native-preview": "^7.0.0-dev.20260207.1",
+    "oxlint": "^1.43.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/analyze.ts

@@ -0,0 +1,69 @@
+import { Chunk, Effect, Stream } from "effect";
+import {
+  optionalStringOption,
+  parseArgs,
+} from "./lib/cli-args.js";
+import {
+  ManifestError,
+  ValidationError,
+  type FileReadError,
+  type ParseError,
+} from "./lib/errors.js";
+import { readJsonLines } from "./lib/jsonl.js";
+import { detectAnomalies, groupSnapshots, renderJson, renderMarkdown } from "./lib/render.js";
+import { decodeAnalyzeConfigUnknown, decodeSnapshotUnknown, type AnalyzeConfig } from "./lib/schema.js";
+import { AppLive, Logger } from "./lib/services.js";
+
+const parseAnalyzeConfig = (argv: readonly string[]): Effect.Effect<AnalyzeConfig, ManifestError | ValidationError, never> =>
+  Effect.gen(function* () {
+    const parsed = parseArgs(argv);
+    const positionalInput = parsed.positionals[0];
+    const input = (yield* optionalStringOption(parsed, "input")) ?? positionalInput;
+    const format = yield* optionalStringOption(parsed, "format");
+
+    if (format !== undefined && format !== "markdown" && format !== "json") {
+      return yield* Effect.fail(new ValidationError({ message: `Unsupported format: ${format}` }));
+    }
+
+    return yield* decodeAnalyzeConfigUnknown({
+      input,
+      format,
+    });
+  });
+
+export type AnalyzeRunError = ManifestError | ValidationError | FileReadError | ParseError;
+
+export const runAnalyze = (
+  config: AnalyzeConfig,
+): Effect.Effect<void, AnalyzeRunError | ValidationError, Logger> =>
+  Effect.gen(function* () {
+    const logger = yield* Logger;
+    const lines = yield* readJsonLines(config.input);
+
+    const snapshots = yield* Stream.fromIterable(lines).pipe(
+      Stream.mapEffect((line) => decodeSnapshotUnknown(line)),
+      Stream.runCollect,
+      Effect.map((chunk) => Chunk.toReadonlyArray(chunk)),
+    );
+
+    const grouped = groupSnapshots(snapshots);
+    const anomalies = detectAnomalies(grouped);
+
+    const output = config.format === "json" ? renderJson(grouped, anomalies) : renderMarkdown(grouped, anomalies);
+    yield* logger.info(output);
+  });
+
+export const runAnalyzeFromArgs = (
+  argv: readonly string[],
+): Effect.Effect<void, AnalyzeRunError | ValidationError, Logger> =>
+  parseAnalyzeConfig(argv).pipe(Effect.flatMap((config) => runAnalyze(config)));
+
+const execute = (argv: readonly string[]): Promise<void> =>
+  Effect.runPromise(runAnalyzeFromArgs(argv).pipe(Effect.provide(AppLive)));
+
+if (import.meta.main) {
+  execute(Bun.argv.slice(2)).catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}

package/src/cleanup.ts

@@ -0,0 +1,150 @@
+import { Effect } from "effect";
+import {
+  optionalBooleanOption,
+  optionalCsvOption,
+  optionalStringOption,
+  parseArgs,
+} from "./lib/cli-args.js";
+import {
+  CleanupError,
+  ManifestError,
+  ValidationError,
+  type FileNotFound,
+  type FileReadError,
+  type FileWriteError,
+} from "./lib/errors.js";
+import { cleanupContent, countMarkers } from "./lib/injection-engine.js";
+import { decodeCleanupConfigUnknown, type CleanupConfig } from "./lib/schema.js";
+import { AppLive, FileSystem, Logger } from "./lib/services.js";
+
+const sourcePattern = "**/*.{js,jsx,ts,tsx,mjs,cjs,py,go,rb,sh,bash,zsh,ksh,java,cs,php,rs,kt,kts}";
+
+const ignoredSegments = new Set(["node_modules", ".git", "dist", "coverage", ".next", "target"]);
+
+const shouldSkipPath = (path: string): boolean => {
+  const parts = path.split("/");
+  return parts.some((part) => ignoredSegments.has(part));
+};
+
+const parseCleanupConfig = (argv: readonly string[]): Effect.Effect<CleanupConfig, ManifestError | ValidationError, never> =>
+  Effect.gen(function* () {
+    const parsed = parseArgs(argv);
+    const positionalDir = parsed.positionals[0];
+    const dir = (yield* optionalStringOption(parsed, "dir")) ?? positionalDir;
+    const ids = yield* optionalCsvOption(parsed, "ids");
+    const dryRun = yield* optionalBooleanOption(parsed, "dry-run");
+    const verify = yield* optionalBooleanOption(parsed, "verify");
+
+    return yield* decodeCleanupConfigUnknown({
+      dir,
+      ids,
+      dryRun,
+      verify,
+    });
+  });
+
+const hasTargetMarkers = (content: string, ids?: readonly string[]): boolean => {
+  if (ids === undefined) {
+    return countMarkers(content) > 0;
+  }
+
+  for (const id of ids) {
+    if (content.includes(`LOGPOINT_START [${id}]`)) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+export type CleanupRunError =
+  | ManifestError
+  | ValidationError
+  | CleanupError
+  | FileNotFound
+  | FileReadError
+  | FileWriteError;
+
+export const runCleanup = (
+  config: CleanupConfig,
+): Effect.Effect<void, CleanupRunError, FileSystem | Logger> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    const logger = yield* Logger;
+
+    const allFiles = yield* fs.glob(sourcePattern, config.dir);
+    const files = allFiles.filter((path) => !shouldSkipPath(path));
+
+    const cleaned = yield* Effect.forEach(
+      files,
+      (filePath) =>
+        Effect.gen(function* () {
+          const content = yield* fs.readFile(filePath);
+          if (!content.includes("LOGPOINT_START")) {
+            return { filePath, removed: 0 };
+          }
+
+          const result = cleanupContent(content, config.ids);
+
+          if (!config.dryRun && result.removed > 0) {
+            yield* fs.writeFile(filePath, result.cleaned);
+          }
+
+          return { filePath, removed: result.removed };
+        }),
+      { concurrency: 16 },
+    );
+
+    const touched = cleaned.filter((item) => item.removed > 0);
+    const totalRemoved = touched.reduce((total, item) => total + item.removed, 0);
+
+    if (config.verify && !config.dryRun) {
+      const verification = yield* Effect.forEach(
+        touched,
+        (entry) =>
+          Effect.gen(function* () {
+            const content = yield* fs.readFile(entry.filePath);
+            return { filePath: entry.filePath, hasMarkers: hasTargetMarkers(content, config.ids) };
+          }),
+      );
+
+      const failed = verification.find((entry) => entry.hasMarkers);
+      if (failed !== undefined) {
+        return yield* Effect.fail(
+          new CleanupError({
+            file: failed.filePath,
+            reason: "Verification failed: marker still present",
+          }),
+        );
+      }
+    }
+
+    yield* logger.json({
+      filesScanned: files.length,
+      filesTouched: touched.length,
+      removed: totalRemoved,
+      dryRun: config.dryRun,
+      ids: config.ids,
+    });
+
+    for (const item of touched) {
+      if (config.dryRun) {
+        yield* logger.info(`dry-run would remove ${item.removed} logpoints from ${item.filePath}`);
+      }
+    }
+  });
+
+export const runCleanupFromArgs = (
+  argv: readonly string[],
+): Effect.Effect<void, CleanupRunError, FileSystem | Logger> =>
+  parseCleanupConfig(argv).pipe(Effect.flatMap((config) => runCleanup(config)));
+
+const execute = (argv: readonly string[]): Promise<void> =>
+  Effect.runPromise(runCleanupFromArgs(argv).pipe(Effect.provide(AppLive)));
+
+if (import.meta.main) {
+  execute(Bun.argv.slice(2)).catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}

package/src/cli.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env bun
+
+import { Effect } from "effect";
+import { runAnalyzeFromArgs } from "./analyze.js";
+import { runCleanupFromArgs } from "./cleanup.js";
+import { runCollectorFromArgs } from "./collector.js";
+import { runDoctorFromArgs } from "./doctor.js";
+import { CliUsageError } from "./lib/errors.js";
+import { AppLive, FileSystem, Logger, RuntimeEnv } from "./lib/services.js";
+import { runInjectFromArgs } from "./inject.js";
+import { runValidateFromArgs } from "./validate.js";
+
+const helpText = `logpoint - HTTP logpoint debugger CLI
+
+Usage:
+  logpoint collector [--port 9111] [--timeout 300] [--output /tmp/debug-logpoints.jsonl] [--cors-origin *]
+  logpoint inject --manifest /tmp/logpoints.json [--project-root .] [--language javascript|typescript|python|go|ruby|shell|java|csharp|php|rust|kotlin] [--dry-run]
+  logpoint cleanup [--dir .] [--ids hp1,hp2] [--dry-run] [--verify]
+  logpoint analyze [--input /tmp/debug-logpoints.jsonl] [--format markdown|json]
+  logpoint validate --manifest /tmp/logpoints.json
+  logpoint doctor
+`;
+
+const dispatch = (
+  command: string,
+  argv: readonly string[],
+): Effect.Effect<void, unknown, FileSystem | Logger | RuntimeEnv> => {
+  switch (command) {
+    case "collector":
+      return runCollectorFromArgs(argv);
+    case "inject":
+      return runInjectFromArgs(argv);
+    case "cleanup":
+      return runCleanupFromArgs(argv);
+    case "analyze":
+      return runAnalyzeFromArgs(argv);
+    case "validate":
+      return runValidateFromArgs(argv);
+    case "doctor":
+      return runDoctorFromArgs();
+    case "help":
+    case "--help":
+    case "-h":
+      return Effect.sync(() => {
+        console.log(helpText);
+      });
+    default:
+      return Effect.fail(new CliUsageError({ message: `Unknown command: ${command}` }));
+  }
+};
+
+const runCli = (argv: readonly string[]) =>
+  Effect.gen(function* () {
+    const [command = "help", ...rest] = argv;
+    yield* dispatch(command, rest).pipe(
+      Effect.catchAll((error) => {
+        if (typeof error === "object" && error !== null && "_tag" in error) {
+          const tagged = error as { readonly _tag: string; readonly message?: string };
+          if (tagged._tag === "CollectorTimeout") {
+            return Effect.sync(() => {
+              console.error(tagged.message ?? "Collector timeout reached");
+            });
+          }
+        }
+        return Effect.fail(error);
+      }),
+    );
+  });
+
+if (import.meta.main) {
+  Effect.runPromise(runCli(Bun.argv.slice(2)).pipe(Effect.provide(AppLive))).catch((error) => {
+    if (typeof error === "object" && error !== null && "_tag" in error) {
+      const tagged = error as { readonly _tag: string; readonly message?: string };
+      if (tagged._tag === "CliUsageError") {
+        console.error(`${tagged.message ?? "Invalid command"}\n\n${helpText}`);
+      } else {
+        console.error(error);
+      }
+    } else {
+      console.error(error);
+    }
+    process.exitCode = 1;
+  });
+}