@zq-silk/yui 0.0.0

package/dist/input/inputRequest.js

@@ -0,0 +1,326 @@
+export class InputRequestStateError extends Error {
+    requestId;
+    status;
+    constructor(requestId, status) {
+        super(`Input request ${requestId} is already ${status}.`);
+        this.requestId = requestId;
+        this.status = status;
+        this.name = "InputRequestStateError";
+    }
+}
+const CHOICE_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export function createInputRequest(id, taskId, requester, input, now) {
+    const timestamp = requireDate(now, "Input request creation time");
+    const choices = normalizeChoices(input.choices);
+    return validateInputRequest({
+        schemaVersion: 1,
+        id: requireIdentity(id, "Input request id"),
+        taskId: requireIdentity(taskId, "Input request Task id"),
+        requester: normalizeRequester(requester),
+        question: requireText(input.question, "Input request question"),
+        choices,
+        blockedRefs: normalizeBlockedRefs(input.blockedRefs),
+        policy: normalizePolicy(input.policy, choices, timestamp),
+        status: "open",
+        createdAt: timestamp,
+        updatedAt: timestamp
+    });
+}
+export function answerInputRequest(request, answer, answeredBy, now) {
+    validateInputRequest(request);
+    assertOpen(request);
+    if (answeredBy !== "user" && answeredBy !== "operator" && answeredBy !== "agent-timeout") {
+        throw new Error("Input answerer must be user, operator, or agent-timeout.");
+    }
+    const answeredAt = transitionTime(request, now);
+    const normalizedAnswer = normalizeAnswer(request, answer);
+    if (answeredBy === "agent-timeout") {
+        assertAgentTimeoutAnswer(request, normalizedAnswer, answeredAt);
+    }
+    return validateInputRequest({
+        ...request,
+        status: "answered",
+        resolution: {
+            answer: normalizedAnswer,
+            answeredBy,
+            answeredAt
+        },
+        updatedAt: answeredAt
+    });
+}
+export function cancelInputRequest(request, reason, now) {
+    validateInputRequest(request);
+    assertOpen(request);
+    const cancelledAt = transitionTime(request, now);
+    return validateInputRequest({
+        ...request,
+        status: "cancelled",
+        cancellation: {
+            reason: requireText(reason, "Input cancellation reason"),
+            cancelledAt
+        },
+        updatedAt: cancelledAt
+    });
+}
+export function validateInputRequest(value) {
+    const request = record(value, "Input request");
+    const terminalField = request.status === "answered"
+        ? ["resolution"]
+        : request.status === "cancelled" ? ["cancellation"] : [];
+    exact(request, [
+        "schemaVersion", "id", "taskId", "requester", "question", "choices",
+        "blockedRefs", "policy", "status", "createdAt", "updatedAt", ...terminalField
+    ], "Input request");
+    if (request.schemaVersion !== 1)
+        throw new Error("Input request must use schemaVersion 1.");
+    const choices = validateChoices(request.choices);
+    const createdAt = requireTimestamp(request.createdAt, "Input request createdAt");
+    const base = {
+        schemaVersion: 1,
+        id: requireIdentity(request.id, "Input request id"),
+        taskId: requireIdentity(request.taskId, "Input request Task id"),
+        requester: normalizeRequester(request.requester),
+        question: requireNormalizedText(request.question, "Input request question"),
+        choices,
+        blockedRefs: validateBlockedRefs(request.blockedRefs),
+        policy: normalizePolicy(request.policy, choices, createdAt),
+        createdAt,
+        updatedAt: requireTimestamp(request.updatedAt, "Input request updatedAt")
+    };
+    if (Date.parse(base.updatedAt) < Date.parse(base.createdAt)) {
+        throw new Error("Input request updatedAt cannot precede createdAt.");
+    }
+    if (request.status === "open")
+        return { ...base, status: "open" };
+    if (request.status === "answered") {
+        const resolution = record(request.resolution, "Input resolution");
+        exact(resolution, ["answer", "answeredBy", "answeredAt"], "Input resolution");
+        const answer = validatePersistedAnswer(base.choices, resolution.answer);
+        if (resolution.answeredBy !== "user"
+            && resolution.answeredBy !== "operator"
+            && resolution.answeredBy !== "agent-timeout") {
+            throw new Error("Input resolution answerer must be user, operator, or agent-timeout.");
+        }
+        const answeredAt = requireTimestamp(resolution.answeredAt, "Input resolution answeredAt");
+        if (answeredAt !== base.updatedAt)
+            throw new Error("Input resolution answeredAt must match updatedAt.");
+        if (resolution.answeredBy === "agent-timeout") {
+            assertAgentTimeoutAnswer(base, answer, answeredAt);
+        }
+        return {
+            ...base,
+            status: "answered",
+            resolution: {
+                answer,
+                answeredBy: resolution.answeredBy,
+                answeredAt
+            }
+        };
+    }
+    if (request.status === "cancelled") {
+        const cancellation = record(request.cancellation, "Input cancellation");
+        exact(cancellation, ["reason", "cancelledAt"], "Input cancellation");
+        const cancelledAt = requireTimestamp(cancellation.cancelledAt, "Input cancellation cancelledAt");
+        if (cancelledAt !== base.updatedAt)
+            throw new Error("Input cancellation cancelledAt must match updatedAt.");
+        return {
+            ...base,
+            status: "cancelled",
+            cancellation: {
+                reason: requireNormalizedText(cancellation.reason, "Input cancellation reason"),
+                cancelledAt
+            }
+        };
+    }
+    throw new Error(`Input request status is invalid: ${String(request.status)}.`);
+}
+function normalizeChoices(value) {
+    if (!Array.isArray(value))
+        throw new Error("Input choices must be an array.");
+    const choices = value.map((choice) => {
+        const item = record(choice, "Input choice");
+        exact(item, ["key", "label"], "Input choice");
+        return {
+            key: requireChoiceKey(item.key),
+            label: requireText(item.label, "Input choice label")
+        };
+    });
+    if (new Set(choices.map(({ key }) => key)).size !== choices.length) {
+        throw new Error("Input choice keys must be unique.");
+    }
+    return choices;
+}
+function validateChoices(value) {
+    const choices = normalizeChoices(value);
+    if (JSON.stringify(choices) !== JSON.stringify(value))
+        throw new Error("Input choices must be normalized.");
+    return choices;
+}
+function normalizeBlockedRefs(value) {
+    if (!Array.isArray(value))
+        throw new Error("Input blocked references must be an array.");
+    const references = value.map((reference) => {
+        const item = record(reference, "Input blocked reference");
+        exact(item, ["type", "id"], "Input blocked reference");
+        if (item.type !== "work-item" && item.type !== "run") {
+            throw new Error("Input blocked reference type must be work-item or run.");
+        }
+        return { type: item.type, id: requireIdentity(item.id, "Input blocked reference id") };
+    });
+    const keys = references.map(({ type, id }) => `${type}:${id}`);
+    if (new Set(keys).size !== keys.length)
+        throw new Error("Input blocked references must be unique.");
+    return references;
+}
+function normalizePolicy(value, choices, createdAt) {
+    if (value === undefined)
+        return { kind: "required" };
+    const policy = record(value, "Input request policy");
+    if (policy.kind === "required") {
+        exact(policy, ["kind"], "Input request policy");
+        return { kind: "required" };
+    }
+    if (policy.kind !== "recommended") {
+        throw new Error("Input request policy kind is invalid.");
+    }
+    exact(policy, ["kind", "recommendedChoiceKey", "timeoutAt"], "Input request policy");
+    if (choices.length === 0) {
+        throw new Error("Recommended input request requires choices.");
+    }
+    const recommendedChoiceKey = requireChoiceKey(policy.recommendedChoiceKey);
+    if (!choices.some((choice) => choice.key === recommendedChoiceKey)) {
+        throw new Error(`Recommended input choice does not exist: ${recommendedChoiceKey}.`);
+    }
+    const timeoutAt = requireTimestamp(policy.timeoutAt, "Input request timeoutAt");
+    if (Date.parse(timeoutAt) <= Date.parse(createdAt)) {
+        throw new Error("Input request timeoutAt must be after creation.");
+    }
+    return { kind: "recommended", recommendedChoiceKey, timeoutAt };
+}
+function validateBlockedRefs(value) {
+    const references = normalizeBlockedRefs(value);
+    if (JSON.stringify(references) !== JSON.stringify(value)) {
+        throw new Error("Input blocked references must be normalized.");
+    }
+    return references;
+}
+function normalizeRequester(value) {
+    const requester = record(value, "Input requester");
+    exact(requester, requester.nativeSessionId === undefined
+        ? ["roleName", "agentId", "runId"]
+        : ["roleName", "agentId", "runId", "nativeSessionId"], "Input requester");
+    if (requester.roleName !== "leader")
+        throw new Error("Input requester must be the Task Leader.");
+    return {
+        roleName: "leader",
+        agentId: requireIdentity(requester.agentId, "Input requester Agent id"),
+        runId: requireIdentity(requester.runId, "Input requester Run id"),
+        ...(requester.nativeSessionId === undefined
+            ? {}
+            : { nativeSessionId: requireIdentity(requester.nativeSessionId, "Input requester native session id") })
+    };
+}
+function normalizeAnswer(request, answer) {
+    const value = record(answer, "Input answer");
+    if (request.choices.length === 0) {
+        if (value.choiceKey !== undefined)
+            throw new Error("Free-text input request does not accept a choice.");
+        exact(value, ["text"], "Input answer");
+        return { text: requireText(value.text, "Input answer") };
+    }
+    exact(value, ["choiceKey"], "Input answer");
+    const key = requireChoiceKey(value.choiceKey);
+    const choice = request.choices.find((candidate) => candidate.key === key);
+    if (choice === undefined)
+        throw new Error(`Input answer choice does not exist: ${key}.`);
+    return { choiceKey: choice.key, text: choice.label };
+}
+function assertAgentTimeoutAnswer(request, answer, answeredAt) {
+    if (request.policy.kind !== "recommended") {
+        throw new Error("Required input request cannot be answered by Agent timeout.");
+    }
+    if (Date.parse(answeredAt) < Date.parse(request.policy.timeoutAt)) {
+        throw new Error("Input request has not reached its timeout.");
+    }
+    if (answer.choiceKey !== request.policy.recommendedChoiceKey) {
+        throw new Error("Agent timeout must use the recommended choice.");
+    }
+}
+function assertOpen(request) {
+    if (request.status !== "open")
+        throw new InputRequestStateError(request.id, request.status);
+}
+function transitionTime(request, now) {
+    const timestamp = requireDate(now, "Input request transition time");
+    if (Date.parse(timestamp) < Date.parse(request.createdAt)) {
+        throw new Error("Input request transition cannot predate creation.");
+    }
+    return timestamp;
+}
+function requireChoiceKey(value) {
+    if (typeof value !== "string" || !CHOICE_KEY.test(value))
+        throw new Error("Input choice key is invalid.");
+    return value;
+}
+function validatePersistedAnswer(choices, value) {
+    const answer = record(value, "Input resolution answer");
+    if (choices.length === 0) {
+        exact(answer, ["text"], "Input resolution answer");
+        return { text: requireNormalizedText(answer.text, "Input answer") };
+    }
+    exact(answer, ["choiceKey", "text"], "Input resolution answer");
+    const choiceKey = requireChoiceKey(answer.choiceKey);
+    const choice = choices.find((candidate) => candidate.key === choiceKey);
+    if (choice === undefined)
+        throw new Error(`Input answer choice does not exist: ${choiceKey}.`);
+    const text = requireNormalizedText(answer.text, "Input answer");
+    if (text !== choice.label)
+        throw new Error("Input answer text does not match the selected choice label.");
+    return { choiceKey, text };
+}
+function requireIdentity(value, label) {
+    const text = requireText(value, label);
+    if (["__proto__", "prototype", "constructor", ".", ".."].includes(text) || /[\/\\\0]/.test(text)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return text;
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.includes("\0"))
+        throw new Error(`${label} is invalid.`);
+    const text = value.replaceAll("\r\n", "\n").replaceAll("\r", "\n").trim();
+    if (text.length === 0)
+        throw new Error(`${label} is required.`);
+    return text;
+}
+function requireNormalizedText(value, label) {
+    const text = requireText(value, label);
+    if (text !== value)
+        throw new Error(`${label} must be normalized.`);
+    return text;
+}
+function requireDate(value, label) {
+    if (!(value instanceof Date) || !Number.isFinite(value.getTime()))
+        throw new Error(`${label} is invalid.`);
+    return value.toISOString();
+}
+function requireTimestamp(value, label) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value)))
+        throw new Error(`${label} is invalid.`);
+    return value;
+}
+function record(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${label} must be an object.`);
+    }
+    return value;
+}
+function exact(value, fields, label) {
+    const allowed = new Set(fields);
+    const unknown = Object.keys(value).find((key) => !allowed.has(key));
+    if (unknown !== undefined)
+        throw new Error(`${label} has unknown field: ${unknown}.`);
+    const missing = fields.find((key) => !Object.hasOwn(value, key));
+    if (missing !== undefined)
+        throw new Error(`${label} is missing field: ${missing}.`);
+}

package/dist/message/message.js

@@ -0,0 +1,69 @@
+export const TASK_MESSAGE_KINDS = ["user", "operator", "role-result", "system"];
+export function createTaskMessage(id, body, kind, author, now, context = {}) {
+    validateKindAndAuthor(kind, author);
+    const message = {
+        schemaVersion: 1,
+        id: requireSafeIdentity(id, "Message id"),
+        kind,
+        author: normalizeAuthor(author),
+        body: requireText(body, "Message body"),
+        ...(context.runId === undefined
+            ? {}
+            : { runId: requireSafeIdentity(context.runId, "Message Run id") }),
+        ...(context.workItemId === undefined
+            ? {}
+            : { workItemId: requireSafeIdentity(context.workItemId, "Message Work item id") }),
+        createdAt: now.toISOString()
+    };
+    validateTaskMessage(message);
+    return message;
+}
+export function taskMessageAuthorLabel(author) {
+    return author.type === "role" ? author.roleName : author.type;
+}
+export function validateTaskMessage(message) {
+    if (message.schemaVersion !== 1)
+        throw new Error("Task Message must use schemaVersion 1.");
+    requireSafeIdentity(message.id, "Message id");
+    requireText(message.body, "Message body");
+    validateKindAndAuthor(message.kind, message.author);
+    normalizeAuthor(message.author);
+    if (message.runId !== undefined)
+        requireSafeIdentity(message.runId, "Message Run id");
+    if (message.workItemId !== undefined) {
+        requireSafeIdentity(message.workItemId, "Message Work item id");
+    }
+    if (typeof message.createdAt !== "string" || Number.isNaN(Date.parse(message.createdAt))) {
+        throw new Error("Message createdAt is invalid.");
+    }
+}
+function validateKindAndAuthor(kind, author) {
+    if (!TASK_MESSAGE_KINDS.includes(kind))
+        throw new Error(`Message kind is invalid: ${String(kind)}.`);
+    const expectedType = kind === "role-result" ? "role" : kind;
+    if (author?.type !== expectedType) {
+        const label = kind === "role-result" ? "Role result" : `Message kind ${kind}`;
+        throw new Error(`${label} requires a ${expectedType} author.`);
+    }
+}
+function normalizeAuthor(author) {
+    return author.type === "role"
+        ? { type: "role", roleName: requireSafeIdentity(author.roleName, "Message Role name") }
+        : { type: author.type };
+}
+function requireSafeIdentity(value, label) {
+    const normalized = requireText(value, label);
+    if (["__proto__", "prototype", "constructor", ".", ".."].includes(normalized)
+        || /[\/\\\0]/.test(normalized)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.includes("\0"))
+        throw new Error(`${label} is invalid.`);
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}

package/dist/milestone/milestone.js

@@ -0,0 +1,27 @@
+export function createMilestone(id, taskId, title, summary, now) {
+    return {
+        schemaVersion: 1,
+        id: requireSafeIdentity(id, "Milestone id"),
+        taskId: requireSafeIdentity(taskId, "Task id"),
+        title: requireText(title, "Milestone title"),
+        summary: requireText(summary, "Milestone summary"),
+        createdBy: "leader",
+        createdAt: now.toISOString()
+    };
+}
+function requireSafeIdentity(value, label) {
+    const normalized = requireText(value, label);
+    if (["__proto__", "prototype", "constructor", ".", ".."].includes(normalized)
+        || /[\/\\\0]/.test(normalized)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.includes("\0"))
+        throw new Error(`${label} is invalid.`);
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}

package/dist/operator/operatorContext.js

@@ -0,0 +1,66 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { SYSTEM_OPERATOR_ROLE } from "../role/systemRoles.js";
+/**
+ * Prepares durable Operator instructions without turning them into Codex's
+ * positional first prompt. Interactive Operator entry must open at the native
+ * Agent composer; launch code can pass systemPrompt through an adapter-native
+ * instruction channel when one is available.
+ */
+export function prepareGlobalRoleLaunch(role, options = {}) {
+    const args = [...(role.args ?? [])];
+    const base = mergeEnv(options.baseEnv, role.env ?? {});
+    if (role.name !== SYSTEM_OPERATOR_ROLE || options.yuiHome === undefined) {
+        return { args, env: base };
+    }
+    const contextPath = writeOperatorContext(options.yuiHome, role.workspace);
+    return {
+        args,
+        env: mergeEnv(base, {
+            YUI_HOME: options.yuiHome,
+            YUI_ROLE: role.name,
+            YUI_WORKSPACE: role.workspace,
+            YUI_OPERATOR_CONTEXT: contextPath
+        }),
+        systemPrompt: renderOperatorLaunchInstruction(contextPath),
+        contextPath
+    };
+}
+export function writeOperatorContext(yuiHome, workspace) {
+    const operatorDir = join(yuiHome, "operator");
+    const contextPath = join(operatorDir, "YUI_OPERATOR.md");
+    mkdirSync(operatorDir, { recursive: true });
+    writeFileSync(contextPath, `${renderOperatorContext(yuiHome, workspace)}\n`, { mode: 0o600 });
+    return contextPath;
+}
+export function renderOperatorLaunchInstruction(contextPath) {
+    return [
+        `Read and follow the Yui Operator instructions in ${contextPath}.`,
+        "Manage Yui through its CLI; do not perform Task work."
+    ].join(" ");
+}
+function renderOperatorContext(yuiHome, workspace) {
+    return `${readOperatorSkill()}
+
+# Yui Operator runtime
+
+You are the Yui Operator. Act as the user's CLI proxy and manage Yui without performing Task work.
+
+Rules:
+
+- Use Yui commands to create and inspect Tasks, manage global and Task Roles, choose Agents, and submit user input.
+- Do not edit files under YUI_HOME directly.
+- Every Task has a protected leader Role; Operator is global and never acts as a Task Leader or Worker.
+- Keep native Agent session interaction intact. Do not emulate Agent slash commands or terminal input.
+
+Environment:
+
+- YUI_HOME=${yuiHome}
+- YUI_WORKSPACE=${workspace}`;
+}
+function readOperatorSkill() {
+    return readFileSync(new URL("../../skills/yui-operator/SKILL.md", import.meta.url), "utf8").trim();
+}
+function mergeEnv(baseEnv = process.env, roleEnv) {
+    return { ...baseEnv, ...roleEnv };
+}

package/dist/output/rolePresentation.js

@@ -0,0 +1,82 @@
+import { defaultTableWidth, renderTable } from "./table.js";
+export function activeRoleSummary(role) {
+    const binding = role.agentBindings[role.activeAgentId];
+    return {
+        agent: role.activeAgentId,
+        model: binding?.config.model ?? "CLI default",
+        effort: binding?.config.effort ?? "CLI default"
+    };
+}
+export function renderRoleDetails(title, role, input) {
+    const bindings = Object.values(role.agentBindings)
+        .sort((left, right) => left.agentId.localeCompare(right.agentId));
+    const profile = [
+        `  Description      ${present(role.description)}`,
+        `  Responsibilities ${presentList(role.responsibilities)}`,
+        `  Constraints      ${presentList(role.constraints)}`,
+        `  Expected output  ${present(role.expectedOutput)}`,
+        `  System prompt    ${present(role.systemPrompt)}`,
+        `  Skills           ${presentList(role.skills)}`
+    ];
+    const overview = [
+        `  Kind             ${input.kind}`,
+        `  Active Agent     ${role.activeAgentId}`,
+        ...("status" in role ? [`  Status           ${role.status}`] : []),
+        `  Workspace        ${role.workspace}`
+    ];
+    return [
+        title,
+        "",
+        "Role settings",
+        ...overview,
+        "",
+        "Profile",
+        ...profile,
+        "",
+        renderTable("Agent settings", [
+            { header: "Agent", minWidth: 5, maxWidth: 20 },
+            { header: "Active", minWidth: 6, maxWidth: 6 },
+            { header: "Adapter", minWidth: 7, maxWidth: 10 },
+            { header: "Model", minWidth: 8, maxWidth: 24 },
+            { header: "Effort", minWidth: 8, maxWidth: 16 },
+            { header: "Permission", minWidth: 10, maxWidth: 34 },
+            { header: "Search", minWidth: 6, maxWidth: 11 },
+            { header: "Session", minWidth: 7, maxWidth: 12 }
+        ], bindings.map((binding) => bindingRow(binding, role, input.sessions)), defaultTableWidth())
+    ].join("\n").concat("\n");
+}
+function bindingRow(binding, role, sessions) {
+    return [
+        binding.agentId,
+        binding.agentId === role.activeAgentId ? "yes" : "",
+        binding.adapterId,
+        binding.config.model ?? "CLI default",
+        binding.config.effort ?? "CLI default",
+        permission(binding),
+        binding.config.adapterId === "codex"
+            ? binding.config.search === true ? "enabled" : "CLI default"
+            : "-",
+        sessions?.sessions[binding.agentId]?.status ?? "not started"
+    ];
+}
+function permission(binding) {
+    if (binding.config.adapterId === "codex") {
+        const sandbox = binding.config.permission?.sandbox;
+        const approval = binding.config.permission?.approval;
+        if (sandbox === undefined && approval === undefined)
+            return "CLI default";
+        return [
+            sandbox === undefined ? undefined : `sandbox=${sandbox}`,
+            approval === undefined ? undefined : `approval=${approval}`
+        ].filter((value) => value !== undefined).join(", ");
+    }
+    return binding.config.permission?.mode === undefined
+        ? "CLI default"
+        : `mode=${binding.config.permission.mode}`;
+}
+function present(value) {
+    return value === undefined || value.length === 0 ? "-" : value;
+}
+function presentList(values) {
+    return values === undefined || values.length === 0 ? "-" : values.join("; ");
+}

package/dist/output/table.js

@@ -0,0 +1,77 @@
+import { padVisibleEnd, visibleWidth, wrapVisibleText } from "./terminal.js";
+export function renderTable(title, columns, rows, maxWidth) {
+    if (columns.length === 0)
+        return title;
+    const availableWidth = Math.max(20, Math.floor(maxWidth));
+    const minimumWidth = tableWidth(columns.map((column) => column.minWidth));
+    if (minimumWidth > availableWidth)
+        return renderRecords(title, columns, rows, availableWidth);
+    const widths = fitColumnWidths(columns, rows, availableWidth);
+    return [
+        ...wrapVisibleText(title, availableWidth),
+        "",
+        renderTableRow(columns.map((column) => column.header), widths),
+        `  ${widths.map((width) => "─".repeat(width)).join("  ")}`,
+        ...rows.flatMap((row) => renderWrappedTableRow(row, widths))
+    ].join("\n");
+}
+export function defaultTableWidth() {
+    return Math.max(46, Math.min(process.stdout.columns ?? 100, 140));
+}
+function fitColumnWidths(columns, rows, maxWidth) {
+    const widths = columns.map((column, columnIndex) => {
+        const contentWidths = rows.flatMap((row) => (row[columnIndex] ?? "").split("\n").map(visibleWidth));
+        const maxContentWidth = Math.max(visibleWidth(column.header), ...contentWidths);
+        return Math.min(column.maxWidth, Math.max(column.minWidth, maxContentWidth));
+    });
+    while (tableWidth(widths) > maxWidth) {
+        const shrink = widths.map((width, index) => ({
+            index,
+            spare: width - (columns[index]?.minWidth ?? width)
+        })).sort((left, right) => right.spare - left.spare)[0];
+        if (shrink === undefined || shrink.spare <= 0)
+            break;
+        widths[shrink.index] = (widths[shrink.index] ?? 1) - 1;
+    }
+    return widths;
+}
+function renderWrappedTableRow(row, widths) {
+    const cells = widths.map((width, index) => wrapVisibleText(row[index] ?? "", width));
+    const height = Math.max(...cells.map((cell) => cell.length));
+    return Array.from({ length: height }, (_, lineIndex) => renderTableRow(cells.map((cell) => cell[lineIndex] ?? ""), widths));
+}
+function renderTableRow(cells, widths) {
+    return `  ${cells.map((cell, index) => padVisibleEnd(cell, widths[index] ?? 1)).join("  ").trimEnd()}`;
+}
+function tableWidth(widths) {
+    return 2 + widths.reduce((sum, width) => sum + width, 0) + Math.max(0, widths.length - 1) * 2;
+}
+function renderRecords(title, columns, rows, maxWidth) {
+    const indexColumn = columns[0]?.header === "#" ? 0 : undefined;
+    const primaryColumn = indexColumn === 0 && columns.length > 1 ? 1 : 0;
+    const detailColumns = columns.map((_, index) => index)
+        .filter((index) => index !== indexColumn && index !== primaryColumn);
+    const labelWidth = Math.max(0, ...detailColumns.map((index) => visibleWidth(columns[index]?.header ?? "")));
+    const lines = [...wrapVisibleText(title, maxWidth), ""];
+    rows.forEach((row, rowIndex) => {
+        if (rowIndex > 0)
+            lines.push("");
+        const indexValue = indexColumn === undefined ? "" : row[indexColumn] ?? "";
+        const primaryValue = row[primaryColumn] ?? "";
+        const primaryPrefix = `  ${indexValue.length === 0 ? "" : `${indexValue}  `}`;
+        const primaryLines = wrapVisibleText(primaryValue, Math.max(1, maxWidth - visibleWidth(primaryPrefix)));
+        lines.push(`${primaryPrefix}${primaryLines[0] ?? ""}`.trimEnd());
+        lines.push(...primaryLines.slice(1).map((line) => `${" ".repeat(visibleWidth(primaryPrefix))}${line}`));
+        for (const columnIndex of detailColumns) {
+            const value = row[columnIndex] ?? "";
+            if (value.length === 0)
+                continue;
+            const header = columns[columnIndex]?.header ?? "";
+            const prefix = `     ${padVisibleEnd(header, labelWidth)}  `;
+            const wrapped = wrapVisibleText(value, Math.max(1, maxWidth - visibleWidth(prefix)));
+            lines.push(`${prefix}${wrapped[0] ?? ""}`.trimEnd());
+            lines.push(...wrapped.slice(1).map((line) => `${" ".repeat(visibleWidth(prefix))}${line}`));
+        }
+    });
+    return lines.join("\n");
+}