@mako10k/shell-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mako10k
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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

@@ -0,0 +1,114 @@
+# shell-server
+
+Shared foundation for MCP Shell Server. This repo contains the core runtime,
+server management layer, daemon IPC, tools, and security modules used by
+interface layers (mcp-shell, VS Code extension, etc.).
+
+## Install
+
+```bash
+npm install @mako10k/shell-server
+```
+
+## Run
+
+```bash
+npx -y @mako10k/shell-server
+```
+
+You can override the daemon socket and workspace namespace via flags or env vars.
+
+```bash
+shell-server --socket /tmp/mcp-shell/daemon.sock --cwd /path/to/repo --branch main
+```
+
+`--branch` is used for daemon socket namespace selection (not Git checkout branch selection).
+
+Option precedence for socket path resolution:
+
+- `--socket` (explicit socket path)
+- `MCP_SHELL_DAEMON_SOCKET`
+- auto-generated from `--cwd`/`MCP_SHELL_DAEMON_CWD` + `--branch`/`MCP_SHELL_DAEMON_BRANCH`
+
+In other words, `--branch` affects the socket path only when an explicit socket path is not provided.
+
+Default values (when options are omitted):
+
+- `--cwd`: current process working directory (`process.cwd()`)
+- `--branch`: `MCP_SHELL_DAEMON_BRANCH` -> `MCP_SHELL_SERVER_BRANCH` -> `main`
+- `--socket`: `MCP_SHELL_DAEMON_SOCKET` or auto-generated as
+	`$XDG_RUNTIME_DIR|os.tmpdir()/mcp-shell/<sha256(cwd)>/<branch>/daemon.sock`
+
+### shell-server-cli
+
+```bash
+shell-server-cli [--socket <path>] [--cwd <path>] [--branch <name>] [subcmd [subcmd options]]
+```
+
+Subcmd (function name):
+
+- `status`
+- `info`
+- `attach`
+- `detach`
+- `reattach`
+- `stop`
+
+Tool subcommand:
+
+```bash
+shell-server-cli [connection options] tool <tool-name> [--tool-option <value> ...]
+```
+
+AWS CLI-style extensions:
+
+- `--input-json <json|@file>`: provide tool params as JSON object
+- `--query <expr>`: filter JSON output with jq expression
+	- engine order: `node-jq` -> system `jq` -> built-in simple query fallback
+
+Examples:
+
+```bash
+shell-server-cli --branch main tool shell-execute --input-json '{"command":"echo hello","execution_mode":"foreground"}'
+shell-server-cli --branch main tool shell-execute --command "echo hello" --execution-mode foreground --query '.result.stdout'
+```
+
+Help and schema inspection:
+
+```bash
+shell-server-cli --help
+shell-server-cli tool help
+shell-server-cli tool shell-execute --help
+```
+
+- `<tool-name>` accepts kebab-case and is converted to internal snake_case.
+	- Example: `shell-execute` -> `shell_execute`
+- tool options use `--kebab-case` and are converted to internal snake_case keys.
+	- Example: `--working-directory` -> `working_directory`
+- tool option values are parsed as JSON literals when possible; otherwise they are treated as strings.
+
+Example:
+
+```bash
+shell-server-cli --branch main tool shell-execute --command "echo hello" --execution-mode "foreground"
+```
+
+`shell-server-cli` uses the same connection option resolution rules as `shell-server`.
+
+## Build
+
+```bash
+npm install
+npm run build
+```
+
+## Exports
+
+- `@mako10k/shell-server/runtime`
+- `@mako10k/shell-server/tool-runtime`
+
+## Environment
+
+- `MCP_SHELL_DAEMON_SOCKET` (socket path override)
+- `MCP_SHELL_DAEMON_CWD` (working directory override)
+- `MCP_SHELL_DAEMON_BRANCH` (branch namespace override)

package/dist/backoffice/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/backoffice/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backoffice/index.ts"],"names":[],"mappings":""}

package/dist/backoffice/index.js

@@ -0,0 +1,47 @@
+import { BackofficeServer } from './server.js';
+import { ProcessManager } from '../core/process-manager.js';
+import { TerminalManager } from '../core/terminal-manager.js';
+import { FileManager } from '../core/file-manager.js';
+import { CommandHistoryManager } from '../core/enhanced-history-manager.js';
+import { ConfigManager } from '../core/config-manager.js';
+import { logger } from '../utils/helpers.js';
+// Minimal bootstrap to run Backoffice standalone for local monitoring
+async function main() {
+    try {
+        const fileManager = new FileManager();
+        const configManager = new ConfigManager();
+        const enhancedConfig = configManager.getEnhancedSecurityConfig();
+        const historyManager = new CommandHistoryManager(enhancedConfig);
+        await historyManager.loadHistory().catch((e) => {
+            // Non-fatal: start with empty history if load fails
+            logger.warn('Backoffice bootstrap: failed to load history', { error: String(e) }, 'backoffice');
+        });
+        const processManager = new ProcessManager(50, '/tmp/mcp-shell-outputs', fileManager);
+        const terminalManager = new TerminalManager();
+        processManager.setTerminalManager(terminalManager);
+        const backoffice = new BackofficeServer({
+            processManager,
+            terminalManager,
+            fileManager,
+            historyManager,
+        });
+        await backoffice.start();
+        logger.info('Backoffice standalone started', {}, 'backoffice');
+        const graceful = async () => {
+            try {
+                await backoffice.stop();
+            }
+            finally {
+                process.exit(0);
+            }
+        };
+        process.on('SIGINT', graceful);
+        process.on('SIGTERM', graceful);
+    }
+    catch (e) {
+        logger.error('Backoffice standalone failed to start', { error: String(e) }, 'backoffice');
+        process.exit(1);
+    }
+}
+void main();
+//# sourceMappingURL=index.js.map

