@affordances/next 0.0.0-stage → 0.0.0

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @affordances/next
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Affordances for Next.js: `withAffordances` for `next.config.ts`, codegen that finds each route's `actions.ts` and `state.ts`, the route handler, and the `affordances` CLI.
+
+```bash
+vlt install @affordances/next @affordances/react zod
+vlx @affordances/cli init
+```
+
+`init` writes `app/api/affordances/graph/[[...path]]/route.ts`, wraps your config, and generates `.affordances/manifest.ts`. Then describe a page next to it:
+
+```ts
+// app/guestbook/actions.ts
+'use server'
+
+import { z } from 'zod'
+import { defineAction } from '@affordances/next'
+import guestbook from './state'
+
+export const sign = defineAction({
+  name: 'sign',
+  description: 'Add a message to the guestbook',
+  input: z.object({ name: z.string().min(1), message: z.string().max(280) }),
+  state: guestbook,
+  expose: 'public',
+  effects: ['entries'],
+  run: (input) => entries.add(input),
+})
+```
+
+`curl -H 'Accept: application/vnd.affordances+json' localhost:3000/guestbook` returns the page's graph, and a POST with `Content-Type: application/vnd.affordances+json` calls `sign`.
+
+Docs: [https://github.com/vltpkg/affordances/blob/main/apps/docs/content/quickstart.mdx](https://github.com/vltpkg/affordances/blob/main/apps/docs/content/quickstart.mdx) and [https://github.com/vltpkg/affordances/blob/main/apps/docs/content/guides/nextjs/index.mdx](https://github.com/vltpkg/affordances/blob/main/apps/docs/content/guides/nextjs/index.mdx)

package/dist/codegen.d.ts

@@ -0,0 +1,22 @@
+export type RouteEntry = {
+  route: string;
+  state?: string;
+  actions?: {
+    file: string;
+    exports: {
+      local: string;
+      name: string;
+    }[];
+  };
+};
+export declare class CodegenError extends Error {
+  name: string;
+}
+export declare const findAppDir: (root: string) => string;
+export declare const scan: (root: string) => RouteEntry[];
+export declare const render: (entries: RouteEntry[], options?: {
+  name?: string;
+}) => string;
+export declare const generate: (root: string, options?: {
+  name?: string;
+}) => RouteEntry[];

package/dist/codegen.js

@@ -0,0 +1,115 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parseSync } from "oxc-parser";
+// src/codegen.ts
+var CodegenError = class extends Error {
+	name = "AffordancesCodegenError";
+};
+const sources = [
+	".ts",
+	".tsx",
+	".js",
+	".jsx"
+];
+const findAppDir = (root) => {
+	for (const dir of ["app", "src/app"]) if (existsSync(path.join(root, dir))) return path.join(root, dir);
+	throw new CodegenError(`No app directory in ${root}`);
+};
+const toRoute = (segments) => `/${segments.filter((s) => !/^\(.*\)$/.test(s) && !s.startsWith("@")).join("/")}`;
+const findFile = (dir, base) => sources.map((ext) => path.join(dir, base + ext)).find((file) => existsSync(file));
+const parseActions = (file, source) => {
+	const { program, errors } = parseSync(file, source);
+	if (errors.length) throw new CodegenError(`${file}: ${errors[0].message}`);
+	const body = program.body;
+	if (!body.some((node) => node.type === "ExpressionStatement" && node.directive === "use server")) throw new CodegenError(`${file}: actions files must start with 'use server'`);
+	const found = [];
+	for (const node of body) {
+		if (node.type !== "ExportNamedDeclaration") continue;
+		const declaration = node.declaration;
+		if (declaration?.type !== "VariableDeclaration") continue;
+		for (const declarator of declaration.declarations) {
+			const init = declarator.init;
+			if (init?.type !== "CallExpression") continue;
+			const callee = init.callee;
+			if ((callee.type === "Identifier" ? callee.name : callee.property?.name) !== "defineAction") continue;
+			const local = declarator.id.name;
+			const config = init.arguments[0];
+			const value = (config?.type === "ObjectExpression" ? config.properties.find((p) => p.type === "Property" && p.key.name === "name") : void 0)?.value;
+			if (value?.type !== "Literal" || typeof value.value !== "string") throw new CodegenError(`${file}: ${local} needs a string literal \`name\``);
+			found.push({
+				local,
+				name: value.value
+			});
+		}
+	}
+	return found;
+};
+const scan = (root) => {
+	const appDir = findAppDir(root);
+	const entries = [];
+	const relative = (file) => path.relative(root, file).replace(/\.[jt]sx?$/, "");
+	const walk = (dir, segments) => {
+		const stateFile = findFile(dir, "state");
+		const actionsFile = findFile(dir, "actions");
+		if (stateFile || actionsFile) {
+			const entry = { route: toRoute(segments) };
+			if (stateFile) {
+				const { program } = parseSync(stateFile, readFileSync(stateFile, "utf8"));
+				if (!program.body.some((node) => node.type === "ExportDefaultDeclaration")) throw new CodegenError(`${stateFile}: state files must \`export default defineState(…)\``);
+				entry.state = relative(stateFile);
+			}
+			if (actionsFile) {
+				const exports = parseActions(actionsFile, readFileSync(actionsFile, "utf8"));
+				const seen = /* @__PURE__ */ new Set();
+				for (const { name } of exports) {
+					if (seen.has(name)) throw new CodegenError(`${actionsFile}: two actions are named ${name} on ${entry.route}`);
+					seen.add(name);
+				}
+				entry.actions = {
+					file: relative(actionsFile),
+					exports
+				};
+			}
+			entries.push(entry);
+		}
+		for (const child of readdirSync(dir, { withFileTypes: true })) {
+			if (!child.isDirectory() || child.name.startsWith("_") || child.name === "node_modules") continue;
+			walk(path.join(dir, child.name), [...segments, child.name]);
+		}
+	};
+	walk(appDir, []);
+	return entries.toSorted((a, b) => a.route.localeCompare(b.route));
+};
+const render = (entries, options = {}) => {
+	const imports = [];
+	const routes = entries.map((entry, i) => {
+		const parts = [];
+		if (entry.state) {
+			imports.push(`import state${i} from '../${entry.state}'`);
+			parts.push(`state: state${i}`);
+		}
+		const names = entry.actions?.exports.map((e) => e.local) ?? [];
+		if (names.length) imports.push(`import { ${names.join(", ")} } from '../${entry.actions.file}'`);
+		parts.push(`actions: [${names.join(", ")}]`);
+		return `    ${JSON.stringify(entry.route)}: { ${parts.join(", ")} },`;
+	});
+	return `// generated by @affordances/next from app/**/{actions,state}.ts; don't edit
+import type { Manifest } from '@affordances/next'
+${imports.join("\n")}
+
+export const manifest = {${options.name ? `\n  name: ${JSON.stringify(options.name)},` : ""}
+  routes: {
+${routes.join("\n")}
+  },
+} satisfies Manifest
+`;
+};
+const generate = (root, options = {}) => {
+	const entries = scan(root);
+	const out = path.join(root, ".affordances", "manifest.ts");
+	const code = render(entries, options);
+	mkdirSync(path.dirname(out), { recursive: true });
+	if (!existsSync(out) || readFileSync(out, "utf8") !== code) writeFileSync(out, code);
+	return entries;
+};
+export { CodegenError, findAppDir, generate, render, scan };

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+import { NextConfig } from "next";
+export declare const API_PATH = "/api/affordances/graph";
+export type Rewrite = {
+  source: string;
+  destination: string;
+  has?: {
+    type: 'header' | 'query';
+    key: string;
+    value?: string;
+  }[];
+};
+export type Rewrites = {
+  beforeFiles: Rewrite[];
+  afterFiles: Rewrite[];
+  fallback: Rewrite[];
+};
+export declare const rewrites: Rewrite[];
+export declare const toSource: (route: string) => string;
+export type AffordancesPlugin = <C extends Config>(config: C) => C;
+export type AffordancesConfig = {
+  name?: string;
+  root?: string;
+  plugins?: AffordancesPlugin[];
+};
+export type Config = Pick<NextConfig, 'rewrites' | 'headers' | 'turbopack'> & {
+  webpack?: ((config: any, context: any) => any) | null;
+};
+export declare const withAffordances: <C extends Config>(nextConfig?: C, options?: AffordancesConfig) => C;

