@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/capabilities/shared/registry.ts

@@ -0,0 +1,70 @@
+/**
+ * npm registry version check — the shared network read `info` (enrichment) and
+ * `upgrade` (mutation) both consume.
+ *
+ * Ported verbatim from the old shell's `info/operations/checkRegistryVersion` +
+ * its `DIST_TAG_MAP`/`REGISTRY_TIMEOUT_MS` constants. A single GET against the
+ * registry's package document, a 3s timeout, and `undefined` on any failure
+ * (offline, non-2xx, timeout, missing dist-tag) — so a caller degrades silently
+ * rather than erroring. The whole request is preview-safe: it is a plain read
+ * with no side effects.
+ */
+
+import type { Channel } from "../../kernel/config/types.js";
+
+/**
+ * The published package `info`/`upgrade` check for updates: the stable name
+ * users installed, so the check answers "is a newer release of the tool
+ * available".
+ */
+export const PRAGMA_PACKAGE = "@canonical/pragma-cli";
+
+/** Maps each release channel to its corresponding npm dist-tag (internal). */
+const DIST_TAG_MAP: Record<Channel, string> = {
+  normal: "latest",
+  experimental: "experimental",
+  prerelease: "next",
+};
+
+/** Timeout in milliseconds for npm registry HTTP requests. */
+export const REGISTRY_TIMEOUT_MS = 3_000;
+
+/** Result of checking the npm registry for the latest package version. */
+export interface RegistryCheckResult {
+  readonly latest: string;
+}
+
+/**
+ * Check the npm registry for the latest published version of a package.
+ *
+ * @param packageName - The npm package name (e.g. `@canonical/pragma-cli`).
+ * @param channel - The release channel, selecting which dist-tag to read.
+ * @returns The latest version for the channel's dist-tag, or `undefined` when
+ *   offline / non-2xx / timed out / the dist-tag is absent.
+ * @note Impure — a single network GET (3s timeout, silent-fail).
+ */
+export async function checkRegistryVersion(
+  packageName: string,
+  channel: Channel,
+): Promise<RegistryCheckResult | undefined> {
+  const distTag = DIST_TAG_MAP[channel];
+  const url = `https://registry.npmjs.org/${encodeURIComponent(packageName)}`;
+
+  try {
+    const response = await fetch(url, {
+      signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),
+      headers: { Accept: "application/json" },
+    });
+    if (!response.ok) return undefined;
+
+    const data = (await response.json()) as {
+      "dist-tags"?: Record<string, string>;
+    };
+    const version = data["dist-tags"]?.[distTag];
+    if (!version) return undefined;
+
+    return { latest: version };
+  } catch {
+    return undefined;
+  }
+}

package/src/capabilities/skill/discover.ts

