avorelo 0.1.0

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

@@ -0,0 +1,407 @@
+#!/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

@@ -0,0 +1,201 @@
+"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,
+};