@softr/sdk 0.0.1

package/README.md

@@ -0,0 +1,3 @@
+# @softr/sdk
+
+Internal Softr package. Not intended for direct use.

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+import { a as ListResult, c as SoftrRecord, d as WorkflowAPI, i as ListOptions, l as SoftrSDK, n as DatasourceAPI, o as SoftrMe, r as DatasourcePermissions, s as SoftrPermissions, t as AuthAPI, u as SoftrUser } from "./types-BLLUI6MI.js";
+
+//#region src/routes/visibility.d.ts
+type RouteVisibility = {
+  userGroup: "ALL_USERS";
+} | {
+  userGroup: "NON_LOGGED_IN_USERS";
+} | {
+  userGroup: "LOGGED_IN_USERS";
+  userGroupIds?: Array<SoftrUserGroupId>;
+};
+/** Shape of the TanStack route context after the root route's beforeLoad. */
+type SoftrContext = {
+  user: SoftrUser | null;
+};
+type RefusalReason = "unauthenticated" | "forbidden" | "alreadySignedIn";
+type RefusalBehaviour = string | {
+  strategy: "redirect";
+  to: string;
+} | {
+  strategy: "throw";
+};
+type GuardOverrides = Partial<Record<RefusalReason, RefusalBehaviour>>;
+type CheckResult = {
+  ok: true;
+} | {
+  ok: false;
+  reason: "unauthenticated" | "alreadySignedIn";
+} | {
+  ok: false;
+  reason: "forbidden";
+  requiredGroupIds: Array<SoftrUserGroupId>;
+};
+declare class VisibilityError extends Error {
+  readonly reason: RefusalReason;
+  readonly requiredGroupIds: Array<SoftrUserGroupId> | undefined;
+  constructor(reason: RefusalReason, requiredGroupIds?: Array<SoftrUserGroupId>);
+}
+interface VisibilityHandle {
+  /** Structured check — returns { ok: true } or { ok: false, reason }. */
+  check(context: SoftrContext): CheckResult;
+  /** Returns true if the visitor passes the rule. */
+  isAuthorized(context: SoftrContext): boolean;
+  /**
+   * Throws a VisibilityError if not authorized. Acts as a TypeScript assertion,
+   * narrowing context.user to non-null for code that follows.
+   *
+   * @example
+   * beforeLoad: ({ context }) => {
+   *   visibility.assert(context)
+   *   if (context.user.trialExpired) throw redirect({ to: '/renew' })
+   * }
+   */
+  assert(context: SoftrContext): asserts context is SoftrContext & {
+    user: SoftrUser;
+  };
+  /**
+   * Returns a TanStack beforeLoad handler. On refusal, throws a VisibilityError
+   * caught by the route's errorComponent.
+   *
+   * For redirect-on-refusal, use isAuthorized or check directly and throw
+   * TanStack's redirect() yourself.
+   *
+   * @example
+   * beforeLoad: visibility.guard()
+   * errorComponent: ({ error }) => isVisibilityError(error) ? <NoAccess /> : <AppError />
+   */
+  guard(overrides?: GuardOverrides): (params: {
+    context: SoftrContext;
+  }) => void;
+}
+declare function defineVisibility(rule: RouteVisibility): VisibilityHandle;
+declare function isVisibilityError(error: unknown): error is VisibilityError;
+declare function isUnauthenticatedError(error: unknown): error is VisibilityError & {
+  reason: "unauthenticated";
+};
+declare function isForbiddenError(error: unknown): error is VisibilityError & {
+  reason: "forbidden";
+};
+declare function isAlreadySignedInError(error: unknown): error is VisibilityError & {
+  reason: "alreadySignedIn";
+};
+//#endregion
+export { type AuthAPI, type CheckResult, type DatasourceAPI, type DatasourcePermissions, type GuardOverrides, type ListOptions, type ListResult, type RefusalBehaviour, type RefusalReason, type RouteVisibility, type SoftrContext, type SoftrMe, type SoftrPermissions, type SoftrRecord, type SoftrSDK, type SoftrUser, VisibilityError, type VisibilityHandle, type WorkflowAPI, defineVisibility, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, isVisibilityError };

package/dist/index.js

