Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion hub/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Hub is being rebuilt in TypeScript. Read the [root instructions](../AGENTS.md),
- [Development](docs/development.md) and [testing](docs/testing-and-operations.md) own local and CI commands.
- [Storybook](docs/storybook.md#ui-changes-and-pull-request-evidence) owns presentation coverage, cleanup, and PR screenshots.

Run Node commands from `hub/`, locally or inside the devcontainer. PostgreSQL and Prisma support configured GitHub authentication, administrator enrollment, Hub sessions, and a seeded prototype index with prototype name editing and draft registration through the API; see [authentication](docs/authentication.md). Other prototype APIs and repository-specific permissions are not built. Agree on the design before adding more product models, permissions, deployment choices, or product API routes.
Run Node commands from `hub/`, locally or inside the devcontainer. PostgreSQL and Prisma support configured GitHub authentication, administrator enrollment, Hub sessions, and a seeded prototype index with prototype metadata editing and draft registration through the API; see [authentication](docs/authentication.md). Other prototype APIs and repository-specific permissions are not built. Agree on the design before adding more product models, permissions, deployment choices, or product API routes.

Use `npm run dev:api` to run Hub with local developer sign-in; this is the default choice for trying or testing Hub. Use `npm run dev:api:live` only when the task needs real GitHub or Entra sign-in configured in `.env`. [Development](docs/development.md#start-with-the-real-api) explains both modes.

Expand Down
6 changes: 3 additions & 3 deletions hub/docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ Hub contributors are rebuilding the app on `build/hub/new` before merging it int

The team has chosen TypeScript, Express for the API, React and Vite for the frontend, and Vitest for tests. The old backend and the frontend code that connected to it have been removed rather than rewritten.

The API responds to a health check and gives signed-in members read access to the seeded repository index and prototype details, plus prototype name edits and draft registration. The frontend connects the retained pages for local exploration. Storybook remains the presentation workbench.
The API responds to a health check and gives signed-in members read access to the seeded repository index and prototype details, plus prototype metadata edits and draft registration. The frontend connects the retained pages for local exploration. Storybook remains the presentation workbench.

Contributors can use PostgreSQL and Prisma locally or in the devcontainer. The database has a provider-neutral identity transaction foundation with explicit GitHub and single-tenant Microsoft Entra sign-in adapters. A reusable deployment bootstrap secret can enroll a verified provider identity as a Hub administrator. Members can browse a seeded repository index and edit visible prototype names through the API. The app cannot yet discover real repositories, import Builds, host published previews, or support live multi-user reviews.
Contributors can use PostgreSQL and Prisma locally or in the devcontainer. The database has a provider-neutral identity transaction foundation with explicit GitHub and single-tenant Microsoft Entra sign-in adapters. A reusable deployment bootstrap secret can enroll a verified provider identity as a Hub administrator. Members can browse a seeded repository index and edit visible prototype metadata through the API. The app cannot yet discover real repositories, import Builds, host published previews, or support live multi-user reviews.

The [production runtime](deployment.md) serves the built frontend and API and runs both workers in one image. Deployment runs database and job setup separately before starting that image.

Expand All @@ -22,7 +22,7 @@ The [database guide](database.md) defines the multi-file Prisma schema and share

The [Pino integration](logging.md) writes structured application and HTTP logs to stdout. `createApp()` installs request logging before routes, so new endpoints inherit completion records and server-generated request IDs without explicit logging calls. Authentication routes install their bounded form parsing after origin and rate-limit checks. Prototype edits check the application origin before bounded JSON parsing, including case and trailing-slash aliases; other routes inherit the shared JSON parser.

The [prototype name-edit API](frontend.md#prototype-name-edits) lets signed-in members rename visible prototypes and register drafts. Hub holds session authority and prototype visibility locks through the write and detail read-back. The frontend editor remains separate work.
The [prototype metadata API](frontend.md#prototype-metadata-edits) lets signed-in members edit visible prototypes and register drafts. Hub holds session authority and prototype visibility locks through the write and detail read-back. The frontend editor remains separate work.

The [background-job foundation](background-jobs.md) uses BullMQ with PostgreSQL and separate on-demand and scheduled worker processes. Setup migrates BullMQ's own schema independently of Prisma. Product processors and schedules are not registered yet.

Expand Down
2 changes: 1 addition & 1 deletion hub/docs/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ Prefer idiomatic Prisma operations for ordinary create, read, update, and delete

Keep ordinary value and shape validation in application code. Add a database guard only for a named cross-writer, concurrency, or history invariant that every writer must preserve. Document the invariant and cover its rejection behavior.

For prototypes, one active branch has one identity per repository, including concurrent writes. Retired branches keep their history. A registered prototype must have a nonblank name and cannot be a replica branch.
For prototypes, one active branch has one identity per repository, including concurrent writes. Retired branches keep their history. A registered prototype must have a nonblank name and cannot be a replica branch. Non-null names and descriptions must not be blank, even for direct database writes. The metadata migration replaces existing blank draft names and blank descriptions with `NULL` before adding the guard. Start pages have a separate 2,048-byte database limit; the API validates their local path safety.

A Build number is positive and unique within its prototype. A known commit SHA uses 40 or 64 lowercase hexadecimal characters and is also unique within its prototype. A prototype's current Build, if set, belongs to that prototype.

Expand Down
12 changes: 8 additions & 4 deletions hub/docs/frontend.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ The dataset includes `octocat`, `mona`, additional fictional collaborators, `git

In mock mode, the neutral root reads the simulated session. Private pages load their workspace in a separate layout; public shared previews and signed-out pages do not load a private workspace. These provisional product contracts are not adapters for real authentication or authorization.

In real mode, signed-out visitors see the authentication shell without loading provisional session or workspace data. Signed-in members open the first repository or an empty workspace. Administrators can open `/settings/administrators`, `/settings/sessions`, `/settings/copilot`, and `/settings/audit?scope=hub` without loading provisional product workspace data. The sessions page reads current Hub authentication counts, requires explicit confirmation, leaves for fresh authorization through the current session provider, and keeps the signed-out completion result visible after the API ends every Hub session. Sign-in, enrollment, and sign-out forms submit natively to the configured API. Members can search the index, filter it by user, page through 24 prototypes at a time, and open prototype details. The detail API selects the latest successful Build by default; `build` pins another successful Build, and invalid or unavailable selections return 404. Every signed-in member who can see a prototype can `PATCH` its name; naming a draft registers it with that member as its first author. Later edits preserve its author and registration time. The real detail page still reports `canEdit: false` and shows no editor. Description and start-page editing, Build history, and sharing links are unavailable in real mode. Users from other providers are shown by name or login without a GitHub link. Build user metadata may be unknown for older records. Hosted previews and live review remain unavailable, and other real product routes retain explicit API failures. In mock mode, `/` keeps the product entry flow, and `/admin-enrollment` redirects to the mock `/settings/enroll` flow. See [Hub development](development.md) for seed data and access limitations.
In real mode, signed-out visitors see the authentication shell without loading provisional session or workspace data. Signed-in members open the first repository or an empty workspace. Administrators can open `/settings/administrators`, `/settings/sessions`, `/settings/copilot`, and `/settings/audit?scope=hub` without loading provisional product workspace data. The sessions page reads current Hub authentication counts, requires explicit confirmation, leaves for fresh authorization through the current session provider, and keeps the signed-out completion result visible after the API ends every Hub session. Sign-in, enrollment, and sign-out forms submit natively to the configured API. Members can search the index, filter it by user, page through 24 prototypes at a time, and open prototype details. The detail API selects the latest successful Build by default; `build` pins another successful Build, and invalid or unavailable selections return 404. Every signed-in member who can see a prototype can edit its metadata through the API; editing a draft registers it with that member as its first author. Later edits preserve its author and registration time. The real detail page still reports `canEdit: false` and shows no editor. Build history and sharing links are unavailable in real mode. Users from other providers are shown by name or login without a GitHub link. Build user metadata may be unknown for older records. Hosted previews and live review remain unavailable, and other real product routes retain explicit API failures. In mock mode, `/` keeps the product entry flow, and `/admin-enrollment` redirects to the mock `/settings/enroll` flow. See [Hub development](development.md) for seed data and access limitations.

The Build pickers on the prototype and History views list successful, failed, and running Builds with their status. The mock Build history lists all Builds. On these views, successful Builds open the prototype view with `?build=N`; failed and running Builds are plain text because Hub does not store workflow run URLs. The separate share-link picker offers only successful Builds with a preview and keeps selections on the share-links page.

Expand Down Expand Up @@ -205,11 +205,15 @@ These are frontend/mock contracts under [the application contracts](../client/ap
| `GET /api/settings/workspace`, `/api/settings/public`, `/api/settings/admin-candidates` | Settings records and synthetic page capabilities |
| `POST /api/settings/actions` | Explicitly named local actions; administrator role changes return 501 without changing state |

In real mode, Express implements `GET /api/workspace`, `GET /api/repositories/:repositoryId`, its `authors` endpoint, `GET /api/repositories/:repositoryId/prototypes/:prototypeId`, and the [prototype name-edit](#prototype-name-edits) `PATCH` endpoint. The workspace lists the viewer and non-removed repositories. The repository index returns 24 eligible prototypes per page. It accepts `q`, `author`, and `page`, and rejects malformed values. Search ignores letter case and matches the prototype name, description, branch, and author login or name. A page past the end shows the last page. Each prototype includes its current Build or, when unset, the chronologically latest Build. The detail endpoint also includes unregistered prototypes and branches that were deleted, but excludes the default branch, replicas, and the reserved installation branch. It chooses the latest successful Build or a requested successful Build number; invalid and unavailable selections return 404. Unknown Build metadata remains null. Preview URLs and screenshots remain null because Hub does not host Builds yet. The authors endpoint lists other users with eligible prototypes, 20 at a time, sorted by login. Its cursor only marks where the last page ended. The [authentication guide](authentication.md) owns the real session routes.
In real mode, Express implements `GET /api/workspace`, `GET /api/repositories/:repositoryId`, its `authors` endpoint, `GET /api/repositories/:repositoryId/prototypes/:prototypeId`, and the [prototype metadata](#prototype-metadata-edits) `PATCH` endpoint. The workspace lists the viewer and non-removed repositories. The repository index returns 24 eligible prototypes per page. It accepts `q`, `author`, and `page`, and rejects malformed values. Search ignores letter case and matches the prototype name, description, branch, and author login or name. A page past the end shows the last page. Each prototype includes its current Build or, when unset, the chronologically latest Build. The detail endpoint also includes unregistered prototypes and branches that were deleted, but excludes the default branch, replicas, and the reserved installation branch. It chooses the latest successful Build or a requested successful Build number; invalid and unavailable selections return 404. Unknown Build metadata remains null. Preview URLs and screenshots remain null because Hub does not host Builds yet. The authors endpoint lists other users with eligible prototypes, 20 at a time, sorted by login. Its cursor only marks where the last page ended. The [authentication guide](authentication.md) owns the real session routes.

### Prototype name edits
### Prototype metadata edits

Unlike the mock contract above, the real endpoint accepts a strict JSON object containing only `name`. Any signed-in member can rename a visible prototype. Naming a draft registers that same prototype and makes the member its first author. Later edits preserve its author and registration time, even when concurrent edits race. Hub checks the configured origin before parsing the bounded body, trims surrounding Unicode whitespace, and rejects blank names, names over 255 Unicode code points, NUL, and unpaired surrogate values. Invalid input returns 400, a wrong origin returns 403, and a missing or expired session returns 401. The default branch, replicas, the reserved installation branch, removed repositories, and prototypes requested under another repository return 404. A failed operation leaves the draft unchanged. A successful response includes the updated detail while preserving the prototype ID and Build relationships; `canEdit` remains false. Hub holds session authority and prototype visibility locked through the update and detail read-back. The client editor remains separate work.
Unlike the mock contract above, the real endpoint accepts a strict JSON object with at least one of `name`, `description`, and `startPage`. For example, `{"description":"New overview"}` changes only the description. Any signed-in member can edit a visible prototype. The first edit registers a draft and makes that member its first author, using its valid existing name or branch name when `name` is omitted. Later edits preserve its author and registration time, even when concurrent edits race.

Hub checks the configured origin before parsing the bounded body and trims surrounding Unicode whitespace. Names must be nonblank and at most 255 Unicode code points. Descriptions may be null or blank, which clears them, and contain at most 500 code points. Both reject NUL and unpaired surrogates. A start page may be null or blank to clear it; detail reads return `/` when it is missing or blank. Omitted fields retain their stored values. Other start pages are local paths of at most 2,048 UTF-8 bytes, including any query or fragment. Hub adds a leading slash when needed and rejects external URLs, traversal, controls, backslashes, malformed escapes, reserved `/__replica` paths, and `.replica-internal` path segments, including encoded forms. Encoded spaces and encoded percent signs remain valid.

Invalid input returns 400, a wrong origin returns 403, and a missing or expired session returns 401. The default branch, replicas, the reserved installation branch, removed repositories, and prototypes requested under another repository return 404. A failed operation leaves the draft unchanged. A successful response includes the updated detail while preserving the prototype ID and Build relationships; `canEdit` remains false. Hub holds session authority and prototype visibility locked through the update and detail read-back. The client editor remains separate work.

Real administrator management does not use the provisional settings contracts:

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
-- Add the optional start page without changing existing prototypes.
ALTER TABLE "prototypes" ADD COLUMN "start_page" VARCHAR(2048);

-- Older writers could save blank draft names and descriptions.
UPDATE "prototypes"
SET "name" = NULL
WHERE "registered_at" IS NULL AND translate(
"name",
chr(9) || chr(10) || chr(11) || chr(12) || chr(13) || chr(32) ||
chr(133) || chr(160) || chr(5760) || chr(8192) || chr(8193) || chr(8194) ||
chr(8195) || chr(8196) || chr(8197) || chr(8198) || chr(8199) ||
chr(8200) || chr(8201) || chr(8202) || chr(8232) || chr(8233) ||
chr(8239) || chr(8287) || chr(12288) || chr(65279),
''
) = '';

UPDATE "prototypes"
SET "description" = NULL
WHERE translate(
"description",
chr(9) || chr(10) || chr(11) || chr(12) || chr(13) || chr(32) ||
chr(133) || chr(160) || chr(5760) || chr(8192) || chr(8193) || chr(8194) ||
chr(8195) || chr(8196) || chr(8197) || chr(8198) || chr(8199) ||
chr(8200) || chr(8201) || chr(8202) || chr(8232) || chr(8233) ||
chr(8239) || chr(8287) || chr(12288) || chr(65279),
''
) = '';

-- Every writer must represent blank optional metadata as NULL.
ALTER TABLE "prototypes" ADD CONSTRAINT "prototypes_metadata_check"
CHECK (
("name" IS NULL OR translate(
"name",
chr(9) || chr(10) || chr(11) || chr(12) || chr(13) || chr(32) ||
chr(133) || chr(160) || chr(5760) || chr(8192) || chr(8193) || chr(8194) ||
chr(8195) || chr(8196) || chr(8197) || chr(8198) || chr(8199) ||
chr(8200) || chr(8201) || chr(8202) || chr(8232) || chr(8233) ||
chr(8239) || chr(8287) || chr(12288) || chr(65279),
''
) <> '') AND
("description" IS NULL OR translate(
"description",
chr(9) || chr(10) || chr(11) || chr(12) || chr(13) || chr(32) ||
chr(133) || chr(160) || chr(5760) || chr(8192) || chr(8193) || chr(8194) ||
chr(8195) || chr(8196) || chr(8197) || chr(8198) || chr(8199) ||
chr(8200) || chr(8201) || chr(8202) || chr(8232) || chr(8233) ||
chr(8239) || chr(8287) || chr(12288) || chr(65279),
''
) <> '')
);

-- VARCHAR counts characters, so enforce the separate UTF-8 byte limit.
ALTER TABLE "prototypes" ADD CONSTRAINT "prototypes_start_page_bytes_check"
CHECK ("start_page" IS NULL OR octet_length("start_page") <= 2048);
1 change: 1 addition & 0 deletions hub/schema/prototype.prisma
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ model Prototype {
branchName String @map("branch_name") @db.VarChar(255)
name String? @db.VarChar(255)
description String? @db.VarChar(500)
startPage String? @map("start_page") @db.VarChar(2048)
registeredAt DateTime? @map("registered_at") @db.Timestamptz(3)
branchDeletedAt DateTime? @map("branch_deleted_at") @db.Timestamptz(3)
replica Boolean @default(false)
Expand Down
Loading
Loading