Decompose: GET /v1/threads/catalog missing from backend #24

New issue

Closed

opened 2026-07-12 23:17:39 +00:00 by Mark · 2 comments

Mark commented 2026-07-12 23:17:39 +00:00

Owner

Copy link

Context

The frontend easystitch-client.ts calls GET /v1/threads/catalog
(getThreadCatalog at line 446) to load the Brother PR10 thread catalog
for the thread-color picker. The backend easystitch-service does not
expose that endpoint — the route is missing from app.py and from the
auto-generated OpenAPI schema. The frontend has to fall back to the
hard-coded BROTHER_PR10_COLORS constant.

Because there's no path from catalog → frontend, paletteIndex: null
keeps coming out of the engine (see #27) and the catalog-aware thread
matching feature is dead in the water.

Goal

Add GET /v1/threads/catalog to the easystitch-service, returning the
Brother PR10 thread catalog with code/name/hex per entry, in the shape
the frontend's ThreadCatalogEntry interface already expects:

type ThreadCatalogEntry = { code: string; name: string; hex: string; }

Response shape:

{
  "catalog": [
    { "code": "001", "name": "White", "hex": "#ffffff" },
    { "code": "002", "name": "Black", "hex": "#000000" }
    ...
  ]
}

Data source: /data/brother_pr10.json (already referenced via
THREAD_PALETTE_PATH in .env.example).

Non-goals

• Catalog authoring / curation (use the existing JSON file as-is).
• Wiring the catalog into the digitize pipeline (out of scope — see
  issue #27 which handles the frontend's null paletteIndex tolerance
  for now).
• POST /v1/threads/resolve improvements (separate concern; backend
  currently returns {"error": "not_implemented"} and that stub is
  tracked by #25).

Pipeline stages

P1: Wire catalog loader + route

Goal: Stand up the route that loads the catalog JSON file and returns
it under the catalog key.

Approach candidates:

• A. Lazy-load via lru_cache or functools.lru_cache keyed on file
  mtime so the JSON is only re-read if it changes on disk.
• B. Load once at startup, store on app.state (FastAPI app.state).
• C. Load per-request with a simple json.load (no caching).

Recommend A — avoids stale-data risk of B, avoids the per-request
disk-hit cost of C.

Outputs: new route handler in easystitch-service/app.py; the
catalog JSON is loaded from the path resolved by
settings.thread_palette_path.

Acceptance:

• GET http://localhost:8080/v1/threads/catalog returns HTTP 200
• Response body: {"catalog": [{code, name, hex}, ...]} with at
  least 50 entries (full BROTHER PR10 palette has 100 threads)
• Each entry has all three fields populated, no nulls
• Unknown shape / file-missing returns 500 with a structured error
  envelope, not a Python traceback

Files touched:

• /home/b/Projects/easystitch-service/app.py (add the route)
• /home/b/Projects/easystitch-service/config.py (confirm
  thread_palette_path setting is exposed)

P2: Add tests

Goal: Lock down P1 with backend tests so a future change can't
silently break the catalog format.

Approach candidates:

• A. Unit test against the FastAPI client fixture with an in-memory
  mock catalog file.
• B. Integration test that runs against the live service with the real
  data/brother_pr10.json.

Recommend A. The catalog file in data/ is committed to the repo
and reading it from disk via the real path adds noise to the test
suite (and CI may not have the file at the expected path).

Outputs: new test file
/home/b/Projects/easystitch-service/tests/unit/test_threads_catalog.py
covering: happy path returns the catalog shape, missing file is
handled, malformed JSON is handled.

Acceptance:

• python -m pytest tests/unit/test_threads_catalog.py -v exits 0
• Each test specifies what assertion it makes
• No production-code changes in this phase

Files touched:

• /home/b/Projects/easystitch-service/tests/unit/test_threads_catalog.py (new)

Dependencies

• Blocks: thread-color picker feature in ThreadCraft UI; any
  downstream feature that wants to map emitted thread hex codes to
  Brother PR10 catalog entries.
• Blocked by: the catalog JSON file
  (/home/b/Projects/easystitch-service/data/brother_pr10.json) must
  exist with all 100 entries. Verify this exists before kicking
  off; if it's a stub with only a few entries, this phase is blocked
  on completing the catalog content first.

Research required

• One spike to verify the existing
  data/brother_pr10.json shape and confirm it matches the
  ThreadCatalogEntry interface. If not, P1 needs a transform layer.

# Context The frontend `easystitch-client.ts` calls `GET /v1/threads/catalog` (`getThreadCatalog` at line 446) to load the Brother PR10 thread catalog for the thread-color picker. The backend `easystitch-service` does not expose that endpoint — the route is missing from `app.py` and from the auto-generated OpenAPI schema. The frontend has to fall back to the hard-coded `BROTHER_PR10_COLORS` constant. Because there's no path from catalog → frontend, `paletteIndex: null` keeps coming out of the engine (see #27) and the catalog-aware thread matching feature is dead in the water. ## Goal Add `GET /v1/threads/catalog` to the easystitch-service, returning the Brother PR10 thread catalog with code/name/hex per entry, in the shape the frontend's `ThreadCatalogEntry` interface already expects: ```ts type ThreadCatalogEntry = { code: string; name: string; hex: string; } ``` Response shape: ```json { "catalog": [ { "code": "001", "name": "White", "hex": "#ffffff" }, { "code": "002", "name": "Black", "hex": "#000000" } ... ] } ``` Data source: `/data/brother_pr10.json` (already referenced via `THREAD_PALETTE_PATH` in `.env.example`). ## Non-goals - Catalog authoring / curation (use the existing JSON file as-is). - Wiring the catalog into the digitize pipeline (out of scope — see issue #27 which handles the frontend's null `paletteIndex` tolerance for now). - `POST /v1/threads/resolve` improvements (separate concern; backend currently returns `{"error": "not_implemented"}` and that stub is tracked by #25). ## Pipeline stages ### P1: Wire catalog loader + route **Goal:** Stand up the route that loads the catalog JSON file and returns it under the `catalog` key. **Approach candidates:** - A. Lazy-load via `lru_cache` or `functools.lru_cache` keyed on file mtime so the JSON is only re-read if it changes on disk. - B. Load once at startup, store on `app.state` (FastAPI app.state). - C. Load per-request with a simple `json.load` (no caching). Recommend A — avoids stale-data risk of B, avoids the per-request disk-hit cost of C. **Outputs:** new route handler in `easystitch-service/app.py`; the catalog JSON is loaded from the path resolved by `settings.thread_palette_path`. **Acceptance:** - `GET http://localhost:8080/v1/threads/catalog` returns HTTP 200 - Response body: `{"catalog": [{code, name, hex}, ...]}` with **at least 50 entries** (full BROTHER PR10 palette has 100 threads) - Each entry has all three fields populated, no nulls - Unknown shape / file-missing returns 500 with a structured error envelope, not a Python traceback **Files touched:** - `/home/b/Projects/easystitch-service/app.py` (add the route) - `/home/b/Projects/easystitch-service/config.py` (confirm `thread_palette_path` setting is exposed) ### P2: Add tests **Goal:** Lock down P1 with backend tests so a future change can't silently break the catalog format. **Approach candidates:** - A. Unit test against the FastAPI client fixture with an in-memory mock catalog file. - B. Integration test that runs against the live service with the real `data/brother_pr10.json`. Recommend A. The catalog file in `data/` is committed to the repo and reading it from disk via the real path adds noise to the test suite (and CI may not have the file at the expected path). **Outputs:** new test file `/home/b/Projects/easystitch-service/tests/unit/test_threads_catalog.py` covering: happy path returns the catalog shape, missing file is handled, malformed JSON is handled. **Acceptance:** - `python -m pytest tests/unit/test_threads_catalog.py -v` exits 0 - Each test specifies what assertion it makes - No production-code changes in this phase **Files touched:** - `/home/b/Projects/easystitch-service/tests/unit/test_threads_catalog.py` (new) ## Dependencies - **Blocks:** thread-color picker feature in ThreadCraft UI; any downstream feature that wants to map emitted thread hex codes to Brother PR10 catalog entries. - **Blocked by:** the catalog JSON file (`/home/b/Projects/easystitch-service/data/brother_pr10.json`) must exist with all 100 entries. **Verify this exists before kicking off; if it's a stub with only a few entries, this phase is blocked on completing the catalog content first.** ## Research required - One spike to verify the existing `data/brother_pr10.json` shape and confirm it matches the `ThreadCatalogEntry` interface. If not, P1 needs a transform layer.

Mark added the

triage-approved

needs-decompose

labels 2026-07-12 23:18:42 +00:00

Mark commented 2026-07-12 23:18:42 +00:00

Author

Owner

Copy link

Auto-triage: needs decompose

Marked triage-approved + needs-decompose. decompose-executor will pick this up and break it into implementable sub-issues.

## Auto-triage: needs decompose Marked `triage-approved` + `needs-decompose`. decompose-executor will pick this up and break it into implementable sub-issues.

Mark referenced this issue 2026-07-13 00:05:38 +00:00

fromServiceStitchObject throws on null paletteIndex, swallows success as 'Auto-digitize failed' #27

Mark referenced this issue 2026-07-13 00:05:49 +00:00

Frontend maxColors default (13) exceeds backend cap (10) — every default digitize 422s #26

Mark referenced this issue 2026-07-13 00:05:49 +00:00

follow-up: verify #23 fix (multipart) against live browser end-to-end test #23

Mark referenced this issue from a commit 2026-07-13 01:43:12 +00:00

fix(#26,#27): maxColors clamp ≤ 10, tolerate null paletteIndex from engine

Mark referenced this issue 2026-07-13 01:43:29 +00:00

fromServiceStitchObject throws on null paletteIndex, swallows success as 'Auto-digitize failed' #27

Mark changed title from GET /v1/threads/catalog missing from backend — frontend ThreadPalette query is permanently 404 to Decompose: GET /v1/threads/catalog missing from backend 2026-07-13 01:53:50 +00:00

Mark referenced this issue 2026-07-13 01:53:50 +00:00

Decompose: Backend /v1/export and /v1/threads/resolve stub replacements #25

Mark referenced this issue 2026-07-13 01:54:38 +00:00

Phase 1 — Wire catalog loader + GET /v1/threads/catalog route (forked from Kimi_Agent_Brother_10_Digitizing_App#24) #29

Mark referenced this issue 2026-07-13 01:54:39 +00:00

Phase 2 — Add tests for /v1/threads/catalog (forked from #24) #30

Mark commented 2026-07-13 01:54:40 +00:00

Author

Owner

Copy link

This issue has been decomposed into the following sub-issues:

#	Title	Phase Scope
#29	Decompose: GET /v1/threads/catalog missing from backend — Ph	Goal: Stand up the route that loads the catalog JSON file and returns it und
#30	Decompose: GET /v1/threads/catalog missing from backend — Ph	Goal: Lock down P1 with backend tests so a future change can't silently brea

Each sub-issue has been labeled with triage-approved and is ready for queue routing.

This issue has been decomposed into the following sub-issues: | # | Title | Phase Scope | |---|-------|-------------| | #29 | Decompose: GET /v1/threads/catalog missing from backend — Ph | **Goal:** Stand up the route that loads the catalog JSON file and returns it und | | #30 | Decompose: GET /v1/threads/catalog missing from backend — Ph | **Goal:** Lock down P1 with backend tests so a future change can't silently brea | Each sub-issue has been labeled with `triage-approved` and is ready for queue routing.

Mark closed this issue 2026-07-13 01:54:40 +00:00

Mark referenced this issue 2026-07-13 01:54:50 +00:00

Phase 1 — Implement POST /v1/threads/resolve (forked from #25) #31

Mark referenced this issue 2026-07-13 01:54:54 +00:00

Phase 4 — Add round-trip tests for /v1/export (forked from #25) #34

Mark referenced this issue 2026-09-14 03:09:25 +00:00

autoThreadMatch knob defined but never consumed #68

Mark referenced this issue 2026-09-14 03:24:15 +00:00

computeThreadStops aggregates by paletteIndex; paletteIndex: null from the engine collapses to one fake stop at index 0 #77

Mark referenced this issue 2026-09-14 03:46:37 +00:00

autoThreadMatch knob defined but never consumed #68

Mark referenced this issue from a commit 2026-10-03 06:19:21 +00:00

fix(#145): wire Auto Thread Match toggle through the digitize flow

Mark referenced this issue 2026-10-03 06:20:04 +00:00

Auto Thread Match toggle is permanently disabled with a tooltip referencing dead issue numbers #24/#29 — the value is in state but never read, the toggle is a UI lie #145

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

main

No results found.

Labels

Clear labels   

blocked:commit-ready-failed

  

blocked:gate-fetch

  

blocked:gate-lint

  

blocked:gate-plan

  

blocked:gate-research

  

blocked:needs-attention

Worker halted; needs human/janitor inspection

  

blocked:needs-decision

  

blocked:needs-human

  

blocked:no-changes

  

blocked:verify-failed

  

bug

  

deferred

  

feature-request

  

in-progress

  

needs-decompose

  

needs-triage

  

quickfix

  

security/medium

  

triage-approved

No labels

blocked:commit-ready-failed

blocked:gate-fetch

blocked:gate-lint

blocked:gate-plan

blocked:gate-research

blocked:needs-attention

blocked:needs-decision

blocked:needs-human

blocked:no-changes

blocked:verify-failed

bug

deferred

feature-request

in-progress

needs-decompose

needs-triage

quickfix

security/medium

triage-approved

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

Mark/Kimi_Agent_Brother_10_Digitizing_App#24

No description provided.