@libar-dev/architect 1.0.0-pre.3

package/dist/cli/lint-steps.d.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * CLI for vitest-cucumber step/feature compatibility linting.
+ *
+ * Detects common vitest-cucumber traps statically — before tests run.
+ * Catches mismatches between .feature files and .steps.ts files that
+ * cause cryptic runtime failures.
+ */
+/**
+ * CLI configuration
+ */
+export interface LintStepsCLIConfig {
+    /** Treat warnings as errors */
+    strict: boolean;
+    /** Base directory for relative paths */
+    baseDir: string;
+    /** Output format */
+    format: 'pretty' | 'json';
+    /** Show help */
+    help: boolean;
+    /** Show version */
+    version: boolean;
+}
+/**
+ * Parse command line arguments
+ */
+export declare function parseArgs(argv?: string[]): LintStepsCLIConfig;
+/**
+ * Print usage information
+ */
+export declare function printHelp(): void;
+//# sourceMappingURL=lint-steps.d.ts.map

package/dist/cli/lint-steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint-steps.d.ts","sourceRoot":"","sources":["../../src/cli/lint-steps.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG;AAYH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,+BAA+B;IAC/B,MAAM,EAAE,OAAO,CAAC;IAChB,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B,gBAAgB;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,mBAAmB;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,kBAAkB,CAmDpF;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,CA0DhC"}

