@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/domains/shared/emptyErrorRecovery.test.ts

@@ -1,106 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { PragmaError } from "#error";
-import blockSpecs from "../block/mcp/specs.js";
-import blockEmptyError from "../block/orchestration/blockEmptyError.js";
-import modifierSpecs from "../modifier/mcp/specs.js";
-import modifierEmptyError from "../modifier/orchestration/modifierEmptyError.js";
-import { TOKEN_READ_SURFACE_ENABLED } from "../token/featureFlag.js";
-import tokenSpecs from "../token/mcp/specs.js";
-import tokenEmptyError from "../token/orchestration/tokenEmptyError.js";
-import type { FilterConfig } from "./types/index.js";
-
-const filters: FilterConfig = { tier: "Apps/WPE", channel: "normal" };
-const allTiers: FilterConfig = { tier: undefined, channel: "normal" };
-
-/**
- * Every distinct empty-result scenario each domain can produce, paired with the
- * set of MCP tool names that domain actually registers. The invariant below
- * holds the four hints to the S-grade contract so authored consistency cannot
- * silently re-drift.
- */
-const cases: ReadonlyArray<{
-  domain: string;
-  error: PragmaError;
-  toolNames: ReadonlySet<string>;
-  // store-empty (packages absent) → the install rung, which must NOT carry an
-  // mcp retry (re-listing an absent store loops). filter-narrowing → may carry
-  // a list-retry mcp pointer.
-  storeEmpty: boolean;
-}> = [
-  {
-    domain: "block (filter active)",
-    error: blockEmptyError(filters, false),
-    toolNames: new Set(blockSpecs.map((s) => s.name)),
-    storeEmpty: false,
-  },
-  {
-    domain: "block (all tiers — terminal)",
-    error: blockEmptyError(allTiers, true),
-    toolNames: new Set(blockSpecs.map((s) => s.name)),
-    storeEmpty: false,
-  },
-  // The token read surface (and with it the paths that raise
-  // tokenEmptyError) is gated behind the token feature flag; its recovery
-  // hints can only point at registered tools while the surface is live.
-  ...(TOKEN_READ_SURFACE_ENABLED
-    ? [
-        {
-          domain: "token (category active)",
-          error: tokenEmptyError("color"),
-          toolNames: new Set(tokenSpecs.map((s) => s.name)),
-          storeEmpty: false,
-        },
-        {
-          domain: "token (store-empty)",
-          error: tokenEmptyError(),
-          toolNames: new Set(tokenSpecs.map((s) => s.name)),
-          storeEmpty: true,
-        },
-      ]
-    : []),
-  {
-    domain: "modifier (store-empty)",
-    error: modifierEmptyError(),
-    toolNames: new Set(modifierSpecs.map((s) => s.name)),
-    storeEmpty: true,
-  },
-  // `standard` left this contract with its domain: the bundled pack has no
-  // emptyError hook (a pinned PARITY_GAP), so an empty standard list renders
-  // zero rows instead of an EMPTY_RESULTS recovery.
-];
-
-describe("empty-error recovery contract (cross-domain)", () => {
-  it.each(cases)("$domain honours the S-grade recovery shape", ({
-    error,
-    toolNames,
-    storeEmpty,
-  }) => {
-    const recovery = error.recovery;
-
-    // Terminal state (e.g. block already at all-tiers) is allowed.
-    if (recovery === undefined) return;
-
-    // Every hint carries a human-readable message.
-    expect(recovery.message).toBeTruthy();
-
-    // No hint is message-only: a runnable cli is always present (either a
-    // pragma re-list for filter-narrowing, or a bun add for store-empty).
-    expect(recovery.cli).toBeTruthy();
-
-    if (storeEmpty) {
-      // Store-empty must NOT carry an mcp retry: re-listing an absent store
-      // just loops. This is the anti-drift guard for the install rung.
-      expect(recovery.mcp).toBeUndefined();
-    } else if (recovery.mcp !== undefined) {
-      // A filter-narrowing mcp pointer must name a tool the domain actually
-      // registers — catches renamed/dangling tool references.
-      expect(toolNames.has(recovery.mcp.tool)).toBe(true);
-    }
-  });
-
-  it("never points an install hint at @canonical/ds-global (not a real default)", () => {
-    for (const { error } of cases) {
-      expect(error.recovery?.cli ?? "").not.toContain("ds-global");
-    }
-  });
-});

