@platforma-sdk/block-tools 2.11.10 → 2.12.0

package/dist/cmd/software/build.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function softwareBuildCommand(): Command;

package/dist/cmd/software/ecr-login.d.ts

@@ -0,0 +1,3 @@
+import { Logger } from '@platforma-sdk/package-builder-lib';
+export declare function ensureAwsProfile(logger?: Logger): void;
+export declare function ensureEcrLogin(registry: string, logger?: Logger): Promise<void>;

package/dist/cmd/software/env.d.ts

@@ -0,0 +1,5 @@
+export declare const PL_BUILD_CHANNEL = "PL_BUILD_CHANNEL";
+export declare const PL_BUILD_VARIANT = "PL_BUILD_VARIANT";
+export declare const PL_BUILD_LOCATION = "PL_BUILD_LOCATION";
+export declare const PL_BUILD_USE_PUBLISHED = "PL_BUILD_USE_PUBLISHED";
+export declare const softwareBuildCacheEnv: readonly string[];

package/dist/cmd/software/index.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function softwareCommand(): Command;

package/dist/cmd/software/knobs.d.ts

@@ -0,0 +1,26 @@
+export declare const channels: readonly ["dev", "release"];
+export declare const variants: readonly ["docker", "binary", "all", "none"];
+export declare const locations: readonly ["local", "remote"];
+export type Channel = (typeof channels)[number];
+export type Variant = (typeof variants)[number];
+export type Location = (typeof locations)[number];
+export type Knobs = {
+    channel?: Channel;
+    variant?: Variant;
+    location?: Location;
+    usePublished?: boolean;
+};
+export type TargetVariant = Exclude<Variant, "none">;
+export type Scenario = {
+    kind: "binary-existing";
+} | {
+    kind: "no-software";
+} | {
+    kind: "bare";
+} | {
+    kind: "target";
+    channel: Channel;
+    variant: TargetVariant;
+    location: Location;
+};
+export declare function parseScenario(knobs: Knobs): Scenario;

package/dist/cmd/software/run-build.d.ts

@@ -0,0 +1,19 @@
+import { Builder, Logger } from '@platforma-sdk/package-builder-lib';
+import { Scenario } from './knobs';
+export type BuildOptions = {
+    ids?: string[];
+    force?: boolean;
+    contentRoot?: string;
+    storageUrl?: string;
+    dockerRegistry?: string;
+    dockerPushTo?: string;
+    buildDocker?: boolean;
+    pushDocker?: boolean;
+    condaBuild?: boolean;
+};
+export declare function runBuild(params: {
+    core: Builder;
+    scenario: Scenario;
+    options?: BuildOptions;
+    logger?: Logger;
+}): Promise<void>;

package/dist/structure/engine/version.d.ts

@@ -1,13 +1,13 @@
 import { FileSystem } from './fs/api';
-export declare const STRUCTURE_VERSION = 1;
+export declare const STRUCTURE_VERSION = 2;
 export declare const STRUCTURE_MIN_SUPPORTED = 0;
 /** Block-relative path of the structurer metadata file. */
 export declare const STRUCTURE_META_FILE = ".structure";
 export type StructureMeta = {
     version: number;
 };
