@platforma-sdk/block-tools 2.10.13 → 2.10.15

package/src/structure/__tests__/root-catalog-bump.test.ts

@@ -0,0 +1,110 @@
+// The `onInitOrUpdate` frame in `rootCatalogBumpRules` resolves the SDK
+// catalog to npm latest. It must fire on `init` AND `--update-deps-only`,
+// but NOT on a default refresh; default-mode leaves are the inverse (fire
+// on init + default refresh, skipped under --update-deps-only). Mocked
+// registry — no network.
+
+import { describe, test, expect } from "vitest";
+import { parse as parseYaml } from "yaml";
+import { defineStructure, scope, fixed, text } from "../engine/api";
+import { rootCatalogBumpRules } from "../rules/root-catalog-bump";
+import { run as engineRun } from "../engine/runner";
+import { MemoryFileSystem } from "../engine/fs/memory";
+import { createRunContext } from "../engine/ctx";
+import type { BlockVars } from "../engine/api";
+
+const VARS: BlockVars = {
+  facadeName: "@platforma-open/test-org.demo",
+  baseName: "test-org.demo",
+  npmOrg: "@platforma-open",
+  orgScope: "test-org",
+  shortName: "demo",
+};
+
+// A normal-mode leaf (MARKER.txt) sits alongside the update-deps frame so
+// we can prove the two modes are mutually exclusive.
+const STRUCTURE = defineStructure(() => {
+  scope("root", () => {
+    fixed("MARKER.txt", text("marker\n"));
+  });
+  rootCatalogBumpRules();
+});
+
+const WORKSPACE_YAML = [
+  "packages:",
+  "  - .",
+  "catalog:",
+  "  '@platforma-sdk/model': 1.0.0",
+  "  '@milaboratories/ts-builder': 1.0.0",
+  "  lodash: 1.0.0",
+  "",
+].join("\n");
+
+function freshFs(): MemoryFileSystem {
+  return new MemoryFileSystem({ "pnpm-workspace.yaml": WORKSPACE_YAML });
+}
+
+function ctx(updateDepsOnly: boolean) {
+  return createRunContext({
+    blockVars: VARS,
+    modules: [{ scope: "root", name: VARS.facadeName, path: "" }],
+    isSdkInternal: false,
+    updateDepsOnly,
+    version: 1,
+    dryRun: false,
+  });
+}
+
+const MOCK_LATEST: Record<string, string> = {
+  "@platforma-sdk/model": "9.9.9",
+  "@milaboratories/ts-builder": "9.9.9",
+};
+const mockLookup = (name: string): string | undefined => MOCK_LATEST[name];
+
+describe("rootCatalogBumpRules mode split", () => {
+  test("default refresh: catalog untouched, default-mode leaf fires", async () => {
+    const fs = freshFs();
+    engineRun(STRUCTURE, fs, ctx(false), { registryLookup: mockLookup });
+
+    const cat = (parseYaml(fs.read("pnpm-workspace.yaml")) as { catalog: Record<string, string> })
+      .catalog;
+    expect(cat["@platforma-sdk/model"]).toBe("1.0.0");
+    expect(cat["@milaboratories/ts-builder"]).toBe("1.0.0");
+    // Default-mode leaf did fire.
+    expect(fs.exists("MARKER.txt")).toBe(true);
+  });
+
+  test("--update-deps-only: SDK catalog bumped, infra floor seeded, default-mode leaf skipped", async () => {
+    const fs = freshFs();
+    engineRun(STRUCTURE, fs, ctx(true), { registryLookup: mockLookup });
+
+    const cat = (parseYaml(fs.read("pnpm-workspace.yaml")) as { catalog: Record<string, string> })
+      .catalog;
+    // Present SDK keys refreshed to latest.
+    expect(cat["@platforma-sdk/model"]).toBe("9.9.9");
+    expect(cat["@milaboratories/ts-builder"]).toBe("9.9.9");
+    // standard infra-floor keys ABSENT from the on-disk catalog are
+    // SEEDED add-if-absent (no manual seed step needed).
+    expect(cat["shx"]).toBe("~0.4.0");
+    expect(cat["turbo"]).toBe("~2.8.11");
+    expect(cat["vitest"]).toBe("~4.0.18");
+    // Non-matching dep left alone.
+    expect(cat["lodash"]).toBe("1.0.0");
+    // Default-mode leaf was skipped in update-deps-only mode.
+    expect(fs.exists("MARKER.txt")).toBe(false);
+  });
+
+  test("init: SDK catalog bumped AND default-mode leaf fires", async () => {
+    const fs = freshFs();
+    engineRun(STRUCTURE, fs, ctx(false), { registryLookup: mockLookup, initMode: true });
+
+    const cat = (parseYaml(fs.read("pnpm-workspace.yaml")) as { catalog: Record<string, string> })
+      .catalog;
+    // onInitOrUpdate fired → SDK bumped.
+    expect(cat["@platforma-sdk/model"]).toBe("9.9.9");
+    expect(cat["@milaboratories/ts-builder"]).toBe("9.9.9");
+    expect(cat["lodash"]).toBe("1.0.0");
+    // Default-mode leaf also fired on init.
+    expect(fs.exists("MARKER.txt")).toBe(true);
+  });
+});

