@platforma-sdk/block-tools 2.10.17 → 2.10.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-sdk/block-tools",
-  "version": "2.10.17",
+  "version": "2.10.19",
   "description": "Utility to manipulate Platforma Blocks and Block Registry",
   "license": "UNLICENSED",
   "bin": {
@@ -33,14 +33,14 @@
     "undici": "~7.16.0",
     "yaml": "^2.8.0",
     "zod": "~3.25.76",
+    "@milaboratories/pl-http": "1.2.4",
     "@milaboratories/pl-model-common": "1.46.1",
-    "@milaboratories/pl-model-backend": "1.4.7",
-    "@milaboratories/resolve-helper": "1.1.3",
     "@milaboratories/pl-model-middle-layer": "1.30.6",
-    "@milaboratories/ts-helpers": "1.8.3",
-    "@milaboratories/pl-http": "1.2.4",
+    "@milaboratories/resolve-helper": "1.1.3",
     "@milaboratories/ts-helpers-oclif": "1.1.42",
-    "@platforma-sdk/blocks-deps-updater": "2.2.0"
+    "@platforma-sdk/blocks-deps-updater": "2.2.0",
+    "@milaboratories/ts-helpers": "1.8.3",
+    "@milaboratories/pl-model-backend": "1.4.7"
   },
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^16.0.1",
@@ -58,8 +58,8 @@
     "vitest": "^4.1.3",
     "@milaboratories/build-configs": "2.0.0",
     "@milaboratories/oclif-index": "1.1.1",
