create-grist-widget 0.3.26 → 0.3.27

package/bin/create-grist-widget.mjs

@@ -223,7 +223,7 @@ function printAgeExceptionsNote(ageExceptions) {
     `\nNote: ${ageExceptions.join(", ")} came out less than 24 hours ago. pnpm only installs versions` +
       "\nthat recent when told to, so it listed them under minimumReleaseAgeExclude in pnpm-workspace.yaml." +
       "\nThat entry is committed: without it, every later install (yours and CI's) rejects the lockfile." +
-      "\nIt only covers the SDK released together with this CLI, and is moot once the version is a day old."
+      "\nIt only covers the SDK and CLI versions this scaffold was made with, and is moot once a day old."
   )
 }
 

package/bin/grist-widget-deploy.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// grist-widget-deploy — the GitHub Pages deploy steps a widget's
+// .github/workflows/deploy.yml runs (plan, place, remove, finalize,
+// reset-branches). See src/deploy.mjs for what each one does.
+//
+// The publish job runs this next to a `contents: write` token, after an
+// install with --ignore-scripts, so this file and src/deploy.mjs must import
+// node builtins only: no other dependency code may run there
+// (tests/deploy-imports.test.mjs).
+
+import {
+  finalize,
+  placeTarget,
+  plan,
+  removeDevDir,
+  resetBranchesIfFirstRelease,
+} from "../src/deploy.mjs"
+
+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
+}
+
+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,
+      repo: args.repo,
+    })
+    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,
+      updateVersions: !!args["update-versions"],
+      push: !!args.push,
+      commitMessage: args["commit-message"],
+      repo: args.repo,
+    })
+    console.log("finalize:", JSON.stringify(res))
+    break
+  }
+  case "reset-branches": {
+    const res = resetBranchesIfFirstRelease(
+      args["repo-dir"] || ".",
+      args.repo,
+      undefined,
+      args["owner-repo"] || process.env.GITHUB_REPOSITORY
+    )
+    console.log("reset-branches:", JSON.stringify(res))
+    break
+  }
+  default:
+    console.error(
+      `grist-widget-deploy: unknown subcommand "${cmd || "(none)"}". ` +
+        "Expected plan, place, remove, finalize or reset-branches."
+    )
+    process.exit(2)
+}

package/examples/reads-demo/WidgetApp.tsx