package/dist/cli/lint-steps.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * CLI for vitest-cucumber step/feature compatibility linting.
+ *
+ * Detects common vitest-cucumber traps statically — before tests run.
+ * Catches mismatches between .feature files and .steps.ts files that
+ * cause cryptic runtime failures.
+ */
+// ─── Error Convention ───────────────────────────────────────────────────
+// CLI modules use throw/catch + process.exit(). Pipeline modules use Result<T,E>.
+// See src/cli/error-handler.ts for the unified handler.
+// ────────────────────────────────────────────────────────────────────────
+import { printVersionAndExit } from './version.js';
+import { handleCliError } from './error-handler.js';
+import { runStepLint } from '../lint/steps/index.js';
+import { formatPretty, formatJson, hasFailures } from '../lint/engine.js';
+/**
+ * Parse command line arguments
+ */
+export function parseArgs(argv = process.argv.slice(2)) {
+    const config = {
+        strict: false,
+        baseDir: process.cwd(),
+        format: 'pretty',
+        help: false,
+        version: false,
+    };
+    let parsingFlags = true;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        // Handle -- separator from pnpm
+        if (arg === '--') {
+            parsingFlags = false;
+            continue;
+        }
+        if (!parsingFlags) {
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            config.help = true;
+        }
+        else if (arg === '--version' || arg === '-v') {
+            config.version = true;
+        }
+        else if (arg === '--strict') {
+            config.strict = true;
+        }
+        else if (arg === '--base-dir' || arg === '-b') {
+            const nextArg = argv[++i];
+            if (nextArg === undefined) {
+                throw new Error(`Missing value for ${arg} flag`);
+            }
+            config.baseDir = nextArg;
+        }
+        else if (arg === '--format') {
+            const nextArg = argv[++i];
+            if (nextArg === undefined) {
+                throw new Error(`Missing value for ${arg} flag`);
+            }
+            if (nextArg !== 'pretty' && nextArg !== 'json') {
+                throw new Error(`Invalid format: ${nextArg}. Use "pretty" or "json"`);
+            }
+            config.format = nextArg;
+        }
+        else if (arg?.startsWith('-') === true) {
+            console.warn(`Warning: Unknown flag '${arg}' ignored`);
+        }
+    }
+    return config;
+}
+/**
+ * Print usage information
+ */
+export function printHelp() {
+    console.log(`
+architect-lint-steps - Validate vitest-cucumber feature/step compatibility
+
+Detects common traps statically before tests run:
+  - {string} function params inside ScenarioOutline (should use variables)
+  - Missing And destructuring (causes StepAbleUnknowStepError)
+  - Missing Rule() wrapper (causes step matching failures)
+  - # in descriptions (terminates Gherkin parser context)
+  - Regex step patterns (not supported)
+  - {phrase} usage (not supported)
+  - Duplicate And step text (causes matching failures)
+  - $ in step text (causes matching issues)
+
+Usage:
+  architect-lint-steps [options]
+
+Options:
+  --strict              Treat warnings as errors (exit 1 on warnings)
+  --format <type>       Output format: "pretty" (default) or "json"
+  -b, --base-dir <dir>  Base directory for paths (default: cwd)
+  -h, --help            Show this help message
+  -v, --version         Show version number
+
+Exit Codes:
+  0  No errors (warnings allowed unless --strict)
+  1  Errors found (or warnings with --strict)
+
+Scan Scope:
+  Feature files:  tests/features/**/*.feature
+                  architect/specs/**/*.feature
+                  architect/decisions/**/*.feature
+  Step files:     tests/steps/**/*.steps.ts
+
+Rules:
+  error    hash-in-description                  # at line start in description context
+  error    duplicate-and-step                    Multiple And with same text in scenario
+  warning  dollar-in-step-text                   $ character in step text
+  error    regex-step-pattern                    Regex pattern in step definition
+  error    unsupported-phrase-type               {phrase} in step string
+  error    scenario-outline-function-params      Function params in ScenarioOutline
+  error    missing-and-destructuring             And steps but no And destructured
+  error    missing-rule-wrapper                  Rule: blocks but no Rule() wrapper
+  warning  hash-in-step-text                    Mid-line # in step text silently truncates
+  error    keyword-in-description               Description line starts with Given/When/Then/And/But
+  warning  outline-quoted-values                 Quoted values in Outline suggest wrong pattern
+  error    repeated-step-pattern                 Same step pattern registered twice in scenario
+
+Examples:
+  # Standard check
+  architect-lint-steps
+
+  # Strict mode (warnings are errors)
+  architect-lint-steps --strict
+
+  # JSON output for CI
+  architect-lint-steps --format json
+  `);
+}
+/**
+ * Main CLI function
+ */
+function main() {
+    const config = parseArgs();
+    if (config.version) {
+        printVersionAndExit('architect-lint-steps');
+    }
+    if (config.help) {
+        printHelp();
+        process.exit(0);
+    }
+    try {
+        console.log('Step Lint: checking vitest-cucumber compatibility...');
+        const summary = runStepLint({ baseDir: config.baseDir });
+        // Format and output results
+        if (config.format === 'json') {
+            const result = formatJson(summary);
+            if (result.ok) {
+                console.log(result.value);
+            }
+            else {
+                console.error(`Output formatting error: ${result.error.message}`);
+                process.exit(1);
+            }
+        }
+        else {
+            console.log(formatPretty(summary));
+        }
+        // Determine exit code
+        const failed = hasFailures(summary, config.strict);
+        process.exit(failed ? 1 : 0);
+    }
+    catch (error) {
+        handleCliError(error, 1);
+    }
+}
+// Entry point
+main();
+//# sourceMappingURL=lint-steps.js.map

package/dist/cli/lint-steps.js.map

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

package/dist/cli/mcp-server.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern MCPServerBin
+ * @architect-status active
+ * @architect-arch-role infrastructure
+ * @architect-arch-context cli
+ * @architect-arch-layer infrastructure
+ * @architect-uses MCPServerImpl
+ * @architect-implements MCPServerIntegration
+ *
+ * ## MCP Server CLI Entry Point
+ *
+ * Handles stdout isolation, CLI arg parsing, and process lifecycle.
+ * Delegates to startMcpServer() for MCP server setup.
+ *
+ * Stdout isolation MUST happen before any MCP module loads — the dynamic
+ * import below ensures the console.log redirect is active first.
+ */
+export {};
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/cli/mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../../src/cli/mcp-server.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,CAAC"}

