@spaceflow/core 0.1.1

package/src/shared/spaceflow-dir/index.ts

@@ -0,0 +1,158 @@
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { SPACEFLOW_DIR, PACKAGE_JSON } from "../../extension-system/extension.interface";
+import { isPnpmWorkspace } from "../package-manager";
+
+/**
+ * 获取 .spaceflow 目录路径
+ * @param isGlobal 是否为全局目录（~/.spaceflow）
+ * @param cwd 工作目录，默认为 process.cwd()
+ */
+export function getSpaceflowDir(isGlobal: boolean, cwd?: string): string {
+  if (isGlobal) {
+    return join(homedir(), SPACEFLOW_DIR);
+  }
+  return join(cwd || process.cwd(), SPACEFLOW_DIR);
+}
+
+/**
+ * 确保 .spaceflow 目录存在
+ * @param spaceflowDir .spaceflow 目录路径
+ */
+export function ensureSpaceflowDir(spaceflowDir: string): void {
+  if (!existsSync(spaceflowDir)) {
+    mkdirSync(spaceflowDir, { recursive: true });
+  }
+
+  // 创建 .gitignore
+  const gitignorePath = join(spaceflowDir, ".gitignore");
+  if (!existsSync(gitignorePath)) {
+    const gitignoreContent = `# Spaceflow Extension dependencies
+node_modules/
+pnpm-lock.yaml
+config-schema.json
+`;
+    writeFileSync(gitignorePath, gitignoreContent);
+  }
+
+  // 创建空的 pnpm-workspace.yaml，防止被父级 workspace 接管
+  const workspaceYamlPath = join(spaceflowDir, "pnpm-workspace.yaml");
+  if (!existsSync(workspaceYamlPath)) {
+    writeFileSync(workspaceYamlPath, "packages: []\n");
+  }
+}
+
+/**
+ * 获取 @spaceflow/cli 的路径
+ * @param isGlobal 是否为全局安装
+ * @param cwd 工作目录，默认为 process.cwd()
+ */
+export function getSpaceflowCliPath(isGlobal: boolean = false, cwd?: string): string {
+  const workDir = cwd || process.cwd();
+
+  if (isGlobal) {
+    // 全局安装：尝试找到 @spaceflow/cli 的实际路径进行 link
+    // 优先从当前项目的 cli 目录 link
+    const cliPath = join(workDir, "packages", "cli");
+    if (existsSync(join(cliPath, PACKAGE_JSON))) {
+      try {
+        const content = readFileSync(join(cliPath, PACKAGE_JSON), "utf-8");
+        const pkg = JSON.parse(content);
+        if (pkg.name === "@spaceflow/cli") {
+          return `link:${cliPath}`;
+        }
+      } catch {
+        // ignore
+      }
+    }
+    // 回退到 latest
+    return "latest";
+  }
+
+  // 本地安装：检查是否在 monorepo 中
+  if (isPnpmWorkspace(workDir)) {
+    return "workspace:*";
+  }
+
+  // 尝试从项目 package.json 获取版本
+  const projectPkgPath = join(workDir, PACKAGE_JSON);
+  if (existsSync(projectPkgPath)) {
+    try {
+      const content = readFileSync(projectPkgPath, "utf-8");
+      const pkg = JSON.parse(content);
+      const version =
+        pkg.dependencies?.["@spaceflow/core"] || pkg.devDependencies?.["@spaceflow/core"];
+      if (version) return version;
+    } catch {
+      // ignore
+    }
+  }
+
+  return "latest";
+}
+
+/**
+ * 确保 .spaceflow/package.json 存在
+ * 包含 @spaceflow/cli 作为依赖
+ * @param spaceflowDir .spaceflow 目录路径
+ * @param isGlobal 是否为全局安装
+ * @param cwd 工作目录，默认为 process.cwd()
+ */
+export function ensureSpaceflowPackageJson(
+  spaceflowDir: string,
+  isGlobal: boolean = false,
+  cwd?: string,
+): void {
+  // 确保目录存在
+  ensureSpaceflowDir(spaceflowDir);
+
+  // 确保 package.json 存在
+  const packageJsonPath = join(spaceflowDir, PACKAGE_JSON);
+  if (!existsSync(packageJsonPath)) {
+    const cliPath = getSpaceflowCliPath(isGlobal, cwd);
+    const packageJson = {
+      name: "spaceflow",
+      private: true,
+      dependencies: {
+        "@spaceflow/core": cliPath,
+      },
+    };
+    writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
+  }
+}
+
+/**
+ * 确保编辑器目录有 .gitignore 文件，并将生成的文件加入忽略列表
+ * @param editorRoot 编辑器根目录（如 .claude）
+ * @param itemType 项目类型 (skills 或 commands)
+ * @param itemName 项目名称
+ */
+export async function ensureEditorGitignore(
+  editorRoot: string,
+  itemType: "skills" | "commands",
+  itemName: string,
+): Promise<void> {
+  const { readFile, writeFile } = await import("fs/promises");
+  const gitignorePath = join(editorRoot, ".gitignore");
+  const ignoreEntry = itemType === "skills" ? `skills/${itemName}` : `commands/${itemName}.md`;
+
+  let content = "";
+  if (existsSync(gitignorePath)) {
+    content = await readFile(gitignorePath, "utf-8");
+    // 检查是否已包含该条目
+    const lines = content.split("\n").map((l) => l.trim());
+    if (lines.includes(ignoreEntry)) {
+      return;
+    }
+    // 确保末尾有换行
+    if (!content.endsWith("\n")) {
+      content += "\n";
+    }
+  } else {
+    content = "# 自动生成的 .gitignore - spaceflow 安装的 skills 和 commands\n";
+  }
+
+  content += `${ignoreEntry}\n`;
+  await writeFile(gitignorePath, content);
+}

