@canonical/pragma-cli 0.30.0 → 0.32.0

package/src/config/readConfigLayers.test.ts

@@ -1,107 +0,0 @@
-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 { PragmaError } from "../error/PragmaError.js";
-import readConfigLayers from "./readConfigLayers.js";
-
-describe("readConfigLayers", () => {
-  let xdgDir: string;
-  let projectDir: string;
-  let originalXdg: string | undefined;
-
-  beforeEach(() => {
-    originalXdg = process.env.XDG_CONFIG_HOME;
-    xdgDir = mkdtempSync(join(tmpdir(), "pragma-layers-xdg-"));
-    process.env.XDG_CONFIG_HOME = xdgDir;
-    projectDir = mkdtempSync(join(tmpdir(), "pragma-layers-project-"));
-    mkdirSync(join(projectDir, ".git"));
-  });
-
-  afterEach(() => {
-    process.env.XDG_CONFIG_HOME = originalXdg;
-    rmSync(xdgDir, { recursive: true, force: true });
-    rmSync(projectDir, { recursive: true, force: true });
-  });
-
-  function writeGlobal(content: string): void {
-    mkdirSync(join(xdgDir, "pragma"), { recursive: true });
-    writeFileSync(join(xdgDir, "pragma/config.json"), content);
-  }
-
-  function writeProject(content: string): void {
-    writeFileSync(join(projectDir, "pragma.config.json"), content);
-  }
-
-  it("returns defaults with default origins when no layer exists", () => {
-    const layers = readConfigLayers(projectDir);
-    expect(layers.config).toEqual({ tier: undefined, channel: "normal" });
-    expect(layers.origins).toEqual({
-      tier: "default",
-      channel: "default",
-      packages: "default",
-      trace: "default",
-      framework: "default",
-      stories: "default",
-      prefixes: "default",
-    });
-    expect(layers.global.exists).toBe(false);
-    expect(layers.project.exists).toBe(false);
-    expect(layers.project.path).toBe(join(projectDir, "pragma.config.json"));
-  });
-
-  it("reads the global layer when no project file exists", () => {
-    writeGlobal('{"channel":"experimental","tier":"global"}');
-    const layers = readConfigLayers(projectDir);
-    expect(layers.config.channel).toBe("experimental");
-    expect(layers.config.tier).toBe("global");
-    expect(layers.origins.channel).toBe("global");
-    expect(layers.origins.tier).toBe("global");
-    expect(layers.global.exists).toBe(true);
-  });
-
-  it("merges per field — project wins only the fields it sets", () => {
-    writeGlobal('{"channel":"experimental","trace":true}');
-    writeProject('{"tier":"apps/lxd"}');
-    const layers = readConfigLayers(projectDir);
-    expect(layers.config).toEqual({
-      tier: "apps/lxd",
-      channel: "experimental",
-      trace: true,
-    });
-    expect(layers.origins).toEqual({
-      tier: "project",
-      channel: "global",
-      packages: "default",
-      trace: "global",
-      framework: "default",
-      stories: "default",
-      prefixes: "default",
-    });
-  });
-
-  it("lets the project override a global field wholesale", () => {
-    writeGlobal('{"packages":["@canonical/a"],"channel":"experimental"}');
-    writeProject('{"packages":["@canonical/b"],"channel":"normal"}');
-    const layers = readConfigLayers(projectDir);
-    expect(layers.config.packages).toEqual(["@canonical/b"]);
-    expect(layers.config.channel).toBe("normal");
-    expect(layers.origins.packages).toBe("project");
-    expect(layers.origins.channel).toBe("project");
-  });
-
-  it("finds the project layer from a subdirectory", () => {
-    writeProject('{"tier":"apps/lxd"}');
-    const sub = join(projectDir, "packages/app");
-    mkdirSync(sub, { recursive: true });
-    const layers = readConfigLayers(sub);
-    expect(layers.config.tier).toBe("apps/lxd");
-    expect(layers.project.path).toBe(join(projectDir, "pragma.config.json"));
-    expect(layers.project.exists).toBe(true);
-  });
-
-  it("throws on invalid JSON in the global layer", () => {
-    writeGlobal("{not json");
-    expect(() => readConfigLayers(projectDir)).toThrow(PragmaError);
-  });
-});

package/src/config/readConfigLayers.ts

@@ -1,115 +0,0 @@
-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/resolveConfigPath.test.ts

@@ -1,20 +0,0 @@
-import { resolve } from "node:path";
-import { describe, expect, it } from "vitest";
-import resolveConfigPath from "./resolveConfigPath.js";
-
-describe("resolveConfigPath", () => {
-  it("appends pragma.config.json to the given directory", () => {
-    expect(resolveConfigPath("/home/user/project")).toBe(
-      resolve("/home/user/project", "pragma.config.json"),
-    );
-  });
-
-  it("resolves relative paths against cwd", () => {
-    const result = resolveConfigPath(".");
-    expect(result).toBe(resolve(process.cwd(), "pragma.config.json"));
-  });
-
-  it("handles nested directories", () => {
-    expect(resolveConfigPath("/a/b/c")).toBe("/a/b/c/pragma.config.json");
-  });
-});

package/src/config/resolveConfigPath.ts

