@lumenflow/cli 5.4.0 → 5.7.12

package/packs/software-delivery/src/policy/gates-agent-mode.ts

@@ -1,223 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-import path from 'node:path';
-import { existsSync, unlinkSync, symlinkSync } from 'node:fs';
-
-/**
- * Options for agent mode detection
- */
-interface GatesAgentModeOptions {
-  /** Command line arguments */
-  argv?: string[];
-  /** Environment variables */
-  env?: Record<string, string | undefined>;
-  /** stdout stream */
-  stdout?: { isTTY?: boolean };
-}
-
-/**
- * Options for log path functions
- */
-interface GatesLogOptions {
-  /** Working directory */
-  cwd: string;
-  /** Environment variables */
-  env?: Record<string, string | undefined>;
-}
-
-/**
- * Options for building gate log path
- */
-interface BuildGatesLogPathOptions extends GatesLogOptions {
-  /** WU ID */
-  wuId?: string;
-  /** Lane name */
-  lane?: string;
-  /** Current timestamp */
-  now?: Date;
-}
-
-/**
- * Options for updating symlink
- */
-interface UpdateGatesLatestSymlinkOptions extends GatesLogOptions {
-  /** Path to the actual gate log file */
-  logPath: string;
-}
-
-/**
- * Determine whether gates should run in low-noise "agent mode".
- *
- * Agent mode is intended for Claude Code sessions, where tool output is injected into the
- * conversation context and can trigger "prompt too long".
- *
- * Detection strategy (WU-1827):
- * 1. --verbose flag always forces full output (returns false)
- * 2. CLAUDE_PROJECT_DIR env var is a strong hint (returns true if set)
- * 3. TTY check: non-TTY + non-CI = likely agent mode (returns true)
- * 4. Interactive TTY = human user (returns false)
- *
- * @param {GatesAgentModeOptions} options
- * @returns {boolean} True if gates should run in agent mode
- */
-export function shouldUseGatesAgentMode({ argv, env, stdout }: GatesAgentModeOptions = {}) {
-  // --verbose flag always forces full output
-  const isVerbose = Array.isArray(argv) && argv.includes('--verbose');
-  if (isVerbose) {
-    return false;
-  }
-
-  // CLAUDE_PROJECT_DIR is a strong hint that we're in Claude Code
-  const hasClaudeProjectDir = Boolean(env?.CLAUDE_PROJECT_DIR);
-  if (hasClaudeProjectDir) {
-    return true;
-  }
-
-  // CI environments should get full output for debugging
-  const isCI = Boolean(env?.CI);
-  if (isCI) {
-    return false;
-  }
-
-  // Use provided stdout or fall back to process.stdout
-  const stdoutStream = stdout ?? process.stdout;
-
-  // TTY check: non-TTY = likely agent mode (Claude Code Bash tool doesn't have TTY)
-  // If stdout is undefined or isTTY is falsy, assume agent mode (safer default)
-  const isTTY = stdoutStream?.isTTY ?? false;
-
-  // Non-TTY + non-CI = likely agent mode
-  return !isTTY;
-}
-
-export function getGatesLogDir({ cwd, env }: GatesLogOptions) {
-  const configured = env?.LUMENFLOW_LOG_DIR;
-  return path.resolve(cwd, configured || '.logs');
-}
-
-export function buildGatesLogPath({
-  cwd,
-  env,
-  wuId,
-  lane,
-  now = new Date(),
-}: BuildGatesLogPathOptions) {
-  const logDir = getGatesLogDir({ cwd, env });
-  const safeLane = (lane || 'unknown').toLowerCase().replace(/[^a-z0-9]+/g, '-');
-  const safeWu = (wuId || 'unknown').toLowerCase().replace(/[^a-z0-9]+/g, '-');
-  const stamp = now.toISOString().replace(/[:.]/g, '-');
-  return path.join(logDir, `gates-${safeLane}-${safeWu}-${stamp}.log`);
-}
-
-/**
- * Get the path to the gates-latest.log symlink (WU-2064)
- *
- * @param {Object} options
- * @param {string} options.cwd - Working directory
- * @param {Object} [options.env] - Environment variables
- * @returns {string} Path to the symlink
- */
-export function getGatesLatestSymlinkPath({ cwd, env }: GatesLogOptions) {
-  const logDir = getGatesLogDir({ cwd, env });
-  return path.join(logDir, 'gates-latest.log');
-}
-
-/**
- * Create or update the gates-latest.log symlink to point to the most recent gate run (WU-2064)
- *
- * This provides a stable path for agents to access the most recent gate log
- * without needing to know the timestamp-based filename.
- *
- * @param {Object} options
- * @param {string} options.logPath - Path to the actual gate log file
- * @param {string} options.cwd - Working directory
- * @param {Object} [options.env] - Environment variables
- * @returns {boolean} True if symlink was created/updated successfully
- */
-export function updateGatesLatestSymlink({ logPath, cwd, env }: UpdateGatesLatestSymlinkOptions) {
-  const symlinkPath = getGatesLatestSymlinkPath({ cwd, env });
-
-  try {
-    // Remove existing symlink if present
-    if (existsSync(symlinkPath)) {
-      unlinkSync(symlinkPath);
-    }
-
-    // Create relative symlink (so it works regardless of absolute path)
-    const logDir = path.dirname(symlinkPath);
-    const relativePath = path.relative(logDir, logPath);
-    symlinkSync(relativePath, symlinkPath);
-
-    return true;
-  } catch {
-    // Symlink creation is best-effort, don't fail gates
-    return false;
-  }
-}
-
-export const WU_DONE_PRE_COMMIT_GATE_DECISION_REASONS = {
-  SKIP_GATES_FLAG: 'skip-gates-flag',
-  REUSE_STEP_ZERO: 'reuse-step-zero',
-  REUSE_CHECKPOINT: 'reuse-checkpoint',
-  RUN_REQUIRED: 'run-required',
-} as const;
-
-export type WuDonePreCommitGateDecisionReason =
-  (typeof WU_DONE_PRE_COMMIT_GATE_DECISION_REASONS)[keyof typeof WU_DONE_PRE_COMMIT_GATE_DECISION_REASONS];
-
-export interface WuDonePreCommitGateDecisionInput {
-  skipGates: boolean;
-  fullGatesRanInCurrentRun: boolean;
-  skippedByCheckpoint: boolean;
-  checkpointId?: string | null;
-}
-
-export interface WuDonePreCommitGateDecision {
-  runPreCommitFullSuite: boolean;
-  reason: WuDonePreCommitGateDecisionReason;
-  message: string;
-}
-
-/**
- * Decide whether wu:done pre-flight hook validation should rerun full gates.
- *
- * WU-1659: Avoid duplicate full-suite execution when Step 0 already ran gates
- * (or reused a valid checkpoint), while keeping operator-visible reasoning.
- */
-export function resolveWuDonePreCommitGateDecision(
-  input: WuDonePreCommitGateDecisionInput,
-): WuDonePreCommitGateDecision {
-  if (input.skipGates) {
-    return {
-      runPreCommitFullSuite: false,
-      reason: WU_DONE_PRE_COMMIT_GATE_DECISION_REASONS.SKIP_GATES_FLAG,
-      message: 'Pre-flight hook validation skipped because --skip-gates is active.',
-    };
-  }
-
-  if (input.fullGatesRanInCurrentRun) {
-    return {
-      runPreCommitFullSuite: false,
-      reason: WU_DONE_PRE_COMMIT_GATE_DECISION_REASONS.REUSE_STEP_ZERO,
-      message:
-        'Pre-flight hook validation reuses Step 0 gate results; duplicate full-suite run skipped.',
-    };
-  }
-
-  if (input.skippedByCheckpoint) {
-    const checkpointSuffix = input.checkpointId ? ` (${input.checkpointId})` : '';
-    return {
-      runPreCommitFullSuite: false,
-      reason: WU_DONE_PRE_COMMIT_GATE_DECISION_REASONS.REUSE_CHECKPOINT,
-      message: `Pre-flight hook validation reuses checkpoint gate attestation${checkpointSuffix}; duplicate full-suite run skipped.`,
-    };
-  }
-
-  return {
-    runPreCommitFullSuite: true,
-    reason: WU_DONE_PRE_COMMIT_GATE_DECISION_REASONS.RUN_REQUIRED,
-    message:
-      'No gate attestation found for this wu:done run; executing pre-flight hook gate suite.',
-  };
-}