package/src/shared/storage/adapters/file.adapter.ts

@@ -0,0 +1,113 @@
+import * as fs from "fs";
+import * as path from "path";
+import { StorageItem } from "../types";
+import { StorageAdapter } from "./storage-adapter.interface";
+
+/**
+ * 文件存储适配器
+ * 数据持久化到 JSON 文件，支持进程重启后恢复
+ */
+export class FileAdapter implements StorageAdapter {
+  protected store = new Map<string, StorageItem>();
+  protected filePath: string;
+  protected saveTimer: ReturnType<typeof setTimeout> | null = null;
+  protected readonly debounceMs = 100; // 防抖延迟
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+    this.load();
+  }
+
+  /**
+   * 从文件加载数据
+   */
+  protected load(): void {
+    try {
+      if (fs.existsSync(this.filePath)) {
+        const data = fs.readFileSync(this.filePath, "utf-8");
+        const parsed = JSON.parse(data) as Record<string, StorageItem>;
+        this.store = new Map(Object.entries(parsed));
+      }
+    } catch {
+      // 文件不存在或解析失败，使用空存储
+      this.store = new Map();
+    }
+  }
+
+  /**
+   * 保存数据到文件（防抖）
+   */
+  protected save(): void {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+    }
+
+    this.saveTimer = setTimeout(() => {
+      this.saveSync();
+      this.saveTimer = null;
+    }, this.debounceMs);
+  }
+
+  /**
+   * 同步保存数据到文件
+   */
+  protected saveSync(): void {
+    try {
+      const dir = path.dirname(this.filePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+
+      const data = Object.fromEntries(this.store);
+      fs.writeFileSync(this.filePath, JSON.stringify(data, null, 2), "utf-8");
+    } catch (error) {
+      console.error("Failed to save storage file:", error);
+    }
+  }
+
+  async get<T = any>(key: string): Promise<StorageItem<T> | undefined> {
+    return this.store.get(key) as StorageItem<T> | undefined;
+  }
+
+  async set<T = any>(key: string, item: StorageItem<T>): Promise<void> {
+    this.store.set(key, item);
+    this.save();
+  }
+
+  async delete(key: string): Promise<boolean> {
+    const result = this.store.delete(key);
+    if (result) {
+      this.save();
+    }
+    return result;
+  }
+
+  async has(key: string): Promise<boolean> {
+    return this.store.has(key);
+  }
+
+  async keys(pattern?: string): Promise<string[]> {
+    const allKeys = Array.from(this.store.keys());
+
+    if (!pattern) {
+      return allKeys;
+    }
+
+    // 将通配符模式转换为正则表达式
+    const regexPattern = pattern
+      .replace(/[.+^${}()|[\]\\]/g, "\\$&") // 转义特殊字符
+      .replace(/\*/g, ".*"); // * 转换为 .*
+
+    const regex = new RegExp(`^${regexPattern}$`);
+    return allKeys.filter((key) => regex.test(key));
+  }
+
+  async clear(): Promise<void> {
+    this.store.clear();
+    this.save();
+  }
+
+  async size(): Promise<number> {
+    return this.store.size;
+  }
+}