-    "@milaboratories/ts-configs": "1.2.3",
-    "@milaboratories/ts-builder": "1.5.1"
+    "@milaboratories/ts-builder": "1.5.2",
+    "@milaboratories/ts-configs": "1.2.3"
   },
   "oclif": {
     "bin": "block-tools",

package/src/structure/CLAUDE.md

@@ -0,0 +1,28 @@
+# structurer — mental model
+
+A declarative reconciler for a block's scaffolding. `rules/` DECLARE the
+canonical end-state of every non-source file in a block (package.json, configs,
+tsconfig, scripts, catalog); `engine/` reconciles any block toward that state.
+To change what "canonical" means, edit `rules/`; the engine is block-agnostic.
+
+## Boundaries
+
+- `engine/` — generic reconciliation primitives, module discovery, IR. Knows nothing about blocks.
+- `rules/` — the only home of block-specific layout knowledge. `templates/` holds the verbatim file bodies the rules reference.
+- Owns: the shape of a block's scaffolding. Is NOT a build tool, and NOT the author of a block's source — seeded/scaffolded files become author-owned once written.
+
+## Reading posture
+
+- Each `rules/*` file pairs a generator (init: full initial content) with a body (refresh: drift-correcting assertions). Read as "what the file should be" + "how to nudge an existing file there", not as sequential logic.
+- The primitive choice IS the design: `fixed` (overwrite verbatim, engine-owned), `managed` (reconcile named fields, author keeps the rest), `scaffold` (write-once default, author may tune), `seed` (written once at init, author owns forever), `remove` (one-way). Wrong primitive is the main design error — `fixed` on an author-tunable file clobbers their work; `seed` on engine-owned content lets drift accumulate.
+
+## Invariants
+
+- Fixpoint: `refresh` on an already-canonical block makes zero changes. Every rule must converge.
+- Generators emit oxfmt-clean output (the `enforce*` calls mirror oxfmt's order), so build→check passes with no prior `fmt`.
+- sdk-internal blocks (`etc/blocks/*`) skip root-scope and standalone test wiring — the monorepo owns that infra; the structurer must neither impose nor strip it.
+
+## Gotchas
+
+- A rule change also changes the canonical for `etc/blocks/*`: refresh them in the SAME PR (`pnpm run check-blocks`) or CI fails.
+- Dep/peer changes need a `pnpm i` lockfile sync — pnpm records peers and per-importer deps in pnpm-lock.yaml; frozen-install CI fails otherwise.

package/src/structure/__tests__/model-package-json.snapshot.test.ts

@@ -34,8 +34,7 @@ const EXPECTED_MODEL_PACKAGE_JSON = `{
   "devDependencies": {
     "@milaboratories/ts-builder": "catalog:",
     "@milaboratories/ts-configs": "catalog:",
-    "@platforma-sdk/block-tools": "catalog:",
-    "vitest": "catalog:"
+    "@platforma-sdk/block-tools": "catalog:"
   },
   "peerDependencies": {
     "@types/node": "*",

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

@@ -11,8 +11,12 @@ 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";
+import {
+  matchesBumpPattern,
+  buildRegistryLookupForNames,
+  buildDerivedPinLookupForPins,
+} from "../engine/registry-client";
+import { SDK_CATALOG_PACKAGES, DERIVED_CATALOG_PINS } from "../rules/root-pnpm-workspace";
 
 export type StructureMode = "check" | "refresh";
 
@@ -60,10 +64,16 @@ export async function runStructureForPath(input: RunStructureInput): Promise<Run
   });
 
   const registryLookup = input.updateDepsOnly ? await buildRegistryLookup() : undefined;
+  // Derived catalog pins (e.g. vue ← ui-vue's declared dep) resolve on the
+  // same prefetch budget as the SDK latest bump; absent on a default refresh.
+  const derivedPinLookup = input.updateDepsOnly
+    ? await buildDerivedPinLookupForPins(DERIVED_CATALOG_PINS)
+    : undefined;
 
   const result = engineRun(STRUCTURE, fs, ctx, {
     templates,
     registryLookup,
+    derivedPinLookup,
     // 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.

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

@@ -0,0 +1,65 @@
+import { describe, test, expect } from "vitest";
+import { pinCatalogToDependencyOf, withManagedYaml } from "../../content-rules";
+import { parseYaml, stringifyYaml } from "../../parsers/yaml";
+
+// The builder is sync: it reads a value the runner pre-resolved + validated
+// into `getDerivedDependencyPin`. These tests inject that accessor directly.
+const lookup =
+  (m: Record<string, string>) =>
+  (entry: string): string | undefined =>
+    m[entry];
+
+describe("pinCatalogToDependencyOf (mocked derived-pin lookup)", () => {
+  test("overwrites a present LOOSE entry with the derived exact version", () => {
+    const doc = parseYaml("catalog:\n  vue: ^3.5.24\n");
+    withManagedYaml(doc, () => pinCatalogToDependencyOf("vue", { of: "@platforma-sdk/ui-vue" }), {
+      getDerivedDependencyPin: lookup({ vue: "3.5.24" }),
+    });
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat.vue).toBe("3.5.24");
+  });
+
+  test("creates an absent entry", () => {
+    const doc = parseYaml("catalog:\n  unrelated: 1.0.0\n");
+    withManagedYaml(doc, () => pinCatalogToDependencyOf("vue", { of: "@platforma-sdk/ui-vue" }), {
+      getDerivedDependencyPin: lookup({ vue: "3.5.24" }),
+    });
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat.vue).toBe("3.5.24");
+    expect(cat.unrelated).toBe("1.0.0");
+  });
+
+  test("no-op when no derived-pin lookup is provided (default refresh)", () => {
+    const doc = parseYaml("catalog:\n  vue: ^3.5.24\n");
+    withManagedYaml(doc, () => pinCatalogToDependencyOf("vue", { of: "@platforma-sdk/ui-vue" }));
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat.vue).toBe("^3.5.24");
+  });
+
+  test("no-op when the entry was not prefetched (lookup returns undefined)", () => {
+    const doc = parseYaml("catalog:\n  vue: ^3.5.24\n");
+    withManagedYaml(doc, () => pinCatalogToDependencyOf("vue", { of: "@platforma-sdk/ui-vue" }), {
+      getDerivedDependencyPin: lookup({ other: "1.0.0" }),
+    });
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat.vue).toBe("^3.5.24");
+  });
+
+  test("idempotent — second run produces the same YAML", () => {
+    const doc = parseYaml("catalog:\n  vue: ^3.5.24\n");
+    const opts = { getDerivedDependencyPin: lookup({ vue: "3.5.24" }) };
+    withManagedYaml(
+      doc,
+      () => pinCatalogToDependencyOf("vue", { of: "@platforma-sdk/ui-vue" }),
+      opts,
+    );
+    const once = stringifyYaml(doc);
+    withManagedYaml(
+      doc,
+      () => pinCatalogToDependencyOf("vue", { of: "@platforma-sdk/ui-vue" }),
+      opts,
+    );
+    const twice = stringifyYaml(doc);
+    expect(twice).toBe(once);
+  });
+});

package/src/structure/engine/__tests__/derived-pin-lookup.test.ts

@@ -0,0 +1,54 @@
+import { describe, test, expect } from "vitest";
+import { buildDerivedPinLookupForPins, createMockRegistryClient } from "../registry-client";
+
+describe("buildDerivedPinLookupForPins (mocked registry)", () => {
+  test("resolves the catalog entry to the source's declared exact dep version", async () => {
+    const client = createMockRegistryClient(
+      { "@platforma-sdk/ui-vue": "1.79.6" },
+      { "@platforma-sdk/ui-vue@1.79.6": { vue: "3.5.24" } },
+    );
+    const lookup = await buildDerivedPinLookupForPins(
+      [{ entry: "vue", of: "@platforma-sdk/ui-vue" }],
+      client,
+    );
+    expect(lookup("vue")).toBe("3.5.24");
+    expect(lookup("unrelated")).toBeUndefined();
+  });
+
+  test("reads from a pinned source version when `ofVersion` is given", async () => {
+    const client = createMockRegistryClient(
+      { "@platforma-sdk/ui-vue": "9.9.9" }, // latest — must NOT be used
+      { "@platforma-sdk/ui-vue@1.79.3": { vue: "3.5.20" } },
+    );
+    const lookup = await buildDerivedPinLookupForPins(
+      [{ entry: "vue", of: "@platforma-sdk/ui-vue", ofVersion: "1.79.3" }],
+      client,
+    );
+    expect(lookup("vue")).toBe("3.5.20");
+  });
+
+  test("empty pin list → lookup returns undefined for everything", async () => {
+    const lookup = await buildDerivedPinLookupForPins([], createMockRegistryClient({}));
+    expect(lookup("vue")).toBeUndefined();
+  });
+
+  test("policy (b): throws when the source declares a NON-EXACT range", async () => {
+    const client = createMockRegistryClient(
+      { "@platforma-sdk/ui-vue": "1.79.6" },
+      { "@platforma-sdk/ui-vue@1.79.6": { vue: "^3.5.24" } },
+    );
+    await expect(
+      buildDerivedPinLookupForPins([{ entry: "vue", of: "@platforma-sdk/ui-vue" }], client),
+    ).rejects.toThrow(/not an exact version/i);
+  });
+
+  test("policy (b): throws when the source declares no such dependency", async () => {
+    const client = createMockRegistryClient(
+      { "@platforma-sdk/ui-vue": "1.79.6" },
+      { "@platforma-sdk/ui-vue@1.79.6": { react: "19.0.0" } },
+    );
+    await expect(
+      buildDerivedPinLookupForPins([{ entry: "vue", of: "@platforma-sdk/ui-vue" }], client),
+    ).rejects.toThrow(/declares no/i);
+  });
+});

package/src/structure/engine/api.ts

@@ -117,6 +117,7 @@ export {
   ensureWorkspaceModulePaths,
   ensureCatalogVersion,
   pinCatalogTo,
+  pinCatalogToDependencyOf,
   ensureCatalogLatest,
   ensureCatalogAbsent,
   // Lines managed builders

package/src/structure/engine/content-rules.ts

@@ -83,6 +83,9 @@ type YamlState = {
   triggerContext?: TriggerContext;
   /** Synchronous accessor for prefetched npm latest versions. */
   getLatestVersion?: (packageName: string) => string | undefined;
+  /** Synchronous accessor for prefetched derived catalog pins
+   *  (`catalogEntry → exact version`); see `pinCatalogToDependencyOf`. */
+  getDerivedDependencyPin?: (catalogEntry: string) => string | undefined;
 };
 
 type LinesState = {
@@ -177,6 +180,9 @@ export type WithManagedYamlOpts = WithManagedOpts & {
   /** Sync accessor for prefetched latest versions. Required for
    *  `ensureCatalogLatest` to take effect. */
   getLatestVersion?: (packageName: string) => string | undefined;
+  /** Sync accessor for prefetched derived catalog pins. Required for
+   *  `pinCatalogToDependencyOf` to take effect. */
+  getDerivedDependencyPin?: (catalogEntry: string) => string | undefined;
 };
 
 /** Engine-internal: run `body` with `doc` as the active YAML state (for
@@ -193,6 +199,7 @@ export function withManagedYaml(
     ctx: opts.ctx,
     triggerContext: opts.triggerContext,
     getLatestVersion: opts.getLatestVersion,
+    getDerivedDependencyPin: opts.getDerivedDependencyPin,
   };
   try {
     body();
@@ -579,6 +586,28 @@ export function ensureCatalogLatest(name: string): void {
   state.doc.setIn(["catalog", name], latest);
 }
 
+/** Pin `catalog.<catalogEntry>` to the EXACT version that package `opts.of`
+ *  declares for `catalogEntry` in its own manifest (read at npm latest, or at
+ *  `opts.ofVersion` if given). The value is resolved by the runner's
+ *  prefetched `getDerivedDependencyPin` accessor (the caller pre-resolves and
+ *  validates — exact-version-only — at prefetch time; no network here).
+ *  OVERWRITES like `pinCatalogTo` (not add-if-absent): a pre-existing loose
+ *  entry (`vue: ^3.5.24`) is tightened to the exact derived version. No-op
+ *  when no derived-pin lookup is available — default refresh/check pass none,
+ *  leaving the entry exactly as the lockfile has it; the resolution leaves
+ *  live in the `onInitOrUpdate` frame. */
+export function pinCatalogToDependencyOf(
+  catalogEntry: string,
+  _opts: { of: string; ofVersion?: string },
+): void {
+  const state = requireYaml("pinCatalogToDependencyOf");
+  if (!state.getDerivedDependencyPin) return;
+  const version = state.getDerivedDependencyPin(catalogEntry);
+  if (version === undefined) return;
+  if (readCatalogString(state, catalogEntry) === version) return;
+  state.doc.setIn(["catalog", catalogEntry], version);
+}
+
 /** Remove `catalog.<name>` if present; no-op when absent. */
 export function ensureCatalogAbsent(name: string): void {
   const state = requireYaml("ensureCatalogAbsent");

package/src/structure/engine/registry-client.ts

@@ -12,6 +12,15 @@ import { setTimeout as sleep } from "node:timers/promises";
 
 export interface RegistryClient {
   getLatestVersion(packageName: string): Promise<string>;
+  /** Read the version `packageName@version` declares for `depName` in its
+   *  published manifest. `version` may be "latest" (resolved via the
+   *  dist-tags). Looks in `dependencies` first, then `peerDependencies`.
+   *  Returns `undefined` when the dep is declared in neither section. */
+  getDeclaredDependency(
+    packageName: string,
+    version: string,
+    depName: string,
+  ): Promise<string | undefined>;
 }
 
 const RETRY_COUNT = 2;
@@ -60,6 +69,14 @@ async function fetchWithRetry(url: string): Promise<Response> {
   }
 }
 
+/** Shape of the per-version manifest doc fetched from
+ *  `https://registry.npmjs.org/<pkg>/<version>` (only the dep sections are
+ *  read). */
+type PackageManifest = {
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+};
+
 /** Live npm registry client. Hits the network on each call. */
 export function createRealRegistryClient(): RegistryClient {
   return {
@@ -74,11 +91,33 @@ export function createRealRegistryClient(): RegistryClient {
       }
       return latest;
     },
+    async getDeclaredDependency(
+      packageName: string,
+      version: string,
+      depName: string,
+    ): Promise<string | undefined> {
+      const res = await fetchWithRetry(`https://registry.npmjs.org/${packageName}/${version}`);
+      const manifest = (await res.json()) as PackageManifest;
+      return manifest.dependencies?.[depName] ?? manifest.peerDependencies?.[depName];
+    },
   };
 }
 