package/src/structure/__tests__/seed-disjointness.test.ts

@@ -0,0 +1,79 @@
+// Validation: a path cannot be declared as both `seed` and any
+// engine-managed primitive (`fixed` / `managed` / `scaffold`) within
+// the same scope.
+
+import { describe, expect, test } from "vitest";
+import { defineStructure, scope, seed, managed, fixed, scaffold, text, file } from "../engine/api";
+
+describe("seed/managed disjointness", () => {
+  test("seed + managed on same path throws", () => {
+    expect(() =>
+      defineStructure(() => {
+        scope("model", () => {
+          seed("src/index.ts", text("// seed\n"));
+          managed("src/index.ts", file("model/index.ts"), () => {});
+        });
+      }),
+    ).toThrow(/path 'src\/index\.ts'.*both seed and/);
+  });
+
+  test("seed + fixed on same path throws", () => {
+    expect(() =>
+      defineStructure(() => {
+        scope("ui", () => {
+          fixed("index.html", file("ui/index.html"));
+          seed("index.html", text("<!doctype html>\n"));
+        });
+      }),
+    ).toThrow(/path 'index\.html'.*both seed and/);
+  });
+
+  test("seed + scaffold on same path throws", () => {
+    expect(() =>
+      defineStructure(() => {
+        scope("workflow", () => {
+          scaffold("README.md", text("# seed README\n"));
+          seed("README.md", text("# seed README\n"));
+        });
+      }),
+    ).toThrow(/path 'README\.md'.*both seed and/);
+  });
+
+  test("seed on its own (no collision) is fine", () => {
+    expect(() =>
+      defineStructure(() => {
+        scope("model", () => {
+          seed("src/index.ts", text("// seed only\n"));
+        });
+      }),
+    ).not.toThrow();
+  });
+
+  test("fixed + managed on same path is fine (no seed)", () => {
+    // This is a structural mistake of a different kind (fixed and
+    // managed both write to the same path) but is NOT in scope of
+    // this validation — the seed disjointness rule is specifically
+    // about seed contracts. Other collisions surface at runtime.
+    expect(() =>
+      defineStructure(() => {
+        scope("model", () => {
+          fixed("same.json", text("a\n"));
+          managed("same.json", text("a\n"), () => {});
+        });
+      }),
+    ).not.toThrow();
+  });
+
+  test("seed and managed on DIFFERENT scopes with the same relative path is fine", () => {
+    expect(() =>
+      defineStructure(() => {
+        scope("model", () => {
+          seed("src/index.ts", text("// model seed\n"));
+        });
+        scope("ui", () => {
+          managed("src/index.ts", text("// ui managed\n"), () => {});
+        });
+      }),
+    ).not.toThrow();
+  });
+});