package/src/shared/storage/adapters/index.ts

@@ -0,0 +1,3 @@
+export * from "./storage-adapter.interface";
+export * from "./memory.adapter";
+export * from "./file.adapter";

package/src/shared/storage/adapters/memory.adapter.ts

@@ -0,0 +1,50 @@
+import { StorageItem } from "../types";
+import { StorageAdapter } from "./storage-adapter.interface";
+
+/**
+ * 内存存储适配器
+ * 数据存储在内存中，进程重启后数据丢失
+ */
+export class MemoryAdapter implements StorageAdapter {
+  protected store = new Map<string, StorageItem>();
+
+  async get<T = any>(key: string): Promise<StorageItem<T> | undefined> {
+    return this.store.get(key) as StorageItem<T> | undefined;
+  }
+
+  async set<T = any>(key: string, item: StorageItem<T>): Promise<void> {
+    this.store.set(key, item);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.store.delete(key);
+  }
+
+  async has(key: string): Promise<boolean> {
+    return this.store.has(key);
+  }
+
+  async keys(pattern?: string): Promise<string[]> {
+    const allKeys = Array.from(this.store.keys());
+
+    if (!pattern) {
+      return allKeys;
+    }
+
+    // 将通配符模式转换为正则表达式
+    const regexPattern = pattern
+      .replace(/[.+^${}()|[\]\\]/g, "\\$&") // 转义特殊字符
+      .replace(/\*/g, ".*"); // * 转换为 .*
+
+    const regex = new RegExp(`^${regexPattern}$`);
+    return allKeys.filter((key) => regex.test(key));
+  }
+
+  async clear(): Promise<void> {
+    this.store.clear();
+  }
+
+  async size(): Promise<number> {
+    return this.store.size;
+  }
+}

package/src/shared/storage/adapters/storage-adapter.interface.ts

@@ -0,0 +1,48 @@
+import { StorageItem } from "../types";
+
+/**
+ * Storage 适配器接口
+ * 所有适配器必须实现此接口
+ */
+export interface StorageAdapter {
+  /**
+   * 获取存储项
+   * @param key 键名
+   */
+  get<T = any>(key: string): Promise<StorageItem<T> | undefined>;
+
+  /**
+   * 设置存储项
+   * @param key 键名
+   * @param item 存储项
+   */
+  set<T = any>(key: string, item: StorageItem<T>): Promise<void>;
+
+  /**
+   * 删除存储项
+   * @param key 键名
+   */
+  delete(key: string): Promise<boolean>;
+
+  /**
+   * 检查键是否存在
+   * @param key 键名
+   */
+  has(key: string): Promise<boolean>;
+
+  /**
+   * 获取所有键名
+   * @param pattern 可选的匹配模式，支持 * 通配符
+   */
+  keys(pattern?: string): Promise<string[]>;
+
+  /**
+   * 清空所有存储
+   */
+  clear(): Promise<void>;
+
+  /**
+   * 获取当前存储的 key 数量
+   */
+  size(): Promise<number>;
+}

package/src/shared/storage/index.ts

@@ -0,0 +1,4 @@
+export * from "./storage.module";
+export * from "./storage.service";
+export * from "./types";
+export * from "./adapters";

package/src/shared/storage/storage.module.ts

