@canonical/pragma-cli 0.27.1-experimental.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/index.ts

@@ -1,5 +1,6 @@
-/** @module Re-exports standard command builders (`categories`, `get`, `list`). */
+/** @module Re-exports standard command builders (`categories`, `list`, `lookup`, `sample`). */
 
 export { default as categoriesCommand } from "./categories.js";
 export { default as listCommand } from "./list.js";
 export { default as lookupCommand } from "./lookup.js";
+export { default as sampleCommand } from "./sample.js";

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/commands/sample.ts

@@ -0,0 +1,57 @@
+/**
+ * Wires the `pragma standard sample` CLI command.
+ *
+ * Returns 1–5 complete standard instances as exemplars so agents
+ * can learn the data shape before writing queries.
+ */
+
+import {
+  type CommandDefinition,
+  createOutputResult,
+} from "@canonical/cli-core";
+import type { PragmaContext } from "../../shared/context.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import type {
+  SampleOutput,
+  StandardDetailed,
+} from "../../shared/types/index.js";
+import { sampleFormatters } from "../formatters/index.js";
+import { sampleStandards } from "../operations/index.js";
+
+const NEXT_STEPS = [
+  "Use standard_lookup to inspect specific standards by name.",
+  "Use standard_list with --category to filter by category.",
+  "Use standard_categories to see all available categories.",
+];
+
+export default function sampleCommand(ctx: PragmaContext): CommandDefinition {
+  return {
+    path: ["standard", "sample"],
+    description:
+      "Return randomly selected complete standard instances as exemplars for shape discovery",
+    parameters: [
+      {
+        name: "count",
+        type: "string",
+        description: "Number of samples to return (1–5, default 2)",
+        required: false,
+      },
+    ],
+    meta: {
+      examples: ["pragma standard sample", "pragma standard sample --count 3"],
+    },
+    async execute(params) {
+      const count = Number(params.count ?? 2);
+      const result = await sampleStandards(ctx.store, count);
+
+      const output: SampleOutput<StandardDetailed> = {
+        ...result,
+        nextSteps: NEXT_STEPS,
+      };
+
+      return createOutputResult(output, {
+        plain: selectFormatter(ctx, sampleFormatters),
+      });
+    },
+  };
+}

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

@@ -1,4 +1,4 @@
-/** @module Re-exports standard formatters (`categoriesFormatters`, `getFormatters`, `listFormatters`). */
+/** @module Re-exports standard formatters (`categoriesFormatters`, `listFormatters`, `lookupFormatters`, `sampleFormatters`). */
 
 export { default as categoriesFormatters } from "./categories.js";
 export { default as listFormatters } from "./list.js";
@@ -6,4 +6,5 @@ export {
   createInkLookupOptions,
   default as lookupFormatters,
 } from "./lookup.js";
+export { default as sampleFormatters } from "./sample.js";
 export type { StandardListOutput, StandardLookupInput } from "./types.js";

package/src/domains/standard/formatters/sample.ts

@@ -0,0 +1,15 @@
+/**
+ * Sample formatter for the standard domain.
+ *
+ * Delegates to the shared factory, rendering each item via the
+ * existing standard lookup formatter.
+ */
+
+import createSampleFormatters from "../../shared/sampleFormatters.js";
+import type { StandardDetailed } from "../../shared/types/index.js";
+import lookupFormatters from "./lookup.js";
+
+export default createSampleFormatters<StandardDetailed>(
+  "standards",
+  (standard, mode) => lookupFormatters[mode]({ standard, detailed: true }),
+);

package/src/domains/standard/index.ts

@@ -12,10 +12,16 @@ import {
   categoriesCommand,
   listCommand,
   lookupCommand,
+  sampleCommand,
 } from "./commands/index.js";
 
 export function commands(ctx: PragmaContext): CommandDefinition[] {
-  return [listCommand(ctx), lookupCommand(ctx), categoriesCommand(ctx)];
+  return [
+    listCommand(ctx),
+    lookupCommand(ctx),
+    categoriesCommand(ctx),
+    sampleCommand(ctx),
+  ];
 }
 
 export { specs as mcpSpecs } from "./mcp/index.js";
@@ -23,6 +29,7 @@ export {
   listCategories,
   listStandards,
   lookupStandard,
+  sampleStandards,
 } from "./operations/index.js";
 export {
   buildStandardFilters,

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

@@ -1,49 +1,32 @@
 /**
- * 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 } from "../operations/index.js";
-import {
-  resolveStandardList,
-  resolveStandardLookup,
-} from "../orchestration/index.js";
+import { listCategories, sampleStandards } from "../operations/index.js";
+import { standardListStory, standardLookupStory } from "../stories.js";
 
 const specs: readonly ToolSpec[] = [
+  compileReadTool(standardListStory),
+  compileLookupTool(standardLookupStory),
   {
-    name: "standard_list",
-    description:
-      "List code standards. Optionally filter by category or search term. Use digest/detailed for progressive disclosure.",
+    name: "standard_categories",
+    description: "List all code standard categories.",
     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",
@@ -51,59 +34,24 @@ const specs: readonly ToolSpec[] = [
       },
     },
     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,
-      };
+    async execute(rt, { condensed }) {
+      const result = await listCategories(rt.store);
 
       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 condense(standardCatFmt.llm(result));
       }
 
-      return {
-        data: JSON.parse(standardListFmt.json(output)),
-        meta: {
-          count: resolution.items.length,
-          disclosure: resolution.disclosure.level,
-        },
-      };
+      return { data: result, meta: { count: result.length } };
     },
   },
-
   {
-    name: "standard_lookup",
+    name: "standard_sample",
     description:
-      "Get detailed information about one or more code standards including dos and donts with code examples.",
+      "Return 1–5 randomly selected complete code standard instances as exemplars. Use BEFORE writing queries to see actual data shapes, property names, and value formats. Each call returns different instances.",
     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)",
+      count: {
+        type: "string",
+        description: "Number of samples (1–5, default 2)",
         optional: true,
       },
       condensed: {
@@ -113,85 +61,29 @@ const specs: readonly ToolSpec[] = [
       },
     },
     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;
+    async execute(rt, { count, condensed }) {
+      const n = Number(count ?? 2);
+      const result = await sampleStandards(rt.store, n);
+      const nextSteps = [
+        `These are ${result.samples.length} of ${result.totalCount} total standards.`,
+        "Use standard_lookup to inspect specific standards by name.",
+        "Use standard_list with category param to filter by category.",
+      ];
 
       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 condense(standardSampleFmt.llm({ ...result, nextSteps }));
       }
 
-      return { data: result, meta: { count: result.results.length } };
-    },
-  },
-
-  {
-    name: "standard_categories",
-    description: "List all code standard categories.",
-    params: {
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { condensed }) {
-      const result = await listCategories(rt.store);
-
-      if (condensed) {
-        const text = standardCatFmt.llm(result);
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return { data: result, meta: { count: result.length } };
+      return {
+        data: {
+          samples: result.samples,
+          totalCount: result.totalCount,
+          nextSteps,
+        },
+        meta: { count: result.samples.length },
+      };
     },
   },
-];
+] as const;
 
 export default specs;