@milaboratories/pl-model-common 1.47.3 → 1.48.0

package/dist/template/kind_selector.js

@@ -0,0 +1,87 @@
+import { parseKindRef, splitVersionedName } from "../bmodel/block_kind_ref.js";
+//#region src/template/kind_selector.ts
+/** `X.Y.Z` with optional semver prerelease and build metadata. */
+const semVerRegex = /^\d+\.\d+\.\d+(?:-[\dA-Za-z-]+(?:\.[\dA-Za-z-]+)*)?(?:\+[\dA-Za-z-]+(?:\.[\dA-Za-z-]+)*)?$/;
+/**
+* Split a raw selector string (`1.2.0`, `~1.2.0`, `^1.2.0`) into its parts.
+*
+* The version is validated as `X.Y.Z`, so a range that is legal npm but not part
+* of the kind grammar (`>=1.0.0`, `1.x`, `latest`) is rejected here rather than
+* reaching resolution. Note the deliberate divergence from
+* `tools/block-tools`'s `parseSelector`, which additionally tolerates a leading
+* `@` as `exact`: after the `{name}@{selector}` split a leading `@` can only
+* come from a doubled separator, which is malformed.
+*
+* Mapping a selector onto a concrete version is resolution, not parsing, and
+* lives with the resolver (`kind_resolver.selectorToRange`).
+*
+* @throws if the version part is not `X.Y.Z`
+*/
+function parseKindSelector(raw) {
+	const s = raw.trim();
+	const op = s.startsWith("~") ? "patch" : s.startsWith("^") ? "minor" : "exact";
+	const version = op === "exact" ? s : s.slice(1);
+	if (!semVerRegex.test(version)) throw new Error(`Malformed kind version selector (expected 'X.Y.Z', '~X.Y.Z' or '^X.Y.Z'): ${raw}`);
+	return {
+		op,
+		version
+	};
+}
+/** Render a {@link KindSelector} back to its on-wire string. */
+function formatKindSelector(sel) {
+	switch (sel.op) {
+		case "exact": return sel.version;
+		case "patch": return `~${sel.version}`;
+		case "minor": return `^${sel.version}`;
+	}
+}
+/**
+* Split a {@link BlockKindSelectorReference} into `{ name, selector }`.
+*
+* @throws if the reference carries no version segment, or the selector is
+*   outside the `X.Y.Z` / `~X.Y.Z` / `^X.Y.Z` grammar
+*/
+function parseKindSelectorReference(ref) {
+	const { name, version } = splitVersionedName(ref, "kind selector reference", "{name}@{selector}");
+	return {
+		name,
+		selector: parseKindSelector(version)
+	};
+}
+/**
+* Compose a {@link BlockKindSelectorReference} from a name and selector.
+*
+* A formatter, not a validator — pass a selector that came from
+* {@link parseKindSelector} or that you constructed from a known-good version.
+*/
+function formatKindSelectorReference(k) {
+	return `${k.name}@${formatKindSelector(k.selector)}`;
+}
+/**
+* Widen a resolved {@link BlockKindReference} to its `exact`-tier selector form.
+*
+* The export direction: a block implements exactly one kind version, so export
+* always emits `{name}@X.Y.Z`. Validates on the way through, so a
+* malformed stored reference fails at the boundary rather than in the file.
+*/
+function kindReferenceToSelectorReference(ref) {
+	const { name, version } = parseKindRef(ref);
+	return formatKindSelectorReference({
+		name,
+		selector: parseKindSelector(version)
+	});
+}
+/** Whether `value` is a well-formed `{name}@{selector}` string. */
+function isBlockKindSelectorReference(value) {
+	if (typeof value !== "string") return false;
+	try {
+		parseKindSelectorReference(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { formatKindSelector, formatKindSelectorReference, isBlockKindSelectorReference, kindReferenceToSelectorReference, parseKindSelector, parseKindSelectorReference };
+
+//# sourceMappingURL=kind_selector.js.map

package/dist/template/kind_selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kind_selector.js","names":[],"sources":["../../src/template/kind_selector.ts"],"sourcesContent":["import type { Branded } from \"@milaboratories/helpers\";\nimport type { BlockKindReference } from \"../bmodel/block_kind_ref\";\nimport { parseKindRef, splitVersionedName } from \"../bmodel/block_kind_ref\";\n\n/**\n * Version-selection tier of a template entry's `kind` field.\n *\n * - `exact` — `X.Y.Z`: this version and no other.\n * - `patch` — `~X.Y.Z`: patch floor, behavior frozen.\n * - `minor` — `^X.Y.Z`: minor floor, behavior floats.\n */\nexport type KindSelectorOp = \"exact\" | \"patch\" | \"minor\";\n\n/** The version half of a `{name}@{selector}` kind reference, split into parts. */\nexport type KindSelector = {\n  readonly op: KindSelectorOp;\n  readonly version: string;\n};\n\n/**\n * On-wire reference to a *set* of block kind versions: `{name}@{selector}`, e.g.\n * `@platforma-open/milaboratories.mixcr-clonotyping.kind@~1.2.0`.\n *\n * The template-file form of a kind reference, and the only form the\n * `template-v1` schema accepts in an entry's `kind` field. It is the same string\n * shape as {@link BlockKindReference} widened by the `~`/`^` tiers, but branded\n * separately so a *resolved* kind reference is never silently passed where a\n * selector is expected, or vice versa. Widen an exact reference explicitly with\n * {@link kindReferenceToSelectorReference}.\n */\nexport type BlockKindSelectorReference = Branded<string, \"BlockKindSelectorReference\">;\n\n/** `X.Y.Z` with optional semver prerelease and build metadata. */\nconst semVerRegex =\n  /^\\d+\\.\\d+\\.\\d+(?:-[\\dA-Za-z-]+(?:\\.[\\dA-Za-z-]+)*)?(?:\\+[\\dA-Za-z-]+(?:\\.[\\dA-Za-z-]+)*)?$/;\n\n/**\n * Split a raw selector string (`1.2.0`, `~1.2.0`, `^1.2.0`) into its parts.\n *\n * The version is validated as `X.Y.Z`, so a range that is legal npm but not part\n * of the kind grammar (`>=1.0.0`, `1.x`, `latest`) is rejected here rather than\n * reaching resolution. Note the deliberate divergence from\n * `tools/block-tools`'s `parseSelector`, which additionally tolerates a leading\n * `@` as `exact`: after the `{name}@{selector}` split a leading `@` can only\n * come from a doubled separator, which is malformed.\n *\n * Mapping a selector onto a concrete version is resolution, not parsing, and\n * lives with the resolver (`kind_resolver.selectorToRange`).\n *\n * @throws if the version part is not `X.Y.Z`\n */\nexport function parseKindSelector(raw: string): KindSelector {\n  const s = raw.trim();\n  const op: KindSelectorOp = s.startsWith(\"~\") ? \"patch\" : s.startsWith(\"^\") ? \"minor\" : \"exact\";\n  const version = op === \"exact\" ? s : s.slice(1);\n  if (!semVerRegex.test(version)) {\n    throw new Error(\n      `Malformed kind version selector (expected 'X.Y.Z', '~X.Y.Z' or '^X.Y.Z'): ${raw}`,\n    );\n  }\n  return { op, version };\n}\n\n/** Render a {@link KindSelector} back to its on-wire string. */\nexport function formatKindSelector(sel: KindSelector): string {\n  switch (sel.op) {\n    case \"exact\":\n      return sel.version;\n    case \"patch\":\n      return `~${sel.version}`;\n    case \"minor\":\n      return `^${sel.version}`;\n  }\n}\n\n/**\n * Split a {@link BlockKindSelectorReference} into `{ name, selector }`.\n *\n * @throws if the reference carries no version segment, or the selector is\n *   outside the `X.Y.Z` / `~X.Y.Z` / `^X.Y.Z` grammar\n */\nexport function parseKindSelectorReference(ref: BlockKindSelectorReference): {\n  name: string;\n  selector: KindSelector;\n} {\n  const { name, version } = splitVersionedName(ref, \"kind selector reference\", \"{name}@{selector}\");\n  return { name, selector: parseKindSelector(version) };\n}\n\n/**\n * Compose a {@link BlockKindSelectorReference} from a name and selector.\n *\n * A formatter, not a validator — pass a selector that came from\n * {@link parseKindSelector} or that you constructed from a known-good version.\n */\nexport function formatKindSelectorReference(k: {\n  name: string;\n  selector: KindSelector;\n}): BlockKindSelectorReference {\n  return `${k.name}@${formatKindSelector(k.selector)}` as BlockKindSelectorReference;\n}\n\n/**\n * Widen a resolved {@link BlockKindReference} to its `exact`-tier selector form.\n *\n * The export direction: a block implements exactly one kind version, so export\n * always emits `{name}@X.Y.Z`. Validates on the way through, so a\n * malformed stored reference fails at the boundary rather than in the file.\n */\nexport function kindReferenceToSelectorReference(\n  ref: BlockKindReference,\n): BlockKindSelectorReference {\n  const { name, version } = parseKindRef(ref);\n  return formatKindSelectorReference({ name, selector: parseKindSelector(version) });\n}\n\n/** Whether `value` is a well-formed `{name}@{selector}` string. */\nexport function isBlockKindSelectorReference(value: unknown): value is BlockKindSelectorReference {\n  if (typeof value !== \"string\") return false;\n  try {\n    parseKindSelectorReference(value as BlockKindSelectorReference);\n    return true;\n  } catch {\n    return false;\n  }\n}\n"],"mappings":";;;AAiCA,MAAM,cACJ;;;;;;;;;;;;;;;;AAiBF,SAAgB,kBAAkB,KAA2B;CAC3D,MAAM,IAAI,IAAI,KAAK;CACnB,MAAM,KAAqB,EAAE,WAAW,GAAG,IAAI,UAAU,EAAE,WAAW,GAAG,IAAI,UAAU;CACvF,MAAM,UAAU,OAAO,UAAU,IAAI,EAAE,MAAM,CAAC;CAC9C,IAAI,CAAC,YAAY,KAAK,OAAO,GAC3B,MAAM,IAAI,MACR,6EAA6E,KAC/E;CAEF,OAAO;EAAE;EAAI;CAAQ;AACvB;;AAGA,SAAgB,mBAAmB,KAA2B;CAC5D,QAAQ,IAAI,IAAZ;EACE,KAAK,SACH,OAAO,IAAI;EACb,KAAK,SACH,OAAO,IAAI,IAAI;EACjB,KAAK,SACH,OAAO,IAAI,IAAI;CACnB;AACF;;;;;;;AAQA,SAAgB,2BAA2B,KAGzC;CACA,MAAM,EAAE,MAAM,YAAY,mBAAmB,KAAK,2BAA2B,mBAAmB;CAChG,OAAO;EAAE;EAAM,UAAU,kBAAkB,OAAO;CAAE;AACtD;;;;;;;AAQA,SAAgB,4BAA4B,GAGb;CAC7B,OAAO,GAAG,EAAE,KAAK,GAAG,mBAAmB,EAAE,QAAQ;AACnD;;;;;;;;AASA,SAAgB,iCACd,KAC4B;CAC5B,MAAM,EAAE,MAAM,YAAY,aAAa,GAAG;CAC1C,OAAO,4BAA4B;EAAE;EAAM,UAAU,kBAAkB,OAAO;CAAE,CAAC;AACnF;;AAGA,SAAgB,6BAA6B,OAAqD;CAChG,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,IAAI;EACF,2BAA2B,KAAmC;EAC9D,OAAO;CACT,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/template/project_template_v1.cjs

@@ -0,0 +1,231 @@
+const require_block_kind_ref = require("../bmodel/block_kind_ref.cjs");
+const require_kind_selector = require("./kind_selector.cjs");
+//#region src/template/project_template_v1.ts
+/**
+* Value of a template file's `schema` field — the format marker every
+* `template-v1` document opens with.
+*/
+const PROJECT_TEMPLATE_SCHEMA_V1 = "template-v1";
+/**
+* Split a {@link BlockPackReference} into `{ name, version }`.
+*
+* @throws if the reference carries no version segment or the version is not
+*   exactly `X.Y.Z`
+*/
+function parseBlockPackReference(ref) {
+	const { name, version } = require_block_kind_ref.splitVersionedName(ref, "block package reference", "{name}@X.Y.Z");
+	const selector = require_kind_selector.parseKindSelector(version);
+	if (selector.op !== "exact") throw new Error(`A 'block' override must pin an exact version (expected '{name}@X.Y.Z'): ${ref}`);
+	return {
+		name,
+		version: selector.version
+	};
+}
+/**
+* Read the scheme off a {@link BlockPackLocationReference}, which is all the
+* document layer knows about it — resolving the rest belongs to whoever can reach
+* the scheme.
+*
+* A scheme is required. Accepting a bare path would mean reading it relative to
+* whatever directory the application happens to have been started from, which is
+* exactly the ambiguity a locator exists to remove.
+*
+* @throws if the value carries no scheme
+*/
+function parseBlockPackLocation(ref) {
+	const match = LocationSchemePattern.exec(ref);
+	if (!match) throw new Error(`A 'location' must be an absolute URI with a scheme (expected e.g. 'file:///path/to/block'), got: ${ref}`);
+	return { scheme: match.groups.scheme.toLowerCase() };
+}
+/**
+* Scheme grammar, with one deliberate narrowing: a scheme is at least TWO
+* characters, while the URI grammar allows one.
+*
+* `C:\blocks\my-block` is a valid single-letter-scheme URI, so a Windows path
+* pasted into the field would otherwise be accepted with scheme `c` and then fail
+* far away from the mistake. Rejecting it here means the error names the actual
+* problem, and the fix — `file:///C:/blocks/my-block` — is spelled out.
+*/
+const LocationSchemePattern = /^(?<scheme>[A-Za-z][A-Za-z0-9+.-]+):/;
+/**
+* One issue as a line: `blocks[2].kind: Expected a kind reference, got nothing.`
+*
+* Indexes read as they are written in the file — `blocks[2]`, not `blocks.2` — so the place
+* can be found by reading rather than by counting.
+*/
+function formatTemplateParseIssue(issue) {
+	const path = issue.path.reduce((acc, segment) => typeof segment === "number" ? `${acc}[${segment}]` : acc === "" ? segment : `${acc}.${segment}`, "");
+	return path === "" ? issue.message : `${path}: ${issue.message}`;
+}
+/**
+* Every problem a document has, thrown once so a caller fixes the file in one pass.
+*
+* The issues are in `message` as well as on `issues`, because a throw that escapes to a log is
+* read as its message and nothing else.
+*/
+var ProjectTemplateV1ParseError = class extends Error {
+	issues;
+	constructor(issues) {
+		super([`The template document could not be read (${issues.length} problem(s)):`, ...issues.map((issue) => `- ${formatTemplateParseIssue(issue)}`)].join("\n"));
+		this.issues = issues;
+		this.name = "ProjectTemplateV1ParseError";
+	}
+};
+const isMapping = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Keys an entry may carry. Anything else is a mistake, not an extension point. */
+const ENTRY_KEYS = [
+	"id",
+	"kind",
+	"block",
+	"location",
+	"params"
+];
+/**
+* Read an already-decoded template document — the value a YAML or JSON reader returns.
+*
+* Checks the format marker, every entry's shape, the reference grammars and id uniqueness,
+* and settles an omitted `params` to `{}`. Unknown keys are refused rather than ignored: a
+* misspelled key that was silently dropped would apply a file that does not say what its
+* author meant.
+*
+* It does NOT check what an entry's params point at, and nothing downstream of it does
+* either. Which values in there carry block ids is knowable only to the block, in its own
+* bundle, where the params are relocated onto the project being built — so a reference to an
+* entry listed later, or to the entry holding it, is not refused here. It survives into the
+* applied project as a block whose references name nothing, which is how a reference to a
+* deleted block already behaves.
+*
+* Collects rather than stops: a file with three mistakes should take one pass to fix.
+*/
+function readProjectTemplateV1(value) {
+	const issues = [];
+	const fail = (path, message) => issues.push({
+		path,
+		message
+	});
+	if (!isMapping(value)) return {
+		ok: false,
+		issues: [{
+			path: [],
+			message: "A template must be a mapping with 'schema' and 'blocks'."
+		}]
+	};
+	for (const key of Object.keys(value)) if (key !== "schema" && key !== "blocks") fail([], `Unrecognized key: '${key}'`);
+	if (value.schema !== "template-v1") fail(["schema"], `Expected '${PROJECT_TEMPLATE_SCHEMA_V1}', got ${describe(value.schema)}. This is the format marker every template opens with.`);
+	if (!Array.isArray(value.blocks)) {
+		fail(["blocks"], `Expected a list of entries, got ${describe(value.blocks)}.`);
+		return {
+			ok: false,
+			issues
+		};
+	}
+	const blocks = [];
+	const seen = /* @__PURE__ */ new Set();
+	value.blocks.forEach((raw, i) => {
+		const entry = readEntry(raw, ["blocks", i], fail);
+		if (entry === void 0) return;
+		if (seen.has(entry.id)) fail([
+			"blocks",
+			i,
+			"id"
+		], `Duplicate template-local id: ${entry.id}`);
+		seen.add(entry.id);
+		blocks.push(entry);
+	});
+	if (issues.length > 0) return {
+		ok: false,
+		issues
+	};
+	return {
+		ok: true,
+		document: {
+			schema: PROJECT_TEMPLATE_SCHEMA_V1,
+			blocks
+		}
+	};
+}
+/**
+* One entry, or `undefined` when it is not even a mapping — in which case its own fields are
+* not reported on top, since a reader given "this entry is not a mapping" does not also need
+* to hear that its `id` is missing.
+*/
+function readEntry(raw, at, fail) {
+	if (!isMapping(raw)) {
+		fail(at, `Expected an entry mapping, got ${describe(raw)}.`);
+		return;
+	}
+	for (const key of Object.keys(raw)) if (!ENTRY_KEYS.includes(key)) fail(at, `Unrecognized key: '${key}'`);
+	let ok = true;
+	if (typeof raw.id !== "string" || raw.id.length === 0) {
+		fail([...at, "id"], `Expected a non-empty id, got ${describe(raw.id)}.`);
+		ok = false;
+	}
+	if (typeof raw.kind !== "string") {
+		fail([...at, "kind"], `Expected a kind reference, got ${describe(raw.kind)}.`);
+		ok = false;
+	} else ok = check([...at, "kind"], () => require_kind_selector.parseKindSelectorReference(raw.kind), fail) && ok;
+	if (raw.block !== void 0) if (typeof raw.block !== "string") {
+		fail([...at, "block"], `Expected a block package reference, got ${describe(raw.block)}.`);
+		ok = false;
+	} else ok = check([...at, "block"], () => parseBlockPackReference(raw.block), fail) && ok;
+	if (raw.location !== void 0) if (typeof raw.location !== "string") {
+		fail([...at, "location"], `Expected a locator URI, got ${describe(raw.location)}.`);
+		ok = false;
+	} else ok = check([...at, "location"], () => parseBlockPackLocation(raw.location), fail) && ok;
+	if (raw.block !== void 0 && raw.location !== void 0) {
+		fail([...at, "location"], "An entry cannot carry both 'block' and 'location': the first pins which version to install, the second pins where to install it from. Keep the one that is actually meant.");
+		ok = false;
+	}
+	if (raw.params !== void 0 && !isMapping(raw.params)) {
+		fail([...at, "params"], `Expected a mapping of params, got ${describe(raw.params)}.`);
+		ok = false;
+	}
+	if (!ok) return void 0;
+	return {
+		id: raw.id,
+		kind: raw.kind,
+		...raw.block !== void 0 ? { block: raw.block } : {},
+		...raw.location !== void 0 ? { location: raw.location } : {},
+		params: raw.params ?? {}
+	};
+}
+/** Run a grammar check, turning its throw into an issue at `path`. */
+function check(path, grammar, fail) {
+	try {
+		grammar();
+		return true;
+	} catch (e) {
+		fail(path, e instanceof Error ? e.message : String(e));
+		return false;
+	}
+}
+/** A value named the way an error message should name it, without printing its contents. */
+function describe(value) {
+	if (value === void 0) return "nothing";
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "a list";
+	if (typeof value === "string") return `'${value}'`;
+	if (typeof value === "object") return "a mapping";
+	return String(value);
+}
+/**
+* {@link readProjectTemplateV1} for a caller that treats an unreadable document as
+* exceptional — export, which asserts on every run that what it wrote can be read back.
+*
+* @throws {ProjectTemplateV1ParseError} carrying every problem found
+*/
+function parseProjectTemplateV1(value) {
+	const outcome = readProjectTemplateV1(value);
+	if (!outcome.ok) throw new ProjectTemplateV1ParseError(outcome.issues);
+	return outcome.document;
+}
+//#endregion
+exports.PROJECT_TEMPLATE_SCHEMA_V1 = PROJECT_TEMPLATE_SCHEMA_V1;
+exports.ProjectTemplateV1ParseError = ProjectTemplateV1ParseError;
+exports.formatTemplateParseIssue = formatTemplateParseIssue;
+exports.parseBlockPackLocation = parseBlockPackLocation;
+exports.parseBlockPackReference = parseBlockPackReference;
+exports.parseProjectTemplateV1 = parseProjectTemplateV1;
+exports.readProjectTemplateV1 = readProjectTemplateV1;
+
+//# sourceMappingURL=project_template_v1.cjs.map

package/dist/template/project_template_v1.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"project_template_v1.cjs","names":["splitVersionedName","parseKindSelector","parseKindSelectorReference"],"sources":["../../src/template/project_template_v1.ts"],"sourcesContent":["import type { Branded } from \"@milaboratories/helpers\";\nimport { splitVersionedName } from \"../bmodel/block_kind_ref\";\nimport type { BlockKindSelectorReference } from \"./kind_selector\";\nimport { parseKindSelector, parseKindSelectorReference } from \"./kind_selector\";\n\n/**\n * Value of a template file's `schema` field — the format marker every\n * `template-v1` document opens with.\n */\nexport const PROJECT_TEMPLATE_SCHEMA_V1 = \"template-v1\";\nexport type ProjectTemplateSchemaV1 = typeof PROJECT_TEMPLATE_SCHEMA_V1;\n\n/**\n * On-wire reference to one exact block package version, `{name}@X.Y.Z`.\n *\n * The `block` override's value type. Exact only — the override exists to pin an\n * implementation, so a range would defeat it. Mapping this to the structured\n * `BlockPackId` (`{ organization, name, version }`) is import-side work; the\n * organization lives inside the npm scope here, as it does for kind names.\n */\nexport type BlockPackReference = Branded<string, \"BlockPackReference\">;\n\n/**\n * Split a {@link BlockPackReference} into `{ name, version }`.\n *\n * @throws if the reference carries no version segment or the version is not\n *   exactly `X.Y.Z`\n */\nexport function parseBlockPackReference(ref: BlockPackReference): {\n  name: string;\n  version: string;\n} {\n  const { name, version } = splitVersionedName(ref, \"block package reference\", \"{name}@X.Y.Z\");\n  const selector = parseKindSelector(version);\n  if (selector.op !== \"exact\") {\n    throw new Error(\n      `A 'block' override must pin an exact version (expected '{name}@X.Y.Z'): ${ref}`,\n    );\n  }\n  return { name, version: selector.version };\n}\n\n/**\n * On-wire locator naming WHERE one entry's block implementation comes from, as an\n * absolute URI: `file:///abs/path/to/block`.\n *\n * The third way an entry can reach an implementation, and the only one that names a\n * place rather than a name. It exists for a block that is built but not published —\n * the implementation lives in a folder and no registry knows it, so neither `kind`\n * resolution nor a `block` version pin can find it.\n *\n * A URI rather than a bare path because the question \"where\" is not limited to the\n * filesystem, and because scheme dispatch is how the rest of the toolchain already\n * answers it. Which schemes an environment can actually serve is that environment's\n * business: this type fixes only the grammar, so a document remains readable by a\n * consumer that cannot fetch every scheme.\n */\nexport type BlockPackLocationReference = Branded<string, \"BlockPackLocationReference\">;\n\n/**\n * Read the scheme off a {@link BlockPackLocationReference}, which is all the\n * document layer knows about it — resolving the rest belongs to whoever can reach\n * the scheme.\n *\n * A scheme is required. Accepting a bare path would mean reading it relative to\n * whatever directory the application happens to have been started from, which is\n * exactly the ambiguity a locator exists to remove.\n *\n * @throws if the value carries no scheme\n */\nexport function parseBlockPackLocation(ref: BlockPackLocationReference): { scheme: string } {\n  const match = LocationSchemePattern.exec(ref);\n  if (!match) {\n    throw new Error(\n      `A 'location' must be an absolute URI with a scheme (expected e.g. ` +\n        `'file:///path/to/block'), got: ${ref}`,\n    );\n  }\n  return { scheme: match.groups!.scheme.toLowerCase() };\n}\n\n/**\n * Scheme grammar, with one deliberate narrowing: a scheme is at least TWO\n * characters, while the URI grammar allows one.\n *\n * `C:\\blocks\\my-block` is a valid single-letter-scheme URI, so a Windows path\n * pasted into the field would otherwise be accepted with scheme `c` and then fail\n * far away from the mistake. Rejecting it here means the error names the actual\n * problem, and the fix — `file:///C:/blocks/my-block` — is spelled out.\n */\nconst LocationSchemePattern = /^(?<scheme>[A-Za-z][A-Za-z0-9+.-]+):/;\n\n/**\n * One block in a template file.\n *\n * `kind` is always required: it carries the params contract the entry is typed against, and\n * whichever of the three routes finds the block, what that block declares is checked against\n * it — so params written for one contract cannot reach an implementation of another.\n *\n * A file may omit `params`, which is terseness and not an escape from the contract: the parser\n * reads the omission as `{}`, so an entry that leaves it out still fails for a kind whose\n * contract has required fields. Past the parser there is only one spelling, and no reader has\n * to normalize. There is no `label` field: a template\n * does not name block instances for display.\n *\n * An entry may also carry one locator override — see {@link BlockPackLocatorOverride} for\n * what each answers. Either one is resolved on its own and kind resolution is skipped\n * entirely; carrying both would state two different things with no way to reconcile them, so\n * the type admits at most one.\n */\nexport type ProjectTemplateV1Entry = {\n  /**\n   * Template-local identifier, unique within the file. Names the entry for\n   * inter-block references; on export it is the block's project-local UUID,\n   * reused verbatim.\n   */\n  readonly id: string;\n  readonly kind: BlockKindSelectorReference;\n  /**\n   * The block's `BlockParams` instance, exactly as the block projected it — opaque here\n   * and typed by the kind. Always present: an entry whose file omitted it parses as `{}`.\n   *\n   * **Nothing here looks inside.** Not for a reference, not for a marker: values travel from\n   * the block that projected them to the block that receives them verbatim, and which of them\n   * carry block ids is recognized in the receiving block's own bundle. A document layer that\n   * recognized a reference would have to model the whole reference system to do it.\n   *\n   * That is also what lets a hand-written file spell a reference readably. A block stores\n   * `{ __isRef: true, blockId, name }` and an export writes that, but a person may write\n   * `{ block: <entry id>, name: … }` instead — see `TemplatePlRef`. Both arrive at the block as\n   * the same reference; neither is understood here.\n   */\n  readonly params: Record<string, unknown>;\n} & BlockPackLocatorOverride;\n\n/**\n * The locator override an entry may carry: a version pin, a place, or neither.\n *\n * Two arms rather than two optional fields, so \"not both\" is a property of the type and not\n * only of the parser. Each arm forbids the other's field by typing it `never`, which is what\n * makes `{ block, location }` match neither — and both arms leave their own field optional, so\n * an entry that pins nothing satisfies either.\n *\n * Readers are unaffected: every arm declares both keys, so `entry.block` and `entry.location`\n * stay directly readable without narrowing.\n */\nexport type BlockPackLocatorOverride =\n  | {\n      /**\n       * WHICH VERSION to install, leaving it to the environment to decide which registry\n       * serves it — so an entry pinned this way stays portable.\n       *\n       * Exact only, `{name}@X.Y.Z` (see {@link BlockPackReference}): the override exists to\n       * pin one implementation, and a range would defeat that. Export never writes it, because\n       * it already records the exact version the block implements, leaving a pin nothing to\n       * add — so this is a hand-written field.\n       */\n      readonly block?: BlockPackReference;\n      /** Excluded: this arm is the version pin. */\n      readonly location?: never;\n    }\n  | {\n      /** Excluded: this arm is the place. */\n      readonly block?: never;\n      /**\n       * WHICH PLACE to install from, as an absolute URI (see\n       * {@link BlockPackLocationReference}).\n       *\n       * Names a concrete, possibly unpublished implementation, and is therefore only\n       * meaningful where that place exists: a `file:` locator written on one machine says\n       * nothing on another. That is the trade it makes — it is the only answer for a block\n       * that is built but not published, which no registry can find and no kind can resolve\n       * to. Export writes it for every block installed from the filesystem, since omitting it\n       * would describe a project that cannot be recreated at all.\n       */\n      readonly location?: BlockPackLocationReference;\n    };\n\n/**\n * A `template-v1` document — the primitive form of a template.\n *\n * `blocks` order is the instantiation order, so every entry must appear after\n * the entries it references. This type is the shared contract for both\n * directions of the round trip: export emits exactly this, import parses\n * exactly this.\n *\n * Scope note: this package owns the *document*, i.e. the shape of the value a\n * YAML (or JSON) reader hands back. The text layer stays out on purpose —\n * pl-model-common is in every block-model and UI bundle and takes no `yaml`\n * dependency; serializing to YAML bytes belongs with the caller that already\n * has one (pl-middle-layer).\n */\nexport type ProjectTemplateV1 = {\n  readonly schema: ProjectTemplateSchemaV1;\n  readonly blocks: readonly ProjectTemplateV1Entry[];\n};\n\n//\n// Reading a decoded document.\n//\n// Hand-written rather than schema-driven, for what a reader of a hand-written file gets out\n// of it. A template is a file a person edits, so the parser's output is a bug report: every\n// problem at once, each located the way the file is written, worded as the edit to make. That\n// means owning the wording, which a schema library gives away — and the values here need\n// checks a schema cannot express anyway (the reference grammars are functions, and the locator\n// exclusion is a rule about two fields), so the schema was carrying the trivial half while the\n// interesting half sat in refinements beside it.\n//\n\n/** One thing wrong with a document, and where in it. */\nexport type TemplateParseIssue = {\n  /** Location in the decoded value: `[\"blocks\", 2, \"kind\"]`. */\n  readonly path: readonly (string | number)[];\n  /** What is wrong, worded for whoever is editing the file. */\n  readonly message: string;\n};\n\n/**\n * One issue as a line: `blocks[2].kind: Expected a kind reference, got nothing.`\n *\n * Indexes read as they are written in the file — `blocks[2]`, not `blocks.2` — so the place\n * can be found by reading rather than by counting.\n */\nexport function formatTemplateParseIssue(issue: TemplateParseIssue): string {\n  const path = issue.path.reduce<string>(\n    (acc, segment) =>\n      typeof segment === \"number\"\n        ? `${acc}[${segment}]`\n        : acc === \"\"\n          ? segment\n          : `${acc}.${segment}`,\n    \"\",\n  );\n  return path === \"\" ? issue.message : `${path}: ${issue.message}`;\n}\n\n/**\n * Every problem a document has, thrown once so a caller fixes the file in one pass.\n *\n * The issues are in `message` as well as on `issues`, because a throw that escapes to a log is\n * read as its message and nothing else.\n */\nexport class ProjectTemplateV1ParseError extends Error {\n  constructor(readonly issues: readonly TemplateParseIssue[]) {\n    super(\n      [\n        `The template document could not be read (${issues.length} problem(s)):`,\n        ...issues.map((issue) => `- ${formatTemplateParseIssue(issue)}`),\n      ].join(\"\\n\"),\n    );\n    this.name = \"ProjectTemplateV1ParseError\";\n  }\n}\n\n/** A document, or everything wrong with the value that was supposed to be one. */\nexport type ProjectTemplateV1ReadResult =\n  | { readonly ok: true; readonly document: ProjectTemplateV1 }\n  | { readonly ok: false; readonly issues: readonly TemplateParseIssue[] };\n\nconst isMapping = (value: unknown): value is Record<string, unknown> =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value);\n\n/** Keys an entry may carry. Anything else is a mistake, not an extension point. */\nconst ENTRY_KEYS = [\"id\", \"kind\", \"block\", \"location\", \"params\"] as const;\n\n/**\n * Read an already-decoded template document — the value a YAML or JSON reader returns.\n *\n * Checks the format marker, every entry's shape, the reference grammars and id uniqueness,\n * and settles an omitted `params` to `{}`. Unknown keys are refused rather than ignored: a\n * misspelled key that was silently dropped would apply a file that does not say what its\n * author meant.\n *\n * It does NOT check what an entry's params point at, and nothing downstream of it does\n * either. Which values in there carry block ids is knowable only to the block, in its own\n * bundle, where the params are relocated onto the project being built — so a reference to an\n * entry listed later, or to the entry holding it, is not refused here. It survives into the\n * applied project as a block whose references name nothing, which is how a reference to a\n * deleted block already behaves.\n *\n * Collects rather than stops: a file with three mistakes should take one pass to fix.\n */\nexport function readProjectTemplateV1(value: unknown): ProjectTemplateV1ReadResult {\n  const issues: TemplateParseIssue[] = [];\n  const fail = (path: readonly (string | number)[], message: string) =>\n    issues.push({ path, message });\n\n  if (!isMapping(value)) {\n    return {\n      ok: false,\n      issues: [{ path: [], message: \"A template must be a mapping with 'schema' and 'blocks'.\" }],\n    };\n  }\n\n  for (const key of Object.keys(value)) {\n    if (key !== \"schema\" && key !== \"blocks\") fail([], `Unrecognized key: '${key}'`);\n  }\n\n  if (value.schema !== PROJECT_TEMPLATE_SCHEMA_V1) {\n    fail(\n      [\"schema\"],\n      `Expected '${PROJECT_TEMPLATE_SCHEMA_V1}', got ${describe(value.schema)}. This is the ` +\n        `format marker every template opens with.`,\n    );\n  }\n\n  if (!Array.isArray(value.blocks)) {\n    fail([\"blocks\"], `Expected a list of entries, got ${describe(value.blocks)}.`);\n    return { ok: false, issues };\n  }\n\n  const blocks: ProjectTemplateV1Entry[] = [];\n  const seen = new Set<string>();\n\n  value.blocks.forEach((raw, i) => {\n    const entry = readEntry(raw, [\"blocks\", i], fail);\n    if (entry === undefined) return;\n    if (seen.has(entry.id)) fail([\"blocks\", i, \"id\"], `Duplicate template-local id: ${entry.id}`);\n    seen.add(entry.id);\n    blocks.push(entry);\n  });\n\n  if (issues.length > 0) return { ok: false, issues };\n  return { ok: true, document: { schema: PROJECT_TEMPLATE_SCHEMA_V1, blocks } };\n}\n\n/**\n * One entry, or `undefined` when it is not even a mapping — in which case its own fields are\n * not reported on top, since a reader given \"this entry is not a mapping\" does not also need\n * to hear that its `id` is missing.\n */\nfunction readEntry(\n  raw: unknown,\n  at: readonly (string | number)[],\n  fail: (path: readonly (string | number)[], message: string) => void,\n): ProjectTemplateV1Entry | undefined {\n  if (!isMapping(raw)) {\n    fail(at, `Expected an entry mapping, got ${describe(raw)}.`);\n    return undefined;\n  }\n\n  for (const key of Object.keys(raw)) {\n    if (!(ENTRY_KEYS as readonly string[]).includes(key)) {\n      fail(at, `Unrecognized key: '${key}'`);\n    }\n  }\n\n  let ok = true;\n\n  if (typeof raw.id !== \"string\" || raw.id.length === 0) {\n    fail([...at, \"id\"], `Expected a non-empty id, got ${describe(raw.id)}.`);\n    ok = false;\n  }\n\n  if (typeof raw.kind !== \"string\") {\n    fail([...at, \"kind\"], `Expected a kind reference, got ${describe(raw.kind)}.`);\n    ok = false;\n  } else {\n    // The grammars are functions, and their messages already name the fix, so they are\n    // reported as they come rather than restated.\n    ok = check([...at, \"kind\"], () => parseKindSelectorReference(raw.kind as never), fail) && ok;\n  }\n\n  if (raw.block !== undefined) {\n    if (typeof raw.block !== \"string\") {\n      fail([...at, \"block\"], `Expected a block package reference, got ${describe(raw.block)}.`);\n      ok = false;\n    } else {\n      ok = check([...at, \"block\"], () => parseBlockPackReference(raw.block as never), fail) && ok;\n    }\n  }\n\n  if (raw.location !== undefined) {\n    if (typeof raw.location !== \"string\") {\n      fail([...at, \"location\"], `Expected a locator URI, got ${describe(raw.location)}.`);\n      ok = false;\n    } else {\n      ok =\n        check([...at, \"location\"], () => parseBlockPackLocation(raw.location as never), fail) && ok;\n    }\n  }\n\n  if (raw.block !== undefined && raw.location !== undefined) {\n    fail(\n      [...at, \"location\"],\n      `An entry cannot carry both 'block' and 'location': the first pins which version to ` +\n        `install, the second pins where to install it from. Keep the one that is actually meant.`,\n    );\n    ok = false;\n  }\n\n  if (raw.params !== undefined && !isMapping(raw.params)) {\n    fail([...at, \"params\"], `Expected a mapping of params, got ${describe(raw.params)}.`);\n    ok = false;\n  }\n\n  if (!ok) return undefined;\n\n  return {\n    id: raw.id as string,\n    kind: raw.kind as BlockKindSelectorReference,\n    ...(raw.block !== undefined ? { block: raw.block as BlockPackReference } : {}),\n    ...(raw.location !== undefined ? { location: raw.location as BlockPackLocationReference } : {}),\n    // Omissible in the file, settled here: every reader downstream gets a mapping.\n    params: (raw.params ?? {}) as Record<string, unknown>,\n  } as ProjectTemplateV1Entry;\n}\n\n/** Run a grammar check, turning its throw into an issue at `path`. */\nfunction check(\n  path: readonly (string | number)[],\n  grammar: () => unknown,\n  fail: (path: readonly (string | number)[], message: string) => void,\n): boolean {\n  try {\n    grammar();\n    return true;\n  } catch (e) {\n    fail(path, e instanceof Error ? e.message : String(e));\n    return false;\n  }\n}\n\n/** A value named the way an error message should name it, without printing its contents. */\nfunction describe(value: unknown): string {\n  if (value === undefined) return \"nothing\";\n  if (value === null) return \"null\";\n  if (Array.isArray(value)) return \"a list\";\n  if (typeof value === \"string\") return `'${value}'`;\n  if (typeof value === \"object\") return \"a mapping\";\n  return String(value);\n}\n\n/**\n * {@link readProjectTemplateV1} for a caller that treats an unreadable document as\n * exceptional — export, which asserts on every run that what it wrote can be read back.\n *\n * @throws {ProjectTemplateV1ParseError} carrying every problem found\n */\nexport function parseProjectTemplateV1(value: unknown): ProjectTemplateV1 {\n  const outcome = readProjectTemplateV1(value);\n  if (!outcome.ok) throw new ProjectTemplateV1ParseError(outcome.issues);\n  return outcome.document;\n}\n"],"mappings":"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"}

package/dist/template/project_template_v1.d.ts

@@ -0,0 +1,215 @@
+import { BlockKindSelectorReference } from "./kind_selector.js";
+import { Branded } from "@milaboratories/helpers";
+
+//#region src/template/project_template_v1.d.ts
+/**
+ * Value of a template file's `schema` field — the format marker every
+ * `template-v1` document opens with.
+ */
+declare const PROJECT_TEMPLATE_SCHEMA_V1 = "template-v1";
+type ProjectTemplateSchemaV1 = typeof PROJECT_TEMPLATE_SCHEMA_V1;
+/**
+ * On-wire reference to one exact block package version, `{name}@X.Y.Z`.
+ *
+ * The `block` override's value type. Exact only — the override exists to pin an
+ * implementation, so a range would defeat it. Mapping this to the structured
+ * `BlockPackId` (`{ organization, name, version }`) is import-side work; the
+ * organization lives inside the npm scope here, as it does for kind names.
+ */
+type BlockPackReference = Branded<string, "BlockPackReference">;
+/**
+ * Split a {@link BlockPackReference} into `{ name, version }`.
+ *
+ * @throws if the reference carries no version segment or the version is not
+ *   exactly `X.Y.Z`
+ */
+declare function parseBlockPackReference(ref: BlockPackReference): {
+  name: string;
+  version: string;
+};
+/**
+ * On-wire locator naming WHERE one entry's block implementation comes from, as an
+ * absolute URI: `file:///abs/path/to/block`.
+ *
+ * The third way an entry can reach an implementation, and the only one that names a
+ * place rather than a name. It exists for a block that is built but not published —
+ * the implementation lives in a folder and no registry knows it, so neither `kind`
+ * resolution nor a `block` version pin can find it.
+ *
+ * A URI rather than a bare path because the question "where" is not limited to the
+ * filesystem, and because scheme dispatch is how the rest of the toolchain already
+ * answers it. Which schemes an environment can actually serve is that environment's
+ * business: this type fixes only the grammar, so a document remains readable by a
+ * consumer that cannot fetch every scheme.
+ */
+type BlockPackLocationReference = Branded<string, "BlockPackLocationReference">;
+/**
+ * Read the scheme off a {@link BlockPackLocationReference}, which is all the
+ * document layer knows about it — resolving the rest belongs to whoever can reach
+ * the scheme.
+ *
+ * A scheme is required. Accepting a bare path would mean reading it relative to
+ * whatever directory the application happens to have been started from, which is
+ * exactly the ambiguity a locator exists to remove.
+ *
+ * @throws if the value carries no scheme
+ */
+declare function parseBlockPackLocation(ref: BlockPackLocationReference): {
+  scheme: string;
+};
+/**
+ * One block in a template file.
+ *
+ * `kind` is always required: it carries the params contract the entry is typed against, and
+ * whichever of the three routes finds the block, what that block declares is checked against
+ * it — so params written for one contract cannot reach an implementation of another.
+ *
+ * A file may omit `params`, which is terseness and not an escape from the contract: the parser
+ * reads the omission as `{}`, so an entry that leaves it out still fails for a kind whose
+ * contract has required fields. Past the parser there is only one spelling, and no reader has
+ * to normalize. There is no `label` field: a template
+ * does not name block instances for display.
+ *
+ * An entry may also carry one locator override — see {@link BlockPackLocatorOverride} for
+ * what each answers. Either one is resolved on its own and kind resolution is skipped
+ * entirely; carrying both would state two different things with no way to reconcile them, so
+ * the type admits at most one.
+ */
+type ProjectTemplateV1Entry = {
+  /**
+   * Template-local identifier, unique within the file. Names the entry for
+   * inter-block references; on export it is the block's project-local UUID,
+   * reused verbatim.
+   */
+  readonly id: string;
+  readonly kind: BlockKindSelectorReference;
+  /**
+   * The block's `BlockParams` instance, exactly as the block projected it — opaque here
+   * and typed by the kind. Always present: an entry whose file omitted it parses as `{}`.
+   *
+   * **Nothing here looks inside.** Not for a reference, not for a marker: values travel from
+   * the block that projected them to the block that receives them verbatim, and which of them
+   * carry block ids is recognized in the receiving block's own bundle. A document layer that
+   * recognized a reference would have to model the whole reference system to do it.
+   *
+   * That is also what lets a hand-written file spell a reference readably. A block stores
+   * `{ __isRef: true, blockId, name }` and an export writes that, but a person may write
+   * `{ block: <entry id>, name: … }` instead — see `TemplatePlRef`. Both arrive at the block as
+   * the same reference; neither is understood here.
+   */
+  readonly params: Record<string, unknown>;
+} & BlockPackLocatorOverride;
+/**
+ * The locator override an entry may carry: a version pin, a place, or neither.
+ *
+ * Two arms rather than two optional fields, so "not both" is a property of the type and not
+ * only of the parser. Each arm forbids the other's field by typing it `never`, which is what
+ * makes `{ block, location }` match neither — and both arms leave their own field optional, so
+ * an entry that pins nothing satisfies either.
+ *
+ * Readers are unaffected: every arm declares both keys, so `entry.block` and `entry.location`
+ * stay directly readable without narrowing.
+ */
+type BlockPackLocatorOverride = {
+  /**
+   * WHICH VERSION to install, leaving it to the environment to decide which registry
+   * serves it — so an entry pinned this way stays portable.
+   *
+   * Exact only, `{name}@X.Y.Z` (see {@link BlockPackReference}): the override exists to
+   * pin one implementation, and a range would defeat that. Export never writes it, because
+   * it already records the exact version the block implements, leaving a pin nothing to
+   * add — so this is a hand-written field.
+   */
+  readonly block?: BlockPackReference; /** Excluded: this arm is the version pin. */
+  readonly location?: never;
+} | {
+  /** Excluded: this arm is the place. */readonly block?: never;
+  /**
+   * WHICH PLACE to install from, as an absolute URI (see
+   * {@link BlockPackLocationReference}).
+   *
+   * Names a concrete, possibly unpublished implementation, and is therefore only
+   * meaningful where that place exists: a `file:` locator written on one machine says
+   * nothing on another. That is the trade it makes — it is the only answer for a block
+   * that is built but not published, which no registry can find and no kind can resolve
+   * to. Export writes it for every block installed from the filesystem, since omitting it
+   * would describe a project that cannot be recreated at all.
+   */
+  readonly location?: BlockPackLocationReference;
+};
+/**
+ * A `template-v1` document — the primitive form of a template.
+ *
+ * `blocks` order is the instantiation order, so every entry must appear after
+ * the entries it references. This type is the shared contract for both
+ * directions of the round trip: export emits exactly this, import parses
+ * exactly this.
+ *
+ * Scope note: this package owns the *document*, i.e. the shape of the value a
+ * YAML (or JSON) reader hands back. The text layer stays out on purpose —
+ * pl-model-common is in every block-model and UI bundle and takes no `yaml`
+ * dependency; serializing to YAML bytes belongs with the caller that already
+ * has one (pl-middle-layer).
+ */
+type ProjectTemplateV1 = {
+  readonly schema: ProjectTemplateSchemaV1;
+  readonly blocks: readonly ProjectTemplateV1Entry[];
+};
+/** One thing wrong with a document, and where in it. */
+type TemplateParseIssue = {
+  /** Location in the decoded value: `["blocks", 2, "kind"]`. */readonly path: readonly (string | number)[]; /** What is wrong, worded for whoever is editing the file. */
+  readonly message: string;
+};
+/**
+ * One issue as a line: `blocks[2].kind: Expected a kind reference, got nothing.`
+ *
+ * Indexes read as they are written in the file — `blocks[2]`, not `blocks.2` — so the place
+ * can be found by reading rather than by counting.
+ */
+declare function formatTemplateParseIssue(issue: TemplateParseIssue): string;
+/**
+ * Every problem a document has, thrown once so a caller fixes the file in one pass.
+ *
+ * The issues are in `message` as well as on `issues`, because a throw that escapes to a log is
+ * read as its message and nothing else.
+ */
+declare class ProjectTemplateV1ParseError extends Error {
+  readonly issues: readonly TemplateParseIssue[];
+  constructor(issues: readonly TemplateParseIssue[]);
+}
+/** A document, or everything wrong with the value that was supposed to be one. */
+type ProjectTemplateV1ReadResult = {
+  readonly ok: true;
+  readonly document: ProjectTemplateV1;
+} | {
+  readonly ok: false;
+  readonly issues: readonly TemplateParseIssue[];
+};
+/**
+ * Read an already-decoded template document — the value a YAML or JSON reader returns.
+ *
+ * Checks the format marker, every entry's shape, the reference grammars and id uniqueness,
+ * and settles an omitted `params` to `{}`. Unknown keys are refused rather than ignored: a
+ * misspelled key that was silently dropped would apply a file that does not say what its
+ * author meant.
+ *
+ * It does NOT check what an entry's params point at, and nothing downstream of it does
+ * either. Which values in there carry block ids is knowable only to the block, in its own
+ * bundle, where the params are relocated onto the project being built — so a reference to an
+ * entry listed later, or to the entry holding it, is not refused here. It survives into the
+ * applied project as a block whose references name nothing, which is how a reference to a
+ * deleted block already behaves.
+ *
+ * Collects rather than stops: a file with three mistakes should take one pass to fix.
+ */
+declare function readProjectTemplateV1(value: unknown): ProjectTemplateV1ReadResult;
+/**
+ * {@link readProjectTemplateV1} for a caller that treats an unreadable document as
+ * exceptional — export, which asserts on every run that what it wrote can be read back.
+ *
+ * @throws {ProjectTemplateV1ParseError} carrying every problem found
+ */
+declare function parseProjectTemplateV1(value: unknown): ProjectTemplateV1;
+//#endregion
+export { BlockPackLocationReference, BlockPackLocatorOverride, BlockPackReference, PROJECT_TEMPLATE_SCHEMA_V1, ProjectTemplateSchemaV1, ProjectTemplateV1, ProjectTemplateV1Entry, ProjectTemplateV1ParseError, ProjectTemplateV1ReadResult, TemplateParseIssue, formatTemplateParseIssue, parseBlockPackLocation, parseBlockPackReference, parseProjectTemplateV1, readProjectTemplateV1 };
+//# sourceMappingURL=project_template_v1.d.ts.map

package/dist/template/project_template_v1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project_template_v1.d.ts","names":[],"sources":["../../src/template/project_template_v1.ts"],"mappings":";;;;;;AASA;;cAAa,0BAAA;AAAA,KACD,uBAAA,UAAiC,0BAA0B;AADhC;AACvC;;;;AAAuE;AAUvE;;AAXuC,KAW3B,kBAAA,GAAqB,OAAO;;AAAA;AAQxC;;;;iBAAgB,uBAAA,CAAwB,GAAA,EAAK,kBAAkB;EAC7D,IAAA;EACA,OAAA;AAAA;;AAAO;AA2BT;;;;AAAgD;AAahD;;;;;;;;KAbY,0BAAA,GAA6B,OAAO;AAqDhD;;;;;;;;;;;AAAA,iBAxCgB,sBAAA,CAAuB,GAAA,EAAK,0BAA0B;EAAK,MAAA;AAAA;;AA+D/C;AAa5B;;;;;;;;;;;AA6BoD;AAiBpD;;;;KAlFY,sBAAA;EAmFO;;;;AAC+B;EAD/B,SA7ER,EAAA;EAAA,SACA,IAAA,EAAM,0BAAA;;;AAiGC;AASlB;;;;AAAkE;AAmBlE;;;;;;WA9GW,MAAA,EAAQ,MAAA;AAAA,IACf,wBAAA;;;;;;;;AA8GwD;AAY5D;;;KA7GY,wBAAA;EA8GG;;;;;;;AACuD;AAyBtE;EA1Be,SAnGA,KAAA,GAAQ,kBAAA;WAER,QAAA;AAAA;EAwRC,gDApRD,KAAA;;;AAoR0D;;;;;;;;;WAxQ1D,QAAA,GAAW,0BAA0B;AAAA;;;;;;;;;;;;;;;KAiBxC,iBAAA;EAAA,SACD,MAAA,EAAQ,uBAAA;EAAA,SACR,MAAA,WAAiB,sBAAsB;AAAA;;KAgBtC,kBAAA;yEAED,IAAA;WAEA,OAAO;AAAA;;;;;;;iBASF,wBAAA,CAAyB,KAAyB,EAAlB,kBAAkB;;;;;;;cAmBrD,2BAAA,SAAoC,KAAA;EAAA,SAC1B,MAAA,WAAiB,kBAAA;cAAjB,MAAA,WAAiB,kBAAA;AAAA;;KAY5B,2BAAA;EAAA,SACG,EAAA;EAAA,SAAmB,QAAA,EAAU,iBAAA;AAAA;EAAA,SAC7B,EAAA;EAAA,SAAoB,MAAA,WAAiB,kBAAkB;AAAA;;;;;;;;;;;;;;;;;;iBAyBtD,qBAAA,CAAsB,KAAA,YAAiB,2BAA2B;;;;;;;iBA6JlE,sBAAA,CAAuB,KAAA,YAAiB,iBAAiB"}