@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/capabilities/sources/status.render.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { type RenderStyle, styleFor } from "../../kernel/render/style.js";
+import { renderSourcesStatusPlain } from "./status.render.js";
+import type { SourcesStatusData } from "./types.js";
+
+const DATA: SourcesStatusData = {
+  cwd: "/repo",
+  lockPresent: true,
+  contentHash: "abcdef012345aaaa",
+  cached: true,
+  builtAt: "2026-01-01",
+  entityCount: 42,
+  sources: [
+    {
+      name: "ds",
+      ref: "ds@1",
+      resolved: "1111111111112222",
+      staleness: "up-to-date",
+    },
+    {
+      name: "extra",
+      ref: "extra@1",
+      resolved: null,
+      staleness: "config-drift",
+    },
+  ],
+};
+
+/** A sentinel styler — enabled, each color wrapped in a visible tag. */
+const TAGGED: RenderStyle = {
+  enabled: true,
+  bold: (t) => `<b>${t}</b>`,
+  dim: (t) => `<d>${t}</d>`,
+  cyan: (t) => `<c>${t}</c>`,
+  green: (t) => `<g>${t}</g>`,
+  yellow: (t) => `<y>${t}</y>`,
+};
+
+describe("renderSourcesStatusPlain", () => {
+  it("is byte-identical to the plain form when the styler is disabled", () => {
+    expect(renderSourcesStatusPlain(DATA, styleFor(false))).toBe(
+      [
+        "Store: ready",
+        "  pack: abcdef012345 — 42 entities, built 2026-01-01",
+        "",
+        "Sources:",
+        "  ds [ok] @ 111111111111",
+        "  extra [config drift]",
+      ].join("\n"),
+    );
+  });
+
+  it("bolds the heading, aligns names, and tints markers on a TTY", () => {
+    const out = renderSourcesStatusPlain(DATA, TAGGED);
+    const nameWidth = "extra".length;
+    expect(out).toContain("<b>Sources:</b>");
+    // up-to-date tints green with a dim resolved suffix; drift tints yellow.
+    expect(out).toContain(
+      `  ${"ds".padEnd(nameWidth)}  <g>[ok]</g><d> @ 111111111111</d>`,
+    );
+    expect(out).toContain(
+      `  ${"extra".padEnd(nameWidth)}  <y>[config drift]</y>`,
+    );
+  });
+});

package/src/capabilities/sources/status.render.ts

