@platforma-sdk/block-tools 2.11.10 → 2.12.0

package/src/cmd/software/knobs.ts

@@ -0,0 +1,61 @@
+import { util } from "@platforma-sdk/package-builder-lib";
+
+export const channels = ["dev", "release"] as const;
+export const variants = ["docker", "binary", "all", "none"] as const;
+export const locations = ["local", "remote"] as const;
+
+export type Channel = (typeof channels)[number];
+export type Variant = (typeof variants)[number];
+export type Location = (typeof locations)[number];
+
+// Raw CLI flags, each independently optional; parseScenario narrows them to a supported Scenario.
+export type Knobs = {
+  channel?: Channel;
+  variant?: Variant;
+  location?: Location;
+  usePublished?: boolean;
+};
+
+// The variant a resolved target actually builds — "none" is its own scenario, never a target.
+export type TargetVariant = Exclude<Variant, "none">;
+
+// The closed set of scenarios runBuild executes; parseScenario rejects anything else. `target`
+// carries the resolved knobs as enums (not pre-derived booleans) — runBuild derives the flags.
+export type Scenario =
+  // `build:dev-binary-existing` (PL_BUILD_USE_PUBLISHED): reference the published binary; no build/push.
+  | { kind: "binary-existing" }
+  // `build:dev-no-software` (PL_BUILD_VARIANT=none): placeholder descriptors; nothing built or pushed.
+  | { kind: "no-software" }
+  // no build:* script — the scriptless default (direct call / `do-pack`); drop-in `pl-pkg build`.
+  | { kind: "bare" }
+  // `build:dev-local` / `build:dev-remote` / `build:release` / `test`: build for a target.
+  | { kind: "target"; channel: Channel; variant: TargetVariant; location: Location };
+
+// Collapse the raw knobs to a supported Scenario; the one place bad combinations are rejected.
+export function parseScenario(knobs: Knobs): Scenario {
+  if (knobs.usePublished) {
+    // A published binary can be referenced; docker (and `all`, which includes it) cannot.
+    if (knobs.variant === "docker" || knobs.variant === "all") {
+      throw util.CLIError(
+        `--use-published is binary-only and cannot be combined with --variant ${knobs.variant}`,
+      );
+    }
+    return { kind: "binary-existing" };
+  }
+
+  if (knobs.variant === "none") {
+    return { kind: "no-software" };
+  }
+
+  if (knobs.location === undefined) {
+    return { kind: "bare" };
+  }
+
+  // `all` (the default) builds every declared variant; the engine skips the kinds the software omits.
+  return {
+    kind: "target",
+    channel: knobs.channel ?? "release",
+    variant: knobs.variant ?? "all",
+    location: knobs.location,
+  };
+}

package/src/cmd/software/run-build.test.ts