package/dist/config.js

@@ -0,0 +1,95 @@
+import { findAppDir, generate } from "./codegen.js";
+import { t as API_PATH } from "./constants-BXXx4qVl.js";
+import { watch } from "node:fs";
+import path from "node:path";
+import { MEDIA_TYPE, WELL_KNOWN_PATH } from "@affordances/protocol";
+// src/config.ts
+const escaped = MEDIA_TYPE.replace(/[.+]/g, "\\$&");
+const page = "/:path((?!api/|_next/).+)";
+const conditions = [
+	[{
+		type: "header",
+		key: "accept",
+		value: `.*${escaped}.*`
+	}],
+	[{
+		type: "header",
+		key: "content-type",
+		value: `.*${escaped}.*`
+	}],
+	[{
+		type: "query",
+		key: "affordances"
+	}]
+];
+const rewrites = [{
+	source: WELL_KNOWN_PATH,
+	destination: `${API_PATH}${WELL_KNOWN_PATH}`
+}, ...conditions.flatMap((has) => [{
+	source: "/",
+	has,
+	destination: API_PATH
+}, {
+	source: page,
+	has,
+	destination: `${API_PATH}/:path`
+}])];
+const toSource = (route) => route.replace(/\[\[\.\.\.(\w+)\]\]/g, ":$1*").replace(/\[\.\.\.(\w+)\]/g, ":$1+").replace(/\[(\w+)\]/g, ":$1");
+const normalize = (value) => Array.isArray(value) ? {
+	beforeFiles: [],
+	afterFiles: value,
+	fallback: []
+} : {
+	beforeFiles: value?.beforeFiles ?? [],
+	afterFiles: value?.afterFiles ?? [],
+	fallback: value?.fallback ?? []
+};
+const withAffordances = (nextConfig = {}, options = {}) => {
+	const root = options.root ?? process.cwd();
+	const entries = generate(root, options);
+	if (process.env.NODE_ENV === "development") {
+		let timer;
+		watch(findAppDir(root), { recursive: true }, (_, file) => {
+			if (!file || !/(^|\/)(actions|state)\.[jt]sx?$/.test(file)) return;
+			clearTimeout(timer);
+			timer = setTimeout(() => {
+				try {
+					generate(root, options);
+				} catch (error) {
+					console.error(`[affordances] ${error.message}`);
+				}
+			}, 50);
+		}).unref();
+	}
+	const manifest = path.join(root, ".affordances", "manifest.ts");
+	const afforded = {
+		...nextConfig,
+		turbopack: {
+			...nextConfig.turbopack,
+			resolveAlias: {
+				...nextConfig.turbopack?.resolveAlias,
+				"@affordances/next/manifest": `./${path.relative(process.cwd(), manifest)}`
+			}
+		},
+		webpack: (config, context) => {
+			config.resolve.alias["@affordances/next/manifest"] = manifest;
+			return nextConfig.webpack ? nextConfig.webpack(config, context) : config;
+		},
+		rewrites: async () => {
+			const user = normalize(await nextConfig.rewrites?.());
+			return {
+				...user,
+				beforeFiles: [...rewrites, ...user.beforeFiles]
+			};
+		},
+		headers: async () => [...entries.map(({ route }) => ({
+			source: toSource(route),
+			headers: [{
+				key: "Link",
+				value: "<?affordances=1>; rel=\"affordances\""
+			}]
+		})), ...await nextConfig.headers?.() ?? []]
+	};
+	return (options.plugins ?? []).reduce((config, plugin) => plugin(config), afforded);
+};
+export { API_PATH, rewrites, toSource, withAffordances };

