bitfab-cli 0.2.328 → 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 () => { ... })
@@ -34062,10 +34062,10 @@ 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.
-- **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.
+- **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.328",
+  "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",