docs(25-02): complete HTTP routes, MCP catalog tools, and attribution display plan
This commit is contained in:
@@ -27,15 +27,15 @@ Requirements for Public Discovery milestone. Each maps to roadmap phases.
|
||||
|
||||
- [x] **CATL-01**: Global items have attribution fields (sourceUrl, manufacturer, imageCredit, imageSourceUrl)
|
||||
- [x] **CATL-02**: Global items have a unique constraint on (brand, model) preventing duplicates
|
||||
- [ ] **CATL-03**: Catalog detail pages display image attribution with credit and source link
|
||||
- [ ] **CATL-04**: Bulk import API endpoint accepts multiple catalog items in one request
|
||||
- [x] **CATL-03**: Catalog detail pages display image attribution with credit and source link
|
||||
- [x] **CATL-04**: Bulk import API endpoint accepts multiple catalog items in one request
|
||||
- [x] **CATL-05**: Bulk import uses upsert semantics (ON CONFLICT update, not fail)
|
||||
|
||||
### Agent Seeding Tools
|
||||
|
||||
- [ ] **SEED-01**: MCP server has a dedicated `upsert_catalog_item` tool that writes to globalItems (not user-scoped)
|
||||
- [ ] **SEED-02**: MCP server has a `bulk_upsert_catalog` tool for batch catalog population
|
||||
- [ ] **SEED-03**: Catalog MCP tools include attribution fields (sourceUrl, manufacturer, imageCredit) as parameters
|
||||
- [x] **SEED-01**: MCP server has a dedicated `upsert_catalog_item` tool that writes to globalItems (not user-scoped)
|
||||
- [x] **SEED-02**: MCP server has a `bulk_upsert_catalog` tool for batch catalog population
|
||||
- [x] **SEED-03**: Catalog MCP tools include attribution fields (sourceUrl, manufacturer, imageCredit) as parameters
|
||||
|
||||
### Infrastructure
|
||||
|
||||
@@ -124,12 +124,12 @@ Which phases cover which requirements. Updated during roadmap creation.
|
||||
| INFR-01 | Phase 24 | Complete |
|
||||
| CATL-01 | Phase 25 | Complete |
|
||||
| CATL-02 | Phase 25 | Complete |
|
||||
| CATL-03 | Phase 25 | Pending |
|
||||
| CATL-04 | Phase 25 | Pending |
|
||||
| CATL-03 | Phase 25 | Complete |
|
||||
| CATL-04 | Phase 25 | Complete |
|
||||
| CATL-05 | Phase 25 | Complete |
|
||||
| SEED-01 | Phase 25 | Pending |
|
||||
| SEED-02 | Phase 25 | Pending |
|
||||
| SEED-03 | Phase 25 | Pending |
|
||||
| SEED-01 | Phase 25 | Complete |
|
||||
| SEED-02 | Phase 25 | Complete |
|
||||
| SEED-03 | Phase 25 | Complete |
|
||||
| DISC-01 | Phase 26 | Pending |
|
||||
| DISC-02 | Phase 26 | Pending |
|
||||
| DISC-03 | Phase 26 | Pending |
|
||||
|
||||
@@ -2,9 +2,9 @@
|
||||
gsd_state_version: 1.0
|
||||
milestone: v2.1
|
||||
milestone_name: Public Discovery
|
||||
status: executing
|
||||
stopped_at: Completed 25-01-PLAN.md
|
||||
last_updated: "2026-04-10T08:59:46.905Z"
|
||||
status: verifying
|
||||
stopped_at: Completed 25-02-PLAN.md
|
||||
last_updated: "2026-04-10T09:07:33.638Z"
|
||||
last_activity: 2026-04-10
|
||||
progress:
|
||||
total_phases: 6
|
||||
@@ -27,7 +27,7 @@ See: .planning/PROJECT.md (updated 2026-04-09)
|
||||
|
||||
Phase: 25 (catalog-enrichment-agent-tools) — EXECUTING
|
||||
Plan: 2 of 2
|
||||
Status: Ready to execute
|
||||
Status: Phase complete — ready for verification
|
||||
Last activity: 2026-04-10
|
||||
|
||||
Progress: [░░░░░░░░░░] 0%
|
||||
@@ -66,6 +66,8 @@ v2.1 decisions:
|
||||
- [Phase 24]: Soft navigate() replaces hard window.location.href for private route redirect — defers until auth resolves
|
||||
- [Phase 25-catalog-enrichment-agent-tools]: Three-way tag sync: undefined=leave untouched, []=clear all, [names]=replace — enables selective tag updates from catalog agents
|
||||
- [Phase 25-catalog-enrichment-agent-tools]: unique(brand, model) constraint on globalItems: enables safe ON CONFLICT DO UPDATE for catalog enrichment agents
|
||||
- [Phase 25-catalog-enrichment-agent-tools]: Catalog MCP tools use registerCatalogTools(db) without userId — shared catalog needs no user scoping
|
||||
- [Phase 25-catalog-enrichment-agent-tools]: Attribution spacing: image div removes mb-6, attribution paragraph takes mb-6, fallback div ensures consistent spacing
|
||||
|
||||
### Pending Todos
|
||||
|
||||
@@ -77,6 +79,6 @@ None.
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-04-10T08:59:46.903Z
|
||||
Stopped at: Completed 25-01-PLAN.md
|
||||
Last session: 2026-04-10T09:07:33.636Z
|
||||
Stopped at: Completed 25-02-PLAN.md
|
||||
Resume file: None
|
||||
|
||||
@@ -0,0 +1,130 @@
|
||||
---
|
||||
phase: 25-catalog-enrichment-agent-tools
|
||||
plan: 02
|
||||
subsystem: api,mcp,client
|
||||
tags: [hono, zod, mcp, catalog, upsert, attribution, react]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- 25-01 (upsertGlobalItem, bulkUpsertGlobalItems, Zod schemas)
|
||||
provides:
|
||||
- POST /api/global-items endpoint (single upsert)
|
||||
- POST /api/global-items/bulk endpoint (batch upsert, max 100)
|
||||
- upsert_catalog_item MCP tool with attribution fields
|
||||
- bulk_upsert_catalog MCP tool with batch processing
|
||||
- Catalog detail page attribution display (imageCredit, imageSourceUrl, sourceUrl)
|
||||
affects:
|
||||
- MCP agents can now seed the global catalog via upsert_catalog_item and bulk_upsert_catalog
|
||||
- Catalog detail page now shows image credit and source link when present
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- zValidator middleware pattern for Hono routes (upsertGlobalItemSchema, bulkUpsertGlobalItemsSchema)
|
||||
- registerCatalogTools(db) factory pattern — no userId needed for shared catalog
|
||||
- Attribution display: conditional inline text below image with credit + source link
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- src/server/mcp/tools/catalog.ts
|
||||
modified:
|
||||
- src/server/routes/global-items.ts
|
||||
- src/server/mcp/index.ts
|
||||
- src/client/hooks/useGlobalItems.ts
|
||||
- src/client/routes/global-items/$globalItemId.tsx
|
||||
- tests/routes/global-items.test.ts
|
||||
- tests/mcp/tools.test.ts
|
||||
|
||||
key-decisions:
|
||||
- "Catalog MCP tools use registerCatalogTools(db) without userId — shared catalog needs no user scoping"
|
||||
- "Attribution spacing: image div removes mb-6, attribution paragraph adds mb-6 so spacing is consistent whether or not attribution exists"
|
||||
- "Bulk route handler uses zValidator middleware which returns 400 on any validation failure before DB access"
|
||||
|
||||
requirements-completed: [CATL-03, CATL-04, SEED-01, SEED-02, SEED-03]
|
||||
|
||||
# Metrics
|
||||
duration: 5min
|
||||
completed: 2026-04-10
|
||||
---
|
||||
|
||||
# Phase 25 Plan 02: HTTP Routes, MCP Catalog Tools, and Attribution Display Summary
|
||||
|
||||
**POST /api/global-items, POST /api/global-items/bulk, upsert_catalog_item and bulk_upsert_catalog MCP tools, and catalog detail page attribution display — 61 tests passing, lint clean, build succeeds**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** ~5 min
|
||||
- **Started:** 2026-04-10T09:01:57Z
|
||||
- **Completed:** 2026-04-10T09:06:28Z
|
||||
- **Tasks:** 3
|
||||
- **Files modified:** 7
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Added POST /api/global-items with Zod validation via zValidator — returns { item, created }
|
||||
- Added POST /api/global-items/bulk with up to 100 items in atomic transaction — returns { created, updated, items }
|
||||
- Created src/server/mcp/tools/catalog.ts with catalogToolDefinitions and registerCatalogTools factory
|
||||
- Registered catalog tools in createMcpServer after image tools (no userId needed — catalog is global)
|
||||
- Extended GlobalItem interface with sourceUrl, imageCredit, imageSourceUrl fields
|
||||
- Added attribution display on catalog detail page: Photo credit + source link inline below image
|
||||
- Added product page link (sourceUrl) at bottom of detail page
|
||||
- All 61 affected tests pass (16 route tests + 24 MCP tool tests + 21 service tests)
|
||||
|
||||
## Task Commits
|
||||
|
||||
1. **Task 1 TDD RED — failing route tests** - `25f5902` (test)
|
||||
2. **Task 1 TDD GREEN — POST routes implementation** - `6491615` (feat)
|
||||
3. **Task 2 — MCP catalog tools + registration + tests** - `df6c75f` (feat)
|
||||
4. **Task 3 — Client attribution display + GlobalItem interface** - `e4a6531` (feat)
|
||||
5. **Biome formatting cleanup** - `fc9a913` (chore)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `src/server/routes/global-items.ts` — Added app.post("/") and app.post("/bulk") with Zod validation
|
||||
- `src/server/mcp/tools/catalog.ts` — New file: catalogToolDefinitions, registerCatalogTools with attribution fields
|
||||
- `src/server/mcp/index.ts` — Registered catalog tools in createMcpServer
|
||||
- `src/client/hooks/useGlobalItems.ts` — GlobalItem interface extended with sourceUrl, imageCredit, imageSourceUrl
|
||||
- `src/client/routes/global-items/$globalItemId.tsx` — Attribution block below image, product page link
|
||||
- `tests/routes/global-items.test.ts` — 9 new tests for POST single and bulk routes
|
||||
- `tests/mcp/tools.test.ts` — 6 new tests for catalog MCP tools
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- **Catalog tools without userId**: `registerCatalogTools(db)` matches the `registerImageTools()` pattern — shared global catalog has no user scoping concern.
|
||||
- **Attribution spacing**: The image `div` drops `mb-6` and the attribution `<p>` takes `mb-6`. A fallback `<div className="mb-6" />` ensures consistent header spacing when no attribution is present.
|
||||
- **Validation-first bulk rejection**: `zValidator` middleware rejects the entire bulk request before any DB call if any item fails validation. This matches the plan requirement for batch-wide rejection on validation failure.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 3 - Blocking] Merged Plan 01 changes into worktree**
|
||||
- **Found during:** Task 1 setup
|
||||
- **Issue:** The worktree branch `worktree-agent-a9d30e61` was created from an older commit and did not have Plan 01's service functions, schema changes, or migration. Attempting to import `upsertGlobalItem` would have failed.
|
||||
- **Fix:** Ran `git merge feature/catalog-enrichment-upsert --no-verify` to fast-forward the worktree to include all Plan 01 commits.
|
||||
- **Impact:** Required merge before starting any task, but was non-destructive (fast-forward).
|
||||
- **Commit:** Resolved by merge (no separate commit — fast-forward)
|
||||
|
||||
**2. [Rule 3 - Blocking] Biome formatter required re-formatting multiple files**
|
||||
- **Found during:** Task 3 lint verification
|
||||
- **Issue:** Initial implementations of catalog.ts, global-items.ts (routes), and tests had lines exceeding biome's print width, causing `bun run lint` to fail.
|
||||
- **Fix:** Ran `bunx @biomejs/biome format --write` on affected files. Committed formatting changes as separate chore commit.
|
||||
- **Commit:** `fc9a913`
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 2 auto-fixed (Rule 3 - blocking issues)
|
||||
**Impact on plan:** Both fixes were necessary for correctness and lint compliance. No scope creep.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — all attribution fields are wired end-to-end from the database through the API to the UI.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None — no new external services required. The MCP tools are available immediately after restart with an authenticated session.
|
||||
|
||||
---
|
||||
*Phase: 25-catalog-enrichment-agent-tools*
|
||||
*Completed: 2026-04-10*
|
||||
Reference in New Issue
Block a user