@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/pipeline/runCli.ts

@@ -1,25 +1,31 @@
 import type { GlobalFlags } from "@canonical/cli-core";
 import { CommanderError } from "commander";
+import { PROGRAM_NAME, VERSION } from "../constants.js";
+import { commands as createCommands } from "../domains/create/index.js";
 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";
+import ensureFirstRun from "./firstRun.js";
 import mapExitCode from "./mapExitCode.js";
-import parseGlobalFlags, { stripGlobalFlags } from "./parseGlobalFlags.js";
+import parseGlobalFlags, {
+  readRawFormat,
+  stripGlobalFlags,
+} from "./parseGlobalFlags.js";
 import {
   renderErrorJson,
   renderErrorLlm,
   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);
@@ -67,8 +73,23 @@ async function handleCompletionsServer(): Promise<void> {
   await startCompletionsServer();
 }
 
-async function handleDoctor(globalFlags: GlobalFlags): Promise<void> {
+async function handleDoctor(
+  argv: readonly string[],
+  globalFlags: GlobalFlags,
+): Promise<void> {
   const { doctorCommand } = await import("../domains/doctor/commands/index.js");
+
+  // `doctor` runs before Commander, so honour --help/-h here rather than
+  // executing the health check when the user only asked for usage.
+  const wantsHelp = argv
+    .slice(2)
+    .some((arg) => arg === "--help" || arg === "-h");
+  if (wantsHelp) {
+    const { formatVerbHelp } = await import("@canonical/cli-core");
+    process.stdout.write(`${formatVerbHelp(PROGRAM_NAME, doctorCommand)}\n`);
+    return;
+  }
+
   const ctx = { cwd: process.cwd(), globalFlags };
   const result = await doctorCommand.execute({}, ctx);
   if (result.tag === "output") {
@@ -79,12 +100,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(),
-    packages: [],
     dispose: () => {},
     globalFlags,
-    interactive: runInteractiveCommand,
+    promptSession: createInteractivePromptSession,
   };
   const commands = collectCommands(stubCtx);
   const program = createProgram(commands, stubCtx);
@@ -92,7 +112,42 @@ async function handleRootHelp(globalFlags: GlobalFlags): Promise<void> {
   try {
     await program.parseAsync(["node", "pragma", "--help"]);
   } catch (err) {
-    handleProgramError(err, globalFlags);
+    await handleProgramError(err, globalFlags, ["node", "pragma", "--help"]);
+  }
+}
+
+/**
+ * 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: [] };
   }
 }
 
@@ -117,22 +172,60 @@ async function bootAndRun(
     return;
   }
 
+  await emitSchemaArtifact(runtime, globalFlags);
+
   try {
     const ctx: PragmaContext = {
       ...runtime,
       globalFlags,
-      interactive: runInteractiveCommand,
+      promptSession: createInteractivePromptSession,
     };
     const commands = collectCommands(ctx);
     const program = createProgram(commands, ctx);
     await program.parseAsync(stripGlobalFlags(argv));
   } catch (err) {
-    handleProgramError(err, globalFlags);
+    await handleProgramError(err, globalFlags, argv);
   } finally {
     runtime.dispose();
   }
 }
 
+/**
+ * Keep the `schema.graphql` artifact current on every booted run.
+ *
+ * The freshness probe is a source hash against the artifact's header, so
+ * the common case costs one hash + one small read; compilation runs only
+ * when the resolved TTL sources actually changed (or on first use).
+ * Never fatal — a failed compile warns and the command proceeds.
+ */
+async function emitSchemaArtifact(
+  runtime: PragmaRuntime,
+  globalFlags: GlobalFlags,
+): Promise<void> {
+  try {
+    const { ensureSchemaArtifact } = await import(
+      "../domains/graphql/operations/index.js"
+    );
+    const result = await ensureSchemaArtifact(runtime);
+    if (result.status === "written") {
+      process.stderr.write(
+        `Updated GraphQL schema artifact (sources changed): ${result.path}\n`,
+      );
+    } else if (result.status === "failed" && globalFlags.verbose) {
+      process.stderr.write(
+        `Warning: GraphQL schema compilation failed; ${result.path} not updated. Run \`pragma graphql check\` for diagnostics.\n`,
+      );
+    }
+  } catch (err) {
+    if (globalFlags.verbose) {
+      const reason = err instanceof Error ? err.message : String(err);
+      process.stderr.write(
+        `Warning: could not update GraphQL schema artifact: ${reason}\n`,
+      );
+    }
+  }
+}
+
 async function runStoreSkip(
   argv: readonly string[],
   globalFlags: GlobalFlags,
@@ -144,13 +237,14 @@ async function runStoreSkip(
     packages: [],
     dispose: () => {},
     globalFlags,
-    interactive: runInteractiveCommand,
+    promptSession: createInteractivePromptSession,
   };
   const commands = [
     ...setupCommands(),
     ...refsCommands(),
     ...traceCommands(),
     ...graphqlCommands(),
+    ...createCommands(),
     buildCapabilitiesCommand(),
   ];
   const program = createProgram(commands, stubCtx);
@@ -158,11 +252,53 @@ async function runStoreSkip(
   try {
     await program.parseAsync(stripGlobalFlags(argv));
   } catch (err) {
-    handleProgramError(err, globalFlags);
+    await handleProgramError(err, globalFlags, argv);
   }
 }
 
-function handleProgramError(err: unknown, globalFlags: GlobalFlags): void {
+/**
+ * First non-flag token in argv — the command noun, if any.
+ *
+ * Global flags are stripped first so a flag *value* (e.g. the `json` in
+ * `--format json`) is never mistaken for the noun; otherwise
+ * `pragma --format json standard frobnicate` would scan `json` and fail to
+ * suggest `standard`'s verbs.
+ */
+function findNoun(argv: readonly string[]): string | undefined {
+  return stripGlobalFlags(argv)
+    .slice(2)
+    .find((arg) => !arg.startsWith("-"));
+}
+
+/**
+ * When an unknown command/verb is entered under a known noun, print that noun's
+ * valid verbs so the user can recover — "defer to the category that exists".
+ *
+ * @note Impure — writes the noun's verb list to stderr.
+ */
+async function suggestNounVerbs(argv: readonly string[]): Promise<void> {
+  const noun = findNoun(argv);
+  if (!noun) return;
+  const stubCtx: PragmaContext = {
+    store: {} as PragmaRuntime["store"],
+    ...(await resolveHelpConfig()),
+    cwd: process.cwd(),
+    dispose: () => {},
+    globalFlags: { llm: false, autoLlm: false, format: "text", verbose: false },
+    promptSession: createInteractivePromptSession,
+  };
+  const commands = collectCommands(stubCtx);
+  const hasNoun = commands.some((cmd) => cmd.path.at(0) === noun);
+  if (!hasNoun) return;
+  const { formatNounHelp } = await import("@canonical/cli-core");
+  process.stderr.write(`\n${formatNounHelp(PROGRAM_NAME, noun, commands)}\n`);
+}
+
+async function handleProgramError(
+  err: unknown,
+  globalFlags: GlobalFlags,
+  argv: readonly string[],
+): Promise<void> {
   if (err instanceof CommanderError) {
     if (
       err.code === "commander.helpDisplayed" ||
@@ -171,6 +307,9 @@ function handleProgramError(err: unknown, globalFlags: GlobalFlags): void {
       process.exitCode = 0;
       return;
     }
+    if (err.code === "commander.unknownCommand") {
+      await suggestNounVerbs(argv);
+    }
     process.exitCode = err.exitCode;
     return;
   }
@@ -206,26 +345,64 @@ function handleProgramError(err: unknown, globalFlags: GlobalFlags): void {
  */
 export default async function runCli(argv: readonly string[]): Promise<void> {
   const globalFlags = parseGlobalFlags(argv);
-  const explicitHelpOrVersion = argv
+
+  const commandKind = resolveCommandKind(argv);
+
+  // Completion queries must be handled before the root-help shortcut:
+  // `pragma --completions` (empty first-Tab partial) has no non-flag command
+  // arg, so it would otherwise fall through to root help and dump the help
+  // banner into the shell's completion buffer.
+  if (commandKind.kind === "completions-client") {
+    return handleCompletionsClient(commandKind.partial);
+  }
+  if (commandKind.kind === "completions-server") {
+    return handleCompletionsServer();
+  }
+
+  // First-run onboarding: when the global config does not exist yet, greet on
+  // stderr and create it with defaults. After the completions early-exits so
+  // the note can never leak into a shell completion buffer; stderr-only so
+  // stdout (command output, --format json, MCP stdio) stays untouched; and
+  // failure-tolerant — onboarding must never break an invocation.
+  await ensureFirstRun();
+
+  // `--version`/`-V` is a global flag: print the version and exit regardless
+  // of where it appears (root or after a command/verb), so `block list -V`
+  // behaves like the root `pragma --version` instead of erroring.
+  if (argv.slice(2).some((arg) => arg === "--version" || arg === "-V")) {
+    process.stdout.write(`${VERSION}\n`);
+    return;
+  }
+
+  const explicitHelp = argv
     .slice(2)
-    .some(
-      (arg) =>
-        arg === "--help" || arg === "-h" || arg === "--version" || arg === "-V",
-    );
+    .some((arg) => arg === "--help" || arg === "-h");
 
-  if (!hasCommandArg(argv) && !explicitHelpOrVersion) {
-    return handleRootHelp(globalFlags);
+  // Reject an unknown --format value early (completion queries and --version
+  // are handled above, so neither errors). Skip when the user asked for help —
+  // it should print regardless of a bad --format. Only text/json are supported.
+  const rawFormat = readRawFormat(argv);
+  if (
+    !explicitHelp &&
+    rawFormat !== undefined &&
+    rawFormat !== "text" &&
+    rawFormat !== "json"
+  ) {
+    const error = PragmaError.invalidInput("format", rawFormat, {
+      validOptions: ["text", "json"],
+    });
+    process.stderr.write(`${renderError(error, globalFlags)}\n`);
+    process.exitCode = mapExitCode(error.code);
+    return;
   }
 
-  const commandKind = resolveCommandKind(argv);
+  if (!hasCommandArg(argv) && !explicitHelp) {
+    return handleRootHelp(globalFlags);
+  }
 
   switch (commandKind.kind) {
-    case "completions-client":
-      return handleCompletionsClient(commandKind.partial);
-    case "completions-server":
-      return handleCompletionsServer();
     case "doctor":
-      return handleDoctor(globalFlags);
+      return handleDoctor(argv, globalFlags);
     case "store-skip":
       return runStoreSkip(argv, globalFlags);
     case "store-required":

package/src/testing/cli.ts

@@ -6,7 +6,9 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { resolve } from "node:path";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 
 /** Captured output from a CLI subprocess invocation. */
 interface CommandResult {
@@ -15,21 +17,47 @@ interface CommandResult {
   exitCode: number;
 }
 
+/**
+ * XDG home whose global config already exists, shared by all default
+ * invocations in this file's worker.
+ *
+ * Subprocesses would otherwise trigger the first-run greeting in whichever
+ * test happens to spawn first (the setup-file XDG is fresh per file), making
+ * stderr assertions ordering-dependent. Seeding the config keeps every
+ * default `runCommand` past first-run; tests that WANT the first-run path
+ * pass their own fresh XDG via `env`.
+ */
+let seededXdg: string | undefined;
+function seededXdgHome(): string {
+  if (!seededXdg) {
+    seededXdg = mkdtempSync(join(tmpdir(), "pragma-cli-xdg-"));
+    mkdirSync(join(seededXdg, "pragma"), { recursive: true });
+    writeFileSync(join(seededXdg, "pragma", "config.json"), "{}\n");
+  }
+  return seededXdg;
+}
+
 /**
  * Spawn the pragma CLI binary synchronously and capture its output.
  *
  * @param args - CLI arguments to pass after the binary path.
  * @param cwd - Optional working directory for the subprocess.
+ * @param env - Extra environment overrides (merged over the seeded default).
  * @returns Captured stdout, stderr, and exit code.
  *
  * @note Impure
  */
-function runCommand(args: string[], cwd?: string): CommandResult {
+function runCommand(
+  args: string[],
+  cwd?: string,
+  env?: Record<string, string>,
+): CommandResult {
   const binPath = resolve(import.meta.dirname, "../bin.ts");
   const result = spawnSync("bun", ["run", binPath, ...args], {
     cwd,
     encoding: "utf-8",
     timeout: 20_000,
+    env: { ...process.env, XDG_CONFIG_HOME: seededXdgHome(), ...env },
   });
 
   return {

package/src/testing/createTestMcpClient.ts

@@ -31,7 +31,10 @@ 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,

package/src/testing/dsFixtures.ts

@@ -5,16 +5,19 @@
  * that D3 operations query against.
  *
  * All @prefix declarations derived from {@link TTL_PREFIXES} so that
- * a namespace rename in PREFIX_MAP propagates here automatically.
+ * a namespace rename in DEFAULT_PREFIX_MAP propagates here automatically.
  */
 
-import { PREFIX_MAP, TTL_PREFIXES } from "../domains/shared/prefixes.js";
+import {
+  DEFAULT_PREFIX_MAP,
+  TTL_PREFIXES,
+} from "../domains/shared/prefixes.js";
 
 /** Turtle @prefix block for ds: only (most data fixtures). */
-const dsPrefix = `@prefix ds: <${PREFIX_MAP.ds}> .`;
+const dsPrefix = `@prefix ds: <${DEFAULT_PREFIX_MAP.ds}> .`;
 
 /** Turtle @prefix block for cs: only (standards fixtures). */
-const csPrefix = `@prefix cs: <${PREFIX_MAP.cs}> .`;
+const csPrefix = `@prefix cs: <${DEFAULT_PREFIX_MAP.cs}> .`;
 
 // =============================================================================
 // Ontology (TBox) — class and property definitions
@@ -225,6 +228,20 @@ cs:code a owl:DatatypeProperty ;
 cs:extends a owl:ObjectProperty ;
   rdfs:domain cs:CodeStandard ;
   rdfs:range cs:CodeStandard .
+
+# ---- TBox extras (header, comments, functional typing, SHACL) ----
+
+ds:ontology a owl:Ontology ;
+  rdfs:label "Design System Ontology" ;
+  owl:versionInfo "0.1.0-test" .
+
+ds:Component rdfs:comment "A reusable UI building block." .
+
+ds:tier a owl:FunctionalProperty .
+
+ds:ComponentShape a <http://www.w3.org/ns/shacl#NodeShape> ;
+  <http://www.w3.org/ns/shacl#targetClass> ds:Component ;
+  <http://www.w3.org/ns/shacl#property> ds:shapeName, ds:shapeTier .
 `;
 
 // =============================================================================

package/src/testing/index.ts

@@ -10,6 +10,13 @@ export {
   GRAPHQL_ERROR_TTL,
   GRAPHQL_FATAL_TTL,
 } from "./graphqlFixtures.js";
+export { PARITY_GAPS } 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";