avorelo 0.1.0 → 0.2.0

package/scripts/lib/upgrade-interruption-recovery.js

@@ -1,407 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * upgrade-interruption-recovery
- * Detects and recovers from interrupted upgrade/setup states
- * Bounded scope: handles "initialized but not completed" pattern only
- */
-
-const fs = require('fs');
-const path = require('path');
-const { safeReadJson, safeWriteJson, ensureCcoDirs } = require('./fsx');
-
-const ONBOARDING_FILE = '.claude/cco/state/onboarding.json';
-const CONFIG_FILE = '.claude/cco/config.json';
-const SEQUENCE_CHECKPOINT_FILE = '.claude/cco/state/sequence-checkpoint.json';
-
-const INIT_SEQUENCE_CHECKPOINTS = {
-  START: 'init_start',
-  DIRS_CREATED: 'dirs_created',
-  CONFIG_WRITTEN: 'config_written',
-  STATE_INITIALIZED: 'state_initialized',
-  CONFIG_UPDATED: 'config_updated',
-  COMPLETED: 'completed'
-};
-
-function safeWriteCheckpoint(cwd, checkpoint, meta = {}) {
-  const checkpointData = {
-    checkpoint,
-    timestamp: new Date().toISOString(),
-    sequence: 'init',
-    meta
-  };
-  safeWriteJson(cwd, SEQUENCE_CHECKPOINT_FILE, checkpointData);
-}
-
-function safeClearCheckpoint(cwd) {
-  const checkpointPath = path.join(cwd, SEQUENCE_CHECKPOINT_FILE);
-  try {
-    if (fs.existsSync(checkpointPath)) {
-      fs.unlinkSync(checkpointPath);
-    }
-  } catch {
-    // Ignore cleanup errors
-  }
-}
-
-function readCheckpoint(cwd) {
-  const checkpoint = safeReadJson(cwd, SEQUENCE_CHECKPOINT_FILE, null);
-  if (!checkpoint || !checkpoint.checkpoint) return null;
-  return checkpoint.checkpoint;
-}
-
-function getPendingSteps(lastCheckpoint) {
-  const orderedSteps = [
-    INIT_SEQUENCE_CHECKPOINTS.START,
-    INIT_SEQUENCE_CHECKPOINTS.DIRS_CREATED,
-    INIT_SEQUENCE_CHECKPOINTS.CONFIG_WRITTEN,
-    INIT_SEQUENCE_CHECKPOINTS.STATE_INITIALIZED,
-    INIT_SEQUENCE_CHECKPOINTS.CONFIG_UPDATED,
-    INIT_SEQUENCE_CHECKPOINTS.COMPLETED
-  ];
-
-  if (!lastCheckpoint) {
-    return orderedSteps;
-  }
-
-  const checkpointIndex = orderedSteps.indexOf(lastCheckpoint);
-  if (checkpointIndex === -1) {
-    // Unknown checkpoint, start from beginning
-    return orderedSteps;
-  }
-
-  return orderedSteps.slice(checkpointIndex + 1);
-}
-
-/**
- * Validates consistency between onboarding state and checkpoint markers
- * @param {string} cwd - Current working directory
- * @returns {Object} Validation result
- */
-function validateMarkerConsistency(cwd) {
-  const onboardingPath = path.join(cwd, ONBOARDING_FILE);
-  const checkpointPath = path.join(cwd, SEQUENCE_CHECKPOINT_FILE);
-
-  const onboardingExists = fs.existsSync(onboardingPath);
-  const checkpointExists = fs.existsSync(checkpointPath);
-
-  // Case 1: Checkpoint without onboarding state
-  if (checkpointExists && !onboardingExists) {
-    return {
-      isConsistent: false,
-      reason: 'checkpoint_without_state',
-      action: 'clear_checkpoint',
-      details: 'Checkpoint exists but onboarding state is missing'
-    };
-  }
-
-  // Case 2: Completed onboarding with lingering checkpoint
-  if (onboardingExists && checkpointExists) {
-    try {
-      const state = JSON.parse(fs.readFileSync(onboardingPath, 'utf8'));
-      if (state.status === 'completed') {
-        return {
-          isConsistent: false,
-          reason: 'completed_with_checkpoint',
-          action: 'clear_checkpoint',
-          details: 'Onboarding completed but checkpoint remains'
-        };
-      }
-    } catch (err) {
-      // If we can't read onboarding state, treat as inconsistent
-      return {
-        isConsistent: false,
-        reason: 'unreadable_onboarding',
-        action: 'clear_checkpoint',
-        details: 'Cannot read onboarding state file'
-      };
-    }
-  }
-
-  return { isConsistent: true };
-}
-
-/**
- * Attempts to auto-repair inconsistent markers
- * @param {string} cwd - Current working directory
- * @returns {Object} Repair result
- */
-function autoRepairMarkers(cwd) {
-  const validation = validateMarkerConsistency(cwd);
-
-  if (!validation.isConsistent) {
-    switch (validation.action) {
-      case 'clear_checkpoint':
-        safeClearCheckpoint(cwd);
-        return {
-          repaired: true,
-          action: 'cleared_stale_checkpoint',
-          reason: validation.reason,
-          details: validation.details
-        };
-    }
-  }
-
-  return { repaired: false };
-}
-
-/**
- * Detection result type
- * @typedef {Object} InterruptionState
- * @property {boolean} isInterrupted - True if interrupted state detected
- * @property {string} interruptionType - Type of interruption
- * @property {Object} currentState - Current state values
- * @property {string} recommendedAction - Next action to take
- * @property {boolean} isSafeToAutoRecover - Whether auto-recovery is safe
- * @property {string} lastCheckpoint - Last successfully completed checkpoint
- * @property {Array<string>} pendingSteps - Steps that need to be completed
- */
-
-/**
- * Detects if system is in an interrupted upgrade/setup state
- * @param {string} cwd - Current working directory
- * @returns {InterruptionState} Detection result
- */
-function detectInterruptedState(cwd) {
-  // Auto-repair any inconsistent markers before detection
-  const repairResult = autoRepairMarkers(cwd);
-  if (repairResult.repaired) {
-    // Note: This goes to stderr to not interfere with JSON output
-    console.error('[detect] Auto-repaired markers:', repairResult.reason);
-  }
-
-  const onboardingPath = path.join(cwd, ONBOARDING_FILE);
-  const checkpoint = readCheckpoint(cwd);
-
-  // Debug info to stderr
-  console.error('[detect] Found checkpoint:', checkpoint);
-
-  // Check if onboarding state file exists
-  if (!fs.existsSync(onboardingPath)) {
-    return {
-      isInterrupted: false,
-      interruptionType: 'not_started',
-      currentState: null,
-      lastCheckpoint: null,
-      pendingSteps: getPendingSteps(null),
-      recommendedAction: 'Run initial setup with: node scripts/cco-init.js',
-      isSafeToAutoRecover: false
-    };
-  }
-
-  const state = safeReadJson(cwd, ONBOARDING_FILE, null);
-
-  // Onboarding state is authoritative - check its status first
-  if (state && state.status === 'completed') {
-    // Validate file integrity for completed state
-    // If critical files are missing, downgrade to incomplete
-    const configPath = path.join(cwd, CONFIG_FILE);
-    if (!fs.existsSync(configPath)) {
-      return {
-        isInterrupted: true,
-        interruptionType: 'missing_config',
-        currentState: {
-          status: state.status,
-          hasConfigFile: false
-        },
-        lastCheckpoint: checkpoint,
-        pendingSteps: checkpoint ? getPendingSteps(checkpoint) : [],
-        recommendedAction: 'Missing critical files. Run: node scripts/cco-init.js to complete initialization',
-        isSafeToAutoRecover: true
-      };
-    }
-
-    // Should not have a checkpoint at this point (autoRepair would have cleared it)
-    return {
-      isInterrupted: false,
-      interruptionType: 'completed',
-      currentState: {
-        status: state.status,
-        stepsCompleted: state.stepsCompleted || []
-      },
-      lastCheckpoint: null,
-      pendingSteps: [],
-      recommendedAction: 'System is fully initialized. Run: node scripts/cco-status.js',
-      isSafeToAutoRecover: false
-    };
-  }
-
-  // Check for "initialized but not completed" pattern
-  if (state && state.status === 'initialized' && state.stepsCompleted && state.stepsCompleted.length === 1) {
-    const pending = getPendingSteps(checkpoint);
-    return {
-      isInterrupted: true,
-      interruptionType: 'init_incomplete',
-      currentState: {
-        status: state.status,
-        stepsCompleted: state.stepsCompleted,
-        createdAt: state.createdAt
-      },
-      lastCheckpoint: checkpoint,
-      pendingSteps: pending,
-      recommendedAction: 'Run: node scripts/cco-init.js to complete initialization',
-      isSafeToAutoRecover: true
-    };
-  }
-
-  // Check for missing expected files
-  const configPath = path.join(cwd, CONFIG_FILE);
-  if (state && state.status === 'initialized' && !fs.existsSync(configPath)) {
-    const pending = getPendingSteps(checkpoint);
-    return {
-      isInterrupted: true,
-      interruptionType: 'missing_config',
-      currentState: {
-        status: state.status,
-        hasConfigFile: false
-      },
-      lastCheckpoint: checkpoint,
-      pendingSteps: pending,
-      recommendedAction: 'Run: node scripts/cco-init.js to recreate missing files',
-      isSafeToAutoRecover: true
-    };
-  }
-
-  // If we reach here, onboarding state exists but is in an unexpected state
-  return {
-    isInterrupted: true,
-    interruptionType: state ? 'unknown_state' : 'missing_or_invalid_state',
-    currentState: state,
-    lastCheckpoint: checkpoint,
-    pendingSteps: checkpoint ? getPendingSteps(checkpoint) : [],
-    recommendedAction: state ? 'Manual inspection required. Check: .claude/cco/state/onboarding.json' : 'Run initial setup with: node scripts/cco-init.js',
-    isSafeToAutoRecover: false
-  };
-}
-
-/**
- * Attempts safe auto-recovery for detectable interrupted states
- * @param {string} cwd - Current working directory
- * @returns {Object} Recovery result
- */
-function attemptAutoRecovery(cwd) {
-  const detection = detectInterruptedState(cwd);
-
-  if (!detection.isInterrupted || !detection.isSafeToAutoRecover) {
-    return {
-      success: false,
-      reason: detection.isInterrupted ? 'Manual recovery required' : 'No interruption detected',
-      detection: detection
-    };
-  }
-
-  try {
-    // Safe recovery actions based on interruption type
-    switch (detection.interruptionType) {
-      case 'init_incomplete':
-      case 'missing_config':
-        // Recovery: ensure directories exist (idempotent)
-        ensureCcoDirs(cwd);
-
-        // Check if config.json needs to be created
-        const config = safeReadJson(cwd, CONFIG_FILE, null);
-        if (!config) {
-          // Create minimal config (will be enhanced by init script)
-          safeWriteJson(cwd, CONFIG_FILE, {
-            version: '0.1.0',
-            initializedAt: new Date().toISOString(),
-            tier: 'free',
-            profile: 'balanced'
-          });
-        }
-
-        return {
-          success: true,
-          recoveryType: detection.interruptionType,
-          nextAction: 'Run: node scripts/cco-init.js to complete initialization'
-        };
-
-      default:
-        return {
-          success: false,
-          reason: `Auto-recovery not implemented for type: ${detection.interruptionType}`
-        };
-    }
-  } catch (error) {
-    return {
-      success: false,
-      reason: `Recovery error: ${error.message}`,
-      error: error
-    };
-  }
-}
-
-/**
- * CLI interface
- */
-function main() {
-  const cwd = process.cwd();
-  const [, , command] = process.argv;
-
-  switch (command) {
-    case 'detect':
-      const detection = detectInterruptedState(cwd);
-      console.log(JSON.stringify(detection, null, 2));
-      break;
-
-    case 'recover':
-      const recovery = attemptAutoRecovery(cwd);
-      console.log(JSON.stringify(recovery, null, 2));
-
-      if (recovery.success) {
-        console.log('\n✅ Recovery successful');
-        console.log('📋 Next action:', recovery.nextAction);
-      } else {
-        console.log('\n❌ Recovery failed');
-        if (recovery.reason) {
-          console.log('Reason:', recovery.reason);
-        }
-        if (recovery.detection) {
-          console.log('\nDetection result:');
-          console.log('Recommended action:', recovery.detection.recommendedAction);
-        }
-      }
-      break;
-
-    case 'status':
-      const status = detectInterruptedState(cwd);
-      console.log('Interruption Status:', status.isInterrupted ? 'INTERRUPTED ⚠️' : 'OK ✅');
-      console.log('Type:', status.interruptionType);
-
-      if (status.isInterrupted) {
-        console.log('\n📊 Current State:', JSON.stringify(status.currentState, null, 2));
-        console.log('\n💡 Recommended Action:', status.recommendedAction);
-
-        if (status.isSafeToAutoRecover) {
-          console.log('\n🤖 Auto-recovery: Available (run with "recover" command)');
-        } else {
-          console.log('\n🔧 Auto-recovery: Manual intervention required');
-        }
-      } else {
-        console.log('\n✨ System is fully initialized and ready');
-      }
-      break;
-
-    default:
-      console.log('Usage: node scripts/lib/upgrade-interruption-recovery.js [detect|recover|status]');
-      console.log('');
-      console.log('Commands:');
-      console.log('  detect   - Detect interrupted state and return JSON details');
-      console.log('  recover  - Attempt auto-recovery if safe (returns result JSON)');
-      console.log('  status   - Show human-readable status');
-  }
-}
-
-if (require.main === module) {
-  main();
-}
-
-module.exports = {
-  detectInterruptedState,
-  attemptAutoRecovery,
-  safeWriteCheckpoint,
-  safeClearCheckpoint,
-  readCheckpoint,
-  getPendingSteps,
-  INIT_SEQUENCE_CHECKPOINTS
-};

