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

Files

T

Claude 63b522494c refactor: move the protocol schema to protocol/schema.json (RL-09)

The WebSocket message-type schema is the one artifact in this repository that
neither component owns: `Server/ws/message_types.go` and
`Client/src/lib/protocolTypes.ts` are both generated from it, and neither may
be hand-edited. It nonetheless lived at `docs/protocol-schema.json` — filed
under the directory for prose, whose own README calls it "Reference" material
— and its generator lived at `Server/scripts/genprotocol/`, i.e. inside one of
the two consumers. Ownership was legible from neither location.

The obvious fix — move the generator to the repository root alongside the
schema, so the whole tool is at the cross-component boundary — is wrong here.
The generator is a Go `package main`, and Go modules are directory-rooted:
`Server/go.mod` roots at `Server/`, so a root-level Go program needs a second
module or a `go.work`. That second module would sit outside every path filter
this repository already has — `golangci-lint` runs with `working-directory:
Server/` (ci.yml), `go vet ./...` runs from `Server/` (scripts/run.mjs,
.githooks/pre-commit), `.githooks/pre-commit` selects Go files with
`^Server/.*\.go$`, `.githooks/pre-push` sets `server_changed` on `^Server/`,
setup-go caches on `Server/go.sum`, and dependabot has one gomod block for
`/Server`. Six gates would silently stop covering the generator, each failing
open. The schema is data and moves freely; the generator is Go and stays where
the Go toolchain already runs.

Done instead:
- `docs/protocol-schema.json` -> `protocol/schema.json`. A new top-level
  `protocol/` is the cross-component boundary, with a `README.md` naming the
  two generated consumers, the one command, and the four gates.
- `Server/scripts/genprotocol/` -> `Server/cmd/genprotocol/`, the module's
  conventional home for an executable. This also empties `Server/scripts/` of
  Go entry points except `seed.go`, which RL-10 moves next.
- `Server/cmd/` added to `Server/.dockerignore` and `Server/.air.toml`, which
  both already excluded `Server/scripts/`. Without this the move would have
  silently widened the Docker build context and the air watch set.

27 files, 115 insertions, 76 deletions. Two runtime path resolvers re-pointed
(`cmd/genprotocol/main.go:41` `-schema` default, `ws/protocol_contract_test.go:67`
`filepath.Join`); two git-hook grep patterns (`pre-commit:53`, `pre-push:57`);
eight generator call sites across five files (Makefile x2, scripts/run.mjs x2,
pre-commit x2, ci-check skill, bughunt-fix.js); two broken relative markdown
links (docs/README.md:47, docs/protocol.md:1497); two generated files
regenerated, header lines only, zero constants changed; two ledger prose hits
plus a `render-ledger.mjs` re-render. No new verify was written: the
regenerate-and-diff check is already enforced three times (CI `make
protocol-verify`, `.githooks/pre-commit`, `npm run check:server`) and
`ws/protocol_contract_test.go` independently checks the schema against the
constants a fourth time.

Verified: both directions, for both resolvers. With `protocol/schema.json`
removed, `go test ./ws/ -run TestProtocol` fails with `reading protocol schema
at /home/user/OwnCord/protocol/schema.json: no such file or directory` (two
tests) and `go run ./cmd/genprotocol` exits 1 with `read schema: open
../protocol/schema.json: no such file or directory`; with the file restored
both pass. So the new path is genuinely resolved, not merely spelled in a
comment. The hook patterns were exercised directly: the pre-commit pattern
matches `protocol/schema.json` and `Server/cmd/genprotocol/main.go` and no
longer matches `docs/protocol-schema.json`; the pre-push pattern matches
`protocol/schema.json`. `go run ./cmd/genprotocol` twice in a row leaves
`git diff --exit-code ws/message_types.go ../Client/src/lib/protocolTypes.ts`
clean, so the committed outputs are exactly what the generator emits.
`go build ./...` and `go vet ./...` pass; `npx prettier --check .`,
`npm run typecheck` and `npm run lint` pass; `node .superpowers/render-ledger.mjs
--check` reports 348 findings valid.

