create-headless-lms 0.1.0

package/README.md

@@ -0,0 +1,19 @@
+# create-headless-lms
+
+Scaffolds a standalone LMS installation: `npm create headless-lms` (or
+`create-headless-lms <name> --yes` for defaults). An interactive wizard asks
+for name, ports, database and storage settings, renders `templates/` into a
+new project depending on `@headless-lms/server` + `@headless-lms/cli`, then
+offers to install and migrate.
+
+The generated installation owns only its config, entry point, and integration
+plugins — the backend itself is the server library.
+
+## Develop
+
+```bash
+pnpm --filter create-headless-lms build
+pnpm --filter create-headless-lms test
+bash scripts/e2e.sh   # scaffold → install packed workspace tarballs → migrate → boot
+                      # (needs docker Postgres from docker/docker-compose.yml)
+```

package/dist/index.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { join, resolve } from "node:path";
+import * as p from "@clack/prompts";
+import { cp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+//#region src/args.ts
+function parseArgs(argv) {
+	const yes = argv.includes("--yes") || argv.includes("-y");
+	return {
+		name: argv.find((a) => !a.startsWith("-")),
+		yes
+	};
+}
+/** Returns an error message, or undefined when valid (npm package name rules, the subset we need). */
+function validateName(name) {
+	if (!name) return "project name is required";
+	if (!/^[a-z0-9][a-z0-9._-]*$/.test(name)) return "use lowercase letters, digits, ., _ and - (must start with a letter or digit)";
+	if (name.length > 214) return "name too long (npm limit is 214)";
+}
+//#endregion
+//#region src/answers.ts
+function defaultAnswers(name) {
+	return {
+		name,
+		db: { mode: "docker" },
+		storage: { mode: "minio" },
+		port: 8e3,
+		clientOrigins: "http://localhost:8001,http://localhost:8002"
+	};
+}
+/** my-lms → my_lms: the docker Postgres database name. */
+function dbName(name) {
+	return name.replace(/[^a-zA-Z0-9]+/g, "_").toLowerCase();
+}
+//#endregion
+//#region src/scaffold.ts
+/** templates/ sits at the package root: ../templates from src/ AND dist/. */
+const TEMPLATES = fileURLToPath(new URL("../templates/", import.meta.url));
+function render(content, vars) {
+	return content.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+		const v = vars[key];
+		if (v === void 0) throw new Error(`template variable {{${key}}} has no value`);
+		return v;
+	});
+}
+const POSTGRES_SERVICE = `  postgres:
+    image: postgres:17
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: {{DB_NAME}}
+    ports:
+      - "8005:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data`;
+const MINIO_SERVICE = `  minio:
+    image: minio/minio
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    ports:
+      - "8006:9000"
+      - "8007:9001"
+    volumes:
+      - miniodata:/data`;
+const MINIO_ENV = `
+STORAGE_ENDPOINT=localhost
+STORAGE_PORT=8006
+STORAGE_USE_SSL=false
+STORAGE_ACCESS_KEY=minioadmin
+STORAGE_SECRET_KEY=minioadmin
+STORAGE_REGION=us-east-1
+STORAGE_BUCKET={{DB_NAME}}
+`;
+function s3Env(s) {
+	return `
+STORAGE_ENDPOINT=${s.endPoint}
+STORAGE_PORT=${s.port}
+STORAGE_USE_SSL=${s.useSSL}
+STORAGE_ACCESS_KEY=${s.accessKey}
+STORAGE_SECRET_KEY=${s.secretKey}
+STORAGE_REGION=${s.region}
+STORAGE_BUCKET=${s.bucket}
+`;
+}
+/** Same keys as s3Env, blanked — s3 credentials are real secrets and must never land in .env.example. */
+const S3_ENV_EXAMPLE = `
+STORAGE_ENDPOINT=
+STORAGE_PORT=
+STORAGE_USE_SSL=
+STORAGE_ACCESS_KEY=
+STORAGE_SECRET_KEY=
+STORAGE_REGION=
+STORAGE_BUCKET=
+`;
+async function scaffold(answers, targetDir) {
+	try {
+		if ((await readdir(targetDir)).length > 0) throw new Error(`target directory ${targetDir} is not empty`);
+	} catch (err) {
+		if (err.code !== "ENOENT") throw err;
+	}
+	const written = [];
+	try {
+		const name = dbName(answers.name);
+		const databaseUrl = answers.db.mode === "docker" ? `postgres://postgres:postgres@localhost:8005/${name}` : answers.db.url;
+		const storageEnv = answers.storage.mode === "minio" ? render(MINIO_ENV, { DB_NAME: name }) : answers.storage.mode === "s3" ? s3Env(answers.storage) : "";
+		const vars = {
+			NAME: answers.name,
+			DB_NAME: name,
+			PORT: String(answers.port),
+			CLIENT_ORIGINS: answers.clientOrigins,
+			DATABASE_URL: databaseUrl,
+			BETTER_AUTH_SECRET: randomBytes(32).toString("base64"),
+			CREDENTIAL_STORE_KEY: randomBytes(32).toString("base64"),
+			STORAGE_ENV: storageEnv
+		};
+		await mkdir(join(targetDir, "src", "plugins"), { recursive: true });
+		const write = async (rel, content) => {
+			await writeFile(join(targetDir, rel), content);
+			written.push(rel);
+		};
+		const fromTemplate = async (tmpl, rel, extra) => write(rel, render(await readFile(join(TEMPLATES, tmpl), "utf8"), {
+			...vars,
+			...extra
+		}));
+		await fromTemplate("package.json.tmpl", "package.json");
+		await fromTemplate("README.md", "README.md");
+		await fromTemplate("env.tmpl", ".env");
+		await fromTemplate("env.tmpl", ".env.example", {
+			BETTER_AUTH_SECRET: "",
+			CREDENTIAL_STORE_KEY: "",
+			DATABASE_URL: answers.db.mode === "docker" ? databaseUrl : "",
+			...answers.storage.mode === "s3" ? { STORAGE_ENV: S3_ENV_EXAMPLE } : {}
+		});
+		await cp(join(TEMPLATES, "tsconfig.json"), join(targetDir, "tsconfig.json"));
+		await cp(join(TEMPLATES, "tsdown.config.ts"), join(targetDir, "tsdown.config.ts"));
+		await cp(join(TEMPLATES, "gitignore"), join(targetDir, ".gitignore"));
+		await cp(join(TEMPLATES, "src/main.ts"), join(targetDir, "src/main.ts"));
+		await cp(join(TEMPLATES, "src/config.ts"), join(targetDir, "src/config.ts"));
+		await cp(join(TEMPLATES, "src/plugins/README.md"), join(targetDir, "src/plugins/README.md"));
+		written.push("tsconfig.json", "tsdown.config.ts", ".gitignore", "src/main.ts", "src/config.ts", "src/plugins/README.md");
+		const services = [];
+		const volumes = [];
+		if (answers.db.mode === "docker") {
+			services.push(render(POSTGRES_SERVICE, { DB_NAME: name }));
+			volumes.push("  pgdata:");
+		}
+		if (answers.storage.mode === "minio") {
+			services.push(MINIO_SERVICE);
+			volumes.push("  miniodata:");
+		}
+		if (services.length > 0) await write("docker-compose.yml", `name: ${answers.name}\nservices:\n${services.join("\n")}\nvolumes:\n${volumes.join("\n")}\n`);
+		return written;
+	} catch (err) {
+		await rm(targetDir, {
+			recursive: true,
+			force: true
+		});
+		throw err;
+	}
+}
+//#endregion
+//#region src/index.ts
+const args = parseArgs(process.argv.slice(2));
+function bail(message = "Cancelled.") {
+	p.cancel(message);
+	process.exit(1);
+}
+/** Unwrap a clack result, exiting cleanly on ctrl-c. */
+function got(value) {
+	if (p.isCancel(value)) bail();
+	return value;
+}
+p.intro("create-headless-lms");
+/** Reject non-integer or out-of-range (1-65535) port input; undefined/empty passes through (Enter keeps the default). */
+function validatePort(v) {
+	if (!v) return;
+	if (!/^\d+$/.test(v)) return "Port must be a whole number.";
+	const n = Number(v);
+	if (n < 1 || n > 65535) return "Port must be between 1 and 65535.";
+}
+let name = args.name;
+if (!name) {
+	if (args.yes) bail("--yes needs a project name: create-headless-lms <name> --yes");
+	name = got(await p.text({
+		message: "Project name",
+		placeholder: "my-lms",
+		validate: (v) => validateName(v ?? "")
+	}));
+}
+const nameError = validateName(name);
+if (nameError) bail(nameError);
+let answers = defaultAnswers(name);
+if (!args.yes) {
+	const db = got(await p.select({
+		message: "Database",
+		options: [{
+			value: "docker",
+			label: "Postgres via docker-compose (recommended)"
+		}, {
+			value: "url",
+			label: "I have a connection string"
+		}]
+	})) === "url" ? {
+		mode: "url",
+		url: got(await p.text({
+			message: "DATABASE_URL",
+			placeholder: "postgres://user:pass@host:5432/db"
+		}))
+	} : { mode: "docker" };
+	const storageMode = got(await p.select({
+		message: "File storage",
+		options: [
+			{
+				value: "minio",
+				label: "Bundled MinIO via docker-compose (recommended)"
+			},
+			{
+				value: "s3",
+				label: "Existing S3-compatible storage"
+			},
+			{
+				value: "skip",
+				label: "Skip for now"
+			}
+		]
+	}));
+	let storage = { mode: "minio" };
+	if (storageMode === "skip") storage = { mode: "skip" };
+	if (storageMode === "s3") storage = {
+		mode: "s3",
+		endPoint: got(await p.text({
+			message: "Endpoint host",
+			placeholder: "s3.amazonaws.com"
+		})),
+		port: Number(got(await p.text({
+			message: "Port",
+			initialValue: "443",
+			validate: validatePort
+		}))),
+		useSSL: got(await p.confirm({
+			message: "Use SSL?",
+			initialValue: true
+		})),
+		accessKey: got(await p.text({ message: "Access key" })),
+		secretKey: got(await p.text({ message: "Secret key" })),
+		region: got(await p.text({
+			message: "Region",
+			initialValue: "us-east-1"
+		})),
+		bucket: got(await p.text({
+			message: "Bucket",
+			initialValue: name
+		}))
+	};
+	const port = Number(got(await p.text({
+		message: "API port",
+		initialValue: "8000",
+		validate: validatePort
+	})));
+	const clientOrigins = got(await p.text({
+		message: "Client origins (comma-separated, for CORS + auth)",
+		initialValue: "http://localhost:8001,http://localhost:8002"
+	}));
+	answers = {
+		name,
+		db,
+		storage,
+		port,
+		clientOrigins
+	};
+}
+const targetDir = resolve(process.cwd(), name);
+const s = p.spinner();
+s.start(`Scaffolding ${name}`);
+try {
+	await scaffold(answers, targetDir);
+	s.stop(`Created ${name}/`);
+} catch (err) {
+	s.stop("Scaffold failed");
+	bail(err instanceof Error ? err.message : String(err));
+}
+const run = (cmd, argv) => spawnSync(cmd, argv, {
+	cwd: targetDir,
+	stdio: "inherit"
+});
+if (!args.yes && got(await p.confirm({
+	message: "Run pnpm install now?",
+	initialValue: true
+}))) {
+	run("pnpm", ["install"]);
+	if (got(await p.confirm({
+		message: "Run migrations now? (database must be reachable)",
+		initialValue: false
+	}))) run("pnpm", ["migrate"]);
+}
+p.note([
+	`cd ${name}`,
+	...answers.db.mode === "docker" || answers.storage.mode === "minio" ? ["docker compose up -d"] : [],
+	"pnpm install        # if you skipped it",
+	"pnpm migrate",
+	"pnpm dev"
+].join("\n"), "Next steps");
+p.outro(`API will listen on http://localhost:${answers.port} — docs at /docs`);
+//#endregion
+export {};
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/args.ts","../src/answers.ts","../src/scaffold.ts","../src/index.ts"],"sourcesContent":["export interface CliArgs {\n  name: string | undefined;\n  yes: boolean;\n}\n\nexport function parseArgs(argv: string[]): CliArgs {\n  const yes = argv.includes(\"--yes\") || argv.includes(\"-y\");\n  const name = argv.find((a) => !a.startsWith(\"-\"));\n  return { name, yes };\n}\n\n/** Returns an error message, or undefined when valid (npm package name rules, the subset we need). */\nexport function validateName(name: string): string | undefined {\n  if (!name) {\n    return \"project name is required\";\n  }\n  if (!/^[a-z0-9][a-z0-9._-]*$/.test(name)) {\n    return \"use lowercase letters, digits, ., _ and - (must start with a letter or digit)\";\n  }\n  if (name.length > 214) {\n    return \"name too long (npm limit is 214)\";\n  }\n  return undefined;\n}\n","export type DbAnswer = { mode: \"docker\" } | { mode: \"url\"; url: string };\nexport type StorageAnswer =\n  | { mode: \"minio\" }\n  | {\n      mode: \"s3\";\n      endPoint: string;\n      port: number;\n      useSSL: boolean;\n      accessKey: string;\n      secretKey: string;\n      region: string;\n      bucket: string;\n    }\n  | { mode: \"skip\" };\n\nexport interface Answers {\n  name: string;\n  db: DbAnswer;\n  storage: StorageAnswer;\n  port: number;\n  clientOrigins: string;\n}\n\nexport function defaultAnswers(name: string): Answers {\n  return {\n    name,\n    db: { mode: \"docker\" },\n    storage: { mode: \"minio\" },\n    port: 8000,\n    clientOrigins: \"http://localhost:8001,http://localhost:8002\",\n  };\n}\n\n/** my-lms → my_lms: the docker Postgres database name. */\nexport function dbName(name: string): string {\n  return name.replace(/[^a-zA-Z0-9]+/g, \"_\").toLowerCase();\n}\n","// Renders the bundled templates into a new installation directory.\n// Pure with respect to prompts: everything variable comes in via Answers.\nimport { cp, mkdir, readFile, readdir, rm, writeFile } from \"node:fs/promises\";\nimport { randomBytes } from \"node:crypto\";\nimport { fileURLToPath } from \"node:url\";\nimport { join } from \"node:path\";\nimport { type Answers, dbName } from \"./answers.js\";\n\n/** templates/ sits at the package root: ../templates from src/ AND dist/. */\nconst TEMPLATES = fileURLToPath(new URL(\"../templates/\", import.meta.url));\n\nfunction render(content: string, vars: Record<string, string>): string {\n  return content.replace(/\\{\\{(\\w+)\\}\\}/g, (_, key: string) => {\n    const v = vars[key];\n    if (v === undefined) {\n      throw new Error(`template variable {{${key}}} has no value`);\n    }\n    return v;\n  });\n}\n\nconst POSTGRES_SERVICE = `  postgres:\n    image: postgres:17\n    environment:\n      POSTGRES_USER: postgres\n      POSTGRES_PASSWORD: postgres\n      POSTGRES_DB: {{DB_NAME}}\n    ports:\n      - \"8005:5432\"\n    volumes:\n      - pgdata:/var/lib/postgresql/data`;\n\nconst MINIO_SERVICE = `  minio:\n    image: minio/minio\n    command: server /data --console-address \":9001\"\n    environment:\n      MINIO_ROOT_USER: minioadmin\n      MINIO_ROOT_PASSWORD: minioadmin\n    ports:\n      - \"8006:9000\"\n      - \"8007:9001\"\n    volumes:\n      - miniodata:/data`;\n\nconst MINIO_ENV = `\nSTORAGE_ENDPOINT=localhost\nSTORAGE_PORT=8006\nSTORAGE_USE_SSL=false\nSTORAGE_ACCESS_KEY=minioadmin\nSTORAGE_SECRET_KEY=minioadmin\nSTORAGE_REGION=us-east-1\nSTORAGE_BUCKET={{DB_NAME}}\n`;\n\nfunction s3Env(s: Extract<Answers[\"storage\"], { mode: \"s3\" }>): string {\n  return `\nSTORAGE_ENDPOINT=${s.endPoint}\nSTORAGE_PORT=${s.port}\nSTORAGE_USE_SSL=${s.useSSL}\nSTORAGE_ACCESS_KEY=${s.accessKey}\nSTORAGE_SECRET_KEY=${s.secretKey}\nSTORAGE_REGION=${s.region}\nSTORAGE_BUCKET=${s.bucket}\n`;\n}\n\n/** Same keys as s3Env, blanked — s3 credentials are real secrets and must never land in .env.example. */\nconst S3_ENV_EXAMPLE = `\nSTORAGE_ENDPOINT=\nSTORAGE_PORT=\nSTORAGE_USE_SSL=\nSTORAGE_ACCESS_KEY=\nSTORAGE_SECRET_KEY=\nSTORAGE_REGION=\nSTORAGE_BUCKET=\n`;\n\nexport async function scaffold(answers: Answers, targetDir: string): Promise<string[]> {\n  try {\n    const existing = await readdir(targetDir);\n    if (existing.length > 0) {\n      throw new Error(`target directory ${targetDir} is not empty`);\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code !== \"ENOENT\") {\n      throw err;\n    }\n  }\n\n  const written: string[] = [];\n  try {\n    const name = dbName(answers.name);\n    const databaseUrl =\n      answers.db.mode === \"docker\"\n        ? `postgres://postgres:postgres@localhost:8005/${name}`\n        : answers.db.url;\n    const storageEnv =\n      answers.storage.mode === \"minio\"\n        ? render(MINIO_ENV, { DB_NAME: name })\n        : answers.storage.mode === \"s3\"\n          ? s3Env(answers.storage)\n          : \"\";\n\n    const vars: Record<string, string> = {\n      NAME: answers.name,\n      DB_NAME: name,\n      PORT: String(answers.port),\n      CLIENT_ORIGINS: answers.clientOrigins,\n      DATABASE_URL: databaseUrl,\n      BETTER_AUTH_SECRET: randomBytes(32).toString(\"base64\"),\n      CREDENTIAL_STORE_KEY: randomBytes(32).toString(\"base64\"),\n      STORAGE_ENV: storageEnv,\n    };\n\n    await mkdir(join(targetDir, \"src\", \"plugins\"), { recursive: true });\n\n    const write = async (rel: string, content: string) => {\n      await writeFile(join(targetDir, rel), content);\n      written.push(rel);\n    };\n    const fromTemplate = async (tmpl: string, rel: string, extra?: Record<string, string>) =>\n      write(rel, render(await readFile(join(TEMPLATES, tmpl), \"utf8\"), { ...vars, ...extra }));\n\n    await fromTemplate(\"package.json.tmpl\", \"package.json\");\n    await fromTemplate(\"README.md\", \"README.md\");\n    await fromTemplate(\"env.tmpl\", \".env\");\n    await fromTemplate(\"env.tmpl\", \".env.example\", {\n      BETTER_AUTH_SECRET: \"\",\n      CREDENTIAL_STORE_KEY: \"\",\n      DATABASE_URL: answers.db.mode === \"docker\" ? databaseUrl : \"\",\n      ...(answers.storage.mode === \"s3\" ? { STORAGE_ENV: S3_ENV_EXAMPLE } : {}),\n    });\n    await cp(join(TEMPLATES, \"tsconfig.json\"), join(targetDir, \"tsconfig.json\"));\n    await cp(join(TEMPLATES, \"tsdown.config.ts\"), join(targetDir, \"tsdown.config.ts\"));\n    await cp(join(TEMPLATES, \"gitignore\"), join(targetDir, \".gitignore\"));\n    await cp(join(TEMPLATES, \"src/main.ts\"), join(targetDir, \"src/main.ts\"));\n    await cp(join(TEMPLATES, \"src/config.ts\"), join(targetDir, \"src/config.ts\"));\n    await cp(join(TEMPLATES, \"src/plugins/README.md\"), join(targetDir, \"src/plugins/README.md\"));\n    written.push(\n      \"tsconfig.json\",\n      \"tsdown.config.ts\",\n      \".gitignore\",\n      \"src/main.ts\",\n      \"src/config.ts\",\n      \"src/plugins/README.md\",\n    );\n\n    const services: string[] = [];\n    const volumes: string[] = [];\n    if (answers.db.mode === \"docker\") {\n      services.push(render(POSTGRES_SERVICE, { DB_NAME: name }));\n      volumes.push(\"  pgdata:\");\n    }\n    if (answers.storage.mode === \"minio\") {\n      services.push(MINIO_SERVICE);\n      volumes.push(\"  miniodata:\");\n    }\n    if (services.length > 0) {\n      const compose = `name: ${answers.name}\\nservices:\\n${services.join(\"\\n\")}\\nvolumes:\\n${volumes.join(\"\\n\")}\\n`;\n      await write(\"docker-compose.yml\", compose);\n    }\n\n    return written;\n  } catch (err) {\n    // Leave no half-written project behind.\n    await rm(targetDir, { recursive: true, force: true });\n    throw err;\n  }\n}\n","#!/usr/bin/env node\n// npm create headless-lms → this. Walks the prompts (or --yes for defaults),\n// scaffolds the installation, then offers install + migrate.\nimport { spawnSync } from \"node:child_process\";\nimport { resolve } from \"node:path\";\nimport * as p from \"@clack/prompts\";\nimport { parseArgs, validateName } from \"./args.js\";\nimport { defaultAnswers, type Answers, type StorageAnswer } from \"./answers.js\";\nimport { scaffold } from \"./scaffold.js\";\n\nconst args = parseArgs(process.argv.slice(2));\n\nfunction bail(message = \"Cancelled.\"): never {\n  p.cancel(message);\n  process.exit(1);\n}\n/** Unwrap a clack result, exiting cleanly on ctrl-c. */\nfunction got<T>(value: T | symbol): T {\n  if (p.isCancel(value)) {\n    bail();\n  }\n  return value as T;\n}\n\np.intro(\"create-headless-lms\");\n\n/** Reject non-integer or out-of-range (1-65535) port input; undefined/empty passes through (Enter keeps the default). */\nfunction validatePort(v: string | undefined): string | undefined {\n  if (!v) {\n    return undefined;\n  }\n  if (!/^\\d+$/.test(v)) {\n    return \"Port must be a whole number.\";\n  }\n  const n = Number(v);\n  if (n < 1 || n > 65535) {\n    return \"Port must be between 1 and 65535.\";\n  }\n  return undefined;\n}\n\nlet name = args.name;\nif (!name) {\n  if (args.yes) {\n    bail(\"--yes needs a project name: create-headless-lms <name> --yes\");\n  }\n  name = got(\n    await p.text({\n      message: \"Project name\",\n      placeholder: \"my-lms\",\n      validate: (v) => validateName(v ?? \"\"),\n    }),\n  );\n}\nconst nameError = validateName(name);\nif (nameError) {\n  bail(nameError);\n}\n\nlet answers: Answers = defaultAnswers(name);\n\nif (!args.yes) {\n  const dbMode = got(\n    await p.select({\n      message: \"Database\",\n      options: [\n        { value: \"docker\", label: \"Postgres via docker-compose (recommended)\" },\n        { value: \"url\", label: \"I have a connection string\" },\n      ],\n    }),\n  );\n  const db =\n    dbMode === \"url\"\n      ? {\n          mode: \"url\" as const,\n          url: got(\n            await p.text({\n              message: \"DATABASE_URL\",\n              placeholder: \"postgres://user:pass@host:5432/db\",\n            }),\n          ),\n        }\n      : { mode: \"docker\" as const };\n\n  const storageMode = got(\n    await p.select({\n      message: \"File storage\",\n      options: [\n        { value: \"minio\", label: \"Bundled MinIO via docker-compose (recommended)\" },\n        { value: \"s3\", label: \"Existing S3-compatible storage\" },\n        { value: \"skip\", label: \"Skip for now\" },\n      ],\n    }),\n  );\n  let storage: StorageAnswer = { mode: \"minio\" };\n  if (storageMode === \"skip\") {\n    storage = { mode: \"skip\" };\n  }\n  if (storageMode === \"s3\") {\n    storage = {\n      mode: \"s3\",\n      endPoint: got(await p.text({ message: \"Endpoint host\", placeholder: \"s3.amazonaws.com\" })),\n      port: Number(\n        got(await p.text({ message: \"Port\", initialValue: \"443\", validate: validatePort })),\n      ),\n      useSSL: got(await p.confirm({ message: \"Use SSL?\", initialValue: true })),\n      accessKey: got(await p.text({ message: \"Access key\" })),\n      secretKey: got(await p.text({ message: \"Secret key\" })),\n      region: got(await p.text({ message: \"Region\", initialValue: \"us-east-1\" })),\n      bucket: got(await p.text({ message: \"Bucket\", initialValue: name })),\n    };\n  }\n\n  const port = Number(\n    got(await p.text({ message: \"API port\", initialValue: \"8000\", validate: validatePort })),\n  );\n  const clientOrigins = got(\n    await p.text({\n      message: \"Client origins (comma-separated, for CORS + auth)\",\n      initialValue: \"http://localhost:8001,http://localhost:8002\",\n    }),\n  );\n\n  answers = { name, db, storage, port, clientOrigins };\n}\n\nconst targetDir = resolve(process.cwd(), name);\nconst s = p.spinner();\ns.start(`Scaffolding ${name}`);\ntry {\n  await scaffold(answers, targetDir);\n  s.stop(`Created ${name}/`);\n} catch (err) {\n  s.stop(\"Scaffold failed\");\n  bail(err instanceof Error ? err.message : String(err));\n}\n\nconst run = (cmd: string, argv: string[]) =>\n  spawnSync(cmd, argv, { cwd: targetDir, stdio: \"inherit\" });\n\nif (!args.yes && got(await p.confirm({ message: \"Run pnpm install now?\", initialValue: true }))) {\n  run(\"pnpm\", [\"install\"]);\n  if (\n    got(\n      await p.confirm({\n        message: \"Run migrations now? (database must be reachable)\",\n        initialValue: false,\n      }),\n    )\n  ) {\n    run(\"pnpm\", [\"migrate\"]);\n  }\n}\n\np.note(\n  [\n    `cd ${name}`,\n    ...(answers.db.mode === \"docker\" || answers.storage.mode === \"minio\"\n      ? [\"docker compose up -d\"]\n      : []),\n    \"pnpm install        # if you skipped it\",\n    \"pnpm migrate\",\n    \"pnpm dev\",\n  ].join(\"\\n\"),\n  \"Next steps\",\n);\np.outro(`API will listen on http://localhost:${answers.port} — docs at /docs`);\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "create-headless-lms",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "create-headless-lms": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.22.9",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "description": "Scaffold a new headless LMS project",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdwt/headless-lms.git",
+    "directory": "packages/create-headless-lms"
+  },
+  "homepage": "https://github.com/mdwt/headless-lms#readme",
+  "bugs": {
+    "url": "https://github.com/mdwt/headless-lms/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/README.md

@@ -0,0 +1,17 @@
+# {{NAME}}
+
+A Headless LMS installation.
+
+## Run
+
+    docker compose up -d      # if you chose the bundled Postgres/MinIO
+    pnpm install
+    pnpm migrate
+    pnpm dev                  # API on http://localhost:{{PORT}}, docs at /docs
+
+## Layout
+
+- `src/main.ts` — entry point: config → container → server
+- `src/config.ts` — reads .env into the ServerConfig
+- `src/plugins/` — integrations (see its README)
+- `.env` — secrets and runtime config (never commit)

package/templates/env.tmpl

@@ -0,0 +1,11 @@
+PORT={{PORT}}
+BETTER_AUTH_URL=http://localhost:{{PORT}}
+CLIENT_ORIGIN={{CLIENT_ORIGINS}}
+STUDENT_PORTAL_URL=http://localhost:8002
+ADMIN_APP_URL=http://localhost:8001
+
+DATABASE_URL={{DATABASE_URL}}
+
+BETTER_AUTH_SECRET={{BETTER_AUTH_SECRET}}
+CREDENTIAL_STORE_KEY={{CREDENTIAL_STORE_KEY}}
+{{STORAGE_ENV}}

package/templates/gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.env

package/templates/package.json.tmpl

@@ -0,0 +1,26 @@
+{
+  "name": "{{NAME}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/main.js",
+  "scripts": {
+    "dev": "tsx watch --env-file=.env src/main.ts",
+    "build": "tsdown",
+    "start": "node --env-file=.env dist/main.js",
+    "migrate": "headless-lms migrate",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@headless-lms/adapter-storage-minio": "^0.0.0",
+    "@headless-lms/cli": "^0.0.0",
+    "@headless-lms/core": "^0.0.0",
+    "@headless-lms/server": "^0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.22.9",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

package/templates/src/config.ts

@@ -0,0 +1,65 @@
+// Reads all runtime configuration from the environment and builds the
+// ServerConfig that @headless-lms/server consumes. The only file that
+// touches process.env.
+import type { ServerConfig, ContainerConfig } from "@headless-lms/server";
+import type { MinioStorageConfig } from "@headless-lms/adapter-storage-minio";
+
+/** STORAGE_ENDPOINT unset → no storage adapter; asset operations fail loudly. */
+export function loadStorageConfig(): MinioStorageConfig | undefined {
+  const endPoint = process.env.STORAGE_ENDPOINT;
+  if (!endPoint) {
+    return undefined;
+  }
+  return {
+    endPoint,
+    port: Number(process.env.STORAGE_PORT ?? 9000),
+    useSSL: (process.env.STORAGE_USE_SSL ?? "false") === "true",
+    accessKey: process.env.STORAGE_ACCESS_KEY ?? "",
+    secretKey: process.env.STORAGE_SECRET_KEY ?? "",
+    region: process.env.STORAGE_REGION ?? "us-east-1",
+    bucket: process.env.STORAGE_BUCKET ?? "headless-lms",
+    uploadExpirySeconds: Number(process.env.STORAGE_UPLOAD_EXPIRY ?? 300),
+    downloadExpirySeconds: Number(process.env.STORAGE_DOWNLOAD_EXPIRY ?? 300),
+  };
+}
+
+/** Browser app origins from CLIENT_ORIGIN (comma-separated). */
+export function parseClientOrigins(): string[] {
+  return (process.env.CLIENT_ORIGIN ?? "http://localhost:8001,http://localhost:8002")
+    .split(",")
+    .map((o) => o.trim())
+    .filter(Boolean);
+}
+
+function loadContainerConfig(): ContainerConfig {
+  const clientOrigins = parseClientOrigins();
+  const apiOrigin = process.env.BETTER_AUTH_URL ?? "http://localhost:8000";
+  const trustedOrigins = [...new Set([...clientOrigins, apiOrigin])];
+  return {
+    databaseUrl: process.env.DATABASE_URL ?? "",
+    authBaseURL: apiOrigin,
+    authSecret: process.env.BETTER_AUTH_SECRET ?? "",
+    trustedOrigins,
+    credentialStoreKey: process.env.CREDENTIAL_STORE_KEY ?? "",
+    cookieDomain: process.env.AUTH_COOKIE_DOMAIN || undefined,
+    secureCookies: process.env.NODE_ENV === "production",
+    studentPortalUrl: process.env.STUDENT_PORTAL_URL ?? "http://localhost:8002",
+    adminAppUrl: process.env.ADMIN_APP_URL ?? "http://localhost:8001",
+  };
+}
+
+export function loadServerConfig(): ServerConfig {
+  const container = loadContainerConfig();
+  return {
+    port: Number(process.env.PORT ?? 8000),
+    host: process.env.HOST ?? "0.0.0.0",
+    // BETTER_AUTH_URL is the API's own origin; reuse it so the public URL
+    // can never drift from what better-auth is configured with.
+    publicUrl: container.authBaseURL,
+    clientOrigins: parseClientOrigins(),
+    // Separate from STORAGE_DOWNLOAD_EXPIRY: raising the general storage
+    // default must never silently extend entitled/paywalled link lifetimes.
+    deliveryExpirySeconds: Number(process.env.DELIVERY_URL_EXPIRY ?? 300),
+    container,
+  };
+}

package/templates/src/main.ts

@@ -0,0 +1,22 @@
+// Process entry point: env → config → container → server → listen.
+import { fileURLToPath } from "node:url";
+import { createContainer, buildServer } from "@headless-lms/server";
+import { MinioStorageAdapter } from "@headless-lms/adapter-storage-minio";
+import { loadServerConfig, loadStorageConfig } from "./config.js";
+
+const config = loadServerConfig();
+const storageConfig = loadStorageConfig();
+const container = await createContainer(config, {
+  // One folder per integration (directory name = integration id). Compiled
+  // to dist/plugins/ by the standard build, so this resolves in dev and prod.
+  pluginsDir: fileURLToPath(new URL("./plugins/", import.meta.url)),
+  adapters: {
+    storage: storageConfig && new MinioStorageAdapter(storageConfig),
+  },
+});
+const app = await buildServer(config, container);
+
+app.listen({ port: config.port, host: config.host }).catch((err) => {
+  app.log.error(err);
+  process.exit(1);
+});

package/templates/src/plugins/README.md

@@ -0,0 +1,15 @@
+# plugins/
+
+One folder per integration; the **directory name is the integration id**. Each
+folder's `index.ts` default-exports an object satisfying the `Integration`
+contract from `@headless-lms/core/types`. Loaded once at startup — a malformed
+plugin fails the boot, not a request.
+
+Two ways to add one:
+
+1. **Published integration** — install it and re-export:
+   `pnpm add @headless-lms/plugin-slack`, then `plugins/slack/index.ts`:
+   `export { default } from "@headless-lms/plugin-slack";`
+2. **Custom integration** — write the folder directly, depending only on
+   `@headless-lms/core/types` (+ `@headless-lms/core/integrations` for the zod
+   helpers).

package/templates/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/tsdown.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  // Transpile-only: mirror the src/ tree into dist/ file-for-file rather than
+  // bundling into one file. Keeps the hexagonal layout intact and preserves
+  // dist/main.js as the process entry (main field + start script).
+  unbundle: true,
+  entry: ["src/**/*.ts", "!src/**/*.test.ts"],
+  outDir: "dist",
+  format: ["esm"],
+  fixedExtension: false,
+  target: "node22",
+  platform: "node",
+  sourcemap: true,
+  clean: true,
+  // Type-checking is the job of `pnpm typecheck` (tsc --noEmit); tsdown only emits.
+  dts: false,
+});