@spaceflow/core 0.1.1

package/src/shared/logger/renderers/tui.renderer.ts

@@ -0,0 +1,162 @@
+import chalk from "chalk";
+import ora from "ora";
+import logUpdate from "log-update";
+import type {
+  LogRenderer,
+  Spinner,
+  ProgressBar,
+  ProgressBarOptions,
+  TaskItem,
+  TaskControl,
+  TaskStatus,
+} from "../logger.interface";
+
+/** 进度条默认宽度 */
+const DEFAULT_BAR_WIDTH = 30;
+
+/** 任务状态图标 */
+const TASK_ICONS: Record<TaskStatus, string> = {
+  pending: chalk.gray("○"),
+  running: chalk.cyan("◌"),
+  success: chalk.green("✔"),
+  failed: chalk.red("✖"),
+  skipped: chalk.yellow("⊘"),
+};
+
+/** 渲染进度条字符串 */
+const renderBar = (current: number, total: number, width: number): string => {
+  const ratio = Math.min(current / total, 1);
+  const filled = Math.round(ratio * width);
+  const empty = width - filled;
+  const bar = chalk.green("█".repeat(filled)) + chalk.gray("░".repeat(empty));
+  const pct = Math.round(ratio * 100);
+  return `${bar} ${pct}%`;
+};
+
+/** TUI 模式渲染器：富交互输出，适合终端 */
+export class TuiRenderer implements LogRenderer {
+  info(prefix: string, message: string): void {
+    console.log(`${chalk.gray(prefix)} ${message}`);
+  }
+
+  success(prefix: string, message: string): void {
+    console.log(`${chalk.gray(prefix)} ${chalk.green("✔")} ${message}`);
+  }
+
+  warn(prefix: string, message: string): void {
+    console.warn(`${chalk.gray(prefix)} ${chalk.yellow("⚠")} ${chalk.yellow(message)}`);
+  }
+
+  error(prefix: string, message: string): void {
+    console.error(`${chalk.gray(prefix)} ${chalk.red("✖")} ${chalk.red(message)}`);
+  }
+
+  debug(prefix: string, message: string): void {
+    console.log(`${chalk.gray(prefix)} ${chalk.magenta("[DEBUG]")} ${chalk.gray(message)}`);
+  }
+
+  verbose(prefix: string, message: string): void {
+    console.log(`${chalk.gray(prefix)} ${chalk.gray(message)}`);
+  }
+
+  createSpinner(prefix: string, message: string): Spinner {
+    const spinner = ora({
+      text: `${chalk.gray(prefix)} ${message}`,
+      prefixText: "",
+    }).start();
+    return {
+      update: (msg: string) => {
+        spinner.text = `${chalk.gray(prefix)} ${msg}`;
+      },
+      succeed: (msg?: string) => {
+        spinner.succeed(`${chalk.gray(prefix)} ${msg ?? message}`);
+      },
+      fail: (msg?: string) => {
+        spinner.fail(`${chalk.gray(prefix)} ${msg ?? message}`);
+      },
+      stop: () => {
+        spinner.stop();
+      },
+    };
+  }
+
+  createProgressBar(prefix: string, options: ProgressBarOptions): ProgressBar {
+    const { total, label = "", width = DEFAULT_BAR_WIDTH } = options;
+    const tag = label ? `${label} ` : "";
+    logUpdate(`${chalk.gray(prefix)} ${tag}${renderBar(0, total, width)} 0/${total}`);
+    return {
+      update: (current: number, msg?: string) => {
+        const suffix = msg ? ` ${chalk.gray(msg)}` : "";
+        logUpdate(
+          `${chalk.gray(prefix)} ${tag}${renderBar(current, total, width)} ${current}/${total}${suffix}`,
+        );
+      },
+      finish: (msg?: string) => {
+        const suffix = msg ? ` ${msg}` : "";
+        logUpdate.done();
+        console.log(
+          `${chalk.gray(prefix)} ${chalk.green("✔")} ${tag}${total}/${total} (100%)${suffix}`,
+        );
+      },
+    };
+  }
+
+  async runTasks<T>(prefix: string, items: TaskItem<T>[]): Promise<T[]> {
+    const enabledItems = items.filter((item) => item.enabled !== false);
+    const statuses: TaskStatus[] = enabledItems.map(() => "pending");
+    const messages: string[] = enabledItems.map((item) => item.title);
+    const results: T[] = [];
+    const renderTaskList = (): string => {
+      return enabledItems
+        .map((item, i) => {
+          const icon = TASK_ICONS[statuses[i]];
+          const title = statuses[i] === "running" ? chalk.cyan(item.title) : item.title;
+          const suffix = messages[i] !== item.title ? chalk.gray(` ${messages[i]}`) : "";
+          return `${chalk.gray(prefix)} ${icon} ${title}${suffix}`;
+        })
+        .join("\n");
+    };
+    logUpdate(renderTaskList());
+    for (let i = 0; i < enabledItems.length; i++) {
+      statuses[i] = "running";
+      logUpdate(renderTaskList());
+      let skipped = false;
+      let skipReason = "";
+      const control: TaskControl = {
+        update: (msg: string) => {
+          messages[i] = msg;
+          logUpdate(renderTaskList());
+        },
+        skip: (reason?: string) => {
+          skipped = true;
+          skipReason = reason ?? "";
+        },
+      };
+      try {
+        const ctx = (results.length > 0 ? results[results.length - 1] : undefined) as T;
+        const result = await enabledItems[i].task(ctx, control);
+        if (skipped) {
+          statuses[i] = "skipped";
+          messages[i] = skipReason ? `${enabledItems[i].title} (${skipReason})` : enabledItems[i].title;
+        } else {
+          statuses[i] = "success";
+          messages[i] = enabledItems[i].title;
+        }
+        results.push(result);
+      } catch (err) {
+        statuses[i] = "failed";
+        messages[i] = err instanceof Error ? err.message : String(err);
+        logUpdate(renderTaskList());
+        logUpdate.done();
+        throw err;
+      }
+      logUpdate(renderTaskList());
+    }
+    logUpdate.done();
+    return results;
+  }
+
+  table(_prefix: string, data: Record<string, unknown>[]): void {
+    console.table(data);
+  }
+}

