create-rsc-kit 0.18.1 → 0.20.0

package/dist/git.d.ts

@@ -0,0 +1,2 @@
+/** Whether `dir` is already inside a git work tree - its own, or a parent's. */
+export declare function insideRepository(dir: string): boolean;

package/dist/git.js

@@ -0,0 +1,6 @@
+import { spawnSync } from 'node:child_process';
+/** Whether `dir` is already inside a git work tree - its own, or a parent's. */
+export function insideRepository(dir) {
+    const result = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, stdio: 'pipe' });
+    return result.status === 0 && String(result.stdout).trim() === 'true';
+}

package/dist/index.js

@@ -9,6 +9,7 @@ import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { insideRepository } from './git.js';
 import { randomBytes } from 'node:crypto';
 import { argv, exit, stdout } from 'node:process';
 import { DEFAULT_COMPILER, HELP, HOSTS, publishedCore, assertInsideCwd, assertUsableName, defaultCore, parseArgs, VALIDATIONS } from './options.js';
@@ -48,8 +49,19 @@ catch (error) {
     stdout.write(`\n${bold('Cannot scaffold here.')}\n  ${error.message}\n\n`);
     exit(1);
 }
-if (options.git)
-    run('git', ['init', '--quiet'], options.dir);
+// Not inside a repository that already exists. A new app scaffolded into a
+// monorepo's apps/ got a repository of its own, nested and empty, and the
+// monorepo then refused to add the directory - git reads a nested .git as a
+// submodule with nothing in it. The new files belong to the repository that
+// is there.
+if (options.git) {
+    if (insideRepository(options.dir)) {
+        stdout.write(`\n${dim('Inside a git repository already; not creating another.')}\n`);
+    }
+    else {
+        run('git', ['init', '--quiet'], options.dir);
+    }
+}
 if (options.install) {
     stdout.write(`\n${dim('Installing dependencies…')}\n`);
     const pm = options.host === 'node' ? 'npm' : 'bun';
@@ -158,6 +170,13 @@ function write(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(o)],
     ];
     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;

package/dist/templates.js

@@ -92,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`,
                     }
                     : {}),
             }),
@@ -326,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'
@@ -618,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
@@ -691,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.
@@ -773,7 +806,8 @@ not render.
 
 A directory with a \`page.tsx\` is a route, so \`src/app/about/page.tsx\` is
 \`/about\` with nothing to register. \`[slug]\` is a parameter, and
-\`middleware.ts\` runs before anything at or below it renders.
+\`middleware.ts\` runs before anything at or below it renders; its default export is one
+check or a list of them, run in order and stopping at the first refusal.
 
 \`.rsc-kit/\` is the build's: the route types that make \`href\` checkable, and
 the ambient declarations. Rewritten every build, and gitignored.
@@ -820,6 +854,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},
@@ -830,11 +866,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.1",
+  "version": "0.20.0",
   "type": "module",
   "description": "Scaffold an RSC app on Bun, Hono, Elysia or Node.",
   "bin": {