@canonical/pragma-cli 0.29.0 → 0.30.0

package/src/domains/shared/stories/pack/validateStoryPackDefinition.ts

@@ -0,0 +1,408 @@
+import { PragmaError } from "#error";
+import type {
+  StoryPackColumn,
+  StoryPackDefinition,
+  StoryPackField,
+  StoryPackFilter,
+  StoryPackLookup,
+  StoryPackSection,
+} from "./types.js";
+
+const NOUN_PATTERN = /^[a-z][a-z0-9-]*$/;
+const FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A prefixed name (`ex:Recipe`) — prefix + local part, no path slashes. */
+const PREFIXED_NAME_PATTERN = /^[A-Za-z][\w-]*:[^/<>"\s]+$/;
+
+/** An absolute IRI that can be safely embedded as `<iri>` in SPARQL. */
+const EMBEDDABLE_IRI_PATTERN = /^[A-Za-z][\w+.-]*:\/\/[^<>"\s]+$/;
+
+/**
+ * A filter parameter name: a single lowercase word.
+ *
+ * Deliberately stricter than a noun (no hyphens): the name is used
+ * verbatim as the CLI flag, the Commander result key, and the MCP
+ * parameter key. A hyphenated name would register as `--meal-type` but
+ * be read back by Commander under the camelCased `mealType`, so the
+ * filter would silently never apply on the CLI while working on MCP.
+ * Restricting to one lowercase word keeps all three identical.
+ */
+const FILTER_PARAM_PATTERN = /^[a-z][a-z0-9]*$/;
+
+/**
+ * Parameter names taken by global flags or parameters the kernel appends
+ * to every read story — `condensed` is added to every MCP list tool, and
+ * `detailed` to every lookup — so a filter may not reuse them.
+ */
+const RESERVED_FILTER_PARAMS = new Set([
+  "llm",
+  "format",
+  "verbose",
+  "detailed",
+  "condensed",
+  "names",
+  "help",
+]);
+
+/**
+ * Validate one raw story-pack definition.
+ *
+ * Fails fast with `CONFIG_ERROR` naming the source and the offending
+ * field, mirroring how the `packages` config field is validated.
+ *
+ * @param raw - Parsed JSON value to validate.
+ * @param source - Where the definition came from, for error messages.
+ * @returns The validated definition.
+ * @throws PragmaError with code `CONFIG_ERROR` when the shape is invalid.
+ */
+export default function validateStoryPackDefinition(
+  raw: unknown,
+  source: string,
+): StoryPackDefinition {
+  const obj = requireObject(raw, "story", source);
+
+  const noun = requireString(obj.noun, "noun", source);
+  if (!NOUN_PATTERN.test(noun)) {
+    throw buildStoryConfigError(
+      source,
+      `"noun" must be kebab-case, got "${noun}".`,
+    );
+  }
+
+  const description =
+    obj.description === undefined
+      ? undefined
+      : requireString(obj.description, "description", source);
+  const toolDescription =
+    obj.toolDescription === undefined
+      ? undefined
+      : requireString(obj.toolDescription, "toolDescription", source);
+
+  const list = validateList(obj.list, source);
+  const lookup =
+    obj.lookup === undefined ? undefined : validateLookup(obj.lookup, source);
+
+  return {
+    noun,
+    ...(description !== undefined ? { description } : {}),
+    ...(toolDescription !== undefined ? { toolDescription } : {}),
+    list,
+    ...(lookup ? { lookup } : {}),
+  };
+}
+
+function validateList(
+  raw: unknown,
+  source: string,
+): StoryPackDefinition["list"] {
+  const obj = requireObject(raw, "list", source);
+  const query = requireString(obj.query, "list.query", source);
+  // Strip leading PREFIX declarations so the real query verb is checked —
+  // "PREFIX ex: <…> CONSTRUCT {…}" must fail here, not at first use.
+  const afterPrefixes = query.replace(
+    /^(\s*PREFIX\s+[A-Za-z][\w-]*:\s*<[^>]*>)+/i,
+    "",
+  );
+  if (!/^\s*SELECT\s/i.test(afterPrefixes)) {
+    throw buildStoryConfigError(
+      source,
+      '"list.query" must be a SPARQL SELECT query.',
+    );
+  }
+
+  if (!Array.isArray(obj.columns) || obj.columns.length === 0) {
+    throw buildStoryConfigError(
+      source,
+      '"list.columns" must be a non-empty array.',
+    );
+  }
+  const columns = obj.columns.map((column, index) =>
+    validateColumn(column, `list.columns[${index}]`, source),
+  );
+
+  const filters = validateFilterArray(obj.filters, source);
+  for (const filter of filters ?? []) {
+    if (!referencesVariable(query, filter.variable)) {
+      throw buildStoryConfigError(
+        source,
+        `filter variable "?${filter.variable}" does not appear in "list.query".`,
+      );
+    }
+  }
+
+  return { query, columns, ...(filters ? { filters } : {}) };
+}
+
+/**
+ * Check that the query mentions the variable (`?name` or `$name`).
+ *
+ * A textual check, not a SPARQL parse — it exists to fail typos at boot
+ * instead of silently filtering every row out at first use.
+ */
+function referencesVariable(query: string, variable: string): boolean {
+  const pattern = new RegExp(`[?$]${variable}\\b`);
+  return pattern.test(query);
+}
+
+function validateFilterArray(
+  raw: unknown,
+  source: string,
+): readonly StoryPackFilter[] | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw buildStoryConfigError(
+      source,
+      '"list.filters" must be a non-empty array.',
+    );
+  }
+  const filters = raw.map((entry, index) =>
+    validateFilter(entry, `list.filters[${index}]`, source),
+  );
+  const seen = new Set<string>();
+  for (const filter of filters) {
+    if (seen.has(filter.param)) {
+      throw buildStoryConfigError(
+        source,
+        `duplicate filter param "${filter.param}".`,
+      );
+    }
+    seen.add(filter.param);
+  }
+  return filters;
+}
+
+function validateFilter(
+  raw: unknown,
+  where: string,
+  source: string,
+): StoryPackFilter {
+  const obj = requireObject(raw, where, source);
+  const param = requireString(obj.param, `${where}.param`, source);
+  if (!FILTER_PARAM_PATTERN.test(param)) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.param" must be a single lowercase word (letters and digits, no hyphens), got "${param}".`,
+    );
+  }
+  if (RESERVED_FILTER_PARAMS.has(param)) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.param" "${param}" is a reserved name.`,
+    );
+  }
+  const variable = requireString(obj.variable, `${where}.variable`, source);
+  if (!FIELD_PATTERN.test(variable)) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.variable" must name a SELECT variable.`,
+    );
+  }
+  if (!Array.isArray(obj.values) || obj.values.length === 0) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.values" must be a non-empty array.`,
+    );
+  }
+  const values = obj.values.map((value, index) =>
+    requireString(value, `${where}.values[${index}]`, source),
+  );
+  const lowered = new Set<string>();
+  for (const value of values) {
+    const key = value.toLowerCase();
+    if (lowered.has(key)) {
+      throw buildStoryConfigError(
+        source,
+        `"${where}.values" contains duplicate value "${value}" ` +
+          "(values must be unique, case-insensitively).",
+      );
+    }
+    lowered.add(key);
+  }
+  const description =
+    obj.description === undefined
+      ? undefined
+      : requireString(obj.description, `${where}.description`, source);
+  return {
+    param,
+    variable,
+    values,
+    ...(description !== undefined ? { description } : {}),
+  };
+}
+
+function validateColumn(
+  raw: unknown,
+  where: string,
+  source: string,
+): StoryPackColumn {
+  const obj = requireObject(raw, where, source);
+  const field = requireString(obj.field, `${where}.field`, source);
+  if (!FIELD_PATTERN.test(field)) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.field" must name a SELECT variable.`,
+    );
+  }
+  const label =
+    obj.label === undefined
+      ? undefined
+      : requireString(obj.label, `${where}.label`, source);
+  return { field, ...(label !== undefined ? { label } : {}) };
+}
+
+function validateLookup(raw: unknown, source: string): StoryPackLookup {
+  const obj = requireObject(raw, "lookup", source);
+  const by = requirePredicateTerm(obj.by, "lookup.by", source);
+  const type =
+    obj.type === undefined
+      ? undefined
+      : requireTerm(obj.type, "lookup.type", source);
+
+  const fields = validateFieldArray(obj.fields, "lookup.fields", source);
+  const sections = validateSectionArray(
+    obj.sections,
+    "lookup.sections",
+    source,
+  );
+
+  return {
+    by,
+    ...(type !== undefined ? { type } : {}),
+    ...(fields ? { fields } : {}),
+    ...(sections ? { sections } : {}),
+  };
+}
+
+function validateFieldArray(
+  raw: unknown,
+  where: string,
+  source: string,
+): readonly StoryPackField[] | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw)) {
+    throw buildStoryConfigError(source, `"${where}" must be an array.`);
+  }
+  return raw.map((entry, index) =>
+    validateField(entry, `${where}[${index}]`, source),
+  );
+}
+
+function validateSectionArray(
+  raw: unknown,
+  where: string,
+  source: string,
+): readonly StoryPackSection[] | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw)) {
+    throw buildStoryConfigError(source, `"${where}" must be an array.`);
+  }
+  return raw.map((entry, index) => {
+    const base = validateField(entry, `${where}[${index}]`, source);
+    const obj = entry as Record<string, unknown>;
+    if (obj.kind !== undefined && obj.kind !== "field" && obj.kind !== "code") {
+      throw buildStoryConfigError(
+        source,
+        `"${where}[${index}].kind" must be "field" or "code".`,
+      );
+    }
+    return {
+      ...base,
+      ...(obj.kind !== undefined ? { kind: obj.kind as "field" | "code" } : {}),
+    };
+  });
+}
+
+function validateField(
+  raw: unknown,
+  where: string,
+  source: string,
+): StoryPackField {
+  const obj = requireObject(raw, where, source);
+  const name = requireString(obj.name, `${where}.name`, source);
+  if (!FIELD_PATTERN.test(name)) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.name" must be a simple identifier.`,
+    );
+  }
+  const property = requirePredicateTerm(
+    obj.property,
+    `${where}.property`,
+    source,
+  );
+  const label =
+    obj.label === undefined
+      ? undefined
+      : requireString(obj.label, `${where}.label`, source);
+  return { name, property, ...(label !== undefined ? { label } : {}) };
+}
+
+function requireObject(
+  raw: unknown,
+  where: string,
+  source: string,
+): Record<string, unknown> {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw buildStoryConfigError(source, `"${where}" must be an object.`);
+  }
+  return raw as Record<string, unknown>;
+}
+
+function requireString(raw: unknown, where: string, source: string): string {
+  if (typeof raw !== "string" || raw.trim() === "") {
+    throw buildStoryConfigError(
+      source,
+      `"${where}" must be a non-empty string.`,
+    );
+  }
+  return raw;
+}
+
+/** Require a prefixed name (`ex:Recipe`) or an embeddable absolute IRI. */
+function requireTerm(raw: unknown, where: string, source: string): string {
+  const value = requireString(raw, where, source);
+  if (value.includes("://")) {
+    if (EMBEDDABLE_IRI_PATTERN.test(value)) return value;
+    throw buildStoryConfigError(
+      source,
+      `"${where}" is not a valid IRI (no whitespace or <>" characters).`,
+    );
+  }
+  if (PREFIXED_NAME_PATTERN.test(value)) return value;
+  throw buildStoryConfigError(
+    source,
+    `"${where}" must be a prefixed name (ex:Recipe) or an absolute IRI.`,
+  );
+}
+
+/**
+ * Require a predicate term: a single term or a slash-separated SPARQL
+ * property path of prefixed names (`cs:hasCategory/cs:slug`).
+ *
+ * Paths are only meaningful in predicate position (`lookup.by` and
+ * `fields[].property`/`sections[].property`); class terms go through
+ * `requireTerm` and reject paths.
+ */
+function requirePredicateTerm(
+  raw: unknown,
+  where: string,
+  source: string,
+): string {
+  const value = requireString(raw, where, source);
+  if (value.includes("://") || !value.includes("/")) {
+    return requireTerm(value, where, source);
+  }
+  const segments = value.split("/");
+  for (const segment of segments) {
+    if (!PREFIXED_NAME_PATTERN.test(segment)) {
+      throw buildStoryConfigError(
+        source,
+        `"${where}" property path segment "${segment}" must be a prefixed name.`,
+      );
+    }
+  }
+  return value;
+}
+
+function buildStoryConfigError(source: string, message: string): PragmaError {
+  return PragmaError.configError(`Invalid story in ${source}: ${message}`);
+}

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

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

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

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

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

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

@@ -0,0 +1,23 @@
+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;
+}