@kynetic-ai/spec 0.1.2 → 0.3.0

package/dist/cli/index.js

@@ -1,35 +1,135 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
-import chalk from 'chalk';
-import { realpathSync } from 'fs';
-import { createRequire } from 'node:module';
+import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import chalk from "chalk";
+import { Command } from "commander";
 // Read version from package.json at runtime
 // AC: @cli-version ac-2 - version automatically reflects package.json without code changes
 const require = createRequire(import.meta.url);
-const { version } = require('../../package.json');
-import { setJsonMode, setVerboseMode, getVerboseMode } from './output.js';
-import { setVerboseModeGetter } from '../parser/shadow.js';
-import { findClosestCommand, getAllCommands, COMMAND_ALIASES } from './suggest.js';
-import { registerTasksCommands, registerTaskCommands, registerSetupCommand, registerSessionCommands, registerInitCommand, registerItemCommands, registerValidateCommand, registerHelpCommand, registerDeriveCommand, registerInboxCommands, registerShadowCommands, registerLogCommand, registerSearchCommand, registerRalphCommand, registerMetaCommands, registerLinkCommands, registerModuleCommands, registerTraitCommands, registerItemTraitCommands, registerCloneForTestingCommand, } from './commands/index.js';
-import { EXIT_CODES } from './exit-codes.js';
+const { version } = require("../../package.json");
+import { setVerboseModeGetter } from "../parser/shadow.js";
+import { initContext } from "../parser/yaml.js";
+import { isBatchMode } from "./batch-context.js";
+import { registerAgentsCommands, registerBatchCommand, registerCloneForTestingCommand, registerDeriveCommand, registerDoctorCommand, registerExportCommand, registerHelpCommand, registerInboxCommands, registerInitCommand, registerItemCommands, registerItemTraitCommands, registerLinkCommands, registerLogCommand, registerMergeDriverCommand, registerMetaCommands, registerModuleCommands, registerPlanCommands, registerRalphCommand, registerRefsCommand, registerSearchCommand, registerServeCommands, registerSessionCommands, registerSetupCommand, registerShadowCommands, registerSkillCommands, registerTaskCommands, registerTasksCommands, registerTraitCommands, registerTriageCommands, registerUtilCommands, registerValidateCommand, registerWorkflowCommand, } from "./commands/index.js";
+import { EXIT_CODES } from "./exit-codes.js";
+import { getVerboseMode, setJsonMode, setVerboseMode, setYamlMode, } from "./output.js";
+import { COMMAND_ALIASES, findClosestCommand, getAllCommands, } from "./suggest.js";
+import { PidFileManager } from "./pid-utils.js";
+import { spawn } from "child_process";
+import { join } from "path";
+import { existsSync } from "fs";
 const program = new Command();
 // Initialize verbose mode getter for shadow operations
 setVerboseModeGetter(getVerboseMode);
