@mono-agent/agent-app 0.3.0 → 0.4.1

package/dist/setup.js

@@ -0,0 +1,97 @@
+import { WITH_CHANNELS } from "./init.js";
+import { RECIPE_CATALOG } from "./recipes/index.js";
+export async function collectSetupOptions(options) {
+    const recipes = options.recipes ?? RECIPE_CATALOG;
+    const recipe = options.recipe ?? await promptForRecipe(options.prompt, recipes);
+    const recipeInputs = {};
+    const secrets = [];
+    for (const input of recipe.inputs) {
+        if (input.secret === true) {
+            secrets.push(secretChecklistItem(input));
+            continue;
+        }
+        const defaultValue = input.id === "model" && options.model !== undefined ? options.model : input.default;
+        const answer = await options.prompt.question(inputPrompt(input, defaultValue));
+        const value = answer.trim();
+        if (value.length > 0) {
+            recipeInputs[input.id] = value;
+        }
+        else if (defaultValue !== undefined) {
+            recipeInputs[input.id] = defaultValue;
+        }
+    }
+    const fallbackModels = await promptForFallbackModels(options.prompt, options.fallbackModels ?? []);
+    const withChannels = await promptForWithChannels(options.prompt, options.withChannels ?? []);
+    return { recipe, recipeInputs, fallbackModels, withChannels, secrets };
+}
+export function renderSetupRecipeMenu(recipes = RECIPE_CATALOG) {
+    return recipes
+        .map((recipe, index) => {
+        const tags = recipe.tags.length === 0 ? "" : ` (${recipe.tags.join(", ")})`;
+        return `${index + 1}. ${recipe.id} [risk: ${recipe.riskLevel}] - ${recipe.title}${tags}`;
+    })
+        .join("\n");
+}
+function inputPrompt(input, defaultValue) {
+    const suffix = defaultValue === undefined ? "" : ` [${defaultValue}]`;
+    return `${input.label}${suffix}\n${input.description}\n> `;
+}
+function secretChecklistItem(input) {
+    return {
+        id: input.id,
+        label: input.label,
+        description: input.description,
+        ...(input.envVar === undefined ? {} : { envVar: input.envVar }),
+    };
+}
+async function promptForRecipe(prompt, recipes) {
+    if (recipes.length === 0) {
+        throw new Error("No setup recipes are available.");
+    }
+    for (;;) {
+        const answer = await prompt.question(`Choose a recipe:\n${renderSetupRecipeMenu(recipes)}\nRecipe [1]: `);
+        const selected = parseRecipeChoice(answer, recipes);
+        if (selected !== undefined) {
+            return selected;
+        }
+    }
+}
+function parseRecipeChoice(answer, recipes) {
+    const value = answer.trim();
+    if (value.length === 0) {
+        return recipes[0];
+    }
+    const index = Number(value);
+    if (Number.isInteger(index) && index >= 1 && index <= recipes.length) {
+        return recipes[index - 1];
+    }
+    return recipes.find((recipe) => recipe.id === value);
+}
+async function promptForWithChannels(prompt, defaults) {
+    const defaultText = defaults.length === 0 ? "none" : defaults.join(",");
+    for (;;) {
+        const answer = await prompt.question(`Enable add-on channels (${WITH_CHANNELS.join(", ")}) [${defaultText}]: `);
+        const raw = answer.trim();
+        if (raw.length === 0) {
+            return defaults;
+        }
+        const parsed = raw.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+        const invalid = parsed.filter((entry) => !WITH_CHANNELS.includes(entry));
+        if (invalid.length === 0) {
+            return parsed;
+        }
+    }
+}
+async function promptForFallbackModels(prompt, defaults) {
+    const defaultText = defaults.length === 0 ? "none" : defaults.join(",");
+    const answer = await prompt.question(`Fallback models, comma-separated [${defaultText}]: `);
+    const raw = answer.trim();
+    if (raw.length === 0) {
+        return defaults;
+    }
+    if (raw.toLowerCase() === "none") {
+        return [];
+    }
+    return raw.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}
+//# sourceMappingURL=setup.js.map

