@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

package/src/domains/shared/packages.ts

@@ -1,126 +1,20 @@
 /**
- * Design system package registry and resolution.
+ * Default semantic graph package registry.
  *
- * Resolves semantic packages from three sources (in priority order):
- * 1. file:// local path (development)
- * 2. git ref cache (shared/CI)
- * 3. require.resolve from node_modules (npm fallback)
+ * Sourced from the declarative built-in defaults document
+ * (`src/config/defaults.json`) — pragma core carries no hardcoded
+ * knowledge of specific design-system packages. These form the base
+ * package set whenever a config layer does not declare a non-empty
+ * `packages` list; global `refs.json` entries then merge over them by
+ * package name, and a non-empty config list replaces them entirely
+ * (see `mergeAndParseRefs`).
  *
- * The package list itself is configurable via pragma.config.json `packages`
- * field. When absent, the hardcoded DEFAULT_PACKAGES are used.
+ * Resolution is handled by the loader chain in `loaders/`.
  */
 
-import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
-import { dirname } from "node:path";
-import type { PackageRef } from "../refs/operations/parseRef.js";
-import { gitCacheDir } from "../refs/operations/paths.js";
+import { DEFAULT_CONFIG } from "../../config/defaultConfig.js";
+import type { RawPackageEntry } from "../refs/operations/parseRef.js";
 
-const require = createRequire(import.meta.url);
-
-// ---------------------------------------------------------------------------
-// Default package registry (used when config.packages is absent)
-// ---------------------------------------------------------------------------
-
-/** Default semantic packages loaded when no config overrides are present. */
-export const DEFAULT_PACKAGES: readonly string[] = [
-  "@canonical/design-system",
-  "@canonical/anatomy-dsl",
-  "@canonical/code-standards",
-  "@canonical/pragma-cli",
-];
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface ResolvedPackage {
-  /** npm package name. */
-  readonly pkg: string;
-  /** Absolute path to the package root. */
-  readonly dir: string;
-}
-
-// ---------------------------------------------------------------------------
-// Resolution
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve packages to filesystem directories.
- *
- * When `refs` is provided, each PackageRef is resolved according to its kind.
- * When `refs` is omitted, the DEFAULT_PACKAGES are resolved via require.resolve.
- *
- * @param refs - Parsed package references (from config merge). Omit for defaults.
- * @returns Array of resolved packages with absolute directory paths.
- */
-export function resolvePackages(
-  refs?: ReadonlyArray<PackageRef>,
-): ResolvedPackage[] {
-  if (!refs) {
-    return resolveNpmPackages(DEFAULT_PACKAGES);
-  }
-
-  const resolved: ResolvedPackage[] = [];
-
-  for (const ref of refs) {
-    switch (ref.kind) {
-      case "file": {
-        if (!existsSync(ref.path)) {
-          console.warn(
-            `pragma: package "${ref.pkg}" points to ${ref.path} which does not exist. Check the path or remove the file:// source.`,
-          );
-          break;
-        }
-        resolved.push({ pkg: ref.pkg, dir: ref.path });
-        break;
-      }
-
-      case "git": {
-        const cacheDir = gitCacheDir(ref.pkg, ref.ref);
-        if (existsSync(cacheDir)) {
-          resolved.push({ pkg: ref.pkg, dir: cacheDir });
-          break;
-        }
-        // Cache miss — warn and fall through to npm
-        console.warn(
-          `pragma: git ref for "${ref.pkg}" not cached. Run "pragma update-refs" to fetch it.`,
-        );
-        resolveNpmFallback(ref.pkg, resolved);
-        break;
-      }
-
-      case "npm": {
-        resolveNpmFallback(ref.pkg, resolved);
-        break;
-      }
-    }
-  }
-
-  return resolved;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Resolve a list of package names via require.resolve. */
-function resolveNpmPackages(pkgs: readonly string[]): ResolvedPackage[] {
-  const resolved: ResolvedPackage[] = [];
-  for (const pkg of pkgs) {
-    resolveNpmFallback(pkg, resolved);
-  }
-  return resolved;
-}
-
-/** Try to resolve a single package via require.resolve, push if found. */
-function resolveNpmFallback(pkg: string, resolved: ResolvedPackage[]): void {
-  try {
-    resolved.push({
-      pkg,
-      dir: dirname(require.resolve(`${pkg}/package.json`)),
-    });
-  } catch {
-    // package not installed — skip
-  }
-}
+/** Default semantic graph packages loaded when no config overrides are present. */
+export const DEFAULT_PACKAGES: readonly RawPackageEntry[] =
+  DEFAULT_CONFIG.packages;

package/src/domains/shared/pickRandom.ts

@@ -0,0 +1,22 @@
+/**
+ * Pick `count` random items from an array without replacement.
+ *
+ * Uses Fisher-Yates partial shuffle for uniform distribution.
+ * Returns at most `arr.length` items if count exceeds the array size.
+ */
+export default function pickRandom<T>(
+  arr: readonly T[],
+  count: number,
+): readonly T[] {
+  const n = Math.min(count, arr.length);
+  if (n === 0) return [];
+
+  const copy = [...arr];
+  for (let i = 0; i < n; i++) {
+    const j = i + Math.floor(Math.random() * (copy.length - i));
+    const tmp = copy[i];
+    copy[i] = copy[j] as T;
+    copy[j] = tmp as T;
+  }
+  return copy.slice(0, n);
+}

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

@@ -0,0 +1,27 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import resolveConfiguredGraphs from "./resolveConfiguredGraphs.js";
+
+describe("resolveConfiguredGraphs", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-rcg-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("resolves the default semantic packages' TTL graphs", async () => {
+    // No pragma.config.json in the temp dir → mergeAndParseRefs falls back to
+    // the default packages, which resolve from node_modules in the workspace.
+    const graphs = await resolveConfiguredGraphs(dir);
+
+    expect(graphs.length).toBeGreaterThan(0);
+    expect(graphs[0]).toMatchObject({ format: "turtle" });
+    expect(typeof graphs[0]?.content).toBe("string");
+  });
+});

