@lumenflow/cli 5.4.0 → 5.7.12

package/packs/software-delivery/src/ports/dashboard-renderer.port.ts

@@ -1,125 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/**
- * Dashboard Renderer Port
- *
- * Hexagonal Architecture - Output Port
- * Defines the contract for rendering orchestration dashboard data to UnsafeAny UI.
- * This abstraction allows the application layer to remain independent of
- * specific rendering implementations.
- *
- * Current Implementations:
- * - TerminalDashboardRenderer (WU-1322) - ASCII/ANSI terminal output
- *
- * Future Implementations:
- * - WebDashboardRenderer - Browser-based UI
- * - VSCodeWebviewRenderer - VS Code extension panel
- *
- * SOLID Principles:
- * - Dependency Inversion: Use cases depend on this abstraction, not concrete renderers
- * - Interface Segregation: Focused on rendering, no data fetching concerns
- * - Open/Closed: New renderers can be added without modifying existing code
- *
- * @module dashboard-renderer.port
- * @see {@link ../domain/orchestration.types.ts} - Types used in this interface
- * @see {@link ../../adapters/terminal-renderer.adapter.ts} - Terminal implementation (WU-1322)
- */
-
-import type {
-  DashboardData,
-  Suggestion,
-  ExecutionPlan,
-  UserChoice,
-} from '../domain/orchestration.types.js';
-
-/**
- * Dashboard Renderer Port Interface
- *
- * Implementers must provide methods to render all dashboard sections
- * and handle user interactions for execution plan approval.
- *
- * @example
- * // Implementing a custom renderer
- * class CustomRenderer implements IDashboardRenderer {
- *   render(data: DashboardData): void {
- *     // Render global status, agent metrics, WU progress, timeline, alerts
- *   }
- *
- *   renderSuggestions(suggestions: Suggestion[]): void {
- *     // Display prioritised suggestions
- *   }
- *
- *   renderPlan(plan: ExecutionPlan): Promise<UserChoice> {
- *     // Show plan and get user approval
- *   }
- *
- *   clear(): void {
- *     // Clear previous output
- *   }
- * }
- *
- * @example
- * // Using in a use case
- * class GetDashboardDataUseCase {
- *   constructor(
- *     private readonly renderer: IDashboardRenderer,
- *     private readonly collector: IMetricsCollector,
- *   ) {}
- *
- *   async execute(): Promise<void> {
- *     const data = await this.collectData();
- *     this.renderer.render(data);
- *   }
- * }
- */
-export interface IDashboardRenderer {
-  /**
-   * Render the complete dashboard with all sections.
-   *
-   * Sections to render:
-   * 1. Global Status - Active WUs, completed, blocked, gates failing
-   * 2. Agent Small Multiples - Per-agent metrics comparison
-   * 3. WU Progress - DoD progress bars with agent status
-   * 4. Timeline - Recent orchestration events
-   * 5. Alerts - Items requiring attention
-   *
-   * @param data - Complete dashboard data from metrics collector
-   */
-  render(data: DashboardData): void;
-
-  /**
-   * Render a list of prioritised suggestions.
-   *
-   * Suggestions should be displayed with:
-   * - Priority indicator (HIGH/MEDIUM/LOW)
-   * - Action description
-   * - Reason for suggestion
-   * - Command to execute
-   *
-   * @param suggestions - Ordered list of suggestions (highest priority first)
-   */
-  renderSuggestions(suggestions: Suggestion[]): void;
-
-  /**
-   * Render an execution plan and get user approval.
-   *
-   * Should display:
-   * - WU being executed
-   * - Ordered list of steps
-   * - Estimated token cost
-   * - Approval prompt (approve/reject/edit)
-   *
-   * @param plan - Proposed execution plan
-   * @returns User's choice (approve, reject, or edit with modifications)
-   */
-  renderPlan(plan: ExecutionPlan): Promise<UserChoice>;
-
-  /**
-   * Clear UnsafeAny previous dashboard output.
-   *
-   * Used before re-rendering to prevent stale data display.
-   * Implementation depends on output medium (e.g., clear terminal, DOM update).
-   */
-  clear(): void;
-}

package/packs/software-delivery/src/ports/index.ts

@@ -1,10 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-// Barrel for pack-local port contracts. Populated by Layer 4 of INIT-058.
-// WU-2699: moved wu-state.ports, sync-validator.ports from @lumenflow/core.
-// WU-2716: moved wu-helpers.ports, config.ports from @lumenflow/core.
-export * from './wu-state.ports.js';
-export * from './sync-validator.ports.js';
-export * from './wu-helpers.ports.js';
-export * from './config.ports.js';

package/packs/software-delivery/src/ports/sync-validator.ports.ts

