@hamak/ui-remote-fs-impl 0.4.3

package/src/middleware/store-sync-middleware.ts

@@ -0,0 +1,175 @@
+/**
+ * Store Sync Middleware
+ *
+ * Redux middleware for synchronizing remote filesystem operations to Redux Store FS.
+ * This middleware listens to remote FS completion actions and updates the Store FS accordingly.
+ * Migrated from amk/libs/ui/core/remote-fs/src/lib/store-fs-adapter-middleware.ts
+ */
+
+import { AnyAction, Middleware } from '@reduxjs/toolkit';
+import { Pathway } from '@hamak/shared-utils';
+import { RemoteFsActionTypes } from '@hamak/ui-remote-fs-api';
+import { StoreSyncMiddlewareConfig } from '@hamak/ui-remote-fs-spi';
+import {
+  rfsActions,
+  LsCompletedAction,
+  MkdirCompletedAction,
+  GetCompletedAction,
+  PostCompletedAction,
+  PutCompletedAction,
+  DeleteCompletedAction,
+} from '../actions/remote-fs-actions';
+
+/**
+ * Create store sync middleware
+ *
+ * This middleware intercepts remote FS completion actions and synchronizes them
+ * to the Redux Store FileSystem. It handles:
+ * - LS_COMPLETED: Creates directories and file entries in Store FS
+ * - MKDIR_COMPLETED: Creates directory in Store FS
+ * - GET_COMPLETED: Creates/updates file content in Store FS
+ * - POST/PUT_COMPLETED: Reloads file content from remote
+ * - DELETE_COMPLETED: Removes node from Store FS
+ *
+ * @param config Middleware configuration
+ * @returns Redux middleware
+ *
+ * @example
+ * ```typescript
+ * const middleware = createStoreSyncMiddleware({
+ *   fileSystemAdapter: storeFs,
+ *   pathTranslator: new PathTranslator(Pathway.ofRoot().resolve('remote')),
+ *   autoReload: true
+ * });
+ * ```
+ */
+export function createStoreSyncMiddleware<S = any>(
+  config: StoreSyncMiddlewareConfig
+): Middleware<{}, S> {
+  const { fileSystemAdapter, pathTranslator, autoReload = true, transformContent } = config;
+  const storeFsActions = fileSystemAdapter.getActions();
+
+  const storeSyncMiddleware: Middleware<{}, S> = (store) => (next) => (action) => {
+    const result = next(action);
+    const anyAction = action as AnyAction;
+
+    // Only process remote FS actions
+    if (!rfsActions.isRemoteFsAction(anyAction)) {
+      return result;
+    }
+
+    const dispatch = store.dispatch;
+
+    switch (anyAction.type) {
+      case RemoteFsActionTypes.LS_COMPLETED: {
+        const completedAction = anyAction as LsCompletedAction;
+        const { request, data } = completedAction.payload;
+
+        // Iterate through file list and create entries in Store FS
+        data?.forEach((fileInfo) => {
+          // Build local path: request path + file name
+          const localPath = Pathway.of(request.payload.path)
+            .resolve(fileInfo.name)
+            .getSegments();
+
+          if (fileInfo.isDirectory) {
+            // Create directory with parents flag
+            dispatch(storeFsActions.mkdir(localPath, true));
+          } else {
+            // Create file entry without content (contentIsPresent: false)
+            dispatch(
+              storeFsActions.setFile(localPath, undefined, 'xs:any', {
+                override: true,
+                contentIsPresent: false,
+              })
+            );
+          }
+        });
+        break;
+      }
+
+      case RemoteFsActionTypes.MKDIR_COMPLETED: {
+        const completedAction = anyAction as MkdirCompletedAction;
+        const { request } = completedAction.payload;
+        const localPath = Pathway.of(request.payload.path).getSegments();
+
+        // Create directory in Store FS
+        dispatch(storeFsActions.mkdir(localPath, true));
+        break;
+      }
+
+      case RemoteFsActionTypes.GET_COMPLETED: {
+        const completedAction = anyAction as GetCompletedAction;
+        const { request, data } = completedAction.payload;
+        const localPath = Pathway.of(request.payload.path).getSegments();
+
+        // Parse content
+        let content =
+          data.content === undefined || data.content === null
+            ? undefined
+            : data.content === ''
+            ? undefined
+            : JSON.parse(data.content);
+
+        // Apply content transform if provided
+        if (content !== undefined && transformContent) {
+          content = transformContent(content);
+        }
+
+        // Check if file exists in Store FS
+        const fileSystemNode = fileSystemAdapter.createSelector(
+          (state: S) => (state as any).fileSystem,
+          localPath
+        )(store.getState());
+
+        if (fileSystemNode === undefined) {
+          // File doesn't exist, create it with content
+          dispatch(
+            storeFsActions.setFile(localPath, content, 'xs:any', {
+              override: true,
+              contentIsPresent: true,
+            })
+          );
+        } else {
+          // File exists, update content only if it's a file
+          if (fileSystemNode?.type === 'file') {
+            dispatch(storeFsActions.setFileContent(localPath, content, true));
+          }
+        }
+        break;
+      }
+
+      case RemoteFsActionTypes.POST_COMPLETED:
+      case RemoteFsActionTypes.PUT_COMPLETED: {
+        const completedAction = anyAction as PostCompletedAction | PutCompletedAction;
+        const { request } = completedAction.payload;
+        const localPath = Pathway.of(request.payload.path).getSegments();
+
+        // Reload file content from remote if autoReload is enabled
+        if (autoReload) {
+          dispatch(rfsActions.ofGetRequest(localPath));
+        }
+        break;
+      }
+
+      case RemoteFsActionTypes.DELETE_COMPLETED: {
+        const completedAction = anyAction as DeleteCompletedAction;
+        const { request } = completedAction.payload;
+        const localPath = Pathway.of(request.payload.path).getSegments();
+
+        // Remove node from Store FS
+        dispatch(storeFsActions.removeNode(localPath));
+        break;
+      }
+
+      default:
+        break;
+    }
+
+    return result;
+  };
+
+  return storeSyncMiddleware;
+}
+
+export default createStoreSyncMiddleware;

