Address various additional site nits discovered in testing (#1576)

Author: anthonyiscoding

.github/workflows/deploy-website.yml

@@ -37,6 +37,19 @@ jobs:
         with:
           ref: ${{ inputs.ref || github.ref }}
 
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Generate llms.txt and AGENTS.md
+        run: pnpm --filter iii-website build
+
       - name: Configure AWS credentials (GitHub OIDC)
         uses: aws-actions/configure-aws-credentials@v4
         with:
@@ -49,6 +62,8 @@ jobs:
             --delete \
             --cache-control "public,max-age=31536000,immutable" \
             --exclude "*.html" \
+            --exclude "llms.txt" \
+            --exclude "AGENTS.md" \
             --exclude "node_modules/*" \
             --exclude "package.json" \
             --exclude "package-lock.json" \
@@ -57,13 +72,15 @@ jobs:
             --exclude "README.md" \
             --exclude "vercel.json"
 
-      - name: Sync HTML (no cache, must revalidate)
+      - name: Sync HTML and AI snapshot (no cache, must revalidate)
         run: |
           aws s3 sync website/ "s3://${{ vars.S3_BUCKET }}/" \
             --delete \
             --cache-control "public,max-age=0,must-revalidate" \
             --exclude "*" \
-            --include "*.html"
+            --include "*.html" \
+            --include "llms.txt" \
+            --include "AGENTS.md"
 
       - name: Create CloudFront invalidation
         id: invalidation

infra/terraform/website/cloudfront_functions/redirects.js

@@ -8,29 +8,73 @@ function redirect(location) {
       location: { value: location },
       'cache-control': { value: 'public, max-age=3600' },
     },
+  };
+}
+
+// CloudFront Functions deliver request.querystring as
+//   { key: { value: string, multiValue?: [{ value: string }, ...] } }
+// where repeated params spill into multiValue. We re-encode and rejoin so the
+// host-redirect path below preserves the original query (otherwise `?a=1&a=2`
+// would silently drop on the 301).
+function serializeQuerystring(qs) {
+  if (!qs) return '';
+  var parts = [];
+  for (var key in qs) {
+    if (!Object.prototype.hasOwnProperty.call(qs, key)) continue;
+    var entry = qs[key];
+    if (!entry) continue;
+    var encodedKey = encodeURIComponent(key);
+    var primary = entry.value == null ? '' : entry.value;
+    parts.push(encodedKey + '=' + encodeURIComponent(primary));
+    if (entry.multiValue && entry.multiValue.length) {
+      for (var i = 0; i < entry.multiValue.length; i++) {
+        var extra = entry.multiValue[i];
+        var extraValue = extra && extra.value != null ? extra.value : '';
+        parts.push(encodedKey + '=' + encodeURIComponent(extraValue));
+      }
+    }
   }
+  return parts.length ? '?' + parts.join('&') : '';
 }
 
 // biome-ignore lint/correctness/noUnusedVariables: CloudFront Function entry point
 // biome-ignore lint/complexity/useOptionalChain: cloudfront-js-2.0 does NOT support optional chaining
 function handler(event) {
-  var request = event.request
-  var uri = request.uri
-  var host = request.headers && request.headers.host ? request.headers.host.value : undefined
+  var request = event.request;
+  var uri = request.uri;
+  var host =
+    request.headers && request.headers.host
+      ? request.headers.host.value
+      : undefined;
 
-  if (host === 'www.iii.dev') return redirect(`https://iii.dev${uri}`)
+  if (host === 'www.iii.dev') {
+    return redirect(
+      `https://iii.dev${uri}${serializeQuerystring(request.querystring)}`,
+    );
+  }
+
+  if (uri.indexOf('/.well-known/') === 0) return request;
 
-  if (uri.indexOf('/.well-known/') === 0) return request
+  // Pretty URLs → matching *.html objects in S3 (Option A). Add a key when you
+  // ship a new top-level page as `pagename.html`.
+  var htmlPretty = {
+    '/manifesto': '/manifesto.html',
+  };
+  var htmlTarget = htmlPretty[uri];
+  if (htmlTarget !== undefined) {
+    request.uri = htmlTarget;
+    return request;
+  }
 
   // SPA fallback: extensionless path not ending in /
   if (uri !== '/' && uri.charAt(uri.length - 1) !== '/') {
-    const lastSlash = uri.lastIndexOf('/')
-    const lastSegment = uri.substring(lastSlash + 1)
+    const lastSlash = uri.lastIndexOf('/');
+    const lastSegment = uri.substring(lastSlash + 1);
     if (lastSegment.indexOf('.') === -1) {
-      request.uri = '/index.html'
-      return request
+      request.uri = '/index.html';
+      return request;
     }
   }
 
-  return request
+  return request;
 }

infra/terraform/website/cloudfront_functions/redirects.test.js

@@ -9,15 +9,15 @@ const path = require('node:path')
 const source = fs.readFileSync(path.join(__dirname, 'redirects.js'), 'utf8')
 const handler = new Function(source + '\nreturn handler;')()
 