@@ -7,7 +7,8 @@ import {
 } from "grist-widget-sdk"
 
 export const GRIST_OPTIONS: UseGristOptions = {
-  requiredAccess: "read table",
+  // fetchTableRows and fetchRow read any table, which Grist only allows with full document access.
+  requiredAccess: "full",
 }
 
 export const WIDGET_METADATA = {

package/examples/safe-parse/WidgetApp.tsx

@@ -10,7 +10,8 @@ import {
 type TaskRow = { Title: string; Due: Date | null }
 
 export const GRIST_OPTIONS: UseGristOptions = {
-  requiredAccess: "read table",
+  // fetchTable reads any table, which Grist only allows with full document access.
+  requiredAccess: "full",
   suppressAlerts: ["section-not-linked"],
 }
 

package/manifest.json

@@ -134,7 +134,7 @@
     "id": "reads-demo",
     "title": "Reads demo",
     "description": "listTables, fetchTableRows, fetchRow, fetchSelectedRecord.",
-    "requiredAccess": "read table",
+    "requiredAccess": "full",
     "columns": [],
     "allowSelectBy": false,
     "hasCustomOptions": false,
@@ -160,7 +160,7 @@
     "id": "safe-parse",
     "title": "Safe parse",
     "description": "safeParseGristTableData with per-cell issues.",
-    "requiredAccess": "read table",
+    "requiredAccess": "full",
     "columns": [],
     "allowSelectBy": false,
     "hasCustomOptions": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-grist-widget",
-  "version": "0.3.26",
+  "version": "0.3.27",
   "description": "Scaffold a new Grist custom widget from the grist-widget-sdk Vite template",
   "license": "MIT",
   "type": "module",
@@ -8,7 +8,8 @@
     "node": "^22.22.0 || >=24.15.0"
   },
   "bin": {
-    "create-grist-widget": "./bin/create-grist-widget.mjs"
+    "create-grist-widget": "./bin/create-grist-widget.mjs",
+    "grist-widget-deploy": "./bin/grist-widget-deploy.mjs"
   },
   "files": [
     "bin",

package/{template/scripts → src}/deploy.mjs

@@ -1,6 +1,11 @@
-#!/usr/bin/env node
 // Deploy publisher for GitHub Pages (gh-pages branch), single-widget repo.
 //
+// Shipped in create-grist-widget and run through its `grist-widget-deploy`
+// bin (bin/grist-widget-deploy.mjs) by a widget's .github/workflows/deploy.yml,
+// so a fix reaches every widget as a dependency update. The publish job runs
+// it next to a `contents: write` token: it imports node builtins only, which
+// tests/deploy-imports.test.mjs enforces.
+//
 // 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):
@@ -15,7 +20,7 @@
 //     - 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.
+// exported for testing; the CLI is a thin dispatch in bin/grist-widget-deploy.mjs.
 //
 // Subcommands:
 //   plan     --site <dir> --repo <name> --event <push|workflow_dispatch>
@@ -347,7 +352,9 @@ function git(args, cwd) {
 function sleep(ms) {
   // synchronous backoff (deploy step is not latency-sensitive)
   const end = Date.now() + ms
-  while (Date.now() < end) {}
+  while (Date.now() < end) {
+    // busy-wait: the retry loop runs synchronously
+  }
 }
 
 /** Regenerate versions.json (release runs only), then commit + push with rebase-retry. */
@@ -572,81 +579,3 @@ export function resetBranchesIfFirstRelease(
   git(["push", "--force", "origin", "HEAD:refs/heads/dev"], repoDir)
   return { deletedBranches, devReset: true, versionReset, identityReset, renamedFiles, installUrl }
 }
-
-// ----------------------------------------------------------------------------
-// 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,
-        repo: args.repo,
-      })
-      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,
-        updateVersions: !!args["update-versions"],
-        push: !!args.push,
-        commitMessage: args["commit-message"],
-        repo: args.repo,
-      })
-      console.log("finalize:", JSON.stringify(res))
-      break
-    }
-    case "reset-branches": {
-      const res = resetBranchesIfFirstRelease(
-        args["repo-dir"] || ".",
-        args.repo,
-        undefined,
-        args["owner-repo"] || process.env.GITHUB_REPOSITORY,
-      )
-      console.log("reset-branches:", 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()

package/template/.github/dependabot.yml

@@ -21,12 +21,13 @@ updates:
     cooldown:
       default-days: 7
     groups:
-      # Minor/patch bumps arrive together as one PR. grist-widget-sdk is
-      # left out so its updates get a PR of their own, whose description
-      # links its release notes.
+      # Minor/patch bumps arrive together as one PR. grist-widget-sdk and
+      # create-grist-widget (the deploy command deploy.yml runs) are left out
+      # so their updates get a PR of their own, whose description links
+      # their release notes.
       routine:
         update-types: ["minor", "patch"]
-        exclude-patterns: ["grist-widget-sdk"]
+        exclude-patterns: ["grist-widget-sdk", "create-grist-widget"]
       # @vitejs/plugin-react pins a vite major in its peer range, so their
       # majors only build when they move together.
       vite:

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

@@ -21,12 +21,16 @@ name: Deploy widget to GitHub Pages
 #   - 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).
+# All logic lives in the `grist-widget-deploy` command of create-grist-widget,
+# a devDependency (node builtins only), so deploy fixes arrive as dependency
+# updates.
 #
 # Two jobs, so no dependency code ever runs next to a write token. `build`
 # installs and builds (Vite and its plugins are third-party code) with a
 # read-only token, and hands dist/ over as an artifact. `publish` holds
-# `contents: write` but installs nothing: it only runs scripts/deploy.mjs.
+# `contents: write`: it installs with --ignore-scripts, so no dependency code
+# runs, and then runs grist-widget-deploy alone, at the version the lockfile
+# pins.
 #
 # One-time setup this workflow can't do for you: enable Pages (Settings ->
 # Pages -> Source: Deploy from a branch -> gh-pages -> / (root); this workflow
@@ -53,7 +57,7 @@ on:
 # Nothing at workflow level: each job states what it needs.
 permissions: {}
 
-# Serialize deploys onto the single shared gh-pages branch. deploy.mjs
+# Serialize deploys onto the single shared gh-pages branch. grist-widget-deploy
 # additionally rebases-and-retries on push, so interleaving runs never clobber.
 concurrency:
   group: pages-gh-pages
@@ -130,7 +134,7 @@ jobs:
           REF: ${{ github.ref }}
           FORCE: ${{ github.event.inputs.force == 'true' && '--force' || '' }}
         run: |
-          PLAN=$(node scripts/deploy.mjs plan \
+          PLAN=$(node_modules/.bin/grist-widget-deploy plan \
             --site site --repo "$REPO_NAME" \
             --event "$EVENT_NAME" \
             --ref "$REF" \
@@ -179,16 +183,26 @@ jobs:
       REF: ${{ github.ref }}
     steps:
       # Credentials stay persisted here: the first-release reset below pushes
-      # with them. Nothing in this job installs or runs dependency code.
+      # with them. No dependency code runs in this job (see the install step).
       - name: Checkout
         uses: actions/checkout@v7
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+
       - name: Setup Node
         uses: actions/setup-node@v7
         with:
           node-version: 22
           package-manager-cache: false
 
+      # Only for grist-widget-deploy, at the version (and integrity hash) the
+      # lockfile pins. --ignore-scripts: no dependency's install script runs,
+      # and the steps below call the bin directly, never through `pnpm
+      # exec`/`pnpm run`, whose dependency check may reinstall with scripts.
+      - name: Install the deploy command
+        run: pnpm install --ignore-scripts
+
       - name: Clone gh-pages into ./site
         env:
           GH_TOKEN: ${{ github.token }}
@@ -219,7 +233,7 @@ jobs:
           SHA="$(git rev-parse --short HEAD)"
           VERSION_ARG=""
           [ -n "$VERSION" ] && VERSION_ARG="--version $VERSION"
-          node scripts/deploy.mjs place \
+          node_modules/.bin/grist-widget-deploy place \
             --site site --repo "$REPO_NAME" \
             --channel "$CONTEXT" $VERSION_ARG \
             --dist dist \
@@ -237,13 +251,13 @@ jobs:
           if [ "$CONTEXT" = "release" ]; then
             UPDATE_VERSIONS="--update-versions"
           fi
-          node scripts/deploy.mjs finalize \
+          node_modules/.bin/grist-widget-deploy finalize \
             --site site --repo "$REPO_NAME" $UPDATE_VERSIONS --push \
             --commit-message "deploy: ${CONTEXT} @ ${SHA_FULL}"
 
       - name: Reset repo to a clean first-release state
         if: needs.build.outputs.context == 'release' && needs.build.outputs.firstRelease == 'true'
-        run: node scripts/deploy.mjs reset-branches --repo "$REPO_NAME"
+        run: node_modules/.bin/grist-widget-deploy reset-branches --repo "$REPO_NAME"
 
   cleanup:
     # When the `dev` branch is deleted, remove /dev/ so the dev URL retires
@@ -253,15 +267,22 @@ jobs:
     permissions:
       contents: write
     steps:
-      - name: Checkout (default branch — for scripts/deploy.mjs)
+      - name: Checkout (default branch — for its pinned grist-widget-deploy)
         uses: actions/checkout@v7
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+
       - name: Setup Node
         uses: actions/setup-node@v7
         with:
           node-version: 22
           package-manager-cache: false
 
+      # As in `publish`: no dependency scripts run, and the bin is called directly.
+      - name: Install the deploy command
+        run: pnpm install --ignore-scripts
+
       - name: Clone gh-pages into ./site (skip if it does not exist)
         id: clone
         env:
@@ -283,7 +304,7 @@ jobs:
         env:
           DELETED_REF: ${{ github.event.ref }}
         run: |
-          node scripts/deploy.mjs remove --site site
-          node scripts/deploy.mjs finalize \
+          node_modules/.bin/grist-widget-deploy remove --site site
+          node_modules/.bin/grist-widget-deploy finalize \
             --site site --push \
             --commit-message "cleanup: retire dev URL for ${DELETED_REF}"

package/template/AGENTS.md

@@ -65,10 +65,10 @@ mapping, and rendering all live in `src/App.tsx` — that's the one file to edit
 | --- | --- |
 | The widget | `src/App.tsx` |
 | Widget test (the pattern to copy for new tests) | `src/App.test.tsx` |
+| Smoke test (one smokeTestWidget call; CI runs it on SDK updates) | `src/App.smoke.test.tsx` |
 | Grist wiring (mountGristWidget, inside vs. outside Grist) | `src/main.tsx` |
 | ui primitives | `src/components/ui/` |
-| Deploy workflow | `.github/workflows/deploy.yml` |
-| Deploy script (version guard, channel logic) | `scripts/deploy.mjs` |
+| Deploy workflow (runs grist-widget-deploy from the create-grist-widget devDependency: version guard, channel logic) | `.github/workflows/deploy.yml` |
 | Pull request checks (lint, test, build) | `.github/workflows/ci.yml` |
 | Dependency update PRs (weekly, against the dev branch) | `.github/dependabot.yml` |
 | Full walkthrough (dev loop, deploying, embedding) | `README.md` |
@@ -96,7 +96,7 @@ Full detail, including the two live URLs (`/latest/` and `/v<version>/`): `READM
   is the trusted real one
 - Merging `dev` into `main` without bumping `package.json`'s `version` first
 - Adding `minimumReleaseAgeExclude` entries to `pnpm-workspace.yaml` to get an install or a
-  check green, or deleting the one pnpm wrote for `grist-widget-sdk` on release day (see
+  check green, or deleting the ones pnpm wrote for `grist-widget-sdk` and `create-grist-widget` on release day (see
   `README.md`): pnpm's 24 h age check protects the widget's supply chain
 - Merging a Dependabot pull request whose `ci.yml` checks are red, or retargeting one at
   `main`: updates go through `dev` like any other change. Template-file updates (this

package/template/README.md

@@ -17,7 +17,7 @@ When actually embedded, the widget shows connection state only when something is
 - **ESLint** blocks direct `grist` global usage in `src/` — use the SDK only.
 - Edit `GRIST_OPTIONS.columns` in `App.tsx` to change the required columns (or remove the array entirely to read raw, unmapped records instead); `mountGristWidget()` gates the widget on `canRender` whenever columns are declared, so it renders once they're mapped.
 
-Run `pnpm test` — see `src/App.test.tsx` for the pattern (`renderWithGrist` + `presets` from `grist-widget-sdk/emulator/testing`, no browser or real Grist doc needed). Full guide: [Testing](https://gristwidgets.com/docs/emulator/testing).
+Run `pnpm test`. `src/App.smoke.test.tsx` is the smoke test, one `smokeTestWidget()` call that checks the widget renders inside an emulated Grist with every declared column mapped, and that CI runs on every pull request; see `src/App.test.tsx` for the pattern (`renderWithGrist` + `presets` from `grist-widget-sdk/emulator/testing`, no browser or real Grist doc needed). Full guide: [Testing](https://gristwidgets.com/docs/emulator/testing).
 
 **Monorepo dev:** this template resolves `grist-widget-sdk` from `packages/core/dist` (like the other widgets), not from SDK source. After changing the SDK, run `pnpm prebuild` or `pnpm --filter grist-widget-sdk build` before `pnpm dev`.
 
@@ -43,11 +43,12 @@ pnpm, even under `npm create`, unless it was run with `--no-install` or
 without pnpm installed. Versions are pinned with their integrity hashes, CI
 installs exactly that, and Dependabot updates it. A `package-lock.json` isn't
 used: the workflows install with pnpm. pnpm 11 won't install a version
-published less than 24 hours ago. So a widget scaffolded on the day of an SDK
-release also gets one `minimumReleaseAgeExclude` entry in
-`pnpm-workspace.yaml`, for that SDK version only, written by pnpm itself.
-Keep it: without it, every install (yours and CI's) rejects the lockfile
-until the version is a day old. After that the entry is harmless.
+published less than 24 hours ago. So a widget scaffolded on the day of a
+release also gets `minimumReleaseAgeExclude` entries in `pnpm-workspace.yaml`,
+written by pnpm itself, for the `grist-widget-sdk` and `create-grist-widget`
+versions it was made with, and nothing else. Keep them: without them, every
+install (yours and CI's) rejects the lockfile until the version is a day old.
+After that the entries are harmless.
 
 ### Live preview
 
@@ -68,8 +69,10 @@ directory, same as `scripts/smoke/create-widget.sh` does.
 
 ## Deployment
 
-A bundled GitHub Actions workflow (`.github/workflows/deploy.yml` +
-`scripts/deploy.mjs`) publishes this widget to **your own** GitHub Pages.
+A bundled GitHub Actions workflow (`.github/workflows/deploy.yml`, which runs
+the `grist-widget-deploy` command of the `create-grist-widget` devDependency)
+publishes this widget to **your own** GitHub Pages. Fixes to the deploy logic
+arrive as updates of that devDependency.
 
 ### The workflow: always develop on `dev`, release by merging to `main`
 

package/template/package.json

@@ -17,7 +17,7 @@
     "@tailwindcss/vite": "^4.3.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "grist-widget-sdk": "^0.3.26",
+    "grist-widget-sdk": "^0.3.27",
     "lucide-react": "^1.61.0",
     "radix-ui": "^1.8.1",
     "react": "^19.3.1",
@@ -35,6 +35,7 @@
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "@vitejs/plugin-react": "^6.1.2",
+    "create-grist-widget": "^0.3.27",
     "eslint": "^10.13.0",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.5.7",

package/template/src/App.smoke.test.tsx

@@ -0,0 +1,17 @@
+/**
+ * Smoke test: the widget renders inside an emulated Grist, mounted as
+ * `main.tsx` mounts it, with every column `GRIST_OPTIONS` declares mapped.
+ *
+ * It only reads `GRIST_OPTIONS`, so it stays valid as the widget changes,
+ * and it improves with each SDK release. `.github/workflows/ci.yml` runs it
+ * on every pull request, Dependabot's `grist-widget-sdk` updates included:
+ * an SDK release that breaks this widget turns that PR red before the merge.
+ * Widget-specific assertions go in their own tests (see `App.test.tsx`).
+ */
+import { it } from "vitest"
+import { smokeTestWidget } from "grist-widget-sdk/emulator/testing"
+
+import App, { GRIST_OPTIONS } from "./App"
+
+it("renders inside Grist with every declared column mapped", () =>
+  smokeTestWidget({ App, options: GRIST_OPTIONS }))

package/vendor/compose-example.mjs

@@ -98,7 +98,7 @@ export function createComposer({ templateDir, examplesDir, uiDir, manifestPath }
     // only remove files this function itself may have added, so a stale
     // sibling from a *different* previous example doesn't linger.
     for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
-      if (entry.name === "App.tsx" || entry.name === "App.test.tsx") continue
+      if (entry.name === "App.tsx" || entry.name === "App.test.tsx" || entry.name === "App.smoke.test.tsx") continue
       if (["components", "lib", "assets", "index.css", "vite-env.d.ts", "main.tsx"].includes(entry.name)) {
         continue
       }
@@ -175,11 +175,14 @@ export function createComposer({ templateDir, examplesDir, uiDir, manifestPath }
    * `workspace:^` (meaningless outside the pnpm workspace) — a `file:`
    * reference to either `packages/core` (workspace source, already built), a
    * packed tarball, or (for the CLI's `create`) a real published semver range.
+   * `cliDependency` does the same for the template's `create-grist-widget`
+   * devDependency (its deploy bin); without one, the devDependency is dropped,
+   * since a composed example is only typechecked, built and tested here.
    *
    * For composing *many* examples against one shared `pnpm install`, use
    * {@link overlayExampleSrc} directly instead (see its own doc comment).
    */
-  function composeExample({ exampleId, destDir, sdkDependency }) {
+  function composeExample({ exampleId, destDir, sdkDependency, cliDependency }) {
     rmSync(destDir, { recursive: true, force: true })
     cpSync(templateDir, destDir, {
       recursive: true,
@@ -192,6 +195,8 @@ export function createComposer({ templateDir, examplesDir, uiDir, manifestPath }
     const pkg = JSON.parse(readFileSync(pkgPath, "utf8"))
     pkg.name = exampleId
     pkg.dependencies["grist-widget-sdk"] = sdkDependency
+    if (cliDependency) pkg.devDependencies["create-grist-widget"] = cliDependency
+    else delete pkg.devDependencies["create-grist-widget"]
     Object.assign(pkg.dependencies, EXTRA_DEPENDENCIES[exampleId] ?? {})
     writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)