@snarkipus/opencode-beads 0.9.2 → 0.9.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +39 -76
- package/package.json +1 -1
- package/vendor/commands/audit.md +1 -2
- package/vendor/commands/blocked.md +1 -1
- package/vendor/commands/close.md +1 -1
- package/vendor/commands/comments.md +1 -1
- package/vendor/commands/compact.md +1 -1
- package/vendor/commands/create.md +1 -1
- package/vendor/commands/decision.md +2 -2
- package/vendor/commands/delete.md +1 -1
- package/vendor/commands/dep.md +1 -1
- package/vendor/commands/epic.md +4 -1
- package/vendor/commands/export.md +2 -2
- package/vendor/commands/import.md +75 -9
- package/vendor/commands/init.md +1 -1
- package/vendor/commands/label.md +1 -1
- package/vendor/commands/list.md +1 -1
- package/vendor/commands/quickstart.md +2 -2
- package/vendor/commands/rename-prefix.md +1 -2
- package/vendor/commands/reopen.md +1 -1
- package/vendor/commands/restore.md +1 -1
- package/vendor/commands/search.md +1 -1
- package/vendor/commands/show.md +1 -1
- package/vendor/commands/sync.md +101 -9
- package/vendor/commands/update.md +1 -1
- package/vendor/manifest.json +47 -47
package/README.md
CHANGED
|
@@ -2,124 +2,87 @@
|
|
|
2
2
|
|
|
3
3
|
[Beads](https://github.com/gastownhall/beads) issue tracker integration for [OpenCode](https://opencode.ai).
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
`@snarkipus/opencode-beads` is a maintained OpenCode adapter that provides full `bd prime` context injection, vendored `/beads:*` workflows, and a bounded task agent. It does not replace Beads: the installed `bd` CLI remains authoritative for issues, project initialization, skills, migrations, backups, and Dolt synchronization.
|
|
6
6
|
|
|
7
7
|
The project originated as [Josh Thomas's `opencode-beads`](https://github.com/joshuadavidthomas/opencode-beads) and continues under the MIT license. This fork is maintained by Matt Jackson and tracks reviewed upstream Beads releases while adapting their plugin artifacts to OpenCode's CLI-only execution model.
|
|
8
8
|
|
|
9
|
-
##
|
|
10
|
-
|
|
11
|
-
Install the `bd` CLI once on the host:
|
|
12
|
-
|
|
13
|
-
```bash
|
|
14
|
-
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
|
|
15
|
-
```
|
|
9
|
+
## Design
|
|
16
10
|
|
|
17
|
-
|
|
11
|
+
The plugin's primary design is **context-preserving atomic delegation**:
|
|
18
12
|
|
|
19
|
-
|
|
13
|
+
- The primary OpenCode thread retains planning context, decisions, and control.
|
|
14
|
+
- `beads-task-agent` processes exactly one Bead per invocation, then closes, blocks, or returns.
|
|
15
|
+
- Without an external orchestrator, this intentionally trades broad autonomy for Bead atomicity and context preservation.
|
|
16
|
+
- An orchestrator may repeat `select → delegate one Bead → verify → select next`, but should not weaken the worker boundary.
|
|
20
17
|
|
|
21
|
-
|
|
22
|
-
{
|
|
23
|
-
"plugin": ["@snarkipus/opencode-beads@0.9.2"]
|
|
24
|
-
}
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
Restart OpenCode. OpenCode caches pinned plugins, so update this version explicitly when upgrading. An unpinned `@snarkipus/opencode-beads` entry follows npm updates on startup but is less reproducible.
|
|
18
|
+
## Installation
|
|
28
19
|
|
|
29
|
-
|
|
20
|
+
Install the [`bd` CLI](https://github.com/gastownhall/beads/blob/main/docs/getting-started/installation.md) once on the host, then initialize each project:
|
|
30
21
|
|
|
31
22
|
```bash
|
|
32
|
-
git init
|
|
23
|
+
git init # only when the directory is not already a Git worktree
|
|
33
24
|
bd init
|
|
34
25
|
```
|
|
35
26
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
### Upgrading from 0.8.0
|
|
27
|
+
`bd init` owns project initialization and creates the canonical shared Beads skill at `.agents/skills/beads`, which OpenCode discovers. This plugin has no separate skill lifecycle and does not write startup files.
|
|
39
28
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
bunx @snarkipus/opencode-beads@0.8.0 remove
|
|
44
|
-
```
|
|
29
|
+
Add the version-pinned plugin to `~/.config/opencode/opencode.json`:
|
|
45
30
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
```bash
|
|
51
|
-
scratch="$(mktemp -d)"
|
|
52
|
-
git -C "$scratch" init
|
|
53
|
-
(cd "$scratch" && bd init)
|
|
54
|
-
mkdir -p .agents/skills
|
|
55
|
-
cp -R "$scratch/.agents/skills/beads" .agents/skills/beads
|
|
56
|
-
rm -rf "$scratch"
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"plugin": ["@snarkipus/opencode-beads@0.9.3"]
|
|
34
|
+
}
|
|
57
35
|
```
|
|
58
36
|
|
|
59
|
-
|
|
37
|
+
Restart OpenCode. Update the pin explicitly when upgrading; an unpinned package entry is less reproducible.
|
|
60
38
|
|
|
61
|
-
##
|
|
39
|
+
## Context injection
|
|
62
40
|
|
|
63
|
-
|
|
64
|
-
- **Commands** - Vendored Beads workflows available under the `/beads:*` namespace
|
|
65
|
-
- **Task agent** - Autonomous issue completion via `beads-task-agent` subagent
|
|
41
|
+
The plugin runs full `bd prime` when a primary-agent session first receives a message and after compaction. Prime supplies the canonical current workflow, command guidance, and persistent memories; the plugin adds only compact OpenCode-specific safety and delegation guidance.
|
|
66
42
|
|
|
67
|
-
|
|
43
|
+
Known regular subagents remain excluded, including `explore` and `general`, while `beads-task-agent` remains eligible. If agent lookup fails, context injection fails open to preserve compatibility with unknown custom primary agents.
|
|
68
44
|
|
|
69
|
-
|
|
45
|
+
If `bd` is unavailable, the project is uninitialized, or prime fails or returns no content, injection is silently skipped and remains retryable. Vendored commands stay available, and the task agent retains a bounded standalone quick reference for `ready`, `show`, atomic claim, discovered follow-up, validate before closure, and close.
|
|
70
46
|
|
|
71
|
-
|
|
47
|
+
## Commands
|
|
72
48
|
|
|
73
|
-
|
|
49
|
+
Vendored workflows are registered under `/beads:*`, including `/beads:ready`, `/beads:create`, and `/beads:show`. The plugin does not generate a command for every `bd` subcommand; use the CLI and the generated [Beads CLI reference](https://beads.gascity.com/cli-reference/index) for the complete surface.
|
|
74
50
|
|
|
75
|
-
|
|
51
|
+
Explicit command and agent definitions in OpenCode configuration take precedence over plugin definitions with the same name. Exact `beads:*` or `beads-task-agent` collisions produce a grouped, rate-limited warning without preventing non-conflicting definitions from loading.
|
|
76
52
|
|
|
77
|
-
##
|
|
53
|
+
## Task agent
|
|
78
54
|
|
|
79
|
-
|
|
55
|
+
`beads-task-agent` supports read-only status and graph analysis or one-Bead completion. Analysis requests never mutate Beads. Completion requests inspect and process one caller-selected or highest-priority ready Bead, quarantine work discovered during that invocation, validate before closure, and return after closing or blocking the selected Bead.
|
|
80
56
|
|
|
81
|
-
|
|
57
|
+
Its runtime prompt is a fork-owned bounded OpenCode adaptation. The vendored upstream task-agent artifact supplies metadata, provenance, and compatibility validation; it is not executed as upstream's autonomous multi-task loop.
|
|
82
58
|
|
|
83
|
-
##
|
|
59
|
+
## Vendored content
|
|
84
60
|
|
|
85
|
-
|
|
61
|
+
[`scripts/sync-beads.sh`](scripts/sync-beads.sh) copies the reviewed upstream command templates and task-agent artifact into `vendor/`. [`vendor/manifest.json`](vendor/manifest.json) pins the upstream tag and commit and records source paths, sorted inventory, byte lengths, and SHA-256 checksums. A deterministic adaptation layer translates reviewed host-specific instructions to OpenCode's CLI-only model.
|
|
86
62
|
|
|
87
|
-
|
|
63
|
+
Do not edit vendored files directly. Sync and package validation reject provenance, checksum, inventory, schema, or reviewed-transformation drift. Adapter behavior lives in `src/`; general Beads behavior and documentation remain upstream.
|
|
88
64
|
|
|
89
65
|
## Compatibility
|
|
90
66
|
|
|
91
|
-
The compatibility ranges and validated baselines for this release are:
|
|
92
|
-
|
|
93
67
|
| Component | Expected range | Validated baseline |
|
|
94
68
|
| --- | --- | --- |
|
|
95
69
|
| OpenCode | 1.18.3 through 1.x | 1.18.15 |
|
|
96
70
|
| `bd` CLI | 1.0.5 through 1.x | 1.1.2 |
|
|
97
71
|
| Bun | >=1.3.14 | 1.3.14 |
|
|
98
72
|
|
|
99
|
-
The
|
|
100
|
-
|
|
101
|
-
## Vendored Content
|
|
102
|
-
|
|
103
|
-
Files under `vendor/` are copied from the upstream Beads plugin by [`scripts/sync-beads.sh`](scripts/sync-beads.sh). The current inventory includes the complete upstream command-template directory and task agent, rather than a duplicate of the much larger `bd` CLI. [`vendor/manifest.json`](vendor/manifest.json) records the stable upstream tag and commit, source paths, sorted inventory, byte lengths, and SHA-256 checksums. A deterministic adaptation layer translates known MCP- or Claude-specific instructions to OpenCode's CLI-only model when prompts load; sync fails if provenance, checksums, inventory, or reviewed transformations differ. Do not edit vendored files directly: the next sync replaces them. Adapter behavior lives in `src/`, while general Beads behavior and documentation remain upstream.
|
|
104
|
-
|
|
105
|
-
The vendor manifest, task agent, and every recorded command file are required package content. Their exact upstream source paths, inventory, byte lengths, and hashes are strict package inputs. Plugin loading fails with the artifact path and validation reason if required content is missing or malformed. Command frontmatter supports `description`, `argument-hint`, `agent`, `model`, and `subtask`; task-agent frontmatter supports `description`, `mode: subagent`, `model`, `temperature`, `top_p`, `disable`, `color`, and `maxSteps`. Unsupported fields or shapes fail validation so upstream changes receive explicit review. Reinstall the package or rerun the sync script from a source checkout rather than repairing generated files by hand.
|
|
73
|
+
The adapter builds against paired `@opencode-ai/plugin` and `@opencode-ai/sdk` 1.18.15 releases and declares compatible optional peers from 1.18.3 through stable 1.x. Command and agent provenance is synced from Beads v1.2.1.
|
|
106
74
|
|
|
107
75
|
## Troubleshooting
|
|
108
76
|
|
|
109
|
-
- **No Beads context:** Run `bd prime
|
|
110
|
-
- **Canonical skill
|
|
111
|
-
- **
|
|
112
|
-
- **
|
|
113
|
-
- **
|
|
114
|
-
- **
|
|
115
|
-
- **Behavior changed after an upgrade:** Compare `opencode --version`, `bd version`, and `bun --version` with the compatibility table, then check the [Beads releases](https://github.com/gastownhall/beads/releases) and this project's changelog.
|
|
77
|
+
- **No Beads context:** Run `bd prime`. Install `bd` if missing or run `bd init` if the project has no Beads workspace.
|
|
78
|
+
- **Canonical skill missing:** For a new workspace, run `bd init`. For an existing workspace, follow current upstream Beads guidance; this plugin does not install or repair skills.
|
|
79
|
+
- **Vendor initialization error:** Reinstall the package. In a source checkout, rerun vendor sync and validation; the error identifies the malformed or missing artifact.
|
|
80
|
+
- **Unexpected definition:** Check OpenCode configuration for a colliding `beads:*` command or `beads-task-agent` definition. Explicit configuration wins.
|
|
81
|
+
- **Regular subagent has no context:** This is intentional. Delegate Beads work to `beads-task-agent` or run the required `bd` command explicitly.
|
|
82
|
+
- **Behavior changed after upgrade:** Compare `opencode --version`, `bd version`, and `bun --version` with the compatibility table, then inspect [Beads releases](https://github.com/gastownhall/beads/releases) and this project's changelog.
|
|
116
83
|
|
|
117
84
|
## License
|
|
118
85
|
|
|
119
|
-
opencode-beads is licensed under the MIT license. See
|
|
120
|
-
|
|
121
|
-
---
|
|
122
|
-
|
|
123
|
-
opencode-beads is not built by, or affiliated with, the OpenCode team.
|
|
86
|
+
opencode-beads is licensed under the MIT license. See [`LICENSE`](LICENSE).
|
|
124
87
|
|
|
125
|
-
OpenCode is ©2025 Anomaly.
|
|
88
|
+
opencode-beads is not built by or affiliated with the OpenCode team. OpenCode is ©2025 Anomaly.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@snarkipus/opencode-beads",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.3",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "A maintained OpenCode integration for the Beads issue tracker, including context injection, vendored workflows, and a task agent.",
|
|
6
6
|
"author": "Matt Jackson",
|
package/vendor/commands/audit.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Log and label agent interactions (append-only JSONL)
|
|
3
|
-
argument-hint: record|label
|
|
3
|
+
argument-hint: "record|label"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
Append-only audit logging for agent interactions (prompts, responses, tool calls) in `.beads/interactions.jsonl`.
|
|
@@ -25,4 +25,3 @@ Each line is one event. Labeling is done by appending a new `"label"` event refe
|
|
|
25
25
|
- Audit entries are **append-only** (no in-place edits).
|
|
26
26
|
- `bd dolt push` includes `.beads/interactions.jsonl` in the commit allowlist.
|
|
27
27
|
|
|
28
|
-
|
package/vendor/commands/close.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Compact old closed issues using semantic summarization
|
|
3
|
-
argument-hint: [--all] [--id issue-id] [--dry-run]
|
|
3
|
+
argument-hint: "[--all] [--id issue-id] [--dry-run]"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
Reduce database size by summarizing closed issues no longer actively referenced.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Record, list, and manage project decisions with rationale tracking
|
|
3
|
-
argument-hint: record|list|show|supersede
|
|
3
|
+
argument-hint: "record|list|show|supersede"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
Record and track project decisions as beads issues with structured rationale, alternatives considered, and links to affected work.
|
|
@@ -9,7 +9,7 @@ Decisions use `--type decision`. The description field holds the structured deci
|
|
|
9
9
|
|
|
10
10
|
## Record a Decision
|
|
11
11
|
|
|
12
|
-
When the user wants to record a decision (
|
|
12
|
+
When the user wants to record a decision (i.e. the `record` action of this command):
|
|
13
13
|
|
|
14
14
|
1. Gather the following (ask if not provided):
|
|
15
15
|
- **Title**: Short summary of what was decided (required)
|
package/vendor/commands/dep.md
CHANGED
package/vendor/commands/epic.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Epic management commands
|
|
3
|
-
argument-hint: [command]
|
|
3
|
+
argument-hint: "[command]"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
Manage epics (large features composed of multiple issues).
|
|
@@ -21,6 +21,9 @@ Manage epics (large features composed of multiple issues).
|
|
|
21
21
|
1. Create epic: `bd create "Large Feature" -t epic -p 1`
|
|
22
22
|
2. Link subtasks: `bd dep add bd-20 bd-10 --type parent-child` (task bd-20 is child of epic bd-10)
|
|
23
23
|
- Or at creation: `bd create "Subtask title" -t task --parent bd-10`
|
|
24
|
+
- Children inherit parent labels by default. If the epic uses size/effort
|
|
25
|
+
labels and children should have their own, add `--no-inherit-labels`
|
|
26
|
+
(GH#4562).
|
|
24
27
|
3. Track progress: `bd epic status`
|
|
25
28
|
4. Auto-close when done: `bd epic close-eligible`
|
|
26
29
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Export issues to JSONL format
|
|
3
|
-
argument-hint: [-o output-file]
|
|
3
|
+
argument-hint: "[-o output-file]"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
Export all issues to JSON Lines format (one JSON object per line).
|
|
@@ -9,7 +9,7 @@ Export all issues to JSON Lines format (one JSON object per line).
|
|
|
9
9
|
|
|
10
10
|
- **To stdout**: `bd export`
|
|
11
11
|
- **To file**: `bd export -o issues.jsonl`
|
|
12
|
-
- **
|
|
12
|
+
- **Include all records**: `bd export --all -o full.jsonl`
|
|
13
13
|
|
|
14
14
|
Issues are sorted by ID for consistent diffs, making git diffs readable.
|
|
15
15
|
|
|
@@ -1,18 +1,84 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Import issues from JSONL
|
|
3
|
-
argument-hint:
|
|
2
|
+
description: Import issues and memories from JSONL
|
|
3
|
+
argument-hint: "[file|-] [--input file] [--dry-run] [--dedup] [--allow-stale]"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
`bd import`
|
|
6
|
+
`bd import` imports newline-delimited JSON into an existing Beads database.
|
|
7
|
+
Issues with new IDs are created and existing IDs use guarded upsert semantics.
|
|
8
|
+
The command is not supported in proxied-server mode.
|
|
7
9
|
|
|
8
|
-
##
|
|
9
|
-
|
|
10
|
-
If you need to import issues from a JSONL file, use `bd init` with the `--from-jsonl` flag:
|
|
10
|
+
## Usage
|
|
11
11
|
|
|
12
12
|
```bash
|
|
13
|
-
bd
|
|
13
|
+
bd import # Read .beads/<import.path>
|
|
14
|
+
bd import backup.jsonl # Read a specific file
|
|
15
|
+
bd import --input backup.jsonl # Same as -i backup.jsonl
|
|
16
|
+
bd import - # Read JSONL from stdin
|
|
17
|
+
bd export --include-memories | bd import - # Round-trip issues and memories
|
|
18
|
+
bd import --dry-run backup.jsonl # Parse and report without writing
|
|
19
|
+
bd import --json backup.jsonl # Return a structured result
|
|
14
20
|
```
|
|
15
21
|
|
|
16
|
-
|
|
22
|
+
With no file argument, the source is the `import.path` file under `.beads/`;
|
|
23
|
+
`import.path` defaults to `issues.jsonl`. Use either a positional file or
|
|
24
|
+
`--input`/`-i`, not both. The special path `-` reads stdin. With `--global` and
|
|
25
|
+
no file, the source is `global-issues.jsonl` in the active Beads directory.
|
|
26
|
+
|
|
27
|
+
Each non-empty line must be a JSON object. Issue records accept the schema
|
|
28
|
+
emitted by `bd export`; `title` is the only required issue field. Records with
|
|
29
|
+
`"_type":"memory"` and non-empty `key` and `value` fields are imported as
|
|
30
|
+
persistent memories. Optional export header records are ignored, and tombstone
|
|
31
|
+
rows are skipped. `bd export` omits memories by default; add
|
|
32
|
+
`--include-memories` or `--all` when they should be carried into an import.
|
|
33
|
+
|
|
34
|
+
## Merge and Safety Semantics
|
|
35
|
+
|
|
36
|
+
For records that supply `updated_at`, an incoming row rewrites an existing
|
|
37
|
+
issue only when its timestamp is strictly newer. Older records are skipped
|
|
38
|
+
wholesale, including their labels, comments, and dependencies. When timestamps
|
|
39
|
+
are equal, the local issue row wins, while those auxiliary records still merge.
|
|
40
|
+
The stale check is repeated inside the upsert so a concurrent newer local update
|
|
41
|
+
is not overwritten.
|
|
42
|
+
|
|
43
|
+
If `updated_at` is omitted, the importer fills it with the current time during
|
|
44
|
+
the write. A record naming an existing ID can therefore overwrite local state;
|
|
45
|
+
include the exported timestamp when stale protection matters.
|
|
46
|
+
|
|
47
|
+
Use `--allow-stale` only when deliberately restoring an older snapshot: it
|
|
48
|
+
disables that guard and can overwrite newer local issue state. Imports are
|
|
49
|
+
upserts, and labels, comments, and dependencies are deduplicated. Re-running
|
|
50
|
+
canonical export data or other input with stable issue IDs and preserved
|
|
51
|
+
`updated_at` values is safe and converges. Without a preserved timestamp, each
|
|
52
|
+
run can appear newer and rewrite the row. An issue record without an ID is
|
|
53
|
+
assigned one; re-importing it can create another issue instead of targeting the
|
|
54
|
+
first.
|
|
55
|
+
|
|
56
|
+
Large issue imports use bounded SQL transaction chunks. If one fails, the
|
|
57
|
+
command exits nonzero and keeps the already committed prefix in the Dolt working
|
|
58
|
+
set; no final import-summary Dolt commit is created. Re-run stable-ID input to
|
|
59
|
+
resume only when its `updated_at` values are also preserved.
|
|
60
|
+
|
|
61
|
+
After a successful non-dry import with accepted issue or memory records, the
|
|
62
|
+
command calls `store.Commit` with an import summary regardless of the
|
|
63
|
+
`dolt.auto-commit` policy. That commit can include unrelated pending working-set
|
|
64
|
+
changes; in direct server mode, config (including memories) is excluded from
|
|
65
|
+
this commit. When commit isolation matters, run `bd doctor` before importing and
|
|
66
|
+
proceed only when its Dolt Status check reports a clean working set.
|
|
67
|
+
|
|
68
|
+
The database must already exist; initialize or bootstrap it before importing.
|
|
69
|
+
Use `--dry-run` to parse the input, apply optional title deduplication, and
|
|
70
|
+
report issue and memory counts without writing. It does not run write-time field
|
|
71
|
+
validation or predict stale skips and updates.
|
|
72
|
+
|
|
73
|
+
## Flags
|
|
17
74
|
|
|
18
|
-
|
|
75
|
+
- `--input`, `-i <file>`: read a specific file instead of a positional path.
|
|
76
|
+
- `--dry-run`: report parsed record counts without writing.
|
|
77
|
+
- `--dedup`: skip an input issue whose title exactly matches, ignoring case, an
|
|
78
|
+
existing non-closed issue. Input rows are not compared with one another; if
|
|
79
|
+
the existing-issue search fails, title filtering is skipped.
|
|
80
|
+
- `--allow-stale`: import older rows too, allowing newer local state to be
|
|
81
|
+
overwritten.
|
|
82
|
+
- `--json`: use global JSON-output mode for structured counts and IDs. The
|
|
83
|
+
`created` count is accepted issue rows, including existing rows, not only new
|
|
84
|
+
inserts.
|
package/vendor/commands/init.md
CHANGED
package/vendor/commands/label.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Manage issue labels
|
|
3
|
-
argument-hint: [command] [issue-id] [label]
|
|
3
|
+
argument-hint: "[command] [issue-id] [label]"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
Manage labels on beads issues. Labels provide flexible cross-cutting metadata beyond structured fields (status, priority, type).
|
package/vendor/commands/list.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Quick start guide for bd workflows (deprecated)
|
|
3
|
-
argument-hint:
|
|
3
|
+
argument-hint: ""
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
**Note:** The `bd quickstart` command is deprecated. See the [Quick Start](https://
|
|
6
|
+
**Note:** The `bd quickstart` command is deprecated. See the [Quick Start](https://beads.gascity.com/getting-started/quickstart) on the documentation site, or the in-repo source [docs/getting-started/quickstart.md](https://github.com/gastownhall/beads/blob/main/docs/getting-started/quickstart.md).
|
|
7
7
|
|
|
8
8
|
The quickstart documentation covers:
|
|
9
9
|
- Getting started with bd
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Rename the issue prefix for all issues
|
|
3
|
-
argument-hint: <new-prefix> [--dry-run]
|
|
3
|
+
argument-hint: "<new-prefix> [--dry-run]"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
Rename the issue prefix for all issues in the database.
|
|
@@ -9,7 +9,6 @@ Updates all issue IDs and all text references across all fields.
|
|
|
9
9
|
|
|
10
10
|
## Prefix Rules
|
|
11
11
|
|
|
12
|
-
- Max length: 8 characters
|
|
13
12
|
- Allowed: lowercase letters, numbers, hyphens
|
|
14
13
|
- Must start with a letter
|
|
15
14
|
- Must end with a hyphen (e.g., 'kw-', 'work-')
|
package/vendor/commands/show.md
CHANGED
package/vendor/commands/sync.md
CHANGED
|
@@ -1,17 +1,109 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Synchronize issues
|
|
3
|
-
argument-hint:
|
|
2
|
+
description: Synchronize issues with a configured Dolt remote
|
|
3
|
+
argument-hint: ""
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
`bd sync`
|
|
6
|
+
`bd sync` runs one full synchronization cycle against the configured Dolt
|
|
7
|
+
remote: pull, check for merge conflicts, recompute the denormalized
|
|
8
|
+
`is_blocked` flag, then push — retrying a bounded number of times when another
|
|
9
|
+
replica wins the push race. It is the loop a multi-machine deployment otherwise
|
|
10
|
+
hand-rolls in shell, and it is the verb to reach for on a sync timer.
|
|
7
11
|
|
|
8
|
-
|
|
12
|
+
(This is not the old JSONL-era `bd sync`, which was removed in v0.51. Nested
|
|
13
|
+
commands such as `bd backup sync` and the tracker-specific sync commands are
|
|
14
|
+
separate commands and are unaffected.)
|
|
9
15
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
16
|
+
```bash
|
|
17
|
+
bd sync # sync with the default remote
|
|
18
|
+
bd sync --remote mini # sync with a specific named remote
|
|
19
|
+
bd sync --attempts 5 # allow more push-race retries (default 3)
|
|
20
|
+
bd sync --json # machine-parseable outcome
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Exit codes are the machine contract, so a timer can branch on them without
|
|
24
|
+
parsing output:
|
|
25
|
+
|
|
26
|
+
| Code | Meaning |
|
|
27
|
+
|------|---------|
|
|
28
|
+
| `0` | Synced, or nothing to do |
|
|
29
|
+
| `1` | Error (transport, auth, storage) |
|
|
30
|
+
| `2` | Merge conflict — halted, nothing pushed; resolve it by hand |
|
|
31
|
+
| `3` | Push-race retries exhausted — transient, retry on the next tick |
|
|
32
|
+
|
|
33
|
+
Two properties are the point of the verb. Conflicts are detected **positively**,
|
|
34
|
+
from the merge's own conflict rows and from Dolt's conflict tables — never
|
|
35
|
+
inferred from the pull's exit status, which is untrustworthy in both directions.
|
|
36
|
+
And a conflict sync cannot settle is **never** resolved by picking a side: it
|
|
37
|
+
halts before recomputing or pushing, and keeps halting the same way until an
|
|
38
|
+
operator resolves the divergence. (The pull underneath still auto-settles the
|
|
39
|
+
convergent conflict classes it always has — machine-local metadata rows,
|
|
40
|
+
audit-only dependency rows, last-write-wins on issue cells. Anything past those
|
|
41
|
+
halts here.)
|
|
42
|
+
|
|
43
|
+
The halt message says which state the halt left behind, because it depends on
|
|
44
|
+
the pull route and both are real: the SQL route aborts the conflicted merge and
|
|
45
|
+
restores the working set, while the CLI/git-protocol route leaves the conflict
|
|
46
|
+
rows **live** for you. A conflict that was already live when sync started — from
|
|
47
|
+
an earlier halted sync or a hand-run merge — halts before the pull instead, and
|
|
48
|
+
says that too.
|
|
49
|
+
|
|
50
|
+
The recompute between pull and push is not bookkeeping either — `is_blocked` is
|
|
51
|
+
denormalized, so a dependency edge merged in from another replica leaves
|
|
52
|
+
`bd ready` stale until it runs. It runs on every attempt, unconditionally:
|
|
53
|
+
`bd recompute-blocked`'s full pass is specifically the repair that does *not*
|
|
54
|
+
depend on a merge advancing HEAD, so it is what recovers a column left stale by
|
|
55
|
+
a conflicted pull you resolved by hand — a state sync itself creates by exiting
|
|
56
|
+
2. Gating it on "did this tick merge anything" would mean that repair never runs
|
|
57
|
+
again while every tick reports success.
|
|
58
|
+
|
|
59
|
+
This is not `bd federation sync`, which syncs with named peer towns and takes a
|
|
60
|
+
`--strategy ours|theirs` to resolve whatever conflicts it meets. `bd sync`
|
|
61
|
+
targets the configured remote and has no such switch.
|
|
62
|
+
|
|
63
|
+
`--json` reports `{"status", "attempts", "conflicts", "conflicts_live",
|
|
64
|
+
"rows_corrected", "pushed"}` on every non-error exit; exit 1 emits bd's standard
|
|
65
|
+
`{"error": ...}` envelope instead, so a timer reading `.status` must treat
|
|
66
|
+
`null` as the error case (or just branch on the exit code, which is the point).
|
|
67
|
+
A rig with no remote configured exits 0 with setup guidance; `dolt.local-only`
|
|
68
|
+
and the `no-push` config flag are honored.
|
|
69
|
+
|
|
70
|
+
## The equivalent by hand
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
# Before starting work or consuming changes from another clone
|
|
74
|
+
bd dolt pull
|
|
75
|
+
|
|
76
|
+
# After local issue updates and before handoff: commit, integrate, then publish
|
|
77
|
+
bd dolt commit
|
|
78
|
+
bd dolt pull
|
|
79
|
+
bd dolt push
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`bd dolt commit` creates an explicit commit boundary when auto-commit is off or
|
|
83
|
+
in batch mode; it is a safe no-op when there is nothing pending. The following
|
|
84
|
+
pull integrates remote changes before the final push. The pull steps require a
|
|
85
|
+
configured remote; use the one-time setup below first when needed.
|
|
86
|
+
|
|
87
|
+
Inspect the configured Dolt remotes with:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
bd dolt remote list
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
If no Dolt remote exists, the project has a Git origin, and remote sync is
|
|
94
|
+
enabled, `bd dolt push` automatically adopts that origin; do not add the
|
|
95
|
+
matching URL manually. To use a distinct custom Dolt remote, first confirm that
|
|
96
|
+
the chosen name is absent, then add it explicitly:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
bd dolt remote add origin <distinct-dolt-remote-url>
|
|
100
|
+
```
|
|
14
101
|
|
|
15
102
|
## Note
|
|
16
103
|
|
|
17
|
-
|
|
104
|
+
When enabled, `dolt.auto-commit` records successful writes in local Dolt
|
|
105
|
+
history; it does not push them to a remote. Remote auto-push is a separate,
|
|
106
|
+
opt-in setting and is disabled by default. Auto-push publishes committed HEAD
|
|
107
|
+
only; it does not commit pending working-set writes when auto-commit is off or
|
|
108
|
+
in batch mode. Keep an explicit commit boundary before handoff unless the
|
|
109
|
+
project has a coordinated policy that provides one.
|
package/vendor/manifest.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"repository": "https://github.com/gastownhall/beads.git",
|
|
4
|
-
"tag": "v1.1
|
|
5
|
-
"commit": "
|
|
4
|
+
"tag": "v1.2.1",
|
|
5
|
+
"commit": "634cbbc4bc580fa5124f63fdf65d137a46d5b4ff",
|
|
6
6
|
"sources": [
|
|
7
7
|
{
|
|
8
8
|
"source": "plugins/beads/agents/task-agent.md",
|
|
@@ -21,78 +21,78 @@
|
|
|
21
21
|
},
|
|
22
22
|
{
|
|
23
23
|
"path": "commands/audit.md",
|
|
24
|
-
"bytes":
|
|
25
|
-
"sha256": "
|
|
24
|
+
"bytes": 956,
|
|
25
|
+
"sha256": "bf941ae72f3dfad0e5a0997c8afa1647d6ce17934692efa30e9fe4da98e39de8"
|
|
26
26
|
},
|
|
27
27
|
{
|
|
28
28
|
"path": "commands/blocked.md",
|
|
29
29
|
"bytes": 561,
|
|
30
|
-
"sha256": "
|
|
30
|
+
"sha256": "30181c3645b5e233005facde694a3bb001c5935258745ae976abfe7b93eec346"
|
|
31
31
|
},
|
|
32
32
|
{
|
|
33
33
|
"path": "commands/close.md",
|
|
34
|
-
"bytes":
|
|
35
|
-
"sha256": "
|
|
34
|
+
"bytes": 585,
|
|
35
|
+
"sha256": "ef43e31c9f86082a6192ca131c175c55ee37dc115f4781413be11f1e85274b58"
|
|
36
36
|
},
|
|
37
37
|
{
|
|
38
38
|
"path": "commands/comments.md",
|
|
39
|
-
"bytes":
|
|
40
|
-
"sha256": "
|
|
39
|
+
"bytes": 967,
|
|
40
|
+
"sha256": "cad54141ee590be3b8d07878bb3ea34c252466bbb00a9b95d7d521303a8e3b83"
|
|
41
41
|
},
|
|
42
42
|
{
|
|
43
43
|
"path": "commands/compact.md",
|
|
44
|
-
"bytes":
|
|
45
|
-
"sha256": "
|
|
44
|
+
"bytes": 1083,
|
|
45
|
+
"sha256": "5204417505320501e2c5a529da6c670826ef5b62feab708a33b7452dfd6a80c4"
|
|
46
46
|
},
|
|
47
47
|
{
|
|
48
48
|
"path": "commands/create.md",
|
|
49
|
-
"bytes":
|
|
50
|
-
"sha256": "
|
|
49
|
+
"bytes": 651,
|
|
50
|
+
"sha256": "1e27f3ff4f3ae041f6896b5181f0b0399ff80d52cd415dfd8cf6584a218736d3"
|
|
51
51
|
},
|
|
52
52
|
{
|
|
53
53
|
"path": "commands/decision.md",
|
|
54
|
-
"bytes":
|
|
55
|
-
"sha256": "
|
|
54
|
+
"bytes": 2670,
|
|
55
|
+
"sha256": "78c0de4a0979502cb553c2ad49df32cc1e6a7cb3eec25dc41f60290ad4fbbe36"
|
|
56
56
|
},
|
|
57
57
|
{
|
|
58
58
|
"path": "commands/delete.md",
|
|
59
|
-
"bytes":
|
|
60
|
-
"sha256": "
|
|
59
|
+
"bytes": 961,
|
|
60
|
+
"sha256": "a6a5e943cccc75c27820548ec4a810894be646604b98821822968c7cb55552eb"
|
|
61
61
|
},
|
|
62
62
|
{
|
|
63
63
|
"path": "commands/dep.md",
|
|
64
|
-
"bytes":
|
|
65
|
-
"sha256": "
|
|
64
|
+
"bytes": 3410,
|
|
65
|
+
"sha256": "2d50ea5c65e0ce27bc076e77de5ea32de7086b34c6f49736e71517548cfe4b76"
|
|
66
66
|
},
|
|
67
67
|
{
|
|
68
68
|
"path": "commands/epic.md",
|
|
69
|
-
"bytes":
|
|
70
|
-
"sha256": "
|
|
69
|
+
"bytes": 1027,
|
|
70
|
+
"sha256": "174f54e3092e5a4b2f4c010e95418b13f1d910e185349ba0e131b04cf5783b8b"
|
|
71
71
|
},
|
|
72
72
|
{
|
|
73
73
|
"path": "commands/export.md",
|
|
74
|
-
"bytes":
|
|
75
|
-
"sha256": "
|
|
74
|
+
"bytes": 800,
|
|
75
|
+
"sha256": "5c8e9c9b4df71c804f489fa5785d607be971b7f62c836ad531f11e8b105ee47a"
|
|
76
76
|
},
|
|
77
77
|
{
|
|
78
78
|
"path": "commands/import.md",
|
|
79
|
-
"bytes":
|
|
80
|
-
"sha256": "
|
|
79
|
+
"bytes": 4433,
|
|
80
|
+
"sha256": "604e48e6d093d9a93f28a3a5ed7dd7946b10e7a4897bec8a88eefc5b6c9c776e"
|
|
81
81
|
},
|
|
82
82
|
{
|
|
83
83
|
"path": "commands/init.md",
|
|
84
|
-
"bytes":
|
|
85
|
-
"sha256": "
|
|
84
|
+
"bytes": 753,
|
|
85
|
+
"sha256": "975759ee3d7ac6611fa54ae27c277a2995288a8fd089e6b46b791f73f3322177"
|
|
86
86
|
},
|
|
87
87
|
{
|
|
88
88
|
"path": "commands/label.md",
|
|
89
|
-
"bytes":
|
|
90
|
-
"sha256": "
|
|
89
|
+
"bytes": 898,
|
|
90
|
+
"sha256": "45f0422cce8764a19158a98e95b6b3c790e7a01b3438d9b5471ddb5f8c544129"
|
|
91
91
|
},
|
|
92
92
|
{
|
|
93
93
|
"path": "commands/list.md",
|
|
94
|
-
"bytes":
|
|
95
|
-
"sha256": "
|
|
94
|
+
"bytes": 2628,
|
|
95
|
+
"sha256": "990a0e6ef5af6a6ec596df32590750efd27fd231a44a0882d3f900dc71a4380f"
|
|
96
96
|
},
|
|
97
97
|
{
|
|
98
98
|
"path": "commands/prime.md",
|
|
@@ -101,8 +101,8 @@
|
|
|
101
101
|
},
|
|
102
102
|
{
|
|
103
103
|
"path": "commands/quickstart.md",
|
|
104
|
-
"bytes":
|
|
105
|
-
"sha256": "
|
|
104
|
+
"bytes": 537,
|
|
105
|
+
"sha256": "de372b2dac3b1786ee383e8295bca781d6ce890db0daa09efa4d044325b80bbc"
|
|
106
106
|
},
|
|
107
107
|
{
|
|
108
108
|
"path": "commands/ready.md",
|
|
@@ -111,28 +111,28 @@
|
|
|
111
111
|
},
|
|
112
112
|
{
|
|
113
113
|
"path": "commands/rename-prefix.md",
|
|
114
|
-
"bytes":
|
|
115
|
-
"sha256": "
|
|
114
|
+
"bytes": 574,
|
|
115
|
+
"sha256": "2e6a457dfe58a855daecc0581433584073d7b52565a9bdb85131d1b4a3d920e8"
|
|
116
116
|
},
|
|
117
117
|
{
|
|
118
118
|
"path": "commands/reopen.md",
|
|
119
|
-
"bytes":
|
|
120
|
-
"sha256": "
|
|
119
|
+
"bytes": 595,
|
|
120
|
+
"sha256": "ea5535f0004d3137f05b6fc81cff1ecc670d918465b7d878eb6cb01d2427578c"
|
|
121
121
|
},
|
|
122
122
|
{
|
|
123
123
|
"path": "commands/restore.md",
|
|
124
|
-
"bytes":
|
|
125
|
-
"sha256": "
|
|
124
|
+
"bytes": 714,
|
|
125
|
+
"sha256": "94928e7b5d8ca1da80571e56685020f31eba6ce8fd38100cba09f00a051e164e"
|
|
126
126
|
},
|
|
127
127
|
{
|
|
128
128
|
"path": "commands/search.md",
|
|
129
|
-
"bytes":
|
|
130
|
-
"sha256": "
|
|
129
|
+
"bytes": 3190,
|
|
130
|
+
"sha256": "2295d2cf34f0d7c3a74fab86f73aa312435870c97aa71d8c965486a450310085"
|
|
131
131
|
},
|
|
132
132
|
{
|
|
133
133
|
"path": "commands/show.md",
|
|
134
|
-
"bytes":
|
|
135
|
-
"sha256": "
|
|
134
|
+
"bytes": 563,
|
|
135
|
+
"sha256": "51aa4b5a5bebeb9f1027f5a31a3de307dd8116052471f40272f0b2c980c720af"
|
|
136
136
|
},
|
|
137
137
|
{
|
|
138
138
|
"path": "commands/stats.md",
|
|
@@ -141,8 +141,8 @@
|
|
|
141
141
|
},
|
|
142
142
|
{
|
|
143
143
|
"path": "commands/sync.md",
|
|
144
|
-
"bytes":
|
|
145
|
-
"sha256": "
|
|
144
|
+
"bytes": 4964,
|
|
145
|
+
"sha256": "09d999165b93ea183e5828c94d45498503ed179211db5f68b3c32f372ade9ac7"
|
|
146
146
|
},
|
|
147
147
|
{
|
|
148
148
|
"path": "commands/template.md",
|
|
@@ -151,8 +151,8 @@
|
|
|
151
151
|
},
|
|
152
152
|
{
|
|
153
153
|
"path": "commands/update.md",
|
|
154
|
-
"bytes":
|
|
155
|
-
"sha256": "
|
|
154
|
+
"bytes": 870,
|
|
155
|
+
"sha256": "34896bde7871805fb1941afd81a25ebc2ce1030090b8ce96afc63763bd2bd108"
|
|
156
156
|
},
|
|
157
157
|
{
|
|
158
158
|
"path": "commands/version.md",
|