gitx.do 0.0.1 → 0.0.3

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 (237) hide show
  1. package/dist/cli/commands/blame.d.ts +259 -0
  2. package/dist/cli/commands/blame.d.ts.map +1 -0
  3. package/dist/cli/commands/blame.js +609 -0
  4. package/dist/cli/commands/blame.js.map +1 -0
  5. package/dist/cli/commands/branch.d.ts +249 -0
  6. package/dist/cli/commands/branch.d.ts.map +1 -0
  7. package/dist/cli/commands/branch.js +693 -0
  8. package/dist/cli/commands/branch.js.map +1 -0
  9. package/dist/cli/commands/commit.d.ts +182 -0
  10. package/dist/cli/commands/commit.d.ts.map +1 -0
  11. package/dist/cli/commands/commit.js +437 -0
  12. package/dist/cli/commands/commit.js.map +1 -0
  13. package/dist/cli/commands/diff.d.ts +464 -0
  14. package/dist/cli/commands/diff.d.ts.map +1 -0
  15. package/dist/cli/commands/diff.js +958 -0
  16. package/dist/cli/commands/diff.js.map +1 -0
  17. package/dist/cli/commands/log.d.ts +239 -0
  18. package/dist/cli/commands/log.d.ts.map +1 -0
  19. package/dist/cli/commands/log.js +535 -0
  20. package/dist/cli/commands/log.js.map +1 -0
  21. package/dist/cli/commands/review.d.ts +457 -0
  22. package/dist/cli/commands/review.d.ts.map +1 -0
  23. package/dist/cli/commands/review.js +533 -0
  24. package/dist/cli/commands/review.js.map +1 -0
  25. package/dist/cli/commands/status.d.ts +269 -0
  26. package/dist/cli/commands/status.d.ts.map +1 -0
  27. package/dist/cli/commands/status.js +493 -0
  28. package/dist/cli/commands/status.js.map +1 -0
  29. package/dist/cli/commands/web.d.ts +199 -0
  30. package/dist/cli/commands/web.d.ts.map +1 -0
  31. package/dist/cli/commands/web.js +696 -0
  32. package/dist/cli/commands/web.js.map +1 -0
  33. package/dist/cli/fs-adapter.d.ts +656 -0
  34. package/dist/cli/fs-adapter.d.ts.map +1 -0
  35. package/dist/cli/fs-adapter.js +1179 -0
  36. package/dist/cli/fs-adapter.js.map +1 -0
  37. package/dist/cli/index.d.ts +387 -0
  38. package/dist/cli/index.d.ts.map +1 -0
  39. package/dist/cli/index.js +523 -0
  40. package/dist/cli/index.js.map +1 -0
  41. package/dist/cli/ui/components/DiffView.d.ts +7 -0
  42. package/dist/cli/ui/components/DiffView.d.ts.map +1 -0
  43. package/dist/cli/ui/components/DiffView.js +11 -0
  44. package/dist/cli/ui/components/DiffView.js.map +1 -0
  45. package/dist/cli/ui/components/ErrorDisplay.d.ts +6 -0
  46. package/dist/cli/ui/components/ErrorDisplay.d.ts.map +1 -0
  47. package/dist/cli/ui/components/ErrorDisplay.js +11 -0
  48. package/dist/cli/ui/components/ErrorDisplay.js.map +1 -0
  49. package/dist/cli/ui/components/FuzzySearch.d.ts +9 -0
  50. package/dist/cli/ui/components/FuzzySearch.d.ts.map +1 -0
  51. package/dist/cli/ui/components/FuzzySearch.js +12 -0
  52. package/dist/cli/ui/components/FuzzySearch.js.map +1 -0
  53. package/dist/cli/ui/components/LoadingSpinner.d.ts +6 -0
  54. package/dist/cli/ui/components/LoadingSpinner.d.ts.map +1 -0
  55. package/dist/cli/ui/components/LoadingSpinner.js +10 -0
  56. package/dist/cli/ui/components/LoadingSpinner.js.map +1 -0
  57. package/dist/cli/ui/components/NavigationList.d.ts +9 -0
  58. package/dist/cli/ui/components/NavigationList.d.ts.map +1 -0
  59. package/dist/cli/ui/components/NavigationList.js +11 -0
  60. package/dist/cli/ui/components/NavigationList.js.map +1 -0
  61. package/dist/cli/ui/components/ScrollableContent.d.ts +8 -0
  62. package/dist/cli/ui/components/ScrollableContent.d.ts.map +1 -0
  63. package/dist/cli/ui/components/ScrollableContent.js +11 -0
  64. package/dist/cli/ui/components/ScrollableContent.js.map +1 -0
  65. package/dist/cli/ui/components/index.d.ts +7 -0
  66. package/dist/cli/ui/components/index.d.ts.map +1 -0
  67. package/dist/cli/ui/components/index.js +9 -0
  68. package/dist/cli/ui/components/index.js.map +1 -0
  69. package/dist/cli/ui/terminal-ui.d.ts +52 -0
  70. package/dist/cli/ui/terminal-ui.d.ts.map +1 -0
  71. package/dist/cli/ui/terminal-ui.js +121 -0
  72. package/dist/cli/ui/terminal-ui.js.map +1 -0
  73. package/dist/durable-object/object-store.d.ts +401 -23
  74. package/dist/durable-object/object-store.d.ts.map +1 -1
  75. package/dist/durable-object/object-store.js +414 -25
  76. package/dist/durable-object/object-store.js.map +1 -1
  77. package/dist/durable-object/schema.d.ts +188 -0
  78. package/dist/durable-object/schema.d.ts.map +1 -1
  79. package/dist/durable-object/schema.js +160 -0
  80. package/dist/durable-object/schema.js.map +1 -1
  81. package/dist/durable-object/wal.d.ts +336 -31
  82. package/dist/durable-object/wal.d.ts.map +1 -1
  83. package/dist/durable-object/wal.js +272 -27
  84. package/dist/durable-object/wal.js.map +1 -1
  85. package/dist/index.d.ts +379 -3
  86. package/dist/index.d.ts.map +1 -1
  87. package/dist/index.js +379 -7
  88. package/dist/index.js.map +1 -1
  89. package/dist/mcp/adapter.d.ts +579 -38
  90. package/dist/mcp/adapter.d.ts.map +1 -1
  91. package/dist/mcp/adapter.js +426 -33
  92. package/dist/mcp/adapter.js.map +1 -1
  93. package/dist/mcp/sandbox.d.ts +532 -29
  94. package/dist/mcp/sandbox.d.ts.map +1 -1
  95. package/dist/mcp/sandbox.js +389 -22
  96. package/dist/mcp/sandbox.js.map +1 -1
  97. package/dist/mcp/sdk-adapter.d.ts +478 -56
  98. package/dist/mcp/sdk-adapter.d.ts.map +1 -1
  99. package/dist/mcp/sdk-adapter.js +346 -44
  100. package/dist/mcp/sdk-adapter.js.map +1 -1
  101. package/dist/mcp/tools.d.ts +445 -30
  102. package/dist/mcp/tools.d.ts.map +1 -1
  103. package/dist/mcp/tools.js +363 -33
  104. package/dist/mcp/tools.js.map +1 -1
  105. package/dist/ops/blame.d.ts +424 -21
  106. package/dist/ops/blame.d.ts.map +1 -1
  107. package/dist/ops/blame.js +303 -20
  108. package/dist/ops/blame.js.map +1 -1
  109. package/dist/ops/branch.d.ts +583 -32
  110. package/dist/ops/branch.d.ts.map +1 -1
  111. package/dist/ops/branch.js +365 -23
  112. package/dist/ops/branch.js.map +1 -1
  113. package/dist/ops/commit-traversal.d.ts +164 -24
  114. package/dist/ops/commit-traversal.d.ts.map +1 -1
  115. package/dist/ops/commit-traversal.js +68 -2
  116. package/dist/ops/commit-traversal.js.map +1 -1
  117. package/dist/ops/commit.d.ts +387 -53
  118. package/dist/ops/commit.d.ts.map +1 -1
  119. package/dist/ops/commit.js +249 -29
  120. package/dist/ops/commit.js.map +1 -1
  121. package/dist/ops/merge-base.d.ts +195 -21
  122. package/dist/ops/merge-base.d.ts.map +1 -1
  123. package/dist/ops/merge-base.js +122 -12
  124. package/dist/ops/merge-base.js.map +1 -1
  125. package/dist/ops/merge.d.ts +600 -130
  126. package/dist/ops/merge.d.ts.map +1 -1
  127. package/dist/ops/merge.js +408 -60
  128. package/dist/ops/merge.js.map +1 -1
  129. package/dist/ops/tag.d.ts +67 -2
  130. package/dist/ops/tag.d.ts.map +1 -1
  131. package/dist/ops/tag.js +42 -1
  132. package/dist/ops/tag.js.map +1 -1
  133. package/dist/ops/tree-builder.d.ts +102 -6
  134. package/dist/ops/tree-builder.d.ts.map +1 -1
  135. package/dist/ops/tree-builder.js +30 -5
  136. package/dist/ops/tree-builder.js.map +1 -1
  137. package/dist/ops/tree-diff.d.ts +50 -2
  138. package/dist/ops/tree-diff.d.ts.map +1 -1
  139. package/dist/ops/tree-diff.js +50 -2
  140. package/dist/ops/tree-diff.js.map +1 -1
  141. package/dist/pack/delta.d.ts +211 -39
  142. package/dist/pack/delta.d.ts.map +1 -1
  143. package/dist/pack/delta.js +232 -46
  144. package/dist/pack/delta.js.map +1 -1
  145. package/dist/pack/format.d.ts +390 -28
  146. package/dist/pack/format.d.ts.map +1 -1
  147. package/dist/pack/format.js +344 -33
  148. package/dist/pack/format.js.map +1 -1
  149. package/dist/pack/full-generation.d.ts +313 -28
  150. package/dist/pack/full-generation.d.ts.map +1 -1
  151. package/dist/pack/full-generation.js +238 -19
  152. package/dist/pack/full-generation.js.map +1 -1
  153. package/dist/pack/generation.d.ts +346 -23
  154. package/dist/pack/generation.d.ts.map +1 -1
  155. package/dist/pack/generation.js +269 -21
  156. package/dist/pack/generation.js.map +1 -1
  157. package/dist/pack/index.d.ts +407 -86
  158. package/dist/pack/index.d.ts.map +1 -1
  159. package/dist/pack/index.js +351 -70
  160. package/dist/pack/index.js.map +1 -1
  161. package/dist/refs/branch.d.ts +517 -71
  162. package/dist/refs/branch.d.ts.map +1 -1
  163. package/dist/refs/branch.js +410 -26
  164. package/dist/refs/branch.js.map +1 -1
  165. package/dist/refs/storage.d.ts +610 -57
  166. package/dist/refs/storage.d.ts.map +1 -1
  167. package/dist/refs/storage.js +481 -29
  168. package/dist/refs/storage.js.map +1 -1
  169. package/dist/refs/tag.d.ts +677 -67
  170. package/dist/refs/tag.d.ts.map +1 -1
  171. package/dist/refs/tag.js +497 -30
  172. package/dist/refs/tag.js.map +1 -1
  173. package/dist/storage/lru-cache.d.ts +556 -53
  174. package/dist/storage/lru-cache.d.ts.map +1 -1
  175. package/dist/storage/lru-cache.js +439 -36
  176. package/dist/storage/lru-cache.js.map +1 -1
  177. package/dist/storage/object-index.d.ts +483 -38
  178. package/dist/storage/object-index.d.ts.map +1 -1
  179. package/dist/storage/object-index.js +388 -22
  180. package/dist/storage/object-index.js.map +1 -1
  181. package/dist/storage/r2-pack.d.ts +957 -94
  182. package/dist/storage/r2-pack.d.ts.map +1 -1
  183. package/dist/storage/r2-pack.js +756 -48
  184. package/dist/storage/r2-pack.js.map +1 -1
  185. package/dist/tiered/cdc-pipeline.d.ts +1610 -38
  186. package/dist/tiered/cdc-pipeline.d.ts.map +1 -1
  187. package/dist/tiered/cdc-pipeline.js +1131 -22
  188. package/dist/tiered/cdc-pipeline.js.map +1 -1
  189. package/dist/tiered/migration.d.ts +903 -41
  190. package/dist/tiered/migration.d.ts.map +1 -1
  191. package/dist/tiered/migration.js +646 -24
  192. package/dist/tiered/migration.js.map +1 -1
  193. package/dist/tiered/parquet-writer.d.ts +944 -47
  194. package/dist/tiered/parquet-writer.d.ts.map +1 -1
  195. package/dist/tiered/parquet-writer.js +667 -39
  196. package/dist/tiered/parquet-writer.js.map +1 -1
  197. package/dist/tiered/read-path.d.ts +728 -34
  198. package/dist/tiered/read-path.d.ts.map +1 -1
  199. package/dist/tiered/read-path.js +310 -27
  200. package/dist/tiered/read-path.js.map +1 -1
  201. package/dist/types/objects.d.ts +457 -0
  202. package/dist/types/objects.d.ts.map +1 -1
  203. package/dist/types/objects.js +305 -4
  204. package/dist/types/objects.js.map +1 -1
  205. package/dist/types/storage.d.ts +407 -35
  206. package/dist/types/storage.d.ts.map +1 -1
  207. package/dist/types/storage.js +27 -3
  208. package/dist/types/storage.js.map +1 -1
  209. package/dist/utils/hash.d.ts +133 -12
  210. package/dist/utils/hash.d.ts.map +1 -1
  211. package/dist/utils/hash.js +133 -12
  212. package/dist/utils/hash.js.map +1 -1
  213. package/dist/utils/sha1.d.ts +102 -9
  214. package/dist/utils/sha1.d.ts.map +1 -1
  215. package/dist/utils/sha1.js +114 -11
  216. package/dist/utils/sha1.js.map +1 -1
  217. package/dist/wire/capabilities.d.ts +896 -88
  218. package/dist/wire/capabilities.d.ts.map +1 -1
  219. package/dist/wire/capabilities.js +566 -62
  220. package/dist/wire/capabilities.js.map +1 -1
  221. package/dist/wire/pkt-line.d.ts +293 -15
  222. package/dist/wire/pkt-line.d.ts.map +1 -1
  223. package/dist/wire/pkt-line.js +251 -15
  224. package/dist/wire/pkt-line.js.map +1 -1
  225. package/dist/wire/receive-pack.d.ts +814 -64
  226. package/dist/wire/receive-pack.d.ts.map +1 -1
  227. package/dist/wire/receive-pack.js +542 -41
  228. package/dist/wire/receive-pack.js.map +1 -1
  229. package/dist/wire/smart-http.d.ts +575 -97
  230. package/dist/wire/smart-http.d.ts.map +1 -1
  231. package/dist/wire/smart-http.js +337 -46
  232. package/dist/wire/smart-http.js.map +1 -1
  233. package/dist/wire/upload-pack.d.ts +492 -98
  234. package/dist/wire/upload-pack.d.ts.map +1 -1
  235. package/dist/wire/upload-pack.js +347 -59
  236. package/dist/wire/upload-pack.js.map +1 -1
  237. package/package.json +10 -2