@@ -0,0 +1,73 @@
+//#region src/routes/visibility.ts
+var VisibilityError = class extends Error {
+	reason;
+	requiredGroupIds;
+	constructor(reason, requiredGroupIds) {
+		super(`Access denied: ${reason}`);
+		this.name = "VisibilityError";
+		this.reason = reason;
+		this.requiredGroupIds = requiredGroupIds;
+	}
+};
+function runCheck(rule, context) {
+	const { user } = context;
+	if (rule.userGroup === "ALL_USERS") return { ok: true };
+	if (rule.userGroup === "NON_LOGGED_IN_USERS") return user ? {
+		ok: false,
+		reason: "alreadySignedIn"
+	} : { ok: true };
+	if (!user) return {
+		ok: false,
+		reason: "unauthenticated"
+	};
+	const { userGroupIds } = rule;
+	if (userGroupIds?.length) {
+		if (!userGroupIds.some((id) => user.userGroupIds.includes(id))) return {
+			ok: false,
+			reason: "forbidden",
+			requiredGroupIds: userGroupIds
+		};
+	}
+	return { ok: true };
+}
+function throwIfDenied(result) {
+	if (result.ok) return;
+	throw new VisibilityError(result.reason, result.reason === "forbidden" ? result.requiredGroupIds : void 0);
+}
+function defineVisibility(rule) {
+	function check(context) {
+		return runCheck(rule, context);
+	}
+	function isAuthorized(context) {
+		return runCheck(rule, context).ok;
+	}
+	function assert(context) {
+		throwIfDenied(runCheck(rule, context));
+	}
+	function guard(_overrides) {
+		return ({ context }) => {
+			throwIfDenied(runCheck(rule, context));
+		};
+	}
+	return {
+		check,
+		isAuthorized,
+		assert,
+		guard
+	};
+}
+function isVisibilityError(error) {
+	return error instanceof VisibilityError;
+}
+function isUnauthenticatedError(error) {
+	return error instanceof VisibilityError && error.reason === "unauthenticated";
+}
+function isForbiddenError(error) {
+	return error instanceof VisibilityError && error.reason === "forbidden";
+}
+function isAlreadySignedInError(error) {
+	return error instanceof VisibilityError && error.reason === "alreadySignedIn";
+}
+
+//#endregion
+export { VisibilityError, defineVisibility, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, isVisibilityError };

package/dist/tanstack.d.ts

@@ -0,0 +1,18 @@
+import { l as SoftrSDK } from "./types-BLLUI6MI.js";
+
+//#region src/tanstack.d.ts
+
+/**
+ * TanStack Start middleware. Injects a per-request Softr SDK instance with
+ * cookies forwarded automatically. The base URL is read from VITE_SOFTR_BASE_URL.
+ *
+ * @example
+ * import { withSDK } from '@softr/sdk/tanstack'
+ *
+ * export const getProjects = createServerFn()
+ *   .middleware([withSDK])
+ *   .handler(({ context }) => context.sdk.datasource('ds_projects').list())
+ */
+declare const withSDK: any;
+//#endregion
+export { type SoftrSDK, withSDK };

package/dist/tanstack.js

