@canonical/pragma-cli 0.30.0 → 0.31.0

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

@@ -36,9 +36,66 @@ export interface StoryPackSection extends StoryPackField {
   readonly kind?: "field" | "code";
 }
 
+/** A field read from each child node of an {@link StoryPackExpand}. */
+export interface StoryPackExpandField {
+  /** Output field name on the child record. */
+  readonly name: string;
+  /** Property to read on the child node — prefixed name, IRI, or path. */
+  readonly property: string;
+  /** Display label (defaults to the field name). */
+  readonly label?: string;
+}
+
+/**
+ * A multi-valued nested projection: `entity → relation → child nodes`, each
+ * child projected to a small record. This is pack v1's structured-section
+ * primitive — the one thing v0 could not express (dos/donts, token scales,
+ * modifier values). Resolved with a generated, injection-safe sub-SELECT bound
+ * to the already-resolved entity IRI (never user input), so it needs no
+ * GraphQL. Rendered through the shared `list`/`table` render-kinds.
+ */
+export interface StoryPackExpand {
+  /** Output field holding the child array on the looked-up entity. */
+  readonly name: string;
+  /** Section heading (defaults to the field name). */
+  readonly heading?: string;
+  /** Render kind for the array (v1: `list` or `table`; defaults to `list`). */
+  readonly kind?: "list" | "table";
+  /** Relation from the entity to each child node — prefixed name, IRI, or path. */
+  readonly relation: string;
+  /** Fields to read from each child node. */
+  readonly select: readonly StoryPackExpandField[];
+  /** Render the section even when the array is empty (default: false). */
+  readonly showWhenEmpty?: boolean;
+  /**
+   * Minimum disclosure level at which this expand is fetched and rendered — a
+   * name from {@link StoryPackDisclosure.levels}. Omitted means the base level
+   * (always included). Below its level the sub-SELECT never runs, so gating is
+   * both a cost and a rendering control.
+   */
+  readonly level?: string;
+}
+
+/**
+ * Progressive-disclosure capability for a lookup.
+ *
+ * Declares an **ordered** list of named levels (the first is the base/default,
+ * always shown). Fields/expands tag themselves with the minimum level at which
+ * they appear. The compiler derives from this one declaration: a `--detail
+ * <level>` CLI flag, a `detail` MCP parameter (enumerated from the levels), and
+ * the JSON/plain/llm projection for the selected level. Levels are additive and
+ * optional — a lookup with no disclosure exposes no detail flag.
+ */
+export interface StoryPackDisclosure {
+  /** Ordered level names, lowest → highest. The first is the base/default. */
+  readonly levels: readonly string[];
+  /** Default level when none is requested (must be one of `levels`). */
+  readonly default?: string;
+}
+
 /**
  * A declarative list filter: a CLI/MCP parameter constraining one SELECT
- * variable to a declared value set.
+ * variable.
  *
  * Filters are row predicates applied AFTER the author query runs — the
  * query text is never modified, so filter input cannot inject SPARQL,
@@ -52,8 +109,27 @@ export interface StoryPackFilter {
   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[];
+  /**
+   * Allowed values; anything else is rejected with INVALID_INPUT and the
+   * set projects to CLI select choices and an MCP enum. Omitted when the
+   * value set is data-driven (e.g. categories that live in the graph): the
+   * parameter is then a free string matched case-insensitively against the
+   * variable — still a post-query row predicate, never query text.
+   */
+  readonly values?: readonly string[];
+  /** Help text (defaults to a generated description). */
+  readonly description?: string;
+}
+
+/**
+ * Free-text search over list rows: a `--search` string parameter that
+ * keeps a row when ANY named SELECT variable's value contains the term
+ * (case-insensitive substring). Like filters, search is applied after the
+ * author query runs — user input never touches the query text.
+ */
+export interface StoryPackSearch {
+  /** SELECT variables searched (without `?`). */
+  readonly variables: readonly string[];
   /** Help text (defaults to a generated description). */
   readonly description?: string;
 }
