@platforma-sdk/block-tools 2.11.2 → 2.11.4

package/src/cmd/structure/init.ts

@@ -1,5 +1,6 @@
-import { Args, Command, Flags } from "@oclif/core";
+import { Command, Option } from "commander";
 import path from "node:path";
+import { ConsoleLoggerAdapter } from "@milaboratories/ts-helpers";
 import {
   resolveBlockVars,
   runInit,
@@ -7,59 +8,51 @@ import {
   type InitFlagValues,
 } from "../../structure/init-block-constructor";
 
-export default class StructureInit extends Command {
-  static override description =
-    "Scaffold a fresh Platforma block from the canonical structure. Missing flags are prompted unless --non-interactive.";
-
-  static override examples = [
-    "<%= config.bin %> <%= command.id %> --npm-org @platforma-open --org-scope my-org --short-name demo --no-software --non-interactive",
-    "<%= config.bin %> <%= command.id %> ./demo --npm-org @platforma-open --org-scope my-org --short-name demo --with-software --platform python --non-interactive",
-  ];
-
-  static override args = {
-    path: Args.string({
-      description: "target directory (default: <short-name> under the current directory)",
-    }),
-  };
-
-  static override flags = {
-    "npm-org": Flags.string({ description: "npm org, e.g. @platforma-open" }),
-    "org-scope": Flags.string({ description: "org scope, e.g. my-org" }),
-    "short-name": Flags.string({ description: "block short name, e.g. mixcr-clonotyping" }),
-    "with-software": Flags.boolean({ description: "include a software module" }),
-    "no-software": Flags.boolean({ description: "omit the software module" }),
-    platform: Flags.string({
-      description: "software platform (single-valued)",
-      options: [...SUPPORTED_PLATFORMS],
-    }),
-    "non-interactive": Flags.boolean({
-      description: "error on any missing flag instead of prompting",
-    }),
-  };
-
-  public async run(): Promise<void> {
-    const { args, flags } = await this.parse(StructureInit);
-
-    if (flags["with-software"] && flags["no-software"]) {
-      this.error("--with-software and --no-software are mutually exclusive.");
+export function structureInitCommand(packageRoot: string): Command {
+  const cmd = new Command("init").description(
+    "Scaffold a fresh Platforma block from the canonical structure. Missing flags are prompted unless --non-interactive.",
+  );
+
+  cmd.argument("[path]", "target directory (default: <short-name> under the current directory)");
+  cmd.option("--npm-org <org>", "npm org, e.g. @platforma-open");
+  cmd.option("--org-scope <scope>", "org scope, e.g. my-org");
+  cmd.option("--short-name <name>", "block short name, e.g. mixcr-clonotyping");
+  cmd.option("--with-software", "include a software module");
+  cmd.option("--no-software", "omit the software module");
+  cmd.addOption(
+    new Option("--platform <platform>", "software platform (single-valued)").choices([
+      ...SUPPORTED_PLATFORMS,
+    ]),
+  );
+  cmd.option("--non-interactive", "error on any missing flag instead of prompting");
+
+  cmd.action(async (argPath: string | undefined, flags) => {
+    const logger = new ConsoleLoggerAdapter();
+
+    // commander maps `--with-software` -> flags.withSoftware===true and
+    // `--no-software` -> flags.software===false
+    const withSoftwareFlag = flags.withSoftware === true;
+    const noSoftwareFlag = flags.software === false;
+    if (withSoftwareFlag && noSoftwareFlag) {
+      throw new Error("--with-software and --no-software are mutually exclusive.");
     }
-    const withSoftware = flags["with-software"] ? true : flags["no-software"] ? false : undefined;
+    const withSoftware = withSoftwareFlag ? true : noSoftwareFlag ? false : undefined;
 
     const flagValues: InitFlagValues = {
-      npmOrg: flags["npm-org"],
-      orgScope: flags["org-scope"],
-      shortName: flags["short-name"],
+      npmOrg: flags.npmOrg,
+      orgScope: flags.orgScope,
+      shortName: flags.shortName,
       withSoftware,
       platform: flags.platform,
-      nonInteractive: flags["non-interactive"],
+      nonInteractive: flags.nonInteractive,
     };
 
     const vars = await resolveBlockVars(flagValues);
-    const blockPath = args.path
-      ? path.resolve(args.path)
-      : path.resolve(process.cwd(), vars.shortName);
-    const templatesRoot = path.join(this.config.root, "src", "structure", "templates");
+    const blockPath = argPath ? path.resolve(argPath) : path.resolve(process.cwd(), vars.shortName);
+    const templatesRoot = path.join(packageRoot, "src", "structure", "templates");
+
+    await runInit({ vars, blockPath, templatesRoot, log: (m) => logger.info(m) });
+  });
 
-    await runInit({ vars, blockPath, templatesRoot, log: (m) => this.log(m) });
-  }
+  return cmd;
 }

package/src/cmd/structure/refresh.ts

@@ -1,44 +1,53 @@
-import { Command, Flags } from "@oclif/core";
+import { Command } from "commander";
 import path from "node:path";
+import type { MiLogger } from "@milaboratories/ts-helpers";
+import { ConsoleLoggerAdapter } from "@milaboratories/ts-helpers";
 import { runStructureForPath, formatChanges } from "../../structure/cli/run-structure";
 
-export default class StructureRefresh extends Command {
-  static override description =
-    "Bring block(s) up to date with the canonical structure. Applies rules, writes files, bumps .structure version. Default mode is offline; --update-deps-only fires only catalog-bump rules (network).";
-
-  static override examples = [
-    "<%= config.bin %> <%= command.id %> ./my-block",
-    "<%= config.bin %> <%= command.id %> --sdk-internal etc/blocks/*",
-    "<%= config.bin %> <%= command.id %> --update-deps-only",
-  ];
+// Shared by `structure refresh` and the deprecated `update-deps` alias.
+export async function runRefresh(opts: {
+  paths: string[];
+  isSdkInternal: boolean;
+  updateDepsOnly: boolean;
+  templatesRoot: string;
+  logger: MiLogger;
+}): Promise<void> {
+  for (const p of opts.paths) {
+    const res = await runStructureForPath({
+      blockPath: p,
+      isSdkInternal: opts.isSdkInternal,
+      updateDepsOnly: opts.updateDepsOnly,
+      mode: "refresh",
+      templatesRoot: opts.templatesRoot,
+      log: (m) => opts.logger.info(m),
+    });
+    opts.logger.info(formatChanges(p, res.changes));
+  }
+}
 
-  static override strict = false;
+export function structureRefreshCommand(packageRoot: string): Command {
+  const cmd = new Command("refresh").description(
+    "Bring block(s) up to date with the canonical structure. Applies rules, writes files, bumps .structure version. Default mode is offline; --update-deps-only fires only catalog-bump rules (network).",
+  );
 
-  static override flags = {
-    "sdk-internal": Flags.boolean({
-      description: "block(s) live inside the SDK monorepo; skip root-scope rules",
-    }),
-    "update-deps-only": Flags.boolean({
-      description:
-        "fire ONLY catalog-bump rules (npm network). Follow with `pnpm install` then a plain refresh.",
-    }),
-  };
+  cmd.argument("[paths...]", "block path(s); defaults to the current directory");
+  cmd.option("--sdk-internal", "block(s) live inside the SDK monorepo; skip root-scope rules");
+  cmd.option(
+    "--update-deps-only",
+    "fire ONLY catalog-bump rules (npm network). Follow with `pnpm install` then a plain refresh.",
+  );
 
-  public async run(): Promise<void> {
-    const { argv, flags } = await this.parse(StructureRefresh);
-    const paths = (argv as string[]).length > 0 ? (argv as string[]) : ["."];
-    const templatesRoot = path.join(this.config.root, "src", "structure", "templates");
+  cmd.action(async (argv: string[], flags) => {
+    const paths = argv.length > 0 ? argv : ["."];
+    const templatesRoot = path.join(packageRoot, "src", "structure", "templates");
+    await runRefresh({
+      paths,
+      isSdkInternal: Boolean(flags.sdkInternal),
+      updateDepsOnly: Boolean(flags.updateDepsOnly),
+      templatesRoot,
+      logger: new ConsoleLoggerAdapter(),
+    });
+  });
 
-    for (const p of paths) {
-      const res = await runStructureForPath({
-        blockPath: p,
-        isSdkInternal: flags["sdk-internal"],
-        updateDepsOnly: flags["update-deps-only"],
-        mode: "refresh",
-        templatesRoot,
-        log: (m) => this.log(m),
-      });
-      this.log(formatChanges(p, res.changes));
-    }
-  }
+  return cmd;
 }

package/src/cmd/update-deps.ts

@@ -1,4 +1,7 @@
-import { Command } from "@oclif/core";
+import { Command } from "commander";
+import path from "node:path";
+import { ConsoleLoggerAdapter } from "@milaboratories/ts-helpers";
+import { runRefresh } from "./structure/refresh";
 
 /**
  * Deprecated. Phase-2 forwarding alias (spec.md § "Coexistence And
@@ -7,19 +10,26 @@ import { Command } from "@oclif/core";
  * semantics. Prints a deprecation warning; will be removed once the
  * structurer path has been live without surprises.
  */
-export default class UpdateDeps extends Command {
-  static override description =
-    "[DEPRECATED] Use `block-tools structure refresh --update-deps-only`. This alias delegates to it.";
+export function updateDepsCommand(packageRoot: string): Command {
+  const cmd = new Command("update-deps").description(
+    "[DEPRECATED] Use `block-tools structure refresh --update-deps-only`. This alias delegates to it.",
+  );
 
-  static override examples = ["<%= config.bin %> <%= command.id %>"];
-
-  public async run(): Promise<void> {
-    this.warn(
+  cmd.action(async () => {
+    const logger = new ConsoleLoggerAdapter();
+    logger.warn(
       "`block-tools update-deps` is deprecated and will be removed in a future release. " +
         "Use `block-tools structure refresh --update-deps-only` instead. Delegating now.",
     );
-    // oclif resolves commands by their internal colon-form id, even
-    // though the user-facing form uses the configured " " topic separator.
-    await this.config.runCommand("structure:refresh", ["--update-deps-only"]);
-  }
+    const templatesRoot = path.join(packageRoot, "src", "structure", "templates");
+    await runRefresh({
+      paths: ["."],
+      isSdkInternal: false,
+      updateDepsOnly: true,
+      templatesRoot,
+      logger,
+    });
+  });
+
+  return cmd;
 }

package/src/cmd/upload-package-v1.ts

@@ -1,67 +1,47 @@
-import { Command, Flags } from "@oclif/core";
+import { Command, Option } from "commander";
 import { getConfig } from "../registry_v1/config";
-import { targetFile } from "../registry_v1/flags";
+import { targetFileOption } from "../registry_v1/flags";
 import fs from "node:fs";
 import YAML from "yaml";
 import { PlRegPackageConfigDataShard } from "../registry_v1/config_schema";
-import { OclifLoggerAdapter } from "@milaboratories/ts-helpers-oclif";
+import { ConsoleLoggerAdapter } from "@milaboratories/ts-helpers";
 
 type BasicConfigField = keyof PlRegPackageConfigDataShard &
   ("registry" | "organization" | "package" | "version");
 const BasicConfigFields: BasicConfigField[] = ["registry", "organization", "package", "version"];
 
-export default class UploadPackageV1 extends Command {
-  static description = "Uploads V1 package and refreshes the registry";
-
-  static flags = {
-    registry: Flags.string({
-      char: "r",
-      summary: "full address of the registry or alias from .pl.reg",
-      helpValue: "<address|alias>",
-      env: "PL_REGISTRY",
-    }),
-
-    organization: Flags.string({
-      char: "o",
-      summary: "target organisation",
-      env: "PL_PACKAGE_ORGANIZATION",
-    }),
-
-    package: Flags.string({
-      char: "p",
-      summary: "target package",
-      env: "PL_PACKAGE_NAME",
-    }),
-
-    version: Flags.string({
-      char: "v",
-      summary: "target version",
-      env: "PL_PACKAGE_VERSION",
-    }),
-
-    meta: Flags.file({
-      char: "m",
-      summary: "json file containing meta information to associate with tha package",
-      exists: true,
-    }),
-
-    file: targetFile({
-      char: "f",
-      summary: "package files",
-      multiple: true,
-      default: [],
-    }),
-
-    refresh: Flags.boolean({
-      summary: "refresh repository after adding the package",
-      default: true,
-      allowNo: true,
-      env: "PL_REGISTRY_REFRESH",
-    }),
-  };
-
-  public async run(): Promise<void> {
-    const { flags } = await this.parse(UploadPackageV1);
+export function uploadPackageV1Command(): Command {
+  const cmd = new Command("upload-package-v1").description(
+    "Uploads V1 package and refreshes the registry",
+  );
+
+  cmd.addOption(
+    new Option(
+      "-r, --registry <address|alias>",
+      "full address of the registry or alias from .pl.reg",
+    ).env("PL_REGISTRY"),
+  );
+  cmd.addOption(
+    new Option("-o, --organization <organization>", "target organisation").env(
+      "PL_PACKAGE_ORGANIZATION",
+    ),
+  );
+  cmd.addOption(new Option("-p, --package <package>", "target package").env("PL_PACKAGE_NAME"));
+  cmd.addOption(new Option("-v, --version <version>", "target version").env("PL_PACKAGE_VERSION"));
+  cmd.option(
+    "-m, --meta <path>",
+    "json file containing meta information to associate with tha package",
+  );
+  cmd.addOption(targetFileOption("-f, --file <file>", "package files"));
+  cmd.addOption(
+    new Option("--refresh", "refresh repository after adding the package")
+      .default(true)
+      .env("PL_REGISTRY_REFRESH"),
+  );
+  cmd.option("--no-refresh", "do not refresh repository after adding the package");
+
+  cmd.action(async (flags) => {
+    const logger = new ConsoleLoggerAdapter();
     const configFromFlags: PlRegPackageConfigDataShard = PlRegPackageConfigDataShard.parse({});
 
     for (const field of BasicConfigFields) if (flags[field]) configFromFlags[field] = flags[field];
@@ -83,23 +63,25 @@ export default class UploadPackageV1 extends Command {
 
     const conf = await getConfig(configFromFlags);
 
-    this.log(YAML.stringify(conf.conf));
+    logger.info(YAML.stringify(conf.conf));
 
-    const registry = conf.createRegistry(new OclifLoggerAdapter(this));
+    const registry = conf.createRegistry(logger);
     const name = conf.fullPackageName;
 
     const builder = registry.constructNewPackage(name);
 
     for (const [dst, src] of Object.entries(conf.conf.files)) {
-      this.log(`Uploading ${src} -> ${dst} ...`);
+      logger.info(`Uploading ${src} -> ${dst} ...`);
       const content = await fs.promises.readFile(src);
       await builder.addFile(dst, content);
     }
 
-    this.log(`Uploading meta information...`);
+    logger.info(`Uploading meta information...`);
     await builder.writeMeta(conf.conf.meta);
     await builder.finish();
 
     if (flags.refresh) await registry.updateIfNeeded();
-  }
+  });
+
+  return cmd;
 }

package/src/registry_v1/flags.ts

@@ -1,4 +1,4 @@
-import { Flags } from "@oclif/core";
+import { Option } from "commander";
 import path from "node:path";
 
 export interface TargetFile {
@@ -16,9 +16,9 @@ function parseTargetFile(arg: string): TargetFile {
   }
 }
 
-export const targetFile = Flags.custom<TargetFile>({
-  summary: "target files to upload",
-  helpValue: "file_path | package_name=file_path",
-  // eslint-disable-next-line @typescript-eslint/require-await -- oclif requires async but parsing is sync
-  parse: async (arg) => parseTargetFile(arg),
-});
+// Repeatable `file_path | package_name=file_path` option.
+export function targetFileOption(flags: string, summary: string): Option {
+  return new Option(flags, summary)
+    .argParser((arg: string, prev?: TargetFile[]) => [...(prev ?? []), parseTargetFile(arg)])
+    .default([] as TargetFile[]);
+}

package/src/structure/__tests__/discovery-shortname.test.ts

@@ -36,10 +36,13 @@ describe("DISCOVERY: shortName from the block package name", () => {
       // Nameless root — the standalone shape; classified `root` by path.
       "package.json": "{}",
       // Legacy block package: name IS the bare facade, no `.block` suffix.
+      // Classified `block` via its top-level `block` field (every real block —
+      // legacy shim or migrated facade — carries one).
       "block/package.json": JSON.stringify({
         name: "@platforma-open/test-org.legacy",
         files: ["index.d.ts", "index.js"],
         dependencies: { "@platforma-sdk/block-tools": "*" },
+        block: { components: {}, meta: {} },
       }),
     });
     const ctx = discoverRunContext({ fs, isSdkInternal: false });

package/src/structure/__tests__/facade-end-state.test.ts

@@ -0,0 +1,195 @@
+// Facade end-state coverage — the slim `block/` the structurer emits and
+// enforces: block-scope detection by the top-level `block` field, the four-file
+// `src/` surface + facade `tsconfig.json`, the slim publishable `package.json`,
+// sibling privacy, and legacy-shim cleanup.
+
+import { describe, test, expect } from "vitest";
+import type { BlockVars, RunContext } from "../engine/api";
+import { classifyOne, type WorkspacePackage } from "../engine/discovery";
+import { STRUCTURE } from "../structure-definition";
+import { run as engineRun } from "../engine/runner";
+import { defaultTemplateProvider, simulateInit } from "../engine/testing";
+
+const TEMPLATES = defaultTemplateProvider();
+
+const VARS: BlockVars = {
+  facadeName: "@platforma-open/test-org.demo",
+  baseName: "test-org.demo",
+  npmOrg: "@platforma-open",
+  orgScope: "test-org",
+  shortName: "demo",
+};
+
+function pkg(path: string, pkgJson: Record<string, unknown>): WorkspacePackage {
+  return { path, pkg: pkgJson };
+}
+
+describe("facade: block-scope detection by the top-level `block` field", () => {
+  test("a package with a top-level `block` field is classified `block`", () => {
+    expect(classifyOne(pkg("block", { name: "x", block: { components: {} } }))).toBe("block");
+  });
+
+  test("the `block` field wins over the model shape (the collision the order guards)", () => {
+    // A migrated facade carries `@platforma-sdk/model` (devDep) + `main`, which
+    // matches the model rule — the `block` field must take precedence.
+    expect(
+      classifyOne(
+        pkg("block", {
+          name: "x",
+          main: "./dist/index.js",
+          devDependencies: { "@platforma-sdk/model": "catalog:" },
+          block: { components: {} },
+        }),
+      ),
+    ).toBe("block");
+  });
+
+  test("a model-shaped package WITHOUT a `block` field is still `model`, not `block`", () => {
+    expect(
+      classifyOne(
+        pkg("model", {
+          name: "x.model",
+          main: "dist/index.cjs",
+          dependencies: { "@platforma-sdk/model": "catalog:" },
+        }),
+      ),
+    ).toBe("model");
+  });
+});
+
+describe("facade: four-file source surface + tsconfig", () => {
+  test("init emits the 4 src files + tsconfig, and no legacy shim", () => {
+    const { fs } = simulateInit({ vars: VARS });
+    for (const f of [
+      "block/src/index.ts",
+      "block/src/AGENTS.ts",
+      "block/src/block-extra.ts",
+      "block/src/agents-extra.ts",
+      "block/tsconfig.json",
+    ]) {
+      expect(fs.exists(f), `expected ${f} to be emitted`).toBe(true);
+    }
+    expect(fs.exists("block/index.js")).toBe(false);
+    expect(fs.exists("block/index.d.ts")).toBe(false);
+  });
+
+  test("index.ts carries the per-block model import path and PascalName aliases", () => {
+    const { fs } = simulateInit({ vars: VARS });
+    const index = fs.read("block/src/index.ts");
+    expect(index).toContain('import { platforma } from "@platforma-open/test-org.demo.model"');
+    expect(index).toContain("export type DemoBlockContract = BlockContract;");
+    expect(index).toContain("export const DemoBlockPointer = BlockPointer;");
+    expect(index).toContain('export * from "./block-extra"');
+  });
+
+  test("tsconfig extends the facade preset (singular `block/facade`)", () => {
+    const { fs } = simulateInit({ vars: VARS });
+    const tsconfig = JSON.parse(fs.read("block/tsconfig.json"));
+    expect(tsconfig.extends).toBe("@milaboratories/ts-configs/block/facade");
+  });
+});
+
+describe("facade: slim `package.json` end-state", () => {
+  test("is slim and carries the facade fields, scripts, and sibling devDeps", () => {
+    const { fs } = simulateInit({ vars: VARS });
+    const p = JSON.parse(fs.read("block/package.json"));
+
+    // Slim invariant: zero runtime dependencies.
+    expect(p.dependencies).toEqual({});
+
+    expect(p.type).toBe("module");
+    expect(p.files).toEqual(["dist", "block-pack"]);
+    expect(p.main).toBe("./dist/index.js");
+    expect(p.module).toBe("./dist/index.js");
+    expect(p.types).toBe("./dist/index.d.ts");
+    expect(p.exports).toEqual({
+      ".": {
+        sources: "./src/index.ts",
+        types: "./dist/index.d.ts",
+        default: "./dist/index.js",
+      },
+    });
+
+    expect(Object.keys(p.scripts).sort()).toEqual(["build", "check", "do-pack", "prepublishOnly"]);
+    expect(p.scripts.build).toBe("ts-builder build --target block-facade && block-tools pack");
+    expect(p.scripts.check).toBe("ts-builder type-check --target block-facade");
+
+    // Siblings are build-time devDeps (workspace links), never runtime deps.
+    expect(p.devDependencies["@platforma-open/test-org.demo.model"]).toBe("workspace:*");
+    expect(p.devDependencies["@platforma-open/test-org.demo.ui"]).toBe("workspace:*");
+    expect(p.devDependencies["@platforma-open/test-org.demo.workflow"]).toBe("workspace:*");
+
+    // Author-owned seed + engine-managed components both present.
+    expect(p.block.components).toBeTruthy();
+    expect(p.block.meta).toBeTruthy();
+  });
+});
+
+describe("facade: `prepublishOnly` publish target branches on isSdkInternal", () => {
+  const AUX_DEV =
+    "block-tools publish -r s3://milab-euce1-prod-pkgs-s3-block-registry/aux/dev/?region=eu-central-1 --registry-serve-url https://aux-blocks.pl-open.science";
+
+  test("in-SDK blocks publish to the aux/dev registry, regardless of org", () => {
+    // `@milaboratories` would route to production via ORG_PUBLISH_TARGETS — the
+    // isSdkInternal branch must override that and send it to aux/dev.
+    const vars: BlockVars = {
+      facadeName: "@milaboratories/test-org.demo",
+      baseName: "test-org.demo",
+      npmOrg: "@milaboratories",
+      orgScope: "test-org",
+      shortName: "demo",
+    };
+    const { fs } = simulateInit({ vars, isSdkInternal: true });
+    const p = JSON.parse(fs.read("block/package.json"));
+    expect(p.scripts.prepublishOnly).toBe(AUX_DEV);
+  });
+
+  test("standalone blocks publish to their per-org production target", () => {
+    const open = simulateInit({ vars: VARS });
+    expect(JSON.parse(open.fs.read("block/package.json")).scripts.prepublishOnly).toBe(
+      "block-tools publish -r s3://milab-euce1-prod-pkgs-s3-block-registry/pub/releases/?region=eu-central-1 --registry-serve-url https://blocks.pl-open.science",
+    );
+
+    const milab = simulateInit({
+      vars: {
+        facadeName: "@milaboratories/test-org.demo",
+        baseName: "test-org.demo",
+        npmOrg: "@milaboratories",
+        orgScope: "test-org",
+        shortName: "demo",
+      },
+    });
+    expect(JSON.parse(milab.fs.read("block/package.json")).scripts.prepublishOnly).toBe(
+      "block-tools publish -r s3://milab-euce1-prod-pkgs-s3-block-registry/pub/releases/?region=eu-central-1 --registry-serve-url https://block.registry.platforma.bio/releases",
+    );
+  });
+});
+
+describe("facade: sibling package privacy", () => {
+  test("model / ui / workflow / test are `private` with no `version`", () => {
+    const { fs } = simulateInit({ vars: VARS });
+    for (const scope of ["model", "ui", "workflow", "test"]) {
+      const p = JSON.parse(fs.read(`${scope}/package.json`));
+      expect(p.private, `${scope} must be private`).toBe(true);
+      expect("version" in p, `${scope} must not carry a version`).toBe(false);
+    }
+  });
+});
+
+describe("facade: legacy shim cleanup on refresh", () => {
+  test("a refresh removes a pre-existing block/index.js + index.d.ts, then is idempotent", () => {
+    const { fs, ctx } = simulateInit({ vars: VARS });
+    // Inject the legacy boilerplate shim a pre-facade block would carry.
+    fs.write("block/index.js", "module.exports = { blockSpec: {} };\n");
+    fs.write("block/index.d.ts", "export declare const blockSpec: unknown;\n");
+
+    // Default-mode refresh (not dry-run): the engine's post-run recheck throws
+    // RecheckError if a second pass would change anything — so this asserts
+    // convergence too.
+    const refreshCtx: RunContext = { ...ctx, dryRun: false };
+    expect(() => engineRun(STRUCTURE, fs, refreshCtx, { templates: TEMPLATES })).not.toThrow();
+
+    expect(fs.exists("block/index.js")).toBe(false);
+    expect(fs.exists("block/index.d.ts")).toBe(false);
+  });
+});

package/src/structure/__tests__/model-package-json.snapshot.test.ts

@@ -9,7 +9,7 @@ import type { BlockVars } from "../engine/api";
 
 const EXPECTED_MODEL_PACKAGE_JSON = `{
   "name": "@platforma-open/test-org.demo.model",
-  "version": "1.0.0",
+  "private": true,
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",

package/src/structure/cli/run-structure.ts

@@ -1,5 +1,5 @@
 // Shared driver for the `structure check` and `structure refresh`
-// oclif commands. Wraps DISCOVERY (discover-fs) + the engine runner for
+// commands. Wraps DISCOVERY (discover-fs) + the engine runner for
 // one block path, handling the standalone vs `--sdk-internal` split, the
 // `--update-deps-only` registry prefetch, and the post-run recheck's
 // fresh re-discovery. Each block path is processed independently (no
@@ -26,7 +26,7 @@ export type RunStructureInput = {
   isSdkInternal: boolean;
   updateDepsOnly: boolean;
   mode: StructureMode;
-  /** `<block-tools>/src/structure/templates` (from oclif `config.root`). */
+  /** `<block-tools>/src/structure/templates`. */
   templatesRoot: string;
   log: (msg: string) => void;
 };