beads/cmd/bd/create_input.go
Harry Miller ce756a5b86
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>
2026-09-26 03:24:57 -07:00

379 lines
13 KiB
Go

package main
import (
"encoding/json"
"fmt"
"os"
"strings"
"time"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/debug"
"github.com/steveyegge/beads/internal/timeparsing"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
"github.com/steveyegge/beads/internal/utils"
"github.com/steveyegge/beads/internal/validation"
)
type createInput struct {
markdownFile string
graphFile string
title string
explicitID string
parentID string
issueType string
status string
priority int
assignee string
externalRef string
specID string
description string
design string
acceptanceCriteria string
notes string
appendNotes string
labels []string
noInheritLabels bool
deps []string
waitsFor string
waitsForGate string
waitsForGateSet bool // true when --waits-for-gate was explicitly passed (not relying on default)
silent bool
dryRun bool
force bool
validate bool
ephemeral bool
noHistory bool
storageClass types.StorageClass
storageClassFlag string
molType types.MolType
wispType types.WispType
eventCategory string
eventActor string
eventTarget string
eventPayload string
dueAt *time.Time
deferUntil *time.Time
metadata json.RawMessage
metadataSet bool
estimatedMinutes *int
repoOverride string
repoOverrideSet bool
createdBy string
owner string
jsonOutput bool
validationMode string
}
// graphApplyOptions projects the plan-wide CLI flags into the options every
// graph validation/materialization helper takes.
func (in createInput) graphApplyOptions() GraphApplyOptions {
return GraphApplyOptions{Ephemeral: in.ephemeral, NoHistory: in.noHistory, Force: in.force}
}
// graphApplyOptionsFromFlags is the embedded-path projection of the plan-wide
// flags, delegating to graphApplyOptions so both transports share one
// flags→options mapping (the embedded create path reads flags directly
// rather than through gatherCreateInput).
func graphApplyOptionsFromFlags(cmd *cobra.Command) GraphApplyOptions {
var in createInput
in.ephemeral, _ = cmd.Flags().GetBool("ephemeral")
in.noHistory, _ = cmd.Flags().GetBool("no-history")
in.force, _ = cmd.Flags().GetBool("force")
return in.graphApplyOptions()
}
func gatherCreateInput(cmd *cobra.Command, args []string) (createInput, error) {
in := createInput{}
in.markdownFile, _ = cmd.Flags().GetString("file")
in.graphFile, _ = cmd.Flags().GetString("graph")
in.dryRun, _ = cmd.Flags().GetBool("dry-run")
if in.markdownFile != "" && in.graphFile != "" {
return in, HandleError("cannot specify both --file and --graph")
}
if in.markdownFile != "" {
if len(args) > 0 {
return in, HandleError("cannot specify both title and --file flag; for a single issue's description from a file, use --body-file")
}
if in.dryRun {
return in, HandleError("--dry-run is not supported with --file flag")
}
if err := rejectSingleIssueFlagsForMarkdown(cmd); err != nil {
return in, err
}
}
if in.graphFile != "" {
if len(args) > 0 {
return in, HandleError("cannot specify both title and --graph flag")
}
if err := rejectSingleIssueFlagsForGraph(cmd); err != nil {
return in, err
}
}
in.silent, _ = cmd.Flags().GetBool("silent")
in.force, _ = cmd.Flags().GetBool("force")
in.validate, _ = cmd.Flags().GetBool("validate")
in.noInheritLabels, _ = cmd.Flags().GetBool("no-inherit-labels")
in.ephemeral, _ = cmd.Flags().GetBool("ephemeral")
in.noHistory, _ = cmd.Flags().GetBool("no-history")
if in.ephemeral && in.noHistory {
return in, HandleError("--ephemeral and --no-history are mutually exclusive")
}
titleFlag, _ := cmd.Flags().GetString("title")
title, err := resolveTitle(args, titleFlag, in.markdownFile, in.graphFile)
if err != nil {
return in, err
}
in.title = title
desc, descChanged, err := getDescriptionFlag(cmd)
if err != nil {
return in, err
}
if err := validateDescriptionUpdate(cmd, desc, descChanged); err != nil {
return in, HandleError("%v", err)
}
in.description = desc
skills, _ := cmd.Flags().GetString("skills")
if skills != "" {
if in.description != "" {
in.description += "\n\n"
}
in.description += "## Required Skills\n" + skills
}
ctxStr, _ := cmd.Flags().GetString("context")
if ctxStr != "" {
if in.description != "" {
in.description += "\n\n"
}
in.description += "## Context\n" + ctxStr
}
design, _, err := getDesignFlag(cmd)
if err != nil {
return in, err
}
in.design = design
in.acceptanceCriteria, _ = cmd.Flags().GetString("acceptance")
in.notes, _ = cmd.Flags().GetString("notes")
in.appendNotes, _ = cmd.Flags().GetString("append-notes")
in.specID, _ = cmd.Flags().GetString("spec-id")
if in.markdownFile == "" && in.graphFile == "" {
if in.description == "" && !isTestIssue(in.title) {
if config.GetBool("create.require-description") {
return in, HandleError("description is required (set create.require-description: false in config.yaml to disable)")
}
}
}
priorityStr, _ := cmd.Flags().GetString("priority")
priority, err := validation.ValidatePriority(priorityStr)
if err != nil {
return in, HandleError("%v", err)
}
in.priority = priority
in.issueType, _ = cmd.Flags().GetString("type")
// The raw flag rides along for the --file batch, which resolves the class
// per template (the per-type config default needs a type to key on, and only
// a template has one). --graph rejects the flag outright, so the only route
// that resolves it here is the single-issue create, on both transports.
in.storageClassFlag, _ = cmd.Flags().GetString("storage-class")
if in.markdownFile == "" && in.graphFile == "" {
class, wisp, err := resolveCreateStorageClass(in.storageClassFlag, types.IssueType(in.issueType), in.ephemeral, in.noHistory)
if err != nil {
return in, HandleError("%v", err)
}
in.storageClass = class
in.ephemeral = wisp
}
in.status, _ = cmd.Flags().GetString("status")
in.assignee, _ = cmd.Flags().GetString("assignee")
in.externalRef, _ = cmd.Flags().GetString("external-ref")
in.explicitID, _ = cmd.Flags().GetString("id")
in.parentID, _ = cmd.Flags().GetString("parent")
in.waitsFor, _ = cmd.Flags().GetString("waits-for")
in.waitsForGate, _ = cmd.Flags().GetString("waits-for-gate")
in.waitsForGateSet = cmd.Flags().Changed("waits-for-gate")
if in.explicitID != "" && in.parentID != "" {
return in, HandleError("cannot specify both --id and --parent flags")
}
in.labels, _ = cmd.Flags().GetStringSlice("labels")
labelAlias, _ := cmd.Flags().GetStringSlice("label")
if len(labelAlias) > 0 {
in.labels = append(in.labels, labelAlias...)
}
// Normalize after merging the alias so dedupe spans both flags. Read paths
// (list, search, ready, orphans) already do this; without it here, `--labels
// 'a, b'` stores " b" with pflag's leading space and can never match its own
// filter.
in.labels = utils.NormalizeLabels(in.labels)
warnLabelsContainingWhitespace(in.labels)
in.deps, _ = cmd.Flags().GetStringSlice("deps")
in.repoOverride, _ = cmd.Flags().GetString("repo")
in.repoOverrideSet = cmd.Flags().Changed("repo")
if molTypeStr, _ := cmd.Flags().GetString("mol-type"); molTypeStr != "" {
mt := types.MolType(molTypeStr)
if !mt.IsValid() {
return in, HandleError("invalid mol-type %q (must be %s)", molTypeStr, types.ValidMolTypeNames())
}
in.molType = mt
}
if wispTypeStr, _ := cmd.Flags().GetString("wisp-type"); wispTypeStr != "" {
wt := types.WispType(wispTypeStr)
if !wt.IsValid() {
return in, HandleError("invalid wisp-type %q (must be %s)", wispTypeStr, types.ValidWispTypeNames())
}
in.wispType = wt
}
in.eventCategory, _ = cmd.Flags().GetString("event-category")
in.eventActor, _ = cmd.Flags().GetString("event-actor")
in.eventTarget, _ = cmd.Flags().GetString("event-target")
in.eventPayload, _ = cmd.Flags().GetString("event-payload")
if (in.eventCategory != "" || in.eventActor != "" || in.eventTarget != "" || in.eventPayload != "") && in.issueType != "event" {
return in, HandleError("--event-category, --event-actor, --event-target, and --event-payload flags require --type=event")
}
if dueStr, _ := cmd.Flags().GetString("due"); dueStr != "" {
t, err := timeparsing.ParseRelativeTime(dueStr, time.Now())
if err != nil {
return in, HandleError("invalid --due format %q. Examples: +6h, tomorrow, next monday, 2025-01-15", dueStr)
}
in.dueAt = &t
}
if deferStr, _ := cmd.Flags().GetString("defer"); deferStr != "" {
t, err := timeparsing.ParseRelativeTime(deferStr, time.Now())
if err != nil {
return in, HandleError("invalid --defer format %q. Examples: +1h, tomorrow, next monday, 2025-01-15", deferStr)
}
if t.Before(time.Now()) && !in.silent && !debug.IsQuiet() {
fmt.Fprintf(os.Stderr, "%s Defer date %q is in the past. Issue will appear in bd ready immediately.\n",
ui.RenderWarn("!"), t.Local().Format("2006-01-02 15:04"))
fmt.Fprintf(os.Stderr, " Did you mean a future date? Use --defer=+1h or --defer=tomorrow\n")
}
in.deferUntil = &t
}
if cmd.Flags().Changed("metadata") {
metadataValue, _ := cmd.Flags().GetString("metadata")
metadata, err := readMetadataFlag(metadataValue)
if err != nil {
return in, HandleError("%v", err)
}
in.metadata = metadata
in.metadataSet = true
}
if cmd.Flags().Changed("estimate") {
est, _ := cmd.Flags().GetInt("estimate")
if est < 0 {
return in, HandleError("estimate must be a non-negative number of minutes")
}
in.estimatedMinutes = &est
}
in.createdBy = getActorWithGit()
in.owner = getOwner()
in.jsonOutput = jsonOutput
in.validationMode = config.GetString("validation.on-create")
if in.validate {
in.validationMode = "error"
}
return in, nil
}
var singleIssueOnlyFlags = []string{
"title",
"id", "parent", "no-inherit-labels",
"deps", "waits-for", "waits-for-gate",
"type", "priority", "assignee", "external-ref", "spec-id",
"status",
"description", "body", "message", "body-file", "description-file", "stdin",
"design", "design-file", "acceptance", "notes", "append-notes",
"allow-empty-description",
"labels", "label", "skills", "context",
"event-category", "event-actor", "event-target", "event-payload",
"due", "defer",
"metadata", "estimate", "wisp-type",
}
func rejectSingleIssueFlagsForMarkdown(cmd *cobra.Command) error {
for _, name := range singleIssueOnlyFlags {
if cmd.Flags().Changed(name) {
return HandleError("--%s is not valid with --file (markdown templates supply per-issue fields)", name)
}
}
// --force is plan-wide for --graph (foreign-prefix explicit IDs) but the
// markdown path never consults it, so reject it here rather than accept
// and silently ignore.
if cmd.Flags().Changed("force") {
return HandleError("--force is not valid with --file (markdown templates supply per-issue fields)")
}
return nil
}
func rejectSingleIssueFlagsForGraph(cmd *cobra.Command) error {
for _, name := range singleIssueOnlyFlags {
if cmd.Flags().Changed(name) {
return HandleError("--%s is not valid with --graph (graph plans supply per-node fields)", name)
}
}
if cmd.Flags().Changed("mol-type") {
return HandleError("--mol-type is not valid with --graph (set mol_type per node in the plan instead)")
}
// Same shape as --mol-type: a plan-wide class would duplicate the per-node
// storage_class field (plus its per-type config default) that graph-apply
// already honors, so the flag is refused rather than accepted and ignored.
if cmd.Flags().Changed("storage-class") {
return HandleError("--storage-class is not valid with --graph (set storage_class per node in the plan instead)")
}
return nil
}
func resolveTitle(args []string, titleFlag, markdownFile, graphFile string) (string, error) {
if markdownFile != "" || graphFile != "" {
return "", nil
}
var title string
switch {
case len(args) > 0 && titleFlag != "":
if args[0] != titleFlag {
return "", HandleError("cannot specify different titles as both positional argument and --title flag\n Positional: %q\n --title: %q", args[0], titleFlag)
}
title = args[0]
case len(args) > 0:
if strings.HasPrefix(args[0], "-") {
return "", HandleError("title %q looks like a flag (starts with '-').\n Run 'bd create --help' for available options.\n To use this title anyway, pass it explicitly: bd create --title=%q", args[0], args[0])
}
title = args[0]
case titleFlag != "":
title = titleFlag
default:
return "", HandleError("title required (or use --file to create from markdown)")
}
if strings.TrimSpace(title) == "" {
return "", HandleError("title cannot be empty or whitespace-only")
}
return title, nil
}