package/src/domains/shared/extractLocalName.test.ts

@@ -1,21 +0,0 @@
-import { describe, expect, it } from "vitest";
-import extractLocalName from "./extractLocalName.js";
-import { DEFAULT_PREFIX_MAP } from "./prefixes.js";
-
-describe("extractLocalName", () => {
-  it("extracts after hash", () => {
-    expect(extractLocalName("http://example.org/ns#Thing")).toBe("Thing");
-  });
-
-  it("extracts after last slash", () => {
-    expect(extractLocalName(`${DEFAULT_PREFIX_MAP.ds}global`)).toBe("global");
-  });
-
-  it("returns full string when no separator", () => {
-    expect(extractLocalName("plain")).toBe("plain");
-  });
-
-  it("handles nested path", () => {
-    expect(extractLocalName(`${DEFAULT_PREFIX_MAP.ds}apps/lxd`)).toBe("lxd");
-  });
-});

package/src/domains/shared/extractLocalName.ts

@@ -1,14 +0,0 @@
-/**
- * Extract the local name from a full URI.
- *
- * `"https://ds.canonical.com/global"` → `"global"`
- * `"http://example.org/ns#Thing"` → `"Thing"`
- */
-
-export default function extractLocalName(uri: string): string {
-  const hashIdx = uri.lastIndexOf("#");
-  if (hashIdx !== -1) return uri.slice(hashIdx + 1);
-  const slashIdx = uri.lastIndexOf("/");
-  if (slashIdx !== -1) return uri.slice(slashIdx + 1);
-  return uri;
-}

package/src/domains/shared/filters/buildChannelFilter.test.ts

@@ -1,52 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { P } from "../prefixes.js";
-import { buildChannelFilter, CHANNEL_RELEASES } from "./buildChannelFilter.js";
-
-describe("CHANNEL_RELEASES", () => {
-  it("normal includes only stable", () => {
-    expect(CHANNEL_RELEASES.normal).toEqual(["stable"]);
-  });
-
-  it("experimental includes stable + experimental", () => {
-    expect(CHANNEL_RELEASES.experimental).toEqual(["stable", "experimental"]);
-  });
-
-  it("prerelease includes all four", () => {
-    expect(CHANNEL_RELEASES.prerelease).toEqual([
-      "stable",
-      "experimental",
-      "alpha",
-      "beta",
-    ]);
-  });
-});
-
-describe("buildChannelFilter", () => {
-  it("generates OPTIONAL + FILTER for normal", () => {
-    const result = buildChannelFilter("normal");
-    expect(result).toContain(`OPTIONAL { ?component ${P.ds}release ?release }`);
-    expect(result).toContain(
-      `FILTER(!BOUND(?release) || ?release IN (${P.ds}stable))`,
-    );
-  });
-
-  it("generates filter for experimental with two releases", () => {
-    const result = buildChannelFilter("experimental");
-    expect(result).toContain(
-      `?release IN (${P.ds}stable, ${P.ds}experimental)`,
-    );
-  });
-
-  it("generates filter for prerelease with all releases", () => {
-    const result = buildChannelFilter("prerelease");
-    expect(result).toContain(
-      `?release IN (${P.ds}stable, ${P.ds}experimental, ${P.ds}alpha, ${P.ds}beta)`,
-    );
-  });
-
-  it("uses custom variable name", () => {
-    const result = buildChannelFilter("normal", "r");
-    expect(result).toContain(`?r IN (${P.ds}stable)`);
-    expect(result).toContain("BOUND(?r)");
-  });
-});