package/packs/software-delivery/src/policy/gates-config-internal.ts

@@ -1,121 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/**
- * Gates Configuration Internals
- *
- * WU-2037: Shared infrastructure for gates modules
- *
- * Contains runtime defaults, field-name constants, and config-loading helpers
- * used by gates-config.ts, gates-coverage.ts, and package-manager-resolver.ts.
- *
- * This module exists to break circular imports between the facade (gates-config.ts)
- * and its extracted sub-modules.
- *
- * @module gates-config-internal
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import * as yaml from 'yaml';
-import { WORKSPACE_CONFIG_FILE_NAME, WORKSPACE_V2_KEYS } from '../constants/config-contract.js';
-import { asRecord } from '../constants/object-guards.js';
-import { getDefaultPolicy } from './resolve-policy.js';
-
-// ---------------------------------------------------------------------------
-// Runtime defaults
-// ---------------------------------------------------------------------------
-
-const DEFAULT_POLICY = getDefaultPolicy();
-
-export const GATES_RUNTIME_DEFAULTS = {
-  COMMAND_TIMEOUT_MS: 120000,
-  MAX_ESLINT_WARNINGS: 100,
-  DEFAULT_MIN_COVERAGE: DEFAULT_POLICY.coverage_threshold,
-  DEFAULT_ENABLE_COVERAGE: true,
-  DEFAULT_PACKAGE_MANAGER: 'pnpm',
-  DEFAULT_TEST_RUNNER: 'vitest',
-} as const;
-
-// ---------------------------------------------------------------------------
-// Field-name constants (avoid magic strings across modules)
-// ---------------------------------------------------------------------------
-
-const SOFTWARE_DELIVERY_KEY = WORKSPACE_V2_KEYS.SOFTWARE_DELIVERY;
-
-export const SOFTWARE_DELIVERY_FIELDS = {
-  GATES: 'gates',
-  METHODOLOGY: 'methodology',
-  PACKAGE_MANAGER: 'package_manager',
-  PACKAGE_MANAGER_CAMEL: 'packageManager',
-  TEST_RUNNER: 'test_runner',
-  TEST_RUNNER_CAMEL: 'testRunner',
-  BUILD_COMMAND: 'build_command',
-  BUILD_COMMAND_CAMEL: 'buildCommand',
-} as const;
-
-export const GATES_FIELDS = {
-  EXECUTION: 'execution',
-  LANE_HEALTH: 'lane_health',
-  LANE_HEALTH_CAMEL: 'laneHealth',
-  TDD_DIFF_EVIDENCE: 'tdd_diff_evidence',
-  TDD_ORDERING: 'tdd_ordering',
-  MIN_COVERAGE: 'minCoverage',
-  MIN_COVERAGE_SNAKE: 'min_coverage',
-  ENABLE_COVERAGE: 'enableCoverage',
-  ENABLE_COVERAGE_SNAKE: 'enable_coverage',
-  COMMANDS: 'commands',
-} as const;
-
-export const GATES_COMMAND_FIELDS = {
-  TEST_FULL: 'test_full',
-  TEST_DOCS_ONLY: 'test_docs_only',
-  TEST_INCREMENTAL: 'test_incremental',
-  LINT: 'lint',
-  TYPECHECK: 'typecheck',
-  FORMAT: 'format',
-  MIGRATION_VERIFY: 'migration_verify',
-} as const;
-
-// ---------------------------------------------------------------------------
-// Config loading helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Load the software_delivery section from workspace.yaml
- *
- * @param projectRoot - Project root directory
- * @returns Parsed software_delivery record, or null
- */
-export function loadSoftwareDeliveryConfig(projectRoot: string): Record<string, unknown> | null {
-  const configPath = path.join(projectRoot, WORKSPACE_CONFIG_FILE_NAME);
-
-  if (!fs.existsSync(configPath)) {
-    return null;
-  }
-
-  try {
-    const content = fs.readFileSync(configPath, 'utf8');
-    const data = asRecord(yaml.parse(content));
-    if (!data) {
-      return null;
-    }
-    return asRecord(data[SOFTWARE_DELIVERY_KEY]);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Load the gates sub-section from workspace.yaml software_delivery
- *
- * @param projectRoot - Project root directory
- * @returns Parsed gates record, or null
- */
-export function getGatesSection(projectRoot: string): Record<string, unknown> | null {
-  const softwareDelivery = loadSoftwareDeliveryConfig(projectRoot);
-  if (!softwareDelivery) {
-    return null;
-  }
-  return asRecord(softwareDelivery[SOFTWARE_DELIVERY_FIELDS.GATES]);
-}

package/packs/software-delivery/src/policy/gates-config.ts

@@ -1,300 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/**
- * Gates Configuration Facade
- *
- * WU-1067: Config-driven gates execution
- * WU-2037: Decomposed into focused sub-modules
- *
- * This module is the public entry point for gates configuration.
- * It re-exports from the extracted sub-modules and retains the
- * config-loading, parsing, and lane-health functions that depend
- * on the shared infrastructure.
- *
- * Sub-modules:
- *  - gates-schemas.ts      Zod schemas, types, interfaces
- *  - gates-presets.ts       Preset definitions and expansion
- *  - gates-coverage.ts      Coverage and test policy resolution
- *  - package-manager-resolver.ts  PM, TR, build, commands, ignore
- *  - gates-config-internal.ts     Shared helpers and constants
- *
- * @module gates-config
- */
-
-import { isString } from '../constants/object-guards.js';
-import { WORKSPACE_CONFIG_FILE_NAME, WORKSPACE_V2_KEYS } from '../constants/config-contract.js';
-import {
-  GatesExecutionConfigSchema,
-  LaneHealthModeSchema,
-  DEFAULT_LANE_HEALTH_MODE,
-} from './gates-schemas.js';
-import type {
-  GateCommandConfig,
-  GatesExecutionConfig,
-  ParsedGateCommand,
-  LaneHealthMode,
-} from './gates-schemas.js';
-import { expandPreset } from './gates-presets.js';
-import { GATES_RUNTIME_DEFAULTS, GATES_FIELDS, getGatesSection } from './gates-config-internal.js';
-
-// ---------------------------------------------------------------------------
-// Re-exports: schemas, types, and interfaces
-// ---------------------------------------------------------------------------
-
-export type {
-  GateCommandConfig,
-  GatesExecutionConfig,
-  ParsedGateCommand,
-  LaneHealthMode,
-  CoverageConfig,
-  CoveragePolicy,
-  TestRunnerPolicy,
-  TestPolicy,
-  GatesCommands,
-} from './gates-schemas.js';
-export type { TddDiffEvidencePolicy, TddOrderingPolicy } from './resolve-policy.js';
-
-export type { ScopedUnitTestExecutionPlan } from './package-manager-resolver.js';
-
-export {
-  GateCommandConfigSchema,
-  GatesExecutionConfigSchema,
-  LaneHealthModeSchema,
-  DEFAULT_LANE_HEALTH_MODE,
-} from './gates-schemas.js';
-
-// Re-export presets
-// WU-2547: PRESET_FIX_COMMANDS and getFormatFixCommand added for preset-aware
-// onboarding template rendering in @lumenflow/cli/src/init.ts.
-export {
-  GATE_PRESETS,
-  expandPreset,
-  PRESET_FIX_COMMANDS,
-  getFormatFixCommand,
-} from './gates-presets.js';
-
-// Re-export coverage/test policy resolution
-export {
-  resolveCoverageConfig,
-  resolveTestPolicy,
-  resolveTddDiffEvidencePolicy,
-  resolveTddOrderingPolicy,
-  evaluateTddDiffEvidenceWaiver,
-  isPathExemptByTddDiffEvidence,
-} from './gates-coverage.js';
-export type { TddDiffEvidenceWaiver, TddDiffEvidenceWaiverReason } from './gates-coverage.js';
-
-// Re-export package manager / test runner resolution
-export {
-  resolvePackageManager,
-  resolveTestRunner,
-  resolveBuildCommand,
-  resolveGatesCommands,
-  getIgnorePatterns,
-  resolveGatePreset,
-  resolveScopedUnitTestExecutionPlan,
-  formatScopedUnitTestFallbackMessage,
-} from './package-manager-resolver.js';
-
-// Re-export shared infrastructure (consumed by child modules and external callers)
-export {
-  GATES_RUNTIME_DEFAULTS,
-  SOFTWARE_DELIVERY_FIELDS,
-  GATES_FIELDS,
-  GATES_COMMAND_FIELDS,
-  loadSoftwareDeliveryConfig,
-  getGatesSection,
-} from './gates-config-internal.js';
-
-// ---------------------------------------------------------------------------
-// Config loading / gate parsing / lane health (facade-owned)
-// ---------------------------------------------------------------------------
-
-const SOFTWARE_DELIVERY_KEY = WORKSPACE_V2_KEYS.SOFTWARE_DELIVERY;
-
-/**
- * Parse a gate command configuration into executable form
- *
- * @param config - Gate command configuration (string or object)
- * @returns Parsed command with defaults applied, or null if undefined
- */
-export function parseGateCommand(config: GateCommandConfig | undefined): ParsedGateCommand | null {
-  if (config === undefined) {
-    return null;
-  }
-
-  if (isString(config)) {
-    return {
-      command: config,
-      continueOnError: false,
-      timeout: GATES_RUNTIME_DEFAULTS.COMMAND_TIMEOUT_MS,
-    };
-  }
-
-  return {
-    command: config.command,
-    continueOnError: config.continueOnError ?? false,
-    timeout: config.timeout ?? GATES_RUNTIME_DEFAULTS.COMMAND_TIMEOUT_MS,
-  };
-}
-
-/**
- * Load gates configuration from workspace.yaml software_delivery.gates.execution
- *
- * @param projectRoot - Project root directory
- * @returns Gates execution config, or null if not configured
- */
-export function loadGatesConfig(projectRoot: string): GatesExecutionConfig | null {
-  const gates = getGatesSection(projectRoot);
-  if (!gates) {
-    return null;
-  }
-
-  try {
-    // Check if gates.execution section exists
-    const executionConfig = gates[GATES_FIELDS.EXECUTION];
-    if (!executionConfig) {
-      return null;
-    }
-
-    // Validate the config
-    const result = GatesExecutionConfigSchema.safeParse(executionConfig);
-    if (!result.success) {
-      // eslint-disable-next-line no-console -- operator-facing config validation warning
-      console.warn('Warning: Invalid gates.execution config:', result.error.message);
-      return null;
-    }
-
-    // Expand preset and merge with explicit config (explicit wins)
-    const presetDefaults = expandPreset(result.data.preset);
-    const merged: GatesExecutionConfig = {
-      ...presetDefaults,
-      ...result.data,
-    };
-
-    return merged;
-  } catch (error) {
-    // eslint-disable-next-line no-console -- operator-facing config parse warning
-    console.warn(
-      `Warning: Failed to parse ${WORKSPACE_CONFIG_FILE_NAME} ${SOFTWARE_DELIVERY_KEY}.gates.execution:`,
-      error instanceof Error ? error.message : String(error),
-    );
-    return null;
-  }
-}
-
-/**
- * Get default gates configuration for auto-detection fallback
- *
- * Used when no gates config is present in workspace.yaml software_delivery.
- * These are generic commands that work across common setups.
- *
- * @returns Default gates configuration
- */
-export function getDefaultGatesConfig(): GatesExecutionConfig {
-  return {
-    format:
-      'npm run format:check 2>/dev/null || npx prettier --check . 2>/dev/null || echo "No formatter configured"',
-    lint: 'npm run lint 2>/dev/null || npx eslint . 2>/dev/null || echo "No linter configured"',
-    typecheck:
-      'npm run typecheck 2>/dev/null || npx tsc --noEmit 2>/dev/null || echo "No type checker configured"',
-    test: 'npm test 2>/dev/null || echo "No test command configured"',
-  };
-}
-
-/**
- * Resolve the effective gates configuration
- *
- * Priority order:
- * 1. Explicit config from workspace.yaml software_delivery
- * 2. Preset defaults (if preset specified)
- * 3. Auto-detection defaults
- *
- * @param projectRoot - Project root directory
- * @returns Resolved gates configuration
- */
-export function resolveGatesConfig(projectRoot: string): GatesExecutionConfig {
-  const config = loadGatesConfig(projectRoot);
-
-  if (config) {
-    return config;
-  }
-
-  // Fall back to defaults for auto-detection
-  return getDefaultGatesConfig();
-}
-
-/**
- * Check if a specific gate should be skipped
- *
- * @param gateName - Name of the gate (format, lint, typecheck, test)
- * @param config - Gates execution configuration
- * @param skipFlags - Map of skip flags from CLI/Action inputs
- * @returns True if the gate should be skipped
- */
-export function shouldSkipGate(
-  gateName: keyof Omit<GatesExecutionConfig, 'preset' | 'coverage'>,
-  config: GatesExecutionConfig,
-  skipFlags: Record<string, boolean>,
-): boolean {
-  // Check if skip flag is set
-  const skipFlagName = `skip-${gateName}`;
-  if (skipFlags[skipFlagName] || skipFlags[gateName]) {
-    return true;
-  }
-
-  // Check if gate is configured (undefined means skip)
-  if (config[gateName] === undefined) {
-    return true;
-  }
-
-  return false;
-}
-
-/**
- * WU-1191: Load lane health configuration from workspace.yaml software_delivery
- *
- * Configuration format:
- * ```yaml
- * gates:
- *   lane_health: warn|error|off
- * ```
- *
- * @param projectRoot - Project root directory
- * @returns Lane health mode ('warn', 'error', or 'off'), defaults to 'warn'
- */
-export function loadLaneHealthConfig(projectRoot: string): LaneHealthMode {
-  const gates = getGatesSection(projectRoot);
-  if (!gates) {
-    return DEFAULT_LANE_HEALTH_MODE;
-  }
-
-  try {
-    // Check if gates.lane_health is configured
-    const laneHealthConfig =
-      gates[GATES_FIELDS.LANE_HEALTH] ?? gates[GATES_FIELDS.LANE_HEALTH_CAMEL];
-    if (laneHealthConfig === undefined) {
-      return DEFAULT_LANE_HEALTH_MODE;
-    }
-
-    // Validate the config value
-    const result = LaneHealthModeSchema.safeParse(laneHealthConfig);
-    if (!result.success) {
-      // eslint-disable-next-line no-console -- operator-facing config validation warning
-      console.warn(
-        `Warning: Invalid gates.lane_health value '${laneHealthConfig}', expected 'warn', 'error', or 'off'. Using default 'warn'.`,
-      );
-      return DEFAULT_LANE_HEALTH_MODE;
-    }
-
-    return result.data;
-  } catch (error) {
-    // eslint-disable-next-line no-console -- operator-facing config parse warning
-    console.warn(
-      `Warning: Failed to parse ${WORKSPACE_CONFIG_FILE_NAME} ${SOFTWARE_DELIVERY_KEY}.gates.lane_health:`,
-      error instanceof Error ? error.message : String(error),
-    );
-    return DEFAULT_LANE_HEALTH_MODE;
-  }
-}