create-grist-widget 0.2.18 → 0.2.20

package/bin/create-grist-widget.mjs

@@ -50,6 +50,21 @@ for (const [file, subs] of edits) {
   writeFileSync(p, content)
 }
 
+// Record which create-grist-widget release produced this scaffold -- purely
+// informational (shown in a small landing-page footer), never read by the
+// deploy pipeline's own version/release logic. Every scaffold gets this,
+// including the ones the template-canary workflow generates for its `dev`
+// and `canary/latest` branches -- so it survives even if that content is
+// later promoted into a reference repo's `main` and copied again via
+// GitHub's "Use this template".
+const cliPkg = JSON.parse(
+  readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"),
+)
+const pkgJsonPath = path.join(target, "package.json")
+const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"))
+pkgJson.createGristWidgetVersion = cliPkg.version
+writeFileSync(pkgJsonPath, JSON.stringify(pkgJson, null, 2) + "\n")
+
 // Initialize git on `main` with the scaffold as its first commit, and a
 // `dev` branch ready to push for live-preview later. Doing this here (not
 // leaving it to whoever/whatever runs next) is what actually prevents the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-grist-widget",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "Scaffold a new Grist custom widget from the grist-widget-sdk Vite template",
   "license": "MIT",
   "type": "module",

package/template/.github/workflows/deploy.yml

@@ -101,6 +101,7 @@ jobs:
             fs.appendFileSync(out, `skip=${p.skip ? "true" : "false"}\n`);
             fs.appendFileSync(out, `version=${p.version || ""}\n`);
             fs.appendFileSync(out, `base=${p.base}\n`);
+            fs.appendFileSync(out, `firstRelease=${p.firstRelease ? "true" : "false"}\n`);
           ' "$PLAN"
 
       - name: Build
@@ -135,6 +136,18 @@ jobs:
             --site site --repo "$REPO_NAME" $UPDATE_VERSIONS --push \
             --commit-message "deploy: ${{ steps.plan.outputs.context }} @ ${{ github.sha }}"
 
+      # On this repo's first genuine release only: prune every branch except
+      # main/dev/gh-pages, and reset dev to main's current tip. Establishes
+      # the schema every widget should start from (main == dev, gh-pages is
+      # CI-managed only) regardless of how the repo was created -- a CLI
+      # scaffold already satisfies this trivially; a repo copied via GitHub's
+      # "Use this template" often doesn't (a stray inherited branch, or dev
+      # tracking the source template's own unrelated preview history).
+      # Placed after Finalize so it never runs if the release itself failed.
+      - name: Reset branches on first genuine release
+        if: steps.plan.outputs.context == 'release' && steps.plan.outputs.firstRelease == 'true'
+        run: node scripts/deploy.mjs reset-branches
+
   cleanup:
     # When the `dev` branch is deleted, remove /dev/ so the dev URL retires
     # (404) instead of serving a stale build forever.

package/template/README.md

@@ -4,7 +4,7 @@ Base template to build a Grist widget with `grist-widget-sdk`.
 
 `src/main.tsx` wraps the app with `GristWidgetProvider`, `GristBoundary`, and `GristSdkAlerts`. The latter maps `getGristSdkAlertDescriptors()` from the SDK to shadcn `Alert` (`src/components/grist-sdk-alerts.tsx` + `src/components/ui/alert.tsx`); keep them in sync with the playground when you change alert styling.
 
