create-grist-widget 0.1.0 → 0.2.2

package/package.json

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

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

@@ -0,0 +1,158 @@
+name: Deploy widget to GitHub Pages
+
+# Two channels, one workflow:
+#   - push to main / manual dispatch -> release channel: immutable
+#     /<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.
+#   - push to dev                    -> dev channel: mutable /<repo>/dev/
+#     with version.json + a self-reload snippet, for live review inside Grist.
+#
+# All logic lives in scripts/deploy.mjs (node builtins only).
+#
+# One-time setup this workflow can't do for you: enable Pages (Settings ->
+# Pages -> Source: Deploy from a branch -> gh-pages -> / (root); this workflow
+# creates the gh-pages branch itself if missing, but Pages must be pointed at
+# it once) and make sure Actions has write access (Settings -> Actions ->
+# General -> Workflow permissions -> Read and write permissions).
+
+on:
+  push:
+    branches: [main, dev]
+  # Retire the dev URL when the `dev` branch is deleted (see `cleanup` job).
+  delete:
+  workflow_dispatch:
+    inputs:
+      force:
+        description: "Rebuild even if v<version> already exists."
+        type: boolean
+        required: false
+        default: false
+
+permissions:
+  contents: write
+
+# Serialize deploys onto the single shared gh-pages branch. deploy.mjs
+# additionally rebases-and-retries on push, so interleaving runs never clobber.
+concurrency:
+  group: pages-gh-pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    # Build/publish on push + manual dispatch. The delete event is handled by `cleanup`.
+    if: github.event_name != 'delete'
+    runs-on: ubuntu-latest
+    env:
+      REPO_NAME: ${{ github.event.repository.name }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Clone gh-pages into ./site
+        run: |
+          git clone --depth 1 --branch gh-pages \
+            "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" site \
+            || {
+              echo "gh-pages branch not found; creating an orphan."
+              git clone --depth 1 "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" site
+              git -C site checkout --orphan gh-pages
+              git -C site rm -rf . >/dev/null 2>&1 || true
+              touch site/.nojekyll
+            }
+          git -C site config user.name  "github-actions[bot]"
+          git -C site config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Resolve deploy plan
+        id: plan
+        run: |
+          PLAN=$(node scripts/deploy.mjs plan \
+            --site site --repo "$REPO_NAME" \
+            --event "${{ github.event_name }}" \
+            --ref "${{ github.ref }}" \
+            ${{ github.event.inputs.force == 'true' && '--force' || '' }})
+          echo "Plan: $PLAN"
+          node -e '
+            const p = JSON.parse(process.argv[1]);
+            const fs = require("fs");
+            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, `version=${p.version || ""}\n`);
+            fs.appendFileSync(out, `base=${p.base}\n`);
+          ' "$PLAN"
+
+      - name: Build
+        if: steps.plan.outputs.skip != 'true'
+        run: |
+          pnpm exec tsc -b
+          pnpm exec vite build --base "${{ steps.plan.outputs.base }}"
+
+      - name: Place build in gh-pages tree
+        if: steps.plan.outputs.skip != 'true'
+        run: |
+          SHA="$(git rev-parse --short HEAD)"
+          VERSION_ARG=""
+          [ -n "${{ steps.plan.outputs.version }}" ] && VERSION_ARG="--version ${{ steps.plan.outputs.version }}"
+          node scripts/deploy.mjs place \
+            --site site --repo "$REPO_NAME" \
+            --channel "${{ steps.plan.outputs.context }}" $VERSION_ARG \
+            --dist dist \
+            --sha "$SHA" --ref "${{ github.ref }}"
+
+      - name: Skip (already published)
+        if: steps.plan.outputs.skip == 'true'
+        run: echo "== skip — v${{ steps.plan.outputs.version }} already published"
+
+      - name: Finalize (commit + push)
+        run: |
+          node scripts/deploy.mjs finalize \
+            --site site --push \
+            --commit-message "deploy: ${{ steps.plan.outputs.context }} @ ${{ github.sha }}"
+
+  cleanup:
+    # When the `dev` branch is deleted, remove /dev/ so the dev URL retires
+    # (404) instead of serving a stale build forever.
+    if: github.event_name == 'delete' && github.event.ref_type == 'branch' && github.event.ref == 'dev'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (default branch — for scripts/deploy.mjs)
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Clone gh-pages into ./site (skip if it does not exist)
+        id: clone
+        run: |
+          if git clone --depth 1 --branch gh-pages \
+              "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" site; then
+            git -C site config user.name  "github-actions[bot]"
+            git -C site config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "gh-pages branch not found; nothing to clean up."
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Remove dev dir + push
+        if: steps.clone.outputs.exists == 'true'
+        run: |
+          node scripts/deploy.mjs remove --site site
+          node scripts/deploy.mjs finalize \
+            --site site --push \
+            --commit-message "cleanup: retire dev URL for ${{ github.event.ref }}"

