@turri-dev/cli 0.1.4-next.318a98a → 0.1.4-next.4342332

package/docs/installation.md

@@ -1,12 +1,8 @@
 # Installation
 
-**turri** runs wherever pi runs - macOS, Linux, WSL - with git, bash and Node 22.19 or newer (a Linux
-distribution's own `nodejs` package is often older: take it from nodejs.org, nvm or NodeSource). Native Windows is
-best effort: it needs bash on the PATH (Git for Windows' Git Bash), and has no OS sandbox under the agents' commands.
+**turri** runs wherever pi runs - macOS, Linux, WSL - with git, bash and Node 22.19 or newer (a Linux distribution's own `nodejs` package is often older: take it from nodejs.org, nvm or NodeSource). Native Windows is best effort: it needs bash on the PATH (Git for Windows' Git Bash), and has no OS sandbox under the agents' commands.
 
-The agents' commands run on this machine, with its toolchains - see [the sandbox](sandbox.md). Each is checked before
-it runs and audited after, on every platform; under them an OS sandbox fences it where the OS has one: Seatbelt on
-macOS, always there, and bubblewrap on Linux and WSL 2 - `apt install bubblewrap`, or your distribution's package.
+The agents' commands run on this machine, with its toolchains - see [the sandbox](sandbox.md). Each is checked before it runs and audited after, on every platform; under them an OS sandbox fences it where the OS has one: Seatbelt on macOS, always there, and bubblewrap on Linux and WSL 2 - `apt install bubblewrap`, or your distribution's package.
 
 ```bash
 npm install -g @turri-dev/cli   # puts `turri` on your PATH
@@ -21,9 +17,7 @@ turri init-config   # a config.turri.yaml with the model you talk to and the one
 turri               # pi, with turri's tools, skills and themes loaded
 ```
 
-The package is `@turri-dev/cli` - npm keeps the name `turri` back, as too like another
-package's - and the command it puts on your PATH is `turri`. `npm install -g @turri-dev/cli@next` gets the latest
-prerelease instead, built from the last commit on `main`.
+The package is `@turri-dev/cli` - npm keeps the name `turri` back, as too like another package's - and the command it puts on your PATH is `turri`. `npm install -g @turri-dev/cli@next` gets the latest prerelease instead, built from the last commit on `main`.
 
 ## From a clone
 
@@ -35,22 +29,13 @@ npm install
 npm link              # puts `turri` on your PATH, pointing at this clone
 ```
 
-A clone runs its TypeScript sources directly - Node strips the types - so edits take effect immediately. The package
-on npm runs JavaScript compiled from them instead (`npm run build`, into `dist/`, run by `npm pack` and `npm publish`
-before they pack), as Node runs no `.ts` file inside a `node_modules`. `bin/turri.mjs` runs `src/` where there is one,
-and `dist/` otherwise.
+A clone runs its TypeScript sources directly - Node strips the types - so edits take effect immediately. The package on npm runs JavaScript compiled from them instead (`npm run build`, into `dist/`, run by `npm pack` and `npm publish` before they pack), as Node runs no `.ts` file inside a `node_modules`. `bin/turri.mjs` runs `src/` where there is one, and `dist/` otherwise.
 
-To update, `git pull` and `npm install` - the second picks up a dependency that changed, pi's say. `npm link` needs
-running only once. A **turri** already running keeps the code it started with: start it again to run what you pulled.
+To update, `git pull` and `npm install` - the second picks up a dependency that changed, pi's say. `npm link` needs running only once. A **turri** already running keeps the code it started with: start it again to run what you pulled.
 
 ## In Docker
 
-`docker/Dockerfile` builds an image with Node, git, bash, bubblewrap and **turri** linked; the agents' commands and the
-testing scripts run inside it, so add the toolchains your projects need first. It runs **turri** as the user who owns
-the project folder mounted at `/work`, never as root - bubblewrap as root in a container lacks the capability to make
-its namespaces - and with seccomp and AppArmor unconfined the OS sandbox starts. `systempaths=unconfined` lets it mount
-a `/proc` of its own; without it, it binds the container's. The build, the run, Windows and the keys:
-[turri in Docker](../docker/README.md).
+`docker/Dockerfile` builds an image with Node, git, bash, bubblewrap and **turri** linked; the agents' commands and the testing scripts run inside it, so add the toolchains your projects need first. It runs **turri** as the user who owns the project folder mounted at `/work`, never as root - bubblewrap as root in a container lacks the capability to make its namespaces - and with seccomp and AppArmor unconfined the OS sandbox starts. `systempaths=unconfined` lets it mount a `/proc` of its own; without it, it binds the container's. The build, the run, Windows and the keys: [turri in Docker](../docker/README.md).
 
 ## What `turri doctor` checks
 
@@ -73,23 +58,17 @@ In a project - a folder with `config.turri.yaml` (or the old `config.yaml`) or `
 | the testing scripts | what in them this machine does not have: a program named by its whole path that is not here (a macOS-only `/usr/libexec/java_home` on Linux), a toolchain they run that is not on the PATH |
 | the models | each model `config.turri.yaml` names - `harness-model`, `coding-model`, `judge-model`, every role under `models:` - sent one short request through pi, with the credentials turri's agents will use, for any provider pi supports. One that answers is ready; for one that does not, it says what the provider said and what to do: the credentials pi reads for that provider (`AWS_PROFILE` and `AWS_REGION` for Amazon Bedrock, `OPENAI_API_KEY`, `/login`, ...), model access in the Bedrock console, the closest model ids pi knows for one it does not. `--harness-model`, `--coding-model` (`--model`) and `--judge-model` name models as the config's keys, as `turri regenerate` reads them - checked in a project or not. `--no-models` skips it |
 
-Removing that file is the one thing `doctor` changes, and it asks first; `turri doctor --yes` says yes. Run without a
-terminal - piped, or in CI - it asks nothing and changes nothing. Run it again whenever something breaks;
-`turri doctor --no-models` leaves out the models' requests.
+Removing that file is the one thing `doctor` changes, and it asks first; `turri doctor --yes` says yes. Run without a terminal - piped, or in CI - it asks nothing and changes nothing. Run it again whenever something breaks; `turri doctor --no-models` leaves out the models' requests.
 
 The chat is told every turn which wall is up and what the project's modules need of this machine that it lacks. What they need is worked out from every spec of the project - seconds, on a project of long requires chains - so it is worked out once the chat is up and again after a turn in which a spec changed, never while your message waits: a turn is told what was known last.
 
 ## turri and `pi`
 
-`turri` runs pi from this project's `node_modules`, with turri loaded, so no global pi install is needed. A plain
-`pi` is left as it is: starting pi does not start turri, and turri puts nothing into pi's own folders.
+`turri` runs pi from this project's `node_modules`, with turri loaded, so no global pi install is needed. A plain `pi` is left as it is: starting pi does not start turri, and turri puts nothing into pi's own folders.
 
-An older `turri setup` could load turri into every `pi`, with a one-line file in `~/.pi/agent/extensions/` pointing at
-this clone. `turri doctor` says when it is there, and offers to remove it. Until it is gone, `turri`
-leaves out its own `-e`: pi treats a tool registered twice as an error.
+An older `turri setup` could load turri into every `pi`, with a one-line file in `~/.pi/agent/extensions/` pointing at this clone. `turri doctor` says when it is there, and offers to remove it. Until it is gone, `turri` leaves out its own `-e`: pi treats a tool registered twice as an error.
 
-`turri` starts in the `turri-dark` theme. A plain `pi` keeps its own theme; to give it
-`turri-dark` too, in `~/.pi/agent/settings.json`:
+`turri` starts in the `turri-dark` theme. A plain `pi` keeps its own theme; to give it `turri-dark` too, in `~/.pi/agent/settings.json`:
 
 ```json
 { "theme": "turri-dark" }
@@ -97,24 +76,18 @@ leaves out its own `-e`: pi treats a tool registered twice as an error.
 
 ### Project trust
 
-pi will not auto-discover a project-local extension until you trust the project, and `-p` has no
-way to ask - so `npm run chat` and `npm run ask` pass `-e` explicitly. Once you have run `pi`
-interactively in this directory and accepted the trust prompt, plain `pi` picks the extension up
-on its own. A `defaultProjectTrust` key in `.pi/settings.json` does *not* work - a project cannot
-vouch for itself; that setting only counts in `~/.pi/agent/settings.json`.
+pi will not auto-discover a project-local extension until you trust the project, and `-p` has no way to ask - so `npm run chat` and `npm run ask` pass `-e` explicitly. Once you have run `pi` interactively in this directory and accepted the trust prompt, plain `pi` picks the extension up on its own. A `defaultProjectTrust` key in `.pi/settings.json` does *not* work - a project cannot vouch for itself; that setting only counts in `~/.pi/agent/settings.json`.
 
 ## Environment
 
-Models and credentials come from your pi configuration (`~/.pi/agent`) or provider environment
-variables - the same resolution `pi` itself uses. Put the rest in your shell profile:
+Models and credentials come from your pi configuration (`~/.pi/agent`) or provider environment variables - the same resolution `pi` itself uses. Put the rest in your shell profile:
 
 ```bash
 export PLAIN_TEMPLATE_DIRS=~/path/to/standard_template_library   # shared templates
 export GEMINI_API_KEY=...        # and leave GOOGLE_API_KEY unset
 ```
 
-For Gemini, `GEMINI_API_KEY` is what makes pi *offer* the google provider, but when
-`GOOGLE_API_KEY` is also set pi uses that one for the calls and says so.
+For Gemini, `GEMINI_API_KEY` is what makes pi *offer* the google provider, but when `GOOGLE_API_KEY` is also set pi uses that one for the calls and says so.
 
 | variable | |
 | --- | --- |

package/docs/parser.md

@@ -1,7 +1,6 @@
 # The \*\*\*plain parser
 
-`src/plain/` is a TypeScript port of the reference \*\*\*plain parser - `plain_file.py`,
-`plain_spec.py`, `concept_utils.py`, and the `file_utils.py` helpers they depend on.
+`src/plain/` is a TypeScript port of the reference \*\*\*plain parser - `plain_file.py`, `plain_spec.py`, `concept_utils.py`, and the `file_utils.py` helpers they depend on.
 
 | module | ports |
 |---|---|
@@ -21,9 +20,7 @@ turri validate .                   # every .plain file in a directory
 turri validate <file.plain> --json
 ```
 
-It uses this repo's own parser, so it needs no external tool, no API key and no credits: it parses
-the file, resolves its imports and required modules, and reports every syntax, concept and
-structure error with the line it is on.
+It uses this repo's own parser, so it needs no external tool, no API key and no credits: it parses the file, resolves its imports and required modules, and reports every syntax, concept and structure error with the line it is on.
 
 ```
 PASS  d365_export.plain  6 functionalities (1, 2, 3, 4, 5, 6), requires d365_restore_api
@@ -37,14 +34,12 @@ The exit code is 0 only when every file passed. In a conversation the same check
 
 ## Two rules of inheritance
 
-- A module that **`requires`** another inherits its functional specs, transitively: it is built on
-  top of that module's code.
+- A module that **`requires`** another inherits its functional specs, transitively: it is built on top of that module's code.
 - A module that **`import`s** another inherits its definitions, implementation reqs and test reqs.
 
 ## The functional-spec iterator
 
-`getFrids` walks functionalities depth-first through nested sections; `getSpecificationsForFrid`
-builds what a single functionality is rendered with. `iterateFunctionalSpecs` pairs them:
+`getFrids` walks functionalities depth-first through nested sections; `getSpecificationsForFrid` builds what a single functionality is rendered with. `iterateFunctionalSpecs` pairs them:
 
 ```ts
 import { plainFileParser, iterateFunctionalSpecs } from "./src/plain/index.ts";
@@ -60,49 +55,26 @@ for (const { frid, specifications, codeVariables } of iterateFunctionalSpecs(tre
 
 ## Parsing once
 
-A module's parse reads its imports and the whole of its `requires` chain, so a long chain asks for the same
-files over and over: bringing an 18-module chain up to its spec parsed for minutes. Two caches keep it to once.
-Inside `withParseCache`, one question about the specs, each file is parsed once. Between calls, a parse is kept
-with a fingerprint of every file directly in its template folders and the current one - name, size,
-modification time, and a `.plain` file's text - and handed out again, as a copy, while the fingerprint is the
-same; a spec that does not parse is kept as that too. What a parse returns is unchanged: the cache only decides
-whether to parse again.
+A module's parse reads its imports and the whole of its `requires` chain, so a long chain asks for the same files over and over: bringing an 18-module chain up to its spec parsed for minutes. Two caches keep it to once. Inside `withParseCache`, one question about the specs, each file is parsed once. Between calls, a parse is kept with a fingerprint of every file directly in its template folders and the current one - name, size, modification time, and a `.plain` file's text - and handed out again, as a copy, while the fingerprint is the same; a spec that does not parse is kept as that too. What a parse returns is unchanged: the cache only decides whether to parse again.
 
 ## Fidelity
 
-The port is checked against the Python implementation directly, not only against the ported
-assertions. Both parsers are run over a corpus and their module name, marshalled tree, required
-modules, functionality ids and per-functionality specifications compared:
+The port is checked against the Python implementation directly, not only against the ported assertions. Both parsers are run over a corpus and their module name, marshalled tree, required modules, functionality ids and per-functionality specifications compared:
 
 | corpus | files | identical | differences |
 |---|---|---|---|
 | `tests/data/` fixtures | 84 | 80 | 4 error strings (below) |
 | `hycu-dynamics-365-modules` | 47 | 47 | none |
 
-The 4 differences are all the same thing: template partials (`implement.plain`,
-`implement_2.plain`, `header.plain`, `pr_implement.plain`) are meant to be included with
-arguments, not parsed alone. Both implementations reject them for the same reason - an undefined
-Liquid variable - but the message text comes from the template engine, and liquidjs phrases it
-differently from liquid2.
-
-Real specs exposed three places where mdast and mistletoe disagree, each covered by
-`tests/plain/renderer.test.ts`:
-
-- **Inline decoding.** mdast resolves `\"` to `"` and forgets whether emphasis was written with `_`
-  or `*`; mistletoe round-trips the source. Inline leaf nodes are pinned back to their original
-  source slice at parse time.
-- **List geometry.** mistletoe indents an item's continuation lines by its `prepend`, measured in
-  coordinates with the enclosing item's indentation stripped - not by the column gap between parent
-  and child. An acceptance test rendered detached from its functionality keeps 6 and 10 spaces where
-  the naive reading gives 4 and 8.
-- **Lazy continuation lines.** A paragraph's continuation lines carry leading whitespace that is not
-  part of the text; keeping it in the raw slice indents the line twice.
+The 4 differences are all the same thing: template partials (`implement.plain`, `implement_2.plain`, `header.plain`, `pr_implement.plain`) are meant to be included with arguments, not parsed alone. Both implementations reject them for the same reason - an undefined Liquid variable - but the message text comes from the template engine, and liquidjs phrases it differently from liquid2.
+
+Real specs exposed three places where mdast and mistletoe disagree, each covered by `tests/plain/renderer.test.ts`:
+
+- **Inline decoding.** mdast resolves `\"` to `"` and forgets whether emphasis was written with `_` or `*`; mistletoe round-trips the source. Inline leaf nodes are pinned back to their original source slice at parse time.
+- **List geometry.** mistletoe indents an item's continuation lines by its `prepend`, measured in coordinates with the enclosing item's indentation stripped - not by the column gap between parent and child. An acceptance test rendered detached from its functionality keeps 6 and 10 spaces where the naive reading gives 4 and 8.
+- **Lazy continuation lines.** A paragraph's continuation lines carry leading whitespace that is not part of the text; keeping it in the raw slice indents the line twice.
 
 Two deliberate differences from the Python source:
 
-- The `test_plainfile.py` tests drive the acceptance-test helpers with `MagicMock` tokens and patch
-  the inner helper to count calls. ESM has no equivalent, so those tests build real ASTs from
-  markdown and assert the same observable outcome.
-- `networkx`'s `topological_sort` is reimplemented rather than replaced with a generic one: it
-  flattens `topological_generations`, so the ordering of independent concepts follows graph
-  insertion order, and the Python tests assert that exact sequence.
+- The `test_plainfile.py` tests drive the acceptance-test helpers with `MagicMock` tokens and patch the inner helper to count calls. ESM has no equivalent, so those tests build real ASTs from markdown and assert the same observable outcome.
+- `networkx`'s `topological_sort` is reimplemented rather than replaced with a generic one: it flattens `topological_generations`, so the ordering of independent concepts follows graph insertion order, and the Python tests assert that exact sequence.