@johnowennixon/diffdash 1.0.3 → 1.2.1

package/dist/src/lib_llm_chat.js

@@ -0,0 +1,66 @@
+import { generateObject, generateText } from "ai";
+import { debug_channels, debug_inspect_when } from "./lib_debug.js";
+import { env_get_empty, env_get_substitute } from "./lib_env.js";
+import { llm_provider_get_ai_sdk_language_model } from "./lib_llm_provider.js";
+import { parse_float_or_undefined, parse_int, parse_int_or_undefined } from "./lib_parse_number.js";
+function llm_chat_get_parameters() {
+    return {
+        max_tokens: parse_int_or_undefined(env_get_empty("lib_llm_chat_max_tokens")),
+        temperature: parse_float_or_undefined(env_get_substitute("lib_llm_chat_temperature", "0.6")),
+        timeout: parse_int(env_get_substitute("lib_llm_chat_timeout", "60")),
+    };
+}
+export async function llm_chat_generate_text({ llm_config, headers, system_prompt, user_prompt, tools, max_steps, min_steps, }) {
+    const { llm_model_name, llm_provider, llm_model_code, llm_api_key } = llm_config;
+    const ai_sdk_language_model = llm_provider_get_ai_sdk_language_model({
+        llm_model_code,
+        llm_provider,
+        llm_api_key,
+    });
+    const { max_tokens, temperature, timeout } = llm_chat_get_parameters();
+    const llm_inputs = {
+        model: ai_sdk_language_model,
+        system: system_prompt,
+        prompt: user_prompt,
+        tools,
+        headers,
+        maxSteps: max_steps,
+        maxTokens: max_tokens,
+        temperature,
+        abortSignal: AbortSignal.timeout(timeout * 1000),
+    };
+    debug_inspect_when(debug_channels.llm_inputs, llm_inputs, `llm_inputs (for ${llm_model_name})`);
+    // This is liable to throw an error
+    const llm_outputs = await generateText(llm_inputs);
+    debug_inspect_when(debug_channels.llm_outputs, llm_outputs, `llm_outputs (for ${llm_model_name})`);
+    if (min_steps !== undefined && llm_outputs.steps.length < min_steps) {
+        throw new Error("Too few steps taken");
+    }
+    if (max_steps !== undefined && llm_outputs.steps.length === max_steps) {
+        throw new Error("Too many steps taken");
+    }
+    return llm_outputs.text;
+}
+export async function llm_chat_generate_object({ llm_config, user_prompt, system_prompt, schema, }) {
+    const { llm_model_name, llm_provider, llm_model_code, llm_api_key } = llm_config;
+    const ai_sdk_language_model = llm_provider_get_ai_sdk_language_model({
+        llm_model_code,
+        llm_provider,
+        llm_api_key,
+    });
+    const { max_tokens, temperature, timeout } = llm_chat_get_parameters();
+    const llm_inputs = {
+        model: ai_sdk_language_model,
+        system: system_prompt,
+        prompt: user_prompt,
+        schema,
+        maxTokens: max_tokens,
+        temperature,
+        abortSignal: AbortSignal.timeout(timeout * 1000),
+    };
+    debug_inspect_when(debug_channels.llm_inputs, llm_inputs, `llm_inputs (for ${llm_model_name})`);
+    // This is liable to throw an error
+    const llm_outputs = await generateObject(llm_inputs);
+    debug_inspect_when(debug_channels.llm_outputs, llm_outputs, `llm_outputs (for ${llm_model_name})`);
+    return llm_outputs.object;
+}

package/dist/src/lib_llm_config.js

@@ -0,0 +1,23 @@
+import { llm_access_available, llm_access_get } from "./lib_llm_access.js";
+import { llm_model_find_detail, llm_model_get_choices } from "./lib_llm_model.js";
+import { llm_provider_get_via } from "./lib_llm_provider.js";
+import { tell_info } from "./lib_tell.js";
+export function llm_config_get({ llm_model_details, llm_model_name, llm_router, }) {
+    const llm_model_detail = llm_model_find_detail({ llm_model_details, llm_model_name });
+    const access = llm_access_get({ llm_model_details, llm_model_name, llm_router });
+    const { llm_model_code, llm_provider, llm_api_key } = access;
+    return { llm_model_name, llm_model_detail, llm_model_code, llm_provider, llm_api_key };
+}
+export function llm_config_get_all({ llm_model_details, llm_router, llm_excludes, }) {
+    const choices = llm_model_get_choices(llm_model_details);
+    const available = choices.filter((llm_model_name) => llm_access_available({ llm_model_details, llm_model_name, llm_excludes }));
+    return available.map((llm_model_name) => llm_config_get({ llm_model_details, llm_model_name, llm_router }));
+}
+export function llm_config_get_model_via(llm_config) {
+    const { llm_model_name, llm_provider } = llm_config;
+    return `${llm_model_name} (${llm_provider_get_via(llm_provider)})`;
+}
+export function llm_config_show(llm_config) {
+    const model_via = llm_config_get_model_via(llm_config);
+    tell_info(`Using LLM ${model_via}`);
+}

