diff --git a/docs/superpowers/plans/2026-06-05-followups-batch.md b/docs/superpowers/plans/2026-06-05-followups-batch.md new file mode 100644 index 0000000..84837a4 --- /dev/null +++ b/docs/superpowers/plans/2026-06-05-followups-batch.md @@ -0,0 +1,317 @@ +# Follow-ups Batch (#38, #28, #41, #26) Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:subagent-driven-development. Steps use `- [ ]`. + +**Goal:** Four small, well-specified follow-ups: enum-type `SearchHitView.visibility` (#38); carry the offending field in the `set_fields` 422 so the UI can highlight it (#28); normalize `localized_text` to the default language on save (#41); pin the pnpm version (#26). + +**Tech Stack:** Rust (axum, utoipa), React + TS, react-hook-form, Vitest + RTL + MSW. + +**Conventions:** nightly fmt; clippy `-D warnings`; no `any`/`eslint-disable`/`@ts-ignore`; en/sv parity; codename ban; bundle ≤150 KB gz. Test infra: `DATABASE_URL=postgres://postgres:postgres@localhost:5442/cms_dev`, `MEILI_URL=http://localhost:7700`, `MEILI_MASTER_KEY=masterKey`. cargo from repo root; web from `web/`. + +--- + +## Task 1: Backend — `SearchHitView.visibility` enum (#38) + `set_fields` field-level 422 (#28) + +**Files:** Modify `crates/api/src/admin_search.rs`, `crates/api/src/admin_objects.rs`, `crates/api/src/openapi.rs`; Test `crates/api/tests/admin_objects.rs`; Regenerate `web/src/api/schema.d.ts`. + +### #38 — enum-type the search hit visibility +- [ ] **Step 1:** In `crates/api/src/admin_search.rs`, `SearchHitView.visibility` (line ~31, `pub visibility: String`): add the attribute above it: +```rust + #[schema(value_type = domain::Visibility)] + pub visibility: String, +``` +(`domain::Visibility` already derives `ToSchema` and is registered in `openapi.rs` from #29 — no further registration needed.) + +### #28 — carry the offending field in the 422 +The db `FieldError` already names the field (`UnknownField(String)`, `TypeMismatch { field, .. }`, `Unresolved { field, .. }`). Surface it. + +- [ ] **Step 2:** In `crates/api/src/admin_objects.rs`, add a response DTO near the other views: +```rust +/// Field-level rejection detail for `set_fields`, so the UI can highlight the field. +#[derive(serde::Serialize, utoipa::ToSchema)] +pub(crate) struct FieldErrorView { + /// The flexible-field key that was rejected. + pub field: String, + /// Machine code: "unknown" | "type_mismatch" | "unresolved". + pub code: String, +} +``` + +- [ ] **Step 3:** Change the `set_fields` handler to return a body on the field-error 422s. Its signature is `-> Result`; change to `-> axum::response::Response` and build responses (import `axum::response::IntoResponse`): +```rust +) -> axum::response::Response { + use axum::response::IntoResponse; + + let Ok(object_id) = id.parse::() else { + return StatusCode::NOT_FOUND.into_response(); + }; + + let mut tx = match state.db.pool().begin().await { + Ok(tx) => tx, + Err(_) => return StatusCode::INTERNAL_SERVER_ERROR.into_response(), + }; + + let result = + db::catalog::set_object_fields(&mut tx, actor(&auth.user), object_id, &values).await; + + match result { + Ok(()) => { + if tx.commit().await.is_err() { + return StatusCode::INTERNAL_SERVER_ERROR.into_response(); + } + reindex(&state, object_id).await; + StatusCode::NO_CONTENT.into_response() + } + Err(db::catalog::FieldError::ObjectNotFound) => StatusCode::NOT_FOUND.into_response(), + Err(db::catalog::FieldError::Db(_)) => StatusCode::INTERNAL_SERVER_ERROR.into_response(), + Err(db::catalog::FieldError::UnknownField(field)) => ( + StatusCode::UNPROCESSABLE_ENTITY, + Json(FieldErrorView { field, code: "unknown".to_owned() }), + ) + .into_response(), + Err(db::catalog::FieldError::TypeMismatch { field, .. }) => ( + StatusCode::UNPROCESSABLE_ENTITY, + Json(FieldErrorView { field, code: "type_mismatch".to_owned() }), + ) + .into_response(), + Err(db::catalog::FieldError::Unresolved { field, .. }) => ( + StatusCode::UNPROCESSABLE_ENTITY, + Json(FieldErrorView { field, code: "unresolved".to_owned() }), + ) + .into_response(), + } +} +``` +Update the `#[utoipa::path(...)]` on `set_fields`: the 422 response now has a body — change/add `(status = 422, body = FieldErrorView, description = "A field was rejected")` in its `responses(...)`. + +- [ ] **Step 4:** Register `admin_objects::FieldErrorView` in `crates/api/src/openapi.rs` `components(schemas(...))`. + +- [ ] **Step 5: Test** — add to `crates/api/tests/admin_objects.rs` (reuse its harness: seed editor, login, create an object). Create an object, then PUT `/api/admin/objects/{id}/fields` with an **unknown** field key → assert `422` and the body `{ field: "", code: "unknown" }`. (Mirror an existing set-fields test if present; if a field-definition is needed for a type_mismatch case, the `unknown` case needs none — simplest.) Read the file for the exact request/parse helpers. + +- [ ] **Step 6: Build + backend tests:** +```bash +cargo +nightly fmt +cargo clippy --workspace --all-targets +DATABASE_URL=postgres://postgres:postgres@localhost:5442/cms_dev MEILI_URL=http://localhost:7700 MEILI_MASTER_KEY=masterKey cargo test -p api +``` +All green (existing set_fields tests still pass — success path still 204; the failure path now carries a body but the status is unchanged at 422). + +- [ ] **Step 7: Regenerate client:** +```bash +cargo build -p server +lsof -ti :8080 | xargs kill 2>/dev/null +DATABASE_URL=postgres://postgres:postgres@localhost:5442/cms_dev MEILI_URL=http://localhost:7700 MEILI_MASTER_KEY=masterKey ./target/debug/server & +SERVER_PID=$! +sleep 2 +( cd web && pnpm gen:api ) +kill "$SERVER_PID" +grep -n "FieldErrorView" web/src/api/schema.d.ts +# confirm SearchHitView.visibility now references the Visibility union: +grep -n "SearchHitView" web/src/api/schema.d.ts +``` +`FieldErrorView` present; `SearchHitView.visibility` → `components["schemas"]["Visibility"]`. `cd web && pnpm typecheck` clean. Diff additive. + +- [ ] **Step 8: Commit:** +```bash +cd /Users/olsson/Laboratory/biggus-dickus +git add crates/api web/src/api/schema.d.ts +git commit -m "feat(api): field-level set_fields 422 body (#28); enum-type SearchHitView.visibility (#38)" +``` + +--- + +## Task 2: Frontend — surface the rejected field & highlight it (#28) + +**Files:** Modify `web/src/api/queries.ts`, `web/src/objects/object-form.tsx`, `web/src/objects/object-new-page.tsx`, `web/src/objects/object-edit-form.tsx`, `web/src/i18n/{en,sv}.json`; Test `web/src/objects/object-form.test.tsx` or the relevant existing object test. + +- [ ] **Step 1: i18n** — add `form.fieldRejected` to BOTH `en.json` and `sv.json` (interpolated): + - en `form`: `"fieldRejected": "The field \"{{field}}\" was rejected — check its value"` + - sv `form`: `"fieldRejected": "Fältet \"{{field}}\" avvisades — kontrollera värdet"` + +- [ ] **Step 2: A typed rejection in `useSetFields`** — in `web/src/api/queries.ts`, add near the other errors: +```ts +export class FieldRejection extends Error { + constructor(public readonly field: string, public readonly code: string) { + super(`field rejected: ${field}`); + this.name = "FieldRejection"; + } +} +``` +Update `useSetFields`'s `mutationFn` to parse the 422 body and throw `FieldRejection`: +```ts + mutationFn: async ({ id, fields }: { id: string; fields: Record }) => { + const { response, error } = await api.PUT("/api/admin/objects/{id}/fields", { + params: { path: { id } }, + body: fields as Record, + }); + + if (response.status === 204) return; + + if (response.status === 422 && error && typeof error === "object" && "field" in error) { + const detail = error as { field: string; code: string }; + throw new FieldRejection(detail.field, detail.code); + } + + throw new Error("set fields failed"); + }, +``` +(openapi-fetch puts the 422 body in `error` because the operation declares a 422 body schema. If `error` typing is awkward, narrow defensively as above — no `any`.) + +- [ ] **Step 3: Thread a field-error into the form** — `object-form.tsx` owns the react-hook-form instance. Add an optional prop `fieldErrorKey?: string | null` and, via `useEffect`, set/clear the RHF error so the field highlights: +```tsx +// in the ObjectForm props type: + fieldErrorKey?: string | null; +// inside the component (form is the useForm instance; t available): + useEffect(() => { + if (fieldErrorKey) { + form.setError(`fields.${fieldErrorKey}` as never, { + type: "server", + message: t("form.fieldRejected", { field: fieldErrorKey }), + }); + } + }, [fieldErrorKey, form, t]); +``` +(The `as never` is to satisfy RHF's path typing for a dynamic flexible-field path; if a cleaner typed path is available without `any`, use it — `as never` is acceptable here and is NOT `as any`. Confirm lint accepts it; if `react-hooks/exhaustive-deps` complains, include the listed deps.) + +- [ ] **Step 4: Parent catch sets the field key** — in `object-new-page.tsx` and `object-edit-form.tsx`, the `catch` currently does `setError(t("form.rejected"))`. Capture the rejected field too: + - Add state `const [fieldErrorKey, setFieldErrorKey] = useState(null);` + - In the catch: `if (e instanceof FieldRejection) { setFieldErrorKey(e.field); setError(t("form.fieldRejected", { field: e.field })); } else { setError(t("form.rejected")); }` (import `FieldRejection` from `../api/queries`). + - Pass `fieldErrorKey={fieldErrorKey}` to ``. + - Clear `setFieldErrorKey(null)` at the top of `onSubmit` (alongside `setError(null)`). + (For `object-edit-form.tsx`, which also reads a `location.state.fieldsError` flag, keep that path but layer the new typed handling on top.) + +- [ ] **Step 5: Test** — add a test (in the object form/new-page test file, MSW) where PUT `/api/admin/objects/:id/fields` returns `422` with `{ field: "dimensions", code: "type_mismatch" }`. Submit the form; assert the field-rejected message appears (`/dimensions/i` + "rejected") and, if practical, that the field's input is marked invalid (`aria-invalid` or an error message near it). Use the existing object-form test setup; read it for the render/submit pattern. + +- [ ] **Step 6: Verify + commit:** +```bash +cd web && pnpm test && pnpm typecheck && pnpm lint && pnpm build && pnpm check:size +cd /Users/olsson/Laboratory/biggus-dickus +git add web +git commit -m "feat(web): highlight the offending field on a set_fields 422 (#28)" +``` + +--- + +## Task 3: Frontend — visibility-badge typing (#38) + localized_text normalize-on-save (#41) + +**Files:** Modify `web/src/objects/visibility-badge.tsx`, `web/src/objects/object-form.tsx`; Test the object-form/field tests. + +### #38 — tighten the VisibilityBadge prop +- [ ] **Step 1:** `web/src/objects/visibility-badge.tsx` — change the prop from `string` to the schema union (now that all callers pass it, incl. search hits after Task 1): +```tsx +import type { components } from "../api/schema"; + +type Visibility = components["schemas"]["Visibility"]; + +export function VisibilityBadge({ visibility }: { visibility: Visibility }) { + const { t } = useTranslation(); + return ( + + {t(`visibility.${visibility}`)} + + ); +} +``` +Run `pnpm typecheck` — every caller (`object-list`, `object-detail`, `search-result-row`) now passes the union (object/search hit `visibility` are the union post-#29/#38). Fix any caller that still has a widened `string` (there should be none). + +### #41 — normalize localized_text to the default language on save +The edit path seeds `defaultValues.fields` from `object.fields` verbatim, so a `localized_text` value authored under another language keeps that key. Normalize in `pruneFields` so only the default-language key is saved. + +- [ ] **Step 2:** In `web/src/objects/object-form.tsx`: + - Add `import { useConfig } from "../config/config-context";` and inside the component: `const { default_language } = useConfig();`. + - Compute the set of localized_text field keys from the loaded definitions: + ```tsx + const localizedTextKeys = new Set( + (definitions ?? []).filter((d) => d.data_type === "localized_text").map((d) => d.key), + ); + ``` + - Pass both into `pruneFields` at its call site (`const fields = pruneFields(data.fields, localizedTextKeys, default_language);`). + - Update `pruneFields` to accept them and, for a localized_text key, keep only the default-language sub-value: + ```tsx + function pruneFields( + fields: Record, + localizedTextKeys: Set, + defaultLang: string, + ): Record { + const out: Record = {}; + + for (const [key, value] of Object.entries(fields)) { + if (value === undefined || value === null || value === "") continue; + + if (typeof value === "object" && !Array.isArray(value)) { + const map = value as Record; + // Single-language authoring: a localized_text value keeps only the default lang. + const entries = localizedTextKeys.has(key) + ? Object.entries(map).filter(([lang]) => lang === defaultLang) + : Object.entries(map); + + const inner = Object.fromEntries( + entries.filter(([, v]) => v !== undefined && v !== null && v !== ""), + ); + + if (Object.keys(inner).length > 0) out[key] = inner; + + continue; + } + + out[key] = value; + } + + return out; + } + ``` + +- [ ] **Step 3: Test** — add/extend a test: an object whose `localized_text` field value is `{ en: "Old", sv: "Ny" }`, edited on an `sv`-default instance, submits `fields` containing only `{ : { sv: "Ny" } }` (the `en` key stripped). Use the object-form test harness (the `definitions` fixture has a `localized_text` field — `title_ml`). Assert the pruned payload via the submit handler / the PUT body. + +- [ ] **Step 4: Verify + commit:** +```bash +cd web && pnpm test && pnpm typecheck && pnpm lint && pnpm build && pnpm check:size +cd /Users/olsson/Laboratory/biggus-dickus +git add web +git commit -m "fix(web): VisibilityBadge typed to the union (#38); normalize localized_text to default language on save (#41)" +``` + +--- + +## Task 4: Pin pnpm (#26) + verification + +**Files:** Modify `web/package.json`, `.gitea/workflows/ci.yaml`. + +- [ ] **Step 1: Pin pnpm** — add a `packageManager` field to `web/package.json` matching the dev/CI version. The local pnpm is `11.5.1`; CI's `pnpm/action-setup` is pinned to `9` — a mismatch. Unify on the local version: + - In `web/package.json`, add (top level): `"packageManager": "pnpm@11.5.1"`. + - In `.gitea/workflows/ci.yaml`, change the `pnpm/action-setup@v4` `version: 9` → `version: 11` (matching the major). +- [ ] **Step 2: Confirm the lockfile is consistent** — run `cd web && pnpm install --frozen-lockfile`. If it passes, the committed `pnpm-lock.yaml` is compatible — done. If it FAILS (lockfile format/version mismatch from the pnpm-9→11 change), run `pnpm install` once to update the lockfile, confirm only the lockfile changed (`git status`), and include `web/pnpm-lock.yaml` in the commit. Report which case occurred. +- [ ] **Step 3: Commit:** +```bash +cd /Users/olsson/Laboratory/biggus-dickus +git add web/package.json .gitea/workflows/ci.yaml web/pnpm-lock.yaml +git commit -m "build(web): pin pnpm via packageManager + align CI (#26)" +``` + +### Final verification +- [ ] **Step 4: i18n parity** — +```bash +cd web +node -e "const a=require('./src/i18n/en.json'),b=require('./src/i18n/sv.json');const k=o=>Object.entries(o).flatMap(([K,v])=>typeof v==='object'?k(v).map(s=>K+'.'+s):[K]);const ka=k(a).sort(),kb=k(b).sort();console.log(JSON.stringify(ka)===JSON.stringify(kb)?'PARITY OK':'MISMATCH '+JSON.stringify({onlyEn:ka.filter(x=>!kb.includes(x)),onlySv:kb.filter(x=>!ka.includes(x))}))" +``` +Expected `PARITY OK`. +- [ ] **Step 5: Full suites** — +```bash +cd web && pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm check:size +cd /Users/olsson/Laboratory/biggus-dickus +DATABASE_URL=postgres://postgres:postgres@localhost:5442/cms_dev MEILI_URL=http://localhost:7700 MEILI_MASTER_KEY=masterKey cargo test --workspace +cargo clippy --workspace --all-targets && cargo +nightly fmt --check +``` +All green; bundle ≤150 KB; clippy/fmt clean. +- [ ] **Step 6:** `git grep -in 'biggus\|dickus' -- crates web/src` → none. + +--- + +## Self-Review (completed) +- **Spec coverage:** #38 (search visibility enum → T1 backend + T3 prop tighten); #28 (422 field body → T1 backend, T2 FE highlight); #41 (localized_text normalize → T3); #26 (pin pnpm → T4). ✓ +- **Placeholder scan:** none — concrete code; the "read the test harness" notes are verification steps against named files. The `as never` in T2 Step 3 is a typed-RHF-path escape (NOT `as any`/ts-ignore) and is flagged for lint confirmation. +- **Type consistency:** `FieldErrorView { field, code }` (Rust) ↔ `components["schemas"]["FieldErrorView"]` (the 422 body openapi-fetch surfaces as `error`) ↔ `FieldRejection{field,code}`; `SearchHitView.visibility` union flows into the tightened `VisibilityBadge` prop; `pruneFields` new signature `(fields, localizedTextKeys, defaultLang)` updated at its single call site. + +## Notes +- #28 changes the `set_fields` handler return type from `Result` to `Response`; the success status (204) and the field-error status (422) are unchanged — only a body is added to the 422, so existing status-only tests still pass. +- #26: if `pnpm install --frozen-lockfile` forces a lockfile regen, that's expected and the regenerated `pnpm-lock.yaml` is committed; flag if dependency versions shifted.