@canonical/pragma-cli 0.30.0 → 0.32.0

package/src/capabilities/upgrade/upgrade.verb.ts

@@ -0,0 +1,56 @@
+/**
+ * The `upgrade` verb spec (noun `upgrade`, self-verb).
+ *
+ * A storeless, network-touching mutation: check the registry, then run the
+ * package-manager update. `destructive: false` is load-bearing (D4) — upgrading
+ * replaces the binary, it destroys no user data — so `annotationsFor` emits
+ * `destructiveHint: false` rather than letting MCP clients default an unset hint
+ * on a non-read-only tool to `true`.
+ *
+ * `run` returns `Promise<Task<UpgradeData>>` (async registry read before the
+ * effects are known) presented through the `Task<R>` arm by the honest cast —
+ * the `update.verb.ts` precedent; a literal `Promise<Task>` union arm would
+ * poison async read-verb inference.
+ */
+
+import type { Task } from "@canonical/task";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import type { UpgradeData } from "./types.js";
+import { upgradeFormatters } from "./upgrade.render.js";
+
+const upgradeVerb: VerbSpec<Record<string, unknown>, UpgradeData> = {
+  path: ["upgrade"],
+  summary: "Upgrade the pragma CLI to the latest version.",
+  doc: "Checks the registry for the active channel's latest release and runs your package manager's global-update command. Preview the update before applying it.",
+  params: [],
+  output: { formatters: upgradeFormatters },
+  examples: [
+    { cmd: "pragma upgrade" },
+    { cmd: "pragma upgrade --dry-run", note: "show the delta and the command" },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: true,
+    destructive: false,
+    needsNetwork: true,
+    mcp: {
+      expose: true,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: false,
+      },
+    },
+  },
+  run: (_params, runtime) =>
+    import("./runUpgrade.js").then((m) =>
+      m.runUpgrade(runtime),
+    ) as unknown as Task<UpgradeData>,
+};
+
+/** The `upgrade` capability module. */
+export const upgradeModule: CapabilityModule = {
+  name: "upgrade",
+  verbs: [asVerb(upgradeVerb)],
+};

package/src/constants.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import {
+  BIN_NAME,
+  DEFAULT_DETAIL_LEVEL,
+  DETAIL_LEVELS,
+  MCP_SERVER_NAME,
+  OUTPUT_FORMATS,
+  PROGRAM_DESCRIPTION,
+  RECOVERY_CLI_PREFIX,
+  VERSION,
+} from "./constants.js";
+
+describe("constants", () => {
+  it("names the v2 bin and the MCP server pragma", () => {
+    expect(BIN_NAME).toBe("pragma");
+    expect(MCP_SERVER_NAME).toBe("pragma");
+  });
+
+  it("reads a semver version from package.json", () => {
+    expect(VERSION).toMatch(/^\d+\.\d+\.\d+/);
+  });
+
+  it("keeps the recovery prefix on the stable command name (D5)", () => {
+    expect(RECOVERY_CLI_PREFIX).toBe("pragma ");
+  });
+
+  it("exposes the stable output formats and detail levels", () => {
+    expect(OUTPUT_FORMATS).toEqual(["plain", "json"]);
+    expect(DETAIL_LEVELS).toEqual(["summary", "standard", "detailed"]);
+    expect(DETAIL_LEVELS).toContain(DEFAULT_DETAIL_LEVEL);
+    expect(PROGRAM_DESCRIPTION.length).toBeGreaterThan(0);
+  });
+});

package/src/constants.ts

@@ -1,89 +1,59 @@
 /**
- * Package-level constants for the pragma CLI.
+ * Package-level constants for the pragma v2 kernel.
  *
- * Groups program metadata (name, version, description), release channel
- * definitions, and the cross-ontology property resolution map shared
- * by MCP resources and domain operations.
+ * Program metadata (bin name, MCP server name, description, version) plus the
+ * stable cross-cutting enums (output formats, detail levels). The CLI binary
+ * and the MCP server share the single `pragma` identity, so existing agent
+ * wiring keeps resolving the server unchanged.
  */
 
 import pkg from "../package.json" with { type: "json" };
-import { PREFIX_MAP } from "./domains/shared/prefixes.js";
 
-/** CLI program name used in help text and error messages. */
-const PROGRAM_NAME = "pragma";
+/** CLI binary name for the v2 kernel (installed as `pragma`). */
+const BIN_NAME = "pragma";
 
