@libar-dev/architect 1.0.0-pre.3

package/dist/cli/cli-schema.js

@@ -0,0 +1,505 @@
+/**
+ * @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.
+ */
+// =============================================================================
+// Schema Definition
+// =============================================================================
+export const CLI_SCHEMA = {
+    globalOptions: {
+        title: 'Global Options',
+        postNote: '**Config auto-detection:** If `--input` and `--features` are not provided, the CLI loads defaults from `architect.config.ts` or `architect.config.js`. If no config file exists, it falls back to filesystem-based detection. If neither works, `--input` is required.',
+        options: [
+            {
+                flag: '--input <pattern>',
+                short: '-i',
+                description: 'TypeScript glob pattern (repeatable)',
+                default: 'from config or auto-detected',
+            },
+            {
+                flag: '--features <pattern>',
+                short: '-f',
+                description: 'Gherkin glob pattern (repeatable)',
+                default: 'from config or auto-detected',
+            },
+            {
+                flag: '--base-dir <dir>',
+                short: '-b',
+                description: 'Base directory',
+                default: 'cwd',
+            },
+            {
+                flag: '--workflow <file>',
+                short: '-w',
+                description: 'Workflow config JSON',
+                default: 'default',
+            },
+            {
+                flag: '--help',
+                short: '-h',
+                description: 'Show help',
+            },
+            {
+                flag: '--version',
+                short: '-v',
+                description: 'Show version',
+            },
+        ],
+    },
+    outputModifiers: {
+        title: 'Output Modifiers',
+        singularTitle: 'Output Modifier',
+        description: 'Composable with `list`, `arch context/layer`, and pattern-array `query` methods.',
+        postNote: [
+            'Valid fields for `--fields`: `patternName`, `status`, `category`, `phase`, `file`, `source`.',
+            '',
+            'Precedence: `--count` > `--names-only` > `--fields` > default summarize.',
+            '',
+            '**Note on summarization:** By default, pattern arrays are summarized to ~100 bytes per pattern (from ~3.5KB raw). Use `--full` to get complete pattern objects.',
+        ].join('\n'),
+        options: [
+            {
+                flag: '--names-only',
+                description: 'Return array of pattern name strings',
+            },
+            {
+                flag: '--count',
+                description: 'Return integer count',
+            },
+            {
+                flag: '--fields <f1,f2,...>',
+                description: 'Return only specified fields per pattern',
+            },
+            {
+                flag: '--full',
+                description: 'Bypass summarization, return raw patterns',
+            },
+            {
+                flag: '--format <fmt>',
+                description: '`json` (default, pretty-printed) or `compact`',
+            },
+        ],
+    },
+    listFilters: {
+        title: 'List Filters',
+        singularTitle: 'List Filter',
+        description: 'For the `list` subcommand. All filters are composable.',
+        options: [
+            {
+                flag: '--status <status>',
+                description: 'Filter by FSM status (roadmap, active, completed, deferred)',
+            },
+            {
+                flag: '--phase <number>',
+                description: 'Filter by roadmap phase number',
+            },
+            {
+                flag: '--category <name>',
+                description: 'Filter by category',
+            },
+            {
+                flag: '--source <ts|gherkin>',
+                description: 'Filter by source type',
+            },
+            {
+                flag: '--arch-context <name>',
+                description: 'Filter by architecture context',
+            },
+            {
+                flag: '--product-area <name>',
+                description: 'Filter by product area',
+            },
+            {
+                flag: '--limit <n>',
+                description: 'Maximum results',
+            },
+            {
+                flag: '--offset <n>',
+                description: 'Skip first n results',
+            },
+        ],
+    },
+    sessionOptions: {
+        title: 'Session Types',
+        description: 'For the `--session` flag used with `context` and `scope-validate`.',
+        options: [
+            {
+                flag: '--session <type>',
+                description: 'Session type: `planning`, `design`, or `implement`',
+            },
+        ],
+    },
+    // ===========================================================================
+    // Command Narratives (from docs/PROCESS-API.md)
+    // ===========================================================================
+    commandNarratives: [
+        // ---- Session Workflow Commands (6 text commands) ----
+        {
+            title: 'Session Workflow Commands',
+            description: 'These 6 commands output structured text (not JSON). They are designed for terminal reading and AI context consumption.',
+            commands: [
+                {
+                    command: 'overview',
+                    description: 'Executive summary: progress percentage, active phases, blocking patterns, and a CLI cheat sheet.',
+                    usageExample: 'pnpm architect:query -- overview',
+                    expectedOutput: [
+                        '=== PROGRESS ===',
+                        '318 patterns (224 completed, 47 active, 47 planned) = 70%',
+                        '',
+                        '=== ACTIVE PHASES ===',
+                        'Phase 24: ProcessStateAPIRelationshipQueries (1 active)',
+                        'Phase 25: DataAPIStubIntegration (1 active)',
+                        '',
+                        '=== BLOCKING ===',
+                        'StepLintExtendedRules blocked by: StepLintVitestCucumber',
+                        '',
+                        '=== DATA API \u2014 Use Instead of Explore Agents ===',
+                        'pnpm architect:query -- <subcommand>',
+                        '  overview, context, scope-validate, dep-tree, list, stubs, files, rules, arch blocking',
+                    ].join('\n'),
+                },
+                {
+                    command: 'scope-validate',
+                    description: '**Highest-impact command.** Pre-flight readiness check that prevents wasted sessions. Returns a PASS/BLOCKED/WARN verdict covering: dependency completion, deliverable definitions, FSM transition validity, and design decisions.',
+                    usageExample: 'pnpm architect:query -- scope-validate MyPattern implement',
+                    details: 'Checks: dependency completion, deliverable definitions, FSM transition validity, design decisions, executable spec location. Valid session types for scope-validate: `implement`, `design`.',
+                    expectedOutput: [
+                        '=== SCOPE VALIDATION: DataAPIDesignSessionSupport (implement) ===',
+                        '',
+                        '=== CHECKLIST ===',
+                        '[PASS] Dependencies completed: 2/2 completed',
+                        '[PASS] Deliverables defined: 4 deliverable(s) found',
+                        '[BLOCKED] FSM allows transition: completed \u2192 active is not valid.',
+                        '[WARN] Design decisions recorded: No PDR/AD references found in stubs',
+                        '',
+                        '=== VERDICT ===',
+                        'BLOCKED: 1 blocker(s) prevent implement session',
+                    ].join('\n'),
+                },
+                {
+                    command: 'context',
+                    description: 'Curated context bundle tailored to session type.',
+                    usageExample: 'pnpm architect:query -- context MyPattern --session design',
+                    expectedOutput: [
+                        '=== PATTERN: ContextAssemblerImpl ===',
+                        'Status: active | Category: pattern',
+                        '## ContextAssembler \u2014 Session-Oriented Context Bundle Builder',
+                        '',
+                        'Pure function composition over MasterDataset.',
+                        'File: src/api/context-assembler.ts',
+                        '',
+                        '=== DEPENDENCIES ===',
+                        '[active] ProcessStateAPI (implementation) src/api/process-state.ts',
+                        '[completed] MasterDataset (implementation) src/validation-schemas/master-dataset.ts',
+                        '',
+                        '=== CONSUMERS ===',
+                        'ContextFormatterImpl (active)',
+                        'ProcessAPICLIImpl (active)',
+                        '',
+                        '=== ARCHITECTURE (context: api) ===',
+                        'MasterDataset (completed, read-model)',
+                        'ProcessStateAPI (active, service)',
+                        '...',
+                    ].join('\n'),
+                },
+                {
+                    command: 'dep-tree',
+                    description: 'Dependency chain with status indicators. Shows what a pattern depends on, recursively.',
+                    usageExample: 'pnpm architect:query -- dep-tree MyPattern',
+                    details: 'Use `--depth` to limit recursion depth: `pnpm architect:query -- dep-tree MyPattern --depth 2`.',
+                },
+                {
+                    command: 'files',
+                    description: 'File reading list with implementation paths. Use `--related` to include architecture neighbors.',
+                    usageExample: 'pnpm architect:query -- files MyPattern --related',
+                    expectedOutput: [
+                        '=== PRIMARY ===',
+                        'src/cli/process-api.ts',
+                        '',
+                        '=== ARCHITECTURE NEIGHBORS ===',
+                        'src/cli/version.ts',
+                        'src/cli/output-pipeline.ts',
+                        'src/cli/error-handler.ts',
+                    ].join('\n'),
+                },
+                {
+                    command: 'handoff',
+                    description: 'Captures session-end state: deliverable statuses, blockers, and modification date.',
+                    usageExample: 'pnpm architect:query -- handoff --pattern MyPattern',
+                    details: 'Use `--git` to include recent commits. Use `--session` to tag the handoff with a session id.',
+                    expectedOutput: [
+                        '=== HANDOFF: DataAPIDesignSessionSupport (review) ===',
+                        'Date: 2026-02-21 | Status: completed',
+                        '',
+                        '=== COMPLETED ===',
+                        '[x] Scope validation logic (src/api/scope-validator.ts)',
+                        '[x] Handoff document generator (src/api/handoff-generator.ts)',
+                        '',
+                        '=== BLOCKERS ===',
+                        'None',
+                    ].join('\n'),
+                },
+            ],
+        },
+        // ---- Pattern Discovery (8 JSON commands) ----
+        {
+            title: 'Pattern Discovery',
+            description: 'These commands output JSON wrapped in a `QueryResult` envelope.',
+            commands: [
+                {
+                    command: 'status',
+                    description: 'Status counts and completion percentage.',
+                    usageExample: 'pnpm architect:query -- status',
+                    details: '**Output:** `{ counts: { completed, active, planned, total }, completionPercentage, distribution }`',
+                },
+                {
+                    command: 'list',
+                    description: 'Filtered pattern listing. Composable with output modifiers and list filters.',
+                    usageExample: 'pnpm architect:query -- list --status roadmap --names-only',
+                    details: 'See Output Modifiers and List Filters for all options. Examples: `list --status active --count`, `list --phase 25 --fields patternName,status,file`.',
+                },
+                {
+                    command: 'search',
+                    description: 'Fuzzy name search with match scores. Suggests close matches when a pattern is not found.',
+                    usageExample: 'pnpm architect:query -- search EventStore',
+                },
+                {
+                    command: 'pattern',
+                    description: 'Full detail for one pattern including deliverables, dependencies, and all relationship fields.',
+                    usageExample: 'pnpm architect:query -- pattern TransformDataset',
+                    details: '**Warning:** Completed patterns can produce ~66KB of output. Prefer `context --session` for interactive sessions.',
+                },
+                {
+                    command: 'stubs',
+                    description: 'Design stubs with target paths and resolution status.',
+                    usageExample: 'pnpm architect:query -- stubs MyPattern',
+                    details: 'Use `--unresolved` to show only stubs missing target files: `pnpm architect:query -- stubs --unresolved`.',
+                },
+                {
+                    command: 'decisions',
+                    description: 'AD-N design decisions extracted from stub descriptions.',
+                    usageExample: 'pnpm architect:query -- decisions MyPattern',
+                    details: '**Note:** Returns exit code 1 when no decisions are found (unlike `list`/`search` which return empty arrays).',
+                },
+                {
+                    command: 'pdr',
+                    description: 'Cross-reference patterns mentioning a PDR number.',
+                    usageExample: 'pnpm architect:query -- pdr 1',
+                    details: '**Note:** Returns exit code 1 when no PDR references are found, same as `decisions`.',
+                },
+                {
+                    command: 'rules',
+                    description: 'Business rules and invariants extracted from Gherkin `Rule:` blocks, grouped by product area, phase, and feature.',
+                    usageExample: 'pnpm architect:query -- rules --pattern ProcessGuardDecider',
+                    details: '**Warning:** Unfiltered `rules` output can exceed 600KB. Always use `--pattern` or `--product-area` filters. **Output shape:** `{ productAreas: [{ productArea, ruleCount, invariantCount, phases: [{ phase, features: [{ pattern, source, rules }] }] }], totalRules, totalInvariants }`',
+                },
+            ],
+        },
+        // ---- Architecture Queries (11 subcommands) ----
+        {
+            title: 'Architecture Queries',
+            description: 'All architecture queries output JSON. They use `@architect-arch-*` annotations.',
+            commands: [
+                {
+                    command: 'arch roles',
+                    description: 'All arch-roles with pattern counts',
+                    usageExample: 'pnpm architect:query -- arch roles',
+                },
+                {
+                    command: 'arch context',
+                    description: 'All bounded contexts',
+                    usageExample: 'pnpm architect:query -- arch context',
+                },
+                {
+                    command: 'arch context <name>',
+                    description: 'Patterns in one bounded context',
+                    usageExample: 'pnpm architect:query -- arch context scanner',
+                },
+                {
+                    command: 'arch layer',
+                    description: 'All architecture layers',
+                    usageExample: 'pnpm architect:query -- arch layer',
+                },
+                {
+                    command: 'arch layer <name>',
+                    description: 'Patterns in one layer',
+                    usageExample: 'pnpm architect:query -- arch layer domain',
+                },
+                {
+                    command: 'arch neighborhood <pattern>',
+                    description: 'Uses, usedBy, dependsOn, same-context',
+                    usageExample: 'pnpm architect:query -- arch neighborhood EventStore',
+                },
+                {
+                    command: 'arch compare <c1> <c2>',
+                    description: 'Cross-context shared deps + integration',
+                    usageExample: 'pnpm architect:query -- arch compare scanner codec',
+                },
+                {
+                    command: 'arch coverage',
+                    description: 'Annotation completeness across input files',
+                    usageExample: 'pnpm architect:query -- arch coverage',
+                },
+                {
+                    command: 'arch dangling',
+                    description: "Broken references (names that don't exist)",
+                    usageExample: 'pnpm architect:query -- arch dangling',
+                },
+                {
+                    command: 'arch orphans',
+                    description: 'Patterns with no relationships (isolated)',
+                    usageExample: 'pnpm architect:query -- arch orphans',
+                },
+                {
+                    command: 'arch blocking',
+                    description: 'Patterns blocked by incomplete deps',
+                    usageExample: 'pnpm architect:query -- arch blocking',
+                },
+            ],
+        },
+        // ---- Metadata & Inventory (4 commands) ----
+        {
+            title: 'Metadata & Inventory',
+            commands: [
+                {
+                    command: 'tags',
+                    description: 'Tag usage report \u2014 counts per tag and value across all annotated sources.',
+                    usageExample: 'pnpm architect:query -- tags',
+                },
+                {
+                    command: 'sources',
+                    description: 'File inventory by type (TypeScript, Gherkin, Stubs, Decisions).',
+                    usageExample: 'pnpm architect:query -- sources',
+                },
+                {
+                    command: 'unannotated',
+                    description: 'TypeScript files missing the `@architect` opt-in marker. Use `--path` to scope to a directory.',
+                    usageExample: 'pnpm architect:query -- unannotated --path src/types',
+                },
+                {
+                    command: 'query',
+                    description: 'Execute any of the 26 query API methods directly by name. This is the escape hatch for methods not exposed as dedicated subcommands.',
+                    usageExample: 'pnpm architect:query -- query getStatusCounts',
+                    details: 'Integer-like arguments are automatically coerced to numbers. Run `architect --help` for the full list of available API methods. Examples: `query isValidTransition roadmap active`, `query getPatternsByPhase 18`, `query getRecentlyCompleted 5`.',
+                },
+            ],
+        },
+    ],
+    // ===========================================================================
+    // Recipes (from docs/PROCESS-API.md "Common Recipes" section)
+    // ===========================================================================
+    recipes: [
+        {
+            title: 'Common Recipes',
+            description: 'Frequently-used command sequences for daily workflow.',
+            recipes: [
+                {
+                    title: 'Starting a Session',
+                    purpose: 'The recommended session startup is three commands.',
+                    steps: [
+                        {
+                            command: 'pnpm architect:query -- overview',
+                            comment: 'project health',
+                        },
+                        {
+                            command: 'pnpm architect:query -- scope-validate MyPattern implement',
+                            comment: 'pre-flight',
+                        },
+                        {
+                            command: 'pnpm architect:query -- context MyPattern --session implement',
+                            comment: 'curated context',
+                        },
+                    ],
+                },
+                {
+                    title: 'Finding What to Work On',
+                    purpose: 'Discover available patterns, blockers, and missing implementations.',
+                    steps: [
+                        {
+                            command: 'pnpm architect:query -- list --status roadmap --names-only',
+                            comment: 'available patterns',
+                        },
+                        {
+                            command: 'pnpm architect:query -- arch blocking',
+                            comment: 'stuck patterns',
+                        },
+                        {
+                            command: 'pnpm architect:query -- stubs --unresolved',
+                            comment: 'missing implementations',
+                        },
+                    ],
+                },
+                {
+                    title: 'Investigating a Pattern',
+                    purpose: 'Deep-dive into a specific pattern: search, dependencies, neighbors, and files.',
+                    steps: [
+                        {
+                            command: 'pnpm architect:query -- search EventStore',
+                            comment: 'fuzzy name search',
+                        },
+                        {
+                            command: 'pnpm architect:query -- dep-tree MyPattern --depth 2',
+                            comment: 'dependency chain',
+                        },
+                        {
+                            command: 'pnpm architect:query -- arch neighborhood MyPattern',
+                            comment: 'what it touches',
+                        },
+                        {
+                            command: 'pnpm architect:query -- files MyPattern --related',
+                            comment: 'file paths',
+                        },
+                    ],
+                },
+                {
+                    title: 'Design Session Prep',
+                    purpose: 'Gather full context, design decisions, and stubs before a design session.',
+                    steps: [
+                        {
+                            command: 'pnpm architect:query -- context MyPattern --session design',
+                            comment: 'full context',
+                        },
+                        {
+                            command: 'pnpm architect:query -- decisions MyPattern',
+                            comment: 'design decisions',
+                        },
+                        {
+                            command: 'pnpm architect:query -- stubs MyPattern',
+                            comment: 'existing stubs',
+                        },
+                    ],
+                },
+                {
+                    title: 'Ending a Session',
+                    purpose: 'Capture session-end state for continuity.',
+                    steps: [
+                        {
+                            command: 'pnpm architect:query -- handoff --pattern MyPattern',
+                            comment: 'capture state',
+                        },
+                        {
+                            command: 'pnpm architect:query -- handoff --pattern MyPattern --git',
+                            comment: 'include commits',
+                        },
+                    ],
+                },
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=cli-schema.js.map

package/dist/cli/cli-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-schema.js","sourceRoot":"","sources":["../../src/cli/cli-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA4EH,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF,MAAM,CAAC,MAAM,UAAU,GAAc;IACnC,aAAa,EAAE;QACb,KAAK,EAAE,gBAAgB;QACvB,QAAQ,EACN,wQAAwQ;QAC1Q,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,mBAAmB;gBACzB,KAAK,EAAE,IAAI;gBACX,WAAW,EAAE,sCAAsC;gBACnD,OAAO,EAAE,8BAA8B;aACxC;YACD;gBACE,IAAI,EAAE,sBAAsB;gBAC5B,KAAK,EAAE,IAAI;gBACX,WAAW,EAAE,mCAAmC;gBAChD,OAAO,EAAE,8BAA8B;aACxC;YACD;gBACE,IAAI,EAAE,kBAAkB;gBACxB,KAAK,EAAE,IAAI;gBACX,WAAW,EAAE,gBAAgB;gBAC7B,OAAO,EAAE,KAAK;aACf;YACD;gBACE,IAAI,EAAE,mBAAmB;gBACzB,KAAK,EAAE,IAAI;gBACX,WAAW,EAAE,sBAAsB;gBACnC,OAAO,EAAE,SAAS;aACnB;YACD;gBACE,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,IAAI;gBACX,WAAW,EAAE,WAAW;aACzB;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,KAAK,EAAE,IAAI;gBACX,WAAW,EAAE,cAAc;aAC5B;SACF;KACF;IAED,eAAe,EAAE;QACf,KAAK,EAAE,kBAAkB;QACzB,aAAa,EAAE,iBAAiB;QAChC,WAAW,EAAE,kFAAkF;QAC/F,QAAQ,EAAE;YACR,8FAA8F;YAC9F,EAAE;YACF,0EAA0E;YAC1E,EAAE;YACF,iKAAiK;SAClK,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,cAAc;gBACpB,WAAW,EAAE,sCAAsC;aACpD;YACD;gBACE,IAAI,EAAE,SAAS;gBACf,WAAW,EAAE,sBAAsB;aACpC;YACD;gBACE,IAAI,EAAE,sBAAsB;gBAC5B,WAAW,EAAE,0CAA0C;aACxD;YACD;gBACE,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,2CAA2C;aACzD;YACD;gBACE,IAAI,EAAE,gBAAgB;gBACtB,WAAW,EAAE,+CAA+C;aAC7D;SACF;KACF;IAED,WAAW,EAAE;QACX,KAAK,EAAE,cAAc;QACrB,aAAa,EAAE,aAAa;QAC5B,WAAW,EAAE,wDAAwD;QACrE,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,mBAAmB;gBACzB,WAAW,EAAE,6DAA6D;aAC3E;YACD;gBACE,IAAI,EAAE,kBAAkB;gBACxB,WAAW,EAAE,gCAAgC;aAC9C;YACD;gBACE,IAAI,EAAE,mBAAmB;gBACzB,WAAW,EAAE,oBAAoB;aAClC;YACD;gBACE,IAAI,EAAE,uBAAuB;gBAC7B,WAAW,EAAE,uBAAuB;aACrC;YACD;gBACE,IAAI,EAAE,uBAAuB;gBAC7B,WAAW,EAAE,gCAAgC;aAC9C;YACD;gBACE,IAAI,EAAE,uBAAuB;gBAC7B,WAAW,EAAE,wBAAwB;aACtC;YACD;gBACE,IAAI,EAAE,aAAa;gBACnB,WAAW,EAAE,iBAAiB;aAC/B;YACD;gBACE,IAAI,EAAE,cAAc;gBACpB,WAAW,EAAE,sBAAsB;aACpC;SACF;KACF;IAED,cAAc,EAAE;QACd,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,oEAAoE;QACjF,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,kBAAkB;gBACxB,WAAW,EAAE,oDAAoD;aAClE;SACF;KACF;IAED,8EAA8E;IAC9E,gDAAgD;IAChD,8EAA8E;IAE9E,iBAAiB,EAAE;QACjB,wDAAwD;QACxD;YACE,KAAK,EAAE,2BAA2B;YAClC,WAAW,EACT,wHAAwH;YAC1H,QAAQ,EAAE;gBACR;oBACE,OAAO,EAAE,UAAU;oBACnB,WAAW,EACT,kGAAkG;oBACpG,YAAY,EAAE,kCAAkC;oBAChD,cAAc,EAAE;wBACd,kBAAkB;wBAClB,2DAA2D;wBAC3D,EAAE;wBACF,uBAAuB;wBACvB,yDAAyD;wBACzD,6CAA6C;wBAC7C,EAAE;wBACF,kBAAkB;wBAClB,0DAA0D;wBAC1D,EAAE;wBACF,uDAAuD;wBACvD,sCAAsC;wBACtC,yFAAyF;qBAC1F,CAAC,IAAI,CAAC,IAAI,CAAC;iBACb;gBACD;oBACE,OAAO,EAAE,gBAAgB;oBACzB,WAAW,EACT,oOAAoO;oBACtO,YAAY,EAAE,4DAA4D;oBAC1E,OAAO,EACL,6LAA6L;oBAC/L,cAAc,EAAE;wBACd,mEAAmE;wBACnE,EAAE;wBACF,mBAAmB;wBACnB,8CAA8C;wBAC9C,qDAAqD;wBACrD,wEAAwE;wBACxE,uEAAuE;wBACvE,EAAE;wBACF,iBAAiB;wBACjB,iDAAiD;qBAClD,CAAC,IAAI,CAAC,IAAI,CAAC;iBACb;gBACD;oBACE,OAAO,EAAE,SAAS;oBAClB,WAAW,EAAE,kDAAkD;oBAC/D,YAAY,EAAE,4DAA4D;oBAC1E,cAAc,EAAE;wBACd,uCAAuC;wBACvC,oCAAoC;wBACpC,oEAAoE;wBACpE,EAAE;wBACF,+CAA+C;wBAC/C,oCAAoC;wBACpC,EAAE;wBACF,sBAAsB;wBACtB,oEAAoE;wBACpE,qFAAqF;wBACrF,EAAE;wBACF,mBAAmB;wBACnB,+BAA+B;wBAC/B,4BAA4B;wBAC5B,EAAE;wBACF,qCAAqC;wBACrC,uCAAuC;wBACvC,mCAAmC;wBACnC,KAAK;qBACN,CAAC,IAAI,CAAC,IAAI,CAAC;iBACb;gBACD;oBACE,OAAO,EAAE,UAAU;oBACnB,WAAW,EACT,wFAAwF;oBAC1F,YAAY,EAAE,4CAA4C;oBAC1D,OAAO,EACL,iGAAiG;iBACpG;gBACD;oBACE,OAAO,EAAE,OAAO;oBAChB,WAAW,EACT,iGAAiG;oBACnG,YAAY,EAAE,mDAAmD;oBACjE,cAAc,EAAE;wBACd,iBAAiB;wBACjB,wBAAwB;wBACxB,EAAE;wBACF,gCAAgC;wBAChC,oBAAoB;wBACpB,4BAA4B;wBAC5B,0BAA0B;qBAC3B,CAAC,IAAI,CAAC,IAAI,CAAC;iBACb;gBACD;oBACE,OAAO,EAAE,SAAS;oBAClB,WAAW,EACT,oFAAoF;oBACtF,YAAY,EAAE,qDAAqD;oBACnE,OAAO,EACL,8FAA8F;oBAChG,cAAc,EAAE;wBACd,uDAAuD;wBACvD,sCAAsC;wBACtC,EAAE;wBACF,mBAAmB;wBACnB,yDAAyD;wBACzD,+DAA+D;wBAC/D,EAAE;wBACF,kBAAkB;wBAClB,MAAM;qBACP,CAAC,IAAI,CAAC,IAAI,CAAC;iBACb;aACF;SACF;QAED,gDAAgD;QAChD;YACE,KAAK,EAAE,mBAAmB;YAC1B,WAAW,EAAE,iEAAiE;YAC9E,QAAQ,EAAE;gBACR;oBACE,OAAO,EAAE,QAAQ;oBACjB,WAAW,EAAE,0CAA0C;oBACvD,YAAY,EAAE,gCAAgC;oBAC9C,OAAO,EACL,qGAAqG;iBACxG;gBACD;oBACE,OAAO,EAAE,MAAM;oBACf,WAAW,EACT,8EAA8E;oBAChF,YAAY,EAAE,4DAA4D;oBAC1E,OAAO,EACL,sJAAsJ;iBACzJ;gBACD;oBACE,OAAO,EAAE,QAAQ;oBACjB,WAAW,EACT,0FAA0F;oBAC5F,YAAY,EAAE,2CAA2C;iBAC1D;gBACD;oBACE,OAAO,EAAE,SAAS;oBAClB,WAAW,EACT,gGAAgG;oBAClG,YAAY,EAAE,kDAAkD;oBAChE,OAAO,EACL,mHAAmH;iBACtH;gBACD;oBACE,OAAO,EAAE,OAAO;oBAChB,WAAW,EAAE,uDAAuD;oBACpE,YAAY,EAAE,yCAAyC;oBACvD,OAAO,EACL,2GAA2G;iBAC9G;gBACD;oBACE,OAAO,EAAE,WAAW;oBACpB,WAAW,EAAE,yDAAyD;oBACtE,YAAY,EAAE,6CAA6C;oBAC3D,OAAO,EACL,+GAA+G;iBAClH;gBACD;oBACE,OAAO,EAAE,KAAK;oBACd,WAAW,EAAE,mDAAmD;oBAChE,YAAY,EAAE,+BAA+B;oBAC7C,OAAO,EACL,sFAAsF;iBACzF;gBACD;oBACE,OAAO,EAAE,OAAO;oBAChB,WAAW,EACT,mHAAmH;oBACrH,YAAY,EAAE,6DAA6D;oBAC3E,OAAO,EACL,2RAA2R;iBAC9R;aACF;SACF;QAED,kDAAkD;QAClD;YACE,KAAK,EAAE,sBAAsB;YAC7B,WAAW,EACT,iFAAiF;YACnF,QAAQ,EAAE;gBACR;oBACE,OAAO,EAAE,YAAY;oBACrB,WAAW,EAAE,oCAAoC;oBACjD,YAAY,EAAE,oCAAoC;iBACnD;gBACD;oBACE,OAAO,EAAE,cAAc;oBACvB,WAAW,EAAE,sBAAsB;oBACnC,YAAY,EAAE,sCAAsC;iBACrD;gBACD;oBACE,OAAO,EAAE,qBAAqB;oBAC9B,WAAW,EAAE,iCAAiC;oBAC9C,YAAY,EAAE,8CAA8C;iBAC7D;gBACD;oBACE,OAAO,EAAE,YAAY;oBACrB,WAAW,EAAE,yBAAyB;oBACtC,YAAY,EAAE,oCAAoC;iBACnD;gBACD;oBACE,OAAO,EAAE,mBAAmB;oBAC5B,WAAW,EAAE,uBAAuB;oBACpC,YAAY,EAAE,2CAA2C;iBAC1D;gBACD;oBACE,OAAO,EAAE,6BAA6B;oBACtC,WAAW,EAAE,uCAAuC;oBACpD,YAAY,EAAE,sDAAsD;iBACrE;gBACD;oBACE,OAAO,EAAE,wBAAwB;oBACjC,WAAW,EAAE,yCAAyC;oBACtD,YAAY,EAAE,oDAAoD;iBACnE;gBACD;oBACE,OAAO,EAAE,eAAe;oBACxB,WAAW,EAAE,4CAA4C;oBACzD,YAAY,EAAE,uCAAuC;iBACtD;gBACD;oBACE,OAAO,EAAE,eAAe;oBACxB,WAAW,EAAE,4CAA4C;oBACzD,YAAY,EAAE,uCAAuC;iBACtD;gBACD;oBACE,OAAO,EAAE,cAAc;oBACvB,WAAW,EAAE,2CAA2C;oBACxD,YAAY,EAAE,sCAAsC;iBACrD;gBACD;oBACE,OAAO,EAAE,eAAe;oBACxB,WAAW,EAAE,qCAAqC;oBAClD,YAAY,EAAE,uCAAuC;iBACtD;aACF;SACF;QAED,8CAA8C;QAC9C;YACE,KAAK,EAAE,sBAAsB;YAC7B,QAAQ,EAAE;gBACR;oBACE,OAAO,EAAE,MAAM;oBACf,WAAW,EACT,gFAAgF;oBAClF,YAAY,EAAE,8BAA8B;iBAC7C;gBACD;oBACE,OAAO,EAAE,SAAS;oBAClB,WAAW,EAAE,iEAAiE;oBAC9E,YAAY,EAAE,iCAAiC;iBAChD;gBACD;oBACE,OAAO,EAAE,aAAa;oBACtB,WAAW,EACT,gGAAgG;oBAClG,YAAY,EAAE,sDAAsD;iBACrE;gBACD;oBACE,OAAO,EAAE,OAAO;oBAChB,WAAW,EACT,sIAAsI;oBACxI,YAAY,EAAE,+CAA+C;oBAC7D,OAAO,EACL,oPAAoP;iBACvP;aACF;SACF;KACF;IAED,8EAA8E;IAC9E,8DAA8D;IAC9D,8EAA8E;IAE9E,OAAO,EAAE;QACP;YACE,KAAK,EAAE,gBAAgB;YACvB,WAAW,EAAE,uDAAuD;YACpE,OAAO,EAAE;gBACP;oBACE,KAAK,EAAE,oBAAoB;oBAC3B,OAAO,EAAE,oDAAoD;oBAC7D,KAAK,EAAE;wBACL;4BACE,OAAO,EAAE,kCAAkC;4BAC3C,OAAO,EAAE,gBAAgB;yBAC1B;wBACD;4BACE,OAAO,EAAE,4DAA4D;4BACrE,OAAO,EAAE,YAAY;yBACtB;wBACD;4BACE,OAAO,EAAE,+DAA+D;4BACxE,OAAO,EAAE,iBAAiB;yBAC3B;qBACF;iBACF;gBACD;oBACE,KAAK,EAAE,yBAAyB;oBAChC,OAAO,EAAE,qEAAqE;oBAC9E,KAAK,EAAE;wBACL;4BACE,OAAO,EAAE,4DAA4D;4BACrE,OAAO,EAAE,oBAAoB;yBAC9B;wBACD;4BACE,OAAO,EAAE,uCAAuC;4BAChD,OAAO,EAAE,gBAAgB;yBAC1B;wBACD;4BACE,OAAO,EAAE,4CAA4C;4BACrD,OAAO,EAAE,yBAAyB;yBACnC;qBACF;iBACF;gBACD;oBACE,KAAK,EAAE,yBAAyB;oBAChC,OAAO,EAAE,gFAAgF;oBACzF,KAAK,EAAE;wBACL;4BACE,OAAO,EAAE,2CAA2C;4BACpD,OAAO,EAAE,mBAAmB;yBAC7B;wBACD;4BACE,OAAO,EAAE,sDAAsD;4BAC/D,OAAO,EAAE,kBAAkB;yBAC5B;wBACD;4BACE,OAAO,EAAE,qDAAqD;4BAC9D,OAAO,EAAE,iBAAiB;yBAC3B;wBACD;4BACE,OAAO,EAAE,mDAAmD;4BAC5D,OAAO,EAAE,YAAY;yBACtB;qBACF;iBACF;gBACD;oBACE,KAAK,EAAE,qBAAqB;oBAC5B,OAAO,EAAE,2EAA2E;oBACpF,KAAK,EAAE;wBACL;4BACE,OAAO,EAAE,4DAA4D;4BACrE,OAAO,EAAE,cAAc;yBACxB;wBACD;4BACE,OAAO,EAAE,6CAA6C;4BACtD,OAAO,EAAE,kBAAkB;yBAC5B;wBACD;4BACE,OAAO,EAAE,yCAAyC;4BAClD,OAAO,EAAE,gBAAgB;yBAC1B;qBACF;iBACF;gBACD;oBACE,KAAK,EAAE,kBAAkB;oBACzB,OAAO,EAAE,2CAA2C;oBACpD,KAAK,EAAE;wBACL;4BACE,OAAO,EAAE,qDAAqD;4BAC9D,OAAO,EAAE,eAAe;yBACzB;wBACD;4BACE,OAAO,EAAE,2DAA2D;4BACpE,OAAO,EAAE,iBAAiB;yBAC3B;qBACF;iBACF;aACF;SACF;KACF;CACF,CAAC"}

package/dist/cli/dataset-cache.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @architect
+ * @architect-cli
+ * @architect-pattern DatasetCache
+ * @architect-status active
+ * @architect-implements DataAPICLIErgonomics
+ * @architect-arch-role infrastructure
+ * @architect-arch-context cli
+ * @architect-arch-layer infrastructure
+ * @architect-uses PipelineFactory, WorkflowConfigSchema
+ *
+ * ## Dataset Cache - MasterDataset Persistence with mtime Invalidation
+ *
+ * Caches the full PipelineResult (MasterDataset + ValidationSummary + warnings)
+ * to a JSON file. Subsequent CLI invocations skip the 2-5s pipeline rebuild
+ * when no source files have changed.
+ *
+ * ### Design Decisions
+ *
+ * - DD-1: Excludes LoadedWorkflow (contains Maps), reconstructs on load via createLoadedWorkflow()
+ * - DD-2: Cache at node_modules/.cache/architect/dataset.json
+ * - DD-3: Cache key = sha256(sorted file mtimes + pipeline options hash)
+ * - DD-4: All errors produce cache miss (never throw)
+ */
+import type { PipelineResult, PipelineOptions } from '../generators/pipeline/index.js';
+/**
+ * Resolve the cache directory for a given base directory.
+ */
+export declare function getCacheDir(baseDir: string): string;
+/**
+ * Compute a cache key from pipeline options and source file mtimes.
+ *
+ * The key captures:
+ * - Sorted list of source files with their modification times
+ * - Pipeline options that affect output (input patterns, features, baseDir, workflowPath)
+ *
+ * Any change to source files or pipeline config produces a different key.
+ */
+export declare function computeCacheKey(opts: PipelineOptions): Promise<string>;
+/**
+ * Attempt to load a cached PipelineResult.
+ *
+ * Returns `undefined` on any error (corrupt cache, key mismatch, etc.).
+ * Never throws — the caller should fall back to running the full pipeline.
+ */
+export declare function tryLoadCache(cacheKey: string, cacheDir: string): Promise<{
+    result: PipelineResult;
+    ageMs: number;
+} | undefined>;
+/**
+ * Write a PipelineResult to the cache file.
+ *
+ * Strips the non-serializable `workflow` field and stores the `WorkflowConfig`
+ * separately for reconstruction on load. Uses atomic write (tmp + rename).
+ *
+ * Never throws — cache write failures are silently ignored.
+ */
+export declare function writeCache(result: PipelineResult, cacheKey: string, cacheDir: string): Promise<void>;
+/**
+ * Check whether a cache file exists (for dry-run reporting).
+ */
+export declare function cacheFileExists(cacheDir: string): {
+    exists: boolean;
+    sizeBytes?: number;
+};
+//# sourceMappingURL=dataset-cache.d.ts.map

package/dist/cli/dataset-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-cache.d.ts","sourceRoot":"","sources":["../../src/cli/dataset-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AA+BvF;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CA6C5E;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAgChE;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAQzF"}