+// Track if we've already shown the manifest daemon deprecation warning this session
+let manifestDaemonWarningShown = false;
+/**
+ * Auto-start daemon if configured and not already running
+ * AC: @daemon-server (implicit auto-start behavior)
+ * AC: @config-daemon ac-3 — uses config.daemon.auto_start
+ * AC: @config-daemon ac-4 — deprecation warning for manifest daemon block
+ */
+async function maybeAutoStartDaemon() {
+    try {
+        // Load context to get daemon config from kspec.config.yaml
+        const context = await initContext();
+        const daemonConfig = context.config.daemon;
+        // AC: @config-daemon ac-4 — emit deprecation warning if manifest has daemon block
+        if (context.manifest?.daemon && !manifestDaemonWarningShown) {
+            manifestDaemonWarningShown = true;
+            console.error(chalk.yellow('Warning: Manifest "daemon" block is deprecated.'));
+            console.error(chalk.yellow('  Migrate to kspec.config.yaml:'));
+            console.error(chalk.gray('    daemon:'));
+            console.error(chalk.gray(`      port: ${context.manifest.daemon.port ?? 3456}`));
+            console.error(chalk.gray(`      auto_start: ${context.manifest.daemon.auto_start ?? true}`));
+        }
+        // AC: @config-daemon ac-3 — auto_start from config (defaults to true)
+        if (!daemonConfig.auto_start) {
+            return;
+        }
+        // AC: @config-daemon ac-1 — port from config (defaults to 3456)
+        const port = daemonConfig.port;
+        // Check if daemon is already running
+        const kspecDir = context.specDir;
+        const pidManager = new PidFileManager(kspecDir);
+        if (pidManager.isDaemonRunning()) {
+            // Already running, nothing to do
+            return;
+        }
+        // Get path to daemon entry point - resolve relative to installed package
+        const packageRoot = join(import.meta.dirname, '../../');
+        const daemonBinary = join(packageRoot, 'dist/daemon/index.js');
+        if (!existsSync(daemonBinary)) {
+            // Daemon not available, skip silently
+            return;
+        }
+        // Start daemon in background using current runtime
+        // Set BUN_ENV=production to prevent Bun dev mode HTML transformation
+        const child = spawn(process.execPath, [daemonBinary, '--port', String(port), '--kspec-dir', kspecDir], {
+            detached: true,
+            stdio: 'ignore',
+            cwd: process.cwd(),
+            env: { ...process.env, BUN_ENV: 'production' },
+        });
+        // Detach from parent
+        child.unref();
+        // Don't wait for daemon to start - let it happen in background
+    }
+    catch {
+        // Errors during auto-start are non-fatal - continue with command
+    }
+}
 program
-    .name('kspec')
-    .description('Kynetic Spec - Structured specification format CLI')
+    .name("kspec")
+    .description("Kynetic Spec - Structured specification format CLI")
     .version(version)
-    .option('--json', 'Output in JSON format')
-    .option('--debug-shadow', 'Enable debug output for shadow operations')
-    .hook('preAction', (thisCommand) => {
-    // Check for --json and --debug-shadow flags at top level or on subcommand
+    // AC: @output-format-option ac-format-json, ac-format-yaml, ac-global-scope
+    // Note: We use shorthands --json, --yaml, --raw as global options
+    // --format is NOT global because it conflicts with command-specific --format options (e.g., export)
+    // Commands can still use --format locally; the global behavior uses shorthands only
+    .option("--json", "Output in JSON format")
+    .option("--yaml", "Output in YAML format")
+    .option("--raw", "Output in raw JSON format (same as --json)")
+    .option("--debug-shadow", "Enable debug output for shadow operations")
+    .hook("preAction", async (thisCommand, actionCommand) => {
+    // Skip all hooks during batch dispatch — the batch handler manages modes itself
+    if (isBatchMode())
+        return;
+    // The actionCommand is the actual command being executed (e.g., 'export')
+    const executingCommandName = actionCommand.name();
+    // Check format options at top level
     const opts = thisCommand.opts();
-    if (opts.json) {
+    // AC: @output-format-option ac-conflict-error
+    // Detect conflicting format shorthand specifications
+    const formatFlags = [];
+    if (opts.json)
+        formatFlags.push("--json");
+    if (opts.yaml)
+        formatFlags.push("--yaml");
+    if (opts.raw)
+        formatFlags.push("--raw");
+    if (formatFlags.length > 1) {
+        console.error(chalk.red(`error: Conflicting format options: ${formatFlags.join(", ")}`));
+        console.error(chalk.gray("Use only one of: --json, --yaml, --raw"));
+        process.exit(EXIT_CODES.ERROR);
+    }
+    // AC: @output-format-option ac-json-shorthand, ac-raw-shorthand, ac-yaml-shorthand
+    // Set output format based on shorthand flags
+    if (opts.json || opts.raw) {
         setJsonMode(true);
     }
+    else if (opts.yaml) {
+        setYamlMode(true);
+    }
     if (opts.debugShadow) {
         setVerboseMode(true);
     }
+    // Auto-start daemon if configured and not running
+    // Skip for init, serve, and help commands
+    const skipCommands = ['init', 'serve', 'help', 'kspec'];
+    if (!skipCommands.includes(executingCommandName)) {
+        await maybeAutoStartDaemon();
+    }
 });
 // Register command groups
 registerTasksCommands(program);
@@ -39,25 +139,37 @@ registerSessionCommands(program);
 registerInitCommand(program);
 // Register item commands first, then add trait subcommands to it
 registerItemCommands(program);
-const itemCmd = program.commands.find(cmd => cmd.name() === 'item');
+const itemCmd = program.commands.find((cmd) => cmd.name() === "item");
 if (itemCmd) {
     registerItemTraitCommands(itemCmd);
 }
 registerTraitCommands(program);
 registerValidateCommand(program);
 registerHelpCommand(program);
+registerDoctorCommand(program);
 registerDeriveCommand(program);
 registerInboxCommands(program);
+registerTriageCommands(program);
 registerShadowCommands(program);
 registerLogCommand(program);
 registerSearchCommand(program);
+registerRefsCommand(program);
+registerServeCommands(program);
 registerRalphCommand(program);
 registerMetaCommands(program);
 registerLinkCommands(program);
 registerModuleCommands(program);
+registerPlanCommands(program);
 registerCloneForTestingCommand(program);
+registerWorkflowCommand(program);
+registerMergeDriverCommand(program);
+registerExportCommand(program);
+registerUtilCommands(program);
+registerBatchCommand(program);
+registerSkillCommands(program);
+registerAgentsCommands(program);
 // Handle unknown commands with suggestions
-program.on('command:*', (operands) => {
+program.on("command:*", (operands) => {
     const unknownCommand = operands[0];
     // Check for direct alias match
     if (COMMAND_ALIASES[unknownCommand]) {

package/dist/cli/index.js.map

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

package/dist/cli/introspection.d.ts

@@ -4,7 +4,7 @@
  * This module provides the foundation for auto-generated CLI documentation
  * by extracting command metadata directly from Commander.js definitions.
  */
-import { Command } from 'commander';
+import type { Command } from "commander";
 /**
  * Metadata for a single command option
  */
@@ -13,8 +13,10 @@ export interface OptionMeta {
     flags: string;
     /** Option description */
     description: string;
-    /** Whether option is required */
+    /** Whether the option's value is required when used (i.e. <value> not [value]) */
     required: boolean;
+    /** Whether the option itself must be provided (i.e. requiredOption) */
+    mandatory: boolean;
     /** Default value if any */
     defaultValue?: unknown;
     /** Whether option can be repeated */
@@ -53,6 +55,8 @@ export interface CommandMeta {
     subcommands: CommandMeta[];
     /** Whether this command is hidden */
     hidden: boolean;
+    /** Whether this command mutates kspec state (annotated via markMutating) */
+    mutating: boolean;
 }
 /**
  * Extract complete command tree from a Commander program

package/dist/cli/introspection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../../src/cli/introspection.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAA6B,MAAM,WAAW,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,QAAQ,EAAE,OAAO,CAAC;IAClB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qCAAqC;IACrC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wBAAwB;IACxB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,sBAAsB;IACtB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,kBAAkB;IAClB,WAAW,EAAE,WAAW,EAAE,CAAC;IAC3B,qCAAqC;IACrC,MAAM,EAAE,OAAO,CAAC;CACjB;AA6BD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,UAAU,GAAE,MAAM,EAAO,GACxB,WAAW,CA6Bb;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,GAAG,IAAI,CAuBjF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,EAAE,CAQnE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAkB/D"}
+{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../../src/cli/introspection.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAA6B,MAAM,WAAW,CAAC;AAGpE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,QAAQ,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,SAAS,EAAE,OAAO,CAAC;IACnB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qCAAqC;IACrC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wBAAwB;IACxB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,sBAAsB;IACtB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,kBAAkB;IAClB,WAAW,EAAE,WAAW,EAAE,CAAC;IAC3B,qCAAqC;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,CAAC;CACnB;AA8BD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,UAAU,GAAE,MAAM,EAAO,GACxB,WAAW,CA8Bb;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,MAAM,EAAE,GACb,WAAW,GAAG,IAAI,CAuBpB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,EAAE,CAQnE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAkB/D"}

package/dist/cli/introspection.js

@@ -5,14 +5,16 @@
  * This module provides the foundation for auto-generated CLI documentation
  * by extracting command metadata directly from Commander.js definitions.
  */
+import { getAnnotation } from "./command-annotations.js";
 /**
  * Extract metadata for a single option
  */
 function extractOptionMeta(option) {
     return {
         flags: option.flags,
-        description: option.description || '',
+        description: option.description || "",
         required: option.required,
+        mandatory: option.mandatory ?? false,
         defaultValue: option.defaultValue,
         variadic: option.variadic,
     };
@@ -25,7 +27,7 @@ function extractArgumentsMeta(command) {
     const args = command.registeredArguments || [];
     return args.map((arg) => ({
         name: arg.name(),
-        description: arg.description || '',
+        description: arg.description || "",
         required: arg.required,
         variadic: arg.variadic,
     }));
@@ -54,12 +56,13 @@ export function extractCommandTree(command, parentPath = []) {
     return {
         name: commandName,
         fullPath,
-        description: command.description() || '',
+        description: command.description() || "",
         aliases: command.aliases(),
         arguments: args,
         options,
         subcommands,
         hidden: isHidden(command),
+        mutating: getAnnotation(command)?.mutating ?? false,
     };
 }
 /**
@@ -108,20 +111,20 @@ export function flattenCommandTree(tree) {
  * @returns Usage string (e.g., "kspec task add [options]")
  */
 export function formatCommandUsage(command) {
-    const parts = ['kspec', ...command.fullPath.slice(1)]; // Skip root 'kspec'
+    const parts = ["kspec", ...command.fullPath.slice(1)]; // Skip root 'kspec'
     // Add arguments
     for (const arg of command.arguments) {
         if (arg.required) {
-            parts.push(`<${arg.name}${arg.variadic ? '...' : ''}>`);
+            parts.push(`<${arg.name}${arg.variadic ? "..." : ""}>`);
         }
         else {
-            parts.push(`[${arg.name}${arg.variadic ? '...' : ''}]`);
+            parts.push(`[${arg.name}${arg.variadic ? "..." : ""}]`);
         }
     }
     // Add [options] if command has options
     if (command.options.length > 0) {
-        parts.push('[options]');
+        parts.push("[options]");
     }
-    return parts.join(' ');
+    return parts.join(" ");
 }
 //# sourceMappingURL=introspection.js.map

package/dist/cli/introspection.js.map

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

package/dist/cli/output.d.ts

@@ -1,33 +1,89 @@
-import type { Task } from '../schema/index.js';
-import type { ReferenceIndex } from '../parser/index.js';
+import type { ReferenceIndex } from "../parser/index.js";
+import type { Note, Task } from "../schema/index.js";
+/**
+ * Check if a note has been superseded by another note.
+ * A note is superseded if its ULID appears in any other note's `supersedes` field.
+ */
+export declare function isNoteSuperseded(note: Note, allNotes: Note[]): boolean;
+/**
+ * Filter notes to exclude superseded ones.
+ * Returns only notes that have not been superseded.
+ */
+export declare function filterSupersededNotes(notes: Note[]): Note[];
+/**
+ * Annotate notes with superseded status for JSON output.
+ * Adds a computed `superseded` field to each note.
+ */
+export declare function annotateNotesWithSuperseded(notes: Note[]): Array<Note & {
+    superseded: boolean;
+}>;
 /**
  * Output options
  */
 export interface OutputOptions {
     json?: boolean;
 }
+/**
+ * Output format types
+ * AC: @output-format-option
+ */
+export type OutputFormat = "text" | "json" | "yaml";
+/**
+ * Valid format values for --format option
+ */
+export declare const VALID_FORMATS: readonly ["json", "yaml"];
+export declare function setOutputFormat(format: OutputFormat): void;
+export declare function getOutputFormat(): OutputFormat;
+/**
+ * Set JSON mode (for backward compatibility)
+ * AC: @output-format-option ac-json-shorthand
+ */
 export declare function setJsonMode(enabled: boolean): void;
+/**
+ * Check if JSON mode is active
+ * AC: @output-format-option ac-json-shorthand
+ */
 export declare function isJsonMode(): boolean;
+/**
+ * Set YAML mode
+ * AC: @output-format-option ac-format-yaml, ac-yaml-shorthand
+ */
+export declare function setYamlMode(enabled: boolean): void;
+/**
+ * Check if YAML mode is active
+ * AC: @output-format-option ac-format-yaml
+ */
+export declare function isYamlMode(): boolean;
+/**
+ * Check if any structured output mode is active (JSON or YAML)
+ * AC: @output-format-option ac-yaml-no-ansi, ac-yaml-references
+ */
+export declare function isStructuredMode(): boolean;
 export declare function setVerboseMode(enabled: boolean): void;
 export declare function getVerboseMode(): boolean;
 /**
- * Output data - JSON if --json flag, otherwise formatted
+ * Output data - JSON/YAML if structured mode, otherwise formatted
+ * AC: @output-format-option ac-format-json, ac-format-yaml
  */
 export declare function output(data: unknown, formatter?: () => void): void;
 /**
  * Output success message
+ * AC: @output-format-option ac-format-json, ac-format-yaml
  */
 export declare function success(message: string, data?: Record<string, unknown>): void;
 /**
  * Output error message
+ * AC: @output-format-option ac-format-json, ac-format-yaml
  */
 export declare function error(message: string, details?: unknown): void;
 /**
  * Output warning message
+ * AC: @output-format-option ac-yaml-no-ansi
  */
 export declare function warn(message: string): void;
 /**
  * Output info message
+ * AC: @output-format-option ac-yaml-no-ansi
  */
 export declare function info(message: string): void;
 /**
@@ -49,8 +105,12 @@ export declare function formatTaskListWithAutomation(tasks: Task[], verbose?: bo
  * Format a list of tasks
  */
 export declare function formatTaskList(tasks: Task[], verbose?: boolean, index?: ReferenceIndex, grepPattern?: string, full?: boolean): void;
+export interface FormatTaskDetailsOptions {
+    /** Show all notes including superseded ones (default: false) */
+    showAllNotes?: boolean;
+}
 /**
  * Format task details
  */
-export declare function formatTaskDetails(task: Task, index?: ReferenceIndex): void;
+export declare function formatTaskDetails(task: Task, index?: ReferenceIndex, options?: FormatTaskDetailsOptions): void;
 //# sourceMappingURL=output.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIzD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAOD,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAElD;AAED,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAOD,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAErD;AAED,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CAQlE;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAM7E;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAgB9D;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAM1C;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAM1C;AAsBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,MAAM,CAMxE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,UAAQ,EAAE,KAAK,CAAC,EAAE,cAAc,EAAE,IAAI,UAAQ,GAAG,MAAM,CAqBpG;AAqGD;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,UAAQ,EAAE,KAAK,CAAC,EAAE,cAAc,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,IAAI,UAAQ,GAAG,IAAI,CA8C7I;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,UAAQ,EAAE,KAAK,CAAC,EAAE,cAAc,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,IAAI,UAAQ,GAAG,IAAI,CA4B/H;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,IAAI,CA4J1E"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"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"}