-/** One-line program description for help text. */
+/**
+ * MCP server identity — `pragma`, matching the CLI bin, so agents already
+ * pointed at the pragma server resolve it unchanged.
+ */
+const MCP_SERVER_NAME = "pragma";
+
+/** One-line program description for help and server metadata. */
 const PROGRAM_DESCRIPTION = "CLI and MCP server for Canonical's design system.";
 
 /** Semver version string read from package.json. */
-const VERSION = pkg.version;
+const VERSION: string = pkg.version;
 
-/** Allowed release channel values for the `channel` config field. */
-const VALID_CHANNELS = ["normal", "experimental", "prerelease"] as const;
+/**
+ * Literal prefix for every `recovery.cli` hint (`pragma `): recovery strings
+ * quote the stable, documented command name — matching the bin (D5). The
+ * recovery invariant test enforces this.
+ */
+const RECOVERY_CLI_PREFIX = "pragma ";
 
-/** A release channel name. */
-type Channel = (typeof VALID_CHANNELS)[number];
+/** The two machine/human output formats the renderer selects between. */
+const OUTPUT_FORMATS = ["plain", "json"] as const;
 
-/** Allowed values for the `framework` config field. */
-const VALID_FRAMEWORKS = ["react", "svelte", "lit"] as const;
+/** A selected output format. `--format text` is normalised to `plain`. */
+type OutputFormat = (typeof OUTPUT_FORMATS)[number];
 
-/**
- * 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];
+/** Progressive-disclosure levels, least to most detail. */
+const DETAIL_LEVELS = ["summary", "standard", "detailed"] as const;
 
-/**
- * Per-namespace property URIs for semantically equivalent fields.
- * Each ontology uses different property names for the same concept
- * (name/label, description/summary/comment).
- */
-interface OntologyPropertyMap {
-  readonly label: string;
-  readonly description?: string;
-  readonly definition?: string;
-}
+/** A progressive-disclosure level. */
+type DetailLevel = (typeof DETAIL_LEVELS)[number];
 
-/**
- * Maps namespace prefix → property URIs for human-readable label and
- * description. Used by MCP resource handlers and domain operations to
- * resolve cross-ontology properties uniformly.
- */
-const PROPERTY_MAP: Record<string, OntologyPropertyMap> = {
-  ds: {
-    label: `${PREFIX_MAP.ds}name`,
-    description: `${PREFIX_MAP.ds}summary`,
-    definition: `${PREFIX_MAP.ds}definition`,
-  },
-  cs: {
-    label: `${PREFIX_MAP.cs}name`,
-    description: `${PREFIX_MAP.cs}description`,
-    definition: `${PREFIX_MAP.cs}definition`,
-  },
-  rdfs: {
-    label: `${PREFIX_MAP.rdfs}label`,
-    description: `${PREFIX_MAP.rdfs}comment`,
-  },
-  owl: {
-    label: `${PREFIX_MAP.rdfs}label`,
-    description: `${PREFIX_MAP.rdfs}comment`,
-  },
-  skos: {
-    label: `${PREFIX_MAP.skos}prefLabel`,
-    definition: `${PREFIX_MAP.skos}definition`,
-  },
-  anatomy: {
-    label: `${PREFIX_MAP.ds}name`,
-  },
-};
+/** Default detail level when neither flag, config, nor spec pins one. */
+const DEFAULT_DETAIL_LEVEL: DetailLevel = "standard";
 
-export type { Channel, Framework, OntologyPropertyMap };
+export type { DetailLevel, OutputFormat };
 export {
+  BIN_NAME,
+  DEFAULT_DETAIL_LEVEL,
+  DETAIL_LEVELS,
+  MCP_SERVER_NAME,
+  OUTPUT_FORMATS,
   PROGRAM_DESCRIPTION,
-  PROGRAM_NAME,
-  PROPERTY_MAP,
-  VALID_CHANNELS,
-  VALID_FRAMEWORKS,
+  RECOVERY_CLI_PREFIX,
   VERSION,
 };

package/src/index.ts

@@ -1,141 +1,34 @@
 /**
- * Public API surface for `@canonical/pragma-cli`.
+ * Public, types-only API surface for `@canonical/pragma-cli`.
  *
- * Exports types, boot functions, domain operations, and the MCP adapter.
- * Internal formatters, command builders, and infrastructure are not exported.
+ * Per the tool-ts convention this barrel exports types only — no runtime
+ * values cross the package boundary. Consumers (and the surface emitter's
+ * golden) depend on the grammar and cross-cutting shapes, never on internal
+ * command builders, projectors, or infrastructure.
  *
  * @module
  */
 
