@canonical/pragma-cli 0.18.0

package/src/domains/shared/contracts.ts

@@ -0,0 +1,113 @@
+/**
+ * Shared command and entity-display contracts.
+ *
+ * These types provide the structural common ground for CLI and MCP surfaces.
+ */
+
+import type { FilterConfig } from "./types.js";
+
+export interface ColumnDef<T> {
+  readonly key: keyof T & string;
+  readonly label: string;
+  readonly format?: (value: unknown) => string;
+  readonly showWhenEmpty?: boolean;
+}
+
+export type SectionKind =
+  | "field"
+  | "code"
+  | "list"
+  | "table"
+  | "nested-table"
+  | "tree";
+
+export interface SectionDef<T> {
+  readonly key: keyof T & string;
+  readonly heading: string;
+  readonly kind: SectionKind;
+  readonly showWhenEmpty?: boolean;
+}
+
+export interface ListParams {
+  readonly allTiers?: boolean;
+  readonly digest?: boolean;
+  readonly detailed?: boolean;
+  readonly condensed?: boolean;
+}
+
+export interface LookupParams {
+  readonly names: readonly string[];
+  readonly detailed?: boolean;
+  readonly condensed?: boolean;
+}
+
+export interface ListResult<T> {
+  readonly items: readonly T[];
+  readonly filters: FilterConfig;
+  readonly disclosure:
+    | { readonly level: "summary" }
+    | { readonly level: "digest"; readonly maxExampleLength?: number }
+    | { readonly level: "detailed" };
+}
+
+export interface LookupResult<T> {
+  readonly results: readonly T[];
+  readonly errors: readonly {
+    query: string;
+    code: string;
+    message: string;
+  }[];
+}
+
+export interface ShowContract<T> {
+  readonly result: T;
+}
+
+export interface MutateContract<TParams, TResult> {
+  readonly params: TParams;
+  readonly result: TResult;
+  readonly confirmation: string;
+}
+
+export interface ListContract<
+  TSummary,
+  TDigest extends TSummary,
+  TDetailed extends TDigest,
+> {
+  readonly params: ListParams;
+  readonly result: ListResult<TSummary | TDigest | TDetailed>;
+}
+
+export interface LookupContract<TDetailed> {
+  readonly params: LookupParams;
+  readonly result: LookupResult<TDetailed>;
+}
+
+export interface EntityDisplayConfig<
+  TSummary,
+  TDigest extends TSummary,
+  TDetailed extends TDigest,
+> {
+  readonly domain: string;
+  readonly entityName: string;
+  readonly rdfTypes: readonly string[];
+  readonly listColumns: readonly ColumnDef<TSummary>[];
+  readonly digestColumns: readonly ColumnDef<TDigest>[];
+  readonly lookupSections: readonly SectionDef<TDetailed>[];
+  readonly emptyRecovery: (filters: FilterConfig) => {
+    readonly message: string;
+    readonly cli?: string;
+    readonly mcp?: {
+      readonly tool: string;
+      readonly params?: Record<string, unknown>;
+    };
+  };
+  readonly notFoundRecovery: (query: string) => {
+    readonly message: string;
+    readonly cli?: string;
+    readonly mcp?: {
+      readonly tool: string;
+      readonly params?: Record<string, unknown>;
+    };
+  };
+}

package/src/domains/shared/extractLocalName.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import extractLocalName from "./extractLocalName.js";
+import { PREFIX_MAP } from "./prefixes.js";
+
+describe("extractLocalName", () => {
+  it("extracts after hash", () => {
+    expect(extractLocalName("http://example.org/ns#Thing")).toBe("Thing");
+  });
+
+  it("extracts after last slash", () => {
+    expect(extractLocalName(`${PREFIX_MAP.ds}global`)).toBe("global");
+  });
+
+  it("returns full string when no separator", () => {
+    expect(extractLocalName("plain")).toBe("plain");
+  });
+
+  it("handles nested path", () => {
+    expect(extractLocalName(`${PREFIX_MAP.ds}apps/lxd`)).toBe("lxd");
+  });
+});