package/src/structure/cli/run-structure.ts

@@ -0,0 +1,89 @@
+// Shared driver for the `structure check` and `structure refresh`
+// oclif commands. Wraps DISCOVERY (discover-fs) + the engine runner for
+// one block path, handling the standalone vs `--sdk-internal` split, the
+// `--update-deps-only` registry prefetch, and the post-run recheck's
+// fresh re-discovery. Each block path is processed independently (no
+// cross-block state).
+
+import path from "node:path";
+import { NodeFileSystem } from "../engine/fs/node";
+import { NodeTemplateProvider } from "../engine/templates";
+import { run as engineRun, type Change } from "../engine/runner";
+import { discoverRunContext } from "../engine/discovery-fs";
+import { STRUCTURE } from "../structure-definition";
+import { matchesBumpPattern, buildRegistryLookupForNames } from "../engine/registry-client";
+import { SDK_CATALOG_PACKAGES } from "../rules/root-pnpm-workspace";
+
+export type StructureMode = "check" | "refresh";
+
+export type RunStructureInput = {
+  /** User-supplied block path (resolved against cwd). */
+  blockPath: string;
+  isSdkInternal: boolean;
+  updateDepsOnly: boolean;
+  mode: StructureMode;
+  /** `<block-tools>/src/structure/templates` (from oclif `config.root`). */
+  templatesRoot: string;
+  log: (msg: string) => void;
+};
+
+export type RunStructureResult = {
+  blockPath: string;
+  changes: Change[];
+};
+
+/** Resolve the registry lookup for `--update-deps-only`: prefetch npm
+ *  "latest" for the SDK catalog MEMBERSHIP list (`SDK_CATALOG_PACKAGES`),
+ *  not the on-disk catalog keys, so the sync `ensureCatalogLatest` builder
+ *  can SEED a standard SDK key the block does not yet carry — reading
+ *  the on-disk catalog could never resolve an absent key. Mirrors
+ *  the `runInit` prefetch. A network failure during prefetch propagates. */
+async function buildRegistryLookup(): Promise<(name: string) => string | undefined> {
+  // Every SDK_CATALOG_PACKAGES entry matches a bump pattern (enforced at
+  // load time in root-pnpm-workspace); filter defensively all the same.
+  const names = SDK_CATALOG_PACKAGES.filter(matchesBumpPattern);
+  return buildRegistryLookupForNames(names);
+}
+
+export async function runStructureForPath(input: RunStructureInput): Promise<RunStructureResult> {
+  const root = path.resolve(input.blockPath);
+  const dryRun = input.mode === "check";
+
+  const fs = new NodeFileSystem(root);
+  const templates = new NodeTemplateProvider(input.templatesRoot);
+
+  const ctx = discoverRunContext({
+    fs,
+    isSdkInternal: input.isSdkInternal,
+    updateDepsOnly: input.updateDepsOnly,
+    dryRun,
+  });
+
+  const registryLookup = input.updateDepsOnly ? await buildRegistryLookup() : undefined;
+
+  const result = engineRun(STRUCTURE, fs, ctx, {
+    templates,
+    registryLookup,
+    // Fresh re-discovery for the post-run recheck (default refresh only)
+    // — re-reads the just-written tree so a rename that shifted the
+    // module map is observed.
+    rediscover: () =>
+      discoverRunContext({
+        fs,
+        isSdkInternal: input.isSdkInternal,
+        updateDepsOnly: false,
+        dryRun: true,
+      }),
+  });
+
+  return { blockPath: input.blockPath, changes: result.changes };
+}
+
+/** One-line-per-change summary for CLI output. */
+export function formatChanges(blockPath: string, changes: Change[]): string {
+  if (changes.length === 0) return `  ${blockPath}: up to date (0 changes)`;
+  const lines = changes.map(
+    (c) => `    ${c.action.padEnd(6)} ${c.primitive.padEnd(8)} ${c.path} [${c.scope}]`,
+  );
+  return `  ${blockPath}: ${changes.length} change(s)\n${lines.join("\n")}`;
+}