@@ -66,6 +142,38 @@ export interface StoryPackList {
   readonly columns: readonly StoryPackColumn[];
   /** Declarative filters projected to CLI flags and MCP parameters. */
   readonly filters?: readonly StoryPackFilter[];
+  /** Free-text search projected to a `--search` flag / `search` parameter. */
+  readonly search?: StoryPackSearch;
+}
+
+/**
+ * An additional list-shaped verb: `<noun> <verb>` and `<noun>_<verb>`
+ * compiled through the SAME machinery as `list` (query, columns, filters,
+ * search) — e.g. standard's `categories`. The verb may not collide with
+ * the compiled `list`/`lookup`/`sample` verbs.
+ */
+export interface StoryPackVerb extends StoryPackList {
+  /** Verb name (kebab-case), e.g. `"categories"`. */
+  readonly verb: string;
+  /** CLI description for the command. */
+  readonly description?: string;
+  /** MCP tool description (defaults to the CLI description). */
+  readonly toolDescription?: string;
+}
+
+/**
+ * The sample capability: `<noun> sample [count]` and `<noun>_sample`
+ * return 1–5 randomly selected complete entities (resolved through the
+ * lookup path at the HIGHEST disclosure level) so agents can learn the
+ * data shape before querying.
+ */
+export interface StoryPackSample {
+  /** Default sample count when none is requested (1–5; default 2). */
+  readonly count?: number;
+  /** CLI description for the command. */
+  readonly description?: string;
+  /** MCP tool description (defaults to the CLI description). */
+  readonly toolDescription?: string;
 }
 
 /**
@@ -78,10 +186,20 @@ export interface StoryPackLookup {
   readonly by: string;
   /** Optional class constraint — prefixed name or IRI. */
   readonly type?: string;
+  /** CLI description for the lookup command (defaults to a generated one). */
+  readonly description?: string;
+  /** MCP tool description (defaults to a generated one). */
+  readonly toolDescription?: string;
   /** Inline fields shown under the entity title. */
   readonly fields?: readonly StoryPackField[];
   /** Long-form sections shown after the fields. */
   readonly sections?: readonly StoryPackSection[];
+  /** Multi-valued nested projections (pack v1 structured sections). */
+  readonly expand?: readonly StoryPackExpand[];
+  /** Progressive-disclosure levels; enables the derived `--detail` flag. */
+  readonly disclosure?: StoryPackDisclosure;
+  /** Sample capability: `true` for defaults, or a configured sample. */
+  readonly sample?: true | StoryPackSample;
 }
 
 /** One declarative read story: a noun with its preferred queries. */
@@ -93,6 +211,8 @@ export interface StoryPackDefinition {
   /** MCP tool description (defaults to the CLI description). */
   readonly toolDescription?: string;
   readonly list: StoryPackList;
+  /** Additional list-shaped verbs beyond `list` (e.g. `categories`). */
+  readonly verbs?: readonly StoryPackVerb[];
   readonly lookup?: StoryPackLookup;
 }
 

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

@@ -237,4 +237,506 @@ describe("validateStoryPackDefinition — list filters", () => {
       ),
     ).toThrow(/values/);
   });
