@canonical/pragma-cli 0.30.0 → 0.32.0

package/src/domains/info/operations/collectInfo.ts

@@ -1,94 +0,0 @@
-import { readConfigLayers } from "#config";
-import { VERSION } from "#constants";
-import { detectInstallSource, PM_COMMANDS } from "#package-manager";
-import type {
-  PackageRef,
-  RawPackageEntry,
-} from "../../refs/operations/parseRef.js";
-import { bootStore } from "../../shared/bootStore.js";
-import { CHANNEL_RELEASES } from "../../shared/filters/buildChannelFilter.js";
-import { resolveTierChain } from "../../shared/filters/buildTierFilter.js";
-import { mergeAndParseRefs } from "../../shared/mergeAndParseRefs.js";
-import type { InfoData, PackageRefSummary } from "../types.js";
-import checkRegistryVersion from "./checkRegistryVersion.js";
-import { collectStoreSummary } from "./collectStoreSummary.js";
-
-/**
- * Collects all data for the `pragma info` command.
- *
- * Reads local config, detects the package manager, checks the npm registry
- * for updates, boots a ke store, and gathers store summary statistics.
- *
- * @note Impure
- *
- * @param cwd - The current working directory used to locate `pragma.config.json`.
- * @returns A fully populated {@link InfoData} object.
- */
-export default async function collectInfo(cwd: string): Promise<InfoData> {
-  const install = detectInstallSource();
-  const pm = install.packageManager;
-  const layers = readConfigLayers(cwd);
-  const config = layers.config;
-  const tierChain = resolveTierChain(config.tier);
-  const channelReleases = CHANNEL_RELEASES[config.channel];
-
-  const registryResult = await checkRegistryVersion(
-    "@canonical/pragma-cli",
-    config.channel,
-  );
-
-  let update: InfoData["update"];
-  const updateSkipped = registryResult === undefined;
-  if (registryResult && registryResult.latest !== VERSION) {
-    update = {
-      current: VERSION,
-      latest: registryResult.latest,
-      command: PM_COMMANDS[pm].update("@canonical/pragma-cli"),
-    };
-  }
-
-  let store: InfoData["store"];
-  let bootResult: Awaited<ReturnType<typeof bootStore>> | undefined;
-  try {
-    bootResult = await bootStore({ cwd });
-    store = await collectStoreSummary(bootResult.store);
-  } catch {
-    // Store unavailable — show info without store section
-  } finally {
-    bootResult?.store.dispose();
-  }
-
-  // Collect package ref summaries
-  const packageRefs = collectPackageRefSummaries(config.packages);
-
-  return {
-    version: VERSION,
-    pm,
-    installSource: install.label,
-    configPath: layers.project.exists
-      ? layers.project.path
-      : layers.global.path,
-    tier: config.tier,
-    tierChain,
-    channel: config.channel,
-    channelReleases: [...channelReleases],
-    update,
-    updateSkipped,
-    store,
-    packageRefs,
-  };
-}
-
-function collectPackageRefSummaries(
-  configPackages?: ReadonlyArray<RawPackageEntry>,
-): PackageRefSummary[] {
-  return mergeAndParseRefs(configPackages).map(refToSummary);
-}
-
-function refToSummary(ref: PackageRef): PackageRefSummary {
-  if (ref.kind === "file")
-    return { pkg: ref.pkg, source: "file", detail: ref.path };
-  if (ref.kind === "git")
-    return { pkg: ref.pkg, source: "git", detail: `${ref.url}#${ref.ref}` };
-  return { pkg: ref.pkg, source: "npm", detail: "node_modules" };
-}

package/src/domains/info/operations/collectStoreSummary.test.ts

