@milaboratories/pl-middle-layer 1.66.19 → 1.67.0

package/dist/mutator/template_construct.cjs

@@ -0,0 +1,77 @@
+const require_template_apply = require("../model/template_apply.cjs");
+let _platforma_sdk_model = require("@platforma-sdk/model");
+let node_crypto = require("node:crypto");
+//#region src/mutator/template_construct.ts
+/**
+* Apply a `template-v1` document: create each entry's block, in file order.
+*
+* Everything slow is already done by the time this runs: kinds resolved, block packs
+* prepared and template-cached, the project created and a mutator open. What is left per
+* entry is in-memory work — assign an id, redirect the entry's references against the ids
+* already handed out, ask the block's own model for the storage those params imply, and
+* place the block. All of it inside the caller's single transaction.
+*
+* File order is instantiation order, and a reference to a later entry is rejected before
+* this point, so one forward pass is enough: by the time an entry is created, every entry it
+* references already exists and already has an id. Blocks are appended in the order they are
+* added, so nothing here passes a `before`.
+*
+* **All or nothing.** An entry this project cannot honour throws
+* {@link TemplateEntryRejected}, which leaves the caller's transaction uncommitted, so the
+* project keeps none of the blocks this call placed. A half-applied project is not a useful
+* result: its tail is missing, so whatever the missing entries were supposed to feed is wired
+* to nothing, and the user cannot tell which of the blocks present were configured by the
+* file and which they would have to fix. Failing whole also means the reader gets one
+* statement about their file rather than a project to reconcile.
+*
+* @param entries Prepared entries by template-local id. Resolution covers every entry
+*   or the apply does not start, so a missing one is a caller error rather than a
+*   property of the file
+* @param newBlockId Source of project-local block ids. Defaults to random UUIDs, the same
+*   ids `Project.addBlock` would have generated on its own; injectable so a test can name
+*   the ids it expects
+* @throws {TemplateEntryRejected} for the first entry the file describes unusably
+*/
+function applyTemplateEntries(deps) {
+	const { document, placer, projectHelper, entries } = deps;
+	const newBlockId = deps.newBlockId ?? node_crypto.randomUUID;
+	const added = [];
+	/**
+	* Template-local entry id → the block id it was given.
+	*
+	* An entry lands in here the moment it is given an id, before its block is placed. That is
+	* safe precisely because the apply is all-or-nothing: there is no surviving project in
+	* which a later entry could point at a block that never got created. It does mean an entry
+	* whose params reference itself is wired to itself rather than left dangling — a document
+	* the reference check rejects before an apply begins.
+	*/
+	const blockIds = /* @__PURE__ */ new Map();
+	for (const entry of document.blocks) {
+		const prepared = entries.get(entry.id);
+		if (prepared === void 0) throw new require_template_apply.TemplateEntryRejected(entry.id, `No block was prepared for entry '${entry.id}'.`);
+		const blockConfig = (0, _platforma_sdk_model.extractConfig)(prepared.blockPack.config);
+		if (blockConfig.modelAPIVersion !== _platforma_sdk_model.BLOCK_STORAGE_FACADE_VERSION) throw new require_template_apply.TemplateEntryRejected(entry.id, "This version of the block is too old to be created from a template. Use a newer version of the block, or remove the pinned block version from this entry so a supported one is chosen automatically.");
+		const blockId = newBlockId();
+		blockIds.set(entry.id, blockId);
+		const storage = projectHelper.getInitialStorageFromParamsInVM(blockConfig, entry.params, blockIds);
+		if (storage.error !== void 0) throw new require_template_apply.TemplateEntryRejected(entry.id, storage.error.message);
+		placer.addBlock({
+			id: blockId,
+			label: prepared.label,
+			renderingMode: blockConfig.renderingMode
+		}, {
+			storageMode: "fromModel",
+			blockPack: prepared.blockPack,
+			initialStorage: storage.value
+		});
+		added.push({
+			templateLocalId: entry.id,
+			blockId
+		});
+	}
+	return added;
+}
+//#endregion
+exports.applyTemplateEntries = applyTemplateEntries;
+
+//# sourceMappingURL=template_construct.cjs.map

package/dist/mutator/template_construct.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_construct.cjs","names":["randomUUID","TemplateEntryRejected","BLOCK_STORAGE_FACADE_VERSION"],"sources":["../../src/mutator/template_construct.ts"],"sourcesContent":["import { BLOCK_STORAGE_FACADE_VERSION, extractConfig } from \"@platforma-sdk/model\";\nimport type { ProjectTemplateV1 } from \"@milaboratories/pl-model-common\";\nimport type { BlockPackSpecPrepared } from \"../model\";\nimport type { ProjectHelper } from \"../model/project_helper\";\nimport type { AppliedEntry } from \"../model/template_apply\";\nimport { TemplateEntryRejected } from \"../model/template_apply\";\nimport { randomUUID } from \"node:crypto\";\nimport type { Block } from \"../model/project_model\";\nimport type { NewBlockSpec } from \"./project\";\n\n/** What construction needs to know about one entry, once its block has been located. */\nexport type PreparedTemplateEntry = {\n  /** The block pack, already prepared and template-cached. */\n  readonly blockPack: BlockPackSpecPrepared;\n  /**\n   * The label to place the block under: the block package's published title.\n   *\n   * A template names no block instances, so this cannot come from the file — and must\n   * not be derived from it, since an exported template names its entries by the source\n   * project's block ids. It reaches here from resolution, the only stage that talks to\n   * a registry.\n   *\n   * A block whose model derives a title shows that instead (`project_overview.ts`\n   * prefers the derived one), so for most blocks this is invisible. For the ones that\n   * derive none it is the name the user reads.\n   */\n  readonly label: string;\n};\n\n/** The one method construction needs from a project mutator. */\nexport type BlockPlacer = {\n  addBlock: (block: Block, spec: NewBlockSpec, before?: string) => void;\n};\n\n/**\n * Apply a `template-v1` document: create each entry's block, in file order.\n *\n * Everything slow is already done by the time this runs: kinds resolved, block packs\n * prepared and template-cached, the project created and a mutator open. What is left per\n * entry is in-memory work — assign an id, redirect the entry's references against the ids\n * already handed out, ask the block's own model for the storage those params imply, and\n * place the block. All of it inside the caller's single transaction.\n *\n * File order is instantiation order, and a reference to a later entry is rejected before\n * this point, so one forward pass is enough: by the time an entry is created, every entry it\n * references already exists and already has an id. Blocks are appended in the order they are\n * added, so nothing here passes a `before`.\n *\n * **All or nothing.** An entry this project cannot honour throws\n * {@link TemplateEntryRejected}, which leaves the caller's transaction uncommitted, so the\n * project keeps none of the blocks this call placed. A half-applied project is not a useful\n * result: its tail is missing, so whatever the missing entries were supposed to feed is wired\n * to nothing, and the user cannot tell which of the blocks present were configured by the\n * file and which they would have to fix. Failing whole also means the reader gets one\n * statement about their file rather than a project to reconcile.\n *\n * @param entries Prepared entries by template-local id. Resolution covers every entry\n *   or the apply does not start, so a missing one is a caller error rather than a\n *   property of the file\n * @param newBlockId Source of project-local block ids. Defaults to random UUIDs, the same\n *   ids `Project.addBlock` would have generated on its own; injectable so a test can name\n *   the ids it expects\n * @throws {TemplateEntryRejected} for the first entry the file describes unusably\n */\nexport function applyTemplateEntries(deps: {\n  readonly document: ProjectTemplateV1;\n  readonly placer: BlockPlacer;\n  readonly projectHelper: ProjectHelper;\n  readonly entries: ReadonlyMap<string, PreparedTemplateEntry>;\n  readonly newBlockId?: () => string;\n}): AppliedEntry[] {\n  const { document, placer, projectHelper, entries } = deps;\n  const newBlockId = deps.newBlockId ?? randomUUID;\n  const added: AppliedEntry[] = [];\n\n  /**\n   * Template-local entry id → the block id it was given.\n   *\n   * An entry lands in here the moment it is given an id, before its block is placed. That is\n   * safe precisely because the apply is all-or-nothing: there is no surviving project in\n   * which a later entry could point at a block that never got created. It does mean an entry\n   * whose params reference itself is wired to itself rather than left dangling — a document\n   * the reference check rejects before an apply begins.\n   */\n  const blockIds = new Map<string, string>();\n\n  for (const entry of document.blocks) {\n    const prepared = entries.get(entry.id);\n    if (prepared === undefined) {\n      throw new TemplateEntryRejected(entry.id, `No block was prepared for entry '${entry.id}'.`);\n    }\n\n    const blockConfig = extractConfig(prepared.blockPack.config);\n\n    // Only a block on the current storage facade can be told what to initialize itself\n    // with, and it is refused rather than created with its own defaults even when the\n    // entry carries no params: every entry names a kind, and a block predating the\n    // facade implements none, so creating one would honour the entry's pinned version\n    // while contradicting the kind it claims to be. With params it is worse still — a\n    // block that looks applied but ignored everything the template said about it.\n    //\n    // Kind resolution never picks such a block, since declaring a kind requires a\n    // recent SDK. An entry pinning an exact version can name anything ever published,\n    // which is the way this is reached.\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      throw new TemplateEntryRejected(\n        entry.id,\n        \"This version of the block is too old to be created from a template. Use a \" +\n          \"newer version of the block, or remove the pinned block version from this \" +\n          \"entry so a supported one is chosen automatically.\",\n      );\n    }\n\n    const blockId = newBlockId();\n    blockIds.set(entry.id, blockId);\n\n    // Params travelled from the file untouched, so pointing their references at this project\n    // is the block's own job, in its own bundle — nothing here knows which of the values in\n    // there carry block ids. It happens inside this same call, along with the kind's check and\n    // the block's own init: the block decides what its params mean, and this is the one place\n    // that asks it. The map holds the entries created so far, including this one, so an entry\n    // referencing itself is wired to itself and one referencing an entry below is left\n    // pointing at nothing.\n    //\n    // Params are a mapping by the time a document exists — the parser reads an omitted key\n    // as `{}` — so every entry goes through this path and is checked against its kind. Run\n    // before anything is placed, so params the block declines cost nothing but the report.\n    const storage = projectHelper.getInitialStorageFromParamsInVM(\n      blockConfig,\n      entry.params,\n      blockIds,\n    );\n    if (storage.error !== undefined) {\n      throw new TemplateEntryRejected(entry.id, storage.error.message);\n    }\n\n    placer.addBlock(\n      { id: blockId, label: prepared.label, renderingMode: blockConfig.renderingMode },\n      {\n        storageMode: \"fromModel\",\n        blockPack: prepared.blockPack,\n        initialStorage: storage.value,\n      },\n    );\n\n    added.push({ templateLocalId: entry.id, blockId });\n  }\n\n  return added;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,SAAgB,qBAAqB,MAMlB;CACjB,MAAM,EAAE,UAAU,QAAQ,eAAe,YAAY;CACrD,MAAM,aAAa,KAAK,cAAcA,YAAAA;CACtC,MAAM,QAAwB,CAAC;;;;;;;;;;CAW/B,MAAM,2BAAW,IAAI,IAAoB;CAEzC,KAAK,MAAM,SAAS,SAAS,QAAQ;EACnC,MAAM,WAAW,QAAQ,IAAI,MAAM,EAAE;EACrC,IAAI,aAAa,KAAA,GACf,MAAM,IAAIC,uBAAAA,sBAAsB,MAAM,IAAI,oCAAoC,MAAM,GAAG,GAAG;EAG5F,MAAM,eAAA,GAAA,qBAAA,cAAA,CAA4B,SAAS,UAAU,MAAM;EAY3D,IAAI,YAAY,oBAAoBC,qBAAAA,8BAClC,MAAM,IAAID,uBAAAA,sBACR,MAAM,IACN,sMAGF;EAGF,MAAM,UAAU,WAAW;EAC3B,SAAS,IAAI,MAAM,IAAI,OAAO;EAa9B,MAAM,UAAU,cAAc,gCAC5B,aACA,MAAM,QACN,QACF;EACA,IAAI,QAAQ,UAAU,KAAA,GACpB,MAAM,IAAIA,uBAAAA,sBAAsB,MAAM,IAAI,QAAQ,MAAM,OAAO;EAGjE,OAAO,SACL;GAAE,IAAI;GAAS,OAAO,SAAS;GAAO,eAAe,YAAY;EAAc,GAC/E;GACE,aAAa;GACb,WAAW,SAAS;GACpB,gBAAgB,QAAQ;EAC1B,CACF;EAEA,MAAM,KAAK;GAAE,iBAAiB,MAAM;GAAI;EAAQ,CAAC;CACnD;CAEA,OAAO;AACT"}

