@canonical/pragma-cli 0.29.0 → 0.30.0

package/src/domains/skill/stories.ts

@@ -0,0 +1,103 @@
+/**
+ * Skill read stories — the single declaration of `skill list` and
+ * `skill lookup` for both surfaces.
+ *
+ * `skill lookup` serves the full SKILL.md content, making skills directly
+ * consumable by agents over MCP (previously only metadata was listed).
+ */
+
+import { PragmaError } from "#error";
+import lookupMany from "../shared/lookupMany.js";
+import {
+  type LookupStory,
+  type ReadStory,
+  requirePragmaContext,
+} from "../shared/stories/index.js";
+import { listFormatters, lookupFormatters } from "./formatters/index.js";
+import type { SkillListInput } from "./formatters/types.js";
+import {
+  discoverSkills,
+  listSkills,
+  lookupSkill,
+  type SkillListResult,
+} from "./operations/index.js";
+import type { SkillDetailed } from "./types.js";
+
+/** The `skill list` / `skill_list` read story. */
+export const skillListStory: ReadStory<SkillListResult, SkillListInput> = {
+  noun: "skill",
+  verb: "list",
+  description: "List available agent skills from design system packages",
+  toolDescription: "List available agent skills from design system packages.",
+  params: [
+    {
+      name: "detailed",
+      type: "boolean",
+      description: "Show full metadata for each skill",
+      default: false,
+      surfaces: "cli",
+    },
+  ],
+  examples: [
+    "pragma skill list",
+    "pragma skill list --detailed",
+    "pragma skill list --llm",
+    "pragma skill list --format json",
+  ],
+  resolve: (rt) => listSkills(rt.cwd),
+  toOutput: ({ skills, sources }, params) => ({
+    skills,
+    sources,
+    detailed: params.detailed === true,
+  }),
+  formatters: listFormatters,
+  toEnvelope: ({ skills, sources }) => ({
+    data: { skills, sources },
+    meta: { count: skills.length },
+  }),
+  emptyError: ({ skills, sources }) => {
+    if (skills.length > 0) return undefined;
+    const allUnavailable = sources.every((source) => !source.available);
+    return PragmaError.emptyResults("skill", {
+      recovery: {
+        message: allUnavailable
+          ? "Install @canonical packages first"
+          : "No SKILL.md files found in source packages",
+      },
+    });
+  },
+};
+
+/** The `skill lookup` / `skill_lookup` read story. */
+export const skillLookupStory: LookupStory<SkillDetailed, SkillDetailed> = {
+  noun: "skill",
+  description: "Show full instructions for a skill by name",
+  toolDescription:
+    "Get full skill instructions (SKILL.md content) for one or more agent skills by name.",
+  namesDescription: "Skill names",
+  namesToolDescription: "Skill names to look up (e.g. ['design-auditor'])",
+  complete: async (partial, cmdCtx) => {
+    const ctx = requirePragmaContext(cmdCtx);
+    const skills = await discoverSkills(ctx.cwd);
+    return skills
+      .map((skill) => skill.name)
+      .filter((name) => name.toLowerCase().startsWith(partial.toLowerCase()));
+  },
+  examples: [
+    "pragma skill lookup design-auditor",
+    "pragma skill lookup design-auditor add-standard",
+    "pragma skill lookup design-auditor --llm",
+  ],
+  resolve: (rt, names) =>
+    lookupMany(names, (query) => lookupSkill(rt.cwd, query)),
+  toFmtInput: (skill) => skill,
+  formatters: lookupFormatters,
+  emptyNamesError: () =>
+    PragmaError.invalidInput("names", "(empty)", {
+      recovery: {
+        message: "List available skills.",
+        cli: "pragma skill list",
+        mcp: { tool: "skill_list" },
+      },
+    }),
+};

package/src/domains/skill/types.ts

@@ -23,3 +23,11 @@ export interface SkillSource {
   readonly packageName: string;
   readonly available: boolean;
 }
+
+/** A discovered skill enriched with its full SKILL.md content and companion files. */
+export interface SkillDetailed extends DiscoveredSkill {
+  /** Full SKILL.md text, frontmatter included. */
+  readonly content: string;
+  /** Companion file names shipped next to SKILL.md (e.g. spec documents). */
+  readonly files: readonly string[];
+}

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

