create-grist-widget 0.2.21 → 0.2.23

package/package.json

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

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

@@ -5,6 +5,19 @@ name: Deploy widget to GitHub Pages
 #     /<repo>/v<version>/ + mutable /<repo>/latest/.
 #     Rebuilt only when package.json's version has no v<version> dir yet, so
 #     re-pushing main without a version bump is a no-op deploy.
+#     A push that *creates* the main ref, authored by GitHub's own web-flow
+#     bot -- fired by "Use this template" copying this repo onto a brand-new
+#     ref -- is skipped entirely instead: it would otherwise publish
+#     whatever boilerplate version package.json happens to have checked in
+#     and permanently spend the first-release override before anyone's done
+#     real work. (Checking github.event.created alone isn't enough: a CLI
+#     scaffold's own first `git push -u origin main` also creates that ref
+#     for the first time, but is a real user's genuine first release and
+#     must not be skipped -- the web-flow committer check tells the two
+#     apart.) That skipped run still clears any foreign content the copy
+#     brought along (stray v<version>/ dirs, a root/latest/ still pointing
+#     at the source repo's own path) via `cleanup-foreign`, so root/latest/
+#     aren't left blank until the widget's real first release.
 #   - push to dev                    -> dev channel: mutable /<repo>/dev/
 #     with version.json + a self-reload snippet, for live review inside Grist.
 #
@@ -91,7 +104,8 @@ jobs:
             --site site --repo "$REPO_NAME" \
             --event "${{ github.event_name }}" \
             --ref "${{ github.ref }}" \
-            ${{ github.event.inputs.force == 'true' && '--force' || '' }})
+            ${{ github.event.inputs.force == 'true' && '--force' || '' }} \
+            ${{ github.event.created == true && github.event.head_commit.committer.email == 'noreply@github.com' && '--created' || '' }})
           echo "Plan: $PLAN"
           node -e '
             const p = JSON.parse(process.argv[1]);
@@ -99,6 +113,7 @@ jobs:
             const out = process.env.GITHUB_OUTPUT;
             fs.appendFileSync(out, `context=${p.context}\n`);
             fs.appendFileSync(out, `skip=${p.skip ? "true" : "false"}\n`);
+            fs.appendFileSync(out, `reason=${p.reason || ""}\n`);
             fs.appendFileSync(out, `version=${p.version || ""}\n`);
             fs.appendFileSync(out, `base=${p.base}\n`);
             fs.appendFileSync(out, `firstRelease=${p.firstRelease ? "true" : "false"}\n`);
@@ -123,9 +138,19 @@ jobs:
             --sha "$SHA" --ref "${{ github.ref }}"
 
       - name: Skip (already published)
-        if: steps.plan.outputs.skip == 'true'
+        if: steps.plan.outputs.skip == 'true' && steps.plan.outputs.reason != 'ref-created'
         run: echo "== skip — v${{ steps.plan.outputs.version }} already published"
 
+      # The ref-created push never reaches Build/Place, so it's the only
+      # path where cleanupForeignVersionsIfFirstRelease (normally a side
+      # effect of Place) needs to run standalone -- otherwise foreign
+      # content from "Use this template" (stray v<version>/ dirs, a
+      # root/latest/ pointing at the source repo's own path) sits untouched
+      # until the widget's real first release.
+      - name: Clean foreign content (ref-created push published nothing)
+        if: steps.plan.outputs.reason == 'ref-created'
+        run: node scripts/deploy.mjs cleanup-foreign --site site --repo "$REPO_NAME"
+
       - name: Finalize (versions.json + commit + push)
         run: |
           UPDATE_VERSIONS=""

package/template/README.md

@@ -111,6 +111,18 @@ automatically.
 > 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.
