@getvitops/create 0.7.0 → 0.8.1

package/templates/emdash/scripts/refresh-dev.mjs

@@ -0,0 +1,182 @@
+// Refreshes the DEV D1 database (and, optionally, the dev media bucket) from
+// PRODUCTION. One direction only: prod is the source of truth for content, dev
+// is a disposable copy used to rehearse code and schema changes against real
+// data (EmDash's own "rehearse changes on a preview environment" pattern).
+//
+//   node scripts/refresh-dev.mjs          # wipe dev D1, import prod's export
+//   node scripts/refresh-dev.mjs --dry    # run every check, change nothing
+//
+// Names come from wrangler.jsonc, the same way scripts/build-dev-wrangler.mjs
+// derives them, so the two can't disagree about which resources are "dev":
+//
+//   D1      <database_name>      → <database_name>-dev   (id from $DEV_D1_ID)
+//   R2      <bucket_name>        → <bucket_name>-dev
+//
+// SAFETY, in the order it is enforced:
+//   1. $DEV_D1_ID must be set, and `wrangler d1 info <name>-dev` must report
+//      that same id. A name that resolves to a different database than the id
+//      we were told about means one of the two is stale.
+//   2. The dev id must differ from prod's. This script DROPS every table in
+//      the target, so pointing it at prod would erase production — the exact
+//      thing the dev/prod split exists to prevent.
+//   Both checks run before the first write, and `--dry` stops after them.
+//
+// Not copied: anything outside D1/R2. Sessions live in the Astro session store
+// (KV), not D1, so nothing is carried over there. The preview-link secret IS in
+// D1 — set EMDASH_PREVIEW_SECRET on the dev worker so prod preview links don't
+// verify on dev (see SETUP.html).
+//
+// Media is copied only when R2 S3 credentials are present, because wrangler has
+// no bucket-to-bucket sync and rclone needs the S3 API:
+//   R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, CLOUDFLARE_ACCOUNT_ID
+// Without them the database is refreshed and media is left alone, with a note —
+// dev then shows broken images for anything uploaded since the last copy.
+//
+// KNOWN LIMIT: `wrangler d1 export` does not support virtual tables, so an FTS5
+// search table breaks the export. EmDash rebuilds its search index on the first
+// search call, so if an export ever fails on one, drop it from prod's schema
+// dump rather than working around it here.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Pull the D1 database and R2 bucket names out of a wrangler.jsonc source.
+ * Regex rather than a JSONC parser: the template carries no parser, the file
+ * is ours, and these two keys are the only thing read. `//` comment lines are
+ * stripped first so a commented-out example block can't be picked up.
+ */
+export function parseBindingNames(jsonc) {
+  const code = jsonc
+    .split('\n')
+    .filter((line) => !line.trim().startsWith('//'))
+    .join('\n');
+  const database = /"database_name"\s*:\s*"([^"]+)"/.exec(code)?.[1];
+  const bucket = /"bucket_name"\s*:\s*"([^"]+)"/.exec(code)?.[1];
+  return { database, bucket };
+}
+
+/**
+ * Throws unless it is safe to wipe `devId`'s database. Pure, so the one check
+ * that stands between this script and production is asserted in a test.
+ */
+export function assertSafeTarget({ devName, devId, devReportedId, prodId }) {
+  if (!devId) throw new Error('DEV_D1_ID is not set.');
+  if (!devName.endsWith('-dev')) throw new Error(`Refusing: "${devName}" is not a -dev database.`);
+  if (devReportedId !== devId) {
+    throw new Error(
+      `DEV_D1_ID (${devId}) does not match "${devName}" (${devReportedId}). One of them is stale.`,
+    );
+  }
+  if (devId === prodId) throw new Error('Refusing: the dev database id is the production id.');
+}
+
+/**
+ * SQL that empties a database: views, then virtual tables, then ordinary
+ * tables. `rows` is `{ name, type, sql }` from sqlite_master. A virtual table
+ * owns shadow tables named `<virtual>_*`, which SQLite refuses to drop on their
+ * own and removes with the parent, so those are skipped.
+ */
+export function dropStatements(rows) {
+  const virtual = rows.filter((r) => /^CREATE VIRTUAL TABLE/i.test(r.sql ?? ''));
+  const isShadow = (name) => virtual.some((v) => name.startsWith(`${v.name}_`));
+  const tables = rows.filter(
+    (r) => r.type === 'table' && !virtual.includes(r) && !isShadow(r.name),
+  );
+  const q = (name) => `"${name.replaceAll('"', '""')}"`;
+  return [
+    'PRAGMA defer_foreign_keys = true;',
+    ...rows.filter((r) => r.type === 'view').map((r) => `DROP VIEW IF EXISTS ${q(r.name)};`),
+    ...virtual.map((r) => `DROP TABLE IF EXISTS ${q(r.name)};`),
+    ...tables.map((r) => `DROP TABLE IF EXISTS ${q(r.name)};`),
+  ];
+}
+
+const wrangler = (args, opts = {}) =>
+  execFileSync('pnpm', ['exec', 'wrangler', ...args], { encoding: 'utf8', ...opts });
+
+const d1Id = (name) => JSON.parse(wrangler(['d1', 'info', name, '--json'])).uuid;
+
+function main() {
+  const dry = process.argv.includes('--dry');
+  const wranglerConfig = 'wrangler.jsonc';
+  if (!existsSync(wranglerConfig))
+    throw new Error(`Run from the project root (no ${wranglerConfig}).`);
+
+  const { database, bucket } = parseBindingNames(readFileSync(wranglerConfig, 'utf8'));
+  if (!database) throw new Error(`No D1 database_name found in ${wranglerConfig}.`);
+  const devDatabase = `${database}-dev`;
+
+  assertSafeTarget({
+    devName: devDatabase,
+    devId: process.env.DEV_D1_ID,
+    devReportedId: d1Id(devDatabase),
+    prodId: d1Id(database),
+  });
+  console.log(`OK to refresh ${devDatabase} from ${database}.`);
+
+  const dir = mkdtempSync(join(tmpdir(), 'refresh-dev-'));
+  const dump = join(dir, 'prod.sql');
+  const wipe = join(dir, 'wipe.sql');
+
+  const master = JSON.parse(
+    wrangler([
+      'd1',
+      'execute',
+      devDatabase,
+      '--remote',
+      '--json',
+      '--command',
+      "SELECT name, type, sql FROM sqlite_master WHERE name NOT LIKE 'sqlite_%' AND name NOT LIKE '\\_cf\\_%' ESCAPE '\\' AND type IN ('table','view')",
+    ]),
+  )[0].results;
+  writeFileSync(wipe, `${dropStatements(master).join('\n')}\n`);
+
+  if (dry) {
+    console.log(`--dry: would drop ${master.length} objects from ${devDatabase} and import prod.`);
+    console.log(
+      bucket ? `--dry: would copy ${bucket} → ${bucket}-dev.` : '--dry: no R2 bucket found.',
+    );
+    return;
+  }
+
+  wrangler(['d1', 'export', database, '--remote', '--output', dump], { stdio: 'inherit' });
+  wrangler(['d1', 'execute', devDatabase, '--remote', '--file', wipe], { stdio: 'inherit' });
+  wrangler(['d1', 'execute', devDatabase, '--remote', '--file', dump], { stdio: 'inherit' });
+  console.log(`Imported ${database} into ${devDatabase}.`);
+
+  const { R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, CLOUDFLARE_ACCOUNT_ID } = process.env;
+  if (!bucket) return;
+  if (!R2_ACCESS_KEY_ID || !R2_SECRET_ACCESS_KEY || !CLOUDFLARE_ACCOUNT_ID) {
+    console.log(
+      `Skipped media: R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY not set, ${bucket}-dev left as is.`,
+    );
+    return;
+  }
+  // Credentials ride rclone's env-var config, not the command line, so the
+  // secret never appears in a process listing.
+  const env = {
+    ...process.env,
+    RCLONE_CONFIG_R2_TYPE: 's3',
+    RCLONE_CONFIG_R2_PROVIDER: 'Cloudflare',
+    RCLONE_CONFIG_R2_ENDPOINT: `https://${CLOUDFLARE_ACCOUNT_ID}.r2.cloudflarestorage.com`,
+    RCLONE_CONFIG_R2_ACCESS_KEY_ID: R2_ACCESS_KEY_ID,
+    RCLONE_CONFIG_R2_SECRET_ACCESS_KEY: R2_SECRET_ACCESS_KEY,
+  };
+  // `sync`, not `copy`: media deleted from prod should disappear from dev too.
+  execFileSync('rclone', ['sync', `R2:${bucket}`, `R2:${bucket}-dev`], { env, stdio: 'inherit' });
+  console.log(`Synced ${bucket} → ${bucket}-dev.`);
+}
+
+// Importable for tests without running; executed when invoked as a script.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    main();
+  } catch (err) {
+    console.error(`ERROR: ${err.message}`);
+    process.exit(1);
+  }
+}

