@cparkerwebm/webmonterey 1.0.0

package/src/cli/new.ts

@@ -0,0 +1,148 @@
+/*
+ * `webm new <domain>` - from nothing to a site that builds.
+ *
+ * THE BOOTSTRAP GAP THIS CLOSES: `start` has to run before the package is installed, so it
+ * cannot come from the package's own skills. `npx @cparkerwebm/webmonterey new example.com` runs
+ * with no repo and no prior setup, and hands off to /webm:start once the skills exist.
+ *
+ * Deliberately does NOT touch Cloudflare or GitHub. Creating a Worker, a D1 database or a repo
+ * are outward-facing actions with real consequences, and they belong to a person with the
+ * dashboard open - or to the start skill, which knows what order they go in. This writes files.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { DomainError, normalizeDomain, repoName, resourceNames } from './slug.ts';
+import { scaffold } from './scaffold.ts';
+import { sync } from './sync.ts';
+import { seed, gitkeepEmptyDirs, SCAFFOLD_DIRS } from './seed.ts';
+
+import { PACKAGE_ROOT, packageVersion } from './package-root.ts';
+
+function parseArgs(argv: string[]) {
+  const positional = argv.filter((a) => !a.startsWith('--'));
+  const flag = (name: string) => {
+    const hit = argv.find((a) => a.startsWith(`--${name}=`));
+    return hit ? hit.slice(name.length + 3) : undefined;
+  };
+  return {
+    domain: positional[0],
+    client: flag('client'),
+    org: flag('org') ?? 'webmonterey',
+    stagingEmail: flag('staging-email'),
+    into: flag('into'),
+    install: !argv.includes('--no-install'),
+  };
+}
+
+/*
+ * WHERE A STAGING SITE'S MAIL GOES, defaulting to whoever is scaffolding it.
+ *
+ * The package carries no inbox of its own: a default address baked into a public package means
+ * a stranger's staging site mails the package author. `git config user.email` is the person at
+ * the keyboard, which is the right default for a site they are about to test. The flag overrides
+ * it; doctor fails a staging site that ends up with none.
+ */
+function gitUserEmail(): string {
+  try {
+    return execFileSync('git', ['config', 'user.email'], { encoding: 'utf8' }).trim();
+  } catch {
+    return '';
+  }
+}
+
+export function run(argv: string[]): number {
+  const args = parseArgs(argv);
+
+  if (!args.domain) {
+    console.error(
+      'webm new <domain> [--client="Name"] [--org=webmonterey] [--staging-email=you@example.com] [--into=path] [--no-install]',
+    );
+    console.error('\n  webm new autire.com --client="Autire Technologies"');
+    return 1;
+  }
+
+  let domain: string;
+  try {
+    domain = normalizeDomain(args.domain);
+  } catch (error) {
+    console.error(`webm new: ${error instanceof DomainError ? error.message : error}`);
+    return 1;
+  }
+
+  const names = resourceNames(domain);
+  const root = resolve(args.into ?? repoName(domain));
+
+  /*
+   * Refuse a directory that already has anything in it. Scaffolding over an existing site would
+   * overwrite webmonterey.json and design.json - the two files nobody can reconstruct.
+   */
+  if (existsSync(root) && readdirSync(root).length > 0) {
+    console.error(`webm new: ${root} exists and is not empty. Refusing to scaffold over it.`);
+    return 1;
+  }
+
+  const files = scaffold({
+    domain,
+    client: args.client,
+    org: args.org,
+    stagingEmail: args.stagingEmail ?? gitUserEmail(),
+    packageVersion: packageVersion(),
+    /* Real today, not a constant - see ScaffoldOptions.today for what a stale one does. */
+    today: new Date().toISOString().slice(0, 10),
+  });
+
+  for (const [path, contents] of Object.entries(files)) {
+    const full = join(root, path);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, contents);
+  }
+  /*
+   * Seed AFTER the scaffold, and never over it. Both can produce a given path; the scaffold's
+   * version is the one with this client's domain in it.
+   */
+  const seeded = seed(PACKAGE_ROOT, root);
+
+  /*
+   * scripts/ and migrations/ come from `sync`, so they arrive on every install rather than only
+   * at scaffold time. Run it before the .gitkeep walk so migrations/ is not marked empty.
+   */
+  sync(root);
+
+  const kept = gitkeepEmptyDirs(root, SCAFFOLD_DIRS);
+
+  console.log(`Scaffolded ${Object.keys(files).length} files into ${root}`);
+  console.log(`  + ${seeded.length} seeded (favicons, headers, CLAUDE.md, a contact form)`);
+  console.log(`  + ${kept.length} .gitkeep, so the empty directories survive a clone\n`);
+  console.log(`  repo     ${args.org}/${names.repo}      (keeps the domain)`);
+  console.log(
+    `  worker   ${names.worker}                (slug - no TLD, so Chrome does not flag previews)`,
+  );
+  console.log(`  d1       ${names.d1}`);
+  console.log(`  r2       ${names.r2Media}`);
+
+  try {
+    execFileSync('git', ['init', '-q', '-b', 'main'], { cwd: root });
+  } catch {
+    console.log('\n  (git init failed - initialize the repo yourself)');
+  }
+
+  if (args.install) {
+    console.log('\nInstalling…');
+    try {
+      execFileSync('npm', ['install'], { cwd: root, stdio: 'inherit' });
+    } catch {
+      console.error(
+        `\nInstall failed. The scaffold is written and fine; fix the cause above and run npm install in ${names.repo}.`,
+      );
+      return 1;
+    }
+  }
+
+  console.log(`\nNext:`);
+  console.log(`  cd ${names.repo}`);
+  console.log(`  claude          # then /webm:start — it takes it from here`);
+  console.log(`\nStart Claude from the repo root. Project skills-dir plugins load only from the`);
+  console.log(`directory you start in; launching from a subdirectory misses them.`);
+  return 0;
+}

