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

package/src/pipeline/collectCommands.ts

@@ -4,12 +4,17 @@ import { commands as configCommands } from "../domains/config/index.js";
 import { commands as createCommands } from "../domains/create/index.js";
 import { doctorCommand } from "../domains/doctor/commands/index.js";
 import { commands as graphCommands } from "../domains/graph/index.js";
+import { commands as graphqlCommands } from "../domains/graphql/index.js";
 import { infoCommand, upgradeCommand } from "../domains/info/index.js";
-import { buildLlmCommand } from "../domains/llm/index.js";
+import {
+  buildCapabilitiesCommand,
+  buildLlmCommand,
+} from "../domains/llm/index.js";
 import { commands as modifierCommands } from "../domains/modifier/index.js";
 import { commands as ontologyCommands } from "../domains/ontology/index.js";
 import { commands as setupCommands } from "../domains/setup/index.js";
 import type { PragmaContext } from "../domains/shared/context.js";
+import { compilePackCommands } from "../domains/shared/stories/pack/index.js";
 import { commands as skillCommands } from "../domains/skill/index.js";
 import { commands as standardCommands } from "../domains/standard/index.js";
 import { commands as tierCommands } from "../domains/tier/index.js";
@@ -27,7 +32,7 @@ import { commands as tokenCommands } from "../domains/token/index.js";
 export default function collectCommands(
   ctx: PragmaContext,
 ): CommandDefinition[] {
-  return [
+  const builtIn: CommandDefinition[] = [
     ...configCommands(ctx),
     ...createCommands(),
     ...setupCommands(),
@@ -38,10 +43,18 @@ export default function collectCommands(
     ...blockCommands(ctx),
     ...ontologyCommands(ctx),
     ...graphCommands(ctx),
+    ...graphqlCommands(),
     ...skillCommands(ctx),
     doctorCommand,
     infoCommand,
     upgradeCommand,
     buildLlmCommand(ctx),
+    buildCapabilitiesCommand(),
   ];
+
+  // Story packs project onto the same surface; built-in nouns are reserved.
+  const reservedNouns = new Set(
+    builtIn.map((command) => command.path.at(0) ?? ""),
+  );
+  return [...builtIn, ...compilePackCommands(ctx, reservedNouns)];
 }

package/src/pipeline/renderError.ts

@@ -43,6 +43,14 @@ function renderErrorPlain(error: PragmaError): string {
     lines.push(`Valid options: ${error.validOptions.join(", ")}`);
   }
 
+  if (error.crossDomain) {
+    lines.push("");
+    lines.push(
+      `"${error.entity?.name ?? ""}" exists as a ${error.crossDomain.entityType}.`,
+    );
+    lines.push(`Run \`${error.crossDomain.cli}\``);
+  }
+
   if (error.recovery) {
     lines.push("");
     if (error.recovery.cli) {
@@ -82,6 +90,12 @@ function renderErrorLlm(error: PragmaError): string {
     lines.push(`Valid options: ${error.validOptions.join(", ")}`);
   }
 
+  if (error.crossDomain) {
+    lines.push(
+      `Cross-domain: "${error.entity?.name ?? ""}" exists as a ${error.crossDomain.entityType}. \`${error.crossDomain.cli}\``,
+    );
+  }
+
   if (error.recovery) {
     if (error.recovery.cli) {
       lines.push(`Recovery: \`${error.recovery.cli}\``);
@@ -106,6 +120,7 @@ function renderErrorJson(error: PragmaError): string {
     entity: error.entity,
     suggestions: error.suggestions,
     recovery: error.recovery,
+    crossDomain: error.crossDomain,
     filters: error.filters,
     validOptions: error.validOptions,
   });

package/src/pipeline/resolveCommandKind.ts

@@ -8,7 +8,14 @@
 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", "update-refs"]);
+const STORE_SKIP_COMMANDS = new Set([
+  "setup",
+  "mcp",
+  "update-refs",
+  "capabilities",
+  "trace",
+  "graphql",
+]);
 
 function findCommandArg(argv: readonly string[]): string | undefined {
   const args = argv.slice(2);

package/src/pipeline/runCli.ts

@@ -1,10 +1,14 @@
 import type { GlobalFlags } from "@canonical/cli-core";
 import { CommanderError } from "commander";
+import { commands as graphqlCommands } from "../domains/graphql/index.js";
+import { buildCapabilitiesCommand } from "../domains/llm/index.js";
 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 createInteractivePromptSession from "../domains/shared/createInteractivePromptSession.js";
 import type { PragmaRuntime } from "../domains/shared/runtime.js";
 import { bootPragma } from "../domains/shared/runtime.js";
+import { commands as traceCommands } from "../domains/trace/index.js";
 import { PragmaError } from "../error/index.js";
 import collectCommands from "./collectCommands.js";
 import createProgram from "./createProgram.js";
@@ -16,7 +20,6 @@ import {
   renderErrorPlain,
 } from "./renderError.js";
 import resolveCommandKind from "./resolveCommandKind.js";
-import runInteractiveCommand from "./runInteractiveCommand.js";
 
 function hasCommandArg(argv: readonly string[]): boolean {
   const args = argv.slice(2);
@@ -76,11 +79,11 @@ async function handleDoctor(globalFlags: GlobalFlags): Promise<void> {
 async function handleRootHelp(globalFlags: GlobalFlags): Promise<void> {
   const stubCtx: PragmaContext = {
     store: {} as PragmaRuntime["store"],
-    config: { tier: undefined, channel: "normal" },
+    ...(await resolveHelpConfig()),
     cwd: process.cwd(),
     dispose: () => {},
     globalFlags,
-    interactive: runInteractiveCommand,
+    promptSession: createInteractivePromptSession,
   };
   const commands = collectCommands(stubCtx);
   const program = createProgram(commands, stubCtx);
@@ -92,6 +95,41 @@ async function handleRootHelp(globalFlags: GlobalFlags): Promise<void> {
   }
 }
 
+/**
+ * Resolve config and packages for root help without booting the store.
+ *
+ * Story-pack nouns come from config and package files, so bare
+ * `pragma --help` reads them via the filesystem loaders only. Help must
+ * never fail on a broken config — errors fall back to the empty stub and
+ * surface on the next real command instead.
+ *
+ * @note Impure — reads config and resolves packages from disk.
+ */
+async function resolveHelpConfig(): Promise<
+  Pick<PragmaRuntime, "config" | "packages">
+> {
+  try {
+    const { readConfig } = await import("#config");
+    const config = readConfig(process.cwd());
+    const { resolveSemanticPackages } = await import(
+      "../domains/shared/semanticPackage.js"
+    );
+    const { createGitLoader, createLocalLoader } = await import(
+      "../domains/shared/loaders/index.js"
+    );
+    const { mergeAndParseRefs } = await import(
+      "../domains/shared/mergeAndParseRefs.js"
+    );
+    const packages = await resolveSemanticPackages(
+      mergeAndParseRefs(config.packages),
+      [createLocalLoader(), createGitLoader()],
+    );
+    return { config, packages };
+  } catch {
+    return { config: { tier: undefined, channel: "normal" }, packages: [] };
+  }
+}
+
 // — Stage 4+5: Boot, build program, execute ——————————————————————————————————
 
 async function bootAndRun(
@@ -117,7 +155,7 @@ async function bootAndRun(
     const ctx: PragmaContext = {
       ...runtime,
       globalFlags,
-      interactive: runInteractiveCommand,
+      promptSession: createInteractivePromptSession,
     };
     const commands = collectCommands(ctx);
     const program = createProgram(commands, ctx);
@@ -137,11 +175,18 @@ async function runStoreSkip(
     store: {} as PragmaRuntime["store"],
     config: { tier: undefined, channel: "normal" },
     cwd: process.cwd(),
+    packages: [],
     dispose: () => {},
     globalFlags,
-    interactive: runInteractiveCommand,
+    promptSession: createInteractivePromptSession,
   };
-  const commands = [...setupCommands(), ...refsCommands()];
+  const commands = [
+    ...setupCommands(),
+    ...refsCommands(),
+    ...traceCommands(),
+    ...graphqlCommands(),
+    buildCapabilitiesCommand(),
+  ];
   const program = createProgram(commands, stubCtx);
 
   try {

package/src/testing/createTestMcpClient.ts

@@ -31,12 +31,16 @@ export default async function createTestMcpClient(options?: {
   };
   const cwd = options?.cwd ?? process.cwd();
 
-  const { store, cleanup: cleanupStore } = await createTestStore({ ttl });
+  const { store, cleanup: cleanupStore } = await createTestStore({
+    ttl,
+    prefixes: config.prefixes,
+  });
 
   const runtime: PragmaRuntime = {
     store,
     config,
     cwd,
+    packages: [],
     dispose: () => cleanupStore(),
   };
 

package/src/testing/graphqlFixtures.ts

@@ -0,0 +1,72 @@
+/**
+ * TTL fixtures for graphql domain tests.
+ *
+ * Three compile outcomes: a clean ontology (no diagnostics), an ontology
+ * with an unresolvable field-name collision (M001 error diagnostic, schema
+ * still composes), and an ontology whose reserved `__` field name fails
+ * schema composition entirely (C003 → CompilationError).
+ */
+
+/** Namespace used by all graphql fixtures. */
+export const EX_NAMESPACE = "http://example.org/";
+
+/** `--prefix` entry registering {@link EX_NAMESPACE}. */
+export const EX_PREFIX_ENTRY = `ex=${EX_NAMESPACE}`;
+
+const prefixBlock = `@prefix ex: <${EX_NAMESPACE}> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .`;
+
+/** Compiles to `type Thing` with zero diagnostics. */
+export const GRAPHQL_CLEAN_TTL = `${prefixBlock}
+
+ex:Thing a owl:Class ;
+  rdfs:label "Thing" .
+
+ex:name a owl:DatatypeProperty ;
+  rdfs:domain ex:Thing ;
+  rdfs:range xsd:string ;
+  rdfs:label "name" .
+
+ex:widget a ex:Thing ;
+  ex:name "Widget" .
+`;
+
+/**
+ * Produces an M001 error diagnostic (three properties collapse to
+ * `Thing.name` and the namespace-prefixed rename collides too), but the
+ * schema still composes — no CompilationError.
+ */
+export const GRAPHQL_ERROR_TTL = `${prefixBlock}
+
+ex:Thing a owl:Class ;
+  rdfs:label "Thing" .
+
+ex:name a owl:DatatypeProperty ;
+  rdfs:domain ex:Thing ;
+  rdfs:range xsd:string .
+
+ex:hasName a owl:DatatypeProperty ;
+  rdfs:domain ex:Thing ;
+  rdfs:range xsd:string .
+
+ex:isName a owl:DatatypeProperty ;
+  rdfs:domain ex:Thing ;
+  rdfs:range xsd:string .
+`;
+
+/**
+ * Fails schema composition (C003): `__bad` survives name sanitization but
+ * `__` is reserved by GraphQL introspection, so compile() throws
+ * CompilationError.
+ */
+export const GRAPHQL_FATAL_TTL = `${prefixBlock}
+
+ex:Thing a owl:Class ;
+  rdfs:label "Thing" .
+
+ex:__bad a owl:DatatypeProperty ;
+  rdfs:domain ex:Thing ;
+  rdfs:range xsd:string .
+`;

package/src/testing/index.ts

@@ -3,6 +3,23 @@ export type { CommandResult } from "./cli.js";
 export { runCommand } from "./cli.js";
 export { default as createTestMcpClient } from "./createTestMcpClient.js";
 export { DS_ALL_TTL, DS_ONTOLOGY_TTL, DS_TIERS_TTL } from "./dsFixtures.js";
+export {
+  EX_NAMESPACE,
+  EX_PREFIX_ENTRY,
+  GRAPHQL_CLEAN_TTL,
+  GRAPHQL_ERROR_TTL,
+  GRAPHQL_FATAL_TTL,
+} from "./graphqlFixtures.js";
+export {
+  PARITY_GAPS,
+  STANDARD_PACK_STORY,
+} from "./standardParityFixtures.js";
 export type { PragmaTestStoreOptions } from "./store.js";
 export { createTestStore } from "./store.js";
+export {
+  RECIPE_NAMESPACE,
+  RECIPE_PREFIXES,
+  RECIPE_STORY,
+  RECIPE_TTL,
+} from "./storyFixtures.js";
 export type { TestMcpClientResult } from "./types.js";