permdock 0.0.0 → 0.1.0

package/dist/collect-O-tOtbnk.js

@@ -0,0 +1,350 @@
+import { i as formatCatalogJson, n as catalogForCompare, t as buildCatalog } from "./catalog-doc-BSo_Q_-6.js";
+import { t as catalogPath } from "./catalog-path-CnI0XTFK.js";
+import { n as listSourceFiles, r as rel, t as defaultSrcPath } from "./files-B_wAGYmt.js";
+import { a as loadModule, i as loadConfiguredPolicy, o as pickNamed, r as leavesOf, t as asPermissionTree } from "./load-BZ24CpZP.js";
+import { t as shortDiff } from "./text-diff-BdkkYSbi.js";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { Visitor, parseSync, visitorKeys } from "oxc-parser";
+//#region src/cli/scan.ts
+const CHECK_CALLS = /* @__PURE__ */ new Set([
+	"can",
+	"decide",
+	"assert",
+	"filter",
+	"where",
+	"simulate",
+	"actions",
+	"usePermission",
+	"getPermission",
+	"protect",
+	"allow",
+	"deny",
+	"registerTool",
+	"anyone",
+	"authenticated",
+	"relation",
+	"plan",
+	"actor",
+	"assurance"
+]);
+function scanSources(cwd, files, knownKeys) {
+	const roots = /* @__PURE__ */ new Set(["permissions"]);
+	const definitionFiles = {};
+	const usages = {};
+	const unknown = [];
+	const dynamic = [];
+	const roleNames = /* @__PURE__ */ new Set();
+	const planNames = /* @__PURE__ */ new Set();
+	const allowKeys = /* @__PURE__ */ new Set();
+	const snapshots = [];
+	for (const file of files) {
+		const source = readFileSync(file, "utf8");
+		let program;
+		try {
+			program = parseSync(file, source).program;
+		} catch {
+			continue;
+		}
+		const fileRel = rel(cwd, file);
+		walk(program, (node, parent) => {
+			if (node.type === "CallExpression") {
+				recordCall(node, parent, source, fileRel, roots, definitionFiles, usages, unknown, dynamic, roleNames, planNames, allowKeys, knownKeys);
+				const callee = calleeName(node.callee);
+				if (callee === "snapshot" || callee === "snapshotFor") snapshots.push({
+					file: fileRel,
+					line: lineAt(source, node.start ?? 0),
+					include: includeOf(node.arguments?.[callee === "snapshot" ? 0 : 2], roots)
+				});
+			}
+			if (node.type === "MemberExpression" && parent?.type !== "MemberExpression") recordMember(node, parent, source, fileRel, roots, usages, unknown, dynamic, allowKeys, knownKeys);
+			if (node.type === "ImportDeclaration") recordImport(node, roots);
+		});
+	}
+	return {
+		roots: [...roots].toSorted(),
+		definitionFiles,
+		usages,
+		unknown,
+		dynamic,
+		roleNames: [...roleNames].toSorted(),
+		planNames: [...planNames].toSorted(),
+		allowKeys: [...allowKeys].toSorted(),
+		snapshots
+	};
+}
+function includeOf(options, roots) {
+	if (options?.type !== "ObjectExpression") return options === void 0 ? void 0 : null;
+	const property = options.properties?.find((item) => item.key?.name === "include");
+	if (property === void 0) return options.properties?.some((item) => item.type === "SpreadElement") ? null : void 0;
+	const list = property.value;
+	if (list?.type !== "ArrayExpression") return null;
+	const keys = [];
+	for (const element of list.elements ?? []) {
+		const [root, ...rest] = (element.type === "MemberExpression" ? memberPath(element) : void 0) ?? [];
+		if (root === void 0 || !roots.has(root) || rest.length === 0) return null;
+		keys.push(rest.join("."));
+	}
+	return keys;
+}
+function recordImport(node, roots) {
+	for (const spec of node.specifiers ?? []) {
+		const imported = spec.imported?.name ?? spec.local?.name;
+		const local = spec.local?.name;
+		if (imported === "permissions" && local !== void 0) roots.add(local);
+	}
+}
+function recordCall(node, parent, source, fileRel, roots, definitionFiles, usages, unknown, dynamic, roleNames, planNames, _allowKeys, knownKeys) {
+	const callee = calleeName(node.callee);
+	const line = lineAt(source, node.start ?? 0);
+	if (callee === "definePermissions" || callee === "defineRoles" || callee === "definePlans") {
+		const name = declaredName(parent);
+		if (name !== void 0) {
+			if (callee === "definePermissions") roots.add(name);
+			definitionFiles[name] = fileRel;
+		}
+		if (callee === "defineRoles") collectObjectKeys(node.arguments?.[0], roleNames);
+		if (callee === "definePlans") collectObjectKeys(node.arguments?.[0], planNames);
+		return;
+	}
+	if (callee === "role") {
+		const first = node.arguments?.[0];
+		if (typeof first?.value === "string") roleNames.add(first.value);
+		else if (first?.type === "MemberExpression" && typeof first.property?.name === "string") roleNames.add(first.property.name);
+		return;
+	}
+	if (callee === "findPermission") {
+		const second = node.arguments?.[1];
+		if (typeof second?.value === "string") {
+			pushUsage(second.value, {
+				file: fileRel,
+				line,
+				call: "findPermission"
+			}, knownKeys, usages, unknown);
+			return;
+		}
+		dynamic.push({
+			file: fileRel,
+			line,
+			call: "findPermission"
+		});
+	}
+}
+function recordMember(node, parent, source, fileRel, roots, usages, unknown, dynamic, allowKeys, knownKeys) {
+	if (node.computed === true) {
+		const root = rootName(node);
+		if (root !== void 0 && roots.has(root)) dynamic.push({
+			file: fileRel,
+			line: lineAt(source, node.start ?? 0),
+			call: callName(parent)
+		});
+		return;
+	}
+	const path = memberPath(node);
+	if (path === void 0 || path.length < 2) return;
+	const [root, ...rest] = path;
+	if (root === void 0 || !roots.has(root)) return;
+	const key = rest.join(".");
+	if (!knownKeys.has(key) && isFieldOrSubtree(rest, knownKeys)) return;
+	const call = callName(parent);
+	const usage = {
+		file: fileRel,
+		line: lineAt(source, node.start ?? 0),
+		call
+	};
+	if (call === "allow") allowKeys.add(key);
+	pushUsage(key, usage, knownKeys, usages, unknown);
+}
+const LEAF_FIELDS = /* @__PURE__ */ new Set([
+	"key",
+	"resource",
+	"action",
+	"scope",
+	"meta"
+]);
+function isFieldOrSubtree(path, knownKeys) {
+	const last = path.at(-1);
+	if (last !== void 0 && LEAF_FIELDS.has(last) && knownKeys.has(path.slice(0, -1).join("."))) return true;
+	const prefix = `${path.join(".")}.`;
+	return [...knownKeys].some((known) => known.startsWith(prefix));
+}
+function pushUsage(key, usage, knownKeys, usages, unknown) {
+	if (knownKeys.size > 0 && !knownKeys.has(key)) {
+		unknown.push({
+			...usage,
+			call: `${usage.call}:${key}`
+		});
+		return;
+	}
+	const list = usages[key] ?? [];
+	list.push(usage);
+	usages[key] = list;
+}
+function calleeName(node) {
+	if (node === void 0) return;
+	if (node.type === "Identifier") return node.name;
+	if (node.type === "MemberExpression" && node.property?.type === "Identifier") return node.property.name;
+}
+function declaredName(parent) {
+	if (parent?.type === "VariableDeclarator" && parent.id?.type === "Identifier") return parent.id.name;
+}
+function callName(parent) {
+	if (parent?.type === "CallExpression") {
+		const name = calleeName(parent.callee);
+		if (name !== void 0 && CHECK_CALLS.has(name)) return name;
+	}
+	if (parent?.type === "Property" || parent?.type === "ObjectProperty") return "tools";
+	return "reference";
+}
+function memberPath(node) {
+	const parts = [];
+	let current = node;
+	while (current?.type === "MemberExpression") {
+		if (current.computed === true) return;
+		const name = current.property?.name;
+		if (name === void 0) return;
+		parts.unshift(name);
+		current = current.object;
+	}
+	if (current?.type !== "Identifier" || current.name === void 0) return;
+	parts.unshift(current.name);
+	return parts;
+}
+function rootName(node) {
+	let current = node;
+	while (current?.type === "MemberExpression") current = current.object;
+	return current?.type === "Identifier" ? current.name : void 0;
+}
+function lineAt(source, index) {
+	let line = 1;
+	const end = Math.min(index, source.length);
+	for (let i = 0; i < end; i += 1) if (source.charCodeAt(i) === 10) line += 1;
+	return line;
+}
+function collectObjectKeys(node, into) {
+	if (node?.type !== "ObjectExpression" || node.properties === void 0) return;
+	for (const property of node.properties) {
+		const key = property.key;
+		if (property.computed !== true && typeof key?.name === "string") {
+			into.add(key.name);
+			continue;
+		}
+		if (typeof key?.value === "string") into.add(key.value);
+	}
+}
+/** Every node in source order, with its parent: Oxc nodes carry none, so enter and exit keep a stack. */
+function walk(program, visit) {
+	const stack = [];
+	const handlers = {};
+	for (const type of Object.keys(visitorKeys)) {
+		handlers[type] = (node) => {
+			visit(node, stack.at(-1));
+			stack.push(node);
+		};
+		handlers[`${type}:exit`] = () => {
+			stack.pop();
+		};
+	}
+	new Visitor(handlers).visit(program);
+}
+//#endregion
+//#region src/cli/collect.ts
+async function runCollect(input) {
+	const srcPath = input.collect.srcPath ?? input.config.collect?.srcPath ?? defaultSrcPath();
+	const outPath = catalogPath(input.config, input.cwd, input.collect.out);
+	const permissionsRel = input.config.permissions ?? guessPermissions(input.cwd, srcPath);
+	if (permissionsRel === void 0) return {
+		code: 2,
+		document: void 0,
+		scan: void 0,
+		outPath,
+		message: "usage: set permissions in permdock.config.ts or pass a definePermissions module"
+	};
+	const permissionsAbs = resolve(input.cwd, permissionsRel);
+	if (!existsSync(permissionsAbs)) return {
+		code: 2,
+		document: void 0,
+		scan: void 0,
+		outPath,
+		message: `PermDock CLI: permissions module not found: ${rel(input.cwd, permissionsAbs)}`
+	};
+	let tree;
+	try {
+		const mod = await loadModule(permissionsAbs);
+		tree = asPermissionTree(pickNamed(mod, ["permissions"]));
+	} catch (error) {
+		return {
+			code: 2,
+			document: void 0,
+			scan: void 0,
+			outPath,
+			message: error instanceof Error ? error.message : String(error)
+		};
+	}
+	const files = listSourceFiles(input.cwd, srcPath);
+	const knownKeys = new Set(leavesOf(tree).map((leaf) => leaf.key));
+	const scan = scanSources(input.cwd, files, knownKeys);
+	const document = buildCatalog(tree, scan, input.now.toISOString(), await loadConfiguredPolicy(input.cwd, input.config.policy));
+	const next = formatCatalogJson(document);
+	if (input.check) {
+		if (!existsSync(outPath)) return {
+			code: 1,
+			document,
+			scan,
+			outPath,
+			message: `catalog missing: ${rel(input.cwd, outPath)}`
+		};
+		const current = readFileSync(outPath, "utf8");
+		const currentDoc = JSON.parse(current);
+		const onDisk = catalogForCompare(currentDoc);
+		const generated = catalogForCompare(document);
+		if (onDisk !== generated) {
+			const file = rel(input.cwd, outPath);
+			return {
+				code: 1,
+				document,
+				scan,
+				outPath,
+				message: `catalog drift: ${file}\n${shortDiff(file, onDisk, generated)}`
+			};
+		}
+		return {
+			code: 0,
+			document,
+			scan,
+			outPath,
+			message: `catalog up to date: ${rel(input.cwd, outPath)}`
+		};
+	}
+	mkdirSync(dirname(outPath), { recursive: true });
+	writeFileSync(outPath, next);
+	const barrel = input.collect.barrel ?? input.config.collect?.barrel;
+	if (barrel !== void 0 && barrel !== false) writeBarrel(resolve(input.cwd, barrel === true ? "src/permissions.generated.ts" : barrel), permissionsAbs);
+	return {
+		code: 0,
+		document,
+		scan,
+		outPath,
+		message: `wrote ${rel(input.cwd, outPath)}`
+	};
+}
+function guessPermissions(cwd, srcPath) {
+	return [
+		"src/permissions.ts",
+		"permissions.ts",
+		...srcPath.map((entry) => `${entry.replace(/\/$/, "")}/permissions.ts`)
+	].find((file) => existsSync(resolve(cwd, file)));
+}
+function writeBarrel(abs, permissionsAbs) {
+	const specifier = relative(dirname(abs), permissionsAbs).replace(/\\/gu, "/").replace(/\.tsx?$/u, ".js");
+	const body = `// @generated by permdock — do not edit
+import { mergePermissions } from 'permdock'
+import { permissions as collected } from '${specifier.startsWith(".") ? specifier : `./${specifier}`}'
+
+export const permissions = mergePermissions(collected)
+`;
+	mkdirSync(dirname(abs), { recursive: true });
+	writeFileSync(abs, body);
+}
+//#endregion
+export { scanSources as n, runCollect as t };

