@milaboratories/pl-middle-layer 1.66.19 → 1.67.0

package/dist/model/template_export.js

@@ -0,0 +1,82 @@
+import { allBlocks } from "./project_model_util.js";
+//#region src/model/template_export.ts
+/**
+* Walk a project's blocks in dependency order, collecting each one's
+* template-descriptor output.
+*
+* **No topological sort is performed, because none is needed.** The project
+* structure is already stored in topological order, and that is enforced rather
+* than assumed: `productionGraph` traverses `allBlocks(structure)` and passes the
+* set of blocks seen *so far* as the allowed set to `inferAllReferencedBlocks`, so
+* a reference to a block that is not already above is recorded as a missing
+* reference instead of an upstream. A block can therefore only legally reference
+* blocks earlier in this sequence — which is exactly what a template file needs,
+* since its block order is the instantiation order and the engine creates blocks
+* upstream-first. Emitting entries in structure order satisfies that for free.
+*
+* Groups are flattened in order, so cross-group ordering is the structure's too.
+*
+* A structure that violates the ordering rule is reported as-is, not repaired:
+* reordering would change which references are legal in the first place.
+*
+* Params are written exactly as the block projected them. The walk parses nothing, rewrites
+* nothing and inspects nothing inside them, and neither does anything else between here and the
+* file — which values carry block ids is knowledge of the reference system, and a template
+* engine holds none of it. The block that receives these params on the way back in is what
+* recognizes them; a block that projects the wrong fields produces a template that does not
+* work, the same way one whose `templateParams` returns the wrong shape does.
+*
+* @param structure The project structure — the source of both membership and order
+* @param paramsProvider Yields a block's derived template params. Return
+*   `undefined` for a block whose state cannot be read at all; such a block is
+*   recorded as a problem rather than skipped, because a template that quietly
+*   omits a block does not describe the project it was exported from, and the
+*   surviving entries may still reference the omitted one.
+*/
+function walkProjectForTemplateExport(structure, paramsProvider) {
+	const entries = [];
+	const problems = [];
+	for (const { id } of allBlocks(structure)) {
+		const derived = paramsProvider(id);
+		if (derived === void 0) {
+			problems.push({
+				blockId: id,
+				error: "Block state is unavailable, so its template params could not be derived"
+			});
+			continue;
+		}
+		if (derived.error !== void 0) {
+			problems.push({
+				blockId: id,
+				error: derived.error
+			});
+			continue;
+		}
+		const params = derived.value;
+		if (typeof params !== "object" || params === null || Array.isArray(params)) {
+			problems.push({
+				blockId: id,
+				error: `templateParams() must return an object, got ${typeName(params)}`
+			});
+			continue;
+		}
+		entries.push({
+			blockId: id,
+			params
+		});
+	}
+	return {
+		entries,
+		problems
+	};
+}
+/** Name the offending value's type for an error message, without printing the value. */
+function typeName(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	return `a ${typeof value}`;
+}
+//#endregion
+export { walkProjectForTemplateExport };
+
+//# sourceMappingURL=template_export.js.map

package/dist/model/template_export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_export.js","names":[],"sources":["../../src/model/template_export.ts"],"sourcesContent":["import type { ProjectStructure } from \"./project_model\";\nimport { allBlocks } from \"./project_model_util\";\n\n/**\n * One block's template-descriptor output as the walk receives it.\n *\n * Deliberately the same shape the `__pl_initializationParams_derive` facade callback\n * returns, so a provider can hand the VM's result straight through without\n * reshaping it.\n */\nexport type TemplateParamsResult =\n  | { readonly error: string }\n  | { readonly error?: undefined; readonly value: unknown };\n\n/** One block's contribution to the template being exported. */\nexport type TemplateExportEntry = {\n  /**\n   * The block's project-local id, which is also its template-local id: a template\n   * has no id namespace of its own, so the id is reused verbatim and references\n   * already stored in params need no translation.\n   */\n  readonly blockId: string;\n  /**\n   * The block's params exactly as it projected them.\n   *\n   * Always a mapping: a block that declared no `templateParams`, or whose lambda returned\n   * something else, is reported as a problem rather than carried here — see the object check\n   * in the walk. So nothing downstream has an absent case to decide.\n   */\n  readonly params: Record<string, unknown>;\n};\n\n/** Why one block could not be exported. */\nexport type TemplateExportProblem = {\n  readonly blockId: string;\n  readonly error: string;\n};\n\n/**\n * Outcome of the walk: the blocks that can be written, and the ones that cannot.\n *\n * Both lists are returned rather than throwing on the first failure, so the\n * caller can report every offending block at once instead of making the user fix\n * them one export at a time. Whether a non-empty `problems` aborts the export is\n * the caller's policy, not the walk's — but note that emitting `entries` while\n * ignoring `problems` can produce a file whose surviving entries reference a\n * dropped block, which is an unusable template.\n */\nexport type TemplateExportWalk = {\n  readonly entries: readonly TemplateExportEntry[];\n  readonly problems: readonly TemplateExportProblem[];\n};\n\n/**\n * Walk a project's blocks in dependency order, collecting each one's\n * template-descriptor output.\n *\n * **No topological sort is performed, because none is needed.** The project\n * structure is already stored in topological order, and that is enforced rather\n * than assumed: `productionGraph` traverses `allBlocks(structure)` and passes the\n * set of blocks seen *so far* as the allowed set to `inferAllReferencedBlocks`, so\n * a reference to a block that is not already above is recorded as a missing\n * reference instead of an upstream. A block can therefore only legally reference\n * blocks earlier in this sequence — which is exactly what a template file needs,\n * since its block order is the instantiation order and the engine creates blocks\n * upstream-first. Emitting entries in structure order satisfies that for free.\n *\n * Groups are flattened in order, so cross-group ordering is the structure's too.\n *\n * A structure that violates the ordering rule is reported as-is, not repaired:\n * reordering would change which references are legal in the first place.\n *\n * Params are written exactly as the block projected them. The walk parses nothing, rewrites\n * nothing and inspects nothing inside them, and neither does anything else between here and the\n * file — which values carry block ids is knowledge of the reference system, and a template\n * engine holds none of it. The block that receives these params on the way back in is what\n * recognizes them; a block that projects the wrong fields produces a template that does not\n * work, the same way one whose `templateParams` returns the wrong shape does.\n *\n * @param structure The project structure — the source of both membership and order\n * @param paramsProvider Yields a block's derived template params. Return\n *   `undefined` for a block whose state cannot be read at all; such a block is\n *   recorded as a problem rather than skipped, because a template that quietly\n *   omits a block does not describe the project it was exported from, and the\n *   surviving entries may still reference the omitted one.\n */\nexport function walkProjectForTemplateExport(\n  structure: ProjectStructure,\n  paramsProvider: (blockId: string) => TemplateParamsResult | undefined,\n): TemplateExportWalk {\n  const entries: TemplateExportEntry[] = [];\n  const problems: TemplateExportProblem[] = [];\n\n  for (const { id } of allBlocks(structure)) {\n    const derived = paramsProvider(id);\n\n    if (derived === undefined) {\n      problems.push({\n        blockId: id,\n        error: \"Block state is unavailable, so its template params could not be derived\",\n      });\n      continue;\n    }\n\n    if (derived.error !== undefined) {\n      problems.push({ blockId: id, error: derived.error });\n      continue;\n    }\n\n    const params = derived.value;\n\n    // An entry's `params` must be a mapping. The lambda's declared return type is the\n    // block kind's params type, and the kind's parser checks values coming IN, but\n    // nothing checks what the lambda hands back on the way out — so a block whose\n    // params type is a primitive or a tuple compiles fine and would produce an\n    // unwritable entry. This is the only place that can catch it.\n    if (typeof params !== \"object\" || params === null || Array.isArray(params)) {\n      problems.push({\n        blockId: id,\n        error: `templateParams() must return an object, got ${typeName(params)}`,\n      });\n      continue;\n    }\n\n    entries.push({ blockId: id, params: params as Record<string, unknown> });\n  }\n\n  return { entries, problems };\n}\n\n/** Name the offending value's type for an error message, without printing the value. */\nfunction typeName(value: unknown): string {\n  if (value === null) return \"null\";\n  if (Array.isArray(value)) return \"an array\";\n  return `a ${typeof value}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsFA,SAAgB,6BACd,WACA,gBACoB;CACpB,MAAM,UAAiC,CAAC;CACxC,MAAM,WAAoC,CAAC;CAE3C,KAAK,MAAM,EAAE,QAAQ,UAAU,SAAS,GAAG;EACzC,MAAM,UAAU,eAAe,EAAE;EAEjC,IAAI,YAAY,KAAA,GAAW;GACzB,SAAS,KAAK;IACZ,SAAS;IACT,OAAO;GACT,CAAC;GACD;EACF;EAEA,IAAI,QAAQ,UAAU,KAAA,GAAW;GAC/B,SAAS,KAAK;IAAE,SAAS;IAAI,OAAO,QAAQ;GAAM,CAAC;GACnD;EACF;EAEA,MAAM,SAAS,QAAQ;EAOvB,IAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,MAAM,QAAQ,MAAM,GAAG;GAC1E,SAAS,KAAK;IACZ,SAAS;IACT,OAAO,+CAA+C,SAAS,MAAM;GACvE,CAAC;GACD;EACF;EAEA,QAAQ,KAAK;GAAE,SAAS;GAAY;EAAkC,CAAC;CACzE;CAEA,OAAO;EAAE;EAAS;CAAS;AAC7B;;AAGA,SAAS,SAAS,OAAwB;CACxC,IAAI,UAAU,MAAM,OAAO;CAC3B,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO;CACjC,OAAO,KAAK,OAAO;AACrB"}

