@procedures/mark 0.22.1 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # @procedures/mark
 
+## 0.24.0
+
+### Minor Changes
+
+- 4261f65: Breaking: each `mark` command starts under `run()` of `@mark1russell7/service` (CLI-26, decision D17). The cold mode runs the procedures host of the CLI server in its own process. The runner owns the signals, the stop in stages and the exit. Thus the exit codes of a signal change. The release before this one marked the old behaviors as deprecated.
+  
+  The new behavior:
+  
+  - Each `mark` command that runs a procedure is a service of one request, with the profile `ephemeral`. `mark` has no signal handler and no `process.exit` of its own in this path. `interruptSignal()` is gone.
+  - The cold mode (no CLI server in this folder, or `--local`): the host has the same registry and policy as `mark --server` (`markHostOptions()`), and no listener, port, token or lockfile. The client sends each call through the local face of the host.
+  - `localFace()` of `@procedures/peer` is new. It gives a face factory and a transport of `@procedures/client`. A `Client` on the transport sends its calls to the host of the same process, through the request tracking of the service, with `LOCAL_CREDENTIALS`.
+  - A first Ctrl-C starts the stop, and the drain aborts the call at once.
+  - The warm mode: the call to the CLI server gets the abort signal. A Ctrl-C aborts the call on the server too. Before, the signal ended `mark`, and the server continued the call.
+  - After the command, the runner ends the process with the exit code of the command. A timer or a socket that a procedure left open does not keep the process alive.
+  - `run()` and `main()` of `@procedures/mark` get the optional options `run` (the options of `run()`: the process port and the clock) and `ownsProcess`. The bin gives `ownsProcess: true`. Without it, a program keeps its process: no signal handler, and the exit code goes to `process.exitCode`.
+  - `CliContext` gets the optional field `registry`. `executeArgs()` does not use `ctx.client` for a command any more.
+  - A program that calls `run()` or `executeArgs()` without a port, and the REPL (`mark -i`), get no signal handler for a command.
+  
+  The exit codes, in the cold mode and in the warm mode:
+  
+  | Event | Before | From this release |
+  |---|---|---|
+  | The command ends without a failure | 0 | 0 |
+  | The command fails | 1 | 1 |
+  | The first Ctrl-C, cold mode | 1 | 130 |
+  | The first Ctrl-C, warm mode | the signal ended the process (the shell showed 130) | 130 |
+  | `SIGTERM` | the signal ended the process (the shell showed 143) | 143 |
+  | A second signal during the stop, cold mode | 130 | 1 |
+  
+  A cold `mark server create` keeps its peer only until the end of the command. Before, the peer kept the process alive after the command.
+  
+  Migration:
+  
+  - A script that reads the exit code of an interrupted `mark` command: read 130 for a Ctrl-C, also in the cold mode. Read 1 for a second signal.
+  - A script that starts `mark server create` as a server in the foreground: start `mark --server` or `procedure-server` in its place.
+  - A program that calls `run()`, `main()` or `executeArgs()` of `@procedures/mark`: no change. It keeps its process. Give `ownsProcess: true` to give the process to the runner, as the bin does.
+  - The site: no change. It does not start `mark`.
+  - MiniMongo: no change. Its dev host starts through `runProcedureHost()`, not through `mark`.
+  - Graph: no change. It does not start `mark`.
+  - jarvis: no change, unless a script of jarvis reads the exit code of an interrupted `mark` command. Then apply the first step.
+
+### Patch Changes
+
+- Updated dependencies [4261f65]
+  - @procedures/peer@0.24.0
+  - @procedures/server@0.24.0
+  - @procedures/client@0.24.0
+  - @procedures/cli-run@0.24.0
+  - @procedures/lib@0.24.0
+  - @procedures/pnpm@0.24.0
+  - @procedures/procedure@0.24.0
+  - @procedures/shell@0.24.0
+  - @procedures/vitest@0.24.0
+  - @procedures/mcp-dev-tools@0.24.0
+
+## 0.23.0
+
+### Patch Changes
+
+- Updated dependencies [f20beb1]
+- Updated dependencies [71091a5]
+  - @procedures/client@0.23.0
+  - @procedures/peer@0.23.0
+  - @procedures/mcp-dev-tools@0.23.0
+  - @procedures/cli-run@0.23.0
+  - @procedures/lib@0.23.0
+  - @procedures/pnpm@0.23.0
+  - @procedures/procedure@0.23.0
+  - @procedures/shell@0.23.0
+  - @procedures/vitest@0.23.0
+  - @procedures/server@0.23.0
+
 ## 0.22.1
 
 ### Patch Changes