package/src/structure/engine/__tests__/content-rules/active-state-guards.test.ts

@@ -0,0 +1,61 @@
+import { describe, test, expect } from "vitest";
+import {
+  ensureField,
+  ensureGitignoreEntries,
+  ensureCatalogVersion,
+  withManagedBody,
+  withManagedYaml,
+} from "../../content-rules";
+import { parseYaml } from "../../parsers/yaml";
+
+describe("active-state guards", () => {
+  test("JSON-only builder throws inside a YAML body", () => {
+    const doc = parseYaml("catalog: {}\n");
+    expect(() =>
+      withManagedYaml(doc, () => {
+        ensureField("type", "module");
+      }),
+    ).toThrow(/requires a JSON-managed body/);
+  });
+
+  test("YAML-only builder throws inside a JSON body", () => {
+    expect(() =>
+      withManagedBody({}, () => {
+        ensureCatalogVersion("yaml", "1.0.0");
+      }),
+    ).toThrow(/requires a YAML-managed body/);
+  });
+
+  test("lines-only builder throws inside a JSON body", () => {
+    expect(() =>
+      withManagedBody({}, () => {
+        ensureGitignoreEntries(["node_modules/"]);
+      }),
+    ).toThrow(/requires a lines-managed body/);
+  });
+
+  test("nested managed bodies are rejected", () => {
+    expect(() =>
+      withManagedBody({}, () => {
+        withManagedBody({}, () => {
+          ensureField("x", 1);
+        });
+      }),
+    ).toThrow(/Nested managed/);
+  });
+
+  test("builder called outside any body throws a clear message", () => {
+    expect(() => ensureCatalogVersion("y", "1")).toThrow(/only valid inside a managed/);
+  });
+
+  test("active state is reset after a body throws", () => {
+    expect(() =>
+      withManagedBody({}, () => {
+        throw new Error("boom");
+      }),
+    ).toThrow(/boom/);
+    // If the active state had leaked, the next call would think it's
+    // still inside a body.
+    expect(() => ensureField("x", 1)).toThrow(/only valid inside a managed/);
+  });
+});

package/src/structure/engine/__tests__/content-rules/catalog-pin.test.ts

@@ -0,0 +1,46 @@
+import { describe, test, expect } from "vitest";
+import { ensureCatalogVersion, pinCatalogTo, withManagedYaml } from "../../content-rules";
+import { parseYaml, stringifyYaml } from "../../parsers/yaml";
+
+describe("ensureCatalogVersion (add-if-absent) / pinCatalogTo (set-exact)", () => {
+  test("ensureCatalogVersion leaves a present entry untouched (no-downgrade)", () => {
+    const doc = parseYaml("catalog:\n  yaml: 2.5.0\n");
+    // A version is already present — add-if-absent must NOT overwrite or
+    // downgrade it.
+    withManagedYaml(doc, () => ensureCatalogVersion("yaml", "2.6.0"));
+    expect((doc.toJSON() as { catalog: Record<string, string> }).catalog.yaml).toBe("2.5.0");
+  });
+
+  test("ensureCatalogVersion creates the entry if missing", () => {
+    const doc = parseYaml("catalog: {}\n");
+    withManagedYaml(doc, () => ensureCatalogVersion("yaml", "2.5.0"));
+    expect((doc.toJSON() as { catalog: Record<string, string> }).catalog.yaml).toBe("2.5.0");
+  });
+
+  test("pinCatalogTo overwrites a present entry (set-exact, downgrade-capable)", () => {
+    const doc = parseYaml("catalog:\n  yaml: 2.5.0\n");
+    withManagedYaml(doc, () => pinCatalogTo("yaml", "3.0.0"));
+    expect((doc.toJSON() as { catalog: Record<string, string> }).catalog.yaml).toBe("3.0.0");
+  });
+
+  test("pinCatalogTo creates the entry if missing", () => {
+    const doc = parseYaml("catalog: {}\n");
+    withManagedYaml(doc, () => pinCatalogTo("yaml", "1.2.3"));
+    expect((doc.toJSON() as { catalog: Record<string, string> }).catalog.yaml).toBe("1.2.3");
+  });
+
+  test("idempotent — double-run produces deep-equal output", () => {
+    const doc = parseYaml("catalog:\n  a: 1.0.0\n  b: 2.0.0\n");
+    withManagedYaml(doc, () => {
+      ensureCatalogVersion("a", "1.5.0");
+      ensureCatalogVersion("b", "2.1.0");
+    });
+    const once = stringifyYaml(doc);
+    withManagedYaml(doc, () => {
+      ensureCatalogVersion("a", "1.5.0");
+      ensureCatalogVersion("b", "2.1.0");
+    });
+    const twice = stringifyYaml(doc);
+    expect(twice).toBe(once);
+  });
+});

