@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/domains/setup/operations/setupMcp.ts

@@ -1,108 +0,0 @@
-import type { McpServerConfig } from "@canonical/harnesses";
-import {
-  detectHarnesses,
-  findHarnessById,
-  writeMcpConfig,
-} from "@canonical/harnesses";
-import {
-  $,
-  gen,
-  info,
-  promptConfirm,
-  type Task,
-  traverse_,
-  warn,
-  when,
-} from "@canonical/task";
-import { MCP_SERVER_NAME } from "../helpers/constants.js";
-
-/**
- * Build the pragma MCP server config object for a project root.
- *
- * @param root - Project root directory.
- * @returns The MCP server configuration pointing to `pragma mcp`.
- */
-function pragmaMcpConfig(root: string): McpServerConfig {
-  return { command: "pragma", args: ["mcp"], cwd: root };
-}
-
-/**
- * Compose a Task that configures the pragma MCP server for detected
- * (or forced) AI harnesses. In detection mode, prompts for each
- * discovered harness before writing.
- *
- * @param root - Project root directory.
- * @param forceHarnessId - If set, bypass detection and configure this harness only.
- * @returns A Task that yields void on completion.
- * @note Impure
- */
-export default function setupMcp(
-  root: string,
-  forceHarnessId?: string,
-): Task<void> {
-  return gen(function* () {
-    // Force mode: bypass detection
-    if (forceHarnessId) {
-      const harness = findHarnessById(forceHarnessId);
-      if (!harness) {
-        yield* $(warn(`Unknown harness: ${forceHarnessId}`));
-        return;
-      }
-      yield* $(
-        writeMcpConfig(harness, root, MCP_SERVER_NAME, pragmaMcpConfig(root)),
-      );
-      yield* $(
-        info(`✓ pragma MCP server added to ${harness.configPath(root)}`),
-      );
-      return;
-    }
-
-    // Detection mode
-    const detected = yield* $(detectHarnesses(root));
-
-    if (detected.length === 0) {
-      yield* $(
-        warn(
-          "No AI harnesses detected. Use --claude-code, --cursor, or --windsurf to configure manually.",
-        ),
-      );
-      return;
-    }
-
-    yield* $(
-      info(
-        `Detected harness${detected.length > 1 ? "es" : ""}: ${detected.map((d) => d.harness.name).join(", ")}`,
-      ),
-    );
-
-    yield* $(
-      traverse_(detected, (d) =>
-        gen(function* () {
-          const confirmed = yield* $(
-            promptConfirm(
-              `setup-mcp-${d.harness.id}`,
-              `Configure pragma MCP for ${d.harness.name}?`,
-              true,
-            ),
-          );
-          yield* $(
-            when(
-              confirmed,
-              gen(function* () {
-                yield* $(
-                  writeMcpConfig(
-                    d.harness,
-                    root,
-                    MCP_SERVER_NAME,
-                    pragmaMcpConfig(root),
-                  ),
-                );
-                yield* $(info(`✓ pragma MCP server added to ${d.configPath}`));
-              }),
-            ),
-          );
-        }),
-      ),
-    );
-  });
-}

package/src/domains/setup/operations/setupSkills.test.ts

