@rse/ase 2.0.3 → 2.0.4

package/dst/man/ase-mcp.md

@@ -0,0 +1,102 @@
+# ase-mcp(1) -- Bridge Stdio MCP to the Per-Project Service
+
+## SYNOPSIS
+
+`ase mcp`
+\[`-h`|`--help`\]
+
+## DESCRIPTION
+
+**ase mcp** is a Model-Context-Protocol (MCP) server speaking the
+stdio transport: it accepts MCP messages on standard input, forwards
+them to the per-project background service of `ase-service`(1) via the
+Streamable HTTP transport (`http://127.0.0.1:`*port*`/mcp`), and writes
+the responses to standard output.
+
+It is configured as the stdio MCP server `ase` of the *ASE* plugin in
+the agent tool and is not intended to be invoked directly by end users.
+All log messages go to standard error (or to the file of the global
+`--log-file` option), as standard output carries the MCP protocol.
+
+On start, the service of the project is probed and auto-started (via
+`ase service start`) if it is not running yet. The bridge then lives as
+long as its standard input is open, and is robust against a vanishing
+service:
+
+- Messages arriving while no service connection exists are buffered
+  (up to 100 messages, dropping the oldest ones on overflow) and sent
+  once the connection is (re-)established.
+
+- On a lost or refused connection, the service is auto-started again
+  and the connection is re-established, with a delay growing from 0.5
+  up to 10 seconds between the attempts.
+
+- Every 30 seconds, the service is probed, and a vanished service
+  triggers the same reconnect.
+
+Under *GitHub Copilot CLI* (detected by the environment variable
+`COPILOT_PLUGIN_ROOT`), the MCP server is started in the plugin
+installation directory instead of the project. Hence, the bridge first
+answers all MCP messages in-process through the same set of MCP tools
+the service provides (covering the MCP handshake and the tool listing),
+holds back all tool calls, and waits until the `SessionStart` hook (see
+`ase-hook`(1)) recorded the project directory of the session (with id
+`COPILOT_AGENT_SESSION_ID`).
+
+It then switches into this directory, starts or connects the service
+of the project there, and forwards the held tool calls. If no project
+directory is recorded within 30 seconds of the first held tool call, it
+falls back to the current directory.
+
+The service provides the `ase_*` MCP tools of the skills, e.g.,
+`ase_ping`, `ase_config_get`, `ase_config_set`, `ase_config_delete`,
+`ase_config_list`, `ase_state_get`, `ase_state_set`,
+`ase_state_delete`, `ase_kv_get`, `ase_kv_set`, `ase_kv_delete`,
+`ase_kv_clear`, `ase_kv_batch`, the `ase_task_*` tools, `ase_artifact_list`,
+`ase_artifact_name`, `ase_specbook_lint`, `ase_specbook_export`,
+`ase_diagram`, `ase_worktree_path`, `ase_mint`, `ase_text_metric`,
+`ase_getopt`, `ase_markdown_prepare`, `ase_timestamp`, `ase_sleep`,
+`ase_compat`, `ase_component_info`, and `ase_decision_matrix`.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## ENVIRONMENT
+
+- `COPILOT_PLUGIN_ROOT`, `COPILOT_AGENT_SESSION_ID`:
+  Exported by *GitHub Copilot CLI* to its MCP servers. When both are
+  set (and the session id matches `[A-Za-z0-9._-]+`), the service is
+  deferred until the project directory of the session is known (see
+  **DESCRIPTION**).
+
+## FILES
+
+- `.ase/service.yaml`:
+  The persisted port of the per-project service.
+
+- *per-user state directory*`/session/`*id*`/state.yaml`:
+  The internal session state, from which the project directory
+  (`basedir`) recorded by the `SessionStart` hook is read under *GitHub
+  Copilot CLI*.
+
+## EXIT STATUS
+
+`0` once standard input is closed, `1` if the service cannot be
+started initially.
+
+## EXAMPLES
+
+```sh
+# register the bridge manually as an MCP server in Claude Code
+$ claude mcp add ase -- ase mcp
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-service`(1), `ase-hook`(1), `ase-setup`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-service-log.md

