feat(update): address envs by their printed key; add scope flags (#166)

[fentas]

Fixes #166.

Problem

b update <arg> resolved every arg through the binary parser first (provider.ParseRef), which splits on @ and is not SSH-aware. So:

• The exact key b env status prints for an SSH-keyed env (git@github.com:org/repo#main) could never be passed back — it parsed to git and failed as "unknown binary or env: git".
• A path like github.com/acme/framework silently fell into binary space → "release not found".
• --group filtered only envs while still updating every binary, so there was no way to refresh vendored env content without toolchain churn.

Root cause: one flat positional addresses two namespaces (binaries + envs) with overlapping grammars, and we committed to the binary grammar before the env namespace (which has the SSH-aware parser) was ever consulted.

Fix — resolve by config membership + an env marker

resolveUpdateArg now decides by what's actually in b.yaml, not by guessing from shape:

• docker:// / oci:// / go:// → always binary (# there is a path/module char, never an env label).
• A local path, or a # outside those protocols → env marker: resolve as env (SSH/local-aware), error if no such env (the user was explicit).
• Otherwise → match envs by exact/canonical key before binary space, so the printed key round-trips and an env ref isn't hijacked by the github.com/org/repo provider convention. A trailing # forces env for keys that are also valid binary refs (dual-namespace escape hatch).
• Typing the https path of an SSH-keyed env still resolves to an ad-hoc binary but prints a "did you mean env …" hint.

Scope flags

• --group now implies env-only (groups are an env-only concept — binaries have no group). This is the direct fix for the --group part of b update can't scope to a single env — SSH-keyed envs are unaddressable, and --group doesn't gate binaries #166.
• Added --envs-only / --binaries-only, validated mutually-exclusive and rejected alongside explicit args.

Notes

• The issue's "minor" item (a generated b.yaml header saying "Run b env sync") is already gone from current source — nothing to change.
• Deliberately not rewriting env keys in b.yaml on save; the membership resolver makes it unnecessary, and silently rewriting user keys is the class of bug we fixed in fix(state): keep relative file paths on save; clearer install errors #159.

Tests

pkg/cli/update_envaddr_test.go (19 cases): SSH-key round-trip, label-less SSH bare, trailing-# force, env-marker-no-match error, https-key-not-hijacked regression guard, claim-3 hint, docker-#-stays-binary, repoTail folding, scope-flag validation, and three runAll scoping tests. go build, go vet ./..., gofmt, full go test ./... all clean.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR fixes b update <arg> ambiguity between binaries and envs (notably SSH-keyed env refs) by resolving args based on config membership and explicit env markers, and adds namespace scoping flags to update only envs or only binaries.

Changes:

• Add resolveUpdateArg to correctly round-trip env keys (including git@...#label) and provide “did you mean env …” hints when users type an https form that maps to an SSH-keyed env.
• Introduce update scoping via --envs-only / --binaries-only, and make --group imply env-only when running b update with no args.
• Add docs + tests covering env address resolution, hinting, and scoping behavior.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
pkg/cli/update.go	Implements new arg resolution and scope flag validation + run-all scoping.
pkg/cli/update_envaddr_test.go	Adds resolver and scoping tests for issue #166 regression coverage.
docs/b/subcommands/update.mdx	Documents env addressing and new scope flags/--group semantics.

[fentas]

Review — solid fix; resolves the core of #166. Membership-based resolveUpdateArg (env-match before binary parsing) is the right call, and --group implying env-scope + --envs-only/--binaries-only closes the binary-churn half cleanly. Confirmed the printed SSH key round-trips. A few open points, mostly small:

1. Short-name addressing — b update lok8s# routes correctly but can't match (the main one)

The # correctly sends it down the env-marker branch, but matchEnv only does exact + canonical-key lookup:

if e := o.Config.Envs.Get(arg); e != nil { ... }              // "lok8s#" → no
if key := canonicalEnvKey(arg); key != arg { Envs.Get(key) }  // "lok8s"  → no

canonicalEnvKey("lok8s#") → "lok8s", and the env is keyed git@github.com:org/repo#main, so you get unknown env: lok8s#. Since the printed key is long, a short handle is the ergonomic win — and repoTail already computes org/repo for the suggestEnv hint. Promoting it to a third matchEnv tier (exact → canonical → repo-tail) makes lok8s# / org/repo# first-class, with ambiguity → error listing the candidate keys.

(Side note: --envs-only as a selector — e.g. lok8s --envs-only — is the wrong layering, and it's already correctly rejected by the (EnvsOnly || BinariesOnly) && len(specifiedArgs) > 0 guard. The # marker is the better idiom.)

2. Trailing-# against a labeled env — worth a targeted test

canonicalEnvKey("org/repo#") reduces to base org/repo (label dropped). Does Envs.Get(base) match an env keyed org/repo#main? If Get is exact, the force-# could miss labeled envs. There's a "trailing-# force" case in the suite — just make sure one of them targets an env that actually has a #label.

3. (minor) https-path hint — surface in docs

github.com/org/repo still resolves to binary-space with the "did you mean env" note — good. A line in update.mdx ("to target an env, paste the key b env status prints, or append #") would save the round-trip.

4. (minor) the #166 doc item

You note the generated b env sync comment is already gone — I hit it on v4.13.0's emitted b.yaml, so just confirm the current generator/templates don't still write it.

Net: ship-able for the core; #1 is the one I'd fold in, since it's the natural follow-up to "address by the printed key."

🤖 via Claude Code

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

[fentas]

Review loop complete — 4 rounds (Copilot + subagent in parallel) + a final verification pass. Findings addressed across 5a5a043, ea84a9a, 47839b4, 1f5a05d, bf6f3b6: env-key round-trip incl. SSH keys, short handles, ambiguity-aware hints, --group/--envs-only/--binaries-only scope, gitcache.RepoPath (ports/.git/), git:// # exemption, --plan-json empty-array fix. 1 false positive refuted, 2 nits declined with rationale. All threads resolved; build/vet/fmt/test green.