diff --git a/docs/handoff/20260618-handoff-74.md b/docs/handoff/20260618-handoff-74.md new file mode 100644 index 0000000..00da05b --- /dev/null +++ b/docs/handoff/20260618-handoff-74.md @@ -0,0 +1,137 @@ +# Session handoff — 2026-06-18 (74) + +Large session. Continues from handoff-73 (Ctrl-G demo alias). This one ran +the **road to public availability** end to end: a post-merge doc +reconciliation, then versioning, installers, crates.io/binstall, the +`cargo fmt` gate, and an actual **`v0.2.0` release that is now live on +crates.io**. Three new main-sequence ADRs (0054/0055/0056), one CI-ADR +amendment, issue **#35 closed**. + +## §1. State + +**Branch `main`.** **2509 pass / 0 fail / 1 ignored** (the long-standing +`friendly` doctest); **clippy clean**; **`cargo fmt --check` clean** (the +tree is now stock-rustfmt formatted, and CI gates it). `rdbms-playground +--version` → `rdbms-playground 0.2.0`. + +**Released:** **`v0.2.0`** — Gitea release with all six D1 targets +(Linux/Windows via `release.yaml` on the tag; macOS via the dispatched +`release-macos.yaml`, **ad-hoc-signed**). **Published to crates.io** +(`cargo install rdbms-playground` and `cargo binstall rdbms-playground` +both user-verified). + +**Push state:** earlier commits were pushed (they triggered CI/releases). +The **most recent commits are unpushed** and matter: +- `3c87dbb` macOS nix-prune fix (takes effect next macOS dispatch). +- `d3af1c4` + `8ebe213` the manual `publish.yaml` workflow — ADR-0056 in + the first, the **workflow file itself in the second** (`git commit -am` + had skipped the new untracked file). +- this handoff. +Push `main` to land them. (Push is the user's step.) + +## §2. What shipped (commits `628b250`→`d3af1c4`) + +- **`628b250` doc reconciliation** after the CI + website branch merges: + rewrote CLAUDE.md's stale repo-layout tree; added a Website subproject + note; fixed the CI note; **gitignored `.wrangler/` + `.vscode/`** and + removed a tracked `website/.vscode/`; updated requirements (D1 macOS + runtime-verified, DOC1 canonical-docs-on-website) + ADR-ci-003. +- **`c30a611` ADR-0054 — version surfaces.** `--version`/`-V` + an in-app + **`version`** command, both reading `CARGO_PKG_VERSION` via one + `cli::version_text()`. A **release-CI guard** fails the release unless + the `v*` tag equals `v`. +- **`ef99e6c` ADR-0055 — `scripts/install.sh`** (curl|sh, POSIX, + shellcheck-clean, checksum-verified, `~/.local/bin`). Verified + end-to-end against the live release. **`install.ps1`** (Windows + `irm|iex`) added later (`e9606b5`) — **written but untested here** (no + PowerShell on this box; validate on Windows). +- **`e9606b5` ADR-0056 — crates.io + binstall prep.** Publish-ready + Cargo.toml (dropped `publish=false`; homepage/keywords/categories/ + `exclude`); `README.md`; `LICENSE-MIT`/`LICENSE-APACHE` (dual, © Lazy + Evaluation Ltd) + `CONTRIBUTING.md` (inbound=outbound); the + `[package.metadata.binstall]` block with per-target overrides + (linux-gnu→musl, windows-msvc→gnu/gnullvm; macOS direct). +- **`41b7e9a` + `ec3c7c3` — #35 fmt gate.** One mechanical `cargo fmt` + (stock defaults, 102 files, behaviour-preserving) recorded in + `.git-blame-ignore-revs`; `ci.yaml` now gates `fmt --check` (ADR-ci-002 + Amendment 1). **Closes #35.** +- **`88830ed`+`bd5be5e` — v0.2.0 bump + the guard bug.** The first + `release.yaml` run **failed** at the version guard: it piped `nix + develop -c cargo metadata` to node, but the **flake devShell prints a + banner to stdout**, corrupting the JSON. Fixed to a toolchain-free + `grep -m1 '^version = ' Cargo.toml`. The `v0.2.0` tag was re-pointed + (Option A) to the fix commit; re-run went green. +- **`3c87dbb` — macOS nix-prune fix.** The prune step's profile dir + (`~/.cache/rdbms-ci`) didn't exist, so `nix develop --profile` errored + (swallowed by `|| true`) → the gc-root was never created → the whole + toolchain (~3.8 GiB) was deleted **and re-downloaded every run**. Added + `mkdir -p` + dropped the `|| true`. Diagnosed from the run-74 log via + `tea actions runs logs 74`. +- **`d3af1c4` — manual `publish.yaml`.** `workflow_dispatch` + `tag` + input (mirrors `release-macos.yaml`). Idempotent `crates-io` job + (crates.io API pre-check + `cargo publish` backstop), independent jobs + so Scoop/Homebrew/winget slot in later. ADR-0056 Amendment 1. + +## §3. Live vs manual vs parked + +- **Automated on a `v*` tag:** `release.yaml` builds + publishes the four + Linux/Windows targets (+ fmt/clippy/test gate). +- **Manual `workflow_dispatch`:** `release-macos.yaml` (mac binaries — + intermittent runner) and `publish.yaml` (crates.io now; more registries + later). Run them once the tag's build is up. +- **Parked (user decisions):** + - **macOS Developer-ID signing.** The pipeline **ad-hoc-signs** + (`codesign --sign -`). The user's `Apple Development` cert is the + **wrong type** — distribution needs **`Developer ID Application`** + + **notarization** (App Store Connect API key recommended). Fine for + `curl|sh` (no quarantine); matters for browser downloads. Details in + `docs/plans/20260616-public-availability.md`. + - **Remaining D3:** Scoop (`lazyeval` bucket), Homebrew (`lazyeval` + tap), winget (komac on Linux CI, or manual PR) — each a sibling job + in `publish.yaml` + a manifest repo. + +## §4. Immediate next steps + +1. **Push `main`** (lands `3c87dbb` + `d3af1c4`). +2. **Add the `CARGO_REGISTRY_TOKEN` secret** (crate-scoped, + `publish-update`) so `publish.yaml` works: `tea actions secrets create + CARGO_REGISTRY_TOKEN` (paste at prompt) or the Gitea UI. +3. **Smoke-test `publish.yaml`:** dispatch it for `v0.2.0` — it should + **idempotently skip** ("already on crates.io"), exercising the path + risk-free. +4. The release ritual going forward (ADR-0054): bump `Cargo.toml` → + commit → tag `v` → push tag (Linux/Windows release builds) → + dispatch `release-macos` → dispatch `publish`. + +## §5. Gotchas learned (don't relearn the hard way) + +- **The flake devShell prints a banner to stdout** — never pipe `nix + develop -c ` into a parser. Read Cargo.toml directly, etc. +- **Workflow-file source differs by trigger:** a **tag**-triggered run + (`release.yaml`) uses the workflow **at the tagged commit**; a + **`workflow_dispatch`** run (`release-macos`/`publish`) uses the + **default branch** (`main`). So fixing a dispatched workflow only needs + a `main` push; fixing a tag-triggered one needs the tag re-pointed. +- **Version vs tag:** `Cargo.toml` is bare `0.2.0`; the git tag is + `v0.2.0`; the guard checks `tag == "v" + version`; binstall `pkg-url` + spells `v{ version }`. +- **CI logs are reachable** via `tea actions runs logs ` (and `tea + actions runs list --output tsv`). Use it instead of guessing from a + step name. +- **crates.io API needs a descriptive User-Agent** (403 without one). + +## §6. How to take over + +1. Read handoffs 72 → 73 → 74, `CLAUDE.md`, `docs/requirements.md`, and + **`docs/plans/20260616-public-availability.md`** (the GA roadmap with + all decisions + parked items). +2. Confirm green: `cargo test` (**2509 / 1 ignored**), `cargo clippy + --all-targets`, `cargo fmt --check`. +3. ADRs for this arc: **0054** (versioning), **0055** (installer), + **0056** (crates.io/binstall + the publish workflow); CI side + **ADR-ci-002 Amendment 1** (fmt gate), **ADR-ci-003** (release matrix + + macOS). +4. Workflow unchanged: phased, test-first, `/runda` + DA before commits, + ADR amendment + README index-upkeep for decided-area changes, confirm + commit messages, never push. +5. Consider a `cargo sweep` at this milestone (`target/` grows).