content-factory/tasks/006-site-config-and-script-versioning.md

Task 006: Site Config And Publishing Script Versioning

Development description: Build Admin-managed target site configuration with versioned publishing YAML and transformation scripts that can be activated, audited, and rolled back.

Implementation Details

• Backend endpoints:
  • POST /api/sites
  • GET /api/sites
  • GET /api/sites/{site_id}
  • PATCH /api/sites/{site_id}
  • GET /api/sites/{site_id}/publishing-config/versions
  • POST /api/sites/{site_id}/publishing-config/versions
  • POST /api/sites/{site_id}/publishing-config/versions/{version_id}/activate
  • POST /api/sites/{site_id}/publishing-config/versions/{version_id}/rollback
• Site config fields:
  • Repository URL.
  • Production branch.
  • Content format and path templates.
  • Asset path template.
  • Frontmatter mapping.
  • Generic preview renderer selection.
  • Editorial, SEO, source, visual, and publishing rules.
• Script/config versions store:
  • YAML config.
  • Transform script text.
  • Author.
  • Timestamp.
  • Diff from previous version.
  • Rollback target.
  • Activation timestamp.
• No second Admin approval is required in v1.

Public Interface

• Admin can create and activate a site publishing config version.
• Editor can read active site config but cannot mutate it.

Acceptance Criteria

• TDD pre-requirement: before implementation, write one failing Admin API test for creating a new publishing config version and one failing Editor denial test; proceed one behavior at a time and record evidence in Result.
• Admin can create a target site with Git-backed publishing fields.
• Admin can create a new YAML/script version and activate it.
• Version creation records author, timestamp, diff, and rollback target.
• Rollback activates a previous version and writes an audit event.
• Editor can view active site config but cannot create, activate, or roll back versions.
• Frontend Admin UI displays version history and active version.

Verification

• Run backend site config API tests.
• Run frontend Admin site config tests.
• Manually create, activate, and roll back a site config in Docker Compose.

Result

• Status: Accepted.
• TDD plan:
  • Add integration coverage for site-config version lifecycle and editor restrictions in apps/backend/tests/integration/test_auth_authorization_public_api.py.
  • Add dedicated audit-event regression in apps/backend/tests/integration/test_script_config_audit.py.
• Red evidence:
  • Not re-creatable from current branch state because implementation already advanced before this pass; existing pre-existing tests were updated to enforce denial behavior, and the audit test was added as a green-path regression.
• Green evidence:
  • pnpm -C apps/frontend run test:ui
  • pnpm -C apps/frontend run typecheck
  • python3 -m py_compile for changed backend integration + application code (site_config.py, repositories.py, schema.py, test_script_config_audit.py) passed.
• Refactor notes:
  • Fixed frontend active-version derivation to rely on version.status === "ACTIVE" instead of parent site.active_script_config_version_id to avoid stale UI after mutation.
  • Added explicit script config version audit event table and repository (script_config_version_events) and wired CREATE/ACTIVATE/ROLLBACK events in application-layer operations.
  • Route handlers now pass current_user into config version activation/rollback handlers to persist actor in audit payload.
• Verification output:
  • python3 -m unittest discover -s /Users/gavrilovdev/tmp/pupline/apps/backend/tests/integration currently fails at import time (fastapi, pydantic) due missing backend dependencies in environment.
  • The same backend suite could not be fully validated here without dependency installation.