@platforma-sdk/block-tools 2.11.10 → 2.12.0

package/src/structure/engine/version.ts

@@ -3,30 +3,28 @@
 // Single JSON file at the block root holding the layout-version
 // integer and (in future) any other structurer metadata. Two
 // constants govern lifecycle gates:
-//   - STRUCTURE_VERSION       : latest known. Initial value 1.
+//   - STRUCTURE_VERSION       : latest known. v2 = software-build layout.
 //   - STRUCTURE_MIN_SUPPORTED : floor. Initial value 0.
 // Both are bumped by structurer releases; rule predicates may consult
 // `ctx.version` for one-shot version-gated transitions.
 
 import type { FileSystem } from "./fs/api";
 
-export const STRUCTURE_VERSION = 1;
+export const STRUCTURE_VERSION = 2;
 export const STRUCTURE_MIN_SUPPORTED = 0;
 /** Block-relative path of the structurer metadata file. */
 export const STRUCTURE_META_FILE = ".structure";
 
 export type StructureMeta = { version: number };
 
-/** Read `.structure`. Missing file or invalid payload → 0. */
-export function readStructureVersion(fs: FileSystem): number {
-  if (!fs.exists(STRUCTURE_META_FILE)) return 0;
+/** Read `.structure`. Missing file or invalid payload → version 0. */
+export function readStructureMeta(fs: FileSystem): StructureMeta {
+  if (!fs.exists(STRUCTURE_META_FILE)) return { version: 0 };
   try {
-    const raw = fs.read(STRUCTURE_META_FILE);
-    const parsed = JSON.parse(raw) as Partial<StructureMeta>;
-    if (typeof parsed?.version === "number") return parsed.version;
-    return 0;
+    const parsed = JSON.parse(fs.read(STRUCTURE_META_FILE)) as Partial<StructureMeta>;
+    return { version: typeof parsed?.version === "number" ? parsed.version : 0 };
   } catch {
-    return 0;
+    return { version: 0 };
   }
 }
 
@@ -53,8 +51,8 @@ export class StructureVersionFloorError extends Error {
   }
 }
 