package/src/structure/engine/__tests__/content-rules/enforce-alphabetical-order.test.ts

@@ -0,0 +1,55 @@
+import { describe, test, expect } from "vitest";
+import { enforceAlphabeticalOrder, withManagedBody, type JsonObject } from "../../content-rules";
+
+function run(input: JsonObject, body: () => void): JsonObject {
+  return withManagedBody(input, body);
+}
+
+describe("enforceAlphabeticalOrder", () => {
+  test("default form (no args) is a no-op (safety)", () => {
+    const out = run({ b: 1, a: 2 }, () => enforceAlphabeticalOrder());
+    expect(Object.keys(out)).toEqual(["b", "a"]);
+  });
+
+  test("sorts keys at a specific nested path", () => {
+    const out = run({ scripts: { test: "x", build: "y", fmt: "z" } }, () =>
+      enforceAlphabeticalOrder("scripts"),
+    );
+    expect(Object.keys(out.scripts as Record<string, unknown>)).toEqual(["build", "fmt", "test"]);
+  });
+
+  test("recursive sorts nested objects too", () => {
+    const out = run(
+      {
+        outer: { z: 1, a: { c: 1, b: 2 } },
+      },
+      () => enforceAlphabeticalOrder("outer", { recursive: true }),
+    );
+    expect(Object.keys(out.outer as Record<string, unknown>)).toEqual(["a", "z"]);
+    const a = (out.outer as { a: Record<string, unknown> }).a;
+    expect(Object.keys(a)).toEqual(["b", "c"]);
+  });
+
+  test("root recursive sorts entire object", () => {
+    const out = run({ b: { z: 1, a: 2 }, a: { y: 1, x: 2 } }, () =>
+      enforceAlphabeticalOrder("", { recursive: true }),
+    );
+    expect(Object.keys(out)).toEqual(["a", "b"]);
+    expect(Object.keys(out.a as Record<string, unknown>)).toEqual(["x", "y"]);
+    expect(Object.keys(out.b as Record<string, unknown>)).toEqual(["a", "z"]);
+  });
+
+  test("no-op when the path is missing or not an object", () => {
+    const out = run({ name: "x" }, () => enforceAlphabeticalOrder("scripts"));
+    expect(out).toEqual({ name: "x" });
+  });
+
+  test("idempotent — second run is deep-equal to the first", () => {
+    const once = run({ scripts: { c: 1, a: 2, b: 3 } }, () => enforceAlphabeticalOrder("scripts"));
+    const twice = run(JSON.parse(JSON.stringify(once)), () => enforceAlphabeticalOrder("scripts"));
+    expect(twice).toEqual(once);
+    expect(Object.keys(twice.scripts as Record<string, unknown>)).toEqual(
+      Object.keys(once.scripts as Record<string, unknown>),
+    );
+  });
+});

