create-kide-app 0.1.5 → 0.1.7

package/README.md

@@ -5,27 +5,29 @@ Scaffold a new [Kide CMS](https://github.com/mhernesniemi/kide-cms) project.
 ## Usage
 
 ```bash
-npm create kide-app my-project
-# or
-pnpm create kide-app my-project
-# or
-bunx create-kide-app my-project
+pnpx create-kide-app my-project
 ```
 
-The CLI will guide you through:
+The CLI asks for:
 
 1. **Project name** — directory to create
 2. **Deploy target** — Local/Node.js or Cloudflare
-3. **Demo content** — optionally seed the database
+3. **Seed demo content** — local target only
 
 ## What it does
 
-- Downloads the latest Kide CMS template from GitHub
-- Applies platform-specific configuration (Node.js adapter, Cloudflare D1/R2, etc.)
-- Installs dependencies
-- Generates the CMS schema
-- Optionally seeds demo content
+- Clones the latest Kide CMS from GitHub.
+- Applies target-specific configuration (Node.js adapter, or Cloudflare D1/R2/Workers).
+- Installs dependencies with pnpm.
+- Optionally creates a GitHub repo (if the `gh` CLI is installed and authenticated).
+- Generates the CMS schema.
+- For **local**: optionally seeds demo content, then starts the dev server.
+- For **Cloudflare**: logs into wrangler (if needed), creates a D1 database and R2 bucket, applies migrations, builds and deploys, and prints the live URL + admin URL.
 
 ## Requirements
 
 - Node.js >= 22.12.0
+- `pnpm` installed
+- `git` on PATH
+- Optional: [`gh` CLI](https://cli.github.com) authenticated (`gh auth login`) for GitHub repo creation
+- For Cloudflare: a Cloudflare account (the CLI runs `wrangler login` for you)

package/index.js

@@ -2,7 +2,14 @@
 
 import * as p from "@clack/prompts";
 import { execSync, spawn } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import path from "node:path";
 
 // Async spawn wrapper so long-running commands don't block clack spinners
@@ -26,14 +33,50 @@ const runAsync = (cmd, cwd) =>
 
 // --- Package manager detection ---
 
-const pm = { name: "pnpm", exec: "pnpm exec", dlx: "pnpm dlx", run: "pnpm", install: "pnpm install" };
+const pm = {
+  name: "pnpm",
+  exec: "pnpm exec",
+  dlx: "pnpm dlx",
+  run: "pnpm",
+  install: "pnpm install",
+};
 
 // --- Template repo ---
 
 const REPO = "https://github.com/mhernesniemi/kide-cms.git";
 
 // Files from the kide-cms repo that shouldn't leak into scaffolded projects.
-const CLEANUP = ["docs", "CLAUDE.md", ".claude", "data", ".cms-data", "dist", ".astro", ".DS_Store"];
+// NOTE: `.claude/settings.local.json` is removed but `.claude/skills/` is kept,
+// so scaffolds ship the /migrate skill alongside AGENTS.md.
+const CLEANUP = [
+  "docs",
+  "CLAUDE.md",
+  ".claude/settings.local.json",
+  "data",
+  ".cms-data",
+  "dist",
+  ".astro",
+  ".DS_Store",
+];
+
+// Resolve the latest release tag (v-prefixed semver) so scaffolds pin to a
+// deliberate release instead of whatever HEAD happens to be. Returns null when
+// the repo has no tags (falls back to the default branch).
+const resolveLatestTag = () => {
+  try {
+    const output = execSync(
+      `git ls-remote --tags --sort=-v:refname ${REPO} "v*"`,
+      { stdio: "pipe" },
+    ).toString();
+    for (const line of output.split("\n")) {
+      const match = line.match(/refs\/tags\/(v[0-9][^^\s]*)$/);
+      if (match) return match[1];
+    }
+  } catch {
+    // Network/git hiccup — fall back to default branch
+  }
+  return null;
+};
 
 // --- Main ---
 
@@ -97,8 +140,24 @@ async function main() {
 
   s.start(`Scaffolding project (using ${pm.name})`);
 
+  const templateRef = resolveLatestTag();
+  let templateCommit = null;
+
   try {
-    execSync(`git clone --depth 1 ${REPO} "${projectDir}"`, { stdio: "pipe" });
+    const branchFlag = templateRef ? `--branch "${templateRef}" ` : "";
+    execSync(`git clone --depth 1 ${branchFlag}${REPO} "${projectDir}"`, {
+      stdio: "pipe",
+    });
+    try {
+      templateCommit = execSync("git rev-parse HEAD", {
+        cwd: projectDir,
+        stdio: "pipe",
+      })
+        .toString()
+        .trim();
+    } catch {
+      // best-effort — stamp without a commit hash
+    }
     rmSync(path.join(projectDir, ".git"), { recursive: true, force: true });
   } catch {
     s.stop("Failed to download template.");
@@ -111,7 +170,11 @@ async function main() {
     rmSync(path.join(projectDir, f), { recursive: true, force: true });
   }
 
-  s.stop("Project scaffolded");
+  s.stop(
+    templateRef
+      ? `Project scaffolded from ${templateRef}`
+      : "Project scaffolded",
+  );
 
   // --- Apply target-specific files ---
 
@@ -121,13 +184,32 @@ async function main() {
   const targetDir = path.join(adaptersDir, target);
 
   if (target === "cloudflare") {
-    cpSync(path.join(targetDir, "astro.config.mjs"), path.join(projectDir, "astro.config.mjs"));
-    cpSync(path.join(targetDir, "src/cms/adapters/db.ts"), path.join(projectDir, "src/cms/adapters/db.ts"));
-    cpSync(path.join(targetDir, "drizzle.config.ts"), path.join(projectDir, "drizzle.config.ts"));
-    cpSync(path.join(targetDir, "src/cms/adapters/storage.ts"), path.join(projectDir, "src/cms/adapters/storage.ts"));
+    cpSync(
+      path.join(targetDir, "astro.config.mjs"),
+      path.join(projectDir, "astro.config.mjs"),
+    );
+    cpSync(
+      path.join(targetDir, "src/cms/adapters/db.ts"),
+      path.join(projectDir, "src/cms/adapters/db.ts"),
+    );
+    cpSync(
+      path.join(targetDir, "drizzle.config.ts"),
+      path.join(projectDir, "drizzle.config.ts"),
+    );
+    cpSync(
+      path.join(targetDir, "src/cms/adapters/storage.ts"),
+      path.join(projectDir, "src/cms/adapters/storage.ts"),
+    );
+    cpSync(
+      path.join(targetDir, "src/cms/adapters/cf-env.ts"),
+      path.join(projectDir, "src/cms/adapters/cf-env.ts"),
+    );
     const uploadsRouteDir = path.join(projectDir, "src/pages/uploads");
     mkdirSync(uploadsRouteDir, { recursive: true });
-    cpSync(path.join(targetDir, "src/pages/uploads/[...path].ts"), path.join(uploadsRouteDir, "[...path].ts"));
+    cpSync(
+      path.join(targetDir, "src/pages/uploads/[...path].ts"),
+      path.join(uploadsRouteDir, "[...path].ts"),
+    );
   }
 
   const pkgPath = path.join(projectDir, "package.json");
@@ -142,27 +224,101 @@ async function main() {
     // Move better-sqlite3 to devDependencies — drizzle-kit needs it to push schema to local D1
     if (pkg.dependencies["better-sqlite3"]) {
       if (!pkg.devDependencies) pkg.devDependencies = {};
-      pkg.devDependencies["better-sqlite3"] = pkg.dependencies["better-sqlite3"];
+      pkg.devDependencies["better-sqlite3"] =
+        pkg.dependencies["better-sqlite3"];
       delete pkg.dependencies["better-sqlite3"];
     }
     delete pkg.dependencies["sharp"];
 
-    let wranglerContent = readFileSync(path.join(targetDir, "wrangler.toml"), "utf-8");
-    wranglerContent = wranglerContent.replaceAll("{{PROJECT_NAME}}", projectName);
+    let wranglerContent = readFileSync(
+      path.join(targetDir, "wrangler.toml"),
+      "utf-8",
+    );
+    wranglerContent = wranglerContent.replaceAll(
+      "{{PROJECT_NAME}}",
+      projectName,
+    );
+    // Seed a placeholder database_id so `pnpm dev` works out of the box —
+    // miniflare requires a non-empty id even for the local D1. It's overwritten
+    // with the real id if a D1 is created below; otherwise paste the real id
+    // before deploying (`wrangler deploy` rejects an id it doesn't own).
+    wranglerContent = wranglerContent.replace(
+      /database_id = ""[^\n]*/,
+      `database_id = "${crypto.randomUUID()}" # local placeholder - replace with the id from \`wrangler d1 create ${projectName}-db\` before deploying`,
+    );
     writeFileSync(path.join(projectDir, "wrangler.toml"), wranglerContent);
 
     pkg.devDependencies.wrangler = "^4.0.0";
 
     pkg.scripts.dev = "astro dev";
     pkg.scripts.build = "astro build";
-    pkg.scripts.preview = "astro build && wrangler dev --config dist/server/wrangler.json";
-    pkg.scripts.deploy = "astro build && wrangler deploy --config dist/server/wrangler.json";
+    pkg.scripts.preview =
+      "astro build && wrangler dev --config dist/server/wrangler.json";
+    pkg.scripts.deploy =
+      "astro build && wrangler deploy --config dist/server/wrangler.json";
+
+    // @cloudflare/vite-plugin statically imports module.registerHooks (Node
+    // >=22.15), and Node >=23 changes the native ABI (breaking the prebuilt
+    // better-sqlite3 used for local D1). So pin Node 22.18–22.x and guard `dev`
+    // with a friendly check instead of a cryptic ESM "registerHooks" crash.
+    pkg.engines = { ...(pkg.engines ?? {}), node: ">=22.18.0" };
+    pkg.scripts.predev =
+      `node -e "const v=process.versions.node.split('.').map(Number);` +
+      `if(v[0]<22||(v[0]===22&&v[1]<18)||v[0]>=23){` +
+      `console.error('\\n[kide] Cloudflare dev needs Node 22.18+ (22.x). You have '+process.version+'.\\n` +
+      `       Run: nvm install 22 && nvm use   (or use fnm/volta)\\n');` +
+      `process.exit(1)}"`;
+    writeFileSync(path.join(projectDir, ".nvmrc"), "22\n");
   }
 
   writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 
   rmSync(adaptersDir, { recursive: true, force: true });
 
+  // Stamp the scaffold provenance. This file is the project's record of which
+  // template release it came from — used to diff against upstream and to check
+  // whether published security advisories apply to this project.
+  let cliVersion = null;
+  try {
+    cliVersion = JSON.parse(
+      readFileSync(new URL("./package.json", import.meta.url), "utf-8"),
+    ).version;
+  } catch {
+    // best-effort
+  }
+  const versionStamp = {
+    template: REPO.replace(/\.git$/, ""),
+    kideVersion: pkg.version ?? null,
+    ref: templateRef ?? "HEAD",
+    commit: templateCommit,
+    target,
+    corePath: "src/cms",
+    scaffoldedAt: new Date().toISOString(),
+    createKideApp: cliVersion,
+  };
+  writeFileSync(
+    path.join(projectDir, ".kide-version"),
+    `${JSON.stringify(versionStamp, null, 2)}\n`,
+  );
+
+  // Wire up the local MCP server so Claude Code (and other MCP clients that read
+  // a project-scoped `.mcp.json`) discover it automatically — no manual
+  // `claude mcp add` needed. The command runs from the project root, where the
+  // `cms:mcp` script lives, so no `cwd` override is required.
+  const mcpConfig = {
+    mcpServers: {
+      kide: {
+        type: "stdio",
+        command: "pnpm",
+        args: ["cms:mcp"],
+      },
+    },
+  };
+  writeFileSync(
+    path.join(projectDir, ".mcp.json"),
+    `${JSON.stringify(mcpConfig, null, 2)}\n`,
+  );
+
   s.stop("Configuration applied");
 
   // --- Install dependencies ---
@@ -179,10 +335,13 @@ async function main() {
 
   let gitInitialized = false;
   try {
-    execSync("git init -q && git add . && git commit -q -m 'Initial commit from create-kide-app'", {
-      cwd: projectDir,
-      stdio: "pipe",
-    });
+    execSync(
+      "git init -q && git add . && git commit -q -m 'Initial commit from create-kide-app'",
+      {
+        cwd: projectDir,
+        stdio: "pipe",
+      },
+    );
     gitInitialized = true;
   } catch {
     // git not available — silently skip
@@ -209,7 +368,9 @@ async function main() {
         // Get the GitHub username so we can check repo availability
         let ghUser = "";
         try {
-          ghUser = execSync("gh api user --jq .login", { stdio: "pipe" }).toString().trim();
+          ghUser = execSync("gh api user --jq .login", { stdio: "pipe" })
+            .toString()
+            .trim();
         } catch {
           // ignore
         }
@@ -222,7 +383,8 @@ async function main() {
             initialValue: projectName,
             validate: (value) => {
               if (!value) return "Repository name is required";
-              if (!/^[a-zA-Z0-9._-]+$/.test(value)) return "Only letters, numbers, dots, hyphens, and underscores";
+              if (!/^[a-zA-Z0-9._-]+$/.test(value))
+                return "Only letters, numbers, dots, hyphens, and underscores";
             },
           });
           if (p.isCancel(input)) break;
@@ -230,7 +392,10 @@ async function main() {
           if (ghUser) {
             try {
               execSync(`gh repo view ${ghUser}/${input}`, { stdio: "pipe" });
-              p.note(`A repository named "${input}" already exists. Pick a different name.`, "Name taken");
+              p.note(
+                `A repository named "${input}" already exists. Pick a different name.`,
+                "Name taken",
+              );
               continue;
             } catch {
               // Repo doesn't exist — name is free
@@ -251,14 +416,20 @@ async function main() {
           if (!p.isCancel(visibility)) {
             s.start("Creating GitHub repository");
             try {
-              execSync(`gh repo create ${repoName} ${visibility}`, { cwd: projectDir, stdio: "pipe" });
-
-              // Use SSH for the remote (works with the user's existing SSH keys;
-              // avoids HTTPS credential prompts when gh's git_protocol defaults to https).
-              execSync(`git remote add origin git@github.com:${ghUser}/${repoName}.git`, {
+              execSync(`gh repo create ${repoName} ${visibility}`, {
                 cwd: projectDir,
                 stdio: "pipe",
               });
+
+              // Use SSH for the remote (works with the user's existing SSH keys;
+              // avoids HTTPS credential prompts when gh's git_protocol defaults to https).
+              execSync(
+                `git remote add origin git@github.com:${ghUser}/${repoName}.git`,
+                {
+                  cwd: projectDir,
+                  stdio: "pipe",
+                },
+              );
               execSync("git branch -M main && git push -u origin main", {
                 cwd: projectDir,
                 stdio: "pipe",
@@ -297,7 +468,11 @@ async function main() {
         stdio: "pipe",
       }).toString();
       pushOk = !out.includes("Error:") && out.includes("Changes applied");
-      s.stop(pushOk ? "Schema pushed" : "Schema push failed — run `pnpm exec drizzle-kit push` manually");
+      s.stop(
+        pushOk
+          ? "Schema pushed"
+          : "Schema push failed — run `pnpm exec drizzle-kit push` manually",
+      );
     } catch {
       s.stop("Schema will be set up on first dev start");
     }
@@ -316,7 +491,7 @@ async function main() {
         "Seeding for Cloudflare requires a D1 database.",
         "",
         `  ${pm.dlx} wrangler d1 create ${projectName}-db`,
-        "  # Add the database_id to wrangler.toml",
+        "  # then replace the placeholder database_id in wrangler.toml",
         `  ${pm.dlx} wrangler d1 migrations apply ${projectName}-db --local`,
         `  ${pm.run} cms:seed`,
       ].join("\n"),
@@ -326,10 +501,17 @@ async function main() {
 
   // --- Cloudflare resource setup ---
 
-  const cf = { d1Created: false, r2Created: false, migrationsApplied: false, deployed: false, url: null };
+  const cf = {
+    d1Created: false,
+    r2Created: false,
+    migrationsApplied: false,
+    deployed: false,
+    url: null,
+  };
   if (target === "cloudflare") {
     const setupNow = await p.confirm({
-      message: "Set up Cloudflare resources now? (creates D1 database and R2 bucket)",
+      message:
+        "Set up Cloudflare resources now? (creates D1 database and R2 bucket)",
       initialValue: true,
     });
 
@@ -337,14 +519,26 @@ async function main() {
       // Check wrangler authentication
       let authenticated = false;
       try {
-        execSync(`${pm.exec} wrangler whoami`, { cwd: projectDir, stdio: "pipe" });
+        execSync(`${pm.exec} wrangler whoami`, {
+          cwd: projectDir,
+          stdio: "pipe",
+        });
         authenticated = true;
       } catch {
-        p.note("You need to log in to Cloudflare first.", "Wrangler login required");
-        const doLogin = await p.confirm({ message: "Open browser to log in?", initialValue: true });
+        p.note(
+          "You need to log in to Cloudflare first.",
+          "Wrangler login required",
+        );
+        const doLogin = await p.confirm({
+          message: "Open browser to log in?",
+          initialValue: true,
+        });
         if (!p.isCancel(doLogin) && doLogin) {
           try {
-            execSync(`${pm.exec} wrangler login`, { cwd: projectDir, stdio: "inherit" });
+            execSync(`${pm.exec} wrangler login`, {
+              cwd: projectDir,
+              stdio: "inherit",
+            });
             authenticated = true;
           } catch {
             s.stop("Login failed");
@@ -357,22 +551,38 @@ async function main() {
         let databaseId = null;
         s.start("Creating D1 database");
         try {
-          const output = execSync(`${pm.exec} wrangler d1 create ${projectName}-db`, {
-            cwd: projectDir,
-            stdio: "pipe",
-          }).toString();
+          const output = execSync(
+            `${pm.exec} wrangler d1 create ${projectName}-db`,
+            {
+              cwd: projectDir,
+              stdio: "pipe",
+            },
+          ).toString();
           const match = output.match(/database_id\s*=\s*"([^"]+)"/);
-          if (match) databaseId = match[1];
-          cf.d1Created = true;
-          s.stop("D1 database created");
+          if (match) {
+            databaseId = match[1];
+            cf.d1Created = true;
+            s.stop("D1 database created");
+          } else {
+            // Created but the id couldn't be parsed from wrangler's output —
+            // don't mark as done, so the summary tells the user to wire it up.
+            s.stop(
+              "D1 database created, but its id could not be read — copy the database_id to wrangler.toml manually",
+            );
+          }
         } catch (err) {
           // Already exists — look it up
           try {
-            const listOutput = execSync(`${pm.exec} wrangler d1 list`, { cwd: projectDir, stdio: "pipe" }).toString();
+            const listOutput = execSync(`${pm.exec} wrangler d1 list`, {
+              cwd: projectDir,
+              stdio: "pipe",
+            }).toString();
             const lines = listOutput.split("\n");
             const dbLine = lines.find((l) => l.includes(`${projectName}-db`));
             if (dbLine) {
-              const idMatch = dbLine.match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/);
+              const idMatch = dbLine.match(
+                /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/,
+              );
               if (idMatch) databaseId = idMatch[0];
             }
             if (databaseId) {
@@ -391,14 +601,20 @@ async function main() {
         if (databaseId) {
           const wranglerPath = path.join(projectDir, "wrangler.toml");
           let wranglerContent = readFileSync(wranglerPath, "utf-8");
-          wranglerContent = wranglerContent.replace(/database_id = "" #[^\n]*/, `database_id = "${databaseId}"`);
+          wranglerContent = wranglerContent.replace(
+            /database_id = "[^"]*"[^\n]*/,
+            `database_id = "${databaseId}"`,
+          );
           writeFileSync(wranglerPath, wranglerContent);
         }
 
         // Create R2 bucket
         s.start("Creating R2 bucket");
         try {
-          execSync(`${pm.exec} wrangler r2 bucket create ${projectName}-assets`, { cwd: projectDir, stdio: "pipe" });
+          execSync(
+            `${pm.exec} wrangler r2 bucket create ${projectName}-assets`,
+            { cwd: projectDir, stdio: "pipe" },
+          );
           cf.r2Created = true;
           s.stop("R2 bucket created");
         } catch {
@@ -410,7 +626,10 @@ async function main() {
         if (databaseId) {
           s.start("Generating database migrations");
           try {
-            execSync(`${pm.exec} drizzle-kit generate`, { cwd: projectDir, stdio: "pipe" });
+            execSync(`${pm.exec} drizzle-kit generate`, {
+              cwd: projectDir,
+              stdio: "pipe",
+            });
             s.stop("Migrations generated");
           } catch (err) {
             s.stop("Migration generation failed");
@@ -420,15 +639,20 @@ async function main() {
 
           s.start("Applying migrations to remote D1");
           try {
-            execSync(`${pm.exec} wrangler d1 migrations apply ${projectName}-db --remote`, {
-              cwd: projectDir,
-              stdio: "pipe",
-              input: "y\n",
-            });
+            execSync(
+              `${pm.exec} wrangler d1 migrations apply ${projectName}-db --remote`,
+              {
+                cwd: projectDir,
+                stdio: "pipe",
+                input: "y\n",
+              },
+            );
             cf.migrationsApplied = true;
             s.stop("Migrations applied");
           } catch {
-            s.stop("Migration apply failed — run manually with: wrangler d1 migrations apply --remote");
+            s.stop(
+              "Migration apply failed — run manually with: wrangler d1 migrations apply --remote",
+            );
           }
         }
 
@@ -441,8 +665,13 @@ async function main() {
           if (!p.isCancel(doDeploy) && doDeploy) {
             s.start("Building and deploying to Cloudflare");
             try {
-              const deployOutput = await runAsync(`${pm.run} run deploy`, projectDir);
-              const urlMatch = deployOutput.match(/https:\/\/[^\s]+\.workers\.dev/);
+              const deployOutput = await runAsync(
+                `${pm.run} run deploy`,
+                projectDir,
+              );
+              const urlMatch = deployOutput.match(
+                /https:\/\/[^\s]+\.workers\.dev/,
+              );
               if (urlMatch) cf.url = urlMatch[0];
               cf.deployed = true;
               s.stop("Deployed to Cloudflare");
@@ -489,13 +718,20 @@ async function main() {
       const lines = [`cd ${projectName}`];
       const remaining = [];
       if (!cf.d1Created) {
-        remaining.push(`  ${pm.dlx} wrangler d1 create ${projectName}-db`, "  # Copy the database_id to wrangler.toml");
+        remaining.push(
+          `  ${pm.dlx} wrangler d1 create ${projectName}-db`,
+          "  # then replace the placeholder database_id in wrangler.toml",
+        );
       }
       if (!cf.r2Created) {
-        remaining.push(`  ${pm.dlx} wrangler r2 bucket create ${projectName}-assets`);
+        remaining.push(
+          `  ${pm.dlx} wrangler r2 bucket create ${projectName}-assets`,
+        );
       }
       if (!cf.migrationsApplied) {
-        remaining.push(`  ${pm.dlx} wrangler d1 migrations apply ${projectName}-db --remote`);
+        remaining.push(
+          `  ${pm.dlx} wrangler d1 migrations apply ${projectName}-db --remote`,
+        );
       }
       if (!cf.deployed) {
         remaining.push(`  ${pm.run} run deploy`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kide-app",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Scaffold a new Kide CMS project",
   "author": "Matti Hernesniemi",
   "license": "MIT",