@canonical/pragma-cli 0.30.0 → 0.32.0

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

@@ -1,135 +0,0 @@
-/**
- * Boot a ke store from resolved semantic packages.
- *
- * Resolves packages via the loader chain (local > git > bundled),
- * then loads all graph content into the store.
- *
- * @note Impure — reads filesystem, creates ke store.
- */
-
-import {
-  createStore,
-  definePlugin,
-  type Plugin,
-  type SourceSpec,
-  type Store,
-} from "@canonical/ke";
-import { PragmaError } from "../../error/index.js";
-import type { PackageRef } from "../refs/operations/parseRef.js";
-import { parsePackageEntry } from "../refs/operations/parseRef.js";
-import {
-  createBundledLoader,
-  createGitLoader,
-  createLocalLoader,
-} from "./loaders/index.js";
-import { DEFAULT_PACKAGES } from "./packages.js";
-import { PREFIX_MAP } from "./prefixes.js";
-import type { SemanticPackage } from "./semanticPackage.js";
-import { resolveSemanticPackages } from "./semanticPackage.js";
-
-export interface BootStoreOptions {
-  /** Override sources (skip package resolution — for testing). */
-  sources?: SourceSpec[];
-  /** Working directory for resolving relative paths. */
-  cwd?: string;
-  /** Cache path for serialized store. */
-  cache?: string;
-  /** Parsed package references for loader-based resolution. */
-  refs?: ReadonlyArray<PackageRef>;
-  /** Enable query tracing (from config). Env var PRAGMA_TRACE=1 overrides. */
-  trace?: boolean;
-  /** Additional namespace prefixes merged over the built-in prefix map. */
-  prefixes?: Readonly<Record<string, string>>;
-}
-
-export interface BootResult {
-  /** The initialized ke store. */
-  readonly store: Store;
-  /** Resolved semantic packages (empty when sources override is used). */
-  readonly packages: readonly SemanticPackage[];
-}
-
-/**
- * Boot a ke store from configuration.
- *
- * When `sources` is provided, uses them directly (testing path).
- * Otherwise, resolves packages via the loader chain and loads their
- * graph content into the store.
- *
- * @throws PragmaError with code STORE_ERROR on failure.
- */
-export async function bootStore(
-  options: BootStoreOptions = {},
-): Promise<BootResult> {
-  const prefixes = { ...PREFIX_MAP, ...options.prefixes };
-  try {
-    // Testing/programmatic override — use explicit sources
-    if (options.sources) {
-      const store = await createStore({
-        sources: options.sources,
-        prefixes,
-        cache: options.cache,
-        cwd: options.cwd,
-      });
-      return { store, packages: [] };
-    }
-
-    // Resolve packages via loader chain: local > git > bundled
-    const refs =
-      options.refs && options.refs.length > 0
-        ? options.refs
-        : DEFAULT_PACKAGES.map(parsePackageEntry);
-    // Precedence: local (file:// + node_modules) > git cache > bundled
-    const loaders = [
-      createLocalLoader(),
-      createGitLoader(),
-      createBundledLoader(),
-    ];
-    const packages = await resolveSemanticPackages(refs, loaders);
-
-    // Collect all graph content from resolved packages
-    const allGraphs = packages.flatMap((pkg) => pkg.graphs);
-
-    // Use a ke plugin to load graph content during store creation.
-    // The onReady hook has access to ctx.load() which loads raw content.
-    const graphLoaderPlugin = definePlugin({
-      name: "pragma-graph-loader",
-      onReady(ctx) {
-        for (const graph of allGraphs) {
-          ctx.load(graph.content, { format: graph.format });
-        }
-      },
-    });
-
-    // biome-ignore lint: Plugin generic variance requires explicit unknown
-    const plugins: Plugin<any>[] = [graphLoaderPlugin];
-    const traceEnabled =
-      process.env.PRAGMA_TRACE === "1" || options.trace === true;
-    if (traceEnabled) {
-      const { createTracePlugin } = await import("../trace/tracePlugin.js");
-      const { traceDir } = await import("../refs/operations/paths.js");
-      plugins.push(createTracePlugin({ traceDir: traceDir() }));
-    }
-
-    const store = await createStore({
-      sources: [],
-      prefixes,
-      cache: options.cache,
-      cwd: options.cwd,
-      plugins,
-    });
-
-    return { store, packages };
-  } catch (error) {
-    if (error instanceof PragmaError) throw 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

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

@@ -1,32 +0,0 @@
-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",
-    );
-  });
-
-  it("picks the longest matching namespace when namespaces overlap", () => {
-    const overlapping = {
-      base: "https://ex.org/",
-      sub: "https://ex.org/sub/",
-    } as const;
-    // Both `base` and `sub` are prefixes of the URI; the longer wins.
-    expect(compactUri("https://ex.org/sub/Thing", overlapping)).toBe(
-      "sub:Thing",
-    );
-  });
-});

package/src/domains/shared/compactUri.ts

@@ -1,21 +0,0 @@
-/**
- * Convert a full URI to its compact prefixed form using the longest matching
- * namespace. When two registered namespaces are both prefixes of the URI
- * (e.g. a base namespace and a sub-namespace), the longer — more specific —
- * one wins. Falls back to the original URI when no namespace matches.
- */
-export default function compactUri(
-  fullUri: string,
-  prefixes: Readonly<Record<string, string>>,
-): string {
-  let best: { prefix: string; namespace: string } | undefined;
-  for (const [prefix, namespace] of Object.entries(prefixes)) {
-    if (!fullUri.startsWith(namespace)) continue;
-    if (best === undefined || namespace.length > best.namespace.length) {
-      best = { prefix, namespace };
-    }
-  }
-
-  if (best === undefined) return fullUri;
-  return `${best.prefix}:${fullUri.slice(best.namespace.length)}`;
-}