package/dist/constants-BXXx4qVl.js

@@ -0,0 +1,3 @@
+// src/constants.ts
+const API_PATH = "/api/affordances/graph";
+export { API_PATH as t };

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { AffordancesError, AffordancesOptions, Ctx, Manifest, redirect } from "@affordances/core";
+export declare const createAffordances: <Session = never>(options?: Pick<AffordancesOptions<Session>, 'auth'>) => {
+  defineAction: <Schema extends import("@standard-schema/spec").StandardSchemaV1, Output, State extends import("@affordances/core").Entities = import("@affordances/core").Entities>(config: import("@affordances/core").ActionConfig<Schema, Output, Session, State>) => import("@affordances/core").Action<import("@standard-schema/spec").StandardSchemaV1.InferInput<Schema>, Output>;
+  defineState: <State extends import("@affordances/core").Entities>(load: import("@affordances/core").StateLoader<State, Session>, extra?: {
+    nav?: ((state: State) => import("@affordances/protocol").NavItem[]) | undefined;
+    description?: string;
+  } | undefined) => import("@affordances/core").StateDef<State>;
+};
+export declare const defineAction: <Schema extends import("@standard-schema/spec").StandardSchemaV1, Output, State extends import("@affordances/core").Entities = import("@affordances/core").Entities>(config: import("@affordances/core").ActionConfig<Schema, Output, never, State>) => import("@affordances/core").Action<import("@standard-schema/spec").StandardSchemaV1.InferInput<Schema>, Output>, defineState: <State extends import("@affordances/core").Entities>(load: import("@affordances/core").StateLoader<State, never>, extra?: {
+  nav?: ((state: State) => import("@affordances/protocol").NavItem[]) | undefined;
+  description?: string;
+} | undefined) => import("@affordances/core").StateDef<State>;
+export { AffordancesError, type Ctx, type Manifest, redirect };

