diff --git a/.planning/phases/38-admin-tag-management/38-RESEARCH.md b/.planning/phases/38-admin-tag-management/38-RESEARCH.md new file mode 100644 index 0000000..03ab771 --- /dev/null +++ b/.planning/phases/38-admin-tag-management/38-RESEARCH.md @@ -0,0 +1,640 @@ +# Phase 38: Admin — Tag Management - Research + +**Researched:** 2026-04-19 +**Domain:** Full-stack CRUD with hierarchical data (self-referential FK), admin panel patterns, cycle detection +**Confidence:** HIGH + +## Summary + +Phase 38 is entirely additive on top of well-established Phase 36/37 admin infrastructure. The codebase already has tags (`id`, `name`, `createdAt`), a service (`getAllTags`), a route (`GET /api/tags`), a hook (`useTags`), and a disabled "Tags" sidebar entry in the admin shell. The phase adds a `parentId` FK to the schema, builds admin CRUD routes under `/api/admin/tags`, and adds two client routes (`/admin/tags` list + `/admin/tags/$tagId` edit). Every pattern needed — service layer, Hono route module, React Query admin hooks, edit page structure, delete confirmation dialog — was established in Phase 37 for global items and can be followed directly. + +The only genuinely new technical concern is hierarchy management: building a flat-to-tree transformation for the list view, a recursive descendant collector for parent-picker filtering and cycle detection, and the server-side cycle guard. All of these are straightforward pure functions operating on the in-memory tag array — no recursive SQL CTEs are required because the tag count is small and the full list fits easily in a single query result. + +The `parentId` Drizzle self-referential FK uses a deferred lambda `() => tags.id` to handle the forward reference. Migration follows the same single-ALTER pattern as the `is_admin` migration from Phase 36. The `ON DELETE SET NULL` semantic is already supported by Drizzle's FK options and does not need custom code. + +**Primary recommendation:** Follow Phase 37 patterns exactly. The only new logic is tree flattening (list view) and cycle detection (service + client parent picker). Keep the tree component as pure local state — no Zustand needed. + +--- + + +## User Constraints (from CONTEXT.md) + +### Locked Decisions + +- **D-01:** Add `parentId integer REFERENCES tags(id) ON DELETE SET NULL NULLABLE` to the `tags` table via Drizzle migration. Self-referential FK — no depth limit at the schema level. +- **D-02:** On parent deletion, `ON DELETE SET NULL` orphans children (they become top-level). No cascading child deletion. +- **D-03:** Collapsible tree view (not a flat table). Parent tags render rows; children are indented below. All nodes start expanded on page load. +- **D-04:** Columns: Name (with indent level visual) | Item Count | Actions. +- **D-05:** Search/filter mode: filter in-tree — non-matching rows are hidden in place. Parents with matching children remain visible; non-matching leaf nodes are hidden. +- **D-06:** No separate "Children Count" column — children are visible in the tree structure below each parent. +- **D-07:** Quick-add form at the top of the tag list (not a separate page). Fields: name + optional parent picker. Submits inline without navigation. +- **D-08:** Dedicated edit page at `/admin/tags/$tagId` — consistent with Phase 37 item edit pattern. Fields: name + parent picker. +- **D-09:** Delete lives on the edit page (not the list), following Phase 37 D-05. +- **D-10:** Arbitrary depth — any tag can be a parent of any other (no 1-level limit). Future-proofed for deep taxonomies. +- **D-11:** Cycle prevention is dual-layer: + - **Client**: Parent picker filters out the tag's own descendants from the dropdown options. + - **Server**: API validates that the new parent is not a descendant of the tag being updated. Returns 400 with a clear error message if a cycle is detected. +- **D-12:** Deleting a tag orphans its children — they become top-level tags (`parentId` SET NULL via FK cascade). +- **D-13:** Delete confirmation dialog shows: item count + child count warning. Example: "Delete 'sleeping-bag'? 12 items use this tag. Its 3 child tags will become top-level. This cannot be undone." +- **D-14:** If a tag has 0 items and 0 children, the confirmation is simplified: "Delete 'sleeping-bag'? This cannot be undone." + +### Claude's Discretion + +- Exact visual styling of tree indentation (border-left line, chevron icon, or indent padding) +- Whether to use a chevron toggle button or click-to-collapse on the row +- Implementation of the collapsible tree (local component state vs. Zustand) +- Exact error message copy for cycle detection rejection +- Whether to add a "Move to top-level" shortcut on the edit page in addition to the parent picker + +### Deferred Ideas (OUT OF SCOPE) + +- Drag-to-reparent +- Bulk operations (bulk delete, bulk reparent) +- Tag merge +- Tag usage analytics + + +--- + + +## Phase Requirements + +| ID | Description | Research Support | +|----|-------------|------------------| +| ADMN-05 | Admin can browse all tags with item counts and parent/child relationships displayed | Tree list view with `getAdminTags` service returning `parentId`, `itemCount`, `childCount` | +| ADMN-06 | Admin can create a new tag with a name | Quick-add form at top of list; `POST /api/admin/tags` → `createTag` service | +| ADMN-07 | Admin can rename an existing tag | Edit page form; `PUT /api/admin/tags/:id` → `updateTag` service | +| ADMN-08 | Admin can assign a parent tag to a tag (enabling sub-tag hierarchy) | Parent picker on edit page; `parentId` FK in schema; cycle detection in service | +| ADMN-09 | Admin can remove a tag's parent assignment (making it top-level again) | Parent picker allows null selection; `PUT /api/admin/tags/:id` with `parentId: null` | +| ADMN-10 | Admin can delete a tag, with a warning if items are currently using it | Delete button on edit page; confirmation dialog showing item count + child count | + + +--- + +## Architectural Responsibility Map + +| Capability | Primary Tier | Secondary Tier | Rationale | +|------------|-------------|----------------|-----------| +| Tag CRUD persistence | API / Backend (`tag.service.ts`) | Database (Drizzle) | Business logic and data validation live in the service layer | +| Cycle detection (authoritative) | API / Backend (`tag.service.ts`) | — | Server is the authority; client filter is UX-only | +| Tree data assembly (flat → tree) | API / Backend (optional) or Frontend | — | Tag count is small; flat array with parentId is sufficient; client transforms | +| Collapsible tree rendering | Browser / Client | — | Pure UI state — local React state, no server involvement | +| Parent picker descendant filtering | Browser / Client | — | Derived from full tag list already in React Query cache | +| Admin auth guard | API / Backend (`requireAdmin` middleware) | Frontend (redirect in admin shell) | Server is authoritative; client redirect is UX convenience | + +--- + +## Standard Stack + +### Core (verified from codebase) + +| Library | Version | Purpose | Why Standard | +|---------|---------|---------|--------------| +| Drizzle ORM | (project version) | Schema definition + migrations + query builder | Already used throughout project | +| Hono | (project version) | HTTP route handlers | Existing admin routes pattern | +| `@hono/zod-validator` | (project version) | Request body validation | Used in `admin-items.ts` | +| Zod | (project version) | Schema definitions | Used in all admin route validators | +| TanStack React Query | (project version) | Server state, mutations, cache invalidation | Used in all admin hooks | +| TanStack Router | (project version) | File-based routing, `createFileRoute` | Used for all client pages | +| Tailwind CSS v4 | v4 | Styling | Project standard | +| bun:test | Bun 1.3.9 | Test runner | Verified — `bun test` works | + +### Supporting + +| Library | Version | Purpose | When to Use | +|---------|---------|---------|-------------| +| PGlite (`@electric-sql/pglite`) | (project version) | In-memory PostgreSQL for tests | `createTestDb()` in `tests/helpers/db.ts` | + +**Installation:** No new packages required — all dependencies exist in the project. + +--- + +## Architecture Patterns + +### System Architecture Diagram + +``` +Admin browser + │ + ├── GET /admin/tags → AdminTagsPage (list) + │ │ + │ ├── useAdminTags() → GET /api/admin/tags + │ │ └── getAdminTags(db) → SELECT tags + item counts + │ │ + │ ├── flat array → buildTree() → TagTree component + │ │ └── local expand/collapse state + │ │ + │ └── QuickAddForm → useCreateAdminTag() → POST /api/admin/tags + │ + └── GET /admin/tags/:tagId → AdminTagEditPage (edit) + │ + ├── useAdminTag(id) → GET /api/admin/tags/:id + │ + ├── Save form → useUpdateAdminTag() → PUT /api/admin/tags/:id + │ └── server: isDescendant() cycle check → 400 if cycle + │ + └── Delete → useDeleteAdminTag() → DELETE /api/admin/tags/:id + └── DB: parentId SET NULL (FK cascade) on children +``` + +### Recommended Project Structure + +New files to create: + +``` +src/ +├── server/ +│ ├── routes/ +│ │ └── admin-tags.ts # CRUD handlers for /api/admin/tags +│ └── services/ +│ └── tag.service.ts # Extend existing file with CRUD + cycle detection +├── client/ +│ ├── hooks/ +│ │ └── useAdminTags.ts # Admin tag hooks (mirrors useAdminGlobalItems pattern) +│ └── routes/ +│ └── admin/ +│ ├── tags.tsx # List page with tree view + quick-add +│ └── tags.$tagId.tsx # Edit page with rename + reparent + delete +``` + +Files to modify: + +``` +src/db/schema.ts # Add parentId to tags table +src/server/routes/admin.ts # Register adminTagRoutes +src/client/routes/admin.tsx # Enable "Tags" sidebar link +``` + +### Pattern 1: Self-Referential FK in Drizzle (PostgreSQL) + +**What:** The `tags` table references itself via `parentId`. Drizzle requires a deferred lambda to handle the forward reference. + +**When to use:** Any time a table references its own primary key. + +```typescript +// Source: [VERIFIED: existing codebase pattern at globalItemTags, onDelete cascade] +// Adapted for self-referential nullable FK + +export const tags = pgTable("tags", { + id: serial("id").primaryKey(), + name: text("name").notNull().unique(), + parentId: integer("parent_id").references(() => tags.id, { onDelete: "set null" }), + createdAt: timestamp("created_at").defaultNow().notNull(), +}); +``` + +**Migration generated:** Single ALTER statement, same as Phase 36's `is_admin` migration: +```sql +ALTER TABLE "tags" ADD COLUMN "parent_id" integer REFERENCES "tags"("id") ON DELETE SET NULL; +``` + +### Pattern 2: Admin Service Functions (tag.service.ts extensions) + +**What:** Extend existing `tag.service.ts` with CRUD + aggregate queries. + +```typescript +// Source: [VERIFIED: adapted from global-item.service.ts pattern in codebase] + +// Returns flat array; client builds tree +export async function getAdminTags(db: Db) { + const result = await db + .select({ + id: tags.id, + name: tags.name, + parentId: tags.parentId, + itemCount: count(globalItemTags.globalItemId), + }) + .from(tags) + .leftJoin(globalItemTags, eq(globalItemTags.tagId, tags.id)) + .groupBy(tags.id, tags.name, tags.parentId) + .orderBy(asc(tags.name)); + return result; +} + +export async function getTagWithCounts(db: Db, id: number) { + const [tag] = await db + .select({ + id: tags.id, + name: tags.name, + parentId: tags.parentId, + itemCount: count(globalItemTags.globalItemId), + }) + .from(tags) + .leftJoin(globalItemTags, eq(globalItemTags.tagId, tags.id)) + .where(eq(tags.id, id)) + .groupBy(tags.id, tags.name, tags.parentId); + return tag ?? null; +} + +// childCount is computed client-side from getAdminTags flat array +// (cheaper than a correlated subquery for small tag sets) +``` + +### Pattern 3: Cycle Detection (Server) + +**What:** Before updating `parentId`, verify that the new parent is not a descendant of the tag being updated. Operates on the full flat tag array fetched from DB. + +```typescript +// Source: [ASSUMED — standard tree algorithm, not library-specific] + +function isDescendant( + allTags: { id: number; parentId: number | null }[], + candidateParentId: number, + tagId: number +): boolean { + // Walk up the ancestor chain of candidateParentId + // If we encounter tagId, there's a cycle + let current: number | null = candidateParentId; + const visited = new Set(); + while (current !== null) { + if (current === tagId) return true; + if (visited.has(current)) break; // safety: existing cycle in data + visited.add(current); + const node = allTags.find((t) => t.id === current); + current = node?.parentId ?? null; + } + return false; +} +``` + +### Pattern 4: Admin Route Module (admin-tags.ts) + +**What:** Hono route module following the same structure as `admin-items.ts`. + +```typescript +// Source: [VERIFIED: adapted from src/server/routes/admin-items.ts] + +import { zValidator } from "@hono/zod-validator"; +import { Hono } from "hono"; +import { z } from "zod"; +import { parseId } from "../lib/params.ts"; +import { createTag, deleteTag, getAdminTags, getTagWithCounts, updateTag } from "../services/tag.service.ts"; + +type Env = { Variables: { db?: any; userId?: number } }; +const app = new Hono(); + +const createTagSchema = z.object({ + name: z.string().min(1), + parentId: z.number().int().positive().nullable().optional(), +}); + +const updateTagSchema = z.object({ + name: z.string().min(1).optional(), + parentId: z.number().int().positive().nullable().optional(), +}); + +// GET /api/admin/tags — flat list with counts +app.get("/", async (c) => { ... }); + +// GET /api/admin/tags/:id — single tag with counts +app.get("/:id", async (c) => { ... }); + +// POST /api/admin/tags — create +app.post("/", zValidator("json", createTagSchema), async (c) => { ... }); + +// PUT /api/admin/tags/:id — update (with cycle check) +app.put("/:id", zValidator("json", updateTagSchema), async (c) => { ... }); + +// DELETE /api/admin/tags/:id +app.delete("/:id", async (c) => { ... }); + +export { app as adminTagRoutes }; +``` + +### Pattern 5: Tree Building (Client) + +**What:** Pure function transforming flat `AdminTag[]` to a `TreeNode[]` for rendering. Keep in component or a `lib/treeUtils.ts` helper. + +```typescript +// Source: [ASSUMED — standard algorithm] + +interface AdminTag { id: number; name: string; parentId: number | null; itemCount: number; } +interface TreeNode extends AdminTag { children: TreeNode[]; depth: number; } + +function buildTree(tags: AdminTag[]): TreeNode[] { + const map = new Map(); + tags.forEach(t => map.set(t.id, { ...t, children: [], depth: 0 })); + const roots: TreeNode[] = []; + map.forEach(node => { + if (node.parentId === null) { + roots.push(node); + } else { + const parent = map.get(node.parentId); + if (parent) { + node.depth = parent.depth + 1; + parent.children.push(node); + } else { + roots.push(node); // orphan (parent deleted) → treat as top-level + } + } + }); + return roots; +} + +// Flatten tree to ordered rows for render +function flattenTree(nodes: TreeNode[], result: TreeNode[] = []): TreeNode[] { + for (const node of nodes) { + result.push(node); + flattenTree(node.children, result); + } + return result; +} +``` + +### Pattern 6: Client Hooks (useAdminTags.ts) + +**What:** Mirrors `useAdminGlobalItems.ts` — typed interfaces, `useQuery`/`useMutation`, query key invalidation. + +```typescript +// Source: [VERIFIED: adapted from src/client/hooks/useAdminGlobalItems.ts] + +export interface AdminTag { + id: number; + name: string; + parentId: number | null; + itemCount: number; +} + +export function useAdminTags() { + return useQuery({ + queryKey: ["admin-tags"], + queryFn: () => apiGet("/api/admin/tags"), + }); +} + +export function useCreateAdminTag() { + const queryClient = useQueryClient(); + return useMutation({ + mutationFn: (data: { name: string; parentId?: number | null }) => + apiPost("/api/admin/tags", data), + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ["admin-tags"] }); + queryClient.invalidateQueries({ queryKey: ["tags"] }); // invalidate public cache too + }, + }); +} + +export function useUpdateAdminTag() { ... } +export function useDeleteAdminTag() { ... } +``` + +### Anti-Patterns to Avoid + +- **Recursive SQL CTE for tree traversal:** Unnecessary complexity for a small tag set. Fetch flat, build tree in JS. +- **Storing tree structure as nested JSON:** The `parentId` column is the canonical representation. Never denormalize. +- **Cycle detection only on the client:** The client filter is UX convenience only. The server MUST validate independently. +- **Infinite loop in `buildTree` if existing cycle in data:** Guard with a `visited` set in the ancestor walk. +- **Forgetting to invalidate `["tags"]` query key on mutations:** The public `useTags` hook and admin `useAdminTags` share the same underlying data but different query keys — both must be invalidated on create/update/delete. + +--- + +## Don't Hand-Roll + +| Problem | Don't Build | Use Instead | Why | +|---------|-------------|-------------|-----| +| Request body validation | Manual type checks | Zod + `@hono/zod-validator` | Already in project; handles error responses automatically | +| Admin auth guard | Inline `isAdmin` checks per route | `requireAdmin` middleware (already exists) | `src/server/middleware/auth.ts` — one line: `app.use("/*", requireAuth, requireAdmin)` | +| Server state / cache | `useState` + `useEffect` + `fetch` | TanStack React Query | Already in project; mutations auto-invalidate | +| Delete confirmation modal | Custom overlay | Inline modal pattern from `items.$itemId.tsx` | Copy the fixed-inset-0 dialog pattern — 30 lines, zero deps | + +**Key insight:** This phase has no new external dependencies. The entire implementation is wiring existing infrastructure with new data. + +--- + +## Common Pitfalls + +### Pitfall 1: Self-Referential FK Forward Reference in Drizzle + +**What goes wrong:** Writing `references(() => tags.id)` where `tags` is the table being defined causes a TypeScript/runtime error if the variable isn't yet in scope. + +**Why it happens:** The table definition references itself before the `const tags = ...` assignment completes. + +**How to avoid:** Drizzle handles this correctly when using a lambda `() => tags.id` — it defers the reference lookup. Confirmed by the `globalItemTags` FK pattern already in the codebase (`references(() => tags.id, { onDelete: "cascade" })`). The self-referential case works the same way. [VERIFIED: codebase at `globalItemTags.tagId`] + +**Warning signs:** TypeScript complains about `tags` being used before assignment — only occurs if you use a direct reference `tags.id` instead of a lambda. + +### Pitfall 2: Orphan Display After Parent Deletion + +**What goes wrong:** A tag's `parentId` points to a deleted parent. The tree builder crashes or silently omits the orphaned tag. + +**Why it happens:** `ON DELETE SET NULL` runs at DB level, but there's a window in tests or seed data where orphans could be created manually. + +**How to avoid:** In `buildTree`, when a node's `parentId` is non-null but no matching parent is found in the map, treat the node as a root (already shown in the Pattern 5 code above). + +**Warning signs:** Tags disappearing from the list after a parent deletion. + +### Pitfall 3: Parent Picker Shows Tag's Own Descendants (Client Side) + +**What goes wrong:** An admin selects a child tag as the parent of its ancestor, creating a cycle. + +**Why it happens:** Parent picker renders all tags without filtering. + +**How to avoid:** The parent picker on the edit page must exclude: (1) the tag itself, (2) all its descendants. Compute the descendant set client-side from the full tag list. The server provides the safety net (D-11). + +**Warning signs:** 400 errors from the server on PUT requests with `{ error: "Cycle detected" }`. + +### Pitfall 4: Missing `["tags"]` Query Invalidation + +**What goes wrong:** The admin creates/renames/deletes a tag, but the public `useTags()` hook (used in the admin items filter chips) still shows stale data. + +**Why it happens:** `useAdminTags` and `useTags` use different query keys (`["admin-tags"]` vs `["tags"]`). Invalidating only `["admin-tags"]` leaves the public cache stale. + +**How to avoid:** All mutations in `useAdminTags.ts` must invalidate both `["admin-tags"]` and `["tags"]`. + +### Pitfall 5: TanStack Router Route Tree Not Regenerated + +**What goes wrong:** New route files `admin/tags.tsx` and `admin/tags.$tagId.tsx` are created but the auto-generated `routeTree.gen.ts` is not updated, causing 404s or build errors. + +**Why it happens:** The route tree is auto-generated by Vite during `bun run dev` or `bun run build`. In development the watcher updates it automatically. In CI it must be regenerated. + +**How to avoid:** Run `bun run dev` at least once after adding new route files so `routeTree.gen.ts` is regenerated. Never manually edit `routeTree.gen.ts`. + +--- + +## Code Examples + +### Registering Admin Tag Routes in admin.ts + +```typescript +// Source: [VERIFIED: src/server/routes/admin.ts pattern] +import { adminTagRoutes } from "./admin-tags.ts"; + +// Add after adminItemRoutes registration: +app.route("/tags", adminTagRoutes); +``` + +### Enabling Tags Sidebar Link in admin.tsx + +```typescript +// Source: [VERIFIED: src/client/routes/admin.tsx — replace disabled div] + +// Replace: +
+ +// With (same structure as Items link above it): + + + Tags + +``` + +### Delete Confirmation Text Logic (D-13/D-14) + +```typescript +// Source: [VERIFIED: adapted from items.$itemId.tsx dialog pattern] + +function getDeleteConfirmText(tag: AdminTagDetail): string { + const parts: string[] = []; + if (tag.itemCount > 0) { + parts.push(`${tag.itemCount} ${tag.itemCount === 1 ? "item uses" : "items use"} this tag.`); + } + if (tag.childCount > 0) { + parts.push(`Its ${tag.childCount} child ${tag.childCount === 1 ? "tag" : "tags"} will become top-level.`); + } + parts.push("This cannot be undone."); + return parts.join(" "); +} +``` + +--- + +## State of the Art + +| Old Approach | Current Approach | When Changed | Impact | +|--------------|------------------|--------------|--------| +| Flat tags (id, name only) | Hierarchical tags with `parentId` | Phase 38 | Enables sub-tag taxonomy (e.g. "down" under "sleeping-bag") | +| Disabled "Tags" sidebar entry | Active link to `/admin/tags` | Phase 38 | Admins can navigate to tag management | + +**Deprecated/outdated:** +- None in this phase — purely additive. + +--- + +## Assumptions Log + +| # | Claim | Section | Risk if Wrong | +|---|-------|---------|---------------| +| A1 | `buildTree` and `flattenTree` pure JS functions are sufficient (no recursive SQL CTE needed) | Architecture Patterns | Low — tag count is small; even 10,000 tags would be fast in JS | +| A2 | `childCount` is cheapest computed client-side from the flat array rather than via SQL subquery | Standard Stack | Low — trivially verifiable; a SQL subquery would also work | +| A3 | `isDescendant` cycle check iterates ancestor chain of `candidateParentId` (not descendants of `tagId`) | Architecture Patterns | Medium — logic must be verified during implementation; wrong direction breaks cycle detection silently | +| A4 | Drizzle self-referential FK with `onDelete: "set null"` generates correct SQL | Standard Stack | Low — Drizzle docs support this; existing `onDelete: "cascade"` FK in codebase confirms the option syntax | + +--- + +## Open Questions + +1. **`childCount` on the single-tag GET endpoint (for edit page delete confirmation)** + - What we know: `getAdminTags` (list endpoint) returns all tags; `childCount` is derivable client-side. + - What's unclear: For the edit page, we need `childCount` for the specific tag being edited. We can either: (a) compute it client-side from the full `useAdminTags` list, or (b) add a correlated count to `getTagWithCounts`. + - Recommendation: Use the full list from `useAdminTags` cache on the edit page as well (React Query keeps it cached). No separate correlated subquery needed. + +2. **`parentId` null on quick-add form submission** + - What we know: Parent picker is optional (D-07). No parent selected = `parentId: null`. + - What's unclear: Zod schema should accept `parentId: z.number().int().positive().nullable().optional()` — ensure `null` and `undefined` both result in DB `NULL`. + - Recommendation: Use `.nullable().optional()` and explicitly pass `null` when no parent is selected. + +--- + +## Environment Availability + +Step 2.6: SKIPPED (no external dependencies beyond existing project stack — no new tools, services, or runtimes introduced). + +--- + +## Validation Architecture + +### Test Framework + +| Property | Value | +|----------|-------| +| Framework | Bun test runner (bun:test) | +| Config file | None — discovered automatically | +| Quick run command | `bun test tests/services/tag.service.test.ts tests/routes/tags.test.ts` | +| Full suite command | `bun test` | + +### Phase Requirements → Test Map + +| Req ID | Behavior | Test Type | Automated Command | File Exists? | +|--------|----------|-----------|-------------------|-------------| +| ADMN-05 | `getAdminTags` returns tags with `parentId`, `itemCount`, ordered alphabetically | unit | `bun test tests/services/tag.service.test.ts` | Exists (extend) | +| ADMN-06 | `POST /api/admin/tags` creates tag, returns 201 with tag object | integration | `bun test tests/routes/admin-tags.test.ts` | Wave 0 gap | +| ADMN-07 | `PUT /api/admin/tags/:id` renames tag | integration | `bun test tests/routes/admin-tags.test.ts` | Wave 0 gap | +| ADMN-08 | `PUT /api/admin/tags/:id` with valid `parentId` sets parent | integration | `bun test tests/routes/admin-tags.test.ts` | Wave 0 gap | +| ADMN-09 | `PUT /api/admin/tags/:id` with `parentId: null` removes parent | integration | `bun test tests/routes/admin-tags.test.ts` | Wave 0 gap | +| ADMN-10 | `DELETE /api/admin/tags/:id` deletes tag; children get `parentId = null` | integration | `bun test tests/routes/admin-tags.test.ts` | Wave 0 gap | +| ADMN-11 (cycle) | `PUT /api/admin/tags/:id` with descendant as `parentId` returns 400 | unit | `bun test tests/services/tag.service.test.ts` | Exists (extend) | + +### Sampling Rate + +- **Per task commit:** `bun test tests/services/tag.service.test.ts` +- **Per wave merge:** `bun test` +- **Phase gate:** Full suite green before `/gsd-verify-work` + +### Wave 0 Gaps + +- [ ] `tests/routes/admin-tags.test.ts` — covers ADMN-06, ADMN-07, ADMN-08, ADMN-09, ADMN-10 route integration tests +- Existing `tests/services/tag.service.test.ts` — extend (do not replace) for ADMN-05 and cycle detection + +--- + +## Security Domain + +### Applicable ASVS Categories + +| ASVS Category | Applies | Standard Control | +|---------------|---------|-----------------| +| V2 Authentication | yes | `requireAuth` middleware (existing) | +| V3 Session Management | no | Handled by existing OIDC middleware | +| V4 Access Control | yes | `requireAdmin` middleware (existing) — all `/api/admin/*` routes | +| V5 Input Validation | yes | Zod schemas on all POST/PUT bodies via `zValidator` | +| V6 Cryptography | no | No new cryptographic operations | + +### Known Threat Patterns + +| Pattern | STRIDE | Standard Mitigation | +|---------|--------|---------------------| +| Unauthorized tag mutation (non-admin) | Elevation of Privilege | `requireAdmin` middleware on all admin tag routes (already pattern-established) | +| Cycle injection via crafted `parentId` | Tampering | Server-side `isDescendant` check before update, returns 400 | +| Mass tag deletion via unauthenticated request | Tampering | `requireAdmin` blocks unauthenticated and non-admin users | +| Tag name injection (XSS) | Tampering | Zod `z.string().min(1)` + React renders as text (not innerHTML) | + +--- + +## Sources + +### Primary (HIGH confidence) + +- [VERIFIED: codebase] `src/server/services/tag.service.ts` — existing service functions and DB patterns +- [VERIFIED: codebase] `src/server/routes/admin-items.ts` — admin route module pattern to replicate +- [VERIFIED: codebase] `src/client/routes/admin/items.$itemId.tsx` — edit page and delete dialog pattern +- [VERIFIED: codebase] `src/client/hooks/useAdminGlobalItems.ts` — React Query admin hook pattern +- [VERIFIED: codebase] `src/db/schema.ts` — current tags table structure; FK syntax for `onDelete: "set null"` +- [VERIFIED: codebase] `src/server/routes/admin.ts` — admin router structure; how to register new sub-router +- [VERIFIED: codebase] `src/client/routes/admin.tsx` — disabled Tags entry to enable +- [VERIFIED: codebase] `tests/helpers/db.ts` — PGlite test setup with migrations +- [VERIFIED: codebase] `bun --version` → 1.3.9 + +### Secondary (MEDIUM confidence) + +- [ASSUMED] Drizzle self-referential FK with `() => tags.id` lambda + `onDelete: "set null"` — confirmed by existing `onDelete: "cascade"` FK syntax in codebase; "set null" is a standard Drizzle option + +### Tertiary (LOW confidence) + +- None + +--- + +## Metadata + +**Confidence breakdown:** +- Standard stack: HIGH — all verified from codebase; no new packages +- Architecture: HIGH — direct extension of Phase 37 patterns; only new logic is tree building and cycle detection +- Pitfalls: HIGH — identified from direct code inspection and structural analysis + +**Research date:** 2026-04-19 +**Valid until:** 2026-05-19 (stable codebase; no fast-moving dependencies)