-Opened outside a Grist iframe, `main.tsx` picks between two components purely by URL shape (`src/lib/showcase-routing.ts`, no router needed): a bare path with no recognized channel suffix renders `TemplateLanding` (its own hero, onboarding, and released-version index); `/latest/`, `/dev/`, or `/v<version>/` renders `ChannelNotice` instead — a distinct hero explaining which build this is, chips to jump to any other version/channel (`src/lib/showcase-versions.ts`), and a copy-this-URL helper for pasting into Grist's custom widget field.
+Opened outside a Grist iframe, `main.tsx` picks between two components purely by URL shape (`src/lib/showcase-routing.ts`, no router needed): a bare path with no recognized channel suffix renders `TemplateLanding` (its own hero, onboarding, and released-version index); `/latest/`, `/dev/`, or `/v<version>/` renders `ChannelNotice` instead — a distinct hero explaining which build this is, chips to jump to any other version/channel (`src/lib/showcase-versions.ts`), and a copy-this-URL helper for pasting into Grist's custom widget field. Both render `ScaffoldFooter` (`src/components/scaffold-footer.tsx`) at the bottom — a small, purely informational note ("Scaffolded from `create-grist-widget@X.Y.Z`") built from `package.json`'s `createGristWidgetVersion` field, which the CLI stamps on every real scaffold (`vite.config.ts` injects it as `__CREATE_GRIST_WIDGET_VERSION__`). Renders nothing if that field is absent, e.g. this pristine template source itself.
 
 When actually embedded, `GristStatusChip` (`src/components/grist-status-chip.tsx`) shows a small pill with live handshake status — connecting, retrying with a countdown, connected, or unavailable — using `useAmbientGristHandshake()` from `grist-widget-sdk/advanced`. It must be mounted *inside* `GristWidgetProvider` (see `src/main.tsx`): it only observes that provider's own handshake manager and never mounts a second one, so it's purely observational and can never duplicate or race the real handshake (see `apps/docs/api/handshake.md`).
 
