@canonical/pragma-cli 0.30.0 → 0.32.0

package/src/domains/shared/semanticPackage.ts

@@ -1,112 +0,0 @@
-/**
- * Semantic package contracts and resolution orchestrator.
- *
- * A semantic package is a resolved graph dependency containing TTL
- * definitions, instance data, and skills. Three loaders produce the
- * same `SemanticPackage` shape — local (file/npm), git cache, and
- * bundled (compiled binary). The orchestrator tries each loader in
- * precedence order: local > git > bundled.
- */
-
-import type { PackageRef } from "../refs/operations/parseRef.js";
-
-// ---------------------------------------------------------------------------
-// Contracts
-// ---------------------------------------------------------------------------
-
-/** A single TTL file's content with provenance annotation. */
-export interface GraphContent {
-  /** Original file path or virtual identifier (for provenance/debugging). */
-  readonly path: string;
-  /** TTL content string. */
-  readonly content: string;
-  /** RDF serialization format. */
-  readonly format: "turtle";
-}
-
-/** A discovered story-pack JSON file with its content. */
-export interface StoryFileEntry {
-  /**
-   * Original file path, or a virtual identifier for embedded sources
-   * (e.g. `(bundled)/…`) — for provenance/debugging, not guaranteed to
-   * exist on disk.
-   */
-  readonly path: string;
-  /** The file's parsed JSON — validated by the story-pack compiler. */
-  readonly definition: unknown;
-}
-
-export interface SkillEntry {
-  /** Absolute path to the skill directory (must exist on disk for symlinking). */
-  readonly dir: string;
-  /** Skill folder name (e.g. "anatomy-author"). */
-  readonly folderName: string;
-}
-
-/** A resolved graph package. All loaders produce this uniform shape. */
-export interface SemanticPackage {
-  /** npm package name (e.g. "@canonical/design-system"). */
-  readonly name: string;
-  /** Version string from package.json. */
-  readonly version: string;
-  /** How this package was resolved. */
-  readonly source: "local" | "git" | "bundled";
-  /** TTL graph content to load into the ke store. */
-  readonly graphs: GraphContent[];
-  /** Skills available in this package. */
-  readonly skills: SkillEntry[];
-  /**
-   * Raw story-pack files shipped by this package (`stories/*.json`).
-   * Parsed JSON, validated at compile time so one bad file cannot break boot.
-   */
-  readonly stories: StoryFileEntry[];
-}
-
-/**
- * Resolves a package reference to a SemanticPackage.
- * Returns `undefined` if this loader cannot resolve the given ref.
- * May be async (e.g. BundledLoader reads blob content asynchronously).
- */
-export interface PackageLoader {
-  /** Loader identity for diagnostics. */
-  readonly name: "local" | "git" | "bundled";
-  /** Attempt to resolve a package reference. */
-  resolve(
-    ref: PackageRef,
-  ): SemanticPackage | undefined | Promise<SemanticPackage | undefined>;
-}
-
-// ---------------------------------------------------------------------------
-// Orchestrator
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve package references to semantic packages using a loader chain.
- *
- * Tries each loader in array order for each ref. The first loader that
- * returns a result wins — subsequent loaders are skipped for that ref.
- * Refs that no loader can resolve are silently dropped.
- *
- * @param refs - Parsed package references from config merge.
- * @param loaders - Loaders in precedence order (local > git > bundled).
- * @returns Array of resolved semantic packages.
- */
-export async function resolveSemanticPackages(
-  refs: ReadonlyArray<PackageRef>,
-  loaders: ReadonlyArray<PackageLoader>,
-): Promise<SemanticPackage[]> {
-  const packages: SemanticPackage[] = [];
-
-  for (const ref of refs) {
-    let resolved: SemanticPackage | undefined;
-    for (const loader of loaders) {
-      resolved = await loader.resolve(ref);
-      if (resolved) break;
-    }
-    if (resolved) {
-      packages.push(resolved);
-    }
-  }
-
-  return packages;
-}

