fix(metadata): require a JSON object for --metadata on create and update (#6035) (#6743)

* fix(metadata): require a JSON object for --metadata on create and update (#6035)

Root cause: the four --metadata entry points (create and update, each in
its direct and proxied-server variant: create.go, create_input.go,
update.go, update_input.go) carried copies of the same check, json.Valid,
which accepts any JSON value. `bd create --metadata '"oops"'` therefore
stored a bare string (or an array, number or null) as the issue's
metadata. `bd update` with the same value was refused only late, by the
storage-layer merge, with an internal unmarshal error.

Fix: one shared readMetadataFlag helper resolves the value (inline or
@file.json) and requires a top-level JSON object, refusing a string,
number, boolean, array or null with "invalid --metadata: must be a JSON
object such as {"key":"value"}, got <kind>". The rule matches what the
storage merge already enforces for update (it unmarshals into a map and
rejects null), so `{}` stays accepted and null is now refused on create
too, where it used to be stored literally. The storage layer is not
changed.

Not changed: an object whose value is a string that looks like JSON
(`{"mykey":"{\"inner\":\"v\"}"}`, the nested case in the report) is
still accepted and stored as written. Metadata values are opaque, and
refusing such strings would be a design change, not a fix.

Agent-Signature: claude-code-opus-5-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(metadata): cover boolean and null in the end-to-end create/update case (#6743 review)

Agent-Signature: claude-code-opus-5-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(metadata): correct the null-behavior claims and the --metadata help text (#6743 review)

Maintainer review fixups for #6743. The review found no blocker and no major,
and the scorecard approved with no required changes; these are its minors and
nits.

- The helper doc comment and the CHANGELOG entry both said the new object rule
  matches what the storage merge already enforced for update. That holds for a
  string, number, boolean or array, and is false for null: json.Unmarshal of
  the literal null into a map zeroes the map and returns no error, so
  MergeMetadataJSON merged nothing and `bd update --metadata null` exited 0.
  Refusing null is a real, if small, behavior change on update, so both
  surfaces now say that instead of claiming a non-change.

- The --metadata help text on create and update advertised "JSON string", the
  one input this change exists to refuse; both now read "JSON object". The
  generated CLI docs are deliberately not regenerated alongside it:
  docs/cli-docs.pin is v1.2.2, so generate-cli-docs.sh builds bd from that tag
  rather than from the checkout, and the committed pages are refreshed at
  release. Verified both ways -- with this edit alone, check-doc-flags.sh
  Check 4 reports "PASS: generated CLI docs are fresh"; hand-editing
  docs/cli-reference/create.md to the new string instead makes it report
  "FAIL: docs/cli-reference is out of sync with live CLI help".

- The `object == nil` arm of the guard is load-bearing and read as redundant to
  both reviewers, so it now says out loud that it is what catches null, and
  names internal/httpapi/batch_apply.go as the source of the idiom. Keeping the
  unmarshal rather than switching the guard to jsonKind preserves symmetry with
  that plane; the synthesis offered either.

- jsonKind's "empty input" arm is unreachable from both callers, which sit
  behind json.Valid. Documented as defensive rather than dropped, because
  dropping it makes the byte index below panic for any future caller that has
  not validated first.

- os.ReadFile's error is wrapped with %w, so callers of this newly shared
  helper can still reach fs.ErrNotExist.

The PR body asserts the same null premise in two places (its `null` table row
and the "keeps update's existing rule" bullet) and overstates HTTP-plane
enforcement; those are corrected at finalize, since review iterations do not
touch GitHub.

No behavior change beyond the help string. `go test ./cmd/bd -run GH6035`
passes; gofmt, go vet, check-doc-flags.sh and check-doc-freshness.sh clean.

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
This commit is contained in:
Harry Miller 2026-09-26 03:24:57 -07:00 • committed by GitHub
commit ce756a5b86
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 270 additions and 63 deletions

View file

@ -148,6 +148,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`backend_managed` is false on external proxied topologies, where the dolt
server is not bd's process to report on.
- **`bd create --metadata` and `bd update --metadata` now require a JSON
object** ([#6035](https://github.com/gastownhall/beads/issues/6035)). Both
checked only that the value was valid JSON, so `bd create --metadata
'"oops"'` stored a bare string (or an array or number) as the issue's
metadata, while `bd update` refused the same value only late, in the
storage merge, with an internal unmarshal error. A shared check now refuses
a string, number, boolean, array or `null` up front on every create and
update path with `invalid --metadata: must be a JSON object`; `{}` is still
accepted. `null` is the one value update handled differently before: the
storage merge accepted it as a no-op and exited 0, so `bd update --metadata
null` now exits 1 where it used to silently change nothing. Values inside
the object stay opaque, so a string value that looks like JSON is kept as
written.
- **`bd mol ready --gated` no longer refuses under `--proxied-server` when
`BEADS_MAX_ROWS` is set**
([#6293](https://github.com/gastownhall/beads/pull/6293)). The proxied

View file

@ -257,22 +257,11 @@ var createCmd = &cobra.Command{
var metadata json.RawMessage
if cmd.Flags().Changed("metadata") {
metadataValue, _ := cmd.Flags().GetString("metadata")
var metadataJSON string
if strings.HasPrefix(metadataValue, "@") {
filePath := metadataValue[1:]
// #nosec G304 -- user explicitly provides file path via @file.json syntax
data, err := os.ReadFile(filePath)
if err != nil {
return HandleError("failed to read metadata file %s: %v", filePath, err)
}
metadataJSON = string(data)
} else {
metadataJSON = metadataValue
parsed, err := readMetadataFlag(metadataValue)
if err != nil {
return HandleError("%v", err)
}
if !json.Valid([]byte(metadataJSON)) {
return HandleError("invalid JSON in --metadata: must be valid JSON")
}
metadata = json.RawMessage(metadataJSON)
metadata = parsed
}
validateTemplate, _ := cmd.Flags().GetBool("validate")
@ -961,7 +950,7 @@ func init() {
// --defer=tomorrow Hidden until tomorrow
createCmd.Flags().String("due", "", "Due date/time. Formats: +6h, +1d, +2w, tomorrow, next monday, 2025-01-15")
createCmd.Flags().String("defer", "", "Defer until date (issue hidden from bd ready until then). Same formats as --due")
createCmd.Flags().String("metadata", "", "Set custom metadata (JSON string or @file.json to read from file)")
createCmd.Flags().String("metadata", "", "Set custom metadata (JSON object, or @file.json to read from file)")
// Note: --json flag is defined as a persistent flag in main.go, not here
rootCmd.AddCommand(createCmd)
}

View file

@ -241,6 +241,31 @@ func TestEmbeddedCreate(t *testing.T) {
}
})
// GH#6035: create stored a bare JSON string/array/number as metadata,
// and update rejected the same value only late, in the storage merge.
t.Run("metadata_must_be_object_GH6035", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mo")
const want = "invalid --metadata: must be a JSON object"
target := bdCreate(t, bd, dir, "Metadata target", "--metadata", `{"a":1}`)
var metadata map[string]any
if err := json.Unmarshal(target.Metadata, &metadata); err != nil || metadata["a"] != float64(1) {
t.Fatalf("object metadata = %q, err = %v", target.Metadata, err)
}
for _, value := range []string{`"oops"`, `[1,2]`, `42`, `true`, `null`} {
if out := bdCreateFail(t, bd, dir, "Bad metadata", "--metadata", value); !strings.Contains(out, want) {
t.Fatalf("create --metadata %s output = %s, want %q", value, out, want)
}
if out := bdUpdateFail(t, bd, dir, target.ID, "--metadata", value); !strings.Contains(out, want) {
t.Fatalf("update --metadata %s output = %s, want %q", value, out, want)
}
}
got := bdShow(t, bd, dir, target.ID)
var after map[string]any
if err := json.Unmarshal(got.Metadata, &after); err != nil || len(after) != 1 || after["a"] != float64(1) {
t.Fatalf("rejected updates changed metadata to %q, err = %v", got.Metadata, err)
}
})
t.Run("relationships_and_parent_journey", func(t *testing.T) {
dir, beadsDir, _ := bdInit(t, bd, "--prefix", "rp")
blocker := bdCreate(t, bd, dir, "Blocker")

View file

@ -272,22 +272,11 @@ func gatherCreateInput(cmd *cobra.Command, args []string) (createInput, error) {
if cmd.Flags().Changed("metadata") {
metadataValue, _ := cmd.Flags().GetString("metadata")
var metadataJSON string
if strings.HasPrefix(metadataValue, "@") {
filePath := metadataValue[1:]
// #nosec G304 -- user explicitly provides file path via @file.json syntax
data, err := os.ReadFile(filePath)
if err != nil {
return in, HandleError("failed to read metadata file %s: %v", filePath, err)
}
metadataJSON = string(data)
} else {
metadataJSON = metadataValue
metadata, err := readMetadataFlag(metadataValue)
if err != nil {
return in, HandleError("%v", err)
}
if !json.Valid([]byte(metadataJSON)) {
return in, HandleError("invalid JSON in --metadata: must be valid JSON")
}
in.metadata = json.RawMessage(metadataJSON)
in.metadata = metadata
in.metadataSet = true
}

78
cmd/bd/metadata_flag.go Normal file
View file

@ -0,0 +1,78 @@
package main
import (
"encoding/json"
"fmt"
"os"
"strings"
)
// readMetadataFlag resolves a --metadata flag value (inline JSON, or
// @file.json to read it from a file) and requires it to be a JSON object.
//
// create and update share it so both commands, proxied or not, agree on the
// shape (GH#6035). `{}` is accepted; a bare string, number, boolean, array,
// or null is refused here with a clear message instead of being stored as-is
// (create) or failing late in the merge (update).
//
// That is close to, but not the same as, what the storage merge enforced for
// update. storage.MergeMetadataJSON unmarshals the incoming document into a
// map, which rejects a string, number, boolean or array with an internal
// error -- but JSON null unmarshals into a map with no error at all, so
// `bd update --metadata null` used to exit 0 having merged nothing. Refusing
// null up front is therefore a deliberate (small) behavior change on update,
// not a restatement of the merge's rule.
//
// Values inside the object are opaque, so a string value that happens to look
// like JSON is kept verbatim.
func readMetadataFlag(value string) (json.RawMessage, error) {
metadataJSON := value
if strings.HasPrefix(value, "@") {
filePath := value[1:]
// #nosec G304 -- user explicitly provides file path via @file.json syntax
data, err := os.ReadFile(filePath)
if err != nil {
return nil, fmt.Errorf("failed to read metadata file %s: %w", filePath, err)
}
metadataJSON = string(data)
}
if !json.Valid([]byte(metadataJSON)) {
return nil, fmt.Errorf("invalid JSON in --metadata: must be valid JSON")
}
var object map[string]json.RawMessage
// The nil check is the arm that catches `null`: unmarshalling the JSON
// literal null into a map zeroes the map and reports no error, so testing
// err alone would let null through. Same idiom as the metadata checks in
// internal/httpapi/batch_apply.go.
if err := json.Unmarshal([]byte(metadataJSON), &object); err != nil || object == nil {
return nil, fmt.Errorf(`invalid --metadata: must be a JSON object such as {"key":"value"}, got %s`, jsonKind(metadataJSON))
}
return json.RawMessage(metadataJSON), nil
}
// jsonKind names the top-level kind of a valid JSON document for error text.
//
// The "empty input" arm is defensive, not a reachable case for the caller
// above: json.Valid is false for both "" and whitespace-only input, so a
// document that has already passed it can never trim to empty. It keeps the
// byte index below safe for any future caller that has not validated first.
func jsonKind(doc string) string {
trimmed := strings.TrimSpace(doc)
if trimmed == "" {
return "empty input"
}
switch trimmed[0] {
case '"':
return "a JSON string"
case '[':
return "a JSON array"
case 't', 'f':
return "a JSON boolean"
case 'n':
return "JSON null"
case '{':
return "a JSON object"
default:
return "a JSON number"
}
}

View file

@ -0,0 +1,135 @@
package main
import (
"context"
"os"
"path/filepath"
"strings"
"testing"
"github.com/spf13/cobra"
)
// GH#6035: --metadata only checked json.Valid, so `bd create --metadata
// '"oops"'` stored a bare JSON string as the metadata, while `bd update`
// with the same value failed late in the storage merge. Both commands now
// require a top-level JSON object up front.
const metadataObjectErr = "invalid --metadata: must be a JSON object"
var nonObjectMetadata = []struct {
value string
kind string
}{
{`"oops"`, "a JSON string"},
{`[1,2]`, "a JSON array"},
{`42`, "a JSON number"},
{`true`, "a JSON boolean"},
{`null`, "JSON null"},
}
func TestReadMetadataFlagRequiresObjectGH6035(t *testing.T) {
for _, tt := range nonObjectMetadata {
t.Run(tt.value, func(t *testing.T) {
_, err := readMetadataFlag(tt.value)
if err == nil {
t.Fatalf("readMetadataFlag(%s) accepted a non-object", tt.value)
}
if !strings.Contains(err.Error(), metadataObjectErr) || !strings.Contains(err.Error(), tt.kind) {
t.Fatalf("readMetadataFlag(%s) error = %q, want %q naming %q", tt.value, err, metadataObjectErr, tt.kind)
}
})
}
// Objects pass through verbatim, including a string value that happens
// to look like JSON: values inside the object are opaque.
for _, value := range []string{`{}`, `{"a":1}`, ` {"mykey":"{\"inner\":\"v\"}"} `} {
got, err := readMetadataFlag(value)
if err != nil {
t.Fatalf("readMetadataFlag(%s): %v", value, err)
}
if string(got) != value {
t.Fatalf("readMetadataFlag(%s) = %s, want it unchanged", value, got)
}
}
if _, err := readMetadataFlag(`{"a":`); err == nil || !strings.Contains(err.Error(), "invalid JSON in --metadata") {
t.Fatalf("malformed JSON error = %v, want the invalid-JSON message", err)
}
dir := t.TempDir()
objPath := filepath.Join(dir, "obj.json")
strPath := filepath.Join(dir, "str.json")
if err := os.WriteFile(objPath, []byte(`{"from":"file"}`), 0o600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(strPath, []byte(`"oops"`), 0o600); err != nil {
t.Fatal(err)
}
if got, err := readMetadataFlag("@" + objPath); err != nil || string(got) != `{"from":"file"}` {
t.Fatalf("@file object = %s, %v", got, err)
}
if _, err := readMetadataFlag("@" + strPath); err == nil || !strings.Contains(err.Error(), metadataObjectErr) {
t.Fatalf("@file string error = %v, want %q", err, metadataObjectErr)
}
}
func TestGatherCreateInputRejectsNonObjectMetadataGH6035(t *testing.T) {
for _, tt := range nonObjectMetadata {
t.Run(tt.value, func(t *testing.T) {
cmd := newCreateFlagsCommand(t, "--title", "Title", "--metadata", tt.value)
var err error
stderr := captureStderr(t, func() {
_, err = gatherCreateInput(cmd, nil)
})
if err == nil {
t.Fatalf("gatherCreateInput accepted --metadata %s", tt.value)
}
if !strings.Contains(stderr, metadataObjectErr) {
t.Fatalf("stderr = %q, want %q", stderr, metadataObjectErr)
}
})
}
cmd := newCreateFlagsCommand(t, "--title", "Title", "--metadata", `{"a":1}`)
in, err := gatherCreateInput(cmd, nil)
if err != nil {
t.Fatalf("gatherCreateInput with an object: %v", err)
}
if string(in.metadata) != `{"a":1}` || !in.metadataSet {
t.Fatalf("metadata = %q, set = %t", in.metadata, in.metadataSet)
}
}
func TestGatherUpdateInputRejectsNonObjectMetadataGH6035(t *testing.T) {
newCmd := func(value string) *cobra.Command {
cmd := &cobra.Command{Use: "update"}
cmd.Flags().String("metadata", "", "Set custom metadata")
if err := cmd.ParseFlags([]string{"--metadata", value}); err != nil {
t.Fatalf("parse update flags: %v", err)
}
return cmd
}
for _, tt := range nonObjectMetadata {
t.Run(tt.value, func(t *testing.T) {
var err error
stderr := captureStderr(t, func() {
_, err = gatherUpdateInput(context.Background(), newCmd(tt.value))
})
if err == nil {
t.Fatalf("gatherUpdateInput accepted --metadata %s", tt.value)
}
if !strings.Contains(stderr, metadataObjectErr) {
t.Fatalf("stderr = %q, want %q", stderr, metadataObjectErr)
}
})
}
in, err := gatherUpdateInput(context.Background(), newCmd(`{"a":1}`))
if err != nil {
t.Fatalf("gatherUpdateInput with an object: %v", err)
}
if string(in.mergeMetadataIn) != `{"a":1}` {
t.Fatalf("mergeMetadataIn = %q", in.mergeMetadataIn)
}
}

View file

@ -351,27 +351,14 @@ pointless).`,
// Metadata flag (GH#1413)
if cmd.Flags().Changed("metadata") {
metadataValue, _ := cmd.Flags().GetString("metadata")
var metadataJSON string
if strings.HasPrefix(metadataValue, "@") {
// Read JSON from file
filePath := metadataValue[1:]
// #nosec G304 -- user explicitly provides file path via @file.json syntax
data, err := os.ReadFile(filePath)
if err != nil {
return HandleErrorRespectJSON("failed to read metadata file %s: %v", filePath, err)
}
metadataJSON = string(data)
} else {
metadataJSON = metadataValue
}
// Validate JSON
if !json.Valid([]byte(metadataJSON)) {
return HandleErrorRespectJSON("invalid JSON in --metadata: must be valid JSON")
metadata, err := readMetadataFlag(metadataValue)
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
// Passed as a merge OPERATION, not a pre-merged value: the storage
// layer re-reads and merges inside the mutation transaction so a
// concurrent writer's keys survive (lost-update fix).
updates[storageissueops.OpMergeMetadata] = json.RawMessage(metadataJSON)
updates[storageissueops.OpMergeMetadata] = metadata
}
// Incremental metadata edits (GH#1406)
@ -1022,7 +1009,7 @@ func init() {
updateCmd.Flags().Bool("no-history", false, "Mark issue as no-history (skip Dolt commits, not GC-eligible)")
updateCmd.Flags().Bool("history", false, "Clear no-history flag (re-enable Dolt commit history)")
// Metadata flag (GH#1413)
updateCmd.Flags().String("metadata", "", "Set custom metadata (JSON string or @file.json to read from file)")
updateCmd.Flags().String("metadata", "", "Set custom metadata (JSON object, or @file.json to read from file)")
// Incremental metadata edits (GH#1406)
updateCmd.Flags().StringArray("set-metadata", nil, "Set metadata key=value (repeatable, e.g., --set-metadata team=platform)")
updateCmd.Flags().StringArray("unset-metadata", nil, "Remove metadata key (repeatable, e.g., --unset-metadata team)")

View file

@ -233,21 +233,11 @@ func gatherUpdateInput(ctx context.Context, cmd *cobra.Command) (*updateInput, e
}
if cmd.Flags().Changed("metadata") {
metadataValue, _ := cmd.Flags().GetString("metadata")
var metadataJSON string
if strings.HasPrefix(metadataValue, "@") {
filePath := metadataValue[1:]
data, err := os.ReadFile(filePath) //#nosec G304 -- user-supplied path via @file syntax
if err != nil {
return nil, HandleErrorRespectJSON("failed to read metadata file %s: %v", filePath, err)
}
metadataJSON = string(data)
} else {
metadataJSON = metadataValue
metadata, err := readMetadataFlag(metadataValue)
if err != nil {
return nil, HandleErrorRespectJSON("%v", err)
}
if !json.Valid([]byte(metadataJSON)) {
return nil, HandleErrorRespectJSON("invalid JSON in --metadata: must be valid JSON")
}
in.mergeMetadataIn = json.RawMessage(metadataJSON)
in.mergeMetadataIn = metadata
}
setMetadataFlags, _ := cmd.Flags().GetStringArray("set-metadata")
unsetMetadataFlags, _ := cmd.Flags().GetStringArray("unset-metadata")