feat(webui): versioned project registry API (Closes #635) #819

2026-07-22T19:33:34-05:00

jcwalker3 commented

2026-07-22 19:33:34 -05:00

Closes #635

Summary

Phase 1 evolution of the Web Console project registry API:

Versioned GET /api/v1/projects contract with project status, remotes/orgs/repos, onboarding checklist state, and optional last-seen health
File-based registry schema compatibility (v1 normalized; v2 current)
Read-only API only; fail-closed validation with actionable remediation
Documentation and tests for valid registry, missing project, and schema validation

Linked issue

Closes #635

Files changed (7)

docs/webui-local-dev.md
docs/webui-project-registry-api.md
tests/test_webui_project_registry.py
webui/app.py
webui/data/projects.registry.json
webui/project_registry.py
webui/project_views.py

Validation

Worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-635-project-registry-api
Branch: feat/issue-635-project-registry-api
Head: b2f6e9a6dc40e9651ef876f322dd0a68bddebfd8
pytest tests/test_webui_project_registry.py → 30 passed, 22 subtests passed
Protected commit published via gitea_publish_unpublished_issue_branch (AC20) after PR #817 preflight worktree-forwarding load proof
Exact-owner issue lock renewed with success: true

Risk

Low: read-only API surface, fail-closed registry load, no credentials in registry JSON, no write endpoints.

Author handoff

Identity: jcwalker3 / prgs-author
No self-review or merge
NEXT_ELIGIBLE_ROLE: reviewer

Closes #635 ## Summary Phase 1 evolution of the Web Console project registry API: - Versioned `GET /api/v1/projects` contract with project status, remotes/orgs/repos, onboarding checklist state, and optional last-seen health - File-based registry schema compatibility (v1 normalized; v2 current) - Read-only API only; fail-closed validation with actionable remediation - Documentation and tests for valid registry, missing project, and schema validation ## Linked issue Closes #635 ## Files changed (7) - `docs/webui-local-dev.md` - `docs/webui-project-registry-api.md` - `tests/test_webui_project_registry.py` - `webui/app.py` - `webui/data/projects.registry.json` - `webui/project_registry.py` - `webui/project_views.py` ## Validation - Worktree: `/Users/jasonwalker/Development/Gitea-Tools/branches/issue-635-project-registry-api` - Branch: `feat/issue-635-project-registry-api` - Head: `b2f6e9a6dc40e9651ef876f322dd0a68bddebfd8` - `pytest tests/test_webui_project_registry.py` → **30 passed, 22 subtests passed** - Protected commit published via `gitea_publish_unpublished_issue_branch` (AC20) after PR #817 preflight worktree-forwarding load proof - Exact-owner issue lock renewed with `success: true` ## Risk Low: read-only API surface, fail-closed registry load, no credentials in registry JSON, no write endpoints. ## Author handoff - Identity: jcwalker3 / prgs-author - No self-review or merge - NEXT_ELIGIBLE_ROLE: reviewer

jcwalker3 added 1 commit 2026-07-22 19:33:34 -05:00

feat(webui): versioned project registry API (Closes #635 ) b2f6e9a6dc

Evolve the MVP project registry (#427) into a versioned, fail-closed
project registry API for the console (Phase 1, read-only).

- Add schema version 2 with project `status`, per-step onboarding
  `state`/`required`, optional redacted `last_seen_health`, and
  `remote_name`. Version 1 files stay loadable and are normalized with
  explicit defaults.
- Serve `/api/v1/projects` and `/api/v1/projects/{project_id}` with API
  provenance (`api_version`, `schema_version`, `source`). `/api/projects`
  is retained as an unversioned Phase 1 alias.
- Replace bare `ValueError` with `RegistryError`, carrying an operator
  `remediation` and `field_path`; invalid registries fail closed as a
  500 JSON payload or a dedicated HTML error page instead of a traceback.
- Reject credential-shaped keys before any DTO is built, reusing
  `registry_safety.is_forbidden_key` as the single source of truth
  shared with the worker registry (#798).
- Render HTML views from `project_to_dict`, so the console and the JSON
  API cannot disagree about status or onboarding progress.
- Document the contract in docs/webui-project-registry-api.md.

Tests: registry load/validate (valid, missing project, schema
validation, credential rejection) and API route coverage.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

jcwalker3 referenced this pull request

2026-07-22 19:34:19 -05:00

Web Console: Project registry API evolution (Phase 1) #635

sysadmin commented

2026-07-22 19:45:44 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #819
issue: #635
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 18405-51fd8b8a8672
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-819
phase: claimed
candidate_head: b2f6e9a6dc
target_branch: master
target_branch_sha: 14c9c4d702
last_activity: 2026-07-23T00:45:44Z
expires_at: 2026-07-23T00:55:44Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #819 issue: #635 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 18405-51fd8b8a8672 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-819 phase: claimed candidate_head: b2f6e9a6dc40e9651ef876f322dd0a68bddebfd8 target_branch: master target_branch_sha: 14c9c4d702055056ff1b25aa93aa6b55df79d1ac last_activity: 2026-07-23T00:45:44Z expires_at: 2026-07-23T00:55:44Z blocker: none

sysadmin approved these changes 2026-07-22 19:48:14 -05:00

sysadmin left a comment

Review Summary for PR #819 (Owning Issue #635)

Verification Evidence & Findings

Acceptance Criteria:
- AC1 (Versioned API documented): New docs/webui-project-registry-api.md documents routes, fields, response shapes, and fail-closed error contracts. Updated docs/webui-local-dev.md.
- AC2 (Status + onboarding checklist): Exposed in webui/project_registry.py (PROJECT_STATUSES, ONBOARDING_STATES, OnboardingSummary, ProjectHealth). Serialized in project_to_dict.
- AC3 (Invalid registry fails closed): Structured RegistryError raised with actionable remediation, field_path, and source_path. HTTP 500 JSON error or fail-closed HTML error page.
- AC4 (Tests cover valid/missing/schema validation): tests/test_webui_project_registry.py covers load, defaults, enum checks, missing fields, invalid JSON, missing file, credential rejection, and v1/v2 schema compatibility.
- AC5 (HTML views share DTO): webui/project_views.py renders all views using project_to_dict.
Diff Scope:
- Exactly 7 files changed (+1211 / -93 lines against base master).
- No untracked, credential, local-state, or generated files included.
Security & Boundaries:
- Read-only API surface (GET routes only).
- Credential keys strictly forbidden by recursive _reject_credential_keys guard using webui.registry_safety.is_forbidden_key.
Validation:
- Focused suite (pytest tests/test_webui_project_registry.py): 30 passed, 22 subtests passed.
- Affected Web UI suites (pytest tests/ -k "webui or registry or project"): 199 passed.
- Full test suite (pytest tests/): 4340 passed, with 11 pre-existing failures matching baseline.
- Reviewer worktree clean. Head SHA: b2f6e9a6dc40e9651ef876f322dd0a68bddebfd8.

## Review Summary for PR #819 (Owning Issue #635) ### Verification Evidence & Findings 1. **Acceptance Criteria**: - **AC1 (Versioned API documented)**: New `docs/webui-project-registry-api.md` documents routes, fields, response shapes, and fail-closed error contracts. Updated `docs/webui-local-dev.md`. - **AC2 (Status + onboarding checklist)**: Exposed in `webui/project_registry.py` (`PROJECT_STATUSES`, `ONBOARDING_STATES`, `OnboardingSummary`, `ProjectHealth`). Serialized in `project_to_dict`. - **AC3 (Invalid registry fails closed)**: Structured `RegistryError` raised with actionable `remediation`, `field_path`, and `source_path`. HTTP 500 JSON error or fail-closed HTML error page. - **AC4 (Tests cover valid/missing/schema validation)**: `tests/test_webui_project_registry.py` covers load, defaults, enum checks, missing fields, invalid JSON, missing file, credential rejection, and v1/v2 schema compatibility. - **AC5 (HTML views share DTO)**: `webui/project_views.py` renders all views using `project_to_dict`. 2. **Diff Scope**: - Exactly 7 files changed (+1211 / -93 lines against base master). - No untracked, credential, local-state, or generated files included. 3. **Security & Boundaries**: - Read-only API surface (`GET` routes only). - Credential keys strictly forbidden by recursive `_reject_credential_keys` guard using `webui.registry_safety.is_forbidden_key`. 4. **Validation**: - Focused suite (`pytest tests/test_webui_project_registry.py`): **30 passed, 22 subtests passed**. - Affected Web UI suites (`pytest tests/ -k "webui or registry or project"`): **199 passed**. - Full test suite (`pytest tests/`): **4340 passed**, with 11 pre-existing failures matching baseline. - Reviewer worktree clean. Head SHA: `b2f6e9a6dc40e9651ef876f322dd0a68bddebfd8`.

sysadmin commented

2026-07-22 19:48:26 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #819
issue: #635
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 18405-51fd8b8a8672
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-819
phase: released
candidate_head: b2f6e9a6dc
target_branch: master
target_branch_sha: 14c9c4d702
last_activity: 2026-07-23T00:48:26Z
expires_at: 2026-07-23T00:58:26Z
blocker: manual-release

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #819 issue: #635 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 18405-51fd8b8a8672 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-819 phase: released candidate_head: b2f6e9a6dc40e9651ef876f322dd0a68bddebfd8 target_branch: master target_branch_sha: 14c9c4d702055056ff1b25aa93aa6b55df79d1ac last_activity: 2026-07-23T00:48:26Z expires_at: 2026-07-23T00:58:26Z blocker: manual-release

sysadmin commented

2026-07-22 20:02:41 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #819
issue: #635
reviewer_identity: sysadmin
profile: prgs-merger
session_id: 46833-d34684c5717a
worktree: /Users/jasonwalker/Development/Gitea-Tools
phase: claimed
candidate_head: b2f6e9a6dc
target_branch: master
target_branch_sha: 14c9c4d702
last_activity: 2026-07-23T01:02:40Z
expires_at: 2026-07-23T01:12:40Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #819 issue: #635 reviewer_identity: sysadmin profile: prgs-merger session_id: 46833-d34684c5717a worktree: /Users/jasonwalker/Development/Gitea-Tools phase: claimed candidate_head: b2f6e9a6dc40e9651ef876f322dd0a68bddebfd8 target_branch: master target_branch_sha: 14c9c4d702055056ff1b25aa93aa6b55df79d1ac last_activity: 2026-07-23T01:02:40Z expires_at: 2026-07-23T01:12:40Z blocker: none

sysadmin merged commit 53c2c92782 into master

2026-07-22 20:04:27 -05:00

sysadmin commented

2026-07-22 20:04:29 -05:00

Stale #332 review-decision lock cleanup (#594)

Status: APPLIED

actor: sysadmin
profile: prgs-merger
timestamp: 2026-07-23T01:04:28.923939+00:00
last terminal: approve on PR feat(webui): versioned project registry API (Closes #635) (#819)
PR state: closed (merged=True)
merge_commit_sha: 53c2c92782fdb4b3ac4af922e6814f345141f82f
prior live_mutations_count: 1
prior profile_identity: prgs-reviewer

Manual deletion of session-state files is not the workflow.
This path only clears a lock when the referenced PR is merged/closed.

## Stale #332 review-decision lock cleanup (#594) Status: **APPLIED** - actor: `sysadmin` - profile: `prgs-merger` - timestamp: `2026-07-23T01:04:28.923939+00:00` - last terminal: `approve` on PR #819 - PR state: `closed` (merged=True) - merge_commit_sha: `53c2c92782fdb4b3ac4af922e6814f345141f82f` - prior live_mutations_count: `1` - prior profile_identity: `prgs-reviewer` Manual deletion of session-state files is **not** the workflow. This path only clears a lock when the referenced PR is merged/closed.

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#819