package/src/domains/shared/resolveConfiguredGraphs.ts

@@ -0,0 +1,41 @@
+/**
+ * Resolve every TTL graph from the semantically-configured packages.
+ *
+ * Reads `pragma.config.json`, merges its `packages` with the global refs
+ * and the built-in defaults (a non-empty `packages` list replaces the set
+ * entirely; an empty or absent list falls back to global refs merged over
+ * the defaults), resolves each package through the loader chain
+ * (local > git > bundled), and returns the union of their definitions/ and
+ * data/ graph content — the same discovery the runtime store performs at
+ * boot, minus the store.
+ *
+ * @note Impure — reads config and package files from disk.
+ *
+ * @param cwd - Working directory used to locate `pragma.config.json`.
+ * @returns The TTL graph content of every resolved package.
+ */
+
+import { readConfig } from "#config";
+import {
+  createBundledLoader,
+  createGitLoader,
+  createLocalLoader,
+} from "./loaders/index.js";
+import { mergeAndParseRefs } from "./mergeAndParseRefs.js";
+import {
+  type GraphContent,
+  resolveSemanticPackages,
+} from "./semanticPackage.js";
+
+export default async function resolveConfiguredGraphs(
+  cwd: string,
+): Promise<GraphContent[]> {
+  const config = readConfig(cwd);
+  const refs = mergeAndParseRefs(config.packages);
+  const packages = await resolveSemanticPackages(refs, [
+    createLocalLoader(),
+    createGitLoader(),
+    createBundledLoader(),
+  ]);
+  return packages.flatMap((pkg) => pkg.graphs);
+}

package/src/domains/shared/runtime.ts

@@ -10,14 +10,8 @@
 
 import type { SourceSpec } from "@canonical/ke";
 import { readConfig } from "#config";
-import {
-  type PackageRef,
-  parsePackageEntry,
-  type RawPackageEntry,
-} from "../refs/operations/parseRef.js";
-import readGlobalRefs from "../refs/operations/readGlobalRefs.js";
 import { bootStore } from "./bootStore.js";
-import { DEFAULT_PACKAGES } from "./packages.js";
+import { mergeAndParseRefs } from "./mergeAndParseRefs.js";
 import type { PragmaRuntime } from "./types/index.js";
 
 export type { PragmaRuntime } from "./types/index.js";
