Commit graph

13 commits

Author SHA1 Message Date
postoso
4c4be78b5c
fix(scripts): make check-doc-flags portable to BSD grep and fail loud on grep errors (#6026)
Co-authored-by: postoso <postoso@users.noreply.github.com>
2026-09-02 17:25:53 -07:00
Steve Yegge
ff1d36fc1f sync: name a resolve command on conflict, fix -q asymmetry, close doc-flags hole, cover runSyncCommand (wy-j6q2z)
Bundled MINOR/NOTE polish from the wy-jpd3.4 adversarial pass:

1. syncConflictMessage now names `bd conflicts list`/`show`/`resolve` on
   every conflict halt instead of only on the generic error path.
2. check-doc-flags.sh Check 1 no longer excludes the "removed in v0.51"
   wording, closing the one phrasing a stale doc could use undetected.
3. sync_test.go gains runSyncCommand-level coverage via a fake
   storage.DoltStorage: the no-remote exit-0 gate, the noPush ->
   PushSkipped correction, --attempts 0 rejection, the JSON envelope per
   status, and exitError -> process-exit mapping.
4. TestIsNoRemoteConfiguredErrSupersetOfRemoteNotFound no longer asserts a
   condition that was unsatisfiable by construction; it now checks the
   widening is real in both directions.
6. `bd sync -q` now silences the success-path prints (printNoRemoteGuidance,
   "Sync complete.") that ops.progress was already gated on, so quiet means
   quiet on a solo rig too. Conflict/retry reports stay unsilenced -q is
   "errors only".
7. A pull error unrelated to a live conflict (e.g. a transport failure
   racing another writer's already-conflicted state on a shared
   sql-server) is no longer silently discarded when the run reports the
   conflict: syncOutcome.DiscardedPullError carries it through to the
   halt message.

Finding 5 (sync's default-remote path never adopts a git origin as Dolt
remote, unlike `bd dolt push`) is confirmed real by code reading but left
unfixed here; filed as wy-gpzg7.

GATE-RECEIPT: go test ./cmd/bd/ -count=1 -timeout 40m rc=0
2026-07-25 19:28:31 -07:00
Steve Yegge
f94ea5bfe5 feat(sync): bd sync — the federation loop as one verb (wy-jpd3.4)
Every multi-machine beads deployment hand-rolls the same shell loop around
pull/push; this ships it as `bd sync [--remote <name>] [--attempts N]`.

Three properties are the point of the verb, and each is a lesson paid for by
the reference deployment (a two-machine federation on a 60s timer):

- Conflicts are detected POSITIVELY, from the merge's own captured conflict
  rows and from dolt_conflicts — never inferred from the pull's exit status.
  A pull fails for reasons that are not conflicts, and a settled merge that IS
  conflicted aborts and leaves dolt_conflicts empty, so an exit-status guess
  both invents phantom conflicts and misses real ones. A pre-flight check also
  halts on conflicts left live by an earlier halted sync, which Dolt otherwise
  refuses to merge over with an opaque transport error.
- A conflict sync cannot settle is NEVER resolved by picking a side: it halts
  before recomputing or pushing, with no --strategy-style override. A timer
  that silently picks a side loses work on a schedule. The halt message
  reports whether the conflict rows are live or were aborted away, read from
  WHICH detection source fired rather than assumed — the SQL pull route aborts
  and restores the working set, the CLI/git-protocol route deliberately leaves
  the rows live, and an operator told the wrong one looks in the wrong place.
- The is_blocked recompute runs unconditionally, on every attempt. That is
  deliberate and load-bearing: RecomputeAllBlocked is specifically the repair
  that does NOT depend on a merge advancing HEAD (bd-6dnrw.37), so it is what
  recovers a column left stale by a conflicted pull an operator resolved by
  hand — a state this verb manufactures itself by exiting 2. Gating it on "did
  this tick merge anything" re-imposes the condition it exists to escape, and
  from then on no tick merges anything, so the repair would never run again
  while every tick reported success. HEAD is the wrong instrument for that
  question anyway: the pull's own pre-merge auto-commit (GH#2474) moves it for
  purely local dirty state, and an auto-resolved merge can land in the working
  set without moving it at all (bd-6dnrw.39).

Exit codes are the machine contract so a timer can branch without parsing
output: 0 synced, 1 error, 2 merge conflict (halted, nothing pushed), 3
push-race retries exhausted (transient). --json reports the same outcome.

Push-race classification is deliberately narrow — race signatures (behind /
non-fast-forward / a lost --force-with-lease: stale info, fetch first, "contains
work that you do not have"), not the word "rejected". A protected branch or a
declining pre-receive hook also rejects, permanently; treating that as a race
burns the whole attempt budget every tick and reports exit 3 ("retry next tick")
forever instead of surfacing the failure.

Also: hasNoRemoteConfigured split out of isConfirmedNoRemote so sync can reuse
the structural no-remote proof with its own (broader) error hint without
loosening it — a solo rig must not fail every tick, but a typoed or broken
remote must still exit non-zero. The command doc and the doc-flags gate are
updated: `bd sync` is live again, so the stale reference to hunt is docs still
calling it removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-24 18:15:13 -07:00
Chris Sells
d2f87d50de
docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876)
* docs(pipeline): pin the generated CLI docs to the released bd; repair main's CLI reference

The #4874 squash-merge raced the docs-autofix bot: the bot had pushed a
regeneration from main's source onto the PR branch, so the squash landed a
contradictory mix — the release-aligned hand-written docs plus a CLI
reference re-documenting unreleased commands and flags, with docs.json
referencing four pages (heartbeat, migrate-personal, reclaim, unclaim)
whose files do not exist. That broken nav fails the docsync guard on main
and on every branch cut from it. This restores the intended end state of
#4874 and lands the pin that prevents the race from recurring.

- Regenerate the CLI reference from a bd built from the v1.1.0 tag (CI's
  canonical pure-Go build), removing the unreleased commands/flags and
  fixing the dangling nav entries.
- docs/cli-docs.pin names the release tag; scripts/resolve-docs-bd.sh
  builds and caches a canonical pure-Go bd from that tag, fetching the tag
  first in shallow CI checkouts.
- generate-cli-docs.sh, check-doc-flags.sh, and check-cli-docs-drift.sh
  resolve bd through the pin and ignore a supplied binary while pinned
  (BD_DOCS_IGNORE_PIN=1 bypasses), so the drift gates and the autofix bot
  now enforce docs-match-release instead of docs-match-main.
- tools/docsmint detects the pre-overhaul Docusaurus staging layout that
  bd <= v1.1.0 emits and converts it to the generic form before its normal
  Mintlify transform (tested); removable once the pin reaches a release
  whose emitter writes build/cli-docs.
- check-doc-flags.sh: run without timeout(1) on macOS instead of failing
  Check 4.
- Decision record: engdocs/decisions/2026-07-17-docs-release-pin.md; the
  beads-docs skill §8 updated to match.

* lint: annotate gosec G705 false positive in the docsmint legacy bridge

Same class as the existing nav-splice annotation: a developer tool writing
repo Markdown, not a web-output sink.
2026-07-17 18:03:28 -07:00
Chris Sells
52aea3f7e3 docs: go all-in on Mintlify — delete the Docusaurus site and its machinery
Per the decision record: no parallel run and no cutover PR. Removes
website/ (including the four versioned doc snapshots — current-only
versioning; snapshots remain in git history), deploy-docs.yml,
generate-llms-full.sh (Mintlify serves llms.txt natively), the ci-website
package gate (Makefile target, scripts/ci/website.sh, the package-website
jobs and their aggregate-gate entries in pr.yml/main.yml/release.yml, the
ci-measurements suite, detect-package-gates wiring), and the release-time
docs snapshot flow (snapshot-release-docs.sh, check-docs-version.sh, their
call sites in update-versions.sh/check-versions.sh, RELEASING.md section
rewritten for the Mintlify reality).

Drift machinery now covers exactly the Mintlify artifacts:
check-cli-docs-drift.sh pathspecs/fingerprint, docs-autofix-push.sh
allowlist, and check-doc-flags.sh scans drop the website/llms paths. The
beads-docs skill's generated-content and verification sections updated to
the bd-generic + docsmint pipeline.

NOTE for merge time: if branch protection requires the 'Package Gate
(website)' check by name (rather than the aggregate gate), drop it from
the required checks or PRs will wait forever.

Gates: docsync PASS, generate-cli-docs.sh --check PASS, freshness PASS.
2026-07-12 10:37:17 -07:00
Chris Sells
4ea6fa3ac0 docs(emitter): emit Mintlify CLI reference and generated docs.json nav
bd help --docs-root now additionally writes docs/cli-reference/ in Mintlify
form (frontmatter title as H1, extensionless root-relative links, JSX
auto-generated markers since Mintlify parses .md through MDX) and rewrites
the CLI Reference pages array inside docs/docs.json via a textual splice
that leaves the rest of the file byte-identical — the ~113 nav entries are
never hand-maintained. The Docusaurus outputs (docs/CLI_REFERENCE.md,
website/docs/cli-reference/, versioned snapshots) are unchanged.

generate-cli-docs.sh --check seeds docs/docs.json and docs/cli-reference/
into its scratch root and diffs both; check-cli-docs-drift.sh adds them to
GEN_PATHSPECS and the regeneration fingerprint; docs-autofix-push.sh
allowlists the new generated paths; check-doc-flags.sh scans the new
docs/ subdirectories and requires command coverage in docs/cli-reference/.

Includes the initial docs/docs.json scaffold (nav mirrors the Docusaurus
sidebar IA) and the generated docs/cli-reference/ pages.

TDD: new emitter behavior covered in cmd/bd/help_all_test.go
(Mintlify page format, nav splice correctness + idempotence, bare-root
generation without docs.json).
2026-07-12 10:37:07 -07:00
matt wilkie
dfa8ea4813
fix(docgen): generate CLI docs in one process (#4474)
Add a bulk help docs writer that emits the root CLI reference and website command pages from a single Cobra walk. Update the shell generator to call that mode, preserve the pure-Go docs binary guard, and refresh historical versioned CLI docs only when release snapshotting requests a specific version.

Agent-Signature: codex-gpt-5.5-medium on behalf of matt wilkie
2026-06-22 18:25:58 -07:00
matt wilkie
1de37278ad ci(docs): blame-scoped CLI docs freshness gate + fix patch artifact (#4301)
The doc freshness gate regenerated all generated doc artifacts and failed
the PR on any diff, even drift the contributor did not cause: staleness
inherited from the base branch, or local regeneration environments that
do not match CI's canonical build. Contributors ended up futzing with
regeneration loops for docs unrelated to their change (#4300, #4301).

New scripts/check-cli-docs-drift.sh keeps the strict regenerate-and-diff
probe as the fast path, but on failure in a PR it attributes the drift
before failing anyone: it regenerates the artifacts at HEAD and at the
merge-base in scratch worktrees, each with the canonical pinned build
(CGO_ENABLED=0 -tags gms_pure_go). If the PR neither changed the
regenerated CLI surface nor touched generated files, the drift is
inherited: warn and pass. Contributors only own docs for code they
actually touched.

When the drift IS attributable, CI now writes the exact regenerated fix
as a patch and uploads it as the cli-docs-freshness-patch artifact, so
the fix never depends on the contributor's local environment: download,
git apply, push.

Strict behavior is preserved wherever there is no PR base ref: pushes to
main, releases, and plain local runs. The pr-policy wrapper picks up the
same logic through check-doc-flags.sh.

Refs #4301, #4203. Complements #4312 (docgen binary pinning).

Agent-Signature: claude-unknown-model-high on behalf of matt wilkie
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-14 23:40:17 -07:00
matt wilkie
ade96333fd
docs: guard plugin CLI reference pointer (#4177)
Record the plugin CLI reference as a pointer-only resource and extend the doc freshness check so it fails if that resource drifts back into a copied command reference.

_codex-gpt-5.5-medium on behalf of CI Bot_
Co-authored-by: CI Bot <ci@beads.test>
2026-05-26 15:31:24 -07:00
matt wilkie
c97c416242
docs: publish v1.0.4 docs snapshot (#3845)
* docs: publish v1.0.4 docs snapshot

* release: guard docs version snapshots
2026-05-09 14:42:25 -07:00
matt wilkie
b2a4d1d04a
docs: generate CLI reference from live help (#3704)
* docs: generate CLI reference from live help

* docs(cli): move bd version stamp from per-command pages to index only

Drops the `(bd version X.Y.Z)` suffix from the auto-generated header on
every per-command CLI reference page (writeSingleCommandDoc) and the
docs/CLI_REFERENCE.md preamble (writeAllHelp). The version label now
lives only on the index page emitted by scripts/generate-cli-docs.sh:

- Dev tree (website/docs/cli-reference/index.md, docs/CLI_REFERENCE.md):
  labelled "Latest"
- Versioned snapshots (website/versioned_docs/version-X.Y.Z/...):
  labelled with the explicit semver tag parsed from the directory name

This eliminates the 100+-file no-signal diff a release version bump
otherwise produces, restoring the "regen as a separate small commit"
workflow PR #3704 enables. After this change a version bump alone
yields zero diff on the dev tree; only the new versioned snapshot
created at release-cut time carries the new tag. No datestamps are
introduced anywhere — scripts/generate-cli-docs.sh --check remains
deterministic across CI runs.

Refs: mybd-afb, PR #3704

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 19:43:49 -07:00
Eugene Brevdo
43715adde7 Add shared Beads plugin package 2026-05-02 10:59:40 -07:00
Amp
a333dcaa75 fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522)
Systematic cleanup of stale documentation references left over from the
Dolt migration:

- Replace all 'bd sync' → 'bd dolt push' / 'bd dolt pull' across 40+ files
- Replace all 'bd import' → 'bd init --from-jsonl' or remove
- Replace 'bd init --branch' → note about refs/dolt/data separation
- Fix AGENT_INSTRUCTIONS.md (highest impact: agents read this directly)
- Fix npm-package, claude-plugin, integrations, examples, website docs

Add scripts/check-doc-flags.sh to catch stale doc references:
- Checks for removed commands (bd sync, bd import)
- Checks for removed flags (bd init --branch)
- Warns on legacy SQLite/beads.db references
- Compares CLI_REFERENCE.md against bd help --all

Add CI job (check-doc-flags) and Makefile target (check-docs) to gate
PRs against doc freshness.

Prior art: feat/help-doc-generator branch has bd help --doc/--list for
generating docs FROM CLI output. This script validates docs AGAINST CLI
output — complementary approaches.

Amp-Thread-ID: https://ampcode.com/threads/T-019cde77-0722-7353-b63a-1779a5773ca6
Co-authored-by: Amp <amp@ampcode.com>
2026-03-11 13:25:40 -07:00