@softr/sdk 0.0.23 → 0.0.25

package/skills/softr-sdk/data-mutations/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.23
+  library_version: 0.0.25
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `q` and every type come from `@softr/sdk` and can be imported anywhere. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -118,7 +118,7 @@ Stamping a record with who created it, or scoping an update to the person making
 
 **A datasource id built from a name.** `'ds_projects'`, the table id, or the table's name glued to a uuid are not datasource ids. The id is the opaque UUID assigned when the table was registered on the application; copy it from there. Anything else fails at request time as not found or forbidden.
 
-**A datasource id stored in a variable.** The build reads ids statically to build the route manifest; it cannot resolve a name. Pass the UUID as a string literal directly at the call site. The lint rule `@softr/ds-no-computed-id` catches this at development time.
+**A datasource id stored in a variable.** Pass the UUID as a string literal directly at the call site. The lint rule `@softr/ds-no-computed-id` catches this at development time.
 
 **A write that sends `fields`.** The option is `data`. Only typecheck catches this, so it survives any run that does not typecheck.
 

package/skills/softr-sdk/reading-records/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.23
+  library_version: 0.0.25
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `q` and every type come from `@softr/sdk` and can be imported anywhere. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -29,13 +29,13 @@ import { q } from '@softr/sdk'
 
 Every `ds` call names its datasource by an opaque UUID from the table's registration on the application (Softr Studio's Data tab, or the `register_application_data_source` tool when an agent does it). It is not the table id, and it is never derived from the table's name — `'ds_posts'` or a name glued to a uuid fails at request time as not found or forbidden.
 
-**The datasource id must be a string literal at the call site.** Do not assign it to a variable and pass the variable — the build reads ids statically and cannot resolve a name. Write the UUID directly as the first argument:
+**The datasource id must be a string literal at the call site.** Do not assign it to a variable and pass the variable. Write the UUID directly as the first argument:
 
 ```ts
 // correct
 ds.list('8ffb4814-b028-4496-b679-7face2167ebc', { ... })
 
-// wrong — the build cannot read this
+// wrong
 const POSTS = '8ffb4814-b028-4496-b679-7face2167ebc'
 ds.list(POSTS, { ... })
 ```

package/skills/softr-sdk/routes-and-visibility/SKILL.md

@@ -7,19 +7,19 @@ description: >-
   per-reason overrides, the redirect and throw strategies, rendering an access
   error with isAccessError, isUnauthenticatedError, isForbiddenError and
   isAlreadySignedInError, guarding a layout, and the lint rule that requires a
-  declaration alongside the build rules that reject a duplicate, computed or
+  declaration alongside the rules that reject a duplicate, computed or
   root-level one.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.23
+  library_version: 0.0.25
 ---
 
 **Boundary.** `defineVisibility`, the error predicates and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
 
 # Route visibility
 
-Every route file in a Softr app declares who may see it. The build reads that declaration out of the source text without executing it and publishes it to Softr Studio, which shows the app owner every route and its audience. That is why the rules below are strict: a rule the build cannot read is a rule Studio cannot show.
+Every route file in a Softr app declares who may see it. Softr reads that declaration out of the source text without executing it and publishes it to Softr Studio, which shows the app owner every route and its audience. That is why the rules below are strict: a rule Softr cannot read is a rule Studio cannot show.
 
 ## Setup
 