Not included: the four dated `docs/audit-*.md` files, the older
`docs/plans/*`, and `CHANGELOG.md` keep the old path — they are point-in-time
records, and `.prettierignore` and `scripts/check-doc-counts.mjs` already
treat them as deliberately unmaintained. The B1 plan itself keeps its own
wording, since it states intent rather than current state. `Server/scripts/`
is not deleted: it still holds `seed.go` (RL-10), `k6/`, `toxiproxy/` and two
shell scripts. `Server/telemetry/metrics.go:19` declares a scope for a
`Server/voice` package that does not exist — spotted here, unrelated to this
move, left for RL-13's sweep to carry forward verbatim rather than fixed
inside a relocation. No `seed:` Make target was added.

Refs RL-09, L-09

2026-08-26 19:37:11 +00:00

9.1 KiB

Raw Blame History

Documentation index

Every document in docs/ is listed here. If it is not on this page it is not current guidance.

Docs fall into four kinds, and the difference matters when you are deciding whether to trust one: guidance tells you how to do something, reference describes a contract the code actually implements, audits are dated snapshots that were true when written and were never updated, and plans record intent. Read an audit as history, not as status.

Start here

I want to…	Read
Run a server	quick-start.md
Deploy for real	deployment.md
Contribute a change	contributing.md
Understand the system	architecture/
Report a vulnerability	security.md

Guidance

Document	Covers
quick-start.md	Getting a server running with the fewest steps.
deployment.md	Production deployment on Windows and Linux.
contributing.md	Environment setup, the branch and PR model, coding standards, how to run the checks CI runs.
security.md	How to report a vulnerability, and how findings are handled in public vs private.
livekit-setup.md	Standing up the LiveKit SFU for voice and video.
port-forwarding.md	Making a server reachable from outside the LAN.
tailscale.md	Remote access without port forwarding.
mcp-introspect.md	Dev-only MCP server for introspecting a running instance.

Reference

These describe contracts the code implements. If one disagrees with the code, the code is right and the document is a bug.

Document	Covers
api.md	REST API under `/api/v1`.
protocol.md	WebSocket protocol — frames, sequencing, reconnect.
schema.md	SQLite schema and migrations.
server-configuration.md	Every server configuration option.
credential-storage.md	What the desktop client persists, and where.
../protocol/schema.json	Generated-code source of truth, at the repository root because it is owned by neither side. `Server/ws/message_types.go` and `Client/src/lib/protocolTypes.ts` are generated from it — never hand-edit either. See ../protocol/README.md.

Architecture

architecture/README.md indexes the blueprints and carries the maintenance rule: each blueprint names its source-of-truth files, and a PR touching those updates the blueprint in the same change.

system-overview.md, server.md, client.md
data-model.md, websocket.md, voice-e2ee.md
ux/ — target-state UX spec, per-view states and event→reaction maps

client-architecture.md is a redirect stub; the live document is architecture/client.md.

Audits — dated, not maintained

Point-in-time snapshots. They are not updated as the code moves, and they are deliberately left alone when paths change, so links from commit messages keep resolving. Anything here may be stale; the ledger and the plan index carry current status.

Audit	Scope
audit-2026-08-23-repository-layout.md	Repository layout and contributor experience (`RL-01`…`RL-22`).
audit-2026-08-23-repository-health.md	Full repository health.
audit-2026-08-19.md	Repo health. States "0 open findings" — untrue since; see the ledger.
audit-test-coverage-2026-08-19.md	Test audit (`T-`, a separate register from the `OC-` ledger).
audit-2026-08-04-docs-and-coverage.md	Documentation accuracy and UI/UX test coverage.
audit-2026-08-04.md	Security review.
audit-test-coverage-2026-07-25.md	Test-coverage audit.
audit-2026-07-19.md	Architecture and spec-conformance review.
audit-2026-04-07.md	First comprehensive audit.

Plans

plans/README.md indexes every plan with a recorded state — active, partially implemented, design-only, or shipped — and is the authority over a plan's own header, which can drift.

Where status actually lives

Do not read a defect count, or a "what works" claim, out of a document on this page. Status has owners:

Concern	Source of truth
Defect status	`.superpowers/findings-ledger.json` (`FINDINGS.md` is rendered from it)
Security-sensitive defects	Private GitHub Security Advisories
Phase order and gates	plans/repo-health-roadmap-2026-08-23.md
Current measured baseline	plans/b0-baseline-2026-08-25.md
Generated-code contracts	`CLAUDE.md`, "Generated code — never hand-edit"

A CI job checks that documents on this page do not contradict the ledger's counts. Adding a count to a document means adding it to that check's allow-list in scripts/check-doc-counts.mjs.

9.1 KiB Raw Blame History