@lumenflow/cli 4.24.0 → 5.0.0

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

@@ -0,0 +1,223 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+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

@@ -0,0 +1,121 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * 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

@@ -0,0 +1,293 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * 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,
+} 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) {
+      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) {
+    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) {
+      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) {
+    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;
+  }
+}