# 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.