@platforma-sdk/block-tools 2.11.2 → 2.11.4

package/src/structure/engine/__tests__/discovery.test.ts

@@ -1,5 +1,5 @@
-// Workspace-package classification — covers all 7 detection rules
-// plus the block-scope override and the unclassified-error path.
+// Workspace-package classification — covers the detection rules plus the
+// block-scope override and the unclassified-error path.
 
 import { describe, test, expect } from "vitest";
 import { classifyOne, discoverModules, DiscoveryError, type WorkspacePackage } from "../discovery";
@@ -14,7 +14,7 @@ describe("discovery — single-package classification", () => {
       name: "x.software",
       "block-software": {},
     });
-    expect(classifyOne(wp, new Set())).toBe("software");
+    expect(classifyOne(wp)).toBe("software");
   });
 
   test("rule 1 alt: software via package-builder + runenv dep", () => {
@@ -25,67 +25,62 @@ describe("discovery — single-package classification", () => {
         "@platforma-open/runenv-python-3": "catalog:",
       },
     });
-    expect(classifyOne(wp, new Set())).toBe("software");
+    expect(classifyOne(wp)).toBe("software");
   });
 
-  test("rule 2: workflow via workflow-tengo dep", () => {
+  test("workflow via workflow-tengo dep", () => {
     const wp = pkg("workflow", {
       name: "x.workflow",
       dependencies: { "@platforma-sdk/workflow-tengo": "catalog:" },
     });
-    expect(classifyOne(wp, new Set())).toBe("workflow");
+    expect(classifyOne(wp)).toBe("workflow");
   });
 
-  test("rule 3: ui via ui-vue dep and no main", () => {
+  test("ui via ui-vue dep and no main", () => {
     const wp = pkg("ui", {
       name: "x.ui",
       dependencies: { "@platforma-sdk/ui-vue": "catalog:" },
     });
-    expect(classifyOne(wp, new Set())).toBe("ui");
+    expect(classifyOne(wp)).toBe("ui");
   });
 
-  test("rule 4: block via block-tools + sibling model/ui/workflow", () => {
-    const siblings = new Set(["x.model", "x.ui", "x.workflow"]);
+  test("block via the top-level `block` field", () => {
     const wp = pkg("block", {
       name: "x.block",
-      dependencies: {
-        "@platforma-sdk/block-tools": "catalog:",
-        "x.model": "workspace:*",
-        "x.ui": "workspace:*",
-      },
+      block: { components: {}, meta: {} },
     });
-    expect(classifyOne(wp, siblings)).toBe("block");
+    expect(classifyOne(wp)).toBe("block");
   });
 
-  test("rule 4 fallback: files=[index.d.ts,index.js] + block-tools", () => {
+  test("a block-tools-ish package WITHOUT a `block` field is not classified `block`", () => {
     const wp = pkg("block", {
       name: "x.block",
       files: ["index.d.ts", "index.js"],
       dependencies: { "@platforma-sdk/block-tools": "catalog:" },
     });
-    expect(classifyOne(wp, new Set())).toBe("block");
+    expect(classifyOne(wp)).toBeUndefined();
   });
 
-  test("rule 5: model via model dep + main", () => {
+  test("model via model dep + main", () => {
     const wp = pkg("model", {
       name: "x.model",
       main: "dist/index.js",
       dependencies: { "@platforma-sdk/model": "catalog:" },
     });
-    expect(classifyOne(wp, new Set())).toBe("model");
+    expect(classifyOne(wp)).toBe("model");
   });
 
-  test("rule 6: test via @platforma-sdk/test dep", () => {
+  test("test via @platforma-sdk/test dep", () => {
     const wp = pkg("test", {
       name: "x.test",
       devDependencies: { "@platforma-sdk/test": "catalog:" },
     });
-    expect(classifyOne(wp, new Set())).toBe("test");
+    expect(classifyOne(wp)).toBe("test");
   });
 
-  test("rule 7: root as catch-all", () => {
+  test("root as catch-all", () => {
     const wp = pkg("", { name: "x" });
-    expect(classifyOne(wp, new Set())).toBe("root");
+    expect(classifyOne(wp)).toBe("root");
   });
 
   test("override: block-scope wins over detection", () => {
@@ -94,7 +89,7 @@ describe("discovery — single-package classification", () => {
       "block-scope": "software",
       dependencies: { "@platforma-sdk/workflow-tengo": "catalog:" },
     });
-    expect(classifyOne(wp, new Set())).toBe("software");
+    expect(classifyOne(wp)).toBe("software");
   });
 
   test("override: bad value throws DiscoveryError", () => {
@@ -102,7 +97,7 @@ describe("discovery — single-package classification", () => {
       name: "x",
       "block-scope": "nope",
     });
-    expect(() => classifyOne(wp, new Set())).toThrow(DiscoveryError);
+    expect(() => classifyOne(wp)).toThrow(DiscoveryError);
   });
 
   test("unclassified non-root throws DiscoveryError", () => {
@@ -134,6 +129,7 @@ describe("discovery — full workspace", () => {
       }),
       pkg("block", {
         name: "x.block",
+        block: { components: {}, meta: {} },
         dependencies: {
           "@platforma-sdk/block-tools": "catalog:",
           "x.model": "workspace:*",

package/src/structure/engine/discovery.ts

@@ -25,6 +25,8 @@ export type PackageJsonLike = {
   devDependencies?: Record<string, string>;
   peerDependencies?: Record<string, string>;
   optionalDependencies?: Record<string, string>;
+  // Top-level `block` field — the unambiguous facade marker.
+  block?: unknown;
   // Override field — value MUST be one of the seven scopes.
   "block-scope"?: string;
   "block-software"?: unknown;
@@ -61,11 +63,9 @@ function isRoot(p: string): boolean {
  * Classify one package.
  *
  * @param wp The workspace package.
- * @param siblingNames Set of all workspace package `name`s (used by
- *   rule 4 "block": depends on ≥2 sibling .model/.ui/.workflow).
  * @returns Scope or `undefined` if unclassified.
  */
-export function classifyOne(wp: WorkspacePackage, siblingNames: Set<string>): Scope | undefined {
+export function classifyOne(wp: WorkspacePackage): Scope | undefined {
   const override = wp.pkg["block-scope"];
   if (typeof override === "string") {
     if (!(ALL_SCOPES as string[]).includes(override)) {
@@ -88,6 +88,12 @@ export function classifyOne(wp: WorkspacePackage, siblingNames: Set<string>): Sc
   // sub-package dirs), so this only ever fires in standalone mode.
   if (isRoot(wp.path)) return "root";
 
+  // block (facade) — a top-level `block` field is the unambiguous facade
+  // marker; no non-facade workspace package carries one. MUST precede the model
+  // rule: a migrated facade carries `@platforma-sdk/model` as a devDep plus
+  // `main`, which would otherwise match model.
+  if (wp.pkg.block !== undefined) return "block";
+
   const deps = depKeys(wp.pkg);
 
   // 1. software — top-level `block-software` field OR
@@ -107,30 +113,10 @@ export function classifyOne(wp: WorkspacePackage, siblingNames: Set<string>): Sc
     return "ui";
   }
 
-  // 4. block — block-tools in deps AND ≥2 sibling .model/.ui/.workflow.
-  if (deps.has("@platforma-sdk/block-tools")) {
-    const matches = [...deps].filter(
-      (d) =>
-        siblingNames.has(d) &&
-        (d.endsWith(".model") || d.endsWith(".ui") || d.endsWith(".workflow")),
-    );
-    if (matches.length >= 2) return "block";
-    // Fallback: `files == ["index.d.ts", "index.js"]` + block-tools.
-    const files = wp.pkg.files;
-    if (
-      Array.isArray(files) &&
-      files.length === 2 &&
-      files.includes("index.d.ts") &&
-      files.includes("index.js")
-    ) {
-      return "block";
-    }
-  }
-
-  // 5. model — @platforma-sdk/model in deps AND main is set.
+  // 4. model — @platforma-sdk/model in deps AND main is set.
   if (deps.has("@platforma-sdk/model") && wp.pkg.main) return "model";
 
-  // 6. test — @platforma-sdk/test in deps.
+  // 5. test — @platforma-sdk/test in deps.
   if (deps.has("@platforma-sdk/test")) return "test";
 
   // (root — the workspace root, path "", is classified above, before the
@@ -144,13 +130,9 @@ export function classifyOne(wp: WorkspacePackage, siblingNames: Set<string>): Sc
  * package.json.
  */
 export function discoverModules(packages: WorkspacePackage[]): Module[] {
-  const siblingNames = new Set<string>();
-  for (const p of packages) {
-    if (typeof p.pkg.name === "string") siblingNames.add(p.pkg.name);
-  }
   const out: Module[] = [];
   for (const p of packages) {
-    const scope = classifyOne(p, siblingNames);
+    const scope = classifyOne(p);
     if (!scope) {
       throw new DiscoveryError(
         `Unclassified workspace package at '${p.path}'. ` +

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

@@ -1,24 +1,67 @@
-// 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.
+// Facade `package.json`: the initial generator and the drift-correcting body
+// rules, co-located. The facade is the only sibling of a block that publishes,
+// and it ships SLIM: `dependencies` is empty (the consumer's install pulls zero
+// `@platforma-sdk/*` transitive runtime deps), siblings are build-time
+// `workspace:*` devDeps, and the built `dist/` + `block-pack/` carry everything
+// the loader needs.
 
 import {
   ensureField,
   ensureScript,
   ensureDevDep,
-  ensureWorkspaceScopeDeps,
+  ensureWorkspaceScopeDevDeps,
+  requireField,
+  removeScript,
   enforceAlphabeticalOrder,
   enforceFieldOrder,
   type RunContext,
 } from "../engine/api";
-import { findModules, scopeDepMap } from "../engine/ctx";
+import { findModules, scopeDepMaps } from "../engine/ctx";
 import { canonicalPackageJsonOrder } from "./shared/key-order";
 
+/** Per-org publish coordinates: the S3 upload bucket and the public registry
+ *  serve URL the facade's `prepublishOnly` script passes to `block-tools
+ *  publish`. One block-registry bucket serves both orgs; only the public read
+ *  hostname differs by org. Safe for the never-published `etc/blocks` test
+ *  blocks — the script never runs for them. Extend the map per new org. */
+const ORG_PUBLISH_TARGETS: Record<string, { s3: string; serveUrl: string }> = {
+  "@platforma-open": {
+    s3: "s3://milab-euce1-prod-pkgs-s3-block-registry/pub/releases/?region=eu-central-1",
+    serveUrl: "https://blocks.pl-open.science",
+  },
+  "@milaboratories": {
+    s3: "s3://milab-euce1-prod-pkgs-s3-block-registry/pub/releases/?region=eu-central-1",
+    serveUrl: "https://block.registry.platforma.bio/releases",
+  },
+};
+
+/** Fallback for an org not in the table — keeps the generated script valid
+ *  (and inert until published) rather than throwing during a refresh. */
+const FALLBACK_PUBLISH_TARGET = {
+  s3: "s3://milab-euce1-prod-pkgs-s3-block-registry/pub/releases/?region=eu-central-1",
+  serveUrl: "https://blocks.pl-open.science",
+};
+
+/** Where the in-SDK blocks (`etc/blocks/*`) publish: the aux/dev registry, not
+ *  production `pub/releases/`. These are the monorepo's test/example blocks, so
+ *  one target regardless of org — their `@milaboratories` scope must NOT route
+ *  them to the real catalog alongside standalone blocks. */
+const SDK_INTERNAL_PUBLISH_TARGET = {
+  s3: "s3://milab-euce1-prod-pkgs-s3-block-registry/aux/dev/?region=eu-central-1",
+  serveUrl: "https://aux-blocks.pl-open.science",
+};
+
+function prepublishScript(npmOrg: string, isSdkInternal: boolean): string {
+  const t = isSdkInternal
+    ? SDK_INTERNAL_PUBLISH_TARGET
+    : (ORG_PUBLISH_TARGETS[npmOrg] ?? FALLBACK_PUBLISH_TARGET);
+  return `block-tools publish -r ${t.s3} --registry-serve-url ${t.serveUrl}`;
+}
+
 /** 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:
+ *  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> = {};
@@ -29,6 +72,44 @@ export function blockComponents(ctx: RunContext): Record<string, string> {
   return components;
 }
 
+/** The slim facade's canonical scripts (build / check / prepublishOnly /
+ *  do-pack). Shared by the initial generator and the body rule so they cannot
+ *  drift apart. `prepublishOnly` routes by block kind: in-SDK blocks publish to
+ *  the aux/dev registry, standalone blocks to their per-org production target. */
+function blockScripts(npmOrg: string, isSdkInternal: boolean): Record<string, string> {
+  return {
+    build: "ts-builder build --target block-facade && block-tools pack",
+    check: "ts-builder type-check --target block-facade",
+    prepublishOnly: prepublishScript(npmOrg, isSdkInternal),
+    "do-pack": "pnpm pack && shx mv *.tgz package.tgz",
+  };
+}
+
+/** The facade's build/publish devDependencies (the workspace `model`/`ui`/
+ *  `workflow` siblings are added separately, from discovery). `sdk:` resolves
+ *  to `workspace:*` for in-monorepo blocks and `catalog:` for standalone — the
+ *  body rule re-asserts the same set. */
+const FACADE_DEV_DEPS = {
+  "@milaboratories/ts-builder": "sdk:",
+  "@milaboratories/ts-configs": "sdk:",
+  "@platforma-sdk/block-tools": "sdk:",
+  "@platforma-sdk/model": "sdk:",
+  shx: "catalog:",
+  typescript: "catalog:",
+} as const;
+
+/** The facade's `exports` map: a single `.` entry. `sources` keeps monorepo IDE
+ *  go-to-definition pointing at `src/` (external consumers don't enable it);
+ *  `types`/`default` carry the bundled `.d.ts` / `.js` from `dist/`. No
+ *  `./AGENTS` subpath — that surface ships as a registry-side component. */
+const FACADE_EXPORTS = {
+  ".": {
+    sources: "./src/index.ts",
+    types: "./dist/index.d.ts",
+    default: "./dist/index.js",
+  },
+};
+
 /** 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
@@ -63,20 +144,18 @@ function assertBlockFieldsFilled(block: {
 
 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"),
+  // The facade's siblings are build-time devDeps, never runtime deps — the
+  // facade ships its content bundled inside dist/ + block-pack/, so the
+  // consumer needs no runtime resolution into siblings. Software/test are
+  // excluded (the workflow owns software; a test→facade dep would be a cycle).
+  const devDeps: Record<string, string> = {
+    ...FACADE_DEV_DEPS,
+    ...scopeDepMaps(ctx, "model"),
+    ...scopeDepMaps(ctx, "ui"),
+    ...scopeDepMaps(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.
+  // `block-tools pack` requires both `block.components` and `block.meta`. The
+  // author edits the placeholder meta before publishing.
   const block = {
     components: blockComponents(ctx),
     meta: {
@@ -94,59 +173,62 @@ export function blockPackageJsonInitial(ctx: RunContext): Record<string, unknown
   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:" },
+    // Facade is ESM: rolldown-plugin-dts requires it, and the BlockPointer's
+    // `import.meta.url` path math needs it.
+    type: "module",
+    // Drives the npm tarball: only the built outputs ship; sources, tsconfig,
+    // and node_modules stay out.
+    files: ["dist", "block-pack"],
+    main: "./dist/index.js",
+    module: "./dist/index.js",
+    types: "./dist/index.d.ts",
+    exports: FACADE_EXPORTS,
+    scripts: blockScripts(v.npmOrg, ctx.isSdkInternal),
+    // Slim invariant: zero runtime deps reach the consumer.
+    dependencies: {},
+    devDependencies: devDeps,
     block,
   };
 }
 
 export function blockPackageJsonRules(ctx: RunContext): 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");
+  const v = ctx.blockVars;
+
+  ensureField("type", "module");
+  ensureField("files", ["dist", "block-pack"]);
+  ensureField("main", "./dist/index.js");
+  ensureField("module", "./dist/index.js");
+  ensureField("types", "./dist/index.d.ts");
+  ensureField("exports", FACADE_EXPORTS);
 
+  const scripts = blockScripts(v.npmOrg, ctx.isSdkInternal);
+  for (const [name, command] of Object.entries(scripts)) ensureScript(name, command);
+  removeScript("mark-stable");
+
+  // Slim invariant: the facade carries ZERO runtime dependencies. The siblings
+  // and the SDK build/publish deps are all devDeps, so `dependencies` ends
+  // empty. Software/test are excluded (the workflow owns software; a
+  // test→facade dep would be a cycle).
+  ensureWorkspaceScopeDevDeps("model");
+  ensureWorkspaceScopeDevDeps("ui");
+  ensureWorkspaceScopeDevDeps("workflow");
+  ensureDevDep("@milaboratories/ts-builder", "sdk:");
+  ensureDevDep("@milaboratories/ts-configs", "sdk:");
   ensureDevDep("@platforma-sdk/block-tools", "sdk:");
-  // shx powers the cross-platform build / do-pack scripts above.
+  ensureDevDep("@platforma-sdk/model", "sdk:");
   ensureDevDep("shx", "catalog:");
+  ensureDevDep("typescript", "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.
+  // `block.components` is fully determined by the discovered modules — keep it
+  // in sync on refresh. `block.meta` is deliberately NOT touched: 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(ctx));
 
+  // The author owns `name` and `version`; `version` MUST be present (the
+  // facade publishes).
+  requireField("version", "facade package.json must carry a 'version' (the facade publishes)");
+
   enforceAlphabeticalOrder("dependencies");
   enforceAlphabeticalOrder("devDependencies");
   enforceAlphabeticalOrder("peerDependencies");

package/src/structure/rules/block.ts

@@ -1,13 +1,48 @@
-// Block-scope rules — the orchestrator package at `block/`.
-// Workspace-scope deps in the body resolve from ctx.modules.
+// Block-scope rules — the facade package at `block/`. The facade is the
+// only sibling of a block that publishes: a slim 4-file `src/` surface
+// (engine-owned `index.ts` + `AGENTS.ts`, author-owned `block-extra.ts` +
+// `agents-extra.ts`), a facade `tsconfig.json`, and a slim publishable
+// `package.json`. Workspace-scope deps in the body resolve from ctx.modules.
 
-import { scope, fixed, managed, seed, file, binaryFile, generate } from "../engine/api";
+import {
+  scope,
+  fixed,
+  scaffold,
+  managed,
+  seed,
+  remove,
+  file,
+  tpl,
+  binaryFile,
+  generate,
+} from "../engine/api";
 import { blockPackageJsonInitial, blockPackageJsonRules } from "./block-package-json";
+import { pascalCase } from "./shared/pascal-case";
 
 export function blockRules(): void {
   scope("block", () => {
-    fixed("index.js", file("block/index.js"));
-    fixed("index.d.ts", file("block/index.d.ts"));
+    // `remove` is idempotent (absent file → no-op), so this is safe on a block
+    // that has no such entry files.
+    remove("index.js");
+    remove("index.d.ts");
+
+    // Four-file source surface. `index.ts` is engine-owned and per-block
+    // (model import path + `<PascalName>` aliases) → text-templated. `AGENTS.ts`
+    // is engine-owned and identical for every block → static. The two `*-extra`
+    // files are author scaffolds (`scaffold`: create-if-missing on every refresh,
+    // never overwritten).
+    fixed(
+      "src/index.ts",
+      tpl("block/src/index.tpl.ts", (ctx) => ({
+        facadeName: ctx.blockVars.facadeName,
+        pascalName: pascalCase(ctx.blockVars.shortName),
+      })),
+    );
+    fixed("src/AGENTS.ts", file("block/src/AGENTS.ts"));
+    scaffold("src/block-extra.ts", file("block/src/block-extra.ts"));
+    scaffold("src/agents-extra.ts", file("block/src/agents-extra.ts"));
+
+    fixed("tsconfig.json", file("block/tsconfig.json"));
 
     // Placeholder logos referenced by `block.meta` (logo + organization.logo).
     // Binary seeds: written once at init, author-owned thereafter — refresh

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

@@ -33,7 +33,7 @@ export function modelPackageJsonInitial(ctx: RunContext): Record<string, unknown
   const v = ctx.blockVars;
   return {
     name: `${v.facadeName}.model`,
-    version: "1.0.0",
+    private: true,
     type: "module",
     // The block-model build emits both index.cjs and index.js. `main` is
     // the CommonJS entry (require fallback); `module` the ESM entry.
@@ -70,6 +70,11 @@ 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.
+  ensureField("private", true);
+
   ensureField("type", "module");
   // build emits both; main = CJS entry, module = ESM entry (prod convention).
   ensureField("main", "dist/index.cjs");

package/src/structure/rules/shared/pascal-case.ts

@@ -0,0 +1,16 @@
+// `pascalCase(shortName)` → the block-named alias prefix the facade entry
+// template emits (`<PascalName>BlockContract`, …). Splits on any run of
+// non-alphanumeric characters and capitalises each segment's first char:
+//   test-sum-numbers-v3  → TestSumNumbersV3
+//   mixcr-clonotyping-2  → MixcrClonotyping2
+//   samples-and-data     → SamplesAndData
+export function pascalCase(s: string): string {
+  const joined = s
+    .split(/[^A-Za-z0-9]+/)
+    .filter((seg) => seg.length > 0)
+    .map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1))
+    .join("");
+  // A leading digit (e.g. `3d-viewer` → `3dViewer`) is not a valid identifier
+  // start — the prefix becomes `const 3dViewerBlockPointer = …`. Prepend `_`.
+  return /^[0-9]/.test(joined) ? `_${joined}` : joined;
+}

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

@@ -46,7 +46,7 @@ export function softwarePackageJsonInitial(ctx: RunContext): Record<string, unkn
   const v = ctx.blockVars;
   return {
     name: `${v.facadeName}.software`,
-    version: "1.0.0",
+    private: true,
     type: "module",
     description: "Block Software",
     files: ["./dist/**/*"],
@@ -65,6 +65,11 @@ export function softwarePackageJsonInitial(ctx: RunContext): Record<string, unkn
 }
 
 export function softwarePackageJsonRules(): void {
+  // Controlled sibling — workspace-only, never npm-published. (Software still
+  // publishes runenv artifacts via `pl-pkg`, which is unaffected by `private`.)
+  // The `version` is kept (changesets-owned) so the packed template carries it.
+  ensureField("private", true);
+
   ensureField("type", "module");
   ensureField("files", ["./dist/**/*"]);
 

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

@@ -19,7 +19,6 @@ 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: {
@@ -41,6 +40,11 @@ export function testPackageJsonInitial(ctx: RunContext): Record<string, unknown>
 }
 
 export function testPackageJsonRules(): void {
+  // Controlled sibling — workspace-only, never published. (The initial already
+  // seeds `private: true`; the body re-asserts it. The `version` is kept —
+  // changesets-owned — so the packed template's lib carries a version.)
+  ensureField("private", true);
+
   ensureField("type", "module");
 
   ensureScript("fmt", "ts-builder format");

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

@@ -32,7 +32,7 @@ export function uiPackageJsonInitial(ctx: RunContext): Record<string, unknown> {
   const v = ctx.blockVars;
   return {
     name: `${v.facadeName}.ui`,
-    version: "1.0.0",
+    private: true,
     type: "module",
     scripts: {
       fmt: "ts-builder format",
@@ -60,6 +60,10 @@ export function uiPackageJsonInitial(ctx: RunContext): Record<string, unknown> {
 }
 
 export function uiPackageJsonRules(): void {
+  // Controlled sibling — workspace-only, never published, but kept versioned
+  // (changesets-owned) so the packed template's lib carries a version.
+  ensureField("private", true);
+
   ensureField("type", "module");
 
   ensureScript("fmt", "ts-builder format");

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

@@ -25,7 +25,7 @@ export function workflowPackageJsonInitial(ctx: RunContext): Record<string, unkn
   const v = ctx.blockVars;
   return {
     name: `${v.facadeName}.workflow`,
-    version: "1.0.0",
+    private: true,
     type: "module",
     scripts: {
       // No `fmt`: the workflow is Tengo, not TS — nothing for oxlint/oxfmt
@@ -54,6 +54,10 @@ export function workflowPackageJsonInitial(ctx: RunContext): Record<string, unkn
 }
 
 export function workflowPackageJsonRules(): void {
+  // Controlled sibling — workspace-only, never published, but kept versioned
+  // (changesets-owned) so the packed template's lib carries a version.
+  ensureField("private", true);
+
   ensureField("type", "module");
 
   // No `fmt` script: the workflow is Tengo, not TS — build + check run via

package/src/structure/templates/static/block/src/AGENTS.ts

@@ -0,0 +1,5 @@
+// This file is managed by `block-tools structure`. Do not edit by hand.
+// Narrow MCP / AI surface.
+
+export type { BlockContract, BlockOutputs, BlockData } from "./index";
+export * from "./agents-extra";