@@ -1,90 +1,11 @@
-/**
- * Wires the `pragma standard list` CLI command.
- *
- * Lists all code standards with optional category and search filters.
- * Supports progressive disclosure via `--digest` (summary + first example)
- * and `--detailed` (full dos/donts) flags.
- */
-
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { createListView } from "#tui";
+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 { StandardListOutput } from "../formatters/types.js";
-import { resolveStandardList } from "../orchestration/index.js";
-import { standardConfig } from "../standardConfig.js";
+import { compileReadCommand } from "../../shared/stories/index.js";
+import { standardListStory } from "../stories.js";
 
+/** Wire the `pragma standard list` CLI command from the standard list story. */
 export default function buildListCommand(
   ctx: PragmaContext,
 ): CommandDefinition {
-  return {
-    path: ["standard", "list"],
-    description: "List all code standards",
-    parameters: [
-      {
-        name: "category",
-        description: "Filter by category",
-        type: "string",
-      },
-      {
-        name: "search",
-        description: "Search in name and description",
-        type: "string",
-      },
-      {
-        name: "digest",
-        description: "Show description and first example for each standard",
-        type: "boolean",
-        default: false,
-      },
-      {
-        name: "detailed",
-        description: "Show full dos/donts for each standard",
-        type: "boolean",
-        default: false,
-      },
-    ],
-    meta: {
-      examples: [
-        "pragma standard list",
-        "pragma standard list --category react",
-        'pragma standard list --search "folder"',
-        "pragma standard list --digest",
-        "pragma standard list --detailed",
-        "pragma standard list --llm",
-      ],
-    },
-    execute: async (
-      params: Record<string, unknown>,
-    ): Promise<CommandResult> => {
-      const contract = await resolveStandardList(ctx, {
-        category: params.category as string | undefined,
-        search: params.search as string | undefined,
-        digest: params.digest === true,
-        detailed: params.detailed === true,
-      });
-
-      const output: StandardListOutput = {
-        items: contract.items,
-        details: contract.details,
-        disclosure: contract.disclosure,
-      };
-
-      return createOutputResult(output, {
-        plain: selectFormatter(ctx, listFormatters),
-        ink: (data) =>
-          createListView({
-            heading: "Standards",
-            domain: "standard",
-            items: data.items,
-            columns: standardConfig.listColumns,
-          }),
-      });
-    },
-  };
+  return compileReadCommand(ctx, standardListStory);
 }

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

@@ -1,99 +1,14 @@
-/**
- * Wires the `pragma standard lookup <name-or-uri...>` CLI command.
- *
- * Retrieves detailed information for a single code standard, including
- * optional dos/donts code blocks when `--detailed` is passed.
- */
-
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { createLookupView } from "#tui";
+import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
-import type { LookupResult } from "../../shared/contracts.js";
-import { renderLookupResults } from "../../shared/formatters.js";
-import {
-  createInkLookupOptions,
-  lookupFormatters,
-} from "../formatters/index.js";
-import type { lookupStandard } from "../operations/index.js";
-import { resolveStandardLookup } from "../orchestration/index.js";
-
-interface StandardLookupOutput {
-  readonly result: LookupResult<Awaited<ReturnType<typeof lookupStandard>>>;
-  readonly detailed: boolean;
-}
+import { compileLookupCommand } from "../../shared/stories/index.js";
+import { standardLookupStory } from "../stories.js";
 