package/src/domains/shared/stories/compileLookupCommand.test.ts

@@ -1,145 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { PragmaError } from "#error";
-import type { PragmaContext } from "../context.js";
-import type { LookupResult } from "../contracts.js";
-import compileLookupCommand from "./compileLookupCommand.js";
-import type { LookupStory } from "./types.js";
-
-interface FakeEntity {
-  readonly name: string;
-  readonly detail: string;
-}
-
-function makeStory(
-  overrides: Partial<LookupStory<FakeEntity, string>> = {},
-): LookupStory<FakeEntity, string> {
-  return {
-    noun: "thing",
-    description: "Look up things",
-    toolDescription: "Look up things over MCP.",
-    namesDescription: "Thing names",
-    detailedParam: { description: "Show details" },
-    examples: ["pragma thing lookup a"],
-    resolve: async (_rt, names) => {
-      const results = names
-        .filter((name) => name !== "missing")
-        .map((name) => ({ name, detail: `detail-${name}` }));
-      const errors: LookupResult<FakeEntity>["errors"] = names
-        .filter((name) => name === "missing")
-        .map((name) => ({
-          query: name,
-          code: "ENTITY_NOT_FOUND",
-          message: `thing "${name}" not found.`,
-        }));
-      return { results, errors };
-    },
-    toFmtInput: (entity, view) =>
-      view.detailed ? `${entity.name}:${entity.detail}` : entity.name,
-    formatters: {
-      plain: (text) => `plain:${text}`,
-      llm: (text) => `llm:${text}`,
-      json: (text) => JSON.stringify(text),
-    },
-    ...overrides,
-  };
-}
-
-function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
-  return {
-    cwd: "/tmp",
-    globalFlags: { llm: false, format: "text" as const, verbose: false },
-    ...overrides,
-  } as PragmaContext;
-}
-
-async function executeText(
-  story: LookupStory<FakeEntity, string>,
-  params: Record<string, unknown>,
-  ctx: PragmaContext,
-): Promise<string> {
-  const cmd = compileLookupCommand(ctx, story);
-  const result = await cmd.execute(params, ctx);
-  if (result.tag !== "output") throw new Error("expected output result");
-  return result.render.plain(result.value);
-}
-
-describe("compileLookupCommand", () => {
-  it("projects names, detailed, and extra parameters", () => {
-    const story = makeStory({
-      params: [
-        { name: "extra", type: "boolean", description: "extra flag" },
-        { name: "mcpOnly", type: "boolean", description: "x", surfaces: "mcp" },
-      ],
-      parameterGroups: { Extras: ["extra"] },
-    });
-    const cmd = compileLookupCommand(makeCtx(), story);
-    expect(cmd.path).toEqual(["thing", "lookup"]);
-    expect(cmd.parameters.map((p) => p.name)).toEqual([
-      "names",
-      "detailed",
-      "extra",
-    ]);
-    const names = cmd.parameters.at(0);
-    expect(names?.type).toBe("multiselect");
-    expect(names?.positional).toBe(true);
-    expect(names?.required).toBe(true);
-    expect(cmd.parameterGroups).toEqual({ Extras: ["extra"] });
-  });
-
-  it("omits the detailed parameter when the story has none", () => {
-    const cmd = compileLookupCommand(
-      makeCtx(),
-      makeStory({ detailedParam: undefined }),
-    );
-    expect(cmd.parameters.map((p) => p.name)).toEqual(["names"]);
-  });
-
-  it("renders each result and appends an errors section", async () => {
-    const text = await executeText(
-      makeStory(),
-      { names: ["a", "missing"] },
-      makeCtx(),
-    );
-    expect(text).toContain("plain:a");
-    expect(text).toContain("Errors:");
-    expect(text).toContain('thing "missing" not found.');
-  });
-
-  it("is summary by default and detailed with the flag", async () => {
-    const summary = await executeText(makeStory(), { names: ["a"] }, makeCtx());
-    expect(summary).toBe("plain:a");
-
-    const detailed = await executeText(
-      makeStory(),
-      { names: ["a"], detailed: true },
-      makeCtx(),
-    );
-    expect(detailed).toBe("plain:a:detail-a");
-  });
-
-  it("accepts the legacy single name parameter", async () => {
-    const text = await executeText(makeStory(), { name: "a" }, makeCtx());
-    expect(text).toBe("plain:a");
-  });
-
-  it("throws the story's empty-names error when no names are given", async () => {
-    const story = makeStory({
-      emptyNamesError: () => PragmaError.invalidInput("names", "(empty)"),
-    });
-    const cmd = compileLookupCommand(makeCtx(), story);
-    await expect(cmd.execute({ names: [] }, makeCtx())).rejects.toThrow(
-      PragmaError,
-    );
-  });
-
-  it("exposes an ink renderer only when the story defines one", async () => {
-    const story = makeStory({
-      renderInk: (result, view) =>
-        `ink:${result.results.length}:${view.detailed}`,
-    });
-    const cmd = compileLookupCommand(makeCtx(), story);
-    const result = await cmd.execute({ names: ["a"] }, makeCtx());
-    if (result.tag !== "output") throw new Error("expected output result");
-    expect(result.render.ink?.(result.value)).toBe("ink:1:false");
-  });
-});

