@platforma-sdk/block-tools 2.10.14 → 2.10.16

package/src/cmd/structure/init.ts

@@ -0,0 +1,65 @@
+import { Args, Command, Flags } from "@oclif/core";
+import path from "node:path";
+import {
+  resolveBlockVars,
+  runInit,
+  SUPPORTED_PLATFORMS,
+  type InitFlagValues,
+} from "../../structure/init-block-constructor";
+
+export default class StructureInit extends Command {
+  static override description =
+    "Scaffold a fresh Platforma block from the canonical structure. Missing flags are prompted unless --non-interactive.";
+
+  static override examples = [
+    "<%= config.bin %> <%= command.id %> --npm-org @platforma-open --org-scope my-org --short-name demo --no-software --non-interactive",
+    "<%= config.bin %> <%= command.id %> ./demo --npm-org @platforma-open --org-scope my-org --short-name demo --with-software --platform python --non-interactive",
+  ];
+
+  static override args = {
+    path: Args.string({
+      description: "target directory (default: <short-name> under the current directory)",
+    }),
+  };
+
+  static override flags = {
+    "npm-org": Flags.string({ description: "npm org, e.g. @platforma-open" }),
+    "org-scope": Flags.string({ description: "org scope, e.g. my-org" }),
+    "short-name": Flags.string({ description: "block short name, e.g. mixcr-clonotyping" }),
+    "with-software": Flags.boolean({ description: "include a software module" }),
+    "no-software": Flags.boolean({ description: "omit the software module" }),
+    platform: Flags.string({
+      description: "software platform (single-valued)",
+      options: [...SUPPORTED_PLATFORMS],
+    }),
+    "non-interactive": Flags.boolean({
+      description: "error on any missing flag instead of prompting",
+    }),
+  };
+
+  public async run(): Promise<void> {
+    const { args, flags } = await this.parse(StructureInit);
+
+    if (flags["with-software"] && flags["no-software"]) {
+      this.error("--with-software and --no-software are mutually exclusive.");
+    }
+    const withSoftware = flags["with-software"] ? true : flags["no-software"] ? false : undefined;
+
+    const flagValues: InitFlagValues = {
+      npmOrg: flags["npm-org"],
+      orgScope: flags["org-scope"],
+      shortName: flags["short-name"],
+      withSoftware,
+      platform: flags.platform,
+      nonInteractive: flags["non-interactive"],
+    };
+
+    const vars = await resolveBlockVars(flagValues);
+    const blockPath = args.path
+      ? path.resolve(args.path)
+      : path.resolve(process.cwd(), vars.shortName);
+    const templatesRoot = path.join(this.config.root, "src", "structure", "templates");
+
+    await runInit({ vars, blockPath, templatesRoot, log: (m) => this.log(m) });
+  }
+}

package/src/cmd/structure/refresh.ts

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

package/src/cmd/update-deps.ts

@@ -1,13 +1,25 @@
 import { Command } from "@oclif/core";
-import { updatePackages } from "@platforma-sdk/blocks-deps-updater";
 
+/**
+ * Deprecated. Phase-2 forwarding alias (spec.md § "Coexistence And
+ * Retirement"): delegates to `structure refresh --update-deps-only`,
+ * which lands at parity with the old `blocks-deps-updater` catalog-bump
+ * semantics. Prints a deprecation warning; will be removed once the
+ * structurer path has been live without surprises.
+ */
 export default class UpdateDeps extends Command {
   static override description =
-    "Updates @platforma-sdk and @milaboratories packages in pnpm-workspace.yaml catalog to their latest versions from npm registry.";
+    "[DEPRECATED] Use `block-tools structure refresh --update-deps-only`. This alias delegates to it.";
 
   static override examples = ["<%= config.bin %> <%= command.id %>"];
 
   public async run(): Promise<void> {
-    await updatePackages();
+    this.warn(
+      "`block-tools update-deps` is deprecated and will be removed in a future release. " +
+        "Use `block-tools structure refresh --update-deps-only` instead. Delegating now.",
+    );
+    // oclif resolves commands by their internal colon-form id, even
+    // though the user-facing form uses the configured " " topic separator.
+    await this.config.runCommand("structure:refresh", ["--update-deps-only"]);
   }
 }

