@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -1,59 +0,0 @@
-import { describe, expect, it } from "vitest";
-import projectCliParameters from "./projectCliParameters.js";
-import type { StoryParam } from "./types.js";
-
-describe("projectCliParameters", () => {
-  it("drops MCP-only parameters", () => {
-    const params: StoryParam[] = [
-      { name: "a", type: "boolean", description: "a" },
-      { name: "b", type: "boolean", description: "b", surfaces: "mcp" },
-      { name: "c", type: "boolean", description: "c", surfaces: "cli" },
-    ];
-    expect(projectCliParameters(params).map((p) => p.name)).toEqual(["a", "c"]);
-  });
-
-  it("maps string[] to multiselect and enum strings to select with choices", () => {
-    const params: StoryParam[] = [
-      { name: "names", type: "string[]", description: "names" },
-      {
-        name: "mode",
-        type: "string",
-        description: "mode",
-        enum: ["fast", "slow"],
-      },
-    ];
-    const projected = projectCliParameters(params);
-    expect(projected.at(0)?.type).toBe("multiselect");
-    expect(projected.at(1)?.type).toBe("select");
-    expect(projected.at(1)?.choices).toEqual([
-      { label: "fast", value: "fast" },
-      { label: "slow", value: "slow" },
-    ]);
-  });
-
-  it("carries defaults, positionals, required, and completion through", async () => {
-    const complete = async () => ["x"];
-    const params: StoryParam[] = [
-      {
-        name: "prefix",
-        type: "string",
-        description: "prefix",
-        positional: true,
-        required: true,
-        default: "ds",
-        complete,
-      },
-    ];
-    const projected = projectCliParameters(params);
-    const first = projected.at(0);
-    expect(first?.positional).toBe(true);
-    expect(first?.required).toBe(true);
-    expect(first?.default).toBe("ds");
-    await expect(
-      first?.complete?.("d", {
-        cwd: "/",
-        globalFlags: { llm: false, format: "text", verbose: false },
-      }),
-    ).resolves.toEqual(["x"]);
-  });
-});

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

@@ -1,57 +0,0 @@
-import type { ParameterDefinition } from "@canonical/cli-core";
-import type { StoryParam } from "./types.js";
-
-/**
- * Project story parameters onto cli-core `ParameterDefinition`s.
- *
- * MCP-only parameters are dropped; `string[]` becomes a multiselect;
- * an `enum` on a string parameter becomes a select with choices.
- */
-export default function projectCliParameters(
-  params: readonly StoryParam[],
-): ParameterDefinition[] {
-  return params
-    .filter((param) => (param.surfaces ?? "both") !== "mcp")
-    .map((param) => toParameterDefinition(param));
-}
-
-function toParameterDefinition(param: StoryParam): ParameterDefinition {
-  const definition: {
-    name: string;
-    description: string;
-    type: ParameterDefinition["type"];
-    choices?: ParameterDefinition["choices"];
-    default?: unknown;
-    positional?: boolean;
-    required?: boolean;
-    complete?: ParameterDefinition["complete"];
-  } = {
-    name: param.name,
-    description: param.description,
-    type: resolveCliType(param),
-  };
-
-  if (param.enum) {
-    definition.choices = param.enum.map((value) => ({ label: value, value }));
-  }
-  if (param.default !== undefined) {
-    definition.default = param.default;
-  }
-  if (param.positional === true) {
-    definition.positional = true;
-  }
-  if (param.required === true) {
-    definition.required = true;
-  }
-  if (param.complete) {
-    definition.complete = param.complete;
-  }
-
-  return definition;
-}
-
-function resolveCliType(param: StoryParam): ParameterDefinition["type"] {
-  if (param.type === "string[]") return "multiselect";
-  if (param.type === "string" && param.enum) return "select";
-  return param.type;
-}

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

