@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/capabilities/tier/lookup.verb.ts

@@ -1,44 +0,0 @@
-/**
- * `tier lookup <name>` — the covenant `tier_lookup` tool.
- *
- * Bespoke store-backed lookup with a SINGLE `<name>` positional (a pack lookup
- * would emit the variadic `<name...>`), so it emits
- * `{ v: "lookup", args: ["<name>"], needsStore: true, mcp: "tier_lookup" }`.
- */
-
-import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
-import { type TierLookupData, tierLookupFormatters } from "./lookup.render.js";
-
-const tierLookupSpec: VerbSpec<Record<string, unknown>, TierLookupData> = {
-  path: ["tier", "lookup"],
-  summary: "Show one tier by name, with the blocks scoped to it.",
-  doc: "Look up a single tier by its name (e.g. apps/lxd) and list the blocks scoped directly to it.",
-  params: [
-    {
-      kind: "string",
-      name: "name",
-      doc: "The tier name (e.g. apps/lxd).",
-      positional: true,
-      required: true,
-      complete: { kind: "names", source: { from: "tiers" } },
-    },
-  ],
-  output: { formatters: tierLookupFormatters },
-  examples: [{ cmd: "pragma tier lookup apps/lxd" }],
-  capability: {
-    needsStore: true,
-    mutates: false,
-    mcp: {
-      expose: true,
-      annotations: { readOnlyHint: true, openWorldHint: false },
-    },
-  },
-  run: (params, rt) =>
-    import("./runLookup.js").then((m) =>
-      m.runTierLookup(rt, String(params.name)),
-    ),
-};
-
-/** The `tier lookup` verb, widened for registry composition. */
-export const tierLookupVerb = asVerb(tierLookupSpec);

package/src/capabilities/tier/pack.ts

@@ -1,28 +0,0 @@
-/**
- * The bundled `tier` pack — a flat, name-ordered list story.
- *
- * Tier hierarchy is encoded in the slash-separated path string (`apps/lxd`), not
- * in graph edges, so `tier list` is a flat list; the ordered-inheritance logic
- * lives in the block list's tier chain. SPARQL-sourced (a flat-ordered list).
- */
-
-import type { PackDefinition } from "../../kernel/packs/types.js";
-
-export const tierPack: PackDefinition = {
-  noun: "tier",
-  description: "List all tiers in the design system ontology.",
-  toolDescription:
-    "List all tiers in the design-system ontology. Use when understanding the tier hierarchy before setting a tier filter. Example: tier_list {}.",
-  list: {
-    query: [
-      "SELECT ?uri ?name WHERE {",
-      "  ?uri a ds:Tier ;",
-      "       ds:name ?name .",
-      "} ORDER BY ?name",
-    ].join("\n"),
-    columns: [
-      { field: "uri", label: "IRI" },
-      { field: "name", label: "Name" },
-    ],
-  },
-};

package/src/capabilities/tier/runLookup.ts

@@ -1,59 +0,0 @@
-/**
- * The `tier lookup` run body (lazily imported, off the fast path).
- *
- * Bespoke (not a pack lookup): the covenant freezes `tier_lookup` with a SINGLE
- * `<name>` positional, whereas a pack lookup emits the variadic `<name...>`.
- * Resolves the tier by its `ds:name` and returns the blocks scoped directly to
- * it (a joined OPTIONAL, so a tier with no direct members still resolves).
- */
-
-import { PragmaError } from "../../kernel/error/PragmaError.js";
-import { runSelect } from "../../kernel/packs/sparql/runSelect.js";
-import { compactUri } from "../../kernel/render/compactUri.js";
-import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
-import type { TierLookupData } from "./lookup.render.js";
-
-/**
- * Look up one tier by name.
- *
- * @param rt - The runtime (its store is booted by the projector for needsStore).
- * @param name - The tier name (its `ds:name`, e.g. `apps/lxd`).
- * @returns The tier's IRI, name, and directly-scoped block names.
- * @throws PragmaError ENTITY_NOT_FOUND when no tier has that name;
- *   STORE_UNAVAILABLE (exit 3) when the store is unseeded for this project.
- */
-export async function runTierLookup(
-  rt: PragmaRuntime,
-  name: string,
-): Promise<TierLookupData> {
-  const query = [
-    "SELECT ?uri ?blockName WHERE {",
-    "  ?uri a ds:Tier ; ds:name ?tierName .",
-    `  FILTER(STR(?tierName) = ${JSON.stringify(name)})`,
-    "  OPTIONAL { ?block ds:tier ?uri ; ds:name ?blockName }",
-    "}",
-    "ORDER BY ?blockName",
-  ].join("\n");
-
-  // Route through `runSelect` (not `rt.query.sparql` directly) so a cold/unseeded
-  // store — a generated `ds:` query hitting an unknown prefix — is remapped to an
-  // actionable STORE_UNAVAILABLE with `pragma sources update` recovery, instead of
-  // a raw "Prefix not found" collapsing to INTERNAL_ERROR at the boundary.
-  const rows = await runSelect(rt, query, "tier");
-  const uri = rows[0]?.uri;
-  if (!uri) {
-    throw PragmaError.notFound("tier", name, {
-      recovery: {
-        message: "List available tiers.",
-        cli: "pragma tier list",
-        mcp: { tool: "tier_list" },
-      },
-    });
-  }
-  const blocks = rows
-    // `blockName` rides an OPTIONAL, so the key is absent for a memberless tier.
-    .map((row) => row.blockName as string | undefined)
-    .filter((block): block is string => Boolean(block));
-  return { uri: compactUri(uri, DEFAULT_PREFIX_MAP), name, blocks };
-}

