swallowkit 1.0.0-beta.4 → 1.0.0-beta.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (204) hide show
  1. package/LICENSE +21 -21
  2. package/README.ja.md +153 -215
  3. package/README.md +153 -216
  4. package/dist/__tests__/fixtures.d.ts +22 -0
  5. package/dist/__tests__/fixtures.d.ts.map +1 -0
  6. package/dist/__tests__/fixtures.js +146 -0
  7. package/dist/__tests__/fixtures.js.map +1 -0
  8. package/dist/cli/commands/add-auth.d.ts +10 -0
  9. package/dist/cli/commands/add-auth.d.ts.map +1 -0
  10. package/dist/cli/commands/add-auth.js +426 -0
  11. package/dist/cli/commands/add-auth.js.map +1 -0
  12. package/dist/cli/commands/add-connector.d.ts +20 -0
  13. package/dist/cli/commands/add-connector.d.ts.map +1 -0
  14. package/dist/cli/commands/add-connector.js +163 -0
  15. package/dist/cli/commands/add-connector.js.map +1 -0
  16. package/dist/cli/commands/create-model.d.ts +1 -4
  17. package/dist/cli/commands/create-model.d.ts.map +1 -1
  18. package/dist/cli/commands/create-model.js +21 -82
  19. package/dist/cli/commands/create-model.js.map +1 -1
  20. package/dist/cli/commands/dev-seeds.d.ts +57 -0
  21. package/dist/cli/commands/dev-seeds.d.ts.map +1 -0
  22. package/dist/cli/commands/dev-seeds.js +470 -0
  23. package/dist/cli/commands/dev-seeds.js.map +1 -0
  24. package/dist/cli/commands/dev.d.ts +33 -0
  25. package/dist/cli/commands/dev.d.ts.map +1 -1
  26. package/dist/cli/commands/dev.js +628 -146
  27. package/dist/cli/commands/dev.js.map +1 -1
  28. package/dist/cli/commands/index.d.ts +1 -0
  29. package/dist/cli/commands/index.d.ts.map +1 -1
  30. package/dist/cli/commands/index.js +3 -1
  31. package/dist/cli/commands/index.js.map +1 -1
  32. package/dist/cli/commands/init.d.ts +45 -0
  33. package/dist/cli/commands/init.d.ts.map +1 -1
  34. package/dist/cli/commands/init.js +2851 -1754
  35. package/dist/cli/commands/init.js.map +1 -1
  36. package/dist/cli/commands/scaffold.d.ts +4 -0
  37. package/dist/cli/commands/scaffold.d.ts.map +1 -1
  38. package/dist/cli/commands/scaffold.js +439 -130
  39. package/dist/cli/commands/scaffold.js.map +1 -1
  40. package/dist/cli/index.d.ts +5 -1
  41. package/dist/cli/index.d.ts.map +1 -1
  42. package/dist/cli/index.js +200 -42
  43. package/dist/cli/index.js.map +1 -1
  44. package/dist/core/config.d.ts +8 -2
  45. package/dist/core/config.d.ts.map +1 -1
  46. package/dist/core/config.js +94 -5
  47. package/dist/core/config.js.map +1 -1
  48. package/dist/core/mock/connector-mock-server.d.ts +101 -0
  49. package/dist/core/mock/connector-mock-server.d.ts.map +1 -0
  50. package/dist/core/mock/connector-mock-server.js +480 -0
  51. package/dist/core/mock/connector-mock-server.js.map +1 -0
  52. package/dist/core/mock/zod-mock-generator.d.ts +14 -0
  53. package/dist/core/mock/zod-mock-generator.d.ts.map +1 -0
  54. package/dist/core/mock/zod-mock-generator.js +163 -0
  55. package/dist/core/mock/zod-mock-generator.js.map +1 -0
  56. package/dist/core/operations/create-model.d.ts +15 -0
  57. package/dist/core/operations/create-model.d.ts.map +1 -0
  58. package/dist/core/operations/create-model.js +171 -0
  59. package/dist/core/operations/create-model.js.map +1 -0
  60. package/dist/core/operations/runtime.d.ts +32 -0
  61. package/dist/core/operations/runtime.d.ts.map +1 -0
  62. package/dist/core/operations/runtime.js +225 -0
  63. package/dist/core/operations/runtime.js.map +1 -0
  64. package/dist/core/operations/scaffold-machine.d.ts +16 -0
  65. package/dist/core/operations/scaffold-machine.d.ts.map +1 -0
  66. package/dist/core/operations/scaffold-machine.js +63 -0
  67. package/dist/core/operations/scaffold-machine.js.map +1 -0
  68. package/dist/core/project/manifest.d.ts +92 -0
  69. package/dist/core/project/manifest.d.ts.map +1 -0
  70. package/dist/core/project/manifest.js +321 -0
  71. package/dist/core/project/manifest.js.map +1 -0
  72. package/dist/core/project/validation.d.ts +20 -0
  73. package/dist/core/project/validation.d.ts.map +1 -0
  74. package/dist/core/project/validation.js +209 -0
  75. package/dist/core/project/validation.js.map +1 -0
  76. package/dist/core/scaffold/auth-generator.d.ts +38 -0
  77. package/dist/core/scaffold/auth-generator.d.ts.map +1 -0
  78. package/dist/core/scaffold/auth-generator.js +1244 -0
  79. package/dist/core/scaffold/auth-generator.js.map +1 -0
  80. package/dist/core/scaffold/connector-functions-generator.d.ts +41 -0
  81. package/dist/core/scaffold/connector-functions-generator.d.ts.map +1 -0
  82. package/dist/core/scaffold/connector-functions-generator.js +1027 -0
  83. package/dist/core/scaffold/connector-functions-generator.js.map +1 -0
  84. package/dist/core/scaffold/functions-generator.d.ts +7 -1
  85. package/dist/core/scaffold/functions-generator.d.ts.map +1 -1
  86. package/dist/core/scaffold/functions-generator.js +920 -220
  87. package/dist/core/scaffold/functions-generator.js.map +1 -1
  88. package/dist/core/scaffold/model-parser.d.ts +20 -1
  89. package/dist/core/scaffold/model-parser.d.ts.map +1 -1
  90. package/dist/core/scaffold/model-parser.js +328 -135
  91. package/dist/core/scaffold/model-parser.js.map +1 -1
  92. package/dist/core/scaffold/native-schema-generator.d.ts +13 -0
  93. package/dist/core/scaffold/native-schema-generator.d.ts.map +1 -0
  94. package/dist/core/scaffold/native-schema-generator.js +696 -0
  95. package/dist/core/scaffold/native-schema-generator.js.map +1 -0
  96. package/dist/core/scaffold/nextjs-generator.d.ts +8 -0
  97. package/dist/core/scaffold/nextjs-generator.d.ts.map +1 -1
  98. package/dist/core/scaffold/nextjs-generator.js +314 -182
  99. package/dist/core/scaffold/nextjs-generator.js.map +1 -1
  100. package/dist/core/scaffold/openapi-generator.d.ts +3 -0
  101. package/dist/core/scaffold/openapi-generator.d.ts.map +1 -0
  102. package/dist/core/scaffold/openapi-generator.js +190 -0
  103. package/dist/core/scaffold/openapi-generator.js.map +1 -0
  104. package/dist/core/scaffold/ui-generator.d.ts +10 -4
  105. package/dist/core/scaffold/ui-generator.d.ts.map +1 -1
  106. package/dist/core/scaffold/ui-generator.js +768 -663
  107. package/dist/core/scaffold/ui-generator.js.map +1 -1
  108. package/dist/database/base-model.d.ts +3 -3
  109. package/dist/database/base-model.js +3 -3
  110. package/dist/index.d.ts +2 -2
  111. package/dist/index.d.ts.map +1 -1
  112. package/dist/index.js +2 -1
  113. package/dist/index.js.map +1 -1
  114. package/dist/machine/contracts.d.ts +16 -0
  115. package/dist/machine/contracts.d.ts.map +1 -0
  116. package/dist/machine/contracts.js +3 -0
  117. package/dist/machine/contracts.js.map +1 -0
  118. package/dist/machine/errors.d.ts +11 -0
  119. package/dist/machine/errors.d.ts.map +1 -0
  120. package/dist/machine/errors.js +34 -0
  121. package/dist/machine/errors.js.map +1 -0
  122. package/dist/machine/index.d.ts +3 -0
  123. package/dist/machine/index.d.ts.map +1 -0
  124. package/dist/machine/index.js +156 -0
  125. package/dist/machine/index.js.map +1 -0
  126. package/dist/mcp/index.d.ts +25 -0
  127. package/dist/mcp/index.d.ts.map +1 -0
  128. package/dist/mcp/index.js +186 -0
  129. package/dist/mcp/index.js.map +1 -0
  130. package/dist/types/index.d.ts +65 -0
  131. package/dist/types/index.d.ts.map +1 -1
  132. package/dist/utils/package-manager.d.ts +110 -0
  133. package/dist/utils/package-manager.d.ts.map +1 -0
  134. package/dist/utils/package-manager.js +224 -0
  135. package/dist/utils/package-manager.js.map +1 -0
  136. package/dist/utils/python-uv.d.ts +21 -0
  137. package/dist/utils/python-uv.d.ts.map +1 -0
  138. package/dist/utils/python-uv.js +111 -0
  139. package/dist/utils/python-uv.js.map +1 -0
  140. package/package.json +84 -73
  141. package/src/__tests__/__snapshots__/functions-generator.test.ts.snap +1139 -0
  142. package/src/__tests__/__snapshots__/nextjs-generator.test.ts.snap +194 -0
  143. package/src/__tests__/__snapshots__/ui-generator.test.ts.snap +532 -0
  144. package/src/__tests__/auth.test.ts +654 -0
  145. package/src/__tests__/config.test.ts +274 -0
  146. package/src/__tests__/connector-functions-generator.test.ts +288 -0
  147. package/src/__tests__/connector-mock-server.test.ts +439 -0
  148. package/src/__tests__/connector-model-bff.test.ts +162 -0
  149. package/src/__tests__/dev-seeds.test.ts +173 -0
  150. package/src/__tests__/dev.test.ts +252 -0
  151. package/src/__tests__/fixtures.ts +144 -0
  152. package/src/__tests__/functions-generator.test.ts +237 -0
  153. package/src/__tests__/init.test.ts +197 -0
  154. package/src/__tests__/jest-globals.d.ts +8 -0
  155. package/src/__tests__/machine.test.ts +356 -0
  156. package/src/__tests__/mcp.test.ts +124 -0
  157. package/src/__tests__/model-parser.test.ts +52 -0
  158. package/src/__tests__/nextjs-generator.test.ts +97 -0
  159. package/src/__tests__/openapi-generator.test.ts +43 -0
  160. package/src/__tests__/package-manager.test.ts +201 -0
  161. package/src/__tests__/python-uv.test.ts +48 -0
  162. package/src/__tests__/scaffold.test.ts +191 -0
  163. package/src/__tests__/string-utils.test.ts +75 -0
  164. package/src/__tests__/tsconfig.json +15 -0
  165. package/src/__tests__/ui-generator.test.ts +144 -0
  166. package/src/__tests__/zod-mock-generator.test.ts +132 -0
  167. package/src/cli/commands/add-auth.ts +482 -0
  168. package/src/cli/commands/add-connector.ts +158 -0
  169. package/src/cli/commands/create-model.ts +62 -0
  170. package/src/cli/commands/dev-seeds.ts +614 -0
  171. package/src/cli/commands/dev.ts +1134 -0
  172. package/src/cli/commands/index.ts +9 -0
  173. package/src/cli/commands/init.ts +3600 -0
  174. package/src/cli/commands/provision.ts +193 -0
  175. package/src/cli/commands/scaffold.ts +991 -0
  176. package/src/cli/index.ts +196 -0
  177. package/src/core/config.ts +312 -0
  178. package/src/core/mock/connector-mock-server.ts +555 -0
  179. package/src/core/mock/zod-mock-generator.ts +205 -0
  180. package/src/core/operations/create-model.ts +174 -0
  181. package/src/core/operations/runtime.ts +235 -0
  182. package/src/core/operations/scaffold-machine.ts +91 -0
  183. package/src/core/project/manifest.ts +402 -0
  184. package/src/core/project/validation.ts +229 -0
  185. package/src/core/scaffold/auth-generator.ts +1284 -0
  186. package/src/core/scaffold/connector-functions-generator.ts +1128 -0
  187. package/src/core/scaffold/functions-generator.ts +970 -0
  188. package/src/core/scaffold/model-parser.ts +841 -0
  189. package/src/core/scaffold/native-schema-generator.ts +822 -0
  190. package/src/core/scaffold/nextjs-generator.ts +370 -0
  191. package/src/core/scaffold/openapi-generator.ts +212 -0
  192. package/src/core/scaffold/ui-generator.ts +1061 -0
  193. package/src/database/base-model.ts +184 -0
  194. package/src/database/client.ts +140 -0
  195. package/src/database/repository.ts +104 -0
  196. package/src/database/runtime-check.ts +25 -0
  197. package/src/index.ts +27 -0
  198. package/src/machine/contracts.ts +17 -0
  199. package/src/machine/errors.ts +34 -0
  200. package/src/machine/index.ts +173 -0
  201. package/src/mcp/index.ts +191 -0
  202. package/src/types/index.ts +134 -0
  203. package/src/utils/package-manager.ts +238 -0
  204. package/src/utils/python-uv.ts +96 -0