@@ -1,59 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/**
- * Sync Validator Port Interfaces
- *
- * Canonical git adapter contract for main-branch sync validation helpers.
- *
- * @module ports/sync-validator
- */
-
-import type { IGitAdapter } from '@lumenflow/host/git/git-validator.ports';
-
-/**
- * Canonical git adapter shape for sync validation operations.
- */
-export interface ISyncValidatorGitAdapter {
-  fetch: IGitAdapter['fetch'];
-  getCommitHash: IGitAdapter['getCommitHash'];
-  revList: IGitAdapter['revList'];
-}
-
-/**
- * WU-2208: Git adapter shape for remote-aware WU ID generation.
- *
- * Extends the sync validator contract with tree listing and file content
- * retrieval at a specific git ref (e.g., origin/main). Designed to
- * accommodate future cloud `allocateWuId()` by keeping the interface
- * narrow and async.
- */
-export interface IWuIdGitAdapter {
-  /** Fetch remote refs (e.g., origin main). */
-  fetch: IGitAdapter['fetch'];
-
-  /**
-   * List file/directory names at a given ref and tree path.
-   *
-   * Equivalent to: git ls-tree --name-only <ref> <path>/
-   * Returns an array of filenames (not full paths) within the directory.
-   * Returns empty array if the path does not exist at the given ref.
-   *
-   * @param ref - Git ref (e.g., 'origin/main')
-   * @param path - Directory path relative to repo root (e.g., 'docs/operations/tasks/wu')
-   * @returns Array of filenames in the directory at the given ref
-   */
-  listTreeAtRef(ref: string, path: string): Promise<string[]>;
-
-  /**
-   * Show a file's content at a given ref.
-   *
-   * Equivalent to: git show <ref>:<path>
-   * Returns empty string if the file does not exist at the given ref.
-   *
-   * @param ref - Git ref (e.g., 'origin/main')
-   * @param path - File path relative to repo root
-   * @returns File content as string, or empty string if not found
-   */
-  showFileAtRef(ref: string, path: string): Promise<string>;
-}

package/packs/software-delivery/src/ports/wu-helpers.ports.ts

@@ -1,168 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/**
- * WU Helpers Port Interfaces
- *
- * WU-1102: INIT-003 Phase 2b - Port interfaces for WU helper modules
- *
- * Hexagonal Architecture - Input Ports:
- * These abstractions allow external users to inject custom implementations
- * for WU lifecycle operations.
- *
- * @module ports/wu-helpers
- */
-
-import type { ISyncValidatorGitAdapter } from './sync-validator.ports.js';
-
-/**
- * Git adapter interface for ensureOnMain and ensureMainUpToDate operations
- */
-export interface IWuGitAdapter extends Pick<ISyncValidatorGitAdapter, 'fetch' | 'getCommitHash'> {
-  /**
-   * Get the current git branch name
-   * @returns Promise resolving to branch name
-   */
-  getCurrentBranch(): Promise<string>;
-}
-
-/**
- * WU status check result
- */
-export interface IWuStatusCheckResult {
-  /** Whether the operation is allowed */
-  allowed: boolean;
-  /** Current WU status */
-  status: string | null;
-  /** Error message if not allowed */
-  error: string | null;
-}
-
-/**
- * Branch validation result
- */
-export interface IBranchValidationResult {
-  /** Whether the branch name is valid */
-  valid: boolean;
-  /** Lane name (kebab-case) or null */
-  lane: string | null;
-  /** WU ID (uppercase) or null */
-  wuid: string | null;
-  /** Error message if invalid */
-  error: string | null;
-}
-
-/**
- * WU YAML reader interface
- */
-export interface IWuYamlReader {
-  /**
-   * Read and parse WU YAML file
-   * @param wuPath - Path to WU YAML file
-   * @param expectedId - Expected WU ID for validation
-   * @returns Parsed WU document
-   */
-  readWU(wuPath: string, expectedId: string): unknown;
-
-  /**
-   * Read YAML file without ID validation
-   * @param yamlPath - Path to YAML file
-   * @returns Parsed document
-   */
-  readWURaw(yamlPath: string): unknown;
-}
-
-/**
- * WU YAML writer interface
- */
-export interface IWuYamlWriter {
-  /**
-   * Write WU document to file
-   * @param wuPath - Path to WU YAML file
-   * @param doc - Document to write
-   */
-  writeWU(wuPath: string, doc: unknown): void;
-}
-
-// WU-2020: IWuStateStore is now canonically defined in wu-state.ports.ts
-// Re-export here for backward compatibility with consumers importing from wu-helpers.ports.
-export type { IWuStateStore } from './wu-state.ports.js';
-
-/**
- * WU checkpoint interface
- */
-export interface IWuCheckpointManager {
-  /**
-   * Create a pre-gates checkpoint
-   */
-  createPreGatesCheckpoint(
-    params: { wuId: string; worktreePath: string; branchName: string; gatesPassed?: boolean },
-    options?: { baseDir?: string },
-  ): Promise<{ checkpointId: string; gatesPassed: boolean }>;
-
-  /**
-   * Mark checkpoint as gates passed
-   * @param wuId - WU identifier
-   * @returns True if updated
-   */
-  markGatesPassed(wuId: string, options?: { baseDir?: string }): boolean;
-
-  /**
-   * Get checkpoint for a WU
-   * @param wuId - WU identifier
-   * @returns Checkpoint or null
-   */
-  getCheckpoint(
-    wuId: string,
-    options?: { baseDir?: string },
-  ): { gatesPassed: boolean; worktreeHeadSha: string } | null;
-
-  /**
-   * Clear checkpoint
-   * @param wuId - WU identifier
-   */
-  clearCheckpoint(wuId: string, options?: { baseDir?: string }): void;
-
-  /**
-   * Check if gates can be skipped
-   */
-  canSkipGates(
-    wuId: string,
-    options?: { baseDir?: string; currentHeadSha?: string },
-  ): { canSkip: boolean; reason?: string };
-}
-
-/**
- * WU paths interface
- */
-export interface IWuPaths {
-  /** Get path to WU YAML file */
-  WU(id: string): string;
-
-  /** Get path to WU directory */
-  WU_DIR(): string;
-
-  /** Get path to status.md */
-  STATUS(): string;
-
-  /** Get path to backlog.md */
-  BACKLOG(): string;
-
-  /** Get path to stamps directory */
-  STAMPS_DIR(): string;
-
-  /** Get path to WU done stamp file */
-  STAMP(id: string): string;
-
-  /** Get path to state directory */
-  STATE_DIR(): string;
-
-  /** Get path to initiatives directory */
-  INITIATIVES_DIR(): string;
-
-  /** Get path to initiative YAML file */
-  INITIATIVE(id: string): string;
-
-  /** Get path to worktrees directory */
-  WORKTREES_DIR(): string;
-}

