@headless-lms/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mdwt
+
+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/README.md

@@ -0,0 +1,27 @@
+# @headless-lms/cli
+
+The `headless-lms` bin: a thin CLI over the operational functions
+`@headless-lms/server` exports. Reads `.env` from the cwd if present.
+
+```bash
+headless-lms migrate   # apply the Drizzle migrations bundled in @headless-lms/adapter-db
+headless-lms --help
+```
+
+Installations get it as a dependency (the `create-headless-lms` scaffold wires
+`pnpm migrate` to it). In this repo, `apps/api` runs the same entry via tsx:
+`pnpm --filter @headless-lms/api db:migrate`.
+
+## Structure
+
+```
+src/
+  index.ts       bin entry: .env, dispatch, exit code — no logic
+  main.ts        dispatcher: usage/help/version, error → exit 1 (testable, no process.exit)
+  command.ts     the Command interface
+  commands/      one module per command + the explicit registry (index.ts)
+```
+
+**Adding a command:** create `src/commands/<name>.ts` exporting a `Command`
+(`{ name, description, run(args) }`), register it in `src/commands/index.ts`.
+Throw from `run` to fail — the dispatcher prints the message and exits 1.

package/dist/index.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { runMigrations } from "@headless-lms/server";
+//#region package.json
+var version = "0.1.0";
+//#endregion
+//#region src/commands/index.ts
+const commands = [{
+	name: "migrate",
+	description: "Apply the bundled Drizzle migrations to DATABASE_URL",
+	async run() {
+		await runMigrations(process.env.DATABASE_URL ?? "");
+		console.log("Migrations applied.");
+	}
+}];
+//#endregion
+//#region src/main.ts
+function usage() {
+	const width = Math.max(...commands.map((c) => c.name.length));
+	return [
+		"Usage: headless-lms <command>",
+		"",
+		"Commands:",
+		...commands.map((c) => `  ${c.name.padEnd(width)}  ${c.description}`),
+		"",
+		"Options:",
+		"  -h, --help     Show this help",
+		"  -v, --version  Print the CLI version"
+	].join("\n");
+}
+async function main(argv) {
+	const [name, ...args] = argv;
+	if (!name) {
+		console.error(usage());
+		return 1;
+	}
+	if (name === "help" || name === "--help" || name === "-h") {
+		console.log(usage());
+		return 0;
+	}
+	if (name === "--version" || name === "-v") {
+		console.log(version);
+		return 0;
+	}
+	const command = commands.find((c) => c.name === name);
+	if (!command) {
+		console.error(`Unknown command: ${name}\n\n${usage()}`);
+		return 1;
+	}
+	try {
+		await command.run(args);
+		return 0;
+	} catch (err) {
+		console.error(err instanceof Error ? err.message : String(err));
+		return 1;
+	}
+}
+//#endregion
+//#region src/index.ts
+try {
+	process.loadEnvFile();
+} catch {}
+process.exitCode = await main(process.argv.slice(2));
+//#endregion
+export {};
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["pkg.version"],"sources":["../package.json","../src/commands/migrate.ts","../src/commands/index.ts","../src/main.ts","../src/index.ts"],"sourcesContent":["","import { runMigrations } from \"@headless-lms/server\";\nimport type { Command } from \"../command.js\";\n\nexport const migrate: Command = {\n  name: \"migrate\",\n  description: \"Apply the bundled Drizzle migrations to DATABASE_URL\",\n  async run() {\n    await runMigrations(process.env.DATABASE_URL ?? \"\");\n    console.log(\"Migrations applied.\");\n  },\n};\n","import type { Command } from \"../command.js\";\nimport { migrate } from \"./migrate.js\";\n\nexport const commands: readonly Command[] = [migrate];\n","// Dispatcher, separated from the bin entry so it is testable: takes argv,\n// returns the exit code, never calls process.exit itself.\nimport pkg from \"../package.json\" with { type: \"json\" };\nimport { commands } from \"./commands/index.js\";\n\nfunction usage(): string {\n  const width = Math.max(...commands.map((c) => c.name.length));\n  return [\n    \"Usage: headless-lms <command>\",\n    \"\",\n    \"Commands:\",\n    ...commands.map((c) => `  ${c.name.padEnd(width)}  ${c.description}`),\n    \"\",\n    \"Options:\",\n    \"  -h, --help     Show this help\",\n    \"  -v, --version  Print the CLI version\",\n  ].join(\"\\n\");\n}\n\nexport async function main(argv: readonly string[]): Promise<number> {\n  const [name, ...args] = argv;\n\n  if (!name) {\n    console.error(usage());\n    return 1;\n  }\n  if (name === \"help\" || name === \"--help\" || name === \"-h\") {\n    console.log(usage());\n    return 0;\n  }\n  if (name === \"--version\" || name === \"-v\") {\n    console.log(pkg.version);\n    return 0;\n  }\n\n  const command = commands.find((c) => c.name === name);\n  if (!command) {\n    console.error(`Unknown command: ${name}\\n\\n${usage()}`);\n    return 1;\n  }\n\n  try {\n    await command.run(args);\n    return 0;\n  } catch (err) {\n    console.error(err instanceof Error ? err.message : String(err));\n    return 1;\n  }\n}\n","#!/usr/bin/env node\n// The bin entry: env, dispatch, exit code. All logic lives in main.ts.\n// Loads ./.env from the cwd if present (Node 22 native), so installations\n// don't need --env-file gymnastics.\nimport { main } from \"./main.js\";\n\ntry {\n  process.loadEnvFile();\n} catch {\n  // no .env in cwd — fine, env may come from the environment itself\n}\n\nprocess.exitCode = await main(process.argv.slice(2));\n"],"mappings":";;;;;;AEGA,MAAa,WAA+B,CAAC;CDC3C,MAAM;CACN,aAAa;CACb,MAAM,MAAM;EACV,MAAM,cAAc,QAAQ,IAAI,gBAAgB,EAAE;EAClD,QAAQ,IAAI,qBAAqB;CACnC;ACN2C,CAAO;;;ACEpD,SAAS,QAAgB;CACvB,MAAM,QAAQ,KAAK,IAAI,GAAG,SAAS,KAAK,MAAM,EAAE,KAAK,MAAM,CAAC;CAC5D,OAAO;EACL;EACA;EACA;EACA,GAAG,SAAS,KAAK,MAAM,KAAK,EAAE,KAAK,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa;EACpE;EACA;EACA;EACA;CACF,CAAC,CAAC,KAAK,IAAI;AACb;AAEA,eAAsB,KAAK,MAA0C;CACnE,MAAM,CAAC,MAAM,GAAG,QAAQ;CAExB,IAAI,CAAC,MAAM;EACT,QAAQ,MAAM,MAAM,CAAC;EACrB,OAAO;CACT;CACA,IAAI,SAAS,UAAU,SAAS,YAAY,SAAS,MAAM;EACzD,QAAQ,IAAI,MAAM,CAAC;EACnB,OAAO;CACT;CACA,IAAI,SAAS,eAAe,SAAS,MAAM;EACzC,QAAQ,IAAIA,OAAW;EACvB,OAAO;CACT;CAEA,MAAM,UAAU,SAAS,MAAM,MAAM,EAAE,SAAS,IAAI;CACpD,IAAI,CAAC,SAAS;EACZ,QAAQ,MAAM,oBAAoB,KAAK,MAAM,MAAM,GAAG;EACtD,OAAO;CACT;CAEA,IAAI;EACF,MAAM,QAAQ,IAAI,IAAI;EACtB,OAAO;CACT,SAAS,KAAK;EACZ,QAAQ,MAAM,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;EAC9D,OAAO;CACT;AACF;;;AC1CA,IAAI;CACF,QAAQ,YAAY;AACtB,QAAQ,CAER;AAEA,QAAQ,WAAW,MAAM,KAAK,QAAQ,KAAK,MAAM,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@headless-lms/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "headless-lms": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@headless-lms/server": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.22.9",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "description": "CLI for running and managing a headless LMS instance",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdwt/headless-lms.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/mdwt/headless-lms#readme",
+  "bugs": {
+    "url": "https://github.com/mdwt/headless-lms/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}