@canonical/pragma-cli 0.31.0 → 0.32.0

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.",
+    },
+  },
+};

package/src/capabilities/standard/parity.test.ts

@@ -0,0 +1,208 @@
+/**
+ * Standard-noun semantic parity (PROTECTED) — the bundled `standard` pack over a
+ * code-standards fixture graph.
+ *
+ * The hand-written standard domain is gone, so parity is asserted directly
+ * against the graph: every standard is reachable through list/lookup/categories/
+ * sample with the same names and values, addressable by name, prefixed name, and
+ * IRI, with the canonical disclosure levels (summary → base, `standard` → dos,
+ * `detailed` → dos + donts). `cs:extends` stays the raw IRI in data.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { compilePack } from "../../kernel/packs/compile.js";
+import type { LookupOutput } from "../../kernel/packs/resolveEntity.js";
+import { parsePackDefinition } from "../../kernel/packs/schema.js";
+import type { PackRow } from "../../kernel/packs/types.js";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import { standardPack } from "./pack.js";
+
+const CS = "http://pragma.canonical.com/codestandards#";
+const PREFIXES = {
+  cs: CS,
+  owl: "http://www.w3.org/2002/07/owl#",
+  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+  xsd: "http://www.w3.org/2001/XMLSchema#",
+};
+
+const TTL = `
+@prefix cs: <${CS}> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+cs:CodeStandard a owl:Class .
+cs:Category a owl:Class .
+cs:Example a owl:Class .
+cs:name a owl:DatatypeProperty ; rdfs:domain cs:CodeStandard ; rdfs:range xsd:string .
+cs:description a owl:DatatypeProperty ; rdfs:range xsd:string .
+cs:hasCategory a owl:ObjectProperty ; rdfs:domain cs:CodeStandard ; rdfs:range cs:Category .
+cs:slug a owl:DatatypeProperty ; rdfs:domain cs:Category ; rdfs:range xsd:string .
+cs:extends a owl:ObjectProperty ; rdfs:domain cs:CodeStandard ; rdfs:range cs:CodeStandard .
+cs:do a owl:ObjectProperty ; rdfs:domain cs:CodeStandard ; rdfs:range cs:Example .
+cs:dont a owl:ObjectProperty ; rdfs:domain cs:CodeStandard ; rdfs:range cs:Example .
+cs:language a owl:DatatypeProperty ; rdfs:domain cs:Example ; rdfs:range xsd:string .
+cs:code a owl:DatatypeProperty ; rdfs:domain cs:Example ; rdfs:range xsd:string .
+
+cs:cat.react a cs:Category ; cs:slug "react" .
+cs:cat.code a cs:Category ; cs:slug "code" .
+
+cs:react.component.props a cs:CodeStandard ;
+  cs:name "react/component/props" ;
+  cs:description "Type component props explicitly." ;
+  cs:hasCategory cs:cat.react ;
+  cs:do [ a cs:Example ; cs:description "Do type props" ; cs:language "tsx" ; cs:code "interface P {}" ] ;
+  cs:dont [ a cs:Example ; cs:description "Avoid any" ; cs:language "tsx" ; cs:code "props: any" ] .
+
+cs:react.component.structure a cs:CodeStandard ;
+  cs:name "react/component/structure" ;
+  cs:description "Keep folder structure flat." ;
+  cs:hasCategory cs:cat.react ;
+  cs:extends cs:react.component.props ;
+  cs:do [ a cs:Example ; cs:description "Do flatten" ; cs:language "text" ; cs:code "src/Button.tsx" ] .
+
+cs:code.function.purity a cs:CodeStandard ;
+  cs:name "code/function/purity" ;
+  cs:description "Prefer pure functions." ;
+  cs:hasCategory cs:cat.code .
+`;
+
+const verbs = () =>
+  compilePack(standardPack, "bundled:standard", DEFAULT_PREFIX_MAP);
+const verb = (label: string) =>
+  verbs().find((v) => verbKey(v.path) === `standard ${label}`) as VerbSpec;
+
+let rt: PragmaRuntime;
+beforeAll(async () => {
+  ({ rt } = await buildFixtureRuntime({ ttl: TTL, prefixes: PREFIXES }));
+});
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+async function lookupAt(
+  name: string,
+  detail?: "summary" | "standard" | "detailed",
+): Promise<Record<string, unknown>> {
+  const runtime = detail
+    ? { ...rt, globalFlags: { ...rt.globalFlags, detail } }
+    : rt;
+  const out = (await verb("lookup").run(
+    { name: [name] },
+    runtime,
+  )) as LookupOutput;
+  return out.results.at(0) as Record<string, unknown>;
+}
+
+describe("standard pack definition (PROTECTED)", () => {
+  it("round-trips as declarative JSON and validates", () => {
+    expect(
+      parsePackDefinition(JSON.parse(JSON.stringify(standardPack)), "t"),
+    ).toEqual(standardPack);
+  });
+});
+
+describe("standard list parity", () => {
+  it("lists every standard with the uniform row shape", async () => {
+    const rows = (await verb("list").run({}, rt)) as PackRow[];
+    expect(rows.map((r) => r.name)).toEqual([
+      "code/function/purity",
+      "react/component/props",
+      "react/component/structure",
+    ]);
+    for (const row of rows) {
+      expect(row.uri).toBeTruthy();
+      expect(row.description).toBeTruthy();
+    }
+  });
+
+  it("filters by category and searches, conjunctively", async () => {
+    const react = (await verb("list").run(
+      { category: "react" },
+      rt,
+    )) as PackRow[];
+    expect(react.map((r) => r.name).sort()).toEqual([
+      "react/component/props",
+      "react/component/structure",
+    ]);
+    const searched = (await verb("list").run(
+      { category: "react", search: "structure" },
+      rt,
+    )) as PackRow[];
+    expect(searched.map((r) => r.name)).toEqual(["react/component/structure"]);
+  });
+});
+
+describe("standard categories parity", () => {
+  it("lists categories with their standard counts", async () => {
+    const rows = (await verb("categories").run({}, rt)) as PackRow[];
+    const counts = new Map(rows.map((r) => [r.name, Number(r.count)]));
+    expect(counts.get("react")).toBe(2);
+    expect(counts.get("code")).toBe(1);
+  });
+});
+
+describe("standard lookup parity — canonical disclosure", () => {
+  it("summary resolves base fields, no dos/donts", async () => {
+    const entity = await lookupAt("react/component/props", "summary");
+    expect(entity.name).toBe("react/component/props");
+    expect(entity.category).toBe("react");
+    expect(entity.description).toBe("Type component props explicitly.");
+    expect(entity.dos).toBeUndefined();
+    expect(entity.donts).toBeUndefined();
+  });
+
+  it("standard fetches dos; detailed fetches dos AND donts", async () => {
+    const atStandard = await lookupAt("react/component/props", "standard");
+    expect((atStandard.dos as unknown[]).length).toBeGreaterThan(0);
+    expect(atStandard.donts).toBeUndefined();
+
+    const atDetailed = await lookupAt("react/component/props", "detailed");
+    expect((atDetailed.dos as { code: string }[])[0]?.code).toBe(
+      "interface P {}",
+    );
+    expect((atDetailed.donts as { caption: string }[])[0]?.caption).toBe(
+      "Avoid any",
+    );
+  });
+
+  it("keeps cs:extends as the raw IRI in data", async () => {
+    const entity = await lookupAt("react/component/structure");
+    expect(entity.extends).toBe(`${CS}react.component.props`);
+  });
+
+  it("resolves the same entity by name and by prefixed name", async () => {
+    const byName = await lookupAt("react/component/props");
+    const byPrefixed = await lookupAt("cs:react.component.props");
+    expect(byPrefixed.name).toBe(byName.name);
+  });
+
+  it("expands globs and reports misses with suggestions", async () => {
+    const out = (await verb("lookup").run(
+      { name: ["react/component/*"] },
+      rt,
+    )) as LookupOutput;
+    expect(out.results.map((e) => e.name).sort()).toEqual([
+      "react/component/props",
+      "react/component/structure",
+    ]);
+    await expect(
+      verb("lookup").run({ name: ["react/component/prop"] }, rt),
+    ).rejects.toThrow(/not found/i);
+  });
+});
+
+describe("standard sample parity", () => {
+  it("returns N full exemplars with the population size", async () => {
+    const data = (await verb("sample").run({ count: "2" }, rt)) as {
+      samples: unknown[];
+      totalCount: number;
+    };
+    expect(data.samples).toHaveLength(2);
+    expect(data.totalCount).toBe(3);
+  });
+});