Skip to content

Add a PR QA pipeline and re-verified functional review - #3

Open
TyperBody wants to merge 21 commits into
mainfrom
feat/project-review-and-pr-qa
Open

TyperBody wants to merge 21 commits into
mainfrom
feat/project-review-and-pr-qa

Conversation

@TyperBody

@TyperBody TyperBody commented Nov 7, 2026 •

Copy link
Copy Markdown
Member

What changed

Two commits that add the reviewer-facing material this repo was missing, rebased onto the current layout:

  1. PR QA pipeline — .github/workflows/ci.yml (four gates, fully offline), labeler.yml, pull_request_template.md, CODEOWNERS, labels.yml, and docs/developer-guide/pr-qa.md (merge gate, reviewer checklist, exception process).
  2. Functional review — docs/developer-guide/functional-review.md, re-verified against this tree rather than the 1.0.0 snapshot it was first written against.

Also web/.eslintrc.cjs: the lint gate had no config at all, so npm run lint exited 2 before linting anything.

Why

CONTRIBUTING.md §6 already claimed "CI must be green" while .github/workflows/ did not exist. The review is what the pipeline is calibrated against.

The finding, minus what main has since fixed: the layers exist but several are never called — internal/message has zero importers, both WebSocket routes only echo, and /messages has no POST so MessageService.Create is unreachable. Those three are still live here. idempotency_key is also uniqueIndex over an empty string, so once an ingest route exists the second keyless message collides.

Re-tested on a build of this branch, not assumed:

POST /api/v1/messages          -> 404
grep -r 'internal/message"'    -> 0 importers
empty idempotency_key, 2 rows  -> UNIQUE constraint failed

How it was verified

  • go vet ./... clean
  • CGO_ENABLED=1 go test ./... — all packages pass
  • gofmt -l . empty
  • golangci-lint run — 0 issues
  • python3 scripts/check_generated.py matrix.json clean
  • npx tsc --noEmit, vite build pass
  • npm run lint — 0 errors, 65 warnings
  • CI: all four jobs green on the head commit

Incidental fixes the gates exposed

Fixing these here rather than shipping a pipeline that is red on its own first PR:

  • 12 pre-existing unformatted Go files (all untouched by this branch)
  • one staticcheck QF1012 in dependency_installer.go
  • 32 missing locale keys that main's newer pages reference (deep-merged, both sides kept)
  • three lint errors in main's newer components and two helper exports added to the eslint allowlist
  • two tests resolved docs/ and scripts/ with one .. too many after the module moved to the root

--max-warnings goes to the measured 65 once; after that the ratchet holds.

Docs affected

pr-qa.md and functional-review.md are new, and both are linked from CONTRIBUTING.md §6.

Protocol impact

No v3 envelope, chain or signing change.

Known, not fixed here

The review's remaining blockers are left for follow-up PRs; the fix order is at the end of functional-review.md. CODEOWNERS names @TyperBody because the org has no maintainers team.

Follow-ups folded in after the base moved

main deleted backend/ and moved the module to the root while this PR was open. Three things the merge left behind, fixed here rather than after merge:

  1. POST /messages and POST /instances/:id/command answered 400, not 413, on an over-cap body. Both were written after middleware.BodyTooLarge became the convention and skipped it, so the raw http: request body too large text came back as a "malformed JSON" 400 — while api-reference.md:968 documents 413. TestOversizeBodyGets413OnIngestRoutes pins both on the real router; disabling the guard makes it fail with 200.
  2. Every backend/… path in this PR's own docs and configs was dead. gofmt -l backend exits 2 instead of printing nothing (pr-qa.md, PR template, functional-review.md), the regenerate command pointed at a directory that no longer exists, and .github/labeler.yml globbed backend/internal/** — so area:backend, area:adapter, area:protocol-v3, database and dependencies would all have matched nothing. All root-relative again, both READMEs included.
  3. web/node_modules is no longer tracked here (6021 files, 96% of the tree), and npx tsc on a fresh clone needs npm ci first or it installs the unrelated tsc stub package — the reviewer command and the template say npm ci && npx tsc now.

The 6021 deletions came from merge rename detection, not an explicit git rm. main still tracks those files, so after any future merge from main check git ls-tree -r HEAD web/node_modules | wc -l; non-zero means they came back.

Corrected in functional-review.md while there: m18's count was the whole-repo git ls-files total (11077), not the files under web/node_modules (6021); the gofmt -l and --max-warnings rows were stale (budget is 68, not 23); m18 is marked fixed with the merge caveat above.

