@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/kernel/packs/schema.ts

@@ -0,0 +1,328 @@
+/**
+ * The zod pack-definition validator — the single gate for DYNAMIC (config- and
+ * package-declared) packs and the parity round-trip tests. It replaces the old
+ * ~1,000-line hand validator with a schema plus a handful of cross-field
+ * refinements that encode the source rule (§3): `type` XOR `types`, a
+ * graphql-sourced lookup names its fragment target, SPARQL expands stay
+ * single-hop, GraphQL fields reject property paths, and every disclosure `level`
+ * names a declared canonical level.
+ *
+ * zod lives here and ONLY here in the pack layer, imported lazily (never on the
+ * `--help`/`__complete` fast path). Bundled packs are authored in-repo and typed
+ * by TypeScript, so `collect` skips validation for them (per-source skip); this
+ * runs for config/package packs and in tests.
+ */
+
+import { z } from "zod";
+import { DETAIL_LEVELS } from "../../constants.js";
+import { PragmaError } from "../error/PragmaError.js";
+import type { PackDefinition } from "./types.js";
+
+const NOUN_PATTERN = /^[a-z][a-z0-9-]*$/;
+const FILTER_PARAM_PATTERN = /^[a-z][a-z0-9]*$/;
+const FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const GRAPHQL_NAME_PATTERN = /^[_A-Za-z][_0-9A-Za-z]*$/;
+/** A prefixed name (`ds:Thing`), a property path of them, or an absolute IRI. */
+const TERM_PATTERN =
+  /^(?:[A-Za-z][A-Za-z0-9+.-]*:\/\/[^<>"\s]+|[A-Za-z][\w-]*:[^/<>"\s]+(?:\/[A-Za-z][\w-]*:[^/<>"\s]+)*)$/;
+
+/** Params a filter/verb may not claim (they are the shared read vocabulary). */
+const RESERVED_PARAMS = new Set(["search", "detail", "name", "count"]);
+
+const term = z.string().regex(TERM_PATTERN, "must be a prefixed name or IRI");
+const graphqlName = z.string().regex(GRAPHQL_NAME_PATTERN);
+const fieldName = z.string().regex(FIELD_PATTERN);
+
+const columnSchema = z
+  .object({ field: fieldName, label: z.string().optional() })
+  .strict();
+
+const filterSchema = z
+  .object({
+    param: z.string().regex(FILTER_PARAM_PATTERN),
+    variable: fieldName,
+    values: z.array(z.string()).min(1).optional(),
+    description: z.string().optional(),
+  })
+  .strict()
+  .refine((f) => !RESERVED_PARAMS.has(f.param), {
+    message: "filter param is a reserved name",
+  });
+
+const searchSchema = z
+  .object({
+    variables: z.array(fieldName).min(1),
+    description: z.string().optional(),
+  })
+  .strict();
+
+const emptyRecoverySchema = z
+  .object({
+    message: z.string().min(1),
+    cli: z
+      .string()
+      .startsWith("pragma ", 'emptyRecovery.cli must be a "pragma " command')
+      .optional(),
+  })
+  .strict();
+
+const listShape = {
+  query: z.string().min(1),
+  columns: z.array(columnSchema).min(1),
+  filters: z.array(filterSchema).min(1).optional(),
+  search: searchSchema.optional(),
+  emptyRecovery: emptyRecoverySchema.optional(),
+};
+
+const listSchema = z.object(listShape).strict();
+const verbSchema = z
+  .object({
+    ...listShape,
+    verb: z.string().regex(NOUN_PATTERN),
+    description: z.string().optional(),
+    toolDescription: z.string().optional(),
+  })
+  .strict();
+
+const fieldSchema = z
+  .object({
+    name: fieldName,
+    property: term,
+    label: z.string().optional(),
+    graphqlField: graphqlName.optional(),
+    level: z.string().optional(),
+  })
+  .strict();
+
+const sectionSchema = fieldSchema.extend({
+  kind: z.enum(["field", "code"]).optional(),
+});
+
+const nestedExpandSchema = z
+  .object({
+    name: fieldName,
+    relation: term,
+    graphqlField: graphqlName.optional(),
+    select: z
+      .array(
+        z
+          .object({
+            name: fieldName,
+            property: term,
+            label: z.string().optional(),
+            graphqlField: graphqlName.optional(),
+          })
+          .strict(),
+      )
+      .min(1),
+  })
+  .strict();
+
+const expandFieldSchema = z
+  .object({
+    name: fieldName,
+    property: term,
+    label: z.string().optional(),
+    graphqlField: graphqlName.optional(),
+  })
+  .strict();
+
+const expandSchema = z
+  .object({
+    name: fieldName,
+    heading: z.string().optional(),
+    kind: z.enum(["list", "table"]).optional(),
+    relation: term,
+    graphqlField: graphqlName.optional(),
+    select: z.array(z.union([nestedExpandSchema, expandFieldSchema])).min(1),
+    showWhenEmpty: z.boolean().optional(),
+    level: z.string().optional(),
+  })
+  .strict();
+
+const disclosureSchema = z
+  .object({
+    levels: z.array(z.enum(DETAIL_LEVELS)).min(1),
+    default: z.enum(DETAIL_LEVELS).optional(),
+  })
+  .strict()
+  .superRefine((disclosure, ctx) => {
+    // `default` must name a DECLARED level, not merely a canonical one — else the
+    // injected MCP `detail` enum offers only the declared levels while the
+    // advertised/resolved default is unselectable (compounds the divergence
+    // resolvePackDetail guards at runtime).
+    if (
+      disclosure.default !== undefined &&
+      !disclosure.levels.includes(disclosure.default)
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `disclosure default "${disclosure.default}" is not one of the declared levels [${disclosure.levels.join(", ")}].`,
+        path: ["default"],
+      });
+    }
+  });
+
+const sampleSchema = z.union([
+  z.literal(true),
+  z
+    .object({
+      count: z.number().int().min(1).max(5).optional(),
+      description: z.string().optional(),
+      toolDescription: z.string().optional(),
+    })
+    .strict(),
+]);
+
+const completionSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    match: z.enum(["prefix", "substring", "fuzzy"]).optional(),
+    minChars: z.number().int().min(0).optional(),
+  })
+  .strict();
+
+const lookupSchema = z
+  .object({
+    source: z.enum(["sparql", "graphql"]).optional(),
+    by: term,
+    type: term.optional(),
+    description: z.string().optional(),
+    toolDescription: z.string().optional(),
+    types: z.array(term).min(1).optional(),
+    graphqlType: graphqlName.optional(),
+    fields: z.array(fieldSchema).min(1).optional(),
+    sections: z.array(sectionSchema).min(1).optional(),
+    expand: z.array(expandSchema).min(1).optional(),
+    disclosure: disclosureSchema.optional(),
+    sample: sampleSchema.optional(),
+    completion: completionSchema.optional(),
+  })
+  .strict();
+
+const definitionSchema = z
+  .object({
+    noun: z.string().regex(NOUN_PATTERN),
+    description: z.string().optional(),
+    toolDescription: z.string().optional(),
+    list: listSchema.optional(),
+    verbs: z.array(verbSchema).min(1).optional(),
+    lookup: lookupSchema.optional(),
+    colophon: z.string().optional(),
+  })
+  .strict()
+  .superRefine((def, ctx) => {
+    if (!def.list && !def.lookup) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'a pack must declare at least one of "list" or "lookup".',
+      });
+    }
+    if (
+      def.list &&
+      !/^\s*(?:PREFIX\s+[^\n]*\n\s*)*SELECT\s/i.test(def.list.query)
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: '"list.query" must be a SPARQL SELECT query.',
+        path: ["list", "query"],
+      });
+    }
+    if (def.lookup) refineLookup(def.lookup, ctx);
+  });
+
+/** Cross-field lookup rules — the source rule (§3, F8). */
+function refineLookup(
+  lookup: z.infer<typeof lookupSchema>,
+  ctx: z.RefinementCtx,
+): void {
+  const source = lookup.source ?? "sparql";
+
+  if (lookup.type !== undefined && lookup.types !== undefined) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: '"lookup.type" and "lookup.types" are mutually exclusive.',
+      path: ["lookup"],
+    });
+  }
+
+  if (source === "graphql" && !lookup.graphqlType && !lookup.type) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message:
+        '"lookup.source" "graphql" requires "lookup.graphqlType" (or a single "lookup.type" to derive it).',
+      path: ["lookup"],
+    });
+  }
+
+  const allValues = [...(lookup.fields ?? []), ...(lookup.sections ?? [])];
+  const declared = new Set<string>(lookup.disclosure?.levels ?? []);
+
+  for (const value of allValues) {
+    if (value.level !== undefined && !declared.has(value.level)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `field "${value.name}" level "${value.level}" is not a declared disclosure level.`,
+        path: ["lookup"],
+      });
+    }
+    if (
+      source === "graphql" &&
+      isPropertyPath(value.property) &&
+      !value.graphqlField
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `field "${value.name}" uses a property path, which the GraphQL source cannot express — set "graphqlField" or use source "sparql".`,
+        path: ["lookup"],
+      });
+    }
+  }
+
+  for (const expand of lookup.expand ?? []) {
+    if (expand.level !== undefined && !declared.has(expand.level)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `expand "${expand.name}" level "${expand.level}" is not a declared disclosure level.`,
+        path: ["lookup"],
+      });
+    }
+    for (const entry of expand.select) {
+      if ("relation" in entry && source !== "graphql") {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `expand "${expand.name}" nests a relation, which requires lookup.source "graphql" (the SPARQL expand sub-SELECT is single-hop).`,
+          path: ["lookup"],
+        });
+      }
+    }
+  }
+}
+
+/** A term with a `/` join of prefixed names (never an absolute IRI). */
+function isPropertyPath(term: string): boolean {
+  return term.includes("/") && !term.includes("://");
+}
+
+/**
+ * Validate a raw pack definition, throwing a config error on the first issue.
+ *
+ * @param raw - The untrusted definition (config/package JSON, or a test input).
+ * @param source - Where it came from, for error attribution.
+ * @returns The validated definition (shape-preserving — no injected defaults).
+ * @throws PragmaError CONFIG_ERROR describing the first violation.
+ */
+export function parsePackDefinition(
+  raw: unknown,
+  source: string,
+): PackDefinition {
+  const result = definitionSchema.safeParse(raw);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    const path = issue?.path.join(".") ?? "<root>";
+    throw PragmaError.configError(
+      `Invalid story in ${source} at ${path}: ${issue?.message ?? "unknown error"}`,
+    );
+  }
+  return result.data as PackDefinition;
+}

