create-kedge 0.10.0 → 0.11.0

package/README.md

@@ -0,0 +1,49 @@
+# create-kedge
+
+A new [Kedge](https://www.npmjs.com/package/@kedge/cli) store: an open-source (MIT)
+headless commerce backend that runs on Cloudflare Workers and D1, in your own
+Cloudflare account.
+
+```sh
+mkdir my-store && cd my-store
+npm create kedge@latest
+```
+
+Run it in an empty folder, or name a new one: `npm create kedge@latest my-store`.
+The store's name comes from the folder (`--name` chooses another). It needs Node 24
+or newer and pnpm 10 or newer (`npm install --global pnpm`), and checks both
+before it writes anything.
+
+## With a coding agent
+
+Give your agent this page and ask: *"Make me a Kedge store and place a test
+order."* The store it makes carries the `kedge-start` skill (in `.claude/skills/`
+and `.agents/skills/`), which holds the steps below. A command that needs you
+stops with exit code 3 and one line starting `for you:`; your agent passes it on.
+
+## The first run
+
+**On this machine** (no Cloudflare account needed):
+
+1. `pnpm kedge check --fast`
+2. `pnpm kedge dev` (keep it running): the store at `http://localhost:8787`, its
+   admin at `/app/`.
+3. `pnpm kedge staff invite-owner you@example.com`: open the link it prints, set a
+   password and an authenticator, and you're the store's Owner.
+4. `pnpm kedge seed --sample apparel --url http://localhost:8787`
+5. `pnpm kedge smoke --url http://localhost:8787`: a test order, placed.
+
+**On Cloudflare** (a Workers Paid account):
+
+1. Commit the store: `git add -A && git commit -m "A new Kedge store"`.
+2. Give the CLI credentials: `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` in
+   `.env.local`, or `npx wrangler login`. `pnpm kedge doctor --remote` checks them.
+3. `pnpm kedge deploy --jurisdiction <eu|us|fedramp|none>`: where the store's data
+   lives, chosen once.
+4. `pnpm kedge staff invite-owner you@example.com --remote`: your invite.
+5. `pnpm kedge seed --sample apparel --url <store> --live` and
+   `pnpm kedge smoke --url <store> --live`: sample products and a test order on the
+   live store.
+
+Every command takes `--json` for a single result object on stdout. The installed
+`@kedge/docs` holds the guides for extending the store, matched to its version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kedge",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/create.mjs

@@ -7,8 +7,26 @@ import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 
-/** A store's name: it becomes Worker, database and queue names, so Cloudflare's rules apply. */
+/**
+ * Kedge's rule for a store's name, not Cloudflare's: with its six-character
+ * suffix it becomes the Worker's, the databases' and the queue's names, and a
+ * preview's Worker adds more, all inside Cloudflare's 63 characters for a
+ * workers.dev name (letters, digits and dashes, no dash first or last:
+ * https://developers.cloudflare.com/workers/configuration/routing/workers-dev/#limitations).
+ */
 export const NAME = /^[a-z][a-z0-9-]{0,38}[a-z0-9]$/;
+
+/** A store name from any folder's name (p0.10.1 §2): always one that meets NAME, so a folder is never refused. */
+export function storeNameOf(folder) {
+  let s = folder
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!s) return "my-store";
+  if (!/^[a-z]/.test(s)) s = `store-${s}`;
+  s = s.slice(0, 40).replace(/-+$/, "");
+  return s.length < 2 ? "my-store" : s;
+}
 /** The starter's placeholder for the store's Cloudflare names. */
 export const PLACEHOLDER = "my-store";
 
@@ -62,6 +80,31 @@ export function render(template, { name, suffix: sfx, packs }) {
   return files;
 }
 