package/README.md

@@ -45,7 +45,7 @@ graph TB
 
     subgraph "Execution Layer"
         REGISTRY[Procedure Registry]
-        TRANSPORT[Local Transport]
+        TRANSPORT["Local face of the host"]
         CLIENT[Client]
     end
 
@@ -145,13 +145,32 @@ The bin is `dist/bin.js`. `node dist/cli.js` also runs the CLI. Importing `@proc
 
 | Command | Host | Notes |
 |---|---|---|
-| `mark <command>` | This process | The registry has the module of each workspace package with `client.procedures`. |
+| `mark <command>` | This process (the cold mode), or the CLI server (the warm mode) | The registry has the module of each workspace package with `client.procedures`. In the two modes, the command starts under `run()` of `@mark1russell7/service`. |
 | `mark --server` | The CLI server | The same registry, on `127.0.0.1`, with a token in the lockfile. A later `mark` command in the same folder uses it. |
 | `mark serve` | The procedure server | The options of the `procedure-server` command. A package of `--procedures` resolves from the current folder, then from the folder of `mark`. A token is necessary by default. |
 | `mark mcp` | The dev-tools MCP server, over stdio | The server of Claude Code's MCP configuration. stdout holds only protocol lines, and `mark mcp --help` writes to stderr. |
 
 `mark mcp <procedure>` runs an `mcp.*` procedure (for example `mark mcp listTools`), not the server. Each host gets its policy from `hostPolicy()` of `@procedures/client`.
 
+#### The cold mode and the warm mode
+
+Each command that runs a procedure is a service of one request (CLI-26, decision D17). The runner of `@mark1russell7/service` owns the signals, the stop in stages and the exit. `mark` installs no signal handler of its own.
+
+- **The warm mode.** A CLI server (`mark --server`) of this build operates in this folder, with the same `--fs-root`. The command goes to the server over HTTP.
+- **The cold mode.** No such server operates, or the command has `--local`. The procedures host of the CLI server then operates in this process, with the same registry and policy. It has no port, no token and no lockfile.
+- **The profile.** The service has the profile `ephemeral`: no checks, no probes, and a flush of the output before the exit.
+- **Ctrl-C.** A first Ctrl-C starts the stop. The drain aborts the call at once: a shell command stops its process tree, and a stream ends. In the warm mode, the server aborts the call too. Before, the server continued it.
+- **A second Ctrl-C.** A second signal during the stop ends the process at once, with the exit code 1.
+- **The exit.** After the command, the runner ends the process with the exit code of the command. A timer or a socket that a procedure left open does not keep the process alive.
+- **The REPL.** `mark -i` starts each line in the cold mode, without the signals: the REPL keeps its process.
+
+```mermaid
+graph LR
+    CMD[mark command] --> SVC["service of the command<br/>run(), profile ephemeral"]
+    SVC -->|warm| HTTP[HttpTransport + signal] --> SERVER["CLI server<br/>runProcedureHost, daemon"]
+    SVC -->|cold| FACE["localFace()"] --> HOST["the same host<br/>in this process"]
+```
+
 #### Remote events of the hosts
 
 `mark --server` and `mark serve` always serve the procedure `events.subscribe` ([EVENTS.md](../documentation/EVENTS.md)):
@@ -234,15 +253,24 @@ A procedure reports a failure in one of three ways:
 
 For a streaming procedure, `mark` examines each item. One failed item makes the command fail.
 
-#### Deprecated: a signal during a command
+The exit codes of a command, since the MINOR of CLI-26. A signal stops a command through the runner:
+
+| Event | Cold mode | Warm mode |
+|---|---|---|
+| The command ends without a failure | 0 | 0 |
+| The command fails | 1 | 1 |
+| The first `SIGINT` (Ctrl-C) | 130 | 130 |
+| `SIGTERM` | 143 | 143 |
+| `SIGQUIT` | 131 | 131 |
+| A second signal during the stop | 1 | 1 |
 
-The MINOR of CLI-26 starts each command under `run()` of `@mark1russell7/service` (decision D17). The runner then owns the signals and the exit. These behaviors are deprecated, and that MINOR changes them:
+The cold mode is a command in this process: no CLI server operates in this folder, or the command has `--local`. The MINOR of CLI-26 changed three behaviors. The release before it marked them as deprecated:
 
-- **The first Ctrl-C in the cold mode.** A command in this process gives the exit code 1. After the change, it gives 130.
-- **A second signal.** A second Ctrl-C in the cold mode ends the process at once with the exit code 130. After the change, the exit code is 1.
-- **`mark server create` in the cold mode.** The peer of the command keeps the process alive after the command. After the change, the peer stops at the end of the command. For a server in the foreground, use `mark --server` or `procedure-server`.
+- **The first Ctrl-C in the cold mode.** Before, the aborted command gave the exit code 1. The runner gives 130.
+- **A second signal.** Before, a second Ctrl-C in the cold mode gave the exit code 130. The runner gives 1.
+- **`mark server create` in the cold mode.** Before, the peer of the command kept the process alive after the command. The peer stops at the end of the command. For a server in the foreground, use `mark --server` or `procedure-server`.
 
-The cold mode is a command in this process: no CLI server operates in this folder, or the command has `--local`. A command on the CLI server (the warm mode) keeps the exit codes 0 and 1.
+Before CLI-26, a signal in the warm mode ended the process, and the server continued the call. The shell showed 130 or 143. The runner gives the same codes, after the server aborts the call.
 
 #### Examples
 
@@ -271,7 +299,7 @@ mark --verbose lib new my-pkg
 
 ### Programmatic API
 
-#### `run(argv: string[]): Promise<void>`
+#### `run(argv: string[], options?): Promise<void>`
 
 Main CLI entry point.
 
@@ -282,6 +310,10 @@ import { run } from "@procedures/mark";
 await run(["lib", "new", "my-package"]);
 ```
 
