create-pangza 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# create-pangza
+
+初始化空项目，并按需生成 `entity` / `mapper` / `service` / `controller`。
+
+## init
+
+```bash
+npx create-pangza init my-app
+# 或
+npm create pangza@latest -- init my-app
+```
+
+交互勾选模块：`orm` / `auth` / `redis` / `log` / `schedule` / `encrypt` / `validate`。
+
+```bash
+npx create-pangza init my-app --modules=orm,auth,redis --db=mysql
+```
+
+## generate（`g`）
+
+在项目根目录执行：
+
+```bash
+npx create-pangza g controller user
+npx create-pangza g service user
+npx create-pangza g mapper user
+npx create-pangza g entity user
+
+# 一次生成整套用户模块
+npx create-pangza g all user
+```
+
+别名：`c|controller|cotroller`、`s|service`、`m|mapper`、`e|entity`、`a|all`。  
+覆盖已有文件：加 `--force`。
+
+生成路径示例（`user`）：
+
+```text
+src/entity/user.ts
+src/mapper/user.ts
+src/service/user.ts
+src/controller/user/index.ts   → /api/user
+```
+
+## 发布
+
+```bash
+cd create-pangza
+npm publish --access public --registry=https://registry.npmjs.org
+```

package/bin/create-pangza.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { MODULES, DB_CHOICES } = require("../lib/modules");
+const { scaffold } = require("../lib/scaffold");
+const { generate, resolveKind } = require("../lib/generate");
+const {
+  createRl,
+  askText,
+  askSelect,
+  askMulti,
+  askYesNo,
+} = require("../lib/prompt");
+
+function usage() {
+  console.log(`create-pangza — scaffold & generate for @pangza/express
+
+Init (empty app + optional modules):
+  create-pangza init [project-name]
+  create-pangza init my-app --modules=orm,redis --db=mysql
+
+Generate (run inside a project):
+  create-pangza g controller user
+  create-pangza g service user
+  create-pangza g mapper user
+  create-pangza g entity user
+  create-pangza g all user
+
+  Aliases: g|generate   c|controller|cotroller   s|service   m|mapper   e|entity   a|all
+  Flags:   --force   overwrite existing files
+
+Modules (init):
+${MODULES.map((m) => `  ${m.id.padEnd(10)} ${m.hint}`).join("\n")}
+`);
+}
+
+function parseArgs(argv) {
+  const args = {
+    cmd: null,
+    name: null,
+    modules: null,
+    db: null,
+    help: false,
+    force: false,
+    genKind: null,
+    genName: null,
+  };
+  const rest = [];
+  for (const a of argv) {
+    if (a === "-h" || a === "--help") args.help = true;
+    else if (a === "--force" || a === "-f") args.force = true;
+    else if (a.startsWith("--modules=")) {
+      args.modules = a
+        .slice("--modules=".length)
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    } else if (a.startsWith("--db=")) {
+      args.db = a.slice("--db=".length).trim();
+    } else {
+      rest.push(a);
+    }
+  }
+
+  const head = rest[0];
+  if (head === "init") {
+    args.cmd = "init";
+    args.name = rest[1] || null;
+  } else if (head === "g" || head === "generate") {
+    args.cmd = "generate";
+    args.genKind = rest[1] || null;
+    args.genName = rest[2] || null;
+  } else if (head) {
+    // 兼容：create-pangza my-app → init
+    args.cmd = "init";
+    args.name = head;
+  }
+  return args;
+}
+
+function isValidName(name) {
+  return Boolean(name) && /^[a-zA-Z0-9._@/-]+$/.test(name) && !name.includes("..");
+}
+
+function normalizeProjectName(raw) {
+  const base = path.basename(String(raw).replace(/[\\/]+$/, ""));
+  return base.startsWith("@") ? base : base.toLowerCase();
+}
+
+async function runInit(args) {
+  const rl = createRl();
+  try {
+    let projectNameInput = args.name;
+    if (!projectNameInput) {
+      projectNameInput = await askText(rl, "项目目录名", "pangza-app");
+    }
+    if (!isValidName(projectNameInput)) {
+      console.error(`Invalid project name: ${projectNameInput}`);
+      process.exit(1);
+    }
+
+    const targetDir = path.resolve(process.cwd(), projectNameInput);
+    if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+      console.error(`Directory is not empty: ${targetDir}`);
+      process.exit(1);
+    }
+
+    let modules = args.modules;
+    if (!modules) {
+      modules = await askMulti(
+        rl,
+        "选择要启用的模块（空模板默认只有 HTTP 核心）",
+        MODULES.map((m) => ({
+          value: m.id,
+          label: m.label,
+          hint: m.hint,
+        })),
+      );
+    } else {
+      const known = new Set(MODULES.map((m) => m.id));
+      const bad = modules.filter((m) => !known.has(m));
+      if (bad.length) {
+        console.error(`Unknown modules: ${bad.join(", ")}`);
+        process.exit(1);
+      }
+    }
+
+    if (modules.includes("auth") && !modules.includes("redis")) {
+      const addRedis =
+        args.modules != null
+          ? true
+          : await askYesNo(
+              rl,
+              "Auth 通常需要 Redis 存 token，是否一并启用 redis？",
+              true,
+            );
+      if (addRedis) modules = [...new Set([...modules, "redis"])];
+    }
+
+    let dbType = args.db || "mysql";
+    if (modules.includes("orm")) {
+      if (!args.db) {
+        dbType = await askSelect(rl, "ORM 数据库类型", DB_CHOICES, "mysql");
+      } else if (!DB_CHOICES.some((c) => c.value === args.db)) {
+        console.error(`Unknown --db=${args.db}`);
+        process.exit(1);
+      }
+    }
+
+    const pkgName = normalizeProjectName(projectNameInput);
+    scaffold({
+      targetDir,
+      projectName: pkgName,
+      modules,
+      dbType,
+    });
+
+    console.log(`
+✓ 已初始化空项目: ${projectNameInput}
+  模块: ${modules.length ? modules.join(", ") : "(仅核心)"}
+${modules.includes("orm") ? `  数据库: ${dbType}\n` : ""}
+下一步:
+  cd ${projectNameInput}
+  cp .env.example .env
+  npm install
+  npm run dev
+
+生成业务文件:
+  npx create-pangza g all user
+`);
+  } finally {
+    rl.close();
+  }
+}
+
+function runGenerate(args) {
+  if (!args.genKind || !args.genName) {
+    console.error("Usage: create-pangza g <controller|service|mapper|entity|all> <name>");
+    process.exit(1);
+  }
+  if (!resolveKind(args.genKind)) {
+    console.error(`Unknown type: ${args.genKind}`);
+    console.error("Use: controller|service|mapper|entity|all (or c|s|m|e|a)");
+    process.exit(1);
+  }
+
+  try {
+    const { root, results, Pascal } = generate({
+      kind: args.genKind,
+      name: args.genName,
+      force: args.force,
+    });
+
+    console.log(`✓ generate ${args.genKind} ${Pascal}  (root: ${root})`);
+    for (const r of results) {
+      const mark = r.status === "skip" ? "skip" : "write";
+      console.log(`  [${mark}] ${r.rel}`);
+    }
+    if (results.some((r) => r.status === "skip")) {
+      console.log("  (已存在文件已跳过；覆盖请加 --force)");
+    }
+  } catch (err) {
+    console.error(err.message || err);
+    process.exit(1);
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || !args.cmd) {
+    usage();
+    process.exit(args.help ? 0 : 1);
+  }
+  if (args.cmd === "init") {
+    await runInit(args);
+    return;
+  }
+  if (args.cmd === "generate") {
+    runGenerate(args);
+    return;
+  }
+  usage();
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/lib/generate.js

@@ -0,0 +1,234 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { toSnake, toPascal, toApiPath, toFileBase } = require("./names");
+
+const KINDS = {
+  entity: { alias: ["e", "entity"] },
+  mapper: { alias: ["m", "mapper"] },
+  service: { alias: ["s", "service"] },
+  controller: { alias: ["c", "controller", "cotroller"] }, // cotroller: 常见拼写容错
+  all: { alias: ["all", "a"] },
+};
+
+function resolveKind(raw) {
+  const key = String(raw || "").toLowerCase();
+  for (const [kind, meta] of Object.entries(KINDS)) {
+    if (meta.alias.includes(key)) return kind;
+  }
+  return null;
+}
+
+function findProjectRoot(cwd = process.cwd()) {
+  let dir = cwd;
+  for (;;) {
+    const pkg = path.join(dir, "package.json");
+    if (fs.existsSync(pkg)) {
+      try {
+        const json = JSON.parse(fs.readFileSync(pkg, "utf8"));
+        const deps = {
+          ...(json.dependencies || {}),
+          ...(json.devDependencies || {}),
+        };
+        if (deps["@pangza/express"]) return dir;
+      } catch {
+        /* ignore */
+      }
+      // 有 package.json 也当作项目根（容错）
+      if (fs.existsSync(path.join(dir, "src"))) return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return cwd;
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeFile(filePath, content, { force }) {
+  if (fs.existsSync(filePath) && !force) {
+    return { path: filePath, status: "skip" };
+  }
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, content, "utf8");
+  return { path: filePath, status: fs.existsSync(filePath) ? "write" : "write" };
+}
+
+function tplEntity({ Pascal, snake }) {
+  return `import { TableField, TableId, TableName } from "@pangza/express";
+
+@TableName("${snake}")
+export default class ${Pascal}Entity {
+  @TableId()
+  id!: string;
+
+  @TableField({
+    value: "create_time",
+    insertFill: () => new Date(),
+  })
+  createTime?: Date;
+
+  @TableField({
+    value: "update_time",
+    insertFill: () => new Date(),
+    updateFill: () => new Date(),
+  })
+  updateTime?: Date;
+
+  @TableField({
+    value: "delete_flag",
+    insertFill: 0,
+  })
+  deleteFlag?: number;
+}
+`;
+}
+
+function tplMapper({ Pascal, fileBase }) {
+  return `import { Mapper, MapperType } from "@pangza/express";
+import ${Pascal}Entity from "../entity/${fileBase}";
+
+@Mapper(${Pascal}Entity)
+export default class ${Pascal}Mapper extends MapperType {}
+`;
+}
+
+function tplService({ Pascal, fileBase }) {
+  return `import { BaseService, Service } from "@pangza/express";
+import ${Pascal}Mapper from "../mapper/${fileBase}";
+
+@Service(${Pascal}Mapper)
+export default class ${Pascal}Service extends BaseService {}
+`;
+}
+
+function tplController({ Pascal, fileBase, apiPath, camel }) {
+  return `import {
+  Controller,
+  DeleteMapping,
+  GetMapping,
+  PostMapping,
+  PutMapping,
+  RequestBody,
+  RequestPath,
+  Resource,
+} from "@pangza/express";
+import ${Pascal}Service from "../../service/${fileBase}";
+
+@Controller("/api/${apiPath}")
+export default class ${Pascal}Controller {
+  @Resource(${Pascal}Service)
+  ${camel}Service!: ${Pascal}Service;
+
+  @GetMapping("/")
+  list() {
+    return this.${camel}Service.selectList();
+  }
+
+  @GetMapping("/:id")
+  detail(@RequestPath() id: string) {
+    return this.${camel}Service.selectById(id);
+  }
+
+  @PostMapping("/")
+  create(@RequestBody() body: Record<string, unknown>) {
+    return this.${camel}Service.insert(body);
+  }
+
+  @PutMapping("/:id")
+  update(@RequestPath() id: string, @RequestBody() body: Record<string, unknown>) {
+    return this.${camel}Service.updateById({ ...body, id });
+  }
+
+  @DeleteMapping("/:id")
+  remove(@RequestPath() id: string) {
+    return this.${camel}Service.deleteById(id);
+  }
+}
+`;
+}
+
+/**
+ * @param {{
+ *   kind: string,
+ *   name: string,
+ *   cwd?: string,
+ *   force?: boolean,
+ * }} opts
+ */
+function generate(opts) {
+  const kind = resolveKind(opts.kind);
+  if (!kind) {
+    throw new Error(
+      `Unknown type "${opts.kind}". Use: controller|service|mapper|entity|all`,
+    );
+  }
+  if (!opts.name || !/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(opts.name)) {
+    throw new Error(`Invalid name: ${opts.name}`);
+  }
+
+  const root = findProjectRoot(opts.cwd || process.cwd());
+  const fileBase = toFileBase(opts.name);
+  const Pascal = toPascal(opts.name);
+  const snake = toSnake(opts.name);
+  const apiPath = toApiPath(opts.name);
+  const camel = fileBase;
+  const force = Boolean(opts.force);
+
+  const ctx = { Pascal, snake, fileBase, apiPath, camel };
+
+  /** @type {{ kind: string, rel: string, content: string }[]} */
+  const jobs = [];
+
+  const want = kind === "all"
+    ? ["entity", "mapper", "service", "controller"]
+    : [kind];
+
+  for (const k of want) {
+    if (k === "entity") {
+      jobs.push({
+        kind: k,
+        rel: path.join("src", "entity", `${fileBase}.ts`),
+        content: tplEntity(ctx),
+      });
+    } else if (k === "mapper") {
+      jobs.push({
+        kind: k,
+        rel: path.join("src", "mapper", `${fileBase}.ts`),
+        content: tplMapper(ctx),
+      });
+    } else if (k === "service") {
+      jobs.push({
+        kind: k,
+        rel: path.join("src", "service", `${fileBase}.ts`),
+        content: tplService(ctx),
+      });
+    } else if (k === "controller") {
+      jobs.push({
+        kind: k,
+        rel: path.join("src", "controller", fileBase, "index.ts"),
+        content: tplController(ctx),
+      });
+    }
+  }
+
+  const results = [];
+  for (const job of jobs) {
+    const abs = path.join(root, job.rel);
+    const r = writeFile(abs, job.content, { force });
+    results.push({ kind: job.kind, ...r, rel: job.rel });
+  }
+
+  return { root, results, Pascal, snake };
+}
+
+module.exports = {
+  KINDS,
+  resolveKind,
+  findProjectRoot,
+  generate,
+};

package/lib/modules.js

@@ -0,0 +1,223 @@
+"use strict";
+
+/** 可选能力模块（当前均由单包 @pangza/express 提供，差异在依赖与脚手架文件） */
+const MODULES = [
+  {
+    id: "orm",
+    label: "ORM",
+    hint: "Db / Mapper / QueryWrapper / 多数据源",
+  },
+  {
+    id: "auth",
+    label: "Auth",
+    hint: "登录态、角色权限装饰器（建议同时选 Redis）",
+  },
+  {
+    id: "redis",
+    label: "Redis",
+    hint: "缓存、限流、Auth token 存储",
+  },
+  {
+    id: "log",
+    label: "Log",
+    hint: "操作审计日志装饰器",
+  },
+  {
+    id: "schedule",
+    label: "Schedule",
+    hint: "定时任务 (cron)",
+  },
+  {
+    id: "encrypt",
+    label: "Encrypt",
+    hint: "AES 等传输加密工具",
+  },
+  {
+    id: "validate",
+    label: "Validate",
+    hint: "参数校验装饰器",
+  },
+];
+
+const DB_CHOICES = [
+  { value: "mysql", label: "MySQL (mysql2)" },
+  { value: "postgresql", label: "PostgreSQL (pg)" },
+  { value: "mssql", label: "SQL Server (mssql)" },
+];
+
+const DB_DEPS = {
+  mysql: { mysql2: "^3.24.4" },
+  postgresql: { pg: "^8.23.1" },
+  mssql: { mssql: "^12.7.9" },
+};
+
+const DB_ENV = {
+  mysql: [
+    "DB_TYPE=mysql",
+    "MYSQL_HOST=127.0.0.1",
+    "MYSQL_PORT=3306",
+    "MYSQL_USER=root",
+    "MYSQL_PASSWORD=",
+    "MYSQL_DATABASE=pangza",
+  ],
+  postgresql: [
+    "DB_TYPE=postgresql",
+    "PG_HOST=127.0.0.1",
+    "PG_PORT=5432",
+    "PG_USER=postgres",
+    "PG_PASSWORD=",
+    "PG_DATABASE=pangza",
+  ],
+  mssql: [
+    "DB_TYPE=mssql",
+    "MSSQL_HOST=127.0.0.1",
+    "MSSQL_PORT=1433",
+    "MSSQL_USER=sa",
+    "MSSQL_PASSWORD=",
+    "MSSQL_DATABASE=pangza",
+  ],
+};
+
+/** @param {string[]} moduleIds @param {string} [dbType] */
+function resolveDependencies(moduleIds, dbType = "mysql") {
+  const deps = {
+    "@pangza/express": "^1.0.0",
+    cors: "^2.8.5",
+    express: "^5.2.1",
+    inversify: "^8.2.3",
+    "reflect-metadata": "^0.2.2",
+  };
+  const set = new Set(moduleIds);
+
+  if (set.has("orm")) {
+    Object.assign(deps, DB_DEPS[dbType] || DB_DEPS.mysql);
+  }
+  if (set.has("redis") || set.has("auth")) {
+    deps.redis = "^6.2.1";
+  }
+  if (set.has("auth")) {
+    deps.jsonwebtoken = "^9.0.3";
+    deps.bcryptjs = "^3.0.3";
+  }
+  if (set.has("schedule")) {
+    deps["node-cron"] = "^4.6.0";
+  }
+
+  return deps;
+}
+
+/** @param {string[]} moduleIds @param {string} [dbType] */
+function resolveEnvLines(moduleIds, dbType = "mysql") {
+  const lines = ["PORT=5270"];
+  const set = new Set(moduleIds);
+
+  if (set.has("orm")) {
+    lines.push("", "# Database", ...(DB_ENV[dbType] || DB_ENV.mysql));
+  }
+  if (set.has("redis") || set.has("auth")) {
+    lines.push(
+      "",
+      "# Redis",
+      "REDIS_HOST=127.0.0.1",
+      "REDIS_PORT=6379",
+      "REDIS_PASSWORD=",
+    );
+  }
+  if (set.has("auth")) {
+    lines.push("", "# Auth", "JWT_SECRET=change-me");
+  }
+  return lines;
+}
+
+/** @param {string[]} moduleIds */
+function resolveDirs(moduleIds) {
+  const dirs = ["src"];
+  const set = new Set(moduleIds);
+  if (set.has("orm")) {
+    dirs.push("src/entity", "src/mapper", "src/service", "src/controller");
+  } else {
+    dirs.push("src/controller");
+  }
+  if (set.has("schedule")) dirs.push("src/schedule");
+  return dirs;
+}
+
+/**
+ * 生成空项目入口：只起 HTTP，模块相关注释提示用户自行接入。
+ * @param {string[]} moduleIds
+ */
+function generateMainTs(moduleIds) {
+  const set = new Set(moduleIds);
+  const imports = [
+    'import "reflect-metadata";',
+    'import cors from "cors";',
+    'import { json } from "express";',
+    'import { Application, Logger } from "@pangza/express";',
+  ];
+
+  const notes = [];
+  if (set.has("orm")) {
+    notes.push(
+      "// ORM: 配置 .env 中的数据库变量后即可使用 @Mapper / QueryWrapper",
+    );
+  }
+  if (set.has("redis") || set.has("auth")) {
+    notes.push("// Redis: 配置 REDIS_* 后由框架自动连接（见文档）");
+  }
+  if (set.has("auth")) {
+    notes.push(
+      '// Auth: Application.registry(Auth({ ignore: ["/api/pub/**"] }))',
+    );
+  }
+  if (set.has("log")) {
+    notes.push("// Log: configureLog({ writer }) 后配合 @Log 装饰器");
+  }
+  if (set.has("schedule")) {
+    notes.push("// Schedule: 在 src/schedule 编写任务并由扫描加载");
+  }
+  if (set.has("encrypt")) {
+    notes.push("// Encrypt: 从 @pangza/express 导入 AESUtil 等");
+  }
+  if (set.has("validate")) {
+    notes.push("// Validate: 在 Controller 参数上使用校验装饰器");
+  }
+
+  const body = [
+    ...imports,
+    "",
+    ...(notes.length ? [...notes, ""] : []),
+    "Application.registry(Logger({ level: \"info\" }))",
+    "  .registry(cors())",
+    "  .registry(json())",
+    '  .scan("src")',
+    "  .start();",
+    "",
+  ];
+  return body.join("\n");
+}
+
+function generateGitkeepReadme(moduleIds) {
+  const set = new Set(moduleIds);
+  const files = {
+    "src/controller/.gitkeep": "",
+  };
+  if (set.has("orm")) {
+    files["src/entity/.gitkeep"] = "";
+    files["src/mapper/.gitkeep"] = "";
+    files["src/service/.gitkeep"] = "";
+  }
+  if (set.has("schedule")) {
+    files["src/schedule/.gitkeep"] = "";
+  }
+  return files;
+}
+
+module.exports = {
+  MODULES,
+  DB_CHOICES,
+  resolveDependencies,
+  resolveEnvLines,
+  resolveDirs,
+  generateMainTs,
+  generateGitkeepReadme,
+};

package/lib/names.js

@@ -0,0 +1,40 @@
+"use strict";
+
+/** user_role / user-role / userRole → user_role (table) */
+function toSnake(name) {
+  return String(name)
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[-\s]+/g, "_")
+    .replace(/__+/g, "_")
+    .toLowerCase();
+}
+
+/** user_role → userRole */
+function toCamel(name) {
+  const snake = toSnake(name);
+  return snake.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/** user_role → UserRole */
+function toPascal(name) {
+  const camel = toCamel(name);
+  return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+
+/** user_role → user-role (url segment often snake or kebab; we use snake for path) */
+function toApiPath(name) {
+  return toSnake(name).replace(/_/g, "-");
+}
+
+/** file base under src/* : prefer camel for multi-word, keep simple names as-is */
+function toFileBase(name) {
+  return toCamel(name);
+}
+
+module.exports = {
+  toSnake,
+  toCamel,
+  toPascal,
+  toApiPath,
+  toFileBase,
+};

package/lib/prompt.js

@@ -0,0 +1,94 @@
+"use strict";
+
+const readline = require("readline");
+
+function createRl() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+function ask(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => resolve(String(answer || "").trim()));
+  });
+}
+
+/**
+ * @param {string} message
+ * @param {string} [fallback]
+ */
+async function askText(rl, message, fallback = "") {
+  const hint = fallback ? ` (${fallback})` : "";
+  const answer = await ask(rl, `${message}${hint}: `);
+  return answer || fallback;
+}
+
+/**
+ * @param {string} message
+ * @param {{ value: string, label: string }[]} choices
+ * @param {string} [fallback]
+ */
+async function askSelect(rl, message, choices, fallback) {
+  console.log(`\n${message}`);
+  choices.forEach((c, i) => {
+    console.log(`  ${i + 1}) ${c.label}`);
+  });
+  const def =
+    fallback != null
+      ? choices.findIndex((c) => c.value === fallback) + 1
+      : 1;
+  const answer = await ask(rl, `选择 [1-${choices.length}] (默认 ${def}): `);
+  const n = Number(answer || def);
+  if (!Number.isInteger(n) || n < 1 || n > choices.length) {
+    console.log(`无效选择，使用默认: ${choices[def - 1].label}`);
+    return choices[def - 1].value;
+  }
+  return choices[n - 1].value;
+}
+
+/**
+ * Multi-select by comma-separated numbers.
+ * @param {string} message
+ * @param {{ value: string, label: string, hint?: string }[]} choices
+ * @param {string[]} [preselected]
+ */
+async function askMulti(rl, message, choices, preselected = []) {
+  console.log(`\n${message}`);
+  console.log("（输入序号，逗号分隔；直接回车=不选额外模块）");
+  choices.forEach((c, i) => {
+    const mark = preselected.includes(c.value) ? "*" : " ";
+    const hint = c.hint ? ` — ${c.hint}` : "";
+    console.log(`  ${i + 1}) [${mark}] ${c.label}${hint}`);
+  });
+  const answer = await ask(rl, "> ");
+  if (!answer) return [...preselected];
+
+  const picked = new Set(preselected);
+  for (const part of answer.split(/[,，\s]+/)) {
+    if (!part) continue;
+    const n = Number(part);
+    if (!Number.isInteger(n) || n < 1 || n > choices.length) {
+      console.log(`忽略无效项: ${part}`);
+      continue;
+    }
+    picked.add(choices[n - 1].value);
+  }
+  return [...picked];
+}
+
+async function askYesNo(rl, message, defaultYes = true) {
+  const tip = defaultYes ? "Y/n" : "y/N";
+  const answer = (await ask(rl, `${message} (${tip}): `)).toLowerCase();
+  if (!answer) return defaultYes;
+  return answer === "y" || answer === "yes";
+}
+
+module.exports = {
+  createRl,
+  askText,
+  askSelect,
+  askMulti,
+  askYesNo,
+};

package/lib/scaffold.js

@@ -0,0 +1,120 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  resolveDependencies,
+  resolveEnvLines,
+  resolveDirs,
+  generateMainTs,
+  generateGitkeepReadme,
+} = require("./modules");
+
+const ROOT = path.join(__dirname, "..");
+const BASE_TEMPLATE = path.join(ROOT, "template", "base");
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeFile(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, content, "utf8");
+}
+
+function copyFile(src, dest) {
+  ensureDir(path.dirname(dest));
+  fs.copyFileSync(src, dest);
+}
+
+/**
+ * @param {{
+ *   targetDir: string,
+ *   projectName: string,
+ *   modules: string[],
+ *   dbType?: string,
+ * }} opts
+ */
+function scaffold(opts) {
+  const {
+    targetDir,
+    projectName,
+    modules,
+    dbType = "mysql",
+  } = opts;
+
+  ensureDir(targetDir);
+
+  // base static files
+  copyFile(
+    path.join(BASE_TEMPLATE, "tsconfig.json"),
+    path.join(targetDir, "tsconfig.json"),
+  );
+  copyFile(
+    path.join(BASE_TEMPLATE, "gitignore"),
+    path.join(targetDir, ".gitignore"),
+  );
+
+  for (const dir of resolveDirs(modules)) {
+    ensureDir(path.join(targetDir, dir));
+  }
+
+  const pkg = {
+    name: projectName,
+    version: "1.0.0",
+    private: true,
+    description: "Pangza Express app",
+    scripts: {
+      dev: "ts-node -r tsconfig-paths/register src/main.ts",
+      build: "tsc -p tsconfig.json",
+      start: "node dist/main.js",
+    },
+    dependencies: resolveDependencies(modules, dbType),
+    devDependencies: {
+      "@types/cors": "^2.8.19",
+      "@types/express": "^5.0.6",
+      "@types/node": "^22.0.0",
+      "ts-node": "^10.9.2",
+      "tsconfig-paths": "^4.2.0",
+      typescript: "^5.9.3",
+    },
+  };
+
+  writeFile(
+    path.join(targetDir, "package.json"),
+    JSON.stringify(pkg, null, 2) + "\n",
+  );
+  writeFile(
+    path.join(targetDir, ".env.example"),
+    resolveEnvLines(modules, dbType).join("\n") + "\n",
+  );
+  writeFile(path.join(targetDir, "src", "main.ts"), generateMainTs(modules));
+
+  const extras = generateGitkeepReadme(modules);
+  for (const [rel, content] of Object.entries(extras)) {
+    writeFile(path.join(targetDir, rel), content);
+  }
+
+  writeFile(
+    path.join(targetDir, "README.md"),
+    `# ${projectName}
+
+Generated by \`create-pangza init\`.
+
+## Modules
+
+${modules.length ? modules.map((m) => `- ${m}`).join("\n") : "- (core only)"}
+
+${modules.includes("orm") ? `Database: **${dbType}**\n` : ""}
+## Run
+
+\`\`\`bash
+cp .env.example .env
+npm install
+npm run dev
+\`\`\`
+`,
+  );
+}
+
+module.exports = { scaffold };

package/package.json

@@ -1,6 +1,39 @@
-{
-  "name": "create-pangza",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "create-pangza",
+  "version": "1.0.0",
+  "description": "Scaffold & generate for @pangza/express (init / g controller|service|mapper|entity|all)",
+  "bin": {
+    "create-pangza": "./bin/create-pangza.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "template",
+    "README.md"
+  ],
+  "keywords": [
+    "pangza",
+    "express",
+    "scaffold",
+    "create",
+    "init",
+    "typescript"
+  ],
+  "author": "",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lx-ayan/pangza-admin-express.git",
+    "directory": "create-pangza"
+  },
+  "bugs": {
+    "url": "https://github.com/lx-ayan/pangza-admin-express/issues"
+  },
+  "homepage": "https://github.com/lx-ayan/pangza-admin-express#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/base/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.env
+*.log
+.DS_Store

package/template/base/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"]
+}