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

package/src/domains/setup/helpers/runSetupTask.ts

@@ -1,18 +1,17 @@
-import { createInterface } from "node:readline";
 import {
+  answerPromptWithDefaults,
   type CommandResult,
   createExitResult,
   createOutputResult,
   formatEffectLine,
   isVisibleEffect,
+  runGeneratorTask,
 } from "@canonical/cli-core";
-import {
-  dryRun,
-  type Effect,
-  runTask,
-  runUndo,
-  type Task,
-} from "@canonical/task";
+import { dryRun, type Effect, type Task } from "@canonical/task";
+import { runUndo } from "@canonical/task/node";
+import createInteractivePromptSession, {
+  type InteractivePromptSession,
+} from "../../shared/createInteractivePromptSession.js";
 import type { LogLevel } from "../types.js";
 
 /** Options controlling how {@link runSetupTask} executes. */
@@ -26,55 +25,41 @@ export interface SetupTaskOptions {
 }
 
 /**
- * Auto-confirm prompt handler for `--yes` mode.
- *
- * @param effect - A Prompt effect to resolve.
- * @returns The default value for the prompt type.
+ * Pick the prompt handler for a run: auto-confirm defaults under `--yes`, else
+ * an interactive readline session (whose lifetime the caller owns via the
+ * returned `dispose`).
  */
