How to Implement the Rollback Command for State Recovery in AIOX

The AIOX rollback command restores projects from the modular v4.0.4 structure to the legacy v2.0 layout by locating backups, removing new directories, and restoring original files with full metadata preservation.

The SynkraAI/aiox-core repository ships a production-ready state recovery system accessible through the CLI command aiox migrate rollback. This implementation enables developers to safely revert failed migrations from the legacy v2.0 layout to the new modular v4.0.4 structure, ensuring projects can always return to a known good state.

Architecture of the Rollback System

The rollback process follows a six-step pipeline orchestrated by executeRollback(projectRoot, options) in .aiox-core/cli/commands/migrate/rollback.js:

1. Backup Discovery: Locates the most recent .aiox-backup-<date> directory or accepts a user-supplied path through findLatestBackup and verifyBackup from .aiox-core/cli/commands/migrate/backup.js.

2. Structure Removal: Deletes modular v4.0.4 directories (core, development, product, infrastructure) using the removeV21Structure function.

3. File Restoration: Iterates the backup manifest to copy files back to original locations with preserved timestamps and permissions via restoreFromBackup and copyFileWithMetadata.

4. State Cleanup: Removes temporary migration metadata through clearMigrationState defined in .aiox-core/cli/commands/migrate/execute.js.

5. Validation: Verifies that at least two of three core directories (agents, tasks, registry) exist to confirm restoration completeness.

6. Reporting: Formats results through formatRollbackSummary for human-readable terminal output.

Core Implementation in rollback.js

The main entry point coordinates recovery by accepting a project root and options object:

// .aiox-core/cli/commands/migrate/rollback.js
async function executeRollback(projectRoot, options = {}) {
  // 1. Locate backup
  const backup = options.backupPath
    ? await loadBackupFromPath(options.backupPath)
    : await findLatestBackup(projectRoot);
  if (!backup) throw new Error('No backup found');

  // 2. Delete v4.0.4 directories
  const aioxCoreDir = path.join(projectRoot, '.aiox-core');
  const removal = await removeV21Structure(aioxCoreDir, { onProgress });

  // 3. Restore files from backup
  const restore = await restoreFromBackup(backup, projectRoot, { onProgress });

  // 4. Clean migration metadata
  await clearMigrationState(projectRoot);

  // 5. Return structured result
  return { success: restore.success, backup, removal, restore };
}

Pre-Execution Validation

Before initiating recovery, call canRollback(projectRoot) to verify backup existence and checksum integrity. This prevents failed restore attempts when backups are missing or corrupted, providing a reason property explaining why rollback is unavailable.

const { canRollback } = require('.aiox-core/cli/commands/migrate/rollback');

const status = await canRollback(projectRoot);
if (!status.canRollback) {
  console.error('Rollback not possible:', status.reason);
  return;
}

CLI Usage and Commands

The rollback command registers under the migration CLI in .aiox-core/cli/commands/migrate/index.js:

# Auto-detect latest backup

aiox migrate rollback

# Specify explicit backup directory

aiox migrate rollback --backup .aiox-backup-2023-09-15

# Enable verbose output

aiox migrate rollback --verbose

Note that the --dry-run flag is not applicable to rollback operations.

Programmatic Implementation

Integrate rollback into custom scripts using the exported API from .aiox-core/cli/commands/migrate/rollback:

const { executeRollback, canRollback } = require('.aiox-core/cli/commands/migrate/rollback');
const path = require('path');

async function safeRollback() {
  const projectRoot = path.resolve(__dirname);
  
  const status = await canRollback(projectRoot);
  if (!status.canRollback) {
    console.error('Prerequisites not met:', status.reason);
    return;
  }

  const result = await executeRollback(projectRoot, {
    onProgress: console.log,
    verbose: true
  });

  console.log('Restoration complete:', result);
}

safeRollback().catch(err => console.error('Rollback failed:', err));

CI/CD Integration

Implement automated recovery in GitHub Actions when migrations fail:

# .github/workflows/aiox-rollback.yml

name: AIOX Rollback on Failure
on:
  workflow_run:
    workflows: ["AIOX Migration"]
    types: [completed]

jobs:
  rollback:
    if: ${{ failure() }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: npm ci
      - name: Execute rollback
        run: npx aiox migrate rollback --verbose

Summary

• The rollback command in AIOX restores projects from v4.0.4 modular structure to legacy v2.0 layout through six distinct phases: backup discovery, directory removal, file restoration, state cleanup, validation, and reporting.
• Core logic resides in .aiox-core/cli/commands/migrate/rollback.js with helper functions imported from backup.js and execute.js.
• Use canRollback() to validate backup integrity before attempting restoration.
• The CLI exposes functionality via aiox migrate rollback with optional --backup and --verbose flags.
• Programmatic integration requires importing executeRollback and handling the result object containing success, backup, removal, and restore details.

Frequently Asked Questions

How does AIOX locate the correct backup during rollback?

The system searches for directories matching the .aiox-backup-<date> pattern in the project root. If multiple backups exist, it selects the most recent one automatically. Users can override this behavior by passing a specific path via the --backup CLI option or backupPath property in the options object when calling executeRollback() programmatically.

What validation ensures the restored project is complete?

After restoration, AIOX checks that at least two of the three core directories—agents, tasks, and registry—exist in the project root. If fewer than two are found, the system reports a warning indicating potential incomplete restoration. Additionally, canRollback() verifies backup checksums before any files are modified.

Can I preview what the rollback will do before executing it?

No, the rollback command does not support --dry-run mode. Unlike the migration command, rollback always performs the restore operation once initiated. To mitigate risk, run canRollback(projectRoot) beforehand to confirm backup validity, or manually inspect the backup manifest in the .aiox-backup-<date> directory.

Which files are removed during the rollback process?

The removeV21Structure() function deletes the modular v4.0.4 directories including core, development, product, and infrastructure from the .aiox-core path. It preserves any files in the project root that are not part of the v4.0.4 structure, ensuring only migration-generated artifacts are removed while restoring original v2.0 layout files from the backup.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}