@canonical/pragma-cli 0.18.0

package/src/compile-validation.ts

@@ -0,0 +1,192 @@
+/**
+ * E1 WASM Embedding Validation — Compiled Binary Entry Point
+ *
+ * This file is compiled via `bun build --compile` and exercised as a
+ * standalone executable. It validates that the Oxigraph WASM module loads
+ * and queries correctly when embedded in a compiled Bun binary.
+ *
+ * Tests exercised:
+ *   1. Dynamic import of @canonical/ke (triggers WASM loading)
+ *   2. createStore() with file sources
+ *   3. SPARQL SELECT query with prefix expansion
+ *   4. sparql tagged template with branded URI interpolation
+ *   5. ASK query
+ *   6. CONSTRUCT query
+ *   7. Cache round-trip (write + re-load)
+ *
+ * @note This file is impure — it writes temp files and reads from disk.
+ * It is a build validation program, not a library module.
+ */
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+async function run() {
+  const start = performance.now();
+
+  // --- Setup temp directory with TTL data ---
+  const workDir = join(tmpdir(), `e1-validate-${Date.now()}`);
+  mkdirSync(workDir, { recursive: true });
+
+  const ttlPath = join(workDir, "people.ttl");
+  writeFileSync(
+    ttlPath,
+    `
+@prefix schema: <http://schema.org/> .
+@prefix ex: <http://example.org/> .
+
+ex:alice a schema:Person ;
+  schema:name "Alice" ;
+  schema:age 30 ;
+  schema:email "alice@example.org" .
+
+ex:bob a schema:Person ;
+  schema:name "Bob" ;
+  schema:age 25 ;
+  schema:knows ex:alice .
+
+ex:charlie a schema:Person ;
+  schema:name "Charlie" ;
+  schema:age 35 ;
+  schema:knows ex:alice, ex:bob .
+`,
+  );
+
+  const cachePath = join(workDir, ".cache", "store.nq");
+
+  // --- 1. Load ke (triggers WASM) ---
+  console.log("[validate] Loading @canonical/ke (triggers WASM)...");
+  const wasmStart = performance.now();
+  const { createStore, sparql, createNamespace } = await import(
+    "@canonical/ke"
+  );
+  console.log(
+    `[validate] WASM loaded in ${(performance.now() - wasmStart).toFixed(1)}ms`,
+  );
+
+  // --- 2. createStore from file sources ---
+  console.log("[validate] Creating store from file sources...");
+  const storeStart = performance.now();
+  const store = await createStore({
+    sources: [ttlPath],
+    prefixes: {
+      schema: "http://schema.org/",
+      ex: "http://example.org/",
+    },
+    cache: cachePath,
+  });
+  console.log(
+    `[validate] Store created in ${(performance.now() - storeStart).toFixed(1)}ms`,
+  );
+
+  // --- 3. SPARQL SELECT ---
+  console.log("[validate] Running SPARQL SELECT...");
+  const selectResult = await store.query(
+    sparql`SELECT ?name ?age WHERE { ?p a schema:Person ; schema:name ?name ; schema:age ?age . } ORDER BY ?name`,
+  );
+
+  if (selectResult.type !== "select") {
+    throw new Error(`Expected select result, got ${selectResult.type}`);
+  }
+  console.log(
+    `[validate] Query returned ${selectResult.bindings.length} bindings`,
+  );
+  for (const b of selectResult.bindings) {
+    console.log(
+      `  name=${JSON.stringify(b.name)} age=${JSON.stringify(b.age)}`,
+    );
+  }
+
+  if (selectResult.bindings.length !== 3) {
+    throw new Error(`Expected 3 bindings, got ${selectResult.bindings.length}`);
+  }
+
+  // --- 4. Branded URI interpolation ---
+  console.log("[validate] Testing branded URI interpolation...");
+  const ex = createNamespace("http://example.org/");
+  const aliceURI = ex("alice");
+  const knowsResult = await store.query(
+    sparql`SELECT ?friend WHERE { ${aliceURI} schema:knows ?friend . }`,
+  );
+  if (knowsResult.type !== "select") {
+    throw new Error(`Expected select result, got ${knowsResult.type}`);
+  }
+  console.log(
+    `[validate] Branded URI query: ${knowsResult.bindings.length} bindings`,
+  );
+
+  // --- 5. ASK query ---
+  console.log("[validate] Testing ASK query...");
+  const askResult = await store.query(sparql`ASK { ex:alice a schema:Person }`);
+  if (askResult.type !== "ask") {
+    throw new Error(`Expected ask result, got ${askResult.type}`);
+  }
+  if (!askResult.result) {
+    throw new Error("ASK should return true");
+  }
+  console.log(`[validate] ASK result: ${askResult.result}`);
+
+  // --- 6. CONSTRUCT query ---
+  console.log("[validate] Testing CONSTRUCT query...");
+  const constructResult = await store.query(
+    sparql`CONSTRUCT { ?p schema:name ?n } WHERE { ?p a schema:Person ; schema:name ?n }`,
+  );
+  if (constructResult.type !== "construct") {
+    throw new Error(`Expected construct result, got ${constructResult.type}`);
+  }
+  if (constructResult.triples.length !== 3) {
+    throw new Error(
+      `Expected 3 triples, got ${constructResult.triples.length}`,
+    );
+  }
+  console.log(
+    `[validate] CONSTRUCT returned ${constructResult.triples.length} triples`,
+  );
+
+  // --- 7. Cache round-trip ---
+  console.log("[validate] Testing cache round-trip...");
+  if (!existsSync(cachePath)) {
+    throw new Error("Cache file was not written");
+  }
+  const cacheStart = performance.now();
+  const cachedStore = await createStore({
+    sources: [ttlPath],
+    prefixes: {
+      schema: "http://schema.org/",
+      ex: "http://example.org/",
+    },
+    cache: cachePath,
+  });
+  const cacheTime = performance.now() - cacheStart;
+  console.log(`[validate] Cached store loaded in ${cacheTime.toFixed(1)}ms`);
+
+  const cachedResult = await cachedStore.query(
+    sparql`SELECT ?name WHERE { ?p a schema:Person ; schema:name ?name . } ORDER BY ?name`,
+  );
+  if (cachedResult.type !== "select") {
+    throw new Error(`Expected select result, got ${cachedResult.type}`);
+  }
+  if (cachedResult.bindings.length !== 3) {
+    throw new Error(
+      `Cached store: expected 3, got ${cachedResult.bindings.length}`,
+    );
+  }
+  console.log(
+    `[validate] Cache round-trip: ${cachedResult.bindings.length} bindings`,
+  );
+
+  // --- Cleanup ---
+  store.dispose();
+  cachedStore.dispose();
+  rmSync(workDir, { recursive: true, force: true });
+
+  const totalTime = performance.now() - start;
+  console.log(`\n[validate] Total time: ${totalTime.toFixed(1)}ms`);
+  console.log("[validate] ALL CHECKS PASSED");
+}
+
+run().catch((err) => {
+  console.error("[validate] FAILED:", err);
+  process.exit(1);
+});

