ushman-characterize 0.4.0

package/AGENTS.md

@@ -0,0 +1,110 @@
+# AGENTS.md — ushman-characterize
+
+Read this before changing code in this package.
+
+## What this package is
+
+Refactor-safety net for the post-Ushman decomposition phase. Per-function trace capture + replay. Three.js-aware deep-equality on captured arg/return shapes.
+
+## What this package is NOT
+
+- Not a coverage tool. We measure behavior, not lines.
+- Not a parity harness. `ushman parity` owns whole-app behavioral equivalence.
+- Not a Three.js library. We *consume* Three.js types via `ushman-threejs-tools`; we don't ship Three.
+
+## Read order
+
+1. `README.md`.
+2. `src/instrument.ts` — the Babel transform.
+3. `src/workspace-paths.ts` — v4 workspace detection, path resolution, and lock semantics.
+4. `src/capture.ts` — preview boot, trace merging, and ledger-backed capture flow.
+5. `src/tracer-runtime.ts` — browser tracer runtime generation and async attribution rules.
+6. `src/trace-serializer.ts` — the canonical serializer and replay comparison rules.
+7. `src/format-contract.ts` — versioned trace/replay format guards and compatibility rules.
+8. `src/trace-format.ts` — generated workspace harness wiring.
+9. `src/generate-replay.ts` — how traces become `bun test` files.
+
+## Code map
+
+| File | Owns |
+|------|------|
+| `src/babel-config.ts` | Shared Babel parser configuration for bundle/test AST work |
+| `src/purity-classifier.ts` | Phase A — AST classification of pure top-level functions |
+| `src/stub-pure.ts` | Phase A — emits `tests/pure/<fn>.test.ts` files |
+| `src/scene.ts` | Phase B — scene-state snapshot scaffold from `screenshots/<state>/scene-heavy.json` |
+| `src/instrument.ts` | Phase C.1 — Babel transform that wraps every top-level fn with `__tracer.enter/exit` |
+| `src/workspace-paths.ts` | V4 workspace detection, `.lab/characterize/` path resolution, and pipeline lock handling |
+| `src/capture-server.ts` | Phase C — Vite build/preview boot host for candidate capture |
+| `src/capture.ts` | Phase C.2 — Puppeteer-driven capture during state DAG playback |
+| `src/tracer-runtime.ts` | Phase C — browser tracer runtime generation and sampling |
+| `src/trace-serializer.ts` | Phase C — shared canonicalization/hydration/comparison logic |
+| `src/trace-format.ts` | Phase C — generated replay harness and workspace harness paths |
+| `src/generate-replay.ts` | Phase C.3 — emits `tests/replay/<fn>.test.ts` |
+| `src/ledger.ts` | Phase C/D — characterize report writing and `validator-result` ledger emission |
+| `src/rebind.ts` | Phase D — rewrite import paths in existing replay tests post-refactor |
+| `src/replay-report.ts` | Versioned `VerifyReport` output for `replay --strict` / `--lenient` |
+
+## Conventions and Rules
+
+- Always use `bun` and `bunx`, HARD BAN on: `npm` unless absolutely necessary.
+- Prefer `Bun.file()` instead of `node:fs` whenever possible.
+- Kill any browser instance you start or stray `bun`, `node` processes after you are done. Never leave it running.
+- Prefer arrow functions to classical functions, and `type` over `interface` in TS.
+- Fixes are made using TDD approach.
+- `bun format` and `bun typecheck` should always be ran at the end of your completion, if you introduced any warnings or errors clean them up yourself before you complete.
+- NEVER disable a biome rule or TS rule without explicit permission from the user.
+- If you believe the code you are changing requires some clarification for future AI agents to understand why the change was made, add a brief comment.
+- Do NOT use decorative section headers made of repeated characters (e.g. `// -----`, `// =====`, etc.).
+- Use `it('should...')` style tests.
+- Unit-tests always live in the same folder as their implementation, never in the `test` folder.
+
+## Working rules
+
+- **TDD the serializer.** It's the most error-prone surface (Three.js cycles, BufferGeometry hashing, async-attribution). Add ≥30 cases.
+- **Phase C output must pass `ushman-verify` Tier 0c + 0d.** The instrumented bundle is still a real bundle.
+- **Trace files are JSONL, append-friendly, dedup by (fnName + arg-shape hash + return-shape hash).** Cap at 50 MB per state.
+- **Float tolerance is 4 decimals by default**, configurable per-test.
+- **Capture and rebind runs emit `validator-result` ledger entries.** Treat missing ledger output as a real regression, not optional metadata.
+- **V4 state DAG input is `.lab/state-dag.json` only.** Do not reintroduce `.ushman/state-dag.json` fallback logic for v4 workspaces.
+- **Async side-effect attribution only covers semantically owned work.**
+Supported:
+- Native `await` inside traced top-level functions.
+- Synchronous callbacks scheduled from an active traced chunk through promise/timer primitives.
+
+Unsupported unless the brief explicitly expands the runtime model:
+- Async callbacks that later suspend with their own `await`.
+- `for await...of` / async iterators.
+- DOM event listeners.
+- Worker/message boundaries.
+- Shared callback registries.
+- **`rebind` never auto-commits.** Always `--dry-run`-first, require `--yes` for write.
+- **No regex on the bundle text.** All instrumentation goes through `@babel/traverse`.
+- **The tracer initializes AFTER the v2 determinism preboot** (Date / Math.random / crypto stubs run first).
+
+## Commands
+
+```bash
+bun test
+bun run typecheck
+./bin/ushman-characterize --help
+```
+
+## Validation rules
+
+- `bun test` green; the `end-to-end.browser.test.ts` smoke test stays green (instrument → capture → generate → replay on a synthetic mini-bundle).
+- `bun run typecheck` green.
+- New phase code ⇒ doc update in README.
+- The `VerifyReport` shape produced by `replay --strict` is **versioned**.
+- If serializer or replay harness semantics change, update the runtime/support versioning story in the docs at the same time.
+
+## LLM boundaries
+
+Allowed:
+- LLMs can run `replay --strict` as the green-bar gate during a decomposition brief.
+- LLMs can be given a brief that says "extract `<symbol>` to `<path>`" and may run `rebind` after the operator approves.
+- LLMs can propose new test cases for the purity classifier corpus.
+
+Not allowed:
+- LLMs **never edit files under `tests/replay/`, `tests/pure/`, `tests/scene/`** during a normal refactor brief. Tests are operator-owned.
+- LLMs cannot bypass `--strict` and switch to `--lenient` without explicit operator sign-off in the brief.
+- LLMs cannot delete trace fixtures.

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to `ushman-characterize` will be documented in this file.
+
+## [Unreleased]
+
+### Breaking Changes
+
+- Hard-cut v4 workspace layout:
+  - characterize fixtures moved from `.ushman/test-harness/` to `.lab/characterize/`
+  - replay, pure, and scene tests are derived into `tests/{replay,pure,scene}/`
+  - capture now boots the candidate through Vite preview by default instead of the legacy static serve path
+  - v3 workspaces are refused with a migration hint instead of being read opportunistically
+- Trace deduplication support version bumped:
+  - replay fixtures and trace JSONL files now treat `thisArg` snapshots and side-effect shapes as part of the uniqueness key
+  - regenerate captures and replay fixtures after upgrading so older deduped traces are not reused silently
+
+### Added
+
+- Characterization and replay generation for anonymous default-exported callables via stable synthetic bindings such as `defaultExport`.
+
+### Removed
+
+- Seed-time scaffold population (`populateScaffolds`, `populateSmokeScaffolds`, `stub-pure|stub-states --regen-stale`, `tests/.seed-fingerprints.json` sidecar) and the legacy state-trace synthesis path. These were the consumer side of the pipeline-emitted test-corpus chain that v4.1 explicitly descoped. The manual operator surfaces (`stub-pure --bundle=`, `stub-states`, `capture`, `generate-replay`, `rebind`) are unchanged.
+
+### Migration Notes
+
+1. Move any workflow or CI references from `.ushman/test-harness/` to `.lab/characterize/`.
+2. Update scripts that invoked stage-based bundle paths so they point at the candidate tree, for example `public/assets/...` or `src/...`.
+3. Expect generated tests under `tests/replay/`, `tests/pure/`, and `tests/scene/`.
+4. Re-run `ushman-characterize capture <ws> ...` and `ushman-characterize generate-replay <ws> ...` after upgrading to refresh the expanded dedupe contract.
+5. If the workspace is still v3-shaped, restore the v3 toolchain first; `ushman migrate-v3-v4` is only a diagnostic stub in v4.
+6. Drop any consumer of `populateScaffolds` / `populateSmokeScaffolds` / `--regen-stale`; operators now own seed-time test population for their own candidate repos.
+
+## [0.1.0] - 2026-05-08
+
+- Finished standalone link-readiness wiring for the CLI and public package exports.
+- Added a shared trace serializer used by capture, replay harness generation, and runtime parity tests.
+- Switched replay import rewriting from regexes to AST-based rewriting with dry-run previews.
+- Added a versioned replay `VerifyReport` written to `.ushman/test-harness/reports/verify-report.json`.
+- Added serializer, instrumentation, flag parsing, replay generation, and workspace-lock tests.

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ragaeeb Haq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# ushman-characterize
+
+> **Per-function regression detection for refactor safety.** Characterization tests for the post-Ushman cleanup phase: classify pure functions, instrument every top-level function/method, capture per-call args/returns at runtime, generate a per-function bun-test that fails the moment a refactor drifts.
+
+This is a generalization of Michael Feathers' **characterization testing** discipline (capture observed behavior of legacy code so a refactor can verify behavioral equivalence) plus **trace-and-replay** (instrument once, replay forever).
+
+The trace serializer has Three.js-aware brand-checks — but those come from the optional [`ushman-threejs-tools`](../ushman-threejs-tools) peer dependency. **For non-graphical donors (browser extensions, plain web apps, embedded webviews) the brand-checks are inert and the package operates on plain JS values.** Graphics support is opt-in.
+
+## Status
+
+**m35 is implemented in the `ushman` orchestrator** (`ushman characterize …`, `src/core/characterize/`). This repo is the standalone, link-ready extraction target for `ushman-characterize`.
+**Runtime:** mixed. Instrumentation, replay, purity-classification, and generate-replay are pure Node. `capture` requires Puppeteer.
+
+## What this package is NOT
+
+- Not a code-coverage tool. `c8` / Istanbul tell us "this line was hit"; refactor safety needs "this function still produces the same output."
+- Not a parity harness. That stays in `ushman` orchestrator's `parity/`.
+- Not a snapshot tester. We do not write `expect.toMatchSnapshot()` files; we capture **traces** that survive normal refactoring.
+- Not a mutation tester.
+
+## Install
+
+```bash
+bun install --global ushman-characterize
+bun add ushman-characterize
+```
+
+## Breaking Changes
+
+- v4 fixtures moved from `.ushman/test-harness/` to `.lab/characterize/`.
+- Generated tests now live under `tests/{pure,scene,replay}/`.
+- `capture` now boots the candidate via Vite preview by default.
+- v3 workspaces are rejected with the standard v4 cutover stub hint.
+
+## Local Dev
+
+- This repo currently depends on a sibling checkout of `ushman-ledger` via `file:../ushman-ledger`.
+- For local installs to work, keep `ushman-characterize` and `ushman-ledger` as sibling directories under the same parent.
+
+## Quick start (the 4-phase loop)
+
+```bash
+ushman-characterize stub-pure <ws> --bundle=public/assets/bundle.js   # Phase A
+ushman-characterize stub-states <ws>                                  # Phase B
+ushman-characterize instrument --bundle=<in> --output=<out> --source-map=external # Phase C.1
+ushman-characterize capture <ws> --bundle=<in> --states=0-lobby,1-game # Phase C.2
+ushman-characterize generate-replay <ws> --bundle=<in>                # Phase C.3
+bun test tests/replay/                                                 # run the generated tests
+```
+
+After the LLM (or operator) refactors a class out of the monolith:
+
+```bash
+ushman-characterize rebind <ws> --map='.lab/characterize/modules/CameraController.mjs:CameraController=src/camera/CameraController.js'
+bun test tests/replay/CameraController.*.test.ts
+```
+
+## Phases
+
+| Phase | What | Effort to enable | Yield |
+|-------|------|------------------|-------|
+| A | Pure-function snapshot tests | <1 day | ~200+ tests on Capybara |
+| B | Scene-state snapshot tests | <1 day | ~one test per captured state |
+| C | Trace-and-replay (the main lift) | 5–7 days | ~400+ tests on Capybara |
+| D | Module-contract rebind after extraction | <1 day | Tests follow the refactor |
+
+## Public API
+
+```ts
+classifyPureTopLevelFunctions(opts): PureClassificationResult
+readCapturedTraceState(opts): Promise<CapturedTraceRecord[]>
+scaffoldPureCharacterizationTests(opts): Promise<{ pureFunctionCount, written, ... }>
+scaffoldSceneCharacterizationTests(opts): Promise<{ written }>
+populateScaffolds({
+  workspaceDir,
+  modulePathPrefix?,
+  symbolFilter?,
+}): Promise<{ sidecarPath, written, skipped, synthesizedTraces, toolingGaps }>
+populateSmokeScaffolds({
+  workspaceDir,
+}): Promise<{ sidecarPath, written, skipped, toolingGaps }>
+runStubPureCommand({
+  workspaceRoot,
+  bundlePath?,
+  regenStale?,
+  log,
+}): Promise<...>
+runStubStatesCommand({
+  workspaceRoot,
+  regenStale?,
+  log,
+}): Promise<...>
+canonicalizeSceneTree(value, opts?): unknown
+instrumentBundle(opts): Promise<InstrumentResult>
+captureCharacterization(opts): Promise<CaptureCharacterizationResult>
+generateReplayCharacterization(opts): Promise<{ writtenTests, writtenFixtures }>
+rewriteReplayImports(opts): Promise<{ files }>
+createConsoleLogger(): Logger
+canonicalizeTrace(value, opts?): unknown
+type CaptureServerHost
+type SceneInspectorDriver
+```
+
+## CLI
+
+```bash
+ushman-characterize --help
+ushman-characterize stub-pure <workspace> --bundle=<path>
+ushman-characterize stub-pure <workspace> --regen-stale
+ushman-characterize stub-states <workspace>
+ushman-characterize stub-states <workspace> --regen-stale
+ushman-characterize instrument --bundle=<path> --output=<path> [--source-map=external|inline|off]
+ushman-characterize capture <workspace> [--bundle=...] [--states=a,b] [--scene-only] [--capture-side-effects] [--mode=preview|dev]
+ushman-characterize generate-replay <workspace> --bundle=<path> [--max-cases=10]
+ushman-characterize replay <workspace> [--strict|--lenient] [--filter=<pattern>]
+ushman-characterize rebind <workspace> --map='symbol=path' [--map='workspace/module.mjs:symbol=path'] [--map=...] [--dry-run] [--yes]
+```
+
+Notes:
+
+- Normal `capture` requires `--bundle=<path>`. `--scene-only` is the only mode that can omit it.
+- Characterize fixtures now live under `<ws>/.lab/characterize/` and derived tests live under `<ws>/tests/{pure,scene,replay}/`.
+- `stub-pure --regen-stale` populates seed-time `tests/pure/**/*.test.ts` scaffolds only when the current file hash still matches `tests/.seed-fingerprints.json`. Operator-edited files are skipped unchanged.
+- `stub-pure --regen-stale` consumes canonical module traces from `<ws>/.lab/characterize/traces/<module>.jsonl`. If only legacy state traces exist, characterize synthesizes the module trace once from unambiguous symbol matches and then reuses that file on later runs.
+- `stub-pure --regen-stale` trusts the symbol list declared by existing `test.todo(...)` blocks. The populator does not re-enumerate exports from source files.
+- Legacy state trace synthesis is intentionally conservative. If the same symbol name appears in more than one managed scaffold, characterize leaves those scaffolds untouched and records a tooling-gap instead of guessing which module owns the trace rows.
+- `stub-states --regen-stale` populates seed-time `tests/smoke/<state>.test.ts` scaffolds when `<ws>/parity/baseline/<state>.png` exists, `tests/smoke/{config,diff,drive}.ts` already exist, and the target scaffold hash still matches the sidecar.
+- Editing any auto-managed scaffold, even comments or whitespace, changes its fingerprint and makes future `--regen-stale` runs skip that file on purpose.
+- V4 capture reads the state DAG only from `<ws>/.lab/state-dag.json`.
+- `capture` boots the candidate through `vite build && vite preview` by default. Use `--mode=dev` only for a faster local smoke loop.
+- `instrument` preserves source maps. The standalone CLI defaults to adjacent `.map` files; in-process capture uses inline maps so browser stack traces point back at the pre-instrumented bundle.
+- `scene-only` capture needs a `SceneInspectorDriver`. The CLI will auto-load one from `ushman-threejs-tools/inspector` when that peer is installed.
+- `capture` is partial-success aware: successful earlier states are kept, failed later states are reported with a yellow validator verdict, and oversized existing trace files fail only the affected state. The result now surfaces `attemptedStates`, `completedStates`, and `skippedStates` alongside `failures`.
+- `replay` writes a versioned report to `.lab/characterize/reports/verify-report.json`.
+- Trace JSONL records and replay fixture JSON files are explicitly versioned. The generated replay harness rejects incompatible fixture/support versions with a regeneration hint.
+- `capture`, `rebind`, and seed-scaffold population emit `validator-result` ledger entries through `ushman-ledger` on every run. Missing traces or smoke baselines are recorded as `tooling-gap` notes instead of silently generating empty tests.
+- `rebind --dry-run` prints before/after import previews for generated replay tests.
+- Mixed replay imports are split per destination. Unmapped specifiers remain on the generated module import.
+- Shorthand `rebind --map='symbol=path'` only works when that symbol is unambiguous across generated replay imports. Use file-scoped mappings when the same symbol name appears in more than one generated module.
+- Anonymous default-exported callables are traced and replayed under a synthetic binding name. The default synthetic name is `defaultExport`; if that name is already taken in the bundle, generation picks `defaultExport_2`, `defaultExport_3`, and so on.
+- Async side-effect attribution survives native `await` inside traced top-level functions, plus synchronous callbacks registered from an active traced chunk through `Promise.then`, `queueMicrotask`, `setTimeout`, `setInterval`, and `requestAnimationFrame`.
+- Unsupported async attribution is explicit: callbacks that later suspend with their own `await`, `for await...of` / async-iterator control flow, DOM/event-listener callbacks fired by unrelated user activity, worker/message boundaries, and shared callback registries are not treated as reliable ownership signals.
+
+Seed scaffold sidecar format:
+
+```json
+{
+  "schemaVersion": "shibuk-seed-fingerprints/v1",
+  "scaffolds": {
+    "tests/pure/util/math.test.ts": "<sha256>",
+    "tests/smoke/lobby.test.ts": "<sha256>"
+  }
+}
+```
+
+## Serializer Contract
+
+Trace canonicalization is shared across Node, the browser tracer, and the generated replay harness. The serializer currently covers:
+
+- special numeric values (`NaN`, `Infinity`, `-Infinity`, `-0`)
+- cycles and repeated references
+- `ArrayBuffer` and typed-array views
+- `Map`, `Set`, plain objects, and instance-like objects
+- Three.js-like values including `Vector2`, `Vector3`, `Vector4`, `Euler`, `Quaternion`, `Matrix4`, `Color`, `Object3D`, `BufferGeometry`, `Material`, and `Texture`
+
+By default floats are rounded to 4 decimals, object `uuid` fields are stripped from generic object payloads, each state trace is capped at 50 MB, and capture refuses to load more than 25,000 unique trace records for a single state without operator intervention.
+
+Trace deduplication keys include the function identity, canonicalized arguments, receiver snapshot, return/throw payload, and captured side-effect shape. Calls that keep the same args and return value but arrive with a different `thisArg` snapshot or a different side-effect sequence are preserved as separate replay cases.
+
+Trace JSONL records carry `ushman.characterize.trace-record@1`, replay fixtures carry `ushman.characterize.replay-fixture@1`, and both also store an explicit support version. When serializer or harness semantics change, bump the support version in lockstep with the replay report schema whenever old generated fixtures or harness files would no longer be trustworthy without regeneration.
+
+## Format Version Migration
+
+When serializer, capture, or replay semantics change in a way that makes older traces untrustworthy:
+
+1. Bump `CHARACTERIZE_SUPPORT_VERSION` in [src/constants.ts](/Users/rhaq/workspace/ushman-characterize/src/constants.ts).
+2. Re-run `ushman-characterize capture <ws> ...` to regenerate trace JSONL files.
+3. Re-run `ushman-characterize generate-replay <ws> ...` to regenerate replay fixtures and generated tests.
+4. Re-run `ushman-characterize replay <ws> --strict` to confirm the regenerated harness is green.
+
+Schema-version bumps are reserved for structural format changes to the trace or replay fixture documents. Support-version bumps cover semantic/runtime changes where old files still parse but should no longer be trusted without regeneration.
+
+## Why this exists separate from `ushman`
+
+The decomposition campaign is **regular SWE work post-Ushman, enabled by m35** (per `IMPLEMENTATION-PLAN.md`'s `m35` row). Cloud LLMs and CI integrations that drive refactors should be able to import the trace harness without cloning the entire reverse-engineering pipeline.
+
+## Where this fits in the family
+
+| | |
+|---|---|
+| **Depends on** | `ushman-threejs-tools` (peer — for `Vector3` / `Quaternion` / `Object3D` brand checks in the trace serializer) |
+| **Verified by** | `ushman-verify` Tier 0c+0d (the instrumented bundle must Babel-parse and have no undefined references) |
+| **Runs alongside** | `ushman parity` for the full safety net during a decomposition campaign |

package/bin/ushman-characterize

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# ushman-characterize CLI wrapper. Symlinked from ~/.bun/bin/ushman-characterize
+# after `bun link` so operators can invoke `ushman-characterize <args>` directly.
+# Resolves this script's real location through any symlink chain and hands off to
+# bun, which executes the TypeScript entrypoint.
+set -euo pipefail
+
+SELF="$0"
+while [ -L "$SELF" ]; do
+    LINK_TARGET="$(readlink "$SELF")"
+    case "$LINK_TARGET" in
+        /*) SELF="$LINK_TARGET" ;;
+        *)  SELF="$(dirname "$SELF")/$LINK_TARGET" ;;
+    esac
+done
+HERE="$(cd "$(dirname "$SELF")" && pwd)"
+PACKAGE_ROOT="$(cd "$HERE/.." && pwd)"
+
+exec "${BUN_BIN:-bun}" run "$PACKAGE_ROOT/src/cli.ts" "$@"

package/dist/babel-config.d.ts

@@ -0,0 +1,7 @@
+import type * as t from '@babel/types';
+export declare const BABEL_PLUGINS: readonly ["asyncGenerators", "classPrivateMethods", "classPrivateProperties", "classProperties", "dynamicImport", "importAssertions", "jsx", "topLevelAwait", "typescript"];
+export declare const parseModuleAst: ({ source, sourcePath }: {
+    readonly source: string;
+    readonly sourcePath: string;
+}) => t.File;
+//# sourceMappingURL=babel-config.d.ts.map

package/dist/babel-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"babel-config.d.ts","sourceRoot":"","sources":["../src/babel-config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,CAAC,MAAM,cAAc,CAAC;AAEvC,eAAO,MAAM,aAAa,6KAUhB,CAAC;AAEX,eAAO,MAAM,cAAc,GAAI,wBAAwB;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,KAKrG,CAAC,CAAC,IAAI,CAAC"}

package/dist/babel-config.js

@@ -0,0 +1,17 @@
+import { parse } from '@babel/parser';
+export const BABEL_PLUGINS = [
+    'asyncGenerators',
+    'classPrivateMethods',
+    'classPrivateProperties',
+    'classProperties',
+    'dynamicImport',
+    'importAssertions',
+    'jsx',
+    'topLevelAwait',
+    'typescript',
+];
+export const parseModuleAst = ({ source, sourcePath }) => parse(source, {
+    plugins: [...BABEL_PLUGINS],
+    sourceFilename: sourcePath,
+    sourceType: 'module',
+});

package/dist/capture-server.d.ts

@@ -0,0 +1,31 @@
+import type { CaptureServerHost } from './types.ts';
+type CaptureServerMode = 'dev' | 'preview';
+type CaptureServerProcess = {
+    readonly exited: Promise<number>;
+    readonly kill: () => void;
+    readonly stderr?: null | ReadableStream<Uint8Array>;
+    readonly stdout?: null | ReadableStream<Uint8Array>;
+};
+type OutputTracker = {
+    readonly pending: readonly Promise<void>[];
+    readonly urls: Set<string>;
+    text: string;
+};
+export declare const createViteCaptureServerHost: ({ mode, }?: {
+    readonly mode?: CaptureServerMode;
+}) => CaptureServerHost;
+export declare const __testOnly: {
+    buildServeCommand: ({ mode, port }: {
+        readonly mode: CaptureServerMode;
+        readonly port?: number;
+    }) => string[];
+    closeProcess: (process: CaptureServerProcess) => Promise<void>;
+    waitForServerReady: ({ fallbackUrl, process, timeoutMs, tracker, }: {
+        readonly fallbackUrl: null | string;
+        readonly process: CaptureServerProcess;
+        readonly timeoutMs?: number;
+        readonly tracker: OutputTracker;
+    }) => Promise<string>;
+};
+export {};
+//# sourceMappingURL=capture-server.d.ts.map

package/dist/capture-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-server.d.ts","sourceRoot":"","sources":["../src/capture-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAQpD,KAAK,iBAAiB,GAAG,KAAK,GAAG,SAAS,CAAC;AAC3C,KAAK,oBAAoB,GAAG;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;CACvD,CAAC;AACF,KAAK,aAAa,GAAG;IACjB,QAAQ,CAAC,OAAO,EAAE,SAAS,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;CAChB,CAAC;AAoNF,eAAO,MAAM,2BAA2B,GAAI,YAEzC;IACC,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAChC,KAAG,iBAmCP,CAAC;AAEH,eAAO,MAAM,UAAU;wCAlPoB;QAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;4BAkClE,oBAAoB;wEAqItD;QACC,QAAQ,CAAC,WAAW,EAAE,IAAI,GAAG,MAAM,CAAC;QACpC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;QACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;KACnC;CA0EA,CAAC"}

package/dist/capture-server.js

@@ -0,0 +1,199 @@
+const BUILD_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_READY_TIMEOUT_MS = 20_000;
+const HOSTNAME = '127.0.0.1';
+const READY_POLL_MS = 100;
+const SERVER_URL_PATTERN = /https?:\/\/(?:127\.0\.0\.1|localhost):\d+\/?/gu;
+const decoder = new TextDecoder();
+const toNormalizedUrl = (value) => (value.endsWith('/') ? value : `${value}/`);
+const buildServeCommand = ({ mode, port }) => {
+    const args = ['bun', 'run', mode === 'preview' ? 'preview' : 'dev', '--', '--host', HOSTNAME];
+    if (typeof port === 'number' && port > 0) {
+        args.push('--port', `${port}`);
+        if (mode === 'preview') {
+            args.push('--strictPort');
+        }
+    }
+    return args;
+};
+const renderSpawnFailure = ({ command, cwd, output, result, }) => {
+    const suffix = output.length > 0 ? `\n${output}` : '';
+    return `${command.join(' ')} failed in ${cwd} with exit code ${result.exitCode}.${suffix}`;
+};
+const readProcessOutput = async (process) => {
+    const [stdout, stderr] = await Promise.all([
+        process.stdout ? new Response(process.stdout).text() : Promise.resolve(''),
+        process.stderr ? new Response(process.stderr).text() : Promise.resolve(''),
+    ]);
+    return [stdout, stderr].filter(Boolean).join('\n').trim();
+};
+const closeProcess = async (process) => {
+    try {
+        process.kill();
+    }
+    catch {
+        // process may already be gone
+    }
+    await process.exited.catch(() => undefined);
+};
+const runPreviewBuild = async (workspaceRoot) => {
+    const command = ['bun', 'run', 'build'];
+    const process = Bun.spawn(command, {
+        cwd: workspaceRoot,
+        stderr: 'pipe',
+        stdin: 'ignore',
+        stdout: 'pipe',
+    });
+    let timedOut = false;
+    const timeoutId = setTimeout(() => {
+        timedOut = true;
+        void closeProcess(process);
+    }, BUILD_TIMEOUT_MS);
+    const exitCode = await process.exited;
+    clearTimeout(timeoutId);
+    if (exitCode === 0) {
+        return;
+    }
+    const output = await readProcessOutput(process);
+    if (timedOut) {
+        throw new Error(`bun run build timed out in ${workspaceRoot} after ${BUILD_TIMEOUT_MS}ms.${output ? `\n${output}` : ''}`);
+    }
+    throw new Error(renderSpawnFailure({
+        command,
+        cwd: workspaceRoot,
+        output,
+        result: {
+            exitCode,
+        },
+    }));
+};
+const appendOutput = (tracker, chunk) => {
+    if (chunk.length === 0) {
+        return;
+    }
+    tracker.text += chunk;
+    for (const match of tracker.text.matchAll(SERVER_URL_PATTERN)) {
+        const value = match[0];
+        if (value) {
+            tracker.urls.add(toNormalizedUrl(value));
+        }
+    }
+};
+const consumeStream = async (stream, tracker) => {
+    const reader = stream.getReader();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                return;
+            }
+            appendOutput(tracker, decoder.decode(value, { stream: true }));
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+};
+const createOutputTracker = (process) => {
+    const tracker = {
+        pending: [],
+        text: '',
+        urls: new Set(),
+    };
+    const pending = [
+        process.stdout ? consumeStream(process.stdout, tracker) : Promise.resolve(),
+        process.stderr ? consumeStream(process.stderr, tracker) : Promise.resolve(),
+    ];
+    return {
+        ...tracker,
+        pending,
+    };
+};
+const wait = async (ms) => {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+};
+const collectCandidateUrls = ({ fallbackUrl, tracker, }) => {
+    const candidates = new Set(fallbackUrl ? [fallbackUrl] : []);
+    for (const url of tracker.urls) {
+        candidates.add(url);
+    }
+    return candidates;
+};
+const firstReachableUrl = async (candidateUrls) => {
+    for (const candidateUrl of candidateUrls) {
+        try {
+            const response = await fetch(candidateUrl);
+            if (response.status < 500) {
+                return candidateUrl;
+            }
+        }
+        catch {
+            // ignore transient startup failures while the server boots
+        }
+    }
+    return null;
+};
+const formatTrackerOutput = (tracker) => {
+    const text = tracker.text.trim();
+    return text.length > 0 ? `\n${text}` : '';
+};
+const waitForServerReady = async ({ fallbackUrl, process, timeoutMs = DEFAULT_READY_TIMEOUT_MS, tracker, }) => {
+    let exitCode = null;
+    void process.exited.then((code) => {
+        exitCode = code;
+    });
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const reachableUrl = await firstReachableUrl(collectCandidateUrls({
+            fallbackUrl,
+            tracker,
+        }));
+        if (reachableUrl) {
+            return reachableUrl;
+        }
+        if (exitCode !== null) {
+            throw new Error(`Capture server exited before becoming ready (exitCode=${exitCode}).${formatTrackerOutput(tracker)}`);
+        }
+        await wait(READY_POLL_MS);
+    }
+    throw new Error(`Timed out waiting for capture server.${formatTrackerOutput(tracker)}`);
+};
+export const createViteCaptureServerHost = ({ mode = 'preview', } = {}) => ({
+    async serve(workspaceRoot, port) {
+        if (mode === 'preview') {
+            await runPreviewBuild(workspaceRoot);
+        }
+        const requestedPort = port > 0 ? port : undefined;
+        const fallbackUrl = requestedPort ? `http://${HOSTNAME}:${requestedPort}/` : null;
+        const process = Bun.spawn(buildServeCommand({ mode, port: requestedPort }), {
+            cwd: workspaceRoot,
+            stderr: 'pipe',
+            stdin: 'ignore',
+            stdout: 'pipe',
+        });
+        const tracker = createOutputTracker(process);
+        try {
+            const url = await waitForServerReady({
+                fallbackUrl,
+                process,
+                tracker,
+            });
+            return {
+                close: async () => {
+                    await closeProcess(process);
+                    await Promise.allSettled(tracker.pending);
+                },
+                url,
+            };
+        }
+        catch (error) {
+            await closeProcess(process);
+            await Promise.allSettled(tracker.pending);
+            throw error;
+        }
+    },
+});
+export const __testOnly = {
+    buildServeCommand,
+    closeProcess,
+    waitForServerReady,
+};