swallowkit 1.0.0-beta.2 → 1.0.0-beta.20

package/src/database/base-model.ts

@@ -0,0 +1,184 @@
+import { z } from "zod";
+import { getDatabaseClient } from "./client.js";
+import { ensureServerSide } from "./runtime-check.js";
+
+/**
+ * @deprecated BaseModel is deprecated and will be removed in a future version.
+ * 
+ * Instead of using BaseModel, define your models as pure Zod schemas:
+ * 
+ * @example
+ * ```typescript
+ * // shared/models/user.ts
+ * import { z } from 'zod';
+ * 
+ * export const userSchema = z.object({
+ *   id: z.string(),
+ *   email: z.string().email(),
+ *   name: z.string(),
+ * });
+ * 
+ * export type UserType = z.infer<typeof userSchema>;
+ * ```
+ * 
+ * Then use the scaffold command to generate CRUD operations:
+ * ```bash
+ * npx swallowkit scaffold shared/models/user.ts
+ * ```
+ * 
+ * This will generate:
+ * - Azure Functions with Cosmos DB bindings
+ * - Next.js BFF API routes
+ * - Type-safe React components
+ * 
+ * Use the generated API from frontend:
+ * ```typescript
+ * import { api } from '@/lib/api/backend';
+ * import type { UserType } from '@myapp/shared';
+ * 
+ * const users = await api.get<UserType[]>('/api/users');
+ * await api.post<UserType>('/api/users', { email: 'test@example.com', name: 'Test' });
+ * ```
+ */
+export abstract class BaseModel {
+  /**
+   * Zod スキーマ（サブクラスで定義）
+   */
+  static schema: z.ZodObject<any>;
+
+  /**
+   * Cosmos DB コンテナ名（サブクラスで定義）
+   */
+  static container: string;
+
+  /**
+   * パーティションキー（サブクラスで定義）
+   * @example "/email" or "/id"
+   */
+  static partitionKey: string;
+
+  /**
+   * データベースクライアントを取得
+   */
+  protected static getClient() {
+    return getDatabaseClient();
+  }
+
+  /**
+   * ドキュメントを作成
+   * @param data ドキュメントデータ
+   * @returns 作成されたドキュメント
+   */
+  static async create<T = any>(data: T): Promise<T> {
+    ensureServerSide(`${this.name}.create`);
+
+    // Zodスキーマでバリデーション
+    const validated = this.schema.parse(data);
+
+    const client = this.getClient();
+    const result = await client.createDocument(this.container, validated);
+    
+    return result as T;
+  }
+
+  /**
+   * ID でドキュメントを取得
+   * @param id ドキュメントID
+   * @returns ドキュメント（見つからない場合は null）
+   */
+  static async findById<T = any>(id: string): Promise<T | null> {
+    ensureServerSide(`${this.name}.findById`);
+
+    const client = this.getClient();
+    const result = await client.getDocument(this.container, id);
+    
+    if (!result) {
+      return null;
+    }
+
+    // Zodスキーマでバリデーション
+    return this.schema.parse(result) as T;
+  }
+
+  /**
+   * クエリでドキュメントを検索
+   * @param query SQL クエリの WHERE 句部分（省略時は全件取得）
+   * @param parameters クエリパラメータ
+   * @returns ドキュメントの配列
+   */
+  static async find<T = any>(query?: string, parameters?: any[]): Promise<T[]> {
+    ensureServerSide(`${this.name}.find`);
+
+    const client = this.getClient();
+    
+    const fullQuery = query 
+      ? `SELECT * FROM c WHERE ${query}`
+      : `SELECT * FROM c`;
+    
+    const results = await client.query(this.container, fullQuery, parameters);
+    
+    // 各ドキュメントをZodスキーマでバリデーション
+    return results.map((result) => this.schema.parse(result)) as T[];
+  }
+
+  /**
+   * ドキュメントを更新
+   * @param data 更新するドキュメントデータ（id フィールド必須）
+   * @returns 更新されたドキュメント
+   */
+  static async update<T = any>(data: T): Promise<T> {
+    ensureServerSide(`${this.name}.update`);
+
+    // Zodスキーマでバリデーション
+    const validated = this.schema.parse(data);
+
+    if (!(validated as any).id) {
+      throw new Error(`${this.name}.update requires an 'id' field`);
+    }
+
+    const client = this.getClient();
+    const result = await client.updateDocument(this.container, validated);
+    
+    return result as T;
+  }
+
+  /**
+   * ドキュメントを削除
+   * @param id ドキュメントID
+   */
+  static async delete(id: string): Promise<void> {
+    ensureServerSide(`${this.name}.delete`);
+
+    const client = this.getClient();
+    await client.deleteDocument(this.container, id);
+  }
+
+  /**
+   * カスタムクエリを実行
+   * @param query 完全な SQL クエリ
+   * @param parameters クエリパラメータ
+   * @returns ドキュメントの配列
+   */
+  static async query<T = any>(query: string, parameters?: any[]): Promise<T[]> {
+    ensureServerSide(`${this.name}.query`);
+
+    const client = this.getClient();
+    const results = await client.query(this.container, query, parameters);
+    
+    // 各ドキュメントをZodスキーマでバリデーション
+    return results.map((result) => this.schema.parse(result)) as T[];
+  }
+
+  /**
+   * Get the API resource name from container name
+   * Converts container name (e.g., "Todos", "Products") to resource path (e.g., "todos", "products")
+   * @returns Resource name in lowercase plural form
+   */
+  static getResourceName(): string {
+    if (!this.container) {
+      throw new Error(`${this.name} must define a static 'container' property`);
+    }
+    // Convert container name to lowercase (Todos -> todos, Products -> products)
+    return this.container.toLowerCase();
+  }
+}