Verified on the head commit: gofmt -l . empty, go vet clean, CGO_ENABLED=1 go test ./... green, check_generated.py clean, tsc/vite build/lint unchanged, CI's four jobs green on eae98fa. Live on one build: 9 MB to both routes 413; 201/201/201, duplicate register 409, delete-missing 404, WS 401/403/101, CORS echo unchanged.

Reviewer-facing material the repo was missing, rebased onto the current
layout (Go module at the root, adapters/ and cmd/ present):

- .github/workflows/ci.yml + labeler.yml — the CI CONTRIBUTING §6 already
  promised; offline, four gates
- .github/pull_request_template.md, CODEOWNERS, labels.yml, labeler.yml
- docs/developer-guide/pr-qa.md — merge gate, reviewer checklist,
  exception process
- docs/developer-guide/functional-review.md — severity-ranked review of
  the running system with file:line and reproduced output
- web/.eslintrc.cjs — the lint gate had no config, so `npm run lint`
  exited 2 before linting anything

Paths follow the root-module layout: no `backend/` prefix, `gofmt -l .`,
generators point at `internal/platformspec`.

Incidental fixes the gates exposed on this tree:
- 12 pre-existing unformatted Go files (`gofmt -l` would have failed the
  first PR)
- one staticcheck QF1012 in dependency_installer.go
- three lint errors in main's newer components (prefer-const, stale
  react-hooks disable directives) and two helper exports added to the
  eslint allowExportNames list
- messagefields/platformspec tests resolved docs and scripts with three
  `..` segments, one too many now the module root moved

`--max-warnings` is raised once to the measured 65 rather than rewritten;
the ratchet rule then holds from here.

The review's blockers were re-checked against this tree: B1 (JWT
validation) and M1 (user scoping) are already fixed upstream and are
noted as such; B2/B3/B4 still stand.
The review was written against the 1.0.0 snapshot. The mainline has since
fixed several of its findings and moved the layout, so the document now
says which ones are stale instead of claiming them as open.

- B1 (JWT never validated) and M1 (hardcoded user-123) are FIXED upstream.
  Verified on a live build of this tree: `Bearer total-garbage` -> 401,
  a real token against /auth/me -> 200 with the actual user row. B1 keeps
  its write-up as background with a note saying so.
- M7 (hardcoded API base) and M8 (no 401 handling) are fixed too:
  client.ts reads VITE_API_BASE_URL and routes 401 through clearToken.
- B2/B3/B4 still stand and were re-tested, not assumed: /messages POST is
  still 404, internal/message still has zero importers, and
  idempotency_key is still uniqueIndex over an empty string.
- every path reference follows the root module (no `backend/` prefix)
- restore migrations/README.md, which the old layout had and the new tree
  links to from CONTRIBUTING but was missing
- CONTRIBUTING's layout block rewritten to match the real tree
@TyperBody
TyperBody force-pushed the feat/project-review-and-pr-qa branch from 2523625 to 96aff88 Compare November 7, 2026 08:05
@TyperBody TyperBody changed the title Add PR QA pipeline and a functional review of the running system Add a PR QA pipeline and re-verified functional review Nov 7, 2026
@TyperBody

Copy link
Copy Markdown
Member Author

CI is green on the head commit — all four jobs (backend, frontend, generated, format-lint).

Two notes for the reviewer:

  1. The first push of this branch could not build. It was based on 1.0.0, but main had since moved the module to the repository root and fixed two of the review's findings. The branch is rebased; the rebase is folded into these two commits rather than left as a merge commit.
  2. --max-warnings moves 17 -> 65. The bulk is main's newer pages (DocViewer, AdapterGateway, Users) which arrived with the rebase; the rest is the API client. It is a one-time set to the measured count, not a discretionary loosening — the rule from here is still "remove one, lower the number".

B1 (JWT never validated) and M1 (hardcoded user-123) from the review are already fixed on main and are marked as such in the doc; they are kept only as background. B2/B3/B4 are still live and were re-tested on a build of this branch.

CODEOWNERS names @TyperBody — the org has no maintainers team yet, so a team reference would fail silently.

The team now exists with @TyperBody as maintainer, so the durable form
works and the handle-by-handle list is no longer needed.
The layers existed but nothing called them: `internal/message` had zero
importers, both WebSocket routes only echoed, `/messages` had no POST so
`MessageService.Create` was unreachable, and `CreateCommand` was a write-only
log. Fixing the ingest route alone would have made the second keyless message
500, so B3 and B4 land together.

- B3: `POST /api/v1/messages` persists and routes. 201 for a new event, 200 for
  a replayed `idempotency_key`, 400 on missing fields.