package/src/completions/computeSocketPath.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import computeSocketPath from "./computeSocketPath.js";
+
+describe("computeSocketPath", () => {
+  it("returns a path starting with the socket prefix", () => {
+    const path = computeSocketPath("/home/user/project");
+    expect(path).toMatch(/^\/tmp\/pragma-completions-/);
+  });
+
+  it("returns a path ending with .sock", () => {
+    const path = computeSocketPath("/home/user/project");
+    expect(path).toMatch(/\.sock$/);
+  });
+
+  it("is deterministic — same cwd produces same path", () => {
+    const a = computeSocketPath("/home/user/project");
+    const b = computeSocketPath("/home/user/project");
+    expect(a).toBe(b);
+  });
+
+  it("produces different paths for different cwds", () => {
+    const a = computeSocketPath("/home/user/project-a");
+    const b = computeSocketPath("/home/user/project-b");
+    expect(a).not.toBe(b);
+  });
+});

package/src/completions/computeSocketPath.ts

@@ -0,0 +1,16 @@
+import { createHash } from "node:crypto";
+import { SOCKET_PREFIX } from "./constants.js";
+
+/**
+ * Compute the Unix domain socket path for a project's completions server.
+ *
+ * Derives a deterministic path from a SHA-256 hash of the working directory
+ * so each project gets its own completions server socket.
+ *
+ * @param cwd - The project working directory to hash.
+ * @returns The absolute socket file path under `/tmp/`.
+ */
+export default function computeSocketPath(cwd: string): string {
+  const hash = createHash("sha256").update(cwd).digest("hex").slice(0, 16);
+  return `${SOCKET_PREFIX}${hash}.sock`;
+}

package/src/completions/constants.ts

