@canonical/pragma-cli 0.30.0 → 0.32.0

package/src/domains/ontology/stories.ts

@@ -1,108 +0,0 @@
-/**
- * Ontology read stories — the single declaration of `ontology list` and
- * `ontology show` for both surfaces.
- *
- * The story kernel compiles these into the CLI commands and MCP tools.
- * Both surfaces now render through the same formatters, so MCP condensed
- * output matches CLI `--llm` output by construction (previously the MCP
- * specs re-implemented the Markdown inline and had drifted).
- */
-
-import { PragmaError } from "#error";
-import { createListView } from "#tui";
-import type { ColumnDef } from "../shared/contracts.js";
-import {
-  type ReadStory,
-  requirePragmaContext,
-} from "../shared/stories/index.js";
-import type {
-  OntologyDetailed,
-  OntologySummary,
-} from "../shared/types/index.js";
-import { listFormatters, showFormatters } from "./formatters/index.js";
-import { listOntologies, showOntology } from "./operations/index.js";
-
-const ontologyListColumns: readonly ColumnDef<OntologySummary>[] = [
-  { key: "prefix", label: "Prefix" },
-  { key: "namespace", label: "Namespace" },
-  { key: "classCount", label: "Classes" },
-  { key: "propertyCount", label: "Properties" },
-  { key: "anatomyCount", label: "Anatomies" },
-];
-
-/** The `ontology list` / `ontology_list` read story. */
-export const ontologyListStory: ReadStory<
-  OntologySummary[],
-  readonly OntologySummary[]
-> = {
-  noun: "ontology",
-  verb: "list",
-  description: "List loaded ontologies",
-  toolDescription:
-    "List all ontologies loaded in the knowledge graph with class and property counts.",
-  params: [],
-  examples: ["pragma ontology list", "pragma ontology list --llm"],
-  resolve: (rt) => listOntologies(rt.store),
-  toOutput: (ontologies) => ontologies,
-  formatters: listFormatters,
-  toEnvelope: (ontologies) => ({
-    data: ontologies,
-    meta: { count: ontologies.length },
-  }),
-  emptyError: (ontologies) =>
-    ontologies.length === 0
-      ? PragmaError.emptyResults("ontology", {
-          recovery: {
-            message: "Ensure design system packages are installed.",
-          },
-        })
-      : undefined,
-  renderInk: (ontologies) =>
-    createListView({
-      heading: "Ontologies",
-      domain: "ontology",
-      items: ontologies,
-      columns: ontologyListColumns,
-    }),
-};
-
-/** The `ontology show <prefix>` / `ontology_show` read story. */
-export const ontologyShowStory: ReadStory<OntologyDetailed, OntologyDetailed> =
-  {
-    noun: "ontology",
-    verb: "show",
-    description: "Show ontology schema details",
-    toolDescription:
-      "Show detailed schema for an ontology including classes and properties.",
-    params: [
-      {
-        name: "prefix",
-        type: "string",
-        description: "Ontology prefix (e.g. 'ds', 'cs')",
-        positional: true,
-        required: true,
-        complete: async (partial, cmdCtx) => {
-          const ctx = requirePragmaContext(cmdCtx);
-          const all = await listOntologies(ctx.store);
-          return all
-            .map((o) => o.prefix)
-            .filter((p) => p.toLowerCase().startsWith(partial.toLowerCase()));
-        },
-      },
-    ],
-    examples: ["pragma ontology show ds", "pragma ontology show cs --llm"],
-    resolve: (rt, params) => showOntology(rt.store, params.prefix as string),
-    toOutput: (ontology) => ontology,
-    formatters: showFormatters,
-    toEnvelope: (ontology) => ({ data: ontology }),
-    guardParams: (params) =>
-      typeof params.prefix === "string" && params.prefix.length > 0
-        ? undefined
-        : PragmaError.invalidInput("prefix", "(empty)", {
-            recovery: {
-              message: "List loaded ontologies to find valid prefixes.",
-              cli: "pragma ontology list",
-              mcp: { tool: "ontology_list" },
-            },
-          }),
-  };

package/src/domains/refs/commands/updateRefs.ts