package/src/plugin/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Remote FS Plugin Factory
+ */
+
+export * from './remote-fs-plugin-factory';

package/src/plugin/remote-fs-plugin-factory.ts

@@ -0,0 +1,238 @@
+/**
+ * Remote FS Plugin Factory
+ *
+ * Creates a microkernel plugin for remote filesystem operations.
+ * Integrates HTTP-based remote filesystem with Redux Store FS.
+ */
+
+import type { PluginModule } from '@hamak/microkernel-spi';
+import type { Pathway } from '@hamak/shared-utils';
+import {
+  WORKSPACE_CLIENT_TOKEN,
+  PATH_TRANSLATOR_TOKEN,
+  REMOTE_FS_SERVICE_TOKEN,
+} from '@hamak/ui-remote-fs-api';
+import { IWorkspaceClient, IPathTranslator, PathTranslator } from '@hamak/ui-remote-fs-spi';
+import { HttpWorkspaceClient, HttpWorkspaceClientConfig } from '../providers/http-workspace-client';
+import { createRemoteFsMiddleware } from '../middleware/remote-fs-middleware';
+import { createStoreSyncMiddleware } from '../middleware/store-sync-middleware';
+import {
+  STORE_MANAGER_TOKEN,
+  STORE_EXTENSIONS_TOKEN,
+  type StoreMiddlewareExtension,
+} from '@hamak/ui-store-api';
+
+/**
+ * Configuration for Remote FS plugin
+ */
+export interface RemoteFsPluginConfig {
+  /**
+   * Workspace identifier
+   */
+  workspaceId: string;
+
+  /**
+   * Mount point for remote filesystem
+   * This is the local path where remote files will be mounted
+   * @example Pathway.ofRoot().resolve('remote')
+   */
+  mountPoint: Pathway;
+
+  /**
+   * Base URL for the workspace API
+   * If not provided, defaults to current origin + '/api'
+   * @example 'http://localhost:3000/api'
+   */
+  baseUrl?: string;
+
+  /**
+   * Request timeout in milliseconds
+   * Default: 30000 (30 seconds)
+   */
+  timeout?: number;
+
+  /**
+   * Whether to automatically reload file content after PUT/POST
+   * Default: true
+   */
+  autoReload?: boolean;
+
+  /**
+   * Optional transform function for file content before storing
+   */
+  transformContent?: (content: any) => any;
+
+  /**
+   * Enable development logging
+   * Default: false
+   */
+  debug?: boolean;
+
+  /**
+   * Custom workspace client (for testing or advanced scenarios)
+   */
+  customClient?: IWorkspaceClient;
+
+  /**
+   * Custom path translator (for advanced scenarios)
+   */
+  customPathTranslator?: IPathTranslator;
+}
+
+/**
+ * Create Remote FS plugin
+ *
+ * This plugin provides remote filesystem capabilities through HTTP API.
+ * It registers two middleware:
+ * - Remote FS Middleware: Handles remote operations via HTTP client
+ * - Store Sync Middleware: Synchronizes remote data to Redux Store FS
+ *
+ * @param config Plugin configuration
+ * @returns PluginModule for microkernel integration
+ *
+ * @example
+ * ```typescript
+ * import { Pathway } from '@hamak/shared-utils';
+ * import { createRemoteFsPlugin } from '@hamak/ui-remote-fs-impl';
+ *
+ * const plugin = createRemoteFsPlugin({
+ *   workspaceId: '0',
+ *   mountPoint: Pathway.ofRoot().resolve('remote'),
+ *   baseUrl: 'http://localhost:3000/api',
+ *   autoReload: true
+ * });
+ * ```
+ */
+export function createRemoteFsPlugin(config: RemoteFsPluginConfig): PluginModule {
+  let workspaceClient: IWorkspaceClient;
+  let pathTranslator: IPathTranslator;
+  let storeManager: any;
+
+  const log = (message: string, ...args: any[]) => {
+    if (config.debug) {
+      console.log(`[ui-remote-fs] ${message}`, ...args);
+    }
+  };
+
+  return {
+    async initialize(ctx) {
+      log('Initializing plugin...');
+
+      // Create or use custom workspace client
+      if (config.customClient) {
+        workspaceClient = config.customClient;
+        log('Using custom workspace client');
+      } else {
+        const clientConfig: HttpWorkspaceClientConfig = {
+          workspaceId: config.workspaceId,
+          baseUrl: config.baseUrl,
+          timeout: config.timeout,
+        };
+        workspaceClient = new HttpWorkspaceClient(clientConfig);
+        log('Created HTTP workspace client', { baseUrl: config.baseUrl, workspaceId: config.workspaceId });
+      }
+
+      // Create or use custom path translator
+      if (config.customPathTranslator) {
+        pathTranslator = config.customPathTranslator;
+        log('Using custom path translator');
+      } else {
+        pathTranslator = new PathTranslator(config.mountPoint);
+        log('Created path translator', { mountPoint: config.mountPoint.getSegments() });
+      }
+
+      // Register services via DI
+      ctx.provide({ provide: WORKSPACE_CLIENT_TOKEN, useValue: workspaceClient });
+      ctx.provide({ provide: PATH_TRANSLATOR_TOKEN, useValue: pathTranslator });
+
+      // Note: IRemoteFsService implementation will be added in future phases
+      // ctx.provide({ provide: REMOTE_FS_SERVICE_TOKEN, useValue: remoteFsService });
+
+      log('Plugin initialized');
+    },
+
+    async activate(ctx) {
+      log('Activating plugin...');
+
+      // Resolve store manager from DI
+      try {
+        storeManager = ctx.resolve(STORE_MANAGER_TOKEN);
+      } catch (error) {
+        throw new Error(
+          '[ui-remote-fs] Store manager not found. Ensure @hamak/ui-store plugin is loaded before ui-remote-fs.'
+        );
+      }
+
+      // Get file system adapter from store
+      const fileSystemAdapter = storeManager.getFileSystemAdapter();
+      if (!fileSystemAdapter) {
+        throw new Error('[ui-remote-fs] File system adapter not found in store manager.');
+      }
+
+      // Get store extensions collector
+      const extensionsCollector = ctx.resolve(STORE_EXTENSIONS_TOKEN) as any;
+
+      // Create and register remote FS middleware
+      const remoteFsMiddleware = createRemoteFsMiddleware({
+        client: workspaceClient,
+        pathTranslator,
+        onError: (error, action) => {
+          log('Remote FS error:', error, action);
+          ctx.hooks.emit('ui-remote-fs:error', { error, action });
+        },
+        onSuccess: (result, action) => {
+          log('Remote FS success:', action.type);
+          ctx.hooks.emit('ui-remote-fs:success', { result, action });
+        },
+      });
+
+      // Create and register store sync middleware
+      const storeSyncMiddleware = createStoreSyncMiddleware({
+        fileSystemAdapter,
+        pathTranslator,
+        autoReload: config.autoReload,
+        transformContent: config.transformContent,
+      });
+
+      // Register middleware with store extensions
+      const middlewareExtensions: StoreMiddlewareExtension[] = [
+        {
+          id: 'remote-fs',
+          middleware: remoteFsMiddleware,
+          priority: 100,
+          plugin: 'ui-remote-fs',
+          description: 'Handles remote filesystem operations via HTTP',
+        },
+        {
+          id: 'store-sync',
+          middleware: storeSyncMiddleware,
+          priority: 50,
+          plugin: 'ui-remote-fs',
+          description: 'Synchronizes remote FS to Redux Store FS',
+        },
+      ];
+
+      extensionsCollector.register('ui-remote-fs:middleware', {
+        middleware: middlewareExtensions,
+      });
+
+      log('Middleware registered');
+
+      // Emit ready event
+      ctx.hooks.emit('ui-remote-fs:ready', {
+        workspaceClient,
+        pathTranslator,
+        mountPoint: config.mountPoint,
+      });
+
+      log('Plugin activated');
+    },
+
+    async deactivate() {
+      log('Plugin deactivated');
+      // Cleanup if needed
+    },
+  };
+}
+
+export default createRemoteFsPlugin;

