@canonical/pragma-cli 0.31.0 → 0.32.0

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

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

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

@@ -1,145 +0,0 @@
-/** Ontology inspection return types. */
-
-/** Summary of a loaded ontology namespace from `ontology list`. */
-export interface OntologySummary {
-  /** Short prefix alias (e.g., `"ds"`), or `""` when none is registered. */
-  readonly prefix: string;
-  /** Full namespace URI the prefix expands to. */
-  readonly namespace: string;
-  /** rdfs:label of the namespace's owl:Ontology header, when declared. */
-  readonly title?: string;
-  /** owl:versionInfo of the namespace's owl:Ontology header, when declared. */
-  readonly version?: string;
-  /** Number of OWL/RDFS classes defined in this namespace. */
-  readonly classCount: number;
-  /** Number of object properties (class-to-class relations). */
-  readonly relationCount: number;
-  /** Number of datatype properties (literal-valued attributes). */
-  readonly attributeCount: number;
-  /** Number of SHACL node shapes constraining this namespace. */
-  readonly shapeCount: number;
-  readonly anatomyCount: number;
-}
-
-/**
- * A property in an ontology namespace.
- *
- * All IRIs are compact (`ds:tier`); the owning {@link OntologyDetailed}
- * carries the `prefixes` map needed to expand them.
- */
-export interface OntologyProperty {
-  /** Compact IRI of the property. */
-  readonly iri: string;
-  /** Human-readable label (rdfs:label, falling back to the local name). */
-  readonly label: string;
-  /** Whether this is an object property (links classes) or datatype property (links to literals). */
-  readonly kind: "object" | "datatype";
-  /** Compact IRI of the domain class this property applies to, if declared. */
-  readonly domain?: string;
-  /** Compact IRI of the range class or datatype, if declared. */
-  readonly range?: string;
-  /** Present (true) when the property is an owl:FunctionalProperty. */
-  readonly functional?: true;
-}
-
-/**
- * A class in an ontology's class hierarchy.
- *
- * Classes arrive in deterministic topological order (roots first,
- * alphabetical among siblings) with their direct properties attached.
- */
-export interface OntologyClass {
-  /** Compact IRI of the class. */
-  readonly iri: string;
-  /** Human-readable label (rdfs:label, falling back to the local name). */
-  readonly label: string;
-  /** Class documentation (rdfs:comment), omitted when absent. */
-  readonly comment?: string;
-  /** Compact IRIs of all direct superclasses (empty for roots). */
-  readonly subClassOf: readonly string[];
-  /** Number of instances typed with this class, omitted when zero. */
-  readonly instances?: number;
-  /** Properties whose rdfs:domain is this class. */
-  readonly properties: readonly OntologyProperty[];
-}
-
-/** Summary of a SHACL node shape constraining a class. */
-export interface OntologyConstraint {
-  /** Compact IRI of the sh:NodeShape. */
-  readonly shape: string;
-  /** Compact IRI of the sh:targetClass, if declared. */
-  readonly targetClass?: string;
-  /** Number of sh:property constraints on the shape. */
-  readonly propertyCount: number;
-}
-
-/** owl:Ontology header metadata, when the namespace declares one. */
-export interface OntologyMeta {
-  /** rdfs:label / dcterms:title of the ontology node. */
-  readonly title?: string;
-  /** owl:versionInfo. */
-  readonly version?: string;
-  /** Compact IRIs of owl:imports. */
-  readonly imports?: readonly string[];
-}
-
-/** A ready-to-run SPARQL hint for follow-up querying. */
-export interface OntologyQueryHint {
-  /** What the query answers (e.g. "instances of ds:Component"). */
-  readonly label: string;
-  /**
-   * SPARQL using compact IRIs — runnable as-is via `pragma graph query`,
-   * which resolves the store's prefix map.
-   */
-  readonly sparql: string;
-}
-
-/** Deep-dive view of one class, produced by `ontology show <ns> --class <C>`. */
-export interface OntologyClassFocus {
-  /** Compact IRI of the focused class. */
-  readonly iri: string;
-  readonly label: string;
-  readonly comment?: string;
-  /** Superclass chain within the namespace, nearest first. */
-  readonly superChain: readonly string[];
-  /** Compact IRIs of direct subclasses. */
-  readonly subclasses: readonly string[];
-  /** Number of instances typed with this class. */
-  readonly instances: number;
-  /** Properties declared directly on this class. */
-  readonly directProperties: readonly OntologyProperty[];
-  /** Properties inherited from the super chain. */
-  readonly inheritedProperties: readonly OntologyProperty[];
-  /** Properties elsewhere in the namespace whose range is this class. */
-  readonly referencedBy: readonly OntologyProperty[];
-  /** Up to a few instance IRIs, as entry points for `graph inspect` / lookups. */
-  readonly sampleInstances: readonly string[];
-  /** Ready-to-run SPARQL for the natural follow-up questions. */
-  readonly queries: readonly OntologyQueryHint[];
-}
-
-/**
- * Detailed view of a single ontology namespace from `ontology show`.
- *
- * This is the single complete structure every output mode projects:
- * plain, `--llm`, `--format json`, and the MCP `ontology_show` envelope
- * all render from this shape and nothing else.
- */
-export interface OntologyDetailed {
-  /** Short prefix alias (e.g., `"ds"`). */
-  readonly prefix: string;
-  /** Full namespace URI the prefix expands to. */
-  readonly namespace: string;
-  /** Prefix map covering every compact IRI used in this structure. */
-  readonly prefixes: Readonly<Record<string, string>>;
-  /** owl:Ontology header metadata, omitted when the namespace declares none. */
-  readonly meta?: OntologyMeta;
-  /** All classes, topologically ordered, with direct properties attached. */
-  readonly classes: readonly OntologyClass[];
-  /** Properties with no domain, or a domain outside this namespace's classes. */
-  readonly unattached: readonly OntologyProperty[];
-  /** SHACL node-shape summaries, omitted when none exist. */
-  readonly constraints?: readonly OntologyConstraint[];
-  /** Per-class deep dive, present when a class filter was requested. */
-  readonly focus?: OntologyClassFocus;
-}

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