@@ -0,0 +1,291 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { runBuild } from "./run-build";
+import { parseScenario, type Knobs } from "./knobs";
+import { defaults, type Builder } from "@platforma-sdk/package-builder-lib";
+import { ensureEcrLogin, ensureAwsProfile } from "./ecr-login";
+
+// Neutralize the real docker/aws shelling; assert only that the orchestration calls it.
+vi.mock("./ecr-login", () => ({ ensureEcrLogin: vi.fn(), ensureAwsProfile: vi.fn() }));
+
+// A Builder stub that records which engine methods ran, in order.
+function fakeBuilder() {
+  const calls: string[] = [];
+  const rec = (name: string) => (_opts?: unknown) => {
+    calls.push(name);
+  };
+  const core = {
+    buildMode: "release",
+    isPrivate: false,
+    buildDockerImages: vi.fn(rec("buildDockerImages")),
+    writePublishedArtifactInfo: vi.fn(rec("writePublishedArtifactInfo")),
+    buildSoftwareArchives: vi.fn(async () => void calls.push("buildSoftwareArchives")),
+    publishDockerImages: vi.fn(rec("publishDockerImages")),
+    publishPackages: vi.fn(async () => void calls.push("publishPackages")),
+    buildSwJsonFiles: vi.fn(rec("buildSwJsonFiles")),
+  };
+  return { core: core as unknown as Builder, calls, spies: core };
+}
+
+const run = (knobs: Knobs, b = fakeBuilder()) =>
+  runBuild({ core: b.core, scenario: parseScenario(knobs) }).then(() => b);
+
+afterEach(() => {
+  for (const k of [
+    "CI",
+    "PL_DEV_DOCKER_PUSH_URL",
+    "PL_DEV_DOCKER_PULL_URL",
+    "PL_RELEASE_DOCKER_PUSH_URL",
+    "PL_RELEASE_DOCKER_PULL_URL",
+  ]) {
+    delete process.env[k];
+  }
+  vi.clearAllMocks();
+});
+
+// What registry/pushTo the engine was called with for a docker target.
+async function dockerAddresses(knobs: Knobs) {
+  const b = await run(knobs);
+  const reg = (fn: { mock: { calls: unknown[][] } }) =>
+    (fn.mock.calls[0]?.[0] as { registry?: string; pushTo?: string }) ?? {};
+  return {
+    pull: reg(b.spies.buildDockerImages).registry,
+    push: reg(b.spies.publishDockerImages).pushTo,
+  };
+}
+
+describe("runBuild orchestration", () => {
+  it("always writes the descriptor last", async () => {
+    for (const knobs of [
+      {},
+      { channel: "dev", variant: "binary", location: "local" },
+      { channel: "dev", variant: "binary", location: "remote" },
+      { channel: "release", location: "remote" },
+      { usePublished: true },
+    ] as Knobs[]) {
+      const { calls } = await run(knobs);
+      expect(calls.at(-1)).toBe("buildSwJsonFiles");
+    }
+  });
+
+  it("dev-binary-remote builds then uploads the binary, no docker", async () => {
+    const { calls } = await run({ channel: "dev", variant: "binary", location: "remote" });
+    expect(calls).toEqual(["buildSoftwareArchives", "publishPackages", "buildSwJsonFiles"]);
+  });
+
+  it("dev-binary-local builds the binary but does not upload", async () => {
+    const { calls } = await run({ channel: "dev", variant: "binary", location: "local" });
+    expect(calls).toEqual(["buildSoftwareArchives", "buildSwJsonFiles"]);
+  });
+
+  it("use-published writes the descriptor only — no build, no push", async () => {
+    const { calls } = await run({ usePublished: true });
+    expect(calls).toEqual(["writePublishedArtifactInfo", "buildSwJsonFiles"]);
+  });
+
+  it("no-software writes a placeholder descriptor only — no build, no push", async () => {
+    const b = await run({ channel: "dev", variant: "none", location: "local" });
+    expect(b.calls).toEqual(["buildSwJsonFiles"]);
+    expect(b.spies.buildSwJsonFiles).toHaveBeenCalledWith(
+      expect.objectContaining({ noSoftware: true }),
+    );
+  });
+
+  it("sets the scenario-derived build mode on the engine", async () => {
+    expect((await run({})).core.buildMode).toBe("release");
+    expect(
+      (await run({ channel: "dev", variant: "binary", location: "local" })).core.buildMode,
+    ).toBe("dev-local");
+    expect(
+      (await run({ channel: "dev", variant: "binary", location: "remote" })).core.buildMode,
+    ).toBe("dev-remote");
+    expect((await run({ usePublished: true })).core.buildMode).toBe("release");
+  });
+
+  it("dev-docker-remote pushes docker (push before descriptor)", async () => {
+    const { calls } = await run({ channel: "dev", variant: "docker", location: "remote" });
+    expect(calls).toEqual(["buildDockerImages", "publishDockerImages", "buildSwJsonFiles"]);
+  });
+
+  it("docker-local builds docker but does not push", async () => {
+    const { calls } = await run({ channel: "dev", variant: "docker", location: "local" });
+    expect(calls).toEqual(["buildDockerImages", "buildSwJsonFiles"]);
+  });
+
+  it("no variant builds both kinds; local => no push", async () => {
+    const { calls } = await run({ channel: "dev", location: "local" });
+    expect(calls).toEqual(["buildDockerImages", "buildSoftwareArchives", "buildSwJsonFiles"]);
+  });
+
+  it("release + remote builds and pushes both kinds in one pass, descriptor last", async () => {
+    const { calls } = await run({ channel: "release", location: "remote" });
+    expect(calls).toEqual([
+      "buildDockerImages",
+      "buildSoftwareArchives",
+      "publishDockerImages",
+      "publishPackages",
+      "buildSwJsonFiles",
+    ]);
+  });
+
+  it("dev docker build targets the built-in dev registry; release does not", async () => {
+    const dev = await run({ channel: "dev", variant: "docker", location: "remote" });
+    expect(dev.spies.buildDockerImages).toHaveBeenCalledWith(
+      expect.objectContaining({ registry: defaults.DEV_DOCKER_REGISTRY }),
+    );
+    const rel = await run({ channel: "release", variant: "docker", location: "remote" });
+    expect(rel.spies.buildDockerImages).toHaveBeenCalledWith(
+      expect.objectContaining({ registry: undefined }),
+    );
+  });
+
+  describe("docker channel address overrides", () => {
+    const devRemote: Knobs = { channel: "dev", variant: "docker", location: "remote" };
+    const releaseRemote: Knobs = { channel: "release", variant: "docker", location: "remote" };
+
+    it("dev defaults: push and embedded pull both target the built-in dev registry", async () => {
+      expect(await dockerAddresses(devRemote)).toEqual({
+        pull: defaults.DEV_DOCKER_REGISTRY,
+        push: defaults.DEV_DOCKER_REGISTRY,
+      });
+    });
+
+    it("dev PUSH override: pull follows push when no pull override is set", async () => {
+      process.env.PL_DEV_DOCKER_PUSH_URL = "ecr.example/dev";
+      expect(await dockerAddresses(devRemote)).toEqual({
+        pull: "ecr.example/dev",
+        push: "ecr.example/dev",
+      });
+    });
+
+    it("dev PUSH + PULL overrides are independent (push there, embed this)", async () => {
+      process.env.PL_DEV_DOCKER_PUSH_URL = "ecr.example/dev";
+      process.env.PL_DEV_DOCKER_PULL_URL = "cdn.example/dev";
+      expect(await dockerAddresses(devRemote)).toEqual({
+        pull: "cdn.example/dev",
+        push: "ecr.example/dev",
+      });
+    });
+
+    it("release override targets the configured release registry, no built-in default", async () => {
+      expect(await dockerAddresses(releaseRemote)).toEqual({ pull: undefined, push: undefined });
+      process.env.PL_RELEASE_DOCKER_PUSH_URL = "quay.io/org/repo";
+      expect(await dockerAddresses(releaseRemote)).toEqual({
+        pull: "quay.io/org/repo",
+        push: "quay.io/org/repo",
+      });
+    });
+
+    it("bare (pl-pkg parity) ignores channel overrides", async () => {
+      process.env.CI = "true";
+      process.env.PL_RELEASE_DOCKER_PUSH_URL = "quay.io/org/repo";
+      // bare invocation: docker addresses stay unset (engine pushes to the embedded tag).
+      expect(await dockerAddresses({})).toEqual({ pull: undefined, push: undefined });
+    });
+
+    it("dev default (ecr:// push target) auto-logs-in for the stripped host", async () => {
+      await run(devRemote);
+      expect(ensureEcrLogin).toHaveBeenCalledWith(defaults.DEV_DOCKER_REGISTRY, undefined);
+      expect(ensureAwsProfile).toHaveBeenCalled();
+    });
+
+    it("a plain (non-ecr) push override opts out of auto-login", async () => {
+      process.env.PL_DEV_DOCKER_PUSH_URL = "ecr.example/dev";
+      await run(devRemote);
+      expect(ensureEcrLogin).not.toHaveBeenCalled();
+    });
+
+    it("local docker build never logs in", async () => {
+      await run({ channel: "dev", variant: "docker", location: "local" });
+      expect(ensureEcrLogin).not.toHaveBeenCalled();
+    });
+
+    it("explicit --docker-push-to wins over the channel override", async () => {
+      process.env.PL_DEV_DOCKER_PUSH_URL = "ecr.example/dev";
+      const b = await run(devRemote);
+      await runBuild({
+        core: b.core,
+        scenario: parseScenario(devRemote),
+        options: { dockerPushTo: "flag.example/repo" },
+      });
+      const lastPush = b.spies.publishDockerImages.mock.calls.at(-1)?.[0] as { pushTo?: string };
+      expect(lastPush.pushTo).toBe("flag.example/repo");
+    });
+  });
+
+  describe("bare honors the resolved docker decisions (resolution lives in build.ts)", () => {
+    it("buildDocker=false: binary only, no docker", async () => {
+      const b = fakeBuilder();
+      await runBuild({
+        core: b.core,
+        scenario: parseScenario({}),
+        options: { buildDocker: false },
+      });
+      expect(b.calls).toEqual(["buildSoftwareArchives", "buildSwJsonFiles"]);
+    });
+
+    it("buildDocker + pushDocker: build then push docker around the binary", async () => {
+      const b = fakeBuilder();
+      await runBuild({
+        core: b.core,
+        scenario: parseScenario({}),
+        options: { buildDocker: true, pushDocker: true },
+      });
+      expect(b.calls).toEqual([
+        "buildDockerImages",
+        "buildSoftwareArchives",
+        "publishDockerImages",
+        "buildSwJsonFiles",
+      ]);
+    });
+  });
+});
+
+describe("runBuild option pass-through", () => {
+  let b: ReturnType<typeof fakeBuilder>;
+  beforeEach(() => (b = fakeBuilder()));
+
+  it("forwards package ids and storage URL to the engine", async () => {
+    await runBuild({
+      core: b.core,
+      scenario: parseScenario({ channel: "dev", variant: "binary", location: "remote" }),
+      options: { ids: ["pkg-a"], storageUrl: "s3://bucket/dev" },
+    });
+    expect(b.spies.buildSoftwareArchives).toHaveBeenCalledWith(
+      expect.objectContaining({ ids: ["pkg-a"], skipIfEmpty: false }),
+    );
+    expect(b.spies.publishPackages).toHaveBeenCalledWith({
+      ids: ["pkg-a"],
+      storageURL: "s3://bucket/dev",
+    });
+  });
+});
+
+// The core safety invariant: "ready ⟺ the descriptor exists". A failed build or push must leave no
+// descriptor, so nothing downstream ever sees a broken half-build.
+describe("descriptor-last: not written when a step fails", () => {
+  it("skips the descriptor when the binary build throws", async () => {
+    const b = fakeBuilder();
+    b.spies.buildSoftwareArchives.mockRejectedValueOnce(new Error("build boom"));
+    await expect(
+      runBuild({
+        core: b.core,
+        scenario: parseScenario({ channel: "dev", variant: "binary", location: "remote" }),
+      }),
+    ).rejects.toThrow("build boom");
+    expect(b.spies.buildSwJsonFiles).not.toHaveBeenCalled();
+  });
+
+  it("skips the descriptor when the docker push throws", async () => {
+    const b = fakeBuilder();
+    b.spies.publishDockerImages.mockImplementationOnce(() => {
+      throw new Error("push boom");
+    });
+    await expect(
+      runBuild({
+        core: b.core,
+        scenario: parseScenario({ channel: "dev", variant: "docker", location: "remote" }),
+      }),
+    ).rejects.toThrow("push boom");
+    expect(b.spies.buildSwJsonFiles).not.toHaveBeenCalled();
+  });
+});

