@spaceflow/core 0.1.1

package/src/shared/git-sdk/git-sdk.service.ts

@@ -0,0 +1,235 @@
+import { Injectable } from "@nestjs/common";
+import { spawn, execSync } from "child_process";
+import type { GitCommit, GitChangedFile, GitDiffFile, GitRunOptions } from "./git-sdk.types";
+import { mapGitStatus, parseDiffText } from "./git-sdk-diff.utils";
+
+@Injectable()
+export class GitSdkService {
+  protected readonly defaultOptions: GitRunOptions = {
+    cwd: process.cwd(),
+    maxBuffer: 10 * 1024 * 1024, // 10MB
+  };
+
+  runCommand(args: string[], options?: GitRunOptions): Promise<string> {
+    const opts = { ...this.defaultOptions, ...options };
+
+    return new Promise((resolve, reject) => {
+      const child = spawn("git", args, {
+        cwd: opts.cwd,
+        env: process.env,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+
+      let stdout = "";
+      let stderr = "";
+
+      child.stdout.on("data", (data) => {
+        stdout += data.toString();
+      });
+
+      child.stderr.on("data", (data) => {
+        stderr += data.toString();
+      });
+
+      child.on("close", (code) => {
+        if (code === 0) {
+          resolve(stdout);
+        } else {
+          reject(new Error(`Git 命令失败 (${code}): ${stderr}`));
+        }
+      });
+
+      child.on("error", (err) => {
+        reject(err);
+      });
+    });
+  }
+
+  runCommandSync(args: string[], options?: GitRunOptions): string {
+    const opts = { ...this.defaultOptions, ...options };
+    return execSync(`git ${args.join(" ")}`, {
+      cwd: opts.cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      maxBuffer: opts.maxBuffer,
+    });
+  }
+
+  getRemoteUrl(options?: GitRunOptions): string | null {
+    try {
+      return this.runCommandSync(["remote", "get-url", "origin"], options).trim();
+    } catch {
+      return null;
+    }
+  }
+
+  getCurrentBranch(options?: GitRunOptions): string | null {
+    try {
+      return this.runCommandSync(["rev-parse", "--abbrev-ref", "HEAD"], options).trim();
+    } catch {
+      return null;
+    }
+  }
+
+  getDefaultBranch(options?: GitRunOptions): string {
+    try {
+      const result = this.runCommandSync(
+        ["symbolic-ref", "refs/remotes/origin/HEAD"],
+        options,
+      ).trim();
+      return result.replace("refs/remotes/origin/", "");
+    } catch {
+      // 回退到常见默认分支
+      for (const branch of ["main", "master"]) {
+        try {
+          this.runCommandSync(["rev-parse", "--verify", `origin/${branch}`], options);
+          return branch;
+        } catch {
+          continue;
+        }
+      }
+      return "main";
+    }
+  }
+
+  parseRepositoryFromRemoteUrl(remoteUrl: string): { owner: string; repo: string } | null {
+    const match = remoteUrl.match(/[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?$/);
+    if (match) {
+      return { owner: match[1], repo: match[2] };
+    }
+    return null;
+  }
+
+  async getChangedFilesBetweenRefs(
+    baseRef: string,
+    headRef: string,
+    options?: GitRunOptions,
+  ): Promise<GitChangedFile[]> {
+    const resolvedBase = await this.resolveRef(baseRef, options);
+    const resolvedHead = await this.resolveRef(headRef, options);
+    const result = await this.runCommand(
+      ["diff", "--name-status", `${resolvedBase}..${resolvedHead}`],
+      options,
+    );
+
+    const files: GitChangedFile[] = [];
+    const lines = result.trim().split("\n").filter(Boolean);
+
+    for (const line of lines) {
+      const [status, filename] = line.split("\t");
+      files.push({
+        filename,
+        status: mapGitStatus(status),
+      });
+    }
+
+    return files;
+  }
+
+  /**
+   * 获取两个 ref 之间的 diff（包含 patch 信息）
+   * @param baseRef 基准 ref
+   * @param headRef 目标 ref
+   * @param options 运行选项
+   * @returns 包含 filename 和 patch 的文件列表
+   */
+  async getDiffBetweenRefs(
+    baseRef: string,
+    headRef: string,
+    options?: GitRunOptions,
+  ): Promise<GitDiffFile[]> {
+    const resolvedBase = await this.resolveRef(baseRef, options);
+    const resolvedHead = await this.resolveRef(headRef, options);
+    const result = await this.runCommand(["diff", `${resolvedBase}..${resolvedHead}`], options);
+
+    return parseDiffText(result);
+  }
+
+  async getCommitsBetweenRefs(
+    baseRef: string,
+    headRef: string,
+    options?: GitRunOptions,
+  ): Promise<GitCommit[]> {
+    const resolvedBase = await this.resolveRef(baseRef, options);
+    const resolvedHead = await this.resolveRef(headRef, options);
+    const result = await this.runCommand(
+      ["log", "--format=%H|%s|%an|%ae|%aI", `${resolvedBase}..${resolvedHead}`],
+      options,
+    );
+
+    const commits: GitCommit[] = [];
+    const lines = result.trim().split("\n").filter(Boolean);
+
+    for (const line of lines) {
+      const [sha, message, authorName, authorEmail, date] = line.split("|");
+      commits.push({
+        sha,
+        message,
+        author: {
+          name: authorName,
+          email: authorEmail,
+          date,
+        },
+      });
+    }
+
+    return commits;
+  }
+
+  async getFilesForCommit(sha: string, options?: GitRunOptions): Promise<string[]> {
+    const result = await this.runCommand(["show", "--name-only", "--format=", sha], options);
+    return result.trim().split("\n").filter(Boolean);
+  }
+
+  async getFileContent(ref: string, filename: string, options?: GitRunOptions): Promise<string> {
+    return this.runCommand(["show", `${ref}:${filename}`], options);
+  }
+
+  getCommitDiff(sha: string, options?: GitRunOptions): GitDiffFile[] {
+    try {
+      const output = this.runCommandSync(["show", "--format=", "--patch", sha], options);
+      return parseDiffText(output);
+    } catch (error) {
+      console.warn(`⚠️ git show 失败: ${error instanceof Error ? error.message : String(error)}`);
+      return [];
+    }
+  }
+
+  /**
+   * 解析 ref，支持本地分支、远程分支、commit SHA
+   * 优先级：commit SHA > 本地分支 > origin/分支 > fetch后重试 > 原始值
+   */
+  async resolveRef(ref: string, options?: GitRunOptions): Promise<string> {
+    if (!ref) {
+      throw new Error(`resolveRef: ref 参数不能为空。调用栈: ${new Error().stack}`);
+    }
+    if (/^[0-9a-f]{7,40}$/i.test(ref)) {
+      return ref;
+    }
+    if (ref.startsWith("origin/")) {
+      return ref;
+    }
+    try {
+      await this.runCommand(["rev-parse", "--verify", ref], options);
+      return ref;
+    } catch {
+      // 本地分支不存在
+    }
+    try {
+      await this.runCommand(["rev-parse", "--verify", `origin/${ref}`], options);
+      return `origin/${ref}`;
+    } catch {
+      // origin/分支也不存在
+    }
+    try {
+      await this.runCommand(
+        ["fetch", "origin", `${ref}:refs/remotes/origin/${ref}`, "--depth=1"],
+        options,
+      );
+      return `origin/${ref}`;
+    } catch {
+      // fetch 失败
+    }
+    return ref;
+  }
+}

package/src/shared/git-sdk/git-sdk.types.ts

@@ -0,0 +1,25 @@
+export interface GitCommit {
+  sha: string;
+  message: string;
+  author?: {
+    name?: string;
+    email?: string;
+    date?: string;
+  };
+}
+
+export interface GitChangedFile {
+  filename: string;
+  status: string;
+  patch?: string;
+}
+
+export interface GitDiffFile {
+  filename: string;
+  patch: string;
+}
+
+export interface GitRunOptions {
+  cwd?: string;
+  maxBuffer?: number;
+}

package/src/shared/git-sdk/index.ts

@@ -0,0 +1,4 @@
+export * from "./git-sdk.types";
+export * from "./git-sdk-diff.utils";
+export { GitSdkService } from "./git-sdk.service";
+export { GitSdkModule } from "./git-sdk.module";

package/src/shared/i18n/i18n.spec.ts

@@ -0,0 +1,96 @@
+import { initI18n, t, addLocaleResources, resetI18n } from "./i18n";
+import zhCN from "../../locales/zh-cn/translation.json";
+import en from "../../locales/en/translation.json";
+
+beforeEach(() => {
+  resetI18n();
+});
+
+describe("initI18n", () => {
+  it("默认初始化为 zh-CN", () => {
+    initI18n("zh-CN");
+    expect(t("common.options.dryRun")).toBe(zhCN["common.options.dryRun"]);
+  });
+
+  it("可以指定英文", () => {
+    initI18n("en");
+    expect(t("common.options.dryRun")).toBe(en["common.options.dryRun"]);
+  });
+});
+
+describe("t", () => {
+  it("返回中文公共翻译", () => {
+    initI18n("zh-CN");
+    expect(t("common.executionFailed", { error: "test" })).toBe("执行失败: test");
+  });
+
+  it("返回英文公共翻译", () => {
+    initI18n("en");
+    expect(t("common.executionFailed", { error: "test" })).toBe("Execution failed: test");
+  });
+
+  it("key 不存在时返回 key 本身", () => {
+    initI18n("zh-CN");
+    expect(t("nonexistent.key")).toBe("nonexistent.key");
+  });
+
+  it("未初始化时自动初始化", () => {
+    const result = t("common.options.dryRun");
+    expect(typeof result).toBe("string");
+    expect(result.length).toBeGreaterThan(0);
+  });
+});
+
+describe("addLocaleResources", () => {
+  it("注册 Extension 命名空间并可通过 t 访问（中文）", () => {
+    initI18n("zh-CN");
+    addLocaleResources("build", {
+      "zh-CN": { description: "构建插件", buildFailed: "构建失败: {{error}}" },
+      en: { description: "Build plugins", buildFailed: "Build failed: {{error}}" },
+    });
+    expect(t("build:description")).toBe("构建插件");
+    expect(t("build:buildFailed", { error: "test" })).toBe("构建失败: test");
+  });
+
+  it("注册 Extension 命名空间并可通过 t 访问（英文）", () => {
+    initI18n("en");
+    addLocaleResources("build", {
+      "zh-CN": { description: "构建插件" },
+      en: { description: "Build plugins" },
+    });
+    expect(t("build:description")).toBe("Build plugins");
+  });
+
+  it("多个命名空间互不干扰", () => {
+    initI18n("zh-CN");
+    addLocaleResources("ext-a", {
+      "zh-CN": { name: "扩展A" },
+      en: { name: "Extension A" },
+    });
+    addLocaleResources("ext-b", {
+      "zh-CN": { name: "扩展B" },
+      en: { name: "Extension B" },
+    });
+    expect(t("ext-a:name")).toBe("扩展A");
+    expect(t("ext-b:name")).toBe("扩展B");
+  });
+});
+
+describe("语言包完整性", () => {
+  it("zh-cn 和 en 的 key 数量一致", () => {
+    const zhKeys = Object.keys(zhCN).sort();
+    const enKeys = Object.keys(en).sort();
+    expect(zhKeys).toEqual(enKeys);
+  });
+
+  it("所有 key 的值都不为空", () => {
+    for (const [_key, value] of Object.entries(zhCN)) {
+      expect(value).toBeTruthy();
+      expect(typeof value).toBe("string");
+    }
+    for (const [_key, value] of Object.entries(en)) {
+      expect(value).toBeTruthy();
+      expect(typeof value).toBe("string");
+    }
+  });
+});

package/src/shared/i18n/i18n.ts

@@ -0,0 +1,86 @@
+import * as i18nextModule from "i18next";
+import type { TOptions, i18n } from "i18next";
+
+// 兼容 CJS/ESM 混合环境
+const i18next: i18n =
+  (i18nextModule as unknown as { default: i18n }).default || (i18nextModule as unknown as i18n);
+import { detectLocale } from "./locale-detect";
+import zhCN from "../../locales/zh-cn/translation.json";
+import en from "../../locales/en/translation.json";
+
+/** 默认命名空间 */
+const DEFAULT_NS = "translation";
+
+/** 是否已初始化 */
+let initialized = false;
+
+/**
+ * 初始化 i18n
+ * 当提供 resources 且无后端加载器时，i18next.init() 同步完成
+ * @param lang 指定语言，不传则自动检测
+ */
+export function initI18n(lang?: string): void {
+  if (initialized) return;
+  const lng = lang || detectLocale();
+  // i18next v25+ 移除了 initSync，但提供内联 resources 时 init() 同步完成
+  void i18next.init({
+    lng,
+    fallbackLng: "zh-CN",
+    defaultNS: DEFAULT_NS,
+    ns: [DEFAULT_NS],
+    resources: {
+      "zh-CN": { [DEFAULT_NS]: zhCN },
+      en: { [DEFAULT_NS]: en },
+    },
+    interpolation: {
+      escapeValue: false,
+    },
+    returnNull: false,
+    returnEmptyString: false,
+    // i18next v25.8+ 会在 init 时输出 locize.com 推广日志
+    showSupportNotice: false,
+  });
+  initialized = true;
+}
+
+/**
+ * 重置 i18n 状态（仅用于测试）
+ */
+export function resetI18n(): void {
+  initialized = false;
+}
+
+/**
+ * 翻译函数
+ * 装饰器和运行时均可使用
+ * @param key 翻译 key
+ * @param options 插值参数
+ */
+export function t(key: string, options?: TOptions): string {
+  if (!initialized) {
+    initI18n();
+  }
+  return i18next.t(key, options) as string;
+}
+
+/**
+ * 为外部 Extension 注册语言资源
+ * @param ns 命名空间（通常为 Extension name）
+ * @param resources 语言资源，key 为语言代码，值为翻译对象
+ */
+export function addLocaleResources(
+  ns: string,
+  resources: Record<string, Record<string, unknown>>,
+): void {
+  if (!initialized) {
+    initI18n();
+  }
+  for (const [lng, translations] of Object.entries(resources)) {
+    i18next.addResourceBundle(lng, ns, translations, true, true);
+  }
+  if (!i18next.options.ns) {
+    i18next.options.ns = [DEFAULT_NS, ns];
+  } else if (Array.isArray(i18next.options.ns) && !i18next.options.ns.includes(ns)) {
+    i18next.options.ns.push(ns);
+  }
+}

package/src/shared/i18n/index.ts

@@ -0,0 +1 @@
+export { initI18n, t, addLocaleResources } from "./i18n";

package/src/shared/i18n/locale-detect.ts

@@ -0,0 +1,134 @@
+import { readFileSync, existsSync } from "fs";
+import { execSync } from "child_process";
+import { join } from "path";
+import { homedir, platform } from "os";
+
+/** 默认语言 */
+const DEFAULT_LOCALE = "zh-CN";
+
+/** 配置文件名 */
+const CONFIG_FILE_NAME = "spaceflow.json";
+
+/** .spaceflow 目录名 */
+const SPACEFLOW_DIR = ".spaceflow";
+
+/**
+ * 标准化 locale 字符串为 BCP 47 格式
+ * @example "zh_CN" → "zh-CN", "zh-Hans" → "zh-CN", "en_US.UTF-8" → "en-US"
+ */
+function normalizeLocale(raw: string): string | undefined {
+  const cleaned = raw.replace(/\..*$/, "").trim();
+  // 处理 Apple 格式：zh-Hans → zh-CN, zh-Hant → zh-TW
+  if (/^zh[-_]?Hans/i.test(cleaned)) return "zh-CN";
+  if (/^zh[-_]?Hant/i.test(cleaned)) return "zh-TW";
+  // 处理标准格式：zh_CN / zh-CN / en_US / en-US
+  const match = cleaned.match(/^([a-z]{2})[-_]([A-Z]{2})/i);
+  if (match) return `${match[1].toLowerCase()}-${match[2].toUpperCase()}`;
+  // 处理纯语言代码：zh → zh-CN, en → en
+  const langOnly = cleaned.match(/^([a-z]{2})$/i);
+  if (langOnly) {
+    const lang = langOnly[1].toLowerCase();
+    return lang === "zh" ? "zh-CN" : lang;
+  }
+  return undefined;
+}
+
+/**
+ * 从 spaceflow.json 读取 lang 字段
+ * 按优先级从高到低查找：项目 > 全局
+ */
+function readLangFromConfig(): string | undefined {
+  const paths = [
+    join(process.cwd(), SPACEFLOW_DIR, CONFIG_FILE_NAME),
+    join(homedir(), SPACEFLOW_DIR, CONFIG_FILE_NAME),
+  ];
+  for (const configPath of paths) {
+    if (!existsSync(configPath)) continue;
+    try {
+      const content = readFileSync(configPath, "utf-8");
+      const config = JSON.parse(content) as Record<string, unknown>;
+      if (typeof config.lang === "string" && config.lang.length > 0) {
+        return normalizeLocale(config.lang) ?? config.lang;
+      }
+    } catch {
+      // 忽略解析错误
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 从系统环境变量推断 locale
+ * 解析 LANG 格式如 "zh_CN.UTF-8" → "zh-CN"
+ */
+function readEnvLocale(): string | undefined {
+  const raw = process.env.LC_ALL || process.env.LANG;
+  if (!raw) return undefined;
+  return normalizeLocale(raw);
+}
+
+/**
+ * macOS：通过 defaults read 获取系统首选语言
+ * AppleLanguages 比 LANG 环境变量更准确地反映用户实际语言偏好
+ */
+function readMacOSLocale(): string | undefined {
+  try {
+    const output = execSync("defaults read -g AppleLanguages", {
+      encoding: "utf-8",
+      timeout: 500,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    // 输出格式: (\n    "zh-Hans-CN",\n    "en-CN"\n)
+    const match = output.match(/"([^"]+)"/);
+    if (!match) return undefined;
+    return normalizeLocale(match[1]);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Windows：通过 PowerShell 获取系统 UI 语言
+ */
+function readWindowsLocale(): string | undefined {
+  try {
+    const output = execSync('powershell -NoProfile -Command "(Get-Culture).Name"', {
+      encoding: "utf-8",
+      timeout: 1000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    const trimmed = output.trim();
+    if (!trimmed) return undefined;
+    return normalizeLocale(trimmed);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 读取操作系统级别的语言偏好
+ * macOS: defaults read -g AppleLanguages
+ * Windows: PowerShell Get-Culture
+ */
+function readOSLocale(): string | undefined {
+  const os = platform();
+  if (os === "darwin") return readMacOSLocale();
+  if (os === "win32") return readWindowsLocale();
+  return undefined;
+}
+
+/**
+ * 检测当前语言
+ *
+ * 优先级：
+ * 1. 环境变量 SPACEFLOW_LANG
+ * 2. spaceflow.json 中的 lang 字段（项目 > 全局）
+ * 3. 操作系统语言偏好（macOS AppleLanguages / Windows Get-Culture）
+ * 4. 系统环境变量 LC_ALL / LANG
+ * 5. 回退到 zh-CN
+ */
+export function detectLocale(): string {
+  const envLang = process.env.SPACEFLOW_LANG;
+  if (envLang) return normalizeLocale(envLang) ?? envLang;
+  return readLangFromConfig() || readOSLocale() || readEnvLocale() || DEFAULT_LOCALE;
+}

package/src/shared/llm-jsonput/index.ts

@@ -0,0 +1,94 @@
+import { jsonrepair } from "jsonrepair";
+import type { LlmJsonPutSchema, LlmJsonSchema } from "./types";
+
+export type { LlmJsonPutSchema, LlmJsonSchema, LlmJsonSchemaType } from "./types";
+
+export interface ParseOptions {
+  disableRequestRetry?: boolean;
+}
+
+export interface LlmJsonPutOptions {
+  llmRequest?: (prompt: { systemPrompt: string; userPrompt: string }) => Promise<string>;
+  systemPrompt?: string;
+}
+
+const JSON_FORMAT_INSTRUCTION = `请严格以 JSON 格式输出结果，不要输出任何其他内容，格式如下：`;
+
+export class LlmJsonPut<T = any> {
+  public readonly jsonFormatInstruction: string;
+  constructor(
+    protected schema: LlmJsonPutSchema,
+    protected opts?: LlmJsonPutOptions,
+  ) {
+    this.jsonFormatInstruction = this.getJsonFormatInstruction(schema);
+  }
+
+  isMatched(prompt: string): boolean {
+    return prompt.includes(JSON_FORMAT_INSTRUCTION);
+  }
+
+  getSchema(): Record<string, unknown> {
+    return this.schema as unknown as Record<string, unknown>;
+  }
+
+  getJsonFormatInstruction(schema: LlmJsonPutSchema): string {
+    const generateExample = (s: LlmJsonSchema): any => {
+      if (s.type === "object") {
+        const obj: any = {};
+        for (const [key, value] of Object.entries(s.properties || {})) {
+          obj[key] = generateExample(value);
+        }
+        return obj;
+      } else if (s.type === "array") {
+        return [generateExample(s.items!)];
+      }
+      return s.description || `<${s.type}>`;
+    };
+
+    const example = JSON.stringify(generateExample(schema), null, 2);
+
+    return `${JSON_FORMAT_INSTRUCTION}\n\`\`\`json\n${example}\`\`\`\n注意：只输出 JSON，不要包含 markdown 代码块或其他文字。`;
+  }
+
+  async parse(input: string, opts?: ParseOptions): Promise<T> {
+    let content = input.trim();
+
+    // 尝试移除 markdown 代码块
+    if (content.startsWith("```")) {
+      content = content.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "");
+    }
+
+    try {
+      try {
+        return JSON.parse(content);
+      } catch {
+        // 如果原生解析失败，尝试修复
+        const repaired = jsonrepair(content);
+        return JSON.parse(repaired);
+      }
+    } catch (err) {
+      // 如果以上都不行就都丢给大模型，然后在重新走parse，但是要记录重新执行的次数，最多5次
+      let retryCount = 0;
+      while (retryCount < 5 && !opts?.disableRequestRetry) {
+        const response = await this.request(input);
+        return response;
+      }
+      throw new Error(
+        `无法解析或修复 LLM 返回的 JSON: ${err instanceof Error ? err.message : String(err)}\n原始内容: ${input}`,
+      );
+    }
+  }
+
+  async request(userPrompt: string): Promise<T> {
+    if (!this.opts?.llmRequest) {
+      throw new Error("未配置 llmRequest 方法，无法发起请求");
+    }
+
+    const systemPrompt = `${this.opts.systemPrompt ? this.opts.systemPrompt + "\n" : ""}${this.jsonFormatInstruction}`;
+    const response = await this.opts.llmRequest({
+      systemPrompt,
+      userPrompt,
+    });
+    return this.parse(response, { disableRequestRetry: true });
+  }
+}

package/src/shared/llm-jsonput/types.ts

@@ -0,0 +1,17 @@
+export type LlmJsonSchemaType = "string" | "number" | "boolean" | "object" | "array" | "null";
+
+export interface LlmJsonSchema {
+  type: LlmJsonSchemaType;
+  description?: string;
+  properties?: Record<string, LlmJsonSchema>;
+  items?: LlmJsonSchema;
+  required?: string[];
+  additionalProperties?: boolean;
+  enum?: string[];
+}
+
+export interface LlmJsonPutSchema extends LlmJsonSchema {
+  type: "object";
+  properties: Record<string, LlmJsonSchema>;
+  required: string[];
+}