package/dist/model/template_parser.cjs

@@ -0,0 +1,74 @@
+const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+let yaml = require("yaml");
+yaml = require_runtime.__toESM(yaml, 1);
+let _milaboratories_pl_model_common = require("@milaboratories/pl-model-common");
+//#region src/model/template_parser.ts
+/**
+* Read `template-v1` YAML text into a document.
+*
+* The text half of the import direction, mirroring `stringifyProjectTemplateV1` on the
+* export side — and, like it, living here rather than in `pl-model-common`, which ships
+* in every block-model and UI bundle and takes no `yaml` dependency. The document half
+* is `parseProjectTemplateV1`, shared with export so that what export writes is by
+* construction what import reads.
+*
+* JSON is accepted for free: every JSON document is also YAML.
+*
+* **Read as YAML 1.2**, while the emitter quotes as if for 1.1. That asymmetry is
+* deliberate on both ends: quoting against the stricter ruleset makes a file we write
+* mean the same thing to any reader, and reading with the looser one means a bare
+* `yes` or `1:30` in a hand-written file stays the string it looks like instead of
+* silently becoming `true` or `90`.
+*
+* Nothing here checks that references point anywhere or that a kind can be resolved —
+* those are later stages, and both need more than the file to answer.
+*/
+function parseProjectTemplateV1Yaml(text) {
+	let value;
+	try {
+		value = yaml.default.parse(text);
+	} catch (e) {
+		return {
+			ok: false,
+			error: `The file is not valid YAML: ${e instanceof Error ? e.message.split("\n")[0] : String(e)}`
+		};
+	}
+	if (value === null || value === void 0) return {
+		ok: false,
+		error: "The file is empty."
+	};
+	if (typeof value !== "object" || Array.isArray(value)) return {
+		ok: false,
+		error: "The file does not describe a template: expected a mapping with 'schema' and 'blocks' at the top level."
+	};
+	const marker = value.schema;
+	if (marker !== _milaboratories_pl_model_common.PROJECT_TEMPLATE_SCHEMA_V1) return {
+		ok: false,
+		error: marker === void 0 ? `This file has no 'schema' field, so it is not a ${_milaboratories_pl_model_common.PROJECT_TEMPLATE_SCHEMA_V1} template.` : `This file says it is '${String(marker)}', not ${_milaboratories_pl_model_common.PROJECT_TEMPLATE_SCHEMA_V1}.`
+	};
+	const outcome = (0, _milaboratories_pl_model_common.readProjectTemplateV1)(value);
+	return outcome.ok ? {
+		ok: true,
+		document: outcome.document
+	} : {
+		ok: false,
+		error: describeIssues(outcome.issues)
+	};
+}
+/**
+* Turn the reader's issues into something a person can act on, all of them at once.
+*
+* The per-issue line comes from `formatTemplateParseIssue`, shared with the error the reader
+* throws, so a problem reads the same whether it reached a person through this outcome or
+* through a log. What is added here is the headline, which is the one part that belongs to
+* this stage: it says the FILE is at fault, which a caller that has one can say and the
+* document reader cannot.
+*/
+function describeIssues(issues) {
+	const lines = issues.map((issue) => `- ${(0, _milaboratories_pl_model_common.formatTemplateParseIssue)(issue)}`);
+	return [lines.length === 1 ? "The template file has a problem:" : `The template file has ${lines.length} problems:`, ...lines].join("\n");
+}
+//#endregion
+exports.parseProjectTemplateV1Yaml = parseProjectTemplateV1Yaml;
+
+//# sourceMappingURL=template_parser.cjs.map

