@canonical/pragma-cli 0.18.0 → 0.21.0

package/src/tui/components/CodeBlock/types.ts

@@ -0,0 +1,6 @@
+export interface CodeBlockProps {
+  /** Raw code string to display. */
+  readonly code: string;
+  /** Language identifier for syntax coloring ("yaml", "ttl", "text"). */
+  readonly language: string;
+}

package/src/tui/components/DataRow/DataRow.tsx

@@ -0,0 +1,80 @@
+import { Text } from "ink";
+import compactUri from "../../../domains/shared/compactUri.js";
+import { PREFIX_MAP } from "../../../domains/shared/prefixes.js";
+import { COL_GAP, DOMAIN_COLORS } from "../../constants.js";
+import { truncateText } from "../../helpers/index.js";
+import type { DataRowProps } from "./types.js";
+
+/**
+ * A single data row in the list view table.
+ *
+ * Formats each column value, truncates to fit the computed width,
+ * and applies domain-aware coloring: IRI columns render dim,
+ * name columns render in the domain's instance color.
+ */
+export default function DataRow<T>({
+  item,
+  columns,
+  widths,
+  prefixes,
+  domain,
+}: DataRowProps<T>) {
+  const prefixMap = prefixes ?? PREFIX_MAP;
+  const gap = " ".repeat(COL_GAP);
+  const colors = DOMAIN_COLORS[domain];
+
+  const cells = columns.map((col, i) => {
+    const w = widths[i] ?? 20;
+    const raw = item[col.key];
+    const formatted = formatCellValue(raw, col, prefixMap);
+    const truncated = truncateText(formatted, w).padEnd(w);
+
+    if (col.key === "uri") {
+      return (
+        <Text key={col.key} dimColor>
+          {truncated}
+        </Text>
+      );
+    }
+    if (col.key === "name" && colors) {
+      return (
+        <Text key={col.key} color={colors.instanceFg}>
+          {truncated}
+        </Text>
+      );
+    }
+    return <Text key={col.key}>{truncated}</Text>;
+  });
+
+  return (
+    <Text>
+      {cells.map((cell, i) => (
+        <Text key={columns[i]?.key ?? i}>
+          {i > 0 ? gap : ""}
+          {cell}
+        </Text>
+      ))}
+    </Text>
+  );
+}
+
+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)
+  );
+}

package/src/tui/components/DataRow/index.ts

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

package/src/tui/components/DataRow/types.ts

@@ -0,0 +1,14 @@
+import type { ColumnDef } from "../../../domains/shared/contracts.js";
+
+export interface DataRowProps<T> {
+  /** The data item for this row. */
+  readonly item: T;
+  /** Visible columns to render. */
+  readonly columns: readonly ColumnDef<T>[];
+  /** Computed widths for each column. */
+  readonly widths: readonly number[];
+  /** URI prefix map for compacting IRIs. */
+  readonly prefixes?: Readonly<Record<string, string>>;
+  /** Domain name — indexes into DOMAIN_COLORS for coloring. */
+  readonly domain: string;
+}

package/src/tui/components/FieldRow/FieldRow.tsx

@@ -0,0 +1,24 @@
+import { Box, Text } from "ink";
+import type { FieldRowProps } from "./types.js";
+
+/**
+ * A label-value pair rendered as a single row in a lookup card.
+ *
+ * The label is bold and padded to a fixed width so that values
+ * align vertically across multiple field rows.
+ */
+export default function FieldRow({
+  label,
+  value,
+  labelWidth,
+  valueColor,
+}: FieldRowProps) {
+  const paddedLabel = label.padEnd(labelWidth);
+
+  return (
+    <Box>
+      <Text bold>{`  ${paddedLabel}`}</Text>
+      <Text color={valueColor}>{` ${value}`}</Text>
+    </Box>
+  );
+}

package/src/tui/components/FieldRow/index.ts

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

package/src/tui/components/FieldRow/types.ts

@@ -0,0 +1,10 @@
+export interface FieldRowProps {
+  /** Field label (rendered bold, fixed-width). */
+  readonly label: string;
+  /** Field value (rendered after the label). */
+  readonly value: string;
+  /** Label column width for alignment across rows. */
+  readonly labelWidth: number;
+  /** Optional chalk color name for the value text. */
+  readonly valueColor?: string;
+}