@@ -1,191 +0,0 @@
-import type { DetectedHarness, HarnessDefinition } from "@canonical/harnesses";
-import { dryRunWith, type Effect, filterEffects } from "@canonical/task";
-import { describe, expect, it } from "vitest";
-import type { DiscoveredSkill } from "../../skill/types.js";
-import type { SetupSkillsResult } from "../types.js";
-import setupSkills from "./setupSkills.js";
-
-const MOCK_SKILLS: readonly DiscoveredSkill[] = [
-  {
-    name: "design-audit",
-    description: "Audit a component against DS specs",
-    sourcePath:
-      "/project/node_modules/@canonical/ds-global/skills/design-audit",
-    sourcePackage: "@canonical/ds-global",
-    folderName: "design-audit",
-    frontmatter: {
-      name: "design-audit",
-      description: "Audit a component against DS specs",
-    },
-  },
-  {
-    name: "scaffold-story",
-    description: "Generate a Storybook story from anatomy",
-    sourcePath:
-      "/project/node_modules/@canonical/pragma-cli/skills/scaffold-story",
-    sourcePackage: "@canonical/pragma-cli",
-    folderName: "scaffold-story",
-    frontmatter: {
-      name: "scaffold-story",
-      description: "Generate a Storybook story from anatomy",
-    },
-  },
-];
-
-function makeHarness(
-  id: string,
-  name: string,
-  skillsDir: string,
-): DetectedHarness {
-  return {
-    harness: {
-      id,
-      name,
-      version: "*",
-      detect: [],
-      configPath: () => "",
-      configFormat: "json",
-      mcpKey: "mcpServers",
-      skillsPath: (root: string) => `${root}/${skillsDir}`,
-    } as HarnessDefinition,
-    confidence: "high",
-    configExists: false,
-    configPath: "",
-  };
-}
-
-const MOCK_HARNESSES: readonly DetectedHarness[] = [
-  makeHarness("claude-code", "Claude Code", ".claude/skills"),
-  makeHarness("cursor", "Cursor", ".cursor/skills"),
-];
-
-describe("setupSkills", () => {
-  it("creates symlinks for each skill in each harness", () => {
-    const task = setupSkills(MOCK_SKILLS, MOCK_HARNESSES, "/project");
-
-    const mocks = new Map<string, (e: Effect) => unknown>([
-      ["Exists", () => false],
-    ]);
-
-    const { value, effects } = dryRunWith(task, mocks);
-    const result = value as SetupSkillsResult;
-
-    const created = result.actions.filter((a) => a.action === "created");
-    // 2 skills × 3 targets (claude, cursor, .agents/skills) = 6
-    expect(created).toHaveLength(6);
-    expect(result.harnessCount).toBe(2);
-    expect(result.skillCount).toBe(2);
-
-    const symlinkEffects = filterEffects(effects, "Symlink");
-    expect(symlinkEffects).toHaveLength(6);
-  });
-
-  it("skips existing correct symlinks", () => {
-    const task = setupSkills(MOCK_SKILLS, MOCK_HARNESSES, "/project");
-
-    const mocks = new Map<string, (e: Effect) => unknown>([
-      ["Exists", () => true],
-      [
-        "Exec",
-        (e: Effect) => {
-          if (e._tag === "Exec" && e.command === "readlink") {
-            const linkPath = e.args[0];
-            if (linkPath.includes("design-audit")) {
-              return {
-                stdout:
-                  "/project/node_modules/@canonical/ds-global/skills/design-audit",
-                stderr: "",
-                exitCode: 0,
-              };
-            }
-            if (linkPath.includes("scaffold-story")) {
-              return {
-                stdout:
-                  "/project/node_modules/@canonical/pragma-cli/skills/scaffold-story",
-                stderr: "",
-                exitCode: 0,
-              };
-            }
-          }
-          return { stdout: "", stderr: "", exitCode: 0 };
-        },
-      ],
-    ]);
-
-    const { value } = dryRunWith(task, mocks);
-    const result = value as SetupSkillsResult;
-
-    const skipped = result.actions.filter((a) => a.action === "skipped");
-    expect(skipped).toHaveLength(6);
-    expect(result.warnings).toHaveLength(0);
-  });
-
-  it("replaces wrong symlinks with warning", () => {
-    const task = setupSkills([MOCK_SKILLS[0]], [MOCK_HARNESSES[0]], "/project");
-
-    const mocks = new Map<string, (e: Effect) => unknown>([
-      ["Exists", () => true],
-      [
-        "Exec",
-        () => ({
-          stdout: "/wrong/target",
-          stderr: "",
-          exitCode: 0,
-        }),
-      ],
-    ]);
-
-    const { value } = dryRunWith(task, mocks);
-    const result = value as SetupSkillsResult;
-
-    const replaced = result.actions.filter((a) => a.action === "replaced");
-    expect(replaced.length).toBeGreaterThan(0);
-    expect(result.warnings.length).toBeGreaterThan(0);
-  });
-
-  it("deduplicates cross-client .agents/skills path", () => {
-    const harnesses = [
-      makeHarness("cline", "Cline", ".agents/skills"),
-      makeHarness("opencode", "OpenCode", ".agents/skills"),
-    ];
-
-    const task = setupSkills(MOCK_SKILLS, harnesses, "/project");
-
-    const mocks = new Map<string, (e: Effect) => unknown>([
-      ["Exists", () => false],
-    ]);
-
-    const { value } = dryRunWith(task, mocks);
-    const result = value as SetupSkillsResult;
-
-    // Both harnesses use .agents/skills, so only one set of symlinks
-    // plus no separate cross-client dir (already covered)
-    const created = result.actions.filter((a) => a.action === "created");
-    expect(created).toHaveLength(2); // 2 skills × 1 unique dir
-  });
-
-  it("handles empty skills list", () => {
-    const task = setupSkills([], MOCK_HARNESSES, "/project");
-
-    const { value } = dryRunWith(task, new Map());
-    const result = value as SetupSkillsResult;
-
-    expect(result.actions).toHaveLength(0);
-    expect(result.skillCount).toBe(0);
-  });
-
-  it("handles empty harnesses list", () => {
-    const task = setupSkills(MOCK_SKILLS, [], "/project");
-
-    const mocks = new Map<string, (e: Effect) => unknown>([
-      ["Exists", () => false],
-    ]);
-
-    const { value } = dryRunWith(task, mocks);
-    const result = value as SetupSkillsResult;
-
-    // Still creates cross-client .agents/skills
-    const created = result.actions.filter((a) => a.action === "created");
-    expect(created).toHaveLength(2); // 2 skills × 1 (.agents/skills)
-  });
-});