package/src/kernel/packs/sparql/applyFilters.ts

@@ -0,0 +1,83 @@
+/**
+ * Apply declared pack filters to resolved list rows.
+ *
+ * Filters are row predicates on projected SELECT variables — the author query is
+ * never modified, so user input cannot inject SPARQL and the query's ordering is
+ * preserved. With declared `values` the input is canonicalized against the set
+ * (NFC, case-insensitive) and rows are matched case-insensitively; without them
+ * the input is a free term matched the same way. A row lacking the variable never
+ * matches. Several filters combine conjunctively.
+ */
+
+import { PragmaError } from "../../error/PragmaError.js";
+import type { PackFilter, PackRow } from "../types.js";
+
+/**
+ * @param rows - Rows produced by the pack's list query.
+ * @param filters - Declared filters (absent means no filtering).
+ * @param params - Story parameters as provided by the surface.
+ * @returns Rows matching every provided filter.
+ * @throws PragmaError INVALID_INPUT when a value is not in a filter's declared
+ *   set, or when a value-free filter receives a non-string value.
+ */
+export function applyPackFilters(
+  rows: PackRow[],
+  filters: readonly PackFilter[] | undefined,
+  params: Record<string, unknown>,
+): PackRow[] {
+  let result = rows;
+  for (const filter of filters ?? []) {
+    const provided = params[filter.param];
+    if (provided === undefined) continue;
+    const values = filter.values;
+    if (values === undefined) {
+      const term = requireStringValue(provided, filter).toLowerCase();
+      result = result.filter(
+        (row) => row[filter.variable]?.normalize("NFC").toLowerCase() === term,
+      );
+      continue;
+    }
+    const canonical = canonicalizeFilterValue(
+      provided,
+      filter,
+      values,
+    ).toLowerCase();
+    result = result.filter(
+      (row) =>
+        row[filter.variable]?.normalize("NFC").toLowerCase() === canonical,
+    );
+  }
+  return result;
+}
+
+/** @throws PragmaError INVALID_INPUT when a value-free filter value is not a string. */
+function requireStringValue(provided: unknown, filter: PackFilter): string {
+  if (typeof provided !== "string") {
+    throw PragmaError.invalidInput(filter.param, String(provided), {
+      recovery: { message: `Provide a string value for --${filter.param}.` },
+    });
+  }
+  return provided.trim().normalize("NFC");
+}
+
+/** @throws PragmaError INVALID_INPUT when the value is not in the declared set. */
+function canonicalizeFilterValue(
+  provided: unknown,
+  filter: PackFilter,
+  values: readonly string[],
+): string {
+  if (typeof provided === "string") {
+    const normalized = provided.trim().normalize("NFC");
+    const match = values.find(
+      (value) =>
+        value.normalize("NFC").toLowerCase() === normalized.toLowerCase(),
+    );
+    if (match !== undefined) return match.normalize("NFC");
+  }
+  throw PragmaError.invalidInput(filter.param, String(provided), {
+    validOptions: [...values],
+    recovery: {
+      message: `Allowed values for --${filter.param}: ${values.join(", ")}.`,
+    },
+  });
+}