@@ -0,0 +1,59 @@
+# ase-service-log(1) -- Show the Log of the Background Service
+
+## SYNOPSIS
+
+`ase service log`
+\[`-h`|`--help`\]
+\[`-f`|`--follow`\]
+\[`-n`|`--lines` *n*\]
+
+## DESCRIPTION
+
+**ase service log** shows the log file `.ase/service.log` of the
+per-project background service of *ASE* (see `ase-service`(1)) on
+standard output: by default the entire file, else its last lines
+only. If no log file exists, nothing is shown and the command exits
+with status `0`.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-f`|`--follow`\]:
+  After showing the last *n* lines (default: `10`), keep following the
+  file in the style of `tail -f` and show all newly appended lines,
+  until interrupted (e.g., via `CTRL+C`), even once the service has
+  stopped. When the log is trimmed on a service start, following
+  continues at the new end of the file.
+
+- \[`-n`|`--lines` *n*\]:
+  Show the last *n* non-empty lines only, where *n* has to be a
+  positive integer (default: all lines, or `10` with `--follow`).
+
+## FILES
+
+- `.ase/service.log`:
+  The log of the detached service.
+
+## EXIT STATUS
+
+`0` on success, `1` on an invalid *n* or an unreadable log file.
+
+## EXAMPLES
+
+```sh
+# show the last 50 log lines
+$ ase service log -n 50
+
+# follow the log
+$ ase service log -f
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-service`(1), `ase-service-start`(1), `tail`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-service-send.md

@@ -0,0 +1,60 @@
+# ase-service-send(1) -- Send a Command to the Background Service
+
+## SYNOPSIS
+
+`ase service send`
+\[`-h`|`--help`\]
+*cmd*
+
+## DESCRIPTION
+
+**ase service send** dispatches the command token *cmd* to the
+per-project background service of *ASE* (see `ase-service`(1)) via an
+HTTP `POST /command` request with the JSON body `{ "command":` *cmd*
+`}`, and prints the raw response body (a JSON object) on standard
+output. If the service is not running, it is auto-started first (like
+`ase service start`).
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## ARGUMENTS
+
+- *cmd*:
+  The command token to dispatch. The service currently understands:
+
+    - `ping`:
+      Answer with `{"ok":true,"pong":true}`.
+    - `status`:
+      Answer with the service identity, i.e., `ok`, the project id
+      `projectId`, the `port`, and the uptime `uptimeMs` in
+      milliseconds.
+
+  Any other token is answered with an `unknown command` error (HTTP
+  status `400`).
+
+## EXIT STATUS
+
+`0` if the service answered with a success status, `1` if it answered
+with an error status (e.g., for an unknown *cmd*), or if it could not
+be started or reached.
+
+## EXAMPLES
+
+```sh
+$ ase service send ping
+{"ok":true,"pong":true}
+
+$ ase service send status
+{"ok":true,"projectId":"ase","port":42817,"uptimeMs":723456}
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-service`(1), `ase-service-status`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-service-start.md

@@ -0,0 +1,93 @@
+# ase-service-start(1) -- Start the Per-Project Background Service
+
+## SYNOPSIS
+
+`ase service start`
+\[`-h`|`--help`\]
+\[`-f`|`--foreground`\]
+
+## DESCRIPTION
+
+**ase service start** starts the per-project background HTTP service
+of *ASE* (see `ase-service`(1)) for the project of the current working
+directory.
+
+If a service of this project already answers on the port persisted in
+`.ase/service.yaml`, the command just reports `service: already running
+on port` *port* and exits with status `0`. Otherwise, it allocates the
+preferred port `project.service.port` (see `ase-config`(1)), if
+configured and free, else (with a warning, if configured) a fresh
+random free port out of the range `42000`..`44000` (trying up to 20
+candidates), spawns the service as a detached background process
+(with its standard output and standard error appended to
+`.ase/service.log`, trimmed to its last 2000 lines beforehand if larger
+than 1 MB), and probes its readiness for up to 5 seconds.
+
+Once ready, the service persists its port into `.ase/service.yaml`,
+and the command reports `service: started on port` *port*. If the
+spawned service exits during its startup, does not become ready in
+time, or loses its port to a foreign listener, the attempt is aborted
+(killing the process) and retried with a new port, up to three attempts
+in total, after which the command fails with the reason and the last
+20 lines of the log.
+
+The detached service adopts the log level of the global `--log-level`
+option of this command, e.g., `ase --log-level debug service start`
+logs the full MCP traffic. It stops itself after 30 minutes without any
+request (but never while a request is in flight or while it holds open
+AI usage windows), on `ase service stop`, and removes its port from
+`.ase/service.yaml` again.
+
+Usually, the service does not have to be started explicitly, as the
+MCP bridge `ase mcp`, `ase service send`, and the hooks start it on
+demand.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-f`|`--foreground`\]:
+  Run the service in the current process instead, on a port allocated
+  as above, logging to the terminal (resp. the global `--log-file`) instead
+  of `.ase/service.log` and without the idle timeout, until it is
+  interrupted (via `SIGINT`, e.g., `CTRL+C`, `SIGTERM`, `SIGHUP`, or
+  `SIGQUIT`) or stopped via `ase service stop`. A service of this
+  project already running is an error in this mode.
+
+## FILES
+
+- `.ase/service.yaml`:
+  The persisted port of the running service.
+
+- `.ase/service.log`:
+  The log of the detached service.
+
+- `.ase/.gitignore`:
+  The self-ignoring Git ignore file covering the machine-local runtime
+  files, created if missing.
+
+## EXIT STATUS
+
+`0` if the service was started or is already running (resp., in the
+foreground, once it was stopped), `1` if it could not be started, or,
+with `--foreground`, if it is already running.
+
+## EXAMPLES
+
+```sh
+# start the service in the background
+$ ase service start
+
+# run the service in the foreground for debugging
+$ ase --log-level debug service start --foreground
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-service`(1), `ase-service-status`(1),
+`ase-service-stop`(1), `ase-service-log`(1), `ase-config`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-service-status.md

