@alxia/create 0.1.0

package/dist/index.js

@@ -0,0 +1,599 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/main.ts
+import { stat as stat2 } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+
+// src/args.ts
+var NAME = "create-alxia";
+var TEMPLATES = ["api", "react-router"];
+function isTemplate(value) {
+  return TEMPLATES.includes(value);
+}
+function parseArgs(args) {
+  let dir;
+  let template;
+  let install = true;
+  let help = false;
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h")
+      help = true;
+    else if (arg === "--no-install")
+      install = false;
+    else if (arg === "--template" || arg === "-t" || arg.startsWith("--template=")) {
+      const value = arg.includes("=") ? arg.slice(arg.indexOf("=") + 1) : args[++i];
+      if (value === undefined || value === "") {
+        return { error: `${arg} needs a template: ${TEMPLATES.join(" or ")}.` };
+      }
+      if (!isTemplate(value)) {
+        return {
+          error: `unknown template ${value}: use ${TEMPLATES.join(" or ")}.`
+        };
+      }
+      template = value;
+    } else if (arg.startsWith("-"))
+      return { error: `unknown option ${arg}.` };
+    else if (dir === undefined)
+      dir = arg;
+    else
+      return { error: `one directory only, given ${dir} and ${arg}.` };
+  }
+  return {
+    ...dir === undefined ? {} : { dir },
+    ...template === undefined ? {} : { template },
+    install,
+    help
+  };
+}
+
+// src/target.ts
+import { readdir, rm, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+function packageName(dir) {
+  const name = basename(dir).toLowerCase().replace(/[^a-z0-9._~-]+/g, "-").replace(/^[._-]+|-+$/g, "");
+  return name || "alxia-app";
+}
+async function refusal(target, shown = target) {
+  const info = await stat(target).catch(() => {
+    return;
+  });
+  if (!info)
+    return;
+  if (!info.isDirectory())
+    return `${shown} exists and is not a directory.`;
+  const entries = (await readdir(target)).sort();
+  if (entries.length === 0)
+    return;
+  return `${shown} is not empty (${entries.slice(0, 3).join(", ")}${entries.length > 3 ? ", ..." : ""}), ` + "and create-alxia writes only into an empty directory. Choose another directory, or empty this one.";
+}
+async function clean(target, existed) {
+  if (!existed) {
+    await rm(target, { recursive: true, force: true });
+    return;
+  }
+  for (const entry of await readdir(target).catch(() => [])) {
+    await rm(join(target, entry), { recursive: true, force: true });
+  }
+}
+
+// src/templates/react-router.ts
+import { join as join2 } from "node:path";
+
+// src/versions.ts
+import { dirname } from "node:path";
+var ALXIA_PACKAGES = [
+  "@alxia/client",
+  "@alxia/core",
+  "@alxia/react-router"
+];
+var PEER_RANGES = {
+  typescript: "^6.0.3 || ^7.0.0",
+  zod: "^4.2.0",
+  "react-router": "^8.0.0",
+  vite: "^7.0.0 || ^8.0.0"
+};
+function highestMajor(range) {
+  const majors = [...range.matchAll(/(?:^|[\s|^~>=])(\d+)/g)].map((match) => Number(match[1]));
+  if (majors.length === 0)
+    throw new Error(`no major in range ${range}`);
+  return Math.max(...majors);
+}
+async function alxiaRanges(manifestUrl = new URL("../package.json", import.meta.url)) {
+  const manifest = await Bun.file(manifestUrl).json();
+  const declared = manifest.devDependencies ?? {};
+  const ranges = {};
+  for (const name of ALXIA_PACKAGES) {
+    const range = declared[name];
+    if (range === undefined) {
+      throw new Error(`@alxia/create: its package.json names no ${name}`);
+    }
+    ranges[name] = range.startsWith("workspace:") ? await workspaceRange(name, range, dirname(manifestUrl.pathname)) : range;
+  }
+  return ranges;
+}
+async function workspaceRange(name, range, from) {
+  const file = Bun.resolveSync(`${name}/package.json`, from);
+  const { version } = await Bun.file(file).json();
+  const prefix = range.slice("workspace:".length);
+  return prefix === "*" ? version : `${prefix}${version}`;
+}
+
+// src/templates/react-router.ts
+function scaffoldCommand(dir) {
+  return [
+    `create-react-router@${highestMajor(PEER_RANGES["react-router"])}`,
+    dir,
+    "--yes",
+    "--no-install",
+    "--no-git-init",
+    "--no-agent-skills",
+    "--no-motion"
+  ];
+}
+
+class ScaffoldChanged extends Error {
+  constructor(file, expected) {
+    super(`create-react-router's ${file} is not what this @alxia/create expects: ${expected}. ` + "Nothing was kept. Try the newest @alxia/create, or add @alxia/react-router to a React Router app by hand, as its README shows.");
+    this.name = "ScaffoldChanged";
+  }
+}
+var BUNFIG = `[run]
+# The React Router CLI is a node script: this starts it on Bun, which
+# alxia's server needs, even where a node is installed.
+bun = true
+`;
+var IMPORT = `import { alxia } from "@alxia/react-router/vite";
+`;
+function addPlugin(config) {
+  const calls = config.match(/\breactRouter\(\)/g) ?? [];
+  if (!config.includes('from "@react-router/dev/vite"') || !/plugins:\s*\[[^\]]*\breactRouter\(\)[^\]]*\]/.test(config) || calls.length !== 1) {
+    throw new ScaffoldChanged("vite.config.ts", 'reactRouter() from "@react-router/dev/vite", called once in plugins: [...]');
+  }
+  if (config.includes("@alxia/react-router/vite")) {
+    throw new ScaffoldChanged("vite.config.ts", "it already imports @alxia/react-router/vite");
+  }
+  return IMPORT + config.replace(/\breactRouter\(\)/, "reactRouter(), alxia()");
+}
+function addAlxia(manifest, alxia) {
+  const scripts = manifest["scripts"];
+  if (scripts?.["dev"] !== "react-router dev" || scripts["build"] !== "react-router build" || scripts["start"] === undefined || manifest.dependencies?.["react-router"] === undefined) {
+    throw new ScaffoldChanged("package.json", "react-router in its dependencies, and the scripts `dev: react-router dev`, `build: react-router build` and a `start`");
+  }
+  const dependencies = sorted({
+    ...manifest.dependencies,
+    "@alxia/core": alxia["@alxia/core"],
+    "@alxia/react-router": alxia["@alxia/react-router"]
+  });
+  return {
+    ...manifest,
+    scripts: { ...scripts, start: "bun build/server/index.js" },
+    dependencies
+  };
+}
+function sorted(deps) {
+  return Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a < b ? -1 : 1));
+}
+async function alxiaLayer(dir, alxia) {
+  const read = async (file) => {
+    const handle = Bun.file(join2(dir, file));
+    if (!await handle.exists()) {
+      throw new ScaffoldChanged(file, "it is missing");
+    }
+    return handle.text();
+  };
+  const manifest = addAlxia(JSON.parse(await read("package.json")), alxia);
+  const config = addPlugin(await read("vite.config.ts"));
+  if (await Bun.file(join2(dir, "bunfig.toml")).exists()) {
+    throw new ScaffoldChanged("bunfig.toml", "none, and there is one");
+  }
+  return {
+    manifest,
+    files: { "vite.config.ts": config, "bunfig.toml": BUNFIG }
+  };
+}
+
+// src/write.ts
+import { mkdir } from "node:fs/promises";
+import { basename as basename2, dirname as dirname2, join as join3 } from "node:path";
+
+// src/registry.ts
+function registryUrl(env) {
+  const url = env["BUN_CONFIG_REGISTRY"] || env["npm_config_registry"] || "https://registry.npmjs.org";
+  return url.replace(/\/+$/, "");
+}
+function allowedRange(name) {
+  if (name === "react-router" || name.startsWith("@react-router/")) {
+    return PEER_RANGES["react-router"];
+  }
+  return name in PEER_RANGES ? PEER_RANGES[name] : undefined;
+}
+function newestWithin(versions, range) {
+  return versions.filter((v) => !v.includes("-") && Bun.semver.satisfies(v, range)).sort(Bun.semver.order).at(-1);
+}
+async function packument(name, registry) {
+  const call = registry.fetch ?? ((request) => fetch(request));
+  const response = await call(new Request(`${registry.url}/${name.replace("/", "%2f")}`, {
+    headers: { accept: "application/vnd.npm.install-v1+json" },
+    signal: AbortSignal.timeout(registry.timeout ?? 5000)
+  }));
+  if (!response.ok)
+    throw new Error(`${response.status}`);
+  return await response.json();
+}
+function choose(versions, range, latest) {
+  if (range !== undefined)
+    return newestWithin(versions, range);
+  return latest && versions.includes(latest) ? latest : newestWithin(versions, "*");
+}
+async function bumpDependencies(manifest, registry, keep = new Set) {
+  const fields = ["dependencies", "devDependencies"];
+  const names = fields.flatMap((field) => Object.keys(manifest[field] ?? {}).filter((name) => !keep.has(name)));
+  const fetched = new Map(await Promise.all(names.map(async (name) => [
+    name,
+    await packument(name, registry).catch(() => {
+      return;
+    })
+  ])));
+  const moved = [];
+  const held = [];
+  const failed = [];
+  const unmatched = [];
+  const chosen = new Map;
+  const ordered = [...names].sort((a, b) => Number(b === "react-router") - Number(a === "react-router"));
+  for (const name of ordered) {
+    const field = fields.find((f) => manifest[f]?.[name] !== undefined);
+    const deps = field && manifest[field];
+    const current = deps?.[name];
+    if (!deps || current === undefined)
+      continue;
+    const meta = fetched.get(name);
+    if (!meta?.versions) {
+      failed.push(name);
+      continue;
+    }
+    const versions = Object.keys(meta.versions);
+    const range = allowedRange(name);
+    const latest = meta["dist-tags"]?.["latest"];
+    const follow = chosen.get("react-router");
+    const version = name.startsWith("@react-router/") && follow && versions.includes(follow) ? follow : choose(versions, range, latest);
+    if (version === undefined) {
+      unmatched.push(`${name}: no release within ${range ?? "any range"}; kept ${current}`);
+      continue;
+    }
+    chosen.set(name, version);
+    if (range !== undefined && latest && Bun.semver.order(latest, version) > 0 && !Bun.semver.satisfies(latest, range)) {
+      held.push(`${name}: kept to ${range}, where the newest is ${version}; npm's latest, ${latest}, is outside it`);
+    }
+    const next = `^${version}`;
+    if (next !== current)
+      moved.push(`${name} ${current} -> ${next}`);
+    deps[name] = next;
+  }
+  return { moved, held, failed, unmatched };
+}
+
+// src/templates/api.ts
+function apiManifest(name, alxia) {
+  return {
+    name,
+    private: true,
+    type: "module",
+    scripts: {
+      dev: "bun --watch src/server.ts",
+      build: "bun build src/server.ts --target=bun --outdir=dist",
+      start: "bun dist/server.js",
+      test: "bun test",
+      typecheck: "tsc --noEmit"
+    },
+    dependencies: {
+      "@alxia/core": alxia["@alxia/core"],
+      zod: "^4.2.0"
+    },
+    devDependencies: {
+      "@alxia/client": alxia["@alxia/client"],
+      "@types/bun": "^1.4.2",
+      typescript: "^6.0.3"
+    }
+  };
+}
+var APP = `import { alxia, defineHook } from '@alxia/core';
+import { z } from 'zod';
+
+const Todo = z.object({ id: z.number(), title: z.string(), done: z.boolean() });
+const NewTodo = z.object({ title: z.string().min(1) });
+
+/** Set API_KEY in the environment: this default is for development. */
+export const apiKey = Bun.env['API_KEY'] ?? 'dev-key';
+
+// A hook of the routes it is given to: it answers 401 without the key, and
+// that 401 joins the type of each, so the client reads it.
+const requireKey = defineHook(({ request, reply }) =>
+	request.headers.get('x-api-key') === apiKey
+		? undefined
+		: reply(401, { error: 'unauthorized' as const }),
+);
+
+const todos: z.infer<typeof Todo>[] = [];
+
+export const app = alxia()
+	.decorate({ todos })
+	.post(
+		'/todos',
+		[requireKey],
+		{ body: NewTodo, response: { 201: Todo } },
+		({ body, todos, reply }) => {
+			const todo = { id: todos.length + 1, title: body.title, done: false };
+			todos.push(todo);
+			return reply.created(todo);
+		},
+	);
+
+export type App = typeof app;
+`;
+var SERVER = `import { app } from './app';
+
+const server = app.listen(Number(Bun.env['PORT'] ?? 3000));
+console.log(\`listening on \${server.url}\`);
+`;
+var SPEC = `import { expect, test } from 'bun:test';
+import { client } from '@alxia/client';
+import { apiKey, app } from './app';
+
+const json = { 'content-type': 'application/json', 'x-api-key': apiKey };
+
+test('creates a todo from JSON', async () => {
+	const response = await app.request('/todos', {
+		method: 'POST',
+		headers: json,
+		body: JSON.stringify({ title: 'Write a route' }),
+	});
+	expect(response.status).toBe(201);
+	expect(await response.json()).toEqual({
+		id: expect.any(Number),
+		title: 'Write a route',
+		done: false,
+	});
+});
+
+test('refuses an empty title with a 400 naming it', async () => {
+	const response = await app.request('/todos', {
+		method: 'POST',
+		headers: json,
+		body: JSON.stringify({ title: '' }),
+	});
+	expect(response.status).toBe(400);
+	expect((await response.json()).issues[0].path).toEqual(['title']);
+});
+
+test('the typed client reads each status the route answers', async () => {
+	// Given the app itself, the client calls its fetch in process.
+	const api = client(app, { headers: { 'x-api-key': apiKey } });
+	const created = await api.post('/todos', { body: { title: 'Call it typed' } });
+	if (created.status !== 201) throw new Error(\`got \${created.status}\`);
+	expect(created.data.title).toBe('Call it typed'); // data is the Todo schema's type
+
+	const anonymous = await client(app).post('/todos', { body: { title: 'No key' } });
+	expect(anonymous.status).toBe(401);
+	if (anonymous.status === 401) expect(anonymous.data.error).toBe('unauthorized');
+});
+`;
+var TSCONFIG = `{
+	"compilerOptions": {
+		"types": ["bun"],
+		"lib": ["ESNext", "DOM"],
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleDetection": "force",
+		"moduleResolution": "bundler",
+		"verbatimModuleSyntax": true,
+		"noEmit": true,
+		"skipLibCheck": true,
+		"resolveJsonModule": true,
+		"strict": true,
+		"noImplicitOverride": true,
+		"noImplicitReturns": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
+		"exactOptionalPropertyTypes": true,
+		"noPropertyAccessFromIndexSignature": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"forceConsistentCasingInFileNames": true
+	},
+	"include": ["src"]
+}
+`;
+var GITIGNORE = `node_modules
+dist
+*.log
+.DS_Store
+.env
+.env.local
+`;
+var readme = (name) => `# ${name}
+
+An [alxia](https://github.com/softistx/alxia) app with
+[Zod](https://zod.dev), made with \`bun create @alxia\`.
+
+\`\`\`sh
+bun dev          # http://localhost:3000, restarted on every change
+bun test         # src/app.spec.ts: in process, and through the typed client
+bun run typecheck
+bun run build    # dist/server.js, run with \`bun start\`
+\`\`\`
+
+\`\`\`sh
+curl -X POST localhost:3000/todos \\
+  -H 'content-type: application/json' -H 'x-api-key: dev-key' \\
+  -d '{"title":"Write a route"}'
+\`\`\`
+
+- \`src/app.ts\`: the app. \`POST /todos\` validates its body with Zod, and
+  its own hook, \`requireKey\`, answers 401 without the \`x-api-key\` header.
+  Set \`API_KEY\` in the environment outside development.
+- \`src/server.ts\`: listens on \`PORT\`, 3000 by default.
+- \`src/app.spec.ts\`: \`app.request()\` and \`@alxia/client\`, no port.
+
+Next: [Getting started](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/getting-started.md)
+and the rest of [\`@alxia/core\`'s guide](https://github.com/softistx/alxia/tree/develop/packages/core/docs).
+`;
+function apiFiles(name) {
+  return {
+    "src/app.ts": APP,
+    "src/server.ts": SERVER,
+    "src/app.spec.ts": SPEC,
+    "tsconfig.json": TSCONFIG,
+    ".gitignore": GITIGNORE,
+    "README.md": readme(name)
+  };
+}
+
+// src/write.ts
+async function write(target, template, alxia, io) {
+  let manifest;
+  let files;
+  if (template === "api") {
+    manifest = apiManifest(packageName(target), alxia);
+    files = apiFiles(packageName(target));
+  } else {
+    await mkdir(dirname2(target), { recursive: true });
+    const code = await io.run([process.execPath, "x", ...scaffoldCommand(basename2(target))], dirname2(target));
+    if (code !== 0) {
+      throw new Error(`create-react-router exited with ${code}.`);
+    }
+    ({ manifest, files } = await alxiaLayer(target, alxia));
+  }
+  io.out("Resolving the newest versions alxia accepts...");
+  const bumped = await bumpDependencies(manifest, { url: registryUrl(io.env), ...io.fetch ? { fetch: io.fetch } : {} }, new Set(Object.keys(alxia)));
+  for (const line of bumped.moved)
+    io.out(`  ${line}`);
+  for (const line of [...bumped.held, ...bumped.unmatched])
+    io.out(`  ${line}`);
+  if (bumped.failed.length > 0) {
+    io.err(`${NAME}: warning: the registry did not answer for ${bumped.failed.join(", ")}; ` + "kept the versions the template ships.");
+  }
+  files["package.json"] = `${JSON.stringify(manifest, null, 2)}
+`;
+  for (const [file, content] of Object.entries(files)) {
+    await Bun.write(join3(target, file), content);
+  }
+  return true;
+}
+// src/io.ts
+function processIo() {
+  return {
+    out: (line) => console.log(line),
+    err: (line) => console.error(line),
+    ask: (question, fallback) => {
+      if (!process.stdin.isTTY)
+        return;
+      const answer = prompt(question, fallback);
+      return answer === null ? null : answer.trim() || fallback;
+    },
+    run: async (command, cwd) => Bun.spawn([...command], { cwd, stdio: ["inherit", "inherit", "inherit"] }).exited,
+    env: process.env
+  };
+}
+
+// src/main.ts
+var USAGE = `Usage: bun create @alxia [dir] [options]
+
+Writes a new alxia app in dir, which must be empty or not exist yet. Asks
+for what is not given.
+
+Options:
+  -t, --template <name>  api           an alxia app with Zod, a spec and the typed client
+                         react-router  React Router's official template, served by alxia
+  --no-install           write the files, skip bun install
+  -h, --help             show this help`;
+async function main(args, cwd, io) {
+  const options = parseArgs(args);
+  if ("error" in options) {
+    io.err(`${NAME}: ${options.error}
+
+${USAGE}`);
+    return 1;
+  }
+  if (options.help) {
+    io.out(USAGE);
+    return 0;
+  }
+  const dir = options.dir ?? io.ask("Where should the project go?", "alxia-app");
+  if (dir === null) {
+    io.err(`${NAME}: cancelled, nothing written.`);
+    return 1;
+  }
+  if (dir === undefined) {
+    io.err(`${NAME}: no directory given, and no terminal to ask in.
+
+${USAGE}`);
+    return 1;
+  }
+  const template = options.template ?? askTemplate(io);
+  if (template === null) {
+    io.err(`${NAME}: cancelled, nothing written.`);
+    return 1;
+  }
+  if (typeof template === "object") {
+    io.err(`${NAME}: ${template.error}
+
+${USAGE}`);
+    return 1;
+  }
+  const target = resolve(cwd, dir);
+  const refused = await refusal(target, dir);
+  if (refused) {
+    io.err(`${NAME}: ${refused}`);
+    return 1;
+  }
+  const existed = await stat2(target).catch(() => {
+    return;
+  }) !== undefined;
+  const made = await alxiaRanges().then((alxia) => write(target, template, alxia, io)).catch(async (error) => {
+    await clean(target, existed);
+    io.err(`${NAME}: ${error instanceof ScaffoldChanged ? "" : "failed: "}${error instanceof Error ? error.message : String(error)}`);
+    return false;
+  });
+  if (!made)
+    return 1;
+  let installed = true;
+  if (options.install) {
+    io.out(`
+Installing dependencies with bun install...`);
+    installed = await io.run([process.execPath, "install"], target) === 0;
+    if (!installed)
+      io.err(`${NAME}: bun install failed; the files are written.`);
+  }
+  io.out(done(relative(cwd, target) || ".", template, options.install && installed));
+  return installed ? 0 : 1;
+}
+function done(where, template, installed) {
+  const steps = [
+    where === "." ? undefined : `cd ${where}`,
+    installed ? undefined : "bun install",
+    "bun dev"
+  ].filter((step) => step !== undefined);
+  return `
+Done: ${where === "." ? "this directory" : where} holds the ${template} template. Next:
+
+${steps.map((step) => `  ${step}`).join(`
+`)}
+`;
+}
+function askTemplate(io) {
+  const answer = io.ask(`Which template? ${TEMPLATES.join(" or ")}`, "api");
+  if (answer === null)
+    return null;
+  if (answer === undefined) {
+    return { error: "no --template given, and no terminal to ask in." };
+  }
+  return isTemplate(answer) ? answer : { error: `unknown template ${answer}: use ${TEMPLATES.join(" or ")}.` };
+}
+
+// src/index.ts
+process.exitCode = await main(process.argv.slice(2), process.cwd(), processIo());
+
+//# debugId=8B48AE430B9AACCF64756E2164756E21
+//# sourceMappingURL=index.js.map