@@ -43,75 +37,25 @@ export async function bootPragma(options?: {
   const cwd = options?.cwd ?? process.cwd();
   const config = readConfig(cwd);
 
-  // Merge package refs: project overrides global, both override defaults.
+  // Merge package refs: a non-empty config list replaces global refs and
+  // defaults; otherwise global refs merge over the defaults.
   const refs = options?.sources
     ? undefined
     : mergeAndParseRefs(config.packages);
 
-  const store = await bootStore({
+  const { store, packages } = await bootStore({
     cwd,
     sources: options?.sources,
     refs,
+    trace: config.trace,
+    prefixes: config.prefixes,
   });
 
   return {
     store,
     config,
     cwd,
+    packages,
     dispose: () => store.dispose(),
   };
 }
-
-// ---------------------------------------------------------------------------
-// Ref merging
-// ---------------------------------------------------------------------------
-
-/**
- * Merge global refs, project config packages, and defaults into a final
- * parsed PackageRef array.
- *
- * Priority: project packages > global refs > hardcoded defaults.
- * Merging is by package name — a project entry for "@canonical/foo"
- * overrides the global entry for the same package.
- */
-function mergeAndParseRefs(
-  projectPackages?: ReadonlyArray<RawPackageEntry>,
-): PackageRef[] {
-  const globalEntries = readGlobalRefs();
-
-  // If neither project nor global defines packages, return undefined
-  // so resolvePackages() uses hardcoded defaults.
-  if (
-    (!projectPackages || projectPackages.length === 0) &&
-    globalEntries.length === 0
-  ) {
-    return DEFAULT_PACKAGES.map((pkg) => parsePackageEntry(pkg));
-  }
-
-  // Build a name → entry map, global first, project overrides.
-  const merged = new Map<string, RawPackageEntry>();
-
-  // Start with defaults (lowest priority)
-  for (const pkg of DEFAULT_PACKAGES) {
-    merged.set(pkg, pkg);
-  }
-
-  // Global overrides defaults
-  for (const entry of globalEntries) {
-    const name = typeof entry === "string" ? entry : entry.name;
-    merged.set(name, entry);
-  }
-
-  // Project overrides global
-  if (projectPackages) {
-    // When project explicitly declares packages, it's a full replacement
-    // of the package list — clear defaults and global, use project only.
-    merged.clear();
-    for (const entry of projectPackages) {
-      const name = typeof entry === "string" ? entry : entry.name;
-      merged.set(name, entry);
-    }
-  }
-
-  return [...merged.values()].map(parsePackageEntry);
-}

package/src/domains/shared/sampleFormatters.ts

@@ -0,0 +1,47 @@
+/**
+ * Factory for sample command formatters.
+ *
+ * Every domain's sample formatter follows the same pattern: a count
+ * header, then each item rendered via the domain's lookup formatter.
+ * This factory eliminates the duplication.
+ */
+
+import type { Formatters } from "./formatters.js";
+import type { SampleOutput } from "./types/index.js";
+
+/**
+ * Create a three-mode formatter for `pragma <domain> sample`.
+ *
+ * @param domain - plural domain label for the header (e.g. "standards")
+ * @param renderItem - renders one item; receives the item and the mode
+ */
+export default function createSampleFormatters<T>(
+  domain: string,
+  renderItem: (item: T, mode: "plain" | "llm") => string,
+): Formatters<SampleOutput<T>> {
+  return {
+    plain(output) {
+      const header = `Showing ${output.samples.length} of ${output.totalCount} ${domain}\n`;
+      const items = output.samples.map((item) => renderItem(item, "plain"));
+      return header + items.join("\n\n");
+    },
+
+    llm(output) {
+      const header = `Showing ${output.samples.length} of ${output.totalCount} ${domain}\n`;
+      const items = output.samples.map((item) => renderItem(item, "llm"));
+      return header + items.join("\n\n");
+    },
+
+    json(output) {
+      return JSON.stringify(
+        {
+          samples: output.samples,
+          totalCount: output.totalCount,
+          nextSteps: output.nextSteps,
+        },
+        null,
+        2,
+      );
+    },
+  };
+}

package/src/domains/shared/semanticPackage.ts

@@ -0,0 +1,112 @@
+/**
+ * Semantic package contracts and resolution orchestrator.
+ *
+ * A semantic package is a resolved graph dependency containing TTL
+ * definitions, instance data, and skills. Three loaders produce the
+ * same `SemanticPackage` shape — local (file/npm), git cache, and
+ * bundled (compiled binary). The orchestrator tries each loader in
+ * precedence order: local > git > bundled.
+ */
+
+import type { PackageRef } from "../refs/operations/parseRef.js";
+
+// ---------------------------------------------------------------------------
+// Contracts
+// ---------------------------------------------------------------------------
+
+/** A single TTL file's content with provenance annotation. */
+export interface GraphContent {
+  /** Original file path or virtual identifier (for provenance/debugging). */
+  readonly path: string;
+  /** TTL content string. */
+  readonly content: string;
+  /** RDF serialization format. */
+  readonly format: "turtle";
+}
+
+/** A discovered story-pack JSON file with its content. */
+export interface StoryFileEntry {
+  /**
+   * Original file path, or a virtual identifier for embedded sources
+   * (e.g. `(bundled)/…`) — for provenance/debugging, not guaranteed to
+   * exist on disk.
+   */
+  readonly path: string;
+  /** The file's parsed JSON — validated by the story-pack compiler. */
+  readonly definition: unknown;
+}
+
+export interface SkillEntry {
+  /** Absolute path to the skill directory (must exist on disk for symlinking). */
+  readonly dir: string;
+  /** Skill folder name (e.g. "anatomy-author"). */
+  readonly folderName: string;
+}
+
+/** A resolved graph package. All loaders produce this uniform shape. */
+export interface SemanticPackage {
+  /** npm package name (e.g. "@canonical/design-system"). */
+  readonly name: string;
+  /** Version string from package.json. */
+  readonly version: string;
+  /** How this package was resolved. */
+  readonly source: "local" | "git" | "bundled";
+  /** TTL graph content to load into the ke store. */
+  readonly graphs: GraphContent[];
+  /** Skills available in this package. */
+  readonly skills: SkillEntry[];
+  /**
+   * Raw story-pack files shipped by this package (`stories/*.json`).
+   * Parsed JSON, validated at compile time so one bad file cannot break boot.
+   */
+  readonly stories: StoryFileEntry[];
+}
+
+/**
+ * Resolves a package reference to a SemanticPackage.
+ * Returns `undefined` if this loader cannot resolve the given ref.
+ * May be async (e.g. BundledLoader reads blob content asynchronously).
+ */
+export interface PackageLoader {
+  /** Loader identity for diagnostics. */
+  readonly name: "local" | "git" | "bundled";
+  /** Attempt to resolve a package reference. */
+  resolve(
+    ref: PackageRef,
+  ): SemanticPackage | undefined | Promise<SemanticPackage | undefined>;
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve package references to semantic packages using a loader chain.
+ *
+ * Tries each loader in array order for each ref. The first loader that
+ * returns a result wins — subsequent loaders are skipped for that ref.
+ * Refs that no loader can resolve are silently dropped.
+ *
+ * @param refs - Parsed package references from config merge.
+ * @param loaders - Loaders in precedence order (local > git > bundled).
+ * @returns Array of resolved semantic packages.
+ */
+export async function resolveSemanticPackages(
+  refs: ReadonlyArray<PackageRef>,
+  loaders: ReadonlyArray<PackageLoader>,
+): Promise<SemanticPackage[]> {
+  const packages: SemanticPackage[] = [];
+
+  for (const ref of refs) {
+    let resolved: SemanticPackage | undefined;
+    for (const loader of loaders) {
+      resolved = await loader.resolve(ref);
+      if (resolved) break;
+    }
+    if (resolved) {
+      packages.push(resolved);
+    }
+  }
+
+  return packages;
+}

package/src/domains/shared/stories/compileLookupCommand.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import type { PragmaContext } from "../context.js";
+import type { LookupResult } from "../contracts.js";
+import compileLookupCommand from "./compileLookupCommand.js";
+import type { LookupStory } from "./types.js";
+
+interface FakeEntity {
+  readonly name: string;
+  readonly detail: string;
+}
+
+function makeStory(
+  overrides: Partial<LookupStory<FakeEntity, string>> = {},
+): LookupStory<FakeEntity, string> {
+  return {
+    noun: "thing",
+    description: "Look up things",
+    toolDescription: "Look up things over MCP.",
+    namesDescription: "Thing names",
+    detailedParam: { description: "Show details" },
+    examples: ["pragma thing lookup a"],
+    resolve: async (_rt, names) => {
+      const results = names
+        .filter((name) => name !== "missing")
+        .map((name) => ({ name, detail: `detail-${name}` }));
+      const errors: LookupResult<FakeEntity>["errors"] = names
+        .filter((name) => name === "missing")
+        .map((name) => ({
+          query: name,
+          code: "ENTITY_NOT_FOUND",
+          message: `thing "${name}" not found.`,
+        }));
+      return { results, errors };
+    },
+    toFmtInput: (entity, view) =>
+      view.detailed ? `${entity.name}:${entity.detail}` : entity.name,
+    formatters: {
+      plain: (text) => `plain:${text}`,
+      llm: (text) => `llm:${text}`,
+      json: (text) => JSON.stringify(text),
+    },
+    ...overrides,
+  };
+}
+
+function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
+  return {
+    cwd: "/tmp",
+    globalFlags: { llm: false, format: "text" as const, verbose: false },
+    ...overrides,
+  } as PragmaContext;
+}
+
+async function executeText(
+  story: LookupStory<FakeEntity, string>,
+  params: Record<string, unknown>,
+  ctx: PragmaContext,
+): Promise<string> {
+  const cmd = compileLookupCommand(ctx, story);
+  const result = await cmd.execute(params, ctx);
+  if (result.tag !== "output") throw new Error("expected output result");
+  return result.render.plain(result.value);
+}
+
+describe("compileLookupCommand", () => {
+  it("projects names, detailed, and extra parameters", () => {
+    const story = makeStory({
+      params: [
+        { name: "extra", type: "boolean", description: "extra flag" },
+        { name: "mcpOnly", type: "boolean", description: "x", surfaces: "mcp" },
+      ],
+      parameterGroups: { Extras: ["extra"] },
+    });
+    const cmd = compileLookupCommand(makeCtx(), story);
+    expect(cmd.path).toEqual(["thing", "lookup"]);
+    expect(cmd.parameters.map((p) => p.name)).toEqual([
+      "names",
+      "detailed",
+      "extra",
+    ]);
+    const names = cmd.parameters.at(0);
+    expect(names?.type).toBe("multiselect");
+    expect(names?.positional).toBe(true);
+    expect(names?.required).toBe(true);
+    expect(cmd.parameterGroups).toEqual({ Extras: ["extra"] });
+  });
+
+  it("omits the detailed parameter when the story has none", () => {
+    const cmd = compileLookupCommand(
+      makeCtx(),
+      makeStory({ detailedParam: undefined }),
+    );
+    expect(cmd.parameters.map((p) => p.name)).toEqual(["names"]);
+  });
+
+  it("renders each result and appends an errors section", async () => {
+    const text = await executeText(
+      makeStory(),
+      { names: ["a", "missing"] },
+      makeCtx(),
+    );
+    expect(text).toContain("plain:a");
+    expect(text).toContain("Errors:");
+    expect(text).toContain('thing "missing" not found.');
+  });
+
+  it("is summary by default and detailed with the flag", async () => {
+    const summary = await executeText(makeStory(), { names: ["a"] }, makeCtx());
+    expect(summary).toBe("plain:a");
+
+    const detailed = await executeText(
+      makeStory(),
+      { names: ["a"], detailed: true },
+      makeCtx(),
+    );
+    expect(detailed).toBe("plain:a:detail-a");
+  });
+
+  it("accepts the legacy single name parameter", async () => {
+    const text = await executeText(makeStory(), { name: "a" }, makeCtx());
+    expect(text).toBe("plain:a");
+  });
+
+  it("throws the story's empty-names error when no names are given", async () => {
+    const story = makeStory({
+      emptyNamesError: () => PragmaError.invalidInput("names", "(empty)"),
+    });
+    const cmd = compileLookupCommand(makeCtx(), story);
+    await expect(cmd.execute({ names: [] }, makeCtx())).rejects.toThrow(
+      PragmaError,
+    );
+  });
+
+  it("exposes an ink renderer only when the story defines one", async () => {
+    const story = makeStory({
+      renderInk: (result, view) =>
+        `ink:${result.results.length}:${view.detailed}`,
+    });
+    const cmd = compileLookupCommand(makeCtx(), story);
+    const result = await cmd.execute({ names: ["a"] }, makeCtx());
+    if (result.tag !== "output") throw new Error("expected output result");
+    expect(result.render.ink?.(result.value)).toBe("ink:1:false");
+  });
+});