beads/cmd/bd/create.go
Julian Knutsen bc1cd64c78
fix(cli): refuse graph workspaces marked by graph-preview-format (#7722)
The graph-mode fence decides a workspace's format from graph_mode in its
metadata alone. Graph-preview builds also write a
.beads/graph-preview-format marker before metadata.json (donnabox fork
commit deea8d57df, Donna Box), so that an interrupted or metadata-lost
graph workspace stays fenced. bd ignored the marker. When a bd that
predates graph_mode had rewritten metadata.json without the field, bd
opened the graph database by its recorded name and `bd list` ran Issue
schema initialization against it. When metadata.json was never written
or was lost, bd fell back to the default database name and created an
Issue database inside the graph workspace, and `bd init` initialized an
Issue workspace there.

checkWorkspaceFormat now also refuses a beadsDir that holds anything at
graph-preview-format, whatever its content and whatever the metadata
says (absent, stripped, or an explicit "dependency"). The graph_mode
check still runs first, so a normal graph workspace is still reported
by its graph_mode. The refusal is the same typed error with its own
message and a hint to restore metadata.json, so every call site, the
--json rendering and exit code 16 (ExitUnsupportedWorkspaceFormat) are
unchanged. An empty beadsDir never probes the working directory.

loadAndCheckWorkspaceFormat reads the metadata with LoadForDiscovery
and refuses metadata that cannot be parsed beside the marker as the
marker's format: the marker alone declares it. Command admission
(guardLegacyUpgradeWorkspaceForInit) uses it, and
checkDiscoveredWorkspaceFormat now delegates to it, so the paths that
check before a migrating configfile.Load (the four store factories,
create --repo's ensureBeadsDirForPath and dry-run target open, the bd
dolt loaders, bootstrap's undiscovered walk) refuse a marked workspace
too, with or without readable metadata. Other metadata load failures
are still left to the caller's own load, so a malformed legacy
config.json without the marker keeps create --repo's
auto-initialization.

bootstrap's ancestor walk (findParentConfig) refuses an ancestor that
holds the marker without metadata it can read, as it refuses one whose
metadata declares graph_mode. It used to skip a marker-only ancestor
and take a more distant workspace's metadata or the defaults, and to
report a marked ancestor with unparseable metadata as a load failure
(exit 1). With the check in checkWorkspaceFormat, bootstrap in a .beads
holding only the marker refuses it (exit 16) instead of reporting no
workspace.

validateConfiguredBackend returns early for nil metadata, so its
backstop covers the marker only when metadata was loaded; every caller
runs admission or checkDiscoveredWorkspaceFormat on the same beadsDir
first, and its comment now says so.

Tests: guard unit tests for marker-only, metadata lost, stripped
(metadata.json and legacy config.json), server, explicit dependency,
unparseable metadata, marker over a legacy Dolt root, and arbitrary
marker content; the four store factories (cgo, and the CGO_ENABLED=0
copies goreleaser ships) with stripped, missing and, for cgo,
unparseable metadata beside the marker; findParentConfig with a marked
ancestor below an ordinary workspace; the exit-code mapping;
ensureBeadsDirForPath with a malformed config.json with and without the
marker; and the subprocess e2e matrices (in-workspace commands, plain
`bd init`, and the outside entry points: create --repo, create
--dry-run, --db, BEADS_DB, init --proxied-server, bootstrap below it)
extended with four marker fixtures that must exit 16 with the marker
refusal and leave .beads byte-identical, while store-less commands
still run. The e2e subprocess timeout goes from 10s to 20s: refused
runs finish in well under a second, but an unrefused one creates or
opens a database and can approach 10s under load, so without the
fence the rows fail on their assertion rather than on the timeout.

Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-20 07:25:38 +00:00

1151 lines
46 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 == "" {
// The preview opens no target, but it refuses a local one in a
// format this build cannot open, as the create it previews would.
if err := checkRepoTargetFormat(repoPath); err != nil {
return handleWorkspaceGuardError(err)
}
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 {
if isUnsupportedWorkspaceFormat(err) {
return handleWorkspaceGuardError(err)
}
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,
// and a target in a format this build cannot open as the workspace refusal.
func handleCreateTargetStoreError(err error, targetPath, fallbackFormat string) error {
if isUnsupportedWorkspaceFormat(err) {
return handleWorkspaceGuardError(err)
}
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")
// A target in a format this build cannot open is refused as that, even
// one marked only by a legacy config.json, which the check below would
// report as not initialized.
if err := checkDiscoveredWorkspaceFormat(beadsDir); err != nil {
return nil, err
}
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
}
// checkRepoTargetFormat refuses a local create target in a format this build
// cannot open, reading its metadata without opening or migrating it. The
// command's own workspace (".") has passed admission already, and a remote
// target has no local metadata to read, so both pass.
func checkRepoTargetFormat(repoPath string) error {
if repoPath == "." || remotecache.IsRemoteURL(repoPath) {
return nil
}
return checkDiscoveredWorkspaceFormat(filepath.Join(routing.ExpandPath(repoPath), ".beads"))
}
// 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")
// A target in a format this build cannot open is refused before anything
// below: one marked only by a legacy config.json or by the graph format
// marker file has no metadata.json, so it would otherwise be initialized
// here, with an Issue database and a metadata.json written beside it.
if err := checkDiscoveredWorkspaceFormat(beadsDir); err != nil {
return err
}
// 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
}