@@ -1,50 +0,0 @@
-import { describe, expect, it } from "vitest";
-import projectToolParams from "./projectToolParams.js";
-import type { StoryParam } from "./types.js";
-
-describe("projectToolParams", () => {
-  it("drops CLI-only parameters", () => {
-    const params: StoryParam[] = [
-      { name: "a", type: "boolean", description: "a" },
-      { name: "b", type: "boolean", description: "b", surfaces: "cli" },
-      { name: "c", type: "boolean", description: "c", surfaces: "mcp" },
-    ];
-    expect(Object.keys(projectToolParams(params))).toEqual(["a", "c"]);
-  });
-
-  it("prefers the tool description and sets optional from required", () => {
-    const params: StoryParam[] = [
-      {
-        name: "names",
-        type: "string[]",
-        description: "cli text",
-        toolDescription: "mcp text",
-        required: true,
-      },
-      { name: "flag", type: "boolean", description: "shared text" },
-    ];
-    const projected = projectToolParams(params);
-    expect(projected.names).toEqual({
-      type: "string[]",
-      description: "mcp text",
-      optional: false,
-    });
-    expect(projected.flag).toEqual({
-      type: "boolean",
-      description: "shared text",
-      optional: true,
-    });
-  });
-
-  it("carries enums through", () => {
-    const params: StoryParam[] = [
-      {
-        name: "mode",
-        type: "string",
-        description: "mode",
-        enum: ["fast", "slow"],
-      },
-    ];
-    expect(projectToolParams(params).mode?.enum).toEqual(["fast", "slow"]);
-  });
-});

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

@@ -1,32 +0,0 @@
-import type { ToolParamDef } from "../ToolSpec.js";
-import type { StoryParam } from "./types.js";
-
-/**
- * Project story parameters onto MCP `ToolParamDef`s.
- *
- * CLI-only parameters are dropped, along with CLI-only attributes
- * (defaults, positionals, completion). Required parameters set
- * `optional: false` explicitly — the MCP adapter treats anything
- * else as optional.
- */
-export default function projectToolParams(
-  params: readonly StoryParam[],
-): Record<string, ToolParamDef> {
-  const projected: Record<string, ToolParamDef> = {};
-
-  for (const param of params) {
-    if ((param.surfaces ?? "both") === "cli") continue;
-    projected[param.name] = toToolParamDef(param);
-  }
-
-  return projected;
-}
-
-function toToolParamDef(param: StoryParam): ToolParamDef {
-  return {
-    type: param.type,
-    description: param.toolDescription ?? param.description,
-    optional: param.required !== true,
-    ...(param.enum && { enum: param.enum }),
-  };
-}

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

@@ -1,23 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { PragmaError } from "#error";
-import type { PragmaContext } from "../context.js";
-import requirePragmaContext from "./requirePragmaContext.js";
-
-describe("requirePragmaContext", () => {
-  it("returns a context that carries the pragma runtime", () => {
-    const ctx = {
-      cwd: "/",
-      globalFlags: { llm: false, format: "text", verbose: false },
-      store: {},
-    } as unknown as PragmaContext;
-    expect(requirePragmaContext(ctx)).toBe(ctx);
-  });
-
-  it("throws for a context without the runtime", () => {
-    const bare = {
-      cwd: "/",
-      globalFlags: { llm: false, format: "text" as const, verbose: false },
-    };
-    expect(() => requirePragmaContext(bare)).toThrow(PragmaError);
-  });
-});

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

@@ -1,23 +0,0 @@
-import type { CommandContext } from "@canonical/cli-core";
-import { PragmaError } from "#error";
-import type { PragmaContext } from "../context.js";
-
-/**
- * Narrow a cli-core `CommandContext` to the pragma context.
- *
- * Story completion callbacks receive the cli-core context type, but every
- * context the pragma pipeline constructs is a `PragmaContext` (it carries
- * the ke store and config). This asserts that invariant at runtime instead
- * of casting silently, failing fast if a foreign context ever appears.
- */
-export default function requirePragmaContext(
-  ctx: CommandContext,
-): PragmaContext {
-  if (!("store" in ctx)) {
-    throw PragmaError.internalError(
-      "completion context is missing the pragma runtime",
-    );
-  }
-  // Proven one line up: a context carrying `store` is a PragmaContext.
-  return ctx as PragmaContext;
-}

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

