bitfab-cli 0.2.329 → 0.2.330

package/dist/index.js

@@ -27010,10 +27010,10 @@ var semver3 = __toESM(require_semver2(), 1);
 
 // ../bitfab-plugin-lib/dist/bakedSdkVersions.js
 var BAKED_SDK_VERSIONS = {
-  typescript: "0.53.2",
+  typescript: "0.53.3",
   python: "0.53.1",
   ruby: "0.51.2",
-  go: "0.51.1"
+  go: "0.51.2"
 };
 
 // ../bitfab-plugin-lib/dist/installedSdk.js
@@ -32931,7 +32931,7 @@ cd <project-dir> && {{command:replayProgress}} --label <pipeline-name> --run-dir
 **If an external child span fails during replay, verify it is actually mockable before tagging it.** When a non-root span throws because a paid call, external service, or stored dependency is unavailable, it can block the whole trace even though the failure is outside the function you're iterating on. The short-term fix is recorded-output mocking, but only after the wrapper and execution-context checks below clear:
 
 1. Find the failing span's call site in the codebase (\`withSpan("<spanName>", ...)\` in TS, \`@bitfab.span\` / \`bitfab_span\` equivalents in other SDKs). **This only works on a span whose call runs through a Bitfab wrapper as a descendant in the same replay context** (a hand-written \`withSpan\` / \`@span\` / \`bitfab_span\`, or a per-call middleware like Vercel AI's \`wrapLanguageModel\`). Python worker threads require \`Bitfab(trace_across_threads=True)\`; Ruby child threads, pre-created consumers, and other processes are outside replay interception. If the failing span is one the SDK only OBSERVES, reported by a callback handler, trace processor, stream, or collector (a LangChain / LangGraph node or tool, an OpenAI Agents / Claude Agent tool span, a BAML call), there is no span-options object to flag, and \`mockOnReplay\` cannot short-circuit it: replay only watches it and re-runs it for real. To mock such a span, first wrap its underlying call in a manual Bitfab span (move the boundary), then flag that manual span. If moving the boundary would change the instrumentation contract, use a database snapshot when the failure is database-shaped; otherwise stop and report the item as unreplayable. In TypeScript, also verify the boundary is async/Promise-returning; a synchronous selected span needs eager \`mock: "all"\`, which is valid only when every matched child may be frozen.
-2. Add the flag to its span declaration (TypeScript, Python, and Ruby; Go does not support replay yet):
+2. Add the flag to its span declaration. For Go, use \`WithMockOnReplay(true)\` on a closure-style \`Client.Span\` boundary; manual \`Start\`/\`End\` spans cannot skip caller-owned code. See https://docs.bitfab.ai/go-sdk.md for typed mock outputs and the \`MockMarked\` replay strategy. TypeScript, Python, and Ruby examples:
    \`\`\`ts
    // TypeScript: SpanOptions.mockOnReplay
    bitfab.withSpan("expensive-llm-call", { mockOnReplay: true }, async () => { ... })
@@ -34065,7 +34065,7 @@ If the block prints \`ERROR: Bitfab plugin not installed\`, the user hasn't inst
 - **The client exposes three instrumentation primitives, not one.** Spans are the oldest, not the only one: TypeScript has \`withSpan\`/\`span\`, \`withTrace\`/\`trace\`, and \`withNode\`/\`node\`; Python has \`@client.span\`, \`@client.trace\`, and \`@client.node\`; Ruby and Go have spans only. \`trace\` records a root plus every first-party call beneath it without decorating them (TypeScript needs a \`@bitfab/transform\` adapter, Python needs 3.12+), and \`node\` applies naming, typing, capture, and \`mockOnReplay\`/\`mock_on_replay\` policy to one call discovered inside that subtree. Name all three when you fetch a reference page. The fetch answers the question you asked, so asking only about \`withSpan\`/\`@span\` returns a page that reads as though spans are the whole API.
 - **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 guide 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.
+- **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.
 
 **MCP tools:** This skill uses \`get_bitfab_api_key\`, \`save_trace_plan\`, \`get_trace_plan\`, \`list_trace_plans\`, and \`cancel_trace_plan\` (login / instrument / modify / view / \`analyze-repo\`), \`list_trace_functions\` and \`search_traces\` (\`inspect\`, \`templates\`, and the exact-trace smoke test in \`db-snapshot\`), \`list_organizations\` (\`switch-org\`), \`get_database_connection_status\` (\`db-snapshot\` only), and, for the \`templates\` mode only, \`get_template_reference\`, \`get_template\`, and \`save_template\`. {{^amp}}All come from the **local plugin MCP server** (bundled with this plugin){{/amp}}{{#amp}}All are registered by the Bitfab plugin under these bare names{{/amp}}{{#claude}}. Do NOT use the remote Bitfab MCP tools (\`mcp__Simforge__*\` or \`mcp__Bitfab__*\`), use only the \`mcp__plugin_bitfab_Bitfab__*\` variants{{/claude}}{{#cursor}}, exposed under the \`mcp__Bitfab__*\` prefix{{/cursor}}{{#codex}}, exposed under the \`mcp__Bitfab__*\` prefix{{/codex}}.
 `,