package/src/cli/package-root.ts

@@ -0,0 +1,58 @@
+/*
+ * Finding the package's own root, from wherever this code ended up.
+ *
+ * THE PROBLEM BUNDLING CREATES: src/cli/*.ts resolve the root as `../../` from their own
+ * location, and bin/webm.mjs as `../`. Bundle them all into dist/webm.mjs and every one of those
+ * is now relative to dist/ - so `../../` overshoots the repo entirely and reads a package.json
+ * belonging to whatever sits above it. That failed as `ENOENT: /Users/cparkerwebm/Workspace/
+ * package.json`, which names a directory that has nothing to do with this package.
+ *
+ * Walking up until the manifest identifies itself works from source and from a bundle, and does
+ * not care how deep either sits.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/*
+ * The manifest identifies itself by its bin, not by a hardcoded name. The package has been
+ * renamed once already; a name literal here is one more place a rename has to find.
+ */
+function isOurs(manifest: string): boolean {
+  try {
+    const pkg = JSON.parse(readFileSync(manifest, 'utf8')) as { bin?: Record<string, string> };
+    return typeof pkg.bin?.webm === 'string';
+  } catch {
+    return false; /* a malformed package.json above us is not ours; keep walking */
+  }
+}
+
+function findRoot(): string {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i++) {
+    const manifest = join(dir, 'package.json');
+    if (existsSync(manifest) && isOurs(manifest)) return dir;
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  throw new Error(
+    `webm: cannot locate the package root from ${fileURLToPath(import.meta.url)}. ` +
+      `This usually means the CLI was moved out of the installed package.`,
+  );
+}
+
+export const PACKAGE_ROOT = findRoot();
+
+function manifest(): { name: string; version: string } {
+  return JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+}
+
+export function packageVersion(): string {
+  return manifest().version;
+}
+
+/** The published name, read from the manifest so a rename is one edit. */
+export function packageName(): string {
+  return manifest().name;
+}

package/src/cli/scaffold.test.ts