package/dist/model/template_parser.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_parser.cjs","names":["YAML","PROJECT_TEMPLATE_SCHEMA_V1"],"sources":["../../src/model/template_parser.ts"],"sourcesContent":["import YAML from \"yaml\";\nimport type { ProjectTemplateV1, TemplateParseIssue } from \"@milaboratories/pl-model-common\";\nimport {\n  PROJECT_TEMPLATE_SCHEMA_V1,\n  formatTemplateParseIssue,\n  readProjectTemplateV1,\n} from \"@milaboratories/pl-model-common\";\n\n/**\n * A template file read, or why it could not be.\n *\n * A single message rather than a list of per-entry problems: until the document\n * parses there are no entries to attach anything to, and a file that does not parse\n * has one problem — it is not a template. Per-entry reporting starts at the stage\n * after this one. The message may span several lines when the file has several\n * fixable issues, so that fixing it takes one pass.\n */\nexport type TemplateParseOutcome =\n  | { readonly ok: true; readonly document: ProjectTemplateV1 }\n  | { readonly ok: false; readonly error: string };\n\n/**\n * Read `template-v1` YAML text into a document.\n *\n * The text half of the import direction, mirroring `stringifyProjectTemplateV1` on the\n * export side — and, like it, living here rather than in `pl-model-common`, which ships\n * in every block-model and UI bundle and takes no `yaml` dependency. The document half\n * is `parseProjectTemplateV1`, shared with export so that what export writes is by\n * construction what import reads.\n *\n * JSON is accepted for free: every JSON document is also YAML.\n *\n * **Read as YAML 1.2**, while the emitter quotes as if for 1.1. That asymmetry is\n * deliberate on both ends: quoting against the stricter ruleset makes a file we write\n * mean the same thing to any reader, and reading with the looser one means a bare\n * `yes` or `1:30` in a hand-written file stays the string it looks like instead of\n * silently becoming `true` or `90`.\n *\n * Nothing here checks that references point anywhere or that a kind can be resolved —\n * those are later stages, and both need more than the file to answer.\n */\nexport function parseProjectTemplateV1Yaml(text: string): TemplateParseOutcome {\n  let value: unknown;\n  try {\n    value = YAML.parse(text);\n  } catch (e) {\n    // The library's message already carries \"at line L, column C\"; what follows it is\n    // a code frame of the offending lines, dropped here because whoever is fixing the\n    // file has it open and the position is what they need.\n    const first = e instanceof Error ? e.message.split(\"\\n\")[0] : String(e);\n    return { ok: false, error: `The file is not valid YAML: ${first}` };\n  }\n\n  // Empty input, blank lines and a file of nothing but comments all parse to null.\n  // Left to the schema, this reads as \"expected object, received null\", which says\n  // nothing about the actual mistake.\n  if (value === null || value === undefined) {\n    return { ok: false, error: \"The file is empty.\" };\n  }\n\n  if (typeof value !== \"object\" || Array.isArray(value)) {\n    return {\n      ok: false,\n      error:\n        \"The file does not describe a template: expected a mapping with 'schema' and \" +\n        \"'blocks' at the top level.\",\n    };\n  }\n\n  // Checked ahead of the document reader because it is the likeliest mistake by far — the\n  // wrong file was picked — and deserves a sentence about that rather than one about a field\n  // whose value is not what was expected.\n  const marker = (value as { schema?: unknown }).schema;\n  if (marker !== PROJECT_TEMPLATE_SCHEMA_V1) {\n    return {\n      ok: false,\n      error:\n        marker === undefined\n          ? `This file has no 'schema' field, so it is not a ${PROJECT_TEMPLATE_SCHEMA_V1} template.`\n          : `This file says it is '${String(marker)}', not ${PROJECT_TEMPLATE_SCHEMA_V1}.`,\n    };\n  }\n\n  const outcome = readProjectTemplateV1(value);\n  return outcome.ok\n    ? { ok: true, document: outcome.document }\n    : { ok: false, error: describeIssues(outcome.issues) };\n}\n\n/**\n * Turn the reader's issues into something a person can act on, all of them at once.\n *\n * The per-issue line comes from `formatTemplateParseIssue`, shared with the error the reader\n * throws, so a problem reads the same whether it reached a person through this outcome or\n * through a log. What is added here is the headline, which is the one part that belongs to\n * this stage: it says the FILE is at fault, which a caller that has one can say and the\n * document reader cannot.\n */\nfunction describeIssues(issues: readonly TemplateParseIssue[]): string {\n  const lines = issues.map((issue) => `- ${formatTemplateParseIssue(issue)}`);\n\n  const headline =\n    lines.length === 1\n      ? \"The template file has a problem:\"\n      : `The template file has ${lines.length} problems:`;\n\n  return [headline, ...lines].join(\"\\n\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,2BAA2B,MAAoC;CAC7E,IAAI;CACJ,IAAI;EACF,QAAQA,KAAAA,QAAK,MAAM,IAAI;CACzB,SAAS,GAAG;EAKV,OAAO;GAAE,IAAI;GAAO,OAAO,+BADb,aAAa,QAAQ,EAAE,QAAQ,MAAM,IAAI,CAAC,CAAC,KAAK,OAAO,CAAC;EACJ;CACpE;CAKA,IAAI,UAAU,QAAQ,UAAU,KAAA,GAC9B,OAAO;EAAE,IAAI;EAAO,OAAO;CAAqB;CAGlD,IAAI,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,GAClD,OAAO;EACL,IAAI;EACJ,OACE;CAEJ;CAMF,MAAM,SAAU,MAA+B;CAC/C,IAAI,WAAWC,gCAAAA,4BACb,OAAO;EACL,IAAI;EACJ,OACE,WAAW,KAAA,IACP,mDAAmDA,gCAAAA,2BAA2B,cAC9E,yBAAyB,OAAO,MAAM,EAAE,SAASA,gCAAAA,2BAA2B;CACpF;CAGF,MAAM,WAAA,GAAA,gCAAA,sBAAA,CAAgC,KAAK;CAC3C,OAAO,QAAQ,KACX;EAAE,IAAI;EAAM,UAAU,QAAQ;CAAS,IACvC;EAAE,IAAI;EAAO,OAAO,eAAe,QAAQ,MAAM;CAAE;AACzD;;;;;;;;;;AAWA,SAAS,eAAe,QAA+C;CACrE,MAAM,QAAQ,OAAO,KAAK,UAAU,MAAA,GAAA,gCAAA,yBAAA,CAA8B,KAAK,GAAG;CAO1E,OAAO,CAJL,MAAM,WAAW,IACb,qCACA,yBAAyB,MAAM,OAAO,aAE1B,GAAG,KAAK,CAAC,CAAC,KAAK,IAAI;AACvC"}

package/dist/model/template_parser.d.ts

