@johannes.latzel/llm-chat-shell 0.1.0
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.
- package/LICENSE +7 -0
- package/README.md +43 -0
- package/dist/index.d.ts +9 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +9 -0
- package/dist/index.js.map +1 -0
- package/dist/lib/bash-executor.d.ts +125 -0
- package/dist/lib/bash-executor.d.ts.map +1 -0
- package/dist/lib/bash-executor.js +314 -0
- package/dist/lib/bash-executor.js.map +1 -0
- package/dist/lib/config.d.ts +79 -0
- package/dist/lib/config.d.ts.map +1 -0
- package/dist/lib/config.js +216 -0
- package/dist/lib/config.js.map +1 -0
- package/dist/lib/env.d.ts +34 -0
- package/dist/lib/env.d.ts.map +1 -0
- package/dist/lib/env.js +77 -0
- package/dist/lib/env.js.map +1 -0
- package/dist/lib/job-registry.d.ts +55 -0
- package/dist/lib/job-registry.d.ts.map +1 -0
- package/dist/lib/job-registry.js +116 -0
- package/dist/lib/job-registry.js.map +1 -0
- package/dist/lib/permission.d.ts +101 -0
- package/dist/lib/permission.d.ts.map +1 -0
- package/dist/lib/permission.js +361 -0
- package/dist/lib/permission.js.map +1 -0
- package/dist/lib/session-manager.d.ts +148 -0
- package/dist/lib/session-manager.d.ts.map +1 -0
- package/dist/lib/session-manager.js +264 -0
- package/dist/lib/session-manager.js.map +1 -0
- package/dist/lib/session-queue.d.ts +58 -0
- package/dist/lib/session-queue.d.ts.map +1 -0
- package/dist/lib/session-queue.js +123 -0
- package/dist/lib/session-queue.js.map +1 -0
- package/dist/lib/session-registry.d.ts +140 -0
- package/dist/lib/session-registry.d.ts.map +1 -0
- package/dist/lib/session-registry.js +267 -0
- package/dist/lib/session-registry.js.map +1 -0
- package/dist/lib/types.d.ts +155 -0
- package/dist/lib/types.d.ts.map +1 -0
- package/dist/lib/types.js +37 -0
- package/dist/lib/types.js.map +1 -0
- package/dist/tools/shell-command-tool.d.ts +30 -0
- package/dist/tools/shell-command-tool.d.ts.map +1 -0
- package/dist/tools/shell-command-tool.js +138 -0
- package/dist/tools/shell-command-tool.js.map +1 -0
- package/dist/tools/shell-create-tool.d.ts +12 -0
- package/dist/tools/shell-create-tool.d.ts.map +1 -0
- package/dist/tools/shell-create-tool.js +24 -0
- package/dist/tools/shell-create-tool.js.map +1 -0
- package/dist/tools/shell-job-status-tool.d.ts +13 -0
- package/dist/tools/shell-job-status-tool.d.ts.map +1 -0
- package/dist/tools/shell-job-status-tool.js +59 -0
- package/dist/tools/shell-job-status-tool.js.map +1 -0
- package/dist/tools/shell-jobs-tool.d.ts +12 -0
- package/dist/tools/shell-jobs-tool.d.ts.map +1 -0
- package/dist/tools/shell-jobs-tool.js +28 -0
- package/dist/tools/shell-jobs-tool.js.map +1 -0
- package/dist/tools/shell-package.d.ts +54 -0
- package/dist/tools/shell-package.d.ts.map +1 -0
- package/dist/tools/shell-package.js +77 -0
- package/dist/tools/shell-package.js.map +1 -0
- package/dist/tools/shell-permissions-tool.d.ts +15 -0
- package/dist/tools/shell-permissions-tool.d.ts.map +1 -0
- package/dist/tools/shell-permissions-tool.js +38 -0
- package/dist/tools/shell-permissions-tool.js.map +1 -0
- package/package.json +87 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
Copyright (c) 2026 Johannes B. Latzel
|
|
2
|
+
|
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
4
|
+
|
|
5
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
6
|
+
|
|
7
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# LLM Chat Shell
|
|
2
|
+
|
|
3
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
|
+
[](https://www.npmjs.com/package/@johannes.latzel/llm-chat-shell)
|
|
5
|
+
[](https://github.com/johanneslatzel/llm-chat-shell/releases)
|
|
6
|
+
[](https://www.typescriptlang.org/)
|
|
7
|
+
[](https://github.com/johanneslatzel/llm-chat-shell/pulls)
|
|
8
|
+
[](https://github.com/johanneslatzel/llm-chat-shell/discussions)
|
|
9
|
+
[](https://codecov.io/gh/johanneslatzel/llm-chat-shell)
|
|
10
|
+
[](https://github.com/johanneslatzel/llm-chat-shell/actions/workflows/ci.yml)
|
|
11
|
+
[](https://badge.socket.dev/npm/package/@johannes.latzel/llm-chat-shell/latest)
|
|
12
|
+
[](https://github.com/mefengl/made-by-ai)
|
|
13
|
+
|
|
14
|
+
A tightly controlled shell tool for LLM chat, with a per-workspace permission system similar to opencode's bash tool permissions. Supports shell compositions including pipes (`|`), logical operators (`||`, `&&`), and stream redirects. Built on the shared [`@johannes.latzel/llm-chat-workspace`](https://johanneslatzel.github.io/llm-chat-workspace/) package for workspace access and switching.
|
|
15
|
+
|
|
16
|
+
## Features
|
|
17
|
+
|
|
18
|
+
- Shell sessions
|
|
19
|
+
- Background jobs
|
|
20
|
+
- Per-workspace allow/deny permission rules with global fallback supporting pipes, redirects, and logical operators, plus a read/write access tier so write-classified rules only run in writable workspaces
|
|
21
|
+
- Three-phase command timeout escalation: Ctrl+C → SIGTERM → SIGKILL
|
|
22
|
+
|
|
23
|
+
## Prerequisites
|
|
24
|
+
|
|
25
|
+
- Node.js >= 18
|
|
26
|
+
|
|
27
|
+
## Installation
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm install @johannes.latzel/llm-chat-shell
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Documentation
|
|
34
|
+
|
|
35
|
+
Full documentation at **[johanneslatzel.github.io/llm-chat-shell/](https://johanneslatzel.github.io/llm-chat-shell/)**
|
|
36
|
+
|
|
37
|
+
## License
|
|
38
|
+
|
|
39
|
+
MIT. See [`LICENSE`](LICENSE).
|
|
40
|
+
|
|
41
|
+
## Contributing
|
|
42
|
+
|
|
43
|
+
Issues and PRs welcome at [github.com/johanneslatzel/llm-chat-shell](https://github.com/johanneslatzel/llm-chat-shell).
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
export { PermissionAction, PermissionAccess, PermissionDenyReason, type PermissionRule, type WorkspacePermissions, type ShellConfigFile, type ShellExecutor, type ShellCommandResult, type ShellExecuteOptions, ShellJobStatus, type ShellJob, type ShellSessionInfo } from './lib/types.js';
|
|
2
|
+
export { ShellConfiguration } from './lib/config.js';
|
|
3
|
+
export { BashShellExecutor, BashShellExecutorFactory } from './lib/bash-executor.js';
|
|
4
|
+
export { ShellSessionManager, type ShellExecutorFactory } from './lib/session-manager.js';
|
|
5
|
+
export { ShellPermissionsTool } from './tools/shell-permissions-tool.js';
|
|
6
|
+
export { ShellJobStatusTool } from './tools/shell-job-status-tool.js';
|
|
7
|
+
export { ShellJobsTool } from './tools/shell-jobs-tool.js';
|
|
8
|
+
export { ShellPackage } from './tools/shell-package.js';
|
|
9
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,cAAc,EACd,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
export { PermissionAction, PermissionAccess, PermissionDenyReason, ShellJobStatus } from './lib/types.js';
|
|
2
|
+
export { ShellConfiguration } from './lib/config.js';
|
|
3
|
+
export { BashShellExecutor, BashShellExecutorFactory } from './lib/bash-executor.js';
|
|
4
|
+
export { ShellSessionManager } from './lib/session-manager.js';
|
|
5
|
+
export { ShellPermissionsTool } from './tools/shell-permissions-tool.js';
|
|
6
|
+
export { ShellJobStatusTool } from './tools/shell-job-status-tool.js';
|
|
7
|
+
export { ShellJobsTool } from './tools/shell-jobs-tool.js';
|
|
8
|
+
export { ShellPackage } from './tools/shell-package.js';
|
|
9
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EAOpB,cAAc,EAGjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAA6B,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC"}
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
import { type ChildProcess } from 'node:child_process';
|
|
2
|
+
import type { ShellExecutor, ShellCommandResult, ShellExecuteOptions } from './types.js';
|
|
3
|
+
import type { ShellExecutorFactory } from './session-manager.js';
|
|
4
|
+
/** Minimal process-level config consumed by the bash executor (cwd and timeouts). */
|
|
5
|
+
export interface BashProcessConfig {
|
|
6
|
+
/** Working directory the bash process starts in. Defaults to the process cwd. */
|
|
7
|
+
cwd?: string;
|
|
8
|
+
/** Ms of inactivity (no stdout/stderr output) before Ctrl+C is sent to a command (idle window). */
|
|
9
|
+
ctrlCTimeout: number;
|
|
10
|
+
/** Ms to wait after SIGTERM before escalating to SIGKILL. */
|
|
11
|
+
sigtermTimeout: number;
|
|
12
|
+
/** Ms to wait after SIGKILL before giving up. */
|
|
13
|
+
killTimeout: number;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Three-phase timeout escalation: Ctrl+C → SIGTERM → SIGKILL.
|
|
17
|
+
*
|
|
18
|
+
* The first phase is an **idle** window: the Ctrl+C timer resets on every
|
|
19
|
+
* stdout/stderr activity, so a command that keeps producing output never
|
|
20
|
+
* times out. Once the window expires the phase chain commits and is no
|
|
21
|
+
* longer resettable.
|
|
22
|
+
*/
|
|
23
|
+
export declare class TimeoutEscalation {
|
|
24
|
+
private readonly proc;
|
|
25
|
+
private readonly config;
|
|
26
|
+
private readonly state;
|
|
27
|
+
private _timedOut;
|
|
28
|
+
private _sessionAlive;
|
|
29
|
+
private idleTimer;
|
|
30
|
+
private resolveCurrent;
|
|
31
|
+
get timedOut(): boolean;
|
|
32
|
+
get sessionAlive(): boolean;
|
|
33
|
+
constructor(proc: ChildProcess, config: BashProcessConfig, state: {
|
|
34
|
+
timeoutStarted: boolean;
|
|
35
|
+
killPhase: boolean;
|
|
36
|
+
});
|
|
37
|
+
/** Start the idle-window countdown. Resolves with -1 after all phases complete. */
|
|
38
|
+
start(): Promise<number>;
|
|
39
|
+
/**
|
|
40
|
+
* Report command activity (stdout/stderr output). Resets the idle window
|
|
41
|
+
* as long as escalation has not committed. No-op once Ctrl+C was sent.
|
|
42
|
+
*/
|
|
43
|
+
activity(): void;
|
|
44
|
+
/** Clear a still-pending idle window (command completed before it expired). */
|
|
45
|
+
dispose(): void;
|
|
46
|
+
/**
|
|
47
|
+
* Handle expiry of the idle window: escalate unless the pending command is
|
|
48
|
+
* already gone. Called by the idle timer; safe to invoke after dispose.
|
|
49
|
+
*/
|
|
50
|
+
handleIdleExpiry(): void;
|
|
51
|
+
private armIdleTimer;
|
|
52
|
+
private phaseCtrlC;
|
|
53
|
+
private phaseSigterm;
|
|
54
|
+
private phaseSigkill;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Implementation of {@link ShellExecutor} that spawns a single persistent
|
|
58
|
+
* bash process and communicates via stdin/stdout with sentinel markers.
|
|
59
|
+
* One instance = one session.
|
|
60
|
+
*/
|
|
61
|
+
export declare class BashShellExecutor implements ShellExecutor {
|
|
62
|
+
private readonly config;
|
|
63
|
+
private proc;
|
|
64
|
+
private readline;
|
|
65
|
+
private stderrBuffer;
|
|
66
|
+
private processExitCode;
|
|
67
|
+
private sentinel;
|
|
68
|
+
private closed;
|
|
69
|
+
private readonly timeoutState;
|
|
70
|
+
/**
|
|
71
|
+
* @param config - Bash process configuration (cwd, timeouts).
|
|
72
|
+
*/
|
|
73
|
+
constructor(config: BashProcessConfig);
|
|
74
|
+
/**
|
|
75
|
+
* Execute a command in the persistent bash session.
|
|
76
|
+
*
|
|
77
|
+
* Uses a **sentinel protocol** to detect command completion and capture the exit code.
|
|
78
|
+
* The problem: bash stdout is a raw byte stream with no "end of output" marker,
|
|
79
|
+
* and the exit code (`$?`) only exists inside bash's memory. The sentinel solves both:
|
|
80
|
+
*
|
|
81
|
+
* 1. Node.js generates a unique sentinel string with a UUID and literal `$?`
|
|
82
|
+
* 2. Node.js writes to bash stdin: the command, then `echo "<sentinel>"`
|
|
83
|
+
* 3. Bash executes both: runs the command, then echoes the sentinel with `$?` expanded
|
|
84
|
+
* 4. Node.js listener parses stdout, matches the sentinel by UUID, extracts exit code
|
|
85
|
+
*
|
|
86
|
+
* Example flow for `execute('ls -lah')`:
|
|
87
|
+
* ```
|
|
88
|
+
* Node.js stdin → ls -lah
|
|
89
|
+
* Node.js stdin → echo "__SHELL_SENTINEL_a1b2c3_-_$?__"
|
|
90
|
+
*
|
|
91
|
+
* Bash stdout → file1.txt
|
|
92
|
+
* Bash stdout → dir1/
|
|
93
|
+
* Bash stdout → __SHELL_SENTINEL_a1b2c3_-0__ ← $? expanded to 0
|
|
94
|
+
* ```
|
|
95
|
+
*/
|
|
96
|
+
execute(command: string, options?: ShellExecuteOptions): Promise<ShellCommandResult>;
|
|
97
|
+
/** @inheritdoc */
|
|
98
|
+
close(): Promise<void>;
|
|
99
|
+
/** @inheritdoc */
|
|
100
|
+
isAlive(): boolean;
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Factory for creating {@link BashShellExecutor} instances.
|
|
104
|
+
* Merges an optional per-session `cwd` with a shared process-level configuration.
|
|
105
|
+
*
|
|
106
|
+
* @example
|
|
107
|
+
* ```typescript
|
|
108
|
+
* const factory = new BashShellExecutorFactory(config);
|
|
109
|
+
* const executor = await factory.create('/tmp'); // cwd override
|
|
110
|
+
* const executor = await factory.create(); // uses config.cwd or process cwd
|
|
111
|
+
* ```
|
|
112
|
+
*/
|
|
113
|
+
export declare class BashShellExecutorFactory implements ShellExecutorFactory {
|
|
114
|
+
private readonly config;
|
|
115
|
+
/**
|
|
116
|
+
* @param config - Base bash process configuration shared across all sessions.
|
|
117
|
+
*/
|
|
118
|
+
constructor(config: BashProcessConfig);
|
|
119
|
+
/**
|
|
120
|
+
* Create a new bash shell executor.
|
|
121
|
+
* @param cwd - Optional working directory for this session, overriding `config.cwd`.
|
|
122
|
+
*/
|
|
123
|
+
create(cwd?: string): Promise<ShellExecutor>;
|
|
124
|
+
}
|
|
125
|
+
//# sourceMappingURL=bash-executor.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bash-executor.d.ts","sourceRoot":"","sources":["../../src/lib/bash-executor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG9D,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAC9B,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mGAAmG;IACnG,YAAY,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;CACvB;AAqED;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAetB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAhB1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,cAAc,CAAyC;IAE/D,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,YAAY,IAAI,OAAO,CAE1B;gBAGoB,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE;QAAE,cAAc,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE;IAG3E,mFAAmF;IACnF,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAOxB;;;OAGG;IACH,QAAQ,IAAI,IAAI;IAUhB,+EAA+E;IAC/E,OAAO,IAAI,IAAI;IAQf;;;OAGG;IACH,gBAAgB,IAAI,IAAI;IAQxB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,YAAY;CAOvB;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IAYvC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAXnC,OAAO,CAAC,IAAI,CAAe;IAC3B,OAAO,CAAC,QAAQ,CAAY;IAC5B,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA+C;IAE5E;;OAEG;gBAC0B,MAAM,EAAE,iBAAiB;IAwBtD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA+E1F,kBAAkB;IACZ,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B,kBAAkB;IAClB,OAAO,IAAI,OAAO;CAGrB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,wBAAyB,YAAW,oBAAoB;IAIrD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC;;OAEG;gBAC0B,MAAM,EAAE,iBAAiB;IAEtD;;;OAGG;IACG,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;CAGrD"}
|
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
import { spawn } from 'node:child_process';
|
|
2
|
+
import { randomUUID } from 'node:crypto';
|
|
3
|
+
import { createInterface } from 'node:readline';
|
|
4
|
+
/** UUID v4 source pattern (no anchors) for matching sentinels. */
|
|
5
|
+
const UUID_V4_SOURCE = '[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}';
|
|
6
|
+
/** Single-quote a shell path so it can be safely embedded in a command. */
|
|
7
|
+
function shellQuoteSingle(value) {
|
|
8
|
+
return `'${value.replace(/'/g, `'\\''`)}'`;
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* Sentinel protocol for detecting command completion and capturing exit codes.
|
|
12
|
+
* Generates a unique sentinel, listens for it in stdout, and resolves with the exit code.
|
|
13
|
+
*/
|
|
14
|
+
class SentinelProtocol {
|
|
15
|
+
_resolve = null;
|
|
16
|
+
_uuid = randomUUID();
|
|
17
|
+
_sentinel = `__SHELL_SENTINEL_${this._uuid}_$?__`;
|
|
18
|
+
get sentinel() {
|
|
19
|
+
return this._sentinel;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Start listening for the sentinel in readline output.
|
|
23
|
+
* @param readline - The readline interface to listen on
|
|
24
|
+
* @param outputLines - Array to collect non-sentinel output lines
|
|
25
|
+
* @param timeoutStarted - Function that returns true if timeout escalation is in progress
|
|
26
|
+
* @returns Promise that resolves with the exit code when sentinel is found
|
|
27
|
+
*/
|
|
28
|
+
start(readline, outputLines, timeoutStarted) {
|
|
29
|
+
const onData = (line) => {
|
|
30
|
+
const match = line.match(new RegExp(`^__SHELL_SENTINEL_(${UUID_V4_SOURCE})_(\\d+)__$`));
|
|
31
|
+
if (match !== null && match[1] === this._uuid) {
|
|
32
|
+
// Found our sentinel — command is done. Extract exit code and resolve,
|
|
33
|
+
// but only if no timeout is in progress (timeoutPromise takes precedence).
|
|
34
|
+
if (!timeoutStarted()) {
|
|
35
|
+
const exitCode = parseInt(match[2], 10);
|
|
36
|
+
readline.removeListener('line', onData);
|
|
37
|
+
this._resolve(exitCode);
|
|
38
|
+
this._resolve = null;
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
else {
|
|
42
|
+
// Regular output line — collect it.
|
|
43
|
+
outputLines.push(line);
|
|
44
|
+
}
|
|
45
|
+
};
|
|
46
|
+
readline.on('line', onData);
|
|
47
|
+
return new Promise((resolve) => {
|
|
48
|
+
this._resolve = resolve;
|
|
49
|
+
});
|
|
50
|
+
}
|
|
51
|
+
/** Resolve from exit handler (when process dies before sentinel arrives). */
|
|
52
|
+
resolve(exitCode) {
|
|
53
|
+
if (this._resolve !== null) {
|
|
54
|
+
const resolve = this._resolve;
|
|
55
|
+
this._resolve = null;
|
|
56
|
+
resolve(exitCode);
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Three-phase timeout escalation: Ctrl+C → SIGTERM → SIGKILL.
|
|
62
|
+
*
|
|
63
|
+
* The first phase is an **idle** window: the Ctrl+C timer resets on every
|
|
64
|
+
* stdout/stderr activity, so a command that keeps producing output never
|
|
65
|
+
* times out. Once the window expires the phase chain commits and is no
|
|
66
|
+
* longer resettable.
|
|
67
|
+
*/
|
|
68
|
+
export class TimeoutEscalation {
|
|
69
|
+
proc;
|
|
70
|
+
config;
|
|
71
|
+
state;
|
|
72
|
+
_timedOut = false;
|
|
73
|
+
_sessionAlive = true;
|
|
74
|
+
idleTimer = null;
|
|
75
|
+
resolveCurrent = null;
|
|
76
|
+
get timedOut() {
|
|
77
|
+
return this._timedOut;
|
|
78
|
+
}
|
|
79
|
+
get sessionAlive() {
|
|
80
|
+
return this._sessionAlive;
|
|
81
|
+
}
|
|
82
|
+
constructor(proc, config, state) {
|
|
83
|
+
this.proc = proc;
|
|
84
|
+
this.config = config;
|
|
85
|
+
this.state = state;
|
|
86
|
+
}
|
|
87
|
+
/** Start the idle-window countdown. Resolves with -1 after all phases complete. */
|
|
88
|
+
start() {
|
|
89
|
+
return new Promise((resolve) => {
|
|
90
|
+
this.resolveCurrent = resolve;
|
|
91
|
+
this.armIdleTimer();
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* Report command activity (stdout/stderr output). Resets the idle window
|
|
96
|
+
* as long as escalation has not committed. No-op once Ctrl+C was sent.
|
|
97
|
+
*/
|
|
98
|
+
activity() {
|
|
99
|
+
if (this.state.timeoutStarted) {
|
|
100
|
+
return;
|
|
101
|
+
}
|
|
102
|
+
if (this.idleTimer !== null) {
|
|
103
|
+
clearTimeout(this.idleTimer);
|
|
104
|
+
this.armIdleTimer();
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
/** Clear a still-pending idle window (command completed before it expired). */
|
|
108
|
+
dispose() {
|
|
109
|
+
if (this.idleTimer !== null) {
|
|
110
|
+
clearTimeout(this.idleTimer);
|
|
111
|
+
this.idleTimer = null;
|
|
112
|
+
}
|
|
113
|
+
this.resolveCurrent = null;
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Handle expiry of the idle window: escalate unless the pending command is
|
|
117
|
+
* already gone. Called by the idle timer; safe to invoke after dispose.
|
|
118
|
+
*/
|
|
119
|
+
handleIdleExpiry() {
|
|
120
|
+
this.idleTimer = null;
|
|
121
|
+
const resolve = this.resolveCurrent;
|
|
122
|
+
if (resolve !== null) {
|
|
123
|
+
this.phaseCtrlC(resolve);
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
armIdleTimer() {
|
|
127
|
+
this.idleTimer = setTimeout(() => this.handleIdleExpiry(), this.config.ctrlCTimeout);
|
|
128
|
+
}
|
|
129
|
+
phaseCtrlC(resolve) {
|
|
130
|
+
this.state.timeoutStarted = true;
|
|
131
|
+
this.proc.stdin.write('\x03');
|
|
132
|
+
setTimeout(() => this.phaseSigterm(resolve), this.config.sigtermTimeout);
|
|
133
|
+
}
|
|
134
|
+
phaseSigterm(resolve) {
|
|
135
|
+
this.proc.kill('SIGTERM');
|
|
136
|
+
setTimeout(() => this.phaseSigkill(resolve), this.config.killTimeout);
|
|
137
|
+
}
|
|
138
|
+
phaseSigkill(resolve) {
|
|
139
|
+
this.state.killPhase = true;
|
|
140
|
+
this.proc.kill('SIGKILL');
|
|
141
|
+
this._sessionAlive = false;
|
|
142
|
+
this._timedOut = true;
|
|
143
|
+
resolve(-1);
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* Implementation of {@link ShellExecutor} that spawns a single persistent
|
|
148
|
+
* bash process and communicates via stdin/stdout with sentinel markers.
|
|
149
|
+
* One instance = one session.
|
|
150
|
+
*/
|
|
151
|
+
export class BashShellExecutor {
|
|
152
|
+
config;
|
|
153
|
+
proc;
|
|
154
|
+
readline;
|
|
155
|
+
stderrBuffer = '';
|
|
156
|
+
processExitCode = null;
|
|
157
|
+
sentinel = null;
|
|
158
|
+
closed = false;
|
|
159
|
+
timeoutState = { killPhase: false, timeoutStarted: false };
|
|
160
|
+
/**
|
|
161
|
+
* @param config - Bash process configuration (cwd, timeouts).
|
|
162
|
+
*/
|
|
163
|
+
constructor(config) {
|
|
164
|
+
this.config = config;
|
|
165
|
+
this.proc = spawn('bash', ['--norc', '--noprofile'], {
|
|
166
|
+
stdio: ['pipe', 'pipe', 'pipe'],
|
|
167
|
+
cwd: this.config.cwd
|
|
168
|
+
});
|
|
169
|
+
this.readline = createInterface({ input: this.proc.stdout });
|
|
170
|
+
this.proc.stderr.on('data', (data) => {
|
|
171
|
+
this.stderrBuffer += data.toString();
|
|
172
|
+
});
|
|
173
|
+
this.proc.on('exit', (code) => {
|
|
174
|
+
this.processExitCode = code ?? 1;
|
|
175
|
+
if (this.timeoutState.killPhase || this.timeoutState.timeoutStarted) {
|
|
176
|
+
// Don't resolve from exit handler during timeout escalation —
|
|
177
|
+
// TimeoutEscalation will resolve.
|
|
178
|
+
return;
|
|
179
|
+
}
|
|
180
|
+
// Resolve sentinel if process dies before sentinel arrives.
|
|
181
|
+
this.sentinel?.resolve(this.processExitCode);
|
|
182
|
+
});
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
185
|
+
* Execute a command in the persistent bash session.
|
|
186
|
+
*
|
|
187
|
+
* Uses a **sentinel protocol** to detect command completion and capture the exit code.
|
|
188
|
+
* The problem: bash stdout is a raw byte stream with no "end of output" marker,
|
|
189
|
+
* and the exit code (`$?`) only exists inside bash's memory. The sentinel solves both:
|
|
190
|
+
*
|
|
191
|
+
* 1. Node.js generates a unique sentinel string with a UUID and literal `$?`
|
|
192
|
+
* 2. Node.js writes to bash stdin: the command, then `echo "<sentinel>"`
|
|
193
|
+
* 3. Bash executes both: runs the command, then echoes the sentinel with `$?` expanded
|
|
194
|
+
* 4. Node.js listener parses stdout, matches the sentinel by UUID, extracts exit code
|
|
195
|
+
*
|
|
196
|
+
* Example flow for `execute('ls -lah')`:
|
|
197
|
+
* ```
|
|
198
|
+
* Node.js stdin → ls -lah
|
|
199
|
+
* Node.js stdin → echo "__SHELL_SENTINEL_a1b2c3_-_$?__"
|
|
200
|
+
*
|
|
201
|
+
* Bash stdout → file1.txt
|
|
202
|
+
* Bash stdout → dir1/
|
|
203
|
+
* Bash stdout → __SHELL_SENTINEL_a1b2c3_-0__ ← $? expanded to 0
|
|
204
|
+
* ```
|
|
205
|
+
*/
|
|
206
|
+
async execute(command, options) {
|
|
207
|
+
this.stderrBuffer = '';
|
|
208
|
+
this.timeoutState.killPhase = false;
|
|
209
|
+
this.timeoutState.timeoutStarted = false;
|
|
210
|
+
// The idle limit for this execution: a positive explicit option wins,
|
|
211
|
+
// otherwise the configured ctrlCTimeout applies.
|
|
212
|
+
const requestedTimeout = options?.idleTimeoutMs;
|
|
213
|
+
const idleTimeoutMs = requestedTimeout !== undefined && requestedTimeout > 0
|
|
214
|
+
? requestedTimeout
|
|
215
|
+
: this.config.ctrlCTimeout;
|
|
216
|
+
// Step 1: Set up sentinel protocol for command completion detection.
|
|
217
|
+
this.sentinel = new SentinelProtocol();
|
|
218
|
+
const outputLines = [];
|
|
219
|
+
const sentinelPromise = this.sentinel.start(this.readline, outputLines, () => this.timeoutState.timeoutStarted);
|
|
220
|
+
// Step 2: Send command to bash, then send echo with sentinel.
|
|
221
|
+
// When a cwd is given, re-anchor the persistent shell into it first, so
|
|
222
|
+
// the command runs in the directory its job was submitted for.
|
|
223
|
+
const commandToRun = options?.cwd !== undefined
|
|
224
|
+
? `cd ${shellQuoteSingle(options.cwd)} && ${command}`
|
|
225
|
+
: command;
|
|
226
|
+
// Bash will execute them sequentially: run the command, then echo the sentinel.
|
|
227
|
+
// When bash echoes it, `$?` is expanded to the command's exit code.
|
|
228
|
+
this.proc.stdin.write(`${commandToRun}\n`);
|
|
229
|
+
this.proc.stdin.write(`echo "${this.sentinel.sentinel}"\n`);
|
|
230
|
+
// Step 3: Idle-based timeout escalation (Ctrl+C → SIGTERM → SIGKILL).
|
|
231
|
+
// The countdown resets on any stdout/stderr output; only silence triggers it.
|
|
232
|
+
const escalation = new TimeoutEscalation(this.proc, { ...this.config, ctrlCTimeout: idleTimeoutMs }, this.timeoutState);
|
|
233
|
+
const onLine = () => escalation.activity();
|
|
234
|
+
const onStderrData = () => escalation.activity();
|
|
235
|
+
this.readline.on('line', onLine);
|
|
236
|
+
this.proc.stderr.on('data', onStderrData);
|
|
237
|
+
const timeoutPromise = escalation.start();
|
|
238
|
+
let exitCode;
|
|
239
|
+
try {
|
|
240
|
+
exitCode = await Promise.race([sentinelPromise, timeoutPromise]);
|
|
241
|
+
// Give the event loop a chance to deliver any pending stderr data before
|
|
242
|
+
// reading it, so the captured stderr is not truncated by the async read.
|
|
243
|
+
await new Promise((resolve) => setImmediate(resolve));
|
|
244
|
+
}
|
|
245
|
+
finally {
|
|
246
|
+
this.readline.removeListener('line', onLine);
|
|
247
|
+
this.proc.stderr.removeListener('data', onStderrData);
|
|
248
|
+
escalation.dispose();
|
|
249
|
+
}
|
|
250
|
+
// Step 4: Return collected output. The sentinel line was never added to
|
|
251
|
+
// outputLines (it was caught by the if-branch), so it's excluded from output.
|
|
252
|
+
const stdout = outputLines.join('\n').trimEnd();
|
|
253
|
+
const stderr = this.stderrBuffer.trimEnd();
|
|
254
|
+
const result = {
|
|
255
|
+
stdout,
|
|
256
|
+
stderr,
|
|
257
|
+
exitCode: escalation.timedOut ? -1 : exitCode,
|
|
258
|
+
timedOut: escalation.timedOut,
|
|
259
|
+
sessionAlive: escalation.sessionAlive
|
|
260
|
+
};
|
|
261
|
+
if (escalation.timedOut) {
|
|
262
|
+
result.idleTimeoutMs = idleTimeoutMs;
|
|
263
|
+
}
|
|
264
|
+
return result;
|
|
265
|
+
}
|
|
266
|
+
/** @inheritdoc */
|
|
267
|
+
async close() {
|
|
268
|
+
if (this.closed) {
|
|
269
|
+
return;
|
|
270
|
+
}
|
|
271
|
+
this.closed = true;
|
|
272
|
+
this.readline.close();
|
|
273
|
+
if (this.proc.exitCode !== null) {
|
|
274
|
+
return;
|
|
275
|
+
}
|
|
276
|
+
if (this.proc.stdin && !this.proc.stdin.destroyed) {
|
|
277
|
+
this.proc.stdin.on('error', () => { });
|
|
278
|
+
this.proc.stdin.write('exit\n');
|
|
279
|
+
}
|
|
280
|
+
this.proc.kill('SIGTERM');
|
|
281
|
+
}
|
|
282
|
+
/** @inheritdoc */
|
|
283
|
+
isAlive() {
|
|
284
|
+
return !this.timeoutState.killPhase && this.proc.exitCode === null;
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
/**
|
|
288
|
+
* Factory for creating {@link BashShellExecutor} instances.
|
|
289
|
+
* Merges an optional per-session `cwd` with a shared process-level configuration.
|
|
290
|
+
*
|
|
291
|
+
* @example
|
|
292
|
+
* ```typescript
|
|
293
|
+
* const factory = new BashShellExecutorFactory(config);
|
|
294
|
+
* const executor = await factory.create('/tmp'); // cwd override
|
|
295
|
+
* const executor = await factory.create(); // uses config.cwd or process cwd
|
|
296
|
+
* ```
|
|
297
|
+
*/
|
|
298
|
+
export class BashShellExecutorFactory {
|
|
299
|
+
config;
|
|
300
|
+
/**
|
|
301
|
+
* @param config - Base bash process configuration shared across all sessions.
|
|
302
|
+
*/
|
|
303
|
+
constructor(config) {
|
|
304
|
+
this.config = config;
|
|
305
|
+
}
|
|
306
|
+
/**
|
|
307
|
+
* Create a new bash shell executor.
|
|
308
|
+
* @param cwd - Optional working directory for this session, overriding `config.cwd`.
|
|
309
|
+
*/
|
|
310
|
+
async create(cwd) {
|
|
311
|
+
return new BashShellExecutor(cwd ? { ...this.config, cwd } : this.config);
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
//# sourceMappingURL=bash-executor.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bash-executor.js","sourceRoot":"","sources":["../../src/lib/bash-executor.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import { PermissionAction, type PermissionRule, type ShellConfigFile, type WorkspacePermissions } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* Load and validate a shell permission config file (strict JSON).
|
|
4
|
+
*
|
|
5
|
+
* The file may contain `globalPermissions` and `workspacePermissions`. Any
|
|
6
|
+
* structural or type error throws, so a typo'd or malformed file never
|
|
7
|
+
* silently falls back to permissive defaults.
|
|
8
|
+
*
|
|
9
|
+
* @param configFilePath - Path to the JSON config file (resolved against the cwd).
|
|
10
|
+
* @returns The parsed config file contents.
|
|
11
|
+
* @throws When the file cannot be read, is not valid JSON, or has an invalid shape.
|
|
12
|
+
*/
|
|
13
|
+
export declare function loadShellConfigFile(configFilePath: string): ShellConfigFile;
|
|
14
|
+
/** Configuration for {@link ShellPackage}. Reads timeouts and sessions from env vars; permission settings load from a config file (env: LLM_CHAT_SHELL_CONFIG). */
|
|
15
|
+
export declare class ShellConfiguration {
|
|
16
|
+
/** Path to the permission config file (env: LLM_CHAT_SHELL_CONFIG). */
|
|
17
|
+
readonly configFilePath: string | undefined;
|
|
18
|
+
/** Parsed contents of the config file ({} when no file is configured). */
|
|
19
|
+
private readonly configFile;
|
|
20
|
+
/** Ms to wait after Ctrl+C before escalating to SIGTERM (env: LLM_CHAT_SHELL_CTRL_C_TIMEOUT, default: 30000). */
|
|
21
|
+
ctrlCTimeout: number;
|
|
22
|
+
/** Ms to wait after SIGTERM before escalating to SIGKILL (env: LLM_CHAT_SHELL_SIGTERM_TIMEOUT, default: 5000). */
|
|
23
|
+
sigtermTimeout: number;
|
|
24
|
+
/** Ms to wait after SIGKILL before giving up (env: LLM_CHAT_SHELL_KILL_TIMEOUT, default: 5000). */
|
|
25
|
+
killTimeout: number;
|
|
26
|
+
/**
|
|
27
|
+
* Max concurrent sessions (env: LLM_CHAT_SHELL_MAX_SESSIONS, default: 10).
|
|
28
|
+
*/
|
|
29
|
+
maxSessions: number;
|
|
30
|
+
/** Session idle timeout in ms (env: LLM_CHAT_SHELL_SESSION_TIMEOUT, default: 3600000 = 1h). */
|
|
31
|
+
sessionTimeout: number;
|
|
32
|
+
/**
|
|
33
|
+
* Idle timeout in ms for background jobs that do not specify a `timeout`
|
|
34
|
+
* (env: LLM_CHAT_SHELL_BACKGROUND_TIMEOUT, default: 3600000 = 1h).
|
|
35
|
+
* Background commands only need to stay "chatty" for this long, so
|
|
36
|
+
* long-running silent jobs are not killed by the short foreground
|
|
37
|
+
* {@link ctrlCTimeout}.
|
|
38
|
+
*/
|
|
39
|
+
backgroundTimeout: number;
|
|
40
|
+
/**
|
|
41
|
+
* Upper bound in ms for LLM-supplied `timeout` values on the shell command
|
|
42
|
+
* tool (env: LLM_CHAT_SHELL_MAX_TIMEOUT, default: 3600000 = 1h). Larger
|
|
43
|
+
* requested timeouts are capped to this value. `0` disables the cap.
|
|
44
|
+
*/
|
|
45
|
+
maxTimeout: number;
|
|
46
|
+
/** Default permission for unmatched commands (config file: `globalPermissions.defaultPermission`, default: Deny). */
|
|
47
|
+
defaultPermission: PermissionAction;
|
|
48
|
+
/** Global permission rules (config file: `globalPermissions.permissionRules`). */
|
|
49
|
+
permissionRules: PermissionRule[];
|
|
50
|
+
/**
|
|
51
|
+
* Per-workspace permission settings keyed by resolved workspace root path
|
|
52
|
+
* (config file: `workspacePermissions` — an object mapping each workspace
|
|
53
|
+
* root to `{ defaultPermission, permissionRules }`).
|
|
54
|
+
* Programmatic assignments take precedence over the config file.
|
|
55
|
+
*/
|
|
56
|
+
workspacePermissions: Map<string, WorkspacePermissions>;
|
|
57
|
+
/**
|
|
58
|
+
* Resolve the effective permission settings for a workspace root.
|
|
59
|
+
* Falls back to the global {@link defaultPermission} / {@link permissionRules}
|
|
60
|
+
* when the root has no per-workspace entry.
|
|
61
|
+
*
|
|
62
|
+
* @param workspaceRoot - Resolved workspace root path ('' or undefined uses the global settings).
|
|
63
|
+
*/
|
|
64
|
+
resolvePermissions(workspaceRoot: string): WorkspacePermissions;
|
|
65
|
+
/**
|
|
66
|
+
* Resolve the effective idle timeout for a command execution.
|
|
67
|
+
*
|
|
68
|
+
* A positive `requested` value (the LLM-supplied `timeout` param) wins and
|
|
69
|
+
* is capped at {@link maxTimeout} when the cap is enabled. Otherwise the
|
|
70
|
+
* value falls back to {@link backgroundTimeout} for background jobs and
|
|
71
|
+
* {@link ctrlCTimeout} for foreground commands.
|
|
72
|
+
*
|
|
73
|
+
* @param background - True for background jobs.
|
|
74
|
+
* @param requested - Optional LLM-supplied timeout in ms.
|
|
75
|
+
* @returns The effective idle timeout in ms (> 0).
|
|
76
|
+
*/
|
|
77
|
+
resolveIdleTimeout(background: boolean, requested?: number): number;
|
|
78
|
+
}
|
|
79
|
+
//# sourceMappingURL=config.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAGA,OAAO,EACH,gBAAgB,EAEhB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EAC5B,MAAM,YAAY,CAAC;AA4EpB;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,eAAe,CAyC3E;AAED,mKAAmK;AACnK,qBAAa,kBAAkB;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAA8C;IAEzF,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAGtB;IAEL,iHAAiH;IACjH,YAAY,EAAE,MAAM,CAGf;IAEL,kHAAkH;IAClH,cAAc,EAAE,MAAM,CAGjB;IAEL,mGAAmG;IACnG,WAAW,EAAE,MAAM,CAGd;IAEL;;OAEG;IACH,WAAW,EAAE,MAAM,CAGd;IAEL,+FAA+F;IAC/F,cAAc,EAAE,MAAM,CAGjB;IAEL;;;;;;OAMG;IACH,iBAAiB,EAAE,MAAM,CAGpB;IAEL;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAGb;IAEL,qHAAqH;IACrH,iBAAiB,EAAE,gBAAgB,CAC+C;IAElF,kFAAkF;IAClF,eAAe,EAAE,cAAc,EAAE,CAA4D;IAE7F;;;;;OAKG;IACH,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAOlD;IAEL;;;;;;OAMG;IACH,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,oBAAoB;IAM/D;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,UAAU,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM;CAStE"}
|