@canonical/pragma-cli 0.18.0

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

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

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

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

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

@@ -0,0 +1,49 @@
+/**
+ * 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 "./runtime.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.ts

@@ -0,0 +1,77 @@
+/**
+ * Boot a ke store from pragma.config.json sources.
+ *
+ * Reads configuration, resolves sources (defaults or overridden),
+ * creates the store with registered prefixes, and wraps errors.
+ *
+ * @note Impure — reads filesystem, creates ke store.
+ */
+
+import { join } from "node:path";
+import type { SourceSpec, Store } from "@canonical/ke";
+import { createStore } from "@canonical/ke";
+import type { PragmaConfig } from "#config";
+import { PragmaError } from "../../error/index.js";
+import { PACKAGES, resolvePackages } from "./packages.js";
+import { PREFIX_MAP } from "./prefixes.js";
+
+/**
+ * Resolve default TTL sources from the package registry.
+ * Package-manager agnostic — works with bun, npm, pnpm, and yarn.
+ */
+export function defaultSources(): SourceSpec[] {
+  const sources: SourceSpec[] = [];
+  const resolved = resolvePackages();
+
+  for (const { pkg, dir } of resolved) {
+    const def = PACKAGES.find((p) => p.pkg === pkg);
+    if (!def) continue;
+    for (const glob of def.ttl) {
+      sources.push(join(dir, glob));
+    }
+  }
+
+  return sources;
+}
+
+export interface BootStoreOptions {
+  /** Override config (skip reading from disk). */
+  config?: PragmaConfig;
+  /** Override sources (skip config sources field). */
+  sources?: SourceSpec[];
+  /** Working directory for resolving relative paths. */
+  cwd?: string;
+  /** Cache path for serialized store. */
+  cache?: string;
+}
+
+/**
+ * Boot a ke store from configuration.
+ *
+ * @throws PragmaError with code STORE_ERROR on failure.
+ */
+export async function bootStore(
+  options: BootStoreOptions = {},
+): Promise<Store> {
+  const sources = options.sources ?? defaultSources();
+
+  try {
+    const store = await createStore({
+      sources,
+      prefixes: PREFIX_MAP,
+      cache: options.cache,
+      cwd: options.cwd,
+    });
+    return store;
+  } catch (error) {
+    throw PragmaError.storeError(
+      error instanceof Error ? error.message : String(error),
+      {
+        recovery: {
+          message:
+            "Ensure design system packages are installed: bun add -D @canonical/design-system @canonical/code-standards @canonical/anatomy-dsl",
+        },
+      },
+    );
+  }
+}

package/src/domains/shared/buildQuery.ts

@@ -0,0 +1,18 @@
+/**
+ * Brand an internally-constructed query string as SPARQL.
+ *
+ * The `sparql` tagged template cannot interpolate raw SPARQL fragments
+ * (it would escape them as string literals). Operations that include
+ * dynamic filter clauses construct the query as a plain string and
+ * brand it via this helper.
+ *
+ * Safe because filter content is generated internally, never from
+ * user input. User-supplied values (e.g., component names) are
+ * escaped via `escapeSparqlValue()` before interpolation.
+ */
+
+import type { SPARQL } from "@canonical/ke";
+
+export function buildQuery(query: string): SPARQL<string> {
+  return query as SPARQL<string>;
+}

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

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import compactUri from "./compactUri.js";
+
+describe("compactUri", () => {
+  const prefixes = {
+    ds: "https://ds.canonical.com/",
+    cs: "http://pragma.canonical.com/codestandards#",
+  } as const;
+
+  it("compacts a URI when a matching prefix exists", () => {
+    expect(
+      compactUri("https://ds.canonical.com/global.component.button", prefixes),
+    ).toBe("ds:global.component.button");
+  });
+
+  it("returns the original URI when no prefix matches", () => {
+    expect(compactUri("https://example.com/thing", prefixes)).toBe(
+      "https://example.com/thing",
+    );
+  });
+});

package/src/domains/shared/compactUri.ts

@@ -0,0 +1,16 @@
+/**
+ * Convert a full URI to its compact prefixed form when a matching prefix exists.
+ * Falls back to the original URI when no namespace matches.
+ */
+export default function compactUri(
+  fullUri: string,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  for (const [prefix, namespace] of Object.entries(prefixes)) {
+    if (fullUri.startsWith(namespace)) {
+      return `${prefix}:${fullUri.slice(namespace.length)}`;
+    }
+  }
+
+  return fullUri;
+}

package/src/domains/shared/context.ts

@@ -0,0 +1,15 @@
+/**
+ * Extended command context for pragma CLI commands.
+ *
+ * Extends `PragmaRuntime` with CLI-specific global flags so commands
+ * access store, config, cwd, and output preferences uniformly via `ctx`.
+ *
+ * cli-core remains unaware of Store or FilterConfig.
+ */
+
+import type { GlobalFlags } from "@canonical/cli-core";
+import type { PragmaRuntime } from "./runtime.js";
+
+export interface PragmaContext extends PragmaRuntime {
+  readonly globalFlags: GlobalFlags;
+}