+- By default, the program keeps its process. A command installs no signal handler, does not end the process, and sets `process.exitCode`.
+- `ownsProcess: true` gives the process to the runner of each command, as the bin does. The runner then owns the signals, and it ends the process with the exit code of the command.
+- `run` gives the options of `run()` of `@mark1russell7/service`: the process port and the clock. A test gives `fakeProcess()` of `@mark1russell7/service/testing`.
+
 #### `parseFromSchema(params, meta, schema?): Record<string, unknown>`
 
 Parse CLI arguments based on procedure metadata. With the schema, each value is converted by the type of its field. `parseCommandLine(argv, procedures)` splits a whole command line: the global flags, the path and the input.
@@ -641,19 +673,24 @@ packages/client-lib/
 
 ### Transport Layer
 
+In the cold mode, the client sends each call to the procedures host of this process through `localFace()` of `@procedures/peer` (CLI-26). In the warm mode, the client sends each call to the CLI server through `HttpTransport`.
+
 ```mermaid
 graph LR
     CLI[CLI]
     CLIENT[Client]
-    TRANSPORT[LocalTransport]
+    TRANSPORT["localFace() transport"]
+    HOST["ProcedureServer of the host<br/>(request tracking of the service)"]
     REGISTRY[ProcedureRegistry]
     HANDLER[Procedure Handler]
 
     CLI --> CLIENT
     CLIENT --> TRANSPORT
-    TRANSPORT --> REGISTRY
+    TRANSPORT --> HOST
+    HOST --> REGISTRY
     REGISTRY --> HANDLER
-    HANDLER --> TRANSPORT
+    HANDLER --> HOST
+    HOST --> TRANSPORT
     TRANSPORT --> CLIENT
     CLIENT --> CLI