SiteWeaver_CMS/MILESTONES.yaml

milestones:
  # Milestone 0: Project Foundation & Setup
  milestone_0_project_foundation:
    status: COMPLETE
    description: >-
      Set up the project structure, Composer dependencies, autoloading,
      and basic bootstrap files. This establishes the base for all subsequent
      development.
    what_is_built:
      - Directory layout (src/, config/, public/, site/, tests/)
      - composer.json with required packages (composer.lock will be generated)
      - Basic bootstrap script (config/bootstrap.php) initializing autoloader,
        DI container, and environment variables.
      - PSR-4 autoloading mapping for core, plugins, themes, admin_themes.
    tests_to_run:
      - Run Composer install validation test
      - Verify autoloaded classes can be instantiated
    artifacts:
      created:
        - composer.json (already present)
        - src/Site/
        - config/bootstrap.php
        - vendor/ (via Composer)
        - .gitignore entries for vendor, storage/, etc.
      modified: []
      deleted: []
    completion_criteria:
      - All files listed above exist and are syntactically correct
      - composer install succeeds without errors
      - Autoloader loads core namespace classes (SiteWeaver\Core)
      - Tests in this milestone pass

  # Milestone 1: Configuration & Environment Management
  milestone_1_configuration:
    status: COMPLETE
    description: >-
      Implement environment configuration loading, Infisical integration,
      and .env handling. This provides secure runtime secrets and
      environment-specific settings for the application.
    what_is_built:
      - Config class to load from env variables and Infisical SDK
      - Integration with Nginx-provided env vars (INFISICAL_URL, etc.)
      - Example config files: config/.env.example
      - Secret retrieval logic using infisical/php-sdk
    tests_to_run:
      - Unit test for Config class reading env vars
      - Integration test that a sample secret is fetched correctly
    artifacts:
      created:
        - src/Site/Core/Config.php
        - config/.env.example
        - composer.json entry for infisical/php-sdk (if not already)
      modified:
        - config/bootstrap.php to load Config
      deleted: []
    completion_criteria:
      - Config can read required secrets from env and Infisical
      - Secrets are available to services via DI container
      - Tests pass

  # Milestone 2: Core Infrastructure – Router, DI Container, Service Provider
  milestone_2_core_infrastructure:
    status: COMPLETE
    description: >-
      Build the custom routing engine, lightweight dependency injection container,
      and service provider pattern that will be used throughout the application.
    what_is_built:
      - core/router/engine (custom router with middleware support)
      - core/container (simple DI container)
      - core/services/providers (ServiceProvider base class)
      - Integration of these components in bootstrap
    tests_to_run:
      - Unit test for routing variable parsing and named routes
      - Unit test for DI container resolution and singleton scopes
      - Feature test for middleware execution order
    artifacts:
      created:
        - src/Site/Core/Router.php
        - src/Site/Core/Container.php
        - src/Site/Core/ServiceProvider.php
        - tests/unit/Core/
      modified:
        - config/bootstrap.php to register container and router
      deleted: []
    completion_criteria:
      - Router correctly matches routes, supports middleware, named URLs
      - DI container resolves dependencies and injects services
      - Service providers can register routes, migrations, etc.
      - Tests pass

  # Milestone 3: Authentication & Authorization Core
  milestone_3_authentication_authorization:
    status: TODO
    description: >-
      Implement user management, roles, permissions, login, logout, session handling,
      and TOTP-based two‑factor authentication. This forms the security backbone
      of the CMS.
    what_is_built:
      - User model, Role model, Permission model, RolePermission pivot, UserRole pivot
      - AuthService (login/logout, password hashing)
      - SessionService (server‑side session storage)
      - TOTPService for 2FA
      - Middleware: auth, role, permission checks
    tests_to_run:
      - Unit test for password hash and verification
      - Integration test for login flow with TOTP
      - Feature test for access control on admin routes
    artifacts:
      created:
        - src/Site/Core/Models/User.php
        - src/Site/Core/Services/AuthService.php
        - src/Site/Core/Services/TOTPService.php
        - src/Site/Core/Middleware/AuthMiddleware.php
        - tests/unit/Authentication/
      modified:
        - config/bootstrap.php to register AuthService, SessionService, TOTPService
      deleted: []
    completion_criteria:
      - Users can create accounts, login with password and 2FA
      - Sessions persist across requests
      - Role & permission checks enforce access control
      - Tests pass

  # Milestone 4: Admin Dashboard Skeleton
  milestone_4_admin_dashboard_skeleton:
    status: TODO
    description: >-
      Provide a basic admin interface with navigation, dashboard views for users,
      roles, pages, posts, media, and plugins. This gives admins an entry point
      to manage the CMS.
    what_is_built:
      - Admin layout template (layout.php)
      - Dashboard controller & view templates
      - Basic CRUD controllers for Users, Roles, Pages, Posts, Media, Plugins, Themes
      - Routing entries for admin routes
    tests_to_run:
      - Feature test for accessing dashboard as Admin
      - Unit test for admin route middleware enforcement
    artifacts:
      created:
        - src/Site/Controllers/Admin/DashboardController.php
        - resources/views/admin/dashboard.php
        - config/routes/admin.php
        - tests/feature/AdminDashboard/
      modified:
        - config/bootstrap.php to register routes
      deleted: []
    completion_criteria:
      - Admin dashboard loads for users with Admin role
      - CRUD pages show appropriate forms and data
      - Tests pass

  # Milestone 5: Media Manager Core
  milestone_5_media_manager_core:
    status: TODO
    description: >-
      Implement file upload, storage abstraction (Local Disk, S3, Nextcloud,
      Linode), JIT image generation with Glide, preview cache warming, and orphaned
      media watcher.
    what_is_built:
      - StorageInterface definition
      - Concrete implementations for each backend
      - MediaService handling uploads, metadata, and deletion
      - JIT generation service using Glide
      - CacheWarmingService for publish/preview caching
      - OrphanedMediaWatcher background job
    tests_to_run:
      - Unit test for storage interface methods
      - Integration test uploading image to each backend
      - Feature test for preview cache warming after publishing a page
    artifacts:
      created:
        - src/Site/Core/StorageInterface.php
        - src/Site/Providers/LocalDiskStorageProvider.php
        - src/Site/Providers/S3StorageProvider.php
        - src/Site/Services/MediaService.php
        - src/Site/Services/JITGenerationService.php
      modified:
        - config/bootstrap.php to register storage providers
      deleted: []
    completion_criteria:
      - Images can be uploaded and retrieved from each backend
      - JIT-generated variants are correctly cached
      - Orphaned media detection works
      - Tests pass

  # Milestone 6: Plugin Architecture Core
  milestone_6_plugin_architecture_core:
    status: TODO
    description: >-
      Build the plugin system that allows ZIP uploads, automatic migrations,
      service provider registration, dependency resolution, and security audits.
    what_is_built:
      - PluginManager to discover, install, activate, deactivate plugins
      - SecurityAuditService for evaluating plugins on upload
      - Modular migration runner integrated with Phinx
      - API for plugin developers: plugin.md metadata schema, ServiceProvider base
    tests_to_run:
      - Unit test for PluginManager installation flow
      - Integration test that a sample plugin's migrations run
      - Feature test that an installed plugin registers its routes and services
    artifacts:
      created:
        - src/Site/Services/PluginManager.php
        - src/Site/Providers/PluginServiceProvider.php
        - tests/unit/Plugins/
      modified:
        - config/bootstrap.php to register PluginManager
      deleted: []
    completion_criteria:
      - ZIP upload installs plugin, runs migrations, registers services
      - Security audit blocks malicious code
      - Tests pass

  # Milestone 7: Theme Architecture Core
  milestone_7_theme_architecture_core:
    status: TODO
    description: >-
      Implement theme installation, activation, asset pipeline (Vite), theme editor,
      and metadata handling. Themes should be selectable for frontend and admin.
    what_is_built:
      - ThemeManager to install/uninstall/activate themes
      - Asset build step using Vite that outputs CSS/JS to public/build
      - ThemeEditor component integration with Vue (SFCs)
      - Theme service provider registration
    tests_to_run:
      - Unit test for ThemeManager activation logic
      - Integration test that a theme's assets are compiled and served
      - Feature test that switching themes updates the layout
    artifacts:
      created:
        - src/Site/Services/ThemeManager.php
        - resources/themes/default (sample)
        - config/routes/theme.php
        - tests/unit/Themes/
      modified:
        - config/bootstrap.php to register ThemeManager
      deleted: []
    completion_criteria:
      - Themes can be installed via ZIP, activated, and provide assets
      - Switching themes updates frontend/admin rendering
      - Tests pass

  # Milestone 8: Page Builder Core
  milestone_8_page_builder_core:
    status: TODO
    description: >-
      Provide CRUD for pages, versioning, publishing workflow, navigation inclusion,
      and a rich text editor (clean HTML output). Pages are stored with locale‑specific
      JSON content.
    what_is_built:
      - Page model, PageVersion model
      - PageController handling create/edit/delete/publish
      - WYSIWYG editor integration (e.g., TinyMCE or custom)
      - NavigationService to generate site navigation based on pages
    tests_to_run:
      - Unit test for page versioning logic
      - Integration test that a published page appears at its slug URL
      - Feature test that navigation includes active pages
    artifacts:
      created:
        - src/Site/Models/Page.php
        - src/Site/Models/PageVersion.php
        - src/Site/Controllers/PageController.php
        - resources/views/page_builder/*.php
      modified:
        - config/routes/frontend.php (add page route)
      deleted: []
    completion_criteria:
      - Pages can be created, edited, versioned, and published
      - Published pages are publicly accessible via slug URLs
      - Navigation reflects included pages
      - Tests pass

  # Milestone 9: Blog Plugin Core
  milestone_9_blog_plugin_core:
    status: TODO
    description: >-
      Implement the built‑in blog plugin with CRUD for posts, categories, tags,
      comments, spam protection (Akismet, honeypot, rate limiting), and translation.
    what_is_built:
      - BlogPost model, BlogPostVersion, Category, Tag models
      - BlogController handling post management
      - CommentService with Akismet integration
      - SpamProtection middleware
      - Admin UI for managing posts/categories/tags/comments
    tests_to_run:
      - Unit test for comment spam detection logic
      - Integration test that a new post is published and accessible
      - Feature test that comments can be added and moderated
    artifacts:
      created:
        - site/plugins/blog (plugin directory)
        - src/Site/Plugins/BlogPluginServiceProvider.php
        - resources/views/blog/*.php
      modified:
        - config/bootstrap.php to register Blog plugin provider
      deleted: []
    completion_criteria:
      - Posts can be created, edited, published, and commented on
      - Spam protection blocks malicious comments
      - Tests pass

  # Milestone 10: Search Functionality Core
  milestone_10_search_functionality_core:
    status: TODO
    description: >-
      Provide full‑text search for posts and pages, faceted filters (categories,
      tags, date ranges), and dynamic filtering UI. Results are paginated.
    what_is_built:
      - SearchService using database full-text indexes or external engine
      - FacetController handling filter submissions
      - Views for search results with pagination
    tests_to_run:
      - Unit test for search query building
      - Integration test that searching by keyword returns expected posts/pages
      - Feature test that applying facets narrows results correctly
    artifacts:
      created:
        - src/Site/Services/SearchService.php
        - src/Site/Controllers/FacetController.php
        - resources/views/search/*.php
      modified:
        - config/routes/frontend.php (add search route)
      deleted: []
    completion_criteria:
      - Search returns correct results and respects facets
      - Pagination works
      - Tests pass

  # Milestone 11: i18n System Core
  milestone_11_i18n_system_core:
    status: TODO
    description: >-
      Implement translation engine, locale detection from URL, content localization,
      and the t() helper for UI strings. Supports multiple languages per site.
    what_is_built:
      - LocaleService to detect locale via URL or Accept‑Language header
      - TranslationService backed by database table translations (or JSON)
      - t() helper function exposed globally
      - Integration of translation into page and blog content storage (locale columns/JSON)
    tests_to_run:
      - Unit test for locale detection logic
      - Integration test that translated strings appear in UI
      - Feature test that switching locale changes displayed content
    artifacts:
      created:
        - src/Site/Core/Services/LocaleService.php
        - src/Site/Core/Services/TranslationService.php
        - app/helpers.php (t() function)
      modified:
        - config/bootstrap.php to register services
      deleted: []
    completion_criteria:
      - UI strings are translated based on locale
      - Content is stored and rendered per locale
      - Tests pass

  # Milestone 12: Backup & Restore Core
  milestone_12_backup_restore_core:
    status: TODO
    description: >-
      Provide manual backup of site files and database, and restore functionality.
      Backups are ZIP archives containing the CMS directory and SQL dump. Restores
      replace current data with a chosen backup.
    what_is_built:
      - BackupService to create zip + DB dump (sqldump)
      - RestoreService to unpack archive and import SQL
      - Admin UI triggers for backup/restore actions
    tests_to_run:
      - Unit test for backup file generation
      - Integration test that restore restores data correctly
    artifacts:
      created:
        - src/Site/Core/Services/BackupService.php
        - src/Site/Core/Services/RestoreService.php
        - resources/views/admin/backup.php
      modified:
        - config/routes/admin.php (add backup routes)
      deleted: []
    completion_criteria:
      - Backups can be created and downloaded
      - Restore replaces current data without corruption
      - Tests pass

  # Milestone 13: Performance Optimization Core
  milestone_13_performance_optimization_core:
    status: TODO
    description: >-
      Implement caching strategy (in‑memory + file), lazy loading of related data,
      and query optimization. This ensures fast response times for high traffic.
    what_is_built:
      - CacheService with in-memory (array) fallback and file-based storage
      - QueryBuilder extensions to eager load relationships
      - Configuration options for cache TTLs
    tests_to_run:
      - Unit test for caching logic
      - Integration test that cached pages are served on subsequent requests
    artifacts:
      created:
        - src/Site/Core/Services/CacheService.php
        - src/Site/Core/Extensions/QueryBuilder.php
      modified:
        - config/bootstrap.php to register CacheService
      deleted: []
    completion_criteria:
      - Pages and posts are served from cache when available
      - Lazy loading reduces database queries
      - Tests pass

  # Milestone 14: Security Hardening Core
  milestone_14_security_hardening_core:
    status: TODO
    description: >-
      Strengthen application security by enforcing input validation, limiting
      file uploads, protecting against XSS/CSRF, and handling lockout policies.
    what_is_built:
      - InputValidator service for form data
      - CSRF token middleware
      - File upload size/type checks
      - Login attempt tracking & lockout enforcement
    tests_to_run:
      - Unit test for validator rules
      - Integration test that invalid uploads are rejected
      - Feature test that account is locked after failed attempts
    artifacts:
      created:
        - src/Site/Core/Services/InputValidator.php
        - src/Site/Middleware/CsrfMiddleware.php
        - src/Site/Middleware/LoginLockoutMiddleware.php
      modified:
        - config/bootstrap.php to register middlewares
      deleted: []
    completion_criteria:
      - Invalid inputs are rejected with proper error messages
      - Uploads adhere to MIME and size limits
      - Lockout policy functions correctly
      - Tests pass

  # Milestone 15: Testing Infrastructure
  milestone_15_testing_infrastructure:
    status: TODO
    description: >-
      Set up Codeception test suite, including unit, feature, integration,
      and behavior tests. Configure CI to run these tests automatically.
    what_is_built:
      - codeception.yml configuration
      - base TestCase classes
      - sample unit & feature tests for core services
      - CI workflow file (forgejo-actions.yml)
    tests_to_run:
      - Run all existing Codeception suites
    artifacts:
      created:
        - tests/unit/
        - tests/feature/
        - tests/integration/
        - codeception.yml
        - .forgejo/actions/ci.yml
      modified:
        - composer.json to include phpunit/codeception dev dependencies
      deleted: []
    completion_criteria:
      - All test suites run successfully locally and in CI
      - Code coverage meets 95% target

  # Milestone 16: CI Integration
  milestone_16_ci_integration:
    status: TODO
    description: >-
      Configure Forgejo Actions to automatically run tests on pull requests,
      pre‑merge, and nightly. Ensure the build pipeline covers linting, static analysis,
      and test execution.
    what_is_built:
      - forgejo-actions.yml workflow file
      - Dockerfile or CI image with required PHP, Composer, Node (for Vite)
      - Linting steps using PHP CS Fixer, PHPStan, Psalm
    tests_to_run:
      - Verify CI pipeline passes on a sample PR
    artifacts:
      created:
        - .forgejo/actions/ci.yml
      modified: []
      deleted: []
    completion_criteria:
      - CI runs linting and tests automatically
      - No failures on PR or nightly builds

  # Milestone 17: Full Verification
  milestone_18_full_verification:
    status: TODO
    description: >-
      Run the complete test suite, perform end‑to‑end verification of all features,
      confirm no regressions, and validate deployment readiness.
    what_is_built:
      - None (verification only)
    tests_to_run:
      - All unit, feature, integration, behavior tests
      - End-to-end smoke tests covering login, page creation, blog post publishing, media upload, etc.
    artifacts:
      created: []
      modified: []
      deleted: []
    completion_criteria:
      - Every test passes without flakiness
      - Manual end‑to‑end checks succeed
      - Application is ready for release