+/** The folder's entries, none when it doesn't exist yet. */
+const existing = (dir) => (existsSync(dir) ? readdirSync(dir) : []);
+
+/** The top-level names the template writes. */
+const ownedTop = (files) => new Set(Object.keys(files).map((p) => p.split("/")[0]));
+
+/** An existing .gitignore with each of the starter's lines it lacks appended, its own lines as they were. */
+/** Where the CLI and kedge dev write credentials and keys: never tracked (p0.10 §4, §6.2). */
+const CREDENTIAL_PATHS = [".env.local", ".env.development.local", ".dev.vars", ".kedge/state.db"];
+
+export function mergeIgnore(mine, starter) {
+  const lines = mine.split("\n").map((l) => l.trim());
+  // A rule counts as present only if no exception follows it: `.env*` then `!.env.local` would commit
+  // the credentials the starter's `.env*` keeps out (codex code r4), so such a rule is appended again, last.
+  const holds = (rule) => {
+    const at = lines.lastIndexOf(rule);
+    return at >= 0 && !lines.slice(at + 1).some((l) => l.startsWith("!"));
+  };
+  const add = starter
+    .split("\n")
+    .filter((l) => l.trim() && (l.trim().startsWith("#") ? !lines.includes(l.trim()) : !holds(l.trim())));
+  if (!add.length) return mine;
+  return `${mine.replace(/\n*$/, "\n")}# Kedge's starter (create-kedge):\n${add.join("\n")}\n`;
+}
+
 export function write(dir, files) {
   for (const [path, text] of Object.entries(files)) {
     if (isAbsolute(path) || path.split("/").includes("..")) throw new Error(`template path ${path} escapes the store`);
@@ -78,7 +121,12 @@ export function write(dir, files) {
  * clean-machine run is what proves these; every package's `engines.node` says the same.
  */
 export const MIN_NODE = 24;
-export const MIN_PNPM = 11;
+/**
+ * pnpm 10 runs the store's pinned pnpm (`packageManager`, pnpm@11.11.0 in the
+ * starter) by itself: measured 2026-11-01, `npx pnpm@10 --version` in such a
+ * folder answers 11.11.0 (p0.10.1 §1, 3).
+ */
+export const MIN_PNPM = 10;
 
 /** What this machine lacks, with the one command that fixes it; null when nothing. */
 export function environmentProblem({ node, pnpm, install }) {
@@ -86,9 +134,10 @@ export function environmentProblem({ node, pnpm, install }) {
   if (major(node) < MIN_NODE)
     return `Kedge needs Node ${MIN_NODE} or newer, and this is ${node}: install it from https://nodejs.org (or \`nvm install ${MIN_NODE}\`), then run this again`;
   if (!install) return null;
-  if (!pnpm) return `Kedge stores install with pnpm, which isn't on the path: run \`npm install --global pnpm@${MIN_PNPM}\`, then run this again`;
+  if (!pnpm)
+    return `Kedge stores install with pnpm, which isn't on the path: run \`npm install --global pnpm\`, then run this again`;
   if (major(pnpm) < MIN_PNPM)
-    return `Kedge needs pnpm ${MIN_PNPM} or newer, and this is ${pnpm}: run \`npm install --global pnpm@${MIN_PNPM}\`, then run this again`;
+    return `Kedge needs pnpm ${MIN_PNPM} or newer, and this is ${pnpm}: run \`npm install --global pnpm\`, then run this again`;
   return null;
 }
 
@@ -104,11 +153,8 @@ export function main(
     return i >= 0 ? argv[i + 1] : undefined;
   };
   const positional = argv.filter((a, i) => !a.startsWith("--") && !["--name", "--from-packs"].includes(argv[i - 1]));
-  const target = positional[0];
-  if (!target) {
-    error(USAGE);
-    return 2;
-  }
+  // No directory: the folder it's run in, as `npm create kedge@latest` alone leaves it (p0.10.1 §1, 1).
+  const target = positional[0] ?? ".";
   // Before anything is written: a half-made store on a machine that can't install it helps no one.
   const pnpm = flags.has("--no-install") ? null : run("pnpm", ["--version"], { encoding: "utf8" });
   const problem = environmentProblem({
@@ -121,11 +167,9 @@ export function main(
     return 1;
   }
   const dir = resolve(target);
-  if (existsSync(dir) && readdirSync(dir).length > 0) {
-    error(`${dir} isn't empty`);
-    return 1;
-  }
-  const name = value("--name") ?? basename(dir).toLowerCase();
+  const chosen = value("--name");
+  const name = chosen ?? storeNameOf(basename(dir));
+  if (!chosen) log(`store name ${name}, from the folder; --name to choose another`);
   const fromPacks = value("--from-packs");
   const t = JSON.parse(readFileSync(template, "utf8"));
   let files;
@@ -135,10 +179,39 @@ export function main(
     error(e.message);
     return 1;
   }
+  // A workspace's own dot-entries (.git, .salve, .vscode) may already be here: a platform like salve
+  // loads AGENTS.md and skills only from its root (p0.11 row 11). Anything the template writes may not.
+  const clash = existing(dir).filter((e) => !e.startsWith(".") || (e !== ".gitignore" && ownedTop(files).has(e)));
+  if (clash.length) {
+    error(
+      `${dir} already holds ${clash.join(", ")}: run it in an empty folder, or one holding only its own dot-files, or name a new one: npm create kedge@latest my-store`,
+    );
+    return positional[0] === undefined ? 2 : 1;
+  }
   mkdirSync(dir, { recursive: true });
+  const ignore = join(dir, ".gitignore");
+  if (existsSync(ignore) && files[".gitignore"] !== undefined)
+    files[".gitignore"] = mergeIgnore(readFileSync(ignore, "utf8"), files[".gitignore"]);
   write(dir, files);
   log(`created ${name} in ${dir} (Kedge ${t.version})`);
-  if (!flags.has("--no-git")) run("git", ["init", "-q"], { cwd: dir, stdio: "inherit" });
+  // Inside a repository already (a workspace's), the store is part of it: no repository inside another (p0.11 row 12).
+  const inRepo =
+    String(run("git", ["rev-parse", "--is-inside-work-tree"], { cwd: dir, encoding: "utf8" })?.stdout ?? "").trim() ===
+    "true";
+  if (!flags.has("--no-git") && !inRepo) run("git", ["init", "-q"], { cwd: dir, stdio: "inherit" });
+  // Whatever else the repository's ignore files say, the credentials the CLI saves stay out of Git.
+  if (inRepo || !flags.has("--no-git")) {
+    const kept = CREDENTIAL_PATHS.filter(
+      // 1 is "not ignored"; no git, or no repository (128), is no answer.
+      (p) => run("git", ["check-ignore", "-q", p], { cwd: dir, stdio: "ignore" })?.status === 1,
+    );
+    if (kept.length) {
+      error(
+        `Git here wouldn't ignore ${kept.join(", ")}, where the CLI saves credentials and keys: add them to .gitignore (an exception such as !.env.local overrides the starter's rule) before anything is committed`,
+      );
+      return 1;
+    }
+  }
   if (!flags.has("--no-install")) {
     const r = run("pnpm", ["install"], { cwd: dir, stdio: "inherit" });
     if (r.status !== 0) {
@@ -153,6 +226,6 @@ export function main(
       return g.status ?? 1;
     }
   }
-  log(`next: cd ${target} && pnpm kedge check`);
+  log(`next: ${target === "." ? "" : `cd ${target} && `}pnpm kedge check`);
   return 0;
 }