@@ -0,0 +1,148 @@
+import { createMiddleware } from "@tanstack/start";
+
+//#region src/core/datasource.ts
+var DatasourceAPIImpl = class {
+	id;
+	fetch;
+	constructor(id, fetch$1) {
+		this.id = id;
+		this.fetch = fetch$1;
+	}
+	async list(options) {
+		const params = new URLSearchParams();
+		if (options?.page != null) params.set("page", String(options.page));
+		if (options?.limit != null) params.set("limit", String(options.limit));
+		if (options?.filters?.length) params.set("filters", JSON.stringify(options.filters));
+		if (options?.sort?.length) params.set("sort", JSON.stringify(options.sort));
+		const query = params.toString() ? `?${params}` : "";
+		const res = await this.fetch(`/api/datasources/${this.id}/records${query}`);
+		if (!res.ok) throw new Error(`Softr datasource list failed: ${res.status}`);
+		return res.json();
+	}
+	async get(recordId) {
+		const res = await this.fetch(`/api/datasources/${this.id}/records/${recordId}`);
+		if (!res.ok) throw new Error(`Softr datasource get failed: ${res.status}`);
+		return res.json();
+	}
+	async create(data) {
+		const res = await this.fetch(`/api/datasources/${this.id}/records`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(data)
+		});
+		if (!res.ok) throw new Error(`Softr datasource create failed: ${res.status}`);
+		return res.json();
+	}
+	async update(recordId, data) {
+		const res = await this.fetch(`/api/datasources/${this.id}/records/${recordId}`, {
+			method: "PATCH",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(data)
+		});
+		if (!res.ok) throw new Error(`Softr datasource update failed: ${res.status}`);
+		return res.json();
+	}
+	async delete(recordId) {
+		const res = await this.fetch(`/api/datasources/${this.id}/records/${recordId}`, { method: "DELETE" });
+		if (!res.ok) throw new Error(`Softr datasource delete failed: ${res.status}`);
+	}
+};
+
+//#endregion
+//#region src/core/workflow.ts
+var WorkflowAPIImpl = class {
+	id;
+	fetch;
+	constructor(id, fetch$1) {
+		this.id = id;
+		this.fetch = fetch$1;
+	}
+	async trigger(payload) {
+		const res = await this.fetch(`/api/workflows/${this.id}/trigger`, {
+			method: "POST",
+			...payload ? {
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(payload)
+			} : {}
+		});
+		if (!res.ok) throw new Error(`Softr workflow trigger failed: ${res.status}`);
+	}
+};
+
+//#endregion
+//#region src/core/sdk.ts
+var SoftrSDKImpl = class {
+	baseUrl;
+	extraHeaders;
+	cachedMe = null;
+	constructor(config) {
+		this.baseUrl = config.baseUrl.replace(/\/$/, "");
+		this.extraHeaders = config.headers;
+	}
+	async me() {
+		if (this.cachedMe) return this.cachedMe;
+		const res = await this._fetch("/me");
+		if (!res.ok) throw new Error(`Softr /me failed: ${res.status}`);
+		this.cachedMe = await res.json();
+		return this.cachedMe;
+	}
+	auth = {
+		login: async ({ email, password }) => {
+			const res = await this._fetch("/auth/login", {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({
+					email,
+					password
+				})
+			});
+			if (!res.ok) throw new Error(`Login failed: ${res.status}`);
+			this.cachedMe = null;
+		},
+		logout: async () => {
+			const res = await this._fetch("/auth/logout", { method: "POST" });
+			if (!res.ok) throw new Error(`Logout failed: ${res.status}`);
+			this.cachedMe = null;
+		}
+	};
+	datasource(id) {
+		return new DatasourceAPIImpl(id, this._fetch.bind(this));
+	}
+	workflow(id) {
+		return new WorkflowAPIImpl(id, this._fetch.bind(this));
+	}
+	_fetch(path, init) {
+		const headers = new Headers(this.extraHeaders);
+		if (init?.headers) new Headers(init.headers).forEach((v, k) => headers.set(k, v));
+		const isServer = typeof window === "undefined";
+		return fetch(`${this.baseUrl}${path}`, {
+			...init,
+			credentials: isServer ? "omit" : "include",
+			headers
+		});
+	}
+};
+function createSoftrSDKFromRequest(request, baseUrl) {
+	return new SoftrSDKImpl({
+		baseUrl,
+		headers: { cookie: request.headers.get("cookie") ?? "" }
+	});
+}
+
+//#endregion
+//#region src/tanstack.ts
+/**
+* TanStack Start middleware. Injects a per-request Softr SDK instance with
+* cookies forwarded automatically. The base URL is read from VITE_SOFTR_BASE_URL.
+*
+* @example
+* import { withSDK } from '@softr/sdk/tanstack'
+*
+* export const getProjects = createServerFn()
+*   .middleware([withSDK])
+*   .handler(({ context }) => context.sdk.datasource('ds_projects').list())
+*/
+const withSDK = createMiddleware().server(({ next, request }) => next({ context: { sdk: createSoftrSDKFromRequest(request, import.meta.env.VITE_SOFTR_BASE_URL) } }));
+
+//#endregion
+export { withSDK };

package/dist/types-BLLUI6MI.d.ts

@@ -0,0 +1,75 @@
+//#region src/types.d.ts
+interface SoftrUser {
+  id: string;
+  email: string;
+  name: string;
+  userGroupIds: Array<SoftrUserGroupId>;
+}
+interface DatasourcePermissions {
+  read: boolean;
+  create: boolean;
+  update: boolean;
+  delete: boolean;
+}
+interface SoftrPermissions {
+  datasources: Record<string, DatasourcePermissions>;
+  workflows: Record<string, boolean>;
+}
+interface SoftrMe {
+  user: SoftrUser | null;
+  permissions: SoftrPermissions;
+}
+interface ListOptions {
+  page?: number;
+  limit?: number;
+  filters?: Array<{
+    field: string;
+    operator: string;
+    value: unknown;
+  }>;
+  sort?: Array<{
+    field: string;
+    direction: 'asc' | 'desc';
+  }>;
+}
+interface ListResult<T = SoftrRecord> {
+  records: T[];
+  total: number;
+  page: number;
+  limit: number;
+}
+interface SoftrRecord {
+  id: string;
+  [field: string]: unknown;
+}
+interface DatasourceAPI {
+  list(options?: ListOptions): Promise<ListResult>;
+  get(recordId: string): Promise<SoftrRecord>;
+  create(data: Record<string, unknown>): Promise<SoftrRecord>;
+  update(recordId: string, data: Record<string, unknown>): Promise<SoftrRecord>;
+  delete(recordId: string): Promise<void>;
+}
+interface WorkflowAPI {
+  trigger(payload?: Record<string, unknown>): Promise<void>;
+}
+interface AuthAPI {
+  /** Sign in with email and password. Clears the cached me() result. */
+  login(credentials: {
+    email: string;
+    password: string;
+  }): Promise<void>;
+  /** Sign out the current user. Clears the cached me() result. */
+  logout(): Promise<void>;
+}
+interface SoftrSDK {
+  /**
+   * Fetch the current user and their permissions from /me.
+   * Cached for the lifetime of the instance — create a new instance per request on the server.
+   */
+  me(): Promise<SoftrMe>;
+  auth: AuthAPI;
+  datasource(id: string): DatasourceAPI;
+  workflow(id: string): WorkflowAPI;
+}
+//#endregion
+export { ListResult as a, SoftrRecord as c, WorkflowAPI as d, ListOptions as i, SoftrSDK as l, DatasourceAPI as n, SoftrMe as o, DatasourcePermissions as r, SoftrPermissions as s, AuthAPI as t, SoftrUser as u };