@@ -1 +1 @@
1
- {"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/mcp/sandbox.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/mcp/sandbox.ts"],"names":[],"mappings":"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"}
@@ -1,46 +1,142 @@
1
1
  /**
2
- * MCP Sandbox Execution Environment
2
+ * @fileoverview MCP Sandbox Execution Environment
3
3
  *
4
- * Provides isolated execution environment for MCP tools with:
5
- * - Resource limits (memory, CPU, time)
6
- * - Capability restrictions (file, network, process)
7
- * - Safe git operation execution
8
- * - Audit logging
4
+ * Provides an isolated execution environment for MCP tools with:
5
+ * - Resource limits (memory, CPU, time, file descriptors, disk)
6
+ * - Capability restrictions (file read/write, network, process spawning)
7
+ * - Safe git operation execution with permission checks
8
+ * - Audit logging for security violations
9
9
  *
10
- * SECURITY: Uses Node.js vm module for proper isolation instead of
11
- * string analysis, which can be easily bypassed.
10
+ * SECURITY: Uses Node.js vm module concepts for proper isolation. The sandbox
11
+ * implements multi-layer security through:
12
+ * 1. Pre-execution static analysis to detect dangerous patterns
13
+ * 2. Runtime permission checks via Proxy-based module interception
14
+ * 3. Resource limit enforcement during execution
15
+ * 4. Permission violation recording for audit trails
16
+ *
17
+ * @module mcp/sandbox
18
+ *
19
+ * @example
20
+ * // Create a sandbox with limited permissions
21
+ * import { createSandbox, SandboxState } from './sandbox'
22
+ *
23
+ * const sandbox = createSandbox({
24
+ * timeout: 5000,
25
+ * memoryLimit: 128 * 1024 * 1024,
26
+ * permissions: {
27
+ * fileRead: true,
28
+ * fileWrite: false,
29
+ * network: false,
30
+ * spawn: false
31
+ * }
32
+ * })
33
+ *
34
+ * await sandbox.start()
35
+ * const result = await sandbox.execute(() => {
36
+ * return 'Hello from sandbox!'
37
+ * })
38
+ *
39
+ * if (result.error) {
40
+ * console.error('Execution failed:', result.error.message)
41
+ * } else {
42
+ * console.log('Result:', result.value)
43
+ * }
44
+ *
45
+ * await sandbox.destroy()
46
+ *
47
+ * @example
48
+ * // Using a sandbox pool for concurrent execution
49
+ * import { createSandboxPool } from './sandbox'
50
+ *
51
+ * const pool = createSandboxPool({ size: 4 })
52
+ * const sandbox = await pool.acquire()
53
+ *
54
+ * try {
55
+ * const result = await sandbox.execute(myFunction)
56
+ * } finally {
57
+ * await pool.release(sandbox)
58
+ * }
59
+ *
60
+ * await pool.shutdown()
12
61
  */
