rvlib-shipkit 0.31.0 → 0.32.0

package/src/pb/collection-scaffold.ts

@@ -0,0 +1,299 @@
+// the file bodies `shipkit pb collection <name>` writes into an app's
+// src/collections/<name>/.
+//
+// THE SHAPE IS NOT THIS FILE'S TO INVENT. It reproduces the house collection
+// folder: `X.` Mantine globals rather than @mantine/core imports, `observer`
+// around anything reading observables, a form that is
+// `ComponentType<{ record?, onClose }>` writing through `db` fire and forget,
+// and an index that CALLS defineCollectionUI as a statement (it returns void).
+// A generator that emits a second dialect is worse than no generator: the code
+// it writes is what the next developer copies.
+//
+// Pure: schema in, {rel, body} out, so the emitter is testable and the fs half
+// stays in run-pb.ts. Anything the schema cannot decide (how a relation reads,
+// what a file url is) is emitted COMMENTED with the reason, never guessed and
+// never dropped: a missing column is invisible, a commented one takes ten
+// seconds to accept or delete.
+import type { PbCollection, PbField } from './pb-types.ts'
+
+export type ScaffoldedFile = { rel: string; body: string }
+
+/** the app's own modules, relative to src/collections/<name>/ */
+const TYPES = '../../pb.types'
+const PB = '../../pb'
+
+/** `client_name` → `Client name`, `emailVisibility` → `Email visibility` */
+export function humanLabel(name: string): string {
+    const words = name.replace(/_/g, ' ').replace(/([a-z0-9])([A-Z])/g, '$1 $2').trim().toLowerCase()
+    return words.charAt(0).toUpperCase() + words.slice(1)
+}
+
+const isIdent = (s: string): boolean => /^[A-Za-z_$][\w$]*$/.test(s)
+const prop = (s: string): string => (isIdent(s) ? `.${s}` : `[${JSON.stringify(s)}]`)
+
+/** the label a list row shows, by convention over the schema */
+const LABEL_PREFERENCE = ['name', 'label', 'title', 'number', 'code', 'email']
+
+export function labelField(col: PbCollection): PbField {
+    for (const want of LABEL_PREFERENCE) {
+        const hit = col.fields.find((f) => f.name === want && !f.secret)
+        if (hit != null) return hit
+    }
+    const id = col.fields.find((f) => f.name === 'id')
+    if (id == null) throw new Error(`collection '${col.name}' has no id field`)
+    return id
+}
+
+/** a value already a string needs no String() around it */
+const readsAsString = (f: PbField): boolean =>
+    !f.array && (f.kind === 'string' || f.kind === 'select' || f.kind === 'date' || f.kind === 'autodate')
+
+/** columns whose value the schema alone cannot turn into a cell */
+const NOT_RENDERABLE: Partial<Record<PbField['kind'], string>> = {
+    relation: 'relation: <RefCell> it, or render the expanded record',
+    file: 'file: build a url with pb.files.getURL(r, …)',
+    json: 'json: pick the fields you want out of the blob',
+    html: 'html markup: render it deliberately, or strip the tags',
+    unknown: 'unrecognised generated type',
+}
+
+/** system plumbing that is never a column worth showing */
+const NOISE = new Set(['collectionId', 'collectionName', 'expand'])
+
+export type ColumnPlan = { field: PbField; render: string | null; sortable: boolean; why: string }
+
+export function planColumns(col: PbCollection): ColumnPlan[] {
+    const plans: ColumnPlan[] = []
+    for (const f of col.fields) {
+        if (f.secret) continue
+        const acc = `r${prop(f.name)}`
+        const push = (render: string | null, why: string, sortable = false): void => void plans.push({ field: f, render, sortable, why })
+        if (NOISE.has(f.name)) { push(null, 'system field, rarely worth a column', true); continue }
+        const blocked = NOT_RENDERABLE[f.kind]
+        if (blocked != null) { push(null, blocked, !f.array); continue }
+        // `key` means the SERVER sorts this column, so a derived cell drops it:
+        // a multi-value field sorts lexically on its raw storage, which is not
+        // what the joined text on screen says
+        if (f.array) { push(`${acc}.join(", ")`, ''); continue }
+        // react renders a boolean as nothing at all, so it has to be spelled out
+        if (f.kind === 'boolean') { push(`String(${acc})`, '', true); continue }
+        push(acc, '', true)
+    }
+    return plans
+}
+
+/** the writable scalar fields a Mantine form can carry on its own */
+export function planForm(col: PbCollection): PbField[] {
+    return col.fields.filter((f) => {
+        if (f.readOnly || f.secret) return false
+        // a multi-value field is editable when its values are free text or a
+        // named union; an array of relations or files still needs a picker
+        if (f.array) return f.kind === 'select' || f.kind === 'string'
+        return f.kind === 'string' || f.kind === 'number' || f.kind === 'boolean' || f.kind === 'date' || f.kind === 'select' || f.kind === 'html'
+    })
+}
+
+function columnsFile(col: PbCollection): string {
+    const lines: string[] = []
+    lines.push(`// what a row of \`${col.name}\` looks like in a grid, and in an export. ONE`)
+    lines.push('// definition, so the table, the card and the csv can never disagree.')
+    lines.push('// `key` is the SERVER sort field: present means the header sorts, absent')
+    lines.push('// means the cell is derived and the database cannot order by it.')
+    lines.push('// labels are plain text, swap them for i18n.t.<collection>.<field> when the')
+    lines.push('// app carries a dict.')
+    lines.push(`import type { Column } from "rvlib-pb-shell"`)
+    lines.push(`import type { ${col.prefix}Response } from "${TYPES}"`)
+    lines.push('')
+    lines.push(`export const columns: Column<${col.prefix}Response>[] = [`)
+    for (const p of planColumns(col)) {
+        const key = p.sortable ? `key: ${JSON.stringify(p.field.name)}, ` : ''
+        const align = p.field.kind === 'number' && !p.field.array ? 'align: "right", ' : ''
+        const entry = `{ ${key}label: ${JSON.stringify(humanLabel(p.field.name))}, ${align}render: (r) => ${p.render ?? `r${prop(p.field.name)}`} },`
+        if (p.render == null) {
+            lines.push(`    // ${p.why}`)
+            lines.push(`    // ${entry}`)
+        } else {
+            lines.push(`    ${entry}`)
+        }
+    }
+    lines.push(']')
+    return `${lines.join('\n')}\n`
+}
+
+function cardFile(col: PbCollection, cardFields: PbField[]): string {
+    const [first, second, third] = cardFields
+    const show = (f: PbField): string =>
+        f.array ? `{r${prop(f.name)}.join(", ")}` : readsAsString(f) ? `{r${prop(f.name)}}` : `{String(r${prop(f.name)})}`
+    const lines: string[] = []
+    lines.push('// the same record as a card, for a LiveCards view or a mobile layout')
+    lines.push(`import type { ${col.prefix}Response } from "${TYPES}"`)
+    lines.push('')
+    lines.push(`export const ${col.prefix}Card = (r: ${col.prefix}Response) => (`)
+    lines.push('    <X.Paper withBorder p="md" radius="md">')
+    lines.push('        <X.Group justify="space-between" wrap="nowrap">')
+    if (first != null) lines.push(`            <X.Text fw={600} truncate>${show(first)}</X.Text>`)
+    if (second != null) lines.push(`            <X.Text size="sm" c="dimmed">${show(second)}</X.Text>`)
+    lines.push('        </X.Group>')
+    if (third != null) lines.push(`        <X.Text size="sm">${show(third)}</X.Text>`)
+    lines.push('    </X.Paper>')
+    lines.push(')')
+    return `${lines.join('\n')}\n`
+}
+
+function gridFile(col: PbCollection): string {
+    return [
+        `// the default grid for \`${col.name}\`. A page that wants the plain table renders`,
+        '// this; a page that wants extra columns passes its own to LiveGrid directly.',
+        `import type { LiveList } from "rvlib-pb-mobx"`,
+        `import { LiveGrid } from "rvlib-pb-shell"`,
+        `import type { ${col.prefix}Response } from "${TYPES}"`,
+        `import { columns } from "./columns"`,
+        '',
+        `export const ${col.prefix}Grid = (p: { list: LiveList<${col.prefix}Response>; selection?: boolean }) => (`,
+        '    <LiveGrid list={p.list} columns={columns} selection={p.selection} />',
+        ')',
+        '',
+    ].join('\n')
+}
+
+function inputFor(f: PbField): string {
+    const label = JSON.stringify(humanLabel(f.name))
+    const key = JSON.stringify(f.name)
+    // a select whose options union typegen did not name has no data source, so
+    // it falls through to a free text input rather than to a broken reference
+    if (f.kind === 'select' && f.optionsType != null) {
+        const control = f.array ? 'MultiSelect' : 'Select'
+        return `<X.${control} label=${label} data={Object.values(${f.optionsType})} {...form.getInputProps(${key})} />`
+    }
+    if (f.array && f.kind === 'string') return `<X.TagsInput label=${label} {...form.getInputProps(${key})} />`
+    if (f.kind === 'boolean') return `<X.Checkbox label=${label} {...form.getInputProps(${key}, { type: "checkbox" })} />`
+    if (f.kind === 'number') return `<X.NumberInput label=${label} {...form.getInputProps(${key})} />`
+    if (f.kind === 'html') return `<X.Textarea label=${label} autosize minRows={3} {...form.getInputProps(${key})} />`
+    if (f.kind === 'date') return `<X.TextInput label=${label} placeholder="YYYY-MM-DD" {...form.getInputProps(${key})} />`
+    return `<X.TextInput label=${label} {...form.getInputProps(${key})} />`
+}
+
+/** what an unset field is, in the app's own terms */
+function emptyValue(f: PbField): string {
+    if (f.array) return '[]'
+    if (f.kind === 'boolean') return 'false'
+    if (f.kind === 'number') return '0'
+    // an optional select starts EMPTY, which is pocketbase's own default, so a
+    // new record never gets a value nobody picked. The cast is the price of the
+    // generated union not admitting the unset state it actually stores
+    if (f.kind === 'select' && f.optionsType != null) {
+        return f.optional ? `("" as ${f.optionsType})` : `Object.values(${f.optionsType})[0]!`
+    }
+    return '""'
+}
+
+function formFile(col: PbCollection, fields: PbField[], left: PbField[]): string {
+    const options = [...new Set(fields.filter((f) => f.kind === 'select').map((f) => f.optionsType).filter((o): o is string => o != null))].sort()
+    const lines: string[] = []
+    lines.push('// create and edit, as a modal. Validators mirror the server rules verbatim:')
+    lines.push("// the UI is a courtesy, the collection's API rules are the enforcement.")
+    lines.push(`import { useForm } from "@mantine/form"`)
+    lines.push(`import { observer } from "rvlib-mobx/src/obs.ts"`)
+    lines.push(`import { db } from "${PB}"`)
+    if (options.length > 0) lines.push(`import { ${options.join(', ')} } from "${TYPES}"`)
+    lines.push(`import type { ${col.prefix}Response } from "${TYPES}"`)
+    lines.push('')
+    if (left.length > 0) {
+        lines.push(`// no input for ${left.map((f) => `${f.name} (${f.kind})`).join(', ')}:`)
+        lines.push('// those need a picker or an uploader of their own.')
+    }
+    lines.push(`type Draft = Pick<`)
+    lines.push(`    ${col.prefix}Response,`)
+    lines.push(fields.map((f) => `    | ${JSON.stringify(f.name)}`).join('\n'))
+    lines.push('>')
+    lines.push('')
+    lines.push(`export const ${col.prefix}Form = observer(function ${col.prefix}Form_(p: { record?: ${col.prefix}Response; onClose: () => void }) {`)
+    lines.push('    const form = useForm<Draft>({')
+    lines.push('        initialValues: {')
+    for (const f of fields) {
+        const key = isIdent(f.name) ? f.name : JSON.stringify(f.name)
+        lines.push(`            ${key}: p.record?${prop(f.name)} ?? ${emptyValue(f)},`)
+    }
+    lines.push('        },')
+    lines.push('    })')
+    lines.push('')
+    lines.push('    // fire and forget: the data layer notifies and rolls back on rejection')
+    lines.push('    const submit = form.onSubmit((values) => {')
+    lines.push(`        if (p.record) db${prop(col.name)}.update(p.record.id, values)`)
+    lines.push(`        else db${prop(col.name)}.create(values)`)
+    lines.push('        p.onClose()')
+    lines.push('    })')
+    lines.push('')
+    lines.push('    return (')
+    lines.push(`        <X.Modal opened onClose={p.onClose} title=${JSON.stringify(humanLabel(col.name))}>`)
+    lines.push('            <form onSubmit={submit}>')
+    lines.push('                <X.Stack>')
+    for (const f of fields) lines.push(`                    ${inputFor(f)}`)
+    lines.push('                    <X.Group justify="flex-end">')
+    lines.push('                        <X.Button variant="default" onClick={p.onClose}>Cancel</X.Button>')
+    lines.push('                        <X.Button type="submit">Save</X.Button>')
+    lines.push('                    </X.Group>')
+    lines.push('                </X.Stack>')
+    lines.push('            </form>')
+    lines.push('        </X.Modal>')
+    lines.push('    )')
+    lines.push('})')
+    return `${lines.join('\n')}\n`
+}
+
+function indexFile(col: PbCollection, hasForm: boolean): string {
+    const label = labelField(col)
+    const lines: string[] = []
+    lines.push('// registration: after this import, a LiveGrid or LiveCards over')
+    lines.push(`// \`${col.name}\` with no columns of its own knows what to render, and any`)
+    lines.push('// relation cell pointing AT one knows how to name it.')
+    lines.push(`import { defineCollectionUI } from "rvlib-pb-shell"`)
+    lines.push(`import { db } from "${PB}"`)
+    lines.push(`import { ${col.prefix}Card } from "./card"`)
+    lines.push(`import { columns } from "./columns"`)
+    if (hasForm) lines.push(`import { ${col.prefix}Form } from "./form"`)
+    lines.push('')
+    lines.push(`defineCollectionUI(db${prop(col.name)}, {`)
+    lines.push('    columns,')
+    lines.push(`    card: ${col.prefix}Card,`)
+    lines.push(`    label: (r) => ${readsAsString(label) ? `r${prop(label.name)}` : `String(r${prop(label.name)})`},`)
+    if (hasForm) lines.push(`    form: ${col.prefix}Form,`)
+    lines.push('})')
+    lines.push('')
+    lines.push(`export { columns, ${col.prefix}Card${hasForm ? `, ${col.prefix}Form` : ''} }`)
+    lines.push(`export { ${col.prefix}Grid } from "./grid"`)
+    return `${lines.join('\n')}\n`
+}
+
+/** what a card leads with. Generated record blocks are ALPHABETICAL, so the
+ *  first three fields of a schema are meaningless: rank by how much a human
+ *  reads a value instead, and keep `id` as the last resort. */
+export function rankForCard(col: PbCollection, plans: ColumnPlan[]): PbField[] {
+    const label = labelField(col).name
+    const tier = (f: PbField): number => {
+        if (f.name === 'id') return 9
+        if (f.name === label) return 0
+        if (f.kind === 'string' || f.kind === 'select') return 1
+        if (f.kind === 'date') return 2
+        return 3
+    }
+    return plans.map((p) => p.field).map((f, i) => ({ f, i, t: tier(f) })).sort((a, b) => a.t - b.t || a.i - b.i).map((x) => x.f)
+}
+
+/** every file the collection folder gets, in write order */
+export function scaffoldCollectionUI(col: PbCollection): ScaffoldedFile[] {
+    const dir = `src/collections/${col.name}`
+    const shown = planColumns(col).filter((p) => p.render != null && !NOISE.has(p.field.name) && p.field.kind !== 'autodate')
+    const cardFields = rankForCard(col, shown).slice(0, 3)
+    const formFields = planForm(col)
+    const left = col.fields.filter((f) => !f.readOnly && !f.secret && !formFields.includes(f))
+    const files: ScaffoldedFile[] = [
+        { rel: `${dir}/columns.tsx`, body: columnsFile(col) },
+        { rel: `${dir}/card.tsx`, body: cardFile(col, cardFields) },
+        { rel: `${dir}/grid.tsx`, body: gridFile(col) },
+    ]
+    // a collection with nothing writable gets NO form rather than an empty one
+    if (formFields.length > 0) files.push({ rel: `${dir}/form.tsx`, body: formFile(col, formFields, left) })
+    files.push({ rel: `${dir}/index.ts`, body: indexFile(col, formFields.length > 0) })
+    return files
+}

