create-softeneers-app 0.1.0 → 0.2.1

package/templates/express-api/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "express-api",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Express + TypeScript REST API generated by create-softeneers-app.",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "db:migrate": "tsx src/scripts/migrate.ts",
+    "db:seed": "tsx src/scripts/seed.ts",
+    "db:reset": "tsx src/scripts/migrate.ts --reset && tsx src/scripts/seed.ts",
+    "test": "node --import tsx --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@softeneers/auth": "^0.1.0",
+    "@softeneers/db": "^0.1.0",
+    "@softeneers/env": "^0.1.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^5.0.0",
+    "mysql2": "^3.11.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/express-api/softeneers.template.json

@@ -0,0 +1,17 @@
+{
+  "toggles": { "db": false, "auth": false, "docker": false },
+  "fragments": {
+    "db": {
+      "removePaths": ["src/db.ts", "src/scripts", "docker-compose.yml"],
+      "removeDeps": ["@softeneers/db", "mysql2"],
+      "removeScripts": ["db:migrate", "db:seed", "db:reset"]
+    },
+    "auth": {
+      "removePaths": ["src/auth"],
+      "removeDeps": ["@softeneers/auth"]
+    },
+    "docker": {
+      "removePaths": ["docker-compose.yml"]
+    }
+  }
+}

package/templates/express-api/src/auth/auth.ts

@@ -0,0 +1,11 @@
+import { createAuth } from "@softeneers/auth";
+
+import { env } from "../env.js";
+
+// Email + password authentication via better-auth. With no `database` configured
+// better-auth uses an in-memory store (fine for local dev); point it at your DB
+// for persistence. Routes are mounted at /api/auth/* in src/index.ts.
+export const auth = createAuth({
+  secret: env.AUTH_SECRET,
+  baseURL: env.AUTH_BASE_URL,
+});

package/templates/express-api/src/cars/demo.ts

@@ -0,0 +1,10 @@
+import type { NewCar } from "./types.js";
+
+// Demo garage inventory seeded on first run so `npm run dev` shows a working
+// CRUD demo immediately — into MySQL when a database is reachable, otherwise
+// into the in-memory store.
+export const DEMO_CARS: NewCar[] = [
+  { brand: "Toyota", model: "Corolla", year: 2021 },
+  { brand: "Tesla", model: "Model 3", year: 2023 },
+  { brand: "Ford", model: "Mustang", year: 1969 },
+];

package/templates/express-api/src/cars/routes.ts

@@ -0,0 +1,58 @@
+import { Router } from "express";
+
+import { carStore } from "./store.js";
+import { parseNewCar, ValidationError } from "./validate.js";
+
+export const carRouter = Router();
+
+carRouter.get("/", async (_req, res) => {
+  res.json(await carStore.list());
+});
+
+carRouter.get("/:id", async (req, res) => {
+  const car = await carStore.get(Number(req.params.id));
+  if (!car) {
+    res.status(404).json({ message: "Car not found." });
+    return;
+  }
+  res.json(car);
+});
+
+carRouter.post("/", async (req, res) => {
+  try {
+    const car = await carStore.create(parseNewCar(req.body));
+    res.status(201).json(car);
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      res.status(400).json({ message: error.message });
+      return;
+    }
+    throw error;
+  }
+});
+
+carRouter.put("/:id", async (req, res) => {
+  try {
+    const car = await carStore.update(Number(req.params.id), parseNewCar(req.body));
+    if (!car) {
+      res.status(404).json({ message: "Car not found." });
+      return;
+    }
+    res.json(car);
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      res.status(400).json({ message: error.message });
+      return;
+    }
+    throw error;
+  }
+});
+
+carRouter.delete("/:id", async (req, res) => {
+  const removed = await carStore.remove(Number(req.params.id));
+  if (!removed) {
+    res.status(404).json({ message: "Car not found." });
+    return;
+  }
+  res.status(204).end();
+});

package/templates/express-api/src/cars/store.ts

