create-grist-widget 0.2.18 → 0.2.19

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.19",
   "description": "Scaffold a new Grist custom widget from the grist-widget-sdk Vite template",
   "license": "MIT",
   "type": "module",

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,22 @@ 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`. Both 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

@@ -80,6 +80,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 +102,14 @@ 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 version = hasGenuineRelease(siteDir, repo) ? pkg.version : "0.0.1"
   if (!version) throw new Error("package.json has no version")
   const versionDir = join(siteDir, `v${version}`)
   const exists = isGenuineRelease(versionDir, repo)
@@ -190,7 +207,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

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),
+  },
 })