@kb-labs/shared-cli-ui 2.94.0 → 2.98.0

package/dist/index.d.cts

@@ -1,4 +1,6 @@
 export { DebugContext, DebugDetailLevel, DebugEntry, DebugExportOptions, DebugFilterOptions, DebugFormat, DebugLevel, DebugMeta, DebugOutput, DebugOutputOptions, DebugSection, DebugTrace, DebugTree, DebugTreeNode, DebugTreeOptions, HumanFormatterOptions, TraceOptions, createDebugTree, describeEntriesAI, describeEntriesHuman, describeEntriesTimeline, exportDebugEntries, exportToChromeFormat, exportToJSON, exportToPlainText, filterByLevel, filterByNamespace, filterByTimeRange, filterDebugEntries, formatDebugEntriesAI, formatDebugEntriesHuman, formatDebugEntryAI, formatDebugEntryHuman, formatDebugOutput, formatDebugOutputs, formatTimeline, formatTimelineNode, formatTimelineWithSummary, groupByGroup, groupByNamespace, searchInLogs, shouldUseAIFormat } from './debug.cjs';
+export { ConfirmOptions, MultiSelectChoice, MultiSelectOptions, SelectChoice, SelectOptions, TextOptions, confirm, isInteractive, multiSelect, select, text } from './interactive/index.cjs';
+import { SelectChoice, MultiSelectChoice, UIFacade } from '@kb-labs/plugin-contracts';
 
 /**
  * Minimalist color utilities for CLI output
@@ -32,6 +34,10 @@ declare const symbols: {
     package: string;
     pointer: string;
     section: string;
+    step: string;
+    stepDone: string;
+    arrow: string;
+    diamond: string;
 };
 declare const supportsColor: boolean;
 declare const safeColors: {
@@ -62,6 +68,10 @@ declare const safeSymbols: {
     package: string;
     pointer: string;
     section: string;
+    step: string;
+    stepDone: string;
+    arrow: string;
+    diamond: string;
     separator: string;
     border: string;
     topLeft: string;
@@ -845,22 +855,146 @@ interface RetryOptions {
 }
 declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 
+interface ErrorContext {
+    ui?: {
+        json?: (data: unknown) => void;
+        error?: (message: string, opts?: Record<string, unknown>) => void;
+    };
+}
+/**
+ * Structured validation error — emits { ok: false, error: { code: 'INVALID_ARGS', ... } } in JSON mode.
+ * Call before try/catch, right before `return { exitCode: 1 }`.
+ */
+declare function validationError(ctx: ErrorContext, message: string, hint?: string, isJson?: boolean): void;
+/**
+ * Structured runtime/API error — emits { ok: false, error: { code: 'INTERNAL_ERROR', ... } } in JSON mode.
+ * Call in catch blocks, right before `return { exitCode: 1 }`.
+ */
+declare function handleError(ctx: ErrorContext, err: unknown, isJson?: boolean): void;
+/**
+ * Re-throws `err` as an HTTP-aware error for REST handlers.
+ * Envelope middleware reads `err.statusCode` to set HTTP status.
+ * If err already has statusCode — preserves it. Otherwise → 500.
+ */
+declare function rethrowForRest(err: unknown): never;
+
+/**
+ * Destructive-action protocol (SOFT layer).
+ *
+ * A single, platform-wide way for a command to declare that an operation is
+ * destructive — how bad, how broad, and whether it can be undone — and to gate
+ * it behind explicit confirmation in EVERY mode (human and agent).
+ *
+ * This layer is intentionally SOFT: it informs and asks, it does not enforce.
+ * Physical enforcement (can-this-token-even-invoke-this) is the platform's
+ * future token/permission layer; it reads the SAME `severity`/`destructive`
+ * declaration on the command. So one declaration drives both:
+ *   - now:   this helper renders a clear signal + requires `--yes`;
+ *   - later: the permission layer filters discovery + blocks invocation by right.
+ *
+ * Declaring it is OPTIONAL for external plugins (commands work without it) but
+ * strongly recommended — agents can only reason about blast radius they're told.
+ */
+type DestructiveSeverity = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Severity rubric — worst-case blast radius weighed against recovery cost
+ * (keep consistent across plugins so agents can calibrate):
+ *  - low      narrow scope AND trivially auto-rebuilt from source (idempotent)
+ *  - medium   a bounded set is lost; rebuildable, but with effort/recompute
+ *  - high     a WHOLE collection is destroyed (entire index/corpus), OR recovery
+ *             is slow / manual — even if rebuildable, the loss is large and
+ *             easy to mis-target
+ *  - critical irreversible, NO recovery (prod data, tenant wipe)
+ */
+interface DestructiveAction {
+    /** Command identity, e.g. "mind drop". */
+    action: string;
+    /** What is affected, e.g. 'index "code"'. */
+    resource: string;
+    /** Plain-language effect, e.g. "deletes all vectors + the manifest". */
+    effect: string;
+    /** Blast-radius tier. */
+    severity: DestructiveSeverity;
+    /** Whether the data can be recovered afterwards. */
+    reversible: boolean;
+    /** How to recover, if reversible (e.g. "re-run `kb mind index --full`"). */
+    recovery?: string;
+    /** Quantified scope — how much, of what, how broad. */
+    blastRadius?: {
+        count?: number;
+        unit?: string;
+        scope?: string;
+    };
+    /** Flag that confirms the action (default `--yes`). */
+    confirmFlag?: string;
+}
+/** The machine-readable signal an agent receives when confirmation is missing. */
+interface ConfirmationRequired {
+    ok: false;
+    confirmationRequired: true;
+    destructive: true;
+    irreversible: boolean;
+    severity: DestructiveSeverity;
+    action: string;
+    resource: string;
+    effect: string;
+    reversible: boolean;
+    blastRadius?: {
+        count?: number;
+        unit?: string;
+        scope?: string;
+    };
+    recovery?: string;
+    confirmWith: string;
+    message: string;
+}
+interface ConfirmContext {
+    ui?: {
+        json?: (data: unknown) => void;
+        warn?: (message: string, opts?: Record<string, unknown>) => void;
+        error?: (message: string, opts?: Record<string, unknown>) => void;
+    };
+}
+/**
+ * Build the machine-readable signal an agent receives when confirmation is
+ * missing in json mode. Exported so a non-CLI surface (REST 409, MCP) can reuse
+ * the exact shape instead of re-deriving it.
+ */
+declare function buildConfirmationSignal(a: DestructiveAction): ConfirmationRequired;
+/** Render the one-line warning — leads with the scary part (irreversibility + severity). */
+declare function renderDestructiveMessage(a: DestructiveAction): string;
+/**
+ * Gate a destructive command. Returns the command result to return immediately
+ * when NOT confirmed (in every mode — agents get the structured signal, not a
+ * silent execution), or `null` when confirmed so the caller proceeds.
+ *
+ *   const blocked = confirmDestructive(ctx, { confirmed: flags.yes, isJson, action });
+ *   if (blocked) return blocked;
+ */
+declare function confirmDestructive(ctx: ConfirmContext, opts: {
+    confirmed: boolean;
+    isJson?: boolean;
+    action: DestructiveAction;
+}): {
+    exitCode: number;
+} | null;
+
 /**
  * Modern CLI formatting utilities with side border design
  * Provides minimalist, modern UI components for CLI output
  */
 
 /**
- * Side border box - modern minimalist design
+ * Side border box - Clack-style design
  *
  * @example
  * ```
- * ┌── Command Name
+ * ◆  Command Name
  * │
- * │ Section Header
+ * │  Section Header
  * │  Key: value
  * │
- * └── ✓ Success / 12ms
+ * └  ✓ Success  84ms
  * ```
  */
 interface SideBorderBoxOptions {
@@ -869,6 +1003,7 @@ interface SideBorderBoxOptions {
     footer?: string;
     status?: 'success' | 'error' | 'warning' | 'info';
     timing?: number;
+    summary?: Record<string, string | number | boolean>;
 }
 interface RichSectionItem {
     text: string;
@@ -899,6 +1034,36 @@ declare function metricsList(metrics: Record<string, string | number>): string[]
  * Format status line for footer
  */
 declare function statusLine(status: 'success' | 'error' | 'warning' | 'info', timing?: number): string;
+/**
+ * A single block in a chained output — a title + sections with optional footer on the last block.
+ */
+interface SideBorderChainItem {
+    title: string;
+    sections: SectionContent[];
+    summary?: Record<string, string | number | boolean>;
+    status?: 'success' | 'error' | 'warning' | 'info';
+    timing?: number;
+}
+/**
+ * Render multiple side-border blocks as a continuous visual chain.
+ *
+ * Every block opens with `◆  Title` on the shared rail.
+ * Only the last block gets `└  status  timing`.
+ *
+ * @example
+ * ```
+ * ◆  workflow metrics
+ * │
+ * │  Failed to fetch metrics
+ * │
+ * ◆  Warning
+ * │
+ * │  Make sure daemon is running
+ * │
+ * └  ✗  12ms
+ * ```
+ */
+declare function sideBorderChain(items: SideBorderChainItem[]): string;
 /**
  * Convert an Error or raw string into clean display lines for sideBorderBox items.
  * Splits on newlines, removes blank lines, and caps at maxLines with a "… N more" hint.
@@ -1066,4 +1231,73 @@ declare function infoResult(title: string, data?: {
     timing?: number;
 }): CommandOutput;
 
-export { type AnalyticsConfig, type ArtifactDisplayOptions, type ArtifactInfo, type BaseFlagSpec, type BooleanFlagSpec, type CLIPackage, type CommandContext, type CommandDiscovery, type CommandExecutionResult, type CommandInfo, type CommandManifest, type CommandOutput, type CommandPresenter, type CommandRegistry, type CommandResult, type CommandResultParams, type CommandRunnerOptions, type CommandSuggestion, DynamicCommandDiscovery, type EnvDefinition, type EnvSchema, type FlagDefinition, type FlagSpec, type FlagType, type FlagsDefinition, type FlagsSchema, type FormatTimestampOptions, type InferFlagsType, type KeyValueOptions, Loader, type LoaderOptions, type ManifestLoader, type MultiCLIContext, MultiCLISuggestions, type NumberFlagSpec, type RetryOptions, type RichSectionItem, type RuntimeLike, type SafeKeyValueOptions, type SectionContent, type SectionItem, type SideBorderBoxOptions, StaticCommandDiscovery, type StringFlagSpec, type TableColumn, type TableOptions, TimingTracker, accentLabel, box, bulletList, colors, createCommandDiscovery, createCommandRegistry, createCommandRunner, createDetailedResult, createKBLabsCommandDiscovery, createProgressBar, createSimpleResult, createSpinner, defineEnv, defineFlags, discoverArtifacts, displayArtifacts, displayArtifactsCompact, displaySingleArtifact, errorResult, extractCommandGroups, extractCommandIds, findCommandById, findCommandsByGroup, formatCommandHelp, formatCommandOutput, formatCommandResult, formatError, formatKeyValueTable, formatRelativeTime, formatSize, formatTable, formatTimestamp, formatTiming, formatTimingBreakdown, generateDevlinkSuggestions, generateGroupSuggestions, generateQuickActions, getCommandInfo, getContextCwd, hasAnsi, headline, indent, infoResult, isCommandAvailable, isJsonMode, keyValue, mergeFlags, metricsList, muted, pad, parseBoolean, parseEnvFromRuntime, parseFlagsFromInput, parseNumber, parseNumberFlag, parseString, safeColors, safeKeyValue, safeSymbols, section, sectionHeader, setJsonMode, showError, showLoading, showSuccess, sideBorderBox, statusLine, stripAnsi, successResult, supportsColor, symbols, table, toPosixPath, truncate, useLoader, validateSuggestions, warningResult, withRetry };
+/**
+ * Structured log display for CLI output (watch/run/stream commands).
+ * Not a spinner — for rendering log lines with level, timestamp, and message.
+ */
+type LogLevel = 'info' | 'warn' | 'error' | 'debug' | 'verbose';
+declare function logLine(level: LogLevel, message: string): string;
+declare function logGroup(title: string, lines: string[]): string;
+declare function printLog(level: LogLevel, message: string): void;
+
+/**
+ * Inline status badges for CLI output.
+ *
+ * @example
+ * badge('ONLINE', 'success')   → green  [ONLINE]
+ * badge('FAILED', 'error')     → red    [FAILED]
+ * badge('PENDING', 'neutral')  → muted  [PENDING]
+ */
+type BadgeVariant = 'success' | 'error' | 'warning' | 'info' | 'neutral';
+declare function badge(label: string, variant?: BadgeVariant): string;
+declare function statusBadge(status: string): string;
+
+/**
+ * Multi-step task runner with visual progress.
+ * Each task shows as ○ pending → spinner running → ● done / ✗ failed.
+ *
+ * @example
+ * await runTasks([
+ *   { title: 'Install dependencies', run: async () => { ... } },
+ *   { title: 'Build', run: async () => { ... } },
+ * ])
+ */
+interface Task {
+    title: string;
+    run: (updateTitle: (t: string) => void) => Promise<void>;
+}
+declare function runTasks(tasks: Task[]): Promise<void>;
+
+/**
+ * All interactive prompt methods of UIFacade.
+ * Required (not optional) so TypeScript catches missing implementations
+ * when UIFacade gains a new prompt method.
+ */
+interface UIPrompts {
+    confirm(msg: string, opts?: {
+        defaultValue?: boolean;
+    }): Promise<boolean>;
+    prompt(msg: string, opts?: {
+        default?: string;
+        mask?: boolean;
+    }): Promise<string>;
+    select<T>(msg: string, choices: SelectChoice<T>[]): Promise<T>;
+    multiSelect<T>(msg: string, choices: MultiSelectChoice<T>[]): Promise<T[]>;
+}
+/**
+ * Safe-return prompts for non-interactive contexts (subprocess, sandbox).
+ * All methods return the most sensible default without any I/O.
+ */
+declare const NOOP_PROMPTS: UIPrompts;
+/**
+ * Shared stdout UIFacade factory for subprocess/worker contexts.
+ *
+ * Both params are required so TypeScript catches any new UIFacade interactive
+ * method at the call site rather than silently inheriting a noop default.
+ *
+ * Uses `satisfies UIFacade` on the object literal — TypeScript will error here
+ * (not just at the return type) if any UIFacade method is missing.
+ */
+declare function createBaseStdoutUI(prompts: UIPrompts, log: UIFacade['log']): UIFacade;
+
+export { type AnalyticsConfig, type ArtifactDisplayOptions, type ArtifactInfo, type BadgeVariant, type BaseFlagSpec, type BooleanFlagSpec, type CLIPackage, type CommandContext, type CommandDiscovery, type CommandExecutionResult, type CommandInfo, type CommandManifest, type CommandOutput, type CommandPresenter, type CommandRegistry, type CommandResult, type CommandResultParams, type CommandRunnerOptions, type CommandSuggestion, type ConfirmationRequired, type DestructiveAction, type DestructiveSeverity, DynamicCommandDiscovery, type EnvDefinition, type EnvSchema, type FlagDefinition, type FlagSpec, type FlagType, type FlagsDefinition, type FlagsSchema, type FormatTimestampOptions, type InferFlagsType, type KeyValueOptions, Loader, type LoaderOptions, type LogLevel, type ManifestLoader, type MultiCLIContext, MultiCLISuggestions, NOOP_PROMPTS, type NumberFlagSpec, type RetryOptions, type RichSectionItem, type RuntimeLike, type SafeKeyValueOptions, type SectionContent, type SectionItem, type SideBorderBoxOptions, type SideBorderChainItem, StaticCommandDiscovery, type StringFlagSpec, type TableColumn, type TableOptions, type Task, TimingTracker, type UIPrompts, accentLabel, badge, box, buildConfirmationSignal, bulletList, colors, confirmDestructive, createBaseStdoutUI, createCommandDiscovery, createCommandRegistry, createCommandRunner, createDetailedResult, createKBLabsCommandDiscovery, createProgressBar, createSimpleResult, createSpinner, defineEnv, defineFlags, discoverArtifacts, displayArtifacts, displayArtifactsCompact, displaySingleArtifact, errorResult, extractCommandGroups, extractCommandIds, findCommandById, findCommandsByGroup, formatCommandHelp, formatCommandOutput, formatCommandResult, formatError, formatKeyValueTable, formatRelativeTime, formatSize, formatTable, formatTimestamp, formatTiming, formatTimingBreakdown, generateDevlinkSuggestions, generateGroupSuggestions, generateQuickActions, getCommandInfo, getContextCwd, handleError, hasAnsi, headline, indent, infoResult, isCommandAvailable, isJsonMode, keyValue, logGroup, logLine, mergeFlags, metricsList, muted, pad, parseBoolean, parseEnvFromRuntime, parseFlagsFromInput, parseNumber, parseNumberFlag, parseString, printLog, renderDestructiveMessage, rethrowForRest, runTasks, safeColors, safeKeyValue, safeSymbols, section, sectionHeader, setJsonMode, showError, showLoading, showSuccess, sideBorderBox, sideBorderChain, statusBadge, statusLine, stripAnsi, successResult, supportsColor, symbols, table, toPosixPath, truncate, useLoader, validateSuggestions, validationError, warningResult, withRetry };

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { DebugContext, DebugDetailLevel, DebugEntry, DebugExportOptions, DebugFilterOptions, DebugFormat, DebugLevel, DebugMeta, DebugOutput, DebugOutputOptions, DebugSection, DebugTrace, DebugTree, DebugTreeNode, DebugTreeOptions, HumanFormatterOptions, TraceOptions, createDebugTree, describeEntriesAI, describeEntriesHuman, describeEntriesTimeline, exportDebugEntries, exportToChromeFormat, exportToJSON, exportToPlainText, filterByLevel, filterByNamespace, filterByTimeRange, filterDebugEntries, formatDebugEntriesAI, formatDebugEntriesHuman, formatDebugEntryAI, formatDebugEntryHuman, formatDebugOutput, formatDebugOutputs, formatTimeline, formatTimelineNode, formatTimelineWithSummary, groupByGroup, groupByNamespace, searchInLogs, shouldUseAIFormat } from './debug.js';
+export { ConfirmOptions, MultiSelectChoice, MultiSelectOptions, SelectChoice, SelectOptions, TextOptions, confirm, isInteractive, multiSelect, select, text } from './interactive/index.js';
+import { SelectChoice, MultiSelectChoice, UIFacade } from '@kb-labs/plugin-contracts';
 
 /**
  * Minimalist color utilities for CLI output
@@ -32,6 +34,10 @@ declare const symbols: {
     package: string;
     pointer: string;
     section: string;
+    step: string;
+    stepDone: string;
+    arrow: string;
+    diamond: string;
 };
 declare const supportsColor: boolean;
 declare const safeColors: {
@@ -62,6 +68,10 @@ declare const safeSymbols: {
     package: string;
     pointer: string;
     section: string;
+    step: string;
+    stepDone: string;
+    arrow: string;
+    diamond: string;
     separator: string;
     border: string;
     topLeft: string;
@@ -845,22 +855,146 @@ interface RetryOptions {
 }
 declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 
+interface ErrorContext {
+    ui?: {
+        json?: (data: unknown) => void;
+        error?: (message: string, opts?: Record<string, unknown>) => void;
+    };
+}
+/**
+ * Structured validation error — emits { ok: false, error: { code: 'INVALID_ARGS', ... } } in JSON mode.
+ * Call before try/catch, right before `return { exitCode: 1 }`.
+ */
+declare function validationError(ctx: ErrorContext, message: string, hint?: string, isJson?: boolean): void;
+/**
+ * Structured runtime/API error — emits { ok: false, error: { code: 'INTERNAL_ERROR', ... } } in JSON mode.
+ * Call in catch blocks, right before `return { exitCode: 1 }`.
+ */
+declare function handleError(ctx: ErrorContext, err: unknown, isJson?: boolean): void;
+/**
+ * Re-throws `err` as an HTTP-aware error for REST handlers.
+ * Envelope middleware reads `err.statusCode` to set HTTP status.
+ * If err already has statusCode — preserves it. Otherwise → 500.
+ */
+declare function rethrowForRest(err: unknown): never;
+
+/**
+ * Destructive-action protocol (SOFT layer).
+ *
+ * A single, platform-wide way for a command to declare that an operation is
+ * destructive — how bad, how broad, and whether it can be undone — and to gate
+ * it behind explicit confirmation in EVERY mode (human and agent).
+ *
+ * This layer is intentionally SOFT: it informs and asks, it does not enforce.
+ * Physical enforcement (can-this-token-even-invoke-this) is the platform's
+ * future token/permission layer; it reads the SAME `severity`/`destructive`
+ * declaration on the command. So one declaration drives both:
+ *   - now:   this helper renders a clear signal + requires `--yes`;
+ *   - later: the permission layer filters discovery + blocks invocation by right.
+ *
+ * Declaring it is OPTIONAL for external plugins (commands work without it) but
+ * strongly recommended — agents can only reason about blast radius they're told.
+ */
+type DestructiveSeverity = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Severity rubric — worst-case blast radius weighed against recovery cost
+ * (keep consistent across plugins so agents can calibrate):
+ *  - low      narrow scope AND trivially auto-rebuilt from source (idempotent)
+ *  - medium   a bounded set is lost; rebuildable, but with effort/recompute
+ *  - high     a WHOLE collection is destroyed (entire index/corpus), OR recovery
+ *             is slow / manual — even if rebuildable, the loss is large and
+ *             easy to mis-target
+ *  - critical irreversible, NO recovery (prod data, tenant wipe)
+ */
+interface DestructiveAction {
+    /** Command identity, e.g. "mind drop". */
+    action: string;
+    /** What is affected, e.g. 'index "code"'. */
+    resource: string;
+    /** Plain-language effect, e.g. "deletes all vectors + the manifest". */
+    effect: string;
+    /** Blast-radius tier. */
+    severity: DestructiveSeverity;
+    /** Whether the data can be recovered afterwards. */
+    reversible: boolean;
+    /** How to recover, if reversible (e.g. "re-run `kb mind index --full`"). */
+    recovery?: string;
+    /** Quantified scope — how much, of what, how broad. */
+    blastRadius?: {
+        count?: number;
+        unit?: string;
+        scope?: string;
+    };
+    /** Flag that confirms the action (default `--yes`). */
+    confirmFlag?: string;
+}
+/** The machine-readable signal an agent receives when confirmation is missing. */
+interface ConfirmationRequired {
+    ok: false;
+    confirmationRequired: true;
+    destructive: true;
+    irreversible: boolean;
+    severity: DestructiveSeverity;
+    action: string;
+    resource: string;
+    effect: string;
+    reversible: boolean;
+    blastRadius?: {
+        count?: number;
+        unit?: string;
+        scope?: string;
+    };
+    recovery?: string;
+    confirmWith: string;
+    message: string;
+}
+interface ConfirmContext {
+    ui?: {
+        json?: (data: unknown) => void;
+        warn?: (message: string, opts?: Record<string, unknown>) => void;
+        error?: (message: string, opts?: Record<string, unknown>) => void;
+    };
+}
+/**
+ * Build the machine-readable signal an agent receives when confirmation is
+ * missing in json mode. Exported so a non-CLI surface (REST 409, MCP) can reuse
+ * the exact shape instead of re-deriving it.
+ */
+declare function buildConfirmationSignal(a: DestructiveAction): ConfirmationRequired;
+/** Render the one-line warning — leads with the scary part (irreversibility + severity). */
+declare function renderDestructiveMessage(a: DestructiveAction): string;
+/**
+ * Gate a destructive command. Returns the command result to return immediately
+ * when NOT confirmed (in every mode — agents get the structured signal, not a
+ * silent execution), or `null` when confirmed so the caller proceeds.
+ *
+ *   const blocked = confirmDestructive(ctx, { confirmed: flags.yes, isJson, action });
+ *   if (blocked) return blocked;
+ */
+declare function confirmDestructive(ctx: ConfirmContext, opts: {
+    confirmed: boolean;
+    isJson?: boolean;
+    action: DestructiveAction;
+}): {
+    exitCode: number;
+} | null;
+
 /**
  * Modern CLI formatting utilities with side border design
  * Provides minimalist, modern UI components for CLI output
  */
 
 /**
- * Side border box - modern minimalist design
+ * Side border box - Clack-style design
  *
  * @example
  * ```
- * ┌── Command Name
+ * ◆  Command Name
  * │
- * │ Section Header
+ * │  Section Header
  * │  Key: value
  * │
- * └── ✓ Success / 12ms
+ * └  ✓ Success  84ms
  * ```
  */
 interface SideBorderBoxOptions {
@@ -869,6 +1003,7 @@ interface SideBorderBoxOptions {
     footer?: string;
     status?: 'success' | 'error' | 'warning' | 'info';
     timing?: number;
+    summary?: Record<string, string | number | boolean>;
 }
 interface RichSectionItem {
     text: string;
@@ -899,6 +1034,36 @@ declare function metricsList(metrics: Record<string, string | number>): string[]
  * Format status line for footer
  */
 declare function statusLine(status: 'success' | 'error' | 'warning' | 'info', timing?: number): string;
+/**
+ * A single block in a chained output — a title + sections with optional footer on the last block.
+ */
+interface SideBorderChainItem {
+    title: string;
+    sections: SectionContent[];
+    summary?: Record<string, string | number | boolean>;
+    status?: 'success' | 'error' | 'warning' | 'info';
+    timing?: number;
+}
+/**
+ * Render multiple side-border blocks as a continuous visual chain.
+ *
+ * Every block opens with `◆  Title` on the shared rail.
+ * Only the last block gets `└  status  timing`.
+ *
+ * @example
+ * ```
+ * ◆  workflow metrics
+ * │
+ * │  Failed to fetch metrics
+ * │
+ * ◆  Warning
+ * │
+ * │  Make sure daemon is running
+ * │
+ * └  ✗  12ms
+ * ```
+ */
+declare function sideBorderChain(items: SideBorderChainItem[]): string;
 /**
  * Convert an Error or raw string into clean display lines for sideBorderBox items.
  * Splits on newlines, removes blank lines, and caps at maxLines with a "… N more" hint.
@@ -1066,4 +1231,73 @@ declare function infoResult(title: string, data?: {
     timing?: number;
 }): CommandOutput;
 
-export { type AnalyticsConfig, type ArtifactDisplayOptions, type ArtifactInfo, type BaseFlagSpec, type BooleanFlagSpec, type CLIPackage, type CommandContext, type CommandDiscovery, type CommandExecutionResult, type CommandInfo, type CommandManifest, type CommandOutput, type CommandPresenter, type CommandRegistry, type CommandResult, type CommandResultParams, type CommandRunnerOptions, type CommandSuggestion, DynamicCommandDiscovery, type EnvDefinition, type EnvSchema, type FlagDefinition, type FlagSpec, type FlagType, type FlagsDefinition, type FlagsSchema, type FormatTimestampOptions, type InferFlagsType, type KeyValueOptions, Loader, type LoaderOptions, type ManifestLoader, type MultiCLIContext, MultiCLISuggestions, type NumberFlagSpec, type RetryOptions, type RichSectionItem, type RuntimeLike, type SafeKeyValueOptions, type SectionContent, type SectionItem, type SideBorderBoxOptions, StaticCommandDiscovery, type StringFlagSpec, type TableColumn, type TableOptions, TimingTracker, accentLabel, box, bulletList, colors, createCommandDiscovery, createCommandRegistry, createCommandRunner, createDetailedResult, createKBLabsCommandDiscovery, createProgressBar, createSimpleResult, createSpinner, defineEnv, defineFlags, discoverArtifacts, displayArtifacts, displayArtifactsCompact, displaySingleArtifact, errorResult, extractCommandGroups, extractCommandIds, findCommandById, findCommandsByGroup, formatCommandHelp, formatCommandOutput, formatCommandResult, formatError, formatKeyValueTable, formatRelativeTime, formatSize, formatTable, formatTimestamp, formatTiming, formatTimingBreakdown, generateDevlinkSuggestions, generateGroupSuggestions, generateQuickActions, getCommandInfo, getContextCwd, hasAnsi, headline, indent, infoResult, isCommandAvailable, isJsonMode, keyValue, mergeFlags, metricsList, muted, pad, parseBoolean, parseEnvFromRuntime, parseFlagsFromInput, parseNumber, parseNumberFlag, parseString, safeColors, safeKeyValue, safeSymbols, section, sectionHeader, setJsonMode, showError, showLoading, showSuccess, sideBorderBox, statusLine, stripAnsi, successResult, supportsColor, symbols, table, toPosixPath, truncate, useLoader, validateSuggestions, warningResult, withRetry };
+/**
+ * Structured log display for CLI output (watch/run/stream commands).
+ * Not a spinner — for rendering log lines with level, timestamp, and message.
+ */
+type LogLevel = 'info' | 'warn' | 'error' | 'debug' | 'verbose';
+declare function logLine(level: LogLevel, message: string): string;
+declare function logGroup(title: string, lines: string[]): string;
+declare function printLog(level: LogLevel, message: string): void;
+
+/**
+ * Inline status badges for CLI output.
+ *
+ * @example
+ * badge('ONLINE', 'success')   → green  [ONLINE]
+ * badge('FAILED', 'error')     → red    [FAILED]
+ * badge('PENDING', 'neutral')  → muted  [PENDING]
+ */
+type BadgeVariant = 'success' | 'error' | 'warning' | 'info' | 'neutral';
+declare function badge(label: string, variant?: BadgeVariant): string;
+declare function statusBadge(status: string): string;
+
+/**
+ * Multi-step task runner with visual progress.
+ * Each task shows as ○ pending → spinner running → ● done / ✗ failed.
+ *
+ * @example
+ * await runTasks([
+ *   { title: 'Install dependencies', run: async () => { ... } },
+ *   { title: 'Build', run: async () => { ... } },
+ * ])
+ */
+interface Task {
+    title: string;
+    run: (updateTitle: (t: string) => void) => Promise<void>;
+}
+declare function runTasks(tasks: Task[]): Promise<void>;
+
+/**
+ * All interactive prompt methods of UIFacade.
+ * Required (not optional) so TypeScript catches missing implementations
+ * when UIFacade gains a new prompt method.
+ */
+interface UIPrompts {
+    confirm(msg: string, opts?: {
+        defaultValue?: boolean;
+    }): Promise<boolean>;
+    prompt(msg: string, opts?: {
+        default?: string;
+        mask?: boolean;
+    }): Promise<string>;
+    select<T>(msg: string, choices: SelectChoice<T>[]): Promise<T>;
+    multiSelect<T>(msg: string, choices: MultiSelectChoice<T>[]): Promise<T[]>;
+}
+/**
+ * Safe-return prompts for non-interactive contexts (subprocess, sandbox).
+ * All methods return the most sensible default without any I/O.
+ */
+declare const NOOP_PROMPTS: UIPrompts;
+/**
+ * Shared stdout UIFacade factory for subprocess/worker contexts.
+ *
+ * Both params are required so TypeScript catches any new UIFacade interactive
+ * method at the call site rather than silently inheriting a noop default.
+ *
+ * Uses `satisfies UIFacade` on the object literal — TypeScript will error here
+ * (not just at the return type) if any UIFacade method is missing.
+ */
+declare function createBaseStdoutUI(prompts: UIPrompts, log: UIFacade['log']): UIFacade;
+
+export { type AnalyticsConfig, type ArtifactDisplayOptions, type ArtifactInfo, type BadgeVariant, type BaseFlagSpec, type BooleanFlagSpec, type CLIPackage, type CommandContext, type CommandDiscovery, type CommandExecutionResult, type CommandInfo, type CommandManifest, type CommandOutput, type CommandPresenter, type CommandRegistry, type CommandResult, type CommandResultParams, type CommandRunnerOptions, type CommandSuggestion, type ConfirmationRequired, type DestructiveAction, type DestructiveSeverity, DynamicCommandDiscovery, type EnvDefinition, type EnvSchema, type FlagDefinition, type FlagSpec, type FlagType, type FlagsDefinition, type FlagsSchema, type FormatTimestampOptions, type InferFlagsType, type KeyValueOptions, Loader, type LoaderOptions, type LogLevel, type ManifestLoader, type MultiCLIContext, MultiCLISuggestions, NOOP_PROMPTS, type NumberFlagSpec, type RetryOptions, type RichSectionItem, type RuntimeLike, type SafeKeyValueOptions, type SectionContent, type SectionItem, type SideBorderBoxOptions, type SideBorderChainItem, StaticCommandDiscovery, type StringFlagSpec, type TableColumn, type TableOptions, type Task, TimingTracker, type UIPrompts, accentLabel, badge, box, buildConfirmationSignal, bulletList, colors, confirmDestructive, createBaseStdoutUI, createCommandDiscovery, createCommandRegistry, createCommandRunner, createDetailedResult, createKBLabsCommandDiscovery, createProgressBar, createSimpleResult, createSpinner, defineEnv, defineFlags, discoverArtifacts, displayArtifacts, displayArtifactsCompact, displaySingleArtifact, errorResult, extractCommandGroups, extractCommandIds, findCommandById, findCommandsByGroup, formatCommandHelp, formatCommandOutput, formatCommandResult, formatError, formatKeyValueTable, formatRelativeTime, formatSize, formatTable, formatTimestamp, formatTiming, formatTimingBreakdown, generateDevlinkSuggestions, generateGroupSuggestions, generateQuickActions, getCommandInfo, getContextCwd, handleError, hasAnsi, headline, indent, infoResult, isCommandAvailable, isJsonMode, keyValue, logGroup, logLine, mergeFlags, metricsList, muted, pad, parseBoolean, parseEnvFromRuntime, parseFlagsFromInput, parseNumber, parseNumberFlag, parseString, printLog, renderDestructiveMessage, rethrowForRest, runTasks, safeColors, safeKeyValue, safeSymbols, section, sectionHeader, setJsonMode, showError, showLoading, showSuccess, sideBorderBox, sideBorderChain, statusBadge, statusLine, stripAnsi, successResult, supportsColor, symbols, table, toPosixPath, truncate, useLoader, validateSuggestions, validationError, warningResult, withRetry };