@@ -0,0 +1,150 @@
+import { DEMO_CARS } from "./demo.js";
+import type { Car, NewCar } from "./types.js";
+
+// The data layer behind the CRUD routes. With the `db` toggle on it persists to
+// MySQL (Sequelize via @softeneers/db) and **falls back to an in-memory store if
+// the database is unreachable**, so `npm run dev` always yields a working,
+// pre-seeded demo. With `db` off it is always in-memory.
+export interface CarStore {
+  list(): Promise<Car[]>;
+  get(id: number): Promise<Car | null>;
+  create(input: NewCar): Promise<Car>;
+  update(id: number, input: NewCar): Promise<Car | null>;
+  remove(id: number): Promise<boolean>;
+}
+
+// In-memory backend (the default, and the fallback when no database is reachable).
+function createMemoryStore(seed = true): CarStore {
+  let nextId = 1;
+  const cars = new Map<number, Car>();
+  if (seed) {
+    for (const car of DEMO_CARS) {
+      const id = nextId++;
+      cars.set(id, { id, ...car });
+    }
+  }
+  return {
+    async list() {
+      return [...cars.values()].sort((a, b) => a.id - b.id);
+    },
+    async get(id) {
+      return cars.get(id) ?? null;
+    },
+    async create(input) {
+      const car: Car = { id: nextId++, ...input };
+      cars.set(car.id, car);
+      return car;
+    },
+    async update(id, input) {
+      const car = cars.get(id);
+      if (!car) return null;
+      const next: Car = { ...car, ...input };
+      cars.set(id, next);
+      return next;
+    },
+    async remove(id) {
+      return cars.delete(id);
+    },
+  };
+}
+
+// #if db
+import { assertConnection, DataTypes, Model } from "@softeneers/db";
+
+import { sequelize } from "../db.js";
+
+class CarModel extends Model {
+  declare id: number;
+  declare brand: string;
+  declare model: string;
+  declare year: number;
+}
+
+CarModel.init(
+  {
+    id: { type: DataTypes.INTEGER, autoIncrement: true, primaryKey: true },
+    brand: { type: DataTypes.STRING, allowNull: false },
+    model: { type: DataTypes.STRING, allowNull: false },
+    year: { type: DataTypes.INTEGER, allowNull: false },
+  },
+  { sequelize, modelName: "Car", tableName: "cars" },
+);
+
+export { CarModel };
+
+const toCar = (m: CarModel): Car => ({ id: m.id, brand: m.brand, model: m.model, year: m.year });
+
+function createDbStore(): CarStore {
+  return {
+    async list() {
+      return (await CarModel.findAll({ order: [["id", "ASC"]] })).map(toCar);
+    },
+    async get(id) {
+      const m = await CarModel.findByPk(id);
+      return m ? toCar(m) : null;
+    },
+    async create(input) {
+      return toCar(await CarModel.create(input));
+    },
+    async update(id, input) {
+      const m = await CarModel.findByPk(id);
+      if (!m) return null;
+      await m.update(input);
+      return toCar(m);
+    },
+    async remove(id) {
+      const m = await CarModel.findByPk(id);
+      if (!m) return false;
+      await m.destroy();
+      return true;
+    },
+  };
+}
+
+// Resolve the backend once, lazily, on first use: try MySQL (create tables +
+// seed if empty); on any connection error, fall back to the in-memory store.
+let backend: Promise<CarStore> | null = null;
+function resolveBackend(): Promise<CarStore> {
+  if (!backend) {
+    backend = (async () => {
+      try {
+        await assertConnection(sequelize);
+        await sequelize.sync();
+        const db = createDbStore();
+        if ((await db.list()).length === 0) {
+          for (const car of DEMO_CARS) await db.create(car);
+        }
+        console.log("Data store: MySQL");
+        return db;
+      } catch {
+        console.warn(
+          "Data store: in-memory — database unreachable. Run `docker compose up -d` (and `npm run db:migrate && npm run db:seed`) for MySQL.",
+        );
+        return createMemoryStore();
+      }
+    })();
+  }
+  return backend;
+}
+
+export const carStore: CarStore = {
+  async list() {
+    return (await resolveBackend()).list();
+  },
+  async get(id) {
+    return (await resolveBackend()).get(id);
+  },
+  async create(input) {
+    return (await resolveBackend()).create(input);
+  },
+  async update(id, input) {
+    return (await resolveBackend()).update(id, input);
+  },
+  async remove(id) {
+    return (await resolveBackend()).remove(id);
+  },
+};
+// #endif
+// #if !db
+export const carStore: CarStore = createMemoryStore();
+// #endif

