create-grist-widget 0.2.23 → 0.2.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-grist-widget",
-  "version": "0.2.23",
+  "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

@@ -14,10 +14,12 @@ name: Deploy widget to GitHub Pages
 #     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.
+#     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.
 #
@@ -119,8 +121,11 @@ jobs:
             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 }}"
@@ -141,15 +146,24 @@ jobs:
         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 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)
+      # 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"
+        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: |

package/template/README.md

@@ -115,14 +115,17 @@ 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'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.
+> 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

@@ -40,6 +40,12 @@
 //     `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/.
@@ -143,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,
@@ -313,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
@@ -453,6 +491,11 @@ function main() {
       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,