-/** In-memory client backed by a fixed `name → version` map. */
-export function createMockRegistryClient(versions: Record<string, string>): RegistryClient {
+/** In-memory client backed by a fixed `name → version` map. The optional
+ *  `manifests` map (`pkg@version` → declared deps) backs
+ *  `getDeclaredDependency`; "latest" keys resolve via the `versions` map. */
+export function createMockRegistryClient(
+  versions: Record<string, string>,
+  manifests: Record<string, Record<string, string>> = {},
+): RegistryClient {
+  function resolveVersion(packageName: string, version: string): string {
+    if (version !== "latest") return version;
+    const v = versions[packageName];
+    if (v === undefined) {
+      throw new Error(`mock registry: no version configured for '${packageName}'`);
+    }
+    return v;
+  }
   return {
     async getLatestVersion(packageName: string): Promise<string> {
       const v = versions[packageName];
@@ -87,6 +126,18 @@ export function createMockRegistryClient(versions: Record<string, string>): Regi
       }
       return v;
     },
+    async getDeclaredDependency(
+      packageName: string,
+      version: string,
+      depName: string,
+    ): Promise<string | undefined> {
+      const resolved = resolveVersion(packageName, version);
+      const deps = manifests[`${packageName}@${resolved}`];
+      if (deps === undefined) {
+        throw new Error(`mock registry: no manifest configured for '${packageName}@${resolved}'`);
+      }
+      return deps[depName];
+    },
   };
 }
 
