@platforma-sdk/block-tools 2.11.2 → 2.11.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-sdk/block-tools",
-  "version": "2.11.2",
+  "version": "2.11.3",
   "description": "Utility to manipulate Platforma Blocks and Block Registry",
   "license": "UNLICENSED",
   "bin": {
@@ -25,8 +25,8 @@
   "dependencies": {
     "@aws-sdk/client-s3": "3.859.0",
     "@inquirer/prompts": "^7.0.1",
-    "@oclif/core": "^4.0.37",
     "canonicalize": "~2.1.0",
+    "commander": "^15.0.0",
     "lru-cache": "^11.2.2",
     "mime-types": "^2.1.35",
     "tar": "^7.4.3",
@@ -35,12 +35,11 @@
     "zod": "~3.25.76",
     "@milaboratories/pl-http": "1.2.4",
     "@milaboratories/pl-model-middle-layer": "1.30.8",
+    "@milaboratories/pl-model-backend": "1.4.8",
     "@milaboratories/pl-model-common": "1.46.2",
-    "@milaboratories/ts-helpers": "1.8.3",
     "@milaboratories/resolve-helper": "1.1.3",
     "@platforma-sdk/blocks-deps-updater": "2.2.0",
-    "@milaboratories/ts-helpers-oclif": "1.1.42",
-    "@milaboratories/pl-model-backend": "1.4.8"
+    "@milaboratories/ts-helpers": "1.8.3"
   },
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^16.0.1",
@@ -48,7 +47,6 @@
     "@types/node": "~24.5.2",
     "@types/semver": "^7.7.0",
     "@vitest/coverage-istanbul": "^4.1.3",
-    "oclif": "^4.16.2",
     "oxfmt": "0.35.0",
     "rollup-plugin-node-externals": "^8.0.0",
     "semver": "^7.7.2",
@@ -57,24 +55,11 @@
     "vite-plugin-dts": "^4.5.3",
     "vitest": "^4.1.3",
     "@milaboratories/build-configs": "2.0.0",
-    "@milaboratories/oclif-index": "1.1.1",
     "@milaboratories/ts-configs": "1.2.3",
     "@milaboratories/ts-builder": "1.5.2"
   },