package/templates/express-api/src/cars/types.ts

@@ -0,0 +1,8 @@
+export interface Car {
+  id: number;
+  brand: string;
+  model: string;
+  year: number;
+}
+
+export type NewCar = Omit<Car, "id">;

package/templates/express-api/src/cars/validate.ts

@@ -0,0 +1,16 @@
+import type { NewCar } from "./types.js";
+
+/** Thrown when a request body is not a valid car. Mapped to HTTP 400. */
+export class ValidationError extends Error {}
+
+/** Validate and normalize an untrusted request body into a NewCar. */
+export function parseNewCar(body: unknown): NewCar {
+  const b = (body ?? {}) as Record<string, unknown>;
+  const brand = typeof b.brand === "string" ? b.brand.trim() : "";
+  const model = typeof b.model === "string" ? b.model.trim() : "";
+  const year = Number(b.year);
+  if (!brand || !model || !Number.isInteger(year)) {
+    throw new ValidationError("brand (string), model (string) and year (integer) are required.");
+  }
+  return { brand, model, year };
+}

package/templates/express-api/src/db.ts

@@ -0,0 +1,13 @@
+import { createDb } from "@softeneers/db";
+
+import { env } from "./env.js";
+
+// A configured (but not-yet-connected) Sequelize instance. Importing a model
+// registers it; `assertConnection`/`sync` open the connection on startup.
+export const sequelize = createDb({
+  host: env.DB_HOST,
+  port: env.DB_PORT,
+  database: env.DB_NAME,
+  username: env.DB_USER,
+  password: env.DB_PASSWORD,
+});

package/templates/express-api/src/env.ts

@@ -0,0 +1,23 @@
+import "dotenv/config";
+
+import { createEnv, z } from "@softeneers/env";
+
+// Validated, typed environment. Boot fails fast with a readable message if the
+// .env is wrong. Variables for a feature exist only when that toggle is on.
+export const env = createEnv({
+  schema: {
+    PORT: z.coerce.number().default(4000),
+    CORS_ORIGIN: z.string().default("http://localhost:3000"),
+    // #if db
+    DB_HOST: z.string().default("127.0.0.1"),
+    DB_PORT: z.coerce.number().default(3306),
+    DB_NAME: z.string().default("app_dev"),
+    DB_USER: z.string().default("root"),
+    DB_PASSWORD: z.string().default(""),
+    // #endif
+    // #if auth
+    AUTH_SECRET: z.string().min(16).default("dev-secret-change-me-to-a-long-random-string"),
+    AUTH_BASE_URL: z.string().default("http://localhost:4000"),
+    // #endif
+  },
+});

package/templates/express-api/src/index.ts

@@ -0,0 +1,37 @@
+import cors from "cors";
+import express from "express";
+
+import { carRouter } from "./cars/routes.js";
+import { env } from "./env.js";
+// #if auth
+import { toNodeHandler } from "@softeneers/auth";
+
+import { auth } from "./auth/auth.js";
+// #endif
+
+const app = express();
+
+// #if auth
+// better-auth handles its own body parsing, so mount it before express.json().
+app.all("/api/auth/*splat", toNodeHandler(auth));
+// #endif
+
+app.use(cors({ origin: env.CORS_ORIGIN }));
+app.use(express.json());
+
+app.get("/health", (_req, res) => {
+  res.json({ ok: true });
+});
+
+app.use("/api/cars", carRouter);
+
+app.use(
+  (error: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+    console.error("Unhandled error:", error);
+    res.status(500).json({ message: "Internal server error." });
+  },
+);
+
+app.listen(env.PORT, () => {
+  console.log(`API running on http://localhost:${env.PORT}`);
+});

package/templates/express-api/src/scripts/migrate.ts

