@milaboratories/pl-middle-layer 1.66.19 → 1.67.0

package/dist/model/template_resolve.d.ts

@@ -0,0 +1,193 @@
+import { TemplateApplyProblem } from "./template_apply.js";
+import { BlockPackId, BlockPackSpec } from "@milaboratories/pl-model-middle-layer";
+import { BlockKindSelectorReference, BlockPackLocationReference, ProjectTemplateV1 } from "@milaboratories/pl-model-common";
+
+//#region src/model/template_resolve.d.ts
+/**
+ * Where a template entry's block comes from.
+ *
+ * All three of an entry's paths to an implementation go through this one interface, and
+ * all three come back as the same `BlockPackSpec` — the shape the existing add-block
+ * path already consumes — plus the block's published title. That convergence is the
+ * point: everything downstream of resolution treats a kind-resolved entry, a
+ * version-pinned one and a filesystem-located one identically, which is why a locally
+ * built block travels the same preparation and construction path as a published one.
+ *
+ * Registry knowledge sits deliberately on the far side of this interface. A template
+ * file names no registry, so choosing which one (or ones) to consult is a property
+ * of the environment applying the file, not of the file — and keeping it out here is
+ * what lets resolution be tested with no registry at all.
+ *
+ * The title is required rather than optional for the same reason: an implementation
+ * always has one to hand — a registry adapter reads it off the block's manifest, and
+ * anything else names the blocks it serves — while a caller downstream has no source
+ * for it at all, and the fallbacks it could invent are all wrong. See
+ * {@link ResolvedEntry}'s `title`.
+ */
+type BlockPackProvider = {
+  /**
+   * Find the block implementing a kind selector.
+   *
+   * @param kind The entry's `{name}@{selector}` reference
+   * @param options `allowUnstable` widens the search from stable implementations to
+   *   every published one, for the whole apply
+   */
+  byKind: (kind: BlockKindSelectorReference, options: {
+    allowUnstable: boolean;
+  }) => Promise<KindResolution>;
+  /**
+   * Find one exact block package version, named directly.
+   *
+   * This is the `block` override's path, and it bypasses kinds entirely — the
+   * override exists precisely to pin an implementation that resolution would not
+   * have chosen.
+   */
+  byExactVersion: (id: BlockPackId) => Promise<ExactResolution>;
+  /**
+   * Read the implementation sitting at one location.
+   *
+   * The `location` override's path, for a block that no registry knows because it was
+   * built and never published. Nothing is searched: the entry says where, so either
+   * that place holds a block or the entry is wrong.
+   *
+   * Answers "is there a block here", not "is it the right one". Whether the block found
+   * implements the kind the entry asks for is settled once it has been prepared, from the
+   * compiled model — the one place all three routes have it. This reader could answer it
+   * too, since it reads the block's description anyway, and answering it here as well would
+   * make two homes for one invariant while leaving the pinned-version route uncovered.
+   */
+  byLocation: (location: BlockPackLocationReference) => Promise<LocationResolution>;
+};
+/**
+ * The outcome of resolving one kind selector.
+ *
+ * The three failure reasons are distinct because each has a different way out, and
+ * a caller that collapsed them would leave the reader guessing which:
+ *
+ * - `no-matching-kind-version` — the selector matches no published version of the
+ *   kind at all. The file, or the registry, is wrong.
+ * - `no-implementation` — the kind version exists, but nothing implements it. The
+ *   kind was published ahead of any block.
+ * - `no-stable-implementation` — implementations exist but none is stable, and the
+ *   apply did not allow unstable ones. This is the only reason the user can act on
+ *   without editing anything.
+ */
+type KindResolution = {
+  readonly ok: true;
+  readonly spec: BlockPackSpec;
+  readonly title: string;
+} | {
+  readonly ok: false;
+  readonly reason: "no-matching-kind-version" | "no-implementation" | "no-stable-implementation";
+};
+/** The outcome of locating one exact block version. */
+type ExactResolution = {
+  readonly ok: true;
+  readonly spec: BlockPackSpec;
+  readonly title: string;
+} | {
+  readonly ok: false;
+  readonly reason: "no-such-block-version";
+};
+/**
+ * The outcome of reading the implementation at one location.
+ *
+ * The three failure reasons separate three different mistakes, and each is fixed
+ * differently:
+ *
+ * - `unsupported-scheme` — the URI is well-formed but names a way of fetching that
+ *   this environment has no reader for. A property of the environment, not the file.
+ * - `not-found` — nothing is at that location. Usually a template carried to another
+ *   machine, or a folder that moved.
+ * - `not-a-block` — something is there, but it is not a block. Usually a path pointing
+ *   one directory off, which is why the message has to say what was looked for.
+ */
+type LocationResolution = {
+  readonly ok: true;
+  readonly spec: BlockPackSpec;
+  readonly title: string;
+} | {
+  readonly ok: false;
+  readonly reason: "unsupported-scheme" | "not-found" | "not-a-block";
+};
+/** Where one entry's block will come from. */
+type ResolvedEntry = {
+  /** The entry's template-local id. */readonly entryId: string;
+  readonly spec: BlockPackSpec;
+  /**
+   * The block package's own title, as its author published it — `meta.title` for a
+   * registry block.
+   *
+   * Carried here because resolution is the only stage that talks to a registry, and a
+   * registry is the only thing that knows it. Nothing downstream can recover it: a
+   * prepared block pack holds the model, the workflow and the frontend, none of which
+   * names the block.
+   *
+   * It becomes the created block's label, which is what the user sees for any block
+   * whose model derives no title of its own — `graph-maker`, `table` and seven other
+   * shipped blocks. Deriving it from the entry instead is specifically wrong: an
+   * exported template names its entries by the source project's block ids, so a
+   * round-tripped project would show UUIDs in the sidebar.
+   */
+  readonly title: string;
+  /**
+   * True when the entry named its own implementation — an exact version or a location —
+   * rather than letting its kind choose one.
+   *
+   * Both overrides count, because what this records is that the choice was the file's
+   * and not the registry's, which is the same fact for either of them.
+   */
+  readonly pinned: boolean;
+};
+/**
+ * What resolution found for a whole document.
+ *
+ * `resolved` is in file order and holds only the entries that resolved, so
+ * `problems.length > 0` means it is incomplete. A caller must not apply a partial
+ * resolution: the point of resolving before construction is that nothing is created
+ * until every entry has an implementation.
+ */
+type TemplateResolveOutcome = {
+  readonly resolved: readonly ResolvedEntry[];
+  readonly problems: readonly TemplateApplyProblem[];
+};
+/**
+ * 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
+ */
+declare function resolveTemplateEntries(document: ProjectTemplateV1, provider: BlockPackProvider, options: {
+  allowUnstable: boolean;
+}): Promise<TemplateResolveOutcome>;
+/**
+ * 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
+ */
+declare function parseBlockPackName(npmName: string): {
+  organization: string;
+  name: string;
+};
+//#endregion
+export { BlockPackProvider, ExactResolution, KindResolution, LocationResolution, ResolvedEntry, TemplateResolveOutcome, parseBlockPackName, resolveTemplateEntries };
+//# sourceMappingURL=template_resolve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"template_resolve.d.ts","names":[],"sources":["../../src/model/template_resolve.ts"],"mappings":";;;;;;;AAkCA;;;;;;;;;;;;;;;;;;;KAAY,iBAAA;EAWG;;;;;;;EAHb,MAAA,GACE,IAAA,EAAM,0BAAA,EACN,OAAA;IAAW,aAAA;EAAA,MACR,OAAA,CAAQ,cAAA;EAwBiD;;AAAkB;AAiBlF;;;;EAhCE,cAAA,GAAiB,EAAA,EAAI,WAAA,KAAgB,OAAA,CAAQ,eAAA;EAiCb;;;;;;AAGb;AAOrB;;;;;;EA5BE,UAAA,GAAa,QAAA,EAAU,0BAAA,KAA+B,OAAA,CAAQ,kBAAA;AAAA;;;;AA8BvB;AAezC;;;;;;;;;;KA5BY,cAAA;EAAA,SACG,EAAA;EAAA,SAAmB,IAAA,EAAM,aAAa;EAAA,SAAW,KAAA;AAAA;EAAA,SAEjD,EAAA;EAAA,SACA,MAAA;AAAA;;KAOH,eAAA;EAAA,SACG,EAAA;EAAA,SAAmB,IAAA,EAAM,aAAa;EAAA,SAAW,KAAA;AAAA;EAAA,SACjD,EAAA;EAAA,SAAoB,MAAA;AAAA;;;;;;AAmEe;AAmBlD;;;;;;;KAvEY,kBAAA;EAAA,SAEG,EAAA;EAAA,SACA,IAAA,EAAM,aAAa;EAAA,SACnB,KAAA;AAAA;EAAA,SAGA,EAAA;EAAA,SACA,MAAA;AAAA;;KAIH,aAAA;EA+DqB,8CA7DtB,OAAA;EAAA,SACA,IAAA,EAAM,aAAa;EAqMI;;;;;;;AAA+C;;;;;;;;EAA/C,SArLvB,KAAA;;;;;;;;WAQA,MAAA;AAAA;;;;;;;;;KAWC,sBAAA;EAAA,SACD,QAAA,WAAmB,aAAA;EAAA,SACnB,QAAA,WAAmB,oBAAoB;AAAA;;;;;;;;;;;;;;;;;iBAmB5B,sBAAA,CACpB,QAAA,EAAU,iBAAA,EACV,QAAA,EAAU,iBAAA,EACV,OAAA;EAAW,aAAA;AAAA,IACV,OAAA,CAAQ,sBAAA;;;;;;;;;;;;;;;iBAyIK,kBAAA,CAAmB,OAAA;EAAoB,YAAA;EAAsB,IAAA;AAAA"}