13
62
  import { EventEmitter } from 'events';
14
63
  /**
15
- * Sandbox error codes
64
+ * Sandbox error codes.
65
+ *
66
+ * @description
67
+ * Enumeration of all possible error codes that can be returned by sandbox
68
+ * operations. These codes indicate the specific reason for execution failure.
69
+ *
70
+ * @enum {string}
16
71
  */
17
72
  export var SandboxErrorCode;
18
73
  (function (SandboxErrorCode) {
74
+ /** Execution exceeded the configured timeout */
19
75
  SandboxErrorCode["TIMEOUT"] = "TIMEOUT";
76
+ /** Memory usage exceeded the configured limit */
20
77
  SandboxErrorCode["MEMORY_LIMIT_EXCEEDED"] = "MEMORY_LIMIT_EXCEEDED";
78
+ /** CPU time exceeded the configured limit */
21
79
  SandboxErrorCode["CPU_LIMIT_EXCEEDED"] = "CPU_LIMIT_EXCEEDED";
80
+ /** Operation was denied due to insufficient permissions */
22
81
  SandboxErrorCode["PERMISSION_DENIED"] = "PERMISSION_DENIED";
82
+ /** General execution error occurred */
23
83
  SandboxErrorCode["EXECUTION_ERROR"] = "EXECUTION_ERROR";
84
+ /** Too many file descriptors opened */
24
85
  SandboxErrorCode["FILE_DESCRIPTOR_LIMIT"] = "FILE_DESCRIPTOR_LIMIT";
86
+ /** Too many processes spawned */
25
87
  SandboxErrorCode["PROCESS_LIMIT_EXCEEDED"] = "PROCESS_LIMIT_EXCEEDED";
88
+ /** Network bandwidth limit exceeded */
26
89
  SandboxErrorCode["BANDWIDTH_LIMIT_EXCEEDED"] = "BANDWIDTH_LIMIT_EXCEEDED";
90
+ /** Disk write limit exceeded */
27
91
  SandboxErrorCode["DISK_LIMIT_EXCEEDED"] = "DISK_LIMIT_EXCEEDED";
92
+ /** Sandbox crashed unexpectedly */
28
93
  SandboxErrorCode["SANDBOX_CRASHED"] = "SANDBOX_CRASHED";
94
+ /** Sandbox is paused and not accepting executions */
29
95
  SandboxErrorCode["SANDBOX_PAUSED"] = "SANDBOX_PAUSED";
30
96
  })(SandboxErrorCode || (SandboxErrorCode = {}));