package/src/cmd/software/run-build.ts

@@ -0,0 +1,156 @@
+import {
+  util,
+  envs,
+  defaults,
+  type Builder,
+  type Logger,
+} from "@platforma-sdk/package-builder-lib";
+import type { Channel, Scenario } from "./knobs";
+import { ensureAwsProfile, ensureEcrLogin } from "./ecr-login";
+
+// Pass-through controls mirroring `pl-pkg build`. Empty means "engine default". The --docker-/
+// --conda- flag pairs are already collapsed to decisions at the CLI boundary (build.ts): only the
+// `bare` scenario reads buildDocker/pushDocker; condaBuild applies to every binary build.
+export type BuildOptions = {
+  ids?: string[];
+  force?: boolean;
+  contentRoot?: string;
+  storageUrl?: string;
+  dockerRegistry?: string;
+  dockerPushTo?: string;
+  buildDocker?: boolean;
+  pushDocker?: boolean;
+  condaBuild?: boolean;
+};
+
+// Build a scenario in one pass: build, push when remote, then write the descriptor last —
+// "ready ⟺ the descriptor exists". The pre-configured builder is injected; runBuild sets the
+// scenario's build mode and drives it.
+export async function runBuild(params: {
+  core: Builder;
+  scenario: Scenario;
+  options?: BuildOptions;
+  logger?: Logger;
+}): Promise<void> {
+  const { core, scenario, options: opts = {}, logger } = params;
+  const ids = opts.ids;
+  core.buildMode = buildModeForScenario(scenario);
+
+  const buildBinary = () =>
+    core.buildSoftwareArchives({
+      ids,
+      forceBuild: Boolean(opts.force),
+      contentRoot: opts.contentRoot,
+      // Tolerate a package with no archives only on a build-all run; when specific ids are
+      // requested, an empty build is a real error the caller wants to hear about.
+      skipIfEmpty: !ids,
+      condaBuild: opts.condaBuild,
+    });
+
+  switch (scenario.kind) {
+    case "binary-existing":
+      // Descriptor points at an already-published release artifact; nothing is built or pushed.
+      core.writePublishedArtifactInfo({ ids });
+      break;
+
+    case "no-software":
+      // Nothing built or pushed; the placeholder descriptor is written below.
+      break;
+
+    case "bare": {
+      // Bare pl-pkg-parity invocation; buildDocker/pushDocker were resolved at the CLI boundary.
+      if (opts.buildDocker) {
+        core.buildDockerImages({
+          ids,
+          registry: opts.dockerRegistry,
+          strictPlatformMatching: envs.isCI(),
+        });
+      }
+      await buildBinary();
+      if (opts.pushDocker) {
+        core.publishDockerImages({
+          ids,
+          pushTo: opts.dockerPushTo,
+          strictPlatformMatching: envs.isCI(),
+        });
+      }
+      break;
+    }
+
+    case "target": {
+      const { channel, variant, location } = scenario;
+      const docker = variant !== "binary";
+      const binary = variant !== "docker";
+      const remote = location === "remote";
+      const addr = resolveDockerAddresses(channel, opts);
+
+      // BUILD (descriptor not written yet).
+      if (docker) {
+        core.buildDockerImages({ ids, registry: addr.pull, strictPlatformMatching: envs.isCI() });
+      }
+      if (binary) await buildBinary();
+
+      // PUSH when remote. Pin the AWS credential chain once (docker login + S3 upload share it), but
+      // only for dev — the fallback profile is the dev SSO one.
+      if (remote && channel === "dev" && (docker || binary)) ensureAwsProfile(logger);
+      if (docker && remote) {
+        if (addr.autoLogin && addr.push) await ensureEcrLogin(addr.push, logger);
+        core.publishDockerImages({ ids, pushTo: addr.push, strictPlatformMatching: envs.isCI() });
+      }
+      if (binary && remote) {
+        // storageURL falls through to the engine, which resolves the dev/release endpoint.
+        await core.publishPackages({ ids, storageURL: opts.storageUrl });
+      }
+      break;
+    }
+
+    default:
+      util.assertNever(scenario);
+  }
+
+  // DESCRIPTOR LAST — only after build + push have succeeded.
+  core.buildSwJsonFiles({ packageIds: ids, noSoftware: scenario.kind === "no-software" });
+}
+
+function buildModeForScenario(scenario: Scenario): util.BuildMode {
+  if (scenario.kind !== "target") return "release";
+  if (scenario.channel === "release") return "release";
+  // Only a remote binary build needs dev-remote (it uploads an archive). Docker-only, or any
+  // local build, uses dev-local — docker naming is content-addressed by image ID regardless.
+  const binaryRemote = scenario.variant !== "docker" && scenario.location === "remote";
+  return binaryRemote ? "dev-remote" : "dev-local";
+}
+
+// Bare registry ref (host[:port]/path) with any URL scheme removed.
+function stripScheme(raw: string): string {
+  if (!raw.includes("://")) return raw; // already bare
+  const url = new URL(raw);
+  return url.host + url.pathname;
+}
+
+// A push target may carry a scheme selecting auto docker-login: `ecr://` opts in, anything else out.
+function parsePushTarget(raw: string): { registry: string; autoLogin: boolean } {
+  return { registry: stripScheme(raw), autoLogin: raw.startsWith("ecr://") };
+}
+
+// Docker push target + the pull address embedded in the descriptor. Precedence flag > channel env >
+// dev default (release has none); pull defaults to push; autoLogin follows the push target's ecr://.
+function resolveDockerAddresses(
+  channel: Channel,
+  opts: BuildOptions,
+): { pull?: string; push?: string; autoLogin: boolean } {
+  const isDev = channel === "dev";
+  const channelPush =
+    process.env[isDev ? envs.PL_DEV_DOCKER_PUSH_URL : envs.PL_RELEASE_DOCKER_PUSH_URL];
+  const channelPull =
+    process.env[isDev ? envs.PL_DEV_DOCKER_PULL_URL : envs.PL_RELEASE_DOCKER_PULL_URL];
+
+  const rawPush =
+    opts.dockerPushTo ?? channelPush ?? (isDev ? defaults.DEV_DOCKER_PUSH_TARGET : undefined);
+  const parsed = rawPush ? parsePushTarget(rawPush) : { registry: undefined, autoLogin: false };
+
+  const rawPull = opts.dockerRegistry ?? channelPull ?? rawPush;
+  const pull = rawPull ? stripScheme(rawPull) : undefined;
+
+  return { pull, push: parsed.registry, autoLogin: parsed.autoLogin };
+}