package/src/kernel/packs/sparql/applySearch.ts

@@ -0,0 +1,33 @@
+/**
+ * Apply a pack list's free-text search to resolved rows.
+ *
+ * Like filters, search runs AFTER the author query, so user input never touches
+ * the query text (injection-safe) and the author's ORDER BY is preserved. The
+ * term is NFC-normalized and matched case-insensitively; a row passes when ANY
+ * declared variable contains it as a substring. A non-string or empty term is a
+ * no-op.
+ */
+
+import type { PackRow, PackSearch } from "../types.js";
+
+/**
+ * @param rows - Rows produced by the pack's list query (post-filter).
+ * @param search - The declared search (absent means no searching).
+ * @param params - Story parameters as provided by the surface.
+ * @returns Rows containing the term in at least one searched variable.
+ */
+export function applyPackSearch(
+  rows: PackRow[],
+  search: PackSearch | undefined,
+  params: Record<string, unknown>,
+): PackRow[] {
+  const provided = params.search;
+  if (search === undefined || typeof provided !== "string") return rows;
+  const term = provided.trim().normalize("NFC").toLowerCase();
+  if (term === "") return rows;
+  return rows.filter((row) =>
+    search.variables.some((variable) =>
+      row[variable]?.normalize("NFC").toLowerCase().includes(term),
+    ),
+  );
+}