package/src/domains/shared/extractLocalName.ts

@@ -0,0 +1,14 @@
+/**
+ * Extract the local name from a full URI.
+ *
+ * `"https://ds.canonical.com/global"` → `"global"`
+ * `"http://example.org/ns#Thing"` → `"Thing"`
+ */
+
+export default function extractLocalName(uri: string): string {
+  const hashIdx = uri.lastIndexOf("#");
+  if (hashIdx !== -1) return uri.slice(hashIdx + 1);
+  const slashIdx = uri.lastIndexOf("/");
+  if (slashIdx !== -1) return uri.slice(slashIdx + 1);
+  return uri;
+}

package/src/domains/shared/filters/buildChannelFilter.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { P } from "../prefixes.js";
+import { buildChannelFilter, CHANNEL_RELEASES } from "./buildChannelFilter.js";
+
+describe("CHANNEL_RELEASES", () => {
+  it("normal includes only stable", () => {
+    expect(CHANNEL_RELEASES.normal).toEqual(["stable"]);
+  });
+
+  it("experimental includes stable + experimental", () => {
+    expect(CHANNEL_RELEASES.experimental).toEqual(["stable", "experimental"]);
+  });
+
+  it("prerelease includes all four", () => {
+    expect(CHANNEL_RELEASES.prerelease).toEqual([
+      "stable",
+      "experimental",
+      "alpha",
+      "beta",
+    ]);
+  });
+});
+
+describe("buildChannelFilter", () => {
+  it("generates OPTIONAL + FILTER for normal", () => {
+    const result = buildChannelFilter("normal");
+    expect(result).toContain(`OPTIONAL { ?component ${P.ds}release ?release }`);
+    expect(result).toContain(
+      `FILTER(!BOUND(?release) || ?release IN (${P.ds}stable))`,
+    );
+  });
+
+  it("generates filter for experimental with two releases", () => {
+    const result = buildChannelFilter("experimental");
+    expect(result).toContain(
+      `?release IN (${P.ds}stable, ${P.ds}experimental)`,
+    );
+  });
+
+  it("generates filter for prerelease with all releases", () => {
+    const result = buildChannelFilter("prerelease");
+    expect(result).toContain(
+      `?release IN (${P.ds}stable, ${P.ds}experimental, ${P.ds}alpha, ${P.ds}beta)`,
+    );
+  });
+
+  it("uses custom variable name", () => {
+    const result = buildChannelFilter("normal", "r");
+    expect(result).toContain(`?r IN (${P.ds}stable)`);
+    expect(result).toContain("BOUND(?r)");
+  });
+});

package/src/domains/shared/filters/buildChannelFilter.ts

@@ -0,0 +1,41 @@
+/**
+ * Channel filter — release stability visibility.
+ *
+ * Maps channel settings to the set of visible release levels.
+ * Components without a release annotation are treated as stable.
+ */
+
+import type { Channel } from "#constants";
+import { P } from "../prefixes.js";
+
+/**
+ * Release levels visible per channel setting.
+ */
+export const CHANNEL_RELEASES: Record<Channel, readonly string[]> = {
+  normal: ["stable"],
+  experimental: ["stable", "experimental"],
+  prerelease: ["stable", "experimental", "alpha", "beta"],
+};
+
+/**
+ * Generate SPARQL clauses for channel visibility.
+ *
+ * Uses OPTIONAL + FILTER pattern: binds ?release if present,
+ * then filters to allowed values OR unbound (= stable default).
+ *
+ * @param channel - Configured channel.
+ * @param varName - SPARQL variable to filter (default: `"release"`).
+ * @returns SPARQL OPTIONAL + FILTER clause string.
+ */
+export function buildChannelFilter(
+  channel: Channel,
+  varName = "release",
+): string {
+  const releases = CHANNEL_RELEASES[channel];
+  const uriList = releases.map((r) => `${P.ds}${r}`).join(", ");
+
+  return [
+    `OPTIONAL { ?component ${P.ds}release ?${varName} }`,
+    `FILTER(!BOUND(?${varName}) || ?${varName} IN (${uriList}))`,
+  ].join("\n    ");
+}

