bitfab-cli 0.2.386 → 0.2.388
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.js +66 -17
- package/package.json +1 -1
package/dist/index.js
CHANGED
|
@@ -24962,10 +24962,10 @@ var semver3 = __toESM(require_semver2(), 1);
|
|
|
24962
24962
|
|
|
24963
24963
|
// ../bitfab-plugin-lib/dist/bakedSdkVersions.js
|
|
24964
24964
|
var BAKED_SDK_VERSIONS = {
|
|
24965
|
-
typescript: "0.
|
|
24966
|
-
python: "0.
|
|
24967
|
-
ruby: "0.
|
|
24968
|
-
go: "0.
|
|
24965
|
+
typescript: "0.61.1",
|
|
24966
|
+
python: "0.61.0",
|
|
24967
|
+
ruby: "0.61.0",
|
|
24968
|
+
go: "0.61.0"
|
|
24969
24969
|
};
|
|
24970
24970
|
|
|
24971
24971
|
// ../bitfab-plugin-lib/dist/installedSdk.js
|
|
@@ -31449,10 +31449,10 @@ var setupFlow = Flow.parse({
|
|
|
31449
31449
|
id: "setup",
|
|
31450
31450
|
title: "Bitfab Setup",
|
|
31451
31451
|
frontmatter: {
|
|
31452
|
-
description: "Set up and maintain Bitfab tracing
|
|
31452
|
+
description: "Set up and maintain Bitfab tracing, replay registries, and cloud replay. Use for instrumenting AI/LLM code, adding observability or evaluation, tracing another workflow, changing captured inputs/outputs, re-instrumenting a function, moving side effects across trace boundaries, inspecting missing traces, explaining Bitfab, login, organization switching, session-log consent, database snapshots, templates, or read-only repo instrumentation recommendations (analyze-repo). Also use for 'setup cloud', 'set up cloud replay', or 'replay on GitHub'. Re-enter this skill for each additional function to instrument, even after earlier setup. Do not use for improving output quality, pass rates, labeling, or experiments (use bitfab:assistant), or upgrading SDK/plugin versions (use bitfab:update)",
|
|
31453
31453
|
argumentHint: {
|
|
31454
31454
|
deriveFromModes: true,
|
|
31455
|
-
suffix: "[
|
|
31455
|
+
suffix: "[what to do]"
|
|
31456
31456
|
}
|
|
31457
31457
|
},
|
|
31458
31458
|
commands: BITFAB_PLUGIN_COMMANDS.defineCommands({
|
|
@@ -31520,9 +31520,9 @@ var setupFlow = Flow.parse({
|
|
|
31520
31520
|
- Keep prose between tool calls to one line or none. Save fuller explanation for decision points and the workflow summaries the user acts on.
|
|
31521
31521
|
- Surfacing a risk, ambiguity, or unexpected finding is never the narration to suppress: raise it immediately, even mid-probe (e.g. unserializable inputs, a shim with lazy init, an ambiguous project root).
|
|
31522
31522
|
|
|
31523
|
-
This skill has
|
|
31523
|
+
This skill has twelve phases: **explain**, **login**, **session-logs**, **instrument**, **modify**, **inspect**, **switch-org**, **replay**, **db-snapshot**, **templates**, **analyze-repo**, and **cloud**. The \`cloud\` mode configures direct GitHub Actions replay without Bitfab login or a repository connection. Run individually or through setup (\`wizard\` runs login \u2192 instrument; \`explain\` is a standalone read-only overview that requires no login; \`session-logs\` is standalone and does not require login; \`modify\` is only invoked explicitly or as a branch from Instrument's existing-SDK-usage menu; \`inspect\` is a standalone diagnostic (with optional one-shot fixes) invoked explicitly; \`switch-org\` is a standalone account action (requires auth) invoked explicitly; \`db-snapshot\` is only invoked explicitly; \`templates\` is only invoked explicitly; \`analyze-repo\` is a standalone, **non-interactive** batch action (requires auth) invoked explicitly: it scans, picks the top few candidates, and reports source locations and replay dependencies, asking nothing and editing no code).
|
|
31524
31524
|
|
|
31525
|
-
**Natural-language aliases:** "explain Bitfab" \u2192 \`explain\`; "trace a new workflow" / "instrument another function" \u2192 \`instrument\`; "adjust what is captured" / "re-instrument" \u2192 \`modify\`; "why are my traces missing" \u2192 \`inspect\`; "switch org" \u2192 \`switch-org\`; "set up database snapshots" \u2192 \`db-snapshot\`; "analyze the repo" \u2192 \`analyze-repo\` (read-only source recommendations).
|
|
31525
|
+
**Natural-language aliases:** "set up cloud replay" / "replay on GitHub" \u2192 \`cloud\`; "explain Bitfab" \u2192 \`explain\`; "trace a new workflow" / "instrument another function" \u2192 \`instrument\`; "adjust what is captured" / "re-instrument" \u2192 \`modify\`; "why are my traces missing" \u2192 \`inspect\`; "switch org" \u2192 \`switch-org\`; "set up database snapshots" \u2192 \`db-snapshot\`; "analyze the repo" \u2192 \`analyze-repo\` (read-only source recommendations).
|
|
31526
31526
|
|
|
31527
31527
|
When instrumenting a workflow, **its instrumentation and replay pipeline are written together in the same cycle** after the workflow is selected (see Instrument's write-instrumentation step). The standalone \`replay\` mode remains available for coverage-verification and backfill.
|
|
31528
31528
|
|
|
@@ -31536,7 +31536,7 @@ If the block prints \`ERROR: Bitfab plugin not installed\`, the user hasn't inst
|
|
|
31536
31536
|
{{/plugin-dir-lookup}}
|
|
31537
31537
|
**SDK reference:** https://docs.bitfab.ai is the source of truth for SDK install, initialization, API surface, and replay. Every docs path below ends in \`.md\`: that suffix returns the page as plain markdown (no HTML chrome), so fetch the URLs exactly as written. Fetch in this order before writing any code, do not improvise from memory:
|
|
31538
31538
|
- **Canonical API surface (preferred for agents):** the dense reference pages at \`/reference/typescript.md\`, \`/reference/python.md\`, \`/reference/ruby.md\`, \`/reference/go.md\`. These list every public export, signature, type, default, and error semantic, no tutorials, no prose. Read these first.
|
|
31539
|
-
- **Default to opt-out tracing.** For TypeScript,
|
|
31539
|
+
- **Default to opt-out tracing.** For TypeScript, wire the matching \`@bitfab/sdk/transform\` build adapter included with the SDK, then use \`withTrace\`/\`trace\` for the workflow root and \`withNode\`/\`node\` only where a discovered call needs naming, typing, capture, finalization, or replay-mocking policy. For Python 3.12+, use \`@client.trace\` and \`@client.node\` the same way. Opt-in \`withSpan\`/\`span\` remains supported, but setup chooses it only when opt-out is technically impossible: Ruby, Go, Python before 3.12, a TypeScript build path for which the documented transform adapters truly cannot be wired, or a live streaming root whose output opt-out tracing cannot finalize without changing behavior. Framework handlers, processors, and their generated spans are compatible descendants of an opt-out root and are never by themselves a reason to choose spans. Keep the framework integration and use \`withNode\`/\`node\` for first-party calls that need explicit policy. Existing manual spans in the selected call stack are also not a reason to fall back. Convert that whole call stack to one opt-out surface. Before converting a span-bearing helper in place, inspect every production caller and confirm each caller belongs to the same opt-out surface; a helper shared with an opt-in caller requires a disjoint trace boundary or explicit refactor confirmation. Remove redundant span wrappers and replace policy-bearing spans with nodes. Preserve their names, types, capture controls, finalizers, and replay-mocking behavior. TypeScript \`withNode\` requires a named function, so preserve an existing name or use an additive named function form; stop for refactor confirmation if naming it would require a non-additive rewrite. Never put \`withSpan\` beneath \`withTrace\`. The SDK raises \`MixedTracingError\`. Name all three primitives when fetching a reference page so the fetched guidance cannot collapse back to spans alone.
|
|
31540
31540
|
- **Cross-SDK shared semantics:** \`/reference/overview.md\` (invariants), \`/reference/span-types.md\` (the \`SpanType\` enum), \`/reference/http.md\` (wire protocol).
|
|
31541
31541
|
- **Framework integrations (fetch when a framework is detected in step 1 of Instrument):** {{frameworkDocsPaths}}. Each page documents the SDK's native handler/processor/wrapper for that framework, which is usually preferable to hand-wrapping every node/agent call with \`withSpan\`/\`@span\`.
|
|
31542
31542
|
- **Tutorials / walkthroughs / replay registry module template:** the language-specific documentation pages (\`/typescript-sdk.md\`, \`/python-sdk.md\`, \`/ruby-sdk.md\`, \`/go-sdk.md\`). Use these for the copy-pasteable replay registry module and the replay output contract. During Instrument, fetch the Replay section before Instrument's write-instrumentation step so the replay registry module can be written alongside the instrumentation in the same cycle without re-fetching.
|
|
@@ -31555,6 +31555,7 @@ If the block prints \`ERROR: Bitfab plugin not installed\`, the user hasn't inst
|
|
|
31555
31555
|
inspect: "inspect/status-check",
|
|
31556
31556
|
"switch-org": "switch-org/status-check",
|
|
31557
31557
|
replay: "replay/gather-keys",
|
|
31558
|
+
cloud: "cloud/inspect",
|
|
31558
31559
|
"db-snapshot": "db-snapshot/preflight",
|
|
31559
31560
|
templates: "templates/pick-function",
|
|
31560
31561
|
"analyze-repo": "analyze-repo/preflight"
|
|
@@ -31570,6 +31571,7 @@ If the block prints \`ERROR: Bitfab plugin not installed\`, the user hasn't inst
|
|
|
31570
31571
|
inspect: "Diagnose (and offer to fix) your tracing setup: auth, what's instrumented, plugin/SDK freshness, replay coverage, trace arrival.",
|
|
31571
31572
|
"switch-org": "Switch which Bitfab org the plugin reads and writes (replaces the local API key).",
|
|
31572
31573
|
replay: "Create or update replay registry modules for instrumented workflows.",
|
|
31574
|
+
cloud: "Set up replay in your own GitHub Actions using local gh authentication. No Bitfab repository connection required.",
|
|
31573
31575
|
"db-snapshot": "Set up per-trace database snapshots so replay runs against the DB state at trace time (TypeScript, Python, Ruby).",
|
|
31574
31576
|
templates: "Iterate on the span-rendering templates for one trace function.",
|
|
31575
31577
|
"analyze-repo": "Read-only discovery: scan source, rank the top workflows to instrument, and report recommendations without creating artifacts or changing code."
|
|
@@ -31622,6 +31624,50 @@ Never modify existing code on a refactor path without completing this three-step
|
|
|
31622
31624
|
}
|
|
31623
31625
|
],
|
|
31624
31626
|
phases: [
|
|
31627
|
+
{
|
|
31628
|
+
id: "cloud",
|
|
31629
|
+
title: "Cloud replay",
|
|
31630
|
+
stepStyle: "list",
|
|
31631
|
+
intro: "Run replay in the customer's GitHub Actions. Use this standalone mode for 'setup cloud', 'set up cloud replay', or 'replay on GitHub'. Do not enter login or connect a repository to Bitfab. Normal replay still uses a Bitfab API key on the runner.",
|
|
31632
|
+
steps: [
|
|
31633
|
+
{
|
|
31634
|
+
id: "inspect",
|
|
31635
|
+
kind: "action",
|
|
31636
|
+
title: "Inspect the replay environment",
|
|
31637
|
+
toolCalls: ["bash", "read", "glob", "grep", "ask"],
|
|
31638
|
+
body: `Read the existing GitHub Actions, runtime manifests, lockfiles, replay registry, gitignore, and environment-variable NAMES. Never read or print secret values. Check git origin, Python 3.10+, and gh authentication. Local dispatch supports macOS/Linux and github.com. Inspect all push-triggered workflows and deployment integrations. Temporary branches use bitfab-replay/** and can trigger those systems. Ask before changing existing CI or deployment behavior. Do not set pushTriggersReviewed until these triggers have been reviewed with the user.
|
|
31639
|
+
|
|
31640
|
+
Choose one existing replay pipeline and reproduce its runtime, dependency installation, build steps, working directory, caches, and required services from CI. Use the installed SDK's cloud-capable CLI. TypeScript/Python/Ruby registry imports happen on the runner only. Go must dispatch cloud flags before building its registry or initializing the application. A private database needs runner network access or a replay-safe service fixture. Do not silently give replay production side effects. Submodules/gitlinks and credential-like tracked files are rejected by the snapshot helper. Surface blockers instead of claiming the environment is ready.
|
|
31641
|
+
|
|
31642
|
+
Present the proposed workflow, fixed replay command, required secret/variable names, and any required CI trigger exclusions. Ask only about unresolved project choices. Never ask for secret values in chat.`,
|
|
31643
|
+
next: "cloud/install"
|
|
31644
|
+
},
|
|
31645
|
+
{
|
|
31646
|
+
id: "install",
|
|
31647
|
+
kind: "action",
|
|
31648
|
+
title: "Install the repository-owned runner",
|
|
31649
|
+
toolCalls: ["bash", "read", "write", "edit"],
|
|
31650
|
+
body: `Create a reviewed JSON setup specification containing version: 1, provider: "github", workflow: "bitfab-replay.yml", workingDirectory (repository-relative), registry (repository-relative path or null for Go), pipeline, command (a JSON argv array without the pipeline argument or cloud flags), pushTriggersReviewed: true, setupSteps (GitHub Actions step objects), secrets (names including BITFAB_API_KEY), and variables (names only). Optional runsOn, services, and environment match the existing CI. Prefer a GitHub Environment with required reviewers when replay code receives sensitive credentials. Pin third-party actions to reviewed commit SHAs. Ensure Python 3.10+ exists on the runner. Commands run in workingDirectory. Registry in the command must be relative to that directory. Set step working-directory explicitly where needed. Do not copy deployment steps, local env values, or API keys into the specification.
|
|
31651
|
+
|
|
31652
|
+
Run python3 "{{pluginRoot}}/scripts/cloudReplay.py" init --config <specification-path>. This creates .bitfab/cloud.json, .bitfab/cloudReplay.py, and .github/workflows/bitfab-replay.yml. The generated workflow is JSON, which is valid YAML. Existing files are never overwritten. For an existing setup, review the diff and edit project configuration deliberately. Remove only your temporary specification after successful installation. If .bitfab is ignored, propose a narrow gitignore exception for these two files. Never force-add secrets or arbitrary ignored files.
|
|
31653
|
+
|
|
31654
|
+
Tell the user which repository or Environment secrets to create in GitHub Settings \u2192 Secrets and variables \u2192 Actions. BITFAB_API_KEY belongs to their intended Bitfab organization. Other names come from their application, such as OPENAI_API_KEY. BITFAB_SERVICE_URL is optional. Do not override the SDK's default with an empty GitHub variable. Runtime secrets belong on the replay step. Any install-time credentials need explicit references on the relevant setup step. Local gh authentication is separate from these runner secrets. Do not create a Bitfab cloud target, install a GitHub App, or request a repository connection.`,
|
|
31655
|
+
next: "cloud/verify"
|
|
31656
|
+
},
|
|
31657
|
+
{
|
|
31658
|
+
id: "verify",
|
|
31659
|
+
kind: "action",
|
|
31660
|
+
title: "Verify and hand off",
|
|
31661
|
+
toolCalls: ["bash", "read", "ask"],
|
|
31662
|
+
body: `Validate workflow syntax (actionlint when available) and run the installed SDK CLI with --cloud --help. The workflow must land on the default branch once before workflow_dispatch can run it on temporary branches. Explain the required commit/merge. Do not push, merge, change repository permissions, or set secrets without authorization.
|
|
31663
|
+
|
|
31664
|
+
After the setup files are tracked, run bitfab-replay --cloud <pipeline> --trace-ids <real-trace-uuid> --cloud-dry-run using the selected SDK command. It reports changed tracked files and omitted new files. Include new source files explicitly with repeated --cloud-include <repository-relative-file>. Review the entire snapshot for credentials. Filename screening is not a secret scanner. Then, only when remote replay is authorized, run without --cloud-dry-run. The helper creates a commit through an isolated index, pushes bitfab-replay/<UUID>, dispatches that branch, waits, retrieves the test-run identity, and deletes the branch with an exact-SHA lease. HEAD, staged changes, and working files stay untouched. Never reset or undo the user's work.
|
|
31665
|
+
|
|
31666
|
+
Use --cloud-detach to return immediately. Explain --cloud-status, --cloud-watch, --cloud-cancel, and --cloud-cleanup with the printed execution UUID. Records live under this worktree's Git directory. Interrupted/lost-response submissions must be recovered, not blindly dispatched again. Cancel requests do not imply the job stopped. Watch/status confirms completion before deleting the branch. Detached jobs do not automatically clean themselves without a later local lifecycle command. Report separately whether files are generated, secrets configured, workflow merged, dry-run verified, and an actual remote replay completed. Never call a mock smoke run a real replay.`,
|
|
31667
|
+
next: "cleanup/finish"
|
|
31668
|
+
}
|
|
31669
|
+
]
|
|
31670
|
+
},
|
|
31625
31671
|
{
|
|
31626
31672
|
id: "login",
|
|
31627
31673
|
title: "Login",
|
|
@@ -31718,6 +31764,7 @@ Save the answer (replace \`CONSENT\` with \`true\` or \`false\`):
|
|
|
31718
31764
|
inspect: "cleanup/finish",
|
|
31719
31765
|
"switch-org": "cleanup/finish",
|
|
31720
31766
|
replay: "cleanup/finish",
|
|
31767
|
+
cloud: "cleanup/finish",
|
|
31721
31768
|
"db-snapshot": "cleanup/finish",
|
|
31722
31769
|
templates: "cleanup/finish",
|
|
31723
31770
|
"analyze-repo": "cleanup/finish"
|
|
@@ -31751,7 +31798,7 @@ Bitfab provides opt-out tracing and safe replay during development. For TypeScri
|
|
|
31751
31798
|
- \`withNode(...)\` / \`node(...)\` to configure a discovered call
|
|
31752
31799
|
- \`replay(...)\` to run recorded scenarios against current code
|
|
31753
31800
|
|
|
31754
|
-
Default to opt-out tracing. A trace root records its serializable inputs and output plus every first-party call beneath it. Most descendants need no wrapper. Add a node only when a call needs a name, type, capture override, finalizer, or replay-mocking policy. TypeScript requires the matching \`@bitfab/transform\` build adapter; setup
|
|
31801
|
+
Default to opt-out tracing. A trace root records its serializable inputs and output plus every first-party call beneath it. Most descendants need no wrapper. Add a node only when a call needs a name, type, capture override, finalizer, or replay-mocking policy. TypeScript requires the matching \`@bitfab/sdk/transform\` build adapter included with the SDK; setup configures it. Python requires 3.12+. Opt-in spans remain supported; setup uses them as the fallback for Ruby, Go, unsupported runtimes, and live streaming roots that opt-out tracing cannot finalize without changing behavior. Keep one tracing surface per call stack. Never mix \`withSpan\` beneath \`withTrace\`; the SDK rejects mixed tracing surfaces.
|
|
31755
31802
|
|
|
31756
31803
|
\`replay\` calls into your trace root and can modify each captured descendant in one of five ways:
|
|
31757
31804
|
|
|
@@ -31786,6 +31833,7 @@ then close with one line: to start tracing, run \`{{cmd}}setup\`; to debug an ex
|
|
|
31786
31833
|
next: {
|
|
31787
31834
|
byMode: {
|
|
31788
31835
|
wizard: "approach/choose-driver",
|
|
31836
|
+
cloud: "cleanup/finish",
|
|
31789
31837
|
explain: "cleanup/finish",
|
|
31790
31838
|
login: "cleanup/finish",
|
|
31791
31839
|
"session-logs": "cleanup/finish",
|
|
@@ -31985,6 +32033,7 @@ Confirm the change to the user.`,
|
|
|
31985
32033
|
inspect: "cleanup/finish",
|
|
31986
32034
|
"switch-org": "cleanup/finish",
|
|
31987
32035
|
replay: "cleanup/finish",
|
|
32036
|
+
cloud: "cleanup/finish",
|
|
31988
32037
|
"db-snapshot": "cleanup/finish",
|
|
31989
32038
|
templates: "cleanup/finish",
|
|
31990
32039
|
"analyze-repo": "cleanup/finish"
|
|
@@ -32010,7 +32059,7 @@ Confirm the change to the user.`,
|
|
|
32010
32059
|
|
|
32011
32060
|
**Install the SDK now.** Detect the project's package manager from its manifest (\`pyproject.toml\` \u2192 \`uv\`/\`poetry\`; \`package.json\` \u2192 \`pnpm\`/\`npm\`/\`yarn\`/\`bun\`; \`Gemfile\` \u2192 \`bundle\`; \`go.mod\` \u2192 \`go get\`; \`requirements.txt\` \u2192 edit file + \`pip install -r\`) and run its canonical add command, do NOT stop to ask about version pinning, dependency groups, package publishing, or whether a supported transform adapter should be added. The user's request to instrument authorizes the dependencies and build wiring required by the selected approach. Prefer \`uv add\`/\`poetry add\` over bare \`pip install\` (bare \`pip install\` doesn't persist to pyproject.toml). In monorepos, scope to the correct workspace (e.g. \`pnpm add --filter <pkg>\`, or cd into the app directory first), running from the repo root will install into the wrong package. Install the SDK as a runtime dependency whenever instrumented code ships or executes from the package, including published libraries and CLIs. Use a development dependency only when the instrumented code is excluded from the published/runtime artifact. Then set the \`BITFAB_API_KEY\` environment variable.
|
|
32012
32061
|
|
|
32013
|
-
**Install opt-out capture support at the same time.** For TypeScript,
|
|
32062
|
+
**Install opt-out capture support at the same time.** For TypeScript, the SDK already includes every transform adapter; do not install a second transform package. Wire the matching \`@bitfab/sdk/transform\` adapter into the actual server build before instrumenting. Inspect the build tool and use the matching documented adapter. For Next.js, wrap the existing config with \`@bitfab/sdk/transform/next\` while preserving existing wrappers such as Sentry; do not replace or bypass them. For tsup, add the \`@bitfab/sdk/transform/esbuild\` plugin to the existing tsup esbuild options. For direct Node or \`tsx\`, update the real start command to register \`@bitfab/sdk/transform/register\`. The package also ships documented adapters for Vite, Rollup, webpack, Rspack, Rsbuild, Rolldown, Bun, SWC, Babel, Nest, and the TypeScript compiler. Verify the transformed build path covers the production entrypoint. Do not call a build unsupported until you have checked these adapters and the language guide. For Python, verify the runtime is 3.12+ before choosing \`trace\`/\`node\`. Fall back to opt-in spans only when the language/runtime or build path truly cannot support subtree capture, or when the selected root returns a live stream that opt-out tracing cannot finalize without changing behavior. A published package, a framework-generated span model, or the need to add a supported transform adapter is not a fallback reason. State the concrete technical blocker to the user and keep the whole selected call stack on one tracing surface.
|
|
32014
32063
|
|
|
32015
32064
|
**Keep organization-specific keys isolated.** Inspect how the selected application already names and loads Bitfab keys before changing its client initialization. A TypeScript client whose configured \`apiKey\` is missing or resolves empty falls back to \`BITFAB_API_KEY\`. If this client intentionally uses a dedicated key for another organization or environment, also set \`captureEnabled\` from the presence of that dedicated key. Never rely on an empty dedicated key to disable tracing because the fallback can send traces to the organization bound to \`BITFAB_API_KEY\`. Do not replace an existing general-purpose \`BITFAB_API_KEY\` when the application deliberately keeps these destinations separate.
|
|
32016
32065
|
|
|
@@ -32145,7 +32194,7 @@ Recommend one to start with. **Ask the user to pick exactly ONE workflow to inst
|
|
|
32145
32194
|
|
|
32146
32195
|
**Delegate 11b to a subagent only when 11a is itself a large mechanical fan-out** (>10 files) whose generation genuinely overlaps the registry work. The subagent must follow the same registry-only contract.
|
|
32147
32196
|
|
|
32148
|
-
**Default instrumentation policy:** use opt-out tracing whenever the selected TypeScript or Python workflow supports it. TypeScript setup must
|
|
32197
|
+
**Default instrumentation policy:** use opt-out tracing whenever the selected TypeScript or Python workflow supports it. TypeScript setup must configure the bundled \`@bitfab/sdk/transform\` adapter in the application build, then put \`withTrace\`/\`trace\` on the existing workflow root. Python 3.12+ uses \`trace\` on the root. Let first-party descendants be discovered automatically and use \`withNode\`/\`node\` for external reads, unsafe side effects, model calls, naming, typing, capture overrides, finalization, and replay mocking. Do not add \`withSpan\` inside an opt-out trace. Existing \`withSpan\` usage is not a reason to extend the opt-in pattern. When a manual span already runs inside the selected call stack, migrate the call stack instead of abandoning opt-out. Before converting a span-bearing helper in place, inspect every production caller and confirm each caller belongs to the same opt-out surface; if an opt-in caller remains, use a disjoint trace boundary or stop for refactor confirmation. Remove redundant span wrappers. Replace spans that carry policy with nodes and preserve that policy. TypeScript \`withNode\` requires a named function, so preserve an existing name or use an additive named function form; stop for refactor confirmation if naming it requires a non-additive rewrite. This tracing-surface migration is instrumentation work, not an application refactor. Stop for refactor confirmation only if preserving application behavior requires changing the underlying function or its callers. Spans remain supported, but during setup choose them only when opt-out is technically impossible: Ruby, Go, unsupported Python runtimes, a TypeScript build path unsupported by every documented transform adapter, or a live streaming root whose output opt-out tracing cannot finalize without changing behavior. Framework integrations and their generated spans remain nested beneath the opt-out root; they do not justify a span root. Adding a supported transform adapter, including the esbuild adapter used by tsup, is required setup work rather than a fallback reason. Report the concrete technical blocker and keep the selected call stack on one tracing surface.
|
|
32149
32198
|
|
|
32150
32199
|
- **11a. Instrumentation edits**: follow the SDK reference exactly, purely additive. Never change behavior, arguments, return values, error handling, variable names, types, control flow, or code structure. **Wrapping means wrapping, not silently rewriting.** Attach the opt-out trace to the existing root and configure only the discovered nodes that need policy. Rewriting, re-implementing, inlining, or hand-reconstructing a framework/SDK call to seat a root is sometimes genuinely necessary, but it is a refactor, not additive instrumentation: never do it silently as part of the write step. Any such rewrite must preserve behavior exactly (labeled *visibility* or *structural* in the refactor plan); a rewrite that would change behavior is never allowed, fall back to an additive root or move the boundary inward instead. Try the additive root first, when the natural root is opaque or stream-returning, reach for the framework handler/middleware or the \`finalize\` option wrapped around the *unchanged* call. If none of those fit and a rewrite really is required, STOP, present the refactor plan to the user in plain terms and get an explicit yes before touching the code (the "Refactor confirmation" rules below say what the plan must contain), then proceed once they approve. **Likewise, if the additive wrap doesn't typecheck, STOP and surface it rather than dropping or loosening an argument, weakening validation, or otherwise quietly changing runtime behavior to make it compile** (the same "no type-checker escape hatches, don't paper over it" rule the replay step enforces): a compile error on a purely-additive wrap means the wrap isn't additive, so either find the additive form or present it to the user as a refactor and get approval first. Batch repetitive edits into one message (many Edit calls); for large mechanical fan-outs (>10 files of the same wrapper pattern), validate the pattern on one file, then delegate the rest to a subagent. **For each external read or unsafe side effect that replay must mock, configure the discovered node with replay mocking** (TypeScript \`withNode({ type, mockOnReplay: true }, fn)\` / \`@client.node(...)\`; Python \`@client.node(type=..., mock_on_replay=True)\`). Under opt-in fallback, put the equivalent option on the span. This lets replay's \`mock: "marked"\` strategy serve its recorded output without mixing tracing surfaces.
|
|
32151
32200
|
|
|
@@ -32163,7 +32212,7 @@ Recommend one to start with. **Ask the user to pick exactly ONE workflow to inst
|
|
|
32163
32212
|
- **Side-effect check**: if importing the instrumented function triggers module-level side effects (booting listeners/ports/prod connections), do not work around it silently; flag it to the user (a subagent returns that fact in its report so the main agent can flag it).
|
|
32164
32213
|
- **Result**: confirm the registry module path and the exact \`bitfab-replay --registry ...\` command. Surface signature mismatches or import side effects.{{/codex}}{{#codex}}**Write instrumentation AND the replay registry module for this trace function in the same cycle.** Skip the registry for Go-only projects.
|
|
32165
32214
|
|
|
32166
|
-
**Default instrumentation policy:** use opt-out tracing whenever the selected TypeScript or Python workflow supports it. TypeScript setup must
|
|
32215
|
+
**Default instrumentation policy:** use opt-out tracing whenever the selected TypeScript or Python workflow supports it. TypeScript setup must configure the bundled \`@bitfab/sdk/transform\` adapter in the application build, then put \`withTrace\`/\`trace\` on the existing workflow root. Python 3.12+ uses \`trace\` on the root. Let first-party descendants be discovered automatically and use \`withNode\`/\`node\` for external reads, unsafe side effects, model calls, naming, typing, capture overrides, finalization, and replay mocking. Do not add \`withSpan\` inside an opt-out trace. Existing \`withSpan\` usage is not a reason to extend the opt-in pattern. When a manual span already runs inside the selected call stack, migrate the call stack instead of abandoning opt-out. Before converting a span-bearing helper in place, inspect every production caller and confirm each caller belongs to the same opt-out surface; if an opt-in caller remains, use a disjoint trace boundary or stop for refactor confirmation. Remove redundant span wrappers. Replace spans that carry policy with nodes and preserve that policy. TypeScript \`withNode\` requires a named function, so preserve an existing name or use an additive named function form; stop for refactor confirmation if naming it requires a non-additive rewrite. This tracing-surface migration is instrumentation work, not an application refactor. Stop for refactor confirmation only if preserving application behavior requires changing the underlying function or its callers. Spans remain supported, but during setup choose them only when opt-out is technically impossible: Ruby, Go, unsupported Python runtimes, a TypeScript build path unsupported by every documented transform adapter, or a live streaming root whose output opt-out tracing cannot finalize without changing behavior. Framework integrations and their generated spans remain nested beneath the opt-out root; they do not justify a span root. Adding a supported transform adapter, including the esbuild adapter used by tsup, is required setup work rather than a fallback reason. Report the concrete technical blocker and keep the selected call stack on one tracing surface.
|
|
32167
32216
|
|
|
32168
32217
|
- **11a. Instrumentation edits**: follow the SDK reference exactly, purely additive. Never change behavior, arguments, return values, error handling, variable names, types, control flow, or code structure. **Wrapping means wrapping, not silently rewriting.** Attach the opt-out trace to the existing root and configure only the discovered nodes that need policy. Rewriting, re-implementing, inlining, or hand-reconstructing a framework/SDK call to seat a root is sometimes genuinely necessary, but it is a refactor, not additive instrumentation: never do it silently as part of the write step. Any such rewrite must preserve behavior exactly (labeled *visibility* or *structural* in the refactor plan); a rewrite that would change behavior is never allowed, fall back to an additive root or move the boundary inward instead. Try the additive root first, when the natural root is opaque or stream-returning, reach for the framework handler/middleware or the \`finalize\` option wrapped around the *unchanged* call. If none of those fit and a rewrite really is required, STOP, present the refactor plan to the user in plain terms and get an explicit yes before touching the code (the "Refactor confirmation" rules below say what the plan must contain), then proceed once they approve. **Likewise, if the additive wrap doesn't typecheck, STOP and surface it rather than dropping or loosening an argument, weakening validation, or otherwise quietly changing runtime behavior to make it compile** (the same "no type-checker escape hatches, don't paper over it" rule the replay step enforces): a compile error on a purely-additive wrap means the wrap isn't additive, so either find the additive form or present it to the user as a refactor and get approval first. Batch repetitive edits in parallel (one message, many Edit calls); for large mechanical fan-outs (>10 files of the same wrapper pattern), validate the pattern on one file, then do the remaining files. **For each external read or unsafe side effect that replay must mock, configure the discovered node with replay mocking** (TypeScript \`withNode({ type, mockOnReplay: true }, fn)\` / \`@client.node(...)\`; Python \`@client.node(type=..., mock_on_replay=True)\`). Under opt-in fallback, put the equivalent option on the span. This lets replay's \`mock: "marked"\` strategy serve its recorded output without mixing tracing surfaces.
|
|
32169
32218
|
|
|
@@ -32408,7 +32457,7 @@ Mark each key as \u2705 traces arriving (with most recent timestamp), \u26A0\uFE
|
|
|
32408
32457
|
- **Bare trace-processor keys** ({{traceProcessorNames}} over plain \`run()\`): the processor captures the run but its root span records an empty input, so a processor-only key without the run wrapper {{traceProcessorRootWrappers}} or an application root is NOT replayable. Flag it \u26A0\uFE0F root not replayable and recommend adding a \`withTrace\`/\`trace\` root that takes the run input in supported subtree runtimes, or routing through the run wrapper. Recommend a manual \`withSpan\`/\`@span\` root only when opt-out is technically unavailable. When an application root exists, check its signature like any decorated key (next bullet).
|
|
32409
32458
|
- **Decorated/wrapped keys**: read the root function signature and confirm it's replayable per Instrument's trace-boundary serializability requirement (serializable inputs). Flag any key whose root takes unserializable inputs (live SDK/DB clients, HTTP \`Request\`/\`Response\`, stream writers, sockets, opaque request contexts) as \u26A0\uFE0F root not replayable, reasoning from the signature, not the function name. This is independent of the replay-registry coverage in sub-step 3 above: a non-replayable root is \u26A0\uFE0F whether or not a registry exists for it (a key can be \u274C no replay registry module AND \u26A0\uFE0F root not replayable at once), so never roll a non-replayable root up into \u2705 just because it has no registry entry.
|
|
32410
32459
|
|
|
32411
|
-
5. **Subtree capture wiring**: an opt-out \`trace\`/\`withTrace\` root records the root and nothing beneath it unless the runtime support is actually there, which looks like healthy tracing until someone opens a trace and finds one node. Only check this when step {{step:inspect/gather-functions}} found an opt-out root; a repo whose roots are all \`withSpan\`/\`span\` needs none of it. **TypeScript** needs two things, both required: (a) \`@bitfab/
|
|
32460
|
+
5. **Subtree capture wiring**: an opt-out \`trace\`/\`withTrace\` root records the root and nothing beneath it unless the runtime support is actually there, which looks like healthy tracing until someone opens a trace and finds one node. Only check this when step {{step:inspect/gather-functions}} found an opt-out root; a repo whose roots are all \`withSpan\`/\`span\` needs none of it. **TypeScript** needs two things, both required: (a) \`@bitfab/sdk\` in that workspace's manifest, and (b) an adapter wired into the build that produces the server entrypoint. Grep the build configuration and start scripts for either the current \`@bitfab/sdk/transform/\` prefix or the still-supported \`@bitfab/transform/\` compatibility prefix: \`next.config.*\`, \`vite.config.*\`, \`webpack.config.*\`, \`rspack.config.*\`, \`rsbuild.config.*\`, \`rollup.config.*\`, \`tsup.config.*\`, \`babel.config.*\`, Nest's \`webpackConfigPath\` target, or the corresponding \`--import .../register\` on the real start command. Treat either adapter prefix as wired; do not add an SDK adapter alongside an existing compatibility adapter. Mark \u2705 package present and adapter wired, \u26A0\uFE0F package installed but no adapter in the real build path, or \u274C package missing. **Python** needs 3.12+ instead; read the project's declared version and flag anything below it. The application's own log corroborates a \u274C or \u26A0\uFE0F finding: both SDKs log one \`[bitfab]\` warning when an opt-out root runs without its runtime support.
|
|
32412
32461
|
|
|
32413
32462
|
Hold these results for the report. (If nothing is instrumented, no trace function keys AND no trace-processor registrations, skip both the **replay** and the **replayability** checks, they are per-workflow, so there's nothing to evaluate; report both as \`n/a (nothing instrumented)\`, never \u2705. Still run the **plugin** and **SDK** checks: the SDK may be installed and stale, or on the legacy \`bitfab\` package needing the \`@bitfab/sdk\` rename, independent of whether any trace functions exist in this repo yet.)`,
|
|
32414
32463
|
next: "inspect/report"
|
|
@@ -32424,13 +32473,13 @@ Hold these results for the report. (If nothing is instrumented, no trace functio
|
|
|
32424
32473
|
- **Instrumented here**: the list of keys with \u2705 / \u26A0\uFE0F / \u2753 markers from step {{step:inspect/check-traces}}.
|
|
32425
32474
|
- **Replay**: \u2705 covers all keys / \u26A0\uFE0F missing keys / \u274C none (from the replay-registry check in step {{step:inspect/check-freshness}}).
|
|
32426
32475
|
- **Replayable**: \u2705 all roots replayable / \u26A0\uFE0F \`<key>\` root not replayable / \`n/a (nothing instrumented)\` (from the per-root replayability check in step {{step:inspect/check-freshness}}; flagged whether or not a replay registry module exists for the key; never \u2705 when nothing is instrumented).
|
|
32427
|
-
- **Subtree capture**: \u2705 wired / \u26A0\uFE0F \`@bitfab/
|
|
32476
|
+
- **Subtree capture**: \u2705 wired / \u26A0\uFE0F \`@bitfab/sdk\` installed but no transform adapter in the real build path / \u274C \`@bitfab/sdk\` missing / \u274C Python below 3.12 / \`n/a (no opt-out roots)\` (from the subtree-capture check in step {{step:inspect/check-freshness}}).
|
|
32428
32477
|
|
|
32429
32478
|
Then, for anything not healthy, name the most likely cause and the fix:
|
|
32430
32479
|
- **Plugin or SDK out of date, or on the legacy \`bitfab\` package**: apply via the fix prompt below (upgrades the version and/or switches \`bitfab\` \u2192 \`@bitfab/sdk\`; same effect as \`{{cmd}}update\`).
|
|
32431
32480
|
- **Replay missing or incomplete**: refresh via \`{{cmd}}setup replay\` (non-interactive; creates or extends registry entries to cover every key).
|
|
32432
32481
|
- **Root not replayable**, two failure modes, with the fix matched to each: **(a) the root takes unserializable inputs** (live SDK/DB clients, HTTP req/res, streams, opaque contexts), with or without a replay registry module: move the trace boundary inward to a serializable-input function or refactor to introduce one; **(b) a bare trace-processor-only key** ({{traceProcessorNames}}) whose root is the processor's empty-input span: add a \`withTrace\`/\`trace\` root that wraps the run and takes its input in a supported subtree runtime, or route the run through the run wrapper ({{traceProcessorRootWrappers}}). Use a manual \`withSpan\`/\`@span\` root only when opt-out is technically unavailable. Either way, re-instrument via \`{{cmd}}setup modify\` (or \`{{cmd}}setup instrument\` for a fresh boundary). This is a code change, recommended here, not applied blanket.
|
|
32433
|
-
- **Opt-out roots without subtree capture**: every trace is the root alone, so tracing looks healthy and the traces are useless for per-step diagnosis, replay mocking, and prompt iteration. For TypeScript,
|
|
32482
|
+
- **Opt-out roots without subtree capture**: every trace is the root alone, so tracing looks healthy and the traces are useless for per-step diagnosis, replay mocking, and prompt iteration. For TypeScript, use the installed SDK and wire the matching adapter into the build behind the server entrypoint, preserving existing config wrappers such as Sentry. For Python, this is a runtime upgrade to 3.12+; report it rather than attempting it.
|
|
32434
32483
|
- **Instrumented but no traces**: the app hasn't run with tracing enabled, or \`BITFAB_API_KEY\` isn't set in the run environment. Run the app with the key loaded.
|
|
32435
32484
|
- **Key set but traces aren't visible in the browser**: the API key is bound to a different Clerk org/tenant than the browser session. A key resolves \`API key \u2192 organization_id \u2192 clerk_organization_id \u2192 Clerk tenant\` at creation time; browser visibility requires both to be the same tenant.
|
|
32436
32485
|
- **Nothing instrumented**: run \`{{cmd}}setup instrument\`.
|
|
@@ -32483,7 +32532,7 @@ Then continue to the fix prompt. Inspect does not open Bitfab.`,
|
|
|
32483
32532
|
- **SDK out of date** (\`updateAvailable: true\`, \`renameFrom\` null), name the workspace and the \`current \u2192 latest\` jump, then {{askVerb}} to upgrade; if yes, run the package manager's upgrade from that workspace directory (the same commands \`{{cmd}}update\` uses): npm / pnpm / yarn / bun \`add @bitfab/sdk@latest\`; uv / poetry / pip \`bitfab-py@latest\`; \`bundle update bitfab\`; \`go get github.com/Project-White-Rabbit/bitfab-go@latest && go mod tidy\`. Read the manifest afterward to confirm the new version. Each workspace is its own decision.
|
|
32484
32533
|
- **On the legacy \`bitfab\` package** (\`renameFrom\` non-null), this rewrites import sites, so **preview before touching code**: list every \`from "bitfab"\` / \`require("bitfab")\` site you would change, then {{askVerb}} to proceed. If yes, remove the old package and add the new one in one step (e.g. \`pnpm remove bitfab && pnpm add @bitfab/sdk@latest\`, or the npm / yarn / bun equivalent) and rewrite those imports to \`@bitfab/sdk\`. Do this even when \`current\` already equals \`latest\`, the rename is the fix. (TypeScript-only; Python / Ruby / Go package names don't change.)
|
|
32485
32534
|
- **Replay missing or incomplete**: {{askVerb}} to refresh; if yes, run \`{{cmd}}setup replay\` to create or extend the scripts so every trace function key is covered (it is non-interactive).
|
|
32486
|
-
- **Subtree capture not wired** (TypeScript), this edits a build file, so **preview before touching code**: name the workspace, the adapter you would use, and the exact config file or start script you would change, then {{askVerb}} to proceed. If yes,
|
|
32535
|
+
- **Subtree capture not wired** (TypeScript), this edits a build file, so **preview before touching code**: name the workspace, the adapter you would use, and the exact config file or start script you would change, then {{askVerb}} to proceed. If yes, use the installed SDK and wire the matching \`@bitfab/sdk/transform\` adapter: \`@bitfab/sdk/transform/next\` wrapping the existing \`next.config\`, the \`/vite\`, \`/rollup\`, \`/rolldown\`, \`/esbuild\`, \`/bun\`, \`/webpack\`, \`/rspack\`, \`/rsbuild\`, \`/babel\`, \`/nest\`, or \`/typescript\` entry in the existing build config, or \`--import @bitfab/sdk/transform/register\` on the real start command. Preserve every existing wrapper; never replace or bypass one. Python below 3.12 is a runtime upgrade, report it and do not attempt it.
|
|
32487
32536
|
|
|
32488
32537
|
For unusual monorepos or private registries, defer to \`{{cmd}}update\`. Report what was applied and what the user declined. Do not open Bitfab.`,
|
|
32489
32538
|
next: "cleanup/finish"
|
package/package.json
CHANGED