-function buildEvent(uri, host) {
+function buildEvent(uri, host, querystring) {
   return {
     version: '1.0',
     context: {},
     viewer: {},
     request: {
       method: 'GET',
       uri: uri,
-      querystring: {},
+      querystring: querystring || {},
       headers: host ? { host: { value: host } } : {},
       cookies: {},
     },
@@ -57,7 +57,7 @@ test('/docsfoo → NOT redirected (not under /docs/)', () => {
   assert.equal(result.uri, '/index.html')
 })
 
-test('/llms.txt → pass through unchanged (matches current 404 behavior)', () => {
+test('/llms.txt → pass through unchanged (static file)', () => {
   const result = handler(buildEvent('/llms.txt', 'iii.dev'))
   assert.ok(!isRedirect(result))
   assert.equal(result.uri, '/llms.txt')
@@ -81,6 +81,58 @@ test('www.iii.dev/docs/foo → 301 https://iii.dev/docs/foo', () => {
   assert.equal(locationOf(result), 'https://iii.dev/docs/foo')
 })
 
+test('www.iii.dev preserves querystring with multiValue and empty params', () => {
+  // Mirrors the CloudFront Functions querystring shape: repeated keys spill into
+  // multiValue, value-less keys arrive as empty strings, and special chars must
+  // be re-encoded.
+  const result = handler(
+    buildEvent('/some/page', 'www.iii.dev', {
+      a: { value: '1', multiValue: [{ value: '2' }] },
+      empty: { value: '' },
+      ref: { value: 'hello world' },
+    }),
+  )
+  assert.ok(isRedirect(result))
+  assert.equal(
+    locationOf(result),
+    'https://iii.dev/some/page?a=1&a=2&empty=&ref=hello%20world',
+  )
+})
+
+test('www.iii.dev with no querystring → no trailing ?', () => {
+  const result = handler(buildEvent('/some/page', 'www.iii.dev', {}))
+  assert.ok(isRedirect(result))
+  assert.equal(locationOf(result), 'https://iii.dev/some/page')
+})
+
+test('www.iii.dev percent-encodes reserved chars in keys and values', () => {
+  // Values containing &, =, #, + would otherwise corrupt the redirect target
+  // (& splits params, # ends the URL into a fragment, + flips to space on parse,
+  // = confuses some clients). Keys with spaces must also be encoded.
+  const result = handler(
+    buildEvent('/p', 'www.iii.dev', {
+      'weird key': { value: 'a&b=c+d#e' },
+    }),
+  )
+  assert.ok(isRedirect(result))
+  assert.equal(
+    locationOf(result),
+    'https://iii.dev/p?weird%20key=a%26b%3Dc%2Bd%23e',
+  )
+})
+
+test('SPA fallback preserves querystring on the request object (no rewrite)', () => {
+  // The handler mutates request.uri but returns the same request object, so
+  // CloudFront forwards the original querystring untouched. Pin the no-op so
+  // a future refactor doesn't accidentally clear it.
+  const qs = { utm_source: { value: 'twitter' }, ref: { value: 'launch' } }
+  const event = buildEvent('/some/route', 'iii.dev', qs)
+  const result = handler(event)
+  assert.ok(!isRedirect(result))
+  assert.equal(result.uri, '/index.html')
+  assert.equal(result.querystring, qs)
+})
+
 test('/ (root) → pass through unchanged', () => {
   const result = handler(buildEvent('/', 'iii.dev'))
   assert.ok(!isRedirect(result))
@@ -93,10 +145,16 @@ test('/some/client/route → rewrite uri to /index.html', () => {
   assert.equal(result.uri, '/index.html')
 })
 
-test('/manifesto → rewrite uri to /index.html', () => {
+test('/manifesto → rewrite uri to /manifesto.html (flat HTML, Option A)', () => {
   const result = handler(buildEvent('/manifesto', 'iii.dev'))
   assert.ok(!isRedirect(result))
-  assert.equal(result.uri, '/index.html')
+  assert.equal(result.uri, '/manifesto.html')
+})
+
+test('/AGENTS.md → pass through unchanged', () => {
+  const result = handler(buildEvent('/AGENTS.md', 'iii.dev'))
+  assert.ok(!isRedirect(result))
+  assert.equal(result.uri, '/AGENTS.md')
 })
 
 test('/foo/ trailing slash → pass through unchanged (no SPA rewrite)', () => {
@@ -111,10 +169,10 @@ test('/missing.jpg → pass through unchanged (S3 returns 404)', () => {
   assert.equal(result.uri, '/missing.jpg')
 })
 
-test('/ai/index.html → pass through unchanged', () => {
-  const result = handler(buildEvent('/ai/index.html', 'iii.dev'))
+test('/ai → SPA fallback to /index.html', () => {
+  const result = handler(buildEvent('/ai', 'iii.dev'))
   assert.ok(!isRedirect(result))
-  assert.equal(result.uri, '/ai/index.html')
+  assert.equal(result.uri, '/index.html')
 })
 
 test('/assets/main.abc123.js → pass through unchanged', () => {