From 7b7773abf3b234e8389bfb2d202cedccc448cc5a Mon Sep 17 00:00:00 2001 From: Cody Fincher Date: Mon, 27 Apr 2026 00:52:00 +0000 Subject: [PATCH] fix(beads): silence bd --json deprecation, opt projects into v2.0 envelope bd 1.x prints a deprecation notice to stderr on every `--json` invocation unless `BD_JSON_ENVELOPE=1` is set, which floods flow's SessionStart context block. Wires a two-layer fix: 1. Hook layer (immediate): `hooks/detect-env.{sh,ps1}` export `BD_JSON_ENVELOPE=1` for the session and update the `bd ready --json` parsers to unwrap the v2.0 envelope shape (`{schema_version, data}`) while still accepting legacy arrays. Same script, both formats. 2. Setup layer (durable): every documented setup path now appends `json-envelope: true` to `.beads/config.yaml` idempotently, recording the project's intent in version-controllable Viper config. bd 1.x reads only the env var today; once beads wires the toggle through Viper (see CONFIG.md table), the YAML key takes over and the env-var bridge can be removed. Touches all 5 host-specific setup mirrors plus the canonical reference and the workflow.md template prose so Claude / Codex / OpenCode agents all leave the same project state behind. --- commands/flow-setup.md | 7 ++++++- commands/flow/setup.toml | 7 ++++++- hooks/detect-env.ps1 | 15 +++++++++++++-- hooks/detect-env.sh | 12 +++++++++++- skills/flow/references/setup.md | 11 +++++++++++ templates/agent/workflow.md | 2 +- templates/opencode/agents/flow.md | 1 + templates/opencode/commands/flow-setup.md | 7 ++++++- 8 files changed, 55 insertions(+), 7 deletions(-) diff --git a/commands/flow-setup.md b/commands/flow-setup.md index 47d781e..bcc9490 100644 --- a/commands/flow-setup.md +++ b/commands/flow-setup.md @@ -378,9 +378,14 @@ bd init --non-interactive --stealth --prefix --skip-agents bd config set no-git-ops true bd config set export.auto false bd config set export.git-add false + +mkdir -p .beads +if [ ! -f .beads/config.yaml ] || ! grep -q '^json-envelope:' .beads/config.yaml; then + printf 'json-envelope: true\n' >> .beads/config.yaml +fi ``` -These defaults keep Beads local-only: no automatic export, no auto-staging, and no git operations in `bd prime` output. `bd dolt push` remains explicit opt-in only. +These defaults keep Beads local-only: no automatic export, no auto-staging, and no git operations in `bd prime` output. `bd dolt push` remains explicit opt-in only. The `json-envelope: true` Viper key opts the project into the bd v2.0 JSON envelope so `bd --json` stops emitting the deprecation notice; flow's hooks export `BD_JSON_ENVELOPE=1` until beads wires this through Viper. If no-Beads mode was selected: diff --git a/commands/flow/setup.toml b/commands/flow/setup.toml index 9c35291..e68fa06 100644 --- a/commands/flow/setup.toml +++ b/commands/flow/setup.toml @@ -57,7 +57,7 @@ Use `${FLOW_INSTALL_ROOT}` in every command below that references shipped templa If B selected, continue in no-Beads mode. Do NOT halt. 3. **Default initialization rules:** - - Official Beads MUST use `bd init --non-interactive --stealth --prefix "$repo_slug" --skip-agents`, then set `bd config set no-git-ops true`, `bd config set export.auto false`, and `bd config set export.git-add false`. + - Official Beads MUST use `bd init --non-interactive --stealth --prefix "$repo_slug" --skip-agents`, then set `bd config set no-git-ops true`, `bd config set export.auto false`, and `bd config set export.git-add false`. Append `json-envelope: true` to `.beads/config.yaml` (idempotent) to opt into the bd v2.0 envelope. - Prefer `.git/info/exclude` for local-only ignores instead of editing repo `.gitignore`. 4. **Continue:** Once the backend choice is clear, proceed to 1.1. @@ -641,6 +641,11 @@ Use `${FLOW_INSTALL_ROOT}` in every command below that references shipped templa bd config set no-git-ops true bd config set export.auto false bd config set export.git-add false + + mkdir -p .beads + if [ ! -f .beads/config.yaml ] || ! grep -q '^json-envelope:' .beads/config.yaml; then + printf 'json-envelope: true\n' >> .beads/config.yaml + fi ``` If B selected, skip backend initialization and continue in no-Beads mode. diff --git a/hooks/detect-env.ps1 b/hooks/detect-env.ps1 index c44ac06..569a3a9 100644 --- a/hooks/detect-env.ps1 +++ b/hooks/detect-env.ps1 @@ -9,6 +9,12 @@ $ErrorActionPreference = 'Stop' $script:DEFAULT_ROOT_DIR = if ($env:CLAUDE_PLUGIN_OPTION_AGENTSDIR) { $env:CLAUDE_PLUGIN_OPTION_AGENTSDIR } else { '.agents' } $script:USE_BEADS = if ($env:CLAUDE_PLUGIN_OPTION_USEBEADS) { $env:CLAUDE_PLUGIN_OPTION_USEBEADS } else { 'true' } +# Opt into the bd v2.0 JSON envelope so `bd --json` stops emitting the +# deprecation notice into the SessionStart context block. Bridges until +# beads wires this through Viper config; flow's parsers below are +# envelope-aware either way. +$env:BD_JSON_ENVELOPE = '1' + function Get-BeadsBackend { Write-Host "## Flow Environment Context" if ($script:USE_BEADS -ne 'true') { @@ -122,8 +128,13 @@ function Get-ActiveWork($backend) { } if ($backend -eq "bd") { try { - # ConvertFrom-Json may return a single object; wrap in @(...) so Select-Object sees an array - $ready = @(bd ready --json | ConvertFrom-Json) | Select-Object -First 3 + # ConvertFrom-Json may return a single object; wrap in @(...) so Select-Object sees an array. + # Unwrap the v2.0 envelope ({schema_version, data: [...]}) when present so legacy and envelope outputs both flow through. + $parsed = bd ready --json | ConvertFrom-Json + if ($parsed -is [PSCustomObject] -and $parsed.PSObject.Properties.Name -contains 'data') { + $parsed = $parsed.data + } + $ready = @($parsed) | Select-Object -First 3 if ($ready) { $readyJson = $ready | ConvertTo-Json -Compress Write-Host "- **Ready Tasks (Top 3)**: $readyJson" diff --git a/hooks/detect-env.sh b/hooks/detect-env.sh index 35bd8a8..f365249 100755 --- a/hooks/detect-env.sh +++ b/hooks/detect-env.sh @@ -17,6 +17,12 @@ IFS=$'\n\t' readonly DEFAULT_ROOT_DIR="${CLAUDE_PLUGIN_OPTION_AGENTSDIR:-.agents}" readonly USE_BEADS="${CLAUDE_PLUGIN_OPTION_USEBEADS:-true}" +# Opt into the bd v2.0 JSON envelope so `bd --json` stops emitting the +# deprecation notice into the SessionStart context block. Bridges until +# beads wires this through Viper config; flow's parsers below are +# envelope-aware either way. +export BD_JSON_ENVELOPE=1 + # --- Functions --- # Helper to safely run a command with timeout and return its output @@ -161,7 +167,11 @@ active_work() { # Attempt to parse and truncate with python if available if command -v python3 >/dev/null 2>&1; then local truncated - truncated=$(echo "${ready}" | python3 -c 'import json, sys; d=json.load(sys.stdin); print(json.dumps(d[:3]))' 2>/dev/null || true) + truncated=$(echo "${ready}" | python3 -c 'import json, sys +d = json.load(sys.stdin) +if isinstance(d, dict) and "data" in d: + d = d["data"] +print(json.dumps(d[:3]))' 2>/dev/null || true) if [[ -n "${truncated}" ]]; then echo "- **Ready Tasks (Top 3)**: ${truncated}" return diff --git a/skills/flow/references/setup.md b/skills/flow/references/setup.md index cdb2c0b..965f901 100644 --- a/skills/flow/references/setup.md +++ b/skills/flow/references/setup.md @@ -261,6 +261,17 @@ bd config set export.git-add false Flow owns the host instruction files, so Beads setup must skip its generated agent files. The config commands keep Beads local-only by default: no automatic export, no auto-staging, and no git operations in `bd prime` output. +Opt the project into the bd v2.0 JSON envelope so `bd --json` stops printing the deprecation notice on every command. Append the Viper key idempotently to `.beads/config.yaml`: + +```bash +mkdir -p .beads +if [ ! -f .beads/config.yaml ] || ! grep -q '^json-envelope:' .beads/config.yaml; then + printf 'json-envelope: true\n' >> .beads/config.yaml +fi +``` + +bd 1.x reads the toggle only from `BD_JSON_ENVELOPE`; flow's hooks export that during sessions. Writing the YAML key now records the intent in version-controllable form so the project is ready when beads wires the toggle through Viper. + Or prompt user: > **Beads mode:** diff --git a/templates/agent/workflow.md b/templates/agent/workflow.md index dc31da7..22c924c 100644 --- a/templates/agent/workflow.md +++ b/templates/agent/workflow.md @@ -39,7 +39,7 @@ Flow supports two modes: Configured for local-only use during setup unless the user explicitly asks for shared repo state. -Default setup writes `.agents/beads.json` with `syncPolicy.autoExport: false`, `syncPolicy.autoGitAdd: false`, and `syncPolicy.allowDoltPush: false`. It also applies `bd config set no-git-ops true`, `bd config set export.auto false`, and `bd config set export.git-add false`. +Default setup writes `.agents/beads.json` with `syncPolicy.autoExport: false`, `syncPolicy.autoGitAdd: false`, and `syncPolicy.allowDoltPush: false`. It also applies `bd config set no-git-ops true`, `bd config set export.auto false`, and `bd config set export.git-add false`, and appends `json-envelope: true` to `.beads/config.yaml` to opt into the bd v2.0 JSON envelope. ### Session Protocol diff --git a/templates/opencode/agents/flow.md b/templates/opencode/agents/flow.md index ae94698..2138f59 100644 --- a/templates/opencode/agents/flow.md +++ b/templates/opencode/agents/flow.md @@ -36,6 +36,7 @@ bd init --non-interactive --stealth --prefix --skip-agents # bd config set no-git-ops true bd config set export.auto false bd config set export.git-add false +mkdir -p .beads && grep -q '^json-envelope:' .beads/config.yaml 2>/dev/null || printf 'json-envelope: true\n' >> .beads/config.yaml # Opt into bd v2.0 envelope bd status # Workspace overview bd ready # Ready queue ``` diff --git a/templates/opencode/commands/flow-setup.md b/templates/opencode/commands/flow-setup.md index 8ed71a6..63fe439 100644 --- a/templates/opencode/commands/flow-setup.md +++ b/templates/opencode/commands/flow-setup.md @@ -261,9 +261,14 @@ bd init --non-interactive --stealth --prefix --skip-agents bd config set no-git-ops true bd config set export.auto false bd config set export.git-add false + +mkdir -p .beads +if [ ! -f .beads/config.yaml ] || ! grep -q '^json-envelope:' .beads/config.yaml; then + printf 'json-envelope: true\n' >> .beads/config.yaml +fi ``` -These defaults keep Beads local-only: no automatic export, no auto-staging, and no git operations in `bd prime` output. `bd dolt push` remains explicit opt-in only. +These defaults keep Beads local-only: no automatic export, no auto-staging, and no git operations in `bd prime` output. `bd dolt push` remains explicit opt-in only. The `json-envelope: true` Viper key opts the project into the bd v2.0 JSON envelope so `bd --json` stops emitting the deprecation notice; flow's hooks export `BD_JSON_ENVELOPE=1` until beads wires this through Viper. If no-Beads mode was selected: