Skip to content

Commit b7deaef

Browse files
nshkiCopilot
andauthored
feat(hub): add prototype Build detail metadata (#230)
## Why Build records need source and author metadata to support the planned prototype detail experience. This slice adds the persistence foundation without expanding into historical Rails imports, Build APIs, preview hosting, or live review. ## What changes Add optional commit SHA, external author identity and snapshots, Build start and finish times, and failure summaries. Database constraints keep known metadata coherent while allowing existing Builds to retain unknown values. Seed data, PostgreSQL coverage, and the database and development guides are updated to match. --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 24981734-e0da-49fc-baf7-507617a6b09f Copilot-Session: 335a01a0-881c-4159-bcf9-5f19b9b66bd4
1 parent dd2cbe1 commit b7deaef

9 files changed

Lines changed: 784 additions & 139 deletions

File tree

‎hub/docs/database.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,11 @@ Keep ordinary value and shape validation in application code. Add a database gua
7676

7777
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.
7878

79-
A Build number is positive and unique within its prototype. A prototype's current Build, if set, belongs to that prototype.
79+
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.
80+
81+
Builds retain the author's provider, issuer, and provider user ID independently of Hub user IDs. For a workflow Build, the author is the Git commit author. Those three identity values must be present together or absent together. Login, name, and avatar are snapshots and may be unavailable. When Build timestamps are present, they must match its state; older Builds may keep both timestamps unknown. A failure summary belongs only to a failed Build and is limited to 1,000 bytes.
82+
83+
Builds created before commit metadata was stored retain `NULL` for unknown values during the upgrade. A later detail API must represent missing values rather than inventing them. This migration does not import Rails records or map their integer IDs.
8084

8185
PostgreSQL `CHECK` expressions accept `NULL` unless the expression explicitly rejects it. Write nullable-branch checks so every invalid `NULL` combination evaluates to false. Design indexes from the real equality, range, ordering, and partial predicates used by lock, restore, and lookup queries.
8286

‎hub/docs/development.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ When you sign in through GitHub or Entra instead, find your `userId` in the brow
7474
NODE_ENV=development npm run db:seed:index -- USER_UUID
7575
```
7676

77-
The command requires an active Hub member and a local development database. It accepts a loopback PostgreSQL URL or the exact devcontainer database URL, and rejects query parameters that override the host, address, port, or service. It creates a sample repository and six prototypes with fixed IDs. Five show each Build state, and one has no Build. Running it again restores those samples. All active Hub members can currently read every non-removed repository. Repository discovery and per-repository authorization are not connected; do not add real repository data until those controls exist.
77+
The command requires an active Hub member and a local development database. It accepts a loopback PostgreSQL URL or the exact devcontainer database URL, and rejects query parameters that override the host, address, port, or service. It creates a sample repository and six prototypes with fixed IDs. Five show each Build state, and one has no Build. Their commit and author values are synthetic. Running it again restores those samples, including metadata added after an upgrade. All active Hub members can currently read every non-removed repository. Repository discovery and per-repository authorization are not connected; do not add real repository data until those controls exist.
7878

7979
Vite also forwards WebSocket upgrades under `/api`. The `/api/realtime` endpoint rejects connections until application access checks are connected; see [WebSocket updates](websockets.md). Stopping the API closes its WebSocket connections as well.
8080

‎hub/schema/build.prisma‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,26 @@ model Build {
88
currentFor Prototype[] @relation("CurrentPrototypeBuild")
99
1010
// Attribute columns
11-
number Int
12-
state BuildState @default(queued)
13-
workflowCreatedAt DateTime? @map("workflow_created_at") @db.Timestamptz(3)
11+
number Int
12+
state BuildState @default(queued)
13+
commitSha String? @map("commit_sha") @db.VarChar(64)
14+
authorProvider String? @map("author_provider") @db.VarChar(100)
15+
authorIssuer String? @map("author_issuer") @db.VarChar(500)
16+
authorProviderUserId String? @map("author_provider_user_id") @db.VarChar(500)
17+
authorLogin String? @map("author_login") @db.VarChar(255)
18+
authorName String? @map("author_name") @db.VarChar(255)
19+
authorAvatarUrl String? @map("author_avatar_url") @db.VarChar(2048)
20+
workflowCreatedAt DateTime? @map("workflow_created_at") @db.Timestamptz(3)
21+
startedAt DateTime? @map("started_at") @db.Timestamptz(3)
22+
finishedAt DateTime? @map("finished_at") @db.Timestamptz(3)
23+
failureSummary String? @map("failure_summary") @db.VarChar(1000)
1424
1525
// Timestamp columns
1626
createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(3)
1727
updatedAt DateTime @default(now()) @updatedAt @map("updated_at") @db.Timestamptz(3)
1828
1929
@@unique([id, prototypeId])
2030
@@unique([prototypeId, number])
31+
@@unique([prototypeId, commitSha])
2132
@@map("builds")
2233
}
Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
ALTER TABLE "builds"
2+
ADD COLUMN "commit_sha" VARCHAR(64),
3+
ADD COLUMN "author_provider" VARCHAR(100),
4+
ADD COLUMN "author_issuer" VARCHAR(500),
5+
ADD COLUMN "author_provider_user_id" VARCHAR(500),
6+
ADD COLUMN "author_login" VARCHAR(255),
7+
ADD COLUMN "author_name" VARCHAR(255),
8+
ADD COLUMN "author_avatar_url" VARCHAR(2048),
9+
ADD COLUMN "started_at" TIMESTAMPTZ(3),
10+
ADD COLUMN "finished_at" TIMESTAMPTZ(3),
11+
ADD COLUMN "failure_summary" VARCHAR(1000);
12+
13+
CREATE UNIQUE INDEX "builds_prototype_id_commit_sha_key"
14+
ON "builds"("prototype_id", "commit_sha");
15+
16+
-- A canonical SHA keeps the same commit from being recorded under different spellings.
17+
ALTER TABLE "builds" ADD CONSTRAINT "builds_commit_sha_check"
18+
CHECK ("commit_sha" IS NULL OR "commit_sha" ~ '^([0-9a-f]{40}|[0-9a-f]{64})$');
19+
20+
-- A provider user ID identifies an author only with its provider and issuer.
21+
ALTER TABLE "builds" ADD CONSTRAINT "builds_author_identity_check"
22+
CHECK (
23+
(
24+
"author_provider" IS NULL
25+
AND "author_issuer" IS NULL
26+
AND "author_provider_user_id" IS NULL
27+
) OR (
28+
"author_provider" IS NOT NULL
29+
AND "author_issuer" IS NOT NULL
30+
AND "author_provider_user_id" IS NOT NULL
31+
AND translate(
32+
"author_provider",
33+
chr(9) || chr(10) || chr(11) || chr(12) || chr(13) || chr(32) ||
34+
chr(133) || chr(160) || chr(5760) || chr(8192) || chr(8193) || chr(8194) ||
35+
chr(8195) || chr(8196) || chr(8197) || chr(8198) || chr(8199) ||
36+
chr(8200) || chr(8201) || chr(8202) || chr(8232) || chr(8233) ||
37+
chr(8239) || chr(8287) || chr(12288) || chr(65279),
38+
''
39+
) <> ''
40+
AND translate(
41+
"author_issuer",
42+
chr(9) || chr(10) || chr(11) || chr(12) || chr(13) || chr(32) ||
43+
chr(133) || chr(160) || chr(5760) || chr(8192) || chr(8193) || chr(8194) ||
44+
chr(8195) || chr(8196) || chr(8197) || chr(8198) || chr(8199) ||
45+
chr(8200) || chr(8201) || chr(8202) || chr(8232) || chr(8233) ||
46+
chr(8239) || chr(8287) || chr(12288) || chr(65279),
47+
''
48+
) <> ''
49+
AND translate(
50+
"author_provider_user_id",
51+
chr(9) || chr(10) || chr(11) || chr(12) || chr(13) || chr(32) ||
52+
chr(133) || chr(160) || chr(5760) || chr(8192) || chr(8193) || chr(8194) ||
53+
chr(8195) || chr(8196) || chr(8197) || chr(8198) || chr(8199) ||
54+
chr(8200) || chr(8201) || chr(8202) || chr(8232) || chr(8233) ||
55+
chr(8239) || chr(8287) || chr(12288) || chr(65279),
56+
''
57+
) <> ''
58+
)
59+
);
60+
61+
ALTER TABLE "builds" ADD CONSTRAINT "builds_failure_summary_check"
62+
CHECK (
63+
"failure_summary" IS NULL
64+
OR ("state" = 'failed' AND octet_length("failure_summary") BETWEEN 1 AND 1000)
65+
);
66+
67+
ALTER TABLE "builds" ADD CONSTRAINT "builds_state_timestamps_check"
68+
CHECK (
69+
("started_at" IS NULL AND "finished_at" IS NULL)
70+
OR ("state" = 'running' AND "started_at" IS NOT NULL AND "finished_at" IS NULL)
71+
OR ("state" = 'superseded' AND "started_at" IS NULL AND "finished_at" IS NOT NULL)
72+
OR ("state" IN ('failed', 'successful') AND "started_at" IS NOT NULL AND "finished_at" IS NOT NULL)
73+
);
Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
import { describe, expect, it } from "vitest"
2+
3+
import { prisma } from "../../integrations/prisma"
4+
import { seedPrototypeIndexData } from "./seed-prototype-index-data"
5+
6+
describe("prototype index seed", () => {
7+
it("seeds a member's prototypes and restores their Build metadata on rerun", async () => {
8+
const user = await prisma.user.create({ data: {} })
9+
await prisma.membership.create({ data: { userId: user.id } })
10+
await seedPrototypeIndexData(prisma, user.id)
11+
const select = {
12+
id: true,
13+
number: true,
14+
state: true,
15+
workflowCreatedAt: true,
16+
commitSha: true,
17+
authorProvider: true,
18+
authorIssuer: true,
19+
authorProviderUserId: true,
20+
authorLogin: true,
21+
authorName: true,
22+
authorAvatarUrl: true,
23+
startedAt: true,
24+
finishedAt: true,
25+
failureSummary: true,
26+
} as const
27+
const samples = await prisma.build.findMany({ select, orderBy: { id: "asc" } })
28+
expect(samples).toHaveLength(5)
29+
const prototypes = await prisma.prototype.findMany({ select: { authorId: true } })
30+
expect(prototypes.every((prototype) => prototype.authorId === user.id)).toBe(true)
31+
expect(samples.map((build) => build.state)).toEqual(
32+
expect.arrayContaining(["queued", "running", "successful", "failed", "superseded"]),
33+
)
34+
for (const build of samples) {
35+
expect(build.commitSha).toMatch(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/)
36+
expect(build.authorProvider).toMatch(/\S/)
37+
expect(build.authorIssuer).toMatch(/\S/)
38+
expect(build.authorProviderUserId).toMatch(/\S/)
39+
expect(build.authorLogin).toMatch(/\S/)
40+
expect(build.authorName).toMatch(/\S/)
41+
expect(build.authorProviderUserId).not.toBe(user.id)
42+
if (build.state === "queued") {
43+
expect(build.startedAt).toBeNull()
44+
expect(build.finishedAt).toBeNull()
45+
}
46+
if (build.state === "running") {
47+
expect(build.startedAt).toBeInstanceOf(Date)
48+
expect(build.finishedAt).toBeNull()
49+
}
50+
if (build.state === "successful" || build.state === "failed") {
51+
expect(build.startedAt).toBeInstanceOf(Date)
52+
expect(build.finishedAt).toBeInstanceOf(Date)
53+
}
54+
if (build.state === "superseded") {
55+
expect(build.startedAt).toBeNull()
56+
expect(build.finishedAt).toBeInstanceOf(Date)
57+
}
58+
if (build.workflowCreatedAt && build.startedAt) {
59+
expect(build.startedAt.getTime()).toBeGreaterThanOrEqual(build.workflowCreatedAt.getTime())
60+
}
61+
if (build.startedAt && build.finishedAt) {
62+
expect(build.finishedAt.getTime()).toBeGreaterThanOrEqual(build.startedAt.getTime())
63+
}
64+
if (build.state === "failed") {
65+
expect(build.failureSummary).toEqual(expect.stringMatching(/\S/))
66+
} else {
67+
expect(build.failureSummary).toBeNull()
68+
}
69+
}
70+
71+
for (const build of samples) {
72+
await prisma.build.update({
73+
where: { id: build.id },
74+
data: {
75+
commitSha: null,
76+
authorProvider: "changed-provider",
77+
authorIssuer: "https://changed.example.test",
78+
authorProviderUserId: "changed-external-id",
79+
authorLogin: "changed-login",
80+
authorName: "Changed Author",
81+
authorAvatarUrl: "https://example.test/changed.png",
82+
startedAt:
83+
build.state === "running" || build.state === "successful" || build.state === "failed"
84+
? new Date("2000-01-01T00:00:00Z")
85+
: null,
86+
finishedAt:
87+
build.state === "superseded" || build.state === "successful" || build.state === "failed"
88+
? new Date("2000-01-01T00:01:00Z")
89+
: null,
90+
failureSummary: build.state === "failed" ? "Changed failure" : null,
91+
},
92+
})
93+
}
94+
await seedPrototypeIndexData(prisma, user.id)
95+
expect(await prisma.build.findMany({ select, orderBy: { id: "asc" } })).toEqual(samples)
96+
}, 60_000)
97+
})

‎hub/server/scripts/seed-prototype-index/index.test.ts‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,34 @@
11
import { spawnSync } from "node:child_process"
22
import { fileURLToPath } from "node:url"
3-
import { describe, expect, it } from "vitest"
3+
import { describe, expect, it, vi } from "vitest"
44

55
describe("prototype index seed", () => {
6+
it("seeds the selected local member and closes the database connection", async () => {
7+
const userId = "00000000-0000-4000-8000-000000000001"
8+
const prisma = { $disconnect: vi.fn() }
9+
const seed = vi.fn()
10+
const originalArgv = process.argv
11+
12+
try {
13+
process.argv = [process.execPath, "seed-prototype-index", userId]
14+
vi.stubEnv("NODE_ENV", "development")
15+
vi.stubEnv("DATABASE_URL", "postgresql://replica:replica@127.0.0.1:5432/replica")
16+
vi.stubEnv("DOTENV_CONFIG_OVERRIDE", "false")
17+
vi.doMock("../../integrations/prisma/index.ts", () => ({ prisma }))
18+
vi.doMock("./seed-prototype-index-data/index.ts", () => ({ seedPrototypeIndexData: seed }))
19+
vi.spyOn(console, "log").mockImplementation(() => {})
20+
21+
await import(".")
22+
23+
expect(seed).toHaveBeenCalledExactlyOnceWith(prisma, userId)
24+
expect(prisma.$disconnect).toHaveBeenCalledOnce()
25+
} finally {
26+
process.argv = originalArgv
27+
vi.doUnmock("../../integrations/prisma/index.ts")
28+
vi.doUnmock("./seed-prototype-index-data/index.ts")
29+
}
30+
})
31+
632
it("rejects unsafe configuration before initializing Prisma", () => {
733
const script = fileURLToPath(new URL("./index.ts", import.meta.url))
834
const result = spawnSync(process.execPath, [script, "00000000-0000-4000-8000-000000000001"], {

0 commit comments

Comments
 (0)