@@ -0,0 +1,13 @@
+import "dotenv/config";
+
+import { assertConnection } from "@softeneers/db";
+
+import { sequelize } from "../db.js";
+import "../cars/store.js"; // importing the store registers the Car model
+
+const reset = process.argv.includes("--reset");
+
+await assertConnection(sequelize);
+await sequelize.sync({ force: reset });
+console.log(reset ? "Database reset — tables recreated." : "Database synced — tables ensured.");
+await sequelize.close();

package/templates/express-api/src/scripts/seed.ts

@@ -0,0 +1,20 @@
+import "dotenv/config";
+
+import { assertConnection } from "@softeneers/db";
+
+import { DEMO_CARS } from "../cars/demo.js";
+import { CarModel } from "../cars/store.js";
+import { sequelize } from "../db.js";
+
+await assertConnection(sequelize);
+await sequelize.sync();
+
+const count = await CarModel.count();
+if (count > 0) {
+  console.log(`Skipped seeding — ${count} cars already present.`);
+} else {
+  await CarModel.bulkCreate([...DEMO_CARS]);
+  console.log(`Seeded ${DEMO_CARS.length} cars.`);
+}
+
+await sequelize.close();

package/templates/express-api/test/validate.test.ts

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { parseNewCar, ValidationError } from "../src/cars/validate.ts";
+
+test("parses a valid car body", () => {
+  assert.deepEqual(parseNewCar({ brand: "Tesla", model: "Model 3", year: 2023 }), {
+    brand: "Tesla",
+    model: "Model 3",
+    year: 2023,
+  });
+});
+
+test("trims strings and coerces a numeric year", () => {
+  assert.deepEqual(parseNewCar({ brand: " Ford ", model: " Mustang ", year: "1969" }), {
+    brand: "Ford",
+    model: "Mustang",
+    year: 1969,
+  });
+});
+
+test("rejects an incomplete body", () => {
+  assert.throws(() => parseNewCar({ brand: "Toyota" }), ValidationError);
+  assert.throws(() => parseNewCar({}), ValidationError);
+});

package/templates/express-api/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

package/templates/hono-api/.env.example

@@ -0,0 +1,13 @@
+PORT=4000
+CORS_ORIGIN=http://localhost:3000
+# #if db
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_NAME=app_dev
+DB_USER=root
+DB_PASSWORD=
+# #endif
+# #if auth
+AUTH_SECRET=dev-secret-change-me-to-a-long-random-string
+AUTH_BASE_URL=http://localhost:4000
+# #endif

package/templates/hono-api/README.md