@@ -0,0 +1,43 @@
+import { ProjectTemplateV1 } from "@milaboratories/pl-model-common";
+
+//#region src/model/template_parser.d.ts
+/**
+ * A template file read, or why it could not be.
+ *
+ * A single message rather than a list of per-entry problems: until the document
+ * parses there are no entries to attach anything to, and a file that does not parse
+ * has one problem — it is not a template. Per-entry reporting starts at the stage
+ * after this one. The message may span several lines when the file has several
+ * fixable issues, so that fixing it takes one pass.
+ */
+type TemplateParseOutcome = {
+  readonly ok: true;
+  readonly document: ProjectTemplateV1;
+} | {
+  readonly ok: false;
+  readonly error: string;
+};
+/**
+ * Read `template-v1` YAML text into a document.
+ *
+ * The text half of the import direction, mirroring `stringifyProjectTemplateV1` on the
+ * export side — and, like it, living here rather than in `pl-model-common`, which ships
+ * in every block-model and UI bundle and takes no `yaml` dependency. The document half
+ * is `parseProjectTemplateV1`, shared with export so that what export writes is by
+ * construction what import reads.
+ *
+ * JSON is accepted for free: every JSON document is also YAML.
+ *
+ * **Read as YAML 1.2**, while the emitter quotes as if for 1.1. That asymmetry is
+ * deliberate on both ends: quoting against the stricter ruleset makes a file we write
+ * mean the same thing to any reader, and reading with the looser one means a bare
+ * `yes` or `1:30` in a hand-written file stays the string it looks like instead of
+ * silently becoming `true` or `90`.
+ *
+ * Nothing here checks that references point anywhere or that a kind can be resolved —
+ * those are later stages, and both need more than the file to answer.
+ */
+declare function parseProjectTemplateV1Yaml(text: string): TemplateParseOutcome;
+//#endregion
+export { TemplateParseOutcome, parseProjectTemplateV1Yaml };
+//# sourceMappingURL=template_parser.d.ts.map

package/dist/model/template_parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_parser.d.ts","names":[],"sources":["../../src/model/template_parser.ts"],"mappings":";;;;;AAiBA;;;;;;;KAAY,oBAAA;EAAA,SACG,EAAA;EAAA,SAAmB,QAAA,EAAU,iBAAiB;AAAA;EAAA,SAC9C,EAAA;EAAA,SAAoB,KAAA;AAAA;;AAsB2C;;;;;;;;;;;;;;;;;;;iBAA9D,0BAAA,CAA2B,IAAA,WAAe,oBAAoB"}

package/dist/model/template_parser.js

@@ -0,0 +1,72 @@
+import YAML from "yaml";
+import { PROJECT_TEMPLATE_SCHEMA_V1, formatTemplateParseIssue, readProjectTemplateV1 } from "@milaboratories/pl-model-common";
+//#region src/model/template_parser.ts
+/**
+* Read `template-v1` YAML text into a document.
+*
+* The text half of the import direction, mirroring `stringifyProjectTemplateV1` on the
+* export side — and, like it, living here rather than in `pl-model-common`, which ships
+* in every block-model and UI bundle and takes no `yaml` dependency. The document half
+* is `parseProjectTemplateV1`, shared with export so that what export writes is by
+* construction what import reads.
+*
+* JSON is accepted for free: every JSON document is also YAML.
+*
+* **Read as YAML 1.2**, while the emitter quotes as if for 1.1. That asymmetry is
+* deliberate on both ends: quoting against the stricter ruleset makes a file we write
+* mean the same thing to any reader, and reading with the looser one means a bare
+* `yes` or `1:30` in a hand-written file stays the string it looks like instead of
+* silently becoming `true` or `90`.
+*
+* Nothing here checks that references point anywhere or that a kind can be resolved —
+* those are later stages, and both need more than the file to answer.
+*/
+function parseProjectTemplateV1Yaml(text) {
+	let value;
+	try {
+		value = YAML.parse(text);
+	} catch (e) {
+		return {
+			ok: false,
+			error: `The file is not valid YAML: ${e instanceof Error ? e.message.split("\n")[0] : String(e)}`
+		};
+	}
+	if (value === null || value === void 0) return {
+		ok: false,
+		error: "The file is empty."
+	};
+	if (typeof value !== "object" || Array.isArray(value)) return {
+		ok: false,
+		error: "The file does not describe a template: expected a mapping with 'schema' and 'blocks' at the top level."
+	};
+	const marker = value.schema;
+	if (marker !== PROJECT_TEMPLATE_SCHEMA_V1) return {
+		ok: false,
+		error: marker === void 0 ? `This file has no 'schema' field, so it is not a ${PROJECT_TEMPLATE_SCHEMA_V1} template.` : `This file says it is '${String(marker)}', not ${PROJECT_TEMPLATE_SCHEMA_V1}.`
+	};
+	const outcome = readProjectTemplateV1(value);
+	return outcome.ok ? {
+		ok: true,
+		document: outcome.document
+	} : {
+		ok: false,
+		error: describeIssues(outcome.issues)
+	};
+}
+/**
+* Turn the reader's issues into something a person can act on, all of them at once.
+*
+* The per-issue line comes from `formatTemplateParseIssue`, shared with the error the reader
+* throws, so a problem reads the same whether it reached a person through this outcome or
+* through a log. What is added here is the headline, which is the one part that belongs to
+* this stage: it says the FILE is at fault, which a caller that has one can say and the
+* document reader cannot.
+*/
+function describeIssues(issues) {
+	const lines = issues.map((issue) => `- ${formatTemplateParseIssue(issue)}`);
+	return [lines.length === 1 ? "The template file has a problem:" : `The template file has ${lines.length} problems:`, ...lines].join("\n");
+}
+//#endregion
+export { parseProjectTemplateV1Yaml };
+
+//# sourceMappingURL=template_parser.js.map

