@canonical/pragma-cli 0.38.0 → 0.40.0

package/src/capabilities/capabilities/hints.ts

@@ -1,266 +0,0 @@
-/**
- * The one authored input to the `capabilities` catalog: a `use_when` behavioural
- * hint + category per tool. Everything else (the tool SET, counts, discovery
- * samples) is DERIVED from the live grammar at build time, so this table is the
- * only thing to keep in sync — and the drift-guard test (`capabilities.test.ts`)
- * fails CI if a live tool has no hint, a hint names a tool that no longer
- * exists, or a hint's category disagrees with the tool's real `mutates` flag.
- *
- * `use_when` strings for the surviving tools are ported verbatim from the old
- * shell's `domains/llm/data/toolCatalog.ts`; the net-new v2 tools (config_set,
- * graph_query, setup, upgrade, doctor, capabilities, prompt_*, sources_*,
- * tier_lookup, create_*) are authored here.
- */
-
-import { BIN_NAME } from "../../constants.js";
-import type { ToolHint } from "./types.js";
-
-/**
- * Behavioural hints keyed by the LIVE tool name (`emitSurface` naming rule:
- * `noun` or `noun_verb`). Categories: `write` ⟺ the verb mutates; `orientation`
- * = the session-start map; `diagnostic` = environment/version reporting; else
- * `read`. The drift guard enforces every one of those invariants.
- */
-export const TOOL_HINTS: Record<string, ToolHint> = {
-  // — Orientation ————————————————————————————————————————————————————————————
-  capabilities: {
-    category: "orientation",
-    use_when:
-      "Starting a session — understand conventions, available tools, and the discovery flow",
-  },
-
-  // — Diagnostic ————————————————————————————————————————————————————————————
-  doctor: {
-    category: "diagnostic",
-    use_when:
-      "Diagnosing environment issues — config, store, completions, MCP health",
-  },
-  info: {
-    category: "diagnostic",
-    use_when: `Checking ${BIN_NAME} version, configuration summary, and store state`,
-  },
-
-  // — Read ——————————————————————————————————————————————————————————————————
-  block_list: {
-    category: "read",
-    use_when:
-      "Browsing all components, patterns, layouts, and subcomponents in the store",
-  },
-  block_lookup: {
-    category: "read",
-    use_when:
-      "Need full anatomy, modifiers, tokens, and standards for specific blocks by name or IRI",
-  },
-  block_sample: {
-    category: "read",
-    use_when:
-      "See actual block data shapes before querying — returns random instances each call, prevents guessing at property names",
-  },
-  colophon: {
-    category: "read",
-    use_when:
-      "Understanding how the active domain is built — its declared colophon, for onboarding or a demo",
-  },
-  config_get: {
-    category: "read",
-    use_when:
-      "Reading ONE config field's effective value and the layer it came from — the single-value form of config_show",
-  },
-  config_show: {
-    category: "read",
-    use_when:
-      "Checking the active configuration (tier, channel, detail) and which layer set each field",
-  },
-  graph_connect: {
-    category: "read",
-    use_when:
-      "Deciding whether two entities are related at all — the shortest relation paths between them, or which kind of nothing there is",
-  },
-  graph_inspect: {
-    category: "read",
-    use_when:
-      "Examining all triples for a specific URI — predicates, objects, and types",
-  },
-  graph_query: {
-    category: "read",
-    use_when:
-      "Complex SPARQL joins or aggregations that other tools cannot express",
-  },
-  modifier_list: {
-    category: "read",
-    use_when: "Listing all modifier families and their allowed values",
-  },
-  modifier_lookup: {
-    category: "read",
-    use_when:
-      "Need values and usage details for specific modifier families by name",
-  },
-  modifier_sample: {
-    category: "read",
-    use_when:
-      "See actual modifier data shapes (with value lists) before querying — returns random instances each call",
-  },
-  ontology_list: {
-    category: "read",
-    use_when:
-      "Discovering loaded namespaces, prefixes, and class/property counts",
-  },
-  ontology_lookup: {
-    category: "read",
-    use_when:
-      "Exploring the full schema of a namespace by name — classes, properties, and hierarchy",
-  },
-  prompt_list: {
-    category: "read",
-    use_when: "Browsing the workflow prompt templates the active graph offers",
-  },
-  prompt_lookup: {
-    category: "read",
-    use_when:
-      "Fetching a specific workflow prompt template's body and arguments by name",
-  },
-  skill_list: {
-    category: "read",
-    use_when: "Discovering agent skills provided by installed packs",
-  },
-  skill_lookup: {
-    category: "read",
-    use_when:
-      "Loading full SKILL.md instructions for a specific agent skill by name",
-  },
-  sources_status: {
-    category: "read",
-    use_when:
-      "Checking whether the local knowledge-graph pack is built and current",
-  },
-  standard_list: {
-    category: "read",
-    use_when:
-      "Browsing code standards, optionally filtered by category or search term",
-  },
-  standard_lookup: {
-    category: "read",
-    use_when:
-      "Need do/don't code examples for specific coding standards by name or IRI",
-  },
-  standard_categories: {
-    category: "read",
-    use_when: "Discovering which standard categories exist before filtering",
-  },
-  concept_list: {
-    category: "read",
-    use_when:
-      "Browsing long-form design-system concepts (foundations, how-to guides, decision guides)",
-  },
-  concept_lookup: {
-    category: "read",
-    use_when: "Reading a concept's full Markdown documentation by name or IRI",
-  },
-  implementation_list: {
-    category: "read",
-    use_when:
-      "Finding which library implements a block, on which platform, and where its source lives",
-  },
-  implementation_libraries: {
-    category: "read",
-    use_when:
-      "Discovering which implementation libraries exist, and how much of the design system each covers",
-  },
-  standard_sample: {
-    category: "read",
-    use_when:
-      "See actual standard data shapes (with dos/donts) before querying — returns random instances each call",
-  },
-  tier_list: {
-    category: "read",
-    use_when: "Picking the tier to scope a read to (the `tier` parameter)",
-  },
-  tier_lookup: {
-    category: "read",
-    use_when: "Need the blocks scoped to a specific tier by name",
-  },
-  token_list: {
-    category: "read",
-    use_when:
-      "Browsing which token SYMBOLS exist (the logical dotted names), optionally by type or by the symbol a channel provisions",
-  },
-  token_lookup: {
-    category: "read",
-    use_when:
-      "Need one symbol in full — its definitions, the families that may rebind it, and what it resolves to at each position",
-  },
-  token_values: {
-    category: "read",
-    use_when:
-      "Need the value a symbol resolves to at a position, with the chain that produced it or the symbol it derives from",
-  },
-  token_consumers: {
-    category: "read",
-    use_when:
-      "Need which blocks consume a symbol, at which style key, state and rank",
-  },
-  token_sample: {
-    category: "read",
-    use_when:
-      "See actual token symbol data shapes before querying — returns random instances each call",
-  },
-  variable_list: {
-    category: "read",
-    use_when:
-      "Browsing the platform names a stylesheet declares, by platform, symbol, tier, visibility or coordinate — including the 236 that stand for no symbol",
-  },
-  variable_lookup: {
-    category: "read",
-    use_when:
-      "Need one platform variable in full — its symbol, tier, visibility, and every selector and at-rule it is declared under",
-  },
-  variable_chain: {
-    category: "read",
-    use_when:
-      "Need what a variable finally means: the transitive walk to every symbol it reaches",
-  },
-  variable_sample: {
-    category: "read",
-    use_when:
-      "See actual platform variable data shapes before querying — returns random instances each call",
-  },
-
-  // — Write ——————————————————————————————————————————————————————————————————
-  config_set: {
-    category: "write",
-    use_when:
-      "Setting any config field by name — tier, channel, or detail (e.g. `config set tier apps/lxd`)",
-  },
-  config_unset: {
-    category: "write",
-    use_when:
-      'Clearing a config field so the built-in default applies again — no value means "remove", this tool does',
-  },
-  create_component: {
-    category: "write",
-    use_when: "Scaffolding a new component (React, Svelte, or Lit)",
-  },
-  create_package: {
-    category: "write",
-    use_when:
-      "Scaffolding a new npm package with proper monorepo configuration",
-  },
-  create_application: {
-    category: "write",
-    use_when:
-      "Scaffolding a new React application with routing, optional Relay, and either server-side rendering or a client-only SPA",
-  },
-  setup: {
-    category: "write",
-    use_when: `Installing ${BIN_NAME}'s shell completions, MCP config, skills, and LSP into the environment`,
-  },
-  sources_update: {
-    category: "write",
-    use_when:
-      "Building or refreshing the knowledge-graph pack from the configured packs",
-  },
-  upgrade: {
-    category: "write",
-    use_when: `Upgrading the ${BIN_NAME} CLI itself to the latest release`,
-  },
-};