@@ -0,0 +1,58 @@
+# ase-service-status(1) -- Report Whether the Background Service Is Running
+
+## SYNOPSIS
+
+`ase service status`
+\[`-h`|`--help`\]
+
+## DESCRIPTION
+
+**ase service status** reports whether the per-project background
+service of *ASE* (see `ase-service`(1)) is running. It probes the port
+persisted in `.ase/service.yaml` via an HTTP `OPTIONS /` request and
+verifies that the responding service belongs to the current project
+(by its project id). It prints one of the following lines on standard
+output:
+
+- `service: running on port` *port* `(uptime:` *duration*`)`:
+  A service of this project is running.
+
+- `service: not running (no port configured)`:
+  No port is persisted in `.ase/service.yaml`.
+
+- `service: not running (port` *port* `not responding)`:
+  Nothing listens on the persisted port.
+
+- `service: not running (port` *port* `in use by foreign service)`:
+  The persisted port is answered by something else, e.g., the service
+  of another project.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## FILES
+
+- `.ase/service.yaml`:
+  The persisted port of the service.
+
+## EXIT STATUS
+
+`0` if the service of the project is running, else `1`.
+
+## EXAMPLES
+
+```sh
+$ ase service status
+service: running on port 42817 (uptime: 12 minutes 3.4 seconds)
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-service`(1), `ase-service-start`(1),
+`ase-service-stop`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-service-stop.md

@@ -0,0 +1,52 @@
+# ase-service-stop(1) -- Stop the Background Service
+
+## SYNOPSIS
+
+`ase service stop`
+\[`-h`|`--help`\]
+
+## DESCRIPTION
+
+**ase service stop** stops the per-project background service of
+*ASE* (see `ase-service`(1)) via an HTTP `POST /stop` request to the
+port persisted in `.ase/service.yaml`, and removes the persisted port
+(and the file, if it becomes empty). This also stops a service running
+in the foreground via `ase service start --foreground`. On stop, the
+service persists the journal of its AI usage windows, so no usage is
+lost.
+
+If no port is persisted, or nothing listens on the persisted port, an
+informational message is logged, a stale port is removed, and the
+command exits with status `0`. If the persisted port is answered by a
+foreign service (e.g., the service of another project), it is left
+alone and the command exits with status `1`.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## FILES
+
+- `.ase/service.yaml`:
+  The persisted port of the service, cleared on stop.
+
+## EXIT STATUS
+
+`0` if the service was stopped or was not running, `1` if the port is
+in use by a foreign service or the stop request failed.
+
+## EXAMPLES
+
+```sh
+$ ase service stop
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-service`(1), `ase-service-start`(1),
+`ase-service-status`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-service.md

