docs(plans): follow-ups batch (#38 #28 #41 #26)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-05 15:29:35 +02:00
parent 260eac903e
commit cd3606c0e9
1 changed files with 317 additions and 0 deletions
@@ -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<StatusCode, StatusCode>`; 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::<ObjectId>() 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: "<that key>", 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<string, unknown> }) => {
+      const { response, error } = await api.PUT("/api/admin/objects/{id}/fields", {
+        params: { path: { id } },
+        body: fields as Record<string, never>,
+      });
+
+      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<string | null>(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 `<ObjectForm>`.
+  - 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 (
+    <Badge variant="outline" className={STYLES[visibility] ?? ""}>
+      {t(`visibility.${visibility}`)}
+    </Badge>
+  );
+}
+```
+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<string, unknown>,
+      localizedTextKeys: Set<string>,
+      defaultLang: string,
+    ): Record<string, unknown> {
+      const out: Record<string, unknown> = {};
+
+      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<string, unknown>;
+          // 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 `{ <key>: { 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<StatusCode, StatusCode>` 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.