@canonical/pragma-cli 0.29.0 → 0.30.0

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,8 +1,5 @@
-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,
@@ -14,60 +11,47 @@ import compileSchema from "./compileSchema.js";
 
 const PREFIXES = { ...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" });
   });

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 { PREFIX_MAP } from "../../shared/prefixes.js";
+import createSchemaServer, { type SchemaServer } from "./createSchemaServer.js";
+
+const PREFIXES = { ...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/index.ts

@@ -5,3 +5,8 @@ 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";

package/src/domains/info/operations/collectInfo.test.ts

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-const readConfigMock = vi.fn();
+const readConfigLayersMock = vi.fn();
 const detectInstallSourceMock = vi.fn();
 const bootStoreMock = vi.fn();
 const checkRegistryVersionMock = vi.fn();
@@ -8,7 +8,7 @@ const collectStoreSummaryMock = vi.fn();
 
 vi.mock("#config", async (importOriginal) => ({
   ...(await importOriginal<typeof import("#config")>()),
-  readConfig: readConfigMock,
+  readConfigLayers: readConfigLayersMock,
 }));
 
 vi.mock("#package-manager", async (importOriginal) => {
@@ -46,7 +46,18 @@ describe("collectInfo", () => {
       scope: "global",
       label: "bun (global)",
     });
-    readConfigMock.mockReturnValue({ tier: "apps/lxd", channel: "normal" });
+    readConfigLayersMock.mockReturnValue({
+      config: { tier: "apps/lxd", channel: "normal" },
+      origins: {
+        tier: "project",
+        channel: "default",
+        packages: "default",
+        trace: "default",
+        framework: "default",
+      },
+      global: { path: "/home/u/.config/pragma/config.json", exists: false },
+      project: { path: "/repo/pragma.config.json", exists: true },
+    });
   });
 
   it("includes update information and store summary when available", async () => {

package/src/domains/info/operations/collectInfo.ts

@@ -1,15 +1,14 @@
-import { readConfig } from "#config";
+import { readConfigLayers } from "#config";
 import { VERSION } from "#constants";
 import { detectInstallSource, PM_COMMANDS } from "#package-manager";
-import {
-  type PackageRef,
-  parsePackageEntry,
+import type {
+  PackageRef,
+  RawPackageEntry,
 } from "../../refs/operations/parseRef.js";
-import readGlobalRefs from "../../refs/operations/readGlobalRefs.js";
 import { bootStore } from "../../shared/bootStore.js";
 import { CHANNEL_RELEASES } from "../../shared/filters/buildChannelFilter.js";
 import { resolveTierChain } from "../../shared/filters/buildTierFilter.js";
-import { DEFAULT_PACKAGES } from "../../shared/packages.js";
+import { mergeAndParseRefs } from "../../shared/mergeAndParseRefs.js";
 import type { InfoData, PackageRefSummary } from "../types.js";
 import checkRegistryVersion from "./checkRegistryVersion.js";
 import { collectStoreSummary } from "./collectStoreSummary.js";
@@ -28,7 +27,8 @@ import { collectStoreSummary } from "./collectStoreSummary.js";
 export default async function collectInfo(cwd: string): Promise<InfoData> {
   const install = detectInstallSource();
   const pm = install.packageManager;
-  const config = readConfig(cwd);
+  const layers = readConfigLayers(cwd);
+  const config = layers.config;
   const tierChain = resolveTierChain(config.tier);
   const channelReleases = CHANNEL_RELEASES[config.channel];
 
@@ -65,7 +65,9 @@ export default async function collectInfo(cwd: string): Promise<InfoData> {
     version: VERSION,
     pm,
     installSource: install.label,
-    configPath: "pragma.config.json",
+    configPath: layers.project.exists
+      ? layers.project.path
+      : layers.global.path,
     tier: config.tier,
     tierChain,
     channel: config.channel,
@@ -78,14 +80,9 @@ export default async function collectInfo(cwd: string): Promise<InfoData> {
 }
 
 function collectPackageRefSummaries(
-  projectPackages?: ReadonlyArray<
-    string | { readonly name: string; readonly source?: string }
-  >,
+  configPackages?: ReadonlyArray<RawPackageEntry>,
 ): PackageRefSummary[] {
-  const entries = projectPackages ?? readGlobalRefs();
-  const raw = entries.length > 0 ? entries : DEFAULT_PACKAGES.map((pkg) => pkg);
-
-  return raw.map((entry) => refToSummary(parsePackageEntry(entry)));
+  return mergeAndParseRefs(configPackages).map(refToSummary);
 }
 
 function refToSummary(ref: PackageRef): PackageRefSummary {

package/src/domains/llm/capabilities.test.ts

@@ -26,10 +26,10 @@ describe("buildCapabilitiesData", () => {
     expect(data.discovery_sequence[2]?.tool).toBe("domain tools");
   });
 
-  it("includes all 29 tools from TOOL_CATALOG", () => {
+  it("includes every tool from TOOL_CATALOG", () => {
     const data = buildCapabilitiesData();
     expect(data.tools).toHaveLength(TOOL_CATALOG.length);
-    expect(data.tools).toHaveLength(29);
+    expect(data.tools).toHaveLength(30);
   });
 
   it("every tool has a non-empty use_when", () => {
@@ -41,7 +41,7 @@ describe("buildCapabilitiesData", () => {
 
   it("counts match tool catalog category lengths", () => {
     const data = buildCapabilitiesData();
-    expect(data.counts.total).toBe(29);
+    expect(data.counts.total).toBe(30);
     expect(data.counts.read).toBe(
       TOOL_CATALOG.filter((t) => t.category === "read").length,
     );
@@ -79,7 +79,7 @@ describe("buildCapabilitiesCommand", () => {
     expect(text).toContain("Discovery Sequence");
     expect(text).toContain("block_list");
     expect(text).toContain("read");
-    expect(text).toContain("29 tools");
+    expect(text).toContain("30 tools");
   });
 
   it("does not require a store or runtime", async () => {

package/src/domains/llm/data/toolCatalog.ts

@@ -100,6 +100,12 @@ export const TOOL_CATALOG: readonly ToolEntry[] = [
     category: "read",
     use_when: "Discovering agent skills provided by installed packages",
   },
+  {
+    name: "skill_lookup",
+    category: "read",
+    use_when:
+      "Loading full SKILL.md instructions for a specific agent skill by name",
+  },
   {
     name: "block_sample",
     category: "read",

package/src/domains/modifier/commands/list.ts

@@ -1,42 +1,9 @@
-/**
- * Wires the `pragma modifier list` CLI command.
- *
- * Lists all modifier families with their allowed values. Throws a
- * structured recovery error when no families are found.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { createListView } from "#tui";
+import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import { listFormatters } from "../formatters/index.js";
-import { modifierConfig } from "../modifierConfig.js";
-import { resolveModifierList } from "../orchestration/index.js";
+import { compileReadCommand } from "../../shared/stories/index.js";
+import { modifierListStory } from "../stories.js";
 
+/** Wire the `pragma modifier list` CLI command from the modifier list story. */
 export default function listCommand(ctx: PragmaContext): CommandDefinition {
-  return {
-    path: ["modifier", "list"],
-    description: "List all modifier families",
-    parameters: [],
-    meta: {
-      examples: ["pragma modifier list", "pragma modifier list --llm"],
-    },
-    async execute() {
-      const resolution = await resolveModifierList(ctx);
-
-      return createOutputResult([...resolution.items], {
-        plain: selectFormatter(ctx, listFormatters),
-        ink: (data) =>
-          createListView({
-            heading: "Modifiers",
-            domain: "modifier",
-            items: data,
-            columns: modifierConfig.listColumns,
-          }),
-      });
-    },
-  };
+  return compileReadCommand(ctx, modifierListStory);
 }