@samva/vite 0.7.0 → 0.8.0

package/dist/project-RON2Ei7d.js

@@ -0,0 +1,603 @@
+import { createEmailRenderer } from "./email.js";
+import { watch } from "node:fs";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { assetUrl, isAssetPath, parseBrandSpecifier, projectBrandSpecifier } from "@samva/markup/compiler";
+import { execFile } from "node:child_process";
+import { TEMPLATE_NAME_PATTERN, isTemplateDefinition, isTemplateDefinition as isTemplateDefinition$1 } from "@samva/markup/template";
+//#region src/internal/guards.ts
+/** A non-null, non-array object, narrowed for property access. */
+const isObject = (input) => typeof input === "object" && input !== null && !Array.isArray(input);
+//#endregion
+//#region src/brand.ts
+/** Where `samva brands pull` writes snapshots, relative to the project root. */
+const BRAND_SNAPSHOT_DIR = ".samva/brands";
+const SNAPSHOT_VERSION = 1;
+const DEFAULT_API_URL = "https://api.samva.dev";
+const LIVE_TIMEOUT_MS = 15e3;
+/** How long a resolution is reused, so a watch loop does not ask the API on every save. */
+const RESOLUTION_TTL_MS = 3e4;
+/** Accept only the fields a build needs, from an API body or a snapshot file. */
+const asBrand = (value) => {
+	if (!isObject(value)) return void 0;
+	const { slug, name, isDefault, css, assets, footer, digest } = value;
+	if (typeof slug !== "string" || typeof name !== "string" || typeof isDefault !== "boolean" || typeof css !== "string" || typeof digest !== "string" || assets !== void 0 && !isObject(assets) || footer !== void 0 && !isObject(footer)) return void 0;
+	return {
+		slug,
+		name,
+		isDefault,
+		css,
+		digest,
+		...assets === void 0 ? {} : { assets },
+		...footer === void 0 ? {} : { footer }
+	};
+};
+const liveFromBody = (body, when) => {
+	const brand = asBrand(body);
+	return brand === void 0 ? {
+		ok: false,
+		reason: `${when} answered with something that is not a brand`
+	} : {
+		ok: true,
+		brand: {
+			...brand,
+			version: SNAPSHOT_VERSION,
+			pulledAt: ""
+		}
+	};
+};
+const fetchJson = async (url, apiKey) => {
+	const response = await fetch(url, {
+		headers: {
+			"x-api-key": apiKey,
+			accept: "application/json"
+		},
+		signal: AbortSignal.timeout(LIVE_TIMEOUT_MS)
+	});
+	if (!response.ok) throw new Error(`${url} answered ${response.status}`);
+	return response.json();
+};
+const liveWithApiKey = async (slug, env, apiKey) => {
+	const base = (env["SAMVA_API_URL"] || DEFAULT_API_URL).replace(/\/+$/, "");
+	try {
+		if (slug !== void 0) return liveFromBody(await fetchJson(`${base}/v1/brands/${slug}`, apiKey), "The Samva API");
+		const body = await fetchJson(`${base}/v1/brands`, apiKey);
+		const found = (isObject(body) && Array.isArray(body["items"]) ? body["items"] : []).find((item) => isObject(item) && item["isDefault"] === true);
+		return found === void 0 ? {
+			ok: false,
+			reason: "the organization has no default brand"
+		} : liveFromBody(found, "The Samva API");
+	} catch (cause) {
+		return {
+			ok: false,
+			reason: `the Samva API did not answer (${cause instanceof Error ? cause.message : String(cause)})`
+		};
+	}
+};
+/** The CLI's error envelope message, or its raw stderr. */
+const cliFailure = (stderr) => {
+	const parsed = (() => {
+		try {
+			return JSON.parse(stderr);
+		} catch {
+			return;
+		}
+	})();
+	return isObject(parsed) && typeof parsed["message"] === "string" ? parsed["message"] : stderr.trim() || "it exited without a message";
+};
+const liveWithCli = (slug, env) => new Promise((resolve) => {
+	execFile("samva", [
+		"brands",
+		"get",
+		...slug === void 0 ? [] : [slug],
+		"--json"
+	], {
+		env: { ...env },
+		timeout: LIVE_TIMEOUT_MS,
+		maxBuffer: 1048576
+	}, (error, stdout, stderr) => {
+		if (error !== null) {
+			const code = error.code;
+			resolve({
+				ok: false,
+				reason: code === "ENOENT" ? "there is no SAMVA_API_KEY and no `samva` CLI on PATH" : `\`samva brands get\` failed: ${cliFailure(stderr)}`
+			});
+			return;
+		}
+		const envelope = (() => {
+			try {
+				return JSON.parse(stdout);
+			} catch {
+				return;
+			}
+		})();
+		resolve(liveFromBody(isObject(envelope) ? envelope["data"] : void 0, "`samva brands get`"));
+	});
+});
+const fetchLiveBrand = (slug, env) => {
+	const apiKey = env["SAMVA_API_KEY"];
+	return apiKey !== void 0 && apiKey.length > 0 ? liveWithApiKey(slug, env, apiKey) : liveWithCli(slug, env);
+};
+const readSnapshotFile = async (path) => {
+	const raw = await readFile(path, "utf8").catch((cause) => {
+		if (cause.code === "ENOENT") return void 0;
+		throw cause;
+	});
+	if (raw === void 0) return {
+		ok: true,
+		snapshot: void 0,
+		path
+	};
+	const parsed = (() => {
+		try {
+			return JSON.parse(raw);
+		} catch {
+			return;
+		}
+	})();
+	const brand = asBrand(parsed);
+	if (brand === void 0 || !isObject(parsed) || parsed["version"] !== SNAPSHOT_VERSION || typeof parsed["pulledAt"] !== "string") return {
+		ok: false,
+		message: `${path} is not a brand snapshot this version of @samva/vite reads. Run \`samva brands pull\` to rewrite it.`
+	};
+	return {
+		ok: true,
+		snapshot: {
+			...brand,
+			version: SNAPSHOT_VERSION,
+			pulledAt: parsed["pulledAt"]
+		},
+		path
+	};
+};
+/**
+* The snapshot for a named brand, or for the default brand the most recently
+* pulled snapshot that was the default when it was pulled.
+*/
+const readSnapshot = async (root, slug) => {
+	const directory = join(root, BRAND_SNAPSHOT_DIR);
+	if (slug !== void 0) return readSnapshotFile(join(directory, `${slug}.json`));
+	const names = await readdir(directory).catch((cause) => {
+		if (cause.code === "ENOENT") return [];
+		throw cause;
+	});
+	const reads = await Promise.all(names.filter((name) => name.endsWith(".json")).sort().map((name) => readSnapshotFile(join(directory, name))));
+	const failed = reads.find((read) => !read.ok);
+	if (failed !== void 0) return failed;
+	const defaults = reads.flatMap((read) => read.ok && read.snapshot?.isDefault === true ? [{
+		...read,
+		snapshot: read.snapshot
+	}] : []);
+	defaults.sort((a, b) => b.snapshot.pulledAt.localeCompare(a.snapshot.pulledAt));
+	return defaults[0] ?? {
+		ok: true,
+		snapshot: void 0,
+		path: directory
+	};
+};
+const toResolved = (brand) => ({
+	slug: brand.slug,
+	css: brand.css,
+	digest: brand.digest,
+	...brand.assets === void 0 ? {} : { assets: brand.assets },
+	...brand.footer === void 0 ? {} : { footer: brand.footer }
+});
+const relativeSnapshot = (root, path) => relative(root, path).split(sep).join("/");
+/**
+* Resolve the brand a project's `samva:brand` import names: live when the
+* environment's credentials reach the API, else the pulled snapshot with a
+* warning, else a failure naming both fixes.
+*/
+const resolveProjectBrand = async (input) => {
+	const specifier = projectBrandSpecifier(input.files, input.themePath ?? "");
+	if (specifier === void 0) return {
+		ok: true,
+		brand: void 0,
+		source: "none",
+		warnings: []
+	};
+	const slug = parseBrandSpecifier(specifier)?.slug;
+	const pullCommand = `samva brands pull${slug === void 0 ? "" : ` ${slug}`}`;
+	const [live, local] = await Promise.all([fetchLiveBrand(slug, input.env), readSnapshot(input.root, slug)]);
+	if (live.ok) {
+		const stale = local.ok && local.snapshot !== void 0 && local.snapshot.digest !== live.brand.digest;
+		return {
+			ok: true,
+			brand: toResolved(live.brand),
+			source: "live",
+			warnings: stale ? [{
+				code: "brand-snapshot-stale",
+				message: `${relativeSnapshot(input.root, local.path)} is older than the live brand ${live.brand.slug}. Run \`${pullCommand}\` so offline builds match it.`
+			}] : []
+		};
+	}
+	if (!local.ok) return {
+		ok: false,
+		message: local.message
+	};
+	if (local.snapshot === void 0) return {
+		ok: false,
+		message: `The project imports ${specifier}, but ${live.reason}, and there is no snapshot in ${BRAND_SNAPSHOT_DIR}. Run \`samva login\` or set SAMVA_API_KEY, or run \`${pullCommand}\` while online.`
+	};
+	return {
+		ok: true,
+		brand: toResolved(local.snapshot),
+		source: "snapshot",
+		warnings: [{
+			code: "brand-offline",
+			message: `Using ${relativeSnapshot(input.root, local.path)} (pulled ${local.snapshot.pulledAt}) for ${specifier}: ${live.reason}.`
+		}]
+	};
+};
+/**
+* The environment a local build resolves the brand with: the process
+* environment plus the project's `.env` files, as the editor's dev server
+* reads them, so `SAMVA_API_KEY` in `.env` reaches `check` and `export` too.
+*/
+const loadBrandEnv = async (root) => {
+	const vite = await import("vite").catch(() => void 0);
+	if (vite === void 0) throw new Error("`vite` is required to resolve samva:brand locally.");
+	return vite.loadEnv("development", root, "");
+};
+/** The resolution as build findings: warnings stay warnings, a failure is an error. */
+const brandDiagnostics = (resolution) => resolution.ok ? resolution.warnings.map((warning) => ({
+	code: warning.code,
+	severity: "warning",
+	message: warning.message,
+	origins: []
+})) : [{
+	code: "brand-unavailable",
+	severity: "error",
+	message: resolution.message,
+	origins: []
+}];
+/**
+* One resolver per watch session. A resolution is reused for a short while per
+* specifier, so saving a file does not ask the API each time while a brand
+* edited elsewhere still arrives within the window.
+*/
+const createBrandResolver = (options) => {
+	const cache = /* @__PURE__ */ new Map();
+	return { resolve: async (files, themePath) => {
+		const key = projectBrandSpecifier(files, themePath ?? "") ?? "";
+		const cached = cache.get(key);
+		if (cached !== void 0 && Date.now() - cached.at < RESOLUTION_TTL_MS) return cached.resolution;
+		const resolution = await resolveProjectBrand({
+			root: options.root,
+			files,
+			themePath,
+			env: options.env
+		});
+		cache.set(key, {
+			at: Date.now(),
+			resolution
+		});
+		return resolution;
+	} };
+};
+/**
+* Resolves the `theme` plugin option to an absolute path, or `undefined` when
+* theming is explicitly disabled (`theme: false`). A string is taken relative to
+* `root` (absolute strings pass through); the default is `<root>/theme.css`.
+*/
+const resolveThemePath = (root, option) => {
+	if (option === false) return void 0;
+	const file = option ?? "theme.css";
+	return isAbsolute(file) ? file : resolve(root, file);
+};
+/** Read authored Tailwind CSS verbatim; the email compiler validates its syntax. */
+const readProjectThemeCss = async (path) => path === void 0 ? void 0 : readFile(path, "utf8").catch((cause) => {
+	if (cause.code === "ENOENT") return void 0;
+	throw cause;
+});
+/** The theme's project-relative path, from which its relative `@import`s resolve. */
+const projectThemePath = (root, themePath) => relative(root, themePath).split(sep).join("/");
+//#endregion
+//#region src/project.ts
+const toPosix = (value) => sep === "/" ? value : value.split(sep).join("/");
+const isCandidateEntry = (path) => path.endsWith(".tsx");
+const diagnostic = (code, severity, message) => ({
+	code,
+	severity,
+	message,
+	origins: []
+});
+/**
+* Read a project directory into the source map the compiler consumes. Text
+* modules arrive as strings and imported files as bytes, which is the same
+* shape the hosted build hands `compileEmailProject`.
+*/
+const readEmailProject = async (dir) => {
+	const root = resolve(dir);
+	const files = {};
+	const walk = async (current) => {
+		const entries = await readdir(current, { withFileTypes: true });
+		await Promise.all(entries.filter((entry) => !entry.name.startsWith(".") && entry.name !== "node_modules").map(async (entry) => {
+			const full = join(current, entry.name);
+			if (entry.isDirectory()) return walk(full);
+			if (!entry.isFile()) return;
+			const path = toPosix(relative(root, full));
+			files[path] = isAssetPath(path) ? new Uint8Array(await readFile(full)) : await readFile(full, "utf8");
+		}));
+	};
+	await walk(root);
+	return files;
+};
+/**
+* Compile and evaluate every candidate entry, keeping the ones that declare a
+* template. Compilation is per entry, exactly as a publication is per template,
+* so shared components and CSS reach each template the same way they reach the
+* hosted build.
+*/
+const loadEmailCatalog = async (input) => {
+	const candidates = (input.entryPaths ?? Object.keys(input.files).filter(isCandidateEntry)).slice();
+	candidates.sort();
+	const templates = [];
+	const helpers = [];
+	const diagnostics = [];
+	const assets = /* @__PURE__ */ new Map();
+	const declaredBy = /* @__PURE__ */ new Map();
+	const loaded = await Promise.all(candidates.map((entryPath) => loadEntry(input.renderer, input.files, entryPath, input.stableNamespaces === true ? entryPath : void 0)));
+	for (const [index, entryPath] of candidates.entries()) {
+		const result = loaded[index];
+		if (!result.ok) {
+			diagnostics.push(diagnostic("entry-load-error", "error", `${entryPath}: ${result.message}`));
+			continue;
+		}
+		const template = result.entry.template;
+		if (template === void 0) {
+			helpers.push(entryPath);
+			continue;
+		}
+		if (!isTemplateDefinition(template)) {
+			helpers.push(entryPath);
+			diagnostics.push(diagnostic("not-a-template", "warning", `${entryPath} default-exports something that is not a template definition. Wrap it with defineEmail, or drop the default export so it reads as a helper module.`));
+			continue;
+		}
+		const previous = declaredBy.get(template.id);
+		if (previous !== void 0) {
+			diagnostics.push(diagnostic("duplicate-template-id", "error", `Template id ${JSON.stringify(template.id)} is declared by both ${previous} and ${entryPath}. An id is a publication's identity, so it must name exactly one template.`));
+			continue;
+		}
+		declaredBy.set(template.id, entryPath);
+		for (const asset of result.entry.compiled.assets) assets.set(asset.digest, asset);
+		diagnostics.push(...result.entry.compiled.diagnostics);
+		templates.push({
+			id: template.id,
+			entryPath,
+			definition: template,
+			loaded: result.entry
+		});
+	}
+	return {
+		templates: templates.sort((left, right) => left.id < right.id ? -1 : 1),
+		helpers,
+		diagnostics,
+		assets: [...assets.values()].sort((left, right) => left.fileName < right.fileName ? -1 : 1)
+	};
+};
+const loadEntry = async (renderer, files, entryPath, namespace) => renderer.load(files, entryPath, namespace).then((entry) => ({
+	ok: true,
+	entry
+}), (cause) => ({
+	ok: false,
+	message: cause instanceof Error ? cause.message : String(cause)
+}));
+/**
+* Validate and render every fixture a template declares. A fixture that its own
+* schema rejects is a source defect the author sees here rather than at publish.
+*/
+const renderEmailFixtures = (entry, options = {}) => Object.entries(entry.definition.fixtures).map(([fixture, data]) => {
+	if (!entry.definition.schema.validate(data)) return {
+		templateId: entry.id,
+		fixture,
+		rendered: void 0,
+		diagnostics: [diagnostic("invalid-fixture", "error", `Fixture ${JSON.stringify(fixture)} does not satisfy ${entry.id}'s own input schema: ${JSON.stringify(entry.definition.schema.validate.errors)}`)]
+	};
+	try {
+		const rendered = entry.loaded.renderEmail(entry.definition, data, options);
+		return {
+			templateId: entry.id,
+			fixture,
+			rendered,
+			diagnostics: rendered.diagnostics
+		};
+	} catch (cause) {
+		return {
+			templateId: entry.id,
+			fixture,
+			rendered: void 0,
+			diagnostics: findingsOf(cause, entry.id, fixture)
+		};
+	}
+});
+const findingsOf = (cause, templateId, fixture) => {
+	const carried = cause.diagnostics;
+	if (Array.isArray(carried) && carried.length > 0) return carried;
+	return [diagnostic("render-failed", "error", `${templateId} could not render fixture ${JSON.stringify(fixture)}: ${cause instanceof Error ? cause.message : String(cause)}`)];
+};
+/**
+* The authoring loop: one evaluator, one catalog, reloaded on change. Content
+* semantics come from `compileEmailProject` and `renderEmail`, the same two
+* calls the hosted preview makes, so what an author iterates on locally is what
+* a publication renders.
+*/
+const createEmailProjectSession = async (dir, options) => {
+	const root = resolve(dir);
+	const renderer = await createEmailRenderer(options);
+	let catalog = {
+		templates: [],
+		helpers: [],
+		diagnostics: [],
+		assets: []
+	};
+	const listeners = /* @__PURE__ */ new Set();
+	const observer = watch(root, { recursive: true }, (_event, name) => {
+		const changed = name === null ? root : toPosix(name.toString());
+		for (const listener of listeners) listener(changed);
+	});
+	const reload = async () => {
+		renderer.invalidate();
+		catalog = await loadEmailCatalog({
+			renderer,
+			files: await readEmailProject(root),
+			stableNamespaces: true
+		});
+		return catalog;
+	};
+	return {
+		reload,
+		current: () => catalog,
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => void listeners.delete(listener);
+		},
+		close: async () => {
+			observer.close();
+			listeners.clear();
+			await renderer.close();
+		}
+	};
+};
+/**
+* Where an export serves its assets from when the caller names no origin.
+*
+* An export writes one page at `templates/<id>/<fixture>.html` and every asset
+* once at `assets/<content address>`, so the base a page resolves against is
+* the path from its own directory back to that one. A template id is one path
+* segment, so every page sits at the same depth and one base serves them all.
+*/
+const DEFAULT_EXPORT_ASSET_BASE = "../../assets";
+/**
+* The path an export writes, or `undefined` when a name would leave the root.
+*
+* `defineEmail` already refuses an id or a fixture key that is not one path
+* segment, so this is the guard rather than the contract: the same pattern,
+* plus a containment check, so a name that reaches `join` can never address a
+* file the export does not own.
+*/
+const exportPath = (out, ...segments) => {
+	if (!segments.every((segment) => TEMPLATE_NAME_PATTERN.test(segment))) return void 0;
+	const path = join(out, ...segments);
+	const inside = relative(out, path);
+	return inside === "" || inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside) ? void 0 : path;
+};
+const unsafeExportName = (kind, value) => diagnostic("unsafe-export-name", "error", `${kind} ${JSON.stringify(value)} is not one path segment, so an export cannot write a file for it. Use letters, digits, ".", "_" and "-", starting with a letter, digit or "_".`);
+/**
+* Render every template's fixtures to HTML and text beside the bytes of every
+* asset they reference, with the manifest that maps each address to its file.
+*
+* The export renders in the compiler's export mode, so a relative `assetBase`
+* is accepted and the written page resolves its images from the directory it
+* sits in. Delivery keeps refusing relative references — an inbox has no
+* directory to resolve one against — so an export destined for sending names
+* the https origin it will be served from instead.
+*/
+const exportEmailProject = async (input) => {
+	const out = resolve(input.out);
+	const root = resolve(input.root ?? input.dir);
+	const files = await readEmailProject(root);
+	const templatesPrefix = toPosix(relative(root, resolve(input.dir)));
+	const entryPaths = templatesPrefix === "" ? void 0 : Object.keys(files).filter((path) => isCandidateEntry(path) && path.startsWith(`${templatesPrefix}/`));
+	const base = input.assetBase ?? "../../assets";
+	const themePath = resolveThemePath(root, input.theme);
+	const themeCss = await readProjectThemeCss(themePath);
+	const themeFile = themeCss === void 0 || themePath === void 0 ? void 0 : projectThemePath(root, themePath);
+	const brandResolution = await resolveProjectBrand({
+		root,
+		files: themeFile === void 0 || themeCss === void 0 ? files : {
+			...files,
+			[themeFile]: themeCss
+		},
+		themePath: themeFile,
+		env: await loadBrandEnv(root)
+	});
+	const renderer = await createEmailRenderer({
+		assetBase: base,
+		...themeCss === void 0 || themeFile === void 0 ? {} : { tailwind: {
+			css: themeCss,
+			cssPath: themeFile
+		} },
+		...brandResolution.ok && brandResolution.brand !== void 0 ? { brand: brandResolution.brand } : {}
+	});
+	try {
+		const catalog = await loadEmailCatalog({
+			renderer,
+			files,
+			entryPaths
+		});
+		const diagnostics = [...brandDiagnostics(brandResolution), ...catalog.diagnostics];
+		const written = await Promise.all(catalog.templates.map(async (entry) => {
+			const directory = exportPath(out, "templates", entry.id);
+			if (directory === void 0) return {
+				entry: void 0,
+				diagnostics: [unsafeExportName("Template id", entry.id)]
+			};
+			await mkdir(directory, { recursive: true });
+			const rendered = renderEmailFixtures(entry, { relativeUrls: true });
+			const pages = await Promise.all(rendered.map(async (result) => {
+				if (result.rendered === void 0) return {
+					fixture: void 0,
+					diagnostics: []
+				};
+				const htmlPath = exportPath(out, "templates", entry.id, `${result.fixture}.html`);
+				const textPath = exportPath(out, "templates", entry.id, `${result.fixture}.txt`);
+				if (htmlPath === void 0 || textPath === void 0) return {
+					fixture: void 0,
+					diagnostics: [unsafeExportName("Fixture name", result.fixture)]
+				};
+				await Promise.all([writeFile(htmlPath, result.rendered.html, "utf8"), writeFile(textPath, result.rendered.text, "utf8")]);
+				return {
+					fixture: {
+						fixture: result.fixture,
+						html: toPosix(relative(out, htmlPath)),
+						text: toPosix(relative(out, textPath))
+					},
+					diagnostics: []
+				};
+			}));
+			return {
+				entry: {
+					id: entry.id,
+					entryPath: entry.entryPath,
+					fixtures: pages.map((result) => result.fixture).filter((fixture) => fixture !== void 0)
+				},
+				diagnostics: [...rendered.flatMap((result) => result.diagnostics), ...pages.flatMap((result) => result.diagnostics)]
+			};
+		}));
+		const templates = written.map((result) => result.entry).filter((entry) => entry !== void 0);
+		diagnostics.push(...written.flatMap((result) => result.diagnostics));
+		const assetDirectory = join(out, "assets");
+		if (catalog.assets.length > 0) await mkdir(assetDirectory, { recursive: true });
+		await Promise.all(catalog.assets.map((asset) => {
+			const bytes = files[asset.path];
+			return bytes === void 0 || typeof bytes === "string" ? Promise.resolve() : writeFile(join(assetDirectory, asset.fileName), bytes);
+		}));
+		const receipt = {
+			templates,
+			assets: {
+				base,
+				assets: catalog.assets
+			},
+			diagnostics
+		};
+		await mkdir(out, { recursive: true });
+		await writeFile(join(out, "catalog.json"), `${JSON.stringify({
+			...receipt,
+			assets: {
+				base,
+				assets: catalog.assets.map((asset) => ({
+					...asset,
+					url: assetUrl(asset, base)
+				}))
+			}
+		}, null, 2)}\n`, "utf8");
+		return receipt;
+	} finally {
+		await renderer.close();
+	}
+};
+//#endregion
+export { loadEmailCatalog as a, projectThemePath as c, BRAND_SNAPSHOT_DIR as d, brandDiagnostics as f, isObject as g, resolveProjectBrand as h, isTemplateDefinition$1 as i, readProjectThemeCss as l, loadBrandEnv as m, createEmailProjectSession as n, readEmailProject as o, createBrandResolver as p, exportEmailProject as r, renderEmailFixtures as s, DEFAULT_EXPORT_ASSET_BASE as t, resolveThemePath as u };
+
+//# sourceMappingURL=project-RON2Ei7d.js.map