package/src/domains/shared/filters/buildFilterConfig.ts

@@ -0,0 +1,16 @@
+/**
+ * Build a FilterConfig from runtime config, optionally widening tier.
+ */
+
+import type { PragmaRuntime } from "../runtime.js";
+import type { FilterConfig } from "../types.js";
+
+export default function buildFilterConfig(
+  runtime: PragmaRuntime,
+  allTiers?: boolean,
+): FilterConfig {
+  return {
+    tier: allTiers ? undefined : runtime.config.tier,
+    channel: runtime.config.channel,
+  };
+}

package/src/domains/shared/filters/buildFilters.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { P } from "../prefixes.js";
+import { buildFilters } from "./buildFilters.js";
+
+describe("buildFilters", () => {
+  it("returns only channel filter when tier is undefined", () => {
+    const result = buildFilters({ tier: undefined, channel: "normal" });
+    expect(result).not.toContain("FILTER(?tier");
+    expect(result).toContain("FILTER(!BOUND(?release)");
+  });
+
+  it("combines tier and channel filters", () => {
+    const result = buildFilters({ tier: "apps/lxd", channel: "experimental" });
+    expect(result).toContain(
+      `FILTER(?tier IN (${P.ds}global, ${P.ds}apps, ${P.ds}apps_lxd))`,
+    );
+    expect(result).toContain(`${P.ds}stable, ${P.ds}experimental`);
+  });
+
+  it("returns channel filter for undefined tier + prerelease", () => {
+    const result = buildFilters({ tier: undefined, channel: "prerelease" });
+    expect(result).toContain(`${P.ds}alpha, ${P.ds}beta`);
+    expect(result).not.toContain("FILTER(?tier");
+  });
+
+  it("returns both filters for global tier + normal channel", () => {
+    const result = buildFilters({ tier: "global", channel: "normal" });
+    expect(result).toContain(`FILTER(?tier IN (${P.ds}global))`);
+    expect(result).toContain(
+      `FILTER(!BOUND(?release) || ?release IN (${P.ds}stable))`,
+    );
+  });
+});

package/src/domains/shared/filters/buildFilters.ts

@@ -0,0 +1,30 @@
+/**
+ * Orthogonal filter combination.
+ *
+ * Both tier and channel filters apply simultaneously as AND constraints.
+ */
+
+import type { FilterConfig } from "../types.js";
+import { buildChannelFilter } from "./buildChannelFilter.js";
+import { buildTierFilter } from "./buildTierFilter.js";
+
+/**
+ * Build combined WHERE clause fragments for tier + channel filters.
+ *
+ * Returns a string to insert into a SPARQL WHERE clause body.
+ * Each filter is independently optional.
+ *
+ * @param config - Tier and channel filter settings.
+ * @returns Combined SPARQL clause fragments.
+ */
+export function buildFilters(config: FilterConfig): string {
+  const parts: string[] = [];
+
+  const tierClause = buildTierFilter(config.tier);
+  if (tierClause) parts.push(tierClause);
+
+  const channelClause = buildChannelFilter(config.channel);
+  parts.push(channelClause);
+
+  return parts.join("\n    ");
+}