package/src/structure/__tests__/floor-version.test.ts

@@ -7,7 +7,7 @@ import {
   STRUCTURE_MIN_SUPPORTED,
   StructureVersionFloorError,
   assertVersionAboveFloor,
-  readStructureVersion,
+  readStructureMeta,
 } from "../engine/version";
 import { MemoryFileSystem } from "../engine/fs/memory";
 
@@ -45,7 +45,7 @@ describe("floor-version refusal", () => {
     const fs = new MemoryFileSystem({
       ".structure": JSON.stringify({ version: 0 }) + "\n",
     });
-    const version = await readStructureVersion(fs);
+    const version = readStructureMeta(fs).version;
     expect(version).toBe(0);
     expect(() => assertVersionAboveFloor(version, 1)).toThrow(StructureVersionFloorError);
   });

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

@@ -4,31 +4,24 @@
 import { describe, test, expect } from "vitest";
 import { MemoryFileSystem } from "../fs/memory";
 import {
-  readStructureVersion,
-  writeStructureVersion,
+  readStructureMeta,
+  writeStructureMeta,
   assertVersionAboveFloor,
   STRUCTURE_VERSION,
   StructureVersionFloorError,
 } from "../version";
 
 describe(".structure metadata file", () => {
-  test("missing file reads as 0", async () => {
+  test("missing file reads as version 0", async () => {
     const fs = new MemoryFileSystem();
-    expect(await readStructureVersion(fs)).toBe(0);
+    expect(readStructureMeta(fs)).toEqual({ version: 0 });
   });
 
-  test("write then read round-trips", async () => {
+  test("write then read round-trips the version", async () => {
     const fs = new MemoryFileSystem();
-    await writeStructureVersion(fs, 3);
-    expect(await readStructureVersion(fs)).toBe(3);
-    const written = fs.read(".structure");
-    expect(JSON.parse(written)).toEqual({ version: 3 });
-  });
-
-  test("default write uses STRUCTURE_VERSION", async () => {
-    const fs = new MemoryFileSystem();
-    await writeStructureVersion(fs);
-    expect(await readStructureVersion(fs)).toBe(STRUCTURE_VERSION);
+    writeStructureMeta(fs, { version: 3 });
+    expect(readStructureMeta(fs).version).toBe(3);
+    expect(JSON.parse(fs.read(".structure"))).toEqual({ version: 3 });
   });
 
   test("floor check throws below floor", () => {
@@ -37,8 +30,12 @@ describe(".structure metadata file", () => {
     expect(() => assertVersionAboveFloor(0, 0)).not.toThrow();
   });
 
-  test("invalid JSON reads as 0", async () => {
+  test("invalid JSON reads as version 0", async () => {
     const fs = new MemoryFileSystem({ ".structure": "not-json" });
-    expect(await readStructureVersion(fs)).toBe(0);
+    expect(readStructureMeta(fs)).toEqual({ version: 0 });
+  });
+
+  test("STRUCTURE_VERSION is a positive integer", () => {
+    expect(Number.isInteger(STRUCTURE_VERSION) && STRUCTURE_VERSION >= 1).toBe(true);
   });
 });

package/src/structure/engine/discovery-fs.ts

@@ -31,7 +31,7 @@ import type { BlockVars, Module, RunContext } from "./api";
 import type { FileSystem } from "./fs/api";
 import { discoverModules, type WorkspacePackage, type PackageJsonLike } from "./discovery";
 import { createRunContext } from "./ctx";
-import { STRUCTURE_META_FILE, STRUCTURE_MIN_SUPPORTED, assertVersionAboveFloor } from "./version";
+import { STRUCTURE_MIN_SUPPORTED, assertVersionAboveFloor, readStructureMeta } from "./version";
 
 export class StructureCliError extends Error {
   constructor(msg: string) {
@@ -147,15 +147,6 @@ export function parseBlockVars(facadeName: string): BlockVars {
   };
 }
 
-function readVersion(fs: FileSystem): number {
-  try {
-    const parsed = JSON.parse(fs.read(STRUCTURE_META_FILE)) as { version?: number };
-    return typeof parsed.version === "number" ? parsed.version : 0;
-  } catch {
-    return 0;
-  }
-}
-
 export type DiscoverInput = {
   /** Block-rooted filesystem (NodeFileSystem for the CLI, MemoryFileSystem
    *  for the Layer-2 round-trip). */
@@ -184,8 +175,8 @@ export function discoverRunContext(input: DiscoverInput): RunContext {
 
   const modules: Module[] = discoverModules(packages);
 
-  const version = readVersion(fs);
-  assertVersionAboveFloor(version, STRUCTURE_MIN_SUPPORTED);
+  const meta = readStructureMeta(fs);
+  assertVersionAboveFloor(meta.version, STRUCTURE_MIN_SUPPORTED);
 
   // BlockVars from the block-scope module's name (facade). Fall back to
   // the root module if a block has the root-as-block shape.
@@ -211,7 +202,7 @@ export function discoverRunContext(input: DiscoverInput): RunContext {
     updateDepsOnly: input.updateDepsOnly ?? false,
     modules,
     blockVars,
-    version,
+    version: meta.version,
     dryRun: input.dryRun ?? false,
   });
 }

package/src/structure/engine/runner.ts

@@ -48,7 +48,7 @@ import { parseJson, stringifyJson } from "./parsers/json";
 import type { JsonObject } from "./parsers/json";
 import { parseYaml, stringifyYaml } from "./parsers/yaml";
 import { parseLines, serializeLines } from "./parsers/lines";
-import { writeStructureVersion, STRUCTURE_META_FILE } from "./version";
+import { writeStructureMeta, STRUCTURE_VERSION, STRUCTURE_META_FILE } from "./version";
 
 export type ChangeAction = "create" | "update" | "delete" | "rename" | "noop";
 
@@ -499,7 +499,7 @@ export function run(
 
     if (isRefreshDefault) {
       // version bump
-      writeStructureVersion(fs);
+      writeStructureMeta(fs, { version: STRUCTURE_VERSION });
 
       // post-run recheck. Fresh discovery → fresh flatten →
       // dry-run. Any change list emits RecheckError on the first item.
@@ -517,7 +517,7 @@ export function run(
         opts.derivedPinLookup,
       );
       // Ignore .structure self-write (already up to date after
-      // writeStructureVersion above).
+      // writeStructureMeta above).
       const filtered = recheckChanges.filter((c) => c.path !== STRUCTURE_META_FILE);
       if (filtered.length > 0) {
         throw new RecheckError(filtered[0]!);
@@ -527,7 +527,7 @@ export function run(
     // Init mode: write .structure so the resulting tree carries the
     // current version (matches what `init` ships to disk).
     if (initMode && !ctx.dryRun) {
-      writeStructureVersion(fs);
+      writeStructureMeta(fs, { version: STRUCTURE_VERSION });
     }
 
     return { changes };