@@ -0,0 +1,124 @@
+# ase-service(1) -- Manage the Per-Project Background Service
+
+## SYNOPSIS
+
+`ase service`
+\[`-h`|`--help`\]
+*command*
+\[*options* \[...\]\]
+\[*args* \[...\]\]
+
+`ase service start` \[`-f`|`--foreground`\]
+
+`ase service status`
+
+`ase service send` *cmd*
+
+`ase service log` \[`-f`|`--follow`\] \[`-n`|`--lines` *n*\]
+
+`ase service stop`
+
+## DESCRIPTION
+
+**ase service** manages the per-project background HTTP service of
+*ASE*. The service is bound to `127.0.0.1` on the preferred port
+`project.service.port`, if configured and available, else on a random
+port out of the range `42000`..`44000`, which is persisted in
+`.ase/service.yaml` of the project, and logs into `.ase/service.log`. It is identified by the id
+of the project (`project.id`, else derived from the project root), so a
+port answered by the service of another project counts as a *foreign*
+service.
+
+The service provides:
+
+- the MCP endpoint `/mcp` (Streamable HTTP), serving the `ase_*` MCP
+  tools of the skills, bridged into the agent tool via `ase-mcp`(1),
+  which auto-starts the service on demand,
+- the command endpoint `/command` (see `ase-service-send`(1)) and the
+  stop endpoint `/stop`,
+- the endpoints `/usage/*` of the AI usage accounting of the task
+  assignments (see `ase-task-assign`(1)), plus, while
+  `telemetry.enabled` is `true`, the attempt to hold the per-user OTLP
+  ingress on `127.0.0.1:`*port* (`telemetry.service.port`, default
+  `44318`), routing the received records to the service of the project
+  owning the session (see `ase-setup-telemetry`(1)),
+- the web task board of `ase task board --web` (see
+  `ase-task-board`(1)).
+
+The service accepts requests with a loopback `Host` header only, to
+defeat DNS rebinding attacks from browser pages. A detached service
+stops itself after 30 minutes without any request, but never while a
+request is in flight or while it holds open AI usage windows.
+
+Without a *command*, the usage information is shown and the command
+exits with status `1`.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## COMMANDS
+
+- `start` \[`-f`|`--foreground`\]:
+  Start the service in the background (or run it in the foreground).
+  See `ase-service-start`(1).
+
+- `status`:
+  Report whether the service is running. See `ase-service-status`(1).
+
+- `send` *cmd*:
+  Send a command to the service. See `ase-service-send`(1).
+
+- `log` \[`-f`|`--follow`\] \[`-n`|`--lines` *n*\]:
+  Show the log of the service. See `ase-service-log`(1).
+
+- `stop`:
+  Stop the service. See `ase-service-stop`(1).
+
+## FILES
+
+- `.ase/service.yaml`:
+  The per-project service state (the `port` of the running service),
+  removed again once the service stopped.
+
+- `.ase/service.log`:
+  The standard output and standard error of the detached service,
+  appended to. As the service inherits the file descriptor for its
+  entire lifetime, the file cannot be rotated while the service runs,
+  and instead is trimmed down to its last 2000 lines whenever a
+  service is started on a file larger than 1 MB.
+
+  Routine MCP traffic (session handshakes, notifications, and stream
+  opens) is logged at level `debug` only, and the arguments of the
+  logged MCP tool calls are cut at 200 characters.
+
+- `.ase/.gitignore`:
+  The self-ignoring Git ignore file covering the machine-local runtime
+  files, created on the first start if missing.
+
+## EXIT STATUS
+
+`0` on success, `1` on any error (including a missing *command*). See
+the individual commands for details.
+
+## EXAMPLES
+
+```sh
+# start the service with the full MCP traffic logged
+$ ase --log-level debug service start
+
+# check the service and follow its log
+$ ase service status
+$ ase service log -f
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-service-start`(1), `ase-service-status`(1),
+`ase-service-send`(1), `ase-service-log`(1), `ase-service-stop`(1),
+`ase-mcp`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-setup-disable.md

