@canonical/pragma-cli 0.31.0 → 0.33.0

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.
-  }
-}

package/src/completions/querySocket.test.ts

@@ -1,101 +0,0 @@
-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",
-    );
-  });
-
-  it("times out and closes the socket when the server never replies", async () => {
-    vi.useFakeTimers();
-    const end = vi.fn();
-
-    connectMock.mockImplementation(
-      (options: {
-        socket: {
-          open: (socket: {
-            write: () => void;
-            flush: () => void;
-            end: () => void;
-          }) => void;
-        };
-      }) => {
-        // Open but never send data or close — simulate a wedged server.
-        options.socket.open({ write: () => {}, flush: () => {}, end });
-        return Promise.resolve({});
-      },
-    );
-
-    try {
-      const promise = querySocket("/tmp/pragma.sock", "blo");
-      const assertion = expect(promise).rejects.toThrow(/timed out/);
-      await vi.advanceTimersByTimeAsync(5000);
-      await assertion;
-      expect(end).toHaveBeenCalledTimes(1);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-});

package/src/completions/querySocket.ts

@@ -1,71 +0,0 @@
-import { QUERY_TIMEOUT_MS } from "./constants.js";
-
-/**
- * Connect to a Unix domain socket, send a partial string, and
- * collect the response.
- *
- * Opens a Bun connection to the socket, writes the partial terminated by a
- * newline, and accumulates response chunks until the server closes the
- * connection. The whole exchange is bounded by {@link QUERY_TIMEOUT_MS}: if a
- * wedged or slow server never replies, the promise rejects rather than hanging
- * the shell's tab-completion indefinitely.
- *
- * @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[] = [];
-    let settled = false;
-    let openSocket: { end: () => void } | undefined;
-
-    const timer = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      // Close the connection so a hung server does not leak an open socket.
-      openSocket?.end();
-      reject(
-        new Error(`Completion query timed out after ${QUERY_TIMEOUT_MS}ms`),
-      );
-    }, QUERY_TIMEOUT_MS);
-
-    const settle = (run: () => void): void => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      run();
-    };
-
-    Bun.connect({
-      unix: socketPath,
-      socket: {
-        open(socket) {
-          openSocket = socket;
-          socket.write(`${partial}\n`);
-          socket.flush();
-        },
-        data(_socket, data) {
-          chunks.push(Buffer.from(data));
-        },
-        close() {
-          settle(() =>
-            resolve(
-              Buffer.concat(chunks)
-                .toString("utf-8")
-                .replace(/\r?\n$/, ""),
-            ),
-          );
-        },
-        error(_socket, err) {
-          settle(() => reject(err));
-        },
-      },
-    }).catch((err) => settle(() => reject(err)));
-  });
-}

package/src/completions/startCompletionsServer.test.ts

@@ -1,74 +0,0 @@
-import { spawn } from "node:child_process";
-import { unlinkSync } from "node:fs";
-import { resolve } from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import computeSocketPath from "./computeSocketPath.js";
-import waitForSocket from "./waitForSocket.js";
-
-const hasBun = typeof globalThis.Bun !== "undefined";
-
-const BIN_PATH = resolve(import.meta.dirname, "../bin.ts");
-const cwd = process.cwd();
-const socketPath = computeSocketPath(cwd);
-
-function cleanSocket(): void {
-  try {
-    unlinkSync(socketPath);
-  } catch {
-    // May not exist.
-  }
-}
-
-afterEach(() => {
-  cleanSocket();
-});
-
-describe.skipIf(!hasBun)("startCompletionsServer", () => {
-  it("starts, accepts a query, and returns noun completions", async () => {
-    cleanSocket();
-
-    const { default: querySocket } = await import("./querySocket.js");
-
-    const server = spawn("bun", ["run", BIN_PATH, "_completions-server"], {
-      stdio: "ignore",
-      cwd,
-      detached: true,
-    });
-
-    try {
-      const ready = await waitForSocket(socketPath, 10_000);
-      expect(ready).toBe(true);
-
-      const result = await querySocket(socketPath, "");
-      expect(result).toContain("component");
-      expect(result).toContain("standard");
-    } finally {
-      server.kill();
-      cleanSocket();
-    }
-  }, 15_000);
-
-  it("returns verb completions for a noun with trailing space", async () => {
-    cleanSocket();
-
-    const { default: querySocket } = await import("./querySocket.js");
-
-    const server = spawn("bun", ["run", BIN_PATH, "_completions-server"], {
-      stdio: "ignore",
-      cwd,
-      detached: true,
-    });
-
-    try {
-      const ready = await waitForSocket(socketPath, 10_000);
-      expect(ready).toBe(true);
-
-      const result = await querySocket(socketPath, "component ");
-      expect(result).toContain("list");
-      expect(result).toContain("get");
-    } finally {
-      server.kill();
-      cleanSocket();
-    }
-  }, 15_000);
-});

package/src/completions/startCompletionsServer.ts

@@ -1,75 +0,0 @@
-import { existsSync, unlinkSync } from "node:fs";
-import type { GlobalFlags } from "@canonical/cli-core";
-import { buildCompleters } from "@canonical/cli-core";
-import type { PragmaContext } from "../domains/shared/context.js";
-import type { PragmaRuntime } from "../domains/shared/runtime.js";
-import { bootPragma } from "../domains/shared/runtime.js";
-import collectCommands from "../pipeline/collectCommands.js";
-import computeSocketPath from "./computeSocketPath.js";
-import { IDLE_TIMEOUT_MS } from "./constants.js";
-import handleQuery from "./handleQuery.js";
-
-const COMPLETIONS_FLAGS: GlobalFlags = {
-  llm: false,
-  format: "text",
-  verbose: false,
-};
-
-/**
- * Boot a ke-backed completions server on a Unix domain socket.
- *
- * Uses `bootPragma()` for unified store + config initialization, builds
- * the completion tree from all registered commands, and listens on a
- * project-scoped Unix domain socket. Auto-exits after 10 seconds of idle.
- *
- * @note Impure
- */
-export default async function startCompletionsServer(): Promise<void> {
-  const runtime: PragmaRuntime = await bootPragma();
-
-  const ctx: PragmaContext = { ...runtime, globalFlags: COMPLETIONS_FLAGS };
-  const commands = collectCommands(ctx);
-  const tree = buildCompleters(commands);
-
-  const socketPath = computeSocketPath(runtime.cwd);
-
-  if (existsSync(socketPath)) {
-    unlinkSync(socketPath);
-  }
-
-  let idleTimer: Timer;
-
-  function resetIdle(): void {
-    clearTimeout(idleTimer);
-    idleTimer = setTimeout(() => {
-      runtime.dispose();
-      server.stop();
-      try {
-        unlinkSync(socketPath);
-      } catch {
-        // Socket may already be removed.
-      }
-      process.exit(0);
-    }, IDLE_TIMEOUT_MS);
-  }
-
-  const server = Bun.listen({
-    unix: socketPath,
-    socket: {
-      async data(socket, rawData) {
-        resetIdle();
-        const partial = Buffer.from(rawData)
-          .toString("utf-8")
-          .replace(/\n$/, "");
-        const result = await handleQuery(partial, tree, ctx);
-        socket.write(result);
-        socket.end();
-      },
-      open() {},
-      close() {},
-      error() {},
-    },
-  });
-
-  resetIdle();
-}

package/src/completions/startCompletionsServer.unit.test.ts

@@ -1,131 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { IDLE_TIMEOUT_MS } from "./constants.js";
-
-const existsSyncMock = vi.fn();
-const unlinkSyncMock = vi.fn();
-const buildCompletersMock = vi.fn(() => ({ root: true }));
-const bootPragmaMock = vi.fn();
-const collectCommandsMock = vi.fn(() => []);
-const computeSocketPathMock = vi.fn(() => "/tmp/pragma-completions.sock");
-const handleQueryMock = vi.fn();
-const listenMock = vi.fn();
-const stopMock = vi.fn();
-
-vi.mock("node:fs", () => ({
-  existsSync: existsSyncMock,
-  unlinkSync: unlinkSyncMock,
-}));
-
-vi.mock("@canonical/cli-core", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("@canonical/cli-core")>();
-  return {
-    ...actual,
-    buildCompleters: buildCompletersMock,
-  };
-});
-
-vi.mock("../domains/shared/runtime.js", () => ({
-  bootPragma: bootPragmaMock,
-}));
-
-vi.mock("../pipeline/collectCommands.js", () => ({
-  default: collectCommandsMock,
-}));
-
-vi.mock("./computeSocketPath.js", () => ({
-  default: computeSocketPathMock,
-}));
-
-vi.mock("./handleQuery.js", () => ({
-  default: handleQueryMock,
-}));
-
-describe("startCompletionsServer", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-    vi.useFakeTimers();
-    stopMock.mockReset();
-    listenMock.mockReset();
-    listenMock.mockReturnValue({ stop: stopMock });
-    vi.stubGlobal("Bun", { listen: listenMock });
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-    vi.unstubAllGlobals();
-  });
-
-  it("boots, removes stale sockets, and handles incoming queries", async () => {
-    existsSyncMock.mockReturnValue(true);
-    const dispose = vi.fn();
-    bootPragmaMock.mockResolvedValue({
-      cwd: "/workspace",
-      store: {},
-      config: { tier: undefined, channel: "normal" },
-      dispose,
-    });
-    handleQueryMock.mockResolvedValue("block\nstandard");
-
-    const { default: startCompletionsServer } = await import(
-      "./startCompletionsServer.js"
-    );
-    await startCompletionsServer();
-
-    expect(unlinkSyncMock).toHaveBeenCalledWith("/tmp/pragma-completions.sock");
-    expect(buildCompletersMock).toHaveBeenCalledTimes(1);
-    expect(listenMock).toHaveBeenCalledTimes(1);
-
-    const listenConfig = listenMock.mock.calls[0]?.[0] as {
-      socket: {
-        data: (
-          socket: { write: (value: string) => void; end: () => void },
-          rawData: Uint8Array,
-        ) => Promise<void>;
-      };
-    };
-    const socket = { write: vi.fn(), end: vi.fn() };
-
-    await listenConfig.socket.data(socket, Buffer.from("blo\n"));
-
-    expect(handleQueryMock).toHaveBeenCalledWith(
-      "blo",
-      { root: true },
-      expect.objectContaining({
-        cwd: "/workspace",
-        globalFlags: { llm: false, format: "text", verbose: false },
-      }),
-    );
-    expect(socket.write).toHaveBeenCalledWith("block\nstandard");
-    expect(socket.end).toHaveBeenCalledTimes(1);
-    expect(dispose).not.toHaveBeenCalled();
-  });
-
-  it("disposes and exits after the idle timeout", async () => {
-    existsSyncMock.mockReturnValue(false);
-    const dispose = vi.fn();
-    const exitSpy = vi
-      .spyOn(process, "exit")
-      .mockImplementation((() => undefined) as never);
-
-    bootPragmaMock.mockResolvedValue({
-      cwd: "/workspace",
-      store: {},
-      config: { tier: undefined, channel: "normal" },
-      dispose,
-    });
-
-    const { default: startCompletionsServer } = await import(
-      "./startCompletionsServer.js"
-    );
-    await startCompletionsServer();
-
-    vi.advanceTimersByTime(IDLE_TIMEOUT_MS);
-
-    expect(dispose).toHaveBeenCalledTimes(1);
-    expect(stopMock).toHaveBeenCalledTimes(1);
-    expect(unlinkSyncMock).toHaveBeenCalledWith("/tmp/pragma-completions.sock");
-    expect(exitSpy).toHaveBeenCalledWith(0);
-
-    exitSpy.mockRestore();
-  });
-});

