@invisibleloop/pulse 0.20.11 → 0.20.20

package/docs/src/pages/forms.js

@@ -1,129 +0,0 @@
-import { renderLayout, h1, lead, section, sub, codeBlock, callout, table } from '../lib/layout.js'
-import { prevNext } from '../lib/nav.js'
-import { highlight } from '../lib/highlight.js'
-
-const { prev, next } = prevNext('/forms')
-
-export default {
-  route: '/forms',
-  meta: {
-    theme:       'light',
-    title: 'Forms — Pulse Docs',
-    description: 'Server-side form handling in Pulse. spec.submit processes POST requests without client JavaScript, with automatic CSRF protection and POST-redirect-GET.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/forms',
-    prev,
-    next,
-    content: `
-      ${h1('Forms')}
-      ${lead('A spec with a <code>submit</code> handler accepts POST requests on its own route — the form works with JavaScript disabled. CSRF protection is automatic, and successful submissions follow POST-redirect-GET. Client-side <code>actions</code> become an enhancement, not a requirement.')}
-
-      ${section('basics', 'Basic usage')}
-      <p>Add a <code>submit</code> function to the spec and render a plain <code>&lt;form method="POST"&gt;</code>. The route accepts POST automatically — no <code>methods</code> declaration needed.</p>
-      ${codeBlock(highlight(`export default {
-  route: '/contact',
-
-  submit: async (ctx) => {
-    const data = await ctx.formData()
-    if (!data?.email) return { errors: { email: 'Email is required' }, values: data ?? {} }
-    await sendMessage(data)
-    return { redirect: '/contact?sent=1' }   // 303 POST-redirect-GET
-  },
-
-  view: (state, server) => \`
-    <main id="main-content">
-      \${server.form?.errors?.email ? \`<p class="error">\${escHtml(server.form.errors.email)}</p>\` : ''}
-      <form method="POST">
-        \${server.csrf}
-        \${input({ label: 'Email', name: 'email', type: 'email', required: true,
-                   value: server.form?.values?.email ?? '' })}
-        \${button({ label: 'Send', type: 'submit' })}
-      </form>
-    </main>
-  \`,
-}`, 'js'))}
-      <p>The flow: the browser POSTs the form, <code>submit(ctx)</code> runs server-side, and either redirects (success) or re-renders the page with the returned value available to the view as <code>server.form</code> (validation failure).</p>
-
-      ${callout('warning', '<strong><code>\${server.csrf}</code> must be inside every POST form.</strong> It renders the hidden CSRF token input — submissions without a valid token are rejected with <strong>403</strong> before <code>submit</code> runs.')}
-
-      ${section('return-values', 'Return values')}
-      ${table(
-        ['Return', 'Response', 'Use for'],
-        [
-          ['<code>{ redirect: \'/path\' }</code>', '<strong>303 See Other</strong>', 'Successful submissions — POST-redirect-GET means refresh never resubmits'],
-          ['<code>{ errors, values, … }</code>',  'Page re-renders (200), value exposed as <code>server.form</code>', 'Validation failures — show errors, echo values back into inputs'],
-          ['<code>{ status: 422, errors, … }</code>', 'Same re-render with status <strong>422</strong>', 'Validation failures where the status code matters (API clients, tests)'],
-          ['<code>undefined</code>', 'Page re-renders (200), <code>server.form</code> is <code>{}</code>', 'Fire-and-forget side effects'],
-        ]
-      )}
-      <p><strong>Always redirect after a successful mutation.</strong> Rendering a success message directly from the POST means a browser refresh resubmits the form. Redirect to a URL that shows the confirmation instead (e.g. <code>/contact?sent=1</code>).</p>
-
-      ${section('server-form', 'server.form — errors and echoed values')}
-      <p>On a re-render, whatever <code>submit</code> returned is available to the view as <code>server.form</code>. On a plain GET it is <code>undefined</code> — always use optional chaining.</p>
-      ${codeBlock(highlight(`// In submit — return errors AND the submitted values:
-return { errors: { email: 'Invalid email' }, values: data }
-
-// In the view — show the error, echo the value back so the form isn't wiped:
-\${server.form?.errors?.email ? \`<p class="error">\${escHtml(server.form.errors.email)}</p>\` : ''}
-\${input({ name: 'email', label: 'Email', value: server.form?.values?.email ?? '' })}`, 'js'))}
-      ${callout('warning', 'Escape user-submitted values before interpolating them into HTML — <code>server.form.values</code> is raw user input. Component props like <code>input({ value })</code> are auto-escaped; manual interpolation needs <code>escHtml()</code>.')}
-
-      ${section('csrf', 'CSRF protection')}
-      <p>Every <code>submit</code> spec gets CSRF protection automatically — there is nothing to configure. Under the hood Pulse uses an HMAC double-submit pattern:</p>
-      ${table(
-        ['Piece', 'Where it lives', 'What it does'],
-        [
-          ['Random id', '<code>pulse_csrf</code> cookie (HttpOnly, SameSite=Lax)', 'Set on the first GET of the form page'],
-          ['Token', 'Hidden <code>_csrf</code> input via <code>\${server.csrf}</code>', '<code>HMAC-SHA256(secret, id)</code> — embedded into the form server-side'],
-          ['Verification', 'On every POST, before <code>submit</code> runs', 'Recomputes the HMAC from the cookie and compares in constant time — mismatch is 403'],
-        ]
-      )}
-      <p>An attacker on another origin can cause the cookie to be sent, but cannot read it or compute the HMAC — so they cannot forge the pair.</p>
-
-      ${sub('multi-instance', 'Multiple server instances')}
-      <p>The HMAC secret defaults to a random value per server boot. Behind a load balancer, pin it so tokens issued by one instance validate on another:</p>
-      ${codeBlock(highlight(`await createServer(pages, {
-  secret: process.env.PULSE_SECRET,   // stable across instances and restarts
-})`, 'js'))}
-
-      ${sub('opt-out', 'Opting out')}
-      <p>Set <code>csrf: false</code> on the spec to disable protection — only for endpoints with their own authentication, such as signed webhooks:</p>
-      ${codeBlock(highlight(`export default {
-  route: '/webhooks/stripe',
-  csrf: false,                       // Stripe signs its requests — verify the signature instead
-  submit: async (ctx) => {
-    verifyStripeSignature(ctx.headers['stripe-signature'], await ctx.text())
-    // ...
-  },
-  view: () => '<main id="main-content">ok</main>',
-}`, 'js'))}
-      ${callout('warning', 'Never set <code>csrf: false</code> to "fix" a 403. The 403 means the form is missing <code>\${server.csrf}</code> — add the field, don\'t remove the protection.')}
-
-      ${section('progressive-enhancement', 'Progressive enhancement')}
-      <p>The same form can serve both worlds: <code>method="POST"</code> is the no-JS fallback, <code>data-action</code> is the hydrated path. With JavaScript enabled the runtime intercepts the submit and runs the async action (no page reload); without it the browser POSTs to <code>submit</code>.</p>
-      ${codeBlock(highlight(`<form method="POST" data-action="send">
-  \${server.csrf}
-  \${input({ label: 'Email', name: 'email', type: 'email', required: true })}
-  \${button({ label: 'Send', type: 'submit' })}
-</form>`, 'html'))}
-      <p>Keep the two paths consistent: <code>submit</code> and the action's <code>run</code> should call the same underlying function so validation and side effects cannot drift apart.</p>
-
-      ${section('caching', 'Interaction with caching')}
-      <p>Pages with <code>submit</code> are automatically excluded from the in-process page cache — the CSRF token is per-visitor, and a cached page would serve one visitor's token to everyone. POST responses are never cached.</p>
-
-      ${section('reference', 'Reference')}
-      ${table(
-        ['Property', 'Type', 'Notes'],
-        [
-          ['<code>submit</code>', '<code>async (ctx) =&gt; { redirect } | object | void</code>', 'Handles POST on the route. Guard runs first.'],
-          ['<code>csrf</code>', '<code>boolean</code>', 'Default <code>true</code>. Set <code>false</code> only for self-authenticated endpoints.'],
-          ['<code>server.csrf</code>', 'string (view)', 'Hidden <code>_csrf</code> input — required inside every POST form.'],
-          ['<code>server.form</code>', 'object | undefined (view)', 'Return value of <code>submit</code> on a re-render; <code>undefined</code> on GET.'],
-          ['<code>secret</code>', 'string (createServer option)', 'Stable HMAC secret for multi-instance deployments.'],
-        ]
-      )}
-    `,
-  }),
-}

package/docs/src/pages/getting-started.js

@@ -1,147 +0,0 @@
-import { renderLayout, h1, lead, section, codeBlock, callout } from '../lib/layout.js'
-import { prevNext } from '../lib/nav.js'
-import { highlight } from '../lib/highlight.js'
-
-const { prev, next } = prevNext('/getting-started')
-
-export default {
-  route: '/getting-started',
-  meta: {
-    theme:       'light',
-    title: 'Getting Started — Pulse Docs',
-    description: 'Install Pulse and build your first page with an AI agent in minutes.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/getting-started',
-    prev,
-    next,
-    content: `
-      ${h1('Getting Started')}
-      ${lead('Install Pulse, run one command, and have an AI agent building your first page — with streaming SSR, security headers, and a 100 Lighthouse score already in place.')}
-
-      ${section('requirements', 'Requirements')}
-      <ul>
-        <li><strong>Node.js 22 or later</strong> — <a href="https://nodejs.org" target="_blank" rel="noopener" aria-label="nodejs.org (opens in new tab)">nodejs.org</a></li>
-        <li><strong>Google Chrome</strong> — used by the agent for screenshots and Lighthouse audits — <a href="https://www.google.com/chrome" target="_blank" rel="noopener" aria-label="google.com/chrome (opens in new tab)">google.com/chrome</a></li>
-        <li><strong>An AI agent</strong> — Claude Code or GitHub Copilot CLI (pick one):</li>
-      </ul>
-      <ul>
-        <li><strong>Claude Code</strong> — <a href="https://docs.anthropic.com/en/docs/claude-code/getting-started" target="_blank" rel="noopener" aria-label="Claude Code installation guide (opens in new tab)">installation guide</a> — the default; no extra config needed</li>
-        <li><strong>GitHub Copilot CLI</strong> — <a href="https://docs.github.com/copilot/concepts/agents/about-copilot-cli" target="_blank" rel="noopener" aria-label="GitHub Copilot CLI documentation (opens in new tab)">documentation</a> — use with the <code>--agent copilot</code> flag</li>
-      </ul>
-      <p>Pulse launches your chosen agent automatically with the Pulse MCP server wired in — so the agent has instant access to the framework reference, your project structure, and all Pulse tools without any manual configuration.</p>
-
-      ${section('install', 'Install Pulse')}
-      <p>Install the Pulse CLI globally:</p>
-      ${codeBlock(highlight('npm install -g @invisibleloop/pulse', 'bash'))}
-
-      ${section('create', 'Create your project')}
-      <p>Run <code>pulse</code> in any empty directory:</p>
-      ${codeBlock(highlight(`mkdir my-app
-cd my-app
-pulse`, 'bash'))}
-      <p>Pulse detects the directory is empty and scaffolds a project there. It creates the project files, installs dependencies, and exits with:</p>
-      ${codeBlock(highlight('✓ Project ready. Run `pulse` again to start your AI session.', 'bash'))}
-      ${callout('tip', 'Running <code>pulse</code> in a non-empty directory prompts for a project name, then creates and scaffolds a subdirectory with that name — so you can run it from anywhere.')}
-
-      ${section('session', 'Start a session')}
-      <p>Run <code>pulse</code> again from inside your project directory:</p>
-      ${codeBlock(highlight('pulse', 'bash'))}
-      <p>Pulse detects the existing project and launches Claude Code with the Pulse MCP server already connected. Claude opens with the complete framework guide loaded, your project structure visible, and all Pulse tools available — ready to build immediately.</p>
-      ${callout('note', 'Run <code>pulse</code> every time you open a working session. It handles starting the agent and wiring up the MCP server. Once the agent is open, use <code>/pulse-dev</code> (Claude) or the <code>build-page</code> skill (Copilot) to start the dev server.')}
-
-      ${section('copilot', 'Using GitHub Copilot')}
-      <p>To use GitHub Copilot CLI instead of Claude, pass the <code>--agent</code> flag when scaffolding:</p>
-      ${codeBlock(highlight('pulse --agent copilot', 'bash'))}
-      <p>This scaffolds the project and writes <code>agent: \'copilot\'</code> into <code>pulse.config.js</code> — so subsequent <code>pulse</code> runs pick up the preference automatically. You can also set it manually in <code>pulse.config.js</code> at any time:</p>
-      ${codeBlock(highlight(`export default {
-  agent: 'copilot',
-}`, 'js'))}
-      <p>When using Copilot, project skills (<code>build-page</code>, <code>verify</code>, <code>new-doc-page</code>) are available via the <code>/skills</code> command inside the Copilot CLI session. The Pulse MCP server is automatically injected into your Copilot MCP config for the duration of the session and removed cleanly on exit.</p>
-
-      ${section('first-build', 'Build your first page')}
-      <p>Once Claude opens, start the dev server and ask for something:</p>
-      ${codeBlock(highlight(`/pulse-dev
-
-"Create a contact form with name, email, and message fields.
-Validate the email format before submitting."`, 'bash'))}
-      <p>The agent will:</p>
-      <ol>
-        <li>Fetch the Pulse guide from the MCP server — spec format, component library, quality rules</li>
-        <li>Check what pages already exist in your project</li>
-        <li>Write the spec — route, state, validation, action lifecycle, view</li>
-        <li>Validate it against the schema and fix every error and warning</li>
-        <li>Open the page in the browser and confirm it looks right</li>
-      </ol>
-      <p>You do not need to explain Pulse to the agent. The MCP server supplies the reference. Just describe what you want.</p>
-
-      ${section('what-was-created', 'What got created')}
-      <p>When you ran <code>pulse</code> in step 2, these files were written to your directory:</p>
-      ${codeBlock(highlight(`my-app/
-├── src/
-│   ├── pages/
-│   │   └── home.js          ← your first page spec (a working counter)
-│   └── components/          ← shared view components go here
-├── public/
-│   ├── app.css              ← global stylesheet
-│   ├── pulse-ui.css         ← Pulse component library styles
-│   └── pulse-ui.js          ← Pulse component library behaviour
-├── .claude/                 ← Claude Code agent context
-│   ├── CLAUDE.md            ← session instructions Claude reads on startup
-│   ├── settings.json        ← hooks: syntax checks, colour guards, package blocklist
-│   ├── pulse-checklist.md   ← spec review checklist, kept in sync by Pulse
-│   └── commands/            ← slash commands available inside Claude
-│       ├── pulse-dev.md
-│       ├── pulse-stop.md
-│       ├── pulse-build.md
-│       └── pulse-start.md
-├── .copilot/                ← GitHub Copilot CLI agent context
-│   └── skills/              ← project skills available inside Copilot
-│       ├── build-page/
-│       ├── verify/
-│       └── new-doc-page/
-├── .github/
-│   ├── copilot-instructions.md          ← session instructions for Copilot
-│   └── instructions/
-│       └── pulse-checklist.instructions.md
-├── package.json
-└── pulse.config.js          ← port, agent, and project settings`, 'bash'))}
-      <p><code>src/pages/home.js</code> is a complete working spec — a counter with increment and decrement buttons. Open <a href="http://localhost:3000">localhost:3000</a> after starting the dev server to see it. Every new page you create goes into <code>src/pages/</code> and is discovered automatically.</p>
-      <p>The <code>.claude/</code> directory contains the Claude agent's operating context. The <code>.copilot/</code> directory contains the equivalent context for GitHub Copilot — project skills and instructions. Both are scaffolded by default so you can switch agents at any time.</p>
-
-      ${section('commands', 'Agent commands')}
-      <p>These slash commands are available once Claude is open:</p>
-      ${codeBlock(highlight(`/pulse-dev     # start (or restart) the dev server
-/pulse-stop    # stop the dev server
-/pulse-build   # production build → public/dist/
-/pulse-start   # run the production server
-/pulse-report  # Lighthouse audit + performance report`, 'bash'))}
-      <p>When using GitHub Copilot CLI, the equivalent capabilities are available as project skills. Type <code>/skills</code> inside Copilot to browse them — <code>build-page</code>, <code>verify</code>, and <code>new-doc-page</code> are all pre-installed.</p>
-      <p>You can also skip commands and skills entirely — just describe what you want and the agent handles the rest.</p>
-
-      ${section('update', 'Keeping up to date')}
-      <p>When a new version of Pulse is released, update the package and then run <code>pulse update</code> from your project root:</p>
-      ${codeBlock(highlight(`npm update @invisibleloop/pulse
-pulse update`, 'bash'))}
-      <p><code>pulse update</code> copies the latest UI assets and agent files into your project:</p>
-      <ul>
-        <li><code>public/pulse-ui.css</code> and <code>public/pulse-ui.js</code> — component library styles and behaviour</li>
-        <li><code>.claude/pulse-checklist.md</code> and <code>.claude/commands/</code> — Claude agent files</li>
-        <li><code>.copilot/skills/</code> — Copilot project skills</li>
-        <li><code>.github/instructions/pulse-checklist.instructions.md</code> — Copilot checklist</li>
-      </ul>
-      <p>Your own source files, <code>CLAUDE.md</code>, <code>.github/copilot-instructions.md</code>, and <code>pulse.config.js</code> are never touched.</p>
-
-      ${section('next-steps', 'Next steps')}
-      <ul>
-        <li><a href="/how-it-works">How It Works</a> — the MCP server, what the agent knows, and the full build cycle</li>
-        <li><a href="/project-structure">Project Structure</a> — where files live and how pages are discovered</li>
-        <li><a href="/spec">Spec Reference</a> — every field the spec supports</li>
-        <li><a href="/state">State</a> — client state and mutations</li>
-        <li><a href="/server-data">Server Data</a> — fetch data on the server before the page renders</li>
-        <li><a href="/prompt-examples">Prompt Examples</a> — real prompts with the output they produce</li>
-      </ul>
-    `,
-  }),
-}

package/docs/src/pages/guard.js

@@ -1,120 +0,0 @@
-import { renderLayout, h1, lead, section, sub, codeBlock, callout, table } from '../lib/layout.js'
-import { prevNext } from '../lib/nav.js'
-import { highlight } from '../lib/highlight.js'
-
-const { prev, next } = prevNext('/guard')
-
-export default {
-  route: '/guard',
-  meta: {
-    theme:       'light',
-    title: 'Guard — Pulse Docs',
-    description: 'Per-route authorization in Pulse. Guard functions run before server data fetchers and redirect unauthorized requests.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/guard',
-    prev,
-    next,
-    content: `
-      ${h1('Guard')}
-      ${lead('A <code>guard</code> function runs on every request to a route, before any server data is fetched. It is the enforced access control point — unauthorized requests are redirected before any database queries or data fetchers execute.')}
-
-      ${section('basics', 'Basic usage')}
-      <p>A <code>guard</code> function on any spec receives the same <code>ctx</code> object as server data fetchers — params, query, headers, and cookies.</p>
-      ${codeBlock(highlight(`export default {
-  route: '/dashboard',
-
-  guard: async (ctx) => {
-    if (!ctx.cookies.session) return { redirect: '/login' }
-  },
-
-  server: {
-    user: async (ctx) => getCurrentUser(ctx.cookies.session),
-  },
-
-  view: (state, server) => \`
-    <main id="main-content">
-      <h1>Welcome, \${server.user.name}</h1>
-    </main>
-  \`,
-}`, 'js'))}
-
-      <p>When the guard returns <code>{ redirect }</code>, the server responds with a <strong>302</strong> and all server data fetchers are skipped — no data is fetched for unauthorized requests. When the guard returns nothing, the request proceeds normally.</p>
-
-      ${section('ctx', 'What ctx contains')}
-      ${table(
-        ['Property / Method', 'Type', 'Description'],
-        [
-          ['<code>ctx.cookies</code>', 'object', 'Parsed cookies from the <code>Cookie</code> header'],
-          ['<code>ctx.headers</code>', 'object', 'Raw request headers'],
-          ['<code>ctx.params</code>',  'object', 'Route params e.g. <code>{ id: "42" }</code>'],
-          ['<code>ctx.query</code>',   'object', 'Parsed query string'],
-          ['<code>ctx.pathname</code>','string',  'URL path e.g. <code>/dashboard</code>'],
-          ['<code>ctx.method</code>',  'string',  'HTTP method e.g. <code>GET</code>, <code>POST</code>'],
-          ['<code>ctx.store</code>',   'object',  'Resolved global store state (if a store is registered)'],
-          ['<code>ctx.nonce</code>',   'string',  'CSP nonce for the current request'],
-          ['<code>await ctx.json()</code>',     'object | null', 'Parse a JSON request body'],
-          ['<code>await ctx.text()</code>',     'string',        'Read the body as a plain string'],
-          ['<code>await ctx.formData()</code>', 'object | null', 'Parse a URL-encoded body into a plain object'],
-          ['<code>await ctx.buffer()</code>',   'Buffer',        'Read the raw body as a Node.js Buffer'],
-        ]
-      )}
-
-      ${section('examples', 'Common patterns')}
-
-      ${sub('Session check')}
-      <p>Redirect to login when no session cookie is present.</p>
-      ${codeBlock(highlight(`guard: async (ctx) => {
-  if (!ctx.cookies.session) return { redirect: '/login' }
-}`, 'js'))}
-
-      ${sub('Role-based access')}
-      <p>Fetch the user from the session and check their role. Keep the lookup fast — guard runs on every request to the route.</p>
-      ${codeBlock(highlight(`guard: async (ctx) => {
-  const user = await getUserFromSession(ctx.cookies.session)
-  if (!user)            return { redirect: '/login' }
-  if (!user.isAdmin)    return { redirect: '/403'   }
-}`, 'js'))}
-
-      ${sub('Redirect authenticated users away from login')}
-      <p>Useful for login and signup pages — send already-authenticated users somewhere useful.</p>
-      ${codeBlock(highlight(`export default {
-  route: '/login',
-
-  guard: async (ctx) => {
-    if (ctx.cookies.session) return { redirect: '/dashboard' }
-  },
-
-  view: () => \`<main id="main-content">...</main>\`,
-}`, 'js'))}
-
-      ${callout('info', 'Guard runs server-side on every request, including client-side navigation requests — those go through the same server pipeline. There is no way to bypass guard from the browser.')}
-
-      ${section('custom-responses', 'Custom status responses')}
-      <p>Guard can return a custom HTTP response instead of (or alongside) a redirect. Return <code>{ status, json?, body?, headers? }</code> to send any status code with an optional JSON or text body. This is useful for POST handlers that need to signal validation errors or API-style rejections:</p>
-      ${codeBlock(highlight(`guard: async (ctx) => {
-  const token = ctx.headers.authorization
-  if (!token) return { status: 401, json: { error: 'Unauthorized' } }
-
-  if (ctx.method === 'POST') {
-    const data = await ctx.formData()
-    if (!data.email) return { status: 422, json: { error: 'Email required' } }
-    await db.leads.create(data)
-    return { redirect: '/contact?sent=1' }
-  }
-  // return nothing to let a GET request proceed to the view
-}`, 'js'))}
-      ${callout('note', 'To use <code>guard</code> as a POST handler, the spec must declare <code>methods: [\'GET\', \'POST\']</code>. Without it, POST requests are rejected with 405 before guard runs.')}
-      ${callout('tip', 'For HTML form submissions, prefer <a href="/forms"><code>spec.submit</code></a> — it accepts POST automatically, gets CSRF protection for free, and re-renders the page with validation errors. Guard-based POST handling is best for API-style endpoints.')}
-
-      ${section('reference', 'Reference')}
-      ${table(
-        ['Property', 'Type', 'Required'],
-        [
-          ['<code>guard</code>', '<code>async (ctx) =&gt; { redirect?: string } | { status, json?, body?, headers? } | void</code>', 'No'],
-        ]
-      )}
-    `,
-  }),
-}