@@ -34188,7 +34188,7 @@ Brackets \`[\u2026]\` are structural labels (not spans). Parens \`(\u2026)\` are
 
 Pick the **base template** from SDK capability and surrounding work:
 
-1. **Trace processor (hybrid) template**: if the SDK guide says to register a processor (e.g. OpenAI Agents SDK \`addTraceProcessor\`) AND there is meaningful work above, alongside, or below the SDK call. The trace function root wraps the broader workflow with manual \`\u25CF\` spans; the SDK call appears as one \`(agent)\` child whose grandchildren are the \`[auto]\` lines; other manual spans capture work outside the SDK. This is the default for any trace processor SDK whenever there's surrounding workflow logic, which is almost always. **The root must take the workflow's serializable input as its argument (the prompt / messages / request), because replay re-runs that root against its recorded input. A bare processor call (plain \`run()\`) with neither a root wrapper nor a manual root records a root span with no input (the agent span carries no recorded input) and is not replayable; the manual \`withSpan\`/\`@span\` root is what makes the broader trace replayable.**
+1. **Trace processor (hybrid) template**: if the framework documentation says to register a processor (e.g. OpenAI Agents SDK \`addTraceProcessor\`) AND there is meaningful work above, alongside, or below the SDK call. The trace function root wraps the broader workflow with manual \`\u25CF\` spans; the SDK call appears as one \`(agent)\` child whose grandchildren are the \`[auto]\` lines; other manual spans capture work outside the SDK. This is the default for any trace processor SDK whenever there's surrounding workflow logic, which is almost always. **The root must take the workflow's serializable input as its argument (the prompt / messages / request), because replay re-runs that root against its recorded input. A bare processor call (plain \`run()\`) with neither a root wrapper nor a manual root records a root span with no input (the agent span carries no recorded input) and is not replayable; the manual \`withSpan\`/\`@span\` root is what makes the broader trace replayable.**
 2. **Trace processor (bare) template**: when the workflow truly is *just* the SDK call with no surrounding work. Use the run wrapper ({{traceProcessorRootWrappers}}) in place of the plain run call: it records a keyed root carrying the run input, and the processor's auto-captured children nest underneath as \`[auto]\` lines, so the bare workflow is **replayable with no hand-written root**. **A plain \`run()\` under the processor alone records an empty-input root (the agent span carries no recorded input): observable but NOT replayable: only acceptable when the user has explicitly accepted an observable-only trace for this workflow.** Confirm before using this, if the workflow has any input prep, orchestration, retries, post-processing, or non-SDK LLM/tool calls, use the hybrid template instead.
 3. **Default view**: every other case (no processor in play). This is the recommended default for SDKs without a processor.
 
@@ -34570,7 +34570,7 @@ Then go to {{skill-ref:instrument}} and start at its first step. The guided path
           title: "Hand over the docs and stop",
           body: `The user is instrumenting on their own. Give them the pointers below in one short message, then **stop**: do not scan the codebase, read files, or edit anything.
 
-- **Docs:** https://docs.bitfab.ai, start with the SDK guide for their language (\`/typescript-sdk\`, \`/python-sdk\`, \`/ruby-sdk\`, \`/go-sdk\`); each one covers install, initialization, wrapping a workflow, and (outside Go) the replay registry module. Name the language's page directly if the project's language is already obvious from the conversation; do not go read the repo to find out.
+- **Docs:** https://docs.bitfab.ai, start with the SDK documentation for their language (\`/typescript-sdk\`, \`/python-sdk\`, \`/ruby-sdk\`, \`/go-sdk\`); each one covers install, initialization, wrapping a workflow, and (outside Go) the replay registry module. Name the language's page directly if the project's language is already obvious from the conversation; do not go read the repo to find out.
 - **API key:** their app needs \`BITFAB_API_KEY\` set in the environment it runs in before any trace will arrive. Tell them to get the key from the Bitfab MCP's \`get_bitfab_api_key\` tool. Do **not** call it yourself, and never print a key.
 - **Coming back:** \`{{cmd}}setup\` picks this flow back up, and \`{{cmd}}setup inspect\` diagnoses an instrumentation they wrote themselves (auth, what's instrumented, whether traces are arriving).
 
@@ -35752,12 +35752,12 @@ For a **confirmed** plan, {{askVerb}} whether to open it in the browser or finis
       stepStyle: "list",
       intro: `Create or update replay registry modules for instrumented trace functions. Requires instrumentation in the codebase; does **not** require existing traces, replay registry modules are created from trace function keys in the code, not captured trace data.
 