@@ -1,52 +0,0 @@
-/**
- * CLI command: pragma update-refs
- *
- * Fetches/clones git-referenced semantic packages into the local cache.
- * Store-skip command — does not boot the ke store.
- */
-
-import type { CommandDefinition } from "@canonical/cli-core";
-import formatUpdateResults from "../formatters/updateRefs.js";
-import updateRefs from "../operations/updateRefs.js";
-
-const updateRefsCommand: CommandDefinition = {
-  path: ["update-refs"],
-  description:
-    "Fetch or clone git-referenced semantic packages into the local cache",
-  parameters: [
-    {
-      name: "package",
-      description: "Update only this package (by name)",
-      type: "string",
-    },
-    {
-      name: "prune",
-      description:
-        "Remove orphaned cache entries that no longer match any configured ref",
-      type: "boolean",
-      default: false,
-    },
-  ],
-  meta: {
-    examples: [
-      "pragma update-refs",
-      "pragma update-refs --package @canonical/design-system",
-      "pragma update-refs --prune",
-    ],
-  },
-  execute: async (params, ctx) => {
-    const results = await updateRefs({
-      cwd: ctx.cwd,
-      package: params.package as string | undefined,
-      prune: params.prune === true,
-    });
-
-    const text = formatUpdateResults(results);
-    process.stdout.write(`${text}\n`);
-
-    const hasErrors = results.some((r) => r.kind === "error");
-    return { tag: "exit" as const, code: hasErrors ? 1 : 0 };
-  },
-};
-
-export default updateRefsCommand;

package/src/domains/refs/formatters/updateRefs.ts

@@ -1,27 +0,0 @@
-/**
- * Plain-text formatter for update-refs results.
- */
-
-import type { UpdateResult } from "../operations/updateRefs.js";
-
-const KIND_LABELS: Record<UpdateResult["kind"], string> = {
-  cloned: "cloned",
-  updated: "updated",
-  "up-to-date": "up to date",
-  ok: "ok",
-  skipped: "skipped",
-  error: "ERROR",
-};
-
-export default function formatUpdateResults(
-  results: ReadonlyArray<UpdateResult>,
-): string {
-  if (results.length === 0) return "No packages configured.";
-
-  const lines: string[] = [];
-  for (const r of results) {
-    const label = KIND_LABELS[r.kind] ?? r.kind;
-    lines.push(`${r.pkg}: ${label} — ${r.detail}`);
-  }
-  return lines.join("\n");
-}

package/src/domains/refs/index.ts

@@ -1,27 +0,0 @@
-/** @module Refs domain — package reference resolution and update-refs command. */
-
-import type { CommandDefinition } from "@canonical/cli-core";
-import updateRefsCommand from "./commands/updateRefs.js";
-
-/**
- * Return all refs command definitions.
- * Store-skip domain — does not require a booted ke store.
- */
-export function commands(): CommandDefinition[] {
-  return [updateRefsCommand];
-}
-
-export type {
-  PackageRef,
-  RawPackageEntry,
-  UpdateRefsOptions,
-  UpdateResult,
-} from "./operations/index.js";
-export {
-  cacheRoot,
-  gitCacheDir,
-  globalConfigDir,
-  parsePackageEntry,
-  readGlobalRefs,
-  updateRefs,
-} from "./operations/index.js";

package/src/domains/refs/operations/gitOps.test.ts

