@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/capabilities/skill/discover.ts

@@ -13,6 +13,7 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
+import { BIN_NAME } from "../../constants.js";
 
 /** Parsed SKILL.md frontmatter. */
 export interface SkillFrontmatter {
@@ -103,26 +104,31 @@ export function parseFrontmatter(content: string): SkillFrontmatter | null {
 }
 
 /**
- * The installed-skills root: `$XDG_DATA_HOME/pragma/skills`. This is where
+ * The installed-skills root: `$XDG_DATA_HOME/<bin>/skills`. This is where
  * `sources update` INSTALLS package-provided skills (U10) — a symlink per skill
  * — and the second discovery root below reads them back. The single source of
  * truth for both, so the install target and the discovery root can never drift.
+ *
+ * Namespaced by {@link BIN_NAME}, like config, state and cache: two
+ * distributions installed side by side owned ONE skills root, so a `recipes`
+ * build served skills a `pragma` build had installed and could not install its
+ * own without colliding.
  */
 export function installedSkillsDir(): string {
   const dataHome =
     process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");
-  return join(dataHome, "pragma", "skills");
+  return join(dataHome, BIN_NAME, "skills");
 }
 
 /**
  * The conventional roots skills are discovered from, in PRECEDENCE order: the
- * project root (`<cwd>/.pragma/skills`) FIRST so a project-local skill overrides
+ * project root (`<cwd>/.<bin>/skills`) FIRST so a project-local skill overrides
  * an installed skill of the same name (`discoverSkills` dedups first-seen-wins),
- * then installed skills under `$XDG_DATA_HOME/pragma/skills` (where package
+ * then installed skills under `$XDG_DATA_HOME/<bin>/skills` (where package
  * skills land on `sources update`).
  */
 export function skillRoots(cwd: string): string[] {
-  return [join(cwd, ".pragma", "skills"), installedSkillsDir()];
+  return [join(cwd, `.${BIN_NAME}`, "skills"), installedSkillsDir()];
 }
 
 /** Immediate subdirectories of `root` (each a candidate skill folder). */

package/src/capabilities/skill/render.ts

@@ -2,15 +2,14 @@
  * Formatters for `skill list` and `skill lookup`.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import type { Formatters } from "../../kernel/spec/types.js";
 import type { DiscoveredSkill } from "./discover.js";
 import type { SkillLookup } from "./verbs.js";
 
-/** Empty-state guidance (U5) — where skills come from now that packages ship them. */
-const EMPTY_PLAIN =
-  "No skills found.\nSkills come from installed design-system packages — add one to your config, run `pragma sources update`, then `pragma setup skills`.";
-const EMPTY_LLM =
-  "## Skills (0)\n\nNo skills found. Skills come from installed design-system packages — add one to the project config, run `pragma sources update`, then `pragma setup skills`.";
+/** Empty-state guidance (U5) — where skills come from now that packs ship them. */
+const EMPTY_PLAIN = `No skills found.\nSkills come from design-system packs — add one to your config's packs, run \`${BIN_NAME} sources update\`, then \`${BIN_NAME} setup skills\`.`;
+const EMPTY_LLM = `## Skills (0)\n\nNo skills found. Skills come from design-system packs — add one to the project config's packs, run \`${BIN_NAME} sources update\`, then \`${BIN_NAME} setup skills\`.`;
 
 export const skillListFormatters: Formatters<DiscoveredSkill[]> = {
   plain: (skills) =>

package/src/capabilities/skill/verbs.ts

@@ -8,7 +8,9 @@
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { BIN_NAME } from "../../constants.js";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { cliRecovery } from "../../kernel/error/recovery.js";
 import { suggestNames } from "../../kernel/project/cli/suggestNames.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
@@ -26,7 +28,7 @@ const listVerb: VerbSpec<Record<string, unknown>, DiscoveredSkill[]> = {
   summary: "List discovered skills (SKILL.md files under the skill roots).",
   params: [],
   output: { formatters: skillListFormatters },
-  examples: [{ cmd: "pragma skill list" }],
+  examples: [{ cmd: `${BIN_NAME} skill list` }],
   capability: {
     needsStore: false,
     mutates: false,
@@ -53,7 +55,7 @@ const lookupVerb: VerbSpec<Record<string, unknown>, SkillLookup> = {
     },
   ],
   output: { formatters: skillLookupFormatters },
-  examples: [{ cmd: "pragma skill lookup docx" }],
+  examples: [{ cmd: `${BIN_NAME} skill lookup docx` }],
   capability: {
     needsStore: false,
     mutates: false,
@@ -74,11 +76,9 @@ const lookupVerb: VerbSpec<Record<string, unknown>, SkillLookup> = {
           name,
           skills.map((skill) => skill.name),
         ),
-        recovery: {
-          message: "List discovered skills.",
-          cli: "pragma skill list",
-          mcp: { tool: "skill_list" },
-        },
+        recovery: cliRecovery("skill list", "List discovered skills.", {
+          tool: "skill_list",
+        }),
       });
     }
     return { ...match, instructions: readInstructions(match.sourcePath) };

package/src/capabilities/sources/collectStatus.ts

@@ -1,42 +1,51 @@
 /**
  * Collect the `sources status` payload — storeless.
  *
- * Reports the store's readiness without booting it: it reads the lock, the
- * resolved config, and — if the locked pack is cached — the manifest and the
- * index.json count (a plain `JSON.parse`, no store, no oxigraph). This is the
- * capability that must stay off the store factory (the storeless-guarantee spy
- * covers it), so it reaches for the pack files directly rather than through a
- * store session. It absorbs the v1 `info store` summary.
+ * Reports the store's readiness without booting it. The `store` field IS the
+ * boot decision ({@link resolveSources}) — status never re-derives which pack
+ * answers reads, so it can never disagree with what the next read actually
+ * loads. Everything else is provenance read straight off that pack's manifest
+ * (a plain `JSON.parse`, no store, no oxigraph). This is the capability that
+ * must stay off the store factory (the storeless-guarantee spy covers it). It
+ * absorbs the v1 `info store` summary.
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { PackageEntry } from "../../kernel/config/types.js";
+import type { PackDeclaration } from "../../kernel/config/types.js";
+import { embeddedManifest } from "../../kernel/runtime/graphpack/embedded.js";
 import { readManifest } from "../../kernel/runtime/graphpack/manifest.js";
 import { INDEX_FILE } from "../../kernel/runtime/graphpack/types.js";
-import { readLock } from "../../kernel/runtime/lock.js";
-import { packDir } from "../../kernel/runtime/paths.js";
+import { resolveSources } from "../../kernel/runtime/resolveSources.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
-import type {
-  SourceStaleness,
-  SourceStatusEntry,
-  SourcesStatusData,
-} from "./types.js";
+import type { SourcesStatusData } from "./types.js";
 
-const entryName = (entry: PackageEntry): string =>
+const entryName = (entry: PackDeclaration): string =>
   typeof entry === "string" ? entry : entry.name;
-const entrySource = (entry: PackageEntry): string =>
+const entrySource = (entry: PackDeclaration): string =>
   typeof entry === "string" ? entry : (entry.source ?? entry.name);
 
-/** The indexed entity count from a cached pack's index.json (storeless). */
+/**
+ * The distinct-abox entity count from a built pack's index.json (storeless).
+ *
+ * Only reached for LEGACY packs whose manifest predates the persisted
+ * `entityCount` (A10) — a current pack's count is read straight from the
+ * manifest, no index parse. Counts distinct abox subjects so the figure matches
+ * both the manifest count and `info`'s `entityTotal` (A1).
+ */
 function indexEntityCount(dir: string): number | null {
   const path = join(dir, INDEX_FILE);
   if (!existsSync(path)) return null;
   try {
     const parsed = JSON.parse(readFileSync(path, "utf-8")) as {
-      entities?: unknown[];
+      entities?: { box?: string; uri?: string; name?: string }[];
     };
-    return Array.isArray(parsed.entities) ? parsed.entities.length : null;
+    if (!Array.isArray(parsed.entities)) return null;
+    const subjects = new Set<string>();
+    for (const entity of parsed.entities) {
+      if (entity.box === "abox") subjects.add(entity.uri ?? entity.name ?? "");
+    }
+    return subjects.size;
   } catch {
     return null;
   }
@@ -47,41 +56,52 @@ function indexEntityCount(dir: string): number | null {
  *
  * @param runtime - The per-invocation runtime.
  * @returns The storeless status payload.
- * @note Impure — reads config, the lock, and the pack cache from disk.
+ * @note Impure — reads config, the active-pack pointer, and the pack cache.
  */
 export async function collectStatus(
   runtime: PragmaRuntime,
 ): Promise<SourcesStatusData> {
   const layers = await runtime.loadConfig();
-  const entries = layers.config.packages ?? [];
-  const lock = readLock(runtime.cwd);
+  const sources = (layers.config.packs ?? []).map((entry) => ({
+    name: entryName(entry),
+    ref: entrySource(entry),
+  }));
+  const decision = resolveSources(layers, runtime.cwd);
+  const base = { cwd: runtime.cwd, sources };
 
-  const dir = lock ? packDir(lock.contentHash) : undefined;
-  const manifest = dir ? readManifest(dir) : undefined;
-  const cached = manifest !== undefined;
-
-  const sources: SourceStatusEntry[] = entries.map((entry) => {
-    const name = entryName(entry);
-    const ref = entrySource(entry);
-    const lockEntry = lock?.packs.find((pack) => pack.name === name);
-    let staleness: SourceStaleness;
-    if (!lock || !cached) {
-      staleness = "uncached";
-    } else if (!lockEntry || lockEntry.source !== ref) {
-      staleness = "config-drift";
-    } else {
-      staleness = "up-to-date";
+  switch (decision.kind) {
+    case "embedded": {
+      const manifest = embeddedManifest();
+      return {
+        ...base,
+        store: "embedded",
+        contentHash: manifest.contentHash,
+        sourceRef: manifest.sourceRef,
+        builtAt: manifest.createdAt,
+        entityCount: manifest.entityCount ?? null,
+      };
     }
-    return { name, ref, resolved: lockEntry?.resolved ?? null, staleness };
-  });
-
-  return {
-    cwd: runtime.cwd,
-    lockPresent: lock !== undefined,
-    contentHash: lock?.contentHash ?? null,
-    cached,
-    builtAt: manifest?.createdAt ?? null,
-    entityCount: dir && cached ? indexEntityCount(dir) : null,
-    sources,
-  };
+    case "pack": {
+      const manifest = readManifest(decision.dir);
+      return {
+        ...base,
+        store: "built",
+        contentHash: decision.contentHash,
+        sourceRef: manifest?.sourceRef ?? null,
+        builtAt: manifest?.createdAt ?? null,
+        // Prefer the manifest's persisted count (no index parse); a legacy pack
+        // without it falls back to counting the index's abox subjects (A10).
+        entityCount: manifest?.entityCount ?? indexEntityCount(decision.dir),
+      };
+    }
+    case "unavailable":
+      return {
+        ...base,
+        store: "unavailable",
+        contentHash: null,
+        sourceRef: null,
+        builtAt: null,
+        entityCount: null,
+      };
+  }
 }

package/src/capabilities/sources/index.ts

@@ -1,6 +1,6 @@
 /**
  * The `sources` capability barrel — `status` (storeless read) and `update`
- * (the resolve/build/lock Task).
+ * (the resolve/build/point Task).
  */
 
 import { asVerb } from "../../kernel/spec/asVerb.js";

package/src/capabilities/sources/installSkills.ts

@@ -4,9 +4,9 @@
  * Design-system packages ship a top-level `skills/<name>/SKILL.md`, but skill
  * discovery only scans the project root and the installed-skills root — never a
  * resolved package's clone/dir. So `sources update` INSTALLS each package's
- * skills into the installed-skills root (`$XDG_DATA_HOME/pragma/skills`) as
+ * skills into the installed-skills root (`$XDG_DATA_HOME/<bin>/skills`) as
  * symlinks, exactly the root `discoverSkills` already reads. Precedence is
- * preserved (a project `.pragma/skills` entry still wins — it is discovered
+ * preserved (a project `.<bin>/skills` entry still wins — it is discovered
  * first), and the update Task stays reversible (each created link carries an
  * unlink undo).
  *