-The SDK-installed \`bitfab-replay\` command lets the team regression-test any registered trace function against production data with one command: it fetches historical traces, re-runs them through the current code, and reports old vs. new outputs side-by-side. The project owns only the registry module. Note: **Go does not support replay**: skip this phase if the project is Go-only.
+The SDK-installed \`bitfab-replay\` command lets the team regression-test any registered trace function against production data with one command: it fetches historical traces, re-runs them through the current code, and reports old vs. new outputs side-by-side. The project owns only the registry module. **Go supports programmatic replay through its SDK, but has no installed replay registry CLI.** For a Go-only project, point to https://docs.bitfab.ai/go-sdk.md and https://docs.bitfab.ai/reference/go.md for the replay API, then skip this registry-specific phase.
 
 **Relationship to Instrument.** Instrument's write-instrumentation step writes each replay pipeline alongside the instrumentation edits. Run this mode standalone (\`{{cmd}}setup replay\`) to catch pre-existing trace function keys that predate that step or were added outside the skill.
 
 **Source of truth:** two pages, read both before creating or modifying a replay registry module. Do not improvise from memory.
-- **Canonical \`replay\` API signature, options, and return shape:** \`/reference/typescript.md\`, \`/reference/python.md\`, \`/reference/ruby.md\` (Go has no replay). Use this for the exact field names (\`result\` / \`originalOutput\` vs \`original_output\`), default \`limit\`, \`maxConcurrency\`/\`max_concurrency\`, error behavior.
+- **Canonical \`replay\` API signature, options, and return shape:** \`/reference/typescript.md\`, \`/reference/python.md\`, \`/reference/ruby.md\` (these are the languages supported by this registry workflow). Use this for the exact field names (\`result\` / \`originalOutput\` vs \`original_output\`), default \`limit\`, \`maxConcurrency\`/\`max_concurrency\`, error behavior.
 - **Copy-pasteable registry template + installed-command contract + input serialization caveat:** \`/typescript-sdk.md\`, \`/python-sdk.md\`, \`/ruby-sdk.md\`. Use this for the language-specific registry shape and the standard \`bitfab-replay --registry <path> <pipeline>\` invocation.`,
       steps: [
         {
@@ -35873,7 +35873,7 @@ If one or more functions can't be invoked or aren't replayable, {{askVerb}} offe
       stepStyle: "list",
       intro: `Set up **per-trace database snapshots for replay** so the team can re-run a historical trace against the database state that existed *when the trace was captured*, not today's data. This is what makes replay trustworthy for any code that reads stored state (a refund decision over a since-cancelled order, a retrieval step over last week's rows). Triggered explicitly by \`{{cmd}}setup db-snapshot\`, never reached from \`wizard\`.
 
-**Available for TypeScript, Python, and Ruby** (the SDKs with replay). Go has no replay, so DB-snapshot replay does not apply, if the project is Go, say so and stop.
+**This registry-based setup flow supports TypeScript, Python, and Ruby.** Go also supports database-snapshot replay through its programmatic API. For Go, point to https://docs.bitfab.ai/go-sdk.md and https://docs.bitfab.ai/reference/go.md for \`ReplayOptions.DBBranch\` and \`GetCurrentReplayBranch(ctx)\`, then stop this registry-specific flow.
 
 **Capture is automatic in current SDKs, there is nothing to turn on.** Eligible root traces captured by an SDK version with always-on snapshot references pin the wall-clock instant they ran (no client config required), so those traces can later be replayed against their historical DB state, subject to replication lag. Older traces without a snapshot reference use the normal database path. Setup is therefore just two pieces:
 1. **Connect the database once** in the Bitfab dashboard. The source database can be **any Postgres**: Bitfab provisions a branchable managed copy from it. A one-time, dashboard-side step.
@@ -35887,7 +35887,7 @@ If one or more functions can't be invoked or aren't replayable, {{askVerb}} offe
           toolCalls: ["bash", "read", "grep", "glob"],
           commandCalls: ["status", "login"],
           title: "Check auth and detect the SDK language",
-          body: `**Confirm the SDK language.** DB-snapshot replay is available for **TypeScript, Python, and Ruby**. If the project is **Go**, tell the user Go has no replay so this doesn't apply, and route to cleanup.
+          body: `**Confirm the SDK language.** This registry-based flow supports **TypeScript, Python, and Ruby**. If the project is **Go**, explain that its SDK supports database-snapshot replay through the programmatic API, point to https://docs.bitfab.ai/go-sdk.md and https://docs.bitfab.ai/reference/go.md for \`ReplayOptions.DBBranch\` and \`GetCurrentReplayBranch(ctx)\`, and route to cleanup.
 
 **Check authentication.** Run:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bitfab-cli",
-  "version": "0.2.329",
+  "version": "0.2.330",
   "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",