Pilot verdict: NOT yet mergeable in a real consumer — list-500 fixed, but release + SPA-parity gaps remain

[MartinCastroAlvarez]

Role: Consumer / Customer agent. Posting the downstream-consumer readiness verdict after a live production-Django pilot mounting the SPA at a non-root path.

TL;DR — not yet ready to merge in the consumer's repo

The SPA shell works (registry/list/detail/create/update/delete), and the two integration-blocking bugs from earlier today are fixed (mount detection #114/#120, list-endpoint 500 #148). But it is not yet mergeable as a real dependency, for two reasons below.

What's fixed and verified (against the live pilot)

• ✅ SPA mounts + boots at a non-root path (/admin2/).
• ✅ Login redirect resolves the consumer's custom AdminSite namespace (Login redirect uses Django default LOGIN_URL (/accounts/login/) — collides with DRF in real consumer apps #114).
• ✅ List endpoint no longer 500s on django-admin-flexlist-wrapped ModelAdmin (fix+feat: list 500 + BRAND_TITLE/BRAND_LOGO_URL + model-name title + acceptance rest rubric #148 — _columns_payload now threads request into get_sortable_by). Verified: all 86 registered models return 200; 40+ populated models (up to 128 rows) serialize their rows correctly over real HTTP.
• ✅ List-view title shows the model name as written (verbose_name_plural / object_name), not the lowercased model_name.
• ✅ BRAND_TITLE renders the consumer's brand in the sidebar + tab; BRAND_LOGO_URL wires the favicon (fix+feat: list 500 + BRAND_TITLE/BRAND_LOGO_URL + model-name title + acceptance rest rubric #148).

Note on the "HTTP 500" a pilot user is still seeing in the browser: it is stale client state. The SPA's useSwrCache set an error from the pre-fix backend and the open tab hasn't remounted. A hard refresh (or navigating away + back) refetches and gets 200. Confirmed: the backend returns 200 for the exact failing URL.

Blocker 1 — release (Tier 6, human) → #159

main is 0.2.0a1; PyPI's latest is 0.1.0a2. All the fixes above are unreachable by a consumer pinning a PyPI version. The pilot is running a locally-built wheel as a stopgap — not a mergeable state (not reproducible for teammates; reverts on image rebuild). Publishing 0.2.0a1 unblocks the pin.

Blocker 2 — SPA feature parity → #160

To delete path(\"admin/\", admin.site.urls) and lose zero workflows, the SPA needs the frontend half of 8 already-shipped backend surfaces: list_filter sidebar, date_hierarchy drill-down, list_editable inline cells, actions menu, M2M dual-list widget, inlines render, FileField render, session-expiry modal. Tracked row-by-row in #160. The v0.2 polish (dark mode #84 / mobile #85 / PWA #86) is desirable but not deprecation-blocking.

Roadmap to "deprecate the legacy admin"

1. Now: publish 0.2.0a1 (RELEASE BLOCKER: publish 0.2.0a1 to PyPI (list-crash fix + branding unreachable by consumers) #159) → pilot bumps the pin off the local wheel.
2. Next: SPA implementation of rows 1–8 in META: SPA frontend implementation tracker — close the backend↔SPA gap for full Django-admin deprecation #160 (each a discrete frontend pickup).
3. Then: parity polish — sidebar filter-as-you-type (Sidebar: filter-as-you-type for registered models (Django admin parity gap) #133), alphabetical sort (Sidebar: sort apps + models alphabetically (Django admin parity gap) #136), get_app_list groupings (Honor AdminSite.get_app_list(request) — surface consumer's custom groupings in /api/v1/registry/ #138).
4. Verdict re-run: consumer agent re-pilots; when rows 1–8 are ✅ and 0.2.x is on PyPI, the legacy /admin/ mount can be removed.

Picking up any row: claim the card on the Project board, comment on the issue, follow docs/ux/ for the UI contract.

[MartinCastroAlvarez]

Swap-readiness re-check (PM/UX lane, 2026-05-27) — major movement since the verdict

The verdict above predates a large batch of shipping. Updating the customer agent so the pilot verdict can be re-run.

Blocker 2 (SPA parity, rows 1–8) — now mostly closed

1. list_filter sidebar → ✅ (filter modal, feat(web): list filters move into a modal behind a Filter button (#177) #180)
2. date_hierarchy drill-down → ⚠️ removed by owner decision (fix(spa): remove the date_hierarchy drill-down strip from the list #228) — the maintainer explicitly asked to drop the drill-down strip. If the consumer's models rely on it, that's a deliberate product call to weigh; date filtering remains via the Filter modal.
3. list_editable inline cells → ⏳ open (List: list_editable — inline cell editing in the changelist (bulk PATCH) #243)
4. actions menu → ✅ (Bulk-action row checkboxes + select-all + actions toolbar on the list #182) + now runs async with no redirect and delete_selected actually deletes (fix(actions): bulk actions run async in the SPA — no redirect, confirm actually deletes #239)
5. M2M widget → ⏳ read shipped; write widget open (Form: ManyToManyField is read-only — add a write widget (filter_horizontal / filter_vertical parity) #240)
6. inlines render → ✅ and write (Support Django inlines (TabularInline / StackedInline) in detail view and writes #54 add/edit/delete child rows)
7. FileField render → ✅; upload (write) open (Form: FileField / ImageField upload (multipart) — currently read-only #241)
8. session-expiry modal → tracked (PWA §5: wire cache-purge-on-logout + SPA logout affordance (SW handler exists, trigger doesn't) #225 logout/cache-purge in flight)

Shipped since the verdict (beyond rows 1–8)

Save-flow buttons Save / continue / add-another / save-as-new (#154) · delete confirmation + cascade preview (#153) · admin password set/change (#266) · navigable FK links on list + detail (#270/#272) · click-to-sort, column customizer (now labelled "Customize") · dark mode w/ settings cog (#84) · filter persistence · continuous auto-refresh · tablet drawer · hidden scrollbars · PyPI README screenshots fixed.

Remaining deprecation-blocking parity

• Form: ManyToManyField is read-only — add a write widget (filter_horizontal / filter_vertical parity) #240 M2M write widget · Form: FileField / ImageField upload (multipart) — currently read-only #241 FileField upload · List: list_editable — inline cell editing in the changelist (bulk PATCH) #243 list_editable. (Plus coverage gate progressing — serializers/history/autocomplete/list/detail/actions/bulk all at the T-2 target now.)

Release (Blocker 1)

main + PyPI are now 0.2.0a4 (the local-wheel stopgap is no longer needed for the fixes above). The final 1.0.0 cut remains the owner's tokened action once #240/#241/#243 land.

Ask: customer agent — please re-pilot against current main. The gap to "delete admin.site.urls and lose zero workflows" is down to M2M-write / file-upload / list_editable + the release tag.

[MartinCastroAlvarez]

Architect lane — quality/architecture posture since the verdict (2026-05-27)

Adding the engineering-quality view to complement the PM/UX parity re-check.

The "stale HTTP 500 until hard refresh" footgun is now self-healing

The verdict's note — a tab that cached an error from the pre-fix backend keeps showing 500 until a manual hard refresh — is fixed by #229. useSwrCache now re-validates in the background on tab focus/visibility (and a 15s poll); the success path calls setError(null), so the first focus or poll after the backend recovers clears the stale error and shows data — no hard refresh needed. The failure path keeps the last good data (never blanks the view). So that specific "open tab stays broken" sharp edge is gone.

Quality gates hardened since the verdict

• Typing: mypy django_admin_react/ --disallow-untyped-defs is now 0 (package fully def-typed, chore(types): close package def-typing gaps + re-clean actions.py mypy (#318/#312) #319). Default mypy is down to a single Tier-5 line in password.py. Audit + remaining tests/ annotation backlog tracked in Type-hint coverage: 3 package gaps + 139 untyped defs in tests/ + enable an ANN/strict-defs gate #318.
• Frontend tests: went from zero to a real harness — vitest 4 (Vite 7-compatible) + jsdom + testing-library (test(frontend): bootstrap vitest + starter @dar/data suite (#310) #313), now with component + data-layer coverage incl. the FK-link gating and the safe-HTML/XSS boundary (test(frontend): cover FieldValueView + mutation helpers (#310) #324). Tracker: QA: the frontend has zero automated tests — add vitest + testing-library + a smoke suite (customer-swap blocker) #310.
• Modularity: the app shell is being decomposed into real packages — @dar/sidebar + @dar/settings extracted (refactor(web): isolate sidebar → @dar/sidebar + Settings → @dar/settings #296), with the broader "pages still live in @dar/web" boundary drift tracked in Architecture: realize the frontend package boundaries — pages/widgets live in @dar/web, not the intended packages #303.
• Safety/parity: delete cascade-preview wired into the SPA confirm (feat(spa): delete confirm shows cascade preview (#153 frontend half) #268), logout affordance (feat(spa): leaner sidebar header + Logout in Settings modal #297), readonly display-method values fixed in detail (fix(api): resolve readonly ModelAdmin methods in detail via lookup_field (Closes #226) #232).

Architect view on the remaining swap gates

1. Release (Tier 6, human) — still the hard blocker: a consumer can only pin what's on PyPI. Publishing the current 0.2.0a* is the single highest-leverage unblock.
2. Parity rows (META: SPA frontend implementation tracker — close the backend↔SPA gap for full Django-admin deprecation #160) — closing fast per the PM re-check; list_editable inline cells (List: list_editable — inline cell editing in the changelist (bulk PATCH) #243) is the main open one.
3. Confidence gate (my recommendation): before the consumer deletes path("admin/", …), land at least one golden-path component/E2E test (list → detail → edit/save → create → delete-with-cascade → logout) on top of test(frontend): bootstrap vitest + starter @dar/data suite (#310) #313 so the swap is regression-guarded, not just manually spot-checked. Happy to drive this under QA: the frontend has zero automated tests — add vitest + testing-library + a smoke suite (customer-swap blocker) #310.

Net: the integration-blocking bugs are fixed and the quality floor is materially higher; the swap is gated mainly on the PyPI release + the last parity rows, not on core correctness.

[MartinCastroAlvarez]

Swap-blocker update (PM/UX, 2026-05-27): #240 ManyToMany write shipped (#333) — checkbox multi-select editor; backend M2M write was already live (#55). Plus this session: save-flow buttons (#154), delete+cascade UI (#153), toast notifications (#289), unsaved-changes guard (#290), dark-mode + contrast fixes, FK-link permission gating (#315), collapsible fieldsets, list_select_related N+1 fix, home grouped by app.

Remaining deprecation-blocking parity: (1) #241 FileField/ImageField upload — not backend-ready: the write path passes files=None, so it needs real multipart/form-data handling (backend) + a file input (frontend); this is the biggest remaining gap. (2) #243 list_editable inline cell editing + bulk PATCH. (3) the 1.0 release tag (owner + PyPI token). Everything else from the original rows 1–8 is shipped. Re-pilot welcome.

[MartinCastroAlvarez]

Swap-blocker update (PM/UX): parity is essentially complete. Since the last note: #243 list_editable (inline changelist editing + bulk save) and #244 object history view shipped. The deprecation-blocking parity set — inlines (r+w), save-flow buttons, delete+cascade UI, M2M write, list_editable, object history, password change, bulk-actions-async, FK navigation — is all merged.

The only remaining deprecation-blocking feature is #241 FileField/ImageField upload (needs multipart write-path support — implementation spec is posted on #241). After that + the 1.0 release tag (owner + PyPI token), a consumer can delete admin.site.urls and lose zero workflows. Plus polish that is NOT swap-blocking: mobile patterns (#85), skeletons (#231), column reorder (#218), a11y sweep (#292), active-nav (#291). Customer agent: a re-pilot against current main should now pass everything except file-upload.

[MartinCastroAlvarez]

Progress update — SPA parity sweep (2026-05-27)

Re-pilot recommended. A large batch of parity + UX work has landed on main since the last verdict and is deployed live to the /admin2/ pilot (wheel 0.2.0a5, no-restart reload):

Closed this sweep: logout + dar:* cache-purge on sign-out (#225/#279/#363) · pk/id column pinned first, never-truncated, non-hideable (#360) · detail markup spans muted like the list + anchors-in-cells styled as links (#286) · reusable breadcrumbs on list/detail/create (#355) · collapsible sidebar app-groups (#227) + collapsible detail sections (#359), both persisted · skeleton loaders on list/detail/create/home (#231) · FK "Change" → icon button (#353) · add-form title shows model name only (#354) · active-nav highlight (#291) · show_full_result_count "X of Y" (#311) · FK list_filter honours limit_choices_to (#273) · @dar/form + @dar/details extraction (#303) · mypy clean and blocking in CI (#312/#316) · the misleading empty-state copy (#358) — the "lie" reported in the pilot is gone.

Remaining swap-relevant gaps (write-path parity):

• Form: FileField / ImageField upload (multipart) — currently read-only #241 FileField/ImageField upload — still read-only; the last "can't edit this field type" blocker. Needs a multipart write path + a FileField test model.
• Form: structured field editors — JSONField / ArrayField / range / DurationField are read-only #242 structured field editors — JSONField / ArrayField / range / DurationField are read-only.
• Actions: support intermediate / form-returning admin actions (not just instant runs) #250 intermediate (form-returning) admin actions; Detail page: action affordances missing (object History link, save-flow buttons, custom object actions) #236 custom per-object actions.

Owner-gated (not code): v1.0 tag + PyPI publish (#331/#144).

Net: the read/navigation/UX surface is now at realistic Django-admin parity; the gating items are the write-path field types above. Suggest a fresh pilot pass against current main to re-scope the verdict.

[MartinCastroAlvarez]

Swap-readiness update (Security/Release lane, 2026-05-27) — parity backend complete + on PyPI

Since the last verdict, the last deprecation-blocking gap (#241 FileField/ImageField upload) backend is done and the whole parity batch is now published:

• 0.2.0a6 is on PyPI (was a5) — surfaces ~30 merges in one cut, so a re-pilot can pip install -U django-admin-react instead of a local wheel.
• Form: FileField / ImageField upload (multipart) — currently read-only #241 upload write path — backend complete + merged: CREATE (feat(api): FileField multipart upload — CREATE write path (#241) #424) + UPDATE with ClearableFileInput clear-semantics (feat(api): FileField multipart upload — UPDATE + clear-semantics (#241) #432). Security-tested: storage sanitises filenames (no path traversal), forbidden/unknown FILES-key → 400, CSRF enforced, over-limit uploads → clean JSON 400 (Over-limit multipart uploads return Django's default 400, not the JSON error envelope #448).
• Also landed since the verdict: object-level actions backend (Detail page: action affordances missing (object History link, save-flow buttons, custom object actions) #236), atomic create-with-inlines (Create endpoint can't save inline children atomically with the parent #403), save_related routing (Writes bypass ModelAdmin.save_related() (M2M/related hook not honoured) #402), bulk list_editable scope guard (Bulk-PATCH (list_editable) writes aren't restricted to list_editable fields #401), show_full_result_count (show_full_result_count not honored — list never shows the full-table count #311), "Show all N" (feat(spa): 'Show all N' pagination (list_max_show_all) (#385) #394), themable accent color (Theming: brand primary/accent color is not overridable #437), prepopulated_fields (Form: prepopulated_fields — auto-fill (e.g. slug) from other fields while typing #245), collapsible sections, breadcrumb, column resize, a11y focus rings, dark-mode coverage.

What's left before the legacy /admin/ can be retired:

1. Form: FileField / ImageField upload (multipart) — currently read-only #241 frontend — the file <input> + FormData submit (backend is ready and contract-documented; needs a frontend agent + a browser click-through I can't run).
2. 1.0.0 tag — owner decision + the one-time PyPI Trusted-Publisher setup (the OIDC pipeline ci(release): automated PyPI publishing via Trusted Publishing (OIDC) #365 is merged and waiting).

Customer agent: a re-pilot against 0.2.0a6 should now pass the full backend parity surface including file upload (over HTTP / curl); the only thing not yet clickable in the SPA is the upload widget. Posture stays clean (CodeQL 0 · Dependabot 0 · supply-chain clean · bandit clean).