create-grist-widget 0.3.22 → 0.3.24

package/README.md

@@ -31,8 +31,10 @@ prompt that asks for both.
 | `list [--json]` | Print the available starting examples |
 
 Common flags for `create`/`init`: `--yes` skips interactive prompts and uses
-flags/defaults only; `--no-install` skips the automatic dependency install;
-`--pm <name>` picks a specific package manager instead of auto-detecting one.
+flags/defaults only; `--no-install` skips the automatic dependency install
+(which uses pnpm, whichever package manager runs the CLI: the widget's
+workflows only read `pnpm-lock.yaml`); `--pm <name>` installs with another
+package manager instead.
 `init` additionally takes `--name <name>` (default: the current directory's
 name) and `--force` (overwrite files that already exist and differ from the
 template — see below).

package/bin/create-grist-widget.mjs

@@ -26,11 +26,13 @@ import {
 } from "node:fs"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
-import { execFileSync } from "node:child_process"
+import { execFileSync, execSync } from "node:child_process"
 import * as clack from "@clack/prompts"
 
 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"
 
 const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..")
 const TEMPLATE_DIR = path.join(PKG_ROOT, "template")
@@ -61,14 +63,6 @@ function titleCase(name) {
     .join(" ")
 }
 
-function detectPackageManager() {
-  // e.g. "pnpm/9.1.0 npm-node/..." -> "pnpm". Set by every package manager's
-  // own `npm create`-equivalent invocation. Falls back to npm, matching
-  // what a bare `node bin/create-grist-widget.mjs` (no wrapping pm) should do.
-  const ua = process.env.npm_config_user_agent || ""
-  return ua.split("/")[0] || "npm"
-}
-
 function parseArgs(argv) {
   const out = { _: [] }
   for (let i = 0; i < argv.length; i++) {
@@ -101,8 +95,8 @@ Options (create / init):
                     (see "list" for ids)
   --yes            Skip interactive prompts, use defaults/flags only
   --no-install     Don't run the package manager install automatically
-  --pm <name>      Package manager for install (default: detected from how
-                    you invoked this — npm/pnpm/yarn/bun)
+  --pm <name>      Install with this package manager instead of pnpm (the
+                    widget's workflows use pnpm and only read its lockfile)
   --name <name>    (init only) Widget name — default: the current directory's name
   --force          (init only) Overwrite files that already exist and differ
                     from the template
@@ -168,18 +162,71 @@ function gitInitCommit(target) {
   }
 }
 
-function maybeInstall(target, { noInstall, pm }) {
-  if (noInstall) return false
-  const manager = pm || detectPackageManager()
+// Package managers are .cmd shims on Windows, which only a shell starts.
+function runCommand(cmd, args, options) {
+  if (process.platform === "win32") return execSync([cmd, ...args].join(" "), options)
+  return execFileSync(cmd, args, options)
+}
+
+function hasCommand(cmd) {
   try {
-    execFileSync(manager, ["install"], { cwd: target, stdio: "inherit" })
+    runCommand(cmd, ["--version"], { stdio: "ignore" })
     return true
   } catch {
-    console.warn(`\nCould not run "${manager} install" automatically — run it yourself.`)
     return false
   }
 }
 
+/** Returns whether the install ran, and why not when it was skipped. */
+function maybeInstall(target, { noInstall, pm }) {
+  const plan = installPlan({ noInstall, pm, hasPnpm: () => hasCommand("pnpm") })
+  if (plan.skip) return { installed: false, skipped: plan.skip }
+  try {
+    runCommand(plan.manager, ["install"], { cwd: target, stdio: "inherit" })
+    return { installed: true }
+  } catch {
+    console.warn(`\nCould not run "${plan.manager} install" automatically — run it yourself.`)
+    return { installed: false }
+  }
+}
+
+/**
+ * Install (unless --no-install, or pnpm is missing), returning which
+ * `minimumReleaseAgeExclude` entries pnpm added to pnpm-workspace.yaml along
+ * the way. Runs before the first commit, so the lockfile -- and those
+ * entries, without which every later install rejects that lockfile -- are
+ * part of it.
+ */
+function installBeforeFirstCommit(target, args) {
+  const workspaceFile = path.join(target, "pnpm-workspace.yaml")
+  const read = () => (existsSync(workspaceFile) ? readFileSync(workspaceFile, "utf8") : "")
+  const before = read()
+  const { installed, skipped } = maybeInstall(target, {
+    noInstall: Boolean(args["no-install"]),
+    pm: typeof args.pm === "string" ? args.pm : null,
+  })
+  return { installed, skipped, ageExceptions: installed ? addedAgeExceptions(before, read()) : [] }
+}
+
+function printNoPnpmNote(skipped) {
+  if (skipped !== "no-pnpm") return
+  console.log(
+    "\nNote: dependencies were not installed. This widget uses pnpm (its workflows install with it," +
+      "\nand only read pnpm-lock.yaml), and pnpm isn't installed. Install it (https://pnpm.io/installation)," +
+      "\nthen run `pnpm install` and commit pnpm-lock.yaml."
+  )
+}
+
+function printAgeExceptionsNote(ageExceptions) {
+  if (ageExceptions.length === 0) return
+  console.log(
+    `\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."
+  )
+}
+
 function listFilesRecursive(dir, base = dir) {
   const out = []
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -282,15 +329,16 @@ async function cmdCreate(argv) {
 
   stampCreateGristWidgetVersion(target)
 
+  // Install first, so the first commit includes the lockfile (pinned, with
+  // integrity hashes; pnpm then freezes installs in CI by itself).
+  const { installed, skipped, ageExceptions } = installBeforeFirstCommit(target, args)
   const committed = gitInitCommit(target)
-  const installed = maybeInstall(target, {
-    noInstall: Boolean(args["no-install"]),
-    pm: typeof args.pm === "string" ? args.pm : null,
-  })
 
+  printAgeExceptionsNote(ageExceptions)
+  printNoPnpmNote(skipped)
   console.log(`\nCreated ${rawName}/${exampleId ? ` (starting from "${exampleId}")` : ""}\n`)
   console.log(`  cd ${rawName}`)
-  if (!installed) console.log("  pnpm install   # or npm/yarn")
+  if (!installed) console.log("  pnpm install")
   console.log("  pnpm dev")
   if (committed) {
     console.log("\nGit is initialized on main (first commit done) with a dev branch ready.")
@@ -384,14 +432,14 @@ async function cmdInit(argv) {
   // git entirely when cwd had none to begin with (a fresh, non-git directory,
   // or a real git clone where .git already carries whatever history it has).
   const gitAlreadyExists = existsSync(path.join(cwd, ".git"))
+  // Install first, so a first commit includes the lockfile (see cmdCreate).
+  const { installed, skipped, ageExceptions } = installBeforeFirstCommit(cwd, args)
   const committed = gitAlreadyExists ? false : gitInitCommit(cwd)
-  const installed = maybeInstall(cwd, {
-    noInstall: Boolean(args["no-install"]),
-    pm: typeof args.pm === "string" ? args.pm : null,
-  })
 
+  printAgeExceptionsNote(ageExceptions)
+  printNoPnpmNote(skipped)
   console.log(`\nInitialized ${rawName}/${exampleId ? ` (starting from "${exampleId}")` : ""} in the current directory.\n`)
-  if (!installed) console.log("  pnpm install   # or npm/yarn")
+  if (!installed) console.log("  pnpm install")
   console.log("  pnpm dev")
   if (gitAlreadyExists) {
     console.log("\nExisting git repository detected — no commit was made automatically.")

package/package.json

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

package/src/age-exceptions.mjs

@@ -0,0 +1,61 @@
+// pnpm 11 won't install a dependency version published less than 24 h ago
+// (`minimumReleaseAge`). When nothing older satisfies a range, its loose mode
+// installs that version anyway and records an exception under
+// `minimumReleaseAgeExclude` in pnpm-workspace.yaml. In practice that is only
+// grist-widget-sdk, which a fresh scaffold pins to the version released with
+// this CLI; every other dependency has an older version in range.
+//
+// A lockfile pinning that version is then rejected by every later install,
+// local or CI, unless the exception stays. So the scaffold's first commit
+// keeps it (docs/planning/2026-11-01-widget-lifecycle-plan.md, D3), and these
+// helpers find the entries pnpm added so the CLI can say why.
+
+const KEY = "minimumReleaseAgeExclude"
+
+/**
+ * Entries listed under `minimumReleaseAgeExclude` in a pnpm-workspace.yaml,
+ * in block (`- name@version`) or flow (`[a, b]`) style.
+ *
+ * @param {string} workspaceYaml
+ * @returns {string[]}
+ */
+export function ageExceptions(workspaceYaml) {
+  const out = []
+  let inBlock = false
+  for (const line of workspaceYaml.split(/\r?\n/)) {
+    const flow = line.match(new RegExp(`^${KEY}:\\s*\\[(.*)\\]\\s*(#.*)?$`))
+    if (flow) {
+      for (const item of flow[1].split(",")) {
+        const entry = item.trim().replace(/^["']|["']$/g, "")
+        if (entry) out.push(entry)
+      }
+      inBlock = false
+      continue
+    }
+    if (new RegExp(`^${KEY}:\\s*(#.*)?$`).test(line)) {
+      inBlock = true
+      continue
+    }
+    if (!inBlock) continue
+    const item = line.match(/^\s+-\s+["']?([^"'\s#]+)["']?/)
+    if (item) {
+      out.push(item[1])
+      continue
+    }
+    if (/^\s*(#.*)?$/.test(line)) continue // blank line or comment inside the block
+    inBlock = false
+  }
+  return out
+}
+
+/**
+ * Exceptions present in `after` but not in `before`.
+ *
+ * @param {string} before pnpm-workspace.yaml before the install
+ * @param {string} after pnpm-workspace.yaml after it
+ * @returns {string[]}
+ */
+export function addedAgeExceptions(before, after) {
+  const had = new Set(ageExceptions(before))
+  return ageExceptions(after).filter((entry) => !had.has(entry))
+}

package/src/package-manager.mjs

@@ -0,0 +1,19 @@
+// Which package manager installs a new widget's dependencies.
+//
+// The scaffold is a pnpm project: its workflows install with pnpm, and
+// pnpm-workspace.yaml holds settings only pnpm reads (build-script
+// approvals, release-age exceptions). So the CLI installs with pnpm
+// whichever package manager runs it -- `npm create grist-widget` runs it
+// under npm. Installing with npm would commit a package-lock.json that the
+// workflows never read, and skip pnpm's 24 h release-age check.
+
+/**
+ * @param {{ noInstall?: boolean, pm?: string | null, hasPnpm: () => boolean }} options
+ *   `pm` is an explicit `--pm`; `hasPnpm` is only called when pnpm is the pick.
+ * @returns {{ manager: string } | { skip: "no-install" | "no-pnpm" }}
+ */
+export function installPlan({ noInstall, pm, hasPnpm }) {
+  if (noInstall) return { skip: "no-install" }
+  if (pm) return { manager: pm }
+  return hasPnpm() ? { manager: "pnpm" } : { skip: "no-pnpm" }
+}

package/template/.github/workflows/ci.yml

@@ -24,7 +24,9 @@ jobs:
         with:
           node-version: 22
           # Same as deploy.yml: pnpm caching and a frozen install both need a
-          # committed pnpm-lock.yaml, which a fresh scaffold doesn't have.
+          # committed pnpm-lock.yaml, which a scaffold made with --no-install
+          # doesn't have. With one committed, pnpm freezes the install in CI
+          # by itself.
           package-manager-cache: false
       - run: pnpm install
       - run: pnpm lint

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

@@ -23,6 +23,11 @@ name: Deploy widget to GitHub Pages
 #
 # All logic lives in scripts/deploy.mjs (node builtins only).
 #
+# 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.
+#
 # 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
@@ -45,8 +50,8 @@ on:
         required: false
         default: false
 
-permissions:
-  contents: write
+# Nothing at workflow level: each job states what it needs.
+permissions: {}
 
 # Serialize deploys onto the single shared gh-pages branch. deploy.mjs
 # additionally rebases-and-retries on push, so interleaving runs never clobber.
@@ -55,18 +60,27 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  deploy:
+  build:
     # Build/publish on push + manual dispatch. The delete event is handled by `cleanup`.
     if: github.event_name != 'delete'
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     env:
       REPO_NAME: ${{ github.event.repository.name }}
+    outputs:
+      context: ${{ steps.plan.outputs.context }}
+      skip: ${{ steps.plan.outputs.skip }}
+      version: ${{ steps.plan.outputs.version }}
+      firstRelease: ${{ steps.plan.outputs.firstRelease }}
     steps:
       # Action majors track the monorepo's own workflows (Dependabot watches
       # this file via the template's directory in .github/dependabot.yml);
       # the v4s here ran on the deprecated Node 20 action runtime.
       - name: Checkout
         uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v6
@@ -75,28 +89,33 @@ jobs:
         uses: actions/setup-node@v7
         with:
           node-version: 22
-          # Never cache: a freshly scaffolded repo has no pnpm-lock.yaml (see
-          # the install step below), and a pnpm cache hard-requires one.
-          # Explicit rather than relying on setup-node's npm-only default.
+          # Never cache: a pnpm cache hard-requires a committed
+          # pnpm-lock.yaml, which a scaffold made with --no-install doesn't
+          # have (see the install step below). Explicit rather than relying
+          # on setup-node's npm-only default.
           package-manager-cache: false
 
-      # Not --frozen-lockfile, and no `cache: pnpm` above: a freshly
-      # scaffolded repo never has a committed pnpm-lock.yaml (the CLI's
-      # auto-commit runs before anyone's first `pnpm install`), and
-      # --frozen-lockfile/cache: pnpm both hard-require one to exist —
-      # found live, the very first real deploy failed with "Dependencies
-      # lock file is not found". A plain install resolves fresh every run
-      # regardless of whether a lockfile was ever committed.
+      # A plain `pnpm install`, not --frozen-lockfile. A scaffold commits
+      # pnpm-lock.yaml in its first commit, and with one committed pnpm
+      # freezes the install in CI by itself: the versions and integrity
+      # hashes in the lockfile are what gets installed. A scaffold made
+      # with --no-install has no lockfile until its author commits one, and
+      # there --frozen-lockfile (or `cache: pnpm`) fails outright with
+      # "Dependencies lock file is not found" (found live, on the very
+      # first real deploy); a plain install resolves fresh instead.
       - name: Install dependencies
         run: pnpm install
 
-      - name: Clone gh-pages into ./site
+      - name: Clone gh-pages into ./site (read-only, to plan against)
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
         run: |
           git clone --depth 1 --branch gh-pages \
-            "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" site \
+            "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.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 clone --depth 1 "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git" site
               git -C site checkout --orphan gh-pages
               git -C site rm -rf . >/dev/null 2>&1 || true
               touch site/.nojekyll
@@ -106,12 +125,16 @@ jobs:
 
       - name: Resolve deploy plan
         id: plan
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          REF: ${{ github.ref }}
+          FORCE: ${{ github.event.inputs.force == 'true' && '--force' || '' }}
         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' || '' }})
+            --event "$EVENT_NAME" \
+            --ref "$REF" \
+            $FORCE)
           echo "Plan: $PLAN"
           node -e '
             const p = JSON.parse(process.argv[1]);
@@ -126,49 +149,100 @@ jobs:
 
       - name: Build
         if: steps.plan.outputs.skip != 'true'
+        env:
+          BASE: ${{ steps.plan.outputs.base }}
         run: |
           pnpm exec tsc -b
-          pnpm exec vite build --base "${{ steps.plan.outputs.base }}"
+          pnpm exec vite build --base "$BASE"
 
-      - name: Place build in gh-pages tree
+      - name: Hand the build over to the publish job
         if: steps.plan.outputs.skip != 'true'
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist
+          if-no-files-found: error
+          # Same files as before the split: upload-artifact skips dotfiles by
+          # default, and a widget's public/ may well ship some.
+          include-hidden-files: true
+          retention-days: 1
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      REPO_NAME: ${{ github.event.repository.name }}
+      CONTEXT: ${{ needs.build.outputs.context }}
+      VERSION: ${{ needs.build.outputs.version }}
+      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.
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          package-manager-cache: false
+
+      - name: Clone gh-pages into ./site
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+        run: |
+          git clone --depth 1 --branch gh-pages \
+            "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git" site \
+            || {
+              echo "gh-pages branch not found; creating an orphan."
+              git clone --depth 1 "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.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: Download the build
+        if: needs.build.outputs.skip != 'true'
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      - name: Place build in gh-pages tree
+        if: needs.build.outputs.skip != 'true'
         run: |
           SHA="$(git rev-parse --short HEAD)"
           VERSION_ARG=""
-          [ -n "${{ steps.plan.outputs.version }}" ] && VERSION_ARG="--version ${{ steps.plan.outputs.version }}"
+          [ -n "$VERSION" ] && VERSION_ARG="--version $VERSION"
           node scripts/deploy.mjs place \
             --site site --repo "$REPO_NAME" \
-            --channel "${{ steps.plan.outputs.context }}" $VERSION_ARG \
+            --channel "$CONTEXT" $VERSION_ARG \
             --dist dist \
-            --sha "$SHA" --ref "${{ github.ref }}"
+            --sha "$SHA" --ref "$REF"
 
       - name: Skip (already published)
-        if: steps.plan.outputs.skip == 'true'
-        run: echo "== skip — v${{ steps.plan.outputs.version }} already published"
+        if: needs.build.outputs.skip == 'true'
+        run: echo "== skip — v${VERSION} already published"
 
       - name: Finalize (versions.json + commit + push)
+        env:
+          SHA_FULL: ${{ github.sha }}
         run: |
           UPDATE_VERSIONS=""
-          if [ "${{ steps.plan.outputs.context }}" = "release" ]; then
+          if [ "$CONTEXT" = "release" ]; then
             UPDATE_VERSIONS="--update-versions"
           fi
           node scripts/deploy.mjs finalize \
             --site site --repo "$REPO_NAME" $UPDATE_VERSIONS --push \
-            --commit-message "deploy: ${{ steps.plan.outputs.context }} @ ${{ github.sha }}"
-
-      # On this repo's first genuine release only: reset package.json's version
-      # to 0.0.1 (so the next release bumps to 0.0.2 rather than any inherited
-      # canary version), prune every branch except main/dev/gh-pages, and
-      # reset dev to main's current tip. Establishes the state every widget
-      # should start from regardless of how the repo was created -- a CLI
-      # scaffold already satisfies it trivially; a repo copied via GitHub's
-      # "Use this template" often doesn't (an inherited version, a stray
-      # branch, or dev tracking the source template's own preview history).
-      # Placed after Finalize so it never runs if the release itself failed.
-      # The version-reset commit re-triggers this workflow on main, but that
-      # run sees v0.0.1 already published (firstRelease=false) and no-ops.
+            --commit-message "deploy: ${CONTEXT} @ ${SHA_FULL}"
+
       - name: Reset repo to a clean first-release state
-        if: steps.plan.outputs.context == 'release' && steps.plan.outputs.firstRelease == 'true'
+        if: needs.build.outputs.context == 'release' && needs.build.outputs.firstRelease == 'true'
         run: node scripts/deploy.mjs reset-branches --repo "$REPO_NAME"
 
   cleanup:
@@ -176,6 +250,8 @@ jobs:
     # (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
+    permissions:
+      contents: write
     steps:
       - name: Checkout (default branch — for scripts/deploy.mjs)
         uses: actions/checkout@v7
@@ -188,9 +264,12 @@ jobs:
 
       - name: Clone gh-pages into ./site (skip if it does not exist)
         id: clone
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
         run: |
           if git clone --depth 1 --branch gh-pages \
-              "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" site; then
+              "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.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"
@@ -201,8 +280,10 @@ jobs:
 
       - name: Remove dev dir + push
         if: steps.clone.outputs.exists == 'true'
+        env:
+          DELETED_REF: ${{ github.event.ref }}
         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 }}"
+            --commit-message "cleanup: retire dev URL for ${DELETED_REF}"

package/template/AGENTS.md

@@ -94,6 +94,9 @@ Full detail, including the two live URLs (`/latest/` and `/v<version>/`): `READM
   template works (see above); `pnpm test` is the trusted local loop, real Grist via `/dev/`
   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
+  `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
   pipeline, the build config) are applied by hand —

package/template/README.md

@@ -2,11 +2,15 @@
 
 Base template to build a Grist widget with `grist-widget-sdk`.
 
+<!-- install-url:start -->
+**Install URL**: written here by this widget's first release (its GitHub Pages `/latest/` URL).
+<!-- install-url:end -->
+
 `src/main.tsx` wraps the app with `GristWidgetProvider`, `GristBoundary`, and `GristSdkAlerts`. The latter maps `getGristSdkAlertDescriptors()` from the SDK to shadcn `Alert` (`src/components/grist-sdk-alerts.tsx` + `src/components/ui/alert.tsx`); keep them in sync with the playground when you change alert styling.
 
 Opened outside a Grist iframe, `main.tsx` picks between two components — never a live preview of the widget itself, since nothing here proves anything about real Grist behavior: local `pnpm dev` renders `LocalDevNotice`, a bare shell pointing at the real verification loop below (push to `dev`, open it in a real Grist document); any built/deployed URL (root, `/latest/`, `/dev/`, `/v<version>/` — all carrying the same build, see Deployment below) renders `ReleaseInfo` instead — which build this is, chips to jump to any other version/channel (hover one to see when it shipped; `src/lib/showcase-versions.ts`), and a copy-this-URL helper for pasting into Grist's custom widget field.
 
-When actually embedded, `GristStatusChip` (`src/components/grist-status-chip.tsx`) shows a small pill with live handshake status — connecting, retrying with a countdown, connected, or unavailable — using `useAmbientGristHandshake()` from `grist-widget-sdk/advanced`. It must be mounted *inside* `GristWidgetProvider` (see `src/main.tsx`): it only observes that provider's own handshake manager and never mounts a second one, so it's purely observational and can never duplicate or race the real handshake (see the [handshake API reference](https://gristwidgets.com/docs/sdk/api/handshake)).
+When actually embedded, the widget shows connection state only when something is wrong: until Grist is connected, or if the connection is lost or fails, `GristBoundary` replaces the widget with a connecting / unavailable / error screen (the error one with a retry button); once the widget is showing, `GristSdkAlerts` reports what needs attention (column mapping, access level, a failed write…). Nothing is drawn over the widget while all is well.
 
 `src/App.tsx` uses `useGrist<TaskRow, TaskMapped>()` for the selected row (`w.record`, `w.mode`) and remounts the UI with `key={rowKey}` when the row changes — same pattern as `widgets/create-email-draft`. It ships with two mapped columns (`title`, `done`) and an editable form that saves back via `w.table.update(...)`/`w.mapBack(...)` — the smallest real starting point, not a placeholder. See `src/grist-types.example.ts` for typing patterns.
 
@@ -34,6 +38,17 @@ This is the **source** template. It is consumed two ways:
 standalone `pnpm install` (pnpm 11) exits cleanly; inside the monorepo it's
 ignored (the root workspace governs).
 
+A scaffold's first commit includes `pnpm-lock.yaml`: the CLI installs with
+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.
+
 ### Live preview
 
 This template has no live-preview deploy of its own inside this monorepo —

package/template/scripts/deploy.mjs

@@ -39,11 +39,13 @@
 //     Regenerates versions.json (release runs only) and commits + pushes the
 //     gh-pages tree with a rebase-and-retry loop.
 //
-//   reset-branches [--repo-dir <dir>] [--repo <name>]
+//   reset-branches [--repo-dir <dir>] [--repo <name>] [--owner-repo <owner/name>]
 //     On a repo's first genuine release only (caller gates on plan()'s
 //     firstRelease): renames the four placeholder-identity spots (only if
 //     --repo is given and they still carry the template's own placeholder
-//     text -- a no-op for a CLI scaffold that already renamed itself), resets
+//     text -- a no-op for a CLI scaffold that already renamed itself), writes
+//     the /latest/ install URL into README.md's install-url block (owner/name
+//     from --owner-repo, else $GITHUB_REPOSITORY; a no-op without it), resets
 //     package.json's version to 0.0.1, prunes every branch except
 //     main/dev/gh-pages, and force-resets dev to main's current tip.
 
@@ -407,6 +409,40 @@ export function deriveIdentity(repoName) {
   return { packageName, title }
 }
 
+// README.md's install-URL block. awesome-grist-widgets only registers a
+// widget whose install URL its own repo states explicitly, so the first
+// release writes it there (docs/planning/2026-11-01-widget-lifecycle-plan.md,
+// R1). A README without these markers is left alone.
+const INSTALL_URL_START = "<!-- install-url:start -->"
+const INSTALL_URL_END = "<!-- install-url:end -->"
+
+/**
+ * The GitHub Pages URL of the `/latest/` channel for `owner/repo`, the same
+ * path plan() builds the release under. A `<owner>.github.io` repo is a
+ * user/org site, served at the domain root. A custom Pages domain isn't
+ * known here: edit the README line if the widget uses one.
+ */
+export function latestPagesUrl(ownerRepo) {
+  const [owner, repo] = String(ownerRepo || "").split("/")
+  if (!owner || !repo) return null
+  const host = `${owner.toLowerCase()}.github.io`
+  const base = repo.toLowerCase() === host ? `https://${host}/` : `https://${host}/${repo}/`
+  return `${base}latest/`
+}
+
+/** README text with its install-URL block set to `url`; unchanged without the markers. */
+export function withInstallUrl(readme, url) {
+  const start = readme.indexOf(INSTALL_URL_START)
+  const end = readme.indexOf(INSTALL_URL_END, start)
+  if (start < 0 || end < 0) return readme
+  const block = [
+    INSTALL_URL_START,
+    `**Install URL**, to paste into a Grist custom widget's URL field: <${url}>`,
+    INSTALL_URL_END,
+  ].join("\n")
+  return readme.slice(0, start) + block + readme.slice(end + INSTALL_URL_END.length)
+}
+
 /**
  * The same four placeholder-identity edits
  * `packages/create-grist-widget/bin/create-grist-widget.mjs` applies at
@@ -454,7 +490,12 @@ function identityEdits({ packageName, title }) {
  * a genuine release already published (firstRelease=false) and skips both
  * the release and this reset, so there's no loop.
  */
-export function resetBranchesIfFirstRelease(repoDir, repo, keep = ["main", "dev", "gh-pages"]) {
+export function resetBranchesIfFirstRelease(
+  repoDir,
+  repo,
+  keep = ["main", "dev", "gh-pages"],
+  ownerRepo = process.env.GITHUB_REPOSITORY,
+) {
   const changedFiles = new Set()
   const renamedFiles = []
 
@@ -473,6 +514,20 @@ export function resetBranchesIfFirstRelease(repoDir, repo, keep = ["main", "dev"
   }
   const identityReset = renamedFiles.length > 0
 
+  // The install URL, for registries and for whoever reads the README.
+  let installUrl = null
+  const readmePath = join(repoDir, "README.md")
+  const url = latestPagesUrl(ownerRepo)
+  if (url && existsSync(readmePath)) {
+    const before = readFileSync(readmePath, "utf8")
+    const after = withInstallUrl(before, url)
+    if (after !== before) {
+      writeFileSync(readmePath, after)
+      changedFiles.add("README.md")
+      installUrl = url
+    }
+  }
+
   let versionReset = false
   const pkgPath = join(repoDir, "package.json")
   if (existsSync(pkgPath)) {
@@ -490,6 +545,7 @@ export function resetBranchesIfFirstRelease(repoDir, repo, keep = ["main", "dev"
   if (changedFiles.size > 0) {
     const parts = []
     if (identityReset) parts.push("personalize scaffold")
+    if (installUrl) parts.push("write install URL")
     if (versionReset) parts.push("reset version to 0.0.1")
     git(["add", ...changedFiles], repoDir)
     git(
@@ -514,7 +570,7 @@ export function resetBranchesIfFirstRelease(repoDir, repo, keep = ["main", "dev"
     deletedBranches.push(b)
   }
   git(["push", "--force", "origin", "HEAD:refs/heads/dev"], repoDir)
-  return { deletedBranches, devReset: true, versionReset, identityReset, renamedFiles }
+  return { deletedBranches, devReset: true, versionReset, identityReset, renamedFiles, installUrl }
 }
 
 // ----------------------------------------------------------------------------
@@ -577,7 +633,12 @@ function main() {
       break
     }
     case "reset-branches": {
-      const res = resetBranchesIfFirstRelease(args["repo-dir"] || ".", args.repo)
+      const res = resetBranchesIfFirstRelease(
+        args["repo-dir"] || ".",
+        args.repo,
+        undefined,
+        args["owner-repo"] || process.env.GITHUB_REPOSITORY,
+      )
       console.log("reset-branches:", JSON.stringify(res))
       break
     }

package/template/src/main.tsx

@@ -3,7 +3,6 @@ import { createRoot } from "react-dom/client"
 import { GristBoundary, GristWidgetProvider } from "grist-widget-sdk"
 
 import { GristSdkAlerts } from "@/components/grist-sdk-alerts"
-import { GristStatusChip } from "@/components/grist-status-chip"
 import { LocalDevNotice } from "@/components/local-dev-notice"
 import { ReleaseInfo } from "@/components/release-info"
 import { ThemeProvider } from "@/components/theme-provider.tsx"
@@ -34,7 +33,6 @@ createRoot(document.getElementById("root")!).render(
     <ThemeProvider>
       {isEmbedded ? (
         <GristWidgetProvider options={GRIST_OPTIONS}>
-          <GristStatusChip />
           <GristBoundary
             gate={GRIST_OPTIONS.columns?.length ? "canRender" : "ready"}
           >

package/template/src/components/grist-status-chip.tsx

@@ -1,116 +0,0 @@
-import { useEffect, useState } from "react"
-import { useAmbientGristHandshake, type GristWidgetSnapshot } from "grist-widget-sdk/advanced"
-
-import { deriveDisplayStatus, type HandshakeDisplayStatus } from "@/lib/grist-handshake-status"
-import { cn } from "@/lib/utils"
-
-// Fixed, approximate countdown shown while retrying -- not a mirror of the
-// SDK's actual internal poll backoff (an implementation detail, not part of
-// the public API surface, which ramps up from ~200ms before settling into a
-// steady cadence). Most production widgets connect in under a second per the
-// SDK's own docs, so a visibly "retrying" chip is already in that settled
-// long tail -- this just picks the same round number as a display countdown.
-const RETRY_COUNTDOWN_SECONDS = 5
-
-function useRetryCountdown(attempts: number, active: boolean) {
-  const [state, setState] = useState({ attempts, secondsLeft: RETRY_COUNTDOWN_SECONDS })
-
-  // Reset the countdown the moment a new retry attempt begins -- an
-  // "adjust state during render" pattern, not a setState-in-effect (which
-  // the linter flags): https://react.dev/learn/you-might-not-need-an-effect
-  if (active && state.attempts !== attempts) {
-    setState({ attempts, secondsLeft: RETRY_COUNTDOWN_SECONDS })
-  }
-
-  useEffect(() => {
-    if (!active) return
-    const id = setInterval(() => {
-      setState((s) => ({ ...s, secondsLeft: s.secondsLeft > 0 ? s.secondsLeft - 1 : 0 }))
-    }, 1000)
-    return () => clearInterval(id)
-  }, [attempts, active])
-
-  return state.secondsLeft
-}
-
-function StatusDot({ pulsing, className }: { pulsing: boolean; className: string }) {
-  return (
-    <span className="relative flex size-2">
-      {pulsing && (
-        <span
-          className={cn(
-            "absolute inline-flex size-full animate-ping rounded-full opacity-75",
-            className,
-          )}
-        />
-      )}
-      <span className={cn("relative inline-flex size-2 rounded-full", className)} />
-    </span>
-  )
-}
-
-/** Pure render of a display status. */
-function ChipVisual({ display, secondsLeft }: { display: HandshakeDisplayStatus; secondsLeft: number }) {
-  switch (display.kind) {
-    case "connecting":
-      return (
-        <>
-          <StatusDot pulsing className="bg-amber-500" />
-          Connecting to Grist
-        </>
-      )
-    case "retrying":
-      return (
-        <>
-          <StatusDot pulsing className="bg-amber-500" />
-          Retry Grist connection in {secondsLeft}s
-        </>
-      )
-    case "connected":
-      return (
-        <>
-          <StatusDot pulsing={false} className="bg-emerald-500" />
-          Grist connected
-        </>
-      )
-    case "unavailable":
-      return (
-        <>
-          <StatusDot pulsing={false} className="bg-destructive" />
-          Grist unavailable
-        </>
-      )
-  }
-}
-
-function RealChipContents({ snapshot }: { snapshot: GristWidgetSnapshot }) {
-  const display = deriveDisplayStatus(snapshot.lifecycle)
-  const retryAttempts = display.kind === "retrying" ? display.attempts : 0
-  const secondsLeft = useRetryCountdown(retryAttempts, display.kind === "retrying")
-  return <ChipVisual display={display} secondsLeft={secondsLeft} />
-}
-
-/**
- * Small pill showing live Grist handshake status while actually embedded in
- * Grist. Must be mounted *inside* `<GristWidgetProvider>` -- it only observes
- * that provider's own handshake manager (`useAmbientGristHandshake()`,
- * `grist-widget-sdk/advanced`) and never mounts its own, so it can't ever run
- * a second, competing `grist.ready()` call. Renders nothing outside a
- * provider.
- */
-export function GristStatusChip({ className }: { className?: string }) {
-  const handshake = useAmbientGristHandshake()
-  if (!handshake) return null
-  return (
-    <div className="pointer-events-none fixed top-2 right-2 z-50">
-      <div
-        className={cn(
-          "flex items-center gap-1.5 rounded-full border bg-background/90 px-2.5 py-1 text-xs text-muted-foreground shadow-sm backdrop-blur",
-          className,
-        )}
-      >
-        <RealChipContents snapshot={handshake.snapshot} />
-      </div>
-    </div>
-  )
-}

package/template/src/lib/grist-handshake-status.ts

@@ -1,26 +0,0 @@
-import type { GristLifecycle } from "grist-widget-sdk/advanced"
-
-// Projects the SDK's full GristLifecycle (advanced API, grist-widget-sdk/advanced)
-// down to the handful of states a small status chip needs to show.
-export type HandshakeDisplayStatus =
-  | { kind: "connecting" }
-  | { kind: "retrying"; attempts: number }
-  | { kind: "connected" }
-  | { kind: "unavailable" }
-
-export function deriveDisplayStatus(lifecycle: GristLifecycle): HandshakeDisplayStatus {
-  switch (lifecycle.phase) {
-    case "idle":
-      return { kind: "connecting" }
-    case "detecting":
-      return lifecycle.attempts > 0
-        ? { kind: "retrying", attempts: lifecycle.attempts }
-        : { kind: "connecting" }
-    case "negotiating":
-      return { kind: "connecting" }
-    case "online":
-      return { kind: "connected" }
-    case "terminated":
-      return { kind: "unavailable" }
-  }
-}