@canonical/pragma-cli 0.18.0 → 0.21.0

package/src/tui/helpers/computeWidths.ts

@@ -0,0 +1,53 @@
+import type { ColumnDef } from "../../domains/shared/contracts.js";
+import { COL_GAP, MIN_COL_WIDTH } from "../constants.js";
+
+const FIRST_COL_MIN_RATIO = 0.3;
+
+/**
+ * Compute proportional column widths based on content and terminal width.
+ *
+ * Measures the maximum content width for each column across all items,
+ * then distributes the available terminal width proportionally. The first
+ * column (typically Name) receives at least 30% of the available width
+ * to ensure readability.
+ *
+ * @param columns - Visible column definitions.
+ * @param items - Data items to measure content widths against.
+ * @param terminalWidth - Available width in characters.
+ * @returns Array of computed widths (one per column).
+ */
+export default function computeWidths<T>(
+  columns: readonly ColumnDef<T>[],
+  items: readonly T[],
+  terminalWidth: number,
+): readonly number[] {
+  if (columns.length === 0) return [];
+
+  const totalGaps = (columns.length - 1) * COL_GAP;
+  const available = terminalWidth - totalGaps - 1;
+
+  const naturalWidths = columns.map((col) => {
+    const labelWidth = col.label.length;
+    const maxContent = items.reduce((max, item) => {
+      const raw = item[col.key];
+      const formatted = col.format ? col.format(raw) : String(raw ?? "");
+      return Math.max(max, formatted.length);
+    }, 0);
+    return Math.max(labelWidth, maxContent);
+  });
+
+  const totalNatural = naturalWidths.reduce((sum, w) => sum + w, 0);
+
+  if (totalNatural <= available) {
+    return naturalWidths;
+  }
+
+  const firstColMin = Math.floor(available * FIRST_COL_MIN_RATIO);
+  return naturalWidths.map((natural, i) => {
+    const ratio =
+      totalNatural > 0 ? natural / totalNatural : 1 / columns.length;
+    const proportional = Math.floor(available * ratio);
+    if (i === 0) return Math.max(proportional, firstColMin);
+    return Math.max(proportional, MIN_COL_WIDTH);
+  });
+}

package/src/tui/helpers/fitColumns.ts

@@ -0,0 +1,33 @@
+import type { ColumnDef } from "../../domains/shared/contracts.js";
+import { COL_GAP, MIN_COL_WIDTH } from "../constants.js";
+
+const MIN_VISIBLE = 3;
+
+/**
+ * Determine which columns are visible given the available terminal width.
+ *
+ * Columns are ordered by priority (first = highest). When the terminal
+ * is too narrow to fit all columns with minimum widths, columns are
+ * dropped right-to-left (lowest priority first). At least three columns
+ * are always retained, and the function never returns an empty array
+ * if the input is non-empty.
+ *
+ * @param columns - Ordered column definitions (priority order).
+ * @param terminalWidth - Available width in characters.
+ * @returns The subset of columns that fit within the terminal width.
+ */
+export default function fitColumns<T>(
+  columns: readonly ColumnDef<T>[],
+  terminalWidth: number,
+): readonly ColumnDef<T>[] {
+  const visible = [...columns];
+
+  while (visible.length > MIN_VISIBLE) {
+    const requiredWidth =
+      visible.length * MIN_COL_WIDTH + (visible.length - 1) * COL_GAP;
+    if (requiredWidth <= terminalWidth) break;
+    visible.pop();
+  }
+
+  return visible;
+}

package/src/tui/helpers/formatMarkdown.ts

@@ -0,0 +1,19 @@
+import chalk from "chalk";
+
+/**
+ * Convert minimal Markdown to ANSI-styled text.
+ *
+ * Handles only the subset of Markdown commonly found in ontology
+ * descriptions: bold, inline code, and bullet lists. No heading
+ * parsing, no link rendering, no block-level structures beyond
+ * paragraph separation.
+ *
+ * @param markdown - Raw Markdown text.
+ * @returns ANSI-styled string suitable for terminal output.
+ */
+export default function formatMarkdown(markdown: string): string {
+  return markdown
+    .replace(/\*\*(.+?)\*\*/g, (_, text: string) => chalk.bold(text))
+    .replace(/`(.+?)`/g, (_, text: string) => chalk.dim(text))
+    .replace(/^- /gm, "• ");
+}