@@ -1,57 +0,0 @@
-import { describe, expect, it } from "vitest";
-import resolveLookupDetailed from "./resolveLookupDetailed.js";
-import type { LookupStory } from "./types.js";
-
-type AnyLookupStory = LookupStory<unknown, unknown>;
-
-const baseStory: Pick<
-  AnyLookupStory,
-  "noun" | "description" | "toolDescription" | "namesDescription"
-> = {
-  noun: "thing",
-  description: "d",
-  toolDescription: "td",
-  namesDescription: "names",
-};
-
-function makeStory(overrides: Partial<AnyLookupStory>): AnyLookupStory {
-  return {
-    ...baseStory,
-    examples: [],
-    resolve: async () => ({ results: [], errors: [] }),
-    toFmtInput: (entity) => entity,
-    formatters: {
-      plain: () => "",
-      llm: () => "",
-      json: () => "",
-    },
-    ...overrides,
-  };
-}
-
-describe("resolveLookupDetailed", () => {
-  it("is never detailed when the story has no detailed param", () => {
-    const story = makeStory({});
-    expect(resolveLookupDetailed(story, "cli", { detailed: true })).toBe(false);
-    expect(resolveLookupDetailed(story, "mcp", {})).toBe(false);
-  });
-
-  it("defaults detailed to true on MCP and false on CLI", () => {
-    const story = makeStory({ detailedParam: { description: "d" } });
-    expect(resolveLookupDetailed(story, "mcp", {})).toBe(true);
-    expect(resolveLookupDetailed(story, "mcp", { detailed: false })).toBe(
-      false,
-    );
-    expect(resolveLookupDetailed(story, "cli", {})).toBe(false);
-    expect(resolveLookupDetailed(story, "cli", { detailed: true })).toBe(true);
-  });
-
-  it("lets a story override the surface defaults", () => {
-    const story = makeStory({
-      detailedParam: { description: "d" },
-      resolveDetailed: (surface) => surface === "cli",
-    });
-    expect(resolveLookupDetailed(story, "cli", {})).toBe(true);
-    expect(resolveLookupDetailed(story, "mcp", {})).toBe(false);
-  });
-});

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

@@ -1,27 +0,0 @@
-import type { LookupStory } from "./types.js";
-
-/**
- * Resolve the effective `detailed` flag for a lookup story on a surface.
- *
- * Defaults follow the ratified surface contract: the CLI opts in
- * (`detailed` is false unless set) while MCP opts out (`detailed` is true
- * unless set, since agents want full data by default). Stories without a
- * `detailed` parameter are never detailed. A story's `resolveDetailed`
- * override wins — block uses it to let aspect flags imply detail.
- */
-export default function resolveLookupDetailed<TDetailed, TFmtInput>(
-  story: LookupStory<TDetailed, TFmtInput>,
-  surface: "cli" | "mcp",
-  params: Record<string, unknown>,
-): boolean {
-  if (story.resolveDetailed) {
-    return story.resolveDetailed(surface, params);
-  }
-  if (!story.detailedParam) {
-    return false;
-  }
-  if (surface === "mcp") {
-    return ((params.detailed as boolean | undefined) ?? true) === true;
-  }
-  return params.detailed === true;
-}

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