package/src/tui/components/HeaderRow/HeaderRow.tsx

@@ -0,0 +1,32 @@
+import { Box, Text } from "ink";
+import { COL_GAP } from "../../constants.js";
+import { truncateText } from "../../helpers/index.js";
+import type { HeaderRowProps } from "./types.js";
+
+/**
+ * Column header labels with a separator line below.
+ *
+ * Renders each column label in bold, padded to its computed width,
+ * followed by a horizontal rule of `─` characters.
+ */
+export default function HeaderRow<T>({ columns, widths }: HeaderRowProps<T>) {
+  const gap = " ".repeat(COL_GAP);
+
+  const labels = columns
+    .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 = "─".repeat(totalWidth);
+
+  return (
+    <Box flexDirection="column">
+      <Text bold>{labels}</Text>
+      <Text dimColor>{separator}</Text>
+    </Box>
+  );
+}

package/src/tui/components/HeaderRow/index.ts

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

package/src/tui/components/HeaderRow/types.ts

@@ -0,0 +1,8 @@
+import type { ColumnDef } from "../../../domains/shared/contracts.js";
+
+export interface HeaderRowProps<T> {
+  /** Visible columns to render labels for. */
+  readonly columns: readonly ColumnDef<T>[];
+  /** Computed widths for each column. */
+  readonly widths: readonly number[];
+}

package/src/tui/components/MarkdownText/MarkdownText.tsx

@@ -0,0 +1,19 @@
+import { Box, Text } from "ink";
+import { formatMarkdown } from "../../helpers/index.js";
+import type { MarkdownTextProps } from "./types.js";
+
+/**
+ * Minimal Markdown-to-ANSI renderer for terminal display.
+ *
+ * Converts `**bold**` to chalk bold, `` `code` `` to dim, and
+ * `- item` to bullet `•`. No heading parsing, no link rendering.
+ */
+export default function MarkdownText({ content }: MarkdownTextProps) {
+  const formatted = formatMarkdown(content);
+
+  return (
+    <Box paddingLeft={2}>
+      <Text>{formatted}</Text>
+    </Box>
+  );
+}

package/src/tui/components/MarkdownText/index.ts

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

package/src/tui/components/MarkdownText/types.ts

@@ -0,0 +1,4 @@
+export interface MarkdownTextProps {
+  /** Raw Markdown text to render. */
+  readonly content: string;
+}

package/src/tui/components/MiniTable/MiniTable.tsx

@@ -0,0 +1,82 @@
+import { Box, Text } from "ink";
+import compactUri from "../../../domains/shared/compactUri.js";
+import { PREFIX_MAP } from "../../../domains/shared/prefixes.js";
+import type { MiniTableProps } from "./types.js";
+
+/**
+ * A compact aligned table for key-value or multi-column data.
+ *
+ * Renders each entry as a row with values aligned by computing
+ * the maximum width of each key across all entries.
+ */
+export default function MiniTable({ data, prefixes }: MiniTableProps) {
+  const prefixMap = prefixes ?? PREFIX_MAP;
+
+  if (data.length === 0) return null;
+
+  const allKeys = collectKeys(data);
+  const widths = computeKeyWidths(data, allKeys, prefixMap);
+
+  return (
+    <Box flexDirection="column" paddingLeft={2}>
+      {data.map((entry, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: static table rows
+        <Text key={i}>
+          {allKeys
+            .map((key) => {
+              const value = formatValue(entry[key], prefixMap);
+              const w = widths.get(key) ?? value.length;
+              return value.padEnd(w);
+            })
+            .join("  ")}
+        </Text>
+      ))}
+    </Box>
+  );
+}
+
+function collectKeys(data: readonly Record<string, unknown>[]): string[] {
+  const seen = new Set<string>();
+  for (const entry of data) {
+    for (const key of Object.keys(entry)) {
+      seen.add(key);
+    }
+  }
+  return [...seen];
+}
+
+function computeKeyWidths(
+  data: readonly Record<string, unknown>[],
+  keys: string[],
+  prefixes: Readonly<Record<string, string>>,
+): Map<string, number> {
+  const widths = new Map<string, number>();
+  for (const key of keys) {
+    let max = 0;
+    for (const entry of data) {
+      const formatted = formatValue(entry[key], prefixes);
+      max = Math.max(max, formatted.length);
+    }
+    widths.set(key, max);
+  }
+  return widths;
+}
+
+function formatValue(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") {
+    if (
+      value.startsWith("http://") ||
+      value.startsWith("https://") ||
+      /^[a-z][a-z0-9+.-]*:/i.test(value)
+    ) {
+      return compactUri(value, prefixes);
+    }
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(String).join(", ");
+  return String(value);
+}

