@softr/sdk 0.0.11 → 0.0.13

package/dist/routes/discover.d.ts

@@ -0,0 +1,9 @@
+import "@tanstack/router-generator";
+
+//#region src/routes/discover.d.ts
+
+type VisibilityValue = string | Array<VisibilityValue> | {
+  [key: string]: VisibilityValue;
+};
+//#endregion
+export { VisibilityValue };

package/dist/routes/discover.js

@@ -0,0 +1,198 @@
+import { createReadOnlyFs } from "./mem-fs.js";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { Generator, getConfig } from "@tanstack/router-generator";
+import os from "node:os";
+import { parse } from "@babel/parser";
+import babelTraverse from "@babel/traverse";
+
+//#region src/routes/discover.ts
+async function crawlRoutes(opts) {
+	const config = getConfig({
+		disableLogging: true,
+		tmpDir: TMP_DIR,
+		generatedRouteTree: generatedRouteTreePath()
+	}, opts.root);
+	const generator = new Generator({
+		config,
+		root: opts.root,
+		fs: createReadOnlyFs()
+	});
+	await generator.run();
+	const crawlingResult = await generator.getCrawlingResult();
+	if (!crawlingResult) throw new Error(`the route crawl produced no result for ${opts.root}`);
+	return {
+		rootRouteNode: crawlingResult.rootRouteNode,
+		routeNodes: crawlingResult.acc.routeNodes,
+		routePiecesByPath: crawlingResult.acc.routePiecesByPath,
+		routeTree: crawlingResult.acc.routeTree,
+		routesDirectory: path.relative(opts.root, path.resolve(opts.root, config.routesDirectory)).split(path.sep).join("/")
+	};
+}
+/** Reads the rule out of the source text. The route file is never executed. */
+function extractVisibility(source, filePath) {
+	let program;
+	try {
+		program = parse(source, {
+			sourceType: "module",
+			plugins: ["typescript", "jsx"]
+		});
+	} catch (error) {
+		const position = error.loc;
+		return fail("unparsable", `could not parse ${filePath}: ${error.message}`, filePath, position?.line ?? 1, position?.column ?? 0);
+	}
+	const calls = findVisibilityCalls(program);
+	if (calls.length > 1) {
+		const second = calls[1].call;
+		return fail("duplicate-declaration", `${filePath} declares visibility more than once; a route has exactly one rule`, filePath, second.loc?.start.line ?? 1, second.loc?.start.column ?? 0);
+	}
+	const declaration = calls[0];
+	if (declaration === void 0) return {
+		ok: true,
+		visibility: null
+	};
+	const { call, statement } = declaration;
+	const argument = call.arguments[0];
+	if (argument === void 0) return fail("not-literal", `${filePath} calls ${VISIBILITY_FUNCTION} with no argument`, filePath, call.loc?.start.line ?? 1, call.loc?.start.column ?? 0);
+	const read = readLiteral(argument);
+	if (!read.ok) return fail("not-literal", `${filePath}: the visibility rule must be a literal — ${read.reason}`, filePath, read.line, read.column);
+	return {
+		ok: true,
+		visibility: {
+			value: read.value,
+			line: statement.loc?.start.line ?? 1,
+			column: statement.loc?.start.column ?? 0
+		}
+	};
+}
+/**
+* The generator `mkdirSync`s `tmpDir` and the directory of `generatedRouteTree` outside the `fs`
+* shim, so defaulted they create directories in the crawled project. Aimed at `os.tmpdir()` both
+* calls are no-ops, and nothing is ever written through either path. The uuid keeps the generated
+* tree file a miss rather than whatever a shared temp directory happens to hold.
+*/
+const TMP_DIR = os.tmpdir();
+const generatedRouteTreePath = () => path.join(TMP_DIR, `softr-sdk-route-tree-${randomUUID()}.gen.ts`);
+const SDK_PACKAGE_NAME = "@softr/sdk";
+const VISIBILITY_FUNCTION = "defineVisibility";
+function fail(code, message, filePath, line, column) {
+	return {
+		ok: false,
+		error: {
+			code,
+			message,
+			filePath,
+			line,
+			column
+		}
+	};
+}
+const traverse = babelTraverse.default ?? babelTraverse;
+/** Only a call initialising a top-level variable counts; one inside a function or block does not. */
+function findVisibilityCalls(ast) {
+	const found = [];
+	traverse(ast, { VariableDeclarator(path$1) {
+		const list = path$1.parentPath;
+		if (!list.isVariableDeclaration()) return;
+		const statement = list.parentPath.isExportNamedDeclaration() ? list.parentPath : list;
+		if (!statement.parentPath?.isProgram()) return;
+		if (path$1.node.init === null || path$1.node.init === void 0) return;
+		const call = unwrap(path$1.node.init);
+		if (call.type !== "CallExpression" && call.type !== "OptionalCallExpression") return;
+		if (call.callee.type !== "Identifier") return;
+		if (!isVisibilityImport(path$1, call.callee.name)) return;
+		found.push({
+			call,
+			statement: statement.node
+		});
+	} });
+	return found;
+}
+function isVisibilityImport(path$1, name) {
+	const binding = path$1.scope.getBinding(name);
+	if (binding === void 0 || binding.kind !== "module") return false;
+	const specifier = binding.path.node;
+	const declaration = binding.path.parent;
+	if (specifier.type !== "ImportSpecifier" || declaration.type !== "ImportDeclaration") return false;
+	if (specifier.importKind === "type" || declaration.importKind === "type") return false;
+	if (declaration.source.value !== SDK_PACKAGE_NAME) return false;
+	return (specifier.imported.type === "Identifier" ? specifier.imported.name : specifier.imported.value) === VISIBILITY_FUNCTION;
+}
+/** Strips the wrappers that leave the runtime value unchanged: `as const`, `satisfies`, `!`, `()`. */
+function unwrap(node) {
+	switch (node.type) {
+		case "TSAsExpression":
+		case "TSSatisfiesExpression":
+		case "TSNonNullExpression":
+		case "TSTypeAssertion":
+		case "TSInstantiationExpression":
+		case "ParenthesizedExpression": return unwrap(node.expression);
+		default: return node;
+	}
+}
+function reject(node, reason) {
+	return {
+		ok: false,
+		reason,
+		line: node.loc?.start.line ?? 1,
+		column: node.loc?.start.column ?? 0
+	};
+}
+function readLiteral(input) {
+	const node = unwrap(input);
+	switch (node.type) {
+		case "StringLiteral": return {
+			ok: true,
+			value: node.value
+		};
+		case "TemplateLiteral":
+			if (node.expressions.length > 0) return reject(node, "a template literal with an expression is not a static value");
+			return {
+				ok: true,
+				value: node.quasis[0]?.value.cooked ?? ""
+			};
+		case "ArrayExpression": {
+			const values = [];
+			for (const element of node.elements) {
+				if (element === null) return reject(node, "an array hole is not a static value");
+				if (element.type === "SpreadElement") return reject(element, "a spread is not a static value");
+				const read = readLiteral(element);
+				if (!read.ok) return read;
+				values.push(read.value);
+			}
+			return {
+				ok: true,
+				value: values
+			};
+		}
+		case "ObjectExpression": {
+			const value = {};
+			for (const property of node.properties) {
+				if (property.type === "SpreadElement") return reject(property, "a spread is not a static value");
+				if (property.type === "ObjectMethod") return reject(property, "a method is not a static value");
+				if (property.computed) return reject(property, "a computed key is not a static value");
+				if (property.shorthand) return reject(property, "a shorthand property is not a static value");
+				const key = property.key.type === "Identifier" ? property.key.name : property.key.type === "StringLiteral" ? property.key.value : null;
+				if (key === null) return reject(property.key, "this key is not a static value");
+				if (key === "__proto__") return reject(property.key, "a __proto__ key is not a static value");
+				const read = readLiteral(property.value);
+				if (!read.ok) return read;
+				value[key] = read.value;
+			}
+			return {
+				ok: true,
+				value
+			};
+		}
+		case "NumericLiteral":
+		case "BooleanLiteral":
+		case "NullLiteral": return reject(node, "a visibility rule is built from strings, arrays and objects");
+		case "Identifier": return reject(node, `an identifier (${node.name}) is not a static value`);
+		case "CallExpression":
+		case "NewExpression": return reject(node, "a call is not a static value");
+		default: return reject(node, `${node.type} is not a static value`);
+	}
+}
+
+//#endregion
+export { crawlRoutes, extractVisibility };