package/src/domains/setup/operations/setupSkills.ts

@@ -1,160 +0,0 @@
-import { resolve } from "node:path";
-import type { DetectedHarness } from "@canonical/harnesses";
-import {
-  deleteFile,
-  exec,
-  exists,
-  flatMap,
-  map,
-  mkdir,
-  pure,
-  sequence,
-  symlink,
-  type Task,
-} from "@canonical/task";
-import type { DiscoveredSkill } from "../../skill/types.js";
-import type { SetupSkillsResult, SymlinkAction } from "../types.js";
-
-/** Cross-client skill directory, shared across all harnesses. */
-const CROSS_CLIENT_DIR = ".agents/skills";
-
-/**
- * Create or replace a single skill symlink, returning the action taken.
- *
- * @param skill - The discovered skill to symlink.
- * @param targetDir - Directory where the symlink will be created.
- * @param projectRoot - Project root for resolving absolute paths.
- * @param harnessName - Display name of the target harness.
- * @returns A Task yielding the SymlinkAction describing what happened.
- */
-function symlinkOneSkill(
-  skill: DiscoveredSkill,
-  targetDir: string,
-  harnessName: string,
-): Task<SymlinkAction> {
-  const target = skill.sourcePath;
-  const linkPath = resolve(targetDir, skill.folderName);
-
-  return flatMap(exists(linkPath), (linkExists) => {
-    if (!linkExists) {
-      return map(
-        symlink(target, linkPath),
-        (): SymlinkAction => ({
-          skillName: skill.name,
-          target,
-          linkPath,
-          action: "created",
-          harnessName,
-        }),
-      );
-    }
-
-    return flatMap(
-      exec("readlink", [linkPath]),
-      (readlinkResult): Task<SymlinkAction> => {
-        const currentTarget = readlinkResult.stdout.trim();
-        if (currentTarget === target) {
-          return pure({
-            skillName: skill.name,
-            target,
-            linkPath,
-            action: "skipped",
-            harnessName,
-          });
-        }
-
-        return map(
-          flatMap(deleteFile(linkPath), () => symlink(target, linkPath)),
-          (): SymlinkAction => ({
-            skillName: skill.name,
-            target,
-            linkPath,
-            action: "replaced",
-            harnessName,
-          }),
-        );
-      },
-    );
-  });
-}
-
-/**
- * Symlink all skills into a single target directory, creating the
- * directory if it does not exist.
- *
- * @param skills - Skills to symlink.
- * @param targetDir - Target directory path.
- * @param projectRoot - Project root for resolving absolute paths.
- * @param harnessName - Display name of the target harness.
- * @returns A Task yielding an array of SymlinkActions.
- */
-function symlinkForTarget(
-  skills: readonly DiscoveredSkill[],
-  targetDir: string,
-  harnessName: string,
-): Task<SymlinkAction[]> {
-  return flatMap(mkdir(targetDir), () =>
-    map(
-      sequence(
-        skills.map((skill) => symlinkOneSkill(skill, targetDir, harnessName)),
-      ),
-      (actions) => [...actions],
-    ),
-  );
-}
-
-/**
- * Symlink discovered skills into each harness skill directory and the
- * cross-client `.agents/skills` directory. Idempotent: existing correct
- * symlinks are skipped, stale symlinks are replaced.
- *
- * @param skills - Skills discovered from installed packages.
- * @param harnesses - Detected AI harnesses to target.
- * @param projectRoot - Project root directory.
- * @returns A Task yielding a SetupSkillsResult summary.
- * @note Impure
- */
-export default function setupSkills(
-  skills: readonly DiscoveredSkill[],
-  harnesses: readonly DetectedHarness[],
-  projectRoot: string,
-): Task<SetupSkillsResult> {
-  const processedDirs = new Set<string>();
-  const targets: { dir: string; name: string }[] = [];
-
-  for (const detected of harnesses) {
-    const dir = detected.harness.skillsPath(projectRoot);
-    if (!processedDirs.has(dir)) {
-      processedDirs.add(dir);
-      targets.push({ dir, name: detected.harness.name });
-    }
-  }
-
-  const crossClientDir = resolve(projectRoot, CROSS_CLIENT_DIR);
-  if (!processedDirs.has(crossClientDir)) {
-    processedDirs.add(crossClientDir);
-    targets.push({ dir: crossClientDir, name: ".agents/skills" });
-  }
-
-  return map(
-    sequence(
-      targets.map(({ dir, name }) => symlinkForTarget(skills, dir, name)),
-    ),
-    (actionGroups): SetupSkillsResult => {
-      const allActions = actionGroups.flat();
-      const warnings = allActions
-        .filter((a) => a.action === "replaced")
-        .map(
-          (a) =>
-            `Replaced existing symlink for ${a.skillName} in ${a.harnessName}`,
-        );
-
-      return {
-        actions: allActions,
-        harnessCount: harnesses.length,
-        skillCount: skills.length,
-        warnings,
-      };
-    },
-  );
-}

