@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/domains/graphql/operations/compileSchema.ts

@@ -1,5 +1,4 @@
-import { readFileSync } from "node:fs";
-import { createStore } from "@canonical/ke";
+import { createStore, type InlineSource } from "@canonical/ke";
 import {
   CompilationError,
   type CompilerResult,
@@ -9,15 +8,14 @@ import {
   hashSources,
 } from "@canonical/ke-graphql";
 import { PragmaError } from "#error";
-import { resolveSourceFiles } from "../helpers/index.js";
 
 export interface CompileSchemaOptions {
-  /** TTL file paths or glob patterns, resolved from `cwd`. */
-  readonly sources: readonly string[];
+  /** In-memory TTL sources (content + provenance path) to compile. */
+  readonly sources: readonly InlineSource[];
   /** Prefix map handed to both the ke store and the compiler. */
   readonly prefixes: Readonly<Record<string, string>>;
-  /** Working directory for resolving relative source paths. */
-  readonly cwd: string;
+  /** Working directory, passed through to the store (unused for inline). */
+  readonly cwd?: string;
 }
 
 export interface CompileSchemaResult {
@@ -25,7 +23,7 @@ export interface CompileSchemaResult {
   readonly status: "ok" | "failed";
   /** All compiler diagnostics, including those carried by a CompilationError. */
   readonly diagnostics: readonly Diagnostic[];
-  /** Resolved absolute TTL file paths that were loaded. */
+  /** Provenance paths of the sources that were loaded. */
   readonly files: readonly string[];
   /** Fingerprint of the raw source contents (matches ke's onLoad hashing). */
   readonly sourcesHash: string;
@@ -34,42 +32,42 @@ export interface CompileSchemaResult {
 }
 
 /**
- * Compile TTL sources into a GraphQL schema via the ke-graphql pipeline.
+ * Compile in-memory TTL sources into a GraphQL schema via the ke-graphql
+ * pipeline.
  *
- * Resolves source patterns, hashes the raw file contents (the exact bytes
- * ke loads, so the artifact's `sourcesHash` matches what
- * `createSchemaPlugin` computes from ke's onLoad), boots a throwaway ke
- * store, and runs the compiler. A {@link CompilationError} (schema
- * composition failed) is converted into a `"failed"` result carrying its
- * diagnostics; the store is always disposed.
+ * Hashes the raw source contents (the exact bytes ke loads, so the
+ * artifact's `sourcesHash` matches what `createSchemaPlugin` computes from
+ * ke's onLoad), boots a throwaway ke store, and runs the compiler. A
+ * {@link CompilationError} (schema composition failed) is converted into a
+ * `"failed"` result carrying its diagnostics; the store is always disposed.
  *
- * @note Impure — reads filesystem and boots a ke store (WASM + TTL).
+ * @note Impure — boots a ke store (WASM + TTL).
  *
- * @param options - Sources, prefixes, and working directory.
+ * @param options - In-memory sources and prefixes.
  * @returns The compile outcome with diagnostics, files, and sources hash.
- * @throws PragmaError with code `INVALID_INPUT` when no sources resolve.
+ * @throws PragmaError with code `INVALID_INPUT` when given no sources.
  * @throws PragmaError with code `STORE_ERROR` when the store fails to load.
  */
 export default async function compileSchema(
   options: CompileSchemaOptions,
 ): Promise<CompileSchemaResult> {
-  const files = resolveSourceFiles(options.sources, options.cwd);
+  const { sources } = options;
 
-  if (files.length === 0) {
-    throw PragmaError.invalidInput("sources", options.sources.join(", "), {
+  if (sources.length === 0) {
+    throw PragmaError.invalidInput("sources", "(empty)", {
       recovery: {
-        message: "Provide at least one existing TTL file or glob pattern.",
+        message: "Provide at least one TTL source.",
       },
     });
   }
 
-  const contents = files.map((file) => readFileSync(file, "utf-8"));
-  const sourcesHash = hashSources(contents);
+  const sourcesHash = hashSources(sources.map((source) => source.content));
+  const files = sources.map((source) => source.path ?? "inline");
 
   let store: Awaited<ReturnType<typeof createStore>>;
   try {
     store = await createStore({
-      sources: [...files],
+      sources: [...sources],
       prefixes: options.prefixes,
       cwd: options.cwd,
     });

package/src/domains/graphql/operations/createSchemaServer.test.ts

@@ -0,0 +1,50 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { EX_NAMESPACE, GRAPHQL_CLEAN_TTL } from "#testing";
+import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
+import createSchemaServer, { type SchemaServer } from "./createSchemaServer.js";
+
+const PREFIXES = { ...DEFAULT_PREFIX_MAP, ex: EX_NAMESPACE };
+
+describe("createSchemaServer", () => {
+  let server: SchemaServer | undefined;
+
+  afterEach(() => {
+    server?.dispose();
+    server = undefined;
+  });
+
+  it("compiles inline sources and serves an introspectable schema", async () => {
+    server = await createSchemaServer({
+      sources: [
+        { content: GRAPHQL_CLEAN_TTL, format: "turtle", path: "clean.ttl" },
+      ],
+      prefixes: PREFIXES,
+    });
+
+    const response = await server.handler(
+      new Request("http://localhost/graphql", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          query: "{ __schema { queryType { name } } }",
+        }),
+      }),
+    );
+
+    expect(response.status).toBe(200);
+    const body = (await response.json()) as {
+      data?: { __schema?: { queryType?: { name?: string } } };
+    };
+    expect(body.data?.__schema?.queryType?.name).toBe("Query");
+    expect(Array.isArray(server.diagnostics)).toBe(true);
+  });
+
+  it("throws a STORE_ERROR on invalid TTL", async () => {
+    await expect(
+      createSchemaServer({
+        sources: [{ content: "not turtle .", format: "turtle", path: "x.ttl" }],
+        prefixes: PREFIXES,
+      }),
+    ).rejects.toMatchObject({ code: "STORE_ERROR" });
+  });
+});

package/src/domains/graphql/operations/createSchemaServer.ts

@@ -0,0 +1,75 @@
+/**
+ * Boot a persistent ke store over in-memory TTL sources with the
+ * ke-graphql schema plugin attached, and build the `/http` fetch handler
+ * (GraphiQL + GraphQL, CORS, incremental delivery) over the compiled
+ * schema. The caller owns the returned `dispose`.
+ *
+ * @note Impure — boots a ke store (WASM + TTL) and compiles the schema.
+ */
+
+import { createStore, type InlineSource, type Plugin } from "@canonical/ke";
+import {
+  createSchemaPlugin,
+  type Diagnostic,
+  type SchemaPluginApi,
+} from "@canonical/ke-graphql";
+import { createGraphQLHandler } from "@canonical/ke-graphql/http";
+import { PragmaError } from "#error";
+
+export interface CreateSchemaServerOptions {
+  /** In-memory TTL sources to load into the store. */
+  readonly sources: readonly InlineSource[];
+  /** Prefix map handed to both the ke store and the compiler. */
+  readonly prefixes: Readonly<Record<string, string>>;
+}
+
+export interface SchemaServer {
+  /** Runtime-neutral fetch handler over the compiled schema. */
+  readonly handler: ReturnType<typeof createGraphQLHandler>;
+  /** Compiler diagnostics produced while building the schema. */
+  readonly diagnostics: readonly Diagnostic[];
+  /** Releases the underlying ke store. */
+  readonly dispose: () => void;
+}
+
+export default async function createSchemaServer(
+  options: CreateSchemaServerOptions,
+): Promise<SchemaServer> {
+  const plugin = createSchemaPlugin({ incremental: true });
+
+  let store: Awaited<ReturnType<typeof createStore>>;
+  try {
+    store = await createStore({
+      sources: [...options.sources],
+      prefixes: options.prefixes,
+      // biome-ignore lint/suspicious/noExplicitAny: Plugin generic variance
+      plugins: [plugin as Plugin<any>],
+    });
+  } catch (error) {
+    throw PragmaError.storeError(
+      error instanceof Error ? error.message : String(error),
+      { recovery: { message: "Check the TTL syntax of the sources." } },
+    );
+  }
+
+  const api = store.api<SchemaPluginApi>("ke-graphql");
+  if (!api) {
+    store.dispose();
+    throw PragmaError.storeError("ke-graphql plugin did not register its API", {
+      recovery: { message: "This is an internal error; please report it." },
+    });
+  }
+
+  const handler = createGraphQLHandler(api.schema, {
+    context: () => api.createContext(store),
+    graphiql: true,
+    cors: true,
+    incremental: true,
+  });
+
+  return {
+    handler,
+    diagnostics: api.diagnostics,
+    dispose: () => store.dispose(),
+  };
+}

package/src/domains/graphql/operations/ensureSchemaArtifact.test.ts

@@ -0,0 +1,167 @@
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { EX_NAMESPACE, GRAPHQL_CLEAN_TTL, GRAPHQL_FATAL_TTL } from "#testing";
+import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
+import type { SemanticPackage } from "../../shared/semanticPackage.js";
+import ensureSchemaArtifact, {
+  resolveSchemaArtifactPath,
+} from "./ensureSchemaArtifact.js";
+
+const PREFIXES = { ...DEFAULT_PREFIX_MAP, ex: EX_NAMESPACE };
+
+let dataDir: string;
+let cwd: string;
+let originalXdgData: string | undefined;
+
+beforeAll(() => {
+  dataDir = mkdtempSync(join(tmpdir(), "pragma-schema-artifact-data-"));
+  cwd = mkdtempSync(join(tmpdir(), "pragma-schema-artifact-cwd-"));
+  originalXdgData = process.env.XDG_DATA_HOME;
+  process.env.XDG_DATA_HOME = dataDir;
+  // The global test setup disables artifact emission; this suite tests it.
+  delete process.env.PRAGMA_SCHEMA_ARTIFACT;
+});
+
+afterAll(() => {
+  if (originalXdgData === undefined) {
+    delete process.env.XDG_DATA_HOME;
+  } else {
+    process.env.XDG_DATA_HOME = originalXdgData;
+  }
+  process.env.PRAGMA_SCHEMA_ARTIFACT = "off";
+  rmSync(dataDir, { recursive: true, force: true });
+  rmSync(cwd, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  delete process.env.PRAGMA_SCHEMA_ARTIFACT;
+  rmSync(join(dataDir, "pragma"), { recursive: true, force: true });
+});
+
+function makeRuntime(ttl: string): Parameters<typeof ensureSchemaArtifact>[0] {
+  const pkg: SemanticPackage = {
+    name: "@test/ontology",
+    version: "1.0.0",
+    source: "local",
+    graphs: [{ path: "ontology.ttl", content: ttl, format: "turtle" }],
+    skills: [],
+    stories: [],
+  };
+  return {
+    cwd,
+    packages: [pkg],
+    store: { prefixes: PREFIXES } as never,
+  };
+}
+
+describe("resolveSchemaArtifactPath", () => {
+  it("uses the XDG data dir when no project config is in tree", () => {
+    expect(resolveSchemaArtifactPath(cwd)).toBe(
+      join(dataDir, "pragma", "schema.graphql"),
+    );
+  });
+
+  it("uses .pragma/ beside the project config when one is in tree", () => {
+    const project = mkdtempSync(join(tmpdir(), "pragma-schema-project-"));
+    try {
+      writeFileSync(join(project, "pragma.config.json"), "{}", "utf-8");
+      const nested = join(project, "src");
+      mkdirSync(nested);
+      expect(resolveSchemaArtifactPath(nested)).toBe(
+        join(project, ".pragma", "schema.graphql"),
+      );
+    } finally {
+      rmSync(project, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("ensureSchemaArtifact", () => {
+  it("writes the artifact with a source-hash header on first use", async () => {
+    const result = await ensureSchemaArtifact(makeRuntime(GRAPHQL_CLEAN_TTL));
+
+    expect(result.status).toBe("written");
+    expect(existsSync(result.path)).toBe(true);
+
+    const content = readFileSync(result.path, "utf-8");
+    expect(content.startsWith("# pragma:sources ")).toBe(true);
+    expect(content).toContain("type Thing");
+  });
+
+  it("is fresh on a second run with unchanged sources", async () => {
+    const runtime = makeRuntime(GRAPHQL_CLEAN_TTL);
+    await ensureSchemaArtifact(runtime);
+
+    const second = await ensureSchemaArtifact(runtime);
+    expect(second.status).toBe("fresh");
+  });
+
+  it("rewrites when the sources change", async () => {
+    await ensureSchemaArtifact(makeRuntime(GRAPHQL_CLEAN_TTL));
+
+    const changed = await ensureSchemaArtifact(
+      makeRuntime(`${GRAPHQL_CLEAN_TTL}\n# changed`),
+    );
+    expect(changed.status).toBe("written");
+  });
+
+  it("leaves a stale artifact in place when compilation fails", async () => {
+    const first = await ensureSchemaArtifact(makeRuntime(GRAPHQL_CLEAN_TTL));
+    const before = readFileSync(first.path, "utf-8");
+
+    const failed = await ensureSchemaArtifact(makeRuntime(GRAPHQL_FATAL_TTL));
+    expect(failed.status).toBe("failed");
+    expect(readFileSync(first.path, "utf-8")).toBe(before);
+  });
+
+  it("compiles from the parseable sources when one is malformed", async () => {
+    const pkg: SemanticPackage = {
+      name: "@test/ontology",
+      version: "1.0.0",
+      source: "local",
+      graphs: [
+        { path: "clean.ttl", content: GRAPHQL_CLEAN_TTL, format: "turtle" },
+        {
+          path: "broken.ttl",
+          content: "this is not turtle .",
+          format: "turtle",
+        },
+      ],
+      skills: [],
+      stories: [],
+    };
+    const result = await ensureSchemaArtifact({
+      cwd,
+      packages: [pkg],
+      store: { prefixes: PREFIXES } as never,
+    });
+
+    expect(result.status).toBe("written");
+    expect(readFileSync(result.path, "utf-8")).toContain("type Thing");
+  });
+
+  it("skips when no sources resolve", async () => {
+    const result = await ensureSchemaArtifact({
+      cwd,
+      packages: [],
+      store: { prefixes: PREFIXES } as never,
+    });
+    expect(result.status).toBe("skipped");
+  });
+
+  it("skips when disabled via PRAGMA_SCHEMA_ARTIFACT=off", async () => {
+    process.env.PRAGMA_SCHEMA_ARTIFACT = "off";
+    const result = await ensureSchemaArtifact(makeRuntime(GRAPHQL_CLEAN_TTL));
+    expect(result.status).toBe("skipped");
+    expect(existsSync(result.path)).toBe(false);
+  });
+});

package/src/domains/graphql/operations/ensureSchemaArtifact.ts

@@ -0,0 +1,178 @@
+/**
+ * Hash-gated `schema.graphql` artifact.
+ *
+ * pragma keeps one compiled GraphQL schema per data set so downstream
+ * tooling (codegen, IDEs, `graphql serve` clients) always has a current
+ * SDL without anyone running `pragma graphql build` by hand:
+ *
+ * - **Location** — next to the project's `pragma.config.json`
+ *   (`<projectRoot>/.pragma/schema.graphql`) when one is in tree, else the
+ *   XDG data dir (`$XDG_DATA_HOME/pragma/schema.graphql`).
+ * - **Emission** — on first use of pragma (any command that boots the
+ *   runtime) the artifact is generated if missing.
+ * - **Renewal** — the artifact's first line records the hash of the TTL
+ *   sources it was compiled from (`# pragma:sources <hash>`); it is
+ *   recompiled only when the resolved sources no longer match that hash.
+ *
+ * Failure is never fatal: a schema that does not compile leaves the
+ * previous artifact in place and the boot proceeds with a warning.
+ */
+
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { createStore, definePlugin, type InlineSource } from "@canonical/ke";
+import { hashSources } from "@canonical/ke-graphql";
+import { findProjectConfigPath } from "#config";
+import { dataRoot } from "../../refs/operations/paths.js";
+import type { PragmaRuntime } from "../../shared/runtime.js";
+import compileSchema from "./compileSchema.js";
+
+/** First-line marker carrying the source fingerprint. */
+const HASH_HEADER = "# pragma:sources ";
+
+/** Environment kill-switch (CI, tests, air-gapped boots). */
+const DISABLE_ENV = "PRAGMA_SCHEMA_ARTIFACT";
+
+export interface SchemaArtifactResult {
+  /** Absolute path of the artifact. */
+  readonly path: string;
+  /**
+   * What happened: `fresh` (hash matched, nothing to do), `written`
+   * (compiled and saved), `failed` (compilation failed, artifact left
+   * as-is), `skipped` (no sources, or disabled via env).
+   */
+  readonly status: "fresh" | "written" | "failed" | "skipped";
+}
+
+/**
+ * Where the schema artifact lives for a working directory: project-local
+ * (`.pragma/` beside the nearest `pragma.config.json`) when the project is
+ * configured, global XDG data dir otherwise.
+ */
+export function resolveSchemaArtifactPath(cwd: string): string {
+  const configPath = findProjectConfigPath(cwd);
+  return configPath
+    ? join(dirname(configPath), ".pragma", "schema.graphql")
+    : join(dataRoot(), "schema.graphql");
+}
+
+/**
+ * Ensure the schema artifact exists and matches the runtime's resolved
+ * TTL sources, recompiling only on hash mismatch.
+ *
+ * @note Impure — reads and writes the artifact; compiles via a throwaway
+ *   ke store when stale.
+ */
+export default async function ensureSchemaArtifact(
+  runtime: Pick<PragmaRuntime, "cwd" | "packages" | "store">,
+): Promise<SchemaArtifactResult> {
+  const path = resolveSchemaArtifactPath(runtime.cwd);
+
+  if (process.env[DISABLE_ENV] === "off") {
+    return { path, status: "skipped" };
+  }
+
+  // Sort by provenance path so the fingerprint is stable across boots
+  // regardless of package resolution order.
+  const sources: InlineSource[] = runtime.packages
+    .flatMap((pkg) =>
+      pkg.graphs.map((graph) => ({
+        content: graph.content,
+        format: "turtle" as const,
+        path: graph.path,
+      })),
+    )
+    .sort((a, b) => a.path.localeCompare(b.path));
+
+  if (sources.length === 0) {
+    return { path, status: "skipped" };
+  }
+
+  const hash = hashSources(sources.map((source) => source.content));
+
+  if (existsSync(path) && readFirstLine(path) === `${HASH_HEADER}${hash}`) {
+    return { path, status: "fresh" };
+  }
+
+  // Mirror boot's "one bad file cannot break boot": compile from the
+  // parseable sources only. The runtime already warned about any malformed
+  // graph while booting the main store, so the filter here is silent.
+  // The fingerprint above covers ALL sources, so fixing a malformed file
+  // changes the hash and triggers recompilation.
+  const parseable = await filterParseableSources(sources);
+  if (parseable.length === 0) {
+    return { path, status: "failed" };
+  }
+
+  const outcome = await compileSchema({
+    sources: parseable,
+    prefixes: runtime.store.prefixes,
+    cwd: runtime.cwd,
+  });
+
+  if (outcome.status === "failed" || !outcome.compiled) {
+    return { path, status: "failed" };
+  }
+
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(
+    path,
+    `${HASH_HEADER}${hash}\n${outcome.compiled.sdl}`,
+    "utf-8",
+  );
+
+  return { path, status: "written" };
+}
+
+/**
+ * Read just the artifact's header line — the freshness probe runs on every
+ * booted invocation, so it must not scale with the SDL's size.
+ */
+function readFirstLine(path: string, max = 96): string {
+  const fd = openSync(path, "r");
+  try {
+    const buffer = Buffer.alloc(max);
+    const bytes = readSync(fd, buffer, 0, max, 0);
+    const text = buffer.subarray(0, bytes).toString("utf-8");
+    const newline = text.indexOf("\n");
+    return newline === -1 ? text : text.slice(0, newline);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Drop sources the Turtle parser rejects, keeping the rest — the same
+ * tolerance the main store's graph loader applies at boot. Probes with a
+ * throwaway store so the strict `graphql check` semantics of
+ * {@link compileSchema} stay untouched.
+ */
+async function filterParseableSources(
+  sources: readonly InlineSource[],
+): Promise<InlineSource[]> {
+  const parseable: InlineSource[] = [];
+  const probe = definePlugin({
+    name: "pragma-schema-artifact-probe",
+    onReady(ctx) {
+      for (const source of sources) {
+        try {
+          ctx.load(source.content, { format: source.format });
+          parseable.push(source);
+        } catch {
+          // Already warned at boot by the main store's graph loader.
+        }
+      }
+    },
+  });
+
+  const store = await createStore({ sources: [], plugins: [probe] });
+  store.dispose();
+  return parseable;
+}

package/src/domains/graphql/operations/index.ts

@@ -5,3 +5,13 @@ export type {
   CompileSchemaResult,
 } from "./compileSchema.js";
 export { default as compileSchema } from "./compileSchema.js";
+export type {
+  CreateSchemaServerOptions,
+  SchemaServer,
+} from "./createSchemaServer.js";
+export { default as createSchemaServer } from "./createSchemaServer.js";
+export type { SchemaArtifactResult } from "./ensureSchemaArtifact.js";
+export {
+  default as ensureSchemaArtifact,
+  resolveSchemaArtifactPath,
+} from "./ensureSchemaArtifact.js";

package/src/domains/info/formatters/upgrade.test.ts

@@ -8,7 +8,9 @@ import {
 
 function createUpgradeData(overrides: Partial<UpgradeData> = {}): UpgradeData {
   return {
-    pm: "bun",
+    // `pm` is the install label, which already carries the scope (as the
+    // command populates it from source.label).
+    pm: "bun (global)",
     current: "0.18.0",
     latest: "0.19.0",
     command: "bun update -g @canonical/pragma-cli",
@@ -21,9 +23,10 @@ function createUpgradeData(overrides: Partial<UpgradeData> = {}): UpgradeData {
 }
 
 describe("renderUpgradePlain", () => {
-  it("shows PM info", () => {
+  it("shows PM info without doubling the scope suffix", () => {
     const output = renderUpgradePlain(createUpgradeData());
-    expect(output).toContain("bun (global)");
+    expect(output).toContain("Installed via: bun (global)");
+    expect(output).not.toContain("(global) (global)");
   });
 
   it("shows version transition", () => {
@@ -107,7 +110,7 @@ describe("renderUpgradeJson", () => {
   it("produces valid JSON", () => {
     const data = createUpgradeData();
     const parsed = JSON.parse(renderUpgradeJson(data));
-    expect(parsed.pm).toBe("bun");
+    expect(parsed.pm).toBe("bun (global)");
     expect(parsed.current).toBe("0.18.0");
     expect(parsed.latest).toBe("0.19.0");
   });

package/src/domains/info/formatters/upgrade.ts

@@ -12,7 +12,9 @@ import type { UpgradeData } from "../types.js";
 function renderUpgradePlain(data: UpgradeData): string {
   const lines: string[] = [];
 
-  lines.push(`Installed via: ${data.pm} (global)`);
+  // `data.pm` is the install label (e.g. "bun (global)"), which already carries
+  // the scope — do not append another "(global)".
+  lines.push(`Installed via: ${data.pm}`);
 
   if (data.offline) {
     lines.push("Could not reach registry");