@canonical/pragma-cli 0.29.0 → 0.30.0

package/src/domains/graph/helpers/resolveUri.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import resolveUri from "./resolveUri.js";
+
+const prefixes = {
+  ds: "https://ds.canonical.com/",
+  cs: "http://pragma.canonical.com/codestandards#",
+} as const;
+
+describe("resolveUri", () => {
+  it("expands a registered prefix", () => {
+    expect(resolveUri("ds:UIBlock", prefixes)).toBe(
+      "https://ds.canonical.com/UIBlock",
+    );
+  });
+
+  it("passes through a full http(s) IRI", () => {
+    expect(resolveUri("https://ds.canonical.com/global", prefixes)).toBe(
+      "https://ds.canonical.com/global",
+    );
+  });
+
+  it("passes through a urn: IRI", () => {
+    expect(resolveUri("urn:isbn:0451450523", prefixes)).toBe(
+      "urn:isbn:0451450523",
+    );
+  });
+
+  it("passes through a foreign scheme:// IRI", () => {
+    expect(resolveUri("ftp://example.org/thing", prefixes)).toBe(
+      "ftp://example.org/thing",
+    );
+  });
+
+  it("throws for an unknown prefix", () => {
+    expect(() => resolveUri("unknown:something", prefixes)).toThrow(
+      PragmaError,
+    );
+  });
+
+  it("throws for a bare string without a prefix", () => {
+    expect(() => resolveUri("button", prefixes)).toThrow(PragmaError);
+  });
+
+  it("throws for an IRI with unsafe characters", () => {
+    expect(() =>
+      resolveUri("https://example.com/<injected>", prefixes),
+    ).toThrow(PragmaError);
+  });
+});

package/src/domains/graph/helpers/resolveUri.ts