@@ -1,61 +0,0 @@
-import type { Store } from "@canonical/ke";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { createTestStore, DS_ONTOLOGY_TTL, DS_TIERS_TTL } from "#testing";
-import { collectStoreSummary } from "./collectStoreSummary.js";
-
-describe("collectStoreSummary", () => {
-  describe("with default graph only", () => {
-    let store: Store;
-    let cleanup: () => void;
-
-    beforeAll(async () => {
-      const result = await createTestStore({
-        ttl: [DS_ONTOLOGY_TTL, DS_TIERS_TTL].join("\n"),
-      });
-      store = result.store;
-      cleanup = result.cleanup;
-    });
-
-    afterAll(() => {
-      cleanup();
-    });
-
-    it("returns a positive triple count", async () => {
-      const summary = await collectStoreSummary(store);
-      expect(summary.tripleCount).toBeGreaterThan(0);
-    });
-
-    it("returns empty graph names when no named graphs", async () => {
-      const summary = await collectStoreSummary(store);
-      expect(summary.graphNames).toEqual([]);
-    });
-  });
-
-  describe("with named graphs", () => {
-    let store: Store;
-    let cleanup: () => void;
-
-    beforeAll(async () => {
-      const result = await createTestStore({
-        ttl: DS_ONTOLOGY_TTL,
-        graphs: [{ graph: "urn:test:tiers", ttl: DS_TIERS_TTL }],
-      });
-      store = result.store;
-      cleanup = result.cleanup;
-    });
-
-    afterAll(() => {
-      cleanup();
-    });
-
-    it("returns triple count including named graphs", async () => {
-      const summary = await collectStoreSummary(store);
-      expect(summary.tripleCount).toBeGreaterThan(0);
-    });
-
-    it("lists named graph URIs", async () => {
-      const summary = await collectStoreSummary(store);
-      expect(summary.graphNames).toContain("urn:test:tiers");
-    });
-  });
-});

package/src/domains/info/operations/collectStoreSummary.ts

@@ -1,42 +0,0 @@
-import type { Store } from "@canonical/ke";
-import { buildQuery } from "../../shared/buildQuery.js";
-import type { StoreSummary } from "../types.js";
-
-/**
- * Queries the ke store for total triple count and named graph URIs.
- *
- * @note Queries ke store
- *
- * @param store - The ke store to query.
- * @returns A {@link StoreSummary} with `tripleCount` and `graphNames`.
- */
-async function collectStoreSummary(store: Store): Promise<StoreSummary> {
-  const countResult = await store.query(
-    buildQuery("SELECT (COUNT(*) AS ?count) WHERE { ?s ?p ?o }"),
-  );
-
-  let tripleCount = 0;
-  if (countResult.type === "select") {
-    const first = countResult.bindings[0];
-    if (first) {
-      tripleCount = Number.parseInt(first.count ?? "0", 10) || 0;
-    }
-  }
-
-  const graphResult = await store.query(
-    buildQuery(
-      "SELECT DISTINCT ?g WHERE { GRAPH ?g { ?s ?p ?o } } ORDER BY ?g",
-    ),
-  );
-
-  const graphNames: string[] = [];
-  if (graphResult.type === "select") {
-    for (const binding of graphResult.bindings) {
-      if (binding.g) graphNames.push(binding.g);
-    }
-  }
-
-  return { tripleCount, graphNames };
-}
-
-export { collectStoreSummary };

package/src/domains/info/operations/index.ts

@@ -1,5 +0,0 @@
-/** @module Barrel for info operations. */
-
-export { default as checkRegistryVersion } from "./checkRegistryVersion.js";
-export { default as collectInfo } from "./collectInfo.js";
-export { collectStoreSummary } from "./collectStoreSummary.js";

package/src/domains/info/types.test-d.ts

@@ -1,35 +0,0 @@
-/**
- * Compile-time type tests for info + upgrade domain types.
- *
- * Checked by `tsc --noEmit`, not executed at runtime.
- */
-
-import { expectTypeOf } from "expect-type";
-import type {
-  InfoData,
-  RegistryCheckResult,
-  StoreSummary,
-  UpgradeData,
-} from "./types.js";
-
-// InfoData
-expectTypeOf<InfoData["version"]>().toBeString();
-expectTypeOf<InfoData["pm"]>().toBeString();
-expectTypeOf<InfoData["tier"]>().toEqualTypeOf<string | undefined>();
-expectTypeOf<InfoData["tierChain"]>().toEqualTypeOf<readonly string[]>();
-expectTypeOf<InfoData["updateSkipped"]>().toBeBoolean();
-
-// UpgradeData
-expectTypeOf<UpgradeData["current"]>().toBeString();
-expectTypeOf<UpgradeData["latest"]>().toEqualTypeOf<string | undefined>();
-expectTypeOf<UpgradeData["dryRun"]>().toBeBoolean();
-expectTypeOf<UpgradeData["offline"]>().toBeBoolean();
-expectTypeOf<UpgradeData["executed"]>().toBeBoolean();
-
-// RegistryCheckResult
-expectTypeOf<RegistryCheckResult["latest"]>().toBeString();
-expectTypeOf<RegistryCheckResult["distTag"]>().toBeString();
-
-// StoreSummary
-expectTypeOf<StoreSummary["tripleCount"]>().toBeNumber();
-expectTypeOf<StoreSummary["graphNames"]>().toEqualTypeOf<readonly string[]>();