package/dist/model/template_parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_parser.js","names":[],"sources":["../../src/model/template_parser.ts"],"sourcesContent":["import YAML from \"yaml\";\nimport type { ProjectTemplateV1, TemplateParseIssue } from \"@milaboratories/pl-model-common\";\nimport {\n  PROJECT_TEMPLATE_SCHEMA_V1,\n  formatTemplateParseIssue,\n  readProjectTemplateV1,\n} from \"@milaboratories/pl-model-common\";\n\n/**\n * A template file read, or why it could not be.\n *\n * A single message rather than a list of per-entry problems: until the document\n * parses there are no entries to attach anything to, and a file that does not parse\n * has one problem — it is not a template. Per-entry reporting starts at the stage\n * after this one. The message may span several lines when the file has several\n * fixable issues, so that fixing it takes one pass.\n */\nexport type TemplateParseOutcome =\n  | { readonly ok: true; readonly document: ProjectTemplateV1 }\n  | { readonly ok: false; readonly error: string };\n\n/**\n * Read `template-v1` YAML text into a document.\n *\n * The text half of the import direction, mirroring `stringifyProjectTemplateV1` on the\n * export side — and, like it, living here rather than in `pl-model-common`, which ships\n * in every block-model and UI bundle and takes no `yaml` dependency. The document half\n * is `parseProjectTemplateV1`, shared with export so that what export writes is by\n * construction what import reads.\n *\n * JSON is accepted for free: every JSON document is also YAML.\n *\n * **Read as YAML 1.2**, while the emitter quotes as if for 1.1. That asymmetry is\n * deliberate on both ends: quoting against the stricter ruleset makes a file we write\n * mean the same thing to any reader, and reading with the looser one means a bare\n * `yes` or `1:30` in a hand-written file stays the string it looks like instead of\n * silently becoming `true` or `90`.\n *\n * Nothing here checks that references point anywhere or that a kind can be resolved —\n * those are later stages, and both need more than the file to answer.\n */\nexport function parseProjectTemplateV1Yaml(text: string): TemplateParseOutcome {\n  let value: unknown;\n  try {\n    value = YAML.parse(text);\n  } catch (e) {\n    // The library's message already carries \"at line L, column C\"; what follows it is\n    // a code frame of the offending lines, dropped here because whoever is fixing the\n    // file has it open and the position is what they need.\n    const first = e instanceof Error ? e.message.split(\"\\n\")[0] : String(e);\n    return { ok: false, error: `The file is not valid YAML: ${first}` };\n  }\n\n  // Empty input, blank lines and a file of nothing but comments all parse to null.\n  // Left to the schema, this reads as \"expected object, received null\", which says\n  // nothing about the actual mistake.\n  if (value === null || value === undefined) {\n    return { ok: false, error: \"The file is empty.\" };\n  }\n\n  if (typeof value !== \"object\" || Array.isArray(value)) {\n    return {\n      ok: false,\n      error:\n        \"The file does not describe a template: expected a mapping with 'schema' and \" +\n        \"'blocks' at the top level.\",\n    };\n  }\n\n  // Checked ahead of the document reader because it is the likeliest mistake by far — the\n  // wrong file was picked — and deserves a sentence about that rather than one about a field\n  // whose value is not what was expected.\n  const marker = (value as { schema?: unknown }).schema;\n  if (marker !== PROJECT_TEMPLATE_SCHEMA_V1) {\n    return {\n      ok: false,\n      error:\n        marker === undefined\n          ? `This file has no 'schema' field, so it is not a ${PROJECT_TEMPLATE_SCHEMA_V1} template.`\n          : `This file says it is '${String(marker)}', not ${PROJECT_TEMPLATE_SCHEMA_V1}.`,\n    };\n  }\n\n  const outcome = readProjectTemplateV1(value);\n  return outcome.ok\n    ? { ok: true, document: outcome.document }\n    : { ok: false, error: describeIssues(outcome.issues) };\n}\n\n/**\n * Turn the reader's issues into something a person can act on, all of them at once.\n *\n * The per-issue line comes from `formatTemplateParseIssue`, shared with the error the reader\n * throws, so a problem reads the same whether it reached a person through this outcome or\n * through a log. What is added here is the headline, which is the one part that belongs to\n * this stage: it says the FILE is at fault, which a caller that has one can say and the\n * document reader cannot.\n */\nfunction describeIssues(issues: readonly TemplateParseIssue[]): string {\n  const lines = issues.map((issue) => `- ${formatTemplateParseIssue(issue)}`);\n\n  const headline =\n    lines.length === 1\n      ? \"The template file has a problem:\"\n      : `The template file has ${lines.length} problems:`;\n\n  return [headline, ...lines].join(\"\\n\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,2BAA2B,MAAoC;CAC7E,IAAI;CACJ,IAAI;EACF,QAAQ,KAAK,MAAM,IAAI;CACzB,SAAS,GAAG;EAKV,OAAO;GAAE,IAAI;GAAO,OAAO,+BADb,aAAa,QAAQ,EAAE,QAAQ,MAAM,IAAI,CAAC,CAAC,KAAK,OAAO,CAAC;EACJ;CACpE;CAKA,IAAI,UAAU,QAAQ,UAAU,KAAA,GAC9B,OAAO;EAAE,IAAI;EAAO,OAAO;CAAqB;CAGlD,IAAI,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,GAClD,OAAO;EACL,IAAI;EACJ,OACE;CAEJ;CAMF,MAAM,SAAU,MAA+B;CAC/C,IAAI,WAAW,4BACb,OAAO;EACL,IAAI;EACJ,OACE,WAAW,KAAA,IACP,mDAAmD,2BAA2B,cAC9E,yBAAyB,OAAO,MAAM,EAAE,SAAS,2BAA2B;CACpF;CAGF,MAAM,UAAU,sBAAsB,KAAK;CAC3C,OAAO,QAAQ,KACX;EAAE,IAAI;EAAM,UAAU,QAAQ;CAAS,IACvC;EAAE,IAAI;EAAO,OAAO,eAAe,QAAQ,MAAM;CAAE;AACzD;;;;;;;;;;AAWA,SAAS,eAAe,QAA+C;CACrE,MAAM,QAAQ,OAAO,KAAK,UAAU,KAAK,yBAAyB,KAAK,GAAG;CAO1E,OAAO,CAJL,MAAM,WAAW,IACb,qCACA,yBAAyB,MAAM,OAAO,aAE1B,GAAG,KAAK,CAAC,CAAC,KAAK,IAAI;AACvC"}

package/dist/model/template_resolve.cjs