@@ -0,0 +1,178 @@
+/**
+ * Storeless skill discovery over the filesystem.
+ *
+ * A skill is a folder with a `SKILL.md` carrying YAML frontmatter (`name`,
+ * `description`, and the #856 `prompt` flag among others). Skills are discovered
+ * from conventional roots — project skills under `<cwd>/.pragma/skills`, which
+ * take precedence, then installed skills under `$XDG_DATA_HOME/pragma/skills` —
+ * with missing files and invalid frontmatter skipped gracefully. Reads only the
+ * filesystem, never the graph store, so `skill list`/`lookup` are storeless
+ * (needsStore: false).
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
+/** Parsed SKILL.md frontmatter. */
+export interface SkillFrontmatter {
+  readonly name: string;
+  readonly description: string;
+  /** #856 — whether this skill also registers as an MCP prompt. */
+  readonly prompt?: boolean;
+  readonly license?: string;
+}
+
+/** A discovered skill: its frontmatter plus where it was found. */
+export interface DiscoveredSkill {
+  readonly name: string;
+  readonly description: string;
+  readonly folderName: string;
+  readonly sourcePath: string;
+  readonly frontmatter: SkillFrontmatter;
+}
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+/** Parse one YAML scalar (string, boolean, number, or inline array). */
+function parseYamlValue(raw: string): unknown {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+    return trimmed
+      .slice(1, -1)
+      .split(",")
+      .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+      .filter(Boolean);
+  }
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  const num = Number(trimmed);
+  if (!Number.isNaN(num) && trimmed !== "") return num;
+  return trimmed.replace(/^["']|["']$/g, "");
+}
+
+/** Parse a simple YAML subset (top-level keys + one nesting level). */
+function parseSimpleYaml(block: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  let currentKey: string | null = null;
+  let nested: Record<string, unknown> | null = null;
+  for (const line of block.split("\n")) {
+    if (line.trim() === "" || line.trim().startsWith("#")) continue;
+    const indented = line.match(/^(\s+)(\w[\w-]*)\s*:\s*(.*)/);
+    const topLevel = line.match(/^(\w[\w-]*)\s*:\s*(.*)/);
+    if (indented && currentKey && (indented[1]?.length ?? 0) >= 2) {
+      if (!nested) nested = {};
+      nested[indented[2] as string] = parseYamlValue(
+        (indented[3] ?? "").trim(),
+      );
+    } else if (topLevel) {
+      if (currentKey && nested) {
+        result[currentKey] = nested;
+        nested = null;
+      }
+      const key = topLevel[1] as string;
+      const value = topLevel[2] ?? "";
+      currentKey = key;
+      if (value === "") {
+        nested = {};
+      } else {
+        result[key] = parseYamlValue(value);
+        nested = null;
+      }
+    }
+  }
+  if (currentKey && nested) result[currentKey] = nested;
+  return result;
+}
+
+/** Extract and validate SKILL.md frontmatter; `null` when missing/invalid. */
+export function parseFrontmatter(content: string): SkillFrontmatter | null {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match?.[1]) return null;
+  const parsed = parseSimpleYaml(match[1]);
+  if (typeof parsed.name !== "string" || parsed.name === "") return null;
+  if (typeof parsed.description !== "string" || parsed.description === "") {
+    return null;
+  }
+  return {
+    name: parsed.name,
+    description: parsed.description,
+    ...(typeof parsed.prompt === "boolean" ? { prompt: parsed.prompt } : {}),
+    ...(typeof parsed.license === "string" ? { license: parsed.license } : {}),
+  };
+}
+
+/**
+ * The installed-skills root: `$XDG_DATA_HOME/pragma/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.
+ */
+export function installedSkillsDir(): string {
+  const dataHome =
+    process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");
+  return join(dataHome, "pragma", "skills");
+}
+
+/**
+ * The conventional roots skills are discovered from, in PRECEDENCE order: the
+ * project root (`<cwd>/.pragma/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
+ * skills land on `sources update`).
+ */
+export function skillRoots(cwd: string): string[] {
+  return [join(cwd, ".pragma", "skills"), installedSkillsDir()];
+}
+
+/** Immediate subdirectories of `root` (each a candidate skill folder). */
+function subdirs(root: string): string[] {
+  try {
+    return readdirSync(root)
+      .map((name) => join(root, name))
+      .filter((path) => {
+        try {
+          return statSync(path).isDirectory();
+        } catch {
+          return false;
+        }
+      });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Discover every skill reachable from the conventional roots.
+ *
+ * @param cwd - The project directory (project skills root).
+ * @returns Discovered skills, sorted by name; malformed ones are skipped.
+ * @note Impure — reads SKILL.md files.
+ */
+export function discoverSkills(cwd: string): DiscoveredSkill[] {
+  const skills: DiscoveredSkill[] = [];
+  const seen = new Set<string>();
+  for (const root of skillRoots(cwd)) {
+    for (const dir of subdirs(root)) {
+      let content: string;
+      try {
+        content = readFileSync(join(dir, "SKILL.md"), "utf-8");
+      } catch {
+        continue;
+      }
+      const frontmatter = parseFrontmatter(content);
+      if (!frontmatter || seen.has(frontmatter.name)) continue;
+      seen.add(frontmatter.name);
+      skills.push({
+        name: frontmatter.name,
+        description: frontmatter.description,
+        folderName: basename(dir),
+        sourcePath: dir,
+        frontmatter,
+      });
+    }
+  }
+  return skills.sort((a, b) =>
+    a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+  );
+}

package/src/capabilities/skill/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The `skill` capability module — storeless filesystem discovery.
+ */
+
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { skillListVerb, skillLookupVerb } from "./verbs.js";
+
+/** The `skill` capability module (`list`, `lookup`). */
+export const skillModule: CapabilityModule = {
+  name: "skill",
+  verbs: [skillListVerb, skillLookupVerb],
+};

package/src/capabilities/skill/render.ts

@@ -0,0 +1,60 @@
+/**
+ * Formatters for `skill list` and `skill lookup`.
+ */
+
+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`.";
+
+export const skillListFormatters: Formatters<DiscoveredSkill[]> = {
+  plain: (skills) =>
+    skills.length === 0
+      ? EMPTY_PLAIN
+      : skills
+          .map(
+            (s) =>
+              `${s.name}${s.frontmatter.prompt ? " (prompt)" : ""}  ${s.description}`,
+          )
+          .join("\n"),
+  llm: (skills) =>
+    skills.length === 0
+      ? EMPTY_LLM
+      : [
+          `## Skills (${skills.length})`,
+          "",
+          ...skills.map(
+            (s) =>
+              `- **${s.name}**${s.frontmatter.prompt ? " (prompt)" : ""} — ${s.description}`,
+          ),
+        ].join("\n"),
+  json: (skills) => JSON.stringify(skills, null, 2),
+};
+
+export const skillLookupFormatters: Formatters<SkillLookup> = {
+  plain(skill) {
+    const lines = [
+      skill.name,
+      "═".repeat(Math.max(skill.name.length, 24)),
+      "",
+      `  ${skill.description}`,
+    ];
+    if (skill.frontmatter.prompt) lines.push("  registers as an MCP prompt");
+    if (skill.frontmatter.license) {
+      lines.push(`  license: ${skill.frontmatter.license}`);
+    }
+    if (skill.instructions) lines.push("", skill.instructions);
+    return lines.join("\n");
+  },
+  llm(skill) {
+    const lines = [`## ${skill.name}`, "", skill.description, ""];
+    if (skill.instructions) lines.push(skill.instructions);
+    return lines.join("\n").trimEnd();
+  },
+  json: (skill) => JSON.stringify(skill, null, 2),
+};