package/src/domains/shared/filters/buildTierFilter.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import { P } from "../prefixes.js";
+import {
+  buildTierFilter,
+  resolveTierChain,
+  tierPathToLocal,
+} from "./buildTierFilter.js";
+
+describe("resolveTierChain", () => {
+  it("returns empty array for undefined", () => {
+    expect(resolveTierChain(undefined)).toEqual([]);
+  });
+
+  it("returns ['global'] for 'global'", () => {
+    expect(resolveTierChain("global")).toEqual(["global"]);
+  });
+
+  it("returns ['global', 'apps'] for 'apps'", () => {
+    expect(resolveTierChain("apps")).toEqual(["global", "apps"]);
+  });
+
+  it("returns full chain for 'apps/lxd'", () => {
+    expect(resolveTierChain("apps/lxd")).toEqual([
+      "global",
+      "apps",
+      "apps/lxd",
+    ]);
+  });
+
+  it("handles deep nesting", () => {
+    expect(resolveTierChain("apps/lxd/storage")).toEqual([
+      "global",
+      "apps",
+      "apps/lxd",
+      "apps/lxd/storage",
+    ]);
+  });
+});
+
+describe("tierPathToLocal", () => {
+  it("converts slashes to underscores", () => {
+    expect(tierPathToLocal("apps/lxd")).toBe("apps_lxd");
+  });
+
+  it("leaves single segment unchanged", () => {
+    expect(tierPathToLocal("global")).toBe("global");
+  });
+
+  it("handles deep paths", () => {
+    expect(tierPathToLocal("apps/lxd/storage")).toBe("apps_lxd_storage");
+  });
+});
+
+describe("buildTierFilter", () => {
+  it("returns empty string for undefined tier", () => {
+    expect(buildTierFilter(undefined)).toBe("");
+  });
+
+  it("generates FILTER for 'global'", () => {
+    expect(buildTierFilter("global")).toBe(`FILTER(?tier IN (${P.ds}global))`);
+  });
+
+  it("generates FILTER for 'apps/lxd' with parent chain", () => {
+    expect(buildTierFilter("apps/lxd")).toBe(
+      `FILTER(?tier IN (${P.ds}global, ${P.ds}apps, ${P.ds}apps_lxd))`,
+    );
+  });
+
+  it("normalizes mixed-case tier paths from config", () => {
+    expect(buildTierFilter("Global")).toBe(`FILTER(?tier IN (${P.ds}global))`);
+  });
+
+  it("uses custom variable name", () => {
+    expect(buildTierFilter("apps", "t")).toBe(
+      `FILTER(?t IN (${P.ds}global, ${P.ds}apps))`,
+    );
+  });
+});

package/src/domains/shared/filters/buildTierFilter.ts