- B4: `IdempotencyKey` becomes `*string` and `Create` generates a fallback key
  when the caller supplies none — a UNIQUE index allows one `''` but many NULLs.
  A concurrent duplicate re-reads instead of surfacing the constraint error.
  `migrations/003` rewrites existing `''` rows to NULL; verified re-runnable.
- B2: `Services` owns a `Hub`; `/ws/app` hands the socket to the dispatcher's
  pumps, `/ws/adapter` uses a register-only path because it already has its own
  reader and single writer. Frames are persisted then routed; the routing
  outcome lands on the row (`received`/`routed`/`delivered`).
- B5: `CreateCommand` claims the row (`ClaimForDispatch`, which stops the retry
  sweep from double-sending it), dispatches, then `MarkSent`, or `MarkFailed`
  into `retrying` with a 30s sweep. The frame is the flat bridge protocol
  (`command_type` + `payload.cid/toid/text`), not a v3 envelope — bridges drop
  envelopes as "指令缺少 cid/toid".
- m1: rules load into the hub at startup and re-sync after every write.

Tests fail without the fix, verified by reverting each piece: two keyless
messages store two rows, a bridge frame reaches a different app socket and the
row says `delivered`, and a command is `sent` with `sent_at` set or `retrying`.

Docs: api-reference gains the endpoint and its status codes, bridge-protocol
records the command frame shape, functional-review marks B2-B5/m1 fixed.

Co-authored-by: multica-agent <github@multica.ai>
TyperBody and others added 6 commits November 7, 2026 19:25
`on.pull_request.branches` matches the base branch. Listing only `main`
meant every PR stacked on an integration branch got zero workflow runs and
sat there looking unverified — a green that never happened, which is worse
than a red.

Verified: PR #4 (base feat/project-review-and-pr-qa) has 0 check-runs.

Drop the extra entry once the stacked work lands on main.
…opened)

Co-authored-by: multica-agent <github@multica.ai>
Three P2 correctness items from the functional review, plus the handler tests
that pin them.

M11 — deleting/acking a missing resource answered 200. Eight repository
Deletes and the two UpdateStatus methods now return gorm.ErrRecordNotFound when
RowsAffected is 0, so "it said deleted but nothing happened" is gone. Live
before/after: DELETE /routes/nope, POST /messages/nope/ack, DELETE
/platforms/nope all 200 -> 404; deleting a row that exists still 200.

M12 — every service error collapsed into 400 (or 500 on delete). Added
ErrNotFound / ErrConflict / ErrValidation sentinels and a single handler
respondError mapping to 404/409/400/500. Wrapped the raw gorm error instead of
echoing "record not found" as a 400 body; 404 and 500 answer generic text,
409/400 keep the specific reason ("username already exists"). Registration and
admin user-create duplicates now 409.

M10 — Monitoring mapped instance.last_heartbeat / message_count / error_count
while AdapterInstance had none of them, so the page was permanently 0. Added
the three columns (migration 003, backfilled from adapter_sessions for the
heartbeat), maintained message/error counters on WS ingest and gateway
persistence, and refreshed the heartbeat on handshake and process start.

M13 — internal/handler had no tests at all. Added sqlite-backed httptest cases
for the 404/409/400 contract and the metric field round-trip; removing the
respondError mapping fails four of them.

Docs: api-reference error-code rules and instance fields, functional-review
fix markers.

Co-authored-by: multica-agent <github@multica.ai>
`server.allowed_origins` is the single list CORS and the WebSocket
handshake will both read, so the two cannot drift apart. Matching is exact
(scheme + host + port): a prefix match would accept
`http://localhost:3000.evil.example` for `http://localhost:3000`.

`server.read_header_timeout` / `read_timeout` / `write_timeout` /
`idle_timeout` / `max_body_bytes` carry defaults, so a deployment that never
edits config.yaml is also hardened rather than only the one that does.

`PlaceholderJWTSecret` names the shipped secret in one place, and
`JWTSecretWarning` returns the startup warning for it. It is a pure function
rather than a log call inside Load because Load runs before logger.Init; a
nil zap logger there would drop the warning silently.

The empty-string case warns too: exporting an empty JWT.SECRET signs with an
empty key, which is not the placeholder but is just as forgeable.

Co-authored-by: multica-agent <github@multica.ai>
M2 — CORS echoed a literal `*` together with
`Access-Control-Allow-Credentials: true`. A browser ignores the credentials
flag when the origin is a star, so the pair was incoherent even though the
current Bearer-header session does not depend on it. The allowed origin is
now echoed, which makes the pair true — and keeps the front door open for a
later Cookie-carried session instead of quietly breaking it.