package/dist/mutator/template_construct.js

@@ -0,0 +1,77 @@
+import { TemplateEntryRejected } from "../model/template_apply.js";
+import { BLOCK_STORAGE_FACADE_VERSION, extractConfig } from "@platforma-sdk/model";
+import { randomUUID } from "node:crypto";
+//#region src/mutator/template_construct.ts
+/**
+* Apply a `template-v1` document: create each entry's block, in file order.
+*
+* Everything slow is already done by the time this runs: kinds resolved, block packs
+* prepared and template-cached, the project created and a mutator open. What is left per
+* entry is in-memory work — assign an id, redirect the entry's references against the ids
+* already handed out, ask the block's own model for the storage those params imply, and
+* place the block. All of it inside the caller's single transaction.
+*
+* File order is instantiation order, and a reference to a later entry is rejected before
+* this point, so one forward pass is enough: by the time an entry is created, every entry it
+* references already exists and already has an id. Blocks are appended in the order they are
+* added, so nothing here passes a `before`.
+*
+* **All or nothing.** An entry this project cannot honour throws
+* {@link TemplateEntryRejected}, which leaves the caller's transaction uncommitted, so the
+* project keeps none of the blocks this call placed. A half-applied project is not a useful
+* result: its tail is missing, so whatever the missing entries were supposed to feed is wired
+* to nothing, and the user cannot tell which of the blocks present were configured by the
+* file and which they would have to fix. Failing whole also means the reader gets one
+* statement about their file rather than a project to reconcile.
+*
+* @param entries Prepared entries by template-local id. Resolution covers every entry
+*   or the apply does not start, so a missing one is a caller error rather than a
+*   property of the file
+* @param newBlockId Source of project-local block ids. Defaults to random UUIDs, the same
+*   ids `Project.addBlock` would have generated on its own; injectable so a test can name
+*   the ids it expects
+* @throws {TemplateEntryRejected} for the first entry the file describes unusably
+*/
+function applyTemplateEntries(deps) {
+	const { document, placer, projectHelper, entries } = deps;
+	const newBlockId = deps.newBlockId ?? randomUUID;
+	const added = [];
+	/**
+	* Template-local entry id → the block id it was given.
+	*
+	* An entry lands in here the moment it is given an id, before its block is placed. That is
+	* safe precisely because the apply is all-or-nothing: there is no surviving project in
+	* which a later entry could point at a block that never got created. It does mean an entry
+	* whose params reference itself is wired to itself rather than left dangling — a document
+	* the reference check rejects before an apply begins.
+	*/
+	const blockIds = /* @__PURE__ */ new Map();
+	for (const entry of document.blocks) {
+		const prepared = entries.get(entry.id);
+		if (prepared === void 0) throw new TemplateEntryRejected(entry.id, `No block was prepared for entry '${entry.id}'.`);
+		const blockConfig = extractConfig(prepared.blockPack.config);
+		if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) throw new TemplateEntryRejected(entry.id, "This version of the block is too old to be created from a template. Use a newer version of the block, or remove the pinned block version from this entry so a supported one is chosen automatically.");
+		const blockId = newBlockId();
+		blockIds.set(entry.id, blockId);
+		const storage = projectHelper.getInitialStorageFromParamsInVM(blockConfig, entry.params, blockIds);
+		if (storage.error !== void 0) throw new TemplateEntryRejected(entry.id, storage.error.message);
+		placer.addBlock({
+			id: blockId,
+			label: prepared.label,
+			renderingMode: blockConfig.renderingMode
+		}, {
+			storageMode: "fromModel",
+			blockPack: prepared.blockPack,
+			initialStorage: storage.value
+		});
+		added.push({
+			templateLocalId: entry.id,
+			blockId
+		});
+	}
+	return added;
+}
+//#endregion
+export { applyTemplateEntries };
+
+//# sourceMappingURL=template_construct.js.map

