@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/kernel/runtime/boot.test.ts

@@ -0,0 +1,69 @@
+/**
+ * C2 (config visibility) at the runtime seam.
+ *
+ * `bootRuntime` memoizes the layered-config read (`configPromise`) for the
+ * invocation. On a long-lived MCP server that memo would strand a stale config
+ * after a `config_set` write — subsequent reads keep serving the old value. The
+ * fix couples the two server-lifetime memos: `store.invalidate()` also clears
+ * the config memo (via the `onInvalidate` hook boot.ts wires), so the next
+ * `loadConfig()` re-reads disk. This drives that mechanism directly against the
+ * real config reader and an isolated global config file.
+ */
+
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { bootRuntime } from "./boot.js";
+import type { GlobalFlags } from "./types.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+
+describe("bootRuntime config memo — invalidate() re-reads config from disk (C2)", () => {
+  let priorXdgConfig: string | undefined;
+  let configPath: string;
+
+  beforeEach(() => {
+    // Isolate the global config to this test so writes never bleed across tests.
+    priorXdgConfig = process.env.XDG_CONFIG_HOME;
+    const xdg = mkdtempSync(join(tmpdir(), "pragma-c2-cfg-"));
+    process.env.XDG_CONFIG_HOME = xdg;
+    mkdirSync(join(xdg, "pragma"), { recursive: true });
+    configPath = join(xdg, "pragma", "config.json");
+  });
+
+  afterEach(() => {
+    if (priorXdgConfig === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = priorXdgConfig;
+  });
+
+  it("serves the memoized config until store.invalidate() clears it, then re-reads disk", async () => {
+    writeFileSync(configPath, JSON.stringify({ tier: "apps/lxd" }));
+    // An empty project dir: only the global layer contributes `tier`.
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-c2-proj-"));
+    const runtime = bootRuntime(FLAGS, cwd);
+
+    const first = await runtime.loadConfig();
+    expect(first.config.tier).toBe("apps/lxd");
+
+    // A mutation changes config on disk...
+    writeFileSync(configPath, JSON.stringify({ tier: "apps/vm" }));
+
+    // ...but the per-invocation memo still serves the STALE value (the bug the
+    // fix targets on a long-lived server).
+    const stale = await runtime.loadConfig();
+    expect(stale.config.tier).toBe("apps/lxd");
+
+    // Invalidating the store drops the coupled config memo (onInvalidate)...
+    runtime.store.invalidate();
+
+    // ...so the next read re-reads disk and sees the new value.
+    const fresh = await runtime.loadConfig();
+    expect(fresh.config.tier).toBe("apps/vm");
+  });
+});

package/src/kernel/runtime/boot.ts

@@ -0,0 +1,59 @@
+/**
+ * Build the per-invocation {@link PragmaRuntime}.
+ *
+ * The runtime stays cheap and storeless to construct: `store` is a lazy handle
+ * (nothing boots until a `needsStore` verb calls `store.get()`), `query` is the
+ * facade over it, and `loadConfig` memoizes the layered-config read behind a
+ * dynamic import so the config reader (and its zod) never lands on the
+ * `--help`/`__complete` fast path. No eager I/O happens here — a storeless verb
+ * that only reads `globalFlags`/`cwd` touches neither the store nor config.
+ *
+ * The store's boot reads config through `loadConfig`, so the two memos are
+ * coupled: `store.invalidate()` (called by the MCP projector after a real
+ * mutation) also clears `configPromise` via the `onInvalidate` hook, so a
+ * re-boot re-reads config from disk instead of reusing a stale layer. On a
+ * long-lived MCP server that is what makes a `config_set` visible to the next
+ * read tool; on a one-shot CLI nothing calls `invalidate`, so it never fires.
+ */
+
+import { VERSION } from "../../constants.js";
+import type { ConfigLayers } from "../config/types.js";
+import { createQueryFacade } from "./facade.js";
+import { createLazyStore } from "./store.js";
+import type { GlobalFlags, PragmaRuntime } from "./types.js";
+
+/**
+ * Assemble a runtime for one CLI or MCP invocation.
+ *
+ * @param globalFlags - The parsed global flags for this invocation.
+ * @param cwd - The directory to resolve project state against (defaults to the
+ *   process working directory).
+ * @returns The runtime handed to every verb `run`.
+ * @note Impure by default — reads `process.cwd()` unless `cwd` is provided; the
+ *   store/config handles it exposes do their own I/O only when used.
+ */
+export function bootRuntime(
+  globalFlags: GlobalFlags,
+  cwd: string = process.cwd(),
+): PragmaRuntime {
+  let configPromise: Promise<ConfigLayers> | undefined;
+  const loadConfig = (): Promise<ConfigLayers> => {
+    configPromise ??= import("../config/readConfig.js").then((module) =>
+      module.readConfig(cwd),
+    );
+    return configPromise;
+  };
+
+  const store = createLazyStore({
+    cwd,
+    loadConfig,
+    // Invalidating the store must also drop the config memo its boot depends on,
+    // so a re-boot after a mutation re-reads config from disk (never stale).
+    onInvalidate: () => {
+      configPromise = undefined;
+    },
+  });
+  const query = createQueryFacade(store);
+
+  return { cwd, version: VERSION, globalFlags, loadConfig, store, query };
+}

package/src/kernel/runtime/facade.test.ts

@@ -0,0 +1,125 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterAll,
+  beforeAll,
+  describe,
+  expect,
+  it,
+  type Mock,
+  vi,
+} from "vitest";
+
+// Spy on the compiler entry points while keeping the real implementations, so
+// we can assert that BOOT rebuilds the schema from the extraction artifact
+// (compileFromExtraction) and NEVER runs the live 7-pass compile.
+vi.mock("@canonical/ke-graphql", async (importActual) => {
+  const actual = await importActual<typeof import("@canonical/ke-graphql")>();
+  return {
+    ...actual,
+    compile: vi.fn(actual.compile),
+    compileFromExtraction: vi.fn(actual.compileFromExtraction),
+  };
+});
+
+import { compile, compileFromExtraction } from "@canonical/ke-graphql";
+import { createQueryFacade } from "./facade.js";
+import { buildPack } from "./graphpack/build.js";
+import { readPack } from "./graphpack/read.js";
+import type { LazyStore } from "./types.js";
+
+const PREFIXES = {
+  ex: "https://pragma.canonical.com/sample#",
+  owl: "http://www.w3.org/2002/07/owl#",
+  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+  xsd: "http://www.w3.org/2001/XMLSchema#",
+};
+const TTL = `
+@prefix ex:   <https://pragma.canonical.com/sample#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix owl:  <http://www.w3.org/2002/07/owl#> .
+@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
+ex:Component a owl:Class ; rdfs:label "Component" .
+ex:Button a ex:Component ; rdfs:label "Button" .
+`;
+
+let savedCacheHome: string | undefined;
+let cacheHome: string;
+let dir: string;
+
+beforeAll(async () => {
+  savedCacheHome = process.env.XDG_CACHE_HOME;
+  cacheHome = mkdtempSync(join(tmpdir(), "pragma-facade-"));
+  process.env.XDG_CACHE_HOME = cacheHome;
+  // Building the pack is the ONE place the live compile runs.
+  const built = await buildPack([{ path: "a.ttl", content: TTL }], {
+    name: "facade-test",
+    version: "0.0.0",
+    sourceRef: "test:inline",
+    prefixes: PREFIXES,
+  });
+  dir = built.dir;
+  expect((compile as unknown as Mock).mock.calls.length).toBeGreaterThan(0);
+});
+
+afterAll(() => {
+  process.env.XDG_CACHE_HOME = savedCacheHome;
+  rmSync(cacheHome, { recursive: true, force: true });
+});
+
+describe("query facade round-trip (PROTECTED)", () => {
+  it("boots via compileFromExtraction and never calls the live compile", async () => {
+    (compile as unknown as Mock).mockClear();
+    (compileFromExtraction as unknown as Mock).mockClear();
+
+    // A minimal lazy store pointed straight at the built pack.
+    let booted = false;
+    const store: LazyStore = {
+      get booted() {
+        return booted;
+      },
+      async get() {
+        const session = await readPack(dir);
+        booted = true;
+        return session;
+      },
+      invalidate() {
+        booted = false;
+      },
+    };
+    const facade = createQueryFacade(store);
+
+    const result = await facade.graphql("{ __schema { queryType { name } } }");
+    expect(result.errors).toBeUndefined();
+    expect(result.data).toBeDefined();
+
+    // Boot rebuilt the schema from the artifact — the live compile stayed cold.
+    expect((compileFromExtraction as unknown as Mock).mock.calls.length).toBe(
+      1,
+    );
+    expect((compile as unknown as Mock).mock.calls.length).toBe(0);
+  });
+
+  it("sparql escape hatch queries the store", async () => {
+    let booted = false;
+    const store: LazyStore = {
+      get booted() {
+        return booted;
+      },
+      async get() {
+        const session = await readPack(dir);
+        booted = true;
+        return session;
+      },
+      invalidate() {
+        booted = false;
+      },
+    };
+    const facade = createQueryFacade(store);
+    const result = await facade.sparql(
+      "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }",
+    );
+    expect(result.type).toBe("select");
+  });
+});

