@platforma-sdk/block-tools 2.11.2 → 2.11.4

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.test.ts

@@ -0,0 +1,35 @@
+import { test, expect } from "vitest";
+import * as os from "node:os";
+import * as path from "node:path";
+import fsp from "node:fs/promises";
+import { publishCommand } from "./publish";
+
+function option(cmd: ReturnType<typeof publishCommand>, long: string) {
+  return cmd.options.find((o) => o.long === long);
+}
+
+test("publish keeps --registry required and adds a required --registry-serve-url", () => {
+  const cmd = publishCommand();
+  expect(option(cmd, "--registry")?.mandatory).toBe(true);
+  expect(option(cmd, "--registry-serve-url")?.mandatory).toBe(true);
+});
+
+test("publish errors when the serve URL is absent", async () => {
+  // A real manifest file so the action's read never runs — parsing must reject
+  // on the missing required --registry-serve-url before any registry I/O.
+  const dir = await fsp.mkdtemp(path.join(os.tmpdir(), "publish-flags-"));
+  const manifestPath = path.join(dir, "manifest.json");
+  await fsp.writeFile(manifestPath, "{}");
+
+  // Clear the env binding so the mandatory check, not the environment, decides.
+  const prev = process.env.PL_REGISTRY_SERVE_URL;
+  delete process.env.PL_REGISTRY_SERVE_URL;
+  try {
+    const cmd = publishCommand().exitOverride();
+    await expect(
+      cmd.parseAsync(["-r", "s3://bucket", "-m", manifestPath], { from: "user" }),
+    ).rejects.toThrow(/registry-serve-url/i);
+  } finally {
+    if (prev !== undefined) process.env.PL_REGISTRY_SERVE_URL = prev;
+  }
+});

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,
@@ -9,6 +9,7 @@ import {
 } from "@milaboratories/pl-model-middle-layer";
 import { storageByUrl } from "../io/storage";
 import { BlockRegistryV2 } from "../v2/registry/registry";
+import { buildPublishedCoords, writePublishedCoords } from "../v2/resolve_to_registry";
 import path from "node:path";
 
 function simpleDeepMerge<T extends Record<string, unknown>>(
@@ -35,47 +36,40 @@ 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.addOption(
+    new Option(
+      "--registry-serve-url <url>",
+      "CDN serve URL written into block-pack/published.json (npm-consumed blocks)",
+    )
+      .env("PL_REGISTRY_SERVE_URL")
+      .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 +83,35 @@ 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);
     }
 
+    // Write registry coordinates next to the manifest so npm consumers can
+    // resolve the published block via `resolveToRegistry`. Written before
+    // returning so `npm publish`'s tarball generation (after prepublishOnly)
+    // picks it up.
+    const coords = buildPublishedCoords({
+      registryUrl: flags.registryServeUrl,
+      id: manifest.description.id,
+    });
+    await writePublishedCoords(manifestRoot, coords);
+    logger.info(`Wrote published coordinates to ${path.resolve(manifestRoot, "published.json")}`);
+
     if (flags.refresh) await registry.updateIfNeeded();
-  }
+  });
+
+  return cmd;
 }

package/src/cmd/refresh-registry.ts

@@ -1,34 +1,30 @@
-import { Command, Flags } from "@oclif/core";
+import { Command, Option } from "commander";
 import { BlockRegistryV2 } from "../v2";
 import { storageByUrl } from "../io";
-import { OclifLoggerAdapter } from "@milaboratories/ts-helpers-oclif";
+import { ConsoleLoggerAdapter } from "@milaboratories/ts-helpers";
 
-export default class RefreshRegistry extends Command {
-  static description = "Refresh overview files based on published but not proecessed artefacts";
+export function refreshRegistryCommand(): Command {
+  const cmd = new Command("refresh-registry").description(
+    "Refresh overview files based on published but not proecessed artefacts",
+  );
 
-  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.addOption(
+    new Option("-m, --mode <mode>", 'refresh mode (allowed valiues: "force", "normal", "dry-run")')
+      .choices(["force", "normal", "dry-run"])
+      .env("PL_REGISTRY_REFRESH_DRY_RUN")
+      .default("normal"),
+  );
 
-    mode: Flags.string({
-      char: "m",
-      summary: 'refresh mode (allowed valiues: "force", "normal", "dry-run")',
-      helpValue: "<mode>",
-      options: ["force", "normal", "dry-run"],
-      env: "PL_REGISTRY_REFRESH_DRY_RUN",
-      default: "normal",
-    }),
-  };
-
-  public async run(): Promise<void> {
-    const { flags } = await this.parse(RefreshRegistry);
+  cmd.action(async (flags) => {
     const storage = storageByUrl(flags.registry);
-    const registry = new BlockRegistryV2(storage, new OclifLoggerAdapter(this));
+    const registry = new BlockRegistryV2(storage, new ConsoleLoggerAdapter());
     await registry.updateIfNeeded(flags.mode as "force" | "normal" | "dry-run");
-  }
+  });
+
+  return cmd;
 }

package/src/cmd/restore-overview-from-snapshot.ts

