@canonical/pragma-cli 0.30.0 → 0.32.0

package/src/capabilities/info/types.ts

@@ -0,0 +1,42 @@
+/**
+ * Data shapes for `pragma info`.
+ */
+
+import type { ConfigOrigins } from "../../kernel/config/types.js";
+
+/** The config summary `info` reports — resolved values plus provenance. */
+export interface InfoConfig {
+  readonly tier?: string;
+  readonly channel: string;
+  readonly detail?: string;
+  readonly origins: ConfigOrigins;
+  readonly projectConfigPath?: string;
+  readonly globalConfigPath: string;
+  readonly projectExists: boolean;
+  readonly globalExists: boolean;
+}
+
+/** An available CLI update — present only when a newer release is published. */
+export interface InfoUpdate {
+  readonly current: string;
+  readonly latest: string;
+  /** The package-manager command that would apply the update. */
+  readonly command: string;
+}
+
+/**
+ * The full `info` payload. Storeless (never boots the store) but network-aware
+ * (PR6): an update-check and a storeless entity total enrich PR1's version +
+ * install-source + resolved config with per-field provenance.
+ */
+export interface InfoData {
+  readonly version: string;
+  readonly installSource: string;
+  /** Set when a newer CLI release is available on the active channel. */
+  readonly update?: InfoUpdate;
+  /** True when the registry could not be reached (the update-check was skipped). */
+  readonly updateSkipped: boolean;
+  /** Total indexed entities from the storeless pack index, when reachable. */
+  readonly entities?: number;
+  readonly config: InfoConfig;
+}

package/src/capabilities/lazy.test.ts