package/dist/model/template_resolve.js

@@ -0,0 +1,133 @@
+import { parseBlockPackReference, parseKindSelectorReference } from "@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 } = 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 = 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
+export { parseBlockPackName, resolveTemplateEntries };
+
+//# sourceMappingURL=template_resolve.js.map

package/dist/model/template_resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_resolve.js","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,YAAY,wBAAwB,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,WAAW,2BAA2B,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"}

package/dist/model/template_serializer.cjs

@@ -0,0 +1,162 @@
+const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+const require_template_export = require("./template_export.cjs");
+let yaml = require("yaml");
+yaml = require_runtime.__toESM(yaml, 1);
+let node_url = require("node:url");
+let _milaboratories_pl_model_common = require("@milaboratories/pl-model-common");
+//#region src/model/template_serializer.ts
+/**
+* The `location` to write for a block installed from the filesystem, or `undefined`
+* for one that came from a registry and therefore needs no locator.
+*
+* Both filesystem spec shapes are emitted, and they anchor at different directories
+* — a dev block at its facade package, an npm-consumed one at its block-pack folder.
+* The document does not distinguish them: one URI is written either way, and telling
+* the two layouts apart is done by looking at what is actually there, by the side
+* that has the filesystem anyway. Encoding the layout in the file instead would
+* freeze today's two shapes into the format.
+*
+* A dev spec carries an OS path and is converted here, which also percent-encodes a
+* path containing spaces. An npm-consumed spec already carries a `file:` URL and is
+* passed through: it is the locator the block itself emitted, and reconstructing one
+* from it could only lose information.
+*/
+function locationOf(spec) {
+	switch (spec.type) {
+		case "dev-v2": return (0, node_url.pathToFileURL)(spec.folder).href;
+		case "from-pack-v2": return spec.packUrl;
+		case "dev-v1":
+		case "from-registry-v1":
+		case "from-registry-v2": return;
+	}
+}
+/**
+* Turn a project into a template document.
+*
+* Assembly is deliberately dull — the entry is the block's id, its widened kind
+* reference, and the params the walk already collected. The interesting decisions
+* were made upstream; what is left here is the two things only this layer can
+* check, both of which produce problems rather than a broken file:
+*
+* - **A block with no kind cannot be written.** An entry's `kind` is required — it
+*   is the params contract the entry is typed against — while a block's kind is
+*   optional, so a block that predates kinds, or that uses the deprecated
+*   kind-less model overload, has no legal entry. Reported per block. This is not
+*   an edge case today: it is what most existing projects will hit until their
+*   blocks are republished.
+* - **References must point at an entry declared earlier.** Verbatim id reuse
+*   means a reference to a deleted block survives into the file naming nothing:
+*   deleting a block only removes it from the structure and does not rewrite
+*   downstream args, so a live project holds such references routinely.
+*
+* `block` is never emitted. That override exists to pin an implementation against
+* a kind's version range, and export always writes the exact version the block
+* implements, so there is nothing left for it to pin.
+*
+* `location` IS emitted, for every block that was installed from the filesystem. Such
+* a block is not in any registry, so the kind reference alone names nothing the
+* importer could find, and a file that omitted the one usable answer would describe a
+* project that cannot be recreated. It costs portability, and nothing says so: such a
+* file is the debugging path, read by the developer who wrote it on the machine that
+* wrote it.
+*
+* Problems from `walk` are carried through, so a caller can hand a walk straight
+* in and get one combined list.
+*/
+function assembleProjectTemplateV1(walk, kindProvider, specProvider) {
+	const problems = [...walk.problems];
+	const blocks = [];
+	for (const entry of walk.entries) {
+		const kind = kindProvider(entry.blockId);
+		if (kind === void 0) {
+			problems.push({
+				blockId: entry.blockId,
+				error: "Block declares no kind, so it cannot be written to a template: an entry's kind carries the params contract the entry is typed against"
+			});
+			continue;
+		}
+		let selector;
+		try {
+			selector = (0, _milaboratories_pl_model_common.kindReferenceToSelectorReference)(kind);
+		} catch (e) {
+			problems.push({
+				blockId: entry.blockId,
+				error: `Block's stored kind reference is malformed: ${e instanceof Error ? e.message : String(e)}`
+			});
+			continue;
+		}
+		const spec = specProvider(entry.blockId);
+		const location = spec === void 0 ? void 0 : locationOf(spec);
+		blocks.push({
+			id: entry.blockId,
+			kind: selector,
+			params: entry.params,
+			...location !== void 0 ? { location } : {}
+		});
+	}
+	return {
+		document: {
+			schema: _milaboratories_pl_model_common.PROJECT_TEMPLATE_SCHEMA_V1,
+			blocks
+		},
+		problems
+	};
+}
+/**
+* Render a template document to YAML text.
+*
+* Two non-default emitter settings, both about the file being read by someone
+* else's code:
+*
+* - **No line folding.** A wrapped scalar still parses, but it makes a diff between
+*   two exported templates unreadable, which is most of the reason to prefer YAML
+*   over JSON here.
+* - **Quote as if the reader were YAML 1.1**, while still parsing as 1.2. YAML 1.2
+*   dropped `yes`/`no`/`on`/`off`/`y`/`n` as booleans and dropped sexagesimal
+*   integers, so a 1.2 emitter leaves a params value of `"yes"` or `"1:30"` bare —
+*   which a 1.1 reader (PyYAML's default, and Go's yaml.v2) turns into `true` and
+*   `90`. A template is a contract for a second implementation, so the safe
+*   combination is to quote against the stricter ruleset and read with the looser
+*   one: a quoted scalar means the same thing under both. This adds no `%YAML`
+*   directive — it only changes which scalars get quotes.
+*/
+function stringifyProjectTemplateV1(document) {
+	return yaml.default.stringify(document, {
+		lineWidth: 0,
+		version: "1.1"
+	});
+}
+/**
+* Export a project as `template-v1` YAML, or report every reason it cannot be.
+*
+* All-or-nothing on purpose. A partial template silently drops blocks and the
+* surviving entries may reference the dropped ones, so what looks like a
+* successful export would produce a project missing pieces the user never chose
+* to leave out. Reporting everything at once instead of failing on the first
+* problem is the other half of that: fixing an export should take one pass.
+*
+* @param structure The project structure, which supplies both membership and order
+* @param paramsProvider A block's derived template params, in live form
+* @param kindProvider A block's exact kind reference, read from its stored config
+* @param specProvider A block's origin spec, read from the same stored container
+*/
+function exportProjectAsTemplateV1(structure, paramsProvider, kindProvider, specProvider) {
+	const { document, problems } = assembleProjectTemplateV1(require_template_export.walkProjectForTemplateExport(structure, paramsProvider), kindProvider, specProvider);
+	if (problems.length > 0) return {
+		ok: false,
+		problems
+	};
+	(0, _milaboratories_pl_model_common.parseProjectTemplateV1)(document);
+	return {
+		ok: true,
+		yaml: stringifyProjectTemplateV1(document),
+		document
+	};
+}
+//#endregion
+exports.assembleProjectTemplateV1 = assembleProjectTemplateV1;
+exports.exportProjectAsTemplateV1 = exportProjectAsTemplateV1;
+exports.locationOf = locationOf;
+exports.stringifyProjectTemplateV1 = stringifyProjectTemplateV1;
+
+//# sourceMappingURL=template_serializer.cjs.map

