@canonical/pragma-cli 0.29.0 → 0.31.0

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

@@ -2,49 +2,144 @@
 
 /** Summary of a loaded ontology namespace from `ontology list`. */
 export interface OntologySummary {
-  /** Short prefix alias (e.g., `"ds"`, `"cs"`). */
+  /** 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 properties (object + datatype) defined in this namespace. */
-  readonly propertyCount: 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 class in an ontology's class hierarchy. */
+/**
+ * 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 {
-  /** Full URI of the class. */
-  readonly uri: string;
-  /** Human-readable label (rdfs:label). */
+  /** Compact IRI of the class. */
+  readonly iri: string;
+  /** Human-readable label (rdfs:label, falling back to the local name). */
   readonly label: string;
-  /** URI of the direct superclass, if declared. */
-  readonly superclass?: 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[];
 }
 
-/** A property in an ontology namespace. */
-export interface OntologyProperty {
-  /** Full URI of the property. */
-  readonly uri: string;
-  /** Human-readable label (rdfs:label). */
+/** 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;
-  /** URI of the domain class this property applies to, if declared. */
-  readonly domain?: string;
-  /** URI of the range class or datatype, if declared. */
-  readonly range?: string;
-  /** Whether this is an object property (links classes) or datatype property (links to literals). */
-  readonly type: "object" | "datatype";
+  /**
+   * SPARQL using compact IRIs — runnable as-is via `pragma graph query`,
+   * which resolves the store's prefix map.
+   */
+  readonly sparql: string;
 }
 
