@platforma-sdk/block-tools 2.10.13 → 2.10.15

package/src/structure/rules/root-catalog-bump.ts

@@ -0,0 +1,77 @@
+// Catalog version-resolution + seeding rules. The single `onInitOrUpdate(...)`
+// frame here resolves the SDK catalog families to npm latest AND seeds any
+// missing standard catalog keys (SDK families + the curated infra floor +
+// the python runenv pin). Its leaves fire on `init` AND
+// `refresh --update-deps-only` (mode "init" + "updateDeps") — both mean
+// "write current versions" — and are skipped on a default refresh/check,
+// which leaves catalog versions exactly as the author/lockfile has them.
+//
+// The network value lives in `ensureCatalogLatest`, which reads prefetched
+// "latest" versions from the runner's `registryLookup` (the CLI / init
+// constructor prefetches the SDK catalog membership list before the run;
+// unit tests pass a mock). Seeding the SDK keys from the membership list
+// (not the on-disk catalog) is what fixes the install failures: a
+// migrated block that never carried `@milaboratories/ts-builder` etc. now
+// gets them ADDED on `--update-deps-only`, no manual catalog seed required.
+//
+// Wrapped in the same root-scope `when(!isSdkInternal)` guard as the rest of
+// the root rules — internal blocks get their catalog from the parent
+// monorepo, so catalog resolution never applies there.
+
+import {
+  onInitOrUpdate,
+  scope,
+  when,
+  managed,
+  generate,
+  ensureCatalogLatest,
+  ensureCatalogVersion,
+} from "../engine/api";
+import { getActiveRunContext } from "../engine/builders";
+import {
+  rootPnpmWorkspaceInitial,
+  SDK_CATALOG_PACKAGES,
+  INFRA_CATALOG_FLOOR,
+  RUNENV_PYTHON,
+  RUNENV_PYTHON_VERSION,
+} from "./root-pnpm-workspace";
+
+export function rootCatalogBumpRules(): void {
+  onInitOrUpdate(() => {
+    scope("root", () => {
+      when(
+        ({ ctx }) => !ctx.isSdkInternal,
+        () => {
+          // On init, the default root rules create pnpm-workspace.yaml from
+          // this same generator (the curated SDK placeholders + infra
+          // floor); this leaf then overwrites the SDK entries with npm
+          // latest (the floor entries are add-if-absent no-ops). On
+          // update-deps the file already exists, so `initial` is not
+          // exercised — but a ContentForm is required, so reuse the
+          // generator.
+          managed(
+            "pnpm-workspace.yaml",
+            generate(() => rootPnpmWorkspaceInitial(getActiveRunContext())),
+            () => {
+              // SDK families → npm latest, ADD-IF-ABSENT (seeds a migrated
+              // block's missing standard keys + overwrites the init
+              // placeholder).
+              for (const name of SDK_CATALOG_PACKAGES) ensureCatalogLatest(name);
+              // Curated infra floor → fixed version, ADD-IF-ABSENT (seeds
+              // shx/turbo/vitest/vue/changesets when missing; never touches a
+              // version the block already pins).
+              for (const [name, version] of Object.entries(INFRA_CATALOG_FLOOR)) {
+                ensureCatalogVersion(name, version);
+              }
+              // The python runenv pin is relevant only to software-bearing
+              // blocks; seed it add-if-absent when one is present.
+              if (getActiveRunContext().modules.some((m) => m.scope === "software")) {
+                ensureCatalogVersion(RUNENV_PYTHON, RUNENV_PYTHON_VERSION);
+              }
+            },
+          );
+        },
+      );
+    });
+  });
+}

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

@@ -0,0 +1,27 @@
+// Root `.gitignore` content rules.
+// The static template under templates/static/root/.gitignore carries the
+// canonical line set; the body re-asserts the same set via
+// `ensureGitignoreEntries` so any future edit that drops a required line
+// is restored.
+
+import { ensureGitignoreEntries } from "../engine/api";
+
+export const GITIGNORE_REQUIRED_LINES = [
+  ".test_auth.json",
+  "node_modules/",
+  "dist/",
+  "block-pack/",
+  "dev/",
+  "work/",
+  "log/",
+  ".turbo",
+  "vite.config.*.timestamp-*",
+  "software/**/*.tgz",
+  ".DS_Store",
+  ".vscode/sftp.json",
+  "test-dry-run.json",
+];
+
+export function rootGitignoreRules(): void {
+  ensureGitignoreEntries(GITIGNORE_REQUIRED_LINES);
+}

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

