@canonical/pragma-cli 0.35.0 → 0.37.0

package/src/capabilities/doctor/runChecks.ts

@@ -1,13 +1,16 @@
 /**
- * The `doctor` run body: the unbanded environment checks plus the banded rows
+ * The `doctor` run body: the unscoped environment checks plus the scoped rows
  * the setup target table derives.
  *
  * Two kinds of finding live in one report and they are not the same kind. The
  * ENVIRONMENT checks — the Node version, this CLI's own version, pack refs, the
- * store — diagnose things `setup` cannot install; they carry no band and stay
- * their own section. The BANDED rows are exactly the setup targets, in both
- * bands, named with the target ids verbatim and repaired by the target's own
- * command. Adding a target adds its rows here for free.
+ * store — diagnose things `setup` cannot install; they carry no scope and stay
+ * their own section. The SCOPED rows are the setup targets, in both scopes,
+ * named with the target ids verbatim and repaired by the target's own command
+ * — plus, per scope, the `harnesses` inventory row: a listing of what this
+ * machine holds and where pragma stands in it, which is the thing the targets
+ * are measured against rather than a target itself. Adding a target adds its
+ * rows here for free.
  *
  * Checks are started eagerly (they run concurrently) and collected in
  * declaration order for a deterministic report. Each is guarded so a thrown
@@ -22,11 +25,11 @@ import { checkKeStore } from "./checks/checkKeStore.js";
 import { checkNodeVersion } from "./checks/checkNodeVersion.js";
 import { checkPackageRefs } from "./checks/checkPackageRefs.js";
 import { checkPragmaVersion } from "./checks/checkPragmaVersion.js";
-import { bandedChecks } from "./checks/targetHealth.js";
+import { scopedChecks } from "./checks/targetHealth.js";
 import type { CheckResult, DoctorData } from "./types.js";
 
 /**
- * The unbanded environment checks, each paired with the display name used if it
+ * The unscoped environment checks, each paired with the display name used if it
  * rejects. The fallback name matches the `name` each check returns on success,
  * so a thrown check reports the same label and stays correlatable.
  */
