create-grist-widget 0.2.16 → 0.2.17

package/package.json

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

package/template/README.md

@@ -91,13 +91,16 @@ automatically.
 > it doesn't run any of the CLI's own setup (renaming `package.json`,
 > titles, etc.), and it won't reset `package.json`'s `version` back to a
 > fresh `0.0.1` for you. Do both by hand before your first real release.
-> Also **never manually seed/copy `gh-pages` content** from another repo
-> (e.g. to get Pages showing something immediately) — each `v<version>/`
-> is only recognized as a genuine prior release if it carries a
+> If you also checked **"Include all branches"** (to get `gh-pages`/Pages
+> already set up, no manual Settings step), your first real release
+> 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); anything else is treated as unpublished and safely
-> rebuilt over, but it's simpler to just let the workflow create
-> `gh-pages` itself (it does, as an orphan branch, on its first real run).
+> `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`. That cleanup only ever runs 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

@@ -177,6 +177,29 @@ function replaceDir(dest, srcDist) {
   cpSync(srcDist, dest, { recursive: true })
 }
 
+/**
+ * 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.
+ */
+export function cleanupForeignVersionsIfFirstRelease(siteDir, repo) {
+  if (buildVersionsManifest(siteDir, repo).length > 0) return { cleaned: [] }
+  const cleaned = []
+  for (const name of existsSync(siteDir) ? readdirSync(siteDir) : []) {
+    if (!/^v\d+\.\d+\.\d+/.test(name)) continue
+    rmSync(join(siteDir, name), { recursive: true, force: true })
+    cleaned.push(name)
+  }
+  return { cleaned }
+}
+
 /** Place a freshly built dist into the gh-pages tree. */
 export function placeTarget({ siteDir, channel, version, distDir, sha, ref, repo }) {
   if (!existsSync(distDir)) throw new Error(`dist not found: ${distDir}`)
@@ -202,6 +225,7 @@ export function placeTarget({ siteDir, channel, version, distDir, sha, ref, repo
   // exactly like latest/ reusing it: the asset URLs it references (under
   // v<version>/assets/) already exist from the versionDir placement above,
   // so nothing 404s.
+  cleanupForeignVersionsIfFirstRelease(siteDir, repo)
   const versionDir = join(siteDir, `v${version}`)
   replaceDir(versionDir, distDir)
   writeFileSync(