config-helper

Operation: detect

Purpose: Detect configuration format and provide migration guidance.

Steps:

1. Execute Detection Script:

   ./scripts/detect-config.sh
   

2. Parse Response:

   • status: "found" or "not_found"
   • format: "json" or "yaml"
   • location: "project" or "global"
   • path: Absolute path to config
   • is_preferred: Boolean - true if YAML project config
   • migration_needed: Boolean - true if JSON or global
   • deprecation_warning: String - warning message if deprecated

3. Output Results:

IF status == "not_found":

📋 Configuration Status: Not Found

No codex configuration detected.

Next Steps:
1. Run: /fractary-codex:init
2. This will create: .fractary/codex.yaml

Preferred format: YAML at .fractary/codex.yaml

IF format == "yaml" AND location == "project":

✅ Configuration Status: OK

Format: YAML (preferred)
Location: .fractary/codex.yaml
Status: Up to date

No migration needed.

IF format == "json" AND location == "project":

⚠️  Configuration Status: Deprecated

Format: JSON (deprecated)
Location: .fractary/plugins/codex/config.json
Status: Migration recommended

Deprecation Warning:
JSON format is deprecated. Please migrate to YAML format.

To migrate:
1. Preview: USE SKILL: config-helper with operation="migrate" and dry_run=true
2. Execute: USE SKILL: config-helper with operation="migrate"
3. This creates: .fractary/codex.yaml (version 4.0)

IF format == "json" AND location == "global":

⚠️  Configuration Status: Legacy

Format: JSON (deprecated)
Location: ~/.config/fractary/codex/config.json
Status: Migration required

Deprecation Warning:
Global config is deprecated. Please migrate to project-level YAML config.

To migrate:
1. cd to your project directory
2. Preview: USE SKILL: config-helper with operation="migrate" and dry_run=true
3. Execute: USE SKILL: config-helper with operation="migrate" and remove_source=true
4. This creates: .fractary/codex.yaml (version 4.0)

Operation: migrate

Purpose: Migrate configuration from JSON to YAML format.

Steps:

1. Validate Prerequisites:

   • Check jq installed: command -v jq
   • Check yq installed: command -v yq
   • If missing: provide installation instructions and STOP

2. Execute Migration Script:

   ./scripts/migrate-config.sh \
     --source "${source_path}" \
     --target "${target_path}" \
     ${dry_run ? "--dry-run" : ""} \
     ${remove_source ? "--remove-source" : ""}
   

3. Parse Response:

IF dry_run == true:

{
  "status": "success",
  "operation": "dry-run",
  "source": {"path": "...", "format": "json"},
  "target": {"path": "...", "format": "yaml"},
  "would_remove_source": false,
  "preview": "...yaml content..."
}

IF dry_run == false:

{
  "status": "success",
  "operation": "migrate",
  "source": {"path": "...", "format": "json", "removed": false},
  "target": {"path": "...", "format": "yaml", "created": true},
  "message": "Configuration migrated successfully",
  "next_steps": [...]
}

4. Output Results:

IF dry_run == true:

🔍 Migration Preview (Dry Run)

Source: .fractary/plugins/codex/config.json (JSON)
Target: .fractary/codex.yaml (YAML)

Changes:
- Format: JSON → YAML
- Version: 3.0 → 4.0 (CLI compatible)
- Location: .fractary/plugins/codex/ → .fractary/

Preview of .fractary/codex.yaml:
───────────────────────────────────────
{yaml_preview}
───────────────────────────────────────

To execute migration:
USE SKILL: config-helper with operation="migrate" and dry_run=false

IF dry_run == false:

✅ Configuration Migrated Successfully

Source: .fractary/plugins/codex/config.json
Target: .fractary/codex.yaml

Actions taken:
✓ Converted JSON → YAML
✓ Updated version: 3.0 → 4.0
✓ Created: .fractary/codex.yaml
{remove_source ? "✓ Removed source JSON config" : "○ Source JSON config preserved"}

Next Steps:
1. Review new config: cat .fractary/codex.yaml
2. Test CLI: fractary codex health
3. Update any scripts referencing old path
{!remove_source ? "4. Remove old config: rm .fractary/plugins/codex/config.json" : ""}

5. Handle Errors:

IF error occurs:

❌ Migration Failed

Error: {error_message}

Suggested fixes:
{suggested_fixes}

No changes were made to your configuration.

Operation: validate

Purpose: Validate configuration format and structure.

Steps:

1. Detect Config:

   • Use detect operation to find config

2. Validate Format:

   • For YAML: use yq validate
   • For JSON: use jq .

3. Validate Against CLI:

   • Run: fractary codex health
   • Check if CLI can read config

4. Output Results:

🔍 Configuration Validation

Format: {format}
Location: {path}

Format validation: {pass|fail}
CLI compatibility: {pass|fail}

{if deprecated}
⚠️  Deprecation warning: {warning}
{endif}

{if errors}
Errors found:
- {error 1}
- {error 2}
{endif}