@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

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

@@ -0,0 +1,104 @@
+/**
+ * Declarative story-pack definitions — read stories as data.
+ *
+ * A story pack maps a noun to preferred queries: a SPARQL SELECT for the
+ * list story and a generated, injection-safe lookup. Definitions are
+ * declared in `pragma.config.json` (`stories`) or shipped by semantic
+ * packages (`stories/*.json`) and compiled through the read-story kernel
+ * into CLI commands and MCP tools at boot.
+ *
+ * @experimental The story-pack format (v0) is experimental: field names,
+ * lookup generation, and rendering semantics may change while GraphQL
+ * document queries and SHACL-derived defaults are designed.
+ */
+
+/** A list column: a SELECT variable to display. */
+export interface StoryPackColumn {
+  /** SELECT variable name (without `?`). */
+  readonly field: string;
+  /** Column heading (defaults to the field name). */
+  readonly label?: string;
+}
+
+/** A looked-up value: an output name bound to a property of the entity. */
+export interface StoryPackField {
+  /** Output field name on the looked-up entity. */
+  readonly name: string;
+  /** Property to read — a prefixed name (`ex:category`) or absolute IRI. */
+  readonly property: string;
+  /** Display label (defaults to the field name). */
+  readonly label?: string;
+}
+
+/** A long-form lookup section. */
+export interface StoryPackSection extends StoryPackField {
+  /** Rendering kind (v0 supports inline fields and code blocks). */
+  readonly kind?: "field" | "code";
+}
+
+/**
+ * A declarative list filter: a CLI/MCP parameter constraining one SELECT
+ * variable to a declared value set.
+ *
+ * Filters are row predicates applied AFTER the author query runs — the
+ * query text is never modified, so filter input cannot inject SPARQL,
+ * and the author's ORDER BY is preserved.
+ */
+export interface StoryPackFilter {
+  /**
+   * Parameter name — a single lowercase word, exposed as `--param` on the
+   * CLI and as the parameter key on the MCP tool.
+   */
+  readonly param: string;
+  /** SELECT variable the filter constrains (without `?`). */
+  readonly variable: string;
+  /** Allowed values; anything else is rejected with INVALID_INPUT. */
+  readonly values: readonly string[];
+  /** Help text (defaults to a generated description). */
+  readonly description?: string;
+}
+
+/** The list half of a story pack. */
+export interface StoryPackList {
+  /** SPARQL SELECT producing one row per item. */
+  readonly query: string;
+  /** Columns to render, referencing SELECT variables. */
+  readonly columns: readonly StoryPackColumn[];
+  /** Declarative filters projected to CLI flags and MCP parameters. */
+  readonly filters?: readonly StoryPackFilter[];
+}
+
+/**
+ * The lookup half of a story pack. The query is generated from `type` and
+ * `by` — user-supplied names are escaped by the generator, never
+ * interpolated by the author.
+ */
+export interface StoryPackLookup {
+  /** Property whose value names the entity — prefixed name or IRI. */
+  readonly by: string;
+  /** Optional class constraint — prefixed name or IRI. */
+  readonly type?: string;
+  /** Inline fields shown under the entity title. */
+  readonly fields?: readonly StoryPackField[];
+  /** Long-form sections shown after the fields. */
+  readonly sections?: readonly StoryPackSection[];
+}
+
+/** One declarative read story: a noun with its preferred queries. */
+export interface StoryPackDefinition {
+  /** Command noun (kebab-case), e.g. `"recipe"` → `pragma recipe list`. */
+  readonly noun: string;
+  /** CLI description for the list command. */
+  readonly description?: string;
+  /** MCP tool description (defaults to the CLI description). */
+  readonly toolDescription?: string;
+  readonly list: StoryPackList;
+  readonly lookup?: StoryPackLookup;
+}
+
+/** A story definition with the source it came from, for diagnostics. */
+export interface StoryPackSource {
+  /** Where the definition was declared (config path or package file). */
+  readonly source: string;
+  readonly definition: StoryPackDefinition;
+}

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

