@lumenflow/cli 5.5.0 → 5.7.14

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

@@ -1,255 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/**
- * WU State Schema (WU-1570)
- *
- * Zod schemas for WU state event validation.
- * Defines event types for WU lifecycle: create, claim, block, unblock, complete.
- *
- * @see {@link packages/@lumenflow/cli/src/lib/__tests__/wu-state-store.test.ts} - Tests
- */
-
-import { z } from 'zod';
-
-/**
- * WU event types
- *
- * - create: WU created (transitions to ready)
- * - claim: WU claimed (transitions to in_progress)
- * - block: WU blocked (transitions to blocked)
- * - unblock: WU unblocked (transitions back to in_progress)
- * - complete: WU completed (transitions to done)
- * - checkpoint: Progress checkpoint (WU-1748: cross-agent visibility)
- * - delegation: WU delegated from parent (WU-1947: parent-child relationships)
- * - release: WU released (WU-1080: transitions from in_progress to ready for orphan recovery)
- * - wu_renamed: WU id canonicalized or normalized (WU-2552: append-only rename, never rewrites history)
- */
-export const WU_EVENT_TYPES = [
-  'create',
-  'claim',
-  'block',
-  'unblock',
-  'complete',
-  'checkpoint',
-  'delegation',
-  'release',
-  'wu_renamed',
-] as const;
-
-/** Type for WU event types */
-export type WUEventType = (typeof WU_EVENT_TYPES)[number];
-
-/**
- * WU Event Type constant object (WU-2044)
- *
- * Named constants for event type strings, analogous to WU_STATUS.
- * Use WU_EVENT_TYPE.CLAIM instead of raw 'claim' strings.
- */
-export const WU_EVENT_TYPE = Object.freeze({
-  CREATE: 'create' as const,
-  CLAIM: 'claim' as const,
-  BLOCK: 'block' as const,
-  UNBLOCK: 'unblock' as const,
-  COMPLETE: 'complete' as const,
-  CHECKPOINT: 'checkpoint' as const,
-  DELEGATION: 'delegation' as const,
-  RELEASE: 'release' as const,
-  WU_RENAMED: 'wu_renamed' as const,
-});
-
-/**
- * WU status values (matches LumenFlow state machine)
- */
-export const WU_STATUSES = ['ready', 'in_progress', 'blocked', 'waiting', 'done'] as const;
-
-/** Type for WU status values */
-export type WUStatus = (typeof WU_STATUSES)[number];
-
-/**
- * Regex patterns for WU validation
- */
-export const WU_PATTERNS = {
-  /** WU ID format: WU-{digits} */
-  WU_ID: /^WU-\d+$/,
-};
-
-/**
- * Error messages for schema validation
- */
-const ERROR_MESSAGES = {
-  EVENT_TYPE: `Event type must be one of: ${WU_EVENT_TYPES.join(', ')}`,
-  WU_ID: 'WU ID must match pattern WU-XXX (e.g., WU-1570)',
-  LANE_REQUIRED: 'Lane is required',
-  TITLE_REQUIRED: 'Title is required',
-  REASON_REQUIRED: 'Reason is required',
-  TIMESTAMP_REQUIRED: 'Timestamp is required',
-};
-
-/**
- * Base event schema (common fields for all events)
- */
-const BaseEventSchema = z.object({
-  /** Event type */
-  type: z.enum(WU_EVENT_TYPES, {
-    error: ERROR_MESSAGES.EVENT_TYPE,
-  }),
-
-  /** WU ID */
-  wuId: z.string().regex(WU_PATTERNS.WU_ID, { message: ERROR_MESSAGES.WU_ID }),
-
-  /** Event timestamp (ISO 8601 datetime) */
-  timestamp: z.string().datetime({ message: ERROR_MESSAGES.TIMESTAMP_REQUIRED }),
-});
-
-/**
- * Create event schema
- */
-export const CreateEventSchema = BaseEventSchema.extend({
-  type: z.literal('create'),
-  lane: z.string().min(1, { message: ERROR_MESSAGES.LANE_REQUIRED }),
-  title: z.string().min(1, { message: ERROR_MESSAGES.TITLE_REQUIRED }),
-});
-
-/**
- * Claim event schema
- */
-export const ClaimEventSchema = BaseEventSchema.extend({
-  type: z.literal('claim'),
-  lane: z.string().min(1, { message: ERROR_MESSAGES.LANE_REQUIRED }),
-  title: z.string().min(1, { message: ERROR_MESSAGES.TITLE_REQUIRED }),
-});
-
-/**
- * Block event schema
- */
-export const BlockEventSchema = BaseEventSchema.extend({
-  type: z.literal('block'),
-  reason: z.string().min(1, { message: ERROR_MESSAGES.REASON_REQUIRED }),
-});
-
-/**
- * Unblock event schema
- */
-export const UnblockEventSchema = BaseEventSchema.extend({
-  type: z.literal('unblock'),
-});
-
-/**
- * Complete event schema
- */
-export const CompleteEventSchema = BaseEventSchema.extend({
-  type: z.literal('complete'),
-});
-
-/**
- * Checkpoint event schema (WU-1748: cross-agent visibility)
- * Records progress checkpoints for abandoned WU detection
- */
-export const CheckpointEventSchema = BaseEventSchema.extend({
-  type: z.literal('checkpoint'),
-  /** Checkpoint note/description */
-  note: z.string().min(1, { message: 'Checkpoint note is required' }),
-  /** Optional session ID */
-  sessionId: z.string().optional(),
-  /** Optional progress summary */
-  progress: z.string().optional(),
-  /** Optional next steps */
-  nextSteps: z.string().optional(),
-});
-
-/**
- * Delegation event schema (WU-1947: parent-child relationships)
- * Records WU delegation relationships for tracking parent-child WUs
- */
-export const DelegationEventSchema = BaseEventSchema.extend({
-  type: z.literal('delegation'),
-  /** Parent WU ID that delegated this WU */
-  parentWuId: z
-    .string()
-    .regex(WU_PATTERNS.WU_ID, { message: 'Parent WU ID must match pattern WU-XXX' }),
-  /** Unique delegation identifier */
-  delegationId: z.string().min(1, { message: 'Delegation ID is required' }),
-});
-
-/**
- * Release event schema (WU-1080: orphan recovery)
- * Releases an in_progress WU back to ready state when agent is interrupted.
- * Allows another agent to reclaim the orphaned WU.
- */
-export const ReleaseEventSchema = BaseEventSchema.extend({
-  type: z.literal('release'),
-  /** Reason for releasing the WU */
-  reason: z.string().min(1, { message: ERROR_MESSAGES.REASON_REQUIRED }),
-});
-
-/**
- * WU renamed event schema (WU-2552: canonical WU IDs)
- *
- * Records a WU id change without rewriting history. Historical events
- * before the rename keep their original wuId field (audit trail intact).
- * Projections use {@link buildRenameProjection} to resolve an original id
- * to its current canonical id.
- *
- * Invariants:
- * - `wuId` field mirrors `from` so filter-by-wuId still returns this event
- *   for queries about the original id.
- * - `from` and `to` accept any WU ID matching WU_PATTERNS.WU_ID, which is
- *   intentionally permissive (matches both padded and unpadded legacy IDs).
- */
-export const WURenamedEventSchema = BaseEventSchema.extend({
-  type: z.literal('wu_renamed'),
-  /** Original WU ID (what the WU was called before the rename) */
-  from: z.string().regex(WU_PATTERNS.WU_ID, { message: ERROR_MESSAGES.WU_ID }),
-  /** New WU ID (what the WU is called after the rename) */
-  to: z.string().regex(WU_PATTERNS.WU_ID, { message: ERROR_MESSAGES.WU_ID }),
-  /** Optional human reason for the rename (e.g. 'canonicalize WU-5 to WU-0005') */
-  reason: z.string().optional(),
-});
-
-/**
- * Union schema for all event types
- */
-export const WUEventSchema = z.discriminatedUnion('type', [
-  CreateEventSchema,
-  ClaimEventSchema,
-  BlockEventSchema,
-  UnblockEventSchema,
-  CompleteEventSchema,
-  CheckpointEventSchema,
-  DelegationEventSchema,
-  ReleaseEventSchema,
-  WURenamedEventSchema,
-]);
-
-/**
- * TypeScript types inferred from schemas
- */
-export type CreateEvent = z.infer<typeof CreateEventSchema>;
-export type ClaimEvent = z.infer<typeof ClaimEventSchema>;
-export type BlockEvent = z.infer<typeof BlockEventSchema>;
-export type UnblockEvent = z.infer<typeof UnblockEventSchema>;
-export type CompleteEvent = z.infer<typeof CompleteEventSchema>;
-export type CheckpointEvent = z.infer<typeof CheckpointEventSchema>;
-export type DelegationEvent = z.infer<typeof DelegationEventSchema>;
-export type ReleaseEvent = z.infer<typeof ReleaseEventSchema>;
-export type WURenamedEvent = z.infer<typeof WURenamedEventSchema>;
-export type WUEvent = z.infer<typeof WUEventSchema>;
-
-/**
- * Validates WU event data against schema
- *
- * @param {unknown} data - Data to validate
- * @returns {z.SafeParseReturnType<WUEvent, WUEvent>} Validation result
- *
- * @example
- * const result = validateWUEvent(eventData);
- * if (!result.success) {
- *   result.error.issues.forEach(issue => {
- *     console.error(`${issue.path.join('.')}: ${issue.message}`);
- *   });
- * }
- */
-export function validateWUEvent(data: unknown) {
-  return WUEventSchema.safeParse(data);
-}

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

