bitfab-cli 0.2.340 → 0.2.342

package/dist/index.js

@@ -24569,10 +24569,10 @@ var semver3 = __toESM(require_semver2(), 1);
 
 // ../bitfab-plugin-lib/dist/bakedSdkVersions.js
 var BAKED_SDK_VERSIONS = {
-  typescript: "0.54.3",
-  python: "0.55.2",
-  ruby: "0.51.5",
-  go: "0.51.4"
+  typescript: "0.54.4",
+  python: "0.55.3",
+  ruby: "0.51.6",
+  go: "0.51.5"
 };
 
 // ../bitfab-plugin-lib/dist/installedSdk.js
@@ -31109,7 +31109,7 @@ If the block prints \`ERROR: Bitfab plugin not installed\`, the user hasn't inst
 {{/plugin-dir-lookup}}
 **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:
 - **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.
-- **Default to opt-out tracing.** For TypeScript, install and wire the matching \`@bitfab/transform\` build adapter, 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. Never choose spans merely because the repository already uses them or because adding the transform changes the build configuration. 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.
+- **Default to opt-out tracing.** For TypeScript, install and wire the matching \`@bitfab/transform\` build adapter, 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.
 - **Cross-SDK shared semantics:** \`/reference/overview.md\` (invariants), \`/reference/span-types.md\` (the \`SpanType\` enum), \`/reference/http.md\` (wire protocol).
 - **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\`.
 - **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.
@@ -31585,6 +31585,8 @@ Confirm the change to the user.`,
 
 **Install opt-out capture support at the same time.** For TypeScript, add \`@bitfab/transform\` as a development dependency in the same application workspace and wire its 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/transform/next\` while preserving existing wrappers such as Sentry; do not replace or bypass them. For tsup, add the \`@bitfab/transform/esbuild\` plugin to the existing tsup esbuild options. For direct Node or \`tsx\`, update the real start command to register \`@bitfab/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.
 
+**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.
+
 **Tell the user what you did.** Pick the env-handling approach that fits the project's existing convention. Whatever you do, surface it explicitly: name the file (with absolute path) or mechanism you used, so the user knows where the key now lives. Do not print the key value itself. If the key landed in a \`.env\`-style file, additionally tell the user that any already-running dev server, REPL, or test runner may need a restart to pick it up, since most file watchers reload code on save but not env files.`,
           next: "instrument/read-signatures"
         },
@@ -31703,7 +31705,7 @@ Recommend one to start with. **Ask the user to pick exactly ONE workflow to inst
           id: "read-signatures",
           kind: "action",
           title: "Read the selected workflow and its dependencies",
-          body: "Read the selected root function, its exact signature, callers, and stateful dependencies. Choose a stable trace function key from the existing conventions. Preserve the real production entrypoint and caller behavior. Verify that recorded inputs can reconstruct the same root during replay; rebuild clients and framework objects inside the replay callable. For live stream outputs, use the documented finalize support and preserve streaming behavior. Read the SDK reference and use its native integration for the detected framework. Once this is established, proceed directly to instrumentation and replay setup. Ask only if the workflow itself remains ambiguous or a non-additive refactor is required; follow the refactor-confirmation appendix for that case.",
+          body: "Read the selected root function, its exact signature, callers, stateful dependencies, and transitive calls that already use Bitfab instrumentation. Choose a stable trace function key from the existing conventions. Preserve the real production entrypoint and caller behavior. Verify that recorded inputs can reconstruct the same root during replay; rebuild clients and framework objects inside the replay callable. For live stream outputs, use the documented finalize support and preserve streaming behavior. Read the SDK reference and use its native integration for the detected framework. If any manual span can execute beneath the selected opt-out root, plan its conversion before writing. Inspect every production caller of each span-bearing helper, not only calls reachable from the selected root. Convert a helper in place only when every caller belongs to the same opt-out surface; otherwise choose a disjoint trace boundary or stop for refactor confirmation so existing opt-in callers cannot encounter `withNode`. Remove a redundant span wrapper or replace it with a node while preserving its name, type, capture controls, finalizer, and replay-mocking behavior. For TypeScript, confirm every `withNode` target is a named function; preserve its existing name or use an additive named function form, and stop if that requires a non-additive rewrite. An existing span in this call stack does not make opt-out technically impossible. Once this is established, proceed directly to instrumentation and replay setup. Ask only if the workflow itself remains ambiguous or a non-additive application refactor is required; follow the refactor-confirmation appendix for that case.",
           toolCalls: ["read", "grep"],
           next: "instrument/write-instrumentation"
         },
@@ -31716,7 +31718,7 @@ Recommend one to start with. **Ask the user to pick exactly ONE workflow to inst
 
 **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.
 
-**Default instrumentation policy:** use opt-out tracing whenever the selected TypeScript or Python workflow supports it. TypeScript setup must install and configure \`@bitfab/transform\` 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. 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.
+**Default instrumentation policy:** use opt-out tracing whenever the selected TypeScript or Python workflow supports it. TypeScript setup must install and configure \`@bitfab/transform\` 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.
 
 - **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.
 
@@ -31734,7 +31736,7 @@ Recommend one to start with. **Ask the user to pick exactly ONE workflow to inst
   - **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).
   - **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.
 
-**Default instrumentation policy:** use opt-out tracing whenever the selected TypeScript or Python workflow supports it. TypeScript setup must install and configure \`@bitfab/transform\` 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. 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.
+**Default instrumentation policy:** use opt-out tracing whenever the selected TypeScript or Python workflow supports it. TypeScript setup must install and configure \`@bitfab/transform\` 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.
 
 - **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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bitfab-cli",
-  "version": "0.2.340",
+  "version": "0.2.342",
   "description": "Install and configure the Bitfab plugin in Claude Code, Codex, or Cursor, or the Bitfab skill pack in Amp (Alpha).",
   "type": "module",
   "main": "dist/index.js",