create-grist-widget 0.2.16 → 0.2.18

package/package.json

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

package/template/README.md

@@ -91,13 +91,16 @@ automatically.
 > it doesn't run any of the CLI's own setup (renaming `package.json`,
 > titles, etc.), and it won't reset `package.json`'s `version` back to a
 > fresh `0.0.1` for you. Do both by hand before your first real release.
-> Also **never manually seed/copy `gh-pages` content** from another repo
-> (e.g. to get Pages showing something immediately) — each `v<version>/`
-> is only recognized as a genuine prior release if it carries a
+> If you also checked **"Include all branches"** (to get `gh-pages`/Pages
+> already set up, no manual Settings step), your first real release
+> automatically clears out every leftover `v<version>/` it finds — a
+> `v<version>/` only counts as a genuine prior release once it carries a
 > `showcase-meta.json` naming *this* repo (written by this pipeline's own
-> `place` step); anything else is treated as unpublished and safely
-> rebuilt over, but it's simpler to just let the workflow create
-> `gh-pages` itself (it does, as an orphan branch, on its first real run).
+> `place` step), so on a repo with no genuine releases yet, everything
+> else is provably inherited noise and gets safely wiped on your first
+> push to `main`. That cleanup only ever runs before your *first* genuine
+> release — once one exists, it's permanently a no-op, so it's still safest
+> to never manually re-seed `gh-pages` again after that point.
 
 **One-time setup** (the workflow can't do this part for you):
 

package/template/scripts/deploy.mjs

@@ -177,6 +177,29 @@ function replaceDir(dest, srcDist) {
   cpSync(srcDist, dest, { recursive: true })
 }
 
+/**
+ * If this repo has never genuinely published a release before (no
+ * v<version>/ directory whose showcase-meta.json matches this repo), any
+ * v<version>/ directories present are provably inherited noise -- e.g. from
+ * copying this template repo including its gh-pages branch (GitHub's "Use
+ * this template" -> "Include all branches"). Safe to clear them all before
+ * placing this repo's actual first release: there is no ambiguity, since a
+ * repo with zero genuine releases can't have any of its own history to lose.
+ * Never touches dev/, latest/, or site-root files. Once a genuine release
+ * exists for this repo, buildVersionsManifest is non-empty and this is
+ * permanently a no-op.
+ */
+export function cleanupForeignVersionsIfFirstRelease(siteDir, repo) {
+  if (buildVersionsManifest(siteDir, repo).length > 0) return { cleaned: [] }
+  const cleaned = []
+  for (const name of existsSync(siteDir) ? readdirSync(siteDir) : []) {
+    if (!/^v\d+\.\d+\.\d+/.test(name)) continue
+    rmSync(join(siteDir, name), { recursive: true, force: true })
+    cleaned.push(name)
+  }
+  return { cleaned }
+}
+
 /** Place a freshly built dist into the gh-pages tree. */
 export function placeTarget({ siteDir, channel, version, distDir, sha, ref, repo }) {
   if (!existsSync(distDir)) throw new Error(`dist not found: ${distDir}`)
@@ -202,6 +225,7 @@ export function placeTarget({ siteDir, channel, version, distDir, sha, ref, repo
   // exactly like latest/ reusing it: the asset URLs it references (under
   // v<version>/assets/) already exist from the versionDir placement above,
   // so nothing 404s.
+  cleanupForeignVersionsIfFirstRelease(siteDir, repo)
   const versionDir = join(siteDir, `v${version}`)
   replaceDir(versionDir, distDir)
   writeFileSync(

package/template/src/components/template-landing.tsx

@@ -63,6 +63,28 @@ function CreateRepoButton() {
   )
 }
 
+// The fastest path: GitHub's own "generate from template" flow, with
+// history included so gh-pages/Pages content comes along -- no
+// create-grist-widget CLI, no local install. See the template README's
+// "Used GitHub's 'Use this template' button instead of `npm create
+// grist-widget`?" note for what this trades away (package.json rename,
+// version reset) in exchange for zero local setup.
+function CopyStarterRepoButton() {
+  return (
+    <div className="mt-2 ml-5">
+      <Button asChild>
+        <a
+          href="https://github.com/arthurblanchon/grist-widget-template/generate"
+          target="_blank"
+          rel="noreferrer"
+        >
+          Copy starter repo
+        </a>
+      </Button>
+    </div>
+  )
+}
+
 export function TemplateLanding() {
   const { versions, error } = useVersions()
 
@@ -84,7 +106,63 @@ export function TemplateLanding() {
 
       <div className="mb-10 rounded-lg border p-4">
         <h2 className="mb-3 font-heading text-base font-semibold">
-          Get started
+          Quickstart
+        </h2>
+        <ol className="list-inside list-decimal space-y-3 text-sm text-muted-foreground">
+          <li>
+            Copy this starter repo. On the next page, check{" "}
+            <strong className="text-foreground">Include all branches</strong>{" "}
+            so GitHub Pages comes already configured — no manual Settings
+            step.
+            <CopyStarterRepoButton />
+          </li>
+          <li>
+            Your new widget starts deploying on its first push. Ask your AI
+            coding agent for two URLs: the{" "}
+            <strong className="text-foreground">dev</strong> build (auto-reloads
+            as you iterate) and the{" "}
+            <strong className="text-foreground">latest</strong> build (ready to
+            paste into a production Grist document).
+          </li>
+        </ol>
+        <div className="mt-4 rounded-md border border-amber-500/40 bg-amber-500/10 p-3 text-xs text-muted-foreground">
+          <strong className="text-foreground">
+            If your AI can't see the new widget repo,
+          </strong>{" "}
+          check its GitHub App has been granted access to it:{" "}
+          <a
+            href="https://github.com/apps/claude"
+            target="_blank"
+            rel="noreferrer"
+            className="underline underline-offset-4 hover:text-foreground"
+          >
+            Claude
+          </a>
+          ,{" "}
+          <a
+            href="https://github.com/apps/chatgpt-codex-connector"
+            target="_blank"
+            rel="noreferrer"
+            className="underline underline-offset-4 hover:text-foreground"
+          >
+            Codex
+          </a>
+          , or{" "}
+          <a
+            href="https://github.com/apps/cursor"
+            target="_blank"
+            rel="noreferrer"
+            className="underline underline-offset-4 hover:text-foreground"
+          >
+            Cursor
+          </a>
+          .
+        </div>
+      </div>
+
+      <div className="mb-10 rounded-lg border p-4">
+        <h2 className="mb-3 font-heading text-base font-semibold">
+          Prefer the CLI?
         </h2>
         <Tabs defaultValue="claude-code">
           <TabsList className="mb-4">