package/src/domains/shared/stories/compileLookupCommand.ts

@@ -1,100 +0,0 @@
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-  type ParameterDefinition,
-} from "@canonical/cli-core";
-import type { PragmaContext } from "../context.js";
-import type { LookupResult } from "../contracts.js";
-import { renderLookupResults } from "../formatters.js";
-import normalizeNames from "./normalizeNames.js";
-import projectCliParameters from "./projectCliParameters.js";
-import resolveLookupDetailed from "./resolveLookupDetailed.js";
-import type { LookupStory, LookupStoryView } from "./types.js";
-
-/**
- * Compile a lookup story into its CLI `CommandDefinition` projection.
- *
- * Owns the shared execute skeleton: normalize the positional `names`,
- * reject empty input when the story defines an error, resolve the batch,
- * then render each result through the story's formatters with the shared
- * multi-result renderer (which appends the "Errors:" section).
- */
-export default function compileLookupCommand<TDetailed, TFmtInput>(
-  ctx: PragmaContext,
-  story: LookupStory<TDetailed, TFmtInput>,
-): CommandDefinition {
-  interface LookupOutput {
-    readonly result: LookupResult<TDetailed>;
-    readonly view: LookupStoryView;
-  }
-
-  return {
-    path: [story.noun, "lookup"],
-    description: story.description,
-    parameters: buildParameters(story),
-    ...(story.parameterGroups && { parameterGroups: story.parameterGroups }),
-    meta: {
-      examples: story.examples,
-    },
-    execute: async (
-      params: Record<string, unknown>,
-    ): Promise<CommandResult> => {
-      const names = normalizeNames(params.names, params.name);
-      if (names.length === 0 && story.emptyNamesError) {
-        throw story.emptyNamesError();
-      }
-
-      const view: LookupStoryView = {
-        surface: "cli",
-        detailed: resolveLookupDetailed(story, "cli", params),
-        params,
-      };
-      const result = await story.resolve(ctx, names, params);
-      const renderInk = story.renderInk;
-
-      return createOutputResult<LookupOutput>(
-        { result, view },
-        {
-          plain: (output) =>
-            renderLookupResults({
-              ctx,
-              result: output.result,
-              formatters: story.formatters,
-              mapResult: (entity) => story.toFmtInput(entity, output.view),
-            }),
-          ...(renderInk && {
-            ink: (output: LookupOutput) =>
-              renderInk(output.result, output.view),
-          }),
-        },
-      );
-    },
-  };
-}
-
-function buildParameters<TDetailed, TFmtInput>(
-  story: LookupStory<TDetailed, TFmtInput>,
-): ParameterDefinition[] {
-  const names: ParameterDefinition = {
-    name: "names",
-    description: story.namesDescription,
-    type: "multiselect",
-    positional: true,
-    required: true,
-    ...(story.complete && { complete: story.complete }),
-  };
-
-  const detailed: ParameterDefinition[] = story.detailedParam
-    ? [
-        {
-          name: "detailed",
-          description: story.detailedParam.description,
-          type: "boolean",
-          default: false,
-        },
-      ]
-    : [];
-
-  return [names, ...detailed, ...projectCliParameters(story.params ?? [])];
-}

