@nahisaho/katashiro-workspace 0.4.0

package/src/local-workspace.ts

@@ -0,0 +1,311 @@
+/**
+ * LocalWorkspace - ローカルファイルシステムワークスペース
+ *
+ * @requirement REQ-011-02
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { glob } from 'fast-glob';
+import type {
+  Workspace,
+  LocalWorkspaceConfig,
+  FileInfo,
+  DirectoryEntry,
+} from './types.js';
+import { WorkspaceError } from './types.js';
+
+/**
+ * LocalWorkspace - ローカルファイルシステム操作
+ *
+ * @example
+ * ```typescript
+ * const workspace = new LocalWorkspace({
+ *   type: 'local',
+ *   workingDir: '/path/to/project',
+ * });
+ *
+ * const content = await workspace.read('README.md');
+ * await workspace.write('output.txt', 'Hello World');
+ * const files = await workspace.search('**\/*.ts');
+ * ```
+ */
+export class LocalWorkspace implements Workspace {
+  readonly type = 'local' as const;
+  readonly workingDir: string;
+  readonly readOnly: boolean;
+
+  constructor(config: LocalWorkspaceConfig) {
+    this.workingDir = path.resolve(config.workingDir);
+    this.readOnly = config.readOnly ?? false;
+  }
+
+  /**
+   * 絶対パスを解決
+   */
+  private resolvePath(filePath: string): string {
+    if (path.isAbsolute(filePath)) {
+      return filePath;
+    }
+    return path.join(this.workingDir, filePath);
+  }
+
+  /**
+   * ワークスペース内のパスか検証
+   */
+  private validatePath(filePath: string): void {
+    const resolved = this.resolvePath(filePath);
+    const normalized = path.normalize(resolved);
+    
+    // パストラバーサル防止
+    if (!normalized.startsWith(this.workingDir)) {
+      throw new WorkspaceError(
+        'PERMISSION_DENIED',
+        `Path traversal detected: ${filePath}`,
+        filePath
+      );
+    }
+  }
+
+  /**
+   * 書き込み可能か検証
+   */
+  private validateWritable(): void {
+    if (this.readOnly) {
+      throw new WorkspaceError(
+        'READ_ONLY',
+        'Workspace is read-only'
+      );
+    }
+  }
+
+  async read(filePath: string, encoding: BufferEncoding = 'utf-8'): Promise<string> {
+    const resolved = this.resolvePath(filePath);
+    this.validatePath(filePath);
+
+    try {
+      return await fs.readFile(resolved, { encoding });
+    } catch (error) {
+      throw this.handleFsError(error, filePath);
+    }
+  }
+
+  async readBuffer(filePath: string): Promise<Buffer> {
+    const resolved = this.resolvePath(filePath);
+    this.validatePath(filePath);
+
+    try {
+      return await fs.readFile(resolved);
+    } catch (error) {
+      throw this.handleFsError(error, filePath);
+    }
+  }
+
+  async write(filePath: string, content: string): Promise<void> {
+    this.validateWritable();
+    const resolved = this.resolvePath(filePath);
+    this.validatePath(filePath);
+
+    try {
+      // ディレクトリを作成
+      await fs.mkdir(path.dirname(resolved), { recursive: true });
+      await fs.writeFile(resolved, content, 'utf-8');
+    } catch (error) {
+      throw this.handleFsError(error, filePath);
+    }
+  }
+
+  async writeBuffer(filePath: string, buffer: Buffer): Promise<void> {
+    this.validateWritable();
+    const resolved = this.resolvePath(filePath);
+    this.validatePath(filePath);
+
+    try {
+      await fs.mkdir(path.dirname(resolved), { recursive: true });
+      await fs.writeFile(resolved, buffer);
+    } catch (error) {
+      throw this.handleFsError(error, filePath);
+    }
+  }
+
+  async list(dirPath: string): Promise<FileInfo[]> {
+    const resolved = this.resolvePath(dirPath);
+    this.validatePath(dirPath);
+
+    try {
+      const entries = await fs.readdir(resolved, { withFileTypes: true });
+      const fileInfos: FileInfo[] = [];
+
+      for (const entry of entries) {
+        const entryPath = path.join(resolved, entry.name);
+        const stats = await fs.stat(entryPath);
+
+        fileInfos.push({
+          name: entry.name,
+          path: entryPath,
+          size: stats.size,
+          isDirectory: entry.isDirectory(),
+          modifiedAt: stats.mtime,
+          createdAt: stats.birthtime,
+        });
+      }
+
+      return fileInfos;
+    } catch (error) {
+      throw this.handleFsError(error, dirPath);
+    }
+  }
+
+  async listEntries(dirPath: string): Promise<DirectoryEntry[]> {
+    const resolved = this.resolvePath(dirPath);
+    this.validatePath(dirPath);
+
+    try {
+      const entries = await fs.readdir(resolved, { withFileTypes: true });
+      return entries.map(entry => ({
+        name: entry.name,
+        isDirectory: entry.isDirectory(),
+      }));
+    } catch (error) {
+      throw this.handleFsError(error, dirPath);
+    }
+  }
+
+  async search(pattern: string): Promise<string[]> {
+    try {
+      const files = await glob(pattern, {
+        cwd: this.workingDir,
+        absolute: false,
+        onlyFiles: true,
+        ignore: ['**/node_modules/**', '**/.git/**'],
+      });
+      return files;
+    } catch (error) {
+      throw new WorkspaceError(
+        'OPERATION_FAILED',
+        `Search failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  async exists(filePath: string): Promise<boolean> {
+    const resolved = this.resolvePath(filePath);
+    this.validatePath(filePath);
+
+    try {
+      await fs.access(resolved);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async delete(filePath: string): Promise<void> {
+    this.validateWritable();
+    const resolved = this.resolvePath(filePath);
+    this.validatePath(filePath);
+
+    try {
+      const stats = await fs.stat(resolved);
+      if (stats.isDirectory()) {
+        await fs.rm(resolved, { recursive: true });
+      } else {
+        await fs.unlink(resolved);
+      }
+    } catch (error) {
+      throw this.handleFsError(error, filePath);
+    }
+  }
+
+  async mkdir(dirPath: string, recursive = true): Promise<void> {
+    this.validateWritable();
+    const resolved = this.resolvePath(dirPath);
+    this.validatePath(dirPath);
+
+    try {
+      await fs.mkdir(resolved, { recursive });
+    } catch (error) {
+      throw this.handleFsError(error, dirPath);
+    }
+  }
+
+  async stat(filePath: string): Promise<FileInfo> {
+    const resolved = this.resolvePath(filePath);
+    this.validatePath(filePath);
+
+    try {
+      const stats = await fs.stat(resolved);
+      return {
+        name: path.basename(resolved),
+        path: resolved,
+        size: stats.size,
+        isDirectory: stats.isDirectory(),
+        modifiedAt: stats.mtime,
+        createdAt: stats.birthtime,
+      };
+    } catch (error) {
+      throw this.handleFsError(error, filePath);
+    }
+  }
+
+  async copy(src: string, dest: string): Promise<void> {
+    this.validateWritable();
+    const srcResolved = this.resolvePath(src);
+    const destResolved = this.resolvePath(dest);
+    this.validatePath(src);
+    this.validatePath(dest);
+
+    try {
+      await fs.mkdir(path.dirname(destResolved), { recursive: true });
+      await fs.cp(srcResolved, destResolved, { recursive: true });
+    } catch (error) {
+      throw this.handleFsError(error, src);
+    }
+  }
+
+  async move(src: string, dest: string): Promise<void> {
+    this.validateWritable();
+    const srcResolved = this.resolvePath(src);
+    const destResolved = this.resolvePath(dest);
+    this.validatePath(src);
+    this.validatePath(dest);
+
+    try {
+      await fs.mkdir(path.dirname(destResolved), { recursive: true });
+      await fs.rename(srcResolved, destResolved);
+    } catch (error) {
+      throw this.handleFsError(error, src);
+    }
+  }
+
+  /**
+   * FSエラーをWorkspaceErrorに変換
+   */
+  private handleFsError(error: unknown, filePath: string): WorkspaceError {
+    if (error instanceof WorkspaceError) {
+      return error;
+    }
+
+    const fsError = error as NodeJS.ErrnoException;
+    switch (fsError.code) {
+      case 'ENOENT':
+        return new WorkspaceError('NOT_FOUND', `Not found: ${filePath}`, filePath, fsError);
+      case 'EACCES':
+      case 'EPERM':
+        return new WorkspaceError('PERMISSION_DENIED', `Permission denied: ${filePath}`, filePath, fsError);
+      case 'EEXIST':
+        return new WorkspaceError('ALREADY_EXISTS', `Already exists: ${filePath}`, filePath, fsError);
+      case 'EISDIR':
+        return new WorkspaceError('IS_DIRECTORY', `Is a directory: ${filePath}`, filePath, fsError);
+      case 'ENOTDIR':
+        return new WorkspaceError('NOT_DIRECTORY', `Not a directory: ${filePath}`, filePath, fsError);
+      default:
+        return new WorkspaceError(
+          'OPERATION_FAILED',
+          `Operation failed: ${fsError.message}`,
+          filePath,
+          fsError
+        );
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,242 @@
+/**
+ * Workspace 型定義
+ *
+ * @requirement REQ-011
+ * @design REQ-011-01〜REQ-011-06
+ */
+
+// ============================================================================
+// ワークスペースタイプ
+// ============================================================================
+
+/**
+ * ワークスペースの種類
+ */
+export type WorkspaceType = 'local' | 'remote' | 'docker';
+
+/**
+ * ファイル情報
+ */
+export interface FileInfo {
+  /** ファイル名 */
+  name: string;
+  /** フルパス */
+  path: string;
+  /** ファイルサイズ（バイト） */
+  size: number;
+  /** ディレクトリかどうか */
+  isDirectory: boolean;
+  /** 最終更新日時 */
+  modifiedAt: Date;
+  /** 作成日時 */
+  createdAt: Date;
+}
+
+/**
+ * ディレクトリエントリ
+ */
+export interface DirectoryEntry {
+  /** ファイル名 */
+  name: string;
+  /** ディレクトリかどうか */
+  isDirectory: boolean;
+}
+
+/**
+ * ワークスペース設定ベース
+ */
+export interface WorkspaceConfigBase {
+  /** 作業ディレクトリ */
+  workingDir: string;
+  /** 読み取り専用モード */
+  readOnly?: boolean;
+}
+
+/**
+ * ローカルワークスペース設定
+ */
+export interface LocalWorkspaceConfig extends WorkspaceConfigBase {
+  type: 'local';
+}
+
+/**
+ * リモートワークスペース設定
+ */
+export interface RemoteWorkspaceConfig extends WorkspaceConfigBase {
+  type: 'remote';
+  /** APIベースURL */
+  apiUrl: string;
+  /** 認証トークン */
+  authToken?: string;
+  /** タイムアウト（ミリ秒） */
+  timeout?: number;
+}
+
+/**
+ * Dockerワークスペース設定
+ */
+export interface DockerWorkspaceConfig extends WorkspaceConfigBase {
+  type: 'docker';
+  /** コンテナID */
+  containerId: string;
+  /** Docker ソケット */
+  socketPath?: string;
+}
+
+/**
+ * ワークスペース設定
+ */
+export type WorkspaceConfig =
+  | LocalWorkspaceConfig
+  | RemoteWorkspaceConfig
+  | DockerWorkspaceConfig;
+
+// ============================================================================
+// ワークスペースインターフェース
+// ============================================================================
+
+/**
+ * ワークスペースインターフェース（REQ-011-01）
+ */
+export interface Workspace {
+  /** ワークスペースタイプ */
+  readonly type: WorkspaceType;
+  /** 作業ディレクトリ */
+  readonly workingDir: string;
+  /** 読み取り専用かどうか */
+  readonly readOnly: boolean;
+
+  /**
+   * ファイルを読み取る
+   * @param path ファイルパス
+   * @param encoding エンコーディング（デフォルト: utf-8）
+   */
+  read(path: string, encoding?: BufferEncoding): Promise<string>;
+
+  /**
+   * ファイルをバイナリとして読み取る
+   * @param path ファイルパス
+   */
+  readBuffer(path: string): Promise<Buffer>;
+
+  /**
+   * ファイルに書き込む
+   * @param path ファイルパス
+   * @param content コンテンツ
+   */
+  write(path: string, content: string): Promise<void>;
+
+  /**
+   * バイナリを書き込む
+   * @param path ファイルパス
+   * @param buffer バッファ
+   */
+  writeBuffer(path: string, buffer: Buffer): Promise<void>;
+
+  /**
+   * ディレクトリの内容をリスト
+   * @param path ディレクトリパス
+   */
+  list(path: string): Promise<FileInfo[]>;
+
+  /**
+   * 簡易ディレクトリリスト（名前のみ）
+   * @param path ディレクトリパス
+   */
+  listEntries(path: string): Promise<DirectoryEntry[]>;
+
+  /**
+   * globパターンでファイルを検索（REQ-011-06）
+   * @param pattern globパターン
+   */
+  search(pattern: string): Promise<string[]>;
+
+  /**
+   * ファイル/ディレクトリの存在確認
+   * @param path パス
+   */
+  exists(path: string): Promise<boolean>;
+
+  /**
+   * ファイル/ディレクトリを削除
+   * @param path パス
+   */
+  delete(path: string): Promise<void>;
+
+  /**
+   * ディレクトリを作成
+   * @param path ディレクトリパス
+   * @param recursive 再帰的に作成するか
+   */
+  mkdir(path: string, recursive?: boolean): Promise<void>;
+
+  /**
+   * ファイル情報を取得
+   * @param path パス
+   */
+  stat(path: string): Promise<FileInfo>;
+
+  /**
+   * ファイル/ディレクトリをコピー
+   * @param src ソースパス
+   * @param dest 宛先パス
+   */
+  copy(src: string, dest: string): Promise<void>;
+
+  /**
+   * ファイル/ディレクトリを移動
+   * @param src ソースパス
+   * @param dest 宛先パス
+   */
+  move(src: string, dest: string): Promise<void>;
+
+  /**
+   * ワークスペースを初期化
+   */
+  initialize?(): Promise<void>;
+
+  /**
+   * ワークスペースをクリーンアップ
+   */
+  cleanup?(): Promise<void>;
+}
+
+// ============================================================================
+// エラー
+// ============================================================================
+
+/**
+ * ワークスペースエラーコード
+ */
+export type WorkspaceErrorCode =
+  | 'NOT_FOUND'
+  | 'PERMISSION_DENIED'
+  | 'ALREADY_EXISTS'
+  | 'IS_DIRECTORY'
+  | 'NOT_DIRECTORY'
+  | 'READ_ONLY'
+  | 'OPERATION_FAILED'
+  | 'CONNECTION_FAILED'
+  | 'TIMEOUT';
+
+/**
+ * ワークスペースエラー
+ */
+export class WorkspaceError extends Error {
+  constructor(
+    public readonly code: WorkspaceErrorCode,
+    message: string,
+    public readonly path?: string,
+    public readonly cause?: Error
+  ) {
+    super(message);
+    this.name = 'WorkspaceError';
+  }
+}
+
+// ============================================================================
+// デフォルト設定
+// ============================================================================
+
+export const DEFAULT_REMOTE_TIMEOUT = 30000;
+export const DEFAULT_DOCKER_SOCKET = '/var/run/docker.sock';

package/src/workspace-factory.ts

@@ -0,0 +1,145 @@
+/**
+ * WorkspaceFactory - ワークスペースファクトリー
+ *
+ * @requirement REQ-011-05
+ */
+
+import { LocalWorkspace } from './local-workspace.js';
+import { DockerWorkspace } from './docker-workspace.js';
+import type { Workspace, WorkspaceConfig } from './types.js';
+import { WorkspaceError } from './types.js';
+
+/**
+ * WorkspaceFactory - ワークスペースの生成ユーティリティ
+ *
+ * @example
+ * ```typescript
+ * // ローカルワークスペース
+ * const local = WorkspaceFactory.create({
+ *   type: 'local',
+ *   workingDir: '/path/to/project',
+ * });
+ *
+ * // Dockerワークスペース
+ * const docker = WorkspaceFactory.create({
+ *   type: 'docker',
+ *   containerId: 'container123',
+ *   workingDir: '/app',
+ * });
+ *
+ * // 型に依存しない統一操作
+ * async function readConfig(workspace: Workspace): Promise<string> {
+ *   return workspace.read('config.json');
+ * }
+ * ```
+ */
+export class WorkspaceFactory {
+  /**
+   * ワークスペースを生成（REQ-011-05）
+   */
+  static create(config: WorkspaceConfig): Workspace {
+    switch (config.type) {
+      case 'local':
+        return new LocalWorkspace(config);
+
+      case 'docker':
+        return new DockerWorkspace(config);
+
+      case 'remote':
+        throw new WorkspaceError(
+          'OPERATION_FAILED',
+          'RemoteWorkspace is not yet implemented'
+        );
+
+      default:
+        throw new WorkspaceError(
+          'OPERATION_FAILED',
+          `Unknown workspace type: ${(config as WorkspaceConfig).type}`
+        );
+    }
+  }
+
+  /**
+   * ローカルワークスペースを生成
+   */
+  static createLocal(workingDir: string, options?: { readOnly?: boolean }): LocalWorkspace {
+    return new LocalWorkspace({
+      type: 'local',
+      workingDir,
+      readOnly: options?.readOnly,
+    });
+  }
+
+  /**
+   * Dockerワークスペースを生成
+   */
+  static createDocker(
+    containerId: string,
+    workingDir: string,
+    options?: { readOnly?: boolean; socketPath?: string }
+  ): DockerWorkspace {
+    return new DockerWorkspace({
+      type: 'docker',
+      containerId,
+      workingDir,
+      readOnly: options?.readOnly,
+      socketPath: options?.socketPath,
+    });
+  }
+}
+
+// ============================================================================
+// ユーティリティ関数
+// ============================================================================
+
+/**
+ * ワークスペースを作成して初期化
+ */
+export async function createWorkspace(config: WorkspaceConfig): Promise<Workspace> {
+  const workspace = WorkspaceFactory.create(config);
+  if (workspace.initialize) {
+    await workspace.initialize();
+  }
+  return workspace;
+}
+
+/**
+ * ワークスペースでファイルを読み取る簡易関数
+ */
+export async function readFile(
+  config: WorkspaceConfig,
+  filePath: string
+): Promise<string> {
+  const workspace = WorkspaceFactory.create(config);
+  if (workspace.initialize) {
+    await workspace.initialize();
+  }
+  try {
+    return await workspace.read(filePath);
+  } finally {
+    if (workspace.cleanup) {
+      await workspace.cleanup();
+    }
+  }
+}
+
+/**
+ * ワークスペースでファイルを書き込む簡易関数
+ */
+export async function writeFile(
+  config: WorkspaceConfig,
+  filePath: string,
+  content: string
+): Promise<void> {
+  const workspace = WorkspaceFactory.create(config);
+  if (workspace.initialize) {
+    await workspace.initialize();
+  }
+  try {
+    await workspace.write(filePath, content);
+  } finally {
+    if (workspace.cleanup) {
+      await workspace.cleanup();
+    }
+  }
+}