create-rsc-kit 0.28.0 → 0.29.0

package/dist/agents.d.ts

@@ -0,0 +1,47 @@
+import type { Options } from './options.js';
+/** What the rules depend on: the app's host, where its source is, and two choices made at scaffold. */
+export interface AgentsOptions {
+    host: Options['host'];
+    sourceDir: string;
+    env: boolean;
+    pwa: boolean;
+    /** Whether actions are a backend's (Go, another server) rather than this app's JavaScript. */
+    backend?: boolean;
+}
+/** What a start marker records. */
+export interface AgentsStamp extends AgentsOptions {
+    version: string;
+}
+/** What the rules need from a scaffold's options. */
+export declare function agentsOptions(o: Options): AgentsOptions;
+/** The rules alone, for the options given: what the MCP server's `rules` tool answers. */
+export declare function rules(o: AgentsOptions): string;
+/** The section, between its markers, stamped with this version and the options. */
+export declare function agentsSection(o: AgentsOptions): string;
+/** The stamp in an AGENTS.md's section; `{}` for a section from before stamps; null with no section. */
+export declare function readStamp(text: string): Partial<AgentsStamp> | null;
+/** What `updateAgents` did, said once. */
+export type AgentsResult = {
+    kind: 'wrote' | 'updated' | 'current';
+    path: string;
+    version: string;
+} | {
+    kind: 'refused';
+    reason: string;
+};
+/**
+ * Write the rsc-kit section of `dir`/AGENTS.md as this version writes it.
+ *
+ * The options come from the section's own stamp; `given` overrides them, and
+ * is what an unstamped section from an older rsc-kit needs - the rules depend
+ * on the host and the source directory, and they are not guessed. A file with
+ * no section is only rewritten whole with `replace`, since then nothing
+ * marks what is ours.
+ */
+export declare function updateAgents(dir: string, given?: Partial<AgentsOptions> & {
+    replace?: boolean;
+}): AgentsResult;
+/** Parse `rsc-kit agents` flags. */
+export declare function agentsFlags(args: string[]): Partial<AgentsOptions> & {
+    replace?: boolean;
+};

package/dist/agents.js

