@platforma-sdk/block-tools 2.14.4 → 2.14.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-sdk/block-tools",
-  "version": "2.14.4",
+  "version": "2.14.6",
   "description": "Utility to manipulate Platforma Blocks and Block Registry",
   "license": "UNLICENSED",
   "bin": {
@@ -35,13 +35,13 @@
     "yaml": "^2.8.0",
     "zod": "~3.25.76",
     "@milaboratories/pl-http": "1.2.4",
-    "@milaboratories/pl-model-common": "1.48.0",
+    "@milaboratories/pl-model-backend": "1.4.23",
     "@milaboratories/pl-model-middle-layer": "1.32.0",
+    "@milaboratories/pl-model-common": "1.48.0",
     "@milaboratories/resolve-helper": "1.1.3",
-    "@milaboratories/ts-helpers": "1.8.6",
     "@platforma-sdk/blocks-deps-updater": "2.2.0",
-    "@milaboratories/pl-model-backend": "1.4.22",
-    "@platforma-sdk/package-builder-lib": "1.3.0"
+    "@platforma-sdk/package-builder-lib": "1.3.0",
+    "@milaboratories/ts-helpers": "1.8.6"
   },
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^16.0.1",
@@ -57,8 +57,8 @@
     "vite-plugin-dts": "^5.0.3",
     "vitest": "^4.1.3",
     "@milaboratories/ts-builder": "1.7.2",
