create-kedge 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Kedge Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/create-kedge.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { main } from "../src/create.mjs";
+
+process.exitCode = main(process.argv.slice(2), {
+  template: join(dirname(fileURLToPath(import.meta.url)), "..", "template.json"),
+});

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "create-kedge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.9.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chandeldivyam/Kedge.git",
+    "directory": "packages/create-kedge"
+  },
+  "type": "module",
+  "description": "npx create-kedge my-store: a new Kedge store from the starter.",
+  "bin": {
+    "create-kedge": "./bin/create-kedge.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "template.json"
+  ],
+  "devDependencies": {
+    "@types/node": "24.19.2"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
 }

package/src/create.mjs

@@ -0,0 +1,123 @@
+// create-kedge: a new store from the starter (docs/proposals/p0.8-cli-agent-kit.md §2).
+// The template is `apps/starter`, which the pack script writes into
+// `template.json` (path → text) rather than as files: npm renames or drops
+// some dot files in a tarball, and a store needs its `.gitignore` and `.claude/`.
+import { spawnSync } from "node:child_process";
+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. */
+export const NAME = /^[a-z][a-z0-9-]{0,38}[a-z0-9]$/;
+/** The starter's placeholder for the store's Cloudflare names. */
+export const PLACEHOLDER = "my-store";
+
+/**
+ * A random suffix for the store's Cloudflare names (§6.1): a Worker upload
+ * is create-or-update, so a name nothing else will choose is what keeps a
+ * first deploy from overwriting another application in the same account.
+ */
+export const suffix = () => randomBytes(3).toString("hex");
+
+/** Each `@kedge/*` tarball in a pack directory, by package name. */
+export function packsIn(dir, version) {
+  const out = {};
+  for (const f of readdirSync(dir)) {
+    const m = /^kedge-(.+)-(\d+\.\d+\.\d+)\.tgz$/.exec(f);
+    if (m && m[2] === version) out[`@kedge/${m[1]}`] = resolve(dir, f);
+  }
+  return out;
+}
+
+/**
+ * The new store's files: the template with the store's name in package.json,
+ * its suffixed name in wrangler.jsonc, and each `workspace:*` pinned to the
+ * template's version. With packs, `pnpm-workspace.yaml` overrides every
+ * `@kedge/*`, transitive ones included, to its tarball.
+ */
+export function render(template, { name, suffix: sfx, packs }) {
+  if (!NAME.test(name)) throw new Error(`"${name}" isn't a store name: lowercase letters, digits and dashes, 2 to 40`);
+  const files = { ...template.files };
+  const pkg = JSON.parse(files["package.json"]);
+  pkg.name = name;
+  pkg.version = "0.0.0";
+  pkg.private = true;
+  for (const field of ["dependencies", "devDependencies"])
+    for (const [dep, v] of Object.entries(pkg[field] ?? {}))
+      if (v === "workspace:*") pkg[field][dep] = template.version;
+  files["package.json"] = `${JSON.stringify(pkg, null, 2)}\n`;
+  const wrangler = files["wrangler.jsonc"];
+  if (!wrangler?.includes(`"${PLACEHOLDER}`)) throw new Error(`the template's wrangler.jsonc lacks "${PLACEHOLDER}"`);
+  files["wrangler.jsonc"] = wrangler.replaceAll(PLACEHOLDER, `${name}-${sfx}`);
+  // pnpm runs no dependency's install script unless allowed: workerd and
+  // esbuild fetch their binaries in theirs, and Wrangler needs both.
+  let workspace = "allowBuilds:\n  esbuild: true\n  workerd: true\n";
+  if (packs) {
+    const lines = Object.entries(packs)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([dep, file]) => `  "${dep}": "file:${file}"`);
+    workspace += `# Kedge's packages from local tarballs (create-kedge --from-packs).\noverrides:\n${lines.join("\n")}\n`;
+  }
+  files["pnpm-workspace.yaml"] = workspace;
+  return files;
+}
+
+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`);
+    const target = join(dir, path);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, text);
+  }
+}
+
+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 } = {}) {
+  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);
+    return 2;
+  }
+  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 fromPacks = value("--from-packs");
+  const t = JSON.parse(readFileSync(template, "utf8"));
+  let files;
+  try {
+    files = render(t, { name, suffix: suffix(), packs: fromPacks ? packsIn(fromPacks, t.version) : undefined });
+  } catch (e) {
+    error(e.message);
+    return 1;
+  }
+  mkdirSync(dir, { recursive: true });
+  write(dir, files);
+  log(`created ${name} in ${dir} (Kedge ${t.version})`);
+  if (!flags.has("--no-git")) run("git", ["init", "-q"], { cwd: dir, stdio: "inherit" });
+  if (!flags.has("--no-install")) {
+    const r = run("pnpm", ["install"], { cwd: dir, stdio: "inherit" });
+    if (r.status !== 0) {
+      error("pnpm install failed; fix it and run `pnpm install` in the store");
+      return r.status ?? 1;
+    }
+    // The agent kit's skills ship in @kedge/docs and are copied by generate, gitignored, so the
+    // store's AGENTS.md can point an agent at them from its first session (p0.8 §9.3).
+    const g = run("pnpm", ["exec", "kedge", "generate"], { cwd: dir, stdio: "inherit" });
+    if (g.status !== 0) {
+      error("kedge generate failed; run `pnpm kedge generate` in the store");
+      return g.status ?? 1;
+    }
+  }
+  log(`next: cd ${target} && pnpm kedge check`);
+  return 0;
+}