create-grist-widget 0.2.3 → 0.2.5

package/README.md

@@ -14,4 +14,72 @@ The template ships embedded in this package — nothing is fetched from GitHub a
 scaffold time. See [Getting started](https://grist-widgets.com/guide/getting-started)
 for the full walkthrough (dev loop, deploying, embedding in Grist).
 
+## Using Claude Code?
+
+The scaffolded project ships a working GitHub Pages deploy pipeline
+([release + dev channels](https://grist-widgets.com/guide/getting-started)), which
+needs a couple of one-time repo settings that only a human can click through. The
+simplest way to get from zero to a deployed widget:
+
+1. Create a new, empty GitHub repo for the widget.
+2. Install the [Claude GitHub App](https://github.com/apps/claude) on that repo.
+3. Start a Claude Code session connected to it and ask it to scaffold and push:
+
+   ```bash
+   npm create grist-widget my-widget
+   cd my-widget
+   ```
+
+   The scaffold already commits itself on `main` (the branch the deploy
+   workflow releases from) with a `dev` branch ready alongside it — no
+   separate `git init`/`git commit` needed. Just add the remote and push:
+
+   ```bash
+   git remote add origin https://github.com/<owner>/<repo>.git
+   git push -u origin main
+   git push origin dev   # optional, for the live-preview channel
+   ```
+
+4. That push triggers the deploy workflow's first run. Once it completes
+   (it creates a `gh-pages` branch), there's **one one-time setting**:
+   Settings → Pages → Source → **Deploy from a branch** → branch `gh-pages`,
+   folder `/ (root)`. This can only be set once `gh-pages` exists, which is
+   why it's a step *after* the first push, not before.
+
+   Once that's saved, your widget is live at two URLs:
+
+   - `https://<owner>.github.io/<repo>/latest/` — mutable, always points at
+     whatever version was last released.
+   - `https://<owner>.github.io/<repo>/v<version>/` — immutable, e.g. `/v0.0.1/`;
+     this exact version, forever, even after later releases move `/latest/`.
+
+   Paste whichever one fits into Grist's custom widget URL field — `/latest/`
+   if you want the widget to update automatically as you release new
+   versions, or a pinned `/v<version>/` if you don't.
+
+   > If the very first workflow run fails with a permissions error pushing
+   > to `gh-pages`, your repo's default Actions token permissions are
+   > read-only — Settings → Actions → General → Workflow permissions →
+   > **Read and write permissions** fixes it. Most repos don't need this;
+   > it depends on account/org defaults.
+
+5. **Ongoing workflow: always develop on `dev`, release by merging to `main`.**
+   The `dev` branch already exists from step 3. From here on:
+
+   - Commit and push to `dev` for every change. Each push auto-deploys a live
+     preview at `https://<owner>.github.io/<repo>/dev/` that self-reloads
+     inside an open Grist document a few seconds later.
+   - Ready to publish? **Bump `package.json`'s `version`** as part of your
+     `dev` changes, then open a PR from `dev` into `main` and merge it —
+     merging is what actually publishes (`/v<version>/` + `/latest/`).
+
+   > ⚠️ **Merging without a version bump publishes nothing.** The release
+   > build skips whenever the version already has a published `v<version>/`
+   > directory, which is always true if you forgot to bump it. The PR merges
+   > cleanly and CI runs "successfully," but `/latest/` doesn't change. Bump
+   > the version *before* merging.
+
+   Keep committing to the same `dev` branch afterward — it's the permanent
+   working/preview branch, not a one-off branch to delete per change.
+
 MIT licensed.

package/bin/create-grist-widget.mjs

@@ -2,6 +2,7 @@
 import { existsSync, mkdirSync, readdirSync, cpSync, readFileSync, writeFileSync, renameSync } from "node:fs"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
+import { execFileSync } from "node:child_process"
 
 const TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "template")
 
@@ -49,7 +50,41 @@ for (const [file, subs] of edits) {
   writeFileSync(p, content)
 }
 
+// Initialize git on `main` with the scaffold as its first commit, and a
+// `dev` branch ready to push for live-preview later. Doing this here (not
+// leaving it to whoever/whatever runs next) is what actually prevents the
+// scaffold from ending up on some other branch — the deploy workflow only
+// ever releases from `main`, so committing anywhere else silently never
+// deploys. Degrades gracefully: if there's no git identity configured yet,
+// `main` still exists locally, just without a commit.
+function git(args) {
+  execFileSync("git", args, { cwd: target, stdio: "ignore" })
+}
+let committed = false
+try {
+  git(["init", "-q", "-b", "main"])
+  git(["add", "-A"])
+  git(["commit", "-q", "-m", "scaffold: initial widget"])
+  git(["branch", "dev"])
+  committed = true
+} catch {
+  // No git identity configured (or git unavailable) — leave it to the
+  // printed next steps below.
+}
+
 console.log(`Created ${rawName}/\n`)
 console.log(`  cd ${rawName}`)
 console.log("  pnpm install   # or npm/yarn")
 console.log("  pnpm dev")
+if (committed) {
+  console.log("\nGit is initialized on main (first commit done) with a dev branch ready.")
+  console.log("To push to GitHub:")
+  console.log("  git remote add origin https://github.com/<owner>/<repo>.git")
+  console.log("  git push -u origin main")
+  console.log("  git push origin dev   # optional, for the live-preview channel")
+} else {
+  console.log("\nCould not create the initial git commit automatically (no git identity")
+  console.log('configured?) — run `git config user.name`/`user.email`, then:')
+  console.log("  git init -b main && git add -A && git commit -m 'scaffold: initial widget'")
+  console.log("  git branch dev")
+}

package/package.json

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

package/template/README.md

@@ -33,16 +33,30 @@ ignored (the root workspace governs).
 ## Deployment
 
 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.
+`scripts/deploy.mjs`) publishes this widget to **your own** GitHub Pages.
+
+### The workflow: always develop on `dev`, release by merging to `main`
+
+1. Commit and push to the `dev` branch (created for you at scaffold time).
+   Every push auto-deploys a live preview at `/dev/` that self-reloads
+   inside an open Grist document a few seconds later — paste that URL into
+   a Grist doc once, then just keep pushing while you iterate.
+2. Ready to publish a release? **Bump `package.json`'s `version`** as part
+   of your `dev` branch changes, then open a PR from `dev` into `main`.
+3. **Merge the PR.** This is the step that actually publishes — merging to
+   `main` builds immutable `/v<version>/` and updates mutable `/latest/`.
+
+> ⚠️ **Merging without bumping the version publishes nothing.** The release
+> build is idempotent — it skips whenever `package.json`'s version already
+> has a matching `v<version>/` directory published, which is always true if
+> you forgot to bump it (it'll match whatever's already live). The PR merges
+> cleanly and CI runs "successfully," but `/latest/` silently stays exactly
+> as it was. Bump the version *before* merging, not after.
+
+After merging, keep committing to the same `dev` branch for your next round
+of changes — it's the permanent working/preview branch for this widget, not
+a one-off feature branch to delete and recreate. Deleting it retires `/dev/`
+automatically.
 
 **One-time setup** (the workflow can't do this part for you):