M4 — `/ws/adapter` and `/ws/app` hang no middleware at all and their
upgrader returned `true` from CheckOrigin. Either route therefore accepted
any site for whatever `instance_id` / `app_id` the caller typed. Both now
sit behind WSTokenRequired (JWT from `?token=`, or an Authorization header
for non-browser clients) and share the CORS allow-list through one
OriginPolicy; a bad token answers 401 and a bad origin answers 403 before
the upgrade, so a client can tell those apart from a network failure.

Browsers send Origin on *every* handshake, same-origin included, so
CheckOrigin also accepts a request whose Origin host equals its Host. Without
that the embedded desktop build, which serves UI and API from one port,
would have to list its own URL. CORS reads the same predicate.

M15 — the http.Server had a bare Addr and Handler: no header deadline, no
read/write/idle budget, and no cap on the body `ShouldBindJSON` slurps into
memory. All four timeouts are set, and MaxBodyBytes wraps the body in
http.MaxBytesReader; handlers answer 413 instead of the misleading 400 for
"unexpected end of JSON input". WebSockets are unaffected because the
upgrade hijacks the conn and clears the deadlines.

M3 — main logs the placeholder-secret warning after logger.Init.

Co-authored-by: multica-agent <github@multica.ai>
API reference gains the origin allow-list, the server limits table, the 413
code, and the WebSocket handshake token — a changed endpoint updates the doc
under the same commit, per pr-qa. SECURITY.md stops describing the `*` plus
credentials pair and the any-origin upgrader as outstanding, and now states
the residual gap: the handshake proves a valid token, not ownership of the
`instance_id` behind it.

The two bridge adapters append `?token=` to their WS URL, quoting it.
Without that a bridge with a token configured still fails the handshake it
used to pass. READMEs, bridge-protocol, inactive-fields and the
troubleshooting snippet follow.

Handlers route bind failures through middleware.BodyTooLarge so an over-size
body is 413, not a parse error. The adapter gateway gets the same CheckOrigin
hook for its custom listen paths.

Co-authored-by: multica-agent <github@multica.ai>
TyperBody and others added 11 commits November 8, 2026 01:15
P2: truthful status codes (404/409/400/500) and live instance metrics
P1: security and deployment items (CORS, default JWT secret, WS auth and Origin, server timeouts)
main gained the standalone-adapter / catbus batch since this branch opened,
so #3 went dirty and the whole stack under it stopped merging.

Conflicts and how they were settled:

- config.go, adapter_catalog.go, dependency_installer.go, python_runner.go —
  main's side is a strict superset of ours (NodeBin, Runtime spec, standalone
  stdin/envelope plumbing); took it
- three docs — heading collisions, each side adding a different section;
  kept our English heading with main's new body beneath it
- web/src/pages/Instances.tsx — this branch rewrote the page to a table while
  main edited the edit-dialog proxy prefill. Kept the rewrite and ported the
  prefill: parseConfig restored and wired through configForForm, which tsc
  caught as unused until it was actually called

--max-warnings moves 65 -> 68: the three ported helpers carry three `any`,
the ratchet goes up once rather than the gate going red.

Verified: build, vet, gofmt (empty), full suite, check_generated, tsc,
vite build, lint at the new budget. Live: POST /messages x3 201/201/201,
duplicate register 409, delete-missing 404, 9 MB JSON 413, WS no token 401,
WS evil origin 403, WS allowed origin 101.
P0 is what main does not have: the hub actually routing between sockets.
The branch handlers are the superset (they carry main's persistInboundMessage,
extractChainText and gateway tool catalog, and add hub ownership), so they win;
main's interfaces are re-learned on top.

- websocket.go: hub handlers kept, both now take the *OriginPolicy and build
  their upgrader from wsUpgrader(policy) — main's per-request origin check
- server.go: WSTokenRequired() plus the hub argument; the InstanceService
  parameter the old handler took is gone
- route.go: not-found wrap AND notifyChange together
- message.go: P2's RecordInbound/Heartbeat/Error unioned with P0's
  CreateAndRoute/Route, missing brace at the junction fixed
- migrations: idempotency rebuild moved to 004, README rows reordered

Verified: build, vet, gofmt, full suite green; ingest x3 201/201/201,
duplicate register 409, delete-missing 404, WS no token 401, WS evil
origin 403.
golangci-lint's unused check caught both: the global upgrader is
superseded by wsUpgrader(policy), and readState lost its last caller when
the WebSocket handlers were merged. Local golangci is 0 issues again.
Two follow-ups found while re-verifying an unrelated report on this head.