package/templates/emdash/seed/seed.json

@@ -36,16 +36,32 @@
       "name": "primary",
       "label": "Primary Navigation",
       "items": [
-        { "type": "custom", "label": "Home", "url": "/" },
-        { "type": "custom", "label": "About", "url": "/about" }
+        {
+          "type": "custom",
+          "label": "Home",
+          "url": "/"
+        },
+        {
+          "type": "custom",
+          "label": "About",
+          "url": "/about"
+        }
       ]
     },
     {
       "name": "footer",
       "label": "Footer",
       "items": [
-        { "type": "custom", "label": "Terms & Conditions", "url": "/terms" },
-        { "type": "custom", "label": "Privacy Policy", "url": "/privacy" }
+        {
+          "type": "custom",
+          "label": "Terms & Conditions",
+          "url": "/terms"
+        },
+        {
+          "type": "custom",
+          "label": "Privacy Policy",
+          "url": "/privacy"
+        }
       ]
     }
   ],
@@ -86,6 +102,84 @@
                 }
               ]
             },
+            {
+              "_type": "vitops.hero",
+              "_key": "demo-hero",
+              "eyebrow": "Vitops blocks",
+              "heading": "Build pages from design-system patterns",
+              "body": "Every block below renders a framework pattern, so it follows your tokens and works without JavaScript.",
+              "primaryLabel": "Open the admin",
+              "primaryHref": "/_emdash/admin",
+              "secondaryLabel": "Docs",
+              "secondaryHref": "https://docs.vitops.ca",
+              "layout": "centered"
+            },
+            {
+              "_type": "vitops.cards",
+              "_key": "demo-cards",
+              "columns": "3",
+              "cards": [
+                {
+                  "_key": "c1",
+                  "title": "Tokens",
+                  "body": "Colour, type and spacing come from site.json.",
+                  "href": "https://docs.vitops.ca",
+                  "linkLabel": "Read more"
+                },
+                {
+                  "_key": "c2",
+                  "title": "Patterns",
+                  "body": "Cards, carousels and dialogs share one vocabulary."
+                },
+                {
+                  "_key": "c3",
+                  "title": "Accessible",
+                  "body": "Semantic HTML first, enhanced when JavaScript loads."
+                }
+              ]
+            },
+            {
+              "_type": "vitops.accordion",
+              "_key": "demo-accordion",
+              "exclusive": true,
+              "items": [
+                {
+                  "_key": "a1",
+                  "summary": "What is a block?",
+                  "body": "A reusable section an editor inserts from the slash menu.",
+                  "open": true
+                },
+                {
+                  "_key": "a2",
+                  "summary": "Can I add my own?",
+                  "body": "Yes. Pass blocks.extra to the plugin and map a component for it."
+                }
+              ]
+            },
+            {
+              "_type": "vitops.marquee",
+              "_key": "demo-marquee",
+              "pauseOnHover": true,
+              "reverse": false,
+              "items": [
+                {
+                  "_key": "m1",
+                  "text": "Fast"
+                },
+                {
+                  "_key": "m2",
+                  "text": "Accessible"
+                },
+                {
+                  "_key": "m3",
+                  "text": "Editable"
+                },
+                {
+                  "_key": "m4",
+                  "text": "Yours"
+                }
+              ]
+            },
             {
               "_type": "vitops.banner",
               "_key": "welcome-banner",
@@ -161,7 +255,12 @@
               "style": "h2",
               "markDefs": [],
               "children": [
-                { "_type": "span", "_key": "terms-use-h-1", "text": "Use of the site", "marks": [] }
+                {
+                  "_type": "span",
+                  "_key": "terms-use-h-1",
+                  "text": "Use of the site",
+                  "marks": []
+                }
               ]
             },
             {

package/templates/emdash/site.json

@@ -23,8 +23,8 @@
             }
           },
           "roles": {
-            "neutral": "ink",
-            "surface": "ink",
+            "neutral": { "hue": "ink", "kind": "surface" },
+            "surface": { "hue": "ink", "kind": "surface" },
             "ui-primary": "brand",
             "brand-primary": "brand",
             "info": "sky",
@@ -223,6 +223,81 @@
         "url": "https://dev.my-emdash-site.example.com",
         "robots": "noindex,nofollow"
       }
