@plitzi/sdk-shared 0.38.6 → 0.38.7

package/dist/project/layout.mjs

@@ -0,0 +1,394 @@
+import { isRecord as e } from "../helpers/isRecord.mjs";
+import { AUTHOR_FILE as t, DATA_DIR as n, FUNCTIONS_DIR as r, PLUGINS_DIR as i, PLUGIN_DECLARATION_FILE as a, PLUGIN_ENTRIES as o, PLUGIN_FUNCTIONS_DIR as s, PLUGIN_MANIFEST_FILE as c, PUBLIC_DIR as l, RUNTIME_DIR as u, SPACE_DIR as d, SPACE_ENTRY as f, VENDOR_PLUGINS_DIR as p } from "./paths.mjs";
+import m from "node:path";
+import { readFileSync as h, readdirSync as g, statSync as _ } from "node:fs";
+//#region src/project/layout.ts
+var v = {
+	"plugin-entry-missing": {
+		level: "error",
+		means: "a folder of src/plugins/ with no index.ts (or index.tsx), which the server builds the plugin from"
+	},
+	"plugin-entry-ambiguous": {
+		level: "error",
+		means: "a folder of src/plugins/ with both index.ts and index.tsx: a plugin starts at one"
+	},
+	"entry-not-typescript": {
+		level: "error",
+		means: "an entry the server builds or runs written as JavaScript (index.js, .jsx, .mjs, .cjs): the project is TypeScript"
+	},
+	"plugin-name-invalid": {
+		level: "error",
+		means: "a folder of src/plugins/ whose name cannot be an element type: a letter, then letters and digits"
+	},
+	"plugin-type-taken": {
+		level: "error",
+		means: "two folders of src/plugins/ that are the same element type (StoryEditor and storyEditor)"
+	},
+	"plugin-shadowed": {
+		level: "error",
+		means: "a plugin both in src/plugins/ and, as it was built, in vendor/plugins/: the built one runs"
+	},
+	"plugin-functions-entry-missing": {
+		level: "error",
+		means: "a plugin’s functions/ with code and no index.ts, which its server half is built from"
+	},
+	"functions-entry-missing": {
+		level: "error",
+		means: "src/functions/ with code and no index.ts, which the project’s functions are built from"
+	},
+	"runtime-entry-missing": {
+		level: "error",
+		means: "src/runtime/ with code and no index.ts, which the space’s runtime starts at"
+	},
+	"space-entry-missing": {
+		level: "error",
+		means: "a space written in the project with no src/space/index.ts, which the server and npm run author import"
+	},
+	"space-default-export": {
+		level: "error",
+		means: "src/space/index.ts exporting the space by default, where it is imported by name: `space`"
+	},
+	"vendor-manifest-missing": {
+		level: "error",
+		means: "a built plugin (vendor/plugins/<type>/) with no plugin-manifest.json"
+	},
+	"vendor-manifest-invalid": {
+		level: "error",
+		means: "a built plugin’s plugin-manifest.json that is not a manifest"
+	},
+	"vendor-script-missing": {
+		level: "error",
+		means: "a built plugin’s manifest naming no script to run, or one that is not there"
+	},
+	"env-in-src": {
+		level: "error",
+		means: ".env inside src/: Node reads the project’s settings from the .env at its root"
+	},
+	"folder-misplaced": {
+		level: "error",
+		means: "code in a folder named like one the server reads (src/plugin/, plugins/ at the root): nothing reads it"
+	},
+	"folder-near-miss": {
+		level: "warning",
+		means: "a folder named like one the server reads (src/Data/, src/runtimes/), which nothing reads"
+	},
+	"plugin-declaration-missing": {
+		level: "warning",
+		means: "a plugin folder with no declaration.ts: the space’s use of the plugin is held to nothing"
+	},
+	"plugin-file-loose": {
+		level: "warning",
+		means: "a file directly in src/plugins/, where every plugin is a folder"
+	},
+	"data-not-json": {
+		level: "warning",
+		means: "a file of src/data/ that is not JSON, which no provider and no ctx.data reads"
+	},
+	"env-missing": {
+		level: "warning",
+		means: "no .env at the project’s root: none of its settings is set"
+	},
+	"env-example-missing": {
+		level: "warning",
+		means: "no .env.example: a clone does not know what .env must hold"
+	},
+	"public-data": {
+		level: "warning",
+		means: "JSON in public/data/ of a project with a server: served to anyone who asks"
+	},
+	"public-secret-file": {
+		level: "warning",
+		means: "a file in public/ named like a secret (.env, a key, a dump): served to anyone who asks"
+	}
+}, y = (e, t, n, r, i) => ({
+	level: v[e].level,
+	code: e,
+	file: t,
+	message: n,
+	fix: r,
+	...i ? { autofix: i } : {}
+}), b = /* @__PURE__ */ new Set([
+	".gitkeep",
+	"README.md",
+	".DS_Store"
+]), ee = /^index\.(?:js|jsx|mjs|cjs)$/, x = /^[A-Za-z][A-Za-z0-9]*$/, S = (e) => {
+	let t = {
+		files: [],
+		folders: []
+	};
+	try {
+		for (let n of g(e, { withFileTypes: !0 })) {
+			let r = n.isSymbolicLink() ? _(m.join(e, n.name), { throwIfNoEntry: !1 }) : void 0;
+			n.isFile() || r?.isFile() ? t.files.push(n.name) : (n.isDirectory() || r?.isDirectory()) && t.folders.push(n.name);
+		}
+	} catch {
+		return t;
+	}
+	return {
+		files: t.files.sort(),
+		folders: t.folders.sort()
+	};
+}, C = (e, t, n) => {
+	let r = t.split("/").filter((e) => e !== "" && e !== "."), i = e;
+	for (let [e, t] of r.entries()) {
+		let { files: a, folders: o } = S(i);
+		if (!(e === r.length - 1 && n === "file" ? a : o).includes(t)) return !1;
+		i = m.join(i, t);
+	}
+	return !0;
+}, w = (e, t, n = /* @__PURE__ */ new Set()) => {
+	let { files: r, folders: i } = S(m.join(e, t));
+	return [...r.map((e) => `${t}/${e}`), ...i.filter((e) => !n.has(e)).flatMap((r) => w(e, `${t}/${r}`, n))];
+}, T = ({ files: e, folders: t }) => t.length > 0 || e.some((e) => !b.has(e)), E = (e, t) => e.toLowerCase() === t.toLowerCase(), D = (e) => `${e.charAt(0).toUpperCase()}${e.slice(1)}`, O = (e, t) => {
+	let n = Array.from({ length: e.length + 1 }, (e, n) => Array.from({ length: t.length + 1 }, (e, t) => Math.max(n, t) * Number(n === 0 || t === 0)));
+	for (let r = 1; r <= e.length; r++) for (let i = 1; i <= t.length; i++) {
+		let a = e[r - 1] === t[i - 1] ? 0 : 1;
+		n[r][i] = Math.min(n[r - 1][i] + 1, n[r][i - 1] + 1, n[r - 1][i - 1] + a), r > 1 && i > 1 && e[r - 1] === t[i - 2] && e[r - 2] === t[i - 1] && (n[r][i] = Math.min(n[r][i], n[r - 2][i - 2] + 1));
+	}
+	return n[e.length][t.length];
+}, k = (e, t) => {
+	if (e === t) return !1;
+	let n = e.toLowerCase(), r = t.toLowerCase();
+	return n === r || n === `${r}s` || `${n}s` === r || r.length >= 5 && O(n, r) <= 1;
+}, A = "macOS and Windows disks ignore case, so it is found there — and not on Linux, where the project is deployed.", j = (e, t) => E(e, t) ? `git mv ${e} ${e}-tmp && git mv ${e}-tmp ${t}` : `git mv ${e} ${t}`, M = (e) => `${e.charAt(0).toLowerCase()}${e.slice(1)}`, N = (e) => {
+	let t = e.split(/[^A-Za-z0-9]+/).filter(Boolean).map(D).join(""), n = /^\d+/.exec(t)?.[0] ?? "", r = `${D(t.slice(n.length))}${n}`;
+	return x.test(r) ? r : void 0;
+}, P = (e) => {
+	let { files: t } = S(e), n = o.filter((e) => t.includes(e));
+	return n.length === 1 ? m.join(e, n[0]) : void 0;
+}, F = (e, t) => x.test(t) ? P(m.join(e, i, t)) : void 0, I = (e) => e.length > 1 ? `${e[0]} (or ${e.slice(1).join(", ")})` : e[0], L = (e, t) => {
+	let { folder: n, accepted: r, code: i, lost: a } = t, o = S(m.join(e, n)), s = r.filter((e) => o.files.includes(e));
+	if (s.length === 1) return [];
+	if (s.length > 1) return [y("plugin-entry-ambiguous", `${n}/`, `${n}/ has both ${s.join(" and ")}, and a plugin is built from one of them.`, `Keep one — ${s[s.length - 1]} when it writes JSX — and delete the other.`)];
+	let c = o.files.find((e) => ee.test(e));
+	if (c) {
+		let e = c.endsWith(".jsx") && r.includes("index.tsx") ? "index.tsx" : "index.ts";
+		return [y("entry-not-typescript", `${n}/${c}`, `${n}/${c} is JavaScript, and ${n}/ is built from ${I(r)}: the project's code is TypeScript, so ${a}.`, `Rename it ${e} — JavaScript is TypeScript already, types left out: ${j(`${n}/${c}`, `${n}/${e}`)}`, {
+			action: "move",
+			from: `${n}/${c}`,
+			to: `${n}/${e}`
+		})];
+	}
+	let l = o.files.find((e) => r.some((t) => k(e, t)));
+	if (l) {
+		let e = r.find((e) => k(l, e)) ?? r[0];
+		return [y(i, `${n}/${l}`, `${n}/ has no ${e} — did you mean ${l}? Named otherwise, ${a}.${E(l, e) ? ` ${A}` : ""}`, `Rename it ${e}: ${j(`${n}/${l}`, `${n}/${e}`)}`, {
+			action: "move",
+			from: `${n}/${l}`,
+			to: `${n}/${e}`
+		})];
+	}
+	let u = o.folders.find((t) => r.some((r) => C(e, `${n}/${t}/${r}`, "file")));
+	return u ? [y(i, `${n}/${u}/`, `${n}/ has no ${I(r)}, and ${n}/${u}/ has: one folder too deep, so ${a}.`, `Move what ${n}/${u}/ holds up into ${n}/.`, {
+		action: "move",
+		from: `${n}/${u}/`,
+		to: `${n}/`
+	})] : [y(i, `${n}/`, `${n}/ has no ${I(r)}, so ${a}.`, t.write)];
+}, R = (e, t) => T(S(m.join(e, t.folder))) ? L(e, t) : [], te = (e) => {
+	let t = N(e), n = `${i}/${e}`;
+	return y("plugin-name-invalid", `${n}/`, `${n}/ cannot be a plugin: a folder of ${i}/ is registered as the element type its name makes, and a type is a letter followed by letters and digits.${t ? ` Did you mean ${t}?` : ""}`, t ? `Rename it ${t} — the type ${M(t)}: ${j(n, `${i}/${t}`)}; then type: '${M(t)}' in its ${a}, and renderType: '${M(t)}' where the space renders it.` : "Rename it with letters and digits, starting with a letter: StatCard is the type statCard.");
+}, ne = (e, t) => e.find((e) => e === `${t}.tsx`) ?? e.find((e) => e === `${t}.ts`), z = (e, t) => {
+	let n = `${i}/${t}`, { files: r } = S(m.join(e, n));
+	if (r.includes("declaration.ts")) return [];
+	let o = M(t), s = `authoring holds none of the space's ${o} elements to its attributes, and the builder does not offer it`, c = r.find((e) => k(e, a));
+	return c ? [y("plugin-declaration-missing", `${n}/${c}`, `${n}/ has no ${a} — did you mean ${c}? Named otherwise, ${s}.${E(c, "declaration.ts") ? ` ${A}` : ""}`, `Rename it ${a}: ${j(`${n}/${c}`, `${n}/${a}`)}`, {
+		action: "move",
+		from: `${n}/${c}`,
+		to: `${n}/${a}`
+	})] : [y("plugin-declaration-missing", `${n}/`, `${n}/ has no ${a}: ${s}.`, `Write ${n}/${a} — export default { type: '${o}', … } — as npx plitzi add plugin writes one beside the component it makes.`)];
+}, B = (e, t) => {
+	if (!x.test(t)) return [te(t)];
+	let n = `${i}/${t}`, r = M(t), a = ne(S(m.join(e, n)).files, t);
+	return [
+		...L(e, {
+			folder: n,
+			accepted: o,
+			code: "plugin-entry-missing",
+			lost: `the server cannot build the plugin ${r}`,
+			write: `Write ${n}/index.ts exporting the component by default${a ? ` — export { default } from './${a}';` : ""} — as npx plitzi add plugin writes it. Every folder of ${i}/ is a plugin: code several plugins share goes outside it (src/shared/).`
+		}),
+		...R(e, {
+			folder: `${n}/${s}`,
+			accepted: ["index.ts"],
+			code: "plugin-functions-entry-missing",
+			lost: `none of the plugin's server half runs (its routes under /fn/plugins/${r}/)`,
+			write: `Write ${n}/${s}/index.ts exporting defineFunctions({ … }) by default — as npx plitzi add plugin --server writes it.`
+		}),
+		...z(e, t)
+	];
+}, V = (e) => {
+	let t = /* @__PURE__ */ new Map();
+	for (let n of e.filter((e) => x.test(e))) t.set(M(n), [...t.get(M(n)) ?? [], n]);
+	return [...t].flatMap(([e, t]) => t.slice(1).map((n) => y("plugin-type-taken", `${i}/${n}/`, `${i}/${t[0]}/ and ${i}/${n}/ are both the plugin ${e}: the server registers a folder by its name with a small first letter, and keeps one.`, `Put them in one folder, or rename one: git mv ${i}/${n} ${i}/<AnotherName>`)));
+}, H = (t) => e(t.assets) ? Object.values(t.assets).flatMap((t) => e(t) && typeof t.src == "string" && typeof t.type == "string" ? [{
+	src: t.src,
+	type: t.type,
+	isMain: t.isMain === !0
+}] : []) : [], U = (t, n) => {
+	let r = `${p}/${n}`, i = `${r}/${c}`, a = `npx plitzi pull brings it again — or delete ${r}/, and the space renders no ${n}.`;
+	if (!C(t, i, "file")) return { problem: y("vendor-manifest-missing", `${r}/`, `${r}/ has no ${c}: the server runs a built plugin by what its manifest names, so ${n} does not run.`, a) };
+	let o;
+	try {
+		o = JSON.parse(h(m.join(t, i), "utf-8"));
+	} catch (e) {
+		return { problem: y("vendor-manifest-invalid", i, `${i} is not JSON (${e instanceof Error ? e.message : String(e)}), so ${n} does not run.`, a) };
+	}
+	if (!e(o)) return { problem: y("vendor-manifest-invalid", i, `${i} is not a manifest, so ${n} does not run.`, a) };
+	let s = H(o), l = s.find((e) => e.type === "script" && e.isMain) ?? s.find((e) => e.type === "script");
+	if (!l) return { problem: y("vendor-script-missing", i, `${i} names no script to run, so ${n} does not run.`, a) };
+	if (!C(t, m.posix.join(r, l.src), "file")) return { problem: y("vendor-script-missing", i, `${i} names ${l.src} as the script to run, and ${r}/${l.src} is not there, so ${n} does not run.`, a) };
+	let u = s.find((e) => e.type === "style");
+	return {
+		script: m.join(t, r, l.src),
+		...u ? { style: m.join(t, r, u.src) } : {},
+		version: typeof o.version == "string" ? o.version : "1.0.0",
+		...typeof o.functions == "string" ? { functions: m.join(t, r, o.functions) } : {}
+	};
+}, W = (e) => {
+	let { files: t, folders: n } = S(m.join(e, i)), r = t.filter((e) => !b.has(e) && e !== "declarations.ts").map((e) => {
+		let { name: t } = m.parse(e), n = t !== "index" && N(t) || "<Name>";
+		return y("plugin-file-loose", `${i}/${e}`, `${i}/${e} is a file, and every plugin is a folder of ${i}/: the server reads nothing of it.`, `Give it a folder with an index.ts that exports it by default — ${i}/${n}/${e} and ${i}/${n}/index.ts, as npx plitzi add plugin writes them — or move it out of ${i}/.`);
+	}), a = S(m.join(e, p)).folders, o = new Set(n.filter((e) => x.test(e)).map(M)), s = a.filter((e) => o.has(e)).map((e) => y("plugin-shadowed", `${p}/${e}/`, `${e} is both ${p}/${e}/, as it was built, and a folder of ${i}/: the server runs the built one, and a change to the source shows nowhere.`, `Delete ${p}/${e}/: the source is the plugin now.`)), c = a.flatMap((t) => {
+		let n = U(e, t);
+		return "problem" in n ? [n.problem] : [];
+	});
+	return [
+		...n.flatMap((t) => B(e, t)),
+		...V(n),
+		...r,
+		...s,
+		...c
+	];
+}, G = (e, t) => t.map((t) => e.find((e) => E(e, t))).find((e) => e !== void 0), K = (e) => (t) => {
+	for (let n of S(m.join(e, t)).folders) {
+		let r = G(S(m.join(e, t, n)).files, [...o, a]);
+		if (r) return `${t}/${n}/${r}`;
+	}
+}, q = (e) => (t) => {
+	let n = G(S(m.join(e, t)).files, ["index.ts"]);
+	return n ? `${t}/${n}` : void 0;
+}, J = (e, { mode: a, space: o }) => [
+	{
+		at: i,
+		reads: `the server builds plugins from ${i}/ only`,
+		holds: K(e)
+	},
+	{
+		at: r,
+		reads: `the project's functions are built from ${r}/ only`,
+		holds: q(e)
+	},
+	{
+		at: u,
+		reads: `the space's runtime is run from ${u}/ only`,
+		holds: q(e)
+	},
+	...o === "local" ? [{
+		at: d,
+		reads: `the server's entry point and ${t} import the space from ${f}`,
+		holds: q(e)
+	}] : [],
+	...a === "server" ? [{
+		at: n,
+		reads: `the server reads the project's data from ${n}/ only (/data/<file>, ctx.data)`
+	}] : [],
+	{
+		at: l,
+		reads: `the server serves ${l}/ only, at the site's root`
+	}
+], Y = (e, t) => {
+	let n = m.posix.dirname(t), r = m.posix.basename(t), i = n === "." ? "src" : ".", a = S(m.join(e, n)).folders.filter((e) => k(e, r)).map((e) => m.posix.join(n, e)), o = S(m.join(e, i)).folders.filter((e) => e === r || k(e, r)).map((e) => m.posix.join(i, e));
+	return [...a, ...o];
+}, X = (e, t) => J(e, t).flatMap(({ at: t, reads: n, holds: r }) => Y(e, t).map((i) => {
+	let a = r?.(i), o = E(i, t), s = `did you mean ${t}/? ${D(n)}.${o ? ` ${A}` : ""}`, c = `Move it: ${j(i, t)}`;
+	o ? c = `Rename it: ${j(i, t)}` : C(e, t, "folder") && (c = `Move what it holds into ${t}/, and delete it.`);
+	let l = {
+		action: "move",
+		from: `${i}/`,
+		to: `${t}/`
+	};
+	return a ? y("folder-misplaced", `${i}/`, `${i}/ holds ${a}, and nothing reads it there — ${s}`, c, l) : y("folder-near-miss", `${i}/`, `${i}/ is read by nothing — ${s}`, c, l);
+})), re = (e, n) => {
+	if (!C(e, f, "file")) return n.some((e) => e.code === "folder-misplaced" && e.autofix?.action === "move" && e.autofix.to === "src/space/") ? [] : L(e, {
+		folder: d,
+		accepted: ["index.ts"],
+		code: "space-entry-missing",
+		lost: `the server's entry point and ${t}, which import the space from ${f}, do not start`,
+		write: `Write ${f} exporting the space — export const space = { name, permanentUrl, pages } — or bring back the one git has: git checkout -- ${f}`
+	});
+	let r = h(m.join(e, f), "utf-8"), i = /^\s*export\s+default\b/m.test(r), a = /\bexport\s+(?:const|let|var|function)\s+space\b/.test(r) || /\bexport\s*\{[^}]*\bspace\b[^}]*\}/.test(r);
+	return i && !a ? [y("space-default-export", f, `${f} exports the space by default, and it is imported by name — import { space } from './space/index.ts' — so the server's entry point and ${t} find no space.`, "Export it as `export const space = …` instead of `export default …`.")] : [];
+}, ie = (e) => e.split("\n").map((e) => e.replace(/^(\s*(?:export\s+)?[A-Za-z_][A-Za-z0-9_]*\s*=).*$/, "$1")).join("\n"), ae = (e) => {
+	let t = S(e).files, n = t.includes(".env"), r = t.includes(".env.example"), i = w(e, "src", /* @__PURE__ */ new Set(["node_modules"])).filter((e) => m.posix.basename(e) === ".env"), a = !n && i.length === 1, o = i.map((e) => y("env-in-src", e, `${e} is never read: Node reads the project's settings from the .env at its root, as its scripts start it (--env-file-if-exists=.env).`, a ? `Move it to the root: mv ${e} .env` : `Copy what it sets into the root's .env, then delete ${e}.`, a ? {
+		action: "move",
+		from: e,
+		to: ".env"
+	} : void 0)), s = n || o.length > 0 ? [] : [y("env-missing", ".env", ".env is missing at the project’s root: none of its settings is set — the keys and secrets its code reads from process.env.", r ? "Copy .env.example and fill it in: cp .env.example .env" : "Write .env with the settings the project reads (process.env.*), and .env.example naming them.", r ? {
+		action: "copy",
+		from: ".env.example",
+		to: ".env"
+	} : void 0)], c = r ? [] : [y("env-example-missing", ".env.example", ".env.example is missing: committed where .env never is, it names the settings .env holds, with no secret in them — so a clone knows what to fill in.", n ? "Write it from .env with every value left empty, and commit it." : "Write it — each setting the project reads, as KEY= with no value — and commit it.", n ? {
+		action: "write",
+		file: ".env.example",
+		contents: ie(h(m.join(e, ".env"), "utf-8"))
+	} : void 0)];
+	return [
+		...o,
+		...s,
+		...c
+	];
+}, oe = (e) => w(e, n).filter((e) => !b.has(m.posix.basename(e)) && !e.endsWith(".json")).map((e) => y("data-not-json", e, `${e} is not JSON: a provider's /data/<file> and ctx.data read JSON files only, and plitzi push leaves it behind.`, `Keep it as JSON (${e.replace(/\.[^./]*$/, "")}.json), or move it out of ${n}/.`)), se = /^\.env(?:\..*)?$|\.(?:pem|key|p12|pfx|jks|keystore|sqlite3?|db|sql|dump)$|secret|credential|password|passwd|private[-_.]?key|id_rsa|id_ed25519|service[-_]?account/i, ce = (e, t) => {
+	let r = w(e, l, /* @__PURE__ */ new Set(["node_modules"])), i = r.filter((e) => se.test(m.posix.basename(e))).map((e) => y("public-secret-file", e, `${e} is served to anyone who asks, as it is — everything in ${l}/ is on the internet once the project is deployed — and its name says it holds a secret, a key or a database.`, `Take it out of ${l}/: settings go in the root's .env${t === "server" ? `, data only the server reads in ${n}/` : ""}.`)), a = `${l}/data`, o = t === "server" ? r.filter((e) => e.startsWith(`${a}/`) && e.endsWith(".json")) : [], s = o.slice(0, 3).map((e) => m.posix.basename(e)), c = o.length > 0 ? [y("public-data", `${a}/`, `${a}/ holds ${String(o.length)} JSON file${o.length === 1 ? "" : "s"} (${s.join(", ")}${o.length > s.length ? ", …" : ""}), served to anyone who asks: every visitor can read all of ${o.length === 1 ? "it" : "them"}, not only what a page shows.`, `Data only the server should read goes in ${n}/ — a provider reads it on the server (runtime: 'server', query: '/data/<file>'), a function with ctx.data('<file>'), and neither serves the file. What every visitor may read can stay.`)] : [];
+	return [...i, ...c];
+}, Z = (t) => {
+	try {
+		let n = JSON.parse(h(m.join(t, "package.json"), "utf-8"));
+		return e(n) && [n.dependencies, n.devDependencies].some((t) => e(t) && "@plitzi/sdk-server" in t);
+	} catch {
+		return !1;
+	}
+}, le = (e, n) => ({
+	mode: n.mode ?? (Z(e) ? "server" : "client"),
+	space: n.space ?? (C(e, "src/space", "folder") || C(e, t, "file") ? "local" : "cloud")
+}), Q = (e, t = {}) => {
+	let n = le(e, t), i = X(e, n), a = [
+		...W(e),
+		...R(e, {
+			folder: r,
+			accepted: ["index.ts"],
+			code: "functions-entry-missing",
+			lost: "none of the project’s functions runs",
+			write: `Write ${r}/index.ts exporting defineFunctions({ … }) by default.`
+		}),
+		...R(e, {
+			folder: u,
+			accepted: ["index.ts"],
+			code: "runtime-entry-missing",
+			lost: "the space’s runtime does not run",
+			write: `Write ${u}/index.ts exporting defineRuntime(…) by default — npx plitzi add runtime writes one.`
+		}),
+		...n.space === "local" ? re(e, i) : [],
+		...i,
+		...ae(e),
+		...n.mode === "server" ? oe(e) : [],
+		...ce(e, n.mode)
+	];
+	return [...a.filter((e) => e.level === "error"), ...a.filter((e) => e.level === "warning")];
+}, ue = (e) => `${e.message}\n  → ${e.fix}`, $ = class extends Error {
+	#e;
+	get findings() {
+		return this.#e;
+	}
+	constructor(e) {
+		let t = e.length === 1 ? "one error" : `${String(e.length)} errors`, n = e.map((e, t) => `${String(t + 1)}. ${e.message}\n   → ${e.fix}`).join("\n\n"), r = e.filter((e) => e.autofix).length, i = r === e.length ? "these fixes" : `${String(r)} of these fixes`, a = r > 0 ? `npx plitzi doctor --fix makes ${i} itself.` : "npx plitzi doctor says these with the rest of the project.";
+		super(`The project is not laid out as Plitzi reads it — ${t}:\n\n${n}\n\n${a}`), this.name = "ProjectLayoutError", this.#e = e;
+	}
+};
+Object.defineProperty($, "name", { value: "ProjectLayoutError" });
+var de = (e, t = {}) => {
+	let n = Q(e, t), r = n.filter((e) => e.level === "error");
+	if (r.length > 0) throw new $(r);
+	return n;
+};
+//#endregion
+export { v as PROJECT_LAYOUT_CODES, $ as ProjectLayoutError, de as assertProjectLayout, B as checkPluginFolder, Q as checkProjectLayout, P as elementEntry, ue as layoutFindingText, F as pluginEntry, M as pluginTypeOf, U as readVendorPlugin };

