swallowkit 1.0.0-beta.8 → 1.0.0

package/README.ja.md

@@ -2,107 +2,115 @@
 
 [![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) | 日本語
 
-**Azure 上の Next.js アプリケーション向けの型安全なスキーマ駆動開発ツールキット**
+Next.js と Azure のための、スキーマ駆動アプリケーション開発ツールキットです。
 
-SwallowKit は、Zod スキーマを通じてエンドツーエンドの型安全性を維持しながら、外部の Azure Functions バックエンドを持つフルスタック Next.js アプリケーションを Static Web Apps で構築するための統合キットです。
+SwallowKit は、共有された Zod スキーマを中心にして、保守しやすいフルスタックアプリケーションを Azure 上に構築するための scaffolding ツールです。1 つのスキーマ定義から、フロントエンドフォーム、BFF ルート、Azure Functions バックエンド、OpenAPI、インフラ定義、AI エージェント向けのプロジェクトメタデータなどを生成できます。
 
-Next.js の API ルートを BFF（Backend For Frontend）としての使用のみに制限し、ビジネスロジックは独立した Azure Functions にオフロードすることでクライアント・サーバー間の明確な分離を提供します。
+フロントエンド、バックエンド、データベース、バリデーション、API 契約、デプロイ構成がばらばらになりがちな Next.js + Azure アプリケーション開発を、明示的な構成で整理することを目的としています。
 
-Zod スキーマから自動的に CRUD 操作を生成する Scaffold 機能を備え、一貫した型定義で Next.js (Azure Static Web Apps)、Azure Functions、Cosmos DB を組み合わせた構成で、CRUD コードの自動生成から本番デプロイ・CI/CD までをサポートします。
+## 🎯 なぜ SwallowKit か
 
-> **注意**: このプロジェクトは活発に開発中です。将来のバージョンでAPIが変更される可能性があります。
+AI はアプリケーションコードをすばやく生成できます。フレームワークは複雑さをうまく隠してくれます。しかし、本番で運用するアプリケーションには、依然として明示的なアーキテクチャが必要です。
 
-## ✨ 主な特徴
+一般的なフルスタックアプリケーションでは、同じドメインモデルが多くの場所に重複して現れます。
 
-- **🔄 Zod スキーマ共有** - フロントエンド、BFF、Azure Functions、Cosmos DB をまたいで Zod を唯一のソースとして維持
-- **⚡ CRUD コード生成** - `swallowkit scaffold` で Azure Functions + Next.js コードを自動生成
-- **🌐 Functions バックエンド多言語対応** - `init` 時に Azure Functions の言語として TypeScript、C#、Python を選択可能
-- **🧬 OpenAPI スキーマブリッジ** - C#/Python バックエンドでは `scaffold` が Zod から OpenAPI を出力し、各言語向けスキーマ資産を生成
-- **🛡️ 契約安全性** - 共有 Zod または OpenAPI 由来のモデルにより、フロント/BFF とバックエンドの契約を整合
-- **🎯 BFF パターン** - Next.js API Routes が BFF レイヤーとして機能、自動検証・リソース名推論
-- **☁️ Azure 最適化** - Static Web Apps + Functions + Cosmos DB で最小コスト構成
-- **🚀 簡単デプロイ** - Bicep IaC + CI/CD ワークフローを自動生成
-- **🤖 AI フレンドリー** - 自動生成される指示ファイル（`AGENTS.md`、`CLAUDE.md`、`.github/copilot-instructions.md`）とレイヤー別ルールにより、GitHub Copilot・Claude Code・OpenAI Codex がプロジェクト規約に従ってコードを生成
+- フロントエンドのフォーム型
+- クライアント側バリデーション
+- BFF のリクエスト・レスポンス型
+- バックエンド DTO
+- API 契約
+- データベースエンティティ
+- シードデータ
+- インフラ・デプロイ構成
 
+アプリケーションが大きくなるほど、これらの定義は少しずつずれていきます。SwallowKit は、スキーマを明示的な中心に置き、その周辺に必要なアプリケーション構造を生成することで、このずれを減らします。
 
-## 📚 ドキュメント
+**SwallowKit は、すべてを隠蔽するフルスタックフレームワークではありません。生成されたコードを読み、編集し、必要なら置き換えられることを重視した scaffolding ツールです。**
 
-**[SwallowKit ドキュメント](https://himanago.github.io/swallowkit/ja/)** で完全なドキュメントをご覧ください（[English](https://himanago.github.io/swallowkit/en/) もあります）。
+## ✨ 主な機能
 
-- **[CLI リファレンス](https://himanago.github.io/swallowkit/ja/cli-reference)** - 全コマンドの詳細
-- **[Scaffold ガイド](https://himanago.github.io/swallowkit/ja/scaffold-guide)** - CRUD コード生成
-- **[Zod スキーマ共有ガイド](https://himanago.github.io/swallowkit/ja/zod-schema-sharing-guide)** - スキーマ設計
-- **[デプロイガイド](https://himanago.github.io/swallowkit/ja/deployment-guide)** - Azure へのデプロイ
+- **Zod スキーマを中心にした型定義** とバリデーション共有
+- **Next.js、BFF ルート、Azure Functions、UI コンポーネントの CRUD scaffolding**
+- **Bicep による Azure 向けインフラ定義**
+- **複数言語の Azure Functions バックエンド対応**（TypeScript、C#、Python）
+- **ローカル開発支援** とシードデータ
+- **AI / MCP 向けのプロジェクトメタデータ** とコマンド
+- **VS Code 拡張機能**
 
-## 🚀 クイックスタート
+## 🏗️ 想定アーキテクチャ
 
-### 1. プロジェクト作成
+SwallowKit は、次のような構成のアプリケーションを主な対象にしています。
 
-```bash
-npx swallowkit init my-app
-# or
-pnpm dlx swallowkit init my-app
-cd my-app
-```
+- Next.js
+- Azure Static Web Apps
+- Azure Functions
+- Azure Cosmos DB
+- Azure Bicep
+- GitHub Actions または Azure Pipelines
 
-対話プロンプトで CI/CD プロバイダー、Azure Functions のバックエンド言語、Cosmos DB モード、ネットワーク設定を選択します。フラグで直接指定するとプロンプトをスキップできます：
+標準構成では、BFF パターンを採用します。
 
-```bash
-# 非対話モード（VS Code 拡張機能や自動化に便利）
-npx swallowkit init my-app --cicd github --backend-language python --cosmos-db-mode serverless --vnet outbound
 ```
+ブラウザー
+  |
+Next.js フロントエンド
+  |
+Next.js BFF ルート
+  |
+Azure Functions API
+  |
+Azure Cosmos DB
+```
+
+BFF レイヤーを置くことで、フロントエンドをシンプルに保ちながら、バックエンドサービス、認証・認可、クラウドリソースとの接続を整理しやすくします。
+
+> **注意**: このプロジェクトは活発に開発中です。将来のバージョンでAPIが変更される可能性があります。
+
+## 📚 ドキュメント
 
-| フラグ | 値 | 説明 |
-|------|-----|------|
-| `--cicd <provider>` | `github`, `azure`, `skip` | CI/CD プロバイダー |
-| `--backend-language <language>` | `typescript`, `csharp`, `python` | Azure Functions のバックエンド言語 |
-| `--cosmos-db-mode <mode>` | `freetier`, `serverless` | Cosmos DB 課金モード |
-| `--vnet <option>` | `outbound`, `none` | ネットワークセキュリティ |
+詳しい使い方はドキュメントサイトを参照してください（[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/coding-agent-guide)** - 開発ライフサイクル、責務境界、外部プロセスとの合成
+- **[認証](https://himanago.github.io/swallowkit/ja/auth-guide)** - 認証と認可
+- **[コネクタ](https://himanago.github.io/swallowkit/ja/connector-guide)** - 外部データソース統合
 
-### 2. モデルの作成
+## 🚀 クイックスタート
 
-複数のモデルをまとめて作成できます：
+新しいプロジェクトを作成します。
 
 ```bash
-npx swallowkit create-model category todo
-# or
-pnpm dlx swallowkit create-model category todo
+npx swallowkit init my-app
+cd my-app
 ```
 
-これにより `shared/models/category.ts` と `shared/models/todo.ts` が生成されます。必要なフィールドを追加してカスタマイズ：
+pnpm 11/12 は `pnpm dlx swallowkit init my-app` で作成し、以後 project 内で `pnpm exec swallowkit …` を使います。`npx` は npm を選択し、`--package-manager npm|pnpm` で明示指定できます。Node.js 22.14 以上が必要です。MCP は選択した manager で意図的に `latest` を参照します。[コマンド・workspace・security の詳細](docs/ja/package-managers.md)を参照してください。
 
-```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>;
+```bash
+npx swallowkit create-model todo
 ```
 
-親子関係を表現するには、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(),
 });
@@ -110,142 +118,40 @@ export const todo = z.object({
 export type Todo = z.infer<typeof todo>;
 ```
 
-> **Tip**: ネスト型を使うことで型安全性が保たれ、関連データがドキュメント内にまとまって保存されます。これは Cosmos DB のドキュメントモデルに自然な形です。
-
-### 3. CRUD コード生成
-
-```bash
-npx swallowkit scaffold shared/models/todo.ts
-# or
-pnpm dlx swallowkit scaffold shared/models/todo.ts
-```
-
-これで以下が自動生成されます:
-- ✅ Azure Functions (CRUD エンドポイント + Cosmos DB バインディング)
-- ✅ Next.js BFF API Routes (自動検証・リソース名推論)
-- ✅ React コンポーネント (型安全なフォーム)
-
-`init` で `csharp` または `python` を選んだ場合、`swallowkit scaffold` はあわせて `functions/openapi/` に OpenAPI ドキュメントを出力し、`functions/generated/` に各言語向けスキーマ資産を生成します。
-
-### 4. 開発サーバー起動
+CRUD コードを生成し、開発サーバーを起動します。
 
 ```bash
+npx swallowkit scaffold todo
 npx swallowkit dev
-# or
-pnpm dlx swallowkit dev
 ```
 
-- Next.js: http://localhost:3000
-- Azure Functions: http://localhost:7071
+Azure Functions、Next.js BFF ルート、React UI コンポーネントが、共有スキーマから型付きで生成されます。
 
-### 5. フロントエンドから使用
+## 🤖 AI エージェントとの協調
 
-```typescript
-import { api } from '@/lib/api/backend';
-import type { Todo } from '@/shared/models/todo';
+SwallowKit は、AI コーディングエージェントがプロジェクト構造を理解し、公式の生成コマンドを通じて変更を行い、生成物を検証できるように、機械可読なプロジェクトメタデータとコマンドインターフェースを提供します。
 
-// 全件取得 - BFFエンドポイントを呼び出し
-const todos = await api.get<Todo[]>('/api/todos');
+目的は、AI に自由にファイルを書き換えさせることではなく、明示的なアーキテクチャ境界の中で安全に開発を支援させることです。
 
-// 作成 - バックエンドで検証
-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                                     │
-└─────────────────────────────────────────────────────────────┘
+.
+├── app/                  # Next.js ページと BFF API ルート
+├── shared/
+│   └── models/           # 共有 Zod スキーマ（単一のソース）
+├── functions/            # Azure Functions バックエンド
+├── infra/                # Bicep テンプレート
+├── lib/                  # BFF ヘルパーと scaffold 設定
+└── .swallowkit/          # SwallowKit プロジェクトメタデータ
 ```
 
-**重要なパターン:**
-- **BFF (Backend For Frontend)**: Next.js API Routes が Azure Functions へのプロキシ
-- **共有スキーマ**: `shared/models/` の Zod スキーマを唯一のソースとして扱う
-- **C#/Python 向け OpenAPI ブリッジ**: TypeScript 以外の Functions は `functions/generated/` の生成資産を利用
-- **契約安全性**: 共有 Zod または生成モデルで BFF とバックエンドの整合を保つ
-- **マネージド ID**: サービス間の安全な接続（接続文字列不要）
+## 🔗 ステータス
 
-## 📦 前提条件
+SwallowKit は現在開発中です。API、プロジェクト構成、生成されるコードは変更される可能性があります。
 
-- Node.js 22.x
-- **pnpm**（推奨）: `corepack enable` を実行するか、`npm install -g pnpm` でインストール
-  - npm でも動作します — SwallowKit はパッケージマネージャーを自動検出します（pnpm がインストール済みなら常に pnpm を優先）
-- 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`
+フィードバック、Issue、小さなサンプルユースケースの共有を歓迎します。
 
-## 🚀 Azure へのデプロイ
-
-Next.js アプリを standalone モードで Azure Static Web Apps にデプロイし、バックエンド操作のために独立した Azure Functions に接続します。
-
-**1. リソースをプロビジョニング (Bicep IaC)**
-
-```bash
-npx swallowkit provision --resource-group my-app-rg --location japaneast
-# or
-pnpm dlx 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 ワークフローを手動で再実行します。**
-
-詳細は **[デプロイガイド](https://himanago.github.io/swallowkit/ja/deployment-guide)** を参照してください。
-
-##  ライセンス
+## 📄 ライセンス
 
 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/)