package/src/structure/engine/__tests__/content-rules/enforce-field-order.test.ts

@@ -0,0 +1,73 @@
+import { describe, test, expect } from "vitest";
+import {
+  enforceFieldOrder,
+  enforceFieldOrderAt,
+  withManagedBody,
+  type JsonObject,
+} from "../../content-rules";
+
+function run(input: JsonObject, body: () => void): JsonObject {
+  return withManagedBody(input, body);
+}
+
+const order = ["name", "version", "private", "scripts", "dependencies", "pnpm"];
+
+describe("enforceFieldOrder / enforceFieldOrderAt", () => {
+  test("reorders known keys; unknowns stay adjacent to their preceding known key", () => {
+    const out = run(
+      {
+        name: "x",
+        private: true,
+        myCustomA: 1,
+        scripts: {},
+        myCustomB: 2,
+        dependencies: {},
+      },
+      () => enforceFieldOrder(order),
+    );
+    expect(Object.keys(out)).toEqual([
+      "name",
+      "private",
+      "myCustomA",
+      "scripts",
+      "myCustomB",
+      "dependencies",
+    ]);
+  });
+
+  test("missing known keys are skipped", () => {
+    const out = run({ name: "x", dependencies: {} }, () => enforceFieldOrder(order));
+    expect(Object.keys(out)).toEqual(["name", "dependencies"]);
+  });
+
+  test("unknowns before any known key go first in source order", () => {
+    const out = run({ foo: 1, bar: 2, name: "x" }, () => enforceFieldOrder(order));
+    expect(Object.keys(out)).toEqual(["foo", "bar", "name"]);
+  });
+
+  test("enforceFieldOrderAt reorders a nested object", () => {
+    const out = run(
+      {
+        scripts: {
+          build: "x",
+          test: "y",
+          fmt: "z",
+        },
+      },
+      () => enforceFieldOrderAt("scripts", ["fmt", "test", "build"]),
+    );
+    expect(Object.keys(out.scripts as Record<string, unknown>)).toEqual(["fmt", "test", "build"]);
+  });
+
+  test("enforceFieldOrderAt is a no-op when path missing", () => {
+    const out = run({ name: "x" }, () => enforceFieldOrderAt("scripts", ["a"]));
+    expect(out).toEqual({ name: "x" });
+  });
+
+  test("idempotent — second run produces deep-equal output", () => {
+    const once = run({ name: "x", scripts: {}, type: "module" }, () => enforceFieldOrder(order));
+    const twice = run(JSON.parse(JSON.stringify(once)), () => enforceFieldOrder(order));
+    expect(twice).toEqual(once);
+    expect(Object.keys(twice)).toEqual(Object.keys(once));
+  });
+});

package/src/structure/engine/__tests__/content-rules/ensure-catalog-absent.test.ts

@@ -0,0 +1,29 @@
+import { describe, test, expect } from "vitest";
+import { ensureCatalogAbsent, withManagedYaml } from "../../content-rules";
+import { parseYaml, stringifyYaml } from "../../parsers/yaml";
+
+describe("ensureCatalogAbsent", () => {
+  test("removes a present entry, leaves other keys alone", () => {
+    const doc = parseYaml("catalog:\n  drop-me: 1.0.0\n  keep: 2.0.0\n");
+    withManagedYaml(doc, () => ensureCatalogAbsent("drop-me"));
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat["drop-me"]).toBeUndefined();
+    expect(cat.keep).toBe("2.0.0");
+  });
+
+  test("no-op when the key is absent", () => {
+    const doc = parseYaml("catalog:\n  keep: 2.0.0\n");
+    withManagedYaml(doc, () => ensureCatalogAbsent("never-here"));
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat.keep).toBe("2.0.0");
+  });
+
+  test("idempotent — second run produces the same YAML", () => {
+    const doc = parseYaml("catalog:\n  drop-me: 1.0.0\n  keep: 2.0.0\n");
+    withManagedYaml(doc, () => ensureCatalogAbsent("drop-me"));
+    const once = stringifyYaml(doc);
+    withManagedYaml(doc, () => ensureCatalogAbsent("drop-me"));
+    const twice = stringifyYaml(doc);
+    expect(twice).toBe(once);
+  });
+});