package/src/domains/shared/stories/compileLookupTool.test.ts

@@ -1,105 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { LookupResult } from "../contracts.js";
-import type { PragmaRuntime } from "../types/index.js";
-import compileLookupTool from "./compileLookupTool.js";
-import type { LookupStory } from "./types.js";
-
-interface FakeEntity {
-  readonly name: string;
-  readonly detail: string;
-}
-
-function makeStory(
-  overrides: Partial<LookupStory<FakeEntity, string>> = {},
-): LookupStory<FakeEntity, string> {
-  return {
-    noun: "thing",
-    description: "Look up things",
-    toolDescription: "Look up things over MCP.",
-    namesDescription: "Thing names",
-    namesToolDescription: "Thing names to look up",
-    detailedParam: { description: "Show details" },
-    examples: [],
-    resolve: async (_rt, names) => {
-      const results = names
-        .filter((name) => name !== "missing")
-        .map((name) => ({ name, detail: `detail-${name}` }));
-      const errors: LookupResult<FakeEntity>["errors"] = names
-        .filter((name) => name === "missing")
-        .map((name) => ({
-          query: name,
-          code: "ENTITY_NOT_FOUND",
-          message: `thing "${name}" not found.`,
-        }));
-      return { results, errors, meta: { internalErrorCount: 0 } };
-    },
-    toFmtInput: (entity, view) =>
-      view.detailed ? `${entity.name}:${entity.detail}` : entity.name,
-    formatters: {
-      plain: (text) => `plain:${text}`,
-      llm: (text) => `llm:${text}`,
-      json: (text) => JSON.stringify(text),
-    },
-    project: (entity) => ({ name: entity.name }),
-    ...overrides,
-  };
-}
-
-const rt = {} as PragmaRuntime;
-
-describe("compileLookupTool", () => {
-  it("derives the tool name and params", () => {
-    const tool = compileLookupTool(makeStory());
-    expect(tool.name).toBe("thing_lookup");
-    expect(tool.readOnly).toBe(true);
-    expect(Object.keys(tool.params ?? {})).toEqual([
-      "names",
-      "detailed",
-      "condensed",
-    ]);
-    expect(tool.params?.names).toEqual({
-      type: "string[]",
-      description: "Thing names to look up",
-      optional: false,
-    });
-  });
-
-  it("returns full results by default (MCP detailed defaults to true)", async () => {
-    const tool = compileLookupTool(makeStory());
-    const result = await tool.execute(rt, { names: ["a"] });
-    expect(result).toEqual({
-      data: {
-        results: [{ name: "a", detail: "detail-a" }],
-        errors: [],
-      },
-      meta: { count: 1 },
-    });
-  });
-
-  it("applies the summary projection when detailed is false", async () => {
-    const tool = compileLookupTool(makeStory());
-    const result = await tool.execute(rt, {
-      names: ["a", "b"],
-      detailed: false,
-    });
-    expect(result).toEqual({
-      data: {
-        results: [{ name: "a" }, { name: "b" }],
-        errors: [],
-      },
-      meta: { count: 2 },
-    });
-  });
-
-  it("renders condensed output per entity and appends an errors section", async () => {
-    const tool = compileLookupTool(makeStory());
-    const result = await tool.execute(rt, {
-      names: ["a", "missing"],
-      condensed: true,
-    });
-    if (!("condensed" in result)) throw new Error("expected condensed result");
-    expect(result.text).toContain("llm:a:detail-a");
-    expect(result.text).toContain("### Errors");
-    expect(result.text).toContain('- missing: thing "missing" not found.');
-  });
-});

