@canonical/pragma-cli 0.29.0 → 0.31.0

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/resolveLookupExitCode.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import type { LookupResult } from "./contracts.js";
+import resolveLookupExitCode from "./resolveLookupExitCode.js";
+
+function makeResult<T>(
+  results: T[],
+  errors: LookupResult<T>["errors"],
+): LookupResult<T> {
+  return { results, errors };
+}
+
+describe("resolveLookupExitCode", () => {
+  it("returns 0 when at least one result was found", () => {
+    const result = makeResult(
+      [{ name: "ok" }],
+      [{ query: "miss", code: "ENTITY_NOT_FOUND", message: "not found" }],
+    );
+    expect(resolveLookupExitCode(result)).toBe(0);
+  });
+
+  it("returns 0 when there are no errors", () => {
+    expect(resolveLookupExitCode(makeResult([{ name: "ok" }], []))).toBe(0);
+  });
+
+  it("maps an all-not-found lookup to exit 1", () => {
+    const result = makeResult(
+      [],
+      [{ query: "x", code: "ENTITY_NOT_FOUND", message: "not found" }],
+    );
+    expect(resolveLookupExitCode(result)).toBe(1);
+  });
+
+  it("maps an all-invalid-input lookup to exit 3", () => {
+    const result = makeResult(
+      [],
+      [{ query: "x", code: "INVALID_INPUT", message: "bad" }],
+    );
+    expect(resolveLookupExitCode(result)).toBe(3);
+  });
+
+  it("falls back to exit 1 for an unrecognised error code", () => {
+    const result = makeResult(
+      [],
+      [{ query: "x", code: "NOT_A_REAL_CODE", message: "?" }],
+    );
+    expect(resolveLookupExitCode(result)).toBe(1);
+  });
+});

package/src/domains/shared/resolveLookupExitCode.ts

