@canonical/pragma-cli 0.29.0 → 0.31.0

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

@@ -0,0 +1,141 @@
+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. A missing flag uses the default; a provided value
+ * must be a valid port (1–65535), otherwise it is rejected rather than
+ * silently falling back and masking the user's mistake.
+ *
+ * @throws PragmaError INVALID_INPUT when a provided `--port` is not a valid port.
+ */
+export function readPort(value: unknown): number {
+  if (value === undefined || value === null || value === "") {
+    return DEFAULT_PORT;
+  }
+  const text = String(value).trim();
+  const port = Number(text);
+  if (!/^\d+$/.test(text) || port < 1 || port > 65535) {
+    throw PragmaError.invalidInput("port", String(value), {
+      recovery: { message: "Provide a port between 1 and 65535." },
+    });
+  }
+  return 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/parsePrefixes.test.ts

@@ -1,17 +1,17 @@
 import { describe, expect, it } from "vitest";
-import { PREFIX_MAP } from "../../shared/prefixes.js";
+import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
 import parsePrefixes from "./parsePrefixes.js";
 
 describe("parsePrefixes", () => {
   it("returns the default prefix map for no entries", () => {
     const prefixes = parsePrefixes([]);
-    expect(prefixes).toEqual(PREFIX_MAP);
+    expect(prefixes).toEqual(DEFAULT_PREFIX_MAP);
   });
 
   it("merges entries on top of the defaults", () => {
     const prefixes = parsePrefixes(["ex=http://example.org/"]);
     expect(prefixes.ex).toBe("http://example.org/");
-    expect(prefixes.ds).toBe(PREFIX_MAP.ds);
+    expect(prefixes.ds).toBe(DEFAULT_PREFIX_MAP.ds);
   });
 
   it("lets entries override default prefixes", () => {

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

@@ -1,11 +1,11 @@
 import { PragmaError } from "#error";
-import { PREFIX_MAP } from "../../shared/prefixes.js";
+import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
 
 /**
  * Parse repeated `--prefix name=namespace` entries into a prefix map.
  *
  * User-supplied prefixes are merged on top of pragma's default
- * {@link PREFIX_MAP}, so `ds:` and the W3C vocabularies stay available
+ * {@link DEFAULT_PREFIX_MAP}, so `ds:` and the W3C vocabularies stay available
  * unless explicitly overridden.
  *
  * @param entries - Raw `name=namespace` strings from the CLI.
@@ -15,7 +15,7 @@ import { PREFIX_MAP } from "../../shared/prefixes.js";
 export default function parsePrefixes(
   entries: readonly string[],
 ): Record<string, string> {
-  const prefixes: Record<string, string> = { ...PREFIX_MAP };
+  const prefixes: Record<string, string> = { ...DEFAULT_PREFIX_MAP };
 
   for (const entry of entries) {
     const separator = entry.indexOf("=");

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

@@ -53,4 +53,13 @@ describe("resolveSourceFiles", () => {
     const files = resolveSourceFiles(["b.ttl", "nested/*.ttl"], dir);
     expect(files).toEqual([join(dir, "b.ttl"), join(dir, "nested", "c.ttl")]);
   });
+
+  it("skips a directory path instead of treating it as a file", () => {
+    // A directory would later crash readFileSync with EISDIR.
+    expect(resolveSourceFiles(["nested"], dir)).toEqual([]);
+  });
+
+  it("resolves the empty string (the cwd directory) to no files", () => {
+    expect(resolveSourceFiles([""], dir)).toEqual([]);
+  });
 });

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

@@ -8,9 +8,27 @@
  * @note Impure — reads filesystem to expand globs and check existence.
  */
 
-import { existsSync, globSync } from "node:fs";
+import { globSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 
+/**
+ * Whether a path points at an existing regular file.
+ *
+ * Guards against a directory (or the empty-string path, which resolves to the
+ * cwd directory) slipping through as a "source" and later crashing readFileSync
+ * with EISDIR.
+ *
+ * @param absPath - Absolute path to check.
+ * @returns True when the path exists and is a regular file.
+ */
+function isRegularFile(absPath: string): boolean {
+  try {
+    return statSync(absPath).isFile();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Expand file paths and glob patterns into absolute file paths.
  *
@@ -31,11 +49,14 @@ export default function resolveSourceFiles(
       pattern.includes("[")
     ) {
       for (const file of globSync(pattern, { cwd })) {
-        files.push(resolve(cwd, file));
+        const absPath = resolve(cwd, file);
+        if (isRegularFile(absPath)) {
+          files.push(absPath);
+        }
       }
     } else {
       const absPath = resolve(cwd, pattern);
-      if (existsSync(absPath)) {
+      if (isRegularFile(absPath)) {
         files.push(absPath);
       }
     }

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();
+  });
+});

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

@@ -0,0 +1,28 @@
+/**
+ * Route an incoming request for the graphql dev server: `/graphql` to the
+ * GraphQL + GraphiQL handler, `/` to a redirect there, and everything else
+ * to 404. Mounting is intentionally the host's job, which keeps the handler
+ * itself path-agnostic.
+ *
+ * @param request - The incoming fetch Request.
+ * @param handler - The GraphQL fetch handler for `/graphql`.
+ * @param port - The listen port, used to build the root redirect target.
+ * @returns The response (or a promise of one) for the route.
+ */
+
+type GraphQLHandler = (request: Request) => Response | Promise<Response>;
+
+export default function routeGraphql(
+  request: Request,
+  handler: GraphQLHandler,
+  port: number,
+): Response | Promise<Response> {
+  const { pathname } = new URL(request.url);
+  if (pathname === "/graphql") {
+    return handler(request);
+  }
+  if (pathname === "/") {
+    return Response.redirect(`http://localhost:${port}/graphql`, 302);
+  }
+  return new Response(null, { status: 404 });
+}

package/src/domains/graphql/index.ts

@@ -1,21 +1,24 @@
 /**
  * @module GraphQL domain barrel.
  *
- * Compiles TTL ontologies into GraphQL schema artifacts via the
- * ke-graphql pipeline. Commands boot their own ke store from explicit
- * TTL sources, so they run on the store-skip pipeline path.
+ * Compiles TTL ontologies into GraphQL schema artifacts via the ke-graphql
+ * pipeline, and serves them locally. Commands boot their own ke store —
+ * from explicit TTL sources or, when none are given, the semantic packages
+ * configured in `pragma.config.json` — so they run on the store-skip
+ * pipeline path.
  */
 
 import type { CommandDefinition } from "@canonical/cli-core";
-import { buildCommand, checkCommand } from "./commands/index.js";
+import { buildCommand, checkCommand, serveCommand } from "./commands/index.js";
 
 /**
  * Returns all command definitions for the graphql domain.
  *
- * @returns An array of command definitions (`graphql build`, `graphql check`).
+ * @returns The `graphql build`, `graphql check`, and `graphql serve`
+ *   command definitions.
  */
 export function commands(): CommandDefinition[] {
-  return [buildCommand, checkCommand];
+  return [buildCommand, checkCommand, serveCommand];
 }
 
 export { compileSchema } from "./operations/index.js";

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

@@ -1,73 +1,57 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { hashSources } from "@canonical/ke-graphql";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { describe, expect, it } from "vitest";
 import {
   EX_NAMESPACE,
   GRAPHQL_CLEAN_TTL,
   GRAPHQL_ERROR_TTL,
   GRAPHQL_FATAL_TTL,
 } from "#testing";
-import { PREFIX_MAP } from "../../shared/prefixes.js";
+import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
 import compileSchema from "./compileSchema.js";
 
-const PREFIXES = { ...PREFIX_MAP, ex: EX_NAMESPACE };
+const PREFIXES = { ...DEFAULT_PREFIX_MAP, ex: EX_NAMESPACE };
 
-describe("compileSchema", () => {
-  let dir: string;
-
-  beforeEach(() => {
-    dir = mkdtempSync(join(tmpdir(), "pragma-graphql-compile-"));
-    writeFileSync(join(dir, "clean.ttl"), GRAPHQL_CLEAN_TTL);
-    writeFileSync(join(dir, "error.ttl"), GRAPHQL_ERROR_TTL);
-    writeFileSync(join(dir, "fatal.ttl"), GRAPHQL_FATAL_TTL);
-  });
-
-  afterEach(() => {
-    rmSync(dir, { recursive: true, force: true });
-  });
+const inline = (content: string, path: string) => ({
+  content,
+  format: "turtle" as const,
+  path,
+});
 
+describe("compileSchema", () => {
   it("compiles a clean ontology into SDL", async () => {
     const outcome = await compileSchema({
-      sources: ["clean.ttl"],
+      sources: [inline(GRAPHQL_CLEAN_TTL, "clean.ttl")],
       prefixes: PREFIXES,
-      cwd: dir,
     });
 
     expect(outcome.status).toBe("ok");
     expect(outcome.compiled?.sdl).toContain("type Thing");
     expect(outcome.diagnostics).toEqual([]);
-    expect(outcome.files).toEqual([join(dir, "clean.ttl")]);
+    expect(outcome.files).toEqual(["clean.ttl"]);
   });
 
-  it("hashes the exact raw file contents", async () => {
+  it("hashes the exact raw source contents", async () => {
     const outcome = await compileSchema({
-      sources: ["clean.ttl"],
+      sources: [inline(GRAPHQL_CLEAN_TTL, "clean.ttl")],
       prefixes: PREFIXES,
-      cwd: dir,
     });
 
-    const raw = readFileSync(join(dir, "clean.ttl"), "utf-8");
-    expect(outcome.sourcesHash).toBe(hashSources([raw]));
+    expect(outcome.sourcesHash).toBe(hashSources([GRAPHQL_CLEAN_TTL]));
   });
 
-  it("resolves glob patterns to source files", async () => {
+  it("labels a source without a path as 'inline'", async () => {
     const outcome = await compileSchema({
-      sources: ["clean*.ttl"],
+      sources: [{ content: GRAPHQL_CLEAN_TTL, format: "turtle" }],
       prefixes: PREFIXES,
-      cwd: dir,
     });
 
-    expect(outcome.status).toBe("ok");
-    expect(outcome.files).toEqual([join(dir, "clean.ttl")]);
+    expect(outcome.files).toEqual(["inline"]);
   });
 
   it("surfaces error diagnostics without failing the compile", async () => {
     const outcome = await compileSchema({
-      sources: ["error.ttl"],
+      sources: [inline(GRAPHQL_ERROR_TTL, "error.ttl")],
       prefixes: PREFIXES,
-      cwd: dir,
     });
 
     expect(outcome.status).toBe("ok");
@@ -81,9 +65,8 @@ describe("compileSchema", () => {
 
   it("converts CompilationError into a failed result with diagnostics", async () => {
     const outcome = await compileSchema({
-      sources: ["fatal.ttl"],
+      sources: [inline(GRAPHQL_FATAL_TTL, "fatal.ttl")],
       prefixes: PREFIXES,
-      cwd: dir,
     });
 
     expect(outcome.status).toBe("failed");
@@ -95,24 +78,17 @@ describe("compileSchema", () => {
     ).toBe(true);
   });
 
-  it("throws structured error when no sources resolve", async () => {
+  it("throws a structured error when given no sources", async () => {
     await expect(
-      compileSchema({
-        sources: ["missing.ttl"],
-        prefixes: PREFIXES,
-        cwd: dir,
-      }),
+      compileSchema({ sources: [], prefixes: PREFIXES }),
     ).rejects.toMatchObject({ code: "INVALID_INPUT" });
   });
 
-  it("throws structured error on invalid TTL syntax", async () => {
-    writeFileSync(join(dir, "broken.ttl"), "this is not turtle .");
-
+  it("throws a structured error on invalid TTL syntax", async () => {
     await expect(
       compileSchema({
-        sources: ["broken.ttl"],
+        sources: [inline("this is not turtle .", "broken.ttl")],
         prefixes: PREFIXES,
-        cwd: dir,
       }),
     ).rejects.toMatchObject({ code: "STORE_ERROR" });
   });