portacode 1.3.32__py3-none-any.whl → 1.4.11.dev0__py3-none-any.whl

portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -41,9 +41,14 @@ This document describes the complete protocol for communicating with devices thr
     - [`terminal_list`](#terminal_list)
   - [System Actions](#system-actions)
     - [`system_info`](#system_info)
+    - [`update_portacode_cli`](#update_portacode_cli)
+    - [`clock_sync_request`](#clock_sync_request)
   - [File Actions](#file-actions)
     - [`file_read`](#file_read)
+    - [`file_search`](#file_search)
     - [`file_write`](#file_write)
+  - [`file_apply_diff`](#file_apply_diff)
+    - [`file_preview_diff`](#file_preview_diff)
     - [`directory_list`](#directory_list)
     - [`file_info`](#file_info)
     - [`file_delete`](#file_delete)
@@ -78,9 +83,14 @@ This document describes the complete protocol for communicating with devices thr
     - [`terminal_list`](#terminal_list-event)
   - [System Events](#system-events)
     - [`system_info`](#system_info-event)
+    - [`update_portacode_response`](#update_portacode_response)
+    - [`clock_sync_response`](#clock_sync_response)
   - [File Events](#file-events)
     - [`file_read_response`](#file_read_response)
+    - [`file_search_response`](#file_search_response)
     - [`file_write_response`](#file_write_response)
+    - [`file_apply_diff_response`](#file_apply_diff_response)
+    - [`file_preview_diff_response`](#file_preview_diff_response)
     - [`directory_list_response`](#directory_list_response)
     - [`file_info_response`](#file_info_response)
     - [`file_delete_response`](#file_delete_response)
@@ -310,6 +320,46 @@ This action does not require any payload fields.
 
 *   On success, the device will respond with a [`system_info`](#system_info-event) event.
 
+### `setup_proxmox_infra`
+
+Configures a Proxmox node for Portacode infrastructure usage (API token storage, default storage selection, and bridge setup). Handled by [`ConfigureProxmoxInfraHandler`](./proxmox_infra.py).
+
+**Payload Fields:**
+
+*   `token_identifier` (string, required): API token identifier in the form `user@realm!tokenid`.
+*   `token_value` (string, required): Secret value associated with the token.
+*   `verify_ssl` (boolean, optional): When true, the handler verifies SSL certificates; defaults to `false`.
+
+**Responses:**
+
+*   On success, the device will emit a [`proxmox_infra_configured`](#proxmox_infra_configured-event) event with the persisted infra snapshot.
+*   On failure, the device will emit an [`error`](#error) event with details (e.g., permission issues, missing proxmoxer/dnsmasq, or missing root privileges).
+
+### `clock_sync_request`
+
+Internal event that devices send to the gateway to request the authoritative server timestamp (used for adjusting `portacode.utils.ntp_clock`). The gateway responds immediately with [`clock_sync_response`](#clock_sync_response).
+
+**Payload Fields:**
+
+*   `request_id` (string, optional): Correlates the response with the request.
+
+**Responses:**
+
+*   The gateway responds with [`clock_sync_response`](#clock_sync_response) that includes the authoritative `server_time` (plus the optional `server_time_iso` mirror).
+
+### `update_portacode_cli`
+
+Updates the Portacode CLI package and restarts the process. Handled by [`update_portacode_cli`](./update_handler.py).
+
+**Payload Fields:**
+
+This action does not require any payload fields.
+
+**Responses:**
+
+*   On success, the device will respond with an `update_portacode_response` event and then exit with code 42 to trigger restart.
+*   On error, an `update_portacode_response` event with error details is sent.
+
 ### `file_read`
 
 Reads the content of a file. Handled by [`file_read`](./file_handlers.py).
@@ -317,12 +367,46 @@ Reads the content of a file. Handled by [`file_read`](./file_handlers.py).
 **Payload Fields:**
 
 *   `path` (string, mandatory): The absolute path to the file to read.
+*   `start_line` (integer, optional): 1-based line number to start reading from. Defaults to `1`.
+*   `end_line` (integer, optional): 1-based line number to stop reading at (inclusive). When provided, limits the response to the range between `start_line` and `end_line`.
+*   `max_lines` (integer, optional): Maximum number of lines to return (capped at 2000). Useful for pagination when `end_line` is not specified.
+*   `encoding` (string, optional): Text encoding to use when reading the file. Defaults to `utf-8` with replacement for invalid bytes.
 
 **Responses:**
 
 *   On success, the device will respond with a [`file_read_response`](#file_read_response) event.
 *   On error, a generic [`error`](#error) event is sent.
 
+### `file_search`
+
+Searches for text matches within files beneath a given root directory. Handled by [`file_search`](./file_handlers.py).
+
+**Payload Fields:**
+
+*   `root_path` (string, mandatory): The absolute path that acts as the search root (typically a project folder).
+*   `query` (string, mandatory): The search query. Treated as plain text unless `regex=true`.
+*   `match_case` (boolean, optional): When `true`, performs a case-sensitive search. Defaults to `false`.
+*   `regex` (boolean, optional): When `true`, interprets `query` as a regular expression. Defaults to `false`.
+*   `whole_word` (boolean, optional): When `true`, matches only whole words. Works with both plain text and regex queries.
+*   `include_patterns` (array[string], optional): Glob patterns that files must match to be included (e.g., `["src/**/*.py"]`).
+*   `exclude_patterns` (array[string], optional): Glob patterns for files/directories to skip (e.g., `["**/tests/**"]`).
+*   `include_hidden` (boolean, optional): When `true`, includes hidden files and folders. Defaults to `false`.
+*   `max_results` (integer, optional): Maximum number of match entries to return (capped at 500). Defaults to `40`.
+*   `max_matches_per_file` (integer, optional): Maximum number of matches to return per file (capped at 50). Defaults to `5`.
+*   `max_file_size` (integer, optional): Maximum file size in bytes to scan (defaults to 1 MiB).
+*   `max_line_length` (integer, optional): Maximum number of characters to return per matching line (defaults to `200`).
+
+**Default Behaviour:**
+
+* Binary files and large vendor/static directories (e.g., `node_modules`, `dist`, `static`) are skipped automatically unless custom `exclude_patterns` are provided.
+* Only common source/text extensions are scanned by default (override with `include_patterns` to widen the scope).
+* Searches stop after 10 seconds, respecting both per-file and global match limits to avoid oversized responses.
+
+**Responses:**
+
+*   On success, the device will respond with a [`file_search_response`](#file_search_response) event containing the matches.
+*   On error, a generic [`error`](#error) event is sent.
+
 ### `file_write`
 
 Writes content to a file. Handled by [`file_write`](./file_handlers.py).
@@ -335,6 +419,57 @@ Writes content to a file. Handled by [`file_write`](./file_handlers.py).
 **Responses:**
 
 *   On success, the device will respond with a [`file_write_response`](#file_write_response) event.
+
+### `file_apply_diff`
+
+Apply one or more unified diff hunks to local files. Handled by [`file_apply_diff`](./diff_handlers.py).
+
+**Request Payload:**
+
+```json
+{
+  "cmd": "file_apply_diff",
+  "diff": "<unified diff string>",
+  "base_path": "<optional base path for relative diff entries>",
+  "project_id": "<server project UUID>",
+  "source_client_session": "<originating session/channel>"
+}
+```
+
+**Behavior:**
+
+* `diff` must be standard unified diff text (like `git diff` output). Multiple files per diff are supported.
+* If `base_path` is omitted the handler will attempt to derive the active project root from `source_client_session`, falling back to the device working directory.
+* Each file hunk is validated before writing; context mismatches or missing files return per-file errors without aborting the rest.
+* `/dev/null` entries are interpreted as file creations/deletions.
+* Inline directives are also supported on their own lines. Use `@@delete:relative/path.py@@` to delete a file directly or `@@move:old/path.py -> new/path.py@@` (alias `@@rename:...@@`) to move/rename a file without crafting a diff. Directives are evaluated before the diff hunks and must point to files inside the project base.
+
+*   On completion the device responds with [`file_apply_diff_response`](#file_apply_diff_response).
+*   On error, a generic [`error`](#error) event is sent.
+
+### `file_preview_diff`
+
+Validate one or more unified diff hunks and render an HTML preview without mutating any files. Handled by [`file_preview_diff`](./diff_handlers.py).
+
+**Request Payload:**
+
+```json
+{
+  "cmd": "file_preview_diff",
+  "diff": "<unified diff string>",
+  "base_path": "<optional base path for relative diff entries>",
+  "request_id": "req_123456"
+}
+```
+
+**Behavior:**
+
+* Reuses the same parser as `file_apply_diff`, so invalid hunks surface the same errors.
+* Produces HTML snippets per file using the device-side renderer. No files are modified.
+* Inline directives (`@@delete:...@@`, `@@move:src -> dest@@`) use the same syntax as `file_apply_diff`. The handler validates them up front and includes them in the preview output so the user can see deletions or moves before clicking “Apply”.
+* Returns immediately with an error payload if preview generation fails.
+
+*   On completion the device responds with [`file_preview_diff_response`](#file_preview_diff_response).
 *   On error, a generic [`error`](#error) event is sent.
 
 ### `directory_list`
@@ -345,6 +480,8 @@ Lists the contents of a directory. Handled by [`directory_list`](./file_handlers
 
 *   `path` (string, optional): The path to the directory to list. Defaults to the current directory.
 *   `show_hidden` (boolean, optional): Whether to include hidden files in the listing. Defaults to `false`.
+*   `limit` (integer, optional): Maximum number of entries to return (defaults to “all”). Values above 1000 are clamped to 1000.
+*   `offset` (integer, optional): Number of entries to skip before collecting results (defaults to `0`).
 
 **Responses:**
 
@@ -750,6 +887,22 @@ The `data` field contains the exact bytes output by the terminal process, decode
 
 **Security Note**: The `device_id` field is automatically injected by the server based on the authenticated connection - the device cannot and should not specify its own ID. The `project_id` and `client_sessions` fields are added by the device's terminal manager for proper routing and filtering.
 
+### <a name="terminal_link_request"></a>`terminal_link_request`
+
+Signals that the active terminal session attempted to open an external URL (e.g., via `xdg-open`). The terminal environment is instrumented with the `portacode/link_capture` helper, so CLI programs that try to open a browser are captured and forwarded to connected clients for confirmation.
+
+**Event Fields:**
+
+*   `terminal_id` (string, mandatory): The UUID of the terminal session that triggered the request.
+*   `channel` (string, mandatory): Same as `terminal_id` (included for backward compatibility with raw channel routing).
+*   `url` (string, mandatory): The full URL the terminal tried to open. Clients must surface this text directly so users can verify it.
+*   `command` (string, optional): The command that attempted the navigation (e.g., `xdg-open`).
+*   `args` (array[string], optional): Arguments passed to the command, which may include safely-encoded paths or flags.
+*   `timestamp` (number, optional): UNIX epoch seconds when the capture occurred.
+*   `project_id` (string, optional): The project UUID in whose context the attempt was made.
+
+Clients receiving this event should pause and ask the user for confirmation before opening the URL, and may throttle or suppress repeated events to prevent modal storms if a CLI tool loops on the same link.
+
 ### <a name="terminal_exit"></a>`terminal_exit`
 
 Notifies the server that a terminal session has terminated. This can be due to the process ending or the session being stopped. Handled by [`terminal_start`](./terminal_handlers.py).
@@ -806,6 +959,76 @@ Provides system information in response to a `system_info` action. Handled by [`
     *   `memory` (object): Memory usage statistics.
     *   `disk` (object): Disk usage statistics.
     *   `os_info` (object): Operating system details, including `os_type`, `os_version`, `architecture`, `default_shell`, and `default_cwd`.
+    *   `user_context` (object): Information about the user running the CLI, including:
+        *   `username` (string): Resolved username (via `os.getlogin` or fallback).
+        *   `username_source` (string): Which API resolved the username.
+        *   `home` (string): Home directory detected for the CLI user.
+        *   `uid` (integer|null): POSIX UID when available.
+        *   `euid` (integer|null): Effective UID when available.
+        *   `is_root` (boolean|null): True when running as root/administrator.
+        *   `has_sudo` (boolean): Whether a `sudo` binary exists on the host.
+        *   `sudo_user` (string|null): Value of `SUDO_USER` when set.
+        *   `is_sudo_session` (boolean): True when the CLI was started via `sudo`.
+    *   `playwright` (object): Optional Playwright runtime metadata when Playwright is installed:
+        *   `installed` (boolean): True if Playwright is importable on the device.
+        *   `version` (string|null): Exact package version when available.
+        *   `browsers` (object): Browser-specific data keyed by Playwright browser names:
+            *   `<browser>` (object): Per-browser info (variants: `chromium`, `firefox`, `webkit`).
+                *   `available` (boolean): True when Playwright knows an executable path.
+                *   `executable_path` (string|null): Absolute path to the browser binary when known.
+        *   `error` (string|null): Any warning message captured while probing Playwright.
+    *   `proxmox` (object): Detection hints for Proxmox VE nodes:
+        *   `is_proxmox_node` (boolean): True when Proxmox artifacts (e.g., `/etc/proxmox-release`) exist.
+        *   `version` (string|null): Raw contents of `/etc/proxmox-release` when readable.
+        *   `infra` (object): Portacode infrastructure configuration snapshot:
+            *   `configured` (boolean): True when `setup_proxmox_infra` stored an API token.
+            *   `host` (string|null): Hostname used for the API client (usually `localhost`).
+            *   `node` (string|null): Proxmox node name that was targeted.
+            *   `user` (string|null): API token owner (e.g., `root@pam`).
+            *   `token_name` (string|null): API token identifier.
+            *   `default_storage` (string|null): Storage pool chosen for future containers.
+            *   `templates` (array[string]): Cached list of available LXC templates.
+            *   `last_verified` (string|null): ISO timestamp when the token was last validated.
+            *   `network` (object):
+                *   `applied` (boolean): True when the bridge/NAT services were successfully configured.
+                *   `message` (string|null): Informational text about the network setup attempt.
+                *   `bridge` (string): The bridge interface configured (typically `vmbr1`).
+            *   `node_status` (object|null): Status response returned by the Proxmox API when validating the token.
+    *   `portacode_version` (string): Installed CLI version returned by `portacode.__version__`.
+
+### `proxmox_infra_configured`
+
+Emitted after a successful `setup_proxmox_infra` action. The event reports the stored API token metadata, template list, and network setup status.
+
+**Event Fields:**
+
+*   `success` (boolean): True when the configuration completed.
+*   `message` (string): User-facing summary (e.g., "Proxmox infrastructure configured").
+*   `infra` (object): Same snapshot described under [`system_info`](#system_info-event) `proxmox.infra`.
+
+### <a name="clock_sync_response"></a>`clock_sync_response`
+
+Reply sent by the gateway immediately after receiving a `clock_sync_request`. Devices use this event plus the measured round-trip time to keep their local `ntp_clock` offset accurate.
+
+**Event Fields:**
+
+*   `event` (string): Always `clock_sync_response`.
+*   `server_time` (integer): Server time in milliseconds.
+*   `server_time_iso` (string, optional): ISO 8601 representation of `server_time`, useful for UI dashboards.
+*   `server_receive_time` (integer, optional): Timestamp when the gateway received the sync request.
+*   `server_send_time` (integer, optional): Timestamp when the gateway replied; used to compute a midpoint for latency compensation.
+*   `request_id` (string, optional): Mirrors the request's `request_id`.
+
+### `update_portacode_response`
+
+Reports the result of an `update_portacode_cli` action. Handled by [`update_portacode_cli`](./update_handler.py).
+
+**Event Fields:**
+
+*   `success` (boolean, mandatory): Whether the update operation was successful.
+*   `message` (string, optional): Success message when update completes.
+*   `error` (string, optional): Error message when update fails.
+*   `restart_required` (boolean, optional): Indicates if process restart is required (always true for successful updates).
 
 ### <a name="file_read_response"></a>`file_read_response`
 
@@ -814,8 +1037,39 @@ Returns the content of a file in response to a `file_read` action. Handled by [`
 **Event Fields:**
 
 *   `path` (string, mandatory): The path of the file that was read.
-*   `content` (string, mandatory): The content of the file.
-*   `size` (integer, mandatory): The size of the file in bytes.
+*   `content` (string, mandatory): The file content returned (may be a slice when pagination parameters are used).
+*   `size` (integer, mandatory): The total size of the file in bytes.
+*   `total_lines` (integer, optional): Total number of lines detected in the file.
+*   `returned_lines` (integer, optional): Number of lines included in `content`.
+*   `start_line` (integer, optional): The first line number included in the response (if any lines were returned).
+*   `requested_start_line` (integer, optional): The requested starting line supplied in the command.
+*   `end_line` (integer, optional): The last line number included in the response.
+*   `has_more_before` (boolean, optional): Whether there is additional content before the returned range.
+*   `has_more_after` (boolean, optional): Whether there is additional content after the returned range.
+*   `encoding` (string, optional): Encoding that was used while reading the file.
+
+### <a name="file_search_response"></a>`file_search_response`
+
+Returns aggregated search results in response to a `file_search` action. Handled by [`file_search`](./file_handlers.py).
+
+**Event Fields:**
+
+*   `root_path` (string, mandatory): The root directory that was searched.
+*   `query` (string, mandatory): The query string that was used.
+*   `match_case` (boolean, mandatory): Indicates if the search was case sensitive.
+*   `regex` (boolean, mandatory): Indicates if the query was interpreted as a regular expression.
+*   `whole_word` (boolean, mandatory): Indicates if the search matched whole words only.
+*   `include_patterns` (array[string], mandatory): Effective include glob patterns.
+*   `exclude_patterns` (array[string], mandatory): Effective exclude glob patterns.
+*   `matches` (array, mandatory): List of match objects containing `relative_path`, `path`, `line_number`, `line`, `match_spans` `[start, end]`, `match_count`, and `line_truncated` (boolean).
+*   `matches_returned` (integer, mandatory): Number of match entries returned (length of `matches`).
+*   `total_matches` (integer, mandatory): Total number of matches found while scanning.
+*   `files_scanned` (integer, mandatory): Count of files inspected.
+*   `truncated` (boolean, mandatory): Indicates if additional matches exist beyond those returned.
+*   `truncated_count` (integer, optional): Number of matches that were omitted due to truncation limits.
+*   `max_results` (integer, mandatory): Maximum number of matches requested.
+*   `max_matches_per_file` (integer, mandatory): Maximum matches requested per file.
+*   `errors` (array[string], optional): Non-fatal errors encountered during scanning (e.g., unreadable files).
 
 ### <a name="file_write_response"></a>`file_write_response`
 
@@ -827,6 +1081,45 @@ Confirms that a file has been written successfully in response to a `file_write`
 *   `bytes_written` (integer, mandatory): The number of bytes written to the file.
 *   `success` (boolean, mandatory): Indicates whether the write operation was successful.
 
+### <a name="file_apply_diff_response"></a>`file_apply_diff_response`
+
+Reports the outcome of a [`file_apply_diff`](#file_apply_diff) action.
+
+**Event Fields:**
+
+* `event`: Always `"file_apply_diff_response"`.
+* `success`: Boolean indicating whether all hunks succeeded.
+* `status`: `"success"`, `"partial_failure"`, or `"failed"`.
+* `base_path`: Absolute base path used for relative diff entries.
+* `files_changed`: Number of files successfully updated.
+* `results`: Array containing one object per file with:
+  * `path`: Absolute path on the device.
+  * `status`: `"applied"` or `"error"`.
+  * `action`: `"created"`, `"modified"`, or `"deleted"` (present for successes).
+  * `bytes_written`: Bytes written for the file (0 for deletes).
+  * `error`: Error text when the patch failed for that file.
+  * `line`: Optional line number hint for mismatches.
+
+The response is emitted even if some files fail so the caller can retry with corrected diffs.
+
+### <a name="file_preview_diff_response"></a>`file_preview_diff_response`
+
+Reports the outcome of a [`file_preview_diff`](#file_preview_diff) action.
+
+**Event Fields:**
+
+* `event`: Always `"file_preview_diff_response"`.
+* `success`: Boolean indicating whether all previews rendered successfully.
+* `status`: `"success"`, `"partial_failure"`, or `"failed"`.
+* `base_path`: Absolute base path used for relative paths.
+* `previews`: Array containing one entry per file with:
+  * `path`: Absolute path hint (used for syntax highlighting).
+  * `relative_path`: Relative project path if known.
+  * `status`: `"ready"` or `"error"`.
+  * `html`: Rendered diff snippet (when status is `"ready"`).
+  * `error`: Error text (when status is `"error"`).
+* `error`: Optional top-level error string when the entire preview failed (e.g., diff parse error).
+
 ### <a name="directory_list_response"></a>`directory_list_response`
 
 Returns the contents of a directory in response to a `directory_list` action. Handled by [`directory_list`](./file_handlers.py).
@@ -835,7 +1128,11 @@ Returns the contents of a directory in response to a `directory_list` action. Ha
 
 *   `path` (string, mandatory): The path of the directory that was listed.
 *   `items` (array, mandatory): A list of objects, each representing a file or directory in the listed directory.
-*   `count` (integer, mandatory): The number of items in the `items` list.
+*   `count` (integer, mandatory): The number of items returned in this response (honours `limit`/`offset`).
+*   `total_count` (integer, mandatory): Total number of entries in the directory before pagination.
+*   `offset` (integer, optional): Offset that was applied.
+*   `limit` (integer, optional): Limit that was applied (or `null` if none).
+*   `has_more` (boolean, optional): Indicates whether additional items remain beyond the returned slice.
 
 ### <a name="file_info_response"></a>`file_info_response`
 
@@ -1277,4 +1574,4 @@ Sent by the server to clients to provide initial device list snapshot.
 
 **Event Fields:**
 
-*   `devices` (array, mandatory): Array of device objects with status information
+*   `devices` (array, mandatory): Array of device objects with status information

portacode/connection/handlers/__init__.py

@@ -23,8 +23,10 @@ from .file_handlers import (
     FileCreateHandler,
     FolderCreateHandler,
     FileRenameHandler,
+    FileSearchHandler,
     ContentRequestHandler,
 )
+from .diff_handlers import FileApplyDiffHandler, FilePreviewDiffHandler
 from .project_state_handlers import (
     ProjectStateFolderExpandHandler,
     ProjectStateFolderCollapseHandler,
@@ -38,6 +40,8 @@ from .project_state_handlers import (
     ProjectStateGitRevertHandler,
     ProjectStateGitCommitHandler,
 )
+from .update_handler import UpdatePortacodeHandler
+from .proxmox_infra import ConfigureProxmoxInfraHandler
 
 __all__ = [
     "BaseHandler",
@@ -49,6 +53,7 @@ __all__ = [
     "TerminalStopHandler",
     "TerminalListHandler",
     "SystemInfoHandler",
+    "ConfigureProxmoxInfraHandler",
     # File operation handlers (optional - register as needed)
     "FileReadHandler",
     "FileWriteHandler", 
@@ -58,7 +63,10 @@ __all__ = [
     "FileCreateHandler",
     "FolderCreateHandler",
     "FileRenameHandler",
+    "FileSearchHandler",
     "ContentRequestHandler",
+    "FileApplyDiffHandler",
+    "FilePreviewDiffHandler",
     # Project state handlers
     "ProjectStateFolderExpandHandler",
     "ProjectStateFolderCollapseHandler",
@@ -71,4 +79,5 @@ __all__ = [
     "ProjectStateGitUnstageHandler",
     "ProjectStateGitRevertHandler",
     "ProjectStateGitCommitHandler",
-] 
+    "UpdatePortacodeHandler",
+]