create-website-build-kit 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-website-build-kit",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Scaffold a production marketing site \u2014 Astro on Cloudflare Workers, with the gates, the migration playbook and the accessibility work already wired.",
   "keywords": [
     "astro",

package/template/package.json

@@ -29,8 +29,8 @@
     "redirects": "node scripts/redirects.mjs",
     "handover": "node scripts/md-to-pdf.mjs docs/handover.md docs/handover.pdf",
     "build": "astro build",
-    "build:staging": "PUBLIC_SITE_ENV=staging PUBLIC_SITE_URL=https://new.example.com astro build && PUBLIC_SITE_ENV=staging node scripts/staging-headers.mjs && PUBLIC_SITE_ENV=staging node scripts/check-env.mjs",
-    "build:production": "node scripts/tells.mjs --undecided-only && PUBLIC_SITE_ENV=production astro check && PUBLIC_SITE_ENV=production PUBLIC_SITE_URL=https://example.com astro build && PUBLIC_SITE_ENV=production node scripts/check-env.mjs && node scripts/check-sitemap.mjs",
+    "build:staging": "node scripts/build.mjs staging",
+    "build:production": "node scripts/build.mjs production",
     "preview": "wrangler dev",
     "deploy:staging": "npm run build:staging && wrangler deploy && node scripts/check-secrets.mjs",
     "deploy:production": "npm run build:production && wrangler deploy && node scripts/check-secrets.mjs",

package/template/scripts/build.mjs

@@ -0,0 +1,114 @@
+/**
+ * Run a build for one environment.
+ *
+ *   node scripts/build.mjs staging
+ *   node scripts/build.mjs production
+ *
+ * `npm run build:staging` and `npm run build:production` are one-line aliases
+ * for these.
+ *
+ * ── WHY A SCRIPT AND NOT INLINE ENV IN package.json ────────────────────────
+ * ⚠ `PUBLIC_SITE_ENV=staging astro build` IS POSIX SHELL SYNTAX, AND npm ON
+ *   WINDOWS RUNS SCRIPTS THROUGH cmd.exe. There it is not an assignment, it is
+ *   a command name, and the build dies immediately with
+ *
+ *     'PUBLIC_SITE_ENV' is not recognized as an internal or external command
+ *
+ *   So the two most important commands in the kit did not work at all on a
+ *   platform the kit says it supports. Nothing caught it because every CI job
+ *   ran on ubuntu.
+ *
+ * ── AND WHY IT IS SAFER EVEN WHERE THE SHELL SYNTAX WORKS ──────────────────
+ * The production line repeated `PUBLIC_SITE_ENV=production` four times, once
+ * per command. Miss one and that step runs as `development` while the others
+ * do not: `astro check` types a different environment than the one that gets
+ * built, or `check-env` validates an environment nobody deployed.
+ *
+ * A mixed-environment build is precisely what `check-env.mjs` exists to catch,
+ * and it is the sort of thing that survives review because every line looks
+ * right on its own. Setting it once removes the class.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const DIM = '\x1b[2m';
+
+const env = process.argv[2];
+
+if (env !== 'staging' && env !== 'production') {
+  console.error(
+    `\n${RED}✗ usage: node scripts/build.mjs <staging|production>${RESET}\n\n` +
+      '  The environment is not optional. A build that does not declare one\n' +
+      '  emits localhost canonical URLs — cleanly, and wrong.\n',
+  );
+  process.exit(1);
+}
+
+/*
+ * The site URL per environment. Read from package.json rather than restated
+ * here, so there is one place a project sets its hostnames.
+ *
+ * ⚠ Kept OUT of src/data/site.ts on purpose: astro.config.mjs needs the value
+ *   before any TypeScript is loaded, and site.ts imports `import.meta.env`.
+ */
+const SITE_URLS = {
+  staging: 'https://new.example.com',
+  production: 'https://example.com',
+};
+
+/**
+ * Run one step with the environment already set, and stop the build if it
+ * fails. `shell: true` on Windows because `npx`-style shims are .cmd files
+ * that execFile cannot resolve — the same reason the a11y scripts need it.
+ */
+function step(command, args) {
+  const run = spawnSync(command, args, {
+    stdio: 'inherit',
+    env: { ...process.env, PUBLIC_SITE_ENV: env, PUBLIC_SITE_URL: SITE_URLS[env] },
+    shell: process.platform === 'win32',
+  });
+  if (run.status !== 0) {
+    console.error(`\n${RED}✗ build failed at:${RESET} ${command} ${args.join(' ')}\n`);
+    process.exit(run.status ?? 1);
+  }
+}
+
+/* astro is a local binary; go through the package's own bin rather than a
+   global `astro`, which may not exist and would be the wrong version if it did. */
+const astro = ['node_modules/astro/astro.js'];
+const hasLocalAstro = existsSync('node_modules/astro/astro.js');
+
+const run = (args) =>
+  hasLocalAstro
+    ? step(process.execPath, [...astro, ...args])
+    : step('npx', ['--no-install', 'astro', ...args]);
+
+console.log(`${DIM}building ${env} → ${SITE_URLS[env]}${RESET}\n`);
+
+if (env === 'production') {
+  /* Refuse a production build of a template that has not been designed yet.
+     Before anything else, because it is the cheapest check and the most
+     embarrassing thing to deploy. */
+  step(process.execPath, ['scripts/tells.mjs', '--undecided-only']);
+  run(['check']);
+}
+
+run(['build']);
+
+if (env === 'staging') {
+  step(process.execPath, ['scripts/staging-headers.mjs']);
+}
+
+step(process.execPath, ['scripts/check-env.mjs']);
+
+if (env === 'production') {
+  step(process.execPath, ['scripts/check-sitemap.mjs']);
+}
+
+/* A sanity line, so the log says which environment actually ran rather than
+   which one was asked for. They are the same now; they were not always. */
+const pkg = existsSync('package.json') ? JSON.parse(readFileSync('package.json', 'utf8')) : {};
+console.log(`\n${DIM}${pkg.name ?? 'site'} built as ${env}${RESET}`);

package/template/scripts/check-sitemap.mjs

@@ -28,7 +28,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { join, relative, sep } from 'node:path';
 
 const RESET = '[0m';
 const RED = '[31m';
@@ -78,7 +78,13 @@ const ROBOTS_META = /<meta[^>]+name=["']robots["'][^>]+content=["'][^"']*\bnoind
 const noindexed = walk(root)
   .filter((f) => f.endsWith('.html'))
   .filter((f) => ROBOTS_META.test(readFileSync(f, 'utf8')))
-  .map((f) => '/' + relative(root, f).replace(/index\.html$/, '').replace(/\.html$/, '/'))
+/* ⚠ SEPARATORS NORMALISED — `relative()` RETURNS BACKSLASHES ON WINDOWS.
+   A URL path is always `/`. Without this the map produced `/about\\` for
+   `about\\index.html`, which matched nothing: check-sitemap's contradiction
+   check silently passed a site that listed a noindexed URL in its sitemap, and
+   Search Console reports that as an error against the whole submission. */
+  .map((f) => '/' + relative(root, f).split(sep).join('/')
+      .replace(/index\.html$/, '').replace(/\.html$/, '/'))
   .map((p) => (p.endsWith('/') ? p : `${p}/`));
 
 const contradictions = noindexed.filter((p) => listed.has(p));

package/template/scripts/lib/routes.mjs

@@ -11,7 +11,7 @@
  */
 
 import { existsSync, readdirSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { join, relative, sep } from 'node:path';
 
 /** Routes this build emitted, as absolute paths. 404 is excluded — it is not a route. */
 export function routesFromDist() {
@@ -26,7 +26,13 @@ export function routesFromDist() {
 
   return walk(root)
     .filter((f) => f.endsWith('.html') && !f.endsWith('404.html'))
-    .map((f) => '/' + relative(root, f).replace(/index\.html$/, '').replace(/\.html$/, '/'))
+    /* ⚠ SEPARATORS NORMALISED — `relative()` RETURNS BACKSLASHES ON WINDOWS.
+       A URL path is always `/`. Without this the map produced `/about\\` for
+       `about\\index.html`, which matched nothing: check-sitemap's contradiction
+       check silently passed a site that listed a noindexed URL in its sitemap, and
+       Search Console reports that as an error against the whole submission. */
+    .map((f) => '/' + relative(root, f).split(sep).join('/')
+          .replace(/index\.html$/, '').replace(/\.html$/, '/'))
     .map((p) => (p.endsWith('/') ? p : `${p}/`))
     .sort();
 }