package/src/domains/info/types.ts

@@ -1,54 +0,0 @@
-/** Summary of how a single package is resolved. */
-export interface PackageRefSummary {
-  readonly pkg: string;
-  readonly source: "npm" | "file" | "git";
-  readonly detail: string;
-}
-
-/** Data collected by `pragma info` for rendering. */
-export interface InfoData {
-  readonly version: string;
-  readonly pm: string;
-  readonly installSource: string;
-  readonly configPath: string;
-  readonly tier: string | undefined;
-  readonly tierChain: readonly string[];
-  readonly channel: string;
-  readonly channelReleases: readonly string[];
-  readonly update:
-    | {
-        readonly current: string;
-        readonly latest: string;
-        readonly command: string;
-      }
-    | undefined;
-  readonly updateSkipped: boolean;
-  readonly store:
-    | { readonly tripleCount: number; readonly graphNames: readonly string[] }
-    | undefined;
-  readonly packageRefs?: readonly PackageRefSummary[];
-}
-
-/** Data collected by `pragma upgrade` for rendering. */
-export interface UpgradeData {
-  readonly pm: string;
-  readonly current: string;
-  readonly latest: string | undefined;
-  readonly command: string;
-  readonly dryRun: boolean;
-  readonly alreadyLatest: boolean;
-  readonly offline: boolean;
-  readonly executed: boolean;
-}
-
-/** Result of checking the npm registry for the latest package version. */
-export interface RegistryCheckResult {
-  readonly latest: string;
-  readonly distTag: string;
-}
-
-/** Summary statistics from the ke store (triple count and named graphs). */
-export interface StoreSummary {
-  readonly tripleCount: number;
-  readonly graphNames: readonly string[];
-}

package/src/domains/llm/capabilities.test.ts

@@ -1,91 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { VERSION } from "#constants";
-import { buildCapabilitiesCommand } from "./commands/index.js";
-import { TOOL_CATALOG } from "./data/index.js";
-import { buildCapabilitiesData } from "./mcp/index.js";
-
-describe("buildCapabilitiesData", () => {
-  it("returns correct version", () => {
-    const data = buildCapabilitiesData();
-    expect(data.version).toBe(VERSION);
-  });
-
-  it("includes conventions with three fields", () => {
-    const data = buildCapabilitiesData();
-    expect(data.conventions.system).toBeTruthy();
-    expect(data.conventions.model).toBeTruthy();
-    expect(data.conventions.querying).toBeTruthy();
-  });
-
-  it("includes a 3-stage discovery sequence", () => {
-    const data = buildCapabilitiesData();
-    expect(data.discovery_sequence).toHaveLength(3);
-    expect(data.discovery_sequence[0]?.stage).toBe(1);
-    expect(data.discovery_sequence[0]?.tool).toBe("capabilities");
-    expect(data.discovery_sequence[1]?.tool).toBe("*_sample");
-    expect(data.discovery_sequence[2]?.tool).toBe("domain tools");
-  });
-
-  it("includes every tool from TOOL_CATALOG", () => {
-    const data = buildCapabilitiesData();
-    expect(data.tools).toHaveLength(TOOL_CATALOG.length);
-    expect(data.tools).toHaveLength(30);
-  });
-
-  it("every tool has a non-empty use_when", () => {
-    const data = buildCapabilitiesData();
-    for (const tool of data.tools) {
-      expect(tool.use_when.length).toBeGreaterThan(0);
-    }
-  });
-
-  it("counts match tool catalog category lengths", () => {
-    const data = buildCapabilitiesData();
-    expect(data.counts.total).toBe(30);
-    expect(data.counts.read).toBe(
-      TOOL_CATALOG.filter((t) => t.category === "read").length,
-    );
-    expect(data.counts.write).toBe(
-      TOOL_CATALOG.filter((t) => t.category === "write").length,
-    );
-    expect(data.counts.orientation).toBe(
-      TOOL_CATALOG.filter((t) => t.category === "orientation").length,
-    );
-    expect(data.counts.diagnostic).toBe(
-      TOOL_CATALOG.filter((t) => t.category === "diagnostic").length,
-    );
-  });
-
-  it("includes limits section", () => {
-    const data = buildCapabilitiesData();
-    expect(data.limits.output_modes).toContain("text");
-    expect(data.limits.output_modes).toContain("json");
-    expect(data.limits.output_modes).toContain("llm");
-    expect(data.limits.condensed_available).toBe(true);
-  });
-});
-
-describe("buildCapabilitiesCommand", () => {
-  it("returns an output result with plain renderer", async () => {
-    const cmd = buildCapabilitiesCommand();
-    expect(cmd.path).toEqual(["capabilities"]);
-
-    const result = await cmd.execute({}, {} as never);
-    expect(result.tag).toBe("output");
-    if (result.tag !== "output") throw new Error("Expected output result");
-
-    const text = result.render.plain(result.value) as string;
-    expect(text).toContain("Conventions");
-    expect(text).toContain("Discovery Sequence");
-    expect(text).toContain("block_list");
-    expect(text).toContain("read");
-    expect(text).toContain("30 tools");
-  });
-
-  it("does not require a store or runtime", async () => {
-    const cmd = buildCapabilitiesCommand();
-    // Execute with no context — should succeed because it's static
-    const result = await cmd.execute({}, {} as never);
-    expect(result.tag).toBe("output");
-  });
-});