package/src/domains/shared/filters/buildChannelFilter.ts

@@ -1,41 +0,0 @@
-/**
- * Channel filter — release stability visibility.
- *
- * Maps channel settings to the set of visible release levels.
- * Components without a release annotation are treated as stable.
- */
-
-import type { Channel } from "#constants";
-import { P } from "../prefixes.js";
-
-/**
- * Release levels visible per channel setting.
- */
-export const CHANNEL_RELEASES: Record<Channel, readonly string[]> = {
-  normal: ["stable"],
-  experimental: ["stable", "experimental"],
-  prerelease: ["stable", "experimental", "alpha", "beta"],
-};
-
-/**
- * Generate SPARQL clauses for channel visibility.
- *
- * Uses OPTIONAL + FILTER pattern: binds ?release if present,
- * then filters to allowed values OR unbound (= stable default).
- *
- * @param channel - Configured channel.
- * @param varName - SPARQL variable to filter (default: `"release"`).
- * @returns SPARQL OPTIONAL + FILTER clause string.
- */
-export function buildChannelFilter(
-  channel: Channel,
-  varName = "release",
-): string {
-  const releases = CHANNEL_RELEASES[channel];
-  const uriList = releases.map((r) => `${P.ds}${r}`).join(", ");
-
-  return [
-    `OPTIONAL { ?component ${P.ds}release ?${varName} }`,
-    `FILTER(!BOUND(?${varName}) || ?${varName} IN (${uriList}))`,
-  ].join("\n    ");
-}

package/src/domains/shared/filters/buildFilterConfig.ts

@@ -1,15 +0,0 @@
-/**
- * Build a FilterConfig from runtime config, optionally widening tier.
- */
-
-import type { FilterConfig, PragmaRuntime } from "../types/index.js";
-
-export default function buildFilterConfig(
-  runtime: PragmaRuntime,
-  allTiers?: boolean,
-): FilterConfig {
-  return {
-    tier: allTiers ? undefined : runtime.config.tier,
-    channel: runtime.config.channel,
-  };
-}

package/src/domains/shared/filters/buildFilters.test.ts

@@ -1,33 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { P } from "../prefixes.js";
-import { buildFilters } from "./buildFilters.js";
-
-describe("buildFilters", () => {
-  it("returns only channel filter when tier is undefined", () => {
-    const result = buildFilters({ tier: undefined, channel: "normal" });
-    expect(result).not.toContain("FILTER(?tier");
-    expect(result).toContain("FILTER(!BOUND(?release)");
-  });
-
-  it("combines tier and channel filters", () => {
-    const result = buildFilters({ tier: "apps/lxd", channel: "experimental" });
-    expect(result).toContain(
-      `FILTER(?tier IN (${P.ds}global, ${P.ds}apps, ${P.ds}apps_lxd))`,
-    );
-    expect(result).toContain(`${P.ds}stable, ${P.ds}experimental`);
-  });
-
-  it("returns channel filter for undefined tier + prerelease", () => {
-    const result = buildFilters({ tier: undefined, channel: "prerelease" });
-    expect(result).toContain(`${P.ds}alpha, ${P.ds}beta`);
-    expect(result).not.toContain("FILTER(?tier");
-  });
-
-  it("returns both filters for global tier + normal channel", () => {
-    const result = buildFilters({ tier: "global", channel: "normal" });
-    expect(result).toContain(`FILTER(?tier IN (${P.ds}global))`);
-    expect(result).toContain(
-      `FILTER(!BOUND(?release) || ?release IN (${P.ds}stable))`,
-    );
-  });
-});

package/src/domains/shared/filters/buildFilters.ts

