Skip to content

version-config.md

Latest commit

 

History

History
237 lines (168 loc) · 12.9 KB

version-config.md

File metadata and controls

237 lines (168 loc) · 12.9 KB

Feature: Version & Config Management

  • p2 - ID: cpt-cypilot-featstatus-version-config

1. Feature Context

  • p2 - cpt-cypilot-feature-version-config

1. Overview

Enables project skill updates with config migration, and provides CLI commands for managing ignore lists and kit registrations. System definitions are managed in artifacts.toml (per cpt-cypilot-adr-remove-system-from-core-toml). The update command refreshes .core/ from cache, detects and auto-restructures old directory layouts, migrates bundled kit references to GitHub sources (versions < 3.0.8), and ensures config/ scaffold files exist without overwriting user content. Kit file updates are a separate operation via cpt kit update.

2. Purpose

Ensures teams can upgrade Cypilot without losing configuration or customizations. Config CLI commands eliminate manual TOML editing and enforce schema validation. Addresses PRD requirements for version management (cpt-cypilot-fr-core-version) and CLI configuration (cpt-cypilot-fr-core-cli-config).

3. Actors

Actor Role in Feature
cpt-cypilot-actor-user Runs cpt update, cpt config, cpt migrate-config
cpt-cypilot-actor-cypilot-cli Executes update pipeline, config mutations, migration

4. References

  • PRD: PRD.md — cpt-cypilot-fr-core-version, cpt-cypilot-fr-core-layout-migration, cpt-cypilot-fr-core-cli-config
  • Design: DESIGN.md — cpt-cypilot-component-config-manager, cpt-cypilot-seq-update
  • Dependencies: cpt-cypilot-feature-core-infra, cpt-cypilot-feature-blueprint-system

2. Actor Flows (CDSL)

Update Project Installation

  • p1 - ID: cpt-cypilot-flow-version-config-update

Actor: cpt-cypilot-actor-user

Success Scenarios:

  • User runs cpt update → .core/ refreshed from cache, old layout auto-restructured if detected, bundled kit refs migrated to GitHub sources, config scaffold ensured
  • Bundled kit (no source field) → auto-migrated to GitHub source

Error Scenarios:

  • Cypilot not initialized → error with hint to run cpt init
  • Cache not available → error with hint to check network

Steps:

  1. - p1 - User invokes cpt update [--project-root P] [--dry-run] - inst-user-update
  2. - p1 - Resolve project root and cypilot directory - inst-resolve-project
  3. - p1 - Replace .core/ from cache (always force-overwrite) - inst-replace-core
  4. - p1 - Detect directory layout; if old layout detected, trigger automatic restructuring using cpt-cypilot-algo-version-config-layout-restructure - inst-detect-layout
  5. - p1 - Migrate {cypilot_path}/config/core.toml preserving all user settings - inst-migrate-config
  6. - p1 - IF core.toml contains [system] section, remove it (system identity is defined in artifacts.toml per cpt-cypilot-adr-remove-system-from-core-toml); log removal in update report - inst-remove-system-section
  7. - p1 - Migrate bundled kit references to GitHub sources (add source field for kits without one) - inst-migrate-kit-sources
  8. - p1 - FOR EACH registered kit: IF kit source contains manifest.toml and core.toml has no [kits.{slug}.resources] section, trigger legacy manifest migration via cpt-cypilot-algo-kit-manifest-legacy-migration (Feature 2 boundary) - inst-manifest-legacy-migration
  9. - p1 - Ensure config scaffold files exist (create only if missing) - inst-ensure-scaffold
  10. - p1 - Regenerate agent entry points - inst-regenerate-agents
  11. - p1 - Run self-check to verify kit integrity (run_self_check_from_meta); include result in report, WARN if failed - inst-self-check
  12. - p1 - RETURN update report with actions taken and self-check result - inst-return-report
  13. - p1 - Imports, constants, and module setup for update command - inst-update-imports
  14. - p1 - Display core whatsnew entries (cache vs installed) before applying update - inst-whatsnew
  15. - p1 - Helper functions: ensure file creation, config README, auto-regenerate agents, read/show whatsnew - inst-update-helpers
  16. - p1 - Human-friendly formatter for update report output - inst-update-format-output

Manage Config via CLI

  • p2 - ID: cpt-cypilot-flow-version-config-manage

Actor: cpt-cypilot-actor-user

Success Scenarios:

  • User runs cpt config show → displays current core.toml contents
  • User runs cpt config system add → adds system definition to artifacts.toml with schema validation

Steps:

  1. - p2 - User invokes cpt config <subcommand> [args] - inst-user-config
  2. - p2 - Validate change against config schema - inst-validate-schema
  3. - p2 - Apply change to config file - inst-apply-change
  4. - p2 - RETURN summary of what was modified - inst-return-config-summary

3. Processes / Business Logic (CDSL)

Update Pipeline

  • p1 - ID: cpt-cypilot-algo-version-config-update-pipeline
  1. - p1 - Replace .core/ from cache - inst-replace-core-algo
  2. - p1 - Detect and auto-restructure old directory layout - inst-detect-layout-algo
  3. - p1 - Migrate {cypilot_path}/config/core.toml - inst-migrate-config-algo
  4. - p1 - Remove [system] section from core.toml if present (per cpt-cypilot-adr-remove-system-from-core-toml) - inst-remove-system-section-algo
  5. - p1 - Migrate bundled kit references to GitHub sources (add source field) - inst-migrate-kit-sources-algo
  6. - p1 - Trigger legacy manifest migration for kits updated to manifest-driven versions without existing resource bindings - inst-manifest-legacy-migration-algo
  7. - p1 - Helper: check manifest presence and resource binding state before triggering migration - inst-manifest-legacy-migration-helper
  8. - p1 - (Removed — no separate regen step; kit files are updated directly) - inst-regen-algo
  9. - p1 - Ensure config scaffold - inst-scaffold-algo