package/src/domains/llm/commands/capabilities.ts

@@ -1,28 +0,0 @@
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import renderCapabilities from "../formatters/capabilities.js";
-import { buildCapabilitiesData } from "../mcp/specs.js";
-
-/**
- * Builds the `pragma capabilities` command definition.
- *
- * Returns a static system map: conventions, tool catalog with behavioral
- * hints, discovery sequence, and output modes. No store needed.
- *
- * @returns A command definition for `capabilities`.
- */
-export default function buildCapabilitiesCommand(): CommandDefinition {
-  return {
-    path: ["capabilities"],
-    description:
-      "Discover conventions, available tools, and discovery sequence",
-    parameters: [],
-    execute: async (): Promise<CommandResult> => {
-      const data = buildCapabilitiesData();
-      return createOutputResult(data, { plain: renderCapabilities });
-    },
-  };
-}

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

@@ -1,4 +0,0 @@
-/** @module Barrel for llm command builders. */
-
-export { default as buildCapabilitiesCommand } from "./capabilities.js";
-export { default as buildLlmCommand } from "./llm.js";

package/src/domains/llm/commands/llm.ts

@@ -1,37 +0,0 @@
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import type { PragmaContext } from "../../shared/context.js";
-import { COMMAND_REFERENCE, DECISION_TREES } from "../data/index.js";
-import renderLlmOrientation from "../formatters/orientation.js";
-import collectContext from "../operations/collectContext.js";
-import type { LlmData } from "../types.js";
-
-/**
- * Builds the `pragma llm` command definition.
- *
- * Produces an LLM orientation document containing live context (entity counts,
- * tier/channel), static decision trees, and a command reference table.
- *
- * @param ctx - Pragma runtime context providing the ke store and config.
- * @returns A command definition for `llm`.
- */
-export default function buildLlmCommand(ctx: PragmaContext): CommandDefinition {
-  return {
-    path: ["llm"],
-    description:
-      "LLM orientation — context, decision trees, and command reference",
-    parameters: [],
-    execute: async (): Promise<CommandResult> => {
-      const context = await collectContext(ctx.store, ctx.config);
-      const data: LlmData = {
-        context,
-        decisionTrees: DECISION_TREES,
-        commandReference: COMMAND_REFERENCE,
-      };
-      return createOutputResult(data, { plain: renderLlmOrientation });
-    },
-  };
-}

package/src/domains/llm/data/commandReference.ts

