@lantharos/pult 0.0.0-stage → 0.9.0

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@lantharos/pult",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.0",
+  "description": "The other side of your app",
+  "license": "MIT",
+  "keywords": [
+    "back office",
+    "admin panel",
+    "internal tools",
+    "console",
+    "feature flags",
+    "status page"
+  ],
+  "homepage": "https://pult.sh",
+  "bugs": "https://github.com/Lantharos/Pult/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lantharos/Pult.git",
+    "directory": "packages/pult"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.17.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.mts",
+      "default": "./index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "pult": "./cli.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "jiti": "2.7.0",
+    "@standard-schema/spec": "1.1.0",
+    "croner": "10.0.1"
+  }
+}

package/schema-DuTVNptF.mjs

@@ -0,0 +1,661 @@
+//#region ../protocol/src/manifest.ts
+const HOME = "home";
+const FLAG_ACTION = "flag:";
+const DEFAULT_STATES = [
+	"open",
+	"in progress",
+	"handled"
+];
+function actionId(resource, action) {
+	return `${resource}.${action}`;
+}
+function splitAction(id) {
+	const dot = id.indexOf(".");
+	return dot === -1 ? {
+		resource: null,
+		name: id
+	} : {
+		resource: id.slice(0, dot),
+		name: id.slice(dot + 1)
+	};
+}
+function findActionDef(manifest, id) {
+	const { resource, name } = splitAction(id);
+	if (!manifest) return null;
+	return (resource === null ? manifest.actions[name] : manifest.resources[resource]?.actions[name]) ?? null;
+}
+//#endregion
+//#region ../protocol/src/blocks.ts
+function eachBlock(blocks, visit) {
+	for (const block of blocks) {
+		visit(block);
+		if (block.type === "columns") for (const column of block.columns) eachBlock(column, visit);
+	}
+}
+function mapBlocks(blocks, map) {
+	return blocks.flatMap((block) => {
+		const mapped = map(block);
+		if (!mapped) return [];
+		if (mapped.type !== "columns") return [mapped];
+		return [{
+			type: "columns",
+			columns: mapped.columns.map((column) => mapBlocks(column, map))
+		}];
+	});
+}
+function valuesIn(block) {
+	switch (block.type) {
+		case "fields": return block.fields.map((field) => field.value);
+		case "stats": return block.stats.map((stat) => stat.value);
+		case "table": return block.rows.flat();
+		default: return [];
+	}
+}
+function shownValue(value) {
+	return value && typeof value === "object" && "edit" in value ? value.edit.value : value;
+}
+//#endregion
+//#region ../protocol/src/signing.ts
+const SIGNATURE_TOLERANCE_MS = 3e5;
+const encoder = new TextEncoder();
+function parseKey(key) {
+	const match = /^pult_([a-z0-9]+)_([A-Za-z0-9_-]{32,})$/.exec(key.trim());
+	if (!match) throw new Error("Malformed Pult key");
+	return {
+		environment: match[1],
+		secret: match[2]
+	};
+}
+function randomToken(bytes = 32) {
+	return base64url(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+async function sha256(data) {
+	const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+	const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+	return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function base64url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+const keyCache = /* @__PURE__ */ new Map();
+function hmacKey(secret) {
+	let key = keyCache.get(secret);
+	if (!key) {
+		key = crypto.subtle.importKey("raw", encoder.encode(secret), {
+			name: "HMAC",
+			hash: "SHA-256"
+		}, false, ["sign", "verify"]);
+		keyCache.set(secret, key);
+	}
+	return key;
+}
+function payload(scope, timestamp, nonce, body) {
+	return encoder.encode(`${scope}\n${timestamp}\n${nonce}\n${body}`);
+}
+async function sign(secret, scope, body) {
+	const timestamp = String(Date.now());
+	const nonce = randomToken(16);
+	const mac = await crypto.subtle.sign("HMAC", await hmacKey(secret), payload(scope, timestamp, nonce, body));
+	return {
+		timestamp,
+		nonce,
+		signature: base64url(new Uint8Array(mac))
+	};
+}
+async function verify(secret, scope, body, headers, now = Date.now()) {
+	const timestamp = Number(headers.timestamp);
+	if (!Number.isFinite(timestamp) || Math.abs(now - timestamp) > 3e5) return "stale";
+	const mac = fromBase64url(headers.signature);
+	if (!mac) return "invalid";
+	return await crypto.subtle.verify("HMAC", await hmacKey(secret), mac, payload(scope, headers.timestamp, headers.nonce, body)) ? null : "invalid";
+}
+function fromBase64url(value) {
+	try {
+		const binary = atob(value.replaceAll("-", "+").replaceAll("_", "/"));
+		return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+	} catch {
+		return null;
+	}
+}
+var NonceWindow = class {
+	ttl;
+	#seen = /* @__PURE__ */ new Map();
+	constructor(ttl = SIGNATURE_TOLERANCE_MS * 2) {
+		this.ttl = ttl;
+	}
+	claim(nonce, now = Date.now()) {
+		for (const [seen, at] of this.#seen) {
+			if (now - at < this.ttl) break;
+			this.#seen.delete(seen);
+		}
+		if (this.#seen.has(nonce)) return false;
+		this.#seen.set(nonce, now);
+		return true;
+	}
+};
+//#endregion
+//#region ../protocol/src/wire.ts
+function refKey(ref) {
+	return `${ref.resource}:${ref.id}`;
+}
+const HEADER = {
+	environment: "pult-environment",
+	timestamp: "pult-timestamp",
+	nonce: "pult-nonce",
+	signature: "pult-signature"
+};
+//#endregion
+//#region src/define/core.ts
+const KIND = Symbol.for("pult.kind");
+const TRACING = Symbol.for("pult.tracing");
+const FRAME = /\(?((?:file:\/\/)?[^()\s]+?):(\d+):\d+\)?\s*$/;
+const RUNTIME = /^node:|[\\/]jiti[\\/]/;
+const UNKNOWN = {
+	file: "",
+	line: 0
+};
+const flags = globalThis;
+async function traceOrigins(work) {
+	flags[TRACING] = true;
+	try {
+		return await work();
+	} finally {
+		flags[TRACING] = false;
+	}
+}
+function captureOrigin() {
+	if (!flags[TRACING]) return UNKNOWN;
+	const [own, ...callers] = ((/* @__PURE__ */ new Error()).stack?.split("\n").slice(1) ?? []).flatMap(parseFrame);
+	if (!own) return UNKNOWN;
+	const sdk = own.file.replace(/[^\\/]*$/, "");
+	return callers.find(({ file }) => !file.startsWith(sdk) && !RUNTIME.test(file)) ?? UNKNOWN;
+}
+function parseFrame(frame) {
+	const match = FRAME.exec(frame);
+	return match ? [{
+		file: match[1].replace(/^file:\/\//, ""),
+		line: Number(match[2])
+	}] : [];
+}
+function kindOf(value) {
+	return value && typeof value === "object" && KIND in value ? value[KIND] : null;
+}
+function humanize(name) {
+	const spaced = name.replace(/[-_]+/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2");
+	return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+//#endregion
+//#region src/define/inbox/view.ts
+function view(name, options) {
+	return {
+		[KIND]: "view",
+		origin: captureOrigin(),
+		name,
+		options
+	};
+}
+function normalizeFilter(filter = {}) {
+	const { state, ...rest } = filter;
+	return {
+		...rest,
+		...state ? { state: [state].flat() } : {}
+	};
+}
+//#endregion
+//#region src/blocks.ts
+function field(value) {
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : { date: value.toISOString() };
+	return value ?? null;
+}
+function fieldValues(fields) {
+	return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== void 0).map(([key, value]) => [key, field(value)]));
+}
+function fieldList(fields) {
+	return Object.entries(fields).filter(([, value]) => value !== void 0).map(([label, value]) => ({
+		label,
+		value: field(value)
+	}));
+}
+function ref(resource, id, title) {
+	return {
+		resource: typeof resource === "string" ? resource : resource.name,
+		id,
+		...title ? { title } : {}
+	};
+}
+function chart(source, options = {}) {
+	const range = options.range ?? "24h";
+	if (source === "occurrences") return {
+		type: "chart",
+		metric: source,
+		range,
+		title: options.title
+	};
+	if (kindOf(source) === "inbox") {
+		const inbox = source;
+		return {
+			type: "chart",
+			inbox: inbox.name,
+			range,
+			title: options.title ?? inbox.options.label
+		};
+	}
+	return {
+		type: "chart",
+		points: source.map(({ at, value }) => ({
+			at: +at,
+			value
+		})),
+		title: options.title
+	};
+}
+function listing(target, filter) {
+	if (kindOf(target) === "view") {
+		const view = target;
+		return {
+			inbox: view.options.inbox.name,
+			filter: normalizeFilter({
+				...view.options.filter,
+				...filter
+			}),
+			sort: view.options.sort ?? "-lastSeen",
+			view: view.name,
+			label: view.options.label ?? humanize(view.name)
+		};
+	}
+	const inbox = target;
+	return {
+		inbox: inbox.name,
+		filter: normalizeFilter(filter),
+		sort: "-lastSeen",
+		view: null,
+		label: inbox.options.label ?? humanize(inbox.name)
+	};
+}
+const idOf = (action) => typeof action === "string" ? action : action.id;
+function button(input) {
+	if (typeof input === "object" && "action" in input) return {
+		action: idOf(input.action),
+		record: input.record ?? null,
+		...input.input && { input: JSON.parse(JSON.stringify(input.input)) },
+		...input.label && { label: input.label }
+	};
+	return {
+		action: idOf(input),
+		record: null
+	};
+}
+function bindActions(blocks, resource, record) {
+	if (!resource) return blocks;
+	const own = (action) => !action.includes(".") && kindOf(resource.actions[action]) === "action";
+	const bind = (target) => own(target.action) ? {
+		...target,
+		action: actionId(resource.name, target.action),
+		record: target.record ?? record
+	} : target;
+	const value = (field) => field && typeof field === "object" && "edit" in field ? { edit: bind(field.edit) } : field;
+	return mapBlocks(blocks, (block) => {
+		if (block.type === "actions") return {
+			...block,
+			actions: block.actions.map(bind)
+		};
+		if (block.type === "form") return {
+			...block,
+			form: bind(block.form)
+		};
+		if (block.type === "fields") return {
+			...block,
+			fields: block.fields.map((entry) => ({
+				...entry,
+				value: value(entry.value)
+			}))
+		};
+		if (block.type === "stats") return {
+			...block,
+			stats: block.stats.map((stat) => ({
+				...stat,
+				value: value(stat.value)
+			}))
+		};
+		if (block.type === "table") return {
+			...block,
+			rows: block.rows.map((row) => row.map(value))
+		};
+		return block;
+	});
+}
+const b = {
+	markdown: (text) => ({
+		type: "markdown",
+		text
+	}),
+	fields: (fields) => ({
+		type: "fields",
+		fields: fieldList(fields)
+	}),
+	code: (code, options = {}) => ({
+		type: "code",
+		code,
+		...options
+	}),
+	chart,
+	attachment: (attachment) => ({
+		type: "attachment",
+		...attachment
+	}),
+	record: (resource, id, title) => ({
+		type: "record",
+		ref: ref(resource, id, title)
+	}),
+	ref: (resource, id, title) => ({ record: ref(resource, id, title) }),
+	sensitive: (value, options = {}) => ({ sensitive: {
+		value: String(value),
+		...options
+	} }),
+	timeline: (entries) => ({
+		type: "timeline",
+		entries: entries.map(({ at, text }) => ({
+			at: +at,
+			text
+		}))
+	}),
+	table: (rows, columns = Object.keys(rows[0] ?? {})) => ({
+		type: "table",
+		columns,
+		rows: rows.map((row) => columns.map((column) => field(row[column])))
+	}),
+	stats: (stats) => ({
+		type: "stats",
+		stats: Object.entries(stats).filter(([, stat]) => stat !== void 0).map(([label, stat]) => stat && typeof stat === "object" && "value" in stat && !(stat instanceof Date) ? {
+			label,
+			value: field(stat.value),
+			...stat.note && { note: stat.note }
+		} : {
+			label,
+			value: field(stat)
+		})
+	}),
+	actions: (...buttons) => ({
+		type: "actions",
+		actions: buttons.map(button)
+	}),
+	form: (action) => ({
+		type: "form",
+		form: button(action)
+	}),
+	columns: (...columns) => ({
+		type: "columns",
+		columns
+	}),
+	count: (target, options = {}) => {
+		const { inbox, filter, view, label } = listing(target, options.filter);
+		return {
+			type: "count",
+			inbox,
+			filter,
+			view,
+			label: options.label ?? label
+		};
+	},
+	items: (target, options = {}) => ({
+		type: "items",
+		...listing(target, options.filter),
+		...options.label && { label: options.label },
+		limit: options.limit ?? 5
+	}),
+	flag: (flag) => ({
+		type: "flag",
+		flag: flag.name
+	}),
+	edit: (value, action, options = {}) => ({ edit: {
+		value: field(value),
+		action: idOf(action),
+		record: options.record ?? null,
+		field: options.field ?? null
+	} })
+};
+function isPendingAttachment(block) {
+	return block.type === "attachment" && "data" in block;
+}
+function hasPendingAttachments(blocks) {
+	return blocks.some((block) => isPendingAttachment(block) || block.type === "columns" && block.columns.some(hasPendingAttachments));
+}
+//#endregion
+//#region src/client/transport.ts
+const DEFAULT_URL = "https://app.pult.sh";
+const UPLOAD_REUSE_MS = 36e5;
+var PultError = class extends Error {
+	status;
+	code;
+	constructor(message, status, code) {
+		super(message);
+		this.status = status;
+		this.code = code;
+		this.name = "PultError";
+	}
+};
+var Transport = class {
+	send;
+	key;
+	url;
+	#uploads = /* @__PURE__ */ new Map();
+	constructor(key, url, send) {
+		this.send = send;
+		this.key = parseKey(key);
+		this.url = url.replace(/\/$/, "");
+	}
+	request(method, path, body) {
+		return this.json(method, path, body === void 0 ? "" : JSON.stringify(body));
+	}
+	json(method, path, json) {
+		return this.#fetch(method, path, json, json, "application/json");
+	}
+	async upload(name, contentType, bytes) {
+		const hex = await sha256(bytes);
+		const id = `${hex}:${name}:${contentType}`;
+		const now = Date.now();
+		const recent = this.#uploads.get(id);
+		if (recent && now - recent.at < UPLOAD_REUSE_MS) return recent.key;
+		for (const [other, { at }] of this.#uploads) {
+			if (now - at < UPLOAD_REUSE_MS) break;
+			this.#uploads.delete(other);
+		}
+		const key = this.#fetch("POST", `/v1/attachments?name=${encodeURIComponent(name)}`, bytes, hex, contentType);
+		this.#uploads.delete(id);
+		this.#uploads.set(id, {
+			key,
+			at: now
+		});
+		key.catch(() => this.#uploads.delete(id));
+		return key;
+	}
+	async #fetch(method, path, body, signed, contentType) {
+		const signature = await sign(this.key.secret, `${method} ${path}`, signed);
+		const response = await this.send(`${this.url}${path}`, {
+			method,
+			body: method === "GET" ? void 0 : body,
+			headers: {
+				"content-type": contentType,
+				[HEADER.environment]: this.key.environment,
+				[HEADER.timestamp]: signature.timestamp,
+				[HEADER.nonce]: signature.nonce,
+				[HEADER.signature]: signature.signature
+			}
+		});
+		const json = await response.json().catch(() => null);
+		if (!response.ok) throw new PultError(json?.error ?? response.statusText, response.status, json?.code);
+		return json;
+	}
+};
+//#endregion
+//#region src/define/controls/flag.ts
+function flag(name, options = {}) {
+	return {
+		[KIND]: "flag",
+		origin: captureOrigin(),
+		name,
+		options: {
+			...options,
+			default: options.default ?? (options.value ? void 0 : false)
+		}
+	};
+}
+function guards(flag) {
+	return [flag.options.guard ?? []].flat();
+}
+//#endregion
+//#region src/define/collect.ts
+function collect(modules) {
+	const found = {
+		resources: /* @__PURE__ */ new Map(),
+		actions: /* @__PURE__ */ new Map(),
+		inboxes: /* @__PURE__ */ new Map(),
+		roles: /* @__PURE__ */ new Map(),
+		views: /* @__PURE__ */ new Map(),
+		pages: /* @__PURE__ */ new Map(),
+		flags: /* @__PURE__ */ new Map(),
+		notify: /* @__PURE__ */ new Map(),
+		spaces: /* @__PURE__ */ new Map(),
+		status: null,
+		config: null
+	};
+	const claim = (map, value, kind) => {
+		const existing = map.get(value.name);
+		if (existing && existing !== value) throw new Error(`Two ${kind} are named "${value.name}"`);
+		map.set(value.name, value);
+	};
+	const add = (value) => {
+		switch (kindOf(value)) {
+			case "resource": {
+				const resource = value;
+				return claim(found.resources, resource, "resources");
+			}
+			case "action": {
+				const action = value;
+				if (action.resource === null) claim(found.actions, action, "actions");
+				return;
+			}
+			case "inbox": {
+				const inbox = value;
+				claim(found.inboxes, inbox, "inboxes");
+				if (inbox.options.resource) add(inbox.options.resource);
+				return;
+			}
+			case "role": {
+				const role = value;
+				claim(found.roles, role, "roles");
+				for (const inbox of role.options.inboxes ?? []) add(inbox);
+				for (const resource of role.options.resources ?? []) add(resource);
+				for (const action of role.options.actions ?? []) add(action);
+				for (const page of role.options.pages ?? []) add(page);
+				for (const flag of role.options.flags ?? []) add(flag);
+				return;
+			}
+			case "view": {
+				const view = value;
+				claim(found.views, view, "views");
+				add(view.options.inbox);
+				return;
+			}
+			case "page": {
+				const page = value;
+				return claim(found.pages, page, "pages");
+			}
+			case "flag": {
+				const flag = value;
+				claim(found.flags, flag, "flags");
+				if (flag.options.target) add(flag.options.target);
+				for (const guard of guards(flag)) add(guard.inbox);
+				return;
+			}
+			case "space": {
+				const space = value;
+				claim(found.spaces, space, "spaces");
+				if (space.home) add(space.home);
+				for (const inbox of space.options.inboxes ?? []) add(inbox);
+				for (const resource of space.options.resources ?? []) add(resource);
+				for (const page of space.options.pages ?? []) add(page);
+				for (const flag of space.options.flags ?? []) add(flag);
+				return;
+			}
+			case "notify": {
+				const rule = value;
+				claim(found.notify, rule, "notifications");
+				for (const inbox of rule.options.inboxes) add(inbox);
+				for (const recipient of rule.options.to) add(recipient);
+				return;
+			}
+			case "status": {
+				const page = value;
+				if (found.status && found.status !== page) throw new Error("A project has one status page, and this one defines two");
+				found.status = page;
+				for (const recipient of page.options.alert ?? []) add(recipient);
+				return;
+			}
+			case "config": found.config = value;
+		}
+	};
+	for (const exports of modules) for (const value of Object.values(exports)) add(value);
+	return found;
+}
+function findAction(definitions, id) {
+	const { resource, name } = splitAction(id);
+	const action = resource === null ? definitions.actions.get(name) : definitions.resources.get(resource)?.actions[name];
+	return action && kindOf(action) === "action" ? action : null;
+}
+//#endregion
+//#region src/schema.ts
+const libraryOptions = { zod: {
+	unrepresentable: "any",
+	override: ({ zodSchema, jsonSchema }) => {
+		if (zodSchema._zod.def.type === "date") Object.assign(jsonSchema, {
+			type: "string",
+			format: "date-time"
+		});
+	}
+} };
+function toJsonSchema(schema) {
+	const standard = schema["~standard"];
+	if (!standard.jsonSchema) throw new Error(`Schemas from "${schema["~standard"].vendor}" can't describe themselves as JSON Schema. Use a library that implements Standard JSON Schema, such as zod, valibot or arktype.`);
+	const { $schema: _, ...json } = standard.jsonSchema.input({
+		target: "draft-2020-12",
+		libraryOptions: libraryOptions[standard.vendor]
+	});
+	return json;
+}
+var ValidationError = class extends Error {
+	issues;
+	constructor(issues) {
+		super(issues.map(describeIssue).join("; "));
+		this.issues = issues;
+		this.name = "ValidationError";
+	}
+};
+function describeIssue(issue) {
+	const path = issue.path?.map((segment) => typeof segment === "object" ? segment.key : segment).join(".");
+	return path ? `${path}: ${issue.message}` : issue.message;
+}
+async function validate(schema, value) {
+	const result = await schema["~standard"].validate(value);
+	if (result.issues) throw new ValidationError(result.issues);
+	return result.value;
+}
+function reviveDates(schema, value) {
+	if (!schema || value === null || value === void 0) return value;
+	if (schema.format === "date-time" && typeof value === "string") return new Date(value);
+	for (const branch of schema.anyOf ?? schema.oneOf ?? []) {
+		const revived = reviveDates(branch, value);
+		if (revived !== value) return revived;
+	}
+	if (Array.isArray(value) && schema.items) return value.map((entry) => reviveDates(schema.items, entry));
+	if (typeof value === "object" && schema.properties) {
+		const out = { ...value };
+		for (const [key, property] of Object.entries(schema.properties)) if (key in out) out[key] = reviveDates(property, out[key]);
+		return out;
+	}
+	return value;
+}
+//#endregion
+export { mapBlocks as A, traceOrigins as C, sign as D, NonceWindow as E, HOME as F, actionId as I, findActionDef as L, valuesIn as M, DEFAULT_STATES as N, verify as O, FLAG_ACTION as P, kindOf as S, refKey as T, normalizeFilter as _, collect as a, captureOrigin as b, guards as c, Transport as d, b as f, isPendingAttachment as g, hasPendingAttachments as h, validate as i, shownValue as j, eachBlock as k, DEFAULT_URL as l, fieldValues as m, reviveDates as n, findAction as o, bindActions as p, toJsonSchema as r, flag as s, ValidationError as t, PultError as u, view as v, HEADER as w, humanize as x, KIND as y };