@@ -0,0 +1,18 @@
+/**
+ * Completions server constants.
+ *
+ * Shared by both the server (idle timeout, socket naming) and
+ * client (poll timing, spawn timeout) sides of the completions system.
+ */
+
+/** Server auto-exit timeout in milliseconds after last request. */
+export const IDLE_TIMEOUT_MS = 10_000;
+
+/** Path prefix for Unix domain socket files. */
+export const SOCKET_PREFIX = "/tmp/pragma-completions-";
+
+/** Interval between socket existence checks in milliseconds. */
+export const POLL_INTERVAL_MS = 50;
+
+/** Maximum time to wait for a spawned server to become ready. */
+export const SPAWN_TIMEOUT_MS = 5_000;

package/src/completions/handleQuery.test.ts

@@ -0,0 +1,93 @@
+import type {
+  CommandContext,
+  CommandDefinition,
+  CompletionTree,
+} from "@canonical/cli-core";
+import { buildCompleters, createExitResult } from "@canonical/cli-core";
+import { describe, expect, it } from "vitest";
+import handleQuery from "./handleQuery.js";
+
+const ctx: CommandContext = {
+  cwd: "/test",
+  globalFlags: { llm: false, format: "text", verbose: false },
+};
+
+function makeTree(): CompletionTree {
+  const commands: CommandDefinition[] = [
+    {
+      path: ["block", "list"],
+      description: "List blocks",
+      parameters: [],
+      execute: async () => createExitResult(0),
+    },
+    {
+      path: ["block", "get"],
+      description: "Get block details",
+      parameters: [
+        {
+          name: "name",
+          description: "Block name",
+          type: "string",
+          positional: true,
+          required: true,
+          complete: async (partial) => {
+            const names = ["Button", "Card", "Modal"];
+            return names.filter((n) =>
+              n.toLowerCase().startsWith(partial.toLowerCase()),
+            );
+          },
+        },
+      ],
+      execute: async () => createExitResult(0),
+    },
+    {
+      path: ["standard", "list"],
+      description: "List standards",
+      parameters: [],
+      execute: async () => createExitResult(0),
+    },
+  ];
+  return buildCompleters(commands);
+}
+
+describe("handleQuery", () => {
+  it("returns all nouns for empty input", async () => {
+    const result = await handleQuery("", makeTree(), ctx);
+    expect(result).toBe("block\nstandard");
+  });
+
+  it("returns filtered nouns for partial input", async () => {
+    const result = await handleQuery("blo", makeTree(), ctx);
+    expect(result).toBe("block");
+  });
+
+  it("returns all verbs when noun is complete with trailing space", async () => {
+    const result = await handleQuery("block ", makeTree(), ctx);
+    expect(result).toBe("get\nlist");
+  });
+
+  it("returns filtered verbs for partial verb", async () => {
+    const result = await handleQuery("block g", makeTree(), ctx);
+    expect(result).toBe("get");
+  });
+
+  it("invokes level 3 completer for argument completion", async () => {
+    const result = await handleQuery("block get Bu", makeTree(), ctx);
+    expect(result).toBe("Button");
+  });
+
+  it("returns all level 3 candidates for empty argument partial", async () => {
+    const result = await handleQuery("block get ", makeTree(), ctx);
+    expect(result).toBe("Button\nCard\nModal");
+  });
+
+  it("returns empty string for unknown noun", async () => {
+    const result = await handleQuery("unknown verb", makeTree(), ctx);
+    expect(result).toBe("");
+  });
+
+  it("returns empty string for verb with no completers", async () => {
+    const result = await handleQuery("block list something", makeTree(), ctx);
+    expect(result).toBe("");
+  });
+});

package/src/completions/handleQuery.ts

@@ -0,0 +1,30 @@
+import type { CommandContext, CompletionTree } from "@canonical/cli-core";
+import { resolveCompletion } from "@canonical/cli-core";
+
+/**
+ * Resolve a partial CLI input against a completion tree and return
+ * newline-separated candidates.
+ *
+ * Splits the partial into words, delegates to resolveCompletion for
+ * level detection (noun/verb/argument), invokes the matched completer,
+ * and joins the results with newlines. Returns an empty string when
+ * no completer matches.
+ *
+ * @param partial - The raw partial input string from the shell.
+ * @param tree - The completion tree built from registered commands.
+ * @param ctx - The command context providing store and config.
+ * @returns Newline-separated completion candidates, or empty string.
+ *
+ * @note Queries ke store
+ */
+export default async function handleQuery(
+  partial: string,
+  tree: CompletionTree,
+  ctx: CommandContext,
+): Promise<string> {
+  const words = partial.length === 0 ? [""] : partial.split(" ");
+  const result = resolveCompletion(tree, words);
+  if (!result.completer) return "";
+  const candidates = await result.completer(result.partial, ctx);
+  return candidates.join("\n");
+}