@@ -1,11 +0,0 @@
-import { resolve } from "node:path";
-
-/**
- * Resolve the absolute path to pragma.config.json for a given cwd.
- *
- * @param cwd - Directory to resolve from.
- * @returns Absolute file path to the configuration file.
- */
-export default function resolveConfigPath(cwd: string): string {
-  return resolve(cwd, "pragma.config.json");
-}

package/src/config/resolveGlobalConfigPath.ts

@@ -1,13 +0,0 @@
-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

@@ -1,53 +0,0 @@
-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

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

@@ -1,121 +0,0 @@
-/**
- * Configuration data shapes for pragma.config.json.
- *
- * Separates the persisted config shape from the read/write logic
- * so consumers can import types without pulling in filesystem code.
- */
-
-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 {
-  /** Active tier path, or `undefined` when no tier is configured. */
-  tier: string | undefined;
-  /** Release channel controlling component visibility. */
-  channel: Channel;
-  /**
-   * Semantic package sources. Each entry is a package name (npm) or an
-   * object with `{ name, source }` where source is `file://` or `git+https://`.
-   * 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. */
-interface ConfigUpdate {
-  /** New tier path, `undefined` to remove the tier field. */
-  tier?: string | undefined;
-  /** New channel, `undefined` to remove the channel field. */
-  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>>;
-}
-
-/** 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,37 +0,0 @@
-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 the resolved target layer.
- *
- * 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 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,
-  scope?: ConfigScope,
-): string {
-  const configPath = resolveWriteConfigPath(cwd, scope);
-  const tempPath = `${configPath}.tmp`;
-  const content = mergeConfigFileUpdate(configPath, update);
-
-  mkdirSync(dirname(configPath), { recursive: true });
-  writeFileSync(tempPath, content);
-  renameSync(tempPath, configPath);
-  return configPath;
-}

package/src/domains/block/blockConfig.ts

@@ -1,97 +0,0 @@
-import type { EntityDisplayConfig } from "../shared/contracts.js";
-import { P } from "../shared/prefixes.js";
-import type {
-  BlockDetailed,
-  BlockDigest,
-  BlockSummary,
-  FilterConfig,
-} from "../shared/types/index.js";
-
-/** Display-contract configuration for block entities (components, patterns, layouts). */
-export const blockConfig: EntityDisplayConfig<
-  BlockSummary,
-  BlockDigest,
-  BlockDetailed
-> = {
-  domain: "block",
-  entityName: "block",
-  rdfTypes: [
-    `${P.ds}Component`,
-    `${P.ds}Pattern`,
-    `${P.ds}Layout`,
-    `${P.ds}Subcomponent`,
-  ],
-  listColumns: [
-    { key: "uri", label: "IRI" },
-    { key: "name", label: "Name" },
-    { key: "type", label: "Type" },
-    { key: "tier", label: "Tier" },
-    {
-      key: "modifiers",
-      label: "Modifiers",
-      showWhenEmpty: false,
-      format: (value) =>
-        Array.isArray(value)
-          ? value.filter((entry) => typeof entry === "string").join(", ")
-          : "",
-    },
-    {
-      key: "implementations",
-      label: "Implementations",
-      showWhenEmpty: false,
-      format: (value) =>
-        Array.isArray(value)
-          ? value
-              .filter(
-                (entry): entry is { framework: string; available: boolean } =>
-                  typeof entry === "object" &&
-                  entry !== null &&
-                  "framework" in entry &&
-                  "available" in entry,
-              )
-              .filter((entry) => entry.available)
-              .map((entry) => entry.framework)
-              .join(", ")
-          : "",
-    },
-    {
-      key: "nodeCount",
-      label: "Nodes",
-      showWhenEmpty: false,
-      format: (value) =>
-        typeof value === "number" && value > 0 ? String(value) : "",
-    },
-    {
-      key: "tokenCount",
-      label: "Tokens",
-      showWhenEmpty: false,
-      format: (value) =>
-        typeof value === "number" && value > 0 ? String(value) : "",
-    },
-  ],
-  digestColumns: [{ key: "summary", label: "Summary", showWhenEmpty: false }],
-  lookupSections: [
-    { key: "summary", heading: "Summary", kind: "field" },
-    { key: "whenToUse", heading: "When to use", kind: "field" },
-    { key: "whenNotToUse", heading: "When not to use", kind: "field" },
-    { key: "guidelines", heading: "Guidelines", kind: "field" },
-    { key: "anatomy", heading: "Anatomy", kind: "tree" },
-    { key: "anatomyDsl", heading: "Anatomy (DSL)", kind: "code" },
-    { key: "anatomyClassic", heading: "Anatomy (classic)", kind: "field" },
-    { key: "modifierFamilies", heading: "Modifiers", kind: "table" },
-    { key: "properties", heading: "Properties", kind: "nested-table" },
-    { key: "subcomponents", heading: "Subcomponents", kind: "tree" },
-    { key: "implementationPaths", heading: "Implementations", kind: "list" },
-    { key: "tokens", heading: "Tokens", kind: "list" },
-  ],
-  emptyRecovery: (_filters: FilterConfig) => ({
-    message: "List visible blocks.",
-    cli: "pragma block list",
-    mcp: { tool: "block_list" },
-  }),
-  notFoundRecovery: (_query: string) => ({
-    message: "List visible blocks.",
-    cli: "pragma block list",
-    mcp: { tool: "block_list" },
-  }),
-};

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

@@ -1,5 +0,0 @@
-/** @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";