@@ -0,0 +1,77 @@
+# {{PROJECT_NAME}}
+
+A **Hono + TypeScript** API generated by
+[`create-softeneers-app`](https://www.npmjs.com/package/create-softeneers-app),
+served on Node via `@hono/node-server`, with a full cars CRUD example.
+
+## Scripts
+
+```bash
+npm run dev        # watch-run src/index.ts (tsx)
+npm run build      # type-check + emit dist/ (tsc)
+npm start          # run the built server
+npm run typecheck  # tsc --noEmit
+npm test           # node:test suite (via tsx)
+# #if db
+npm run db:migrate # create/sync tables
+npm run db:seed    # insert sample cars
+npm run db:reset   # drop, recreate, reseed
+# #endif
+```
+
+## API
+
+| Method | Path             | Description        |
+| ------ | ---------------- | ------------------ |
+| GET    | `/health`        | Liveness check     |
+| GET    | `/api/cars`      | List cars          |
+| GET    | `/api/cars/:id`  | Get one car        |
+| POST   | `/api/cars`      | Create a car       |
+| PUT    | `/api/cars/:id`  | Update a car       |
+| DELETE | `/api/cars/:id`  | Delete a car       |
+# #if auth
+| GET/POST | `/api/auth/*`  | better-auth routes |
+# #endif
+
+```bash
+curl localhost:4000/api/cars
+curl -X POST localhost:4000/api/cars -H 'content-type: application/json' \
+  -d '{"brand":"Tesla","model":"Model 3","year":2023}'
+```
+# #if db
+
+## Database
+
+Persistence is MySQL via Sequelize ([`@softeneers/db`](https://www.npmjs.com/package/@softeneers/db)).
+**`npm run dev` works immediately even without a database** — the store falls back
+to a pre-seeded in-memory one when MySQL is unreachable. To switch on real
+persistence, set `DB_*` in `.env` and start MySQL:
+
+```bash
+# #if docker
+docker compose up -d   # start MySQL
+# #endif
+# The app auto-creates and seeds tables on first connect; these scripts give
+# you explicit control (e.g. reseeding or a clean reset):
+npm run db:migrate && npm run db:seed
+```
+# #endif
+# #if auth
+
+## Authentication
+
+Email + password auth via better-auth ([`@softeneers/auth`](https://www.npmjs.com/package/@softeneers/auth)),
+mounted at `/api/auth/*`. Set a strong `AUTH_SECRET` in `.env` before deploying.
+# #endif
+
+## Getting started
+
+```bash
+npm install
+npm run dev          # a pre-seeded CRUD demo — no other setup needed
+```
+# #if db
+
+The app starts immediately on an in-memory demo and uses MySQL automatically once
+it's reachable — see **Database** above to enable persistence.
+# #endif

package/templates/hono-api/docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  db:
+    image: mysql:8
+    restart: unless-stopped
+    environment:
+      MYSQL_DATABASE: ${DB_NAME:-app_dev}
+      MYSQL_ROOT_PASSWORD: ${DB_PASSWORD:-}
+      MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
+    ports:
+      - "${DB_PORT:-3306}:3306"
+    volumes:
+      - db_data:/var/lib/mysql
+
+volumes:
+  db_data:

package/templates/hono-api/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "hono-api",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Hono + TypeScript API generated by create-softeneers-app.",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "db:migrate": "tsx src/scripts/migrate.ts",
+    "db:seed": "tsx src/scripts/seed.ts",
+    "db:reset": "tsx src/scripts/migrate.ts --reset && tsx src/scripts/seed.ts",
+    "test": "node --import tsx --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.0",
+    "@softeneers/auth": "^0.1.0",
+    "@softeneers/db": "^0.1.0",
+    "@softeneers/env": "^0.1.0",
+    "dotenv": "^16.4.5",
+    "hono": "^4.6.0",
+    "mysql2": "^3.11.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/hono-api/softeneers.template.json

@@ -0,0 +1,17 @@
+{
+  "toggles": { "db": false, "auth": false, "docker": false },
+  "fragments": {
+    "db": {
+      "removePaths": ["src/db.ts", "src/scripts", "docker-compose.yml"],
+      "removeDeps": ["@softeneers/db", "mysql2"],
+      "removeScripts": ["db:migrate", "db:seed", "db:reset"]
+    },
+    "auth": {
+      "removePaths": ["src/auth"],
+      "removeDeps": ["@softeneers/auth"]
+    },
+    "docker": {
+      "removePaths": ["docker-compose.yml"]
+    }
+  }
+}

package/templates/hono-api/src/auth/auth.ts

@@ -0,0 +1,11 @@
+import { createAuth } from "@softeneers/auth";
+
+import { env } from "../env.js";
+
+// Email + password authentication via better-auth. With no `database` configured
+// better-auth uses an in-memory store (fine for local dev); point it at your DB
+// for persistence. Routes are mounted at /api/auth/* in src/index.ts.
+export const auth = createAuth({
+  secret: env.AUTH_SECRET,
+  baseURL: env.AUTH_BASE_URL,
+});

package/templates/hono-api/src/cars/demo.ts

@@ -0,0 +1,10 @@
+import type { NewCar } from "./types.js";
+
+// Demo garage inventory seeded on first run so `npm run dev` shows a working
+// CRUD demo immediately — into MySQL when a database is reachable, otherwise
+// into the in-memory store.
+export const DEMO_CARS: NewCar[] = [
+  { brand: "Toyota", model: "Corolla", year: 2021 },
+  { brand: "Tesla", model: "Model 3", year: 2023 },
+  { brand: "Ford", model: "Mustang", year: 1969 },
+];