package/packs/software-delivery/src/ports/wu-state.ports.ts

@@ -1,241 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/**
- * WU State Ports (WU-2013)
- *
- * Focused interfaces for the decomposed WU state store services.
- * Each interface defines a single responsibility boundary.
- *
- * Error Contract (WU-2128):
- * Port methods THROW on failure (boundary contracts). Specifically:
- * - State transition methods (claim, complete, block, etc.) throw if the
- *   WU is in an invalid state for the requested transition.
- * - Lock methods (acquireLock) throw if the lock cannot be acquired.
- * - Query methods (getWUState, getByStatus) return undefined/empty set for
- *   "not found" conditions -- absence of data is not an error.
- *
- * @module ports/wu-state
- */
-
-import type { WUEvent } from '../state/wu-state-schema.js';
-
-/**
- * WU state entry in the in-memory store
- */
-export interface WUStateEntry {
-  status: string;
-  lane: string;
-  title: string;
-  completedAt?: string;
-  lastCheckpoint?: string;
-  lastCheckpointNote?: string;
-}
-
-/**
- * Checkpoint options for recording WU progress
- */
-export interface CheckpointOptions {
-  sessionId?: string;
-  progress?: string;
-  nextSteps?: string;
-}
-
-/**
- * Lock file data structure
- */
-export interface LockData {
-  pid: number;
-  timestamp: number;
-  hostname: string;
-}
-
-/**
- * Repair result from corruption recovery
- */
-export interface RepairResult {
-  success: boolean;
-  linesKept: number;
-  linesRemoved: number;
-  backupPath: string | null;
-  warnings: string[];
-}
-
-/**
- * Event log interface for loading, replaying, and appending WU events.
- *
- * Responsible for:
- * - Loading events from JSONL storage
- * - Replaying events to rebuild in-memory state
- * - Appending new validated events
- */
-export interface IWuEventLog {
-  /**
-   * Load and replay events from storage into in-memory state.
-   * Resets all state before replaying.
-   */
-  load(): Promise<void>;
-
-  /**
-   * Append a validated event to persistent storage and apply to in-memory state.
-   */
-  appendAndApply(event: WUEvent): Promise<void>;
-
-  /**
-   * Apply a validated event to in-memory state without persisting.
-   */
-  applyEvent(event: WUEvent): void;
-}
-
-/**
- * Lock manager interface for file-level locking with stale detection.
- *
- * Responsible for:
- * - Acquiring file locks with retry logic
- * - Releasing file locks
- * - Detecting stale locks (expired or dead process)
- */
-export interface IWuLockManager {
-  /**
-   * Acquire a file lock at the given path.
-   * Retries with stale lock detection.
-   *
-   * @throws Error if lock cannot be acquired after retries
-   */
-  acquireLock(lockPath: string): Promise<void>;
-
-  /**
-   * Release a file lock at the given path.
-   * Silently ignores errors if lock file doesn't exist.
-   */
-  releaseLock(lockPath: string): void;
-
-  /**
-   * Check if a lock is stale (expired timeout or dead process).
-   */
-  isLockStale(lockData: LockData): boolean;
-}
-
-/**
- * State query interface for O(1) lookups into WU state.
- *
- * Responsible for:
- * - Querying WU state by ID
- * - Querying WU IDs by status (O(1))
- * - Querying WU IDs by lane (O(1))
- * - Querying child WU IDs by parent (O(1))
- */
-export interface IWuStateQuery {
-  /**
-   * Get current in-memory state for a WU.
-   */
-  getWUState(wuId: string): WUStateEntry | undefined;
-
-  /**
-   * Get WU IDs by status (O(1) lookup).
-   */
-  getByStatus(status: string): Set<string>;
-
-  /**
-   * Get WU IDs by lane (O(1) lookup).
-   */
-  getByLane(lane: string): Set<string>;
-
-  /**
-   * Get child WU IDs delegated from a parent WU (O(1) lookup).
-   */
-  getChildWUs(parentWuId: string): Set<string>;
-
-  /**
-   * WU-2552: Resolve a (possibly stale) WU id to its current canonical
-   * id after any observed wu_renamed events. Returns the input unchanged
-   * if no rename chain applies.
-   */
-  resolveRenamedWuId(wuId: string): string;
-}
-
-// ---------------------------------------------------------------------------
-// Composite interface for command handler injection (WU-2020)
-// ---------------------------------------------------------------------------
-
-/**
- * WU State Store interface for dependency injection in command handlers.
- *
- * Combines event log and state query capabilities into a single injectable
- * interface. Command handlers should depend on this interface rather than
- * importing and instantiating WUStateStore directly.
- *
- * WU-2020: DIP compliance - high-level modules depend on abstraction,
- * not on the concrete WUStateStore class.
- *
- * @example
- * ```typescript
- * // Command handler accepts interface, not concrete class
- * async function completeWU(store: IWuStateStore, wuId: string) {
- *   await store.load();
- *   await store.complete(wuId);
- * }
- * ```
- */
-export interface IWuStateStore extends IWuEventLog, IWuStateQuery {
-  /**
-   * Claim a WU, transitioning it to in_progress status.
-   * @throws Error if WU is already in_progress
-   */
-  claim(wuId: string, lane: string, title: string): Promise<void>;
-
-  /**
-   * Complete a WU, transitioning it to done status.
-   * @throws Error if WU is not in_progress
-   */
-  complete(wuId: string): Promise<void>;
-
-  /**
-   * Block a WU with a reason.
-   * @throws Error if WU is not in_progress
-   */
-  block(wuId: string, reason: string): Promise<void>;
-
-  /**
-   * Unblock a WU, transitioning it back to in_progress.
-   * @throws Error if WU is not blocked
-   */
-  unblock(wuId: string): Promise<void>;
-
-  /**
-   * Record a checkpoint for a WU without changing its status.
-   */
-  checkpoint(wuId: string, note: string, options?: CheckpointOptions): Promise<void>;
-
-  /**
-   * Record a parent-child delegation relationship.
-   */
-  delegate(childWuId: string, parentWuId: string, delegationId: string): Promise<void>;
-
-  /**
-   * Release a WU, transitioning it from in_progress to ready.
-   * @throws Error if WU is not in_progress
-   */
-  release(wuId: string, reason: string): Promise<void>;
-
-  /**
-   * WU-2552: Append a wu_renamed event mapping `from` to `to`. Historical
-   * events are not rewritten; the in-memory rename map is updated so
-   * subsequent events and queries resolve `from` -> `to`.
-   */
-  renameWu(from: string, to: string, reason?: string): Promise<void>;
-
-  /**
-   * Create a complete event without persisting it.
-   * Useful for transactional flows.
-   * @throws Error if WU is not in_progress
-   */
-  createCompleteEvent(wuId: string, timestamp?: string): WUEvent;
-
-  /**
-   * Create a release event without persisting it.
-   * Useful for transactional flows.
-   * @throws Error if WU is not in_progress
-   */
-  createReleaseEvent(wuId: string, reason: string, timestamp?: string): WUEvent;
-}

package/packs/software-delivery/src/primitives/index.ts

@@ -1,5 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-// Barrel for pack-local primitives. Populated by Layers 2-4 of INIT-058.
-export {};

package/packs/software-delivery/src/runtime/index.ts

@@ -1,6 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-// Barrel for pack-runtime-helpers. Populated by Layer 4 of INIT-058.
-// WU-2698: added work-classifier (L4-prep narrow — pure leaf from @lumenflow/core).
-export * from './work-classifier.js';