package/src/domains/setup/types.ts

@@ -1,18 +0,0 @@
-/** Describes a single symlink create/skip/replace action performed during skill setup. */
-export interface SymlinkAction {
-  readonly skillName: string;
-  readonly target: string;
-  readonly linkPath: string;
-  readonly action: "created" | "skipped" | "replaced";
-  readonly harnessName: string;
-}
-
-/** Aggregate result of the `pragma setup skills` operation. */
-export interface SetupSkillsResult {
-  readonly actions: readonly SymlinkAction[];
-  readonly harnessCount: number;
-  readonly skillCount: number;
-  readonly warnings: readonly string[];
-}
-
-export type LogLevel = "debug" | "info" | "warn" | "error";

package/src/domains/shared/ToolSpec.ts

@@ -1,49 +0,0 @@
-/**
- * Declarative MCP tool specification — no MCP imports.
- *
- * Domains export `ToolSpec[]` from `mcp/specs.ts`. The `mcp/` adapter layer
- * consumes specs via `registerFromSpec()` to wire zod schemas, wrapTool
- * envelopes, and `server.registerTool()` calls.
- */
-
-import type { PragmaRuntime } from "./types/index.js";
-
-/**
- * Parameter definition for a tool — neutral format.
- *
- * The MCP adapter generates zod schemas from this. A future CLI adapter
- * could generate `ParameterDefinition[]`.
- */
-export interface ToolParamDef {
-  readonly type: "string" | "boolean" | "string[]";
-  readonly description: string;
-  readonly optional?: boolean;
-  readonly enum?: readonly string[];
-}
-
-/**
- * Return value from a tool spec's execute function.
- *
- * Structurally compatible with `ToolPayload` from `mcp/types.ts`.
- */
-export type ToolResult =
-  | { data: unknown; meta?: Record<string, unknown> }
-  | { condensed: true; text: string; tokens: string };
-
-/**
- * Declarative tool specification — no MCP imports.
- *
- * Domains export arrays of these. The `mcp/tools/registerFromSpec.ts`
- * adapter converts each spec into a registered MCP tool.
- */
-export interface ToolSpec {
-  readonly name: string;
-  readonly description: string;
-  readonly params?: Readonly<Record<string, ToolParamDef>>;
-  readonly readOnly: boolean;
-  readonly destructive?: boolean;
-  readonly execute: (
-    rt: PragmaRuntime,
-    params: Record<string, unknown>,
-  ) => Promise<ToolResult>;
-}

package/src/domains/shared/bootStore.bareCore.test.ts