+/**
+ * Wire the `pragma standard lookup <name-or-uri...>` CLI command from the
+ * standard lookup story.
+ */
 export default function buildLookupCommand(
   ctx: PragmaContext,
 ): CommandDefinition {
-  return {
-    path: ["standard", "lookup"],
-    description: "Look up detailed information for a standard by name or IRI",
-    parameters: [
-      {
-        name: "names",
-        description: "Standard names or IRIs",
-        type: "multiselect",
-        positional: true,
-        required: true,
-      },
-      {
-        name: "detailed",
-        description: "Include dos and donts with code blocks",
-        type: "boolean",
-        default: false,
-      },
-    ],
-    meta: {
-      examples: [
-        "pragma standard lookup react/component/folder-structure",
-        "pragma standard lookup react/component/folder-structure react/component/props",
-        "pragma standard lookup react/component/folder-structure --detailed",
-        "pragma standard lookup react/component/folder-structure --llm",
-        "pragma standard lookup cs:react_props",
-      ],
-    },
-    execute: async (
-      params: Record<string, unknown>,
-    ): Promise<CommandResult> => {
-      const names = normalizeNames(params.names, params.name);
-      const detailed = (params.detailed as boolean) ?? false;
-      const contract = await resolveStandardLookup(ctx.store, names);
-
-      return createOutputResult<StandardLookupOutput>(
-        { result: contract.result, detailed },
-        {
-          plain: ({ result, detailed: isDetailed }) =>
-            renderLookupResults({
-              ctx,
-              result,
-              formatters: lookupFormatters,
-              mapResult: (standard) => ({ standard, detailed: isDetailed }),
-            }),
-          ink: ({ result, detailed: isDetailed }) =>
-            createLookupView({
-              results: result.results,
-              errors: result.errors,
-              domain: "standard",
-              options: createInkLookupOptions(isDetailed),
-            }),
-        },
-      );
-    },
-  };
-}
-
-function normalizeNames(names: unknown, legacyName?: unknown): string[] {
-  if (Array.isArray(names)) {
-    return names.filter(
-      (name): name is string => typeof name === "string" && name.length > 0,
-    );
-  }
-  if (typeof legacyName === "string" && legacyName.length > 0) {
-    return [legacyName];
-  }
-  return [];
+  return compileLookupCommand(ctx, standardLookupStory);
 }

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

@@ -1,172 +1,28 @@
 /**
- * MCP tool specs for the standard domain.
+ * MCP tool specs for the standard domain — standard_list, standard_lookup,
+ * standard_categories, standard_sample.
  *
- * Declarative definitions — no MCP imports. The adapter layer
- * converts these into registered MCP tools via `registerFromSpec()`.
+ * The list and lookup tools are compiled from the standard read stories in
+ * `../stories.ts`; categories and sample are spec'd by hand. The adapter
+ * layer converts these into registered MCP tools via `registerFromSpec()`.
  */
 
+import {
+  compileLookupTool,
+  compileReadTool,
+  condense,
+} from "../../shared/stories/index.js";
 import type { ToolSpec } from "../../shared/ToolSpec.js";
 import {
-  type StandardListOutput,
   categoriesFormatters as standardCatFmt,
-  listFormatters as standardListFmt,
-  lookupFormatters as standardLookupFmt,
   sampleFormatters as standardSampleFmt,
 } from "../formatters/index.js";
 import { listCategories, sampleStandards } from "../operations/index.js";