package/dist/setup.js.map

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

package/dist/trigger-overrides.d.ts

@@ -0,0 +1,17 @@
+/** One enabled trigger (cron job / webhook endpoint) carrying override strings. */
+export interface TriggerOverrideEntry {
+    /** Display name for the issue message, e.g. `cron job "digest"`. */
+    readonly name: string;
+    readonly model?: string;
+    readonly effort?: string;
+}
+/**
+ * Validate per-trigger `model`/`effort` overrides with the same parsers the
+ * runtime applies at run time (`request-model-override.ts`), but at
+ * validate/load time — so a typo'd cron `model` fails `mono-agent validate`
+ * before the 3am job silently falls back to the default. At run time an
+ * invalid value is still warn-and-ignored; this check only moves the discovery
+ * forward, it never changes run behavior.
+ */
+export declare function findTriggerOverrideIssues(entries: readonly TriggerOverrideEntry[]): readonly string[];
+//# sourceMappingURL=trigger-overrides.d.ts.map

package/dist/trigger-overrides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger-overrides.d.ts","sourceRoot":"","sources":["../src/trigger-overrides.ts"],"names":[],"mappings":"AAGA,mFAAmF;AACnF,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,SAAS,oBAAoB,EAAE,GACvC,SAAS,MAAM,EAAE,CAkBnB"}

package/dist/trigger-overrides.js

