@platforma-sdk/block-tools 2.11.3 → 2.11.4

package/src/v2/from_pack_v2.test.ts

@@ -0,0 +1,142 @@
+import { test, expect } from "vitest";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import fsp from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { loadPackDescriptionFromManifest } from "./source_package";
+import { buildPublishedCoords, resolveToRegistry } from "./resolve_to_registry";
+
+/** Writes a minimal-but-valid v2 block-pack into a fresh temp module root and
+ * returns its path (the folder containing `block-pack/`). */
+async function makePackedBlock(): Promise<string> {
+  const moduleRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "from-pack-v2-"));
+  const blockPackDir = path.join(moduleRoot, "block-pack");
+  await fsp.mkdir(blockPackDir);
+
+  await fsp.writeFile(path.join(blockPackDir, "model.json"), JSON.stringify({ code: {} }));
+  await fsp.writeFile(path.join(blockPackDir, "main.plj.gz"), "workflow-bytes");
+  await fsp.writeFile(path.join(blockPackDir, "ui.tgz"), "ui-tarball-bytes");
+
+  const manifest = {
+    schema: "v2",
+    description: {
+      id: { organization: "milaboratories", name: "test-from-pack", version: "1.0.0" },
+      components: {
+        workflow: { type: "workflow-v1", main: { type: "relative", path: "main.plj.gz" } },
+        model: { type: "relative", path: "model.json" },
+        ui: { type: "relative", path: "ui.tgz" },
+      },
+      meta: {
+        title: "Test",
+        description: "Test block",
+        organization: { name: "MiLaboratories", url: "https://milaboratories.com" },
+      },
+    },
+    timestamp: 1782150933623,
+    files: [
+      { name: "main.plj.gz", size: 1, sha256: "A".repeat(64) },
+      { name: "model.json", size: 1, sha256: "A".repeat(64) },
+      { name: "ui.tgz", size: 1, sha256: "A".repeat(64) },
+    ],
+  };
+  await fsp.writeFile(path.join(blockPackDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+
+  return moduleRoot;
+}
+
+test("loadPackDescriptionFromManifest resolves manifest entries to absolute FS paths", async () => {
+  const moduleRoot = await makePackedBlock();
+  const blockPackDir = path.join(moduleRoot, "block-pack");
+
+  const description = await loadPackDescriptionFromManifest(blockPackDir);
+
+  // workflow + model resolve to absolute-file refs inside block-pack/.
+  expect(description.components.workflow.main).toStrictEqual({
+    type: "absolute-file",
+    file: path.join(blockPackDir, "main.plj.gz"),
+  });
+  expect(description.components.model).toStrictEqual({
+    type: "absolute-file",
+    file: path.join(blockPackDir, "model.json"),
+  });
+  // ui (a ui.tgz archive) resolves into the absolute-folder slot.
+  expect(description.components.ui).toStrictEqual({
+    type: "absolute-folder",
+    folder: path.join(blockPackDir, "ui.tgz"),
+  });
+
+  // The id passes through unchanged.
+  expect(description.id).toStrictEqual({
+    organization: "milaboratories",
+    name: "test-from-pack",
+    version: "1.0.0",
+  });
+
+  // All resolved paths exist on disk.
+  expect(path.isAbsolute(description.components.model.file)).toBe(true);
+  expect(existsSync(description.components.workflow.main.file)).toBe(true);
+  expect(existsSync(description.components.model.file)).toBe(true);
+  expect(existsSync(description.components.ui.folder)).toBe(true);
+});
+
+test("loadPackDescriptionFromManifest works against a real packed sum-numbers-v3", async () => {
+  // Runs when the block has been built+packed; skips gracefully in a clean
+  // checkout where block-pack/ is gitignored. Guards against manifest-shape
+  // drift the hermetic fixture above can't catch.
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const real = path.resolve(here, "../../../../etc/blocks/sum-numbers-v3/block");
+  if (!existsSync(path.join(real, "block-pack", "manifest.json"))) return;
+
+  const description = await loadPackDescriptionFromManifest(path.join(real, "block-pack"));
+  expect(existsSync(description.components.model.file)).toBe(true);
+  expect(existsSync(description.components.workflow.main.file)).toBe(true);
+  expect(existsSync(description.components.ui.folder)).toBe(true);
+  expect(description.components.ui.folder.endsWith("ui.tgz")).toBe(true);
+});
+
+test("resolveToRegistry reads published.json into a from-registry-v2 spec", async () => {
+  const folder = await fsp.mkdtemp(path.join(os.tmpdir(), "resolve-reg-"));
+  const blockPackDir = path.join(folder, "block-pack");
+  await fsp.mkdir(blockPackDir);
+  // A stray `channel` in the file is ignored — channels are mutable registry
+  // pointers, not part of the pinned coordinates.
+  await fsp.writeFile(
+    path.join(blockPackDir, "published.json"),
+    JSON.stringify({
+      registryUrl: "https://cdn.platforma.bio/blocks",
+      id: { organization: "milaboratories", name: "test-from-pack", version: "2.3.4" },
+      channel: "stable",
+    }),
+  );
+
+  // from-pack-v2 carries `packUrl` (the block-pack dir as a file: URL);
+  // published.json lives inside it.
+  const spec = await resolveToRegistry({
+    type: "from-pack-v2",
+    packUrl: pathToFileURL(blockPackDir).href,
+  });
+  expect(spec).toStrictEqual({
+    type: "from-registry-v2",
+    registryUrl: "https://cdn.platforma.bio/blocks",
+    id: { organization: "milaboratories", name: "test-from-pack", version: "2.3.4" },
+  });
+});
+
+test("resolveToRegistry throws the documented error when published.json is missing", async () => {
+  const folder = await fsp.mkdtemp(path.join(os.tmpdir(), "resolve-reg-missing-"));
+  await expect(resolveToRegistry({ type: "dev-v2", folder })).rejects.toThrow(
+    /has no published\.json/,
+  );
+});
+
+test("buildPublishedCoords shapes the payload (immutable coords only)", () => {
+  const id = { organization: "milaboratories", name: "test-from-pack", version: "1.0.0" };
+
+  expect(
+    buildPublishedCoords({ registryUrl: "https://cdn.platforma.bio/blocks", id }),
+  ).toStrictEqual({
+    registryUrl: "https://cdn.platforma.bio/blocks",
+    id,
+  });
+});

package/src/v2/index.ts

@@ -1,4 +1,5 @@
 export * from "./model";
 export * from "./build_dist";
 export * from "./source_package";
+export * from "./resolve_to_registry";
 export * from "./registry";

package/src/v2/model/block_components.ts

@@ -5,8 +5,10 @@ import type {
   ContentAbsoluteFile,
   ContentAbsoluteFolder,
   ContentAbsoluteUrl,
+  ContentRelative,
 } from "@milaboratories/pl-model-middle-layer";
 import { mapRemoteToAbsolute } from "@milaboratories/pl-model-middle-layer";
+import path from "node:path";
 import {
   cpAbsoluteToRelative,
   packFolderToRelativeTgz,
@@ -45,6 +47,37 @@ export function resolveBlockComponents(
   };
 }
 
+/**
+ * Resolves a manifest's relative component paths against the `block-pack/`
+ * folder of a consumed package. Workflow main and model become absolute-file
+ * refs; the UI (a `ui.tgz` archive) resolves to its absolute path carried in
+ * the `absolute-folder` slot — `BlockComponentsDescription` types `ui` as a
+ * folder, and for manifest-consumed packs that slot holds the tgz file path
+ * (the `from-pack-v2` loader reads `.ui.folder` and feeds it to the lazy
+ * `local-tgz` frontend). Counterpart to `resolveBlockComponents`, which
+ * resolves a raw `package.json` description against authoring source.
+ */
+export function resolveManifestBlockComponents(
+  manifest: BlockComponentsManifest,
+  blockPackDir: string,
+): BlockComponentsDescription {
+  const toAbsFile = (c: ContentRelative): ContentAbsoluteFile => ({
+    type: "absolute-file",
+    file: path.resolve(blockPackDir, c.path),
+  });
+  return {
+    workflow: {
+      type: "workflow-v1",
+      main: toAbsFile(manifest.workflow.main),
+    },
+    model: toAbsFile(manifest.model),
+    ui: {
+      type: "absolute-folder",
+      folder: path.resolve(blockPackDir, manifest.ui.path),
+    },
+  };
+}
+
 /**
  * Copies file references for workflow and model into `dstFolder`, packs the
  * UI folder into `ui.tgz`, returning the manifest form with relative paths.

package/src/v2/model/block_meta.ts

@@ -73,6 +73,24 @@ export async function resolveBlockPackMeta(
   );
 }
 
+/**
+ * Resolves a manifest's relative text/binary references against the
+ * `block-pack/` folder of a consumed package. Counterpart to
+ * `resolveBlockPackMeta` (which resolves raw `package.json` meta against
+ * authoring source); inlined explicit content passes through unchanged.
+ */
+export async function resolveManifestBlockPackMeta(
+  manifest: BlockPackMetaManifest,
+  blockPackDir: string,
+): Promise<BlockPackMetaDescription> {
+  const toAbs = mapLocalToAbsolute(blockPackDir);
+  return transformBlockPackMeta(
+    manifest,
+    async (v) => toAbs(v),
+    async (v) => toAbs(v),
+  );
+}
+
 /**
  * Copies absolute text/binary file references into `dstFolder` and returns
  * the manifest form with relative paths.

package/src/v2/resolve_to_registry.ts

@@ -0,0 +1,84 @@
+import path from "node:path";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import type {
+  BlockPackDevV2,
+  BlockPackFromPackV2,
+  BlockPackFromRegistryV2,
+  BlockPackId,
+} from "@milaboratories/pl-model-middle-layer";
+
+/** File written by `block-tools publish` into `block-pack/`, carrying the
+ * registry coordinates of the published version. Holds only the immutable
+ * coordinates (CDN serve URL + version id). No `channel`: channels are moving
+ * pointers in the registry — a version can be promoted/moved later — so the
+ * channel at publish time is transient state we can't pin here. Update-checking
+ * resolves the channel at read time (`BlockPackFromRegistryV2.channel` is
+ * optional; the watcher defaults stable → any). */
+export const PublishedCoordsFileName = "published.json";
+
+/** Registry coordinates persisted in `block-pack/published.json`. */
+export interface PublishedCoords {
+  /** CDN serve URL the block is fetched from (not the S3 upload bucket). */
+  registryUrl: string;
+  id: BlockPackId;
+}
+
+/**
+ * Builds the `published.json` payload. Pure (no filesystem) so it is unit
+ * testable.
+ */
+export function buildPublishedCoords(args: {
+  registryUrl: string;
+  id: BlockPackId;
+}): PublishedCoords {
+  return {
+    registryUrl: args.registryUrl,
+    id: args.id,
+  };
+}
+
+/** Writes `block-pack/published.json` into the given block-pack folder. */
+export async function writePublishedCoords(
+  blockPackDir: string,
+  coords: PublishedCoords,
+): Promise<void> {
+  const file = path.resolve(blockPackDir, PublishedCoordsFileName);
+  await fsp.writeFile(file, JSON.stringify(coords, null, 2), { encoding: "utf-8" });
+}
+
+/**
+ * Resolves a local block locator (`dev-v2` or `from-pack-v2`) to its registry
+ * coordinates by reading `published.json`. `published.json` lives inside the
+ * block-pack directory (written there by `block-tools publish`), so for
+ * `from-pack-v2` we read it directly from `packUrl` (converted to a path at this
+ * Node boundary) — the structurer owns the layout, we do not re-derive it. For a
+ * `dev-v2` block folder it sits under
+ * `<folder>/block-pack/`. The facade's engine-generated `from-pack-v2`
+ * BlockPointer feeds this so a consumed block can be installed via the registry
+ * path. Throws when the block was never published.
+ */
+export async function resolveToRegistry(
+  locator: BlockPackDevV2 | BlockPackFromPackV2,
+): Promise<BlockPackFromRegistryV2> {
+  const file =
+    locator.type === "from-pack-v2"
+      ? path.resolve(fileURLToPath(locator.packUrl), PublishedCoordsFileName)
+      : path.resolve(locator.folder, "block-pack", PublishedCoordsFileName);
+  if (!fs.existsSync(file)) {
+    throw new Error(
+      `Block has no ${PublishedCoordsFileName} at ${file} — ` +
+        `was the block published? Run block-tools publish before consuming via registry.`,
+    );
+  }
+  const raw = JSON.parse(await fsp.readFile(file, { encoding: "utf-8" })) as {
+    registryUrl: string;
+    id: BlockPackFromRegistryV2["id"];
+  };
+  return {
+    type: "from-registry-v2",
+    registryUrl: raw.registryUrl,
+    id: raw.id,
+  };
+}

package/src/v2/source_package.ts

@@ -1,13 +1,19 @@
 import path from "node:path";
 import { tryLoadFile } from "../util";
 import type { BlockPackDescriptionAbsolute } from "./model";
-import { resolveBlockPackDescription } from "./model";
+import {
+  resolveBlockPackDescription,
+  resolveManifestBlockComponents,
+  resolveManifestBlockPackMeta,
+} from "./model";
 import type { MiLogger } from "@milaboratories/ts-helpers";
 import { notEmpty } from "@milaboratories/ts-helpers";
 import fsp from "node:fs/promises";
 import type { BlockPackDescriptionRaw, BlockPackId } from "@milaboratories/pl-model-middle-layer";
 import {
   BlockPackDescriptionFromPackageJsonRaw,
+  BlockPackManifest,
+  BlockPackManifestFile,
   SemVer,
 } from "@milaboratories/pl-model-middle-layer";
 
@@ -89,3 +95,30 @@ export async function loadPackDescription(
   const descriptionRaw = await loadPackDescriptionRaw(moduleRoot);
   return await resolveBlockPackDescription(descriptionRaw, moduleRoot);
 }
+
+/** Folder name (under a consumed package root) holding the v2 block-pack artifacts. */
+export const BlockPackFolderName = "block-pack";
+
+/**
+ * Loads a block-pack description from a block-pack directory's `manifest.json`,
+ * resolving every relative entry against that directory to an absolute
+ * filesystem path. Takes the pack directory directly (the `from-pack-v2`
+ * pointer's `packUrl`) — the structurer owns the layout, so this does not
+ * re-derive `<root>/block-pack`. Counterpart to `loadPackDescription`, which
+ * reads the authoring `block` field from `package.json` and resolves against
+ * source.
+ */
+export async function loadPackDescriptionFromManifest(
+  blockPackDir: string,
+): Promise<BlockPackDescriptionAbsolute> {
+  const manifestPath = path.resolve(blockPackDir, BlockPackManifestFile);
+  const raw = JSON.parse(await fsp.readFile(manifestPath, { encoding: "utf-8" })) as unknown;
+  const manifest = BlockPackManifest.parse(raw);
+  const components = resolveManifestBlockComponents(manifest.description.components, blockPackDir);
+  const meta = await resolveManifestBlockPackMeta(manifest.description.meta, blockPackDir);
+  return {
+    ...manifest.description,
+    components,
+    meta,
+  };
+}