package/dist/model/template_serializer.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"template_serializer.cjs","names":["PROJECT_TEMPLATE_SCHEMA_V1","YAML","walkProjectForTemplateExport"],"sources":["../../src/model/template_serializer.ts"],"sourcesContent":["import YAML from \"yaml\";\nimport { pathToFileURL } from \"node:url\";\nimport type {\n  BlockKindReference,\n  BlockKindSelectorReference,\n  BlockPackLocationReference,\n  ProjectTemplateV1,\n  ProjectTemplateV1Entry,\n} from \"@milaboratories/pl-model-common\";\nimport {\n  PROJECT_TEMPLATE_SCHEMA_V1,\n  kindReferenceToSelectorReference,\n  parseProjectTemplateV1,\n} from \"@milaboratories/pl-model-common\";\nimport type { BlockPackSpec } from \"@milaboratories/pl-model-middle-layer\";\nimport type { ProjectStructure } from \"./project_model\";\nimport type {\n  TemplateExportProblem,\n  TemplateExportWalk,\n  TemplateParamsResult,\n} from \"./template_export\";\nimport { walkProjectForTemplateExport } from \"./template_export\";\n\n/** A block's exact kind reference, or `undefined` for a block that declares no kind. */\nexport type BlockKindProvider = (blockId: string) => BlockKindReference | undefined;\n\n/**\n * A block's origin spec — where the installed block came from — or `undefined` when\n * it is not known for that block.\n *\n * The project stores this next to the kind reference, so both are read from the same\n * place and neither costs an extra round-trip.\n */\nexport type BlockPackSpecProvider = (blockId: string) => BlockPackSpec | undefined;\n\n/** What the caller gets back for a whole project. */\nexport type ProjectTemplateExportOutcome =\n  | {\n      readonly ok: true;\n      readonly yaml: string;\n      /** The document the YAML was rendered from, already validated. */\n      readonly document: ProjectTemplateV1;\n    }\n  | {\n      readonly ok: false;\n      /** Every block that stands in the way, not just the first. */\n      readonly problems: readonly TemplateExportProblem[];\n    };\n\n/**\n * The `location` to write for a block installed from the filesystem, or `undefined`\n * for one that came from a registry and therefore needs no locator.\n *\n * Both filesystem spec shapes are emitted, and they anchor at different directories\n * — a dev block at its facade package, an npm-consumed one at its block-pack folder.\n * The document does not distinguish them: one URI is written either way, and telling\n * the two layouts apart is done by looking at what is actually there, by the side\n * that has the filesystem anyway. Encoding the layout in the file instead would\n * freeze today's two shapes into the format.\n *\n * A dev spec carries an OS path and is converted here, which also percent-encodes a\n * path containing spaces. An npm-consumed spec already carries a `file:` URL and is\n * passed through: it is the locator the block itself emitted, and reconstructing one\n * from it could only lose information.\n */\nexport function locationOf(spec: BlockPackSpec): BlockPackLocationReference | undefined {\n  switch (spec.type) {\n    case \"dev-v2\":\n      return pathToFileURL(spec.folder).href as BlockPackLocationReference;\n    case \"from-pack-v2\":\n      return spec.packUrl as BlockPackLocationReference;\n    // A registry block is found by name, which is what makes the entry portable —\n    // writing where this machine happened to cache it would take that away. `dev-v1`\n    // predates kinds entirely, so such a block has no kind and never reaches here.\n    case \"dev-v1\":\n    case \"from-registry-v1\":\n    case \"from-registry-v2\":\n      return undefined;\n  }\n}\n\n/**\n * Turn a project into a template document.\n *\n * Assembly is deliberately dull — the entry is the block's id, its widened kind\n * reference, and the params the walk already collected. The interesting decisions\n * were made upstream; what is left here is the two things only this layer can\n * check, both of which produce problems rather than a broken file:\n *\n * - **A block with no kind cannot be written.** An entry's `kind` is required — it\n *   is the params contract the entry is typed against — while a block's kind is\n *   optional, so a block that predates kinds, or that uses the deprecated\n *   kind-less model overload, has no legal entry. Reported per block. This is not\n *   an edge case today: it is what most existing projects will hit until their\n *   blocks are republished.\n * - **References must point at an entry declared earlier.** Verbatim id reuse\n *   means a reference to a deleted block survives into the file naming nothing:\n *   deleting a block only removes it from the structure and does not rewrite\n *   downstream args, so a live project holds such references routinely.\n *\n * `block` is never emitted. That override exists to pin an implementation against\n * a kind's version range, and export always writes the exact version the block\n * implements, so there is nothing left for it to pin.\n *\n * `location` IS emitted, for every block that was installed from the filesystem. Such\n * a block is not in any registry, so the kind reference alone names nothing the\n * importer could find, and a file that omitted the one usable answer would describe a\n * project that cannot be recreated. It costs portability, and nothing says so: such a\n * file is the debugging path, read by the developer who wrote it on the machine that\n * wrote it.\n *\n * Problems from `walk` are carried through, so a caller can hand a walk straight\n * in and get one combined list.\n */\nexport function assembleProjectTemplateV1(\n  walk: TemplateExportWalk,\n  kindProvider: BlockKindProvider,\n  specProvider: BlockPackSpecProvider,\n): { document: ProjectTemplateV1; problems: readonly TemplateExportProblem[] } {\n  const problems: TemplateExportProblem[] = [...walk.problems];\n  const blocks: ProjectTemplateV1Entry[] = [];\n\n  for (const entry of walk.entries) {\n    const kind = kindProvider(entry.blockId);\n\n    if (kind === undefined) {\n      problems.push({\n        blockId: entry.blockId,\n        error:\n          \"Block declares no kind, so it cannot be written to a template: an entry's kind \" +\n          \"carries the params contract the entry is typed against\",\n      });\n      continue;\n    }\n\n    let selector: BlockKindSelectorReference;\n    try {\n      // Widening validates, and therefore throws — which is why it happens here\n      // and not where the reference is read: every read site sits inside a\n      // recomputed project overview, where one malformed stored reference must not\n      // be able to break unrelated blocks.\n      selector = kindReferenceToSelectorReference(kind);\n    } catch (e) {\n      problems.push({\n        blockId: entry.blockId,\n        error: `Block's stored kind reference is malformed: ${e instanceof Error ? e.message : String(e)}`,\n      });\n      continue;\n    }\n\n    const spec = specProvider(entry.blockId);\n    const location = spec === undefined ? undefined : locationOf(spec);\n\n    blocks.push({\n      id: entry.blockId,\n      kind: selector,\n      params: entry.params,\n      ...(location !== undefined ? { location } : {}),\n    });\n  }\n\n  // References are not examined. A project's structure is topological by construction, so an\n  // entry cannot legally reference one below it — and checking would mean reading the params,\n  // which only the block that wrote them can do.\n  const document: ProjectTemplateV1 = { schema: PROJECT_TEMPLATE_SCHEMA_V1, blocks };\n\n  return { document, problems };\n}\n\n/**\n * Render a template document to YAML text.\n *\n * Two non-default emitter settings, both about the file being read by someone\n * else's code:\n *\n * - **No line folding.** A wrapped scalar still parses, but it makes a diff between\n *   two exported templates unreadable, which is most of the reason to prefer YAML\n *   over JSON here.\n * - **Quote as if the reader were YAML 1.1**, while still parsing as 1.2. YAML 1.2\n *   dropped `yes`/`no`/`on`/`off`/`y`/`n` as booleans and dropped sexagesimal\n *   integers, so a 1.2 emitter leaves a params value of `\"yes\"` or `\"1:30\"` bare —\n *   which a 1.1 reader (PyYAML's default, and Go's yaml.v2) turns into `true` and\n *   `90`. A template is a contract for a second implementation, so the safe\n *   combination is to quote against the stricter ruleset and read with the looser\n *   one: a quoted scalar means the same thing under both. This adds no `%YAML`\n *   directive — it only changes which scalars get quotes.\n */\nexport function stringifyProjectTemplateV1(document: ProjectTemplateV1): string {\n  return YAML.stringify(document, { lineWidth: 0, version: \"1.1\" });\n}\n\n/**\n * Export a project as `template-v1` YAML, or report every reason it cannot be.\n *\n * All-or-nothing on purpose. A partial template silently drops blocks and the\n * surviving entries may reference the dropped ones, so what looks like a\n * successful export would produce a project missing pieces the user never chose\n * to leave out. Reporting everything at once instead of failing on the first\n * problem is the other half of that: fixing an export should take one pass.\n *\n * @param structure The project structure, which supplies both membership and order\n * @param paramsProvider A block's derived template params, in live form\n * @param kindProvider A block's exact kind reference, read from its stored config\n * @param specProvider A block's origin spec, read from the same stored container\n */\nexport function exportProjectAsTemplateV1(\n  structure: ProjectStructure,\n  paramsProvider: (blockId: string) => TemplateParamsResult | undefined,\n  kindProvider: BlockKindProvider,\n  specProvider: BlockPackSpecProvider,\n): ProjectTemplateExportOutcome {\n  const walk = walkProjectForTemplateExport(structure, paramsProvider);\n  const { document, problems } = assembleProjectTemplateV1(walk, kindProvider, specProvider);\n\n  if (problems.length > 0) return { ok: false, problems };\n\n  // Export must emit exactly what import parses, so that is asserted on every\n  // export rather than only in tests — running the import-side parser over the\n  // document we are about to write is the cheapest possible proof of it. Nothing\n  // user-facing is expected to fail here: the kind grammar was checked by the\n  // widening above, params were checked to be a mapping by the walk, and the\n  // reference rules by the assembler. A throw means a bug in the assembler, with\n  // one known exception: a project structure holding two blocks with the same id,\n  // which is reachable through the mutator and produces duplicate entry ids.\n  parseProjectTemplateV1(document);\n\n  return {\n    ok: true,\n    yaml: stringifyProjectTemplateV1(document),\n    document,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAiEA,SAAgB,WAAW,MAA6D;CACtF,QAAQ,KAAK,MAAb;EACE,KAAK,UACH,QAAA,GAAA,SAAA,cAAA,CAAqB,KAAK,MAAM,CAAC,CAAC;EACpC,KAAK,gBACH,OAAO,KAAK;EAId,KAAK;EACL,KAAK;EACL,KAAK,oBACH;CACJ;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,0BACd,MACA,cACA,cAC6E;CAC7E,MAAM,WAAoC,CAAC,GAAG,KAAK,QAAQ;CAC3D,MAAM,SAAmC,CAAC;CAE1C,KAAK,MAAM,SAAS,KAAK,SAAS;EAChC,MAAM,OAAO,aAAa,MAAM,OAAO;EAEvC,IAAI,SAAS,KAAA,GAAW;GACtB,SAAS,KAAK;IACZ,SAAS,MAAM;IACf,OACE;GAEJ,CAAC;GACD;EACF;EAEA,IAAI;EACJ,IAAI;GAKF,YAAA,GAAA,gCAAA,iCAAA,CAA4C,IAAI;EAClD,SAAS,GAAG;GACV,SAAS,KAAK;IACZ,SAAS,MAAM;IACf,OAAO,+CAA+C,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC;GACjG,CAAC;GACD;EACF;EAEA,MAAM,OAAO,aAAa,MAAM,OAAO;EACvC,MAAM,WAAW,SAAS,KAAA,IAAY,KAAA,IAAY,WAAW,IAAI;EAEjE,OAAO,KAAK;GACV,IAAI,MAAM;GACV,MAAM;GACN,QAAQ,MAAM;GACd,GAAI,aAAa,KAAA,IAAY,EAAE,SAAS,IAAI,CAAC;EAC/C,CAAC;CACH;CAOA,OAAO;EAAE,UAAA;GAF6B,QAAQA,gCAAAA;GAA4B;EAE1D;EAAG;CAAS;AAC9B;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,2BAA2B,UAAqC;CAC9E,OAAOC,KAAAA,QAAK,UAAU,UAAU;EAAE,WAAW;EAAG,SAAS;CAAM,CAAC;AAClE;;;;;;;;;;;;;;;AAgBA,SAAgB,0BACd,WACA,gBACA,cACA,cAC8B;CAE9B,MAAM,EAAE,UAAU,aAAa,0BADlBC,wBAAAA,6BAA6B,WAAW,cACO,GAAG,cAAc,YAAY;CAEzF,IAAI,SAAS,SAAS,GAAG,OAAO;EAAE,IAAI;EAAO;CAAS;CAUtD,CAAA,GAAA,gCAAA,uBAAA,CAAuB,QAAQ;CAE/B,OAAO;EACL,IAAI;EACJ,MAAM,2BAA2B,QAAQ;EACzC;CACF;AACF"}

