create-grist-widget 0.2.23 → 0.2.25

package/package.json

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

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

@@ -2,22 +2,18 @@ name: Deploy widget to GitHub Pages
 
 # Two channels, one workflow:
 #   - push to main / manual dispatch -> release channel: immutable
-#     /<repo>/v<version>/ + mutable /<repo>/latest/.
+#     /<repo>/v<version>/ + mutable /<repo>/latest/, plus the same build at
+#     the site root (the showcase hub landing page).
 #     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.
+#     A repo's first genuine release always resolves to v0.0.1 regardless of
+#     package.json's version, so "Use this template" (whose initial push to
+#     main by GitHub's web-flow bot fires this workflow) publishes a clean
+#     v0.0.1 + /latest/ + root right away, discarding any inherited canary
+#     version. On that same first release, the "Reset repo to a clean
+#     first-release state" step below rewrites package.json's version back to
+#     0.0.1 in the repo itself, so the *next* release bumps to 0.0.2 rather
+#     than the inherited number.
 #   - push to dev                    -> dev channel: mutable /<repo>/dev/
 #     with version.json + a self-reload snippet, for live review inside Grist.
 #
@@ -104,8 +100,7 @@ jobs:
             --site site --repo "$REPO_NAME" \
             --event "${{ github.event_name }}" \
             --ref "${{ github.ref }}" \
-            ${{ github.event.inputs.force == 'true' && '--force' || '' }} \
-            ${{ github.event.created == true && github.event.head_commit.committer.email == 'noreply@github.com' && '--created' || '' }})
+            ${{ github.event.inputs.force == 'true' && '--force' || '' }})
           echo "Plan: $PLAN"
           node -e '
             const p = JSON.parse(process.argv[1]);
@@ -113,7 +108,6 @@ 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`);
@@ -138,19 +132,9 @@ jobs:
             --sha "$SHA" --ref "${{ github.ref }}"
 
       - name: Skip (already published)
-        if: steps.plan.outputs.skip == 'true' && steps.plan.outputs.reason != 'ref-created'
+        if: steps.plan.outputs.skip == 'true'
         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=""
@@ -161,15 +145,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).
+      # On this repo's first genuine release only: reset package.json's version
+      # to 0.0.1 (so the next release bumps to 0.0.2 rather than any inherited
+      # canary version), prune every branch except main/dev/gh-pages, and
+      # reset dev to main's current tip. Establishes the state every widget
+      # should start from regardless of how the repo was created -- a CLI
+      # scaffold already satisfies it trivially; a repo copied via GitHub's
+      # "Use this template" often doesn't (an inherited version, a stray
+      # branch, or dev tracking the source template's own preview history).
       # Placed after Finalize so it never runs if the release itself failed.
-      - name: Reset branches on first genuine release
+      # The version-reset commit re-triggers this workflow on main, but that
+      # run sees v0.0.1 already published (firstRelease=false) and no-ops.
+      - name: Reset repo to a clean first-release state
         if: steps.plan.outputs.context == 'release' && steps.plan.outputs.firstRelease == 'true'
         run: node scripts/deploy.mjs reset-branches
 

package/template/README.md

@@ -90,39 +90,32 @@ automatically.
 > 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 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
+> source repo's `package.json` (which can be well past `0.0.1`) comes along
+> with it. **The moment the repo is created, GitHub's own initial push to
+> `main` fires this workflow and publishes a clean `v0.0.1`** — your first
 > 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.
->
-> "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.
+> says, so `/`, `/latest/`, and `/v0.0.1/` all go live right away (once
+> you've done the one-time Pages setup below). You don't reset the version
+> by hand: on that first release the pipeline also **rewrites
+> `package.json`'s version back to `0.0.1` in the repo itself** (a commit it
+> pushes to `main`/`dev`), so your *next* release naturally bumps to
+> `0.0.2` instead of jumping to whatever inherited number you started with.
+> If you also checked **"Include all branches"** (to get `gh-pages`/Pages
+> already set up, no manual Settings step), that first release also clears
+> out every leftover bit of inherited content it finds — stray
+> `v<version>/` dirs, and a root/`latest/` still pointing at the *source*
+> repo's own path — before writing its own. A `v<version>/` only counts as
+> a genuine prior release once it carries a `showcase-meta.json` naming
+> *this* repo, so on a repo with no genuine releases yet, everything else is
+> provably inherited noise and gets safely replaced. On that same first
+> release, every branch except `main`, `dev`, and `gh-pages` is pruned and
+> `dev` is force-reset to match `main`'s tip — a fresh widget always starts
+> from `main == dev`, 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 of this only ever
+> applies 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.
 
 **One-time setup** (the workflow can't do this part for you):
 

package/template/scripts/deploy.mjs

@@ -19,27 +19,18 @@
 //
 // Subcommands:
 //   plan     --site <dir> --repo <name> --event <push|workflow_dispatch>
-//            --ref <ref> [--force] [--created]
+//            --ref <ref> [--force]
 //     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.
+//     A repo's first genuine release always resolves to v0.0.1 regardless of
+//     package.json's version -- so "Use this template" (whose initial push
+//     to main fires this workflow) publishes a clean v0.0.1 straight away.
 //
 //   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/.
@@ -50,7 +41,8 @@
 //
 //   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
+//     firstRelease): resets package.json's version to 0.0.1, prunes every
+//     branch except main/dev/gh-pages, and
 //     force-resets dev to main's current tip.
 
 import {
@@ -113,7 +105,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, created = false } = {}) {
+export function plan(siteDir, repo, event, ref, { force = false } = {}) {
   const isRelease = event === "workflow_dispatch" || ref === "refs/heads/main" || ref === "main"
   if (!isRelease) {
     return { context: "dev", base: basePathFor(repo, "dev") }
@@ -123,35 +115,20 @@ export function plan(siteDir, repo, event, ref, { force = false, created = false
   // 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`.