package/src/tui/helpers/getTerminalSize.ts

@@ -0,0 +1,16 @@
+/**
+ * Return the current terminal dimensions.
+ *
+ * Reads `process.stdout.columns` and `process.stdout.rows` directly.
+ * Falls back to 80x24 when dimensions are unavailable (e.g., piped
+ * output or non-TTY environments).
+ */
+export default function getTerminalSize(): {
+  columns: number;
+  rows: number;
+} {
+  return {
+    columns: process.stdout.columns ?? 80,
+    rows: process.stdout.rows ?? 24,
+  };
+}

package/src/tui/helpers/index.ts

@@ -0,0 +1,6 @@
+export { default as computeWidths } from "./computeWidths.js";
+export { default as fitColumns } from "./fitColumns.js";
+export { default as formatMarkdown } from "./formatMarkdown.js";
+export { default as getTerminalSize } from "./getTerminalSize.js";
+export { default as syntaxColor } from "./syntaxColor.js";
+export { default as truncateText } from "./truncateText.js";

package/src/tui/helpers/syntaxColor.ts

@@ -0,0 +1,67 @@
+import chalk from "chalk";
+
+/**
+ * Apply lightweight syntax coloring to a code string.
+ *
+ * Performs keyword-level colorization for YAML and Turtle (TTL) content.
+ * This is not full syntax highlighting — just enough to make structure
+ * scannable in the terminal.
+ *
+ * - YAML keys: bold
+ * - YAML list markers (`-`): dim
+ * - TTL prefixes (`@prefix`): cyan
+ * - TTL predicates (prefixed names like `ds:name`): blue
+ * - TTL type declarations (`a ds:Component`): magenta
+ *
+ * @param code - The raw code string.
+ * @param language - Language identifier ("yaml", "ttl", or "text").
+ * @returns The string with ANSI color codes applied.
+ */
+export default function syntaxColor(code: string, language: string): string {
+  switch (language) {
+    case "yaml":
+      return colorizeYaml(code);
+    case "ttl":
+      return colorizeTurtle(code);
+    default:
+      return code;
+  }
+}
+
+function colorizeYaml(code: string): string {
+  return code
+    .split("\n")
+    .map((line) => {
+      const listMatch = line.match(/^(\s*)(- )(.*)/);
+      if (listMatch) {
+        return `${listMatch[1]}${chalk.dim(listMatch[2])}${listMatch[3]}`;
+      }
+      const kvMatch = line.match(/^(\s*)([^:]+):(.*)/);
+      if (kvMatch) {
+        return `${kvMatch[1]}${chalk.bold(kvMatch[2])}:${kvMatch[3]}`;
+      }
+      return line;
+    })
+    .join("\n");
+}
+
+function colorizeTurtle(code: string): string {
+  return code
+    .split("\n")
+    .map((line) => {
+      if (line.trimStart().startsWith("@prefix")) {
+        return chalk.cyan(line);
+      }
+      const typeMatch = line.match(/(\s+a\s+)(\S+)/);
+      if (typeMatch) {
+        return line.replace(
+          typeMatch[0],
+          `${typeMatch[1]}${chalk.magenta(typeMatch[2])}`,
+        );
+      }
+      return line.replace(/\b([a-z]+:[a-zA-Z.]+)/g, (match) =>
+        chalk.blue(match),
+      );
+    })
+    .join("\n");
+}

package/src/tui/helpers/truncateText.ts

@@ -0,0 +1,12 @@
+/**
+ * Truncate a string to fit within a maximum width, appending an ellipsis
+ * when the string exceeds the limit.
+ *
+ * Returns the original string unchanged if it fits. Otherwise, trims to
+ * `maxWidth - 1` characters and appends `…`.
+ */
+export default function truncateText(text: string, maxWidth: number): string {
+  if (text.length <= maxWidth) return text;
+  if (maxWidth <= 1) return "…";
+  return `${text.slice(0, maxWidth - 1)}…`;
+}

package/src/tui/hooks/index.ts

