@plitzi/sdk-shared 0.37.7 → 0.37.9

package/dist/source/export.d.ts

@@ -0,0 +1,107 @@
+import { SpaceVersionContents } from '../types';
+/**
+ * A space taken back out as a project (docs/en/projects-from-spaces.md): everything it is made of that Plitzi keeps, as
+ * `GET /spaces/:spaceId/export` answers it and `plitzi create --from` writes it. One shape for both ends.
+ */
+export declare const SPACE_EXPORT_FORMAT = 1;
+/** A file the project downloads once and serves itself: where it is on the space's CDN, and where it goes. */
+export type SpaceExportFile = {
+    /** Its address on the space's CDN, today. */
+    url: string;
+    /** Where it goes in the project, relative to the folder it is served from: `assets/85a7_world.json`. */
+    path: string;
+};
+/** A path the merge of the source snapshots met more than once, with different content. */
+export type SpaceExportConflict = {
+    path: string;
+    /** The artifact whose copy was kept: the newest snapshot holding the path. */
+    kept: string;
+    /** The others that held a different copy. */
+    others: string[];
+};
+export type SpaceExport = {
+    format: typeof SPACE_EXPORT_FORMAT;
+    space: {
+        id: number;
+        name: string;
+        permanentUrl: string;
+    };
+    /** The version taken out: the draft (`main`, revision 0), or a snapshot an environment holds. */
+    version: Pick<SpaceVersionContents, 'environment' | 'revision' | 'snapshot'>;
+    /** The space as authoring code, by path (`index.ts`, a file per page): none for a project that reads it from Plitzi. */
+    authoring: {
+        exportName: string;
+        files: Record<string, string>;
+    } | null;
+    /**
+     * The server-side documents, as they are kept: a flow and a connector name steps and credentials. Whether an action
+     * is on is its trigger steps', so nothing beside the document says it.
+     */
+    actions: {
+        identifier: string;
+        name: string;
+        document: unknown;
+    }[];
+    connectors: {
+        identifier: string;
+        name: string;
+        manifest: unknown;
+    }[];
+    /**
+     * The space's functions, by path in `functions/`, and the version of them this is — what `plitzi functions push`
+     * checks the space's copy has not moved on from.
+     */
+    functions: {
+        version: string;
+        files: Record<string, string>;
+    };
+    /**
+     * The source its plugins and runtime were built from, merged: every file by its path in the project (bytes in
+     * base64), the packages they need, and where each build starts.
+     */
+    source: {
+        files: Record<string, string>;
+        dependencies: Record<string, string>;
+        runtime: {
+            entries: string[];
+        } | null;
+        plugins: {
+            type: string;
+            entries: string[];
+        }[];
+    };
+    /** What there is no source of: kept built, so the project runs it as it is and cannot change it. */
+    builtOnly: {
+        plugins: {
+            type: string;
+            files: SpaceExportFile[];
+        }[];
+        /** The packed runtime, in base64 — what `@plitzi/sdk-server/runtime` loads. */
+        runtime: string | null;
+    };
+    /** The space's files on its CDN — pictures, fonts, data — for the project to serve itself. */
+    assets: SpaceExportFile[];
+    /** Names the project is given values for: never the values, which stay on the platform. */
+    variables: string[];
+    credentials: {
+        identifier: string;
+        name: string;
+        provider: string;
+    }[];
+    /**
+     * The roles the space declares for its visitors (`settings.visitorRoles`), by name. Who holds them stays on Plitzi:
+     * they are people's addresses, and a server of its own signs people in itself.
+     */
+    visitorRoles: string[];
+    report: {
+        conflicts: SpaceExportConflict[];
+        /** Packages two snapshots ask for at different ranges: the newest's is the one written. */
+        rangeConflicts: {
+            name: string;
+            kept: string;
+            others: string[];
+        }[];
+        /** What the authoring export repaired on the way, in words. */
+        corrections: string[];
+    };
+};

package/dist/source/export.mjs

@@ -0,0 +1,4 @@
+//#region src/source/export.ts
+var e = 1;
+//#endregion
+export { e as SPACE_EXPORT_FORMAT };