package/src/capabilities/token/addConfig.render.ts

@@ -1,27 +0,0 @@
-/**
- * Formatters for `token add-config` — plain, llm, json.
- */
-
-import type { Formatters } from "../../kernel/spec/types.js";
-import type { AddConfigResult } from "./runAddConfig.js";
-
-export const addConfigFormatters: Formatters<AddConfigResult> = {
-  plain(data) {
-    const lines = [
-      `${data.alreadyExisted ? "Updated" : "Wrote"} ${data.path}`,
-      `  ${data.tokenCount} token${data.tokenCount === 1 ? "" : "s"} in the active graph`,
-      `  sources: ${data.sources.join(", ")}`,
-    ];
-    return lines.join("\n");
-  },
-  llm(data) {
-    return [
-      `${data.alreadyExisted ? "Updated" : "Wrote"} \`${data.path}\` for the terrazzo token pipeline.`,
-      `- ${data.tokenCount} token(s) in the active graph`,
-      `- sources: ${data.sources.map((source) => `\`${source}\``).join(", ")}`,
-    ].join("\n");
-  },
-  json(data) {
-    return JSON.stringify(data);
-  },
-};

package/src/capabilities/token/addConfig.test.ts

@@ -1,62 +0,0 @@
-import { existsSync, readFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
-import { CANONICAL_TTL } from "../../testing/fixtures/graph/canonical.js";
-import {
-  bootFixtureRuntime,
-  type FixtureGraph,
-} from "../../testing/helpers/fixtureGraph.js";
-import type { McpHarness } from "../../testing/helpers/projectMcp.js";
-import { projectMcp } from "../../testing/helpers/projectMcp.js";
-import { capabilities } from "../index.js";
-
-let fixture: FixtureGraph;
-let mcp: McpHarness;
-let configPath: string;
-
-beforeAll(async () => {
-  fixture = await bootFixtureRuntime({ ttl: CANONICAL_TTL });
-  mcp = await projectMcp(capabilities, fixture.cwd);
-  configPath = join(fixture.cwd, "tokens.config.mjs");
-});
-
-afterAll(async () => {
-  await mcp.cleanup();
-  await fixture.dispose();
-});
-
-beforeEach(() => {
-  rmSync(configPath, { force: true });
-});
-
-describe("token_add-config — plan-first mutation (PROTECTED)", () => {
-  it("without confirm, returns a plan and writes NOTHING", async () => {
-    const result = await mcp.callTool("token_add-config");
-    expect(result.ok).toBe(true);
-    const meta = result.meta as {
-      planOnly?: boolean;
-      confirmRequired?: boolean;
-    };
-    expect(meta.planOnly).toBe(true);
-    expect(meta.confirmRequired).toBe(true);
-    const data = result.data as { plan: string[] };
-    expect(data.plan.join("\n")).toMatch(/tokens\.config\.mjs/);
-    expect(existsSync(configPath)).toBe(false);
-  });
-
-  it("with confirm, writes a terrazzo config reflecting the store token count", async () => {
-    const result = await mcp.callTool("token_add-config", { confirm: true });
-    expect(result.ok).toBe(true);
-    const data = result.data as {
-      path: string;
-      tokenCount: number;
-      sources: string[];
-    };
-    expect(existsSync(configPath)).toBe(true);
-    // The canonical fixture holds 2 ds:Token entities.
-    expect(data.tokenCount).toBe(2);
-    const written = readFileSync(configPath, "utf-8");
-    expect(written).toContain("defineConfig");
-    expect(written).toContain("@canonical/terrazzo");
-  });
-});

package/src/capabilities/token/addConfig.verb.ts

@@ -1,40 +0,0 @@
-/**
- * `token add-config` — generate a terrazzo `tokens.config.mjs` (the one `token`
- * mutation). Store-backed (needsStore, per covenant) so it can report the token
- * count; plan-first through the uniform mutation seam (a tool call without
- * `confirm` returns the write plan; `--dry-run`/`--yes` on the CLI). No params —
- * the covenant emits `{ v: "add-config", mutates: true, needsStore: true }`.
- */
-
-import type { Task } from "@canonical/task";
-import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
-import { addConfigFormatters } from "./addConfig.render.js";
-import type { AddConfigResult } from "./runAddConfig.js";
-
-const addConfigVerb: VerbSpec<Record<string, unknown>, AddConfigResult> = {
-  path: ["token", "add-config"],
-  summary: "Generate a tokens.config.mjs for the terrazzo token pipeline.",
-  doc: "Writes a terrazzo `defineConfig` at the project root, sourcing token JSON from the configured design-system packages. Store-backed so it reports how many tokens the active graph holds. Plan-first: returns the write plan until you confirm.",
-  params: [],
-  output: { formatters: addConfigFormatters },
-  examples: [
-    { cmd: "pragma token add-config --dry-run", note: "preview the write" },
-    { cmd: "pragma token add-config --yes", note: "write the config" },
-  ],
-  capability: {
-    needsStore: true,
-    mutates: true,
-    mcp: {
-      expose: true,
-      annotations: { readOnlyHint: false, openWorldHint: false },
-    },
-  },
-  run: (_params, rt) =>
-    import("./runAddConfig.js").then((m) =>
-      m.runAddConfig(rt),
-    ) as unknown as Task<AddConfigResult>,
-};
-
-/** The `token add-config` verb, widened for registry composition. */
-export const tokenAddConfigVerb = asVerb(addConfigVerb);

package/src/capabilities/token/index.ts

@@ -1,19 +0,0 @@
-/**
- * The `token` capability module — the bundled SPARQL pack compiled to verbs.
- */
-
-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 { tokenAddConfigVerb } from "./addConfig.verb.js";
-import { tokenPack } from "./pack.js";
-
-/** The `token` capability module — the bundled read pack plus the `add-config`
- * mutation (hand-written; the pack compiler emits reads only). */
-export const tokenModule: CapabilityModule = {
-  name: "token",
-  verbs: [
-    ...compilePack(tokenPack, "bundled:token", DEFAULT_PREFIX_MAP),
-    tokenAddConfigVerb,
-  ],
-};

package/src/capabilities/token/pack.ts

@@ -1,58 +0,0 @@
-/**
- * The bundled `token` pack — design tokens as data.
- *
- * SPARQL-sourced on both verbs: there is no `ds:Token` GraphQL type to project
- * against when the graph ships no tokens, and the lookup reads a property path
- * (`ds:tokenType/rdfs:label`) only SPARQL can express. `token add-config` (a
- * mutation) is out of PR3; the `emptyRecovery` install hint is the story users
- * see on an empty store.
- */
-
-import type { PackDefinition } from "../../kernel/packs/types.js";
-
-export const tokenPack: PackDefinition = {
-  noun: "token",
-  description: "List all design tokens.",
-  toolDescription:
-    "List all design tokens with their type. Use when browsing which tokens exist under the active scope. Example: token_list {}.",
-  list: {
-    query: [
-      "SELECT ?uri ?name ?category WHERE {",
-      "  ?uri a ds:Token ;",
-      "       ds:tokenId ?name .",
-      "  OPTIONAL {",
-      "    ?uri ds:tokenType ?type .",
-      "    ?type rdfs:label ?category .",
-      "  }",
-      "}",
-      "ORDER BY ?name",
-    ].join("\n"),
-    columns: [
-      { field: "uri", label: "IRI" },
-      { field: "name", label: "Name" },
-      { field: "category", label: "Type" },
-    ],
-    emptyRecovery: {
-      message:
-        "No tokens in the store. Build it from the configured design-system packages.",
-      cli: "pragma sources update",
-    },
-  },
-  lookup: {
-    source: "sparql",
-    by: "ds:tokenId",
-    type: "ds:Token",
-    toolDescription:
-      'Get type and theme values for one or more design tokens by name. Use when resolving specific tokens\' light/dark values. Example: token_lookup { names: ["color.primary"] }.',
-    fields: [
-      { name: "category", property: "ds:tokenType/rdfs:label", label: "Type" },
-      { name: "valueLight", property: "ds:valueLight", label: "Light value" },
-      { name: "valueDark", property: "ds:valueDark", label: "Dark value" },
-    ],
-    sample: {
-      fixedCount: true,
-      toolDescription:
-        "Return randomly selected complete design tokens (with theme values) as exemplars. Use BEFORE writing queries to see actual data shapes.",
-    },
-  },
-};

package/src/capabilities/token/runAddConfig.ts

@@ -1,95 +0,0 @@
-/**
- * The `token add-config` write body (lazily imported, off the fast path).
- *
- * A store-backed mutation: it counts the design tokens in the active graph (so
- * the plan reports how many tokens the config will cover) and derives the
- * terrazzo token-source globs from the configured design-system packages, then
- * returns a Task that writes `tokens.config.mjs`. The store read happens in the
- * async setup; the file write is the Task's single `WriteFile` effect, so a
- * plan-only preview (`mutation.preview`) describes the write without performing
- * it. Ported from the old shell's `token add-config` (terrazzo `defineConfig`).
- */
-
-import { resolve } from "node:path";
-import { $, exists, gen, type Task, writeFile } from "@canonical/task";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
-
-/** The default token source when no design-system packages are configured. */
-const DEFAULT_TOKEN_SOURCE =
-  "node_modules/@canonical/ds-global/tokens/**/*.json";
-
-/** The result of generating a terrazzo tokens config. */
-export interface AddConfigResult {
-  /** The absolute path written. */
-  readonly path: string;
-  /** How many `ds:Token` entities the active graph holds. */
-  readonly tokenCount: number;
-  /** The token-source globs written into the config. */
-  readonly sources: readonly string[];
-  /** Whether a `tokens.config.mjs` already existed (it is overwritten). */
-  readonly alreadyExisted: boolean;
-}
-
-/** Count the `ds:Token` entities in the booted store (best-effort). */
-async function countTokens(rt: PragmaRuntime): Promise<number> {
-  try {
-    const result = (await rt.query.sparql(
-      "SELECT (COUNT(DISTINCT ?token) AS ?count) WHERE { ?token a ds:Token }",
-    )) as { type?: string; bindings?: { count?: string }[] };
-    const raw = result.bindings?.[0]?.count;
-    return raw ? Number(raw) : 0;
-  } catch {
-    return 0;
-  }
-}
-
-/** Derive the terrazzo token-source globs from the configured packages. */
-async function resolveSources(rt: PragmaRuntime): Promise<string[]> {
-  const { config } = await rt.loadConfig();
-  const packages = config.packages ?? [];
-  if (packages.length === 0) return [DEFAULT_TOKEN_SOURCE];
-  return packages.map((pkg) => {
-    const name = typeof pkg === "string" ? pkg : pkg.name;
-    return `node_modules/${name}/tokens/**/*.json`;
-  });
-}
-
-/** Render the terrazzo `tokens.config.mjs` content. */
-function generateConfig(sources: readonly string[]): string {
-  const sourceList = sources
-    .map((source) => `    ${JSON.stringify(source)}`)
-    .join(",\n");
-  return `// tokens.config.mjs — generated by \`pragma token add-config\`
-import { defineConfig } from "@canonical/terrazzo";
-
-export default defineConfig({
-  tokens: [
-${sourceList},
-  ],
-  outDir: "./tokens/",
-  plugins: [],
-});
-`;
-}
-
-/**
- * Build the Task that writes `tokens.config.mjs` for the terrazzo pipeline.
- *
- * @param rt - The runtime (its store is booted by the projector for needsStore).
- * @returns A Task yielding the write outcome.
- * @note Impure — reads the store + config; the write is the Task's effect.
- */
-export async function runAddConfig(
-  rt: PragmaRuntime,
-): Promise<Task<AddConfigResult>> {
-  const tokenCount = await countTokens(rt);
-  const sources = await resolveSources(rt);
-  const path = resolve(rt.cwd, "tokens.config.mjs");
-  const content = generateConfig(sources);
-
-  return gen(function* () {
-    const alreadyExisted = yield* $(exists(path));
-    yield* $(writeFile(path, content));
-    return { path, tokenCount, sources, alreadyExisted };
-  });
-}

package/src/kernel/completion/bashDrive.test.ts

@@ -1,73 +0,0 @@
-import { spawnSync } from "node:child_process";
-import { mkdtempSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import { completionFixture } from "../../testing/fixtures/completionFixture.js";
-import { emitScripts } from "./emitScripts.js";
-
-/**
- * M1 regression: the generated bash script must complete the `--flag=value`
- * wordbreak form. With `=` in COMP_WORDBREAKS, bash splits `--format=` into
- * `--format` `=` `` (or `` after `=`); without the normalization at the top of
- * `_pragma`, the value slot falls through to the noun/positional arm and
- * offers the WRONG candidates. These tests drive the REAL bash to prove the
- * fix, so the static tier answers `--format=<TAB>` as a flag value with zero
- * exec (the resolver is only reached for `{kind:"entity"}` contexts).
- */
-
-/** Whether a usable bash is on PATH (the package pins os:["linux"], so it is). */
-const bashOk =
-  spawnSync("bash", ["-c", "printf ok"], { encoding: "utf-8" }).stdout === "ok";
-
-/** The bash completion script for the fixture grammar (has the global --format). */
-const script = emitScripts([completionFixture]).bash;
-
-/**
- * Source the generated script in a real bash, place the cursor per COMP_WORDS
- * / COMP_CWORD, invoke `_pragma`, and return COMPREPLY line-by-line.
- */
-function driveBash(words: readonly string[], cword: number): string[] {
-  const dir = mkdtempSync(join(tmpdir(), "pragma-bashdrive-"));
-  const file = join(dir, "completion.bash");
-  writeFileSync(file, script);
-  const wordsLiteral = words
-    .map((word) => `'${word.replace(/'/g, "'\\''")}'`)
-    .join(" ");
-  const driver = [
-    `source '${file}'`,
-    `COMP_WORDS=(${wordsLiteral})`,
-    `COMP_CWORD=${cword}`,
-    "_pragma",
-    `printf '%s\\n' "\${COMPREPLY[@]}"`,
-  ].join("\n");
-  const result = spawnSync("bash", ["--norc", "--noprofile", "-c", driver], {
-    encoding: "utf-8",
-  });
-  return result.stdout.split("\n").filter((line) => line.length > 0);
-}
-
-describe.skipIf(!bashOk)("generated bash — --flag=value wordbreak (M1)", () => {
-  it("routes --format=<TAB> to the format values (not nouns/positionals)", () => {
-    // Default COMP_WORDBREAKS split: `--format` `=` `` (empty current word).
-    const reply = driveBash(["pragma", "--format", "=", ""], 3);
-    expect(reply.sort()).toEqual(["json", "plain"]);
-  });
-
-  it("filters the value by the partial typed after =", () => {
-    const reply = driveBash(["pragma", "--format", "=", "j"], 3);
-    expect(reply).toEqual(["json"]);
-  });
-
-  it("routes a verb-scoped --format=<TAB> the same way", () => {
-    // After a noun/verb the value must still route as a flag value, never as
-    // block's positional (which would offer entity/enum candidates instead).
-    const reply = driveBash(["pragma", "block", "get", "--format", "=", ""], 5);
-    expect(reply.sort()).toEqual(["json", "plain"]);
-  });
-
-  it("still completes the space form --format <TAB> (unbroken)", () => {
-    const reply = driveBash(["pragma", "--format", ""], 2);
-    expect(reply.sort()).toEqual(["json", "plain"]);
-  });
-});