@@ -1,155 +0,0 @@
-import { execFileSync } from "node:child_process";
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { cloneRef, fetchRef, isSha, pruneCache } from "./gitOps.js";
-
-describe("isSha", () => {
-  it("recognizes a 7-char hex string", () => {
-    expect(isSha("abc1234")).toBe(true);
-  });
-
-  it("recognizes a 40-char hex string", () => {
-    expect(isSha("abc1234def5678901234567890abcdef12345678")).toBe(true);
-  });
-
-  it("rejects non-hex characters", () => {
-    expect(isSha("main")).toBe(false);
-    expect(isSha("v1.0.0")).toBe(false);
-    expect(isSha("feature/branch")).toBe(false);
-  });
-
-  it("rejects too-short strings", () => {
-    expect(isSha("abc12")).toBe(false);
-  });
-
-  it("rejects uppercase hex", () => {
-    expect(isSha("ABC1234")).toBe(false);
-  });
-});
-
-describe("cloneRef + fetchRef (integration, requires git)", () => {
-  let tmpDir: string;
-  let bareRepo: string;
-
-  beforeEach(() => {
-    tmpDir = mkdtempSync(join(tmpdir(), "pragma-gitops-"));
-
-    // Create a bare repo to clone from (avoids network)
-    bareRepo = join(tmpDir, "origin.git");
-    execFileSync("git", ["init", "--bare", "-b", "main", bareRepo], {
-      stdio: "pipe",
-    });
-
-    // Push an initial commit to the bare repo via a temp working copy
-    const workDir = join(tmpDir, "work");
-    execFileSync("git", ["clone", bareRepo, workDir], { stdio: "pipe" });
-    execFileSync(
-      "git",
-      ["-C", workDir, "config", "user.email", "test@test.com"],
-      { stdio: "pipe" },
-    );
-    execFileSync("git", ["-C", workDir, "config", "user.name", "Test"], {
-      stdio: "pipe",
-    });
-    execFileSync(
-      "git",
-      ["-C", workDir, "commit", "--allow-empty", "-m", "initial"],
-      { stdio: "pipe" },
-    );
-    execFileSync("git", ["-C", workDir, "push", "origin", "main"], {
-      stdio: "pipe",
-    });
-    // Tag it
-    execFileSync("git", ["-C", workDir, "tag", "v0.1.0"], { stdio: "pipe" });
-    execFileSync("git", ["-C", workDir, "push", "origin", "v0.1.0"], {
-      stdio: "pipe",
-    });
-    // Add another commit for update testing
-    execFileSync(
-      "git",
-      ["-C", workDir, "commit", "--allow-empty", "-m", "second"],
-      { stdio: "pipe" },
-    );
-    execFileSync("git", ["-C", workDir, "push", "origin", "main"], {
-      stdio: "pipe",
-    });
-
-    rmSync(workDir, { recursive: true, force: true });
-  });
-
-  afterEach(() => {
-    rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it("clones a branch ref", () => {
-    const dest = join(tmpDir, "clone-branch");
-    cloneRef(bareRepo, "main", dest);
-    expect(existsSync(join(dest, ".git"))).toBe(true);
-  });
-
-  it("clones a tag ref", () => {
-    const dest = join(tmpDir, "clone-tag");
-    cloneRef(bareRepo, "v0.1.0", dest);
-    expect(existsSync(join(dest, ".git"))).toBe(true);
-  });
-
-  it("clones a SHA ref", () => {
-    // Get the SHA of the initial commit
-    const sha = execFileSync("git", ["-C", bareRepo, "rev-parse", "v0.1.0"], {
-      stdio: "pipe",
-    })
-      .toString()
-      .trim();
-
-    const dest = join(tmpDir, "clone-sha");
-    cloneRef(bareRepo, sha, dest);
-    expect(existsSync(join(dest, ".git"))).toBe(true);
-  });
-
-  it("fetches updates on an existing clone", () => {
-    // Clone at tag (first commit)
-    const dest = join(tmpDir, "clone-fetch");
-    cloneRef(bareRepo, "v0.1.0", dest);
-
-    // Fetch main (which has a second commit)
-    const result = fetchRef(bareRepo, "main", dest);
-    expect(result.updated).toBe(true);
-    expect(result.oldHead).not.toBe(result.newHead);
-  });
-
-  it("reports up-to-date when no changes", () => {
-    const dest = join(tmpDir, "clone-noop");
-    cloneRef(bareRepo, "main", dest);
-
-    const result = fetchRef(bareRepo, "main", dest);
-    expect(result.updated).toBe(false);
-    expect(result.oldHead).toBe(result.newHead);
-  });
-});
-
-describe("pruneCache", () => {
-  let tmpDir: string;
-
-  beforeEach(() => {
-    tmpDir = mkdtempSync(join(tmpdir(), "pragma-prune-"));
-  });
-
-  afterEach(() => {
-    rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it("removes an existing directory", () => {
-    const dir = join(tmpDir, "to-remove");
-    execFileSync("mkdir", ["-p", dir]);
-    expect(existsSync(dir)).toBe(true);
-    pruneCache(dir);
-    expect(existsSync(dir)).toBe(false);
-  });
-
-  it("does nothing for a non-existent directory", () => {
-    pruneCache(join(tmpDir, "does-not-exist"));
-    // no throw
-  });
-});

package/src/domains/refs/operations/gitOps.ts

@@ -1,92 +0,0 @@
-/**
- * Git operations for managing cached package clones.
- *
- * All operations use execFileSync with shell: false for security.
- * Relies entirely on the user's git client for authentication
- * (SSH keys, credential helpers). Zero custom auth logic.
- */
-
-import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, rmSync } from "node:fs";
-import { dirname } from "node:path";
-
-/** Check whether a ref looks like a commit SHA (7-40 hex chars). */
-export function isSha(ref: string): boolean {
-  return /^[0-9a-f]{7,40}$/.test(ref);
-}
-
-/**
- * Clone a repository at a specific ref into a destination directory.
- * Uses shallow clone (--depth 1) for speed.
- *
- * @param url - Git remote URL (https:// or ssh://).
- * @param ref - Branch, tag, or commit SHA.
- * @param dest - Target directory (must not exist).
- */
-export function cloneRef(url: string, ref: string, dest: string): void {
-  mkdirSync(dirname(dest), { recursive: true });
-
-  if (isSha(ref)) {
-    // Git doesn't support shallow clone by SHA directly.
-    // Init, fetch the specific commit, checkout.
-    mkdirSync(dest, { recursive: true });
-    git(dest, ["init"]);
-    git(dest, ["fetch", "--depth", "1", url, ref]);
-    git(dest, ["checkout", "FETCH_HEAD"]);
-  } else {
-    // Branches and tags: --branch works with --depth 1
-    execFileSync("git", ["clone", "--depth", "1", "--branch", ref, url, dest], {
-      stdio: "pipe",
-    });
-  }
-}
-
-/**
- * Update an existing cached clone by fetching the latest for its ref.
- *
- * @param url - Git remote URL.
- * @param ref - Branch, tag, or commit SHA.
- * @param dest - Existing cache directory.
- * @returns Whether the HEAD changed after fetch.
- */
-export function fetchRef(
-  url: string,
-  ref: string,
-  dest: string,
-): { updated: boolean; oldHead: string; newHead: string } {
-  const oldHead = gitOutput(dest, ["rev-parse", "HEAD"]);
-
-  if (isSha(ref)) {
-    git(dest, ["fetch", "--depth", "1", url, ref]);
-    git(dest, ["checkout", "FETCH_HEAD"]);
-  } else {
-    git(dest, ["fetch", "--depth", "1", url, ref]);
-    git(dest, ["checkout", "FETCH_HEAD"]);
-  }
-
-  const newHead = gitOutput(dest, ["rev-parse", "HEAD"]);
-  return { updated: oldHead !== newHead, oldHead, newHead };
-}
-
-/**
- * Remove a cached directory.
- */
-export function pruneCache(dir: string): void {
-  if (existsSync(dir)) {
-    rmSync(dir, { recursive: true, force: true });
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Run a git command in a directory. Throws on non-zero exit. */
-function git(cwd: string, args: string[]): void {
-  execFileSync("git", args, { cwd, stdio: "pipe" });
-}
-
-/** Run a git command and return trimmed stdout. */
-function gitOutput(cwd: string, args: string[]): string {
-  return execFileSync("git", args, { cwd, stdio: "pipe" }).toString().trim();
-}

package/src/domains/refs/operations/index.ts

@@ -1,10 +0,0 @@
-/** @module Refs operations — parsing, resolution, caching, and update logic. */
-
-export { cloneRef, fetchRef, isSha, pruneCache } from "./gitOps.js";
-export type { PackageRef, RawPackageEntry } from "./parseRef.js";
-export { parsePackageEntry } from "./parseRef.js";
-export { cacheRoot, dataRoot, gitCacheDir, globalConfigDir } from "./paths.js";
-export { default as readGlobalRefs } from "./readGlobalRefs.js";
-
-export type { UpdateRefsOptions, UpdateResult } from "./updateRefs.js";
-export { default as updateRefs } from "./updateRefs.js";

package/src/domains/refs/operations/parseRef.test.ts

@@ -1,157 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { PragmaError } from "../../../error/index.js";
-import { parsePackageEntry } from "./parseRef.js";
-
-describe("parsePackageEntry", () => {
-  describe("npm references", () => {
-    it("parses a bare string as npm", () => {
-      const ref = parsePackageEntry("@canonical/design-system");
-      expect(ref).toEqual({ kind: "npm", pkg: "@canonical/design-system" });
-    });
-
-    it("parses an object without source as npm", () => {
-      const ref = parsePackageEntry({ name: "@canonical/design-system" });
-      expect(ref).toEqual({ kind: "npm", pkg: "@canonical/design-system" });
-    });
-
-    it("parses an object with undefined source as npm", () => {
-      const ref = parsePackageEntry({
-        name: "@canonical/design-system",
-        source: undefined,
-      });
-      expect(ref).toEqual({ kind: "npm", pkg: "@canonical/design-system" });
-    });
-  });
-
-  describe("file references", () => {
-    it("parses file:// source with absolute path", () => {
-      const ref = parsePackageEntry({
-        name: "@canonical/design-system",
-        source: "file:///home/user/code/design-system",
-      });
-      expect(ref).toEqual({
-        kind: "file",
-        pkg: "@canonical/design-system",
-        path: "/home/user/code/design-system",
-      });
-    });
-
-    it("parses file:// source with relative path", () => {
-      const ref = parsePackageEntry({
-        name: "@canonical/design-system",
-        source: "file://./local-packages/design-system",
-      });
-      expect(ref).toEqual({
-        kind: "file",
-        pkg: "@canonical/design-system",
-        path: "./local-packages/design-system",
-      });
-    });
-
-    it("throws on empty file:// path", () => {
-      expect(() =>
-        parsePackageEntry({
-          name: "@canonical/design-system",
-          source: "file://",
-        }),
-      ).toThrow(PragmaError);
-    });
-  });
-
-  describe("git references", () => {
-    it("parses git+https:// source with branch ref", () => {
-      const ref = parsePackageEntry({
-        name: "@canonical/design-system",
-        source: "git+https://github.com/canonical/design-system.git#main",
-      });
-      expect(ref).toEqual({
-        kind: "git",
-        pkg: "@canonical/design-system",
-        url: "https://github.com/canonical/design-system.git",
-        ref: "main",
-      });
-    });
-
-    it("parses git+https:// source with tag ref", () => {
-      const ref = parsePackageEntry({
-        name: "@canonical/design-system",
-        source: "git+https://github.com/canonical/design-system.git#v0.3.0",
-      });
-      expect(ref).toEqual({
-        kind: "git",
-        pkg: "@canonical/design-system",
-        url: "https://github.com/canonical/design-system.git",
-        ref: "v0.3.0",
-      });
-    });
-
-    it("parses git+https:// source with SHA ref", () => {
-      const ref = parsePackageEntry({
-        name: "@canonical/design-system",
-        source:
-          "git+https://github.com/canonical/design-system.git#abc1234def5678",
-      });
-      expect(ref).toEqual({
-        kind: "git",
-        pkg: "@canonical/design-system",
-        url: "https://github.com/canonical/design-system.git",
-        ref: "abc1234def5678",
-      });
-    });
-
-    it("parses git+ssh:// source", () => {
-      const ref = parsePackageEntry({
-        name: "@canonical/design-system",
-        source: "git+ssh://git@github.com/canonical/design-system.git#main",
-      });
-      expect(ref).toEqual({
-        kind: "git",
-        pkg: "@canonical/design-system",
-        url: "ssh://git@github.com/canonical/design-system.git",
-        ref: "main",
-      });
-    });
-
-    it("throws on git URL without #ref", () => {
-      expect(() =>
-        parsePackageEntry({
-          name: "@canonical/design-system",
-          source: "git+https://github.com/canonical/design-system.git",
-        }),
-      ).toThrow(PragmaError);
-    });
-
-    it("throws on git URL with empty ref after #", () => {
-      expect(() =>
-        parsePackageEntry({
-          name: "@canonical/design-system",
-          source: "git+https://github.com/canonical/design-system.git#",
-        }),
-      ).toThrow(PragmaError);
-    });
-  });
-
-  describe("invalid entries", () => {
-    it("throws on unknown source scheme", () => {
-      expect(() =>
-        parsePackageEntry({
-          name: "@canonical/design-system",
-          source: "https://example.com/package.tar.gz",
-        }),
-      ).toThrow(PragmaError);
-    });
-
-    it("throws on empty name", () => {
-      expect(() => parsePackageEntry({ name: "" })).toThrow(PragmaError);
-    });
-
-    it("throws on non-string source", () => {
-      expect(() =>
-        parsePackageEntry({
-          name: "@canonical/design-system",
-          source: 42 as unknown as string,
-        }),
-      ).toThrow(PragmaError);
-    });
-  });
-});