create-grist-widget 0.2.22 → 0.2.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-grist-widget",
-  "version": "0.2.22",
+  "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,12 +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 (github.event.created) -- fired by
-#     GitHub's "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.
+#     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.
 #
@@ -98,7 +105,7 @@ jobs:
             --event "${{ github.event_name }}" \
             --ref "${{ github.ref }}" \
             ${{ github.event.inputs.force == 'true' && '--force' || '' }} \
-            ${{ github.event.created == true && '--created' || '' }})
+            ${{ 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]);
@@ -106,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`);
@@ -130,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

@@ -114,10 +114,15 @@ automatically.
 >
 > "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 marks it as the push
-> that *created* 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.
+> 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

@@ -23,14 +23,23 @@
 //     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 (github.event.created off a push event) additionally skips
-//     unconditionally, without consuming the first-release version override
-//     -- see plan()'s own comment.
+//     --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/.
@@ -237,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)
   }
@@ -432,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,