@@ -138,3 +189,66 @@ export async function buildRegistryLookupForNames(
   const resolved = await prefetchLatestVersions(client, names);
   return makeSyncLookup(resolved);
 }
+
+/** A catalog entry whose version is DERIVED from the version another
+ *  package declares for it. `entry` is the catalog key (== the dep name in
+ *  the source manifest); `of` is the package whose manifest is read; the
+ *  optional `ofVersion` pins which release of `of` to read (default: npm
+ *  latest, the same release the catalog bump pins `of` to). Consumed by
+ *  `pinCatalogToDependencyOf`. */
+export type DerivedCatalogPin = {
+  entry: string;
+  of: string;
+  ofVersion?: string;
+};
+
+/** True iff `version` is a bare exact `x.y.z(-prerelease)?` — no range
+ *  modifier (`^`, `~`, `>=`, `*`, `||`, ` - `, `x`, workspace:, etc.). */
+function isExactVersion(version: string): boolean {
+  return /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version);
+}
+
+/** Prefetch every derived pin and build the sync lookup the runner passes
+ *  to `pinCatalogToDependencyOf` (`entry → exact version`). Reads
+ *  `pin.of`'s manifest (at `pin.ofVersion`, default npm latest) and the
+ *  version it declares for `pin.entry`. Policy (b): THROWS at prefetch time
+ *  if the source declares the dep as a non-exact (ranged) version or does
+ *  not declare it at all — a derived pin must resolve to an exact version
+ *  or it is a configuration error. Empty list → a lookup that resolves
+ *  nothing (no network). A registry failure REJECTS. `client` defaults to
+ *  the live npm client; tests inject a mock. */
+export async function buildDerivedPinLookupForPins(
+  pins: readonly DerivedCatalogPin[],
+  client: RegistryClient = createRealRegistryClient(),
+): Promise<(entry: string) => string | undefined> {
+  if (pins.length === 0) return () => undefined;
+  const entries = await Promise.all(
+    pins.map(async (pin) => {
+      const declared = await client.getDeclaredDependency(
+        pin.of,
+        pin.ofVersion ?? "latest",
+        pin.entry,
+      );
+      if (declared === undefined) {
+        throw new Error(
+          `derived catalog pin '${pin.entry}': package '${pin.of}'` +
+            `${pin.ofVersion ? `@${pin.ofVersion}` : " (latest)"} declares no ` +
+            `dependency '${pin.entry}'. A derived pin requires the source to ` +
+            `declare the dep as an exact version.`,
+        );
+      }
+      if (!isExactVersion(declared)) {
+        throw new Error(
+          `derived catalog pin '${pin.entry}': package '${pin.of}'` +
+            `${pin.ofVersion ? `@${pin.ofVersion}` : " (latest)"} declares ` +
+            `'${pin.entry}: ${declared}', which is not an exact version. ` +
+            `A derived pin requires an exact ('x.y.z') source dependency so ` +
+            `the catalog can pin to it precisely.`,
+        );
+      }
+      return [pin.entry, declared] as const;
+    }),
+  );
+  const resolved = new Map(entries);
+  return (entry) => resolved.get(entry);
+}

