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

package/src/config/readConfigLayers.ts

@@ -0,0 +1,115 @@
+import { readFileSync } from "node:fs";
+import { DEFAULT_CONFIG } from "./defaultConfig.js";
+import findProjectConfigPath from "./findProjectConfigPath.js";
+import parseConfigValues from "./parseConfigValues.js";
+import resolveConfigPath from "./resolveConfigPath.js";
+import resolveGlobalConfigPath from "./resolveGlobalConfigPath.js";
+import type {
+  ConfigFileValues,
+  ConfigLayers,
+  ConfigOrigin,
+  PragmaConfig,
+} from "./types.js";
+
+/**
+ * Fields the built-in defaults document contributes to the layer merge.
+ *
+ * `packages` is deliberately absent: it reaches the ref merge through
+ * `DEFAULT_PACKAGES` instead, so global `refs.json` entries keep merging
+ * over the default packages by name. Surfacing it here would make the
+ * defaults look user-declared and replace the merged set wholesale.
+ */
+const DEFAULT_LAYER: ConfigFileValues = {
+  channel: DEFAULT_CONFIG.channel,
+};
+
+/**
+ * Resolve the layered configuration with per-field provenance.
+ *
+ * Layer order, least to most specific: built-in defaults, the global XDG
+ * file (`~/.config/pragma/config.json`), and the nearest project
+ * `pragma.config.json` up the tree. Merging is per field — a field set by
+ * a more specific layer wins wholesale (`packages` replaces as a whole,
+ * preserving the established project-pins-exactly semantics).
+ *
+ * @param cwd - Directory the project layer is resolved from.
+ * @returns The effective config, per-field origins, and both layers.
+ * @throws PragmaError with code `CONFIG_ERROR` when either file is invalid.
+ * @note Impure — reads config files from the filesystem.
+ */
+export default function readConfigLayers(
+  cwd: string = process.cwd(),
+): ConfigLayers {
+  const globalPath = resolveGlobalConfigPath();
+  const projectPath = findProjectConfigPath(cwd) ?? resolveConfigPath(cwd);
+
+  const globalFile = readConfigFile(globalPath);
+  const projectFile = readConfigFile(projectPath);
+
+  const pick = <K extends keyof ConfigFileValues>(
+    field: K,
+  ): { value: ConfigFileValues[K] | undefined; origin: ConfigOrigin } => {
+    if (field in projectFile.values) {
+      return { value: projectFile.values[field], origin: "project" };
+    }
+    if (field in globalFile.values) {
+      return { value: globalFile.values[field], origin: "global" };
+    }
+    if (field in DEFAULT_LAYER) {
+      return { value: DEFAULT_LAYER[field], origin: "default" };
+    }
+    return { value: undefined, origin: "default" };
+  };
+
+  const tier = pick("tier");
+  const channel = pick("channel");
+  const packages = pick("packages");
+  const trace = pick("trace");
+  const framework = pick("framework");
+  const stories = pick("stories");
+  const prefixes = pick("prefixes");
+
+  const config: PragmaConfig = {
+    tier: tier.value,
+    channel: channel.value ?? DEFAULT_CONFIG.channel,
+    ...(packages.value ? { packages: packages.value } : {}),
+    ...(trace.value !== undefined ? { trace: trace.value } : {}),
+    ...(framework.value !== undefined ? { framework: framework.value } : {}),
+    ...(stories.value ? { stories: stories.value } : {}),
+    ...(prefixes.value ? { prefixes: prefixes.value } : {}),
+  };
+
+  return {
+    config,
+    origins: {
+      tier: tier.origin,
+      channel: channel.origin,
+      packages: packages.origin,
+      trace: trace.origin,
+      framework: framework.origin,
+      stories: stories.origin,
+      prefixes: prefixes.origin,
+    },
+    global: { path: globalPath, exists: globalFile.exists },
+    project: { path: projectPath, exists: projectFile.exists },
+  };
+}
+
+/**
+ * Read and parse one config file layer.
+ *
+ * A missing or unreadable file contributes no values — the layer simply
+ * does not participate in the merge.
+ */
+function readConfigFile(path: string): {
+  values: ConfigFileValues;
+  exists: boolean;
+} {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return { values: {}, exists: false };
+  }
+  return { values: parseConfigValues(raw, path), exists: true };
+}

package/src/config/resolveGlobalConfigPath.ts

@@ -0,0 +1,13 @@
+import { join } from "node:path";
+import { globalConfigDir } from "../domains/refs/operations/paths.js";
+
+/**
+ * Resolve the absolute path of the global config file.
+ *
+ * Lives next to `refs.json` in the pragma XDG config directory:
+ * `$XDG_CONFIG_HOME/pragma/config.json`, defaulting to
+ * `~/.config/pragma/config.json`.
+ */
+export default function resolveGlobalConfigPath(): string {
+  return join(globalConfigDir(), "config.json");
+}