package/src/completions/waitForSocket.test.ts

@@ -1,27 +0,0 @@
-import { mkdtempSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import waitForSocket from "./waitForSocket.js";
-
-describe("waitForSocket", () => {
-  it("returns true immediately when file exists", async () => {
-    const dir = mkdtempSync(join(tmpdir(), "pragma-ws-"));
-    const path = join(dir, "test.sock");
-    writeFileSync(path, "");
-
-    try {
-      const result = await waitForSocket(path, 1_000);
-      expect(result).toBe(true);
-    } finally {
-      unlinkSync(path);
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it("returns false after timeout when file does not exist", async () => {
-    const path = "/tmp/pragma-test-nonexistent-socket.sock";
-    const result = await waitForSocket(path, 200);
-    expect(result).toBe(false);
-  });
-});

package/src/completions/waitForSocket.ts

@@ -1,27 +0,0 @@
-import { existsSync } from "node:fs";
-import { setTimeout } from "node:timers/promises";
-import { POLL_INTERVAL_MS } from "./constants.js";
-
-/**
- * Poll for a Unix socket file to appear on disk.
- *
- * Checks at `POLL_INTERVAL_MS` intervals until the file exists or
- * the timeout elapses.
- *
- * @param path - Absolute path to the expected socket file.
- * @param timeoutMs - Maximum time to wait in milliseconds.
- * @returns `true` if the socket appeared, `false` on timeout.
- *
- * @note Impure
- */
-export default async function waitForSocket(
-  path: string,
-  timeoutMs: number,
-): Promise<boolean> {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    if (existsSync(path)) return true;
-    await setTimeout(POLL_INTERVAL_MS);
-  }
-  return false;
-}

package/src/config/configExists.ts

@@ -1,14 +0,0 @@
-import { existsSync } from "node:fs";
-import resolveConfigPath from "./resolveConfigPath.js";
-
-/**
- * Check whether a pragma.config.json exists at the given cwd.
- *
- * @param cwd - Directory to check for configuration.
- * @returns `true` if the config file exists.
- *
- * @note Impure — reads filesystem.
- */
-export default function configExists(cwd: string): boolean {
-  return existsSync(resolveConfigPath(cwd));
-}

package/src/config/defaultConfig.test.ts

@@ -1,33 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { VALID_CHANNELS } from "../constants.js";
-import { parsePackageEntry } from "../domains/refs/operations/parseRef.js";
-import { DEFAULT_CONFIG } from "./defaultConfig.js";
-
-describe("DEFAULT_CONFIG", () => {
-  it("declares a valid channel", () => {
-    expect(VALID_CHANNELS).toContain(DEFAULT_CONFIG.channel);
-  });
-
-  it("declares at least one package, all parseable", () => {
-    expect(DEFAULT_CONFIG.packages.length).toBeGreaterThan(0);
-    for (const entry of DEFAULT_CONFIG.packages) {
-      const ref = parsePackageEntry(entry);
-      expect(ref.pkg.length).toBeGreaterThan(0);
-    }
-  });
-
-  it("carries the canonical design-system package by default", () => {
-    const names = DEFAULT_CONFIG.packages.map((entry) =>
-      typeof entry === "string" ? entry : entry.name,
-    );
-    expect(names).toContain("@canonical/design-system");
-  });
-
-  it("does not declare fields the document must not layer", () => {
-    // tier/trace/framework defaults are semantic absences, and packages
-    // must reach the merge via DEFAULT_PACKAGES (see defaultConfig.ts).
-    expect(DEFAULT_CONFIG.tier).toBeUndefined();
-    expect(DEFAULT_CONFIG.trace).toBeUndefined();
-    expect(DEFAULT_CONFIG.framework).toBeUndefined();
-  });
-});

package/src/config/defaultConfig.ts

@@ -1,59 +0,0 @@
-import type { Channel } from "../constants.js";
-import type { RawPackageEntry } from "../domains/refs/operations/parseRef.js";
-import { PragmaError } from "../error/PragmaError.js";
-import defaultsDocument from "./defaults.json" with { type: "json" };
-import parseConfigValues from "./parseConfigValues.js";
-import type { ConfigFileValues } from "./types.js";
-
-/** The built-in defaults with the fields every install relies on present. */
-interface DefaultConfig extends ConfigFileValues {
-  /** Release channel active when no config file sets one. */
-  readonly channel: Channel;
-  /** Semantic packages loaded when no config or global refs declare any. */
-  readonly packages: ReadonlyArray<RawPackageEntry>;
-}
-
-/**
- * Validate the embedded defaults document into the built-in config layer.
- *
- * The document goes through the same parser as user config files, so an
- * invalid edit to `defaults.json` fails loudly at first import (and in
- * tests) instead of silently changing behavior.
- *
- * @throws PragmaError with code `CONFIG_ERROR` when the document is
- *         invalid or misses a required default.
- */
-function parseDefaultsDocument(): DefaultConfig {
-  const values = parseConfigValues(
-    JSON.stringify(defaultsDocument),
-    "built-in defaults (src/config/defaults.json)",
-  );
-  if (values.channel === undefined) {
-    throw PragmaError.configError("Built-in defaults must declare a channel.", {
-      recovery: { message: "Restore `channel` in src/config/defaults.json." },
-    });
-  }
-  if (values.packages === undefined || values.packages.length === 0) {
-    throw PragmaError.configError(
-      "Built-in defaults must declare at least one semantic package.",
-      {
-        recovery: {
-          message: "Restore `packages` in src/config/defaults.json.",
-        },
-      },
-    );
-  }
-  return { ...values, channel: values.channel, packages: values.packages };
-}
-
-/**
- * The built-in configuration layer, sourced from the embedded declarative
- * `defaults.json` document rather than hardcoded values.
- *
- * `packages` is deliberately NOT surfaced through the layered `pick()` in
- * `readConfigLayers` — it feeds `DEFAULT_PACKAGES` (and from there the
- * ref merge), where global `refs.json` entries still merge over it by
- * package name. Sourcing it as an ordinary config layer would make it
- * look user-declared and shut global refs out.
- */
-export const DEFAULT_CONFIG: DefaultConfig = parseDefaultsDocument();