@defai.digital/contracts 13.0.3

package/dist/cli/v1/output.d.ts

@@ -0,0 +1,347 @@
+/**
+ * CLI Output Protocol Contracts v1
+ *
+ * Contract schemas for CLI output parsing and error classification.
+ * These contracts define the expected formats from CLI provider outputs
+ * and enable consumer-driven contract testing.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/**
+ * Supported CLI output formats
+ *
+ * - json: Single JSON object response
+ * - stream-json: JSON Lines format (one JSON object per line)
+ * - text: Plain text output
+ */
+export declare const CLIOutputFormatSchema: z.ZodEnum<["json", "stream-json", "text"]>;
+export type CLIOutputFormat = z.infer<typeof CLIOutputFormatSchema>;
+/**
+ * Token usage information
+ */
+export declare const TokenUsageSchema: z.ZodObject<{
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    totalTokens: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    totalTokens: number;
+    outputTokens: number;
+    inputTokens: number;
+}, {
+    totalTokens: number;
+    outputTokens: number;
+    inputTokens: number;
+}>;
+export type TokenUsage = z.infer<typeof TokenUsageSchema>;
+/**
+ * Result of parsing CLI output
+ */
+export declare const ParsedCLIOutputSchema: z.ZodObject<{
+    /** Extracted content from the CLI response */
+    content: z.ZodString;
+    /** Raw metadata from the response (provider-specific) */
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Token usage if available */
+    tokenUsage: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        totalTokens: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        totalTokens: number;
+        outputTokens: number;
+        inputTokens: number;
+    }, {
+        totalTokens: number;
+        outputTokens: number;
+        inputTokens: number;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    metadata?: Record<string, unknown> | undefined;
+    tokenUsage?: {
+        totalTokens: number;
+        outputTokens: number;
+        inputTokens: number;
+    } | undefined;
+}, {
+    content: string;
+    metadata?: Record<string, unknown> | undefined;
+    tokenUsage?: {
+        totalTokens: number;
+        outputTokens: number;
+        inputTokens: number;
+    } | undefined;
+}>;
+export type ParsedCLIOutput = z.infer<typeof ParsedCLIOutputSchema>;
+/**
+ * Error categories for CLI outputs
+ *
+ * Each category has specific retry/fallback guidance:
+ * - authentication: Don't retry, don't fallback (fix credentials)
+ * - quota: Don't retry, fallback to different provider
+ * - rate_limit: Retry with backoff, don't fallback
+ * - validation: Don't retry, don't fallback (fix request)
+ * - network: Retry, then fallback
+ * - server: Retry, then fallback
+ * - timeout: Retry, then fallback
+ * - not_found: Don't retry, fallback
+ * - configuration: Don't retry, don't fallback (fix config)
+ * - unknown: Don't retry, fallback
+ */
+export declare const CLIErrorCategorySchema: z.ZodEnum<["authentication", "quota", "rate_limit", "validation", "network", "server", "timeout", "not_found", "configuration", "unknown"]>;
+export type CLIErrorCategory = z.infer<typeof CLIErrorCategorySchema>;
+/**
+ * Retry guidance for each error category
+ */
+export declare const ERROR_CATEGORY_GUIDANCE: Record<CLIErrorCategory, {
+    shouldRetry: boolean;
+    shouldFallback: boolean;
+}>;
+/**
+ * Classified error with retry/fallback guidance
+ */
+export declare const ClassifiedCLIErrorSchema: z.ZodObject<{
+    /** Error category */
+    category: z.ZodEnum<["authentication", "quota", "rate_limit", "validation", "network", "server", "timeout", "not_found", "configuration", "unknown"]>;
+    /** Human-readable error message */
+    message: z.ZodString;
+    /** Whether to retry the request */
+    shouldRetry: z.ZodBoolean;
+    /** Whether to fallback to another provider */
+    shouldFallback: z.ZodBoolean;
+    /** Suggested retry delay in milliseconds */
+    retryAfterMs: z.ZodNullable<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    category: "validation" | "unknown" | "timeout" | "rate_limit" | "authentication" | "quota" | "network" | "server" | "not_found" | "configuration";
+    retryAfterMs: number | null;
+    shouldRetry: boolean;
+    shouldFallback: boolean;
+}, {
+    message: string;
+    category: "validation" | "unknown" | "timeout" | "rate_limit" | "authentication" | "quota" | "network" | "server" | "not_found" | "configuration";
+    retryAfterMs: number | null;
+    shouldRetry: boolean;
+    shouldFallback: boolean;
+}>;
+export type ClassifiedCLIError = z.infer<typeof ClassifiedCLIErrorSchema>;
+/**
+ * Raw CLI output structure for test fixtures
+ */
+export declare const RawCLIOutputSchema: z.ZodObject<{
+    /** stdout from the CLI process */
+    stdout: z.ZodString;
+    /** stderr from the CLI process */
+    stderr: z.ZodDefault<z.ZodString>;
+    /** Exit code from the CLI process */
+    exitCode: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}, {
+    stdout: string;
+    stderr?: string | undefined;
+    exitCode?: number | undefined;
+}>;
+export type RawCLIOutput = z.infer<typeof RawCLIOutputSchema>;
+/**
+ * Expected parsing result for test fixtures
+ */
+export declare const ExpectedParseResultSchema: z.ZodObject<{
+    /** Expected extracted content */
+    content: z.ZodString;
+    /** Whether this output represents an error */
+    isError: z.ZodDefault<z.ZodBoolean>;
+    /** Expected error category if isError is true */
+    errorCategory: z.ZodOptional<z.ZodEnum<["authentication", "quota", "rate_limit", "validation", "network", "server", "timeout", "not_found", "configuration", "unknown"]>>;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    isError: boolean;
+    errorCategory?: "validation" | "unknown" | "timeout" | "rate_limit" | "authentication" | "quota" | "network" | "server" | "not_found" | "configuration" | undefined;
+}, {
+    content: string;
+    isError?: boolean | undefined;
+    errorCategory?: "validation" | "unknown" | "timeout" | "rate_limit" | "authentication" | "quota" | "network" | "server" | "not_found" | "configuration" | undefined;
+}>;
+export type ExpectedParseResult = z.infer<typeof ExpectedParseResultSchema>;
+/**
+ * CLI output fixture for consumer-driven contract testing
+ *
+ * Each fixture represents a real or realistic CLI output from a provider,
+ * along with the expected parsing result. Tests validate that the
+ * output parser correctly extracts content and classifies errors.
+ */
+export declare const CLIOutputFixtureSchema: z.ZodObject<{
+    /** Provider ID (claude, gemini, codex, qwen, glm, grok) */
+    provider: z.ZodString;
+    /** Scenario description */
+    scenario: z.ZodString;
+    /** Output format expected from this provider */
+    outputFormat: z.ZodEnum<["json", "stream-json", "text"]>;
+    /** When the fixture was captured (ISO 8601 datetime) */
+    capturedAt: z.ZodOptional<z.ZodString>;
+    /** Version of the CLI that produced this output */
+    cliVersion: z.ZodOptional<z.ZodString>;
+    /** Raw CLI output */
+    rawOutput: z.ZodObject<{
+        /** stdout from the CLI process */
+        stdout: z.ZodString;
+        /** stderr from the CLI process */
+        stderr: z.ZodDefault<z.ZodString>;
+        /** Exit code from the CLI process */
+        exitCode: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }, {
+        stdout: string;
+        stderr?: string | undefined;
+        exitCode?: number | undefined;
+    }>;
+    /** Expected parsing result */
+    expected: z.ZodObject<{
+        /** Expected extracted content */
+        content: z.ZodString;
+        /** Whether this output represents an error */
+        isError: z.ZodDefault<z.ZodBoolean>;
+        /** Expected error category if isError is true */
+        errorCategory: z.ZodOptional<z.ZodEnum<["authentication", "quota", "rate_limit", "validation", "network", "server", "timeout", "not_found", "configuration", "unknown"]>>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        isError: boolean;
+        errorCategory?: "validation" | "unknown" | "timeout" | "rate_limit" | "authentication" | "quota" | "network" | "server" | "not_found" | "configuration" | undefined;
+    }, {
+        content: string;
+        isError?: boolean | undefined;
+        errorCategory?: "validation" | "unknown" | "timeout" | "rate_limit" | "authentication" | "quota" | "network" | "server" | "not_found" | "configuration" | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    expected: {
+        content: string;
+        isError: boolean;
+        errorCategory?: "validation" | "unknown" | "timeout" | "rate_limit" | "authentication" | "quota" | "network" | "server" | "not_found" | "configuration" | undefined;
+    };
+    provider: string;
+    outputFormat: "text" | "json" | "stream-json";
+    scenario: string;
+    rawOutput: {
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    };
+    capturedAt?: string | undefined;
+    cliVersion?: string | undefined;
+}, {
+    expected: {
+        content: string;
+        isError?: boolean | undefined;
+        errorCategory?: "validation" | "unknown" | "timeout" | "rate_limit" | "authentication" | "quota" | "network" | "server" | "not_found" | "configuration" | undefined;
+    };
+    provider: string;
+    outputFormat: "text" | "json" | "stream-json";
+    scenario: string;
+    rawOutput: {
+        stdout: string;
+        stderr?: string | undefined;
+        exitCode?: number | undefined;
+    };
+    capturedAt?: string | undefined;
+    cliVersion?: string | undefined;
+}>;
+export type CLIOutputFixture = z.infer<typeof CLIOutputFixtureSchema>;
+/**
+ * Documented provider output formats
+ *
+ * This constant documents the expected output structures from each provider.
+ * Used for reference when creating test fixtures and validating parsers.
+ */
+export declare const PROVIDER_OUTPUT_FORMATS: {
+    readonly claude: {
+        readonly format: "stream-json";
+        readonly description: "JSON Lines with turn events";
+        readonly contentExtraction: "content field in content events";
+        readonly examples: readonly ["{\"type\":\"turn.started\",...}", "{\"type\":\"content\",\"content\":\"Hello\"}", "{\"type\":\"turn.completed\",\"usage\":{...}}"];
+    };
+    readonly gemini: {
+        readonly format: "stream-json";
+        readonly description: "JSON Lines with content events";
+        readonly contentExtraction: "content field in response objects";
+        readonly examples: readonly ["{\"candidates\":[{\"content\":{\"parts\":[{\"text\":\"Hello\"}]}}]}"];
+    };
+    readonly codex: {
+        readonly format: "stream-json";
+        readonly description: "JSON Lines with item.completed events";
+        readonly contentExtraction: "item.text or item.agent_message.text in item.completed events";
+        readonly examples: readonly ["{\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",\"text\":\"Hello\"}}"];
+    };
+    readonly qwen: {
+        readonly format: "text";
+        readonly description: "Plain text output";
+        readonly contentExtraction: "Raw stdout";
+        readonly examples: readonly ["Hello, how can I help you today?"];
+    };
+    readonly glm: {
+        readonly format: "stream-json";
+        readonly description: "JSON Lines with role:assistant messages";
+        readonly contentExtraction: "content field from assistant role messages";
+        readonly examples: readonly ["{\"role\":\"assistant\",\"content\":\"Hello\"}"];
+    };
+    readonly grok: {
+        readonly format: "stream-json";
+        readonly description: "JSON Lines with role:assistant messages";
+        readonly contentExtraction: "content field from assistant role messages";
+        readonly examples: readonly ["{\"role\":\"assistant\",\"content\":\"Hello\"}"];
+    };
+};
+export declare const CLIOutputErrorCodes: {
+    /** Output could not be parsed */
+    readonly PARSE_ERROR: "CLI_OUTPUT_PARSE_ERROR";
+    /** Unknown output format */
+    readonly UNKNOWN_FORMAT: "CLI_OUTPUT_UNKNOWN_FORMAT";
+    /** Empty output received */
+    readonly EMPTY_OUTPUT: "CLI_OUTPUT_EMPTY";
+    /** Fixture validation failed */
+    readonly INVALID_FIXTURE: "CLI_OUTPUT_INVALID_FIXTURE";
+};
+export type CLIOutputErrorCode = (typeof CLIOutputErrorCodes)[keyof typeof CLIOutputErrorCodes];
+/**
+ * Validates a CLI output fixture
+ */
+export declare function validateCLIOutputFixture(data: unknown): CLIOutputFixture;
+/**
+ * Safely validates a CLI output fixture
+ */
+export declare function safeValidateCLIOutputFixture(data: unknown): {
+    success: true;
+    data: CLIOutputFixture;
+} | {
+    success: false;
+    error: z.ZodError;
+};
+/**
+ * Validates a classified CLI error
+ */
+export declare function validateClassifiedCLIError(data: unknown): ClassifiedCLIError;
+/**
+ * Validates parsed CLI output
+ */
+export declare function validateParsedCLIOutput(data: unknown): ParsedCLIOutput;
+/**
+ * Creates a CLI output fixture
+ */
+export declare function createCLIOutputFixture(provider: string, scenario: string, outputFormat: CLIOutputFormat, rawOutput: RawCLIOutput, expected: ExpectedParseResult): CLIOutputFixture;
+/**
+ * Creates a classified CLI error
+ */
+export declare function createClassifiedCLIError(category: CLIErrorCategory, message: string, retryAfterMs?: number | null): ClassifiedCLIError;
+/**
+ * Gets retry guidance for an error category
+ */
+export declare function getErrorCategoryGuidance(category: CLIErrorCategory): {
+    shouldRetry: boolean;
+    shouldFallback: boolean;
+};
+//# sourceMappingURL=output.d.ts.map

package/dist/cli/v1/output.d.ts.map

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

package/dist/cli/v1/output.js

@@ -0,0 +1,288 @@
+/**
+ * CLI Output Protocol Contracts v1
+ *
+ * Contract schemas for CLI output parsing and error classification.
+ * These contracts define the expected formats from CLI provider outputs
+ * and enable consumer-driven contract testing.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+// ============================================================================
+// Output Format Types
+// ============================================================================
+/**
+ * Supported CLI output formats
+ *
+ * - json: Single JSON object response
+ * - stream-json: JSON Lines format (one JSON object per line)
+ * - text: Plain text output
+ */
+export const CLIOutputFormatSchema = z.enum(['json', 'stream-json', 'text']);
+// ============================================================================
+// Token Usage
+// ============================================================================
+/**
+ * Token usage information
+ */
+export const TokenUsageSchema = z.object({
+    inputTokens: z.number().int().nonnegative(),
+    outputTokens: z.number().int().nonnegative(),
+    totalTokens: z.number().int().nonnegative(),
+});
+// ============================================================================
+// Parsed Output
+// ============================================================================
+/**
+ * Result of parsing CLI output
+ */
+export const ParsedCLIOutputSchema = z.object({
+    /** Extracted content from the CLI response */
+    content: z.string(),
+    /** Raw metadata from the response (provider-specific) */
+    metadata: z.record(z.unknown()).optional(),
+    /** Token usage if available */
+    tokenUsage: TokenUsageSchema.optional(),
+});
+// ============================================================================
+// Error Categories
+// ============================================================================
+/**
+ * Error categories for CLI outputs
+ *
+ * Each category has specific retry/fallback guidance:
+ * - authentication: Don't retry, don't fallback (fix credentials)
+ * - quota: Don't retry, fallback to different provider
+ * - rate_limit: Retry with backoff, don't fallback
+ * - validation: Don't retry, don't fallback (fix request)
+ * - network: Retry, then fallback
+ * - server: Retry, then fallback
+ * - timeout: Retry, then fallback
+ * - not_found: Don't retry, fallback
+ * - configuration: Don't retry, don't fallback (fix config)
+ * - unknown: Don't retry, fallback
+ */
+export const CLIErrorCategorySchema = z.enum([
+    'authentication',
+    'quota',
+    'rate_limit',
+    'validation',
+    'network',
+    'server',
+    'timeout',
+    'not_found',
+    'configuration',
+    'unknown',
+]);
+/**
+ * Retry guidance for each error category
+ */
+export const ERROR_CATEGORY_GUIDANCE = {
+    authentication: { shouldRetry: false, shouldFallback: false },
+    quota: { shouldRetry: false, shouldFallback: true },
+    rate_limit: { shouldRetry: true, shouldFallback: false },
+    validation: { shouldRetry: false, shouldFallback: false },
+    network: { shouldRetry: true, shouldFallback: true },
+    server: { shouldRetry: true, shouldFallback: true },
+    timeout: { shouldRetry: true, shouldFallback: true },
+    not_found: { shouldRetry: false, shouldFallback: true },
+    configuration: { shouldRetry: false, shouldFallback: false },
+    unknown: { shouldRetry: false, shouldFallback: true },
+};
+// ============================================================================
+// Classified Error
+// ============================================================================
+/**
+ * Classified error with retry/fallback guidance
+ */
+export const ClassifiedCLIErrorSchema = z.object({
+    /** Error category */
+    category: CLIErrorCategorySchema,
+    /** Human-readable error message */
+    message: z.string(),
+    /** Whether to retry the request */
+    shouldRetry: z.boolean(),
+    /** Whether to fallback to another provider */
+    shouldFallback: z.boolean(),
+    /** Suggested retry delay in milliseconds */
+    retryAfterMs: z.number().nullable(),
+});
+// ============================================================================
+// Test Fixtures (Consumer-Driven Contract Testing)
+// ============================================================================
+/**
+ * Raw CLI output structure for test fixtures
+ */
+export const RawCLIOutputSchema = z.object({
+    /** stdout from the CLI process */
+    stdout: z.string(),
+    /** stderr from the CLI process */
+    stderr: z.string().default(''),
+    /** Exit code from the CLI process */
+    exitCode: z.number().int().default(0),
+});
+/**
+ * Expected parsing result for test fixtures
+ */
+export const ExpectedParseResultSchema = z.object({
+    /** Expected extracted content */
+    content: z.string(),
+    /** Whether this output represents an error */
+    isError: z.boolean().default(false),
+    /** Expected error category if isError is true */
+    errorCategory: CLIErrorCategorySchema.optional(),
+});
+/**
+ * CLI output fixture for consumer-driven contract testing
+ *
+ * Each fixture represents a real or realistic CLI output from a provider,
+ * along with the expected parsing result. Tests validate that the
+ * output parser correctly extracts content and classifies errors.
+ */
+export const CLIOutputFixtureSchema = z.object({
+    /** Provider ID (claude, gemini, codex, qwen, glm, grok) */
+    provider: z.string(),
+    /** Scenario description */
+    scenario: z.string(),
+    /** Output format expected from this provider */
+    outputFormat: CLIOutputFormatSchema,
+    /** When the fixture was captured (ISO 8601 datetime) */
+    capturedAt: z.string().datetime().optional(),
+    /** Version of the CLI that produced this output */
+    cliVersion: z.string().optional(),
+    /** Raw CLI output */
+    rawOutput: RawCLIOutputSchema,
+    /** Expected parsing result */
+    expected: ExpectedParseResultSchema,
+});
+// ============================================================================
+// Provider Output Formats Documentation
+// ============================================================================
+/**
+ * Documented provider output formats
+ *
+ * This constant documents the expected output structures from each provider.
+ * Used for reference when creating test fixtures and validating parsers.
+ */
+export const PROVIDER_OUTPUT_FORMATS = {
+    claude: {
+        format: 'stream-json',
+        description: 'JSON Lines with turn events',
+        contentExtraction: 'content field in content events',
+        examples: [
+            '{"type":"turn.started",...}',
+            '{"type":"content","content":"Hello"}',
+            '{"type":"turn.completed","usage":{...}}',
+        ],
+    },
+    gemini: {
+        format: 'stream-json',
+        description: 'JSON Lines with content events',
+        contentExtraction: 'content field in response objects',
+        examples: ['{"candidates":[{"content":{"parts":[{"text":"Hello"}]}}]}'],
+    },
+    codex: {
+        format: 'stream-json',
+        description: 'JSON Lines with item.completed events',
+        contentExtraction: 'item.text or item.agent_message.text in item.completed events',
+        examples: ['{"type":"item.completed","item":{"type":"agent_message","text":"Hello"}}'],
+    },
+    qwen: {
+        format: 'text',
+        description: 'Plain text output',
+        contentExtraction: 'Raw stdout',
+        examples: ['Hello, how can I help you today?'],
+    },
+    glm: {
+        format: 'stream-json',
+        description: 'JSON Lines with role:assistant messages',
+        contentExtraction: 'content field from assistant role messages',
+        examples: ['{"role":"assistant","content":"Hello"}'],
+    },
+    grok: {
+        format: 'stream-json',
+        description: 'JSON Lines with role:assistant messages',
+        contentExtraction: 'content field from assistant role messages',
+        examples: ['{"role":"assistant","content":"Hello"}'],
+    },
+};
+// ============================================================================
+// Error Codes
+// ============================================================================
+export const CLIOutputErrorCodes = {
+    /** Output could not be parsed */
+    PARSE_ERROR: 'CLI_OUTPUT_PARSE_ERROR',
+    /** Unknown output format */
+    UNKNOWN_FORMAT: 'CLI_OUTPUT_UNKNOWN_FORMAT',
+    /** Empty output received */
+    EMPTY_OUTPUT: 'CLI_OUTPUT_EMPTY',
+    /** Fixture validation failed */
+    INVALID_FIXTURE: 'CLI_OUTPUT_INVALID_FIXTURE',
+};
+// ============================================================================
+// Validation Functions
+// ============================================================================
+/**
+ * Validates a CLI output fixture
+ */
+export function validateCLIOutputFixture(data) {
+    return CLIOutputFixtureSchema.parse(data);
+}
+/**
+ * Safely validates a CLI output fixture
+ */
+export function safeValidateCLIOutputFixture(data) {
+    const result = CLIOutputFixtureSchema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return { success: false, error: result.error };
+}
+/**
+ * Validates a classified CLI error
+ */
+export function validateClassifiedCLIError(data) {
+    return ClassifiedCLIErrorSchema.parse(data);
+}
+/**
+ * Validates parsed CLI output
+ */
+export function validateParsedCLIOutput(data) {
+    return ParsedCLIOutputSchema.parse(data);
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Creates a CLI output fixture
+ */
+export function createCLIOutputFixture(provider, scenario, outputFormat, rawOutput, expected) {
+    return CLIOutputFixtureSchema.parse({
+        provider,
+        scenario,
+        outputFormat,
+        rawOutput,
+        expected,
+        capturedAt: new Date().toISOString(),
+    });
+}
+/**
+ * Creates a classified CLI error
+ */
+export function createClassifiedCLIError(category, message, retryAfterMs = null) {
+    const guidance = ERROR_CATEGORY_GUIDANCE[category];
+    return {
+        category,
+        message,
+        shouldRetry: guidance.shouldRetry,
+        shouldFallback: guidance.shouldFallback,
+        retryAfterMs,
+    };
+}
+/**
+ * Gets retry guidance for an error category
+ */
+export function getErrorCategoryGuidance(category) {
+    return ERROR_CATEGORY_GUIDANCE[category];
+}
+//# sourceMappingURL=output.js.map

package/dist/cli/v1/output.js.map

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