@procedures/mark 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # @procedures/mark
 
+## 0.5.0
+
+### Minor Changes
+
+- a47bee6: The hosts can confine the file procedures to a root (roadmap R33).
+  
+  - `confineFsProcedures(registry, root)` of `@procedures/fs` replaces the handler of each `fs.*` procedure of a registry with the handler of `createFsModule({ root })`. It adds no procedure. A nested `fs.*` call of another procedure is confined too. The root must be a folder that exists.
+  - `mark --fs-root <folder>` confines the `fs.*` procedures of each mode and host of `mark`: a command, the REPL, `--server`, `serve` and `mcp`. Give the flag before the command.
+  - A `mark` command uses a CLI server only when the server has the same root. The lockfile of `@procedures/peer` has the new field `fsRoot`, and `findServer()` compares it.
+  - `procedure-server --fs-root <folder>` and `mark serve --fs-root <folder>` confine the procedures of the server.
+  - The MCP server reads `MCP_FS_ROOT`, and `mark mcp` has the flag `--fs-root`. `fs` is not a tool namespace, so the tools do not change.
+  - A path outside the root gives `FORBIDDEN` with the reason `outside-root`. A procedure that reads files with `node:fs`, or that starts a program, is not confined.
+  - `@procedures/lib/cli-flags` has the global flags `--fs-root` and `--events`, and the field `repeatable`.
+- a47bee6: The hosts serve the remote events (`documentation/EVENTS.md`).
+  
+  - `hostPolicy()` takes the option `events`: the topic rule, with an optional bus, `allow` function and buffer. `procedureServerOptions()` gives it to the `ProcedureServer`, which pins `events.subscribe`. `HostPolicy` has the new field `events`.
+  - `procedure-server` and `mark serve` have the option `--events <patterns>`. The option is repeatable, and it takes comma-separated patterns: exact names, prefixes (`orders.*`) or `*`. `parseTopicPatterns()` checks them.
+  - `mark --server` has the same option `--events`.
+  - These hosts always serve `events.subscribe`. Without `--events`, they serve no topic, and each subscription gets `TOPIC_NOT_FOUND`. The bus is the global bus, which is also the `ctx.bus` of their procedures.
+  - The MCP server serves no events, because its transport carries only MCP.
+  - `mark --port`, `--host`, `--transport` and `--events` without `--server` are an error now, also before `serve` and `mcp`. Before, `mark --port 4000 serve` ignored `--port`.
+
+### Patch Changes
+
+- Updated dependencies [0f75644]
+- Updated dependencies [09e5566]
+- Updated dependencies [ab77f75]
+- Updated dependencies [a47bee6]
+- Updated dependencies [a47bee6]
+- Updated dependencies [64120d9]
+- Updated dependencies [64120d9]
+- Updated dependencies [bc74091]
+  - @procedures/client@0.5.0
+  - @procedures/server@0.5.0
+  - @procedures/mcp-dev-tools@0.5.0
+  - @procedures/peer@0.5.0
+  - @procedures/lib@0.5.0
+  - @procedures/procedure@0.5.0
+  - @procedures/cli-run@0.5.0
+  - @procedures/pnpm@0.5.0
+  - @procedures/shell@0.5.0
+  - @procedures/vitest@0.5.0
+
+## 0.4.0
+
+### Patch Changes
+
+- Updated dependencies [d919678]
+- Updated dependencies [057d69a]
+- Updated dependencies [b2a1a1e]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [afd6a19]
+- Updated dependencies [057d69a]
+- Updated dependencies [2fd2398]
+- Updated dependencies [3fefa43]
+- Updated dependencies [cc3f5f6]
+- Updated dependencies [bae25e2]
+- Updated dependencies [4c51727]
+- Updated dependencies [d42d716]
+- Updated dependencies [4e751da]
+  - @procedures/client@0.4.0
+  - @procedures/lib@0.4.0
+  - @procedures/mcp-dev-tools@0.4.0
+  - @procedures/procedure@0.4.0
+  - @procedures/shell@0.4.0
+  - @procedures/server@0.4.0
+  - @procedures/peer@0.4.0
+  - @procedures/cli-run@0.4.0
+  - @procedures/pnpm@0.4.0
+  - @procedures/vitest@0.4.0
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -130,10 +130,11 @@ The package provides a `mark` binary for command-line usage.
 
 ```bash
 mark [global options] <path...> [positional...] [--options]
-mark serve [--procedures pkgs] [--port N] [--token T | --no-token] [--expose patterns]
-mark mcp [--bundles list] [--tool-timeout ms] [--debug]
-mark --server [--port N] [--host H] [--transport http|websocket|both]
+mark serve [--procedures pkgs] [--port N] [--token T | --no-token] [--expose patterns] [--events topics] [--fs-root folder]
+mark mcp [--bundles list] [--tool-timeout ms] [--read-only] [--http port] [--fs-root folder] [--debug]
+mark --server [--port N] [--host H] [--transport http|websocket|both] [--events topics]
 mark -i
+mark --fs-root <folder> <command | --server | -i | serve | mcp>
 ```
 
 The bin is `dist/bin.js`. `node dist/cli.js` also runs the CLI. Importing `@procedures/mark` runs nothing.