@@ -0,0 +1,89 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Walk the *static* import graph from an entry file, following relative
+ * `... from "./x.js"` and bare `import "./x.js"` specifiers (mapping `.js` back
+ * to `.ts`). Dynamic `import("./x.js")` calls use no `from`, so they are not
+ * followed — which is exactly the boundary the lazy-dispatch invariant relies
+ * on. This is the module-graph probe the brief calls for.
+ */
+function staticImportGraph(
+  entry: string,
+  seen = new Set<string>(),
+): Set<string> {
+  if (seen.has(entry) || !existsSync(entry)) return seen;
+  seen.add(entry);
+  const source = readFileSync(entry, "utf-8");
+  const fromRe = /\bfrom\s*["']([^"']+)["']/g;
+  const bareRe = /(?:^|\n)\s*import\s+["']([^"']+)["']/g;
+  for (const match of [
+    ...source.matchAll(fromRe),
+    ...source.matchAll(bareRe),
+  ]) {
+    const spec = match[1];
+    if (!spec?.startsWith(".")) continue;
+    staticImportGraph(
+      resolve(dirname(entry), spec.replace(/\.js$/, ".ts")),
+      seen,
+    );
+  }
+  return seen;
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+const has = (graph: Set<string>, suffix: string): boolean =>
+  [...graph].some((file) => file.endsWith(suffix));
+
+describe("lazy dispatch — module-graph probe (PROTECTED)", () => {
+  it("importing capabilities/index pulls no verb run body or config reader", () => {
+    const graph = staticImportGraph(resolve(here, "index.ts"));
+
+    // Spec + formatter modules are statically reachable...
+    expect(has(graph, "info/info.render.ts")).toBe(true);
+    expect(has(graph, "config/show.render.ts")).toBe(true);
+
+    // ...but run bodies and the config reader are only dynamic-imported.
+    expect(has(graph, "info/collectInfo.ts")).toBe(false);
+    expect(has(graph, "config/collectConfigShow.ts")).toBe(false);
+    expect(has(graph, "kernel/config/readConfig.ts")).toBe(false);
+  });
+
+  it("the help path (buildProgram) imports no zod schema module", () => {
+    const graph = staticImportGraph(
+      resolve(here, "../kernel/project/cli/buildProgram.ts"),
+    );
+    expect(has(graph, "kernel/config/schema.ts")).toBe(false);
+    expect(has(graph, "kernel/spec/validate.ts")).toBe(false);
+  });
+
+  // The store code (ke / ke-graphql / oxigraph) AND @canonical/harnesses (the
+  // harness detector doctor/setup reach only behind a dynamic import) must be
+  // dynamic-import-only: no file statically reachable from capabilities/index
+  // may `import … from` any of them, so building the command tree — or the
+  // __complete fast path — never loads the WASM runtime or the harness scan.
+  // Dynamic `import("…")` (used by the lazy store + setup ops) has no `from`,
+  // so it is allowed.
+  it("capabilities/index pulls no ke/ke-graphql/oxigraph/harnesses into the static graph (PROTECTED)", () => {
+    const heavy = [
+      "@canonical/ke",
+      "@canonical/ke-graphql",
+      "oxigraph",
+      "@canonical/harnesses",
+    ];
+    const graph = staticImportGraph(resolve(here, "index.ts"));
+    for (const file of graph) {
+      const source = readFileSync(file, "utf-8");
+      for (const pkg of heavy) {
+        const escaped = pkg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const staticImport = new RegExp(`from\\s*["']${escaped}["']`);
+        expect(
+          staticImport.test(source),
+          `${file} statically imports ${pkg}`,
+        ).toBe(false);
+      }
+    }
+  });
+});

package/src/capabilities/meta/complete.verb.ts

@@ -0,0 +1,52 @@
+/**
+ * The hidden `__complete` verb — the dynamic shell-completion resolver.
+ *
+ * Declared as a verb so the grammar is the single registry (every command is a
+ * verb, even internal ones), but `hidden` so it never shows in help or the
+ * surface, and withheld from MCP with a reason. The bin fast-paths `__complete`
+ * for latency; this spec's lazy `run` is the same resolution — the full
+ * completion engine, fed by the active pack's index through
+ * `indexCompletionEnv(runtime.cwd)` — reachable if a future tier dispatches it.
+ * Storeless: the entity tier reads the index off disk, never booting the store.
+ */
+
+import type { VerbSpec } from "../../kernel/spec/types.js";
+
+/** The `__complete` verb spec. */
+export const completeVerb: VerbSpec<Record<string, unknown>, string[]> = {
+  path: ["__complete"],
+  summary: "Resolve shell completions for the given words.",
+  hidden: true,
+  params: [
+    {
+      kind: "string[]",
+      name: "words",
+      doc: "The command words typed so far (last is the partial).",
+      positional: true,
+    },
+  ],
+  output: {
+    formatters: {
+      plain: (matches) => matches.join("\n"),
+      llm: (matches) => matches.join("\n"),
+      json: (matches) => JSON.stringify(matches),
+    },
+  },
+  capability: {
+    needsStore: false,
+    mutates: false,
+    mcp: { expose: false, reason: "internal shell-completion resolver" },
+  },
+  run: (params, runtime) =>
+    Promise.all([
+      import("../../kernel/completion/complete.js"),
+      import("../../kernel/completion/entitySource.js"),
+      import("../index.js"),
+    ]).then(([completion, entitySource, caps]) =>
+      completion.runComplete(
+        (params.words as string[] | undefined) ?? [],
+        caps.capabilities,
+        entitySource.indexCompletionEnv(runtime.cwd),
+      ),
+    ),
+};

package/src/capabilities/meta/index.ts

@@ -0,0 +1,15 @@
+/**
+ * The `meta` capability barrel — the hidden internal verbs (`__complete`,
+ * `mcp`). Both are withheld from the surface and MCP; the bin fast-paths them.
+ */
+
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { completeVerb } from "./complete.verb.js";
+import { mcpVerb } from "./mcp.verb.js";
+
+/** The `meta` capability module. */
+export const metaModule: CapabilityModule = {
+  name: "meta",
+  verbs: [asVerb(completeVerb), asVerb(mcpVerb)],
+};

package/src/capabilities/meta/mcp.verb.ts

@@ -0,0 +1,35 @@
+/**
+ * The hidden `mcp` verb — the MCP server entry point.
+ *
+ * The server is not an agent tool, so it is withheld from MCP with a reason and
+ * `hidden` from the CLI surface/help. The bin special-cases `pragma mcp` to
+ * serve over stdio (D9); this spec's lazy `run` is the same serve, reachable if
+ * a future tier dispatches it.
+ */
+
+import type { VerbSpec } from "../../kernel/spec/types.js";
+
+/** The `mcp` verb spec. */
+export const mcpVerb: VerbSpec<Record<string, unknown>, void> = {
+  path: ["mcp"],
+  summary: "Start the MCP server over stdio.",
+  hidden: true,
+  params: [],
+  output: {
+    formatters: {
+      plain: () => "",
+      llm: () => "",
+      json: () => JSON.stringify(null),
+    },
+  },
+  capability: {
+    needsStore: false,
+    mutates: false,
+    mcp: { expose: false, reason: "server entry, not an agent tool" },
+  },
+  run: () =>
+    Promise.all([
+      import("../../kernel/project/mcp/serve.js"),
+      import("../index.js"),
+    ]).then(([mcp, caps]) => mcp.serveMcp(caps.capabilities)),
+};

package/src/capabilities/modifier/index.ts

@@ -0,0 +1,15 @@
+/**
+ * The `modifier` capability module — the bundled pack (SPARQL list, GraphQL
+ * lookup) compiled to verbs.
+ */
+
+import { compilePack } from "../../kernel/packs/compile.js";
+import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { modifierPack } from "./pack.js";
+
+/** The `modifier` capability module (`list`, `lookup`). */
+export const modifierModule: CapabilityModule = {
+  name: "modifier",
+  verbs: compilePack(modifierPack, "bundled:modifier", DEFAULT_PREFIX_MAP),
+};

package/src/capabilities/modifier/pack.ts

@@ -0,0 +1,64 @@
+/**
+ * The bundled `modifier` pack — modifier families as data.
+ *
+ * `modifier list` is SPARQL (an alternation path collects values asserted in
+ * either direction); `modifier lookup` is GRAPHQL, where the compiled
+ * `ModifierFamily.modifiers` field is the declared-inverse union and resolves
+ * both directions in ONE generated document — exactly the case the GraphQL fetch
+ * path exists for.
+ */
+
+import type { PackDefinition } from "../../kernel/packs/types.js";
+
+export const modifierPack: PackDefinition = {
+  noun: "modifier",
+  description: "List all modifier families.",
+  toolDescription:
+    "List all modifier families with their values. Use when browsing which modifier families exist and the values each allows. Example: modifier_list {}.",
+  list: {
+    query: [
+      "SELECT ?uri ?name",
+      '       (GROUP_CONCAT(DISTINCT ?valueName; separator=", ") AS ?values)',
+      "WHERE {",
+      "  ?uri a ds:ModifierFamily ;",
+      "       ds:name ?name .",
+      "  OPTIONAL {",
+      "    ?uri (ds:hasModifier|^ds:modifierFamily) ?value .",
+      "    ?value ds:name ?valueName .",
+      "  }",
+      "}",
+      "GROUP BY ?uri ?name",
+      "ORDER BY ?name",
+    ].join("\n"),
+    columns: [
+      { field: "uri", label: "IRI" },
+      { field: "name", label: "Name" },
+      { field: "values", label: "Values" },
+    ],
+    emptyRecovery: {
+      message:
+        "No modifier families in the store. Build it from the configured design-system packages.",
+      cli: "pragma sources update",
+    },
+  },
+  lookup: {
+    source: "graphql",
+    by: "ds:name",
+    type: "ds:ModifierFamily",
+    toolDescription:
+      'Get values and usage details for one or more modifier families by name. Use when you need the allowed values of specific families. Example: modifier_lookup { names: ["importance"] }.',
+    expand: [
+      {
+        name: "values",
+        heading: "Values",
+        relation: "ds:hasModifier",
+        select: [{ name: "name", property: "ds:name" }],
+      },
+    ],
+    sample: {
+      fixedCount: true,
+      toolDescription:
+        "Return randomly selected complete modifier families (with value lists) as exemplars. Use BEFORE writing queries to see actual data shapes.",
+    },
+  },
+};

package/src/capabilities/ontology/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The `ontology` capability module — schema (TBox) inspection.
+ */
+
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { ontologyListVerb, ontologyShowVerb } from "./verbs.js";
+
+/** The `ontology` capability module (`list`, `show`). */
+export const ontologyModule: CapabilityModule = {
+  name: "ontology",
+  verbs: [ontologyListVerb, ontologyShowVerb],
+};

package/src/capabilities/ontology/ontology.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Ontology inspection (list + show) over the block fixture graph.
+ *
+ * Asserts the TBox exception: namespaces are grouped with class/property counts,
+ * a namespace's class hierarchy carries per-class instance counts from the pack
+ * index, `--class` focuses, `--properties` includes properties, and `--full-uris`
+ * shows absolute IRIs.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  BLOCK_PREFIXES,
+  BLOCK_TTL,
+} from "../../testing/fixtures/blockGraph.js";
+import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import { ontologyModule } from "./index.js";
+import type { OntologyShowData, OntologySummary } from "./queries.js";
+
+const listVerb = ontologyModule.verbs.find(
+  (v) => verbKey(v.path) === "ontology list",
+) as VerbSpec;
+const showVerb = ontologyModule.verbs.find(
+  (v) => verbKey(v.path) === "ontology show",
+) as VerbSpec;
+
+let rt: PragmaRuntime;
+beforeAll(async () => {
+  ({ rt } = await buildFixtureRuntime({
+    ttl: BLOCK_TTL,
+    prefixes: BLOCK_PREFIXES,
+  }));
+});
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+describe("ontology list", () => {
+  it("groups the ds namespace with class and property counts", async () => {
+    const rows = (await listVerb.run({}, rt)) as OntologySummary[];
+    const ds = rows.find((r) => r.prefix === "ds");
+    expect(ds).toBeDefined();
+    expect(ds?.namespace).toBe("https://ds.canonical.com/");
+    expect(ds?.classCount).toBeGreaterThan(0);
+    expect(ds?.propertyCount).toBeGreaterThan(0);
+  });
+});
+
+describe("ontology show", () => {
+  it("renders the class hierarchy with per-class instance counts from the index", async () => {
+    const data = (await showVerb.run({ prefix: "ds" }, rt)) as OntologyShowData;
+    const component = data.classes.find((c) => c.uri.endsWith("Component"));
+    expect(component?.superclass).toBe("https://ds.canonical.com/UIBlock");
+    // Two Component individuals (Button, Modal) in the fixture.
+    expect(component?.instanceCount).toBe(2);
+    expect(data.properties).toEqual([]);
+  });
+
+  it("--class focuses on one class and its properties", async () => {
+    const data = (await showVerb.run(
+      { prefix: "ds", class: "BlockProperty" },
+      rt,
+    )) as OntologyShowData;
+    expect(data.classes.map((c) => c.uri.split(/[#/]/).pop())).toEqual([
+      "BlockProperty",
+    ]);
+    // The focus pulls in properties whose domain is BlockProperty.
+    expect(
+      data.properties.every(
+        (p) => p.domain === "https://ds.canonical.com/BlockProperty",
+      ),
+    ).toBe(true);
+    expect(data.properties.length).toBeGreaterThan(0);
+    expect(data.focus).toBe("BlockProperty");
+  });
+
+  it("--full-uris flag rides on the payload for the renderer", async () => {
+    const data = (await showVerb.run(
+      { prefix: "ds", fullUris: true },
+      rt,
+    )) as OntologyShowData;
+    expect(data.fullUris).toBe(true);
+    const llm = showVerb.output.formatters.llm(data);
+    expect(llm).toContain("https://ds.canonical.com/Component");
+  });
+
+  it("rejects an unknown prefix with recovery", async () => {
+    await expect(showVerb.run({ prefix: "nope" }, rt)).rejects.toThrow(
+      /prefix/i,
+    );
+  });
+});

package/src/capabilities/ontology/queries.ts

@@ -0,0 +1,197 @@
+/**
+ * Store-backed ontology inspection queries + shapes (the TBox exception).
+ *
+ * Unlike instance reads (GraphQL by default), ontology inspection queries the
+ * schema directly with SPARQL over `owl:Class`/`owl:*Property` — a recorded
+ * TBox exception to the source rule. Full IRIs are used in the query text so the
+ * result never depends on which vocabulary prefixes the store injected.
+ */
+
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+
+const OWL = "http://www.w3.org/2002/07/owl#";
+const RDFS = "http://www.w3.org/2000/01/rdf-schema#";
+const OWL_CLASS = `${OWL}Class`;
+const OWL_OBJECT_PROPERTY = `${OWL}ObjectProperty`;
+const OWL_DATATYPE_PROPERTY = `${OWL}DatatypeProperty`;
+
+/** A loaded namespace summary (`ontology list`). */
+export interface OntologySummary {
+  readonly prefix: string;
+  readonly namespace: string;
+  readonly classCount: number;
+  readonly propertyCount: number;
+}
+
+/** A class in the hierarchy, with its instance count from the pack index. */
+export interface OntologyClass {
+  readonly uri: string;
+  readonly label: string;
+  readonly superclass?: string;
+  readonly instanceCount: number;
+}
+
+/** A property definition. */
+export interface OntologyProperty {
+  readonly uri: string;
+  readonly label: string;
+  readonly domain?: string;
+  readonly range?: string;
+  readonly type: "object" | "datatype";
+}
+
+/** The `ontology show` payload — the detailed view plus render options. */
+export interface OntologyShowData {
+  readonly prefix: string;
+  readonly namespace: string;
+  readonly classes: readonly OntologyClass[];
+  readonly properties: readonly OntologyProperty[];
+  /** Show full IRIs instead of prefix-compacted ones. */
+  readonly fullUris: boolean;
+  /** The `--class` focus, if any. */
+  readonly focus?: string;
+}
+
+type QueryRt = Pick<PragmaRuntime, "query">;
+
+/** Local name of an IRI (`…#Thing`/`…/Thing` → `Thing`). */
+export function localName(uri: string): string {
+  const hash = uri.lastIndexOf("#");
+  if (hash !== -1) return uri.slice(hash + 1);
+  const slash = uri.lastIndexOf("/");
+  return slash !== -1 ? uri.slice(slash + 1) : uri;
+}
+
+async function select(
+  rt: QueryRt,
+  text: string,
+): Promise<Record<string, string>[]> {
+  const result = await rt.query.sparql(text);
+  return result.type === "select"
+    ? (result.bindings as Record<string, string>[])
+    : [];
+}
+
+/** Group all defined classes/properties by their namespace prefix, with counts. */
+export async function listNamespaces(
+  rt: QueryRt,
+  prefixes: Readonly<Record<string, string>>,
+): Promise<OntologySummary[]> {
+  const [classes, props] = await Promise.all([
+    select(rt, `SELECT ?class WHERE { ?class a <${OWL_CLASS}> }`),
+    select(
+      rt,
+      `SELECT ?prop WHERE { ?prop a ?t . VALUES ?t { <${OWL_OBJECT_PROPERTY}> <${OWL_DATATYPE_PROPERTY}> } }`,
+    ),
+  ]);
+  const entries = Object.entries(prefixes);
+  const classByPrefix = new Map<string, Set<string>>();
+  const propByPrefix = new Map<string, Set<string>>();
+  const tally = (
+    rows: Record<string, string>[],
+    key: "class" | "prop",
+    into: Map<string, Set<string>>,
+  ) => {
+    for (const row of rows) {
+      const uri = row[key] ?? "";
+      const match = findNamespace(uri, entries);
+      if (!match) continue;
+      const set = into.get(match.prefix) ?? new Set();
+      set.add(uri);
+      into.set(match.prefix, set);
+    }
+  };
+  tally(classes, "class", classByPrefix);
+  tally(props, "prop", propByPrefix);
+  const allPrefixes = new Set([
+    ...classByPrefix.keys(),
+    ...propByPrefix.keys(),
+  ]);
+  return [...allPrefixes].sort().map((prefix) => ({
+    prefix,
+    namespace: prefixes[prefix] ?? "",
+    classCount: classByPrefix.get(prefix)?.size ?? 0,
+    propertyCount: propByPrefix.get(prefix)?.size ?? 0,
+  }));
+}
+
+/** The longest-matching namespace prefix for a URI. */
+function findNamespace(
+  uri: string,
+  entries: [string, string][],
+): { prefix: string; namespace: string } | undefined {
+  let best: { prefix: string; namespace: string } | undefined;
+  for (const [prefix, namespace] of entries) {
+    if (
+      uri.startsWith(namespace) &&
+      (!best || namespace.length > best.namespace.length)
+    ) {
+      best = { prefix, namespace };
+    }
+  }
+  return best;
+}
+
+/** All classes in a namespace, with labels, superclasses, and index counts. */
+export async function queryClasses(
+  rt: QueryRt,
+  namespace: string,
+  instanceCountByType: Readonly<Record<string, number>>,
+): Promise<OntologyClass[]> {
+  const rows = await select(
+    rt,
+    [
+      "SELECT ?class ?label ?superclass WHERE {",
+      `  ?class a <${OWL_CLASS}> .`,
+      `  FILTER(STRSTARTS(STR(?class), "${namespace}"))`,
+      `  OPTIONAL { ?class <${RDFS}label> ?label }`,
+      `  OPTIONAL { ?class <${RDFS}subClassOf> ?superclass }`,
+      "} ORDER BY ?class",
+    ].join("\n"),
+  );
+  const seen = new Map<string, OntologyClass>();
+  for (const row of rows) {
+    const uri = row.class ?? "";
+    if (seen.has(uri)) continue;
+    seen.set(uri, {
+      uri,
+      label: row.label || localName(uri),
+      ...(row.superclass ? { superclass: row.superclass } : {}),
+      instanceCount: instanceCountByType[uri] ?? 0,
+    });
+  }
+  return [...seen.values()];
+}
+
+/** All object/datatype properties in a namespace. */
+export async function queryProperties(
+  rt: QueryRt,
+  namespace: string,
+): Promise<OntologyProperty[]> {
+  const rows = await select(
+    rt,
+    [
+      "SELECT ?prop ?label ?domain ?range ?propType WHERE {",
+      "  ?prop a ?propType .",
+      `  VALUES ?propType { <${OWL_OBJECT_PROPERTY}> <${OWL_DATATYPE_PROPERTY}> }`,
+      `  FILTER(STRSTARTS(STR(?prop), "${namespace}"))`,
+      `  OPTIONAL { ?prop <${RDFS}label> ?label }`,
+      `  OPTIONAL { ?prop <${RDFS}domain> ?domain }`,
+      `  OPTIONAL { ?prop <${RDFS}range> ?range }`,
+      "} ORDER BY ?prop",
+    ].join("\n"),
+  );
+  const seen = new Map<string, OntologyProperty>();
+  for (const row of rows) {
+    const uri = row.prop ?? "";
+    if (seen.has(uri)) continue;
+    seen.set(uri, {
+      uri,
+      label: row.label || localName(uri),
+      ...(row.domain ? { domain: row.domain } : {}),
+      ...(row.range ? { range: row.range } : {}),
+      type: row.propType?.includes("ObjectProperty") ? "object" : "datatype",
+    });
+  }
+  return [...seen.values()];
+}