@@ -1,24 +0,0 @@
-/** Boot-time state shared by CLI, MCP, and completions server. */
-
-import type { Store } from "@canonical/ke";
-import type { PragmaConfig } from "#config";
-import type { SemanticPackage } from "../semanticPackage.js";
-
-/**
- * Boot-time state shared by CLI, MCP, and completions server.
- *
- * Five 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.
- * - `packages` — resolved semantic packages (for diagnostics and skills).
- * - `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;
-  readonly packages: readonly SemanticPackage[];
-  dispose(): void;
-}

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

@@ -1,17 +0,0 @@
-/**
- * Shared types for sample operations across domains.
- *
- * Sample returns 1–5 complete instances as exemplars so agents
- * can learn actual data shapes before writing queries.
- */
-
-/** Raw result from a sample operation — instances plus total count. */
-export interface SampleResult<T> {
-  readonly samples: readonly T[];
-  readonly totalCount: number;
-}
-
-/** Full sample output including agent guidance. */
-export interface SampleOutput<T> extends SampleResult<T> {
-  readonly nextSteps: readonly string[];
-}

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

@@ -1,21 +0,0 @@
-/**
- * Standard cross-reference type.
- *
- * The hand-written standard domain's return types (StandardSummary,
- * StandardDetailed, CodeBlock, …) were deleted with the domain — the
- * `standard` noun is served by the bundled story pack, whose rows and
- * entities are generic string records. Only {@link StandardRef} remains:
- * block lookups still cross-reference standards by name/URI/category.
- */
-
-import type { URI } from "@canonical/ke";
-
-/** Lightweight reference to a standard, used in block cross-references. */
-export interface StandardRef {
-  /** Human-readable standard name. */
-  readonly name: string;
-  /** Full RDF URI of the referenced standard. */
-  readonly uri: URI;
-  /** Category the referenced standard belongs to. */
-  readonly category: string;
-}

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

@@ -1,15 +0,0 @@
-/** Tier hierarchy return types. */
-
-import type { URI } from "@canonical/ke";
-
-/** A single entry in the tier hierarchy (e.g., `global`, `apps`, `apps/lxd`). */
-export interface TierEntry {
-  /** Full RDF URI identifying this tier in the ke store. */
-  readonly uri: URI;
-  /** Slash-separated tier path (e.g., `"apps/lxd"`). */
-  readonly path: string;
-  /** Path of the parent tier, if this is not the root. */
-  readonly parent?: string;
-  /** Nesting depth in the tier hierarchy (0 = root). */
-  readonly depth: number;
-}

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

@@ -1,30 +0,0 @@
-/** Token domain return types. */
-
-import type { URI } from "@canonical/ke";
-
-/** Summary view of a design token. */
-export interface TokenSummary {
-  /** Full RDF URI identifying this token in the ke store. */
-  readonly uri: URI;
-  /** Human-readable token name (e.g., `"color-primary"`). */
-  readonly name: string;
-  /** Token category (e.g., `"color"`, `"spacing"`, `"typography"`). */
-  readonly category: string;
-}
-
-/** Digest view of a token for generic list contracts. */
-export type TokenDigest = TokenSummary;
-
-/** Detailed view of a token, extending the summary with per-theme resolved values. */
-export interface TokenDetailed extends TokenSummary {
-  /** Resolved values keyed by theme (e.g., `{ theme: "dark", value: "#fff" }`). */
-  readonly values: readonly { theme: string; value: string }[];
-}
-
-/** Lightweight reference to a token (name + URI), used in cross-references. */
-export interface TokenRef {
-  /** Human-readable token name. */
-  readonly name: string;
-  /** Full RDF URI of the referenced token. */
-  readonly uri: URI;
-}