@@ -0,0 +1,119 @@
+// Root `package.json`: the initial generator and the drift-correcting body
+// rules, co-located. The body re-asserts the canonical scripts, devDeps,
+// peerDeps, and the final field-order projection (enforceFieldOrder is the
+// LAST call).
+
+import {
+  ensureField,
+  ensureScript,
+  ensureDevDeps,
+  ensurePeerDeps,
+  removeField,
+  pruneKeysMatching,
+  enforceAlphabeticalOrder,
+  enforceFieldOrder,
+  type RunContext,
+} from "../engine/api";
+import { canonicalPackageJsonOrder } from "./shared/key-order";
+
+export function rootPackageJsonInitial(_ctx: RunContext): 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",
+    private: true,
+    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",
+      "mark-stable": "turbo run mark-stable",
+      "do-pack": "turbo run do-pack",
+      watch: "turbo watch build",
+      changeset: "changeset",
+      "version-packages": "changeset version",
+      // Deprecated in favour of `update` (the full refresh → install →
+      // refresh → format flow); kept for compatibility.
+      "update-sdk": "block-tools structure refresh --update-deps-only",
+      update:
+        "block-tools structure refresh --update-deps-only && pnpm i && block-tools structure refresh && pnpm fmt",
+    },
+    peerDependencies: {
+      oxlint: "*",
+      oxfmt: "*",
+    },
+    devDependencies: {
+      "@changesets/cli": "catalog:",
+      "@milaboratories/ts-builder": "sdk:",
+      "@platforma-sdk/block-tools": "sdk:",
+      shx: "catalog:",
+      turbo: "catalog:",
+    },
+    packageManager: "pnpm@9.12.0",
+  };
+}
+
+export function rootPackageJsonRules(): void {
+  ensureField("packageManager", "pnpm@9.12.0");
+
+  // 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).
+  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");
+  ensureScript("mark-stable", "turbo run mark-stable");
+  ensureScript("do-pack", "turbo run do-pack");
+  ensureScript("watch", "turbo watch build");
+  ensureScript("changeset", "changeset");
+  ensureScript("version-packages", "changeset version");
+  // Deprecated in favour of `update`; kept for compatibility.
+  ensureScript("update-sdk", "block-tools structure refresh --update-deps-only");
+  // Full SDK-update flow: bump catalog (deps-only) → install → re-apply
+  // structure against the freshly-pulled deps → format the result, wrapped
+  // as one script. `pnpm fmt` (turbo run fmt) leaves the tree oxfmt-clean
+  // after the structural rewrite so a follow-up `pnpm check` passes.
+  ensureScript(
+    "update",
+    "block-tools structure refresh --update-deps-only && pnpm i && block-tools structure refresh && pnpm fmt",
+  );
+
+  ensureDevDeps({
+    "@changesets/cli": "catalog:",
+    "@milaboratories/ts-builder": "sdk:",
+    "@platforma-sdk/block-tools": "sdk:",
+    shx: "catalog:",
+    turbo: "catalog:",
+  });
+
+  ensurePeerDeps({
+    oxlint: "*",
+    oxfmt: "*",
+  });
+
+  // Strip committed dev-machine override clutter: keys like "//pnpm",
+  // "///pnpm", "--" carrying a pnpm/overrides sub-object (often absolute
+  // local paths). Left in place these are unknown top-level keys that oxfmt
+  // shoves past the canonical sections, breaking `oxfmt --check`.
+  pruneKeysMatching((key, value): boolean => {
+    if (!/^(\/\/|--)/.test(key)) return false;
+    if (typeof value !== "object" || value === null) return false;
+    const v = value as { pnpm?: unknown; overrides?: unknown };
+    return v.pnpm !== undefined || v.overrides !== undefined;
+  });
+
+  enforceAlphabeticalOrder("dependencies");
+  enforceAlphabeticalOrder("devDependencies");
+  enforceAlphabeticalOrder("peerDependencies");
+  enforceAlphabeticalOrder("optionalDependencies");
+  enforceFieldOrder([...canonicalPackageJsonOrder]);
+}

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

