create-rsc-kit 0.18.0 → 0.19.0

package/dist/index.js

@@ -152,12 +152,19 @@ function write(o) {
         ['.gitignore', t.gitignore],
         ['README.md', t.readme(o)],
         ['AGENTS.md', t.agents(o)],
-        ['.mcp.json', t.mcp()],
+        ['.mcp.json', t.mcp(o)],
         ['src/app/layout.tsx', t.layout(o)],
         ['src/app/page.tsx', t.page(o)],
         ['src/components/Counter.tsx', t.counter(o)],
         ['tests/app.test.ts', t.smokeTest(o)],
     ];
+    // Bun's test runner reads the real server-only package, which throws on
+    // import; a preload stubs it so an action file that carries the line is
+    // still a function a test can call.
+    if (o.host !== 'node') {
+        files.push(['bunfig.toml', t.bunfig]);
+        files.push(['tests/preload.ts', t.testPreload]);
+    }
     if (o.tailwind)
         files.push(['src/app/styles.css', t.styles]);
     if (o.env) {

package/dist/init.js

@@ -182,6 +182,59 @@ function combine(name, theirs, ours) {
  * that quietly replaces a working build script loses someone's trust
  * permanently, and it only has to be wrong once.
  */
+/** Where this tool's section of an AGENTS.md begins and ends, so a second run finds it. */
+const AGENTS_START = '<!-- rsc-kit:start -->';
+const AGENTS_END = '<!-- rsc-kit:end -->';
+/**
+ * This tool's instructions, added to an existing AGENTS.md or written as one.
+ *
+ * Someone else's instructions are not a file to rewrite, but a delimited
+ * section at the end is not a rewrite: theirs stay exactly as written above
+ * it, the markers say what is ours, and a second run finds the markers and
+ * leaves it be. A project that already has an AGENTS.md is the project whose
+ * agents most need to hear how this works.
+ */
+function mergeAgents(dir, o) {
+    const path = join(dir, 'AGENTS.md');
+    if (!existsSync(path)) {
+        writeFileSync(path, t.agents(o));
+        return { kind: 'wrote', what: 'AGENTS.md' };
+    }
+    const existing = readFileSync(path, 'utf8');
+    if (existing.includes(AGENTS_START) || /rsc-kit/i.test(existing)) {
+        return { kind: 'skipped', what: 'AGENTS.md', detail: 'already covers rsc-kit' };
+    }
+    writeFileSync(path, existing.replace(/\s*$/, '\n\n') + `${AGENTS_START}\n${t.agents(o).trim()}\n${AGENTS_END}\n`);
+    return { kind: 'merged', what: 'AGENTS.md', detail: 'added a section at the end; yours is untouched above it' };
+}
+/**
+ * The rsc-kit server, added to an existing .mcp.json or written as a new one.
+ *
+ * The file is a map of servers under `mcpServers`; a project with other
+ * servers keeps them, and one that already lists rsc-kit is left alone. A
+ * file that does not parse is not one to rewrite.
+ */
+function mergeMcp(dir, o) {
+    const path = join(dir, '.mcp.json');
+    if (!existsSync(path)) {
+        writeFileSync(path, t.mcp(o));
+        return { kind: 'wrote', what: '.mcp.json' };
+    }
+    let existing;
+    try {
+        existing = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return { kind: 'skipped', what: '.mcp.json', detail: 'already exists and is not JSON; add the rsc-kit server by hand' };
+    }
+    if (existing.mcpServers?.['rsc-kit']) {
+        return { kind: 'skipped', what: '.mcp.json', detail: 'already lists rsc-kit' };
+    }
+    const ours = JSON.parse(t.mcp(o)).mcpServers['rsc-kit'];
+    existing.mcpServers = { ...(existing.mcpServers ?? {}), 'rsc-kit': ours };
+    writeFileSync(path, JSON.stringify(existing, null, 2) + '\n');
+    return { kind: 'merged', what: '.mcp.json', detail: 'added the rsc-kit server beside the others' };
+}
 function mergeScripts(o, found) {
     const pkg = found.packageJson;
     const scripts = pkg.scripts ?? {};
@@ -315,18 +368,17 @@ function manualPluginStep(o, existing) {
 function routes(o, dir) {
     const appDir = join(dir, o.sourceDir, 'app');
     const steps = [];
+    // The two files beside the tree are looked at whether or not the tree is
+    // here: a project that already has pages is the one whose agents and
+    // editor most need to know about this.
+    steps.push(mergeAgents(dir, o), mergeMcp(dir, o));
     if (existsSync(join(appDir, 'layout.tsx')) || existsSync(join(appDir, 'page.tsx'))) {
-        return [{ kind: 'skipped', what: `${o.sourceDir}/app`, detail: 'a route tree is already here' }];
+        return [...steps, { kind: 'skipped', what: `${o.sourceDir}/app`, detail: 'a route tree is already here' }];
     }
     const files = [
         [join(o.sourceDir, 'app/layout.tsx'), t.layout(o)],
         [join(o.sourceDir, 'app/page.tsx'), t.page(o)],
         [join(o.sourceDir, 'components/Counter.tsx'), t.counter(o)],
-        // Beside the route tree rather than merged into an existing AGENTS.md: a
-        // file of someone else's instructions is not one to append to blind, and
-        // the loop below skips it if it is already there.
-        ['AGENTS.md', t.agents(o)],
-        ['.mcp.json', t.mcp()],
     ];
     if (o.tailwind)
         files.push([join(o.sourceDir, 'app/styles.css'), t.styles]);
@@ -401,10 +453,10 @@ function tsconfig(o, found, dir) {
         writeFileSync(path, t.tsconfig(o));
         return [{ kind: 'wrote', what: 'tsconfig.json' }];
     }
-    // Reported, never rewritten. Adding the entry means parsing and reprinting
-    // the file, which loses the comments a tsconfig is allowed to have and the
-    // formatting someone chose — a worse trade than one line of output, for a
-    // file this does not own.
+    // Edited in place, never reprinted: parsing and printing the file would
+    // lose the comments a tsconfig is allowed to have and the formatting
+    // someone chose. The entry goes in as text, at the front of the include
+    // list that is there, or as a list of its own after the opening brace.
     const current = readFileSync(path, 'utf-8');
     // Comments are legal here and JSON.parse does not take them. Stripped
     // outside strings only: a glob like ".rsc-kit/**/*" holds "/*", and a
@@ -428,13 +480,25 @@ function tsconfig(o, found, dir) {
     // with a dot is outside it. So both cases need the entry, and a project with
     // no `include` needs `**\/*` written alongside it or it loses everything
     // else. Measured both ways.
+    const opened = /"include"\s*:\s*\[/.exec(current);
+    if (include && opened) {
+        const at = opened.index + opened[0].length;
+        const rest = current.slice(at);
+        // The list's own style: one entry per line, or all on one.
+        const separator = /^\s*\n/.test(rest) ? rest.match(/^\s*\n(\s*)/)[0] : ' ';
+        writeFileSync(path, current.slice(0, at) + `${separator}"${TYPES_GLOB}",` + (separator === ' ' ? ' ' : '') + rest.replace(/^\s*\n/, ''));
+        return [{ kind: 'merged', what: 'tsconfig.json', detail: `added "${TYPES_GLOB}" to "include"` }];
+    }
+    const brace = current.indexOf('{');
+    if (!include && brace !== -1) {
+        writeFileSync(path, current.slice(0, brace + 1) + `\n  "include": ["**/*", "${TYPES_GLOB}"],` + current.slice(brace + 1));
+        return [{ kind: 'merged', what: 'tsconfig.json', detail: `added "include": ["**/*", "${TYPES_GLOB}"]` }];
+    }
     return [
         {
             kind: 'manual',
             what: 'tsconfig.json',
-            detail: include
-                ? `add "${TYPES_GLOB}" to "include", or typed routes fall back to string`
-                : `add "include": ["**/*", "${TYPES_GLOB}"], or typed routes fall back to string`,
+            detail: `add "${TYPES_GLOB}" to "include", or typed routes fall back to string`,
         },
     ];
 }
@@ -483,7 +547,23 @@ function backend(o, found, dir) {
     const steps = [];
     const env = join(dir, '.env');
     if (existsSync(env)) {
-        steps.push({ kind: 'skipped', what: '.env', detail: 'already exists; RSC_BACKEND and RSC_HOST_CALL_SECRET must be in it' });
+        // The two lines, added to what is there. A secret already present is
+        // the one the backend was given and is never regenerated; a backend
+        // already named is left as named.
+        const current = readFileSync(env, 'utf8');
+        const missing = [];
+        if (!/^\s*RSC_BACKEND=/m.test(current))
+            missing.push(`RSC_BACKEND=${o.backend}`);
+        if (!/^\s*RSC_HOST_CALL_SECRET=/m.test(current)) {
+            missing.push(`RSC_HOST_CALL_SECRET=${randomBytes(32).toString('base64url')}`);
+        }
+        if (missing.length === 0) {
+            steps.push({ kind: 'skipped', what: '.env', detail: 'already has RSC_BACKEND and RSC_HOST_CALL_SECRET' });
+        }
+        else {
+            writeFileSync(env, current.replace(/\s*$/, '\n\n') + missing.join('\n') + '\n');
+            steps.push({ kind: 'merged', what: '.env', detail: `added ${missing.map((line) => line.split('=')[0]).join(' and ')}` });
+        }
     }
     else {
         writeFileSync(env, t.backendEnv(o.backend, randomBytes(32).toString('base64url')));
@@ -515,9 +595,10 @@ const DEFAULT_BACKEND = 'http://127.0.0.1:8080';
 const INIT_HELP = `
   rsc-kit init — add RSC to the project in this directory
 
-  Nothing existing is ever rewritten. New files are written, missing
-  dependencies are added, and for anything already there the exact edit is
-  printed for you to make.
+  Nothing existing is rewritten. New files are written; a file that is a list
+  gets our entry added to it - .mcp.json, AGENTS.md, tsconfig.json's include,
+  .env - with yours left as written; and for anything else already there the
+  exact edit is printed for you to make.
 
   Options
     --source-dir <dir>   where app/ should live (detected, usually src)

package/dist/templates.d.ts

@@ -66,6 +66,18 @@ export declare function layout(o: Options): string;
  * the app, and what gets chosen is a port, a spawned server, and a sleep. This
  * is the shape instead: the deployed handler, a Request in, a Response out.
  */
+/** Bun's test settings: the preload below, before every test file. */
+export declare const bunfig = "[test]\npreload = [\"./tests/preload.ts\"]\n";
+/**
+ * What every test file sees first.
+ *
+ * `import 'server-only'` is honoured by the build - a client file importing
+ * the module fails to build rather than shipping a secret - and resolves to
+ * nothing on the server. Under bun test it is the real package, which throws
+ * on import, so an action or a route that carries the line would not be a
+ * function a test can call. Stubbed here, once.
+ */
+export declare const testPreload = "import { mock } from 'bun:test'\n\n// The build honours this import and resolves it to nothing on the server;\n// the real package throws when imported, which is what a test would hit.\nmock.module('server-only', () => ({}))\nmock.module('client-only', () => ({}))\n";
 export declare function smokeTest(o: Options): string;
 export declare function page(o: Options): string;
 export declare function counter(o: Options): string;
@@ -112,7 +124,7 @@ export declare function agents(o: Options): string;
  * the server the first time an agent starts it. Other clients want the same
  * four lines in their own file.
  */
-export declare function mcp(): string;
+export declare function mcp(o?: Options): string;
 export declare function readme(o: Options): string;
 /**
  * Typed environment variables, read once at startup.

package/dist/templates.js

@@ -61,9 +61,16 @@ export function scripts(o) {
             start: 'bun .output/server/index.mjs',
         };
     }
+    // On Bun, Vite itself runs on Bun. `vite` is a bin with a node shebang, so
+    // `bun run dev` alone still started it under Node - and a project that
+    // imports `bun` or `bun:sqlite` failed at the first render with "Cannot
+    // find package 'bun'", in a scaffold that had just said it was a Bun app.
+    // `bun --bun` runs the bin on Bun's runtime; the dev server, the build and
+    // the prerender then see the same runtime the server will.
+    const vite = o.host === 'bun' ? 'bun --bun vite' : 'vite';
     return {
-        dev: 'vite',
-        build: 'vite build',
+        dev: vite,
+        build: `${vite} build`,
         // The two that produce something you ship build first, rather than reading
         // whatever .output happens to hold. Run on a project that has never been
         // built, they failed with `ENOENT opening root directory ".output/server"`
@@ -85,12 +92,17 @@ export function scripts(o) {
                 // every asset — the static path resolves into Bun's virtual
                 // filesystem, where the files on disk are not.
                 //
+                // compile.mjs rather than index.mjs: the build writes it beside the
+                // server, and it is what puts the frozen pages inside the binary -
+                // imported by name, which a compile embeds, where the server's own
+                // computed import is invisible to it.
+                //
                 // Into dist/, which is already ignored. Named after the project it
                 // landed a 63MB binary in the root of, next to the source, with
                 // nothing in .gitignore covering it.
                 ...(o.host === 'bun'
                     ? {
-                        compile: 'vite build && bun build --compile .output/server/index.mjs --outfile dist/app',
+                        compile: `${vite} build && bun build --compile .output/server/compile.mjs --outfile dist/app`,
                     }
                     : {}),
             }),
@@ -319,6 +331,26 @@ export default function RootLayout({ children }: { children: ReactNode }) {
  * the app, and what gets chosen is a port, a spawned server, and a sleep. This
  * is the shape instead: the deployed handler, a Request in, a Response out.
  */
+/** Bun's test settings: the preload below, before every test file. */
+export const bunfig = `[test]
+preload = ["./tests/preload.ts"]
+`;
+/**
+ * What every test file sees first.
+ *
+ * `import 'server-only'` is honoured by the build - a client file importing
+ * the module fails to build rather than shipping a secret - and resolves to
+ * nothing on the server. Under bun test it is the real package, which throws
+ * on import, so an action or a route that carries the line would not be a
+ * function a test can call. Stubbed here, once.
+ */
+export const testPreload = `import { mock } from 'bun:test'
+
+// The build honours this import and resolves it to nothing on the server;
+// the real package throws when imported, which is what a test would hit.
+mock.module('server-only', () => ({}))
+mock.module('client-only', () => ({}))
+`;
 export function smokeTest(o) {
     const runner = o.host === 'node'
         ? `import { before, describe, test } from 'node:test'
@@ -584,6 +616,11 @@ export async function createPost(input) { … }   // callable from a client comp
 Do not put \`"use server"\` at the top of a page to make it a server component.
 It already is one.
 
+A callback that a timer, a subscription or a listener calls and that must see
+the latest props is \`useEffectEvent\` from React, not a ref you assign every
+render. An Effect Event is never a dependency: leave it out of the array. The
+engine's own hooks are written this way.
+
 ## Reading the request
 
 \`cookies()\`, \`headers()\` and \`searchParams()\` come from
@@ -606,6 +643,13 @@ it before any page. ${o.env
 render waits for it). Do not import a bootstrap module from pages to get the
 same effect; it depends on nobody forgetting.
 
+## Forms
+
+Uncontrolled. Inputs keep their value in the DOM, an initial value is
+\`defaultValue\`, and the action reads \`FormData\`. Do not write \`useState\` +
+\`value\`/\`onChange\` per input. Control one field only when the UI must react
+as the user types, and bind that one with \`useField\`.
+
 ## Data
 
 Fetch in a server component and await it. There is no loader and no
@@ -679,7 +723,8 @@ not hand-parse \`Number(searchParams.get('page'))\`.
 
 \`${o.sourceDir}/app/**/route.ts\`, exporting \`GET\`, \`POST\` and so on.
 A real \`Request\` in, a real \`Response\` out. Await \`params\`,
-\`searchParams\` and \`body\` from the second argument.
+\`searchParams\` and \`body\` from the second argument - never
+\`new URL(request.url).searchParams\`, which the build cannot see.
 
 They run their directory's \`middleware.ts\`, and a \`GET\` that reads nothing
 from the request is answered from disk.
@@ -700,10 +745,15 @@ from the request is answered from disk.
  * the server the first time an agent starts it. Other clients want the same
  * four lines in their own file.
  */
-export function mcp() {
+export function mcp(o) {
+    // bunx on a Bun project, npx elsewhere: the same server either way, but an
+    // editor launching it should not need npm on a machine that has Bun.
+    const launcher = o && o.host !== 'node'
+        ? { command: 'bunx', args: ['@rsc-kit/mcp'] }
+        : { command: 'npx', args: ['-y', '@rsc-kit/mcp'] };
     return (JSON.stringify({
         mcpServers: {
-            'rsc-kit': { command: 'npx', args: ['-y', '@rsc-kit/mcp'] },
+            'rsc-kit': launcher,
         },
     }, null, 2) + '\n');
 }
@@ -803,6 +853,8 @@ import { createEnv } from '@t3-oss/env-core'
 // to start with PUBLIC_, and is read from import.meta.env, which is what Vite
 // exposes there. Add a variable: one line in the schema, and every reader is
 // typed.
+const processEnv: Record<string, string | undefined> = typeof process === 'undefined' ? {} : process.env
+
 export const env = createEnv({
   server: {
     NODE_ENV: ${lib.opt},
@@ -813,11 +865,13 @@ export const env = createEnv({
   client: {
     // PUBLIC_SITE_URL: ${lib.url},
   },
-  runtimeEnv: { ...process.env, ...import.meta.env },
+  // process is the server's; a "use client" file importing this for a
+  // PUBLIC_ value has only import.meta.env, and Vite fills the PUBLIC_ ones.
+  runtimeEnv: { ...processEnv, ...import.meta.env },
   emptyStringAsUndefined: true,
   // A build machine without the production variables: SKIP_ENV_VALIDATION=1
   // builds anyway, and the server that runs the build validates at startup.
-  skipValidation: !!process.env.SKIP_ENV_VALIDATION,
+  skipValidation: !!processEnv.SKIP_ENV_VALIDATION,
 })
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rsc-kit",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "type": "module",
   "description": "Scaffold an RSC app on Bun, Hono, Elysia or Node.",
   "bin": {