package/src/pb/pb-types.ts

@@ -0,0 +1,233 @@
+// reading a PocketBase schema out of an app's GENERATED types file
+// (pocketbase-typegen output).
+//
+// CONSTRAINT: this is a LINE parse of generated code, not a TypeScript AST.
+// shipkit carries no typescript dependency, and the input is machine written
+// with exactly one field per line, so a line parse is exact for the shape
+// typegen emits and worthless for anything else. Two consequences the callers
+// depend on: a file that yields zero collections is reported as "not typegen
+// output" rather than as an empty schema, and every line inside a record block
+// that does not parse is returned in `unparsed` so it can be shown, never
+// dropped.
+
+/** what a generated field type maps to, which decides how it renders and
+ *  whether a form can edit it at all */
+export type PbFieldKind =
+    | 'string'
+    | 'number'
+    | 'boolean'
+    | 'date'
+    | 'autodate'
+    | 'relation'
+    | 'file'
+    | 'select'
+    | 'json'
+    | 'html'
+    | 'unknown'
+
+export type PbField = {
+    name: string
+    /** the type expression exactly as generated, `[]` included */
+    type: string
+    kind: PbFieldKind
+    /** the generated field carried a `?` */
+    optional: boolean
+    array: boolean
+    /** select fields: the generated `<Prefix><Field>Options` union to import */
+    optionsType?: string
+    /** written by the server or the auth layer, never by a form */
+    readOnly: boolean
+    /** a credential the scaffold must never put on screen */
+    secret: boolean
+    /** added from the API's response shape, not declared in the record block */
+    system: boolean
+}
+
+export type PbCollection = {
+    /** the name PocketBase knows, `order_lines` */
+    name: string
+    /** the generated type prefix, `OrderLines` */
+    prefix: string
+    /** an auth collection, so the response carries email/username/verified */
+    auth: boolean
+    /** false when the `<Prefix>Record` block is absent or unreadable, which is
+     *  a PARSE failure and not an empty collection */
+    readable: boolean
+    fields: PbField[]
+    /** record-block lines this parser could not read */
+    unparsed: string[]
+}
+
+/** an auth collection's identity fields do not move through a plain patch:
+ *  `verified` is superuser-only, and email and username have their own
+ *  endpoints, so a form control over them submits into the void */
+const AUTH_MANAGED = new Set(['email', 'emailVisibility', 'username', 'verified'])
+
+/** pocketbase's own internal collections, never an app surface */
+export const isSystemCollection = (name: string): boolean => name.startsWith('_')
+
+/** fields the API adds to every response, absent from the record block */
+const BASE_SYSTEM: [string, PbFieldKind][] = [
+    ['id', 'string'],
+    ['collectionId', 'string'],
+    ['collectionName', 'string'],
+]
+const AUTH_SYSTEM: [string, PbFieldKind][] = [
+    ['email', 'string'],
+    ['emailVisibility', 'boolean'],
+    ['username', 'string'],
+    ['verified', 'boolean'],
+]
+
+const SYSTEM_NAMES = new Set(['id', 'collectionId', 'collectionName', 'expand'])
+const SECRET_NAMES = new Set(['password', 'passwordConfirm', 'oldPassword', 'tokenKey'])
+
+/** the body between a `{` and its matching `}`, or null when unbalanced */
+function braceBlock(src: string, openIdx: number): string | null {
+    let depth = 0
+    for (let i = openIdx; i < src.length; i++) {
+        const c = src[i]
+        if (c === '{') depth++
+        else if (c === '}') {
+            depth--
+            if (depth === 0) return src.slice(openIdx + 1, i)
+        }
+    }
+    return null
+}
+
+/** the body of `export type <name><generics?> = { … }`. The open brace is
+ *  found by scanning forward rather than by regex, because typegen
+ *  parameterises a record carrying a json field (`<Tdata = unknown>`) and the
+ *  default value swallows any `=\\s*{` pattern */
+function typeBlock(src: string, name: string): string | null {
+    const head = new RegExp(`export\\s+(?:type|interface)\\s+${name}\\b`).exec(src)
+    if (head == null) return null
+    const from = head.index + head[0].length
+    const open = src.indexOf('{', from)
+    if (open === -1) return null
+    // a declaration with no object body at all (an alias) must not borrow the
+    // braces of whatever is declared next
+    const nextDecl = src.indexOf('\nexport ', from)
+    if (nextDecl !== -1 && nextDecl < open) return null
+    return braceBlock(src, open)
+}
+
+export function kindOf(typeExpr: string): { kind: PbFieldKind; array: boolean; optionsType?: string } {
+    const stripped = typeExpr.replace(/\s+/g, ' ').trim()
+    // typegen writes a json field as `null | Tdata`, the generic the record
+    // type is parameterised by
+    if (/\bnull\s*\|/.test(stripped)) return { kind: 'json', array: /\[\]/.test(stripped) }
+    const array = /\[\]$/.test(stripped)
+    const base = stripped.replace(/\[\]$/, '').trim()
+    if (base === 'IsoAutoDateString') return { kind: 'autodate', array }
+    if (base === 'IsoDateString') return { kind: 'date', array }
+    if (base === 'RecordIdString') return { kind: 'relation', array }
+    if (base === 'FileNameString') return { kind: 'file', array }
+    if (base === 'HTMLString') return { kind: 'html', array }
+    if (base === 'GeoPoint') return { kind: 'json', array }
+    if (base === 'number') return { kind: 'number', array }
+    if (base === 'boolean') return { kind: 'boolean', array }
+    if (base === 'string') return { kind: 'string', array }
+    if (/^[A-Za-z_$][\w$]*Options$/.test(base)) return { kind: 'select', array, optionsType: base }
+    return { kind: 'unknown', array }
+}
+
+/** one `name?: Type` line of a record block */
+function parseFieldLine(line: string): PbField | null {
+    const m = /^\s*(?:"([^"]+)"|([A-Za-z_$][\w$]*))(\?)?\s*:\s*(.+?)\s*[,;]?\s*$/.exec(line)
+    if (m == null) return null
+    const name = m[1] ?? m[2]
+    if (name == null) return null
+    const type = m[4]
+    if (type == null) return null
+    const { kind, array, optionsType } = kindOf(type)
+    return {
+        name,
+        type,
+        kind,
+        optional: m[3] === '?',
+        array,
+        ...(optionsType == null ? {} : { optionsType }),
+        readOnly: kind === 'autodate' || SYSTEM_NAMES.has(name) || SECRET_NAMES.has(name),
+        secret: SECRET_NAMES.has(name),
+        system: false,
+    }
+}
+
+/** collection name → generated type prefix, from `CollectionRecords` when the
+ *  file has one and from the `Collections` const or enum otherwise */
+function collectionPrefixes(src: string): Map<string, string> {
+    const out = new Map<string, string>()
+    const recordsHead = /export\s+type\s+CollectionRecords\s*=\s*\{/.exec(src)
+    if (recordsHead != null) {
+        const body = braceBlock(src, recordsHead.index + recordsHead[0].length - 1) ?? ''
+        for (const line of body.split('\n')) {
+            const m = /^\s*(?:"([^"]+)"|([A-Za-z_$][\w$]*))\s*:\s*([A-Za-z_$][\w$]*)Record\b/.exec(line)
+            const name = m?.[1] ?? m?.[2]
+            const prefix = m?.[3]
+            if (name != null && prefix != null) out.set(name, prefix)
+        }
+        if (out.size > 0) return out
+    }
+    const constHead = /export\s+(?:const|enum)\s+Collections\s*=?\s*\{/.exec(src)
+    if (constHead != null) {
+        const body = braceBlock(src, constHead.index + constHead[0].length - 1) ?? ''
+        for (const line of body.split('\n')) {
+            const m = /^\s*(?:"([^"]+)"|([A-Za-z_$][\w$]*))\s*[:=]\s*"([^"]+)"/.exec(line)
+            const prefix = m?.[1] ?? m?.[2]
+            const name = m?.[3]
+            if (name != null && prefix != null) out.set(name, prefix)
+        }
+    }
+    return out
+}
+
+/** every collection the generated file describes, in declaration order */
+export function parsePbTypes(src: string): PbCollection[] {
+    const out: PbCollection[] = []
+    for (const [name, prefix] of collectionPrefixes(src)) {
+        const block = typeBlock(src, `${prefix}Record`)
+        const auth0 = new RegExp(`export\\s+type\\s+${prefix}Response\\b[^\\n]*AuthSystemFields`).test(src)
+        if (block == null) {
+            out.push({ name, prefix, auth: auth0, readable: false, fields: [], unparsed: [] })
+            continue
+        }
+        const fields: PbField[] = []
+        const unparsed: string[] = []
+        const seen = new Set<string>()
+        for (const raw of block.split('\n')) {
+            const line = raw.trim()
+            if (line === '' || line.startsWith('//') || line.startsWith('*') || line.startsWith('/*')) continue
+            const field = parseFieldLine(raw)
+            if (field == null) {
+                unparsed.push(line)
+                continue
+            }
+            if (seen.has(field.name)) continue
+            seen.add(field.name)
+            fields.push(field)
+        }
+        const auth = auth0
+        // the record block holds the collection's OWN fields, the response adds
+        // the API's, so a scaffold built off the record alone would miss half
+        // the columns the list actually has
+        for (const [sysName, sysKind] of [...BASE_SYSTEM, ...(auth ? AUTH_SYSTEM : [])]) {
+            if (seen.has(sysName)) continue
+            seen.add(sysName)
+            fields.push({
+                name: sysName,
+                type: sysKind === 'boolean' ? 'boolean' : 'string',
+                kind: sysKind,
+                optional: false,
+                array: false,
+                readOnly: SYSTEM_NAMES.has(sysName) || SECRET_NAMES.has(sysName) || (auth && AUTH_MANAGED.has(sysName)),
+                secret: SECRET_NAMES.has(sysName),
+                system: true,
+            })
+        }
+        if (auth) for (const f of fields) if (AUTH_MANAGED.has(f.name)) f.readOnly = true
+        out.push({ name, prefix, auth, readable: true, fields, unparsed })
+    }
+    return out
+}