package/dist/model/template_serializer.d.ts

@@ -0,0 +1,17 @@
+import { TemplateExportProblem } from "./template_export.js";
+import { BlockPackSpec } from "@milaboratories/pl-model-middle-layer";
+import { BlockKindReference, BlockPackLocationReference, ProjectTemplateV1 } from "@milaboratories/pl-model-common";
+
+//#region src/model/template_serializer.d.ts
+/** What the caller gets back for a whole project. */
+type ProjectTemplateExportOutcome = {
+  readonly ok: true;
+  readonly yaml: string; /** The document the YAML was rendered from, already validated. */
+  readonly document: ProjectTemplateV1;
+} | {
+  readonly ok: false; /** Every block that stands in the way, not just the first. */
+  readonly problems: readonly TemplateExportProblem[];
+};
+//#endregion
+export { ProjectTemplateExportOutcome };
+//# sourceMappingURL=template_serializer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"template_serializer.d.ts","names":[],"sources":["../../src/model/template_serializer.ts"],"mappings":";;;;;;KAoCY,4BAAA;EAAA,SAEG,EAAA;EAAA,SACA,IAAA,UAOwC;EAAA,SALxC,QAAA,EAAU,iBAAA;AAAA;EAAA,SAGV,EAAA;WAEA,QAAA,WAAmB,qBAAqB;AAAA"}