@@ -1,179 +0,0 @@
-/**
- * Read-story spec types — one declaration per read story, many projections.
- *
- * A read story (list, show, or lookup) is declared once per domain and
- * compiled into both surfaces: a cli-core `CommandDefinition` and a
- * declarative MCP `ToolSpec`. The compilers in this folder own the shared
- * execute skeletons — parameter projection, condensed rendering with token
- * estimates, empty-result guards, and summary projection — so a domain
- * supplies only its facts: descriptions, parameters, resolve function,
- * formatters, and envelope mapping. This kills the per-domain duplication
- * between `commands/*.ts` and `mcp/specs.ts` for read verbs and makes
- * CLI/MCP parity structural instead of conventional.
- */
-
-import type { CommandContext } from "@canonical/cli-core";
-import type { PragmaError } from "#error";
-import type { LookupResult } from "../contracts.js";
-import type { Formatters } from "../formatters.js";
-import type { PragmaRuntime } from "../types/index.js";
-
-/** Surfaces a story parameter is projected to (default: "both"). */
-export type StorySurface = "both" | "cli" | "mcp";
-
-/**
- * Neutral parameter definition projected to a CLI flag and an MCP tool
- * parameter. `string[]` becomes a CLI multiselect and an MCP string array.
- */
-export interface StoryParam {
-  readonly name: string;
-  readonly type: "string" | "boolean" | "string[]";
-  /** CLI help text; also the MCP description unless `toolDescription` is set. */
-  readonly description: string;
-  /** MCP-specific description override. */
-  readonly toolDescription?: string;
-  readonly required?: boolean;
-  /** CLI default value — MCP parameters carry no defaults. */
-  readonly default?: unknown;
-  /** Allowed values; projects to CLI select choices and an MCP enum. */
-  readonly enum?: readonly string[];
-  /** If true, the CLI accepts this parameter as a positional argument. */
-  readonly positional?: boolean;
-  /** Surfaces this parameter appears on (default: "both"). */
-  readonly surfaces?: StorySurface;
-  /** CLI tab-completion for this parameter's argument. */
-  readonly complete?: (
-    partial: string,
-    ctx: CommandContext,
-  ) => Promise<string[]>;
-}
-
-/** MCP envelope fragment produced by a story's `toEnvelope`. */
-export interface StoryEnvelope {
-  readonly data: unknown;
-  readonly meta?: Record<string, unknown>;
-}
-
-/**
- * A collection-or-singleton read story (`<noun> list`, `<noun> show`).
- *
- * `TData` is the domain's resolved payload; `TOutput` is the formatter and
- * renderer input derived from it via `toOutput`.
- */
-export interface ReadStory<TData, TOutput> {
-  readonly noun: string;
-  /** Read verb this story projects to (e.g. "list", "show"). */
-  readonly verb: string;
-  /** CLI one-line help description. */
-  readonly description: string;
-  /** MCP tool description. */
-  readonly toolDescription: string;
-  readonly params: readonly StoryParam[];
-  /** Usage examples shown in CLI help. */
-  readonly examples: readonly string[];
-  /** Fetch the story's data. Shared verbatim by both surfaces. */
-  readonly resolve: (
-    rt: PragmaRuntime,
-    params: Record<string, unknown>,
-  ) => Promise<TData>;
-  /** Map resolved data to the formatter/renderer input. */
-  readonly toOutput: (data: TData, params: Record<string, unknown>) => TOutput;
-  readonly formatters: Formatters<TOutput>;
-  /** Map resolved data to the MCP `{ data, meta }` envelope. */
-  readonly toEnvelope: (data: TData) => StoryEnvelope;
-  /**
-   * CLI-only pre-resolve guard: return an error to reject invalid
-   * parameters (e.g. an empty required positional).
-   */
-  readonly guardParams?: (
-    params: Record<string, unknown>,
-  ) => PragmaError | undefined;
-  /**
-   * CLI-only post-resolve guard: return an error to reject an empty
-   * result set with a recovery hint.
-   */
-  readonly emptyError?: (
-    data: TData,
-    params: Record<string, unknown>,
-  ) => PragmaError | undefined;
-  /** Optional interactive (ink) renderer for the CLI. */
-  readonly renderInk?: (output: TOutput) => unknown;
-}
-
-/** Per-invocation view state passed to lookup story hooks. */
-export interface LookupStoryView {
-  readonly surface: "cli" | "mcp";
-  /** Effective detail level after surface defaults and flag implications. */
-  readonly detailed: boolean;
-  readonly params: Record<string, unknown>;
-}
-
-/**
- * A batch retrieval story (`<noun> lookup <names...>`).
- *
- * `TDetailed` is the looked-up entity; `TFmtInput` is the per-entity
- * formatter input derived via `toFmtInput` (some domains pair the entity
- * with view flags such as `detailed` or aspect selections).
- */
-export interface LookupStory<TDetailed, TFmtInput> {
-  readonly noun: string;
-  readonly description: string;
-  readonly toolDescription: string;
-  /** CLI description of the `names` positional parameter. */
-  readonly namesDescription: string;
-  /** MCP-specific `names` description override. */
-  readonly namesToolDescription?: string;
-  /** CLI tab-completion for names. */
-  readonly complete?: (
-    partial: string,
-    ctx: CommandContext,
-  ) => Promise<string[]>;
-  /**
-   * The `detailed` toggle, when the story supports one. MCP defaults
-   * `detailed` to true; the CLI defaults it to false.
-   */
-  readonly detailedParam?: {
-    readonly description: string;
-    readonly toolDescription?: string;
-  };
-  /** Additional story parameters beyond `names` and `detailed`. */
-  readonly params?: readonly StoryParam[];
-  /** Named groups for organizing CLI parameters in help output. */
-  readonly parameterGroups?: Readonly<Record<string, readonly string[]>>;
-  readonly examples: readonly string[];
-  /**
-   * Resolve all queries, collecting per-query failures.
-   *
-   * The compilers pass the per-invocation `view` so surface-sensitive
-   * resolution (e.g. pack disclosure defaults, which differ between the
-   * CLI and MCP per the ratified surface contract) can see which surface
-   * is calling; most stories ignore it.
-   */
-  readonly resolve: (
-    rt: PragmaRuntime,
-    names: readonly string[],
-    params: Record<string, unknown>,
-    view?: LookupStoryView,
-  ) => Promise<LookupResult<TDetailed>>;
-  /**
-   * Effective `detailed` for a surface. Defaults to the plain flag value
-   * (CLI: false unless set; MCP: true unless set). Domains override this
-   * when other flags imply detail (e.g. block aspect filters).
-   */
-  readonly resolveDetailed?: (
-    surface: "cli" | "mcp",
-    params: Record<string, unknown>,
-  ) => boolean;
-  /** Map an entity to the per-entity formatter input. */
-  readonly toFmtInput: (entity: TDetailed, view: LookupStoryView) => TFmtInput;
-  readonly formatters: Formatters<TFmtInput>;
-  /** MCP summary projection applied when `detailed` is false. */
-  readonly project?: (entity: TDetailed) => unknown;
-  /** CLI-only error thrown when no names are supplied. */
-  readonly emptyNamesError?: () => PragmaError;
-  /** Optional interactive (ink) renderer for the CLI. */
-  readonly renderInk?: (
-    result: LookupResult<TDetailed>,
-    view: LookupStoryView,
-  ) => unknown;
-}