@@ -0,0 +1,134 @@
+let _milaboratories_pl_model_common = require("@milaboratories/pl-model-common");
+//#region src/model/template_resolve.ts
+/**
+* Resolve every entry in a template document to a concrete block pack.
+*
+* The first stage of an apply, and the only one that touches the network. It runs
+* before the project exists, which is what makes "no block for this entry" a message
+* about a file rather than a half-built project — and it is also why the whole
+* construction API downstream can be synchronous.
+*
+* Every entry is attempted, and every failure collected: an unapplicable file should
+* take one pass to fix, not one pass per bad entry. The one exception is that a
+* problem short-circuits nothing, so `resolved` may be shorter than the document.
+*
+* @param document A parsed template document
+* @param provider Where blocks come from
+* @param options `allowUnstable` applies to the whole document, not per entry
+*/
+async function resolveTemplateEntries(document, provider, options) {
+	const resolved = [];
+	const problems = [];
+	for (const entry of document.blocks) {
+		const outcome = await resolveEntry(entry, provider, options);
+		if (outcome.ok) resolved.push(outcome.entry);
+		else problems.push(outcome.problem);
+	}
+	return {
+		resolved,
+		problems
+	};
+}
+async function resolveEntry(entry, provider, options) {
+	const problem = (error) => ({
+		ok: false,
+		problem: {
+			entryId: entry.id,
+			error
+		}
+	});
+	if (entry.location !== void 0) {
+		const outcome = await provider.byLocation(entry.location);
+		if (!outcome.ok) switch (outcome.reason) {
+			case "unsupported-scheme": return problem(`This entry says its block is at '${entry.location}', which this application cannot read. Only a local path ('file:') is supported here.`);
+			case "not-found": return problem(`Nothing is at '${entry.location}', where this entry says its block is. A template that pins a folder only works on the machine that folder is on.`);
+			case "not-a-block": return problem(`'${entry.location}' is not a block: it holds neither a built block package nor a block's manifest. Point the entry at the folder holding the block's package.json.`);
+		}
+		return {
+			ok: true,
+			entry: {
+				entryId: entry.id,
+				spec: outcome.spec,
+				title: outcome.title,
+				pinned: true
+			}
+		};
+	}
+	if (entry.block !== void 0) {
+		let id;
+		try {
+			const { name, version } = (0, _milaboratories_pl_model_common.parseBlockPackReference)(entry.block);
+			id = {
+				...parseBlockPackName(name),
+				version
+			};
+		} catch (e) {
+			return problem(`Pinned block version is not readable: ${messageOf(e)}`);
+		}
+		const outcome = await provider.byExactVersion(id);
+		if (outcome.ok) return {
+			ok: true,
+			entry: {
+				entryId: entry.id,
+				spec: outcome.spec,
+				title: outcome.title,
+				pinned: true
+			}
+		};
+		return problem(`Block '${id.organization}/${id.name}' version ${id.version} was not found. Correct the pinned version in this entry, or remove it so a version is chosen automatically.`);
+	}
+	let kindName;
+	try {
+		kindName = (0, _milaboratories_pl_model_common.parseKindSelectorReference)(entry.kind).name;
+	} catch (e) {
+		return problem(`Block kind is not readable: ${messageOf(e)}`);
+	}
+	const outcome = await provider.byKind(entry.kind, options);
+	if (outcome.ok) return {
+		ok: true,
+		entry: {
+			entryId: entry.id,
+			spec: outcome.spec,
+			title: outcome.title,
+			pinned: false
+		}
+	};
+	switch (outcome.reason) {
+		case "no-matching-kind-version": return problem(`No published version of '${kindName}' matches what this entry asks for (${entry.kind}). Check the version, or update the block registry.`);
+		case "no-implementation": return problem(`'${kindName}' has no block implementing the version this entry asks for (${entry.kind}). Nothing can be installed for it yet.`);
+		case "no-stable-implementation": return problem(`The only blocks implementing '${kindName}' for this entry (${entry.kind}) are pre-release versions. Import again with unstable versions allowed to use them.`);
+	}
+}
+/**
+* Split a block package's npm name into the organization and name a registry knows
+* it by: `@npm-scope/organization.name` → `{ organization, name }`.
+*
+* The npm scope and the organization are different things, and only the second one
+* reaches the registry — `@milaboratories/milaboratories.test-download-file` is
+* published as organization `milaboratories`, name `test-download-file`. The split is
+* on the FIRST dot, so a name may contain further dots.
+*
+* Kind names follow the same convention, which is why a template can carry both in
+* the same npm-ish form.
+*
+* @throws if the name has no npm scope or no organization segment
+*/
+function parseBlockPackName(npmName) {
+	const slash = npmName.indexOf("/");
+	if (!npmName.startsWith("@") || slash < 0) throw new Error(`expected '@npm-scope/organization.name', got '${npmName}'`);
+	const base = npmName.slice(slash + 1);
+	const dot = base.indexOf(".");
+	if (dot <= 0 || dot === base.length - 1) throw new Error(`'${base}' does not separate an organization from a name with '.' in '${npmName}'`);
+	return {
+		organization: base.slice(0, dot),
+		name: base.slice(dot + 1)
+	};
+}
+function messageOf(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+//#endregion
+exports.parseBlockPackName = parseBlockPackName;
+exports.resolveTemplateEntries = resolveTemplateEntries;
+
+//# sourceMappingURL=template_resolve.cjs.map

package/dist/model/template_resolve.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_resolve.cjs","names":[],"sources":["../../src/model/template_resolve.ts"],"sourcesContent":["import type {\n  BlockKindSelectorReference,\n  BlockPackLocationReference,\n  ProjectTemplateV1,\n  ProjectTemplateV1Entry,\n} from \"@milaboratories/pl-model-common\";\nimport {\n  parseBlockPackReference,\n  parseKindSelectorReference,\n} from \"@milaboratories/pl-model-common\";\nimport type { BlockPackId, BlockPackSpec } from \"@milaboratories/pl-model-middle-layer\";\nimport type { TemplateApplyProblem } from \"./template_apply\";\n\n/**\n * Where a template entry's block comes from.\n *\n * All three of an entry's paths to an implementation go through this one interface, and\n * all three come back as the same `BlockPackSpec` — the shape the existing add-block\n * path already consumes — plus the block's published title. That convergence is the\n * point: everything downstream of resolution treats a kind-resolved entry, a\n * version-pinned one and a filesystem-located one identically, which is why a locally\n * built block travels the same preparation and construction path as a published one.\n *\n * Registry knowledge sits deliberately on the far side of this interface. A template\n * file names no registry, so choosing which one (or ones) to consult is a property\n * of the environment applying the file, not of the file — and keeping it out here is\n * what lets resolution be tested with no registry at all.\n *\n * The title is required rather than optional for the same reason: an implementation\n * always has one to hand — a registry adapter reads it off the block's manifest, and\n * anything else names the blocks it serves — while a caller downstream has no source\n * for it at all, and the fallbacks it could invent are all wrong. See\n * {@link ResolvedEntry}'s `title`.\n */\nexport type BlockPackProvider = {\n  /**\n   * Find the block implementing a kind selector.\n   *\n   * @param kind The entry's `{name}@{selector}` reference\n   * @param options `allowUnstable` widens the search from stable implementations to\n   *   every published one, for the whole apply\n   */\n  byKind: (\n    kind: BlockKindSelectorReference,\n    options: { allowUnstable: boolean },\n  ) => Promise<KindResolution>;\n\n  /**\n   * Find one exact block package version, named directly.\n   *\n   * This is the `block` override's path, and it bypasses kinds entirely — the\n   * override exists precisely to pin an implementation that resolution would not\n   * have chosen.\n   */\n  byExactVersion: (id: BlockPackId) => Promise<ExactResolution>;\n\n  /**\n   * Read the implementation sitting at one location.\n   *\n   * The `location` override's path, for a block that no registry knows because it was\n   * built and never published. Nothing is searched: the entry says where, so either\n   * that place holds a block or the entry is wrong.\n   *\n   * Answers \"is there a block here\", not \"is it the right one\". Whether the block found\n   * implements the kind the entry asks for is settled once it has been prepared, from the\n   * compiled model — the one place all three routes have it. This reader could answer it\n   * too, since it reads the block's description anyway, and answering it here as well would\n   * make two homes for one invariant while leaving the pinned-version route uncovered.\n   */\n  byLocation: (location: BlockPackLocationReference) => Promise<LocationResolution>;\n};\n\n/**\n * The outcome of resolving one kind selector.\n *\n * The three failure reasons are distinct because each has a different way out, and\n * a caller that collapsed them would leave the reader guessing which:\n *\n * - `no-matching-kind-version` — the selector matches no published version of the\n *   kind at all. The file, or the registry, is wrong.\n * - `no-implementation` — the kind version exists, but nothing implements it. The\n *   kind was published ahead of any block.\n * - `no-stable-implementation` — implementations exist but none is stable, and the\n *   apply did not allow unstable ones. This is the only reason the user can act on\n *   without editing anything.\n */\nexport type KindResolution =\n  | { readonly ok: true; readonly spec: BlockPackSpec; readonly title: string }\n  | {\n      readonly ok: false;\n      readonly reason:\n        | \"no-matching-kind-version\"\n        | \"no-implementation\"\n        | \"no-stable-implementation\";\n    };\n\n/** The outcome of locating one exact block version. */\nexport type ExactResolution =\n  | { readonly ok: true; readonly spec: BlockPackSpec; readonly title: string }\n  | { readonly ok: false; readonly reason: \"no-such-block-version\" };\n\n/**\n * The outcome of reading the implementation at one location.\n *\n * The three failure reasons separate three different mistakes, and each is fixed\n * differently:\n *\n * - `unsupported-scheme` — the URI is well-formed but names a way of fetching that\n *   this environment has no reader for. A property of the environment, not the file.\n * - `not-found` — nothing is at that location. Usually a template carried to another\n *   machine, or a folder that moved.\n * - `not-a-block` — something is there, but it is not a block. Usually a path pointing\n *   one directory off, which is why the message has to say what was looked for.\n */\nexport type LocationResolution =\n  | {\n      readonly ok: true;\n      readonly spec: BlockPackSpec;\n      readonly title: string;\n    }\n  | {\n      readonly ok: false;\n      readonly reason: \"unsupported-scheme\" | \"not-found\" | \"not-a-block\";\n    };\n\n/** Where one entry's block will come from. */\nexport type ResolvedEntry = {\n  /** The entry's template-local id. */\n  readonly entryId: string;\n  readonly spec: BlockPackSpec;\n  /**\n   * The block package's own title, as its author published it — `meta.title` for a\n   * registry block.\n   *\n   * Carried here because resolution is the only stage that talks to a registry, and a\n   * registry is the only thing that knows it. Nothing downstream can recover it: a\n   * prepared block pack holds the model, the workflow and the frontend, none of which\n   * names the block.\n   *\n   * It becomes the created block's label, which is what the user sees for any block\n   * whose model derives no title of its own — `graph-maker`, `table` and seven other\n   * shipped blocks. Deriving it from the entry instead is specifically wrong: an\n   * exported template names its entries by the source project's block ids, so a\n   * round-tripped project would show UUIDs in the sidebar.\n   */\n  readonly title: string;\n  /**\n   * True when the entry named its own implementation — an exact version or a location —\n   * rather than letting its kind choose one.\n   *\n   * Both overrides count, because what this records is that the choice was the file's\n   * and not the registry's, which is the same fact for either of them.\n   */\n  readonly pinned: boolean;\n};\n\n/**\n * What resolution found for a whole document.\n *\n * `resolved` is in file order and holds only the entries that resolved, so\n * `problems.length > 0` means it is incomplete. A caller must not apply a partial\n * resolution: the point of resolving before construction is that nothing is created\n * until every entry has an implementation.\n */\nexport type TemplateResolveOutcome = {\n  readonly resolved: readonly ResolvedEntry[];\n  readonly problems: readonly TemplateApplyProblem[];\n};\n\n/**\n * Resolve every entry in a template document to a concrete block pack.\n *\n * The first stage of an apply, and the only one that touches the network. It runs\n * before the project exists, which is what makes \"no block for this entry\" a message\n * about a file rather than a half-built project — and it is also why the whole\n * construction API downstream can be synchronous.\n *\n * Every entry is attempted, and every failure collected: an unapplicable file should\n * take one pass to fix, not one pass per bad entry. The one exception is that a\n * problem short-circuits nothing, so `resolved` may be shorter than the document.\n *\n * @param document A parsed template document\n * @param provider Where blocks come from\n * @param options `allowUnstable` applies to the whole document, not per entry\n */\nexport async function resolveTemplateEntries(\n  document: ProjectTemplateV1,\n  provider: BlockPackProvider,\n  options: { allowUnstable: boolean },\n): Promise<TemplateResolveOutcome> {\n  const resolved: ResolvedEntry[] = [];\n  const problems: TemplateApplyProblem[] = [];\n\n  // Sequential, not concurrent. Entries commonly share a kind, and a provider\n  // caching its reads can only dedupe them if the second request happens after the\n  // first has landed. A template holds a handful of entries, so there is nothing to\n  // win by overlapping the reads.\n  for (const entry of document.blocks) {\n    const outcome = await resolveEntry(entry, provider, options);\n    if (outcome.ok) resolved.push(outcome.entry);\n    else problems.push(outcome.problem);\n  }\n\n  return { resolved, problems };\n}\n\ntype EntryOutcome =\n  | { ok: true; entry: ResolvedEntry }\n  | { ok: false; problem: TemplateApplyProblem };\n\nasync function resolveEntry(\n  entry: ProjectTemplateV1Entry,\n  provider: BlockPackProvider,\n  options: { allowUnstable: boolean },\n): Promise<EntryOutcome> {\n  const problem = (error: string): EntryOutcome => ({\n    ok: false,\n    problem: { entryId: entry.id, error },\n  });\n\n  if (entry.location !== undefined) {\n    const outcome = await provider.byLocation(entry.location);\n\n    if (!outcome.ok) {\n      switch (outcome.reason) {\n        case \"unsupported-scheme\":\n          return problem(\n            `This entry says its block is at '${entry.location}', which this application ` +\n              `cannot read. Only a local path ('file:') is supported here.`,\n          );\n        case \"not-found\":\n          return problem(\n            `Nothing is at '${entry.location}', where this entry says its block is. A ` +\n              `template that pins a folder only works on the machine that folder is on.`,\n          );\n        case \"not-a-block\":\n          return problem(\n            `'${entry.location}' is not a block: it holds neither a built block package ` +\n              `nor a block's manifest. Point the entry at the folder holding the block's ` +\n              `package.json.`,\n          );\n      }\n    }\n\n    return {\n      ok: true,\n      entry: { entryId: entry.id, spec: outcome.spec, title: outcome.title, pinned: true },\n    };\n  }\n\n  if (entry.block !== undefined) {\n    let id: BlockPackId;\n    try {\n      const { name, version } = parseBlockPackReference(entry.block);\n      id = { ...parseBlockPackName(name), version };\n    } catch (e) {\n      // The document's parser already checked the `{name}@X.Y.Z` grammar, but not\n      // that the name carries an organization, so this is reachable from a\n      // hand-written file. Reported rather than thrown, so one malformed entry cannot\n      // hide the state of the rest.\n      return problem(`Pinned block version is not readable: ${messageOf(e)}`);\n    }\n\n    const outcome = await provider.byExactVersion(id);\n    if (outcome.ok)\n      return {\n        ok: true,\n        entry: { entryId: entry.id, spec: outcome.spec, title: outcome.title, pinned: true },\n      };\n\n    return problem(\n      `Block '${id.organization}/${id.name}' version ${id.version} was not found. Correct ` +\n        `the pinned version in this entry, or remove it so a version is chosen ` +\n        `automatically.`,\n    );\n  }\n\n  let kindName: string;\n  try {\n    kindName = parseKindSelectorReference(entry.kind).name;\n  } catch (e) {\n    return problem(`Block kind is not readable: ${messageOf(e)}`);\n  }\n\n  const outcome = await provider.byKind(entry.kind, options);\n  if (outcome.ok)\n    return {\n      ok: true,\n      entry: { entryId: entry.id, spec: outcome.spec, title: outcome.title, pinned: false },\n    };\n\n  switch (outcome.reason) {\n    case \"no-matching-kind-version\":\n      return problem(\n        `No published version of '${kindName}' matches what this entry asks for ` +\n          `(${entry.kind}). Check the version, or update the block registry.`,\n      );\n    case \"no-implementation\":\n      return problem(\n        `'${kindName}' has no block implementing the version this entry asks for ` +\n          `(${entry.kind}). Nothing can be installed for it yet.`,\n      );\n    case \"no-stable-implementation\":\n      // The one failure with a way out that changes nothing in the file, so the\n      // message names it.\n      return problem(\n        `The only blocks implementing '${kindName}' for this entry (${entry.kind}) are ` +\n          `pre-release versions. Import again with unstable versions allowed to use them.`,\n      );\n  }\n}\n\n/**\n * Split a block package's npm name into the organization and name a registry knows\n * it by: `@npm-scope/organization.name` → `{ organization, name }`.\n *\n * The npm scope and the organization are different things, and only the second one\n * reaches the registry — `@milaboratories/milaboratories.test-download-file` is\n * published as organization `milaboratories`, name `test-download-file`. The split is\n * on the FIRST dot, so a name may contain further dots.\n *\n * Kind names follow the same convention, which is why a template can carry both in\n * the same npm-ish form.\n *\n * @throws if the name has no npm scope or no organization segment\n */\nexport function parseBlockPackName(npmName: string): { organization: string; name: string } {\n  const slash = npmName.indexOf(\"/\");\n  if (!npmName.startsWith(\"@\") || slash < 0) {\n    throw new Error(`expected '@npm-scope/organization.name', got '${npmName}'`);\n  }\n\n  const base = npmName.slice(slash + 1);\n  const dot = base.indexOf(\".\");\n  if (dot <= 0 || dot === base.length - 1) {\n    throw new Error(\n      `'${base}' does not separate an organization from a name with '.' in '${npmName}'`,\n    );\n  }\n\n  return { organization: base.slice(0, dot), name: base.slice(dot + 1) };\n}\n\nfunction messageOf(e: unknown): string {\n  return e instanceof Error ? e.message : String(e);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAyLA,eAAsB,uBACpB,UACA,UACA,SACiC;CACjC,MAAM,WAA4B,CAAC;CACnC,MAAM,WAAmC,CAAC;CAM1C,KAAK,MAAM,SAAS,SAAS,QAAQ;EACnC,MAAM,UAAU,MAAM,aAAa,OAAO,UAAU,OAAO;EAC3D,IAAI,QAAQ,IAAI,SAAS,KAAK,QAAQ,KAAK;OACtC,SAAS,KAAK,QAAQ,OAAO;CACpC;CAEA,OAAO;EAAE;EAAU;CAAS;AAC9B;AAMA,eAAe,aACb,OACA,UACA,SACuB;CACvB,MAAM,WAAW,WAAiC;EAChD,IAAI;EACJ,SAAS;GAAE,SAAS,MAAM;GAAI;EAAM;CACtC;CAEA,IAAI,MAAM,aAAa,KAAA,GAAW;EAChC,MAAM,UAAU,MAAM,SAAS,WAAW,MAAM,QAAQ;EAExD,IAAI,CAAC,QAAQ,IACX,QAAQ,QAAQ,QAAhB;GACE,KAAK,sBACH,OAAO,QACL,oCAAoC,MAAM,SAAS,sFAErD;GACF,KAAK,aACH,OAAO,QACL,kBAAkB,MAAM,SAAS,kHAEnC;GACF,KAAK,eACH,OAAO,QACL,IAAI,MAAM,SAAS,iJAGrB;EACJ;EAGF,OAAO;GACL,IAAI;GACJ,OAAO;IAAE,SAAS,MAAM;IAAI,MAAM,QAAQ;IAAM,OAAO,QAAQ;IAAO,QAAQ;GAAK;EACrF;CACF;CAEA,IAAI,MAAM,UAAU,KAAA,GAAW;EAC7B,IAAI;EACJ,IAAI;GACF,MAAM,EAAE,MAAM,aAAA,GAAA,gCAAA,wBAAA,CAAoC,MAAM,KAAK;GAC7D,KAAK;IAAE,GAAG,mBAAmB,IAAI;IAAG;GAAQ;EAC9C,SAAS,GAAG;GAKV,OAAO,QAAQ,yCAAyC,UAAU,CAAC,GAAG;EACxE;EAEA,MAAM,UAAU,MAAM,SAAS,eAAe,EAAE;EAChD,IAAI,QAAQ,IACV,OAAO;GACL,IAAI;GACJ,OAAO;IAAE,SAAS,MAAM;IAAI,MAAM,QAAQ;IAAM,OAAO,QAAQ;IAAO,QAAQ;GAAK;EACrF;EAEF,OAAO,QACL,UAAU,GAAG,aAAa,GAAG,GAAG,KAAK,YAAY,GAAG,QAAQ,6GAG9D;CACF;CAEA,IAAI;CACJ,IAAI;EACF,YAAA,GAAA,gCAAA,2BAAA,CAAsC,MAAM,IAAI,CAAC,CAAC;CACpD,SAAS,GAAG;EACV,OAAO,QAAQ,+BAA+B,UAAU,CAAC,GAAG;CAC9D;CAEA,MAAM,UAAU,MAAM,SAAS,OAAO,MAAM,MAAM,OAAO;CACzD,IAAI,QAAQ,IACV,OAAO;EACL,IAAI;EACJ,OAAO;GAAE,SAAS,MAAM;GAAI,MAAM,QAAQ;GAAM,OAAO,QAAQ;GAAO,QAAQ;EAAM;CACtF;CAEF,QAAQ,QAAQ,QAAhB;EACE,KAAK,4BACH,OAAO,QACL,4BAA4B,SAAS,sCAC/B,MAAM,KAAK,oDACnB;EACF,KAAK,qBACH,OAAO,QACL,IAAI,SAAS,+DACP,MAAM,KAAK,wCACnB;EACF,KAAK,4BAGH,OAAO,QACL,iCAAiC,SAAS,oBAAoB,MAAM,KAAK,qFAE3E;CACJ;AACF;;;;;;;;;;;;;;;AAgBA,SAAgB,mBAAmB,SAAyD;CAC1F,MAAM,QAAQ,QAAQ,QAAQ,GAAG;CACjC,IAAI,CAAC,QAAQ,WAAW,GAAG,KAAK,QAAQ,GACtC,MAAM,IAAI,MAAM,iDAAiD,QAAQ,EAAE;CAG7E,MAAM,OAAO,QAAQ,MAAM,QAAQ,CAAC;CACpC,MAAM,MAAM,KAAK,QAAQ,GAAG;CAC5B,IAAI,OAAO,KAAK,QAAQ,KAAK,SAAS,GACpC,MAAM,IAAI,MACR,IAAI,KAAK,+DAA+D,QAAQ,EAClF;CAGF,OAAO;EAAE,cAAc,KAAK,MAAM,GAAG,GAAG;EAAG,MAAM,KAAK,MAAM,MAAM,CAAC;CAAE;AACvE;AAEA,SAAS,UAAU,GAAoB;CACrC,OAAO,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC;AAClD"}