-/** Read `.structure`. Missing file or invalid payload → 0. */
-export declare function readStructureVersion(fs: FileSystem): number;
+/** Read `.structure`. Missing file or invalid payload → version 0. */
+export declare function readStructureMeta(fs: FileSystem): StructureMeta;
 /** Throw if version is below floor. */
 export declare function assertVersionAboveFloor(version: number, floor?: number): void;
 export declare class StructureVersionFloorError extends Error {
@@ -15,4 +15,5 @@ export declare class StructureVersionFloorError extends Error {
     readonly floor: number;
     constructor(version: number, floor: number);
 }
-export declare function writeStructureVersion(fs: FileSystem, version?: number): void;
+/** Write `.structure`. Writes a fresh payload rather than merging. */
+export declare function writeStructureMeta(fs: FileSystem, meta: StructureMeta): void;

package/dist/structure/rules/root-package-json.d.ts

@@ -1,3 +1,2 @@
-import { RunContext } from '../engine/api';
-export declare function rootPackageJsonInitial(_ctx: RunContext): Record<string, unknown>;
+export declare function rootPackageJsonInitial(): Record<string, unknown>;
 export declare function rootPackageJsonRules(): void;

package/dist/structure/rules/root-pnpm-workspace.d.ts

@@ -17,7 +17,13 @@ export declare const INFRA_CATALOG_FLOOR: Record<string, string>;
  *  3.5.x than ui-vue's, yielding two vue instances and a SdkPluginV3-vs-Plugin
  *  type clash in `main.ts`. Deriving the pin from ui-vue's declared dep keeps
  *  the block in lockstep with whatever vue ui-vue's npm-latest pins, with no
- *  hand-maintained version here. */
+ *  hand-maintained version here.
+ *
+ *  `@milaboratories/helpers`: the block's model/ui depend on it (catalog:) and
+ *  `@platforma-sdk/model` pins it as an EXACT regular dependency. A hand-pinned
+ *  floor that lags a model bump yields two helpers instances — the model's
+ *  inferred `platforma` type then references the SDK's copy, not the block's,
+ *  failing `tsc` with TS2742. Deriving from model keeps them in lockstep. */
 export declare const DERIVED_CATALOG_PINS: readonly DerivedCatalogPin[];
 /** Catalog name of the python runenv. Added to a block's catalog only when
  *  the block carries a software module. Pinned to an EXACT version — updating

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-sdk/block-tools",
-  "version": "2.11.10",
+  "version": "2.12.0",
   "description": "Utility to manipulate Platforma Blocks and Block Registry",
   "license": "UNLICENSED",
   "bin": {
@@ -23,6 +23,7 @@
     }
   },
   "dependencies": {
+    "@aws-sdk/client-ecr-public": "3.859.0",
     "@aws-sdk/client-s3": "3.859.0",
     "@inquirer/prompts": "^7.0.1",
     "canonicalize": "~2.1.0",
@@ -35,11 +36,12 @@
     "zod": "~3.25.76",
     "@milaboratories/pl-http": "1.2.4",
     "@milaboratories/pl-model-backend": "1.4.13",
-    "@milaboratories/resolve-helper": "1.1.3",
     "@milaboratories/pl-model-common": "1.46.4",
     "@milaboratories/pl-model-middle-layer": "1.30.11",
     "@platforma-sdk/blocks-deps-updater": "2.2.0",
-    "@milaboratories/ts-helpers": "1.8.4"
+    "@platforma-sdk/package-builder-lib": "1.2.0",
+    "@milaboratories/ts-helpers": "1.8.4",
+    "@milaboratories/resolve-helper": "1.1.3"
   },
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^16.0.1",
@@ -54,9 +56,9 @@
     "vite": "^8.0.6",
     "vite-plugin-dts": "^4.5.3",
     "vitest": "^4.1.3",
-    "@milaboratories/ts-builder": "1.6.0",
     "@milaboratories/build-configs": "2.0.0",
-    "@milaboratories/ts-configs": "1.3.0"
+    "@milaboratories/ts-configs": "1.3.0",
+    "@milaboratories/ts-builder": "1.6.0"
   },
   "scripts": {
     "build": "vite build",

package/src/cli.test.ts

@@ -15,7 +15,7 @@ function longNames(cmd: Command): string[] {
 describe("block-tools CLI structure", () => {
   const program = buildProgram();
 
-  it("exposes the full command surface (10 commands + structure topic)", () => {
+  it("exposes the full command surface (11 commands + structure topic)", () => {
     expect(program.commands.map((c) => c.name()).sort()).toEqual([
       "build-meta",
       "build-model",
@@ -25,6 +25,7 @@ describe("block-tools CLI structure", () => {
       "publish",
       "refresh-registry",
       "restore-overview-from-snapshot",
+      "software",
       "structure",
       "update-deps",
       "upload-package-v1",
@@ -34,6 +35,24 @@ describe("block-tools CLI structure", () => {
         .commands.map((c) => c.name())
         .sort(),
     ).toEqual(["check", "init", "refresh"]);
+    expect(
+      subcommand(program, "software")
+        .commands.map((c) => c.name())
+        .sort(),
+    ).toEqual(["build"]);
+  });
+
+  it("software build exposes the three knobs + use-published with env bindings", () => {
+    const build = subcommand(subcommand(program, "software"), "build");
+    const names = longNames(build);
+    for (const f of ["--channel", "--variant", "--location", "--use-published"]) {
+      expect(names).toContain(f);
+    }
+    const env = (long: string) => build.options.find((o) => o.long === long)?.envVar;
+    expect(env("--channel")).toBe("PL_BUILD_CHANNEL");
+    expect(env("--variant")).toBe("PL_BUILD_VARIANT");
+    expect(env("--location")).toBe("PL_BUILD_LOCATION");
+    expect(env("--use-published")).toBe("PL_BUILD_USE_PUBLISHED");
   });
 
   it("preserves key flags + env bindings", () => {

package/src/cli.ts

@@ -12,6 +12,7 @@ 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";
+import { softwareCommand } from "./cmd/software";
 
 // `packageRoot` is the package install root (the dir containing `src/` and
 // `bin/`); the `structure` commands resolve their templates under it. bin/run.js
@@ -32,6 +33,7 @@ export function buildProgram(packageRoot: string = process.cwd()): Command {
   program.addCommand(listOverviewSnapshotsCommand());
   program.addCommand(restoreOverviewFromSnapshotCommand());
   program.addCommand(uploadPackageV1Command());
+  program.addCommand(softwareCommand());
 
   // `structure` subcommands: check | init | refresh.
   const structure = new Command("structure").description(

package/src/cmd/software/build.ts

@@ -0,0 +1,175 @@
+import { Command, Option } from "commander";
+import { util, envs, createBuilder } from "@platforma-sdk/package-builder-lib";
+import { parseScenario, channels, variants, locations } from "./knobs";
+import { runBuild } from "./run-build";
+import {
+  PL_BUILD_CHANNEL,
+  PL_BUILD_VARIANT,
+  PL_BUILD_LOCATION,
+  PL_BUILD_USE_PUBLISHED,
+} from "./env";
+
+// Build a software module in one pass — build, push when remote, then write the descriptor
+// last. With no knobs it reproduces `pl-pkg build`.
+export function softwareBuildCommand(): Command {
+  const cmd = new Command("build").description(
+    "Build a software module for a target and write its .sw.json descriptor (build + push in one pass)",
+  );
+
+  // The three target knobs (env-backed; flag wins on conflict).
+  cmd.addOption(
+    new Option("--channel <channel>", "registry channel to build for")
+      .choices([...channels])
+      .env(PL_BUILD_CHANNEL),
+  );
+  cmd.addOption(
+    new Option("--variant <variant>", "artifact kind to build (default: all declared)")
+      .choices([...variants])
+      .env(PL_BUILD_VARIANT),
+  );
+  cmd.addOption(
+    new Option("--location <location>", "where the artifact lands (local = no push)")
+      .choices([...locations])
+      .env(PL_BUILD_LOCATION),
+  );
+  cmd.addOption(
+    new Option(
+      "--use-published",
+      "do not build or push; emit a descriptor pointing at the already-published release artifact",
+    ).env(PL_BUILD_USE_PUBLISHED),
+  );
+
+  // Pass-through build options, mirroring `pl-pkg build` so this is a drop-in replacement.
+  cmd.addOption(
+    new Option("--log-level <level>", "logging level")
+      .choices(["error", "warn", "info", "debug"])
+      .default("info"),
+  );
+  cmd.addOption(new Option("--package-root <path>", "path to directory with package.json file"));
+  cmd.addOption(
+    new Option("--force", "force action, ignoring automatic safety checks").default(false),
+  );
+  cmd.addOption(new Option("--version <value>", "override package version (ignore package.json)"));
+  cmd.addOption(
+    new Option("--platform <os-arch>", "{os}-{arch} pair; no effect on cross-platform packages")
+      .choices([...util.AllPlatforms])
+      .env(envs.PL_PKG_OS),
+  );
+  cmd.addOption(new Option("--all-platforms", "build for all supported platforms").default(false));
+  cmd.addOption(
+    new Option("--full-dir-hash", "hash file contents (not metadata) for the dev content hash")
+      .env(envs.PL_PKG_FULL_HASH)
+      .default(false),
+  );
+  cmd.addOption(new Option("--package-id <id...>", "act only on selected packages"));
+  cmd.addOption(
+    new Option("--content-root <path>", "override software content root").env(
+      envs.PL_PKG_CONTENT_ROOT,
+    ),
+  );
+  cmd.addOption(
+    new Option("--storage-url <url>", "override binary upload registry URL").env(
+      envs.PL_PKG_STORAGE_URL,
+    ),
+  );
+  cmd.addOption(
+    new Option(
+      "--docker-registry <registry>",
+      "docker pull registry embedded in the descriptor",
+    ).env(envs.PL_DOCKER_REGISTRY),
+  );
+  cmd.addOption(
+    new Option("--docker-push-to <registry>", "alternative registry for docker push").env(
+      envs.PL_DOCKER_REGISTRY_PUSH_TO,
+    ),
+  );
+  cmd.addOption(
+    new Option("--docker-build", "build docker images").env(envs.PL_DOCKER_BUILD).default(false),
+  );
+  cmd.addOption(
+    new Option("--docker-no-build", "do not build docker images")
+      .env(envs.PL_DOCKER_NO_BUILD)
+      .default(false),
+  );
+  cmd.addOption(
+    new Option("--docker-autopush", "push docker images after build")
+      .env(envs.PL_DOCKER_AUTOPUSH)
+      .default(false),
+  );
+  cmd.addOption(
+    new Option("--docker-no-autopush", "do not push docker images")
+      .env(envs.PL_DOCKER_NO_AUTOPUSH)
+      .default(false),
+  );
+  cmd.addOption(
+    new Option("--conda-build", "build conda environment before packing")
+      .env(envs.PL_CONDA_BUILD)
+      .default(false),
+  );
+  cmd.addOption(
+    new Option("--conda-no-build", "do not build conda environment")
+      .env(envs.PL_CONDA_NO_BUILD)
+      .default(false),
+  );
+
+  cmd.action(async (o) => {
+    const logger = util.createLogger(o.logLevel);
+
+    try {
+      const scenario = parseScenario({
+        channel: o.channel,
+        variant: o.variant,
+        location: o.location,
+        usePublished: Boolean(o.usePublished),
+      });
+
+      const core = createBuilder(logger, { packageRoot: o.packageRoot });
+      core.version = o.version;
+      core.targetPlatform = o.platform as util.PlatformType;
+      core.allPlatforms = Boolean(o.allPlatforms);
+      core.fullDirHash = Boolean(o.fullDirHash);
+
+      // Collapse the pl-pkg-parity --{docker,conda}-{,no-}* flag pairs to decisions here, at the CLI
+      // boundary, so runBuild receives resolved booleans (docker defaults to on in CI, push unless private).
+      const buildDocker = util.shouldDoAction({
+        default: envs.isCI(),
+        enable: o.dockerBuild,
+        disable: o.dockerNoBuild,
+      });
+      const pushDocker =
+        buildDocker &&
+        util.shouldDoAction({
+          default: envs.isCI() && !core.isPrivate,
+          enable: o.dockerAutopush,
+          disable: o.dockerNoAutopush,
+        });
+
+      await runBuild({
+        core,
+        scenario,
+        logger,
+        options: {
+          ids: o.packageId,
+          force: o.force,
+          contentRoot: o.contentRoot,
+          storageUrl: o.storageUrl,
+          dockerRegistry: o.dockerRegistry,
+          dockerPushTo: o.dockerPushTo,
+          buildDocker,
+          pushDocker,
+          condaBuild: util.shouldDoAction({
+            default: true,
+            enable: o.condaBuild,
+            disable: o.condaNoBuild,
+          }),
+        },
+      });
+    } catch (e) {
+      logger.debug(e);
+      if (e instanceof Error) logger.debug(e.stack);
+      throw e;
+    }
+  });
+
+  return cmd;
+}

package/src/cmd/software/ecr-login.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { defaults } from "@platforma-sdk/package-builder-lib";
+
+// Mock the AWS SDK client and docker CLI so nothing touches the network or a real docker daemon.
+const { sendMock, spawnMock } = vi.hoisted(() => ({ sendMock: vi.fn(), spawnMock: vi.fn() }));
+vi.mock("@aws-sdk/client-ecr-public", () => ({
+  ECRPUBLICClient: class {
+    send = sendMock;
+  },
+  GetAuthorizationTokenCommand: class {},
+}));
+vi.mock("node:child_process", () => ({ spawnSync: spawnMock }));
+
+const { ensureAwsProfile, ensureEcrLogin } = await import("./ecr-login");
+
+const DEV_ECR = "public.ecr.aws/miresearch/pl-containers";
+const token = (raw: string) => Buffer.from(raw, "utf8").toString("base64");
+const authOk = (raw: string) => ({ authorizationData: { authorizationToken: token(raw) } });
+
+afterEach(() => {
+  for (const k of ["AWS_ACCESS_KEY_ID", "AWS_PROFILE", "PL_AWS_PROFILE"]) delete process.env[k];
+  vi.clearAllMocks();
+});
+
+describe("ensureAwsProfile — credential-chain selection", () => {
+  it("does nothing when env credentials are present (the CI path)", () => {
+    process.env.AWS_ACCESS_KEY_ID = "AKIA...";
+    ensureAwsProfile();
+    expect(process.env.AWS_PROFILE).toBeUndefined();
+  });
+
+  it("leaves an explicit AWS_PROFILE untouched", () => {
+    process.env.AWS_PROFILE = "my-profile";
+    ensureAwsProfile();
+    expect(process.env.AWS_PROFILE).toBe("my-profile");
+  });
+
+  it("prefers PL_AWS_PROFILE over the built-in default", () => {
+    process.env.PL_AWS_PROFILE = "custom-dev";
+    ensureAwsProfile();
+    expect(process.env.AWS_PROFILE).toBe("custom-dev");
+  });
+
+  it("falls back to the built-in dev profile when nothing is set", () => {
+    ensureAwsProfile();
+    expect(process.env.AWS_PROFILE).toBe(defaults.AWS_DEV_PROFILE);
+  });
+});
+
+describe("ensureEcrLogin", () => {
+  it("rejects a non-public.ecr.aws host", async () => {
+    await expect(ensureEcrLogin("quay.io/milaboratories/pl")).rejects.toThrow(/public\.ecr\.aws/);
+    expect(sendMock).not.toHaveBeenCalled();
+  });
+
+  it("logs in with the decoded token, splitting only on the first colon", async () => {
+    sendMock.mockResolvedValue(authOk("AWS:pass:with:colons"));
+    spawnMock.mockReturnValue({ status: 0 });
+
+    await ensureEcrLogin(DEV_ECR);
+
+    expect(spawnMock).toHaveBeenCalledWith(
+      "docker",
+      ["login", "--username", "AWS", "--password-stdin", "public.ecr.aws"],
+      expect.objectContaining({ input: "pass:with:colons" }),
+    );
+  });
+
+  it("throws a recoverable SSO hint when the token is empty (expired/absent session)", async () => {
+    sendMock.mockResolvedValue({ authorizationData: { authorizationToken: undefined } });
+    await expect(ensureEcrLogin(DEV_ECR)).rejects.toThrow(/aws sso login/);
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it("throws on a malformed token with no ':' separator", async () => {
+    sendMock.mockResolvedValue(authOk("no-colon-here"));
+    await expect(ensureEcrLogin(DEV_ECR)).rejects.toThrow(/aws sso login/);
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it("throws when `docker login` exits non-zero", async () => {
+    sendMock.mockResolvedValue(authOk("AWS:pw"));
+    spawnMock.mockReturnValue({ status: 1 });
+    await expect(ensureEcrLogin(DEV_ECR)).rejects.toThrow(/docker login.*failed/);
+  });
+
+  it("throws when spawning docker errors", async () => {
+    sendMock.mockResolvedValue(authOk("AWS:pw"));
+    spawnMock.mockReturnValue({ error: new Error("ENOENT"), status: null });
+    await expect(ensureEcrLogin(DEV_ECR)).rejects.toThrow(/docker login.*failed/);
+  });
+});

package/src/cmd/software/ecr-login.ts

@@ -0,0 +1,75 @@
+import { spawnSync } from "node:child_process";
+import * as os from "node:os";
+import {
+  ECRPUBLICClient as EcrPublicClient,
+  GetAuthorizationTokenCommand,
+} from "@aws-sdk/client-ecr-public";
+import { util, defaults, type Logger } from "@platforma-sdk/package-builder-lib";
+
+const PUBLIC_ECR_HOST = "public.ecr.aws";
+// ECR Public's API is served only from us-east-1, independent of where images are pulled.
+const PUBLIC_ECR_REGION = "us-east-1";
+
+// Pin AWS_PROFILE once so the ECR client and the S3 upload resolve identical credentials.
+// Env credentials (CI) and an explicit AWS_PROFILE take precedence and skip this.
+export function ensureAwsProfile(logger?: Logger): void {
+  if (process.env.AWS_ACCESS_KEY_ID || process.env.AWS_PROFILE) return;
+  const profile = process.env.PL_AWS_PROFILE ?? defaults.AWS_DEV_PROFILE;
+  process.env.AWS_PROFILE = profile;
+  logger?.debug(`Using AWS profile '${profile}' for dev push credentials`);
+}
+
+// Host of a scheme-less registry ref: public.ecr.aws/u5p1x5q2/pl-containers -> public.ecr.aws
+function registryHost(registry: string): string {
+  return new URL(`https://${registry}`).hostname;
+}
+
+function ssoLoginHint(): string {
+  const profile = process.env.AWS_PROFILE ?? process.env.PL_AWS_PROFILE ?? defaults.AWS_DEV_PROFILE;
+  return `  aws sso login --profile ${profile}`;
+}
+
+// docker login to public ECR with an SDK-fetched token. No cached-auth check — re-authenticates
+// every call, so an expired/absent session fails here with a recoverable hint, not opaquely at push.
+export async function ensureEcrLogin(registry: string, logger?: Logger): Promise<void> {
+  const host = registryHost(registry);
+  if (host !== PUBLIC_ECR_HOST) {
+    // Public ECR is the only dev docker registry; reject a mis-set ecr:// override.
+    throw util.CLIError(
+      `automatic docker login is only supported for '${PUBLIC_ECR_HOST}', not '${host}'.\n` +
+        `Log in manually, or drop the ecr:// scheme from the push target to opt out.`,
+    );
+  }
+
+  logger?.info(`Logging in to ECR registry '${host}'...`);
+
+  let user: string;
+  let password: string;
+  try {
+    const client = new EcrPublicClient({ region: PUBLIC_ECR_REGION });
+    const res = await client.send(new GetAuthorizationTokenCommand({}));
+    const token = res.authorizationData?.authorizationToken;
+    if (!token) throw new Error("empty authorization token");
+    // Token decodes to "AWS:<password>"; password may contain ':', so split on the first only.
+    const decoded = Buffer.from(token, "base64").toString("utf8");
+    const sep = decoded.indexOf(":");
+    if (sep < 0) throw new Error(`malformed authorization token (no ':' separator)`);
+    user = decoded.slice(0, sep);
+    password = decoded.slice(sep + 1);
+  } catch (e) {
+    throw util.CLIError(
+      `failed to obtain an ECR login token for '${host}': ${e instanceof Error ? e.message : String(e)}\n` +
+        `Your AWS/SSO session is likely expired or absent — log in and retry:\n` +
+        ssoLoginHint(),
+    );
+  }
+
+  const login = spawnSync("docker", ["login", "--username", user, "--password-stdin", host], {
+    input: password,
+    stdio: ["pipe", "inherit", "inherit"],
+    env: { ...process.env, HOME: process.env.HOME || os.homedir() },
+  });
+  if (login.error || login.status !== 0) {
+    throw util.CLIError(`'docker login ${host}' failed`);
+  }
+}

package/src/cmd/software/env.test.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { softwareBuildCacheEnv } from "./env";
+
+// The block's turbo build task must cache-key on every software-build env var, declared once in the
+// structurer template. This guards against the template drifting from softwareBuildCacheEnv.
+const turboPath = fileURLToPath(
+  new URL("../../structure/templates/static/root/turbo.json", import.meta.url),
+);
+const buildEnv: string[] = JSON.parse(readFileSync(turboPath, "utf8")).tasks.build.env;
+
+describe("block turbo build cache env", () => {
+  it("declares every software-build cache var", () => {
+    for (const v of softwareBuildCacheEnv) expect(buildEnv).toContain(v);
+  });
+});

package/src/cmd/software/env.ts

@@ -0,0 +1,22 @@
+import { envs } from "@platforma-sdk/package-builder-lib";
+
+// The `software build` knob env vars (the flag/env pairs the scenario scripts set).
+export const PL_BUILD_CHANNEL = "PL_BUILD_CHANNEL";
+export const PL_BUILD_VARIANT = "PL_BUILD_VARIANT";
+export const PL_BUILD_LOCATION = "PL_BUILD_LOCATION";
+export const PL_BUILD_USE_PUBLISHED = "PL_BUILD_USE_PUBLISHED";
+
+// Every env var that changes `block-tools software build` output, so must key the turbo build cache.
+export const softwareBuildCacheEnv: readonly string[] = [
+  PL_BUILD_CHANNEL,
+  PL_BUILD_VARIANT,
+  PL_BUILD_LOCATION,
+  PL_BUILD_USE_PUBLISHED,
+  envs.PL_DOCKER_REGISTRY_PUSH_TO,
+  envs.PL_DEV_DOCKER_PUSH_URL,
+  envs.PL_DEV_DOCKER_PULL_URL,
+  envs.PL_DEV_BINARY_UPLOAD_URL,
+  envs.PL_RELEASE_DOCKER_PUSH_URL,
+  envs.PL_RELEASE_DOCKER_PULL_URL,
+  envs.PL_RELEASE_BINARY_UPLOAD_URL,
+];

package/src/cmd/software/index.ts

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+import { softwareBuildCommand } from "./build";
+
+// `software` parent command: per-target software build (and future software subcommands).
+export function softwareCommand(): Command {
+  const cmd = new Command("software").description("Build and publish a block's software modules");
+  cmd.addCommand(softwareBuildCommand());
+  return cmd;
+}

package/src/cmd/software/knobs.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { parseScenario } from "./knobs";
+
+describe("parseScenario — knobs collapse to the supported set", () => {
+  it("no location => bare invocation (pl-pkg parity)", () => {
+    expect(parseScenario({})).toEqual({ kind: "bare" });
+    expect(parseScenario({ channel: "dev" })).toEqual({ kind: "bare" });
+  });
+
+  it("explicit location => a target cell carrying the knobs as enums", () => {
+    expect(parseScenario({ channel: "dev", variant: "binary", location: "remote" })).toEqual({
+      kind: "target",
+      channel: "dev",
+      variant: "binary",
+      location: "remote",
+    });
+    // channel and variant default when unset.
+    expect(parseScenario({ location: "local" })).toEqual({
+      kind: "target",
+      channel: "release",
+      variant: "all",
+      location: "local",
+    });
+  });
+
+  it("variant=all is preserved on the target", () => {
+    expect(parseScenario({ channel: "dev", variant: "all", location: "local" })).toEqual({
+      kind: "target",
+      channel: "dev",
+      variant: "all",
+      location: "local",
+    });
+  });
+
+  it("variant=none => no-software, regardless of location", () => {
+    expect(parseScenario({ channel: "dev", variant: "none", location: "local" })).toEqual({
+      kind: "no-software",
+    });
+    expect(parseScenario({ variant: "none" })).toEqual({ kind: "no-software" });
+  });
+
+  it("use-published collapses everything but rejects docker and all (binary-only)", () => {
+    expect(parseScenario({ channel: "dev", usePublished: true })).toEqual({
+      kind: "binary-existing",
+    });
+    expect(parseScenario({ usePublished: true, variant: "binary" })).toEqual({
+      kind: "binary-existing",
+    });
+    expect(() => parseScenario({ usePublished: true, variant: "docker" })).toThrow(/binary-only/);
+    expect(() => parseScenario({ usePublished: true, variant: "all" })).toThrow(/binary-only/);
+  });
+});