package/src/structure/__tests__/colocated-test-wiring.test.ts

@@ -0,0 +1,107 @@
+// End-to-end (real STRUCTURE): co-located unit tests wire the vitest `test`
+// script + node ambient types into a scope, and ONLY that scope. A
+// test-less scope stays lean (no test script, no @types/node, no node types
+// in tsconfig) and a refresh of a test-less block is a fixpoint.
+
+import { describe, test, expect } from "vitest";
+import { parse as parseYaml } from "yaml";
+import { simulateInit, defaultTemplateProvider } from "../engine/testing";
+import { run as engineRun } from "../engine/runner";
+import { discoverRunContext } from "../engine/discovery-fs";
+import { STRUCTURE } from "../structure-definition";
+import { SDK_CATALOG_PACKAGES } from "../rules/root-pnpm-workspace";
+import type { BlockVars } from "../engine/api";
+
+const VARS: BlockVars = {
+  facadeName: "@platforma-open/test-org.demo",
+  baseName: "test-org.demo",
+  npmOrg: "@platforma-open",
+  orgScope: "test-org",
+  shortName: "demo",
+};
+
+const mockLookup = (name: string): string | undefined =>
+  SDK_CATALOG_PACKAGES.includes(name) ? "9.9.9" : undefined;
+
+type Pkg = {
+  scripts?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+};
+type Tsconfig = { compilerOptions?: { types?: unknown } };
+
+async function refresh(fs: Awaited<ReturnType<typeof simulateInit>>["fs"]) {
+  const ctx = discoverRunContext({ fs, isSdkInternal: false });
+  engineRun(STRUCTURE, fs, ctx, {
+    templates: defaultTemplateProvider(),
+    rediscover: () => discoverRunContext({ fs, isSdkInternal: false, dryRun: true }),
+  });
+}
+
+describe("co-located test wiring (real STRUCTURE)", () => {
+  test("a model test wires test script + @types/node devDep + node types; ui (no test) stays lean", async () => {
+    const { fs } = simulateInit({ vars: VARS, registryLookup: mockLookup });
+    // Author drops a co-located unit test into the model scope only.
+    fs.write("model/src/label.test.ts", `import { test } from "vitest";\ntest("x", () => {});\n`);
+
+    await refresh(fs);
+
+    const model = JSON.parse(fs.read("model/package.json")) as Pkg;
+    expect(model.scripts?.test).toBe("vitest run --passWithNoTests");
+    expect(model.devDependencies?.["@types/node"]).toBe("*");
+    // promoted from peer -> dev (single-section invariant drops the peer)
+    expect(model.peerDependencies?.["@types/node"]).toBeUndefined();
+
+    const modelTs = JSON.parse(fs.read("model/tsconfig.json")) as Tsconfig;
+    expect(modelTs.compilerOptions?.types).toEqual(["node"]);
+
+    // ui has no co-located test -> stays lean.
+    const ui = JSON.parse(fs.read("ui/package.json")) as Pkg;
+    expect(ui.scripts?.test).toBeUndefined();
+    expect(ui.devDependencies?.["@types/node"]).toBeUndefined();
+    const uiTs = JSON.parse(fs.read("ui/tsconfig.json")) as Tsconfig;
+    expect(uiTs.compilerOptions?.types).toBeUndefined();
+  });
+
+  test("test-less block: refresh is a fixpoint (no test script, no node types)", async () => {
+    const { fs } = simulateInit({ vars: VARS, registryLookup: mockLookup });
+
+    const before = {
+      model: fs.read("model/package.json"),
+      modelTs: fs.read("model/tsconfig.json"),
+      ui: fs.read("ui/package.json"),
+      uiTs: fs.read("ui/tsconfig.json"),
+      workflow: fs.read("workflow/package.json"),
+    };
+
+    await refresh(fs);
+
+    expect(fs.read("model/package.json")).toBe(before.model);
+    expect(fs.read("model/tsconfig.json")).toBe(before.modelTs);
+    expect(fs.read("ui/package.json")).toBe(before.ui);
+    expect(fs.read("ui/tsconfig.json")).toBe(before.uiTs);
+    expect(fs.read("workflow/package.json")).toBe(before.workflow);
+
+    // none of the test-less scopes carry a `test` script
+    const model = JSON.parse(before.model) as Pkg;
+    const ui = JSON.parse(before.ui) as Pkg;
+    const workflow = JSON.parse(before.workflow) as Pkg;
+    expect(model.scripts?.test).toBeUndefined();
+    expect(ui.scripts?.test).toBeUndefined();
+    expect(workflow.scripts?.test).toBeUndefined();
+  });
+
+  test("a workflow test wires its test script (no node-types wiring needed there)", async () => {
+    const { fs } = simulateInit({ vars: VARS, registryLookup: mockLookup });
+    fs.write("workflow/src/wf.test.ts", `import { test } from "vitest";\ntest("x", () => {});\n`);
+
+    await refresh(fs);
+
+    const workflow = JSON.parse(fs.read("workflow/package.json")) as Pkg;
+    expect(workflow.scripts?.test).toBe("vitest run --passWithNoTests");
+    // workflow tsconfig stays standalone — no node types added there
+    const wfTs = parseYaml(fs.read("workflow/tsconfig.json")) as { types?: unknown };
+    // (workflow tsconfig is JSON, but parseYaml reads JSON too; types:[] unchanged)
+    expect(wfTs.types).toEqual([]);
+  });
+});

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