package/src/database/client.ts

@@ -0,0 +1,140 @@
+import { CosmosClient, Database, Container } from "@azure/cosmos";
+import { SwallowKitConfig } from "../types/index.js";
+import { ensureServerSide } from "./runtime-check.js";
+
+/**
+ * Cosmos DB クライアントの管理
+ */
+export class DatabaseClient {
+  private client: CosmosClient | null = null;
+  private database: Database | null = null;
+  private containers: Map<string, Container> = new Map();
+
+  constructor(private config: SwallowKitConfig) {}
+
+  /**
+   * データベースに接続
+   */
+  async connect(): Promise<void> {
+    ensureServerSide('Database connection');
+
+    if (!this.config.database?.connectionString) {
+      throw new Error("Cosmos DB connection string が設定されていません");
+    }
+
+    this.client = new CosmosClient(this.config.database.connectionString);
+    
+    const databaseName = this.config.database.databaseName || "SwallowKitDB";
+    const { database } = await this.client.databases.createIfNotExists({
+      id: databaseName,
+    });
+    
+    this.database = database;
+    console.log(`📦 Cosmos DB に接続しました: ${databaseName}`);
+  }
+
+  /**
+   * コンテナを取得
+   */
+  async getContainer(containerName: string): Promise<Container> {
+    ensureServerSide('Get container');
+
+    if (!this.database) {
+      await this.connect();
+    }
+
+    if (!this.containers.has(containerName)) {
+      const { container } = await this.database!.containers.createIfNotExists({
+        id: containerName,
+        partitionKey: "/id",
+      });
+      this.containers.set(containerName, container);
+    }
+
+    return this.containers.get(containerName)!;
+  }
+
+  /**
+   * ドキュメントを作成
+   */
+  async createDocument<T extends Record<string, any>>(containerName: string, document: T): Promise<T> {
+    ensureServerSide('Create document');
+
+    const container = await this.getContainer(containerName);
+    const { resource } = await container.items.create(document as any);
+    return resource as T;
+  }
+
+  /**
+   * ドキュメントを取得
+   */
+  async getDocument<T extends Record<string, any>>(containerName: string, id: string): Promise<T | null> {
+    ensureServerSide('Get document');
+
+    const container = await this.getContainer(containerName);
+    
+    try {
+      const { resource } = await container.item(id, id).read();
+      return resource as T || null;
+    } catch (error: any) {
+      if (error.code === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * ドキュメントを更新
+   */
+  async updateDocument<T extends Record<string, any>>(containerName: string, document: T): Promise<T> {
+    ensureServerSide('Update document');
+
+    const container = await this.getContainer(containerName);
+    const { resource } = await container.items.upsert(document as any);
+    return resource as unknown as T;
+  }
+
+  /**
+   * ドキュメントを削除
+   */
+  async deleteDocument(containerName: string, id: string): Promise<void> {
+    ensureServerSide('Delete document');
+
+    const container = await this.getContainer(containerName);
+    await container.item(id, id).delete();
+  }
+
+  /**
+   * クエリを実行
+   */
+  async query<T>(containerName: string, query: string, parameters?: any[]): Promise<T[]> {
+    ensureServerSide('Query');
+
+    const container = await this.getContainer(containerName);
+    const { resources } = await container.items.query<T>({
+      query,
+      parameters,
+    }).fetchAll();
+    
+    return resources;
+  }
+}
+
+/**
+ * グローバルデータベースクライアント
+ */
+let globalDatabaseClient: DatabaseClient | null = null;
+
+export function getDatabaseClient(config?: SwallowKitConfig): DatabaseClient {
+  if (!globalDatabaseClient) {
+    if (!config) {
+      throw new Error(
+        "DatabaseClient is not initialized. " +
+        "Please provide a config or initialize it first."
+      );
+    }
+    globalDatabaseClient = new DatabaseClient(config);
+  }
+  return globalDatabaseClient;
+}

package/src/database/repository.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { getDatabaseClient } from "./client";
+
+/**
+ * Zodスキーマベースのデータベース操作ヘルパー
+ */
+export class SchemaRepository<T extends Record<string, any>> {
+  constructor(
+    private containerName: string,
+    private schema: z.ZodSchema<T>
+  ) {}
+
+  /**
+   * ドキュメントを作成（バリデーション付き）
+   */
+  async create(data: T): Promise<T> {
+    const validatedData = this.schema.parse(data);
+    const client = getDatabaseClient();
+    return client.createDocument(this.containerName, validatedData);
+  }
+
+  /**
+   * ドキュメントを取得
+   */
+  async findById(id: string): Promise<T | null> {
+    const client = getDatabaseClient();
+    const document = await client.getDocument<T>(this.containerName, id);
+    
+    if (!document) return null;
+    
+    // データをバリデーション
+    return this.schema.parse(document);
+  }
+
+  /**
+   * ドキュメントを更新（バリデーション付き）
+   */
+  async update(data: T): Promise<T> {
+    const validatedData = this.schema.parse(data);
+    const client = getDatabaseClient();
+    return client.updateDocument(this.containerName, validatedData);
+  }
+
+  /**
+   * ドキュメントを削除
+   */
+  async delete(id: string): Promise<void> {
+    const client = getDatabaseClient();
+    return client.deleteDocument(this.containerName, id);
+  }
+
+  /**
+   * 全てのドキュメントを取得
+   */
+  async findAll(): Promise<T[]> {
+    const client = getDatabaseClient();
+    const documents = await client.query<T>(
+      this.containerName,
+      "SELECT * FROM c"
+    );
+    
+    // 全てのドキュメントをバリデーション
+    return documents.map(doc => this.schema.parse(doc));
+  }
+
+  /**
+   * 条件付きクエリ
+   */
+  async findWhere(condition: string, parameters?: any[]): Promise<T[]> {
+    const client = getDatabaseClient();
+    const query = `SELECT * FROM c WHERE ${condition}`;
+    const documents = await client.query<T>(this.containerName, query, parameters);
+    
+    return documents.map(doc => this.schema.parse(doc));
+  }
+}
+
+/**
+ * 簡単なリポジトリ作成ヘルパー
+ */
+export function createRepository<T extends Record<string, any>>(
+  containerName: string,
+  schema: z.ZodSchema<T>
+): SchemaRepository<T> {
+  return new SchemaRepository(containerName, schema);
+}
+
+/**
+ * よく使われるスキーマの例
+ */
+export const TodoSchema = z.object({
+  id: z.string(),
+  text: z.string(),
+  completed: z.boolean().default(false),
+  createdAt: z.string().default(() => new Date().toISOString()),
+  updatedAt: z.string().default(() => new Date().toISOString()),
+});
+
+export type Todo = z.infer<typeof TodoSchema>;
+
+/**
+ * Todo専用リポジトリの例
+ */
+export const TodoRepository = createRepository("todos", TodoSchema);

package/src/database/runtime-check.ts

@@ -0,0 +1,25 @@
+/**
+ * ランタイム環境の検証
+ * クライアント側でのDB操作を防ぐ
+ */
+
+/**
+ * サーバー側で実行されているかチェック
+ */
+export function isServer(): boolean {
+  return typeof window === 'undefined';
+}
+
+/**
+ * サーバー側での実行を強制
+ * クライアント側で呼ばれた場合はエラーを投げる
+ */
+export function ensureServerSide(operationName: string = 'Database operation'): void {
+  if (!isServer()) {
+    throw new Error(
+      `${operationName} can only be executed on the server side. ` +
+      `Please use this within Server Components, Server Actions, or API Routes. ` +
+      `Client Components cannot directly access the database.`
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * SwallowKit - Next.js framework optimized for Azure deployment
+ * Main exports
+ */
+
+// Type definitions
+export type {
+  UseServerFnOptions,
+  UseServerFnResult,
+  ServerFnMode,
+  BackendLanguage,
+  SwallowKitConfig,
+} from "./types";
+
+// Configuration
+export {
+  loadConfig,
+  generateConfig,
+  getBackendLanguage,
+  getFullConfig,
+  validateConfig,
+} from "./core/config";
+
+// Database - Zod-based schema sharing between frontend, backend, and Cosmos DB
+export { DatabaseClient, getDatabaseClient } from "./database/client";
+export { SchemaRepository, createRepository, TodoSchema, TodoRepository } from "./database/repository";
+export type { Todo } from "./database/repository";

package/src/machine/contracts.ts

@@ -0,0 +1,17 @@
+export interface MachineSuccessResponse<TData> {
+  ok: true;
+  command: string;
+  data: TData;
+}
+
+export interface MachineErrorResponse {
+  ok: false;
+  command: string;
+  error: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+}
+
+export type MachineResponse<TData> = MachineSuccessResponse<TData> | MachineErrorResponse;

package/src/machine/errors.ts

@@ -0,0 +1,34 @@
+export class MachineCommandError extends Error {
+  readonly code: string;
+  readonly details?: unknown;
+
+  constructor(code: string, message: string, details?: unknown) {
+    super(message);
+    this.name = "MachineCommandError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function toMachineError(error: unknown): { code: string; message: string; details?: unknown } {
+  if (error instanceof MachineCommandError) {
+    return {
+      code: error.code,
+      message: error.message,
+      ...(error.details === undefined ? {} : { details: error.details }),
+    };
+  }
+
+  if (error instanceof Error) {
+    return {
+      code: "internal-error",
+      message: error.message,
+    };
+  }
+
+  return {
+    code: "internal-error",
+    message: "Unknown error",
+    details: error,
+  };
+}

package/src/machine/index.ts

@@ -0,0 +1,173 @@
+import { Command, CommanderError } from "commander";
+import { createModelOperation } from "../core/operations/create-model";
+import { runMachineScaffoldOperation } from "../core/operations/scaffold-machine";
+import { loadProjectManifest } from "../core/project/manifest";
+import { validateProject } from "../core/project/validation";
+import { MachineErrorResponse, MachineResponse, MachineSuccessResponse } from "./contracts";
+import { MachineCommandError, toMachineError } from "./errors";
+
+function writeMachineResponse<TData>(response: MachineResponse<TData>): void {
+  process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+}
+
+function writeMachineSuccess<TData>(command: string, data: TData): void {
+  const response: MachineSuccessResponse<TData> = {
+    ok: true,
+    command,
+    data,
+  };
+  writeMachineResponse(response);
+}
+
+function writeMachineError(command: string, error: unknown): void {
+  const response: MachineErrorResponse = {
+    ok: false,
+    command,
+    error: toMachineError(error),
+  };
+  writeMachineResponse(response);
+}
+
+async function handleMachineAction<TData>(
+  command: string,
+  action: () => Promise<TData>
+): Promise<void> {
+  try {
+    writeMachineSuccess(command, await action());
+  } catch (error) {
+    writeMachineError(command, error);
+    process.exitCode = 1;
+  }
+}
+
+function createMachineProgram(): Command {
+  const program = new Command();
+  program
+    .name("swallowkit machine")
+    .description("SwallowKit machine-readable CLI for AI and MCP integrations")
+    .showHelpAfterError(false)
+    .configureOutput({
+      writeErr: () => undefined,
+      writeOut: () => undefined,
+    });
+
+  const inspect = new Command("inspect");
+  inspect
+    .command("project")
+    .description("Inspect SwallowKit project metadata")
+    .action(async () => {
+      await handleMachineAction("inspect-project", async () => {
+        const loaded = await loadProjectManifest();
+        return {
+          manifestSource: loaded.source,
+          diagnostics: loaded.diagnostics,
+          manifest: loaded.manifest,
+        };
+      });
+    });
+
+  inspect
+    .command("entities")
+    .description("Inspect SwallowKit entities")
+    .action(async () => {
+      await handleMachineAction("inspect-entities", async () => {
+        const loaded = await loadProjectManifest();
+        return {
+          manifestSource: loaded.source,
+          diagnostics: loaded.diagnostics,
+          entities: loaded.manifest.entities,
+        };
+      });
+    });
+
+  inspect
+    .command("routes")
+    .description("Inspect SwallowKit routes")
+    .action(async () => {
+      await handleMachineAction("inspect-routes", async () => {
+        const loaded = await loadProjectManifest();
+        return {
+          manifestSource: loaded.source,
+          diagnostics: loaded.diagnostics,
+          routes: loaded.manifest.routes,
+        };
+      });
+    });
+
+  const validate = new Command("validate");
+  validate
+    .command("project")
+    .description("Validate SwallowKit project metadata and conventions")
+    .action(async () => {
+      await handleMachineAction("validate-project", async () => validateProject());
+    });
+
+  const generate = new Command("generate");
+  generate
+    .command("model")
+    .description("Generate model templates with deterministic JSON output")
+    .argument("<names...>", "Model names to generate")
+    .option("--models-dir <dir>", "Models directory", "shared/models")
+    .option("--connector <name>", "Associate the models with a configured connector")
+    .option("--overwrite <mode>", "Overwrite policy: always | never", "never")
+    .action(async (names: string[], options: { modelsDir?: string; connector?: string; overwrite?: string }) => {
+      await handleMachineAction("generate-model", async () => {
+        if (options.overwrite !== "always" && options.overwrite !== "never") {
+          throw new MachineCommandError(
+            "invalid-overwrite-mode",
+            `Unsupported overwrite mode: ${options.overwrite}. Use "always" or "never".`
+          );
+        }
+
+        return createModelOperation({
+          names,
+          modelsDir: options.modelsDir,
+          connector: options.connector,
+          overwriteMode: options.overwrite,
+        });
+      });
+    });
+
+  generate
+    .command("scaffold")
+    .description("Generate scaffold artifacts with deterministic JSON output")
+    .argument("<model>", "Model file or model name")
+    .option("--functions-dir <dir>", "Functions directory", "functions")
+    .option("--api-dir <dir>", "API routes directory", "app/api")
+    .option("--api-only", "Generate only API artifacts", false)
+    .action(async (model: string, options: { functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+      await handleMachineAction("generate-scaffold", async () => runMachineScaffoldOperation({
+        model,
+        functionsDir: options.functionsDir,
+        apiDir: options.apiDir,
+        apiOnly: options.apiOnly,
+      }));
+    });
+
+  program.addCommand(inspect);
+  program.addCommand(validate);
+  program.addCommand(generate);
+  return program;
+}
+
+export function isMachineCommand(argv: string[]): boolean {
+  return argv[2] === "machine";
+}
+
+export async function runMachineCli(argv: string[] = process.argv): Promise<void> {
+  const program = createMachineProgram();
+  program.exitOverride();
+
+  try {
+    await program.parseAsync(argv.slice(3), { from: "user" });
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      writeMachineError("machine-parse", new MachineCommandError("invalid-command", error.message));
+      process.exitCode = Number.isFinite(error.exitCode) ? error.exitCode : 1;
+      return;
+    }
+
+    writeMachineError("machine-parse", error);
+    process.exitCode = 1;
+  }
+}