@canonical/pragma-cli 0.31.0 → 0.33.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,19 @@
+/**
+ * The `ontology` capability module — schema (TBox) inspection.
+ */
+
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import {
+  ontologyListVerb,
+  ontologyLookupVerb,
+  ontologyShowVerb,
+} from "./verbs.js";
+
+/**
+ * The `ontology` capability module (`list`, `lookup`, and the deprecated `show`
+ * alias — AV-228 B1).
+ */
+export const ontologyModule: CapabilityModule = {
+  name: "ontology",
+  verbs: [ontologyListVerb, ontologyLookupVerb, ontologyShowVerb],
+};

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

@@ -0,0 +1,246 @@
+/**
+ * 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 { CANONICAL_TTL } from "../../testing/fixtures/graph/canonical.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../../testing/helpers/fixtureGraph.js";
+import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { capabilities } from "../index.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 lookupVerb = ontologyModule.verbs.find(
+  (v) => verbKey(v.path) === "ontology lookup",
+) 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 lookup (primary by-name read)", () => {
+  it("renders the class hierarchy with per-class instance counts from the index", async () => {
+    const data = (await lookupVerb.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("--detail detailed folds onto disclosure and includes properties (B5)", async () => {
+    // Ontology honours the canonical `--detail` instead of only its bespoke
+    // `--properties`: standard/detailed add the properties section.
+    const detailed = {
+      ...rt,
+      globalFlags: { ...rt.globalFlags, detail: "detailed" as const },
+    };
+    const data = (await lookupVerb.run(
+      { prefix: "ds" },
+      detailed,
+    )) as OntologyShowData;
+    expect(data.properties.length).toBeGreaterThan(0);
+  });
+
+  it("--detail summary keeps classes only (no properties)", async () => {
+    const summary = {
+      ...rt,
+      globalFlags: { ...rt.globalFlags, detail: "summary" as const },
+    };
+    const data = (await lookupVerb.run(
+      { prefix: "ds" },
+      summary,
+    )) as OntologyShowData;
+    expect(data.properties).toEqual([]);
+  });
+
+  it("--class focuses on one class and its properties", async () => {
+    const data = (await lookupVerb.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 lookupVerb.run(
+      { prefix: "ds", fullUris: true },
+      rt,
+    )) as OntologyShowData;
+    expect(data.fullUris).toBe(true);
+    const llm = lookupVerb.output.formatters.llm(data);
+    expect(llm).toContain("https://ds.canonical.com/Component");
+  });
+
+  it("rejects an unknown prefix with recovery", async () => {
+    await expect(lookupVerb.run({ prefix: "nope" }, rt)).rejects.toThrow(
+      /prefix/i,
+    );
+  });
+});
+
+describe("ontology show — deprecated alias of lookup (AV-228 B1)", () => {
+  it("is marked deprecated in its summary and steers callers to `ontology lookup`", () => {
+    expect(showVerb.summary.toLowerCase()).toContain("deprecated");
+    expect(showVerb.summary).toContain("ontology lookup");
+  });
+
+  it("shares the lookup handler — same payload for the same input", async () => {
+    const viaLookup = (await lookupVerb.run(
+      { prefix: "ds", properties: true },
+      rt,
+    )) as OntologyShowData;
+    const viaShow = (await showVerb.run(
+      { prefix: "ds", properties: true },
+      rt,
+    )) as OntologyShowData;
+    expect(viaShow).toEqual(viaLookup);
+  });
+
+  it("still rejects an unknown prefix (the alias is a full, callable verb)", async () => {
+    await expect(showVerb.run({ prefix: "nope" }, rt)).rejects.toThrow(
+      /prefix/i,
+    );
+  });
+});
+
+describe("ontology_show honours detail over MCP (B5)", () => {
+  // The CLI B5 cases above seed `globalFlags.detail` and call `showVerb.run`
+  // directly. Over MCP there are NO global flags — the ONLY detail channel is
+  // the per-tool `detail` param the projector injects from the VerbSpec
+  // disclosure. Under an AMBIENT config `detail: standard`, an `ontology_show`
+  // with no declared disclosure would force the properties section with no
+  // per-call escape (the AV-228 MCP-opt-out asymmetry `block`/`standard` lack);
+  // declaring disclosure lights the param up, so an agent can ask for
+  // classes-only per call and can equally override upward.
+  let fixture: FixtureGraph;
+  let mcp: Awaited<ReturnType<typeof projectMcp>>;
+
+  beforeAll(async () => {
+    // Ambient config detail=standard → origins.detail === "project", so it
+    // outranks the verb's `summary` default inside resolvePackDetail.
+    fixture = await bootFixtureRuntime({
+      ttl: CANONICAL_TTL,
+      config: { detail: "standard" },
+    });
+    mcp = await projectMcp(capabilities, fixture.cwd);
+  });
+
+  afterAll(async () => {
+    await mcp.cleanup();
+    await fixture.dispose();
+  });
+
+  it("injects a detail param onto the ontology_show tool (symmetric with block/standard)", async () => {
+    const tools = await mcp.listTools();
+    const show = tools.find((t) => t.name === "ontology_show");
+    const schema = show?.inputSchema as {
+      properties?: Record<string, unknown>;
+    };
+    expect(schema.properties?.detail).toBeDefined();
+  });
+
+  it("exposes the primary ontology_lookup tool with the same injected detail param (AV-228 B1)", async () => {
+    const tools = await mcp.listTools();
+    const lookup = tools.find((t) => t.name === "ontology_lookup");
+    expect(lookup).toBeDefined();
+    const schema = lookup?.inputSchema as {
+      properties?: Record<string, unknown>;
+    };
+    expect(schema.properties?.detail).toBeDefined();
+  });
+
+  it("ontology_lookup honours a per-call detail=summary despite the ambient standard", async () => {
+    const result = await mcp.callTool("ontology_lookup", {
+      prefix: "ds",
+      detail: "summary",
+    });
+    expect(result.ok).toBe(true);
+    const data = result.data as { classes: unknown[]; properties: unknown[] };
+    expect(data.classes.length).toBeGreaterThan(0);
+    expect(data.properties).toEqual([]);
+  });
+
+  it("honours the ambient detail=standard config when no per-call detail is set", async () => {
+    // Proves the ambient level really is standard, so the summary case below is
+    // a genuine per-call override rather than merely the spec default.
+    const result = await mcp.callTool("ontology_show", { prefix: "ds" });
+    expect(result.ok).toBe(true);
+    const data = result.data as { properties: unknown[] };
+    expect(data.properties.length).toBeGreaterThan(0);
+  });
+
+  it("a per-call detail=summary returns classes-only despite the ambient standard", async () => {
+    const result = await mcp.callTool("ontology_show", {
+      prefix: "ds",
+      detail: "summary",
+    });
+    expect(result.ok).toBe(true);
+    const data = result.data as { classes: unknown[]; properties: unknown[] };
+    expect(data.classes.length).toBeGreaterThan(0);
+    expect(data.properties).toEqual([]);
+  });
+
+  it("an explicit detail=detailed overrides upward to include properties", async () => {
+    const result = await mcp.callTool("ontology_show", {
+      prefix: "ds",
+      detail: "detailed",
+    });
+    expect(result.ok).toBe(true);
+    const data = result.data as { properties: unknown[] };
+    expect(data.properties.length).toBeGreaterThan(0);
+  });
+});