@canonical/pragma-cli 0.18.0

package/src/completions/startCompletionsServer.test.ts

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

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

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

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

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

@@ -0,0 +1,14 @@
+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/index.ts

@@ -0,0 +1,6 @@
+/** @module Configuration file reading, writing, and path resolution. */
+export { default as configExists } from "./configExists.js";
+export { default as readConfig } from "./readConfig.js";
+export { default as resolveConfigPath } from "./resolveConfigPath.js";
+export type { ConfigUpdate, PragmaConfig } from "./types.js";
+export { default as writeConfig } from "./writeConfig.js";

package/src/config/readConfig.test.ts

@@ -0,0 +1,152 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { PragmaError } from "../error/PragmaError.js";
+import readConfig from "./readConfig.js";
+import writeConfig from "./writeConfig.js";
+
+describe("readConfig", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-config-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("returns defaults when no config file exists", () => {
+    const config = readConfig(dir);
+    expect(config).toEqual({ tier: undefined, channel: "normal" });
+  });
+
+  it("parses tier and channel", () => {
+    writeFileSync(
+      join(dir, "pragma.config.json"),
+      '{"tier":"apps/lxd","channel":"experimental"}',
+    );
+    const config = readConfig(dir);
+    expect(config.tier).toBe("apps/lxd");
+    expect(config.channel).toBe("experimental");
+  });
+
+  it("parses tier only, defaults channel to normal", () => {
+    writeFileSync(join(dir, "pragma.config.json"), '{"tier":"global"}');
+    const config = readConfig(dir);
+    expect(config.tier).toBe("global");
+    expect(config.channel).toBe("normal");
+  });
+
+  it("parses channel only, tier is undefined", () => {
+    writeFileSync(join(dir, "pragma.config.json"), '{"channel":"prerelease"}');
+    const config = readConfig(dir);
+    expect(config.tier).toBeUndefined();
+    expect(config.channel).toBe("prerelease");
+  });
+
+  it("handles empty file", () => {
+    writeFileSync(join(dir, "pragma.config.json"), "");
+    const config = readConfig(dir);
+    expect(config).toEqual({ tier: undefined, channel: "normal" });
+  });
+
+  it("throws PragmaError on invalid channel", () => {
+    writeFileSync(join(dir, "pragma.config.json"), '{"channel":"aggressive"}');
+    expect(() => readConfig(dir)).toThrow(PragmaError);
+    try {
+      readConfig(dir);
+    } catch (e) {
+      expect(e).toBeInstanceOf(PragmaError);
+      expect((e as PragmaError).code).toBe("CONFIG_ERROR");
+      expect((e as PragmaError).validOptions).toEqual([
+        "normal",
+        "experimental",
+        "prerelease",
+      ]);
+    }
+  });
+
+  it("ignores non-string tier", () => {
+    writeFileSync(join(dir, "pragma.config.json"), '{"tier":42}');
+    const config = readConfig(dir);
+    expect(config.tier).toBeUndefined();
+  });
+});
+
+describe("writeConfig", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-config-write-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("creates a new config file with tier", () => {
+    writeConfig(dir, { tier: "apps/lxd" });
+    const config = readConfig(dir);
+    expect(config.tier).toBe("apps/lxd");
+    expect(config.channel).toBe("normal");
+  });
+
+  it("creates a new config file with channel", () => {
+    writeConfig(dir, { channel: "experimental" });
+    const config = readConfig(dir);
+    expect(config.channel).toBe("experimental");
+    expect(config.tier).toBeUndefined();
+  });
+
+  it("merges tier into existing config", () => {
+    writeFileSync(join(dir, "pragma.config.json"), '{"channel":"prerelease"}');
+    writeConfig(dir, { tier: "global" });
+    const config = readConfig(dir);
+    expect(config.tier).toBe("global");
+    expect(config.channel).toBe("prerelease");
+  });
+
+  it("removes tier when set to undefined", () => {
+    writeFileSync(
+      join(dir, "pragma.config.json"),
+      '{"tier":"apps","channel":"normal"}',
+    );
+    writeConfig(dir, { tier: undefined });
+    const config = readConfig(dir);
+    expect(config.tier).toBeUndefined();
+    expect(config.channel).toBe("normal");
+  });
+
+  it("removes channel when set to undefined", () => {
+    writeFileSync(
+      join(dir, "pragma.config.json"),
+      '{"tier":"apps","channel":"experimental"}',
+    );
+    writeConfig(dir, { channel: undefined });
+    const config = readConfig(dir);
+    expect(config.tier).toBe("apps");
+    // Channel defaults to "normal" when absent from file
+    expect(config.channel).toBe("normal");
+  });
+
+  it("round-trips tier and channel through write then read", () => {
+    writeConfig(dir, { tier: "apps/lxd", channel: "prerelease" });
+    const config = readConfig(dir);
+    expect(config.tier).toBe("apps/lxd");
+    expect(config.channel).toBe("prerelease");
+  });
+
+  it("writes valid empty JSON when all fields removed", () => {
+    writeFileSync(join(dir, "pragma.config.json"), '{"tier":"apps"}');
+    writeConfig(dir, { tier: undefined });
+    const raw = readFileSync(join(dir, "pragma.config.json"), "utf-8");
+    expect(raw).toBe("{}\n");
+  });
+
+  it("throws on unparseable existing config instead of silently overwriting", () => {
+    writeFileSync(join(dir, "pragma.config.json"), "{invalid json");
+    expect(() => writeConfig(dir, { tier: "apps" })).toThrow();
+  });
+});