@@ -0,0 +1,42 @@
+/**
+ * Compute the process exit code for a lookup result.
+ *
+ * A lookup that produced at least one result — even alongside some failures —
+ * is a partial success and exits 0. A lookup where every query failed exits
+ * non-zero, mapping the first error's code to its exit code so callers and
+ * scripts can detect the failure. The errors are still rendered inline for the
+ * human reader.
+ */
+
+import { ERROR_CODES, type ErrorCode } from "#error";
+// mapExitCode is imported by its direct path, not the #pipeline barrel: the
+// barrel re-exports runCli/createProgram, which would form an import cycle
+// through this shared utility and break module initialization.
+import mapExitCode from "../../pipeline/mapExitCode.js";
+import type { LookupResult } from "./contracts.js";
+
+/** Default non-zero exit when a lookup error carries an unrecognised code. */
+const FALLBACK_LOOKUP_EXIT_CODE = 1;
+
+/** Narrow an arbitrary error-code string to a known {@link ErrorCode}. */
+function isErrorCode(code: string | undefined): code is ErrorCode {
+  return (
+    code !== undefined && (ERROR_CODES as readonly string[]).includes(code)
+  );
+}
+
+/**
+ * Resolve the exit code a lookup command should report.
+ *
+ * @param result - The resolved lookup result.
+ * @returns 0 on success/partial success, else the mapped non-zero exit code.
+ */
+export default function resolveLookupExitCode<T>(
+  result: LookupResult<T>,
+): number {
+  if (result.results.length > 0 || result.errors.length === 0) return 0;
+  const firstCode = result.errors.at(0)?.code;
+  return isErrorCode(firstCode)
+    ? mapExitCode(firstCode)
+    : FALLBACK_LOOKUP_EXIT_CODE;
+}

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,7 +37,8 @@ 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);
@@ -53,6 +48,7 @@ export async function bootPragma(options?: {
     sources: options?.sources,
     refs,
     trace: config.trace,
+    prefixes: config.prefixes,
   });
 
   return {
@@ -63,58 +59,3 @@ 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 entry of DEFAULT_PACKAGES) {
-    const name = typeof entry === "string" ? entry : entry.name;
-    merged.set(name, entry);
-  }
-
-  // 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/semanticPackage.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import type { PackageRef } from "../refs/operations/parseRef.js";
+import type { PackageLoader, SemanticPackage } from "./semanticPackage.js";
+import { resolveSemanticPackages } from "./semanticPackage.js";
+
+function makeRef(pkg: string): PackageRef {
+  return { kind: "npm", pkg };
+}
+
+function makePackage(name: string): SemanticPackage {
+  return {
+    name,
+    version: "1.0.0",
+    source: "local",
+    graphs: [{ path: `${name}/data.ttl`, content: "", format: "turtle" }],
+    skills: [],
+    stories: [],
+  };
+}
+
+describe("resolveSemanticPackages", () => {
+  it("resolves each ref through the loader chain", async () => {
+    const loader: PackageLoader = {
+      name: "local",
+      resolve: (ref) => makePackage(ref.pkg),
+    };
+
+    const packages = await resolveSemanticPackages(
+      [makeRef("a"), makeRef("b")],
+      [loader],
+    );
+
+    expect(packages.map((pkg) => pkg.name)).toEqual(["a", "b"]);
+  });
+
+  it("drops refs no loader can resolve", async () => {
+    const loader: PackageLoader = {
+      name: "local",
+      resolve: (ref) => (ref.pkg === "a" ? makePackage("a") : undefined),
+    };
+
+    const packages = await resolveSemanticPackages(
+      [makeRef("a"), makeRef("b")],
+      [loader],
+    );
+
+    expect(packages.map((pkg) => pkg.name)).toEqual(["a"]);
+  });
+
+  // Regression: the bundled loader returns ONE cached aggregate package for
+  // every ref it serves. Including it once per ref loaded its graphs into
+  // the store multiple times, re-minting blank nodes on each parse — which
+  // triplicated blank-node subgraphs (standard do/don't examples) whenever
+  // all three default refs fell back to the bundled data.
+  it("includes a package instance resolved for multiple refs only once", async () => {
+    const aggregate = makePackage("(bundled)");
+    const loader: PackageLoader = {
+      name: "bundled",
+      resolve: () => aggregate,
+    };
+
+    const packages = await resolveSemanticPackages(
+      [makeRef("a"), makeRef("b"), makeRef("c")],
+      [loader],
+    );
+
+    expect(packages).toHaveLength(1);
+    expect(packages[0]).toBe(aggregate);
+  });
+
+  it("keeps distinct packages from a mixed loader chain", async () => {
+    const aggregate = makePackage("(bundled)");
+    const git: PackageLoader = {
+      name: "git",
+      resolve: (ref) => (ref.pkg === "a" ? makePackage("a") : undefined),
+    };
+    const bundled: PackageLoader = {
+      name: "bundled",
+      resolve: () => aggregate,
+    };
+
+    const packages = await resolveSemanticPackages(
+      [makeRef("a"), makeRef("b"), makeRef("c")],
+      [git, bundled],
+    );
+
+    expect(packages.map((pkg) => pkg.name)).toEqual(["a", "(bundled)"]);
+  });
+});

package/src/domains/shared/semanticPackage.ts

@@ -24,7 +24,18 @@ export interface GraphContent {
   readonly format: "turtle";
 }
 
-/** A discovered skill directory with its filesystem path. */
+/** 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;
@@ -42,8 +53,20 @@ export interface SemanticPackage {
   readonly source: "local" | "git" | "bundled";
   /** TTL graph content to load into the ke store. */
   readonly graphs: GraphContent[];