@@ -0,0 +1,52 @@
+// Floor-version refusal — when `.structure` carries a version below
+// `STRUCTURE_MIN_SUPPORTED`, structurer entry points must abort with a
+// hard error pointing at the legacy-migration skill.
+
+import { describe, test, expect } from "vitest";
+import {
+  STRUCTURE_MIN_SUPPORTED,
+  StructureVersionFloorError,
+  assertVersionAboveFloor,
+  readStructureVersion,
+} from "../engine/version";
+import { MemoryFileSystem } from "../engine/fs/memory";
+
+describe("floor-version refusal", () => {
+  test("version 0 below floor 1 throws StructureVersionFloorError", () => {
+    expect(() => assertVersionAboveFloor(0, 1)).toThrow(StructureVersionFloorError);
+  });
+
+  test("error message names the version, the floor, and points at legacy migration", () => {
+    try {
+      assertVersionAboveFloor(0, 1);
+      throw new Error("expected throw");
+    } catch (e) {
+      expect(e).toBeInstanceOf(StructureVersionFloorError);
+      const msg = (e as Error).message;
+      expect(msg).toContain("0");
+      expect(msg).toContain("1");
+      expect(msg).toMatch(/legacy-migration/i);
+    }
+  });
+
+  test("at-floor and above-floor versions do not throw", () => {
+    expect(() => assertVersionAboveFloor(1, 1)).not.toThrow();
+    expect(() => assertVersionAboveFloor(5, 1)).not.toThrow();
+  });
+
+  test("default floor is STRUCTURE_MIN_SUPPORTED", () => {
+    // Document the constant invariant: shipping floor stays 0 until a
+    // legacy-migration skill exists. Bumping the floor without that
+    // skill in place would brick existing blocks.
+    expect(STRUCTURE_MIN_SUPPORTED).toBe(0);
+  });
+
+  test("read+assert against a fixture .structure with version 0 and floor 1 throws", async () => {
+    const fs = new MemoryFileSystem({
+      ".structure": JSON.stringify({ version: 0 }) + "\n",
+    });
+    const version = await readStructureVersion(fs);
+    expect(version).toBe(0);
+    expect(() => assertVersionAboveFloor(version, 1)).toThrow(StructureVersionFloorError);
+  });
+});