package/dist/backoffice/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backoffice/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,sEAAsE;AACtE,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;QACtC,MAAM,aAAa,GAAG,IAAI,aAAa,EAAE,CAAC;QAC1C,MAAM,cAAc,GAAG,aAAa,CAAC,yBAAyB,EAAE,CAAC;QACjE,MAAM,cAAc,GAAG,IAAI,qBAAqB,CAAC,cAAc,CAAC,CAAC;QACjE,MAAM,cAAc,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;YAC7C,oDAAoD;YACpD,MAAM,CAAC,IAAI,CAAC,8CAA8C,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;QAClG,CAAC,CAAC,CAAC;QAEH,MAAM,cAAc,GAAG,IAAI,cAAc,CAAC,EAAE,EAAE,wBAAwB,EAAE,WAAW,CAAC,CAAC;QACrF,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;QAC9C,cAAc,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAC;QAEnD,MAAM,UAAU,GAAG,IAAI,gBAAgB,CAAC;YACtC,cAAc;YACd,eAAe;YACf,WAAW;YACX,cAAc;SACf,CAAC,CAAC;QAEH,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,IAAI,CAAC,+BAA+B,EAAE,EAAE,EAAE,YAAY,CAAC,CAAC;QAE/D,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;YAC1B,IAAI,CAAC;gBACH,MAAM,UAAU,CAAC,IAAI,EAAE,CAAC;YAC1B,CAAC;oBAAS,CAAC;gBACT,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;QACH,CAAC,CAAC;QACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,CAAC,KAAK,CAAC,uCAAuC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;QAC1F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,KAAK,IAAI,EAAE,CAAC"}

package/dist/backoffice/server.d.ts

@@ -0,0 +1,45 @@
+import { ProcessManager } from '../core/process-manager.js';
+import { TerminalManager } from '../core/terminal-manager.js';
+import { FileManager } from '../core/file-manager.js';
+import { CommandHistoryManager } from '../core/enhanced-history-manager.js';
+interface BackofficeDeps {
+    processManager: ProcessManager;
+    terminalManager: TerminalManager;
+    fileManager: FileManager;
+    historyManager: CommandHistoryManager;
+}
+export declare class BackofficeServer {
+    private deps;
+    private server;
+    private readonly host;
+    private readonly port;
+    constructor(deps: BackofficeDeps, port?: number);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getListenPort(): number;
+    private handleHistoryList;
+    private handleHistoryGet;
+    private handleExecutionsList;
+    private handleExecutionGet;
+    private handleExecutionOutputs;
+    private handleTerminalsList;
+    private handleTerminalGet;
+    private handleTerminalOutput;
+    private isRemoteBackend;
+    private getRemoteService;
+    private ensureRemoteBackend;
+    private handleRemoteRequest;
+    private handleDashboard;
+    private handleRemoteExecGet;
+    private handleRemoteExecOutputs;
+    private handleRemoteExecKill;
+    private initSSE;
+    private writeSSE;
+    private handleTerminalSSE;
+    private handleRemoteExecSSE;
+    private serveStatic;
+    private json;
+    private isLocalAddress;
+}
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/backoffice/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/backoffice/server.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAM5E,UAAU,cAAc;IACtB,cAAc,EAAE,cAAc,CAAC;IAC/B,eAAe,EAAE,eAAe,CAAC;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,cAAc,EAAE,qBAAqB,CAAC;CACvC;AAED,qBAAa,gBAAgB;IAKf,OAAO,CAAC,IAAI;IAJxB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAEV,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,MAAM;IAIvD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA+KhB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B,aAAa,IAAI,MAAM;YAST,iBAAiB;YAkDjB,gBAAgB;YAUhB,oBAAoB;YAiBpB,kBAAkB;YASlB,sBAAsB;YAStB,mBAAmB;YAYnB,iBAAiB;YASjB,oBAAoB;IAoBlC,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,mBAAmB;YAQb,mBAAmB;YAenB,eAAe;YA6Df,mBAAmB;YAInB,uBAAuB;YAIvB,oBAAoB;IAiBlC,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,QAAQ;YAWF,iBAAiB;YAiFjB,mBAAmB;YA4DnB,WAAW;IAYzB,OAAO,CAAC,IAAI;IAMZ,OAAO,CAAC,cAAc;CAOvB"}