@@ -1,30 +0,0 @@
-/**
- * Orthogonal filter combination.
- *
- * Both tier and channel filters apply simultaneously as AND constraints.
- */
-
-import type { FilterConfig } from "../types/index.js";
-import { buildChannelFilter } from "./buildChannelFilter.js";
-import { buildTierFilter } from "./buildTierFilter.js";
-
-/**
- * Build combined WHERE clause fragments for tier + channel filters.
- *
- * Returns a string to insert into a SPARQL WHERE clause body.
- * Each filter is independently optional.
- *
- * @param config - Tier and channel filter settings.
- * @returns Combined SPARQL clause fragments.
- */
-export function buildFilters(config: FilterConfig): string {
-  const parts: string[] = [];
-
-  const tierClause = buildTierFilter(config.tier);
-  if (tierClause) parts.push(tierClause);
-
-  const channelClause = buildChannelFilter(config.channel);
-  parts.push(channelClause);
-
-  return parts.join("\n    ");
-}

package/src/domains/shared/filters/buildTierFilter.test.ts

@@ -1,78 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { P } from "../prefixes.js";
-import {
-  buildTierFilter,
-  resolveTierChain,
-  tierPathToLocal,
-} from "./buildTierFilter.js";
-
-describe("resolveTierChain", () => {
-  it("returns empty array for undefined", () => {
-    expect(resolveTierChain(undefined)).toEqual([]);
-  });
-
-  it("returns ['global'] for 'global'", () => {
-    expect(resolveTierChain("global")).toEqual(["global"]);
-  });
-
-  it("returns ['global', 'apps'] for 'apps'", () => {
-    expect(resolveTierChain("apps")).toEqual(["global", "apps"]);
-  });
-
-  it("returns full chain for 'apps/lxd'", () => {
-    expect(resolveTierChain("apps/lxd")).toEqual([
-      "global",
-      "apps",
-      "apps/lxd",
-    ]);
-  });
-
-  it("handles deep nesting", () => {
-    expect(resolveTierChain("apps/lxd/storage")).toEqual([
-      "global",
-      "apps",
-      "apps/lxd",
-      "apps/lxd/storage",
-    ]);
-  });
-});
-
-describe("tierPathToLocal", () => {
-  it("converts slashes to underscores", () => {
-    expect(tierPathToLocal("apps/lxd")).toBe("apps_lxd");
-  });
-
-  it("leaves single segment unchanged", () => {
-    expect(tierPathToLocal("global")).toBe("global");
-  });
-
-  it("handles deep paths", () => {
-    expect(tierPathToLocal("apps/lxd/storage")).toBe("apps_lxd_storage");
-  });
-});
-
-describe("buildTierFilter", () => {
-  it("returns empty string for undefined tier", () => {
-    expect(buildTierFilter(undefined)).toBe("");
-  });
-
-  it("generates FILTER for 'global'", () => {
-    expect(buildTierFilter("global")).toBe(`FILTER(?tier IN (${P.ds}global))`);
-  });
-
-  it("generates FILTER for 'apps/lxd' with parent chain", () => {
-    expect(buildTierFilter("apps/lxd")).toBe(
-      `FILTER(?tier IN (${P.ds}global, ${P.ds}apps, ${P.ds}apps_lxd))`,
-    );
-  });
-
-  it("normalizes mixed-case tier paths from config", () => {
-    expect(buildTierFilter("Global")).toBe(`FILTER(?tier IN (${P.ds}global))`);
-  });
-
-  it("uses custom variable name", () => {
-    expect(buildTierFilter("apps", "t")).toBe(
-      `FILTER(?t IN (${P.ds}global, ${P.ds}apps))`,
-    );
-  });
-});

package/src/domains/shared/filters/buildTierFilter.ts

