@robsun/create-keystone-app 0.2.15 → 0.4.1

package/template/scripts/check-help.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+const fs = require('fs')
+const path = require('path')
+
+const rootDir = path.resolve(__dirname, '..')
+const webSrcDir = path.join(rootDir, 'apps', 'web', 'src')
+const modulesDir = path.join(webSrcDir, 'modules')
+const appConfigPath = path.join(webSrcDir, 'app.config.ts')
+
+const stripBom = (content) =>
+  content.charCodeAt(0) === 0xfeff ? content.slice(1) : content
+const readFile = (filePath) => stripBom(fs.readFileSync(filePath, 'utf8'))
+
+const toRelative = (filePath) => path.relative(rootDir, filePath)
+
+const walk = (dir, visitor) => {
+  if (!fs.existsSync(dir)) {
+    return
+  }
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      walk(fullPath, visitor)
+    } else {
+      visitor(fullPath, entry)
+    }
+  }
+}
+
+const addKey = (map, key, filePath) => {
+  if (!map.has(key)) {
+    map.set(key, new Set())
+  }
+  map.get(key).add(filePath)
+}
+
+const parseSupportedLocales = () => {
+  const fallback = ['zh-CN', 'en-US']
+  if (!fs.existsSync(appConfigPath)) {
+    return fallback
+  }
+  const content = readFile(appConfigPath)
+  const match = content.match(/supportedLocales\s*:\s*\[([\s\S]*?)\]/m)
+  if (!match) {
+    return fallback
+  }
+  const values = []
+  const regex = /['"]([^'"]+)['"]/g
+  let current = regex.exec(match[1])
+  while (current) {
+    values.push(current[1])
+    current = regex.exec(match[1])
+  }
+  if (values.length === 0) {
+    return fallback
+  }
+  return Array.from(new Set(values))
+}
+
+const extractLocaleFromPath = (filePath, locales) => {
+  const normalized = filePath.split(path.sep).join('/')
+  const marker = '/help/'
+  const idx = normalized.lastIndexOf(marker)
+  if (idx < 0) {
+    return null
+  }
+  const rest = normalized.slice(idx + marker.length)
+  const locale = rest.split('/')[0]
+  if (!locale || !locales.includes(locale)) {
+    return null
+  }
+  return locale
+}
+
+const parseEnabledModules = () => {
+  const fallback = ['keystone']
+  if (!fs.existsSync(appConfigPath)) {
+    return fallback
+  }
+  const content = readFile(appConfigPath)
+  const match = content.match(/modules\s*:\s*\{[\s\S]*?enabled\s*:\s*\[([\s\S]*?)\]/m)
+  if (!match) {
+    return fallback
+  }
+  const items = []
+  const regex = /['"]([^'"]+)['"]/g
+  let current = regex.exec(match[1])
+  while (current) {
+    items.push(current[1])
+    current = regex.exec(match[1])
+  }
+  if (items.length === 0) {
+    return fallback
+  }
+  return Array.from(new Set(items))
+}
+
+const resolveModuleName = (filePath) => {
+  const normalized = filePath.split(path.sep).join('/')
+  const marker = '/modules/'
+  const idx = normalized.indexOf(marker)
+  if (idx < 0) {
+    return null
+  }
+  const rest = normalized.slice(idx + marker.length)
+  const parts = rest.split('/')
+  if (parts.length === 0) {
+    return null
+  }
+  return parts[0]
+}
+
+const collectRouteHelpKeys = (dir, enabledModules) => {
+  const result = new Map()
+  const routeFileRegex = /\.(ts|tsx)$/
+  const helpKeyRegex = /helpKey\s*:\s*['"]([^'"]+)['"]/g
+  walk(dir, (filePath) => {
+    if (!routeFileRegex.test(filePath)) {
+      return
+    }
+    const moduleName = resolveModuleName(filePath)
+    if (moduleName && enabledModules && !enabledModules.has(moduleName)) {
+      return
+    }
+    const content = readFile(filePath)
+    helpKeyRegex.lastIndex = 0
+    let match = helpKeyRegex.exec(content)
+    while (match) {
+      addKey(result, match[1], filePath)
+      match = helpKeyRegex.exec(content)
+    }
+  })
+  return result
+}
+
+const extractFrontmatter = (content) => {
+  if (!content.startsWith('---')) {
+    return null
+  }
+  const match = content.match(/^---\s*[\r\n]+([\s\S]*?)\r?\n---\s*/)
+  if (!match) {
+    return null
+  }
+  return match[1]
+}
+
+const collectDocHelpKeys = (dir, locales) => {
+  const result = new Map()
+  locales.forEach((locale) => result.set(locale, new Map()))
+  const warnings = []
+  walk(dir, (filePath) => {
+    if (!filePath.endsWith('.md')) {
+      return
+    }
+    const normalized = filePath.split(path.sep).join('/')
+    if (!normalized.includes('/help/')) {
+      return
+    }
+    const locale = extractLocaleFromPath(filePath, locales)
+    if (!locale) {
+      warnings.push(`Unknown locale path ${toRelative(filePath)}`)
+      return
+    }
+    const content = readFile(filePath)
+    const frontmatter = extractFrontmatter(content)
+    if (!frontmatter) {
+      return
+    }
+    const match = frontmatter.match(/^\s*helpKey\s*:\s*["']?([^"'\n]+)["']?/m)
+    if (!match) {
+      warnings.push(`Missing helpKey in ${toRelative(filePath)}`)
+      return
+    }
+    const bucket = result.get(locale)
+    if (!bucket) {
+      return
+    }
+    addKey(bucket, match[1], filePath)
+  })
+  return { keys: result, warnings }
+}
+
+try {
+  if (!fs.existsSync(modulesDir)) {
+    throw new Error('apps/web/src/modules not found')
+  }
+
+  const locales = parseSupportedLocales()
+  const enabledModules = new Set(parseEnabledModules())
+  const routeKeys = collectRouteHelpKeys(modulesDir, enabledModules)
+  const { keys: docKeys, warnings } = collectDocHelpKeys(webSrcDir, locales)
+
+  if (warnings.length > 0) {
+    console.warn('Help docs warnings:')
+    warnings.forEach((warning) => console.warn(`  - ${warning}`))
+  }
+
+  const missingDocs = []
+  for (const [key, sources] of routeKeys.entries()) {
+    for (const locale of locales) {
+      const bucket = docKeys.get(locale)
+      if (!bucket || !bucket.has(key)) {
+        missingDocs.push({ key, locale, sources })
+      }
+    }
+  }
+
+  const duplicateDocs = []
+  for (const [locale, bucket] of docKeys.entries()) {
+    for (const [key, sources] of bucket.entries()) {
+      if (sources.size > 1) {
+        duplicateDocs.push({ key, locale, sources })
+      }
+    }
+  }
+
+  if (missingDocs.length === 0 && duplicateDocs.length === 0) {
+    console.log('Help docs are in sync.')
+    process.exit(0)
+  }
+
+  console.error('Help documentation check failed:')
+  if (missingDocs.length > 0) {
+    console.error('\nMissing help docs for route helpKey:')
+    missingDocs.forEach(({ key, locale, sources }) => {
+      console.error(`  - ${key} (${locale})`)
+      sources.forEach((source) => {
+        console.error(`    route: ${toRelative(source)}`)
+      })
+    })
+  }
+
+  if (duplicateDocs.length > 0) {
+    console.error('\nDuplicate helpKey entries found:')
+    duplicateDocs.forEach(({ key, locale, sources }) => {
+      console.error(`  - ${key} (${locale})`)
+      sources.forEach((source) => {
+        console.error(`    doc: ${toRelative(source)}`)
+      })
+    })
+  }
+
+  process.exit(1)
+} catch (err) {
+  console.error('Failed to check help docs:')
+  console.error(err instanceof Error ? err.message : String(err))
+  process.exit(2)
+}

package/template/scripts/compress-assets.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+const fs = require('fs')
+const path = require('path')
+const zlib = require('zlib')
+
+const rootDir = path.resolve(__dirname, '..')
+const distDir = path.join(rootDir, 'apps', 'server', 'internal', 'frontend', 'dist')
+
+const compressibleExts = new Set([
+  '.js',
+  '.mjs',
+  '.css',
+  '.html',
+  '.json',
+  '.svg',
+  '.txt',
+  '.xml',
+  '.map',
+])
+
+const skipExts = new Set([
+  '.br',
+  '.gz',
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.webp',
+  '.woff',
+  '.woff2',
+  '.ttf',
+  '.eot',
+  '.ico',
+])
+
+if (!fs.existsSync(distDir)) {
+  console.error(`[compress-assets] dist not found: ${distDir}`)
+  process.exit(1)
+}
+
+const files = []
+walk(distDir, (filePath) => files.push(filePath))
+
+const brotliOptions = {
+  params: {
+    [zlib.constants.BROTLI_PARAM_QUALITY]: 11,
+    [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
+  },
+}
+
+let compressed = 0
+for (const filePath of files) {
+  const ext = path.extname(filePath).toLowerCase()
+  if (skipExts.has(ext)) {
+    continue
+  }
+  if (!compressibleExts.has(ext)) {
+    continue
+  }
+  const data = fs.readFileSync(filePath)
+  const brPath = `${filePath}.br`
+  const gzPath = `${filePath}.gz`
+
+  if (!fs.existsSync(brPath)) {
+    const br = zlib.brotliCompressSync(data, brotliOptions)
+    fs.writeFileSync(brPath, br)
+  }
+  if (!fs.existsSync(gzPath)) {
+    const gz = zlib.gzipSync(data, { level: 9 })
+    fs.writeFileSync(gzPath, gz)
+  }
+  compressed += 1
+}
+
+console.log(`[compress-assets] precompressed ${compressed} asset(s)`)
+
+function walk(dir, onFile) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      walk(fullPath, onFile)
+      continue
+    }
+    if (entry.isFile()) {
+      onFile(fullPath)
+    }
+  }
+}

