@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/config/resolveWriteConfigPath.ts

@@ -0,0 +1,31 @@
+import findProjectConfigPath from "./findProjectConfigPath.js";
+import resolveConfigPath from "./resolveConfigPath.js";
+import resolveGlobalConfigPath from "./resolveGlobalConfigPath.js";
+import type { ConfigScope } from "./types.js";
+
+/**
+ * Resolve which config file a write should target.
+ *
+ * An explicit scope wins: `"local"` targets `<cwd>/pragma.config.json`,
+ * `"global"` targets the XDG file. Otherwise the nearest existing project
+ * file up the tree is updated in place, and when none exists the write
+ * goes to the global file — pragma is global-first: an unconfigured
+ * directory should not sprout a project file as a side effect.
+ *
+ * @param cwd - Directory the project layer is resolved from.
+ * @param scope - Optional explicit target layer.
+ * @returns Absolute path of the config file to write.
+ * @note Impure — probes the filesystem for the nearest project file.
+ */
+export default function resolveWriteConfigPath(
+  cwd: string,
+  scope?: ConfigScope,
+): string {
+  if (scope === "local") {
+    return resolveConfigPath(cwd);
+  }
+  if (scope === "global") {
+    return resolveGlobalConfigPath();
+  }
+  return findProjectConfigPath(cwd) ?? resolveGlobalConfigPath();
+}

package/src/config/types.ts

@@ -7,6 +7,7 @@
 
 import type { Channel, Framework } from "../constants.js";
 import type { RawPackageEntry } from "../domains/refs/operations/parseRef.js";
