init

docs/agents/handoffs/04-projects-releases.md

@@ -0,0 +1,105 @@
+# Agent
+
+Name: Agent 04 - Projects, Tags, And Releases
+
+Stage: Projects, Tags, And Releases
+
+Date: 2026-04-14
+
+## Scope
+
+Implemented the core product data management stage on top of the existing authenticated `/admin` route group.
+
+Completed in this stage:
+
+- added artifact storage configuration rooted under `DATA_DIR/artifacts`, with validation that artifacts stay outside the public static directory;
+- implemented local filesystem artifact storage with temp-file staging and final path validation;
+- added project repository methods for create, update, list, archive toggle, and project-tag assignment queries;
+- added tag repository methods for create, update, list, delete-if-unused, and project usage queries;
+- added release repository methods for create, lookup, and per-project release listing;
+- implemented a release upload service that sanitizes filenames, streams uploads to a temp artifact, computes SHA-256 checksums, detects content type, moves the file into structured private storage, and writes release metadata to SQLite;
+- extended the protected admin router with project list/create/detail/archive routes, tag list/create/detail/delete routes, project-tag attach or detach actions, and release upload handling;
+- replaced the placeholder dashboard with project/tag/release-aware admin pages and added server-rendered templates for project list, project detail, project creation, tag list, and tag detail;
+- added integration coverage for the admin flow that logs in, creates and edits project/tag data, attaches tags, uploads a release, verifies the checksum and sanitized filename, and checks the artifact on disk.
+
+## Files Changed
+
+- `/Users/delete/projects/update_server/internal/app/app.go`
+- `/Users/delete/projects/update_server/internal/config/config.go`
+- `/Users/delete/projects/update_server/internal/db/errors.go`
+- `/Users/delete/projects/update_server/internal/db/models.go`
+- `/Users/delete/projects/update_server/internal/db/projects.go`
+- `/Users/delete/projects/update_server/internal/db/tags.go`
+- `/Users/delete/projects/update_server/internal/db/releases.go`
+- `/Users/delete/projects/update_server/internal/http/router.go`
+- `/Users/delete/projects/update_server/internal/http/render.go`
+- `/Users/delete/projects/update_server/internal/http/view_data.go`
+- `/Users/delete/projects/update_server/internal/http/handlers.go`
+- `/Users/delete/projects/update_server/internal/http/auth_handlers.go`
+- `/Users/delete/projects/update_server/internal/http/admin_common.go`
+- `/Users/delete/projects/update_server/internal/http/admin_projects.go`
+- `/Users/delete/projects/update_server/internal/http/admin_tags.go`
+- `/Users/delete/projects/update_server/internal/http/auth_integration_test.go`
+- `/Users/delete/projects/update_server/internal/http/projects_integration_test.go`
+- `/Users/delete/projects/update_server/internal/releases/service.go`
+- `/Users/delete/projects/update_server/internal/slug/slug.go`
+- `/Users/delete/projects/update_server/internal/storage/local.go`
+- `/Users/delete/projects/update_server/web/templates/layouts/base.gohtml`
+- `/Users/delete/projects/update_server/web/templates/pages/admin.gohtml`
+- `/Users/delete/projects/update_server/web/templates/pages/home.gohtml`
+- `/Users/delete/projects/update_server/web/templates/pages/login.gohtml`
+- `/Users/delete/projects/update_server/web/templates/pages/projects.gohtml`
+- `/Users/delete/projects/update_server/web/templates/pages/project_form.gohtml`
+- `/Users/delete/projects/update_server/web/templates/pages/project_detail.gohtml`
+- `/Users/delete/projects/update_server/web/templates/pages/tags.gohtml`
+- `/Users/delete/projects/update_server/web/templates/pages/tag_form.gohtml`
+- `/Users/delete/projects/update_server/web/static/app.css`
+- `/Users/delete/projects/update_server/docs/agents/handoffs/04-projects-releases.md`
+
+## Database Changes
+
+- no schema or migration changes were required in this stage;
+- the existing `projects`, `tags`, `project_tags`, and `releases` tables are now actively used by repository methods and protected admin workflows;
+- release `storage_path` values are now persisted as relative paths underneath the configured artifact root;
+- release rows now store sanitized filenames, SHA-256 checksum values, detected content type, file size, release notes, and uploader linkage.
+
+## API Or Route Changes
+
+- added `GET /admin/projects` for the protected project list page;
+- added `GET /admin/projects/new` and `POST /admin/projects` for project creation;
+- added `GET /admin/projects/{projectID}` and `POST /admin/projects/{projectID}` for project detail and editing;
+- added `POST /admin/projects/{projectID}/archive` for archive or restore actions;
+- added `POST /admin/projects/{projectID}/tags` and `POST /admin/projects/{projectID}/tags/{tagID}/detach` for project-tag assignment;
+- added `POST /admin/projects/{projectID}/releases` for protected release uploads;
+- added `GET /admin/tags`, `GET /admin/tags/new`, and `POST /admin/tags` for tag list and creation;
+- added `GET /admin/tags/{tagID}`, `POST /admin/tags/{tagID}`, and `POST /admin/tags/{tagID}/delete` for tag edit and delete-if-unused behavior;
+- updated `GET /admin` to show project/tag/release summary data instead of the auth-only placeholder;
+- kept `/api/v1` unchanged and intentionally did not add API key or client update endpoints in this stage.
+
+## Commands And Tests Run
+
+- `gofmt -w ./internal ./cmd` - passed;
+- `GOCACHE=/tmp/go-build-agent04 GOMODCACHE=/tmp/go-mod-agent04 go test ./...` - initially failed in the sandbox due dependency download DNS restrictions, then passed after rerunning with approval;
+- `GOCACHE=/tmp/go-build-agent04 GOMODCACHE=/tmp/go-mod-agent04 go build -o /tmp/update-server-agent04 ./cmd/server` - passed;
+- `GOCACHE=/tmp/go-build-agent04 GOMODCACHE=/tmp/go-mod-agent04 go build -o /tmp/update-migrate-agent04 ./cmd/migrate` - passed.
+
+## Known Limitations
+
+- CSRF protection is still not implemented for admin forms, including the new project, tag, archive, and upload actions;
+- release deletion or disable flows are not implemented in this stage;
+- there is still no client-facing download or metadata endpoint for releases; only the protected admin upload and metadata path is present;
+- duplicate project slugs, tag slugs, and `(project_id, version, build)` release combinations are rejected rather than offering replace-in-place behavior;
+- upload handling currently relies on the standard multipart temp-file path before final storage, which is acceptable for MVP but not yet a custom streaming parser.
+
+## Recommended Next Step
+
+Agent 05 should implement API key generation, hashing, permissions, and scope evaluation on top of the now-working project and tag data model, using the existing `projects`, `tags`, and assignment relationships for allow-list and deny-list management.
+
+## Notes For Validator
+
+- verify that all new admin project and tag routes remain inside the existing authenticated `/admin` route group and reuse the session context;
+- verify that uploaded artifacts land under `DATA_DIR/artifacts` and not under `web/static`;
+- verify that uploaded filenames are sanitized before persistence and that `releases.checksum_sha256` matches the actual file bytes on disk;
+- verify that release metadata rows are written to SQLite with the expected storage path, size, content type, and uploader linkage;
+- verify that project archive or restore toggles `projects.is_active`;
+- verify that tag deletion is blocked while the tag is still attached to a project.