@plitzi/sdk-shared 0.38.5 → 0.38.7

package/dist/network/spaceEvents.mjs

@@ -2,163 +2,166 @@ import { isRecord as e } from "../helpers/isRecord.mjs";
 import { isSchemaFlag as t } from "../flags/schemaFlag.mjs";
 import { StyleVariableCategory as n } from "../types/StyleTypes.mjs";
 import { DISPLAY_MODES as r } from "../style/displayModes.mjs";
-import { STYLE_STATES as i } from "../style/styleStates.mjs";
-import { elementFromWire as a, schemaFromWire as o, schemaToWire as s } from "../schema/wire.mjs";
-import { z as c } from "zod";
+import { STYLE_PSEUDOS as i } from "../style/stylePseudos.mjs";
+import { STYLE_STATES as a } from "../style/styleStates.mjs";
+import { elementFromWire as o, schemaFromWire as s, schemaToWire as c } from "../schema/wire.mjs";
+import { z as l } from "zod";
 //#region src/network/spaceEvents.ts
-var l = c.custom((t) => e(t) && typeof t.id == "string", { message: "expected an element with an id" }), u = c.array(l), d = c.custom((t) => e(t) && typeof t.id == "string" && e(t.flat), { message: "expected a component with an id and a flat" }), f = c.custom((t) => e(t) && Array.isArray(t.flat), { message: "expected a schema whose `flat` is a list of elements" }), p = c.custom((t) => e(t) && typeof t.id == "string", { message: "expected a page folder with an id" }), m = c.custom((t) => e(t) && typeof t.name == "string", { message: "expected a variable with a name" }), h = c.custom(t, { message: "expected a flag with a value and its rules" }), g = c.custom(e, { message: "expected a style attributes object" }), _ = c.custom((t) => e(t) && typeof t.family == "string" && typeof t.source == "string", { message: "expected a font with a family and a source" }), v = c.custom((t) => typeof t == "string" || typeof t == "number" || e(t), { message: "expected a style variable value" }), y = c.enum(r), b = c.custom((e) => typeof e == "string", { message: "expected a drop position" }), x = c.custom((e) => typeof e == "string", { message: "expected a style category" }), S = c.enum([
+var u = l.custom((t) => e(t) && typeof t.id == "string", { message: "expected an element with an id" }), d = l.array(u), f = l.custom((t) => e(t) && typeof t.id == "string" && e(t.flat), { message: "expected a component with an id and a flat" }), p = l.custom((t) => e(t) && Array.isArray(t.flat), { message: "expected a schema whose `flat` is a list of elements" }), m = l.custom((t) => e(t) && typeof t.id == "string", { message: "expected a page folder with an id" }), h = l.custom((t) => e(t) && typeof t.name == "string", { message: "expected a variable with a name" }), g = l.custom(t, { message: "expected a flag with a value and its rules" }), _ = l.custom(e, { message: "expected a style attributes object" }), v = l.custom((t) => e(t) && typeof t.family == "string" && typeof t.source == "string", { message: "expected a font with a family and a source" }), y = l.custom((t) => typeof t == "string" || typeof t == "number" || e(t), { message: "expected a style variable value" }), b = l.enum(r), x = l.custom((e) => typeof e == "string", { message: "expected a drop position" }), S = l.custom((e) => typeof e == "string", { message: "expected a style category" }), C = l.enum([
 	"class",
 	"element",
 	"id"
-]), C = c.enum(i), w = c.enum(n), T = c.object({
-	componentType: c.string().optional(),
-	styleSelector: c.string().optional(),
-	styleState: C.optional(),
-	styleVariant: c.string().optional(),
-	styleAncestor: c.string().optional()
-}), E = T.extend({ styleSelector: c.string() }), D = c.object({ variable: m }), O = c.object({
-	displayMode: y,
-	selector: c.string(),
-	category: w,
-	name: c.string(),
-	value: v
-}), k = c.object({
-	displayMode: y,
-	selector: c.string(),
-	category: w,
-	name: c.string()
-}), A = c.object({
-	category: w,
-	name: c.string(),
-	value: v
-}), j = c.object({
-	type: c.string(),
-	resource: c.string(),
-	settings: c.custom(e, { message: "expected a plugin settings object" })
-}), M = {
-	SPACE_UPDATED: c.object({ schema: f }),
-	STYLE_UPDATED: c.object({
-		platform: c.custom(e),
-		variables: c.custom(e),
-		cache: c.string()
-	}),
-	SPACE_ADD_PAGE: c.object({ page: l }),
-	SPACE_UPDATE_PAGE: c.object({ page: l }),
-	SPACE_SET_HOME_PAGE: c.object({ page: l }),
-	SPACE_REMOVE_PAGE: c.object({ pageId: c.string() }),
-	SPACE_ADD_PAGE_FOLDER: c.object({ pageFolder: p }),
-	SPACE_UPDATE_PAGE_FOLDER: c.object({ pageFolder: p }),
-	SPACE_REMOVE_PAGE_FOLDER: c.object({ pageFolderId: c.string() }),
-	SPACE_ADD_VARIABLE: D,
-	SPACE_UPDATE_VARIABLE: D,
-	SPACE_REMOVE_VARIABLE: c.object({ name: c.string() }),
-	SPACE_SET_FLAG: c.object({
-		name: c.string(),
-		flag: h
-	}),
-	SPACE_REMOVE_FLAG: c.object({ name: c.string() }),
-	SPACE_ADD_ELEMENT: c.object({
-		element: l,
-		dropPosition: b,
-		to: c.string(),
-		initialItems: u.optional(),
-		variables: c.array(m).optional()
-	}),
-	SPACE_UPDATE_ELEMENT: c.object({ element: l }),
-	SPACE_RENAME_ELEMENT: c.object({
-		elementId: c.string(),
-		id: c.string()
-	}),
-	SPACE_UPDATE_ELEMENTS: c.object({ elements: u }),
-	SPACE_REMOVE_ELEMENT: c.object({ elementId: c.string() }),
-	SPACE_MOVE_ELEMENT: c.object({
-		from: c.string(),
-		to: c.string(),
-		elementId: c.string(),
-		dropPosition: b
-	}),
-	SPACE_CLONE_ELEMENT: c.object({
-		to: c.string(),
-		element: l,
-		dropPosition: b,
-		initialItems: u
-	}),
-	SPACE_ADD_SNIPPET: c.object({
-		element: l,
-		style: c.custom(e),
-		to: c.string(),
-		dropPosition: b,
-		initialItems: u.optional(),
-		variables: c.array(m).optional()
-	}),
-	SPACE_ADD_PLUGIN: c.object({ plugin: j }),
-	SPACE_UPDATE_PLUGIN: c.object({ plugin: j }),
-	SPACE_REMOVE_PLUGIN: c.object({ pluginType: c.string() }),
-	SPACE_UPDATE_SETTINGS: c.object({
-		path: c.string(),
-		value: c.union([
-			c.string(),
-			c.number(),
-			c.boolean()
+]), w = l.enum(a), T = l.enum(n), E = l.object({
+	componentType: l.string().optional(),
+	styleSelector: l.string().optional(),
+	styleState: w.optional(),
+	styleVariant: l.string().optional(),
+	styleAncestor: l.string().optional(),
+	stylePseudo: l.enum(i).optional(),
+	styleCondition: l.string().optional()
+}), D = E.extend({ styleSelector: l.string() }), O = l.object({ variable: h }), k = l.object({
+	displayMode: b,
+	selector: l.string(),
+	category: T,
+	name: l.string(),
+	value: y
+}), A = l.object({
+	displayMode: b,
+	selector: l.string(),
+	category: T,
+	name: l.string()
+}), j = l.object({
+	category: T,
+	name: l.string(),
+	value: y
+}), M = l.object({
+	type: l.string(),
+	resource: l.string(),
+	settings: l.custom(e, { message: "expected a plugin settings object" })
+}), N = {
+	SPACE_UPDATED: l.object({ schema: p }),
+	STYLE_UPDATED: l.object({
+		platform: l.custom(e),
+		variables: l.custom(e),
+		cache: l.string()
+	}),
+	SPACE_ADD_PAGE: l.object({ page: u }),
+	SPACE_UPDATE_PAGE: l.object({ page: u }),
+	SPACE_SET_HOME_PAGE: l.object({ page: u }),
+	SPACE_REMOVE_PAGE: l.object({ pageId: l.string() }),
+	SPACE_ADD_PAGE_FOLDER: l.object({ pageFolder: m }),
+	SPACE_UPDATE_PAGE_FOLDER: l.object({ pageFolder: m }),
+	SPACE_REMOVE_PAGE_FOLDER: l.object({ pageFolderId: l.string() }),
+	SPACE_ADD_VARIABLE: O,
+	SPACE_UPDATE_VARIABLE: O,
+	SPACE_REMOVE_VARIABLE: l.object({ name: l.string() }),
+	SPACE_SET_FLAG: l.object({
+		name: l.string(),
+		flag: g
+	}),
+	SPACE_REMOVE_FLAG: l.object({ name: l.string() }),
+	SPACE_ADD_ELEMENT: l.object({
+		element: u,
+		dropPosition: x,
+		to: l.string(),
+		initialItems: d.optional(),
+		variables: l.array(h).optional()
+	}),
+	SPACE_UPDATE_ELEMENT: l.object({ element: u }),
+	SPACE_RENAME_ELEMENT: l.object({
+		elementId: l.string(),
+		id: l.string()
+	}),
+	SPACE_UPDATE_ELEMENTS: l.object({ elements: d }),
+	SPACE_REMOVE_ELEMENT: l.object({ elementId: l.string() }),
+	SPACE_MOVE_ELEMENT: l.object({
+		from: l.string(),
+		to: l.string(),
+		elementId: l.string(),
+		dropPosition: x
+	}),
+	SPACE_CLONE_ELEMENT: l.object({
+		to: l.string(),
+		element: u,
+		dropPosition: x,
+		initialItems: d
+	}),
+	SPACE_ADD_SNIPPET: l.object({
+		element: u,
+		style: l.custom(e),
+		to: l.string(),
+		dropPosition: x,
+		initialItems: d.optional(),
+		variables: l.array(h).optional()
+	}),
+	SPACE_ADD_PLUGIN: l.object({ plugin: M }),
+	SPACE_UPDATE_PLUGIN: l.object({ plugin: M }),
+	SPACE_REMOVE_PLUGIN: l.object({ pluginType: l.string() }),
+	SPACE_UPDATE_SETTINGS: l.object({
+		path: l.string(),
+		value: l.union([
+			l.string(),
+			l.number(),
+			l.boolean()
 		])
 	}),
-	STYLE_ADD_SELECTOR: c.object({
-		displayMode: y,
-		selector: c.string(),
-		path: x.optional(),
-		type: S,
-		style: g.optional(),
-		params: T
-	}),
-	STYLE_UPDATE_SELECTOR: c.object({
-		displayMode: y,
-		selector: c.string(),
-		path: x.optional(),
-		style: g.optional(),
+	STYLE_ADD_SELECTOR: l.object({
+		displayMode: b,
+		selector: l.string(),
+		path: S.optional(),
+		type: C,
+		style: _.optional(),
 		params: E
 	}),
-	STYLE_REMOVE_SELECTOR: c.object({
-		displayMode: y,
-		selector: c.string()
-	}),
-	STYLE_REMOVE_SELECTORS: c.object({
-		displayMode: y,
-		selectors: c.array(c.string())
-	}),
-	STYLE_ADD_SELECTOR_VARIABLE: O,
-	STYLE_UPDATE_SELECTOR_VARIABLE: O,
-	STYLE_REMOVE_SELECTOR_VARIABLE: k,
-	STYLE_ADD_VARIABLE: A,
-	STYLE_UPDATE_VARIABLE: A,
-	STYLE_REMOVE_VARIABLE: c.object({
-		category: w,
-		name: c.string()
-	}),
-	STYLE_UPDATE_SETTINGS: c.object({
-		path: c.string(),
-		value: c.string()
-	}),
-	STYLE_ADD_FONT: c.object({ font: _ }),
-	STYLE_UPDATE_FONT: c.object({
-		family: c.string(),
-		font: _
-	}),
-	STYLE_REMOVE_FONT: c.object({ family: c.string() }),
-	SPACE_ADD_COMPONENT: c.object({
-		component: d,
-		from: c.object({
-			elementId: c.string(),
-			instanceId: c.string()
+	STYLE_UPDATE_SELECTOR: l.object({
+		displayMode: b,
+		selector: l.string(),
+		path: S.optional(),
+		style: _.optional(),
+		params: D
+	}),
+	STYLE_REMOVE_SELECTOR: l.object({
+		displayMode: b,
+		selector: l.string()
+	}),
+	STYLE_REMOVE_SELECTORS: l.object({
+		displayMode: b,
+		selectors: l.array(l.string())
+	}),
+	STYLE_ADD_SELECTOR_VARIABLE: k,
+	STYLE_UPDATE_SELECTOR_VARIABLE: k,
+	STYLE_REMOVE_SELECTOR_VARIABLE: A,
+	STYLE_ADD_VARIABLE: j,
+	STYLE_UPDATE_VARIABLE: j,
+	STYLE_REMOVE_VARIABLE: l.object({
+		category: T,
+		name: l.string()
+	}),
+	STYLE_UPDATE_SETTINGS: l.object({
+		path: l.string(),
+		value: l.string()
+	}),
+	STYLE_ADD_FONT: l.object({ font: v }),
+	STYLE_UPDATE_FONT: l.object({
+		family: l.string(),
+		font: v
+	}),
+	STYLE_REMOVE_FONT: l.object({ family: l.string() }),
+	SPACE_ADD_COMPONENT: l.object({
+		component: f,
+		from: l.object({
+			elementId: l.string(),
+			instanceId: l.string()
 		}).optional()
 	}),
-	SPACE_UPDATE_COMPONENT: c.object({
-		componentId: c.string(),
-		declaration: c.custom(e)
+	SPACE_UPDATE_COMPONENT: l.object({
+		componentId: l.string(),
+		declaration: l.custom(e)
 	}),
-	SPACE_REMOVE_COMPONENT: c.object({ componentId: c.string() }),
-	SPACE_DETACH_INSTANCE: c.object({ instanceId: c.string() })
-}, N = Object.fromEntries(Object.keys(M).map((e) => [e, e])), P = (e, t) => {
-	let n = M[e];
+	SPACE_REMOVE_COMPONENT: l.object({ componentId: l.string() }),
+	SPACE_DETACH_INSTANCE: l.object({ instanceId: l.string() })
+}, P = Object.fromEntries(Object.keys(N).map((e) => [e, e])), F = (e, t) => {
+	let n = N[e];
 	if (!n) return {
 		ok: !1,
 		issues: [{
@@ -179,4 +182,4 @@ var l = c.custom((t) => e(t) && typeof t.id == "string", { message: "expected an
 	};
 };
 //#endregion
-export { N as SpaceEvents, N as default, a as elementFromWire, o as schemaFromWire, s as schemaToWire, M as spaceEventSchemas, P as validateSpaceEvent };
+export { P as SpaceEvents, P as default, o as elementFromWire, s as schemaFromWire, c as schemaToWire, N as spaceEventSchemas, F as validateSpaceEvent };

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 pack plugin` 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[];