31
97
  /**
32
- * Sandbox error class
98
+ * Sandbox error class.
99
+ *
100
+ * @description
101
+ * Custom error class for sandbox-specific errors. Includes an error code
102
+ * for programmatic handling and optional additional data.
103
+ *
104
+ * @class SandboxError
105
+ * @extends Error
106
+ *
107
+ * @example
108
+ * try {
109
+ * await sandbox.execute(fn)
110
+ * } catch (error) {
111
+ * if (error instanceof SandboxError) {
112
+ * console.log('Error code:', error.code)
113
+ * console.log('Error data:', error.data)
114
+ * }
115
+ * }
33
116
  */
34
117
  export class SandboxError extends Error {
118
+ /** The error code identifying the type of error */
35
119
  code;
120
+ /** Optional additional error data */
36
121
  data;
122
+ /** Stack trace (inherited from Error) */
37
123
  stack;
124
+ /**
125
+ * Create a new sandbox error.
126
+ * @param code - The error code
127
+ * @param message - Human-readable error message
128
+ * @param data - Optional additional error data
129
+ */
38
130
  constructor(code, message, data) {
39
131
  super(message);
40
132
  this.name = 'SandboxError';
41
133
  this.code = code;
42
134
  this.data = data;
43
135
  }
136
+ /**
137
+ * Convert error to JSON representation.
138
+ * @returns JSON-serializable error object
139
+ */
44
140
  toJSON() {
45
141
  const result = {
46
142
  code: this.code,
@@ -53,23 +149,37 @@ export class SandboxError extends Error {
53
149
  }
54
150
  }
55
151
  /**
56
- * Sandbox state enum
152
+ * Sandbox state enum.
153
+ *
154
+ * @description
155
+ * Represents the lifecycle state of a sandbox instance.
156
+ *
157
+ * @enum {string}
57
158
  */
58
159
  export var SandboxState;
59
160
  (function (SandboxState) {
161
+ /** Sandbox is idle and ready for use */
60
162
  SandboxState["IDLE"] = "IDLE";
163
+ /** Sandbox is currently executing code */
61
164
  SandboxState["RUNNING"] = "RUNNING";
165
+ /** Sandbox is paused (can be resumed) */
62
166
  SandboxState["PAUSED"] = "PAUSED";
167
+ /** Sandbox has been destroyed and cannot be reused */
63
168
  SandboxState["DESTROYED"] = "DESTROYED";
64
169
  })(SandboxState || (SandboxState = {}));
65
170
  /**
66
- * Generate unique ID
171
+ * Generate unique ID.
172
+ * @returns Unique sandbox identifier
173
+ * @internal
67
174
  */
68
175
  function generateId() {
69
176
  return `sandbox-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
70
177
  }
71
178
  /**
72
- * Get permission set from preset
179
+ * Get permission set from preset.
180
+ * @param preset - The permission preset to convert
181
+ * @returns Corresponding PermissionSet
182
+ * @internal
73
183
  */
74
184
  function getPermissionsFromPreset(preset) {
75
185
  switch (preset) {
@@ -105,7 +215,8 @@ function getPermissionsFromPreset(preset) {
105
215
  }
106
216
  }
107
217
  /**
108
- * Dangerous modules that require permission checks
218
+ * Dangerous modules that require permission checks.
219
+ * @internal
109
220
  */
110
221
  const DANGEROUS_MODULES = new Set([
111
222
  'fs',
@@ -121,7 +232,8 @@ const DANGEROUS_MODULES = new Set([
121
232
  'worker_threads',
122
233
  ]);
123
234
  /**
124
- * File system read methods
235
+ * File system read methods.
236
+ * @internal
125
237
  */
126
238
  const FS_READ_METHODS = new Set([
127
239
  'readFile',
@@ -143,7 +255,8 @@ const FS_READ_METHODS = new Set([
143
255
  'createReadStream',
144
256
  ]);
145
257
  /**
146
- * File system write methods
258
+ * File system write methods.
259
+ * @internal
147
260
  */
148
261
  const FS_WRITE_METHODS = new Set([
149
262
  'writeFile',
@@ -169,10 +282,43 @@ const FS_WRITE_METHODS = new Set([
169
282
  'chownSync',
170
283
  ]);
171
284
  /**
172
- * MCP Sandbox class for isolated execution
285
+ * MCP Sandbox class for isolated execution.
286
+ *
287
+ * @description
288
+ * Provides an isolated execution environment with resource limits and
289
+ * permission controls. Uses multi-layer security including static analysis,
290
+ * runtime permission checks, and resource limit enforcement.
291
+ *
292
+ * SECURITY: This implementation uses Node.js vm module concepts with proper
293
+ * context isolation and runtime permission checks instead of string analysis.
294
+ *
295
+ * Lifecycle:
296
+ * 1. Create sandbox with createSandbox() or new MCPSandbox()
297
+ * 2. Start the sandbox with start()
298
+ * 3. Execute code with execute()
299
+ * 4. Optionally pause()/resume()
300
+ * 5. Cleanup with cleanup() or destroy()
301
+ *
302
+ * @class MCPSandbox
303
+ * @extends EventEmitter
304
+ *
305
+ * @fires stateChange - When sandbox state changes
306
+ *
307
+ * @example
308
+ * const sandbox = new MCPSandbox({
309
+ * timeout: 5000,
310
+ * permissions: { fileRead: true, fileWrite: false }
311
+ * })
312
+ *
313
+ * await sandbox.start()
173
314
  *
174
- * SECURITY: This implementation uses Node.js vm module with proper context
175
- * isolation and runtime permission checks instead of string analysis.
315
+ * const result = await sandbox.execute(() => {
316
+ * return 'Hello from sandbox!'
317
+ * })
318
+ *
319
+ * console.log(result.value) // 'Hello from sandbox!'
320
+ *
321
+ * await sandbox.destroy()
176
322
  */
177
323
  export class MCPSandbox extends EventEmitter {
178
324
  id;
@@ -189,6 +335,10 @@ export class MCPSandbox extends EventEmitter {
189
335
  executionQueue = [];
190
336
  activeExecutions = 0;
191
337
  globalContext = new Map();
338
+ /**
339
+ * Create a new sandbox instance.
340
+ * @param config - Configuration options
341
+ */
192
342
  constructor(config = {}) {
193
343
  super();
194
344
  this.id = generateId();
@@ -214,21 +364,45 @@ export class MCPSandbox extends EventEmitter {
214
364
  this.permissions = config.permissions ?? {};
215
365
  }
216
366
  }
367
+ /**
368
+ * Get the sandbox ID.
369
+ * @returns Unique sandbox identifier
370
+ */
217
371
  getId() {
218
372
  return this.id;
219
373
  }
374
+ /**
375
+ * Get the sandbox configuration.
376
+ * @returns Copy of the configuration
377
+ */
220
378
  getConfig() {
221
379
  return { ...this.config };
222
380
  }
381
+ /**
382
+ * Get the current sandbox state.
383
+ * @returns Current SandboxState
384
+ */
223
385
  getState() {
224
386
  return this.state;
225
387
  }
388
+ /**
389
+ * Get the current permission set.
390
+ * @returns Copy of permissions
391
+ */
226
392
  getPermissions() {
227
393
  return { ...this.permissions };
228
394
  }
395
+ /**
396
+ * Get resource usage statistics.
397
+ * @returns Copy of resource stats
398
+ */
229
399
  getResourceStats() {
230
400
  return { ...this.resourceStats };
231
401
  }
402
+ /**
403
+ * Get configured resource limits.
404
+ * @returns Copy of resource limits
405
+ */
232
406
  getResourceLimits() {
233
407
  return {
234
408
  memoryLimit: this.config.memoryLimit,
@@ -238,9 +412,22 @@ export class MCPSandbox extends EventEmitter {
238
412
  diskWriteLimit: this.config.diskWriteLimit,
239
413
  };
240
414
  }
415
+ /**
416
+ * Get list of permission violations.
417
+ * @returns Array of recorded violations
418
+ */
241
419
  getPermissionViolations() {
242
420
  return [...this.permissionViolations];
243
421
  }
422
+ /**
423
+ * Start the sandbox.
424
+ *
425
+ * @description
426
+ * Transitions the sandbox to RUNNING state. Must be called before execute().
427
+ *
428
+ * @returns Promise that resolves when started
429
+ * @throws {Error} If sandbox is destroyed or already running
430
+ */
244
431
  async start() {
245
432
  if (this.state === SandboxState.DESTROYED) {
246
433
  throw new Error('Cannot start a destroyed sandbox');
@@ -251,6 +438,15 @@ export class MCPSandbox extends EventEmitter {
251
438
  this.state = SandboxState.RUNNING;
252
439
  this.emit('stateChange', this.state);
253
440
  }
441
+ /**
442
+ * Stop the sandbox.
443
+ *
444
+ * @description
445
+ * Transitions from RUNNING or PAUSED to IDLE state. Clears global context.
446
+ *
447
+ * @returns Promise that resolves when stopped
448
+ * @throws {Error} If sandbox is not running
449
+ */
254
450
  async stop() {
255
451
  if (this.state !== SandboxState.RUNNING && this.state !== SandboxState.PAUSED) {
256
452
  throw new Error('Sandbox is not running');
@@ -259,6 +455,16 @@ export class MCPSandbox extends EventEmitter {
259
455
  this.globalContext.clear();
260
456
  this.emit('stateChange', this.state);
261
457
  }
458
+ /**
459
+ * Pause the sandbox.
460
+ *
461
+ * @description
462
+ * Temporarily pauses execution. New execute() calls will be queued if
463
+ * queueOnPause is enabled, otherwise they return immediately with an error.
464
+ *
465
+ * @returns Promise that resolves when paused
466
+ * @throws {Error} If sandbox is not running
467
+ */
262
468
  async pause() {
263
469
  if (this.state !== SandboxState.RUNNING) {
264
470
  throw new Error('Sandbox is not running');
@@ -266,6 +472,15 @@ export class MCPSandbox extends EventEmitter {
266
472
  this.state = SandboxState.PAUSED;
267
473
  this.emit('stateChange', this.state);
268
474
  }
475
+ /**
476
+ * Resume the sandbox.
477
+ *
478
+ * @description
479
+ * Resumes execution after pause. Processes any queued executions.
480
+ *
481
+ * @returns Promise that resolves when resumed
482
+ * @throws {Error} If sandbox is not paused
483
+ */
269
484
  async resume() {
270
485
  if (this.state !== SandboxState.PAUSED) {
271
486
  throw new Error('Sandbox is not paused');
@@ -280,6 +495,15 @@ export class MCPSandbox extends EventEmitter {
280
495
  }
281
496
  }
282
497
  }
498
+ /**
499
+ * Cleanup sandbox resources.
500
+ *
501
+ * @description
502
+ * Resets resource statistics and clears global context. Sandbox remains
503
+ * usable after cleanup.
504
+ *
505
+ * @returns Promise that resolves when cleanup is complete
506
+ */
283
507
  async cleanup() {
284
508
  this.resourceStats = {
285
509
  memoryUsed: 0,
@@ -289,6 +513,14 @@ export class MCPSandbox extends EventEmitter {
289
513
  };
290
514
  this.globalContext.clear();
291
515
  }
516
+ /**
517
+ * Destroy the sandbox.
518
+ *
519
+ * @description
520
+ * Permanently destroys the sandbox. It cannot be reused after destruction.
521
+ *
522
+ * @returns Promise that resolves when destroyed
523
+ */
292
524
  async destroy() {
293
525
  if (this.state === SandboxState.RUNNING) {
294
526
  await this.stop();
@@ -296,6 +528,30 @@ export class MCPSandbox extends EventEmitter {
296
528
  this.state = SandboxState.DESTROYED;
297
529
  this.emit('stateChange', this.state);
298
530
  }
531
+ /**
532
+ * Execute a function in the sandbox.
533
+ *
534
+ * @description
535
+ * Executes the provided function within the sandbox's isolated environment.
536
+ * The function is subject to configured timeout, resource limits, and
537
+ * permission restrictions.
538
+ *
539
+ * @template T - Return type of the function
540
+ * @param fn - Function to execute (sync or async)
541
+ * @param options - Execution options (timeout, context)
542
+ * @returns Promise resolving to SandboxResult with value or error
543
+ *
544
+ * @example
545
+ * const result = await sandbox.execute<number>(() => {
546
+ * return 42
547
+ * })
548
+ *
549
+ * if (result.error) {
550
+ * console.error('Failed:', result.error.code)
551
+ * } else {
552
+ * console.log('Result:', result.value) // 42
553
+ * }
554
+ */
299
555
  async execute(fn, options = {}) {
300
556
  const startTime = Date.now();
301
557
  const timeout = options.timeout ?? this.config.timeout ?? 30000;
@@ -887,20 +1143,72 @@ export class MCPSandbox extends EventEmitter {
887
1143
  }
888
1144
  }
889
1145
  /**
890
- * Create a new sandbox instance
1146
+ * Create a new sandbox instance.
1147
+ *
1148
+ * @description
1149
+ * Factory function for creating a new MCPSandbox instance.
1150
+ * Equivalent to using `new MCPSandbox(config)`.
1151
+ *
1152
+ * @param config - Sandbox configuration options
1153
+ * @returns A new MCPSandbox instance
1154
+ *
1155
+ * @example
1156
+ * import { createSandbox } from './sandbox'
1157
+ *
1158
+ * const sandbox = createSandbox({
1159
+ * timeout: 5000,
1160
+ * permissions: { fileRead: true, network: false }
1161
+ * })
1162
+ *
1163
+ * await sandbox.start()
1164
+ * const result = await sandbox.execute(() => 'Hello!')
891
1165
  */
892
1166
  export function createSandbox(config = {}) {
893
1167
  return new MCPSandbox(config);
894
1168
  }
895
1169
  /**
896
- * Sandbox pool for managing multiple sandbox instances
1170
+ * Sandbox pool for managing multiple sandbox instances.
1171
+ *
1172
+ * @description
1173
+ * Manages a fixed-size pool of sandbox instances for concurrent execution.
1174
+ * Provides acquire/release semantics with automatic waiting and timeout.
1175
+ *
1176
+ * @class SandboxPool
1177
+ *
1178
+ * @example
1179
+ * const pool = new SandboxPool({
1180
+ * size: 4,
1181
+ * acquireTimeout: 10000,
1182
+ * sandboxConfig: { timeout: 5000 }
1183
+ * })
1184
+ *
1185
+ * // Acquire a sandbox
1186
+ * const sandbox = await pool.acquire()
1187
+ *
1188
+ * try {
1189
+ * const result = await sandbox.execute(() => 'Hello')
1190
+ * } finally {
1191
+ * await pool.release(sandbox)
1192
+ * }
1193
+ *
1194
+ * // Shutdown when done
1195
+ * await pool.shutdown()
897
1196
  */
898
1197
  export class SandboxPool {
1198
+ /** @internal */
899
1199
  sandboxes = [];
1200
+ /** @internal */
900
1201
  availableSandboxes = [];
1202
+ /** @internal */
901
1203
  acquireTimeout;
1204
+ /** @internal */
902
1205
  waiters = [];
1206
+ /** @internal */
903
1207
  isShutdown = false;
1208
+ /**
1209
+ * Create a new sandbox pool.
1210
+ * @param config - Pool configuration
1211
+ */
904
1212
  constructor(config) {
905
1213
  this.acquireTimeout = config.acquireTimeout ?? 30000;
906
1214
  for (let i = 0; i < config.size; i++) {
@@ -909,12 +1217,30 @@ export class SandboxPool {
909
1217
  this.availableSandboxes.push(sandbox);
910
1218
  }
911
1219
  }
1220
+ /**
1221
+ * Get total number of sandboxes in the pool.
1222
+ * @returns Pool size
1223
+ */
912
1224
  size() {
913
1225
  return this.sandboxes.length;
914
1226
  }
1227
+ /**
1228
+ * Get number of available (not in use) sandboxes.
1229
+ * @returns Number of available sandboxes
1230
+ */
915
1231
  available() {
916
1232
  return this.availableSandboxes.length;
917
1233
  }
1234
+ /**
1235
+ * Acquire a sandbox from the pool.
1236
+ *
1237
+ * @description
1238
+ * Returns an available sandbox or waits until one becomes available.
1239
+ * The sandbox is started if in IDLE state.
1240
+ *
1241
+ * @returns Promise resolving to an acquired sandbox
1242
+ * @throws {Error} If pool is shutdown or acquire times out
1243
+ */
918
1244
  async acquire() {
919
1245
  if (this.isShutdown) {
920
1246
  throw new Error('Pool is shutdown');
@@ -944,6 +1270,17 @@ export class SandboxPool {
944
1270
  });
945
1271
  });
946
1272
  }
1273
+ /**
1274
+ * Release a sandbox back to the pool.
1275
+ *
1276
+ * @description
1277
+ * Returns a sandbox to the pool after use. The sandbox is cleaned up
1278
+ * before being made available again. If waiters are present, the sandbox
1279
+ * is given to the next waiter instead of being added to the available pool.
1280
+ *
1281
+ * @param sandbox - The sandbox to release
1282
+ * @returns Promise that resolves when the sandbox is released
1283
+ */
947
1284
  async release(sandbox) {
948
1285
  if (this.isShutdown) {
949
1286
  return;
@@ -957,6 +1294,15 @@ export class SandboxPool {
957
1294
  this.availableSandboxes.push(sandbox);
958
1295
  }
959
1296
  }
1297
+ /**
1298
+ * Shutdown the pool.
1299
+ *
1300
+ * @description
1301
+ * Rejects all pending waiters, destroys all sandboxes, and prevents
1302
+ * further acquire operations. This is a permanent operation.
1303
+ *
1304
+ * @returns Promise that resolves when shutdown is complete
1305
+ */
960
1306
  async shutdown() {
961
1307
  this.isShutdown = true;
962
1308
  // Reject all waiters
@@ -975,7 +1321,28 @@ export class SandboxPool {
975
1321
  }
976
1322
  }
977
1323
  /**
978
- * Create a sandbox pool
1324
+ * Create a sandbox pool.
1325
+ *
1326
+ * @description
1327
+ * Factory function for creating a new SandboxPool instance.
1328
+ * Equivalent to using `new SandboxPool(config)`.
1329
+ *
1330
+ * @param config - Pool configuration
1331
+ * @returns A new SandboxPool instance
1332
+ *
1333
+ * @example
1334
+ * import { createSandboxPool } from './sandbox'
1335
+ *
1336
+ * const pool = createSandboxPool({
1337
+ * size: 4,
1338
+ * sandboxConfig: { timeout: 10000 }
1339
+ * })
1340
+ *
1341
+ * const sandbox = await pool.acquire()
1342
+ * // ... use sandbox ...
1343
+ * await pool.release(sandbox)
1344
+ *
1345
+ * await pool.shutdown()
979
1346
  */
980
1347
  export function createSandboxPool(config) {
981
1348
  return new SandboxPool(config);