package/dist/index.js

@@ -0,0 +1,17 @@
+import { headers } from "next/headers";
+import { redirect as redirect$1 } from "next/navigation";
+import { AffordancesError, createAffordances as createAffordances$1, redirect } from "@affordances/core";
+// src/index.ts
+const request = async () => {
+	const list = await headers();
+	const host = list.get("x-forwarded-host") ?? list.get("host") ?? "localhost";
+	const proto = list.get("x-forwarded-proto") ?? "http";
+	return new Request(`${proto}://${host}/`, { headers: list });
+};
+const createAffordances = (options = {}) => createAffordances$1({
+	...options,
+	request,
+	redirect: redirect$1
+});
+const { defineAction, defineState } = createAffordances();
+export { AffordancesError, createAffordances, defineAction, defineState, redirect };

package/dist/manifest.d.ts

@@ -0,0 +1,2 @@
+import { Manifest } from "@affordances/core";
+export declare const manifest: Manifest | undefined;

package/dist/manifest.js

@@ -0,0 +1,3 @@
+// src/manifest.ts
+const manifest = void 0;
+export { manifest };

package/dist/route.d.ts

@@ -0,0 +1,7 @@
+import { HandlerOptions, Manifest } from "@affordances/core";
+export type RouteHandlerOptions = Omit<HandlerOptions, 'manifest' | 'basePath'> & {
+  manifest?: Manifest;
+};
+export declare const createRouteHandler: (options?: RouteHandlerOptions) => (request: Request) => Promise<Response>;
+export declare const GET: (request: Request) => Promise<Response>;
+export declare const POST: (request: Request) => Promise<Response>;

package/dist/route.js

@@ -0,0 +1,28 @@
+import { t as API_PATH } from "./constants-BXXx4qVl.js";
+import { createHandler } from "@affordances/core";
+// src/route.ts
+const redirectFrom = (error) => {
+	const digest = error?.digest;
+	if (typeof digest === "string" && digest.startsWith("NEXT_REDIRECT;")) return digest.split(";")[2];
+};
+const appManifest = async () => {
+	const { manifest } = await import("@affordances/next/manifest");
+	if (!manifest) throw new Error("No Affordances manifest: wrap next.config with withAffordances from @affordances/next/config");
+	return manifest;
+};
+const createRouteHandler = (options = {}) => {
+	const { manifest, ...rest } = options;
+	let handler;
+	return async (request) => {
+		handler ??= (manifest ? Promise.resolve(manifest) : appManifest()).then((m) => createHandler({
+			redirectFrom,
+			...rest,
+			manifest: m,
+			basePath: API_PATH
+		}));
+		return (await handler)(request);
+	};
+};
+const GET = createRouteHandler();
+const POST = GET;
+export { GET, POST, createRouteHandler };

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@affordances/next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "Affordances for Next.js: withAffordances, codegen, and the route handler",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vltpkg/affordances.git",
+    "directory": "packages/next"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./route": {
+      "types": "./dist/route.d.ts",
+      "default": "./dist/route.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./codegen": {
+      "types": "./dist/codegen.d.ts",
+      "default": "./dist/codegen.js"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@affordances/core": "0.0.0",
+    "@affordances/protocol": "0.0.0",
+    "oxc-parser": "^0.156.0"
+  },
+  "devDependencies": {
+    "next": "^16.4.3",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "zod": "^4.6.7"
+  },
+  "peerDependencies": {
+    "next": ">=16",
+    "react": ">=19"
+  }
+}