package/template/scripts/test.bat

@@ -22,6 +22,19 @@ if errorlevel 1 (
 echo [OK] Go found
 
 echo.
+set "USE_LOCAL_KEYSTONE=0"
+set "ADDED_KEYSTONE_REPLACE=0"
+set "KEYSTONE_ROOT="
+set "SCRIPT_DIR=%~dp0"
+set "KEYSTONE_CANDIDATE=%SCRIPT_DIR%..\..\..\.."
+for %%I in ("%KEYSTONE_CANDIDATE%") do set "KEYSTONE_CANDIDATE=%%~fI"
+if exist "%KEYSTONE_CANDIDATE%\go.mod" (
+    findstr /C:"module github.com/robsuncn/keystone" "%KEYSTONE_CANDIDATE%\go.mod" >nul 2>&1
+    if not errorlevel 1 (
+        set "KEYSTONE_ROOT=%KEYSTONE_CANDIDATE%"
+        set "USE_LOCAL_KEYSTONE=1"
+    )
+)
 echo Running tests...
 echo.
 
@@ -70,6 +83,13 @@ echo ----------------------------------------
 echo Backend Tests
 echo ----------------------------------------
 cd apps\server
+if "%USE_LOCAL_KEYSTONE%"=="1" (
+    findstr /C:"replace github.com/robsuncn/keystone" go.mod >nul 2>&1
+    if errorlevel 1 (
+        go mod edit -replace github.com/robsuncn/keystone=%KEYSTONE_ROOT%
+        set "ADDED_KEYSTONE_REPLACE=1"
+    )
+)
 go vet ./...
 if errorlevel 1 (
     echo [FAIL] Backend vet failed
@@ -84,6 +104,9 @@ if errorlevel 1 (
 ) else (
     echo [OK] Backend tests passed
 )
+if "%ADDED_KEYSTONE_REPLACE%"=="1" (
+    go mod edit -dropreplace github.com/robsuncn/keystone
+)
 cd ..\..
 
 echo.

package/template/scripts/test.sh

@@ -23,6 +23,15 @@ if ! command -v go &> /dev/null; then
 fi
 echo -e "${GREEN}[OK]${NC} Go found"
 
+USE_LOCAL_KEYSTONE=0
+ADDED_KEYSTONE_REPLACE=0
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+KEYSTONE_CANDIDATE="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+if [ -f "$KEYSTONE_CANDIDATE/go.mod" ] && grep -q "module github.com/robsuncn/keystone" "$KEYSTONE_CANDIDATE/go.mod"; then
+  KEYSTONE_ROOT="$KEYSTONE_CANDIDATE"
+  USE_LOCAL_KEYSTONE=1
+fi
+
 echo ""
 echo "Running tests..."
 echo ""
@@ -70,6 +79,10 @@ echo "----------------------------------------"
 echo "Backend Tests"
 echo "----------------------------------------"
 cd apps/server
+if [ "$USE_LOCAL_KEYSTONE" -eq 1 ] && ! grep -q "replace github.com/robsuncn/keystone" go.mod; then
+  go mod edit -replace github.com/robsuncn/keystone="$KEYSTONE_ROOT"
+  ADDED_KEYSTONE_REPLACE=1
+fi
 if go vet ./...; then
   echo -e "${GREEN}[OK]${NC} Backend vet passed"
 else
@@ -83,6 +96,9 @@ else
   echo -e "${RED}[FAIL]${NC} Backend tests failed"
   FAILED=1
 fi
+if [ "$ADDED_KEYSTONE_REPLACE" -eq 1 ]; then
+  go mod edit -dropreplace github.com/robsuncn/keystone
+fi
 cd ../..
 
 echo ""

package/template/.claude/skills/keystone-dev/SKILL.md

@@ -1,90 +0,0 @@
----
-name: keystone-dev
-description: Build and extend Keystone modules and features (frontend + backend) with consistent structure, permissions, i18n, help docs, and OpenAPI contracts. Use when adding new modules, routes, APIs, migrations, or updating the scaffold template in this repo.
----
-# Keystone Dev
-
-## Core workflow
-1) Identify the target app root: this repo's scaffold template or a generated app.
-2) Create or update the module using the generator or the Example module as the baseline.
-3) Add or update tests for new behavior before finishing implementation.
-4) Wire frontend routes, menus, permissions, help docs, and i18n.
-5) Wire backend module registration, permissions, i18n, routes, migrations, and seeds.
-6) Update contracts and types when APIs change.
-7) Run the relevant checks before finishing.
-
-## Module creation
-- Use the generator when possible:
-  ```bash
-  pnpm create:module <module-name> [options]
-
-  Options:
-    --frontend-only    Only generate the frontend module
-    --backend-only     Only generate the backend module
-    --with-crud        Include CRUD example code
-    --with-approval    Include approval workflow code (implies --with-crud)
-    --skip-register    Skip auto registration steps
-  ```
-- Keep module names in kebab-case and consistent across frontend, backend, and permissions.
-- Prefer copying the Example module if you need a manual template.
-
-## Approval workflow (--with-approval)
-When using `--with-approval`, the generator creates:
-- **Backend**: `domain/service/approval.go` (Submit/Cancel), `domain/service/callback.go` (OnApproved/OnRejected), `api/handler/approval.go`
-- **Frontend**: `components/ApprovalActions.tsx` with status tags and action buttons
-- **Model updates**: Adds `draft/pending/approved/rejected` statuses and `ApprovalInstanceID` field
-- **I18n**: Approval-related translations in both languages
-- **Routes**: `POST /:id/submit` and `POST /:id/cancel` endpoints
-
-After generation, register the approval callback in `module.go`:
-```go
-func (m *Module) RegisterApprovalCallback(reg *approval.CallbackRegistry) error {
-    return reg.Register(service.ApprovalBusinessType, service.New{Pascal}ApprovalCallback(m.repo))
-}
-```
-
-## Frontend checklist (apps/web)
-- Add module at `apps/web/src/modules/<module>`.
-- In `index.ts`, call `loadModuleLocales` and `registerModule`.
-- In `routes.tsx`, set `handle.menu`, `handle.permission`, `handle.helpKey`, and use `labelKey`/`breadcrumbKey` for i18n.
-- Add help docs under `apps/web/src/modules/<module>/help/**` and keep `helpKey` aligned.
-- Add locale files in `apps/web/src/modules/<module>/locales/zh-CN/*.json` and `en-US/*.json`.
-
-## Backend checklist (apps/server)
-- Add module at `apps/server/internal/modules/<module>`.
-- Implement the Module interface in `module.go` and keep DDD layering (`api/`, `domain/`, `infra/`, `bootstrap/`).
-- Register permissions with `CreateMenuI18n`/`CreateActionI18n` using `{module}:{resource}:{action}`.
-- Register i18n in `RegisterI18n()` and provide `i18n/keys.go` + `i18n/locales/*.json`.
-- Register the module in `apps/server/internal/modules/manifest.go`.
-- Enable the module in `apps/server/config.yaml` (scaffold apps).
-
-## Testing development
-- Backend: add unit tests in package folders (`*_test.go`) or in `tests/unit`/`tests/integration`/`tests/perf`.
-- Frontend: add component or page tests alongside modules (e.g. `*.test.tsx`).
-- Cover critical paths first (permissions, validation, and data mutations).
-
-## Contracts and API types
-- Add or update OpenAPI specs under `contracts/NNN-<name>/`.
-- Update `CONTRACT_MAPPING` in `scripts/generate-api-types.mjs` for new contract folders.
-- Run `pnpm contracts:sync` and `pnpm -C packages/keystone-contracts generate` after contract changes.
-
-## Quality gates
-- For scaffold changes: `pnpm -C packages/create-keystone-app/template test`.
-- For contracts: `pnpm contracts:check` and `pnpm -C packages/keystone-contracts typecheck`.
-- For backend changes: `go test ./...`.
-
-## Key references
-- `packages/create-keystone-app/template/docs/CONVENTIONS.md`
-- `packages/create-keystone-app/template/docs/CODE_STYLE.md`
-- `packages/create-keystone-app/template/docs/I18N.md`
-- `packages/create-keystone-app/template/apps/web/src/modules/example`
-- `packages/create-keystone-app/template/apps/server/internal/modules/example`
-
-## Advanced templates (in `references/`)
-- `TEMPLATES.md` - 基础 CRUD + 高级业务模板（多实体、审批流、导入导出、前端高级组件）
-- `ADVANCED_PATTERNS.md` - 高级开发模式（跨模块依赖、状态机、缓存、并发控制、任务编排）
-- `PATTERNS.md` - 后端开发模式（分页、事务、批量、软删除、预加载、审批集成）
-- `CHECKLIST.md` - 模块开发完整自检清单
-- `GOTCHAS.md` - 常见陷阱与解决方案
-- `CAPABILITIES.md` - 平台完整能力清单
-- `TESTING.md` - 测试开发指南