@lumenflow/packs-software-delivery 4.24.0 → 5.0.0

package/dist/src/ports/wu-state.ports.d.ts

@@ -0,0 +1,209 @@
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+//# sourceMappingURL=wu-state.ports.d.ts.map

package/dist/src/ports/wu-state.ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-state.ports.d.ts","sourceRoot":"","sources":["../../../src/ports/wu-state.ports.ts"],"names":[],"mappings":"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"}

package/dist/src/ports/wu-state.ports.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};
+//# sourceMappingURL=wu-state.ports.js.map

package/dist/src/ports/wu-state.ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-state.ports.js","sourceRoot":"","sources":["../../../src/ports/wu-state.ports.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC"}

package/dist/src/primitives/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/src/primitives/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/primitives/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC"}

package/dist/src/primitives/index.js

@@ -0,0 +1,5 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+// Barrel for pack-local primitives. Populated by Layers 2-4 of INIT-058.
+export {};
+//# sourceMappingURL=index.js.map

package/dist/src/primitives/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/primitives/index.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC,yEAAyE;AACzE,OAAO,EAAE,CAAC"}

package/dist/src/runtime/index.d.ts

@@ -0,0 +1,2 @@
+export * from './work-classifier.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/index.ts"],"names":[],"mappings":"AAKA,cAAc,sBAAsB,CAAC"}

package/dist/src/runtime/index.js

@@ -0,0 +1,6 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+// 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';
+//# sourceMappingURL=index.js.map

package/dist/src/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC,qEAAqE;AACrE,oFAAoF;AACpF,cAAc,sBAAsB,CAAC"}

package/dist/src/runtime/work-classifier.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Work domain enum-style constants
+ */
+export declare const WORK_DOMAINS: {
+    readonly UI: "ui";
+    readonly BACKEND: "backend";
+    readonly DOCS: "docs";
+    readonly INFRA: "infra";
+    readonly MIXED: "mixed";
+};
+export type WorkDomain = (typeof WORK_DOMAINS)[keyof typeof WORK_DOMAINS];
+/**
+ * Classifier-produced methodology hints consumed by prompt guidance builders.
+ */
+export declare const TEST_METHODOLOGY_HINTS: {
+    readonly SMOKE_TEST: "smoke-test";
+    readonly STRUCTURED_CONTENT: "structured-content";
+};
+export type TestMethodologyHint = (typeof TEST_METHODOLOGY_HINTS)[keyof typeof TEST_METHODOLOGY_HINTS];
+/**
+ * Signal weights for each source type.
+ * Confidence = max(matched_signal_weights), not sum.
+ */
+export declare const SIGNAL_WEIGHTS: {
+    readonly CODE_PATHS: 1;
+    readonly LANE: 0.6;
+    readonly TYPE: 0.3;
+    readonly DESCRIPTION: 0.2;
+};
+/**
+ * Built-in default UI code path patterns (minimatch glob patterns).
+ * CSS/SCSS/LESS, components/pages directories, app page/layout files,
+ * module CSS, styled components.
+ */
+export declare const DEFAULT_UI_CODE_PATH_PATTERNS: readonly string[];
+/**
+ * Built-in default UI lane hints.
+ * Matched against the lane parent (part before the colon).
+ */
+export declare const DEFAULT_UI_LANE_HINTS: readonly string[];
+/**
+ * A signal that contributed to the classification.
+ */
+export interface WorkSignal {
+    /** Signal source: 'code_paths' | 'lane' | 'type' | 'description' */
+    source: string;
+    /** The domain this signal points to */
+    domain: WorkDomain;
+    /** The weight of this signal */
+    weight: number;
+    /** What matched (e.g., the pattern or keyword) */
+    match: string;
+}
+/**
+ * Result of classifyWork.
+ */
+export interface WorkClassification {
+    /** Detected work domain */
+    domain: WorkDomain;
+    /** Confidence score (max signal weight, 0 if no match) */
+    confidence: number;
+    /** Individual signals that contributed */
+    signals: WorkSignal[];
+    /** Abstract capability tags (NOT client skill names) */
+    capabilities: string[];
+    /** Test methodology hint, e.g. smoke-test (UI) or structured-content (non-code content) */
+    testMethodologyHint?: TestMethodologyHint;
+}
+/**
+ * Optional configuration to extend defaults.
+ * Maps to methodology.work_classification in workspace.yaml.
+ */
+export interface WorkClassificationConfig {
+    ui?: {
+        /** Additional code_path_patterns (extend defaults) */
+        code_path_patterns?: string[];
+        /** Additional lane_hints (extend defaults) */
+        lane_hints?: string[];
+    };
+}
+/**
+ * Classify work domain from multiple weighted signals.
+ *
+ * Signal weights:
+ * - code_paths patterns: 1.0
+ * - lane hints: 0.6
+ * - WU type: 0.3
+ * - description keywords: 0.2
+ *
+ * Confidence = max(matched signal weights for winning domain).
+ * Domain only assigned when confidence >= 0.3.
+ *
+ * @param doc - WU document (code_paths, lane, type, description)
+ * @param config - Optional config to extend default patterns
+ * @returns WorkClassification with domain, confidence, signals, capabilities, testMethodologyHint
+ */
+export declare function classifyWork(doc: {
+    code_paths?: string[];
+    lane?: string;
+    type?: string;
+    description?: string;
+}, config?: WorkClassificationConfig): WorkClassification;
+//# sourceMappingURL=work-classifier.d.ts.map

package/dist/src/runtime/work-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-classifier.d.ts","sourceRoot":"","sources":["../../../src/runtime/work-classifier.ts"],"names":[],"mappings":"AAqBA;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;CAMf,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE1E;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;CAGzB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAC7B,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,OAAO,sBAAsB,CAAC,CAAC;AAEvE;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC;AA8BX;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAezD,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAKjD,CAAC;AA0FH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,MAAM,EAAE,UAAU,CAAC;IACnB,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,wDAAwD;IACxD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,2FAA2F;IAC3F,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,EAAE,CAAC,EAAE;QACH,sDAAsD;QACtD,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;QAC9B,8CAA8C;QAC9C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;CACH;AA0GD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,EACD,MAAM,CAAC,EAAE,wBAAwB,GAChC,kBAAkB,CAwLpB"}