@canonical/pragma-cli 0.31.0 → 0.32.0

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,87 @@
+/**
+ * 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 indexed entity count from a cached pack's index.json (storeless). */
+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[];
+    };
+    return Array.isArray(parsed.entities) ? parsed.entities.length : null;
+  } 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,
+    entityCount: dir && cached ? 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)],
+};

package/src/capabilities/sources/installSkills.ts

@@ -0,0 +1,124 @@
+/**
+ * Plan the symlink install of package-provided skills (U10).
+ *
+ * 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
+ * symlinks, exactly the root `discoverSkills` already reads. Precedence is
+ * preserved (a project `.pragma/skills` entry still wins — it is discovered
+ * first), and the update Task stays reversible (each created link carries an
+ * unlink undo).
+ *
+ * Decisions run against REAL fs here so the update's `--dry-run` plan is
+ * accurate; the composed Task performs only the symlink/delete effects.
+ */
+
+import { existsSync, lstatSync, readdirSync, readlinkSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import type { ResolvedPackage } from "../../kernel/runtime/refs/resolve.js";
+import { installedSkillsDir } from "../skill/discover.js";
+
+/** One planned skill symlink into the installed-skills root. */
+export interface SkillLinkAction {
+  /** The package's skill folder — the symlink target. */
+  readonly target: string;
+  /** `<installedSkillsDir>/<folderName>` — where the symlink is created. */
+  readonly linkPath: string;
+  /** created (absent), skipped (already correct / a real dir), or replaced. */
+  readonly action: "created" | "skipped" | "replaced";
+  /** The skill folder name (the discovery key). */
+  readonly folderName: string;
+  /** The package the skill came from. */
+  readonly packageName: string;
+}
+
+/** What currently occupies a candidate link path. */
+type LinkState =
+  | { readonly kind: "absent" }
+  | { readonly kind: "symlink"; readonly target: string }
+  | { readonly kind: "other" };
+
+/** Classify a link path: absent, our-or-another symlink, or a real entry. */
+function linkState(linkPath: string): LinkState {
+  let stat: ReturnType<typeof lstatSync>;
+  try {
+    stat = lstatSync(linkPath);
+  } catch {
+    return { kind: "absent" };
+  }
+  if (stat.isSymbolicLink()) {
+    try {
+      return { kind: "symlink", target: readlinkSync(linkPath) };
+    } catch {
+      return { kind: "other" };
+    }
+  }
+  return { kind: "other" };
+}
+
+/** Skill folders (immediate subdirs with a `SKILL.md`) under `<root>/skills`. */
+function packageSkillDirs(root: string): string[] {
+  const skillsDir = join(root, "skills");
+  let names: string[];
+  try {
+    names = readdirSync(skillsDir);
+  } catch {
+    return []; // No `skills/` dir — the common case.
+  }
+  const out: string[] = [];
+  for (const name of names) {
+    const dir = join(skillsDir, name);
+    try {
+      if (lstatSync(dir).isDirectory() && existsSync(join(dir, "SKILL.md"))) {
+        out.push(dir);
+      }
+    } catch {
+      // Unreadable entry — skip.
+    }
+  }
+  return out;
+}
+
+/**
+ * Plan the symlink actions that install each resolved package's `skills/*` into
+ * the installed-skills discovery root. First-seen wins on a folder-name clash
+ * across packages. A real (non-symlink) entry at the link path is left untouched
+ * (`skipped`) so a manually-installed skill is never clobbered.
+ *
+ * @param resolved - The resolved packages (each carrying its on-disk `root`).
+ * @returns The planned actions (including `skipped`, for an accurate preview).
+ * @note Impure — stats the filesystem to decide each action.
+ */
+export function planSkillInstall(
+  resolved: readonly ResolvedPackage[],
+): SkillLinkAction[] {
+  const dest = installedSkillsDir();
+  const actions: SkillLinkAction[] = [];
+  const seen = new Set<string>();
+  for (const pkg of resolved) {
+    for (const skillDir of packageSkillDirs(pkg.root)) {
+      const folderName = basename(skillDir);
+      if (seen.has(folderName)) continue;
+      seen.add(folderName);
+      const linkPath = resolve(dest, folderName);
+      const state = linkState(linkPath);
+      const action: SkillLinkAction["action"] =
+        state.kind === "absent"
+          ? "created"
+          : state.kind === "symlink" && state.target === skillDir
+            ? "skipped"
+            : state.kind === "symlink"
+              ? "replaced"
+              : "skipped";
+      actions.push({
+        target: skillDir,
+        linkPath,
+        action,
+        folderName,
+        packageName: pkg.name,
+      });
+    }
+  }
+  return actions;
+}