docs: reconcile docs after ci+website merges; gitignore wrangler/vscode

Post-merge documentation accuracy pass (CI and website branches both
merged to main; website deployed).

- CLAUDE.md: rewrite the stale repository-layout tree; add a Website &
  docs-site decision bullet (Astro+Starlight, Cloudflare Pages via Gitea
  Actions, ADR-website-001, the website branch stays open); update the CI
  note (merged to main; release-macos dispatchable + verified working).
- requirements.md: D1 — macOS targets now runtime-verified (release-macos
  dispatched end-to-end); DOC1 — canonical user docs now live on the
  deployed website.
- ADR-ci-003 (+ docs/ci/adr README): Amendment 2 — CI on main,
  release-macos dispatched + verified; macOS runtime-verified.
- docs/website/adr README: drop the stale "no CI yet".
- .gitignore: ignore .wrangler/ (Cloudflare Wrangler cache) and .vscode/;
  remove the tracked website/.vscode/ an Astro template had added.

D3 (package-manager manifests) + some install instructions remain open.
This commit is contained in:
claude@clouddev1
2026-06-16 15:06:49 +00:00
parent 784373a254
commit 628b250db6
8 changed files with 91 additions and 54 deletions
+6
View File
@@ -12,7 +12,13 @@
*.snap.new
*.pending-snap
# Website tooling — Cloudflare Wrangler local cache/state (regenerable;
# CI deploys from website/, this dir only appears on a local wrangler run)
.wrangler/
# Editor / OS
.DS_Store
*.swp
*.swo
# Astro/template-seeded editor configs we don't track (e.g. website/.vscode)
.vscode/
+56 -27
View File
@@ -108,10 +108,11 @@ Current decisions at a glance (each backed by an ADR):
SQL `select` / `with` / `insert` / `update` / `delete`
(ADR-0039). `EXPLAIN QUERY PLAN` never executes, so
explaining a destructive command is safe.
- **Continuous integration & release** (built on the `ci` branch,
2026-06-15; decisions in `docs/ci/adr/` — **ADR-ci-001/002/003**,
a namespace kept separate from the main ADR sequence to avoid
cross-branch number collisions, like the website's): a self-hosted
- **Continuous integration & release** (developed on the `ci` branch,
**merged to `main` 2026-06-15**; decisions in `docs/ci/adr/` —
**ADR-ci-001/002/003**, a namespace kept separate from the main ADR
sequence to avoid cross-branch number collisions, like the website's):
a self-hosted
**Gitea Actions** pipeline built on a **nix flake** (pinned Rust
`1.95.0` — one source of toolchain for dev *and* CI) plus a
prebuilt CI image. **Gate** (`ci.yaml`): `clippy -D warnings` +
@@ -122,44 +123,72 @@ Current decisions at a glance (each backed by an ADR):
`release-macos.yaml` on a Tart Apple-Silicon runner (de-nix the
`libiconv` load path + ad-hoc re-sign). All published to a Gitea
release with `.sha256`s. **`fmt` is intentionally not gated yet**
(the tree isn't stock-`rustfmt`-clean). `workflow_dispatch` is
Gitea-default-branch-only, so `release-macos` is dispatchable once
this lands on `main`.
(the tree isn't stock-`rustfmt`-clean). Now that this is on `main`,
`release-macos` is dispatchable (`workflow_dispatch` is
Gitea-default-branch-only) — **dispatched and verified working**: the
macOS build + de-nix/re-sign + upload runs end-to-end and the binaries
launch.
- **Website & docs site** (developed on the `website` branch, **merged
to `main`**; the branch **stays open** for future staging deploys;
decisions in `docs/website/adr/` — **ADR-website-001**, its own
namespace like CI's): an **Astro + Starlight + Tailwind** marketing
landing page plus the **canonical** user docs, under `website/`.
Showcase demos are **asciinema casts** (a scripted-input driver, paced
+ re-recordable — *not* `history.log` replay; the `--demo` overlay,
ADR-0047, dresses them). **Deployed to Cloudflare Pages via Gitea
Actions** (`.gitea/workflows/website.yaml`; the crate gate is skipped
for website-only changes). Two copy rules bind user-facing text: **no
engine name** (continues ADR-0002) and **no "DSL"** (say "simple mode"
/ "advanced mode"). Install docs are still partial — package-manager
manifests + some installation instructions are pending (`requirements.md`
D3 / DOC1).
## Repository layout
```
.
├── Cargo.toml # dependencies, lints (nursery)
├── Cargo.toml / Cargo.lock # dependencies, lints (nursery)
├── CLAUDE.md # this file
├── flake.nix / flake.lock # pinned Rust toolchain, one source for dev + CI (ADR-ci-002)
├── rust-toolchain.toml # toolchain pin
├── .gitea/ # Gitea Actions workflows + prebuilt CI image (ADR-ci-001..003, website)
├── ci/ # CI build helpers (e.g. winstub/ — Windows link stub)
├── docs/
│ ├── adr/ # all decision records (read 0000 first)
│ ├── adr/ # project-wide decision records (read 0000 first)
│ ├── ci/{adr,handoff}/ # CI subproject ADRs (ci-001..003) + handoffs
│ ├── website/{adr,plans}/ # website subproject ADRs (website-001) + plan
│ ├── handoff/ # session-handover notes
│ ├── plans/ # working plans
│ └── requirements.md # the Phase-1 checklist with progress
├── src/
│ ├── action.rs # Action enum (Quit / ExecuteDsl)
│ ├── action.rs # Action enum (Quit / ExecuteDsl / …)
│ ├── app.rs # App state + pure update() + Tier-1 tests
│ ├── cli.rs # CLI args (--theme, --log-file)
│ ├── cli.rs # CLI args (--theme, --log-file, --demo, --no-undo, --resume, …)
│ ├── clipboard.rs # copy output to the system clipboard
│ ├── completion.rs # Tab completion + schema cache
│ ├── db.rs # rusqlite worker, all DDL/DML, metadata tables
│ ├── dsl/
│ │ ├── action.rs # ReferentialAction enum + parsing
│ │ ├── command.rs # Command AST + RelationshipSelector + RowFilter
│ │ ├── mod.rs # re-exports
│ ├── parser.rs # parse entry point → unified-grammar walker
│ │ ├── shortid.rs # base58 generator + validator
│ │ ├── types.rs # user-facing Type enum + fk_target_type
│ │ └── value.rs # Value/Bound + per-type validation
│ │ ├── grammar/ # hand-rolled unified grammar nodes (DSL + SQL)
│ │ ├── walker/ # grammar walker (driver / context / highlight / outcome)
│ │ ├── command.rs parser.rs types.rs value.rs action.rs shortid.rs sql_functions.rs
├── echo.rs # command echo / SQL rendering
│ ├── event.rs # AppEvent (input + DSL outcomes)
│ ├── lib.rs # module re-exports for tests
│ ├── logging.rs # tracing setup, file-backed
│ ├── main.rs # binary entry; thin
│ ├── mode.rs # Simple/Advanced mode enum
│ ├── runtime.rs # Tokio loop, terminal setup, dispatch
│ ├── friendly/ # friendly-error layer + string catalog (strings/en-US.yaml) + keys
│ ├── input_render.rs # input-field render + ambient hint classification
│ ├── output_render.rs # output-panel render helpers (incl. relationship diagrams)
│ ├── logging.rs main.rs mode.rs runtime.rs # tracing / entry / mode enum / Tokio loop
│ ├── persistence/ # csv + yaml + history IO + migrations
│ ├── project/ # open/create, lock, naming, prettifier
│ ├── seed/ # seed generators / heuristics / vocabulary (ADR-0048)
│ ├── snapshots/ # insta snapshots for Tier-2 tests
│ ├── theme.rs # light/dark themes
│ └── ui.rs # ratatui rendering
── tests/
── walking_skeleton.rs # Tier-3 integration tests
│ ├── theme.rs type_change.rs ui.rs undo.rs # themes / column type-change / render / undo ring
│ └── lib.rs # module re-exports for tests
── tests/
── it/ # Tier-3 integration tests (consolidated into one binary)
│ └── typing_surface_matrix.rs # typing-surface matrix (separate Tier-3 target)
└── website/ # Astro + Starlight docs/marketing site (ADR-website-001)
├── src/ public/ casts-src/ # pages + assets + asciinema cast sources
└── astro.config.mjs package.json … # deploys to Cloudflare Pages via Gitea Actions
```
Key invariants in the code:
+11
View File
@@ -20,6 +20,17 @@ This ADR records the **cross-platform build strategy**; it sits on top of
**ADR-ci-002** (the nix flake, which now carries the cross toolchain) and
**ADR-ci-001** (the pipeline, whose release job this fills in).
## Amendment 2 — 2026-06-16: CI on `main`; `release-macos` dispatched + verified
The CI branch is **merged to `main`**, so `release-macos.yaml`
(`workflow_dispatch`, Gitea-default-branch-only) is now triggerable. It
has been **dispatched and verified end-to-end**: both `*-apple-darwin`
targets build on the Tart runner, the de-nix/re-sign step runs, the
assets upload to the tagged release, and the binaries launch. macOS is
therefore runtime-verified (alongside the original Linux x86_64 +
Windows aarch64); only **Linux aarch64** and **Windows x86_64** remain
link-clean / valid-format without a runtime smoke-test.
## Amendment — 2026-06-14: macOS implemented (closes D1)
macOS is no longer deferred. The two `*-apple-darwin` targets now build on a
+1 -1
View File
@@ -20,4 +20,4 @@ here too).
- [ADR-ci-001 — CI + release pipeline on Gitea Actions](20260612-adr-ci-001.md) — **Accepted 2026-06-12** (implemented the same day on the `ci` branch). Establishes the CI/release pipeline on the self-hosted Gitea instance's Actions runner (`ci-public`). **Runner model** (established by a throwaway probe): jobs execute *inside* a container (`catthehacker/ubuntu:act-22.04` by default), as root, so the runner host's nix is **not** reachable from steps. **Toolchain delivery:** a **baked CI image**`node:22-bookworm-slim` (satisfies the act_runner job-container contract: `/bin/sleep` keep-alive, `bash`, `node` for JS actions; a bare `nixos/nix` image lacks these and won't start) **+ single-user nix + the flake's devShell pre-warmed** — built by `build-ci-image.yaml` via DinD and pushed to the Gitea container registry as a **public** package, so CI runs `nix develop -c …` against the **same pinned toolchain as dev** (the flake, ADR-ci-002) with a warm store (~1.4 s to a ready toolchain). **Gate** (`ci.yaml`): `clippy -D warnings` + `cargo test` inside that image on branch pushes + PRs; **fmt deliberately not gated** (the tree isn't stock-rustfmt-clean — user decision, revisit on `main`; see ADR-ci-002). **Release** (`release.yaml`): on a `v*` tag, runs the tests, builds the **static `x86_64-unknown-linux-musl` binary** (D2: single static binary, no runtime deps — the glibc/nix build is non-portable), strips it, and publishes it + a `.sha256` to a Gitea release via the API and the auto-provided `GITEA_TOKEN`. **Triggers:** gate + image-build are scoped to **branch** pushes (`branches: ['**']`) so a release tag doesn't spuriously re-run them; the image-build additionally path-filters to its inputs (Dockerfile/flake/toolchain); the release owns tags. **Auth:** a dedicated PAT (`REGISTRY_USERNAME`/`REGISTRY_TOKEN` secrets) pushes the image; the auto `GITEA_TOKEN` publishes releases. **Scope:** the original release job was Linux x86_64 only; it's now the **four non-macOS D1 targets** (Linux + Windows × x86_64/aarch64) cross-built via cargo-zigbuild — see **ADR-ci-003**. macOS, D3 package-manager manifests, CI-speed dependency caching, and the website's static→Cloudflare deploy remain deferred, added step by step. Verified live: probe → runner facts; image built + checked locally; gate green (**2424 tests**); release exercised end-to-end (`v0.0.0-citest2` published with binary + checksum). Builds on **ADR-ci-002** (the nix flake, relocated here from main's ADR-0049 to avoid exactly this cross-branch collision).
- [ADR-ci-002 — Nix flake for a reproducible dev + build environment](20260612-adr-ci-002.md) — **Accepted 2026-06-12** (relocated from main's **ADR-0049** on the same day — content unchanged — to keep CI/dev-env decisions out of `main`'s integer sequence). The single, version-pinned declaration of the **dev *and* build toolchain** so CI never relies on whatever Rust is on the build machine — mirroring **datamage ADR 0046**, but far simpler (pure-Rust TUI). Root **Nix flake** with two outputs: **`devShells.default`** (pinned **Rust 1.95.0** via `rust-toolchain.toml` + `rust-overlay`, `cargo-sweep`, and the musl cc for the static release build) and **`packages.default`** (`rustPlatform.buildRustPackage` from the committed `Cargo.lock`; `doCheck = false`). Exact-pin (not floating `stable`) so `nix flake update` can't surprise-bump clippy past the `-D warnings` gate. System inputs near-empty by design (`libsqlite3-sys bundled` → stdenv cc only; `arboard``x11rb` pure-Rust). `.envrc` (`use flake`) for direnv parity. Verified through the flake: `nix build` yields a working binary, clippy clean, **2424 tests pass / 0 fail / 1 intentional ignored doctest**. Consumed by **ADR-ci-001** (the pipeline). Alternatives rejected: dev-shell-only; a standard `rust:1.95` CI image (a second toolchain definition = drift); `rustup` on the build host (non-reproducible).
- [ADR-ci-003 — Cross-platform release builds (the D1 matrix)](20260613-adr-ci-003.md) — **Accepted 2026-06-13** (implemented + a real matrix release verified the same day — tag `v.0.0.0-citest3` published 8 assets). Cross-compiles the **four non-macOS D1 targets** from the Linux x86_64 runner with **`cargo-zigbuild`** (Zig's bundled clang + libc as one universal cross cc/linker, incl. rusqlite's bundled SQLite C; added to the flake devShell, replacing the single-target musl cc): **`x86_64`/`aarch64-unknown-linux-musl`** (musl + crt-static → fully static, **D2**) and **`x86_64-pc-windows-gnu`** / **`aarch64-pc-windows-gnullvm`** (Zig statically links libc → standalone `.exe`). **Windows `synchronization` stub:** Rust std links `-lsynchronization` (WaitOnAddress thread-parking), an import lib rust-overlay's toolchain doesn't ship and Zig's mingw lacks; the symbols are forwarded by `kernel32`, so an **empty 8-byte stub** `libsynchronization.a` (`ci/winstub/`, wired via `.cargo/config.toml` for the Windows targets only) satisfies the linker. **Workflow:** `release.yaml` = **`test` once (host) → `build` matrix** over the four targets (`needs: test`, `fail-fast: false`); each job packages binary (`.exe` for Windows) + `.sha256` and uploads to the **shared release** via idempotent create-or-get. **macOS** (2026-06-14 amendment) — built natively on a **Tart (Apple-Silicon) runner** (`runs-on: macos`), which makes the SDK fully licensed and dissolves the grey-area/public-image problem; `release-macos.yaml` is **dispatch-only** (intermittent runner; becomes triggerable once CI is on `main`), de-nixes the binary's libiconv load path (`install_name_tool``/usr/lib`) + re-signs ad-hoc, and uploads to the tagged release. **D1 complete (all six targets).** Alternatives rejected: `cross` (no macOS, needs DinD), per-target nix cross (Windows-aarch64 unpackaged, macOS-from-Linux unsupported), a real `libsynchronization.a` (more machinery, doesn't cover Windows-aarch64). Runtime-verified by the user (2026-06-13): Linux x86_64 + Windows aarch64 run correctly; Linux aarch64 + Windows x86_64 are the outstanding runtime checks. Builds on ADR-ci-002 (flake) and fills in ADR-ci-001 §3 (Release).
- [ADR-ci-003 — Cross-platform release builds (the D1 matrix)](20260613-adr-ci-003.md) — **Accepted 2026-06-13** (implemented + a real matrix release verified the same day — tag `v.0.0.0-citest3` published 8 assets). Cross-compiles the **four non-macOS D1 targets** from the Linux x86_64 runner with **`cargo-zigbuild`** (Zig's bundled clang + libc as one universal cross cc/linker, incl. rusqlite's bundled SQLite C; added to the flake devShell, replacing the single-target musl cc): **`x86_64`/`aarch64-unknown-linux-musl`** (musl + crt-static → fully static, **D2**) and **`x86_64-pc-windows-gnu`** / **`aarch64-pc-windows-gnullvm`** (Zig statically links libc → standalone `.exe`). **Windows `synchronization` stub:** Rust std links `-lsynchronization` (WaitOnAddress thread-parking), an import lib rust-overlay's toolchain doesn't ship and Zig's mingw lacks; the symbols are forwarded by `kernel32`, so an **empty 8-byte stub** `libsynchronization.a` (`ci/winstub/`, wired via `.cargo/config.toml` for the Windows targets only) satisfies the linker. **Workflow:** `release.yaml` = **`test` once (host) → `build` matrix** over the four targets (`needs: test`, `fail-fast: false`); each job packages binary (`.exe` for Windows) + `.sha256` and uploads to the **shared release** via idempotent create-or-get. **macOS** (2026-06-14 amendment) — built natively on a **Tart (Apple-Silicon) runner** (`runs-on: macos`), which makes the SDK fully licensed and dissolves the grey-area/public-image problem; `release-macos.yaml` is **dispatch-only** (intermittent runner), de-nixes the binary's libiconv load path (`install_name_tool``/usr/lib`) + re-signs ad-hoc, and uploads to the tagged release. **D1 complete (all six targets).** Alternatives rejected: `cross` (no macOS, needs DinD), per-target nix cross (Windows-aarch64 unpackaged, macOS-from-Linux unsupported), a real `libsynchronization.a` (more machinery, doesn't cover Windows-aarch64). **Amendment 2 (2026-06-16):** CI is **merged to `main`**, so `release-macos` is now triggerable (`workflow_dispatch` is default-branch-only) and has been **dispatched + verified end-to-end** (build → de-nix/re-sign → upload, binaries launch). Runtime-verified by the user: Linux x86_64, Windows aarch64, **and both macOS targets**; Linux aarch64 + Windows x86_64 are the outstanding runtime checks. Builds on ADR-ci-002 (flake) and fills in ADR-ci-001 §3 (Release).
+9 -3
View File
@@ -70,8 +70,11 @@ since ADR-0027.)
natively on a Tart Apple-Silicon runner via the dispatched
`release-macos.yaml`. All uploaded to the Gitea release with a
`.sha256` each. Decisions in `docs/ci/adr/` (ADR-ci-001/002/003).
Runtime-verified by the user: Linux x86_64 + Windows aarch64; the
others are link-clean / valid format.)*
Runtime-verified by the user: Linux x86_64, Windows aarch64, and both
macOS targets (the `release-macos.yaml` dispatch — now triggerable
since CI is on `main` — was run end-to-end and the binaries launch);
Linux aarch64 + Windows x86_64 remain link-clean / valid-format
only.)*
- [x] **D2** Single static binary, no runtime dependencies.
*(Done 2026-06-15, per platform: **Linux** is fully static (musl +
`crt-static`); **Windows** is a standalone `.exe` (Zig statically
@@ -888,7 +891,10 @@ since ADR-0027.)
exists (~55 lines, covers the WHERE-expression and
table-creation boundaries). **Missing:** a DSL
command-surface reference and a standalone type-system
reference under `docs/`.)*
reference under `docs/`. **Note (2026-06-16):** the **canonical**
user docs now live on the **website** (ADR-website-001, deployed) —
it covers the full feature set; the in-repo `docs/` reference pieces
named here remain the outstanding part of DOC1.)*
## Testing (per ADR-0008)
+1 -1
View File
@@ -16,4 +16,4 @@ applies here too).
## Index
- [ADR-website-001 — Public website and documentation site](20260604-adr-website-001.md) — **Accepted 2026-06-04** (formerly ADR-0044 in the main index; moved here 2026-06-10 to end recurring cross-branch number collisions). The first public website: a marketing landing page plus the **canonical** user docs. Stack **Astro 6 + Starlight + Tailwind v4** (chosen over SvelteKit + Tailwind for a docs-heavy + marketing site; interactive bits as Astro islands). Showcase demos are **asciinema** `.cast` recordings (scripted-input driver for paced, re-recordable sessions — *not* `history.log` replay), reused inline in docs. The **in-page WASM playground is deferred** (OOS: deferred) behind a stable `Demo` seam, with the portable-core vs native-edge boundary recorded for a future ADR + iteration plan. Portable **static build** (**Cloudflare** target via **Gitea Actions**, host-agnostic); **no CI yet**; **monorepo** (`website/`). Docs cover the **full supported feature set** with "planned" callouts for the unshipped minority; two wording rules bind user-facing copy — **no engine name** (continues ADR-0002) and **no "DSL"** ("simple mode" / "advanced mode"). Install docs cover **prebuilt binaries + package managers** (D1D3 track the release tooling). Plan: [`docs/website/plans/20260604-website-implementation-plan.md`](../plans/20260604-website-implementation-plan.md)
- [ADR-website-001 — Public website and documentation site](20260604-adr-website-001.md) — **Accepted 2026-06-04** (formerly ADR-0044 in the main index; moved here 2026-06-10 to end recurring cross-branch number collisions). The first public website: a marketing landing page plus the **canonical** user docs. Stack **Astro 6 + Starlight + Tailwind v4** (chosen over SvelteKit + Tailwind for a docs-heavy + marketing site; interactive bits as Astro islands). Showcase demos are **asciinema** `.cast` recordings (scripted-input driver for paced, re-recordable sessions — *not* `history.log` replay), reused inline in docs. The **in-page WASM playground is deferred** (OOS: deferred) behind a stable `Demo` seam, with the portable-core vs native-edge boundary recorded for a future ADR + iteration plan. Portable **static build** (**Cloudflare** target via **Gitea Actions**, host-agnostic); **monorepo** (`website/`). **§4 update (CI implemented):** the static→Cloudflare Pages deploy now runs via Gitea Actions (`.gitea/workflows/website.yaml`; the crate gate is skipped for website-only changes); both `website` and `main` are merged and the site is **deployed**. Docs cover the **full supported feature set** with "planned" callouts for the unshipped minority; two wording rules bind user-facing copy — **no engine name** (continues ADR-0002) and **no "DSL"** ("simple mode" / "advanced mode"). Install docs cover **prebuilt binaries + package managers** (D1D3 track the release tooling). Plan: [`docs/website/plans/20260604-website-implementation-plan.md`](../plans/20260604-website-implementation-plan.md)
-4
View File
@@ -1,4 +0,0 @@
{
"recommendations": ["astro-build.astro-vscode"],
"unwantedRecommendations": []
}
-11
View File
@@ -1,11 +0,0 @@
{
"version": "0.2.0",
"configurations": [
{
"command": "./node_modules/.bin/astro dev",
"name": "Development server",
"request": "launch",
"type": "node-terminal"
}
]
}