@libar-dev/architect 1.0.0-pre.3

package/dist/api/summarize.js

@@ -0,0 +1,97 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern PatternSummarizerImpl
+ * @architect-status active
+ * @architect-implements DataAPIOutputShaping
+ * @architect-uses ProcessStateAPI
+ * @architect-used-by OutputPipeline, ProcessAPICLIImpl
+ * @architect-arch-role service
+ * @architect-arch-context api
+ * @architect-arch-layer application
+ *
+ * ## PatternSummarizer — Compact Pattern Projection
+ *
+ * Projects the full ExtractedPattern (~3.5KB per pattern) down to a
+ * PatternSummary (~100 bytes) for list queries. Reduces CLI output
+ * from ~594KB to ~4KB for typical codebases.
+ *
+ * Uses Zod schema-first pattern: PatternSummarySchema defines the type,
+ * and PatternSummary is inferred from it.
+ *
+ * **When to Use:** When projecting full ExtractedPattern data down to compact summaries for list and overview queries.
+ */
+import { z } from 'zod';
+import { getPatternName } from './pattern-helpers.js';
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+/**
+ * Compact projection of ExtractedPattern for list queries.
+ *
+ * Fields selected for maximum information density at minimum size:
+ * - patternName: identifies the pattern
+ * - status: FSM state (roadmap/active/completed/deferred)
+ * - category: domain classification
+ * - phase: roadmap phase number (for sequencing)
+ * - file: source file path (for navigation)
+ * - source: typescript or gherkin (for filtering)
+ */
+export const PatternSummarySchema = z.object({
+    patternName: z.string(),
+    status: z.string().optional(),
+    category: z.string(),
+    phase: z.number().int().optional(),
+    file: z.string(),
+    source: z.enum(['typescript', 'gherkin']),
+});
+/**
+ * Valid field names for PatternSummary, used by --fields validation.
+ */
+export const SUMMARY_FIELDS = new Set([
+    'patternName',
+    'status',
+    'category',
+    'phase',
+    'file',
+    'source',
+]);
+// ---------------------------------------------------------------------------
+// Functions
+// ---------------------------------------------------------------------------
+/**
+ * Derive source type from file extension.
+ */
+export function deriveSource(filePath) {
+    return filePath.endsWith('.feature') ? 'gherkin' : 'typescript';
+}
+/**
+ * Project an ExtractedPattern to a compact PatternSummary.
+ *
+ * - `patternName` prefers explicit @architect-pattern tag, falls back to `name`
+ * - `source` is derived from file extension (.feature -> gherkin, else typescript)
+ * - Optional fields (status, phase) are included when present, omitted when undefined
+ *
+ * @param pattern - Full ExtractedPattern from the pipeline
+ * @returns Compact PatternSummary (~100 bytes JSON)
+ */
+export function summarizePattern(pattern) {
+    return {
+        patternName: getPatternName(pattern),
+        category: pattern.category,
+        file: pattern.source.file,
+        source: deriveSource(pattern.source.file),
+        ...(pattern.status !== undefined && { status: pattern.status }),
+        ...(pattern.phase !== undefined && { phase: pattern.phase }),
+    };
+}
+/**
+ * Project an array of ExtractedPatterns to compact summaries.
+ *
+ * @param patterns - Array of ExtractedPatterns
+ * @returns Array of PatternSummary objects
+ */
+export function summarizePatterns(patterns) {
+    return patterns.map(summarizePattern);
+}
+//# sourceMappingURL=summarize.js.map

package/dist/api/summarize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarize.js","sourceRoot":"","sources":["../../src/api/summarize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAClC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;CAC1C,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC;IACzD,aAAa;IACb,QAAQ;IACR,UAAU;IACV,OAAO;IACP,MAAM;IACN,QAAQ;CACT,CAAC,CAAC;AAEH,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,OAAO,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC;AAClE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAyB;IACxD,OAAO;QACL,WAAW,EAAE,cAAc,CAAC,OAAO,CAAC;QACpC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI;QACzB,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;QACzC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QAC/D,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;KAC7D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAqC;IAErC,OAAO,QAAQ,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AACxC,CAAC"}

package/dist/api/types.d.ts