package/src/structure/__tests__/init-catalog-resolution.test.ts

@@ -0,0 +1,82 @@
+// Layer-2: the version-model redesign end-to-end against the real
+// STRUCTURE, mocked registry (no network).
+//
+// Proves the three promises of the `onInitOrUpdate` redesign:
+//   1. init writes REAL latest SDK versions (the `onInitOrUpdate` frame
+//      fires on init), while the infra floor stays `~`-pinned and untouched;
+//   2. a default refresh touches NO catalog versions — the central
+//      no-pin-on-refresh guard (byte-identical pnpm-workspace.yaml);
+//   3. init = fixpoint of check: a dry-run after init reports no
+//      pnpm-workspace.yaml change.
+
+import { describe, test, expect } from "vitest";
+import { parse as parseYaml } from "yaml";
+import { simulateInit, defaultTemplateProvider } from "../engine/testing";
+import { run as engineRun } from "../engine/runner";
+import { discoverRunContext } from "../engine/discovery-fs";
+import { STRUCTURE } from "../structure-definition";
+import { matchesBumpPattern } from "../engine/registry-client";
+import { SDK_CATALOG_PACKAGES, INFRA_CATALOG_FLOOR } from "../rules/root-pnpm-workspace";
+import type { BlockVars } from "../engine/api";
+
+const VARS: BlockVars = {
+  facadeName: "@platforma-open/test-org.demo",
+  baseName: "test-org.demo",
+  npmOrg: "@platforma-open",
+  orgScope: "test-org",
+  shortName: "demo",
+};
+
+// A distinct mock "latest" per SDK package so we can prove per-name
+// resolution. Anything not in the SDK set resolves to undefined.
+const LATEST: Record<string, string> = Object.fromEntries(
+  SDK_CATALOG_PACKAGES.map((n, i) => [n, `9${i}.4.2`]),
+);
+const mockLookup = (name: string): string | undefined => LATEST[name];
+
+function catalogOf(yamlText: string): Record<string, string> {
+  return (parseYaml(yamlText) as { catalog: Record<string, string> }).catalog;
+}
+
+describe("version model — init fetch + no-pin-on-refresh", () => {
+  test("init writes latest SDK versions; infra floor stays ~-pinned", async () => {
+    const { fs } = simulateInit({ vars: VARS, registryLookup: mockLookup });
+    const cat = catalogOf(fs.read("pnpm-workspace.yaml"));
+
+    // Every SDK family entry resolved to the mocked latest (exact, no modifier).
+    for (const name of SDK_CATALOG_PACKAGES) {
+      expect(matchesBumpPattern(name)).toBe(true);
+      expect(cat[name]).toBe(LATEST[name]);
+    }
+    // Infra floor untouched — still its curated `~` pin.
+    for (const [name, floor] of Object.entries(INFRA_CATALOG_FLOOR)) {
+      expect(cat[name]).toBe(floor);
+    }
+  });
+
+  test("default refresh touches NO catalog versions (byte-identical)", async () => {
+    const { fs } = simulateInit({ vars: VARS, registryLookup: mockLookup });
+    const afterInit = fs.read("pnpm-workspace.yaml");
+
+    // A real default refresh — no registryLookup passed, proving refresh
+    // never fetches. The onInitOrUpdate bump leaf is excluded from "default".
+    const refreshCtx = discoverRunContext({ fs, isSdkInternal: false });
+    engineRun(STRUCTURE, fs, refreshCtx, {
+      templates: defaultTemplateProvider(),
+      rediscover: () => discoverRunContext({ fs, isSdkInternal: false, dryRun: true }),
+    });
+
+    const afterRefresh = fs.read("pnpm-workspace.yaml");
+    expect(afterRefresh).toBe(afterInit);
+  });
+
+  test("init = fixpoint of check: dry-run reports no pnpm-workspace.yaml change", async () => {
+    const { fs, ctx } = simulateInit({ vars: VARS, registryLookup: mockLookup });
+    const checkCtx = { ...ctx, dryRun: true };
+    const result = engineRun(STRUCTURE, fs, checkCtx, {
+      templates: defaultTemplateProvider(),
+    });
+    const workspaceChange = result.changes.find((c) => c.path === "pnpm-workspace.yaml");
+    expect(workspaceChange).toBeUndefined();
+  });
+});

