@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -1,6 +0,0 @@
-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

@@ -1,91 +0,0 @@
-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

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

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

@@ -1,15 +0,0 @@
-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

@@ -1,84 +0,0 @@
-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

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

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

@@ -1,6 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,39 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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);
-}

package/src/tui/helpers/computeWidths.ts

@@ -1,53 +0,0 @@
-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

@@ -1,33 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,16 +0,0 @@
-/**
- * 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

@@ -1,6 +0,0 @@
-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

@@ -1,67 +0,0 @@
-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

@@ -1,12 +0,0 @@
-/**
- * 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

@@ -1,3 +0,0 @@
-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

@@ -1,7 +0,0 @@
-/** 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

@@ -1,17 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,15 +0,0 @@
-/**
- * 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

@@ -1,18 +0,0 @@
-/**
- * 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

@@ -1,12 +0,0 @@
-/**
- * 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;
-}