package/dist/src/lib_llm_list.js

@@ -0,0 +1,21 @@
+import { DOLLAR } from "./lib_char_punctuation.js";
+import { stdio_write_stdout_linefeed } from "./lib_stdio_write.js";
+import { tell_info, tell_warning } from "./lib_tell.js";
+import { tui_justify_right } from "./lib_tui_justify.js";
+import { TuiTable } from "./lib_tui_table.js";
+export function llm_list_models({ llm_model_details }) {
+    const headings = ["NAME", "CONTEXT", "INPUT", "OUTPUT"];
+    const table = new TuiTable({ headings });
+    for (const detail of llm_model_details) {
+        const { llm_model_name, context_window, cents_input, cents_output } = detail;
+        const tui_name = llm_model_name;
+        const tui_context = tui_justify_right(7, context_window.toString());
+        const tui_input = tui_justify_right(6, DOLLAR + (cents_input / 100).toFixed(2));
+        const tui_output = tui_justify_right(6, DOLLAR + (cents_output / 100).toFixed(2));
+        const row = [tui_name, tui_context, tui_input, tui_output];
+        table.push(row);
+    }
+    stdio_write_stdout_linefeed(table.toString());
+    tell_info("Prices are per million tokens.");
+    tell_warning("Prices are best effort and are liable to change - always double-check with your LLM provider.");
+}

package/dist/src/lib_llm_model.js

