@invisibleloop/pulse 0.18.2 → 0.19.0

package/CLAUDE.md

@@ -294,6 +294,10 @@ await createServer(
                                   // dynamic :param routes contribute via spec.sitemap enumerators;
                                   // a physical sitemap.xml/robots.txt in staticDir always wins
     robots:       null,           // robots.txt when sitemap on: null = auto, false = off, string = verbatim
+    redirects: {                  // declarative redirects for legacy URLs — 301 by default,
+      '/old-blog/:slug': '/blog/:slug',          // :params carry over, query string preserved
+      '/promo': { to: '/pricing', status: 302 }, // custom status: 301 | 302 | 307 | 308
+    },                            // checked before routing (GET/HEAD only); validated at startup
     csp: {                        // extra sources merged into the framework's default CSP
       'style-src': ['https://fonts.googleapis.com'],
       'font-src':  ['https://fonts.gstatic.com'],

package/docs/src/pages/routing.js

@@ -79,6 +79,19 @@ server: {
   },
 }`, 'js'))}
 
+      ${section('redirects', 'Redirects')}
+      <p>Migrating an existing site? Preserve the old URLs with the <code>redirects</code> map — legacy links and search rankings survive the move:</p>
+      ${codeBlock(highlight(`await createServer(pages, {
+  redirects: {
+    '/old-blog/:slug': '/blog/:slug',                 // 301 — :params carry over
+    '/pricing-2024':   '/pricing',                    // 301 (default)
+    '/promo':          { to: '/sale', status: 302 },  // temporary redirect
+    '/moved/:slug':    'https://other.com/:slug',     // absolute targets for domain moves
+  },
+})`, 'js'))}
+      <p>Redirects respond <strong>301</strong> by default (permanent — search engines transfer ranking to the target). Use <code>{ to, status }</code> for <code>302</code>, <code>307</code>, or <code>308</code>. The query string is preserved, redirects apply to GET/HEAD only, and the map is validated at startup — a bad entry fails the boot rather than silently misrouting traffic.</p>
+      ${callout('note', 'Redirects are checked before route matching, so a redirect source that equals a registered route shadows the page — the server logs a startup warning when that happens. Occasionally intentional (retiring a page), usually a mistake.')}
+
       ${section('not-found', '404 handling')}
       <p>If no spec matches the incoming request path, Pulse returns a 404. To customise it, create a spec with <code>route: '*'</code> — it renders through the normal pipeline (layout, styles, components) with status 404:</p>
       ${codeBlock(highlight(`export default {

package/docs/src/pages/server-api.js

@@ -51,6 +51,7 @@ await createServer(entries, options)`, 'js'))}
           ['<code>secret</code>', '<code>string</code>', 'random per boot', 'HMAC secret for CSRF tokens (<a href="/forms">Forms</a>). Set a stable value when running multiple instances so tokens issued by one validate on another.'],
           ['<code>sitemap</code>', '<code>boolean | { origin }</code>', '<code>false</code>', 'Auto-serve <code>/sitemap.xml</code> + <code>robots.txt</code> from the registered routes. Dynamic <code>:param</code> routes contribute via <code>spec.sitemap</code> enumerators. See <a href="/meta#sitemap">Metadata &amp; SEO</a>.'],
           ['<code>robots</code>', '<code>string | false</code>', 'auto', 'robots.txt behaviour when sitemap is enabled — <code>false</code> disables, a string is served verbatim.'],
+          ['<code>redirects</code>', '<code>object</code>', '<code>null</code>', 'Declarative redirect map for legacy URLs — <code>{ \'/old/:slug\': \'/new/:slug\' }</code>, 301 by default. See <a href="/routing#redirects">Routing</a>.'],
           ['<code>onRequest</code>', '<code>function</code>', '<code>undefined</code>', 'Called on every request before routing. Return <code>false</code> to short-circuit Pulse handling.'],
           ['<code>onError</code>', '<code>function</code>', '<code>undefined</code>', 'Called on unhandled errors. Receives <code>(err, req, res)</code>. See <a href="/error-pages">Error Pages</a>.'],
         ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.18.2
+0.19.0

package/src/agent/guide-routing.md

@@ -147,6 +147,25 @@ export default {
 - **Every site should have one** — without it, visitors to a bad URL get the framework's unbranded default 404.
 - 500 errors are customised via `createServer`'s `onError` option, not a spec.
 
+## Declarative redirects (legacy URLs)
+
+When migrating an existing site to Pulse, preserve the old URLs with the `redirects` map in `pulse.config.js` / `createServer` — never let legacy URLs 404:
+
+```js
+export default {
+  redirects: {
+    '/old-blog/:slug': '/blog/:slug',             // 301 — :params carry over
+    '/pricing-2024':   '/pricing',                // 301
+    '/promo':          { to: '/sale', status: 302 },  // temporary
+    '/moved/:slug':    'https://other.com/:slug', // absolute targets for domain moves
+  },
+}
+```
+
+- **301 by default** (permanent — search engines transfer ranking). Use `{ to, status }` for 302/307/308.
+- Query strings are preserved; checked before route matching (GET/HEAD only); validated at startup — bad entries fail the boot.
+- A redirect source that equals a registered route shadows the page (startup warning) — that is sometimes intentional (retiring a page), usually a mistake.
+
 ## Sitemap & robots.txt
 
 Enable in `pulse.config.js` / `createServer` — the framework serves `/sitemap.xml` and `/robots.txt` generated from the registered routes:

package/src/server/index.js

@@ -551,6 +551,9 @@ export async function createServer(entries, options = {}) {
                                     // spec.sitemap = async () => ['/blog/a', ...]
     robots         = null,          // robots.txt content when sitemap is enabled:
                                     // null = auto-generate, false = disable, string = serve verbatim
+    redirects      = null,          // declarative redirect map for legacy URLs (SEO-safe migrations):
+                                    // { '/old-blog/:slug': '/blog/:slug',           — 301 (default)
+                                    //   '/promo': { to: '/pricing', status: 302 } } — custom status
     onError        = (err, req, res) => defaultErrorHandler(err, req, res, dev),
     onRequest,
     agentMode      = false,        // show agent-active indicator in banner
@@ -619,6 +622,16 @@ export async function createServer(entries, options = {}) {
   // tied to a cookie, so a restart only means in-flight forms re-render once.
   const csrfSecret = secret || crypto.randomBytes(32).toString('hex')
 
+  // Redirects — compile the declarative map once at startup (throws on bad
+  // entries) and warn when a redirect source shadows a registered page route.
+  const redirectTable = compileRedirects(redirects)
+  if (redirectTable.length > 0 && !quiet) {
+    const shadowed = redirectTable.filter(r => specs.some(s => s.route === r.source))
+    if (shadowed.length > 0) {
+      console.log(`  ⚠ redirects: ${shadowed.map(r => r.source).join(', ')} also match registered page routes — the redirect wins and the page is unreachable`)
+    }
+  }
+
   // Sitemap — track the live spec list (updated on hot reload) and surface a
   // startup hint for dynamic routes that can't be enumerated automatically.
   const sitemapEnabled = !!sitemap
@@ -727,6 +740,27 @@ export async function createServer(entries, options = {}) {
         // 'allow' — no redirect
       }
 
+      // Declarative redirects — checked before route matching so legacy URLs
+      // redirect even when a spec also matches (a startup warning flags that).
+      // GET/HEAD only: redirecting a POST silently drops the body.
+      if (redirectTable.length > 0 && (req.method === 'GET' || req.method === 'HEAD')) {
+        for (const r of redirectTable) {
+          const m = pathname.match(r.pattern)
+          if (!m) continue
+          // Substitute captured :params into the target, keeping their original
+          // percent-encoding intact (no decode/re-encode round trip). Longest
+          // names first so :s never clobbers part of :slug.
+          let target = r.target
+          ;[...r.params.entries()]
+            .sort((a, b) => b[1].length - a[1].length)
+            .forEach(([i, name]) => { target = target.split(`:${name}`).join(m[i + 1]) })
+          if (target === pathname) break  // self-redirect — fall through to normal routing
+          res.writeHead(r.status, { Location: target + (url.search || ''), ...SECURITY_HEADERS, ...httpsHeaders(req) })
+          res.end()
+          return
+        }
+      }
+
       // Match route
       let match          = matchRoute(router, pathname)
       let responseStatus = 200
@@ -1724,6 +1758,47 @@ function escHtml(str) {
     .replace(/'/g, ''')
 }
 
+/**
+ * Compile the declarative redirects map into matchable entries.
+ * Validates at startup — a bad entry throws before the server accepts connections.
+ *
+ * Sources are route patterns ('/old/:slug'); targets are paths or absolute URLs
+ * and may reference the same :params. Values are a target string (301) or
+ * { to, status } for 302/307/308.
+ *
+ * @param {Record<string, string | { to: string, status?: number }> | null} redirects
+ * @returns {Array<{ source: string, pattern: RegExp, params: string[], target: string, status: number }>}
+ */
+function compileRedirects(redirects) {
+  if (!redirects) return []
+  const VALID_STATUS = new Set([301, 302, 307, 308])
+  const table = []
+
+  for (const [source, value] of Object.entries(redirects)) {
+    if (!source.startsWith('/')) {
+      throw new Error(`Invalid redirect source "${source}" — sources must start with "/" (e.g. '/old-blog/:slug')`)
+    }
+    const target = typeof value === 'string' ? value : value?.to
+    const status = typeof value === 'string' ? 301 : (value?.status ?? 301)
+    if (typeof target !== 'string' || !(target.startsWith('/') || /^https?:\/\//.test(target))) {
+      throw new Error(`Invalid redirect target for "${source}" — targets must start with "/" or be an absolute http(s) URL`)
+    }
+    if (!VALID_STATUS.has(status)) {
+      throw new Error(`Invalid redirect status ${status} for "${source}" — use 301, 302, 307, or 308`)
+    }
+    // Targets may only reference params that the source captures
+    const { pattern, params } = routeToRegex(source)
+    const targetParams = [...target.matchAll(/:([a-zA-Z][\w-]*)/g)].map(m => m[1])
+    const unknown = targetParams.filter(p => !params.includes(p))
+    if (unknown.length > 0) {
+      throw new Error(`Redirect target for "${source}" references :${unknown[0]} which the source does not capture`)
+    }
+    table.push({ source, pattern, params, target, status })
+  }
+
+  return table
+}
+
 /**
  * Collect sitemap entries from the registered specs.
  *

package/src/server/server.test.js

@@ -1446,6 +1446,92 @@ await test('submit pages are excluded from the in-process page cache', async ()
 
 // ---------------------------------------------------------------------------
 
+console.log('\nDeclarative redirects\n')
+
+await test('plain redirect responds 301 with Location', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/old-hello': '/hello' } }, async (port) => {
+    const { status, headers } = await get(port, '/old-hello')
+    assert(status === 301, `Expected 301, got ${status}`)
+    assert(headers.location === '/hello', `Expected /hello, got ${headers.location}`)
+  })
+})
+
+await test(':params are substituted into the target', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/old-blog/:slug': '/blog/:slug' } }, async (port) => {
+    const { status, headers } = await get(port, '/old-blog/my-post')
+    assert(status === 301)
+    assert(headers.location === '/blog/my-post', `Expected /blog/my-post, got ${headers.location}`)
+  })
+})
+
+await test('percent-encoded params keep their encoding through substitution', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/old/:slug': '/new/:slug' } }, async (port) => {
+    const { headers } = await get(port, '/old/caf%C3%A9')
+    assert(headers.location === '/new/caf%C3%A9', `Encoding mangled: ${headers.location}`)
+  })
+})
+
+await test('query string is preserved on redirect', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/old-hello': '/hello' } }, async (port) => {
+    const { headers } = await get(port, '/old-hello?utm=x&page=2')
+    assert(headers.location === '/hello?utm=x&page=2', `Query lost: ${headers.location}`)
+  })
+})
+
+await test('custom status via { to, status }', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/promo': { to: '/hello', status: 302 } } }, async (port) => {
+    const { status, headers } = await get(port, '/promo')
+    assert(status === 302, `Expected 302, got ${status}`)
+    assert(headers.location === '/hello')
+  })
+})
+
+await test('absolute URL targets work (domain moves)', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/moved/:slug': 'https://newsite.com/blog/:slug' } }, async (port) => {
+    const { headers } = await get(port, '/moved/post-1')
+    assert(headers.location === 'https://newsite.com/blog/post-1', `Got ${headers.location}`)
+  })
+})
+
+await test('redirect wins over a registered route at the same path', async () => {
+  await withServer([helloSpec], { stream: false, quiet: true, redirects: { '/hello': '/elsewhere' } }, async (port) => {
+    const { status, headers } = await get(port, '/hello')
+    assert(status === 301 && headers.location === '/elsewhere', `Expected redirect to win, got ${status}`)
+  })
+})
+
+await test('POST is not redirected', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/old-api': '/hello' } }, async (port) => {
+    const { status } = await requestFull(port, 'POST', '/old-api', {})
+    assert(status === 404, `Expected POST to skip redirects (404), got ${status}`)
+  })
+})
+
+await test('self-redirects fall through to normal routing instead of looping', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/hello/:x': '/hello/:x' } }, async (port) => {
+    const { status } = await get(port, '/hello/abc')
+    assert(status === 404, `Expected fall-through to routing (404 here), got ${status}`)
+    const ok = await get(port, '/hello')
+    assert(ok.status === 200, 'Unrelated routes unaffected')
+  })
+})
+
+await test('invalid redirect config throws at startup', async () => {
+  const cases = [
+    { redirects: { 'no-slash': '/x' } },
+    { redirects: { '/x': 'no-slash-target' } },
+    { redirects: { '/x': { to: '/y', status: 418 } } },
+    { redirects: { '/x': '/y/:missing' } },
+  ]
+  for (const opts of cases) {
+    let threw = false
+    try { await createServer([helloSpec], { ...opts, port: nextPort++, quiet: true }) } catch { threw = true }
+    assert(threw, `Expected startup throw for ${JSON.stringify(opts.redirects)}`)
+  }
+})
+
+// ---------------------------------------------------------------------------
+
 console.log('\nSitemap + robots.txt\n')
 
 const aboutSpec   = { route: '/about', view: () => '<main id="main-content">About</main>' }

package/types/server.d.ts

@@ -94,6 +94,20 @@ export interface ServerOptions {
    */
   robots?: string | false | null
 
+  /**
+   * Declarative redirect map for legacy URLs (SEO-safe migrations).
+   * Sources are route patterns; targets are paths or absolute URLs and may
+   * reference the same :params. A string target redirects with 301; use
+   * { to, status } for 302/307/308. Checked before route matching (GET/HEAD
+   * only); the query string is preserved. Validated at startup.
+   * @example
+   * redirects: {
+   *   '/old-blog/:slug': '/blog/:slug',
+   *   '/promo':          { to: '/pricing', status: 302 },
+   * }
+   */
+  redirects?: Record<string, string | { to: string; status?: 301 | 302 | 307 | 308 }> | null
+
   /**
    * Extra CSP sources to merge into the framework's default Content-Security-Policy.
    * Use this to allow external stylesheets, fonts, or API origins.