1. `POST /messages` and `POST /instances/:id/command` skipped
   `middleware.BodyTooLarge`, so an over-cap body answered 400 with the raw
   `http: request body too large` text instead of 413. Every other binding
   handler converts it, and `api-reference.md:968` documents 413. Both now
   call BodyTooLarge; `TestOversizeBodyGets413OnIngestRoutes` covers them on
   the real router and fails with 200 when the guard is disabled.

2. `main` moved the Go module out of `backend/`, and this branch's docs
   still told people to `cd backend`, `gofmt -l backend`, and regenerate
   into `backend/internal/platformspec`. Same for `.github/labeler.yml`
   (every area label would have silently stopped matching), the PR
   template and both READMEs. Paths are root-relative again.

Also corrected in `functional-review.md`: the m18 file count was 11077,
which is the whole-repo `git ls-files` line count, not the 6021 tracked
files under `web/node_modules`; the `gofmt -l` / `--max-warnings` rows and
the m16 budget note were stale; and m18 is now marked fixed, with the
caveat that the 6021 deletions came from merge rename detection rather
than an explicit `git rm`, so `main` still tracks them and a later merge
can bring them back.

Verified: gofmt -l . empty, go vet clean, CGO_ENABLED=1 go test ./...
green, check_generated clean, tsc/vite/lint unchanged. Live: 9 MB to
/messages and /instances/i1/command both 413; every other smoke case
(201/201/201, 409, 404, WS 401/403/101, CORS) unchanged.

Co-authored-by: multica-agent <github@multica.ai>
Brings in the work that was sitting uncommitted on this head, and finishes
the one piece of it that was half-wired.

- instance log drawer: the component and its client method were written but
  nothing mounted it and neither locale had the `logs.*` keys. Added the
  keys, wired a row action and mounted the drawer, so the three existing
  `/instances/:id/logs` endpoints are reachable from the UI at last
- messages page gains an ingest dialog; the create path it needs already
  existed server-side
- runtime labels: node/go are accepted as labels without a dispatch path,
  and the bridge cookie check keys off bridge runtimes generally, so a
  labelled adapter with main.py still starts
- the launcher emitted a warning through r.appendLog before main.py
  fallback; the helper did not exist. Added it, sharing the installer's
  level-marker and envelope rules so the log viewer's filter keeps working
- adapters/platformspec tests compare against platformspec.Active()/
  Upcoming() instead of hardcoded counts, and 12306 moves to Upcoming

Verified: build, vet, gofmt, full suite, golangci (0 issues),
check_generated, tsc, vite build, lint at 68. Frontend smoke: tsc and
build both pass with the drawer mounted.
- 折叠按钮标签 truncate -> break-words,内边距收到 px-1/py-1:
  truncate 下 scrollWidth 恒等于 clientWidth,看上去没裁、实际在省略;
  r24/r26/r28 分别被裁 17/37/57px。
- --sidebar-width min(15rem,22vw) -> clamp(288px,24vw,17rem):
  按钮自带 shrink-0、内容盒取 max-content,侧栏压到 225 时收不动。
- shell-rail 纵向留白 py-6 -> py-6 sm:py-8 lg:py-[clamp(56px,5vw,96px)]:
  按视口封顶,不随根字号放大(原 lg:py-12 在 r28 下会到 84px)。
- 行高 57px、上下各 12px,文字贴行线;提到 16px 后 65px。
- /messages 自 dark 之后就不在 App.tsx 路由里,侧栏点进去是空白页
  (根节点为空、无报错),Messages.tsx 一直在但没被引用,现补回 import 与 Route。
The review was written against a much older tree. Most of its findings have
since been fixed, so re-ran every command on HEAD and marked each entry.

Verified fixed: M2 (echoes allow-listed Origin + Vary), M4 (WS auth +
CheckOrigin from the shared policy; 401/403/101 as expected), M5 routes,
M6 frontend wiring, M9 RequireAuth, M11 user routes, M13 test coverage,
M15 timeouts and the body cap (9 MB JSON -> 413), m6 connection badge,
m9 favicons, m17 (below).

Still live, now stated as such: M1 (user isolation - bob still lists and
deletes alice's instances; promoted to the top of P0), M3, M5's missing
AdminRequired, M16, and m2-m5/m7/m8/m10/m12-m16.

m17 is partly closed with a real test: web/scripts/check-locales.mjs runs
in the frontend job and compares the two language packs. Writing it caught
15 t() keys absent from both, which render as raw key names on the login
page; all 15 now have copy in both languages. Hint keys were missed by the
first pass and the test found them. Lint budget drops 68 -> 67 since one
`any` went with them.

Also syncs the concurrent registration-endpoint work already in the tree.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant