@specforge/cli 0.1.0

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/cli/ui/output.ts"],"sourcesContent":["/**\n * Output Formatting Utilities\n *\n * Provides consistent output formatting for tables, lists, and structured data.\n */\n\nimport { colors, style, icons } from './colors.js';\n\n/**\n * Print a labeled value\n *\n * @example\n * printField('Project', 'my-project');\n * // Output: Project: my-project\n */\nexport function printField(label: string, value: string | null | undefined): void {\n  const displayValue = value ?? colors.muted('(not set)');\n  console.log(`${style.label(label)}: ${displayValue}`);\n}\n\n/**\n * Print a section header\n *\n * @example\n * printHeader('Configuration');\n * // Output:\n * // Configuration\n * // ─────────────\n */\nexport function printHeader(title: string): void {\n  console.log();\n  console.log(style.label(title));\n  console.log(colors.muted('─'.repeat(title.length)));\n}\n\n/**\n * Print a blank line\n */\nexport function printBlank(): void {\n  console.log();\n}\n\n/**\n * Print a list of items\n *\n * @example\n * printList(['Item 1', 'Item 2', 'Item 3']);\n * // Output:\n * // • Item 1\n * // • Item 2\n * // • Item 3\n */\nexport function printList(items: string[], bullet: string = icons.bullet): void {\n  for (const item of items) {\n    console.log(`  ${bullet} ${item}`);\n  }\n}\n\n/**\n * Print a success message\n *\n * @example\n * printSuccess('Configuration saved');\n * // Output: ✓ Configuration saved\n */\nexport function printSuccess(message: string): void {\n  console.log(`${icons.success} ${message}`);\n}\n\n/**\n * Print an error message\n *\n * @example\n * printError('Failed to connect');\n * // Output: ✗ Failed to connect\n */\nexport function printError(message: string): void {\n  console.error(`${icons.error} ${style.err(message)}`);\n}\n\n/**\n * Print a warning message\n *\n * @example\n * printWarning('API key will expire soon');\n * // Output: ⚠ API key will expire soon\n */\nexport function printWarning(message: string): void {\n  console.error(`${icons.warning} ${style.warn(message)}`);\n}\n\n/**\n * Print an info message\n *\n * @example\n * printInfo('Fetching data...');\n * // Output: ℹ Fetching data...\n */\nexport function printInfo(message: string): void {\n  console.log(`${icons.info} ${message}`);\n}\n\n/**\n * Print a key-value table\n *\n * @example\n * printTable({\n *   'Project': 'my-project',\n *   'Specification': 'v2.0',\n *   'Status': 'active',\n * });\n */\nexport function printTable(data: Record<string, string | null | undefined>): void {\n  const maxKeyLength = Math.max(...Object.keys(data).map(k => k.length));\n\n  for (const [key, value] of Object.entries(data)) {\n    const paddedKey = key.padEnd(maxKeyLength);\n    const displayValue = value ?? colors.muted('(not set)');\n    console.log(`  ${style.label(paddedKey)}  ${displayValue}`);\n  }\n}\n\n/**\n * Print JSON output (for --format json)\n *\n * @example\n * printJson({ project: 'my-project', status: 'active' });\n */\nexport function printJson(data: unknown): void {\n  console.log(JSON.stringify(data, null, 2));\n}\n\n/**\n * Print a command hint\n *\n * @example\n * printHint('specforge init', 'Initialize project');\n * // Output: → Run `specforge init` to initialize project\n */\nexport function printHint(command: string, description: string): void {\n  console.log(`${icons.arrow} Run ${style.command(command)} to ${description}`);\n}\n\n/**\n * Print a URL with description\n *\n * @example\n * printLink('https://specforge.com', 'Visit documentation');\n * // Output: → Visit documentation: https://specforge.com\n */\nexport function printLink(url: string, description: string): void {\n  console.log(`${icons.arrow} ${description}: ${style.url(url)}`);\n}\n\n/**\n * Format bytes to human readable size\n */\nexport function formatBytes(bytes: number): string {\n  if (bytes === 0) return '0 B';\n\n  const units = ['B', 'KB', 'MB', 'GB', 'TB'];\n  const i = Math.floor(Math.log(bytes) / Math.log(1024));\n\n  return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;\n}\n\n/**\n * Format duration in milliseconds to human readable\n */\nexport function formatDuration(ms: number): string {\n  if (ms < 1000) return `${ms}ms`;\n  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;\n  if (ms < 3600000) return `${Math.floor(ms / 60000)}m ${Math.floor((ms % 60000) / 1000)}s`;\n\n  const hours = Math.floor(ms / 3600000);\n  const minutes = Math.floor((ms % 3600000) / 60000);\n  return `${hours}h ${minutes}m`;\n}\n\n/**\n * Truncate string with ellipsis\n */\nexport function truncate(str: string, maxLength: number): string {\n  if (str.length <= maxLength) return str;\n  return str.slice(0, maxLength - 1) + '…';\n}\n"],"mappings":"AAMA,SAAS,QAAQ,OAAO,aAAa;AAS9B,SAAS,WAAW,OAAe,OAAwC;AAChF,QAAM,eAAe,SAAS,OAAO,MAAM,WAAW;AACtD,UAAQ,IAAI,GAAG,MAAM,MAAM,KAAK,CAAC,KAAK,YAAY,EAAE;AACtD;AAWO,SAAS,YAAY,OAAqB;AAC/C,UAAQ,IAAI;AACZ,UAAQ,IAAI,MAAM,MAAM,KAAK,CAAC;AAC9B,UAAQ,IAAI,OAAO,MAAM,SAAI,OAAO,MAAM,MAAM,CAAC,CAAC;AACpD;AAKO,SAAS,aAAmB;AACjC,UAAQ,IAAI;AACd;AAYO,SAAS,UAAU,OAAiB,SAAiB,MAAM,QAAc;AAC9E,aAAW,QAAQ,OAAO;AACxB,YAAQ,IAAI,KAAK,MAAM,IAAI,IAAI,EAAE;AAAA,EACnC;AACF;AASO,SAAS,aAAa,SAAuB;AAClD,UAAQ,IAAI,GAAG,MAAM,OAAO,IAAI,OAAO,EAAE;AAC3C;AASO,SAAS,WAAW,SAAuB;AAChD,UAAQ,MAAM,GAAG,MAAM,KAAK,IAAI,MAAM,IAAI,OAAO,CAAC,EAAE;AACtD;AASO,SAAS,aAAa,SAAuB;AAClD,UAAQ,MAAM,GAAG,MAAM,OAAO,IAAI,MAAM,KAAK,OAAO,CAAC,EAAE;AACzD;AASO,SAAS,UAAU,SAAuB;AAC/C,UAAQ,IAAI,GAAG,MAAM,IAAI,IAAI,OAAO,EAAE;AACxC;AAYO,SAAS,WAAW,MAAuD;AAChF,QAAM,eAAe,KAAK,IAAI,GAAG,OAAO,KAAK,IAAI,EAAE,IAAI,OAAK,EAAE,MAAM,CAAC;AAErE,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,IAAI,GAAG;AAC/C,UAAM,YAAY,IAAI,OAAO,YAAY;AACzC,UAAM,eAAe,SAAS,OAAO,MAAM,WAAW;AACtD,YAAQ,IAAI,KAAK,MAAM,MAAM,SAAS,CAAC,KAAK,YAAY,EAAE;AAAA,EAC5D;AACF;AAQO,SAAS,UAAU,MAAqB;AAC7C,UAAQ,IAAI,KAAK,UAAU,MAAM,MAAM,CAAC,CAAC;AAC3C;AASO,SAAS,UAAU,SAAiB,aAA2B;AACpE,UAAQ,IAAI,GAAG,MAAM,KAAK,QAAQ,MAAM,QAAQ,OAAO,CAAC,OAAO,WAAW,EAAE;AAC9E;AASO,SAAS,UAAU,KAAa,aAA2B;AAChE,UAAQ,IAAI,GAAG,MAAM,KAAK,IAAI,WAAW,KAAK,MAAM,IAAI,GAAG,CAAC,EAAE;AAChE;AAKO,SAAS,YAAY,OAAuB;AACjD,MAAI,UAAU,EAAG,QAAO;AAExB,QAAM,QAAQ,CAAC,KAAK,MAAM,MAAM,MAAM,IAAI;AAC1C,QAAM,IAAI,KAAK,MAAM,KAAK,IAAI,KAAK,IAAI,KAAK,IAAI,IAAI,CAAC;AAErD,SAAO,IAAI,QAAQ,KAAK,IAAI,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC;AAC9D;AAKO,SAAS,eAAe,IAAoB;AACjD,MAAI,KAAK,IAAM,QAAO,GAAG,EAAE;AAC3B,MAAI,KAAK,IAAO,QAAO,IAAI,KAAK,KAAM,QAAQ,CAAC,CAAC;AAChD,MAAI,KAAK,KAAS,QAAO,GAAG,KAAK,MAAM,KAAK,GAAK,CAAC,KAAK,KAAK,MAAO,KAAK,MAAS,GAAI,CAAC;AAEtF,QAAM,QAAQ,KAAK,MAAM,KAAK,IAAO;AACrC,QAAM,UAAU,KAAK,MAAO,KAAK,OAAW,GAAK;AACjD,SAAO,GAAG,KAAK,KAAK,OAAO;AAC7B;AAKO,SAAS,SAAS,KAAa,WAA2B;AAC/D,MAAI,IAAI,UAAU,UAAW,QAAO;AACpC,SAAO,IAAI,MAAM,GAAG,YAAY,CAAC,IAAI;AACvC;","names":[]}

package/dist/cli/ui/spinner.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Loading Spinner Utilities
+ *
+ * Wraps ora spinner with consistent styling and error handling.
+ */
+import { Ora } from 'ora';
+/**
+ * A single stage in a forgeProgress pipeline.
+ */
+export interface ForgeStage {
+    label: string;
+    fn: () => Promise<unknown>;
+}
+/**
+ * Run multi-stage operations with a branded gradient progress bar.
+ *
+ * TTY: draws the bar, stage counter, and labeled stage row, redrawing
+ * after each stage completes. Non-TTY: falls back to `[i/N] label...`
+ * log lines. Suppressed entirely when `SPECFORGE_JSON=1` is set.
+ */
+export declare function forgeProgress(context: string, stages: ForgeStage[]): Promise<unknown[]>;
+/**
+ * Spinner instance type
+ */
+export type Spinner = Ora;
+/**
+ * Create a new spinner with consistent styling
+ *
+ * @param text - Initial spinner text
+ * @returns Spinner instance
+ *
+ * @example
+ * ```typescript
+ * const spinner = createSpinner('Loading...');
+ * spinner.start();
+ *
+ * try {
+ *   await doAsyncWork();
+ *   spinner.succeed('Done!');
+ * } catch (error) {
+ *   spinner.fail('Failed');
+ * }
+ * ```
+ */
+export declare function createSpinner(text: string): Spinner;
+/**
+ * Run an async function with a spinner
+ *
+ * Automatically handles success/failure states.
+ *
+ * @param text - Spinner text while running
+ * @param fn - Async function to run
+ * @param successText - Text to show on success (optional)
+ * @returns Result of the async function
+ *
+ * @example
+ * ```typescript
+ * const data = await withSpinner(
+ *   'Fetching tickets...',
+ *   async () => await api.getTickets(),
+ *   'Tickets loaded'
+ * );
+ * ```
+ */
+export declare function withSpinner<T>(text: string, fn: () => Promise<T>, successText?: string): Promise<T>;
+/**
+ * Run multiple async operations with progress
+ *
+ * @param operations - Array of operations with labels
+ * @returns Array of results
+ *
+ * @example
+ * ```typescript
+ * const results = await withProgress([
+ *   { label: 'Loading config', fn: loadConfig },
+ *   { label: 'Fetching data', fn: fetchData },
+ *   { label: 'Processing', fn: process },
+ * ]);
+ * ```
+ */
+export declare function withProgress<T>(operations: Array<{
+    label: string;
+    fn: () => Promise<T>;
+}>): Promise<T[]>;
+/**
+ * Create a manual spinner for custom control
+ *
+ * @param text - Initial text
+ * @returns Object with spinner control methods
+ *
+ * @example
+ * ```typescript
+ * const { start, update, succeed, fail } = manualSpinner('Loading');
+ *
+ * start();
+ * update('Loading step 1...');
+ * update('Loading step 2...');
+ * succeed('All loaded');
+ * ```
+ */
+export declare function manualSpinner(text: string): {
+    start: () => Ora;
+    stop: () => Ora;
+    update: (newText: string) => void;
+    succeed: (finalText?: string) => void;
+    fail: (finalText?: string) => void;
+    warn: (finalText?: string) => void;
+    info: (finalText?: string) => void;
+};
+/**
+ * Check if spinners should be disabled (non-TTY)
+ */
+export declare function shouldDisableSpinner(): boolean;
+/**
+ * Simple progress indicator for non-TTY environments
+ *
+ * @param text - Progress text
+ */
+export declare function progressLog(text: string): void;
+//# sourceMappingURL=spinner.d.ts.map

package/dist/cli/ui/spinner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../../../src/cli/ui/spinner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAY,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AA0C/B;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,UAAU,EAAE,GACnB,OAAO,CAAC,OAAO,EAAE,CAAC,CAmDpB;AAED;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,GAAG,CAAC;AAE1B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMnD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,CAAC,CAAC,CAYZ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,UAAU,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC,GACzD,OAAO,CAAC,CAAC,EAAE,CAAC,CAad;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM;;;sBAMpB,MAAM;0BAGF,MAAM;uBAGT,MAAM;uBAGN,MAAM;uBAGN,MAAM;EAI5B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAO9C"}

package/dist/cli/ui/spinner.js

@@ -0,0 +1,158 @@
+import readline from "node:readline";
+import ora from "ora";
+import { icons } from "./colors.js";
+import { BRAND_PALETTE, ANSI_RESET, ANSI_BOLD } from "./banner.js";
+const C = BRAND_PALETTE;
+const GRADIENT_STOPS = [C.g1, C.g2, C.g3, C.g4, C.g5, C.g6, C.g7, C.g8, C.pink];
+const BAR_WIDTH = 23;
+const FORGE_RENDER_LINES = 5;
+function renderGradientBar(filledCount, totalWidth) {
+  let out = "";
+  for (let i = 0; i < totalWidth; i++) {
+    if (i < filledCount) {
+      const stopIdx = Math.min(
+        GRADIENT_STOPS.length - 1,
+        Math.floor(i / Math.max(1, totalWidth - 1) * (GRADIENT_STOPS.length - 1))
+      );
+      out += `${GRADIENT_STOPS[stopIdx]}\u25B0${ANSI_RESET}`;
+    } else {
+      out += `${C.darkGray}\u25B1${ANSI_RESET}`;
+    }
+  }
+  return out;
+}
+function renderStageLabels(stages, activeIdx, allDone) {
+  const parts = [];
+  for (let i = 0; i < stages.length; i++) {
+    if (allDone || i < activeIdx) {
+      parts.push(`${C.g4}\u2713${ANSI_RESET} ${stages[i].label}`);
+    } else if (i === activeIdx) {
+      parts.push(`${C.pink}\u2692${ANSI_RESET} ${stages[i].label}`);
+    }
+  }
+  return parts.join("    ");
+}
+async function forgeProgress(context, stages) {
+  const results = [];
+  const silent = process.env.SPECFORGE_JSON === "1";
+  const tty = process.stdout.isTTY && !silent;
+  if (silent) {
+    for (const stage of stages) {
+      results.push(await stage.fn());
+    }
+    return results;
+  }
+  if (!tty) {
+    for (let i = 0; i < stages.length; i++) {
+      console.log(`[${i + 1}/${stages.length}] ${stages[i].label}...`);
+      results.push(await stages[i].fn());
+    }
+    return results;
+  }
+  const render = (activeIdx, allDone) => {
+    const current = allDone ? stages.length : activeIdx;
+    const filled = Math.round(current / stages.length * BAR_WIDTH);
+    const header = `  ${C.darkGray}${context}${ANSI_RESET}  ${C.darkGray}\xB7${ANSI_RESET}  ${ANSI_BOLD}${C.g5}${current}/${stages.length}${ANSI_RESET} ${C.darkGray}stages${ANSI_RESET}`;
+    const bar = `  ${renderGradientBar(filled, BAR_WIDTH)}`;
+    const labels = `  ${renderStageLabels(stages, activeIdx, allDone)}`;
+    return `${header}
+
+${bar}
+
+${labels}`;
+  };
+  process.stdout.write(render(0, false) + "\n");
+  for (let i = 0; i < stages.length; i++) {
+    try {
+      const result = await stages[i].fn();
+      results.push(result);
+      readline.moveCursor(process.stdout, 0, -FORGE_RENDER_LINES);
+      readline.clearScreenDown(process.stdout);
+      const done = i === stages.length - 1;
+      process.stdout.write(render(done ? i : i + 1, done) + "\n");
+    } catch (err) {
+      readline.moveCursor(process.stdout, 0, -FORGE_RENDER_LINES);
+      readline.clearScreenDown(process.stdout);
+      const failHeader = `  ${C.darkGray}${context}${ANSI_RESET}  ${C.pink}failed${ANSI_RESET} ${C.darkGray}at${ANSI_RESET} ${ANSI_BOLD}${C.pink}${stages[i].label}${ANSI_RESET}`;
+      process.stdout.write(`${failHeader}
+
+
+
+
+`);
+      throw err;
+    }
+  }
+  return results;
+}
+function createSpinner(text) {
+  return ora({
+    text,
+    color: "cyan",
+    spinner: "dots"
+  });
+}
+async function withSpinner(text, fn, successText) {
+  const spinner = createSpinner(text);
+  spinner.start();
+  try {
+    const result = await fn();
+    spinner.succeed(successText || text.replace(/\.{3}$/, ""));
+    return result;
+  } catch (error) {
+    spinner.fail(text.replace(/\.{3}$/, " failed"));
+    throw error;
+  }
+}
+async function withProgress(operations) {
+  const results = [];
+  for (let i = 0; i < operations.length; i++) {
+    const { label, fn } = operations[i];
+    const progress = `[${i + 1}/${operations.length}]`;
+    const text = `${progress} ${label}...`;
+    const result = await withSpinner(text, fn);
+    results.push(result);
+  }
+  return results;
+}
+function manualSpinner(text) {
+  const spinner = createSpinner(text);
+  return {
+    start: () => spinner.start(),
+    stop: () => spinner.stop(),
+    update: (newText) => {
+      spinner.text = newText;
+    },
+    succeed: (finalText) => {
+      spinner.succeed(finalText);
+    },
+    fail: (finalText) => {
+      spinner.fail(finalText);
+    },
+    warn: (finalText) => {
+      spinner.warn(finalText);
+    },
+    info: (finalText) => {
+      spinner.info(finalText);
+    }
+  };
+}
+function shouldDisableSpinner() {
+  return !process.stdout.isTTY;
+}
+function progressLog(text) {
+  if (process.stdout.isTTY) {
+    return;
+  }
+  console.log(`${icons.running} ${text}`);
+}
+export {
+  createSpinner,
+  forgeProgress,
+  manualSpinner,
+  progressLog,
+  shouldDisableSpinner,
+  withProgress,
+  withSpinner
+};
+//# sourceMappingURL=spinner.js.map

