create-grist-widget 0.2.20 → 0.2.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-grist-widget",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "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,12 @@ 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.
 #   - push to dev                    -> dev channel: mutable /<repo>/dev/
 #     with version.json + a self-reload snippet, for live review inside Grist.
 #
@@ -91,7 +97,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 && '--created' || '' }})
           echo "Plan: $PLAN"
           node -e '
             const p = JSON.parse(process.argv[1]);

package/template/README.md

@@ -111,6 +111,13 @@ 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 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.
 
 **One-time setup** (the workflow can't do this part for you):
 

package/template/scripts/deploy.mjs

@@ -19,10 +19,13 @@
 //
 // 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 (github.event.created off a push event) additionally skips
+//     unconditionally, without consuming the first-release version override
+//     -- see plan()'s own comment.
 //
 //   place    --site <dir> --repo <name> --channel <release|dev>
 //            [--version <v>] --dist <dir> --sha <sha> [--ref <ref>]
@@ -101,7 +104,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 +121,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",
@@ -151,6 +176,12 @@ export function selfReloadSnippet(sha) {
       }
     } catch (e) { /* transient offline / 404 during publish: keep polling */ }
   }
+  check(); // don't wait a full POLL_MS for the first check -- a plain
+           // (non-cache-busted) request for this very page can hit a stale
+           // CDN-cached index.html referencing JS assets a newer deploy
+           // already deleted, producing a blank/black screen until this
+           // fires; found live, waiting the full interval left that
+           // black screen up for ~5s on a fresh visit.
   setInterval(check, POLL_MS);
 })();
 </script>`
@@ -376,7 +407,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
     }