-function autoConfirmHandler(
-  effect: Effect & { _tag: "Prompt" },
-): Promise<unknown> {
-  const q = effect.question;
-  if (q.type === "confirm") return Promise.resolve(q.default ?? true);
-  if (q.type === "select")
-    return Promise.resolve(q.default ?? q.choices[0]?.value);
-  if (q.type === "multiselect") return Promise.resolve(q.default ?? []);
-  return Promise.resolve(q.default ?? "");
+function selectPromptHandler(yes: boolean): {
+  handler: (effect: Effect & { _tag: "Prompt" }) => Promise<unknown>;
+  wasInterrupted: () => boolean;
+  dispose: () => void;
+} {
+  if (yes) {
+    return {
+      handler: answerPromptWithDefaults,
+      wasInterrupted: () => false,
+      dispose: () => {},
+    };
+  }
+  const session: InteractivePromptSession = createInteractivePromptSession();
+  return {
+    handler: session.answerPrompt,
+    wasInterrupted: session.wasInterrupted,
+    dispose: session.dispose,
+  };
 }
 
 /**
- * Interactive prompt handler using readline on stdin/stderr.
- * Supports confirm prompts; other types fall back to defaults.
- *
- * @param effect - A Prompt effect to resolve interactively.
- * @returns The user's answer.
+ * Build a task log sink that writes to stderr, hiding debug lines unless
+ * verbose is set.
  */
-async function interactivePromptHandler(
-  effect: Effect & { _tag: "Prompt" },
-): Promise<unknown> {
-  const q = effect.question;
-
-  if (q.type === "confirm") {
-    const defaultYes = q.default !== false;
-    const hint = defaultYes ? "Y/n" : "y/N";
-    const rl = createInterface({
-      input: process.stdin,
-      output: process.stderr,
-    });
-
-    const answer = await new Promise<string>((resolve) => {
-      rl.question(`${q.message} [${hint}] `, (ans) => {
-        rl.close();
-        resolve(ans.trim());
-      });
-    });
-
-    if (answer === "") return defaultYes;
-    return answer.toLowerCase().startsWith("y");
-  }
-
-  // Non-confirm prompts fall back to defaults in D15
-  return q.default;
+function createStderrLogger(
+  verbose: boolean,
+): (level: LogLevel, message: string) => void {
+  return (level, message) => {
+    if (level === "debug" && !verbose) return;
+    process.stderr.write(`${message}\n`);
+  };
 }
 
 /**
@@ -150,7 +135,8 @@ function formatDryRunJson(effects: readonly Effect[]): string {
  * Supports three execution modes:
  * - `--dry-run`: collects effects without executing, formats for display.
  * - `--undo`: walks the task tree, collects undo operations, executes in reverse.
- * - default: interactive execution with readline-based prompts on stderr.
+ * - default: execution through {@link runGeneratorTask}, with readline-based
+ *   prompts on stderr.
  *
  * @param task - The setup Task to execute.
  * @param options - Execution options (dryRun, undo, yes, verbose, llm, format).
@@ -182,14 +168,12 @@ export default async function runSetupTask(
 
   // Undo mode: walk the task tree, collect undos, execute in reverse
   if (options.undo) {
-    const promptHandler = options.yes
-      ? autoConfirmHandler
-      : interactivePromptHandler;
-
-    const onLog = (level: LogLevel, message: string): void => {
-      if (level === "debug" && !verbose) return;
-      process.stderr.write(`${message}\n`);
-    };
+    const {
+      handler: promptHandler,
+      wasInterrupted,
+      dispose,
+    } = selectPromptHandler(options.yes ?? false);
+    const onLog = createStderrLogger(verbose);
 
     try {
       const result = await runUndo(task, { promptHandler, onLog });
@@ -202,28 +186,36 @@ export default async function runSetupTask(
       }
       return createExitResult(0);
     } catch (err) {
+      if (wasInterrupted()) {
+        return createExitResult(130);
+      }
       const message = err instanceof Error ? err.message : String(err);
       process.stderr.write(`Undo failed: ${message}\n`);
       return createExitResult(1);
+    } finally {
+      dispose();
     }
   }
 
   // Production execution
-  const promptHandler = options.yes
-    ? autoConfirmHandler
-    : interactivePromptHandler;
-
-  const onLog = (level: LogLevel, message: string): void => {
-    if (level === "debug" && !verbose) return;
-    process.stderr.write(`${message}\n`);
-  };
+  const {
+    handler: promptHandler,
+    wasInterrupted,
+    dispose,
+  } = selectPromptHandler(options.yes ?? false);
+  const onLog = createStderrLogger(verbose);
 
   try {
-    await runTask(task, { promptHandler, onLog });
+    await runGeneratorTask(task, { promptHandler, onLog });
     return createExitResult(0);
   } catch (err) {
+    if (wasInterrupted()) {
+      return createExitResult(130);
+    }
     const message = err instanceof Error ? err.message : String(err);
     process.stderr.write(`Setup failed: ${message}\n`);
     return createExitResult(1);
+  } finally {
+    dispose();
   }
 }

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

@@ -10,7 +10,12 @@ const mockExists =
 function mocks(
   existsPredicate: (path: string) => boolean,
 ): Map<string, (effect: Effect) => unknown> {
-  return new Map([["Exists", mockExists(existsPredicate)]]);
+  return new Map<string, (effect: Effect) => unknown>([
+    ["Exists", mockExists(existsPredicate)],
+    // An existing config reads back as an empty-but-valid JSON object, so a
+    // write merges into it rather than failing closed on the dry-run placeholder.
+    ["ReadFile", () => "{}"],
+  ]);
 }
 
 describe("setupMcp", () => {

package/src/domains/shared/bootStore.ts

@@ -1,85 +1,127 @@
 /**
- * Boot a ke store from pragma.config.json sources.
+ * Boot a ke store from resolved semantic packages.
  *
- * Reads configuration, resolves sources (defaults or overridden),
- * creates the store with registered prefixes, and wraps errors.
+ * 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 { existsSync } from "node:fs";
-import { join } from "node:path";
-import type { SourceSpec, Store } from "@canonical/ke";
-import { createStore } from "@canonical/ke";
+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 { resolvePackages } from "./packages.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";
-
-/**
- * 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.
- */
-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(refs);
-
-  for (const { dir } of resolved) {
-    for (const entry of TTL_DIRS) {
-      if (existsSync(join(dir, entry.dir))) {
-        sources.push(join(dir, entry.glob));
-      }
-    }
-  }
-
-  return sources;
-}
+import type { SemanticPackage } from "./semanticPackage.js";
+import { resolveSemanticPackages } from "./semanticPackage.js";
 
 export interface BootStoreOptions {
-  /** Override sources (skip filesystem resolution). */
+  /** 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 ref-based resolution. */
+  /** 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<Store> {
-  const sources = options.sources ?? defaultSources(options.refs);
-
+): 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: PREFIX_MAP,
+      sources: [],
+      prefixes,
       cache: options.cache,
       cwd: options.cwd,
+      plugins,
     });
-    return store;
+
+    return { store, packages };
   } catch (error) {
+    if (error instanceof PragmaError) throw error;
     throw PragmaError.storeError(
       error instanceof Error ? error.message : String(error),
       {

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

@@ -18,4 +18,15 @@ describe("compactUri", () => {
       "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,16 +1,21 @@
 /**
- * Convert a full URI to its compact prefixed form when a matching prefix exists.
- * Falls back to the original URI when no namespace matches.
+ * 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)) {
-      return `${prefix}:${fullUri.slice(namespace.length)}`;
+    if (!fullUri.startsWith(namespace)) continue;
+    if (best === undefined || namespace.length > best.namespace.length) {
+      best = { prefix, namespace };
     }
   }
 
-  return fullUri;
+  if (best === undefined) return fullUri;
+  return `${best.prefix}:${fullUri.slice(best.namespace.length)}`;
 }

package/src/domains/shared/context.ts

@@ -7,10 +7,10 @@
  * cli-core remains unaware of Store or FilterConfig.
  */
 
-import type { GlobalFlags, InteractiveHandler } from "@canonical/cli-core";
+import type { GlobalFlags, PromptSessionFactory } from "@canonical/cli-core";
 import type { PragmaRuntime } from "./types/index.js";
 
 export interface PragmaContext extends PragmaRuntime {
   readonly globalFlags: GlobalFlags;
-  readonly interactive?: InteractiveHandler | undefined;
+  readonly promptSession?: PromptSessionFactory | undefined;
 }

package/src/domains/shared/contracts.ts

@@ -50,13 +50,25 @@ export interface ListResult<T> {
     | { 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> {