@@ -1,63 +0,0 @@
-/**
- * Bare-core boot — pragma must serve the generic `graph`, `graphql`, and
- * `ontology` surfaces with zero semantic packages loaded. This pins the P0
- * invariant that the core no longer depends on the design-system packages:
- * a store booted with no packages resolves generic queries and each
- * generic operation returns cleanly instead of crashing.
- */
-
-import type { Store } from "@canonical/ke";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { EX_NAMESPACE, GRAPHQL_CLEAN_TTL } from "#testing";
-import inspectUri from "../graph/operations/inspectUri.js";
-import compileSchema from "../graphql/operations/compileSchema.js";
-import listOntologies from "../ontology/operations/listOntologies.js";
-import { bootStore } from "./bootStore.js";
-import { PREFIX_MAP, resolvePrefixes } from "./prefixes.js";
-
-let store: Store;
-
-beforeAll(async () => {
-  // The `sources` override boots with zero resolved packages (bare core).
-  const boot = await bootStore({ sources: [] });
-  store = boot.store;
-  expect(boot.packages).toEqual([]);
-});
-
-afterAll(() => store?.dispose());
-
-describe("bare-core boot", () => {
-  it("carries the generic core prefixes on the store", () => {
-    expect(store.prefixes.rdf).toBe(PREFIX_MAP.rdf);
-    expect(store.prefixes.owl).toBe(PREFIX_MAP.owl);
-  });
-
-  it("serves generic SPARQL without any packages loaded", async () => {
-    const result = await store.query(
-      "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }",
-    );
-    expect(result.type).toBe("select");
-  });
-
-  it("serves `ontology` — listOntologies returns cleanly, not a crash", async () => {
-    await expect(listOntologies(store)).resolves.toEqual([]);
-  });
-
-  it("serves `graph` — inspecting an unknown URI reports not-found, not a crash", async () => {
-    await expect(
-      inspectUri(store, "https://example.org/nothing"),
-    ).rejects.toMatchObject({ code: "ENTITY_NOT_FOUND" });
-  });
-
-  it("serves `graphql` — compiles a generic ontology with core-only prefixes", async () => {
-    const outcome = await compileSchema({
-      sources: [
-        { content: GRAPHQL_CLEAN_TTL, format: "turtle", path: "x.ttl" },
-      ],
-      // Package-style prefix layered over the bare core — no DS packages.
-      prefixes: resolvePrefixes([{ prefixes: { ex: EX_NAMESPACE } }]),
-    });
-    expect(outcome.status).toBe("ok");
-    expect(outcome.compiled?.sdl).toContain("type Thing");
-  });
-});

package/src/domains/shared/bootStore.test.ts

@@ -1,82 +0,0 @@
-import { createStore } from "@canonical/ke";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { createGraphLoaderPlugin } from "./bootStore.js";
-
-const PREFIXES = { ds: "https://ds.canonical.com/" };
-
-const goodGraph = (path: string, subject: string) => ({
-  path,
-  content: `@prefix ds: <https://ds.canonical.com/>.\nds:${subject} a ds:Component.\n`,
-  format: "turtle" as const,
-});
-
-/** Mirrors the malformed `ds:hasSubcomponent ds:global..` shipped by upstream. */
-const badGraph = (path: string) => ({
-  path,
-  content:
-    "@prefix ds: <https://ds.canonical.com/>.\nds:global.component.broken a ds:Component;\n    ds:hasSubcomponent ds:global...\n",
-  format: "turtle" as const,
-});
-
-async function countTriples(
-  graphs: readonly ReturnType<typeof goodGraph>[],
-): Promise<number> {
-  const store = await createStore({
-    sources: [],
-    prefixes: PREFIXES,
-    plugins: [createGraphLoaderPlugin(graphs)],
-  });
-  // Always dispose the WASM-backed store so it can't leak across tests.
-  try {
-    const result = await store.query(
-      "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }",
-    );
-    return Number(
-      result.type === "select" ? (result.bindings[0]?.n ?? "0") : "0",
-    );
-  } finally {
-    store.dispose();
-  }
-}
-
-let stderrSpy: ReturnType<typeof vi.spyOn>;
-
-beforeEach(() => {
-  stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
-});
-
-afterEach(() => {
-  stderrSpy.mockRestore();
-});
-
-const stderrText = (): string =>
-  stderrSpy.mock.calls.map((call) => String(call[0])).join("");
-
-describe("createGraphLoaderPlugin", () => {
-  it("loads every graph when all are well-formed", async () => {
-    const count = await countTriples([
-      goodGraph("a.ttl", "global.component.a"),
-      goodGraph("b.ttl", "global.component.b"),
-    ]);
-    expect(count).toBe(2);
-    expect(stderrText()).toBe("");
-  });
-
-  it("skips a malformed graph but still boots and loads the good ones", async () => {
-    const count = await countTriples([
-      goodGraph("a.ttl", "global.component.a"),
-      badGraph("data/global/component/broken.ttl"),
-      goodGraph("b.ttl", "global.component.b"),
-    ]);
-    // The two good graphs load; the malformed one is skipped, not fatal.
-    expect(count).toBe(2);
-  });
-
-  it("warns with the offending file path and parse error", async () => {
-    await countTriples([badGraph("data/global/component/broken.ttl")]);
-    const text = stderrText();
-    expect(text).toContain("skipping malformed graph");
-    expect(text).toContain("data/global/component/broken.ttl");
-    expect(text).toContain("Check the TTL syntax");
-  });
-});