package/dist/cli/ui/spinner.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/cli/ui/spinner.ts"],"sourcesContent":["/**\n * Loading Spinner Utilities\n *\n * Wraps ora spinner with consistent styling and error handling.\n */\n\nimport readline from 'node:readline';\nimport ora, { Ora } from 'ora';\nimport { colors, icons } from './colors.js';\nimport { BRAND_PALETTE, ANSI_RESET, ANSI_BOLD } from './banner.js';\n\nconst C = BRAND_PALETTE;\n\nconst GRADIENT_STOPS = [C.g1, C.g2, C.g3, C.g4, C.g5, C.g6, C.g7, C.g8, C.pink] as const;\nconst BAR_WIDTH = 23;\nconst FORGE_RENDER_LINES = 5;\n\nfunction renderGradientBar(filledCount: number, totalWidth: number): string {\n  let out = '';\n  for (let i = 0; i < totalWidth; i++) {\n    if (i < filledCount) {\n      const stopIdx = Math.min(\n        GRADIENT_STOPS.length - 1,\n        Math.floor((i / Math.max(1, totalWidth - 1)) * (GRADIENT_STOPS.length - 1))\n      );\n      out += `${GRADIENT_STOPS[stopIdx]}▰${ANSI_RESET}`;\n    } else {\n      out += `${C.darkGray}▱${ANSI_RESET}`;\n    }\n  }\n  return out;\n}\n\nfunction renderStageLabels(\n  stages: ReadonlyArray<ForgeStage>,\n  activeIdx: number,\n  allDone: boolean\n): string {\n  const parts: string[] = [];\n  for (let i = 0; i < stages.length; i++) {\n    if (allDone || i < activeIdx) {\n      parts.push(`${C.g4}✓${ANSI_RESET} ${stages[i].label}`);\n    } else if (i === activeIdx) {\n      parts.push(`${C.pink}⚒${ANSI_RESET} ${stages[i].label}`);\n    }\n  }\n  return parts.join('    ');\n}\n\n/**\n * A single stage in a forgeProgress pipeline.\n */\nexport interface ForgeStage {\n  label: string;\n  fn: () => Promise<unknown>;\n}\n\n/**\n * Run multi-stage operations with a branded gradient progress bar.\n *\n * TTY: draws the bar, stage counter, and labeled stage row, redrawing\n * after each stage completes. Non-TTY: falls back to `[i/N] label...`\n * log lines. Suppressed entirely when `SPECFORGE_JSON=1` is set.\n */\nexport async function forgeProgress(\n  context: string,\n  stages: ForgeStage[]\n): Promise<unknown[]> {\n  const results: unknown[] = [];\n  const silent = process.env.SPECFORGE_JSON === '1';\n  const tty = process.stdout.isTTY && !silent;\n\n  if (silent) {\n    for (const stage of stages) {\n      results.push(await stage.fn());\n    }\n    return results;\n  }\n\n  if (!tty) {\n    for (let i = 0; i < stages.length; i++) {\n      console.log(`[${i + 1}/${stages.length}] ${stages[i].label}...`);\n      results.push(await stages[i].fn());\n    }\n    return results;\n  }\n\n  const render = (activeIdx: number, allDone: boolean): string => {\n    const current = allDone ? stages.length : activeIdx;\n    const filled = Math.round((current / stages.length) * BAR_WIDTH);\n    const header = `  ${C.darkGray}${context}${ANSI_RESET}  ${C.darkGray}·${ANSI_RESET}  ${ANSI_BOLD}${C.g5}${current}/${stages.length}${ANSI_RESET} ${C.darkGray}stages${ANSI_RESET}`;\n    const bar = `  ${renderGradientBar(filled, BAR_WIDTH)}`;\n    const labels = `  ${renderStageLabels(stages, activeIdx, allDone)}`;\n    return `${header}\\n\\n${bar}\\n\\n${labels}`;\n  };\n\n  // Initial frame with stage 0 active\n  process.stdout.write(render(0, false) + '\\n');\n\n  for (let i = 0; i < stages.length; i++) {\n    try {\n      const result = await stages[i].fn();\n      results.push(result);\n\n      readline.moveCursor(process.stdout, 0, -FORGE_RENDER_LINES);\n      readline.clearScreenDown(process.stdout);\n      const done = i === stages.length - 1;\n      process.stdout.write(render(done ? i : i + 1, done) + '\\n');\n    } catch (err) {\n      readline.moveCursor(process.stdout, 0, -FORGE_RENDER_LINES);\n      readline.clearScreenDown(process.stdout);\n      const failHeader = `  ${C.darkGray}${context}${ANSI_RESET}  ${C.pink}failed${ANSI_RESET} ${C.darkGray}at${ANSI_RESET} ${ANSI_BOLD}${C.pink}${stages[i].label}${ANSI_RESET}`;\n      process.stdout.write(`${failHeader}\\n\\n\\n\\n\\n`);\n      throw err;\n    }\n  }\n\n  return results;\n}\n\n/**\n * Spinner instance type\n */\nexport type Spinner = Ora;\n\n/**\n * Create a new spinner with consistent styling\n *\n * @param text - Initial spinner text\n * @returns Spinner instance\n *\n * @example\n * ```typescript\n * const spinner = createSpinner('Loading...');\n * spinner.start();\n *\n * try {\n *   await doAsyncWork();\n *   spinner.succeed('Done!');\n * } catch (error) {\n *   spinner.fail('Failed');\n * }\n * ```\n */\nexport function createSpinner(text: string): Spinner {\n  return ora({\n    text,\n    color: 'cyan',\n    spinner: 'dots',\n  });\n}\n\n/**\n * Run an async function with a spinner\n *\n * Automatically handles success/failure states.\n *\n * @param text - Spinner text while running\n * @param fn - Async function to run\n * @param successText - Text to show on success (optional)\n * @returns Result of the async function\n *\n * @example\n * ```typescript\n * const data = await withSpinner(\n *   'Fetching tickets...',\n *   async () => await api.getTickets(),\n *   'Tickets loaded'\n * );\n * ```\n */\nexport async function withSpinner<T>(\n  text: string,\n  fn: () => Promise<T>,\n  successText?: string\n): Promise<T> {\n  const spinner = createSpinner(text);\n  spinner.start();\n\n  try {\n    const result = await fn();\n    spinner.succeed(successText || text.replace(/\\.{3}$/, ''));\n    return result;\n  } catch (error) {\n    spinner.fail(text.replace(/\\.{3}$/, ' failed'));\n    throw error;\n  }\n}\n\n/**\n * Run multiple async operations with progress\n *\n * @param operations - Array of operations with labels\n * @returns Array of results\n *\n * @example\n * ```typescript\n * const results = await withProgress([\n *   { label: 'Loading config', fn: loadConfig },\n *   { label: 'Fetching data', fn: fetchData },\n *   { label: 'Processing', fn: process },\n * ]);\n * ```\n */\nexport async function withProgress<T>(\n  operations: Array<{ label: string; fn: () => Promise<T> }>\n): Promise<T[]> {\n  const results: T[] = [];\n\n  for (let i = 0; i < operations.length; i++) {\n    const { label, fn } = operations[i];\n    const progress = `[${i + 1}/${operations.length}]`;\n    const text = `${progress} ${label}...`;\n\n    const result = await withSpinner(text, fn);\n    results.push(result);\n  }\n\n  return results;\n}\n\n/**\n * Create a manual spinner for custom control\n *\n * @param text - Initial text\n * @returns Object with spinner control methods\n *\n * @example\n * ```typescript\n * const { start, update, succeed, fail } = manualSpinner('Loading');\n *\n * start();\n * update('Loading step 1...');\n * update('Loading step 2...');\n * succeed('All loaded');\n * ```\n */\nexport function manualSpinner(text: string) {\n  const spinner = createSpinner(text);\n\n  return {\n    start: () => spinner.start(),\n    stop: () => spinner.stop(),\n    update: (newText: string) => {\n      spinner.text = newText;\n    },\n    succeed: (finalText?: string) => {\n      spinner.succeed(finalText);\n    },\n    fail: (finalText?: string) => {\n      spinner.fail(finalText);\n    },\n    warn: (finalText?: string) => {\n      spinner.warn(finalText);\n    },\n    info: (finalText?: string) => {\n      spinner.info(finalText);\n    },\n  };\n}\n\n/**\n * Check if spinners should be disabled (non-TTY)\n */\nexport function shouldDisableSpinner(): boolean {\n  return !process.stdout.isTTY;\n}\n\n/**\n * Simple progress indicator for non-TTY environments\n *\n * @param text - Progress text\n */\nexport function progressLog(text: string): void {\n  if (process.stdout.isTTY) {\n    // In TTY, use spinner instead\n    return;\n  }\n\n  console.log(`${icons.running} ${text}`);\n}\n"],"mappings":"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","names":[]}

package/dist/cli/ui/time.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Time Utilities
+ *
+ * Formatting utilities for time display in CLI output.
+ */
+/**
+ * Format ISO timestamp to relative time string
+ *
+ * Examples:
+ * - "just now" (< 1 minute)
+ * - "5m ago" (minutes)
+ * - "2h ago" (hours)
+ * - "3 days ago" (days)
+ * - "2 weeks ago" (weeks)
+ * - "1 month ago" (months)
+ * - "1 year ago" (years)
+ *
+ * @param isoString ISO 8601 timestamp string
+ * @returns Human-readable relative time
+ */
+export declare function formatRelativeTime(isoString: string): string;
+/**
+ * Format duration between two timestamps
+ *
+ * @param startIso Start timestamp (ISO 8601)
+ * @param endIso End timestamp (ISO 8601), defaults to now
+ * @returns Human-readable duration string
+ */
+export declare function formatDuration(startIso: string, endIso?: string): string;
+/**
+ * Format a timestamp for display
+ *
+ * @param isoString ISO 8601 timestamp string
+ * @param format Output format: 'relative', 'short', 'long'
+ * @returns Formatted time string
+ */
+export declare function formatTimestamp(isoString: string, format?: 'relative' | 'short' | 'long'): string;
+/**
+ * Check if a timestamp is within a given time window
+ *
+ * @param isoString ISO 8601 timestamp string
+ * @param windowMs Time window in milliseconds
+ * @returns True if within window
+ */
+export declare function isWithinTimeWindow(isoString: string, windowMs: number): boolean;
+/**
+ * Get "time ago" for session display
+ * Similar to formatRelativeTime but more compact
+ *
+ * @param isoString ISO 8601 timestamp string
+ * @returns Compact relative time (e.g., "2h 15m ago")
+ */
+export declare function formatTimeAgo(isoString: string): string;
+//# sourceMappingURL=time.d.ts.map

package/dist/cli/ui/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../../src/cli/ui/time.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAgD5D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CA0BxE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,UAAU,GAAG,OAAO,GAAG,MAAmB,GACjD,MAAM,CA6BR;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAK/E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CA0BvD"}

package/dist/cli/ui/time.js

@@ -0,0 +1,119 @@
+const MS_PER_MINUTE = 60 * 1e3;
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+const MS_PER_DAY = 24 * MS_PER_HOUR;
+const MS_PER_WEEK = 7 * MS_PER_DAY;
+const MS_PER_MONTH = 30 * MS_PER_DAY;
+const MS_PER_YEAR = 365 * MS_PER_DAY;
+function formatRelativeTime(isoString) {
+  const date = new Date(isoString);
+  const now = /* @__PURE__ */ new Date();
+  const diffMs = now.getTime() - date.getTime();
+  if (diffMs < 0) {
+    return "in the future";
+  }
+  if (diffMs < MS_PER_MINUTE) {
+    return "just now";
+  }
+  if (diffMs < MS_PER_HOUR) {
+    const minutes = Math.floor(diffMs / MS_PER_MINUTE);
+    return `${minutes}m ago`;
+  }
+  if (diffMs < MS_PER_DAY) {
+    const hours = Math.floor(diffMs / MS_PER_HOUR);
+    return `${hours}h ago`;
+  }
+  if (diffMs < MS_PER_WEEK) {
+    const days = Math.floor(diffMs / MS_PER_DAY);
+    return days === 1 ? "1 day ago" : `${days} days ago`;
+  }
+  if (diffMs < MS_PER_MONTH) {
+    const weeks = Math.floor(diffMs / MS_PER_WEEK);
+    return weeks === 1 ? "1 week ago" : `${weeks} weeks ago`;
+  }
+  if (diffMs < MS_PER_YEAR) {
+    const months = Math.floor(diffMs / MS_PER_MONTH);
+    return months === 1 ? "1 month ago" : `${months} months ago`;
+  }
+  const years = Math.floor(diffMs / MS_PER_YEAR);
+  return years === 1 ? "1 year ago" : `${years} years ago`;
+}
+function formatDuration(startIso, endIso) {
+  const start = new Date(startIso);
+  const end = endIso ? new Date(endIso) : /* @__PURE__ */ new Date();
+  const diffMs = end.getTime() - start.getTime();
+  if (diffMs < 0) {
+    return "0m";
+  }
+  const days = Math.floor(diffMs / MS_PER_DAY);
+  const hours = Math.floor(diffMs % MS_PER_DAY / MS_PER_HOUR);
+  const minutes = Math.floor(diffMs % MS_PER_HOUR / MS_PER_MINUTE);
+  if (days > 0) {
+    return `${days}d ${hours}h`;
+  }
+  if (hours > 0) {
+    return `${hours}h ${minutes}m`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m`;
+  }
+  return "just started";
+}
+function formatTimestamp(isoString, format = "relative") {
+  const date = new Date(isoString);
+  switch (format) {
+    case "relative":
+      return formatRelativeTime(isoString);
+    case "short":
+      return date.toLocaleString("en-US", {
+        month: "short",
+        day: "numeric",
+        hour: "numeric",
+        minute: "2-digit"
+      });
+    case "long":
+      return date.toLocaleString("en-US", {
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+        hour: "numeric",
+        minute: "2-digit"
+      });
+    default:
+      return formatRelativeTime(isoString);
+  }
+}
+function isWithinTimeWindow(isoString, windowMs) {
+  const date = new Date(isoString);
+  const now = /* @__PURE__ */ new Date();
+  const diffMs = now.getTime() - date.getTime();
+  return diffMs >= 0 && diffMs <= windowMs;
+}
+function formatTimeAgo(isoString) {
+  const date = new Date(isoString);
+  const now = /* @__PURE__ */ new Date();
+  const diffMs = now.getTime() - date.getTime();
+  if (diffMs < 0) {
+    return "in the future";
+  }
+  if (diffMs < MS_PER_MINUTE) {
+    return "just now";
+  }
+  const days = Math.floor(diffMs / MS_PER_DAY);
+  const hours = Math.floor(diffMs % MS_PER_DAY / MS_PER_HOUR);
+  const minutes = Math.floor(diffMs % MS_PER_HOUR / MS_PER_MINUTE);
+  if (days > 0) {
+    return `${days}d ${hours}h ago`;
+  }
+  if (hours > 0) {
+    return `${hours}h ${minutes}m ago`;
+  }
+  return `${minutes}m ago`;
+}
+export {
+  formatDuration,
+  formatRelativeTime,
+  formatTimeAgo,
+  formatTimestamp,
+  isWithinTimeWindow
+};
+//# sourceMappingURL=time.js.map

package/dist/cli/ui/time.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/cli/ui/time.ts"],"sourcesContent":["/**\n * Time Utilities\n *\n * Formatting utilities for time display in CLI output.\n */\n\n/**\n * Time unit thresholds in milliseconds\n */\nconst MS_PER_MINUTE = 60 * 1000;\nconst MS_PER_HOUR = 60 * MS_PER_MINUTE;\nconst MS_PER_DAY = 24 * MS_PER_HOUR;\nconst MS_PER_WEEK = 7 * MS_PER_DAY;\nconst MS_PER_MONTH = 30 * MS_PER_DAY;\nconst MS_PER_YEAR = 365 * MS_PER_DAY;\n\n/**\n * Format ISO timestamp to relative time string\n *\n * Examples:\n * - \"just now\" (< 1 minute)\n * - \"5m ago\" (minutes)\n * - \"2h ago\" (hours)\n * - \"3 days ago\" (days)\n * - \"2 weeks ago\" (weeks)\n * - \"1 month ago\" (months)\n * - \"1 year ago\" (years)\n *\n * @param isoString ISO 8601 timestamp string\n * @returns Human-readable relative time\n */\nexport function formatRelativeTime(isoString: string): string {\n  const date = new Date(isoString);\n  const now = new Date();\n  const diffMs = now.getTime() - date.getTime();\n\n  // Handle future dates\n  if (diffMs < 0) {\n    return 'in the future';\n  }\n\n  // Just now (< 1 minute)\n  if (diffMs < MS_PER_MINUTE) {\n    return 'just now';\n  }\n\n  // Minutes\n  if (diffMs < MS_PER_HOUR) {\n    const minutes = Math.floor(diffMs / MS_PER_MINUTE);\n    return `${minutes}m ago`;\n  }\n\n  // Hours\n  if (diffMs < MS_PER_DAY) {\n    const hours = Math.floor(diffMs / MS_PER_HOUR);\n    return `${hours}h ago`;\n  }\n\n  // Days\n  if (diffMs < MS_PER_WEEK) {\n    const days = Math.floor(diffMs / MS_PER_DAY);\n    return days === 1 ? '1 day ago' : `${days} days ago`;\n  }\n\n  // Weeks\n  if (diffMs < MS_PER_MONTH) {\n    const weeks = Math.floor(diffMs / MS_PER_WEEK);\n    return weeks === 1 ? '1 week ago' : `${weeks} weeks ago`;\n  }\n\n  // Months\n  if (diffMs < MS_PER_YEAR) {\n    const months = Math.floor(diffMs / MS_PER_MONTH);\n    return months === 1 ? '1 month ago' : `${months} months ago`;\n  }\n\n  // Years\n  const years = Math.floor(diffMs / MS_PER_YEAR);\n  return years === 1 ? '1 year ago' : `${years} years ago`;\n}\n\n/**\n * Format duration between two timestamps\n *\n * @param startIso Start timestamp (ISO 8601)\n * @param endIso End timestamp (ISO 8601), defaults to now\n * @returns Human-readable duration string\n */\nexport function formatDuration(startIso: string, endIso?: string): string {\n  const start = new Date(startIso);\n  const end = endIso ? new Date(endIso) : new Date();\n  const diffMs = end.getTime() - start.getTime();\n\n  if (diffMs < 0) {\n    return '0m';\n  }\n\n  const days = Math.floor(diffMs / MS_PER_DAY);\n  const hours = Math.floor((diffMs % MS_PER_DAY) / MS_PER_HOUR);\n  const minutes = Math.floor((diffMs % MS_PER_HOUR) / MS_PER_MINUTE);\n\n  if (days > 0) {\n    return `${days}d ${hours}h`;\n  }\n\n  if (hours > 0) {\n    return `${hours}h ${minutes}m`;\n  }\n\n  if (minutes > 0) {\n    return `${minutes}m`;\n  }\n\n  return 'just started';\n}\n\n/**\n * Format a timestamp for display\n *\n * @param isoString ISO 8601 timestamp string\n * @param format Output format: 'relative', 'short', 'long'\n * @returns Formatted time string\n */\nexport function formatTimestamp(\n  isoString: string,\n  format: 'relative' | 'short' | 'long' = 'relative'\n): string {\n  const date = new Date(isoString);\n\n  switch (format) {\n    case 'relative':\n      return formatRelativeTime(isoString);\n\n    case 'short':\n      // e.g., \"Jan 15, 2:30 PM\"\n      return date.toLocaleString('en-US', {\n        month: 'short',\n        day: 'numeric',\n        hour: 'numeric',\n        minute: '2-digit',\n      });\n\n    case 'long':\n      // e.g., \"January 15, 2024 at 2:30 PM\"\n      return date.toLocaleString('en-US', {\n        year: 'numeric',\n        month: 'long',\n        day: 'numeric',\n        hour: 'numeric',\n        minute: '2-digit',\n      });\n\n    default:\n      return formatRelativeTime(isoString);\n  }\n}\n\n/**\n * Check if a timestamp is within a given time window\n *\n * @param isoString ISO 8601 timestamp string\n * @param windowMs Time window in milliseconds\n * @returns True if within window\n */\nexport function isWithinTimeWindow(isoString: string, windowMs: number): boolean {\n  const date = new Date(isoString);\n  const now = new Date();\n  const diffMs = now.getTime() - date.getTime();\n  return diffMs >= 0 && diffMs <= windowMs;\n}\n\n/**\n * Get \"time ago\" for session display\n * Similar to formatRelativeTime but more compact\n *\n * @param isoString ISO 8601 timestamp string\n * @returns Compact relative time (e.g., \"2h 15m ago\")\n */\nexport function formatTimeAgo(isoString: string): string {\n  const date = new Date(isoString);\n  const now = new Date();\n  const diffMs = now.getTime() - date.getTime();\n\n  if (diffMs < 0) {\n    return 'in the future';\n  }\n\n  if (diffMs < MS_PER_MINUTE) {\n    return 'just now';\n  }\n\n  const days = Math.floor(diffMs / MS_PER_DAY);\n  const hours = Math.floor((diffMs % MS_PER_DAY) / MS_PER_HOUR);\n  const minutes = Math.floor((diffMs % MS_PER_HOUR) / MS_PER_MINUTE);\n\n  if (days > 0) {\n    return `${days}d ${hours}h ago`;\n  }\n\n  if (hours > 0) {\n    return `${hours}h ${minutes}m ago`;\n  }\n\n  return `${minutes}m ago`;\n}\n"],"mappings":"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","names":[]}

package/dist/client/api-client.d.ts

@@ -0,0 +1,123 @@
+/**
+ * SpecForge API Client
+ *
+ * HTTP client for communicating with the SpecForge API Gateway.
+ * Handles authentication, request/response formatting, and error handling.
+ */
+import { McpConfig } from '../config/index.js';
+import type { ITransport, TransportOrigin } from '../transport/interface.js';
+/**
+ * API response structure returned by SpecForge API
+ */
+export interface ApiResponse<T = unknown> {
+    /** Response data on success */
+    data?: T;
+    /** Error message on failure */
+    error?: string;
+}
+/**
+ * Result of API key validation
+ */
+export interface ApiKeyValidationResult {
+    /** Whether the API key is valid */
+    valid: boolean;
+    /** User ID associated with the key (if valid) */
+    userId?: string;
+    /** Permissions granted to the key (if valid) */
+    permissions?: {
+        read?: boolean;
+        write?: boolean;
+        admin?: boolean;
+    };
+    /** Error message (if invalid) */
+    message?: string;
+}
+/**
+ * Options for API requests
+ */
+export interface ApiRequestOptions {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Additional headers to include */
+    headers?: Record<string, string>;
+    /** Signal for aborting the request */
+    signal?: AbortSignal;
+}
+/**
+ * API Client for SpecForge
+ *
+ * @example
+ * ```typescript
+ * import { getConfig } from './config/index.js';
+ * import { ApiClient } from './client/api-client.js';
+ *
+ * const config = getConfig();
+ * const client = new ApiClient(config);
+ *
+ * // Make an API call
+ * const projects = await client.call('list_projects', { userId: 'user123' });
+ * ```
+ */
+export declare class ApiClient {
+    private config;
+    private transport;
+    private sessionId;
+    /**
+     * @param config - resolved MCP config (URL, key, debug)
+     * @param options - optional client options; `origin` sets the
+     *   `X-SpecForge-Origin` header (M9.7), defaulting to `mcp` (agent traffic).
+     *   The human CLI surface ({@link createCliClient} / the feedback command)
+     *   passes `cli`.
+     */
+    constructor(config: McpConfig, options?: {
+        origin?: TransportOrigin;
+    });
+    /**
+     * Get the underlying transport for direct use by tool handlers
+     */
+    getTransport(): ITransport;
+    /**
+     * Get the session ID for this MCP connection
+     * Used for working context management
+     */
+    getSessionId(): string;
+    /**
+     * Make an API call to SpecForge
+     *
+     * @param operation - Name of the operation to execute
+     * @param args - Arguments for the operation
+     * @param options - Optional request configuration
+     * @returns Promise resolving to the operation result
+     * @throws {Error} If the request fails or returns an error
+     *
+     * @example
+     * ```typescript
+     * // List projects
+     * const result = await client.call('list_projects');
+     *
+     * // Get a specific ticket
+     * const ticket = await client.call('get_ticket', { ticketId: 'ticket123' });
+     * ```
+     */
+    call<T = unknown>(operation: string, args?: Record<string, unknown>, _options?: ApiRequestOptions): Promise<T>;
+    /**
+     * Validate the configured API key
+     *
+     * Makes a lightweight call to verify the API key is valid and
+     * returns the associated user information.
+     *
+     * @returns Promise resolving to validation result
+     *
+     * @example
+     * ```typescript
+     * const result = await client.validateApiKey();
+     * if (result.valid) {
+     *   console.log('Authenticated as:', result.userId);
+     * } else {
+     *   console.error('Invalid API key:', result.message);
+     * }
+     * ```
+     */
+    validateApiKey(): Promise<ApiKeyValidationResult>;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/client/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/client/api-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAG7E;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,+BAA+B;IAC/B,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,mCAAmC;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,WAAW,CAAC,EAAE;QACZ,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAC;IACF,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,sCAAsC;IACtC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAOD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,SAAS,CAAS;IAE1B;;;;;;OAMG;gBACS,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,eAAe,CAAA;KAAO;IAYzE;;OAEG;IACH,YAAY,IAAI,UAAU;IAI1B;;;OAGG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;;;;;;;;;;;;;OAiBG;IACG,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAClC,QAAQ,GAAE,iBAAsB,GAC/B,OAAO,CAAC,CAAC,CAAC;IAkBb;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,IAAI,OAAO,CAAC,sBAAsB,CAAC;CAwBxD"}