package/src/structure/__tests__/init-check-parity.test.ts

@@ -0,0 +1,59 @@
+// Invariant — `init → check` must report zero diff for every supported
+// BlockVars variant.
+//
+// For each variant:
+//  1. simulateInit populates an in-memory FS with seeds + scaffolds +
+//     fixed + managed in canonical form, then re-discovers the module set
+//     from that written FS (the same DISCOVERY `check` runs) — a real
+//     init→check round-trip, not a reuse of init's module set.
+//  2. engine.run is invoked with `dryRun: true` on the same FS.
+//  3. result.changes must be empty (every primitive idempotent).
+
+import { describe, test, expect } from "vitest";
+import type { BlockVars, RunContext } from "../engine/api";
+import { STRUCTURE } from "../structure-definition";
+import { run as engineRun } from "../engine/runner";
+import { defaultTemplateProvider, simulateInit } from "../engine/testing";
+
+const TEMPLATES = defaultTemplateProvider();
+
+async function checkZeroDiff(vars: BlockVars): Promise<void> {
+  const { fs, ctx } = simulateInit({ vars });
+  const checkCtx: RunContext = { ...ctx, dryRun: true };
+  const result = engineRun(STRUCTURE, fs, checkCtx, { templates: TEMPLATES });
+  if (result.changes.length > 0) {
+    // Surface the first diff for diagnostics.
+    const first = result.changes[0]!;
+    throw new Error(
+      `Layer-2 invariant violated for ${vars.facadeName}: ` +
+        `${first.primitive} '${first.path}' (scope=${first.scope}, action=${first.action}). ` +
+        `Total changes: ${result.changes.length}.`,
+    );
+  }
+  expect(result.changes).toEqual([]);
+}
+
+describe("Layer-2: init → check zero diff", () => {
+  test("with software (single platform)", async () => {
+    const vars: BlockVars = {
+      facadeName: "@platforma-open/test-org.demo",
+      baseName: "test-org.demo",
+      npmOrg: "@platforma-open",
+      orgScope: "test-org",
+      shortName: "demo",
+      softwarePlatform: "python",
+    };
+    await checkZeroDiff(vars);
+  });
+
+  test("no software", async () => {
+    const vars: BlockVars = {
+      facadeName: "@platforma-open/test-org.demo",
+      baseName: "test-org.demo",
+      npmOrg: "@platforma-open",
+      orgScope: "test-org",
+      shortName: "demo",
+    };
+    await checkZeroDiff(vars);
+  });
+});

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

