@canonical/pragma-cli 0.30.0 → 0.31.0

package/src/pipeline/firstRun.ts

@@ -0,0 +1,99 @@
+/**
+ * First-run onboarding — welcome note + global config creation.
+ *
+ * On the first invocation of pragma (detected by the absence of the global
+ * config file), print a short welcome to stderr and create
+ * `$XDG_CONFIG_HOME/pragma/config.json` with defaults. Modeled as a
+ * {@link Task} so the effects (exists/mkdir/write/log) stay declarative and
+ * testable, mirroring the config domain's write tasks.
+ *
+ * The banner goes to STDERR: stdout belongs to command output (`--format
+ * json` consumers, MCP stdio), and the note must never corrupt it.
+ */
+
+import { dirname } from "node:path";
+import {
+  $,
+  exists,
+  gen,
+  info,
+  mkdir,
+  type Task,
+  writeFile,
+} from "@canonical/task";
+import { runTask } from "@canonical/task/node";
+import { resolveGlobalConfigPath } from "../config/index.js";
+
+/**
+ * Seed content for a fresh global config: an empty object, so every field
+ * keeps its built-in default and `config show` reports honest provenance
+ * (nothing is pinned that the user did not choose).
+ */
+const SEED_CONFIG = "{}\n";
+
+/** Build the welcome note. The resolved path is shown so it is copyable. */
+function welcomeLines(path: string): string[] {
+  return [
+    "Hello! Thanks for taking the time to try the pre-release pragma CLI.",
+    "Please file issues, suggestions, and feedback at https://github.com/canonical/pragma/issues.",
+    `Pragma stores its configuration in ${path} (just created with defaults).`,
+    "A `pragma.config.json` in the current directory or any directory above it overrides it per project.",
+    "",
+  ];
+}
+
+/**
+ * The first-run task: create the global config, announcing it on first run.
+ *
+ * @returns Task yielding whether the config was created and its path.
+ * @note Impure — checks/creates the global config file, emits log effects.
+ */
+export function firstRunTask(): Task<{ created: boolean; path: string }> {
+  return gen(function* () {
+    const path = resolveGlobalConfigPath();
+
+    if (yield* $(exists(path))) {
+      return { created: false, path };
+    }
+
+    // Create the config first, then greet: if creation fails the effects throw
+    // before any line is emitted, so onboarding degrades to the single stderr
+    // warning ensureFirstRun writes — never a "just created" banner alongside a
+    // failure. `mkdir` is recursive (its default), so a missing XDG parent is
+    // created rather than being treated as an error.
+    yield* $(mkdir(dirname(path), true));
+    yield* $(writeFile(path, SEED_CONFIG));
+
+    for (const line of welcomeLines(path)) {
+      yield* $(info(line));
+    }
+
+    return { created: true, path };
+  });
+}
+
+/**
+ * Run the first-run task, tolerating every failure.
+ *
+ * Onboarding must never break the CLI: a read-only home, a weird XDG path,
+ * or a race with a concurrent first run degrade to a single stderr warning
+ * and the invocation proceeds normally (the config layers treat a missing
+ * global file as defaults anyway).
+ *
+ * @param write - Stderr sink, injectable for tests.
+ * @note Impure — filesystem effects + stderr.
+ */
+export default async function ensureFirstRun(
+  write: (line: string) => void = (line) => process.stderr.write(`${line}\n`),
+): Promise<void> {
+  try {
+    await runTask(firstRunTask(), {
+      // Route log effects to stderr without the interpreter's [INFO] prefix —
+      // this is a greeting, not diagnostics.
+      onLog: (_level, message) => write(message),
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    write(`Warning: could not create the global pragma config — ${reason}`);
+  }
+}

package/src/pipeline/parseGlobalFlags.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from "vitest";
-import parseGlobalFlags, { stripGlobalFlags } from "./parseGlobalFlags.js";
+import parseGlobalFlags, {
+  readRawFormat,
+  stripGlobalFlags,
+} from "./parseGlobalFlags.js";
 
 describe("parseGlobalFlags", () => {
   it("extracts --llm", () => {
@@ -29,6 +32,20 @@ describe("parseGlobalFlags", () => {
     expect(flags.format).toBe("text");
   });
 
+  it("accepts the --format=json equals form", () => {
+    const flags = parseGlobalFlags(["node", "pragma", "info", "--format=json"]);
+    expect(flags.format).toBe("json");
+  });
+
+  it("treats an unknown --format value as text", () => {
+    expect(
+      parseGlobalFlags(["node", "pragma", "info", "--format", "xml"]).format,
+    ).toBe("text");
+    expect(
+      parseGlobalFlags(["node", "pragma", "info", "--format=xml"]).format,
+    ).toBe("text");
+  });
+
   it("extracts --verbose", () => {
     const flags = parseGlobalFlags([
       "node",
@@ -39,6 +56,52 @@ describe("parseGlobalFlags", () => {
     ]);
     expect(flags.verbose).toBe(true);
   });
+
+  describe("auto-LLM detection", () => {
+    const tty = { isTty: true, noAutoLlm: false };
+    const piped = { isTty: false, noAutoLlm: false };
+
+    it("stays plain on an interactive terminal", () => {
+      expect(parseGlobalFlags(["node", "pragma", "info"], tty).llm).toBe(false);
+    });
+
+    it("defaults to llm when stdout is not a TTY, flagged as auto", () => {
+      const flags = parseGlobalFlags(["node", "pragma", "info"], piped);
+      expect(flags.llm).toBe(true);
+      expect(flags.autoLlm).toBe(true);
+    });
+
+    it("marks explicit --llm as not auto", () => {
+      const flags = parseGlobalFlags(
+        ["node", "pragma", "--llm", "info"],
+        piped,
+      );
+      expect(flags.llm).toBe(true);
+      expect(flags.autoLlm).toBe(false);
+    });
+
+    it("does not auto-enable llm when --format json is requested", () => {
+      expect(
+        parseGlobalFlags(["node", "pragma", "info", "--format", "json"], piped)
+          .llm,
+      ).toBe(false);
+    });
+
+    it("respects an explicit --llm even on a TTY", () => {
+      expect(
+        parseGlobalFlags(["node", "pragma", "--llm", "info"], tty).llm,
+      ).toBe(true);
+    });
+
+    it("honours PRAGMA_NO_AUTO_LLM to stay plain when piped", () => {
+      expect(
+        parseGlobalFlags(["node", "pragma", "info"], {
+          isTty: false,
+          noAutoLlm: true,
+        }).llm,
+      ).toBe(false);
+    });
+  });
 });
 
 describe("stripGlobalFlags", () => {
@@ -89,4 +152,42 @@ describe("stripGlobalFlags", () => {
       "list",
     ]);
   });
+
+  it("removes the equals form of every global flag", () => {
+    expect(
+      stripGlobalFlags([
+        "node",
+        "pragma",
+        "--llm=",
+        "--verbose=",
+        "--format=json",
+        "block",
+        "list",
+      ]),
+    ).toEqual(["node", "pragma", "block", "list"]);
+  });
+});
+
+describe("readRawFormat", () => {
+  it("reads the space form", () => {
+    expect(readRawFormat(["node", "pragma", "--format", "json"])).toBe("json");
+  });
+
+  it("reads the equals form", () => {
+    expect(readRawFormat(["node", "pragma", "--format=text"])).toBe("text");
+  });
+
+  it("returns undefined when --format is absent", () => {
+    expect(readRawFormat(["node", "pragma", "info"])).toBeUndefined();
+  });
+
+  it("returns an empty string for a bare --format at end of argv", () => {
+    // Not undefined — the caller must reject it rather than fall through to
+    // root help with exit code 0.
+    expect(readRawFormat(["node", "pragma", "--format"])).toBe("");
+  });
+
+  it("returns an empty string when --format is followed by another flag", () => {
+    expect(readRawFormat(["node", "pragma", "--format", "--llm"])).toBe("");
+  });
 });

package/src/pipeline/parseGlobalFlags.ts

@@ -1,21 +1,102 @@
 import type { GlobalFlags } from "@canonical/cli-core";
 
+/**
+ * Read the value of a `--flag` that accepts both the space form
+ * (`--flag value`) and the equals form (`--flag=value`).
+ *
+ * @param argv - Raw process.argv array.
+ * @param flag - The flag name including leading dashes (e.g. `--format`).
+ * @returns The flag's value, or undefined when the flag is absent.
+ */
+function readFlagValue(
+  argv: readonly string[],
+  flag: string,
+): string | undefined {
+  const equalsPrefix = `${flag}=`;
+  const equalsArg = argv.find((arg) => arg.startsWith(equalsPrefix));
+  if (equalsArg !== undefined) {
+    return equalsArg.slice(equalsPrefix.length);
+  }
+  const spaceIndex = argv.indexOf(flag);
+  return spaceIndex === -1 ? undefined : argv[spaceIndex + 1];
+}
+
+/**
+ * Read the raw `--format` value exactly as the user typed it (both space and
+ * equals forms), for validation. Unlike {@link parseGlobalFlags}, this does not
+ * coerce unknown values to `text` — the caller decides how to reject them.
+ *
+ * A bare `--format` with no following value (either at the end of argv or
+ * immediately followed by another flag) is reported as an empty string rather
+ * than `undefined`, so the caller rejects it as invalid input instead of
+ * silently falling through to the root-help path with exit code 0.
+ *
+ * @param argv - Raw process.argv array.
+ * @returns The raw format value, an empty string when `--format` is present
+ *   without a value, or undefined when `--format` is absent.
+ */
+export function readRawFormat(argv: readonly string[]): string | undefined {
+  const equalsArg = argv.find((arg) => arg.startsWith("--format="));
+  if (equalsArg !== undefined) return equalsArg.slice("--format=".length);
+
+  const spaceIndex = argv.indexOf("--format");
+  if (spaceIndex === -1) return undefined;
+
+  const value = argv[spaceIndex + 1];
+  // A missing value or another flag means the user gave no format at all.
+  return value !== undefined && !value.startsWith("-") ? value : "";
+}
+
+/**
+ * Environment probe used to decide the auto-LLM default. Injectable so the
+ * detection can be unit-tested without touching the real process.
+ */
+export interface OutputEnvironment {
+  /** Whether stdout is attached to an interactive terminal. */
+  readonly isTty: boolean;
+  /** Whether the auto-LLM default is explicitly disabled. */
+  readonly noAutoLlm: boolean;
+}
+
+/** Read the real stdout/env output environment. @note Impure — reads process. */
+function readOutputEnvironment(): OutputEnvironment {
+  return {
+    isTty: process.stdout.isTTY === true,
+    noAutoLlm: Boolean(process.env.PRAGMA_NO_AUTO_LLM),
+  };
+}
+
 /**
  * Extract global flags (--llm, --format, --verbose) from raw argv.
  *
- * Performs simple indexOf scanning rather than full argument parsing
- * so it can run before Commander processes the command tree.
+ * Performs simple scanning rather than full argument parsing so it can run
+ * before Commander processes the command tree. Recognises both the space form
+ * (`--format json`) and the equals form (`--format=json`).
+ *
+ * Auto-LLM: when no `--llm`/`--format` is given and stdout is not an
+ * interactive terminal (piped or redirected — the shape an agent captures),
+ * `llm` defaults to true so agents get condensed Markdown without passing a
+ * flag. Interactive terminals stay in rich mode. `--llm`, `--format json`, and
+ * `PRAGMA_NO_AUTO_LLM` all override this.
  *
  * @param argv - Raw process.argv array.
+ * @param env - Output environment probe (defaults to the real process).
  * @returns Parsed global flags.
+ * @note Impure by default — reads process.stdout/env unless `env` is injected.
  */
-export default function parseGlobalFlags(argv: readonly string[]): GlobalFlags {
+export default function parseGlobalFlags(
+  argv: readonly string[],
+  env: OutputEnvironment = readOutputEnvironment(),
+): GlobalFlags {
+  const explicitLlm = argv.includes("--llm");
+  const format = readFlagValue(argv, "--format") === "json" ? "json" : "text";
+  const formatRequested = readFlagValue(argv, "--format") !== undefined;
+  const autoLlm =
+    !explicitLlm && !formatRequested && !env.isTty && !env.noAutoLlm;
   return {
-    llm: argv.includes("--llm"),
-    format:
-      argv.includes("--format") && argv[argv.indexOf("--format") + 1] === "json"
-        ? "json"
-        : "text",
+    llm: explicitLlm || autoLlm,
+    autoLlm,
+    format,
     verbose: argv.includes("--verbose"),
   };
 }
@@ -36,8 +117,16 @@ export function stripGlobalFlags(argv: readonly string[]): string[] {
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--llm" || arg === "--verbose") continue;
+    // Equals form (`--format=json`, `--llm=…`) is a single token — drop it.
+    if (
+      arg?.startsWith("--format=") ||
+      arg?.startsWith("--llm=") ||
+      arg?.startsWith("--verbose=")
+    ) {
+      continue;
+    }
     if (arg === "--format") {
-      i += 1; // skip the value too
+      i += 1; // skip the space-form value too
       continue;
     }
     result.push(arg as string);

package/src/pipeline/resolveCommandKind.test.ts

@@ -40,6 +40,18 @@ describe("resolveCommandKind", () => {
     expect(result).toEqual({ kind: "store-skip", command: "mcp" });
   });
 
+  it("detects store-skip for create (pure scaffolding, no store)", () => {
+    const result = resolveCommandKind([
+      "node",
+      "pragma",
+      "create",
+      "component",
+      "react",
+      "Accordion2",
+    ]);
+    expect(result).toEqual({ kind: "store-skip", command: "create" });
+  });
+
   it("defaults to store-required for regular commands", () => {
     const result = resolveCommandKind(["node", "pragma", "component", "list"]);
     expect(result).toEqual({ kind: "store-required" });

package/src/pipeline/resolveCommandKind.ts

@@ -15,6 +15,10 @@ const STORE_SKIP_COMMANDS = new Set([
   "capabilities",
   "trace",
   "graphql",
+  // `create` is pure scaffolding (summon generators) — it never queries the
+  // design-system graph, so booting the shared store just couples it to the
+  // installed packages and makes it fail when they are missing or malformed.
+  "create",
 ]);
 
 function findCommandArg(argv: readonly string[]): string | undefined {

package/src/pipeline/rootHelp.test.ts

@@ -0,0 +1,87 @@
+import type { CommandDefinition } from "@canonical/cli-core";
+import { describe, expect, it } from "vitest";
+import formatRootHelp from "./rootHelp.js";
+
+/** Minimal command stub — only the fields the help renderer reads. */
+function cmd(
+  path: string[],
+  extra: Partial<CommandDefinition> = {},
+): CommandDefinition {
+  return {
+    path,
+    description: `${path.join(" ")} description`,
+    parameters: [],
+    execute: async () => ({ tag: "output" }) as never,
+    ...extra,
+  };
+}
+
+const commands: CommandDefinition[] = [
+  cmd(["block", "list"]),
+  cmd(["token", "list"]),
+  cmd(["create", "component"], {
+    parameters: [
+      {
+        name: "framework",
+        description: "Component framework",
+        type: "select",
+        positional: true,
+        required: true,
+        choices: [
+          { label: "react", value: "react" },
+          { label: "svelte", value: "svelte" },
+          { label: "lit", value: "lit" },
+        ],
+      },
+    ],
+  }),
+  cmd(["create", "package"]),
+  cmd(["doctor"]),
+  cmd(["mystery", "verb"], { description: "an uncatalogued thing" }),
+];
+
+describe("formatRootHelp", () => {
+  const out = formatRootHelp("pragma", "Design system CLI", commands);
+
+  it("groups nouns under task-oriented headings instead of a flat list", () => {
+    expect(out).toContain("Explore the design system");
+    expect(out).toContain("Generate code");
+    expect(out).toContain("Set up & maintain");
+  });
+
+  it("gives real summaries, never the `<noun> commands` placeholder", () => {
+    expect(out).toContain("Look up design tokens and their values");
+    expect(out).not.toContain("block commands");
+    expect(out).not.toContain("token commands");
+  });
+
+  it("expands create with its subtypes and derived frameworks", () => {
+    expect(out).toContain("component");
+    expect(out).toContain("react · svelte · lit");
+    expect(out).toContain("package");
+  });
+
+  it("surfaces uncatalogued nouns under Other instead of dropping them", () => {
+    expect(out).toContain("Other");
+    expect(out).toContain("mystery");
+    expect(out).toContain("an uncatalogued thing");
+  });
+
+  it("always lists the mcp server command even without a definition", () => {
+    const withoutMcp = commands.filter((c) => c.path[0] !== "mcp");
+    const rendered = formatRootHelp("pragma", "d", withoutMcp);
+    expect(rendered).toContain("mcp");
+    expect(rendered).toContain("Start the MCP server over stdio");
+  });
+
+  it("hides nouns that are catalogued but not registered", () => {
+    // `standard` is catalogued but absent from this command set.
+    expect(out).not.toContain("Browse code standards");
+  });
+
+  it("lists the global flags and an orientation hint", () => {
+    expect(out).toContain("Global flags");
+    expect(out).toContain("--format json");
+    expect(out).toContain("pragma capabilities");
+  });
+});