@@ -1,69 +0,0 @@
-import { P } from "../prefixes.js";
-
-/**
- * Tier filter — hierarchical visibility.
- *
- * Setting a tier activates a parent chain filter.
- * `"apps/lxd"` -> visible tiers: `global`, `apps`, `apps/lxd`.
- */
-
-/**
- * Resolve the parent chain for a tier path.
- *
- * "apps/lxd" -> ["global", "apps", "apps/lxd"]
- * "apps" -> ["global", "apps"]
- * "global" -> ["global"]
- * undefined -> [] (no filter -- all tiers visible)
- *
- * @param tierPath - Slash-separated tier path, or `undefined` for no filtering.
- * @returns Ordered array of tier paths from root to leaf.
- */
-export function resolveTierChain(tierPath: string | undefined): string[] {
-  if (tierPath === undefined) return [];
-
-  const normalizedTierPath = tierPath.trim().toLowerCase();
-
-  const chain: string[] = ["global"];
-  const segments = normalizedTierPath.split("/");
-
-  for (let i = 0; i < segments.length; i++) {
-    const path = segments.slice(0, i + 1).join("/");
-    if (path !== "global") {
-      chain.push(path);
-    }
-  }
-
-  return chain;
-}
-
-/**
- * Convert a tier path to its URI local name.
- * Slashes become underscores: `"apps/lxd"` -> `"apps_lxd"`.
- *
- * @param tierPath - Slash-separated tier path.
- * @returns Underscore-separated local name suitable for URI construction.
- */
-export function tierPathToLocal(tierPath: string): string {
-  return tierPath.trim().toLowerCase().replace(/\//g, "_");
-}
-
-/**
- * Generate a SPARQL FILTER clause for tier visibility.
- *
- * Returns an empty string when tier is undefined (no filter = all tiers visible).
- *
- * @param tierPath - Configured tier path (e.g., `"apps/lxd"`) or `undefined`.
- * @param varName - SPARQL variable to filter (default: `"tier"`).
- * @returns SPARQL FILTER clause string, or empty string when no tier is set.
- */
-export function buildTierFilter(
-  tierPath: string | undefined,
-  varName = "tier",
-): string {
-  if (tierPath === undefined) return "";
-
-  const chain = resolveTierChain(tierPath);
-  const uriList = chain.map((t) => `${P.ds}${tierPathToLocal(t)}`).join(", ");
-
-  return `FILTER(?${varName} IN (${uriList}))`;
-}

package/src/domains/shared/filters/describeFilters.ts

@@ -1,14 +0,0 @@
-/**
- * Describe active filters as human-readable key-value pairs.
- */
-
-import type { FilterConfig } from "../types/index.js";
-
-export default function describeFilters(
-  filters: FilterConfig,
-): Record<string, string> {
-  return {
-    ...(filters.tier !== undefined && { tier: filters.tier }),
-    channel: filters.channel,
-  };
-}

package/src/domains/shared/filters/index.ts

@@ -1,10 +0,0 @@
-/** @module Shared SPARQL filter builders for tier and channel visibility. */
-export { buildChannelFilter, CHANNEL_RELEASES } from "./buildChannelFilter.js";
-export { default as buildFilterConfig } from "./buildFilterConfig.js";
-export { buildFilters } from "./buildFilters.js";
-export {
-  buildTierFilter,
-  resolveTierChain,
-  tierPathToLocal,
-} from "./buildTierFilter.js";
-export { default as describeFilters } from "./describeFilters.js";

package/src/domains/shared/formatters.ts

@@ -1,103 +0,0 @@
-/**
- * Shared formatter infrastructure for CLI output modes.
- *
- * Every command must support three output modes: plain (terminal),
- * llm (condensed Markdown), and json (structured). The `Formatters<T>`
- * type enforces this contract. `selectFormatter` eliminates the
- * duplicated if/else dispatch in every command's execute function.
- */
-
-import type { CommandContext } from "@canonical/cli-core";
-import type { LookupResult } from "./contracts.js";
-
-/**
- * The three output modes every command must support.
- *
- * Each formatter is a pure function from data to string.
- */
-export interface Formatters<T> {
-  readonly plain: (data: T) => string;
-  readonly llm: (data: T) => string;
-  readonly json: (data: T) => string;
-}
-
-interface RenderLookupResultsOptions<TResult, TInput> {
-  readonly ctx: CommandContext;
-  readonly result: LookupResult<TResult>;
-  readonly formatters: Formatters<TInput>;
-  readonly mapResult: (item: TResult) => TInput;
-}
-
-/**
- * Pick the right formatter based on global flags.
- *
- * Precedence: `--format json` > `--llm` > plain.
- */
-export function selectFormatter<T>(
-  ctx: CommandContext,
-  formatters: Formatters<T>,
-): (data: T) => string {
-  if (ctx.globalFlags.format === "json") return formatters.json;
-  if (ctx.globalFlags.llm) return formatters.llm;
-  return formatters.plain;
-}
-
-export function renderLookupResults<TResult, TInput>(
-  options: RenderLookupResultsOptions<TResult, TInput>,
-): string {
-  const { ctx, result, formatters, mapResult } = options;
-  const formatOne = selectFormatter(ctx, formatters);
-
-  if (ctx.globalFlags.format === "json") {
-    if (result.results.length === 1 && result.errors.length === 0) {
-      const only = result.results[0];
-      return only
-        ? formatters.json(mapResult(only))
-        : JSON.stringify({ results: [], errors: result.errors }, null, 2);
-    }
-
-    return JSON.stringify(
-      {
-        results: result.results.map((item) =>
-          JSON.parse(formatters.json(mapResult(item))),
-        ),
-        errors: result.errors,
-      },
-      null,
-      2,
-    );
-  }
-
-  const parts = result.results.map((item) => formatOne(mapResult(item)));
-  if (result.errors.length > 0) {
-    const heading = ctx.globalFlags.llm ? "**Errors:**" : "Errors:";
-    parts.push(
-      [
-        heading,
-        ...result.errors.flatMap((error) => formatErrorLines(error)),
-      ].join("\n"),
-    );
-  }
-
-  return parts.join("\n\n");
-}
-
-/**
- * Render one lookup error as display lines: the query and message, plus any
- * fuzzy-match suggestions carried on the error (which the JSON mode surfaces
- * but the text modes previously dropped).
- *
- * @param error - A single lookup error entry.
- * @returns One or more display lines for this error.
- */
-function formatErrorLines(error: {
-  query: string;
-  message: string;
-  suggestions?: readonly string[];
-}): string[] {
-  const lines = [`- ${error.query}: ${error.message}`];
-  if (error.suggestions && error.suggestions.length > 0) {
-    lines.push(`  Did you mean: ${error.suggestions.join(", ")}?`);
-  }
-  return lines;
-}

package/src/domains/shared/listTiers.ts

@@ -1,40 +0,0 @@
-/**
- * List the tiers defined in the loaded ontology, ordered by name.
- *
- * Shared operation: the `tier list` CLI/MCP surface is served by the bundled
- * `tier` story pack, but `config tier` validation still needs the tier set
- * programmatically, and this stays part of the package's public API. Kept in
- * the shared layer so it has no dependency on any DS-specific domain module.
- *
- * @param store - ke store to query.
- * @returns Array of tier entries, empty when none exist.
- * @note Impure — queries the ke store.
- */
-
-import type { Store, URI } from "@canonical/ke";
-import { buildQuery } from "./buildQuery.js";
-import { P } from "./prefixes.js";
-import type { TierEntry } from "./types/index.js";
-
-export async function listTiers(store: Store): Promise<TierEntry[]> {
-  const result = await store.query(
-    buildQuery(`
-      SELECT ?tier ?name
-      WHERE {
-        ?tier a ${P.ds}Tier ;
-              ${P.ds}name ?name .
-      }
-      ORDER BY ?name
-    `),
-  );
-
-  if (result.type !== "select") return [];
-
-  return result.bindings.map((b) => ({
-    uri: (b.tier ?? "") as URI,
-    path: b.name ?? "",
-    depth: 0,
-  }));
-}
-
-export default listTiers;