-export function writeStructureVersion(fs: FileSystem, version: number = STRUCTURE_VERSION): void {
-  const payload: StructureMeta = { version };
+/** Write `.structure`. Writes a fresh payload rather than merging. */
+export function writeStructureMeta(fs: FileSystem, meta: StructureMeta): void {
   // Compact, single-line — this is a tiny machine file, no pretty-print.
-  fs.write(STRUCTURE_META_FILE, JSON.stringify(payload));
+  fs.write(STRUCTURE_META_FILE, JSON.stringify(meta));
 }

package/src/structure/rules/migrations.ts

@@ -49,7 +49,7 @@ export function legacyCleanup(): void {
     remove(".prettierrc");
     managed(
       "package.json",
-      generate((ctx) => rootPackageJsonInitial(ctx)),
+      generate(() => rootPackageJsonInitial()),
       () => {
         // `pretty` (prettier) is superseded by `fmt` (oxfmt); the standalone
         // deps-updater is now part of block-tools.

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

@@ -13,11 +13,32 @@ import {
   pruneKeysMatching,
   enforceAlphabeticalOrder,
   enforceFieldOrder,
-  type RunContext,
 } from "../engine/api";
 import { canonicalPackageJsonOrder } from "./shared/key-order";
 
-export function rootPackageJsonInitial(_ctx: RunContext): Record<string, unknown> {
+// `variant=all` builds every variant the software declares — docker-vs-binary is not a per-script
+// choice. `no-software` builds placeholder software for validators.
+
+const BUILD_SCRIPTS: Record<string, string> = {
+  "build:dev-local":
+    "env PL_BUILD_CHANNEL=dev PL_BUILD_VARIANT=all PL_BUILD_LOCATION=local turbo run build",
+  "build:dev-remote":
+    "env PL_BUILD_CHANNEL=dev PL_BUILD_VARIANT=all PL_BUILD_LOCATION=remote turbo run build",
+  "build:dev-no-software": "env PL_BUILD_CHANNEL=dev PL_BUILD_VARIANT=none turbo run build",
+  "build:dev-binary-existing":
+    "env PL_BUILD_CHANNEL=dev PL_BUILD_USE_PUBLISHED=true turbo run build",
+  "build:release":
+    "env PL_BUILD_CHANNEL=release PL_BUILD_VARIANT=all PL_BUILD_LOCATION=remote turbo run build",
+};
+
+// `test` / `test:dry-run` run the build-then-test DAG in the dev-binary-local target; the live
+// backend's env reaches the integration tests via the turbo `test` task's passThroughEnv.
+const TEST_SCRIPTS: Record<string, string> = {
+  test: `env PL_BUILD_CHANNEL=dev PL_BUILD_VARIANT=binary PL_BUILD_LOCATION=local turbo run test --concurrency 1`,
+  "test:dry-run": `env PL_BUILD_CHANNEL=dev PL_BUILD_VARIANT=binary PL_BUILD_LOCATION=local turbo run test --dry-run=json`,
+};
+
+export function rootPackageJsonInitial(): Record<string, unknown> {
   // No `name`: the root is never published. Body rules re-assert
   // (removeField("name")) as a drift-corrector.
   return {
@@ -26,10 +47,8 @@ export function rootPackageJsonInitial(_ctx: RunContext): Record<string, unknown
     scripts: {
       fmt: "turbo run fmt",
       check: "turbo run check",
-      build: "turbo run build",
-      "build:dev": "env PL_PKG_DEV=local turbo run build",
-      test: "env PL_PKG_DEV=local turbo run test --concurrency 1",
-      "test:dry-run": "env PL_PKG_DEV=local turbo run test --dry-run=json",
+      ...BUILD_SCRIPTS,
+      ...TEST_SCRIPTS,
       "mark-stable": "turbo run mark-stable",
       "do-pack": "turbo run do-pack",
       watch: "turbo watch build",
@@ -61,16 +80,21 @@ export function rootPackageJsonRules(): void {
   // Root is never published — it carries no `name`; delete any stray one.
   removeField("name");
 
-  // Canonical lifecycle script set. `test` / `test:dry-run` carry the
-  // PL_PKG_DEV wrapper; the live backend's env reaches the integration
-  // tests via the turbo `test` task's passThroughEnv (no --env-mode=loose
-  // needed).
+  // Canonical lifecycle script set. The live backend's env reaches the
+  // integration tests via the turbo `test` task's passThroughEnv (no
+  // --env-mode=loose needed).
   ensureScript("fmt", "turbo run fmt");
   ensureScript("check", "turbo run check");
-  ensureScript("build", "turbo run build");
-  ensureScript("build:dev", "env PL_PKG_DEV=local turbo run build");
-  ensureScript("test", "env PL_PKG_DEV=local turbo run test --concurrency 1");
-  ensureScript("test:dry-run", "env PL_PKG_DEV=local turbo run test --dry-run=json");
+  for (const [name, command] of Object.entries(BUILD_SCRIPTS)) {
+    ensureScript(name, command);
+  }
+  for (const [name, command] of Object.entries(TEST_SCRIPTS)) {
+    ensureScript(name, command);
+  }
+  // No bare `build` — a developer must pick a scenario (`build:dev-local`, `build:release`,
+  // …). Drop the legacy plain `build` and the old single `build:dev` so migrated blocks converge.
+  removeScript("build");
+  removeScript("build:dev");
   ensureScript("mark-stable", "turbo run mark-stable");
   ensureScript("do-pack", "turbo run do-pack");
   ensureScript("watch", "turbo watch build");

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

@@ -75,9 +75,16 @@ export const INFRA_CATALOG_FLOOR: Record<string, string> = {
  *  3.5.x than ui-vue's, yielding two vue instances and a SdkPluginV3-vs-Plugin
  *  type clash in `main.ts`. Deriving the pin from ui-vue's declared dep keeps
  *  the block in lockstep with whatever vue ui-vue's npm-latest pins, with no
- *  hand-maintained version here. */
+ *  hand-maintained version here.
+ *
+ *  `@milaboratories/helpers`: the block's model/ui depend on it (catalog:) and
+ *  `@platforma-sdk/model` pins it as an EXACT regular dependency. A hand-pinned
+ *  floor that lags a model bump yields two helpers instances — the model's
+ *  inferred `platforma` type then references the SDK's copy, not the block's,
+ *  failing `tsc` with TS2742. Deriving from model keeps them in lockstep. */
 export const DERIVED_CATALOG_PINS: readonly DerivedCatalogPin[] = [
   { entry: "vue", of: "@platforma-sdk/ui-vue" },
+  { entry: "@milaboratories/helpers", of: "@platforma-sdk/model" },
 ];
 
 /** Catalog name of the python runenv. Added to a block's catalog only when

package/src/structure/rules/root.ts

@@ -18,7 +18,7 @@ export function rootRules(): void {
 
         managed(
           "package.json",
-          generate((ctx) => rootPackageJsonInitial(ctx)),
+          generate(() => rootPackageJsonInitial()),
           () => {
             rootPackageJsonRules();
           },

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

@@ -12,13 +12,21 @@ import {
   ensureField,
   removeField,
   ensureScript,
-  ensureDevDeps,
+  removeScript,
+  ensureDevDep,
+  removeDep,
   enforceAlphabeticalOrder,
   enforceFieldOrder,
   type RunContext,
 } from "../engine/api";
 import { canonicalPackageJsonOrder } from "./shared/key-order";
 
+// The software-build build/pack commands, shared by the generator and the reconciler. block-tools
+// bundles the build engine, so these are the only build-tool commands a software-build block runs.
+const BUILD_CMD = "block-tools software build";
+const DO_PACK_CMD =
+  "shx rm -f *.tgz && block-tools software build && pnpm pack && shx mv platforma-open*.tgz package.tgz";
+
 /** The `block-software` package-builder descriptor for a python
  *  entrypoint. Kept opaque by the engine; rule authors edit it via
  *  `transformAt("block-software", ...)`. The `:3.12.10` tag inside
@@ -45,21 +53,22 @@ function pythonBlockSoftware(): Record<string, unknown> {
 
 export function softwarePackageJsonInitial(ctx: RunContext): Record<string, unknown> {
   const v = ctx.blockVars;
+
   return {
     name: `${v.facadeName}.software`,
     type: "module",
     description: "Block Software",
     files: ["./dist/**/*"],
     scripts: {
-      build: "pl-pkg build",
-      prepublishOnly: "pl-pkg prepublish",
+      build: BUILD_CMD,
+      "do-pack": DO_PACK_CMD,
       changeset: "changeset",
       "version-packages": "changeset version",
     },
     "block-software": pythonBlockSoftware(),
     devDependencies: {
       "@platforma-open/milaboratories.runenv-python-3": "catalog:",
-      "@platforma-sdk/package-builder": "sdk:",
+      "@platforma-sdk/block-tools": "sdk:",
     },
   };
 }
@@ -74,15 +83,19 @@ export function softwarePackageJsonRules(): void {
   ensureField("type", "module");
   ensureField("files", ["./dist/**/*"]);
 
-  ensureScript("build", "pl-pkg build");
-  ensureScript("prepublishOnly", "pl-pkg prepublish");
+  // Lifecycle scripts. block-tools builds and packs; a block migrated off pl-pkg converges on
+  // refresh — the old `pl-pkg prepublish` upload step is dropped (build + push happen in `build`).
+  ensureScript("build", BUILD_CMD);
+  ensureScript("do-pack", DO_PACK_CMD);
+  removeScript("prepublishOnly");
   ensureScript("changeset", "changeset");
   ensureScript("version-packages", "changeset version");
 
-  ensureDevDeps({
-    "@platforma-open/milaboratories.runenv-python-3": "catalog:",
-    "@platforma-sdk/package-builder": "sdk:",
-  });
+  // Canonical devDeps. block-tools bundles the build engine, so the pl-pkg
+  // `@platforma-sdk/package-builder` dependency is dropped.
+  ensureDevDep("@platforma-open/milaboratories.runenv-python-3", "catalog:");
+  ensureDevDep("@platforma-sdk/block-tools", "sdk:");
+  removeDep("@platforma-sdk/package-builder");
 
   enforceAlphabeticalOrder("dependencies");
   enforceAlphabeticalOrder("devDependencies");

package/src/structure/templates/static/root/turbo.json

@@ -12,7 +12,21 @@
     "build": {
       "dependsOn": ["^build", "check"],
       "inputs": ["$TURBO_DEFAULT$"],
-      "env": ["PL_PKG_DEV", "PL_DOCKER_REGISTRY_PUSH_TO"],
+      "env": [
+        "PL_DOCKER_REGISTRY_PUSH_TO",
+        "PL_BUILD_CHANNEL",
+        "PL_BUILD_VARIANT",
+        "PL_BUILD_LOCATION",
+        "PL_BUILD_USE_PUBLISHED",
+        "PL_DEV_DOCKER_PUSH_URL",
+        "PL_DEV_DOCKER_PULL_URL",
+        "PL_DEV_BINARY_UPLOAD_URL",
+        "PL_RELEASE_DOCKER_PUSH_URL",
+        "PL_RELEASE_DOCKER_PULL_URL",
+        "PL_RELEASE_BINARY_UPLOAD_URL",
+        "PL_REGISTRY_PLATFORMA_OPEN_UPLOAD_URL"
+      ],
+      "passThroughEnv": ["AWS_*", "PL_AWS_*"],
       "outputs": ["./dist/**", "./block-pack/**", "./pkg-*.tgz"]
     },
     "build:dev": {