package/dist/source/index.d.ts

@@ -0,0 +1,4 @@
+export { readSourceSnapshot, secretIn, sourcePathProblem, SOURCE_SNAPSHOT_FORMAT, SOURCE_SNAPSHOT_LIMITS } from './snapshot';
+export { SPACE_EXPORT_FORMAT } from './export';
+export type { SourceSnapshot, SourceSnapshotKind, SourceSnapshotReading } from './snapshot';
+export type { SpaceExport, SpaceExportConflict, SpaceExportFile } from './export';

package/dist/source/index.mjs

@@ -0,0 +1,3 @@
+import { SPACE_EXPORT_FORMAT as e } from "./export.mjs";
+import { SOURCE_SNAPSHOT_FORMAT as t, SOURCE_SNAPSHOT_LIMITS as n, readSourceSnapshot as r, secretIn as i, sourcePathProblem as a } from "./snapshot.mjs";
+export { t as SOURCE_SNAPSHOT_FORMAT, n as SOURCE_SNAPSHOT_LIMITS, e as SPACE_EXPORT_FORMAT, r as readSourceSnapshot, i as secretIn, a as sourcePathProblem };

package/dist/source/snapshot.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A source snapshot: the files of a project that one artifact — a plugin, a runtime — was built from, as the platform
+ * keeps them beside what was built, so the space can be taken back out as a project (`plitzi create --from`).
+ *
+ * The files are the ones the build reached from its entries, by their path in the project: a plugin and a runtime that
+ * import the same `board/model.ts` each carry it under that one path, and a project put back together from both has it
+ * once. Nothing under `node_modules` is in one — the packages are `dependencies`, by name and range.
+ *
+ * One shape for everybody that touches one: the CLI that packs it, the seeder, and the platform that refuses one it
+ * should not keep.
+ */
+export declare const SOURCE_SNAPSHOT_FORMAT = 1;
+export type SourceSnapshotKind = 'plugin' | 'runtime';
+export type SourceSnapshot = {
+    format: typeof SOURCE_SNAPSHOT_FORMAT;
+    kind: SourceSnapshotKind;
+    /** The plugin's type, or `runtime`. */
+    name: string;
+    /** Where the build started, by path in the project: a plugin of several elements has one per element. */
+    entries: string[];
+    /** Every file the build reached, by path in the project, its bytes in base64 — fonts and pictures travel too. */
+    files: Record<string, string>;
+    /** The packages those files import, by name, with the range the project asked for. */
+    dependencies: Record<string, string>;
+};
+/** How much one snapshot may hold: source, not data. */
+export declare const SOURCE_SNAPSHOT_LIMITS: {
+    files: number;
+    fileBytes: number;
+    totalBytes: number;
+};
+/**
+ * Why `file` is not a path a snapshot may hold, or nothing: relative to the project, inside it, never in a package or a
+ * repository's own folder, and never a file of credentials.
+ */
+export declare const sourcePathProblem: (file: string) => string | undefined;
+/** What in `text` looks like a credential, by what it is — or nothing. */
+export declare const secretIn: (text: string) => string | undefined;
+export type SourceSnapshotReading = {
+    ok: true;
+    snapshot: SourceSnapshot;
+} | {
+    ok: false;
+    problems: string[];
+};
+/**
+ * A snapshot read from what was sent, checked whole: its shape, every path, the limits, and no credentials in any file
+ * — `decode` turns a file's base64 into text for that last check, since how is the reader's (Node or the browser).
+ * Every problem is said at once, so one round fixes them all.
+ */
+export declare const readSourceSnapshot: (value: unknown, decode: (base64: string) => string) => SourceSnapshotReading;

package/dist/source/snapshot.mjs