+  /**
+   * Namespace prefixes this package declares, merged over the core prefix
+   * map at boot (see {@link resolvePrefixes}). Read from the package's
+   * `package.json` `pragma.prefixes` field. Absent when the package
+   * declares none.
+   */
+  readonly prefixes?: Readonly<Record<string, string>>;
   /** 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[];
 }
 
 /**
@@ -71,15 +94,22 @@ export interface PackageLoader {
  * returns a result wins — subsequent loaders are skipped for that ref.
  * Refs that no loader can resolve are silently dropped.
  *
+ * A package instance that resolves for more than one ref (the bundled
+ * loader returns one cached aggregate for every ref it serves) is
+ * included only once: loading the same graphs repeatedly re-mints their
+ * blank nodes on each parse, duplicating blank-node subgraphs (e.g.
+ * standard do/don't examples) in the store.
+ *
  * @param refs - Parsed package references from config merge.
  * @param loaders - Loaders in precedence order (local > git > bundled).
- * @returns Array of resolved semantic packages.
+ * @returns Array of resolved semantic packages, deduplicated by identity.
  */
 export async function resolveSemanticPackages(
   refs: ReadonlyArray<PackageRef>,
   loaders: ReadonlyArray<PackageLoader>,
 ): Promise<SemanticPackage[]> {
   const packages: SemanticPackage[] = [];
+  const seen = new Set<SemanticPackage>();
 
   for (const ref of refs) {
     let resolved: SemanticPackage | undefined;
@@ -87,7 +117,8 @@ export async function resolveSemanticPackages(
       resolved = await loader.resolve(ref);
       if (resolved) break;
     }
-    if (resolved) {
+    if (resolved && !seen.has(resolved)) {
+      seen.add(resolved);
       packages.push(resolved);
     }
   }

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");
+  });
+});

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

@@ -0,0 +1,102 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+  type ParameterDefinition,
+} from "@canonical/cli-core";
+import type { PragmaContext } from "../context.js";
+import type { LookupResult } from "../contracts.js";
+import { renderLookupResults } from "../formatters.js";
+import resolveLookupExitCode from "../resolveLookupExitCode.js";
+import normalizeNames from "./normalizeNames.js";
+import projectCliParameters from "./projectCliParameters.js";
+import resolveLookupDetailed from "./resolveLookupDetailed.js";
+import type { LookupStory, LookupStoryView } from "./types.js";
+
+/**
+ * Compile a lookup story into its CLI `CommandDefinition` projection.
+ *
+ * Owns the shared execute skeleton: normalize the positional `names`,
+ * reject empty input when the story defines an error, resolve the batch,
+ * then render each result through the story's formatters with the shared
+ * multi-result renderer (which appends the "Errors:" section).
+ */
+export default function compileLookupCommand<TDetailed, TFmtInput>(
+  ctx: PragmaContext,
+  story: LookupStory<TDetailed, TFmtInput>,
+): CommandDefinition {
+  interface LookupOutput {
+    readonly result: LookupResult<TDetailed>;
+    readonly view: LookupStoryView;
+  }
+
+  return {
+    path: [story.noun, "lookup"],
+    description: story.description,
+    parameters: buildParameters(story),
+    ...(story.parameterGroups && { parameterGroups: story.parameterGroups }),
+    meta: {
+      examples: story.examples,
+    },
+    execute: async (
+      params: Record<string, unknown>,
+    ): Promise<CommandResult> => {
+      const names = normalizeNames(params.names, params.name);
+      if (names.length === 0 && story.emptyNamesError) {
+        throw story.emptyNamesError();
+      }
+
+      const view: LookupStoryView = {
+        surface: "cli",
+        detailed: resolveLookupDetailed(story, "cli", params),
+        params,
+      };
+      const result = await story.resolve(ctx, names, params, view);
+      const renderInk = story.renderInk;
+
+      return createOutputResult<LookupOutput>(
+        { result, view },
+        {
+          plain: (output) =>
+            renderLookupResults({
+              ctx,
+              result: output.result,
+              formatters: story.formatters,
+              mapResult: (entity) => story.toFmtInput(entity, output.view),
+            }),
+          ...(renderInk && {
+            ink: (output: LookupOutput) =>
+              renderInk(output.result, output.view),
+          }),
+        },
+        resolveLookupExitCode(result),
+      );
+    },
+  };
+}
+
+function buildParameters<TDetailed, TFmtInput>(
+  story: LookupStory<TDetailed, TFmtInput>,
+): ParameterDefinition[] {
+  const names: ParameterDefinition = {
+    name: "names",
+    description: story.namesDescription,
+    type: "multiselect",
+    positional: true,
+    required: true,
+    ...(story.complete && { complete: story.complete }),
+  };
+
+  const detailed: ParameterDefinition[] = story.detailedParam
+    ? [
+        {
+          name: "detailed",
+          description: story.detailedParam.description,
+          type: "boolean",
+          default: false,
+        },
+      ]
+    : [];
+
+  return [names, ...detailed, ...projectCliParameters(story.params ?? [])];
+}