@@ -1,44 +1,32 @@
-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 RestoreOverviewFromSnapshot extends Command {
-  static description = "Restore global overview from a snapshot";
+export function restoreOverviewFromSnapshotCommand(): Command {
+  const cmd = new Command("restore-overview-from-snapshot").description(
+    "Restore global overview from a snapshot",
+  );
 
-  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.requiredOption("-s, --snapshot <timestamp>", "snapshot timestamp ID to restore from");
+  cmd.option("--skip-confirmation", "skip confirmation prompt (use with caution)", false);
 
-    snapshot: Flags.string({
-      char: "s",
-      summary: "snapshot timestamp ID to restore from",
-      helpValue: "<timestamp>",
-      required: true,
-    }),
-
-    "skip-confirmation": Flags.boolean({
-      summary: "skip confirmation prompt (use with caution)",
-      default: false,
-    }),
-  };
-
-  public async run(): Promise<void> {
-    const { flags } = await this.parse(RestoreOverviewFromSnapshot);
+  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);
 
     // Check if snapshot exists
     const snapshots = await registry.listGlobalOverviewSnapshots();
     const targetSnapshot = snapshots.find((s) => s.timestamp === flags.snapshot);
 
     if (!targetSnapshot) {
-      this.error(
+      throw new Error(
         `Snapshot '${flags.snapshot}' not found. Available snapshots:\n${
           snapshots.map((s) => `  - ${s.timestamp}`).join("\n") || "  (none)"
         }`,
@@ -46,7 +34,7 @@ export default class RestoreOverviewFromSnapshot extends Command {
     }
 
     // Confirmation prompt (unless skipped)
-    if (!flags["skip-confirmation"]) {
+    if (!flags.skipConfirmation) {
       const readline = await import("node:readline");
       const rl = readline.createInterface({
         input: process.stdin,
@@ -64,7 +52,7 @@ export default class RestoreOverviewFromSnapshot extends Command {
       rl.close();
 
       if (answer.toLowerCase() !== "y" && answer.toLowerCase() !== "yes") {
-        this.log("Restore cancelled.");
+        logger.info("Restore cancelled.");
         return;
       }
     }
@@ -72,9 +60,11 @@ export default class RestoreOverviewFromSnapshot extends Command {
     // Perform restore
     try {
       await registry.restoreGlobalOverviewFromSnapshot(flags.snapshot);
-      this.log(`✅ Successfully restored global overview from snapshot '${flags.snapshot}'`);
+      logger.info(`✅ Successfully restored global overview from snapshot '${flags.snapshot}'`);
     } catch (error) {
-      this.error(`Failed to restore from snapshot: ${String(error)}`);
+      throw new Error(`Failed to restore from snapshot: ${String(error)}`);
     }
-  }
+  });
+
+  return cmd;
 }

package/src/cmd/structure/check.ts

@@ -1,51 +1,42 @@
-import { Command, Flags } from "@oclif/core";
+import { Command } from "commander";
 import path from "node:path";
+import { ConsoleLoggerAdapter } from "@milaboratories/ts-helpers";
 import { runStructureForPath, formatChanges } from "../../structure/cli/run-structure";
 
-export default class StructureCheck extends Command {
-  static override description =
-    "Check block(s) against the canonical structure (read-only). Exits non-zero if any diff would land — used as the CI gate.";
-
-  static override examples = [
-    "<%= config.bin %> <%= command.id %> ./my-block",
-    "<%= config.bin %> <%= command.id %> --sdk-internal etc/blocks/*",
-  ];
+export function structureCheckCommand(packageRoot: string): Command {
+  const cmd = new Command("check").description(
+    "Check block(s) against the canonical structure (read-only). Exits non-zero if any diff would land — used as the CI gate.",
+  );
 
   // Variadic positional block paths (shell-expanded globs).
-  static override strict = false;
-
-  static override flags = {
-    "sdk-internal": Flags.boolean({
-      description: "block(s) live inside the SDK monorepo; skip root-scope rules",
-    }),
-  };
+  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");
 
-  public async run(): Promise<void> {
-    const { argv, flags } = await this.parse(StructureCheck);
-    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 logger = new ConsoleLoggerAdapter();
+    const paths = argv.length > 0 ? argv : ["."];
+    const templatesRoot = path.join(packageRoot, "src", "structure", "templates");
 
     let anyChanged = false;
     for (const p of paths) {
       const res = await runStructureForPath({
         blockPath: p,
-        isSdkInternal: flags["sdk-internal"],
+        isSdkInternal: Boolean(flags.sdkInternal),
         updateDepsOnly: false,
         mode: "check",
         templatesRoot,
-        log: (m) => this.log(m),
+        log: (m) => logger.info(m),
       });
-      this.log(formatChanges(p, res.changes));
+      logger.info(formatChanges(p, res.changes));
       if (res.changes.length > 0) anyChanged = true;
     }
 
     if (anyChanged) {
-      this.error(
+      throw new Error(
         "Structure check failed: one or more blocks are out of date. Run `structure refresh`.",
-        {
-          exit: 1,
-        },
       );
     }
-  }
+  });
+
+  return cmd;
 }