package/src/capabilities/skill/skill.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Skill discovery (list + lookup) — storeless filesystem reads.
+ *
+ * Skills are SKILL.md folders under the project root; discovery reads only the
+ * filesystem, so the store must never boot (needsStore: false). The #856
+ * `prompt` frontmatter flag is preserved.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { TEST_FLAGS } from "../../testing/helpers/projectCli.js";
+import type { DiscoveredSkill } from "./discover.js";
+import { skillModule } from "./index.js";
+import { skillListFormatters } from "./render.js";
+import type { SkillLookup } from "./verbs.js";
+
+const listVerb = skillModule.verbs.find(
+  (v) => verbKey(v.path) === "skill list",
+) as VerbSpec;
+const lookupVerb = skillModule.verbs.find(
+  (v) => verbKey(v.path) === "skill lookup",
+) as VerbSpec;
+
+let projectDir: string;
+let rt: PragmaRuntime;
+
+function writeSkill(name: string, body: string): void {
+  const dir = join(projectDir, ".pragma", "skills", name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "SKILL.md"), body);
+}
+
+beforeAll(() => {
+  projectDir = mkdtempSync(join(tmpdir(), "pragma-skills-"));
+  writeSkill(
+    "docx",
+    "---\nname: docx\ndescription: Work with Word documents.\n---\nUse this for .docx files.",
+  );
+  writeSkill(
+    "pdf",
+    "---\nname: pdf\ndescription: Work with PDF files.\nprompt: true\nlicense: MIT\n---\nUse this for PDFs.",
+  );
+  // A folder with no SKILL.md is skipped gracefully.
+  mkdirSync(join(projectDir, ".pragma", "skills", "empty"), {
+    recursive: true,
+  });
+  rt = bootRuntime(TEST_FLAGS, projectDir);
+});
+
+afterAll(() => {
+  rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe("skill list (storeless)", () => {
+  it("discovers skills by name, carrying the prompt flag", async () => {
+    const skills = (await listVerb.run({}, rt)) as DiscoveredSkill[];
+    expect(skills.map((s) => s.name)).toEqual(["docx", "pdf"]);
+    expect(skills.find((s) => s.name === "pdf")?.frontmatter.prompt).toBe(true);
+    expect(
+      skills.find((s) => s.name === "docx")?.frontmatter.prompt,
+    ).toBeUndefined();
+    // needsStore: false — discovery never boots the store.
+    expect(rt.store.booted).toBe(false);
+  });
+});
+
+describe("skill lookup (storeless)", () => {
+  it("returns metadata + instructions, and suggests on a miss", async () => {
+    const skill = (await lookupVerb.run({ name: "pdf" }, rt)) as SkillLookup;
+    expect(skill.description).toBe("Work with PDF files.");
+    expect(skill.frontmatter.license).toBe("MIT");
+    expect(skill.instructions).toBe("Use this for PDFs.");
+    expect(rt.store.booted).toBe(false);
+
+    await expect(lookupVerb.run({ name: "docs" }, rt)).rejects.toThrow(
+      /not found/i,
+    );
+  });
+});
+
+describe("skill list empty-state (U5)", () => {
+  it("plain output is non-blank and guides toward package sources", () => {
+    const plain = skillListFormatters.plain([]);
+    expect(plain).not.toBe("");
+    expect(plain).toContain("No skills found");
+    expect(plain).toContain("pragma sources update");
+  });
+
+  it("llm output announces zero and guides, json stays []", () => {
+    expect(skillListFormatters.llm([])).toContain("Skills (0)");
+    expect(skillListFormatters.llm([])).toContain("pragma sources update");
+    expect(skillListFormatters.json([])).toBe("[]");
+  });
+});
+
+describe("skill precedence (project overrides installed)", () => {
+  let precedenceDir: string;
+  let installedHome: string;
+  let savedDataHome: string | undefined;
+  let precedenceRt: PragmaRuntime;
+
+  beforeAll(() => {
+    precedenceDir = mkdtempSync(join(tmpdir(), "pragma-skills-proj-"));
+    installedHome = mkdtempSync(join(tmpdir(), "pragma-skills-installed-"));
+    // An installed skill and a project skill both claim the name `shared`.
+    const installed = join(installedHome, "pragma", "skills", "shared");
+    mkdirSync(installed, { recursive: true });
+    writeFileSync(
+      join(installed, "SKILL.md"),
+      "---\nname: shared\ndescription: INSTALLED copy.\n---\nInstalled body.",
+    );
+    const project = join(precedenceDir, ".pragma", "skills", "shared");
+    mkdirSync(project, { recursive: true });
+    writeFileSync(
+      join(project, "SKILL.md"),
+      "---\nname: shared\ndescription: PROJECT copy.\n---\nProject body.",
+    );
+    savedDataHome = process.env.XDG_DATA_HOME;
+    process.env.XDG_DATA_HOME = installedHome;
+    precedenceRt = bootRuntime(TEST_FLAGS, precedenceDir);
+  });
+
+  afterAll(() => {
+    if (savedDataHome === undefined) delete process.env.XDG_DATA_HOME;
+    else process.env.XDG_DATA_HOME = savedDataHome;
+    rmSync(precedenceDir, { recursive: true, force: true });
+    rmSync(installedHome, { recursive: true, force: true });
+  });
+
+  it("returns the project skill, not the installed one, on a name clash", async () => {
+    const skills = (await listVerb.run({}, precedenceRt)) as DiscoveredSkill[];
+    const shared = skills.filter((s) => s.name === "shared");
+    expect(shared).toHaveLength(1);
+    expect(shared[0]?.description).toBe("PROJECT copy.");
+  });
+});

package/src/capabilities/skill/verbs.ts

@@ -0,0 +1,100 @@
+/**
+ * `skill list` and `skill lookup <name>` — storeless filesystem discovery.
+ *
+ * Both read SKILL.md files from the conventional roots (never the graph store),
+ * so they are needsStore: false. `lookup` additionally returns the skill's
+ * instructions (the SKILL.md body after the frontmatter).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { suggestNames } from "../../kernel/project/cli/suggestNames.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { type DiscoveredSkill, discoverSkills } from "./discover.js";
+import { skillListFormatters, skillLookupFormatters } from "./render.js";
+
+/** A looked-up skill: its metadata plus the SKILL.md instructions body. */
+export interface SkillLookup extends DiscoveredSkill {
+  readonly instructions: string;
+}
+
+const listVerb: VerbSpec<Record<string, unknown>, DiscoveredSkill[]> = {
+  path: ["skill", "list"],
+  summary: "List discovered skills (SKILL.md files under the skill roots).",
+  params: [],
+  output: { formatters: skillListFormatters },
+  examples: [{ cmd: "pragma skill list" }],
+  capability: {
+    needsStore: false,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: async (_params: Record<string, unknown>, rt: PragmaRuntime) =>
+    discoverSkills(rt.cwd),
+};
+
+const lookupVerb: VerbSpec<Record<string, unknown>, SkillLookup> = {
+  path: ["skill", "lookup"],
+  summary: "Show a skill's metadata and instructions by name.",
+  params: [
+    {
+      kind: "string",
+      name: "name",
+      doc: "The skill name.",
+      positional: true,
+      required: true,
+      complete: { kind: "names", source: { from: "skills" } },
+    },
+  ],
+  output: { formatters: skillLookupFormatters },
+  examples: [{ cmd: "pragma skill lookup docx" }],
+  capability: {
+    needsStore: false,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: async (params: Record<string, unknown>, rt: PragmaRuntime) => {
+    const name = String(params.name);
+    const skills = discoverSkills(rt.cwd);
+    const match = skills.find(
+      (skill) => skill.name.toLowerCase() === name.toLowerCase(),
+    );
+    if (!match) {
+      throw PragmaError.notFound("skill", name, {
+        suggestions: suggestNames(
+          name,
+          skills.map((skill) => skill.name),
+        ),
+        recovery: {
+          message: "List discovered skills.",
+          cli: "pragma skill list",
+          mcp: { tool: "skill_list" },
+        },
+      });
+    }
+    return { ...match, instructions: readInstructions(match.sourcePath) };
+  },
+};
+
+/** Read the SKILL.md body after its frontmatter block. */
+function readInstructions(dir: string): string {
+  try {
+    const content = readFileSync(join(dir, "SKILL.md"), "utf-8");
+    return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "").trim();
+  } catch {
+    return "";
+  }
+}
+
+/** The `skill` verbs (`list`, `lookup`). */
+export const skillListVerb = asVerb(listVerb);
+export const skillLookupVerb = asVerb(lookupVerb);

package/src/capabilities/sources/collectStatus.ts

@@ -0,0 +1,102 @@
+/**
+ * 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.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { PackageEntry } from "../../kernel/config/types.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 type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type {
+  SourceStaleness,
+  SourceStatusEntry,
+  SourcesStatusData,
+} from "./types.js";
+
+const entryName = (entry: PackageEntry): string =>
+  typeof entry === "string" ? entry : entry.name;
+const entrySource = (entry: PackageEntry): string =>
+  typeof entry === "string" ? entry : (entry.source ?? entry.name);
+
+/**
+ * The distinct-abox entity count from a cached 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?: { box?: string; uri?: string; name?: string }[];
+    };
+    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;
+  }
+}
+
+/**
+ * Assemble the `sources status` payload for the runtime's cwd.
+ *
+ * @param runtime - The per-invocation runtime.
+ * @returns The storeless status payload.
+ * @note Impure — reads config, the lock, and the pack cache from disk.
+ */
+export async function collectStatus(
+  runtime: PragmaRuntime,
+): Promise<SourcesStatusData> {
+  const layers = await runtime.loadConfig();
+  const entries = layers.config.packages ?? [];
+  const lock = readLock(runtime.cwd);
+
+  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";
+    }
+    return { name, ref, resolved: lockEntry?.resolved ?? null, staleness };
+  });
+
+  return {
+    cwd: runtime.cwd,
+    lockPresent: lock !== undefined,
+    contentHash: lock?.contentHash ?? null,
+    cached,
+    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:
+      dir && cached ? (manifest?.entityCount ?? indexEntityCount(dir)) : null,
+    sources,
+  };
+}

package/src/capabilities/sources/index.ts

@@ -0,0 +1,15 @@
+/**
+ * The `sources` capability barrel — `status` (storeless read) and `update`
+ * (the resolve/build/lock Task).
+ */
+
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { statusVerb } from "./status.verb.js";
+import { updateVerb } from "./update.verb.js";
+
+/** The `sources` capability module. */
+export const sourcesModule: CapabilityModule = {
+  name: "sources",
+  verbs: [asVerb(statusVerb), asVerb(updateVerb)],
+};