+  // had been promoted there), instead of starting fresh. This is what makes
+  // "Use this template" publish a clean v0.0.1 the moment the repo is
+  // created (GitHub's own initial push to main fires this workflow): the
+  // copy's inherited canary version is ignored for that first release. To
+  // keep the *next* release clean too, the workflow's first-release reset
+  // step rewrites package.json's version back to 0.0.1 in the repo itself
+  // (see `resetBranchesIfFirstRelease`), so the second release naturally
+  // bumps from 0.0.1 rather than the inherited canary number. Once a repo
+  // has a genuine release, this override no longer applies -- its own
+  // version bumps are its own responsibility from then on.
   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}`)
-  // 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",
@@ -254,11 +231,11 @@ function replaceDir(dest, srcDist) {
  * 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
+ * pointed at `/grist-widget-template/v0.2.22/assets/...`, which 404s on
+ * this repo's own Pages site). Called by `placeTarget` right before it
+ * writes this repo's own first release, so the inherited noise is replaced
+ * rather than layered under. 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.
  */
@@ -372,19 +349,50 @@ export function finalize({ siteDir, updateVersions, push, commitMessage, remoteB
 }
 
 /**
- * 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.
+ * Establish the state every widget repo should start from, on its first
+ * genuine release only (gated by the caller on `plan()`'s `firstRelease`):
+ *
+ *   1. Reset package.json's version to 0.0.1. The first release already
+ *      published v0.0.1 (forced by plan() regardless of package.json), but a
+ *      repo copied via GitHub's "Use this template" still carries the source
+ *      template's inherited canary version in the file (found live: a copy
+ *      shipped 0.2.23) -- so its *next* release would jump straight to
+ *      v0.2.24 instead of a clean v0.0.2. Rewriting the file to 0.0.1 here,
+ *      committed to main, makes the next bump land on 0.0.2. A CLI scaffold
+ *      already ships 0.0.1, so this is a no-op there.
+ *   2. main == dev, gh-pages CI-managed only: prune every other branch and
+ *      force-reset `dev` to `main`'s current tip (which now carries the
+ *      version-reset commit). A CLI scaffold satisfies this trivially; a
+ *      "Use this template" copy may have a stray inherited branch, or a
+ *      `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. The
+ * version-reset commit re-triggers this workflow on main, but that run sees
+ * a genuine release already published (firstRelease=false) and skips both
+ * the release and this reset, so there's no loop.
  */
 export function resetBranchesIfFirstRelease(repoDir, keep = ["main", "dev", "gh-pages"]) {
+  let versionReset = false
+  const pkgPath = join(repoDir, "package.json")
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"))
+    if (pkg.version !== "0.0.1") {
+      pkg.version = "0.0.1"
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n")
+      git(["add", "package.json"], repoDir)
+      git(
+        [
+          "-c", "user.name=github-actions[bot]",
+          "-c", "user.email=41898282+github-actions[bot]@users.noreply.github.com",
+          "commit", "-m", "chore: reset version to 0.0.1 for a clean first release",
+        ],
+        repoDir,
+      )
+      git(["push", "origin", "HEAD:refs/heads/main"], repoDir)
+      versionReset = true
+    }
+  }
   const raw = git(["ls-remote", "--heads", "origin"], repoDir)
   const branches = raw
     ? raw.split("\n").map((line) => line.split("refs/heads/")[1]).filter(Boolean)
@@ -396,7 +404,7 @@ export function resetBranchesIfFirstRelease(repoDir, keep = ["main", "dev", "gh-
     deletedBranches.push(b)
   }
   git(["push", "--force", "origin", "HEAD:refs/heads/dev"], repoDir)
-  return { deletedBranches, devReset: true }
+  return { deletedBranches, devReset: true, versionReset }
 }
 
 // ----------------------------------------------------------------------------
@@ -425,7 +433,6 @@ function main() {
     case "plan": {
       const result = plan(args.site, args.repo, args.event, args.ref, {
         force: !!args.force,
-        created: !!args.created,
       })
       process.stdout.write(JSON.stringify(result))
       break
@@ -448,11 +455,6 @@ 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,