@@ -89,18 +89,28 @@ automatically.
 > ⚠️ **Used GitHub's "Use this template" button instead of `npm create
 > grist-widget`?** That path copies this repo's default branch verbatim —
 > it doesn't run any of the CLI's own setup (renaming `package.json`,
-> titles, etc.), and it won't reset `package.json`'s `version` back to a
-> fresh `0.0.1` for you. Do both by hand before your first real release.
-> If you also checked **"Include all branches"** (to get `gh-pages`/Pages
-> already set up, no manual Settings step), your first real release
-> automatically clears out every leftover `v<version>/` it finds — a
-> `v<version>/` only counts as a genuine prior release once it carries a
-> `showcase-meta.json` naming *this* repo (written by this pipeline's own
-> `place` step), so on a repo with no genuine releases yet, everything
-> else is provably inherited noise and gets safely wiped on your first
-> push to `main`. That cleanup only ever runs before your *first* genuine
-> release — once one exists, it's permanently a no-op, so it's still safest
-> to never manually re-seed `gh-pages` again after that point.
+> titles, etc.), and whatever version happens to be checked into the
+> source repo's `package.json` (which can be well past `0.0.1` — see below)
+> comes along with it. You don't need to reset it by hand: your first real
+> release always resolves to `v0.0.1` regardless of what `package.json`
+> says, and that value stays untouched in the file — only the deploy
+> pipeline's own idea of "which version is this" is overridden, once, for
+> that first release. If you also checked **"Include all branches"** (to
+> get `gh-pages`/Pages already set up, no manual Settings step), your first
+> real release also automatically clears out every leftover `v<version>/`
+> it finds — a `v<version>/` only counts as a genuine prior release once it
+> carries a `showcase-meta.json` naming *this* repo (written by this
+> pipeline's own `place` step), so on a repo with no genuine releases yet,
+> everything else is provably inherited noise and gets safely wiped on your
+> first push to `main`. Also on that same first release, every branch
+> except `main`, `dev`, and `gh-pages` gets pruned, and `dev` gets
+> force-reset to match `main`'s tip — a fresh widget always starts from
+> `main == dev`, regardless of whether it came from the CLI (already true)
+> or a template copy (may have inherited a stray branch, or a `dev` full of
+> the source template's own unrelated preview history). All three of these
+> only ever apply before your *first* genuine release — once one exists,
+> they're permanently a no-op, so it's still safest to never manually
+> re-seed `gh-pages` again after that point.
 
 **One-time setup** (the workflow can't do this part for you):
 

package/template/scripts/deploy.mjs

@@ -35,6 +35,11 @@
 //   finalize --site <dir> [--update-versions] [--push] [--commit-message <msg>]
 //     Regenerates versions.json (release runs only) and commits + pushes the
 //     gh-pages tree with a rebase-and-retry loop.
+//
+//   reset-branches [--repo-dir <dir>]
+//     On a repo's first genuine release only (caller gates on plan()'s
+//     firstRelease): prunes every branch except main/dev/gh-pages and
+//     force-resets dev to main's current tip.
 
 import {
   existsSync,
@@ -80,6 +85,16 @@ function isGenuineRelease(versionDir, repo) {
   }
 }
 
+/**
+ * Whether this repo has ever genuinely published a release (a v<version>/
+ * dir whose showcase-meta.json names this repo). Shared by `plan()` (forces
+ * the first release to 0.0.1) and `cleanupForeignVersionsIfFirstRelease()`
+ * (clears inherited v<version>/ noise) -- both need the exact same signal.
+ */
+function hasGenuineRelease(siteDir, repo) {
+  return buildVersionsManifest(siteDir, repo).length > 0
+}
+
 /**
  * Build the release/dev plan from this repo's own package.json + the current
  * gh-pages tree. Release is skipped when its immutable v<version> dir was
@@ -92,7 +107,15 @@ export function plan(siteDir, repo, event, ref, { force = false } = {}) {
     return { context: "dev", base: basePathFor(repo, "dev") }
   }
   const pkg = JSON.parse(readFileSync("package.json", "utf8"))
-  const version = pkg.version
+  // A repo's first genuine release always starts at 0.0.1, regardless of
+  // whatever package.json's version field says -- found live: a repo copied
+  // via GitHub's "Use this template" inherited "0.2.18" from the source
+  // template repo's own main branch (itself a canary-stamped scaffold that
+  // had been promoted there), instead of starting fresh. Once a repo has a
+  // genuine release, this no longer applies -- its own version bumps are
+  // its own responsibility from then on, same as `cleanupForeignVersionsIfFirstRelease`.
+  const firstRelease = !hasGenuineRelease(siteDir, repo)
+  const version = firstRelease ? "0.0.1" : pkg.version
   if (!version) throw new Error("package.json has no version")
   const versionDir = join(siteDir, `v${version}`)
   const exists = isGenuineRelease(versionDir, repo)
@@ -102,6 +125,10 @@ export function plan(siteDir, repo, event, ref, { force = false } = {}) {
     base: basePathFor(repo, "release", version),
     skip: exists && !force,
     reason: exists ? (force ? "force-rebuild" : "already-published") : "new-version",
+    // Exposed so the workflow can gate a one-time repo cleanup (prune stray
+    // branches, reset dev to main) on exactly this signal -- see
+    // `resetBranchesIfFirstRelease`.
+    firstRelease,
   }
 }
 
@@ -190,7 +217,7 @@ function replaceDir(dest, srcDist) {
  * permanently a no-op.
  */
 export function cleanupForeignVersionsIfFirstRelease(siteDir, repo) {
-  if (buildVersionsManifest(siteDir, repo).length > 0) return { cleaned: [] }
+  if (hasGenuineRelease(siteDir, repo)) return { cleaned: [] }
   const cleaned = []
   for (const name of existsSync(siteDir) ? readdirSync(siteDir) : []) {
     if (!/^v\d+\.\d+\.\d+/.test(name)) continue
@@ -297,6 +324,34 @@ export function finalize({ siteDir, updateVersions, push, commitMessage, remoteB
   throw lastErr
 }
 
+/**
+ * Establish the schema every widget repo should start from -- `main` and
+ * `dev` identical, `gh-pages` managed by CI only -- by pruning every other
+ * branch and force-resetting `dev` to `main`'s current tip (the commit
+ * already checked out at `repoDir`). Runs once, gated by the caller on
+ * `plan()`'s `firstRelease` flag, so it applies equally to a CLI scaffold
+ * (already satisfies this trivially -- nothing to prune, dev already equals
+ * main) and a repo copied via GitHub's "Use this template" (may have a
+ * stray inherited branch, or `dev` tracking the source template's own
+ * unrelated preview history). Operates on `repoDir`, the repo's own
+ * checkout -- a different directory than the gh-pages `siteDir` every other
+ * function here works with.
+ */
+export function resetBranchesIfFirstRelease(repoDir, keep = ["main", "dev", "gh-pages"]) {
+  const raw = git(["ls-remote", "--heads", "origin"], repoDir)
+  const branches = raw
+    ? raw.split("\n").map((line) => line.split("refs/heads/")[1]).filter(Boolean)
+    : []
+  const deletedBranches = []
+  for (const b of branches) {
+    if (keep.includes(b)) continue
+    git(["push", "origin", "--delete", b], repoDir)
+    deletedBranches.push(b)
+  }
+  git(["push", "--force", "origin", "HEAD:refs/heads/dev"], repoDir)
+  return { deletedBranches, devReset: true }
+}
+
 // ----------------------------------------------------------------------------
 // CLI
 // ----------------------------------------------------------------------------
@@ -354,6 +409,11 @@ function main() {
       console.log("finalize:", JSON.stringify(res))
       break
     }
+    case "reset-branches": {
+      const res = resetBranchesIfFirstRelease(args["repo-dir"] || ".")
+      console.log("reset-branches:", JSON.stringify(res))
+      break
+    }
     default:
       console.error(`unknown subcommand: ${cmd || "(none)"}`)
       process.exit(2)

package/template/src/components/channel-notice.tsx

@@ -1,5 +1,6 @@
 import { useState } from "react"
 
+import { ScaffoldFooter } from "@/components/scaffold-footer"
 import { Button } from "@/components/ui/button"
 import {
   Card,
@@ -117,6 +118,8 @@ export function ChannelNotice({
       >
         ← Back to the template home
       </a>
+
+      <ScaffoldFooter />
     </div>
   )
 }

package/template/src/components/scaffold-footer.tsx

@@ -0,0 +1,17 @@
+// Shown on the showcase hub and channel pages, never inside Grist (there's
+// no room, and it's not relevant to using the widget). Purely informational:
+// which create-grist-widget release this repo's package.json was scaffolded
+// from -- distinct from the repo's own `version`, which the deploy pipeline
+// always starts fresh at 0.0.1 regardless of this value (see
+// scripts/deploy.mjs's `plan()`). Renders nothing for the pristine template
+// source itself, or any copy predating this field.
+export function ScaffoldFooter() {
+  if (!__CREATE_GRIST_WIDGET_VERSION__) return null
+
+  return (
+    <p className="mt-10 text-center text-xs text-muted-foreground">
+      Scaffolded from{" "}
+      <code className="text-foreground">create-grist-widget@{__CREATE_GRIST_WIDGET_VERSION__}</code>
+    </p>
+  )
+}

package/template/src/components/template-landing.tsx

@@ -1,5 +1,6 @@
 import { useState } from "react"
 
+import { ScaffoldFooter } from "@/components/scaffold-footer"
 import { Button } from "@/components/ui/button"
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
 import { devUrl, formatDate, useVersions, versionUrl } from "@/lib/showcase-versions"
@@ -301,6 +302,8 @@ git push origin dev`}</code>
           </ul>
         )}
       </section>