@@ -0,0 +1,3 @@
+export type * from "./types.js";
+export { default as useAutoExit } from "./useAutoExit.js";
+export { default as useTerminalSize } from "./useTerminalSize.js";

package/src/tui/hooks/types.ts

@@ -0,0 +1,7 @@
+/** Return type for the useTerminalSize hook. */
+export interface UseTerminalSizeResult {
+  /** Terminal width in columns. Falls back to 80 if not detectable. */
+  readonly columns: number;
+  /** Terminal height in rows. Falls back to 24 if not detectable. */
+  readonly rows: number;
+}

package/src/tui/hooks/useAutoExit.ts

@@ -0,0 +1,17 @@
+import { useApp } from "ink";
+import { useEffect } from "react";
+
+/**
+ * Exit the Ink application after the initial render.
+ *
+ * All pragma TUI views are static — they render a single frame and
+ * exit. This hook calls `useApp().exit()` in a `useEffect`, which
+ * runs after the first paint. Ink then flushes the frame to stdout
+ * and resolves the `waitUntilExit()` promise in the renderInk bridge.
+ */
+export default function useAutoExit(): void {
+  const { exit } = useApp();
+  useEffect(() => {
+    exit();
+  }, [exit]);
+}

package/src/tui/hooks/useTerminalSize.ts

@@ -0,0 +1,19 @@
+import type { UseTerminalSizeResult } from "./types.js";
+
+/**
+ * Return the current terminal dimensions.
+ *
+ * Reads `process.stdout.columns` and `process.stdout.rows` directly.
+ * Falls back to 80x24 when dimensions are unavailable (e.g., piped
+ * output, or Ink's renderToString mode where stdout is not attached).
+ *
+ * For renderToString usage, Ink passes the column width via its own
+ * options — this hook provides the value for components that need
+ * to compute layout independently.
+ */
+export default function useTerminalSize(): UseTerminalSizeResult {
+  return {
+    columns: process.stdout.columns ?? 80,
+    rows: process.stdout.rows ?? 24,
+  };
+}

package/src/tui/index.ts

@@ -0,0 +1,15 @@
+/**
+ * TUI rendering domain for the pragma CLI.
+ *
+ * Provides Ink-based React components for rich terminal output of list
+ * and lookup commands. Activated when stdout is an interactive TTY and
+ * no machine-readable format flag is set.
+ *
+ * @module tui
+ */
+
+export { default as createListView } from "./createListView.js";
+export { default as createLookupView } from "./createLookupView.js";
+export { default as renderInk } from "./renderInk.js";
+export type { ListViewProps, LookupViewProps } from "./views/index.js";
+export { ListView, LookupView } from "./views/index.js";

package/src/tui/renderInk.tsx

@@ -0,0 +1,18 @@
+/**
+ * Write TUI-rendered output to stdout.
+ *
+ * The ink renderers in pragma produce chalk-styled strings directly
+ * (not React elements), so this function simply writes the string
+ * to stdout. The dynamic import boundary is preserved so that domain
+ * command files can reference the `#tui` barrel without pulling in
+ * React/Ink at parse time for non-TTY invocations.
+ *
+ * @param output - A chalk-styled string produced by a TUI view.
+ *
+ * @note Impure — writes to process.stdout.
+ */
+export default async function renderInk(output: unknown): Promise<void> {
+  if (typeof output === "string" && output.length > 0) {
+    process.stdout.write(`${output}\n`);
+  }
+}

package/src/tui/types.ts

@@ -0,0 +1,12 @@
+/**
+ * A color pair for domain-aware TUI rendering.
+ *
+ * Maps chalk color method names — `classBg` for background colors
+ * on class-level labels, `instanceFg` for text colors on instance values.
+ */
+export interface DomainColorPair {
+  /** Chalk background color name for class-level labels. */
+  readonly classBg: string;
+  /** Chalk text color name for instance values. */
+  readonly instanceFg: string;
+}

package/src/tui/views/ListView/ListView.tsx