package/dist/mutator/template_construct.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_construct.js","names":[],"sources":["../../src/mutator/template_construct.ts"],"sourcesContent":["import { BLOCK_STORAGE_FACADE_VERSION, extractConfig } from \"@platforma-sdk/model\";\nimport type { ProjectTemplateV1 } from \"@milaboratories/pl-model-common\";\nimport type { BlockPackSpecPrepared } from \"../model\";\nimport type { ProjectHelper } from \"../model/project_helper\";\nimport type { AppliedEntry } from \"../model/template_apply\";\nimport { TemplateEntryRejected } from \"../model/template_apply\";\nimport { randomUUID } from \"node:crypto\";\nimport type { Block } from \"../model/project_model\";\nimport type { NewBlockSpec } from \"./project\";\n\n/** What construction needs to know about one entry, once its block has been located. */\nexport type PreparedTemplateEntry = {\n  /** The block pack, already prepared and template-cached. */\n  readonly blockPack: BlockPackSpecPrepared;\n  /**\n   * The label to place the block under: the block package's published title.\n   *\n   * A template names no block instances, so this cannot come from the file — and must\n   * not be derived from it, since an exported template names its entries by the source\n   * project's block ids. It reaches here from resolution, the only stage that talks to\n   * a registry.\n   *\n   * A block whose model derives a title shows that instead (`project_overview.ts`\n   * prefers the derived one), so for most blocks this is invisible. For the ones that\n   * derive none it is the name the user reads.\n   */\n  readonly label: string;\n};\n\n/** The one method construction needs from a project mutator. */\nexport type BlockPlacer = {\n  addBlock: (block: Block, spec: NewBlockSpec, before?: string) => void;\n};\n\n/**\n * Apply a `template-v1` document: create each entry's block, in file order.\n *\n * Everything slow is already done by the time this runs: kinds resolved, block packs\n * prepared and template-cached, the project created and a mutator open. What is left per\n * entry is in-memory work — assign an id, redirect the entry's references against the ids\n * already handed out, ask the block's own model for the storage those params imply, and\n * place the block. All of it inside the caller's single transaction.\n *\n * File order is instantiation order, and a reference to a later entry is rejected before\n * this point, so one forward pass is enough: by the time an entry is created, every entry it\n * references already exists and already has an id. Blocks are appended in the order they are\n * added, so nothing here passes a `before`.\n *\n * **All or nothing.** An entry this project cannot honour throws\n * {@link TemplateEntryRejected}, which leaves the caller's transaction uncommitted, so the\n * project keeps none of the blocks this call placed. A half-applied project is not a useful\n * result: its tail is missing, so whatever the missing entries were supposed to feed is wired\n * to nothing, and the user cannot tell which of the blocks present were configured by the\n * file and which they would have to fix. Failing whole also means the reader gets one\n * statement about their file rather than a project to reconcile.\n *\n * @param entries Prepared entries by template-local id. Resolution covers every entry\n *   or the apply does not start, so a missing one is a caller error rather than a\n *   property of the file\n * @param newBlockId Source of project-local block ids. Defaults to random UUIDs, the same\n *   ids `Project.addBlock` would have generated on its own; injectable so a test can name\n *   the ids it expects\n * @throws {TemplateEntryRejected} for the first entry the file describes unusably\n */\nexport function applyTemplateEntries(deps: {\n  readonly document: ProjectTemplateV1;\n  readonly placer: BlockPlacer;\n  readonly projectHelper: ProjectHelper;\n  readonly entries: ReadonlyMap<string, PreparedTemplateEntry>;\n  readonly newBlockId?: () => string;\n}): AppliedEntry[] {\n  const { document, placer, projectHelper, entries } = deps;\n  const newBlockId = deps.newBlockId ?? randomUUID;\n  const added: AppliedEntry[] = [];\n\n  /**\n   * Template-local entry id → the block id it was given.\n   *\n   * An entry lands in here the moment it is given an id, before its block is placed. That is\n   * safe precisely because the apply is all-or-nothing: there is no surviving project in\n   * which a later entry could point at a block that never got created. It does mean an entry\n   * whose params reference itself is wired to itself rather than left dangling — a document\n   * the reference check rejects before an apply begins.\n   */\n  const blockIds = new Map<string, string>();\n\n  for (const entry of document.blocks) {\n    const prepared = entries.get(entry.id);\n    if (prepared === undefined) {\n      throw new TemplateEntryRejected(entry.id, `No block was prepared for entry '${entry.id}'.`);\n    }\n\n    const blockConfig = extractConfig(prepared.blockPack.config);\n\n    // Only a block on the current storage facade can be told what to initialize itself\n    // with, and it is refused rather than created with its own defaults even when the\n    // entry carries no params: every entry names a kind, and a block predating the\n    // facade implements none, so creating one would honour the entry's pinned version\n    // while contradicting the kind it claims to be. With params it is worse still — a\n    // block that looks applied but ignored everything the template said about it.\n    //\n    // Kind resolution never picks such a block, since declaring a kind requires a\n    // recent SDK. An entry pinning an exact version can name anything ever published,\n    // which is the way this is reached.\n    if (blockConfig.modelAPIVersion !== BLOCK_STORAGE_FACADE_VERSION) {\n      throw new TemplateEntryRejected(\n        entry.id,\n        \"This version of the block is too old to be created from a template. Use a \" +\n          \"newer version of the block, or remove the pinned block version from this \" +\n          \"entry so a supported one is chosen automatically.\",\n      );\n    }\n\n    const blockId = newBlockId();\n    blockIds.set(entry.id, blockId);\n\n    // Params travelled from the file untouched, so pointing their references at this project\n    // is the block's own job, in its own bundle — nothing here knows which of the values in\n    // there carry block ids. It happens inside this same call, along with the kind's check and\n    // the block's own init: the block decides what its params mean, and this is the one place\n    // that asks it. The map holds the entries created so far, including this one, so an entry\n    // referencing itself is wired to itself and one referencing an entry below is left\n    // pointing at nothing.\n    //\n    // Params are a mapping by the time a document exists — the parser reads an omitted key\n    // as `{}` — so every entry goes through this path and is checked against its kind. Run\n    // before anything is placed, so params the block declines cost nothing but the report.\n    const storage = projectHelper.getInitialStorageFromParamsInVM(\n      blockConfig,\n      entry.params,\n      blockIds,\n    );\n    if (storage.error !== undefined) {\n      throw new TemplateEntryRejected(entry.id, storage.error.message);\n    }\n\n    placer.addBlock(\n      { id: blockId, label: prepared.label, renderingMode: blockConfig.renderingMode },\n      {\n        storageMode: \"fromModel\",\n        blockPack: prepared.blockPack,\n        initialStorage: storage.value,\n      },\n    );\n\n    added.push({ templateLocalId: entry.id, blockId });\n  }\n\n  return added;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,SAAgB,qBAAqB,MAMlB;CACjB,MAAM,EAAE,UAAU,QAAQ,eAAe,YAAY;CACrD,MAAM,aAAa,KAAK,cAAc;CACtC,MAAM,QAAwB,CAAC;;;;;;;;;;CAW/B,MAAM,2BAAW,IAAI,IAAoB;CAEzC,KAAK,MAAM,SAAS,SAAS,QAAQ;EACnC,MAAM,WAAW,QAAQ,IAAI,MAAM,EAAE;EACrC,IAAI,aAAa,KAAA,GACf,MAAM,IAAI,sBAAsB,MAAM,IAAI,oCAAoC,MAAM,GAAG,GAAG;EAG5F,MAAM,cAAc,cAAc,SAAS,UAAU,MAAM;EAY3D,IAAI,YAAY,oBAAoB,8BAClC,MAAM,IAAI,sBACR,MAAM,IACN,sMAGF;EAGF,MAAM,UAAU,WAAW;EAC3B,SAAS,IAAI,MAAM,IAAI,OAAO;EAa9B,MAAM,UAAU,cAAc,gCAC5B,aACA,MAAM,QACN,QACF;EACA,IAAI,QAAQ,UAAU,KAAA,GACpB,MAAM,IAAI,sBAAsB,MAAM,IAAI,QAAQ,MAAM,OAAO;EAGjE,OAAO,SACL;GAAE,IAAI;GAAS,OAAO,SAAS;GAAO,eAAe,YAAY;EAAc,GAC/E;GACE,aAAa;GACb,WAAW,SAAS;GACpB,gBAAgB,QAAQ;EAC1B,CACF;EAEA,MAAM,KAAK;GAAE,iBAAiB,MAAM;GAAI;EAAQ,CAAC;CACnD;CAEA,OAAO;AACT"}

package/dist/network_check/template.js

@@ -2,7 +2,7 @@ import { createRenderTemplate } from "../mutator/template/render_template.js";
 import { loadTemplate, prepareTemplateSpec } from "../mutator/template/template_loading.js";
 import path from "node:path";
 import { notEmpty } from "@milaboratories/ts-helpers";
-import fs from "node:fs/promises";
+import fsp from "node:fs/promises";
 import { ContinuePolling, Pl, field, isNotNullSignedResourceId, isNullSignedResourceId, poll, toGlobalFieldId } from "@milaboratories/pl-client";
 import { randomBytes } from "node:crypto";
 import { Templates } from "@platforma-sdk/workflow-tengo";