@@ -151,6 +152,38 @@ The bin is `dist/bin.js`. `node dist/cli.js` also runs the CLI. Importing `@proc
 
 `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`.
 
+#### Remote events of the hosts
+
+`mark --server` and `mark serve` always serve the procedure `events.subscribe` ([EVENTS.md](../documentation/EVENTS.md)):
+
+- `--events <patterns>` gives the topics that a peer can subscribe to: exact names (`orders.created`), prefixes (`orders.*`) or `*`. Repeat the flag, or separate the patterns with commas.
+- Without `--events`, the host serves no topic. Each subscription gets `TOPIC_NOT_FOUND`.
+- The bus is the global bus of the process. The procedures get it as `ctx.bus`, so a procedure publishes with `ctx.bus.emit()`.
+- The token of the host applies to a subscription. The hosts have no capability limits, so they permit each subscription to a topic of the rule.
+- `mark mcp` serves no events: MCP carries only the tool calls, and `events.subscribe` is not a tool.
+
+```bash
+mark --server --transport both --events "orders.*"
+mark serve --procedures ./my-procedures.js --events orders.created --events audit.created
+```
+
+#### The root of the file procedures
+
+`--fs-root <folder>` confines each path of the `fs.*` procedures to the folder (roadmap R33). It applies to each mode and host of `mark`:
+
+- A command in this process, the REPL (`-i`) and the CLI server (`--server`): the registry of `mark` gets the root.
+- `mark serve` and `mark mcp`: the root goes to their servers. `mark mcp` also reads `MCP_FS_ROOT`.
+- A path outside the folder gives `FORBIDDEN` with the reason `outside-root`. A relative path starts at the folder.
+- The nested `fs.*` calls of the other commands are confined too. For example, `mark --fs-root ./data lib scan` cannot list the packages of a workspace outside `./data`.
+- Give `--fs-root` before the command. After the command, it is an error, because the procedures loaded without it.
+- A command uses a CLI server only when the server has the same root. The lockfile of the server records its root.
+- A procedure that reads files with `node:fs`, or that starts a program, is not confined. The [README of the MCP server](../impl-mcp-dev/README.md) lists them.
+
+```bash
+mark --fs-root ./data fs read notes.txt
+mark --fs-root ./data --server
+```
+
 #### Global Options
 
 A flag before the command path is a global flag. After the path, a flag is the command's flag when the command declares it. Otherwise it is a global flag. For example, `mark docker compose down -v` gives `-v` (volumes) to the command. To show the version, write `mark -v`. `mark lib audit` lists the command flags that hide a global flag.
@@ -163,7 +196,8 @@ A flag before the command path is a global flag. After the path, a flag is the c
 | `--format <format>` | `-f` | Override output format (text, json, table, streaming) |
 | `--local` | | Run the command in this process, not on the CLI server |
 | `--json <json>` | | Execute raw procedure reference |
-| `--server` | | Start the CLI server (with `--port`, `--host`, `--transport`) |
+| `--fs-root <folder>` | | Confine each path of `fs.*` to the folder, also in the nested calls. Give it before the command. |
+| `--server` | | Start the CLI server (with `--port`, `--host`, `--transport`, `--events`) |
 | `--interactive` | `-i` | Start the REPL |
 
 #### Exit Codes and Failures