@@ -0,0 +1,80 @@
+//#region src/source/snapshot.ts
+var e = 1, t = {
+	files: 2e3,
+	fileBytes: 4194304,
+	totalBytes: 25165824
+}, n = ["plugin", "runtime"], r = [
+	/(^|\/)\.env(\.|$)/,
+	/\.(pem|key|p12|pfx)$/i,
+	/(^|\/)id_(rsa|dsa|ecdsa|ed25519)$/
+], i = [
+	{
+		what: "a private key",
+		pattern: /-----BEGIN (?:[A-Z]+ )?PRIVATE KEY-----/
+	},
+	{
+		what: "an AWS access key",
+		pattern: /\bAKIA[0-9A-Z]{16}\b/
+	},
+	{
+		what: "a Stripe live key",
+		pattern: /\b[sr]k_live_[0-9a-zA-Z]{20,}\b/
+	},
+	{
+		what: "a GitHub token",
+		pattern: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/
+	},
+	{
+		what: "a Slack token",
+		pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/
+	}
+], a = (e) => {
+	let t = e.split("/");
+	if (!e || e.startsWith("/") || /^[a-zA-Z]:/.test(e) || e.includes("\\")) return `"${e}" is not a path relative to the project, with forward slashes`;
+	if (t.some((e) => e === "" || e === "." || e === "..")) return `"${e}" climbs out of the project, or has an empty part`;
+	if (t.some((e) => e === "node_modules" || e === ".git")) return `"${e}" is in node_modules or .git: a package is a dependency, not a file of the project`;
+	if (r.some((t) => t.test(e))) return `"${e}" is a file of credentials: they stay where the project runs, never in what Plitzi keeps`;
+}, o = (e) => i.find(({ pattern: t }) => t.test(e))?.what, s = (e) => typeof e == "string" && n.some((t) => t === e), c = (e) => typeof e == "string" && /^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(e), l = (e) => Array.isArray(e) && e.length > 0 && e.every((e) => typeof e == "string"), u = (e) => typeof e == "object" && !!e && !Array.isArray(e), d = (e) => u(e) && Object.values(e).every((e) => typeof e == "string"), f = (e) => Math.floor(e.length * 3 / 4) - (e.endsWith("==") ? 2 : +!!e.endsWith("=")), p = (e, r) => {
+	if (!u(e) || e.format !== 1) return {
+		ok: !1,
+		problems: ["Not a source snapshot of format 1"]
+	};
+	let { kind: i, name: p, entries: m, files: h, dependencies: g } = e, _ = [];
+	if (s(i) || _.push(`Its kind is one of ${n.join(", ")}`), c(p) || _.push("Its name is a plugin type or \"runtime\": letters, digits, dashes and underscores"), !d(h) || !d(g)) return {
+		ok: !1,
+		problems: [..._, "Its files and dependencies are maps of text"]
+	};
+	l(m) ? m.filter((e) => !Object.hasOwn(h, e)).forEach((e) => _.push(`Its entry "${e}" is not among its files`)) : _.push("It names at least one entry");
+	let v = Object.keys(h);
+	v.length > t.files && _.push(`It holds ${String(v.length)} files; a snapshot holds at most ${String(t.files)}`);
+	let y = 0;
+	return v.forEach((e) => {
+		let n = a(e);
+		if (n) {
+			_.push(n);
+			return;
+		}
+		let i = f(h[e]);
+		if (y += i, i > t.fileBytes) {
+			_.push(`"${e}" is ${(i / 1024 / 1024).toFixed(1)} MB; a file of source is at most 4 MB`);
+			return;
+		}
+		let s = o(r(h[e]));
+		s && _.push(`"${e}" holds ${s}: take it out of the code and give it to the project as a variable`);
+	}), y > t.totalBytes && _.push(`It holds ${(y / 1024 / 1024).toFixed(1)} MB of files; a snapshot holds at most 24 MB`), _.length > 0 || !s(i) || !c(p) || !l(m) ? {
+		ok: !1,
+		problems: _
+	} : {
+		ok: !0,
+		snapshot: {
+			format: 1,
+			kind: i,
+			name: p,
+			entries: m,
+			files: h,
+			dependencies: g
+		}
+	};
+};
+//#endregion
+export { e as SOURCE_SNAPSHOT_FORMAT, t as SOURCE_SNAPSHOT_LIMITS, p as readSourceSnapshot, o as secretIn, a as sourcePathProblem };