@procedures/lib 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # @procedures/lib
 
+## 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`.
+- 64120d9: `lib.audit` reports each procedure without `metadata.effects`. A host with a capability refuses such a procedure.
+  
+  - The output has the new list `procedureIssues`. Each issue has the kind `missing-effects`, the procedure path (for example `git.status`) and a message.
+  - The issues are warnings. They do not change `success`, so the audit step of CI does not fail for them. CI shows each one as a warning annotation.
+  - The audit examines the procedures of the registry of the host, as it does for `flagNotices`. It imports no package code, so its effects do not change.
+  - `mark` loads its registry from the built `./module` entry of each package. Thus the audit does not examine a package without a build.
+
+### Patch Changes
+
+- Updated dependencies [0f75644]
+- Updated dependencies [09e5566]
+- Updated dependencies [ab77f75]
+- Updated dependencies [01e5b1f]
+- Updated dependencies [da56027]
+- Updated dependencies [a47bee6]
+- Updated dependencies [a47bee6]
+- Updated dependencies [bc74091]
+  - @procedures/client@0.5.0
+  - @procedures/dag@0.5.0
+  - @procedures/git@0.5.0
+  - @procedures/fs@0.5.0
+  - @procedures/pnpm@0.5.0
+  - @procedures/shell@0.5.0
+
+## 0.4.0
+
+### Minor Changes
+
+- 2fd2398: `dag.traverse` moved from `@procedures/lib` to `@procedures/dag`. Its name, input, output and effects stay the same. In this version, `@procedures/dag` has a `./module` entry, a `./register` entry and the `client.procedures` field, and it depends on `@procedures/client` and `zod`. The graph algorithms of its root do not change.
+  
+  `dag.traverse` gets the packages from `lib.scan` through `ctx.client` (`calls: ["lib.scan"]`). `@procedures/lib` depends on `@procedures/dag`, so the module of `@procedures/dag` does not list the module of `@procedures/lib` as a dependency: a host registers the two modules. `bundle-dev`, `bundle-mcp` and `mark` do. The module of `@procedures/lib` does not register `dag.traverse` any more.
+  
+  `DagTraverseInputSchema`, `DagTraverseInput`, `DagTraverseOutput` and `TraverseNodeResult` are exports of `@procedures/dag`, not of `@procedures/lib`.
+- 3fefa43: `core.catch` is removed. Use `client.tryCatch`.
+  
+  `core.catch` did the same as `client.tryCatch` of `@procedures/client`. `CoreCatchInputSchema`, `CoreCatchInput`, `CoreCatchOutput` and `CoreCatchOutputSchema` are removed too. `client.tryCatch` gives no context name: a call of its `try` or `catch` operand needs no `$when: "catch"`.
+
+### 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 [3d76cb7]
+- Updated dependencies [0ecc788]
+- Updated dependencies [4c51727]
+- Updated dependencies [4e751da]
+  - @procedures/client@0.4.0
+  - @procedures/dag@0.4.0
+  - @procedures/fs@0.4.0
+  - @procedures/git@0.4.0
+  - @procedures/shell@0.4.0
+  - @procedures/pnpm@0.4.0
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -6,7 +6,7 @@
 npm install @procedures/lib
 ```
 
-`client-lib` gives the procedures that manage the packages of the monorepo, and two runners of programs.
+`client-lib` gives the procedures that manage the packages of the monorepo.
 
 | Procedure | Function |
 |---|---|
@@ -16,11 +16,14 @@ npm install @procedures/lib
 | `lib.rename` | Rename a package in each file of the workspace |
 | `lib.graph` | Give the dependency graph of the workspace packages, with its cycles |
 | `ecosystem.procedures` | List the procedures of the packages |
-| `dag.traverse` | Start a procedure for each package, in the order of their dependencies |
-| `core.catch` | Start a deferred call, and give the error to a handler call |
 
 Until October 2026, `client-lib` also had `lib.install`, `lib.pull` and `lib.refresh`, for one repository per package. The monorepo does not need them, and they are gone ([DECISIONS-2026-10.md](../documentation/DECISIONS-2026-10.md)).
 
+In version 0.3.0 and before, `client-lib` also had two runners of programs:
+
+- `dag.traverse` moved to [`client-dag`](../client-dag) (`@procedures/dag`), with the same name. It gets the packages from `lib.scan` of this package. Thus a host registers the two modules.
+- `core.catch` is removed. It did the same as `client.tryCatch` of `@procedures/client`. Use `client.tryCatch`.
+
 ## Use
 
 ```typescript
