kindred/silo
1
1
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(api): .kc commit extraction pipeline + metadata API (Phase 1) #141

New Issue
Closed
opened 2026-02-18 20:58:23 +00:00 by forbes · 0 comments
forbes commented 2026-02-18 20:58:23 +00:00
Owner
Copy Link

Implement the .kc commit extraction pipeline and metadata CRUD endpoints as specified in KC_SERVER.md Sections 2 and 4.1.

Depends on: #140 (database migration)
Supports: SILO_VIEWPORT Phase 1-2 (Manifest Viewer, Metadata Editor)

Commit Pipeline (Section 2)

When a .kc file is uploaded via POST /api/items/{partNumber}/file, after storing the file:

  1. Open the ZIP and look for a silo/ directory
  2. If not found, short-circuit (plain .fcstd -- existing behavior)
  3. Parse silo/manifest.json and validate:
    • UUID matches item's UUID (409 if mismatch)
    • kc_version is supported (422 if too new)
    • revision_hash differs from current head (200 no-op if same)
    • All JSON entries parse cleanly (422 with path on error)
  4. Upsert item_metadata row from manifest + metadata entries
  5. If validation fails, still store the file but set a metadata_error flag on the revision

Metadata API Endpoints (Section 4.1)

Method Path Auth Description
GET /api/items/{pn}/metadata viewer Return indexed metadata (schema fields, tags, lifecycle, manifest)
PUT /api/items/{pn}/metadata editor Partial update of schema fields (merge into JSONB)
PATCH /api/items/{pn}/metadata/lifecycle editor Transition lifecycle state with validation
PATCH /api/items/{pn}/metadata/tags editor Add/remove tags

Implementation scope

  • internal/kc/extract.go -- ZIP reader, silo/ directory parser, manifest validation
  • internal/db/item_metadata.go -- item_metadata repository (upsert, get, update fields, update lifecycle, update tags)
  • internal/api/metadata_handlers.go -- HTTP handlers for the 4 endpoints
  • internal/api/routes.go -- register new routes
  • Hook into existing file upload handler to call extraction pipeline

Acceptance criteria

  • Uploading a .kc file with valid silo/manifest.json + silo/metadata.json populates item_metadata
  • Uploading a plain .fcstd works unchanged (no metadata row created)
  • GET /metadata returns indexed data without touching the file on disk
  • PUT /metadata merges fields, rejects unknown field names with 422
  • PATCH /lifecycle validates state transitions
  • PATCH /tags adds/removes from the tags array
Implement the .kc commit extraction pipeline and metadata CRUD endpoints as specified in [KC_SERVER.md](docs/KC_SERVER.md) Sections 2 and 4.1. **Depends on:** #140 (database migration) **Supports:** SILO_VIEWPORT Phase 1-2 (Manifest Viewer, Metadata Editor) ## Commit Pipeline (Section 2) When a .kc file is uploaded via `POST /api/items/{partNumber}/file`, after storing the file: 1. Open the ZIP and look for a `silo/` directory 2. If not found, short-circuit (plain .fcstd -- existing behavior) 3. Parse `silo/manifest.json` and validate: - UUID matches item's UUID (409 if mismatch) - kc_version is supported (422 if too new) - revision_hash differs from current head (200 no-op if same) - All JSON entries parse cleanly (422 with path on error) 4. Upsert `item_metadata` row from manifest + metadata entries 5. If validation fails, still store the file but set a `metadata_error` flag on the revision ## Metadata API Endpoints (Section 4.1) | Method | Path | Auth | Description | |--------|------|------|-------------| | `GET` | `/api/items/{pn}/metadata` | viewer | Return indexed metadata (schema fields, tags, lifecycle, manifest) | | `PUT` | `/api/items/{pn}/metadata` | editor | Partial update of schema fields (merge into JSONB) | | `PATCH` | `/api/items/{pn}/metadata/lifecycle` | editor | Transition lifecycle state with validation | | `PATCH` | `/api/items/{pn}/metadata/tags` | editor | Add/remove tags | ## Implementation scope - `internal/kc/extract.go` -- ZIP reader, silo/ directory parser, manifest validation - `internal/db/item_metadata.go` -- item_metadata repository (upsert, get, update fields, update lifecycle, update tags) - `internal/api/metadata_handlers.go` -- HTTP handlers for the 4 endpoints - `internal/api/routes.go` -- register new routes - Hook into existing file upload handler to call extraction pipeline ## Acceptance criteria - Uploading a .kc file with valid silo/manifest.json + silo/metadata.json populates item_metadata - Uploading a plain .fcstd works unchanged (no metadata row created) - GET /metadata returns indexed data without touching the file on disk - PUT /metadata merges fields, rejects unknown field names with 422 - PATCH /lifecycle validates state transitions - PATCH /tags adds/removes from the tags array
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
forbes
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: kindred/silo#141
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?