package/src/structure/engine/runner.ts

@@ -83,6 +83,12 @@ export type RunOptions = {
    *  and passes the resulting sync map here; unit tests pass a mock.
    *  Absent → `ensureCatalogLatest` is a no-op (default refresh). */
   registryLookup?: (packageName: string) => string | undefined;
+  /** Sync accessor for prefetched derived catalog pins
+   *  (`catalogEntry → exact version`), consumed by `pinCatalogToDependencyOf`
+   *  inside `onInitOrUpdate` managed bodies. The CLI / init constructor
+   *  prefetches + validates these before the run (network). Absent →
+   *  `pinCatalogToDependencyOf` is a no-op (default refresh). */
+  derivedPinLookup?: (catalogEntry: string) => string | undefined;
 };
 
 export class RecheckError extends Error {
@@ -189,6 +195,7 @@ function runManagedBody(
   body: ManagedBody,
   tctx: TriggerContext,
   registryLookup: ((packageName: string) => string | undefined) | undefined,
+  derivedPinLookup: ((catalogEntry: string) => string | undefined) | undefined,
 ): string {
   const base = path.split("/").pop() ?? path;
   if (path.endsWith(".json")) {
@@ -203,7 +210,11 @@ function runManagedBody(
   }
   if (path.endsWith(".yaml") || path.endsWith(".yml")) {
     const doc = parseYaml(raw);
-    withManagedYaml(doc, body, { triggerContext: tctx, getLatestVersion: registryLookup });
+    withManagedYaml(doc, body, {
+      triggerContext: tctx,
+      getLatestVersion: registryLookup,
+      getDerivedDependencyPin: derivedPinLookup,
+    });
     return stringifyYaml(doc);
   }
   if (base === ".gitignore" || base.endsWith(".gitignore")) {
@@ -371,6 +382,7 @@ function applyManaged(
   tctx: TriggerContext,
   templates: TemplateProvider | undefined,
   registryLookup: ((packageName: string) => string | undefined) | undefined,
+  derivedPinLookup: ((catalogEntry: string) => string | undefined) | undefined,
   isSdkInternal: boolean,
 ): Change | undefined {
   if (item.leaf.kind !== "managed") return undefined;
@@ -388,7 +400,7 @@ function applyManaged(
     beforeRaw = fs.read(path);
   }
 
-  const after = runManagedBody(path, beforeRaw, leaf.body, tctx, registryLookup);
+  const after = runManagedBody(path, beforeRaw, leaf.body, tctx, registryLookup, derivedPinLookup);
 
   if (created) {
     if (!dryRun) fs.write(path, after);
@@ -419,6 +431,7 @@ function executePass(
   templates: TemplateProvider | undefined,
   initMode: boolean,
   registryLookup: ((packageName: string) => string | undefined) | undefined,
+  derivedPinLookup: ((catalogEntry: string) => string | undefined) | undefined,
 ): Change[] {
   const items = filterByMode(flat, currentMode(ctx, initMode));
   const changes: Change[] = [];
@@ -448,6 +461,7 @@ function executePass(
       tctx2,
       templates,
       registryLookup,
+      derivedPinLookup,
       ctx.isSdkInternal,
     );
     if (change) changes.push(change);
@@ -478,6 +492,7 @@ export function run(
       opts.templates,
       initMode,
       opts.registryLookup,
+      opts.derivedPinLookup,
     );
 
     const isRefreshDefault = !ctx.dryRun && !ctx.updateDepsOnly && !initMode;
@@ -499,6 +514,7 @@ export function run(
         opts.templates,
         false,
         opts.registryLookup,
+        opts.derivedPinLookup,
       );
       // Ignore .structure self-write (already up to date after
       // writeStructureVersion above).

package/src/structure/init-block-constructor.ts

@@ -14,8 +14,12 @@ import { run as engineRun } from "./engine/runner";
 import { createRunContext, modulesForInit } from "./engine/ctx";
 import { STRUCTURE } from "./structure-definition";
 import { STRUCTURE_VERSION } from "./engine/version";
-import { matchesBumpPattern, buildRegistryLookupForNames } from "./engine/registry-client";
-import { SDK_CATALOG_PACKAGES } from "./rules/root-pnpm-workspace";
+import {
+  matchesBumpPattern,
+  buildRegistryLookupForNames,
+  buildDerivedPinLookupForPins,
+} from "./engine/registry-client";
+import { SDK_CATALOG_PACKAGES, DERIVED_CATALOG_PINS } from "./rules/root-pnpm-workspace";
 import type { BlockVars } from "./engine/api";
 
 /** Platform choices `init` can scaffold a software module for. Python is
@@ -145,8 +149,12 @@ export async function runInit(init: InitInput): Promise<BlockVars> {
   // aborts init rather than silently shipping an unresolved placeholder.
   const sdkNames = SDK_CATALOG_PACKAGES.filter(matchesBumpPattern);
   let registryLookup: (name: string) => string | undefined;
+  let derivedPinLookup: (entry: string) => string | undefined;
   try {
     registryLookup = await buildRegistryLookupForNames(sdkNames);
+    // Derived catalog pins (e.g. vue ← ui-vue's declared dep) are resolved on
+    // init too, so a freshly-scaffolded block pins vue exactly from the start.
+    derivedPinLookup = await buildDerivedPinLookupForPins(DERIVED_CATALOG_PINS);
   } catch (err) {
     throw new Error(
       `init requires network access to resolve SDK catalog versions from npm, ` +
@@ -154,7 +162,12 @@ export async function runInit(init: InitInput): Promise<BlockVars> {
     );
   }
 
-  engineRun(STRUCTURE, fs, ctx, { templates, initMode: true, registryLookup });
+  engineRun(STRUCTURE, fs, ctx, {
+    templates,
+    initMode: true,
+    registryLookup,
+    derivedPinLookup,
+  });
   init.log(
     `Initialised block '${vars.facadeName}'${
       vars.softwarePlatform ? ` (software: ${vars.softwarePlatform})` : " (no software)"

package/src/structure/rules/migrations.ts

@@ -23,40 +23,39 @@ export function testFrameworkMigration(): void {
 // Unconditional legacy-cleanup rules. Each is a no-op on an
 // already-canonical block (remove on an absent path, removeScript /
 // removeDep on an absent key) and idempotent, so they sit at top level
-// with no `when` gate. The trailing comment on each line names the real
-// block(s) that carry the artefact being cleaned.
+// with no `when` gate.
 //
 // Root-scope cleanup is skipped for `--sdk-internal` blocks (no root
 // module in that mode), so it never touches in-monorepo blocks.
 export function legacyCleanup(): void {
-  // eslint → oxlint: the canonical layout ships `.oxlintrc.json` /
-  // `.oxfmtrc.json`; flat eslint configs are retired.
+  // Retired per-scope config files: flat eslint configs and vite-era build /
+  // split-tsconfig files, replaced by the oxlint/oxfmt + ts-builder layout.
   scope("model", () => {
-    remove("eslint.config.mjs"); // samples-and-data, mixcr-clonotyping, clonotype-clustering, antibody-sequence-liabilities
-    remove("vite.config.mts"); // samples-and-data (vite build → ts-builder)
+    remove("eslint.config.mjs");
+    remove("vite.config.mts");
   });
   scope("ui", () => {
-    remove("eslint.config.mjs"); // samples-and-data, mixcr-clonotyping, clonotype-clustering, antibody-sequence-liabilities
-    remove("vite.config.ts"); // samples-and-data (vite build → ts-builder)
-    remove("tsconfig.app.json"); // samples-and-data (vite-era split tsconfig)
-    remove("tsconfig.node.json"); // samples-and-data (vite-era split tsconfig)
+    remove("eslint.config.mjs");
+    remove("vite.config.ts");
+    remove("tsconfig.app.json");
+    remove("tsconfig.node.json");
   });
   scope("test", () => {
-    remove("eslint.config.mjs"); // all 5 experiment blocks
+    remove("eslint.config.mjs");
   });
 
   // Root-scope cleanup. The second `managed("package.json")` body composes
   // after rootRules.
   scope("root", () => {
-    remove(".prettierrc"); // samples-and-data, sequence-properties (prettier → oxfmt)
+    remove(".prettierrc");
     managed(
       "package.json",
       generate(() => rootPackageJsonInitial(getActiveRunContext())),
       () => {
-        // `pretty` (prettier) is superseded by the canonical `fmt` (oxfmt);
-        // the standalone deps-updater was merged into block-tools.
-        removeScript("pretty"); // samples-and-data
-        removeDep("@platforma-sdk/blocks-deps-updater"); // samples-and-data
+        // `pretty` (prettier) is superseded by `fmt` (oxfmt); the standalone
+        // deps-updater is now part of block-tools.
+        removeScript("pretty");
+        removeDep("@platforma-sdk/blocks-deps-updater");
       },
     );
   });