From 684588f8b4621eeb0870d64dd1c3123cbe8ac95e Mon Sep 17 00:00:00 2001 From: jdjioe5-cpu <297354017+CodingAngel1@users.noreply.github.com> Date: Sat, 17 Oct 2026 19:03:17 +0800 Subject: [PATCH] docs(readme): correct test counts and commands after a clean-machine run - Closes #37 (Roadmap row W-04 sdk slice) - Add 'First 15 minutes' quick-start section covering install, root vitest execution, builds, and local indexer instructions - Correct test suite file counts from 8/5 to 9 SDK files and 6 indexer files (15 test files, 165 tests total) - Document that SDK and indexer tests run from workspace root - Verified all commands: pnpm install, pnpm lint (73 files clean), pnpm typecheck, pnpm test (165 passed), and pnpm build - Update ROADMAP.md with Changelog entry (W-04 left TODO as required) --- README.md | 30 +++++++++++++++++++++++++++++- ROADMAP.md | 3 ++- 2 files changed, 31 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4dc2bab..a744c7e 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,34 @@ The TypeScript client for the `kinlock` contract (`packages/sdk`) and the event **Try it live (testnet):** [kinlock-app.vercel.app](https://kinlock-app.vercel.app) · **Docs:** [kinlock-org.github.io](https://kinlock-org.github.io) · **Indexer:** [indexer-production-705a.up.railway.app](https://indexer-production-705a.up.railway.app) (`GET /health`) +## First 15 minutes + +To get up and running from a fresh checkout: + +1. **Prerequisites:** Node 20+, pnpm 10 (`corepack enable pnpm`). +2. **Install dependencies:** + ```bash + pnpm install + ``` +3. **Run tests:** + ```bash + pnpm test + ``` + Vitest runs all 15 test files (9 in `@kinlock/sdk`, 6 in `@kinlock/indexer`) using in-process PGlite; no external database or local Postgres installation is required. + *Note: SDK and indexer tests run from the workspace root (packages do not define individual `test` scripts).* +4. **Build and check:** + ```bash + pnpm build + pnpm typecheck + pnpm lint + ``` +5. **Run the indexer locally (optional):** + ```bash + docker compose up -d # local Postgres 17 + pnpm --filter indexer db:migrate # apply Drizzle migrations + pnpm --filter indexer dev # watch poller + list API + ``` + ## Layout | Package | Name | What it is | @@ -59,7 +87,7 @@ Routes: `GET /health` (returns 503 when lagging), `/locks`, `/locks/:id`, `/paye pnpm lint && pnpm typecheck && pnpm test && pnpm build ``` -Vitest runs both projects (8 SDK test files, 5 indexer files against in-process Postgres via PGlite). Node 20, TypeScript 7, Biome for lint and format. `publish.yml` attaches a `.tgz` to a GitHub Release on any `sdk-v*` tag — packages ship as release artifacts, not through npm (ADR-0026). +Vitest runs both projects (15 test files: 9 SDK test files, 6 indexer test files against in-process Postgres via PGlite; 165 tests total as of 2026-10). Node 20, TypeScript 7, Biome for lint and format. `publish.yml` attaches a `.tgz` to a GitHub Release on any `sdk-v*` tag — packages ship as release artifacts, not through npm (ADR-0026). ## Read first diff --git a/ROADMAP.md b/ROADMAP.md index 0b2a524..a29cd09 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -4,7 +4,7 @@ | | | |---|---| -| **Last updated** | 2026-10-08 (W-05 resolved; 17 Wave issues seeded with seven new rows; issue format proofed against Drips' maintainer guide; the three pre-format issues triaged — app #16 re-emitted, app #15 and registry #7 closed as superseded; repo-side Changelog lines unioned back into canonical by `scripts/roadmap-merge`; that merge's ADR-link normalization anchored so quoted prose cannot be rewritten) | +| **Last updated** | 2026-10-17 (W-04 sdk slice #37 README clean-machine verification; 165 tests green) | | **Docs baseline** | v0.3, worldwide scope (`PRD.md`, `ARCHITECTURE.md`, `ARCHITECTURE_ESSENTIALS.md`, `AGENTS.md`, `CLAUDE.md`, `project_structure.md`) | | **Current phase** | Phase 0 (Foundations) → starting Phase 1 (M0 Validate) | | **Readiness** | See [§3](#3-progress-snapshot) | @@ -535,6 +535,7 @@ Newest first. One entry per PR. Required for every contribution (see §2). | Date | PR / ref | Repo | Rows touched | Summary | |---|---|---|---|---| +| 2026-10-17 | `docs/readme-clean-machine-verification` (#41) | sdk | W-04 (sdk slice) | Closes #37. Verified clean-machine onboarding from fresh clone to green test suite under 1 minute. Added 'First 15 minutes' quick-start guide covering prerequisites, root test execution, builds, and local indexer instructions. Corrected test suite counts from 8/5 to 9 SDK files and 6 indexer files (15 test files, 165 tests total). Re-verified all documented commands: pnpm install, pnpm lint (73 files clean), pnpm typecheck, pnpm test, and pnpm build. | | 2026-10-08 | `chore/roadmap-copy-back` (#39) | sdk | no row changes | Copy-back run: `ROADMAP.md` replaced with the merged canonical (`.github` main as of #31) in repo-root link form, and §3 recomputed with `scripts/roadmap-progress`. This is the step `roadmap-merge`'s header requires after every merge and that was skipped between 2026-10-06 and 2026-10-08, which is how the seven copies reached 92 divergent statuses. Verified in this checkout: the file equals canonical byte for byte apart from this entry and the ADR link prefix, `W-05` reads `DONE`, the seven Wave rows are present, duplicate row-ID scan is 0. No row, status, priority, dependency or **Done when** was authored in this repo. | | 2026-10-08 | `fix/roadmap-merge-link-anchor` | org | no row changes | Found while preparing the copy-back. `roadmap-merge`'s read normalization rewrote the docs-rooted ADR link form into the root-relative one on every copy so the two depths compare equal — correct for links, wrong for prose: the union entry above quotes both forms, so reading that line collapsed its own quote and emitted a Changelog entry contradicting itself, in a copy that no longer matched canonical line for line. Fixed by anchoring the replace on the numeric ADR filename that always follows the slash, so only real links are rewritten, and by re-wording the union entry to name the two forms as `docs/adr/` and `adr/` rather than spelling them as link text: **an entry that describes this rewrite must not itself be a string the rewrite can act on.** Verified: the anchored read leaves a quoted form byte-identical where the blanket replace corrupted it; a full `roadmap-merge` over all five copies against `b12d290` exits 0 with **0 lines** differing from canonical, which also confirms the union is complete; the one real link (`ADR-0026`) still normalizes both ways. No row, status, priority, dependency or **Done when** in this diff. | | 2026-10-08 | `chore/roadmap-changelog-union` | org | no row changes | Second `scripts/roadmap-merge` run now that the Wave-format PRs have merged (`.github` #26 and #27, contracts #31, sdk #38, app #43, registry #18). Three-way against `b12d290`, the revision where all five copies were last identical. The merge's **entire** output is four lines: the repo-side `docs/wave-issue-format` Changelog rows that each repo wrote into its own copy and canonical never saw. No row ID, status, priority, dependency or **Done when** moved — the seven new rows went in byte-identically, and `W-05`'s `TODO` → `DONE` stayed on the `org` row in canonical as §12 requires, so the repo copies' deliberately-untouched `TODO` was not merged back over it. §3 verified unchanged by `roadmap-progress`: 211 rows, 75 `DONE`, 40%. **Not in this PR:** the copy-back. Each repo's `ROADMAP.md` must be rewritten from the merged canonical, with the ADR links rewritten for the repo-root location, so all five copies are byte-identical again — that invariant is what makes `--ancestor` meaningful next time, and it needs four repo PRs that can only be cut after this lands. |