@canonical/pragma-cli 0.24.0 → 0.26.0

package/src/domains/shared/bootStore.ts

@@ -7,27 +7,43 @@
  * @note Impure — reads filesystem, creates ke store.
  */
 
+import { existsSync } from "node:fs";
 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 type { PackageRef } from "../refs/operations/parseRef.js";
+import { 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.
+ * Convention-based TTL directories to scan in each package.
+ * Only directories that exist are globbed — packages that lack
+ * a `data/` or `definitions/` dir are silently skipped.
  */
-export function defaultSources(): SourceSpec[] {
+const TTL_DIRS: readonly { dir: string; glob: string }[] = [
+  { dir: "definitions", glob: "definitions/**/*.ttl" },
+  { dir: "data", glob: "data/**/*.ttl" },
+];
+
+/**
+ * Resolve default TTL sources from resolved packages.
+ *
+ * Uses convention-based TTL discovery: definitions and data globs
+ * relative to each package root. Only adds globs for directories
+ * that actually exist in the package.
+ *
+ * @param refs - Parsed package references. Omit for defaults.
+ */
+export function defaultSources(refs?: ReadonlyArray<PackageRef>): SourceSpec[] {
   const sources: SourceSpec[] = [];
-  const resolved = resolvePackages();
+  const resolved = resolvePackages(refs);
 
-  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));
+  for (const { dir } of resolved) {
+    for (const entry of TTL_DIRS) {
+      if (existsSync(join(dir, entry.dir))) {
+        sources.push(join(dir, entry.glob));
+      }
     }
   }
 
@@ -35,14 +51,14 @@ export function defaultSources(): SourceSpec[] {
 }
 
 export interface BootStoreOptions {
-  /** Override config (skip reading from disk). */
-  config?: PragmaConfig;
-  /** Override sources (skip config sources field). */
+  /** Override sources (skip filesystem resolution). */
   sources?: SourceSpec[];
   /** Working directory for resolving relative paths. */
   cwd?: string;
   /** Cache path for serialized store. */
   cache?: string;
+  /** Parsed package references for ref-based resolution. */
+  refs?: ReadonlyArray<PackageRef>;
 }
 
 /**
@@ -53,7 +69,7 @@ export interface BootStoreOptions {
 export async function bootStore(
   options: BootStoreOptions = {},
 ): Promise<Store> {
-  const sources = options.sources ?? defaultSources();
+  const sources = options.sources ?? defaultSources(options.refs);
 
   try {
     const store = await createStore({

package/src/domains/shared/packages.ts

@@ -1,53 +1,39 @@
 /**
- * Design system package registry.
+ * Design system package registry and resolution.
  *
- * Single source of truth for all external packages that provide TTL data
- * and/or agent skills. Both `bootStore` (TTL sources) and `resolveSkillSources`
- * (skill discovery) derive their paths from this 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)
  *
- * Each entry declares:
- * - `pkg`    — npm package name (resolved via `require.resolve`)
- * - `ttl`    — glob patterns for TTL data, relative to the package root
- * - `skills` — subpath to the skills directory, or `undefined` if none
+ * The package list itself is configurable via pragma.config.json `packages`
+ * field. When absent, the hardcoded DEFAULT_PACKAGES are used.
  */
 
+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";
 
 const require = createRequire(import.meta.url);
 
-export interface PackageDefinition {
-  /** npm package name. */
-  readonly pkg: string;
-  /** Glob patterns for TTL data (relative to package root). */
-  readonly ttl: readonly string[];
-  /** Subpath to skills directory, or undefined if the package has no skills. */
-  readonly skills: string | undefined;
-}
+// ---------------------------------------------------------------------------
+// Default package registry (used when config.packages is absent)
+// ---------------------------------------------------------------------------
 
-export const PACKAGES: readonly PackageDefinition[] = [
-  {
-    pkg: "@canonical/design-system",
-    ttl: ["definitions/ontology.ttl", "data/**/*.ttl"],
-    skills: "skills",
-  },
-  {
-    pkg: "@canonical/anatomy-dsl",
-    ttl: ["definitions/**/*.ttl"],
-    skills: undefined,
-  },
-  {
-    pkg: "@canonical/code-standards",
-    ttl: ["definitions/**/*.ttl", "data/**/*.ttl"],
-    skills: "skills",
-  },
-  {
-    pkg: "@canonical/pragma-cli",
-    ttl: [],
-    skills: "skills",
-  },
+/** 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;
@@ -55,22 +41,86 @@ export interface ResolvedPackage {
   readonly dir: string;
 }
 
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
 /**
- * Resolve installed packages from the registry via `require.resolve`.
- * Package-manager agnostic — works with bun, npm, pnpm, yarn.
- * Skips packages that are not installed.
+ * 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(): ResolvedPackage[] {
+export function resolvePackages(
+  refs?: ReadonlyArray<PackageRef>,
+): ResolvedPackage[] {
+  if (!refs) {
+    return resolveNpmPackages(DEFAULT_PACKAGES);
+  }
+
   const resolved: ResolvedPackage[] = [];
-  for (const { pkg } of PACKAGES) {
-    try {
-      resolved.push({
-        pkg,
-        dir: dirname(require.resolve(`${pkg}/package.json`)),
-      });
-    } catch {
-      // package not installed — skip
+
+  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
+  }
+}

package/src/domains/shared/runtime.ts

@@ -10,7 +10,14 @@
 
 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 type { PragmaRuntime } from "./types/index.js";
 
 export type { PragmaRuntime } from "./types/index.js";
@@ -18,9 +25,11 @@ export type { PragmaRuntime } from "./types/index.js";
 /**
  * Create a fully initialized `PragmaRuntime`.
  *
- * Reads config from `cwd` (defaults to `process.cwd()`), boots the ke
- * store from resolved sources, and returns a runtime ready for operation
- * calls. The caller owns the lifecycle and must call `dispose()`.
+ * Reads config from `cwd` (defaults to `process.cwd()`), merges global
+ * and project package refs, boots the ke store from resolved sources,
+ * and returns a runtime ready for operation calls.
+ *
+ * The caller owns the lifecycle and must call `dispose()`.
  *
  * @param options.cwd - Working directory for config and source resolution.
  * @param options.sources - Override sources for testing (skip filesystem resolution).
@@ -33,9 +42,16 @@ export async function bootPragma(options?: {
 }): Promise<PragmaRuntime> {
   const cwd = options?.cwd ?? process.cwd();
   const config = readConfig(cwd);
+
+  // Merge package refs: project overrides global, both override defaults.
+  const refs = options?.sources
+    ? undefined
+    : mergeAndParseRefs(config.packages);
+
   const store = await bootStore({
     cwd,
     sources: options?.sources,
+    refs,
   });
 
   return {
@@ -45,3 +61,57 @@ export async function bootPragma(options?: {
     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/skill/helpers/resolveSkillSources.ts

@@ -1,5 +1,7 @@
+import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { PACKAGES, resolvePackages } from "../../shared/packages.js";
+import type { PackageRef } from "../../refs/operations/parseRef.js";
+import { resolvePackages } from "../../shared/packages.js";
 
 /** A resolved skill source directory from an installed package. */
 export interface SkillSource {
@@ -10,24 +12,26 @@ export interface SkillSource {
 }
 
 /**
- * Resolve skill source directories from the shared package registry.
- * Package-manager agnostic -- works with bun, npm, pnpm, yarn.
+ * Resolve skill source directories from resolved packages.
  *
+ * Auto-detects skills by checking for a `skills/` subdirectory
+ * in each resolved package root.
+ *
+ * @param refs - Parsed package references. Omit for defaults.
  * @returns Array of resolved skill sources with absolute paths.
  * @note Impure
  */
-export default function resolveSkillSources(): SkillSource[] {
+export default function resolveSkillSources(
+  refs?: ReadonlyArray<PackageRef>,
+): SkillSource[] {
   const sources: SkillSource[] = [];
-  const resolved = resolvePackages();
+  const resolved = resolvePackages(refs);
 
   for (const { pkg, dir } of resolved) {
-    const def = PACKAGES.find((p) => p.pkg === pkg);
-    if (!def?.skills) continue;
-
-    sources.push({
-      dir: join(dir, def.skills),
-      packageName: pkg,
-    });
+    const skillsDir = join(dir, "skills");
+    if (existsSync(skillsDir)) {
+      sources.push({ dir: skillsDir, packageName: pkg });
+    }
   }
 
   return sources;

package/src/pipeline/resolveCommandKind.ts

@@ -8,7 +8,7 @@
 import type { CommandKind } from "./types.js";
 
 /** Commands that do not require the ke store to be booted. */
-const STORE_SKIP_COMMANDS = new Set(["setup", "mcp"]);
+const STORE_SKIP_COMMANDS = new Set(["setup", "mcp", "update-refs"]);
 
 function findCommandArg(argv: readonly string[]): string | undefined {
   const args = argv.slice(2);

package/src/pipeline/runCli.ts

@@ -1,5 +1,6 @@
 import type { GlobalFlags } from "@canonical/cli-core";
 import { CommanderError } from "commander";
+import { commands as refsCommands } from "../domains/refs/index.js";
 import { commands as setupCommands } from "../domains/setup/index.js";
 import type { PragmaContext } from "../domains/shared/context.js";
 import type { PragmaRuntime } from "../domains/shared/runtime.js";
@@ -140,7 +141,7 @@ async function runStoreSkip(
     globalFlags,
     interactive: runInteractiveCommand,
   };
-  const commands = [...setupCommands()];
+  const commands = [...setupCommands(), ...refsCommands()];
   const program = createProgram(commands, stubCtx);
 
   try {

package/src/testing/integration/boot.test.ts

@@ -5,9 +5,12 @@
  * consistency from the canonical fixture.
  */
 
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { afterAll, describe, expect, it } from "vitest";
 import { listBlocks } from "../../domains/block/operations/index.js";
 import type { PragmaRuntime } from "../../domains/shared/runtime.js";
+import { bootPragma } from "../../domains/shared/runtime.js";
 import createTestRuntime from "../helpers/createTestRuntime.js";
 
 describe("PragmaRuntime boot", () => {
@@ -54,6 +57,41 @@ describe("PragmaRuntime boot", () => {
     expect(names).toContain("Button");
   });
 
+  it("boots with file:// package ref", async () => {
+    // Create a temp "package" with TTL in the convention structure
+    const { mkdirSync, copyFileSync, writeFileSync } = await import("node:fs");
+    const { join } = await import("node:path");
+
+    const fixturesDir = new URL("../fixtures/", import.meta.url).pathname;
+    const tmpPkg = mkdtempSync(join(tmpdir(), "pragma-ref-pkg-"));
+    const dataDir = join(tmpPkg, "data");
+    mkdirSync(dataDir, { recursive: true });
+    copyFileSync(
+      join(fixturesDir, "canonical.ttl"),
+      join(dataDir, "canonical.ttl"),
+    );
+
+    // Create a temp project dir with config pointing to the file:// package
+    const tmpProject = mkdtempSync(join(tmpdir(), "pragma-ref-project-"));
+    writeFileSync(
+      join(tmpProject, "pragma.config.json"),
+      JSON.stringify({
+        packages: [{ name: "@test/fixture", source: `file://${tmpPkg}` }],
+      }),
+    );
+
+    const rt = await bootPragma({ cwd: tmpProject });
+    runtimes.push(rt);
+
+    expect(rt.store).toBeDefined();
+    expect(rt.config.packages).toHaveLength(1);
+
+    // Clean up
+    const { rmSync } = await import("node:fs");
+    rmSync(tmpPkg, { recursive: true, force: true });
+    rmSync(tmpProject, { recursive: true, force: true });
+  });
+
   it("two runtimes produce identical store content", async () => {
     const rt1 = await createTestRuntime();
     const rt2 = await createTestRuntime();