@loopstack/remote-file-explorer-module 0.24.0 → 0.24.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +123 -28
  2. package/package.json +10 -3
package/README.md CHANGED
@@ -1,18 +1,20 @@
1
- # @loopstack/remote-file-explorer-module
2
-
3
- > A module for the [Loopstack AI](https://loopstack.ai) automation framework.
1
+ ---
2
+ title: Remote File Explorer Module
3
+ description: REST API controller for browsing files on remote Loopstack workspaces — RemoteFileExplorerModule, RemoteFileExplorerController, file tree and file content endpoints, proxies requests via RemoteClient and EnvironmentService
4
+ ---
4
5
 
5
- REST endpoints for browsing files in a Loopstack remote workspace. A thin proxy over `@loopstack/remote-client` designed to back a file-tree UI.
6
+ # @loopstack/remote-file-explorer-module
6
7
 
7
- ## Overview
8
+ > File browsing module for the [Loopstack](https://loopstack.ai) automation framework.
8
9
 
9
- When a UI (like the Loopstack Studio) needs to render a file tree and file contents for a remote workspace, it talks to `RemoteFileExplorerController`. The controller forwards the request to the workspace's remote agent via `RemoteClient`. No workflow tools are exposed by this module — if you want to read files from a workflow, use `ReadTool` / `GlobTool` from `@loopstack/remote-client` instead.
10
+ Exposes REST endpoints that let a frontend (like Loopstack Studio) browse the file system of a remote workspace. The controller resolves the workspace's remote agent URL and proxies requests through `RemoteClient` from `@loopstack/remote-client`.
10
11
 
11
- By using this module you'll get:
12
+ ## When to Use
12
13
 
13
- - **`RemoteFileExplorerController`** with two endpoints:
14
- - `GET /remote-file-explorer/tree?path=...` — returns the directory tree
15
- - `GET /remote-file-explorer/content?path=...` — returns the contents of a single file
14
+ - You are building a UI that needs to render a **file tree** and display **file contents** for a remote workspace.
15
+ - You want authenticated REST endpoints that proxy file requests to a remote agent without exposing the agent URL to the client.
16
+ - Use `@loopstack/local-file-explorer-module` instead if the files are on the local machine.
17
+ - Use `GlobTool` / `ReadTool` from `@loopstack/remote-client` instead if you need file access inside a workflow (this module provides no workflow tools).
16
18
 
17
19
  ## Installation
18
20
 
@@ -20,48 +22,141 @@ By using this module you'll get:
20
22
  npm install @loopstack/remote-file-explorer-module
21
23
  ```
22
24
 
23
- Register the module:
25
+ Register the module in your app:
24
26
 
25
27
  ```ts
28
+ import { Module } from '@nestjs/common';
26
29
  import { RemoteFileExplorerModule } from '@loopstack/remote-file-explorer-module';
27
30
 
28
31
  @Module({
29
- imports: [RemoteFileExplorerModule /* ... */],
32
+ imports: [RemoteFileExplorerModule],
30
33
  })
31
34
  export class AppModule {}
32
35
  ```
33
36
 
34
- `RemoteFileExplorerModule` depends on `RemoteClientModule`, `LoopCoreModule`, and uses `WorkspaceEntity` via TypeORM.
37
+ `RemoteFileExplorerModule` depends on `RemoteClient` and `EnvironmentService` from `@loopstack/remote-client`, which must be available in the DI container (import `RemoteClientModule` in a parent module).
35
38
 
36
- ## How It Works
39
+ ### Feature gating
40
+
41
+ Use `forFeature()` to register the module with optional feature-flag configuration:
37
42
 
38
- Once registered, the two endpoints are available on your backend. They resolve the workspace (from query / body params) and proxy to the workspace's remote agent:
43
+ ```ts
44
+ RemoteFileExplorerModule.forFeature({ enabled: true, environments: ['production'] });
45
+ ```
46
+
47
+ ## Quick Start
48
+
49
+ Once imported, the controller is available at `/api/v1/workspaces/:workspaceId/files`. No additional setup is required beyond having `RemoteClientModule` registered.
39
50
 
40
51
  ```http
41
- GET /remote-file-explorer/tree?workspaceId=<id>&path=src
42
- GET /remote-file-explorer/content?workspaceId=<id>&path=src/index.ts
52
+ GET /api/v1/workspaces/:workspaceId/files/tree?path=src
53
+ GET /api/v1/workspaces/:workspaceId/files/read?path=src/index.ts
54
+ ```
55
+
56
+ Both endpoints require an authenticated user (resolved via `@CurrentUser()`).
57
+
58
+ ## How It Works
59
+
60
+ ```
61
+ Frontend (Studio)
62
+ |
63
+ | GET /api/v1/workspaces/:workspaceId/files/tree?path=src
64
+ v
65
+ RemoteFileExplorerController
66
+ |
67
+ | EnvironmentService.getAgentUrlForWorkspace(workspaceId)
68
+ | -> resolves the remote agent URL for the workspace
69
+ |
70
+ | RemoteClient.getFileTree(agentUrl, path)
71
+ v
72
+ Remote Agent (remote-server)
73
+ |
74
+ | reads filesystem, returns FileTreeNode[]
75
+ v
76
+ Response -> Frontend
77
+ ```
78
+
79
+ The controller has two endpoints:
80
+
81
+ 1. **`GET tree`** -- calls `RemoteClient.getFileTree()`. Defaults to `./src` if no `path` query param is provided.
82
+ 2. **`GET read`** -- calls `RemoteClient.readFile()`. Requires a `path` query param.
83
+
84
+ Both endpoints resolve the workspace's agent URL via `EnvironmentService.getAgentUrlForWorkspace()` before proxying.
85
+
86
+ ## Endpoints Reference
87
+
88
+ ### GET `/api/v1/workspaces/:workspaceId/files/tree`
89
+
90
+ Returns the directory tree for the given path.
91
+
92
+ | Parameter | In | Type | Required | Description |
93
+ | ------------- | ----- | -------- | -------- | --------------------------------------- |
94
+ | `workspaceId` | path | `string` | yes | The workspace ID |
95
+ | `path` | query | `string` | no | Base path to list (defaults to `./src`) |
96
+
97
+ **Response:** `FileTreeNode[]`
98
+
99
+ ```ts
100
+ interface FileTreeNode {
101
+ id: string;
102
+ name: string;
103
+ path: string;
104
+ type: 'file' | 'folder';
105
+ children?: FileTreeNode[];
106
+ }
107
+ ```
108
+
109
+ ### GET `/api/v1/workspaces/:workspaceId/files/read`
110
+
111
+ Returns the content of a single file.
112
+
113
+ | Parameter | In | Type | Required | Description |
114
+ | ------------- | ----- | -------- | -------- | ----------------- |
115
+ | `workspaceId` | path | `string` | yes | The workspace ID |
116
+ | `path` | query | `string` | yes | File path to read |
117
+
118
+ **Response:** `FileReadResponse`
119
+
120
+ ```ts
121
+ interface FileReadResponse {
122
+ content: string;
123
+ }
43
124
  ```
44
125
 
45
- See `src/controllers/remote-file-explorer.controller.ts` for the exact shape of each response.
126
+ ## Configuration
127
+
128
+ `RemoteFileExplorerModule.forFeature()` accepts an optional config object:
129
+
130
+ | Option | Type | Default | Description |
131
+ | -------------- | ---------- | ------- | -------------------------------------- |
132
+ | `enabled` | `boolean` | `true` | Whether the feature is active |
133
+ | `environments` | `string[]` | all | Restrict to specific environment names |
134
+
135
+ No environment variables are required by this module itself. The remote agent URL is resolved at runtime by `EnvironmentService` from `@loopstack/remote-client`.
46
136
 
47
137
  ## Public API
48
138
 
49
- - **Module:** `RemoteFileExplorerModule`
50
- - **Controller:** `RemoteFileExplorerController`
139
+ - **Module:** `RemoteFileExplorerModule` -- NestJS module with `forFeature()` static method
140
+ - **Controller:** `RemoteFileExplorerController` -- REST controller with `getFileTree()` and `readFile()` endpoints
51
141
 
52
142
  ## Dependencies
53
143
 
54
- - `@loopstack/common`, `@loopstack/core` — framework
55
- - `@loopstack/remote-client` — underlying remote file access
56
- - `@nestjs/typeorm`, `typeorm` — workspace persistence
144
+ | Package | Role |
145
+ | -------------------------- | ----------------------------------------------- |
146
+ | `@loopstack/common` | Shared utilities, `CurrentUser` decorator |
147
+ | `@loopstack/remote-client` | `RemoteClient` service and `EnvironmentService` |
148
+ | `@nestjs/common` | NestJS framework |
149
+ | `@nestjs/typeorm` | TypeORM integration |
150
+ | `typeorm` | ORM |
151
+
152
+ ## Related
153
+
154
+ - [`@loopstack/remote-client`](https://loopstack.ai/docs/registry/features/remote-client-module) -- the underlying client this module proxies through; also provides `GlobTool`, `ReadTool`, and other workflow tools for remote file operations
155
+ - [`@loopstack/local-file-explorer-module`](https://loopstack.ai/docs/registry/features/local-file-explorer-module) -- same concept for local filesystems instead of remote agents
156
+ - [Remote File Explorer example workflow](https://github.com/nicobrinkkemper/loopstack/tree/main/registry/examples/remote-file-explorer-example-workflow) -- demonstrates using `GlobTool` and `ReadTool` from `@loopstack/remote-client` in a workflow
57
157
 
58
158
  ## About
59
159
 
60
160
  Author: [Jakob Klippel](https://www.linkedin.com/in/jakob-klippel/)
61
161
 
62
162
  License: MIT
63
-
64
- ### Additional Resources
65
-
66
- - [Loopstack Documentation](https://loopstack.ai/docs)
67
- - Find more Loopstack modules in the [Loopstack Registry](https://loopstack.ai/registry)
package/package.json CHANGED
@@ -8,7 +8,7 @@
8
8
  "remote-agent",
9
9
  "workflow"
10
10
  ],
11
- "version": "0.24.0",
11
+ "version": "0.24.2",
12
12
  "license": "MIT",
13
13
  "author": {
14
14
  "name": "Jakob Klippel",
@@ -31,12 +31,19 @@
31
31
  "watch": "nest build --watch"
32
32
  },
33
33
  "dependencies": {
34
- "@loopstack/common": "^0.32.0",
35
- "@loopstack/remote-client": "^0.25.0",
34
+ "@loopstack/common": "^0.33.0",
35
+ "@loopstack/remote-client": "^0.25.2"
36
+ },
37
+ "devDependencies": {
36
38
  "@nestjs/common": "^11.1.19",
37
39
  "@nestjs/typeorm": "^11.0.1",
38
40
  "typeorm": "^0.3.28"
39
41
  },
42
+ "peerDependencies": {
43
+ "@nestjs/common": "^11.0.0",
44
+ "@nestjs/typeorm": "^11.0.0",
45
+ "typeorm": "^0.3.0"
46
+ },
40
47
  "files": [
41
48
  "dist"
42
49
  ],