-import {
-  resolveStandardList,
-  resolveStandardLookup,
-} from "../orchestration/index.js";
+import { standardListStory, standardLookupStory } from "../stories.js";
 
 const specs: readonly ToolSpec[] = [
-  {
-    name: "standard_list",
-    description:
-      "List code standards. Optionally filter by category or search term. Use digest/detailed for progressive disclosure.",
-    params: {
-      category: {
-        type: "string",
-        description: "Filter by category name",
-        optional: true,
-      },
-      search: {
-        type: "string",
-        description: "Search in name and description",
-        optional: true,
-      },
-      digest: {
-        type: "boolean",
-        description: "Show description and first example for each standard",
-        optional: true,
-      },
-      detailed: {
-        type: "boolean",
-        description: "Show full dos/donts for each standard",
-        optional: true,
-      },
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { category, search, digest, detailed, condensed }) {
-      const resolution = await resolveStandardList(rt, {
-        category: category as string | undefined,
-        search: search as string | undefined,
-        digest: digest === true,
-        detailed: detailed === true,
-      });
-      const output: StandardListOutput = {
-        items: resolution.items,
-        details: resolution.details,
-        disclosure: resolution.disclosure,
-      };
-
-      if (condensed) {
-        const text = standardListFmt.llm(output);
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      if (resolution.disclosure.level === "summary") {
-        return {
-          data: resolution.items,
-          meta: { count: resolution.items.length },
-        };
-      }
-
-      return {
-        data: JSON.parse(standardListFmt.json(output)),
-        meta: {
-          count: resolution.items.length,
-          disclosure: resolution.disclosure.level,
-        },
-      };
-    },
-  },
-
-  {
-    name: "standard_lookup",
-    description:
-      "Get detailed information about one or more code standards including dos and donts with code examples.",
-    params: {
-      names: {
-        type: "string[]",
-        description: "Standard names or IRIs to look up",
-        optional: false,
-      },
-      detailed: {
-        type: "boolean",
-        description:
-          "Return full details with dos/donts (default: true for MCP)",
-        optional: true,
-      },
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { names, detailed, condensed }) {
-      const showDetailed = (detailed as boolean | undefined) ?? true;
-      const contract = await resolveStandardLookup(rt.store, names as string[]);
-      const result = contract.result;
-
-      if (condensed) {
-        const textParts = result.results.map((standard) =>
-          standardLookupFmt.llm({
-            standard,
-            detailed: showDetailed,
-          }),
-        );
-
-        if (result.errors.length > 0) {
-          textParts.push(
-            [
-              "### Errors",
-              ...result.errors.map(
-                (error) => `- ${error.query}: ${error.message}`,
-              ),
-            ].join("\n"),
-          );
-        }
-
-        const text = textParts.join("\n\n");
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      if (!showDetailed) {
-        return {
-          data: {
-            results: result.results.map(
-              ({ uri, name, category, description }) => ({
-                uri,
-                name,
-                category,
-                description,
-              }),
-            ),
-            errors: result.errors,
-          },
-          meta: { count: result.results.length },
-        };
-      }
-
-      return { data: result, meta: { count: result.results.length } };
-    },
-  },
-
+  compileReadTool(standardListStory),
+  compileLookupTool(standardLookupStory),
   {
     name: "standard_categories",
     description: "List all code standard categories.",
@@ -182,18 +38,12 @@ const specs: readonly ToolSpec[] = [
       const result = await listCategories(rt.store);
 
       if (condensed) {
-        const text = standardCatFmt.llm(result);
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
+        return condense(standardCatFmt.llm(result));
       }
 
       return { data: result, meta: { count: result.length } };
     },
   },
-
   {
     name: "standard_sample",
     description:
@@ -221,12 +71,7 @@ const specs: readonly ToolSpec[] = [
       ];
 
       if (condensed) {
-        const text = standardSampleFmt.llm({ ...result, nextSteps });
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
+        return condense(standardSampleFmt.llm({ ...result, nextSteps }));
       }
 
       return {
@@ -239,6 +84,6 @@ const specs: readonly ToolSpec[] = [
       };
     },
   },
-];
+] as const;
 
 export default specs;

package/src/domains/standard/orchestration/resolveStandardLookup.ts

@@ -18,11 +18,12 @@ export default async function resolveStandardLookup(
   const lookupResult: LookupResult<StandardDetailed> =
     names.length > 0
       ? await lookupMany(names, (query) => lookupStandard(store, query))
-      : { results: [], errors: [] };
+      : { results: [], errors: [], meta: { internalErrorCount: 0 } };
 
   const result: LookupResult<StandardDetailed> = {
     results: lookupResult.results,
     errors: [...lookupResult.errors, ...globErrors],
+    meta: lookupResult.meta ?? { internalErrorCount: 0 },
   };
 
   return {

package/src/domains/standard/stories.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { standardListStory, standardLookupStory } from "./stories.js";
+
+describe("standardListStory", () => {
+  it("renders the ink list view", () => {
+    const view = standardListStory.renderInk?.({
+      items: [],
+      details: undefined,
+      disclosure: { level: "summary" },
+    });
+    expect(typeof view).toBe("string");
+    expect(view).toContain("Standards");
+  });
+});
+
+describe("standardLookupStory", () => {
+  it("renders the ink lookup view", () => {
+    const view = standardLookupStory.renderInk?.(
+      { results: [], errors: [] },
+      { surface: "cli", detailed: false, params: {} },
+    );
+    expect(typeof view).toBe("string");
+  });
+});