@@ -0,0 +1,104 @@
+import chalk from "chalk";
+import compactUri from "../../../domains/shared/compactUri.js";
+import { PREFIX_MAP } from "../../../domains/shared/prefixes.js";
+import { COL_GAP, DOMAIN_COLORS } from "../../constants.js";
+import {
+  computeWidths,
+  fitColumns,
+  getTerminalSize,
+  truncateText,
+} from "../../helpers/index.js";
+import type { ListViewProps } from "./types.js";
+
+/**
+ * A responsive table view for list commands.
+ *
+ * Renders all items of a domain (block, token, modifier, etc.) as a
+ * tabular display with column headers, proportional widths, and
+ * domain-aware coloring. Columns drop right-to-left when the terminal
+ * is too narrow. Output is built as a chalk-styled string inside a
+ * single `<Text>` element to avoid Ink's flex-column spacing.
+ */
+export default function ListView<T>({
+  heading,
+  domain,
+  items,
+  columns,
+  prefixes,
+}: ListViewProps<T>) {
+  const { columns: termWidth } = getTerminalSize();
+  const prefixMap = prefixes ?? PREFIX_MAP;
+  const colors = DOMAIN_COLORS[domain];
+  const colorFn = resolveChalkColor(colors?.instanceFg);
+
+  if (items.length === 0) {
+    return `${chalk.bold(colorFn(`${heading} (0)`))}\n${chalk.dim("No results.")}`;
+  }
+
+  const visibleColumns = fitColumns(columns, termWidth);
+  const widths = computeWidths(visibleColumns, items, termWidth);
+  const gap = " ".repeat(COL_GAP);
+
+  const headingLine = chalk.bold(colorFn(`${heading} (${items.length})`));
+
+  const headerLine = chalk.bold(
+    visibleColumns
+      .map((col, i) => {
+        const w = widths[i] ?? col.label.length;
+        return truncateText(col.label, w).padEnd(w);
+      })
+      .join(gap),
+  );
+
+  const totalWidth =
+    widths.reduce((sum, w) => sum + w, 0) + (widths.length - 1) * COL_GAP;
+  const separator = chalk.dim("─".repeat(totalWidth));
+
+  const dataLines = items.map((item) =>
+    visibleColumns
+      .map((col, i) => {
+        const w = widths[i] ?? 20;
+        const raw = (item as Record<string, unknown>)[col.key];
+        const formatted = formatCellValue(raw, col, prefixMap);
+        const padded = truncateText(formatted, w).padEnd(w);
+
+        if (col.key === "uri") return chalk.dim(padded);
+        if (col.key === "name") return colorFn(padded);
+        return padded;
+      })
+      .join(gap),
+  );
+
+  return [headingLine, headerLine, separator, ...dataLines].join("\n");
+}
+
+function formatCellValue(
+  raw: unknown,
+  col: { format?: (value: unknown) => string },
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  if (col.format) return col.format(raw);
+  if (raw === null || raw === undefined) return "";
+  if (typeof raw === "string" && looksLikeUri(raw))
+    return compactUri(raw, prefixes);
+  if (Array.isArray(raw)) return raw.map(String).join(", ");
+  return String(raw);
+}
+
+function looksLikeUri(value: string): boolean {
+  return (
+    value.startsWith("http://") ||
+    value.startsWith("https://") ||
+    /^[a-z][a-z0-9+.-]*:/i.test(value)
+  );
+}
+
+function resolveChalkColor(
+  colorName: string | undefined,
+): (text: string) => string {
+  if (!colorName) return (text) => text;
+  const fn = chalk[colorName as keyof typeof chalk];
+  return typeof fn === "function"
+    ? (fn as (text: string) => string)
+    : (text) => text;
+}

package/src/tui/views/ListView/index.ts

@@ -0,0 +1,2 @@
+export { default as ListView } from "./ListView.js";
+export type * from "./types.js";

package/src/tui/views/ListView/types.ts

@@ -0,0 +1,14 @@
+import type { ColumnDef } from "../../../domains/shared/contracts.js";
+
+export interface ListViewProps<T> {
+  /** Heading text displayed above the table (e.g., "Blocks"). */
+  readonly heading: string;
+  /** Domain name — indexes into DOMAIN_COLORS for heading and row coloring. */
+  readonly domain: string;
+  /** Data items to render as table rows. */
+  readonly items: readonly T[];
+  /** Column definitions controlling which fields appear and how they format. */
+  readonly columns: readonly ColumnDef<T>[];
+  /** URI prefix map for compacting IRIs. */
+  readonly prefixes?: Readonly<Record<string, string>>;
+}