@@ -0,0 +1,103 @@
+// Root `pnpm-workspace.yaml`: the catalog membership, the initial generator,
+// and the drift-correcting body rules, co-located.
+//
+// The catalog is split in two:
+//   - SDK packages: `SDK_CATALOG_PACKAGES` is a list of package NAMES (catalog
+//     membership only — no versions). On init the `onInitOrUpdate` frame fetches
+//     npm latest for each (init requires network) and writes it; the keys must
+//     exist in the catalog first for that in-place bump to land, so the initial
+//     generator seeds them with an obviously-invalid placeholder that the bump
+//     always overwrites. No version is stored here and there is no fallback.
+//   - infra / tooling: a `~`-floored set we control deliberately. No rule
+//     ever fetches these — refresh leaves them untouched and update-deps
+//     does not match them. Bump the floor here when authoring the scaffold.
+//
+// Default refresh is purely structural: it verifies the workspace
+// `packages:` list matches the discovered modules and leaves every catalog
+// version exactly as the author/lockfile has it. Version resolution (writing
+// npm-latest for the SDK families) lives in the separate `onInitOrUpdate`
+// frame (`rootCatalogBumpRules`), which fires on init + update-deps only.
+
+import { ensureWorkspaceModulePaths, type RunContext } from "../engine/api";
+import { matchesBumpPattern } from "../engine/registry-client";
+
+/** SDK packages that live in the catalog (membership only — no versions).
+ *  Init fetches npm latest for each; refresh leaves them as the lockfile has
+ *  them. */
+export const SDK_CATALOG_PACKAGES: readonly string[] = [
+  "@platforma-sdk/model",
+  "@platforma-sdk/ui-vue",
+  "@platforma-sdk/workflow-tengo",
+  "@platforma-sdk/test",
+  "@platforma-sdk/block-tools",
+  "@platforma-sdk/tengo-builder",
+  "@platforma-sdk/package-builder",
+  "@milaboratories/ts-builder",
+  "@milaboratories/ts-configs",
+];
+
+/** Init-only catalog seed for every SDK package: an obviously-invalid version
+ *  the `onInitOrUpdate` bump always overwrites with npm latest. It exists only
+ *  so the catalog key is present for that in-place bump. It is never a
+ *  fallback — a real init requires network and overwrites it; were it ever to
+ *  reach a lockfile, `pnpm install` fails loudly on the unresolvable version. */
+const SDK_CATALOG_INIT_PLACEHOLDER = "0.0.0-init-must-fetch";
+
+// Invariant: every SDK package must be fetched on init (match a bump pattern),
+// or its placeholder would ship un-resolved. Caught at load time.
+for (const name of SDK_CATALOG_PACKAGES) {
+  if (!matchesBumpPattern(name)) {
+    throw new Error(
+      `SDK_CATALOG_PACKAGES entry '${name}' matches no catalog bump pattern; ` +
+        `its placeholder would never be resolved to npm latest on init. ` +
+        `Add it to CATALOG_BUMP_PATTERNS or move it to the infra floor.`,
+    );
+  }
+}
+
+/** Infra / tooling — a `~`-floored curated set. Not exact-pinned on refresh
+ *  and not bumped by update-deps. */
+export const INFRA_CATALOG_FLOOR: Record<string, string> = {
+  turbo: "~2.8.11",
+  shx: "~0.4.0",
+  "@changesets/cli": "~2.29.8",
+  vitest: "~4.0.18",
+  // The seeded ui depends on `vue` (catalog:). `@platforma-sdk/ui-vue` pins
+  // vue as an EXACT regular dependency (not a peer), so the block must pin the
+  // SAME exact version — a floated `~` lets the ui resolve a newer 3.5.x than
+  // ui-vue's, yielding two vue instances and a SdkPluginV3-vs-Plugin type
+  // clash in `main.ts`. Keep this in lockstep with ui-vue's vue pin.
+  vue: "3.5.24",
+};
+
+/** Catalog name of the python runenv. Added to a block's catalog only when
+ *  the block carries a software module. Pinned to an EXACT version — updating
+ *  the python runenv is an explicit author decision, never automatic. */
+export const RUNENV_PYTHON = "@platforma-open/milaboratories.runenv-python-3";
+export const RUNENV_PYTHON_VERSION = "1.8.2";
+
+export function rootPnpmWorkspaceInitial(ctx: RunContext): Record<string, unknown> {
+  // Non-root module paths only. The block root ("") is discovered
+  // implicitly and must never be written as a "." entry — listing it breaks
+  // turbo's task graph. Root stays in ctx.modules for rule fan-out.
+  const paths = ctx.modules
+    .filter((m) => m.path !== "")
+    .map((m) => m.path)
+    .sort();
+  // SDK packages first (placeholder, overwritten by the init bump), then the
+  // infra floor — matching the order the catalog is written.
+  const catalog: Record<string, string> = {};
+  for (const name of SDK_CATALOG_PACKAGES) catalog[name] = SDK_CATALOG_INIT_PLACEHOLDER;
+  Object.assign(catalog, INFRA_CATALOG_FLOOR);
+  if (ctx.modules.some((m) => m.scope === "software")) {
+    catalog[RUNENV_PYTHON] = RUNENV_PYTHON_VERSION;
+  }
+  return {
+    packages: paths,
+    catalog,
+  };
+}
+
+export function rootPnpmWorkspaceRules(): void {
+  ensureWorkspaceModulePaths();
+}