package/src/domains/skill/commands/index.ts

@@ -1,4 +0,0 @@
-/** @module Re-exports skill command builders (`list`, `lookup`). */
-
-export { default as listCommand } from "./list.js";
-export { default as lookupCommand } from "./lookup.js";

package/src/domains/skill/commands/list.test.ts

@@ -1,115 +0,0 @@
-import { mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { CommandDefinition } from "@canonical/cli-core";
-import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
-import type { PragmaContext } from "../../shared/context.js";
-import type { SkillListInput } from "../formatters/types.js";
-import buildListCommand from "./list.js";
-
-const TMP_ROOT = join(tmpdir(), `pragma-skill-cmd-${Date.now()}`);
-
-/** One source per skill directory, matching the loader granularity. */
-const TEST_SOURCES = [
-  {
-    dir: join(
-      TMP_ROOT,
-      "node_modules/@canonical/design-system/skills/design-audit",
-    ),
-    packageName: "@canonical/design-system",
-  },
-];
-
-vi.mock("../helpers/resolveSkillSources.js", () => ({
-  default: () => TEST_SOURCES,
-}));
-
-beforeAll(() => {
-  mkdirSync(TMP_ROOT, { recursive: true });
-
-  const dir = TEST_SOURCES.at(0)?.dir ?? "";
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(
-    join(dir, "SKILL.md"),
-    `---
-name: design-audit
-description: Audit a component against DS specs
-metadata:
-  author: canonical
----
-`,
-  );
-});
-
-afterAll(() => {
-  rmSync(TMP_ROOT, { recursive: true, force: true });
-});
-
-function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
-  return {
-    cwd: TMP_ROOT,
-    globalFlags: { llm: false, format: "text" as const, verbose: false },
-    store: {} as PragmaContext["store"],
-    config: { tier: undefined, channel: "normal" },
-    ...overrides,
-  } as PragmaContext;
-}
-
-async function executeOutput(
-  cmd: CommandDefinition,
-  params: Record<string, unknown>,
-  ctx: PragmaContext,
-): Promise<{ value: unknown; text: string }> {
-  const result = await cmd.execute(params, ctx);
-  expect(result.tag).toBe("output");
-  if (result.tag !== "output") throw new Error("Expected output result");
-  const text = result.render.plain(result.value);
-  return { value: result.value, text };
-}
-
-describe("buildListCommand", () => {
-  it("returns output result with skill data", async () => {
-    const ctx = makeCtx();
-    const cmd = buildListCommand(ctx);
-    const { value } = await executeOutput(cmd, {}, ctx);
-    const input = value as SkillListInput;
-    expect(input.skills).toHaveLength(1);
-    expect(input.skills[0].name).toBe("design-audit");
-  });
-
-  it("renders plain text output", async () => {
-    const ctx = makeCtx();
-    const cmd = buildListCommand(ctx);
-    const { text } = await executeOutput(cmd, {}, ctx);
-    expect(text).toContain("design-audit");
-    expect(text).toContain("@canonical/design-system");
-  });
-
-  it("renders LLM markdown", async () => {
-    const ctx = makeCtx({
-      globalFlags: { llm: true, format: "text" as const, verbose: false },
-    });
-    const cmd = buildListCommand(ctx);
-    const { text } = await executeOutput(cmd, {}, ctx);
-    expect(text).toContain("## Skills");
-    expect(text).toContain("**design-audit**");
-  });
-
-  it("renders JSON output", async () => {
-    const ctx = makeCtx({
-      globalFlags: { llm: false, format: "json" as const, verbose: false },
-    });
-    const cmd = buildListCommand(ctx);
-    const { text } = await executeOutput(cmd, {}, ctx);
-    const parsed = JSON.parse(text);
-    expect(Array.isArray(parsed)).toBe(true);
-    expect(parsed[0].name).toBe("design-audit");
-  });
-
-  it("passes detailed flag to formatter input", async () => {
-    const ctx = makeCtx();
-    const cmd = buildListCommand(ctx);
-    const { value } = await executeOutput(cmd, { detailed: true }, ctx);
-    expect((value as SkillListInput).detailed).toBe(true);
-  });
-});

package/src/domains/skill/commands/list.ts

@@ -1,11 +0,0 @@
-import type { CommandDefinition } from "@canonical/cli-core";
-import type { PragmaContext } from "../../shared/context.js";
-import { compileReadCommand } from "../../shared/stories/index.js";
-import { skillListStory } from "../stories.js";
-
-/** Wire the `pragma skill list` CLI command from the skill list story. */
-export default function buildListCommand(
-  ctx: PragmaContext,
-): CommandDefinition {
-  return compileReadCommand(ctx, skillListStory);
-}

package/src/domains/skill/commands/lookup.test.ts

@@ -1,118 +0,0 @@
-import { mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { CommandDefinition } from "@canonical/cli-core";
-import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
-import { PragmaError } from "#error";
-import type { PragmaContext } from "../../shared/context.js";
-import buildLookupCommand from "./lookup.js";
-
-const TMP_ROOT = join(tmpdir(), `pragma-skill-lookup-cmd-${Date.now()}`);
-
-/** One source per skill directory, matching the loader granularity. */
-const TEST_SOURCES = [
-  {
-    dir: join(
-      TMP_ROOT,
-      "node_modules/@canonical/design-system/skills/design-auditor",
-    ),
-    packageName: "@canonical/design-system",
-  },
-];
-
-vi.mock("../helpers/resolveSkillSources.js", () => ({
-  default: () => TEST_SOURCES,
-}));
-
-beforeAll(() => {
-  const dir = TEST_SOURCES.at(0)?.dir ?? "";
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(
-    join(dir, "SKILL.md"),
-    `---
-name: design-auditor
-description: Audit design system coverage
----
-
-# Design Auditor
-`,
-  );
-});
-
-afterAll(() => {
-  rmSync(TMP_ROOT, { recursive: true, force: true });
-});
-
-function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
-  return {
-    cwd: TMP_ROOT,
-    globalFlags: { llm: false, format: "text" as const, verbose: false },
-    store: {} as PragmaContext["store"],
-    config: { tier: undefined, channel: "normal" },
-    ...overrides,
-  } as PragmaContext;
-}
-
-async function executeText(
-  cmd: CommandDefinition,
-  params: Record<string, unknown>,
-  ctx: PragmaContext,
-): Promise<string> {
-  const result = await cmd.execute(params, ctx);
-  expect(result.tag).toBe("output");
-  if (result.tag !== "output") throw new Error("Expected output result");
-  return result.render.plain(result.value);
-}
-
-describe("buildLookupCommand", () => {
-  it("serves the full SKILL.md content", async () => {
-    const ctx = makeCtx();
-    const text = await executeText(
-      buildLookupCommand(ctx),
-      { names: ["design-auditor"] },
-      ctx,
-    );
-    expect(text).toContain("design-auditor");
-    expect(text).toContain("# Design Auditor");
-  });
-
-  it("renders JSON with content under --format json", async () => {
-    const ctx = makeCtx({
-      globalFlags: { llm: false, format: "json", verbose: false },
-    });
-    const text = await executeText(
-      buildLookupCommand(ctx),
-      { names: ["design-auditor"] },
-      ctx,
-    );
-    const data = JSON.parse(text) as { name: string; content: string };
-    expect(data.name).toBe("design-auditor");
-    expect(data.content).toContain("# Design Auditor");
-  });
-
-  it("reports unknown skills in the errors section", async () => {
-    const ctx = makeCtx();
-    const text = await executeText(
-      buildLookupCommand(ctx),
-      { names: ["nope"] },
-      ctx,
-    );
-    expect(text).toContain("Errors:");
-    expect(text).toContain('skill "nope" not found.');
-  });
-
-  it("rejects an empty names list with a recovery hint", async () => {
-    const ctx = makeCtx();
-    const cmd = buildLookupCommand(ctx);
-    await expect(cmd.execute({ names: [] }, ctx)).rejects.toThrow(PragmaError);
-  });
-
-  it("completes skill names from discovery", async () => {
-    const ctx = makeCtx();
-    const cmd = buildLookupCommand(ctx);
-    const names = cmd.parameters.at(0);
-    await expect(names?.complete?.("des", ctx)).resolves.toEqual([
-      "design-auditor",
-    ]);
-  });
-});

package/src/domains/skill/commands/lookup.ts

@@ -1,14 +0,0 @@
-import type { CommandDefinition } from "@canonical/cli-core";
-import type { PragmaContext } from "../../shared/context.js";
-import { compileLookupCommand } from "../../shared/stories/index.js";
-import { skillLookupStory } from "../stories.js";
-
-/**
- * Wire the `pragma skill lookup <name...>` CLI command from the skill
- * lookup story.
- */
-export default function buildLookupCommand(
-  ctx: PragmaContext,
-): CommandDefinition {
-  return compileLookupCommand(ctx, skillLookupStory);
-}

package/src/domains/skill/formatters/index.ts

@@ -1,3 +0,0 @@
-/** @module Formatter sets for skill domain output. */
-export { default as listFormatters } from "./list.js";
-export { default as lookupFormatters } from "./lookup.js";