package/src/tui/views/LookupView/LookupView.tsx

@@ -0,0 +1,244 @@
+import chalk from "chalk";
+import compactUri from "../../../domains/shared/compactUri.js";
+import { PREFIX_MAP } from "../../../domains/shared/prefixes.js";
+import { buildCard } from "../../components/Card/index.js";
+import { formatMarkdown, syntaxColor } from "../../helpers/index.js";
+import type { LookupViewProps } from "./types.js";
+
+/**
+ * A stacked card view for lookup commands.
+ *
+ * Renders each lookup result as a bordered card with field rows
+ * and sections. Multiple results show a `[N of M]` badge in each
+ * card header. Errors are appended after all cards. Output is built
+ * as a chalk-styled string inside a single `<Text>` element.
+ */
+export default function LookupView<T>({
+  results,
+  errors,
+  options,
+  domain,
+}: LookupViewProps<T>) {
+  const prefixes = options.prefixes ?? PREFIX_MAP;
+  const total = results.length;
+  const labelWidth = computeLabelWidth(options.fields);
+  const termWidth = process.stdout.columns ?? 80;
+
+  const cards = results.map((entity, i) => {
+    const bodyLines: string[] = [];
+
+    // 2 (left pad) + labelWidth + 2 (gap) = value column offset
+    const valueOffset = 2 + labelWidth + 2;
+    const valueIndent = " ".repeat(valueOffset);
+    const innerWidth = Math.max(termWidth - 4, 20);
+    const maxValueWidth = innerWidth - valueOffset;
+
+    for (const field of options.fields) {
+      const value = field.value(entity);
+      if (isEmpty(value)) continue;
+      const raw = formatInlineValue(value, prefixes);
+      const formatted = typeof value === "string" ? formatMarkdown(raw) : raw;
+      const label = chalk.bold(field.label.padEnd(labelWidth));
+      const wrapped = wrapText(formatted, maxValueWidth);
+      bodyLines.push(`  ${label}  ${wrapped[0]}`);
+      for (let l = 1; l < wrapped.length; l++) {
+        bodyLines.push(`${valueIndent}${wrapped[l]}`);
+      }
+    }
+
+    for (const section of options.sections) {
+      const value = entity[section.key];
+      if (!section.showWhenEmpty && isEmpty(value)) continue;
+
+      const sectionBody = formatSectionValue(value, section.kind, prefixes);
+      if (!sectionBody) continue;
+
+      bodyLines.push("");
+      bodyLines.push(`  ${chalk.bold(section.heading)}`);
+      for (const line of sectionBody.split("\n")) {
+        bodyLines.push(`  ${line}`);
+      }
+    }
+
+    const badge = total > 1 ? `[${i + 1} of ${total}]` : undefined;
+    return buildCard(
+      options.title(entity),
+      domain,
+      bodyLines,
+      termWidth,
+      badge,
+    );
+  });
+
+  const errorLines =
+    errors.length > 0
+      ? [
+          "",
+          chalk.bold.red("Errors:"),
+          ...errors.map((err) => chalk.red(`  • ${err.query}: ${err.message}`)),
+        ]
+      : [];
+
+  return [...cards, ...errorLines].join("\n\n");
+}
+
+function computeLabelWidth<T>(
+  fields: readonly { label: string; value: (entity: T) => unknown }[],
+): number {
+  return fields.reduce((max, f) => Math.max(max, f.label.length), 0);
+}
+
+function formatInlineValue(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  if (Array.isArray(value)) {
+    return value.map((entry) => formatInlineValue(entry, prefixes)).join(", ");
+  }
+  if (value && typeof value === "object") {
+    return Object.entries(value as Record<string, unknown>)
+      .filter(([, v]) => !isEmpty(v))
+      .map(([k, v]) => `${k}=${formatInlineValue(v, prefixes)}`)
+      .join("; ");
+  }
+  return formatScalar(value, prefixes);
+}
+
+function formatScalar(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") {
+    if (looksLikeUri(value)) return compactUri(value, prefixes);
+    return value;
+  }
+  return String(value);
+}
+
+function formatSectionValue(
+  value: unknown,
+  kind: string,
+  prefixes: Readonly<Record<string, string>>,
+): string | null {
+  switch (kind) {
+    case "field":
+      return typeof value === "string" && value.trim().length > 0
+        ? formatMarkdown(value)
+        : null;
+    case "code":
+      return typeof value === "string" && value.trim().length > 0
+        ? syntaxColor(value, "yaml")
+        : null;
+    case "list":
+      if (!Array.isArray(value) || value.length === 0) return null;
+      return value
+        .map((item) => `• ${formatScalar(item, prefixes)}`)
+        .join("\n");
+    case "table":
+    case "nested-table":
+      if (!Array.isArray(value) || value.length === 0) return null;
+      return value
+        .map((entry) => {
+          if (typeof entry === "object" && entry !== null) {
+            return Object.entries(entry as Record<string, unknown>)
+              .filter(([, v]) => !isEmpty(v))
+              .map(([k, v]) => `${k}: ${formatScalar(v, prefixes)}`)
+              .join("  ");
+          }
+          return formatScalar(entry, prefixes);
+        })
+        .join("\n");
+    case "tree":
+      return formatTree(value, prefixes);
+    default:
+      return null;
+  }
+}
+
+function formatTree(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+  depth = 0,
+): string | null {
+  if (Array.isArray(value)) {
+    const lines = value
+      .map((entry) => formatTree(entry, prefixes, depth))
+      .filter(Boolean);
+    return lines.length > 0 ? lines.join("\n") : null;
+  }
+
+  if (!value || typeof value !== "object") {
+    return typeof value === "string" && value.length > 0
+      ? `${"  ".repeat(depth)}├─ ${formatScalar(value, prefixes)}`
+      : null;
+  }
+
+  const node = value as {
+    root?: unknown;
+    name?: string;
+    uri?: string;
+    children?: unknown;
+  };
+  if (node.root) return formatTree(node.root, prefixes, depth);
+
+  const label =
+    node.name && node.name.length > 0
+      ? node.name
+      : node.uri
+        ? compactUri(node.uri, prefixes)
+        : "item";
+
+  const prefix = depth > 0 ? "├─ " : "";
+  const lines = [`${"  ".repeat(depth)}${prefix}${label}`];
+  if (Array.isArray(node.children)) {
+    const childResult = formatTree(node.children, prefixes, depth + 1);
+    if (childResult) lines.push(childResult);
+  }
+  return lines.join("\n");
+}
+
+function isEmpty(value: unknown): boolean {
+  if (value === null || value === undefined) return true;
+  if (typeof value === "string") return value.trim().length === 0;
+  if (Array.isArray(value)) return value.length === 0;
+  return false;
+}
+
+function looksLikeUri(value: string): boolean {
+  return (
+    value.startsWith("http://") ||
+    value.startsWith("https://") ||
+    /^[a-z][a-z0-9+.-]*:/i.test(value)
+  );
+}
+
+/**
+ * Wrap text at word boundaries to fit within maxWidth.
+ * Splits on existing newlines first, then wraps each segment.
+ */
+function wrapText(text: string, maxWidth: number): string[] {
+  const segments = text.split("\n");
+  return segments.flatMap((segment) => wrapSegment(segment, maxWidth));
+}
+
+function wrapSegment(text: string, maxWidth: number): string[] {
+  if (text.length <= maxWidth) return [text];
+
+  const words = text.split(/\s+/);
+  const lines: string[] = [];
+  let current = "";
+
+  for (const word of words) {
+    const candidate = current.length === 0 ? word : `${current} ${word}`;
+    if (candidate.length > maxWidth && current.length > 0) {
+      lines.push(current);
+      current = word;
+    } else {
+      current = candidate;
+    }
+  }
+  if (current.length > 0) lines.push(current);
+
+  return lines;
+}

package/src/tui/views/LookupView/index.ts

@@ -0,0 +1,2 @@
+export { default as LookupView } from "./LookupView.js";
+export type * from "./types.js";