@@ -0,0 +1,240 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import { RECIPE_STORY } from "#testing";
+import validateStoryPackDefinition from "./validateStoryPackDefinition.js";
+
+describe("validateStoryPackDefinition", () => {
+  it("accepts a valid definition and round-trips it", () => {
+    const validated = validateStoryPackDefinition(
+      JSON.parse(JSON.stringify(RECIPE_STORY)),
+      "test",
+    );
+    expect(validated).toEqual(RECIPE_STORY);
+  });
+
+  it("rejects a non-kebab noun", () => {
+    expect(() =>
+      validateStoryPackDefinition({ ...RECIPE_STORY, noun: "Recipe" }, "test"),
+    ).toThrow(PragmaError);
+  });
+
+  it("rejects a list without a SELECT query", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        {
+          ...RECIPE_STORY,
+          list: { ...RECIPE_STORY.list, query: "DELETE WHERE { ?s ?p ?o }" },
+        },
+        "test",
+      ),
+    ).toThrow(/SELECT/);
+  });
+
+  it("rejects empty columns", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        { ...RECIPE_STORY, list: { ...RECIPE_STORY.list, columns: [] } },
+        "test",
+      ),
+    ).toThrow(/columns/);
+  });
+
+  it("rejects a lookup term that is neither prefixed nor an IRI", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        {
+          ...RECIPE_STORY,
+          lookup: { by: "just a name" },
+        },
+        "test",
+      ),
+    ).toThrow(/prefixed name/);
+  });
+
+  it("rejects an unknown section kind", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        {
+          ...RECIPE_STORY,
+          lookup: {
+            by: "ex:name",
+            sections: [{ name: "x", property: "ex:x", kind: "table" }],
+          },
+        },
+        "test",
+      ),
+    ).toThrow(/kind/);
+  });
+
+  it("names the source in errors", () => {
+    try {
+      validateStoryPackDefinition({}, "/pkg/stories/broken.json");
+      expect.unreachable("should have thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(PragmaError);
+      expect((error as PragmaError).message).toContain(
+        "/pkg/stories/broken.json",
+      );
+    }
+  });
+});
+
+describe("validateStoryPackDefinition — term and query hardening", () => {
+  function withLookup(lookup: Record<string, unknown>): unknown {
+    const base = JSON.parse(JSON.stringify(RECIPE_STORY)) as Record<
+      string,
+      unknown
+    >;
+    return { ...base, lookup: { ...(base.lookup as object), ...lookup } };
+  }
+
+  it("rejects a slashed prefixed name in class position", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withLookup({ type: "ex:Recipe/Sub" }),
+        "test",
+      ),
+    ).toThrow(/must be a prefixed name/);
+  });
+
+  it("accepts a property path in predicate position", () => {
+    const validated = validateStoryPackDefinition(
+      withLookup({ by: "ex:hasName/ex:value" }),
+      "test",
+    );
+    expect(validated.lookup?.by).toBe("ex:hasName/ex:value");
+  });
+
+  it("rejects a property path with a malformed segment", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withLookup({ by: "ex:hasName/not a name" }),
+        "test",
+      ),
+    ).toThrow(/property path segment/);
+  });
+
+  it("rejects an IRI that cannot embed in SPARQL", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withLookup({ type: "https://example.org/a b>c" }),
+        "test",
+      ),
+    ).toThrow(/not a valid IRI/);
+  });
+
+  it("rejects a PREFIX-led non-SELECT list query", () => {
+    const base = JSON.parse(JSON.stringify(RECIPE_STORY)) as Record<
+      string,
+      unknown
+    >;
+    const list = {
+      ...(base.list as Record<string, unknown>),
+      query:
+        "PREFIX ex: <http://example.org/> CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }",
+    };
+    expect(() =>
+      validateStoryPackDefinition({ ...base, list }, "test"),
+    ).toThrow(/must be a SPARQL SELECT/);
+  });
+});
+
+describe("validateStoryPackDefinition — list filters", () => {
+  const base = JSON.parse(JSON.stringify(RECIPE_STORY)) as Record<
+    string,
+    unknown
+  >;
+
+  function withFilters(filters: unknown): unknown {
+    const list = { ...(base.list as Record<string, unknown>), filters };
+    return { ...base, list };
+  }
+
+  it("accepts declared filters", () => {
+    const validated = validateStoryPackDefinition(
+      withFilters([
+        { param: "category", variable: "category", values: ["soup"] },
+      ]),
+      "test",
+    );
+    expect(validated.list.filters?.at(0)?.param).toBe("category");
+  });
+
+  it("rejects an empty filters array", () => {
+    expect(() => validateStoryPackDefinition(withFilters([]), "test")).toThrow(
+      /list.filters/,
+    );
+  });
+
+  it("rejects reserved parameter names", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withFilters([{ param: "format", variable: "category", values: ["x"] }]),
+        "test",
+      ),
+    ).toThrow(/reserved/);
+  });
+
+  it("rejects the MCP-appended condensed parameter name", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withFilters([
+          { param: "condensed", variable: "category", values: ["x"] },
+        ]),
+        "test",
+      ),
+    ).toThrow(/reserved/);
+  });
+
+  it("rejects a hyphenated parameter name that breaks CLI readback", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withFilters([
+          { param: "meal-type", variable: "category", values: ["x"] },
+        ]),
+        "test",
+      ),
+    ).toThrow(/single lowercase word/);
+  });
+
+  it("rejects duplicate parameter names", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withFilters([
+          { param: "category", variable: "category", values: ["x"] },
+          { param: "category", variable: "name", values: ["y"] },
+        ]),
+        "test",
+      ),
+    ).toThrow(/duplicate filter param/);
+  });
+
+  it("rejects a filter variable the query never mentions", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withFilters([{ param: "season", variable: "season", values: ["x"] }]),
+        "test",
+      ),
+    ).toThrow(/does not appear in "list.query"/);
+  });
+
+  it("rejects case-insensitive duplicate values", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withFilters([
+          { param: "category", variable: "category", values: ["Soup", "soup"] },
+        ]),
+        "test",
+      ),
+    ).toThrow(/duplicate value/);
+  });
+
+  it("rejects empty values arrays", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withFilters([{ param: "category", variable: "category", values: [] }]),
+        "test",
+      ),
+    ).toThrow(/values/);
+  });
+});