package/template/README.md

@@ -32,12 +32,32 @@ ignored (the root workspace governs).
 
 ## Deployment
 
-A bundled GitHub Actions workflow that publishes a scaffolded widget to
-**your** GitHub Pages — immutable versioned URLs (`/v<version>/` +
-`/latest/`) plus a push-to-`dev` preview channel, the same model the SDK's
-own widgets use — is still on the roadmap (ROADMAP Phase 2).
-
-> Until then, build with `pnpm build` and host the `dist/` folder on any
-> static host (GitHub Pages, Cloudflare Pages, …). `create-grist-widget`
-> already scaffolds this template via `npm create grist-widget`.
+A bundled GitHub Actions workflow (`.github/workflows/deploy.yml` +
+`scripts/deploy.mjs`) publishes this widget to **your own** GitHub Pages,
+with the same two-channel model the SDK's own widgets use:
+
+- **Push `main`** (after bumping `package.json`'s `version`) → immutable
+  `/v<version>/` + mutable `/latest/`. Re-pushing without a version bump is a
+  no-op — a version is only ever built once.
+- **Push a `dev` branch** → mutable `/dev/`, which self-reloads inside an
+  open Grist document a few seconds after every new push — paste the `/dev/`
+  URL into a Grist doc once, then just keep pushing while you iterate.
+- **Delete the `dev` branch** → `/dev/` is retired automatically.
+
+**One-time setup** (the workflow can't do this part for you):
+
+1. **Settings → Pages** → Source: "Deploy from a branch" → branch `gh-pages`
+   → `/ (root)`. The workflow creates the `gh-pages` branch itself the first
+   time it runs (if it doesn't exist yet), but Pages needs to be pointed at
+   it once.
+2. **Settings → Actions → General → Workflow permissions** → "Read and write
+   permissions". New repos sometimes default the workflow's token to
+   read-only, which would fail the push to `gh-pages` with a 403.
+3. If the repo is private, set **Pages visibility to Public** — a widget
+   embeds inside a Grist iframe, which needs a publicly reachable URL.
+
+No manifest/widget-catalog file is generated — that's a multi-widget,
+Grist-widget-repository concept this single-widget template doesn't need.
+Paste your `/latest/` or `/v<version>/` URL directly into Grist's custom
+widget URL field.
 

package/template/scripts/deploy.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+// Deploy publisher for GitHub Pages (gh-pages branch), single-widget repo.
+//
+// Adapted from the grist-widget-sdk monorepo's scripts/deploy/publish.mjs —
+// same two channels, minus the multi-widget folder loop and manifest.json
+// (there's only one widget here, so nothing to catalog):
+//
+//   release (push to main / workflow_dispatch)
+//     - immutable  /<repo>/v<version>/   (built once, never overwritten)
+//     - mutable    /<repo>/latest/       (alias to newest release)
+//
+//   dev (push to dev)
+//     - mutable    /<repo>/dev/          (+ version.json + self-reload)
+//
+// Design notes: dependency-free (node builtins only). Pure helpers are
+// exported for testing; the CLI is a thin dispatch at the bottom.
+//
+// Subcommands:
+//   plan     --site <dir> --repo <name> --event <push|workflow_dispatch>
+//            --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).
+//
+//   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.
+//
+//   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/.
+//
+//   finalize --site <dir> [--push] [--commit-message <msg>]
+//     Commits + pushes the gh-pages tree with a rebase-and-retry loop.
+
+import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync, cpSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { execFileSync } from "node:child_process"
+
+// ----------------------------------------------------------------------------
+// Pure helpers (exported for tests)
+// ----------------------------------------------------------------------------
+
+/** Absolute Pages base path for a channel, e.g. "/my-widget/v1.2.0/". */
+export function basePathFor(repo, channel, version) {
+  const leaf = channel === "dev" ? "dev" : `v${version}`
+  return `/${repo}/${leaf}/`
+}
+
+/**
+ * Build the release/dev plan from this repo's own package.json + the current
+ * gh-pages tree. Release is skipped when its immutable v<version> dir already
+ * exists (unless force), so re-pushing main without a version bump is a no-op.
+ */
+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") }
+  }
+  const pkg = JSON.parse(readFileSync("package.json", "utf8"))
+  const version = pkg.version
+  if (!version) throw new Error("package.json has no version")
+  const versionDir = join(siteDir, `v${version}`)
+  const exists = existsSync(versionDir)
+  return {
+    context: "release",
+    version,
+    base: basePathFor(repo, "release", version),
+    skip: exists && !force,
+    reason: exists ? (force ? "force-rebuild" : "already-published") : "new-version",
+  }
+}
+
+/** The dev-only self-reload snippet, embedding this build's short SHA. */
+export function selfReloadSnippet(sha) {
+  return `<script>
+/* grist-widget-sdk dev channel: auto-reload when a newer build is published. */
+(function () {
+  var CURRENT = ${JSON.stringify(sha)};
+  var POLL_MS = 5000;
+  async function check() {
+    try {
+      var res = await fetch("version.json?ts=" + Date.now(), { cache: "no-store" });
+      if (!res.ok) return;
+      var data = await res.json();
+      if (data && data.sha && data.sha !== CURRENT) {
+        var url = new URL(location.href);
+        url.searchParams.set("__dev", data.sha); // unique => busts Pages CDN + browser cache
+        location.replace(url.toString());        // preserves Grist's own iframe query params
+      }
+    } catch (e) { /* transient offline / 404 during publish: keep polling */ }
+  }
+  setInterval(check, POLL_MS);
+})();
+</script>`
+}
+
+/** Insert the snippet just before </body> (or append if none). Idempotent-ish: strips a prior block first. */
+export function injectSelfReload(html, sha) {
+  const marker = "grist-widget-sdk dev channel"
+  let out = html
+  if (out.includes(marker)) {
+    out = out.replace(/<script>\s*\/\* grist-widget-sdk dev channel[\s\S]*?<\/script>\s*/g, "")
+  }
+  const snippet = selfReloadSnippet(sha) + "\n"
+  if (out.includes("</body>")) return out.replace("</body>", snippet + "</body>")
+  return out + snippet
+}
+
+// ----------------------------------------------------------------------------
+// Filesystem / git effects
+// ----------------------------------------------------------------------------
+
+function replaceDir(dest, srcDist) {
+  if (existsSync(dest)) rmSync(dest, { recursive: true, force: true })
+  mkdirSync(dirname(dest), { recursive: true })
+  cpSync(srcDist, dest, { recursive: true })
+}
+
+/** Place a freshly built dist into the gh-pages tree. */
+export function placeTarget({ siteDir, channel, version, distDir, sha, ref }) {
+  if (!existsSync(distDir)) throw new Error(`dist not found: ${distDir}`)
+  if (channel === "dev") {
+    const devDir = join(siteDir, "dev")
+    replaceDir(devDir, distDir)
+    writeFileSync(
+      join(devDir, "version.json"),
+      JSON.stringify({ sha, builtAt: new Date().toISOString(), ref: ref || null }, null, 2) + "\n",
+    )
+    const indexPath = join(devDir, "index.html")
+    if (existsSync(indexPath)) {
+      writeFileSync(indexPath, injectSelfReload(readFileSync(indexPath, "utf8"), sha))
+    }
+    return { placed: "dev" }
+  }
+  // release
+  const versionDir = join(siteDir, `v${version}`)
+  replaceDir(versionDir, distDir)
+  const latestDir = join(siteDir, "latest")
+  replaceDir(latestDir, distDir)
+  return { placed: `v${version}`, latest: "latest" }
+}
+
+/**
+ * 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
+ * release or `latest/`. No-op if absent.
+ */
+export function removeDevDir(siteDir) {
+  const devDir = join(siteDir, "dev")
+  if (!existsSync(devDir)) return { removed: false }
+  rmSync(devDir, { recursive: true, force: true })
+  return { removed: true, path: "dev" }
+}
+
+function git(args, cwd) {
+  return execFileSync("git", args, { cwd, encoding: "utf8" }).trim()
+}
+
+function sleep(ms) {
+  // synchronous backoff (deploy step is not latency-sensitive)
+  const end = Date.now() + ms
+  while (Date.now() < end) {}
+}
+
+/** Commit + push the gh-pages tree with a rebase-and-retry loop. */
+export function finalize({ siteDir, push, commitMessage, remoteBranch = "gh-pages" }) {
+  git(["add", "-A"], siteDir)
+  const status = git(["status", "--porcelain"], siteDir)
+  if (!status) {
+    console.log("deploy: nothing to commit (no-op)")
+    return { committed: false }
+  }
+  git(["commit", "-m", commitMessage || "deploy: publish widget"], siteDir)
+  if (!push) return { committed: true, pushed: false }
+
+  let lastErr
+  for (let attempt = 1; attempt <= 4; attempt++) {
+    try {
+      git(["push", "origin", `HEAD:${remoteBranch}`], siteDir)
+      return { committed: true, pushed: true, attempts: attempt }
+    } catch (err) {
+      lastErr = err
+      console.warn(`deploy: push attempt ${attempt} failed, rebasing on origin/${remoteBranch}`)
+      try {
+        git(["fetch", "origin", remoteBranch], siteDir)
+        git(["rebase", `origin/${remoteBranch}`], siteDir)
+      } catch (rebaseErr) {
+        git(["rebase", "--abort"], siteDir)
+        throw rebaseErr
+      }
+      if (attempt < 4) sleep(2000 * 2 ** (attempt - 1)) // 2s,4s,8s
+    }
+  }
+  throw lastErr
+}
+
+// ----------------------------------------------------------------------------
+// CLI
+// ----------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const out = { _: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith("--")) {
+      const key = a.slice(2)
+      const next = argv[i + 1]
+      if (next === undefined || next.startsWith("--")) out[key] = true
+      else { out[key] = next; i++ }
+    } else out._.push(a)
+  }
+  return out
+}
+
+function main() {
+  const [cmd, ...rest] = process.argv.slice(2)
+  const args = parseArgs(rest)
+
+  switch (cmd) {
+    case "plan": {
+      const result = plan(args.site, args.repo, args.event, args.ref, { force: !!args.force })
+      process.stdout.write(JSON.stringify(result))
+      break
+    }
+    case "place": {
+      const res = placeTarget({
+        siteDir: args.site,
+        channel: args.channel,
+        version: args.version,
+        distDir: args.dist,
+        sha: args.sha,
+        ref: args.ref,
+      })
+      console.log("placed:", JSON.stringify(res))
+      break
+    }
+    case "remove": {
+      const res = removeDevDir(args.site)
+      console.log("remove:", JSON.stringify(res))
+      break
+    }
+    case "finalize": {
+      const res = finalize({
+        siteDir: args.site,
+        push: !!args.push,
+        commitMessage: args["commit-message"],
+      })
+      console.log("finalize:", JSON.stringify(res))
+      break
+    }
+    default:
+      console.error(`unknown subcommand: ${cmd || "(none)"}`)
+      process.exit(2)
+  }
+}
+
+// Only run the CLI when executed directly (not when imported by tests).
+if (import.meta.url === `file://${process.argv[1]}`) main()