create-grist-widget 0.3.26 → 0.3.28

package/README.md

@@ -21,13 +21,14 @@ dependencies automatically, detecting whichever package manager you invoked this
 what's available — or just run `npm create grist-widget` with no name for an interactive
 prompt that asks for both.
 
-## The four commands
+## The five commands
 
 | Command | What it does |
 | --- | --- |
 | `create <name> [--example <id>]` | Scaffold a new widget into `./<name>` (the command above, or run explicitly) |
 | `init [--example <id>]` | Scaffold into the **current** directory instead of a new one — for an already-cloned or agent-initialized repo |
 | `use <example-id>` | Swap the current project's widget for a different example |
+| `upgrade` | Bring an existing widget's template files up to this version's template |
 | `list [--json]` | Print the available starting examples |
 
 Common flags for `create`/`init`: `--yes` skips interactive prompts and uses
@@ -52,7 +53,7 @@ npx create-grist-widget init --example form-edit
 ```
 
 Files that already exist and are identical to the template are left untouched; the four
-identity-bearing files (`package.json`, `README.md`, `index.html`, `src/App.tsx`) get the
+identity-bearing files (`package.json`, `README.md`, `index.html`, `src/app/App.tsx`) get the
 usual name/title substitution even if present. Anything else that already exists **and**
 differs from the template's own copy stops the run with a list of the conflicting paths —
 pass `--force` to overwrite anyway. If `.git` already exists, `init` never auto-commits;
@@ -61,18 +62,35 @@ initial commit exactly like `create` does.
 
 ### `use` — swapping to a different example later
 
-Changed your mind about which example to start from, or want to compare two? `use` swaps
-`src/App.tsx` (and any example-specific files) for a different one, in place:
+Changed your mind about which example to start from, or want to compare two? `use`
+replaces the widget, `src/app/`, with a different example:
 
 ```bash
 create-grist-widget use task-board
 ```
 
-It only ever touches `src/**` — never `main.tsx`, `vite.config.ts`, or the deploy
-workflow — and it requires a clean git working tree first (`git status --porcelain`
+It touches nothing else but the `src/components/ui/` primitives and dependencies the example
+needs — never `main.tsx`, `vite.config.ts`, or the deploy workflow — and it requires a clean git working tree first (`git status --porcelain`
 empty), so the swap is always a single reviewable, revertible diff. Commit or stash first
 if you have uncommitted changes; `use` refuses to run otherwise.
 
+### `upgrade` — picking up template changes
+
+Inside a widget, on `dev` with nothing uncommitted, after updating its `create-grist-widget`
+dependency:
+
+```bash
+pnpm exec create-grist-widget upgrade
+```
+
+It rewrites the template's files (`src/main.tsx`, the workflows, the build configuration) to
+this version's copies, deletes the ones earlier templates wrote that are gone now, merges the
+template's scripts and dependency versions into `package.json`, and drops pnpm age exceptions
+that are old enough not to matter. Nothing of the widget's own is touched (`src/app/` and its
+smoke test, `src/components/ui/`, `src/index.css`, `README.md`…). It refuses to
+run on `main`, with uncommitted changes, or on a widget still in `src/App.tsx`. Details:
+[Upgrading a widget](https://gristwidgets.com/docs/cli/upgrading).
+
 ### `list` — what's available
 
 ```bash
@@ -80,7 +98,7 @@ create-grist-widget list          # id / title / description, one per line
 create-grist-widget list --json   # the same, as JSON
 ```
 
-> **Note:** `create`, `init`, `use`, and `list` are themselves valid widget names — a bare
+> **Note:** `create`, `init`, `use`, `upgrade`, and `list` are themselves valid widget names — a bare
 > `create-grist-widget list` runs the `list` command, not "scaffold a widget named list."
 > Use the explicit form (`create-grist-widget create list`) for a widget with one of these
 > names.

package/bin/create-grist-widget.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 // create-grist-widget — scaffold a Grist custom widget, fully offline.
 //
-// Four verbs (batch H, docs/planning/2026-08-execution-plan.md §98-105):
+// Five verbs (batch H, docs/planning/2026-08-execution-plan.md §98-105, and
+// T2 of docs/planning/2026-11-01-widget-lifecycle-plan.md):
 //   create <name> [--example <id>]   scaffold a new widget into ./<name>
 //   init [--example <id>]            scaffold into the current directory
-//   use <example-id>                 swap the current project's widget
+//   use <example-id>                 swap the current project's widget (src/app/)
+//   upgrade                          bring the template's files up to this CLI's
 //   list [--json]                    print the available starting examples
 //
 // `create`/`init`/`use` share one compose engine — see
@@ -13,7 +15,8 @@
 // scripts/build-template.mjs alongside the template itself, along with
 // examples/, ui-source/, and manifest.json — see that script for why).
 // Nothing here ever hits the network: everything list/use/create --example
-// need already shipped in the tarball.
+// need already shipped in the tarball. The one exception is `upgrade`, which
+// asks the npm registry when versions in pnpm's age exceptions were published.
 
 import {
   cpSync,
@@ -33,6 +36,7 @@ import { createComposer } from "../vendor/compose-example.mjs"
 import { checkGitGate } from "../src/git-gate.mjs"
 import { addedAgeExceptions } from "../src/age-exceptions.mjs"
 import { installPlan } from "../src/package-manager.mjs"
+import { runUpgrade, upgradeRefusal } from "../src/upgrade.mjs"
 
 const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..")
 const TEMPLATE_DIR = path.join(PKG_ROOT, "template")
@@ -87,7 +91,9 @@ Usage:
   npm create grist-widget <name> [options]       Scaffold into ./<name>
   create-grist-widget create <name> [options]    Same as above, explicit
   create-grist-widget init [options]             Scaffold into the current directory
-  create-grist-widget use <example-id>           Swap the current project's widget
+  create-grist-widget use <example-id>           Replace the current project's widget (src/app/)
+  create-grist-widget upgrade                    Bring the template's files up to this CLI's
+                                                 (run it on dev, in a widget: pnpm exec create-grist-widget upgrade)
   create-grist-widget list [--json]              List available starting examples
 
 Options (create / init):
@@ -104,7 +110,7 @@ Options (create / init):
   --help, -h       Show this help
   --version, -v    Show this CLI's version
 
-Note: "create", "init", "use", and "list" are themselves valid widget names.
+Note: "create", "init", "use", "upgrade", and "list" are themselves valid widget names.
 A bare "create-grist-widget list" runs the list command, not "scaffold a
 widget named list" — use "create-grist-widget create list" for that.`)
 }
@@ -116,7 +122,7 @@ function applyIdentityEdits(target, rawName) {
     ["package.json", [["grist-widget-template-vite", rawName]]],
     ["README.md", [["grist-widget-template-vite", rawName]]],
     ["index.html", [["<title>Grist Widget</title>", `<title>${title}</title>`]]],
-    ["src/App.tsx", [['title: "Grist Widget Template",', `title: "${title}",`]]],
+    ["src/app/App.tsx", [['title: "Grist Widget Template",', `title: "${title}",`]]],
   ]
   for (const [file, subs] of edits) {
     const p = path.join(target, file)
@@ -223,7 +229,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."
   )
 }
 
@@ -393,7 +399,7 @@ async function cmdInit(argv) {
   // common case, a pristine "Use this template" clone); anything else that
   // already exists and differs from the template's own pristine copy blocks
   // the run, listed, unless --force.
-  const IDENTITY_FILES = new Set(["package.json", "README.md", "index.html", "src/App.tsx"])
+  const IDENTITY_FILES = new Set(["package.json", "README.md", "index.html", "src/app/App.tsx"])
   const templateFiles = listFilesRecursive(TEMPLATE_DIR)
   if (!args.force) {
     const conflicts = []
@@ -470,11 +476,21 @@ function cmdUse(argv) {
   }
 
   const cwd = process.cwd()
+  // Scaffolds older than the src/app/ layout keep their widget in src/, and
+  // their main.tsx imports ./App.tsx: an example written to src/app/ would
+  // never show.
+  if (existsSync(path.join(cwd, "src", "App.tsx"))) {
+    console.error(
+      "use: this project keeps its widget in src/App.tsx. Widgets now live in src/app/: move it there first" +
+        " (see https://gristwidgets.com/docs/cli/upgrading), then run use again."
+    )
+    process.exit(1)
+  }
   const gate = checkGitGate(cwd)
   if (!gate.ok) {
     if (gate.reason === "no-repo") {
       console.error(
-        'use: this command overwrites src/App.tsx and must run inside a git repository so the change is easy to review and undo. Run "git init" first.'
+        'use: this command replaces src/app/ and must run inside a git repository so the change is easy to review and undo. Run "git init" first.'
       )
     } else {
       console.error(
@@ -493,6 +509,105 @@ function cmdUse(argv) {
   console.log("  pnpm dev")
 }
 
+// ---------------------------------------------------------------------------
+// upgrade
+// ---------------------------------------------------------------------------
+
+const CLI_CHANGELOG_URL =
+  "https://github.com/ArthurBlanchon/grist-widget-sdk/blob/main/packages/create-grist-widget/CHANGELOG.md"
+
+/** When `name@version` was published, from the registry `npm` is configured for in `cwd`; null if unknown. */
+function npmPublishTimes(cwd) {
+  const cache = new Map()
+  return (name, version) => {
+    if (!cache.has(name)) {
+      let times = null
+      try {
+        const out = runCommand("npm", ["view", name, "time", "--json"], {
+          cwd,
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+          timeout: 30_000,
+        })
+        times = JSON.parse(out)
+      } catch {
+        // Offline, or not on that registry: the entry stays.
+      }
+      cache.set(name, times)
+    }
+    const at = cache.get(name)?.[version]
+    return at ? new Date(at) : null
+  }
+}
+
+function printList(title, items) {
+  if (items.length === 0) return
+  console.log(`\n${title}`)
+  for (const item of items) console.log(`  ${item}`)
+}
+
+function cmdUpgrade(argv) {
+  parseArgs(argv)
+  const cwd = process.cwd()
+  const refusal = upgradeRefusal(cwd, { cliVersion: cliPkg.version })
+  if (refusal) {
+    console.error(refusal.message)
+    process.exit(1)
+  }
+
+  const report = runUpgrade({
+    cwd,
+    templateDir: TEMPLATE_DIR,
+    cliVersion: cliPkg.version,
+    publishedAt: npmPublishTimes(cwd),
+  })
+  const changed =
+    report.written.length +
+      report.deleted.length +
+      report.tsconfigs.length +
+      report.packageChanges.length +
+      report.ageRemoved.length >
+    0
+
+  const from = report.fromVersion && report.fromVersion !== cliPkg.version ? ` (from ${report.fromVersion})` : ""
+  if (!changed) {
+    console.log(`Already on create-grist-widget ${cliPkg.version}'s template: nothing to change.`)
+  } else {
+    console.log(`Upgraded to create-grist-widget ${cliPkg.version}'s template${from}.`)
+  }
+  printList("Template files rewritten:", report.written)
+  printList("Deleted (earlier templates wrote them, nothing uses them now):", report.deleted)
+  printList(
+    "Kept: earlier templates wrote these, but a file of yours still refers to them (delete them once it doesn't):",
+    report.keptRetired.map(({ file, by }) => `${file}  (by ${by.join(", ")})`)
+  )
+  printList(
+    "Switched to grist-widget-sdk's compiler settings, keeping these types:",
+    report.tsconfigs.map(({ file, types }) => `${file}  (types: ${types.join(", ") || "none"})`)
+  )
+  printList(
+    "Not switched to grist-widget-sdk's compiler settings (could not be read; do it by hand):",
+    report.tsconfigsUnreadable
+  )
+  printList("package.json:", report.packageChanges)
+  printList("pnpm age exceptions removed (old enough now that pnpm no longer needs them):", report.ageRemoved)
+  printList("pnpm age exceptions kept (their publish time could not be looked up):", report.ageUnknown)
+  if (!changed) return
+
+  console.log("\nNext:")
+  // Only what pnpm-lock.yaml records: dependencies, packageManager, age exceptions.
+  const lockfileChanges = report.packageChanges.filter((c) => /^(dependencies|devDependencies|packageManager)\b/.test(c))
+  if (lockfileChanges.length || report.ageRemoved.length) {
+    console.log("  pnpm install                                # update pnpm-lock.yaml")
+  }
+  console.log("  pnpm typecheck && pnpm lint && pnpm test")
+  console.log("  git diff                                    # review, then commit and push dev")
+  console.log(
+    `\nAnything a template change needs beyond these files is in the changelog entries${from ? ` after ${report.fromVersion}` : ""}:` +
+      `\n  ${CLI_CHANGELOG_URL}`
+  )
+}
+
 // ---------------------------------------------------------------------------
 // list
 // ---------------------------------------------------------------------------
