pywebexec 1.9.2__tar.gz → 1.9.4__tar.gz

{pywebexec-1.9.2/pywebexec.egg-info → pywebexec-1.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pywebexec
-Version: 1.9.2
+Version: 1.9.4
 Summary: Simple Python HTTP Exec Server
 Home-page: https://github.com/joknarf/pywebexec
 Author: Franck Jouvanceau
@@ -63,13 +63,13 @@ Requires-Dist: ldap3>=2.9.1
 Requires-Dist: pyte>=0.8.1
 
 [![Pypi version](https://img.shields.io/pypi/v/pywebexec.svg)](https://pypi.org/project/pywebexec/)
-![example](https://github.com/joknarf/pywebexec/actions/workflows/python-publish.yml/badge.svg)
+![Publish Package](https://github.com/joknarf/pywebexec/actions/workflows/python-publish.yml/badge.svg)
 [![Licence](https://img.shields.io/badge/licence-MIT-blue.svg)](https://shields.io/)
 [![PyPI Downloads](https://static.pepy.tech/badge/pywebexec)](https://pepy.tech/projects/pywebexec)
 [![Python versions](https://img.shields.io/badge/python-3.6+-blue.svg)](https://shields.io/)
 
 # pywebexec
-Simple Python HTTP(S) API/Web Command Launcher and Terminal sharing
+Simple Python HTTP(S) API/Web Server Command Launcher and Terminal sharing
 
 ## Install
 ```
@@ -79,6 +79,8 @@ $ pip install pywebexec
 ## Quick start
 
 * share terminal
+  * start http server and spawn a new terminal shared on 0.0.0.0 port 8080 (defaults)
+  * exiting terminal stops server/share
 ```shell
 $ pywebexec shareterm
 ```
@@ -100,6 +102,7 @@ all commands output / statuses are available in the executables directory in sub
 ## features
 
 * Serve executables in a directory
+* full API driven with dynamic swagger UI
 * Launch commands with params from web browser or API call
 * multiple share terminal output
 * Follow live output
@@ -190,20 +193,29 @@ $ pywebexec stop
 ## Launch command through API
 
 ```shell
-$ curl http://myhost:8080/run_command -H 'Content-Type: application/json' -X POST -d '{ "command":"myscript", "params":["param1", ...]}'
-$ curl http://myhost:8080/command_status/<command_id>
-$ curl http://myhost:8080/command_output/<command_id> -H "Accept: text/plain"
+$ curl http://myhost:8080/commands/myscript -H 'Content-Type: application/json' -X POST -d '{"params":["param1", ...]}'
+$ curl http://myhost:8080/commands/<command_id>
+$ curl http://myhost:8080/commands/<command_id>/output -H "Accept: text/plain"
 ```
 
+## Add help to commands
+
+For each exposed command, you can add a help message by creating a file named `<command>.help` in the same directory as the command.  
+The help message is displayed:
+* in the web interface as tooltip when focused on param input field,
+* in the response when calling the API `/executables`
+* in the swagger-ui in the `/commands/<command>` route.
+
 ## API reference
 
 
 | method    | route                       | params/payload     | returns
 |-----------|-----------------------------|--------------------|---------------------|
-| GET       | /executables                |                    | array of str        |
-| GET       | /commands                   |                    | array of<br>command_id: uuid<br>command: str<br>start_time: isotime<br>end_time: isotime<br>status: str<br>exit_code: int<br>last_output_line: str      |
+| GET       | /executables                |                    | executables: [<br>&nbsp;&nbsp;{command: str,help: str},<br>]        |
+| GET       | /commands                   |                    | commands: [<br>&nbsp;&nbsp;{<br>&nbsp;&nbsp;&nbsp;&nbsp;command_id: uuid<br>&nbsp;&nbsp;&nbsp;&nbsp;command: str<br>&nbsp;&nbsp;&nbsp;&nbsp;start_time: isotime<br>&nbsp;&nbsp;&nbsp;&nbsp;end_time: isotime<br>&nbsp;&nbsp;&nbsp;&nbsp;status: str<br>&nbsp;&nbsp;&nbsp;&nbsp;exit_code: int<br>&nbsp;&nbsp;&nbsp;&nbsp;last_output_line: str<br>&nbsp;&nbsp;},<br>]      |
 | GET       | /commands/{id}  |                    | command_id: uuid<br>command: str<br>params: array[str]<br>start_time: isotime<br>end_time: isotime<br>status: str<br>exit_code: int<br>last_output_line: str      |
 | GET       | /commands/{id}/output    | offset: int        | output: str<br>status: str<br>links: { next: str }         |
 | GET       | /commands/{id}/output_raw  | offset: int        | output: stream raw output until end of command<br>curl -Ns http://srv/commands/{id}/output_raw|
 | POST      | /commands                | command: str<br>params: array[str]<br>rows: int<br>cols: int       | command_id: uuid<br>message: str    |
+| POST      | /commands/{cmd}       | params: array[str]<br>rows: int<br>cols: int       | command_id: uuid<br>message: str    |
 | PATCH      | /commands/{id}/stop    |                    | message: str        |

{pywebexec-1.9.2 → pywebexec-1.9.4}/README.md

@@ -1,11 +1,11 @@
 [![Pypi version](https://img.shields.io/pypi/v/pywebexec.svg)](https://pypi.org/project/pywebexec/)
-![example](https://github.com/joknarf/pywebexec/actions/workflows/python-publish.yml/badge.svg)
+![Publish Package](https://github.com/joknarf/pywebexec/actions/workflows/python-publish.yml/badge.svg)
 [![Licence](https://img.shields.io/badge/licence-MIT-blue.svg)](https://shields.io/)
 [![PyPI Downloads](https://static.pepy.tech/badge/pywebexec)](https://pepy.tech/projects/pywebexec)
 [![Python versions](https://img.shields.io/badge/python-3.6+-blue.svg)](https://shields.io/)
 
 # pywebexec
-Simple Python HTTP(S) API/Web Command Launcher and Terminal sharing
+Simple Python HTTP(S) API/Web Server Command Launcher and Terminal sharing
 
 ## Install
 ```
@@ -15,6 +15,8 @@ $ pip install pywebexec
 ## Quick start
 
 * share terminal
+  * start http server and spawn a new terminal shared on 0.0.0.0 port 8080 (defaults)
+  * exiting terminal stops server/share
 ```shell
 $ pywebexec shareterm
 ```
@@ -36,6 +38,7 @@ all commands output / statuses are available in the executables directory in sub
 ## features
 
 * Serve executables in a directory
+* full API driven with dynamic swagger UI
 * Launch commands with params from web browser or API call
 * multiple share terminal output
 * Follow live output
@@ -126,20 +129,29 @@ $ pywebexec stop
 ## Launch command through API
 
 ```shell
-$ curl http://myhost:8080/run_command -H 'Content-Type: application/json' -X POST -d '{ "command":"myscript", "params":["param1", ...]}'
-$ curl http://myhost:8080/command_status/<command_id>
-$ curl http://myhost:8080/command_output/<command_id> -H "Accept: text/plain"
+$ curl http://myhost:8080/commands/myscript -H 'Content-Type: application/json' -X POST -d '{"params":["param1", ...]}'
+$ curl http://myhost:8080/commands/<command_id>
+$ curl http://myhost:8080/commands/<command_id>/output -H "Accept: text/plain"
 ```
 
+## Add help to commands
+
+For each exposed command, you can add a help message by creating a file named `<command>.help` in the same directory as the command.  
+The help message is displayed:
+* in the web interface as tooltip when focused on param input field,
+* in the response when calling the API `/executables`
+* in the swagger-ui in the `/commands/<command>` route.
+
 ## API reference
 
 
 | method    | route                       | params/payload     | returns
 |-----------|-----------------------------|--------------------|---------------------|
-| GET       | /executables                |                    | array of str        |
-| GET       | /commands                   |                    | array of<br>command_id: uuid<br>command: str<br>start_time: isotime<br>end_time: isotime<br>status: str<br>exit_code: int<br>last_output_line: str      |
+| GET       | /executables                |                    | executables: [<br>&nbsp;&nbsp;{command: str,help: str},<br>]        |
+| GET       | /commands                   |                    | commands: [<br>&nbsp;&nbsp;{<br>&nbsp;&nbsp;&nbsp;&nbsp;command_id: uuid<br>&nbsp;&nbsp;&nbsp;&nbsp;command: str<br>&nbsp;&nbsp;&nbsp;&nbsp;start_time: isotime<br>&nbsp;&nbsp;&nbsp;&nbsp;end_time: isotime<br>&nbsp;&nbsp;&nbsp;&nbsp;status: str<br>&nbsp;&nbsp;&nbsp;&nbsp;exit_code: int<br>&nbsp;&nbsp;&nbsp;&nbsp;last_output_line: str<br>&nbsp;&nbsp;},<br>]      |
 | GET       | /commands/{id}  |                    | command_id: uuid<br>command: str<br>params: array[str]<br>start_time: isotime<br>end_time: isotime<br>status: str<br>exit_code: int<br>last_output_line: str      |
 | GET       | /commands/{id}/output    | offset: int        | output: str<br>status: str<br>links: { next: str }         |
 | GET       | /commands/{id}/output_raw  | offset: int        | output: stream raw output until end of command<br>curl -Ns http://srv/commands/{id}/output_raw|
 | POST      | /commands                | command: str<br>params: array[str]<br>rows: int<br>cols: int       | command_id: uuid<br>message: str    |
+| POST      | /commands/{cmd}       | params: array[str]<br>rows: int<br>cols: int       | command_id: uuid<br>message: str    |
 | PATCH      | /commands/{id}/stop    |                    | message: str        |

{pywebexec-1.9.2 → pywebexec-1.9.4}/pywebexec/pywebexec.py

@@ -29,7 +29,8 @@ from pathlib import Path
 import pyte
 from . import host_ip
 from flask_swagger_ui import get_swaggerui_blueprint  # new import
-import yaml  # new import
+import yaml
+import html
 
 if os.environ.get('PYWEBEXEC_LDAP_SERVER'):
     from ldap3 import Server, Connection, ALL, SIMPLE, SUBTREE, Tls
@@ -167,12 +168,22 @@ def strip_ansi_control_chars(text):
 def decode_line(line: bytes) -> str:
     """try decode line exception on binary"""
     try:
-        return get_visible_output(line.decode())
+        return get_visible_line(line.decode())
+    except UnicodeDecodeError:
+        return ""
+
+def get_visible_output(output, cols, rows):
+    """pyte vt100 render to get last line"""
+    try:
+        screen = pyte.Screen(cols, rows)
+        stream = pyte.Stream(screen)
+        stream.feed(output)
+        return "\n".join(screen.display).strip()
     except UnicodeDecodeError:
         return ""
 
 
-def get_visible_output(line, cols, rows):
+def get_visible_line(line, cols, rows):
     """pyte vt100 render to get last line"""
     try:
         screen = pyte.Screen(cols, rows)
@@ -197,7 +208,7 @@ def get_last_line(file_path, cols=None, rows=None, maxsize=2048):
             fd.seek(-maxsize, os.SEEK_END)
         except OSError:
             fd.seek(0)
-        return get_visible_output(fd.read(), cols, rows)
+        return get_visible_line(fd.read(), cols, rows)
 
 
 def start_gunicorn(daemonized=False, baselog=None):
@@ -619,6 +630,19 @@ def log_error(fromip, user, message):
 def log_request(message):
     log_info(request.remote_addr, session.get('username', '-'), message)
 
+def get_executables():
+    executables_list = []
+    for f in os.listdir('.'):
+        if os.path.isfile(f) and os.access(f, os.X_OK):
+            help_file = f"{f}.help"
+            help_text = ""
+            if os.path.exists(help_file) and os.path.isfile(help_file):
+                with open(help_file, 'r') as hf:
+                    help_text = hf.read()
+            executables_list.append({"command": f, "help": help_text})
+    return executables_list
+
+
 @app.route('/commands/<command_id>/stop', methods=['PATCH'])
 def stop_command(command_id):
     log_request(f"stop_command {command_id}")
@@ -744,6 +768,37 @@ def run_command_endpoint():
 
     return jsonify({'message': 'Command is running', 'command_id': command_id})
 
+@app.route('/commands/<cmd>', methods=['POST'])
+def run_dynamic_command(cmd):
+    # Validate that 'cmd' is an executable in the current directory
+    cmd_path = os.path.join(".", os.path.basename(cmd))
+    if not os.path.isfile(cmd_path) or not os.access(cmd_path, os.X_OK):
+        return jsonify({'error': 'Command not found or not executable'}), 400
+    try:
+        data = request.json
+    except Exception as e:
+        data = {}
+    params = data.get('params', [])
+    rows = data.get('rows', tty_rows) or tty_rows
+    cols = data.get('cols', tty_cols) or tty_cols
+    try:
+        params = shlex.split(' '.join(params)) if isinstance(params, list) else []
+    except Exception as e:
+        return jsonify({'error': str(e)}), 400
+    user = session.get('username', '-')
+    command_id = str(uuid.uuid4())
+    update_command_status(command_id, {
+        'status': 'running',
+        'command': cmd,
+        'params': params,
+        'user': user,
+        'from': request.remote_addr,
+    })
+    Path(get_output_file_path(command_id)).touch()
+    thread = threading.Thread(target=run_command, args=(request.remote_addr, user, cmd_path, params, command_id, rows, cols))
+    thread.start()
+    return jsonify({'message': 'Command is running', 'command_id': command_id})
+
 @app.route('/commands/<command_id>', methods=['GET'])
 def get_command_status(command_id):
     status = read_command_status(command_id)
@@ -757,15 +812,15 @@ def index():
 
 @app.route('/commands', methods=['GET'])
 def list_commands():
-    # Sort commands by start_time in descending order
     commands = read_commands()
     commands.sort(key=lambda x: x['start_time'], reverse=True)
-    return jsonify(commands)
+    return jsonify({"commands": commands})
 
 @app.route('/commands/<command_id>/output', methods=['GET'])
 def get_command_output(command_id):
     offset = int(request.args.get('offset', 0))
     maxsize = int(request.args.get('maxsize', 10485760))
+    maxlines = int(request.args.get('maxlines', 5000))
     output_file_path = get_output_file_path(command_id)
     if os.path.exists(output_file_path):
         size = os.path.getsize(output_file_path)
@@ -790,7 +845,7 @@ def get_command_output(command_id):
             }
         }
         if request.headers.get('Accept') == 'text/plain':
-            return f"{output}\nstatus: {status_data.get('status')}", 200, {'Content-Type': 'text/plain'}
+            return f"{get_visible_output(output, status_data.get('cols'), maxlines)}\nstatus: {status_data.get('status')}", 200, {'Content-Type': 'text/plain'}
         return jsonify(response)
     return jsonify({'error': 'Invalid command_id'}), 404
 
@@ -820,9 +875,8 @@ def get_command_output_raw(command_id):
 
 @app.route('/executables', methods=['GET'])
 def list_executables():
-    executables = [f for f in os.listdir('.') if os.path.isfile(f) and os.access(f, os.X_OK)]
-    executables.sort()  # Sort the list of executables alphabetically
-    return jsonify(executables)
+    executables_list = get_executables()
+    return jsonify({"executables": executables_list})
 
 @app.route('/commands/<command_id>/popup')
 def popup(command_id):
@@ -854,7 +908,54 @@ def swagger_yaml():
         with open(swagger_path, 'r') as f:
             swagger_spec_str = f.read()
         swagger_spec = yaml.safe_load(swagger_spec_str)
-        # Set title dynamically using the app configuration
+        # Update existing POST /commands enum if present
+        executables = get_executables()
+        post_cmd = swagger_spec.get('paths', {}).get('/commands', {}).get('post')
+        if post_cmd:
+            params_list = post_cmd.get('parameters', [])
+            for param in params_list:
+                if param.get('in') == 'body' and 'schema' in param:
+                    props = param['schema'].get('properties', {})
+                    if 'command' in props:
+                        props['command']['enum'] = [e['command'] for e in executables]
+        # Add dynamic paths for each 
+        # Add dynamic paths for each executable:
+        for exe in executables:
+            dynamic_path = "/commands/" + exe["command"]
+            swagger_spec.setdefault("paths", {})[dynamic_path] = {
+                "post": {
+                    "summary": f"Run command {exe["command"]}",
+                    "description": html.escape(exe["help"]),
+                    "consumes": ["application/json"],
+                    "produces": ["application/json"],
+                    "parameters": [
+                        {
+                            "in": "body",
+                            "name": "commandRequest",
+                            "schema": {
+                                "type": "object",
+                                "properties": {
+                                    "params": {"type": "array", "items": {"type": "string"}, "default": []},
+                                    "rows": {"type": "integer", "default": tty_rows},
+                                    "cols": {"type": "integer", "default": tty_cols},
+                                }
+                            }
+                        }
+                    ],
+                    "responses": {
+                        "200": {
+                            "description": "Command started",
+                            "schema": {
+                                "type": "object",
+                                "properties": {
+                                    "message": {"type": "string"},
+                                    "command_id": {"type": "string"}
+                                }
+                            }
+                        }
+                    }
+                }
+            }
         swagger_spec['info']['title'] = app.config.get('TITLE', 'PyWebExec API')
         swagger_spec_str = yaml.dump(swagger_spec)
         return Response(swagger_spec_str, mimetype='application/yaml')

{pywebexec-1.9.2 → pywebexec-1.9.4}/pywebexec/static/css/style.css

@@ -99,6 +99,18 @@ form {
     vertical-align: bottom;
     padding-left: 35px;
 }
+#paramsHelp {
+    position: absolute;
+    background-color: #e0e0ff;
+    border: 1px solid #ccc;
+    padding: 4px 8px;
+    font-size: 0.9em;
+    display: none;
+    z-index: 1000;
+    white-space: pre;
+    border-radius: 5px;
+    font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
+}
 #thStatus {
     cursor: pointer;
 }

pywebexec-1.9.2/pywebexec/static/js/commands.js → pywebexec-1.9.4/pywebexec/static/js/executables.js

@@ -5,6 +5,8 @@ let commandListDiv = document.getElementById('commandList');
 let showCommandListButton = document.getElementById('showCommandListButton');
 let isHandlingKeydown = false;
 let firstVisibleItem = 0;
+let gExecutables = {};
+let helpDiv = document.getElementById('paramsHelp');
 
 function unfilterCommands() {
     const items = commandListDiv.children;
@@ -43,6 +45,13 @@ function setCommandListPosition() {
     commandListDiv.style.top = `${rect.bottom}px`;
 }
 
+// Update helpDiv position relative to paramsInput
+function setHelpDivPosition() {
+    const rect = paramsInput.getBoundingClientRect();
+    helpDiv.style.left = `${rect.left}px`;
+    helpDiv.style.top = `${rect.bottom + 2}px`;
+}
+
 function adjustInputWidth(input) {
     input.style.width = 'auto';
     input.style.width = `${input.scrollWidth}px`;
@@ -216,17 +225,23 @@ window.addEventListener('load', () => {
 
 async function fetchExecutables() {
     try {
-        const response = await fetch(`/executables${urlToken}`);
+        const response = await fetch(`/executables`);
         if (!response.ok) {
-            throw new Error('Failed to fetch command status');
+            throw new Error('Failed to fetch executables');
         }
-        const executables = await response.json();
+        const data = await response.json();
+        // Build mapping from executable name to its object
+        gExecutables = {};
         commandListDiv.innerHTML = '';
-        executables.forEach(executable => {
+        data.executables.forEach(exeObj => {
+            gExecutables[exeObj.command] = exeObj;
             const div = document.createElement('div');
             div.className = 'command-item';
-            div.textContent = executable;
-            div.tabIndex = 0; // Make the div focusable
+            div.textContent = exeObj.command;
+            div.tabIndex = 0;
+            if (exeObj.help) {
+                div.title = exeObj.help;
+            }
             commandListDiv.appendChild(div);
         });
     } catch (error) {
@@ -240,3 +255,22 @@ async function fetchExecutables() {
         document.getElementById('launchForm').style.display = 'none';
 
 }
+
+paramsInput.addEventListener('focus', () => {
+    const currentCmd = commandInput.value;
+    if (gExecutables[currentCmd] && gExecutables[currentCmd].help) {
+        //helpDiv.innerHTML = gExecutables[currentCmd].help.replace(/\n/g, '<br>');
+        helpDiv.innerText = gExecutables[currentCmd].help;
+        setHelpDivPosition();
+        helpDiv.style.display = 'block';
+    } else {
+        helpDiv.style.display = 'none';
+    }
+});
+
+paramsInput.addEventListener('blur', () => {
+    helpDiv.style.display = 'none';
+});
+
+window.addEventListener('resize', setHelpDivPosition);
+window.addEventListener('scroll', setHelpDivPosition);

{pywebexec-1.9.2 → pywebexec-1.9.4}/pywebexec/static/js/popup.js

@@ -98,11 +98,6 @@ function autoFit(scroll=true) {
     if (scroll) terminal.scrollToBottom();
 }
 
-function getTokenParam() {
-    const urlParams = new URLSearchParams(window.location.search);
-    return urlParams.get('token') ? `?token=${urlParams.get('token')}` : '';
-}
-const urlToken = getTokenParam();
 
 
 function setCommandStatus(status) {
@@ -161,14 +156,14 @@ async function viewOutput(command_id) {
     slider.value = 1000;
     adjustOutputHeight();
     currentCommandId = command_id;
-    nextOutputLink = `/commands/${command_id}/output${urlToken}`;
+    nextOutputLink = `/commands/${command_id}/output`;
     clearInterval(outputInterval);
     terminal.clear();
     terminal.reset();
     fullOutput = '';
     try {
         // Updated endpoint below:
-        const response = await fetch(`/commands/${command_id}${urlToken}`);
+        const response = await fetch(`/commands/${command_id}`);
         if (!response.ok) {
             return;
         }

{pywebexec-1.9.2 → pywebexec-1.9.4}/pywebexec/static/js/script.js

@@ -108,12 +108,6 @@ function autoFit(scroll=true) {
     if (scroll) terminal.scrollToBottom();
 }
 
-function getTokenParam() {
-    const urlParams = new URLSearchParams(window.location.search);
-    return urlParams.get('token') ? `?token=${urlParams.get('token')}` : '';
-}
-const urlToken = getTokenParam();
-
 
 document.getElementById('launchForm').addEventListener('submit', async (event) => {
     event.preventDefault();
@@ -122,7 +116,7 @@ document.getElementById('launchForm').addEventListener('submit', async (event) =
     fitAddon.fit();
     terminal.clear();
     try {
-        const response = await fetch(`/commands${urlToken}`, {
+        const response = await fetch(`/commands`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json'
@@ -144,12 +138,14 @@ document.getElementById('launchForm').addEventListener('submit', async (event) =
 
 async function fetchCommands(hide=false) {
     try {
-        const response = await fetch(`/commands${urlToken}`);
+        const response = await fetch(`/commands`);
         if (!response.ok) {
             document.getElementById('dimmer').style.display = 'block';
             return;
         }
-        const commands = await response.json();
+        // Adapt to the new result structure:
+        const data = await response.json();
+        const commands = data.commands;
         commands.sort((a, b) => new Date(b.start_time) - new Date(a.start_time));
         const commandsTbody = document.getElementById('commands');
         commandsTbody.innerHTML = '';
@@ -252,13 +248,13 @@ async function viewOutput(command_id) {
     outputPercentage.innerText = '100%';
     adjustOutputHeight();
     currentCommandId = command_id;
-    nextOutputLink = `/commands/${command_id}/output${urlToken}`; // updated URL
+    nextOutputLink = `/commands/${command_id}/output`;
     clearInterval(outputInterval);
     terminal.clear();
     terminal.reset();
     fullOutput = '';
     try {
-        const response = await fetch(`/commands/${command_id}${urlToken}`);
+        const response = await fetch(`/commands/${command_id}`);
         if (!response.ok) {
             outputInterval = setInterval(() => fetchOutput(nextOutputLink), 500);
         }
@@ -289,7 +285,7 @@ async function viewOutput(command_id) {
 async function openPopup(command_id, event) {
     event.stopPropagation();
     event.stopImmediatePropagation();
-    const popupUrl = `/commands/${command_id}/popup${urlToken}`;
+    const popupUrl = `/commands/${command_id}/popup`;
     window.open(popupUrl, '_blank', 'width=1000,height=600');
 }
 
@@ -297,7 +293,7 @@ async function relaunchCommand(command_id, event) {
     event.stopPropagation();
     event.stopImmediatePropagation();
     try {
-        const response = await fetch(`/commands/${command_id}${urlToken}`);
+        const response = await fetch(`/commands/${command_id}`);
         if (!response.ok) {
             throw new Error('Failed to fetch command status');
         }
@@ -308,7 +304,7 @@ async function relaunchCommand(command_id, event) {
         }
         fitAddon.fit();
         terminal.clear();
-        const relaunchResponse = await fetch(`/commands${urlToken}`, {
+        const relaunchResponse = await fetch(`/commands`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json'
@@ -336,7 +332,7 @@ async function stopCommand(command_id, event) {
     event.stopPropagation();
     event.stopImmediatePropagation();
     try {
-        const response = await fetch(`/commands/${command_id}/stop${urlToken}`, {
+        const response = await fetch(`/commands/${command_id}/stop`, {
             method: 'PATCH'
         });
         if (!response.ok) {

pywebexec-1.9.4/pywebexec/swagger.yaml

@@ -0,0 +1,209 @@
+swagger: "2.0"
+info:
+  title: PyWebExec API
+  version: "1.0"
+paths:
+  /commands:
+    get:
+      summary: "List commands status"
+      responses:
+        "200":
+          description: "List of all commands status"
+          schema:
+            type: object
+            properties:
+              commands:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    command_id:
+                      type: string
+                    command:
+                      type: string
+                    status:
+                      type: string
+                    start_time:
+                      type: string
+                      format: date-time
+                    end_time:
+                      type: string
+                      format: date-time
+                    exit_code:
+                      type: integer
+                    last_output_line:
+                      type: string
+                    user:
+                      type: string
+    post:
+      summary: "Run a command"
+      consumes:
+        - application/json
+      produces:
+        - application/json
+      parameters:
+        - in: body
+          name: commandRequest
+          schema:
+            type: object
+            properties:
+              command:
+                type: string
+                # Enum will be added dynamically by the APIs
+                default: commandName
+              params:
+                type: array
+                items:
+                  type: string
+                default: []
+              rows:
+                type: integer
+                default: 24
+              cols:
+                type: integer
+                default: 125
+            required:
+              - command
+      responses:
+        "200":
+          description: "Command started"
+          schema:
+            type: object
+            properties:
+              command_id:
+                type: string
+              message:
+                type: string
+  /commands/{command_id}:
+    get:
+      summary: "Get command status"
+      parameters:
+        - in: path
+          name: command_id
+          required: true
+          type: string
+      responses:
+        "200":
+          description: "Command status returned"
+          schema:
+            type: object
+            properties:
+              command_id:
+                type: string
+              command:
+                type: string
+              params:
+                type: array
+                items:
+                  type: string
+              status:
+                type: string
+              start_time:
+                type: string
+                format: date-time
+              end_time:
+                type: string
+                format: date-time
+              exit_code:
+                type: integer
+              last_output_line:
+                type: string
+              cols:
+                type: integer
+              rows:
+                type: integer
+              user:
+                type: string
+              from:
+                type: string
+              pid:
+                type: integer
+
+  /commands/{command_id}/output:
+    get:
+      summary: "Get command output"
+      parameters:
+        - in: path
+          name: command_id
+          required: true
+          type: string
+        - in: query
+          name: offset
+          type: integer
+          default: 0
+        - in: query
+          name: maxsize
+          type: integer
+          default: 10485760
+        - in: query
+          name: maxlines
+          type: integer
+          default: 5000
+      consumes:
+        - application/json
+      produces:
+        - application/json
+        - text/plain
+      responses:
+        "200":
+          description: "Command output returned"
+          schema:
+            type: object
+            properties:
+              output:
+                type: string
+              status:
+                type: string
+              rows:
+                type: integer
+              cols:
+                type: integer
+              links:
+                type: object
+                properties:
+                  next:
+                    type: string
+                    format: uri
+  /commands/{command_id}/stop:
+    patch:
+      summary: "Stop a running command"
+      parameters:
+        - in: path
+          name: command_id
+          required: true
+          type: string
+      responses:
+        "200":
+          description: "Command stopped successfully"
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+  /executables:
+    get:
+      summary: "List available executable commands"
+      produces:
+        - application/json
+      responses:
+        "200":
+          description: "List of executables returned as an array of executable objects"
+          schema:
+            type: object
+            properties:
+              executables:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    command:
+                      type: string
+                    help:
+                      type: string
+          examples:
+            application/json:
+              executables:
+                - command: ls
+                  help: "List directory contents\nparams:\n  <ls_params>"
+                - command: cat
+                  help: "Concatenate and display files\nparams:\n  <cat_params>"

{pywebexec-1.9.2 → pywebexec-1.9.4}/pywebexec/templates/index.html

@@ -21,6 +21,7 @@
             </div>
             <div id="commandList" class="command-list"></div>
             <input type="text" id="params" name="params" oninput="this.style.width = ((this.value.length + 1) * 8) + 'px';">
+            <pre id="paramsHelp"></pre>
         </div>
         <button type="submit">Run</button>
     </form>
@@ -60,6 +61,6 @@
     <script src="/static/js/xterm/addon-unicode-graphemes.js"></script>
     <script src="/static/js/xterm/addon-fit.js"></script>
     <script type="text/javascript" src="/static/js/script.js"></script>
-    <script type="text/javascript" src="/static/js/commands.js"></script>
+    <script type="text/javascript" src="/static/js/executables.js"></script>
 </body>
 </html>

{pywebexec-1.9.2 → pywebexec-1.9.4}/pywebexec/version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.9.2'
-__version_tuple__ = version_tuple = (1, 9, 2)
+__version__ = version = '1.9.4'
+__version_tuple__ = version_tuple = (1, 9, 4)

{pywebexec-1.9.2 → pywebexec-1.9.4/pywebexec.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pywebexec
-Version: 1.9.2
+Version: 1.9.4
 Summary: Simple Python HTTP Exec Server
 Home-page: https://github.com/joknarf/pywebexec
 Author: Franck Jouvanceau
@@ -63,13 +63,13 @@ Requires-Dist: ldap3>=2.9.1
 Requires-Dist: pyte>=0.8.1
 
 [![Pypi version](https://img.shields.io/pypi/v/pywebexec.svg)](https://pypi.org/project/pywebexec/)
-![example](https://github.com/joknarf/pywebexec/actions/workflows/python-publish.yml/badge.svg)
+![Publish Package](https://github.com/joknarf/pywebexec/actions/workflows/python-publish.yml/badge.svg)
 [![Licence](https://img.shields.io/badge/licence-MIT-blue.svg)](https://shields.io/)
 [![PyPI Downloads](https://static.pepy.tech/badge/pywebexec)](https://pepy.tech/projects/pywebexec)
 [![Python versions](https://img.shields.io/badge/python-3.6+-blue.svg)](https://shields.io/)
 
 # pywebexec
-Simple Python HTTP(S) API/Web Command Launcher and Terminal sharing
+Simple Python HTTP(S) API/Web Server Command Launcher and Terminal sharing
 
 ## Install
 ```
@@ -79,6 +79,8 @@ $ pip install pywebexec
 ## Quick start
 
 * share terminal
+  * start http server and spawn a new terminal shared on 0.0.0.0 port 8080 (defaults)
+  * exiting terminal stops server/share
 ```shell
 $ pywebexec shareterm
 ```
@@ -100,6 +102,7 @@ all commands output / statuses are available in the executables directory in sub
 ## features
 
 * Serve executables in a directory
+* full API driven with dynamic swagger UI
 * Launch commands with params from web browser or API call
 * multiple share terminal output
 * Follow live output
@@ -190,20 +193,29 @@ $ pywebexec stop
 ## Launch command through API
 
 ```shell
-$ curl http://myhost:8080/run_command -H 'Content-Type: application/json' -X POST -d '{ "command":"myscript", "params":["param1", ...]}'
-$ curl http://myhost:8080/command_status/<command_id>
-$ curl http://myhost:8080/command_output/<command_id> -H "Accept: text/plain"
+$ curl http://myhost:8080/commands/myscript -H 'Content-Type: application/json' -X POST -d '{"params":["param1", ...]}'
+$ curl http://myhost:8080/commands/<command_id>
+$ curl http://myhost:8080/commands/<command_id>/output -H "Accept: text/plain"
 ```
 
+## Add help to commands
+
+For each exposed command, you can add a help message by creating a file named `<command>.help` in the same directory as the command.  
+The help message is displayed:
+* in the web interface as tooltip when focused on param input field,
+* in the response when calling the API `/executables`
+* in the swagger-ui in the `/commands/<command>` route.
+
 ## API reference
 
 
 | method    | route                       | params/payload     | returns
 |-----------|-----------------------------|--------------------|---------------------|
-| GET       | /executables                |                    | array of str        |
-| GET       | /commands                   |                    | array of<br>command_id: uuid<br>command: str<br>start_time: isotime<br>end_time: isotime<br>status: str<br>exit_code: int<br>last_output_line: str      |
+| GET       | /executables                |                    | executables: [<br>&nbsp;&nbsp;{command: str,help: str},<br>]        |
+| GET       | /commands                   |                    | commands: [<br>&nbsp;&nbsp;{<br>&nbsp;&nbsp;&nbsp;&nbsp;command_id: uuid<br>&nbsp;&nbsp;&nbsp;&nbsp;command: str<br>&nbsp;&nbsp;&nbsp;&nbsp;start_time: isotime<br>&nbsp;&nbsp;&nbsp;&nbsp;end_time: isotime<br>&nbsp;&nbsp;&nbsp;&nbsp;status: str<br>&nbsp;&nbsp;&nbsp;&nbsp;exit_code: int<br>&nbsp;&nbsp;&nbsp;&nbsp;last_output_line: str<br>&nbsp;&nbsp;},<br>]      |
 | GET       | /commands/{id}  |                    | command_id: uuid<br>command: str<br>params: array[str]<br>start_time: isotime<br>end_time: isotime<br>status: str<br>exit_code: int<br>last_output_line: str      |
 | GET       | /commands/{id}/output    | offset: int        | output: str<br>status: str<br>links: { next: str }         |
 | GET       | /commands/{id}/output_raw  | offset: int        | output: stream raw output until end of command<br>curl -Ns http://srv/commands/{id}/output_raw|
 | POST      | /commands                | command: str<br>params: array[str]<br>rows: int<br>cols: int       | command_id: uuid<br>message: str    |
+| POST      | /commands/{cmd}       | params: array[str]<br>rows: int<br>cols: int       | command_id: uuid<br>message: str    |
 | PATCH      | /commands/{id}/stop    |                    | message: str        |

{pywebexec-1.9.2 → pywebexec-1.9.4}/pywebexec.egg-info/SOURCES.txt

@@ -36,7 +36,7 @@ pywebexec/static/images/popup.svg
 pywebexec/static/images/resume.svg
 pywebexec/static/images/running.svg
 pywebexec/static/images/success.svg
-pywebexec/static/js/commands.js
+pywebexec/static/js/executables.js
 pywebexec/static/js/popup.js
 pywebexec/static/js/script.js
 pywebexec/static/js/xterm/LICENSE

pywebexec-1.9.2/pywebexec/swagger.yaml

@@ -1,83 +0,0 @@
-swagger: "2.0"
-info:
-  title: PyWebExec API
-  version: "1.0"
-paths:
-  /commands:
-    get:
-      summary: "List commands status"
-      responses:
-        "200":
-          description: "List of all commands status"
-    post:
-      summary: "Run a command"
-      consumes:
-        - application/json
-      produces:
-        - application/json
-      parameters:
-        - in: body
-          name: commandRequest
-          schema:
-            type: object
-            properties:
-              command:
-                type: string
-              params:
-                type: array
-                items:
-                  type: string
-              rows:
-                type: integer
-              cols:
-                type: integer
-      responses:
-        "200":
-          description: "Command started"
-  /commands/{command_id}:
-    get:
-      summary: "Get command status"
-      parameters:
-        - in: path
-          name: command_id
-          required: true
-          type: string
-      responses:
-        "200":
-          description: "Command status returned"
-  /commands/{command_id}/output:
-    get:
-      summary: "Get command output"
-      parameters:
-        - in: path
-          name: command_id
-          required: true
-          type: string
-        - in: query
-          name: offset
-          type: integer
-          default: 0
-        - in: query
-          name: maxsize
-          type: integer
-          default: 10485760
-      responses:
-        "200":
-          description: "Command output returned"
-  /commands/{command_id}/stop:
-    patch:
-      summary: "Stop a running command"
-      parameters:
-        - in: path
-          name: command_id
-          required: true
-          type: string
-      responses:
-        "200":
-          description: "Command stopped successfully"
-  /executables:
-    get:
-      summary: "List available executable commands"
-      responses:
-        "200":
-          description: "List of executables returned as an array of executable names"