@@ -0,0 +1,150 @@
+import { DynamicModule, Module } from "@nestjs/common";
+import { ConfigModule, ConfigService } from "@nestjs/config";
+import { StorageService } from "./storage.service";
+import { MemoryAdapter } from "./adapters/memory.adapter";
+import { FileAdapter } from "./adapters/file.adapter";
+import { StorageAdapter } from "./adapters/storage-adapter.interface";
+import {
+  type StorageModuleOptions,
+  type StorageModuleAsyncOptions,
+  STORAGE_MODULE_OPTIONS,
+  STORAGE_ADAPTER,
+} from "./types";
+import { storageConfig, StorageConfig } from "../../config";
+
+/**
+ * 创建适配器实例
+ */
+function createAdapter(options: StorageModuleOptions): StorageAdapter {
+  switch (options.adapter) {
+    case "file":
+      if (!options.filePath) {
+        throw new Error("filePath is required for file adapter");
+      }
+      return new FileAdapter(options.filePath);
+    case "memory":
+    default:
+      return new MemoryAdapter();
+  }
+}
+
+@Module({})
+export class StorageModule {
+  /**
+   * 同步注册模块
+   *
+   * @example
+   * ```ts
+   * StorageModule.forRoot({
+   *   adapter: 'memory',
+   *   defaultTtl: 3600000, // 1 hour
+   * })
+   * ```
+   *
+   * @example
+   * ```ts
+   * StorageModule.forRoot({
+   *   adapter: 'file',
+   *   filePath: './data/storage.json',
+   * })
+   * ```
+   */
+  static forRoot(options: StorageModuleOptions): DynamicModule {
+    return {
+      module: StorageModule,
+      providers: [
+        {
+          provide: STORAGE_MODULE_OPTIONS,
+          useValue: options,
+        },
+        {
+          provide: STORAGE_ADAPTER,
+          useValue: createAdapter(options),
+        },
+        StorageService,
+      ],
+      exports: [StorageService],
+    };
+  }
+
+  /**
+   * 异步注册模块
+   *
+   * @example
+   * ```ts
+   * StorageModule.forRootAsync({
+   *   useFactory: (configService: ConfigService) => ({
+   *     adapter: configService.get('STORAGE_ADAPTER') || 'memory',
+   *     filePath: configService.get('STORAGE_FILE_PATH'),
+   *   }),
+   *   inject: [ConfigService],
+   * })
+   * ```
+   */
+  static forRootAsync(options: StorageModuleAsyncOptions): DynamicModule {
+    return {
+      module: StorageModule,
+      providers: [
+        {
+          provide: STORAGE_MODULE_OPTIONS,
+          useFactory: options.useFactory,
+          inject: options.inject || [],
+        },
+        {
+          provide: STORAGE_ADAPTER,
+          useFactory: (opts: StorageModuleOptions) => createAdapter(opts),
+          inject: [STORAGE_MODULE_OPTIONS],
+        },
+        StorageService,
+      ],
+      exports: [StorageService],
+    };
+  }
+
+  /**
+   * 使用 ConfigService 注册模块
+   *
+   * 环境变量：
+   * - STORAGE_ADAPTER: 'memory' | 'file'
+   * - STORAGE_FILE_PATH: 文件存储路径
+   * - STORAGE_DEFAULT_TTL: 默认过期时间（毫秒）
+   * - STORAGE_MAX_KEYS: 最大 key 数量
+   *
+   * @example
+   * ```ts
+   * @Module({
+   *   imports: [StorageModule.forFeature()],
+   * })
+   * export class AppModule {}
+   * ```
+   */
+  static forFeature(): DynamicModule {
+    return {
+      global: true,
+      module: StorageModule,
+      imports: [ConfigModule.forFeature(storageConfig)],
+      providers: [
+        {
+          provide: STORAGE_MODULE_OPTIONS,
+          useFactory: (configService: ConfigService): StorageModuleOptions => {
+            const config = configService.get<StorageConfig>("storage");
+            return {
+              adapter: config?.adapter || "memory",
+              filePath: config?.filePath,
+              defaultTtl: config?.defaultTtl,
+              maxKeys: config?.maxKeys,
+            };
+          },
+          inject: [ConfigService],
+        },
+        {
+          provide: STORAGE_ADAPTER,
+          useFactory: (opts: StorageModuleOptions) => createAdapter(opts),
+          inject: [STORAGE_MODULE_OPTIONS],
+        },
+        StorageService,
+      ],
+      exports: [StorageService],
+    };
+  }
+}