+
+      <ScaffoldFooter />
     </div>
   )
 }

package/template/src/vite-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="vite/client" />
+
+// Injected by vite.config.ts's `define` from package.json's
+// createGristWidgetVersion field -- null for the pristine template source
+// itself (that field only exists on scaffolded copies).
+declare const __CREATE_GRIST_WIDGET_VERSION__: string | null

package/template/vite.config.ts

@@ -1,8 +1,14 @@
+import { readFileSync } from "fs"
 import path from "path"
 import tailwindcss from "@tailwindcss/vite"
 import react from "@vitejs/plugin-react"
 import { defineConfig } from "vite"
 
+// Read here (Node context) rather than importing package.json into src/ --
+// keeps the whole file out of the bundle, exposing only the one field the
+// landing page footer needs.
+const pkg = JSON.parse(readFileSync(path.resolve(__dirname, "package.json"), "utf8"))
+
 // https://vite.dev/config/
 export default defineConfig({
   plugins: [react(), tailwindcss()],
@@ -11,4 +17,7 @@ export default defineConfig({
       "@": path.resolve(__dirname, "./src"),
     },
   },
+  define: {
+    __CREATE_GRIST_WIDGET_VERSION__: JSON.stringify(pkg.createGristWidgetVersion ?? null),
+  },
 })