package/src/kernel/runtime/graphpack/embedded/sample.ttl

@@ -1,39 +0,0 @@
-# Embedded fallback pack source — a small, self-contained sample ontology.
-#
-# Compiled by `scripts/genEmbedded.ts` into `pack.generated.ts`. It exists so a
-# fresh install (no configured packages, no lock) can answer store-backed reads
-# without a network round-trip. Keep it tiny: it ships inside the binary.
-
-@prefix ex:   <https://pragma.canonical.com/sample#> .
-@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
-@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
-@prefix owl:  <http://www.w3.org/2002/07/owl#> .
-@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
-
-ex:Component a owl:Class ;
-  rdfs:label "Component" ;
-  rdfs:comment "A reusable design-system building block." .
-
-ex:componentName a owl:DatatypeProperty ;
-  rdfs:label "component name" ;
-  rdfs:domain ex:Component ;
-  rdfs:range xsd:string .
-
-ex:dependsOn a owl:ObjectProperty ;
-  rdfs:label "depends on" ;
-  rdfs:domain ex:Component ;
-  rdfs:range ex:Component .
-
-ex:Button a ex:Component ;
-  rdfs:label "Button" ;
-  ex:componentName "Button" .
-
-ex:Card a ex:Component ;
-  rdfs:label "Card" ;
-  ex:componentName "Card" ;
-  ex:dependsOn ex:Button .
-
-ex:Dialog a ex:Component ;
-  rdfs:label "Dialog" ;
-  ex:componentName "Dialog" ;
-  ex:dependsOn ex:Button , ex:Card .