@@ -67,16 +70,16 @@ async function guarded(
  * @note Impure — the checks read the fs, boot the store, and detect harnesses.
  */
 export async function runChecks(rt: PragmaRuntime): Promise<DoctorData> {
-  // The banded rows come back as a batch (one detection pass over the table),
+  // The scoped rows come back as a batch (one detection pass over the table),
   // so they are guarded as a batch: a detection that throws becomes one
   // attributable failure instead of taking the environment section with it.
-  const [environmentResults, bandedResults] = await Promise.all([
+  const [environmentResults, scopedResults] = await Promise.all([
     Promise.all(
       buildEnvironmentChecks(rt).map(([name, promise]) =>
         guarded(name, promise),
       ),
     ),
-    bandedChecks(rt, BIN_NAME).catch((error: unknown): CheckResult[] => [
+    scopedChecks(rt, BIN_NAME).catch((error: unknown): CheckResult[] => [
       {
         name: "setup targets",
         status: "fail",
@@ -88,7 +91,7 @@ export async function runChecks(rt: PragmaRuntime): Promise<DoctorData> {
     ]),
   ]);
 
-  const checks: CheckResult[] = [...environmentResults, ...bandedResults];
+  const checks: CheckResult[] = [...environmentResults, ...scopedResults];
   return {
     checks,
     passed: checks.filter((c) => c.status === "pass").length,

package/src/capabilities/doctor/types.ts

@@ -2,26 +2,17 @@
  * Data shapes for `pragma doctor` (ported verbatim from the old shell).
  */
 
-/**
- * One of the two config bands a check can concern. Mirrors the harnesses
- * `ScopeBand` structurally but is redeclared here so this statically-reachable
- * type module never pulls the harnesses runtime into the fast-path module graph.
- */
-export type ScopeBand = "project" | "global";
+// The scope and status types are part of the rendering vocabulary — the one
+// module that owns both the states and the words (and glyphs) for them.
+// Re-exported here so doctor's type surface stays complete; the definitions,
+// the `available` tier's rationale, and the structural pin against
+// `@canonical/harnesses` live with the vocabulary.
+import type { CheckStatus, Scope } from "../../kernel/render/vocabulary.js";
 
-/**
- * Status of a doctor check or one of its sub-items.
- *
- * `available` is the tier between fail and skip that keeps the report honest:
- * an opt-in integration (MCP registration, skills symlinks, a completion
- * script) that is detected and installable but that the user has not set up.
- * Nothing is broken — a fresh install is HEALTHY with several availables — so
- * reporting these as `fail` would teach users that the failure count is noise.
- * `fail` stays reserved for a real fault: something set up that no longer
- * works, or an environment the CLI cannot run correctly in. `skip` remains
- * "nothing to check here" (no shell detected, no harnesses present).
- */
-export type CheckStatus = "pass" | "fail" | "available" | "skip";
+export type {
+  CheckStatus,
+  Scope,
+} from "../../kernel/render/vocabulary.js";
 
 /**
  * A structured sub-item under a check — e.g. one resolved package under
@@ -52,13 +43,13 @@ export interface CheckResult {
    */
   readonly remedy?: string;
   /**
-   * Which config band the check concerns, if any: `global` for the user/home
+   * Which config scope the check concerns, if any: `global` for the user/home
    * level (shell completions), `project` for per-repo config (skills). The MCP
-   * checks derive their band from the harnesses they found. The renderer groups
-   * banded checks into Global/Project sections; environment checks (Node,
-   * versions, store) carry no band.
+   * checks derive their scope from the harnesses they found. The renderer groups
+   * scoped checks into Global/Project sections; environment checks (Node,
+   * versions, store) carry no scope.
    */
-  readonly band?: ScopeBand;
+  readonly scope?: Scope;
 }
 
 /** Aggregated results from all doctor checks — one count per status tier. */

package/src/capabilities/emptyRecovery.test.ts

@@ -35,6 +35,9 @@ function storyFor(noun: string): PackDefinition {
 const PREFIXES = {
   ds: "https://ds.canonical.com/",
   cs: "https://ds.canonical.com/code-standards/",
+  // The `standard` list query names `skos:broader` for its category roll-up —
+  // a CORE prefix on the real build path, which this in-memory helper bypasses.
+  skos: "http://www.w3.org/2004/02/skos/core#",
   owl: "http://www.w3.org/2002/07/owl#",
   rdfs: "http://www.w3.org/2000/01/rdf-schema#",
   xsd: "http://www.w3.org/2001/XMLSchema#",
@@ -85,7 +88,12 @@ const listVerb = (pack: PackDefinition): VerbSpec =>
 const PACK_LISTS: readonly { pack: PackDefinition; hint: RegExp }[] = [
   { pack: storyFor("modifier"), hint: /pragma sources update/ },
   { pack: storyFor("token"), hint: /pragma sources update/ },
-  { pack: storyFor("standard"), hint: /broaden the filter/ },
+  // CHANGED DELIBERATELY. `standard` used to fall through to the generic
+  // build/broaden hint, and the build half of it is actively WRONG for this
+  // noun: the code standards ride the embedded snapshot and answer with no
+  // `sources update` at all. It now authors its own, pointing at the one
+  // surface that reads the category vocabulary out of the graph.
+  { pack: storyFor("standard"), hint: /pragma standard categories/ },
 ];
 
 const REAL = { dryRun: false, undo: false, yes: false };
@@ -108,7 +116,7 @@ describe("pack list empty-state (U5, PROTECTED)", () => {
     const { formatters } = listVerb(pack).output;
     // The message + runnable hint live on the empty-state seam — the
     // dispatcher routes them to stderr, keeping plain stdout pure data.
-    const notice = formatters.emptyNotice?.([]);
+    const notice = formatters.notice?.([]);
     expect(notice).toContain(`No ${pack.noun} entries found.`);
     expect(notice).toMatch(hint);
     // JSON is the uniform empty array — unchanged by the message.

package/src/capabilities/graph/query.render.ts

@@ -37,9 +37,9 @@ function formatTriples(
 
 export const queryFormatters: Formatters<QueryResult> = {
   // Zero rows/triples: plain stdout stays empty — the notice is
-  // `emptyNotice`, routed to stderr (exit 0) by the dispatcher so a pipe
+  // `notice`, routed to stderr (exit 0) by the dispatcher so a pipe
   // reads no prose. ASK always has a result and never goes empty.
-  emptyNotice(result) {
+  notice(result) {
     if (result.type === "select" && result.bindings.length === 0) {
       return "No results.";
     }

package/src/capabilities/info/collectInfo.ts

@@ -26,6 +26,7 @@ import {
   detectInstallSource,
   PRAGMA_PACKAGE,
   pmUpdateCommand,
+  updateGuidance,
 } from "../shared/index.js";
 import type { InfoData, InfoUpdate } from "./types.js";
 
@@ -44,12 +45,17 @@ export async function collectInfo(runtime: PragmaRuntime): Promise<InfoData> {
 
   // Update-check: unconditional (no flag exists), 3s timeout, silent-fail.
   const registry = await checkRegistryVersion(PRAGMA_PACKAGE, config.channel);
+  // Only a GLOBAL install gets a command; every other state gets the honest
+  // guidance sentence — a confidently wrong `npm i -g` against a linked
+  // checkout would overwrite the development link.
   const update: InfoUpdate | undefined =
     registry && registry.latest !== runtime.version
       ? {
           current: runtime.version,
           latest: registry.latest,
-          command: pmUpdateCommand(install.pm, PRAGMA_PACKAGE),
+          ...(install.kind === "global"
+            ? { command: pmUpdateCommand(install, PRAGMA_PACKAGE) }
+            : { guidance: updateGuidance(install) }),
         }
       : undefined;
   const updateSkipped = registry === undefined;
@@ -62,6 +68,7 @@ export async function collectInfo(runtime: PragmaRuntime): Promise<InfoData> {
   return {
     version: runtime.version,
     installSource: install.label,
+    installKind: install.kind,
     ...(update ? { update } : {}),
     updateSkipped,
     ...(entities !== undefined ? { entities } : {}),

package/src/capabilities/info/info.render.ts

@@ -37,7 +37,9 @@ export const infoFormatters: Formatters<InfoData> = {
       lines.push(
         "",
         `Update available: ${data.update.current} → ${data.update.latest}`,
-        `  Run: ${data.update.command}`,
+        data.update.command
+          ? `  Run: ${data.update.command}`
+          : `  ${data.update.guidance}`,
       );
     }
     return lines.join("\n");
@@ -61,7 +63,9 @@ export const infoFormatters: Formatters<InfoData> = {
     }
     if (data.update) {
       lines.push(
-        `- Update available: ${data.update.current} → ${data.update.latest} (\`${data.update.command}\`)`,
+        data.update.command
+          ? `- Update available: ${data.update.current} → ${data.update.latest} (\`${data.update.command}\`)`
+          : `- Update available: ${data.update.current} → ${data.update.latest} — ${data.update.guidance}`,
       );
     }
     return lines.join("\n");

package/src/capabilities/info/info.test.ts

@@ -17,9 +17,26 @@ import { bootRuntime } from "../../kernel/runtime/boot.js";
 import type { GlobalFlags, PragmaRuntime } from "../../kernel/runtime/types.js";
 import type { VerbSpec } from "../../kernel/spec/types.js";
 import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import type { InstallSource } from "../shared/index.js";
 import { infoModule } from "./index.js";
 import type { InfoData } from "./types.js";
 
+// Pin the install-source detection: the real detector reads THIS process
+// (whose entry is a source checkout — an honest `unknown`), and these tests
+// are about the enrichment around it, not the detection itself (covered by
+// `shared/packageManager.test.ts`). The holder lets a case retarget it.
+const detection = vi.hoisted(() => ({ install: undefined as unknown }));
+vi.mock("../shared/index.js", async (importOriginal) => ({
+  ...(await importOriginal<object>()),
+  detectInstallSource: () => detection.install,
+}));
+
+const GLOBAL_NPM: InstallSource = {
+  kind: "global",
+  pm: "npm",
+  label: "npm (global)",
+};
+
 const infoVerb = infoModule.verbs[0] as VerbSpec;
 const FLAGS_JSON: GlobalFlags = {
   llm: false,
@@ -54,6 +71,7 @@ let prevXdg: string | undefined;
 beforeEach(() => {
   prevXdg = process.env.XDG_CONFIG_HOME;
   process.env.XDG_CONFIG_HOME = tmpCwd();
+  detection.install = GLOBAL_NPM;
 });
 afterEach(() => {
   process.env.XDG_CONFIG_HOME = prevXdg;
@@ -74,12 +92,30 @@ describe("info — update-check enrichment", () => {
     const data = await collect(rt);
 
     expect(data.update).toMatchObject({ current: VERSION, latest: "99.0.0" });
-    expect(data.update?.command).toContain("@canonical/pragma-cli");
+    expect(data.update?.command).toBe("npm i -g @canonical/pragma-cli");
+    expect(data.installSource).toBe("npm (global)");
+    expect(data.installKind).toBe("global");
     expect(data.updateSkipped).toBe(false);
     // The storeless invariant: the enrichment must NOT boot the store.
     expect(rt.store.booted).toBe(false);
   });
 
+  it("a LINKED install gets guidance, never a command (would clobber the link)", async () => {
+    detection.install = {
+      kind: "linked",
+      pm: "npm",
+      target: "/home/u/code/pragma/packages/cli/pragma",
+      label: "npm link (development checkout)",
+    } satisfies InstallSource;
+    stubRegistry("99.0.0");
+    const data = await collect(bootRuntime(FLAGS_JSON, tmpCwd()));
+
+    expect(data.installKind).toBe("linked");
+    expect(data.installSource).toBe("npm link (development checkout)");
+    expect(data.update?.command).toBeUndefined();
+    expect(data.update?.guidance).toMatch(/development checkout/i);
+  });
+
   it("marks `updateSkipped` when the registry is unreachable", async () => {
     stubRegistry("offline");
     const data = await collect(bootRuntime(FLAGS_JSON, tmpCwd()));

package/src/capabilities/info/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { ConfigOrigins } from "../../kernel/config/types.js";
+import type { InstallKind } from "../../kernel/render/vocabulary.js";
 
 /** The config summary `info` reports — resolved values plus provenance. */
 export interface InfoConfig {
@@ -20,8 +21,12 @@ export interface InfoConfig {
 export interface InfoUpdate {
   readonly current: string;
   readonly latest: string;
-  /** The package-manager command that would apply the update. */
-  readonly command: string;
+  /** The package-manager command that would apply the update — only for a
+   * GLOBAL install; every other state carries {@link guidance} instead. */
+  readonly command?: string;
+  /** The honest sentence for an install with no sanctioned update command
+   * (linked / ephemeral / workspace / unknown). */
+  readonly guidance?: string;
 }
 
 /**
@@ -31,7 +36,10 @@ export interface InfoUpdate {
  */
 export interface InfoData {
   readonly version: string;
+  /** The install-source display label (e.g. `npm (global)`). */
   readonly installSource: string;
+  /** The install-source state the label renders. */
+  readonly installKind: InstallKind;
   /** Set when a newer CLI release is available on the active channel. */
   readonly update?: InfoUpdate;
   /** True when the registry could not be reached (the update-check was skipped). */

package/src/capabilities/lazy.test.ts

@@ -88,8 +88,9 @@ describe("lazy dispatch — module-graph probe (PROTECTED)", () => {
 
   it("the dispatch path never reaches the embedded n-quads module (PROTECTED)", () => {
     // `activeStories` reads the pack's carried stories from their OWN generated
-    // module rather than through `graphpack/embedded.ts`, which statically
-    // imports the ~1.9 MB `pack.generated.ts`. Restoring that edge costs a
+    // module rather than through `graphpack/embedded.ts`, which reaches the
+    // ~2.1 MB `pack.generated.ts` (dynamically since the manifest split, but
+    // this path must not reach it at all). Restoring that edge costs a
     // measured +23 ms on EVERY dispatched command, and the whole test suite
     // passes with it restored — the split is prose in three docblocks and
     // nothing else. This is the constraint those docblocks describe.
@@ -104,6 +105,29 @@ describe("lazy dispatch — module-graph probe (PROTECTED)", () => {
     }
   });
 
+  it("`embedded.ts` itself never statically imports the payload (PROTECTED)", () => {
+    // The store-boot path DOES go through `graphpack/embedded.ts`, so the test
+    // above cannot cover it. `materializeEmbeddedPack` reads the manifest to
+    // name the cache directory and then returns early when the pack is already
+    // there — the common case — so a static import of `pack.generated.ts` would
+    // parse ~2.1 MB of n-quads to reach that return, on every boot.
+    //
+    // Restoring `import { dataNq } from "./embedded/pack.generated.js"` at
+    // module scope costs a measured ~370 ms per CLI invocation on a
+    // 30,340-triple pack, and every other test still passes. This is the only
+    // thing standing between that edit and a silent regression.
+    for (const entry of [
+      "../kernel/runtime/graphpack/embedded.ts",
+      "../kernel/runtime/loadSession.ts",
+    ]) {
+      const graph = staticImportGraph(resolve(here, entry));
+      expect(has(graph, "embedded/pack.manifest.generated.ts"), entry).toBe(
+        true,
+      );
+      expect(has(graph, "embedded/pack.generated.ts"), entry).toBe(false);
+    }
+  });
+
   it("the help path (buildProgram) imports no zod schema module", () => {
     const graph = staticImportGraph(
       resolve(here, "../kernel/project/cli/buildProgram.ts"),