package/src/config/resolveWriteConfigPath.test.ts

@@ -0,0 +1,53 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import resolveWriteConfigPath from "./resolveWriteConfigPath.js";
+
+describe("resolveWriteConfigPath", () => {
+  let xdgDir: string;
+  let projectDir: string;
+  let originalXdg: string | undefined;
+
+  beforeEach(() => {
+    originalXdg = process.env.XDG_CONFIG_HOME;
+    xdgDir = mkdtempSync(join(tmpdir(), "pragma-write-xdg-"));
+    process.env.XDG_CONFIG_HOME = xdgDir;
+    projectDir = mkdtempSync(join(tmpdir(), "pragma-write-project-"));
+    mkdirSync(join(projectDir, ".git"));
+  });
+
+  afterEach(() => {
+    process.env.XDG_CONFIG_HOME = originalXdg;
+    rmSync(xdgDir, { recursive: true, force: true });
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it("targets the nearest existing project file", () => {
+    writeFileSync(join(projectDir, "pragma.config.json"), "{}");
+    const sub = join(projectDir, "packages/app");
+    mkdirSync(sub, { recursive: true });
+    expect(resolveWriteConfigPath(sub)).toBe(
+      join(projectDir, "pragma.config.json"),
+    );
+  });
+
+  it("falls back to the global file when no project file exists", () => {
+    expect(resolveWriteConfigPath(projectDir)).toBe(
+      join(xdgDir, "pragma/config.json"),
+    );
+  });
+
+  it("honors an explicit local scope even without an existing file", () => {
+    expect(resolveWriteConfigPath(projectDir, "local")).toBe(
+      join(projectDir, "pragma.config.json"),
+    );
+  });
+
+  it("honors an explicit global scope over an existing project file", () => {
+    writeFileSync(join(projectDir, "pragma.config.json"), "{}");
+    expect(resolveWriteConfigPath(projectDir, "global")).toBe(
+      join(xdgDir, "pragma/config.json"),
+    );
+  });
+});

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

@@ -5,8 +5,9 @@
  * so consumers can import types without pulling in filesystem code.
  */
 
-import type { Channel } from "../constants.js";
+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 {
@@ -20,6 +21,24 @@ interface PragmaConfig {
    * When absent, the hardcoded defaults are used.
    */
   packages?: ReadonlyArray<RawPackageEntry> | undefined;
+  /** Whether query access tracing is enabled. Overridden by PRAGMA_TRACE env var. */
+  trace?: boolean | undefined;
+  /**
+   * Preferred UI framework (`react` | `svelte` | `lit`). Currently advisory
+   * 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;
 }
 
 /** Partial update payload for writing config changes. */
@@ -30,6 +49,73 @@ interface ConfigUpdate {
   channel?: Channel | undefined;
   /** New packages list, `undefined` to remove the field. */
   packages?: ReadonlyArray<RawPackageEntry> | undefined;
+  /** Enable/disable query tracing, `undefined` to remove the field. */
+  trace?: boolean | undefined;
+  /** New preferred framework, `undefined` to remove the field. */
+  framework?: Framework | undefined;
+}
+
+/**
+ * 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>>;
 }
 
-export type { ConfigUpdate, PragmaConfig };
+/** 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;
+}
+
+/** 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,55 +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;
-  }
-
-  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

@@ -24,6 +24,16 @@ const VALID_CHANNELS = ["normal", "experimental", "prerelease"] as const;
 /** A release channel name. */
 type Channel = (typeof VALID_CHANNELS)[number];
 
+/** Allowed values for the `framework` config field. */
+const VALID_FRAMEWORKS = ["react", "svelte", "lit"] as const;
+
+/**
+ * A preferred UI framework. Currently advisory only (a no-op); reserved for
+ * future use to default framework-specific behaviour (e.g. which generator
+ * `pragma`/`summon` scaffolds, which component tier is surfaced).
+ */
+type Framework = (typeof VALID_FRAMEWORKS)[number];
+
 /**
  * Per-namespace property URIs for semantically equivalent fields.
  * Each ontology uses different property names for the same concept
@@ -68,11 +78,12 @@ const PROPERTY_MAP: Record<string, OntologyPropertyMap> = {
   },
 };
 
-export type { Channel, OntologyPropertyMap };
+export type { Channel, Framework, OntologyPropertyMap };
 export {
   PROGRAM_DESCRIPTION,
   PROGRAM_NAME,
   PROPERTY_MAP,
   VALID_CHANNELS,
+  VALID_FRAMEWORKS,
   VERSION,
 };

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

@@ -1,4 +1,5 @@
-/** @module Re-exports block command builders (`lookup`, `list`). */
+/** @module Re-exports block command builders (`list`, `lookup`, `sample`). */
 
 export { default as listCommand } from "./list.js";
 export { default as lookupCommand } from "./lookup.js";
+export { default as sampleCommand } from "./sample.js";

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);
 }