package/src/structure/rules/root.ts

@@ -0,0 +1,43 @@
+// Root-scope rules — apply only to the standalone block layout (the
+// pnpm workspace + tooling around the block). `--sdk-internal` blocks
+// 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 { getActiveRunContext } from "../engine/builders";
+import { rootPackageJsonInitial, rootPackageJsonRules } from "./root-package-json";
+import { rootPnpmWorkspaceInitial, rootPnpmWorkspaceRules } from "./root-pnpm-workspace";
+import { rootGitignoreRules } from "./root-gitignore";
+
+export function rootRules(): void {
+  scope("root", () => {
+    when(
+      ({ ctx }) => !ctx.isSdkInternal,
+      () => {
+        // see templates/static/root/turbo.json — verbatim canonical content.
+        fixed("turbo.json", file("root/turbo.json"));
+        fixed(".vscode/settings.json", file("root/.vscode/settings.json"));
+
+        managed(
+          "package.json",
+          generate(() => rootPackageJsonInitial(getActiveRunContext())),
+          () => {
+            rootPackageJsonRules();
+          },
+        );
+
+        managed(
+          "pnpm-workspace.yaml",
+          generate(() => rootPnpmWorkspaceInitial(getActiveRunContext())),
+          () => {
+            rootPnpmWorkspaceRules();
+          },
+        );
+
+        managed(".gitignore", file("root/.gitignore"), () => {
+          rootGitignoreRules();
+        });
+      },
+    );
+  });
+}

package/src/structure/rules/shared/colocated-tests.ts

@@ -0,0 +1,11 @@
+// Shared definition for co-located unit-test handling.
+//
+// A block's model / ui / workflow scope MAY carry co-located vitest unit
+// tests (`src/**/*.test.ts`, including nested `src/test/*.test.ts`). The
+// structurer wires the vitest `test` script and (for ui/model) node ambient
+// types into a scope ONLY when such files are present — so a test-less scope
+// stays free of a `test` script it would never run, and a freshly-init'd
+// (test-less) block remains a refresh fixpoint.
+
+/** Glob (module-relative) for co-located unit tests in a scope's `src/`. */
+export const COLOCATED_TEST_GLOB = "src/**/*.test.ts";

package/src/structure/rules/shared/key-order.ts

@@ -0,0 +1,34 @@
+// Canonical top-level key order for `package.json` files.
+// Used by `enforceFieldOrder(canonicalPackageJsonOrder)` at the end of
+// every `*-package-json.ts` body.
+// Per-block extensions: rules call
+// `enforceFieldOrder([...canonicalPackageJsonOrder, "customKey"])`.
+//
+// This order is derived EMPIRICALLY from oxfmt (the canonical formatter run
+// by `ts-builder check`): a freshly-refreshed package.json must pass
+// `oxfmt --check` so `pnpm check` is green without a prior `pnpm fmt`. oxfmt
+// also alphabetises the dependency sections — the `*-package-json.ts` bodies
+// call `enforceAlphabeticalOrder` on each dep section to match (scripts and
+// `exports` keep source order; oxfmt does not reorder them).
+export const canonicalPackageJsonOrder = [
+  "name",
+  "version",
+  "private",
+  "description",
+  "keywords",
+  "files",
+  "type",
+  "main",
+  "module",
+  "types",
+  "exports",
+  "scripts",
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+  "packageManager",
+  "pnpm",
+  "block",
+  "block-software",
+] as const;

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

