beads/cmd/bd/create.go
Julian Knutsen a2d43e6792
fix(mol): molecule reads, auto-close and close --continue over http through issueops entries (S16) (#7513)
* fix(create): let a remote backend mint the --parent child id

`bd create --parent` always called the raw GetNextChildID first, which the
http backend does not serve, so every child create on a remote workspace
refused before writing anything. The Lifecycle role already mints
<parent>.<n> for a create that carries a ParentID and no id of its own, on
every backend and inside the create's own transaction; conformance
RunIssueOperationsCreateUnderAParentMintsTheNextChildID pins it on every leg,
the served one included (and the bd-enterprise postgres leg the MC server
runs). So the create route needs no new capability token: on a registered
Remote backend the client skips the raw reservation and lets the server mint.
The local route keeps its reservation so its Dolt commit staging is
unchanged, and an explicit --id beside --parent is still refused up front.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(mol): molecule reads, auto-close and close --continue over issueops roles

Over the http backend three molecule paths failed, and two of them
silently:

- `bd mol current` / `bd mol progress` without an id answered "no molecules"
  because the in_progress listing (a raw SearchIssues shape) and the parent
  walk (raw GetDependencyRecordsForIssues) were refused and the refusal was
  swallowed; with an id they refused on raw GetMoleculeProgress.
- The molecule auto-close after `bd close` never ran: findParentMolecules
  swallowed the same refused edge read into "not part of a molecule".
- `bd close --continue` claimed the next step in a raw RunInTransaction.

The direct route now reads molecules through roleMolStore, which answers
through roles every backend serves: EdgeReader (batched at the wire's 100
anchors) for the parent walk, BatchGetter for the roots (Get per id where a
server does not publish issues.batchGet), Relations for the step rows (full
rows; the raw dependents read over http is getIssue's shallow projection,
which zeroed step assignees) and the progress counts, and Reader.List for the
in_progress/hooked listings. The auto-close closes the root through
Lifecycle.Close, and the --continue claim is one Lifecycle.Update guarded by
ExpectedStatus=open.

No refusal is swallowed any more: findParentMolecules, the molecule finders
and the hooked scan return their errors; `mol current/progress` report them;
the auto-close stays best effort but warns on stderr; AdvanceToNextStep only
moves on to the next ready step when the claim LOST a race (status mismatch,
not claimable, already claimed) and returns anything else. The one heuristic
still skipped is the id-pattern heal in loadDescendants, and only for an
ErrUnsupported backend that cannot express an id-prefix search; other
failures now surface. `mol current`/`mol progress` leave the
types.IssueFilter forbidigo hole, since they no longer build a filter.

gc does not depend on bd's molecule auto-close: it runs its own
(cmd/gc/molecule_autoclose.go, from the bd on_close hook and the
controller's bead-close events). Its worker prompts do run `bd mol current`.

Served e2e (TestE2E_MoleculesOverHTTP): create --parent mints <root>.1/.2,
mol current <id> is non-empty with the full in-progress step, mol progress
counts, close --continue auto-advances, closing the last step auto-closes
the root. `mol current` without an id now refuses out loud on this stack
(asserted: never an empty list); its non-empty assertion is skipped until
S6c (externaldeps reader passthrough) is underneath.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(mol): list molecule candidates with the four wire knobs, drop the S6c skip

On top of S6c the in_progress listing behind 'bd mol current' (no id)
reaches the v0 wire encoder, which refuses ListRequest.IncludeAllTypes.
Ask for templates, gates, infra and ephemeral rows explicitly, which the
wire publishes, and run the 'mol current without an id' served case.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(issueops): one library entry each for molecule auto-close, advance and reads

The molecule rules lived only in cmd/bd, in copies that disagreed: two
auto-close implementations that closed the root through different
library entries outside the step close's transaction, a `close
--continue` claim that set no assignee and could take a step another
agent held on the direct and http routes, and three progress counts.
Every molecule rule now has one implementation in the public issueops
package, composed over three roles every backend serves (BatchGetter,
Relations, EdgeReader): MoleculeRoots, LoadMolecule, AnalyzeMolecule,
ViewMolecule, ReadMoleculeProgress, ActiveMoleculeIDs,
CompletedMolecule. Membership is the parent-child edge.

Auto-close: CloseRequest.AutoCloseMolecule and
CloseBatchRequest.AutoCloseMolecule (opt-in, so gc's own auto-close is
not doubled) close the molecule root a close completed IN THE SAME
TRANSACTION, unforced and guarded on the root revision read there:
storageissueops.CloseCompletedMoleculeInTx on the store backends (the
role bodies bound to the caller's tx, TxMoleculeReader) and
uow.CloseCompletedMoleculeInUOW on the unit of work. It replays on an
idempotent re-close, reports the root on CloseResult/CloseOutcome
.AutoClosedMolecule, and a root its own close policy refuses stays open
and is reported (MoleculeAutoCloseRefusal) without failing the step.

Advance: a new MoleculeStepper role (storage.DoltStorage accessor,
uow.MoleculeStepperSource) whose one implementation,
issueops.NewMoleculeStepper, claims the next ready step through the
Claimer (Lifecycle.Update's Claim for a wisp step): assignee set, a step
another actor holds skipped, never taken.

HTTP: closeIssue/batchCloseIssues carry auto_close_molecule behind the
issues.close.autoCloseMolecule behavior token, and POST
/v0/beads/issues/{id}:advanceMolecule (issues.advanceMolecule) serves
the stepper. Handlers only decode, call the role and encode. The client
sends the member and dials the operation only where advertised; against
an older server it DEGRADES rather than refuses — it runs the same
library rule over its own roles (issueops.CloseCompletedMolecule after
the close, NewMoleculeStepper for the advance), so the outcome is the
same in more round trips. The capability fallbacks that lived in
cmd/bd move into the client: BatchGetter answers one getIssue per id
without issues.batchGet, and EdgeReader splits past the operation's 100
anchors.

Conformance: RunMolecule* on dolt, embedded, uow and http (the http leg
twice: served, and against a server with the tokens struck out).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(cmd/bd): molecule commands and create --parent through the library entries

`bd close`, `bd close --continue`, `bd mol current`, `bd mol progress`,
`bd ready --mol` and `bd create --parent` now call the one library entry
for each rule on every route (direct, proxied server, remote):

- close (batch, --if-revision, proxied) sets CloseRequest/
  CloseBatchRequest.AutoCloseMolecule and only reports what the library
  closed in the step close's transaction. autoCloseCompletedMolecule,
  autoCloseProxiedCompletedMolecule and closeCompletedMoleculeRoot are
  gone, and so is the separate post-close write.
- --continue is the route's MoleculeStepper role: a real claim (the
  assignee is set) that skips a step another actor holds. Before, the
  direct and http routes flipped the status only and could take it.
  AdvanceToNextStep, ClaimStepIfOpen and its two implementations are
  gone.
- mol current / mol progress / ready --mol read through
  issueops.ViewMolecule, ReadMoleculeProgress, ActiveMoleculeIDs and
  LoadMolecule/AnalyzeMolecule over the route's roles. Over http this
  fixes the missing step assignee on `ready --mol` (corpus mark
  mc-ready-mol). The proxied route's SearchIssues fallback, the role
  store, the third progress count and the cmd/bd copy of the readiness
  analysis are deleted; only presentation stays here.
- create --parent asks the create role to mint the child id on every
  route (the local CLI reservation is gone) and to inherit the parent's
  labels (InheritLabelsFromParent) inside the create. The dry-run
  preview still shows the labels, and a failed label read there is
  reported, not swallowed.

TestProxiedServerMoleculeLifecycleAgreesOnEveryRoute runs one molecule
lifecycle through the real binary on the direct, proxied and remote
(`bd connect` to `bd serve`) routes and requires the same rows and the
same JSON on all three. The served e2e now also pins the held-step skip,
the claimed step's assignee and the full rows of `ready --mol`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(httpclient): refuse molecule auto-close and advance before dialing an older server

The client used to DEGRADE against a server without
issues.close.autoCloseMolecule / issues.advanceMolecule: it closed the step
without the member and ran a second, client-side copy of the auto-close
(issueops.CloseCompletedMolecule) in its own transactions, and composed the
stepper over its own roles. That kept two executions of each rule alive.
Now the rule runs in ONE place, the server's library: a close or batch close
that sets AutoCloseMolecule, and an Advance, refuse before anything is dialed
with the typed capability error (storage.ErrUnsupported, Capability naming the
token). The composed single-item batch leg now carries the member too.

- issueops.CloseCompletedMolecule (the role-composed form) is gone.
  MoleculeRootClose is the one root close request (unforced, the auto-close
  reason, the session, guarded on the root revision read), and both
  in-transaction bodies (storage issueops CloseCompletedMoleculeInTx, uow
  CloseCompletedMoleculeInUOW) build from it.
- MoleculeView.Ready is `bd ready --mol`'s list (every analysis-ready node,
  hydrated), so ready --mol and mol current derive from ViewMolecule alone.

Tests: unit pre-dial refusal and member pins (httpclient molecule_test.go),
TestServedMoleculeRefusesAgainstAnOlderServer (step stays open, nothing
claimed) replacing the degraded contract arm.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cmd/bd): ask for the molecule auto-close only where the route serves it

The refuse-before-dialing client made every `bd close` over http fail
against a server that does not advertise issues.close.autoCloseMolecule
(an older bd serve, or the MC server shape, whose orchestrator owns the
molecule lifecycle): the CLI always set AutoCloseMolecule.
storage.ServesMoleculeAutoClose answers, through every decorator, whether a
store's closes may carry the flag (MoleculeAutoCloseProber, implemented by
httpclient.Store from its handshake; every local backend serves it). The
direct batch close and the --if-revision close set the flag from it; the
proxied route always serves it. Against a silent server the close goes out
without the member and the server's side owns the auto-close.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(backend/http): scope the advertised-policy check to reads before the close

The close policy check is the client-side policy's last chance: it runs
before the close request, so only the reads up to that request count. A
read after the close (the old-server molecule notice reads the closed
step's edges) is not the external-dependency policy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(backend/http/corpus): drop the six marks S16 and S19 retire

With the molecule library entries underneath, mol current (with and
without an id, json and text), mol progress and ready --mol read through
issueops.LoadMolecule over the roles, and create --parent lets the server
mint the child id. Those six shapes pass on the reference profile.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cmd/bd): never silent against a server without the molecule tokens

Against a server that advertises neither issues.close.autoCloseMolecule
nor issues.advanceMolecule (an older bd serve, or one whose orchestrator
owns the molecule lifecycle):

- `bd close --continue` closed the step and only then found the advance
  refused, leaving the step closed and the next step unclaimed. It now
  asks storage.ServesMoleculeAdvance (a MoleculeAdvanceProber the http
  store answers from its handshake; local backends always serve it)
  BEFORE the close and refuses up front, saying nothing was closed.
- `bd close` went out without auto_close_molecule and said nothing. When
  the closed step belongs to a molecule (issueops.MoleculeRoot), a notice
  on stderr now names the molecule and the missing token: its auto-close
  is the server's to run. The batch and --if-revision closes both say it.

The served e2e masks both tokens out of the handshake and checks the
up-front refusal (the step stays open) and the notice; the httpclient
unit test pins ServesMoleculeAdvance to the handshake.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(cmd/bd): mol show through issueops.LoadMolecule on every route

`bd mol show` still loaded the molecule through cmd/bd's
loadTemplateSubgraph (raw GetIssue, GetDependentsWithMetadata and
GetDependencyRecords, plus an id-pattern child probe), while mol current,
mol progress and ready --mol read through the library. It now loads
through issueops.LoadMolecule over the route's molecule roles (the direct
store's, or the proxied provider's), so membership is the parent-child
edge everywhere and the http route reads through roles the server serves.
The served e2e checks mol show's root and step count.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: the molecule auto-close fails the step's close on a non-policy error; stale comments

CloseRequest.AutoCloseMolecule and CloseCompletedMoleculeInTx now say what
changed when the auto-close moved into the close's transaction: a root
close the close policy refuses still leaves the root open and is reported,
but any other failure (a storage error, a lost race on the root's revision)
fails the step's close with it, where the CLI used to close the root
afterwards and only warn.

Stale: the advanceMolecule vocabulary entry said the client composes the
stepper over its own roles when unserved (it refuses before dialing), and
the graph-create collision probe called itself best-effort by transport
(the http GetIssue miss is storage.ErrNotFound like every other store's).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(changelog): the molecule tokens and the S16/S19 behaviours

Entries for issues.close.autoCloseMolecule and issues.advanceMolecule, the
issueops molecule entries, the auto-close inside the step's close (and a
non-policy failure of it failing the close), the real claim behind
close --continue, the molecule reads on every route, the notice and the
up-front --continue refusal against a server without the tokens, and
create --parent / mol reads over http.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(httpclient): regenerate unsupported_gen.go for MoleculeStepper

The PR adds MoleculeStepper() to storage.DoltStorage (200 -> 201
methods). httpclient implements it by hand, but the generated shell's
trailer still counted 200, so
//internal/storage/unsupportedgen:unsupportedgen_test
(TestGeneratedShellIsFresh) failed in Bazel / test and
Bazel / integration, turning CI Gate / Required red.

Regenerated with `go generate ./internal/httpclient`; the only change
is the trailer count (143 of 201 methods generated; 58 left).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(molecule): auto-close refusals, write skew, close --json, docs

Review fixes for #7513, numbered as in each iteration's review
synthesis.

Iteration 1:

F1: a close guard's refusal of the root (TemplateReadOnlyError,
PinnedError, CloseNotAssigneeError) is an auto-close refusal, like the
close policy's: the root stays open and is reported, and the step's
close stands. Pinned by the new conformance case
RunMoleculeGuardedRootKeepsTheStepClose on dolt, embedded, uow and the
served http client.

F2: two closes that finish a molecule's last two steps in concurrent
transactions each read the other's step as open, so neither closed the
root and both committed. Every auto-close now rewrites the root's
coordination cell before it decides the root (local_metadata
molecule-coordination/v1/<shard>, the dependency coordination idiom and
sharding with a FreshRowLock value), in both twins
(CloseCompletedMoleculesInTx and CloseCompletedMoleculesInUOW). Two
deciders of one root now conflict at commit (1213), and the retry reads
the winner's close and closes the root. This is the synthesis's option
(c), applied through a coordination cell instead of the root row; it
needs no post-commit second transaction and no engine lock. The
deterministic two-transaction regression fails without the touch and
passes with it on dolt and uow; the concurrent-close tests end with the
root closed in every round, reported by exactly one close.

F3: the auto-close checks the root's eligibility before walking any
step, MoleculeStepsClosed stops at the first open step, and a batch
decides each root once and reports it on the first item under it.

F4: ErrVersionMismatch on the root is not a refusal; it fails the
step's close with it. The classifier unit test pins this. A conformance
case cannot stage that race deterministically through the public roles.

F5: storage.ServesMoleculeAdvance answers (bool, error), and bd close
--continue refuses before closing anything when the handshake cannot be
read.

F6: the CHANGELOG and the stepper and batch-closer doc comments say
what the code does.

F7: the unserved-auto-close notice fires only when the close left an
auto-closing molecule with every step closed and its root open
(issueops.CompletedMolecule): again on a re-close, once per root in a
batch, never for a step under an ordinary epic or an unfinished
molecule. Proxied mol show, mol current and mol progress again report a
read unit of work that cannot be opened as itself, not as a molecule
that was not found.

F8: the write-ledger comment says the close is refused before dialing.
The dead FirstClosed/LastClosed guards in mol progress pre-exist on main
and are left as they are.

Iteration 2:

F1: on the proxied route, bd ready --mol reported a read unit
of work it could not open twice: once as itself, then as "molecule
'<id>' not found", which under --json is a second error document on
stdout. It now returns moleculeNotResolved, as mol show, mol current and
mol progress do. TestProxiedReadyMolReportsAnUnopenableReadOnce drives
runMoleculeReady with a provider whose NewUOW fails and wants one Error:
line, or one JSON document; both subtests fail with the old return.

F2: the coordination cell serializes every concurrent close of a step
under an open auto-closing root, not only the closes that finish the
molecule. That is the price of deciding the root in the step's
transaction, so it is documented (TouchMoleculeCoordinationInTx, the
UOW twin, CloseRequest.AutoCloseMolecule, the CHANGELOG) and pinned on
dolt and uow: two sibling closes with a third step still open conflict
(both commit when the touch is removed, on either twin), and a six-step
fan-out closes every step through the store's retry, with the root
closed and reported by exactly one close. The synthesis's alternative,
a post-commit recheck by any close that read a step open, is not taken:
it is a second, best-effort transaction after the step's commit, the
shape this PR exists to remove.

F3: MoleculeRootClose's doc no longer promises that a step reopened
between the completion read and the root close fails the step's close.
The guard is the root's RowVersion, which a step reopen never writes;
the doc now says what the guard covers and that this race goes
undetected (it is inherited from the CLI's old post-commit auto-close).

F4: the user docs describe the auto-close. docs/workflows/molecules.md
replaces "Closing the last child does not close the molecule root"
with which roots close and which stay open, the refusal warning, the
unserved-server note and the --json members, and documents the claiming
--continue and parent-child step membership;
docs/reference/json-schema.md gains a bd close --json section. These
are main-only behaviors on pages pinned to v1.2.2 (docs/cli-docs.pin):
a maintainer call against §1 of
engdocs/decisions/2026-07-17-docs-release-pin.md, as in #6508, #5855,
#5997 and #5092. The auto-close itself shipped in v1.2.2
(cmd/bd/close.go autoCloseCompletedMolecule), so the old sentence was
already wrong at the pin. docs/cli-reference/ is generated from the
pinned release and is not hand-edited; the bd close and bd mol show
help texts carry the same facts and reach it at the next pin bump.

F5: bd close --json reports the auto-close. The entry of a close that
completed a molecule gains auto_closed_molecule (the root it closed) or
molecule_auto_close_refusal (why the root stayed open), the HTTP API's
names, on the direct, proxied and --if-revision routes. The members sit
beside the issue's own rather than wrapping the output in an object the
way --suggest-next does: an object would change the output's shape
exactly when a close completes a molecule and break every consumer that
reads an array, while members leave each entry decoding as the closed
issue, compose with `closed` under the flag objects, and leave a plain
close's bytes unchanged. Pinned on the embedded and proxied tiers
(TestEmbeddedCloseJSONReportsMoleculeAutoClose, TestProxiedServerClose2B
json_reports_*, and both --if-revision replay tests), all red without
the change.

F6: cmd/bd's BeadsTemplateLabel is issueops.MoleculeTemplateLabel, so
the template commands and molecule membership cannot drift apart.

F7: the UOW twin's revision probe says that it writes nothing,
and the BatchCloseRequest.auto_close_molecule spec description has its
verb back (apigen regenerated, no drift).

Iteration 3:

F1: on the unit-of-work route (bd serve, the proxied CLI), a refused
root's molecule_auto_close_refusal and warning carried the use case's
and repository's wrapping ("close <id>: db:
IssueSQLRepository.CloseChecked <id>: ...") around the refusal, where
the tx twin and the docs give the refusal alone. Both twins now report
it through RefusedMoleculeAutoClose, which answers the refusing guard's
or policy's own sentence. RunMoleculeRefusedRootKeepsTheStepClose,
RunMoleculeGuardedRootKeepsTheStepClose and the embedded and proxied
close --json tests want that exact sentence; the uow conformance leg
and the proxied test fail without the unwrap.

F2: the docs no longer promise ErrVersionMismatch for a write to the
root that races its auto-close. The root's read and its revision check
share one transaction snapshot, so that write conflicts with the root
close at commit and the retry decides the root again; the close fails
only if it still conflicts when its retry budget runs out
(MoleculeRootClose, IsMoleculeAutoCloseRefusal,
CloseRequest.AutoCloseMolecule, the tx twin's comment, the CHANGELOG
and the OpenAPI description, apigen regenerated).

F3: TestEmbeddedCloseJSONReportsMoleculeAutoClose moves above
TestEmbeddedCloseConcurrent's doc comment, which documents its own test
again.

F4: bd mol progress counting direct steps while the auto-close counts
every descendant predates this PR; it is left for a follow-up.

F5: cmd/bd's molReader drops GetMoleculeProgress, which nothing called
once mol progress read through issueops.ReadMoleculeProgress.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 19:50:34 +00:00

1114 lines
44 KiB
Go

package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
"sort"
"strconv"
"strings"
"time"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/debug"
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/remotecache"
"github.com/steveyegge/beads/internal/routing"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/dolt"
"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"
"github.com/steveyegge/beads/issueops"
)
// validateCreateArgs runs as cobra's Args validation, which executes before
// PersistentPreRunE opens the store or runs migrations. It reuses
// resolveTitle — the same shared validator gatherCreateInput calls for the
// proxied-server create path — so a whitespace-only title (GH#4771) is
// rejected identically for both backends, and before any invocation that is
// guaranteed to fail wastes a store open/migration.
func validateCreateArgs(cmd *cobra.Command, args []string) error {
markdownFile, _ := cmd.Flags().GetString("file")
graphFile, _ := cmd.Flags().GetString("graph")
titleFlag, _ := cmd.Flags().GetString("title")
_, err := resolveTitle(args, titleFlag, markdownFile, graphFile)
return err
}
var createCmd = &cobra.Command{
Use: "create [title]",
GroupID: "issues",
Aliases: []string{"new"},
Short: "Create a new issue (or batch from markdown/graph JSON)",
Args: cobra.MatchAll(cobra.MaximumNArgs(1), validateCreateArgs),
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
CheckReadonly("create") // also covers the migration freeze check (dc-6jaq)
evt := metrics.NewCommandEvent("create")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
if usesProxiedServer() {
in, err := gatherCreateInput(cmd, args)
if err != nil {
return err
}
return runCreateProxiedServer(cmd, rootCtx, in)
}
file, _ := cmd.Flags().GetString("file")
graphFile, _ := cmd.Flags().GetString("graph")
if file != "" {
// gatherCreateInput repeats the --file argument checks and applies
// the plan-wide flags this route used to accept and ignore
// (--ephemeral, --no-history, --mol-type, --validate). It is the
// same input the proxied route reads, which is what lets both build
// one issueops.CreateBatchRequest.
in, err := gatherCreateInput(cmd, args)
if err != nil {
return err
}
return createIssuesFromMarkdown(rootCtx, in)
}
if graphFile != "" {
if len(args) > 0 {
return HandleError("cannot specify both title and --graph flag")
}
graphDryRun, _ := cmd.Flags().GetBool("dry-run")
graphOpts := graphApplyOptionsFromFlags(cmd)
if err := graphOpts.Validate(); err != nil {
return HandleError("invalid graph options: %v", err)
}
if err := rejectSingleIssueFlagsForGraph(cmd); err != nil {
return err
}
return createIssuesFromGraph(graphFile, graphDryRun, graphOpts)
}
titleFlag, _ := cmd.Flags().GetString("title")
title, err := resolveTitle(args, titleFlag, "", "")
if err != nil {
return err
}
// Get silent flag
silent, _ := cmd.Flags().GetBool("silent")
// Warn if creating a test issue in a database with existing issues.
// A brand-new repo with zero issues is not a "production database" (#2898).
// store is nil here for `create --repo=<remote URL>` from a directory with
// no local .beads/: PersistentPreRunE skips local store init entirely for
// that path, so this check is best-effort only.
if store != nil && isTestIssue(title) && !silent && !debug.IsQuiet() {
if stats, err := store.GetStatistics(context.Background()); err == nil && stats != nil && stats.TotalIssues >= 5 {
fmt.Fprintf(os.Stderr, "%s Creating test issue in production database\n", ui.RenderWarn("⚠"))
fmt.Fprintf(os.Stderr, " Title: %q appears to be test data\n", title)
fmt.Fprintf(os.Stderr, " Recommendation: Use isolated test database with --db\n")
fmt.Fprintf(os.Stderr, " bd --db /tmp/test-beads create %q\n", title)
}
}
description, descriptionChanged, err := getDescriptionFlag(cmd)
if err != nil {
return err
}
if err := validateDescriptionUpdate(cmd, description, descriptionChanged); err != nil {
return HandleError("%v", err)
}
skills, _ := cmd.Flags().GetString("skills")
if skills != "" {
if description != "" {
description += "\n\n"
}
description += "## Required Skills\n" + skills
}
ctxStr, _ := cmd.Flags().GetString("context")
if ctxStr != "" {
if description != "" {
description += "\n\n"
}
description += "## Context\n" + ctxStr
}
if description == "" && !isTestIssue(title) {
if config.GetBool("create.require-description") {
return HandleError("description is required (set create.require-description: false in config.yaml to disable)")
}
}
design, _, err := getDesignFlag(cmd)
if err != nil {
return err
}
acceptance, _ := cmd.Flags().GetString("acceptance")
notes, _ := cmd.Flags().GetString("notes")
specID, _ := cmd.Flags().GetString("spec-id")
priorityStr, _ := cmd.Flags().GetString("priority")
priority, err := validation.ValidatePriority(priorityStr)
if err != nil {
return HandleError("%v", err)
}
// No --priority asks the role for its default (CreateRequest.
// DefaultPriority). The flag's displayed default is that same library
// constant, so the dry-run preview below still shows what will land.
priorityDefault := !cmd.Flags().Changed("priority")
issueType, _ := cmd.Flags().GetString("type")
assignee, _ := cmd.Flags().GetString("assignee")
statusFlag, _ := cmd.Flags().GetString("status")
if statusFlag != "" {
if !types.Status(statusFlag).IsValidWithCustom(loadEmbeddedCustomStatuses()) {
return HandleErrorRespectJSON("invalid status %q (built-in: open, in_progress, blocked, deferred, closed, pinned, hooked; or configure custom statuses via 'bd config set status.custom')", statusFlag)
}
}
labels, _ := cmd.Flags().GetStringSlice("labels")
labelAlias, _ := cmd.Flags().GetStringSlice("label")
if len(labelAlias) > 0 {
labels = append(labels, labelAlias...)
}
labels = utils.NormalizeLabels(labels)
warnLabelsContainingWhitespace(labels)
explicitID, _ := cmd.Flags().GetString("id")
parentID, _ := cmd.Flags().GetString("parent")
externalRef, _ := cmd.Flags().GetString("external-ref")
deps, _ := cmd.Flags().GetStringSlice("deps")
waitsFor, _ := cmd.Flags().GetString("waits-for")
waitsForGate, _ := cmd.Flags().GetString("waits-for-gate")
forceCreate, _ := cmd.Flags().GetBool("force")
repoOverride, _ := cmd.Flags().GetString("repo")
wisp, _ := cmd.Flags().GetBool("ephemeral")
noHistory, _ := cmd.Flags().GetBool("no-history")
if wisp && noHistory {
return HandleError("--ephemeral and --no-history are mutually exclusive")
}
storageClassFlag, _ := cmd.Flags().GetString("storage-class")
storageClass, wisp, err := resolveCreateStorageClass(storageClassFlag, types.IssueType(issueType), wisp, noHistory)
if err != nil {
return HandleError("%v", err)
}
molTypeStr, _ := cmd.Flags().GetString("mol-type")
var molType types.MolType
if molTypeStr != "" {
molType = types.MolType(molTypeStr)
if !molType.IsValid() {
return HandleError("invalid mol-type %q (must be swarm, patrol, or work)", molTypeStr)
}
}
wispTypeStr, _ := cmd.Flags().GetString("wisp-type")
var wispType types.WispType
if wispTypeStr != "" {
wispType = types.WispType(wispTypeStr)
if !wispType.IsValid() {
return HandleError("invalid wisp-type %q (must be heartbeat, ping, patrol, gc_report, recovery, error, or escalation)", wispTypeStr)
}
}
eventCategory, _ := cmd.Flags().GetString("event-category")
eventActor, _ := cmd.Flags().GetString("event-actor")
eventTarget, _ := cmd.Flags().GetString("event-target")
eventPayload, _ := cmd.Flags().GetString("event-payload")
if (eventCategory != "" || eventActor != "" || eventTarget != "" || eventPayload != "") && issueType != "event" {
return HandleError("--event-category, --event-actor, --event-target, and --event-payload flags require --type=event")
}
var dueAt *time.Time
dueStr, _ := cmd.Flags().GetString("due")
if dueStr != "" {
t, err := timeparsing.ParseRelativeTime(dueStr, time.Now())
if err != nil {
return HandleError("invalid --due format %q. %s", dueStr, deferUntilFormatHint)
}
dueAt = &t
}
var deferUntil *time.Time
deferStr, _ := cmd.Flags().GetString("defer")
if deferStr != "" {
t, err := timeparsing.ParseRelativeTime(deferStr, time.Now())
if err != nil {
return HandleError("invalid --defer format %q. %s", deferStr, deferUntilFormatHint)
}
// Warn if defer date is in the past (user probably meant future)
if t.Before(time.Now()) && !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")
}
deferUntil = &t
}
var metadata json.RawMessage
if cmd.Flags().Changed("metadata") {
metadataValue, _ := cmd.Flags().GetString("metadata")
parsed, err := readMetadataFlag(metadataValue)
if err != nil {
return HandleError("%v", err)
}
metadata = parsed
}
validateTemplate, _ := cmd.Flags().GetBool("validate")
validationMode := config.GetString("validation.on-create")
if validateTemplate || validationMode == "error" || validationMode == "warn" {
lintIssue := &types.Issue{
IssueType: types.IssueType(issueType).Normalize(),
Description: description,
AcceptanceCriteria: acceptance,
}
if err := validation.LintIssue(lintIssue); err != nil {
if validateTemplate || validationMode == "error" {
return HandleError("%v", err)
}
fmt.Fprintf(os.Stderr, "%s %v\n", ui.RenderWarn("⚠"), err)
}
}
dryRun, _ := cmd.Flags().GetBool("dry-run")
var estimatedMinutes *int
if cmd.Flags().Changed("estimate") {
est, _ := cmd.Flags().GetInt("estimate")
if est < 0 {
return HandleError("estimate must be a non-negative number of minutes")
}
estimatedMinutes = &est
}
// Use global jsonOutput set by PersistentPreRun
// Determine target repository using routing logic
repoPath := "." // default to current directory
if cmd.Flags().Changed("repo") {
// Explicit --repo flag overrides auto-routing
repoPath = repoOverride
} else {
// Build routing config with backward compatibility for legacy contributor.* keys.
// Prefer config.yaml values, but fall back to DB config values set by bd init --contributor.
routingMode := getRoutingConfigValue(rootCtx, store, "routing.mode")
contributorRepo := getRoutingConfigValue(rootCtx, store, "routing.contributor")
// NFR-001: Backward compatibility - fall back to legacy contributor.* keys
if routingMode == "" {
if getRoutingConfigValue(rootCtx, store, "contributor.auto_route") == "true" {
routingMode = "auto"
}
}
if contributorRepo == "" {
contributorRepo = getRoutingConfigValue(rootCtx, store, "contributor.planning_repo")
}
routingConfig := &routing.RoutingConfig{
Mode: routingMode,
DefaultRepo: getRoutingConfigValue(rootCtx, store, "routing.default"),
MaintainerRepo: getRoutingConfigValue(rootCtx, store, "routing.maintainer"),
ContributorRepo: contributorRepo,
ExplicitOverride: repoOverride,
}
// Auto-routing based on user role, detected only once the resolved
// config shows routing will read it.
userRole := detectUserRoleForRouting(routingConfig)
repoPath = routing.DetermineTargetRepo(routingConfig, userRole, ".")
}
renderDryRun := func() error {
previewIssue := buildCreateIssue(createIssueParams{
ID: explicitID,
Title: title,
Description: description,
Design: design,
AcceptanceCriteria: acceptance,
Notes: notes,
SpecID: specID,
Priority: priority,
IssueType: types.IssueType(issueType).Normalize(),
Assignee: assignee,
ExternalRef: externalRef,
EstimatedMinutes: estimatedMinutes,
Ephemeral: wisp,
NoHistory: noHistory,
StorageClass: storageClass,
CreatedBy: getActorWithGit(),
Owner: getOwner(),
Labels: labels,
MolType: molType,
WispType: wispType,
InitialStatus: statusFlag,
DueAt: dueAt,
DeferUntil: deferUntil,
Metadata: metadata,
EventKind: eventCategory,
Actor: eventActor,
Target: eventTarget,
Payload: eventPayload,
})
if jsonOutput {
return outputJSON(previewIssue)
}
renderCreateDryRunPreview(previewIssue, labels, deps)
return nil
}
if dryRun && parentID == "" {
return renderDryRun()
}
var targetStore storage.DoltStorage
var remoteCache *remotecache.Cache
if !dryRun && repoPath != "." {
if remotecache.IsRemoteURL(repoPath) {
var err error
remoteCache, err = remotecache.DefaultCache()
if err != nil {
return HandleError("failed to initialize remote cache: %v", err)
}
if _, err := remoteCache.Ensure(rootCtx, repoPath); err != nil {
return HandleError("failed to sync remote %s: %v", repoPath, err)
}
targetStore, err = remoteCache.OpenStore(rootCtx, repoPath, newDoltStoreFromConfig)
if err != nil {
return HandleError("failed to open remote store: %v", err)
}
} else {
targetBeadsDir := routing.ExpandPath(repoPath)
debug.Logf("DEBUG: Routing to target repo: %s\n", targetBeadsDir)
// Auto-routed paths (routing.mode: auto, routing.default)
// come from config, not caller input, so they're always
// allowed to auto-vivify as before; only an explicit --repo
// flag value can be ambiguous.
allowCreate := !isAmbiguousRepoTarget(cmd.Flags().Changed("repo"), repoOverride)
if err := ensureBeadsDirForPath(rootCtx, targetBeadsDir, store, allowCreate); err != nil {
return HandleError("failed to initialize target repo: %v", err)
}
targetBeadsDirPath := filepath.Join(targetBeadsDir, ".beads")
var err error
targetStore, err = newDoltStoreFromConfig(rootCtx, targetBeadsDirPath)
if err != nil {
return handleCreateTargetStoreError(err, targetBeadsDirPath, "failed to open target store: %v")
}
}
// Close the original store before replacing it (it won't be used anymore)
// Note: We don't defer-close targetStore here because PersistentPostRun
// will close whatever store is assigned to the global `store` variable.
// This fixes the "database is closed" error during auto-flush (GH#routing-close-bug).
if store != nil {
_ = store.Close() // Best effort cleanup on error path
}
// Replace store for remainder of create operation.
// Must use setStore to sync cmdCtx.Store — a bare `store = targetStore`
// leaves cmdCtx.Store pointing at the closed original, which causes
// "store is closed" in PostRun tip auto-commit (GH#tip-closed-bug).
setStore(targetStore)
}
if explicitID != "" && parentID != "" {
return HandleError("cannot specify both --id and --parent flags")
}
parentLookupStore := store
if dryRun && repoPath != "." {
var err error
parentLookupStore, err = openDryRunTargetStore(rootCtx, repoPath)
if err != nil {
targetPath := repoPath
if !remotecache.IsRemoteURL(repoPath) {
targetPath = filepath.Join(routing.ExpandPath(repoPath), ".beads")
}
return handleCreateTargetStoreError(err, targetPath, "%v")
}
defer func() { _ = parentLookupStore.Close() }()
}
noInheritLabels, _ := cmd.Flags().GetBool("no-inherit-labels")
inheritParentLabels := parentID != "" && !noInheritLabels
if parentID != "" {
// A fail-fast with the message this command has always printed;
// the create role refuses a missing parent on its own as well.
ctx := rootCtx
_, err := parentLookupStore.GetIssue(ctx, parentID)
if err != nil {
if errors.Is(err, storage.ErrNotFound) {
return HandleError("parent issue %s not found", parentID)
}
return HandleError("failed to check parent issue: %v", err)
}
}
if dryRun {
// The preview shows what the create role would inherit; the real
// create asks the role to inherit (CreateRequest.InheritLabelsFromParent)
// inside its own transaction. A failed read is reported, never
// previewed as "no labels".
if inheritParentLabels {
inherited, err := parentLookupStore.GetLabels(rootCtx, parentID)
if err != nil {
return HandleError("failed to read the labels of parent %s: %v", parentID, err)
}
labels = mergeCreateLabels(labels, inherited)
}
return renderDryRun()
}
// Parse every requested dependency edge BEFORE reserving a child ID
// or creating anything so a malformed spec aborts with no burned
// child ID and no orphan issue behind it.
depSpecs, err := parseDepSpecs(deps)
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
waitsForSpec, err := buildWaitsFor(waitsFor, waitsForGate, cmd.Flags().Changed("waits-for-gate"))
if err != nil {
return HandleError("%v", err)
}
createCtx := rootCtx
// The --parent child id is minted by the Lifecycle role, on every
// backend and route: a create with a ParentID and no id of its own is
// <parent>.<n>, minted inside the create's own transaction (conformance
// RunIssueOperationsCreateUnderAParentMintsTheNextChildID, served leg
// included), and the role stages the advanced counter itself. An
// explicit --id never reaches here with a parent (refused above).
if explicitID != "" {
_, err := validation.ValidateIDFormat(explicitID)
if err != nil {
return HandleError("%v", err)
}
// Validate prefix matches database prefix (YAML config takes
// precedence over DB, except under --global — see
// loadEmbeddedIDPrefixes).
dbPrefix, allowedPrefixes := loadEmbeddedIDPrefixes()
if err := validation.ValidateIDPrefixAllowed(explicitID, dbPrefix, allowedPrefixes, forceCreate); err != nil {
return HandleError("%v", err)
}
}
issue := buildCreateIssue(createIssueParams{
ID: explicitID,
Title: title,
Description: description,
Design: design,
AcceptanceCriteria: acceptance,
Notes: notes,
SpecID: specID,
Priority: priority,
IssueType: types.IssueType(issueType).Normalize(),
Assignee: assignee,
ExternalRef: externalRef,
EstimatedMinutes: estimatedMinutes,
Ephemeral: wisp,
NoHistory: noHistory,
StorageClass: storageClass,
Owner: getOwner(),
Labels: labels,
MolType: molType,
WispType: wispType,
EventKind: eventCategory,
Actor: eventActor,
Target: eventTarget,
Payload: eventPayload,
InitialStatus: statusFlag,
DueAt: dueAt,
DeferUntil: deferUntil,
Metadata: metadata,
})
ctx := createCtx
// Resolve partial --deps targets the way `bd dep add` does, so a bare
// slug becomes a qualified id rather than a dangling edge, and an
// unknown target fails closed here instead of reaching the write.
resolvedDepSpecs, resolveErr := resolveDepSpecTargets(ctx, store, depSpecs)
if resolveErr != nil {
return HandleErrorRespectJSON("%v", resolveErr)
}
depSpecs = resolvedDepSpecs
// If a discovered-from dependency is present, inherit source_repo
// from the referenced parent issue. Reuse the already-parsed specs
// (not the raw --deps strings) so this can't drift from parseDepSpec's
// normalization rules.
if dfParent := discoveredFromParentSpec(depSpecs); dfParent != "" {
parentIssue, err := store.GetIssue(ctx, dfParent)
if err == nil && parentIssue.SourceRepo != "" {
issue.SourceRepo = parentIssue.SourceRepo
}
// If error getting parent or parent has no source_repo, continue with default
}
ops, err := writeOps(store)
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
opsCtx, err := issueOpsContext(ctx)
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
// The parent's labels are the role's to inherit, inside the create.
if priorityDefault {
issue.Priority = 0
}
result, err := ops.Create(opsCtx, issueops.CreateRequest{
Actor: currentActor(),
Issue: issue,
ParentID: parentID,
InheritLabelsFromParent: inheritParentLabels,
Dependencies: createDependencyRequests(depSpecs),
WaitsFor: waitsForRequest(waitsForSpec),
ForceIDPrefix: forceCreate,
IDPrefix: createIDPrefixOverride(),
DefaultPriority: priorityDefault,
})
if err != nil {
// RULING R1: an occupied --id is a refusal, not a silent full-row
// upsert reported as success.
if errors.Is(err, storage.ErrAlreadyExists) && explicitID != "" {
return HandleErrorRespectJSON("%s already exists; use bd update, or bd import for upsert semantics", explicitID)
}
return HandleErrorRespectJSON("%v", err)
}
// Every post-write read comes from the facade's result snapshot, never
// from the local struct: the facade clones its request, so the local
// struct still has no ID for an auto-minted create and no persisted
// timestamps. Dependencies and comments are dropped because `bd create`
// has never printed them.
created := result.Issue
created.Dependencies = nil
created.Comments = nil
edges := createDepEdges{parentID: parentID, specs: depSpecs, waitsFor: waitsForSpec}
if edges.empty() {
// Bare create: preserve the embedded-mode follow-up Dolt commit.
// The deps path commits inside its transaction instead.
shouldCommit, err := shouldCommitCreatePostWrites(created, false)
if err != nil {
return HandleError("dolt auto-commit failed: %v", err)
}
if shouldCommit {
commitMsg := fmt.Sprintf("bd: create %s", created.ID)
if err := store.Commit(ctx, commitMsg); err != nil && !isDoltNothingToCommit(err) {
WarnError("failed to commit: %v", err)
}
}
}
if repoPath != "." && targetStore != nil {
if err := commitPendingIfEmbedded(ctx, targetStore, currentActor(), doltAutoCommitParams{
Command: "create",
IssueIDs: []string{created.ID},
}); err != nil {
debug.Logf("warning: failed to commit routed repo: %v", err)
}
}
if remoteCache != nil {
if pushErr := remoteCache.Push(rootCtx, repoPath); pushErr != nil {
return HandleError("failed to push to %s: %v\nThe issue was created locally but not synced to the remote.", repoPath, pushErr)
}
}
if jsonOutput {
if err := outputJSON(created); err != nil {
return err
}
} else if silent {
fmt.Println(created.ID)
} else {
debug.PrintNormal("%s Created issue: %s\n", ui.RenderPass("✓"), formatFeedbackID(created.ID, created.Title))
debug.PrintNormal(" Priority: P%d\n", created.Priority)
debug.PrintNormal(" Status: %s\n", created.Status)
maybeShowTip(store)
}
SetLastTouchedID(created.ID)
return nil
},
}
type createIssueParams struct {
ID string
Title string
Description string
Design string
AcceptanceCriteria string
Notes string
SpecID string
Priority int
IssueType types.IssueType
Assignee string
ExternalRef string
EstimatedMinutes *int
Ephemeral bool
NoHistory bool
StorageClass types.StorageClass
CreatedBy string
Owner string
Labels []string
MolType types.MolType
WispType types.WispType
EventKind string
Actor string
Target string
Payload string
InitialStatus string
DueAt *time.Time
DeferUntil *time.Time
Metadata json.RawMessage
}
// resolveStorageClass resolves the requested storage class at create time
// (Protocol v0.1 C1.3): the explicit --storage-class flag wins; otherwise the
// per-type config default storage-class.<type> applies; otherwise unset.
// The parsed class is returned verbatim, including versioned. The caller must
// normalize versioned to the unset marker (the marker is omitted when
// versioned, C2.4) only AFTER plane-conflict validation, so an explicit durable
// request paired with a wisp-plane flag is rejected rather than silently erased
// into an effective-ephemeral row. Values are validated wherever they came
// from: a bad flag is a usage error, a bad config value is a config bug and
// fails just as loudly.
func resolveStorageClass(explicit string, issueType types.IssueType) (types.StorageClass, error) {
raw := explicit
if raw == "" {
raw = config.GetString("storage-class." + string(issueType))
if raw == "" {
return "", nil
}
}
class, err := types.ParseStorageClass(raw)
if err != nil {
if explicit == "" {
return "", fmt.Errorf("config storage-class.%s: %w", issueType, err)
}
return "", err
}
return class, nil
}
// reconcileStorageClassPlane applies flag-over-config precedence between a
// resolved storage class and the effective wisp plane (Protocol v0.1 §C1.3).
// A wisp-plane record is ephemeral by construction, so a durable class
// (versioned/unversioned) cannot ride on it. explicit reports whether the class
// came from an explicit flag/field rather than a per-type config default:
// - explicit durable class + wisp plane -> conflict=true; the caller rejects
// it so the durable intent is preserved rather than silently collapsed into
// an effective-ephemeral record;
// - config-derived durable class + wisp plane -> cleared, yielding to the
// explicit --ephemeral/--no-history plane.
//
// versioned normalizes to the unset marker (C2.4) only after the check, so the
// durable request survives long enough to be honored, rejected, or yielded. On
// conflict the class is returned verbatim so the caller can name it in the error.
func reconcileStorageClassPlane(class types.StorageClass, explicit, wispPlane bool) (types.StorageClass, bool) {
if class != "" && wispPlane {
if explicit {
return class, true
}
class = "" // config default yields to the explicit wisp-plane flag
}
return class.Normalize(), false
}
// resolveCreateStorageClass is the ONE create-time storage-class decision every
// `bd create` CLI door makes: parse the flag (or fall back to the per-type
// storage-class.<type> config default), route the ephemeral spelling to the wisp
// plane, and reject a durable class that contradicts the plane. Every door goes
// through it so the direct, proxied, and --file routes cannot answer differently;
// graphApplyNodeStorageClass is the per-node mirror, which additionally honors a
// node's own pointer overrides.
//
// flagValue is the raw --storage-class spelling ("" when unset). wisp/noHistory
// are the plane flags as the caller read them; the returned wisp is the plane
// AFTER the ephemeral spelling has been folded in (Protocol v0.1 C1.4). The
// returned class is already normalized (C2.4), so it can go straight onto the
// issue.
func resolveCreateStorageClass(flagValue string, issueType types.IssueType, wisp, noHistory bool) (types.StorageClass, bool, error) {
class, err := resolveStorageClass(flagValue, issueType.Normalize())
if err != nil {
return "", wisp, err
}
// --storage-class ephemeral is the spelled-out spelling of --ephemeral
// (Protocol v0.1 C1.4: the wisp plane is today's ephemeral-class
// implementation). It routes to the wisp path exactly like the flag; the
// --ephemeral/--no-history mutual exclusion still applies.
if class == types.StorageClassEphemeral {
if noHistory {
return "", wisp, errors.New("--storage-class ephemeral and --no-history are mutually exclusive")
}
wisp = true
class = "" // wisp-plane rows derive ephemeral class (C1.2); no marker cell needed
}
// Reconcile the requested durable class with the effective wisp plane
// (flag > config, Protocol v0.1 §C1.3): an explicit --storage-class
// contradicts --ephemeral/--no-history and is rejected, so the durable
// intent is preserved rather than silently collapsed into an
// effective-ephemeral record; a per-type config default yields to the
// explicit flag. versioned normalizes to the unset marker only after the
// check (C2.4).
class, conflict := reconcileStorageClassPlane(class, flagValue != "", wisp || noHistory)
if conflict {
return "", wisp, fmt.Errorf("--storage-class %s conflicts with --ephemeral/--no-history: wisp-plane records are storage class ephemeral", class)
}
return class, wisp, nil
}
func buildCreateIssue(params createIssueParams) *types.Issue {
var externalRefPtr *string
if params.ExternalRef != "" {
externalRefPtr = &params.ExternalRef
}
status := types.StatusOpen
if params.InitialStatus != "" {
status = types.Status(params.InitialStatus)
} else if params.DeferUntil != nil && params.DeferUntil.After(time.Now()) {
status = types.StatusDeferred
}
return &types.Issue{
ID: params.ID,
Title: params.Title,
Description: params.Description,
Design: params.Design,
AcceptanceCriteria: params.AcceptanceCriteria,
Notes: params.Notes,
SpecID: params.SpecID,
Status: status,
Priority: params.Priority,
IssueType: params.IssueType,
Assignee: params.Assignee,
ExternalRef: externalRefPtr,
EstimatedMinutes: params.EstimatedMinutes,
Ephemeral: params.Ephemeral,
NoHistory: params.NoHistory,
StorageClass: params.StorageClass,
CreatedBy: params.CreatedBy,
Owner: params.Owner,
Labels: append([]string(nil), params.Labels...),
MolType: params.MolType,
WispType: params.WispType,
EventKind: params.EventKind,
Actor: params.Actor,
Target: params.Target,
Payload: params.Payload,
DueAt: params.DueAt,
DeferUntil: params.DeferUntil,
Metadata: params.Metadata,
}
}
func mergeCreateLabels(labels, inheritedLabels []string) []string {
merged := make([]string, 0, len(labels)+len(inheritedLabels))
seen := make(map[string]struct{}, len(labels)+len(inheritedLabels))
for _, label := range labels {
if _, ok := seen[label]; ok {
continue
}
seen[label] = struct{}{}
merged = append(merged, label)
}
for _, label := range inheritedLabels {
if _, ok := seen[label]; ok {
continue
}
seen[label] = struct{}{}
merged = append(merged, label)
}
if len(merged) == 0 {
return nil
}
return merged
}
// createIDPrefixOverride is the prefix an explicit --id must match, when the
// WORKSPACE knows better than the database does.
//
// config.yaml's `issue-prefix` wins over the database's, except under --global
// where the shared database is authoritative (GH#4957, selectCreateIDPrefix).
// Only a front door can read config.yaml — a shared server's database knows
// only its own prefix — so both routes resolve it here and hand it to the role
// as CreateRequest.IDPrefix. Empty means "the substrate's prefix is right",
// which is the ordinary case.
func createIDPrefixOverride() string {
if globalFlag {
return ""
}
return overlayYAMLPrefix("")
}
func selectCreateIDPrefix(global bool, yamlPrefix, storePrefix string) string {
if global {
return storePrefix
}
if yamlPrefix != "" {
return yamlPrefix
}
return storePrefix
}
func renderCreateDryRunPreview(issue *types.Issue, labels, deps []string) {
idDisplay := issue.ID
if idDisplay == "" {
idDisplay = "(will be generated)"
}
fmt.Printf("%s [DRY RUN] Would create issue:\n", ui.RenderWarn("⚠"))
fmt.Printf(" ID: %s\n", idDisplay)
fmt.Printf(" Title: %s\n", issue.Title)
fmt.Printf(" Type: %s\n", issue.IssueType)
fmt.Printf(" Priority: P%d\n", issue.Priority)
fmt.Printf(" Status: %s\n", issue.Status)
if issue.Assignee != "" {
fmt.Printf(" Assignee: %s\n", issue.Assignee)
}
if issue.Description != "" {
fmt.Printf(" Description: %s\n", issue.Description)
}
if len(labels) > 0 {
fmt.Printf(" Labels: %s\n", strings.Join(labels, ", "))
}
if len(deps) > 0 {
fmt.Printf(" Dependencies: %s\n", strings.Join(deps, ", "))
}
if issue.EventKind != "" {
fmt.Printf(" Event category: %s\n", issue.EventKind)
}
}
func shouldCommitCreatePostWrites(_ *types.Issue, _ bool) (bool, error) {
return embeddedWritesCommitNow()
}
func createDepsAcceptedTypeList() string {
names := []string{"blocked-by", "depends-on"}
for _, depType := range types.WellKnownDependencyTypes() {
names = append(names, string(depType))
}
sort.Strings(names)
return strings.Join(names, ", ")
}
func init() {
createCmd.Flags().StringP("file", "f", "", "Create one issue per ## heading (### fields attach to that issue); for title plus description-from-file, use --body-file")
createCmd.Flags().String("graph", "", "Create a graph of issues with dependencies from JSON plan file")
createCmd.Flags().String("title", "", "Issue title (alternative to positional argument)")
createCmd.Flags().Bool("silent", false, "Output only the issue ID (for scripting)")
createCmd.Flags().Bool("dry-run", false, "Preview what would be created without actually creating")
registerPriorityFlag(createCmd, strconv.Itoa(issueops.DefaultCreatePriority))
createCmd.Flags().StringP("type", "t", "task", "Issue type (bug|feature|task|epic|chore|decision|spike|story|milestone); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision")
createCmd.Flags().StringP("status", "s", "", "Initial status")
registerCommonIssueFlags(createCmd)
createCmd.Flags().String("spec-id", "", "Link to specification document")
createCmd.Flags().StringSliceP("labels", "l", []string{}, "Labels (comma-separated)")
createCmd.Flags().String("skills", "", "Required skills for this issue")
createCmd.Flags().String("context", "", "Additional context for the issue")
createCmd.Flags().StringSlice("label", []string{}, "Alias for --labels")
_ = createCmd.Flags().MarkHidden("label") // Only fails if flag missing (caught in tests)
createCmd.Flags().String("id", "", "Explicit issue ID (e.g., 'bd-42' for partitioning)")
createCmd.Flags().String("parent", "", "Parent issue ID for hierarchical child (e.g., 'bd-a3f8e9')")
createCmd.Flags().Bool("no-inherit-labels", false, "Don't inherit labels from parent issue")
createCmd.Flags().StringSlice("deps", []string{}, "Dependencies as 'type:id' or bare 'id'. Bare 'id', 'depends-on:id', and 'blocked-by:id' all make THIS issue depend on id; 'blocks:id' reverses direction (id depends on this issue). E.g. 'blocked-by:bd-20,discovered-from:bd-15'")
createCmd.Flags().String("waits-for", "", "Spawner issue ID to wait for (creates waits-for dependency for fanout gate)")
createCmd.Flags().String("waits-for-gate", "all-children", "Gate type: all-children (wait for all) or any-children (wait for first)")
createCmd.Flags().Bool("force", false, "Force creation even if prefix doesn't match database prefix")
createCmd.Flags().String("repo", "", "Target repository for issue (overrides auto-routing)")
createCmd.Flags().IntP("estimate", "e", 0, "Time estimate in minutes (e.g., 60 for 1 hour)")
createCmd.Flags().Bool("ephemeral", false, "Create as ephemeral (short-lived, subject to TTL compaction)")
createCmd.Flags().Bool("no-history", false, "Skip Dolt commit history without making GC-eligible (for permanent agent beads)")
createCmd.Flags().String("storage-class", "", "Storage class: versioned, unversioned, or ephemeral (default: storage-class.<type> config, else versioned)")
createCmd.Flags().String("mol-type", "", "Molecule type: swarm (multi-agent), patrol (recurring ops), work (default)")
createCmd.Flags().String("wisp-type", "", "Wisp type for TTL-based compaction: heartbeat, ping, patrol, gc_report, recovery, error, escalation")
createCmd.Flags().Bool("validate", false, "Validate description contains required sections for issue type")
createCmd.Flags().Bool("allow-empty-description", false, "Allow empty description input from stdin or file")
// Event-specific flags (only valid when --type=event)
createCmd.Flags().String("event-category", "", "Event category (e.g., patrol.muted, agent.started) (requires --type=event)")
createCmd.Flags().String("event-actor", "", "Entity URI who caused this event (requires --type=event)")
createCmd.Flags().String("event-target", "", "Entity URI or bead ID affected (requires --type=event)")
createCmd.Flags().String("event-payload", "", "Event-specific JSON data (requires --type=event)")
// Time-based scheduling flags (GH#820)
// Examples:
// --due=+6h Due in 6 hours
// --due=tomorrow Due tomorrow
// --due="next monday" Due next Monday
// --due=2025-01-15 Due on specific date
// --defer=+1h Hidden from bd ready for 1 hour
// --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 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)
}
// handleCreateTargetStoreError preserves the existing text path for ordinary
// store failures while rendering capability refusals as typed JSON when asked.
func handleCreateTargetStoreError(err error, targetPath, fallbackFormat string) error {
var capErr *ProxyCapabilityError
if !errors.As(err, &capErr) {
return HandleError(fallbackFormat, err)
}
withContext := *capErr
withContext.Message = fmt.Sprintf("failed to open create target %q: %s", targetPath, capErr.Message)
if capErr.Code == "proxy.store.unrouted" {
withContext.Message = fmt.Sprintf("create target %q is a proxied-server workspace; bd cannot open it as a direct store", targetPath)
}
return HandleProxyCapabilityError(&withContext)
}
// formatTimeForRPC converts a *time.Time to RFC3339 string for RPC calls.
// Returns empty string if t is nil, to distinguish "not set" from "set to zero".
func formatTimeForRPC(t *time.Time) string {
if t == nil {
return ""
}
return t.Format(time.RFC3339)
}
// openDryRunTargetStore opens the store a `create --dry-run --repo <other>`
// resolves --parent against. It is read-only on BOTH paths and must stay that
// way: newDoltStoreFromConfig runs schema initialization on whatever it opens
// and can rename a legacy hyphenated database and rewrite the target's
// metadata.json on the way (GH#3231), so using it here would have a dry-run
// mutate a repository the user only named as a lookup target — the same
// migrate-at-open trap this preview policy exists to close, one repo over.
// newPreviewStoreFromConfig is the non-mutating factory for a foreign
// project (bd-6dnrw.32), relaxed for previews exactly as the root pre-run
// relaxes the command's own store.
func openDryRunTargetStore(ctx context.Context, repoPath string) (storage.DoltStorage, error) {
if remotecache.IsRemoteURL(repoPath) {
cache, err := remotecache.DefaultCache()
if err != nil {
return nil, fmt.Errorf("failed to initialize remote cache: %w", err)
}
// The dry-run parent lookup only reads from this cached remote store.
// Do not add writes here; dry-runs must not mutate cached remotes.
store, err := cache.OpenStore(ctx, repoPath, newPreviewStoreFromConfig)
if err != nil {
return nil, fmt.Errorf("dry-run parent lookup requires an existing cached remote store for %s: %w", repoPath, err)
}
return store, nil
}
targetPath := routing.ExpandPath(repoPath)
beadsDir := filepath.Join(targetPath, ".beads")
metadataPath := filepath.Join(beadsDir, "metadata.json")
if _, err := os.Stat(metadataPath); err != nil {
if os.IsNotExist(err) {
return nil, fmt.Errorf("target repo %s is not initialized; refusing to initialize it during dry-run", targetPath)
}
return nil, fmt.Errorf("failed to inspect target repo %s: %w", targetPath, err)
}
store, err := newPreviewStoreFromConfig(ctx, beadsDir)
if err != nil {
return nil, fmt.Errorf("failed to open target store for dry-run: %w", err)
}
return store, nil
}
// isAmbiguousRepoTarget reports whether an explicit --repo value is a
// bare/relative filesystem path (not absolute, not "~/"-prefixed). Such a
// value silently resolves against the current working directory (see
// routing.ExpandPath) rather than failing, so a misresolved value (e.g. a
// typo) previously wrote a bead into a brand-new, disconnected database
// instead of erroring (bd-8d3f).
func isAmbiguousRepoTarget(repoFlagChanged bool, repoOverride string) bool {
return repoFlagChanged && !filepath.IsAbs(repoOverride) && !strings.HasPrefix(repoOverride, "~/")
}
// ensureBeadsDirForPath ensures a beads directory exists at the target path.
// If the .beads directory doesn't exist, it creates it and initializes with
// the same prefix as the source store (T010, T012: prefix inheritance).
//
// When allowCreate is false, a target with no existing workspace is refused
// instead of fabricated — see isAmbiguousRepoTarget.
func ensureBeadsDirForPath(ctx context.Context, targetPath string, sourceStore storage.DoltStorage, allowCreate bool) error {
beadsDir := filepath.Join(targetPath, ".beads")
metadataPath := filepath.Join(beadsDir, "metadata.json")
// Check if beads directory already exists with a Dolt database.
// metadata.json is the canonical marker for an initialized beads dir.
if _, err := os.Stat(metadataPath); err == nil {
return nil
}
if !allowCreate {
return fmt.Errorf("no beads workspace found at %s and --repo's value is a relative/bare path, so it won't be auto-created here (this is likely not the target you intended). Pass an absolute or \"~/\"-prefixed --repo path to an existing workspace instead", targetPath)
}
// Create .beads directory
if err := os.MkdirAll(beadsDir, 0750); err != nil {
return fmt.Errorf("cannot create .beads directory: %w", err)
}
// Initialize database via NewFromConfigWithOptions to respect Dolt config.
// Set the prefix if source store has one (T012: prefix inheritance).
if sourceStore != nil {
sourcePrefix, err := sourceStore.GetConfig(ctx, "issue_prefix")
if err == nil && sourcePrefix != "" {
// Sanitize prefix for SQL database name (same as bd init).
dbName := strings.ReplaceAll(sourcePrefix, "-", "_")
// Open target store temporarily to set prefix.
// Use newDoltStore with explicit config since the target .beads
// directory was just created and has no metadata.json yet.
tempStore, err := newDoltStore(ctx, &dolt.Config{
BeadsDir: beadsDir,
Database: dbName,
CreateIfMissing: true,
})
if err != nil {
return fmt.Errorf("failed to initialize target database: %w", err)
}
if err := tempStore.SetConfig(ctx, "issue_prefix", sourcePrefix); err != nil {
_ = tempStore.Close() // Best effort cleanup on error path
return fmt.Errorf("failed to set prefix in target store: %w", err)
}
if err := tempStore.Close(); err != nil {
return fmt.Errorf("failed to close target store: %w", err)
}
// Write metadata.json so newDoltStoreFromConfig can find the
// correct database name on subsequent opens (GH#2988).
cfg := configfile.DefaultConfig()
cfg.Backend = configfile.BackendDolt
cfg.DoltDatabase = dbName
cfg.DoltMode = configfile.DoltModeEmbedded
cfg.ProjectID = configfile.GenerateProjectID()
if err := cfg.Save(beadsDir); err != nil {
return fmt.Errorf("failed to write metadata.json: %w", err)
}
}
}
return nil
}