@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/compile-validation.ts

@@ -1,191 +0,0 @@
-/**
- * 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. Static 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 "./embedWasm.js";
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { createNamespace, createStore, sparql } from "@canonical/ke";
-
-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();
-  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

@@ -1,26 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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

@@ -1,25 +0,0 @@
-/**
- * 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;
-
-/**
- * Maximum time to wait for a query response before giving up. Bounds the
- * whole client call so a wedged or slow server can never hang the shell's
- * tab-completion — the query resolves to no candidates instead.
- */
-export const QUERY_TIMEOUT_MS = 3_000;

package/src/completions/handleQuery.test.ts

@@ -1,125 +0,0 @@
-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()),
-            );
-          },
-        },
-        {
-          name: "detailed",
-          description: "Show full detail",
-          type: "boolean",
-        },
-        {
-          name: "anatomyOnly",
-          description: "Show anatomy only",
-          type: "boolean",
-        },
-      ],
-      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("");
-  });
-
-  it("strips the leading program name shells forward", async () => {
-    // Every generated shell script forwards the full command line, so the
-    // program name arrives as the first word.
-    const result = await handleQuery("pragma blo", makeTree(), ctx);
-    expect(result).toBe("block");
-  });
-
-  it("lists nouns when only the program name is present", async () => {
-    const result = await handleQuery("pragma", makeTree(), ctx);
-    expect(result).toBe("block\nstandard");
-  });
-
-  it("completes verb flags when the word starts with a dash", async () => {
-    const result = await handleQuery("block get --", makeTree(), ctx);
-    expect(result).toBe("--anatomy-only\n--detailed");
-  });
-
-  it("filters verb flags by the dash-prefixed partial", async () => {
-    const result = await handleQuery("block get --d", makeTree(), ctx);
-    expect(result).toBe("--detailed");
-  });
-});

package/src/completions/handleQuery.ts

@@ -1,49 +0,0 @@
-import type { CommandContext, CompletionTree } from "@canonical/cli-core";
-import { resolveCompletion } from "@canonical/cli-core";
-import { PROGRAM_NAME } from "../constants.js";
-
-/**
- * Split a raw shell partial into completion words, dropping the leading
- * program name.
- *
- * Every generated shell script forwards the full command line — including the
- * `pragma` program name as the first word — so without this strip the resolver
- * mistakes `pragma` for the noun and returns no candidates. An empty partial
- * (first-Tab, no word yet) resolves to a single empty word so noun completion
- * still fires.
- *
- * @param partial - The raw partial input string from the shell.
- * @returns The completion words with any leading program name removed.
- */
-function splitCompletionWords(partial: string): string[] {
-  const words = partial.length === 0 ? [""] : partial.split(" ");
-  return words.at(0) === PROGRAM_NAME ? words.slice(1) : words;
-}
-
-/**
- * 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 = splitCompletionWords(partial);
-  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

@@ -1,14 +0,0 @@
-/**
- * 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

@@ -1,105 +0,0 @@
-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>;
-  const unrefMock = vi.fn();
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    stdoutSpy = vi
-      .spyOn(process.stdout, "write")
-      .mockImplementation(() => true);
-    // The spawned server handle is unref'd so the client can exit immediately.
-    spawnMock.mockReturnValue({ unref: unrefMock });
-    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);
-    // The server handle is detached so the client is not held alive by it.
-    expect(unrefMock).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

@@ -1,75 +0,0 @@
-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. Re-invoke THIS executable so completion
-  // works from the shipped binary as well as from source: when the entry file
-  // exists on disk (source run) spawn `bun run bin.ts`; otherwise (a compiled
-  // standalone binary, where bin.ts is embedded, not a file) spawn the binary
-  // itself. The old code always spawned `bun run <dir>/../bin.ts`, which does
-  // not exist inside a compiled binary, so its server never started and every
-  // completion silently returned nothing.
-  const entryPath = resolve(import.meta.dirname, "../bin.ts");
-  const spawnArgs = existsSync(entryPath)
-    ? [process.execPath, "run", entryPath, "_completions-server"]
-    : [process.execPath, "_completions-server"];
-  const server = Bun.spawn(spawnArgs, {
-    stdio: ["ignore", "ignore", "ignore"],
-    cwd: process.cwd(),
-  });
-  // Detach the server from the client's lifecycle. Without this the child keeps
-  // the client's event loop alive until the server's idle timeout (~10s) fires,
-  // so every tab-completion appears to hang for ~10s and the client tears the
-  // server down on exit — defeating the persistent-server fast path entirely.
-  server.unref();
-
-  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.
-  }
-}