@@ -0,0 +1,86 @@
+// Software `package.json`: the initial generator and the drift-correcting
+// body rules, co-located. One body, N modules — fan-out is driven by
+// `ctx.modules`.
+//
+// Drift-correctors only: identity (name/version), `description`, and the
+// `block-software` descriptor are author-owned / opaque and left untouched
+// — re-asserting them would clobber real multi-software blocks on refresh.
+// The body enforces the structural essentials: ESM type, the publish
+// `files` glob, the lifecycle scripts, and the canonical devDeps.
+
+import {
+  ensureField,
+  ensureScript,
+  ensureDevDeps,
+  enforceAlphabeticalOrder,
+  enforceFieldOrder,
+  type RunContext,
+} from "../engine/api";
+import { canonicalPackageJsonOrder } from "./shared/key-order";
+
+/** 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
+ *  `environment` is the runenv artifact tag (python version), distinct
+ *  from the npm catalog version. */
+function pythonBlockSoftware(): Record<string, unknown> {
+  return {
+    entrypoints: {
+      main: {
+        binary: {
+          artifact: {
+            type: "python",
+            registry: "platforma-open",
+            environment: "@platforma-open/milaboratories.runenv-python-3:3.12.10",
+            dependencies: { toolset: "pip", requirements: "requirements.txt" },
+            root: "./src",
+          },
+          cmd: ["python", "{pkg}/main.py"],
+        },
+      },
+    },
+  };
+}
+
+export function softwarePackageJsonInitial(ctx: RunContext): Record<string, unknown> {
+  const v = ctx.blockVars;
+  return {
+    name: `${v.facadeName}.software`,
+    version: "1.0.0",
+    type: "module",
+    description: "Block Software",
+    files: ["./dist/**/*"],
+    scripts: {
+      build: "pl-pkg build",
+      prepublishOnly: "pl-pkg prepublish",
+      changeset: "changeset",
+      "version-packages": "changeset version",
+    },
+    "block-software": pythonBlockSoftware(),
+    devDependencies: {
+      "@platforma-open/milaboratories.runenv-python-3": "catalog:",
+      "@platforma-sdk/package-builder": "sdk:",
+    },
+  };
+}
+
+export function softwarePackageJsonRules(): void {
+  ensureField("type", "module");
+  ensureField("files", ["./dist/**/*"]);
+
+  ensureScript("build", "pl-pkg build");
+  ensureScript("prepublishOnly", "pl-pkg prepublish");
+  ensureScript("changeset", "changeset");
+  ensureScript("version-packages", "changeset version");
+
+  ensureDevDeps({
+    "@platforma-open/milaboratories.runenv-python-3": "catalog:",
+    "@platforma-sdk/package-builder": "sdk:",
+  });
+
+  enforceAlphabeticalOrder("dependencies");
+  enforceAlphabeticalOrder("devDependencies");
+  enforceAlphabeticalOrder("peerDependencies");
+  enforceAlphabeticalOrder("optionalDependencies");
+  enforceFieldOrder([...canonicalPackageJsonOrder]);
+}

package/src/structure/rules/software.ts

@@ -0,0 +1,33 @@
+// Software-scope rules. One scope body, N modules — the engine fans out
+// once per discovered software module. Zero software modules → entire
+// scope body no-ops.
+//
+// Seeds (`software/src/main.py` + `requirements.txt`) are written once by
+// `init` and never touched again — the block author owns them.
+
+import { scope, managed, seed, generate, text } from "../engine/api";
+import { getActiveRunContext } from "../engine/builders";
+import { softwarePackageJsonInitial, softwarePackageJsonRules } from "./software-package-json";
+
+const MAIN_PY_SEED = `import sys
+
+print("Hello from Python, " + sys.argv[1] + "!")
+`;
+
+const REQUIREMENTS_SEED = `# No dependencies specified for this script
+`;
+
+export function softwareRules(): void {
+  scope("software", () => {
+    seed("src/main.py", text(MAIN_PY_SEED));
+    seed("src/requirements.txt", text(REQUIREMENTS_SEED));
+
+    managed(
+      "package.json",
+      generate(() => softwarePackageJsonInitial(getActiveRunContext())),
+      () => {
+        softwarePackageJsonRules();
+      },
+    );
+  });
+}

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