+    },
+    "icons": {
+      "sprite": true,
+      "semantic": [
+        "menu",
+        "close",
+        "home",
+        "settings",
+        "search",
+        "add",
+        "remove",
+        "delete",
+        "edit",
+        "save",
+        "copy",
+        "paste",
+        "attach",
+        "upload",
+        "download",
+        "share",
+        "bookmark",
+        "favorite",
+        "star",
+        "login",
+        "logout",
+        "email",
+        "phone",
+        "location",
+        "globe",
+        "link",
+        "clock",
+        "calendar",
+        "schedule",
+        "person",
+        "group",
+        "file",
+        "folder",
+        "image",
+        "export",
+        "import",
+        "backup",
+        "compress",
+        "check",
+        "error",
+        "warning",
+        "info",
+        "help",
+        "cart",
+        "tag",
+        "receipt",
+        "leaf",
+        "tree",
+        "seedling",
+        "trowel",
+        "droplet",
+        "snowflake",
+        "sun",
+        "cloud",
+        "grid",
+        "list",
+        "filter",
+        "sort",
+        "fullscreen",
+        "collapse",
+        "building",
+        "video",
+        "lock",
+        "unlock",
+        "eye",
+        "print",
+        "code",
+        "palette",
+        "lightbulb",
+        "lightning"
+      ]
     }
   }
 }