@@ -1,338 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-import { existsSync, readFileSync, writeFileSync, promises as fs } from 'node:fs';
-
-import {
-  createError,
-  ErrorCodes,
-  getErrorMessage,
-} from '@lumenflow/kernel/primitives/error-handler';
-import { parse, stringify } from 'yaml';
-
-import { STRING_LITERALS } from '../constants/wu-ui-constants.js';
-
-import { createWuPaths } from './wu-paths.js';
-import { BaseWUSchema } from './wu-schema.js';
-
-/**
- * Unified WU YAML I/O module.
- *
- * Replaces 4 duplicate read/write functions scattered across wu-claim, wu-done,
- * wu-block, and wu-unblock. Single source of truth for WU YAML operations.
- *
- * WU-1352: Standardized on yaml v2.8.1 (eemeli) with consistent stringify options.
- *
- * Functions:
- * - readWU(path, id): Read and validate WU YAML
- * - readWURaw(path): Read YAML without ID validation
- * - parseYAML(text): Parse YAML string to object
- * - writeWU(path, doc): Write WU YAML with consistent formatting
- * - stringifyYAML(doc): Stringify object to YAML with consistent formatting
- * - appendNote(doc, note): Append note to doc.notes field
- *
- * @example
- * import { readWU, writeWU, appendNote } from './lib/wu-yaml.js';
- * import { createWuPaths } from './wu-paths.js';
- *
- * const wuPaths = createWuPaths();
- *
- * // Read WU
- * const doc = readWU(wuPaths.WU('WU-123'), 'WU-123');
- *
- * // Modify doc
- * doc.status = 'in_progress';
- * appendNote(doc, 'Started work on this WU');
- *
- * // Write back
- * writeWU(wuPaths.WU('WU-123'), doc);
- */
-
-/**
- * WU-1352: YAML scalar type constants (from yaml library).
- * These match the string values expected by the yaml package.
- * @see https://github.com/eemeli/yaml/blob/main/docs/03_options.md
- */
-const YAML_SCALAR_TYPES = Object.freeze({
-  /** Unquoted string (when safe) */
-  PLAIN: 'PLAIN',
-  /** Single-quoted string */
-  QUOTE_SINGLE: 'QUOTE_SINGLE',
-  /** Double-quoted string */
-  QUOTE_DOUBLE: 'QUOTE_DOUBLE',
-  /** Block literal (|) */
-  BLOCK_LITERAL: 'BLOCK_LITERAL',
-  /** Block folded (>) */
-  BLOCK_FOLDED: 'BLOCK_FOLDED',
-});
-
-/** Standard line width for WU YAML files */
-const YAML_LINE_WIDTH = 100;
-
-/**
- * WU-1352: Standardized YAML stringify options.
- *
- * Ensures consistent output across all WU tools:
- * - lineWidth: 100 (wrap long lines)
- * - singleQuote: true (prefer 'single' over "double")
- * - defaultKeyType: PLAIN (unquoted keys when safe)
- *
- * @type {import('yaml').ToStringOptions}
- */
-export const YAML_STRINGIFY_OPTIONS = Object.freeze({
-  lineWidth: YAML_LINE_WIDTH,
-  singleQuote: true,
-  defaultKeyType: YAML_SCALAR_TYPES.PLAIN,
-});
-
-/**
- * WU-2125: Parse YAML content string into a validated object.
- *
- * Shared parse boundary for all read functions. Wraps YAML parse errors
- * with structured error codes and path context.
- *
- * @param {string} text - Raw YAML content
- * @param {string} sourcePath - File path (for error messages)
- * @returns {Record<string, unknown>} Parsed document
- * @throws {Error} YAML_PARSE_ERROR if YAML is invalid
- */
-function parseWUYaml(text: string, sourcePath: string): Record<string, unknown> {
-  try {
-    return parse(text) as Record<string, unknown>;
-  } catch (e: unknown) {
-    const msg = getErrorMessage(e);
-    throw createError(ErrorCodes.YAML_PARSE_ERROR, `Failed to parse YAML ${sourcePath}: ${msg}`, {
-      path: sourcePath,
-      originalError: msg,
-    });
-  }
-}
-
-/**
- * WU-2125: Validate that a parsed WU document's id field matches the expected ID.
- *
- * @param {unknown} doc - Parsed YAML document (may be null for empty files)
- * @param {string} expectedId - Expected WU ID (e.g., 'WU-123')
- * @param {string} wuPath - File path (for error messages)
- * @returns {Record<string, unknown>} Validated document
- * @throws {Error} WU_NOT_FOUND if doc is null or ID does not match
- */
-function validateWUId(doc: unknown, expectedId: string, wuPath: string): Record<string, unknown> {
-  const parsed = doc as Record<string, unknown> | null;
-  if (!parsed || parsed.id !== expectedId) {
-    throw createError(
-      ErrorCodes.WU_NOT_FOUND,
-      `WU YAML id mismatch. Expected ${expectedId}, found ${parsed && parsed.id}`,
-      { path: wuPath, expectedId, foundId: parsed && parsed.id },
-    );
-  }
-  return parsed;
-}
-
-/**
- * Read and parse WU YAML file.
- *
- * Validates:
- * - File exists
- * - YAML is valid
- * - WU ID matches expected ID
- *
- * @param {string} wuPath - Path to WU YAML file
- * @param {string} expectedId - Expected WU ID (e.g., 'WU-123')
- * @returns {object} Parsed YAML document
- * @throws {Error} If file not found, YAML invalid, or ID mismatch
- */
-export function readWU(wuPath: string, expectedId: string): Record<string, unknown> {
-  if (!existsSync(wuPath)) {
-    throw createError(ErrorCodes.FILE_NOT_FOUND, `WU file not found: ${wuPath}`, {
-      path: wuPath,
-      expectedId,
-    });
-  }
-
-  const text = readFileSync(wuPath, { encoding: 'utf-8' });
-  const doc = parseWUYaml(text, wuPath);
-  return validateWUId(doc, expectedId, wuPath);
-}
-
-/**
- * Read and parse WU YAML file asynchronously.
- *
- * Validates:
- * - File exists
- * - YAML is valid
- * - WU ID matches expected ID
- *
- * @param {string} wuPath - Path to WU YAML file
- * @param {string} expectedId - Expected WU ID (e.g., 'WU-123')
- * @returns {Promise<object>} Parsed YAML document
- * @throws {Error} If file not found, YAML invalid, or ID mismatch
- */
-export async function readWUAsync(
-  wuPath: string,
-  expectedId: string,
-): Promise<Record<string, unknown>> {
-  try {
-    const text = await fs.readFile(wuPath, { encoding: 'utf-8' });
-    const doc = parseWUYaml(text, wuPath);
-    return validateWUId(doc, expectedId, wuPath);
-  } catch (err: unknown) {
-    const errObj = err as { code?: string };
-    if (errObj.code === 'ENOENT') {
-      throw createError(ErrorCodes.FILE_NOT_FOUND, `WU file not found: ${wuPath}`, {
-        path: wuPath,
-        expectedId,
-      });
-    }
-    throw err;
-  }
-}
-
-/**
- * Parse YAML string to object.
- * WU-1352: Centralized YAML parsing for consistency.
- *
- * @param {string} text - YAML string to parse
- * @returns {object} Parsed object
- * @throws {Error} If YAML is invalid
- */
-export function parseYAML(text: string): Record<string, unknown> {
-  return parse(text) as Record<string, unknown>;
-}
-
-/**
- * Stringify object to YAML with standardized options.
- * WU-1352: Centralized YAML serialization for consistency.
- *
- * @param {object} doc - Object to stringify
- * @param {object} [options] - Additional stringify options (merged with YAML_STRINGIFY_OPTIONS)
- * @returns {string} YAML string
- */
-export function stringifyYAML(doc: unknown, options: Record<string, unknown> = {}): string {
-  return stringify(doc, { ...YAML_STRINGIFY_OPTIONS, ...options });
-}
-
-/**
- * Read and parse YAML file without ID validation.
- * WU-1352: For cases where you don't know/need to validate the WU ID.
- *
- * @param {string} yamlPath - Path to YAML file
- * @returns {object} Parsed YAML document
- * @throws {Error} If file not found or YAML invalid
- */
-export function readWURaw(yamlPath: string): Record<string, unknown> {
-  if (!existsSync(yamlPath)) {
-    throw createError(ErrorCodes.FILE_NOT_FOUND, `YAML file not found: ${yamlPath}`, {
-      path: yamlPath,
-    });
-  }
-
-  const text = readFileSync(yamlPath, { encoding: 'utf-8' });
-  return parseWUYaml(text, yamlPath);
-}
-
-/**
- * Read and parse YAML file without ID validation asynchronously.
- * WU-1352: For cases where you don't know/need to validate the WU ID.
- *
- * @param {string} yamlPath - Path to YAML file
- * @returns {Promise<object>} Parsed YAML document
- * @throws {Error} If file not found or YAML invalid
- */
-export async function readWURawAsync(yamlPath: string): Promise<Record<string, unknown>> {
-  try {
-    const text = await fs.readFile(yamlPath, { encoding: 'utf-8' });
-    return parseWUYaml(text, yamlPath);
-  } catch (err: unknown) {
-    const errObj = err as { code?: string };
-    if (errObj.code === 'ENOENT') {
-      throw createError(ErrorCodes.FILE_NOT_FOUND, `YAML file not found: ${yamlPath}`, {
-        path: yamlPath,
-      });
-    }
-    throw err;
-  }
-}
-
-/**
- * Write WU YAML file with consistent formatting.
- * WU-1352: Uses YAML_STRINGIFY_OPTIONS for consistent output.
- * WU-2115: Validates doc against BaseWUSchema before writing to prevent
- * malformed WU YAML from being silently persisted.
- *
- * @param {string} wuPath - Path to WU YAML file
- * @param {object} doc - YAML document to write
- * @throws {ZodError} If doc fails BaseWUSchema validation
- */
-export function writeWU(wuPath: string, doc: unknown): void {
-  // WU-2115: Validate against schema before writing — throws ZodError on invalid data
-  BaseWUSchema.parse(doc);
-  const out = stringify(doc, YAML_STRINGIFY_OPTIONS);
-  writeFileSync(wuPath, out, { encoding: 'utf-8' });
-}
-
-/**
- * Append note to WU document's notes field.
- *
- * Always outputs a string (Zod schema requires string type).
- * Handles various input formats:
- * - undefined/null/empty: Set note directly as string
- * - string: Append with newline separator
- * - array: Convert to newline-separated string, then append
- * - other: Replace with note
- *
- * @param {object} doc - WU document
- * @param {string} note - Note to append
- */
-export function appendNote(doc: Record<string, unknown>, note: string): void {
-  // Do nothing if note is falsy
-  if (!note) return;
-
-  const existing = doc.notes;
-
-  if (existing === undefined || existing === null || existing === '') {
-    // No existing notes: set directly as string
-    doc.notes = note;
-  } else if (Array.isArray(existing)) {
-    // Array notes: convert to string first (schema requires string), then append
-    const joined = existing.filter(Boolean).join(STRING_LITERALS.NEWLINE).trimEnd();
-    doc.notes = joined ? `${joined}${STRING_LITERALS.NEWLINE}${note}` : note;
-  } else if (typeof existing === 'string') {
-    // String notes: append with newline
-    const trimmed = existing.trimEnd();
-    doc.notes = trimmed ? `${trimmed}${STRING_LITERALS.NEWLINE}${note}` : note;
-  } else {
-    // Invalid type: replace with note
-    doc.notes = note;
-  }
-}
-
-/**
- * Append an agent session entry to a WU's agent_sessions[] array
- *
- * @param {string} wuId - WU ID (e.g., "WU-1234")
- * @param {object} sessionData - Session summary from endSession()
- * @throws {Error} if WU file not found
- */
-export function appendAgentSession(wuId: string, sessionData: Record<string, unknown>): void {
-  const paths = createWuPaths();
-  const wuPath = paths.WU(wuId);
-
-  if (!existsSync(wuPath)) {
-    throw createError(ErrorCodes.FILE_NOT_FOUND, `WU file not found: ${wuPath}`);
-  }
-
-  // Parse WU YAML
-  const doc = readWU(wuPath, wuId);
-
-  // Initialize agent_sessions array if needed
-  if (!Array.isArray(doc.agent_sessions)) {
-    doc.agent_sessions = [];
-  }
-
-  // Append session
-  (doc.agent_sessions as unknown[]).push(sessionData);
-
-  // Write back
-  writeWU(wuPath, doc);
-}