SiteWeaver_CMS/MILESTONES.yaml

milestones:
  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:
    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:
    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:
    status: COMPLETE
    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_database_and_repositories:
    status: TODO
    description: >-
      Create the core database schema defined in APP.yaml, write Phinx migrations,
      and implement repository interfaces that replace the current in‑memory arrays.
      All services (AuthService, SessionService, TOTPService) will use these
      repositories. The migrations are already present in `database/migrations` – we
      just need to verify them and ensure they run cleanly on all supported engines.
    what_is_built:
      - src/Site/Core/Database/Migrations/*   # existing migration files
      - src/Site/Core/Repositories/UserRepository.php
      - src/Site/Core/Repositories/RoleRepository.php
      - src/Site/Core/Repositories/PageRepository.php
      - src/Site/Core/Providers/AuthServiceProvider.php  # now injects UserRepository, RoleRepository, etc.
    tests_to_run:
      - Unit test that migrations run cleanly on SQLite/MySQL/PostgreSQL
      - Integration test that AuthService can load users via the repository
      - Feature test that creating a user persists to the DB and survives a restart

  milestone_5_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_6_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
    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_7_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

  milestone_8_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_9_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_10_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

  milestone_11_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

  milestone_12_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

  milestone_13_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

  milestone_14_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

  milestone_15_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:

  milestone_16_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:

  milestone_17_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:

  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