package/src/kernel/runtime/facade.ts

@@ -0,0 +1,47 @@
+/**
+ * The query facade — the typed spine over the lazy store.
+ *
+ * `graphql` is the default surface: it executes a document against the pack's
+ * precompiled schema via ke-graphql's in-process `executeLocal` (no HTTP, no
+ * serialization). `sparql` is the escape hatch: a raw query against the store,
+ * auto-prefixed by ke from the pack's prefix map. Both boot the store lazily on
+ * first use through the same memoized `LazyStore.get()`. ke-graphql is
+ * dynamic-imported so this module carries no static import of the heavy
+ * runtime; the ke/graphql types are referenced inline.
+ */
+
+import type { LazyStore, QueryFacade } from "./types.js";
+
+/**
+ * Build the query facade over a lazy store.
+ *
+ * @param store - The lazy store to query through.
+ * @returns The `{ graphql, sparql }` facade.
+ */
+export function createQueryFacade(store: LazyStore): QueryFacade {
+  return {
+    async graphql(
+      document: string,
+      variables?: Record<string, unknown> | null,
+    ): Promise<import("graphql").ExecutionResult> {
+      const session = await store.get();
+      const { executeLocal } = await import("@canonical/ke-graphql");
+      const result = await executeLocal({
+        schema: session.schema,
+        source: document,
+        variableValues: variables ?? undefined,
+        contextValue: session.createContext(session.store),
+      });
+      // Our packs compile without @defer/@stream, so this is always a plain
+      // ExecutionResult (never an incremental stream).
+      return result as import("graphql").ExecutionResult;
+    },
+
+    async sparql(text: string): Promise<import("@canonical/ke").QueryResult> {
+      const session = await store.get();
+      return session.store.query(text as never) as Promise<
+        import("@canonical/ke").QueryResult
+      >;
+    },
+  };
+}