package/scripts/lib/usage-ledger.js

@@ -1,201 +0,0 @@
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-const { ensureCcoDirs, safeWriteJson, nowIso } = require("./fsx");
-const { getQuota, getCurrentPlan } = require("./entitlements");
-
-const USAGE_LEDGER_REL_PATH = ".claude/cco/state/avorelo-usage.json";
-const SCHEMA_VERSION = 1;
-
-function ledgerPath(cwd) {
-  return path.join(cwd, USAGE_LEDGER_REL_PATH);
-}
-
-function startOfUtcWeek(date) {
-  const copy = new Date(date.getTime());
-  const day = copy.getUTCDay();
-  const diff = day === 0 ? -6 : 1 - day;
-  copy.setUTCDate(copy.getUTCDate() + diff);
-  copy.setUTCHours(0, 0, 0, 0);
-  return copy;
-}
-
-function formatWindowKey(date, period) {
-  const current = new Date(date.getTime());
-  if (period === "month") {
-    const month = `${current.getUTCMonth() + 1}`.padStart(2, "0");
-    return `${current.getUTCFullYear()}-${month}`;
-  }
-  const start = startOfUtcWeek(current);
-  const month = `${start.getUTCMonth() + 1}`.padStart(2, "0");
-  const day = `${start.getUTCDate()}`.padStart(2, "0");
-  return `${start.getUTCFullYear()}-W-${month}-${day}`;
-}
-
-function buildEmptyLedger() {
-  return {
-    schemaVersion: SCHEMA_VERSION,
-    updatedAt: nowIso(),
-    usage: {},
-  };
-}
-
-function readUsageLedger(cwd) {
-  const absPath = ledgerPath(cwd);
-  if (!fs.existsSync(absPath)) {
-    return {
-      ok: true,
-      ledger: buildEmptyLedger(),
-      warnings: [],
-      path: USAGE_LEDGER_REL_PATH,
-    };
-  }
-
-  try {
-    const raw = JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^\uFEFF/, ""));
-    const usage = raw && typeof raw === "object" && raw.usage && typeof raw.usage === "object" ? raw.usage : {};
-    return {
-      ok: true,
-      ledger: {
-        schemaVersion: SCHEMA_VERSION,
-        updatedAt: typeof raw?.updatedAt === "string" ? raw.updatedAt : nowIso(),
-        usage,
-      },
-      warnings: [],
-      path: USAGE_LEDGER_REL_PATH,
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      ledger: buildEmptyLedger(),
-      warnings: [`Usage ledger is unreadable: ${error.message}`],
-      path: USAGE_LEDGER_REL_PATH,
-    };
-  }
-}
-
-function writeUsageLedger(cwd, ledger) {
-  ensureCcoDirs(cwd);
-  safeWriteJson(cwd, USAGE_LEDGER_REL_PATH, {
-    schemaVersion: SCHEMA_VERSION,
-    updatedAt: nowIso(),
-    usage: ledger.usage || {},
-  });
-}
-
-function getUsageCount(ledger, capabilityId, period, date = new Date()) {
-  const windowKey = formatWindowKey(date, period);
-  return Number(ledger?.usage?.[capabilityId]?.[windowKey] || 0);
-}
-
-function getQuotaStatus(cwd, capabilityId, options = {}) {
-  const plan = options.plan || getCurrentPlan({ cwd });
-  const quota = getQuota(capabilityId, { cwd, plan });
-  const state = readUsageLedger(cwd);
-  if (!quota || !quota.period || !Number.isFinite(Number(quota.limit))) {
-    return {
-      plan,
-      capabilityId,
-      tracked: false,
-      allowed: true,
-      used: 0,
-      limit: null,
-      remaining: null,
-      warnings: state.warnings,
-      ledgerPath: state.path,
-    };
-  }
-
-  const used = getUsageCount(state.ledger, capabilityId, quota.period, options.date || new Date());
-  const remaining = Math.max(0, Number(quota.limit) - used);
-  return {
-    plan,
-    capabilityId,
-    tracked: true,
-    allowed: state.ok && used < Number(quota.limit),
-    used,
-    limit: Number(quota.limit),
-    remaining,
-    period: quota.period,
-    windowKey: formatWindowKey(options.date || new Date(), quota.period),
-    warnings: state.warnings,
-    ledgerPath: state.path,
-  };
-}
-
-function consumeQuota(cwd, capabilityId, options = {}) {
-  const date = options.date || new Date();
-  const plan = options.plan || getCurrentPlan({ cwd });
-  const quota = getQuota(capabilityId, { cwd, plan });
-  if (!quota || !quota.period || !Number.isFinite(Number(quota.limit))) {
-    return {
-      ok: true,
-      consumed: false,
-      plan,
-      capabilityId,
-      tracked: false,
-      message: "This capability does not use a counted quota.",
-    };
-  }
-
-  const state = readUsageLedger(cwd);
-  if (!state.ok) {
-    return {
-      ok: false,
-      consumed: false,
-      plan,
-      capabilityId,
-      tracked: true,
-      message: `Cannot safely consume quota because ${USAGE_LEDGER_REL_PATH} is unreadable.`,
-      warnings: state.warnings,
-    };
-  }
-
-  const windowKey = formatWindowKey(date, quota.period);
-  const used = getUsageCount(state.ledger, capabilityId, quota.period, date);
-  if (used >= Number(quota.limit)) {
-    return {
-      ok: false,
-      consumed: false,
-      plan,
-      capabilityId,
-      tracked: true,
-      used,
-      limit: Number(quota.limit),
-      remaining: 0,
-      period: quota.period,
-      windowKey,
-      message: `Quota reached for ${capabilityId}: ${used}/${quota.limit} ${quota.period} uses.`,
-    };
-  }
-
-  const next = buildEmptyLedger();
-  next.usage = { ...(state.ledger.usage || {}) };
-  next.usage[capabilityId] = { ...(next.usage[capabilityId] || {}) };
-  next.usage[capabilityId][windowKey] = used + 1;
-  writeUsageLedger(cwd, next);
-
-  return {
-    ok: true,
-    consumed: true,
-    plan,
-    capabilityId,
-    tracked: true,
-    used: used + 1,
-    limit: Number(quota.limit),
-    remaining: Math.max(0, Number(quota.limit) - used - 1),
-    period: quota.period,
-    windowKey,
-    message: `Quota recorded for ${capabilityId}: ${used + 1}/${quota.limit} ${quota.period} uses.`,
-  };
-}
-
-module.exports = {
-  USAGE_LEDGER_REL_PATH,
-  formatWindowKey,
-  readUsageLedger,
-  writeUsageLedger,
-  getQuotaStatus,
-  consumeQuota,
-};