+>
+> "Use this template" also immediately fires this workflow once on its own,
+> the moment the repo is created — before you've cloned it, let alone
+> changed anything. That run is recognized (GitHub's own web-flow bot
+> creating the `main` ref) and skipped entirely: nothing gets published,
+> and it doesn't count as your first release, so the `0.0.1` override above
+> still applies in full once you actually push real changes. If you also
+> checked "Include all branches", that same skipped run still clears out
+> whatever foreign content came along with it — stray `v<version>/` dirs,
+> and a root/`latest/` still pointing at the *source* repo's own path
+> (which would otherwise render blank until your real first release) —
+> without needing to publish anything of its own to do so.
 
 **One-time setup** (the workflow can't do this part for you):
 

package/template/scripts/deploy.mjs

@@ -19,15 +19,27 @@
 //
 // Subcommands:
 //   plan     --site <dir> --repo <name> --event <push|workflow_dispatch>
-//            --ref <ref> [--force]
+//            --ref <ref> [--force] [--created]
 //     Prints JSON { context: "release"|"dev", version?, base, skip }.
 //     Release is skipped when v<version> already exists on gh-pages
 //     (idempotence: re-pushing main without a version bump is a no-op).
+//     --created additionally skips unconditionally, without consuming the
+//     first-release version override -- see plan()'s own comment. Callers
+//     must only pass --created for GitHub's own server-side "Use this
+//     template" push, never a real user push that merely happens to create
+//     a ref for the first time (e.g. a CLI scaffold's first `git push -u
+//     origin main`) -- see deploy.yml's wiring for the distinguishing check.
 //
 //   place    --site <dir> --repo <name> --channel <release|dev>
 //            [--version <v>] --dist <dir> --sha <sha> [--ref <ref>]
 //     Copies a freshly built dist into the gh-pages tree.
 //
+//   cleanup-foreign --site <dir> --repo <name>
+//     Standalone entry point for `cleanupForeignVersionsIfFirstRelease` --
+//     used on a skipped ref-created push (see `plan`), which never reaches
+//     `place` (the only other caller of this cleanup) so foreign content
+//     from "Use this template" would otherwise sit untouched indefinitely.
+//
 //   remove   --site <dir>
 //     Removes dev/ from the gh-pages tree (retire the dev URL when the `dev`
 //     branch is deleted). Never touches a release or latest/.
@@ -101,7 +113,7 @@ function hasGenuineRelease(siteDir, repo) {
  * genuinely published by this repo before (unless force), so re-pushing main
  * without a version bump is a no-op.
  */
-export function plan(siteDir, repo, event, ref, { force = false } = {}) {
+export function plan(siteDir, repo, event, ref, { force = false, created = false } = {}) {
   const isRelease = event === "workflow_dispatch" || ref === "refs/heads/main" || ref === "main"
   if (!isRelease) {
     return { context: "dev", base: basePathFor(repo, "dev") }
@@ -118,6 +130,28 @@ export function plan(siteDir, repo, event, ref, { force = false } = {}) {
   const version = firstRelease ? "0.0.1" : pkg.version
   if (!version) throw new Error("package.json has no version")
   const versionDir = join(siteDir, `v${version}`)
+  // GitHub's "Use this template" copies the source repo's main branch onto a
+  // brand-new ref, which fires this same push-to-main event itself --
+  // before anyone has done any real work. Without this check, that event
+  // would consume the first-release override above on whatever unmodified
+  // boilerplate happens to be checked in, so the widget's *actual* first
+  // release (once someone merges real content) no longer counts as
+  // firstRelease and publishes under that boilerplate's version verbatim
+  // instead of a clean 0.0.1 -- found live (a monorepo widget moved into its
+  // own repo this way published its real first release as "v0.2.21").
+  // Skipping this event entirely (never placing anything, never touching
+  // gh-pages) keeps hasGenuineRelease() false, so the override survives
+  // intact for whenever a real release actually happens.
+  if (created && event === "push") {
+    return {
+      context: "release",
+      version,
+      base: basePathFor(repo, "release", version),
+      skip: true,
+      reason: "ref-created",
+      firstRelease,
+    }
+  }
   const exists = isGenuineRelease(versionDir, repo)
   return {
     context: "release",
@@ -212,21 +246,28 @@ function replaceDir(dest, srcDist) {
 
 /**
  * If this repo has never genuinely published a release before (no
- * v<version>/ directory whose showcase-meta.json matches this repo), any
- * v<version>/ directories present are provably inherited noise -- e.g. from
- * copying this template repo including its gh-pages branch (GitHub's "Use
- * this template" -> "Include all branches"). Safe to clear them all before
- * placing this repo's actual first release: there is no ambiguity, since a
- * repo with zero genuine releases can't have any of its own history to lose.
- * Never touches dev/, latest/, or site-root files. Once a genuine release
- * exists for this repo, buildVersionsManifest is non-empty and this is
- * permanently a no-op.
+ * v<version>/ directory whose showcase-meta.json matches this repo), *every*
+ * top-level entry except `dev/` (the mutable dev channel, legitimately this
+ * repo's own regardless of release history) and a small set of
+ * pipeline-managed files is provably inherited noise -- e.g. from copying
+ * this template repo including its gh-pages branch (GitHub's "Use this
+ * template" -> "Include all branches"): stray `v<version>/` directories,
+ * but also a root `index.html`/`latest/` still referencing the *source*
+ * repo's own base path (found live: a fresh copy's root and `latest/`
+ * pointed at `/grist-widget-template/v0.2.22/assets/...`, 404ing on this
+ * repo's own Pages site -- a blank page -- because the ref-created push
+ * that used to overwrite them with this repo's own build is now skipped
+ * entirely, see `plan()`). Safe to clear unconditionally: a repo with zero
+ * genuine releases can't have any of its own history to lose. Once a
+ * genuine release exists for this repo, buildVersionsManifest is non-empty
+ * and this is permanently a no-op.
  */
 export function cleanupForeignVersionsIfFirstRelease(siteDir, repo) {
   if (hasGenuineRelease(siteDir, repo)) return { cleaned: [] }
+  const PROTECTED = new Set([".nojekyll", "dev", "versions.json", ".git"])
   const cleaned = []
   for (const name of existsSync(siteDir) ? readdirSync(siteDir) : []) {
-    if (!/^v\d+\.\d+\.\d+/.test(name)) continue
+    if (PROTECTED.has(name)) continue
     rmSync(join(siteDir, name), { recursive: true, force: true })
     cleaned.push(name)
   }
@@ -382,7 +423,10 @@ function main() {
 
   switch (cmd) {
     case "plan": {
-      const result = plan(args.site, args.repo, args.event, args.ref, { force: !!args.force })
+      const result = plan(args.site, args.repo, args.event, args.ref, {
+        force: !!args.force,
+        created: !!args.created,
+      })
       process.stdout.write(JSON.stringify(result))
       break
     }
@@ -404,6 +448,11 @@ function main() {
       console.log("remove:", JSON.stringify(res))
       break
     }
+    case "cleanup-foreign": {
+      const res = cleanupForeignVersionsIfFirstRelease(args.site, args.repo)
+      console.log("cleanup-foreign:", JSON.stringify(res))
+      break
+    }
     case "finalize": {
       const res = finalize({
         siteDir: args.site,