@platforma-sdk/block-tools 2.10.13 → 2.10.15

package/src/structure/engine/version.ts

@@ -0,0 +1,60 @@
+// `.structure` metadata file — read/write + floor check.
+//
+// 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_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_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;
+  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;
+  } catch {
+    return 0;
+  }
+}
+
+/** Throw if version is below floor. */
+export function assertVersionAboveFloor(
+  version: number,
+  floor: number = STRUCTURE_MIN_SUPPORTED,
+): void {
+  if (version < floor) {
+    throw new StructureVersionFloorError(version, floor);
+  }
+}
+
+export class StructureVersionFloorError extends Error {
+  constructor(
+    public readonly version: number,
+    public readonly floor: number,
+  ) {
+    super(
+      `Block .structure version is ${version}, below floor ${floor}. ` +
+        `Bootstrap via the legacy-migration skill, then re-run.`,
+    );
+    this.name = "StructureVersionFloorError";
+  }
+}
+
+export function writeStructureVersion(fs: FileSystem, version: number = STRUCTURE_VERSION): void {
+  const payload: StructureMeta = { version };
+  // Compact, single-line — this is a tiny machine file, no pretty-print.
+  fs.write(STRUCTURE_META_FILE, JSON.stringify(payload));
+}

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

@@ -0,0 +1,164 @@
+// `block-tools structure init` constructor: collects BlockVars from CLI
+// flags (prompting for any missing field unless --non-interactive),
+// assembles `ctx.modules` via the shared `modulesForInit`, and runs the
+// engine in init mode against a NodeFileSystem rooted at the target dir.
+//
+// Replaces the manual `git clone platforma-block-boilerplate` workflow
+// and `pl-dev create-block`. `--platform` is single-valued: a
+// freshly-init'd block has at most one software module.
+
+import { confirm, input, select } from "@inquirer/prompts";
+import { NodeFileSystem } from "./engine/fs/node";
+import { NodeTemplateProvider } from "./engine/templates";
+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 type { BlockVars } from "./engine/api";
+
+/** Platform choices `init` can scaffold a software module for. Python is
+ *  the only platform with a real, buildable scaffold at v1; any other
+ *  value is rejected rather than scaffolded as a non-buildable placeholder,
+ *  which would defeat the "init must produce a working block" intent.
+ *  `softwarePlatform` stays in BlockVars for when another platform gets a
+ *  real scaffold. (Note: Tengo is the workflow language, not a software
+ *  platform.) */
+export const SUPPORTED_PLATFORMS = ["python"] as const;
+
+export type InitFlagValues = {
+  npmOrg?: string;
+  orgScope?: string;
+  shortName?: string;
+  /** Tri-state: true (--with-software), false (--no-software),
+   *  undefined (unspecified → prompt or, non-interactive, default off). */
+  withSoftware?: boolean;
+  platform?: string;
+  nonInteractive: boolean;
+};
+
+export type InitInput = {
+  /** Resolved BlockVars (from `resolveBlockVars`). */
+  vars: BlockVars;
+  /** Resolved absolute target directory. */
+  blockPath: string;
+  /** `<block-tools>/src/structure/templates`. */
+  templatesRoot: string;
+  log: (msg: string) => void;
+};
+
+class InitFlagError extends Error {
+  constructor(flag: string) {
+    super(
+      `Missing required flag --${flag} in --non-interactive mode. ` +
+        `Supply every BlockVars flag, or drop --non-interactive to be prompted.`,
+    );
+    this.name = "InitFlagError";
+  }
+}
+
+async function need(
+  value: string | undefined,
+  flag: string,
+  nonInteractive: boolean,
+  prompt: () => Promise<string>,
+): Promise<string> {
+  if (value !== undefined && value !== "") return value;
+  if (nonInteractive) throw new InitFlagError(flag);
+  return prompt();
+}
+
+/** Resolve the full BlockVars (incl. softwarePlatform) from flags +
+ *  prompts. */
+export async function resolveBlockVars(flags: InitFlagValues): Promise<BlockVars> {
+  const npmOrg = await need(flags.npmOrg, "npm-org", flags.nonInteractive, () =>
+    input({ message: "npm org (e.g. @platforma-open):", default: "@platforma-open" }),
+  );
+  const orgScope = await need(flags.orgScope, "org-scope", flags.nonInteractive, () =>
+    input({ message: "org scope (e.g. my-org):" }),
+  );
+  const shortName = await need(flags.shortName, "short-name", flags.nonInteractive, () =>
+    input({ message: "block short name (e.g. mixcr-clonotyping):" }),
+  );
+
+  // Software: explicit flag wins; otherwise prompt (interactive) or
+  // default off (non-interactive).
+  let hasSoftware: boolean;
+  if (flags.withSoftware !== undefined) {
+    hasSoftware = flags.withSoftware;
+  } else if (flags.nonInteractive) {
+    hasSoftware = false;
+  } else {
+    hasSoftware = await confirm({ message: "Include a software module?", default: false });
+  }
+
+  let softwarePlatform: string | undefined;
+  if (hasSoftware) {
+    softwarePlatform = await need(flags.platform, "platform", flags.nonInteractive, () =>
+      select({
+        message: "Software platform:",
+        choices: SUPPORTED_PLATFORMS.map((p) => ({ name: p, value: p })),
+      }),
+    );
+    if (!(SUPPORTED_PLATFORMS as readonly string[]).includes(softwarePlatform)) {
+      throw new Error(
+        `Unsupported --platform '${softwarePlatform}'. ` +
+          `Only ${SUPPORTED_PLATFORMS.join(", ")} ${
+            SUPPORTED_PLATFORMS.length === 1 ? "is" : "are"
+          } supported at v1.`,
+      );
+    }
+  } else if (flags.platform) {
+    throw new Error("--platform was given but software is disabled (--no-software).");
+  }
+
+  const facadeName = `${npmOrg}/${orgScope}.${shortName}`;
+  return {
+    facadeName,
+    baseName: `${orgScope}.${shortName}`,
+    npmOrg,
+    orgScope,
+    shortName,
+    softwarePlatform,
+  };
+}
+
+export async function runInit(init: InitInput): Promise<BlockVars> {
+  const vars = init.vars;
+  const modules = modulesForInit(vars);
+
+  const fs = new NodeFileSystem(init.blockPath);
+  const templates = new NodeTemplateProvider(init.templatesRoot);
+  const ctx = createRunContext({
+    blockVars: vars,
+    modules,
+    isSdkInternal: false,
+    version: STRUCTURE_VERSION,
+    dryRun: false,
+  });
+
+  // Init REQUIRES network: resolve the SDK catalog families to npm latest
+  // before the run, so the generated block carries real current versions
+  // (no placeholders). The names come from the SDK catalog package list —
+  // there is no on-disk pnpm-workspace.yaml to read yet. A registry failure
+  // aborts init rather than silently shipping an unresolved placeholder.
+  const sdkNames = SDK_CATALOG_PACKAGES.filter(matchesBumpPattern);
+  let registryLookup: (name: string) => string | undefined;
+  try {
+    registryLookup = await buildRegistryLookupForNames(sdkNames);
+  } catch (err) {
+    throw new Error(
+      `init requires network access to resolve SDK catalog versions from npm, ` +
+        `but the registry lookup failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  engineRun(STRUCTURE, fs, ctx, { templates, initMode: true, registryLookup });
+  init.log(
+    `Initialised block '${vars.facadeName}'${
+      vars.softwarePlatform ? ` (software: ${vars.softwarePlatform})` : " (no software)"
+    } at ${init.blockPath}`,
+  );
+  return vars;
+}

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

@@ -0,0 +1,156 @@
+// Block-level (orchestrator) `package.json`: the initial generator and the
+// drift-correcting body rules, co-located. Workspace-scope deps reflect the
+// discovered modules at run time; the generator pre-computes them and the
+// body rule re-asserts them.
+
+import {
+  ensureField,
+  ensureScript,
+  ensureDevDep,
+  ensureWorkspaceScopeDeps,
+  enforceAlphabeticalOrder,
+  enforceFieldOrder,
+  type RunContext,
+} from "../engine/api";
+import { getActiveRunContext } from "../engine/builders";
+import { findModules, scopeDepMap } from "../engine/ctx";
+import { canonicalPackageJsonOrder } from "./shared/key-order";
+
+/** The facade's `block.components` map: the dist artifact each module build
+ *  emits, keyed by role. Fully determined by the discovered modules — the
+ *  body rule re-asserts this exact value, so it is engine-managed (NOT an
+ *  author seed). Mirrors the artifact paths produced by each scope's build:
+ *  workflow → pl-tengo, model → build-model, ui → ts-builder. */
+export function blockComponents(ctx: RunContext): Record<string, string> {
+  const components: Record<string, string> = {};
+  for (const m of findModules(ctx, "workflow"))
+    components.workflow = `${m.name}/dist/tengo/tpl/main.plj.gz`;
+  for (const m of findModules(ctx, "model")) components.model = `${m.name}/dist/model.json`;
+  for (const m of findModules(ctx, "ui")) components.ui = `${m.name}/dist`;
+  return components;
+}
+
+/** Fail loudly if any required `block.*` field is empty — a missing
+ *  title / description / logo / organization or empty components map would
+ *  otherwise produce an init block that `block-tools pack` rejects only
+ *  later. Asserted at generation time so the failure is immediate. */
+function assertBlockFieldsFilled(block: {
+  components: Record<string, string>;
+  meta: Record<string, unknown>;
+}): void {
+  if (Object.keys(block.components).length === 0) {
+    throw new Error("block.components is empty — no workflow/model/ui module was discovered");
+  }
+  const meta = block.meta as {
+    title?: unknown;
+    description?: unknown;
+    logo?: unknown;
+    organization?: { name?: unknown; url?: unknown; logo?: unknown };
+  };
+  const required: [string, unknown][] = [
+    ["block.meta.title", meta.title],
+    ["block.meta.description", meta.description],
+    ["block.meta.logo", meta.logo],
+    ["block.meta.organization.name", meta.organization?.name],
+    ["block.meta.organization.url", meta.organization?.url],
+    ["block.meta.organization.logo", meta.organization?.logo],
+  ];
+  for (const [path, value] of required) {
+    if (typeof value !== "string" || value === "") {
+      throw new Error(`required block field '${path}' is empty`);
+    }
+  }
+}
+
+export function blockPackageJsonInitial(ctx: RunContext): Record<string, unknown> {
+  const v = ctx.blockVars;
+  // The facade depends on its model / ui / workflow modules — not on its
+  // software module (the workflow owns that dep) and not on its test module
+  // (the test package depends on the facade, so a reciprocal dep would be a
+  // pnpm/turbo cycle).
+  const deps: Record<string, string> = {
+    ...scopeDepMap(ctx, "model"),
+    ...scopeDepMap(ctx, "ui"),
+    ...scopeDepMap(ctx, "workflow"),
+  };
+  // `block.components` is engine-managed (re-asserted by the body rule);
+  // `block.meta` is an author SEED — written once at init, never touched on
+  // refresh, so the author owns title / description / organization / logo.
+  // `block-tools pack` requires both. The author edits the placeholder meta
+  // before publishing.
+  const block = {
+    components: blockComponents(ctx),
+    meta: {
+      title: v.shortName,
+      description: `${v.shortName} block`,
+      logo: "file:logos/block-logo.png",
+      organization: {
+        name: v.orgScope,
+        url: "https://example.com",
+        logo: "file:logos/organization-logo.png",
+      },
+    },
+  };
+  assertBlockFieldsFilled(block);
+  return {
+    name: `${v.facadeName}.block`,
+    version: "1.0.0",
+    // type:"module" intentionally omitted.
+    files: ["index.d.ts", "index.js"],
+    scripts: {
+      build: "shx rm -rf ./block-pack && block-tools pack",
+      "mark-stable":
+        "block-tools mark-stable -r 's3://milab-euce1-prod-pkgs-s3-block-registry/pub/releases/?region=eu-central-1'",
+      prepublishOnly:
+        "block-tools pack && block-tools publish -r 's3://milab-euce1-prod-pkgs-s3-block-registry/pub/releases/?region=eu-central-1'",
+      "do-pack": "shx rm -f *.tgz && block-tools pack && pnpm pack && shx mv *.tgz package.tgz",
+    },
+    dependencies: deps,
+    devDependencies: { "@platforma-sdk/block-tools": "sdk:", shx: "catalog:" },
+    block,
+  };
+}
+
+export function blockPackageJsonRules(): void {
+  // type:"module" intentionally omitted: the facade's index.js is the
+  // CommonJS dev-block descriptor (module.exports / __dirname); ESM would
+  // break it. The facade has no TS sources to compile.
+  ensureField("files", ["index.d.ts", "index.js"]);
+
+  ensureScript("build", "shx rm -rf ./block-pack && block-tools pack");
+  ensureScript(
+    "mark-stable",
+    "block-tools mark-stable -r 's3://milab-euce1-prod-pkgs-s3-block-registry/pub/releases/?region=eu-central-1'",
+  );
+  ensureScript(
+    "prepublishOnly",
+    "block-tools pack && block-tools publish -r 's3://milab-euce1-prod-pkgs-s3-block-registry/pub/releases/?region=eu-central-1'",
+  );
+  ensureScript(
+    "do-pack",
+    "shx rm -f *.tgz && block-tools pack && pnpm pack && shx mv *.tgz package.tgz",
+  );
+
+  // One workspace dep per discovered module in the facade's scopes. The
+  // facade depends on model / ui / workflow — not software (the workflow
+  // owns it) and not test (a reciprocal dep would be a pnpm/turbo cycle).
+  ensureWorkspaceScopeDeps("model");
+  ensureWorkspaceScopeDeps("ui");
+  ensureWorkspaceScopeDeps("workflow");
+
+  ensureDevDep("@platforma-sdk/block-tools", "sdk:");
+  // shx powers the cross-platform build / do-pack scripts above.
+  ensureDevDep("shx", "catalog:");
+
+  // `block.components` is fully determined by the discovered modules — keep
+  // it in sync on refresh. `block.meta` is deliberately NOT touched here: it
+  // is an author-owned seed (set once in the init package.json), so refresh
+  // must never overwrite the author's title / description / logo.
+  ensureField("block.components", blockComponents(getActiveRunContext()));
+
+  enforceAlphabeticalOrder("dependencies");
+  enforceAlphabeticalOrder("devDependencies");
+  enforceAlphabeticalOrder("peerDependencies");
+  enforceAlphabeticalOrder("optionalDependencies");
+  enforceFieldOrder([...canonicalPackageJsonOrder]);
+}

package/src/structure/rules/block.ts

@@ -0,0 +1,29 @@
+// Block-scope rules — the orchestrator package at `block/`.
+// Workspace-scope deps in the body resolve from ctx.modules.
+
+import { scope, fixed, managed, seed, file, binaryFile, generate } from "../engine/api";
+import { getActiveRunContext } from "../engine/builders";
+import { blockPackageJsonInitial, blockPackageJsonRules } from "./block-package-json";
+
+export function blockRules(): void {
+  scope("block", () => {
+    fixed("index.js", file("block/index.js"));
+    fixed("index.d.ts", file("block/index.d.ts"));
+
+    // Placeholder logos referenced by `block.meta` (logo + organization.logo).
+    // Binary seeds: written once at init, author-owned thereafter — refresh
+    // never overwrites them, so a custom logo survives. `block-tools pack`
+    // embeds these into the block pack; without them pack would fail on the
+    // `file:logos/...` meta references.
+    seed("logos/block-logo.png", binaryFile("block/logos/block-logo.png"));
+    seed("logos/organization-logo.png", binaryFile("block/logos/organization-logo.png"));
+
+    managed(
+      "package.json",
+      generate(() => blockPackageJsonInitial(getActiveRunContext())),
+      () => {
+        blockPackageJsonRules();
+      },
+    );
+  });
+}

package/src/structure/rules/migrations.ts

@@ -0,0 +1,63 @@
+// Migrations + legacy cleanup live here.
+//
+// Two patterns coexist:
+//
+// 1. One-shot migrations gated on filesystem state. Folder renames,
+//    cross-cutting one-time transforms. Use `when(pathExists/pathMissing)`
+//    so the migration fires once and is idempotent on subsequent runs.
+//
+// 2. Legacy cleanup primitives. Unconditional `removeScript`,
+//    `removeDep`, `remove(path)` calls naming artefacts the canonical
+//    layout never produces. Idempotent by definition (no-op on absent
+//    keys/paths). Each line is a one-way decision: every block converges.
+
+import { scope, remove, managed, generate, removeScript, removeDep } from "../engine/api";
+import { getActiveRunContext } from "../engine/builders";
+import { rootPackageJsonInitial } from "./root-package-json";
+
+export function testFrameworkMigration(): void {
+  // No active rename-bearing migration yet. Reserved for the test
+  // framework rollout.
+}
+
+// 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.
+//
+// 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.
+  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)
+  });
+  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)
+  });
+  scope("test", () => {
+    remove("eslint.config.mjs"); // all 5 experiment blocks
+  });
+
+  // Root-scope cleanup. The second `managed("package.json")` body composes
+  // after rootRules.
+  scope("root", () => {
+    remove(".prettierrc"); // samples-and-data, sequence-properties (prettier → oxfmt)
+    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
+      },
+    );
+  });
+}

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

@@ -0,0 +1,123 @@
+// Model `package.json`: the initial generator and the drift-correcting body
+// rules, co-located. Identity (name/version) stays untouched; the body
+// enforces type/main/types/exports + canonical scripts + canonical dep sets,
+// then projects canonical field / dependency order.
+//
+// Authored oxfmt-clean: the model is one of the two scopes `ts-builder
+// check` runs oxfmt on, so neither half enforces field / dependency ordering
+// beyond what oxfmt itself produces — the enforce* calls match oxfmt's order
+// exactly, so refreshing a legacy block yields oxfmt-clean output and the
+// build→check gate (oxfmt --check) passes without a prior `pnpm fmt`.
+
+import {
+  ensureField,
+  ensureScript,
+  ensureDep,
+  ensureDevDep,
+  ensureDevDeps,
+  ensurePeerDeps,
+  enforceAlphabeticalOrder,
+  enforceFieldOrder,
+  when,
+  whenFilesExist,
+  type RunContext,
+} from "../engine/api";
+import { canonicalPackageJsonOrder } from "./shared/key-order";
+import { COLOCATED_TEST_GLOB } from "./shared/colocated-tests";
+
+export function modelPackageJsonInitial(ctx: RunContext): Record<string, unknown> {
+  const v = ctx.blockVars;
+  return {
+    name: `${v.facadeName}.model`,
+    version: "1.0.0",
+    type: "module",
+    // The block-model build emits both index.cjs and index.js. `main` is
+    // the CommonJS entry (require fallback); `module` the ESM entry.
+    main: "dist/index.cjs",
+    module: "dist/index.js",
+    types: "dist/index.d.ts",
+    exports: {
+      ".": {
+        types: "./dist/index.d.ts",
+        sources: "./src/index.ts",
+        import: "./dist/index.js",
+      },
+      "./dist/*": "./dist/*",
+    },
+    scripts: {
+      fmt: "ts-builder format",
+      watch: "ts-builder build --target block-model --watch",
+      build: "ts-builder build --target block-model && block-tools build-model",
+      check: "ts-builder check --target block-model",
+      // No `test`: the vitest `test` script is wired by the body rule ONLY
+      // when co-located test files exist (a freshly-init'd model has none).
+    },
+    dependencies: {
+      "@platforma-sdk/model": "sdk:",
+    },
+    devDependencies: {
+      "@milaboratories/ts-builder": "sdk:",
+      "@milaboratories/ts-configs": "sdk:",
+      "@platforma-sdk/block-tools": "sdk:",
+      vitest: "catalog:",
+    },
+    peerDependencies: {
+      "@types/node": "*",
+      typescript: "*",
+    },
+  };
+}
+
+export function modelPackageJsonRules(): void {
+  ensureField("type", "module");
+  // build emits both; main = CJS entry, module = ESM entry (prod convention).
+  ensureField("main", "dist/index.cjs");
+  ensureField("module", "dist/index.js");
+  ensureField("types", "dist/index.d.ts");
+  ensureField("exports", {
+    ".": {
+      types: "./dist/index.d.ts",
+      sources: "./src/index.ts",
+      import: "./dist/index.js",
+    },
+    "./dist/*": "./dist/*",
+  });
+
+  ensureScript("fmt", "ts-builder format");
+  ensureScript("watch", "ts-builder build --target block-model --watch");
+  ensureScript("build", "ts-builder build --target block-model && block-tools build-model");
+  ensureScript("check", "ts-builder check --target block-model");
+
+  ensureDep("@platforma-sdk/model", "sdk:");
+
+  ensureDevDeps({
+    "@milaboratories/ts-builder": "sdk:",
+    "@milaboratories/ts-configs": "sdk:",
+    "@platforma-sdk/block-tools": "sdk:",
+    vitest: "catalog:",
+  });
+
+  ensurePeerDeps({
+    "@types/node": "*",
+    typescript: "*",
+  });
+
+  // The vitest `test` script + node ambient types are wired ONLY when the
+  // model carries co-located unit tests (`src/**/*.test.ts`). A test-less
+  // model gets neither — turbo simply has no `test` task for it, and the
+  // scope stays a refresh fixpoint. When tests ARE present, `@types/node`
+  // is promoted from peer to a devDep (the single-section invariant drops
+  // the peer) so the tests' `node:*` imports resolve under the
+  // `types: ["node"]` that model/tsconfig adds under the same predicate.
+  // Runs AFTER ensurePeerDeps so the promotion is not reverted.
+  when(whenFilesExist(COLOCATED_TEST_GLOB), () => {
+    ensureScript("test", "vitest run --passWithNoTests");
+    ensureDevDep("@types/node", "*");
+  });
+
+  enforceAlphabeticalOrder("dependencies");
+  enforceAlphabeticalOrder("devDependencies");
+  enforceAlphabeticalOrder("peerDependencies");
+  enforceAlphabeticalOrder("optionalDependencies");
+  enforceFieldOrder([...canonicalPackageJsonOrder]);
+}

package/src/structure/rules/model.ts

@@ -0,0 +1,65 @@
+// Model-scope rules. Static config files + managed package.json; the
+// `src/index.ts` seed is dropped by `init` and never touched again
+// (block author owns it).
+
+import {
+  scope,
+  fixed,
+  managed,
+  seed,
+  file,
+  generate,
+  when,
+  whenFilesExist,
+  ensureField,
+  removeField,
+  pruneKeysMatching,
+} from "../engine/api";
+import { getActiveRunContext } from "../engine/builders";
+import { modelPackageJsonInitial, modelPackageJsonRules } from "./model-package-json";
+import { COLOCATED_TEST_GLOB } from "./shared/colocated-tests";
+
+export function modelRules(): void {
+  scope("model", () => {
+    // tsconfig is managed (not fixed) so node ambient types can be provided
+    // CONDITIONALLY. The body still enforces the canonical shape —
+    // `{extends, include}` with NO stray keys — and, ONLY when the model
+    // carries co-located unit tests (`src/**/*.test.ts`), adds
+    // `compilerOptions.types: ["node"]` so those tests type-check: provide
+    // node types, do NOT exclude the tests. A test-less model is
+    // canonicalised to bare `{extends, include}`
+    // and stays a refresh fixpoint. The matching `@types/node` devDep is
+    // wired by the package.json rule under the same predicate.
+    managed("tsconfig.json", file("model/tsconfig.json"), () => {
+      ensureField("extends", "@milaboratories/ts-configs/block/model");
+      // Canonical default carries no compilerOptions; drop any legacy block's
+      // before (conditionally) re-adding only `types`.
+      removeField("compilerOptions");
+      when(whenFilesExist(COLOCATED_TEST_GLOB), () => {
+        ensureField("compilerOptions.types", ["node"]);
+      });
+      ensureField("include", ["src/**/*"]);
+      // Strip anything else a legacy tsconfig carried (files, references, a
+      // different extends layout) — keep only the canonical keys.
+      pruneKeysMatching((k) => k !== "extends" && k !== "include" && k !== "compilerOptions");
+    });
+    fixed(".oxlintrc.json", file("model/.oxlintrc.json"));
+    fixed(".oxfmtrc.json", file("model/.oxfmtrc.json"));
+
+    // A minimal-but-REAL BlockModelV3: `build-model` rejects a non-model
+    // export ("Malformed model object"), and a bare `.create(dataModel)`
+    // still errors ("Args rendering function not set"). This seed is the
+    // smallest chain that produces a valid `dist/model.json` — empty data
+    // model, identity args, a single "Main" section. The block author owns
+    // and extends it after init.
+    seed("src/index.ts", file("model/src/index.ts"));
+
+    managed(
+      "package.json",
+      generate(() => modelPackageJsonInitial(getActiveRunContext())),
+      () => {
+        modelPackageJsonRules();
+      },
+    );
+  });
+}