@@ -43,11 +43,11 @@ function Billing() {
 
 One `defineVisibility` call per file, at module scope, with an inline object literal as its argument.
 
-Three rules about that shape, because the build reads the file rather than running it:
+Three rules about that shape, because Softr reads the file rather than running it:
 
 - The call must initialise a top-level `const`.
 - The import must be a direct named import from `@softr/sdk`.
-- Never declare on `__root.tsx`. The root cannot carry an audience, so the build rejects a declaration there rather than shipping an app that only looks gated. Put the rule on a layout below the root instead.
+- Never declare on `__root.tsx`. The root cannot carry an audience, so a declaration there would gate nothing while looking like it does. Softr rejects it. Put the rule on a layout below the root instead.
 
 The four rules:
 

package/dist/preview-identity/preview-identity.js

@@ -1,121 +0,0 @@
-import { makeSessionClearingCookies, makeSessionTokenCookie, sessionTokenCookieName } from "../auth/session.js";
-
-//#region src/preview-identity/preview-identity.ts
-const PREVIEW_REDEMPTION_PATH = "/__preview/identity";
-const PREVIEW_SIGNED_IN_PATH = "/__preview/signed-in";
-/** The grant in the URL is the only credential: studio-api authorized the builder before issuing it. */
-const redeemGrant = async (req, res) => {
-	res.setHeader("Cache-Control", "no-store");
-	res.setHeader("Referrer-Policy", "no-referrer");
-	if (req.method !== "GET") {
-		sendJson(res, 405, { error: `${PREVIEW_REDEMPTION_PATH} only supports GET` });
-		return;
-	}
-	const grant = searchParamsOf(req).get("grant");
-	if (!grant) {
-		sendJson(res, 400, { error: "no grant" });
-		return;
-	}
-	const landing = landingPath(searchParamsOf(req).get("next"));
-	let session;
-	try {
-		session = await redeemPreviewGrant(req, grant);
-	} catch (error) {
-		sendJson(res, statusOf(error), { error: messageOf(error) });
-		return;
-	}
-	const secure = requestIsHttps(req);
-	res.statusCode = 302;
-	res.setHeader("Location", landing);
-	res.setHeader("Set-Cookie", session.anonymous ? makeSessionClearingCookies(secure) : makeSessionTokenCookie(session.jwt, secure));
-	res.end();
-};
-/** Presence only, never decoded: decoding would put an app user's identity on a route Studio reads. */
-const reportSignedIn = (req, res) => {
-	res.setHeader("Cache-Control", "no-store");
-	if (req.method !== "GET") {
-		sendJson(res, 405, { error: `${PREVIEW_SIGNED_IN_PATH} only supports GET` });
-		return;
-	}
-	sendJson(res, 200, { signedIn: hasSessionCookie(req.headers.cookie, sessionTokenCookieName(requestIsHttps(req))) });
-};
-var RedemptionError = class extends Error {
-	status;
-	constructor(status, message) {
-		super(message);
-		this.status = status;
-	}
-};
-function statusOf(error) {
-	return error instanceof RedemptionError ? error.status : 503;
-}
-function messageOf(error) {
-	return error instanceof Error ? error.message : String(error);
-}
-async function redeemPreviewGrant(req, grant) {
-	const applicationId = process.env.SOFTR_APPLICATION_ID;
-	const studioApiUrl = process.env.SOFTR_STUDIO_API_URL?.trim() || studioApiUrlFor(req);
-	if (!applicationId || !studioApiUrl) throw new RedemptionError(503, "studio-api is unavailable");
-	let response;
-	try {
-		response = await fetch(`${studioApiUrl}/v1/applications/${encodeURIComponent(applicationId)}/vibe-coding/preview-identity/redeem`, {
-			method: "POST",
-			headers: { "content-type": "application/json" },
-			body: JSON.stringify({ grant })
-		});
-	} catch {
-		throw new RedemptionError(503, "studio-api is unreachable");
-	}
-	if (!response.ok) throw new RedemptionError(response.status, "studio-api refused the preview identity grant");
-	const body = await response.json().catch(() => null);
-	if (typeof body !== "object" || body === null) throw new RedemptionError(503, "studio-api returned no session");
-	const { anonymous, jwt } = body;
-	if (anonymous === true) return { anonymous: true };
-	if (typeof jwt !== "string" || jwt.length === 0) throw new RedemptionError(503, "studio-api returned no token");
-	return {
-		anonymous: false,
-		jwt
-	};
-}
-const STAGING_HOST_PATTERN = /(?:^|\.)staging(\d+)\.softr\.io$/;
-/** The host is the only per-environment signal the app has. Anything but a staging one gives null. */
-function studioApiUrlFor(req) {
-	const forwarded = req.headers["x-forwarded-host"];
-	const name = ((Array.isArray(forwarded) ? forwarded[0] : forwarded) ?? req.headers.host ?? "").split(",")[0].trim().split(":")[0];
-	const digits = STAGING_HOST_PATTERN.exec(name)?.[1];
-	if (!digits) return null;
-	return `https://studio-api-staging${digits.padStart(2, "0")}.softr.io`;
-}
-function hasSessionCookie(header, name) {
-	if (!header) return false;
-	return header.split(";").some((pair) => {
-		const separator = pair.indexOf("=");
-		return separator !== -1 && pair.slice(0, separator).trim() === name;
-	});
-}
-/**
-* Exactly as strict as h3's `getRequestProtocol`, which reads the cookie back. Being more generous
-* writes `__Host-session_token` where the app looks up `session_token`, and the visitor is silently
-* anonymous with no error on either side.
-*/
-function requestIsHttps(req) {
-	const forwarded = req.headers["x-forwarded-proto"];
-	if (forwarded === "https") return true;
-	if (forwarded === "http") return false;
-	return Boolean(req.socket?.encrypted);
-}
-function landingPath(next) {
-	if (!next || !next.startsWith("/") || next.startsWith("//") || next.includes("\\") || next.includes("://") || /[\u0000-\u001f\u007f]/.test(next)) return "/";
-	return next;
-}
-function searchParamsOf(req) {
-	return new URL(req.url ?? "", "http://request.invalid").searchParams;
-}
-function sendJson(res, status, body) {
-	res.statusCode = status;
-	res.setHeader("Content-Type", "application/json");
-	res.end(JSON.stringify(body));
-}
-
-//#endregion
-export { PREVIEW_REDEMPTION_PATH, PREVIEW_SIGNED_IN_PATH, redeemGrant, reportSignedIn };

package/dist/routes/discover.d.ts

@@ -1,14 +0,0 @@
-import "@tanstack/router-generator";
-
-//#region src/routes/discover.d.ts
-
-type DatasourceMethod = "list" | "get" | "create" | "update" | "delete" | "metric" | "chartData";
-type DatasourceAccess = {
-  id: string;
-  methods: Array<DatasourceMethod>;
-};
-type VisibilityValue = string | Array<VisibilityValue> | {
-  [key: string]: VisibilityValue;
-};
-//#endregion
-export { DatasourceAccess, VisibilityValue };

package/dist/routes/discover.js

@@ -1,305 +0,0 @@
-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
-		}
-	};
-}
-/** Reads all ds.method() calls from the source text. The route file is never executed. */
-function extractDatasources(source, filePath) {
-	let program;
-	try {
-		program = parse(source, {
-			sourceType: "module",
-			plugins: ["typescript", "jsx"]
-		});
-	} catch (error) {
-		const position = error.loc;
-		return {
-			ok: false,
-			error: {
-				code: "unparsable",
-				message: `could not parse ${filePath}: ${error.message}`,
-				filePath,
-				line: position?.line ?? 1,
-				column: position?.column ?? 0
-			}
-		};
-	}
-	const raw = findDatasourceCalls(program, filePath);
-	if (!raw.ok) return raw;
-	const byId = /* @__PURE__ */ new Map();
-	for (const { id, method } of raw.calls) {
-		if (!byId.has(id)) byId.set(id, /* @__PURE__ */ new Set());
-		byId.get(id).add(method);
-	}
-	return {
-		ok: true,
-		datasources: Array.from(byId.entries()).map(([id, methods]) => ({
-			id,
-			methods: [...methods]
-		}))
-	};
-}
-/**
-* 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 SDK_SERVER_PACKAGE_NAME = "@softr/sdk/server";
-const VISIBILITY_FUNCTION = "defineVisibility";
-const DS_BINDING = "ds";
-const DS_METHODS = new Set([
-	"list",
-	"get",
-	"create",
-	"update",
-	"delete",
-	"metric",
-	"chartData"
-]);
-function fail(code, message, filePath, line, column) {
-	return {
-		ok: false,
-		error: {
-			code,
-			message,
-			filePath,
-			line,
-			column
-		}
-	};
-}
-function findDatasourceCalls(ast, filePath) {
-	const calls = [];
-	let error = null;
-	traverse(ast, { CallExpression(path$1) {
-		const { node } = path$1;
-		const { callee } = node;
-		if (callee.type !== "MemberExpression") return;
-		if (callee.computed) return;
-		if (callee.object.type !== "Identifier") return;
-		if (callee.property.type !== "Identifier") return;
-		const method = callee.property.name;
-		if (!DS_METHODS.has(method)) return;
-		if (!isDsImport(path$1, callee.object.name)) return;
-		const firstArg = node.arguments[0];
-		if (firstArg === void 0 || firstArg.type === "SpreadElement") {
-			error = {
-				code: "not-literal",
-				message: `${filePath}: ds.${method}() must be called with a string literal datasource id`,
-				filePath,
-				line: node.loc?.start.line ?? 1,
-				column: node.loc?.start.column ?? 0
-			};
-			path$1.stop();
-			return;
-		}
-		if (firstArg.type !== "StringLiteral") {
-			error = {
-				code: "not-literal",
-				message: `${filePath}: the datasource id passed to ds.${method}() must be a string literal`,
-				filePath,
-				line: firstArg.loc?.start.line ?? 1,
-				column: firstArg.loc?.start.column ?? 0
-			};
-			path$1.stop();
-			return;
-		}
-		calls.push({
-			id: firstArg.value,
-			method
-		});
-	} });
-	if (error !== null) return {
-		ok: false,
-		error
-	};
-	return {
-		ok: true,
-		calls
-	};
-}
-function isDsImport(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_SERVER_PACKAGE_NAME) return false;
-	return (specifier.imported.type === "Identifier" ? specifier.imported.name : specifier.imported.value) === DS_BINDING;
-}
-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, extractDatasources, extractVisibility };

package/dist/routes/manifest.d.ts

@@ -1,24 +0,0 @@
-import { DatasourceAccess, VisibilityValue } from "./discover.js";
-
-//#region src/routes/manifest.d.ts
-type DatasourceEntry = DatasourceAccess & {
-  /** Project-relative path to the file where the datasource is accessed. */
-  filename: string;
-  /** Route path, if the file is a route file. */
-  route?: string;
-};
-type ManifestNode = {
-  routePath: string;
-  filePath: string;
-  _fsRouteType?: string;
-  inferFullPath: string | null;
-  createFileRouteProps: Array<string>;
-  visibility: VisibilityValue | null;
-  children: Array<ManifestNode>;
-};
-type Manifest = {
-  root: ManifestNode;
-  datasources: Array<DatasourceEntry>;
-};
-//#endregion
-export { Manifest, ManifestNode };