package/src/tui/components/MiniTable/index.ts

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

package/src/tui/components/MiniTable/types.ts

@@ -0,0 +1,6 @@
+export interface MiniTableProps {
+  /** Array of objects to render as rows. Each object's entries become columns. */
+  readonly data: readonly Record<string, unknown>[];
+  /** URI prefix map for compacting IRIs. */
+  readonly prefixes?: Readonly<Record<string, string>>;
+}

package/src/tui/components/SectionRenderer/SectionRenderer.tsx

@@ -0,0 +1,91 @@
+import { Box, Text } from "ink";
+import { PREFIX_MAP } from "../../../domains/shared/prefixes.js";
+import { BulletList } from "../BulletList/index.js";
+import { CodeBlock } from "../CodeBlock/index.js";
+import { MarkdownText } from "../MarkdownText/index.js";
+import { MiniTable } from "../MiniTable/index.js";
+import { TreeView } from "../TreeView/index.js";
+import type { SectionRendererProps } from "./types.js";
+
+/**
+ * Dispatches a lookup section to the appropriate rendering component
+ * based on the section's `kind`.
+ *
+ * Skips rendering when the section value is empty and `showWhenEmpty`
+ * is not set. Renders a section heading followed by the kind-specific
+ * component.
+ */
+export default function SectionRenderer<T>({
+  section,
+  entity,
+  options,
+  domain: _domain,
+}: SectionRendererProps<T>) {
+  const value = entity[section.key];
+  if (!section.showWhenEmpty && isEmpty(value)) return null;
+
+  const prefixes = options.prefixes ?? PREFIX_MAP;
+  const content = renderByKind(value, section.kind, options, section, prefixes);
+  if (!content) return null;
+
+  return (
+    <Box flexDirection="column" marginTop={1}>
+      <Text bold>{`  ${section.heading}`}</Text>
+      {content}
+    </Box>
+  );
+}
+
+function renderByKind<T>(
+  value: unknown,
+  kind: string,
+  options: SectionRendererProps<T>["options"],
+  section: SectionRendererProps<T>["section"],
+  prefixes: Readonly<Record<string, string>>,
+): React.JSX.Element | null {
+  switch (kind) {
+    case "field": {
+      if (typeof value !== "string" || value.trim().length === 0) return null;
+      return <MarkdownText content={value} />;
+    }
+    case "code": {
+      if (typeof value !== "string" || value.trim().length === 0) return null;
+      const language =
+        options.codeLanguage?.(section, value) ?? inferCodeLanguage(value);
+      return <CodeBlock code={value} language={language} />;
+    }
+    case "tree": {
+      return <TreeView data={value} prefixes={prefixes} />;
+    }
+    case "table":
+    case "nested-table": {
+      if (!Array.isArray(value) || value.length === 0) return null;
+      return (
+        <MiniTable
+          data={value as Record<string, unknown>[]}
+          prefixes={prefixes}
+        />
+      );
+    }
+    case "list": {
+      if (!Array.isArray(value) || value.length === 0) return null;
+      return <BulletList items={value} prefixes={prefixes} />;
+    }
+    default:
+      return null;
+  }
+}
+
+function inferCodeLanguage(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.startsWith("@prefix") || trimmed.includes(" a ")) return "ttl";
+  if (trimmed.includes(":") && trimmed.includes("\n")) return "yaml";
+  return "text";
+}
+
+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;
+}

package/src/tui/components/SectionRenderer/index.ts

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

package/src/tui/components/SectionRenderer/types.ts