Layout Restructuring

  • p1 - ID: cpt-cypilot-algo-version-config-layout-restructure

Input: Cypilot directory path

Output: Restructured directory layout or no-op if already new layout

Detection: Old layout is detected when {cypilot_path}/.gen/kits/{slug}/ exists.

Steps:

  1. - p1 - Backup affected directories - inst-layout-backup
  2. - p1 - Move generated outputs: .gen/kits/{slug}/ → config/kits/{slug}/ - inst-layout-move-gen
  3. - p1 - Remove old kits/{slug}/ reference copies if present - inst-layout-remove-refs
  4. - p1 - Remove .gen/kits/ directory (preserve .gen/AGENTS.md, .gen/SKILL.md, .gen/README.md) - inst-layout-clean-gen
  5. - p1 - Update core.toml kit registrations with new paths (config/kits/{slug}) - inst-layout-update-core
  6. - p1 - IF any step fails, restore from backup and report error - inst-layout-rollback

Supporting:

  • - p1 - Migrate single entry from old kits/{slug}/ directory to new layout - inst-migrate-kits-entry
  • - p1 - Migrate single entry from old .gen/kits/{slug}/ directory to config - inst-migrate-gen-entry
  • - p1 - Update kit path registrations in core.toml after layout migration - inst-update-core-paths

Compare Blueprint Versions (LEGACY)

  • p1 - ID: cpt-cypilot-algo-version-config-compare-versions

LEGACY: Blueprint version comparison is preserved for backward compatibility with v2/early-v3 installations. New kit updates use file-level diff.

    • p1 - Read @cpt:blueprint TOML block from each blueprint to extract version - inst-read-versions
    • p1 - Compare cache version vs user version per blueprint - inst-compare-per-bp
    • p1 - RETURN current (same), migration_needed (higher), or missing - inst-return-comparison

Migrate Config

  • p2 - ID: cpt-cypilot-algo-version-config-migrate
    • p2 - Create backup of current config - inst-backup
    • p2 - Apply migration rules preserving user settings - inst-apply-migration
    • p2 - Report any settings that could not be migrated - inst-report-unmigrated

4. States (CDSL)

Installation Version State

  • p1 - ID: cpt-cypilot-state-version-config-installation
[CURRENT] --new-cache-available--> [OUTDATED] --update--> [CURRENT]
[OUTDATED] --update-with-migration--> [MIGRATION_NEEDED] --manual-resolve--> [CURRENT]

5. Definitions of Done

Update Command

  • p1 - ID: cpt-cypilot-dod-version-config-update

  • - p1 - cpt update replaces .core/ from cache

  • - p1 - cpt update detects old directory layout and auto-restructures (move generated outputs from .gen/kits/ to config/kits/, remove old reference copies)

  • - p1 - cpt update migrates bundled kit references to GitHub sources (versions < 3.0.8)

  • - p1 - User config files in config/ are NEVER overwritten

  • - p1 - [LEGACY] Blueprint version comparison detects same, migration needed, and missing states

  • - p1 - cpt update renders whatsnew ANSI styling only when stderr is a TTY; redirected or piped stderr stays plain text

  • - p1 - cpt update removes leftover config/kits/*/blueprints/ directories from pre-ADR-0001 installs

  • - p1 - cpt update removes legacy [system] section from config/core.toml (system identity now lives in artifacts.toml)

  • - p1 - cpt update auto-migrates legacy kits to manifest-driven resource bindings when source contains manifest.toml and core.toml lacks [kits.{slug}.resources]

Config CLI Commands

  • p2 - ID: cpt-cypilot-dod-version-config-cli

  • - p2 - cpt config show displays current configuration

  • - p2 - cpt config system add/remove manages system definitions in artifacts.toml

  • - p2 - Schema validation rejects invalid changes before writing

Config Migration

  • p2 - ID: cpt-cypilot-dod-version-config-migration

  • - p2 - cpt migrate-config migrates legacy JSON configs to TOML

  • - p2 - Backup created before any migration

  • - p2 - User settings preserved across version upgrades

ralphex Integration Settings

  • p1 - ID: cpt-cypilot-dod-version-config-ralphex-settings

The Config Manager MUST persist resolved ralphex executable path and related integration settings in core.toml so that future delegation does not require re-discovery. Settings are stored under a dedicated [integrations.ralphex] section in core.toml.

Persisted settings:

  • executable_path — resolved absolute path to the ralphex binary

Note: plans_dir and other execution-time settings are owned by ralphex's own config precedence chain (CLI flags > local .ralphex/ > global ~/.config/ralphex/ > embedded defaults). Cypilot does not duplicate or override ralphex's plans_dir resolution — it queries ralphex at export time to determine the active plans directory.

Implements:

  • cpt-cypilot-component-config-manager (see cpt-cypilot-adr-ralphex-delegation-skill)

6. Implementation Modules

Module Path Responsibility
Update Command skills/.../commands/update.py Update pipeline, layout restructuring, file-level kit diff

7. Acceptance Criteria

  • cpt update refreshes .core/ without touching user config
  • cpt update detects and auto-restructures old directory layout with backup and rollback
  • cpt update migrates bundled kit references to GitHub sources (versions < 3.0.8)
  • [LEGACY] Blueprint version comparison correctly identifies same, migration needed, and missing states
  • cpt config show displays readable config summary
  • Config migration preserves all user settings with backup
  • core.toml [integrations.ralphex] section persists resolved executable path
  • cpt update automatically runs self-check after update and reports WARN if integrity check fails