@robsun/create-keystone-app 0.1.12 → 0.1.13

package/bin/create-keystone-app.js

@@ -114,6 +114,9 @@ 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) =>
+    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.',

package/package.json

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

package/template/README.md

@@ -1,6 +1,9 @@
 # __RAW_NAME__
 Minimal Keystone platform shell (web + server) with a demo module.
 
+## Guides
+- `docs/CONVENTIONS.md` - module structure, routing/menu/permission rules, API patterns, and tests.
+
 ## Prereqs
 - Node 18+ and pnpm
 - Go 1.23+
@@ -21,6 +24,11 @@ pnpm server:dev
 pnpm 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:
 
 - Menu: Demo Tasks

package/template/config.yaml

@@ -1,13 +1,51 @@
 server:
   port: "8080"
   mode: "debug"
+  swagger_enabled: true
+
+modules:
+  enabled:
+    - "keystone"
+    - "demo"
+
 database:
   driver: "sqlite"
+  host: "localhost"
+  port: "5432"
+  user: "keystone"
+  password: "keystone"
+  dbname: "keystone"
+  sslmode: "disable"
   path: "./data/keystone-local.db"
+
 jwt:
   secret: "change-me-in-prod"
+  access_token_ttl: 2
+  refresh_token_ttl: 168
+
+approval:
+  callback_secret: ""
+
+pdf:
+  font_path: ""
+
 queue:
   driver: "memory"
+  buffer: 200
+  redis:
+    addr: "localhost:6379"
+    password: ""
+    db: 0
+    key: "keystone:jobs"
+
 storage:
   driver: "local"
-  local_dir: "./storage"
+  local_dir: "./storage"
+  base_url: ""
+  s3:
+    endpoint: ""
+    region: ""
+    bucket: ""
+    access_key: ""
+    secret_key: ""
+    use_ssl: true

package/template/docs/CONVENTIONS.md

@@ -0,0 +1,134 @@
+# Keystone App Conventions
+
+## Goals
+- Keep modules predictable across web and server.
+- Keep routing, menus, permissions, and help content in one place.
+- Follow the tradeflow app patterns for structure and naming.
+
+## Project Layout
+- `apps/web/`: React + Vite app.
+- `apps/server/`: Go API app.
+- `apps/web/src/app.config.ts`: web runtime config (modules, branding, approval).
+- `config.yaml`: server runtime config (modules, database, queue, storage).
+
+## Frontend Module Rules
+- Each business module lives in `apps/web/src/modules/<module>`.
+- `index.ts` must register the module:
+  - `registerModule({ name, routes, i18n })`.
+- `routes.tsx` owns menu/breadcrumb/permission metadata via `handle`.
+- Pages go in `pages/`, shared UI in `components/`, API calls in `services/`, types in `types.ts`, shared state in `stores/`.
+- Lazy-load page components and wrap with `Suspense`.
+
+Example module entry:
+```ts
+import { registerModule } from '@robsun/keystone-web-core'
+import { orderRoutes } from './routes'
+
+registerModule({ name: 'orders', routes: orderRoutes })
+```
+
+Example route meta:
+```tsx
+{
+  path: 'orders',
+  element: <Outlet />,
+  handle: {
+    menu: { label: 'Orders', icon: <FileTextOutlined />, permission: 'sales:order:view' },
+    breadcrumb: 'Orders',
+    permission: 'sales:order:view',
+    helpKey: 'sales/orders',
+  },
+}
+```
+
+## Permissions and Menu Rules
+- Permission format: `domain:resource:action` (wildcards allowed, e.g. `inventory:*:*`).
+- Menus are derived from `handle.menu`. If a route should not appear, omit `handle.menu`.
+- Breadcrumbs are derived from `handle.breadcrumb`.
+- Use `handle.menu.order` to control menu ordering when needed.
+
+## Help Docs
+- Store help markdown under `apps/web/src/modules/<module>/help/**`.
+- Use frontmatter keys: `helpKey`, `title`, `description`, `category`, `tags`, `relatedKeys`.
+- Route `handle.helpKey` must match the markdown `helpKey`.
+- Enable app help by pointing Vite to your help folder (`helpDir` in `vite.config.ts`).
+
+Frontmatter example:
+```md
+---
+helpKey: "inventory/warehouses"
+title: "Warehouse Management"
+description: "Manage warehouses and locations."
+category: "inventory"
+tags: ["warehouse", "location"]
+relatedKeys: ["inventory/stock"]
+---
+```
+
+## API and Services
+- Use `api` from `@robsun/keystone-web-core` for HTTP.
+- If your API base path changes, call `setApiBaseUrl` once at startup.
+- Keep API calls in `services/*.ts`, return typed data, and let pages handle UI state.
+- For paginated endpoints, map `page`/`page_size` (server) to `page`/`pageSize` (web).
+
+Example service:
+```ts
+import { api, type ApiResponse, type PaginatedData } from '@robsun/keystone-web-core'
+
+export async function listItems(page = 1, pageSize = 20) {
+  const { data } = await api.get<ApiResponse<PaginatedData<Item>>>('/items', {
+    params: { page, page_size: pageSize },
+  })
+  return data.data
+}
+```
+
+## State
+- Use local state for single pages.
+- Use zustand stores for shared state or cross-page flows.
+- Store shape should include `loading`, `error`, `filters`, and a `fetch` method.
+
+## Naming
+- Page components: `*Page.tsx` (e.g. `InventoryListPage.tsx`).
+- API modules: `services/api.ts` or `services/<feature>.ts`.
+- Store modules: `stores/*Store.ts` or `stores/use*Store.ts`.
+- Domain types: `types.ts` (export interfaces and enums).
+
+## Backend Module Rules
+For production modules, mirror this layout:
+```
+apps/server/internal/modules/<module>/
+  module.go
+  api/routes/
+  api/handler/
+  domain/service/
+  infra/repository/
+  bootstrap/migrations/
+  bootstrap/seeds/
+```
+
+Module interface (simplified):
+```go
+type Module interface {
+    Name() string
+    RegisterRoutes(rg *gin.RouterGroup)
+    RegisterModels() []interface{}
+    RegisterPermissions(reg *permissions.Registry) error
+    RegisterJobs(reg *jobs.Registry) error
+    Migrate(db *gorm.DB) error
+    Seed(db *gorm.DB) error
+}
+```
+
+Register modules and enable them via `config.yaml` (`modules.enabled`).
+Keep the enabled list aligned with `app.config.ts`.
+
+## Routing and Responses (Server)
+- Mount API under `/api/v1`.
+- Use auth, rbac, and tenant guards consistently across module routes.
+- Use `github.com/robsuncn/keystone/api/response` helpers for JSON responses.
+
+## Testing
+- Web: `apps/web/tests/{unit,component,e2e,perf}` with `*.test.ts(x)`.
+- Server: `apps/server/tests/{unit,integration,e2e,fixtures}` with `*_test.go`.
+- Run `go test ./...` for server changes; add a web test runner when needed.