@canonical/pragma-cli 0.18.0 → 0.21.0

package/src/domains/shared/renderers.ts

@@ -0,0 +1,410 @@
+/**
+ * Generic list and lookup renderers for CLI and LLM output modes.
+ *
+ * All domain formatters delegate to these pure, layout-only functions.
+ * Each renderer accepts a typed options bag (defined in contracts.ts)
+ * and returns a fully formatted string — no I/O, no side effects.
+ */
+
+import compactUri from "./compactUri.js";
+import type {
+  ColumnDef,
+  RenderListOptions,
+  RenderLookupOptions,
+  SectionDef,
+} from "./contracts.js";
+import { PREFIX_MAP } from "./prefixes.js";
+
+type RenderMode = "plain" | "llm";
+
+export function renderListPlain<T>(
+  items: readonly T[],
+  options: RenderListOptions<T>,
+): string {
+  const prefixes = options.prefixes ?? PREFIX_MAP;
+  const rows = items.map((item) =>
+    options.columns
+      .map((column) => ({
+        column,
+        value: formatColumnValue(item, column, prefixes),
+      }))
+      .filter(({ column, value }) => shouldRenderColumn(column, value))
+      .map(({ value }) => value),
+  );
+
+  const widths = rows.reduce<number[]>(
+    (acc, row) =>
+      row.map((value, index) => Math.max(acc[index] ?? 0, value.length)),
+    [],
+  );
+
+  return rows
+    .map((row) =>
+      row
+        .map((value, index) => value.padEnd(widths[index] ?? value.length))
+        .join("  ")
+        .trimEnd(),
+    )
+    .join("\n");
+}
+
+export function renderListLlm<T>(
+  items: readonly T[],
+  options: RenderListOptions<T>,
+): string {
+  const prefixes = options.prefixes ?? PREFIX_MAP;
+  const lines = [`## ${options.heading} (${items.length})`, ""];
+
+  for (const item of items) {
+    const values = options.columns
+      .map((column) => ({
+        column,
+        value: formatColumnValue(item, column, prefixes),
+      }))
+      .filter(({ column, value }) => shouldRenderColumn(column, value));
+
+    const iri = values.find(({ column }) => column.key === "uri")?.value;
+    const name = values.find(({ column }) => column.key === "name")?.value;
+    const rest = values
+      .filter(({ column }) => column.key !== "uri" && column.key !== "name")
+      .map(({ value }) => value)
+      .filter(Boolean);
+
+    const parts: string[] = [];
+    if (iri) parts.push(`\`${iri}\``);
+    if (name) {
+      parts.push(iri ? `— **${name}**` : `**${name}**`);
+    }
+    if (rest.length > 0) {
+      parts.push(rest.join(" | "));
+    }
+
+    lines.push(`- ${parts.join(" ")}`.trimEnd());
+  }
+
+  return lines.join("\n");
+}
+
+export function renderLookupPlain<T>(
+  entity: T,
+  options: RenderLookupOptions<T>,
+): string {
+  return renderLookup(entity, options, "plain");
+}
+
+export function renderLookupLlm<T>(
+  entity: T,
+  options: RenderLookupOptions<T>,
+): string {
+  return renderLookup(entity, options, "llm");
+}
+
+function renderLookup<T>(
+  entity: T,
+  options: RenderLookupOptions<T>,
+  mode: RenderMode,
+): string {
+  const title = options.title(entity);
+  const fields = renderLookupFields(entity, options, mode);
+  const sections = renderLookupSections(entity, options, mode);
+
+  if (mode === "llm") {
+    return [`## ${title}`, "", ...fields, ...sections].join("\n").trimEnd();
+  }
+
+  const headingRule = "═".repeat(Math.max(title.length, 24));
+  return [title, headingRule, "", ...fields, ...sections].join("\n").trimEnd();
+}
+
+function renderLookupFields<T>(
+  entity: T,
+  options: RenderLookupOptions<T>,
+  mode: RenderMode,
+): string[] {
+  const prefixes = options.prefixes ?? PREFIX_MAP;
+  return options.fields.flatMap((field) => {
+    const value = field.value(entity);
+    if (isEmptyValue(value)) {
+      return [];
+    }
+
+    const formatted = formatInlineValue(value, prefixes);
+    return mode === "llm"
+      ? [`- ${field.label}: ${formatted}`]
+      : [`  ${field.label}: ${formatted}`];
+  });
+}
+
+function renderLookupSections<T>(
+  entity: T,
+  options: RenderLookupOptions<T>,
+  mode: RenderMode,
+): string[] {
+  const sections: string[] = [];
+
+  for (const section of options.sections) {
+    const value = entity[section.key];
+    if (!section.showWhenEmpty && isEmptyValue(value)) {
+      continue;
+    }
+
+    const override = options.sectionOverrides?.[section.key]?.[mode];
+    const body = override
+      ? override(entity, section)
+      : renderSectionValue(value, section, options, mode);
+
+    if (!body) {
+      continue;
+    }
+
+    sections.push("");
+    sections.push(
+      mode === "llm" ? `### ${section.heading}` : `${section.heading}:`,
+    );
+    sections.push(body);
+  }
+
+  return sections;
+}
+
+function renderSectionValue<T>(
+  value: unknown,
+  section: SectionDef<T>,
+  options: RenderLookupOptions<T>,
+  mode: RenderMode,
+): string | null {
+  const prefixes = options.prefixes ?? PREFIX_MAP;
+
+  switch (section.kind) {
+    case "field":
+      return renderFieldValue(value, prefixes, mode);
+    case "code":
+      return renderCodeValue(value, section, options, mode);
+    case "list":
+    case "table":
+    case "nested-table":
+      return renderCollectionValue(value, prefixes, mode);
+    case "tree":
+      return renderTreeValue(value, prefixes, mode);
+    default:
+      return null;
+  }
+}
+
+function renderFieldValue(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+  mode: RenderMode,
+): string | null {
+  if (isEmptyValue(value)) {
+    return null;
+  }
+
+  const text = formatScalarValue(value, prefixes);
+  return mode === "llm" ? text : indentBlock(text);
+}
+
+function renderCodeValue<T>(
+  value: unknown,
+  section: SectionDef<T>,
+  options: RenderLookupOptions<T>,
+  mode: RenderMode,
+): string | null {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    return null;
+  }
+
+  const language =
+    options.codeLanguage?.(section, value) ?? inferCodeLanguage(value);
+  if (mode === "llm") {
+    return [`\`\`\`${language}`, value, "```"].join("\n");
+  }
+
+  const header = language === "text" ? "" : `[${language}]\n`;
+  return indentBlock(`${header}${value}`.trimEnd());
+}
+
+function renderCollectionValue(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+  mode: RenderMode,
+): string | null {
+  if (!Array.isArray(value) || value.length === 0) {
+    return null;
+  }
+
+  const lines = value.map(
+    (entry) => `- ${formatCollectionEntry(entry, prefixes)}`,
+  );
+  return mode === "llm" ? lines.join("\n") : indentBlock(lines.join("\n"));
+}
+
+function renderTreeValue(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+  mode: RenderMode,
+): string | null {
+  const lines = buildTreeLines(value, prefixes);
+  if (lines.length === 0) {
+    return null;
+  }
+
+  return mode === "llm" ? lines.join("\n") : indentBlock(lines.join("\n"));
+}
+
+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)}- ${formatScalarValue(value, prefixes)}`]
+      : [];
+  }
+
+  const rootedTree = value as { root?: unknown };
+  if (rootedTree.root) {
+    return buildTreeLines(rootedTree.root, prefixes, depth);
+  }
+
+  const treeNode = value as {
+    name?: unknown;
+    uri?: unknown;
+    children?: unknown;
+  };
+  const label =
+    typeof treeNode.name === "string" && treeNode.name.length > 0
+      ? treeNode.name
+      : typeof treeNode.uri === "string"
+        ? compactUri(treeNode.uri, prefixes)
+        : "item";
+
+  const lines = [`${"  ".repeat(depth)}- ${label}`];
+  if (Array.isArray(treeNode.children)) {
+    lines.push(...buildTreeLines(treeNode.children, prefixes, depth + 1));
+  }
+  return lines;
+}
+
+function formatCollectionEntry(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  if (!value || typeof value !== "object") {
+    return formatScalarValue(value, prefixes);
+  }
+
+  const object = value as Record<string, unknown>;
+  return Object.entries(object)
+    .filter(([, entryValue]) => !isEmptyValue(entryValue))
+    .map(
+      ([key, entryValue]) =>
+        `${key}: ${formatInlineValue(entryValue, prefixes)}`,
+    )
+    .join(" | ");
+}
+
+function formatColumnValue<T>(
+  item: T,
+  column: ColumnDef<T>,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  const raw = item[column.key];
+  if (column.format) {
+    return column.format(raw);
+  }
+
+  return formatInlineValue(raw, prefixes);
+}
+
+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(([, entryValue]) => !isEmptyValue(entryValue))
+      .map(
+        ([key, entryValue]) =>
+          `${key}=${formatInlineValue(entryValue, prefixes)}`,
+      )
+      .join("; ");
+  }
+
+  return formatScalarValue(value, prefixes);
+}
+
+function formatScalarValue(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  if (value === null || value === undefined) {
+    return "";
+  }
+
+  if (typeof value === "string") {
+    return looksLikeUri(value) ? compactUri(value, prefixes) : value;
+  }
+
+  return String(value);
+}
+
+function shouldRenderColumn<T>(column: ColumnDef<T>, value: string): boolean {
+  if (value.length > 0) {
+    return true;
+  }
+
+  return column.showWhenEmpty === true;
+}
+
+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 looksLikeUri(value: string): boolean {
+  return (
+    value.startsWith("http://") ||
+    value.startsWith("https://") ||
+    /^[a-z][a-z0-9+.-]*:/i.test(value)
+  );
+}
+
+function isEmptyValue(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 indentBlock(value: string, spaces = 2): string {
+  const indent = " ".repeat(spaces);
+  return value
+    .split("\n")
+    .map((line) => `${indent}${line}`)
+    .join("\n");
+}

package/src/domains/shared/runtime.ts

@@ -1,34 +1,19 @@
 /**
  * Unified boot path for pragma CLI, MCP, and completions server.
  *
- * `PragmaRuntime` encapsulates all boot-time state (store, config, cwd).
- * `bootPragma()` is the single factory function that creates it. All three
- * surfaces (CLI, MCP, completions) call `bootPragma()` instead of manually
- * assembling store + config.
+ * `bootPragma()` is the single factory function that creates a
+ * `PragmaRuntime`. All three surfaces (CLI, MCP, completions) call it
+ * instead of manually assembling store + config.
  *
  * @note Impure — reads config from filesystem and boots ke store (WASM + TTL).
  */
 
-import type { SourceSpec, Store } from "@canonical/ke";
-import { type PragmaConfig, readConfig } from "#config";
+import type { SourceSpec } from "@canonical/ke";
+import { readConfig } from "#config";
 import { bootStore } from "./bootStore.js";
+import type { PragmaRuntime } from "./types/index.js";
 
-/**
- * Boot-time state shared by CLI, MCP, and completions server.
- *
- * Four members:
- * - `store` — the ke triple store, loaded and ready for SPARQL queries.
- * - `config` — resolved pragma config (tier, channel).
- * - `cwd` — working directory used for config and source resolution.
- * - `dispose()` — tears down the store and frees WASM memory. Must be
- *   called exactly once; calling operations after dispose is undefined.
- */
-export interface PragmaRuntime {
-  readonly store: Store;
-  readonly config: PragmaConfig;
-  readonly cwd: string;
-  dispose(): void;
-}
+export type { PragmaRuntime } from "./types/index.js";
 
 /**
  * Create a fully initialized `PragmaRuntime`.

package/src/domains/shared/types/block.ts

@@ -0,0 +1,107 @@
+/** Block domain return types. */
+
+import type { URI } from "@canonical/ke";
+import type { StandardRef } from "./standard.js";
+import type { TokenRef } from "./token.js";
+
+/** Summary view of a design-system block (component, pattern, or primitive). */
+export interface BlockSummary {
+  /** Full RDF URI identifying this block in the ke store. */
+  readonly uri: URI;
+  /** Human-readable name (local name extracted from URI). */
+  readonly name: string;
+  /** Normalized ontology type for the block. */
+  readonly type: "component" | "pattern" | "layout" | "subcomponent";
+  /** Tier path this block belongs to (e.g., `"global"`, `"apps/lxd"`). */
+  readonly tier: string;
+  /** Active modifier names applied to this block. */
+  readonly modifiers: readonly string[];
+  /** Framework implementations declared for this block, with availability flags. */
+  readonly implementations: readonly {
+    framework: string;
+    available: boolean;
+  }[];
+  /** Number of anatomy nodes (DOM elements) in this block's anatomy tree. */
+  readonly nodeCount: number;
+  /** Number of design tokens referenced by this block. */
+  readonly tokenCount: number;
+}
+
+/** Digest view of a block for richer summary displays. */
+export interface BlockDigest extends BlockSummary {
+  /** Summary guidance when present in the graph. */
+  readonly summary: string | null;
+}
+
+/** Single node in a block's anatomy tree (recursive). */
+export interface AnatomyNode {
+  /** Element name (e.g., `"trigger"`, `"panel"`). */
+  readonly name: string;
+  /** Whether the node is explicitly named or inferred as anonymous. */
+  readonly type: "named" | "anonymous";
+  /** Child nodes nested under this element. */
+  readonly children: readonly AnatomyNode[];
+  /** Named slot this node exposes, if any. */
+  readonly slot?: string;
+}
+
+/** Wrapper around the root of a block's anatomy tree. */
+export interface AnatomyTree {
+  /** Top-level anatomy node from which all children descend. */
+  readonly root: AnatomyNode;
+}
+
+/** Recursive subcomponent entry used in block detailed views. */
+export interface BlockSubcomponent {
+  /** Full RDF URI of the subcomponent. */
+  readonly uri: URI;
+  /** Human-readable subcomponent name. */
+  readonly name: string;
+  /** Nested subcomponents owned by this subcomponent. */
+  readonly children: readonly BlockSubcomponent[];
+}
+
+/** Detailed view of a block, extending the digest with anatomy, tokens, and standards. */
+export interface BlockDetailed extends BlockDigest {
+  /** Guidance on when the block should be used. */
+  readonly whenToUse: string | null;
+  /** Guidance on when the block should not be used. */
+  readonly whenNotToUse: string | null;
+  /** Additional usage guidance. */
+  readonly guidelines: string | null;
+  /** YAML anatomy DSL payload when present. */
+  readonly anatomyDsl: string | null;
+  /** Legacy anatomy payload when present. */
+  readonly anatomyClassic: string | null;
+  /** Figma reference link when present. */
+  readonly figmaLink: string | null;
+  /** Full anatomy tree, or `null` if the block declares no anatomy. */
+  readonly anatomy: AnatomyTree | null;
+  /** Modifier families with their allowed values. */
+  readonly modifierValues: readonly {
+    family: string;
+    values: readonly string[];
+  }[];
+  /** Modifier families resolved as richer objects. */
+  readonly modifierFamilies: readonly {
+    uri: URI;
+    name: string;
+    values: readonly string[];
+  }[];
+  /** Property metadata resolved from blank nodes. */
+  readonly properties: readonly {
+    name: string;
+    propertyType: string;
+    optional: boolean;
+    defaultValue: string | null;
+    constraints: string | null;
+  }[];
+  /** Direct subcomponents of the block. */
+  readonly subcomponents: readonly BlockSubcomponent[];
+  /** File paths to framework-specific implementations. */
+  readonly implementationPaths: readonly { framework: string; path: string }[];
+  /** Design tokens referenced by this block. */
+  readonly tokens: readonly TokenRef[];
+  /** Standards (guidelines/rules) that apply to this block. */
+  readonly standards: readonly StandardRef[];
+}

package/src/domains/shared/types/common.ts

@@ -0,0 +1,33 @@
+/** Shared cross-domain types used by multiple domains and contracts. */
+
+/** Runtime filter settings controlling tier and channel visibility in queries. */
+export interface FilterConfig {
+  /** Active tier path, or `undefined` for all-tiers visibility. */
+  readonly tier: string | undefined;
+  /** Release channel determining which stability levels are visible. */
+  readonly channel: "normal" | "experimental" | "prerelease";
+}
+
+/**
+ * Controls how much detail an operation returns.
+ *
+ * - `"summary"` — minimal fields (names and counts).
+ * - `"digest"` — intermediate detail with optional example length cap.
+ * - `"detailed"` — full content including code blocks and anatomy.
+ */
+export type Disclosure =
+  | { readonly level: "summary" }
+  | { readonly level: "digest"; readonly maxExampleLength?: number }
+  | { readonly level: "detailed" };
+
+/** Outcome of a batch operation: successful results alongside per-item errors. */
+export interface BatchResult<T> {
+  /** Items that were processed successfully. */
+  readonly results: readonly T[];
+  /** Items that failed, each carrying the entity name, error code, and message. */
+  readonly errors: readonly {
+    name: string;
+    code: string;
+    message: string;
+  }[];
+}

package/src/domains/shared/types/graph.ts

@@ -0,0 +1,17 @@
+/** Graph inspection return types. */
+
+/** A predicate group from `graph inspect`: one predicate with all its objects. */
+export interface PredicateGroup {
+  /** RDF predicate URI (e.g., `"rdfs:label"`). */
+  readonly predicate: string;
+  /** Object values (URIs or literals) associated with this predicate. */
+  readonly objects: readonly string[];
+}
+
+/** Result of `graph inspect <uri>`: all triples where URI is subject. */
+export interface InspectResult {
+  /** The inspected subject URI. */
+  readonly uri: string;
+  /** Predicate groups aggregating all outgoing triples. */
+  readonly groups: readonly PredicateGroup[];
+}

package/src/domains/shared/types/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @module types
+ *
+ * Shared operation return types — contract between operations (D3) and
+ * CLI/MCP adapters. Same data, different presentations.
+ *
+ * Per-domain files keep each concern isolated; this barrel re-exports
+ * everything for consumers that import from `shared/types/index.js`.
+ */
+
+export type {
+  AnatomyNode,
+  AnatomyTree,
+  BlockDetailed,
+  BlockDigest,
+  BlockSubcomponent,
+  BlockSummary,
+} from "./block.js";
+export type { BatchResult, Disclosure, FilterConfig } from "./common.js";
+export type { InspectResult, PredicateGroup } from "./graph.js";
+export type {
+  ModifierDetailed,
+  ModifierDigest,
+  ModifierFamily,
+  ModifierSummary,
+} from "./modifier.js";
+export type {
+  OntologyClass,
+  OntologyDetailed,
+  OntologyProperty,
+  OntologySummary,
+} from "./ontology.js";
+export type { PragmaRuntime } from "./runtime.js";
+export type {
+  CategorySummary,
+  CodeBlock,
+  StandardDetailed,
+  StandardDigest,
+  StandardListFilters,
+  StandardRef,
+  StandardSummary,
+} from "./standard.js";
+export type { TierEntry } from "./tier.js";
+export type {
+  TokenDetailed,
+  TokenDigest,
+  TokenRef,
+  TokenSummary,
+} from "./token.js";

package/src/domains/shared/types/modifier.ts

@@ -0,0 +1,22 @@
+/** Modifier domain return types. */
+
+import type { URI } from "@canonical/ke";
+
+/** A modifier family (e.g., "size", "variant") with its allowed values. */
+export interface ModifierFamily {
+  /** Full RDF URI identifying this modifier family. */
+  readonly uri: URI;
+  /** Human-readable family name. */
+  readonly name: string;
+  /** Allowed values within this family (e.g., `["small", "medium", "large"]`). */
+  readonly values: readonly string[];
+}
+
+/** Summary view of a modifier family. */
+export type ModifierSummary = ModifierFamily;
+
+/** Digest view of a modifier family for generic list contracts. */
+export type ModifierDigest = ModifierSummary;
+
+/** Detailed view of a modifier family. */
+export type ModifierDetailed = ModifierFamily;