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

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Takumasa Hirabayashi
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Takumasa Hirabayashi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -1,215 +1,153 @@
-# SwallowKit
-
-[![npm version](https://img.shields.io/npm/v/swallowkit.svg)](https://www.npmjs.com/package/swallowkit)
-[![npm downloads](https://img.shields.io/npm/dm/swallowkit.svg)](https://www.npmjs.com/package/swallowkit)
-[![license](https://img.shields.io/npm/l/swallowkit.svg)](./LICENSE)
-
-[English](./README.md) | 日本語
-
-**Azure 上の Next.js アプリケーション向けの型安全なスキーマ駆動開発ツールキット**
-
-SwallowKit は、Zod スキーマを通じてエンドツーエンドの型安全性を維持しながら、外部の Azure Functions バックエンドを持つフルスタック Next.js アプリケーションを Static Web Apps で構築するための統合キットです。
-
-Next.js の API ルートを BFF（Backend For Frontend）としての使用のみに制限し、ビジネスロジックは独立した Azure Functions にオフロードすることでクライアント・サーバー間の明確な分離を提供します。
-
-Zod スキーマから自動的に CRUD 操作を生成する Scaffold 機能を備え、一貫した型定義で Next.js (Azure Static Web Apps)、Azure Functions、Cosmos DB を組み合わせた構成で、CRUD コードの自動生成から本番デプロイ・CI/CD までをサポートします。
-
-> **注意**: このプロジェクトは活発に開発中です。将来のバージョンでAPIが変更される可能性があります。
-
-## ✨ 主な特徴
-
-- **🔄 Zod スキーマ共有** - フロントエンド、BFF、Azure Functions、Cosmos DB で同じスキーマを使用
-- **⚡ CRUD コード生成** - `swallowkit scaffold` で Azure Functions + Next.js コードを自動生成
-- **🛡️ 完全な型安全性** - クライアントからデータベースまでエンドツーエンド TypeScript
-- **🎯 BFF パターン** - Next.js API Routes が BFF レイヤーとして機能、自動検証・リソース名推論
-- **☁️ Azure 最適化** - Static Web Apps + Functions + Cosmos DB で最小コスト構成
-- **🚀 簡単デプロイ** - Bicep IaC + CI/CD ワークフローを自動生成
-
-
-## 📚 ドキュメント
-
-- **[CLI リファレンス](./docs/cli-reference.ja.md)** - 全コマンドの詳細
-- **[Scaffold ガイド](./docs/scaffold-guide.ja.md)** - CRUD コード生成
-- **[Zod スキーマ共有ガイド](./docs/zod-schema-sharing-guide.ja.md)** - スキーマ設計
-- **[デプロイガイド](./docs/deployment-guide.ja.md)** - Azure へのデプロイ
-
-## 🚀 クイックスタート
-
-### 1. プロジェクト作成
-
-```bash
-npx swallowkit init my-app
-cd my-app
-```
-
-### 2. モデルの作成
-
-複数のモデルをまとめて作成できます：
-
-```bash
-npx swallowkit create-model category todo
-```
-
-これにより `shared/models/category.ts` と `shared/models/todo.ts` が生成されます。必要なフィールドを追加してカスタマイズ：
-
-```typescript
-// shared/models/category.ts
-import { z } from 'zod';
-
-export const category = z.object({
-  id: z.string(),
-  name: z.string().min(1).max(50),
-  createdAt: z.string().optional(),
-  updatedAt: z.string().optional(),
-});
-
-export type Category = z.infer<typeof category>;
-```
-
-親子関係を表現するには、ID 参照ではなく**ネスト型**で記述します：
-
-```typescript
-// shared/models/todo.ts
-import { z } from 'zod';
-import { category } from './category';
-
-export const todo = z.object({
-  id: z.string(),
-  text: z.string().min(1).max(200),
-  completed: z.boolean().default(false),
-  category: category.optional(),       // ネストオブジェクト（categoryId ではない）
-  createdAt: z.string().optional(),
-  updatedAt: z.string().optional(),
-});
-
-export type Todo = z.infer<typeof todo>;
-```
-
-> **Tip**: ネスト型を使うことで型安全性が保たれ、関連データがドキュメント内にまとまって保存されます。これは Cosmos DB のドキュメントモデルに自然な形です。
-
-### 3. CRUD コード生成
-
-```bash
-npx swallowkit scaffold shared/models/todo.ts
-```
-
-これで以下が自動生成されます:
-- ✅ Azure Functions (CRUD エンドポイント + Cosmos DB バインディング)
-- ✅ Next.js BFF API Routes (自動検証・リソース名推論)
-- ✅ React コンポーネント (型安全なフォーム)
-
-### 4. 開発サーバー起動
-
-```bash
-npx swallowkit dev
-```
-
-- Next.js: http://localhost:3000
-- Azure Functions: http://localhost:7071
-
-### 5. フロントエンドから使用
-
-```typescript
-import { api } from '@/lib/api/backend';
-import type { Todo } from '@/shared/models/todo';
-
-// 全件取得 - BFFエンドポイントを呼び出し
-const todos = await api.get<Todo[]>('/api/todos');
-
-// 作成 - バックエンドで検証
-const created = await api.post<Todo>('/api/todos', {
-  text: '牛乳を買う',
-  completed: false
-});
-
-// 更新 - バックエンドで検証
-const updated = await api.put<Todo>('/api/todos/123', { completed: true });
-
-// 削除
-await api.delete('/api/todos/123');
-```
-
-## 🏗️ アーキテクチャ
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Frontend (React)                                            │
-│  - Client Components                                         │
-│  - Server Components (SSR)                                   │
-└──────────────────────────┬───────────────────────────────────┘
-                           │ api.post('/api/todos', data)
-                           ▼
-┌─────────────────────────────────────────────────────────────┐
-│  BFF Layer (Next.js API Routes)                              │
-│  - Auto Schema Validation (Zod)                              │
-│  - Error Handling                                            │
-└──────────────────────────┬───────────────────────────────────┘
-                           │ HTTP Request
-                           ▼
-┌─────────────────────────────────────────────────────────────┐
-│  Azure Functions (Backend)                                   │
-│  - HTTP Triggers (CRUD)                                      │
-│  - Zod Validation (Re-check)                                 │
-│  - Business Logic                                            │
-│  - Cosmos DB Bindings                                        │
-└──────────────────────────┬───────────────────────────────────┘
-                           │
-                           ▼
-┌─────────────────────────────────────────────────────────────┐
-│  Azure Cosmos DB                                             │
-│  - NoSQL Database                                            │
-│  - Zod Schema Validation                                     │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**重要なパターン:**
-- **BFF (Backend For Frontend)**: Next.js API Routes が Azure Functions へのプロキシ
-- **共有スキーマ**: Zod スキーマをフロントエンド・BFF・Functions・DB で共有
-- **型安全性**: Zod から TypeScript 型を自動推論
-- **マネージド ID**: サービス間の安全な接続（接続文字列不要）
-
-## 📦 前提条件
-
-- Node.js 22.x
-- Azure Cosmos DB Emulator (ローカル開発用)
-  - [公式ドキュメント (vNext 推奨)](https://learn.microsoft.com/ja-jp/azure/cosmos-db/emulator-linux)
-    - Windows: [ダウンロード](https://aka.ms/cosmosdb-emulator)
-    - Docker: `docker run -p 8081:8081 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator`
-
-## 🚀 Azure へのデプロイ
-
-Next.js アプリを standalone モードで Azure Static Web Apps にデプロイし、バックエンド操作のために独立した Azure Functions に接続します。
-
-**1. リソースをプロビジョニング (Bicep IaC)**
-
-```bash
-npx swallowkit provision --resource-group my-app-rg --location japaneast
-```
-
-プロビジョニング完了後、CI/CD に必要なシークレット値がターミナルに表示されます。コピーしておいてください。
-
-**2. コードをプッシュ**
-
-```bash
-git push origin main
-```
-
-**3. 自動実行された CI/CD をキャンセル** — シークレット未登録のため失敗します。
-
-**4. 表示された値をシークレットに登録** — GitHub (Settings → Secrets) または Azure DevOps (Pipelines → Library) に登録します。
-
-**5. CI/CD ワークフローを手動で再実行します。**
-
-詳細は **[デプロイガイド](./docs/deployment-guide.ja.md)** を参照してください。
-
-##  ライセンス
-
-MIT
-
-## 🔗 関連リンク
-
-- [Azure Static Web Apps](https://learn.microsoft.com/ja-jp/azure/static-web-apps/)
-- [Azure Functions](https://learn.microsoft.com/ja-jp/azure/azure-functions/)
-- [Azure Cosmos DB](https://learn.microsoft.com/ja-jp/azure/cosmos-db/)
-- [Next.js](https://nextjs.org/)
-- [Zod](https://zod.dev/)
+# SwallowKit
+
+[![npm version](https://img.shields.io/npm/v/swallowkit.svg)](https://www.npmjs.com/package/swallowkit)
+[![npm downloads](https://img.shields.io/npm/dm/swallowkit.svg)](https://www.npmjs.com/package/swallowkit)
+[![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)
+[![license](https://img.shields.io/npm/l/swallowkit.svg)](./LICENSE)
+
+[English](./README.md) | 日本語
+
+Next.js と Azure のための、スキーマ駆動アプリケーション開発ツールキットです。
+
+SwallowKit は、共有された Zod スキーマを中心にして、保守しやすいフルスタックアプリケーションを Azure 上に構築するための scaffolding ツールです。1 つのスキーマ定義から、フロントエンドフォーム、BFF ルート、Azure Functions バックエンド、OpenAPI、インフラ定義、AI エージェント向けのプロジェクトメタデータなどを生成できます。
+
+フロントエンド、バックエンド、データベース、バリデーション、API 契約、デプロイ構成がばらばらになりがちな Next.js + Azure アプリケーション開発を、明示的な構成で整理することを目的としています。
+
+## 🎯 なぜ SwallowKit か
+
+AI はアプリケーションコードをすばやく生成できます。フレームワークは複雑さをうまく隠してくれます。しかし、本番で運用するアプリケーションには、依然として明示的なアーキテクチャが必要です。
+
+一般的なフルスタックアプリケーションでは、同じドメインモデルが多くの場所に重複して現れます。
+
+- フロントエンドのフォーム型
+- クライアント側バリデーション
+- BFF のリクエスト・レスポンス型
+- バックエンド DTO
+- API 契約
+- データベースエンティティ
+- シードデータ
+- インフラ・デプロイ構成
+
+アプリケーションが大きくなるほど、これらの定義は少しずつずれていきます。SwallowKit は、スキーマを明示的な中心に置き、その周辺に必要なアプリケーション構造を生成することで、このずれを減らします。
+
+**SwallowKit は、すべてを隠蔽するフルスタックフレームワークではありません。生成されたコードを読み、編集し、必要なら置き換えられることを重視した scaffolding ツールです。**
+
+## ✨ 主な機能
+
+- **Zod スキーマを中心にした型定義** とバリデーション共有
+- **Next.js、BFF ルート、Azure Functions、UI コンポーネントの CRUD scaffolding**
+- **Bicep による Azure 向けインフラ定義**
+- **複数言語の Azure Functions バックエンド対応**（TypeScript、C#、Python）
+- **ローカル開発支援** とシードデータ
+- **AI / MCP 向けのプロジェクトメタデータ** とコマンド
+- **VS Code 拡張機能**
+
+## 🏗️ 想定アーキテクチャ
+
+SwallowKit は、次のような構成のアプリケーションを主な対象にしています。
+
+- Next.js
+- Azure Static Web Apps
+- Azure Functions
+- Azure Cosmos DB
+- Azure Bicep
+- GitHub Actions または Azure Pipelines
+
+標準構成では、BFF パターンを採用します。
+
+```
+ブラウザー
+  |
+Next.js フロントエンド
+  |
+Next.js BFF ルート
+  |
+Azure Functions API
+  |
+Azure Cosmos DB
+```
+
+BFF レイヤーを置くことで、フロントエンドをシンプルに保ちながら、バックエンドサービス、認証・認可、クラウドリソースとの接続を整理しやすくします。
+
+> **注意**: このプロジェクトは活発に開発中です。将来のバージョンでAPIが変更される可能性があります。
+
+## 📚 ドキュメント
+
+詳しい使い方はドキュメントサイトを参照してください（[English](https://himanago.github.io/swallowkit/en/) もあります）。
+
+- **[はじめる](https://himanago.github.io/swallowkit/ja/getting-started)** - 最初のプロジェクトセットアップ
+- **[基本概念](https://himanago.github.io/swallowkit/ja/concepts)** - スキーマ中心のアーキテクチャ
+- **[Scaffold ガイド](https://himanago.github.io/swallowkit/ja/scaffold-guide)** - CRUD コード生成
+- **[ローカル開発](https://himanago.github.io/swallowkit/ja/dev-guide)** - Dev サーバー、seeds、モックコネクタ
+- **[デプロイガイド](https://himanago.github.io/swallowkit/ja/deployment-guide)** - Azure へのデプロイ
+- **[AI / MCP ガイド](https://himanago.github.io/swallowkit/ja/ai-mcp-guide)** - AI エージェント統合
+- **[認証](https://himanago.github.io/swallowkit/ja/auth-guide)** - 認証と認可
+- **[コネクタ](https://himanago.github.io/swallowkit/ja/connector-guide)** - 外部データソース統合
+
+## 🚀 クイックスタート
+
+新しいプロジェクトを作成します。
+
+```bash
+npx swallowkit init my-app
+cd my-app
+```
+
+モデルを作成し、スキーマを編集します。
+
+```bash
+npx swallowkit create-model todo
+```
+
+```typescript
+// shared/models/todo.ts
+import { z } from 'zod';
+
+export const todo = z.object({
+  id: z.string(),
+  text: z.string().min(1).max(200),
+  completed: z.boolean().default(false),
+  createdAt: z.string().optional(),
+  updatedAt: z.string().optional(),
+});
+
+export type Todo = z.infer<typeof todo>;
+```
+
+CRUD コードを生成し、開発サーバーを起動します。
+
+```bash
+npx swallowkit scaffold todo
+npx swallowkit dev
+```
+
+Azure Functions、Next.js BFF ルート、React UI コンポーネントが、共有スキーマから型付きで生成されます。
+
+## 🤖 AI エージェントとの協調
+
+SwallowKit は、AI コーディングエージェントがプロジェクト構造を理解し、公式の生成コマンドを通じて変更を行い、生成物を検証できるように、機械可読なプロジェクトメタデータとコマンドインターフェースを提供します。
+
+目的は、AI に自由にファイルを書き換えさせることではなく、明示的なアーキテクチャ境界の中で安全に開発を支援させることです。
+
+## 📦 生成されるプロジェクト構成
+
+```
+.
+├── app/                  # Next.js ページと BFF API ルート
+├── shared/
+│   └── models/           # 共有 Zod スキーマ（単一のソース）
+├── functions/            # Azure Functions バックエンド
+├── infra/                # Bicep テンプレート
+├── lib/                  # BFF ヘルパーと scaffold 設定
+└── .swallowkit/          # SwallowKit プロジェクトメタデータ
+```
+
+## 🔗 ステータス
+
+SwallowKit は現在開発中です。API、プロジェクト構成、生成されるコードは変更される可能性があります。
+
+フィードバック、Issue、小さなサンプルユースケースの共有を歓迎します。
+
+## 📄 ライセンス
+
+MIT