schema-forge site generate has no codegen branch for file field types

[rrrodzilla]

Problem

schema-forge site generate doesn't have a code branch for file field types in edit.generated.tsx.jinja. Schemas with a file field fall through to the default <input> branch in the form generator and emit:

<input
  id={field.name}
  {...field}
  value={field.value as string | undefined ?? ""}
  className={"input" + (fieldState.error ? " invalid" : "")}
/>

field.value for a file-typed field is a FileAttachment object ({ key, status, size, mime, uploaded_at?, checksum? }), not a string. TypeScript catches the cast at build time:

src/app/pages/<entity>/edit.generated.tsx(140,24): error TS2352: Conversion of
type '{ key: string; status: string; size: number; mime: string; ... }' to type
'string' may be a mistake because neither type sufficiently overlaps with the
other.

Even if you bypass the cast, the runtime renders [object Object] in the input — the generated form is non-functional for file fields. detail.generated.tsx.jinja and list.generated.tsx.jinja have no file handling at all (same hole).

Reproduction

Any schema with a file field, e.g.:

schema Document {
    name:       text(max: 255) required
    attachment: file(bucket: "documents", max_size: "10MB", mime: ["application/pdf"]) required
}

schema-forge site generate -s schemas -o site
cd site && pnpm install && pnpm build
# fails on edit.generated.tsx

What the file branch needs to do

The runtime already exposes a three-endpoint upload flow:

1. POST /api/v1/forge/schemas/<schema>/entities/<id>/fields/<field>/upload-url — mint presigned PUT URL
2. PUT <presigned_url> — client uploads bytes directly to S3
3. POST /api/v1/forge/schemas/<schema>/entities/<id>/fields/<field>/confirm-upload — register the upload

The codegen should emit a <FileUpload> component that:

• In edit mode with an existing attachment: shows filename / status / size and offers a "Replace" button that runs the three-step flow against the existing entity id
• In create mode (no entity id yet): defers the upload until after the entity is created — typical pattern is "save first, then upload" with a two-phase form, OR creates a draft entity, OR (simplest) renders a disabled state with copy explaining file uploads happen after first save
• Surfaces the file-state-machine status (pending → uploaded → scanning → available|quarantined|rejected)
• Uses the field's access mode (presigned vs proxied) for download links
• Vendors as src/components/ui/file-upload.tsx alongside the other shadcn primitives (or as a SchemaForge-specific component if it ends up too coupled to the upload flow)

detail.generated.tsx.jinja likely has the same kind of mismatch when displaying file attachments. list.generated.tsx.jinja should never include a file column by default — it's not summarisable in a list cell, and a column would force N extra presigned-URL fetches per page.

Open design questions (resolve before implementation)

1. Create-mode strategy: two-phase form ("save first, then upload"), draft entity, or disabled-with-copy. Two-phase is simplest and matches typical shadcn/Hook Form stacks; draft entities introduce GC complexity.
2. Component location: vendored src/components/ui/file-upload.tsx (shadcn convention) or SchemaForge-specific path? It's not a generic primitive — it knows about the 3-endpoint flow and the file-state-machine.
3. Polling for scanning → available: server-sent event, client polling, or user-triggered refresh? Avirum scan latency varies; need a UX answer before coding.

Workaround applied locally (stub, do not ship)

crates/schema-forge-cli/templates/site/src/app/pages/edit.generated.tsx.jinja has a read-only stub branch for f.kind == "file" that unblocks pnpm build but leaves users without an upload UI:

{%- elif f.kind == "file" %}
              <div className="mono" style={ { ... }}>
                {(() => {
                  const att = field.value as { key?: string; status?: string; size?: number } | null | undefined
                  return att && att.key
                    ? `${att.key} · ${att.status ?? "unknown"}${att.size ? ` · ${att.size} bytes` : ""}`
                    : "no file attached — upload via API"
                })()}
              </div>

Uploads have to be made via direct API calls until a real <FileUpload> widget ships.

Acceptance criteria

• edit.generated.tsx.jinja has an f.kind == "file" branch that renders a real upload widget driving the three-endpoint flow
• detail.generated.tsx.jinja renders attachments with at least filename / size / state / download link
• list.generated.tsx.jinja either hides file fields by default or renders a non-crashing placeholder
• A vendored <FileUpload> component ships alongside the existing shadcn primitives
• pnpm build passes on a generated site for any schema using file fields, with no TS escape hatches needed in either generated or preserve files
• Create-mode behavior is consistent and documented (whichever strategy is chosen)
• File-state-machine transitions are visible to the user (no silent scanning → quarantined failures)

Split-out adjacent issues

Two smaller things spotted while reproducing this — split into their own issues:

• principal_claims source TOML form documented in reference doesn't deserialize #54 — principal-claims-reference.md documents a TOML form for source that doesn't deserialize
• /health endpoint reports stale version (lags workspace crate version) #55 — /health reports a stale version (lags the workspace crate version)

[rrrodzilla]

Shipped in 87e2f14 (schema-forge-cli 0.26.0).

What landed

• src/components/ui/file-upload.tsx — new vendored primitive exporting FileUpload (controlled editor for the 3-endpoint upload flow) and AttachmentDownload (read-only download button that honors presigned vs proxied access mode). Self-contained: reads VITE_API_BASE and pulls the PASETO token from @/lib/auth.
• edit.generated.tsx.jinja — file branch now renders <FileUpload> with full file metadata (size cap, MIME allowlist, access mode). FormFields accepts an optional entityId?: string; create mode renders a "save first" hint instead of the broken <input> cast. normalize<Pascal>Payload strips file fields from the entity PUT body so the round-trip never resends a stale FileAttachment.
• edit.tsx.jinja — preserve template now passes entityId={id} for schemas with file fields.
• detail.generated.tsx.jinja — file branch renders <AttachmentDownload> against the field endpoint.
• list.generated.tsx.jinja — file fields default to hidden. default_list_placement was the bug: it only listed rich_text | composite | array | relation_one | relation_many | json as auto-hide kinds; file now joins them. Explicit @list(column) annotations still win.

Acceptance criteria

• edit.generated.tsx.jinja has an f.kind == "file" branch driving the three-endpoint flow
• detail.generated.tsx.jinja renders attachments with filename / size / state / download link
• list.generated.tsx.jinja hides file fields by default
• Vendored <FileUpload> ships alongside the existing shadcn primitives
• pnpm build passes on a generated site for any schema using file fields, with no TS escape hatches
• Create-mode behavior is consistent ("save first" hint; uppload widget unlocks after first save)
• File-state-machine transitions are visible to the user (StatusChip surfaces pending → uploaded → scanning → available|quarantined|rejected)

Verification

• 260 CLI codegen tests pass (3 new tests cover the file branches against a synthetic Document schema).
• End-to-end: schema-forge site generate against a schema with a file field produces a tree where pnpm tsc --noEmit and pnpm build are both clean.
• End-to-end: same generator against a schema without any file fields also passes both — conditional import gating on entity.has_file_field keeps noUnusedLocals satisfied.

Migration note for existing generated sites

Sites generated against an older CLI keep their existing preserve edit.tsx. To pick up uploads on a file-bearing schema, either pass entityId={id} to <EntityFormFields> manually, or regenerate that file with --force-user-files. Until then the upload widget renders the "save first" hint instead of the input — non-fatal, but no uploads.

Adjacent issues split out earlier

• principal_claims source TOML form documented in reference doesn't deserialize #54 — principal-claims-reference.md documents a TOML form for source that doesn't deserialize
• /health endpoint reports stale version (lags workspace crate version) #55 — /health reports a stale version (lags the workspace crate version)