Relocate contributor- and maintainer-facing material out of docs/ so the directory can become the user-facing Mintlify site. Moves preserve subpaths (adr/, design/, staged-for-removal/ intact). messaging.md, UI_PHILOSOPHY.md, and AGENT_SIGNING.md move per their DOC_INVENTORY dispositions (design doc, design philosophy, maintainer convention). Inbound links updated repo-wide: root guides, CONTRIBUTING, AGENTS, workflows, lint config, scripts (check-doc-freshness now resolves the inventory at engdocs/DOC_INVENTORY.md), Go comments, and the synced website metadata page (regenerated via sync-website-docs.sh + generate-llms-full.sh). The emitted help text in cmd/bd/init_safety_help.go still references docs/adr/0002-init-safety-invariants.md; changing it would change bd's runtime output, which is out of scope for this branch (flagged in the PR).
100 lines
3.3 KiB
Go
100 lines
3.3 KiB
Go
package main
|
|
|
|
import (
|
|
"fmt"
|
|
|
|
"github.com/spf13/cobra"
|
|
|
|
"github.com/steveyegge/beads/internal/metrics"
|
|
)
|
|
|
|
// initSafetyHelpCmd documents the init flag surface and the destroy-token
|
|
// format. Its contents are the authoritative runtime reference for the
|
|
// error-message-no-echo invariant: refusal texts point here rather than
|
|
// constructing copy-pasteable destructive invocations. See
|
|
// engdocs/adr/0002-init-safety-invariants.md.
|
|
var initSafetyHelpCmd = &cobra.Command{
|
|
Use: "init-safety",
|
|
Short: "Explain bd init flag semantics and the destroy-token format",
|
|
Long: `bd init flag safety contract.
|
|
|
|
Every bd init invocation resolves project_id from exactly one explicitly
|
|
named source (local reinit, remote adoption, or a fresh mint). When the
|
|
source is ambiguous, bd init refuses.
|
|
|
|
FLAG SURFACE
|
|
|
|
bd init Mint a new identity. Bootstraps from
|
|
origin if it has refs/dolt/data.
|
|
|
|
bd init --reinit-local Re-initialize local .beads/ over existing
|
|
local data. Does NOT authorize discarding
|
|
remote history. If origin has Dolt data
|
|
this will refuse — pair with
|
|
--discard-remote to override.
|
|
|
|
bd init --reinit-local \ Discard the remote's Dolt history and
|
|
--discard-remote replace it with the local reinit. First
|
|
bd dolt push after this will be a
|
|
history-replacing force-push.
|
|
|
|
bd init --force Deprecated alias for --reinit-local.
|
|
Kept working for ≥2 releases.
|
|
|
|
bd init --from-jsonl Import from configured import.path. If
|
|
origin has Dolt data, this refuses unless
|
|
--discard-remote authorizes replacing that
|
|
remote history.
|
|
|
|
ADOPTING A REMOTE
|
|
|
|
If you want to use the remote's existing history, use:
|
|
|
|
bd bootstrap
|
|
|
|
bd init will automatically suggest this when a remote is detected.
|
|
|
|
DESTROY-TOKEN (non-interactive only)
|
|
|
|
When running with no TTY (CI, agents, piped input), --discard-remote
|
|
requires an explicit --destroy-token value. The token format is:
|
|
|
|
DESTROY-<issue-prefix>
|
|
|
|
For example, if your issue prefix is "bd", the token is "DESTROY-bd":
|
|
|
|
bd init --reinit-local --discard-remote --destroy-token=DESTROY-bd
|
|
|
|
In interactive (TTY) mode you confirm via a typed prompt instead. The
|
|
token is not echoed by bd's runtime error messages — this is a
|
|
deliberate guard against pattern-matched one-liners (see
|
|
docs/adr/0002-init-safety-invariants.md).
|
|
|
|
EXIT CODES
|
|
|
|
10 refused: remote has Dolt history and you selected local history
|
|
without --discard-remote
|
|
11 refused: existing local data and you declined the destroy confirm
|
|
12 refused: --discard-remote passed without a valid --destroy-token
|
|
(non-interactive mode)
|
|
|
|
RECOVERY
|
|
|
|
If you hit a refusal, see docs/RECOVERY.md for step-by-step recovery
|
|
playbooks for each exit code.
|
|
`,
|
|
Run: func(cmd *cobra.Command, _ []string) {
|
|
evt := metrics.NewCommandEvent("init-safety")
|
|
defer func() {
|
|
if c := metrics.Global(); c != nil {
|
|
c.CloseEventAndAdd(evt)
|
|
}
|
|
}()
|
|
|
|
fmt.Print(cmd.Long)
|
|
},
|
|
}
|
|
|
|
func init() {
|
|
rootCmd.AddCommand(initSafetyHelpCmd)
|
|
}
|