package/src/domains/shared/stories/compileLookupTool.ts

@@ -1,96 +0,0 @@
-import { lookupToolMeta } from "../lookupMany.js";
-import type { ToolParamDef, ToolSpec } from "../ToolSpec.js";
-import condense from "./condense.js";
-import projectToolParams from "./projectToolParams.js";
-import resolveLookupDetailed from "./resolveLookupDetailed.js";
-import type { LookupStory, LookupStoryView } from "./types.js";
-
-/**
- * Compile a lookup story into its MCP `ToolSpec` projection.
- *
- * The tool is named `<noun>_lookup` and takes a required `names` array.
- * Condensed responses render each entity through the story's llm
- * formatter and append a `### Errors` section for failed queries. When
- * the story supports `detailed` (MCP default: true), a false value
- * applies the story's summary projection to each result.
- */
-export default function compileLookupTool<TDetailed, TFmtInput>(
-  story: LookupStory<TDetailed, TFmtInput>,
-): ToolSpec {
-  return {
-    name: `${story.noun}_lookup`,
-    description: story.toolDescription,
-    params: buildParams(story),
-    readOnly: true,
-    async execute(rt, params) {
-      const names = (params.names as string[] | undefined) ?? [];
-      const view: LookupStoryView = {
-        surface: "mcp",
-        detailed: resolveLookupDetailed(story, "mcp", params),
-        params,
-      };
-      const result = await story.resolve(rt, names, params);
-
-      if (params.condensed) {
-        const textParts = result.results.map((entity) =>
-          story.formatters.llm(story.toFmtInput(entity, view)),
-        );
-
-        if (result.errors.length > 0) {
-          textParts.push(
-            [
-              "### Errors",
-              ...result.errors.map(
-                (error) => `- ${error.query}: ${error.message}`,
-              ),
-            ].join("\n"),
-          );
-        }
-
-        return condense(textParts.join("\n\n"));
-      }
-
-      const project = story.project;
-      const results =
-        !view.detailed && project
-          ? result.results.map((entity) => project(entity))
-          : result.results;
-
-      return {
-        data: { results, errors: result.errors },
-        meta: lookupToolMeta(result),
-      };
-    },
-  };
-}
-
-function buildParams<TDetailed, TFmtInput>(
-  story: LookupStory<TDetailed, TFmtInput>,
-): Record<string, ToolParamDef> {
-  const detailed: Record<string, ToolParamDef> = story.detailedParam
-    ? {
-        detailed: {
-          type: "boolean",
-          description:
-            story.detailedParam.toolDescription ??
-            story.detailedParam.description,
-          optional: true,
-        },
-      }
-    : {};
-
-  return {
-    names: {
-      type: "string[]",
-      description: story.namesToolDescription ?? story.namesDescription,
-      optional: false,
-    },
-    ...detailed,
-    ...projectToolParams(story.params ?? []),
-    condensed: {
-      type: "boolean",
-      description: "Token-optimized output",
-      optional: true,
-    },
-  };
-}

package/src/domains/shared/stories/compileReadCommand.test.ts