+import type { StoryPackDefinition } from "../domains/shared/stories/pack/types.js";
 
 /** Parsed contents of pragma.config.json. */
 interface PragmaConfig {
@@ -27,6 +28,22 @@ interface PragmaConfig {
    * only — no behaviour reads it yet; reserved for future framework defaulting.
    */
   framework?: Framework | undefined;
+  /**
+   * Declarative read stories compiled into CLI commands and MCP tools at
+   * boot.
+   * @experimental Story packs (v0) are experimental — the format may change.
+   */
+  stories?: ReadonlyArray<StoryPackDefinition> | undefined;
+  /**
+   * Additional namespace prefixes merged over the built-in prefix map —
+   * registered on the store (usable in queries) and used for display.
+   */
+  prefixes?: Readonly<Record<string, string>> | undefined;
+  /**
+   * Default progressive-disclosure level for disclosure-capable commands
+   * (e.g. `"digest"`, `"detailed"`). An explicit `--detail` flag overrides it.
+   */
+  detail?: string | undefined;
 }
 
 /** Partial update payload for writing config changes. */
@@ -43,4 +60,69 @@ interface ConfigUpdate {
   framework?: Framework | undefined;
 }
 
-export type { ConfigUpdate, PragmaConfig };
+/**
+ * Values a single config file declares. A key is present only when the
+ * file sets it — presence drives which layer wins during merging.
+ */
+interface ConfigFileValues {
+  readonly tier?: string;
+  readonly channel?: Channel;
+  readonly packages?: ReadonlyArray<RawPackageEntry>;
+  readonly trace?: boolean;
+  readonly framework?: Framework;
+  readonly stories?: ReadonlyArray<StoryPackDefinition>;
+  readonly prefixes?: Readonly<Record<string, string>>;
+  readonly detail?: string;
+}
+
+/** Which config layer supplied an effective field value. */
+type ConfigOrigin = "default" | "global" | "project";
+
+/** Per-field provenance for the effective merged config. */
+interface ConfigOrigins {
+  readonly tier: ConfigOrigin;
+  readonly channel: ConfigOrigin;
+  readonly packages: ConfigOrigin;
+  readonly trace: ConfigOrigin;
+  readonly framework: ConfigOrigin;
+  readonly stories: ConfigOrigin;
+  readonly prefixes: ConfigOrigin;
+  readonly detail: ConfigOrigin;
+}
+
+/** A resolved config file layer. */
+interface ConfigLayer {
+  /** Absolute path of the layer's config file (existing or would-be). */
+  readonly path: string;
+  /** Whether the file exists and was readable. */
+  readonly exists: boolean;
+}
+
+/** Layered config resolution result with per-field provenance. */
+interface ConfigLayers {
+  /** The effective merged configuration (defaults < global < project). */
+  readonly config: PragmaConfig;
+  /** Which layer supplied each effective field. */
+  readonly origins: ConfigOrigins;
+  /** The global XDG layer (`$XDG_CONFIG_HOME/pragma/config.json`). */
+  readonly global: ConfigLayer;
+  /**
+   * The project layer: the nearest `pragma.config.json` up the tree, or
+   * the would-be path at `cwd` when none exists.
+   */
+  readonly project: ConfigLayer;
+}
+
+/** Target layer selector for config writes. */
+type ConfigScope = "global" | "local";
+
+export type {
+  ConfigFileValues,
+  ConfigLayer,
+  ConfigLayers,
+  ConfigOrigin,
+  ConfigOrigins,
+  ConfigScope,
+  ConfigUpdate,
+  PragmaConfig,
+};

package/src/config/writeConfig.ts

@@ -1,67 +1,37 @@
-import { readFileSync, renameSync, writeFileSync } from "node:fs";
-import resolveConfigPath from "./resolveConfigPath.js";
-import type { ConfigUpdate } from "./types.js";
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import mergeConfigFileUpdate from "./mergeConfigFileUpdate.js";
+import resolveWriteConfigPath from "./resolveWriteConfigPath.js";
+import type { ConfigScope, ConfigUpdate } from "./types.js";
 
 /**
- * Write config updates to pragma.config.json.
+ * Write config updates to the resolved target layer.
  *
- * Merges updates into existing JSON. A field set to `undefined` removes it.
- * Creates the file if it doesn't exist.
+ * The target follows the global-first write rule (see
+ * `resolveWriteConfigPath`): an explicit scope wins, else the nearest
+ * existing project file, else the global XDG file. Merges updates into
+ * that file's own contents — a field set to `undefined` removes it —
+ * creating the file (and its directory) if needed, atomically via a
+ * temp file rename.
  *
- * @param cwd - Directory containing (or to contain) pragma.config.json.
+ * @param cwd - Directory the project layer is resolved from.
  * @param update - Fields to set or remove.
+ * @param scope - Optional explicit target layer (`"global"` | `"local"`).
+ * @returns Absolute path of the file that was written.
  *
  * @note Impure — writes to the filesystem.
  */
-export default function writeConfig(cwd: string, update: ConfigUpdate): void {
-  const configPath = resolveConfigPath(cwd);
+export default function writeConfig(
+  cwd: string,
+  update: ConfigUpdate,
+  scope?: ConfigScope,
+): string {
+  const configPath = resolveWriteConfigPath(cwd, scope);
   const tempPath = `${configPath}.tmp`;
+  const content = mergeConfigFileUpdate(configPath, update);
 
-  let existing: Record<string, unknown> = {};
-  try {
-    const raw = readFileSync(configPath, "utf-8");
-    existing = JSON.parse(raw) as Record<string, unknown>;
-  } catch (err: unknown) {
-    // Only swallow "file not found" — surface parse or permission errors.
-    const isNotFound =
-      err instanceof Error &&
-      "code" in err &&
-      (err as NodeJS.ErrnoException).code === "ENOENT";
-    if (!isNotFound) {
-      throw err;
-    }
-  }
-
-  if (update.tier !== undefined) {
-    existing.tier = update.tier;
-  } else if ("tier" in update) {
-    delete existing.tier;
-  }
-
-  if (update.channel !== undefined) {
-    existing.channel = update.channel;
-  } else if ("channel" in update) {
-    delete existing.channel;
-  }
-
-  if (update.packages !== undefined) {
-    existing.packages = update.packages;
-  } else if ("packages" in update) {
-    delete existing.packages;
-  }
-
-  if (update.trace !== undefined) {
-    existing.trace = update.trace;
-  } else if ("trace" in update) {
-    delete existing.trace;
-  }
-
-  if (update.framework !== undefined) {
-    existing.framework = update.framework;
-  } else if ("framework" in update) {
-    delete existing.framework;
-  }
-
-  writeFileSync(tempPath, `${JSON.stringify(existing, null, 2)}\n`);
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(tempPath, content);
   renameSync(tempPath, configPath);
+  return configPath;
 }

package/src/constants.ts

@@ -7,7 +7,9 @@
  */
 
 import pkg from "../package.json" with { type: "json" };
-import { PREFIX_MAP } from "./domains/shared/prefixes.js";
+// DEFAULT_PREFIX_MAP carries the transitional DS prefixes (ds/cs) this map
+// still keys on; remove in P4 when DS prefixes ship from their packages.
+import { DEFAULT_PREFIX_MAP as PREFIX_MAP } from "./domains/shared/prefixes.js";
 
 /** CLI program name used in help text and error messages. */
 const PROGRAM_NAME = "pragma";

package/src/domains/block/commands/list.ts

@@ -1,96 +1,11 @@
-/**
- * Wires the `pragma block list` CLI command.
- *
- * Lists all blocks visible under the current tier and channel filters.
- * Supports progressive disclosure via `--digest` and `--detailed` flags,
- * and an `--all-tiers` flag to widen the search.
- */
-
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { createListView } from "#tui";
+import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
-import type { ColumnDef } from "../../shared/contracts.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import { blockConfig } from "../blockConfig.js";
-import { listFormatters } from "../formatters/index.js";
-import { resolveBlockList } from "../orchestration/index.js";
+import { compileReadCommand } from "../../shared/stories/index.js";
+import { blockListStory } from "../stories.js";
 
+/** Wire the `pragma block list` CLI command from the block list story. */
 export default function buildListCommand(
   ctx: PragmaContext,
 ): CommandDefinition {
-  return {
-    path: ["block", "list"],
-    description: "List blocks in the design system",
-    parameters: [
-      {
-        name: "allTiers",
-        description: "Show blocks from all tiers",
-        type: "boolean",
-        default: false,
-      },
-      {
-        name: "digest",
-        description: "Show enriched summary with implementations",
-        type: "boolean",
-        default: false,
-      },
-      {
-        name: "detailed",
-        description: "Show full details for each block",
-        type: "boolean",
-        default: false,
-      },
-    ],
-    meta: {
-      examples: [
-        "pragma block list",
-        "pragma block list --all-tiers",
-        "pragma block list --digest",
-        "pragma block list --detailed",
-        "pragma block list --llm",
-        "pragma block list --format json",
-      ],
-    },
-    execute: async (
-      params: Record<string, unknown>,
-    ): Promise<CommandResult> => {
-      const contract = await resolveBlockList(ctx, {
-        allTiers: params.allTiers === true,
-        digest: params.digest === true,
-        detailed: params.detailed === true,
-      });
-
-      return createOutputResult(contract.result.items, {
-        plain: selectFormatter(ctx, listFormatters),
-        ink: (data) =>
-          createListView({
-            heading: "Blocks",
-            domain: "block",
-            items: data,
-            columns: reorderColumns(blockConfig.listColumns, [
-              "name",
-              "type",
-              "tier",
-              "modifiers",
-              "uri",
-            ]),
-          }),
-      });
-    },
-  };
-}
-
-function reorderColumns<T>(
-  columns: readonly ColumnDef<T>[],
-  order: readonly string[],
-): readonly ColumnDef<T>[] {
-  const byKey = new Map(columns.map((col) => [col.key, col]));
-  return order.flatMap((key) => {
-    const col = byKey.get(key as keyof T & string);
-    return col ? [col] : [];
-  });
+  return compileReadCommand(ctx, blockListStory);
 }

package/src/domains/block/commands/lookup.ts

@@ -1,173 +1,14 @@
-/**
- * Wires the `pragma block lookup <name-or-uri...>` CLI command.
- *
- * Accepts a positional block name or IRI and optional aspect flags (anatomy,
- * modifiers, tokens, implementations). Delegates to {@link lookupBlock} for
- * data retrieval and {@link lookupFormatters} for output rendering.
- */
-
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { PragmaError } from "#error";
-import { createLookupView } from "#tui";
+import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
-import type { LookupResult } from "../../shared/contracts.js";
-import { renderLookupResults } from "../../shared/formatters.js";
-import type { BlockDetailed } from "../../shared/types/index.js";
-import { createLookupOptions, lookupFormatters } from "../formatters/index.js";
-import { resolveAspects } from "../helpers/index.js";
-import { listBlocks } from "../operations/index.js";
-import {
-  buildBlockFilters,
-  resolveBlockLookup,
-} from "../orchestration/index.js";
-import type { AspectFlags } from "../types.js";
-
-interface BlockLookupOutput {
-  readonly result: LookupResult<BlockDetailed>;
-  readonly detailed: boolean;
-  readonly aspects: AspectFlags;
-}
+import { compileLookupCommand } from "../../shared/stories/index.js";
+import { blockLookupStory } from "../stories.js";
 
+/**
+ * Wire the `pragma block lookup <name-or-uri...>` CLI command from the
+ * block lookup story.
+ */
 export default function buildLookupCommand(
   ctx: PragmaContext,
 ): CommandDefinition {
-  return {
-    path: ["block", "lookup"],
-    description: "Look up block details",
-    parameters: [
-      {
-        name: "names",
-        description: "Block names or IRIs",
-        type: "multiselect",
-        positional: true,
-        required: true,
-        complete: async (partial: string) => {
-          const all = await listBlocks(ctx.store, ctx.config);
-          return all
-            .map((c) => c.name)
-            .filter((n) => n.toLowerCase().startsWith(partial.toLowerCase()));
-        },
-      },
-      {
-        name: "detailed",
-        description:
-          "Show full details including anatomy, modifiers, tokens, and implementations",
-        type: "boolean",
-        default: false,
-      },
-      {
-        name: "anatomy",
-        description: "Show anatomy tree",
-        type: "boolean",
-        default: false,
-      },
-      {
-        name: "modifiers",
-        description: "Show modifier values",
-        type: "boolean",
-        default: false,
-      },
-      {
-        name: "tokens",
-        description: "Show token references",
-        type: "boolean",
-        default: false,
-      },
-      {
-        name: "implementations",
-        description: "Show implementation paths",
-        type: "boolean",
-        default: false,
-      },
-    ],
-    parameterGroups: {
-      "Aspect filters": ["anatomy", "modifiers", "tokens", "implementations"],
-    },
-    meta: {
-      examples: [
-        "pragma block lookup Button",
-        "pragma block lookup Button Card",
-        "pragma block lookup Button --detailed",
-        "pragma block lookup Button --anatomy --modifiers",
-        "pragma block lookup Button --detailed --llm",
-        "pragma block lookup ds:global.component.button",
-      ],
-    },
-    execute: async (
-      params: Record<string, unknown>,
-    ): Promise<CommandResult> => {
-      const names = normalizeNames(params.names, params.name);
-      if (names.length === 0) {
-        throw PragmaError.invalidInput("names", "(empty)", {
-          recovery: {
-            message: "List available blocks.",
-            cli: "pragma block list",
-            mcp: { tool: "block_list" },
-          },
-        });
-      }
-
-      const detailed = params.detailed === true;
-      const aspectInput: Partial<AspectFlags> = {
-        anatomy: params.anatomy === true,
-        modifiers: params.modifiers === true,
-        tokens: params.tokens === true,
-        implementations: params.implementations === true,
-      };
-
-      const isAspectSelected =
-        aspectInput.anatomy ||
-        aspectInput.modifiers ||
-        aspectInput.tokens ||
-        aspectInput.implementations;
-      const showDetailed = detailed || (isAspectSelected ?? false);
-      const aspects = resolveAspects(aspectInput);
-
-      const contract = await resolveBlockLookup(
-        ctx.store,
-        names,
-        buildBlockFilters(ctx),
-      );
-
-      return createOutputResult<BlockLookupOutput>(
-        { result: contract.result, detailed: showDetailed, aspects },
-        {
-          plain: ({ result, detailed: isDetailed, aspects: selectedAspects }) =>
-            renderLookupResults({
-              ctx,
-              result,
-              formatters: lookupFormatters,
-              mapResult: (block) => ({
-                block,
-                detailed: isDetailed,
-                aspects: selectedAspects,
-              }),
-            }),
-          ink: ({ result, detailed: isDetailed, aspects: selectedAspects }) =>
-            createLookupView({
-              results: result.results,
-              errors: result.errors,
-              domain: "block",
-              options: createLookupOptions(isDetailed, selectedAspects),
-            }),
-        },
-      );
-    },
-  };
-}
-
-function normalizeNames(names: unknown, legacyName?: unknown): string[] {
-  if (Array.isArray(names)) {
-    return names.filter(
-      (name): name is string => typeof name === "string" && name.length > 0,
-    );
-  }
-  if (typeof legacyName === "string" && legacyName.length > 0) {
-    return [legacyName];
-  }
-  return [];
+  return compileLookupCommand(ctx, blockLookupStory);
 }

package/src/domains/block/commands/sample.ts

@@ -11,6 +11,7 @@ import {
 } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
 import { selectFormatter } from "../../shared/formatters.js";
+import parseSampleCount from "../../shared/parseSampleCount.js";
 import type { BlockDetailed, SampleOutput } from "../../shared/types/index.js";
 import { sampleFormatters } from "../formatters/index.js";
 import { sampleBlocks } from "../operations/index.js";
@@ -38,7 +39,7 @@ export default function sampleCommand(ctx: PragmaContext): CommandDefinition {
       examples: ["pragma block sample", "pragma block sample --count 3"],
     },
     async execute(params) {
-      const count = Number(params.count ?? 2);
+      const count = parseSampleCount(params.count);
       const filters = buildBlockFilters(ctx);
       const result = await sampleBlocks(ctx.store, filters, count);
 

package/src/domains/block/formatters/list.test.ts

@@ -1,11 +1,11 @@
 import type { URI } from "@canonical/ke";
 import { describe, expect, it } from "vitest";
-import { PREFIX_MAP } from "../../shared/prefixes.js";
+import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
 import type { BlockSummary } from "../../shared/types/index.js";
 import formatters from "./list.js";
 
 const BUTTON: BlockSummary = {
-  uri: `${PREFIX_MAP.ds}button` as URI,
+  uri: `${DEFAULT_PREFIX_MAP.ds}button` as URI,
   name: "Button",
   tier: "global",
   modifiers: ["importance", "density"],
@@ -18,7 +18,7 @@ const BUTTON: BlockSummary = {
 };
 
 const CARD: BlockSummary = {
-  uri: `${PREFIX_MAP.ds}card` as URI,
+  uri: `${DEFAULT_PREFIX_MAP.ds}card` as URI,
   name: "Card",
   tier: "global",
   modifiers: [],

package/src/domains/block/formatters/lookup.test.ts

@@ -1,12 +1,12 @@
 import type { URI } from "@canonical/ke";
 import { describe, expect, it } from "vitest";
-import { PREFIX_MAP } from "../../shared/prefixes.js";
+import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
 import type { BlockDetailed } from "../../shared/types/index.js";
 import type { AspectFlags } from "../types.js";
 import formatters from "./lookup.js";
 
 const BUTTON_DETAILED: BlockDetailed = {
-  uri: `${PREFIX_MAP.ds}global.component.button` as URI,
+  uri: `${DEFAULT_PREFIX_MAP.ds}global.component.button` as URI,
   name: "Button",
   type: "component",
   tier: "global",
@@ -40,7 +40,7 @@ const BUTTON_DETAILED: BlockDetailed = {
   ],
   modifierFamilies: [
     {
-      uri: `${PREFIX_MAP.ds}modifier_family.importance` as URI,
+      uri: `${DEFAULT_PREFIX_MAP.ds}modifier_family.importance` as URI,
       name: "importance",
       values: ["default", "primary", "secondary"],
     },
@@ -56,7 +56,7 @@ const BUTTON_DETAILED: BlockDetailed = {
   ],
   subcomponents: [
     {
-      uri: `${PREFIX_MAP.ds}global.subcomponent.button.icon` as URI,
+      uri: `${DEFAULT_PREFIX_MAP.ds}global.subcomponent.button.icon` as URI,
       name: "Button Icon",
     },
   ],
@@ -65,7 +65,7 @@ const BUTTON_DETAILED: BlockDetailed = {
   ],
   tokens: [
     {
-      uri: `${PREFIX_MAP.ds}token.color.primary` as URI,
+      uri: `${DEFAULT_PREFIX_MAP.ds}token.color.primary` as URI,
       name: "color.primary",
     },
   ],