package/src/structure/engine/__tests__/content-rules/ensure-catalog-latest.test.ts

@@ -0,0 +1,70 @@
+import { describe, test, expect } from "vitest";
+import { ensureCatalogLatest, withManagedYaml } from "../../content-rules";
+import { parseYaml, stringifyYaml } from "../../parsers/yaml";
+import {
+  createMockRegistryClient,
+  makeSyncLookup,
+  prefetchLatestVersions,
+} from "../../registry-client";
+
+async function lookupFor(versions: Record<string, string>) {
+  const client = createMockRegistryClient(versions);
+  const resolved = await prefetchLatestVersions(client, Object.keys(versions));
+  return makeSyncLookup(resolved);
+}
+
+describe("ensureCatalogLatest (mocked registry)", () => {
+  test("overwrites a present entry with the resolved latest", async () => {
+    const doc = parseYaml("catalog:\n  '@platforma-sdk/model': 1.0.0\n");
+    const getLatestVersion = await lookupFor({ "@platforma-sdk/model": "2.0.0" });
+    withManagedYaml(doc, () => ensureCatalogLatest("@platforma-sdk/model"), { getLatestVersion });
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat["@platforma-sdk/model"]).toBe("2.0.0");
+  });
+
+  test("add-if-absent: seeds a missing key from the resolved latest", async () => {
+    const doc = parseYaml("catalog:\n  unrelated: 9.9.9\n");
+    const getLatestVersion = await lookupFor({ "@milaboratories/ts-builder": "3.4.5" });
+    withManagedYaml(doc, () => ensureCatalogLatest("@milaboratories/ts-builder"), {
+      getLatestVersion,
+    });
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat["@milaboratories/ts-builder"]).toBe("3.4.5");
+    expect(cat.unrelated).toBe("9.9.9");
+  });
+
+  test("no-op when getLatestVersion is not provided (default refresh)", () => {
+    const doc = parseYaml("catalog:\n  '@platforma-sdk/model': 1.0.0\n");
+    withManagedYaml(doc, () => ensureCatalogLatest("@platforma-sdk/model"));
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat["@platforma-sdk/model"]).toBe("1.0.0");
+  });
+
+  test("no-op when the name was not prefetched (lookup returns undefined)", async () => {
+    const doc = parseYaml("catalog:\n  '@platforma-sdk/model': 1.0.0\n");
+    const getLatestVersion = await lookupFor({ "@platforma-sdk/other": "2.0.0" });
+    // The present key has no prefetched latest → left untouched, and an
+    // absent unprefetched key is not added.
+    withManagedYaml(
+      doc,
+      () => {
+        ensureCatalogLatest("@platforma-sdk/model");
+        ensureCatalogLatest("@platforma-sdk/missing");
+      },
+      { getLatestVersion },
+    );
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat["@platforma-sdk/model"]).toBe("1.0.0");
+    expect(cat["@platforma-sdk/missing"]).toBeUndefined();
+  });
+
+  test("idempotent — second run produces the same YAML", async () => {
+    const doc = parseYaml("catalog:\n  '@platforma-sdk/model': 1.0.0\n");
+    const getLatestVersion = await lookupFor({ "@platforma-sdk/model": "2.0.0" });
+    withManagedYaml(doc, () => ensureCatalogLatest("@platforma-sdk/model"), { getLatestVersion });
+    const once = stringifyYaml(doc);
+    withManagedYaml(doc, () => ensureCatalogLatest("@platforma-sdk/model"), { getLatestVersion });
+    const twice = stringifyYaml(doc);
+    expect(twice).toBe(once);
+  });
+});