package/dist/vite.d.ts

@@ -0,0 +1,31 @@
+import "@tanstack/router-generator";
+import { Plugin } from "vite";
+
+//#region src/routes/discover.d.ts
+
+type VisibilityValue = string | Array<VisibilityValue> | {
+  [key: string]: VisibilityValue;
+};
+//#endregion
+//#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
+//#region src/vite.d.ts
+declare const MANIFEST_RELATIVE_PATH: string;
+/** Writes `<root>/dist/routes.json` and returns its path. Throws on a rule it cannot read. */
+declare function generateManifest(root: string): Promise<string>;
+/** Plugin order does not matter: this puts nothing into the module graph. */
+declare function softr(): Plugin;
+//#endregion
+export { MANIFEST_RELATIVE_PATH, type Manifest, type ManifestNode, generateManifest, softr };

package/dist/vite.js

@@ -0,0 +1,449 @@
+import * as nodeFs from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { Generator, getConfig, inferFullPath } from "@tanstack/router-generator";
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+import { parse } from "@babel/parser";
+import babelTraverse from "@babel/traverse";
+
+//#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
+//#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
+//#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$1 = (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$1(`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$1(`"${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$1(`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$1(`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$1(`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
+//#region src/vite.ts
+const MANIFEST_RELATIVE_PATH = path.join("dist", "routes.json");
+async function renderManifest(root) {
+	try {
+		return await generateRoutesManifest(root);
+	} catch (error) {
+		if (error instanceof ManifestError) {
+			const { filePath, line, column, message } = error.detail;
+			throw new Error(`[softr] ${filePath}:${line}:${column} — ${message}`, { cause: error });
+		}
+		throw error;
+	}
+}
+async function writeManifest(root, contents) {
+	const target = path.resolve(root, MANIFEST_RELATIVE_PATH);
+	await mkdir(path.dirname(target), { recursive: true });
+	await writeFile(target, contents, "utf8");
+	return target;
+}
+/** Writes `<root>/dist/routes.json` and returns its path. Throws on a rule it cannot read. */
+async function generateManifest(root) {
+	return writeManifest(root, await renderManifest(root));
+}
+/** Plugin order does not matter: this puts nothing into the module graph. */
+function softr() {
+	let root = process.cwd();
+	let rendered = null;
+	return {
+		name: "softr",
+		apply: "build",
+		configResolved(config) {
+			root = config.root;
+		},
+		async closeBundle() {
+			rendered ??= renderManifest(root);
+			await writeManifest(root, await rendered);
+		}
+	};
+}
+
+//#endregion
+export { MANIFEST_RELATIVE_PATH, generateManifest, softr };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@softr/sdk",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./vite": { "types": "./dist/vite.d.ts", "import": "./dist/vite.js" },
+    "./tanstack": { "types": "./dist/tanstack.d.ts", "import": "./dist/tanstack.js" }
+  },
+  "files": ["dist"],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsdown",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.28.0",
+    "@babel/traverse": "^7.28.0",
+    "@babel/types": "^7.28.0",
+    "@tanstack/router-generator": "1.167.23"
+  },
+  "devDependencies": {
+    "@types/babel__traverse": "^7.28.0",
+    "@types/node": "^24.3.0",
+    "tsdown": "^0.15.0",
+    "typescript": "^5.9.2",
+    "vite": "^8.0.0"
+  },
+  "peerDependencies": {
+    "@tanstack/start": ">=1",
+    "vite": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/start": { "optional": true },
+    "vite": { "optional": true }
+  }
+}