-/** Detailed view of a single ontology namespace from `ontology show`. */
+/** 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;
-  /** All classes defined in this namespace. */
+  /** 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[];
-  /** All properties defined in this namespace. */
-  readonly properties: readonly OntologyProperty[];
+  /** 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/standard.ts

@@ -1,58 +1,15 @@
-/** Standard domain return types. */
+/**
+ * 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";
 
-/** Summary view of a design-system standard (guideline or rule). */
-export interface StandardSummary {
-  /** Full RDF URI identifying this standard in the ke store. */
-  readonly uri: URI;
-  /** Human-readable name of the standard. */
-  readonly name: string;
-  /** Category grouping (e.g., `"accessibility"`, `"layout"`). */
-  readonly category: string;
-  /** Brief prose description of what the standard prescribes. */
-  readonly description: string;
-  /** URI of the parent standard this one extends, if any. */
-  readonly extends?: string;
-}
-
-/** Digest view of a standard for generic list contracts. */
-export type StandardDigest = StandardSummary;
-
-/** Fenced code block used in standard do/don't examples. */
-export interface CodeBlock {
-  /** Programming language identifier for syntax highlighting. */
-  readonly language: string;
-  /** Source code content of the example. */
-  readonly code: string;
-  /** Optional explanatory caption displayed alongside the code. */
-  readonly caption?: string;
-}
-
-/** Detailed view of a standard, extending the summary with code examples. */
-export interface StandardDetailed extends StandardSummary {
-  /** Positive examples demonstrating correct usage. */
-  readonly dos: readonly CodeBlock[];
-  /** Negative examples demonstrating incorrect usage. */
-  readonly donts: readonly CodeBlock[];
-}
-
-/** Summary of a standards category with its member count. */
-export interface CategorySummary {
-  /** Category name (e.g., `"accessibility"`, `"layout"`). */
-  readonly name: string;
-  /** Number of standards belonging to this category. */
-  readonly standardCount: number;
-}
-
-/** Optional filters for narrowing the standards list. */
-export interface StandardListFilters {
-  /** Restrict results to a single category name. */
-  readonly category?: string;
-  /** Free-text search term matched against standard names and descriptions. */
-  readonly search?: string;
-}
-
 /** Lightweight reference to a standard, used in block cross-references. */
 export interface StandardRef {
   /** Human-readable standard name. */

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

@@ -1,2 +1,4 @@
-/** @module Skill command definitions for `pragma skill`. */
+/** @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

@@ -9,9 +9,13 @@ 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"),
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/design-system/skills/design-audit",
+    ),
     packageName: "@canonical/design-system",
   },
 ];
@@ -23,7 +27,7 @@ vi.mock("../helpers/resolveSkillSources.js", () => ({
 beforeAll(() => {
   mkdirSync(TMP_ROOT, { recursive: true });
 
-  const dir = join(TEST_SOURCES[0].dir, "design-audit");
+  const dir = TEST_SOURCES.at(0)?.dir ?? "";
   mkdirSync(dir, { recursive: true });
   writeFileSync(
     join(dir, "SKILL.md"),

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

@@ -1,69 +1,11 @@
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { PragmaError } from "#error";
+import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import { listFormatters } from "../formatters/index.js";
-import type { SkillListInput } from "../formatters/types.js";
-import { listSkills } from "../operations/index.js";
+import { compileReadCommand } from "../../shared/stories/index.js";
+import { skillListStory } from "../stories.js";
 
-/**
- * Build the `pragma skill list` command definition.
- *
- * Discovers skills from installed packages and formats the result.
- * Throws when no skills are found, with a recovery hint.
- *
- * @param ctx - Pragma context providing cwd and formatter selection.
- * @returns The command definition for `pragma skill list`.
- * @note Impure
- */
+/** Wire the `pragma skill list` CLI command from the skill list story. */
 export default function buildListCommand(
   ctx: PragmaContext,
 ): CommandDefinition {
-  return {
-    path: ["skill", "list"],
-    description: "List available agent skills from design system packages",
-    parameters: [
-      {
-        name: "detailed",
-        description: "Show full metadata for each skill",
-        type: "boolean",
-        default: false,
-      },
-    ],
-    meta: {
-      examples: [
-        "pragma skill list",
-        "pragma skill list --detailed",
-        "pragma skill list --llm",
-        "pragma skill list --format json",
-      ],
-    },
-    execute: async (
-      params: Record<string, unknown>,
-    ): Promise<CommandResult> => {
-      const detailed = params.detailed === true;
-      const { skills, sources } = await listSkills(ctx.cwd);
-
-      if (skills.length === 0) {
-        const allUnavailable = sources.every((s) => !s.available);
-        throw PragmaError.emptyResults("skill", {
-          recovery: {
-            message: allUnavailable
-              ? "Install @canonical packages first"
-              : "No SKILL.md files found in source packages",
-          },
-        });
-      }
-
-      const input: SkillListInput = { skills, sources, detailed };
-
-      return createOutputResult(input, {
-        plain: selectFormatter(ctx, listFormatters),
-      });
-    },
-  };
+  return compileReadCommand(ctx, skillListStory);
 }

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

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

@@ -0,0 +1,14 @@
+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,2 +1,3 @@
 /** @module Formatter sets for skill domain output. */
 export { default as listFormatters } from "./list.js";
+export { default as lookupFormatters } from "./lookup.js";

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

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import type { SkillDetailed } from "../types.js";
+import formatters from "./lookup.js";
+
+const skill: SkillDetailed = {
+  name: "design-auditor",
+  description: "Audit design system coverage",
+  sourcePath: "/pkgs/design-system/skills/design-auditor",
+  sourcePackage: "@canonical/design-system",
+  folderName: "design-auditor",
+  frontmatter: {
+    name: "design-auditor",
+    description: "Audit design system coverage",
+  },
+  content: "---\nname: design-auditor\n---\n\n# Design Auditor\n",
+  files: ["AUDIT_SPEC.md"],
+};
+
+describe("skill lookup formatters", () => {
+  it("plain renders a header and the full content", () => {
+    const text = formatters.plain(skill);
+    expect(text).toContain("design-auditor");
+    expect(text).toContain("@canonical/design-system");
+    expect(text).toContain("Companion files: AUDIT_SPEC.md");
+    expect(text).toContain("# Design Auditor");
+  });
+
+  it("llm renders a markdown header above the content", () => {
+    const text = formatters.llm(skill);
+    expect(text).toContain("## Skill: design-auditor");
+    expect(text).toContain("**Companion files:** AUDIT_SPEC.md");
+    expect(text).toContain("# Design Auditor");
+  });
+
+  it("llm omits the companion files line when there are none", () => {
+    const text = formatters.llm({ ...skill, files: [] });
+    expect(text).not.toContain("Companion files");
+  });
+
+  it("json serializes the skill with content and files", () => {
+    const data = JSON.parse(formatters.json(skill)) as Record<string, unknown>;
+    expect(data.name).toBe("design-auditor");
+    expect(data.files).toEqual(["AUDIT_SPEC.md"]);
+    expect(data.content).toContain("# Design Auditor");
+  });
+});

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

@@ -0,0 +1,57 @@
+import chalk from "chalk";
+import type { Formatters } from "../../shared/formatters.js";
+import type { SkillDetailed } from "../types.js";
+
+/**
+ * Formatters for `pragma skill lookup` output.
+ *
+ * - **plain** renders a chalk-styled header (name, source, files) above
+ *   the full SKILL.md content.
+ * - **llm** renders a markdown header above the content — the skill body
+ *   is already markdown, so it is served verbatim.
+ * - **json** serializes the skill with its content and companion files.
+ */
+const formatters: Formatters<SkillDetailed> = {
+  plain(skill) {
+    const lines: string[] = [
+      chalk.bold(skill.name),
+      chalk.dim(skill.description),
+      chalk.dim(`Source: ${skill.sourcePackage} (${skill.sourcePath})`),
+    ];
+    if (skill.files.length > 0) {
+      lines.push(chalk.dim(`Companion files: ${skill.files.join(", ")}`));
+    }
+    lines.push("", skill.content);
+    return lines.join("\n");
+  },
+
+  llm(skill) {
+    const lines: string[] = [
+      `## Skill: ${skill.name}`,
+      "",
+      `**Source:** ${skill.sourcePackage} (${skill.folderName})`,
+    ];
+    if (skill.files.length > 0) {
+      lines.push(`**Companion files:** ${skill.files.join(", ")}`);
+    }
+    lines.push("", skill.content);
+    return lines.join("\n");
+  },
+
+  json(skill) {
+    return JSON.stringify(
+      {
+        name: skill.name,
+        description: skill.description,
+        source: skill.sourcePackage,
+        path: skill.sourcePath,
+        files: skill.files,
+        content: skill.content,
+      },
+      null,
+      2,
+    );
+  },
+};
+
+export default formatters;

package/src/domains/skill/helpers/resolveSkillSources.ts

@@ -5,7 +5,6 @@ import {
 } from "../../shared/loaders/index.js";
 import { DEFAULT_PACKAGES } from "../../shared/packages.js";
 import type { SemanticPackage } from "../../shared/semanticPackage.js";
-import { resolveSemanticPackages } from "../../shared/semanticPackage.js";
 
 /** A resolved skill source directory from an installed package. */
 export interface SkillSource {

package/src/domains/skill/index.ts

@@ -2,7 +2,7 @@
 
 import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../shared/context.js";
-import { listCommand } from "./commands/index.js";
+import { listCommand, lookupCommand } from "./commands/index.js";
 
 /**
  * Return all skill command definitions.
@@ -11,9 +11,13 @@ import { listCommand } from "./commands/index.js";
  * @returns An array of CommandDefinitions for the skill subcommands.
  */
 export function commands(ctx: PragmaContext): CommandDefinition[] {
-  return [listCommand(ctx)];
+  return [listCommand(ctx), lookupCommand(ctx)];
 }
 
 export { specs as mcpSpecs } from "./mcp/index.js";
 export type { SkillListResult } from "./operations/index.js";
-export { discoverSkills, listSkills } from "./operations/index.js";
+export {
+  discoverSkills,
+  listSkills,
+  lookupSkill,
+} from "./operations/index.js";

package/src/domains/skill/mcp/specs.ts

@@ -1,38 +1,19 @@
 /**
- * MCP tool specs for the skill domain.
+ * MCP tool specs for the skill domain — skill_list and skill_lookup,
+ * compiled from the skill read stories in `../stories.ts`. skill_lookup
+ * serves full SKILL.md content so agents can load skills over MCP.
  */
 
+import {
+  compileLookupTool,
+  compileReadTool,
+} from "../../shared/stories/index.js";
 import type { ToolSpec } from "../../shared/ToolSpec.js";
-import { listFormatters as skillListFmt } from "../formatters/index.js";
-import { listSkills } from "../operations/index.js";
+import { skillListStory, skillLookupStory } from "../stories.js";
 
 const specs: readonly ToolSpec[] = [
-  {
-    name: "skill_list",
-    description: "List available agent skills from design system packages.",
-    params: {
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { condensed }) {
-      const { skills, sources } = await listSkills(rt.cwd);
-
-      if (condensed) {
-        const text = skillListFmt.llm({ skills, sources, detailed: false });
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return { data: { skills, sources }, meta: { count: skills.length } };
-    },
-  },
+  compileReadTool(skillListStory),
+  compileLookupTool(skillLookupStory),
 ];
 
 export default specs;