package/dist/project.d.ts

@@ -1,8 +1,60 @@
 import { EmailProjectSource, EmailRenderer, LoadedEmailEntry } from "./email.js";
-import { AssetEntry, RenderedEmail, TransformOptions } from "@samva/markup/compiler";
+import { AssetEntry, EmailBrand, RenderedEmail, TransformOptions } from "@samva/markup/compiler";
 import { TemplateDefinition, isTemplateDefinition } from "@samva/markup/template";
 import { EmailDiagnostic } from "@samva/markup/email/diagnostics";
 import { SerializeEmailOptions } from "@samva/markup/email/html";
+//#region src/brand.d.ts
+/** Where `samva brands pull` writes snapshots, relative to the project root. */
+declare const BRAND_SNAPSHOT_DIR = ".samva/brands";
+declare const SNAPSHOT_VERSION = 1;
+/** A brand as a build compiles it, with the digest the API knows its content by. */
+interface ResolvedBrand extends EmailBrand {
+  readonly digest: string;
+}
+/** The file `samva brands pull` writes. */
+interface BrandSnapshot extends ResolvedBrand {
+  readonly version: typeof SNAPSHOT_VERSION;
+  readonly name: string;
+  readonly isDefault: boolean;
+  /** ISO timestamp of the pull. */
+  readonly pulledAt: string;
+}
+type BrandWarningCode = "brand-snapshot-stale" | "brand-offline";
+interface BrandWarning {
+  readonly code: BrandWarningCode;
+  readonly message: string;
+}
+type BrandResolution = {
+  readonly ok: true;
+  /** `undefined` when the project imports no brand. */
+  readonly brand: ResolvedBrand | undefined;
+  readonly source: "live" | "snapshot" | "none";
+  readonly warnings: readonly BrandWarning[];
+} | {
+  readonly ok: false;
+  readonly message: string;
+};
+interface ResolveProjectBrandInput {
+  readonly root: string;
+  readonly files: EmailProjectSource;
+  /** Project-relative theme path; `undefined` when theming is disabled. */
+  readonly themePath?: string | undefined;
+  /** Environment holding `SAMVA_API_KEY`, `SAMVA_API_URL` and `PATH`; see `loadBrandEnv`. */
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Resolve the brand a project's `samva:brand` import names: live when the
+ * environment's credentials reach the API, else the pulled snapshot with a
+ * warning, else a failure naming both fixes.
+ */
+declare const resolveProjectBrand: (input: ResolveProjectBrandInput) => Promise<BrandResolution>;
+/**
+ * The environment a local build resolves the brand with: the process
+ * environment plus the project's `.env` files, as the editor's dev server
+ * reads them, so `SAMVA_API_KEY` in `.env` reaches `check` and `export` too.
+ */
+declare const loadBrandEnv: (root: string) => Promise<Readonly<Record<string, string | undefined>>>;
+//#endregion
 //#region src/project.d.ts
 /**
  * Read a project directory into the source map the compiler consumes. Text
@@ -106,11 +158,18 @@ declare const DEFAULT_EXPORT_ASSET_BASE = "../../assets";
  * the https origin it will be served from instead.
  */
 declare const exportEmailProject: (input: {
+  /** Directory holding the templates; every `.tsx` under it is a candidate entry. */
   readonly dir: string;
+  /**
+   * Project root holding shared imports, `theme.css` and `.samva/brands`; defaults to `dir`.
+   * `samva templates export` passes the working directory, as `check` and `build` do.
+   */
+  readonly root?: string | undefined;
   readonly out: string;
   readonly assetBase?: string | undefined;
-  readonly tailwind?: TransformOptions["tailwind"] | undefined;
+  /** Project theme file relative to `root`, as in `buildTemplates()`; `false` disables it. */
+  readonly theme?: string | false | undefined;
 }) => Promise<EmailExportReceipt>;
 //#endregion
-export { DEFAULT_EXPORT_ASSET_BASE, EmailCatalog, EmailCatalogEntry, EmailExportReceipt, EmailProjectSession, RenderedFixture, createEmailProjectSession, exportEmailProject, isTemplateDefinition, loadEmailCatalog, readEmailProject, renderEmailFixtures };
+export { BRAND_SNAPSHOT_DIR, type BrandResolution, type BrandSnapshot, type BrandWarning, DEFAULT_EXPORT_ASSET_BASE, EmailCatalog, EmailCatalogEntry, EmailExportReceipt, EmailProjectSession, RenderedFixture, type ResolvedBrand, createEmailProjectSession, exportEmailProject, isTemplateDefinition, loadBrandEnv, loadEmailCatalog, readEmailProject, renderEmailFixtures, resolveProjectBrand };
 //# sourceMappingURL=project.d.ts.map