package/src/domains/shared/context.ts

@@ -1,16 +0,0 @@
-/**
- * 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, PromptSessionFactory } from "@canonical/cli-core";
-import type { PragmaRuntime } from "./types/index.js";
-
-export interface PragmaContext extends PragmaRuntime {
-  readonly globalFlags: GlobalFlags;
-  readonly promptSession?: PromptSessionFactory | undefined;
-}

package/src/domains/shared/contracts.ts

@@ -1,164 +0,0 @@
-/**
- * Shared command and entity-display contracts.
- *
- * These types provide the structural common ground for CLI and MCP surfaces.
- */
-
-import type { FilterConfig } from "./types/index.js";
-
-export interface ColumnDef<T> {
-  readonly key: keyof T & string;
-  readonly label: string;
-  readonly format?: (value: unknown) => string;
-  readonly showWhenEmpty?: boolean;
-}
-
-export type SectionKind =
-  | "field"
-  | "code"
-  | "list"
-  | "table"
-  | "nested-table"
-  | "tree";
-
-export interface SectionDef<T> {
-  readonly key: keyof T & string;
-  readonly heading: string;
-  readonly kind: SectionKind;
-  readonly showWhenEmpty?: boolean;
-}
-
-export interface ListParams {
-  readonly allTiers?: boolean;
-  readonly digest?: boolean;
-  readonly detailed?: boolean;
-  readonly condensed?: boolean;
-}
-
-export interface LookupParams {
-  readonly names: readonly string[];
-  readonly detailed?: boolean;
-  readonly condensed?: boolean;
-}
-
-export interface ListResult<T> {
-  readonly items: readonly T[];
-  readonly filters: FilterConfig;
-  readonly disclosure:
-    | { readonly level: "summary" }
-    | { readonly level: "digest"; readonly maxExampleLength?: number }
-    | { readonly level: "detailed" };
-}
-
-/** Aggregate metadata about a multi-query lookup. */
-export interface LookupResultMeta {
-  /**
-   * Number of queries that failed with an unexpected (non-Pragma) error.
-   * Each such failure is also present in `errors` with code `INTERNAL_ERROR`.
-   */
-  readonly internalErrorCount: number;
-}
-
-export interface LookupResult<T> {
-  readonly results: readonly T[];
-  readonly errors: readonly {
-    query: string;
-    code: string;
-    message: string;
-    suggestions?: readonly string[];
-  }[];
-  /** Populated by `lookupMany`; may be absent on hand-built results. */
-  readonly meta?: LookupResultMeta;
-}
-
-export interface ShowContract<T> {
-  readonly result: T;
-}
-
-export interface MutateContract<TParams, TResult> {
-  readonly params: TParams;
-  readonly result: TResult;
-  readonly confirmation: string;
-}
-
-export interface ListContract<
-  TSummary,
-  TDigest extends TSummary,
-  TDetailed extends TDigest,
-> {
-  readonly params: ListParams;
-  readonly result: ListResult<TSummary | TDigest | TDetailed>;
-}
-
-export interface LookupContract<TDetailed> {
-  readonly params: LookupParams;
-  readonly result: LookupResult<TDetailed>;
-}
-
-// ---------------------------------------------------------------------------
-// Renderer contracts
-// ---------------------------------------------------------------------------
-
-/** A single inline field rendered in a lookup heading block. */
-export interface LookupField<T> {
-  readonly label: string;
-  readonly value: (entity: T) => unknown;
-}
-
-/** Per-mode override callbacks for a lookup section. */
-export interface LookupSectionOverride<T> {
-  readonly plain?: (entity: T, section: SectionDef<T>) => string | null;
-  readonly llm?: (entity: T, section: SectionDef<T>) => string | null;
-}
-
-/** Options controlling the generic list renderer. */
-export interface RenderListOptions<T> {
-  readonly heading: string;
-  readonly columns: readonly ColumnDef<T>[];
-  readonly prefixes?: Readonly<Record<string, string>>;
-}
-
-/** Options controlling the generic lookup renderer. */
-export interface RenderLookupOptions<T> {
-  readonly title: (entity: T) => string;
-  readonly fields: readonly LookupField<T>[];
-  readonly sections: readonly SectionDef<T>[];
-  readonly prefixes?: Readonly<Record<string, string>>;
-  readonly sectionOverrides?: Partial<
-    Record<keyof T & string, LookupSectionOverride<T>>
-  >;
-  readonly codeLanguage?: (section: SectionDef<T>, value: unknown) => string;
-}
-
-// ---------------------------------------------------------------------------
-// Entity display configuration
-// ---------------------------------------------------------------------------
-
-export interface EntityDisplayConfig<
-  TSummary,
-  TDigest extends TSummary,
-  TDetailed extends TDigest,
-> {
-  readonly domain: string;
-  readonly entityName: string;
-  readonly rdfTypes: readonly string[];
-  readonly listColumns: readonly ColumnDef<TSummary>[];
-  readonly digestColumns: readonly ColumnDef<TDigest>[];
-  readonly lookupSections: readonly SectionDef<TDetailed>[];
-  readonly emptyRecovery: (filters: FilterConfig) => {
-    readonly message: string;
-    readonly cli?: string;
-    readonly mcp?: {
-      readonly tool: string;
-      readonly params?: Record<string, unknown>;
-    };
-  };
-  readonly notFoundRecovery: (query: string) => {
-    readonly message: string;
-    readonly cli?: string;
-    readonly mcp?: {
-      readonly tool: string;
-      readonly params?: Record<string, unknown>;
-    };
-  };
-}