package/templates/emdash/src/layouts/Layout.astro

@@ -1,8 +1,10 @@
 ---
 import VitopsHead from '@getvitops/astro/Head.astro';
+import { resolveOrganizationName } from '@getvitops/astro/routes';
 import { getMenu, getSiteSettings } from 'emdash';
 import { createPublicPageContext } from 'emdash/page';
 import { EmDashHead } from 'emdash/ui';
+import config from '../../site.json' with { type: 'json' };
 // Design-system CSS, layout-scoped (vitops css.inject: false): only pages
 // rendered through this layout get it — keeps it out of /_emdash/admin, while
 // EmDash previews (rendered through this layout) keep it.
@@ -19,7 +21,11 @@ interface Props {
 
 const { title, description, image } = Astro.props;
 const settings = await getSiteSettings();
-const siteTitle = settings?.title || 'My EmDash Site';
+// getSiteSettings().title is the editable, client-facing display name (set in
+// the EmDash admin) — it wins whenever it's set. resolveOrganizationName(config)
+// is the fallback rather than a second hardcoded string, so a fresh scaffold
+// shows organization.name (from site.json) before anyone's touched the admin.
+const siteTitle = settings?.title || resolveOrganizationName(config) || 'My EmDash Site';
 const fullTitle = title ? `${title} — ${siteTitle}` : siteTitle;
 const siteDescription = settings?.tagline || 'An EmDash website with the Vitops design system';
 

package/templates/emdash/src/pages/404.astro

@@ -1,5 +1,10 @@
 ---
 import Layout from '../layouts/Layout.astro';
+
+// No per-request data — safe to prerender per AGENTS.md's "Prerender by
+// default" rule. [...slug].astro reaches this via Astro.rewrite('/404'),
+// which resolves a prerendered destination the same as a server-rendered one.
+export const prerender = true;
 ---
 
 <Layout title="Page not found">

package/templates/emdash/src/pages/[...slug].astro

@@ -4,17 +4,30 @@ import { PortableText } from 'emdash/ui';
 import Layout from '../layouts/Layout.astro';
 
 // Catch-all: any entry in the `pages` collection renders at its slug.
+//
+// Deliberately NOT prerendered, unlike AGENTS.md's general "prerender by
+// default" rule — see index.astro's comment for why: a live EmDash publish
+// should reach visitors without a redeploy. A page that's known ahead of
+// time and doesn't need that (rarely edited, or fine to lag a build) can
+// move to its own prerendered route with `getStaticPaths()` over the
+// `pages` collection instead of relying on this catch-all.
 const { slug } = Astro.params;
 const { entry: page } = slug ? await getEmDashEntry('pages', slug) : { entry: null };
 
 if (!page) {
   return Astro.rewrite('/404');
 }
+
+// `page.data` is typed `unknown` until `.emdash/types.ts` is generated from a
+// running site (`pnpm dev`, then `emdash types`), so a fresh scaffold would fail
+// `astro check`; the cast keeps it passing both before and after, where the
+// generated type is already `string`.
+const title = page.data.title as string | undefined;
 ---
 
-<Layout title={page.data.title}>
+<Layout title={title}>
   <article class="rhythm">
-    <h1>{page.data.title}</h1>
+    <h1>{title}</h1>
     {page.data.content && <PortableText value={page.data.content} />}
   </article>
 </Layout>

package/templates/emdash/src/pages/index.astro

@@ -6,12 +6,25 @@ import Layout from '../layouts/Layout.astro';
 // The seeded home page (seed/seed.json → pages/home). Edit it in the admin;
 // the Vitops blocks from @getvitops/emdash render automatically — EmDash
 // merges the plugin's block components into <PortableText>.
+//
+// Deliberately NOT prerendered, unlike AGENTS.md's general "prerender by
+// default" rule: this is the one route where the tradeoff that rule names
+// (prerendered = fast, but reflects the database as of the last build) is
+// unacceptable — the whole point of editing in EmDash is that a publish
+// shows up without a redeploy. Add `getStaticPaths()` + `prerender = true`
+// here only if this site's home page genuinely doesn't need that.
 const { entry: page } = await getEmDashEntry('pages', 'home');
+
+// `page.data` is typed `unknown` until `.emdash/types.ts` is generated from a
+// running site (`pnpm dev`, then `emdash types`), so a fresh scaffold would fail
+// `astro check`; the cast keeps it passing both before and after, where the
+// generated type is already `string`.
+const title = page?.data.title as string | undefined;
 ---
 
-<Layout description={page?.data.title}>
+<Layout description={title}>
   <section class="rhythm">
-    <h1>{page?.data.title ?? 'Welcome'}</h1>
+    <h1>{title ?? 'Welcome'}</h1>
     {
       page?.data.content ? (
         <PortableText value={page.data.content} />

package/templates/emdash/vite.config.ts

@@ -11,13 +11,27 @@ export default defineConfig({
       'vitops lint -i site.json -f tailwind --strict',
   },
   fmt: {
+    // Explicit, matching the monorepo root's style: unlike `lint`, a nested
+    // `fmt` config genuinely takes effect independently here rather than
+    // being root-only, so leaving these unset let this file (and anything
+    // else oxfmt formats under this directory, e.g. SETUP.html's embedded
+    // `<script>`) drift to a different default quote style each time
+    // `vp check --fix` ran, breaking `templates.test.ts`'s byte-identical
+    // mirror assertion.
+    semi: true,
+    singleQuote: true,
     ignorePatterns: ['dist/**', 'node_modules/**', 'src/styles/**', 'public/vitops/**'],
   },
   lint: {
     ignorePatterns: ['dist/**', 'node_modules/**', 'src/styles/**', 'public/vitops/**'],
-    options: {
-      typeAware: true,
-      typeCheck: true,
-    },
+    // `options.typeAware`/`typeCheck` commented out, not deleted: vite-plus 1.0
+    // only honours those at the root config, and while this file sits nested
+    // inside the getvitops/design-system monorepo (which has its own root
+    // vite.config.ts), setting them here is a hard error — "typeAware is only
+    // supported in the root config" — rather than the silent no-op it was
+    // pre-1.0. Once `vp create @getvitops:emdash` scaffolds this file out into
+    // its own project, it *becomes* that project's root config, and
+    // uncommenting this is the right move there.
+    // options: { typeAware: true, typeCheck: true },
   },
 });

package/templates/emdash/wrangler.jsonc

@@ -30,6 +30,10 @@
       "bucket_name": "my-emdash-site-media",
     },
   ],