-  "oclif": {
-    "bin": "block-tools",
-    "commands": {
-      "identifier": "COMMANDS",
-      "strategy": "explicit",
-      "target": "./dist/cli.js"
-    },
-    "dirname": "block-tools",
-    "topicSeparator": " "
-  },
   "scripts": {
-    "oclif:index": "oclif-index --commands-root=./src/cmd/ --index-file=./src/cmd/index.ts && node --run fmt",
     "build": "vite build",
-    "readme": "oclif readme",
     "test": "vitest run --coverage",
     "do-pack": "rm -f *.tgz && pnpm pack && mv *.tgz package.tgz",
     "formatter:check": "ts-builder formatter --check",

package/src/cli.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from "vitest";
+import type { Command } from "commander";
+import { buildProgram } from "./cli";
+
+function subcommand(cmd: Command, name: string): Command {
+  const c = cmd.commands.find((x) => x.name() === name);
+  if (!c) throw new Error(`subcommand "${name}" not found`);
+  return c;
+}
+
+function longNames(cmd: Command): string[] {
+  return cmd.options.map((o) => o.long ?? o.short ?? o.name());
+}
+
+describe("block-tools CLI structure", () => {
+  const program = buildProgram();
+
+  it("exposes the full command surface (10 commands + structure topic)", () => {
+    expect(program.commands.map((c) => c.name()).sort()).toEqual([
+      "build-meta",
+      "build-model",
+      "list-overview-snapshots",
+      "mark-stable",
+      "pack",
+      "publish",
+      "refresh-registry",
+      "restore-overview-from-snapshot",
+      "structure",
+      "update-deps",
+      "upload-package-v1",
+    ]);
+    expect(
+      subcommand(program, "structure")
+        .commands.map((c) => c.name())
+        .sort(),
+    ).toEqual(["check", "init", "refresh"]);
+  });
+
+  it("preserves key flags + env bindings", () => {
+    const publish = subcommand(program, "publish");
+    const pnames = longNames(publish);
+    for (const f of ["--registry", "--manifest", "--version-override", "--refresh", "--unstable"]) {
+      expect(pnames).toContain(f);
+    }
+    // --no-refresh negation and PL_REGISTRY env preserved
+    expect(pnames).toContain("--no-refresh");
+    expect(publish.options.find((o) => o.long === "--registry")?.envVar).toBe("PL_REGISTRY");
+
+    // structure init keeps its positional [path] and the with/no-software pair
+    const init = subcommand(subcommand(program, "structure"), "init");
+    const inames = longNames(init);
+    expect(inames).toContain("--with-software");
+    expect(inames).toContain("--no-software");
+    expect(init.registeredArguments.map((a) => a.name())).toContain("path");
+  });
+});

package/src/cli.ts

@@ -0,0 +1,50 @@
+import { Command } from "commander";
+import { buildMetaCommand } from "./cmd/build-meta";
+import { buildModelCommand } from "./cmd/build-model";
+import { packCommand } from "./cmd/pack";
+import { publishCommand } from "./cmd/publish";
+import { refreshRegistryCommand } from "./cmd/refresh-registry";
+import { markStableCommand } from "./cmd/mark-stable";
+import { updateDepsCommand } from "./cmd/update-deps";
+import { listOverviewSnapshotsCommand } from "./cmd/list-overview-snapshots";
+import { restoreOverviewFromSnapshotCommand } from "./cmd/restore-overview-from-snapshot";
+import { uploadPackageV1Command } from "./cmd/upload-package-v1";
+import { structureCheckCommand } from "./cmd/structure/check";
+import { structureInitCommand } from "./cmd/structure/init";
+import { structureRefreshCommand } from "./cmd/structure/refresh";
+
+// `packageRoot` is the package install root (the dir containing `src/` and
+// `bin/`); the `structure` commands resolve their templates under it. bin/run.js
+// passes it in; defaults to cwd for tests/introspection.
+export function buildProgram(packageRoot: string = process.cwd()): Command {
+  const program = new Command();
+  program
+    .name("block-tools")
+    .description("Utility to manipulate Platforma Blocks and Block Registry");
+
+  program.addCommand(buildMetaCommand());
+  program.addCommand(buildModelCommand());
+  program.addCommand(packCommand());
+  program.addCommand(publishCommand());
+  program.addCommand(refreshRegistryCommand());
+  program.addCommand(markStableCommand());
+  program.addCommand(updateDepsCommand(packageRoot));
+  program.addCommand(listOverviewSnapshotsCommand());
+  program.addCommand(restoreOverviewFromSnapshotCommand());
+  program.addCommand(uploadPackageV1Command());
+
+  // `structure` subcommands: check | init | refresh.
+  const structure = new Command("structure").description(
+    "Manage block scaffolding against the canonical structure (check / init / refresh)",
+  );
+  structure.addCommand(structureCheckCommand(packageRoot));
+  structure.addCommand(structureInitCommand(packageRoot));
+  structure.addCommand(structureRefreshCommand(packageRoot));
+  program.addCommand(structure);
+
+  return program;
+}
+
+export async function run(argv: string[], packageRoot: string): Promise<void> {
+  await buildProgram(packageRoot).parseAsync(argv);
+}

package/src/cmd/build-meta.ts

@@ -1,32 +1,19 @@
-import { Command, Flags } from "@oclif/core";
+import { Command } from "commander";
 import path from "node:path";
 import fs from "node:fs";
 import { loadPackDescriptionRaw } from "../v2";
 import { embedBlockPackMetaAbsoluteBase64, resolveBlockPackMeta } from "../v2/model/block_meta";
 
-export default class BuildMeta extends Command {
-  static override description =
+export function buildMetaCommand(): Command {
+  const cmd = new Command("build-meta").description(
     "Extracts meta information from blocks package.json and outputs meta.json with embedded binary " +
-    "and textual information linked from the meta section.";
+      "and textual information linked from the meta section.",
+  );
 
-  static flags = {
-    modulePath: Flags.string({
-      char: "i",
-      summary: "input module path",
-      helpValue: "<path>",
-      default: ".",
-    }),
+  cmd.option("-i, --modulePath <path>", "input module path", ".");
+  cmd.requiredOption("-o, --destination <path>", "output meta.json file");
 
-    destination: Flags.string({
-      char: "o",
-      summary: "output meta.json file",
-      helpValue: "<path>",
-      required: true,
-    }),
-  };
-
-  public async run(): Promise<void> {
-    const { flags } = await this.parse(BuildMeta);
+  cmd.action(async (flags) => {
     const modulePath = path.resolve(flags.modulePath);
     const descriptionRaw = await loadPackDescriptionRaw(modulePath);
     const metaEmbedded = await embedBlockPackMetaAbsoluteBase64(
@@ -34,5 +21,7 @@ export default class BuildMeta extends Command {
     );
 
     await fs.promises.writeFile(path.resolve(flags.destination), JSON.stringify(metaEmbedded));
-  }
+  });
+
+  return cmd;
 }

package/src/cmd/build-model.ts

@@ -1,4 +1,4 @@
-import { Command, Flags } from "@oclif/core";
+import { Command } from "commander";
 import fs from "node:fs";
 import path from "node:path";
 
@@ -13,44 +13,26 @@ async function getFileContent(path: string) {
   }
 }
 
-export default class BuildModel extends Command {
-  static override description =
-    "Extracts and outputs block model JSON from pre-built block model module";
+export function buildModelCommand(): Command {
+  const cmd = new Command("build-model").description(
+    "Extracts and outputs block model JSON from pre-built block model module",
+  );
 
-  static flags = {
-    modulePath: Flags.string({
-      char: "i",
-      summary: "input module path",
-      helpValue: "<path>",
-      default: ".",
-    }),
+  cmd.option("-i, --modulePath <path>", "input module path", ".");
+  cmd.option(
+    "-b, --sourceBundle <path>",
+    "bundled model code to embed into the model for callback-based rendering to work",
+    "./dist/bundle.js",
+  );
+  cmd.option("-o, --destination <path>", "output model file", "./dist/model.json");
 
-    sourceBundle: Flags.string({
-      char: "b",
-      summary: "bundled model code to embed into the model for callback-based rendering to work",
-      helpValue: "<path>",
-      default: "./dist/bundle.js",
-    }),
-
-    destination: Flags.string({
-      char: "o",
-      summary: "output model file",
-      helpValue: "<path>",
-      default: "./dist/model.json",
-    }),
-  };
-
-  public async run(): Promise<void> {
-    const { flags } = await this.parse(BuildModel);
+  cmd.action(async (flags) => {
     const modulePath = path.resolve(flags.modulePath); // i.e. folder with package.json file
-    // eslint-disable-next-line prefer-const, @typescript-eslint/no-unsafe-assignment
     let { model, platforma } = require(modulePath);
 
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
     if (!model) model = platforma;
     if (!model) throw new Error('"model" export not found');
 
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
     const { config } = model;
 
     if (!config)
@@ -64,7 +46,6 @@ export default class BuildModel extends Command {
 
     const code = await getFileContent(flags.sourceBundle);
     if (code !== undefined) {
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
       config.code = {
         type: "plain",
         content: code,
@@ -72,5 +53,7 @@ export default class BuildModel extends Command {
     }
 
     await fs.promises.writeFile(path.resolve(flags.destination), JSON.stringify(config));
-  }
+  });
+
+  return cmd;
 }

package/src/cmd/list-overview-snapshots.ts

@@ -1,46 +1,42 @@
-import { Command, Flags } from "@oclif/core";
+import { Command, Option } from "commander";
 import { BlockRegistryV2 } from "../v2/registry/registry";
 import { storageByUrl } from "../io/storage";
-import { OclifLoggerAdapter } from "@milaboratories/ts-helpers-oclif";
+import { ConsoleLoggerAdapter } from "@milaboratories/ts-helpers";
 
-export default class ListOverviewSnapshots extends Command {
-  static description = "List all available global overview snapshots in the registry";
+export function listOverviewSnapshotsCommand(): Command {
+  const cmd = new Command("list-overview-snapshots").description(
+    "List all available global overview snapshots in the registry",
+  );
 
-  static flags = {
-    registry: Flags.string({
-      char: "r",
-      summary: "full address of the registry",
-      helpValue: "<address>",
-      env: "PL_REGISTRY",
-      required: true,
-    }),
+  cmd.addOption(
+    new Option("-r, --registry <address>", "full address of the registry")
+      .env("PL_REGISTRY")
+      .makeOptionMandatory(),
+  );
+  cmd.option("--json", "output in JSON format", false);
 
-    json: Flags.boolean({
-      summary: "output in JSON format",
-      default: false,
-    }),
-  };
-
-  public async run(): Promise<void> {
-    const { flags } = await this.parse(ListOverviewSnapshots);
+  cmd.action(async (flags) => {
+    const logger = new ConsoleLoggerAdapter();
     const storage = storageByUrl(flags.registry);
-    const registry = new BlockRegistryV2(storage, new OclifLoggerAdapter(this));
+    const registry = new BlockRegistryV2(storage, logger);
 
     const snapshots = await registry.listGlobalOverviewSnapshots();
 
     if (flags.json) {
-      this.log(JSON.stringify(snapshots, null, 2));
+      logger.info(JSON.stringify(snapshots, null, 2));
     } else {
       if (snapshots.length === 0) {
-        this.log("No snapshots found.");
+        logger.info("No snapshots found.");
       } else {
-        this.log(`Found ${snapshots.length} snapshot(s):\n`);
+        logger.info(`Found ${snapshots.length} snapshot(s):\n`);
         for (const snapshot of snapshots) {
-          this.log(`  ${snapshot.timestamp}`);
-          this.log(`    Path: ${snapshot.path}`);
-          this.log("");
+          logger.info(`  ${snapshot.timestamp}`);
+          logger.info(`    Path: ${snapshot.path}`);
+          logger.info("");
         }
       }
     }
-  }
+  });
+
+  return cmd;
 }

package/src/cmd/mark-stable.ts

@@ -1,67 +1,47 @@
-import { Command, Flags } from "@oclif/core";
+import { Command, Option } from "commander";
 import { BlockRegistryV2, loadPackDescriptionRaw } from "../v2";
 import path from "node:path";
 import { overrideDescriptionVersion, StableChannel } from "@milaboratories/pl-model-middle-layer";
 import { storageByUrl } from "../io";
-import { OclifLoggerAdapter } from "@milaboratories/ts-helpers-oclif";
-
-export default class MarkStable extends Command {
-  static description = "Mark target block stable";
-
-  static flags = {
-    modulePath: Flags.string({
-      char: "i",
-      summary: "input module path",
-      helpValue: "<path>",
-      default: ".",
-    }),
-
-    channel: Flags.string({
-      char: "c",
-      hidden: true,
-      summary: "custom channel",
-      helpValue: "<channel name>",
-      default: StableChannel,
-    }),
-
-    "version-override": Flags.file({
-      char: "v",
-      summary: "override package version",
-    }),
-
-    registry: Flags.string({
-      char: "r",
-      summary: "full address of the registry",
-      helpValue: "<address>",
-      env: "PL_REGISTRY",
-      required: true,
-    }),
-
-    refresh: Flags.boolean({
-      summary: "refresh repository after adding the package",
-      default: true,
-      allowNo: true,
-      env: "PL_REGISTRY_REFRESH",
-    }),
-
-    unmark: Flags.boolean({
-      summary:
-        'reverses meaning of this command, flag can be used to remove "stable" flag from the package',
-      default: false,
-    }),
-  };
-
-  public async run(): Promise<void> {
-    const { flags } = await this.parse(MarkStable);
+import { ConsoleLoggerAdapter } from "@milaboratories/ts-helpers";
+
+export function markStableCommand(): Command {
+  const cmd = new Command("mark-stable").description("Mark target block stable");
+
+  cmd.option("-i, --modulePath <path>", "input module path", ".");
+  cmd.addOption(
+    new Option("-c, --channel <channel name>", "custom channel").default(StableChannel).hideHelp(),
+  );
+  cmd.option("-v, --version-override <path>", "override package version");
+  cmd.addOption(
+    new Option("-r, --registry <address>", "full address of the registry")
+      .env("PL_REGISTRY")
+      .makeOptionMandatory(),
+  );
+  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.option(
+    "--unmark",
+    'reverses meaning of this command, flag can be used to remove "stable" flag from the package',
+    false,
+  );
+
+  cmd.action(async (flags) => {
     let description = await loadPackDescriptionRaw(path.resolve(flags.modulePath));
-    if (flags["version-override"])
-      description = overrideDescriptionVersion(description, flags["version-override"]);
+    if (flags.versionOverride)
+      description = overrideDescriptionVersion(description, flags.versionOverride);
     const storage = storageByUrl(flags.registry);
-    const registry = new BlockRegistryV2(storage, new OclifLoggerAdapter(this));
+    const registry = new BlockRegistryV2(storage, new ConsoleLoggerAdapter());
 
     if (flags.unmark) await registry.removePackageFromChannel(description.id, flags.channel);
     else await registry.addPackageToChannel(description.id, flags.channel);
 
     if (flags.refresh) await registry.updateIfNeeded();
-  }
+  });
+
+  return cmd;
 }

package/src/cmd/pack.ts

@@ -1,32 +1,21 @@
-import { Command, Flags } from "@oclif/core";
+import { Command } from "commander";
 import { loadPackDescription } from "../v2/source_package";
 import path from "node:path";
 import { buildBlockPackDist } from "../v2/build_dist";
 
-export default class PackBlock extends Command {
-  static description =
+export function packCommand(): Command {
+  const cmd = new Command("pack").description(
     "Builds block pack and outputs a block pack manifest consolidating all " +
-    "references assets into a single folder";
+      "references assets into a single folder",
+  );
 
-  static flags = {
-    modulePath: Flags.string({
-      char: "i",
-      summary: "input module path",
-      helpValue: "<path>",
-      default: ".",
-    }),
+  cmd.option("-i, --modulePath <path>", "input module path", ".");
+  cmd.option("-o, --destinationPath <path>", "output folder", "./block-pack");
 
-    destinationPath: Flags.string({
-      char: "o",
-      summary: "output folder",
-      helpValue: "<path>",
-      default: "./block-pack",
-    }),
-  };
-
-  public async run(): Promise<void> {
-    const { flags } = await this.parse(PackBlock);
+  cmd.action(async (flags) => {
     const description = await loadPackDescription(path.resolve(flags.modulePath));
     await buildBlockPackDist(description, path.resolve(flags.destinationPath));
-  }
+  });
+
+  return cmd;
 }

package/src/cmd/publish.ts

@@ -1,6 +1,6 @@
-import { Command, Flags } from "@oclif/core";
+import { Command, Option } from "commander";
 import fs from "node:fs";
-import { OclifLoggerAdapter } from "@milaboratories/ts-helpers-oclif";
+import { ConsoleLoggerAdapter } from "@milaboratories/ts-helpers";
 import { ManifestFileName } from "../v2/registry/schema_public";
 import {
   BlockPackManifest,
@@ -35,47 +35,32 @@ function simpleDeepMerge<T extends Record<string, unknown>>(
   return result as T;
 }
 
-export default class Publish extends Command {
-  static description =
-    "Publishes the block package and refreshes the registry (for v2 block-pack schema)";
-
-  static flags = {
-    registry: Flags.string({
-      char: "r",
-      summary: "full address of the registry",
-      helpValue: "<address>",
-      env: "PL_REGISTRY",
-      required: true,
-    }),
-
-    manifest: Flags.file({
-      char: "m",
-      summary: "manifest file path",
-      exists: true,
-      default: `./block-pack/${ManifestFileName}`,
-    }),
-
-    "version-override": Flags.file({
-      char: "v",
-      summary: "override package version",
-    }),
-
-    refresh: Flags.boolean({
-      summary: "refresh repository after adding the package",
-      default: true,
-      allowNo: true,
-      env: "PL_REGISTRY_REFRESH",
-    }),
-
-    unstable: Flags.boolean({
-      summary: "do not add the published package to stable channel",
-      default: false,
-      env: "PL_PUBLISH_UNSTABLE",
-    }),
-  };
-
-  public async run(): Promise<void> {
-    const { flags } = await this.parse(Publish);
+export function publishCommand(): Command {
+  const cmd = new Command("publish").description(
+    "Publishes the block package and refreshes the registry (for v2 block-pack schema)",
+  );
+
+  cmd.addOption(
+    new Option("-r, --registry <address>", "full address of the registry")
+      .env("PL_REGISTRY")
+      .makeOptionMandatory(),
+  );
+  cmd.option("-m, --manifest <path>", "manifest file path", `./block-pack/${ManifestFileName}`);
+  cmd.option("-v, --version-override <path>", "override package version");
+  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.addOption(
+    new Option("--unstable", "do not add the published package to stable channel")
+      .default(false)
+      .env("PL_PUBLISH_UNSTABLE"),
+  );
+
+  cmd.action(async (flags) => {
+    const logger = new ConsoleLoggerAdapter();
 
     const manifestPath = path.resolve(flags.manifest);
     const rawManifest = JSON.parse(
@@ -89,23 +74,24 @@ export default class Publish extends Command {
     );
     const manifestRoot = path.dirname(manifestPath);
 
-    this.log(`Manifest root = ${manifestRoot}`);
+    logger.info(`Manifest root = ${manifestRoot}`);
 
-    if (flags["version-override"])
-      manifest = overrideManifestVersion(manifest, flags["version-override"]);
+    if (flags.versionOverride) manifest = overrideManifestVersion(manifest, flags.versionOverride);
 
     const storage = storageByUrl(flags.registry);
-    const registry = new BlockRegistryV2(storage, new OclifLoggerAdapter(this));
+    const registry = new BlockRegistryV2(storage, logger);
 
     await registry.publishPackage(manifest, async (file) =>
       Buffer.from(await fs.promises.readFile(path.resolve(manifestRoot, file))),
     );
 
     if (!flags.unstable) {
-      this.log(`Adding package to ${StableChannel} channel...`);
+      logger.info(`Adding package to ${StableChannel} channel...`);
       await registry.addPackageToChannel(manifest.description.id, StableChannel);
     }
 
     if (flags.refresh) await registry.updateIfNeeded();
-  }
+  });
+
+  return cmd;
 }