package/dist/collect-fRPAQIWb.js

@@ -0,0 +1,2 @@
+import { t as runCollect } from "./collect-O-tOtbnk.js";
+export { runCollect };

package/dist/commands-BMh_Etm2.js

@@ -0,0 +1,93 @@
+//#region src/cli/commands/context.ts
+/** Flags every command accepts. `run()` reads them from anywhere in argv. */
+const globalArgs = {
+	cwd: {
+		type: "string",
+		description: "Run as if started in this directory",
+		valueHint: "dir"
+	},
+	config: {
+		type: "string",
+		description: "Config file (default permdock.config.{ts,mts,js,mjs})",
+		valueHint: "file"
+	},
+	json: {
+		type: "boolean",
+		description: "Machine-readable output"
+	},
+	yes: {
+		type: "boolean",
+		alias: "y",
+		description: "Never prompt; take the answer the flags give"
+	},
+	color: {
+		type: "boolean",
+		description: "Styled output on a colour terminal",
+		default: true,
+		negativeDescription: "Plain output"
+	}
+};
+/**
+* A list flag: every `--name a,b` and `--name=c` occurrence, comma-split and
+* trimmed, in order. citty keeps only the last occurrence of a string flag.
+*/
+function listArg(rawArgs, name) {
+	const values = [];
+	const flag = `--${name}`;
+	for (const [i, token] of rawArgs.entries()) {
+		if (token === "--") break;
+		let value;
+		if (token.startsWith(`${flag}=`)) value = token.slice(flag.length + 1);
+		else if (token === flag) {
+			const next = rawArgs[i + 1];
+			if (next !== void 0 && (next === "-" || !next.startsWith("-"))) value = next;
+		}
+		if (value !== void 0) values.push(...value.split(",").map((item) => item.trim()));
+	}
+	return values;
+}
+/** A command's flag and positional definitions, whatever form it declared them in. */
+function resolveArgs(command) {
+	const args = command.args;
+	if (args === void 0) return {};
+	return typeof args === "function" ? args() : args;
+}
+/** A string flag, `undefined` when absent or given without a value. */
+function stringArg(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+//#endregion
+//#region src/cli/commands/index.ts
+/** What `permdock --help` lists, without loading any command module. */
+const COMMAND_DESCRIPTIONS = {
+	collect: "Scan the sources for definePermissions() and permission references; write the catalog and barrel",
+	catalog: "Export the catalog as JSON, JSON Schema or Markdown",
+	diff: "Compare two policies or catalogs; exit 1 on a breaking change",
+	usage: "Report unused, ungranted and role-less permissions and conditions on undeclared fields",
+	doctor: "Check a PermDock installation and print a fix for each finding",
+	skills: "Install, update or list the PermDock Agent Skills",
+	openapi: "Emit security into an OpenAPI document, or import one into a generated definition",
+	rls: "Generate, import, verify or migrate Postgres RLS policies from the policy",
+	arazzo: "Resolve every Arazzo step to x-permdock-permissions",
+	cloud: "Publish the catalog, hostable flags and role assignability to a PermDock Cloud environment",
+	supabase: "Generate the Supabase Custom Access Token Hook, or inspect its manifest"
+};
+/** Every top-level command, loaded only when it runs or its own `--help` is asked for. */
+const commands = {
+	collect: async () => (await import("./collect-B7_TIfmg.js")).collect,
+	catalog: async () => (await import("./catalog-B0E6bggc.js")).catalog,
+	diff: async () => (await import("./diff-BUzf5Poi.js")).diff,
+	usage: async () => (await import("./usage-1ozMubLY.js")).usage,
+	doctor: async () => (await import("./doctor-Bqo6FwUa.js")).doctor,
+	skills: async () => (await import("./skills-C_lpV4Jx.js")).skills,
+	openapi: async () => (await import("./openapi-CwePaF7C.js")).openapi,
+	rls: async () => (await import("./rls-BOFU3chG.js")).rls,
+	arazzo: async () => (await import("./arazzo-aoTkqYsJ.js")).arazzo,
+	cloud: async () => (await import("./cloud-BNQTrmrr.js")).cloud,
+	supabase: async () => (await import("./supabase-D8UlBA7Z.js")).supabase
+};
+function isCommand(name) {
+	return Object.hasOwn(commands, name);
+}
+//#endregion
+export { listArg as a, globalArgs as i, commands as n, resolveArgs as o, isCommand as r, stringArg as s, COMMAND_DESCRIPTIONS as t };

package/dist/compact-y6vfu2_f.js

@@ -0,0 +1,19 @@
+//#region src/core/compact.ts
+function compact(value) {
+	const result = {};
+	for (const key of Object.keys(value)) {
+		const next = value[key];
+		if (next !== void 0) result[key] = next;
+	}
+	return result;
+}
+/** `Array.isArray` that keeps `readonly T[]` instead of widening to `any[]`. */
+function isReadonlyArray(value) {
+	return Array.isArray(value);
+}
+/** The element of a one-element list, else `undefined`. */
+function sole(items) {
+	return items.length === 1 ? items[0] : void 0;
+}
+//#endregion
+export { isReadonlyArray as n, sole as r, compact as t };

package/dist/compare-pfyVnBjE.js

@@ -0,0 +1,12 @@
+//#region src/core/compare.ts
+/**
+* Orders strings by UTF-16 code unit, the same in every locale and runtime,
+* so sorted output is byte-stable where `localeCompare` would follow the ICU
+* build.
+*/
+function byCodePoint(a, b) {
+	if (a === b) return 0;
+	return a < b ? -1 : 1;
+}
+//#endregion
+export { byCodePoint as t };

package/dist/compile-CQbvyIBr.d.ts

@@ -0,0 +1,30 @@
+//#region src/conditions/compile.d.ts
+type MembershipTable = {
+  readonly table: string;
+  readonly user: string;
+  readonly role: string;
+  /** Per scope name, the column holding that scope's id (the row's own scope and its ancestors). */
+  readonly columns?: Readonly<Record<string, string>>;
+  /** Column of the first scope's id; shorthand for `columns[<first scope>]`. */
+  readonly tenant?: string;
+  /** Column of the second scope's id; shorthand for `columns[<second scope>]`. */
+  readonly team?: string;
+  readonly id?: string;
+  /** Column naming the membership's resource, when one table holds several kinds. */
+  readonly resource?: string;
+  /** Column holding the membership kind (`Membership.via`); roles with `for` need it. */
+  readonly via?: string;
+  /** Unix seconds, like `Membership.expiresAt`; `null` never expires. */
+  readonly expiresAt?: string;
+};
+type MembershipsMapping = {
+  /** The membership table of each named scope. */
+  readonly scopes?: Readonly<Record<string, MembershipTable>>;
+  /** The first scope's table; shorthand for `scopes[<first scope>]`. */
+  readonly tenant?: MembershipTable;
+  /** The second scope's table; shorthand for `scopes[<second scope>]`. */
+  readonly team?: MembershipTable;
+  readonly resource?: Readonly<Record<string, MembershipTable>>;
+};
+//#endregion
+export { MembershipsMapping as t };