@vafast/cli 0.1.1

package/README.md

@@ -0,0 +1,140 @@
+# @vafast/cli
+
+Vafast CLI 工具，提供 API 类型同步等功能。
+
+## 安装
+
+```bash
+npm install -D @vafast/cli
+```
+
+## 命令
+
+### `vafast sync` - 同步 API 类型
+
+从服务端获取 API 契约，生成 TypeScript 类型定义文件。
+
+```bash
+# 基本用法
+npx vafast sync --url http://localhost:3000
+
+# 指定输出文件
+npx vafast sync --url http://localhost:3000 --out src/types/api.ts
+
+# 指定契约端点（默认 /__contract__）
+npx vafast sync --url http://localhost:3000 --endpoint /api/contract
+```
+
+#### 选项
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--url <url>` | 服务端地址（必填） | - |
+| `--out <path>` | 输出文件路径 | `src/api.generated.ts` |
+| `--endpoint <path>` | 契约接口路径 | `/__contract__` |
+
+## 工作流程
+
+### 1. 服务端配置
+
+在 vafast 服务端暴露契约接口：
+
+```typescript
+import { defineRoutes, createContractHandler } from 'vafast'
+
+const routes = defineRoutes([
+  // 你的路由定义...
+])
+
+// 添加契约接口
+const allRoutes = [
+  ...routes,
+  {
+    method: 'GET',
+    path: '/__contract__',
+    handler: createContractHandler(routes)
+  }
+]
+```
+
+### 2. 客户端同步
+
+```bash
+npx vafast sync --url http://localhost:3000
+```
+
+### 3. 使用生成的类型
+
+```typescript
+import { eden } from '@vafast/api-client'
+import type { Api } from './api.generated'
+
+const api = eden<Api>('http://localhost:3000')
+
+// 类型安全的调用
+const { data, error } = await api.users.get({ page: 1 })
+```
+
+## 自动化
+
+在 `package.json` 中配置脚本：
+
+```json
+{
+  "scripts": {
+    "sync": "vafast sync --url $API_URL",
+    "dev": "npm run sync && vite",
+    "build": "npm run sync && vite build"
+  }
+}
+```
+
+## 生成的类型示例
+
+输入契约：
+
+```json
+{
+  "routes": [
+    {
+      "method": "GET",
+      "path": "/users",
+      "schema": { "query": { "type": "object", "properties": { "page": { "type": "number" } } } }
+    },
+    {
+      "method": "POST",
+      "path": "/users",
+      "schema": { "body": { "type": "object", "properties": { "name": { "type": "string" } } } }
+    }
+  ]
+}
+```
+
+生成的类型：
+
+```typescript
+export type Api = {
+  users: {
+    get: {
+      query: { page?: number }
+      return: unknown
+    }
+    post: {
+      body: { name?: string }
+      return: unknown
+    }
+  }
+}
+```
+
+## 注意事项
+
+1. **返回类型**：当前契约不包含返回类型信息，生成的类型中返回值为 `unknown`。如需完整类型推断，建议使用 monorepo 共享路由定义。
+
+2. **服务器必须运行**：执行 `sync` 命令时，服务端必须在运行并暴露契约接口。
+
+3. **不要手动修改**：生成的文件会被覆盖，请勿手动修改。
+
+## License
+
+MIT

package/bin/vafast.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import('../dist/cli.js')

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Vafast CLI
+ *
+ * 命令：
+ * - vafast sync --url <url> [--out <path>]  同步 API 类型
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,21 @@
+import { syncTypes } from "./sync-DU-mhmR1.js";
+import { cac } from "cac";
+
+//#region src/cli.ts
+const cli = cac("vafast");
+cli.command("sync", "从服务端同步 API 类型定义").option("--url <url>", "服务端地址（必填）").option("--out <path>", "输出文件路径", { default: "src/api.generated.ts" }).option("--endpoint <path>", "API Spec 接口路径", { default: "/api-spec" }).action(async (options) => {
+	if (!options.url) {
+		console.error("❌ 请指定服务端地址：--url <url>");
+		process.exit(1);
+	}
+	await syncTypes({
+		url: options.url,
+		output: options.out,
+		endpoint: options.endpoint
+	});
+});
+cli.help();
+cli.version("0.1.0");
+cli.parse();
+
+//#endregion

package/dist/codegen/schema-to-type.d.ts

@@ -0,0 +1,9 @@
+/**
+ * JSON Schema → TypeScript 类型转换器
+ *
+ * 将 TypeBox 生成的 JSON Schema 转换为 TypeScript 类型字符串
+ */
+/**
+ * 将 JSON Schema 转换为 TypeScript 类型字符串
+ */
+export declare function schemaToType(schema: unknown): string;

package/dist/commands/sync.d.ts

@@ -0,0 +1,15 @@
+/**
+ * sync 命令实现
+ *
+ * 从服务端拉取契约并生成 TypeScript 类型定义
+ */
+interface SyncOptions {
+    url: string;
+    output: string;
+    endpoint: string;
+}
+/**
+ * 同步 API 类型
+ */
+export declare function syncTypes(options: SyncOptions): Promise<void>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @vafast/cli
+ *
+ * Vafast CLI 工具，提供类型同步等功能
+ */
+export { syncTypes } from './commands/sync';
+export { schemaToType } from './codegen/schema-to-type';

package/dist/index.js

@@ -0,0 +1,3 @@
+import { schemaToType, syncTypes } from "./sync-DU-mhmR1.js";
+
+export { schemaToType, syncTypes };

package/dist/sync-DU-mhmR1.js

@@ -0,0 +1,182 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+//#region src/codegen/schema-to-type.ts
+/**
+* 将 JSON Schema 转换为 TypeScript 类型字符串
+*/
+function schemaToType(schema) {
+	if (!schema || typeof schema !== "object") return "unknown";
+	const s = schema;
+	if (s.const !== void 0) return JSON.stringify(s.const);
+	if (s.enum) return s.enum.map((v) => JSON.stringify(v)).join(" | ");
+	if (s.anyOf) return s.anyOf.map(schemaToType).join(" | ");
+	if (s.oneOf) return s.oneOf.map(schemaToType).join(" | ");
+	if (s.allOf) return s.allOf.map(schemaToType).join(" & ");
+	switch (s.type) {
+		case "string": return "string";
+		case "number":
+		case "integer": return "number";
+		case "boolean": return "boolean";
+		case "null": return "null";
+		case "array": return arrayToType(s);
+		case "object": return objectToType(s);
+		default:
+			if (s.properties) return objectToType(s);
+			return "unknown";
+	}
+}
+/**
+* 数组类型转换
+*/
+function arrayToType(schema) {
+	if (schema.items) {
+		const itemType = schemaToType(schema.items);
+		return `${itemType}[]`;
+	}
+	return "unknown[]";
+}
+/**
+* 对象类型转换
+*/
+function objectToType(schema) {
+	if (!schema.properties) {
+		if (schema.additionalProperties === true) return "Record<string, unknown>";
+		if (typeof schema.additionalProperties === "object") {
+			const valueType = schemaToType(schema.additionalProperties);
+			return `Record<string, ${valueType}>`;
+		}
+		return "{}";
+	}
+	const required = new Set(schema.required || []);
+	const props = [];
+	for (const [key, propSchema] of Object.entries(schema.properties)) {
+		const propType = schemaToType(propSchema);
+		const optional = required.has(key) ? "" : "?";
+		props.push(`${key}${optional}: ${propType}`);
+	}
+	if (props.length === 0) return "{}";
+	return `{ ${props.join("; ")} }`;
+}
+
+//#endregion
+//#region src/commands/sync.ts
+/**
+* 同步 API 类型
+*/
+async function syncTypes(options) {
+	const { url, output, endpoint } = options;
+	console.log(`🔄 正在从 ${url}${endpoint} 获取契约...`);
+	const contractUrl = new URL(endpoint, url).toString();
+	let contract;
+	try {
+		const response = await fetch(contractUrl);
+		if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+		contract = await response.json();
+	} catch (error) {
+		const err = error instanceof Error ? error : new Error(String(error));
+		console.error(`❌ 获取契约失败: ${err.message}`);
+		process.exit(1);
+	}
+	console.log(`✅ 获取到 ${contract.routes.length} 个路由`);
+	const typeContent = generateTypeDefinition(contract);
+	const outputDir = dirname(output);
+	mkdirSync(outputDir, { recursive: true });
+	writeFileSync(output, typeContent, "utf-8");
+	console.log(`✅ 类型定义已生成: ${output}`);
+	console.log("");
+	console.log("📝 使用方式:");
+	console.log(`   import { eden } from '@vafast/api-client'`);
+	console.log(`   import type { Api } from './${output.replace(/\.ts$/, "")}'`);
+	console.log(`   const api = eden<Api>('${url}')`);
+}
+/**
+* 生成类型定义文件内容
+*/
+function generateTypeDefinition(contract) {
+	const lines = [];
+	lines.push("/**");
+	lines.push(" * 自动生成的 API 类型定义");
+	lines.push(` * 生成时间: ${contract.generatedAt}`);
+	lines.push(` * 版本: ${contract.version}`);
+	lines.push(" * ");
+	lines.push(" * ⚠️ 请勿手动修改此文件，使用 `vafast sync` 重新生成");
+	lines.push(" */");
+	lines.push("");
+	const routeTree = buildRouteTree(contract.routes);
+	lines.push("export type Api = {");
+	lines.push(generateRouteTreeType(routeTree, 1));
+	lines.push("}");
+	lines.push("");
+	return lines.join("\n");
+}
+/**
+* 构建路由树
+*/
+function buildRouteTree(routes) {
+	const root = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		const segments = route.path.split("/").filter(Boolean);
+		let current = root;
+		for (let i = 0; i < segments.length; i++) {
+			const segment = segments[i];
+			const isDynamic = segment.startsWith(":");
+			const key = isDynamic ? ":id" : segment;
+			if (!current.has(key)) current.set(key, {
+				methods: /* @__PURE__ */ new Map(),
+				children: /* @__PURE__ */ new Map(),
+				isDynamic
+			});
+			const node = current.get(key);
+			if (i === segments.length - 1) node.methods.set(route.method.toLowerCase(), route);
+			current = node.children;
+		}
+	}
+	return root;
+}
+/**
+* 生成路由树的类型定义
+*/
+function generateRouteTreeType(tree, indent) {
+	const lines = [];
+	const pad = "  ".repeat(indent);
+	for (const [key, node] of tree) {
+		if (key === ":id") lines.push(`${pad}':id': {`);
+		else lines.push(`${pad}${key}: {`);
+		for (const [method, route] of node.methods) {
+			const methodType = generateMethodType(route);
+			if (route.description) lines.push(`${pad}  /** ${route.description} */`);
+			lines.push(`${pad}  ${method}: ${methodType}`);
+		}
+		if (node.children.size > 0) {
+			const childContent = generateRouteTreeType(node.children, indent + 1);
+			if (childContent) lines.push(childContent);
+		}
+		lines.push(`${pad}}`);
+	}
+	return lines.join("\n");
+}
+/**
+* 生成方法类型
+*/
+function generateMethodType(route) {
+	const parts = [];
+	if (route.schema?.query) {
+		const queryType = schemaToType(route.schema.query);
+		parts.push(`query: ${queryType}`);
+	}
+	if (route.schema?.body) {
+		const bodyType = schemaToType(route.schema.body);
+		parts.push(`body: ${bodyType}`);
+	}
+	if (route.schema?.params) {
+		const paramsType = schemaToType(route.schema.params);
+		parts.push(`params: ${paramsType}`);
+	}
+	parts.push("return: unknown");
+	if (parts.length === 1) return `{ ${parts[0]} }`;
+	return `{\n      ${parts.join("\n      ")}\n    }`;
+}
+
+//#endregion
+export { schemaToType, syncTypes };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@vafast/cli",
+  "version": "0.1.1",
+  "description": "Vafast CLI - 类型同步和开发工具",
+  "type": "module",
+  "bin": {
+    "vafast": "./bin/vafast.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "release": "npm run build && npm run test && npx bumpp && npm publish --access=public"
+  },
+  "keywords": [
+    "vafast",
+    "cli",
+    "typescript",
+    "codegen",
+    "api-client"
+  ],
+  "author": "vafast",
+  "license": "MIT",
+  "dependencies": {
+    "cac": "^6.7.14"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsdown": "^0.2.0",
+    "typescript": "^5.4.5",
+    "vafast": "^0.5.1",
+    "vitest": "^2.0.0"
+  }
+}