@@ -0,0 +1,60 @@
+// Snapshot of the canonical `model/package.json` that `init` produces
+// for a representative BlockVars set. Catches accidental template /
+// rule drift — any rule-set change that intentionally shifts the
+// generated content must be paired with an updated fixture.
+
+import { describe, expect, test } from "vitest";
+import { simulateInit } from "../engine/testing";
+import type { BlockVars } from "../engine/api";
+
+const EXPECTED_MODEL_PACKAGE_JSON = `{
+  "name": "@platforma-open/test-org.demo.model",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "sources": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./dist/*": "./dist/*"
+  },
+  "scripts": {
+    "fmt": "ts-builder format",
+    "watch": "ts-builder build --target block-model --watch",
+    "build": "ts-builder build --target block-model && block-tools build-model",
+    "check": "ts-builder check --target block-model"
+  },
+  "dependencies": {
+    "@platforma-sdk/model": "catalog:"
+  },
+  "devDependencies": {
+    "@milaboratories/ts-builder": "catalog:",
+    "@milaboratories/ts-configs": "catalog:",
+    "@platforma-sdk/block-tools": "catalog:",
+    "vitest": "catalog:"
+  },
+  "peerDependencies": {
+    "@types/node": "*",
+    "typescript": "*"
+  }
+}
+`;
+
+describe("model/package.json snapshot", () => {
+  test("init produces canonical model/package.json", async () => {
+    const vars: BlockVars = {
+      facadeName: "@platforma-open/test-org.demo",
+      baseName: "test-org.demo",
+      npmOrg: "@platforma-open",
+      orgScope: "test-org",
+      shortName: "demo",
+    };
+    const { fs } = simulateInit({ vars });
+    const actual = fs.read("model/package.json");
+    expect(actual).toBe(EXPECTED_MODEL_PACKAGE_JSON);
+  });
+});

package/src/structure/__tests__/oxfmt-clean-init.test.ts

@@ -0,0 +1,64 @@
+// The model + ui scopes are the two `ts-builder check` runs oxfmt on, so
+// their rules cede field / dependency ordering to oxfmt (no enforce* calls).
+// This guard proves the init output is already oxfmt-clean — `oxfmt --check`
+// passes with no prior `pnpm fmt` — so the first refresh/check is a no-op.
+//
+// Requires the `oxfmt` binary (declared as a block-tools devDep). When it
+// is genuinely unavailable the test skips with a warning rather than
+// failing an environment that has no formatter installed.
+
+import { describe, test, expect } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { simulateInit } from "../engine/testing";
+import type { BlockVars } from "../engine/api";
+
+function oxfmtAvailable(): boolean {
+  const r = spawnSync("oxfmt", ["--help"], { encoding: "utf-8" });
+  return !r.error;
+}
+
+describe("oxfmt-clean init output (model + ui)", () => {
+  const available = oxfmtAvailable();
+
+  // Both files `ts-builder check` runs oxfmt on, per scope: package.json AND
+  // tsconfig.json. tsconfig is the regression that motivated the
+  // width-collapsing serialiser — oxfmt collapses its single-element
+  // `include` array, which the plain `JSON.stringify` expansion left
+  // non-clean. Guard both so a future serialiser change is caught here, not
+  // in the build→check gate.
+  const FILES = ["package.json", "tsconfig.json"];
+
+  test.runIf(available)("model + ui init package.json + tsconfig pass oxfmt --check", async () => {
+    const vars: BlockVars = {
+      facadeName: "@platforma-open/test-org.demo",
+      baseName: "test-org.demo",
+      npmOrg: "@platforma-open",
+      orgScope: "test-org",
+      shortName: "demo",
+    };
+    const { fs } = simulateInit({ vars });
+
+    const root = mkdtempSync(path.join(tmpdir(), "oxfmt-clean-"));
+    for (const scope of ["model", "ui"]) {
+      mkdirSync(path.join(root, scope), { recursive: true });
+      for (const fileName of FILES) {
+        const content = fs.read(`${scope}/${fileName}`);
+        writeFileSync(path.join(root, scope, fileName), content);
+        const r = spawnSync("oxfmt", ["--check", path.join(scope, fileName)], {
+          cwd: root,
+          encoding: "utf-8",
+        });
+        expect(r.status, `${scope}/${fileName} is not oxfmt-clean:\n${r.stdout}\n${r.stderr}`).toBe(
+          0,
+        );
+      }
+    }
+  });
+
+  if (!available) {
+    test.skip("oxfmt binary unavailable — skipping oxfmt-clean guard", () => {});
+  }
+});