@@ -0,0 +1,336 @@
+import { abort_with_error } from "./lib_abort.js";
+const LLM_MODEL_DETAILS = [
+    {
+        llm_model_name: "claude-3.5-haiku",
+        llm_provider: "anthropic",
+        llm_model_code_direct: "claude-3-5-haiku-latest",
+        llm_model_code_requesty: "anthropic/claude-3-5-haiku-latest",
+        llm_model_code_openrouter: "anthropic/claude-3.5-haiku",
+        context_window: 200_000,
+        cents_input: 80,
+        cents_output: 400,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "claude-3.7-sonnet",
+        llm_provider: "anthropic",
+        llm_model_code_direct: "claude-3-7-sonnet-20250219",
+        llm_model_code_requesty: "anthropic/claude-3-7-sonnet-latest",
+        llm_model_code_openrouter: "anthropic/claude-3.7-sonnet",
+        context_window: 200_000,
+        cents_input: 300,
+        cents_output: 1500,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "claude-sonnet-4",
+        llm_provider: "anthropic",
+        llm_model_code_direct: "claude-sonnet-4-0",
+        llm_model_code_requesty: "anthropic/claude-sonnet-4-20250514",
+        llm_model_code_openrouter: "anthropic/claude-sonnet-4",
+        context_window: 200_000,
+        cents_input: 300,
+        cents_output: 1500,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "codex-mini",
+        llm_provider: "openai",
+        llm_model_code_direct: "codex-mini-latest",
+        llm_model_code_requesty: null,
+        llm_model_code_openrouter: "openai/codex-mini",
+        context_window: 200_000,
+        cents_input: 150,
+        cents_output: 600,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "deepseek-v3",
+        llm_provider: "deepseek",
+        llm_model_code_direct: "deepseek-chat",
+        llm_model_code_requesty: "novita/deepseek/deepseek-v3-0324",
+        llm_model_code_openrouter: "deepseek/deepseek-chat-v3-0324",
+        context_window: 64_000,
+        cents_input: 27,
+        cents_output: 110,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "deepseek-r1",
+        llm_provider: "deepseek",
+        llm_model_code_direct: "deepseek-reasoner",
+        llm_model_code_requesty: "netmind/deepseek-ai/DeepSeek-R1-0528",
+        llm_model_code_openrouter: "deepseek/deepseek-r1-0528",
+        context_window: 163_840,
+        cents_input: 55,
+        cents_output: 219,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "devstral-small",
+        llm_provider: null,
+        llm_model_code_direct: null,
+        llm_model_code_requesty: "mistral/devstral-small-latest",
+        llm_model_code_openrouter: "mistralai/devstral-small",
+        context_window: 128_000,
+        cents_input: 7,
+        cents_output: 10,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "ernie-4.5-300b",
+        llm_provider: null,
+        llm_model_code_direct: null,
+        llm_model_code_requesty: null,
+        llm_model_code_openrouter: "baidu/ernie-4.5-300b-a47b",
+        context_window: 123_000,
+        cents_input: 30,
+        cents_output: 100,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "gemini-2.0-flash",
+        llm_provider: "google",
+        llm_model_code_direct: "gemini-2.0-flash",
+        llm_model_code_requesty: "google/gemini-2.0-flash-001",
+        llm_model_code_openrouter: "google/gemini-2.0-flash-001",
+        context_window: 1_048_576,
+        cents_input: 10,
+        cents_output: 40,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "gemini-2.5-flash",
+        llm_provider: "google",
+        llm_model_code_direct: "gemini-2.5-flash",
+        llm_model_code_requesty: "google/gemini-2.5-flash",
+        llm_model_code_openrouter: "google/gemini-2.5-flash",
+        context_window: 1_048_576,
+        cents_input: 30,
+        cents_output: 250,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "gemini-2.5-pro",
+        llm_provider: "google",
+        llm_model_code_direct: "gemini-2.5-pro",
+        llm_model_code_requesty: "google/gemini-2.5-pro",
+        llm_model_code_openrouter: "google/gemini-2.5-pro",
+        context_window: 1_048_576,
+        cents_input: 125,
+        cents_output: 1000,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "glm-4-32b",
+        llm_provider: null,
+        llm_model_code_direct: null,
+        llm_model_code_requesty: null,
+        llm_model_code_openrouter: "thudm/glm-4-32b",
+        context_window: 32_000,
+        cents_input: 24,
+        cents_output: 24,
+        has_structured_json: false,
+    },
+    {
+        llm_model_name: "gpt-4.1",
+        llm_provider: "openai",
+        llm_model_code_direct: "gpt-4.1",
+        llm_model_code_requesty: "openai/gpt-4.1",
+        llm_model_code_openrouter: "openai/gpt-4.1",
+        context_window: 1_047_576,
+        cents_input: 200,
+        cents_output: 800,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "gpt-4.1-mini",
+        llm_provider: "openai",
+        llm_model_code_direct: "gpt-4.1-mini",
+        llm_model_code_requesty: "openai/gpt-4.1-mini",
+        llm_model_code_openrouter: "openai/gpt-4.1-mini",
+        context_window: 1_047_576,
+        cents_input: 40,
+        cents_output: 160,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "gpt-4.1-nano",
+        llm_provider: "openai",
+        llm_model_code_direct: "gpt-4.1-nano",
+        llm_model_code_requesty: "openai/gpt-4.1-nano",
+        llm_model_code_openrouter: "openai/gpt-4.1-nano",
+        context_window: 1_047_576,
+        cents_input: 10,
+        cents_output: 40,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "gpt-4o",
+        llm_provider: "openai",
+        llm_model_code_direct: "gpt-4o-2024-11-20",
+        llm_model_code_requesty: "openai/gpt-4o-2024-11-20",
+        llm_model_code_openrouter: "openai/gpt-4o-2024-11-20",
+        context_window: 128_000,
+        cents_input: 250,
+        cents_output: 1000,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "gpt-4o-mini",
+        llm_provider: "openai",
+        llm_model_code_direct: "gpt-4o-mini",
+        llm_model_code_requesty: "openai/gpt-4o-mini-2024-07-18",
+        llm_model_code_openrouter: "openai/gpt-4o-mini-2024-07-18",
+        context_window: 128_000,
+        cents_input: 15,
+        cents_output: 60,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "grok-3",
+        llm_provider: null,
+        llm_model_code_direct: "grok-3",
+        llm_model_code_requesty: "xai/grok-3-beta",
+        llm_model_code_openrouter: "x-ai/grok-3-beta",
+        context_window: 131_072,
+        cents_input: 300,
+        cents_output: 1500,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "grok-3-mini",
+        llm_provider: null,
+        llm_model_code_direct: "grok-3-mini",
+        llm_model_code_requesty: "xai/grok-3-mini-beta",
+        llm_model_code_openrouter: "x-ai/grok-3-mini-beta",
+        context_window: 131_072,
+        cents_input: 30,
+        cents_output: 50,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "llama-4-maverick",
+        llm_provider: null,
+        llm_model_code_direct: null,
+        llm_model_code_requesty: "parasail/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8",
+        llm_model_code_openrouter: "meta-llama/llama-4-maverick",
+        context_window: 1_048_576,
+        cents_input: 21,
+        cents_output: 85,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "llama-4-scout",
+        llm_provider: null,
+        llm_model_code_direct: null,
+        llm_model_code_requesty: "parasail/meta-llama/Llama-4-Scout-17B-16E-Instruct",
+        llm_model_code_openrouter: "meta-llama/llama-4-scout",
+        context_window: 1_048_576,
+        cents_input: 14,
+        cents_output: 58,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "mercury-coder-small",
+        llm_provider: null,
+        llm_model_code_direct: null,
+        llm_model_code_requesty: null,
+        llm_model_code_openrouter: "inception/mercury-coder-small-beta",
+        context_window: 32_000,
+        cents_input: 25,
+        cents_output: 100,
+        has_structured_json: false,
+    },
+    {
+        llm_model_name: "mistral-medium-3",
+        llm_provider: null,
+        llm_model_code_direct: null,
+        llm_model_code_requesty: null,
+        llm_model_code_openrouter: "mistralai/mistral-medium-3",
+        context_window: 131_072,
+        cents_input: 40,
+        cents_output: 200,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "o3",
+        llm_provider: "openai",
+        llm_model_code_direct: "o3-2025-04-16",
+        llm_model_code_requesty: "openai/o3-2025-04-16",
+        llm_model_code_openrouter: "openai/o3-2025-04-16",
+        context_window: 200_000,
+        cents_input: 200,
+        cents_output: 800,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "o3-pro",
+        llm_provider: "openai",
+        llm_model_code_direct: "o3-pro",
+        llm_model_code_requesty: "openai/o3-pro",
+        llm_model_code_openrouter: "openai/o3-pro",
+        context_window: 200_000,
+        cents_input: 2000,
+        cents_output: 8000,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "o4-mini",
+        llm_provider: "openai",
+        llm_model_code_direct: "o4-mini-2025-04-16",
+        llm_model_code_requesty: "openai/o4-mini-2025-04-16",
+        llm_model_code_openrouter: "openai/o4-mini-2025-04-16",
+        context_window: 200_000,
+        cents_input: 110,
+        cents_output: 440,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "qwen3-30b-a3b",
+        llm_provider: null,
+        llm_model_code_direct: null,
+        llm_model_code_requesty: null,
+        llm_model_code_openrouter: "qwen/qwen3-30b-a3b",
+        context_window: 40_000,
+        cents_input: 8,
+        cents_output: 29,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "qwen3-32b",
+        llm_provider: null,
+        llm_model_code_direct: null,
+        llm_model_code_requesty: "deepinfra/Qwen/Qwen3-32B",
+        llm_model_code_openrouter: "qwen/qwen3-32b",
+        context_window: 40_000,
+        cents_input: 10,
+        cents_output: 30,
+        has_structured_json: true,
+    },
+    {
+        llm_model_name: "qwen3-235b-a22b",
+        llm_provider: null,
+        llm_model_code_direct: null,
+        llm_model_code_requesty: "deepinfra/Qwen/Qwen3-235B-A22B",
+        llm_model_code_openrouter: "qwen/qwen3-235b-a22b",
+        context_window: 40_000,
+        cents_input: 20,
+        cents_output: 60,
+        has_structured_json: true,
+    },
+];
+export function llm_model_get_details({ llm_model_names, }) {
+    return LLM_MODEL_DETAILS.filter((detail) => llm_model_names.includes(detail.llm_model_name));
+}
+export function llm_model_get_choices(llm_model_details) {
+    return llm_model_details.map((model) => model.llm_model_name);
+}
+export function llm_model_find_detail({ llm_model_details, llm_model_name, }) {
+    for (const detail of llm_model_details) {
+        if (detail.llm_model_name === llm_model_name) {
+            return detail;
+        }
+    }
+    abort_with_error(`Unknown model: ${llm_model_name}`);
+}