@@ -1,121 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { PragmaError } from "#error";
-import type { PragmaContext } from "../context.js";
-import compileReadCommand from "./compileReadCommand.js";
-import type { ReadStory } from "./types.js";
-
-interface FakeData {
-  readonly items: readonly string[];
-}
-
-function makeStory(
-  overrides: Partial<ReadStory<FakeData, readonly string[]>> = {},
-): ReadStory<FakeData, readonly string[]> {
-  return {
-    noun: "thing",
-    verb: "list",
-    description: "List things",
-    toolDescription: "List things over MCP.",
-    params: [
-      { name: "flag", type: "boolean", description: "a flag", default: false },
-      { name: "hidden", type: "boolean", description: "mcp", surfaces: "mcp" },
-    ],
-    examples: ["pragma thing list"],
-    resolve: async (_rt, params) => ({
-      items: params.flag === true ? ["a", "b", "extra"] : ["a", "b"],
-    }),
-    toOutput: (data) => data.items,
-    formatters: {
-      plain: (items) => `plain:${items.join(",")}`,
-      llm: (items) => `llm:${items.join(",")}`,
-      json: (items) => JSON.stringify(items),
-    },
-    toEnvelope: (data) => ({ data: data.items }),
-    ...overrides,
-  };
-}
-
-function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
-  return {
-    cwd: "/tmp",
-    globalFlags: { llm: false, format: "text" as const, verbose: false },
-    ...overrides,
-  } as PragmaContext;
-}
-
-async function executeOutput(
-  story: ReadStory<FakeData, readonly string[]>,
-  params: Record<string, unknown>,
-  ctx: PragmaContext,
-): Promise<{ value: unknown; text: string }> {
-  const cmd = compileReadCommand(ctx, story);
-  const result = await cmd.execute(params, ctx);
-  if (result.tag !== "output") throw new Error("expected output result");
-  return { value: result.value, text: result.render.plain(result.value) };
-}
-
-describe("compileReadCommand", () => {
-  it("projects path, description, examples, and CLI parameters", () => {
-    const cmd = compileReadCommand(makeCtx(), makeStory());
-    expect(cmd.path).toEqual(["thing", "list"]);
-    expect(cmd.description).toBe("List things");
-    expect(cmd.meta?.examples).toEqual(["pragma thing list"]);
-    expect(cmd.parameters.map((p) => p.name)).toEqual(["flag"]);
-  });
-
-  it("resolves with parameters and renders the plain formatter", async () => {
-    const { value, text } = await executeOutput(
-      makeStory(),
-      { flag: true },
-      makeCtx(),
-    );
-    expect(value).toEqual(["a", "b", "extra"]);
-    expect(text).toBe("plain:a,b,extra");
-  });
-
-  it("selects the llm formatter under --llm", async () => {
-    const ctx = makeCtx({
-      globalFlags: { llm: true, format: "text", verbose: false },
-    });
-    const { text } = await executeOutput(makeStory(), {}, ctx);
-    expect(text).toBe("llm:a,b");
-  });
-
-  it("throws the story's guardParams error before resolving", async () => {
-    const story = makeStory({
-      guardParams: (params) =>
-        params.bad === true
-          ? PragmaError.invalidInput("bad", "true")
-          : undefined,
-    });
-    const cmd = compileReadCommand(makeCtx(), story);
-    await expect(cmd.execute({ bad: true }, makeCtx())).rejects.toThrow(
-      PragmaError,
-    );
-  });
-
-  it("throws the story's emptyError after resolving", async () => {
-    const story = makeStory({
-      resolve: async () => ({ items: [] }),
-      emptyError: (data) =>
-        data.items.length === 0 ? PragmaError.emptyResults("thing") : undefined,
-    });
-    const cmd = compileReadCommand(makeCtx(), story);
-    await expect(cmd.execute({}, makeCtx())).rejects.toThrow(
-      "No things found.",
-    );
-  });
-
-  it("exposes an ink renderer only when the story defines one", async () => {
-    const withInk = makeStory({ renderInk: (items) => `ink:${items.length}` });
-    const cmd = compileReadCommand(makeCtx(), withInk);
-    const result = await cmd.execute({}, makeCtx());
-    if (result.tag !== "output") throw new Error("expected output result");
-    expect(result.render.ink?.(["a"])).toBe("ink:1");
-
-    const plainOnly = compileReadCommand(makeCtx(), makeStory());
-    const plainResult = await plainOnly.execute({}, makeCtx());
-    if (plainResult.tag !== "output") throw new Error("expected output");
-    expect(plainResult.render.ink).toBeUndefined();
-  });
-});