@@ -0,0 +1,120 @@
+// The rsc-kit section of an AGENTS.md: the rules an agent follows in an
+// rsc-kit app, kept current the way Laravel Boost keeps its guidelines.
+//
+// The package owns the section and regenerates it on request - `rsc-kit
+// agents` - and git shows the change for review. Everything outside the
+// markers is the app's and is never touched. The start marker records which
+// version wrote the section and the options it was written for, so it can be
+// written again exactly, and the dev server can say when it is behind.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { selfVersion } from './stale.js';
+import * as t from './templates.js';
+const START = '<!-- rsc-kit:start';
+const END = '<!-- rsc-kit:end -->';
+/** What the rules need from a scaffold's options. */
+export function agentsOptions(o) {
+    return { host: o.host, sourceDir: o.sourceDir, env: Boolean(o.env), pwa: Boolean(o.pwa), backend: Boolean(o.backend) };
+}
+/** The rules alone, for the options given: what the MCP server's `rules` tool answers. */
+export function rules(o) {
+    return t.agents({ ...o, backend: o.backend ? 'yes' : undefined }).trim();
+}
+/** The section, between its markers, stamped with this version and the options. */
+export function agentsSection(o) {
+    const stamp = {
+        version: selfVersion(import.meta.url),
+        host: o.host,
+        sourceDir: o.sourceDir,
+        env: Boolean(o.env),
+        pwa: Boolean(o.pwa),
+        backend: Boolean(o.backend),
+    };
+    return `${START} ${JSON.stringify(stamp)} -->\n${rules(o)}\n${END}\n`;
+}
+/** The stamp in an AGENTS.md's section; `{}` for a section from before stamps; null with no section. */
+export function readStamp(text) {
+    const at = text.indexOf(START);
+    if (at === -1)
+        return null;
+    const line = text.slice(at, text.indexOf('-->', at));
+    const json = line.slice(START.length).trim();
+    try {
+        return json ? JSON.parse(json) : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Write the rsc-kit section of `dir`/AGENTS.md as this version writes it.
+ *
+ * The options come from the section's own stamp; `given` overrides them, and
+ * is what an unstamped section from an older rsc-kit needs - the rules depend
+ * on the host and the source directory, and they are not guessed. A file with
+ * no section is only rewritten whole with `replace`, since then nothing
+ * marks what is ours.
+ */
+export function updateAgents(dir, given = {}) {
+    const path = join(dir, 'AGENTS.md');
+    const version = selfVersion(import.meta.url);
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
+    const stamp = existing === null ? null : readStamp(existing);
+    if (existing !== null && stamp === null && !given.replace) {
+        return {
+            kind: 'refused',
+            reason: 'AGENTS.md has no rsc-kit section to update. If it is the one rsc-kit wrote, run again with --replace ' +
+                '(and --host and --source-dir) to rewrite it whole; git shows the change.',
+        };
+    }
+    const o = { ...stamp, ...given };
+    if (!o.host || !o.sourceDir) {
+        return {
+            kind: 'refused',
+            reason: 'This AGENTS.md was written before rsc-kit recorded the options it was written for. ' +
+                'Say them once: --host bun|node|worker|laravel --source-dir <dir> [--env] [--pwa].',
+        };
+    }
+    const section = agentsSection({
+        host: o.host,
+        sourceDir: o.sourceDir,
+        env: Boolean(o.env),
+        pwa: Boolean(o.pwa),
+        backend: Boolean(o.backend),
+    });
+    if (existing === null || (stamp === null && given.replace)) {
+        writeFileSync(path, section);
+        return { kind: 'wrote', path, version };
+    }
+    const start = existing.indexOf(START);
+    const endAt = existing.indexOf(END, start);
+    const before = existing.slice(0, start);
+    const after = endAt === -1 ? '' : existing.slice(endAt + END.length).replace(/^\n/, '');
+    const next = before + section + after;
+    if (next === existing)
+        return { kind: 'current', path, version };
+    writeFileSync(path, next);
+    return { kind: 'updated', path, version };
+}
+/** Parse `rsc-kit agents` flags. */
+export function agentsFlags(args) {
+    const out = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const [flag, inline] = arg.split('=', 2);
+        const value = () => inline ?? args[++i];
+        if (flag === '--host')
+            out.host = value();
+        else if (flag === '--source-dir')
+            out.sourceDir = value();
+        else if (flag === '--env')
+            out.env = true;
+        else if (flag === '--pwa')
+            out.pwa = true;
+        else if (flag === '--backend')
+            out.backend = true;
+        else if (flag === '--replace')
+            out.replace = true;
+    }
+    return out;
+}

package/dist/index.js

@@ -15,6 +15,7 @@ import { argv, exit, stdout } from 'node:process';
 import { DEFAULT_COMPILER, HELP, HOSTS, publishedCore, assertInsideCwd, assertUsableName, defaultCore, parseArgs, VALIDATIONS } from './options.js';
 import { Prompter, bold, cyan, dim } from './prompt.js';
 import { checkForNewer, notifyIfStale, selfVersion } from './stale.js';
+import { agentsOptions, agentsSection } from './agents.js';
 import * as t from './templates.js';
 import { setUpShadcn } from './shadcn.js';
 import { STARTER_ICONS } from './icons.js';
@@ -182,7 +183,13 @@ function write(o) {
         ['vite.config.ts', t.viteConfig(o)],
         ['.gitignore', t.gitignore],
         ['README.md', t.readme(o)],
-        ['AGENTS.md', t.agents(o)],
+        // Between markers, stamped: `rsc-kit agents` can bring it up to date.
+        ['AGENTS.md', agentsSection(agentsOptions(o))],
+        // The client every action and query is built from, for an app whose
+        // actions are its own JavaScript - so the check is there before the first.
+        ...(o.host !== 'laravel' && !o.backend
+            ? [[`${o.sourceDir}/server/client.ts`, t.actionClient()]]
+            : []),
         ['.mcp.json', t.mcp(o)],
         ['src/app/layout.tsx', t.layout(o)],
         ['src/app/page.tsx', t.page(o)],

package/dist/init.js

@@ -17,6 +17,7 @@ import { DEFAULT_COMPILER, parseArgs, publishedCore } from './options.js';
 import { setUpShadcn } from './shadcn.js';
 import { Prompter, bold, cyan, dim } from './prompt.js';
 import * as t from './templates.js';
+import { agentsOptions, agentsSection, readStamp } from './agents.js';
 // Nothing here detects a host any more: a host is a Nitro preset, and Nitro
 // is added to whatever project this runs in.
 const HOST_PACKAGES = {};
@@ -228,9 +229,6 @@ 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.
  *
@@ -243,14 +241,14 @@ const AGENTS_END = '<!-- rsc-kit:end -->';
 function mergeAgents(dir, o) {
     const path = join(dir, 'AGENTS.md');
     if (!existsSync(path)) {
-        writeFileSync(path, t.agents(o));
+        writeFileSync(path, agentsSection(agentsOptions(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' };
+    if (readStamp(existing) !== null || /rsc-kit/i.test(existing)) {
+        return { kind: 'skipped', what: 'AGENTS.md', detail: 'already covers rsc-kit - rsc-kit agents brings it up to date' };
     }
-    writeFileSync(path, existing.replace(/\s*$/, '\n\n') + `${AGENTS_START}\n${t.agents(o).trim()}\n${AGENTS_END}\n`);
+    writeFileSync(path, existing.replace(/\s*$/, '\n\n') + agentsSection(agentsOptions(o)));
     return { kind: 'merged', what: 'AGENTS.md', detail: 'added a section at the end; yours is untouched above it' };
 }
 /**

package/dist/templates.d.ts

@@ -169,3 +169,9 @@ export declare function backendEnvExample(backend: string): string;
 export declare function backendStep(go: boolean): string;
 /** The example beside it - the one file that is committed. */
 export declare const envExample = "# Copy to .env and fill in. Server variables never reach the browser;\n# a browser-readable one starts with VITE_. The schema is src/env.ts.\n#\n# Not NODE_ENV. Vite sets it - development under `vite`, production under\n# `vite build` - and a value written here overrides that: NODE_ENV=development\n# in .env makes a production build emit React's development JSX runtime,\n# which the production server does not have, and every page fails to render.\n# DATABASE_URL=\n# SESSION_SECRET=\n# VITE_SITE_URL=\n";
+/**
+ * The action client every action and query is built from - for an app whose
+ * actions are JavaScript. One place for the check, so a new action cannot be
+ * written without it.
+ */
+export declare function actionClient(): string;

package/dist/templates.js

@@ -624,6 +624,46 @@ The \`rsc-kit\` MCP server in \`.mcp.json\` answers from this project's last
 build — which routes froze and why, what is heaviest — and has the long-form
 recipe for anything here (\`how_to\`). Ask it before guessing.
 
+## Rules
+
+Follow these on every change. Each is explained further down.
+
+${o.host === 'laravel'
+        ? `- **Run \`${pm} typecheck\` before saying it is done**, and test the PHP side with Pest.`
+        : `- **A change is not done without its test**, and not done until \`${pm} check\` passes.
+  A route, action, query or api route that is added or changed gets one.`}
+${o.host === 'laravel'
+        ? `- **Configuration is Laravel's**: a new setting goes in \`config/\` and \`.env.example\`.`
+        : `- **Every environment variable is declared in \`${o.sourceDir}/env.ts\`** - server or
+  \`VITE_\` client schema - and in \`.env.example\`, rsc-kit's own included
+  (\`RSC_SIGNING_SECRET\`, once a page uses \`refreshOn\`). Server code reads
+  \`env\` from it, never \`process.env\`; a client component reads its \`VITE_\` value
+  from \`import.meta.env\`, already checked there.${o.env ? '' : ` No \`env.ts\` yet? \`how_to({ topic: 'env' })\` sets it up.`}`}
+- **Pages paint at once.** A page is synchronous; each read is an async
+  component under its own \`<Suspense>\`. Reach for \`loading.tsx\` only when a
+  route's whole body is one read.
+- **Server components call the data function directly** - never \`fetch\` this
+  app's own api routes from the server.
+- **Live data**: \`refreshOn\` on the section and \`changed()\` where the data
+  changes. \`usePolling\` only for data nothing can announce. Never
+  \`setInterval\` with \`refresh()\`.
+${o.host === 'laravel' || o.backend
+        ? `- **Authorisation lives in the backend**, in the function the call reaches${o.host === 'laravel' ? ' - \`#[Authenticated]\`, \`#[Can]\`, a policy' : ' - its guard or the handler'} - never only in the component that shows the button.`
+        : `- **Every action and query is built from the client in \`${o.sourceDir}/server/client.ts\`**,
+  and authorisation is its \`.use()\` middleware - never a check written in a
+  component, and never a bare \`'use server'\` function for anything that writes.`}
+- **Links and redirects are typed**: \`\`<Link href={\`/posts/\${slug}\`}>\`\`, a template
+  literal, so a renamed route fails the typecheck. Never build urls by
+  concatenation.
+- **Metadata is \`export const metadata\`** (or \`generateMetadata\`), never tags in
+  a page's markup.
+- **Never edit generated files**: \`.rsc-kit/\`, \`${o.sourceDir}/server-actions.generated.ts\`,
+  \`rsc-host.json\`. Change what they are generated from.
+- **Secrets are generated, never invented or committed**: \`openssl rand -base64 32\`,
+  kept in \`.env\` (ignored) and the platform's secret settings.
+- **Ask before guessing**: \`how_to\` has the pattern for anything here; a
+  pattern from another framework is usually wrong here.
+
 ## Commands
 
 \`\`\`sh
@@ -803,6 +843,25 @@ A real \`Request\` in, a real \`Response\` out. Await \`params\`,
 They run their directory's \`middleware.ts\`, and a \`GET\` that reads nothing
 from the request is answered from disk.
 
+## Live data
+
+A section that names what it depends on refreshes in every open tab when
+something says that changed - a webhook, a job, another visitor:
+
+\`\`\`tsx
+export default section('repos', Repos, { refreshOn: ({ params }) => [\`team:\${params.team}:repos\`] })
+\`\`\`
+
+\`\`\`ts
+await changed(\`team:\${team}:repos\`)   // after the write commits
+\`\`\`
+
+Name the data with ids, as narrowly as it changes. More than one process
+needs a shared store, and production needs \`RSC_SIGNING_SECRET\` - ${o.host === 'laravel'
+        ? 'in the renderer\'s environment, beside the host-call secret, and in `.env.example`:'
+        : 'declared in `env.ts`, required in production, so a deploy without it fails at startup:'}
+\`how_to({ topic: 'refresh-on' })\`, or the Live data guide.
+
 ## Things that are not this project
 
 - No \`pages/\` directory, no \`_app\`, no \`getStaticProps\`.
@@ -1047,3 +1106,45 @@ export const envExample = `# Copy to .env and fill in. Server variables never re
 # SESSION_SECRET=
 # VITE_SITE_URL=
 `;
+/**
+ * The action client every action and query is built from - for an app whose
+ * actions are JavaScript. One place for the check, so a new action cannot be
+ * written without it.
+ */
+export function actionClient() {
+    return `'use server'
+
+import { createActionClient } from '@rsc-kit/core/action'
+import { ServerAuthenticationError } from '@rsc-kit/core/errors'
+
+// Every action and query in this app is built from one of these clients, so
+// the check runs before the body and cannot be forgotten:
+//
+//   export const createPost = authedClient.input(schema).handler(async ({ input, ctx }) => …)
+//   export const getPosts   = publicClient.query(async () => …)
+//
+// An action is a public endpoint - anyone can call it, with any arguments -
+// so the check belongs here, never in the component that shows the button.
+
+/** Anyone may call it: public reads, a contact form. */
+export const publicClient = createActionClient()
+
+/** Only someone signed in; ctx.user is theirs inside the action. */
+export const authedClient = publicClient.use(async ({ next }) => {
+  const user = await currentUser()
+
+  if (!user) throw new ServerAuthenticationError()
+
+  return next({ ctx: { user } })
+})
+
+/**
+ * Who is calling - connect this to your session: read its cookie with
+ * cookies() from '@rsc-kit/core/request', and look the user up. Until then
+ * nobody is signed in, and authedClient refuses every call.
+ */
+async function currentUser(): Promise<{ id: string } | null> {
+  return null
+}
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rsc-kit",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "type": "module",
   "description": "Scaffold an RSC app on Bun, Hono, Elysia or Node.",
   "bin": {
@@ -38,6 +38,10 @@
     "./stale": {
       "types": "./dist/stale.d.ts",
       "default": "./dist/stale.js"
+    },
+    "./agents": {
+      "types": "./dist/agents.d.ts",
+      "default": "./dist/agents.js"
     }
   },
   "repository": {