@@ -0,0 +1,15 @@
+import type {
+  RenderLookupOptions,
+  SectionDef,
+} from "../../../domains/shared/contracts.js";
+
+export interface SectionRendererProps<T> {
+  /** The section definition to render. */
+  readonly section: SectionDef<T>;
+  /** The entity data containing the section value. */
+  readonly entity: T;
+  /** Full lookup options (for code language inference and prefix map). */
+  readonly options: RenderLookupOptions<T>;
+  /** Domain name for coloring. */
+  readonly domain: string;
+}

package/src/tui/components/TreeView/TreeView.tsx

@@ -0,0 +1,84 @@
+import { Box, Text } from "ink";
+import compactUri from "../../../domains/shared/compactUri.js";
+import { PREFIX_MAP } from "../../../domains/shared/prefixes.js";
+import type { TreeViewProps } from "./types.js";
+
+/**
+ * A tree display with box-drawing connectors.
+ *
+ * Recursively renders tree nodes with `├─` / `└─` connectors and
+ * proper indentation. Handles nodes with `name`, `uri`, and
+ * `children` fields, as well as rooted trees with a `root` field.
+ */
+export default function TreeView({ data, prefixes }: TreeViewProps) {
+  const prefixMap = prefixes ?? PREFIX_MAP;
+  const lines = buildTreeLines(data, prefixMap);
+
+  return (
+    <Box flexDirection="column" paddingLeft={2}>
+      {lines.map((line, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: static tree lines
+        <Text key={i}>{line}</Text>
+      ))}
+    </Box>
+  );
+}
+
+function buildTreeLines(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+  depth = 0,
+): string[] {
+  if (Array.isArray(value)) {
+    return value.flatMap((entry) => buildTreeLines(entry, prefixes, depth));
+  }
+
+  if (!value || typeof value !== "object") {
+    return typeof value === "string" && value.length > 0
+      ? [
+          `${"  ".repeat(depth)}${depth > 0 ? "├─ " : ""}${formatValue(value, prefixes)}`,
+        ]
+      : [];
+  }
+
+  const rootedTree = value as { root?: unknown };
+  if (rootedTree.root) {
+    return buildTreeLines(rootedTree.root, prefixes, depth);
+  }
+
+  const node = value as {
+    name?: unknown;
+    uri?: unknown;
+    children?: unknown;
+  };
+
+  const label =
+    typeof node.name === "string" && node.name.length > 0
+      ? node.name
+      : typeof node.uri === "string"
+        ? compactUri(node.uri, prefixes)
+        : "item";
+
+  const prefix = depth > 0 ? "├─ " : "";
+  const lines = [`${"  ".repeat(depth)}${prefix}${label}`];
+
+  if (Array.isArray(node.children)) {
+    lines.push(...buildTreeLines(node.children, prefixes, depth + 1));
+  }
+
+  return lines;
+}
+
+function formatValue(
+  value: string,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  if (
+    value.startsWith("http://") ||
+    value.startsWith("https://") ||
+    /^[a-z][a-z0-9+.-]*:/i.test(value)
+  ) {
+    return compactUri(value, prefixes);
+  }
+  return value;
+}

package/src/tui/components/TreeView/index.ts

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

package/src/tui/components/TreeView/types.ts

@@ -0,0 +1,6 @@
+export interface TreeViewProps {
+  /** Tree data to render (array of nodes, or a single rooted tree). */
+  readonly data: unknown;
+  /** URI prefix map for compacting IRIs. */
+  readonly prefixes?: Readonly<Record<string, string>>;
+}

package/src/tui/components/index.ts

@@ -0,0 +1,19 @@
+export type { BulletListProps } from "./BulletList/index.js";
+export { BulletList } from "./BulletList/index.js";
+export { buildCard } from "./Card/index.js";
+export type { CodeBlockProps } from "./CodeBlock/index.js";
+export { CodeBlock } from "./CodeBlock/index.js";
+export type { DataRowProps } from "./DataRow/index.js";
+export { DataRow } from "./DataRow/index.js";
+export type { FieldRowProps } from "./FieldRow/index.js";
+export { FieldRow } from "./FieldRow/index.js";
+export type { HeaderRowProps } from "./HeaderRow/index.js";
+export { HeaderRow } from "./HeaderRow/index.js";
+export type { MarkdownTextProps } from "./MarkdownText/index.js";
+export { MarkdownText } from "./MarkdownText/index.js";
+export type { MiniTableProps } from "./MiniTable/index.js";
+export { MiniTable } from "./MiniTable/index.js";
+export type { SectionRendererProps } from "./SectionRenderer/index.js";
+export { SectionRenderer } from "./SectionRenderer/index.js";
+export type { TreeViewProps } from "./TreeView/index.js";
+export { TreeView } from "./TreeView/index.js";

