@plitzi/sdk-shared 0.38.6 → 0.38.8

package/dist/project/layout.d.ts

@@ -0,0 +1,197 @@
+/**
+ * The project's layout held to what reads it: every folder the server builds, runs or serves from where the CLI puts
+ * it, each with the file it starts at. One check, said the same by the three that read the project — its server at
+ * boot (`serveProject`), its authoring (`projectAuthoring`: `npm run author` and the CLI's checks) and `plitzi doctor`,
+ * which makes the fixes that have one reading (`autofix`). Pure file system: what a file holds is never imported.
+ *
+ * An `error` is what keeps a part of the project from running — a plugin the server cannot build, code in a folder
+ * nothing reads, settings Node never loads — and stops the server and the authoring; a `warning` works, and should not
+ * stay.
+ */
+export type LayoutLevel = 'error' | 'warning';
+/** Every finding of the layout check, by its code: how much it matters, and what it means in a line. */
+export declare const PROJECT_LAYOUT_CODES: {
+    readonly 'plugin-entry-missing': {
+        readonly level: "error";
+        readonly means: "a folder of src/plugins/ with no index.ts (or index.tsx), which the server builds the plugin from";
+    };
+    readonly 'plugin-entry-ambiguous': {
+        readonly level: "error";
+        readonly means: "a folder of src/plugins/ with both index.ts and index.tsx: a plugin starts at one";
+    };
+    readonly 'entry-not-typescript': {
+        readonly level: "error";
+        readonly means: "an entry the server builds or runs written as JavaScript (index.js, .jsx, .mjs, .cjs): the project is TypeScript";
+    };
+    readonly 'plugin-name-invalid': {
+        readonly level: "error";
+        readonly means: "a folder of src/plugins/ whose name cannot be an element type: a letter, then letters and digits";
+    };
+    readonly 'plugin-type-taken': {
+        readonly level: "error";
+        readonly means: "two folders of src/plugins/ that are the same element type (StoryEditor and storyEditor)";
+    };
+    readonly 'plugin-shadowed': {
+        readonly level: "error";
+        readonly means: "a plugin both in src/plugins/ and, as it was built, in vendor/plugins/: the built one runs";
+    };
+    readonly 'plugin-functions-entry-missing': {
+        readonly level: "error";
+        readonly means: "a plugin’s functions/ with code and no index.ts, which its server half is built from";
+    };
+    readonly 'functions-entry-missing': {
+        readonly level: "error";
+        readonly means: "src/functions/ with code and no index.ts, which the project’s functions are built from";
+    };
+    readonly 'runtime-entry-missing': {
+        readonly level: "error";
+        readonly means: "src/runtime/ with code and no index.ts, which the space’s runtime starts at";
+    };
+    readonly 'space-entry-missing': {
+        readonly level: "error";
+        readonly means: "a space written in the project with no src/space/index.ts, which the server and npm run author import";
+    };
+    readonly 'space-default-export': {
+        readonly level: "error";
+        readonly means: "src/space/index.ts exporting the space by default, where it is imported by name: `space`";
+    };
+    readonly 'vendor-manifest-missing': {
+        readonly level: "error";
+        readonly means: "a built plugin (vendor/plugins/<type>/) with no plugin-manifest.json";
+    };
+    readonly 'vendor-manifest-invalid': {
+        readonly level: "error";
+        readonly means: "a built plugin’s plugin-manifest.json that is not a manifest";
+    };
+    readonly 'vendor-script-missing': {
+        readonly level: "error";
+        readonly means: "a built plugin’s manifest naming no script to run, or one that is not there";
+    };
+    readonly 'env-in-src': {
+        readonly level: "error";
+        readonly means: ".env inside src/: Node reads the project’s settings from the .env at its root";
+    };
+    readonly 'folder-misplaced': {
+        readonly level: "error";
+        readonly means: "code in a folder named like one the server reads (src/plugin/, plugins/ at the root): nothing reads it";
+    };
+    readonly 'folder-near-miss': {
+        readonly level: "warning";
+        readonly means: "a folder named like one the server reads (src/Data/, src/runtimes/), which nothing reads";
+    };
+    readonly 'plugin-declaration-missing': {
+        readonly level: "warning";
+        readonly means: "a plugin folder with no declaration.ts: the space’s use of the plugin is held to nothing";
+    };
+    readonly 'plugin-file-loose': {
+        readonly level: "warning";
+        readonly means: "a file directly in src/plugins/, where every plugin is a folder";
+    };
+    readonly 'data-not-json': {
+        readonly level: "warning";
+        readonly means: "a file of src/data/ that is not JSON, which no provider and no ctx.data reads";
+    };
+    readonly 'env-missing': {
+        readonly level: "warning";
+        readonly means: "no .env at the project’s root: none of its settings is set";
+    };
+    readonly 'env-example-missing': {
+        readonly level: "warning";
+        readonly means: "no .env.example: a clone does not know what .env must hold";
+    };
+    readonly 'public-data': {
+        readonly level: "warning";
+        readonly means: "JSON in public/data/ of a project with a server: served to anyone who asks";
+    };
+    readonly 'public-secret-file': {
+        readonly level: "warning";
+        readonly means: "a file in public/ named like a secret (.env, a key, a dump): served to anyone who asks";
+    };
+};
+export type LayoutCode = keyof typeof PROJECT_LAYOUT_CODES;
+/**
+ * The fix of a finding that has one reading, for `plitzi doctor --fix` to make. Paths are relative to the root, a
+ * folder's ending in `/`: a `move` of a folder takes everything under it, into a folder that may already be there.
+ */
+export type LayoutAutofix = {
+    action: 'move';
+    from: string;
+    to: string;
+} | {
+    action: 'copy';
+    from: string;
+    to: string;
+} | {
+    action: 'write';
+    file: string;
+    contents: string;
+};
+/** One thing out of place: where (`file`, relative to the root), what is wrong, and what to do — the command, if any. */
+export interface LayoutFinding {
+    level: LayoutLevel;
+    code: LayoutCode;
+    file: string;
+    message: string;
+    fix: string;
+    autofix?: LayoutAutofix;
+}
+export interface ProjectLayoutOptions {
+    /** Whether the project runs a server of its own — told by its `@plitzi/sdk-server` dependency when left out. */
+    mode?: 'server' | 'client';
+    /** Where its space is: written in it (`src/space/`), or kept on Plitzi — told by its files when left out. */
+    space?: 'local' | 'cloud';
+}
+/** `src/plugins/StatCard` is the plugin `statCard`: what the server registers a folder as. */
+export declare const pluginTypeOf: (folder: string) => string;
+/**
+ * The file an element's folder is built from, wherever the folder is — its `index.ts`, or `index.tsx` — or nothing
+ * when it has neither, or both: what `plitzi plugin pack` builds a folder from, as the server does.
+ */
+export declare const elementEntry: (dir: string) => string | undefined;
+/**
+ * The file a folder of `src/plugins/` is built from (`elementEntry`) — or nothing when it is no plugin the server can
+ * build: a name that is no element type, no entry, or both. What the server registers, and what `checkPluginFolder`
+ * says why of.
+ */
+export declare const pluginEntry: (root: string, folder: string) => string | undefined;
+/**
+ * One folder of `src/plugins/` as the server reads it: a name that is a type, the entry it is built from, its server
+ * half's entry, and its declaration. What the server says of a folder added while it runs, and what
+ * `checkProjectLayout` says of each.
+ */
+export declare const checkPluginFolder: (root: string, folder: string) => LayoutFinding[];
+/** What a built plugin runs, by absolute path: its script, its style and its server half, as its manifest names them. */
+export interface VendorPlugin {
+    script: string;
+    style?: string;
+    version: string;
+    functions?: string;
+}
+/**
+ * A plugin of `vendor/plugins/` — one a project made from a space runs as it was built, beside the manifest `plitzi
+ * pack plugin` wrote when it was published — or what keeps it from running.
+ */
+export declare const readVendorPlugin: (root: string, type: string) => VendorPlugin | {
+    problem: LayoutFinding;
+};
+/**
+ * Everything out of place in the project at `root`, errors first: what its server, its authoring and `plitzi doctor`
+ * say of its layout. `PROJECT_LAYOUT_CODES` says what each code means.
+ */
+export declare const checkProjectLayout: (root: string, options?: ProjectLayoutOptions) => LayoutFinding[];
+/** One finding as the terminal says it: what is wrong, then what to do. */
+export declare const layoutFindingText: (layoutFinding: LayoutFinding) => string;
+/**
+ * The errors of a project's layout, every one at once: what its server and its authoring refuse to start with.
+ * `findings` holds them as data, for a tool that says them its own way.
+ */
+export declare class ProjectLayoutError extends Error {
+    #private;
+    get findings(): readonly LayoutFinding[];
+    constructor(findings: readonly LayoutFinding[]);
+}
+/**
+ * The project's layout, refused with every error at once (`ProjectLayoutError`) — what its server and its authoring
+ * check before anything else — and its warnings answered, for the caller to say.
+ */
+export declare const assertProjectLayout: (root: string, options?: ProjectLayoutOptions) => LayoutFinding[];

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 plugin add 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 plugin add 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 plugin add --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 space 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 plugin add 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 space 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 runtime add 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 };