@@ -0,0 +1,67 @@
+# ase-setup-disable(1) -- Disable the ASE Plugin in an Agent Tool
+
+## SYNOPSIS
+
+`ase setup disable`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+\[`-s`|`--scope` *scope*\]
+
+## DESCRIPTION
+
+**ase setup disable** disables the installed *ASE* plugin in the agent
+tool selected by `--tool` without uninstalling it, so it can be
+enabled again via `ase setup enable`. It requires the CLI of the
+agent tool to be found in `$PATH`.
+
+For *Anthropic Claude Code CLI*, the plugin is disabled via `claude
+plugin disable ase@ase` (with `--scope` *scope* for a non-`user`
+scope), which keeps its registration under `enabledPlugins` (with the
+value `false`). As *GitHub Copilot CLI* and *OpenAI Codex CLI* have no
+plugin disable command, the plugin is uninstalled there instead
+(`copilot plugin uninstall ase@ase`, resp. `codex plugin remove
+ase@ase`, retried up to three times), while its plugin marketplace
+stays registered.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-t`|`--tool` *tool*\]:
+  Select the target agent tool: `claude`, `copilot`, or `codex`
+  (default: `$ASE_TOOL`, else `claude`).
+
+- \[`-s`|`--scope` *scope*\]:
+  Select the plugin installation scope: `user`, `project`, or
+  `local`. The default is auto-detected from the existing
+  installation: the scopes `local`, `project`, and `user` are probed
+  in this order, and the first one whose settings file registers the
+  plugin `ase@ase` under `enabledPlugins` is taken, falling back to
+  `user`. Only supported for `--tool claude`; a non-`user` scope for
+  `copilot` or `codex` fails with an error.
+
+## ENVIRONMENT
+
+- `ASE_TOOL`:
+  The default of `--tool`.
+
+## EXIT STATUS
+
+`0` on success, `1` on any error.
+
+## EXAMPLES
+
+```sh
+# temporarily disable the ASE plugin in Anthropic Claude Code CLI
+$ ase setup disable
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-setup`(1), `ase-setup-enable`(1),
+`ase-setup-uninstall`(1), `ase-setup-status`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-setup-enable.md

@@ -0,0 +1,66 @@
+# ase-setup-enable(1) -- Enable the ASE Plugin in an Agent Tool
+
+## SYNOPSIS
+
+`ase setup enable`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+\[`-s`|`--scope` *scope*\]
+
+## DESCRIPTION
+
+**ase setup enable** enables the already installed *ASE* plugin in the
+agent tool selected by `--tool`, e.g., after it was disabled via `ase
+setup disable`. It requires the CLI of the agent tool to be found in
+`$PATH`.
+
+For *Anthropic Claude Code CLI*, the plugin is enabled via `claude
+plugin enable ase@ase` (with `--scope` *scope* for a non-`user`
+scope). As *GitHub Copilot CLI* and *OpenAI Codex CLI* have no plugin
+enable command, the plugin is (re-)installed there instead (`copilot
+plugin install ase@ase`, resp. `codex plugin add ase@ase`, retried up
+to three times), which requires the *ASE* plugin marketplace to be
+still registered (see `ase-setup-install`(1)).
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-t`|`--tool` *tool*\]:
+  Select the target agent tool: `claude`, `copilot`, or `codex`
+  (default: `$ASE_TOOL`, else `claude`).
+
+- \[`-s`|`--scope` *scope*\]:
+  Select the plugin installation scope: `user`, `project`, or
+  `local`. The default is auto-detected from the existing
+  installation: the scopes `local`, `project`, and `user` are probed
+  in this order, and the first one whose settings file registers the
+  plugin `ase@ase` under `enabledPlugins` (enabled or disabled) is
+  taken, falling back to `user`. Only supported for `--tool claude`;
+  a non-`user` scope for `copilot` or `codex` fails with an error.
+
+## ENVIRONMENT
+
+- `ASE_TOOL`:
+  The default of `--tool`.
+
+## EXIT STATUS
+
+`0` on success, `1` on any error.
+
+## EXAMPLES
+
+```sh
+# re-enable the ASE plugin in Anthropic Claude Code CLI
+$ ase setup enable
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-setup`(1), `ase-setup-disable`(1),
+`ase-setup-status`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>