@canonical/pragma-cli 0.30.0 → 0.32.0

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

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

@@ -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;
-}