@@ -249,14 +249,14 @@ async function* listFilesSequence(lsDriver, storage, parent, nLsRequests) {
 async function createBigTempFile() {
 	const filePath = path.join(os.tmpdir(), `check-network-big-temp-${Date.now()}.bin`);
 	const fileContent = randomBytes(20 * 1024 * 1024);
-	await fs.appendFile(filePath, fileContent);
+	await fsp.appendFile(filePath, fileContent);
 	return { filePath };
 }
 /** Creates a temporarly file we could use for uploading and downloading. */
 async function createTempFile() {
 	const filePath = path.join(os.tmpdir(), `check-network-temp-${Date.now()}.txt`);
 	const fileContent = "Hello, world! " + (/* @__PURE__ */ new Date()).toISOString();
-	await fs.writeFile(filePath, fileContent);
+	await fsp.writeFile(filePath, fileContent);
 	return {
 		filePath,
 		fileContent

package/dist/network_check/template.js.map

@@ -1 +1 @@
-{"version":3,"file":"template.js","names":["SdkTemplates"],"sources":["../../src/network_check/template.ts"],"sourcesContent":["import type { FieldId, FieldRef, PlClient, ResourceData } from \"@milaboratories/pl-client\";\nimport {\n  type PlTransaction,\n  ContinuePolling,\n  field,\n  isNotNullSignedResourceId,\n  isNullSignedResourceId,\n  Pl,\n  poll,\n  toGlobalFieldId,\n} from \"@milaboratories/pl-client\";\nimport { createRenderTemplate } from \"../mutator/template/render_template\";\nimport { Templates as SdkTemplates } from \"@platforma-sdk/workflow-tengo\";\nimport type { TemplateSpecAny } from \"../model/template_spec\";\nimport { loadTemplate, prepareTemplateSpec } from \"../mutator/template/template_loading\";\nimport type { ClientDownload, LsDriver } from \"@milaboratories/pl-drivers\";\nimport {\n  ImportFileHandleUploadData,\n  isSignMatch,\n  isUpload,\n  uploadBlob,\n  type ClientUpload,\n  type LsEntryWithFileStats,\n} from \"@milaboratories/pl-drivers\";\nimport type { Signer } from \"@milaboratories/ts-helpers\";\nimport { notEmpty, type MiLogger } from \"@milaboratories/ts-helpers\";\nimport type { ResourceInfo } from \"@milaboratories/pl-tree\";\nimport { text } from \"node:stream/consumers\";\nimport path from \"node:path\";\nimport fs from \"node:fs/promises\";\nimport os from \"node:os\";\nimport { randomBytes } from \"node:crypto\";\nimport type { StorageEntry } from \"@milaboratories/pl-model-common\";\n\nexport interface TemplateReport {\n  status: \"ok\" | \"warn\" | \"failed\";\n  message: string;\n}\n\n/** Uploads `hello-world` template and checks the output is correct. */\nexport async function uploadTemplate(\n  logger: MiLogger,\n  pl: PlClient,\n  name: string,\n): Promise<TemplateReport> {\n  try {\n    const gotGreeting = await runUploadTemplate(logger, pl, name);\n    if (gotGreeting !== `Hello, ${name}`) {\n      return {\n        status: \"failed\",\n        message: `Template uploading failed: expected: ${name}, got: ${gotGreeting}`,\n      };\n    }\n\n    return { status: \"ok\", message: `Template uploading succeeded: ${gotGreeting}` };\n  } catch (e: unknown) {\n    return { status: \"failed\", message: `Template uploading failed: error occurred: ${e}` };\n  }\n}\n\nexport async function runUploadTemplate(\n  logger: MiLogger,\n  pl: PlClient,\n  name: string,\n): Promise<string> {\n  const outputs = await runTemplate(\n    pl,\n    SdkTemplates[\"check_network.upload_template\"],\n    true,\n    (tx) => ({\n      name: tx.createValue(Pl.JsonObject, JSON.stringify(name)),\n    }),\n    [\"greeting\"],\n  );\n\n  try {\n    return JSON.parse(notEmpty((await getFieldValue(pl, outputs.greeting)).data?.toString()));\n  } finally {\n    if (outputs != undefined) {\n      await deleteFields(pl, Object.values(outputs));\n    }\n  }\n}\n\n/** Uploads a file to the backend and checks the output is a Blob resource. */\nexport async function uploadFile(\n  logger: MiLogger,\n  signer: Signer,\n  lsDriver: LsDriver,\n  uploadClient: ClientUpload,\n  pl: PlClient,\n  filePath: string,\n): Promise<TemplateReport> {\n  try {\n    const gotBlob = await runUploadFile(logger, signer, lsDriver, uploadClient, pl, filePath);\n\n    if (gotBlob.type.name !== \"Blob\") {\n      return { status: \"failed\", message: `File uploading failed: ${gotBlob.type.name}` };\n    }\n\n    return { status: \"ok\", message: `File uploading succeeded: ${gotBlob.type.name}` };\n  } catch (e: unknown) {\n    return { status: \"failed\", message: `File uploading failed: error occurred: ${e}` };\n  }\n}\n\nexport async function runUploadFile(\n  logger: MiLogger,\n  signer: Signer,\n  lsDriver: LsDriver,\n  uploadClient: ClientUpload,\n  pl: PlClient,\n  filePath: string,\n): Promise<ResourceInfo> {\n  const handle = await lsDriver.getLocalFileHandle(filePath);\n  const result = await runTemplate(\n    pl,\n    SdkTemplates[\"check_network.upload_blob\"],\n    true,\n    (tx) => ({\n      file: tx.createValue(Pl.JsonObject, JSON.stringify(handle)),\n    }),\n    [\"progress\", \"file\"],\n  );\n\n  try {\n    const progress = await getFieldValue(pl, result.progress);\n\n    if (isUpload(progress)) {\n      const uploadData = ImportFileHandleUploadData.parse(\n        JSON.parse(notEmpty(progress.data?.toString())),\n      );\n      const isUploadSignMatch = isSignMatch(signer, uploadData.localPath, uploadData.pathSignature);\n\n      if (isUploadSignMatch) {\n        await uploadBlob(logger, uploadClient, progress, uploadData, () => false, {\n          nPartsWithThisUploadSpeed: 10,\n          nPartsToIncreaseUpload: 10,\n          currentSpeed: 10,\n          maxSpeed: 10,\n        });\n      }\n    }\n\n    return await getFieldValue(pl, result.file);\n  } finally {\n    await deleteFields(pl, Object.values(result));\n  }\n}\n\n/** Uploads a file to the backend and then tries to download it back. */\nexport async function downloadFile(\n  logger: MiLogger,\n  pl: PlClient,\n  lsDriver: LsDriver,\n  uploadClient: ClientUpload,\n  downloadClient: ClientDownload,\n  filePath: string,\n  fileContent: string,\n): Promise<TemplateReport> {\n  try {\n    const gotFileContent = await runDownloadFile(\n      logger,\n      pl,\n      lsDriver,\n      uploadClient,\n      downloadClient,\n      filePath,\n    );\n\n    if (gotFileContent !== fileContent) {\n      return {\n        status: \"failed\",\n        message: `File downloading failed: expected: ${fileContent}, got: ${gotFileContent}`,\n      };\n    }\n    return { status: \"ok\", message: `File downloading succeeded: ${gotFileContent}` };\n  } catch (e: unknown) {\n    return { status: \"failed\", message: `File downloading failed: error occurred: ${e}` };\n  }\n}\n\nexport async function runDownloadFile(\n  logger: MiLogger,\n  pl: PlClient,\n  lsDriver: LsDriver,\n  uploadClient: ClientUpload,\n  downloadClient: ClientDownload,\n  filePath: string,\n) {\n  const handle = await lsDriver.getLocalFileHandle(filePath);\n\n  const outputs = await runTemplate(\n    pl,\n    SdkTemplates[\"check_network.download_blob\"],\n    true,\n    (tx) => ({ file: tx.createValue(Pl.JsonObject, JSON.stringify(handle)) }),\n    [\"progress\", \"file\"],\n  );\n\n  try {\n    const progress = await getFieldValue(pl, outputs.progress);\n\n    await uploadBlob(\n      logger,\n      uploadClient,\n      progress,\n      ImportFileHandleUploadData.parse(JSON.parse(notEmpty(progress.data?.toString()))),\n      () => false,\n      {\n        nPartsWithThisUploadSpeed: 1,\n        nPartsToIncreaseUpload: 1,\n        currentSpeed: 1,\n        maxSpeed: 1,\n      },\n    );\n\n    const fileInfo = await getFieldValue(pl, outputs.file);\n\n    return await downloadClient.withBlobContent(\n      fileInfo,\n      {},\n      {},\n      async (content) => await text(content),\n    );\n  } finally {\n    await deleteFields(pl, Object.values(outputs));\n  }\n}\n\n/** Runs Go's hello-world binary. */\nexport async function softwareCheck(pl: PlClient): Promise<TemplateReport> {\n  try {\n    const gotGreeting = await runSoftware(pl);\n\n    if (gotGreeting !== \"Hello from go binary\\n\") {\n      return { status: \"failed\", message: `Software check failed: got: ${gotGreeting}` };\n    }\n    return { status: \"ok\", message: `Software check succeeded: ${gotGreeting}` };\n  } catch (e: unknown) {\n    return { status: \"failed\", message: `Software check failed: error occurred: ${e}` };\n  }\n}\n\nexport async function runSoftware(pl: PlClient): Promise<string> {\n  const result = await runTemplate(\n    pl,\n    SdkTemplates[\"check_network.run_hello_world\"],\n    true,\n    (_: PlTransaction) => ({}),\n    [\"greeting\"],\n  );\n\n  try {\n    return notEmpty((await getFieldValue(pl, result.greeting)).data?.toString());\n  } finally {\n    await deleteFields(pl, Object.values(result));\n  }\n}\n\n/** Runs Python hello-world. */\nexport async function pythonSoftware(pl: PlClient, name: string): Promise<TemplateReport> {\n  try {\n    const gotGreeting = await runPythonSoftware(pl, name);\n\n    if (gotGreeting !== `Hello, ${name}!\\n`) {\n      return { status: \"failed\", message: `Python software check failed: got: ${gotGreeting}` };\n    }\n    return { status: \"ok\", message: `Python software check succeeded: ${gotGreeting}` };\n  } catch (e: unknown) {\n    return { status: \"failed\", message: `Python software check failed: error occurred: ${e}` };\n  }\n}\n\nexport async function runPythonSoftware(pl: PlClient, name: string): Promise<string> {\n  const result = await runTemplate(\n    pl,\n    SdkTemplates[\"check_network.run_hello_world_py\"],\n    true,\n    (tx) => ({ name: tx.createValue(Pl.JsonObject, JSON.stringify(name)) }),\n    [\"greeting\"],\n  );\n\n  try {\n    return notEmpty((await getFieldValue(pl, result.greeting)).data?.toString());\n  } finally {\n    await deleteFields(pl, Object.values(result));\n  }\n}\n\n/** Tries to download a file from every storage. */\nexport async function downloadFromEveryStorage(\n  logger: MiLogger,\n  pl: PlClient,\n  lsDriver: LsDriver,\n  ops: {\n    minLsRequests: number;\n    bytesLimit: number;\n    minFileSize: number;\n    maxFileSize: number;\n    nFilesToCheck: number;\n  },\n): Promise<Record<string, TemplateReport>> {\n  try {\n    const storages = await lsDriver.getStorageList();\n    const results: Record<string, TemplateReport> = {};\n\n    for (const storage of storages) {\n      const result = await chooseFile(\n        lsDriver,\n        storage,\n        ops.nFilesToCheck,\n        ops.minFileSize,\n        ops.maxFileSize,\n        ops.minLsRequests,\n      );\n      if (result.file === undefined) {\n        results[storage.id] = {\n          status: \"warn\",\n          message:\n            `No file between ${ops.minFileSize} and ${ops.maxFileSize} bytes ` +\n            `found in storage ${storage.name}, checked ${result.nCheckedFiles} files, ` +\n            `did ${result.nLsRequests} ls requests`,\n        };\n        continue;\n      }\n\n      logger.info(`Downloading file ${JSON.stringify(result)} from storage ${storage.name}`);\n      const outputs = await runTemplate(\n        pl,\n        SdkTemplates[\"check_network.create_workdir_from_storage\"],\n        true,\n        (tx) => ({\n          file: tx.createValue(\n            Pl.JsonObject,\n            JSON.stringify((result.file as { handle: string }).handle),\n          ),\n        }),\n        [\"workdirTypeName\"],\n      );\n\n      try {\n        const workdirTypeName = JSON.parse(\n          Buffer.from((await getFieldValue(pl, outputs.workdirTypeName)).data!).toString(),\n        ) as string;\n\n        if (workdirTypeName?.startsWith(\"WorkingDirectory\")) {\n          results[storage.id] = {\n            status: \"ok\",\n            message:\n              `Workdir creation succeeded, size of file: ${result.file?.size}, ` +\n              `checked ${result.nCheckedFiles} files, did ${result.nLsRequests} ls requests`,\n          };\n        } else {\n          results[storage.id] = {\n            status: \"failed\",\n            message:\n              `Workdir creation failed: ${workdirTypeName}, size of file: ${result.file?.size}, ` +\n              `checked ${result.nCheckedFiles} files, did ${result.nLsRequests} ls requests`,\n          };\n        }\n      } finally {\n        await deleteFields(pl, Object.values(outputs));\n      }\n    }\n\n    return results;\n  } catch (e: unknown) {\n    return {\n      unknown: {\n        status: \"failed\",\n        message: `Download from every storage failed: error occurred: ${e}`,\n      },\n    };\n  }\n}\n\n/** Chooses a random file from the storage in a size range.\n * If we couldn't find a normal-sized file, we'll return a small file to check at least something.\n */\nexport async function chooseFile(\n  lsDriver: LsDriver,\n  storage: StorageEntry,\n  limit: number,\n  minSize: number,\n  maxSize: number,\n  minLsRequests: number,\n): Promise<{\n  file: LsEntryWithFileStats | undefined;\n  nLsRequests: number;\n  nCheckedFiles: number;\n}> {\n  const files = listFilesSequence(lsDriver, storage, \"\", 0);\n\n  // return small file in case we don't have many normal-sized files.\n  // While we'll download only a small range of bytes from the file,\n  // we don't want to return a big file in case the underlying S3 doesn't support range requests.\n  let smallFile: LsEntryWithFileStats | undefined;\n  let nCheckedFiles = 0;\n  let maxNLsRequests = 0;\n\n  for await (const { file, nLsRequests } of files) {\n    maxNLsRequests = Math.max(maxNLsRequests, nLsRequests);\n\n    if (nCheckedFiles >= limit && maxNLsRequests > minLsRequests) {\n      // we reached a limit on both the number of files and the number of ls requests.\n      return { file: smallFile, nLsRequests: maxNLsRequests, nCheckedFiles };\n    }\n    nCheckedFiles++;\n    if (minSize <= file.size && file.size <= maxSize) {\n      return { file, nLsRequests: maxNLsRequests, nCheckedFiles };\n    } else if (file.size < minSize) {\n      smallFile = file;\n    }\n  }\n\n  return { file: smallFile, nLsRequests: maxNLsRequests, nCheckedFiles };\n}\n\n/** Deep-first search for files in the storage. */\nexport async function* listFilesSequence(\n  lsDriver: LsDriver,\n  storage: StorageEntry,\n  parent: string,\n  nLsRequests: number,\n): AsyncGenerator<{ file: LsEntryWithFileStats; nLsRequests: number }, void, unknown> {\n  nLsRequests++;\n  const files = await lsDriver.listRemoteFilesWithFileStats(storage.handle, parent);\n\n  for (const file of files.entries) {\n    if (file.type === \"file\" && file.fullPath.startsWith(parent)) {\n      yield {\n        file,\n        nLsRequests,\n      };\n    } else if (file.type === \"dir\") {\n      for await (const nestedFile of listFilesSequence(\n        lsDriver,\n        storage,\n        file.fullPath,\n        nLsRequests,\n      )) {\n        nLsRequests = Math.max(nestedFile.nLsRequests, nLsRequests);\n        yield nestedFile;\n      }\n    }\n  }\n}\n\n/** Creates a big temporary file with random content. */\nexport async function createBigTempFile(): Promise<{ filePath: string }> {\n  const filePath = path.join(os.tmpdir(), `check-network-big-temp-${Date.now()}.bin`);\n  const fileSize = 20 * 1024 * 1024; // 20 MiB\n\n  const fileContent = randomBytes(fileSize);\n\n  await fs.appendFile(filePath, fileContent);\n\n  return { filePath };\n}\n\n/** Creates a temporarly file we could use for uploading and downloading. */\nexport async function createTempFile(): Promise<{ filePath: string; fileContent: string }> {\n  const filePath = path.join(os.tmpdir(), `check-network-temp-${Date.now()}.txt`);\n\n  const fileContent = \"Hello, world! \" + new Date().toISOString();\n  await fs.writeFile(filePath, fileContent);\n\n  return { filePath, fileContent };\n}\n\n/** Creates a template and RenderTemplate resources, gets all resources from outputs.\n * Throws a error if any of the outputs failed.\n */\nasync function runTemplate(\n  client: PlClient,\n  tpl: TemplateSpecAny,\n  ephemeral: boolean,\n  inputs: (tx: PlTransaction) => Pl.PlRecord,\n  outputs: string[],\n): Promise<Record<string, FieldId>> {\n  return await client.withWriteTx(\"TemplateRender\", async (tx) => {\n    const preparedTemplate = await prepareTemplateSpec(tpl);\n    const tplResource = loadTemplate(tx, preparedTemplate);\n\n    const outputFields: Record<string, FieldRef> = createRenderTemplate(\n      tx,\n      tplResource,\n      ephemeral,\n      inputs(tx),\n      outputs,\n    );\n\n    const outputsIds: Record<string, FieldId> = {};\n\n    for (const output of outputs) {\n      const fieldRef = field(client.clientRoot, output) as FieldId;\n      tx.createField(fieldRef, \"Dynamic\", outputFields[output]);\n      outputsIds[output] = await toGlobalFieldId(fieldRef);\n    }\n\n    await tx.commit();\n\n    return outputsIds;\n  });\n}\n\n/** Gets a resource from field's value or throws a error. */\nasync function getFieldValue(client: PlClient, fieldId: FieldId): Promise<ResourceData> {\n  // We could also do polling with pl-tree, but it seemed like an overkill,\n  // that's why we have a simple polling here.\n\n  return await poll(client, async (tx) => {\n    const field = await tx.tx.getField(fieldId);\n    if (isNotNullSignedResourceId(field.error)) {\n      const err = await tx.tx.getResourceData(field.error, true);\n      throw new Error(`getFieldValue of \"${fieldId.fieldName}\" field failed: ${err.data}`);\n    }\n\n    if (isNullSignedResourceId(field.value)) {\n      throw new ContinuePolling();\n    }\n\n    return await tx.tx.getResourceData(field.value, true);\n  });\n}\n\nasync function deleteFields(client: PlClient, fieldIds: FieldId[]) {\n  await client.withWriteTx(\"DeleteFields\", async (tx) => {\n    for (const fieldId of fieldIds) {\n      tx.resetField(fieldId);\n    }\n    await tx.commit();\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"template.js","names":["SdkTemplates","fs"],"sources":["../../src/network_check/template.ts"],"sourcesContent":["import type { FieldId, FieldRef, PlClient, ResourceData } from \"@milaboratories/pl-client\";\nimport {\n  type PlTransaction,\n  ContinuePolling,\n  field,\n  isNotNullSignedResourceId,\n  isNullSignedResourceId,\n  Pl,\n  poll,\n  toGlobalFieldId,\n} from \"@milaboratories/pl-client\";\nimport { createRenderTemplate } from \"../mutator/template/render_template\";\nimport { Templates as SdkTemplates } from \"@platforma-sdk/workflow-tengo\";\nimport type { TemplateSpecAny } from \"../model/template_spec\";\nimport { loadTemplate, prepareTemplateSpec } from \"../mutator/template/template_loading\";\nimport type { ClientDownload, LsDriver } from \"@milaboratories/pl-drivers\";\nimport {\n  ImportFileHandleUploadData,\n  isSignMatch,\n  isUpload,\n  uploadBlob,\n  type ClientUpload,\n  type LsEntryWithFileStats,\n} from \"@milaboratories/pl-drivers\";\nimport type { Signer } from \"@milaboratories/ts-helpers\";\nimport { notEmpty, type MiLogger } from \"@milaboratories/ts-helpers\";\nimport type { ResourceInfo } from \"@milaboratories/pl-tree\";\nimport { text } from \"node:stream/consumers\";\nimport path from \"node:path\";\nimport fs from \"node:fs/promises\";\nimport os from \"node:os\";\nimport { randomBytes } from \"node:crypto\";\nimport type { StorageEntry } from \"@milaboratories/pl-model-common\";\n\nexport interface TemplateReport {\n  status: \"ok\" | \"warn\" | \"failed\";\n  message: string;\n}\n\n/** Uploads `hello-world` template and checks the output is correct. */\nexport async function uploadTemplate(\n  logger: MiLogger,\n  pl: PlClient,\n  name: string,\n): Promise<TemplateReport> {\n  try {\n    const gotGreeting = await runUploadTemplate(logger, pl, name);\n    if (gotGreeting !== `Hello, ${name}`) {\n      return {\n        status: \"failed\",\n        message: `Template uploading failed: expected: ${name}, got: ${gotGreeting}`,\n      };\n    }\n\n    return { status: \"ok\", message: `Template uploading succeeded: ${gotGreeting}` };\n  } catch (e: unknown) {\n    return { status: \"failed\", message: `Template uploading failed: error occurred: ${e}` };\n  }\n}\n\nexport async function runUploadTemplate(\n  logger: MiLogger,\n  pl: PlClient,\n  name: string,\n): Promise<string> {\n  const outputs = await runTemplate(\n    pl,\n    SdkTemplates[\"check_network.upload_template\"],\n    true,\n    (tx) => ({\n      name: tx.createValue(Pl.JsonObject, JSON.stringify(name)),\n    }),\n    [\"greeting\"],\n  );\n\n  try {\n    return JSON.parse(notEmpty((await getFieldValue(pl, outputs.greeting)).data?.toString()));\n  } finally {\n    if (outputs != undefined) {\n      await deleteFields(pl, Object.values(outputs));\n    }\n  }\n}\n\n/** Uploads a file to the backend and checks the output is a Blob resource. */\nexport async function uploadFile(\n  logger: MiLogger,\n  signer: Signer,\n  lsDriver: LsDriver,\n  uploadClient: ClientUpload,\n  pl: PlClient,\n  filePath: string,\n): Promise<TemplateReport> {\n  try {\n    const gotBlob = await runUploadFile(logger, signer, lsDriver, uploadClient, pl, filePath);\n\n    if (gotBlob.type.name !== \"Blob\") {\n      return { status: \"failed\", message: `File uploading failed: ${gotBlob.type.name}` };\n    }\n\n    return { status: \"ok\", message: `File uploading succeeded: ${gotBlob.type.name}` };\n  } catch (e: unknown) {\n    return { status: \"failed\", message: `File uploading failed: error occurred: ${e}` };\n  }\n}\n\nexport async function runUploadFile(\n  logger: MiLogger,\n  signer: Signer,\n  lsDriver: LsDriver,\n  uploadClient: ClientUpload,\n  pl: PlClient,\n  filePath: string,\n): Promise<ResourceInfo> {\n  const handle = await lsDriver.getLocalFileHandle(filePath);\n  const result = await runTemplate(\n    pl,\n    SdkTemplates[\"check_network.upload_blob\"],\n    true,\n    (tx) => ({\n      file: tx.createValue(Pl.JsonObject, JSON.stringify(handle)),\n    }),\n    [\"progress\", \"file\"],\n  );\n\n  try {\n    const progress = await getFieldValue(pl, result.progress);\n\n    if (isUpload(progress)) {\n      const uploadData = ImportFileHandleUploadData.parse(\n        JSON.parse(notEmpty(progress.data?.toString())),\n      );\n      const isUploadSignMatch = isSignMatch(signer, uploadData.localPath, uploadData.pathSignature);\n\n      if (isUploadSignMatch) {\n        await uploadBlob(logger, uploadClient, progress, uploadData, () => false, {\n          nPartsWithThisUploadSpeed: 10,\n          nPartsToIncreaseUpload: 10,\n          currentSpeed: 10,\n          maxSpeed: 10,\n        });\n      }\n    }\n\n    return await getFieldValue(pl, result.file);\n  } finally {\n    await deleteFields(pl, Object.values(result));\n  }\n}\n\n/** Uploads a file to the backend and then tries to download it back. */\nexport async function downloadFile(\n  logger: MiLogger,\n  pl: PlClient,\n  lsDriver: LsDriver,\n  uploadClient: ClientUpload,\n  downloadClient: ClientDownload,\n  filePath: string,\n  fileContent: string,\n): Promise<TemplateReport> {\n  try {\n    const gotFileContent = await runDownloadFile(\n      logger,\n      pl,\n      lsDriver,\n      uploadClient,\n      downloadClient,\n      filePath,\n    );\n\n    if (gotFileContent !== fileContent) {\n      return {\n        status: \"failed\",\n        message: `File downloading failed: expected: ${fileContent}, got: ${gotFileContent}`,\n      };\n    }\n    return { status: \"ok\", message: `File downloading succeeded: ${gotFileContent}` };\n  } catch (e: unknown) {\n    return { status: \"failed\", message: `File downloading failed: error occurred: ${e}` };\n  }\n}\n\nexport async function runDownloadFile(\n  logger: MiLogger,\n  pl: PlClient,\n  lsDriver: LsDriver,\n  uploadClient: ClientUpload,\n  downloadClient: ClientDownload,\n  filePath: string,\n) {\n  const handle = await lsDriver.getLocalFileHandle(filePath);\n\n  const outputs = await runTemplate(\n    pl,\n    SdkTemplates[\"check_network.download_blob\"],\n    true,\n    (tx) => ({ file: tx.createValue(Pl.JsonObject, JSON.stringify(handle)) }),\n    [\"progress\", \"file\"],\n  );\n\n  try {\n    const progress = await getFieldValue(pl, outputs.progress);\n\n    await uploadBlob(\n      logger,\n      uploadClient,\n      progress,\n      ImportFileHandleUploadData.parse(JSON.parse(notEmpty(progress.data?.toString()))),\n      () => false,\n      {\n        nPartsWithThisUploadSpeed: 1,\n        nPartsToIncreaseUpload: 1,\n        currentSpeed: 1,\n        maxSpeed: 1,\n      },\n    );\n\n    const fileInfo = await getFieldValue(pl, outputs.file);\n\n    return await downloadClient.withBlobContent(\n      fileInfo,\n      {},\n      {},\n      async (content) => await text(content),\n    );\n  } finally {\n    await deleteFields(pl, Object.values(outputs));\n  }\n}\n\n/** Runs Go's hello-world binary. */\nexport async function softwareCheck(pl: PlClient): Promise<TemplateReport> {\n  try {\n    const gotGreeting = await runSoftware(pl);\n\n    if (gotGreeting !== \"Hello from go binary\\n\") {\n      return { status: \"failed\", message: `Software check failed: got: ${gotGreeting}` };\n    }\n    return { status: \"ok\", message: `Software check succeeded: ${gotGreeting}` };\n  } catch (e: unknown) {\n    return { status: \"failed\", message: `Software check failed: error occurred: ${e}` };\n  }\n}\n\nexport async function runSoftware(pl: PlClient): Promise<string> {\n  const result = await runTemplate(\n    pl,\n    SdkTemplates[\"check_network.run_hello_world\"],\n    true,\n    (_: PlTransaction) => ({}),\n    [\"greeting\"],\n  );\n\n  try {\n    return notEmpty((await getFieldValue(pl, result.greeting)).data?.toString());\n  } finally {\n    await deleteFields(pl, Object.values(result));\n  }\n}\n\n/** Runs Python hello-world. */\nexport async function pythonSoftware(pl: PlClient, name: string): Promise<TemplateReport> {\n  try {\n    const gotGreeting = await runPythonSoftware(pl, name);\n\n    if (gotGreeting !== `Hello, ${name}!\\n`) {\n      return { status: \"failed\", message: `Python software check failed: got: ${gotGreeting}` };\n    }\n    return { status: \"ok\", message: `Python software check succeeded: ${gotGreeting}` };\n  } catch (e: unknown) {\n    return { status: \"failed\", message: `Python software check failed: error occurred: ${e}` };\n  }\n}\n\nexport async function runPythonSoftware(pl: PlClient, name: string): Promise<string> {\n  const result = await runTemplate(\n    pl,\n    SdkTemplates[\"check_network.run_hello_world_py\"],\n    true,\n    (tx) => ({ name: tx.createValue(Pl.JsonObject, JSON.stringify(name)) }),\n    [\"greeting\"],\n  );\n\n  try {\n    return notEmpty((await getFieldValue(pl, result.greeting)).data?.toString());\n  } finally {\n    await deleteFields(pl, Object.values(result));\n  }\n}\n\n/** Tries to download a file from every storage. */\nexport async function downloadFromEveryStorage(\n  logger: MiLogger,\n  pl: PlClient,\n  lsDriver: LsDriver,\n  ops: {\n    minLsRequests: number;\n    bytesLimit: number;\n    minFileSize: number;\n    maxFileSize: number;\n    nFilesToCheck: number;\n  },\n): Promise<Record<string, TemplateReport>> {\n  try {\n    const storages = await lsDriver.getStorageList();\n    const results: Record<string, TemplateReport> = {};\n\n    for (const storage of storages) {\n      const result = await chooseFile(\n        lsDriver,\n        storage,\n        ops.nFilesToCheck,\n        ops.minFileSize,\n        ops.maxFileSize,\n        ops.minLsRequests,\n      );\n      if (result.file === undefined) {\n        results[storage.id] = {\n          status: \"warn\",\n          message:\n            `No file between ${ops.minFileSize} and ${ops.maxFileSize} bytes ` +\n            `found in storage ${storage.name}, checked ${result.nCheckedFiles} files, ` +\n            `did ${result.nLsRequests} ls requests`,\n        };\n        continue;\n      }\n\n      logger.info(`Downloading file ${JSON.stringify(result)} from storage ${storage.name}`);\n      const outputs = await runTemplate(\n        pl,\n        SdkTemplates[\"check_network.create_workdir_from_storage\"],\n        true,\n        (tx) => ({\n          file: tx.createValue(\n            Pl.JsonObject,\n            JSON.stringify((result.file as { handle: string }).handle),\n          ),\n        }),\n        [\"workdirTypeName\"],\n      );\n\n      try {\n        const workdirTypeName = JSON.parse(\n          Buffer.from((await getFieldValue(pl, outputs.workdirTypeName)).data!).toString(),\n        ) as string;\n\n        if (workdirTypeName?.startsWith(\"WorkingDirectory\")) {\n          results[storage.id] = {\n            status: \"ok\",\n            message:\n              `Workdir creation succeeded, size of file: ${result.file?.size}, ` +\n              `checked ${result.nCheckedFiles} files, did ${result.nLsRequests} ls requests`,\n          };\n        } else {\n          results[storage.id] = {\n            status: \"failed\",\n            message:\n              `Workdir creation failed: ${workdirTypeName}, size of file: ${result.file?.size}, ` +\n              `checked ${result.nCheckedFiles} files, did ${result.nLsRequests} ls requests`,\n          };\n        }\n      } finally {\n        await deleteFields(pl, Object.values(outputs));\n      }\n    }\n\n    return results;\n  } catch (e: unknown) {\n    return {\n      unknown: {\n        status: \"failed\",\n        message: `Download from every storage failed: error occurred: ${e}`,\n      },\n    };\n  }\n}\n\n/** Chooses a random file from the storage in a size range.\n * If we couldn't find a normal-sized file, we'll return a small file to check at least something.\n */\nexport async function chooseFile(\n  lsDriver: LsDriver,\n  storage: StorageEntry,\n  limit: number,\n  minSize: number,\n  maxSize: number,\n  minLsRequests: number,\n): Promise<{\n  file: LsEntryWithFileStats | undefined;\n  nLsRequests: number;\n  nCheckedFiles: number;\n}> {\n  const files = listFilesSequence(lsDriver, storage, \"\", 0);\n\n  // return small file in case we don't have many normal-sized files.\n  // While we'll download only a small range of bytes from the file,\n  // we don't want to return a big file in case the underlying S3 doesn't support range requests.\n  let smallFile: LsEntryWithFileStats | undefined;\n  let nCheckedFiles = 0;\n  let maxNLsRequests = 0;\n\n  for await (const { file, nLsRequests } of files) {\n    maxNLsRequests = Math.max(maxNLsRequests, nLsRequests);\n\n    if (nCheckedFiles >= limit && maxNLsRequests > minLsRequests) {\n      // we reached a limit on both the number of files and the number of ls requests.\n      return { file: smallFile, nLsRequests: maxNLsRequests, nCheckedFiles };\n    }\n    nCheckedFiles++;\n    if (minSize <= file.size && file.size <= maxSize) {\n      return { file, nLsRequests: maxNLsRequests, nCheckedFiles };\n    } else if (file.size < minSize) {\n      smallFile = file;\n    }\n  }\n\n  return { file: smallFile, nLsRequests: maxNLsRequests, nCheckedFiles };\n}\n\n/** Deep-first search for files in the storage. */\nexport async function* listFilesSequence(\n  lsDriver: LsDriver,\n  storage: StorageEntry,\n  parent: string,\n  nLsRequests: number,\n): AsyncGenerator<{ file: LsEntryWithFileStats; nLsRequests: number }, void, unknown> {\n  nLsRequests++;\n  const files = await lsDriver.listRemoteFilesWithFileStats(storage.handle, parent);\n\n  for (const file of files.entries) {\n    if (file.type === \"file\" && file.fullPath.startsWith(parent)) {\n      yield {\n        file,\n        nLsRequests,\n      };\n    } else if (file.type === \"dir\") {\n      for await (const nestedFile of listFilesSequence(\n        lsDriver,\n        storage,\n        file.fullPath,\n        nLsRequests,\n      )) {\n        nLsRequests = Math.max(nestedFile.nLsRequests, nLsRequests);\n        yield nestedFile;\n      }\n    }\n  }\n}\n\n/** Creates a big temporary file with random content. */\nexport async function createBigTempFile(): Promise<{ filePath: string }> {\n  const filePath = path.join(os.tmpdir(), `check-network-big-temp-${Date.now()}.bin`);\n  const fileSize = 20 * 1024 * 1024; // 20 MiB\n\n  const fileContent = randomBytes(fileSize);\n\n  await fs.appendFile(filePath, fileContent);\n\n  return { filePath };\n}\n\n/** Creates a temporarly file we could use for uploading and downloading. */\nexport async function createTempFile(): Promise<{ filePath: string; fileContent: string }> {\n  const filePath = path.join(os.tmpdir(), `check-network-temp-${Date.now()}.txt`);\n\n  const fileContent = \"Hello, world! \" + new Date().toISOString();\n  await fs.writeFile(filePath, fileContent);\n\n  return { filePath, fileContent };\n}\n\n/** Creates a template and RenderTemplate resources, gets all resources from outputs.\n * Throws a error if any of the outputs failed.\n */\nasync function runTemplate(\n  client: PlClient,\n  tpl: TemplateSpecAny,\n  ephemeral: boolean,\n  inputs: (tx: PlTransaction) => Pl.PlRecord,\n  outputs: string[],\n): Promise<Record<string, FieldId>> {\n  return await client.withWriteTx(\"TemplateRender\", async (tx) => {\n    const preparedTemplate = await prepareTemplateSpec(tpl);\n    const tplResource = loadTemplate(tx, preparedTemplate);\n\n    const outputFields: Record<string, FieldRef> = createRenderTemplate(\n      tx,\n      tplResource,\n      ephemeral,\n      inputs(tx),\n      outputs,\n    );\n\n    const outputsIds: Record<string, FieldId> = {};\n\n    for (const output of outputs) {\n      const fieldRef = field(client.clientRoot, output) as FieldId;\n      tx.createField(fieldRef, \"Dynamic\", outputFields[output]);\n      outputsIds[output] = await toGlobalFieldId(fieldRef);\n    }\n\n    await tx.commit();\n\n    return outputsIds;\n  });\n}\n\n/** Gets a resource from field's value or throws a error. */\nasync function getFieldValue(client: PlClient, fieldId: FieldId): Promise<ResourceData> {\n  // We could also do polling with pl-tree, but it seemed like an overkill,\n  // that's why we have a simple polling here.\n\n  return await poll(client, async (tx) => {\n    const field = await tx.tx.getField(fieldId);\n    if (isNotNullSignedResourceId(field.error)) {\n      const err = await tx.tx.getResourceData(field.error, true);\n      throw new Error(`getFieldValue of \"${fieldId.fieldName}\" field failed: ${err.data}`);\n    }\n\n    if (isNullSignedResourceId(field.value)) {\n      throw new ContinuePolling();\n    }\n\n    return await tx.tx.getResourceData(field.value, true);\n  });\n}\n\nasync function deleteFields(client: PlClient, fieldIds: FieldId[]) {\n  await client.withWriteTx(\"DeleteFields\", async (tx) => {\n    for (const fieldId of fieldIds) {\n      tx.resetField(fieldId);\n    }\n    await tx.commit();\n  });\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-middle-layer",
-  "version": "1.66.19",
+  "version": "1.67.0",
   "description": "Pl Middle Layer",
   "keywords": [],
   "license": "UNLICENSED",
@@ -31,24 +31,24 @@
     "yaml": "^2.8.0",
     "zod": "~3.25.76",
     "@milaboratories/computable": "2.9.8",
-    "@milaboratories/columns-collection-driver": "0.2.3",
-    "@milaboratories/pf-driver": "1.9.0",
+    "@milaboratories/pf-driver": "1.9.1",
     "@milaboratories/helpers": "1.14.5",
-    "@milaboratories/pf-spec-driver": "1.5.0",
-    "@milaboratories/pl-client": "3.14.6",
-    "@milaboratories/pl-drivers": "1.16.15",
-    "@milaboratories/pl-deployments": "3.0.15",
-    "@milaboratories/pl-errors": "1.4.35",
-    "@milaboratories/pl-model-backend": "1.4.20",
+    "@milaboratories/pl-client": "3.14.7",
+    "@milaboratories/columns-collection-driver": "0.2.4",
+    "@milaboratories/pf-spec-driver": "1.5.1",
+    "@milaboratories/pl-drivers": "1.16.16",
+    "@milaboratories/pl-errors": "1.4.36",
+    "@milaboratories/pl-deployments": "3.0.16",
+    "@milaboratories/pl-model-backend": "1.4.21",
+    "@milaboratories/pl-model-middle-layer": "1.32.0",
     "@milaboratories/pl-http": "1.2.4",
-    "@milaboratories/pl-model-middle-layer": "1.31.0",
-    "@milaboratories/resolve-helper": "1.1.3",
-    "@milaboratories/pl-model-common": "1.47.3",
+    "@milaboratories/pl-tree": "1.13.7",
+    "@milaboratories/pl-model-common": "1.48.0",
     "@milaboratories/ts-helpers": "1.8.6",
-    "@milaboratories/pl-tree": "1.13.6",
-    "@platforma-sdk/block-tools": "2.13.0",
-    "@platforma-sdk/workflow-tengo": "6.8.2",
-    "@platforma-sdk/model": "1.81.1"
+    "@platforma-sdk/model": "1.82.0",
+    "@platforma-sdk/block-tools": "2.14.0",
+    "@milaboratories/resolve-helper": "1.1.3",
+    "@platforma-sdk/workflow-tengo": "6.8.2"
   },
   "devDependencies": {
     "@types/node": "~24.5.2",
@@ -57,8 +57,8 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.3",
     "@milaboratories/build-configs": "2.0.0",
-    "@milaboratories/ts-builder": "1.6.2",
-    "@milaboratories/ts-configs": "1.4.0"
+    "@milaboratories/ts-configs": "1.4.0",
+    "@milaboratories/ts-builder": "1.7.0"
   },
   "engines": {
     "node": ">=22.19.0"

package/src/block_registry/index.ts

@@ -1,3 +1,4 @@
 export * from "./registry";
 export * from "./registry-v2-provider";
 export * from "./well_known_registries";
+export * from "./template_provider";

package/src/block_registry/location_provider.test.ts

@@ -0,0 +1,236 @@
+import { beforeAll, describe, expect, test } from "vitest";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { BlockPackLocationReference } from "@milaboratories/pl-model-common";
+import { resolveBlockPackLocation } from "./location_provider";
+
+/**
+ * The filesystem side of template import, driven against real directories.
+ *
+ * Everything here is about what is actually on disk — which layout is present, which spec
+ * addresses it, whether a path with a space still resolves — so these tests build the layouts
+ * rather than mock the readers. What each failure *says* to the reader is the resolver's, and
+ * lives with it.
+ */
+
+const KIND = "@milaboratories/milaboratories.test-loc.kind@1.2.3";
+
+let root: string;
+
+beforeAll(async () => {
+  root = await fsp.mkdtemp(path.join(os.tmpdir(), "template-location-"));
+});
+
+const locate = (dir: string) =>
+  resolveBlockPackLocation(pathToFileURL(dir).href as BlockPackLocationReference);
+
+/**
+ * A built-but-never-packed block: the source `package.json` names the components, and
+ * the kind is only in the compiled model. The shape a developer's working tree is in.
+ */
+async function writeDevBlock(
+  dir: string,
+  options: { title?: string; kind?: string | null } = {},
+): Promise<string> {
+  const { title = "Located Block", kind = KIND } = options;
+  await fsp.mkdir(path.join(dir, "ui"), { recursive: true });
+  await fsp.writeFile(
+    path.join(dir, "package.json"),
+    JSON.stringify({
+      name: "@milaboratories/milaboratories.test-loc",
+      version: "1.0.0",
+      block: {
+        components: {
+          workflow: "./main.plj.gz",
+          model: "./model.json",
+          ui: "./ui",
+        },
+        meta: {
+          title,
+          description: "A block used to exercise location resolution",
+          organization: { name: "MiLaboratories Inc", url: "https://milaboratories.com/" },
+        },
+      },
+    }),
+  );
+  await fsp.writeFile(path.join(dir, "main.plj.gz"), "workflow-bytes");
+  await fsp.writeFile(path.join(dir, "ui", "index.html"), "<html></html>");
+  // A real config container, because loading a source description normalizes the model
+  // to read its feature flags and refuses anything it cannot recognize. The render
+  // envelope is left empty: the kind sits above it, and nothing on this path runs the
+  // block.
+  await fsp.writeFile(
+    path.join(dir, "model.json"),
+    JSON.stringify({ v3: {}, code: {}, ...(kind === null ? {} : { kind }) }),
+  );
+  return dir;
+}
+
+/** A packed block: one manifest naming everything, kind included. */
+async function writePackedBlock(
+  dir: string,
+  options: { title?: string; kind?: string | null } = {},
+): Promise<string> {
+  const { title = "Packed Block", kind = KIND } = options;
+  await fsp.mkdir(dir, { recursive: true });
+  await fsp.writeFile(
+    path.join(dir, "manifest.json"),
+    JSON.stringify({
+      schema: "v2",
+      description: {
+        id: { organization: "milaboratories", name: "test-loc", 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,
+          description: "A packed block used to exercise location resolution",
+          organization: { name: "MiLaboratories Inc", url: "https://milaboratories.com/" },
+        },
+        ...(kind === null ? {} : { kind }),
+      },
+      files: [],
+    }),
+  );
+  return dir;
+}
+
+describe("a block built from source", () => {
+  test("resolves to the dev spec pointing at that very folder", async () => {
+    const dir = await writeDevBlock(path.join(root, "dev-basic"));
+
+    const outcome = await locate(dir);
+
+    expect(outcome.ok).toBe(true);
+    if (!outcome.ok) return;
+    expect(outcome.spec).toEqual({ type: "dev-v2", folder: dir });
+    expect(outcome.title).toBe("Located Block");
+  });
+
+  test("a model declaring no kind still resolves", async () => {
+    // Whether the block is the one the entry meant is settled once it has been prepared,
+    // from the compiled model there. Here it is only a block that was found.
+    const dir = await writeDevBlock(path.join(root, "dev-no-kind"), { kind: null });
+
+    const outcome = await locate(dir);
+
+    expect(outcome.ok).toBe(true);
+  });
+});
+
+describe("a packed block", () => {
+  test("resolves to the pack spec addressing the folder the manifest was read from", async () => {
+    const dir = await writePackedBlock(path.join(root, "packed"));
+
+    const outcome = await locate(dir);
+
+    expect(outcome.ok).toBe(true);
+    if (!outcome.ok) return;
+    expect(outcome.spec).toEqual({ type: "from-pack-v2", packUrl: pathToFileURL(dir).href });
+    expect(outcome.title).toBe("Packed Block");
+  });
+
+  test("the manifest wins over a package.json beside it", async () => {
+    // A facade package that has been packed holds both shapes; the manifest is the
+    // built artifact, and it is what the preparer will read.
+    const dir = path.join(root, "both-shapes");
+    await writeDevBlock(dir);
+    await writePackedBlock(dir, { title: "Packed Block" });
+
+    const outcome = await locate(dir);
+
+    expect(outcome.ok && outcome.spec.type).toBe("from-pack-v2");
+    expect(outcome.ok && outcome.title).toBe("Packed Block");
+  });
+});
+
+describe("a folder that is not itself the block", () => {
+  test("the conventional 'block' subfolder is found", async () => {
+    // So a hand-written entry may name what a person calls the block. Export never
+    // writes this form: it emits the folder the loader accepts.
+    const parent = path.join(root, "parent-block");
+    await writeDevBlock(path.join(parent, "block"));
+
+    const outcome = await locate(parent);
+
+    expect(outcome.ok).toBe(true);
+    expect(outcome.ok && outcome.spec).toEqual({
+      type: "dev-v2",
+      folder: path.join(parent, "block"),
+    });
+  });
+
+  test("the 'meta' subfolder too", async () => {
+    const parent = path.join(root, "parent-meta");
+    await writeDevBlock(path.join(parent, "meta"));
+
+    const outcome = await locate(parent);
+
+    expect(outcome.ok && outcome.spec).toEqual({
+      type: "dev-v2",
+      folder: path.join(parent, "meta"),
+    });
+  });
+});
+
+describe("what cannot be read", () => {
+  test("a folder that does not exist is not-found", async () => {
+    const outcome = await locate(path.join(root, "nowhere-at-all"));
+
+    expect(outcome).toEqual({ ok: false, reason: "not-found" });
+  });
+
+  test("a folder that exists but holds nothing is not-a-block", async () => {
+    // The two are kept apart because they send the reader somewhere different: one is
+    // a template carried to another machine, the other is a path one level off.
+    const dir = path.join(root, "empty");
+    await fsp.mkdir(dir, { recursive: true });
+
+    const outcome = await locate(dir);
+
+    expect(outcome).toEqual({ ok: false, reason: "not-a-block" });
+  });
+
+  test("an ordinary npm package is not a block", async () => {
+    // A `package.json` with no block description must not reach the loader, which
+    // would throw rather than report.
+    const dir = path.join(root, "plain-package");
+    await fsp.mkdir(dir, { recursive: true });
+    await fsp.writeFile(
+      path.join(dir, "package.json"),
+      JSON.stringify({ name: "just-a-package", version: "1.0.0" }),
+    );
+
+    const outcome = await locate(dir);
+
+    expect(outcome).toEqual({ ok: false, reason: "not-a-block" });
+  });
+
+  test("a scheme with no reader here is reported as such, not as a missing block", async () => {
+    const outcome = await resolveBlockPackLocation(
+      "https://blocks.internal/enter-numbers" as BlockPackLocationReference,
+    );
+
+    expect(outcome).toEqual({ ok: false, reason: "unsupported-scheme" });
+  });
+});
+
+describe("paths that need decoding", () => {
+  test("a folder whose name contains a space resolves", async () => {
+    // The value is a URL, so the space arrives as `%20`; reading the URL's pathname
+    // directly instead of converting it would look correct and never find the folder.
+    const dir = await writeDevBlock(path.join(root, "my blocks", "spaced"));
+
+    const location = pathToFileURL(dir).href;
+    expect(location).toContain("%20");
+
+    const outcome = await resolveBlockPackLocation(location as BlockPackLocationReference);
+
+    expect(outcome.ok).toBe(true);
+    expect(outcome.ok && outcome.spec).toEqual({ type: "dev-v2", folder: dir });
+  });
+});