package/src/providers/http-workspace-client.ts

@@ -0,0 +1,232 @@
+/**
+ * HTTP Workspace Client
+ *
+ * HTTP-based implementation of IWorkspaceClient using Axios.
+ * Migrated from amk/libs/server/ws/ws-client/src/lib/server-ws-ws-client.ts
+ */
+
+import axios, { AxiosInstance, AxiosError } from 'axios';
+import { IWorkspaceClient } from '@hamak/ui-remote-fs-spi';
+import { FileInfo } from '@hamak/shared-utils';
+import { ErrorObject } from '@hamak/ui-remote-fs-api';
+
+/**
+ * Configuration for HTTP workspace client
+ */
+export interface HttpWorkspaceClientConfig {
+  /**
+   * Base URL for the API (e.g., 'http://localhost:3000/api')
+   * If not provided, defaults to current origin + '/api'
+   */
+  baseUrl?: string;
+
+  /**
+   * Workspace identifier
+   */
+  workspaceId: string;
+
+  /**
+   * Request timeout in milliseconds
+   * Default: 30000 (30 seconds)
+   */
+  timeout?: number;
+
+  /**
+   * Custom axios instance (for advanced configuration)
+   */
+  axiosInstance?: AxiosInstance;
+}
+
+/**
+ * HTTP-based implementation of IWorkspaceClient
+ *
+ * This implementation uses Axios to communicate with a REST API backend.
+ * Supports configurable base URL, timeout, and custom axios instances.
+ *
+ * @example
+ * ```typescript
+ * const client = new HttpWorkspaceClient({
+ *   workspaceId: '0',
+ *   baseUrl: 'http://localhost:3000/api'
+ * });
+ *
+ * const files = await client.listFiles(['folder', 'subfolder']);
+ * ```
+ */
+export class HttpWorkspaceClient implements IWorkspaceClient {
+  private readonly workspaceId: string;
+  private readonly baseUrl: string;
+  private readonly axios: AxiosInstance;
+
+  constructor(config: HttpWorkspaceClientConfig) {
+    this.workspaceId = config.workspaceId;
+
+    // Default base URL to current origin if not provided
+    this.baseUrl = config.baseUrl ||
+      (typeof globalThis !== 'undefined' && 'location' in globalThis
+        ? `${(globalThis as any).location.protocol}//${(globalThis as any).location.host}/api`
+        : '/api');
+
+    // Use provided axios instance or create new one
+    this.axios = config.axiosInstance || axios.create({
+      baseURL: this.baseUrl,
+      timeout: config.timeout || 30000,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    });
+  }
+
+  /**
+   * Format path segments to URL path string
+   */
+  private formatPath(path: string[]): string {
+    return path.join('/');
+  }
+
+  /**
+   * Handle axios errors and convert to ErrorObject
+   */
+  private handleError(error: unknown): never {
+    if (axios.isAxiosError(error)) {
+      const axiosError = error as AxiosError<{ error?: ErrorObject }>;
+
+      // Try to extract error from response
+      if (axiosError.response?.data?.error) {
+        throw axiosError.response.data.error;
+      }
+
+      // Create error from axios error
+      const errorObj: ErrorObject = {
+        code: axiosError.code || 'UNKNOWN',
+        message: axiosError.message || 'Unknown error occurred',
+        params: {
+          status: axiosError.response?.status,
+          statusText: axiosError.response?.statusText,
+        },
+      };
+      throw errorObj;
+    }
+
+    // Handle non-axios errors
+    const errorObj: ErrorObject = {
+      code: 'UNKNOWN',
+      message: error instanceof Error ? error.message : 'Unknown error occurred',
+    };
+    throw errorObj;
+  }
+
+  /**
+   * Serialize content to string for transmission
+   */
+  private serializeContent(content: any): string {
+    if (typeof content === 'string') {
+      return content;
+    }
+    return JSON.stringify(content);
+  }
+
+  /**
+   * List files and directories at the specified path
+   */
+  async listFiles(path: string[]): Promise<FileInfo[]> {
+    try {
+      const formattedPath = this.formatPath(path);
+      const response = await this.axios.get<FileInfo[]>(
+        `/workspaces/${this.workspaceId}/files/${formattedPath}`
+      );
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  /**
+   * Create a directory at the specified path
+   */
+  async createDirectory(path: string[]): Promise<FileInfo> {
+    try {
+      const formattedPath = this.formatPath(path);
+      const response = await this.axios.post<FileInfo>(
+        `/workspaces/${this.workspaceId}/mkdir/${formattedPath}`
+      );
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  /**
+   * Read a file's metadata and content
+   */
+  async readFile(path: string[]): Promise<FileInfo> {
+    try {
+      const formattedPath = this.formatPath(path);
+      const response = await this.axios.get<FileInfo>(
+        `/workspaces/${this.workspaceId}/read/${formattedPath}`
+      );
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  /**
+   * Write or update a file's content (uses PUT method)
+   */
+  async putFile(path: string[], content: any): Promise<FileInfo> {
+    try {
+      const formattedPath = this.formatPath(path);
+      const serializedContent = this.serializeContent(content);
+      const response = await this.axios.put<FileInfo>(
+        `/workspaces/${this.workspaceId}/put/${formattedPath}`,
+        { content: serializedContent }
+      );
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  /**
+   * Delete a file or directory
+   */
+  async deleteFile(path: string[]): Promise<FileInfo> {
+    try {
+      const formattedPath = this.formatPath(path);
+      const response = await this.axios.delete<FileInfo>(
+        `/workspaces/${this.workspaceId}/delete/${formattedPath}`
+      );
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  /**
+   * Get the workspace ID
+   */
+  getWorkspaceId(): string {
+    return this.workspaceId;
+  }
+
+  /**
+   * Get the base URL
+   */
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+}
+
+/**
+ * Factory function to create HTTP workspace client with default configuration
+ */
+export function createHttpWorkspaceClient(
+  workspaceId: string,
+  baseUrl?: string
+): HttpWorkspaceClient {
+  return new HttpWorkspaceClient({
+    workspaceId,
+    baseUrl,
+  });
+}

package/src/providers/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Remote FS Providers
+ */
+
+export * from './http-workspace-client';

package/src/services/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Remote FS Services
+ */
+
+export * from './remote-fs-service';

package/src/services/remote-fs-service.ts

@@ -0,0 +1,13 @@
+/**
+ * Remote FS Service
+ *
+ * Service implementation for remote filesystem operations.
+ * Will be implemented in future phases.
+ */
+
+// Placeholder - will be implemented in future phases
+export class RemoteFsService {
+  constructor() {
+    throw new Error('Not yet implemented');
+  }
+}

package/tsconfig.es2015.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2015",
+    "module": "CommonJS",
+    "lib": ["ES2015"],
+    "skipLibCheck": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "strict": true,
+    "outDir": "./dist/es2015",
+    "rootDir": "./src",
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": false,
+    "downlevelIteration": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}