mirror of https://github.com/J3vb/OwnCord.git synced 2026-09-03 03:50:00 +03:00

Files

T

J3vbandClaude eb873fe7b2 B1-6: generated artifacts (RL-06 / L-06, RL-07 / L-07, RL-08 / L-08) (#1418 )

* ci: verify FINDINGS.md against the ledger it renders from (RL-07)

`.superpowers/FINDINGS.md` is generated from `findings-ledger.json`, and
`CLAUDE.md` forbids hand-editing it — but nothing checked. The one automated
consumer, `render-ledger.mjs --check`, validates the ledger's JSON schema and
`return`s at line 116, *before* the only `render()` call at line 118, and never
opens `FINDINGS.md` at all. A stale 1.09 MB rendering passed it cleanly.

The audit says "no workflow runs it". That was true when it was written and is
not now: B1-2 (#1412) wired `--check` into the `Docs & Ledger Consistency` job.
So the gate exists, reports, and is blind to the thing its name suggests it
watches — which is worse than absent, because it reads as covered.

The obvious fix — render to a temp file and diff, as the B1 plan suggests — is
not what this repository does. It has three implementations of one idea
(`Server/Makefile` sqlc-verify and protocol-verify, `.githooks/pre-commit`,
`scripts/run.mjs`), and all three regenerate **in place** and let `git diff
--exit-code` be the differ. That needs no temp path, no cleanup, and inherits
`.gitattributes`' line-ending normalisation for free. A fourth shape would cost
a reader something for nothing.

Done:
- The gate, in all three places the existing two gates live: the
  `docs-consistency` CI job, `scripts/run.mjs`'s `CHECK_DOCS`, and a new
  `.githooks/pre-commit` block gated on the ledger, the rendering, or the
  renderer being staged. `npm run check` never ran the renderer at all before
  this, which contradicted `run.mjs`'s own stated purpose.
- `validate()` now requires `severity`. This is not a nice-to-have riding
  along: `render()` sorts the open section by `SEV_RANK`, and an unranked
  severity makes the comparator return `NaN`, which leaves the sort order
  implementation-defined. A gate whose expected output is implementation-defined
  can go red across a Node upgrade for a reason that is not drift. The
  validation is what makes the gate's premise — that the rendering is a pure
  function of the ledger — true rather than merely true today.
- `--stat` on the diff. Deliberate deviation from the three precedents: a fully
  drifted rendering is a ~40,000-line CI log, and the exit code is what gates.

Eight files, 119 insertions, 24 deletions. The gate is one render (67-170 ms)
plus one `git diff`. Rendering subsumes `--check`, because `main()` validates
and exits 1 before it writes — so the CI job keeps both steps only so the checks
UI names which fix is needed.

Verified: both directions, and the naive test would have lied. Appending to
`FINDINGS.md` proves nothing — the renderer overwrites it, so the perturbation
vanishes and the diff comes back clean. `git diff <path>` compares the worktree
against the **index**, so the drift has to live in the index. Changing one
finding's title in the ledger and staging it *without* re-rendering — exactly
the mistake the gate exists to catch — makes `git diff --exit-code --stat` exit
1 with a one-line stat, and `.githooks/pre-commit` fail with `FINDINGS.md is
stale`. Restoring the ledger and re-rendering returns both to exit 0, and `git
status --porcelain` is clean afterwards. Severity validation both ways: setting
one finding to `moderate` makes `--check` print `INVALID OC-0001: bad severity
moderate` and exit 1; `git checkout` of the ledger makes it valid again. The
hook's grep pattern was exercised against five paths — the three
`.superpowers/` targets match, `.superpowers/sdd/notes.md` and
`scripts/check-doc-counts.mjs` do not. `node scripts/run.mjs --list` resolves
`check:docs` to three steps rather than one; `npm run check:docs` and
`npm run check:hygiene` pass, the latter with prettier, shellcheck (the new hook
block) and actionlint (the new CI step) all running for real.

Not included: untracking `FINDINGS.md` — that is the next commit, and the order
matters. L-07 requires the drift check to exist *before* the removal, because
the check is what proves the tracked copy was current at the moment it was
deleted. No `import.meta.main` guard on the renderer: no caller imports it, and
`import.meta.main` landed in Node 24.2 against an `engines` floor of `>=24`, so
it would silently no-op on 24.0/24.1 — `scripts/check-doc-counts.mjs` documents
the workaround and stays accurate. No `existsSync` guard for a missing ledger:
the unhandled rejection already exits non-zero, so CI already rejects it and
only the message is ugly, which is not drift. The `docs-consistency` job is not
converted to `npm run check:docs`; it is deliberately `npm ci`-free with direct
`node` calls in every step, and half-converting it would be worse than being
internally consistent. No `Server/Makefile` target — the ledger is
root-scoped, and `make` is not on PATH on a stock Windows box (RL-20).

Refs RL-07, L-07

* chore: stop tracking the rendered FINDINGS.md (RL-07)

The previous commit built the drift check RL-07 asked for. This is the second
half: with the check in place proving the committed rendering was current, the
rendering itself comes out of the index.

Untracking is strictly stronger than checking. A drift check watches for a
rendering that has fallen behind its source; not tracking it removes the
possibility. `findings-ledger.json` stays the only tracked copy and remains
canonical — `CLAUDE.md` tells contributors to open a PR against it — and the
1.09 MB view of it is regenerated in 67-170 ms by a command that was already
documented.

Why the drift check still had to land first, in its own commit: it is what
proved the tracked copy was current at the moment it was deleted. Deleting a
generated file you have never verified against its source is how you discover,
later, that the source was wrong. L-07 sequences it the same way — "remove the
tracked duplicate human rendering *after* deterministic on-demand/CI rendering
and a drift check exist" — and this commit is the "after".

The gate transforms rather than disappears. `git diff --exit-code` cannot watch
an untracked file, so what remains of L-07's "CI rejects generation failure or
drift" is the generation half, plus its separate "a downloadable rendering is
reproducible" clause. CI now renders **twice and compares** — which tests both:
the render must succeed (it validates and exits 1 before writing) and it must be
a pure function of the ledger. The severity rule added in the previous commit is
what makes that second property true rather than merely true today. The
rendering is then uploaded as the `findings-ledger-rendering` artifact with
`if: always()`, so a reviewer reads it without a Node run — and can read it
precisely when the job failed.

Six coordinated edits, and the fourth is not optional:
- `.gitignore` — drop the `!` negation; the `.superpowers/*` blanket takes over.
- `.gitattributes` — drop `linguist-generated=true`, now dead.
- `.prettierignore` — drop the entry; Prettier 3 reads the root `.gitignore`.
- `scripts/check-doc-counts.mjs` — drop it from `WATCHED`. A missing watched
  file is pushed to `failures` and exits 1 by design, with a message telling you
  to fix the list. Forgetting this line reds `Docs & Ledger Consistency` and
  `npm run check` on every subsequent run.
- `CLAUDE.md` — the command stays, the "tracked artifact" framing goes.
- `.claude/skills/bughunt-run/SKILL.md` — the human gate between hunt and fix
  reads this file, so it now says to generate it first. That reader is already
  at a terminal that ran the renderer seconds earlier.

13 files, 103 insertions, 9,278 deletions. The check-doc-counts gate goes from
27 claims across 9 documents to 21 across 8; the six it loses were rendered
*from* the ledger they were checked against, so they were self-consistent by
construction and could only ever have failed on a stale rendering — which is the
thing that can no longer exist.

Verified: both directions. `git ls-files .superpowers/` returns exactly two
files; `git check-ignore -v .superpowers/FINDINGS.md` names `.gitignore:87`
while the ledger itself is not ignored (exit 1), so the blanket rule did not
overreach. Deleting the rendering outright and running
`node scripts/check-doc-counts.mjs` prints `21 claim(s) across 8 watched
document(s)` and exits **0** — the proof that the `WATCHED` line was dropped,
because leaving it would have failed here. `npm run check:docs` then regenerates
the file (1,087,051 bytes) and passes. Rendering twice and `cmp`-ing the results
reports byte-identical output. The pre-commit hook was exercised both ways with
the ledger staged: a severity of `moderate` fails with `findings-ledger.json is
invalid`, and a valid tree passes with exit 0. `npm run check:hygiene` passes
with prettier, shellcheck and actionlint all running for real.

Not included: `findings-ledger.json` is untouched by this commit — it is the
canonical copy and it stays tracked, at 1,205,085 bytes, which is *larger* than
the rendering just removed. Anyone reaching for the size argument should know
that untracking the rendering removes 47% of the pair and leaves the bigger,
less readable half; the reason to do it is that the rendering is 100% derived
and would otherwise write a fresh ~1.06 MB blob into permanent history on every
hunt, not that it is the heavy one. No history rewrite — the blobs already
committed stay where they are, per the B1 non-goal. `Server/Makefile` gains no
ledger target: root-scoped, and `make` is not on PATH on a stock Windows box.

Refs RL-07, L-07

* chore: stop tracking the prebuilt hello.wasm plugin example (RL-08)

`Server/plugin/examples/hello/hello.wasm` was 946,410 bytes of committed build
output — 84% of that directory — for a plugin subsystem that is disabled twice
over: it compiles only under `-tags wazero`, and `plugins.enabled` defaults to
`false`. Nothing verified it matched the `main.go` beside it.

The remedy the audit names is a compile-and-compare gate. It cannot be built,
and not for cost reasons: TinyGo embeds absolute host paths from the building
machine's Go SDK and module cache into its output and offers no `-trimpath`
equivalent, so two machines compiling identical source produce different bytes.
A byte-identity gate cannot pass in principle. What is left is a compile-only
check, and that needs three pinned downloads — TinyGo, a *second* Go SDK at
1.25.x because TinyGo 0.40.1 rejects the Go 1.26 this module pins, and Binaryen
129 — on every PR, to prove something weaker than advertised about a subsystem
that ships in zero release artifacts.

So the artifact goes and its provenance is written down instead. BPR-080 asks
that the example WASM be "reproducible **or** provenance-verified" — disjunctive
— and the second branch is the one that is actually reachable here.

The repository had already made this call for itself. `sandbox_wazero_test.go`
uses a 41-byte inline WASM literal, with the comment "Using a literal here
avoids dragging a binary asset into the repo." This extends that from the tests
to the example.

Done:
- `git rm --cached` the artifact; a narrow `.gitignore` entry naming the exact
  path. Deliberately **not** a blanket `*.wasm`: `Client/public/rnnoise.wasm` is
  a vendored npm artifact this repository does not build and the client fetches
  at runtime, so ignoring it would break noise suppression. The rule that
  separates them — untrack build output whose source we own and whose absence
  breaks nothing; keep vendored third-party artifacts required at runtime — is
  written into the ignore comment.
- `Server/.dockerignore` gains `plugin/examples/`. `Dockerfile` does `COPY . .`
  and the file already excluded `scripts/` and `cmd/` but not this, so a
  developer who still has the untracked artifact on disk was shipping it into
  the build context. Same omission B1-5 fixed for `cmd/`.
- The README carried two false statements, both now removed: it claimed the
  plugin is "used by `Server/plugin/plugin_test.go`" and that that test
  "exercises the manifest parser and the loader against this directory".
  Neither is true — `plugin_test.go` builds every fixture in `t.TempDir()`.
- A Provenance section: TinyGo 0.40.1 + Go 1.25.3 + Binaryen 129, why the output
  is not byte-reproducible, and why the compile gate is deferred rather than
  merely absent.
- The ABI-stability sentence L-08 requires, which existed nowhere in the
  repository: the ABI is experimental with no compatibility promise, and both
  halves of "disabled" are named with the files that prove them. Verbatim
  identical in the example README and `docs/contributing.md`.
- The TinyGo/Go/Binaryen table existed in two hand-maintained copies that had
  already drifted in wording. It now lives in the example README only;
  `docs/contributing.md` links to it, which is the pattern that page already
  used two lines above for the ABI itself.

Five files, 87 insertions, 20 deletions, plus the 946,410-byte deletion.

Verified: both directions. The inertness proof is the load-bearing one, and it
is the inverse of B1-5's remove-and-watch-it-fail, because here passing is the
point: with `hello.wasm` moved out of the tree entirely, `go build ./...`,
`go build -tags wazero ./...`, `go vet ./...`, `go test ./plugin/...`,
`go test -tags wazero -count=1 ./plugin/...` and `go test ./api/...` all pass.
`go list ./plugin/...` returns a single package with and without the tag, so
`//go:build tinygo` keeps the example out of the module's build graph. The
narrowness proof is one pair: `git check-ignore -v` matches
`Server/plugin/examples/hello/hello.wasm` at `.gitignore:59` and exits 0, and
exits 1 on `Client/public/rnnoise.wasm`, which `git ls-files` confirms is still
tracked. `git ls-files Server/plugin/examples/` now returns exactly the three
source files. `npm run check:hygiene` and `npm run check:docs` pass.

Not included: no CI compile-and-compare job, per the reasoning above — deferred
to B2, which the issue register already names as L-08's second phase. **L-08 is
not claimed closed**: its closure evidence reads "Deterministic source build
passes", and that is precisely what TinyGo cannot deliver here; the register's
B1/B2 span is what makes deferring it in-scope rather than a slip. No
`tinygo.version` pin file — `Server/sqlc.version` earns its existence through
four mechanical consumers, and nothing would read this one; the gap in
`docs/contributing.md`'s toolchain-pinning policy is closed by recording TinyGo
and Binaryen as a documented exception instead. `main.go`, `plugin.json` and the
README stay tracked — L-08 says keep the source, and this commit keeps all of
it. `.gitattributes` keeps `*.wasm binary`, which still covers the client's
vendored module. No history rewrite: the artifact's existing blobs stay where
they are, per the B1 non-goal.

Refs RL-08, L-08

* docs(plans): retire the removed graphify tooling from the B1 plan (RL-06)

RL-06 asked for a 20.41 MB tracked `graphify-out/` payload to stop being
tracked, after a portable regeneration command and a CI artifact existed.
None of that happened. Instead `a5f7d95` (#1413) deleted the tool outright,
taking all 7 tracked files with it — 20,408,656 bytes, `graph.json` at
19,463,420 — before B1-6 opened. `git ls-files` matches nothing graphify-related
today.

So the outcome RL-06 wanted holds (no large tracked payload, history intact) and
the method it prescribed was bypassed. There is nothing left to do in the
repository. What was left is a documentation problem, and a live one: this plan
is an active document, and it still told a reader to run a tool that does not
exist.

The obvious response — delete every graphify mention — is wrong twice over.
The `.gitignore` rule has to stay: the local directory reached ~208 MB with
cache and dated snapshots on the machine that ran the tool, and dropping the
rule would flood that contributor's `git status` with untracked noise. And the
"do not rewrite history to shrink graphify-out" non-goal has to stay too: the
files are gone from the tree but four `graph.json` revisions remain in the pack
(~71 MiB logical, ~3.2 MiB packed of 13.28 MiB), so the line is still operative.
It is what keeps "closed" honest rather than overclaiming.

Done — nine edits, each a dead instruction rather than a stale mention:
- **B1-2 Step 7, the worst of them.** It told a human to `unset
  GRAPHIFY_SKIP_HOOK`, run `graphify update .`, and `git commit -am` a refresh.
  The tool is gone, and `git commit -am` with nothing to commit exits non-zero
  while reading like a no-op success. Replaced with a retirement note; Step 7 is
  the last step, so nothing renumbers.
- **The "Traps carried forward" entry.** A live instruction, in a list of traps,
  aimed at exactly the multi-commit sequence this phase is. Deleted.
- B1-1 Step 1's `export GRAPHIFY_SKIP_HOOK=1` and its four-line hook rationale,
  collapsed to one sentence of history. The "close any editor, cargo, vite"
  paragraph beside it is still true and stays.
- The RL-06 verdict row, the B1-6 bullet, the flatten's "leave alone" list, the
  `post-commit` parenthetical, B1-3's exclusion list, and the non-goal line.
- `.gitignore`'s stale "delete the dir when convenient" TODO becomes a recorded
  decision citing the commit that caused it.

Verified: `git grep -i graphify` outside the dated audit and the issue register
returns exactly five hits, and every one is intended — the `.gitignore` rule and
four plan lines that are explicitly retirement or history notes ("once began",
"Retired", "closed by deletion", and the non-goal). `git grep
GRAPHIFY_SKIP_HOOK` returns one hit, the sentence recording that it used to be
required. `node scripts/check-doc-counts.mjs` still passes — this file is one of
the documents it watches — and `npx prettier --check` is clean after the
verdict-row rewrite reflowed the table.

Not included: `docs/audit-2026-08-23-repository-layout.md` keeps its RL-06 row —
dated point-in-time snapshot, and `check-doc-counts.mjs` already classifies
`docs/audit-*` as report-only. `docs/plans/repo-health-issue-register-2026-08-23.md`
keeps L-06 and the R-03 row that routes to it, and the reason is *not* that it
is dated: it is in the watched set, i.e. this repository treats it as active. It
is that no B1 phase has updated its closure column, so L-01, L-04, L-05 and
L-09 through L-13 are all closed in fact and open on paper. Changing that
convention in the phase with the least to say about it would leave the register
half-updated, which is worse than uniformly stale. That sweep belongs to `R-06`,
or to one pass at B1's end. No history rewrite, per the non-goal this commit
deliberately keeps.

Refs RL-06, L-06

* docs(plans): record B1 progress through B1-6

The header still read "B1-3 are complete; B1-4 is the next step" three merged
phases later — B1-3 (#1414), B1-4 (#1415) and B1-5 (#1417) have all landed, and
B1-6 is this branch.

B1-3 set this convention with its own `docs(plans): record B1 progress through
B1-3` commit, and then B1-4 and B1-5 both skipped it. A plan that misstates
where it is costs a reader the same confusion whether it is one phase stale or
three; three is just harder to notice, because the header looks deliberate.

Verified: `node scripts/check-doc-counts.mjs` still agrees on 21 claims across 8
watched documents — this file is one of them — and prettier reports it clean.

Refs RL-06 (the phase this records), R-08

* chore(ci): pin Docs & Ledger Consistency as a required check on dev

The previous commits gave `Docs & Ledger Consistency` a gate that can actually
fail: it now rejects a ledger that will not render, on top of the schema check
it already ran. But the job is not among `dev`'s required contexts, so it
reports and cannot block. L-07's closure evidence reads "CI **rejects**
generation failure or drift" — reporting is not rejecting, and the item is not
closed until this lands.

The script's own header already diagnosed the omission: it listed
`Docs & Ledger Consistency` under "deliberately NOT pinned" with the note that
it "looks like an oversight from the 2026-08-25 pass rather than a decision".
That entry is now wrong in the other direction, so it moves out of the
not-pinned list and into a dated note beside `Repository Hygiene`'s.

The name was read off **PR #1418's live check runs** after the job reported
`success` — not copied out of `ci.yml`. That order is B1-3's rule and it is not
pedantry: the B0 script records that three of the pinned names exist in no
workflow file at all, because CodeQL runs from GitHub default setup.

Two count claims move with it. `docs/contributing.md` said "All ten required
checks" and the HP-0 scorecard's table said **10**, both stale since B1-3 added
`Repository Hygiene` and now doubly so. B1-5 spotted the first and deferred it
to "the branch-protection item's to fix"; this is that item, and it is also the
commit that changes the number, so leaving them stale here would make this
commit the proximate cause of a documented inconsistency. The scorecard is in
`check-doc-counts.mjs`'s watched set — the repository classifies it as active,
not as a frozen snapshot — so the don't-edit-dated-docs rule does not shield it.
Its pinned block gains both names and a line recording when each was added.

NOT APPLIED YET. Running this script is `gh api -X PUT
repos/J3vb/OwnCord/branches/dev/protection`, a repository-settings write this
session cannot perform. Run `bash docs/plans/b0-dev-branch-protection.sh` after
this PR merges.

The pre-flight is clear, stated positively rather than assumed: a required check
that never reports blocks every PR forever, which is the hazard B1-3's own
NOT-APPLIED note was about. It does not apply here. `Docs & Ledger Consistency`
has existed in `dev`'s `ci.yml` since #1412, so no in-flight branch predates the
job, and it reported `success` on this PR in 11 seconds.

Verified: `bash -n` and `shellcheck` are clean. Extracting the heredoc and
parsing it with `node` reports **12** contexts including
`Docs & Ledger Consistency`, spelled exactly as the live check reports it — the
JSON is machine-checked rather than eyeballed, because a typo here is a branch
that cannot merge. `node scripts/check-doc-counts.mjs` still agrees on 21 claims
across 8 watched documents, the scorecard among them, and
`npm run check:hygiene` passes with prettier, shellcheck and actionlint all
running.

Not included: the script is not run — that is the owner's step, above. No other
context is added or removed; the four remaining "deliberately NOT pinned"
entries keep their recorded reasons, including `Admin Panel E2E`, whose
`continue-on-error: true` still makes requiring it theatre until `R-01`
graduates it.

Refs RL-07, L-07, RL-14, G-03

---------

Co-authored-by: Claude <noreply@anthropic.com>

2026-08-27 11:08:07 +02:00

20 KiB

Raw Blame History

Contributing

How to set up the development environment and contribute to OwnCord.

Development Setup

Prerequisites

Platform	Server	Client
Windows 10+ x64	✅	✅
Linux x64	✅	✅
Linux ARM64	✅	✅ (CI only)

Go 1.26+ (server)
Node.js 24+ (client) — pinned in Client/.nvmrc; engine-strict makes a wrong major a hard failure, not a warning
Rust / Cargo (Tauri client — not needed for server-only work)
Docker + Compose v2 (optional — alternative to building the server locally)

Available Commands

Root facade — one entry point

From the repository root. These orchestrate the per-stack commands below; they are a convenience, not a replacement. Nothing here needs make, and everything works the same on Windows, macOS and Linux.

Command	Description
`npm run bootstrap`	`npm ci` in all three package roots
`npm run check`	Everything CI gates on: server, client, Rust
`npm run check:server`	Server only — build variants, vet, race, deadlock, lint, generated-output drift
`npm run check:client`	Client only — typecheck, lint, format, unit + integration tests
`npm run check:rust`	Tauri backend — `cargo test --lib` and clippy
`npm run check:docs`	Fail if a watched document contradicts the ledger's finding counts, or the ledger fails to render
`npm run format`	Prettier over the client, `gofmt -w` over the server
`npm run generate`	Regenerate protocol constants and the sqlc query layer
`npm run release:preflight`	`check` plus a client production build
`node scripts/run.mjs --list`	Print the exact command every task runs, and where

Tools CI installs but you may not have — golangci-lint, sqlc — are skipped with a printed reason rather than failing the run.

Working on the server only? You never need Node. The facade prints each command it runs and the directory it runs it in; those are the commands in the next section, and using them directly is equally correct.

Server (Go)

Command	Description
`go build -o chatserver.exe -ldflags "-s -w" .`	Build server binary (Windows)
`CGO_ENABLED=0 go build -o chatserver -ldflags "-s -w" .`	Build server binary (Linux)
`go build -tags otel .`	Build with OpenTelemetry SDK (requires `go get` first — see Phase B)
`go build -tags wazero .`	Build with Wazero plugin runtime (requires `go get` first — see Phase C)
`go test ./...`	Run all server tests
`go test ./... -cover`	Run server tests with coverage
`go test -race ./...`	Run server tests with race detection

Make targets (run from Server/):

Command	Description
`make test`	Run the test suite the way CI does (`-race`, 20 min timeout)
`make test-deadlock`	Run the deadlock-detection pass CI also runs (`-tags deadlock`)
`make cover`	Per-package coverage (what CI uploads) + a function summary
`make cover-all`	Cross-package coverage — the honest number (also lists 0.0% functions)
`make sqlc-install`	Install the pinned sqlc version into `$GOBIN`
`make sqlc-generate`	Regenerate the type-safe Go query layer (`db/dbgen/`, SQLite engine)
`make sqlc-verify`	Fail if the committed `dbgen` output is stale (used by CI)
`make protocol-generate`	Regenerate the WS message-type constants (Go + TS) from `protocol/schema.json`
`make protocol-verify`	Fail if the committed protocol constants are stale (used by CI)
`make otel-up`	Start Jaeger (traces) + Prometheus (metrics) via Docker for local OTel development
`make otel-down`	Stop and remove the OTel dev containers

Client (Tauri v2)

Build & dev

Command	Description
`npm run dev`	Start Vite dev server with hot reload
`npm run build`	TypeScript check + Vite production build
`npm run tauri dev`	Launch Tauri app in dev mode
`npm run tauri build`	Build release installer (NSIS on Windows, AppImage+deb on Linux)

Tests

Command	Description
`npm test`	Run all tests (vitest)
`npm run test:unit`	Unit tests only
`npm run test:integration`	Integration tests only
`npm run test:contract`	Cross-component contract tests only
`npm run test:e2e`	Playwright E2E (mocked Tauri)
`npm run test:e2e:native`	Playwright E2E (real Tauri exe + CDP)
`npm run test:e2e:admin`	Playwright E2E (real Go server + SPA)
`npm run test:e2e:prod`	Playwright E2E (prod build)
`npm run test:e2e:ui`	Playwright UI mode
`npm run test:watch`	Vitest watch mode
`npm run test:coverage`	Coverage report
`npm run test:mutate`	Stryker mutation testing
`npm run test:mutate:dry`	Stryker dry-run (no mutations applied)
`npm run test:browser`	Vitest browser-mode tests

Type checking, linting & formatting

Command	Description
`npm run typecheck`	Full typecheck (all sources)
`npm run typecheck:build`	Typecheck build config only
`npm run lint`	oxlint + ESLint check (src/)
`npm run lint:fix`	ESLint auto-fix
`npm run lint:ox`	oxlint only (fast correctness checks)
`npm run format`	Prettier format (src/ + tests/)
`npm run format:check`	Prettier check only (no writes)
`npm run knip`	Dead code and unused export detection

Git hooks (recommended)

Committed hooks in .githooks/ catch the most common CI failures locally. Enable once per clone (from the repo root):

npm run hooks:install    # = git config core.hooksPath .githooks

Hook	What it runs
`pre-commit`	gofmt + `go vet` (when Go files staged), oxlint + prettier + `tsc --noEmit` (when client TS staged), `sqlc-verify` / `protocol-verify` (when their inputs staged)
`pre-push`	Server build in all build-tag variants, client typecheck + type-aware ESLint. Set `OWNCORD_PREPUSH_TESTS=1` to also run `go test -race ./...`

Bypass with --no-verify or OWNCORD_SKIP_HOOKS=1 when needed — CI still enforces everything.

Neither hook needs make, and neither needs Node for the Go checks.

core.hooksPath is exclusive. Once set, Git resolves every hook against .githooks/ and never looks in .git/hooks/ again. .githooks/ holds only pre-commit and pre-push, so hooks:install silently disables any other hook you installed there (post-commit, post-checkout, ...). Nothing warns you. Put it under .githooks/ instead (untracked, so it stays yours), or skip hooks:install and use npm run check before pushing.

Plugin Development

Plugins are WASM modules loaded at runtime when the server is built with -tags wazero.

The plugin ABI is experimental and carries no compatibility promise. The subsystem is disabled twice over — it compiles only under -tags wazero (Server/plugin/sandbox_default.go), and plugins.enabled defaults to false (Server/config/config.go) — and the five exported functions may change or be removed in any release without a deprecation period.

See Server/plugin/examples/hello/README.md for the ABI, the build command, and the pinned TinyGo/Go/Binaryen versions. That file is the single source of truth for the plugin toolchain — this page used to carry a second copy of the version table, and the two had already drifted apart in wording.

The example's .wasm is not checked in: TinyGo embeds absolute host paths from the building machine and offers no -trimpath, so its output is not byte-reproducible and no CI job can verify it. Build it locally from the source beside it.

Branch and PR model

This section is the single source of truth for the branch model. Everywhere else -- the root README.md, CLAUDE.md, the PR template -- summarises it and links here rather than restating it.

dev -- the integration branch. All contributions target dev.
main -- releases only. dev is merged to main for a release, and release tags are cut from main.

dev is protected and PR-only: direct pushes are rejected, ten status checks are required, required_approving_review_count is 0, and the rule is enforced on admins. So a PR is self-mergeable once CI is green, but no commit reaches dev without CI having run on it. Settings and rationale live in docs/plans/b0-dev-branch-protection.sh.

Two consequences worth knowing before you open a PR:

The Docker and Tauri Full Build jobs are gated on main and report as skipped on a PR into dev. That is expected, not a failure.
Squash merge, and a conventional commit subject on the squashed commit.

Branch Naming

feature/<name> -- new features
fix/<name> -- bug fixes
docs/<name> -- documentation changes

Commit Format

Use conventional commits:

feat: add thread support to channels
fix: prevent duplicate WebSocket connections
refactor: extract permission checks into middleware
docs: update quick-start guide
test: add integration tests for invite flow
chore: bump Go dependencies
perf: cache role permissions in memory
ci: add lint step to GitHub Actions

For anything non-trivial the body carries the reasoning, not a restatement of the diff: what was wrong, why the obvious fix is wrong, what was done, concrete numbers, and a Verified: paragraph proving both directions — that the defect was present before and is absent after.

End with an explicit Not included: line naming adjacent scope you deliberately left out, and why. A written deferral is a deliverable: it is what separates considered-and-declined from silently-missed, and it means adjacent work you spotted mid-change does not have to become either scope creep or a blocking question. Put it in the commit that noticed it.

Pull Request Process

See Branch and PR model above for what to branch from and target.

Branch from dev
Open the PR against dev
All twelve required checks must pass -- dev is protected, so a red PR cannot merge
Request code review
Squash merge, conventional commit subject

Testing

The client suite enforces 70% coverage thresholds in vitest.config.ts; the Go suite has deliberately no floor (T-2026-07-25-19) — use make cover-all to see the honest cross-package number. Follow a test-driven workflow and never lower a threshold to make a change fit.

Tiers

Tier	Command	CI job	Blocking
`Client/tests/unit`	`npm run test:unit`	Client Unit Tests	yes
`Client/tests/integration`	`npm run test:integration`	Client Unit Tests	yes
`Client/tests/contract`	`npm run test:contract`	Client Unit Tests	yes
`Client/tests/browser`	`npm run test:browser`	—	no
`Client/tests/e2e`	`npm run test:e2e`	Client E2E (Playwright)	yes
`Client/tests/e2e` @parity	—	Client E2E (parity subset, blocking)	yes
`Client/tests/e2e/native`	`npm run test:e2e:native`	—	no
`Client/tests/e2e/admin`	`npm run test:e2e:admin`	Admin Panel E2E (real server, non-blocking)	no
`Server/*/_test.go`	`make test`	Server Build & Test	yes
`Client/src-tauri`	`cargo test --lib`	Rust Unit Tests	yes

npm test — not npm run test:unit — is what CI runs and what npm run check:client invokes, so it is the command that covers tests/contract.

What belongs in `tests/contract`

A test is a contract test when its assertions read, import or execute an artifact owned by a different top-level component (Server/, Client/, root protocol/) than the one its runner lives in. A comment referencing the other side does not count.

Placement follows capability, not ownership. A contract test lives in the tier whose runtime can execute or parse the artifact. If the owning component can execute it, it stays in that component's own suite — Server/updater/tauri_key_contract_test.go reads Client/src-tauri/tauri.conf.json and stays in Go, because Go parses JSON fine and the assertion is about a server constant.
Ownership is declared in the name, never in the directory. The file name and the top-level describe/Test name must name the owned artifact's path.
A contract test may only live in a blocking tier. A non-blocking job is not coverage. Admin Panel E2E is continue-on-error: true (.github/workflows/ci.yml), so it is ineligible however well it fits topically — until it graduates.
Client/ is one component: its TypeScript frontend and its thin Rust backend in src-tauri/ are the same side of the boundary, so a tests/unit test that reads src-tauri/tauri.conf.json is an ordinary unit test. The same goes for a Go test reading its own package's embedded assets (Server/admin/perm_grid_test.go).

E2E is runtime coupling rather than artifact coupling; it stays in tests/e2e.

If a tier ever gains a runner of its own, model its anti-vacuity guard on Server/invariants/invariants_test.go — it fails loudly when a configured scope resolves to nothing, rather than passing on an empty set.

Code Style

TypeScript: See Client Architecture
Go: gofmt + golangci-lint, standard library preferred
Rust: cargo fmt + cargo clippy, minimal code (native APIs only)

Dependency Policy

The policy behind what the lockfiles already enforce (decided 2026-08-05, closing audit findings 2026-04-07 #8 / DC-11):

Lockfiles are authoritative. package-lock.json, go.sum and Cargo.lock pin every transitive dependency; CI installs only from them (npm ci, module/registry verification — never a bare npm install in CI or hooks). package.json keeps ordinary caret ranges: exact-pinning it would duplicate what the lockfile does while making every security patch a manual edit.
Upgrades arrive as reviewed PRs, not ambient drift. Dependabot runs weekly per ecosystem (.github/dependabot.yml) with semver-major updates ignored across the board — majors are adopted deliberately, by a human, reading the changelog. Peer-coupled groups (vitest/@vitest/*, @stryker-mutator/*) update as one PR so exact peer pins cannot wedge.
Security gates run on every PR: npm audit --omit=dev --audit-level=high (shipped deps only — dev-tooling advisories are triaged in the workflow comment instead of blocking on unfixable pins), govulncheck for Go, cargo audit for Rust, and knip refuses unused client dependencies outright.
Version skew is pinned at the toolchain level too: Client/.nvmrc, every actions/setup-node in CI, and an engines block in all three package.json files say Node 24 — with engine-strict=true in each package's .npmrc, so a wrong major fails the install instead of warning. Server/sqlc.version pins sqlc, Go pins via go.mod (GOTOOLCHAIN=auto), and GitHub Actions are SHA-pinned with Dependabot bumping the pins. The one deliberate exception is the plugin toolchain: TinyGo and Binaryen are documented rather than file-pinned, because no gate installs them and nothing would read the pin — the example plugin's README is their single source of truth.
Three package roots, not an npm workspace — measured 2026-08-26 (npm 11.17, Node 26), not decided on principle. Making /, /Client and /tools/mcp-introspect npm workspaces buys one 298 KB lockfile instead of three (17 KB / 253 KB / 42 KB) and dedupes 614 resolved packages to 582 — 32 packages, 5.2%. Client install time is unchanged: 5642 ms against 5667 ms. The things you would expect to break do not: npm ci inside Client/ still exits 0, npm run <script> still resolves the hoisted binaries (npm prepends every ancestor node_modules/.bin to PATH), and engine-strict still fails the install on a wrong Node major. The costs that are real:
- Ten CI steps key on cache-dependency-path: Client/package-lock.json — six in ci.yml, four in the tag-only, CI-ungated release.yml. That file stops existing, and four of the ten have no gate that would catch it.
- Repository Hygiene installs root-only on purpose (prettier is all it needs). Under workspaces that grows 970 ms → 6172 ms and 39 → 318 packages, unless every call site gains --workspaces=false — the mitigation works (1112 ms, 38 packages) but has to be remembered forever.
- One lockfile puts all three npm Dependabot groups back into the same file. They rewrite three disjoint files today; undoing that reinstates the merge-then-rebase-then-re-run-CI storm the grouping comment at the top of .github/dependabot.yml exists to prevent.
Thirty-two deduped packages does not pay for that. The roots stay separate, npm run bootstrap installs all three, and Dependabot covers all three.

20 KiB Raw Blame History