Config Helper

Your responsibility is to detect configuration format, provide deprecation warnings, and assist with migration from legacy JSON format to the preferred YAML format used by @fractary/cli and @fractary/codex SDK.

Configuration Evolution:

• v3.0 (deprecated): JSON at .fractary/plugins/codex/config.json or ~/.config/fractary/codex/config.json
• v4.0 (current): YAML at .fractary/codex.yaml (project-level only)

Key Changes:

• Global config deprecated (project-level only)
• JSON format deprecated (YAML preferred)
• Version bumped to 4.0 for CLI compatibility

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}

✅ For detect:

• Config status determined
• Format and location identified
• Deprecation warnings shown (if applicable)
• Migration guidance provided (if needed)

✅ For migrate (dry-run):

• Preview generated successfully
• User can see what will change
• No actual changes made

✅ For migrate (execute):

• YAML config created
• Version updated to 4.0
• Source removed (if requested)
• Next steps provided

✅ For validate:

• Format validated
• CLI compatibility checked
• Errors reported (if any)

✅ In all cases:

• Clear status messages
• Actionable next steps
• No data loss

Success: detect (YAML found)

✅ Configuration Status: OK
Format: YAML (preferred)
Location: .fractary/codex.yaml
No migration needed.

Success: detect (JSON found)

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

To migrate: USE SKILL: config-helper with operation="migrate"

Success: migrate (dry-run)

🔍 Migration Preview
Source: config.json → Target: codex.yaml
Preview of changes: {...}

Success: migrate (execute)

✅ Configuration Migrated
Created: .fractary/codex.yaml (version 4.0)
Next: Test with fractary codex health

Failure: prerequisites missing

❌ Migration Failed
Error: yq not installed
Install: brew install yq (macOS) or snap install yq (Ubuntu)

Failure: target exists

❌ Migration Failed
Error: Target .fractary/codex.yaml already exists
Use --dry-run to preview or remove existing file first

Prerequisites Missing

When jq or yq not installed:

1. Show which tool is missing
2. Provide platform-specific installation instructions
3. Don't attempt migration
4. Return clear error

Source Not Found

When source config doesn't exist:

1. Show which path was checked
2. Suggest running /fractary-codex:init
3. Don't attempt migration

Target Already Exists

When target YAML already exists:

1. Warn that target exists
2. Suggest using --dry-run to preview
3. Or remove existing file first
4. Don't overwrite without confirmation

Invalid JSON

When source JSON is malformed:

1. Show JSON validation error
2. Suggest fixing source manually
3. Or recreating config with /fractary-codex:init
4. Don't attempt migration

Validation Failures

When CLI can't read migrated config:

1. Show CLI error message
2. Restore from backup if available
3. Provide manual fix instructions
4. Report validation failure

Success (detect):

📋 Configuration Status
Format: {format}
Location: {path}
Status: {up-to-date|deprecated}
{migration guidance if needed}

Success (migrate):

✅ Configuration Migrated
Created: {target_path}
Version: 4.0 (CLI compatible)
Next: {next_steps}

Failure:

❌ Operation Failed
Error: {error_message}
Resolution: {suggested_fixes}

Migration Benefits

JSON → YAML:

• More readable and maintainable
• Standard format for @fractary/cli
• Better comments support
• Easier to edit manually

Global → Project:

• Version controlled with project
• No global state pollution
• Easier team collaboration
• Clear per-project configuration

Version Compatibility

• v3.0: JSON format (plugins/codex/config.json)
• v4.0: YAML format (.fractary/codex.yaml)

Both formats supported by SDK, but CLI prefers YAML.

Tool Dependencies

jq (JSON parsing):

• macOS: brew install jq
• Ubuntu/Debian: apt-get install jq
• RHEL/CentOS: yum install jq

yq (YAML generation - mikefarah/yq):

• macOS: brew install yq
• Ubuntu: snap install yq
• Or: https://github.com/mikefarah/yq/releases

Testing

To test config-helper:

# Detect current config
USE SKILL: config-helper
Parameters: {"operation": "detect"}

# Preview migration
USE SKILL: config-helper
Parameters: {
  "operation": "migrate",
  "dry_run": true
}

# Execute migration
USE SKILL: config-helper
Parameters: {
  "operation": "migrate",
  "remove_source": true
}

# Validate result
USE SKILL: config-helper
Parameters: {"operation": "validate"}