create-grist-widget 0.2.19 → 0.2.20

package/package.json

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

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

@@ -101,6 +101,7 @@ jobs:
             fs.appendFileSync(out, `skip=${p.skip ? "true" : "false"}\n`);
             fs.appendFileSync(out, `version=${p.version || ""}\n`);
             fs.appendFileSync(out, `base=${p.base}\n`);
+            fs.appendFileSync(out, `firstRelease=${p.firstRelease ? "true" : "false"}\n`);
           ' "$PLAN"
 
       - name: Build
@@ -135,6 +136,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).
+      # Placed after Finalize so it never runs if the release itself failed.
+      - name: Reset branches on first genuine release
+        if: steps.plan.outputs.context == 'release' && steps.plan.outputs.firstRelease == 'true'
+        run: node scripts/deploy.mjs reset-branches
+
   cleanup:
     # When the `dev` branch is deleted, remove /dev/ so the dev URL retires
     # (404) instead of serving a stale build forever.

package/template/README.md

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

package/template/scripts/deploy.mjs

@@ -35,6 +35,11 @@
 //   finalize --site <dir> [--update-versions] [--push] [--commit-message <msg>]
 //     Regenerates versions.json (release runs only) and commits + pushes the
 //     gh-pages tree with a rebase-and-retry loop.
+//
+//   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
+//     force-resets dev to main's current tip.
 
 import {
   existsSync,
@@ -109,7 +114,8 @@ export function plan(siteDir, repo, event, ref, { force = false } = {}) {
   // 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"
+  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}`)
   const exists = isGenuineRelease(versionDir, repo)
@@ -119,6 +125,10 @@ export function plan(siteDir, repo, event, ref, { force = false } = {}) {
     base: basePathFor(repo, "release", version),
     skip: exists && !force,
     reason: exists ? (force ? "force-rebuild" : "already-published") : "new-version",
+    // Exposed so the workflow can gate a one-time repo cleanup (prune stray
+    // branches, reset dev to main) on exactly this signal -- see
+    // `resetBranchesIfFirstRelease`.
+    firstRelease,
   }
 }
 
@@ -314,6 +324,34 @@ export function finalize({ siteDir, updateVersions, push, commitMessage, remoteB
   throw lastErr
 }
 
+/**
+ * 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.
+ */
+export function resetBranchesIfFirstRelease(repoDir, keep = ["main", "dev", "gh-pages"]) {
+  const raw = git(["ls-remote", "--heads", "origin"], repoDir)
+  const branches = raw
+    ? raw.split("\n").map((line) => line.split("refs/heads/")[1]).filter(Boolean)
+    : []
+  const deletedBranches = []
+  for (const b of branches) {
+    if (keep.includes(b)) continue
+    git(["push", "origin", "--delete", b], repoDir)
+    deletedBranches.push(b)
+  }
+  git(["push", "--force", "origin", "HEAD:refs/heads/dev"], repoDir)
+  return { deletedBranches, devReset: true }
+}
+
 // ----------------------------------------------------------------------------
 // CLI
 // ----------------------------------------------------------------------------
@@ -371,6 +409,11 @@ function main() {
       console.log("finalize:", JSON.stringify(res))
       break
     }
+    case "reset-branches": {
+      const res = resetBranchesIfFirstRelease(args["repo-dir"] || ".")
+      console.log("reset-branches:", JSON.stringify(res))
+      break
+    }
     default:
       console.error(`unknown subcommand: ${cmd || "(none)"}`)
       process.exit(2)