create-grist-widget 0.2.22 → 0.2.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-grist-widget",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "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,21 @@ 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 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`, and places the freshly
+#     built showcase hub at the site root via `place-root`, so the bare
+#     repo-root URL works immediately instead of 404ing until the widget's
+#     real first release. It just never creates a v<version>/ or latest/.
 #   - push to dev                    -> dev channel: mutable /<repo>/dev/
 #     with version.json + a self-reload snippet, for live review inside Grist.
 #
@@ -98,7 +107,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,13 +115,17 @@ 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`);
           ' "$PLAN"
 
+      # Also builds on the ref-created push (skip == 'true' there), but with
+      # the root base plan() hands back for that case (/<repo>/, not a
+      # versioned path) -- see the "landing hub" step below.
       - name: Build
-        if: steps.plan.outputs.skip != 'true'
+        if: steps.plan.outputs.skip != 'true' || steps.plan.outputs.reason == 'ref-created'
         run: |
           pnpm exec tsc -b
           pnpm exec vite build --base "${{ steps.plan.outputs.base }}"
@@ -130,9 +143,28 @@ 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 "Use this template" push publishes no versioned
+      # release (that would spend the first-release override on unmodified
+      # boilerplate -- see plan()), so it never reaches Place. But it still:
+      #   1. clears any foreign content the copy brought along
+      #      (cleanupForeignVersionsIfFirstRelease, normally a side effect of
+      #      Place) -- stray v<version>/ dirs, a root/latest/ pointing at the
+      #      source repo's own path; then
+      #   2. places the freshly built showcase hub at the site root, so
+      #      https://owner.github.io/<repo>/ isn't a bare 404 until the
+      #      widget's first real release (the CLI path gets a working root on
+      #      its own genuine first push; this makes the template-copy path
+      #      match). No v<version>/ or latest/ -- those stay absent, correctly
+      #      404ing, until a real release exists.
+      - name: Clean foreign content + place landing hub (ref-created push)
+        if: steps.plan.outputs.reason == 'ref-created'
+        run: |
+          node scripts/deploy.mjs cleanup-foreign --site site --repo "$REPO_NAME"
+          node scripts/deploy.mjs place-root --site site --dist dist
+
       - name: Finalize (versions.json + commit + push)
         run: |
           UPDATE_VERSIONS=""

package/template/README.md

@@ -114,10 +114,18 @@ 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 **publishes no versioned release**: 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. It does two useful
+> things, though: if you checked "Include all branches", it clears out
+> whatever foreign content came along (stray `v<version>/` dirs, a
+> root/`latest/` still pointing at the *source* repo's own path); and it
+> places the landing page at your repo-root URL so
+> `https://<you>.github.io/<repo>/` works right away, instead of 404ing
+> until your first real release. Your `/latest/` and `/v<version>/` URLs
+> stay absent (they 404) until you actually publish — there's no release to
+> point them at yet.
 
 **One-time setup** (the workflow can't do this part for you):
 

package/template/scripts/deploy.mjs

@@ -23,14 +23,29 @@
 //     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.
+//
+//   place-root --site <dir> --dist <dir>
+//     Place a root-based build (built with base "/<repo>/") at the site
+//     root only -- the showcase hub landing page. Used on the ref-created
+//     push so the bare repo-root URL works before the first real release,
+//     without publishing a versioned release. Run after `cleanup-foreign`.
+//
 //   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/.
@@ -134,10 +149,21 @@ export function plan(siteDir, repo, event, ref, { force = false, created = false
   // gh-pages) keeps hasGenuineRelease() false, so the override survives
   // intact for whenever a real release actually happens.
   if (created && event === "push") {
+    // Publish no versioned release (so the first-release override above
+    // survives), but the caller still builds + places the showcase hub at
+    // the site root -- otherwise https://owner.github.io/<repo>/ is a bare
+    // 404 until the widget's first real release (found live on a fresh "Use
+    // this template" copy). The hub renders for any URL with no channel
+    // suffix, the bare root included (see main.tsx), so it must be built
+    // based at the repo root (/<repo>/), not a versioned path -- hence the
+    // root base here rather than basePathFor's v<version>/. The workflow
+    // keys off reason === "ref-created" to build with this base and place
+    // root-only. `skip` stays true so the normal versioned place/finalize
+    // path is bypassed.
     return {
       context: "release",
       version,
-      base: basePathFor(repo, "release", version),
+      base: `/${repo}/`,
       skip: true,
       reason: "ref-created",
       firstRelease,
@@ -237,21 +263,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)
   }
@@ -297,6 +330,27 @@ export function placeTarget({ siteDir, channel, version, distDir, sha, ref, repo
   return { placed: `v${version}`, latest: "latest", root: true }
 }
 
+/**
+ * Place a root-based build (built with base "/<repo>/") at the gh-pages site
+ * root only -- the showcase hub landing page, nothing else. Used on the
+ * ref-created "Use this template" push (see plan()): publishes no versioned
+ * release, so the first-release override survives, but keeps the bare
+ * repo-root URL from 404ing until that first real release (found live: a
+ * fresh copy's https://owner.github.io/<repo>/ was a 404, since the initial
+ * deploy that used to place this hub now publishes nothing). Never creates a
+ * v<version>/ or latest/. On the first genuine release, placeTarget's own
+ * cleanupForeignVersionsIfFirstRelease clears this hub (root index.html +
+ * assets/) before placing the release's own root copy, so nothing lingers.
+ * Callers run `cleanup-foreign` first, so a re-triggered ref-created run
+ * replaces the hub cleanly rather than layering onto stale files.
+ */
+export function placeRootHub({ siteDir, distDir }) {
+  if (!existsSync(distDir)) throw new Error(`dist not found: ${distDir}`)
+  mkdirSync(siteDir, { recursive: true })
+  cpSync(distDir, siteDir, { recursive: true })
+  return { placed: "root" }
+}
+
 /**
  * Remove the mutable dev dir from the gh-pages tree (retire the dev URL when
  * the `dev` branch is deleted). Only ever touches `dev/` — never a versioned
@@ -432,6 +486,16 @@ 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 "place-root": {
+      const res = placeRootHub({ siteDir: args.site, distDir: args.dist })
+      console.log("place-root:", JSON.stringify(res))
+      break
+    }
     case "finalize": {
       const res = finalize({
         siteDir: args.site,