create-kedge 0.9.0 → 0.10.1

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,12 +1,15 @@
 {
   "name": "create-kedge",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chandeldivyam/Kedge.git",
     "directory": "packages/create-kedge"
   },
+  "engines": {
+    "node": ">=24"
+  },
   "type": "module",
   "description": "npx create-kedge my-store: a new Kedge store from the starter.",
   "bin": {

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";
 
@@ -71,26 +89,70 @@ export function write(dir, files) {
   }
 }
 
+/**
+ * The oldest Node and pnpm a store is tested on (p0.10 §3): `kedge generate`
+ * reads with `node:sqlite` (D-039), and the template's pnpm-workspace.yaml
+ * relies on `allowBuilds` to let workerd and esbuild fetch their binaries. The
+ * clean-machine run is what proves these; every package's `engines.node` says the same.
+ */
+export const MIN_NODE = 24;
+/**
+ * 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 }) {
+  const major = (v) => Number(/^v?(\d+)\./.exec(v ?? "")?.[1] ?? 0);
+  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\`, 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\`, then run this again`;
+  return null;
+}
+
 const USAGE = `usage: create-kedge <directory> [--name <name>] [--from-packs <dir>] [--no-install] [--no-git]`;
 
-export function main(argv, { template, run = spawnSync, log = console.log, error = console.error } = {}) {
+export function main(
+  argv,
+  { template, run = spawnSync, log = console.log, error = console.error, node = process.versions.node } = {},
+) {
   const flags = new Set(argv.filter((a) => a.startsWith("--no-")));
   const value = (f) => {
     const i = argv.indexOf(f);
     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);
+  // 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] ?? ".";
+  if (positional[0] === undefined && readdirSync(resolve(target)).length > 0) {
+    error(`this folder isn't empty: run it in an empty one, or name a new one: npm create kedge@latest my-store`);
     return 2;
   }
+  // 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({
+    node,
+    pnpm: pnpm?.status === 0 ? String(pnpm.stdout ?? "").trim() : null,
+    install: !flags.has("--no-install"),
+  });
+  if (problem) {
+    error(problem);
+    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;
@@ -118,6 +180,6 @@ export function main(argv, { template, run = spawnSync, log = console.log, error
       return g.status ?? 1;
     }
   }
-  log(`next: cd ${target} && pnpm kedge check`);
+  log(`next: ${target === "." ? "" : `cd ${target} && `}pnpm kedge check`);
   return 0;
 }