@@ -0,0 +1,70 @@
+// Test `package.json`: the initial generator and the drift-correcting body
+// rules, co-located.
+
+import {
+  ensureField,
+  ensureScript,
+  ensureDevDeps,
+  ensurePeerDeps,
+  removeDep,
+  enforceAlphabeticalOrder,
+  enforceFieldOrder,
+  type RunContext,
+} from "../engine/api";
+import { canonicalPackageJsonOrder } from "./shared/key-order";
+
+export function testPackageJsonInitial(ctx: RunContext): Record<string, unknown> {
+  const v = ctx.blockVars;
+  return {
+    name: `${v.facadeName}.test`,
+    version: "1.0.0",
+    private: true,
+    type: "module",
+    scripts: {
+      // Type-only check (no oxlint/oxfmt — the test scope ships no lint/fmt
+      // config). Slots into the turbo `check` task.
+      check: "ts-builder type-check --target block-test",
+      test: "vitest run --passWithNoTests",
+    },
+    peerDependencies: {
+      typescript: "*",
+    },
+    devDependencies: {
+      "@platforma-sdk/test": "sdk:",
+      "@milaboratories/ts-builder": "sdk:",
+      "@milaboratories/ts-configs": "sdk:",
+      vitest: "catalog:",
+    },
+  };
+}
+
+export function testPackageJsonRules(): void {
+  ensureField("type", "module");
+
+  // Type-only check (no oxlint/oxfmt — the test scope ships no lint/fmt
+  // config); slots into the turbo `check` task.
+  ensureScript("check", "ts-builder type-check --target block-test");
+  ensureScript("test", "vitest run --passWithNoTests");
+
+  // @platforma-sdk/test is a test-time dep → devDependencies (matches prod).
+  ensureDevDeps({
+    "@platforma-sdk/test": "sdk:",
+    "@milaboratories/ts-builder": "sdk:",
+    "@milaboratories/ts-configs": "sdk:",
+    vitest: "catalog:",
+  });
+
+  // The test tsconfig (@milaboratories/ts-configs/block/test) supplies the
+  // ambient types; only the `typescript` peer is needed. Drop any stray
+  // `@types/node` peer a legacy block declares.
+  ensurePeerDeps({
+    typescript: "*",
+  });
+  removeDep("@types/node");
+
+  enforceAlphabeticalOrder("dependencies");
+  enforceAlphabeticalOrder("devDependencies");
+  enforceAlphabeticalOrder("peerDependencies");
+  enforceAlphabeticalOrder("optionalDependencies");
+  enforceFieldOrder([...canonicalPackageJsonOrder]);
+}

package/src/structure/rules/test.ts

@@ -0,0 +1,40 @@
+// Test-scope rules.
+
+import { scope, fixed, managed, scaffold, seed, file, text, generate } from "../engine/api";
+import { getActiveRunContext } from "../engine/builders";
+import { testPackageJsonInitial, testPackageJsonRules } from "./test-package-json";
+
+export function testRules(): void {
+  scope("test", () => {
+    // tsconfig carries `files: []` alongside `include: ["src/**/*"]`: tsc
+    // errors TS18003 when an `include` matches nothing, so an empty `files`
+    // lets the check pass on a test-less block while `include` still
+    // type-checks real tests once present.
+    fixed("tsconfig.json", file("test/tsconfig.json"));
+    // scaffold (not fixed): integration tests legitimately tune timeout /
+    // retry per block. Write the canonical default if absent; never
+    // overwrite an author's config.
+    scaffold("vitest.config.mts", file("test/vitest.config.mts"));
+
+    // A trivial, backend-free demo test so a freshly-init'd block ships a
+    // runnable suite (`pnpm test` green out of the box) rather than an empty
+    // scope. Author-owned seed: written once at init, untouched on refresh.
+    seed(
+      "src/demo.test.ts",
+      text(
+        `import { expect, test } from "vitest";\n\n` +
+          `test("scaffolded block sanity check", () => {\n` +
+          `  expect(true).toBe(true);\n` +
+          `});\n`,
+      ),
+    );
+
+    managed(
+      "package.json",
+      generate(() => testPackageJsonInitial(getActiveRunContext())),
+      () => {
+        testPackageJsonRules();
+      },
+    );
+  });
+}