package/src/completions/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Completions server public API.
+ *
+ * Re-exports the server entry point, client entry point, socket path
+ * computation, and query handler for use by runCli and the pragma
+ * package barrel.
+ *
+ * @module
+ */
+
+export { default as computeSocketPath } from "./computeSocketPath.js";
+export { default as handleQuery } from "./handleQuery.js";
+export { default as queryCompletions } from "./queryCompletions.js";
+export { default as startCompletionsServer } from "./startCompletionsServer.js";

package/src/completions/queryCompletions.test.ts

@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const existsSyncMock = vi.fn();
+const unlinkSyncMock = vi.fn();
+const computeSocketPathMock = vi.fn(() => "/tmp/pragma-completions.sock");
+const querySocketMock = vi.fn();
+const waitForSocketMock = vi.fn();
+const spawnMock = vi.fn();
+
+vi.mock("node:fs", () => ({
+  existsSync: existsSyncMock,
+  unlinkSync: unlinkSyncMock,
+}));
+
+vi.mock("./computeSocketPath.js", () => ({
+  default: computeSocketPathMock,
+}));
+
+vi.mock("./querySocket.js", () => ({
+  default: querySocketMock,
+}));
+
+vi.mock("./waitForSocket.js", () => ({
+  default: waitForSocketMock,
+}));
+
+describe("queryCompletions", () => {
+  let stdoutSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    stdoutSpy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    vi.stubGlobal("Bun", { spawn: spawnMock });
+  });
+
+  afterEach(() => {
+    stdoutSpy.mockRestore();
+    vi.unstubAllGlobals();
+  });
+
+  it("uses an existing server and prints results", async () => {
+    existsSyncMock.mockReturnValue(true);
+    querySocketMock.mockResolvedValue("block\nstandard");
+
+    const { default: queryCompletions } = await import("./queryCompletions.js");
+    await queryCompletions("blo");
+
+    expect(querySocketMock).toHaveBeenCalledWith(
+      "/tmp/pragma-completions.sock",
+      "blo",
+    );
+    expect(stdoutSpy).toHaveBeenCalledWith("block\nstandard\n");
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it("cleans up a stale socket, spawns a server, and retries", async () => {
+    existsSyncMock.mockReturnValue(true);
+    querySocketMock
+      .mockRejectedValueOnce(new Error("stale socket"))
+      .mockResolvedValueOnce("block");
+    waitForSocketMock.mockResolvedValue(true);
+
+    const { default: queryCompletions } = await import("./queryCompletions.js");
+    await queryCompletions("blo");
+
+    expect(unlinkSyncMock).toHaveBeenCalledWith("/tmp/pragma-completions.sock");
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    expect(waitForSocketMock).toHaveBeenCalled();
+    expect(querySocketMock).toHaveBeenCalledTimes(2);
+    expect(stdoutSpy).toHaveBeenCalledWith("block\n");
+  });
+
+  it("returns silently when the spawned server never becomes ready", async () => {
+    existsSyncMock.mockReturnValue(false);
+    waitForSocketMock.mockResolvedValue(false);
+
+    const { default: queryCompletions } = await import("./queryCompletions.js");
+    await queryCompletions("blo");
+
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    expect(querySocketMock).not.toHaveBeenCalled();
+    expect(stdoutSpy).not.toHaveBeenCalled();
+  });
+
+  it("swallows post-spawn query errors and empty responses", async () => {
+    existsSyncMock.mockReturnValue(false);
+    waitForSocketMock.mockResolvedValue(true);
+    querySocketMock
+      .mockResolvedValueOnce("")
+      .mockRejectedValueOnce(new Error("boom"));
+
+    const { default: queryCompletions } = await import("./queryCompletions.js");
+    await queryCompletions("blo");
+    await queryCompletions("blo");
+
+    expect(stdoutSpy).not.toHaveBeenCalled();
+  });
+});

package/src/completions/queryCompletions.ts