@@ -534,6 +649,7 @@ async function main() {
   }
   if (first === "list") return cmdList(rest)
   if (first === "use") return cmdUse(rest)
+  if (first === "upgrade") return cmdUpgrade(rest)
   if (first === "init") return cmdInit(rest)
   if (first === "create") return cmdCreate(rest)
   // Bare invocation — `npm create grist-widget my-widget` (npm's `create`

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.28",
   "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. */
@@ -457,6 +464,9 @@ function identityEdits({ packageName, title }) {
     ["package.json", [["grist-widget-template-vite", packageName]]],
     ["README.md", [["grist-widget-template-vite", packageName]]],
     ["index.html", [["<title>Grist Widget</title>", `<title>${title}</title>`]]],
+    ["src/app/App.tsx", [['title: "Grist Widget Template",', `title: "${title}",`]]],
+    // Where the widget lived before the src/app/ layout: a repo copied from
+    // an older template repository still has it there.
     ["src/App.tsx", [['title: "Grist Widget Template",', `title: "${title}",`]]],
   ]
 }
@@ -572,81 +582,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/src/git-gate.mjs

@@ -1,5 +1,5 @@
-// The safety gate `use <example-id>` rests on: overlayExampleSrc overwrites
-// src/App.tsx (and any other example-specific files) in place, so the only
+// The safety gate `use <example-id>` rests on: overlayExampleSrc replaces
+// src/app/ (the widget's own folder) with the example's files, so the only
 // thing that makes that recoverable is a clean git tree to diff/revert
 // against. `create`/`init` always leave a repo behind today (see
 // bin/create-grist-widget.mjs's gitInitCommit), but `use` checks for one