package/src/config/readConfig.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from "node:fs";
+import { type Channel, VALID_CHANNELS } from "../constants.js";
+import { PragmaError } from "../error/PragmaError.js";
+import resolveConfigPath from "./resolveConfigPath.js";
+import type { PragmaConfig } from "./types.js";
+
+/**
+ * Type guard: check whether a value is a recognized channel string.
+ *
+ * @param value - Candidate value.
+ * @returns `true` if value is a valid Channel.
+ */
+function isValidChannel(value: unknown): value is Channel {
+  return typeof value === "string" && VALID_CHANNELS.includes(value as Channel);
+}
+
+/**
+ * Read pragma config from `pragma.config.json` in the given directory.
+ *
+ * Returns defaults (no tier, `"normal"` channel) when the file is missing or empty.
+ *
+ * @param cwd - Directory containing pragma.config.json (defaults to `process.cwd()`).
+ * @returns Parsed configuration.
+ * @throws PragmaError with code `CONFIG_ERROR` if JSON is invalid or channel is unrecognized.
+ *
+ * @note Impure — reads config from filesystem.
+ */
+export default function readConfig(cwd: string = process.cwd()): PragmaConfig {
+  const configPath = resolveConfigPath(cwd);
+
+  let raw: string;
+  try {
+    raw = readFileSync(configPath, "utf-8");
+  } catch {
+    return { tier: undefined, channel: "normal" };
+  }
+
+  const trimmed = raw.trim();
+  if (trimmed === "") {
+    return { tier: undefined, channel: "normal" };
+  }
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(trimmed) as Record<string, unknown>;
+  } catch {
+    throw PragmaError.configError(`Invalid JSON in ${configPath}.`);
+  }
+
+  const tier = typeof parsed.tier === "string" ? parsed.tier : undefined;
+
+  let channel: Channel = "normal";
+  if (parsed.channel !== undefined) {
+    if (!isValidChannel(parsed.channel)) {
+      throw PragmaError.configError(
+        `Invalid channel "${String(parsed.channel)}".`,
+        { validOptions: [...VALID_CHANNELS] },
+      );
+    }
+    channel = parsed.channel;
+  }
+
+  return { tier, channel };
+}

package/src/config/resolveConfigPath.test.ts

@@ -0,0 +1,20 @@
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import resolveConfigPath from "./resolveConfigPath.js";
+
+describe("resolveConfigPath", () => {
+  it("appends pragma.config.json to the given directory", () => {
+    expect(resolveConfigPath("/home/user/project")).toBe(
+      resolve("/home/user/project", "pragma.config.json"),
+    );
+  });
+
+  it("resolves relative paths against cwd", () => {
+    const result = resolveConfigPath(".");
+    expect(result).toBe(resolve(process.cwd(), "pragma.config.json"));
+  });
+
+  it("handles nested directories", () => {
+    expect(resolveConfigPath("/a/b/c")).toBe("/a/b/c/pragma.config.json");
+  });
+});

package/src/config/resolveConfigPath.ts

@@ -0,0 +1,11 @@
+import { resolve } from "node:path";
+
+/**
+ * Resolve the absolute path to pragma.config.json for a given cwd.
+ *
+ * @param cwd - Directory to resolve from.
+ * @returns Absolute file path to the configuration file.
+ */
+export default function resolveConfigPath(cwd: string): string {
+  return resolve(cwd, "pragma.config.json");
+}

package/src/config/types.ts

@@ -0,0 +1,26 @@
+/**
+ * Configuration data shapes for pragma.config.json.
+ *
+ * Separates the persisted config shape from the read/write logic
+ * so consumers can import types without pulling in filesystem code.
+ */
+
+import type { Channel } from "../constants.js";
+
+/** Parsed contents of pragma.config.json. */
+interface PragmaConfig {
+  /** Active tier path, or `undefined` when no tier is configured. */
+  tier: string | undefined;
+  /** Release channel controlling component visibility. */
+  channel: Channel;
+}
+
+/** Partial update payload for writing config changes. */
+interface ConfigUpdate {
+  /** New tier path, `undefined` to remove the tier field. */
+  tier?: string | undefined;
+  /** New channel, `undefined` to remove the channel field. */
+  channel?: Channel | undefined;
+}
+
+export type { ConfigUpdate, PragmaConfig };

package/src/config/writeConfig.ts

@@ -0,0 +1,49 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import resolveConfigPath from "./resolveConfigPath.js";
+import type { ConfigUpdate } from "./types.js";
+
+/**
+ * Write config updates to pragma.config.json.
+ *
+ * Merges updates into existing JSON. A field set to `undefined` removes it.
+ * Creates the file if it doesn't exist.
+ *
+ * @param cwd - Directory containing (or to contain) pragma.config.json.
+ * @param update - Fields to set or remove.
+ *
+ * @note Impure — writes to the filesystem.
+ */
+export default function writeConfig(cwd: string, update: ConfigUpdate): void {
+  const configPath = resolveConfigPath(cwd);
+  const tempPath = `${configPath}.tmp`;
+
+  let existing: Record<string, unknown> = {};
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    existing = JSON.parse(raw) as Record<string, unknown>;
+  } catch (err: unknown) {
+    // Only swallow "file not found" — surface parse or permission errors.
+    const isNotFound =
+      err instanceof Error &&
+      "code" in err &&
+      (err as NodeJS.ErrnoException).code === "ENOENT";
+    if (!isNotFound) {
+      throw err;
+    }
+  }
+
+  if (update.tier !== undefined) {
+    existing.tier = update.tier;
+  } else if ("tier" in update) {
+    delete existing.tier;
+  }
+
+  if (update.channel !== undefined) {
+    existing.channel = update.channel;
+  } else if ("channel" in update) {
+    delete existing.channel;
+  }
+
+  writeFileSync(tempPath, `${JSON.stringify(existing, null, 2)}\n`);
+  renameSync(tempPath, configPath);
+}