package/src/shared/mcp/index.ts

@@ -0,0 +1,332 @@
+/**
+ * MCP (Model Context Protocol) 支持模块
+ *
+ * 提供装饰器和基础设施，用于在服务中定义 MCP 工具
+ *
+ * 使用方式：
+ * ```typescript
+ * class ListRulesInput {
+ *   @ApiPropertyOptional({ description: "项目目录" })
+ *   @IsString()
+ *   @IsOptional()
+ *   cwd?: string;
+ * }
+ *
+ * @McpServer({ name: "review-rules", version: "1.0.0" })
+ * export class ReviewMcpService {
+ *   @McpTool({
+ *     name: "list_rules",
+ *     description: "获取所有审查规则",
+ *     dto: ListRulesInput,
+ *   })
+ *   async listRules(input: ListRulesInput) {
+ *     return { rules: [...] };
+ *   }
+ * }
+ * ```
+ */
+
+import "reflect-metadata";
+import { Injectable } from "@nestjs/common";
+
+/** MCP 服务元数据 key（使用 Symbol 确保唯一性） */
+export const MCP_SERVER_METADATA = Symbol.for("spaceflow:mcp:server");
+
+/** MCP 工具元数据 key（使用 Symbol 确保唯一性） */
+export const MCP_TOOL_METADATA = Symbol.for("spaceflow:mcp:tool");
+
+/** JSON Schema 类型 */
+export interface JsonSchema {
+  type: string;
+  properties?: Record<string, JsonSchema & { description?: string }>;
+  required?: string[];
+  items?: JsonSchema;
+  description?: string;
+}
+
+/** MCP 服务定义 */
+export interface McpServerDefinition {
+  /** 服务名称 */
+  name: string;
+  /** 服务版本 */
+  version?: string;
+  /** 服务描述 */
+  description?: string;
+}
+
+/** Swagger 元数据常量 */
+const SWAGGER_API_MODEL_PROPERTIES = "swagger/apiModelProperties";
+const SWAGGER_API_MODEL_PROPERTIES_ARRAY = "swagger/apiModelPropertiesArray";
+
+/**
+ * 从 @nestjs/swagger 的 @ApiProperty / @ApiPropertyOptional 元数据生成 JSON Schema
+ * 直接读取 swagger 装饰器存储的 reflect-metadata，无需自定义装饰器
+ */
+export function dtoToJsonSchema(dtoClass: new (...args: any[]) => any): JsonSchema {
+  const prototype = dtoClass.prototype;
+
+  // 读取属性名列表（swagger 存储格式为 ":propertyName"）
+  const propertyKeys: string[] = (
+    Reflect.getMetadata(SWAGGER_API_MODEL_PROPERTIES_ARRAY, prototype) || []
+  ).map((key: string) => key.replace(/^:/, ""));
+
+  const properties: Record<string, any> = {};
+  const required: string[] = [];
+
+  for (const key of propertyKeys) {
+    const meta = Reflect.getMetadata(SWAGGER_API_MODEL_PROPERTIES, prototype, key) || {};
+
+    // 推断 JSON Schema type
+    const typeMap: Record<string, string> = {
+      String: "string",
+      Number: "number",
+      Boolean: "boolean",
+      Array: "array",
+      Object: "object",
+    };
+
+    let schemaType = meta.type;
+    // meta.type 可能是构造函数（如 Boolean）或字符串（如 "boolean"）
+    if (typeof schemaType === "function") {
+      schemaType = typeMap[schemaType.name] || "string";
+    }
+    // 如果 swagger 没有显式 type，从 class-validator 元数据推断
+    if (!schemaType) {
+      try {
+        const { getMetadataStorage } = require("class-validator");
+        const validationMetas = getMetadataStorage().getTargetValidationMetadatas(
+          dtoClass,
+          "",
+          false,
+          false,
+        );
+        const validatorTypeMap: Record<string, string> = {
+          isString: "string",
+          isNumber: "number",
+          isBoolean: "boolean",
+          isArray: "array",
+          isObject: "object",
+          isInt: "number",
+          isEnum: "string",
+        };
+        const propMeta = validationMetas.find(
+          (m: any) => m.propertyName === key && validatorTypeMap[m.name],
+        );
+        if (propMeta) {
+          schemaType = validatorTypeMap[propMeta.name];
+        }
+      } catch {
+        // class-validator 不可用时忽略
+      }
+    }
+    // 最后从 reflect-metadata 的 design:type 推断
+    if (!schemaType) {
+      const reflectedType = Reflect.getMetadata("design:type", prototype, key);
+      if (reflectedType) {
+        schemaType = typeMap[reflectedType.name] || "string";
+      }
+    }
+
+    const prop: Record<string, any> = {};
+    if (schemaType) prop.type = schemaType;
+    if (meta.description) prop.description = meta.description;
+    if (meta.default !== undefined) prop.default = meta.default;
+    if (meta.enum) prop.enum = meta.enum;
+    if (meta.example !== undefined) prop.example = meta.example;
+
+    properties[key] = prop;
+
+    // required 判断：swagger 的 @ApiProperty 默认 required=true，@ApiPropertyOptional 为 false
+    if (meta.required !== false) {
+      required.push(key);
+    }
+  }
+
+  const schema: JsonSchema = { type: "object", properties };
+  if (required.length > 0) schema.required = required;
+  return schema;
+}
+
+/** MCP 工具定义 */
+export interface McpToolDefinition {
+  /** 工具名称 */
+  name: string;
+  /** 工具描述 */
+  description: string;
+  /** 输入参数 schema (JSON Schema 格式，与 dto 二选一) */
+  inputSchema?: JsonSchema;
+  /** 输入参数 DTO 类（与 inputSchema 二选一，优先级高于 inputSchema） */
+  dto?: new (...args: any[]) => any;
+}
+
+/** 存储的工具元数据 */
+export interface McpToolMetadata extends McpToolDefinition {
+  /** 方法名 */
+  methodName: string;
+}
+
+/**
+ * MCP 服务装饰器
+ * 标记一个类为 MCP 服务，内部自动应用 @Injectable()
+ *
+ * @example
+ * ```typescript
+ * @McpServer({ name: "review-rules", version: "1.0.0" })
+ * export class ReviewMcpService {
+ *   @McpTool({ name: "list_rules", description: "获取规则" })
+ *   async listRules() { ... }
+ * }
+ * ```
+ */
+export function McpServer(definition: McpServerDefinition): ClassDecorator {
+  return (target: Function) => {
+    // 应用 @Injectable() 装饰器
+    Injectable()(target);
+    // 使用静态属性存储元数据（跨模块可访问）
+    (target as any).__mcp_server__ = definition;
+  };
+}
+
+/**
+ * MCP 工具装饰器
+ * 标记一个方法为 MCP 工具
+ */
+export function McpTool(definition: McpToolDefinition): MethodDecorator {
+  return (target: object, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {
+    const constructor = target.constructor as any;
+    // 使用静态属性存储工具列表（跨模块可访问）
+    if (!constructor.__mcp_tools__) {
+      constructor.__mcp_tools__ = [];
+    }
+
+    // 如果提供了 dto，自动从 swagger 元数据生成 inputSchema
+    const resolvedDefinition = { ...definition };
+    if (resolvedDefinition.dto) {
+      resolvedDefinition.inputSchema = dtoToJsonSchema(resolvedDefinition.dto);
+    }
+
+    constructor.__mcp_tools__.push({
+      ...resolvedDefinition,
+      methodName: String(propertyKey),
+    });
+  };
+}
+
+/**
+ * 检查一个类是否是 MCP 服务
+ */
+export function isMcpServer(target: any): boolean {
+  const constructor = target?.constructor || target;
+  return !!constructor?.__mcp_server__;
+}
+
+/**
+ * 获取 MCP 服务元数据
+ */
+export function getMcpServerMetadata(target: any): McpServerDefinition | undefined {
+  const constructor = target?.constructor || target;
+  return constructor?.__mcp_server__;
+}
+
+/**
+ * 从服务类获取所有 MCP 工具定义
+ */
+export function getMcpTools(target: any): McpToolMetadata[] {
+  const constructor = target?.constructor || target;
+  return constructor?.__mcp_tools__ || [];
+}
+
+/**
+ * MCP Server 运行器
+ * 收集服务中的 MCP 工具并启动 stdio 服务
+ */
+export async function runMcpServer(
+  service: any,
+  serverInfo: { name: string; version: string },
+): Promise<void> {
+  const tools = getMcpTools(service);
+
+  if (tools.length === 0) {
+    console.error("没有找到 MCP 工具定义");
+    process.exit(1);
+  }
+
+  // 动态导入 MCP SDK（避免在不需要时加载）
+  const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+
+  const server = new McpServer(serverInfo);
+
+  // 注册所有工具（使用 v1 API: server.tool）
+  for (const tool of tools) {
+    // v1 API: server.tool(name, description, schema, callback)
+    // 使用工具定义中的 inputSchema 转为 zod，如果没有则传空对象
+    const schema = tool.inputSchema ? jsonSchemaToZod(tool.inputSchema) : {};
+    server.tool(tool.name, tool.description, schema, async (args: any) => {
+      try {
+        const result = await service[tool.methodName](args || {});
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  /**
+   * 将 JSON Schema 转换为简单的 zod 对象（MCP SDK 需要 zod）
+   * 仅处理顶层 properties，满足 MCP 工具注册需求
+   */
+  function jsonSchemaToZod(jsonSchema: JsonSchema): Record<string, any> {
+    const { z } = require("zod") as typeof import("zod");
+    if (!jsonSchema.properties) return {};
+
+    const shape: Record<string, any> = {};
+    const requiredFields = jsonSchema.required || [];
+
+    for (const [key, prop] of Object.entries(jsonSchema.properties)) {
+      let field: any;
+      switch (prop.type) {
+        case "number":
+          field = z.number();
+          break;
+        case "boolean":
+          field = z.boolean();
+          break;
+        case "array":
+          field = z.array(z.any());
+          break;
+        case "object":
+          field = z.object({});
+          break;
+        default:
+          field = z.string();
+      }
+      if (prop.description) field = field.describe(prop.description);
+      if (!requiredFields.includes(key)) field = field.optional();
+      shape[key] = field;
+    }
+
+    return shape;
+  }
+
+  // 启动 stdio 传输
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error(`MCP Server "${serverInfo.name}" started with ${tools.length} tools`);
+}

package/src/shared/output/index.ts

@@ -0,0 +1,2 @@
+export * from "./output.service";
+export * from "./output.module";

package/src/shared/output/output.module.ts

@@ -0,0 +1,9 @@
+import { Global, Module } from "@nestjs/common";
+import { OutputService } from "./output.service";
+
+@Global()
+@Module({
+  providers: [OutputService],
+  exports: [OutputService],
+})
+export class OutputModule {}

package/src/shared/output/output.service.ts

@@ -0,0 +1,97 @@
+import { Injectable, Scope } from "@nestjs/common";
+import { randomUUID } from "crypto";
+
+const OUTPUT_MARKER_START = "::spaceflow-output::";
+const OUTPUT_MARKER_END = "::end::";
+
+/**
+ * OutputService - 用于标准化命令输出
+ *
+ * 命令可以通过此服务设置输出值，这些值会在命令执行完成后
+ * 以特定格式输出到 stdout，供 CI 流程中的其他步骤使用。
+ *
+ * 输出格式: ::spaceflow-output::{"key":"value","_cacheId":"uuid"}::end::
+ *
+ * _cacheId 用于 actions/cache 在不同 job 之间传递数据
+ *
+ * 使用示例:
+ * ```typescript
+ * @Injectable()
+ * export class MyService {
+ *   constructor(protected readonly output: OutputService) {}
+ *
+ *   async execute() {
+ *     // ... 执行逻辑
+ *     this.output.set("version", "1.0.0");
+ *     this.output.set("tag", "v1.0.0");
+ *   }
+ * }
+ * ```
+ */
+@Injectable({ scope: Scope.DEFAULT })
+export class OutputService {
+  protected outputs: Record<string, string> = {};
+  protected cacheId: string = randomUUID();
+
+  /**
+   * 设置单个输出值
+   */
+  set(key: string, value: string | number | boolean): void {
+    this.outputs[key] = String(value);
+  }
+
+  /**
+   * 批量设置输出值
+   */
+  setAll(values: Record<string, string | number | boolean>): void {
+    for (const [key, value] of Object.entries(values)) {
+      this.set(key, value);
+    }
+  }
+
+  /**
+   * 获取所有输出值
+   */
+  getAll(): Record<string, string> {
+    return { ...this.outputs };
+  }
+
+  /**
+   * 清空所有输出值
+   */
+  clear(): void {
+    this.outputs = {};
+  }
+
+  /**
+   * 输出所有值到 stdout（带标记格式）
+   * 通常在命令执行完成后调用
+   * _cacheId 会被 actions 捕获并用于 actions/cache
+   */
+  flush(): void {
+    if (Object.keys(this.outputs).length === 0) {
+      return;
+    }
+
+    // 输出到 stdout，包含 cacheId 供 actions/cache 使用
+    const outputWithCache = { ...this.outputs, _cacheId: this.cacheId };
+    const json = JSON.stringify(outputWithCache);
+    console.log(`${OUTPUT_MARKER_START}${json}${OUTPUT_MARKER_END}`);
+  }
+
+  /**
+   * 检查是否有输出值
+   */
+  hasOutputs(): boolean {
+    return Object.keys(this.outputs).length > 0;
+  }
+
+  /**
+   * 获取当前 cacheId
+   */
+  getCacheId(): string {
+    return this.cacheId;
+  }
+}
+
+export { OUTPUT_MARKER_START, OUTPUT_MARKER_END };