@@ -0,0 +1,230 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { scaffold } from './scaffold.ts';
+import { MCP_NAMES, mcpConfig } from './mcp.ts';
+
+const files = (over = {}) =>
+  scaffold({
+    domain: 'autire.com',
+    client: 'Autire Technologies',
+    packageVersion: '1.0.0',
+    today: '2026-08-26',
+    ...over,
+  });
+
+const json = (f: Record<string, string>, path: string) => JSON.parse(f[path]!);
+
+test('three names, three jobs: repo, slug, Cloudflare', () => {
+  const f = files();
+  const site = json(f, 'webmonterey.json');
+  // Repo carries the full domain with UNDERSCORES; Cloudflare carries the slug, no TLD.
+  assert.equal(site.repo, 'webmonterey/autire_com');
+  assert.equal(site.worker, 'webm-autire');
+  assert.equal(site.slug, 'autire');
+  assert.match(f['wrangler.jsonc']!, /"name": "webm-autire"/);
+  assert.match(f['README.md']!, /webm-autire-db/);
+});
+
+test('MCP is declared AND pre-approved - a declaration alone is inert', () => {
+  const f = files();
+  // Both halves come from src/cli/mcp.ts, so this asserts against that list rather than a literal
+  // that has to be edited every time a server is added - which is how it fell one behind before.
+  assert.deepEqual(json(f, '.mcp.json'), mcpConfig());
+  assert.deepEqual(json(f, '.claude/settings.json').enabledMcpjsonServers, MCP_NAMES);
+});
+
+test('Mailgun and Stripe are never scaffolded into a client repo', () => {
+  // A session there could send mail as any client, or issue refunds.
+  const all = Object.values(files()).join('\n').toLowerCase();
+  assert.ok(!all.includes('mailgun-mcp'), 'mailgun MCP must not appear');
+  assert.ok(!/stripe.*mcp|mcp.*stripe/.test(all), 'stripe MCP must not appear');
+});
+
+test('the registry and the block union both start empty - the package ships no components', () => {
+  const f = files();
+  assert.match(
+    f['src/components/registry.ts']!,
+    /blocks: Record<string, AstroComponentFactory> = \{\}/,
+  );
+  assert.match(f['src/content.config.ts']!, /webmontereyCollections\(\[\]\)/);
+});
+
+test('postinstall runs webm sync, or a repo has no fleet skills and no error saying why', () => {
+  assert.equal(json(files(), 'package.json').scripts.postinstall, 'webm sync');
+});
+
+test('no .npmrc is scaffolded - the package is on the public registry', () => {
+  const f = files();
+  assert.equal(f['.npmrc'], undefined);
+  const all = Object.values(f).join('\n');
+  assert.ok(!all.includes('NODE_AUTH_TOKEN'), 'no registry credential anywhere in the scaffold');
+});
+
+test('stagingEmail is the address passed in, and empty rather than invented when none is', () => {
+  // The package carries no inbox. A default address in a public package would mean a stranger's
+  // staging site mails the author; `webm new` supplies the git user's email instead.
+  assert.equal(
+    json(files({ stagingEmail: 'me@example.com' }), 'webmonterey.json').stagingEmail,
+    'me@example.com',
+  );
+  assert.equal(json(files(), 'webmonterey.json').stagingEmail, '');
+  assert.ok(!Object.values(files()).join('\n').includes('webmonterey.com'), 'no agency inbox');
+});
+
+test('run_worker_first starts with the actions endpoint and carries its warning', () => {
+  const w = files()['wrangler.jsonc']!;
+  assert.match(w, /"run_worker_first": \["\/_actions\/\*"\]/);
+  assert.match(w, /BOTH SLASH FORMS/);
+  assert.match(w, /Sec-Fetch-Dest/);
+});
+
+test('secrets are gitignored and the example names the password-manager habit', () => {
+  const f = files();
+  assert.match(f['.gitignore']!, /^\.dev\.vars$/m);
+  assert.match(f['.dev.vars.example']!, /password manager/);
+});
+
+test('an unnamed client gets CHANGEME, which go-live refuses to launch with', () => {
+  const site = json(files({ client: undefined }), 'webmonterey.json');
+  assert.equal(site.client, 'CHANGEME');
+});
+
+test('timeZone defaults to a real IANA zone', () => {
+  assert.equal(json(files(), 'webmonterey.json').timeZone, 'America/Los_Angeles');
+});
+
+test('features are technical switches, and carry no plan or tier', () => {
+  const site = json(files(), 'webmonterey.json');
+  assert.deepEqual(Object.keys(site.features).sort(), [
+    'compliance',
+    'd1',
+    'platform',
+    'turnstile',
+  ]);
+  // The app namespace is reserved on every site from day one - off, folder fixed, path public.
+  assert.deepEqual(site.app, { enabled: false, path: 'webapp', label: 'Portal' });
+
+  /*
+   * Check the DATA, not the `//`-prefixed keys - those are inline documentation and one of them
+   * says "Nothing here reads a tier", which a blunt substring check flags as the very thing it
+   * forbids.
+   */
+  const data = Object.fromEntries(Object.entries(site).filter(([k]) => !k.startsWith('//')));
+  const raw = JSON.stringify(data).toLowerCase();
+  for (const word of ['basic', 'standard', 'premium', 'plan_label', 'tier', 'billable', 'credit']) {
+    assert.ok(!raw.includes(word), `webmonterey.json must not know about "${word}"`);
+  }
+});
+
+test('there is no orphan stylesheet entry point in the site', () => {
+  /*
+   * The scaffold used to write src/styles/index.css importing the package's stylesheet and then
+   * custom/. Nothing imported it. A client could write a rule in custom/_index.css, see the
+   * import chain in their own repo, and never see the rule on the page - the file was not in the
+   * module graph at all.
+   *
+   * base.astro now pulls custom/ in through virtual:webm/custom, so there is nothing here to
+   * keep in step, and a file that looks like an entry point but is not is worse than none.
+   */
+  const f = files();
+  assert.equal(f['src/styles/index.css'], undefined, 'no orphan entry point');
+  assert.ok(f['src/styles/custom/_index.css'], 'the override seam itself still ships');
+  assert.match(
+    f['src/styles/custom/_index.css']!,
+    /NOTHING IMPORTS THIS FILE FROM THIS REPO/,
+    'and it says so, so nobody goes looking for the import',
+  );
+});
+
+test('astro.config names the adapter, or the build dies on the first on-demand route', () => {
+  /*
+   * An adapter set through updateConfig from inside the integration does not run its own hooks.
+   * A fully static site never notices, which is how it went unnoticed for a whole build-out.
+   */
+  const config = files()['astro.config.mjs']!;
+  assert.match(config, /import webmonterey, \{ adapter \} from '@cparkerwebm\/webmonterey'/);
+  assert.match(config, /adapter:\s*adapter\(\)/);
+  assert.match(config, /integrations:\s*\[webmonterey\(\)\]/);
+  /*
+   * Check the IMPORTS, not the whole file - the config's own comment explains that the site takes
+   * no direct dependency on @astrojs/cloudflare, and a substring check flags the explanation as
+   * the thing it forbids.
+   */
+  const imports = config.split('\n').filter((l) => l.trimStart().startsWith('import '));
+  assert.ok(
+    !imports.some((l) => l.includes('@astrojs/')),
+    `the site must not import an Astro integration directly: ${imports.join(' | ')}`,
+  );
+});
+
+test('the scaffolded site wires the form pipeline by re-export, not by copy', () => {
+  // The re-export is the propagation seam: a fix to validation, Turnstile, the D1 write or an
+  // email template reaches the site on npm update. A copied pipeline never receives one.
+  const actions = files()['src/actions/index.ts']!;
+  assert.match(actions, /export \{ server \} from '@cparkerwebm\/webmonterey\/actions'/);
+  assert.match(actions, /wrap rather than fork/i);
+});
+
+test('compatibility_date is the date passed in, never a constant baked into the package', () => {
+  /*
+   * The bug this exists to prevent, and it is the nastiest one found in the whole build-out: a
+   * compatibility_date a few months behind the installed workerd renders EVERY page as the
+   * string "[object Object]". 15 bytes, no warning, exit code 0, and `astro build` says
+   * "Complete!". It was hardcoded to 2026-01-01 with a comment claiming the caller overwrote it.
+   *
+   * It is now derived from the argument rather than equal to it - see the fortnight margin in
+   * scaffold.ts, which exists because a date NEWER than the installed runtime does not build at
+   * all. Both directions are traps and they pull in opposite ways.
+   */
+  const config = scaffold({ domain: 'a.com', packageVersion: '1.0.0', today: '2026-08-26' })[
+    'wrangler.jsonc'
+  ]!;
+  assert.match(config, /"compatibility_date":\s*"2026-08-12"/, 'derived from it, a fortnight back');
+
+  const other = scaffold({ domain: 'a.com', packageVersion: '1.0.0', today: '2027-03-04' })[
+    'wrangler.jsonc'
+  ]!;
+  assert.match(other, /"compatibility_date":\s*"2027-02-18"/, 'and it still tracks the argument');
+});
+
+test('a malformed date is refused rather than written into wrangler.jsonc', () => {
+  assert.throws(
+    () => scaffold({ domain: 'a.com', packageVersion: '1.0.0', today: 'today' }),
+    /YYYY-MM-DD/,
+  );
+});
+
+test('the scaffolded compatibility_date is never in the future of the installed runtime', () => {
+  /*
+   * A date newer than the runtime the installed wrangler bundles is refused outright - miniflare
+   * throws ERR_FUTURE_COMPATIBILITY_DATE and the site does not build AT ALL, from the moment it
+   * is scaffolded. Writing today's date walks into that for anyone whose wrangler is a few weeks
+   * old, which is most people most of the time. Two client sites hit it independently.
+   *
+   * Measured: on wrangler 4.126 the ceiling is today, so today's date happens to work on a
+   * machine that just installed. The margin is for every machine that did not.
+   */
+  const written = (today: string) =>
+    scaffold({ domain: 'a.com', packageVersion: '1.0.0', today })['wrangler.jsonc']!.match(
+      /"compatibility_date":\s*"([\d-]+)"/,
+    )![1]!;
+
+  for (const today of ['2026-08-27', '2026-01-01', '2026-03-01', '2027-12-31']) {
+    const gap = (Date.parse(today) - Date.parse(written(today))) / 86_400_000;
+    assert.equal(
+      gap,
+      14,
+      `${today} should scaffold a date a fortnight back, got ${written(today)}`,
+    );
+  }
+});
+
+test('the margin crosses a month and a year boundary correctly', () => {
+  // Naive string arithmetic gets 2026-01-05 minus 14 days wrong; this is why it goes through Date.
+  const at = (today: string) =>
+    scaffold({ domain: 'a.com', packageVersion: '1.0.0', today })['wrangler.jsonc']!.match(
+      /"compatibility_date":\s*"([\d-]+)"/,
+    )![1]!;
+  assert.equal(at('2026-01-05'), '2025-12-22');
+  assert.equal(at('2026-03-05'), '2026-02-19', 'and February');
+});