@ryuenn3123/agentic-senior-core 4.3.15 → 5.1.0

package/lib/cli/commands/upgrade.mjs

@@ -1,451 +0,0 @@
-/**
- * Upgrade Command — Governance upgrade assistant.
- * Depends on: constants, utils, detector, compiler
- */
-import { createInterface } from 'node:readline/promises';
-import { stdin, stdout } from 'node:process';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-
-import {
-  CLI_VERSION,
-  AGENT_CONTEXT_DIR,
-  PROFILE_PRESETS,
-  AGENT_DECISION_STACK_FILE_NAME,
-  AGENT_DECISION_BLUEPRINT_FILE_NAME,
-} from '../constants.mjs';
-
-import {
-  ensureDirectory,
-  askYesNo,
-  toTitleCase,
-  collectFileNames,
-  formatDuration,
-  pathExists,
-  analyzeManagedGovernanceSurface,
-  copyGovernanceAssetsToTarget,
-} from '../utils.mjs';
-
-import {
-  detectProjectContext,
-  buildDetectionSummary,
-  formatDetectionCandidates,
-  detectUiScopeSignals,
-} from '../detector.mjs';
-import {
-  writeSelectedPolicy,
-  writeOnboardingReport,
-  loadOnboardingReportIfExists,
-} from '../compiler.mjs';
-
-import { runPreflightChecks } from '../preflight.mjs';
-import {
-  createBackup,
-  ensureBackupGitignoreEntry,
-  ensureRuntimeArtifactGitignoreEntries,
-} from '../backup.mjs';
-import { performRollback } from '../rollback.mjs';
-import { detectProjectDocTemplateStaleness } from '../project-scaffolder.mjs';
-import { ensureActiveMemorySnapshot } from '../memory-continuity.mjs';
-import { buildExistingProjectMajorConstraints } from '../init-detection-flow.mjs';
-import {
-  applyUpgradeTokenOptimizationPlan,
-  resolveUpgradeTokenOptimizationPlan,
-} from './upgrade/token-optimization-state.mjs';
-
-export function parseUpgradeArguments(commandArguments) {
-  const parsedUpgradeOptions = {
-    targetDirectory: '.',
-    dryRun: false,
-    skipConfirmation: false,
-    includeMcpTemplate: false,
-    pruneManagedSurface: true,
-  };
-
-  for (let argumentIndex = 0; argumentIndex < commandArguments.length; argumentIndex++) {
-    const currentArgument = commandArguments[argumentIndex];
-
-    if (!currentArgument.startsWith('--')) {
-      parsedUpgradeOptions.targetDirectory = currentArgument;
-      continue;
-    }
-
-    if (currentArgument === '--dry-run') {
-      parsedUpgradeOptions.dryRun = true;
-      continue;
-    }
-
-    if (currentArgument === '--yes') {
-      parsedUpgradeOptions.skipConfirmation = true;
-      continue;
-    }
-
-    if (currentArgument === '--mcp-template') {
-      parsedUpgradeOptions.includeMcpTemplate = true;
-      continue;
-    }
-
-    if (currentArgument === '--no-mcp-template') {
-      parsedUpgradeOptions.includeMcpTemplate = false;
-      continue;
-    }
-
-    if (currentArgument === '--prune') {
-      parsedUpgradeOptions.pruneManagedSurface = true;
-      continue;
-    }
-
-    if (currentArgument === '--no-prune') {
-      parsedUpgradeOptions.pruneManagedSurface = false;
-      continue;
-    }
-
-    throw new Error(`Unknown option: ${currentArgument}`);
-  }
-
-  return parsedUpgradeOptions;
-}
-
-export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions = {}) {
-  const resolvedTargetDirectoryPath = path.resolve(targetDirectoryArgument || '.');
-
-  if (resolvedTargetDirectoryPath.toLowerCase() === 'c:\\windows' || resolvedTargetDirectoryPath.toLowerCase() === 'c:\\windows\\system32') {
-    console.error('\n[FATAL] Target directory resolved to a Windows system folder (C:\\Windows).');
-    console.error('If you are running Windows npm from inside WSL, this is caused by cmd.exe lacking UNC path support.');
-    console.error('Please install and use a native Linux Node.js/npm directly inside WSL to setup your project.');
-    process.exit(1);
-  }
-
-  const setupStartedAt = Date.now();
-  await ensureDirectory(resolvedTargetDirectoryPath);
-
-  const preflightResult = await runPreflightChecks(resolvedTargetDirectoryPath, 'upgrade');
-  if (!preflightResult.passed) {
-      console.error('\n[FATAL] Preflight checks failed. Upgrading here would cause errors or data loss:');
-      console.error(JSON.stringify(preflightResult, null, 2));
-      throw new Error('Preflight checks failed.');
-  }
-
-  const userInterface = createInterface({ input: stdin, output: stdout });
-
-  try {
-    console.log(`\nAgentic-Senior-Core CLI v${CLI_VERSION}`);
-    console.log('Running managed guidance upgrade for an existing repository.');
-
-    const managedSurfacePlan = await analyzeManagedGovernanceSurface(resolvedTargetDirectoryPath, {
-      includeMcpTemplate: upgradeOptions.includeMcpTemplate === true,
-    });
-
-    const stackFileNames = await collectFileNames(path.join(AGENT_CONTEXT_DIR, 'stacks'));
-    const blueprintFileNames = await collectFileNames(path.join(AGENT_CONTEXT_DIR, 'blueprints'));
-    const existingOnboardingReport = await loadOnboardingReportIfExists(resolvedTargetDirectoryPath);
-    const tokenOptimizationPlan = await resolveUpgradeTokenOptimizationPlan(
-      resolvedTargetDirectoryPath,
-      existingOnboardingReport
-    );
-    const projectDetection = await detectProjectContext(resolvedTargetDirectoryPath);
-    const selectedProfileName = PROFILE_PRESETS[existingOnboardingReport?.selectedProfile]
-      ? existingOnboardingReport.selectedProfile
-      : 'balanced';
-
-    const hasExplicitRuntimeConstraint = existingOnboardingReport?.runtimeDecision?.mode === 'explicit-constraint';
-    const hasExplicitArchitectureConstraint = existingOnboardingReport?.architectureDecision?.mode === 'explicit-constraint';
-
-    const selectedStackFileName = hasExplicitRuntimeConstraint && stackFileNames.includes(existingOnboardingReport?.selectedStack)
-      ? existingOnboardingReport.selectedStack
-      : AGENT_DECISION_STACK_FILE_NAME;
-
-    const selectedAdditionalStackFileNames = hasExplicitRuntimeConstraint && Array.isArray(existingOnboardingReport?.selectedAdditionalStacks)
-      ? Array.from(new Set(existingOnboardingReport.selectedAdditionalStacks.filter(
-        (stackFileName) => stackFileNames.includes(stackFileName) && stackFileName !== selectedStackFileName
-      )))
-      : [];
-
-    const selectedBlueprintFileName = hasExplicitArchitectureConstraint && blueprintFileNames.includes(existingOnboardingReport?.selectedBlueprint)
-      ? existingOnboardingReport.selectedBlueprint
-      : AGENT_DECISION_BLUEPRINT_FILE_NAME;
-
-    const selectedAdditionalBlueprintFileNames = hasExplicitArchitectureConstraint && Array.isArray(existingOnboardingReport?.selectedAdditionalBlueprints)
-      ? Array.from(new Set(existingOnboardingReport.selectedAdditionalBlueprints.filter(
-        (blueprintFileName) => blueprintFileNames.includes(blueprintFileName) && blueprintFileName !== selectedBlueprintFileName
-      )))
-      : [];
-
-    const includeCiGuardrails = typeof existingOnboardingReport?.ciGuardrailsEnabled === 'boolean'
-      ? existingOnboardingReport.ciGuardrailsEnabled
-      : true;
-    const uiScopeSignals = await detectUiScopeSignals({
-      targetDirectoryPath: resolvedTargetDirectoryPath,
-      selectedStackFileName,
-      selectedBlueprintFileName,
-      projectScopeKey: existingOnboardingReport?.projectScope?.key || null,
-      projectScopeSourceLabel: 'onboarding project scope',
-    });
-    const packageManifest = uiScopeSignals.packageManifest;
-    const designContractPaths = ['docs/DESIGN.md'];
-    const missingDesignContractPaths = [];
-
-    for (const designContractPath of designContractPaths) {
-      const absoluteDesignContractPath = path.join(resolvedTargetDirectoryPath, ...designContractPath.split('/'));
-      if (!(await pathExists(absoluteDesignContractPath))) {
-        missingDesignContractPaths.push(designContractPath);
-      }
-    }
-
-    const detectionMajorConstraints = buildExistingProjectMajorConstraints({ mode: 'upgrade' });
-    const detectionTransparency = {
-      declaredAt: new Date().toISOString(),
-      declarationType: 'existing-project',
-      declarationShown: true,
-      detectionSummary: buildDetectionSummary(projectDetection),
-      activeRulesSummary: {
-        canonicalSource: 'AGENTS.md',
-        compiledRulebook: null,
-        legacyThinAdapters: [],
-        generatedBridgeAdapters: ['CLAUDE.md', 'GEMINI.md'],
-        stackLoadingMode: 'lazy',
-        domainRuleLoadingMode: 'lazy',
-        selectedProfile: selectedProfileName,
-        selectedProfileDisplayName: toTitleCase(selectedProfileName),
-        blockingSeverities: PROFILE_PRESETS[selectedProfileName]?.blockingSeverities || [],
-        ciGuardrailsEnabled: includeCiGuardrails,
-      },
-      majorConstraints: detectionMajorConstraints,
-      quickConfirmation: {
-        offered: false,
-        response: 'upgrade-auto',
-        source: 'upgrade-assistant',
-      },
-      decision: {
-        mode: 'upgrade-auto',
-        selectedStackFileName,
-        selectedBlueprintFileName,
-      },
-    };
-
-    console.log('\nExisting project detection transparency:');
-    if (projectDetection.detectedStackFileName) {
-      const confidenceScoreLabel = Number(projectDetection.confidenceScore || 0).toFixed(2);
-      console.log(
-        `- Detected stack: ${toTitleCase(projectDetection.detectedStackFileName)} (${projectDetection.confidenceLabel}, score ${confidenceScoreLabel})`
-      );
-    } else {
-      console.log('- Detected stack: unresolved (insufficient markers).');
-    }
-    console.log('- Active rules baseline: canonical AGENTS.md + .agent-context/ lazy rule library');
-    console.log(
-      `- Active review thresholds: ${(
-        PROFILE_PRESETS[selectedProfileName]?.blockingSeverities || []
-      ).join(', ') || 'none'})`
-    );
-    console.log('- Top candidates:');
-    console.log(formatDetectionCandidates(projectDetection.rankedCandidates));
-    console.log('- Major constraints:');
-    for (const majorConstraint of detectionMajorConstraints) {
-      console.log(`  - ${majorConstraint}`);
-    }
-
-    const projectDocStalenessReport = await detectProjectDocTemplateStaleness(resolvedTargetDirectoryPath);
-
-    console.log('\nUpgrade preview:');
-    console.log(`- Target directory: ${resolvedTargetDirectoryPath}`);
-    console.log(`- Runtime decision: ${selectedStackFileName === AGENT_DECISION_STACK_FILE_NAME ? 'agent recommendation required from repo evidence' : toTitleCase(selectedStackFileName)}`);
-    if (selectedAdditionalStackFileNames.length > 0) {
-      console.log(`- Additional stacks: ${selectedAdditionalStackFileNames.map((stackFileName) => toTitleCase(stackFileName)).join(', ')}`);
-    }
-    console.log(`- Architecture decision: ${selectedBlueprintFileName === AGENT_DECISION_BLUEPRINT_FILE_NAME ? 'agent recommendation required from repo evidence' : toTitleCase(selectedBlueprintFileName)}`);
-    if (selectedAdditionalBlueprintFileNames.length > 0) {
-      console.log(`- Additional blueprints: ${selectedAdditionalBlueprintFileNames.map((blueprintFileName) => toTitleCase(blueprintFileName)).join(', ')}`);
-    }
-    console.log(`- CI/CD quality checks (guardrails): ${includeCiGuardrails ? 'enabled' : 'disabled'}`);
-    console.log('- Instruction surface: AGENTS.md canonical with CLAUDE.md and GEMINI.md import bridges');
-    console.log('- Default activation cues: Adaptive Context bootstrap, ASCX wrappers, Compact Natural replies');
-    console.log(`- Token optimization policy: ${tokenOptimizationPlan.previewLabel}`);
-    console.log('- Default response mode: Compact Natural Mode enabled');
-    console.log(`- Managed surface stale files: ${managedSurfacePlan.staleFiles.length}`);
-    console.log(`- Managed surface stale directories: ${managedSurfacePlan.staleDirectories.length}`);
-    console.log(`- Managed surface sync mode: 1:1 (prune enabled)`);
-    console.log(`- Managed surface prune mode: ${upgradeOptions.pruneManagedSurface === true ? 'enabled (default)' : 'disabled (--no-prune)'}`);
-    console.log(`- MCP config write mode: ${upgradeOptions.includeMcpTemplate === true ? 'enabled (--mcp-template)' : 'disabled (default)'}`);
-    if (projectDocStalenessReport.hasProjectDocs) {
-      console.log(`- Project docs detected: ${projectDocStalenessReport.checkedFileNames.length}`);
-      console.log(`- Project docs expected template version: ${projectDocStalenessReport.expectedTemplateVersion}`);
-      console.log(`- Project docs stale files: ${projectDocStalenessReport.staleFiles.length}`);
-    }
-
-    if (managedSurfacePlan.staleFiles.length > 0 || managedSurfacePlan.staleDirectories.length > 0) {
-      console.log('\nManaged surface stale paths preview (up to 5):');
-      const previewPaths = [
-        ...managedSurfacePlan.staleFiles,
-        ...managedSurfacePlan.staleDirectories,
-      ].slice(0, 5);
-      for (const previewPath of previewPaths) {
-        console.log(`- ${previewPath}`);
-      }
-      if (managedSurfacePlan.staleFiles.length + managedSurfacePlan.staleDirectories.length > previewPaths.length) {
-        console.log('- ...');
-      }
-    }
-
-    if (projectDocStalenessReport.staleFiles.length > 0) {
-      console.log('\n[WARN] Some project docs were generated from older template versions:');
-      for (const staleDoc of projectDocStalenessReport.staleFiles) {
-        const detectedVersionLabel = staleDoc.detectedTemplateVersion || 'missing';
-        console.log(`- docs/${staleDoc.fileName} (detected: ${detectedVersionLabel}, expected: ${projectDocStalenessReport.expectedTemplateVersion})`);
-      }
-      console.log('Required action: regenerate docs with init --scaffold-docs or update the files manually to match the latest template version.');
-    }
-
-    if (uiScopeSignals.isUiScopeLikely && missingDesignContractPaths.length > 0) {
-      console.log('\n[WARN] UI/frontend scope was detected, but the dynamic design contract is incomplete:');
-      for (const missingDesignContractPath of missingDesignContractPaths) {
-        console.log(`- Missing ${missingDesignContractPath}`);
-      }
-      if (uiScopeSignals.signalReasons.length > 0) {
-        console.log(`- Detection signals: ${uiScopeSignals.signalReasons.join('; ')}`);
-      }
-      if (Array.isArray(uiScopeSignals.workspaceUiEntries) && uiScopeSignals.workspaceUiEntries.length > 0) {
-        console.log(`- Nested UI workspaces: ${uiScopeSignals.workspaceUiEntries.map((workspaceUiEntry) => workspaceUiEntry.relativePath).join(', ')}`);
-      }
-      console.log('Required action: create or refresh docs/DESIGN.md before allowing UI implementation work.');
-      console.log('Upgrade synchronizes governance assets, but it does not author project-specific docs/DESIGN.md automatically.');
-    }
-
-    if (upgradeOptions.dryRun) {
-      console.log('\nDry run enabled. No files were modified.');
-      return;
-    }
-
-    const shouldApplyUpgrade = upgradeOptions.skipConfirmation
-      ? true
-      : await askYesNo('Apply upgrade and synchronize managed files?', userInterface, true);
-
-    if (!shouldApplyUpgrade) {
-      console.log('Upgrade cancelled by user.');
-      return;
-    }
-
-    await createBackup(resolvedTargetDirectoryPath);
-    const backupGitignoreResult = await ensureBackupGitignoreEntry(resolvedTargetDirectoryPath);
-    if (backupGitignoreResult.status !== 'unchanged') {
-      console.log(`Local backup artifacts ignored in .gitignore (${backupGitignoreResult.entry}).`);
-    }
-    const runtimeArtifactGitignoreResult = await ensureRuntimeArtifactGitignoreEntries(resolvedTargetDirectoryPath);
-    if (runtimeArtifactGitignoreResult.status !== 'unchanged') {
-      console.log(
-        `Local runtime artifacts ignored in .gitignore (${runtimeArtifactGitignoreResult.addedEntries.join(', ')}).`
-      );
-    }
-
-    try {
-      const governanceSyncResult = await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath, {
-        includeMcpTemplate: upgradeOptions.includeMcpTemplate === true,
-        pruneManagedSurface: upgradeOptions.pruneManagedSurface === true,
-        managedSurfacePlan,
-      });
-      const supplementalCreatedFileNames = [];
-      const shouldEnsureActiveMemorySnapshot = existingOnboardingReport?.memoryContinuity?.enabled !== false;
-      const tokenOptimizationApplyResult = await applyUpgradeTokenOptimizationPlan(
-        resolvedTargetDirectoryPath,
-        tokenOptimizationPlan
-      );
-      if (tokenOptimizationApplyResult.createdFileName) {
-        supplementalCreatedFileNames.push(tokenOptimizationApplyResult.createdFileName);
-      }
-
-      const obsoleteDesignIntentPath = path.join(resolvedTargetDirectoryPath, 'docs', 'design-intent.json');
-      if (await pathExists(obsoleteDesignIntentPath)) {
-        try {
-          await fs.unlink(obsoleteDesignIntentPath);
-          supplementalCreatedFileNames.push('docs/design-intent.json (DELETED - Obsolete Compliance Theater)');
-          console.log('\n[CLEANUP] Removed obsolete docs/design-intent.json. The 2026 Context Ops Paradigm uses plain-text DESIGN.md only.');
-        } catch (err) {
-          // ignore error
-        }
-      }
-
-      if (shouldEnsureActiveMemorySnapshot) {
-        const activeMemoryResult = await ensureActiveMemorySnapshot(resolvedTargetDirectoryPath, {
-          projectName: packageManifest?.name || path.basename(resolvedTargetDirectoryPath),
-        });
-
-        if (activeMemoryResult.created) {
-          supplementalCreatedFileNames.push('.agent-context/state/active-memory.json');
-        }
-      }
-
-      await writeSelectedPolicy(resolvedTargetDirectoryPath, selectedProfileName);
-
-      const setupDurationMs = Date.now() - setupStartedAt;
-      await writeOnboardingReport({
-        targetDirectoryPath: resolvedTargetDirectoryPath,
-        selectedProfileName,
-        projectScope: existingOnboardingReport?.projectScope || null,
-        selectedStackFileName,
-        selectedAdditionalStackFileNames,
-        selectedBlueprintFileName,
-        selectedAdditionalBlueprintFileNames,
-        includeCiGuardrails,
-        setupDurationMs,
-        projectDetection,
-        runtimeEnvironment: existingOnboardingReport?.runtimeEnvironment || null,
-        operationMode: 'upgrade',
-        tokenOptimization: tokenOptimizationApplyResult.reportState,
-        detectionTransparency,
-        uiScopeSignals,
-      });
-
-      console.log('\nUpgrade complete.');
-      console.log(`- Governance surface sync: 1:1 (${governanceSyncResult.updatedFiles.length} updated, ${governanceSyncResult.createdFiles.length} new, ${governanceSyncResult.deletedManagedFiles.length} deleted, ${governanceSyncResult.unchangedFiles.length} unchanged)`);
-      const preservedInstructionEntrypoints = Array.from(new Set([
-        ...(governanceSyncResult.preservedFiles || []),
-      ])).sort();
-      if (preservedInstructionEntrypoints.length > 0) {
-        console.log(`- User-owned instruction entrypoints preserved: ${preservedInstructionEntrypoints.length}`);
-      }
-      if (governanceSyncResult.deletedManagedDirectories.length > 0) {
-        console.log(`- Managed stale directories removed: ${governanceSyncResult.deletedManagedDirectories.length}`);
-      }
-      console.log(`- Setup time: ${formatDuration(setupDurationMs)}`);
-
-      const hasDetailedGovernanceChanges = governanceSyncResult.updatedFiles.length > 0
-        || governanceSyncResult.createdFiles.length > 0
-        || governanceSyncResult.deletedManagedFiles.length > 0
-        || preservedInstructionEntrypoints.length > 0;
-
-      if (hasDetailedGovernanceChanges) {
-        console.log('\nDetailed changes:');
-        governanceSyncResult.createdFiles.forEach((fileName) => console.log(`  [NEW]     ${fileName}`));
-        governanceSyncResult.updatedFiles.forEach((fileName) => console.log(`  [UPDATED] ${fileName}`));
-        governanceSyncResult.deletedManagedFiles.forEach((fileName) => console.log(`  [DELETED] ${fileName}`));
-        preservedInstructionEntrypoints.forEach((fileName) => console.log(`  [PRESERVE] ${fileName}`));
-      }
-      if (supplementalCreatedFileNames.length > 0) {
-        if (!hasDetailedGovernanceChanges) {
-          console.log('\nDetailed changes:');
-        }
-        supplementalCreatedFileNames.forEach((fileName) => console.log(`  [NEW]     ${fileName} (seed)`));
-      }
-
-      console.log('\nRefreshed files: AGENTS.md, CLAUDE.md, GEMINI.md, .agent-context/, and .agent-context/state/onboarding-report.json');
-      console.log('Default activation cues remain Adaptive Context bootstrap, ASCX command wrappers, and Compact Natural final replies.');
-      console.log('Default response mode remains Compact Natural Mode through .agent-context/prompts/compact-natural-mode.md.');
-
-    } catch (error) {
-      console.error('\n[FATAL] An error occurred during upgrade. Attempting automatic rollback...');
-      try {
-          const rollbackReport = await performRollback(resolvedTargetDirectoryPath);
-          if (rollbackReport.success) {
-              console.error('[OK] Automatic rollback successful. The directory has been restored.');
-          } else {
-              console.error('[WARN] Automatic rollback completed with errors. You may need to manually clean up.');
-          }
-      } catch (rbError) {
-          console.error(`[FATAL] Automatic rollback failed: ${rbError.message}`);
-      }
-      throw error;
-    }
-  } finally {
-    userInterface.close();
-  }
-}