permdock 0.7.0 → 0.9.0

package/dist/gen-BtfFWGbz.js

@@ -0,0 +1,827 @@
+import { r as isRecord } from "./compact-CAf557ZB.js";
+import { t as DESCRIBE_TITLES } from "./describe-Bb4hGK5d.js";
+import { c as listPermissions } from "./permission-registry-B8tYxPIt.js";
+import { f as scopeList } from "./scopes-0Up_UA2t.js";
+import { v as listRoles } from "./grantee-Dke-9rd1.js";
+import { t as byCodePoint } from "./compare-DTfyUunF.js";
+import { i as configError, n as CliError } from "./errors-Vpu6rKHl.js";
+import { c as jsonSchemaOf } from "./catalog-doc-DjMKzJp9.js";
+import { c as requirePolicy } from "./load-DjSU5KXO.js";
+import { t as loadConfiguredOperations } from "./catalog-operations-DeHTrJSV.js";
+import { n as fileSummary, r as planFiles } from "./files-B3AA05f1.js";
+import { f as writeOutputFiles, r as driftOf } from "./output-files-BIQ_9pIs.js";
+import { t as resolveNames } from "./resolve-names-ConCSj1y.js";
+import { i as schemaExpression } from "./generate-CezbCaTI.js";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, extname, relative, resolve } from "node:path";
+//#region src/cli/gen/model.ts
+/** `org.post` to `orgPost`, `quote-files` to `quoteFiles`. */
+function camelCase(name) {
+	const joined = name.split(/[^A-Za-z0-9]+/u).filter((word) => word !== "").map((word, index) => index === 0 ? `${word.charAt(0).toLowerCase()}${word.slice(1)}` : `${word.charAt(0).toUpperCase()}${word.slice(1)}`).join("");
+	return /^[0-9]/u.test(joined) ? `_${joined}` : joined;
+}
+function pascalCase(name) {
+	const camel = camelCase(name);
+	return `${camel.charAt(0).toUpperCase()}${camel.slice(1)}`;
+}
+function unique(kind, items) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const other = seen.get(item.ident);
+		if (other !== void 0) throw configError(`PermDock CLI: ${kind} '${other}' and '${item.name}' both generate the name '${item.ident}'; rename one of them`);
+		if (item.ident === "") throw configError(`PermDock CLI: ${kind} '${item.name}' has no letters or digits to name it by`);
+		seen.set(item.ident, item.name);
+	}
+	return items;
+}
+function isNullType(value) {
+	return isRecord(value) && value["type"] === "null";
+}
+/**
+* `anyOf: [T, { type: 'null' }]`, which Zod and Valibot write for a nullable
+* field, folded into `T` with `null` in `type` (and `enum`), so every kind
+* reads one shape.
+*/
+function foldNullable(schema) {
+	const options = schema["anyOf"];
+	let node = schema;
+	if (Array.isArray(options) && options.length === 2) {
+		const other = options.find((option) => !isNullType(option));
+		if (options.some(isNullType) && isRecord(other)) {
+			const { anyOf: _, ...rest } = schema;
+			const type = other["type"];
+			const values = other["enum"];
+			node = {
+				...rest,
+				...other,
+				...typeof type === "string" ? { type: [type, "null"] } : {},
+				...Array.isArray(values) ? { enum: [...values, null] } : {}
+			};
+		}
+	}
+	const properties = node["properties"];
+	const items = node["items"];
+	return {
+		...node,
+		...isRecord(properties) ? { properties: Object.fromEntries(Object.entries(properties).map(([name, child]) => [name, isRecord(child) ? foldNullable(child) : child])) } : {},
+		...isRecord(items) ? { items: foldNullable(items) } : {}
+	};
+}
+function schemaOf(value) {
+	return isRecord(value) ? foldNullable(value) : void 0;
+}
+function genResource(node) {
+	const title = node.meta?.title;
+	return {
+		name: node.name,
+		ident: camelCase(node.name),
+		schema: schemaOf(jsonSchemaOf(node)),
+		...node.parent === void 0 ? {} : { parent: {
+			field: node.parent.field,
+			resource: node.parent.resource
+		} },
+		...title === void 0 ? {} : { title }
+	};
+}
+function genOperation(operation, resourceOf) {
+	const results = operation.results === void 0 ? void 0 : resourceOf.get(operation.results);
+	return {
+		name: operation.name,
+		ident: camelCase(operation.name),
+		...results === void 0 ? {} : { results }
+	};
+}
+function genModel(input) {
+	const { policy, config } = input;
+	const leaves = listPermissions(policy.vocabulary.permissions);
+	const resourceOf = new Map(leaves.map((leaf) => [leaf.key, leaf.resource]));
+	const declaredRoles = listRoles(policy.vocabulary.roles);
+	const roleTitles = new Map(declaredRoles.map((role) => [role.key, role.meta.title ?? role.key]));
+	const resources = [...policy.resources.values()].map(genResource).toSorted((a, b) => byCodePoint(a.name, b.name));
+	const operations = (input.operations ?? []).map((operation) => genOperation(operation, resourceOf)).toSorted((a, b) => byCodePoint(a.name, b.name));
+	const roles = [.../* @__PURE__ */ new Set([...policy.roles.map((binding) => binding.name), ...declaredRoles.map((role) => role.key)])].toSorted(byCodePoint);
+	return {
+		resources: unique("resource", resources),
+		operations: unique("operation", operations),
+		scopes: scopeList(policy.scopes),
+		roles,
+		names: resolveNames(policy, config),
+		topics: Object.keys(config.rls?.realtime?.topics ?? {}).toSorted(byCodePoint),
+		buckets: Object.entries(config.rls?.storage?.buckets ?? {}).toSorted(([a], [b]) => byCodePoint(a, b)),
+		labels: {
+			permissions: leaves.map((leaf) => [leaf.key, leaf.meta.title ?? leaf.key]).toSorted(([a], [b]) => byCodePoint(a, b)),
+			roles: roles.map((role) => [role, roleTitles.get(role) ?? role])
+		}
+	};
+}
+//#endregion
+//#region src/cli/gen/schemas.ts
+const GENERATED = "// @generated by permdock gen; do not edit";
+const IDENTIFIER$2 = /^[A-Za-z_$][A-Za-z0-9_$]*$/u;
+const MAX_DEPTH = 6;
+const FIELD_BOUNDS = [
+	"minimum",
+	"maximum",
+	"exclusiveMinimum",
+	"exclusiveMaximum",
+	"minLength",
+	"maxLength",
+	"minItems",
+	"maxItems"
+];
+function typed(model) {
+	return model.resources.filter((resource) => resource.schema !== void 0);
+}
+function propertyKey(name) {
+	return IDENTIFIER$2.test(name) ? name : JSON.stringify(name);
+}
+/** `createdAt` and `created_at` read as `Created at`. */
+function labelOf(name) {
+	const sentence = name.replaceAll(/([a-z0-9])([A-Z])/gu, "$1 $2").split(/[^A-Za-z0-9]+/u).filter((word) => word !== "").map((word) => word.toLowerCase()).join(" ");
+	return `${sentence.charAt(0).toUpperCase()}${sentence.slice(1)}`;
+}
+function properties(schema) {
+	const required = new Set(Array.isArray(schema["required"]) ? schema["required"] : []);
+	const props = isRecord(schema["properties"]) ? schema["properties"] : {};
+	return Object.entries(props).filter((entry) => isRecord(entry[1])).map(([name, child]) => [
+		name,
+		child,
+		required.has(name)
+	]);
+}
+/** Per field: label, required, enum options, format and bounds, for forms. */
+function fieldMeta(schema) {
+	return Object.fromEntries(properties(schema).map(([name, child, required]) => {
+		const title = child["title"];
+		const options = child["enum"];
+		const format = child["format"];
+		const meta = {
+			label: typeof title === "string" ? title : labelOf(name),
+			required
+		};
+		const type = child["type"];
+		if (Array.isArray(type) && type.includes("null")) meta["nullable"] = true;
+		if (Array.isArray(options)) meta["options"] = options.filter((option) => option !== null);
+		if (typeof format === "string") meta["format"] = format;
+		for (const key of FIELD_BOUNDS) {
+			const value = child[key];
+			if (typeof value === "number") meta[key] = value;
+		}
+		return [name, meta];
+	}));
+}
+function fieldsExport(resource) {
+	return `export const ${resource.ident}Fields = ${JSON.stringify(fieldMeta(resource.schema), null, 2)} as const;`;
+}
+const IMPORTS = {
+	zod: "import { z } from \"zod\";",
+	valibot: "import * as v from \"valibot\";",
+	arktype: "import { type } from \"arktype\";"
+};
+function inferType(kind, ident) {
+	switch (kind) {
+		case "zod": return `z.infer<typeof ${ident}>`;
+		case "valibot": return `v.InferOutput<typeof ${ident}>`;
+		case "arktype": return `typeof ${ident}.infer`;
+		default: return kind;
+	}
+}
+function arrayOf(kind, ident) {
+	switch (kind) {
+		case "zod": return `z.array(${ident})`;
+		case "valibot": return `v.array(${ident})`;
+		case "arktype": return `${ident}.array()`;
+		default: return kind;
+	}
+}
+function resultsOf(model) {
+	const byName = new Map(typed(model).map((resource) => [resource.name, resource]));
+	return model.operations.flatMap((operation) => {
+		const resource = operation.results === void 0 ? void 0 : byName.get(operation.results);
+		return resource === void 0 ? [] : [[operation.ident, resource]];
+	});
+}
+/**
+* `zod`, `valibot` or `arktype`: a row schema per resource and a result schema
+* per operation.
+*/
+function validatorModule(kind, model, options) {
+	const blocks = typed(model).map((resource) => {
+		const ident = `${resource.ident}Row`;
+		const lines = [`export const ${ident} = ${schemaExpression(kind, resource.schema, void 0, { constraints: true })};`, `export type ${pascalCase(resource.name)}Row = ${inferType(kind, ident)};`];
+		return options.fieldMeta ? [
+			...lines,
+			"",
+			fieldsExport(resource)
+		].join("\n") : lines.join("\n");
+	});
+	const results = resultsOf(model).map(([operation, resource]) => `export const ${operation}Result = ${arrayOf(kind, `${resource.ident}Row`)};`);
+	return `${[
+		GENERATED,
+		IMPORTS[kind],
+		...blocks,
+		...results
+	].join("\n\n")}\n`;
+}
+function literalType(value) {
+	return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? JSON.stringify(value) : "unknown";
+}
+/** A TypeScript type for the portable JSON Schema core. */
+function typeOf(schema, depth = 0) {
+	const values = schema["enum"];
+	if (Array.isArray(values) && values.length > 0) return values.map(literalType).join(" | ");
+	const raw = schema["type"];
+	const types = Array.isArray(raw) ? raw : [raw];
+	const nullable = types.includes("null");
+	const named = types.filter((type) => typeof type === "string" && type !== "null");
+	const base = depth > MAX_DEPTH || named.length !== 1 ? isRecord(schema["properties"]) && named.length === 0 ? objectType(schema, depth) : "unknown" : primitiveType(schema, named[0], depth);
+	return nullable && base !== "unknown" ? `${base} | null` : base;
+}
+function objectType(schema, depth) {
+	const fields = properties(schema).map(([name, child, required]) => `readonly ${propertyKey(name)}${required ? "" : "?"}: ${typeOf(child, depth + 1)}`);
+	return fields.length === 0 ? "{}" : `{ ${fields.join("; ")} }`;
+}
+function primitiveType(schema, type, depth) {
+	switch (type) {
+		case "string": return "string";
+		case "number":
+		case "integer": return "number";
+		case "boolean": return "boolean";
+		case "array": return `readonly (${isRecord(schema["items"]) ? typeOf(schema["items"], depth + 1) : "unknown"})[]`;
+		case "object": return objectType(schema, depth);
+		default: return "unknown";
+	}
+}
+/**
+* `standard-schema`: validators over the JSON Schema core through
+* `permdock/catalog`, so the project needs no schema library.
+*/
+function standardSchemaModule(model, options) {
+	const blocks = typed(model).map((resource) => {
+		const lines = [`export type ${pascalCase(resource.name)}Row = ${typeOf(resource.schema)};`, `export const ${resource.ident}Row = resourceSchemaFromJson(${JSON.stringify(resource.schema)});`];
+		return options.fieldMeta ? [
+			...lines,
+			"",
+			fieldsExport(resource)
+		].join("\n") : lines.join("\n");
+	});
+	const results = resultsOf(model).map(([operation, resource]) => `export const ${operation}Result = resourceSchemaFromJson(${JSON.stringify({
+		type: "array",
+		items: resource.schema
+	})});`);
+	return `${[
+		GENERATED,
+		"import { resourceSchemaFromJson } from \"permdock/catalog\";",
+		...blocks,
+		...results
+	].join("\n\n")}\n`;
+}
+/** `json-schema`: the row documents as they are, results as `$ref` arrays. */
+function jsonSchemaDocument(model) {
+	const document = {
+		$comment: "@generated by permdock gen; do not edit",
+		resources: Object.fromEntries(typed(model).map((resource) => [resource.name, resource.schema])),
+		operations: Object.fromEntries(resultsOf(model).map(([operation, resource]) => [operation, { results: {
+			type: "array",
+			items: { $ref: `#/resources/${resource.name.replaceAll("~", "~0").replaceAll("/", "~1")}` }
+		} }]))
+	};
+	return `${JSON.stringify(document, null, 2)}\n`;
+}
+//#endregion
+//#region src/cli/gen/constants.ts
+const IDENTIFIER$1 = /^[A-Za-z_$][A-Za-z0-9_$]*$/u;
+const PLACEHOLDER = /\{([^{}]+)\}/gu;
+function key$1(name) {
+	return IDENTIFIER$1.test(name) ? name : JSON.stringify(name);
+}
+function read(name) {
+	return IDENTIFIER$1.test(name) ? `params.${name}` : `params[${JSON.stringify(name)}]`;
+}
+/** Text for inside a template literal. */
+function templateText(text) {
+	return text.replaceAll("\\", "\\\\").replaceAll("`", "\\`").replaceAll("${", "\\${");
+}
+function builder(params, body) {
+	return `(params: { ${params.map((name) => `readonly ${key$1(name)}: string`).join("; ")} }): string => \`${body}\``;
+}
+function distinct(kind, entries) {
+	const seen = /* @__PURE__ */ new Map();
+	const lines = [];
+	for (const [ident, source, code] of entries) {
+		const other = seen.get(ident);
+		if (other !== void 0) throw configError(`PermDock CLI: ${kind} '${other}' and '${source}' both generate the builder '${ident}'; rename one of them`);
+		seen.set(ident, source);
+		lines.push(`  ${key$1(ident)}: ${code},`);
+	}
+	return lines.length === 0 ? "{}" : `{\n${lines.join("\n")}\n}`;
+}
+/**
+* `org:{organization}:quotes` to `orgQuotes`, building
+* `org:${organization}:quotes`.
+*/
+function topicBuilder(topic) {
+	const params = [...topic.matchAll(PLACEHOLDER)].map((match) => String(match[1]));
+	const camel = camelCase(topic.replaceAll(PLACEHOLDER, " "));
+	const ident = camel === "" ? camelCase(topic) : camel;
+	let body = "";
+	let last = 0;
+	for (const match of topic.matchAll(PLACEHOLDER)) {
+		body += `${templateText(topic.slice(last, match.index))}\${${read(String(match[1]))}}`;
+		last = match.index + match[0].length;
+	}
+	body += templateText(topic.slice(last));
+	return [
+		ident,
+		topic,
+		builder([...new Set(params)], body)
+	];
+}
+/**
+* A bucket's object path: `folder - 1` leading segments, the scope id, then
+* `name`, as `storage.foldername(name)` reads it.
+*/
+function pathBuilder(bucket, config) {
+	const params = [
+		...Array.from({ length: Math.max(0, (config.folder ?? 1) - 1) }, (_, index) => `segment${String(index + 1)}`),
+		config.scope,
+		"name"
+	];
+	const body = params.map((name) => `\${${read(name)}}`).join("/");
+	return [
+		camelCase(bucket),
+		bucket,
+		builder(params, body)
+	];
+}
+function qualify(schema, name) {
+	return name.includes(".") ? name : `${schema}.${name}`;
+}
+/** Every helper name schema-qualified; tables and views keep their own schema. */
+function sqlNames(names) {
+	const fn = (name) => qualify(names.schema, name);
+	const map = (entries, keep) => Object.fromEntries(Object.entries(entries).map(([name, helpers]) => [name, Object.fromEntries(Object.entries(helpers).map(([field, value]) => [field, keep.has(field) ? value : fn(value)]))]));
+	return {
+		schema: names.schema,
+		claims: names.claims,
+		scopes: map(names.scopes, /* @__PURE__ */ new Set()),
+		resources: map(names.resources, /* @__PURE__ */ new Set(["table", "visible"]))
+	};
+}
+function list(name, type, values) {
+	return `export const ${name} = ${JSON.stringify(values)} as const;
+export type ${type} = (typeof ${name})[number];`;
+}
+/** `constants`: scope and role names, topic and path builders, SQL names. */
+function constantsModule(model) {
+	return `${[
+		GENERATED,
+		list("scopes", "ScopeName", model.scopes.map((scope) => scope.name)),
+		list("roles", "RoleName", model.roles),
+		`/** \`rls.realtime.topics\`: the channel names the realtime policies match. */
+export const topics = ${distinct("topic", model.topics.map(topicBuilder))} as const;`,
+		`/** \`rls.storage.buckets\`: object paths that start with a scope id. */
+export const paths = ${distinct("bucket", model.buckets.map(([bucket, config]) => pathBuilder(bucket, config)))} as const;`,
+		`/** The SQL helpers \`rls generate\` writes. */
+export const sqlNames = ${JSON.stringify(sqlNames(model.names), null, 2)} as const;`
+	].join("\n\n")}\n`;
+}
+//#endregion
+//#region src/cli/gen/factories.ts
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/u;
+function key(name) {
+	return IDENTIFIER.test(name) ? name : JSON.stringify(name);
+}
+function number(schema, name) {
+	const value = schema[name];
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function typeName(schema) {
+	const raw = schema["type"];
+	return (Array.isArray(raw) ? raw : [raw]).find((type) => typeof type === "string" && type !== "null") ?? (isRecord(schema["properties"]) ? "object" : void 0);
+}
+function numberValue(schema, integer) {
+	const step = integer ? 1 : .5;
+	const exclusive = number(schema, "exclusiveMinimum");
+	const minimum = number(schema, "minimum") ?? (exclusive === void 0 ? void 0 : exclusive + step);
+	const maximum = number(schema, "maximum");
+	const value = minimum ?? (maximum === void 0 ? 0 : Math.min(0, maximum));
+	return String(integer ? Math.ceil(value) : value);
+}
+/**
+* A valid value for a required field: the first enum value, the lower bound, a
+* sequence id.
+*/
+function valueOf(schema, field, depth) {
+	const values = schema["enum"];
+	if (Array.isArray(values) && values.length > 0) return JSON.stringify(values[0]);
+	switch (typeName(schema) ?? "unknown") {
+		case "string": return stringValue(schema, field);
+		case "integer": return numberValue(schema, true);
+		case "number": return numberValue(schema, false);
+		case "boolean": return "false";
+		case "array": return "[]";
+		case "object": return depth > 4 ? "{}" : objectValue(schema, depth + 1, /* @__PURE__ */ new Map());
+		default: return "null";
+	}
+}
+function stringValue(schema, field) {
+	switch (schema["format"]) {
+		case "uuid": return "uuid()";
+		case "email": return "`user${String(next())}@example.com`";
+		case "date-time": return "\"2026-01-01T00:00:00.000Z\"";
+		case "date": return "\"2026-01-01\"";
+		case "uri": return "`https://example.com/${String(next())}`";
+		default: return `text(${JSON.stringify(field)}, ${String(number(schema, "minLength") ?? 0)}, ${String(number(schema, "maxLength") ?? 255)})`;
+	}
+}
+function objectValue(schema, depth, refs) {
+	const required = new Set(Array.isArray(schema["required"]) ? schema["required"] : []);
+	const properties = isRecord(schema["properties"]) ? schema["properties"] : {};
+	const fields = Object.entries(properties).filter((entry) => isRecord(entry[1])).filter(([name]) => required.has(name)).map(([name, child]) => {
+		const ref = typeName(child) === "string" ? refs.get(name) : void 0;
+		const fill = valueOf(child, name, depth);
+		return `${key(name)}: ${ref === void 0 ? fill : `refs.${ref} === undefined ? ${fill} : idOf(refs.${ref})`}`;
+	});
+	return fields.length === 0 ? "{}" : `{ ${fields.join(", ")} }`;
+}
+function requiredFields(schema) {
+	const required = Array.isArray(schema["required"]) ? schema["required"] : [];
+	const properties = isRecord(schema["properties"]) ? schema["properties"] : {};
+	return new Set(required.filter((name) => typeof name === "string" && isRecord(properties[name])));
+}
+/**
+* Required field to the `refs` key that fills it: the parent resource, then
+* each scope by its key.
+*/
+function refsOf(resource, model) {
+	const fields = requiredFields(resource.schema);
+	const refs = /* @__PURE__ */ new Map();
+	if (resource.parent !== void 0 && fields.has(resource.parent.field)) refs.set(resource.parent.field, "parent");
+	for (const scope of model.scopes) if (scope.key !== void 0 && fields.has(scope.key) && IDENTIFIER.test(scope.name)) refs.set(scope.key, scope.name);
+	return refs;
+}
+function factory(resource, model) {
+	const row = `${pascalCase(resource.name)}Row`;
+	const refs = refsOf(resource, model);
+	const used = [...new Set(refs.values())].map((name) => `readonly ${name}?: Ref`);
+	const fill = objectValue(resource.schema, 0, refs);
+	const params = [`overrides: Partial<${row}> = {}`, ...used.length === 0 ? [] : [`refs: { ${used.join("; ")} } = {}`]];
+	return `  ${key(resource.ident)}: (${params.join(", ")}): ${row} => (${fill === "{}" ? "{ ...overrides }" : `{ ...${fill}, ...overrides }`}),`;
+}
+const RUNTIME = `let sequence = 0;
+
+/** Restarts the ids and names, so a test reads the same rows on every run. */
+export function resetFactories(): void {
+  sequence = 0;
+}
+
+function next(): number {
+  sequence += 1;
+  return sequence;
+}
+
+function uuid(): string {
+  return \`00000000-0000-4000-8000-\${String(next()).padStart(12, "0")}\`;
+}
+
+function text(field: string, min: number, max: number): string {
+  return \`\${field}-\${String(next())}\`.padEnd(min, "x").slice(0, max);
+}
+
+type Ref = string | { readonly id: string };
+
+function idOf(ref: Ref): string {
+  return typeof ref === "string" ? ref : ref.id;
+}`;
+/**
+* `factories`: a row builder per resource that fills the required fields with
+* valid values, plus `subject` for a principal with typed roles and
+* memberships.
+*/
+function factoriesModule(model) {
+	const resources = model.resources.filter((resource) => resource.schema !== void 0);
+	const types = resources.map((resource) => `export type ${pascalCase(resource.name)}Row = ${typeOf(resource.schema)};`);
+	const roles = model.roles.map((role) => JSON.stringify(role)).join(" | ");
+	const scopes = model.scopes.map((scope) => JSON.stringify(scope.name)).join(" | ");
+	const subject = `export type FactoryMembership = {
+  readonly scope: ${scopes === "" ? "string" : scopes};
+  readonly id: string;
+  readonly roles: readonly (${roles === "" ? "string" : roles})[];
+};
+
+export type FactorySubject = Principal & {
+  readonly roles: readonly (${roles === "" ? "string" : roles})[];
+  readonly memberships: readonly FactoryMembership[];
+};`;
+	const body = [...resources.map((resource) => factory(resource, model)), `  subject: (input: Partial<FactorySubject> = {}): FactorySubject => ({ id: uuid(), roles: [], memberships: [], ...input }),`];
+	return `${[
+		GENERATED,
+		"import type { Principal } from \"permdock\";",
+		RUNTIME,
+		...types,
+		subject,
+		`export const factories = {\n${body.join("\n")}\n};`
+	].join("\n\n")}\n`;
+}
+//#endregion
+//#region src/cli/gen/hooks.ts
+const BINDINGS = {
+	react: {
+		entry: "permdock/react",
+		instance: "usePermDock",
+		roles: "useRoles",
+		rolesParam: "AppRolesOptions"
+	},
+	vue: {
+		entry: "permdock/vue",
+		instance: "usePermDock",
+		roles: "useRoles",
+		rolesParam: "MaybeRefOrGetter<AppRolesOptions>",
+		frameworkType: "import type { MaybeRefOrGetter } from \"vue\";"
+	},
+	svelte: {
+		entry: "permdock/svelte",
+		instance: "getPermDock",
+		roles: "roles",
+		rolesParam: "() => AppRolesOptions"
+	},
+	solid: {
+		entry: "permdock/solid",
+		instance: "usePermDock",
+		roles: "useRoles",
+		rolesParam: "Accessor<AppRolesOptions>",
+		frameworkType: "import type { Accessor } from \"solid-js\";"
+	}
+};
+const JS_EXTENSION = {
+	".ts": ".js",
+	".tsx": ".js",
+	".mts": ".mjs",
+	".cts": ".cjs"
+};
+/**
+* The specifier from the generated file to the policy module. A `.ts` source is
+* named by its `.js` output, which both `bundler` and `nodenext` resolution map
+* back to the source.
+*/
+function policySpecifier(outFile, policy) {
+	const extension = extname(policy);
+	const target = `${policy.slice(0, policy.length - extension.length)}${JS_EXTENSION[extension] ?? extension}`;
+	const path = relative(dirname(outFile), target).split("\\").join("/");
+	return path.startsWith(".") ? path : `./${path}`;
+}
+/** One line when it fits the formatter's 80 columns, else a wrapped tail. */
+function fitted(head, tail) {
+	const line = `${head} ${tail}`;
+	return line.length <= 80 ? line : `${head}\n  ${tail}`;
+}
+/**
+* A typed hook file for a UI adapter: the instance getter bound to
+* `VocabularyOf<typeof policy>` and the roles reader narrowed to its scopes, so
+* call sites need no generic; every other export passes through. It reaches the
+* policy through `import type` only, so the client bundle never includes it.
+*/
+function hooksModule(kind, specifier) {
+	const binding = BINDINGS[kind];
+	return `${[
+		GENERATED,
+		`import type { ScopeNameOf, VocabularyOf } from "permdock";
+import type { ClientPermDock, RolesOptions } from "${binding.entry}";${binding.frameworkType === void 0 ? "" : `\n${binding.frameworkType}`}
+
+import {
+  ${binding.instance} as ${binding.instance}Of,
+  ${binding.roles} as ${binding.roles}Of,
+} from "${binding.entry}";
+
+import type * as source from ${JSON.stringify(specifier)};`,
+		`type AppPolicy = typeof source extends { readonly policy: infer P }
+  ? P
+  : typeof source extends { readonly default: infer P }
+    ? P
+    : never;`,
+		`/** The configured policy's vocabulary: its permissions, roles and plans. */
+export type AppVocabulary = VocabularyOf<AppPolicy>;`,
+		`/** A scope the configured policy declares. */
+export type AppScope = ScopeNameOf<AppPolicy>;`,
+		`export type AppRolesOptions = Omit<RolesOptions, "scope"> & {
+  readonly scope?: AppScope;
+};`,
+		fitted(`export const ${binding.instance}: () => ClientPermDock<AppVocabulary> =`, `${binding.instance}Of;`),
+		`export const ${binding.roles}: (
+  options?: ${binding.rolesParam},
+) => ReturnType<typeof ${binding.roles}Of> = ${binding.roles}Of;`,
+		`export * from "${binding.entry}";`
+	].join("\n\n")}\n`;
+}
+//#endregion
+//#region src/cli/gen/messages.ts
+const REASONS = {
+	"no-grant": "No role grants this",
+	condition: "A condition did not match",
+	deny: "A deny rule applies",
+	"inactive-grant": "The grant is not active now",
+	"closure-error": "A condition failed to evaluate",
+	"opaque-condition": "Checked on the server",
+	"server-only": "Checked on the server",
+	anonymous: "Sign in first",
+	"not-delegated": "Not delegated to this agent",
+	"no-delegation": "The agent has no delegation",
+	"agent-tool-not-delegated": "This tool is not delegated to the agent",
+	"insufficient-user-authentication": "Verify your identity again",
+	"not-entitled": "Your plan does not include this",
+	purpose: "The stated purpose does not allow this",
+	"reason-required": "A reason is required",
+	"actor-required": "An actor is required",
+	limit: "The limit is reached",
+	"limit-unavailable": "The limit could not be checked",
+	"relation-depth": "The relation is too deep to check",
+	"relation-unavailable": "The relation could not be checked",
+	validation: "The input is not valid",
+	"tenant-mismatch": "This belongs to another workspace",
+	"no-membership": "You are not a member",
+	"no-tenant": "No workspace is selected",
+	scope: "Not available in this scope",
+	"expired-membership": "Your membership has expired",
+	"stale-credentials": "Your session is out of date",
+	"unknown-role": "The role is not known",
+	"last-holder": "The last holder cannot be removed",
+	"max-holders": "The role has its maximum holders",
+	"transfer-only": "The role can only be transferred",
+	"not-assignable-by": "You cannot assign this role",
+	"self-demotion": "You cannot demote yourself",
+	"externally-managed": "Managed by your identity provider",
+	"not-allowed-for-membership": "Not allowed for this membership",
+	"conflicting-role": "Conflicts with a role already held",
+	approval: "Approval is required",
+	"stale-approval": "The approval is out of date",
+	"pdp-denied": "The policy service denied this",
+	"pdp-unavailable": "The policy service is unavailable",
+	"pdp-invalid-response": "The policy service gave an invalid answer",
+	undocumented: "Not documented in the policy",
+	unsupported: "Not supported",
+	"exceeds-creator": "Exceeds your own access",
+	"credential-policy": "The credential policy does not allow this"
+};
+function kept(defaults, previous) {
+	const existing = isRecord(previous) ? previous : {};
+	return Object.fromEntries(Object.entries(defaults).map(([key, text]) => {
+		const translated = Object.hasOwn(existing, key) ? existing[key] : void 0;
+		return [key, typeof translated === "string" ? translated : text];
+	}));
+}
+function parsePrevious(rel, previous) {
+	if (previous === void 0) return {};
+	try {
+		return JSON.parse(previous);
+	} catch {
+		throw configError(`PermDock CLI: ${rel} is not valid JSON; fix or delete it before permdock gen rewrites it`);
+	}
+}
+/**
+* A `DescribeMessages` skeleton: every `describe` title and denial reason, plus
+* each permission's and role's title. A value already in the file is kept, so a
+* translated file only gains the keys it lacks and loses the ones the policy
+* dropped; `--check` reports both.
+*/
+function messagesDocument(model, rel, previous) {
+	const parsed = parsePrevious(rel, previous);
+	const existing = isRecord(parsed) ? parsed : {};
+	const sections = {
+		titles: kept(DESCRIBE_TITLES, existing["titles"]),
+		reasons: kept(REASONS, existing["reasons"]),
+		permissions: kept(Object.fromEntries(model.labels.permissions), existing["permissions"]),
+		roles: kept(Object.fromEntries(model.labels.roles), existing["roles"])
+	};
+	return `${JSON.stringify(sections, null, 2)}\n`;
+}
+//#endregion
+//#region src/cli/gen/gen.ts
+const GEN_KINDS = [
+	"constants",
+	"zod",
+	"valibot",
+	"arktype",
+	"json-schema",
+	"standard-schema",
+	"factories",
+	"react",
+	"vue",
+	"svelte",
+	"solid",
+	"messages"
+];
+const DEFAULT_GEN_OUT = "src/generated";
+const FILE_NAMES = {
+	constants: "permdock.generated.ts",
+	zod: "permdock.zod.ts",
+	valibot: "permdock.valibot.ts",
+	arktype: "permdock.arktype.ts",
+	"json-schema": "permdock.schemas.json",
+	"standard-schema": "permdock.schemas.ts",
+	factories: "permdock.factories.ts",
+	react: "permdock.react.ts",
+	vue: "permdock.vue.ts",
+	svelte: "permdock.svelte-stores.ts",
+	solid: "permdock.solid.ts",
+	messages: "permdock.messages.json"
+};
+function isGenKind(value) {
+	return GEN_KINDS.some((kind) => kind === value);
+}
+function kindsOf(flags, config) {
+	if (flags.length > 0) return [...new Set(flags)];
+	const configured = config.gen?.kinds;
+	if (configured === void 0) return ["constants"];
+	for (const kind of configured) if (!isGenKind(kind)) throw configError(`PermDock CLI: gen.kinds has '${String(kind)}'; use ${GEN_KINDS.join(", ")}`);
+	return [...new Set(configured)];
+}
+function readIfExists(file) {
+	return existsSync(file) ? readFileSync(file, "utf8") : void 0;
+}
+function render(kind, model, context) {
+	switch (kind) {
+		case "constants": return constantsModule(model);
+		case "zod":
+		case "valibot":
+		case "arktype": return validatorModule(kind, model, context);
+		case "json-schema": return jsonSchemaDocument(model);
+		case "standard-schema": return standardSchemaModule(model, context);
+		case "factories": return factoriesModule(model);
+		case "react":
+		case "vue":
+		case "svelte":
+		case "solid": return hooksModule(kind, policySpecifier(context.file, context.policy));
+		case "messages": return messagesDocument(model, context.rel, context.previous);
+		default: return kind;
+	}
+}
+/** The files `permdock gen` writes: one per kind under the output directory. */
+async function genFiles(input) {
+	const kinds = kindsOf(input.kinds, input.config);
+	if (input.out !== void 0 && kinds.length > 1) throw new CliError("usage", `gen: --out names one file; ${String(kinds.length)} kinds need --out-dir`, {
+		code: "invalid_value",
+		extensions: { flag: "--out" }
+	});
+	const policyPath = input.from ?? input.config.policy ?? "";
+	const policy = await requirePolicy(input.cwd, input.from ?? input.config.policy, "gen needs policy in the config or --policy");
+	const operations = await loadConfiguredOperations(input.cwd, input.config.operations);
+	const model = genModel({
+		policy,
+		config: input.config,
+		operations
+	});
+	const dir = input.outDir ?? input.config.gen?.out ?? DEFAULT_GEN_OUT;
+	const fieldMeta = input.config.gen?.fieldMeta === true;
+	return kinds.map((kind) => {
+		const rel = input.out ?? `${dir}/${FILE_NAMES[kind]}`;
+		const file = resolve(input.cwd, rel === "-" ? `${dir}/${FILE_NAMES[kind]}` : rel);
+		return {
+			part: kind,
+			rel,
+			text: render(kind, model, {
+				fieldMeta,
+				rel,
+				file,
+				policy: resolve(input.cwd, policyPath),
+				previous: rel === "-" ? void 0 : readIfExists(file)
+			})
+		};
+	});
+}
+async function runGen(input) {
+	const files = await genFiles(input);
+	if (input.check) {
+		const drift = driftOf(input.cwd, files);
+		return drift.length === 0 ? {
+			code: 0,
+			output: files.map((file) => `${file.rel} is current`).join("\n"),
+			data: { stale: [] }
+		} : {
+			code: 1,
+			output: `${drift.join("\n")}\nrun permdock gen to refresh`,
+			data: { stale: drift }
+		};
+	}
+	const onDisk = files.filter((file) => file.rel !== "-").map((file) => ({
+		path: file.rel,
+		text: file.text
+	}));
+	if (input.dryRun) {
+		const planned = planFiles(input.cwd, onDisk);
+		return {
+			code: 0,
+			output: fileSummary(planned, true),
+			data: { files: planned }
+		};
+	}
+	const planned = planFiles(input.cwd, onDisk);
+	const { printed } = writeOutputFiles(input.cwd, files);
+	return {
+		code: 0,
+		output: printed === "" ? fileSummary(planned, false) : printed,
+		data: { files: planned }
+	};
+}
+//#endregion
+export { runGen };