diff --git a/internal/bashupgrade/alias_invocation_test.go b/cmd/docket/alias_invocation_test.go similarity index 79% rename from internal/bashupgrade/alias_invocation_test.go rename to cmd/docket/alias_invocation_test.go index 7d45413b8..e91ca6267 100644 --- a/internal/bashupgrade/alias_invocation_test.go +++ b/cmd/docket/alias_invocation_test.go @@ -1,4 +1,4 @@ -package bashupgrade +package main import ( "os" @@ -11,10 +11,10 @@ import ( ) // The alias is only useful if the binary behaves the same whatever name it was -// invoked by. This uses the real built binary (shared with the upgrade tests via -// buildDocket's sync.Once, so it costs no extra build) behind a dckt symlink. +// invoked by. This puts the binary TestMain builds once (binPath) behind a dckt +// symlink, so it costs no extra build. func TestAliasInvocationMatchesDocket(t *testing.T) { - bin := buildDocket(t) + bin := binPath dir := testsupport.TempDir(t) alias := filepath.Join(dir, install.AliasName) if err := os.Symlink(bin, alias); err != nil { diff --git a/docs/release/upgrading-from-bash.md b/docs/release/upgrading-from-bash.md index 2d72bc225..59d045ca2 100644 --- a/docs/release/upgrading-from-bash.md +++ b/docs/release/upgrading-from-bash.md @@ -2,10 +2,6 @@ This guide moves a Bash docket install, and the repositories it manages, to the docket binary. -An automated test runs every marked step below against saved copies of real `v0.9.2` and `v0.9.3` -installs. The exception is the download and checksum lines in section 3, which need the published -release. When something is outside that test, the guide says so. - ## 1. Who this is for Use this guide if all of these are true: @@ -20,7 +16,7 @@ not supported. ## 2. Before you start -- In each repository, finish or kill every change that is in progress. The test covers +- In each repository, finish or kill every change that is in progress. The guide covers repositories with no change in progress. - In each repository, check out the default branch and make sure `git status` shows no changes. The steps below commit and push to the default branch. @@ -31,7 +27,6 @@ Run these commands outside any repository. They download the installer and the c a new folder, check the installer against the checksum, then run it for Claude Code and Cursor. If you use only one of them, drop the other one's `--harness` flag, here and in section 4. - ```sh mkdir -p ~/docket-download && cd ~/docket-download curl -fsSLO "https://github.com/danielhanold/docket/releases/latest/download/install.sh" @@ -41,8 +36,7 @@ sh install.sh --harness claude --harness cursor ``` The `shasum` line must print `install.sh: OK`. If it prints anything else, stop and do not run -`install.sh`. The download and checksum lines are checked by the release's own verification, not by -this guide's test. +`install.sh`. The installer puts `docket` in `~/.local/bin`. Make sure that folder is on your `PATH`. @@ -75,7 +69,6 @@ same way. It reports these Cursor paths as conflicts: Delete the Cursor paths first. If you don't use Cursor, skip this block. - ```sh rm ~/.cursor/skills/docket-* rm -f ~/.cursor/agents/docket-plan-writer.md ~/.cursor/rules/docket-dispatch.mdc @@ -85,7 +78,6 @@ Then delete the Claude Code paths and run the installer again from the same fold `--harness` flags as in section 3. If you don't use Claude Code, leave out the two `rm` lines. The failed run left no `docket` command, so run `sh install.sh` again, not `docket install`. - ```sh rm ~/.claude/skills/docket-* rm -f ~/.claude/agents/docket-plan-writer.md @@ -98,7 +90,6 @@ Bash docket also left a `runtime.bash` setting in your global config, `~/.config/docket/config.yml`. docket warns about it and ignores it. Delete these lines from that file. The path on the `bash:` line is whatever your Bash install recorded. - ```yaml # >>> docket (runtime.bash) >>> runtime: @@ -108,7 +99,6 @@ runtime: Then confirm the install. Both commands succeed, and `docket install check` prints no warning. - ```sh docket version docket install check @@ -119,7 +109,6 @@ docket install check Do this in every repository that has a `docket` branch. Replace `` with the repository's folder. - ```sh cd docket repository prepare @@ -128,7 +117,6 @@ docket repository prepare It reports `healthy` and keeps using the `.docket` folder Bash docket made. That does not mean the repository is ready yet. The next command finds what still needs fixing. - ```sh docket repository check ``` @@ -149,7 +137,6 @@ On a Bash repository it exits with an error and lists some of these findings: Start with `.gitignore`. Replace everything from its `# docket:start` line to its `# docket:end` line with exactly these lines, which `docket repository check` also prints: - ```text # docket:start (managed by docket — do not hand-edit) .docket/ @@ -170,7 +157,6 @@ a warning, with a remedy. Remove each of them from `.docket.yml`. Section 6 list that show up only as notices can stay. If the repository has no `.docket.yml`, there is nothing to remove. - ```sh docket status ``` @@ -178,7 +164,6 @@ docket status `docket status` reads `.docket.yml` from the pushed default branch, not from your working copy. Its list clears only after you commit and push. Commit and push both files: - ```sh git commit -am "Update docket's .gitignore block and settings" git push @@ -187,7 +172,6 @@ git push Now set up the test command. `docket repository configure-tests` writes the test settings into `.docket.yml`. Review them. - ```sh docket repository configure-tests ``` @@ -197,14 +181,12 @@ Next, choose the coding agents docket writes instructions for. On a terminal, because Bash docket's `CLAUDE.md` block would get in the way. The last step of this section, after you remove that block, chooses your agents. - ```sh docket repository configure-harnesses --harnesses none ``` Commit and push both settings in `.docket.yml`, the test command and the agents: - ```sh git add .docket.yml git commit -m "Configure docket's test command and agents" @@ -214,7 +196,6 @@ git push The last fix is for the records on the `docket` branch. First look at what will change: the command lists the files it would rewrite and asks `repair? [y/N]`. Answer `N`. - ```sh docket repository repair ``` @@ -222,14 +203,12 @@ docket repository repair Then apply the repairs. docket commits and pushes them to the `docket` branch itself, and brings your local `.docket` folder up to the repaired commit. - ```sh docket repository repair --yes ``` Then check the repository: - ```sh docket repository check ``` @@ -244,7 +223,6 @@ everything from the start line through the end line. If that leaves `CLAUDE.md` file. Then commit and push the change. If there is no such block, skip this step. There is nothing to commit, and `git commit` stops with an error. - ```sh git commit -am "Remove the Bash docket block from CLAUDE.md" git push @@ -256,7 +234,6 @@ For Cursor, it writes `.cursor/rules/docket-dispatch.mdc` into the repository, w `.gitignore` block keeps out of commits. Drop the agent you don't use from `--harnesses`, and if you don't use Claude Code, leave `CLAUDE.md` off the `git add` line. - ```sh docket repository configure-harnesses --harnesses claude,cursor git add .docket.yml CLAUDE.md @@ -279,7 +256,7 @@ These are the Bash-era settings docket reports, in `.docket.yml` or in | `build.checkpoint` | Error when set to `true`. | Remove it, or set it to `false`. | | `auto_capture.enabled` | Error when set to `true`. | Remove it, or set it to `false`. | | `dummy_mode.enabled` | Error when set to `true`. | Remove it, or set it to `false`. | -| `finalize.gate` | Error when set to `ci` or `both`. The saved installs cover `ci` only. | Remove it, or set it to `local` or `off`. | +| `finalize.gate` | Error when set to `ci` or `both`. | Remove it, or set it to `local` or `off`. | | `board_surfaces` | Error when the list holds `github`. | Remove it, or remove `github` from the list. | | `skills.` | Error. | Remove it. | | `agents...runner` | Error. | Remove it. | @@ -292,14 +269,12 @@ These are the Bash-era settings docket reports, in `.docket.yml` or in The Bash installer also left these behind. docket does not use them, and `docket install check` does not mention them. Delete them: - ```text ~/.claude/settings.json the "DOCKET_SCRIPTS_DIR" and "DOCKET_BASH_PATH" entries under "env" ~/.zshenv the lines from "# >>> docket (DOCKET_SCRIPTS_DIR) >>>" to "# <<< docket (DOCKET_SCRIPTS_DIR) <<<" ``` -The test covers zsh, where those lines are in `~/.zshenv`. Other shells keep them in a different -startup file, which the test does not cover. +These lines are in `~/.zshenv` for zsh. Other shells keep them in a different startup file. Your old Bash checkout, usually `~/dev/docket`, is no longer used by Claude Code or Cursor: nothing under `~/.claude` or `~/.cursor` points into it after the upgrade. The links Bash docket made for @@ -317,11 +292,8 @@ Bash docket also wrote agent files into a repository when its `.docket.yml` has setting: one `docket-*.md` file per agent under the repository's `.claude/agents/` folder, and for Cursor under `.cursor/agents/`. Claude Code uses an agent file in the repository instead of the one with the same name in `~/.claude/agents/`, so these old files hide the agents the installer just -wrote. Delete them in every repository. If a repository has none, the command does nothing. The -saved installs the test runs carry no repository Cursor agent files, so the test does not prove the -`.cursor/agents` line. +wrote. Delete them in every repository. If a repository has none, the command does nothing. - ```sh cd rm -f .claude/agents/docket-*.md @@ -334,8 +306,7 @@ commit. In each repository it converted, Bash docket's `migrate-to-docket.sh` also wrote `.claude/settings.local.json`. It holds a Claude Code permission rule for Bash docket's push to your default branch, such as `Bash(git -C * push origin HEAD:main)`, and it can also hold settings of -your own. This guide does not cover that file: the test leaves it in place and does not show -whether deleting it is safe. +your own. This guide does not cover that file and does not say whether deleting it is safe. ## 8. Restart Claude Code and Cursor diff --git a/docs/superpowers/specs/2026-11-08-retire-the-saved-bash-upgrade-test-cases-when-stable-v1-0-0-design.md b/docs/superpowers/specs/2026-11-08-retire-the-saved-bash-upgrade-test-cases-when-stable-v1-0-0-design.md new file mode 100644 index 000000000..c1671307e --- /dev/null +++ b/docs/superpowers/specs/2026-11-08-retire-the-saved-bash-upgrade-test-cases-when-stable-v1-0-0-design.md @@ -0,0 +1,91 @@ +# Retire the saved Bash upgrade test cases — design + +Change 0514 — Retire the saved Bash upgrade test cases when stable v1.0.0 ships + +## Intent + +`docs/release/upgrading-from-bash.md` moves a Bash docket `v0.9.2`/`v0.9.3` install to the docket +binary. During the v1.0.0 pre-releases, a test kept the guide accurate as the code changed: it +restored saved copies of real Bash installs from `testdata/bash-upgrade/` and ran the guide's +marked steps against the binary. Stable v1.0.0 has shipped, so that test has done its job. Users +never ran it, and it costs suite time on every build. + +This change deletes the saved cases and everything that exists only for them. The guide stays, +edited so it describes only the upgrade, with no mention of a test that will no longer exist. The +human's rule: documentation must not keep referring to code that is gone. + +## Goals + +1. Remove the Bash upgrade proof and every artifact that exists only to support it. +2. Keep the one test in that package that is not about upgrades: the `dckt` alias check. +3. Leave the guide accurate after the removal: same steps, tables and commands, with every + sentence about "the test" gone or rewritten as the guide's own scope. + +## Non-goals + +- Changing any upgrade step, command, findings table, or the guide's structure. +- Changing the installer's v0.9.2 takeover behavior. +- Editing point-in-time records that mention the test: release `decisions.md` and + `candidate/run.txt` files, archived specs, plans and results, and the frozen export corpus under + `internal/export/testdata/corpus/`. They stay as written. + +## Anti-goals + +- Losing `TestAliasInvocationMatchesDocket` along with the package it happens to live in. +- Leaving a "last verified against v1.0.0" line or any other note pointing at the retired test. + The human explicitly rejected one. + +## What gets deleted + +- `testdata/bash-upgrade/` — the whole tree (`PROVENANCE.md`, `v0.9.2/`, `v0.9.3/`). +- `internal/bashupgrade/` — the whole package (`doc.go` and every `*_test.go`), after the alias + test is moved out (below). +- `tests/test_go_integration_bashupgrade.sh` — the integration shard (prefix + `TestIntegrationBashUpgrade`). +- The `tests/test_go_integration_bashupgrade.sh` row in `tests/runtime-budgets.tsv`. +- The `## Root \`testdata/bash-upgrade//\`` section of `testdata/README.md`. + +The builder re-runs a whole-repo grep for `bashupgrade`, `bash-upgrade`, `BashUpgrade` and +`upgrade-step` at build time and sorts each hit into maintained source (fix) or point-in-time +record (leave). At grooming time the only maintained hits were the items above and the guide. + +## What moves + +`TestAliasInvocationMatchesDocket` (currently `internal/bashupgrade/alias_invocation_test.go`) +checks that the binary invoked through a `dckt` symlink (`install.AliasName`) gives the same +`version --json` output as when invoked as `docket`. It sat in `internal/bashupgrade` only to reuse +that package's one-time binary build. Move it into the `cmd/docket` package, whose `TestMain` +(in `main_test.go`) already builds the binary once into `binPath`, so the move adds no build. The assertion stays the +same; only the binary source changes from `buildDocket(t)` to `binPath`. + +## The guide edit (`docs/release/upgrading-from-bash.md`) + +Each passage about the test, by the sentence it opens with today: + +| Passage | Change | +|---|---| +| Intro: "An automated test runs every marked step below against saved copies…" (whole paragraph) | Delete. | +| §2: "The test covers repositories with no change in progress." | Becomes "The guide covers repositories with no change in progress." | +| §3: "The download and checksum lines are checked by the release's own verification, not by this guide's test." | Delete. Keep the "must print `install.sh: OK`" instruction before it. | +| §7: "The test covers zsh, where those lines are in `~/.zshenv`. Other shells keep them in a different startup file, which the test does not cover." | Becomes "These lines are in `~/.zshenv` for zsh. Other shells keep them in a different startup file." | +| §7: "The saved installs the test runs carry no repository Cursor agent files, so the test does not prove the `.cursor/agents` line." | Delete. | +| §7: "This guide does not cover that file: the test leaves it in place and does not show whether deleting it is safe." | Becomes "This guide does not cover that file and does not say whether deleting it is safe." | +| All 20 `` marker comments | Delete. | + +These are the passages found at grooming time. The builder greps the guide for `test` once more +and applies the same rule to any other sentence about the retired test: delete it if it only +describes test coverage, or rewrite it as the guide's own scope if the limit still matters to a +reader. The links to the guide from `README.md` and `docs/install/install.md` stay. + +## Verification + +- The full suite passes (`build.test_command`). The budget runner no longer lists the deleted shard, + and no runtime-budgets row is orphaned. +- `TestAliasInvocationMatchesDocket` runs in the `cmd/docket` package and passes. As a mutation + check, break the comparison and confirm the test goes red. +- The whole-repo grep above returns only point-in-time records. + +## Left to the builder + +- The exact wording around the deleted sentences, as long as no step, command or table changes. +- Whether the moved alias test keeps its own file in `cmd/docket` or joins `main_test.go`. diff --git a/internal/bashupgrade/bashupgrade_integration_test.go b/internal/bashupgrade/bashupgrade_integration_test.go deleted file mode 100644 index 7b1de7c33..000000000 --- a/internal/bashupgrade/bashupgrade_integration_test.go +++ /dev/null @@ -1,271 +0,0 @@ -//go:build integration - -package bashupgrade - -import ( - "encoding/json" - "errors" - "io/fs" - "os" - "path/filepath" - "reflect" - "strings" - "testing" -) - -// ownershipRefusals are the repository-setup finding codes that mean the binary -// refused (or could not prove) docket ownership of the Bash-made metadata branch. -// Any of them on a saved case is a binary defect per the spec's "When the binary is -// wrong" rule, never a guide step. -var ownershipRefusals = []string{ - "metadata-root-foreign", "metadata-root-unresolved", "metadata-ownership-unverified", - "metadata-presence-unknown", "docket-dir-foreign", -} - -// TestIntegrationBashUpgradeOwnership requires every saved Bash-made docket branch -// to be accepted as docket-owned by both ownership checks. repository prepare and -// repository check decide ownership with the quick structural check (one -// parentless root, no history shared with the integration branch); the full proof, -// which also reads seed receipts and compares the root's contents against the -// integration history, runs only in repository init and migrate, so the test -// reaches it through the unauthorized migrate preview. -func TestIntegrationBashUpgradeOwnership(t *testing.T) { - for _, tag := range savedTags(t) { - t.Run(tag, func(t *testing.T) { - c := restoreCase(t, tag) - if got, want := listRecords(t, c), readRecords(t, tag); !reflect.DeepEqual(got, want) { - t.Fatalf("records.txt disagrees with the saved bundle\n got %v\nwant %v", got, want) - } - for _, args := range [][]string{{"repository", "prepare", "--json"}, {"repository", "check", "--json"}} { - r := c.run(t, c.Clone, c.Docket, args...) - if r.Stdout == "" { - t.Fatalf("%s produced no JSON (code %d); stderr:\n%s", strings.Join(args, " "), r.Code, r.Stderr) - } - for _, f := range findingCodes(t, r.Stdout) { - for _, bad := range ownershipRefusals { - if f.Code == bad { - t.Fatalf("BLOCKED: %s refused the Bash-made docket branch (%s)\nstdout:\n%s\nstderr:\n%s", - strings.Join(args, " "), f.Code, r.Stdout, r.Stderr) - } - } - } - // prepare must adopt the Bash clone (applied or no-op); check exits - // non-zero whenever it reports findings, which the guide handles later. - if args[1] == "prepare" && r.Code != 0 { - t.Fatalf("repository prepare did not adopt the restored Bash clone (code %d)\nstdout:\n%s\nstderr:\n%s", r.Code, r.Stdout, r.Stderr) - } - t.Logf("%s exit %d\nstdout:\n%s\nstderr:\n%s", strings.Join(args, " "), r.Code, r.Stdout, r.Stderr) - } - assertMigrateAcceptsOwnership(t, c) - }) - } -} - -// assertMigrateAcceptsOwnership runs the unauthorized repository migrate preview on -// the adopted case. migrate routes through the full ownership proof (receipt and -// content equivalence), so on an already-migrated Bash case it must report the -// no-op, never refuse the branch as unverified. The preview writes nothing: it is -// not authorized, and prepare has already attached the .docket worktree. -func assertMigrateAcceptsOwnership(t *testing.T, c *upgradeCase) { - t.Helper() - r := c.run(t, c.Clone, c.Docket, "repository", "migrate", "--json") - t.Logf("repository migrate --json exit %d\nstdout:\n%s\nstderr:\n%s", r.Code, r.Stdout, r.Stderr) - var doc struct { - Result string `json:"result"` - RepositoryState string `json:"repository_state"` - } - if err := json.Unmarshal([]byte(r.Stdout), &doc); err != nil { - t.Fatalf("repository migrate produced no JSON (code %d): %v\nstderr:\n%s", r.Code, err, r.Stderr) - } - if r.Code != 0 || doc.Result != "no-op" { - t.Fatalf("BLOCKED: repository migrate's full ownership proof did not accept the Bash-made docket branch "+ - "(code %d, result %q, state %q)\nstdout:\n%s\nstderr:\n%s", r.Code, doc.Result, doc.RepositoryState, r.Stdout, r.Stderr) - } -} - -// TestIntegrationBashUpgradeGuideShape keeps the guide and the step registry in step -// both ways, and refuses an unmarked block that runs docket commands. -func TestIntegrationBashUpgradeGuideShape(t *testing.T) { - src := readGuide(t) - g, err := parseGuide(src) - if err != nil { - t.Fatal(err) - } - marked := map[string]bool{} - for _, s := range g.Steps { - marked[s.Name] = true - if _, ok := stepRegistry[s.Name]; !ok { - t.Errorf("guide step %q (line %d) is neither executed nor mirrored by the test", s.Name, s.Line) - } - } - for name := range stepRegistry { - if !marked[name] { - t.Errorf("test registry step %q has no marked block in the guide", name) - } - } - for _, f := range g.Unmarked { - if cmds := docketCommandLines(f.Body); len(cmds) > 0 { - t.Errorf("unmarked fenced block at line %d runs docket commands %q; mark it as an upgrade step", f.Line, cmds) - } - } - if len(g.Steps) < len(stepRegistry) || len(stepRegistry) == 0 { - t.Fatalf("population floor: %d marked steps, %d registry entries", len(g.Steps), len(stepRegistry)) - } -} - -// TestIntegrationBashUpgradeGuide runs the guide end to end on every saved case and -// requires a clean, writable repository with every record intact. Across the cases, -// every row of the guide's finding and settings tables must have been observed, so -// the tables carry no claim the test never saw. -func TestIntegrationBashUpgradeGuide(t *testing.T) { - src := readGuide(t) - seenFindings := map[string]bool{} - seenSettings := map[string]bool{} - dispatchRemoved := false - repoAgentShadow, repoSettingsSeen := false, false - for _, tag := range savedTags(t) { - t.Run(tag, func(t *testing.T) { - c := restoreCase(t, tag) - before := listRecords(t, c) - st := runGuide(t, c) - - // Both saved installs carry Bash skill links the installer will not take - // over, so the first run always conflicts and the remedy always runs. - if len(st.Conflicts) == 0 { - t.Fatalf("first install reported no conflict (attempts: %+v)", st.InstallAttempts) - } - if len(st.InstallAttempts) < 2 { - t.Fatalf("the remedy did not lead to a second install run") - } - assertCleanEndState(t, c) - if _, err := os.Lstat(filepath.Join(c.Home, ".cursor", "rules", "docket-dispatch.mdc")); !errors.Is(err, fs.ErrNotExist) { - t.Errorf("Bash's user-level Cursor rule ~/.cursor/rules/docket-dispatch.mdc is still there after the guide (%v)", err) - } - assertRecordsSurvive(t, c, before) - if after, _ := os.ReadFile(filepath.Join(c.Clone, "CLAUDE.md")); strings.Contains(string(after), bashDispatchSignature) { - t.Errorf("the repository CLAUDE.md still carries Bash docket's dispatch block (it runs docket.sh) after the guide") - } - if fi, err := os.Lstat(filepath.Join(c.Clone, ".cursor", "rules", "docket-dispatch.mdc")); err != nil || !fi.Mode().IsRegular() { - t.Errorf("the repository has no .cursor/rules/docket-dispatch.mdc after the guide (%v)", err) - } - dispatchRemoved = dispatchRemoved || st.DispatchBlockRemoved - repoAgentShadow = repoAgentShadow || st.RepoAgentFilesShadow > 0 - repoSettingsSeen = repoSettingsSeen || st.RepoSettingsSeen - assertWritable(t, c) - for _, f := range st.Observed["repo-check"] { - seenFindings[f.Code] = true - } - for _, p := range st.Settings { - seenSettings[p] = true - } - }) - } - if t.Failed() { - return - } - if !dispatchRemoved { - t.Errorf("the guide's dispatch-block step removed no block on any saved case") - } - if !repoAgentShadow { - t.Errorf("the guide's repo-agent-files step found no repository agent file hiding an installed agent on any saved case") - } - if !repoSettingsSeen { - t.Errorf("the guide names the repository's .claude/settings.local.json, which no saved case carries") - } - for code := range findingTable(t, src) { - if !seenFindings[code] { - t.Errorf("the guide's finding table lists %s, which no saved case reported", code) - } - } - for _, row := range settingTable(t, src) { - for _, p := range row.Patterns { - if !seenSettings[p] { - t.Errorf("the guide's settings table lists %s, which no saved case reported", p) - } - } - } -} - -// assertCleanEndState: install check (for every harness the guide installs), -// repository check and status all clean. -func assertCleanEndState(t *testing.T, c *upgradeCase) { - t.Helper() - for _, args := range [][]string{{"--json", "install", "check"}, {"--json", "repository", "check"}} { - r := c.run(t, c.Clone, "docket", args...) - if r.Code != 0 { - t.Errorf("docket %s exited %d\nstdout:\n%s\nstderr:\n%s", strings.Join(args, " "), r.Code, r.Stdout, r.Stderr) - continue - } - if args[1] == "install" { - var doc struct { - Harnesses []string `json:"harnesses"` - } - if err := json.Unmarshal([]byte(r.Stdout), &doc); err != nil { - t.Errorf("decode install check JSON: %v\n%s", err, r.Stdout) - } - have := map[string]bool{} - for _, h := range doc.Harnesses { - have[h] = true - } - for _, h := range guideHarnesses { - if !have[h] { - t.Errorf("docket install check reports harnesses %v; the guide installs %s", doc.Harnesses, h) - } - } - } - for _, f := range findingCodes(t, r.Stdout) { - if f.Severity == "error" || f.Severity == "warning" { - t.Errorf("docket %s still reports %s (%s)", strings.Join(args, " "), f.Code, f.Severity) - } - } - } - r := c.run(t, c.Clone, "docket", "--json", "status") - for _, f := range findingCodes(t, r.Stdout) { - if f.Severity == "error" { - t.Errorf("docket status still reports error %s", f.Code) - } - } -} - -// assertRecordsSurvive: every record that existed before the upgrade is still at the -// same path on the same branch at origin. -func assertRecordsSurvive(t *testing.T, c *upgradeCase, before []string) { - t.Helper() - if len(before) == 0 { - t.Fatal("population floor: no records before the upgrade") - } - for _, rec := range before { - branch, path, ok := strings.Cut(rec, ":") - if !ok { - t.Fatalf("malformed record entry %q", rec) - } - if r := c.run(t, c.Origin, "git", "cat-file", "-e", branch+":"+path); r.Code != 0 { - t.Errorf("record %s did not survive the upgrade", rec) - } - } -} - -// assertWritable: a new change can be created and shows on the re-rendered board. -func assertWritable(t *testing.T, c *upgradeCase) { - t.Helper() - const title = "Upgrade proof stub" - req, err := json.Marshal(map[string]string{ - "request_id": "bash-upgrade-proof-0001", "title": title, "type": "chore", "priority": "low", - "why": "Prove the upgraded repository is writable.", "what_changes": "Nothing; this is a probe.", - "out_of_scope": "Everything else.", - }) - if err != nil { - t.Fatal(err) - } - reqPath := filepath.Join(c.Root, "change-create.json") - if err := os.WriteFile(reqPath, req, 0o644); err != nil { - t.Fatal(err) - } - if r := c.run(t, c.Clone, "docket", "change", "create", "--request", reqPath); r.Code != 0 { - t.Fatalf("change create exited %d\nstdout:\n%s\nstderr:\n%s", r.Code, r.Stdout, r.Stderr) - } - board := c.mustGit(t, c.Origin, "show", "docket:"+changesDir(t, c)+"/BOARD.md") - if !strings.Contains(board, title) { - t.Fatalf("the new change %q is not on the docket branch's board:\n%s", title, board) - } -} diff --git a/internal/bashupgrade/doc.go b/internal/bashupgrade/doc.go deleted file mode 100644 index aef24acbf..000000000 --- a/internal/bashupgrade/doc.go +++ /dev/null @@ -1,6 +0,0 @@ -// Package bashupgrade holds the temporary proof that docs/release/upgrading-from-bash.md -// works: integration tests restore saved Bash docket v0.9.2/v0.9.3 installs from -// testdata/bash-upgrade/ and run the guide's own marked steps against the binary -// built from this checkout. The package has no non-test code beyond this file and is -// deleted, with testdata/bash-upgrade/, when stable v1.0.0 ships. -package bashupgrade diff --git a/internal/bashupgrade/registry_test.go b/internal/bashupgrade/registry_test.go deleted file mode 100644 index 49aba39a4..000000000 --- a/internal/bashupgrade/registry_test.go +++ /dev/null @@ -1,1549 +0,0 @@ -package bashupgrade - -// The step registry: one action per `` block in -// docs/release/upgrading-from-bash.md. runGuide drives the guide's marked blocks in -// guide order through these actions against a restored saved case. -// -// Three kinds of action keep the guide honest: -// - run actions execute only the block's own text (`/bin/sh -e -c `) and -// never add a command the guide does not show; -// - observe actions run the block's command with --json to read its findings, -// and check that the guide's tables explain every one; -// - mirror actions do by hand exactly what the block and its prose tell the reader -// to do (download, edit a file, delete paths), after asserting the guide text -// names the object they act on. -// -// Each action also asserts the claims the guide's prose makes about that step, so a -// change in the binary's behavior turns the test red instead of leaving the guide -// silently wrong. - -import ( - "bytes" - "crypto/sha256" - "encoding/hex" - "encoding/json" - "errors" - "fmt" - "io/fs" - "os" - "path/filepath" - "regexp" - "sort" - "strings" - "testing" - - "go.yaml.in/yaml/v3" -) - -// runState carries what earlier steps observed to later ones. InstallAttempts holds -// every install hand-off in order; Conflicts the paths the first failed attempt -// named; Observed the finding codes each observe step saw. -type runState struct { - InstallAttempts []cmdResult - Conflicts []string - Observed map[string][]findingRef - - Guide string // the full guide text, for prose and table checks - Cwd string // the reader's terminal directory after the last block - DownloadDir string // where install-binary downloaded install.sh - InstallLine string // install-binary's installer invocation, re-run by takeover-remedy - InstallHarnesses []string // the --harness names of InstallLine, in line order - CheckJSON string // repo-check's --json stdout - Settings []string // settings-table patterns config-cleanup matched to a finding - Removed []string // settings config-cleanup removed from .docket.yml - - DispatchBlockRemoved bool // dispatch-block found and removed the CLAUDE.md block - RepoAgentFilesShadow int // repository agent files that hid an installed agent before repo-agent-files - RepoSettingsSeen bool // the repository carried migrate's .claude/settings.local.json -} - -type stepAction func(t *testing.T, c *upgradeCase, st *runState, body string) - -var stepRegistry = map[string]stepAction{ - "install-binary": mirrorInstallBinary, - "cursor-takeover-remedy": mirrorCursorTakeoverRemedy, - "takeover-remedy": mirrorTakeoverRemedy, - "global-config-cleanup": mirrorGlobalConfigCleanup, - "confirm-install": runConfirmInstall, - "repo-prepare": runRepoPrepare, - "repo-check": observeRepoCheck, - "fix-gitignore": mirrorFixGitignore, - "config-cleanup": mirrorConfigCleanup, - "commit-fixes": runCommitFixes, - "configure-tests": runPlain, - "configure-harnesses": runPlain, - "commit-config": runCommit, - "repair-preview": observeRepairPreview, - "repair-apply": runRepairApply, - "repo-confirm": runRepoConfirm, - "dispatch-block": mirrorDispatchBlock, - "choose-harnesses": runChooseHarnesses, - "leftovers": mirrorLeftovers, - "repo-agent-files": runRepoAgentFiles, -} - -// Guide headings the table checks anchor on. -const ( - findingTableHeading = "## 5. Upgrade each repository" - settingTableHeading = "## 6. Settings that changed" -) - -// settingCodes are the finding codes the settings table must explain. -var settingCodes = map[string]bool{ - "deferred-capability-requested": true, - "obsolete-setting": true, - "inert-setting": true, -} - -// guidePath is the guide under test: $DOCKET_BASH_UPGRADE_GUIDE when set (the -// by-hand mutation-check seam), else the committed guide. -func guidePath(t *testing.T) string { - t.Helper() - if p := os.Getenv("DOCKET_BASH_UPGRADE_GUIDE"); p != "" { - return p - } - return filepath.Join(repoRoot(t), "docs", "release", "upgrading-from-bash.md") -} - -func readGuide(t *testing.T) string { - t.Helper() - b, err := os.ReadFile(guidePath(t)) - if err != nil { - t.Fatalf("read guide: %v", err) - } - return string(b) -} - -// runGuide runs every marked step of the guide, in guide order, against c. -func runGuide(t *testing.T, c *upgradeCase) *runState { - t.Helper() - src := readGuide(t) - g, err := parseGuide(src) - if err != nil { - t.Fatalf("parse guide: %v", err) - } - st := &runState{Observed: map[string][]findingRef{}, Guide: src, Cwd: c.Home} - for _, s := range g.Steps { - act, ok := stepRegistry[s.Name] - if !ok { - t.Fatalf("guide step %q (line %d) has no registry action", s.Name, s.Line) - } - body, err := substitutePlaceholders(s.Body, map[string]string{"repo": c.Clone}) - if err != nil { - t.Fatalf("guide step %q (line %d): %v", s.Name, s.Line, err) - } - t.Logf("guide step %s (line %d)", s.Name, s.Line) - act(t, c, st, body) - } - return st -} - -// ---- shared helpers --------------------------------------------------------------- - -func blockLines(body string) []string { - var out []string - for _, l := range strings.Split(body, "\n") { - if strings.TrimSpace(l) != "" { - out = append(out, strings.TrimRight(l, " \t")) - } - } - return out -} - -// expandHome expands a leading ~ the way the reader's shell does. -func (c *upgradeCase) expandHome(p string) string { - if p == "~" { - return c.Home - } - if strings.HasPrefix(p, "~/") { - return filepath.Join(c.Home, p[2:]) - } - return p -} - -// trackCd follows every `cd ` segment of a block so the next block starts where -// the reader's terminal is. -func (c *upgradeCase) trackCd(st *runState, body string) { - for _, line := range blockLines(body) { - for _, seg := range strings.Split(line, "&&") { - f := strings.Fields(seg) - if len(f) == 2 && f[0] == "cd" { - st.Cwd = c.expandHome(f[1]) - } - } - } -} - -// runBlock executes the block's own text with /bin/sh -e in the reader's current -// directory and fails the test on a non-zero exit. -func runBlock(t *testing.T, c *upgradeCase, st *runState, body string) cmdResult { - t.Helper() - r := c.run(t, st.Cwd, "/bin/sh", "-e", "-c", body) - if r.Code != 0 { - t.Fatalf("guide block exited %d (in %s)\nblock:\n%s\nstdout:\n%s\nstderr:\n%s", r.Code, st.Cwd, body, r.Stdout, r.Stderr) - } - c.trackCd(st, body) - return r -} - -func mustContain(t *testing.T, what, text, want string) { - t.Helper() - if !strings.Contains(text, want) { - t.Fatalf("%s does not contain %q:\n%s", what, want, text) - } -} - -// guideHarnesses are the harnesses the guide's combined path covers; the test runs -// every saved case once, through all of them. -var guideHarnesses = []string{"claude", "cursor"} - -// installLineHarnesses parses the guide's installer invocation: exactly `sh install.sh` -// followed by one or more `--harness ` pairs, each name one the downloader -// accepts and none repeated. It returns the names in line order. -func installLineHarnesses(line string) ([]string, bool) { - f := strings.Fields(line) - if len(f) < 4 || len(f)%2 != 0 || f[0] != "sh" || f[1] != "install.sh" { - return nil, false - } - known := map[string]bool{"claude": true, "codex": true, "cursor": true, "opencode": true} - seen := map[string]bool{} - var out []string - for i := 2; i < len(f); i += 2 { - if f[i] != "--harness" || !known[f[i+1]] || seen[f[i+1]] { - return nil, false - } - seen[f[i+1]] = true - out = append(out, f[i+1]) - } - return out, true -} - -// containsProse reports whether text contains want once every whitespace run in both -// is collapsed to one space, so a re-flowed guide paragraph still matches the claim. -func containsProse(text, want string) bool { - return strings.Contains(strings.Join(strings.Fields(text), " "), strings.Join(strings.Fields(want), " ")) -} - -func mustContainProse(t *testing.T, what, text, want string) { - t.Helper() - if !containsProse(text, want) { - t.Fatalf("%s does not contain %q (whitespace collapsed):\n%s", what, want, text) - } -} - -// pendingPathsLead introduces the paths `docket repository configure-harnesses` asks -// the reader to review and commit, in its human output. -const pendingPathsLead = "review and commit the pending paths: " - -// pendingPathsFrom returns, sorted, the paths after pendingPathsLead up to the end of -// that line, or nil when the output carries no such list. -func pendingPathsFrom(out string) []string { - _, rest, ok := strings.Cut(out, pendingPathsLead) - if !ok { - return nil - } - line, _, _ := strings.Cut(rest, "\n") - var paths []string - for _, p := range strings.Split(line, ",") { - if p = strings.TrimSpace(p); p != "" { - paths = append(paths, p) - } - } - sort.Strings(paths) - return paths -} - -// sameSet reports whether a and b hold the same strings, ignoring order. -func sameSet(a, b []string) bool { - x, y := append([]string(nil), a...), append([]string(nil), b...) - sort.Strings(x) - sort.Strings(y) - return strings.Join(x, "\x00") == strings.Join(y, "\x00") && len(x) == len(y) -} - -// findingObjects decodes one JSON document and returns, in document order, every -// object carrying string code and severity fields (the shape findingCodes reads). -func findingObjects(t *testing.T, stdout string) []map[string]any { - t.Helper() - var doc any - if err := json.Unmarshal([]byte(stdout), &doc); err != nil { - t.Fatalf("decode JSON output: %v\n%s", err, stdout) - } - var out []map[string]any - var walk func(v any) - walk = func(v any) { - switch x := v.(type) { - case map[string]any: - _, okCode := x["code"].(string) - _, okSev := x["severity"].(string) - if okCode && okSev { - out = append(out, x) - } - keys := make([]string, 0, len(x)) - for k := range x { - keys = append(keys, k) - } - sort.Strings(keys) - for _, k := range keys { - walk(x[k]) - } - case []any: - for _, e := range x { - walk(e) - } - } - } - walk(doc) - return out -} - -func str(m map[string]any, k string) string { - s, _ := m[k].(string) - return s -} - -// guideTable returns the body rows (cells trimmed) of the first table after heading, -// stopping at the next "## " heading. -func guideTable(t *testing.T, src, heading string) [][]string { - t.Helper() - lines := strings.Split(src, "\n") - start := -1 - for i, l := range lines { - if strings.TrimSpace(l) == heading { - start = i - break - } - } - if start < 0 { - t.Fatalf("guide has no %q heading", heading) - } - var rows [][]string - inTable := false - for _, l := range lines[start+1:] { - if strings.HasPrefix(l, "## ") { - break - } - if !strings.HasPrefix(l, "|") { - if inTable { - break - } - continue - } - if !inTable { - inTable = true - continue // header row - } - cells := strings.Split(strings.Trim(strings.TrimSpace(l), "|"), "|") - for i := range cells { - cells[i] = strings.TrimSpace(cells[i]) - } - if strings.HasPrefix(cells[0], "---") { - continue - } - rows = append(rows, cells) - } - if len(rows) == 0 { - t.Fatalf("guide has no table under %q", heading) - } - return rows -} - -func backticked(s string) []string { - var out []string - for _, m := range regexp.MustCompile("`([^`]+)`").FindAllStringSubmatch(s, -1) { - out = append(out, m[1]) - } - return out -} - -// findingTable maps each finding code in the section-5 table to its row. -func findingTable(t *testing.T, src string) map[string][]string { - t.Helper() - out := map[string][]string{} - for _, row := range guideTable(t, src, findingTableHeading) { - codes := backticked(row[0]) - if len(codes) != 1 || len(row) != 3 { - t.Fatalf("finding table row %q must name exactly one `code` and have 3 cells", strings.Join(row, " | ")) - } - out[codes[0]] = row - } - return out -} - -type settingRow struct { - Patterns []string - Severity string // error | warning | notice - Does, Fix, Raw string -} - -func settingTable(t *testing.T, src string) []settingRow { - t.Helper() - var out []settingRow - for _, row := range guideTable(t, src, settingTableHeading) { - if len(row) != 3 { - t.Fatalf("settings table row %q must have 3 cells", strings.Join(row, " | ")) - } - pats := backticked(row[0]) - word := strings.ToLower(strings.TrimRight(strings.Fields(row[1])[0], ":.")) - if len(pats) == 0 || (word != "error" && word != "warning" && word != "notice") { - t.Fatalf("settings table row %q needs `setting` names and a Error/Warning/Notice first word", strings.Join(row, " | ")) - } - out = append(out, settingRow{Patterns: pats, Severity: word, Does: row[1], Fix: row[2], Raw: strings.Join(row, " | ")}) - } - return out -} - -// settingMatches reports whether a dotted setting name matches a table pattern, -// where a segment stands for any one segment. -func settingMatches(pattern, field string) bool { - p, f := strings.Split(pattern, "."), strings.Split(field, ".") - if len(p) != len(f) { - return false - } - for i := range p { - if strings.HasPrefix(p[i], "<") && strings.HasSuffix(p[i], ">") { - continue - } - if p[i] != f[i] { - return false - } - } - return true -} - -// snapshotTree records every path under dir with its link target or content hash. -func snapshotTree(t *testing.T, dir string) map[string]string { - t.Helper() - out := map[string]string{} - err := filepath.WalkDir(dir, func(p string, d fs.DirEntry, err error) error { - if err != nil { - return err - } - switch { - case d.Type()&fs.ModeSymlink != 0: - target, err := os.Readlink(p) - if err != nil { - return err - } - out[p] = "link:" + target - case d.Type().IsRegular(): - b, err := os.ReadFile(p) - if err != nil { - return err - } - sum := sha256.Sum256(b) - out[p] = "file:" + hex.EncodeToString(sum[:]) - default: - out[p] = "dir" - } - return nil - }) - if err != nil { - t.Fatalf("snapshot %s: %v", dir, err) - } - return out -} - -// harnessHomesSnapshot snapshots every harness folder the guide's install writes. -func harnessHomesSnapshot(t *testing.T, c *upgradeCase) map[string]string { - t.Helper() - out := map[string]string{} - for _, d := range []string{".claude", ".cursor"} { - for k, v := range snapshotTree(t, filepath.Join(c.Home, d)) { - out[k] = v - } - } - return out -} - -func gitRev(t *testing.T, c *upgradeCase, ref string) string { - t.Helper() - return strings.TrimSpace(c.mustGit(t, c.Origin, "rev-parse", ref)) -} - -// ---- section 3 and 4: the machine install ------------------------------------------ - -// repairFollowsProse is the guide's statement that the repair brings the local .docket -// copy up to the repaired commit. It is matched with whitespace collapsed, so a -// re-flowed paragraph still matches. -const repairFollowsProse = "and brings your local `.docket` folder up to the repaired commit." - -// releaseVerifiedProse is the guide's statement that the download and checksum -// lines rest on the release verification, not on this test. -const releaseVerifiedProse = "The download and checksum lines are checked by the release's own verification, not by\nthis guide's test." - -// mirrorInstallBinary mirrors the release download block. The download and the -// checksum check need the published release, which the release verification proves -// (and the guide says so); here every line must be one of those known shapes, and the -// installer invocation is mirrored by installHandoff. -func mirrorInstallBinary(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - mustContain(t, "guide", st.Guide, releaseVerifiedProse) - var sawInstallSh, sawChecksums, sawVerify bool - for _, line := range blockLines(body) { - f := strings.Fields(line) - switch { - case len(f) == 6 && f[0] == "mkdir" && f[1] == "-p" && f[3] == "&&" && f[4] == "cd" && f[2] == f[5]: - dir := c.expandHome(f[2]) - if err := os.MkdirAll(dir, 0o755); err != nil { - t.Fatal(err) - } - st.Cwd = dir - st.DownloadDir = dir - case strings.HasPrefix(line, "VERSION="): - case f[0] == "curl" && strings.HasSuffix(line, `/install.sh"`): - sawInstallSh = true - case f[0] == "curl" && strings.HasSuffix(line, `/checksums.txt"`): - sawChecksums = true - case strings.Contains(line, "checksums.txt") && strings.Contains(line, "shasum -a 256 -c"): - sawVerify = true - case f[0] == "sh": - hs, ok := installLineHarnesses(line) - if !ok || !sameSet(hs, guideHarnesses) { - t.Fatalf("install-binary: installer line %q must be `sh install.sh` with one --harness per covered harness %v", line, guideHarnesses) - } - st.InstallLine, st.InstallHarnesses = line, hs - default: - t.Fatalf("install-binary: line %q is not a shape the test mirrors", line) - } - } - if st.DownloadDir == "" || !sawInstallSh || !sawChecksums || !sawVerify || st.InstallLine == "" { - t.Fatalf("install-binary block must make a download folder, fetch install.sh and checksums.txt, verify with shasum -a 256 -c, and run the installer for every covered harness:\n%s", body) - } - installHandoff(t, c, st) -} - -// installHandoff mirrors internal/release/downloader/install.sh from the point it -// has a verified binary: stage it beside the destination, run the staged binary's -// `install` with one `--harness` per harness on the guide's installer line, and -// only on success move it into place, place the relative dckt alias beside it, -// write the ownership record (naming the alias), and run `docket install check`. -func installHandoff(t *testing.T, c *upgradeCase, st *runState) { - t.Helper() - dest := filepath.Join(c.BinDir, "docket") - alias := filepath.Join(c.BinDir, "dckt") - for _, p := range []string{dest, alias} { - if _, err := os.Lstat(p); err == nil { - t.Fatalf("%s already exists; the mirror covers only the downloader's fresh-install path", p) - } - } - if err := os.MkdirAll(c.BinDir, 0o755); err != nil { - t.Fatal(err) - } - stage := filepath.Join(c.BinDir, ".docket-stage") - bin, err := os.ReadFile(c.Docket) - if err != nil { - t.Fatal(err) - } - if err := os.WriteFile(stage, bin, 0o755); err != nil { - t.Fatal(err) - } - args := []string{"install"} - for _, h := range st.InstallHarnesses { - args = append(args, "--harness", h) - } - before := harnessHomesSnapshot(t, c) - // The downloader runs the staged binary in human mode, so the reader sees these - // lines; the guide quotes them. - r := c.run(t, st.DownloadDir, stage, args...) - st.InstallAttempts = append(st.InstallAttempts, r) - human := r.Stdout + r.Stderr - if r.Code != 0 { - // Guide: "this first run stops with `install: invalid-state` and a list of - // `conflict` lines". - mustContain(t, "guide", st.Guide, "`install: invalid-state`") - mustContain(t, "install output", human, "install: invalid-state") - // A failed run changes nothing, so a --json re-run reads the same conflict - // set in a form the test can parse; the human output must list each path on - // a conflict line. - j := c.run(t, st.DownloadDir, stage, append([]string{"--json"}, args...)...) - _ = os.Remove(stage) - var conflicts []string - var doc struct { - Result string `json:"result"` - Actions []struct { - Op, Path, Detail string - } `json:"actions"` - } - if err := json.Unmarshal([]byte(j.Stdout), &doc); err != nil { - t.Fatalf("install --json output: %v\nstdout:\n%s\nstderr:\n%s", err, j.Stdout, j.Stderr) - } - for _, a := range doc.Actions { - if a.Op == "conflict" { - conflicts = append(conflicts, a.Path) - } - } - if j.Code == 0 || len(conflicts) == 0 || doc.Result != "invalid-state" { - t.Fatalf("install exited %d (json %d) with result %q and %d conflict paths\nhuman:\n%s\njson:\n%s", r.Code, j.Code, doc.Result, len(conflicts), human, j.Stdout) - } - for _, p := range conflicts { - if !humanConflictLine(human, p) { - t.Errorf("install's human output has no `conflict` line naming %s:\n%s", p, human) - } - } - if t.Failed() { - t.FailNow() - } - if len(st.InstallAttempts) > 1 { - t.Fatalf("install still conflicts after the guide's remedy: %v", conflicts) - } - // Guide: "The run changes nothing and leaves no docket command behind." - if _, err := os.Lstat(dest); err == nil { - t.Fatalf("a failed install left %s behind", dest) - } - if after := harnessHomesSnapshot(t, c); !mapsEqual(before, after) { - t.Fatalf("a failed install changed ~/.claude or ~/.cursor") - } - st.Conflicts = conflicts - return - } - // Guide: "This time the installer reports `install: applied`." - mustContain(t, "guide", st.Guide, "`install: applied`") - mustContain(t, "install output", human, "install: applied") - if err := os.Rename(stage, dest); err != nil { - t.Fatal(err) - } - // The downloader's fresh-install alias step: `ln -s docket "$bin_dir/dckt"`. - if err := os.Symlink("docket", alias); err != nil { - t.Fatal(err) - } - sum := sha256.Sum256(bin) - recDir := filepath.Join(c.Home, ".local", "state", "docket") - if err := os.MkdirAll(recDir, 0o755); err != nil { - t.Fatal(err) - } - rec := "path=" + dest + "\nversion=development\nalias=" + alias + "\nsha256=" + hex.EncodeToString(sum[:]) + "\n" - if err := os.WriteFile(filepath.Join(recDir, "release-binary.record"), []byte(rec), 0o644); err != nil { - t.Fatal(err) - } - if chk := c.run(t, st.DownloadDir, dest, "install", "check"); chk.Code != 0 { - t.Fatalf("install check after install exited %d\nstdout:\n%s\nstderr:\n%s", chk.Code, chk.Stdout, chk.Stderr) - } -} - -// humanConflictLine reports whether human-mode install output has a line whose first -// word is "conflict" and which names path. -func humanConflictLine(out, path string) bool { - for _, l := range strings.Split(out, "\n") { - f := strings.Fields(l) - if len(f) > 0 && strings.TrimRight(f[0], ":") == "conflict" && strings.Contains(l, path) { - return true - } - } - return false -} - -func mapsEqual(a, b map[string]string) bool { - if len(a) != len(b) { - return false - } - for k, v := range a { - if b[k] != v { - return false - } - } - return true -} - -// mirrorTakeoverRemedy runs the block's delete commands, proves they removed every -// path the installer named, and re-runs the installer the way the block's last line -// does. -func mirrorTakeoverRemedy(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - lines := blockLines(body) - if len(lines) < 2 || lines[len(lines)-1] != st.InstallLine { - t.Fatalf("takeover-remedy must end by re-running %q:\n%s", st.InstallLine, body) - } - mustContain(t, "takeover-remedy block", body, "~/.claude/skills/docket-*") - for _, l := range lines[:len(lines)-1] { - if !strings.HasPrefix(l, "rm ") { - t.Fatalf("takeover-remedy line %q is not a delete the test mirrors", l) - } - } - if len(st.Conflicts) == 0 { - t.Logf("takeover-remedy: the first install had no conflict; nothing to do") - return - } - // Guide: every docket-* link under ~/.claude/skills/ is a conflict; every agent - // file except v0.9.3's docket-plan-writer.md is taken over. - conflict := map[string]bool{} - for _, p := range st.Conflicts { - conflict[p] = true - } - links, _ := filepath.Glob(filepath.Join(c.Home, ".claude", "skills", "docket-*")) - for _, l := range links { - if !conflict[l] { - t.Errorf("guide says every ~/.claude/skills/docket-* link conflicts, but %s did not", l) - } - } - planWriter := filepath.Join(c.Home, ".claude", "agents", "docket-plan-writer.md") - for _, p := range st.Conflicts { - if strings.HasPrefix(p, filepath.Join(c.Home, ".claude", "agents")+"/") && p != planWriter { - t.Errorf("guide says agent files are taken over, but %s conflicted", p) - } - } - if conflict[planWriter] != (c.Tag == "v0.9.3") { - t.Errorf("guide says docket-plan-writer.md conflicts on v0.9.3 only; %s conflict = %v", c.Tag, conflict[planWriter]) - } - r := c.run(t, st.DownloadDir, "/bin/sh", "-e", "-c", strings.Join(lines[:len(lines)-1], "\n")) - if r.Code != 0 { - t.Fatalf("takeover-remedy deletes exited %d\nstdout:\n%s\nstderr:\n%s", r.Code, r.Stdout, r.Stderr) - } - for _, p := range st.Conflicts { - if _, err := os.Lstat(p); !errors.Is(err, fs.ErrNotExist) { - t.Errorf("takeover-remedy left the conflict path %s in place", p) - } - } - if t.Failed() { - t.FailNow() - } - installHandoff(t, c, st) - if last := st.InstallAttempts[len(st.InstallAttempts)-1]; last.Code != 0 { - t.Fatalf("the install after takeover-remedy exited %d", last.Code) - } -} - -// The Cursor paths the guide's cursor-takeover-remedy block deletes, and the guide's -// claims about them. -const ( - cursorSkillsGlob = "~/.cursor/skills/docket-*" - cursorPlanWriter = "~/.cursor/agents/docket-plan-writer.md" - cursorUserRule = "~/.cursor/rules/docket-dispatch.mdc" - cursorRuleNoConflictProse = "On `v0.9.2` it is not reported as a conflict; the block below deletes it either way." - cursorRemedySkipProse = "If you don't use Cursor, skip this block." - cursorSandboxLink = "](../install/cursor.md)" -) - -// mirrorCursorTakeoverRemedy runs the block's Cursor deletes after proving the first -// install's Cursor conflicts are exactly the ones the guide lists: every -// ~/.cursor/skills/docket-* link, plus, on v0.9.3 only, docket-plan-writer.md and Bash's -// user-level rule. On v0.9.2 the rule is present but no conflict, which is what the -// guide's "not reported as a conflict; the block below deletes it either way" claims: -// the first install fails on the skills conflicts, so the block's rm -f is what removes it. -// The installer re-run stays in takeover-remedy, so this block must come first. -func mirrorCursorTakeoverRemedy(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - lines := blockLines(body) - if len(lines) == 0 { - t.Fatalf("cursor-takeover-remedy block is empty") - } - for _, l := range lines { - if !strings.HasPrefix(l, "rm ") { - t.Fatalf("cursor-takeover-remedy line %q is not a delete the test mirrors; the installer re-run belongs to takeover-remedy", l) - } - } - for _, p := range []string{cursorSkillsGlob, cursorPlanWriter, cursorUserRule} { - mustContain(t, "cursor-takeover-remedy block", body, p) - } - mustContainProse(t, "guide", st.Guide, cursorRuleNoConflictProse) - mustContainProse(t, "guide", st.Guide, cursorRemedySkipProse) - if len(st.Conflicts) == 0 { - t.Fatalf("cursor-takeover-remedy: the first install reported no conflict; the guide says every %s link conflicts", cursorSkillsGlob) - } - links, _ := filepath.Glob(c.expandHome(cursorSkillsGlob)) - if len(links) == 0 { - t.Fatalf("population floor: the saved %s home has no %s link", c.Tag, cursorSkillsGlob) - } - planWriter, rule := c.expandHome(cursorPlanWriter), c.expandHome(cursorUserRule) - want := map[string]bool{} - for _, l := range links { - want[l] = true - } - if c.Tag == "v0.9.3" { - want[planWriter], want[rule] = true, true - } else if _, err := os.Lstat(rule); err != nil { - t.Errorf("guide says the block deletes Bash's rule on %s, but the saved home has no %s: %v", c.Tag, rule, err) - } - got := map[string]bool{} - for _, p := range st.Conflicts { - if strings.HasPrefix(p, filepath.Join(c.Home, ".cursor")+"/") { - got[p] = true - } - } - for p := range want { - if !got[p] { - t.Errorf("guide says %s conflicts on %s; the installer did not report it", p, c.Tag) - } - } - for p := range got { - if !want[p] { - t.Errorf("the installer reported %s as a conflict on %s, which the guide does not list", p, c.Tag) - } - } - if t.Failed() { - t.FailNow() - } - runBlock(t, c, st, body) - for p := range want { - if _, err := os.Lstat(p); !errors.Is(err, fs.ErrNotExist) { - t.Errorf("cursor-takeover-remedy left the conflict path %s in place", p) - } - } -} - -// mirrorGlobalConfigCleanup deletes the marked runtime.bash block from the global -// config, after checking it is the block the guide shows. -func mirrorGlobalConfigCleanup(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - want := blockLines(body) - if len(want) != 4 || want[0] != "# >>> docket (runtime.bash) >>>" || want[1] != "runtime:" || - !strings.HasPrefix(want[2], " bash: ") || want[3] != "# <<< docket (runtime.bash) <<<" { - t.Fatalf("global-config-cleanup block is not the runtime.bash block:\n%s", body) - } - mustContain(t, "guide", st.Guide, "`~/.config/docket/config.yml`") - path := filepath.Join(c.Home, ".config", "docket", "config.yml") - b, err := os.ReadFile(path) - if err != nil { - t.Fatalf("guide says Bash docket left runtime.bash in %s: %v", path, err) - } - lines := strings.Split(string(b), "\n") - start, end := -1, -1 - for i, l := range lines { - switch l { - case want[0]: - start = i - case want[3]: - end = i - } - } - if start < 0 || end != start+3 || lines[start+1] != want[1] || !strings.HasPrefix(lines[start+2], " bash: ") { - t.Fatalf("%s holds no runtime.bash block shaped like the guide's:\n%s", path, b) - } - out := append(append([]string{}, lines[:start]...), lines[end+1:]...) - if err := os.WriteFile(path, []byte(strings.Join(out, "\n")), 0o644); err != nil { - t.Fatal(err) - } -} - -// runConfirmInstall runs the block; the guide promises both commands succeed and -// install check prints no warning. -func runConfirmInstall(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - r := runBlock(t, c, st, body) - for _, l := range strings.Split(r.Stdout+r.Stderr, "\n") { - if strings.HasPrefix(strings.TrimSpace(l), "warning:") { - t.Fatalf("confirm-install printed a warning the guide says it does not:\n%s%s", r.Stdout, r.Stderr) - } - } -} - -// ---- section 5: each repository ---------------------------------------------------- - -func runPlain(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - runBlock(t, c, st, body) -} - -func runRepoPrepare(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - r := runBlock(t, c, st, body) - if st.Cwd != c.Clone { - t.Fatalf("repo-prepare must leave the reader in the repository; cwd %s", st.Cwd) - } - mustContain(t, "repository prepare output", r.Stdout+r.Stderr, "healthy") -} - -// observeRepoCheck runs the check with --json, records its findings, and requires -// the guide's finding table to explain each one. -func observeRepoCheck(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - if strings.TrimSpace(body) != "docket repository check" { - t.Fatalf("repo-check block must be exactly `docket repository check`:\n%s", body) - } - r := c.run(t, st.Cwd, "docket", "--json", "repository", "check") - if r.Code == 0 { - t.Fatalf("guide says the first repository check exits with an error; it exited 0\n%s", r.Stdout) - } - st.CheckJSON = r.Stdout - st.Observed["repo-check"] = findingCodes(t, r.Stdout) - table := findingTable(t, st.Guide) - for _, f := range st.Observed["repo-check"] { - if _, ok := table[f.Code]; !ok { - t.Errorf("repository check reported %s (%s), which the guide's finding table does not explain", f.Code, f.Severity) - } - } -} - -// mirrorFixGitignore replaces the .gitignore docket block with the guide's lines, -// after checking they are exactly the lines the check's remedy printed. -func mirrorFixGitignore(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - want := blockLines(body) - var remedy string - for _, f := range findingObjects(t, st.CheckJSON) { - if str(f, "code") == "committed-ignore-invalid" { - remedy = str(f, "remedy") - } - } - if remedy == "" { - t.Logf("fix-gitignore: repository check did not report committed-ignore-invalid; nothing to do") - return - } - _, printed, ok := strings.Cut(remedy, ":\n") - if !ok || strings.Join(blockLines(printed), "\n") != strings.Join(want, "\n") { - t.Fatalf("the guide's .gitignore block differs from the lines the check printed\nguide:\n%s\ncheck:\n%s", strings.Join(want, "\n"), printed) - } - path := filepath.Join(c.Clone, ".gitignore") - b, err := os.ReadFile(path) - if err != nil { - t.Fatal(err) - } - lines := strings.Split(string(b), "\n") - start, end := -1, -1 - for i, l := range lines { - switch { - case strings.HasPrefix(l, "# docket:start"): - if start >= 0 { - t.Fatalf(".gitignore has two docket:start lines") - } - start = i - case l == "# docket:end": - if end >= 0 { - t.Fatalf(".gitignore has two docket:end lines") - } - end = i - } - } - if start < 0 || end <= start { - t.Fatalf(".gitignore has no well-formed docket block:\n%s", b) - } - out := append(append(append([]string{}, lines[:start]...), want...), lines[end+1:]...) - if err := os.WriteFile(path, []byte(strings.Join(out, "\n")), 0o644); err != nil { - t.Fatal(err) - } -} - -// mirrorConfigCleanup reads `docket status`, requires the settings table to explain -// every setting finding with the same severity, and removes each error and warning -// setting from .docket.yml the way the table's Fix column says. -func mirrorConfigCleanup(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - if strings.TrimSpace(body) != "docket status" { - t.Fatalf("config-cleanup block must be exactly `docket status`:\n%s", body) - } - rows := settingTable(t, st.Guide) - r := c.run(t, st.Cwd, "docket", "--json", "status") - var remove []string - for _, f := range findingObjects(t, r.Stdout) { - if !settingCodes[str(f, "code")] { - continue - } - field := str(f, "field") - if field == "" { - field = str(f, "path") - } - var row *settingRow - for i := range rows { - for _, p := range rows[i].Patterns { - if settingMatches(p, field) { - row = &rows[i] - st.Settings = append(st.Settings, p) - } - } - } - if row == nil { - t.Errorf("docket status reports %s (%s) for %s, which the guide's settings table does not list", str(f, "code"), str(f, "severity"), field) - continue - } - if row.Severity != str(f, "severity") { - t.Errorf("settings table says %s is %s; docket status reports %s", field, row.Severity, str(f, "severity")) - } - checkSettingFix(t, *row, f, field) - if row.Severity == "notice" { - continue - } - if !strings.HasPrefix(str(f, "message"), ".docket.yml:") { - t.Errorf("%s is reported outside .docket.yml (%s); the guide only tells the reader to edit .docket.yml here", field, str(f, "message")) - } - remove = append(remove, field) - } - if t.Failed() { - t.FailNow() - } - if len(remove) == 0 { - t.Logf("config-cleanup: no setting to remove") - return - } - path := filepath.Join(c.Clone, ".docket.yml") - b, err := os.ReadFile(path) - if err != nil { - t.Fatalf("settings to remove %v but no .docket.yml: %v", remove, err) - } - var doc yaml.Node - if err := yaml.Unmarshal(b, &doc); err != nil || len(doc.Content) != 1 { - t.Fatalf("parse .docket.yml: %v", err) - } - for _, field := range remove { - if !removeYAMLKey(doc.Content[0], strings.Split(field, ".")) { - t.Fatalf("config-cleanup: %s is reported but not found in .docket.yml", field) - } - } - var buf bytes.Buffer - enc := yaml.NewEncoder(&buf) - enc.SetIndent(2) - if err := enc.Encode(&doc); err != nil { - t.Fatal(err) - } - if err := os.WriteFile(path, buf.Bytes(), 0o644); err != nil { - t.Fatal(err) - } - st.Removed = remove - // Guide: status reads the pushed .docket.yml, so the edit alone clears nothing. - still := map[string]bool{} - for _, f := range findingObjects(t, c.run(t, st.Cwd, "docket", "--json", "status").Stdout) { - still[str(f, "field")+str(f, "path")] = true - } - for _, field := range remove { - if !still[field] { - t.Errorf("guide says docket status reads the pushed .docket.yml, but the uncommitted edit already cleared %s", field) - } - } -} - -// runCommitFixes commits and pushes the .gitignore and settings fixes, then checks -// the guide's claim that the pushed edit clears every setting it removed. -func runCommitFixes(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - runCommit(t, c, st, body) - if len(st.Removed) == 0 { - return - } - after := c.run(t, st.Cwd, "docket", "--json", "status") - for _, f := range findingObjects(t, after.Stdout) { - code, sev := str(f, "code"), str(f, "severity") - if (settingCodes[code] && sev != "notice") || strings.Contains(code, "config") { - t.Errorf("after pushing the settings fix, docket status still reports %s (%s): %s", code, sev, str(f, "message")) - } - } -} - -// checkSettingFix binds the table's Fix and What-docket-does cells to the binary's -// own words: every alternative value the Fix cell offers appears in the binary's -// remedy, and each notice's description matches the binary's message. -func checkSettingFix(t *testing.T, row settingRow, f map[string]any, field string) { - t.Helper() - remedy, msg := str(f, "remedy"), str(f, "message") - if row.Severity != "notice" && !strings.HasPrefix(row.Fix, "Remove it") { - t.Errorf("settings row %q: the Fix the test mirrors is removal, so the cell must start with \"Remove it\"", row.Raw) - } - for _, tok := range backticked(row.Fix) { - switch { - case tok == "~/.config/docket/config.yml": - mustContain(t, "remedy for "+field, remedy, "global docket configuration") - case !strings.Contains(tok, "/"): - mustContain(t, "remedy for "+field, remedy, tok) - } - } - if strings.Contains(row.Does, "no effect") { - mustContain(t, "message for "+field, msg, "no effect") - } - if strings.Contains(row.Does, "read only once") { - mustContain(t, "message for "+field, msg, "read only once") - } -} - -// removeYAMLKey deletes path from mapping m, then drops every mapping the deletion -// left empty. It reports whether the key was found. -func removeYAMLKey(m *yaml.Node, path []string) bool { - if m.Kind != yaml.MappingNode { - return false - } - for i := 0; i+1 < len(m.Content); i += 2 { - if m.Content[i].Value != path[0] { - continue - } - if len(path) == 1 { - m.Content = append(m.Content[:i], m.Content[i+2:]...) - return true - } - child := m.Content[i+1] - if !removeYAMLKey(child, path[1:]) { - return false - } - if child.Kind == yaml.MappingNode && len(child.Content) == 0 { - m.Content = append(m.Content[:i], m.Content[i+2:]...) - } - return true - } - return false -} - -// runCommit runs a commit block. The guide shows these blocks unconditionally, so a -// clean tree means the steps before it did nothing the guide says they do: fatal. -// A step the guide says to skip when there is nothing to commit handles that case -// itself and never reaches here with a clean tree. -func runCommit(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - if strings.TrimSpace(c.mustGit(t, st.Cwd, "status", "--porcelain")) == "" { - t.Fatalf("commit block has nothing to commit, but the guide runs it unconditionally:\n%s", body) - } - before := gitRev(t, c, "main") - runBlock(t, c, st, body) - if gitRev(t, c, "main") == before { - t.Fatalf("commit block did not push a new commit to main") - } - if left := strings.TrimSpace(c.mustGit(t, st.Cwd, "status", "--porcelain")); left != "" { - t.Fatalf("commit block left changes behind:\n%s", left) - } -} - -// observeRepairPreview runs the preview with no terminal; the guide says it lists the -// repairs and asks for confirmation, and answering no (end of input) writes nothing. -func observeRepairPreview(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - if strings.TrimSpace(body) != "docket repository repair" { - t.Fatalf("repair-preview block must be exactly `docket repository repair`:\n%s", body) - } - before := gitRev(t, c, "docket") - r := c.run(t, st.Cwd, "/bin/sh", "-c", body) - out := r.Stdout + r.Stderr - mustContain(t, "repair preview", out, "preview") - mustContain(t, "repair preview", out, "repair? [y/N]") - if r.Code != 0 { - mustContain(t, "repair preview", out, "confirmation required") - } - if gitRev(t, c, "docket") != before { - t.Fatalf("the repair preview changed the docket branch") - } -} - -// runRepairApply runs the block and checks the guide's claims: the repair is pushed -// to the docket branch and the local .docket copy is brought up to that repaired -// commit, so the output asks for no `docket repository prepare` sync either. -func runRepairApply(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - before := gitRev(t, c, "docket") - r := runBlock(t, c, st, body) - after := gitRev(t, c, "docket") - if after == before { - t.Fatalf("guide says repair pushes to the docket branch; origin/docket did not move") - } - mustContainProse(t, "guide", st.Guide, repairFollowsProse) - if out := r.Stdout + r.Stderr; strings.Contains(out, "docket repository prepare") { - t.Fatalf("the repair brought .docket up to date, yet its output still asks for `docket repository prepare`:\n%s", out) - } - local := strings.TrimSpace(c.mustGit(t, filepath.Join(st.Cwd, ".docket"), "rev-parse", "HEAD")) - if local != after { - t.Fatalf("guide says repair brings the local .docket copy up to the repaired commit %s; it is at %s", after, local) - } -} - -// runRepoConfirm checks the guide's claim that `docket repository check` alone -// reports healthy right after the repair, with no `prepare` step in between. -func runRepoConfirm(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - if strings.TrimSpace(body) != "docket repository check" { - t.Fatalf("repo-confirm block must be exactly `docket repository check`:\n%s", body) - } - r := runBlock(t, c, st, body) - mustContain(t, "repository check output", r.Stdout+r.Stderr, "repository check: setup healthy, no problems found") -} - -// The lines that open and close the dispatch block Bash docket wrote into a -// repository's CLAUDE.md. The opening line carries a trailing note after the stem. -const ( - dispatchBlockStart = "" - // dispatchBlockSkip and dispatchBlockSkipWhy are the guide's instruction for a - // repository without the block, which mirrorDispatchBlock proves. - dispatchBlockSkip = "If there is no such block, skip this step." - dispatchBlockSkipWhy = "There is nothing to commit, and `git commit` stops with an error." - // bashDispatchSignature is what marks a dispatch block as Bash docket's: its body - // runs docket.sh. docket's own block shares the marker lines but never this. - bashDispatchSignature = "/docket.sh " -) - -// dispatchBlockSpan validates the dispatch block's markers in lines and returns the -// index of its opening and closing line, or -1, -1 when neither marker is present. -// A dangling, duplicated or out-of-order marker is an error, so the caller refuses -// before writing anything and the removal never runs to the end of the file. -func dispatchBlockSpan(lines []string) (int, int, error) { - start, end := -1, -1 - for i, l := range lines { - switch { - case strings.HasPrefix(l, dispatchBlockStart): - if start >= 0 { - return -1, -1, fmt.Errorf("two %q lines", dispatchBlockStart) - } - start = i - case l == dispatchBlockEnd: - if end >= 0 { - return -1, -1, fmt.Errorf("two %q lines", dispatchBlockEnd) - } - end = i - } - } - if (start < 0) != (end < 0) || end < start { - return -1, -1, fmt.Errorf("dispatch block markers are unbalanced or out of order (start line %d, end line %d)", start+1, end+1) - } - return start, end, nil -} - -// mirrorDispatchBlock deletes the Bash dispatch block from the repository's CLAUDE.md -// the way the prose says (the file too, when nothing else is left), then runs the -// block to commit and push it. On a case without the block it asserts the guide's -// skip instruction holds: nothing to commit, and the block as written fails. -func mirrorDispatchBlock(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - mustContain(t, "guide", st.Guide, "`"+dispatchBlockStart+"`") - mustContain(t, "guide", st.Guide, "`"+dispatchBlockEnd+"`") - mustContain(t, "guide", st.Guide, "If that leaves `CLAUDE.md` empty") - if st.Cwd != c.Clone { - t.Fatalf("dispatch-block runs in the repository; the reader is in %s", st.Cwd) - } - path := filepath.Join(c.Clone, "CLAUDE.md") - b, err := os.ReadFile(path) - if err != nil && !errors.Is(err, fs.ErrNotExist) { - t.Fatal(err) - } - lines := strings.Split(string(b), "\n") - start, end, err := dispatchBlockSpan(lines) - if err != nil { - t.Fatalf("CLAUDE.md: %v; leaving it untouched", err) - } - if start < 0 { - // Guide: with no block there is nothing to commit, so the reader skips the - // step, because the block's `git commit -am` stops with an error on a clean - // tree. Prove both halves: the tree is clean, and the block as written fails - // and pushes nothing. - mustContain(t, "guide", st.Guide, dispatchBlockSkip) - mustContain(t, "guide", st.Guide, dispatchBlockSkipWhy) - if left := strings.TrimSpace(c.mustGit(t, st.Cwd, "status", "--porcelain")); left != "" { - t.Fatalf("dispatch-block found no block but the repository has changes:\n%s", left) - } - before := gitRev(t, c, "main") - if r := c.run(t, st.Cwd, "/bin/sh", "-e", "-c", body); r.Code == 0 { - t.Fatalf("guide says git commit stops with an error on a clean tree; the dispatch-block block exited 0\nstdout:\n%s\nstderr:\n%s", r.Stdout, r.Stderr) - } - if gitRev(t, c, "main") != before { - t.Fatalf("the skipped dispatch-block block moved origin main") - } - t.Logf("dispatch-block: the repository has no dispatch block; the step is skipped") - return - } - // Guide: the upgrade leaves the block in place and `docket repository check` - // does not report it. repo-confirm already saw `healthy` with the block present. - mustContain(t, "guide", st.Guide, "`docket.sh`") - if !strings.Contains(strings.Join(lines[start:end+1], "\n"), bashDispatchSignature) { - t.Errorf("the guide says the block tells Claude to run Bash docket's docket.sh; it does not") - } - out := append(append([]string{}, lines[:start]...), lines[end+1:]...) - rest := strings.Join(out, "\n") - if strings.TrimSpace(rest) == "" { - if err := os.Remove(path); err != nil { - t.Fatal(err) - } - } else if err := os.WriteFile(path, []byte(rest), 0o644); err != nil { - t.Fatal(err) - } - runCommit(t, c, st, body) - // The block is gone from the working copy and from the pushed default branch. - after, err := os.ReadFile(path) - if err != nil && !errors.Is(err, fs.ErrNotExist) { - t.Fatal(err) - } - if s, _, err := dispatchBlockSpan(strings.Split(string(after), "\n")); err != nil || s >= 0 { - t.Fatalf("CLAUDE.md still carries the dispatch block after dispatch-block") - } - if r := c.run(t, c.Origin, "git", "show", "main:CLAUDE.md"); r.Code == 0 && strings.Contains(r.Stdout, "docket:dispatch:") { - t.Fatalf("origin main:CLAUDE.md still carries the dispatch block after dispatch-block") - } - st.DispatchBlockRemoved = true -} - -// The guide's final section-5 step: choose the agents, then commit what the command -// lists. The Cursor rule it writes is ignored, so only the listed paths are committed. -const ( - chooseHarnessesLine = "docket repository configure-harnesses --harnesses claude,cursor" - cursorRepoRule = ".cursor/rules/docket-dispatch.mdc" - cursorRepoRuleProse = "For Cursor, it writes `.cursor/rules/docket-dispatch.mdc` into the repository, which the `.gitignore` block keeps out of commits." - claudeRepoBlockProse = "For Claude Code, it writes docket's own block into `CLAUDE.md`." -) - -// runChooseHarnesses runs the block and checks the guide's claims: the git add line -// names exactly the paths configure-harnesses lists, the commit reaches origin main and -// leaves nothing behind, .docket.yml there records both harnesses, CLAUDE.md there -// carries docket's dispatch block (not Bash's), and the repository Cursor rule exists -// and is ignored by git. -func runChooseHarnesses(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - lines := blockLines(body) - if len(lines) != 4 || lines[0] != chooseHarnessesLine || !strings.HasPrefix(lines[1], "git add ") || - !strings.HasPrefix(lines[2], "git commit -m ") || lines[3] != "git push" { - t.Fatalf("choose-harnesses block must be `%s`, `git add `, `git commit -m …` and `git push`:\n%s", chooseHarnessesLine, body) - } - mustContainProse(t, "guide", st.Guide, cursorRepoRuleProse) - mustContainProse(t, "guide", st.Guide, claudeRepoBlockProse) - if st.Cwd != c.Clone { - t.Fatalf("choose-harnesses runs in the repository; the reader is in %s", st.Cwd) - } - if left := strings.TrimSpace(c.mustGit(t, st.Cwd, "status", "--porcelain")); left != "" { - t.Fatalf("choose-harnesses starts from a clean repository; git status shows:\n%s", left) - } - before := gitRev(t, c, "main") - r := runBlock(t, c, st, body) - pending := pendingPathsFrom(r.Stdout + r.Stderr) - added := strings.Fields(strings.TrimPrefix(lines[1], "git add ")) - if len(pending) == 0 || !sameSet(pending, added) { - t.Fatalf("the guide's git add line names %v; configure-harnesses asked to commit %v\nstdout:\n%s\nstderr:\n%s", added, pending, r.Stdout, r.Stderr) - } - if gitRev(t, c, "main") == before { - t.Fatalf("choose-harnesses did not push a new commit to main") - } - if left := strings.TrimSpace(c.mustGit(t, st.Cwd, "status", "--porcelain")); left != "" { - t.Fatalf("choose-harnesses left changes behind:\n%s", left) - } - if fi, err := os.Lstat(filepath.Join(c.Clone, filepath.FromSlash(cursorRepoRule))); err != nil || !fi.Mode().IsRegular() { - t.Fatalf("configure-harnesses did not write %s into the repository (%v)", cursorRepoRule, err) - } - if ig := c.run(t, c.Clone, "git", "check-ignore", "-q", "--", cursorRepoRule); ig.Code != 0 { - t.Errorf("guide says the .gitignore block keeps %s out of commits; git does not ignore it", cursorRepoRule) - } - var cfg struct { - AgentHarnesses []string `yaml:"agent_harnesses"` - } - if err := yaml.Unmarshal([]byte(c.mustGit(t, c.Origin, "show", "main:.docket.yml")), &cfg); err != nil { - t.Fatalf("parse main:.docket.yml: %v", err) - } - if !sameSet(cfg.AgentHarnesses, guideHarnesses) { - t.Errorf("origin main:.docket.yml records agent_harnesses %v; the guide chooses %v", cfg.AgentHarnesses, guideHarnesses) - } - claudeLines := strings.Split(c.mustGit(t, c.Origin, "show", "main:CLAUDE.md"), "\n") - start, end, err := dispatchBlockSpan(claudeLines) - switch { - case err != nil || start < 0: - t.Errorf("origin main:CLAUDE.md has no docket dispatch block after choose-harnesses (%v)", err) - case strings.Contains(strings.Join(claudeLines[start:end+1], "\n"), bashDispatchSignature): - t.Errorf("origin main:CLAUDE.md carries Bash docket's dispatch block after choose-harnesses, not docket's") - } -} - -// ---- section 7: leftovers ---------------------------------------------------------- - -// mirrorLeftovers deletes each leftover the block lists, after proving it exists and -// that `docket install check` does not mention it. It also checks the guide's claims -// about the old Bash checkout. -func mirrorLeftovers(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - chk := c.run(t, c.Home, "docket", "--json", "install", "check") - for _, line := range blockLines(body) { - path, desc, _ := strings.Cut(line, " ") - desc = strings.TrimSpace(desc) - full := c.expandHome(path) - if strings.Contains(chk.Stdout+chk.Stderr, full) { - t.Errorf("docket install check mentions %s, which the guide calls an unused leftover", path) - } - switch path { - case "~/.claude/settings.json": - removeSettingsEnv(t, full, desc) - case "~/.zshenv": - removeMarkedLines(t, full, desc) - default: - t.Fatalf("leftovers line %q names a path the test does not mirror", line) - } - } - // Guide: nothing under ~/.claude or ~/.cursor points into the old checkout; the - // other tools' links under ~/.codex and ~/.agents still do. The guide states that - // using docket from those tools on an upgraded repository is not supported, rather - // than advising to keep using Bash docket there: the test observes only the links. - mustContain(t, "guide", st.Guide, "`~/dev/docket`") - mustContainProse(t, "guide", st.Guide, "on an upgraded repository is not supported") - checkout := filepath.Join(c.Home, "dev", "docket") - for _, d := range []string{".claude", ".cursor"} { - mustContain(t, "guide", st.Guide, "`~/"+d+"`") - if n := linksInto(t, filepath.Join(c.Home, d), checkout); n != 0 { - t.Errorf("guide says nothing under ~/%s points into the old checkout; %d links do", d, n) - } - } - for _, d := range []string{".codex", ".agents"} { - mustContain(t, "guide", st.Guide, "`~/"+d+"`") - if linksInto(t, filepath.Join(c.Home, d), checkout) == 0 { - t.Errorf("guide says links under ~/%s still point into the old checkout; none do", d) - } - } - // Guide: docket must run outside Cursor's sandbox, with a link to the Cursor page. - mustContain(t, "guide", st.Guide, cursorSandboxLink) - if _, err := os.Stat(filepath.Join(repoRoot(t), "docs", "install", "cursor.md")); err != nil { - t.Errorf("the guide links %s, which does not exist: %v", cursorSandboxLink, err) - } -} - -// The per-repository leftovers the guide names. repoAgentGlob is the exact block line -// the test requires; repoSettings is the file the guide says it does not cover. -const ( - repoAgentGlob = "rm -f .claude/agents/docket-*.md" - repoSettings = ".claude/settings.local.json" - repoCursorAgentGlob = "rm -f .cursor/agents/docket-*.md" - repoCursorAgentUnproven = "so the test does not prove the `.cursor/agents` line" -) - -// runRepoAgentFiles runs the block that deletes the repository's Bash agent files. -// Before it runs, every such file must be ignored by git (the guide says there is -// nothing to commit) and at least one must share its name with an agent the installer -// wrote under ~/.claude/agents (the guide says the old files hide those). Afterwards -// none may be left, the repository has nothing to commit, and the repository's -// .claude/settings.local.json, which the guide leaves alone, is unchanged. -func runRepoAgentFiles(t *testing.T, c *upgradeCase, st *runState, body string) { - t.Helper() - lines := blockLines(body) - if len(lines) != 3 || lines[0] != "cd "+c.Clone || lines[1] != repoAgentGlob || lines[2] != repoCursorAgentGlob { - t.Fatalf("repo-agent-files block must be exactly `cd `, `%s` and `%s`:\n%s", repoAgentGlob, repoCursorAgentGlob, body) - } - mustContainProse(t, "guide", st.Guide, "these old files hide the agents the installer just wrote") - mustContainProse(t, "guide", st.Guide, "`"+repoSettings+"`") - mustContainProse(t, "guide", st.Guide, "the test leaves it in place") - mustContainProse(t, "guide", st.Guide, repoCursorAgentUnproven) - - glob := filepath.Join(c.Clone, ".claude", "agents", "docket-*.md") - cursorGlob := filepath.Join(c.Clone, ".cursor", "agents", "docket-*.md") - if found, _ := filepath.Glob(cursorGlob); len(found) > 0 { - t.Errorf("the saved %s clone carries repository Cursor agent files %v; the guide says the test does not prove the .cursor/agents line, so prove it and drop that sentence", c.Tag, found) - } - before, _ := filepath.Glob(glob) - for _, p := range before { - rel := strings.TrimPrefix(p, c.Clone+"/") - if r := c.run(t, c.Clone, "git", "check-ignore", "-q", "--", rel); r.Code != 0 { - t.Errorf("guide says the .gitignore block keeps %s out of commits; git does not ignore it", rel) - } - if _, err := os.Stat(filepath.Join(c.Home, ".claude", "agents", filepath.Base(p))); err == nil { - st.RepoAgentFilesShadow++ - } - } - if len(before) > 0 && st.RepoAgentFilesShadow == 0 { - t.Errorf("guide says the repository's agent files hide installed agents; none of %d shares a name with ~/.claude/agents", len(before)) - } - settingsPath := filepath.Join(c.Clone, filepath.FromSlash(repoSettings)) - settingsBefore, settingsErr := os.ReadFile(settingsPath) - if settingsErr == nil { - st.RepoSettingsSeen = true - mustContain(t, repoSettings, string(settingsBefore), "push origin HEAD:") - } - - runBlock(t, c, st, body) - - for _, g := range []string{glob, cursorGlob} { - if left, _ := filepath.Glob(g); len(left) > 0 { - t.Errorf("repo-agent-files left %v behind", left) - } - } - if left := strings.TrimSpace(c.mustGit(t, c.Clone, "status", "--porcelain")); left != "" { - t.Errorf("guide says there is nothing to commit after repo-agent-files; git status shows:\n%s", left) - } - if settingsErr == nil { - if after, err := os.ReadFile(settingsPath); err != nil || !bytes.Equal(after, settingsBefore) { - t.Errorf("guide says the test leaves %s in place; it changed or is gone (%v)", repoSettings, err) - } - } -} - -func removeSettingsEnv(t *testing.T, path, desc string) { - t.Helper() - b, err := os.ReadFile(path) - if err != nil { - t.Fatalf("guide lists %s as a leftover: %v", path, err) - } - var doc map[string]any - if err := json.Unmarshal(b, &doc); err != nil { - t.Fatalf("parse %s: %v", path, err) - } - env, _ := doc["env"].(map[string]any) - names := regexp.MustCompile(`"([A-Z_]+)"`).FindAllStringSubmatch(desc, -1) - if len(names) == 0 || !strings.Contains(desc, `under "env"`) { - t.Fatalf("leftovers line for %s must name the \"env\" entries to delete: %q", path, desc) - } - for _, m := range names { - if _, ok := env[m[1]]; !ok { - t.Fatalf("guide lists %s in %s, but it is not there", m[1], path) - } - delete(env, m[1]) - } - for k := range env { - if strings.HasPrefix(k, "DOCKET_") { - t.Errorf("%s still has %s after the guide's deletions", path, k) - } - } - if len(env) == 0 { - delete(doc, "env") - } - out, err := json.MarshalIndent(doc, "", " ") - if err != nil { - t.Fatal(err) - } - if err := os.WriteFile(path, append(out, '\n'), 0o644); err != nil { - t.Fatal(err) - } -} - -func removeMarkedLines(t *testing.T, path, desc string) { - t.Helper() - m := regexp.MustCompile(`^the lines from "([^"]+)" to "([^"]+)"$`).FindStringSubmatch(desc) - if m == nil { - t.Fatalf("leftovers line for %s must read `the lines from \"\" to \"\"`: %q", path, desc) - } - b, err := os.ReadFile(path) - if err != nil { - t.Fatalf("guide lists %s as a leftover: %v", path, err) - } - lines := strings.Split(string(b), "\n") - start, end := -1, -1 - for i, l := range lines { - if l == m[1] && start < 0 { - start = i - } - if l == m[2] && start >= 0 && end < 0 { - end = i - } - } - if start < 0 || end < start { - t.Fatalf("%s has no lines from %q to %q:\n%s", path, m[1], m[2], b) - } - out := append(append([]string{}, lines[:start]...), lines[end+1:]...) - if err := os.WriteFile(path, []byte(strings.Join(out, "\n")), 0o644); err != nil { - t.Fatal(err) - } -} - -// linksInto counts the symlinks under dir whose target lies inside root. -func linksInto(t *testing.T, dir, root string) int { - t.Helper() - n := 0 - err := filepath.WalkDir(dir, func(p string, d fs.DirEntry, err error) error { - if err != nil { - return err - } - if d.Type()&fs.ModeSymlink == 0 { - return nil - } - target, err := os.Readlink(p) - if err != nil { - return err - } - if target == root || strings.HasPrefix(target, root+"/") { - n++ - } - return nil - }) - if err != nil && !errors.Is(err, fs.ErrNotExist) { - t.Fatalf("walk %s: %v", dir, err) - } - return n -} - -// changesDir is the case's changes directory: changes_dir from .docket.yml on main -// when set, else the default. -func changesDir(t *testing.T, c *upgradeCase) string { - t.Helper() - dir := "docs/changes" - if r := c.run(t, c.Origin, "git", "show", "main:.docket.yml"); r.Code == 0 { - var cfg struct { - ChangesDir string `yaml:"changes_dir"` - } - if err := yaml.Unmarshal([]byte(r.Stdout), &cfg); err != nil { - t.Fatalf("parse main:.docket.yml: %v", err) - } - if cfg.ChangesDir != "" { - dir = strings.TrimSuffix(cfg.ChangesDir, "/") - } - } - return dir -} diff --git a/internal/bashupgrade/registry_unit_test.go b/internal/bashupgrade/registry_unit_test.go deleted file mode 100644 index 4d39d60b1..000000000 --- a/internal/bashupgrade/registry_unit_test.go +++ /dev/null @@ -1,68 +0,0 @@ -package bashupgrade - -import ( - "strings" - "testing" -) - -func TestInstallLineHarnesses(t *testing.T) { - for line, want := range map[string][]string{ - "sh install.sh --harness claude --harness cursor": {"claude", "cursor"}, - "sh install.sh --harness cursor": {"cursor"}, - "sh install.sh --harness claude": {"claude"}, - "sh install.sh --harness cursor --harness claude": {"cursor", "claude"}, - } { - got, ok := installLineHarnesses(line) - if !ok || strings.Join(got, ",") != strings.Join(want, ",") { - t.Errorf("%q: got %v, %v; want %v", line, got, ok, want) - } - } - for _, line := range []string{ - "sh install.sh", - "sh install.sh --harness", - "sh install.sh --harness claude extra", - "sh install.sh --harness claude --harness claude", - "sh install.sh --harness vim", - "sh install.sh --harnesses claude", - "bash install.sh --harness claude", - "sh ./install.sh --harness claude", - } { - if got, ok := installLineHarnesses(line); ok { - t.Errorf("%q was accepted as an installer line (%v)", line, got) - } - } -} - -func TestContainsProse(t *testing.T) { - if !containsProse("one two\n three\tfour", "two three four") { - t.Error("a wrapped sentence did not match its one-line form") - } - if !containsProse("On `v0.9.2` it is not reported as a conflict; the block\n below deletes it either way.", "On `v0.9.2` it is not reported as a conflict; the block below deletes it either way.") { - t.Error("a wrapped guide sentence did not match") - } - if containsProse("one two three", "two four") { - t.Error("different words matched") - } - if containsProse("onetwo", "one two") { - t.Error("collapsing must not delete whitespace between words") - } -} - -func TestPendingPathsFrom(t *testing.T) { - out := "agent harnesses set to `[claude, cursor]` (needs-review); review and commit the pending paths: CLAUDE.md, .docket.yml\nnext line\n" - if got := pendingPathsFrom(out); strings.Join(got, ",") != ".docket.yml,CLAUDE.md" { - t.Fatalf("got %v", got) - } - if got := pendingPathsFrom("agent harnesses set to `[claude]` (healthy)\n"); got != nil { - t.Fatalf("no lead must give nil, got %v", got) - } -} - -func TestSameSet(t *testing.T) { - if !sameSet([]string{"b", "a"}, []string{"a", "b"}) { - t.Error("order mattered") - } - if sameSet([]string{"a"}, []string{"a", "b"}) || sameSet([]string{"a", "a"}, []string{"a", "b"}) { - t.Error("different sets compared equal") - } -} diff --git a/internal/bashupgrade/restore_test.go b/internal/bashupgrade/restore_test.go deleted file mode 100644 index 085c4ea5b..000000000 --- a/internal/bashupgrade/restore_test.go +++ /dev/null @@ -1,633 +0,0 @@ -package bashupgrade - -// Restore and sandbox helpers shared by the default-tag unit tests and the -// integration-tagged upgrade proof. A saved case (testdata/bash-upgrade//, see -// that tree's PROVENANCE.md) is restored into a per-test sandbox: the home.tar -// harness folders become a throwaway HOME, origin.bundle becomes a local bare -// origin, and clone-config.txt is replayed on a fresh clone so the clone looks the -// way the Bash tag left it. Every subprocess runs with upgradeCase.Env, which is -// built from nothing (never os.Environ), so no real HOME, XDG dir or DOCKET_* -// variable can leak in. - -import ( - "archive/tar" - "bytes" - "encoding/json" - "errors" - "fmt" - "io" - "io/fs" - "os" - "os/exec" - "path" - "path/filepath" - "runtime" - "sort" - "strings" - "sync" - "testing" - - "go.yaml.in/yaml/v3" - - "github.com/danielhanold/docket/internal/testsupport" -) - -// homeToken stands for the sandbox HOME in every saved home.tar symlink target and -// regular-file body; restoreCase substitutes the per-test home for it. -const homeToken = "@@SANDBOX_HOME@@" - -// upgradeCase is one restored saved case. Root is the per-test sandbox root, Home -// the restored home, Origin the local bare origin, Clone the user's repository, -// BinDir $Home/.local/bin, Docket the freshly built binary (not yet in BinDir), and -// Env the complete environment for every subprocess. -type upgradeCase struct { - Tag, Root, Home, Origin, Clone, BinDir string - Env []string - Docket string -} - -type cmdResult struct { - Stdout, Stderr string - Code int -} - -type findingRef struct { - Code, Severity string -} - -// cloneAction is one parsed clone-config.txt line: Kind "config" (A key, B value), -// Kind "worktree" (A path relative to the clone root, B branch), or Kind -// "hooks-off" (A worktree path relative to the clone root, B empty). -type cloneAction struct { - Kind, A, B string -} - -// substituteHome replaces every homeToken in b with home. -func substituteHome(b []byte, home string) []byte { - return bytes.ReplaceAll(b, []byte(homeToken), []byte(home)) -} - -// parseCloneConfig parses clone-config.txt: blank lines and # comments are -// skipped; every other line is exactly `config `, -// `worktree ` or `hooks-off `, with a relative, -// non-escaping worktree path. -// -// hooks-off exists because the Bash tags' disable-worktree-hooks.sh sets a -// WORKTREE-scoped core.hooksPath (pointing at /docket/empty-hooks, -// a path inside the clone) that a `git config --local` line cannot express. -// Without it the restored .docket worktree has hooks enabled, a state no Bash -// user's clone was ever in. -func parseCloneConfig(s string) ([]cloneAction, error) { - var out []cloneAction - for i, line := range strings.Split(s, "\n") { - trimmed := strings.TrimSpace(line) - if trimmed == "" || strings.HasPrefix(trimmed, "#") { - continue - } - f := strings.Fields(trimmed) - want := map[string]int{"config": 3, "worktree": 3, "hooks-off": 2}[f[0]] - if want == 0 || len(f) != want { - return nil, fmt.Errorf("clone-config line %d: %q is not `config `, `worktree ` or `hooks-off `", i+1, line) - } - if f[0] != "config" && !localRelPath(f[1]) { - return nil, fmt.Errorf("clone-config line %d: worktree path %q must be relative and stay inside the clone", i+1, f[1]) - } - a := cloneAction{Kind: f[0], A: f[1]} - if len(f) == 3 { - a.B = f[2] - } - out = append(out, a) - } - return out, nil -} - -// localRelPath reports whether p is a relative slash path that cannot escape its -// base (no leading /, no .. element). -func localRelPath(p string) bool { - if p == "" || strings.HasPrefix(p, "/") { - return false - } - for _, el := range strings.Split(p, "/") { - if el == ".." { - return false - } - } - return true -} - -// findingCodes decodes one JSON document and collects, depth first in document -// order (map keys sorted), every object whose code and severity fields are both -// strings. It does not depend on the wrapper shape of any one command's output. -func findingCodes(t *testing.T, stdout string) []findingRef { - t.Helper() - var doc any - if err := json.Unmarshal([]byte(stdout), &doc); err != nil { - t.Fatalf("decode JSON output: %v\n%s", err, stdout) - } - var out []findingRef - var walk func(v any) - walk = func(v any) { - switch x := v.(type) { - case map[string]any: - code, okCode := x["code"].(string) - sev, okSev := x["severity"].(string) - if okCode && okSev { - out = append(out, findingRef{Code: code, Severity: sev}) - } - keys := make([]string, 0, len(x)) - for k := range x { - keys = append(keys, k) - } - sort.Strings(keys) - for _, k := range keys { - walk(x[k]) - } - case []any: - for _, e := range x { - walk(e) - } - } - } - walk(doc) - return out -} - -// repoRoot returns the module root: this file lives at -// internal/bashupgrade/restore_test.go, two directories below it. -func repoRoot(t *testing.T) string { - t.Helper() - _, file, _, ok := runtime.Caller(0) - if !ok { - t.Fatal("runtime.Caller failed; cannot locate the repo root") - } - root, err := filepath.Abs(filepath.Join(filepath.Dir(file), "..", "..")) - if err != nil { - t.Fatalf("resolve repo root: %v", err) - } - if _, err := os.Stat(filepath.Join(root, "go.mod")); err != nil { - t.Fatalf("resolved repo root %q has no go.mod: %v", root, err) - } - return root -} - -// savedTags lists the testdata/bash-upgrade/ subdirectories that hold an -// origin.bundle, sorted. It is derived, never hand-listed, so a newly saved tag is -// picked up with no test edit; an empty list fails (population floor). -func savedTags(t *testing.T) []string { - t.Helper() - dir := filepath.Join(repoRoot(t), "testdata", "bash-upgrade") - entries, err := os.ReadDir(dir) - if err != nil { - t.Fatalf("read saved cases: %v", err) - } - var tags []string - for _, e := range entries { - if !e.IsDir() { - continue - } - if _, err := os.Stat(filepath.Join(dir, e.Name(), "origin.bundle")); err == nil { - tags = append(tags, e.Name()) - } - } - sort.Strings(tags) - if len(tags) == 0 { - t.Fatalf("population floor: no saved case with an origin.bundle under %s", dir) - } - return tags -} - -var ( - buildOnce sync.Once - buildDir string - buildBin string - buildErr error -) - -// TestMain removes the process-lifetime build dir buildDocket created. -func TestMain(m *testing.M) { - code := m.Run() - if buildDir != "" { - _ = os.RemoveAll(buildDir) - } - os.Exit(code) -} - -// buildDocket builds ./cmd/docket from this checkout once per test binary and -// returns the binary's absolute path. A build failure fails every caller. -func buildDocket(t *testing.T) string { - t.Helper() - root := repoRoot(t) - buildOnce.Do(func() { - // tempdir-exempt: process-lifetime binary dir shared by every test under sync.Once; TestMain removes it. - dir, err := os.MkdirTemp("", "docket-bashupgrade-bin-*") - if err != nil { - buildErr = err - return - } - buildDir = dir - bin := filepath.Join(dir, "docket") - cmd := exec.Command("go", "build", "-o", bin, "./cmd/docket") - cmd.Dir = root - if out, err := cmd.CombinedOutput(); err != nil { - buildErr = fmt.Errorf("go build ./cmd/docket: %v\n%s", err, out) - return - } - buildBin = bin - }) - if buildErr != nil { - t.Fatal(buildErr) - } - return buildBin -} - -// restoreCase restores the saved case for tag into a fresh per-test sandbox. -func restoreCase(t *testing.T, tag string) *upgradeCase { - t.Helper() - root, err := filepath.EvalSymlinks(testsupport.TempDir(t)) - if err != nil { - t.Fatalf("canonicalize sandbox root: %v", err) - } - home := filepath.Join(root, "home") - c := &upgradeCase{ - Tag: tag, - Root: root, - Home: home, - Origin: filepath.Join(root, "origin.git"), - Clone: filepath.Join(home, "dev", "sample"), - BinDir: filepath.Join(home, ".local", "bin"), - } - saved := filepath.Join(repoRoot(t), "testdata", "bash-upgrade", tag) - - extractTar(t, filepath.Join(saved, "home.tar"), home, home) - assertNoHomeToken(t, home) - - xdg := map[string]string{ - "XDG_CONFIG_HOME": filepath.Join(home, ".config"), - "XDG_DATA_HOME": filepath.Join(home, ".local", "share"), - "XDG_CACHE_HOME": filepath.Join(home, ".cache"), - "XDG_STATE_HOME": filepath.Join(home, ".local", "state"), - "XDG_RUNTIME_DIR": filepath.Join(home, ".local", "runtime"), - "XDG_BIN_HOME": c.BinDir, - } - tmp := filepath.Join(root, "tmp") - for _, d := range append([]string{tmp}, mapValues(xdg)...) { - if err := os.MkdirAll(d, 0o755); err != nil { - t.Fatalf("create sandbox dir: %v", err) - } - } - env := []string{ - "HOME=" + home, "USER=fixture", "LOGNAME=fixture", "SHELL=/bin/zsh", "TERM=dumb", "LANG=en_US.UTF-8", - "TMPDIR=" + tmp, - "PATH=" + c.BinDir + ":/usr/bin:/bin:/usr/sbin:/sbin", - } - for _, k := range sortedKeys(xdg) { - env = append(env, k+"="+xdg[k]) - } - c.Env = append(env, testsupport.GitEnv(t)...) - c.Docket = buildDocket(t) - - c.mustGit(t, root, "init", "--quiet", "--bare", "-b", "main", c.Origin) - c.mustGit(t, c.Origin, "fetch", "--quiet", filepath.Join(saved, "origin.bundle"), "refs/heads/*:refs/heads/*") - c.mustGit(t, root, "clone", "--quiet", c.Origin, c.Clone) - c.mustGit(t, c.Clone, "remote", "set-head", "origin", "main") - - raw, err := os.ReadFile(filepath.Join(saved, "clone-config.txt")) - if err != nil { - t.Fatalf("read clone-config.txt: %v", err) - } - actions, err := parseCloneConfig(string(raw)) - if err != nil { - t.Fatalf("%s/clone-config.txt: %v", tag, err) - } - for _, a := range actions { - switch a.Kind { - case "config": - c.mustGit(t, c.Clone, "config", "--local", a.A, a.B) - case "worktree": - // git's own DWIM creates a missing local branch tracking origin/. - c.mustGit(t, c.Clone, "worktree", "add", "--quiet", a.A, a.B) - case "hooks-off": - // Mirrors the tags' disable-worktree-hooks.sh: an empty hooks dir under - // the git common dir, named by the worktree-scoped core.hooksPath. The - // tag's script also enables extensions.worktreeConfig; clone-config.txt - // carries that as its own config line, which must come first. - wt := filepath.Join(c.Clone, filepath.FromSlash(a.A)) - common := strings.TrimSpace(c.mustGit(t, wt, "rev-parse", "--path-format=absolute", "--git-common-dir")) - empty := filepath.Join(common, "docket", "empty-hooks") - if err := os.MkdirAll(empty, 0o755); err != nil { - t.Fatalf("create empty hooks dir: %v", err) - } - c.mustGit(t, wt, "config", "--worktree", "core.hooksPath", empty) - } - } - - // clone-files.tar (optional) holds the ignored, per-clone files the Bash tag - // wrote into the repository's working tree, which neither the bundle nor - // clone-config.txt can carry. - if cf := filepath.Join(saved, "clone-files.tar"); fileExists(cf) { - tops := extractTar(t, cf, c.Clone, home) - if r := c.run(t, c.Clone, "git", "status", "--porcelain"); r.Code != 0 || strings.TrimSpace(r.Stdout) != "" { - t.Fatalf("clone-files.tar must hold only ignored files; git status shows:\n%s%s", r.Stdout, r.Stderr) - } - if files, _ := assertNoToken(t, tops...); files == 0 { - t.Fatalf("clone-files.tar restored no file") - } - } - return c -} - -func fileExists(p string) bool { - _, err := os.Stat(p) - return err == nil -} - -// extractTar unpacks a saved tar under dest, substituting homeToken with home in -// symlink targets and regular-file bodies. A member name that is absolute, escapes -// with .., enters .git, or would be written through an already-restored symlink is -// refused. It returns the restored top-level paths under dest. -func extractTar(t *testing.T, tarPath, dest, home string) []string { - t.Helper() - f, err := os.Open(tarPath) - if err != nil { - t.Fatalf("open %s: %v", filepath.Base(tarPath), err) - } - defer f.Close() - if err := os.MkdirAll(dest, 0o755); err != nil { - t.Fatal(err) - } - tr := tar.NewReader(f) - tops := map[string]bool{} - base := filepath.Base(tarPath) - for { - h, err := tr.Next() - if errors.Is(err, io.EOF) { - break - } - if err != nil { - t.Fatalf("read %s: %v", base, err) - } - name := strings.TrimSuffix(h.Name, "/") - if !localRelPath(name) || name == "." { - t.Fatalf("%s member %q is absolute or escapes its root", base, h.Name) - } - top, _, _ := strings.Cut(name, "/") - if top == ".git" { - t.Fatalf("%s member %q writes into .git", base, h.Name) - } - tops[top] = true - dst := filepath.Join(dest, filepath.FromSlash(name)) - mustNotTraverseSymlink(t, dest, path.Dir(name)) - mode := fs.FileMode(h.Mode).Perm() - switch h.Typeflag { - case tar.TypeDir: - if mode == 0 { - mode = 0o755 - } - if err := os.MkdirAll(dst, mode); err != nil { - t.Fatalf("restore dir %s: %v", name, err) - } - case tar.TypeReg: - body, err := io.ReadAll(tr) - if err != nil { - t.Fatalf("read member %s: %v", name, err) - } - if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil { - t.Fatal(err) - } - if err := os.WriteFile(dst, substituteHome(body, home), mode); err != nil { - t.Fatalf("restore file %s: %v", name, err) - } - case tar.TypeSymlink: - if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil { - t.Fatal(err) - } - if err := os.Symlink(string(substituteHome([]byte(h.Linkname), home)), dst); err != nil { - t.Fatalf("restore symlink %s: %v", name, err) - } - default: - t.Fatalf("%s member %q has unsupported type %q", base, h.Name, h.Typeflag) - } - } - if len(tops) == 0 { - t.Fatalf("%s is empty", tarPath) - } - var out []string - for top := range tops { - out = append(out, filepath.Join(dest, top)) - } - sort.Strings(out) - return out -} - -// mustNotTraverseSymlink fails when any existing component of rel (under root) is -// a symlink, so no member is written outside root through a restored link. -func mustNotTraverseSymlink(t *testing.T, root, rel string) { - t.Helper() - if rel == "." || rel == "" { - return - } - cur := root - for _, el := range strings.Split(rel, "/") { - cur = filepath.Join(cur, el) - fi, err := os.Lstat(cur) - if err != nil { - return // not created yet; MkdirAll makes a real directory - } - if fi.Mode()&fs.ModeSymlink != 0 { - t.Fatalf("a saved tar writes through the restored symlink %s", cur) - } - } -} - -// assertNoHomeToken fails when any regular file body or symlink target under home -// still holds homeToken: a surviving placeholder makes every later assert a test -// of a broken home. The restored home must hold both files and symlinks, or the -// check would be vacuous. -func assertNoHomeToken(t *testing.T, home string) { - t.Helper() - if files, links := assertNoToken(t, home); files == 0 || links == 0 { - t.Fatalf("restored home has %d files and %d symlinks; the placeholder check would be vacuous", files, links) - } -} - -// assertNoToken fails when any regular file body or symlink target under each root -// still holds homeToken, and returns how many files and symlinks it read. -func assertNoToken(t *testing.T, roots ...string) (files, links int) { - t.Helper() - var left []string - for _, root := range roots { - err := filepath.WalkDir(root, func(p string, d fs.DirEntry, err error) error { - if err != nil { - return err - } - switch { - case d.Type()&fs.ModeSymlink != 0: - links++ - target, err := os.Readlink(p) - if err != nil { - return err - } - if strings.Contains(target, homeToken) { - left = append(left, p+" -> "+target) - } - case d.Type().IsRegular(): - files++ - b, err := os.ReadFile(p) - if err != nil { - return err - } - if bytes.Contains(b, []byte(homeToken)) { - left = append(left, p) - } - } - return nil - }) - if err != nil { - t.Fatalf("walk restored %s: %v", root, err) - } - } - if len(left) > 0 { - t.Fatalf("%s survived restore in:\n%s", homeToken, strings.Join(left, "\n")) - } - return files, links -} - -// run executes name with args in dir under c.Env. A bare name is resolved on -// c.Env's PATH (not the test process's), so the case's own tools are used. -func (c *upgradeCase) run(t *testing.T, dir string, name string, args ...string) cmdResult { - t.Helper() - bin := name - if !strings.Contains(name, "/") { - bin = c.lookPath(t, name) - } - cmd := exec.Command(bin, args...) - cmd.Dir = dir - cmd.Env = c.Env - var stdout, stderr bytes.Buffer - cmd.Stdout, cmd.Stderr = &stdout, &stderr - res := cmdResult{} - err := cmd.Run() - res.Stdout, res.Stderr = stdout.String(), stderr.String() - var exitErr *exec.ExitError - switch { - case err == nil: - case errors.As(err, &exitErr): - res.Code = exitErr.ExitCode() - default: - t.Fatalf("run %s %v: %v", name, args, err) - } - return res -} - -// mustGit runs git in dir and fails the test on a non-zero exit. -func (c *upgradeCase) mustGit(t *testing.T, dir string, args ...string) string { - t.Helper() - r := c.run(t, dir, "git", args...) - if r.Code != 0 { - t.Fatalf("git %s (in %s) exited %d\nstdout:\n%s\nstderr:\n%s", strings.Join(args, " "), dir, r.Code, r.Stdout, r.Stderr) - } - return r.Stdout -} - -func (c *upgradeCase) lookPath(t *testing.T, name string) string { - t.Helper() - for _, kv := range c.Env { - if !strings.HasPrefix(kv, "PATH=") { - continue - } - for _, d := range filepath.SplitList(strings.TrimPrefix(kv, "PATH=")) { - p := filepath.Join(d, name) - if fi, err := os.Stat(p); err == nil && fi.Mode().IsRegular() && fi.Mode().Perm()&0o111 != 0 { - return p - } - } - } - t.Fatalf("%s is not on the case PATH", name) - return "" -} - -// readRecords returns the saved records.txt inventory for tag (comments and blank -// lines dropped), in file order. -func readRecords(t *testing.T, tag string) []string { - t.Helper() - b, err := os.ReadFile(filepath.Join(repoRoot(t), "testdata", "bash-upgrade", tag, "records.txt")) - if err != nil { - t.Fatalf("read records.txt: %v", err) - } - var out []string - for _, line := range strings.Split(string(b), "\n") { - line = strings.TrimSpace(line) - if line == "" || strings.HasPrefix(line, "#") { - continue - } - out = append(out, line) - } - return out -} - -// listRecords computes the records.txt inventory from the case's origin: every -// change record, ADR, spec and learning on the docket and main branches, prefixed -// with its branch and sorted bytewise (LC_ALL=C sort). Ledger dirs come from -// .docket.yml on main when it sets them, else the defaults. -func listRecords(t *testing.T, c *upgradeCase) []string { - t.Helper() - changes, adrs := "docs/changes", "docs/adrs" - if r := c.run(t, c.Origin, "git", "show", "main:.docket.yml"); r.Code == 0 { - var cfg struct { - ChangesDir string `yaml:"changes_dir"` - AdrsDir string `yaml:"adrs_dir"` - } - if err := yaml.Unmarshal([]byte(r.Stdout), &cfg); err != nil { - t.Fatalf("parse main:.docket.yml: %v", err) - } - if cfg.ChangesDir != "" { - changes = strings.TrimSuffix(cfg.ChangesDir, "/") - } - if cfg.AdrsDir != "" { - adrs = strings.TrimSuffix(cfg.AdrsDir, "/") - } - } - patterns := []string{ - changes + "/active/*.md", - changes + "/archive/*.md", - changes + "/learnings/*.md", - adrs + "/[0-9]*.md", - "docs/superpowers/specs/*.md", - } - var out []string - for _, branch := range []string{"docket", "main"} { - for _, p := range strings.Split(c.mustGit(t, c.Origin, "ls-tree", "-r", "--name-only", branch), "\n") { - if p == "" { - continue - } - if base := path.Base(p); base == "README.md" || base == "BOARD.md" { - continue - } - for _, pat := range patterns { - if ok, _ := path.Match(pat, p); ok { - out = append(out, branch+":"+p) - break - } - } - } - } - sort.Strings(out) - return out -} - -func sortedKeys(m map[string]string) []string { - keys := make([]string, 0, len(m)) - for k := range m { - keys = append(keys, k) - } - sort.Strings(keys) - return keys -} - -func mapValues(m map[string]string) []string { - var out []string - for _, k := range sortedKeys(m) { - out = append(out, m[k]) - } - return out -} diff --git a/internal/bashupgrade/restore_unit_test.go b/internal/bashupgrade/restore_unit_test.go deleted file mode 100644 index 45b84e1f8..000000000 --- a/internal/bashupgrade/restore_unit_test.go +++ /dev/null @@ -1,52 +0,0 @@ -package bashupgrade - -import ( - "reflect" - "testing" -) - -func TestSubstituteHome(t *testing.T) { - got := substituteHome([]byte("x=@@SANDBOX_HOME@@/dev/docket/scripts\ny=@@SANDBOX_HOME@@"), "/tmp/h") - if string(got) != "x=/tmp/h/dev/docket/scripts\ny=/tmp/h" { - t.Fatalf("substituteHome = %q", got) - } - if string(substituteHome([]byte("no token"), "/tmp/h")) != "no token" { - t.Fatal("substituteHome changed bytes without a token") - } -} - -func TestParseCloneConfig(t *testing.T) { - in := "# replay\nconfig core.hooksPath /dev/null\n\nworktree .docket docket\n" - got, err := parseCloneConfig(in) - if err != nil { - t.Fatal(err) - } - want := []cloneAction{{Kind: "config", A: "core.hooksPath", B: "/dev/null"}, {Kind: "worktree", A: ".docket", B: "docket"}} - if !reflect.DeepEqual(got, want) { - t.Fatalf("parseCloneConfig = %#v", got) - } - hooks, err := parseCloneConfig("config extensions.worktreeConfig true\nhooks-off .docket\n") - if err != nil { - t.Fatal(err) - } - if want := []cloneAction{{Kind: "config", A: "extensions.worktreeConfig", B: "true"}, {Kind: "hooks-off", A: ".docket"}}; !reflect.DeepEqual(hooks, want) { - t.Fatalf("parseCloneConfig(hooks-off) = %#v", hooks) - } - for _, bad := range []string{ - "config onlykey\n", "worktree .docket\n", "exec rm -rf /\n", "config a b c\n", - "hooks-off\n", "hooks-off .docket extra\n", "hooks-off ../elsewhere\n", "worktree /abs docket\n", - } { - if _, err := parseCloneConfig(bad); err == nil { - t.Errorf("parseCloneConfig(%q) accepted a malformed line", bad) - } - } -} - -func TestFindingCodesWalksAnyShape(t *testing.T) { - doc := `{"result":"applied","checks":[{"findings":[{"code":"board-stale","severity":"warning"}]}],"findings":[{"code":"test-config-missing","severity":"error"}]}` + "\n" - got := findingCodes(t, doc) - want := []findingRef{{"board-stale", "warning"}, {"test-config-missing", "error"}} - if !reflect.DeepEqual(got, want) { - t.Fatalf("findingCodes = %#v", got) - } -} diff --git a/internal/bashupgrade/steps_test.go b/internal/bashupgrade/steps_test.go deleted file mode 100644 index 14ccfe44c..000000000 --- a/internal/bashupgrade/steps_test.go +++ /dev/null @@ -1,183 +0,0 @@ -package bashupgrade - -// Guide step extraction: the upgrade guide (docs/release/upgrading-from-bash.md) marks -// every block the test drives with a `` line directly -// above its fence. parseGuide pulls those blocks out in guide order and keeps every -// other fence in Unmarked, so the shape test can refuse an unmarked block that runs -// docket commands. - -import ( - "fmt" - "regexp" - "strings" -) - -const stepMarkerPrefix = "$`) - openRe := regexp.MustCompile("^(`{3,})[^`]*$") - markerStem := strings.TrimSuffix(stepMarkerPrefix, " ") - - lines := strings.Split(src, "\n") - var doc guideDoc - seen := map[string]int{} - - // readFence consumes the fence opening at lines[i] and returns its body and the - // index of the closing line. - readFence := func(i int, ticks string) (string, int, error) { - var b strings.Builder - for j := i + 1; j < len(lines); j++ { - if strings.TrimRight(lines[j], " \t\r") == ticks { - return b.String(), j, nil - } - b.WriteString(lines[j]) - b.WriteString("\n") - } - return "", 0, fmt.Errorf("line %d: unterminated fence %s", i+1, ticks) - } - - for i := 0; i < len(lines); i++ { - line := strings.TrimRight(lines[i], " \t\r") - if strings.HasPrefix(line, markerStem) { - m := markerRe.FindStringSubmatch(line) - if m == nil { - return guideDoc{}, fmt.Errorf("line %d: malformed upgrade-step marker %q", i+1, line) - } - name := m[1] - if prev, dup := seen[name]; dup { - return guideDoc{}, fmt.Errorf("line %d: duplicate upgrade-step %q (first at line %d)", i+1, name, prev) - } - seen[name] = i + 1 - j := i + 1 - for j < len(lines) && strings.TrimSpace(lines[j]) == "" { - j++ - } - var fm []string - if j < len(lines) { - fm = openRe.FindStringSubmatch(strings.TrimRight(lines[j], " \t\r")) - } - if fm == nil { - return guideDoc{}, fmt.Errorf("line %d: upgrade-step %q is not followed by a fenced block", i+1, name) - } - body, end, err := readFence(j, fm[1]) - if err != nil { - return guideDoc{}, err - } - doc.Steps = append(doc.Steps, guideStep{Name: name, Body: body, Line: i + 1}) - i = end - continue - } - if fm := openRe.FindStringSubmatch(line); fm != nil { - body, end, err := readFence(i, fm[1]) - if err != nil { - return guideDoc{}, err - } - doc.Unmarked = append(doc.Unmarked, guideFence{Body: body, Line: i + 1}) - i = end - } - } - return doc, nil -} - -var ( - // commandSeparatorRe splits a shell line where a new command word can start: - // a list or pipe operator, or a command substitution. A single | also splits || - // (the empty segment between the two bars has no command word). - commandSeparatorRe = regexp.MustCompile(`&&|;|\||\$\(`) - // leadingAssignmentRe matches one leading VAR=value word. - leadingAssignmentRe = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*=("[^"]*"|'[^']*'|\S*)(\s+|$)`) -) - -// docketCommandLines returns the lines of body that run docket as a command: after -// trimming leading whitespace and an optional "$ " prompt, some command segment (the -// line start, or the text after &&, ||, ;, | or $( ) has docket as its command word -// once leading VAR=value assignments and sudo are stripped. A command word "docket" -// or any path ending in "/docket" counts. Comment lines are skipped. -func docketCommandLines(body string) []string { - var out []string - for _, raw := range strings.Split(body, "\n") { - line := strings.TrimSpace(raw) - if line == "" || strings.HasPrefix(line, "#") { - continue - } - line = strings.TrimSpace(strings.TrimPrefix(line, "$ ")) - for _, seg := range commandSeparatorRe.Split(line, -1) { - if commandWord(seg) == "docket" { - out = append(out, line) - break - } - } - } - return out -} - -// commandWord returns the command word of one shell command segment, skipping leading -// VAR=value assignments and sudo, with a path reduced to its last element. -func commandWord(seg string) string { - seg = strings.TrimSpace(seg) - for { - if m := leadingAssignmentRe.FindString(seg); m != "" { - seg = seg[len(m):] - continue - } - if f := strings.Fields(seg); len(f) > 0 && f[0] == "sudo" { - seg = strings.TrimSpace(strings.TrimPrefix(seg, "sudo")) - continue - } - break - } - f := strings.Fields(seg) - if len(f) == 0 { - return "" - } - w := f[0] - if i := strings.LastIndex(w, "/"); i >= 0 { - w = w[i+1:] - } - return w -} - -// substitutePlaceholders replaces each token named in repl and refuses a body -// carrying any <[a-z-]+> token repl does not name. Replacement is single-pass, so a -// value that itself looks like a token is never re-expanded or rejected. -func substitutePlaceholders(body string, repl map[string]string) (string, error) { - tokenRe := regexp.MustCompile(`<([a-z-]+)>`) - var unknown []string - for _, m := range tokenRe.FindAllStringSubmatch(body, -1) { - if _, ok := repl[m[1]]; !ok { - unknown = append(unknown, m[0]) - } - } - if len(unknown) > 0 { - return "", fmt.Errorf("unknown placeholders %v", unknown) - } - var pairs []string - for k, v := range repl { - pairs = append(pairs, "<"+k+">", v) - } - return strings.NewReplacer(pairs...).Replace(body), nil -} diff --git a/internal/bashupgrade/steps_unit_test.go b/internal/bashupgrade/steps_unit_test.go deleted file mode 100644 index adf03e362..000000000 --- a/internal/bashupgrade/steps_unit_test.go +++ /dev/null @@ -1,127 +0,0 @@ -package bashupgrade - -import ( - "reflect" - "strings" - "testing" -) - -const sampleGuide = "# Guide\n\n\n\n```sh\ncd \ndocket repository prepare\n```\n\nProse.\n\n```sh\ncurl -fsSLO https://example.invalid/docket/install.sh\n```\n\n\n```sh\n$ docket repository check\n```\n" - -func TestParseGuideOrderAndFences(t *testing.T) { - g, err := parseGuide(sampleGuide) - if err != nil { - t.Fatal(err) - } - var names []string - for _, s := range g.Steps { - names = append(names, s.Name) - } - if !reflect.DeepEqual(names, []string{"repo-prepare", "repo-check"}) { - t.Fatalf("steps = %v", names) - } - if g.Steps[0].Body != "cd \ndocket repository prepare\n" { - t.Fatalf("body = %q", g.Steps[0].Body) - } - if len(g.Unmarked) != 1 || !strings.Contains(g.Unmarked[0].Body, "curl") { - t.Fatalf("unmarked = %#v", g.Unmarked) - } -} - -func TestParseGuideRejects(t *testing.T) { - for name, src := range map[string]string{ - "marker without fence": "\nprose\n", - "malformed marker": "\n```sh\nx\n```\n", - "duplicate": "\n```\nx\n```\n\n```\ny\n```\n", - "unterminated": "\n```\nx\n", - } { - if _, err := parseGuide(src); err == nil { - t.Errorf("%s: parseGuide accepted it", name) - } - } -} - -func TestDocketCommandLines(t *testing.T) { - got := docketCommandLines("cd \n docket version\n$ docket install check\n# docket in a comment\ncurl https://x/docket/install.sh\ndocketx run\n") - want := []string{"docket version", "docket install check"} - if !reflect.DeepEqual(got, want) { - t.Fatalf("got %v", got) - } -} - -// TestDocketCommandLinesShapes: docket counts as a command wherever a shell command -// word can stand, and never as an argument, a value, or part of a longer word. -func TestDocketCommandLinesShapes(t *testing.T) { - for name, line := range map[string]string{ - "line start": "docket version", - "prompt": "$ docket version", - "after &&": "cd && docket repository check", - "after ||": "false || docket repository check", - "after ;": "cd ; docket repository check", - "after |": "yes | docket repository repair", - "inside $(": "echo \"$(docket version)\"", - "after sudo": "sudo docket install check", - "after VAR=value": "DOCKET_HOME=/x docket install check", - "after quoted VAR": "A='x y' B=\"z\" docket version", - "assignment then sudo": "A=1 sudo docket version", - "path to the binary": "~/.local/bin/docket version", - "after && with no gaps": "cd x&&docket version", - } { - if got := docketCommandLines(line + "\n"); len(got) != 1 { - t.Errorf("%s: %q was not recognised as a docket command (got %q)", name, line, got) - } - } - for name, line := range map[string]string{ - "argument": "echo docket", - "assignment value": "VERSION=docket", - "longer word": "docketx run", - "comment": "# docket version", - "url path segment": "curl https://x/docket/install.sh", - "quoted in echo": "echo 'run docket version'", - "sudo other": "sudo rm -f docket", - "assignment, other": "A=1 rm docket", - } { - if got := docketCommandLines(line + "\n"); len(got) != 0 { - t.Errorf("%s: %q was taken for a docket command", name, line) - } - } -} - -func TestSubstitutePlaceholders(t *testing.T) { - out, err := substitutePlaceholders("cd \n", map[string]string{"repo": "/r"}) - if err != nil || out != "cd /r\n" { - t.Fatalf("got %q, %v", out, err) - } - if _, err := substitutePlaceholders("cd \n", map[string]string{"repo": "/r"}); err == nil { - t.Fatal("an unknown placeholder was accepted") - } -} - -func TestDispatchBlockSpan(t *testing.T) { - const s, e = "", "" - for _, tc := range []struct { - name string - lines []string - start, end int - bad bool - }{ - {"balanced", []string{"x", s, "body", e, "y"}, 1, 3, false}, - {"absent", []string{"x", "y"}, -1, -1, false}, - {"start only", []string{s, "body"}, 0, 0, true}, - {"end only", []string{"body", e}, 0, 0, true}, - {"out of order", []string{e, "body", s}, 0, 0, true}, - {"two starts", []string{s, s, "body", e}, 0, 0, true}, - {"two ends", []string{s, "body", e, e}, 0, 0, true}, - } { - start, end, err := dispatchBlockSpan(tc.lines) - if tc.bad { - if err == nil { - t.Errorf("%s: want an error, got span %d..%d", tc.name, start, end) - } - continue - } - if err != nil || start != tc.start || end != tc.end { - t.Errorf("%s: got %d..%d, %v; want %d..%d", tc.name, start, end, err, tc.start, tc.end) - } - } -} diff --git a/testdata/README.md b/testdata/README.md index 70ae62868..1f24d7cb9 100644 --- a/testdata/README.md +++ b/testdata/README.md @@ -1,6 +1,6 @@ # testdata — fixture conventions -Three fixture tiers, one rule each: +Two fixture tiers, one rule each: ## Package-local `testdata/` @@ -31,25 +31,3 @@ provenance file. Adding new samples is always fine. directory first and mutates the copy. Tests never write inside `testdata/`. - **Expected outputs live with the test:** expected transformed output belongs beside the owning test (its package `testdata/`), never inside `testdata/repositories/`. - -## Root `testdata/bash-upgrade//` - -Saved Bash-install upgrade cases: the machine and repository state a user had after installing -Bash docket from a release tag (`v0.9.2`, `v0.9.3`) and running a repository through its -`docket`-branch flows. The upgrade test restores each case into a sandbox and drives the upgrade -guide against it. - -- **Made once, from the tag:** each case was built by hand in a throwaway sandbox (temporary - `HOME`, local bare `origin`) by running that tag's own installer and scripts. The tag is the - generator; no generator script is committed. -- **Provenance per tag:** every `/` directory has its own `PROVENANCE.md` recording the tag - and commit, the installer's SHA-256, every command run, what each record exercises, and every - gap. `bash-upgrade/PROVENANCE.md` only points at them. -- **Saved form:** `origin.bundle` (all refs of the sandbox `origin`), `home.tar` (the harness - folders with symlinks kept and the sandbox home rewritten to `@@SANDBOX_HOME@@`), - `clone-config.txt` (clone actions to replay), `records.txt` (the record inventory), and, where - the tag wrote ignored files into the repository's working tree, `clone-files.tar` (those files, - rooted at the clone, in the same tokenized form as `home.tar`). -- **Never edited to make a test pass**, like the samples above: a different state is a new case. - Tests restore into their own temp directories and never write here. -- **Temporary:** the cases and their test are retired when stable v1.0.0 ships. diff --git a/testdata/bash-upgrade/PROVENANCE.md b/testdata/bash-upgrade/PROVENANCE.md deleted file mode 100644 index d3bacfee0..000000000 --- a/testdata/bash-upgrade/PROVENANCE.md +++ /dev/null @@ -1,6 +0,0 @@ -# Provenance — saved Bash-install upgrade cases - -Each tag directory owns its own provenance; this file only points at them. - -- `v0.9.2/` — [`v0.9.2/PROVENANCE.md`](v0.9.2/PROVENANCE.md) -- `v0.9.3/` — [`v0.9.3/PROVENANCE.md`](v0.9.3/PROVENANCE.md) diff --git a/testdata/bash-upgrade/v0.9.2/PROVENANCE.md b/testdata/bash-upgrade/v0.9.2/PROVENANCE.md deleted file mode 100644 index 8eb672da5..000000000 --- a/testdata/bash-upgrade/v0.9.2/PROVENANCE.md +++ /dev/null @@ -1,914 +0,0 @@ -# Provenance — saved Bash docket v0.9.2 install and `docket`-branch repository - -This directory is a saved upgrade case: the state a user had after installing Bash docket from the -`v0.9.2` tag and running one repository through its `docket`-branch flows. It was made once, by -hand, in a throwaway sandbox. The tag is the generator; no generator script is committed. The -scratch helpers used are reproduced verbatim below. - -**Temporary.** This case and the test that reads it are retired when stable v1.0.0 ships. - -## Source - -| Item | Value | -|---|---| -| Tag | `v0.9.2` (annotated tag object `4e199cd0f65de048a248cf0f2f17a60ebc3e217f`) | -| Commit | `ca8251e8bc0a7944ece39dd750b1b159c978f2b3` | -| `install.sh` SHA-256 | `18d46c0489c638827ef56ab85ac39179acb263f2b2ee83a5c0ae72aaae785c71` | -| Date made | 2026-10-04 (UTC; sandbox work began 2026-10-04T18:10:19Z) | -| Host | macOS 27.0 (build 26A428), Darwin 27.0.0 arm64 | -| Bash | GNU bash 5.3.20(1)-release (aarch64-apple-darwin27.0.0), `/opt/homebrew/bin/bash` | -| Git / Python | git 2.55.0 / Python 3.14.7 (Python only for the `home.tar` helper) | - -## Files - -| File | What it is | -|---|---| -| `origin.bundle` | `git bundle create … --all` of the sandbox bare `origin`: `refs/heads/main` (`aea93f28d201f2e49289c3a605de1bd85739a923`), `refs/heads/docket` (`d0ea17ba29702c438b21fe17b559187e8466fc98`) and `HEAD` → `main`, complete history | -| `home.tar` | USTAR tar rooted at the sandbox `HOME`; 197 members, 48 symlinks; mtimes 0, uid/gid 0; `@@SANDBOX_HOME@@` stands for the home path in link targets and file bodies | -| `clone-config.txt` | the clone actions the restore replays (one `worktree`, one `config`, one `hooks-off`) | -| `records.txt` | the 9 records (changes, ADR, specs, learning) the case holds, all on `docket` | - -## Sandbox - -The sandbox root `$SB` was -`/private/tmp/claude-501/-Users-homer-dev-docket/9cbfa2e1-e5f8-4f8a-9555-3ec1f4e089eb/scratchpad/bash-upgrade-v092.apc2fV` -(a session scratchpad, removed afterwards). `HOME` was `$SB/home`. Every command below ran through -the wrapper `$SB/sbx`, written by Step 1; it clears the environment and sets exactly: - -```sh -#!/bin/sh -exec env -i HOME="$SB/home" USER=fixture LOGNAME=fixture SHELL=/bin/zsh TERM=dumb LANG=en_US.UTF-8 \ - XDG_CONFIG_HOME="$SB/home/.config" XDG_DATA_HOME="$SB/home/.local/share" \ - XDG_CACHE_HOME="$SB/home/.cache" XDG_STATE_HOME="$SB/home/.local/state" \ - XDG_BIN_HOME="$SB/home/.local/bin" TMPDIR="$SB/tmp" \ - GIT_CONFIG_GLOBAL="$SB/gitconfig" GIT_CONFIG_NOSYSTEM=1 \ - PATH="$SB/stub-bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin" "$@" -``` - -`/opt/homebrew/bin` holds no `docket`, so it stayed on `PATH`; Bash 4+ was still always named by -its absolute path. A fail-loud `gh` stub sat first on `PATH`; it logs to `$SB/gh-calls.log` and -exits 97. That log never existed at any check, so nothing called `gh`. The real `~/.claude`, -`~/.config/docket`, `~/.zshenv` and `~/dev/docket` were checked with -`find … -newer "$SB/task-start.txt"` after the install and showed nothing newer. - -## Commands, in order - -`$SCRATCH` is the session scratchpad that contains `$SB`. - -### Step 1 — sandbox - -```bash -SB="$(mktemp -d "$SCRATCH/bash-upgrade-v092.XXXXXX")" -mkdir -p "$SB/home" "$SB/stub-bin" "$SB/home/.config" "$SB/home/.local/share" "$SB/home/.cache" "$SB/home/.local/state" -printf '#!/bin/sh\necho "gh stub: network is forbidden in the sandbox: $*" >&2\necho "$*" >> "%s/gh-calls.log"\nexit 97\n' "$SB" > "$SB/stub-bin/gh" -chmod +x "$SB/stub-bin/gh" -printf '[user]\n\tname = Bash Upgrade Fixture\n\temail = fixture@docket.invalid\n[init]\n\tdefaultBranch = main\n' > "$SB/gitconfig" -cat > "$SB/sbx" < HOME=$SB/home / no docket on PATH / 0 -``` - -### Step 2 — the tag, checked out into the sandbox home - -```bash -"$SB/sbx" git clone --quiet --branch v0.9.2 --depth 1 file:///Users/homer/dev/docket "$SB/home/dev/docket" -"$SB/sbx" git -C "$SB/home/dev/docket" remote remove origin -git -C /Users/homer/dev/docket rev-parse 'v0.9.2^{commit}' # ca8251e8bc0a7944ece39dd750b1b159c978f2b3 -"$SB/sbx" git -C "$SB/home/dev/docket" rev-parse HEAD # ca8251e8bc0a7944ece39dd750b1b159c978f2b3 -shasum -a 256 "$SB/home/dev/docket/install.sh" # 18d46c04…785c71 -``` - -`~/dev/docket` is the tag's default checkout location, so the skill links look like a real user's. - -### Step 3 — harness folders and the tag's installer - -`link-skills.sh` (`HARNESS_SKILL_DIRS`) targets `.claude`, `.codex`, `.cursor`, `.agents`, `.kiro` -and `.windsurf` `skills/`; `sync-agents.sh` writes `./agents` for every token in -`DOCKET_GI_HARNESS_TOKENS` (`claude codex cursor opencode agents kiro windsurf`) whose parent -exists. The tag's README names `~/.agents/skills` as where OpenCode reads skills and -`.opencode/agents/` as its agent root. So the parents for Claude Code, Cursor, Codex and OpenCode -were created, and `.kiro` and `.windsurf` were not: - -```bash -date -u +%Y-%m-%dT%H:%M:%SZ > "$SB/task-start.txt" # 2026-10-04T18:10:19Z -mkdir -p "$SB/home/.claude" "$SB/home/.cursor" "$SB/home/.codex" "$SB/home/.opencode" "$SB/home/.agents" -"$SB/sbx" sh -c 'cd "$HOME/dev/docket" && /opt/homebrew/bin/bash ./install.sh' > "$SB/install.log" 2>&1 # exit 0 -find ~/.claude/agents ~/.claude/skills ~/.claude/settings.json ~/.claude/CLAUDE.md ~/.zshenv ~/.config/docket -newer "$SB/task-start.txt" # (no output) -``` - -One attempt; it ended `docket: install complete`. Its output, apart from the 48 `linked …` lines: - -```text -==> ensure-global-config.sh (configure Bash runtime) -docket: wrote $SB/home/.config/docket/config.yml (pointer config plus managed runtime.bash) -==> link-skills.sh (install skills) - -Created: 48 Skipped (already present): 0 -==> sync-agents.sh (generate agent wrappers) -sync-agents: WARN agents/docket-: no harness-specific model — generated unpinned; harness 'agents' will apply its own default. … (once per agent, 16 lines) -sync-agents: WARN harness 'agents' has no named emitter — its wrappers are Claude-shaped and unverified for 'agents', … (ADR-0060). … -sync-agents: done -==> ensure-docket-env.sh (export Docket runtime environment) -ensure-docket-env: wrote DOCKET_SCRIPTS_DIR and DOCKET_BASH_PATH -> $SB/home/.zshenv (zsh) -ensure-docket-env: set env.DOCKET_SCRIPTS_DIR and env.DOCKET_BASH_PATH -> .claude/settings.json -docket: install complete -``` - -### Step 4 — consuming repository and the empty-orphan bootstrap - -```bash -"$SB/sbx" git init --quiet --bare -b main "$SB/origin.git" -"$SB/sbx" git clone --quiet "$SB/origin.git" "$SB/home/dev/sample" -"$SB/sbx" sh -c 'cd "$HOME/dev/sample" && printf "# sample\n" > README.md && git add README.md && git commit -qm "initial" && git push -q origin main && git remote set-head origin main' -"$SB/sbx" sh -c 'cd "$HOME/dev/sample" && export DOCKET_SCRIPTS_DIR="$HOME/dev/docket/scripts" DOCKET_BASH_PATH=/opt/homebrew/bin/bash && "$DOCKET_BASH_PATH" "$DOCKET_SCRIPTS_DIR/docket-config.sh" --export --bootstrap' > "$SB/bootstrap.out" 2> "$SB/bootstrap.err" # exit 0, BOOTSTRAP=PROCEED -"$SB/sbx" git -C "$SB/home/dev/sample" rev-parse 'origin/docket^{tree}' # 4b825dc642cb6eb9a060e54bf8d69288fbee4904 -"$SB/sbx" sh -c 'cd "$HOME/dev/sample" && git add .gitignore && git commit -qm "chore: commit docket managed .gitignore block" && git push -q origin main' -"$SB/sbx" sh -c 'cd "$HOME/dev/sample" && export DOCKET_SCRIPTS_DIR="$HOME/dev/docket/scripts" DOCKET_BASH_PATH=/opt/homebrew/bin/bash && "$DOCKET_BASH_PATH" "$DOCKET_SCRIPTS_DIR/docket.sh" preflight' > "$SB/preflight.out" 2> "$SB/preflight.err" # exit 0 -``` - -- **Bootstrap kind:** the empty-orphan `CREATE_ORPHAN` cell. `docket-config.sh --bootstrap` made a - root commit `c1ea581` (`docket: initialize empty orphan metadata branch`) on the empty tree, - pushed it straight to `origin/docket`, and seeded the managed `.gitignore` block with a - `COMMIT THIS` notice. That block was committed on `main` as above. -- **`.docket.yml`:** the fresh-repository path needs none (`metadata_branch` defaults to `docket`), - so none was committed. `main` has no `.docket.yml`. -- **`.docket` worktree command:** the tag's skills create it through `docket.sh preflight` - (`scripts/lib/docket-preflight.sh` `docket_preflight`), which ran - `git -C worktree add .docket docket` (git's DWIM made a local `docket` tracking - `origin/docket`). Its fallback, `git worktree add .docket origin/docket`, was not needed. It then - ran `disable-worktree-hooks.sh --worktree .docket`, which set `extensions.worktreeConfig=true` and - the worktree-scoped `core.hooksPath=/.git/docket/empty-hooks`. - -### Step 5 — populate through the tag's flows - -```bash -mkdir -p "$SB/snap-pre-populate" && cp -Rp "$SB/origin.git" "$SB/home/dev/sample" "$SB/snap-pre-populate/" -"$SB/sbx" /opt/homebrew/bin/bash "$SCRATCH/populate-v092.sh" > "$SB/populate.log" 2>&1 -``` - -Three runs; each failed one was reset from the snapshot -(`rm -rf "$SB/origin.git" "$SB/home/dev/sample" && cp -Rp "$SB/snap-pre-populate/origin.git" "$SB/" && cp -Rp "$SB/snap-pre-populate/sample" "$SB/home/dev/"`) -so the saved history holds only the third run: - -1. **Failed (exit 1)** in change 1's archive step. The merge date came from - `TZ=UTC git show -s --date=format-local:%Y-%m-%d HEAD`, the form the tag's - `skills/docket-convention/references/terminal-close-out.md` step 1 prints. Without `--format` - that prints the whole commit header, so `archive-change.sh --date` got a multi-line value and - `git mv` failed. Fix: add `--format=%ad`. -2. **Failed (exit 1)** in change 2's close-out. Re-rendering the archived file's `## Artifacts` - block changed no bytes (a trivial change with no spec), and the follow-on `git commit` refused - an empty commit. Fix: make that follow-on commit only when the file changed. -3. **Succeeded (exit 0)**, with no `gh` call. The script below is that final version. - -Tag scripts used, all as subprocesses through `docket.sh` (counts from the final log): -`preflight` ×7, `docket-status --board-only [--must-land]` ×11, `render-change-links` ×9, -`render-artifact-backlink` ×7, `render-adr-index` ×1, `render-learnings-index` ×1, `mint-stub` ×1, -`archive-change` ×2, `terminal-publish --enabled false` ×2 (each logged `terminal_publish: false — -skipping publish onto main; the record stays on docket`) and `cleanup-feature-branch` ×2. - -`$SCRATCH/populate-v092.sh`, final version, verbatim: - -```bash -#!/opt/homebrew/bin/bash -# populate-v092.sh — scratch driver (never committed) that populates the v0.9.2 sample repository -# through the tag's own scripts. Run ONLY through the sandbox wrapper: -# "$SB/sbx" /opt/homebrew/bin/bash "$SCRATCH/populate-v092.sh" -# It never sources a tag script; every tag script runs as a subprocess via docket.sh. -set -euo pipefail - -export DOCKET_SCRIPTS_DIR="$HOME/dev/docket/scripts" -export DOCKET_BASH_PATH=/opt/homebrew/bin/bash -R="$HOME/dev/sample" -M="$R/.docket" -C="$M/docs/changes" -A="$M/docs/adrs" -SPECS="$M/docs/superpowers/specs" -TODAY="$(date -u +%F)" -cd "$R" - -dk(){ echo "+ docket.sh $*" >&2; "$DOCKET_BASH_PATH" "$DOCKET_SCRIPTS_DIR/docket.sh" "$@"; } -ghcheck(){ if [ -e "$HOME/../gh-calls.log" ]; then echo "FATAL: gh was called:" >&2; cat "$HOME/../gh-calls.log" >&2; exit 97; fi; } -# metadata commit: explicit paths only, then push origin/docket -mcommit(){ local msg="$1"; shift; git -C "$M" add -- "$@"; git -C "$M" commit -q -m "$msg" -- "$@"; git -C "$M" push -q origin docket; ghcheck; } -board(){ dk docket-status --board-only --must-land; ghcheck; } -now(){ date -u +%Y-%m-%dT%H:%M:%SZ; } -# fm_set FILE KEY VALUE — set a frontmatter field inside the FIRST ---…--- block only -# (append before the closing --- when absent). -fm_set(){ - local f="$1" k="$2" v="$3" tmp - tmp="$(mktemp "$(dirname "$f")/.fmset.XXXXXX")" - awk -v k="$k" -v v="$v" ' - BEGIN{n=0; done=0} - /^---[[:space:]]*$/ { n++; if (n==2 && !done) { print k ": " v; done=1 } print; next } - n==1 && !done && index($0, k ":")==1 { print k ": " v; done=1; next } - { print } - ' "$f" > "$tmp" - mv -f "$tmp" "$f" -} -change_links(){ dk render-change-links --change-file "$1" --adrs-dir "$A"; } - -dk preflight >/dev/null -mkdir -p "$C/active" "$SPECS" "$A" - -# --------------------------------------------------------------------------------------------- -# 0001 — brainstorm-mode change with a spec, later built, merged and closed out as done. -# docket-new-change Brainstorm mode (steps 1, 4, 5); spec + change body hand-authored. -# --------------------------------------------------------------------------------------------- -S1="docs/superpowers/specs/$TODAY-add-a-greeting-script-design.md" -cat > "$M/$S1" <<'EOF' -# Add a greeting script — design - -## Purpose - -Give the sample repository a tiny executable so later changes have code to build on. - -## Design - -A POSIX `sh` script, `hello.sh`, prints `hello, ` for its first argument and `hello, world` -when called with none. No dependencies. - -## Testing - -`sh hello.sh` prints `hello, world`; `sh hello.sh docket` prints `hello, docket`. -EOF -F1="$C/active/0001-add-a-greeting-script.md" -cat > "$F1" < - - -## Why - -The sample repository has no code yet. A small greeting script gives later changes something to -build on and proves the build loop end to end. - -## What changes - -Add \`hello.sh\`, which greets its first argument or the world. - -## Out of scope - -Localisation and any configuration file. - -## Reconcile log -EOF -change_links "$F1" -dk render-artifact-backlink --artifact-file "$M/$S1" --change-file "$F1" -mcommit "docket(0001): new change — add a greeting script (spec)" "docs/changes/active/0001-add-a-greeting-script.md" "$S1" -board - -# --------------------------------------------------------------------------------------------- -# 0002 — trivial-mode change, later built, merged and closed out as done. -# --------------------------------------------------------------------------------------------- -F2="$C/active/0002-document-the-greeting-script.md" -cat > "$F2" < - - -## Why - -The README does not say how to run the greeting script. - -## What changes - -Add a short *Usage* section to \`README.md\`. - -## Out of scope - -Any change to the script itself. - -## Reconcile log -EOF -mcommit "docket(0002): new change — document the greeting script (trivial)" "docs/changes/active/0002-document-the-greeting-script.md" -board - -# --------------------------------------------------------------------------------------------- -# Build + merge + close-out helper for a done change (docket-implement-next steps 2-7, then a -# local merge standing in for the GitHub PR merge, then docket-finalize-change's close-out). -# --------------------------------------------------------------------------------------------- -build_and_close(){ - local id="$1" slug="$2" pr="$3" codefile="$4" codebody="$5" adr="$6" - local pad; pad="$(printf '%04d' "$id")" - local F="$C/active/$pad-$slug.md" rel="docs/changes/active/$pad-$slug.md" - local W="$R/.worktrees/$slug" - local plan="docs/superpowers/plans/$TODAY-$slug.md" - local results="docs/results/$TODAY-$pad-$slug.md" - - # Step 2 — claim - dk preflight >/dev/null - fm_set "$F" status in-progress - fm_set "$F" branch "feat/$slug" - fm_set "$F" updated "$TODAY" - fm_set "$F" claimed_at "$(now)" - mcommit "docket($pad): claim — in-progress on feat/$slug" "$rel" - dk docket-status --board-only || echo "best-effort board pass failed (continuing)" >&2; ghcheck - - # Step 3 — reconcile (no drift): reconciled: true + a dated reconcile-log entry - fm_set "$F" reconciled true - fm_set "$F" claimed_at "$(now)" - printf '\n- %s — reconciled against main: no drift.\n' "$TODAY" >> "$F" - mcommit "docket($pad): reconcile — no drift" "$rel" - - # Step 4 — feature worktree + plan (plan back-link stamped on the feature branch) - git fetch -q origin - git worktree add -q "$W" -b "feat/$slug" origin/main - mkdir -p "$W/docs/superpowers/plans" "$W/docs/results" - printf '# %s Implementation Plan\n\n### Task 1\n\n- [ ] Write `%s`.\n' "$(sed -n 's/^title: //p' "$F" | head -n 1)" "$codefile" > "$W/$plan" - dk render-artifact-backlink --artifact-file "$W/$plan" --change-file "$F" - git -C "$W" add -- "$plan" - git -C "$W" commit -q -m "docs(plan): $slug implementation plan" -- "$plan" - fm_set "$F" plan "$plan" - fm_set "$F" claimed_at "$(now)" - change_links "$F" - mcommit "docket($pad): plan" "$rel" - - # Step 5 — build - printf '%s' "$codebody" > "$W/$codefile" - git -C "$W" add -- "$codefile" - git -C "$W" commit -q -m "$( [ "$codefile" = hello.sh ] && echo feat || echo docs ): $slug" -- "$codefile" - - # Step 6 — review; optional ADR via the docket-adr flow (ADR commit, then separate index commit) - if [ -n "$adr" ]; then - local adrfile="docs/adrs/0001-greeting-script-is-posix-sh.md" - cat > "$M/$adrfile" < "$A/README.md" - mcommit "docket(adr): regenerate ADR index" "docs/adrs/README.md" - fm_set "$F" adrs "[1]" - fm_set "$F" claimed_at "$(now)" - change_links "$F" - mcommit "docket($pad): adrs [1]" "$rel" - fi - - # Step 6.5 — results file on the feature branch, with its back-link - printf '# Results — %s\n\nBuilt as planned. Manual check: the change does what its plan says.\n' "$slug" > "$W/$results" - dk render-artifact-backlink --artifact-file "$W/$results" --change-file "$F" - git -C "$W" add -- "$results" - git -C "$W" commit -q -m "docs(results): $slug" -- "$results" - git -C "$W" push -q origin "feat/$slug" - ghcheck - - # Step 7 — implemented + pr: (+ results:) — PR opening itself needs gh (stubbed out: gap) - fm_set "$F" status implemented - fm_set "$F" pr "$pr" - fm_set "$F" results "$results" - fm_set "$F" claimed_at "$(now)" - change_links "$F" - mcommit "docket($pad): implemented — PR open" "$rel" - dk docket-status --board-only || echo "best-effort board pass failed (continuing)" >&2; ghcheck - - # Merge: a local --no-ff merge of feat/ into main stands in for GitHub's PR merge. - git checkout -q main - git pull -q --ff-only origin main - git merge -q --no-ff "feat/$slug" -m "Merge pull request #${pr##*/} from fixture/feat/$slug" - git push -q origin main - ghcheck - local mdate; mdate="$(TZ=UTC git show -s --format=%ad --date=format-local:%Y-%m-%d HEAD)" - - # Finalize close-out (terminal-close-out.md): harvest -> archive -> re-render -> publish -> cleanup -> board - dk preflight >/dev/null - if [ -n "$adr" ]; then - mkdir -p "$C/learnings" - cat > "$C/learnings/posix-sh-means-no-arrays.md" < "$tmp" && [ -s "$tmp" ] && mv -f "$tmp" "$C/learnings/README.md" || rm -f "$tmp" - mcommit "docket($pad): harvest learnings" "docs/changes/learnings/posix-sh-means-no-arrays.md" "docs/changes/learnings/README.md" - fi - dk archive-change --changes-dir "$C" --id "$id" --outcome done --date "$mdate" --results "$results" \ - --message "docket($pad): done — archived (status done, $mdate)" - ghcheck - local AF="$C/archive/$mdate-$pad-$slug.md" arel="docs/changes/archive/$mdate-$pad-$slug.md" - change_links "$AF" - local spec; spec="$(awk '/^---[[:space:]]*$/{n++; next} n==1 && /^spec:/{sub(/^spec:[[:space:]]*/, ""); print; exit}' "$AF")" - if [ -n "$spec" ]; then - dk render-artifact-backlink --artifact-file "$M/$spec" --change-file "$AF" - mcommit "docket($pad): re-render artifacts after archive" "$arel" "$spec" - elif [ -n "$(git -C "$M" status --porcelain -- "$arel")" ]; then - mcommit "docket($pad): re-render artifacts after archive" "$arel" - else - echo "re-render after archive: block unchanged for $pad — no follow-on commit" >&2 - fi - dk terminal-publish --id "$id" --outcome done --integration-branch main --metadata-branch docket \ - --changes-dir docs/changes --adrs-dir docs/adrs --enabled false --metadata-worktree "$M" - ghcheck - dk cleanup-feature-branch --slug "$slug" - ghcheck - board -} - -build_and_close 1 add-a-greeting-script "https://github.com/fixture/sample/pull/1" hello.sh \ - '#!/bin/sh -# hello.sh — greet the first argument, or the world. -printf "hello, %s\n" "${1:-world}" -' adr - -build_and_close 2 document-the-greeting-script "https://github.com/fixture/sample/pull/2" USAGE.md \ - '# Usage - -Run `sh hello.sh [name]`. With no name it greets the world. -' "" - -# --------------------------------------------------------------------------------------------- -# 0003 — proposed change with a spec (docket-new-change Brainstorm mode). -# --------------------------------------------------------------------------------------------- -dk preflight >/dev/null -S3="docs/superpowers/specs/$TODAY-add-a-farewell-script-design.md" -cat > "$M/$S3" <<'EOF' -# Add a farewell script — design - -## Purpose - -Pair the greeting script with a farewell, so the sample has two commands. - -## Design - -`bye.sh` prints `goodbye, `, defaulting to `goodbye, world`. It reuses the greeting script's -POSIX `sh` rule (ADR-0001). - -## Testing - -`sh bye.sh` prints `goodbye, world`. -EOF -F3="$C/active/0003-add-a-farewell-script.md" -cat > "$F3" < - - -## Why - -A greeting without a farewell is half a conversation. - -## What changes - -Add \`bye.sh\`, the counterpart of \`hello.sh\`. - -## Out of scope - -Merging the two scripts into one. - -## Reconcile log -EOF -change_links "$F3" -dk render-artifact-backlink --artifact-file "$M/$S3" --change-file "$F3" -mcommit "docket(0003): new change — add a farewell script (spec)" "docs/changes/active/0003-add-a-farewell-script.md" "$S3" -board - -# --------------------------------------------------------------------------------------------- -# 0004 — trivial proposed change (docket-new-change Trivial mode). -# --------------------------------------------------------------------------------------------- -F4="$C/active/0004-add-a-license-file.md" -cat > "$F4" < - - -## Why - -The sample repository has no license. - -## What changes - -Add an MIT \`LICENSE\` file at the root. - -## Out of scope - -Per-file license headers. - -## Reconcile log -EOF -mcommit "docket(0004): new change — add a license file (trivial)" "docs/changes/active/0004-add-a-license-file.md" -board - -# --------------------------------------------------------------------------------------------- -# 0005 — a discovered-work stub minted by the tag's mint-stub.sh, then deferred through the -# docket-groom-next Defer exit (status: deferred + ## Why deferred + updated:). -# --------------------------------------------------------------------------------------------- -BODY="$(mktemp "$TMPDIR/stub-body.XXXXXX")" -cat > "$BODY" <<'EOF' -## Why - -The greeting script could read a default name from an environment variable, which the review of -change 1 suggested but did not need. - -## What changes - -Read `HELLO_NAME` when no argument is given. - -## Open questions - -- Should an empty `HELLO_NAME` count as unset? -EOF -dk mint-stub --changes-dir "$C" --title "Read the default greeting name from the environment" --type feat \ - --body-file "$BODY" --discovered-from 1 --metadata-branch docket -ghcheck -F5="$(ls "$C"/active/0005-*.md)" -rel5="docs/changes/active/$(basename "$F5")" -dk preflight >/dev/null -fm_set "$F5" status deferred -fm_set "$F5" updated "$TODAY" -printf '\n## Why deferred\n\nRight idea, wrong time: nobody has asked for it yet. Revisit when a caller needs it.\n' >> "$F5" -mcommit "docket(0005): defer — right idea, wrong time" "$rel5" -board - -echo "populate-v092: done" -``` - -### Step 6 — resolved configuration (read-only) - -```bash -"$SB/sbx" sh -c 'cd "$HOME/dev/sample" && DOCKET_BASH_PATH=/opt/homebrew/bin/bash /opt/homebrew/bin/bash "$HOME/dev/docket/scripts/docket-config.sh" --export' > "$SB/config-export.txt" # exit 0 -``` - -No config edits were made. `config-export.txt`: - -```text -DOCKET_MODE=docket -DEFAULT_BRANCH=main -METADATA_BRANCH=docket -INTEGRATION_BRANCH=main -METADATA_WORKTREE=.docket -DOCKET_BASH_PATH=/opt/homebrew/bin/bash -CHANGES_DIR=docs/changes -ADRS_DIR=docs/adrs -RESULTS_DIR=docs/results -FINALIZE_GATE=local -FINALIZE_TEST_COMMAND='' -FINALIZE_REQUIRE_PR_APPROVAL=false -FINALIZE_SKIP_RESULTS_ONLY_DELTA=false -LEARNINGS_ENABLED=true -LEARNINGS_CAP=300 -BOARD_SURFACES=inline -AUTO_GROOM=false -CHANGE_TYPES=chore\ docs\ feat\ fix\ refactor\ perf -AUTO_CAPTURE_ENABLED=false -AUTO_CAPTURE_TYPES=all -TERMINAL_PUBLISH=false -RECLAIM_LEASE_TTL=72 -RECLAIM_AUTO=false -BUILD_CHECKPOINT=false -REVIEW_MIN_FIX_SEVERITY=minor -REVIEW_MAX_FIX_TASKS=10 -GATE_OBSERVATION_BUDGET=30 -DELEGATION_OBSERVATION_BUDGET=60 -SKILL_BRAINSTORM=superpowers:brainstorming -SKILL_PLAN=superpowers:writing-plans -SKILL_BUILD=docket-build -SKILL_REVIEW=docket-review -SKILL_FINISH=superpowers:finishing-a-development-branch -DUMMY_MODE_ENABLED=false -DUMMY_MODE_PERSONA=A\ mid-level\ software\ engineer:\ solid\ grasp\ of\ software\ architecture\ and\ general\ engineering\ concepts\ —\ APIs\,\ testing\,\ CI\,\ version\ control\ —\ but\ only\ working-level\ fluency\ in\ any\ specific\ programming\ language\,\ so\ avoid\ language-specific\ idioms\ unless\ glossed.\ Assume\ no\ familiarity\ with\ this\ project\'s\ internal\ vocabulary\;\ introduce\ each\ project-specific\ term\ with\ a\ one-clause\ explanation. -DUMMY_MODE_SURFACES=all -BOOTSTRAP=PROCEED -``` - -### Step 7 — export - -```bash -OUT=/testdata/bash-upgrade/v0.9.2 -"$SB/sbx" git -C "$SB/origin.git" bundle create "$OUT/origin.bundle" --all -git -C "$SB/origin.git" bundle verify "$OUT/origin.bundle" # okay; refs/heads/docket, refs/heads/main, HEAD; complete history -{ git -C "$SB/origin.git" ls-tree -r --name-only docket | sed 's/^/docket:/'; git -C "$SB/origin.git" ls-tree -r --name-only main | sed 's/^/main:/'; } > "$SB/all-paths.txt" -grep -E -e '^(docket|main):docs/changes/(active|archive)/[^/]+\.md$' -e '^(docket|main):docs/adrs/[0-9][^/]*\.md$' -e '^(docket|main):docs/superpowers/specs/[^/]+\.md$' -e '^(docket|main):docs/changes/learnings/[^/]+\.md$' "$SB/all-paths.txt" | grep -v -e '/README\.md$' | LC_ALL=C sort > "$OUT/records.txt" -rm -rf "$SB/freshclone"; "$SB/sbx" git clone -q "$SB/origin.git" "$SB/freshclone" -"$SB/sbx" git -C "$SB/freshclone" config --local --list | sort > "$SB/cfg-fresh.txt" -"$SB/sbx" git -C "$SB/home/dev/sample" config --local --list | sort > "$SB/cfg-sample.txt" -diff "$SB/cfg-fresh.txt" "$SB/cfg-sample.txt" -# > branch.docket.merge=refs/heads/docket -# > branch.docket.remote=origin -# > extensions.worktreeconfig=true -"$SB/sbx" git -C "$SB/home/dev/sample/.docket" config --worktree --list -# core.hookspath=$SB/home/dev/sample/.git/docket/empty-hooks -python3 "$SCRATCH/make-home-tar.py" "$SB/home" "$OUT/home.tar" # members: 197 -tar -xOf "$OUT/home.tar" | grep -c -e "$SB" || true # 0 -tar -xOf "$OUT/home.tar" | grep -c -e "/tmp/claude-501" || true # 0 (the /tmp spelling of the same path) -tar -tvf "$OUT/home.tar" | grep -c -e '^l' # 48 -``` - -`clone-config.txt` keeps `worktree .docket docket` and `config extensions.worktreeConfig true`, in -the order the tag made them. `branch.docket.*` comes from the worktree add itself. The -worktree-scoped `core.hooksPath` cannot be written as a `config` line (that is -`git config --local`), so it is the third line, `hooks-off .docket`: the restore creates -`/docket/empty-hooks` and sets the `.docket` worktree's `core.hooksPath` to it, as -the tag's `disable-worktree-hooks.sh` did. (This line was added with the restore harness; without -it the restored `.docket` worktree had hooks enabled, a state the tag never leaves.) - -`$SCRATCH/make-home-tar.py`, verbatim: - -```python -#!/usr/bin/env python3 -"""make-home-tar.py SANDBOX_HOME OUT_TAR — scratch helper (never committed). - -Writes an uncompressed USTAR tar rooted at SANDBOX_HOME holding only the harness folders, the -docket skills tree the skill links point at, and the shell profile the tag's ensure-docket-env.sh -wrote. Every absolute sandbox-home prefix (and its realpath / /tmp spelling) in a symlink target or -regular-file body becomes @@SANDBOX_HOME@@. mtimes are zeroed, uid/gid 0, no user/group names. -""" -import io -import os -import sys -import tarfile - -home = sys.argv[1].rstrip("/") -out = sys.argv[2] -TOKEN = "@@SANDBOX_HOME@@" - -INCLUDE = [".claude", ".cursor", ".codex", ".agents", ".opencode", ".config/docket", - "dev/docket/skills", ".zshenv"] - -real = os.path.realpath(home) -spellings = {home, real} -for s in list(spellings): - if s.startswith("/private/"): - spellings.add(s[len("/private"):]) -# longest first so "/private/tmp/x" is rewritten before "/tmp/x" can match inside it -spellings = sorted(spellings, key=len, reverse=True) - - -def rewrite(text): - for s in spellings: - text = text.replace(s, TOKEN) - return text - - -def norm(ti): - ti.mtime = 0 - ti.uid = ti.gid = 0 - ti.uname = ti.gname = "" - return ti - - -members = [] -for top in INCLUDE: - p = os.path.join(home, top) - if not os.path.lexists(p): - sys.exit("missing include: " + top) - if os.path.isdir(p) and not os.path.islink(p): - for root, dirs, files in os.walk(p, followlinks=False): - dirs.sort() - members.append(root) - for name in sorted(files + [d for d in dirs if os.path.islink(os.path.join(root, d))]): - members.append(os.path.join(root, name)) - # symlinked dirs must not be descended into - dirs[:] = [d for d in dirs if not os.path.islink(os.path.join(root, d))] - else: - members.append(p) - -# parents of nested includes (".config", "dev", "dev/docket") so extraction recreates them -parents = set() -for top in INCLUDE: - parts = top.split("/")[:-1] - for i in range(1, len(parts) + 1): - parents.add("/".join(parts[:i])) - -seen = set() -with tarfile.open(out, "w", format=tarfile.USTAR_FORMAT) as tf: - for rel in sorted(parents): - ti = norm(tf.gettarinfo(os.path.join(home, rel), arcname=rel)) - tf.addfile(ti) - for path in members: - rel = os.path.relpath(path, home) - if rel in seen: - continue - seen.add(rel) - ti = norm(tf.gettarinfo(path, arcname=rel)) - if ti.issym(): - ti.linkname = rewrite(ti.linkname) - tf.addfile(ti) - elif ti.isfile(): - with open(path, "rb") as fh: - data = fh.read() - try: - data = rewrite(data.decode("utf-8")).encode("utf-8") - except UnicodeDecodeError: - for s in spellings: - data = data.replace(s.encode(), TOKEN.encode()) - ti.size = len(data) - tf.addfile(ti, io.BytesIO(data)) - elif ti.isdir(): - tf.addfile(ti) - else: - sys.exit("unexpected member type: " + rel) -print("members:", len(seen) + len(parents)) -``` - -## What `home.tar` holds - -| Folder | Written by | Contents | -|---|---|---| -| `.claude/` | `link-skills.sh`, `sync-agents.sh`, `ensure-docket-env.sh` | `skills/docket-*` (12 symlinks), `agents/docket-*.md` (16), `settings.json` with an `env` block setting `DOCKET_SCRIPTS_DIR` and `DOCKET_BASH_PATH` | -| `.cursor/` | same | `skills/` (12 symlinks), `agents/` (16), `rules/docket-dispatch.mdc` | -| `.codex/` | same | `skills/` (12 symlinks), `agents/docket-*.toml` (16). **Saved, never asserted.** | -| `.agents/` | same | `skills/` (12 symlinks, OpenCode's skill root), `agents/` (16, Claude-shaped, unpinned) | -| `.opencode/` | `sync-agents.sh` | `agents/docket-*.md` (16) | -| `.config/docket/` | `ensure-global-config.sh` | `config.yml` with the managed `runtime.bash` block | -| `dev/docket/skills/` | the tag checkout | the tree every skill symlink points at | -| `.zshenv` | `ensure-docket-env.sh` | the managed `DOCKET_SCRIPTS_DIR` / `DOCKET_BASH_PATH` export block | - -Not saved: `dev/sample` (it is the bundle plus `clone-config.txt`), `.cache`, `.local`, and the rest -of `dev/docket`. So after a restore, `DOCKET_SCRIPTS_DIR` in `.zshenv` and `settings.json` points at -`@@SANDBOX_HOME@@/dev/docket/scripts`, which does not exist. - -v0.9.2 wrote **no** `~/.claude/CLAUDE.md` and no dispatch block anywhere under the home. Its only -dispatch artifact is Cursor's `rules/docket-dispatch.mdc`. - -## Records - -| `records.txt` entry | Exercises | -|---|---| -| `docket:docs/adrs/0001-greeting-script-is-posix-sh.md` | ADR, `Accepted`, `change: 1`, made by the `docket-adr` flow (ADR commit, then a separate index commit) | -| `docket:docs/changes/active/0003-add-a-farewell-script.md` | proposed + spec (Brainstorm mode), `related: [1]`, priority `high` | -| `docket:docs/changes/active/0004-add-a-license-file.md` | trivial proposed (`trivial: true`, no spec) | -| `docket:docs/changes/active/0005-read-the-default-greeting-name-from-the-environment.md` | deferred: minted by `mint-stub.sh` (`discovered_from: [1]`, single-quoted `title:` written by the script), then the groom Defer exit | -| `docket:docs/changes/archive/2026-10-04-0001-add-a-greeting-script.md` | done #1: spec, plan, results, `adrs: [1]`, `pr:`, `reconciled: true`, `claimed_at:` left empty by `archive-change.sh` | -| `docket:docs/changes/archive/2026-10-04-0002-document-the-greeting-script.md` | done #2: trivial, `depends_on: [1]`, plan, results, `pr:`, empty `claimed_at:` | -| `docket:docs/changes/learnings/posix-sh-means-no-arrays.md` | learning from the finalize harvest; double-quoted `hook:` with `\"` escapes | -| `docket:docs/superpowers/specs/2026-10-04-add-a-farewell-script-design.md` | spec of 0003, back-link to `active/` | -| `docket:docs/superpowers/specs/2026-10-04-add-a-greeting-script-design.md` | spec of 0001, back-link re-stamped to `archive/` | - -Counts: 5 changes (3 active, 2 archived), 1 ADR, 2 specs, 1 learning. Also on `docket`, but not -records: `docs/changes/BOARD.md` (rendered by the tag's board pass), `docs/adrs/README.md` and -`docs/changes/learnings/README.md` (tag-rendered indexes). On `main`: `README.md`, `.gitignore` -(the managed block), `hello.sh`, `USAGE.md`, the two plans and the two results files. Nothing was -published to `main`, so `records.txt` has no `main:` entries. - -**Empty categories** (a saved case only covers what it contains): no in-progress, implemented, -blocked or killed change; no superseded or reversed ADR; no stacked change; no `.docket.yml` and -no `.docket.local.yml`; no per-repository agent wrappers (the repo never opted in with -`agents:` or `agent_harnesses:`); no change with a `## Run halted` section; no record on `main`. - -## Gaps - -- **Interactive steps were hand-written** to the tag's prescribed shape: the specs and change - bodies (`skills/docket-new-change/SKILL.md` Brainstorm and Trivial modes, steps 4–5, using - `change-template.md`); the claim, reconcile, `plan:`, `adrs:`, `implemented` + `pr:` + - `results:` field writes (`skills/docket-implement-next/SKILL.md` Steps 2–7 and the field-write - rule, including the `claimed_at` re-stamp); the plan, code and results commits on - `feat/`; the ADR (`skills/docket-adr/SKILL.md` Create, from `adr-template.md`); the defer - (`skills/docket-groom-next/SKILL.md` Step 4 exit 4); and the learning - (`skills/docket-finalize-change/SKILL.md` step 2.5 and `references/learnings.md`). The commit - subjects use a `docket(): …` style. The skills prescribe no exact wording for these. -- **No pull request was opened or merged on GitHub.** `gh` was stubbed out. Each `pr:` holds an - invented `https://github.com/fixture/sample/pull/` URL, and the merge is a local - `git merge --no-ff feat/` on `main` with GitHub's merge-commit subject, pushed to `origin`. - The close-out then ran the tag's terminal close-out sequence, with the merge commit's UTC date. -- **`terminal_publish` is `false` by default at v0.9.2**, so the tag's close-out publishes nothing - onto `main`. The plan's "terminal-published to `main`" became "the publish step ran and skipped, - as the tag does". This keeps the bootstrap's config, the common path. -- **The tag's merge-date command** in `terminal-close-out.md` step 1 needs `--format=%ad` to print - only the date (run 1 above). -- **The worktree-scoped `core.hooksPath`** is not a `git config --local` setting, so - `clone-config.txt` replays it through its `hooks-off` line (see Step 7). diff --git a/testdata/bash-upgrade/v0.9.2/clone-config.txt b/testdata/bash-upgrade/v0.9.2/clone-config.txt deleted file mode 100644 index 4680c7c52..000000000 --- a/testdata/bash-upgrade/v0.9.2/clone-config.txt +++ /dev/null @@ -1,14 +0,0 @@ -# clone-config.txt — actions the restore replays, in order, on a fresh clone of origin.bundle. -# Grammar: `config ` (git config --local) | `worktree ` (git worktree -# add, path relative to the clone root) | `hooks-off ` (what disable-worktree-hooks.sh does to -# that worktree: create /docket/empty-hooks and set the WORKTREE-scoped -# core.hooksPath to it). Recorded from the v0.9.2 sandbox clone; see PROVENANCE.md. -# -# The tag's `docket.sh preflight` ran `git worktree add .docket docket` (DWIM: creates local -# `docket` tracking `origin/docket`, which is where branch.docket.remote/merge come from). -worktree .docket docket -# The tag's disable-worktree-hooks.sh then turned on per-worktree config ... -config extensions.worktreeConfig true -# ... and set the worktree-scoped key on .docket: -# `git -C .docket config --worktree core.hooksPath /.git/docket/empty-hooks`. -hooks-off .docket diff --git a/testdata/bash-upgrade/v0.9.2/home.tar b/testdata/bash-upgrade/v0.9.2/home.tar deleted file mode 100644 index 5a89da9e0..000000000 Binary files a/testdata/bash-upgrade/v0.9.2/home.tar and /dev/null differ diff --git a/testdata/bash-upgrade/v0.9.2/origin.bundle b/testdata/bash-upgrade/v0.9.2/origin.bundle deleted file mode 100644 index d7bd64497..000000000 Binary files a/testdata/bash-upgrade/v0.9.2/origin.bundle and /dev/null differ diff --git a/testdata/bash-upgrade/v0.9.2/records.txt b/testdata/bash-upgrade/v0.9.2/records.txt deleted file mode 100644 index 3516be681..000000000 --- a/testdata/bash-upgrade/v0.9.2/records.txt +++ /dev/null @@ -1,9 +0,0 @@ -docket:docs/adrs/0001-greeting-script-is-posix-sh.md -docket:docs/changes/active/0003-add-a-farewell-script.md -docket:docs/changes/active/0004-add-a-license-file.md -docket:docs/changes/active/0005-read-the-default-greeting-name-from-the-environment.md -docket:docs/changes/archive/2026-10-04-0001-add-a-greeting-script.md -docket:docs/changes/archive/2026-10-04-0002-document-the-greeting-script.md -docket:docs/changes/learnings/posix-sh-means-no-arrays.md -docket:docs/superpowers/specs/2026-10-04-add-a-farewell-script-design.md -docket:docs/superpowers/specs/2026-10-04-add-a-greeting-script-design.md diff --git a/testdata/bash-upgrade/v0.9.3/PROVENANCE.md b/testdata/bash-upgrade/v0.9.3/PROVENANCE.md deleted file mode 100644 index edad024f6..000000000 --- a/testdata/bash-upgrade/v0.9.3/PROVENANCE.md +++ /dev/null @@ -1,1178 +0,0 @@ -# Provenance — saved Bash docket v0.9.3 install and migrated `docket`-branch repository - -This directory is a saved upgrade case: the state a user had after installing Bash docket from the -`v0.9.3` tag, running one repository in single-branch mode, converting it with the tag's -`migrate-to-docket.sh`, working on in `docket` mode, and then committing a `.docket.yml` that sets -every setting the Go binary now refuses or warns about. It was made once, by hand, in a throwaway -sandbox. The tag is the generator; no generator script is committed. The scratch helpers used are -reproduced verbatim below. - -**Temporary.** This case and the test that reads it are retired when stable v1.0.0 ships. - -## Source - -| Item | Value | -|---|---| -| Tag | `v0.9.3` (annotated tag object `5897ac000d2ea69c36a226b9459d925067530190`) | -| Commit | `dd742abd5e9fcdf8ffe78eb6f36a293410873bbf` | -| `install.sh` SHA-256 | `18d46c0489c638827ef56ab85ac39179acb263f2b2ee83a5c0ae72aaae785c71` (byte-identical to v0.9.2's) | -| Date made | 2026-10-04 (UTC; sandbox work began 2026-10-04T18:30:38Z) | -| Host | macOS 27.0 (build 26A428), Darwin 27.0.0 arm64 | -| Bash | GNU bash 5.3.20(1)-release (aarch64-apple-darwin27.0.0), `/opt/homebrew/bin/bash` | -| Git / Python | git 2.55.0 / Python 3.14.7 (Python only for the `home.tar` helper) | - -Between the two tags, the Bash surface changed only in the agent set: v0.9.3 adds -`agents/docket-plan-writer.md` (17 agents instead of 16), its `harness-defaults.yml` rows and its -Cursor dispatch rule, plus skill text in `docket-convention` and `docket-implement-next`. -`scripts/`, `install.sh`, `link-skills.sh` and `migrate-to-docket.sh` are unchanged, and -`sync-agents.sh` differs only in one comment (`git diff --stat v0.9.2 v0.9.3`). - -## Files - -| File | What it is | -|---|---| -| `origin.bundle` | `git bundle create … --all` of the sandbox bare `origin`: `refs/heads/main` (`5654d4f9f09ec3fe04a375b970c41775fa291717`), `refs/heads/docket` (`7a4b3425a4872008e2179df90212803cef99248b`) and `HEAD` → `main`, complete history | -| `home.tar` | USTAR tar rooted at the sandbox `HOME`; 202 members, 48 symlinks; mtimes 0, uid/gid 0; `@@SANDBOX_HOME@@` stands for the home path in link targets and file bodies | -| `clone-config.txt` | the clone actions the restore replays (one `worktree`, one `config`, one `hooks-off`) | -| `records.txt` | the 14 record paths (9 on `docket`, 5 on `main`) the case holds | -| `clone-files.tar` | USTAR tar rooted at the sample clone: its ignored `.claude/` folder, 20 members (`.claude/`, `.claude/agents/`, the 17 per-repository `agents/docket-*.md` wrappers, `settings.local.json`); same normalization and `@@SANDBOX_HOME@@` rule as `home.tar` (no member needed it). Regenerated afterwards from the tag; see Step 10 | - -## The seeded root (what this case exists to prove) - -The v0.9.2 case covers the empty-orphan bootstrap. This case covers the other receiptless legacy -root, the one `migrate-to-docket.sh` writes: a root commit whose tree is a copy of the planning -directories of `main` at the moment of migration. - -| Item | Value | -|---|---| -| Pre-migration `main` tip (the copied snapshot) | `3cc746b36708159334f436ec457477821070edce` (`docket: board refresh`) | -| `docket` root commit | `2e86fd7f8bce29bbf1a47435bbf9f4f092157fde` (`docket: seed metadata branch from main (migrate-to-docket.sh)`), no parents, no trailers | -| Root tree | `db3ba79d84f62347e34dec034cef959e1bba42ad` (not the empty tree `4b825dc…`) | -| `{docs/changes, docs/adrs, docs/superpowers/specs}` projection of `3cc746b` | `db3ba79d84f62347e34dec034cef959e1bba42ad` — equal to the root tree | -| Shared ancestry of `main` and `docket` | none (`git merge-base main docket` exits 1) | - -The seed set was `docs/changes docs/adrs docs/superpowers/specs docs/changes/BOARD.md`; the board -sits inside `docs/changes`, so the root tree is exactly the three-directory projection the Go -binary's `verifyLegacyEquivalence` composes. The `.docket.yml` on `3cc746b` is -`metadata_branch: main` / `integration_branch: main`, so that snapshot's own config resolves the -default directories. - -## Sandbox - -The sandbox root `$SB` was -`/private/tmp/claude-501/-Users-homer-dev-docket/9cbfa2e1-e5f8-4f8a-9555-3ec1f4e089eb/scratchpad/bash-upgrade-v093.GeYYNm` -(a session scratchpad, removed afterwards). `HOME` was `$SB/home`. Every sandbox command below ran -through the wrapper `$SB/sbx`, written by Step 1; it clears the environment and sets exactly: - -```sh -#!/bin/sh -exec env -i HOME="$SB/home" USER=fixture LOGNAME=fixture SHELL=/bin/zsh TERM=dumb LANG=en_US.UTF-8 \ - XDG_CONFIG_HOME="$SB/home/.config" XDG_DATA_HOME="$SB/home/.local/share" \ - XDG_CACHE_HOME="$SB/home/.cache" XDG_STATE_HOME="$SB/home/.local/state" \ - XDG_BIN_HOME="$SB/home/.local/bin" TMPDIR="$SB/tmp" \ - GIT_CONFIG_GLOBAL="$SB/gitconfig" GIT_CONFIG_NOSYSTEM=1 \ - PATH="$SB/stub-bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin" "$@" -``` - -`/opt/homebrew/bin` holds no `docket`, so it stayed on `PATH`; Bash 4+ was still always named by -its absolute path. A fail-loud `gh` stub sat first on `PATH`; it logs to `$SB/gh-calls.log` and -exits 97. That log never existed at any check, so nothing called `gh`. The real `~/.claude`, -`~/.config/docket`, `~/.zshenv` and `~/dev/docket` were checked with -`find … -newer "$SB/task-start.txt"` after the install and showed nothing newer. - -Where a tag script needs `DOCKET_SCRIPTS_DIR`/`DOCKET_BASH_PATH`, the commands pass the values the -tag's `ensure-docket-env.sh` wrote to `$SB/home/.zshenv` (`$HOME/dev/docket/scripts` and -`/opt/homebrew/bin/bash`), which a user's zsh exports. The sandbox shell is `sh`, which does not -read `.zshenv`. - -## Commands, in order - -`$SCRATCH` is the session scratchpad that contains `$SB`. - -### Step 1 — sandbox - -```bash -SB="$(mktemp -d "$SCRATCH/bash-upgrade-v093.XXXXXX")" -mkdir -p "$SB/home" "$SB/stub-bin" "$SB/home/.config" "$SB/home/.local/share" "$SB/home/.cache" "$SB/home/.local/state" -printf '#!/bin/sh\necho "gh stub: network is forbidden in the sandbox: $*" >&2\necho "$*" >> "%s/gh-calls.log"\nexit 97\n' "$SB" > "$SB/stub-bin/gh" -chmod +x "$SB/stub-bin/gh" -printf '[user]\n\tname = Bash Upgrade Fixture\n\temail = fixture@docket.invalid\n[init]\n\tdefaultBranch = main\n' > "$SB/gitconfig" -cat > "$SB/sbx" < HOME=$SB/home / no docket on PATH / 0 -ls /opt/homebrew/bin/docket # No such file or directory -``` - -### Step 2 — the tag, checked out into the sandbox home - -```bash -"$SB/sbx" git clone --quiet --branch v0.9.3 --depth 1 file:///Users/homer/dev/docket "$SB/home/dev/docket" -"$SB/sbx" git -C "$SB/home/dev/docket" remote remove origin -git -C /Users/homer/dev/docket rev-parse 'v0.9.3^{commit}' v0.9.3 # dd742abd5e9fcdf8ffe78eb6f36a293410873bbf / 5897ac000d2ea69c36a226b9459d925067530190 -"$SB/sbx" git -C "$SB/home/dev/docket" rev-parse HEAD # dd742abd5e9fcdf8ffe78eb6f36a293410873bbf -shasum -a 256 "$SB/home/dev/docket/install.sh" # 18d46c04…785c71 -``` - -### Step 3 — harness folders and the tag's installer - -The v0.9.3 harness lists equal v0.9.2's: `link-skills.sh` (`HARNESS_SKILL_DIRS`) targets `.claude`, -`.codex`, `.cursor`, `.agents`, `.kiro` and `.windsurf` `skills/`, and `sync-agents.sh` writes -`./agents` for every token in `DOCKET_GI_HARNESS_TOKENS` -(`claude codex cursor opencode agents kiro windsurf`) whose parent exists. As for v0.9.2, the -parents for Claude Code, Cursor, Codex and OpenCode (`.opencode`, and `.agents` for its skills) were -created, and `.kiro` and `.windsurf` were not: - -```bash -date -u +%Y-%m-%dT%H:%M:%SZ > "$SB/task-start.txt" # 2026-10-04T18:30:38Z -mkdir -p "$SB/home/.claude" "$SB/home/.cursor" "$SB/home/.codex" "$SB/home/.opencode" "$SB/home/.agents" -"$SB/sbx" sh -c 'cd "$HOME/dev/docket" && /opt/homebrew/bin/bash ./install.sh' > "$SB/install.log" 2>&1 # exit 0 -find ~/.claude/agents ~/.claude/skills ~/.claude/settings.json ~/.claude/CLAUDE.md ~/.zshenv ~/.config/docket -newer "$SB/task-start.txt" # (no output) -``` - -One attempt; it ended `docket: install complete`. Its output, apart from the 48 `linked …` lines: - -```text -==> ensure-global-config.sh (configure Bash runtime) -docket: wrote $SB/home/.config/docket/config.yml (pointer config plus managed runtime.bash) -==> link-skills.sh (install skills) - -Created: 48 Skipped (already present): 0 -==> sync-agents.sh (generate agent wrappers) -sync-agents: WARN agents/docket-: no harness-specific model — generated unpinned; harness 'agents' will apply its own default. … (once per agent, 17 lines) -sync-agents: WARN harness 'agents' has no named emitter — its wrappers are Claude-shaped and unverified for 'agents', … (ADR-0060). … -sync-agents: done -==> ensure-docket-env.sh (export Docket runtime environment) -ensure-docket-env: wrote DOCKET_SCRIPTS_DIR and DOCKET_BASH_PATH -> $SB/home/.zshenv (zsh) -ensure-docket-env: set env.DOCKET_SCRIPTS_DIR and env.DOCKET_BASH_PATH -> .claude/settings.json -docket: install complete -``` - -### Step 4 — a single-branch repository, populated through the tag's main-mode flows - -The tag's single-branch opt-out is `metadata_branch: main` with `integration_branch: main` -(`skills/docket-convention/SKILL.md`, *Configuration*); `docket-config.sh` reads the committed -`.docket.yml` from `origin/HEAD`, so it is pushed before any flow runs. - -```bash -"$SB/sbx" git init --quiet --bare -b main "$SB/origin.git" -"$SB/sbx" git clone --quiet "$SB/origin.git" "$SB/home/dev/sample" -"$SB/sbx" sh -c 'cd "$HOME/dev/sample" && printf "# sample\n" > README.md && git add README.md && git commit -qm "initial" && git push -q origin main && git remote set-head origin main' -"$SB/sbx" sh -c 'cd "$HOME/dev/sample" && printf "metadata_branch: main\nintegration_branch: main\n" > .docket.yml && git add .docket.yml && git commit -qm "chore: use docket in single-branch mode" && git push -q origin main' -"$SB/sbx" sh -c 'cd "$HOME/dev/sample" && export DOCKET_SCRIPTS_DIR="$HOME/dev/docket/scripts" DOCKET_BASH_PATH=/opt/homebrew/bin/bash && "$DOCKET_BASH_PATH" "$DOCKET_SCRIPTS_DIR/docket.sh" preflight' # exit 0, DOCKET_MODE=main, BOOTSTRAP=PROCEED -mkdir -p "$SB/snap-pre-populate" && cp -Rp "$SB/origin.git" "$SB/home/dev/sample" "$SB/snap-pre-populate/" -"$SB/sbx" /opt/homebrew/bin/bash "$SCRATCH/populate-v093.sh" pre > "$SB/populate-pre.log" 2>&1 # exit 0 -``` - -One run, exit 0, no `gh` call. In main mode the metadata working tree is the primary clone on -`main`, so every metadata commit went straight to `origin/main`. Tag scripts used (counts from the -log): `preflight` ×4, `docket-status --board-only [--must-land]` ×6, `render-change-links` ×6, -`render-artifact-backlink` ×5, `render-adr-index` ×1, `render-learnings-index` ×1, `archive-change` -×1, `terminal-publish` ×1 (logged `terminal-publish: main-mode (metadata-branch == -integration-branch); no-op`) and `cleanup-feature-branch` ×1. - -### Step 5 — `migrate-to-docket.sh` (the seeded-root bootstrap) - -```bash -mkdir -p "$SB/snap-pre-migrate" && cp -Rp "$SB/origin.git" "$SB/home/dev/sample" "$SB/snap-pre-migrate/" -"$SB/sbx" git -C "$SB/origin.git" rev-parse main > "$SB/pre-migrate-main.txt" # 3cc746b36708159334f436ec457477821070edce -cd "$SB/home/dev/sample" && ../../../sbx env DOCKET_SCRIPTS_DIR="$SB/home/dev/docket/scripts" DOCKET_BASH_PATH=/opt/homebrew/bin/bash /opt/homebrew/bin/bash "$SB/home/dev/docket/migrate-to-docket.sh" --yes > ../../../migrate.log 2>&1 # exit 0 -``` - -The plan's form (`"$SB/sbx" sh -c 'cd "$HOME/dev/sample" && /opt/homebrew/bin/bash "$HOME/dev/docket/migrate-to-docket.sh" --yes'`) -was first issued combined with the snapshot command; the agent harness's safety check refused it -before anything ran (it cannot inspect removals inside a `sh -c` script, and the tag's script -removes its own `mktemp -d` directory). Nothing executed. The command above runs the same script -directly, with the two variables a user's zsh exports; without `DOCKET_BASH_PATH` the script's -`${DOCKET_BASH_PATH:?run docket/install.sh}` guard would abort it mid-seed. - -One run, exit 0, no `gh` call. Its output: - -```text -==> Resolved configuration - target repo : $SB/home/dev/sample (the repo that will be migrated) - integration_branch : main (code lands here; ref origin/main) - changes_dir : docs/changes - adrs_dir : docs/adrs - results_dir : docs/results (stays on integration — NOT seeded onto docket) - specs_dir : docs/superpowers/specs - board : docs/changes/BOARD.md - (source: .docket.yml) - -==> Checking preconditions - Live planning surface present on origin/main — ok. - origin/docket does not exist — ok to seed. - -==> Seeding the orphan 'docket' branch - Local 'docket' branch absent — creating orphan and seeding from origin/main. -Preparing worktree (new branch 'docket') - Seeded docket with: docs/changes docs/adrs docs/superpowers/specs docs/changes/BOARD.md - Pushing docket → origin/docket. -To $SB/origin.git - * [new branch] docket -> docket -branch 'docket' set up to track 'origin/docket'. - -==> Pruning the live planning surface from 'main' -Preparing worktree (new branch 'migrate-prune-main') - Removing from main: docs/changes/active docs/changes/BOARD.md - Kept on main: docs/changes/archive/, docs/adrs/, docs/results/, docs/superpowers/plans/ - -==> Seeding the managed docket .gitignore block on 'main' -docket-gitignore: UPDATED $SB/tmp/migrate-to-docket.4Ald5M/prune/.gitignore managed docket block — COMMIT THIS so docket-owned files stay untracked. - -==> Pushing 'main' → origin/main -To $SB/origin.git - 3cc746b..fa99478 HEAD -> main - -==> Granting docket's integration-branch push permission (local Claude settings) -ensure-claude-settings: created .claude/settings.local.json and granted: Bash(git -C * push origin HEAD:main) - -==> Migration complete - (next-steps text: .docket.yml is optional; pin metadata_branch: main only to opt back out; re-run - install.sh; the allow-rule was written to .claude/settings.local.json) -``` - -Fidelity of the seeded root (read-only; loose objects only, in a throwaway clone): - -```bash -"$SB/sbx" git clone -q --bare "$SB/origin.git" "$SB/fidelity.git" -cd "$SB/fidelity.git" -"$SB/sbx" git rev-list --max-parents=0 docket # 2e86fd7f8bce29bbf1a47435bbf9f4f092157fde -"$SB/sbx" git cat-file -p 2e86fd7f8bce29bbf1a47435bbf9f4f092157fde # tree db3ba79d…, no parent, no trailers -"$SB/sbx" git merge-base main docket || echo "no shared ancestry" # no shared ancestry -# (a first projection attempt with read-tree --prefix failed here: it needs a work tree) -"$SB/sbx" git clone -q --no-checkout "$SB/origin.git" "$SB/fidelity-wt" -cd "$SB/fidelity-wt" -"$SB/sbx" env GIT_INDEX_FILE="$SB/tmp/fid2.index" git read-tree --empty -for p in docs/changes docs/adrs docs/superpowers/specs; do "$SB/sbx" env GIT_INDEX_FILE="$SB/tmp/fid2.index" git read-tree --prefix="$p/" "3cc746b36708159334f436ec457477821070edce:$p"; done -"$SB/sbx" env GIT_INDEX_FILE="$SB/tmp/fid2.index" git write-tree # db3ba79d84f62347e34dec034cef959e1bba42ad -``` - -### Step 6 — switch to `docket` mode and keep working there - -The migration leaves `metadata_branch: main` in `.docket.yml`, which keeps the tag in single-branch -mode; the migration's own next steps say to pin it only to opt back out. The user's edit: - -```bash -cd "$SB/home/dev/sample" -"$SB/sbx" git pull -q --ff-only origin main # the clone was 2 commits behind (prune, .gitignore) -printf "metadata_branch: docket\nintegration_branch: main\n" > .docket.yml -"$SB/sbx" git add .docket.yml && "$SB/sbx" git commit -qm "chore: switch docket to docket-mode after migrate-to-docket.sh" && "$SB/sbx" git push -q origin main -"$SB/sbx" env DOCKET_SCRIPTS_DIR="$SB/home/dev/docket/scripts" DOCKET_BASH_PATH=/opt/homebrew/bin/bash /opt/homebrew/bin/bash "$SB/home/dev/docket/scripts/docket.sh" preflight > "$SB/preflight-post.out" 2> "$SB/preflight-post.err" # exit 0, DOCKET_MODE=docket, BOOTSTRAP=PROCEED -mkdir -p "$SB/snap-post-migrate" && cp -Rp "$SB/origin.git" "$SB/home/dev/sample" "$SB/snap-post-migrate/" -"$SB/sbx" /opt/homebrew/bin/bash "$SCRATCH/populate-v093.sh" post > "$SB/populate-post.log" 2>&1 # exit 0 -``` - -- **`.docket` worktree command:** `docket.sh preflight` (`scripts/lib/docket-preflight.sh` - `docket_preflight`) ran `git -C worktree add .docket docket` on the local `docket` branch - the migration had made and pushed with `-u`, then `disable-worktree-hooks.sh --worktree .docket`. - The migration had already run `disable-worktree-hooks.sh` on its own temp worktrees, which is - where `extensions.worktreeConfig=true` first came from. -- **Post-migration run:** one run, exit 0, no `gh` call. Tag scripts used: `preflight` ×5, - `docket-status --board-only [--must-land]` ×5, `render-change-links` ×3, - `render-artifact-backlink` ×2, `mint-stub` ×1, `archive-change` ×1, `terminal-publish - --enabled false` ×1 (logged `terminal_publish: false — skipping publish onto main; the record - stays on docket`) and `cleanup-feature-branch` ×1. - -`$SCRATCH/populate-v093.sh`, verbatim (both phases): - -```bash -#!/opt/homebrew/bin/bash -# populate-v093.sh pre|post — scratch driver (never committed) that populates the v0.9.3 sample -# repository through the tag's own scripts. Run ONLY through the sandbox wrapper: -# "$SB/sbx" /opt/homebrew/bin/bash "$SCRATCH/populate-v093.sh" pre # single-branch (main) mode -# "$SB/sbx" /opt/homebrew/bin/bash "$SCRATCH/populate-v093.sh" post # docket mode, after migrate -# It never sources a tag script; every tag script runs as a subprocess via docket.sh. -set -euo pipefail -PHASE="${1:?usage: populate-v093.sh pre|post}" - -export DOCKET_SCRIPTS_DIR="$HOME/dev/docket/scripts" -export DOCKET_BASH_PATH=/opt/homebrew/bin/bash -R="$HOME/dev/sample" -case "$PHASE" in - pre) M="$R"; MBRANCH=main ;; # main-mode: the metadata working tree is the primary tree - post) M="$R/.docket"; MBRANCH=docket ;; - *) echo "unknown phase $PHASE" >&2; exit 2 ;; -esac -C="$M/docs/changes" -A="$M/docs/adrs" -SPECS="$M/docs/superpowers/specs" -TODAY="$(date -u +%F)" -cd "$R" - -dk(){ echo "+ docket.sh $*" >&2; "$DOCKET_BASH_PATH" "$DOCKET_SCRIPTS_DIR/docket.sh" "$@"; } -ghcheck(){ if [ -e "$HOME/../gh-calls.log" ]; then echo "FATAL: gh was called:" >&2; cat "$HOME/../gh-calls.log" >&2; exit 97; fi; } -# metadata commit: explicit paths only, then push the metadata branch (main in main-mode) -mcommit(){ local msg="$1"; shift; git -C "$M" add -- "$@"; git -C "$M" commit -q -m "$msg" -- "$@"; git -C "$M" push -q origin "$MBRANCH"; ghcheck; } -board(){ dk docket-status --board-only --must-land; ghcheck; } -now(){ date -u +%Y-%m-%dT%H:%M:%SZ; } -# fm_set FILE KEY VALUE — set a frontmatter field inside the FIRST ---…--- block only -# (append before the closing --- when absent). -fm_set(){ - local f="$1" k="$2" v="$3" tmp - tmp="$(mktemp "$(dirname "$f")/.fmset.XXXXXX")" - awk -v k="$k" -v v="$v" ' - BEGIN{n=0; done=0} - /^---[[:space:]]*$/ { n++; if (n==2 && !done) { print k ": " v; done=1 } print; next } - n==1 && !done && index($0, k ":")==1 { print k ": " v; done=1; next } - { print } - ' "$f" > "$tmp" - mv -f "$tmp" "$f" -} -change_links(){ dk render-change-links --change-file "$1" --adrs-dir "$A"; } - -# --------------------------------------------------------------------------------------------- -# Build + merge + close-out helper for a done change (docket-implement-next steps 2-7, then a -# local merge standing in for the GitHub PR merge, then docket-finalize-change's close-out). -# --------------------------------------------------------------------------------------------- -build_and_close(){ - local id="$1" slug="$2" pr="$3" codefile="$4" codebody="$5" adr="$6" - local pad; pad="$(printf '%04d' "$id")" - local F="$C/active/$pad-$slug.md" rel="docs/changes/active/$pad-$slug.md" - local W="$R/.worktrees/$slug" - local plan="docs/superpowers/plans/$TODAY-$slug.md" - local results="docs/results/$TODAY-$pad-$slug.md" - - # Step 2 — claim - dk preflight >/dev/null - fm_set "$F" status in-progress - fm_set "$F" branch "feat/$slug" - fm_set "$F" updated "$TODAY" - fm_set "$F" claimed_at "$(now)" - mcommit "docket($pad): claim — in-progress on feat/$slug" "$rel" - dk docket-status --board-only || echo "best-effort board pass failed (continuing)" >&2; ghcheck - - # Step 3 — reconcile (no drift): reconciled: true + a dated reconcile-log entry - fm_set "$F" reconciled true - fm_set "$F" claimed_at "$(now)" - printf '\n- %s — reconciled against main: no drift.\n' "$TODAY" >> "$F" - mcommit "docket($pad): reconcile — no drift" "$rel" - - # Step 4 — feature worktree + plan (plan back-link stamped on the feature branch) - git fetch -q origin - git worktree add -q "$W" -b "feat/$slug" origin/main - mkdir -p "$W/docs/superpowers/plans" "$W/docs/results" - printf '# %s Implementation Plan\n\n### Task 1\n\n- [ ] Write `%s`.\n' "$(sed -n 's/^title: //p' "$F" | head -n 1)" "$codefile" > "$W/$plan" - dk render-artifact-backlink --artifact-file "$W/$plan" --change-file "$F" - git -C "$W" add -- "$plan" - git -C "$W" commit -q -m "docs(plan): $slug implementation plan" -- "$plan" - fm_set "$F" plan "$plan" - fm_set "$F" claimed_at "$(now)" - change_links "$F" - mcommit "docket($pad): plan" "$rel" - - # Step 5 — build - printf '%s' "$codebody" > "$W/$codefile" - git -C "$W" add -- "$codefile" - git -C "$W" commit -q -m "$( [ "$codefile" = hello.sh ] && echo feat || echo docs ): $slug" -- "$codefile" - - # Step 6 — review; optional ADR via the docket-adr flow (ADR commit, then separate index commit) - if [ -n "$adr" ]; then - local adrfile="docs/adrs/0001-greeting-script-is-posix-sh.md" - cat > "$M/$adrfile" < "$A/README.md" - mcommit "docket(adr): regenerate ADR index" "docs/adrs/README.md" - fm_set "$F" adrs "[1]" - fm_set "$F" claimed_at "$(now)" - change_links "$F" - mcommit "docket($pad): adrs [1]" "$rel" - fi - - # Step 6.5 — results file on the feature branch, with its back-link - printf '# Results — %s\n\nBuilt as planned. Manual check: the change does what its plan says.\n' "$slug" > "$W/$results" - dk render-artifact-backlink --artifact-file "$W/$results" --change-file "$F" - git -C "$W" add -- "$results" - git -C "$W" commit -q -m "docs(results): $slug" -- "$results" - git -C "$W" push -q origin "feat/$slug" - ghcheck - - # Step 7 — implemented + pr: (+ results:) — PR opening itself needs gh (stubbed out: gap) - fm_set "$F" status implemented - fm_set "$F" pr "$pr" - fm_set "$F" results "$results" - fm_set "$F" claimed_at "$(now)" - change_links "$F" - mcommit "docket($pad): implemented — PR open" "$rel" - dk docket-status --board-only || echo "best-effort board pass failed (continuing)" >&2; ghcheck - - # Merge: a local --no-ff merge of feat/ into main stands in for GitHub's PR merge. - git checkout -q main - git pull -q --ff-only origin main - git merge -q --no-ff "feat/$slug" -m "Merge pull request #${pr##*/} from fixture/feat/$slug" - git push -q origin main - ghcheck - local mdate; mdate="$(TZ=UTC git show -s --format=%ad --date=format-local:%Y-%m-%d HEAD)" - - # Finalize close-out (terminal-close-out.md): harvest -> archive -> re-render -> publish -> cleanup -> board - dk preflight >/dev/null - if [ -n "$adr" ]; then - mkdir -p "$C/learnings" - cat > "$C/learnings/posix-sh-means-no-arrays.md" < "$tmp" && [ -s "$tmp" ] && mv -f "$tmp" "$C/learnings/README.md" || rm -f "$tmp" - mcommit "docket($pad): harvest learnings" "docs/changes/learnings/posix-sh-means-no-arrays.md" "docs/changes/learnings/README.md" - fi - dk archive-change --changes-dir "$C" --id "$id" --outcome done --date "$mdate" --results "$results" \ - --message "docket($pad): done — archived (status done, $mdate)" - ghcheck - local AF="$C/archive/$mdate-$pad-$slug.md" arel="docs/changes/archive/$mdate-$pad-$slug.md" - change_links "$AF" - local spec; spec="$(awk '/^---[[:space:]]*$/{n++; next} n==1 && /^spec:/{sub(/^spec:[[:space:]]*/, ""); print; exit}' "$AF")" - if [ -n "$spec" ]; then - dk render-artifact-backlink --artifact-file "$M/$spec" --change-file "$AF" - mcommit "docket($pad): re-render artifacts after archive" "$arel" "$spec" - elif [ -n "$(git -C "$M" status --porcelain -- "$arel")" ]; then - mcommit "docket($pad): re-render artifacts after archive" "$arel" - else - echo "re-render after archive: block unchanged for $pad — no follow-on commit" >&2 - fi - # main-mode: --metadata-branch equals --integration-branch, so terminal-publish logs its mode-guard - # no-op (the archive move on main IS the terminal record). docket-mode: --enabled false (the - # tag's default terminal_publish) logs the knob-guard skip. - dk terminal-publish --id "$id" --outcome done --integration-branch main --metadata-branch "$MBRANCH" \ - --changes-dir docs/changes --adrs-dir docs/adrs --enabled false --metadata-worktree "$M" - ghcheck - dk cleanup-feature-branch --slug "$slug" - ghcheck - board -} - -new_change(){ # new_change ID SLUG TITLE PRIORITY TYPE DEPENDS RELATED SPEC TRIVIAL WHY WHAT OUT - local id="$1" slug="$2" title="$3" prio="$4" type="$5" deps="$6" rel="$7" spec="$8" trivial="$9" - local why="${10}" what="${11}" out="${12}" - local pad; pad="$(printf '%04d' "$id")" - local F="$C/active/$pad-$slug.md" - { - printf -- '---\nid: %s\nslug: %s\ntitle: %s\nstatus: proposed\npriority: %s\ntype: %s\n' "$id" "$slug" "$title" "$prio" "$type" - printf 'created: %s\nupdated: %s\ndepends_on: %s\nstacked_on:\nrelated: %s\ndiscovered_from: []\nadrs: []\n' "$TODAY" "$TODAY" "$deps" "$rel" - [ -n "$spec" ] && printf 'spec: %s\n' "$spec" - printf 'plan:\nresults:\ntrivial: %s\nauto_groomable:\nbranch:\npr:\nblocked_by:\nreconciled: false\n---\n\n' "$trivial" - printf '## Artifacts\n\n\n\n\n' - printf '## Why\n\n%s\n\n## What changes\n\n%s\n\n## Out of scope\n\n%s\n\n## Reconcile log\n' "$why" "$what" "$out" - } > "$F" -} - -dk preflight >/dev/null -mkdir -p "$C/active" "$SPECS" "$A" - -if [ "$PHASE" = pre ]; then - # ------------------------------------------------------------------------------------------- - # 0001 — brainstorm-mode change with a spec, built, merged and closed out as done (main-mode). - # ------------------------------------------------------------------------------------------- - S1="docs/superpowers/specs/$TODAY-add-a-greeting-script-design.md" - cat > "$M/$S1" <<'EOF' -# Add a greeting script — design - -## Purpose - -Give the sample repository a tiny executable so later changes have code to build on. - -## Design - -A POSIX `sh` script, `hello.sh`, prints `hello, ` for its first argument and `hello, world` -when called with none. No dependencies. - -## Testing - -`sh hello.sh` prints `hello, world`; `sh hello.sh docket` prints `hello, docket`. -EOF - new_change 1 add-a-greeting-script "Add a greeting script" medium feat "[]" "[]" "$S1" false \ - "The sample repository has no code yet. A small greeting script gives later changes something to -build on and proves the build loop end to end." \ - 'Add `hello.sh`, which greets its first argument or the world.' \ - "Localisation and any configuration file." - F1="$C/active/0001-add-a-greeting-script.md" - change_links "$F1" - dk render-artifact-backlink --artifact-file "$M/$S1" --change-file "$F1" - mcommit "docket(0001): new change — add a greeting script (spec)" "docs/changes/active/0001-add-a-greeting-script.md" "$S1" - board - - # 0002 — trivial-mode change (stays proposed until after the migration). - new_change 2 document-the-greeting-script "Document the greeting script" low docs "[1]" "[]" "" true \ - "The repository does not say how to run the greeting script." \ - 'Add a short `USAGE.md` that shows how to run it.' \ - "Any change to the script itself." - mcommit "docket(0002): new change — document the greeting script (trivial)" "docs/changes/active/0002-document-the-greeting-script.md" - board - - build_and_close 1 add-a-greeting-script "https://github.com/fixture/sample/pull/1" hello.sh \ - '#!/bin/sh -# hello.sh — greet the first argument, or the world. -printf "hello, %s\n" "${1:-world}" -' adr - - # 0003 — proposed change with a spec (docket-new-change Brainstorm mode). - dk preflight >/dev/null - S3="docs/superpowers/specs/$TODAY-add-a-farewell-script-design.md" - cat > "$M/$S3" <<'EOF' -# Add a farewell script — design - -## Purpose - -Pair the greeting script with a farewell, so the sample has two commands. - -## Design - -`bye.sh` prints `goodbye, `, defaulting to `goodbye, world`. It reuses the greeting script's -POSIX `sh` rule (ADR-0001). - -## Testing - -`sh bye.sh` prints `goodbye, world`. -EOF - new_change 3 add-a-farewell-script "Add a farewell script" high feat "[]" "[1]" "$S3" false \ - "A greeting without a farewell is half a conversation." \ - 'Add `bye.sh`, the counterpart of `hello.sh`.' \ - "Merging the two scripts into one." - F3="$C/active/0003-add-a-farewell-script.md" - change_links "$F3" - dk render-artifact-backlink --artifact-file "$M/$S3" --change-file "$F3" - mcommit "docket(0003): new change — add a farewell script (spec)" "docs/changes/active/0003-add-a-farewell-script.md" "$S3" - board -else - # ------------------------------------------------------------------------------------------- - # docket mode, after migrate-to-docket.sh: 0002 (seeded as a proposed trivial change) is - # built, merged and closed out as done; 0004 is a new trivial proposed change; 0005 is minted - # by mint-stub.sh and then deferred. - # ------------------------------------------------------------------------------------------- - build_and_close 2 document-the-greeting-script "https://github.com/fixture/sample/pull/2" USAGE.md \ - '# Usage - -Run `sh hello.sh [name]`. With no name it greets the world. -' "" - - dk preflight >/dev/null - new_change 4 add-a-license-file "Add a license file" medium chore "[]" "[]" "" true \ - "The sample repository has no license." \ - 'Add an MIT `LICENSE` file at the root.' \ - "Per-file license headers." - mcommit "docket(0004): new change — add a license file (trivial)" "docs/changes/active/0004-add-a-license-file.md" - board - - BODY="$(mktemp "$TMPDIR/stub-body.XXXXXX")" - cat > "$BODY" <<'EOF' -## Why - -The greeting script could read a default name from an environment variable, which the review of -change 1 suggested but did not need. - -## What changes - -Read `HELLO_NAME` when no argument is given. - -## Open questions - -- Should an empty `HELLO_NAME` count as unset? -EOF - dk mint-stub --changes-dir "$C" --title "Read the default greeting name from the environment" --type feat \ - --body-file "$BODY" --discovered-from 1 --metadata-branch docket - ghcheck - F5="$(ls "$C"/active/0005-*.md)" - rel5="docs/changes/active/$(basename "$F5")" - dk preflight >/dev/null - fm_set "$F5" status deferred - fm_set "$F5" updated "$TODAY" - printf '\n## Why deferred\n\nRight idea, wrong time: nobody has asked for it yet. Revisit when a caller needs it.\n' >> "$F5" - mcommit "docket(0005): defer — right idea, wrong time" "$rel5" - board -fi - -echo "populate-v093 $PHASE: done" -``` - -### Step 7 — the deliberate configuration, committed last - -v0.9.3's schema (`scripts/docket-config.sh` and its `.md`, `.docket.example.yml`, -`skills/docket-convention`, and `sync-agents.sh` for `agents:`/`runners:`) accepts every key in the -spec's configuration table. Each is set below, switched **on** where the Go binary blocks only when -on. The file was first tried in a throwaway copy of the repository (its own copy of `origin`), so -the saved history holds only the accepted version: - -```bash -mkdir -p "$SB/snap-pre-config" && cp -Rp "$SB/origin.git" "$SB/home/dev/sample" "$SB/snap-pre-config/" -mkdir -p "$SB/trial" && cp -Rp "$SB/origin.git" "$SB/trial/origin.git" && "$SB/sbx" git clone -q "$SB/trial/origin.git" "$SB/trial/sample" && "$SB/sbx" git -C "$SB/trial/sample" remote set-head origin main -cp "$SB/docket.yml.final" "$SB/trial/sample/.docket.yml" -cd "$SB/trial/sample" && "$SB/sbx" git add .docket.yml && "$SB/sbx" git commit -qm "chore: docket configuration" && "$SB/sbx" git push -q origin main -"$SB/sbx" env DOCKET_BASH_PATH=/opt/homebrew/bin/bash /opt/homebrew/bin/bash "$SB/home/dev/docket/scripts/docket-config.sh" --export # exit 0 (one runtime.bash warning) -"$SB/sbx" env DOCKET_BASH_PATH=/opt/homebrew/bin/bash /opt/homebrew/bin/bash "$SB/home/dev/docket/sync-agents.sh" --check # exit 1: -# sync-agents: check: the docket dispatch block in $SB/trial/sample/CLAUDE.md is missing or stale — run: bash sync-agents.sh and commit it -"$SB/sbx" env DOCKET_BASH_PATH=/opt/homebrew/bin/bash /opt/homebrew/bin/bash "$SB/home/dev/docket/sync-agents.sh" # exit 0: created CLAUDE.md … COMMIT THIS -"$SB/sbx" git add CLAUDE.md && "$SB/sbx" git commit -qm "chore: commit the docket dispatch block" && "$SB/sbx" git push -q origin main -"$SB/sbx" env DOCKET_BASH_PATH=/opt/homebrew/bin/bash /opt/homebrew/bin/bash "$SB/home/dev/docket/sync-agents.sh" --check # exit 0 -"$SB/sbx" env DOCKET_BASH_PATH=/opt/homebrew/bin/bash /opt/homebrew/bin/bash "$SB/home/dev/docket/scripts/docket-config.sh" --export # exit 0 -``` - -The `agents:` block opts the repository into the tag's per-repository agent generation, and the -tag's own check then requires a committed dispatch block in the repository's `CLAUDE.md`. So the -config commit is followed by that one commit, made exactly as the tag tells the user to. Neither -reaches `gh`. The trial's `sync-agents.sh` also re-ran the user-level pass on the shared sandbox -home; a SHA-1 listing of every harness file and a listing of every symlink target, taken before the -trial and after the final run below, were identical. Then, for real: - -```bash -cd "$SB/home/dev/sample" -cp "$SB/docket.yml.final" .docket.yml -"$SB/sbx" git add .docket.yml && "$SB/sbx" git commit -qm "chore: docket configuration" && "$SB/sbx" git push -q origin main -"$SB/sbx" env DOCKET_BASH_PATH=/opt/homebrew/bin/bash /opt/homebrew/bin/bash "$SB/home/dev/docket/sync-agents.sh" > "$SB/sync-agents-repo.out" 2> "$SB/sync-agents-repo.err" # exit 0 -"$SB/sbx" git add CLAUDE.md && "$SB/sbx" git commit -qm "chore: commit the docket dispatch block" && "$SB/sbx" git push -q origin main -"$SB/sbx" env DOCKET_BASH_PATH=/opt/homebrew/bin/bash /opt/homebrew/bin/bash "$SB/home/dev/docket/scripts/docket-config.sh" --export > "$SB/config-export.txt" 2> "$SB/config-export.err" # exit 0 -"$SB/sbx" env DOCKET_BASH_PATH=/opt/homebrew/bin/bash /opt/homebrew/bin/bash "$SB/home/dev/docket/sync-agents.sh" --check > "$SB/sync-check.out" 2> "$SB/sync-check.err" # exit 0 -``` - -`sync-agents.sh` printed the 17 unpinned-agent warnings for the `agents` harness, the -no-named-emitter warning, `created CLAUDE.md to carry the docket dispatch block — COMMIT THIS.`, -`wrote/updated the docket dispatch block in $SB/home/dev/sample/CLAUDE.md — COMMIT THIS -(machine-neutral; no model IDs).` and `done`. `config-export.err` held one line: -`docket-config: warning: committed config key runtime.bash is machine-local — set it in -.docket.local.yml or global config.yml; ignored`. `sync-check.err` was empty. - -The committed `.docket.yml` (`main:.docket.yml`), verbatim: - -```yaml -# Docket configuration for the sample repository (written for Bash docket v0.9.3). -metadata_branch: docket -integration_branch: main - -runtime: - bash: /opt/homebrew/bin/bash - -finalize: - gate: ci - skip_results_only_delta: true - -learnings: - cap: 250 - -build: - checkpoint: true - -delegation_observation_budget: 45 - -board_surfaces: [inline, github] -github_project: {owner: fixture, number: 7} - -terminal_publish: true -auto_groom: true - -auto_capture: - enabled: true - types: [feat, fix] - -dummy_mode: - enabled: true - persona: "A new contributor who knows shell scripts but not this project." - surfaces: [dialogue, reports] - -agents: - claude: - implement-next: { model: claude-opus-5, effort: high } - rebase-resolver: { model: gpt-5.6-sol, effort: high, runner: codex } - -runners: - codex: - sandbox: workspace-write - network: true - shim_model: inherit - shim_effort: low - opencode: - permissions: ask - -skills: - brainstorm: superpowers:brainstorming - plan: superpowers:writing-plans - build: docket-build - review: docket-review - finish: superpowers:finishing-a-development-branch -``` - -| Key | Value set | Go behavior it exercises (spec table) | v0.9.3 verdict | -|---|---|---|---| -| `metadata_branch` | `docket` | warn and ignore | accepted (`METADATA_BRANCH=docket`) | -| `runtime.bash` | `/opt/homebrew/bin/bash` | warn and ignore | warned as machine-local and ignored, exit 0 (the tag's own documented handling) | -| `terminal_publish` | `true` | blocks when on | accepted (`TERMINAL_PUBLISH=true`) | -| `auto_groom` | `true` | blocks when on | accepted (`AUTO_GROOM=true`) | -| `build.checkpoint` | `true` | blocks when on | accepted (`BUILD_CHECKPOINT=true`) | -| `finalize.skip_results_only_delta` | `true` | blocks when on | accepted (`FINALIZE_SKIP_RESULTS_ONLY_DELTA=true`) | -| `auto_capture.enabled` | `true` | blocks when on | accepted (`AUTO_CAPTURE_ENABLED=true`) | -| `dummy_mode.enabled` | `true` | blocks when on | accepted (`DUMMY_MODE_ENABLED=true`) | -| `finalize.gate` | `ci` | blocks by value | accepted (`FINALIZE_GATE=ci`) | -| `board_surfaces` | `[inline, github]` | blocks by value | accepted (`BOARD_SURFACES=inline github`) | -| `skills.brainstorm`/`plan`/`build`/`review`/`finish` | the shipped defaults | blocks whenever present | accepted (`SKILL_*`) | -| `agents.claude.implement-next.model`/`effort` | `claude-opus-5` / `high` | blocks in a repository layer | accepted by `sync-agents.sh` (per-repo wrapper pinned `model: claude-opus-5`, `effort: high`) | -| `agents.claude.rebase-resolver.model`/`effort`/`runner` | `gpt-5.6-sol` / `high` / `codex` | blocks whenever present | accepted by `sync-agents.sh` (delegated wrapper, `--runner codex --model gpt-5.6-sol --effort high`) | -| `learnings.cap` | `250` | info notice | accepted (`LEARNINGS_CAP=250`) | -| `github_project` | `{owner: fixture, number: 7}` | info notice | accepted (the tag reads it nowhere) | -| `delegation_observation_budget` | `45` | info notice | accepted (`DELEGATION_OBSERVATION_BUDGET=45`) | -| companions `auto_capture.types` | `[feat, fix]` | info notice | accepted (`AUTO_CAPTURE_TYPES=feat fix`) | -| companions `dummy_mode.persona`/`surfaces` | one quoted line / `[dialogue, reports]` | info notice | accepted | -| companions `runners.codex.sandbox`/`network`/`shim_model`/`shim_effort`, `runners.opencode.permissions` | `workspace-write`/`true`/`inherit`/`low`, `ask` | info notice | accepted by `sync-agents.sh --check` (runner and shim validation gates) | - -No table key was refused by v0.9.3. `integration_branch: main` is also set; it is a supported Go -key and is not part of the test. - -`config-export.txt` (stdout of the final `--export`): - -```text -DOCKET_MODE=docket -DEFAULT_BRANCH=main -METADATA_BRANCH=docket -INTEGRATION_BRANCH=main -METADATA_WORKTREE=.docket -DOCKET_BASH_PATH=/opt/homebrew/bin/bash -CHANGES_DIR=docs/changes -ADRS_DIR=docs/adrs -RESULTS_DIR=docs/results -FINALIZE_GATE=ci -FINALIZE_TEST_COMMAND='' -FINALIZE_REQUIRE_PR_APPROVAL=false -FINALIZE_SKIP_RESULTS_ONLY_DELTA=true -LEARNINGS_ENABLED=true -LEARNINGS_CAP=250 -BOARD_SURFACES=inline\ github -AUTO_GROOM=true -CHANGE_TYPES=chore\ docs\ feat\ fix\ refactor\ perf -AUTO_CAPTURE_ENABLED=true -AUTO_CAPTURE_TYPES=feat\ fix -TERMINAL_PUBLISH=true -RECLAIM_LEASE_TTL=72 -RECLAIM_AUTO=false -BUILD_CHECKPOINT=true -REVIEW_MIN_FIX_SEVERITY=minor -REVIEW_MAX_FIX_TASKS=10 -GATE_OBSERVATION_BUDGET=30 -DELEGATION_OBSERVATION_BUDGET=45 -SKILL_BRAINSTORM=superpowers:brainstorming -SKILL_PLAN=superpowers:writing-plans -SKILL_BUILD=docket-build -SKILL_REVIEW=docket-review -SKILL_FINISH=superpowers:finishing-a-development-branch -DUMMY_MODE_ENABLED=true -DUMMY_MODE_PERSONA=A\ new\ contributor\ who\ knows\ shell\ scripts\ but\ not\ this\ project. -DUMMY_MODE_SURFACES=dialogue\ reports -BOOTSTRAP=PROCEED -``` - -### Step 8 — export - -```bash -OUT=/testdata/bash-upgrade/v0.9.3 -"$SB/sbx" git -C "$SB/origin.git" bundle create "$OUT/origin.bundle" --all -"$SB/sbx" git -C "$SB/origin.git" bundle verify "$OUT/origin.bundle" # okay; refs/heads/docket, refs/heads/main, HEAD; complete history -{ "$SB/sbx" git -C "$SB/origin.git" ls-tree -r --name-only docket | sed 's/^/docket:/'; "$SB/sbx" git -C "$SB/origin.git" ls-tree -r --name-only main | sed 's/^/main:/'; } > "$SB/all-paths.txt" -grep -E -e '^(docket|main):docs/changes/(active|archive)/[^/]+\.md$' -e '^(docket|main):docs/adrs/[0-9][^/]*\.md$' -e '^(docket|main):docs/superpowers/specs/[^/]+\.md$' -e '^(docket|main):docs/changes/learnings/[^/]+\.md$' "$SB/all-paths.txt" | grep -v -e '/README\.md$' | LC_ALL=C sort > "$OUT/records.txt" -rm -rf "$SB/freshclone"; "$SB/sbx" git clone -q "$SB/origin.git" "$SB/freshclone" -"$SB/sbx" git -C "$SB/freshclone" config --local --list | sort > "$SB/cfg-fresh.txt" -"$SB/sbx" git -C "$SB/home/dev/sample" config --local --list | sort > "$SB/cfg-sample.txt" -diff "$SB/cfg-fresh.txt" "$SB/cfg-sample.txt" -# > branch.docket.merge=refs/heads/docket -# > branch.docket.remote=origin -# > extensions.worktreeconfig=true -"$SB/sbx" git -C "$SB/home/dev/sample/.docket" config --worktree --list -# core.hookspath=$SB/home/dev/sample/.git/docket/empty-hooks -python3 "$SCRATCH/make-home-tar.py" "$SB/home" "$OUT/home.tar" # members: 202 -tar -xOf "$OUT/home.tar" | grep -c -e "$SB" || true # 0 -tar -xOf "$OUT/home.tar" | grep -c -e "/tmp/claude-501" || true # 0 (the /tmp spelling of the same path) -tar -tvf "$OUT/home.tar" | grep -c -e '^l' # 48 -du -sk "$OUT" # 676 (with this file; under 1024) -``` - -`clone-config.txt` has the same three lines as the v0.9.2 case: `worktree .docket docket`, -`config extensions.worktreeConfig true` and `hooks-off .docket`. Here `branch.docket.*` came from -the migration's `git push -u origin docket`; on a fresh clone, git's DWIM in -`git worktree add .docket docket` recreates the same tracking branch. - -`$SCRATCH/make-home-tar.py` is byte-identical to the helper reproduced in -[`../v0.9.2/PROVENANCE.md`](../v0.9.2/PROVENANCE.md) (SHA-256 -`de52b56ede3b6568b9ff17b9a291bcd97eaf67129c7e1c05b6681212ad611458`); it is repeated here verbatim: - -```python -#!/usr/bin/env python3 -"""make-home-tar.py SANDBOX_HOME OUT_TAR — scratch helper (never committed). - -Writes an uncompressed USTAR tar rooted at SANDBOX_HOME holding only the harness folders, the -docket skills tree the skill links point at, and the shell profile the tag's ensure-docket-env.sh -wrote. Every absolute sandbox-home prefix (and its realpath / /tmp spelling) in a symlink target or -regular-file body becomes @@SANDBOX_HOME@@. mtimes are zeroed, uid/gid 0, no user/group names. -""" -import io -import os -import sys -import tarfile - -home = sys.argv[1].rstrip("/") -out = sys.argv[2] -TOKEN = "@@SANDBOX_HOME@@" - -INCLUDE = [".claude", ".cursor", ".codex", ".agents", ".opencode", ".config/docket", - "dev/docket/skills", ".zshenv"] - -real = os.path.realpath(home) -spellings = {home, real} -for s in list(spellings): - if s.startswith("/private/"): - spellings.add(s[len("/private"):]) -# longest first so "/private/tmp/x" is rewritten before "/tmp/x" can match inside it -spellings = sorted(spellings, key=len, reverse=True) - - -def rewrite(text): - for s in spellings: - text = text.replace(s, TOKEN) - return text - - -def norm(ti): - ti.mtime = 0 - ti.uid = ti.gid = 0 - ti.uname = ti.gname = "" - return ti - - -members = [] -for top in INCLUDE: - p = os.path.join(home, top) - if not os.path.lexists(p): - sys.exit("missing include: " + top) - if os.path.isdir(p) and not os.path.islink(p): - for root, dirs, files in os.walk(p, followlinks=False): - dirs.sort() - members.append(root) - for name in sorted(files + [d for d in dirs if os.path.islink(os.path.join(root, d))]): - members.append(os.path.join(root, name)) - # symlinked dirs must not be descended into - dirs[:] = [d for d in dirs if not os.path.islink(os.path.join(root, d))] - else: - members.append(p) - -# parents of nested includes (".config", "dev", "dev/docket") so extraction recreates them -parents = set() -for top in INCLUDE: - parts = top.split("/")[:-1] - for i in range(1, len(parts) + 1): - parents.add("/".join(parts[:i])) - -seen = set() -with tarfile.open(out, "w", format=tarfile.USTAR_FORMAT) as tf: - for rel in sorted(parents): - ti = norm(tf.gettarinfo(os.path.join(home, rel), arcname=rel)) - tf.addfile(ti) - for path in members: - rel = os.path.relpath(path, home) - if rel in seen: - continue - seen.add(rel) - ti = norm(tf.gettarinfo(path, arcname=rel)) - if ti.issym(): - ti.linkname = rewrite(ti.linkname) - tf.addfile(ti) - elif ti.isfile(): - with open(path, "rb") as fh: - data = fh.read() - try: - data = rewrite(data.decode("utf-8")).encode("utf-8") - except UnicodeDecodeError: - for s in spellings: - data = data.replace(s.encode(), TOKEN.encode()) - ti.size = len(data) - tf.addfile(ti, io.BytesIO(data)) - elif ti.isdir(): - tf.addfile(ti) - else: - sys.exit("unexpected member type: " + rel) -print("members:", len(seen) + len(parents)) -``` - -### Step 9 — the ownership probe - -```bash -timeout --kill-after=10s 10m go test -tags integration -count=1 -run '^TestIntegrationBashUpgradeOwnership' ./internal/bashupgrade/ -v # exit 0; v0.9.2 and v0.9.3 PASS -``` - -On this case `docket repository prepare --json` returned `no-op` / `healthy` (no ownership -refusal), so the binary proved the receiptless non-empty root through the legacy-equivalence path. -`docket repository check --json` (exit 1) reported `postconditions-unmet` (error), -`committed-ignore-invalid` (error, `.gitignore`), `legacy-config-key-present` (error, -`.docket.yml`), `board-stale` (warning), `artifact-links-stale` (warning, both archived changes) and -`test-config-missing` (warning). - -### Step 10 — the per-clone ignored files (`clone-files.tar`, regenerated) - -Made the same day (sandbox work began 2026-10-04T19:25:55Z), on the same host and tools, after the -case above was exported. The Step 1 sandbox was gone, so a new one was built the same way, under -the same session scratchpad: `$SB2` was -`$SCRATCH/bash-upgrade-v093-clone.6we20K`. Its `sbx` wrapper is the Step 1 wrapper with `$SB2` for -`$SB`. Tag scripts run only as subprocesses; none is sourced. - -```bash -/opt/homebrew/bin/bash "$SCRATCH/regen-clone-files.sh" # exit 0 -``` - -`$SCRATCH/regen-clone-files.sh`, verbatim (SHA-256 -`a509dbbe0e62f20f6642acbd69d36f71e38346a9c65be546001dec0b5ef1d2e0`): - -```bash -#!/opt/homebrew/bin/bash -# regen-clone-files.sh — scratch driver (never committed). Regenerates the per-clone ignored -# files of the saved v0.9.3 case in a throwaway sandbox. Tag scripts run only as subprocesses. -set -euo pipefail -SCRATCH="/private/tmp/claude-501/-Users-homer-dev-docket/9cbfa2e1-e5f8-4f8a-9555-3ec1f4e089eb/scratchpad" -CASE="/Users/homer/dev/docket/.worktrees/upgrade-guide-from-bash-docket-to-the-go-binary-proven-on-sa/testdata/bash-upgrade/v0.9.3" -SB="$(mktemp -d "$SCRATCH/bash-upgrade-v093-clone.XXXXXX")" -echo "SB=$SB" -mkdir -p "$SB/home" "$SB/stub-bin" "$SB/home/.config" "$SB/home/.local/share" "$SB/home/.cache" "$SB/home/.local/state" "$SB/tmp" -printf '#!/bin/sh\necho "gh stub: network is forbidden in the sandbox: $*" >&2\necho "$*" >> "%s/gh-calls.log"\nexit 97\n' "$SB" > "$SB/stub-bin/gh" -chmod +x "$SB/stub-bin/gh" -printf '[user]\n\tname = Bash Upgrade Fixture\n\temail = fixture@docket.invalid\n[init]\n\tdefaultBranch = main\n' > "$SB/gitconfig" -cat > "$SB/sbx" < "$SB/task-start.txt" -cat "$SB/task-start.txt" - -# Step A — the tag and its installer, exactly as PROVENANCE.md Steps 2-3. -"$X" git clone --quiet --branch v0.9.3 --depth 1 file:///Users/homer/dev/docket "$SB/home/dev/docket" -"$X" git -C "$SB/home/dev/docket" remote remove origin -"$X" git -C "$SB/home/dev/docket" rev-parse HEAD -mkdir -p "$SB/home/.claude" "$SB/home/.cursor" "$SB/home/.codex" "$SB/home/.opencode" "$SB/home/.agents" -( cd "$SB/home/dev/docket" && "$X" /opt/homebrew/bin/bash ./install.sh ) > "$SB/install.log" 2>&1 -tail -n 3 "$SB/install.log" - -# Step B — the saved repository, restored the way the harness restores it. -"$X" git init --quiet --bare -b main "$SB/origin.git" -"$X" git -C "$SB/origin.git" fetch --quiet "$CASE/origin.bundle" 'refs/heads/*:refs/heads/*' -"$X" git clone --quiet "$SB/origin.git" "$SB/home/dev/sample" -cd "$SB/home/dev/sample" -"$X" git remote set-head origin main -"$X" git worktree add --quiet .docket docket -"$X" git config --local extensions.worktreeConfig true -mkdir -p "$SB/home/dev/sample/.git/docket/empty-hooks" -"$X" git -C .docket config --worktree core.hooksPath "$SB/home/dev/sample/.git/docket/empty-hooks" - -# Step C — migrate-to-docket.sh's step 5b, verbatim invocation shape (cwd = the repo). -"$X" env DOCKET_INTEGRATION_BRANCH=main DOCKET_BASH_PATH=/opt/homebrew/bin/bash \ - /opt/homebrew/bin/bash "$SB/home/dev/docket/scripts/ensure-claude-settings.sh" > "$SB/ensure-claude-settings.out" 2>&1 -cat "$SB/ensure-claude-settings.out" - -# Step D — PROVENANCE.md Step 7's real sync-agents.sh run on the committed configuration. -"$X" env DOCKET_BASH_PATH=/opt/homebrew/bin/bash /opt/homebrew/bin/bash "$SB/home/dev/docket/sync-agents.sh" \ - > "$SB/sync-agents-repo.out" 2> "$SB/sync-agents-repo.err" -grep -v -e 'no harness-specific model' "$SB/sync-agents-repo.err" || true -"$X" env DOCKET_BASH_PATH=/opt/homebrew/bin/bash /opt/homebrew/bin/bash "$SB/home/dev/docket/sync-agents.sh" --check \ - > "$SB/sync-check.out" 2> "$SB/sync-check.err"; echo "sync --check exit $?" -echo "--- git status (tracked changes must be none)" -"$X" git status --porcelain -echo "--- ignored" -"$X" git status --porcelain --ignored -[ -e "$SB/gh-calls.log" ] && { echo "FATAL gh called"; exit 97; } -echo "SB=$SB" -``` - -One run, exit 0. Results: - -- Step A repeats Steps 2–3: `rev-parse HEAD` printed `dd742abd5e9fcdf8ffe78eb6f36a293410873bbf` - and the install ended `docket: install complete`. `make-home-tar.py` (SHA-256 `de52b56e…11458`, - as above) run on `$SB2/home` wrote a tar **byte-identical** to the saved `home.tar` (`cmp` - silent), so this sandbox's home, including the global `config.yml` that `sync-agents.sh` reads - as a layer, equals the original's. -- Step B restores the bundle and replays `clone-config.txt` exactly as the test's `restoreCase` - does. -- Step C printed `ensure-claude-settings: created .claude/settings.local.json and granted: - Bash(git -C * push origin HEAD:main)`, the line the migration printed in Step 5. -- Step D's `sync-agents.sh` printed the 17 unpinned-agent warnings for the `agents` harness, the - no-named-emitter warning and `done`, and nothing about `CLAUDE.md` or `.gitignore`: the committed - dispatch block and ignore block were already what the tag writes. `sync-agents.sh --check` exited - 0. `git status --porcelain` was empty; `git status --porcelain --ignored` listed only `!! .claude/` - and `!! .docket/`. -- The 17 wrappers: `docket-implement-next.md` is pinned `model: claude-opus-5` / `effort: high`; - `docket-rebase-resolver.md` is the delegated wrapper (`model: inherit`, `docket.sh - runner-dispatch … --runner codex --agent rebase-resolver --model gpt-5.6-sol --effort high`). - No file holds a sandbox path. -- No `gh` call (`$SB2/gh-calls.log` never existed). `find ~/.claude/agents ~/.claude/skills - ~/.claude/settings.json ~/.claude/CLAUDE.md ~/.zshenv ~/.config/docket -newer - "$SB2/task-start.txt"` printed nothing. - -Export: - -```bash -OUT=/testdata/bash-upgrade/v0.9.3 -python3 "$SCRATCH/make-clone-tar.py" "$SB2/home" "$OUT/clone-files.tar" # members: 20 -tar -xOf "$OUT/clone-files.tar" | grep -c -e "$SB2" -e /tmp/claude-501 -e @@SANDBOX_HOME@@ # 0 -python3 "$SCRATCH/make-clone-tar.py" "$SB2/home" "$SB2/again.tar" && cmp "$SB2/again.tar" "$OUT/clone-files.tar" # identical -shasum -a 256 "$OUT/clone-files.tar" # 02c9e32ac2ccfa3809629a47fbe816555c00c450dfafecdc66971d69cb914c4c -``` - -`$SCRATCH/make-clone-tar.py` (SHA-256 -`d3aa64a8a65e7cb6d6972ffaf9924dabc17930361aa2f490d0271935763fa122`) is `make-home-tar.py` with its -root moved to the clone and its include list narrowed to `.claude`; the token rewrite still keys on -the sandbox home. Its full difference from `make-home-tar.py`: - -```diff -2c2,3 -< """make-home-tar.py SANDBOX_HOME OUT_TAR — scratch helper (never committed). ---- -> """make-clone-tar.py SANDBOX_HOME OUT_TAR — scratch helper (never committed); make-home-tar.py with -> the root moved to the sample clone and INCLUDE narrowed to its ignored .claude/ folder. -14a16 -> clone = os.path.join(home, "dev", "sample") -18,19c20 -< INCLUDE = [".claude", ".cursor", ".codex", ".agents", ".opencode", ".config/docket", -< "dev/docket/skills", ".zshenv"] ---- -> INCLUDE = [".claude"] -45c46 -< p = os.path.join(home, top) ---- -> p = os.path.join(clone, top) -69c70 -< ti = norm(tf.gettarinfo(os.path.join(home, rel), arcname=rel)) ---- -> ti = norm(tf.gettarinfo(os.path.join(clone, rel), arcname=rel)) -72c73 -< rel = os.path.relpath(path, home) ---- -> rel = os.path.relpath(path, clone) -``` - -## What `home.tar` holds - -| Folder | Written by | Contents | -|---|---|---| -| `.claude/` | `link-skills.sh`, `sync-agents.sh`, `ensure-docket-env.sh` | `skills/docket-*` (12 symlinks), `agents/docket-*.md` (17, including `docket-plan-writer.md`), `settings.json` with an `env` block setting `DOCKET_SCRIPTS_DIR` and `DOCKET_BASH_PATH` | -| `.cursor/` | same | `skills/` (12 symlinks), `agents/` (17), `rules/docket-dispatch.mdc` | -| `.codex/` | same | `skills/` (12 symlinks), `agents/docket-*.toml` (17). **Saved, never asserted.** | -| `.agents/` | same | `skills/` (12 symlinks, OpenCode's skill root), `agents/` (17, Claude-shaped, unpinned) | -| `.opencode/` | `sync-agents.sh` | `agents/docket-*.md` (17) | -| `.config/docket/` | `ensure-global-config.sh` | `config.yml` with the managed `runtime.bash` block | -| `dev/docket/skills/` | the tag checkout | the tree every skill symlink points at | -| `.zshenv` | `ensure-docket-env.sh` | the managed `DOCKET_SCRIPTS_DIR` / `DOCKET_BASH_PATH` export block | - -Not saved: `dev/sample` (it is the bundle plus `clone-config.txt` and `clone-files.tar`), `.cache`, `.local`, and the rest -of `dev/docket`. So after a restore, `DOCKET_SCRIPTS_DIR` in `.zshenv` and `settings.json` points at -`@@SANDBOX_HOME@@/dev/docket/scripts`, which does not exist. - -Like v0.9.2, v0.9.3 wrote **no** `~/.claude/CLAUDE.md` and no dispatch block anywhere under the -home. The repository, unlike the v0.9.2 one, does carry a dispatch block: `main:CLAUDE.md`, written -by `sync-agents.sh` because of the `agents:` opt-in. - -## Records - -| `records.txt` entry | Exercises | -|---|---| -| `docket:docs/adrs/0001-greeting-script-is-posix-sh.md` | ADR, `Accepted`, `change: 1`, made in main mode by the `docket-adr` flow, carried into the seeded root | -| `docket:docs/changes/active/0003-add-a-farewell-script.md` | proposed + spec (Brainstorm mode, made in main mode, carried by the seed), `related: [1]`, priority `high` | -| `docket:docs/changes/active/0004-add-a-license-file.md` | trivial proposed (`trivial: true`, no spec), made in docket mode | -| `docket:docs/changes/active/0005-read-the-default-greeting-name-from-the-environment.md` | deferred: minted by `mint-stub.sh` in docket mode (`discovered_from: [1]`, single-quoted `title:`), then the groom Defer exit | -| `docket:docs/changes/archive/2026-10-04-0001-add-a-greeting-script.md` | done #1, closed out in main mode before the migration: spec, plan, results, `adrs: [1]`, `pr:`, `reconciled: true`, empty `claimed_at:` | -| `docket:docs/changes/archive/2026-10-04-0002-document-the-greeting-script.md` | done #2: proposed in main mode, carried by the seed, then built and closed out in docket mode; trivial, `depends_on: [1]`, plan, results, `pr:`, empty `claimed_at:`; on `docket` only (`terminal_publish` was `false` then) | -| `docket:docs/changes/learnings/posix-sh-means-no-arrays.md` | learning from the main-mode finalize harvest; double-quoted `hook:` with `\"` escapes | -| `docket:docs/superpowers/specs/2026-10-04-add-a-farewell-script-design.md` | spec of 0003, back-link to `active/` | -| `docket:docs/superpowers/specs/2026-10-04-add-a-greeting-script-design.md` | spec of 0001, back-link re-stamped to `archive/` | -| `main:docs/adrs/0001-greeting-script-is-posix-sh.md` | the same ADR, kept on `main` by the migration (same blob as on `docket`) | -| `main:docs/changes/archive/2026-10-04-0001-add-a-greeting-script.md` | done #1, kept on `main` by the migration (same blob) | -| `main:docs/changes/learnings/posix-sh-means-no-arrays.md` | the learning, kept on `main` (same blob) | -| `main:docs/superpowers/specs/2026-10-04-add-a-farewell-script-design.md` | spec of 0003, kept on `main` (same blob) | -| `main:docs/superpowers/specs/2026-10-04-add-a-greeting-script-design.md` | spec of 0001, kept on `main` (same blob) | - -Counts: on `docket`, 5 changes (3 active, 2 archived), 1 ADR, 2 specs, 1 learning; on `main`, the -5 records the migration keeps (1 archived change, 1 ADR, 2 specs, 1 learning), each the same blob -as its `docket` copy. Also on `docket`, but not records: `docs/changes/BOARD.md` (the tag's board -render) and the `docs/adrs/README.md` and `docs/changes/learnings/README.md` indexes. Also on -`main`: `README.md`, `.docket.yml`, `.gitignore` (the managed block from the migration), -`CLAUDE.md` (the dispatch block), `hello.sh`, `USAGE.md`, the ADR and learnings indexes, the two -plans and the two results files. - -**Empty categories** (a saved case only covers what it contains): no in-progress, implemented, -blocked or killed change; no superseded or reversed ADR; no stacked change; no -`.docket.local.yml`; no change with a `## Run halted` section; no record published to `main` by -`terminal-publish.sh` (the `main` records are the ones the migration kept). - -## Gaps - -- **Interactive steps were hand-written** to the tag's prescribed shape, exactly as in the v0.9.2 - case: the specs and change bodies (`skills/docket-new-change/SKILL.md` Brainstorm and Trivial - modes, using `change-template.md`); the claim, reconcile, `plan:`, `adrs:`, `implemented` + - `pr:` + `results:` field writes (`skills/docket-implement-next/SKILL.md` Steps 2–7, including - the `claimed_at` re-stamp); the plan, code and results commits on `feat/`; the ADR - (`skills/docket-adr/SKILL.md` Create); the defer (`skills/docket-groom-next/SKILL.md` exit 4); - the learning (`skills/docket-finalize-change/SKILL.md` step 2.5); and the two `.docket.yml` - edits around the migration. Commit subjects use a `docket(): …` style. -- **No pull request was opened or merged on GitHub.** `gh` was stubbed out. Each `pr:` holds an - invented `https://github.com/fixture/sample/pull/` URL, and the merge is a local - `git merge --no-ff feat/` on `main` with GitHub's merge-commit subject, pushed to `origin`. -- **`terminal_publish` was `false`** while the changes closed out (the tag's default), so - `terminal-publish.sh` published nothing. It is `true` only in the final configuration. -- **The tag's merge-date command** in `terminal-close-out.md` step 1 needs `--format=%ad` (see the - v0.9.2 note); the driver uses that form from the start. -- **The per-clone ignored files were regenerated, not copied.** The first export (Step 8) left out - the two ignored paths in the sandbox clone, and that sandbox was gone by the time they were - needed: `.claude/settings.local.json` (the allow-rule written by `migrate-to-docket.sh` through - `ensure-claude-settings.sh`) and `.claude/agents/docket-*.md` (the 17 per-repository wrappers - `sync-agents.sh` generated because of the `agents:` opt-in, including the delegated - `docket-rebase-resolver.md`). Step 10 rebuilt them from the tag in a new sandbox, against the - saved bundle, by the same two tag commands. That sandbox's install reproduced `home.tar` byte for - byte, and its `sync-agents.sh` run left every tracked file unchanged, so the inputs matched the - original's. One difference remains: the clone the files sit in was restored from the bundle (as - the test restores it), not carried through the original's history, and `settings.local.json` - was written after the configuration commit rather than during the migration. Neither script - reads the history; `ensure-claude-settings.sh` reads only the integration branch, passed - explicitly as `main` exactly as `migrate-to-docket.sh` passes it. -- **The worktree-scoped `core.hooksPath`** is replayed through the `hooks-off` line, as in the - v0.9.2 case. diff --git a/testdata/bash-upgrade/v0.9.3/clone-config.txt b/testdata/bash-upgrade/v0.9.3/clone-config.txt deleted file mode 100644 index e7f206a83..000000000 --- a/testdata/bash-upgrade/v0.9.3/clone-config.txt +++ /dev/null @@ -1,17 +0,0 @@ -# clone-config.txt — actions the restore replays, in order, on a fresh clone of origin.bundle. -# Grammar: `config ` (git config --local) | `worktree ` (git worktree -# add, path relative to the clone root) | `hooks-off ` (what disable-worktree-hooks.sh does to -# that worktree: create /docket/empty-hooks and set the WORKTREE-scoped -# core.hooksPath to it). Recorded from the v0.9.3 sandbox clone; see PROVENANCE.md. -# -# migrate-to-docket.sh made the local `docket` branch (`git worktree add --orphan -b docket` in a -# temp worktree, then `git push -u origin docket`, which set branch.docket.remote/merge). The tag's -# `docket.sh preflight` later ran `git worktree add .docket docket` on that branch. On a fresh -# clone, git's DWIM creates the same local `docket` tracking `origin/docket`. -worktree .docket docket -# disable-worktree-hooks.sh (first run by migrate-to-docket.sh on its temp worktree, then by -# preflight on .docket) turned on per-worktree config ... -config extensions.worktreeConfig true -# ... and set the worktree-scoped key on .docket: -# `git -C .docket config --worktree core.hooksPath /.git/docket/empty-hooks`. -hooks-off .docket diff --git a/testdata/bash-upgrade/v0.9.3/clone-files.tar b/testdata/bash-upgrade/v0.9.3/clone-files.tar deleted file mode 100644 index 6f3e939a2..000000000 Binary files a/testdata/bash-upgrade/v0.9.3/clone-files.tar and /dev/null differ diff --git a/testdata/bash-upgrade/v0.9.3/home.tar b/testdata/bash-upgrade/v0.9.3/home.tar deleted file mode 100644 index f78e6f49d..000000000 Binary files a/testdata/bash-upgrade/v0.9.3/home.tar and /dev/null differ diff --git a/testdata/bash-upgrade/v0.9.3/origin.bundle b/testdata/bash-upgrade/v0.9.3/origin.bundle deleted file mode 100644 index ab9c71350..000000000 Binary files a/testdata/bash-upgrade/v0.9.3/origin.bundle and /dev/null differ diff --git a/testdata/bash-upgrade/v0.9.3/records.txt b/testdata/bash-upgrade/v0.9.3/records.txt deleted file mode 100644 index 618d93cff..000000000 --- a/testdata/bash-upgrade/v0.9.3/records.txt +++ /dev/null @@ -1,14 +0,0 @@ -docket:docs/adrs/0001-greeting-script-is-posix-sh.md -docket:docs/changes/active/0003-add-a-farewell-script.md -docket:docs/changes/active/0004-add-a-license-file.md -docket:docs/changes/active/0005-read-the-default-greeting-name-from-the-environment.md -docket:docs/changes/archive/2026-10-04-0001-add-a-greeting-script.md -docket:docs/changes/archive/2026-10-04-0002-document-the-greeting-script.md -docket:docs/changes/learnings/posix-sh-means-no-arrays.md -docket:docs/superpowers/specs/2026-10-04-add-a-farewell-script-design.md -docket:docs/superpowers/specs/2026-10-04-add-a-greeting-script-design.md -main:docs/adrs/0001-greeting-script-is-posix-sh.md -main:docs/changes/archive/2026-10-04-0001-add-a-greeting-script.md -main:docs/changes/learnings/posix-sh-means-no-arrays.md -main:docs/superpowers/specs/2026-10-04-add-a-farewell-script-design.md -main:docs/superpowers/specs/2026-10-04-add-a-greeting-script-design.md diff --git a/tests/runtime-budgets.tsv b/tests/runtime-budgets.tsv index 03a474331..6b723c98c 100644 --- a/tests/runtime-budgets.tsv +++ b/tests/runtime-budgets.tsv @@ -71,7 +71,6 @@ tests/test_go_integration_app_finalizerebaseops.sh 45 parallel tests/test_go_integration_app_evidence.sh 35 parallel tests/test_go_integration_app_recordops.sh 55 parallel tests/test_go_integration_app_contextprobe.sh 15 parallel -tests/test_go_integration_bashupgrade.sh 45 parallel tests/test_go_integration_contract.sh 15 parallel tests/test_go_integration_cli_agent.sh 15 parallel tests/test_go_integration_gitcli_concurrency.sh 10 parallel diff --git a/tests/test_go_integration_bashupgrade.sh b/tests/test_go_integration_bashupgrade.sh deleted file mode 100755 index ef96cf63f..000000000 --- a/tests/test_go_integration_bashupgrade.sh +++ /dev/null @@ -1,25 +0,0 @@ -#!/usr/bin/env bash -# docket-suite: go -# tests/test_go_integration_bashupgrade.sh — Go integration shard: the Bash docket -# v0.9.2/v0.9.3 upgrade proof. It restores the saved Bash installs under -# testdata/bash-upgrade/ and checks the binary built from this checkout against -# them (metadata ownership, then the upgrade guide's own marked steps), behind the -# `integration` build tag, prefix ^TestIntegrationBashUpgrade. Temporary: retired -# with internal/bashupgrade/ and testdata/bash-upgrade/ when stable v1.0.0 ships. -# Declarations only — execution and inspection live in -# tests/lib/go-integration-shard.sh; the completeness contract is -# tests/test_go_integration_contract.sh. -set -uo pipefail -REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)" -cd "$REPO" || exit 1 -fail=0 -assert(){ if eval "$2"; then printf 'ok - %s\n' "$1"; else printf 'NOT OK - %s\n' "$1"; fail=1; fi; } - -SHARD_PKG="./internal/bashupgrade" -SHARD_PREFIX="TestIntegrationBashUpgrade" -SHARD_MODE="normal" - -. "$REPO/tests/lib/go-integration-shard.sh" -shard_inspect_maybe -run_integration_shard -exit "$fail"