package/src/domains/shared/suggestions/detectCrossDomain.test.ts

@@ -1,43 +0,0 @@
-import type { Store } from "@canonical/ke";
-import { describe, expect, it } from "vitest";
-import { createTestStore, DS_ALL_TTL } from "#testing";
-import detectCrossDomain from "./detectCrossDomain.js";
-
-let store: Store;
-let cleanup: () => void;
-
-describe("detectCrossDomain", () => {
-  beforeAll(async () => {
-    const result = await createTestStore({ ttl: DS_ALL_TTL });
-    store = result.store;
-    cleanup = result.cleanup;
-  });
-
-  afterAll(() => {
-    cleanup();
-  });
-
-  it("T2-4: returns undefined when name is not in any domain", async () => {
-    const hint = await detectCrossDomain("nonexistent_xyz", "token", store);
-    expect(hint).toBeUndefined();
-  });
-
-  it("returns a hint with the correct shape", async () => {
-    const hint = await detectCrossDomain("Button", "modifier", store);
-    if (hint) {
-      expect(hint).toHaveProperty("domain");
-      expect(hint).toHaveProperty("entityType");
-      expect(hint).toHaveProperty("cli");
-      expect(hint).toHaveProperty("mcp");
-      expect(hint.mcp).toHaveProperty("tool");
-      expect(hint.mcp).toHaveProperty("params");
-    }
-  });
-
-  it("skips the current domain", async () => {
-    const hint = await detectCrossDomain("Button", "block", store);
-    if (hint) {
-      expect(hint.domain).not.toBe("block");
-    }
-  });
-});