package/dist/src/lib_llm_provider.js

@@ -0,0 +1,63 @@
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createDeepSeek } from "@ai-sdk/deepseek";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import { createRequesty } from "@requesty/ai-sdk";
+import { abort_with_error } from "./lib_abort.js";
+import { env_get } from "./lib_env.js";
+export function llm_provider_get_via(llm_provider) {
+    switch (llm_provider) {
+        case "anthropic":
+        case "deepseek":
+        case "google":
+        case "openai":
+            return "direct";
+        case "requesty":
+            return "via Requesty";
+        case "openrouter":
+            return "via OpenRouter";
+        default:
+            abort_with_error("Unknown LLM provider");
+    }
+}
+export function llm_provider_get_api_key_env(llm_provider) {
+    switch (llm_provider) {
+        case "anthropic":
+            return "ANTHROPIC_API_KEY";
+        case "deepseek":
+            return "DEEPSEEK_API_KEY";
+        case "google":
+            return "GEMINI_API_KEY";
+        case "openai":
+            return "OPENAI_API_KEY";
+        case "requesty":
+            return "REQUESTY_API_KEY";
+        case "openrouter":
+            return "OPENROUTER_API_KEY";
+        default:
+            abort_with_error("Unknown LLM provider");
+    }
+}
+export function llm_provider_get_api_key(llm_provider) {
+    const env = llm_provider_get_api_key_env(llm_provider);
+    return env_get(env);
+}
+export function llm_provider_get_ai_sdk_language_model({ llm_model_code, llm_provider, llm_api_key, }) {
+    switch (llm_provider) {
+        case "anthropic":
+            return createAnthropic({ apiKey: llm_api_key })(llm_model_code);
+        case "deepseek":
+            return createDeepSeek({ apiKey: llm_api_key })(llm_model_code);
+        case "google":
+            return createGoogleGenerativeAI({ apiKey: llm_api_key })(llm_model_code);
+        case "openai":
+            return createOpenAI({ apiKey: llm_api_key })(llm_model_code);
+        case "requesty":
+            return createRequesty({ apiKey: llm_api_key })(llm_model_code);
+        case "openrouter":
+            return createOpenRouter({ apiKey: llm_api_key })(llm_model_code);
+        default:
+            abort_with_error("Unknown LLM provider");
+    }
+}