@@ -6,12 +6,20 @@ import { PragmaError } from "#error";
  */
 const UNSAFE_IRI_PATTERN = /[<>"{}|\\^`\s]/;
 
+/**
+ * Matches a general absolute IRI: any scheme with an authority (`scheme://…`,
+ * covering http, https, ftp, ws, and foreign schemes) or a `urn:` opaque IRI.
+ * Broader than an http(s)-only check so foreign ontologies resolve.
+ */
+const ABSOLUTE_IRI_PATTERN = /^(?:[A-Za-z][A-Za-z0-9+.-]*:\/\/|urn:)\S/i;
+
 /**
  * Resolves a potentially prefixed URI (e.g. `ds:UIBlock`) to a full URI.
  *
- * If the URI is already a full URI (starts with `http`), validates IRI safety
- * and returns it as-is. Otherwise, expands the prefix using the provided
- * prefix map.
+ * A registered prefix always wins: `ds:UIBlock` expands via the prefix map.
+ * Otherwise a general absolute IRI (`scheme://…` or `urn:…`) is validated and
+ * returned as-is, so foreign ontologies are not rejected as unknown prefixes.
+ * Any other `token:rest` is treated as an unknown prefix.
  *
  * @param uri - A full or prefixed URI string.
  * @param prefixes - Registered prefix-to-namespace mapping from the store.
@@ -22,11 +30,6 @@ export default function resolveUri(
   uri: string,
   prefixes: Readonly<Record<string, string>>,
 ): string {
-  if (uri.startsWith("http://") || uri.startsWith("https://")) {
-    assertSafeIri(uri);
-    return uri;
-  }
-
   const colonIdx = uri.indexOf(":");
   if (colonIdx === -1) {
     throw PragmaError.invalidInput("uri", uri, {
@@ -38,23 +41,27 @@ export default function resolveUri(
   }
 
   const prefix = uri.slice(0, colonIdx);
-  const localName = uri.slice(colonIdx + 1);
   const namespace = prefixes[prefix];
 
-  if (namespace === undefined) {
-    throw PragmaError.invalidInput("prefix", prefix, {
-      validOptions: Object.keys(prefixes),
-      recovery: {
-        message: "List known ontology prefixes.",
-        cli: "pragma ontology list",
-        mcp: { tool: "ontology_list" },
-      },
-    });
+  if (namespace !== undefined) {
+    const resolved = `${namespace}${uri.slice(colonIdx + 1)}`;
+    assertSafeIri(resolved);
+    return resolved;
+  }
+
+  if (ABSOLUTE_IRI_PATTERN.test(uri)) {
+    assertSafeIri(uri);
+    return uri;
   }
 
-  const resolved = `${namespace}${localName}`;
-  assertSafeIri(resolved);
-  return resolved;
+  throw PragmaError.invalidInput("prefix", prefix, {
+    validOptions: Object.keys(prefixes),
+    recovery: {
+      message: "List known ontology prefixes.",
+      cli: "pragma ontology list",
+      mcp: { tool: "ontology_list" },
+    },
+  });
 }
 
 /**

package/src/domains/graphql/commands/build.test.ts

@@ -181,13 +181,15 @@ describe("graphql build command", () => {
     expect(printed).toContain("C003");
   });
 
-  it("throws structured error when sources are missing", async () => {
+  it("throws a structured error when explicit sources match nothing", async () => {
     const ctx = makeCtx();
 
-    await expect(buildCommand.execute({}, ctx)).rejects.toMatchObject({
+    await expect(
+      buildCommand.execute({ sources: ["no-such-*.ttl"] }, ctx),
+    ).rejects.toMatchObject({
       code: "INVALID_INPUT",
       recovery: {
-        message: "Provide at least one TTL file or glob pattern.",
+        message: "No files matched the given paths or glob patterns.",
       },
     });
   });

package/src/domains/graphql/commands/build.ts

@@ -7,16 +7,13 @@ import {
   createOutputResult,
 } from "@canonical/cli-core";
 import { serializeExtraction } from "@canonical/ke-graphql";
-import { PragmaError } from "#error";
 import { selectFormatter } from "../../shared/formatters.js";
+import { DEFAULT_EXTRACTION_PATH, DEFAULT_SDL_PATH } from "../constants.js";
 import { reportFormatters } from "../formatters/index.js";
-import { parsePrefixes } from "../helpers/index.js";
+import { gatherSources, parsePrefixes } from "../helpers/index.js";
 import { compileSchema } from "../operations/index.js";
 import type { GraphqlCompileReport } from "../types.js";
 
-const DEFAULT_SDL_PATH = "./schema.graphql";
-const DEFAULT_EXTRACTION_PATH = "./extraction.json";
-
 /** Narrow an unknown param to a string array. */
 function readStringArray(value: unknown): string[] {
   return Array.isArray(value)
@@ -37,10 +34,10 @@ const buildCommand: CommandDefinition = {
   parameters: [
     {
       name: "sources",
-      description: "TTL source files or glob patterns",
+      description:
+        "TTL files or globs (default: the configured semantic packages)",
       type: "multiselect",
       positional: true,
-      required: true,
     },
     {
       name: "sdl",
@@ -68,15 +65,10 @@ const buildCommand: CommandDefinition = {
     ],
   },
   async execute(params, ctx): Promise<CommandResult> {
-    const sources = readStringArray(params.sources);
-    if (sources.length === 0) {
-      throw PragmaError.invalidInput("sources", "(empty)", {
-        recovery: {
-          message: "Provide at least one TTL file or glob pattern.",
-        },
-      });
-    }
-
+    const sources = await gatherSources(
+      readStringArray(params.sources),
+      ctx.cwd,
+    );
     const prefixes = parsePrefixes(readStringArray(params.prefix));
     const outcome = await compileSchema({ sources, prefixes, cwd: ctx.cwd });
     const format = selectFormatter(ctx, reportFormatters);

package/src/domains/graphql/commands/check.test.ts

@@ -126,13 +126,15 @@ describe("graphql check command", () => {
     expect(parsed.artifacts).toBeUndefined();
   });
 
-  it("throws structured error when sources are missing", async () => {
+  it("throws a structured error when explicit sources match nothing", async () => {
     const ctx = makeCtx();
 
-    await expect(checkCommand.execute({}, ctx)).rejects.toMatchObject({
+    await expect(
+      checkCommand.execute({ sources: ["no-such-*.ttl"] }, ctx),
+    ).rejects.toMatchObject({
       code: "INVALID_INPUT",
       recovery: {
-        message: "Provide at least one TTL file or glob pattern.",
+        message: "No files matched the given paths or glob patterns.",
       },
     });
   });

package/src/domains/graphql/commands/check.ts

@@ -4,10 +4,9 @@ import {
   createExitResult,
   createOutputResult,
 } from "@canonical/cli-core";
-import { PragmaError } from "#error";
 import { selectFormatter } from "../../shared/formatters.js";
 import { reportFormatters } from "../formatters/index.js";
-import { parsePrefixes } from "../helpers/index.js";
+import { gatherSources, parsePrefixes } from "../helpers/index.js";
 import { compileSchema } from "../operations/index.js";
 import type { GraphqlCompileReport } from "../types.js";
 
@@ -31,10 +30,10 @@ const checkCommand: CommandDefinition = {
   parameters: [
     {
       name: "sources",
-      description: "TTL source files or glob patterns",
+      description:
+        "TTL files or globs (default: the configured semantic packages)",
       type: "multiselect",
       positional: true,
-      required: true,
     },
     {
       name: "prefix",
@@ -49,15 +48,10 @@ const checkCommand: CommandDefinition = {
     ],
   },
   async execute(params, ctx): Promise<CommandResult> {
-    const sources = readStringArray(params.sources);
-    if (sources.length === 0) {
-      throw PragmaError.invalidInput("sources", "(empty)", {
-        recovery: {
-          message: "Provide at least one TTL file or glob pattern.",
-        },
-      });
-    }
-
+    const sources = await gatherSources(
+      readStringArray(params.sources),
+      ctx.cwd,
+    );
     const prefixes = parsePrefixes(readStringArray(params.prefix));
     const outcome = await compileSchema({ sources, prefixes, cwd: ctx.cwd });
 

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

@@ -2,3 +2,4 @@
 
 export { default as buildCommand } from "./build.js";
 export { default as checkCommand } from "./check.js";
+export { default as serveCommand } from "./serve.js";

package/src/domains/graphql/commands/serve.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, describe, expect, it } from "vitest";
+import type { PragmaContext } from "../../shared/context.js";
+import serveCommand, { readPort } from "./serve.js";
+
+describe("readPort", () => {
+  it("parses a valid port", () => {
+    expect(readPort("4001")).toBe(4001);
+  });
+
+  it("falls back to the default for non-string values", () => {
+    expect(readPort(undefined)).toBe(4000);
+    expect(readPort(4001)).toBe(4000);
+  });
+
+  it("falls back to the default for out-of-range or unparseable values", () => {
+    expect(readPort("0")).toBe(4000);
+    expect(readPort("70000")).toBe(4000);
+    expect(readPort("not-a-port")).toBe(4000);
+  });
+});
+
+describe("graphql serve command", () => {
+  const ctx = { cwd: process.cwd() } as PragmaContext;
+  const original = (globalThis as Record<string, unknown>).Bun;
+
+  afterEach(() => {
+    (globalThis as Record<string, unknown>).Bun = original;
+  });
+
+  it("requires the Bun runtime", async () => {
+    (globalThis as Record<string, unknown>).Bun = undefined;
+
+    await expect(serveCommand.execute({}, ctx)).rejects.toMatchObject({
+      code: "STORE_ERROR",
+      recovery: {
+        message: "Run the compiled `pragma` binary or use `bun run`.",
+      },
+    });
+  });
+});

package/src/domains/graphql/commands/serve.ts

@@ -0,0 +1,131 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { PragmaError } from "#error";
+import { DEFAULT_PORT } from "../constants.js";
+import { gatherSources, parsePrefixes } from "../helpers/index.js";
+import routeGraphql from "../helpers/routeGraphql.js";
+import createSchemaServer, {
+  type SchemaServer,
+} from "../operations/createSchemaServer.js";
+
+/** Narrow an unknown param to a string array. */
+function readStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+/** Parse the --port flag, falling back to the default on anything invalid. */
+export function readPort(value: unknown): number {
+  if (typeof value !== "string") {
+    return DEFAULT_PORT;
+  }
+  const port = Number.parseInt(value, 10);
+  return Number.isInteger(port) && port > 0 && port < 65536
+    ? port
+    : DEFAULT_PORT;
+}
+
+/**
+ * Listen on `port` and block until the process is interrupted, then stop
+ * the server and dispose the store.
+ *
+ * @note Impure — opens a network listener and registers signal handlers.
+ */
+/* v8 ignore start -- the live Bun.serve listener and signal loop run under `pragma graphql serve`, not unit tests */
+async function listen(server: SchemaServer, port: number): Promise<void> {
+  const httpServer = Bun.serve({
+    port,
+    fetch: (request) => routeGraphql(request, server.handler, port),
+  });
+  await new Promise<void>((resolve) => {
+    const shutdown = (): void => {
+      httpServer.stop();
+      server.dispose();
+      resolve();
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+  });
+}
+/* v8 ignore stop */
+
+/**
+ * Builds the `pragma graphql serve` command definition.
+ *
+ * Compiles the configured ontologies (or explicit TTL sources) and serves
+ * a local GraphQL + GraphiQL endpoint until interrupted. With no positional
+ * sources it serves every TTL across the semantic packages in
+ * `pragma.config.json`.
+ */
+const serveCommand: CommandDefinition = {
+  path: ["graphql", "serve"],
+  description:
+    "Serve a local GraphQL + GraphiQL endpoint over the configured ontologies",
+  parameters: [
+    {
+      name: "sources",
+      description:
+        "TTL files or globs to serve (default: the configured semantic packages)",
+      type: "multiselect",
+      positional: true,
+    },
+    {
+      name: "port",
+      description: `Port to listen on (default ${DEFAULT_PORT})`,
+      type: "string",
+    },
+    {
+      name: "prefix",
+      description: "Ontology prefix as name=namespace (repeatable)",
+      type: "multiselect",
+    },
+  ],
+  meta: {
+    examples: [
+      "pragma graphql serve",
+      "pragma graphql serve ontology.ttl --port 4001",
+    ],
+  },
+  async execute(params, ctx): Promise<CommandResult> {
+    if (typeof Bun === "undefined") {
+      throw PragmaError.storeError(
+        "`pragma graphql serve` requires the Bun runtime.",
+        {
+          recovery: {
+            message: "Run the compiled `pragma` binary or use `bun run`.",
+          },
+        },
+      );
+    }
+
+    const sources = await gatherSources(
+      readStringArray(params.sources),
+      ctx.cwd,
+    );
+    const prefixes = parsePrefixes(readStringArray(params.prefix));
+    const port = readPort(params.port);
+
+    const server = await createSchemaServer({ sources, prefixes });
+    const errorCount = server.diagnostics.filter(
+      (d) => d.severity === "error",
+    ).length;
+    process.stdout.write(
+      `[ke-graphql] schema compiled — ${server.diagnostics.length} diagnostic(s)${
+        errorCount > 0 ? `, ${errorCount} error(s)` : ""
+      }\n[ke-graphql] GraphiQL on http://localhost:${port}/graphql (Ctrl-C to stop)\n`,
+    );
+
+    await listen(server, port);
+
+    return createOutputResult(
+      { port, diagnostics: server.diagnostics },
+      { plain: () => `Stopped the graphql server on port ${port}.` },
+    );
+  },
+};
+
+export default serveCommand;

package/src/domains/graphql/constants.ts

@@ -0,0 +1,10 @@
+/** Default port `pragma graphql serve` listens on. */
+const DEFAULT_PORT = 4000;
+
+/** Default output path for the SDL written by `pragma graphql build`. */
+const DEFAULT_SDL_PATH = "./schema.graphql";
+
+/** Default output path for the extraction artifact written by `pragma graphql build`. */
+const DEFAULT_EXTRACTION_PATH = "./extraction.json";
+
+export { DEFAULT_EXTRACTION_PATH, DEFAULT_PORT, DEFAULT_SDL_PATH };

package/src/domains/graphql/helpers/gatherSources.test.ts

@@ -0,0 +1,92 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { GRAPHQL_CLEAN_TTL } from "#testing";
+import resolveConfiguredGraphs from "../../shared/resolveConfiguredGraphs.js";
+import gatherSources from "./gatherSources.js";
+
+vi.mock("../../shared/resolveConfiguredGraphs.js", () => ({
+  default: vi.fn(),
+}));
+
+const mockResolve = vi.mocked(resolveConfiguredGraphs);
+
+describe("gatherSources", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-gather-"));
+    writeFileSync(join(dir, "a.ttl"), GRAPHQL_CLEAN_TTL);
+    writeFileSync(join(dir, "b.ttl"), GRAPHQL_CLEAN_TTL);
+    mockResolve.mockReset();
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("reads explicit files into inline sources, ignoring the config", async () => {
+    const sources = await gatherSources(["a.ttl"], dir);
+
+    expect(sources).toEqual([
+      {
+        content: GRAPHQL_CLEAN_TTL,
+        format: "turtle",
+        path: join(dir, "a.ttl"),
+      },
+    ]);
+    expect(mockResolve).not.toHaveBeenCalled();
+  });
+
+  it("expands glob patterns", async () => {
+    const sources = await gatherSources(["*.ttl"], dir);
+
+    expect(sources.map((source) => source.path).sort()).toEqual([
+      join(dir, "a.ttl"),
+      join(dir, "b.ttl"),
+    ]);
+  });
+
+  it("throws when explicit sources match nothing", async () => {
+    await expect(gatherSources(["none-*.ttl"], dir)).rejects.toMatchObject({
+      code: "INVALID_INPUT",
+      recovery: {
+        message: "No files matched the given paths or glob patterns.",
+      },
+    });
+  });
+
+  it("falls back to the configured package graphs when no sources are given", async () => {
+    mockResolve.mockResolvedValue([
+      {
+        path: "definitions/ontology.ttl",
+        content: GRAPHQL_CLEAN_TTL,
+        format: "turtle",
+      },
+    ]);
+
+    const sources = await gatherSources([], dir);
+
+    expect(mockResolve).toHaveBeenCalledWith(dir);
+    expect(sources).toEqual([
+      {
+        content: GRAPHQL_CLEAN_TTL,
+        format: "turtle",
+        path: "definitions/ontology.ttl",
+      },
+    ]);
+  });
+
+  it("throws when no sources are given and no packages resolve", async () => {
+    mockResolve.mockResolvedValue([]);
+
+    await expect(gatherSources([], dir)).rejects.toMatchObject({
+      code: "INVALID_INPUT",
+      recovery: {
+        message:
+          "No TTL sources given and no semantic packages resolved. Pass TTL files or globs, or configure `packages` in pragma.config.json and install them.",
+      },
+    });
+  });
+});

package/src/domains/graphql/helpers/gatherSources.ts

@@ -0,0 +1,58 @@
+/**
+ * Resolve the TTL sources for a graphql command.
+ *
+ * When positional paths or globs are given they win; otherwise the sources
+ * are the union of every configured semantic package's graphs (the
+ * `pragma.config.json` packages, falling back to the defaults). Either way
+ * the result is a list of ke `InlineSource`s (content + provenance path),
+ * so the compiler and the dev server load the exact same bytes.
+ *
+ * @note Impure — reads files and resolves packages from disk.
+ *
+ * @param positional - Explicit TTL file paths or glob patterns (may be empty).
+ * @param cwd - Working directory for file and config resolution.
+ * @returns In-memory TTL sources to compile or serve.
+ * @throws PragmaError (INVALID_INPUT) when nothing resolves.
+ */
+
+import { readFileSync } from "node:fs";
+import type { InlineSource } from "@canonical/ke";
+import { PragmaError } from "#error";
+import resolveConfiguredGraphs from "../../shared/resolveConfiguredGraphs.js";
+import resolveSourceFiles from "./resolveSourceFiles.js";
+
+export default async function gatherSources(
+  positional: readonly string[],
+  cwd: string,
+): Promise<InlineSource[]> {
+  if (positional.length > 0) {
+    const files = resolveSourceFiles([...positional], cwd);
+    if (files.length === 0) {
+      throw PragmaError.invalidInput("sources", positional.join(", "), {
+        recovery: {
+          message: "No files matched the given paths or glob patterns.",
+        },
+      });
+    }
+    return files.map((path) => ({
+      content: readFileSync(path, "utf-8"),
+      format: "turtle" as const,
+      path,
+    }));
+  }
+
+  const graphs = await resolveConfiguredGraphs(cwd);
+  if (graphs.length === 0) {
+    throw PragmaError.invalidInput("sources", "(none)", {
+      recovery: {
+        message:
+          "No TTL sources given and no semantic packages resolved. Pass TTL files or globs, or configure `packages` in pragma.config.json and install them.",
+      },
+    });
+  }
+  return graphs.map((graph) => ({
+    content: graph.content,
+    format: graph.format,
+    path: graph.path,
+  }));
+}

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

@@ -1,4 +1,6 @@
 /** @module Barrel for graphql helpers. */
 
+export { default as gatherSources } from "./gatherSources.js";
 export { default as parsePrefixes } from "./parsePrefixes.js";
 export { default as resolveSourceFiles } from "./resolveSourceFiles.js";
+export { default as routeGraphql } from "./routeGraphql.js";

package/src/domains/graphql/helpers/routeGraphql.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it, vi } from "vitest";
+import routeGraphql from "./routeGraphql.js";
+
+describe("routeGraphql", () => {
+  it("delegates /graphql to the handler", async () => {
+    const handler = vi.fn(() => new Response("handled"));
+    const request = new Request("http://localhost:4000/graphql");
+
+    const response = await routeGraphql(request, handler, 4000);
+
+    expect(handler).toHaveBeenCalledWith(request);
+    expect(await response.text()).toBe("handled");
+  });
+
+  it("redirects / to /graphql", async () => {
+    const handler = vi.fn();
+
+    const response = await routeGraphql(
+      new Request("http://localhost:4000/"),
+      handler,
+      4000,
+    );
+
+    expect(response.status).toBe(302);
+    expect(response.headers.get("location")).toBe(
+      "http://localhost:4000/graphql",
+    );
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("404s any other path", async () => {
+    const handler = vi.fn();
+
+    const response = await routeGraphql(
+      new Request("http://localhost:4000/favicon.ico"),
+      handler,
+      4000,
+    );
+
+    expect(response.status).toBe(404);
+    expect(handler).not.toHaveBeenCalled();
+  });
+});