package/dist/routes/manifest.d.ts

@@ -0,0 +1,17 @@
+import { VisibilityValue } from "./discover.js";
+
+//#region src/routes/manifest.d.ts
+type ManifestNode = {
+  routePath: string;
+  filePath: string;
+  _fsRouteType?: string;
+  inferFullPath: string | null;
+  createFileRouteProps: Array<string>;
+  visibility: VisibilityValue | null;
+  children: Array<ManifestNode>;
+};
+type Manifest = {
+  root: ManifestNode;
+};
+//#endregion
+export { Manifest, ManifestNode };

package/dist/routes/manifest.js

@@ -0,0 +1,148 @@
+import { crawlRoutes, extractVisibility } from "./discover.js";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { inferFullPath } from "@tanstack/router-generator";
+
+//#region src/routes/manifest.ts
+var ManifestError = class extends Error {
+	detail;
+	constructor(detail) {
+		super(detail.message);
+		this.name = "ManifestError";
+		this.detail = detail;
+	}
+};
+/** Returns the manifest as the exact text to write. Throws on a declaration it cannot read. */
+async function generateRoutesManifest(root) {
+	const crawl = await crawlRoutes({ root });
+	const routeFiles = new Set([crawl.rootRouteNode.filePath]);
+	for (const node of crawl.routeNodes) routeFiles.add(node.filePath);
+	for (const pieces of Object.values(crawl.routePiecesByPath)) if (pieces.lazy) routeFiles.add(pieces.lazy.filePath);
+	const sources = /* @__PURE__ */ new Map();
+	for (const relative of routeFiles) {
+		const absolute = path.resolve(root, crawl.routesDirectory, relative);
+		const source = await readIfPresent(absolute);
+		if (source !== null) sources.set(absolute, source);
+	}
+	const manifest = buildManifest({
+		crawl,
+		root,
+		sources
+	});
+	return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+function buildManifest(opts) {
+	const routesDirectory = opts.crawl.routesDirectory;
+	const toNode = (node) => {
+		const projectRelative = toProjectRelative(opts.root, routesDirectory, node.filePath);
+		const routePath = node.routePath;
+		if (routePath === void 0) throw new Error(`the route crawl produced a node with no route path: ${projectRelative}`);
+		let declared = visibilityOf(opts, node.filePath);
+		const lazyPiece = opts.crawl.routePiecesByPath[routePath]?.lazy;
+		if (lazyPiece && lazyPiece.filePath !== node.filePath) {
+			const lazyDeclared = visibilityOf(opts, lazyPiece.filePath);
+			if (lazyDeclared !== null && declared !== null) throw new ManifestError({
+				code: "duplicate-declaration",
+				message: `${routePath} declares visibility in both ${projectRelative} and ${lazyDeclared.filePath}; a route has exactly one rule`,
+				filePath: lazyDeclared.filePath,
+				line: lazyDeclared.line,
+				column: lazyDeclared.column
+			});
+			if (lazyDeclared !== null) declared = lazyDeclared;
+		}
+		return {
+			routePath,
+			filePath: projectRelative,
+			...node._fsRouteType ? { _fsRouteType: node._fsRouteType } : {},
+			inferFullPath: inferFullPath(node) ?? null,
+			createFileRouteProps: [...node.createFileRouteProps ?? []].sort(),
+			visibility: declared?.value ?? null,
+			children: (node.children ?? []).map(toNode)
+		};
+	};
+	const rootNode = opts.crawl.rootRouteNode;
+	const rootRelative = toProjectRelative(opts.root, routesDirectory, rootNode.filePath);
+	const rootDeclared = visibilityOf(opts, rootNode.filePath);
+	if (rootDeclared !== null) throw new ManifestError({
+		code: "root-declaration",
+		message: "the root route cannot carry a visibility rule: it would gate sign-in with no way back in. Move this declaration to the routes you want gated.",
+		filePath: rootRelative,
+		line: rootDeclared.line,
+		column: rootDeclared.column
+	});
+	return { root: {
+		routePath: ROOT_ROUTE_ID,
+		filePath: rootRelative,
+		inferFullPath: inferFullPath(rootNode) ?? null,
+		createFileRouteProps: [...rootNode.createFileRouteProps ?? []].sort(),
+		visibility: null,
+		children: opts.crawl.routeTree.map(toNode)
+	} };
+}
+/**
+* `rootRouteId` from `@tanstack/router-core`, which is what a consumer matches against — not the
+* generator's `rootPathId`, which is the base name of `__root.tsx` and names a file, not a route.
+*/
+const ROOT_ROUTE_ID = "__root__";
+/** The crawl's paths are relative to the routes directory; the manifest's are project-relative. */
+function toProjectRelative(root, routesDirectory, filePath) {
+	const absolute = path.resolve(root, routesDirectory, filePath);
+	return path.relative(root, absolute).split(path.sep).join("/");
+}
+const USER_GROUPS = [
+	"ALL_USERS",
+	"NON_LOGGED_IN_USERS",
+	"LOGGED_IN_USERS"
+];
+function checkVisibilityShape(declared) {
+	const reject = (message) => {
+		throw new ManifestError({
+			code: "invalid-visibility",
+			message: `${declared.filePath}: ${message}`,
+			filePath: declared.filePath,
+			line: declared.line,
+			column: declared.column
+		});
+	};
+	const visibility = declared.value;
+	if (typeof visibility !== "object" || Array.isArray(visibility)) reject(`the visibility rule must be an object literal like { userGroup: 'ALL_USERS' }, not ${JSON.stringify(visibility)}`);
+	for (const key of Object.keys(visibility)) {
+		if (key === "userGroup" || key === "userGroupIds") continue;
+		reject(`"${key}" is not part of a visibility rule; a rule has userGroup and, under LOGGED_IN_USERS, userGroupIds. Check the spelling.`);
+	}
+	const userGroup = visibility["userGroup"];
+	if (typeof userGroup !== "string" || !USER_GROUPS.includes(userGroup)) reject(`userGroup must be one of ${USER_GROUPS.join(", ")}, not ${JSON.stringify(userGroup)}. A rule the build cannot read is a route with no rule at all.`);
+	if (!("userGroupIds" in visibility)) return;
+	if (userGroup !== "LOGGED_IN_USERS") reject(`userGroupIds only means anything under LOGGED_IN_USERS, not under ${userGroup}`);
+	const ids = visibility["userGroupIds"];
+	if (!Array.isArray(ids) || ids.some((id) => typeof id !== "string")) reject(`userGroupIds must be an array of group id strings, not ${JSON.stringify(ids)}. Drop the key entirely to mean "any logged-in user".`);
+}
+function visibilityOf(opts, filePath) {
+	const projectRelative = toProjectRelative(opts.root, opts.crawl.routesDirectory, filePath);
+	const source = opts.sources.get(path.resolve(opts.root, opts.crawl.routesDirectory, filePath));
+	if (source === void 0) return null;
+	const result = extractVisibility(source, projectRelative);
+	if (!result.ok) throw new ManifestError(result.error);
+	if (result.visibility === null) return null;
+	const declared = {
+		...result.visibility,
+		filePath: projectRelative
+	};
+	checkVisibilityShape(declared);
+	return declared;
+}
+/**
+* Only ENOENT becomes `null`. The caller reads `null` as "nothing declared here", so swallowing any
+* other read error would turn an unreadable declaration into an ungated route.
+*/
+async function readIfPresent(filePath) {
+	try {
+		return await readFile(filePath, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+//#endregion
+export { ManifestError, generateRoutesManifest };

package/dist/routes/mem-fs.js

@@ -0,0 +1,71 @@
+import * as nodeFs from "node:fs/promises";
+import path from "node:path";
+
+//#region src/routes/mem-fs.ts
+/**
+* Reads through to disk and swallows every write. Driving the generator without this rewrites the
+* app's route sources and strips Start's `Register` block from its routeTree.gen.ts.
+*/
+function createReadOnlyFs() {
+	const writes = /* @__PURE__ */ new Map();
+	return {
+		async stat(filePath) {
+			const stat = await statOrNull(path.resolve(filePath));
+			if (stat === null) return {
+				mtimeMs: SYNTHETIC_MTIME,
+				mode: 420,
+				uid: 0,
+				gid: 0
+			};
+			return {
+				mtimeMs: stat.mtimeMs,
+				mode: Number(stat.mode),
+				uid: Number(stat.uid),
+				gid: Number(stat.gid)
+			};
+		},
+		async rename(oldPath, newPath) {
+			const from = path.resolve(oldPath);
+			const content = writes.get(from);
+			if (content !== void 0) {
+				writes.delete(from);
+				writes.set(path.resolve(newPath), content);
+			}
+		},
+		async writeFile(filePath, content) {
+			writes.set(path.resolve(filePath), content);
+		},
+		async readFile(filePath) {
+			const resolved = path.resolve(filePath);
+			const pending = writes.get(resolved);
+			const stat = await statOrNull(resolved);
+			if (pending !== void 0) return {
+				stat: { mtimeMs: stat?.mtimeMs ?? SYNTHETIC_MTIME },
+				fileContent: pending
+			};
+			if (stat === null) return "file-not-existing";
+			try {
+				const fileContent = await nodeFs.readFile(resolved, "utf8");
+				return {
+					stat: { mtimeMs: stat.mtimeMs },
+					fileContent
+				};
+			} catch {
+				return "file-not-existing";
+			}
+		},
+		async chmod() {},
+		async chown() {}
+	};
+}
+const SYNTHETIC_MTIME = 1n;
+async function statOrNull(filePath) {
+	try {
+		return await nodeFs.stat(filePath, { bigint: true });
+	} catch {
+		return null;
+	}
+}
+
+//#endregion
+export { createReadOnlyFs };

package/dist/routes/visibility.d.ts

@@ -0,0 +1,142 @@
+import { SoftrUserGroupId, User } from "../auth/user.js";
+import { SoftrContext } from "../auth/context.js";
+
+//#region src/routes/visibility.d.ts
+
+/**
+ * Who may see a route.
+ *
+ * - `ALL_USERS` — everyone, signed in or not.
+ * - `NON_LOGGED_IN_USERS` — signed-out visitors only.
+ * - `LOGGED_IN_USERS` — signed-in visitors; with `userGroupIds`, only members of
+ *   at least one of those groups.
+ */
+type RouteVisibility = {
+  userGroup: "ALL_USERS";
+} | {
+  userGroup: "NON_LOGGED_IN_USERS";
+} | {
+  userGroup: "LOGGED_IN_USERS";
+  userGroupIds?: Array<SoftrUserGroupId>;
+};
+/**
+ * Why a visitor was denied.
+ *
+ * - `unauthenticated` — the route needs a signed-in visitor and there is none.
+ * - `forbidden` — signed in, but in none of the groups the route names.
+ * - `alreadySignedIn` — the route is for signed-out visitors only.
+ */
+declare const ACCESS_REASONS: readonly ["unauthenticated", "forbidden", "alreadySignedIn"];
+type AccessReason = (typeof ACCESS_REASONS)[number];
+/**
+ * What a guard does when it refuses a visitor: redirect to a path, or throw an
+ * {@link AccessError} for the route's `errorComponent` to render. A bare string
+ * is shorthand for redirecting there.
+ */
+type AccessBehaviour = string | {
+  strategy: "redirect";
+  to: string;
+} | {
+  strategy: "throw";
+};
+/** Per-reason overrides of the default {@link AccessBehaviour}. */
+type GuardOverrides = Partial<Record<AccessReason, AccessBehaviour>>;
+/** The result of {@link VisibilityHandle.check}: passed, or denied with a reason. */
+type AccessCheck = {
+  ok: true;
+} | {
+  ok: false;
+  reason: AccessReason;
+};
+/** The one field of {@link SoftrContext} every access check reads. */
+type AccessContext = Pick<SoftrContext, "user">;
+/** Decides whether a visitor passes a visibility rule, without throwing. */
+
+/**
+ * The access error a guard throws. It is plain data, not an `Error` subclass, so
+ * take it as `unknown` in an `errorComponent` and narrow it with
+ * {@link isAccessError}. It carries the reason and nothing else: the error is
+ * serialized into the page, so it never names the groups the route wanted.
+ *
+ * @example
+ * errorComponent: ({ error }: { error: unknown }) =>
+ *   isAccessError(error) ? <NoAccess /> : <AppError />
+ */
+type AccessError = {
+  type: "access_error";
+  reason: AccessReason;
+};
+/**
+ * True for any access error thrown by a guard, whatever its reason.
+ *
+ * An access error arrives as `unknown` — hydrated from the page, or thrown by
+ * anything else at all — so every field is checked before it is narrowed.
+ */
+declare function isAccessError(error: unknown): error is AccessError;
+/** True for an access error thrown because nobody was signed in. */
+declare function isUnauthenticatedError(error: unknown): error is AccessError;
+/** True for an access error thrown because the visitor was in none of the groups. */
+declare function isForbiddenError(error: unknown): error is AccessError;
+/** True for an access error thrown because a signed-out-only route saw a user. */
+declare function isAlreadySignedInError(error: unknown): error is AccessError;
+type Narrowed<R extends RouteVisibility> = R extends {
+  userGroup: "LOGGED_IN_USERS";
+} ? AccessContext & {
+  user: User;
+} : R extends {
+  userGroup: "NON_LOGGED_IN_USERS";
+} ? AccessContext & {
+  user: null;
+} : AccessContext;
+/** The four ways to apply a rule, returned by {@link defineVisibility}. */
+type VisibilityHandle<R extends RouteVisibility = RouteVisibility> = {
+  /**
+   * A `beforeLoad` handler that denies a visitor who fails the rule.
+   *
+   * By default an unauthenticated visitor is redirected to `/login`, an already
+   * signed-in one to `/`, and a forbidden one gets an {@link AccessError} thrown
+   * in place, for the route's `errorComponent` to render. Pass `overrides` to
+   * change what any one reason does.
+   *
+   * @example
+   * beforeLoad: visibility.guard({ unauthenticated: "/sign-in" })
+   */
+  guard(overrides?: GuardOverrides): (opts: {
+    context: AccessContext;
+  }) => void;
+  /**
+   * Throws the same access error or redirect `guard()` would, for code that
+   * needs to run its own checks after the rule.
+   *
+   * @example
+   * beforeLoad: ({ context }) => {
+   *   visibility.assert(context)
+   *   if (context.user.trialExpired) throw redirect({ to: "/renew" })
+   * }
+   */
+  assert(context: AccessContext): void;
+  /**
+   * Whether the visitor passes the rule. Narrows `context.user` where the rule
+   * allows it.
+   */
+  isAuthorized(context: AccessContext): context is Narrowed<R>;
+  /** The decision and, when a visitor is refused, the reason. Throws nothing. */
+  check(context: AccessContext): AccessCheck;
+};
+/**
+ * Declares who may see a route, and returns the handle that enforces it.
+ *
+ * One call per route file, at module scope: the build reads these declarations
+ * to publish the app's route visibility, so the rule must be a literal.
+ *
+ * @example
+ * const visibility = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
+ *
+ * export const Route = createFileRoute("/about")({
+ *   beforeLoad: visibility.guard(),
+ *   component: About,
+ * })
+ */
+declare function defineVisibility<const R extends RouteVisibility>(rule: R): VisibilityHandle<R>;
+//#endregion
+export { AccessBehaviour, AccessCheck, AccessError, AccessReason, RouteVisibility, VisibilityHandle, defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError };