cabloy 5.1.49 → 5.1.51

package/cabloy-docs/fullstack/introduction.md

@@ -0,0 +1,69 @@
+# Fullstack Introduction
+
+Cabloy is a fullstack framework built around a single source tree where backend and frontend development stay close enough for code sharing, workflow reuse, and AI-assisted implementation.
+
+## Shared architecture
+
+- **Vona** provides the backend framework capabilities.
+- **Zova** provides the frontend framework capabilities.
+- The root repository coordinates the two through shared scripts, shared terminology, and a shared release story.
+
+In the current monorepo root, the main command entrypoints are:
+
+- `npm run vona`
+- `npm run zova`
+- `npm run dev`
+- `npm run build`
+- `npm run test`
+- `npm run tsc`
+
+These are defined in the root `package.json` and should be the first place an agent or contributor checks before inventing a custom workflow.
+
+## Why the monorepo matters for workflow selection
+
+The monorepo makes it possible to answer cross-stack questions from source rather than memory, for example:
+
+- how frontend routes and components are reflected back into backend type hints
+- how backend OpenAPI and DTO output feeds frontend SDK generation
+- how edition-specific scripts differ between Cabloy Basic and Cabloy Start
+- how Vona and Zova CLI commands can be reused instead of writing scaffolding manually
+
+## Technology Stack
+
+### General
+
+| Package    | Version   |
+| ---------- | --------- |
+| TypeScript | `^5.9.3`  |
+| Zod        | `^4.3.6`  |
+
+### Backend (Vona)
+
+| Package                            | Version   |
+| ---------------------------------- | --------- |
+| Koa                                | `^3.2.0`  |
+| Knex                               | `^3.2.9`  |
+| Redis Client (`ioredis`)           | `^5.10.1` |
+| SQLite Driver (`better-sqlite3`)   | `^12.9.0` |
+
+### Frontend (Zova)
+
+| Package          | Version     |
+| ---------------- | ----------- |
+| Vue              | `^3.5.32`   |
+| Vite             | `^8.0.14`   |
+| Quasar           | `^2.19.3`   |
+| TanStack Query   | `^5.100.10` |
+| TanStack Form    | `^1.32.0`   |
+| TanStack Table   | `^8.21.3`   |
+
+### Edition-specific UI Stack
+
+- **Cabloy Basic**: DaisyUI + Tailwind CSS
+- **Cabloy Start**: Vuetify
+
+## Common-first, edition-aware
+
+Most framework concepts are shared across Cabloy Basic and Cabloy Start. The new documentation prefers a common-first explanation, then adds edition-specific notes only where the repos intentionally diverge.
+
+Use the [Editions Overview](/editions/overview) page whenever a task depends on UI library, module composition, or private-value project boundaries.

package/cabloy-docs/fullstack/openapi-to-sdk.md

@@ -0,0 +1,116 @@
+# Backend OpenAPI to Frontend SDK
+
+This page turns one of Cabloy’s most important fullstack collaboration paths into an explicit guide.
+
+## Why this path matters
+
+Cabloy’s fullstack productivity depends heavily on a contract loop:
+
+1. Vona emits backend API metadata through Swagger/OpenAPI
+2. Zova consumes that metadata to generate frontend SDKs and schema-aware helpers
+3. frontend pages, models, and services build on those generated contracts instead of re-declaring everything manually
+
+This is one of the strongest AI-leverage paths in the repo because it reduces duplicated type work and keeps backend/frontend coordination closer to source truth.
+
+## The contract loop in practical terms
+
+A useful split is:
+
+- backend docs define the authoring side of the contract
+- fullstack docs define the bridge from emitted contract to generated SDK
+- frontend docs define the consumption side of the generated contract
+
+That means this page is the fullstack contract-bridge page, not the backend authoring page and not the frontend usage page.
+
+## Backend side: Vona emits the contract
+
+On the backend side, OpenAPI metadata is driven by:
+
+- controller argument and return contracts
+- DTO and entity field definitions
+- validation rules and `v` helpers
+- `a-openapi` configuration
+
+For the deeper backend perspective, see:
+
+- [Controller Guide](/backend/controller-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [Validation Guide](/backend/validation-guide)
+- [DTO Infer and Generation](/backend/dto-infer-generation)
+
+## Frontend side: Zova consumes the contract
+
+On the frontend side, the generated-contract path typically includes:
+
+- OpenAPI configuration
+- SDK generation
+- API services or schema-driven helpers based on the generated output
+
+For the deeper frontend perspective, see:
+
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [Server Data](/frontend/server-data)
+- [API Guide](/frontend/api-guide)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [SDK Guide](/frontend/sdk-guide)
+
+## Cabloy Basic workflow
+
+In the current public monorepo, Basic-specific Zova flavors include:
+
+- `cabloyBasicAdmin`
+- `cabloyBasicWeb`
+
+Representative frontend-side contract-generation commands include:
+
+```bash
+npm run zova :openapi:config demo-student
+npm run zova :openapi:generate demo-student
+cd zova && npm run build:rest:cabloyBasicAdmin
+cd zova && npm run build:rest:cabloyBasicWeb
+```
+
+A practical contract-loop sequence is:
+
+1. author or change the backend contract
+2. emit or inspect backend OpenAPI output
+3. configure frontend module ownership if needed
+4. generate module-level OpenAPI SDK output
+5. run the rest build for the active Basic flavor when needed
+6. consume the generated contract from frontend code instead of re-declaring it manually
+
+A practical responsibility split is:
+
+- project-level OpenAPI config decides where the backend Swagger/OpenAPI source comes from
+- module-level OpenAPI config decides which generated contract slice belongs to which frontend module
+
+A practical regeneration rule is:
+
+- if the backend contract changed, prefer regenerating the SDK/rest layer before hand-editing frontend request code
+
+## Cabloy Start workflow
+
+In the sibling private Start repo, the same collaboration idea applies, but the frontend flavor names differ.
+
+Representative Start-specific flavors include:
+
+- `cabloyStartAdmin`
+- `cabloyStartWeb`
+
+Before documenting or automating this path for Start, confirm:
+
+1. the `__CABLOY_START__` marker
+2. the Start repo’s `package.json`
+3. the exact frontend flavor names and generated output paths
+
+## Implementation checks for backend-to-frontend contract changes
+
+When changing a backend API contract, ask:
+
+1. does OpenAPI output change?
+2. does the frontend SDK or schema layer need regeneration?
+3. is the active edition Basic or Start?
+4. is the right next step to regenerate contracts instead of hand-editing frontend request code?
+5. is the current task on the backend authoring side, the bridge step, or the frontend consumption side?
+
+That keeps the backend/frontend contract loop coherent.

package/cabloy-docs/fullstack/quickstart.md

@@ -0,0 +1,86 @@
+# Fullstack Quickstart
+
+This guide explains the fastest way to start a Cabloy fullstack project.
+
+## 1. Prerequisites
+
+Before creating a new Cabloy project, make sure your environment has:
+
+| Name         | Version     |
+| ------------ | ----------- |
+| `pnpm`       | `>=10.19.0` |
+| `Node.js`    | `>=24.4.0`  |
+| `Redis`      | `>=7.2.6`   |
+| `SQLite3`    | `Built-in`  |
+| `MySQL`      | `>=8`       |
+| `PostgreSQL` | `>=16`      |
+
+- `Redis`: powers queue, schedule, startup, broadcast, caching, two-layer cache, and redlock
+- `SQLite3`: if you use `better-sqlite3`, set up `node-gyp` before installing dependencies
+
+## 2. Create a new project
+
+```bash
+npm create cabloy
+```
+
+The generated project already includes `CLAUDE.md` and the `.claude/` workspace assets. Open this project in Claude Code and start coding immediately with project-specific guidance.
+
+## 3. Start the backend
+
+```bash
+npm run dev
+```
+
+- Web: http://localhost:7102/
+- Admin: http://localhost:7102/admin/
+
+## 4. Start the frontend for your edition
+
+### Cabloy Basic
+
+```bash
+npm run dev:zova:admin # http://localhost:9000/admin/
+npm run dev:zova:web   # http://localhost:9000/
+```
+
+### Cabloy Start
+
+Use the frontend commands provided by your project edition. Do not assume the Cabloy Basic flavor names apply to Cabloy Start.
+
+If you are not sure which edition you are using, read:
+
+- [Edition Detection](/editions/detection)
+- [Cabloy Basic](/editions/cabloy-basic)
+- [Cabloy Start](/editions/cabloy-start)
+
+## 5. Upgrade an existing project
+
+```bash
+npm run upgrade
+```
+
+## 6. Next steps for framework-aware development
+
+If you are contributing to framework-aware workflows or using Cabloy CLI generation directly, prefer CLI-backed generation over manual scaffolding.
+
+Instead of creating framework files by hand, start with:
+
+```bash
+npm run vona :create
+npm run zova :create
+```
+
+Then narrow into the specific command family you need.
+
+## 7. Shared verification commands for deeper workflow checks
+
+If you are validating framework-aware changes or a broader workflow, use the shared project scripts before declaring a workflow correct:
+
+```bash
+npm run tsc
+npm run test
+npm run build
+```
+
+Choose more targeted checks when only one area is affected, but treat these scripts as the shared reference surface.

package/cabloy-docs/fullstack/vona-zova-integration.md

@@ -0,0 +1,86 @@
+# Fullstack Vona + Zova Integration
+
+This guide explains the current monorepo-native workflow for integrating Vona and Zova.
+
+## Why the workflow looks different in the monorepo
+
+Earlier standalone-repo workflows often described integrating Zova by cloning a separate repository and copying its built output into Vona manually.
+
+That is not the preferred Cabloy workflow.
+
+In the current monorepo:
+
+- Vona and Zova already live in the same source tree
+- the root repository already exposes shared scripts for both sides
+- edition differences should be handled explicitly rather than through ad hoc path replacement
+
+## Core integration model
+
+Cabloy uses a frontend-backend separation architecture:
+
+- Vona provides the backend runtime
+- Zova provides the frontend application
+- generated or built frontend output is consumed by the backend-side fullstack flow
+- type sharing is coordinated through OpenAPI, generated SDKs, and frontend-generated route/component typing
+
+## Cabloy Basic
+
+In Cabloy Basic, the root repository already exposes these shared entrypoints:
+
+```bash
+npm run dev
+npm run dev:zova:admin
+npm run dev:zova:web
+npm run build
+npm run build:zova
+```
+
+The relevant Zova flavors in this repository include:
+
+- `cabloyBasicAdmin`
+- `cabloyBasicWeb`
+
+The frontend-side REST/type build flows include:
+
+```bash
+cd zova && npm run build:rest:cabloyBasicAdmin
+cd zova && npm run build:rest:cabloyBasicWeb
+```
+
+## Cabloy Start
+
+Cabloy Start is a sibling private repository rather than a subdirectory here, but the same integration idea applies.
+
+Its root script surface uses Start-specific flavors such as:
+
+- `cabloyStartAdmin`
+- `cabloyStartWeb`
+
+Because Start differs in UI stack and module composition, do not reuse Basic integration examples without first confirming:
+
+1. the `__CABLOY_START__` marker
+2. the Start repo’s `package.json`
+3. the exact Zova flavor names and generated output paths used there
+
+## Recommended integration workflow
+
+### 1. Detect the edition
+
+- `__CABLOY_BASIC__` → use Basic examples from this repo
+- `__CABLOY_START__` → verify the sibling Start repo scripts before using examples
+
+### 2. Start from root scripts
+
+Use the root `package.json` as the first workflow surface.
+
+### 3. Use Zova build and REST generation deliberately
+
+For frontend builds and type generation, inspect the relevant Zova flavor scripts instead of hardcoding copy paths or ad hoc integration steps.
+
+### 4. Verify both sides together
+
+For meaningful fullstack changes, verify:
+
+- backend dev/build/test flow
+- frontend dev/build/type generation flow
+- the edition-specific flavor you actually targeted

package/cabloy-docs/index.md

@@ -0,0 +1,73 @@
+---
+layout: home
+
+hero:
+  name: 'Cabloy'
+  text: 'Unified fullstack framework documentation'
+  tagline: Build SSR, SPA, Web, and Admin applications with monorepo-native guidance for Cabloy, Vona, Zova, and AI-assisted development.
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /fullstack/quickstart
+    - theme: alt
+      text: Editions
+      link: /editions/overview
+    - theme: alt
+      text: AI Development
+      link: /ai/introduction
+
+features:
+  - title: Fullstack by design
+    details: Understand how Cabloy combines the Vona backend and the Zova frontend in one source tree so humans and AI agents can work from the same ground truth.
+  - title: Edition-aware workflows
+    details: Distinguish what is common across Cabloy Basic and Cabloy Start, and what changes because of UI library, module composition, or private value-add features.
+  - title: CLI-first automation
+    details: Reuse Vona and Zova CLI capabilities for scaffolding, refactoring, metadata, and verification instead of re-deriving framework conventions from scratch.
+  - title: AI-ready knowledge system
+    details: Connect public docs, internal architecture notes, Claude rules, and skills so AI-assisted development stays accurate, efficient, and maintainable.
+---
+
+# Cabloy Documentation
+
+This site is the new documentation home for the Cabloy monorepo.
+
+It is designed around four practical goals:
+
+1. explain the shared architecture across Cabloy, Vona, and Zova
+2. document the real monorepo workflows used in current source code
+3. distinguish Cabloy Basic and Cabloy Start clearly
+4. provide durable guidance for AI-assisted development
+
+## What is covered here
+
+- **Fullstack**: monorepo setup, shared workflows, and cross-stack architecture
+- **Backend (Vona)**: backend concepts, infrastructure, and CLI-backed workflows
+- **Frontend (Zova)**: frontend concepts, SSR, UI-stack considerations, and CLI-backed workflows
+- **Editions**: how Cabloy Basic and Cabloy Start relate and where they differ
+- **AI Development**: how docs, skills, rules, commands, and internal engineering notes work together
+- **Reference**: scripts, CLI command families, package layout, and terminology
+
+## Documentation scope labels
+
+Use these labels throughout the site:
+
+<Badge type="tip" text="Common" /> applies to both Cabloy Basic and Cabloy Start.
+
+<Badge type="info" text="Basic" /> applies only to Cabloy Basic.
+
+<Badge type="warning" text="Start" /> applies only to Cabloy Start.
+
+## First reading path
+
+### For project users
+
+1. [Fullstack Quickstart](/fullstack/quickstart)
+2. [Editions Overview](/editions/overview)
+3. [Fullstack Introduction](/fullstack/introduction)
+
+### For framework contributors and AI workflows
+
+1. [Fullstack Introduction](/fullstack/introduction)
+2. [AI Development Introduction](/ai/introduction)
+3. [Repo Scripts Reference](/reference/repo-scripts)
+4. [Editions Overview](/editions/overview)

package/cabloy-docs/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "cabloy-docs",
+  "private": true,
+  "description": "Unified Cabloy monorepo docs",
+  "license": "MIT",
+  "author": "zhennann",
+  "type": "module",
+  "scripts": {
+    "docs:dev": "vitepress dev .",
+    "docs:build": "vitepress build .",
+    "docs:preview": "vitepress preview ."
+  },
+  "devDependencies": {
+    "vitepress": "^1.6.4"
+  }
+}