@@ -67,6 +70,12 @@ Input: `rootPath` and `fix`. For each package, the output gives the files and th
 
 The output also has `flagNotices`: the procedure flags whose short form is also a global flag of `mark`. After the command path, the flag of the procedure wins (deep dive CLI-7).
 
+The output also has `procedureIssues`. It has one issue of the kind `missing-effects` for each procedure without `metadata.effects`. A host with a capability refuses such a procedure. `procedure new` writes no effects, so the author writes them.
+
+- The issues are warnings. They do not change `success`, so the audit step of CI does not fail for them.
+- The audit examines the procedures of the registry of the host. It does not import the code of a package.
+- `mark` loads its registry from the built `./module` entry of each package. Thus start `pnpm build` before the audit. The audit does not examine a package without a build.
+
 ## `lib.rename`
 
 Input: `oldName`, `newName`, `rootPath` and `dryRun`. The procedure changes the package name, the dependencies, the imports and the dynamic imports in the workspace. The output lists each change and gives a summary.
@@ -89,47 +98,8 @@ node packages/mark/dist/cli.js lib graph
 
 Input: `rootPath`, `namespace` and `includeMetadata`. The output lists the procedures of the packages that have a `client.procedures` field.
 
-## `dag.traverse`
-
-`dag.traverse` starts the `visit` procedure once for each package, with `cwd` set to the folder of the package. A package starts after the packages that it depends on.
-
-| Field | Default | Function |
-|---|---|---|
-| `visit` | | A procedure path, or a call with `$when: "$parent"` (or `$never`) |
-| `filter` | | Only these package names |
-| `root` | | Only this package and the packages that it depends on |
-| `rootPath` | the workspace | The workspace root |
-| `concurrency` | 4 | The number of visits at the same time |
-| `serialize` | `auto` | When the visits in one git repository start one at a time: `auto` (when the visit uses a `git` procedure), `repository` (always) or `none` |
-| `continueOnError` | false | Continue after a failed visit |
-| `dryRun` | false | Give the plan only |
-
-All packages of the monorepo are in one git repository. Concurrent `git add` commands fail on `index.lock`, so `auto` starts git visits one at a time (deep dive DATA-17).
-
-```typescript
-await client.exec(["dag", "traverse"], {
-  visit: { $proc: ["pnpm", "run"], input: { script: "build" }, $when: "$parent" },
-  root: "@procedures/fs",
-});
-```
-
-`dag.traverse` has the tag `runs-refs`: it starts the refs of its input. Thus a server with an `expose` rule lets it use only exposed procedures. A call in `visit` with `$when: "dag.traverse"` waits for this runner ([PROGRAM-FORMAT.md](../documentation/PROGRAM-FORMAT.md), section 5).
-
-## `core.catch`
-
-`core.catch` starts the `try` call. When it fails, `core.catch` starts the `handler` call with the error in its input (`success: false`, `error`, `proc`). Give both calls `$when: "catch"`, so that they wait for this runner.
-
-```typescript
-await client.exec(["core", "catch"], {
-  try: { $proc: ["git", "commit"], input: { message: "auto" }, $when: "catch" },
-  handler: { $proc: ["client", "identity"], input: { value: { continue: true } }, $when: "catch" },
-});
-```
-
-The output gives `success`, `result`, `error` and `continue`. The calls of the `try` input start inside the error handling (deep dive DATA-22).
-
 ## Related packages
 
-- `client-dag`: the graph algorithms of `dag.traverse`.
+- `client-dag`: the graph algorithms of `lib.graph`, and the procedure `dag.traverse`, which uses `lib.scan`.
 - `client-procedure`: `procedure.new`, the scaffold of a procedure.
 - `mark`: the CLI that starts these procedures.