package/README.md CHANGED
@@ -1,216 +1,153 @@
1
- # SwallowKit
2
-
3
- [![npm version](https://img.shields.io/npm/v/swallowkit.svg)](https://www.npmjs.com/package/swallowkit)
4
- [![npm downloads](https://img.shields.io/npm/dm/swallowkit.svg)](https://www.npmjs.com/package/swallowkit)
5
- [![license](https://img.shields.io/npm/l/swallowkit.svg)](./LICENSE)
6
-
7
- English | [日本語](./README.ja.md)
8
-
9
- **Type-safe schema-driven development toolkit for Next.js applications on Azure**
10
-
11
- SwallowKit enables developers to build full-stack Next.js applications with external Azure Functions backends while maintaining end-to-end type safety through shared Zod schemas.
12
-
13
- Deploy your Next.js app to Azure Static Web Apps using standalone mode, and connect to independent Azure Functions for backend operations.
14
-
15
- Next.js API routes are restricted to use only as BFF (Backend For Frontend), offloading business logic to Azure Functions to provide clear separation between client and server.
16
-
17
- Featuring Scaffold functionality to automatically generate CRUD operations from Zod schemas, achieving type-safe integration with Cosmos DB and consistent type definitions and validation.
18
-
19
- > **Note**: This project is in active development. APIs may change in future versions.
20
-
21
- ## ✨ Key Features
22
-
23
- - **🔄 Zod Schema Sharing** - Same schema across frontend, BFF, Azure Functions, and Cosmos DB
24
- - **⚡ CRUD Code Generation** - Auto-generate Azure Functions + Next.js code with `swallowkit scaffold`
25
- - **🛡️ Full Type Safety** - End-to-end TypeScript from client to database
26
- - **🎯 BFF Pattern** - Next.js API Routes as BFF layer with auto-validation and resource inference
27
- - **☁️ Azure Optimized** - Minimal-cost architecture with Static Web Apps + Functions + Cosmos DB
28
- - **🚀 Easy Deployment** - Auto-generated Bicep IaC + CI/CD workflows
29
-
30
- ## 📚 Documentation
31
-
32
- - **[CLI Reference](./docs/cli-reference.md)** - All commands in detail
33
- - **[Scaffold Guide](./docs/scaffold-guide.md)** - CRUD code generation
34
- - **[Zod Schema Sharing Guide](./docs/zod-schema-sharing-guide.md)** - Schema design
35
- - **[Deployment Guide](./docs/deployment-guide.md)** - Deploy to Azure
36
-
37
- ## 🚀 Quick Start
38
-
39
- ### 1. Create Project
40
-
41
- ```bash
42
- npx swallowkit init my-app
43
- cd my-app
44
- ```
45
-
46
- ### 2. Create Models
47
-
48
- You can create multiple models at once:
49
-
50
- ```bash
51
- npx swallowkit create-model category todo
52
- ```
53
-
54
- This generates `shared/models/category.ts` and `shared/models/todo.ts`. Customize them by adding your required fields:
55
-
56
- ```typescript
57
- // shared/models/category.ts
58
- import { z } from 'zod';
59
-
60
- export const category = z.object({
61
- id: z.string(),
62
- name: z.string().min(1).max(50),
63
- createdAt: z.string().optional(),
64
- updatedAt: z.string().optional(),
65
- });
66
-
67
- export type Category = z.infer<typeof category>;
68
- ```
69
-
70
- For parent-child relationships, use **nested schemas** instead of ID references:
71
-
72
- ```typescript
73
- // shared/models/todo.ts
74
- import { z } from 'zod';
75
- import { category } from './category';
76
-
77
- export const todo = z.object({
78
- id: z.string(),
79
- text: z.string().min(1).max(200),
80
- completed: z.boolean().default(false),
81
- category: category.optional(), // Nested object (not categoryId)
82
- createdAt: z.string().optional(),
83
- updatedAt: z.string().optional(),
84
- });
85
-
86
- export type Todo = z.infer<typeof todo>;
87
- ```
88
-
89
- > **Tip**: Nesting preserves type safety and stores related data together in the document, which is natural for Cosmos DB's document model.
90
-
91
- ### 3. Generate CRUD Code
92
-
93
- ```bash
94
- npx swallowkit scaffold shared/models/todo.ts
95
- ```
96
-
97
- This auto-generates:
98
- - ✅ Azure Functions (CRUD endpoints + Cosmos DB bindings)
99
- - Next.js BFF API Routes (auto-validation + resource inference)
100
- - ✅ React Components (type-safe forms)
101
-
102
- ### 4. Start Development Server
103
-
104
- ```bash
105
- npx swallowkit dev
106
- ```
107
-
108
- - Next.js: http://localhost:3000
109
- - Azure Functions: http://localhost:7071
110
-
111
- ### 5. Use from Frontend
112
-
113
- ```typescript
114
- import { api } from '@/lib/api/backend';
115
- import type { Todo } from '@/shared/models/todo';
116
-
117
- // Get all - call BFF endpoint
118
- const todos = await api.get<Todo[]>('/api/todos');
119
-
120
- // Create - validated by backend
121
- const created = await api.post<Todo>('/api/todos', {
122
- text: 'Buy milk',
123
- completed: false
124
- });
125
-
126
- // Update - validated by backend
127
- const updated = await api.put<Todo>('/api/todos/123', { completed: true });
128
-
129
- // Delete
130
- await api.delete('/api/todos/123');
131
- ```
132
-
133
- ## 🏗️ Architecture
134
-
135
- ```
136
- ┌─────────────────────────────────────────────────────────────┐
137
- │ Frontend (React) │
138
- - Client Components │
139
- │ - Server Components (SSR) │
140
- └──────────────────────────┬───────────────────────────────────┘
141
- api.post('/api/todos', data)
142
-
143
- ┌─────────────────────────────────────────────────────────────┐
144
- │ BFF Layer (Next.js API Routes) │
145
- │ - Auto Schema Validation (Zod) │
146
- │ - Error Handling │
147
- └──────────────────────────┬───────────────────────────────────┘
148
- │ HTTP Request
149
-
150
- ┌─────────────────────────────────────────────────────────────┐
151
- │ Azure Functions (Backend) │
152
- │ - HTTP Triggers (CRUD) │
153
- │ - Zod Validation (Re-check) │
154
- │ - Business Logic │
155
- │ - Cosmos DB Bindings │
156
- └──────────────────────────┬───────────────────────────────────┘
157
-
158
-
159
- ┌─────────────────────────────────────────────────────────────┐
160
- │ Azure Cosmos DB │
161
- │ - NoSQL Database │
162
- │ - Zod Schema Validation │
163
- └─────────────────────────────────────────────────────────────┘
164
- ```
165
-
166
- **Key Patterns:**
167
- - **BFF (Backend For Frontend)**: Next.js API Routes proxy to Azure Functions
168
- - **Shared Schemas**: Zod schemas used across frontend, BFF, Functions, and DB
169
- - **Type Safety**: TypeScript types auto-inferred from Zod
170
- - **Managed Identity**: Secure service connections (no connection strings)
171
-
172
- ## 📦 Prerequisites
173
-
174
- - Node.js 22.x
175
- - Azure Cosmos DB Emulator (local development)
176
- - [Official documentation (vNext recommended)](https://learn.microsoft.com/en-us/azure/cosmos-db/emulator-linux)
177
- - Windows: [Download](https://aka.ms/cosmosdb-emulator)
178
- - Docker: `docker run -p 8081:8081 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator`
179
-
180
- ## 🚀 Deploy to Azure
181
-
182
- Deploy your Next.js app to Azure Static Web Apps using standalone mode, and connect to independent Azure Functions for backend operations.
183
-
184
- **1. Provision resources (Bicep IaC)**
185
-
186
- ```bash
187
- npx swallowkit provision --resource-group my-app-rg --location japaneast
188
- ```
189
-
190
- After provisioning, the required CI/CD secret values are displayed in the terminal. Copy them.
191
-
192
- **2. Push code**
193
-
194
- ```bash
195
- git push origin main
196
- ```
197
-
198
- **3. Cancel the auto-triggered CI/CD run** — it will fail because secrets are not registered yet.
199
-
200
- **4. Register the displayed secret values** in GitHub (Settings → Secrets) or Azure DevOps (Pipelines → Library).
201
-
202
- **5. Manually re-run the CI/CD workflow.**
203
-
204
- See **[Deployment Guide](./docs/deployment-guide.md)** for details.
205
-
206
- ## License
207
-
208
- MIT
209
-
210
- ## 🔗 Related Links
211
-
212
- - [Azure Static Web Apps](https://learn.microsoft.com/en-us/azure/static-web-apps/)
213
- - [Azure Functions](https://learn.microsoft.com/en-us/azure/azure-functions/)
214
- - [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/)
215
- - [Next.js](https://nextjs.org/)
216
- - [Zod](https://zod.dev/)
1
+ # SwallowKit
2
+
3
+ [![npm version](https://img.shields.io/npm/v/swallowkit.svg)](https://www.npmjs.com/package/swallowkit)
4
+ [![npm downloads](https://img.shields.io/npm/dm/swallowkit.svg)](https://www.npmjs.com/package/swallowkit)
5
+ [![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/himanago.swallowkit-vscode?label=VS%20Code%20Extension)](https://marketplace.visualstudio.com/items?itemName=himanago.swallowkit-vscode)
6
+ [![license](https://img.shields.io/npm/l/swallowkit.svg)](./LICENSE)
7
+
8
+ English | [日本語](./README.ja.md)
9
+
10
+ Schema-driven application scaffolding for Next.js and Azure.
11
+
12
+ SwallowKit helps you build maintainable full-stack applications on Azure by using shared Zod schemas as the source of truth. From one schema definition, it can generate frontend forms, BFF routes, Azure Functions backends, OpenAPI contracts, infrastructure templates, and AI-agent-friendly project metadata.
13
+
14
+ It is designed for developers who want to build Next.js applications on Azure without letting the frontend, backend, database model, validation rules, and deployment configuration drift apart.
15
+
16
+ ## 🎯 Why SwallowKit?
17
+
18
+ AI can generate application code quickly. Frameworks can hide complexity nicely. But production applications still need explicit architecture.
19
+
20
+ In a typical full-stack application, the same domain model is repeated across many places:
21
+
22
+ - frontend form types
23
+ - client-side validation
24
+ - BFF request and response models
25
+ - backend DTOs
26
+ - API contracts
27
+ - database entities
28
+ - seed data
29
+ - infrastructure and deployment configuration
30
+
31
+ As the application grows, these layers often drift apart. SwallowKit reduces that drift by making the schema explicit and using it to generate the surrounding application structure.
32
+
33
+ **SwallowKit is not a full-stack framework that hides everything behind magic. It is a scaffolding toolkit that generates readable, editable, and replaceable code.**
34
+
35
+ ## What it gives you
36
+
37
+ - **Shared Zod schemas** as the source of truth
38
+ - **CRUD scaffolding** for Next.js, BFF routes, Azure Functions, and UI components
39
+ - **Azure-ready infrastructure** using Bicep
40
+ - **Multi-language Azure Functions** backends (TypeScript, C#, Python)
41
+ - **Local development helpers** and seed data
42
+ - **AI/MCP-friendly** project metadata and commands
43
+ - **VS Code extension** support
44
+
45
+ ## 🏗️ Typical architecture
46
+
47
+ SwallowKit is optimized for applications built with:
48
+
49
+ - Next.js
50
+ - Azure Static Web Apps
51
+ - Azure Functions
52
+ - Azure Cosmos DB
53
+ - Azure Bicep
54
+ - GitHub Actions or Azure Pipelines
55
+
56
+ The default architecture follows a BFF pattern:
57
+
58
+ ```
59
+ Browser
60
+ |
61
+ Next.js frontend
62
+ |
63
+ Next.js BFF routes
64
+ |
65
+ Azure Functions API
66
+ |
67
+ Azure Cosmos DB
68
+ ```
69
+
70
+ The BFF layer keeps frontend code simple while allowing backend services, authentication, authorization, and cloud resources to evolve independently.
71
+
72
+ > **Note**: This project is in active development. APIs may change in future versions.
73
+
74
+ ## 📚 Documentation
75
+
76
+ Visit the **[SwallowKit Documentation](https://himanago.github.io/swallowkit/)** for the full docs (also available in [日本語](https://himanago.github.io/swallowkit/ja/)).
77
+
78
+ - **[Getting Started](https://himanago.github.io/swallowkit/en/getting-started)** - First project setup
79
+ - **[Core Concepts](https://himanago.github.io/swallowkit/en/concepts)** - Schema-centric architecture
80
+ - **[Scaffold Guide](https://himanago.github.io/swallowkit/en/scaffold-guide)** - CRUD code generation
81
+ - **[Local Development](https://himanago.github.io/swallowkit/en/dev-guide)** - Dev server, seeds, mock connectors
82
+ - **[Deployment Guide](https://himanago.github.io/swallowkit/en/deployment-guide)** - Deploy to Azure
83
+ - **[AI / MCP Guide](https://himanago.github.io/swallowkit/en/ai-mcp-guide)** - AI-agent integration
84
+ - **[Authentication](https://himanago.github.io/swallowkit/en/auth-guide)** - Auth and authorization
85
+ - **[Connectors](https://himanago.github.io/swallowkit/en/connector-guide)** - External data sources
86
+
87
+ ## 🚀 Quick start
88
+
89
+ Create a new project:
90
+
91
+ ```bash
92
+ npx swallowkit init my-app
93
+ cd my-app
94
+ ```
95
+
96
+ Create a model and customize the schema:
97
+
98
+ ```bash
99
+ npx swallowkit create-model todo
100
+ ```
101
+
102
+ ```typescript
103
+ // shared/models/todo.ts
104
+ import { z } from 'zod';
105
+
106
+ export const todo = z.object({
107
+ id: z.string(),
108
+ text: z.string().min(1).max(200),
109
+ completed: z.boolean().default(false),
110
+ createdAt: z.string().optional(),
111
+ updatedAt: z.string().optional(),
112
+ });
113
+
114
+ export type Todo = z.infer<typeof todo>;
115
+ ```
116
+
117
+ Generate CRUD code and start the dev server:
118
+
119
+ ```bash
120
+ npx swallowkit scaffold todo
121
+ npx swallowkit dev
122
+ ```
123
+
124
+ This generates Azure Functions, Next.js BFF routes, and React UI components — all typed from the shared schema.
125
+
126
+ ## 🤖 AI-agent-friendly development
127
+
128
+ SwallowKit provides machine-readable project metadata and command interfaces so coding agents can inspect the project structure, generate code through official commands, and validate changes without directly rewriting unrelated files.
129
+
130
+ The goal is to make AI-assisted development safer by giving agents explicit architectural boundaries.
131
+
132
+ ## 📦 Generated project structure
133
+
134
+ ```
135
+ .
136
+ ├── app/ # Next.js pages and BFF API routes
137
+ ├── shared/
138
+ └── models/ # Shared Zod schemas (source of truth)
139
+ ├── functions/ # Azure Functions backend
140
+ ├── infra/ # Bicep templates
141
+ ├── lib/ # BFF helpers and scaffold config
142
+ └── .swallowkit/ # SwallowKit project metadata
143
+ ```
144
+
145
+ ## 🔗 Status
146
+
147
+ SwallowKit is under active development. The API, project structure, and generated output may change.
148
+
149
+ Feedback, issues, and small example use cases are welcome.
150
+
151
+ ## 📄 License
152
+
153
+ MIT
@@ -0,0 +1,22 @@
1
+ import { ModelInfo } from "../core/scaffold/model-parser";
2
+ /**
3
+ * テスト用の基本的な ModelInfo フィクスチャ
4
+ */
5
+ export declare function createBasicModelInfo(overrides?: Partial<ModelInfo>): ModelInfo;
6
+ /**
7
+ * RDB コネクタ (read-only) 付きの ModelInfo フィクスチャ
8
+ */
9
+ export declare function createRdbConnectorModelInfo(overrides?: Partial<ModelInfo>): ModelInfo;
10
+ /**
11
+ * API コネクタ (read-write) 付きの ModelInfo フィクスチャ
12
+ */
13
+ export declare function createApiConnectorModelInfo(overrides?: Partial<ModelInfo>): ModelInfo;
14
+ /**
15
+ * 外部キーを含む ModelInfo フィクスチャ
16
+ */
17
+ export declare function createModelInfoWithForeignKey(): ModelInfo;
18
+ /**
19
+ * enum フィールドを含む ModelInfo フィクスチャ
20
+ */
21
+ export declare function createModelInfoWithEnum(): ModelInfo;
22
+ //# sourceMappingURL=fixtures.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../src/__tests__/fixtures.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE1D;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAqB9E;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAuBrF;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CA2BrF;AAED;;GAEG;AACH,wBAAgB,6BAA6B,IAAI,SAAS,CAqBzD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,SAAS,CA0BnD"}
@@ -0,0 +1,146 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.createBasicModelInfo = createBasicModelInfo;
4
+ exports.createRdbConnectorModelInfo = createRdbConnectorModelInfo;
5
+ exports.createApiConnectorModelInfo = createApiConnectorModelInfo;
6
+ exports.createModelInfoWithForeignKey = createModelInfoWithForeignKey;
7
+ exports.createModelInfoWithEnum = createModelInfoWithEnum;
8
+ /**
9
+ * テスト用の基本的な ModelInfo フィクスチャ
10
+ */
11
+ function createBasicModelInfo(overrides) {
12
+ return {
13
+ name: "Todo",
14
+ displayName: "Todo",
15
+ schemaName: "todoSchema",
16
+ filePath: "/models/todo.ts",
17
+ fields: [
18
+ { name: "id", type: "string", isOptional: false, isArray: false },
19
+ { name: "title", type: "string", isOptional: false, isArray: false },
20
+ { name: "description", type: "string", isOptional: true, isArray: false },
21
+ { name: "completed", type: "boolean", isOptional: false, isArray: false },
22
+ { name: "createdAt", type: "string", isOptional: false, isArray: false },
23
+ { name: "updatedAt", type: "string", isOptional: false, isArray: false },
24
+ ],
25
+ hasId: true,
26
+ hasCreatedAt: true,
27
+ hasUpdatedAt: true,
28
+ nestedSchemaRefs: [],
29
+ partitionKey: '/id',
30
+ ...overrides,
31
+ };
32
+ }
33
+ /**
34
+ * RDB コネクタ (read-only) 付きの ModelInfo フィクスチャ
35
+ */
36
+ function createRdbConnectorModelInfo(overrides) {
37
+ return createBasicModelInfo({
38
+ name: "User",
39
+ displayName: "User",
40
+ schemaName: "userSchema",
41
+ filePath: "/models/user.ts",
42
+ fields: [
43
+ { name: "id", type: "string", isOptional: false, isArray: false },
44
+ { name: "employeeCode", type: "string", isOptional: false, isArray: false },
45
+ { name: "name", type: "string", isOptional: false, isArray: false },
46
+ { name: "email", type: "string", isOptional: false, isArray: false },
47
+ { name: "department", type: "string", isOptional: true, isArray: false },
48
+ { name: "createdAt", type: "string", isOptional: true, isArray: false },
49
+ { name: "updatedAt", type: "string", isOptional: true, isArray: false },
50
+ ],
51
+ connectorConfig: {
52
+ connector: "mysql",
53
+ operations: ["getAll", "getById"],
54
+ table: "users",
55
+ idColumn: "id",
56
+ },
57
+ ...overrides,
58
+ });
59
+ }
60
+ /**
61
+ * API コネクタ (read-write) 付きの ModelInfo フィクスチャ
62
+ */
63
+ function createApiConnectorModelInfo(overrides) {
64
+ return createBasicModelInfo({
65
+ name: "BacklogIssue",
66
+ displayName: "BacklogIssue",
67
+ schemaName: "backlogIssueSchema",
68
+ filePath: "/models/backlog-issue.ts",
69
+ fields: [
70
+ { name: "id", type: "string", isOptional: false, isArray: false },
71
+ { name: "projectId", type: "string", isOptional: false, isArray: false },
72
+ { name: "issueKey", type: "string", isOptional: false, isArray: false },
73
+ { name: "summary", type: "string", isOptional: false, isArray: false },
74
+ { name: "description", type: "string", isOptional: true, isArray: false },
75
+ { name: "createdAt", type: "string", isOptional: true, isArray: false },
76
+ { name: "updatedAt", type: "string", isOptional: true, isArray: false },
77
+ ],
78
+ connectorConfig: {
79
+ connector: "backlog",
80
+ operations: ["getAll", "getById", "create", "update"],
81
+ endpoints: {
82
+ getAll: "GET /issues",
83
+ getById: "GET /issues/{id}",
84
+ create: "POST /issues",
85
+ update: "PATCH /issues/{id}",
86
+ },
87
+ },
88
+ ...overrides,
89
+ });
90
+ }
91
+ /**
92
+ * 外部キーを含む ModelInfo フィクスチャ
93
+ */
94
+ function createModelInfoWithForeignKey() {
95
+ return createBasicModelInfo({
96
+ name: "Task",
97
+ displayName: "Task",
98
+ schemaName: "taskSchema",
99
+ filePath: "/models/task.ts",
100
+ fields: [
101
+ { name: "id", type: "string", isOptional: false, isArray: false },
102
+ { name: "title", type: "string", isOptional: false, isArray: false },
103
+ {
104
+ name: "categoryId",
105
+ type: "string",
106
+ isOptional: false,
107
+ isArray: false,
108
+ isForeignKey: true,
109
+ referencedModel: "Category",
110
+ },
111
+ { name: "createdAt", type: "string", isOptional: false, isArray: false },
112
+ { name: "updatedAt", type: "string", isOptional: false, isArray: false },
113
+ ],
114
+ });
115
+ }
116
+ /**
117
+ * enum フィールドを含む ModelInfo フィクスチャ
118
+ */
119
+ function createModelInfoWithEnum() {
120
+ return createBasicModelInfo({
121
+ name: "Issue",
122
+ displayName: "Issue",
123
+ schemaName: "issueSchema",
124
+ filePath: "/models/issue.ts",
125
+ fields: [
126
+ { name: "id", type: "string", isOptional: false, isArray: false },
127
+ { name: "title", type: "string", isOptional: false, isArray: false },
128
+ {
129
+ name: "status",
130
+ type: "string",
131
+ isOptional: false,
132
+ isArray: false,
133
+ enumValues: ["open", "in_progress", "closed"],
134
+ },
135
+ {
136
+ name: "priority",
137
+ type: "number",
138
+ isOptional: true,
139
+ isArray: false,
140
+ },
141
+ { name: "createdAt", type: "string", isOptional: false, isArray: false },
142
+ { name: "updatedAt", type: "string", isOptional: false, isArray: false },
143
+ ],
144
+ });
145
+ }
146
+ //# sourceMappingURL=fixtures.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"fixtures.js","sourceRoot":"","sources":["../../src/__tests__/fixtures.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,10 @@
1
+ /**
2
+ * SwallowKit Add-Auth コマンド
3
+ * 認証認可基盤ファイルを生成する
4
+ */
5
+ interface AddAuthOptions {
6
+ provider?: string;
7
+ }
8
+ export declare function addAuthCommand(options: AddAuthOptions): Promise<void>;
9
+ export {};
10
+ //# sourceMappingURL=add-auth.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"add-auth.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/add-auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyBH,UAAU,cAAc;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,iBAoH3D"}