@@ -1,97 +0,0 @@
-import type { CommandRefEntry } from "../types.js";
-import { TOOL_CATALOG } from "./toolCatalog.js";
-
-/** Look up a use_when string from the tool catalog by MCP tool name. */
-function hintFor(mcpName: string): string {
-  return TOOL_CATALOG.find((t) => t.name === mcpName)?.use_when ?? "";
-}
-
-/**
- * Static command reference table with approximate token-cost estimates
- * and behavioral hints for LLM tool selection.
- *
- * Used by the `pragma llm` orientation output to help LLMs budget context
- * and choose the right tool.
- */
-export const COMMAND_REFERENCE: readonly CommandRefEntry[] = [
-  {
-    command: "block sample",
-    tokens: "~600",
-    use_when: hintFor("block_sample"),
-  },
-  { command: "block list", tokens: "~200", use_when: hintFor("block_list") },
-  {
-    command: "block lookup <name-or-iri...> --detailed",
-    tokens: "~500",
-    use_when: hintFor("block_lookup"),
-  },
-  {
-    command: "standard sample",
-    tokens: "~500",
-    use_when: hintFor("standard_sample"),
-  },
-  {
-    command: "standard list --category <cat>",
-    tokens: "~100",
-    use_when: hintFor("standard_list"),
-  },
-  {
-    command: "standard lookup <name-or-iri...> --detailed",
-    tokens: "~400",
-    use_when: hintFor("standard_lookup"),
-  },
-  {
-    command: "standard categories",
-    tokens: "~50",
-    use_when: hintFor("standard_categories"),
-  },
-  {
-    command: "modifier sample",
-    tokens: "~200",
-    use_when: hintFor("modifier_sample"),
-  },
-  {
-    command: "modifier list",
-    tokens: "~100",
-    use_when: hintFor("modifier_list"),
-  },
-  {
-    command: "modifier lookup <name-or-iri...>",
-    tokens: "~80",
-    use_when: hintFor("modifier_lookup"),
-  },
-  {
-    command: "token sample",
-    tokens: "~300",
-    use_when: hintFor("token_sample"),
-  },
-  { command: "token list", tokens: "~400", use_when: hintFor("token_list") },
-  {
-    command: "token lookup <name-or-iri...> --detailed",
-    tokens: "~150",
-    use_when: hintFor("token_lookup"),
-  },
-  { command: "tier list", tokens: "~50", use_when: hintFor("tier_list") },
-  {
-    command: "ontology list",
-    tokens: "~80",
-    use_when: hintFor("ontology_list"),
-  },
-  {
-    command: "ontology show <prefix>",
-    tokens: "~300",
-    use_when: hintFor("ontology_show"),
-  },
-  {
-    command: 'graph query "<sparql>"',
-    tokens: "varies",
-    use_when: hintFor("graph_query"),
-  },
-  {
-    command: "graph inspect <uri>",
-    tokens: "~200",
-    use_when: hintFor("graph_inspect"),
-  },
-  { command: "config show", tokens: "~50", use_when: hintFor("config_show") },
-  { command: "info", tokens: "~100", use_when: hintFor("info") },
-];

package/src/domains/llm/data/decisionTrees.ts

@@ -1,50 +0,0 @@
-import type { DecisionTree } from "../types.js";
-
-/**
- * Static decision trees guiding LLMs through common pragma workflows.
- *
- * Each tree maps an intent (e.g. "Build a block") to a compact ASCII
- * flowchart with token-cost annotations.
- */
-export const DECISION_TREES: readonly DecisionTree[] = [
-  {
-    intent: "Build a block",
-    tree: `? First time seeing block data?
-  yes → block sample [~600] → see actual shapes, then query
-  no  → ? Know IRI or name?
-    yes → block lookup <name-or-iri...> --detailed  [~500]
-          e.g. block lookup ds:global.component.button
-    no  → block list [~200] → pick compact IRI → lookup`,
-  },
-  {
-    intent: "Audit standards",
-    tree: `? First time seeing standard data?
-  yes → standard sample [~500] → see actual shapes, then query
-  no  → ? Know standard IRI or name?
-    yes → standard lookup <name-or-iri...> --detailed [~400]
-          e.g. standard lookup react/component/props
-    no  → standard list --category <cat> [~100]
-          → standard lookup <std-iri...> --detailed [~400] Σ500`,
-  },
-  {
-    intent: "Find a token",
-    tree: `? Know token IRI or name?
-  yes → token lookup <name-or-iri...> --detailed [~150]
-  no  → token list --category <cat> [~100]
-        → token lookup <name-or-iri...> --detailed [~150] Σ250`,
-  },
-  {
-    intent: "Explore the design system",
-    tree: `first time → block sample / token sample / modifier sample [~300] → see real shapes
-high-level → ontology list [~80] → ontology show <ns> [~300]
-modifiers  → modifier list [~100] → modifier lookup <name-or-iri...> [~80]
-tiers      → tier list [~50]
-raw        → graph query "SELECT ..." → graph inspect <uri> [~200]`,
-  },
-  {
-    intent: "Configure",
-    tree: `tier    → config tier <path> → config show [~50]
-channel → config channel <value> (normal|experimental|prerelease)
-status  → info [~100]`,
-  },
-];

package/src/domains/llm/data/index.ts

@@ -1,6 +0,0 @@
-/** @module Barrel for llm static data. */
-
-export { COMMAND_REFERENCE } from "./commandReference.js";
-export { DECISION_TREES } from "./decisionTrees.js";
-export type { ToolEntry } from "./toolCatalog.js";
-export { TOOL_CATALOG } from "./toolCatalog.js";