@robsun/create-keystone-app 0.1.13 → 0.1.14

package/README.md

@@ -1,22 +1,31 @@
-# @robsun/create-keystone-app
+# @robsun/create-keystone-app
 
 ## 用法
 ```bash
-npx @robsun/create-keystone-app <dir> [--demo]
-pnpm dlx @robsun/create-keystone-app <dir> [--demo]
+npx @robsun/create-keystone-app <dir> [options]
+pnpm dlx @robsun/create-keystone-app <dir> [options]
 ```
 
-## 参数
-- `<dir>`：目标目录（必填）。新目录名或 `.`（当前目录）。
-- `--demo`：生成 Demo 模块（默认不生成）。
-- 目标目录必须为空；不为空会退出。
+## 选项
+- `<dir>`：目标目录（必填），可为新目录名或 `.`（当前目录）。
+- `--profile <starter|full>`：模板档位，默认 `starter`。
+- `--demo` / `--no-demo`：是否包含 Demo 模块（`full` 默认包含）。
+- `--db <sqlite|postgres>`：数据库驱动（默认 `sqlite`）。
+- `--queue <memory|redis>`：队列驱动（默认 `memory`）。
+- `--storage <local|s3>`：存储驱动（默认 `local`）。
+
+## 示例
+```bash
+npx @robsun/create-keystone-app my-app --profile=full --db=postgres --queue=redis
+```
 
 ## 初始化后操作
 ```bash
 cd <dir>
 pnpm install
-pnpm server:dev
 pnpm dev
 ```
-- Web 默认端口：`3000`，后端默认端口：`8080`。
-- `--demo` 模式下：Demo API 为 `/api/v1/demo/tasks`。
+
+## 端口与 Demo
+- Web 默认端口：`3000`；后端默认端口：`8080`。
+- Demo API：`/api/v1/demo/tasks`（仅在包含 Demo 时可用）。

package/bin/create-keystone-app.js

@@ -3,45 +3,44 @@ const fs = require('fs');
 const path = require('path');
 
 const usage = [
-  'Usage: create-keystone-app <dir> [--demo]',
+  'Usage: create-keystone-app <dir> [options]',
   '',
   'Options:',
-  '  --demo   Include demo module',
+  '  --profile <starter|full>  Template profile (default: starter)',
+  '  --demo                    Include demo module',
+  '  --no-demo                 Exclude demo module',
+  '  --db <sqlite|postgres>    Database driver (default: sqlite)',
+  '  --queue <memory|redis>    Queue driver (default: memory)',
+  '  --storage <local|s3>      Storage driver (default: local)',
+  '  -h, --help                Show help',
 ].join('\n');
-const args = process.argv.slice(2);
-let rawTarget = null;
-let includeDemo = false;
-
-for (const arg of args) {
-  if (arg === '--demo') {
-    includeDemo = true;
-    continue;
-  }
-  if (arg === '--help' || arg === '-h') {
-    console.log(usage);
-    process.exit(0);
-  }
-  if (arg.startsWith('-')) {
-    console.error(`Unknown option: ${arg}`);
-    console.error(usage);
-    process.exit(1);
-  }
-  if (!rawTarget) {
-    rawTarget = arg;
-    continue;
-  }
-  console.error('Too many arguments.');
-  console.error(usage);
-  process.exit(1);
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help) {
+  console.log(usage);
+  process.exit(0);
 }
 