+
+  it("accepts a value-free filter (data-driven value set)", () => {
+    const validated = validateStoryPackDefinition(
+      withFilters([{ param: "category", variable: "category" }]),
+      "test",
+    );
+    expect(validated.list.filters?.at(0)).toEqual({
+      param: "category",
+      variable: "category",
+    });
+  });
+
+  it("rejects the compiled search parameter name", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withFilters([{ param: "search", variable: "category", values: ["x"] }]),
+        "test",
+      ),
+    ).toThrow(/reserved/);
+  });
+
+  it("rejects the derived detail parameter name", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withFilters([{ param: "detail", variable: "category", values: ["x"] }]),
+        "test",
+      ),
+    ).toThrow(/reserved/);
+  });
+
+  /** RECIPE_STORY with the given `list.search`. */
+  function withSearch(search: unknown): unknown {
+    const list = { ...(base.list as Record<string, unknown>), search };
+    return { ...base, list };
+  }
+
+  it("accepts a search over variables the query mentions", () => {
+    const validated = validateStoryPackDefinition(
+      withSearch({ variables: ["name", "category"] }),
+      "test",
+    );
+    expect(validated.list.search?.variables).toEqual(["name", "category"]);
+  });
+
+  it("rejects a search without variables", () => {
+    expect(() =>
+      validateStoryPackDefinition(withSearch({ variables: [] }), "test"),
+    ).toThrow(/search.variables/);
+  });
+
+  it("rejects a search variable the query never mentions", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withSearch({ variables: ["season"] }),
+        "test",
+      ),
+    ).toThrow(/does not appear in "list.query"/);
+  });
+
+  /** RECIPE_STORY with the given `lookup.expand`, for expand validation. */
+  function withExpand(expand: unknown): unknown {
+    return {
+      ...RECIPE_STORY,
+      lookup: { ...RECIPE_STORY.lookup, expand },
+    };
+  }
+
+  it("accepts a valid expand", () => {
+    const validated = validateStoryPackDefinition(
+      withExpand([
+        {
+          name: "ingredients",
+          heading: "Ingredients",
+          kind: "table",
+          relation: "ex:ingredient",
+          select: [{ name: "label", property: "ex:label" }],
+        },
+      ]),
+      "test",
+    );
+    expect(validated.lookup?.expand?.[0]?.name).toBe("ingredients");
+  });
+
+  it("rejects an expand with an empty select", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withExpand([
+          { name: "ingredients", relation: "ex:ingredient", select: [] },
+        ]),
+        "test",
+      ),
+    ).toThrow(/select/);
+  });
+
+  it("rejects an expand kind other than list or table", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withExpand([
+          {
+            name: "ingredients",
+            relation: "ex:ingredient",
+            kind: "tree",
+            select: [{ name: "label", property: "ex:label" }],
+          },
+        ]),
+        "test",
+      ),
+    ).toThrow(/must be "list" or "table"/);
+  });
+
+  it("rejects duplicate expand names", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withExpand([
+          {
+            name: "dup",
+            relation: "ex:a",
+            select: [{ name: "x", property: "ex:x" }],
+          },
+          {
+            name: "dup",
+            relation: "ex:b",
+            select: [{ name: "y", property: "ex:y" }],
+          },
+        ]),
+        "test",
+      ),
+    ).toThrow(/duplicate expand name/);
+  });
+
+  /** RECIPE_STORY with the given `lookup` extras merged in. */
+  function withLookupExtras(extras: Record<string, unknown>): unknown {
+    return {
+      ...RECIPE_STORY,
+      lookup: { ...RECIPE_STORY.lookup, ...extras },
+    };
+  }
+
+  it("accepts a valid disclosure with a level-gated expand", () => {
+    const validated = validateStoryPackDefinition(
+      withLookupExtras({
+        disclosure: { levels: ["summary", "detailed"], default: "summary" },
+        expand: [
+          {
+            name: "ingredients",
+            relation: "ex:ingredient",
+            select: [{ name: "label", property: "ex:label" }],
+            level: "detailed",
+          },
+        ],
+      }),
+      "test",
+    );
+    expect(validated.lookup?.disclosure?.levels).toEqual([
+      "summary",
+      "detailed",
+    ]);
+  });
+
+  it("rejects empty disclosure levels", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withLookupExtras({ disclosure: { levels: [] } }),
+        "test",
+      ),
+    ).toThrow(/non-empty array/);
+  });
+
+  it("rejects a disclosure default not among the levels", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withLookupExtras({
+          disclosure: { levels: ["summary"], default: "detailed" },
+        }),
+        "test",
+      ),
+    ).toThrow(/default "detailed" is not one of/);
+  });
+
+  it("rejects a disclosure level named detail (derived param collision)", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withLookupExtras({ disclosure: { levels: ["summary", "detail"] } }),
+        "test",
+      ),
+    ).toThrow(/reserved/);
+  });
+
+  it("rejects a disclosure level colliding with a kernel param name", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withLookupExtras({ disclosure: { levels: ["summary", "names"] } }),
+        "test",
+      ),
+    ).toThrow(/reserved/);
+  });
+
+  it("rejects a disclosure level that is not a single lowercase word", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withLookupExtras({ disclosure: { levels: ["summary", "Fully-Deep"] } }),
+        "test",
+      ),
+    ).toThrow(/single lowercase word/);
+  });
+
+  it("accepts a disclosure level named detailed (the legacy alias)", () => {
+    const validated = validateStoryPackDefinition(
+      withLookupExtras({ disclosure: { levels: ["summary", "detailed"] } }),
+      "test",
+    );
+    expect(validated.lookup?.disclosure?.levels).toEqual([
+      "summary",
+      "detailed",
+    ]);
+  });
+
+  it("rejects an expand level that is not a declared disclosure level", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withLookupExtras({
+          disclosure: { levels: ["summary"] },
+          expand: [
+            {
+              name: "ingredients",
+              relation: "ex:ingredient",
+              select: [{ name: "label", property: "ex:label" }],
+              level: "detailed",
+            },
+          ],
+        }),
+        "test",
+      ),
+    ).toThrow(/is not a declared disclosure level/);
+  });
+});
+
+describe("validateStoryPackDefinition — identifier hardening", () => {
+  const base = JSON.parse(JSON.stringify(RECIPE_STORY)) as Record<
+    string,
+    unknown
+  >;
+
+  it("rejects a column field the query never mentions", () => {
+    const list = {
+      ...(base.list as Record<string, unknown>),
+      columns: [{ field: "name" }, { field: "season" }],
+    };
+    expect(() =>
+      validateStoryPackDefinition({ ...base, list }, "test"),
+    ).toThrow(/column field "\?season" does not appear in "list.query"/);
+  });
+
+  it("validates verb columns against the verb query", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        {
+          ...RECIPE_STORY,
+          verbs: [
+            {
+              verb: "categories",
+              query: "SELECT ?name WHERE { ?uri ex:category ?name }",
+              columns: [{ field: "count" }],
+            },
+          ],
+        },
+        "test",
+      ),
+    ).toThrow(/column field "\?count" does not appear in "verbs\[0\].query"/);
+  });
+
+  it("accepts a column bound via AS in the SELECT projection", () => {
+    const validated = validateStoryPackDefinition(
+      {
+        ...RECIPE_STORY,
+        verbs: [
+          {
+            verb: "categories",
+            query:
+              "SELECT ?name (COUNT(?uri) AS ?count) WHERE { ?uri ex:category ?name } GROUP BY ?name",
+            columns: [{ field: "name" }, { field: "count" }],
+          },
+        ],
+      },
+      "test",
+    );
+    expect(validated.verbs?.at(0)?.columns).toHaveLength(2);
+  });
+
+  // Reserved object-prototype keys: pack identifiers become plain-object
+  // keys at run time, so __proto__/constructor/prototype must fail at boot.
+  it("rejects a reserved object key as a column field", () => {
+    const list = {
+      ...(base.list as Record<string, unknown>),
+      query: "SELECT ?__proto__ WHERE { ?uri ex:name ?__proto__ }",
+      columns: [{ field: "__proto__" }],
+      filters: undefined,
+    };
+    expect(() =>
+      validateStoryPackDefinition({ ...base, list }, "test"),
+    ).toThrow(/reserved object key "__proto__"/);
+  });
+
+  it("rejects a reserved object key as a filter param or variable", () => {
+    const withFilter = (filter: Record<string, unknown>): unknown => ({
+      ...base,
+      list: {
+        ...(base.list as Record<string, unknown>),
+        query:
+          "SELECT ?uri ?name ?category ?constructor WHERE { ?uri ex:name ?name ; ex:category ?category ; ex:kind ?constructor }",
+        filters: [filter],
+      },
+    });
+    expect(() =>
+      validateStoryPackDefinition(
+        withFilter({ param: "constructor", variable: "category" }),
+        "test",
+      ),
+    ).toThrow(/reserved object key "constructor"/);
+    expect(() =>
+      validateStoryPackDefinition(
+        withFilter({ param: "kind", variable: "constructor" }),
+        "test",
+      ),
+    ).toThrow(/reserved object key "constructor"/);
+  });
+
+  it("rejects a reserved object key as a search variable", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        {
+          ...base,
+          list: {
+            ...(base.list as Record<string, unknown>),
+            query:
+              "SELECT ?uri ?name ?category ?prototype WHERE { ?uri ex:name ?name ; ex:category ?category ; ex:proto ?prototype }",
+            search: { variables: ["prototype"] },
+          },
+        },
+        "test",
+      ),
+    ).toThrow(/reserved object key "prototype"/);
+  });
+
+  it("rejects a reserved object key as a lookup field or expand name", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        {
+          ...RECIPE_STORY,
+          lookup: {
+            ...RECIPE_STORY.lookup,
+            fields: [{ name: "__proto__", property: "ex:category" }],
+          },
+        },
+        "test",
+      ),
+    ).toThrow(/reserved object key "__proto__"/);
+    expect(() =>
+      validateStoryPackDefinition(
+        {
+          ...RECIPE_STORY,
+          lookup: {
+            ...RECIPE_STORY.lookup,
+            expand: [
+              {
+                name: "__proto__",
+                relation: "ex:ingredient",
+                select: [{ name: "label", property: "ex:label" }],
+              },
+            ],
+          },
+        },
+        "test",
+      ),
+    ).toThrow(/reserved object key "__proto__"/);
+  });
+
+  it("rejects a reserved object key inside an expand select", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        {
+          ...RECIPE_STORY,
+          lookup: {
+            ...RECIPE_STORY.lookup,
+            expand: [
+              {
+                name: "ingredients",
+                relation: "ex:ingredient",
+                select: [{ name: "constructor", property: "ex:label" }],
+              },
+            ],
+          },
+        },
+        "test",
+      ),
+    ).toThrow(/reserved object key "constructor"/);
+  });
+
+  it("rejects a reserved object key as a disclosure level", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        {
+          ...RECIPE_STORY,
+          lookup: {
+            ...RECIPE_STORY.lookup,
+            disclosure: { levels: ["summary", "prototype"] },
+          },
+        },
+        "test",
+      ),
+    ).toThrow(/reserved object key "prototype"/);
+  });
+});
+
+// Pack v1: extra list verbs and the sample capability.
+describe("validateStoryPackDefinition — verbs and sample", () => {
+  const VERB = {
+    verb: "categories",
+    query: "SELECT ?name WHERE { ?uri ex:category ?name }",
+    columns: [{ field: "name" }],
+  };
+
+  function withVerbs(verbs: unknown): unknown {
+    return { ...RECIPE_STORY, verbs };
+  }
+
+  it("accepts a valid extra verb and validates its list shape", () => {
+    const validated = validateStoryPackDefinition(withVerbs([VERB]), "test");
+    expect(validated.verbs?.at(0)?.verb).toBe("categories");
+    expect(validated.verbs?.at(0)?.columns).toEqual([{ field: "name" }]);
+  });
+
+  it("rejects a verb colliding with a compiled verb", () => {
+    for (const verb of ["list", "lookup", "sample"]) {
+      expect(() =>
+        validateStoryPackDefinition(withVerbs([{ ...VERB, verb }]), "test"),
+      ).toThrow(/collides with a compiled verb/);
+    }
+  });
+
+  it("rejects duplicate verbs", () => {
+    expect(() =>
+      validateStoryPackDefinition(withVerbs([VERB, VERB]), "test"),
+    ).toThrow(/duplicate verb/);
+  });
+
+  it("rejects a non-kebab verb", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withVerbs([{ ...VERB, verb: "Cats" }]),
+        "test",
+      ),
+    ).toThrow(/kebab-case/);
+  });
+
+  it("rejects a verb whose query is not a SELECT", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withVerbs([{ ...VERB, query: "ASK { ?s ?p ?o }" }]),
+        "test",
+      ),
+    ).toThrow(/verbs\[0\].query/);
+  });
+
+  it("validates verb filters against the verb query", () => {
+    expect(() =>
+      validateStoryPackDefinition(
+        withVerbs([
+          {
+            ...VERB,
+            filters: [{ param: "season", variable: "season", values: ["x"] }],
+          },
+        ]),
+        "test",
+      ),
+    ).toThrow(/does not appear in "verbs\[0\].query"/);
+  });
+
+  function withSample(sample: unknown): unknown {
+    return { ...RECIPE_STORY, lookup: { ...RECIPE_STORY.lookup, sample } };
+  }
+
+  it("accepts sample: true", () => {
+    const validated = validateStoryPackDefinition(withSample(true), "test");
+    expect(validated.lookup?.sample).toBe(true);
+  });
+
+  it("accepts a configured sample with a valid default count", () => {
+    const validated = validateStoryPackDefinition(
+      withSample({ count: 3 }),
+      "test",
+    );
+    expect(validated.lookup?.sample).toEqual({ count: 3 });
+  });
+
+  it("rejects an out-of-range or non-integer sample count", () => {
+    for (const count of [0, 6, 2.5, "2"]) {
+      expect(() =>
+        validateStoryPackDefinition(withSample({ count }), "test"),
+      ).toThrow(/sample.count/);
+    }
+  });
 });