@@ -0,0 +1,221 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern ProcessStateTypes
+ * @architect-status active
+ * @architect-depends-on:MasterDataset
+ *
+ * ## Process State API Types
+ *
+ * Type definitions for the ProcessStateAPI query interface.
+ * Designed for programmatic access by Claude Code and other tools.
+ *
+ * ### When to Use
+ *
+ * - Import types when working with ProcessStateAPI responses
+ * - Use QueryResult<T> for typed response handling
+ */
+import type { DeliverableStatus, ProcessStatusValue } from '../taxonomy/index.js';
+import type { ExtractedPattern } from '../validation-schemas/extracted-pattern.js';
+import type { ImplementationRef } from '../validation-schemas/master-dataset.js';
+/**
+ * Optional extended metadata for query responses.
+ * Populated when the pipeline runs (not for FSM short-circuit queries).
+ */
+export interface QueryMetadataExtra {
+    readonly validation?: {
+        readonly danglingReferenceCount: number;
+        readonly malformedPatternCount: number;
+        readonly unknownStatusCount: number;
+        readonly warningCount: number;
+    };
+    readonly cache?: {
+        readonly hit: boolean;
+        readonly ageMs?: number;
+    };
+    readonly pipelineMs?: number;
+}
+/**
+ * Successful query response
+ */
+export interface QuerySuccess<T> {
+    success: true;
+    data: T;
+    metadata: {
+        timestamp: string;
+        patternCount: number;
+    } & QueryMetadataExtra;
+}
+/**
+ * Error codes for query failures
+ */
+export type QueryErrorCode = 'INVALID_ARGUMENT' | 'INVALID_STATUS' | 'INVALID_TRANSITION' | 'PATTERN_NOT_FOUND' | 'PHASE_NOT_FOUND' | 'QUARTER_NOT_FOUND' | 'CATEGORY_NOT_FOUND' | 'CONTEXT_NOT_FOUND' | 'STUB_NOT_FOUND' | 'PDR_NOT_FOUND' | 'CONTEXT_ASSEMBLY_ERROR' | 'UNKNOWN_METHOD';
+/**
+ * Failed query response
+ */
+export interface QueryError {
+    success: false;
+    error: string;
+    code: QueryErrorCode;
+}
+/**
+ * Query result union type
+ */
+export type QueryResult<T> = QuerySuccess<T> | QueryError;
+/**
+ * Status counts response
+ */
+export interface StatusCounts {
+    completed: number;
+    active: number;
+    planned: number;
+    total: number;
+}
+/**
+ * Status distribution with percentages
+ */
+export interface StatusDistribution {
+    counts: StatusCounts;
+    percentages: {
+        completed: number;
+        active: number;
+        planned: number;
+    };
+}
+/**
+ * Phase progress summary
+ */
+export interface PhaseProgress {
+    phaseNumber: number;
+    phaseName: string | undefined;
+    completed: number;
+    active: number;
+    planned: number;
+    total: number;
+    completionPercentage: number;
+}
+/**
+ * Phase group with patterns
+ */
+export interface PhaseGroup {
+    phaseNumber: number;
+    phaseName: string | undefined;
+    patterns: ExtractedPattern[];
+    counts: StatusCounts;
+}
+/**
+ * Pattern dependencies
+ */
+export interface PatternDependencies {
+    /** Patterns this pattern depends on */
+    dependsOn: readonly string[];
+    /** Patterns this pattern enables */
+    enables: readonly string[];
+    /** Patterns this pattern uses */
+    uses: readonly string[];
+    /** Patterns that use this pattern */
+    usedBy: readonly string[];
+}
+/**
+ * Complete pattern relationships (includes all relationship types)
+ *
+ * Used by ProcessStateAPI.getPatternRelationships() to expose the full
+ * relationship graph from the MasterDataset's relationshipIndex.
+ */
+export interface PatternRelationships {
+    /** Patterns this pattern depends on (from @architect-depends-on) */
+    dependsOn: readonly string[];
+    /** Patterns this pattern enables (from @architect-enables) */
+    enables: readonly string[];
+    /** Patterns this pattern uses (from @architect-uses) */
+    uses: readonly string[];
+    /** Patterns that use this pattern (from @architect-used-by) */
+    usedBy: readonly string[];
+    /** Patterns this code implements (from @architect-implements) */
+    implementsPatterns: readonly string[];
+    /** Files that implement this pattern with metadata (computed inverse) */
+    implementedBy: readonly ImplementationRef[];
+    /** Pattern this extends (from @architect-extends) */
+    extendsPattern: string | undefined;
+    /** Patterns that extend this pattern (computed inverse) */
+    extendedBy: readonly string[];
+    /** Related patterns for cross-reference without dependency (from @architect-see-also) */
+    seeAlso: readonly string[];
+    /** File paths to implementation APIs (from @architect-api-ref) */
+    apiRef: readonly string[];
+}
+/**
+ * Pattern deliverables from feature files
+ *
+ * Matches the DeliverableSchema structure from dual-source.ts
+ */
+export interface PatternDeliverable {
+    /** Deliverable name/description */
+    name: string;
+    /** Canonical deliverable status */
+    status: DeliverableStatus;
+    /** Number of tests */
+    tests: number;
+    /** Implementation location */
+    location: string;
+    /** Optional finding ID for review traceability */
+    finding: string | undefined;
+    /** Optional release version for changelog grouping */
+    release: string | undefined;
+}
+/**
+ * Quarter grouping
+ */
+export interface QuarterGroup {
+    quarter: string;
+    patterns: ExtractedPattern[];
+    counts: StatusCounts;
+}
+/**
+ * Transition validation result
+ */
+export interface TransitionCheck {
+    from: ProcessStatusValue;
+    to: ProcessStatusValue;
+    valid: boolean;
+    error: string | undefined;
+    validAlternatives: readonly ProcessStatusValue[] | undefined;
+}
+/**
+ * Protection level info
+ */
+export interface ProtectionInfo {
+    status: ProcessStatusValue;
+    level: 'none' | 'scope' | 'hard';
+    description: string;
+    canAddDeliverables: boolean;
+    requiresUnlock: boolean;
+}
+/**
+ * Entry for a neighboring pattern with architecture metadata.
+ * Shared between ContextAssembler and ArchQueries.
+ */
+export interface NeighborEntry {
+    readonly name: string;
+    readonly status: string | undefined;
+    readonly archRole: string | undefined;
+    readonly archContext: string | undefined;
+    readonly file: string | undefined;
+}
+/**
+ * Create a success response with optional extended metadata.
+ */
+export declare function createSuccess<T>(data: T, patternCount: number, extra?: QueryMetadataExtra): QuerySuccess<T>;
+/**
+ * Create an error response
+ */
+export declare function createError(code: QueryErrorCode, message: string): QueryError;
+/**
+ * Structured error for API and CLI domain errors.
+ * Caught at the CLI boundary and converted to QueryError envelope.
+ */
+export declare class QueryApiError extends Error {
+    readonly code: QueryErrorCode;
+    constructor(code: QueryErrorCode, message: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/types.d.ts.map

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

package/dist/api/types.js

@@ -0,0 +1,57 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern ProcessStateTypes
+ * @architect-status active
+ * @architect-depends-on:MasterDataset
+ *
+ * ## Process State API Types
+ *
+ * Type definitions for the ProcessStateAPI query interface.
+ * Designed for programmatic access by Claude Code and other tools.
+ *
+ * ### When to Use
+ *
+ * - Import types when working with ProcessStateAPI responses
+ * - Use QueryResult<T> for typed response handling
+ */
+// =============================================================================
+// Helper Type for Creating Responses
+// =============================================================================
+/**
+ * Create a success response with optional extended metadata.
+ */
+export function createSuccess(data, patternCount, extra) {
+    return {
+        success: true,
+        data,
+        metadata: {
+            timestamp: new Date().toISOString(),
+            patternCount,
+            ...extra,
+        },
+    };
+}
+/**
+ * Create an error response
+ */
+export function createError(code, message) {
+    return {
+        success: false,
+        error: message,
+        code,
+    };
+}
+/**
+ * Structured error for API and CLI domain errors.
+ * Caught at the CLI boundary and converted to QueryError envelope.
+ */
+export class QueryApiError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'QueryApiError';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/api/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAsPH,gFAAgF;AAChF,qCAAqC;AACrC,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAO,EACP,YAAoB,EACpB,KAA0B;IAE1B,OAAO;QACL,OAAO,EAAE,IAAI;QACb,IAAI;QACJ,QAAQ,EAAE;YACR,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,YAAY;YACZ,GAAG,KAAK;SACT;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,IAAoB,EAAE,OAAe;IAC/D,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,OAAO;QACd,IAAI;KACL,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,IAAI,CAAiB;IAE9B,YAAY,IAAoB,EAAE,OAAe;QAC/C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/cache/file-cache.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @architect
+ * @architect-pattern FileCache
+ * @architect-status active
+ * @architect-arch-role infrastructure
+ * @architect-arch-context generator
+ * @architect-arch-layer infrastructure
+ *
+ * ## File Cache - Request-Scoped Content Caching
+ *
+ * Simple Map-based cache for file contents during a single generation run.
+ * Avoids repeated disk reads for files accessed multiple times during
+ * extraction and deduplication phases.
+ *
+ * ### Design Rationale
+ *
+ * - **Request-scoped**: Created fresh per orchestrator run, naturally cleared when done
+ * - **No eviction needed**: Generation runs are bounded in duration and file count
+ * - **Thread-safe**: Single-threaded Node.js, no locking required
+ * - **Stats tracking**: Optional hit/miss tracking for performance analysis
+ *
+ * **When to Use:** When a generation run reads the same file multiple times — create a cache instance per orchestrator run.
+ */
+/**
+ * File content cache interface
+ */
+export interface FileCache {
+    /** Get cached content by absolute path */
+    get(path: string): string | undefined;
+    /** Store content in cache */
+    set(path: string, content: string): void;
+    /** Check if path is cached */
+    has(path: string): boolean;
+    /** Clear all cached content */
+    clear(): void;
+    /** Get cache statistics */
+    getStats(): FileCacheStats;
+}
+/**
+ * Cache statistics for performance analysis
+ */
+export interface FileCacheStats {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Number of entries currently in cache */
+    size: number;
+    /** Hit rate as percentage (0-100) */
+    hitRate: number;
+}
+/**
+ * Create a new file content cache
+ *
+ * @returns Fresh FileCache instance
+ *
+ * @example
+ * ```typescript
+ * const cache = createFileCache();
+ *
+ * // First access reads from disk
+ * const content = await readFile(path);
+ * cache.set(path, content);
+ *
+ * // Subsequent access uses cache
+ * if (cache.has(path)) {
+ *   return cache.get(path);
+ * }
+ * ```
+ */
+export declare function createFileCache(): FileCache;
+//# sourceMappingURL=file-cache.d.ts.map

package/dist/cache/file-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-cache.d.ts","sourceRoot":"","sources":["../../src/cache/file-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,0CAA0C;IAC1C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAEtC,6BAA6B;IAC7B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzC,8BAA8B;IAC9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAE3B,+BAA+B;IAC/B,KAAK,IAAI,IAAI,CAAC;IAEd,2BAA2B;IAC3B,QAAQ,IAAI,cAAc,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IAEb,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IAEf,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IAEb,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,IAAI,SAAS,CAwC3C"}

package/dist/cache/file-cache.js

@@ -0,0 +1,80 @@
+/**
+ * @architect
+ * @architect-pattern FileCache
+ * @architect-status active
+ * @architect-arch-role infrastructure
+ * @architect-arch-context generator
+ * @architect-arch-layer infrastructure
+ *
+ * ## File Cache - Request-Scoped Content Caching
+ *
+ * Simple Map-based cache for file contents during a single generation run.
+ * Avoids repeated disk reads for files accessed multiple times during
+ * extraction and deduplication phases.
+ *
+ * ### Design Rationale
+ *
+ * - **Request-scoped**: Created fresh per orchestrator run, naturally cleared when done
+ * - **No eviction needed**: Generation runs are bounded in duration and file count
+ * - **Thread-safe**: Single-threaded Node.js, no locking required
+ * - **Stats tracking**: Optional hit/miss tracking for performance analysis
+ *
+ * **When to Use:** When a generation run reads the same file multiple times — create a cache instance per orchestrator run.
+ */
+/**
+ * Create a new file content cache
+ *
+ * @returns Fresh FileCache instance
+ *
+ * @example
+ * ```typescript
+ * const cache = createFileCache();
+ *
+ * // First access reads from disk
+ * const content = await readFile(path);
+ * cache.set(path, content);
+ *
+ * // Subsequent access uses cache
+ * if (cache.has(path)) {
+ *   return cache.get(path);
+ * }
+ * ```
+ */
+export function createFileCache() {
+    const store = new Map();
+    let hits = 0;
+    let misses = 0;
+    return {
+        get(path) {
+            const content = store.get(path);
+            if (content !== undefined) {
+                hits++;
+            }
+            else {
+                misses++;
+            }
+            return content;
+        },
+        set(path, content) {
+            store.set(path, content);
+        },
+        has(path) {
+            return store.has(path);
+        },
+        clear() {
+            store.clear();
+            hits = 0;
+            misses = 0;
+        },
+        getStats() {
+            const total = hits + misses;
+            return {
+                hits,
+                misses,
+                size: store.size,
+                hitRate: total > 0 ? (hits / total) * 100 : 0,
+            };
+        },
+    };
+}
+//# sourceMappingURL=file-cache.js.map

package/dist/cache/file-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-cache.js","sourceRoot":"","sources":["../../src/cache/file-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAuCH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,OAAO;QACL,GAAG,CAAC,IAAY;YACd,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,IAAI,EAAE,CAAC;YACT,CAAC;iBAAM,CAAC;gBACN,MAAM,EAAE,CAAC;YACX,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,GAAG,CAAC,IAAY,EAAE,OAAe;YAC/B,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC3B,CAAC;QAED,GAAG,CAAC,IAAY;YACd,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;QAED,KAAK;YACH,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,IAAI,GAAG,CAAC,CAAC;YACT,MAAM,GAAG,CAAC,CAAC;QACb,CAAC;QAED,QAAQ;YACN,MAAM,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;YAC5B,OAAO;gBACL,IAAI;gBACJ,MAAM;gBACN,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;aAC9C,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/cache/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Cache module exports
+ */
+export { createFileCache, type FileCache, type FileCacheStats } from './file-cache.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/cache/index.js

@@ -0,0 +1,5 @@
+/**
+ * Cache module exports
+ */
+export { createFileCache } from './file-cache.js';
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,eAAe,EAAuC,MAAM,iBAAiB,CAAC"}

package/dist/cli/cli-schema.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @architect
+ * @architect-pattern CLISchema
+ * @architect-status completed
+ * @architect-unlock-reason:Add-recipe-and-narrative-fields-for-CliRecipeCodec
+ * @architect-implements ProcessApiHybridGeneration
+ * @architect-arch-context cli
+ * @architect-arch-layer domain
+ * @architect-product-area:DataAPI
+ *
+ * ## CLI Schema — Single Source of Truth for CLI Reference
+ *
+ * Declarative schema defining all CLI options for the architect command.
+ * Consumed by:
+ * - `showHelp()` in process-api.ts (terminal help text)
+ * - `ProcessApiReferenceGenerator` (generated markdown reference)
+ *
+ * This eliminates three-way sync between parser code, help text, and docs.
+ */
+export interface CLIOptionDef {
+    /** Flag with value placeholder, e.g., '--input <pattern>' */
+    readonly flag: string;
+    /** Short alias, e.g., '-i' */
+    readonly short?: string;
+    /** Human-readable description */
+    readonly description: string;
+    /** Default value display string */
+    readonly default?: string;
+}
+export interface CLIOptionGroup {
+    /** Section heading */
+    readonly title: string;
+    /** Singular form of title for column headers in two-column tables */
+    readonly singularTitle?: string;
+    /** Intro prose rendered above the table */
+    readonly description?: string;
+    /** Prose rendered below the table */
+    readonly postNote?: string;
+    /** Option definitions */
+    readonly options: readonly CLIOptionDef[];
+}
+/** A single step in a recipe — one CLI command with an explanatory comment. */
+export interface RecipeStep {
+    readonly command: string;
+    readonly comment?: string;
+}
+/** A complete recipe example — a titled sequence of commands with context. */
+export interface RecipeExample {
+    readonly title: string;
+    readonly purpose: string;
+    readonly steps: readonly RecipeStep[];
+    readonly expectedOutput?: string;
+}
+/** A group of related recipes under a shared heading. */
+export interface RecipeGroup {
+    readonly title: string;
+    readonly description?: string;
+    readonly recipes: readonly RecipeExample[];
+}
+/** Narrative metadata for a single CLI command. */
+export interface CommandNarrative {
+    readonly command: string;
+    readonly description: string;
+    readonly usageExample: string;
+    readonly details?: string;
+    readonly expectedOutput?: string;
+}
+/** A group of related command narratives under a shared section heading. */
+export interface CommandNarrativeGroup {
+    readonly title: string;
+    readonly description?: string;
+    readonly commands: readonly CommandNarrative[];
+}
+export interface CLISchema {
+    readonly globalOptions: CLIOptionGroup;
+    readonly outputModifiers: CLIOptionGroup;
+    readonly listFilters: CLIOptionGroup;
+    readonly sessionOptions: CLIOptionGroup;
+    readonly recipes?: readonly RecipeGroup[];
+    readonly commandNarratives?: readonly CommandNarrativeGroup[];
+}
+export declare const CLI_SCHEMA: CLISchema;
+//# sourceMappingURL=cli-schema.d.ts.map

package/dist/cli/cli-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-schema.d.ts","sourceRoot":"","sources":["../../src/cli/cli-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,sBAAsB;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAED,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,aAAa,EAAE,cAAc,CAAC;IACvC,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC/D;AAMD,eAAO,MAAM,UAAU,EAAE,SAqgBxB,CAAC"}