package/dist/cli/mcp-server.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern MCPServerBin
+ * @architect-status active
+ * @architect-arch-role infrastructure
+ * @architect-arch-context cli
+ * @architect-arch-layer infrastructure
+ * @architect-uses MCPServerImpl
+ * @architect-implements MCPServerIntegration
+ *
+ * ## MCP Server CLI Entry Point
+ *
+ * Handles stdout isolation, CLI arg parsing, and process lifecycle.
+ * Delegates to startMcpServer() for MCP server setup.
+ *
+ * Stdout isolation MUST happen before any MCP module loads — the dynamic
+ * import below ensures the console.log redirect is active first.
+ */
+// Redirect console.log to stderr BEFORE loading MCP modules.
+// MCP uses JSON-RPC over stdout — stray console.log corrupts the transport.
+console.log = console.error;
+// Dynamic import ensures the redirect is active before server module loads.
+const { parseCliArgs, startMcpServer } = await import('../mcp/server.js');
+const parsed = parseCliArgs(process.argv.slice(2));
+switch (parsed.type) {
+    case 'help':
+        console.error(parsed.text);
+        process.exit(0);
+        break;
+    case 'version':
+        console.error(parsed.text);
+        process.exit(0);
+        break;
+    case 'error':
+        console.error(`[architect-mcp] Error: ${parsed.message}`);
+        process.exit(1);
+        break;
+    case 'options':
+        try {
+            await startMcpServer({
+                ...(parsed.options.input !== undefined ? { input: parsed.options.input } : {}),
+                ...(parsed.options.features !== undefined ? { features: parsed.options.features } : {}),
+                ...(parsed.options.baseDir !== undefined ? { baseDir: parsed.options.baseDir } : {}),
+                ...(parsed.options.watch !== undefined ? { watch: parsed.options.watch } : {}),
+                ...(parsed.options.version !== undefined ? { version: parsed.options.version } : {}),
+            });
+        }
+        catch (error) {
+            console.error(`Fatal error: ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
+        break;
+}
+export {};
+//# sourceMappingURL=mcp-server.js.map

package/dist/cli/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../../src/cli/mcp-server.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,6DAA6D;AAC7D,4EAA4E;AAC5E,OAAO,CAAC,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC;AAE5B,4EAA4E;AAC5E,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;AAE1E,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;IACpB,KAAK,MAAM;QACT,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChB,MAAM;IACR,KAAK,SAAS;QACZ,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChB,MAAM;IACR,KAAK,OAAO;QACV,OAAO,CAAC,KAAK,CAAC,0BAA0B,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChB,MAAM;IACR,KAAK,SAAS;QACZ,IAAI,CAAC;YACH,MAAM,cAAc,CAAC;gBACnB,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC9E,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvF,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpF,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC9E,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACrF,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,OAAO,CAAC,KAAK,CAAC,gBAAgB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACxF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM;AACV,CAAC"}

package/dist/cli/output-pipeline.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern OutputPipelineImpl
+ * @architect-status active
+ * @architect-implements DataAPIOutputShaping
+ * @architect-uses PatternSummarizerImpl
+ * @architect-used-by ProcessAPICLIImpl
+ * @architect-arch-role service
+ * @architect-arch-context cli
+ * @architect-arch-layer application
+ *
+ * ## OutputPipeline — CLI Output Shaping and Formatting
+ *
+ * Post-processing pipeline that transforms raw API results into shaped CLI output.
+ * Applies output modifiers (--names-only, --count, --fields, --full) and wraps
+ * results in QueryResult envelopes.
+ *
+ * Architecture decision: This is a single post-processing function, NOT a
+ * middleware chain. The 4 modifiers are mutually exclusive with clear precedence:
+ * count > namesOnly > fields > default summarize.
+ *
+ * **When to Use:** When processing CLI query results that need output shaping via --names-only, --count, --fields, or --full modifiers.
+ */
+import type { ExtractedPattern } from '../validation-schemas/extracted-pattern.js';
+import type { MasterDataset } from '../validation-schemas/master-dataset.js';
+import type { QueryResult } from '../api/types.js';
+/**
+ * Output modifier flags parsed from CLI arguments.
+ *
+ * Precedence: count > namesOnly > fields > default summarize.
+ * When --full is set, summarization is bypassed.
+ */
+export interface OutputModifiers {
+    /** --names-only: return array of pattern name strings */
+    readonly namesOnly: boolean;
+    /** --count: return single integer count */
+    readonly count: boolean;
+    /** --fields name,status: return only selected fields per pattern */
+    readonly fields: readonly string[] | null;
+    /** --full: bypass summarization, return raw ExtractedPattern[] */
+    readonly full: boolean;
+}
+export declare const DEFAULT_OUTPUT_MODIFIERS: OutputModifiers;
+/**
+ * Composable list filters for the `list` subcommand.
+ *
+ * Filters combine via AND logic. Each filter narrows the result set.
+ */
+export interface ListFilters {
+    /** Filter by FSM status (roadmap, active, completed, deferred) */
+    readonly status: string | null;
+    /** Filter by roadmap phase number */
+    readonly phase: number | null;
+    /** Filter by category name */
+    readonly category: string | null;
+    /** Filter by source type */
+    readonly source: 'typescript' | 'gherkin' | null;
+    /** Filter by architecture context (@architect-arch-context) */
+    readonly archContext: string | null;
+    /** Filter by product area (@architect-product-area) */
+    readonly productArea: string | null;
+    /** Maximum number of results */
+    readonly limit: number | null;
+    /** Number of results to skip */
+    readonly offset: number | null;
+}
+export declare const DEFAULT_LIST_FILTERS: ListFilters;
+/**
+ * Discriminated union for pipeline input.
+ *
+ * The router determines `kind` based on which API method was called.
+ * Pattern arrays get summarization + modifiers; scalars pass through.
+ */
+export type PipelineInput = {
+    readonly kind: 'patterns';
+    readonly data: readonly ExtractedPattern[];
+} | {
+    readonly kind: 'scalar';
+    readonly data: unknown;
+};
+/**
+ * Set of ProcessStateAPI method names that return ExtractedPattern[].
+ *
+ * Used by the router to tag results with `kind: 'patterns'` for the pipeline.
+ */
+export declare const PATTERN_ARRAY_METHODS: ReadonlySet<string>;
+/**
+ * Validate output modifier combinations.
+ * Throws on conflicts: --full + --names-only, --full + --count, --full + --fields.
+ */
+export declare function validateModifiers(modifiers: OutputModifiers): void;
+/**
+ * Apply output modifiers to pipeline input.
+ *
+ * For pattern arrays:
+ * - Default: summarize each pattern to ~100 bytes
+ * - --full: bypass summarization
+ * - --names-only: extract pattern names as string[]
+ * - --count: return array length as number
+ * - --fields: pick specific fields from each summary
+ *
+ * For scalars: pass through unchanged (modifiers do not apply).
+ */
+export declare function applyOutputPipeline(input: PipelineInput, modifiers: OutputModifiers): unknown;
+/**
+ * Apply composable filters to the pattern list.
+ *
+ * Sequential filter composition: status → phase → category → source.
+ * Pagination (offset/limit) applies after all filters.
+ */
+export declare function applyListFilters(dataset: MasterDataset, filters: ListFilters): readonly ExtractedPattern[];
+/**
+ * Strip null, undefined, and empty values from an object for compact output.
+ *
+ * Recursively removes:
+ * - null and undefined values
+ * - empty strings
+ * - empty arrays
+ * - empty objects
+ */
+export declare function stripEmpty(obj: unknown): unknown;
+/**
+ * Format a QueryResult envelope for CLI output.
+ *
+ * - json mode: pretty-printed with 2-space indent
+ * - compact mode: minified with empty values stripped
+ */
+export declare function formatOutput(envelope: QueryResult<unknown>, format: 'json' | 'compact'): string;
+//# sourceMappingURL=output-pipeline.d.ts.map

package/dist/cli/output-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-pipeline.d.ts","sourceRoot":"","sources":["../../src/cli/output-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AACnF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAE7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAQnD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAC1C,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,eAAO,MAAM,wBAAwB,EAAE,eAKtC,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,qCAAqC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI,CAAC;IACjD,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,eAAO,MAAM,oBAAoB,EAAE,WASlC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAAE,GACzE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CASpD,CAAC;AAMH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI,CA6BlE;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,GAAG,OAAO,CAoC7F;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,WAAW,GACnB,SAAS,gBAAgB,EAAE,CAmD7B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CA0BhD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM/F"}

package/dist/cli/output-pipeline.js

@@ -0,0 +1,234 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern OutputPipelineImpl
+ * @architect-status active
+ * @architect-implements DataAPIOutputShaping
+ * @architect-uses PatternSummarizerImpl
+ * @architect-used-by ProcessAPICLIImpl
+ * @architect-arch-role service
+ * @architect-arch-context cli
+ * @architect-arch-layer application
+ *
+ * ## OutputPipeline — CLI Output Shaping and Formatting
+ *
+ * Post-processing pipeline that transforms raw API results into shaped CLI output.
+ * Applies output modifiers (--names-only, --count, --fields, --full) and wraps
+ * results in QueryResult envelopes.
+ *
+ * Architecture decision: This is a single post-processing function, NOT a
+ * middleware chain. The 4 modifiers are mutually exclusive with clear precedence:
+ * count > namesOnly > fields > default summarize.
+ *
+ * **When to Use:** When processing CLI query results that need output shaping via --names-only, --count, --fields, or --full modifiers.
+ */
+import { QueryApiError } from '../api/types.js';
+import { summarizePatterns, SUMMARY_FIELDS, deriveSource } from '../api/summarize.js';
+import { getPatternName } from '../api/pattern-helpers.js';
+export const DEFAULT_OUTPUT_MODIFIERS = {
+    namesOnly: false,
+    count: false,
+    fields: null,
+    full: false,
+};
+export const DEFAULT_LIST_FILTERS = {
+    status: null,
+    phase: null,
+    category: null,
+    source: null,
+    archContext: null,
+    productArea: null,
+    limit: null,
+    offset: null,
+};
+/**
+ * Set of ProcessStateAPI method names that return ExtractedPattern[].
+ *
+ * Used by the router to tag results with `kind: 'patterns'` for the pipeline.
+ */
+export const PATTERN_ARRAY_METHODS = new Set([
+    'getPatternsByNormalizedStatus',
+    'getPatternsByStatus',
+    'getPatternsByPhase',
+    'getPatternsByCategory',
+    'getPatternsByQuarter',
+    'getCurrentWork',
+    'getRoadmapItems',
+    'getRecentlyCompleted',
+]);
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate output modifier combinations.
+ * Throws on conflicts: --full + --names-only, --full + --count, --full + --fields.
+ */
+export function validateModifiers(modifiers) {
+    if (modifiers.full && modifiers.namesOnly) {
+        throw new QueryApiError('INVALID_ARGUMENT', 'Conflicting modifiers: --full and --names-only cannot be used together');
+    }
+    if (modifiers.full && modifiers.count) {
+        throw new QueryApiError('INVALID_ARGUMENT', 'Conflicting modifiers: --full and --count cannot be used together');
+    }
+    if (modifiers.full && modifiers.fields !== null) {
+        throw new QueryApiError('INVALID_ARGUMENT', 'Conflicting modifiers: --full and --fields cannot be used together');
+    }
+    if (modifiers.fields !== null) {
+        const validFields = SUMMARY_FIELDS;
+        const invalidFields = modifiers.fields.filter((f) => !validFields.has(f));
+        if (invalidFields.length > 0) {
+            throw new QueryApiError('INVALID_ARGUMENT', `Invalid field names: ${invalidFields.join(', ')}. Valid fields: ${[...validFields].join(', ')}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Pipeline
+// ---------------------------------------------------------------------------
+/**
+ * Apply output modifiers to pipeline input.
+ *
+ * For pattern arrays:
+ * - Default: summarize each pattern to ~100 bytes
+ * - --full: bypass summarization
+ * - --names-only: extract pattern names as string[]
+ * - --count: return array length as number
+ * - --fields: pick specific fields from each summary
+ *
+ * For scalars: pass through unchanged (modifiers do not apply).
+ */
+export function applyOutputPipeline(input, modifiers) {
+    if (input.kind === 'scalar') {
+        return input.data;
+    }
+    const patterns = input.data;
+    // Precedence: count > namesOnly > fields > default summarize
+    if (modifiers.count) {
+        return patterns.length;
+    }
+    if (modifiers.namesOnly) {
+        return patterns.map((p) => getPatternName(p));
+    }
+    if (modifiers.full) {
+        return patterns;
+    }
+    const summaries = summarizePatterns(patterns);
+    if (modifiers.fields !== null) {
+        const fieldSet = new Set(modifiers.fields);
+        return summaries.map((s) => {
+            const picked = {};
+            for (const field of fieldSet) {
+                if (field in s) {
+                    picked[field] = s[field];
+                }
+            }
+            return picked;
+        });
+    }
+    return summaries;
+}
+// ---------------------------------------------------------------------------
+// Filtering
+// ---------------------------------------------------------------------------
+/**
+ * Apply composable filters to the pattern list.
+ *
+ * Sequential filter composition: status → phase → category → source.
+ * Pagination (offset/limit) applies after all filters.
+ */
+export function applyListFilters(dataset, filters) {
+    let candidates = dataset.patterns;
+    // Filter by status
+    if (filters.status !== null) {
+        // For exact status matching (roadmap, active, completed, deferred),
+        // filter directly rather than using normalized views
+        candidates = candidates.filter((p) => p.status === filters.status);
+    }
+    // Filter by phase
+    if (filters.phase !== null) {
+        const phase = filters.phase;
+        candidates = candidates.filter((p) => p.phase === phase);
+    }
+    // Filter by category
+    if (filters.category !== null) {
+        const category = filters.category.toLowerCase();
+        candidates = candidates.filter((p) => p.category.toLowerCase() === category);
+    }
+    // Filter by source
+    if (filters.source !== null) {
+        const source = filters.source;
+        candidates = candidates.filter((p) => {
+            return deriveSource(p.source.file) === source;
+        });
+    }
+    // Filter by architecture context
+    if (filters.archContext !== null) {
+        const ctx = filters.archContext.toLowerCase();
+        candidates = candidates.filter((p) => p.archContext?.toLowerCase() === ctx);
+    }
+    // Filter by product area
+    if (filters.productArea !== null) {
+        const area = filters.productArea.toLowerCase();
+        candidates = candidates.filter((p) => p.productArea?.toLowerCase() === area);
+    }
+    // Apply pagination
+    if (filters.offset !== null) {
+        candidates = candidates.slice(filters.offset);
+    }
+    if (filters.limit !== null) {
+        candidates = candidates.slice(0, filters.limit);
+    }
+    return candidates;
+}
+// ---------------------------------------------------------------------------
+// Output formatting
+// ---------------------------------------------------------------------------
+/**
+ * Strip null, undefined, and empty values from an object for compact output.
+ *
+ * Recursively removes:
+ * - null and undefined values
+ * - empty strings
+ * - empty arrays
+ * - empty objects
+ */
+export function stripEmpty(obj) {
+    if (obj === null || obj === undefined) {
+        return undefined;
+    }
+    if (Array.isArray(obj)) {
+        if (obj.length === 0)
+            return undefined;
+        return obj.map(stripEmpty).filter((v) => v !== undefined);
+    }
+    if (typeof obj === 'object') {
+        const result = {};
+        let hasKeys = false;
+        for (const [key, value] of Object.entries(obj)) {
+            if (value === null || value === undefined)
+                continue;
+            if (typeof value === 'string' && value === '')
+                continue;
+            const stripped = stripEmpty(value);
+            if (stripped !== undefined) {
+                result[key] = stripped;
+                hasKeys = true;
+            }
+        }
+        return hasKeys ? result : undefined;
+    }
+    return obj;
+}
+/**
+ * Format a QueryResult envelope for CLI output.
+ *
+ * - json mode: pretty-printed with 2-space indent
+ * - compact mode: minified with empty values stripped
+ */
+export function formatOutput(envelope, format) {
+    if (format === 'compact') {
+        const stripped = stripEmpty(envelope);
+        return JSON.stringify(stripped);
+    }
+    return JSON.stringify(envelope, null, 2);
+}
+//# sourceMappingURL=output-pipeline.js.map