-// — Config & Error ————————————————————————————————————————————————————————————
-
-export type { PragmaConfig } from "./config/index.js";
-export { readConfig } from "./config/index.js";
-export type { ErrorCode, PragmaErrorData, Recovery } from "./error/index.js";
-export { PragmaError } from "./error/index.js";
-
-// — Runtime ———————————————————————————————————————————————————————————————————
-
-export type { PragmaRuntime } from "./domains/shared/runtime.js";
-export { bootPragma } from "./domains/shared/runtime.js";
-
-// — Shared Types —————————————————————————————————————————————————————————————
-
-export type {
-  ColumnDef,
-  EntityDisplayConfig,
-  ListContract,
-  ListParams,
-  ListResult,
-  LookupContract,
-  LookupParams,
-  LookupResult,
-  MutateContract,
-  SectionDef,
-  SectionKind,
-  ShowContract,
-} from "./domains/shared/contracts.js";
-
-export type {
-  AnatomyNode,
-  AnatomyTree,
-  BatchResult,
-  BlockDetailed,
-  BlockDigest,
-  BlockSummary,
-  CategorySummary,
-  CodeBlock,
-  Disclosure,
-  FilterConfig,
-  InspectResult,
-  ModifierFamily,
-  OntologyClass,
-  OntologyDetailed,
-  OntologyProperty,
-  OntologySummary,
-  PredicateGroup,
-  StandardDetailed,
-  StandardListFilters,
-  StandardRef,
-  StandardSummary,
-  TierEntry,
-  TokenDetailed,
-  TokenRef,
-  TokenSummary,
-} from "./domains/shared/types/index.js";
-
-// — Domain Operations —————————————————————————————————————————————————————————
-
-export {
-  buildBlockFilters,
-  listBlocks,
-  lookupBlock,
-  resolveBlockList,
-  resolveBlockLookup,
-} from "./domains/block/index.js";
-export { runChecks } from "./domains/doctor/operations/index.js";
-export {
-  executeQuery,
-  inspectUri,
-} from "./domains/graph/operations/index.js";
-export {
-  listModifiers,
-  lookupModifier,
-  modifierEmptyError,
-  resolveModifierList,
-  resolveModifierLookup,
-} from "./domains/modifier/index.js";
-export {
-  listOntologies,
-  showOntology,
-  showOntologyRaw,
-} from "./domains/ontology/operations/index.js";
-export {
-  discoverSkills,
-  listSkills,
-} from "./domains/skill/operations/index.js";
-export {
-  listCategories,
-  listStandards,
-  lookupStandard,
-  resolveStandardList,
-  resolveStandardLookup,
-} from "./domains/standard/index.js";
-export { listTiers } from "./domains/tier/operations/index.js";
-export {
-  listTokens,
-  lookupToken,
-  resolveTokenList,
-  resolveTokenLookup,
-  tokenEmptyError,
-} from "./domains/token/index.js";
-
-// — Domain Types ——————————————————————————————————————————————————————————————
-
-export type { ConfigShowData } from "./domains/config/operations/index.js";
 export type {
-  CheckContext,
-  CheckResult,
-  DoctorData,
-} from "./domains/doctor/operations/index.js";
-export type {
-  InfoData,
-  RegistryCheckResult,
-  StoreSummary,
-  UpgradeData,
-} from "./domains/info/types.js";
-export type { SkillListResult } from "./domains/skill/operations/index.js";
-export type {
-  DiscoveredSkill,
-  SkillFrontmatter,
-  SkillSource,
-} from "./domains/skill/types.js";
-
-// — MCP Adapter ——————————————————————————————————————————————————————————————
-
-export {
-  createMcpServer,
-  createMcpServerFromRuntime,
-} from "./mcp/index.js";
-export { default as registerAllTools } from "./mcp/tools/index.js";
-export type { McpErrorPayload, McpRecovery } from "./mcp/types.js";
+  Capability,
+  CapabilityModule,
+  Channel,
+  DetailLevel,
+  DisclosureSpec,
+  ErrorCode,
+  ErrorEnvelope,
+  ErrorPayload,
+  Example,
+  Formatters,
+  McpAnnotations,
+  OutputFormat,
+  PackageDeclaration,
+  PackageEntry,
+  ParamComplete,
+  ParamSpec,
+  PragmaConfig,
+  PragmaErrorData,
+  Recovery,
+  SuccessEnvelope,
+  VerbSpec,
+} from "./types.js";