@@ -0,0 +1,30 @@
+import { EFFORT_LEVELS } from "@mono-agent/config";
+import { parseMonoRuntimeModelReference } from "@mono-agent/runtime-adapter";
+const EFFORT_SET = new Set(EFFORT_LEVELS);
+/**
+ * Validate per-trigger `model`/`effort` overrides with the same parsers the
+ * runtime applies at run time (`request-model-override.ts`), but at
+ * validate/load time — so a typo'd cron `model` fails `mono-agent validate`
+ * before the 3am job silently falls back to the default. At run time an
+ * invalid value is still warn-and-ignored; this check only moves the discovery
+ * forward, it never changes run behavior.
+ */
+export function findTriggerOverrideIssues(entries) {
+    const issues = [];
+    for (const entry of entries) {
+        if (entry.model !== undefined) {
+            try {
+                parseMonoRuntimeModelReference(entry.model);
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                issues.push(`${entry.name} has an invalid model override "${entry.model}": ${reason}`);
+            }
+        }
+        if (entry.effort !== undefined && !EFFORT_SET.has(entry.effort)) {
+            issues.push(`${entry.name} has an invalid effort override "${entry.effort}". Valid: ${[...EFFORT_SET].join(", ")}.`);
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=trigger-overrides.js.map

package/dist/trigger-overrides.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger-overrides.js","sourceRoot":"","sources":["../src/trigger-overrides.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAU7E,MAAM,UAAU,GAAwB,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAwC;IAExC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC;gBACH,8BAA8B,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC9C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACtE,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,mCAAmC,KAAK,CAAC,KAAK,MAAM,MAAM,EAAE,CAAC,CAAC;YACzF,CAAC;QACH,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;YAChE,MAAM,CAAC,IAAI,CACT,GAAG,KAAK,CAAC,IAAI,oCAAoC,KAAK,CAAC,MAAM,aAAa,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACxG,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/tui-command.d.ts

@@ -0,0 +1,56 @@
+import { listTraceSources } from "@mono-agent/observability";
+import type { TraceSourceListItem } from "@mono-agent/observability";
+export interface RunTuiOptions {
+    readonly configPath: string;
+    readonly cwd: string;
+    readonly env: Record<string, string | undefined>;
+    /** --agent: connect to this label or sourceId directly. */
+    readonly agent?: string;
+    /** --conversation: conversation id to chat under (default tui-<sourceId>). */
+    readonly conversationId?: string;
+}
+/** Test seams: discovery + TUI boot are injectable. */
+export interface RunTuiDeps {
+    readonly listSources?: typeof listTraceSources;
+    readonly startTui?: (options: Record<string, unknown>) => Promise<{
+        waitUntilExit(): Promise<void>;
+    }>;
+    readonly isTty?: boolean;
+    readonly stdout?: {
+        write(text: string): void;
+    };
+    readonly stderr?: {
+        write(text: string): void;
+    };
+}
+export type TuiLaunchPlan = {
+    readonly kind: "none";
+    readonly message: string;
+} | {
+    readonly kind: "error";
+    readonly message: string;
+} | {
+    readonly kind: "connect";
+    readonly source: TraceSourceListItem;
+} | {
+    readonly kind: "picker";
+    readonly sources: readonly TraceSourceListItem[];
+};
+/**
+ * Pure selection logic for `mono-agent tui`: which running agent to connect
+ * to, or whether to open the picker. `registryDirs` names every registry that
+ * was consulted (one entry, or two when the configured registry and the
+ * machine-wide global one differ) purely for the "nothing found" messaging.
+ * Exported for unit tests.
+ */
+export declare function resolveTuiLaunch(sources: readonly TraceSourceListItem[], registryDirs: readonly string[], agentFilter: string | undefined): TuiLaunchPlan;
+/** Extract the tui channel's baseUrl from a manifest's channel summaries. */
+export declare function tuiEndpointOf(source: TraceSourceListItem): string | undefined;
+/**
+ * `mono-agent tui`: discover running agents (machine-wide registry), resolve
+ * the target's stream endpoint + key, and launch the operator console. Works
+ * from any directory — with no local config the registry falls back to
+ * ~/.mono-agent/trace-sources.
+ */
+export declare function runTui(options: RunTuiOptions, deps?: RunTuiDeps): Promise<number>;
+//# sourceMappingURL=tui-command.d.ts.map

package/dist/tui-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tui-command.d.ts","sourceRoot":"","sources":["../src/tui-command.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAwC,MAAM,2BAA2B,CAAC;AACnG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAKrE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACjD,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,gBAAgB,CAAC;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;QAAE,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC,CAAC;IACtG,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACjD;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,GAClE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAA;CAAE,CAAC;AAElF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,mBAAmB,EAAE,EACvC,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,aAAa,CAiCf;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAe7E;AAED;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CA2F3F"}

package/dist/tui-command.js

@@ -0,0 +1,160 @@
+import { dirname, resolve } from "node:path";
+import { listTraceSources, mergeTraceSources, pruneTraceSources } from "@mono-agent/observability";
+import { loadTuiAdapterConfig } from "@mono-agent/operator-adapter";
+import { resolveAppTraceRegistryDir, resolveGlobalTraceRegistryDir } from "./app-config.js";
+/**
+ * Pure selection logic for `mono-agent tui`: which running agent to connect
+ * to, or whether to open the picker. `registryDirs` names every registry that
+ * was consulted (one entry, or two when the configured registry and the
+ * machine-wide global one differ) purely for the "nothing found" messaging.
+ * Exported for unit tests.
+ */
+export function resolveTuiLaunch(sources, registryDirs, agentFilter) {
+    const alive = sources.filter((source) => source.health !== "stopped");
+    const registryLabel = registryDirs.length <= 1 ? `registry: ${registryDirs[0] ?? ""}` : `registries: ${registryDirs.join(", ")}`;
+    if (agentFilter !== undefined) {
+        const match = alive.find((source) => source.label === agentFilter || source.sourceId === agentFilter);
+        if (match === undefined) {
+            const available = alive.map((source) => `  ${source.label} (${source.sourceId})`).join("\n");
+            return {
+                kind: "error",
+                message: `No running agent matches \`${agentFilter}\`.\n` +
+                    (alive.length === 0
+                        ? `No agents are running (${registryLabel}).`
+                        : `Running agents:\n${available}`),
+            };
+        }
+        return { kind: "connect", source: match };
+    }
+    if (alive.length === 0) {
+        return {
+            kind: "none",
+            message: `No running agents found (${registryLabel}).\n` +
+                "Start one with `mono-agent start` in its folder, then run `mono-agent tui` again.",
+        };
+    }
+    if (alive.length === 1 && alive[0] !== undefined) {
+        return { kind: "connect", source: alive[0] };
+    }
+    return { kind: "picker", sources: alive };
+}
+/** Extract the tui channel's baseUrl from a manifest's channel summaries. */
+export function tuiEndpointOf(source) {
+    const channels = source.metadata?.channels;
+    if (typeof channels !== "object" || channels === null) {
+        return undefined;
+    }
+    const tui = channels.tui;
+    if (typeof tui !== "object" || tui === null) {
+        return undefined;
+    }
+    const record = tui;
+    // Non-empty required: a malformed manifest with baseUrl "" must fall back to
+    // discovery mode rather than attempt a broken connection.
+    return record.kind === "running" && typeof record.baseUrl === "string" && record.baseUrl.length > 0
+        ? record.baseUrl
+        : undefined;
+}
+/**
+ * `mono-agent tui`: discover running agents (machine-wide registry), resolve
+ * the target's stream endpoint + key, and launch the operator console. Works
+ * from any directory — with no local config the registry falls back to
+ * ~/.mono-agent/trace-sources.
+ */
+export async function runTui(options, deps = {}) {
+    const stdout = deps.stdout ?? process.stdout;
+    const stderr = deps.stderr ?? process.stderr;
+    if ((deps.isTty ?? process.stdin.isTTY) !== true) {
+        stderr.write("mono-agent tui needs an interactive terminal (stdin is not a TTY).\n");
+        return 1;
+    }
+    const configuredRegistryDir = await resolveAppTraceRegistryDir({
+        env: options.env,
+        cwd: options.cwd,
+        configPath: options.configPath,
+    });
+    const globalRegistryDir = resolveGlobalTraceRegistryDir(options.env);
+    const listSources = deps.listSources ?? listTraceSources;
+    // Use the registry's own echoed (normalized) dir from here on. The "does this
+    // differ from the global registry" decision is made BEFORE querying (against
+    // the resolvers' own output), not against the echoed result, since a listing
+    // seam is free to echo back whatever registryDir it likes.
+    const sameAsGlobal = resolve(configuredRegistryDir) === resolve(globalRegistryDir);
+    const primary = await listSources({ registryDir: configuredRegistryDir });
+    void pruneTraceSources({ registryDir: primary.registryDir });
+    const merged = sameAsGlobal ? undefined : await listSources({ registryDir: globalRegistryDir });
+    if (merged !== undefined) {
+        void pruneTraceSources({ registryDir: merged.registryDir });
+    }
+    const sources = merged === undefined ? primary.sources : mergeTraceSources(primary.sources, merged.sources);
+    // Every consulted registry, in precedence order. The TUI's discovery view
+    // (picker, and its in-TUI `r`/`/agents` refresh) re-lists from these, so it
+    // MUST see the full union: an agent present only in its local registry (a
+    // globalDiscovery:false opt-out, or one still running a pre-mirror build)
+    // stays visible from inside its own directory.
+    const registryDirs = merged === undefined ? [primary.registryDir] : [primary.registryDir, merged.registryDir];
+    const plan = resolveTuiLaunch(sources, registryDirs, options.agent);
+    if (plan.kind === "none") {
+        stdout.write(`${plan.message}\n`);
+        return 1;
+    }
+    if (plan.kind === "error") {
+        stderr.write(`${plan.message}\n`);
+        return 1;
+    }
+    // Lazy: the TUI (and pi-tui) load only when this command actually runs.
+    const startTui = deps.startTui ??
+        (async (tuiOptions) => {
+            const { startMonoAgentTui } = await import("@mono-agent/tui");
+            return startMonoAgentTui(tuiOptions);
+        });
+    const common = {
+        title: "mono-agent",
+        env: options.env,
+        ...(options.conversationId === undefined ? {} : { conversationId: options.conversationId }),
+    };
+    if (plan.kind === "picker") {
+        const handle = await startTui({ ...common, discovery: { registryDirs } });
+        await handle.waitUntilExit();
+        return 0;
+    }
+    const source = plan.source;
+    const baseUrl = tuiEndpointOf(source);
+    const apiKey = await resolveAgentApiKey(source, options.env);
+    const handle = await startTui({
+        ...common,
+        ...(baseUrl === undefined
+            ? // No stream endpoint (tui channel disabled): replay/config still work.
+                { discovery: { registryDirs } }
+            : { connection: { baseUrl, ...(apiKey === undefined ? {} : { apiKey }) } }),
+        instance: {
+            label: source.label,
+            artifactDir: source.artifactDir,
+            ...(source.configPath === undefined ? {} : { configPath: source.configPath }),
+        },
+        ...(options.conversationId === undefined ? { conversationId: `tui-${source.sourceId}` } : {}),
+        subtitle: source.configPath === undefined ? source.sourceId : dirname(resolve(source.configPath)),
+    });
+    if (baseUrl === undefined) {
+        stdout.write(`Agent \`${source.label}\` has no tui stream endpoint (channel disabled?) — opening in discovery mode; replay/config remain available.\n`);
+    }
+    await handle.waitUntilExit();
+    return 0;
+}
+/**
+ * The registry never carries secrets: read `tui.apiKey` through the adapter's
+ * own loader against the agent's config file (json→env layering included).
+ */
+async function resolveAgentApiKey(source, env) {
+    if (source.configPath === undefined) {
+        return env.MONO_AGENT_TUI_API_KEY;
+    }
+    try {
+        const config = await loadTuiAdapterConfig({ env, jsonPath: source.configPath });
+        return config.apiKey;
+    }
+    catch {
+        return env.MONO_AGENT_TUI_API_KEY;
+    }
+}
+//# sourceMappingURL=tui-command.js.map

package/dist/tui-command.js.map

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

package/dist/ui.d.ts

@@ -0,0 +1,54 @@
+import type { ValidationStatus } from "./doctor.js";
+/**
+ * Decide whether ANSI color should be emitted. `NO_COLOR` (any value) always
+ * wins per the no-color.org convention; `FORCE_COLOR` forces the decision when
+ * set to a recognized truthy/falsy value; otherwise color follows the TTY-ness
+ * of the stream. Pure and env-injected so it is trivially testable.
+ */
+export declare function computeColorEnabled(env: Record<string, string | undefined>, isTty: boolean | undefined): boolean;
+export declare function isColorEnabled(): boolean;
+/** Color/weight helpers. Each is the identity function when color is disabled. */
+export declare const style: {
+    readonly bold: (text: string) => string;
+    readonly dim: (text: string) => string;
+    readonly red: (text: string) => string;
+    readonly green: (text: string) => string;
+    readonly yellow: (text: string) => string;
+    readonly cyan: (text: string) => string;
+    readonly gray: (text: string) => string;
+};
+/**
+ * Render a status badge as a fixed-width prefix (badge + trailing space). With
+ * color on it is a green/yellow/dim/red glyph; with color off it falls back to
+ * an equal-width ASCII tag so columns still line up in plain output.
+ */
+export declare function badge(status: ValidationStatus): string;
+/**
+ * Render aligned `label  value` rows: labels are padded to the widest label so
+ * values line up, replacing the hand-tuned `padEnd` blocks. `indent` prefixes
+ * every row with that many spaces (used to nest rows under a section rule).
+ * Returns one string with a trailing newline per row (empty when there are no
+ * rows).
+ */
+export declare function keyValue(rows: ReadonlyArray<readonly [label: string, value: string]>, indent?: number): string;
+/**
+ * A horizontal section divider, optionally labeled — `── instance ────────`.
+ * Width tracks the terminal (read at call time so resizes are honored), capped
+ * for readability and falling back to a fixed width when stdout is not a TTY.
+ * Rendered dim/gray (identity when color is off); the label appears verbatim so
+ * it stays greppable. Always ends with a newline.
+ */
+export declare function rule(label?: string): string;
+/** Badge for a channel status *kind* string (running/waiting…/disabled/error). */
+export declare function channelBadge(kind: string): string;
+/** Badge for a trace-source health word (running/stale/stopped/…). */
+export declare function healthBadge(health: string): string;
+/** A bold/cyan section heading with a trailing newline. */
+export declare function heading(text: string): string;
+/** The CLI title block: bold title plus an optional dim subtitle. */
+export declare function banner(title: string, subtitle?: string): string;
+/** A red error line (✗ prefix) with a trailing newline — write to stderr. */
+export declare function errorLine(message: string): string;
+/** A dim hint line (→ prefix) with a trailing newline. */
+export declare function hint(message: string): string;
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAuBpD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,KAAK,EAAE,OAAO,GAAG,SAAS,GACzB,OAAO,CAYT;AAID,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAMD,kFAAkF;AAClF,eAAO,MAAM,KAAK;0BACH,MAAM,KAAG,MAAM;yBAChB,MAAM,KAAG,MAAM;yBACf,MAAM,KAAG,MAAM;2BACb,MAAM,KAAG,MAAM;4BACd,MAAM,KAAG,MAAM;0BACjB,MAAM,KAAG,MAAM;0BACf,MAAM,KAAG,MAAM;CACpB,CAAC;AAgBX;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAGtD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,EAC5D,MAAM,SAAI,GACT,MAAM,CASR;AAKD;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ3C;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkBjD;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAWlD;AAED,2DAA2D;AAC3D,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,qEAAqE;AACrE,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,0DAA0D;AAC1D,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5C"}

package/dist/ui.js

@@ -0,0 +1,157 @@
+import process from "node:process";
+/**
+ * Tiny zero-dependency terminal styling layer for the CLI. Every helper returns
+ * a plain string, so callers can keep writing through `process.stdout.write` or
+ * the injected `deps.stdout`/`deps.stderr` sinks in background.ts. Color is a
+ * single global decision keyed on the REAL process stdout (see
+ * {@link computeColorEnabled}); when it is off — piped output, `NO_COLOR`, or a
+ * non-TTY test harness — every styling helper degrades to plain ASCII so logs
+ * and test assertions stay greppable.
+ */
+const ANSI = {
+    reset: "",
+    bold: "",
+    dim: "",
+    red: "",
+    green: "",
+    yellow: "",
+    cyan: "",
+    gray: "",
+};
+/**
+ * Decide whether ANSI color should be emitted. `NO_COLOR` (any value) always
+ * wins per the no-color.org convention; `FORCE_COLOR` forces the decision when
+ * set to a recognized truthy/falsy value; otherwise color follows the TTY-ness
+ * of the stream. Pure and env-injected so it is trivially testable.
+ */
+export function computeColorEnabled(env, isTty) {
+    if (env.NO_COLOR !== undefined) {
+        return false;
+    }
+    const force = env.FORCE_COLOR;
+    if (force === "1" || force === "true") {
+        return true;
+    }
+    if (force === "0" || force === "false") {
+        return false;
+    }
+    return Boolean(isTty);
+}
+const colorEnabled = computeColorEnabled(process.env, process.stdout.isTTY);
+export function isColorEnabled() {
+    return colorEnabled;
+}
+function paint(code, text) {
+    return colorEnabled ? `${code}${text}${ANSI.reset}` : text;
+}
+/** Color/weight helpers. Each is the identity function when color is disabled. */
+export const style = {
+    bold: (text) => paint(ANSI.bold, text),
+    dim: (text) => paint(ANSI.dim, text),
+    red: (text) => paint(ANSI.red, text),
+    green: (text) => paint(ANSI.green, text),
+    yellow: (text) => paint(ANSI.yellow, text),
+    cyan: (text) => paint(ANSI.cyan, text),
+    gray: (text) => paint(ANSI.gray, text),
+};
+const BADGES = {
+    ok: { glyph: "✓", paint: style.green, plain: "[ok]   " },
+    waiting: { glyph: "⚠", paint: style.yellow, plain: "[wait] " },
+    disabled: { glyph: "○", paint: style.dim, plain: "[off]  " },
+    error: { glyph: "✗", paint: style.red, plain: "[error]" },
+};
+/**
+ * Render a status badge as a fixed-width prefix (badge + trailing space). With
+ * color on it is a green/yellow/dim/red glyph; with color off it falls back to
+ * an equal-width ASCII tag so columns still line up in plain output.
+ */
+export function badge(status) {
+    const spec = BADGES[status];
+    return colorEnabled ? `${spec.paint(spec.glyph)} ` : `${spec.plain} `;
+}
+/**
+ * Render aligned `label  value` rows: labels are padded to the widest label so
+ * values line up, replacing the hand-tuned `padEnd` blocks. `indent` prefixes
+ * every row with that many spaces (used to nest rows under a section rule).
+ * Returns one string with a trailing newline per row (empty when there are no
+ * rows).
+ */
+export function keyValue(rows, indent = 0) {
+    if (rows.length === 0) {
+        return "";
+    }
+    const pad = " ".repeat(indent);
+    const width = rows.reduce((max, [label]) => Math.max(max, label.length), 0);
+    return rows
+        .map(([label, value]) => `${pad}${style.gray(label.padEnd(width))}  ${value}\n`)
+        .join("");
+}
+const RULE_FALLBACK_WIDTH = 44;
+const RULE_MAX_WIDTH = 72;
+/**
+ * A horizontal section divider, optionally labeled — `── instance ────────`.
+ * Width tracks the terminal (read at call time so resizes are honored), capped
+ * for readability and falling back to a fixed width when stdout is not a TTY.
+ * Rendered dim/gray (identity when color is off); the label appears verbatim so
+ * it stays greppable. Always ends with a newline.
+ */
+export function rule(label) {
+    const width = Math.min(process.stdout.columns ?? RULE_FALLBACK_WIDTH, RULE_MAX_WIDTH);
+    if (label === undefined) {
+        return `${style.gray("─".repeat(width))}\n`;
+    }
+    const prefix = `── ${label} `;
+    const fill = Math.max(0, width - prefix.length);
+    return `${style.gray(`${prefix}${"─".repeat(fill)}`)}\n`;
+}
+/** Badge for a channel status *kind* string (running/waiting…/disabled/error). */
+export function channelBadge(kind) {
+    if (kind === "running") {
+        return badge("ok");
+    }
+    if (kind.startsWith("waiting")) {
+        return badge("waiting");
+    }
+    if (kind === "disabled") {
+        return badge("disabled");
+    }
+    if (kind === "degraded") {
+        // Still serving, transport self-recovering — a warning, not an error.
+        return badge("waiting");
+    }
+    if (/error|fail|crash/u.test(kind)) {
+        return badge("error");
+    }
+    return badge("waiting");
+}
+/** Badge for a trace-source health word (running/stale/stopped/…). */
+export function healthBadge(health) {
+    switch (health) {
+        case "running":
+            return badge("ok");
+        case "stale":
+            return badge("waiting");
+        case "stopped":
+            return badge("disabled");
+        default:
+            return badge("error");
+    }
+}
+/** A bold/cyan section heading with a trailing newline. */
+export function heading(text) {
+    return `${style.bold(style.cyan(text))}\n`;
+}
+/** The CLI title block: bold title plus an optional dim subtitle. */
+export function banner(title, subtitle) {
+    const head = style.bold(style.cyan(title));
+    return subtitle === undefined ? `${head}\n` : `${head} ${style.dim(`— ${subtitle}`)}\n`;
+}
+/** A red error line (✗ prefix) with a trailing newline — write to stderr. */
+export function errorLine(message) {
+    return `${style.red(`✗ ${message}`)}\n`;
+}
+/** A dim hint line (→ prefix) with a trailing newline. */
+export function hint(message) {
+    return `${style.dim(`→ ${message}`)}\n`;
+}
+//# sourceMappingURL=ui.js.map

package/dist/ui.js.map

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