-if (!rawTarget) {
+if (!args.target) {
   console.error(usage);
   process.exit(1);
 }
 
-const targetDir = path.resolve(process.cwd(), rawTarget);
-const targetName = rawTarget === '.'
+const profile = normalizeChoice(args.profile, ['starter', 'full'], 'profile') || 'starter';
+const db = normalizeChoice(args.db, ['sqlite', 'postgres'], 'db') || 'sqlite';
+const queue = normalizeChoice(args.queue, ['memory', 'redis'], 'queue') || 'memory';
+const storage = normalizeChoice(args.storage, ['local', 's3'], 'storage') || 'local';
+
+let includeDemo = profile === 'full';
+if (args.demo === true) {
+  includeDemo = true;
+}
+if (args.demo === false) {
+  includeDemo = false;
+}
+
+const targetDir = path.resolve(process.cwd(), args.target);
+const targetName = args.target === '.'
   ? path.basename(process.cwd())
   : path.basename(targetDir);
 
@@ -61,13 +60,15 @@ copyDir(templateDir, targetDir, {
   '__RAW_NAME__': targetName,
 });
 
+applyConfigOptions(targetDir, { db, queue, storage });
+
 if (!includeDemo) {
   stripDemo(targetDir);
 }
 
 console.log(`Created ${targetName}`);
 console.log('Next steps:');
-console.log(`  cd ${rawTarget}`);
+console.log(`  cd ${args.target}`);
 console.log('  pnpm install');
 console.log('  pnpm server:dev');
 console.log('  pnpm dev');
@@ -102,11 +103,18 @@ function copyFile(src, dest, replacements) {
     content = content.split(key).join(value);
   }
   fs.writeFileSync(dest, content, 'utf8');
+  if (shouldMakeExecutable(dest)) {
+    try {
+      fs.chmodSync(dest, 0o755);
+    } catch (err) {
+      // Ignore chmod errors on platforms that don't support it.
+    }
+  }
 }
 
 function stripDemo(targetDir) {
   removePath(path.join(targetDir, 'apps', 'web', 'src', 'modules', 'demo'));
-  removePath(path.join(targetDir, 'apps', 'server', 'internal', 'demo'));
+  removePath(path.join(targetDir, 'apps', 'server', 'internal', 'modules', 'demo'));
 
   updateFile(path.join(targetDir, 'apps', 'web', 'src', 'main.tsx'), (content) =>
     content.replace(/^\s*import ['"]\.\/modules\/demo['"];?\r?\n/m, '')
@@ -114,38 +122,71 @@ function stripDemo(targetDir) {
   updateFile(path.join(targetDir, 'apps', 'web', 'src', 'app.config.ts'), (content) =>
     content.replace(/,\s*['"]demo['"]/, '')
   );
-  updateFile(path.join(targetDir, 'config.yaml'), (content) =>
+  updateFile(path.join(targetDir, 'apps', 'server', 'config.yaml'), (content) =>
+    content.replace(/\r?\n\s*-\s*['"]demo['"]\s*/g, '')
+  );
+  updateFile(path.join(targetDir, 'apps', 'server', 'config.example.yaml'), (content) =>
     content.replace(/\r?\n\s*-\s*['"]demo['"]\s*/g, '')
   );
-  updateFile(path.join(targetDir, 'README.md'), (content) => {
-    let next = content.replace(
-      'Minimal Keystone platform shell (web + server) with a demo module.',
-      'Minimal Keystone platform shell (web + server).'
-    );
-    next = next.replace(/\n+Demo module:[\s\S]*$/m, '\n');
-    return `${next.trimEnd()}\n`;
-  });
-
-  const serverMainPath = path.join(targetDir, 'apps', 'server', 'main.go');
-  const serverMain = `package main
-
-import (
-\t"log"
-
-\t"github.com/robsuncn/keystone/server"
-)
-
-func main() {
-\tapp, err := server.New()
-\tif err != nil {
-\t\tlog.Fatalf("failed to initialize server: %v", err)
-\t}
-\tif err := app.Run(); err != nil {
-\t\tlog.Fatalf("server stopped: %v", err)
-\t}
+  updateFile(path.join(targetDir, 'README.md'), (content) =>
+    content.replace(/<!-- DEMO_START -->[\s\S]*?<!-- DEMO_END -->\s*/m, '')
+  );
+
+  const manifestPath = path.join(
+    targetDir,
+    'apps',
+    'server',
+    'internal',
+    'modules',
+    'manifest.go'
+  );
+  const manifest = `package modules
+
+// RegisterAll wires the module registry for this app.
+func RegisterAll() {
+\tClear()
 }
 `;
-  fs.writeFileSync(serverMainPath, serverMain, 'utf8');
+  fs.writeFileSync(manifestPath, manifest, 'utf8');
+}
+
+function applyConfigOptions(targetDir, options) {
+  const configFiles = [
+    path.join(targetDir, 'apps', 'server', 'config.yaml'),
+    path.join(targetDir, 'apps', 'server', 'config.example.yaml'),
+  ];
+
+  for (const filePath of configFiles) {
+    updateFile(filePath, (content) => applyYamlOptions(content, options));
+  }
+
+}
+
+function applyYamlOptions(content, options) {
+  let next = content;
+  if (options.db) {
+    next = updateYamlSectionValue(next, 'database', 'driver', options.db);
+    if (options.db === 'sqlite') {
+      next = updateYamlSectionValue(next, 'database', 'path', './data/keystone-local.db');
+    } else if (options.db === 'postgres') {
+      next = updateYamlSectionValue(next, 'database', 'path', '');
+    }
+  }
+  if (options.queue) {
+    next = updateYamlSectionValue(next, 'queue', 'driver', options.queue);
+  }
+  if (options.storage) {
+    next = updateYamlSectionValue(next, 'storage', 'driver', options.storage);
+  }
+  return next;
+}
+
+function updateYamlSectionValue(content, section, key, value) {
+  const pattern = new RegExp(`(^${section}:\\s*[\\s\\S]*?^\\s*${key}:\\s*\")([^\"]*)(\")`, 'm');
+  if (!pattern.test(content)) {
+    return content;
+  }
+  return content.replace(pattern, `$1${value}$3`);
 }
 
 function removePath(target) {
@@ -164,3 +205,101 @@ function updateFile(filePath, updater) {
     fs.writeFileSync(filePath, next, 'utf8');
   }
 }
+
+function shouldMakeExecutable(filePath) {
+  const normalized = String(filePath).replace(/\\/g, '/');
+  if (normalized.endsWith('.sh')) {
+    return true;
+  }
+  return normalized.includes('/.husky/');
+}
+
+function parseArgs(argv) {
+  const out = { demo: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--demo') {
+      out.demo = true;
+      continue;
+    }
+    if (arg === '--no-demo') {
+      out.demo = false;
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') {
+      out.help = true;
+      continue;
+    }
+
+    const profile = readValueOption(arg, argv, i, '--profile');
+    if (profile) {
+      out.profile = profile.value;
+      i += profile.skip;
+      continue;
+    }
+    const db = readValueOption(arg, argv, i, '--db');
+    if (db) {
+      out.db = db.value;
+      i += db.skip;
+      continue;
+    }
+    const queue = readValueOption(arg, argv, i, '--queue');
+    if (queue) {
+      out.queue = queue.value;
+      i += queue.skip;
+      continue;
+    }
+    const storage = readValueOption(arg, argv, i, '--storage');
+    if (storage) {
+      out.storage = storage.value;
+      i += storage.skip;
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      fail(`Unknown option: ${arg}`);
+    }
+    if (!out.target) {
+      out.target = arg;
+      continue;
+    }
+    fail('Too many arguments.');
+  }
+  return out;
+}
+
+function readValueOption(arg, argv, index, name) {
+  const prefix = `${name}=`;
+  if (arg.startsWith(prefix)) {
+    const value = arg.slice(prefix.length);
+    if (!value) {
+      fail(`Missing value for ${name}`);
+    }
+    return { value, skip: 0 };
+  }
+  if (arg === name) {
+    const value = argv[index + 1];
+    if (!value || value.startsWith('-')) {
+      fail(`Missing value for ${name}`);
+    }
+    return { value, skip: 1 };
+  }
+  return null;
+}
+
+function normalizeChoice(value, choices, label) {
+  if (!value) {
+    return null;
+  }
+  const normalized = String(value).trim().toLowerCase();
+  if (!choices.includes(normalized)) {
+    fail(`Invalid ${label}: ${value}`);
+  }
+  return normalized;
+}
+
+function fail(message) {
+  console.error(message);
+  console.error(usage);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robsun/create-keystone-app",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "publishConfig": {
     "access": "public"
   },

package/template/.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+pnpm lint-staged

package/template/.lintstagedrc.json

@@ -0,0 +1,5 @@
+{
+  "apps/web/**/*.{ts,tsx,js,jsx}": ["pnpm --filter web lint --fix", "prettier --write"],
+  "*.{json,yml,yaml,md}": ["prettier --write"],
+  "apps/server/**/*.go": ["gofmt -w"]
+}

package/template/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "endOfLine": "lf",
+  "arrowParens": "always"
+}

package/template/README.md

@@ -1,41 +1,63 @@
-# __RAW_NAME__
-Minimal Keystone platform shell (web + server) with a demo module.
+# __RAW_NAME__
 
-## Guides
-- `docs/CONVENTIONS.md` - module structure, routing/menu/permission rules, API patterns, and tests.
+Keystone 平台脚手架项目（Web + Server）。
 
-## Prereqs
-- Node 18+ and pnpm
-- Go 1.23+
-
-## Setup
-1) Install dependencies:
+## 快速开始
+1) 安装依赖
 ```bash
 pnpm install
 ```
 
-2) Start the Keystone server:
+2) 启动开发环境（前后端一起）
 ```bash
-pnpm server:dev
+pnpm dev
 ```
 
-3) Start the web shell:
+3) 单独启动
 ```bash
-pnpm dev
+pnpm server:dev
+pnpm web:dev
 ```
 
-## Project Structure
-- `apps/web/`: React + Vite shell and business modules (`src/modules/*`).
-- `apps/server/`: Go API and module wiring (demo routes by default).
-- `config.yaml`: runtime config (ports, database, queue, storage).
-
-Demo module:
+## 初始化后建议
+- 复制 `apps/web/.env.example` 为 `apps/web/.env`（Vite 会读取）。
+- 检查 `apps/server/config.yaml`（Go 运行配置）。
+- 需要外部依赖时参考 `docker-compose.yml`。
+- 建议阅读：`docs/CONVENTIONS.md`、`apps/web/README.md`、`apps/server/README.md`。
+
+## 常用命令
+- `pnpm dev`：跨平台开发启动（Air + Vite）。
+- `pnpm build`：构建并嵌入前端，生成可执行后端产物。
+- `pnpm test`：Web 类型检查 + Lint + Vitest + Go 测试。
+- `pnpm clean`：清理构建产物。
+
+## 目录结构
+- `apps/web/`：React + Vite 壳与业务模块（`src/modules/*`）。
+- `apps/server/`：Go API + 模块注册/迁移/种子数据（含 `config.yaml`）。
+- `apps/server/internal/frontend/`：嵌入式前端目录（`dist/`）。
+- `docs/CONVENTIONS.md`：项目规范与最佳实践。
+- `apps/web/README.md`：前端壳与模块开发说明。
+- `apps/server/README.md`：后端模块与运行说明。
+- `scripts/`：跨平台 dev/build/test/clean。
 
-- Menu: Demo Tasks
-- API: `/api/v1/demo/tasks`
+```
+.
+├─ apps/
+│  ├─ web/            # 前端壳与模块
+│  └─ server/         # Go 服务与模块
+├─ docs/              # 开发规范与说明
+└─ scripts/           # 跨平台脚本
+```
 
-Default login:
+<!-- DEMO_START -->
+## Demo 模块（可选）
+如果需要 Demo，可在创建时使用 `--demo` 或 `--profile=full`。
+- 菜单：Demo Tasks
+- API：`/api/v1/demo/tasks`
+- 权限：`demo:task:view`、`demo:task:manage`
+<!-- DEMO_END -->
 
+## 默认登录
 - Tenant code: `default`
 - Identifier: `admin`
 - Password: `Admin123!`

package/template/apps/server/.air.toml

@@ -0,0 +1,44 @@
+# Air - Live reload for Go apps
+# https://github.com/air-verse/air
+root = "."
+testdata_dir = "testdata"
+tmp_dir = "tmp"
+
+[build]
+  bin = "./tmp/main.exe"
+  cmd = "go build -o ./tmp/main.exe ./cmd/server"
+  delay = 1000
+  exclude_dir = ["assets", "tmp", "vendor", "testdata", "node_modules"]
+  exclude_file = []
+  exclude_regex = ["_test.go"]
+  exclude_unchanged = false
+  follow_symlink = false
+  include_dir = []
+  include_ext = ["go", "tpl", "tmpl", "html", "yaml", "yml"]
+  include_file = []
+  kill_delay = "0s"
+  log = "build-errors.log"
+  poll = false
+  poll_interval = 0
+  rerun = false
+  rerun_delay = 500
+  send_interrupt = false
+  stop_on_error = false
+
+[color]
+  app = ""
+  build = "yellow"
+  main = "magenta"
+  runner = "green"
+  watcher = "cyan"
+
+[log]
+  main_only = false
+  time = false
+
+[misc]
+  clean_on_exit = true
+
+[screen]
+  clear_on_rebuild = false
+  keep_scroll = true

package/template/apps/server/README.md

@@ -0,0 +1,27 @@
+# Server App
+
+## 定位
+- Go 后端应用入口在 `cmd/server/main.go`。
+- 业务模块统一放在 `internal/modules/*`。
+
+## 配置
+- 主配置：`apps/server/config.yaml`。
+- 模板配置：`apps/server/config.example.yaml`。
+- 环境变量：需通过 Shell/工具注入（服务端不读取 `.env`）。
+
+## 数据与存储
+- SQLite：`apps/server/data/keystone-local.db`。
+- 本地存储：`apps/server/storage/`（`storage.driver=local`）。
+
+## 模块开发
+1) 在 `internal/modules/<module>` 增加模块实现。
+2) 在 `internal/modules/manifest.go` 注册模块。
+3) 在 `apps/server/config.yaml` 的 `modules.enabled` 启用模块。
+
+## 嵌入式前端
+- 前端产物输出到 `internal/frontend/dist`。
+- Go 使用 `//go:embed` 直接嵌入静态资源。
+
+## 常用命令
+- 开发：`pnpm server:dev`
+- 测试：`go -C apps/server test ./...`