package/src/kernel/runtime/lock.ts

@@ -1,90 +0,0 @@
-/**
- * The project lock — `pragma.lock.json`, committed at the project root.
- *
- * It pins the single combined pack the store boots from: `contentHash` names
- * the pack's cache directory, and `packs[]` records the resolved provenance of
- * every configured source (so `sources status` reports it and a `--frozen`
- * update re-resolves to exactly these commits). Serialization is canonical —
- * fixed field order, packs sorted by name, one trailing newline — so a
- * `--frozen` update that changes nothing rewrites a byte-identical file.
- *
- * Pure: zod + fs only, no store code, so both the storeless `sources status`
- * verb and the store-boot decision table read it without booting oxigraph.
- */
-
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { z } from "zod";
-import { lockPath } from "./paths.js";
-
-/** One resolved source's provenance in the lock. */
-export const lockPackageSchema = z.object({
-  /** Package name (config `packages` entry name / npm name). */
-  name: z.string(),
-  /** The config `packages` source ref, verbatim (e.g. `git+https://…#main`). */
-  source: z.string(),
-  /** The resolved commit / version / absolute path this ref pinned to. */
-  resolved: z.string(),
-  /** ISO timestamp the ref was resolved. */
-  resolvedAt: z.string(),
-});
-
-/** The lock document. */
-export const pragmaLockSchema = z.object({
-  version: z.literal(1),
-  /** The combined pack's content hash — names its cache directory. */
-  contentHash: z.string(),
-  packs: z.array(lockPackageSchema),
-});
-
-/** One resolved source's provenance in the lock. */
-export type PragmaLockPackage = z.infer<typeof lockPackageSchema>;
-/** The parsed lock document. */
-export type PragmaLock = z.infer<typeof pragmaLockSchema>;
-
-/**
- * Read and validate the lock for a working directory.
- *
- * @param cwd - The project directory.
- * @returns The parsed lock, or `undefined` when absent or invalid.
- * @note Impure — reads from disk.
- */
-export function readLock(cwd: string): PragmaLock | undefined {
-  const path = lockPath(cwd);
-  if (!existsSync(path)) return undefined;
-  try {
-    return pragmaLockSchema.parse(JSON.parse(readFileSync(path, "utf-8")));
-  } catch {
-    return undefined;
-  }
-}
-
-/** Serialize a lock canonically — stable field order, sorted packs, newline. */
-export function serializeLock(lock: PragmaLock): string {
-  const packs = [...lock.packs]
-    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
-    .map((pack) => ({
-      name: pack.name,
-      source: pack.source,
-      resolved: pack.resolved,
-      resolvedAt: pack.resolvedAt,
-    }));
-  return `${JSON.stringify(
-    { version: lock.version, contentHash: lock.contentHash, packs },
-    null,
-    2,
-  )}\n`;
-}
-
-/**
- * Write the lock for a working directory.
- *
- * @param cwd - The project directory.
- * @param lock - The lock to persist.
- * @returns The exact bytes written (for the write effect / assertions).
- * @note Impure — writes `pragma.lock.json`.
- */
-export function writeLock(cwd: string, lock: PragmaLock): string {
-  const content = serializeLock(lock);
-  writeFileSync(lockPath(cwd), content);
-  return content;
-}