# 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.