package/dist/project/paths.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The layout of a project `@plitzi/cli` writes, relative to its root: the one place the CLI that writes and checks it,
+ * the server that serves it (`@plitzi/sdk-server/project`) and the authoring that checks its space
+ * (`@plitzi/sdk-authoring/node`'s `projectAuthoring`) read it from.
+ *
+ * `tmp/` is what the project writes for itself, never committed, everything in it rebuilt when it is missing — the
+ * server's plugin bundles (`tmp/.sdk-plugins`) and resized pictures (`tmp/images`), both `@plitzi/sdk-server`'s
+ * defaults, beside what the files below name. One folder, so a reader of the project — a person, an agent — knows at a
+ * glance what is the project and what is a by-product of running it.
+ */
+export declare const PROJECT_TMP = "tmp";
+/** The project's own code — its space, plugins, data, functions and server — which the server watches while developing. */
+export declare const SOURCE_DIR = "src";
+/**
+ * The CLI's own part of a project — the script that authors the space, the types its plugins import besides code, the
+ * page's base styles — apart from `src/`, which is the project's: `plitzi upgrade` keeps this folder current, and a
+ * person reads `src/` without wading through it.
+ */
+export declare const CLI_DIR = "plitzi";
+/**
+ * What authors the space and says what it found: `npm run author`, and the server's re-authoring on a save, which runs
+ * it in a process of its own and is handed the documents over IPC (`--ipc`).
+ */
+export declare const AUTHOR_FILE = "plitzi/author.ts";
+/**
+ * The space, in a folder of its own — it grows a page, a layout, a component at a time — whose `index.ts` exports it as
+ * `space`: what the server's entry point, the author script, the visual test and the CLI's checks import.
+ */
+export declare const SPACE_DIR = "src/space";
+export declare const SPACE_ENTRY = "src/space/index.ts";
+/**
+ * The project's own components: every folder is one, registered under its name in camelCase — `src/plugins/StatCard`
+ * renders a space's `custom({ renderType: 'statCard' })` — built from its entry (`PLUGIN_ENTRIES`) and declared by its
+ * `declaration.ts`.
+ */
+export declare const PLUGINS_DIR = "src/plugins";
+/**
+ * What a plugin folder is built from: `index.ts`, or `index.tsx` for one that writes its JSX there — TypeScript both,
+ * and one of them, never both.
+ */
+export declare const PLUGIN_ENTRIES: readonly ["index.ts", "index.tsx"];
+/** What a plugin folder declares itself in — its type, attributes, triggers — as `plitzi add plugin` writes it. */
+export declare const PLUGIN_DECLARATION_FILE = "declaration.ts";
+/** A plugin's server half, a folder of its own beside its component: built from its `index.ts`. */
+export declare const PLUGIN_FUNCTIONS_DIR = "functions";
+/**
+ * Plugins no source of was kept, as they were built (a project made from a space): `vendor/plugins/<type>/`, each
+ * beside the manifest it was published with (`PLUGIN_MANIFEST_FILE`).
+ */
+export declare const VENDOR_PLUGINS_DIR = "vendor/plugins";
+/** What `plitzi pack plugin` writes beside a plugin's bundle: its version, its files, and the elements it provides. */
+export declare const PLUGIN_MANIFEST_FILE = "plugin-manifest.json";
+/** A runtime that came across built only (a project made from a space): run as it was built. */
+export declare const RUNTIME_BUNDLE = "vendor/runtime.bundle";
+/** Served to anyone as it is: pictures, a favicon — every file in it is on the internet once the project is deployed. */
+export declare const PUBLIC_DIR = "public";
+/**
+ * The project's own data, server mode: JSON its server reads (`dataDir`) and never serves — a provider asks for
+ * `/data/<file>` on the server. A project with no server keeps it in `public/data/`, where the browser fetches it.
+ */
+export declare const DATA_DIR = "src/data";
+/** The project's own server code — the tasks and `/fn/` routes `defineFunctions` declares — built at boot. */
+export declare const FUNCTIONS_DIR = "src/functions";
+/**
+ * The space's runtime — its own server code, run as a process of its own on Plitzi and by the project's server in its
+ * process — a folder like the space, whose `index.ts` exports it.
+ */
+export declare const RUNTIME_DIR = "src/runtime";
+export declare const RUNTIME_ENTRY = "src/runtime/index.ts";
+/**
+ * What `npm run build` compiles `src/` into — the server's own code, as JavaScript, for `start:prod` to run with no
+ * TypeScript in the process. The same tree: `src/runtime/index.ts` is `dist/runtime/index.js`.
+ */
+export declare const BUILD_DIR = "dist";
+/**
+ * What the running server keeps for the space — its `kv`: saved layouts, counters, a source's cached answer. Not
+ * committed either, but not a by-product: it is the deployment's state, so it is never rebuilt and `tmp/` is no place
+ * for it. A deployment that keeps it elsewhere says so in `src/config/serverOptions.ts` (`action.kv`).
+ */
+export declare const PROJECT_STATE = "state";
+/** The `kv` a project's server keeps, as one JSON file (`createFileKv`). */
+export declare const KV_FILE = "state/kv.json";
+/** The port the server took and the name its `/health` answers with: what `check`, `shot` and `visual` find it by. */
+export declare const DEV_SERVER_FILE = "tmp/dev-server.json";

package/dist/project/paths.mjs

@@ -0,0 +1,4 @@
+//#region src/project/paths.ts
+var e = "tmp", t = "src", n = "plitzi", r = `${n}/author.ts`, i = "src/space", a = `${i}/index.ts`, o = "src/plugins", s = ["index.ts", "index.tsx"], c = "declaration.ts", l = "functions", u = "vendor/plugins", d = "plugin-manifest.json", f = "vendor/runtime.bundle", p = "public", m = "src/data", h = "src/functions", g = "src/runtime", _ = `${g}/index.ts`, v = "dist", y = "state", b = `${y}/kv.json`, x = "tmp/dev-server.json";
+//#endregion
+export { r as AUTHOR_FILE, v as BUILD_DIR, n as CLI_DIR, m as DATA_DIR, x as DEV_SERVER_FILE, h as FUNCTIONS_DIR, b as KV_FILE, o as PLUGINS_DIR, c as PLUGIN_DECLARATION_FILE, s as PLUGIN_ENTRIES, l as PLUGIN_FUNCTIONS_DIR, d as PLUGIN_MANIFEST_FILE, y as PROJECT_STATE, e as PROJECT_TMP, p as PUBLIC_DIR, f as RUNTIME_BUNDLE, g as RUNTIME_DIR, _ as RUNTIME_ENTRY, t as SOURCE_DIR, i as SPACE_DIR, a as SPACE_ENTRY, u as VENDOR_PLUGINS_DIR };

package/dist/project/root.d.ts

@@ -0,0 +1,24 @@
+/** A process started outside the project's root: its message names what is missing, and where to run it instead. */
+export declare class ProjectRootError extends Error {
+    constructor(root: string, missing: readonly string[]);
+}
+/**
+ * `root`, when it is the root of a project `@plitzi/cli` writes; refused otherwise, naming what it lacks. What
+ * `projectRoot` holds the working directory to — and what a tool working on a project from another folder (the CLI, run
+ * anywhere inside one) holds the root it found to.
+ */
+export declare const checkProjectRoot: (root: string) => string;
+/**
+ * The root of the project this process runs: its working directory. Every script of the project's `package.json` runs
+ * there, and a deployment starts `node dist/main.js` there too — so the root is never worked out from where a file is,
+ * and a process started from anywhere else is refused, saying what is missing (`checkProjectRoot`).
+ */
+export declare const projectRoot: () => string;
+/**
+ * Where a module of the project's source (`entry`, under `src/` — `src/space/index.ts`) is, in the form the process
+ * runs in: what `build` emitted (`dist/space/index.js`) when it was started on that — `node dist/main.js`, which carries
+ * no TypeScript at all — and the source otherwise. Told by the script the process was started with (`script`,
+ * `process.argv[1]`), followed through any link, rather than by `NODE_ENV`: a production server run from its source
+ * still finds the source, and one run compiled never imports a `.ts` file.
+ */
+export declare const projectModule: (root: string, entry: string, script: string | undefined) => string;

package/dist/project/root.mjs

@@ -0,0 +1,26 @@
+import { BUILD_DIR as e } from "./paths.mjs";
+import t from "node:path";
+import { existsSync as n, realpathSync as r } from "node:fs";
+//#region src/project/root.ts
+var i = ["package.json", "src/"], a = class extends Error {
+	constructor(e, t) {
+		super(`${e} is not the root of a Plitzi project: it has no ${t.join(" and no ")}. Run it from the project's root, the folder its package.json is in — where its scripts run it (npm start, npm run author).`), this.name = "ProjectRootError";
+	}
+};
+Object.defineProperty(a, "name", { value: "ProjectRootError" });
+var o = (e) => {
+	let r = i.filter((r) => !n(t.join(e, r)));
+	if (r.length > 0) throw new a(e, r);
+	return e;
+}, s = () => o(process.cwd()), c = (e) => {
+	try {
+		return r(e);
+	} catch {
+		return t.resolve(e);
+	}
+}, l = (n, r, i) => {
+	let a = c(t.join(n, e)), o = i !== void 0 && c(i).startsWith(`${a}${t.sep}`);
+	return t.join(n, o ? t.join(e, t.relative("src", r)).replace(/\.tsx?$/, ".js") : r);
+};
+//#endregion
+export { a as ProjectRootError, o as checkProjectRoot, l as projectModule, s as projectRoot };

package/dist/queries/index.d.ts

@@ -1,10 +1,15 @@
 import { default as queryCache, QueryMeta } from './queryCache';
 export { QueryCache, GC_TIME, queryId, queryPath } from './queryCache';
+export { registerServerQuery } from './serverQueries';
 export { default as useQuery } from './useQuery';
+export { default as useServerQuery } from './useServerQuery';
 export type { QueriesState, QueryEntry, QueryMeta, QueryObserverOptions } from './queryCache';
+export type { ServerQuery } from './serverQueries';
 export type { UseQueryOptions, UseQueryResult } from './useQuery';
+export type { UseServerQueryOptions } from './useServerQuery';
 /**
- * Every query that could have read what `url` just wrote: the ones on the same origin.
+ * Every query that could have read what `url` just wrote: the ones on the same origin — a server provider's too, when
+ * it reads a URL.
  *
  * The origin, not the path: `POST /api/cart/items` changes what `GET /api/cart` answers, and no path rule tells
  * those apart from two unrelated resources. Another origin is another backend, and nothing it writes shows up here.
@@ -25,7 +30,12 @@ export type QuerySelector = {
  * template nobody can write down.
  */
 export declare const matchesQuery: ({ url, elements }: QuerySelector) => (meta: QueryMeta) => boolean;
-/** The `invalidateQueries` step, and anything else that knows which data changed. */
+/**
+ * The `invalidateQueries` step, and anything else that knows which data changed.
+ *
+ * Both halves of the page's data: the cached browser requests, and the providers the page server answers, which
+ * never pass through the cache. Either is marked and asks when shown if nobody is looking at it now.
+ */
 export declare const invalidateQueries: (selector?: QuerySelector) => Promise<void>;
 /**
  * One key for one request, whoever makes it — an api container and a webhook step asking the same thing share the

package/dist/queries/index.mjs

@@ -1,37 +1,47 @@
 import e, { GC_TIME as t, QueryCache as n, queryId as r, queryPath as i } from "./queryCache.mjs";
-import a from "./useQuery.mjs";
+import { refreshServerQueries as a, registerServerQuery as o } from "./serverQueries.mjs";
+import s from "./useQuery.mjs";
+import c from "./useServerQuery.mjs";
 //#region src/queries/index.ts
-var o = () => typeof location > "u" ? void 0 : location.href, s = (e) => {
+var l = () => typeof location > "u" ? void 0 : location.href, u = (e) => {
 	try {
-		return new URL(e, o()).origin;
+		return new URL(e, l()).origin;
 	} catch {
 		return;
 	}
-}, c = (t) => {
-	let n = s(t);
-	return n ? e.invalidate((e) => s(e.url) === n) : Promise.resolve();
-}, l = (e) => Array.isArray(e) ? e.filter((e) => typeof e == "string" && e.trim() !== "").map((e) => e.trim()) : typeof e == "string" ? e.split(",").map((e) => e.trim()).filter(Boolean) : [], u = (e) => {
+}, d = (e, t) => ({ id: n, url: r }) => (!t || r !== void 0) && e({
+	url: r ?? "",
+	tags: [n]
+}), f = (t) => {
+	let n = u(t);
+	if (!n) return Promise.resolve();
+	let r = (e) => u(e.url) === n;
+	return Promise.all([e.invalidate(r), a(d(r, !0))]).then(() => void 0);
+}, p = (e) => Array.isArray(e) ? e.filter((e) => typeof e == "string" && e.trim() !== "").map((e) => e.trim()) : typeof e == "string" ? e.split(",").map((e) => e.trim()).filter(Boolean) : [], m = (e) => {
 	try {
-		return new URL(e, o()).href;
+		return new URL(e, l()).href;
 	} catch {
 		return e;
 	}
-}, d = ({ url: e, elements: t }) => {
-	let n = e ? u(e) : void 0;
-	return (e) => (n === void 0 || u(e.url).startsWith(n)) && (!t?.length || t.some((t) => e.tags?.includes(t) ?? !1));
-}, f = (t = {}) => t.url || t.elements?.length ? e.invalidate(d(t)) : e.invalidate(), p = ({ method: e, url: t, credentials: n, headers: r }) => JSON.stringify([
+}, h = ({ url: e, elements: t }) => {
+	let n = e ? m(e) : void 0;
+	return (e) => (n === void 0 || m(e.url).startsWith(n)) && (!t?.length || t.some((t) => e.tags?.includes(t) ?? !1));
+}, g = (t = {}) => {
+	let n = t.url || t.elements?.length ? h(t) : void 0;
+	return Promise.all([e.invalidate(n), a(n && d(n, !!t.url))]).then(() => void 0);
+}, _ = ({ method: e, url: t, credentials: n, headers: r }) => JSON.stringify([
 	e.toLowerCase(),
 	t,
 	n,
 	Object.entries(r).filter(([e]) => e.toLowerCase() !== "content-type").sort(([e], [t]) => e < t ? -1 : +(e > t))
-]), m = ({ mode: e, fallback: t, elements: n, url: r }) => {
+]), v = ({ mode: e, fallback: t, elements: n, url: r }) => {
 	let i = e === "origin" || e === "all" || e === "elements" || e === "none" ? e : t;
 	if (i === "none") return Promise.resolve();
 	if (i === "elements") {
-		let e = l(n);
-		return e.length > 0 ? f({ elements: e }) : Promise.resolve();
+		let e = p(n);
+		return e.length > 0 ? g({ elements: e }) : Promise.resolve();
 	}
-	return i === "origin" && r ? c(r) : f();
+	return i === "origin" && r ? f(r) : g();
 };
 //#endregion
-export { t as GC_TIME, n as QueryCache, m as invalidateAfterWrite, f as invalidateQueries, c as invalidateQueriesForWrite, d as matchesQuery, l as parseIds, e as queryCache, r as queryId, i as queryPath, p as requestKey, a as useQuery };
+export { t as GC_TIME, n as QueryCache, v as invalidateAfterWrite, g as invalidateQueries, f as invalidateQueriesForWrite, h as matchesQuery, p as parseIds, e as queryCache, r as queryId, i as queryPath, o as registerServerQuery, _ as requestKey, s as useQuery, c as useServerQuery };