package/src/domains/shared/suggestions/detectCrossDomain.ts

@@ -1,116 +0,0 @@
-import type { SPARQL, Store } from "@canonical/ke";
-import { escapeSparqlValue } from "@canonical/ke";
-import { buildQuery } from "../buildQuery.js";
-import { P } from "../prefixes.js";
-
-/**
- * Structured hint pointing the user/agent to the correct domain
- * when a name exists in a different domain than the one queried.
- */
-export interface CrossDomainHint {
-  /** Domain where the name was found (e.g., "modifier"). */
-  readonly domain: string;
-  /** Entity type label for messages (e.g., "modifier"). */
-  readonly entityType: string;
-  /** CLI recovery command. */
-  readonly cli: string;
-  /** MCP recovery tool + params. */
-  readonly mcp: { tool: string; params: Record<string, unknown> };
-}
-
-interface DomainSpec {
-  readonly domain: string;
-  readonly entityType: string;
-  readonly lookupTool: string;
-  readonly cliCommand: string;
-  readonly query: (name: string) => SPARQL<string>;
-}
-
-const DOMAIN_SPECS: readonly DomainSpec[] = [
-  {
-    domain: "block",
-    entityType: "block",
-    lookupTool: "block_lookup",
-    cliCommand: "pragma block lookup",
-    query: (name) =>
-      buildQuery(`
-        ASK {
-          VALUES ?type { ${P.ds}Component ${P.ds}Pattern ${P.ds}Layout ${P.ds}Subcomponent }
-          ?s a ?type ; ${P.ds}name ?name .
-          FILTER(LCASE(STR(?name)) = LCASE(${escapeSparqlValue(name)}))
-        }
-      `),
-  },
-  {
-    domain: "token",
-    entityType: "token",
-    lookupTool: "token_lookup",
-    cliCommand: "pragma token lookup",
-    query: (name) =>
-      buildQuery(`
-        ASK {
-          ?s a ${P.ds}Token ; ${P.ds}tokenId ?id .
-          FILTER(LCASE(STR(?id)) = LCASE(${escapeSparqlValue(name)}))
-        }
-      `),
-  },
-  {
-    domain: "modifier",
-    entityType: "modifier",
-    lookupTool: "modifier_lookup",
-    cliCommand: "pragma modifier lookup",
-    query: (name) =>
-      buildQuery(`
-        ASK {
-          ?s a ${P.ds}ModifierFamily ; ${P.ds}name ?name .
-          FILTER(LCASE(STR(?name)) = LCASE(${escapeSparqlValue(name)}))
-        }
-      `),
-  },
-  {
-    domain: "standard",
-    entityType: "standard",
-    lookupTool: "standard_lookup",
-    cliCommand: "pragma standard lookup",
-    query: (name) =>
-      buildQuery(`
-        ASK {
-          ?s a ${P.cs}CodeStandard ; ${P.cs}name ?name .
-          FILTER(LCASE(STR(?name)) = LCASE(${escapeSparqlValue(name)}))
-        }
-      `),
-  },
-];
-
-/**
- * Check if a name exists in a domain other than the current one.
- *
- * Queries each domain in a deterministic order (block → token → modifier → standard)
- * and returns the first match. Returns undefined if the name is not found anywhere.
- *
- * @param name - The user-supplied name.
- * @param currentDomain - The domain the user queried (e.g., "token").
- * @param store - ke store for cross-domain queries.
- * @returns Hint pointing to the correct domain, or undefined.
- */
-export default async function detectCrossDomain(
-  name: string,
-  currentDomain: string,
-  store: Store,
-): Promise<CrossDomainHint | undefined> {
-  for (const spec of DOMAIN_SPECS) {
-    if (spec.domain === currentDomain) continue;
-
-    const result = await store.query(spec.query(name));
-    if (result.type === "ask" && result.result) {
-      return {
-        domain: spec.domain,
-        entityType: spec.entityType,
-        cli: `${spec.cliCommand} ${name}`,
-        mcp: { tool: spec.lookupTool, params: { names: [name] } },
-      };
-    }
-  }
-
-  return undefined;
-}