-    "@milaboratories/ts-configs": "1.4.0",
-    "@milaboratories/build-configs": "2.0.1"
+    "@milaboratories/build-configs": "2.0.1",
+    "@milaboratories/ts-configs": "1.4.0"
   },
   "scripts": {
     "build": "vite build",

package/src/structure/__tests__/kind-bootstrap.test.ts

@@ -0,0 +1,136 @@
+// A block written before kinds existed carries no `kind/` package, so
+// DISCOVERY finds no kind module. `refresh` must BOOTSTRAP the package rather
+// than fail: DISCOVERY synthesises the module (discovery-fs.ts) and the kind
+// rules then write it. Before this, the facade rule threw
+// `declares no kind` before a single file was touched, and the only way
+// forward was to hand-craft `kind/package.json` so discovery could see it.
+
+import { describe, test, expect } from "vitest";
+import { parse as parseYaml } from "yaml";
+import type { BlockVars } from "../engine/api";
+import { simulateInit, defaultTemplateProvider } from "../engine/testing";
+import { discoverRunContext } from "../engine/discovery-fs";
+import { run as engineRun } from "../engine/runner";
+import { STRUCTURE } from "../structure-definition";
+import type { MemoryFileSystem } from "../engine/fs/memory";
+
+const VARS: BlockVars = {
+  facadeName: "@platforma-open/test-org.demo",
+  baseName: "test-org.demo",
+  npmOrg: "@platforma-open",
+  orgScope: "test-org",
+  shortName: "demo",
+};
+
+/** The packages `init` wires to the kind: the model depends on it, the facade
+ *  carries it as a devDependency. */
+const KIND_DEPENDENTS = ["model/package.json", "block/package.json"];
+
+type DepSections = {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+};
+
+const DEP_SECTIONS = ["dependencies", "devDependencies", "peerDependencies"] as const;
+
+/** Every `<facade>.kind` reference the file declares, in any dep section. */
+function kindDepsOf(fs: MemoryFileSystem, path: string): string[] {
+  const pkg = JSON.parse(fs.read(path)) as DepSections;
+  return DEP_SECTIONS.flatMap((s) => Object.keys(pkg[s] ?? {})).filter((d) => d.endsWith(".kind"));
+}
+
+/** Drop every `<facade>.kind` reference from one package.json. */
+function stripKindDeps(fs: MemoryFileSystem, path: string): void {
+  const pkg = JSON.parse(fs.read(path)) as DepSections;
+  for (const section of DEP_SECTIONS) {
+    const deps = pkg[section];
+    if (!deps) continue;
+    for (const name of Object.keys(deps)) if (name.endsWith(".kind")) delete deps[name];
+  }
+  fs.write(path, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+/** A canonical block with every trace of its kind stripped back off — the shape
+ *  a pre-kind block has on disk. The package, the workspace entry AND the
+ *  dependencies its siblings declare on it all have to go: leaving the deps
+ *  behind would make the wiring assertions below pass without a bootstrap. */
+function preKindBlock(): MemoryFileSystem {
+  const { fs } = simulateInit({ vars: VARS });
+  for (const p of Object.keys(fs.snapshot())) {
+    if (p === "kind" || p.startsWith("kind/")) fs.delete(p);
+  }
+  const ws = parseYaml(fs.read("pnpm-workspace.yaml")) as { packages: string[] };
+  ws.packages = ws.packages.filter((p) => p !== "kind");
+  fs.write("pnpm-workspace.yaml", `packages:\n${ws.packages.map((p) => `  - ${p}\n`).join("")}`);
+  for (const p of KIND_DEPENDENTS) stripKindDeps(fs, p);
+  return fs;
+}
+
+function refresh(fs: MemoryFileSystem) {
+  const ctx = discoverRunContext({ fs, isSdkInternal: false });
+  return engineRun(STRUCTURE, fs, ctx, { templates: defaultTemplateProvider() });
+}
+
+describe("refresh bootstraps a missing kind package", () => {
+  test("DISCOVERY synthesises the kind module", () => {
+    const ctx = discoverRunContext({ fs: preKindBlock(), isSdkInternal: false });
+    const kind = ctx.modules.filter((m) => m.scope === "kind");
+    expect(kind).toHaveLength(1);
+    expect(kind[0]).toMatchObject({
+      name: "@platforma-open/test-org.demo.kind",
+      path: "kind",
+    });
+  });
+
+  test("refresh writes the package, its configs and the params sentinel", () => {
+    const fs = preKindBlock();
+    expect(fs.exists("kind/package.json")).toBe(false);
+
+    refresh(fs);
+
+    expect(fs.exists("kind/package.json")).toBe(true);
+    expect(fs.exists("kind/tsconfig.json")).toBe(true);
+    expect(fs.exists("kind/.oxlintrc.json")).toBe(true);
+    expect(fs.exists("kind/.oxfmtrc.json")).toBe(true);
+
+    const pkg = JSON.parse(fs.read("kind/package.json")) as {
+      name: string;
+      dependencies: Record<string, string>;
+    };
+    expect(pkg.name).toBe("@platforma-open/test-org.demo.kind");
+    expect(pkg.dependencies).toHaveProperty("@platforma-sdk/block-kind");
+
+    // The entry point is a `scaffold`, so it lands on refresh too — a `seed`
+    // would have left the package without one.
+    expect(fs.read("kind/src/index.ts")).toContain("NEEDS_BLOCK_PARAMS");
+  });
+
+  test("the bootstrapped kind joins the workspace and its dependents", () => {
+    const fs = preKindBlock();
+
+    // The fixture really is kind-free: nothing declares the dep yet, so the
+    // assertions after the refresh can only pass by way of the bootstrap.
+    for (const p of KIND_DEPENDENTS) expect(kindDepsOf(fs, p)).toEqual([]);
+
+    refresh(fs);
+
+    const ws = parseYaml(fs.read("pnpm-workspace.yaml")) as { packages: string[] };
+    expect(ws.packages).toContain("kind");
+
+    for (const p of KIND_DEPENDENTS) {
+      expect(kindDepsOf(fs, p)).toEqual(["@platforma-open/test-org.demo.kind"]);
+    }
+  });
+
+  test("a second refresh is a fixpoint — the sentinel is never rewritten", () => {
+    const fs = preKindBlock();
+    refresh(fs);
+    fs.write("kind/src/index.ts", "// the author's own contract\n");
+
+    const changes = refresh(fs).changes;
+
+    expect(changes).toHaveLength(0);
+    expect(fs.read("kind/src/index.ts")).toBe("// the author's own contract\n");
+  });
+});

package/src/structure/engine/discovery-fs.ts

@@ -197,6 +197,19 @@ export function discoverRunContext(input: DiscoverInput): RunContext {
   const facadeName = blockMod.name.replace(/\.block$/, "");
   const blockVars = parseBlockVars(facadeName);
 
+  // A kind is a mandatory block component, but a block written before kinds
+  // existed has no `kind/` package on disk, so DISCOVERY finds no kind module
+  // and every kind rule fans out over nothing. Synthesise the module the same
+  // way `init` does (`modulesForInit`) so a plain `structure refresh`
+  // BOOTSTRAPS the package: the managed `package.json` and the fixed configs
+  // are written from their generators, `src/index.ts` lands as a scaffold, and
+  // `kind` joins `packages:` because `ensureWorkspaceModulePaths` reads
+  // `ctx.modules`. Without this a pre-kind block could only be migrated by
+  // hand-crafting the package first — `refresh` threw before touching a file.
+  if (!modules.some((m) => m.scope === "kind")) {
+    modules.push({ scope: "kind", name: `${facadeName}.kind`, path: "kind" });
+  }
+
   return createRunContext({
     isSdkInternal,
     updateDepsOnly: input.updateDepsOnly ?? false,

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

@@ -200,8 +200,11 @@ export function blockPackageJsonRules(ctx: RunContext): void {
   const v = ctx.blockVars;
 
   // The kind is a MANDATORY block component: every block must declare exactly
-  // one sibling `kind/` package. Fail loudly otherwise — a kind-less block is
-  // invalid, and this is what surfaces the not-yet-migrated blocks.
+  // one sibling `kind/` package. DISCOVERY synthesises the module when the
+  // package is absent, so `refresh` bootstraps it instead of failing here and
+  // the zero branch is an invariant guard rather than the migration signal it
+  // once was. Two or more kinds stay a hard error — nothing can pick between
+  // them.
   const kindModules = findModules(ctx, "kind");
   if (kindModules.length !== 1) {
     throw new Error(

package/src/structure/rules/kind.ts

@@ -1,10 +1,11 @@
 // Kind-scope rules. Static config files + managed package.json; the
-// `src/index.ts` seed is dropped by `init` and never touched again (the block
-// author owns the BlockParams contract). The seed is a deliberate non-building
-// sentinel — its BlockParams is undefined, so a scaffolded-but-unmigrated block
-// fails to typecheck until the params contract is chosen on purpose.
+// `src/index.ts` scaffold is dropped once, on whichever run first finds it
+// missing, and never touched again — the block author owns the BlockParams
+// contract. What lands is a deliberate non-building sentinel: its BlockParams
+// is undefined, so a scaffolded-but-unmigrated block fails to typecheck until
+// the params contract is chosen on purpose.
 
-import { scope, fixed, managed, seed, file, generate } from "../engine/api";
+import { scope, fixed, managed, scaffold, file, generate } from "../engine/api";
 import { kindPackageJsonInitial, kindPackageJsonRules } from "./kind-package-json";
 
 export function kindRules(): void {
@@ -16,7 +17,13 @@ export function kindRules(): void {
     // Minimal-but-real kind: identity imported from the package's own
     // package.json, plus a non-building BlockParams sentinel the block author
     // must resolve (via the migration recipe or by hand) before the block builds.
-    seed("src/index.ts", file("kind/src/index.ts"));
+    //
+    // `scaffold`, not `seed`: create-if-missing in EVERY mode, so `refresh`
+    // bootstrapping a kind for a pre-kind block deposits the sentinel too. A
+    // seed is init-only, which would have left such a block with a kind package
+    // that has no entry point. Once the file exists the engine never touches it
+    // — the params contract belongs to the block author.
+    scaffold("src/index.ts", file("kind/src/index.ts"));
 
     managed(
       "package.json",