package/dist/src/lib_llm_tokens.js

@@ -0,0 +1,14 @@
+import { debug_channels } from "./lib_debug.js";
+import { tell_debug } from "./lib_tell.js";
+export function llm_tokens_count_estimated({ text }) {
+    return Math.round(text.length / 3);
+}
+export function llm_tokens_debug_usage({ name, llm_config, text, }) {
+    if (debug_channels.llm_tokens) {
+        const { llm_model_name } = llm_config;
+        const length = text.length;
+        const tokens = llm_tokens_count_estimated({ llm_config, text });
+        const ratio = Math.round((length / tokens) * 100) / 100;
+        tell_debug(`${name}: length=${length}, tokens=${tokens}, ratio=${ratio}, model=${llm_model_name}`);
+    }
+}

package/dist/src/lib_package.js

@@ -0,0 +1,7 @@
+import package_json from "../package.json" with { type: "json" };
+import { EMPTY } from "./lib_char_empty.js";
+function remove_npmjs_scope(name) {
+    return name.replace(/^@[^/]+\//, EMPTY);
+}
+export const PACKAGE_NAME = remove_npmjs_scope(package_json.name);
+export const PACKAGE_VERSION = package_json.version;

package/dist/src/lib_parse_number.js

@@ -0,0 +1,13 @@
+import { EMPTY } from "./lib_char_empty.js";
+export function parse_int(input) {
+    return Number.parseInt(input, 10);
+}
+export function parse_float(input) {
+    return Number.parseFloat(input);
+}
+export function parse_int_or_undefined(input) {
+    return input === undefined || input === EMPTY ? undefined : parse_int(input);
+}
+export function parse_float_or_undefined(input) {
+    return input === undefined || input === EMPTY ? undefined : parse_float(input);
+}

package/dist/src/lib_stdio_write.js

@@ -0,0 +1,14 @@
+import { writeSync } from "node:fs";
+import { LF } from "./lib_char_control.js";
+export function stdio_write_stdout(message) {
+    writeSync(1, message);
+}
+export function stdio_write_stdout_linefeed(message) {
+    stdio_write_stdout(message + LF);
+}
+export function stdio_write_stderr(message) {
+    writeSync(2, message);
+}
+export function stdio_write_stderr_linefeed(message) {
+    stdio_write_stderr(message + LF);
+}

package/dist/src/lib_string_types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/lib_tell.js

@@ -0,0 +1,58 @@
+import { ansi_cyan, ansi_green, ansi_grey, ansi_magenta, ansi_normal, ansi_red, ansi_yellow } from "./lib_ansi.js";
+import { LF } from "./lib_char_control.js";
+import { EMPTY } from "./lib_char_empty.js";
+import { SPACE } from "./lib_char_punctuation.js";
+import { datetime_format_local_iso_ymdthms, datetime_now } from "./lib_datetime.js";
+import { enabled_from_env } from "./lib_enabled.js";
+import { stdio_write_stderr_linefeed } from "./lib_stdio_write.js";
+export const tell_enables = {
+    timestamp: enabled_from_env("TELL_TIMESTAMP"),
+    okay: enabled_from_env("TELL_OKAY", { default: true }),
+};
+function tell_generic({ message, colourizer }) {
+    while (message.endsWith(LF)) {
+        message = message.slice(0, -1);
+    }
+    let text = EMPTY;
+    if (tell_enables.timestamp) {
+        const now_local_ymdthms = datetime_format_local_iso_ymdthms(datetime_now());
+        text += ansi_grey(now_local_ymdthms);
+        text += SPACE;
+    }
+    if (colourizer) {
+        text += colourizer(message);
+    }
+    stdio_write_stderr_linefeed(text);
+}
+export function tell_nowhere(_message) {
+    // intentionally empty
+}
+export function tell_plain(message) {
+    tell_generic({ message, colourizer: ansi_normal });
+}
+export function tell_error(message) {
+    tell_generic({ message, colourizer: ansi_red });
+}
+export function tell_warning(message) {
+    tell_generic({ message, colourizer: ansi_yellow });
+}
+export function tell_success(message) {
+    tell_generic({ message, colourizer: ansi_green });
+}
+export function tell_info(message) {
+    tell_generic({ message, colourizer: ansi_cyan });
+}
+export function tell_action(message) {
+    tell_generic({ message, colourizer: ansi_magenta });
+}
+export function tell_debug(message) {
+    tell_generic({ message, colourizer: ansi_grey });
+}
+export function tell_blank() {
+    tell_plain(EMPTY);
+}
+export function tell_okay() {
+    if (tell_enables.okay) {
+        tell_success("Okay");
+    }
+}

package/dist/src/lib_tui_block.js

@@ -0,0 +1,10 @@
+import { BOX_DRAWINGS_LIGHT_HORIZONTAL } from "./lib_char_box.js";
+import { SPACE } from "./lib_char_punctuation.js";
+import { tui_justify_centre } from "./lib_tui_justify.js";
+export function tui_block_string({ teller, content, title, pad_char = BOX_DRAWINGS_LIGHT_HORIZONTAL, width = 120, }) {
+    const separator = pad_char.repeat(width);
+    const top_line = title ? tui_justify_centre({ line: SPACE + title + SPACE, width, pad_char }) : separator;
+    teller(top_line);
+    teller(content);
+    teller(separator);
+}

package/dist/src/lib_tui_justify.js

@@ -0,0 +1,29 @@
+import { DIGIT_0 } from "./lib_char_digit.js";
+import { SPACE } from "./lib_char_punctuation.js";
+import { tui_truncate_ellipsis, tui_truncate_plain } from "./lib_tui_truncate.js";
+export function tui_justify_left(n, s, ellipsis = false, truncate = false) {
+    let justified = s;
+    if (ellipsis) {
+        justified = tui_truncate_ellipsis(n, justified);
+    }
+    if (truncate) {
+        justified = tui_truncate_plain(n, justified);
+    }
+    justified = justified.padEnd(n);
+    return justified;
+}
+export function tui_justify_right(n, s) {
+    return s.padStart(n);
+}
+export function tui_justify_centre({ line, width, pad_char = SPACE, }) {
+    if (line.length >= width) {
+        return line;
+    }
+    const total_pad = width - line.length;
+    const left_pad = Math.floor(total_pad / 2);
+    const right_pad = total_pad - left_pad;
+    return pad_char.repeat(left_pad) + line + pad_char.repeat(right_pad);
+}
+export function tui_justify_zero(n, s) {
+    return s.padStart(n, DIGIT_0);
+}