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

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.