package/src/kernel/packs/sparql/buildLookupQuery.ts

@@ -0,0 +1,180 @@
+/**
+ * Generated, injection-safe SPARQL lookup queries for a pack story.
+ *
+ * Pack authors declare *what* names an entity (`by`, optional `type`/`types`)
+ * and which properties to read; the query text is generated here so
+ * user-supplied names are always escaped SPARQL string literals, and level-gated
+ * fields below the active level are excluded from the projection (fetch-gating).
+ * Matching on the `by` property is exact and case-insensitive.
+ */
+
+import { activeExpands, activeFields } from "../disclosure.js";
+import type { PackExpand, PackLookup } from "../types.js";
+import { escapeSparqlString, formatTerm } from "./escape.js";
+
+/**
+ * The class-constraint clause for a lookup: a single `a` triple for `type`, a
+ * VALUES-constrained type triple for `types`, or nothing. All terms are
+ * validated pack terms, never user input.
+ */
+function buildTypeConstraint(lookup: PackLookup): string {
+  if (lookup.type) {
+    return `  ?uri a ${formatTerm(lookup.type)} .\n`;
+  }
+  if (lookup.types && lookup.types.length > 0) {
+    const values = lookup.types.map(formatTerm).join(" ");
+    return `  VALUES ?packType { ${values} }\n  ?uri a ?packType .\n`;
+  }
+  return "";
+}
+
+/**
+ * The gated projection shared by both lookup forms: the `?uri ?name <vars>`
+ * SELECT header, the class constraint, and the OPTIONAL field triples, all
+ * restricted to the fields active at `level`. The name- and IRI-addressed forms
+ * differ ONLY in how `?uri` is bound (a `FILTER` on the escaped name vs a `BIND`
+ * of the resolved IRI), so both thread the active level through here and gate
+ * identically — an IRI-addressed lookup honours `--detail` just like a name one.
+ */
+function lookupProjection(
+  lookup: PackLookup,
+  level: string | undefined,
+): { header: string; body: string } {
+  const fields = activeFields(lookup, level);
+  const vars = fields.map((field) => `?${field.name}`).join(" ");
+  const optionals = fields
+    .map(
+      (field) =>
+        `  OPTIONAL { ?uri ${formatTerm(field.property)} ?${field.name} . }`,
+    )
+    .join("\n");
+  return {
+    header: `SELECT ?uri ?name${vars.length > 0 ? ` ${vars}` : ""} WHERE {`,
+    body: buildTypeConstraint(lookup) + optionals,
+  };
+}
+
+/**
+ * Build the SELECT retrieving one named entity with its declared fields.
+ *
+ * @param lookup - The pack's lookup declaration.
+ * @param name - User-supplied entity name (escaped here).
+ * @param level - Active canonical level; gated fields below it are excluded.
+ * @returns SPARQL SELECT text.
+ */
+export function buildLookupQuery(
+  lookup: PackLookup,
+  name: string,
+  level?: string,
+): string {
+  const { header, body } = lookupProjection(lookup, level);
+  return [
+    header,
+    `  ?uri ${formatTerm(lookup.by)} ?name .`,
+    body,
+    `  FILTER (LCASE(STR(?name)) = LCASE("${escapeSparqlString(name)}"))`,
+    "}",
+    "LIMIT 1",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+/**
+ * Build the SELECT retrieving one entity addressed directly by IRI.
+ *
+ * Binds the already-resolved IRI to `?uri` instead of filtering on the `by`
+ * value; otherwise identical to the name form, including level-gating. Injection-
+ * safe by construction: the caller validates `iri` against the embeddable-IRI
+ * shape BEFORE it is interpolated here — raw user input never reaches this
+ * function.
+ *
+ * @param lookup - The pack's lookup declaration.
+ * @param iri - The already-resolved, embeddable entity IRI.
+ * @param level - Active canonical level; gated fields below it are excluded.
+ */
+export function buildLookupByIriQuery(
+  lookup: PackLookup,
+  iri: string,
+  level?: string,
+): string {
+  const { header, body } = lookupProjection(lookup, level);
+  return [
+    header,
+    `  BIND(<${iri}> AS ?uri)`,
+    `  ?uri ${formatTerm(lookup.by)} ?name .`,
+    body,
+    "}",
+    "LIMIT 1",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+/**
+ * Build the minimal name→URI resolve for a graphql-sourced lookup (and the
+ * shared entry point for the sparql path's name form): maps the user-supplied
+ * name to the entity IRI, everything else comes from the field fetch. The name
+ * is an escaped literal; all terms are validated pack terms.
+ */
+export function buildNameResolveQuery(
+  lookup: PackLookup,
+  name: string,
+): string {
+  return [
+    "SELECT ?uri ?name WHERE {",
+    `  ?uri ${formatTerm(lookup.by)} ?name .`,
+    buildTypeConstraint(lookup).trimEnd(),
+    `  FILTER (LCASE(STR(?name)) = LCASE("${escapeSparqlString(name)}"))`,
+    "}",
+    // Names can recur across tiers; LIMIT 1 takes the store's first match.
+    "LIMIT 1",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+/**
+ * Build the sub-SELECT retrieving one expand's child rows for a resolved entity.
+ *
+ * Injection-safe: the only interpolated value is `entityUri`, the IRI the base
+ * lookup already resolved from the store (never user input); the
+ * relation/properties are validated pack terms. SPARQL expands are single-hop,
+ * so every select entry here is a plain field.
+ */
+export function buildExpandQuery(
+  expand: PackExpand,
+  entityUri: string,
+): string {
+  const vars = expand.select.map((field) => `?${field.name}`).join(" ");
+  const optionals = expand.select
+    .map((field) =>
+      "property" in field
+        ? `  OPTIONAL { ?child ${formatTerm(field.property)} ?${field.name} . }`
+        : "",
+    )
+    .filter((line) => line !== "")
+    .join("\n");
+  return [
+    `SELECT ${vars} WHERE {`,
+    `  <${entityUri}> ${formatTerm(expand.relation)} ?child .`,
+    optionals,
+    "}",
+  ].join("\n");
+}
+
+/** Build the SELECT listing all entity names — lookup-miss suggestions. */
+export function buildLookupNamesQuery(lookup: PackLookup): string {
+  return [
+    "SELECT ?name WHERE {",
+    `  ?uri ${formatTerm(lookup.by)} ?name .`,
+    buildTypeConstraint(lookup).trimEnd(),
+    "}",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+export type { PackExpand };
+/** Re-export the active-value helpers the GraphQL document generator shares. */
+export { activeExpands, activeFields };

package/src/kernel/packs/sparql/escape.ts

@@ -0,0 +1,22 @@
+/**
+ * SPARQL literal/term escaping for generated pack queries.
+ *
+ * Pack authors declare RDF terms (prefixed names or IRIs); users supply entity
+ * names. The generators here escape user names as SPARQL string literals and
+ * render validated terms as query tokens, so a pack definition never
+ * interpolates raw user input into query text.
+ */
+
+/** Escape a user-supplied value as a SPARQL string-literal body. */
+export function escapeSparqlString(value: string): string {
+  return value
+    .replaceAll("\\", "\\\\")
+    .replaceAll('"', '\\"')
+    .replaceAll("\n", "\\n")
+    .replaceAll("\r", "\\r");
+}
+
+/** Render a validated term (prefixed name or absolute IRI) as a query token. */
+export function formatTerm(term: string): string {
+  return term.includes("://") ? `<${term}>` : term;
+}