@platforma-sdk/block-tools 2.14.0 → 2.14.2

package/dist/structure/engine/testing.d.ts

@@ -19,6 +19,9 @@ export type SimulateInitInput = {
      *  Absent → the SDK catalog keeps its seed versions (no bump), matching
      *  an offline scaffold; tests that assert init writes latest pass a mock. */
     registryLookup?: (packageName: string) => string | undefined;
+    /** Sync lookup for the derived catalog pins. Absent → those entries are
+     *  left out of the catalog; the real `init` always passes one. */
+    derivedPinLookup?: (catalogEntry: string) => string | undefined;
 };
 export type SimulatedInit = {
     fs: MemoryFileSystem;

package/dist/structure/rules/root-changeset-config.d.ts

@@ -0,0 +1,8 @@
+/** Seeded so the scaffold's own PR passes the `require-package-path-bump` gate
+ *  without bumping: `changeset version` consumes it and leaves the facade at
+ *  `INITIAL_MODULE_VERSION`, so the first version a user sees is 1.0.0 rather
+ *  than 1.0.1. Seeded (not managed) — a refresh must never resurrect it once
+ *  the first release has consumed it. */
+export declare const EMPTY_CHANGESET_SEED = "---\n---\n\nInitial release.\n";
+export declare function rootChangesetConfigInitial(): Record<string, unknown>;
+export declare function rootChangesetConfigRules(): void;

package/dist/structure/rules/shared/initial-version.d.ts

@@ -0,0 +1,10 @@
+/** Seeded at init for every module. `pnpm pack` rewrites the facade's
+ *  `workspace:*` devDeps to concrete ranges, so a versionless sibling breaks
+ *  `do-pack`. Changesets owns the field afterwards. */
+export declare const INITIAL_MODULE_VERSION = "1.0.0";
+/** Backfill `version` on a sibling that has none — a block scaffolded before
+ *  the initials seeded the field keeps its versionless manifests through a
+ *  `structure refresh`, and `do-pack` then dies resolving the facade's
+ *  `workspace:*` deps. Never touches an existing value: past init the field
+ *  belongs to changesets. */
+export declare function ensureModuleVersion(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-sdk/block-tools",
-  "version": "2.14.0",
+  "version": "2.14.2",
   "description": "Utility to manipulate Platforma Blocks and Block Registry",
   "license": "UNLICENSED",
   "bin": {
@@ -34,13 +34,13 @@
     "undici": "~7.16.0",
     "yaml": "^2.8.0",
     "zod": "~3.25.76",
+    "@milaboratories/pl-model-backend": "1.4.21",
     "@milaboratories/pl-http": "1.2.4",
+    "@milaboratories/ts-helpers": "1.8.6",
     "@milaboratories/pl-model-common": "1.48.0",
     "@milaboratories/pl-model-middle-layer": "1.32.0",
-    "@platforma-sdk/blocks-deps-updater": "2.2.0",
-    "@milaboratories/ts-helpers": "1.8.6",
-    "@milaboratories/pl-model-backend": "1.4.21",
     "@milaboratories/resolve-helper": "1.1.3",
+    "@platforma-sdk/blocks-deps-updater": "2.2.0",
     "@platforma-sdk/package-builder-lib": "1.3.0"
   },
   "devDependencies": {

package/src/structure/__tests__/facade-end-state.test.ts

@@ -9,6 +9,7 @@ import { classifyOne, type WorkspacePackage } from "../engine/discovery";
 import { STRUCTURE } from "../structure-definition";
 import { run as engineRun } from "../engine/runner";
 import { defaultTemplateProvider, simulateInit } from "../engine/testing";
+import { INITIAL_MODULE_VERSION } from "../rules/shared/initial-version";
 
 const TEMPLATES = defaultTemplateProvider();
 
@@ -166,14 +167,78 @@ describe("facade: `prepublishOnly` publish target branches on isSdkInternal", ()
 });
 
 describe("facade: sibling package privacy", () => {
-  test("model / ui / workflow / test are `private` with no `version`", () => {
+  // Private but versioned. `pnpm pack` in the facade has to rewrite each
+  // `workspace:*` devDep to a concrete range, so a versionless sibling fails
+  // `do-pack` with ERR_PNPM_CANNOT_RESOLVE_WORKSPACE_PROTOCOL. The kind needs
+  // one for a second reason: its own src imports `version` from its
+  // package.json.
+  test("kind / model / ui / workflow / test are `private` and versioned", () => {
     const { fs } = simulateInit({ vars: VARS });
-    for (const scope of ["model", "ui", "workflow", "test"]) {
+    for (const scope of ["kind", "model", "ui", "workflow", "test"]) {
       const p = JSON.parse(fs.read(`${scope}/package.json`));
       expect(p.private, `${scope} must be private`).toBe(true);
-      expect("version" in p, `${scope} must not carry a version`).toBe(false);
+      expect(p.version, `${scope} must carry a version`).toBe(INITIAL_MODULE_VERSION);
     }
   });
+
+  test("every `workspace:*` dep of the facade resolves to a versioned package", () => {
+    const { fs } = simulateInit({ vars: VARS });
+    const facade = JSON.parse(fs.read("block/package.json"));
+    const byName = new Map<string, string | undefined>();
+    for (const scope of ["kind", "model", "ui", "workflow", "test"]) {
+      const p = JSON.parse(fs.read(`${scope}/package.json`));
+      byName.set(p.name, p.version);
+    }
+
+    const workspaceDeps = Object.entries({
+      ...facade.dependencies,
+      ...facade.devDependencies,
+    }).filter(([, spec]) => String(spec).startsWith("workspace:"));
+    expect(workspaceDeps.length).toBeGreaterThan(0);
+
+    for (const [name] of workspaceDeps) {
+      expect(byName.get(name), `${name} is a workspace dep with no version`).toBeDefined();
+    }
+  });
+});
+
+describe("facade: sibling versions on refresh", () => {
+  // A block scaffolded before the initials seeded `version` carries versionless
+  // sibling manifests. `refresh` never re-runs an initial for a file that
+  // exists, so the bodies have to backfill the field themselves — otherwise
+  // `do-pack` dies on ERR_PNPM_CANNOT_RESOLVE_WORKSPACE_PROTOCOL rewriting the
+  // facade's `workspace:*` deps.
+  test("a refresh backfills `version` on versionless siblings", () => {
+    const { fs, ctx } = simulateInit({ vars: VARS });
+    const scopes = ["kind", "model", "ui", "workflow", "test"];
+    for (const scope of scopes) {
+      const p = JSON.parse(fs.read(`${scope}/package.json`));
+      delete p.version;
+      fs.write(`${scope}/package.json`, `${JSON.stringify(p, null, 2)}\n`);
+    }
+
+    const refreshCtx: RunContext = { ...ctx, dryRun: false };
+    expect(() => engineRun(STRUCTURE, fs, refreshCtx, { templates: TEMPLATES })).not.toThrow();
+
+    for (const scope of scopes) {
+      const p = JSON.parse(fs.read(`${scope}/package.json`));
+      expect(p.version, `${scope} must be versioned after refresh`).toBe(INITIAL_MODULE_VERSION);
+      // `version` sits right after `name` — the canonical order the formatter
+      // enforces; a backfill appended at the end would fail `oxfmt --check`.
+      expect(Object.keys(p).indexOf("version")).toBe(1);
+    }
+  });
+
+  test("a refresh leaves an existing sibling `version` alone (changesets owns it)", () => {
+    const { fs, ctx } = simulateInit({ vars: VARS });
+    const bumped = JSON.parse(fs.read("model/package.json"));
+    bumped.version = "3.4.5";
+    fs.write("model/package.json", `${JSON.stringify(bumped, null, 2)}\n`);
+
+    engineRun(STRUCTURE, fs, { ...ctx, dryRun: false }, { templates: TEMPLATES });
+
+    expect(JSON.parse(fs.read("model/package.json")).version).toBe("3.4.5");
+  });
 });
 
 describe("facade: legacy shim cleanup on refresh", () => {

package/src/structure/__tests__/init-catalog-completeness.test.ts

@@ -0,0 +1,86 @@
+// One `"x": "catalog:"` with no `x` catalog key fails the whole `pnpm install`
+// with ERR_PNPM_CATALOG_ENTRY_NOT_FOUND_FOR_SPEC. The dep sets live in
+// `rules/*-package-json.ts` and the catalog in `rules/root-pnpm-workspace.ts`;
+// nothing else ties the two together.
+
+import { describe, test, expect } from "vitest";
+import { parse as parseYaml } from "yaml";
+import { simulateInit } from "../engine/testing";
+import { MemoryFileSystem } from "../engine/fs/memory";
+import { SDK_CATALOG_PACKAGES, DERIVED_CATALOG_PINS } from "../rules/root-pnpm-workspace";
+import type { BlockVars } from "../engine/api";
+
+const DEP_SECTIONS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+] as const;
+
+const BASE_VARS: BlockVars = {
+  facadeName: "@platforma-open/test-org.demo",
+  baseName: "test-org.demo",
+  npmOrg: "@platforma-open",
+  orgScope: "test-org",
+  shortName: "demo",
+};
+
+// Distinct mock versions, so a wrong-name lookup cannot pass by accident.
+const registryLookup = (name: string): string | undefined =>
+  SDK_CATALOG_PACKAGES.includes(name) ? "9.9.9" : undefined;
+const derivedPinLookup = (entry: string): string | undefined =>
+  DERIVED_CATALOG_PINS.some((pin) => pin.entry === entry) ? "8.8.8" : undefined;
+
+/** `path → catalog-referencing dep names`, over every package.json written. */
+function catalogReferences(fs: MemoryFileSystem): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  for (const path of fs.list("")) {
+    if (!path.endsWith("package.json")) continue;
+    const manifest = JSON.parse(fs.read(path)) as Record<string, unknown>;
+    const names: string[] = [];
+    for (const section of DEP_SECTIONS) {
+      const deps = manifest[section];
+      if (typeof deps !== "object" || deps === null) continue;
+      for (const [name, spec] of Object.entries(deps as Record<string, string>)) {
+        if (spec === "catalog:") names.push(name);
+      }
+    }
+    if (names.length > 0) out.set(path, names);
+  }
+  return out;
+}
+
+function catalogOf(fs: MemoryFileSystem): Record<string, string> {
+  const parsed = parseYaml(fs.read("pnpm-workspace.yaml")) as {
+    catalog?: Record<string, string>;
+  };
+  return parsed.catalog ?? {};
+}
+
+describe("init output is installable: every `catalog:` dep has a catalog entry", () => {
+  for (const [shape, vars] of [
+    ["without software", BASE_VARS],
+    ["with software", { ...BASE_VARS, softwarePlatform: "python" }],
+  ] as const) {
+    test(`a block ${shape}`, () => {
+      const { fs } = simulateInit({ vars, registryLookup, derivedPinLookup });
+      const catalog = catalogOf(fs);
+      const references = catalogReferences(fs);
+
+      // Guard the guard: a walk that finds nothing would pass vacuously.
+      expect(references.size).toBeGreaterThan(0);
+
+      for (const [path, names] of references) {
+        for (const name of names) {
+          expect(
+            catalog[name],
+            `${path} declares "${name}": "catalog:", but pnpm-workspace.yaml has no ` +
+              `'${name}' catalog entry — pnpm install fails with ` +
+              `ERR_PNPM_CATALOG_ENTRY_NOT_FOUND_FOR_SPEC. Add it to ` +
+              `SDK_CATALOG_PACKAGES or INFRA_CATALOG_FLOOR in rules/root-pnpm-workspace.ts.`,
+          ).toBeDefined();
+        }
+      }
+    });
+  }
+});

package/src/structure/__tests__/init-lint-clean.test.ts

@@ -0,0 +1,84 @@
+// `ts-builder format` runs oxlint with `--deny-warnings`, so one unused
+// parameter in a seeded file fails `pnpm fmt` — the last step of `upgrade-sdk`.
+
+import { describe, test, expect } from "vitest";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { simulateInit } from "../engine/testing";
+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",
+};
+
+function resolveTsBuilderConfig(configFile: string): string {
+  return fileURLToPath(import.meta.resolve(`@milaboratories/ts-builder/configs/${configFile}`));
+}
+
+/** ts-builder pins its own oxlint, so block-tools' PATH copy is a different
+ *  version. */
+function resolveOxlintBinary(): string | undefined {
+  const configsDir = path.dirname(resolveTsBuilderConfig("oxlint-base.json"));
+  const binary = path.resolve(configsDir, "..", "..", "node_modules", ".bin", "oxlint");
+  return existsSync(binary) ? binary : undefined;
+}
+
+/** The scopes whose `fmt` script lints. */
+const LINTED_SCOPES = ["kind", "model", "test", "ui"];
+
+describe("init output is lint-clean (oxlint --deny-warnings)", () => {
+  const oxlint = resolveOxlintBinary();
+
+  test.runIf(oxlint)("every seeded source passes its scope's oxlint config", () => {
+    const { fs } = simulateInit({ vars: VARS });
+    const root = mkdtempSync(path.join(tmpdir(), "init-lint-clean-"));
+
+    for (const scope of LINTED_SCOPES) {
+      const configPath = `${scope}/.oxlintrc.json`;
+      expect(fs.exists(configPath), `${scope} must carry an .oxlintrc.json`).toBe(true);
+
+      // The generated `extends` are relative to an installed node_modules.
+      const config = JSON.parse(fs.read(configPath)) as { extends?: string[] };
+      const extendsAbsolute = (config.extends ?? []).map((entry) =>
+        resolveTsBuilderConfig(path.basename(entry)),
+      );
+      expect(
+        extendsAbsolute.length,
+        `${scope}/.oxlintrc.json must extend a config`,
+      ).toBeGreaterThan(0);
+
+      mkdirSync(path.join(root, scope), { recursive: true });
+      writeFileSync(
+        path.join(root, scope, ".oxlintrc.json"),
+        JSON.stringify({ ...config, extends: extendsAbsolute }),
+      );
+      for (const file of fs.list(`${scope}/src`)) {
+        const target = path.join(root, file);
+        mkdirSync(path.dirname(target), { recursive: true });
+        writeFileSync(target, fs.read(file));
+      }
+
+      const result = spawnSync(
+        oxlint!,
+        ["--config", path.join(root, scope, ".oxlintrc.json"), "--deny-warnings", "src"],
+        { cwd: path.join(root, scope), encoding: "utf-8" },
+      );
+      expect(
+        result.status,
+        `seeded ${scope}/src is not lint-clean, so \`pnpm run fmt\` (and with it ` +
+          `\`pnpm run upgrade-sdk\`) fails on a fresh block:\n${result.stdout}\n${result.stderr}`,
+      ).toBe(0);
+    }
+  });
+
+  if (!oxlint) {
+    test.skip("oxlint binary unavailable — skipping lint-clean guard", () => {});
+  }
+});

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

@@ -9,6 +9,7 @@ import type { BlockVars } from "../engine/api";
 
 const EXPECTED_MODEL_PACKAGE_JSON = `{
   "name": "@platforma-open/test-org.demo.model",
+  "version": "1.0.0",
   "private": true,
   "type": "module",
   "main": "dist/index.cjs",

package/src/structure/__tests__/root-changeset-config.test.ts

@@ -0,0 +1,94 @@
+// CI runs `pnpm run version-packages` on every PR, so a block with no
+// `.changeset/config.json` fails its first CI run.
+
+import { describe, test, expect } from "vitest";
+import { simulateInit, defaultTemplateProvider } from "../engine/testing";
+import { run as engineRun } from "../engine/runner";
+import { discoverRunContext } from "../engine/discovery-fs";
+import { STRUCTURE } from "../structure-definition";
+import { MemoryFileSystem } from "../engine/fs/memory";
+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",
+};
+
+const PATH = ".changeset/config.json";
+
+function refresh(fs: MemoryFileSystem, isSdkInternal = false) {
+  return engineRun(STRUCTURE, fs, discoverRunContext({ fs, isSdkInternal }), {
+    templates: defaultTemplateProvider(),
+    rediscover: () => discoverRunContext({ fs, isSdkInternal, dryRun: true }),
+  });
+}
+
+describe("root .changeset/config.json", () => {
+  test("init writes the config CI needs", () => {
+    const { fs } = simulateInit({ vars: VARS });
+    const config = JSON.parse(fs.read(PATH));
+    expect(config.changelog).toBe("@changesets/cli/changelog");
+    expect(config.commit).toBe(false);
+    expect(config.access).toBe("restricted");
+    expect(config.baseBranch).toBe("main");
+    expect(config.updateInternalDependencies).toBe("patch");
+  });
+
+  test("refresh creates it for a block that predates the rule", () => {
+    const { fs } = simulateInit({ vars: VARS });
+    fs.delete(".changeset");
+    expect(fs.exists(PATH)).toBe(false);
+
+    refresh(fs);
+    expect(JSON.parse(fs.read(PATH)).baseBranch).toBe("main");
+  });
+
+  test("refresh keeps author-owned lists and re-asserts the CI fields", () => {
+    const { fs } = simulateInit({ vars: VARS });
+    const authored = {
+      ...JSON.parse(fs.read(PATH)),
+      $schema: "https://unpkg.com/@changesets/config@3.0.2/schema.json",
+      ignore: ["@platforma-open/test-org.demo.ui"],
+      access: "public",
+      "//privatePackages": "a note the author added",
+    };
+    fs.write(PATH, JSON.stringify(authored, null, 2));
+
+    refresh(fs);
+    const after = JSON.parse(fs.read(PATH));
+    expect(after.ignore).toEqual(["@platforma-open/test-org.demo.ui"]);
+    expect(after.$schema).toBe("https://unpkg.com/@changesets/config@3.0.2/schema.json");
+    expect(after["//privatePackages"]).toBe("a note the author added");
+    expect(after.access).toBe("restricted");
+  });
+
+  test("sdk-internal blocks get no config — the monorepo owns it", () => {
+    const { fs } = simulateInit({ vars: VARS, isSdkInternal: true });
+    expect(fs.exists(PATH)).toBe(false);
+  });
+});
+
+describe("root .changeset/scaffold.md", () => {
+  const SEED = ".changeset/scaffold.md";
+
+  // An empty changeset names no package, so `changeset version` consumes it
+  // without bumping. That is what keeps the first RELEASED facade version at
+  // 1.0.0 instead of 1.0.1, and it passes CI's require-package-path-bump gate.
+  test("init seeds an empty changeset — no package named", () => {
+    const { fs } = simulateInit({ vars: VARS });
+    const body = fs.read(SEED);
+    expect(body.startsWith("---\n---\n")).toBe(true);
+    expect(body).not.toContain(VARS.facadeName);
+  });
+
+  test("refresh does not resurrect it once a release consumed it", () => {
+    const { fs } = simulateInit({ vars: VARS });
+    fs.delete(SEED);
+
+    refresh(fs);
+    expect(fs.exists(SEED)).toBe(false);
+  });
+});

package/src/structure/__tests__/root-ci-workflows.test.ts

@@ -37,6 +37,9 @@ describe("root CI workflows (fixed, generated)", () => {
     // Shared constants.
     expect(build).toContain("team-id: 'ciplopen'");
     expect(build).toContain("test: true");
+    // Both workflows track the toolchain's node major (mise pins 22).
+    expect(build).toContain("node-version: '22.x'");
+    expect(fs.read(MARK_STABLE)).toContain("node-version: '22.x'");
     // Opt-in gate: the published `block` package must be bumped on PRs.
     expect(build).toContain("require-package-path-bump: true");
     // No bare `build` script exists (root-package-json removes it), so both

package/src/structure/engine/testing.ts

@@ -45,6 +45,9 @@ export type SimulateInitInput = {
    *  Absent → the SDK catalog keeps its seed versions (no bump), matching
    *  an offline scaffold; tests that assert init writes latest pass a mock. */
   registryLookup?: (packageName: string) => string | undefined;
+  /** Sync lookup for the derived catalog pins. Absent → those entries are
+   *  left out of the catalog; the real `init` always passes one. */
+  derivedPinLookup?: (catalogEntry: string) => string | undefined;
 };
 
 export type SimulatedInit = {
@@ -84,6 +87,7 @@ export function simulateInit(input: SimulateInitInput): SimulatedInit {
     templates,
     initMode: true,
     registryLookup: input.registryLookup,
+    derivedPinLookup: input.derivedPinLookup,
   });
 
   // Re-discover from the written FS — the returned ctx is what `check`

package/src/structure/rules/block-package-json.ts

@@ -18,6 +18,7 @@ import {
 } from "../engine/api";
 import { findModules, scopeDepMaps } from "../engine/ctx";
 import { canonicalPackageJsonOrder } from "./shared/key-order";
+import { INITIAL_MODULE_VERSION } from "./shared/initial-version";
 
 /** Per-org publish coordinates: the S3 upload bucket and the public registry
  *  serve URL the facade's `prepublishOnly` script passes to `block-tools
@@ -177,7 +178,7 @@ export function blockPackageJsonInitial(ctx: RunContext): Record<string, unknown
   assertBlockFieldsFilled(block);
   return {
     name: `${v.facadeName}.block`,
-    version: "1.0.0",
+    version: INITIAL_MODULE_VERSION,
     // Facade is ESM: rolldown-plugin-dts requires it, and the BlockPointer's
     // `import.meta.url` path math needs it.
     type: "module",

package/src/structure/rules/kind-package-json.ts

@@ -29,6 +29,7 @@ import {
   type RunContext,
 } from "../engine/api";
 import { canonicalPackageJsonOrder } from "./shared/key-order";
+import { ensureModuleVersion, INITIAL_MODULE_VERSION } from "./shared/initial-version";
 
 const KIND_EXPORTS = {
   ".": {
@@ -44,6 +45,7 @@ export function kindPackageJsonInitial(ctx: RunContext): Record<string, unknown>
   const v = ctx.blockVars;
   return {
     name: `${v.facadeName}.kind`,
+    version: INITIAL_MODULE_VERSION,
     private: true,
     type: "module",
     // `main` is the CommonJS entry (require fallback), `module` the ESM one —
@@ -81,7 +83,9 @@ export function kindPackageJsonInitial(ctx: RunContext): Record<string, unknown>
 export function kindPackageJsonRules(): void {
   // Controlled sibling — workspace-only, never published to npm. `private: true`
   // makes npm refuse to publish it; the `version` is kept (changesets-owned) and
-  // is what the kind's on-wire `{name}@{version}` reference is baked from.
+  // is what the kind's on-wire `{name}@{version}` reference is baked from — only
+  // backfilled when the manifest predates the seeded field.
+  ensureModuleVersion();
   ensureField("private", true);
 
   ensureField("type", "module");

package/src/structure/rules/model-package-json.ts

@@ -28,6 +28,7 @@ import {
 } from "../engine/api";
 import { scopeDepMaps } from "../engine/ctx";
 import { canonicalPackageJsonOrder } from "./shared/key-order";
+import { ensureModuleVersion, INITIAL_MODULE_VERSION } from "./shared/initial-version";
 import { COLOCATED_TEST_GLOB } from "./shared/colocated-tests";
 import { removeRetiredToolchainDeps } from "./shared/retired-deps";
 
@@ -35,6 +36,7 @@ export function modelPackageJsonInitial(ctx: RunContext): Record<string, unknown
   const v = ctx.blockVars;
   return {
     name: `${v.facadeName}.model`,
+    version: INITIAL_MODULE_VERSION,
     private: true,
     type: "module",
     // The block-model build emits both index.cjs and index.js. `main` is
@@ -77,7 +79,9 @@ export function modelPackageJsonInitial(ctx: RunContext): Record<string, unknown
 export function modelPackageJsonRules(): void {
   // Controlled sibling — workspace-only, never published. `private: true` makes
   // npm refuse to publish it; the `version` is kept (changesets-owned) so the
-  // packed template's lib carries a version.
+  // packed template's lib carries a version, and backfilled when the manifest
+  // predates the seeded field.
+  ensureModuleVersion();
   ensureField("private", true);
 
   ensureField("type", "module");

package/src/structure/rules/root-changeset-config.ts

@@ -0,0 +1,61 @@
+// Root `.changeset/config.json`. CI runs `pnpm run version-packages`
+// (`changeset version`) on every PR and sets `require-package-path-bump`, so a
+// block without this file fails its first CI run with "There is no .changeset
+// folder".
+//
+// Managed, not fixed: `$schema` is whatever `changeset init` last wrote (seven
+// versions are in use across the blocks) and `fixed`/`linked`/`ignore` are
+// author-owned lists. Only the fields CI depends on are re-asserted.
+
+import { ensureField, enforceFieldOrder } from "../engine/api";
+
+/** Seeded so the scaffold's own PR passes the `require-package-path-bump` gate
+ *  without bumping: `changeset version` consumes it and leaves the facade at
+ *  `INITIAL_MODULE_VERSION`, so the first version a user sees is 1.0.0 rather
+ *  than 1.0.1. Seeded (not managed) — a refresh must never resurrect it once
+ *  the first release has consumed it. */
+export const EMPTY_CHANGESET_SEED = `---
+---
+
+Initial release.
+`;
+
+const CHANGELOG = "@changesets/cli/changelog";
+const ACCESS = "restricted";
+const BASE_BRANCH = "main";
+const UPDATE_INTERNAL_DEPENDENCIES = "patch";
+
+const FIELD_ORDER = [
+  "$schema",
+  "changelog",
+  "commit",
+  "fixed",
+  "linked",
+  "access",
+  "baseBranch",
+  "updateInternalDependencies",
+  "ignore",
+];
+
+export function rootChangesetConfigInitial(): Record<string, unknown> {
+  return {
+    $schema: "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+    changelog: CHANGELOG,
+    commit: false,
+    fixed: [],
+    linked: [],
+    access: ACCESS,
+    baseBranch: BASE_BRANCH,
+    updateInternalDependencies: UPDATE_INTERNAL_DEPENDENCIES,
+    ignore: [],
+  };
+}
+
+export function rootChangesetConfigRules(): void {
+  ensureField("changelog", CHANGELOG);
+  ensureField("commit", false);
+  ensureField("access", ACCESS);
+  ensureField("baseBranch", BASE_BRANCH);
+  ensureField("updateInternalDependencies", UPDATE_INTERNAL_DEPENDENCIES);
+  enforceFieldOrder(FIELD_ORDER);
+}

package/src/structure/rules/root-package-json.ts

@@ -15,6 +15,7 @@ import {
   enforceFieldOrder,
 } from "../engine/api";
 import { canonicalPackageJsonOrder } from "./shared/key-order";
+import { INITIAL_MODULE_VERSION } from "./shared/initial-version";
 
 // `variant=all` builds every variant the software declares — docker-vs-binary is not a per-script
 // choice. `no-software` builds placeholder software for validators.
@@ -42,7 +43,7 @@ export function rootPackageJsonInitial(): Record<string, unknown> {
   // No `name`: the root is never published. Body rules re-assert
   // (removeField("name")) as a drift-corrector.
   return {
-    version: "1.0.0",
+    version: INITIAL_MODULE_VERSION,
     private: true,
     scripts: {
       fmt: "turbo run fmt",

package/src/structure/rules/root-pnpm-workspace.ts

@@ -30,7 +30,9 @@ export const SDK_CATALOG_PACKAGES: readonly string[] = [
   "@platforma-sdk/ui-vue",
   "@platforma-sdk/workflow-tengo",
   "@platforma-sdk/test",
+  "@platforma-sdk/block-kind",
   "@platforma-sdk/block-tools",
+  "@platforma-sdk/block-kind",
   "@platforma-sdk/tengo-builder",
   "@platforma-sdk/package-builder",
   "@milaboratories/ts-builder",
@@ -63,6 +65,7 @@ export const INFRA_CATALOG_FLOOR: Record<string, string> = {
   shx: "~0.4.0",
   "@changesets/cli": "~2.29.8",
   vitest: "~4.0.18",
+  typescript: "~5.9.3",
 };
 
 /** Catalog entries whose exact version is DERIVED from the version another

package/src/structure/rules/root.ts

@@ -3,11 +3,16 @@
 // skip this whole scope: the parent monorepo owns root files. Hence the
 // `when(({ ctx }) => !ctx.isSdkInternal, ...)` wrapper.
 
-import { scope, when, fixed, managed, file, generate } from "../engine/api";
+import { scope, when, fixed, managed, seed, file, text, generate } from "../engine/api";
 import { rootPackageJsonInitial, rootPackageJsonRules } from "./root-package-json";
 import { rootTurboJsonInitial, rootTurboJsonRules } from "./root-turbo-json";
 import { rootPnpmWorkspaceInitial, rootPnpmWorkspaceRules } from "./root-pnpm-workspace";
 import { rootGitignoreRules } from "./root-gitignore";
+import {
+  rootChangesetConfigInitial,
+  rootChangesetConfigRules,
+  EMPTY_CHANGESET_SEED,
+} from "./root-changeset-config";
 
 export function rootRules(): void {
   scope("root", () => {
@@ -42,6 +47,15 @@ export function rootRules(): void {
         managed(".gitignore", file("root/.gitignore"), () => {
           rootGitignoreRules();
         });
+
+        managed(
+          ".changeset/config.json",
+          generate(() => rootChangesetConfigInitial()),
+          () => {
+            rootChangesetConfigRules();
+          },
+        );
+        seed(".changeset/scaffold.md", text(EMPTY_CHANGESET_SEED));
       },
     );
   });