+  // Outbound mail for EmDash's magic-link sign-in, invites and recovery
+  // (cloudflareEmail() in astro.config.mjs). The binding does nothing until the
+  // sender domain is onboarded: `npx vitops email setup send.<your-domain>`.
+  "send_email": [{ "name": "EMAIL" }],
   // Drives scheduled publishing, plugin cron, and maintenance (see
   // src/worker.ts). Without it, content scheduled in the admin never
   // publishes on Cloudflare Workers. Local `astro dev` doesn't need it.

package/templates/static/.github/workflows/backmerge.yml

@@ -0,0 +1,18 @@
+# Carry changes made directly on `main` (a hotfix) back into `dev`, so the
+# integration branch doesn't silently drift from what is live. Runs on every
+# push to `main`, including each promotion, and opens a PR only when merging
+# main into dev would actually change dev.
+#
+# Deploys via the vitops toolchain's reusable workflow — see
+# https://github.com/getvitops/design-system/blob/main/.github/workflows/site-backmerge.yml
+# for why the PR is left for a human unless BACKMERGE_TOKEN is set.
+name: Back-merge main → dev
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  backmerge:
+    uses: getvitops/design-system/.github/workflows/site-backmerge.yml@v1
+    secrets: inherit

package/templates/static/.github/workflows/deploy-prod.yml

