@cparkerwebm/webmonterey 1.2.0 → 1.3.0

package/src/includes/webmonterey/config.test.ts

@@ -3,9 +3,11 @@ import assert from 'node:assert/strict';
 import {
   APP_DIR,
   isConfigured,
+  isPreviewBuild,
   isStagingDeployment,
   isValidTimeZone,
   PLACEHOLDER,
+  previewReason,
   resolveAppPath,
   resolveDisplayName,
   workerFirstPaths,
@@ -92,3 +94,52 @@ test('shortName falls back to the display name when unset', () => {
   assert.equal(isConfigured('FoML'), true);
   assert.equal(isConfigured(''), false);
 });
+
+/* --- preview builds ------------------------------------------------------ */
+
+test('a staging site is a preview with no branch at all - the laptop build', () => {
+  assert.equal(isPreviewBuild({ environment: 'staging', branch: null }), true);
+  assert.equal(previewReason({ environment: 'staging', branch: null }), 'staging');
+});
+
+test('a staging site is a preview on main - the case that was crawlable', () => {
+  /* autire.webmonterey.workers.dev: main on Workers Builds, environment staging, and indexable
+   * because only a non-production BRANCH used to be a preview. */
+  assert.equal(isPreviewBuild({ environment: 'staging', branch: 'main' }), true);
+  assert.equal(previewReason({ environment: 'staging', branch: 'main' }), 'staging');
+});
+
+test('a production site with no branch is production output', () => {
+  assert.equal(isPreviewBuild({ environment: 'production', branch: null }), false);
+  assert.equal(previewReason({ environment: 'production', branch: null }), null);
+});
+
+test('a production site on main is production output', () => {
+  assert.equal(isPreviewBuild({ environment: 'production', branch: 'main' }), false);
+});
+
+test('a feature branch of a production site is still a preview', () => {
+  /* webmonterey.json is committed, so the branch inherits production from main. The branch rule
+   * is what keeps a launched site's review links out of the index. */
+  assert.equal(isPreviewBuild({ environment: 'production', branch: 'feature/x' }), true);
+  assert.equal(previewReason({ environment: 'production', branch: 'feature/x' }), 'branch');
+});
+
+test('productionBranch renames which branch is production', () => {
+  const on = { environment: 'production', productionBranch: 'release' } as const;
+  assert.equal(isPreviewBuild({ ...on, branch: 'release' }), false);
+  assert.equal(isPreviewBuild({ ...on, branch: 'main' }), true);
+});
+
+test('staging wins over the production branch, whatever it is called', () => {
+  assert.equal(
+    previewReason({ environment: 'staging', branch: 'release', productionBranch: 'release' }),
+    'staging',
+  );
+});
+
+test('an unset environment is production, so a site predating the field builds as before', () => {
+  assert.equal(isPreviewBuild({ environment: undefined, branch: null }), false);
+  assert.equal(isPreviewBuild({ environment: undefined, branch: 'main' }), false);
+  assert.equal(isPreviewBuild({ environment: undefined, branch: 'feature/x' }), true);
+});

package/src/includes/webmonterey/config.ts

@@ -125,6 +125,14 @@ export interface SiteConfig {
    * Read it anywhere via `environment`, `isStaging` and `isProduction` from webmonterey/site.
    * The first consumer is transactional email, which redirects every recipient to `stagingEmail`
    * on a staging deployment rather than mailing the client's real contacts from a preview.
+   *
+   * THE SECOND CONSUMER IS INDEXABILITY. A staging site is a PREVIEW BUILD on every hostname and
+   * in every build - laptop, `main` on Workers Builds, anywhere: every page is noindex with no
+   * canonical, there is no sitemap, robots.txt disallows everything, and Google Tag Manager does
+   * not load. Until this switch existed a site that had not launched was crawlable on its
+   * workers.dev URL the moment `main` deployed, because only a non-production BRANCH was a
+   * preview. See `isPreviewBuild`. Flipping this to production is therefore what makes a site
+   * indexable, which is why /webm:launch does it only once the custom domain is live.
    */
   environment?: 'production' | 'staging';
 
@@ -344,3 +352,44 @@ export function isStagingDeployment(
   /* Match the label, not a substring: a client domain ending "notworkers.dev" is not a preview. */
   return Boolean(hostname && /(^|\.)workers\.dev$/i.test(hostname));
 }
+
+/** Which signal made a build a preview, or null for production output. */
+export type PreviewReason = 'staging' | 'branch' | null;
+
+/**
+ * Why this build is a preview - noindex on every page, no canonical, no sitemap, robots.txt
+ * disallowing everything, no analytics - or null when it is production output.
+ *
+ * TWO INDEPENDENT SIGNALS, for the same reason `isStagingDeployment` has two.
+ *
+ * `environment` is what the deployment is FOR. A site that has not launched says `staging`, and
+ * a site that has not launched must not be indexable ANYWHERE: not on a feature branch, not on
+ * `main`, not from a laptop. Before this signal existed only a non-production branch was a
+ * preview, so `main` on Workers Builds was production output for every site that had not gone
+ * live yet - indexable pages with a canonical, a sitemap and `Allow: /` on a public workers.dev
+ * hostname. autire.webmonterey.workers.dev was crawlable that way.
+ *
+ * The branch covers the opposite case: webmonterey.json is committed, so a feature branch of a
+ * LAUNCHED site inherits `production` from main and would build indexable pages under a review
+ * URL. Workers Builds injects WORKERS_CI_BRANCH; anything other than the production branch is a
+ * preview whatever the config says.
+ *
+ * An unset environment is production, as it is everywhere else - see SiteConfig.environment for
+ * why that default is the safe one - so a site predating the field builds exactly as before.
+ * `branch` is null when nothing injected one, which is every laptop build.
+ */
+export function previewReason(input: {
+  environment: SiteConfig['environment'] | undefined;
+  branch: string | null | undefined;
+  productionBranch?: string;
+}): PreviewReason {
+  if (input.environment === 'staging') return 'staging';
+  const branch = input.branch ?? null;
+  if (branch !== null && branch !== (input.productionBranch ?? 'main')) return 'branch';
+  return null;
+}
+
+/** Whether this build is a preview. `previewReason` says which signal decided it. */
+export function isPreviewBuild(input: Parameters<typeof previewReason>[0]): boolean {
+  return previewReason(input) !== null;
+}

package/src/integration/index.ts

@@ -31,7 +31,12 @@ import { fileURLToPath } from 'node:url';
 import { compileToCss } from '../design/compile.ts';
 import { imageSize } from './image-size.ts';
 import { loadForms, loadSiteFiles, resolveSiteUrl } from './config.ts';
-import { APP_DIR, appEnabled, resolveAppPath } from '../includes/webmonterey/config.ts';
+import {
+  APP_DIR,
+  appEnabled,
+  previewReason,
+  resolveAppPath,
+} from '../includes/webmonterey/config.ts';
 
 export interface WebmontereyOptions {
   /**
@@ -79,10 +84,14 @@ export interface WebmontereyOptions {
   /**
    * The branch Workers Builds deploys to production. Default `main`.
    *
-   * Every other branch is a PREVIEW, and a preview build is different on purpose: every page is
-   * noindex, there is no sitemap, robots.txt disallows everything, and Google Tag Manager does
-   * not load - so a client's review link can never be indexed, and clicking around it never
-   * lands in their analytics. Detected from WORKERS_CI_BRANCH, which Workers Builds injects.
+   * Every other branch is a PREVIEW - and so is every build, on any branch and from any machine,
+   * of a site whose webmonterey.json says `environment: "staging"`. A preview build is different
+   * on purpose: every page is noindex with no canonical, there is no sitemap, robots.txt
+   * disallows everything, and Google Tag Manager does not load - so a client's review link can
+   * never be indexed, a site that has not launched cannot be indexed before it exists, and
+   * clicking around either never lands in their analytics. The branch comes from
+   * WORKERS_CI_BRANCH, which Workers Builds injects; the decision is `isPreviewBuild` in
+   * includes/webmonterey/config.ts.
    */
   productionBranch?: string;
 }
@@ -133,14 +142,29 @@ export default function webmonterey(options: WebmontereyOptions = {}): AstroInte
         const appPath = resolveAppPath(files.site);
 
         /*
-         * BRANCH PREVIEW OR PRODUCTION. Workers Builds injects WORKERS_CI_BRANCH; anything that
-         * is not the production branch is a preview. A local build has no branch and is treated
-         * as production, which is what `npm run preview` and the e2e need. See the option.
+         * PREVIEW OR PRODUCTION, decided in one place - previewReason - from two signals. A site
+         * whose webmonterey.json says `environment: "staging"` is a preview in every build,
+         * whatever the branch and whatever the machine; and on a launched site any Workers
+         * Builds branch other than the production one is a preview too. A local build of a
+         * production site has no branch and is production output, which is what
+         * `npm run preview` and the e2e need. See the option, and the function.
          */
         const branch = process.env.WORKERS_CI_BRANCH ?? null;
-        const preview = branch !== null && branch !== (options.productionBranch ?? 'main');
-        if (preview) {
-          logger.info(`branch "${branch}" is a preview: noindex, no sitemap, no analytics`);
+        const productionBranch = options.productionBranch ?? 'main';
+        const reason = previewReason({
+          environment: files.site.environment,
+          branch,
+          productionBranch,
+        });
+        const preview = reason !== null;
+        if (reason === 'staging') {
+          logger.info(
+            'environment is "staging" in webmonterey.json: a preview build - noindex, no sitemap, no analytics',
+          );
+        } else if (reason === 'branch') {
+          logger.info(
+            `branch "${branch}" is not ${productionBranch}: a preview build - noindex, no sitemap, no analytics`,
+          );
         }
 
         /*
@@ -255,7 +279,7 @@ export default function webmonterey(options: WebmontereyOptions = {}): AstroInte
                 load(id: string) {
                   switch (id) {
                     case resolved(VIRTUAL.build):
-                      return `export default ${JSON.stringify({ preview, branch })};`;
+                      return `export default ${JSON.stringify({ preview, reason, branch })};`;
                     case resolved(VIRTUAL.site):
                       return `export default ${JSON.stringify(files.site)};`;
                     case resolved(VIRTUAL.design):

package/src/integration/virtual.d.ts

@@ -5,11 +5,14 @@
  * a package cannot import relatively - see includes/webmonterey/config.ts.
  */
 /**
- * What this build is FOR. `preview` is true on any Workers Builds branch other than the
- * production one - every page noindex, no sitemap, no analytics. A local build is not a preview.
+ * What this build is FOR. `preview` is true when webmonterey.json says `environment: "staging"`,
+ * or on any Workers Builds branch other than the production one - every page noindex, no
+ * sitemap, no analytics. `reason` says which signal decided it. A local build of a production
+ * site is not a preview. See `isPreviewBuild` in includes/webmonterey/config.ts.
  */
 declare module 'virtual:webm/build' {
-  const build: { preview: boolean; branch: string | null };
+  import type { PreviewReason } from '../includes/webmonterey/config.ts';
+  const build: { preview: boolean; reason: PreviewReason; branch: string | null };
   export default build;
 }
 

package/src/layouts/base.astro

@@ -183,12 +183,15 @@ const {
 } = Astro.props;
 
 /*
- * A BRANCH PREVIEW IS NOINDEX, EVERY PAGE. The review link a client gets is a public workers.dev
- * URL, and a search engine that finds one indexes a duplicate of the site under the wrong
- * hostname. noindex also suppresses the canonical and og:url below, so the preview sends one
- * signal rather than "do not index me" beside "my real address is over there". GTM is skipped on
- * a preview for the same reason in the other direction: a client clicking through their review
- * link must not show up in their own analytics.
+ * A PREVIEW BUILD IS NOINDEX, EVERY PAGE. A preview is a staging site (`environment` in
+ * webmonterey.json) on any hostname, or a non-production branch of a launched one - see
+ * isPreviewBuild in includes/webmonterey/config.ts. The review link a client gets is a public
+ * workers.dev URL, and a search engine that finds one indexes a duplicate of the site under the
+ * wrong hostname - or, for a site that has not launched, indexes the site before it exists.
+ * noindex also suppresses the canonical and og:url below, so the preview sends one signal rather
+ * than "do not index me" beside "my real address is over there". GTM is skipped on a preview for
+ * the same reason in the other direction: a client clicking through their review link must not
+ * show up in their own analytics.
  */
 const noindex = noindexProp || build.preview;
 const analyticsOn = analytics && !build.preview;

package/src/pages/robots.txt.ts

@@ -25,9 +25,11 @@ import build from 'virtual:webm/build';
 
 export const GET: APIRoute = ({ site }) => {
   /*
-   * A BRANCH PREVIEW DISALLOWS EVERYTHING. Every page on a preview is already noindex; this is
-   * the belt to that brace, and it is the one place Disallow is right - there is nothing on a
-   * preview a crawler should ever fetch, and no noindex tag it needs to see.
+   * A PREVIEW DISALLOWS EVERYTHING - a staging site on any hostname, or a non-production branch
+   * of a launched one (isPreviewBuild in includes/webmonterey/config.ts). Every page on a preview
+   * is already noindex; this is the belt to that brace, and it is the one place Disallow is
+   * right - there is nothing on a preview a crawler should ever fetch, and no noindex tag it
+   * needs to see.
    */
   if (build.preview) {
     return new Response('User-agent: *\nDisallow: /\n', {

package/template/site/CLAUDE.md

@@ -14,7 +14,8 @@ The relationship is a WordPress parent theme and child theme.
 
 **A fix to the package reaches this site on `npm update`.** That is the entire point of the
 package existing, and it is why the default answer to "the shared behavior is wrong" is to fix
-it upstream rather than to work around it here.
+it upstream rather than to work around it here. Upstream means the package's own repo, in a
+session opened there — never from here. Rule 12 says what a session in this repo does instead.
 
 ## The one rule that protects that
 
@@ -198,7 +199,29 @@ alone renders.
 ### 11. Never edit inside `node_modules`
 
 A change there survives until the next install and not one second longer. If the package is
-wrong, fix the package — see the top of this file.
+wrong, the package gets fixed — by a session in the package repo, not this one. See rule 12.
+
+### 12. A session in a client repo never edits the package
+
+Not in `node_modules`, and not in the package's own checkout if it happens to be on this machine.
+When something in the package is wrong, the deliverable from a session in this repo is a
+**description of the fix** — what is wrong, where (file and line in the installed package), what
+the behavior should be, and how to verify it — written as a prompt the user can run in a session
+opened in the package repo. The package is versioned, tested and published on its own; this site
+takes the fix with `npm update`.
+
+This session stays inside this site's scope. An override in `design.json`, `src/styles/custom/`
+or `src/actions/index.ts` is fine; reaching upstream is not.
+
+Why this is a rule: "fix it upstream", read from inside a client repo, invited exactly the wrong
+thing. The package source sat next door on the same machine, a session opened it mid-task and
+edited it — a change nobody reviewed, in a repo nobody had open, on no branch, which then had to
+be published before this site could even use it. The client-site session ended with the site
+depending on a package version that did not exist.
+
+`.claude/settings.json` denies `Edit` under any `node_modules/`, so the first half is mechanical
+and `webm sync` keeps it that way. Claude Code has no rule syntax for "any path outside this
+project", so the second half is this paragraph.
 
 ## Structure