package/src/tui/constants.ts

@@ -0,0 +1,39 @@
+import type { DomainColorPair } from "./types.js";
+
+/**
+ * Per-domain color assignments for TUI rendering.
+ *
+ * Each domain gets a distinct hue. Class-level labels (e.g., "Component",
+ * "Token") use the background variant; instance values (e.g., "Button",
+ * "color.primary") use the foreground text variant of the same hue.
+ * This creates visual coherence within a domain while distinguishing
+ * domains from each other.
+ */
+export const DOMAIN_COLORS: Readonly<Record<string, DomainColorPair>> = {
+  block: { classBg: "bgBlue", instanceFg: "blue" },
+  token: { classBg: "bgGreen", instanceFg: "green" },
+  modifier: { classBg: "bgYellow", instanceFg: "yellow" },
+  standard: { classBg: "bgCyan", instanceFg: "cyan" },
+  tier: { classBg: "bgMagenta", instanceFg: "magenta" },
+  ontology: { classBg: "bgWhite", instanceFg: "white" },
+};
+
+/** Box-drawing characters for card borders and separators. */
+export const BOX = {
+  topLeft: "╔",
+  topRight: "╗",
+  bottomLeft: "╚",
+  bottomRight: "╝",
+  horizontal: "═",
+  vertical: "║",
+  dividerLeft: "╠",
+  dividerRight: "╣",
+  dividerHorizontal: "─",
+  thinVertical: "│",
+} as const;
+
+/** Column gap width (characters between columns in list view). */
+export const COL_GAP = 2;
+
+/** Minimum width for any visible column (characters). */
+export const MIN_COL_WIDTH = 8;

package/src/tui/createListView.ts

@@ -0,0 +1,23 @@
+import type { ColumnDef } from "../domains/shared/contracts.js";
+import { ListView } from "./views/index.js";
+
+/**
+ * Create a ListView string output with proper generic type inference.
+ *
+ * Wraps the ListView function call to preserve the generic `T` at
+ * the call site. Domain commands call this from plain `.ts` files
+ * without needing JSX or React.
+ *
+ * @param props - ListView props with typed items and columns.
+ * @returns A chalk-styled string ready for stdout.
+ */
+export default function createListView<T>(props: {
+  readonly heading: string;
+  readonly domain: string;
+  readonly items: readonly T[];
+  readonly columns: readonly ColumnDef<T>[];
+  readonly prefixes?: Readonly<Record<string, string>>;
+}): string {
+  // biome-ignore lint/suspicious/noExplicitAny: generic erasure at function boundary
+  return (ListView as (props: any) => string)(props);
+}

package/src/tui/createLookupView.ts

@@ -0,0 +1,26 @@
+import type { RenderLookupOptions } from "../domains/shared/contracts.js";
+import { LookupView } from "./views/index.js";
+
+/**
+ * Create a LookupView string output with proper generic type inference.
+ *
+ * Wraps the LookupView function call to preserve the generic `T` at
+ * the call site. Domain commands call this from plain `.ts` files
+ * without needing JSX or React.
+ *
+ * @param props - LookupView props with typed results and options.
+ * @returns A chalk-styled string ready for stdout.
+ */
+export default function createLookupView<T>(props: {
+  readonly results: readonly T[];
+  readonly errors: readonly {
+    readonly query: string;
+    readonly code: string;
+    readonly message: string;
+  }[];
+  readonly options: RenderLookupOptions<T>;
+  readonly domain: string;
+}): string {
+  // biome-ignore lint/suspicious/noExplicitAny: generic erasure at function boundary
+  return (LookupView as (props: any) => string)(props);
+}