@@ -0,0 +1,69 @@
+import { P } from "../prefixes.js";
+
+/**
+ * Tier filter — hierarchical visibility.
+ *
+ * Setting a tier activates a parent chain filter.
+ * `"apps/lxd"` -> visible tiers: `global`, `apps`, `apps/lxd`.
+ */
+
+/**
+ * Resolve the parent chain for a tier path.
+ *
+ * "apps/lxd" -> ["global", "apps", "apps/lxd"]
+ * "apps" -> ["global", "apps"]
+ * "global" -> ["global"]
+ * undefined -> [] (no filter -- all tiers visible)
+ *
+ * @param tierPath - Slash-separated tier path, or `undefined` for no filtering.
+ * @returns Ordered array of tier paths from root to leaf.
+ */
+export function resolveTierChain(tierPath: string | undefined): string[] {
+  if (tierPath === undefined) return [];
+
+  const normalizedTierPath = tierPath.trim().toLowerCase();
+
+  const chain: string[] = ["global"];
+  const segments = normalizedTierPath.split("/");
+
+  for (let i = 0; i < segments.length; i++) {
+    const path = segments.slice(0, i + 1).join("/");
+    if (path !== "global") {
+      chain.push(path);
+    }
+  }
+
+  return chain;
+}
+
+/**
+ * Convert a tier path to its URI local name.
+ * Slashes become underscores: `"apps/lxd"` -> `"apps_lxd"`.
+ *
+ * @param tierPath - Slash-separated tier path.
+ * @returns Underscore-separated local name suitable for URI construction.
+ */
+export function tierPathToLocal(tierPath: string): string {
+  return tierPath.trim().toLowerCase().replace(/\//g, "_");
+}
+
+/**
+ * Generate a SPARQL FILTER clause for tier visibility.
+ *
+ * Returns an empty string when tier is undefined (no filter = all tiers visible).
+ *
+ * @param tierPath - Configured tier path (e.g., `"apps/lxd"`) or `undefined`.
+ * @param varName - SPARQL variable to filter (default: `"tier"`).
+ * @returns SPARQL FILTER clause string, or empty string when no tier is set.
+ */
+export function buildTierFilter(
+  tierPath: string | undefined,
+  varName = "tier",
+): string {
+  if (tierPath === undefined) return "";
+
+  const chain = resolveTierChain(tierPath);
+  const uriList = chain.map((t) => `${P.ds}${tierPathToLocal(t)}`).join(", ");
+
+  return `FILTER(?${varName} IN (${uriList}))`;
+}

package/src/domains/shared/filters/describeFilters.ts

@@ -0,0 +1,14 @@
+/**
+ * Describe active filters as human-readable key-value pairs.
+ */
+
+import type { FilterConfig } from "../types.js";
+
+export default function describeFilters(
+  filters: FilterConfig,
+): Record<string, string> {
+  return {
+    ...(filters.tier !== undefined && { tier: filters.tier }),
+    channel: filters.channel,
+  };
+}

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

@@ -0,0 +1,10 @@
+/** @module Shared SPARQL filter builders for tier and channel visibility. */
+export { buildChannelFilter, CHANNEL_RELEASES } from "./buildChannelFilter.js";
+export { default as buildFilterConfig } from "./buildFilterConfig.js";
+export { buildFilters } from "./buildFilters.js";
+export {
+  buildTierFilter,
+  resolveTierChain,
+  tierPathToLocal,
+} from "./buildTierFilter.js";
+export { default as describeFilters } from "./describeFilters.js";

package/src/domains/shared/formatters.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared formatter infrastructure for CLI output modes.
+ *
+ * Every command must support three output modes: plain (terminal),
+ * llm (condensed Markdown), and json (structured). The `Formatters<T>`
+ * type enforces this contract. `selectFormatter` eliminates the
+ * duplicated if/else dispatch in every command's execute function.
+ */
+
+import type { CommandContext } from "@canonical/cli-core";
+
+/**
+ * The three output modes every command must support.
+ *
+ * Each formatter is a pure function from data to string.
+ */
+export interface Formatters<T> {
+  readonly plain: (data: T) => string;
+  readonly llm: (data: T) => string;
+  readonly json: (data: T) => string;
+}
+
+/**
+ * Pick the right formatter based on global flags.
+ *
+ * Precedence: `--format json` > `--llm` > plain.
+ */
+export function selectFormatter<T>(
+  ctx: CommandContext,
+  formatters: Formatters<T>,
+): (data: T) => string {
+  if (ctx.globalFlags.format === "json") return formatters.json;
+  if (ctx.globalFlags.llm) return formatters.llm;
+  return formatters.plain;
+}

package/src/domains/shared/lookupMany.ts

@@ -0,0 +1,45 @@
+import { PragmaError } from "#error";
+import type { LookupResult } from "./contracts.js";
+
+/**
+ * Resolve multiple lookup queries and collect structured per-query failures.
+ *
+ * Used by MCP lookup tools so a single call can return multiple results
+ * without failing the entire request when one query is missing.
+ */
+export default async function lookupMany<TResult>(
+  queries: readonly string[],
+  lookup: (query: string) => Promise<TResult>,
+): Promise<LookupResult<TResult>> {
+  const errors: Array<{ query: string; code: string; message: string }> = [];
+  const settled = await Promise.allSettled(
+    queries.map((query) => lookup(query)),
+  );
+  const results: TResult[] = [];
+
+  for (const [index, outcome] of settled.entries()) {
+    const query = queries[index];
+    if (!query) {
+      continue;
+    }
+
+    if (outcome.status === "fulfilled") {
+      results.push(outcome.value);
+      continue;
+    }
+
+    const error = outcome.reason;
+
+    if (error instanceof PragmaError) {
+      errors.push({
+        query,
+        code: error.code,
+        message: error.message,
+      });
+    } else {
+      throw error;
+    }
+  }
+
+  return { results, errors };
+}

package/src/domains/shared/namespaces.ts

@@ -0,0 +1,18 @@
+/**
+ * Namespace helpers for SPARQL queries.
+ *
+ * Derived from {@link PREFIX_MAP} via {@link createNamespace} for use
+ * in the `sparql` tagged template.
+ */
+
+import { createNamespace } from "@canonical/ke";
+import { PREFIX_MAP } from "./prefixes.js";
+
+/** Design system namespace — classes, properties, and instances (e.g., `ds:Component`). */
+export const ds = createNamespace(PREFIX_MAP.ds);
+/** Component specification namespace — component-level metadata (e.g., `cs:anatomy`). */
+export const cs = createNamespace(PREFIX_MAP.cs);
+/** RDF Schema namespace — core vocabulary (e.g., `rdfs:label`, `rdfs:subClassOf`). */
+export const rdfs = createNamespace(PREFIX_MAP.rdfs);
+/** OWL namespace — ontology constructs (e.g., `owl:Class`, `owl:ObjectProperty`). */
+export const owl = createNamespace(PREFIX_MAP.owl);

package/src/domains/shared/packages.ts

@@ -0,0 +1,76 @@
+/**
+ * Design system package registry.
+ *
+ * Single source of truth for all external packages that provide TTL data
+ * and/or agent skills. Both `bootStore` (TTL sources) and `resolveSkillSources`
+ * (skill discovery) derive their paths from this registry.
+ *
+ * Each entry declares:
+ * - `pkg`    — npm package name (resolved via `require.resolve`)
+ * - `ttl`    — glob patterns for TTL data, relative to the package root
+ * - `skills` — subpath to the skills directory, or `undefined` if none
+ */
+
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+
+const require = createRequire(import.meta.url);
+
+export interface PackageDefinition {
+  /** npm package name. */
+  readonly pkg: string;
+  /** Glob patterns for TTL data (relative to package root). */
+  readonly ttl: readonly string[];
+  /** Subpath to skills directory, or undefined if the package has no skills. */
+  readonly skills: string | undefined;
+}
+
+export const PACKAGES: readonly PackageDefinition[] = [
+  {
+    pkg: "@canonical/design-system",
+    ttl: ["definitions/ontology.ttl", "data/**/*.ttl"],
+    skills: "skills",
+  },
+  {
+    pkg: "@canonical/anatomy-dsl",
+    ttl: ["definitions/**/*.ttl"],
+    skills: undefined,
+  },
+  {
+    pkg: "@canonical/code-standards",
+    ttl: ["definitions/**/*.ttl", "data/**/*.ttl"],
+    skills: "skills",
+  },
+  {
+    pkg: "@canonical/pragma-cli",
+    ttl: [],
+    skills: "skills",
+  },
+];
+
+export interface ResolvedPackage {
+  /** npm package name. */
+  readonly pkg: string;
+  /** Absolute path to the package root. */
+  readonly dir: string;
+}
+
+/**
+ * Resolve installed packages from the registry via `require.resolve`.
+ * Package-manager agnostic — works with bun, npm, pnpm, yarn.
+ * Skips packages that are not installed.
+ */
+export function resolvePackages(): ResolvedPackage[] {
+  const resolved: ResolvedPackage[] = [];
+  for (const { pkg } of PACKAGES) {
+    try {
+      resolved.push({
+        pkg,
+        dir: dirname(require.resolve(`${pkg}/package.json`)),
+      });
+    } catch {
+      // package not installed — skip
+    }
+  }
+  return resolved;
+}