package/src/kernel/runtime/graphpack/build.ts

@@ -0,0 +1,176 @@
+/**
+ * Build a content-addressed pack from RDF source inputs.
+ *
+ * This is the ONE place the live ke-graphql 7-pass `compile` runs (~210 ms):
+ * building is when we can afford it. The store is created once (parsing the
+ * TTL and writing the `data.nq` n-quads dump via ke's cache), the schema is
+ * extracted and serialized, the entity index is built, and a manifest is
+ * written LAST so the directory is only ever observed complete. Writes go to a
+ * temp directory and are atomically renamed into `packs/<contentHash>/`, so a
+ * crashed build never leaves a half-written pack; a hash whose directory is
+ * already complete is reused untouched.
+ *
+ * Reached only behind a dynamic import (`sources update`), never on the
+ * storeless fast path.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { createStore } from "@canonical/ke";
+import {
+  compile,
+  createStoreQueryFn,
+  serializeExtraction,
+} from "@canonical/ke-graphql";
+import { packDir, packsCacheDir } from "../paths.js";
+import { buildIndex } from "./buildIndex.js";
+import { contentHash, hashSources } from "./hash.js";
+import { packIsComplete, readManifest } from "./manifest.js";
+import {
+  DATA_FILE,
+  INDEX_FILE,
+  MANIFEST_FILE,
+  type Manifest,
+  SCHEMA_FILE,
+} from "./types.js";
+
+/** One RDF source to build into a pack. */
+export interface BuildPackInput {
+  /** Stable path label — part of the content hash. */
+  readonly path: string;
+  /** Raw RDF content. */
+  readonly content: string;
+}
+
+/** Provenance and options for a pack build. */
+export interface BuildPackOptions {
+  readonly name: string;
+  readonly version: string;
+  /** The config `packages` ref (verbatim) or a label. */
+  readonly sourceRef: string;
+  /** Prefixes the store (and every query) is built with. */
+  readonly prefixes?: Readonly<Record<string, string>>;
+}
+
+/** The outcome of a pack build (or cache hit). */
+export interface BuildPackResult {
+  readonly dir: string;
+  readonly contentHash: string;
+  readonly manifest: Manifest;
+  /** True when an already-complete pack was reused rather than rebuilt. */
+  readonly reused: boolean;
+}
+
+/**
+ * Build (or reuse) the pack for a set of source inputs.
+ *
+ * @param inputs - The RDF sources (path + content).
+ * @param options - Provenance and the prefixes to build with.
+ * @returns The pack directory, its content hash, and whether it was reused.
+ * @note Impure — creates a store, compiles the schema, writes the pack.
+ */
+export async function buildPack(
+  inputs: readonly BuildPackInput[],
+  options: BuildPackOptions,
+): Promise<BuildPackResult> {
+  const hash = await contentHash(
+    inputs.map((input) => ({ path: input.path, content: input.content })),
+  );
+  const dir = packDir(hash);
+
+  // Reuse only a COMPLETE pack (manifest + non-empty dump). A corrupt cache
+  // (intact manifest, ruined `data.nq`) must rebuild, not be reused — otherwise
+  // an emptied dump would be permanent.
+  if (packIsComplete(dir)) {
+    const cached = readManifest(dir);
+    if (cached)
+      return { dir, contentHash: hash, manifest: cached, reused: true };
+  }
+
+  mkdirSync(packsCacheDir(), { recursive: true });
+  const temp = mkdtempSync(
+    join(packsCacheDir(), `.build-${hash.slice(0, 12)}-`),
+  );
+  try {
+    const prefixes = options.prefixes ?? {};
+    const store = await createStore({
+      sources: inputs.map((input) => ({
+        content: input.content,
+        path: input.path,
+      })),
+      prefixes,
+      // ke writes the n-quads dump here after loading — our `data.nq`.
+      cache: join(temp, DATA_FILE),
+    });
+
+    try {
+      const compiled = await compile(createStoreQueryFn(store), store.prefixes);
+      const sourcesHash = hashSources(inputs.map((input) => input.content));
+      writeFileSync(
+        join(temp, SCHEMA_FILE),
+        serializeExtraction(compiled.extraction, sourcesHash),
+      );
+
+      const index = await buildIndex(store, store.prefixes, hash);
+      writeFileSync(join(temp, INDEX_FILE), JSON.stringify(index));
+
+      const tripleCount = await countTriples(store);
+      // Distinct abox subjects — the same figure `entityTotal` reports (A10),
+      // so `sources status` reads it from the manifest without parsing the
+      // whole index.json. Keep this in sync with `entityTotal` in entitySource.
+      const entityCount = new Set(
+        index.entities
+          .filter((entity) => entity.box === "abox")
+          .map((entity) => entity.uri ?? entity.name),
+      ).size;
+
+      const manifest: Manifest = {
+        name: options.name,
+        version: options.version,
+        sourceRef: options.sourceRef,
+        contentHash: hash,
+        prefixes: { ...store.prefixes },
+        createdAt: new Date().toISOString(),
+        tripleCount,
+        entityCount,
+      };
+      // Written LAST — the completeness marker for the directory.
+      writeFileSync(join(temp, MANIFEST_FILE), JSON.stringify(manifest));
+
+      // Publish atomically. A concurrent builder may have won the race — its
+      // pack is content-identical, so keep it and drop ours.
+      if (!packIsComplete(dir)) {
+        rmSync(dir, { recursive: true, force: true });
+        renameSync(temp, dir);
+      }
+      return { dir, contentHash: hash, manifest, reused: false };
+    } finally {
+      store.dispose();
+    }
+  } finally {
+    if (existsSync(temp)) rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Count a store's triples (a cheap aggregate over the union graph).
+ *
+ * @param store - The booted store.
+ * @returns The number of triples.
+ * @note Impure — runs a COUNT query against the store.
+ */
+async function countTriples(
+  store: Awaited<ReturnType<typeof createStore>>,
+): Promise<number> {
+  const result = (await store.query(
+    "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }" as never,
+  )) as import("@canonical/ke").SelectResult;
+  return Number(result.bindings.at(0)?.n ?? 0);
+}

package/src/kernel/runtime/graphpack/buildIndex.test.ts

@@ -0,0 +1,103 @@
+import { createStore } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  OWL_EXPORT_ABOX_SUBJECTS,
+  OWL_EXPORT_PREFIXES,
+  OWL_EXPORT_TTL,
+} from "../../../testing/fixtures/graph/owlExport.js";
+import { entityTotal } from "../../completion/entitySource.js";
+import { buildIndex } from "./buildIndex.js";
+import type { PackIndex } from "./types.js";
+
+type Store = import("@canonical/ke").Store;
+
+/**
+ * The counters/classifiers `buildIndex` builds are masked by the embedded
+ * single-typed toy graph; the multi-typed OWL-export fixture is where the
+ * backlog-A bugs bite. Each `it` fails on the pre-fix code and passes after.
+ */
+describe("buildIndex — real-data counters/classifiers (backlog A)", () => {
+  let store: Store;
+  let index: PackIndex;
+
+  beforeAll(async () => {
+    store = await createStore({
+      sources: [{ content: OWL_EXPORT_TTL, path: "owl-export.ttl" }],
+      prefixes: OWL_EXPORT_PREFIXES,
+    });
+    index = await buildIndex(store, OWL_EXPORT_PREFIXES, "test-hash");
+  });
+
+  afterAll(() => {
+    store.dispose();
+  });
+
+  const byName = (name: string): PackIndex["entities"][number][] =>
+    index.entities.filter((entity) => entity.name === name);
+
+  it("A1: entityTotal counts DISTINCT abox subjects, not the raw multiset", () => {
+    // Every individual once — despite Protégé's `owl:NamedIndividual` dual-typing.
+    expect(entityTotal(index)).toBe(OWL_EXPORT_ABOX_SUBJECTS.length);
+
+    // The raw multiset the old code summed is strictly larger: each individual
+    // double-counts under `owl:NamedIndividual`, plus the class/property
+    // meta-buckets pile on top.
+    const rawSum = Object.values(index.instanceCountByType).reduce(
+      (sum, n) => sum + n,
+      0,
+    );
+    expect(rawSum).toBeGreaterThan(entityTotal(index));
+
+    // The abox names match the oracle exactly.
+    const aboxNames = index.entities
+      .filter((entity) => entity.box === "abox")
+      .map((entity) => entity.name);
+    expect([...new Set(aboxNames)].sort()).toEqual([
+      ...OWL_EXPORT_ABOX_SUBJECTS,
+    ]);
+  });
+
+  it("A3: a multi-domain individual gets a deterministic (lexical) primary type", () => {
+    // ex:toggle is both ex:Interactive and ex:FormControl; the smaller wins,
+    // every build/engine — never whichever type the store returned first.
+    const toggle = byName("ex:toggle").at(0);
+    expect(toggle?.type).toBe("ex:FormControl");
+    expect(toggle?.box).toBe("abox");
+  });
+
+  it("A6: a blank-node rdf:type is ignored, never a garbage primary type", () => {
+    // ex:field is typed by an anonymous class too; the blank node must not win.
+    expect(byName("ex:field").at(0)?.type).toBe("ex:FormControl");
+    // No entity type, no listed type, and no instance-count bucket is a blank node.
+    for (const entity of index.entities) {
+      expect(entity.type.startsWith("_:")).toBe(false);
+      for (const type of entity.types ?? []) {
+        expect(type.startsWith("_:")).toBe(false);
+      }
+    }
+    for (const key of Object.keys(index.instanceCountByType)) {
+      expect(key.startsWith("_:")).toBe(false);
+    }
+  });
+
+  it("A7: a multilingual label resolves to @en, deterministically", () => {
+    // "Button"@en / "Bouton"@fr → Button; the @lang no longer flips the pick.
+    expect(byName("ds:button").at(0)?.label).toBe("Button");
+    expect(byName("ex:toggle").at(0)?.label).toBe("Toggle");
+    expect(byName("ds:datePicker").at(0)?.label).toBe("Date Picker");
+  });
+
+  it("A8: an OWL-punned subject emits BOTH its tbox and abox facet", () => {
+    // ex:Slider is a class (tbox) AND an ex:Category individual (abox) — both
+    // must survive, so its abox membership stays completable.
+    const facets = byName("ex:Slider");
+    expect(facets).toHaveLength(2);
+    expect(facets.map((facet) => facet.box).sort()).toEqual(["abox", "tbox"]);
+    expect(facets.find((facet) => facet.box === "tbox")?.type).toBe(
+      "owl:Class",
+    );
+    expect(facets.find((facet) => facet.box === "abox")?.type).toBe(
+      "ex:Category",
+    );
+  });
+});