@@ -1,7 +1,7 @@
 # Deploys `main` to production.
 # `main` should be branch-protected — it then only advances via the Promote
 # workflow (promote.yml), so a push here always represents promoted code. The
-# `production` GitHub Environment (set up by `scripts/init-github.mjs`) has
+# `production` GitHub Environment (set up by `vitops setup repo`) has
 # required reviewers restricted to admins, so this PAUSES for approval before
 # deploying.
 #

package/templates/static/.node-version

@@ -0,0 +1 @@
+24

package/templates/static/AGENTS.md

@@ -18,15 +18,15 @@ as Cloudflare Workers static assets (no server runtime, no database).
   full generated class-vocabulary reference to this file.
 - **Layout foundations — these are the answer, not a starting point.** Six
   substitutions carry the structure of nearly every page:
-  | About to write… | Write instead |
-  | --- | --- |
-  | a `wrap`/`wrapper`/`container`/`inner` class | **`centered`** |
-  | `max-width` + `margin-inline: auto` | **`centered`** |
-  | `padding-block` on a section | **`region`** |
-  | margins between headings/paragraphs/lists | **`rhythm`** |
-  | `display: grid` + `grid-template-columns: repeat(n, …)` | **`subgrid`** |
-  | `repeat(auto-fit, minmax(…))` | **`grid-auto`** |
-  | `display: flex` + `gap` for a row of controls | **`cluster`** |
+  | About to write…                                         | Write instead   |
+  | ------------------------------------------------------- | --------------- |
+  | a `wrap`/`wrapper`/`container`/`inner` class            | **`centered`**  |
+  | `max-width` + `margin-inline: auto`                     | **`centered`**  |
+  | `padding-block` on a section                            | **`region`**    |
+  | margins between headings/paragraphs/lists               | **`rhythm`**    |
+  | `display: grid` + `grid-template-columns: repeat(n, …)` | **`subgrid`**   |
+  | `repeat(auto-fit, minmax(…))`                           | **`grid-auto`** |
+  | `display: flex` + `gap` for a row of controls           | **`cluster`**   |
 - Every page is prerendered by default (`output: 'static'`) — there is no
   server to fall back to, so nothing here can read request-time data
   (cookies, headers, query params) at render time. If a page genuinely needs