@@ -0,0 +1,61 @@
+import { existsSync, unlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import computeSocketPath from "./computeSocketPath.js";
+import { SPAWN_TIMEOUT_MS } from "./constants.js";
+import querySocket from "./querySocket.js";
+import waitForSocket from "./waitForSocket.js";
+
+/**
+ * Client entry point for shell tab completion.
+ *
+ * Checks for a running completions server, spawns one if absent,
+ * connects via Unix socket, and prints candidates to stdout.
+ * Designed to be called by `pragma --completions <partial>`.
+ * Fails silently on error — shell completion must never block the terminal.
+ *
+ * @param partial - The partial CLI input to complete.
+ *
+ * @note Impure
+ */
+export default async function queryCompletions(partial: string): Promise<void> {
+  const socketPath = computeSocketPath(process.cwd());
+
+  // Try an existing server first.
+  if (existsSync(socketPath)) {
+    try {
+      const response = await querySocket(socketPath, partial);
+      if (response.length > 0) {
+        process.stdout.write(`${response}\n`);
+      }
+      return;
+    } catch {
+      // Stale socket from a crashed server — clean up and spawn fresh.
+      try {
+        unlinkSync(socketPath);
+      } catch {
+        // Socket may have been removed concurrently.
+      }
+    }
+  }
+
+  // No running server — spawn one.
+  const binPath = resolve(import.meta.dirname, "../bin.ts");
+  Bun.spawn(["bun", "run", binPath, "_completions-server"], {
+    stdio: ["ignore", "ignore", "ignore"],
+    cwd: process.cwd(),
+  });
+
+  const ready = await waitForSocket(socketPath, SPAWN_TIMEOUT_MS);
+  if (!ready) {
+    return;
+  }
+
+  try {
+    const response = await querySocket(socketPath, partial);
+    if (response.length > 0) {
+      process.stdout.write(`${response}\n`);
+    }
+  } catch {
+    // Silent — shell completion must never signal failure.
+  }
+}

package/src/completions/querySocket.test.ts

@@ -0,0 +1,70 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import querySocket from "./querySocket.js";
+
+const connectMock = vi.fn();
+
+describe("querySocket", () => {
+  beforeEach(() => {
+    vi.stubGlobal("Bun", {
+      connect: connectMock,
+    });
+    connectMock.mockReset();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("writes the partial with a newline and trims the trailing newline", async () => {
+    const write = vi.fn();
+    const flush = vi.fn();
+
+    connectMock.mockImplementation(
+      (options: {
+        socket: {
+          open: (socket: {
+            write: (value: string) => void;
+            flush: () => void;
+          }) => void;
+          data: (_socket: unknown, data: Uint8Array) => void;
+          close: () => void;
+        };
+      }) => {
+        options.socket.open({ write, flush });
+        options.socket.data({}, Buffer.from("block\n"));
+        options.socket.close();
+        return Promise.resolve({});
+      },
+    );
+
+    await expect(querySocket("/tmp/pragma.sock", "blo")).resolves.toBe("block");
+
+    expect(write).toHaveBeenCalledWith("blo\n");
+    expect(flush).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects when the socket emits an error", async () => {
+    const socketError = new Error("socket failed");
+
+    connectMock.mockImplementation(
+      (options: {
+        socket: { error: (_socket: unknown, err: Error) => void };
+      }) => {
+        options.socket.error({}, socketError);
+        return Promise.resolve({});
+      },
+    );
+
+    await expect(querySocket("/tmp/pragma.sock", "blo")).rejects.toThrow(
+      "socket failed",
+    );
+  });
+
+  it("rejects when Bun.connect fails before the socket opens", async () => {
+    connectMock.mockReturnValue(Promise.reject(new Error("connect failed")));
+
+    await expect(querySocket("/tmp/pragma.sock", "blo")).rejects.toThrow(
+      "connect failed",
+    );
+  });
+});

package/src/completions/querySocket.ts

@@ -0,0 +1,44 @@
+/**
+ * Connect to a Unix domain socket, send a partial string, and
+ * collect the response.
+ *
+ * Opens a Bun TCP connection to the socket, writes the partial
+ * terminated by a newline, and accumulates response chunks until
+ * the server closes the connection.
+ *
+ * @param socketPath - Absolute path to the Unix domain socket.
+ * @param partial - The partial CLI input to send for completion.
+ * @returns The server's response with trailing newline stripped.
+ *
+ * @note Impure
+ */
+export default function querySocket(
+  socketPath: string,
+  partial: string,
+): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    Bun.connect({
+      unix: socketPath,
+      socket: {
+        open(socket) {
+          socket.write(`${partial}\n`);
+          socket.flush();
+        },
+        data(_socket, data) {
+          chunks.push(Buffer.from(data));
+        },
+        close() {
+          resolve(
+            Buffer.concat(chunks)
+              .toString("utf-8")
+              .replace(/\r?\n$/, ""),
+          );
+        },
+        error(_socket, err) {
+          reject(err);
+        },
+      },
+    }).catch(reject);
+  });
+}