@@ -0,0 +1,83 @@
+/**
+ * Formatters for `pragma sources status` — plain, llm, json.
+ */
+
+import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
+import type { Formatters } from "../../kernel/spec/types.js";
+import type { SourcesStatusData } from "./types.js";
+
+const STALENESS_MARK: Record<string, string> = {
+  "up-to-date": "ok",
+  "config-drift": "config drift",
+  uncached: "not built",
+};
+
+/**
+ * Render `sources status` as plain text.
+ *
+ * @param data - The resolved sources-status payload.
+ * @param style - TTY styling; defaults to the process style. On a color-capable
+ *   terminal the `Sources:` heading is bold, source names align into a column,
+ *   and each staleness marker is tinted (green up-to-date, else yellow); off a
+ *   TTY the styler is inert, so the output is byte-identical to the plain form.
+ * @returns The formatted status block.
+ */
+export function renderSourcesStatusPlain(
+  data: SourcesStatusData,
+  style: RenderStyle = defaultStyle(),
+): string {
+  const lines = [
+    data.lockPresent
+      ? `Store: ${data.cached ? "ready" : "locked but not cached"}`
+      : "Store: no lock (run `pragma sources update`)",
+  ];
+  if (data.cached) {
+    lines.push(
+      `  pack: ${data.contentHash?.slice(0, 12)} — ${data.entityCount ?? "?"} entities, built ${data.builtAt ?? "?"}`,
+    );
+  }
+  lines.push("", style.enabled ? style.bold("Sources:") : "Sources:");
+  if (data.sources.length === 0) {
+    lines.push("  (none configured)");
+  }
+  const nameWidth = style.enabled
+    ? Math.max(0, ...data.sources.map((source) => source.name.length))
+    : 0;
+  for (const source of data.sources) {
+    const mark = STALENESS_MARK[source.staleness] ?? source.staleness;
+    const resolved = source.resolved
+      ? ` @ ${source.resolved.slice(0, 12)}`
+      : "";
+    if (!style.enabled) {
+      lines.push(`  ${source.name} [${mark}]${resolved}`);
+      continue;
+    }
+    const tint = source.staleness === "up-to-date" ? style.green : style.yellow;
+    lines.push(
+      `  ${source.name.padEnd(nameWidth)}  ${tint(`[${mark}]`)}${style.dim(resolved)}`,
+    );
+  }
+  return lines.join("\n");
+}
+
+export const statusFormatters: Formatters<SourcesStatusData> = {
+  plain(data) {
+    return renderSourcesStatusPlain(data);
+  },
+
+  llm(data) {
+    const lines = [
+      `# sources`,
+      `- Store: ${data.lockPresent ? (data.cached ? "ready" : "locked, not cached") : "no lock"}`,
+      ...(data.cached ? [`- Entities: ${data.entityCount ?? "?"}`] : []),
+    ];
+    for (const source of data.sources) {
+      lines.push(`- ${source.name}: ${source.staleness}`);
+    }
+    return lines.join("\n");
+  },
+
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

package/src/capabilities/sources/status.verb.ts

@@ -0,0 +1,42 @@
+/**
+ * The `sources status` verb — a storeless read.
+ *
+ * `needsStore: false` is load-bearing: status must report even a cold or
+ * unbuilt store (staleness `uncached`), so it must NOT boot the store — booting
+ * a cold store would throw STORE_UNAVAILABLE before status could say so. Its
+ * `run` is a lazy thunk (the collector is dynamic-imported), keeping the config
+ * reader off the fast path, exactly like `info`.
+ */
+
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { statusFormatters } from "./status.render.js";
+import type { SourcesStatusData } from "./types.js";
+
+/** The `sources status` verb spec. */
+export const statusVerb: VerbSpec<
+  Record<string, unknown>,
+  SourcesStatusData
+> = {
+  path: ["sources", "status"],
+  summary: "Report the local store's readiness and per-source staleness.",
+  doc: "Storeless — reads the lock, config, and pack cache without booting the store, so it works even when the store is cold.",
+  params: [],
+  output: { formatters: statusFormatters },
+  examples: [
+    { cmd: "pragma sources status", note: "human-readable readiness summary" },
+    { cmd: "pragma sources status --format json", note: "the full envelope" },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: false,
+    needsNetwork: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (_params, runtime) =>
+    import("./collectStatus.js").then((module) =>
+      module.collectStatus(runtime),
+    ),
+};

package/src/capabilities/sources/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Data shapes for the `sources` noun — `status` (storeless read) and `update`
+ * (the Task that resolves, builds, and locks the store).
+ */
+
+/** How a configured source stands relative to the lock and the pack cache. */
+export type SourceStaleness = "up-to-date" | "config-drift" | "uncached";
+
+/** One configured source's status. */
+export interface SourceStatusEntry {
+  /** Package name. */
+  readonly name: string;
+  /** The config `packages` source ref (verbatim). */
+  readonly ref: string;
+  /** The lock's resolved revision, or null when not locked. */
+  readonly resolved: string | null;
+  /** Whether the config ref matches the lock and the pack is cached. */
+  readonly staleness: SourceStaleness;
+}
+
+/** The `sources status` payload — assembled without booting the store. */
+export interface SourcesStatusData {
+  readonly cwd: string;
+  /** Whether a `pragma.lock.json` is present. */
+  readonly lockPresent: boolean;
+  /** The locked combined-pack content hash, or null. */
+  readonly contentHash: string | null;
+  /** Whether the locked pack is present in the cache. */
+  readonly cached: boolean;
+  /** When the cached pack was built (manifest `createdAt`), or null. */
+  readonly builtAt: string | null;
+  /** Total indexed entity count from the cached pack, or null. */
+  readonly entityCount: number | null;
+  readonly sources: readonly SourceStatusEntry[];
+}
+
+/** One resolved source in the `sources update` result. */
+export interface UpdatedSource {
+  readonly name: string;
+  readonly resolved: string;
+  readonly sourceCount: number;
+}
+
+/** The `sources update` result payload. */
+export interface SourcesUpdateData {
+  readonly contentHash: string;
+  /** Whether the pack was reused from cache rather than rebuilt. */
+  readonly reused: boolean;
+  readonly lockPath: string;
+  readonly packs: readonly UpdatedSource[];
+}

package/src/capabilities/sources/update.render.ts

@@ -0,0 +1,35 @@
+/**
+ * Formatters for `pragma sources update` — plain, llm, json.
+ */
+
+import type { Formatters } from "../../kernel/spec/types.js";
+import type { SourcesUpdateData } from "./types.js";
+
+export const updateFormatters: Formatters<SourcesUpdateData> = {
+  plain(data) {
+    const lines = [
+      data.reused
+        ? `Store up to date (pack ${data.contentHash.slice(0, 12)}).`
+        : `Built pack ${data.contentHash.slice(0, 12)}.`,
+      `Wrote ${data.lockPath}.`,
+    ];
+    for (const pack of data.packs) {
+      lines.push(
+        `  ${pack.name} @ ${pack.resolved.slice(0, 12)} (${pack.sourceCount} source${pack.sourceCount === 1 ? "" : "s"})`,
+      );
+    }
+    return lines.join("\n");
+  },
+
+  llm(data) {
+    return [
+      `# sources update`,
+      `- Pack: ${data.contentHash.slice(0, 12)}${data.reused ? " (reused)" : ""}`,
+      ...data.packs.map((pack) => `- ${pack.name}: ${pack.resolved}`),
+    ].join("\n");
+  },
+
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

package/src/capabilities/sources/update.verb.ts

@@ -0,0 +1,76 @@
+/**
+ * The `sources update` verb — resolve, build, and lock the store.
+ *
+ * A mutation (`mutates: true`) that needs the network (`needsNetwork: true`)
+ * but NOT the pre-booted store (`needsStore: false`): update is what *creates*
+ * the store, so the dispatcher must not try to boot it first (a cold boot would
+ * throw STORE_UNAVAILABLE). `run` returns a `Promise<Task<R>>` — the union's
+ * third arm — which the dispatcher awaits: for a real execution it resolves and
+ * builds before handing back the lock-writing Task; for a preview
+ * (`runtime.mutation.preview`) it stays network-free and hands back a
+ * plan-only Task. `--frozen` re-resolves to the lock's pinned revisions.
+ */
+
+import type { Task } from "@canonical/task";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import type { SourcesUpdateData } from "./types.js";
+import { updateFormatters } from "./update.render.js";
+
+/** The `sources update` verb spec. */
+export const updateVerb: VerbSpec<
+  { frozen?: boolean; skipInvalid?: boolean },
+  SourcesUpdateData
+> = {
+  path: ["sources", "update"],
+  summary: "Resolve configured packages, build the local store, and lock it.",
+  doc: "Resolves each configured package (git/file/npm), builds one content-addressed pack, and writes pragma.lock.json. Networkless boots then load from the lock.",
+  params: [
+    {
+      kind: "boolean",
+      name: "frozen",
+      doc: "Re-resolve to the lock's pinned revisions exactly; never advance.",
+    },
+    {
+      kind: "boolean",
+      name: "skipInvalid",
+      doc: "Skip sources that fail to parse (warning about each) and build from the rest, instead of failing the whole update.",
+    },
+  ],
+  output: { formatters: updateFormatters },
+  examples: [
+    { cmd: "pragma sources update", note: "resolve, build, and lock" },
+    {
+      cmd: "pragma sources update --frozen",
+      note: "reproduce the locked state",
+    },
+    {
+      cmd: "pragma sources update --skip-invalid",
+      note: "build from the parseable sources, warning about any dropped",
+    },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: true,
+    needsNetwork: true,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: false, openWorldHint: true },
+    },
+  },
+  // `run` really returns `Promise<Task<R>>`: `buildUpdateTask` awaits config
+  // (and, on a real execution, resolves + builds) before handing back the
+  // lock-writing Task — or, when `runtime.mutation.preview` is set, a
+  // network-free plan Task. The dispatcher and MCP handler both `await` this
+  // promise into a `Task`. The `VerbSpec.run` union is deliberately two-armed
+  // (`Promise<R> | Task<R>`) — a third `Promise<Task<R>>` arm would poison async
+  // read-verb inference — so the awaited-away Promise is presented through the
+  // `Task<R>` arm by this single, honest cast.
+  run: (params, runtime) =>
+    import("./runUpdate.js").then((module) =>
+      module.buildUpdateTask(
+        runtime,
+        params.frozen === true,
+        params.skipInvalid === true,
+      ),
+    ) as unknown as Task<SourcesUpdateData>,
+};

package/src/capabilities/standard/index.ts

@@ -0,0 +1,18 @@
+/**
+ * The `standard` capability module — the bundled pack compiled to verbs.
+ *
+ * Compiled at import (fast-path safe: compilePack is pure/zod-free) so the module
+ * is surface-deterministic. A config/package story for `standard` overrides it at
+ * dispatch (see kernel/packs/collect).
+ */
+
+import { compilePack } from "../../kernel/packs/compile.js";
+import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { standardPack } from "./pack.js";
+
+/** The `standard` capability module (list, categories, lookup, sample). */
+export const standardModule: CapabilityModule = {
+  name: "standard",
+  verbs: compilePack(standardPack, "bundled:standard", DEFAULT_PREFIX_MAP),
+};

package/src/capabilities/standard/pack.ts

@@ -0,0 +1,128 @@
+/**
+ * The bundled `standard` pack — code standards as data.
+ *
+ * `standard list|lookup|categories|sample` compile from this definition through
+ * the one pack kernel. Normalized for v2: the old `digest` level is renamed to
+ * the canonical `standard`, so disclosure gates by the canonical index; the
+ * default is `summary` (base fields by name), `--detail standard` adds the `dos`
+ * examples, `--detail detailed` adds `donts`. `cs:extends` stays the raw IRI in
+ * JSON (renderers compact it at display time).
+ */
+
+import type { PackDefinition } from "../../kernel/packs/types.js";
+
+export const standardPack: PackDefinition = {
+  noun: "standard",
+  description: "List all code standards.",
+  toolDescription:
+    "List code standards. Optionally filter by category or search term.",
+  list: {
+    query: [
+      "SELECT ?uri ?name ?category ?description",
+      "WHERE {",
+      "  ?uri a cs:CodeStandard ;",
+      "       cs:description ?description .",
+      "  OPTIONAL { ?uri cs:name ?n . }",
+      '  BIND(COALESCE(?n, REPLACE(STRAFTER(STR(?uri), "#"), "\\\\.", "/")) AS ?name)',
+      "  OPTIONAL {",
+      "    ?uri cs:hasCategory ?cat .",
+      "    ?cat cs:slug ?category .",
+      "  }",
+      "}",
+      "ORDER BY ?name",
+    ].join("\n"),
+    columns: [
+      { field: "uri", label: "IRI" },
+      { field: "name", label: "Name" },
+      { field: "category", label: "Category" },
+      { field: "description", label: "Description" },
+    ],
+    filters: [
+      {
+        param: "category",
+        variable: "category",
+        description: "Filter by category name.",
+      },
+    ],
+    search: {
+      variables: ["name", "description"],
+      description: "Search in name and description.",
+    },
+  },
+  verbs: [
+    {
+      verb: "categories",
+      description: "List all standard categories with counts.",
+      toolDescription: "List all code standard categories.",
+      query: [
+        "SELECT ?name (COUNT(?standard) AS ?count)",
+        "WHERE {",
+        "  ?cat a cs:Category ;",
+        "       cs:slug ?name .",
+        "  OPTIONAL {",
+        "    ?standard a cs:CodeStandard ;",
+        "              cs:hasCategory ?cat .",
+        "  }",
+        "}",
+        "GROUP BY ?name",
+        "ORDER BY ?name",
+      ].join("\n"),
+      columns: [
+        { field: "name", label: "Category" },
+        { field: "count", label: "Standards" },
+      ],
+    },
+  ],
+  lookup: {
+    source: "sparql",
+    by: "cs:name",
+    type: "cs:CodeStandard",
+    description:
+      "Look up detailed information for a standard by name, IRI, or glob.",
+    toolDescription:
+      "Get detailed information about one or more code standards including dos and donts with code examples. Address standards by name, prefixed name (cs:…), absolute IRI, or glob pattern (react/component/*).",
+    fields: [
+      {
+        name: "category",
+        property: "cs:hasCategory/cs:slug",
+        label: "Category",
+      },
+      { name: "description", property: "cs:description", label: "Description" },
+      { name: "extends", property: "cs:extends", label: "Extends" },
+    ],
+    expand: [
+      {
+        name: "dos",
+        heading: "Do",
+        relation: "cs:do",
+        select: [
+          { name: "caption", property: "cs:description" },
+          { name: "language", property: "cs:language" },
+          { name: "code", property: "cs:code" },
+        ],
+        level: "standard",
+      },
+      {
+        name: "donts",
+        heading: "Don't",
+        relation: "cs:dont",
+        select: [
+          { name: "caption", property: "cs:description" },
+          { name: "language", property: "cs:language" },
+          { name: "code", property: "cs:code" },
+        ],
+        level: "detailed",
+      },
+    ],
+    disclosure: {
+      levels: ["summary", "standard", "detailed"],
+      default: "summary",
+    },
+    sample: {
+      description:
+        "Return randomly selected complete standard instances as exemplars for shape discovery.",
+      toolDescription:
+        "Return 1–5 randomly selected complete code standard instances as exemplars. Use BEFORE writing queries to see actual data shapes, property names, and value formats. Each call returns different instances.",
+    },
+  },
+};