packages feed

plexus-synapse 4.1.0 → 4.2.0

raw patch · 18 files changed

+1183/−1224 lines, 18 filesdep ~aesondep ~plexus-protocolPVP ok

version bump matches the API change (PVP)

Dependency ranges changed: aeson, plexus-protocol

API changes (from Hackage documentation)

+ Synapse.CLI.Source: sourcePath :: SourceEnv -> Text -> Maybe FilePath
+ Synapse.IR.Types: MethodRolePeer :: Maybe Text -> Maybe Text -> Maybe PeerInterface -> MethodRole
+ Synapse.IR.Types: [childSchema] :: MethodRole -> Maybe PluginSchema
+ Synapse.IR.Types: [peerInterface] :: MethodRole -> Maybe PeerInterface
+ Synapse.Transport: fetchSlotSchemaAt :: Path -> SynapseM (Maybe PluginSchema)
+ Synapse.Watch: Gone :: Stamp
+ Synapse.Watch: NothingToWatch :: WatchRefusal
+ Synapse.Watch: ReadsStdin :: Text -> WatchRefusal
+ Synapse.Watch: Stamp :: UTCTime -> Integer -> Stamp
+ Synapse.Watch: awaitChange :: Int -> Int -> [(FilePath, Stamp)] -> IO ([(FilePath, Stamp)], [FilePath])
+ Synapse.Watch: childArgs :: [String] -> [String]
+ Synapse.Watch: data Stamp
+ Synapse.Watch: data WatchRefusal
+ Synapse.Watch: instance GHC.Classes.Eq Synapse.Watch.Stamp
+ Synapse.Watch: instance GHC.Classes.Eq Synapse.Watch.WatchRefusal
+ Synapse.Watch: instance GHC.Show.Show Synapse.Watch.Stamp
+ Synapse.Watch: instance GHC.Show.Show Synapse.Watch.WatchRefusal
+ Synapse.Watch: pollMicros :: Int
+ Synapse.Watch: renderRefusal :: WatchRefusal -> Text
+ Synapse.Watch: reportLine :: Int -> [FilePath] -> ExitCode -> NominalDiffTime -> Maybe NominalDiffTime -> String
+ Synapse.Watch: runWatch :: [FilePath] -> [String] -> IO a
+ Synapse.Watch: settleMicros :: Int
+ Synapse.Watch: stampOf :: FilePath -> IO Stamp
+ Synapse.Watch: watchedFiles :: SourceEnv -> Maybe Text -> [Text] -> Either WatchRefusal [FilePath]
- Synapse.IR.Types: MethodRoleDynamicChild :: Maybe Text -> Maybe Text -> MethodRole
+ Synapse.IR.Types: MethodRoleDynamicChild :: Maybe Text -> Maybe Text -> Maybe PluginSchema -> MethodRole

Files

CHANGELOG.md view
@@ -1,5 +1,53 @@ # Changelog for plexus-synapse +## 4.2.0++A call follows the files it reads (SYNAPSE-43, SYNAPSE-44).++### Added++- **`--watch`** (SYNAPSE-43): the call is made at once and again each time a+  file it reads with `@FILE` changes — the command as written, run again as+  a process of its own, the files read anew. stderr says what changed, how+  the call ended, how long it took and how long after the save its answer+  was whole; stdout carries the answers alone. A truncate and its write are+  one call; changes during a call are one more call; a failing call ends+  nothing; Ctrl-C ends it, 130. Refused, 2, for a command that reads no+  file or reads stdin. `Synapse.Watch`; test: `watch-test` (25).+- **A record in a list, a field a flag** (SYNAPSE-44): `--sources.name+  clock --sources.source @clock.svelte` is one record of the list+  `sources`, built by the record's type; a field given again begins the+  next record. So a field of a record can come from a file. Before, a+  dotted key into a list was refused. Test: `parse-test` (84).++## 4.1.1++synapse steps into a schema's slots (NEST-21, SYNAPSE-41). Requires+`plexus-protocol >= 0.8` (its `MethodRole` carries the peer slot and the+dynamic child's slot type).++### Fixed++- **A dynamic child's names are navigated** (NEST-21). A segment that is+  neither a child nor a method of a schema with a `dynamic_child` slot+  (NEST-5: plexus-core's `config.{key}`) is asked of the service as the+  slot's instance (`<path>.<segment>.schema`) and stepped into, so+  `synapse … config transport insecure_ws set --value true` reaches+  `config.transport.insecure_ws.set`.+- **A peer slot's names are navigated** (SYNAPSE-41, NEST-7). After a method+  marked `peer` (plexus-dyn's `dyn.peer`) the next segment is a peer's name:+  `synapse … dyn peer <name> <ns> <method>` reaches+  `dyn.peer.<name>.<ns>.<method>`, whether or not the slot lists its peers+  as children.+- **A slot's instance is a tree of its own.** A peer is another service, so+  its activations' hashes (its `dyn` has the host's `dyn`'s) are no longer a+  `Cycle detected` with the path that reached it; the same for a dynamic+  child's keys, which share their type's hash.+- A name the service says is not there (activation or method not found, or a+  slot's `not_found`) is still `Command not found`; any other failure while+  asking for it — an outage, a refusal, a sign-in — is that failure, never+  `Command not found`. Test: `nav-dynamic-test` (11).+ ## 4.1.0  bidir removed (ASK-1, ASK-3); plexus 0.10's schemas read (NEST-10). Breaking
README.md view
@@ -1,1198 +1,125 @@-# Synapse--**A CLI that writes itself from your API.**--Synapse is the command-line frontend for [Plexus RPC](../plexus-protocol/) — a streaming JSON-RPC 2.0 protocol built for LLM orchestration. Define methods in Rust, and Synapse discovers them at runtime: commands, help text, parameter validation, and output rendering all come from the schema. No codegen, no static config.--```-                  ┌─────────────┐-                  │  Substrate   │  Rust backend service-                  │  (Plexus)    │  hosts activations-                  └──────┬──────┘-                         │ WebSocket JSON-RPC 2.0-                         │ streaming responses-                  ┌──────┴──────┐-                  │   Synapse    │  Haskell CLI-                  │  discovers   │  builds commands from schema-                  │  & invokes   │  renders streaming output-                  └─────────────┘-```--## Two problem domains synapse solves--1. **Schema-driven invocation.** Method discovery, parameter parsing, help text, and output rendering are all derived live from the backend's JSON Schema. No codegen, no static config — change the backend, the CLI follows.--2. **Credential lifecycle.** Per-backend defaults at `~/.plexus/<backend>/defaults.json` hold cookies and headers as **credential-reference URIs** (`literal:`, `env://`, `file://`, `keychain://`) resolved at request time. JWT decoding surfaces expiry inline (`expired 16d ago`), legacy `~/.plexus/tokens/<backend>` files auto-migrate, and the `_self` subcommand lets you inspect, set, and rotate credentials without ever pasting them into a shell. See [Credentials & Headers](#credentials--headers).--## The Full Picture: Define → Call--### 1. Define a method in Rust--An **activation** is a namespace of related methods. You define one by annotating an impl block:--```rust-use schemars::JsonSchema;-use serde::{Deserialize, Serialize};--// Event type — what the method streams back-#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]-#[serde(tag = "event", rename_all = "snake_case")]-pub enum EchoEvent {-    Echo { message: String, count: u32 },-}--// The activation-pub struct Echo;--#[plexus_macros::activation(-    namespace = "echo",-    version = "1.0.0",-    description = "Echo messages back"-)]-impl Echo {-    #[plexus_macros::method(-        description = "Echo a message back the specified number of times",-        params(-            message = "The message to echo",-            count = "Number of times to repeat (default: 1)"-        )-    )]-    async fn echo(-        &self,-        message: String,-        count: u32,-    ) -> impl Stream<Item = EchoEvent> + Send + 'static {-        stream! {-            for i in 0..count {-                yield EchoEvent::Echo {-                    message: message.clone(),-                    count: i + 1,-                };-            }-        }-    }--    #[plexus_macros::method(-        description = "Echo a message once",-        params(message = "The message to echo")-    )]-    async fn once(-        &self,-        message: String,-    ) -> impl Stream<Item = EchoEvent> + Send + 'static {-        stream! {-            yield EchoEvent::Echo { message, count: 1 };-        }-    }-}-```--The macro generates the JSON-RPC server, `Activation` trait impl, method enum, and JSON Schemas — all from the function signatures and `JsonSchema` derives. Register it with the service:--```rust-let service = DynamicService::new("substrate")-    .register(Echo::new())-    .register(Health::new())-    .register(Cone::new());-```--That's the entire backend. No route tables, no handler boilerplate, no schema files.--### 2. Call it from Synapse--```bash-# Install-cd synapse && cabal install--# Synapse discovers the echo activation and its methods automatically-$ synapse substrate echo once --message "hello"-message: hello-count: 1--$ synapse substrate echo echo --message "hello" --count 3-message: hello-count: 1--message: hello-count: 2--message: hello-count: 3-```--Every method you add to the Rust backend is immediately available as a CLI command. The parameter names, types, descriptions, and validation all come from the schema.--### 3. See what's on the wire--```bash-# Dry-run: show the JSON-RPC request without sending-$ synapse --dry-run substrate echo echo --message "hello" --count 3-{"method":"echo.echo","params":{"message":"hello","count":3}}--# JSON mode: see the raw stream items-$ synapse --json substrate echo echo --message "hello" --count 3-{"type":"data","content":{"event":"echo","message":"hello","count":1}}-{"type":"data","content":{"event":"echo","message":"hello","count":2}}-{"type":"data","content":{"event":"echo","message":"hello","count":3}}-{"type":"complete"}--# Fetch the JSON Schema for the activation-$ synapse --schema substrate echo-{"namespace":"echo","methods":[...]}-```--## The Registry--Plexus backends register themselves with a **registry** — a central service that tracks what's running and where. Synapse talks to the registry by default (at `localhost:4444`), so you never need to know host:port pairs for individual backends. You just use the backend by name:--```bash-# This just works — the registry resolves "substrate" to its host:port-synapse substrate echo once --message "hello"-```--When you run `synapse` with no arguments, it queries the registry and lists everything available:--```bash-$ synapse-Available backends:-  substrate      127.0.0.1:4444 [OK]-  lforge         127.0.0.1:4447 [OK]-  secrets        127.0.0.1:4446 [OK]-```--If your backend isn't showing up, it needs to register with the registry. Synapse also auto-registers backends it connects to directly — so if you point at a non-default port once, it becomes available by name for future calls:--```bash-# Direct connection (also registers with the registry at :4444)-synapse -P 4447 lforge hyperforge repos_list --org juggernaut--# Now this works without -P-synapse lforge hyperforge repos_list --org juggernaut-```--The key mental model: **don't think in terms of hosts and ports.** Register your backends, then use them by name. The registry is the source of truth.--## A service behind TLS: `--url wss://…` (SCAFFOLD-21, 3.15.0)--A hosted app sits behind a proxy that terminates TLS and routes its socket-at a path — every app on the house's edge is `wss://<app>.menger.sh/ws`.-Name it with `--url`, before the backend name like every global option:--```bash-synapse --url wss://hostdemo.menger.sh/ws hostdemo greeter hello --name Ada-synapse --url wss://hostdemo.menger.sh/ws -j hostdemo greeter count --to 3-synapse --url wss://hostdemo.menger.sh/ws -s hostdemo greeter        # the schema-synapse --url wss://hostdemo.menger.sh/ws                            # the backend there, [OK]-synapse -H hostdemo.menger.sh --tls --path /ws hostdemo greeter hello --name Ada   # the same address-```--| option | meaning |-| -- | -- |-| `--url ws[s]://HOST[:PORT][/PATH]` | the whole address; the port defaults to the scheme's (80, 443), the path to `/`. Not with `-H`/`-P`/`--tls`/`--path`; `http(s)://` is refused with the `ws(s)://` it means |-| `--tls` | dial `wss://` at `-H`/`-P` (port 443 unless `-P`) |-| `--path PATH` | the socket's path at `-H`/`-P` (default `/`) |-| `--cacert FILE` | with wss, also trust the CA certificate(s) in this PEM file (repeatable) |--**The certificate is always verified**: the chain against the system's trust-store (the distribution's bundle; `SYSTEM_CERTIFICATE_PATH` points synapse at-another directory or file) and the name against the host, which is also sent-as SNI. A failed check fails the handshake before any of the request — a-token included — is sent. There is no switch that skips the check: for a local-CA (a throwaway proxy, `caddy … tls internal`), pass its root with `--cacert`.--**Everything rides the same address**: the `_info` probe, calls, streams and-their reconnects (SYNAPSE-20 — the outage line names the URL), `-s`, `-i`,-`_find`, `_login` / `_logout` and the-session every later call carries. The upgrade's `Host` is the host alone on 443-(`host:port` otherwise). A registry lists plain `ws://HOST:PORT` backends, so an-address behind TLS or on a path is never auto-registered: name it each time,-or put `--url` in a shell alias.--**Sessions are kept per URL.** A plain `ws://HOST:PORT/` keeps the key it-always had (`~/.plexus/sessions/HOST_PORT/`, keychain `backend=HOST:PORT`), so-no stored session moves. Any other address is keyed by its URL with the port-written — `~/.plexus/sessions/wss_hostdemo.menger.sh_443_ws/AGENT.json`,-keychain `backend=wss://hostdemo.menger.sh:443/ws` — so a ws and a wss backend-on one host, or two paths, never share a session. Sign in with the options-the calls use:--```bash-synapse --url wss://app.example/ws _login app --key builder --as builder-synapse --url wss://app.example/ws app tickets health     # carries builder's session-```--An agent's key proof names the server's socket origin as its audience:-`ws://HOST:PORT` on a plain address (as before), `wss://HOST` (`:PORT` when-not 443) behind TLS — what a service run with `--public-url https://HOST` accepts-(plexus-login's `socket_urls`). The path is not part of it.--## Progressive Discovery--Once you're connected, just start typing. Synapse navigates the backend like a filesystem — each level shows what's available, so you never need external docs:--```bash-# What can substrate do?-$ synapse substrate-  arbor               Tree-structured conversation storage-  bash                Execute bash commands-  cone                Conversational AI sessions-  echo                Echo messages back-  health              Health check endpoint--# What methods does echo have?-$ synapse substrate echo-  echo                Echo a message back the specified number of times-  once                Echo a message once--# What does cone chat need? (auto-help when required params are missing)-$ synapse substrate cone chat-chat - Conversational interaction with a cone--  --identifier.type <string> (required)-      Discriminator for cone lookup (by_id, by_name)--  --identifier.name <string> (required if type=by_name)-  --prompt <string> (required)-      User message to send--# Inspect the raw JSON Schema for an activation-$ synapse --schema substrate cone-```--### Help and search: `_find`--A listing (`synapse -P 4455 menger`, `… menger tickets`) is one line per-activation and method; a method's page (`… tickets set_status --help`) is its-usage, aligned options and examples (SYNAPSE-12, SYNAPSE-13). When you don't-know the name, search for it (SYNAPSE-17):--```bash-$ synapse -P 4455 _find menger comit-5 matches for 'comit' (as 'commit') in menger--METHODS-  tickets link_commits      Link commits to a ticket, or to many-  tickets unlink_commits    Unlink commits from a ticket--PARAMETERS-  deployments record        [--commits <string[]>]    Every commit in previous..revision…-  tickets link_commits      --commits <string[]>      Commit references, in link order-  tickets unlink_commits    --commits <string[]>      Commit references to remove…--Run 'synapse -P 4455 menger tickets link_commits --help' for its options.-```--`synapse [OPTIONS] _find <backend> [activation…] <words…> [--limit N] [--methods | --params]`--- Every method and parameter whose name or description matches **all** the-  words, best first: an exact name, then a name's prefix (or a `snake_case`-  segment's), then an abbreviation (`setpar` → `set_parent`, prefixes of its-  segments in order) or a typo (one edit for 4–7 letters, two beyond), then a-  word of a description. Ties: the shorter path, then alphabetical.-- Grouped `METHODS` · `PARAMETERS` · `MENTIONED IN` (found only in a-  description; left out for a method already listed above). A parameter line is-  its method, its flag as the method's page shows it (`[brackets]` when-  optional) and its description, with `[values: …]` under it.-- The header says what a typo or an abbreviation was taken as; on a terminal-  the matched characters are bold (piped, or with `NO_COLOR`, plain text).-- Activation names before the words narrow it: `_find menger tickets setpar`.-  `--limit N` (default 20; the footer says how many more), `--methods` /-  `--params` for one group. Nothing found: the three nearest names, exit 1.-- `-j` (before `_find`): one JSON object per hit — `kind` (method | param),-  `path`, `param`, `type`, `required`, `description`, `values`, `group`,-  `score`, `matched`.-- Under login it searches the caller's view of the schema: a method the caller-  can't see is never a hit. The IR is kept in `~/.cache/synapse/ir` under the-  root schema's hash (and the caller's view), so a search costs one schema call-  while nothing has changed; `--no-cache` walks the backend again.--## Parameters--Synapse parses flags into typed JSON using the schema's IR:--```bash-# Simple flags-synapse substrate echo echo --message "hello" --count 3--# Dotted keys for nested objects-synapse substrate cone chat \-  --identifier.type by_name \-  --identifier.name my-assistant \-  --prompt "hello"--# Lists — repeated flags or comma-separated (see Lists below)-synapse substrate tags set --tags backend --tags critical-synapse substrate tags set --tags backend,critical,urgent-synapse substrate tags set --tags '"red, green",blue'   # an element with a comma--# Boolean flags (bare flag = true)-synapse substrate cone create --ephemeral-synapse substrate cone create --ephemeral=false--# A value may begin with dashes; --key=value works too-synapse substrate echo once --message "--- starts with dashes"-synapse substrate echo once --message @note.md--# Raw JSON override-synapse substrate cone chat -p '{-  "identifier": {"type": "by_name", "name": "my-assistant"},-  "prompt": "hello"-}'-```--Path parameters (`--path`, `--working_dir`, etc.) expand `~`, resolve relative paths, and substitute `$ENV` variables automatically. **No other value is touched**: `--body 'costs $HOME'` sends `costs $HOME`. (Before 3.14.2 every value had `$VAR` substituted — a ticket body read from a file with `--body "$(cat body.md)"` lost its literal `$HOME`, `$PATH`, … The shell already expands what you leave unquoted, so synapse doing it again only ever rewrote text you had protected.)--### Flag values--Once synapse has found the method, it reads each flag by its parameter's type:--| typed | read as |-| -- | -- |-| `--body VALUE` | the next argument is the value, whatever it begins with: `---`, `--force`, `-5`, `--`, or nothing (`''`) |-| `--body=VALUE` | everything after the first `=`, which may be empty or contain `=` |-| `--body @body.md` | the file's contents, UTF-8, exactly as they are (3.14.8, SYNAPSE-10): no argument carries the value, so a body may be as large as the backend accepts; `~/` and a relative path resolve as the shell's would; a file that cannot be read is a refusal naming the flag and the path |-| `--body -` | standard input, read once however many values ask for it |-| `--handle @@alice` | the text `@alice`: one `@` is dropped, so a value that really begins with `@` can still be sent |-| `--summary` (a boolean) | `true`; it takes the next argument only when that is `true` or `false` (or `1`, `0`), so `--summary --limit 3` is two flags |-| `--summary=false` | `false` |-| `--no-such x` (names no parameter) | `Unknown parameter: --no-such`, nothing is sent; such a flag takes the next argument unless it begins with `--` |--So a markdown body with frontmatter passes as itself: `--body @body.md`, or `--body "$(cat body.md)"` while it is under the shell's 128 KB argument cap. The same sources serve `-p`: `-p @params.json` and `-p -`. Only the flag's name is normalized (`--blocked-by` is `blocked_by`), never its value. An argument that no flag takes (`--summary yes`) is an error, and nothing is sent. `--help` is always help, even right after a flag: to send the text `--help`, write `--body=--help`. Synapse's own options (`-P`, `-n`, `--json`, …) still go before the backend name.--**Changed in 3.14.1.** Through 3.14.0 a value that began with `--` was read as the next flag (`--body "---…"` failed with `Unknown parameter: --_`), any flag followed by another flag was bare whatever its type, and `--body=…` was read as a flag named `body=…`.--### Lists--A list parameter takes its elements one flag at a time, several to a flag, or both. When the elements are scalars (strings, integers, numbers, booleans, or a named type that is one of those, such as an id or a string enum), each flag value is read as one comma-separated record, with double quotes for an element that contains a comma:--| flag value as synapse receives it | elements |-| -- | -- |-| `a,b,c` | `a` `b` `c` |-| `a` | `a` |-| `"a,b,c,d","e,f,g"` | `a,b,c,d` and `e,f,g` — a double-quoted element keeps its commas |-| `"say ""hi""",b` | `say "hi"` and `b` — `""` inside quotes is one quote |-| `a, b ,c` | `a` `b` `c` — space around an unquoted element is dropped |-| `a,,b,` | `a` `b` — an empty unquoted element is dropped |-| `"",a` | the empty string and `a` |-| `"a,b` or `"a"x,b` | an error naming the parameter and the value; nothing is sent |--Repeated flags append in order: `--tags a,b --tags c` is `a` `b` `c`. Elements are then typed as before (`--ids 1,2,3` sends `[1,2,3]` for an integer list). A list of objects, of lists, or of untyped values is not split — each flag value is one element, since JSON has commas of its own. Nothing else splits: a comma in `--title` is just a comma, and `-p '{…}'` is sent as written. `<method> --help` marks each list parameter with the forms it takes.--**The shell removes double quotes before synapse runs**, so an element that contains a comma needs its quotes protected by single quotes:--| typed | what synapse receives |-| -- | -- |-| `--commits a,b,c,e` | `a,b,c,e` — four elements |-| `--multi "a,b,c,d","e,f,g"` | `a,b,c,d,e,f,g` — seven elements; the shell dropped the quotes |-| `--multi '"a,b,c,d","e,f,g"'` | `"a,b,c,d","e,f,g"` — two elements |--**Changed in 3.14.0.** Through 3.13 every flag value was exactly one element, commas included (`--tags a,b` sent `["a,b"]`). Now a single element that contains a comma must be quoted (`--tags '"a,b"'`), and a value that begins with `"` is read as a quoted element.--## Credentials & Headers--Synapse sends a JWT as `Cookie: access_token=<jwt>` on WebSocket upgrade when one is available, plus any extra cookies or headers you specify. All of these come from a single per-backend defaults file with a priority chain for per-invocation overrides.--### Defaults store--Each backend has a JSON file at `~/.plexus/<backend>/defaults.json` holding default cookies and headers. Values are **credential-reference URIs**, not raw secrets — synapse resolves them at request time.--```json-{-  "version": 1,-  "defaults": {-    "cookies": {-      "access_token": "literal:eyJhbGc..."-    },-    "headers": {-      "X-API-Key": "env://MY_API_KEY"-    }-  },-  "scopes": {}-}-```--Supported schemes:--| Scheme | Example | Meaning |-|---|---|---|-| `literal:` | `literal:eyJ...` | Raw value verbatim after the colon. |-| `env://` | `env://MY_JWT` | Read from environment variable. |-| `file://` | `file:///abs/path` | File contents (trailing newline stripped). |-| `keychain://` | `keychain://uscis/access_token` | OS keychain item (macOS via `security` CLI; Linux/Windows return a "not implemented" error). |--File mode is content-aware: `0600` if any `literal:` value is present, `0644` if the file is a pure manifest of references.--#### Threat model for `keychain://`--The keychain resolver shells out to `/usr/bin/security`. Items it creates have ACLs scoped to the `security` binary itself, not to synapse — meaning **any process running as your user can read them silently** by shelling out to `security` with the matching service/account. What `keychain://` actually protects against:--- Other users on the same machine-- Plaintext-on-disk leaks (the file contains only URIs; `defaults.json` becomes commit-safe when no `literal:` refs are present)-- Disk theft (the keychain DB is encrypted at rest, unlocked at login)--What it does **not** protect against:--- Any process running as you that knows the service/account (`security find-generic-password -s plexus -a <…> -w` works without a prompt)-- A compromised synapse binary--This is the standard tradeoff for "shell out to `security`" tools (cargo, gcloud, aws-cli all do the same). If you need per-process sandboxing, the upgrade path is to use the Security framework C API directly with code-signing-anchored ACLs — not implemented in v1.--### Managing defaults: the `_self` subcommand--```bash-# Inspect current state — decodes JWTs, flags expired tokens-synapse _self <backend> show--# Set a value (auto-wrapped as literal: unless you provide a scheme)-synapse _self <backend> set cookie access_token "eyJ..."-synapse _self <backend> set header X-API-Key "env://MY_API_KEY"--# Read from stdin (always literal:, bypasses the scheme heuristic)-cat my-jwt.txt | synapse _self <backend> set-from-stdin cookie access_token--# Import a JWT file into cookies.access_token-synapse _self <backend> import-token ~/Downloads/jwt.txt--# Resolve a single value (debug): prints the resolved concrete value-synapse _self <backend> resolve cookie access_token--# Remove entries-synapse _self <backend> unset cookie access_token-synapse _self <backend> clear --yes-```--`show` decodes JWT-shaped values and prints `alg`, `kid`, `iss`, `aud`, `sub`, `exp` (with human-relative rendering like `"expired 15d 23h ago"` or `"valid for 4m 32s"`), `iat`, `preferred_username`, `email`. Signatures are never printed.--### Per-invocation overrides--Four CLI paths populate credentials at call time, highest priority first:--```bash-# --token takes a JWT, sends it as Cookie: access_token=<jwt>-synapse --token eyJ... <backend> <method>--# SYNAPSE_TOKEN env-SYNAPSE_TOKEN=eyJ... synapse <backend> <method>--# --token-file reads from a path-synapse --token-file ~/tokens/uscis <backend> <method>--# --cookie / --header add arbitrary key/values on the upgrade request-synapse --cookie session=abc --header X-Trace-Id=xyz <backend> <method>-```--Invocation flags override the defaults store per key. CLI flags apply only to that one call; they don't write to disk.--### Legacy token file--The pre-SELF convention was `~/.plexus/tokens/<backend>` holding a raw JWT. On the first `loadDefaults` call for a backend that has a legacy file but no `defaults.json`, synapse auto-migrates: the JWT becomes `cookies.access_token = literal:<jwt>` in the new file, and the legacy file is deleted. An INFO log line names both paths and suggests upgrading to keychain storage.--## Output Rendering--Synapse renders streaming responses through a Mustache template pipeline:--```bash-# Default: schema-aware pretty output-synapse substrate health check-status: healthy-uptime: 12345--# --raw: content JSON only (skip template rendering)-synapse --raw substrate health check-{"status":"healthy","uptime":12345}--# --json: full JSON-RPC stream items-synapse --json substrate health check-{"type":"data","content":{"status":"healthy","uptime":12345}}-```--Templates are resolved in order: `.substrate/templates/{namespace}/{method}.mustache` (project-local) → `~/.config/synapse/templates/` (user) → YAML-like fallback.--Generate templates from the schema:--```bash-synapse --generate-templates substrate-```--### The answer in a file: `-o FILE` (SYNAPSE-39, 3.17.3)--An answer you mean to read goes to a file, then you read the file — never-through a filter that may stop reading early (a `grep` that cuts a list short,-a `head` that closes on a write):--```bash-synapse -P 4455 -o /tmp/t.json -j menger tickets list --summary true-synapse -P 4455 --output /tmp/t.txt menger tickets get --id MENGER-12-```--- `-o FILE` / `--output FILE` is a global option (before the service name,-  as `-j`). What the call prints goes to FILE instead of stdout, in the same-  form a pipe would get (`-j` lines with `-j`, the rendered answer without);-  stdout gets nothing, stderr what it always gets.-- It is written to a temporary file beside FILE and renamed over FILE when-  the call ends with 0, so a reader never sees half an answer. FILE is-  `0600` (an answer may carry a session token — `session login`).-- A call that ends with anything else leaves no FILE — an older FILE is-  removed too, so nothing stale is read as this call's answer — and no-  temporary file. The exit code is the call's (75, 77, 69…).-- A stream (`watch`) has no end: its items are appended to FILE and flushed-  as each comes. A stream that fails keeps what it wrote.-- A write's answer is written whole, whoever reads it.-- Under `-j` an error or a refusal goes to **stderr**, not FILE (its `-j`-  line goes with the failed run's FILE, so a refused call says why on stderr-  and exits 77).-- `-o -` is stdout. A FILE that cannot be made (no such directory, a-  directory) is said on stderr and the run **exits 73** before anything is-  sent; a write to it that fails later (a full disk, a file size limit) is-  no outage — the call ends, unretried — and the run **exits 74**.-- A SIGTERM or SIGHUP ends the run as a failed one (143, 129): no FILE and-  no temporary file. A SIGKILL can leave the temporary file-  (`FILE<n>.tmp`) behind.--## Outages: reconnecting (SYNAPSE-20)--synapse rides out a backend that goes away — a restart, a promote, a-network blip — for **ten minutes** by default.--- **A lost connection is noticed**: the server closing it, a reset, or-  silence. While a call is open, synapse pings after 15 s with nothing heard-  and counts the connection lost when 10 s more pass without an answer-  (`PLEXUS_KEEPALIVE=IDLE[,TIMEOUT]` in seconds, `0` for none). A call is-  never left waiting on a dead socket.-- **It retries for the window**: 0.5 s, doubling, to 15 s between tries.-  `--reconnect-for 10m` (`90s`, `1h`, `0` = never; or-  `SYNAPSE_RECONNECT_FOR`) sets how long. A backend that is down when synapse-  starts is waited for the same way (a wrong port that answers something-  other than Plexus fails at once). Progress goes to **stderr only**:--  ```-  synapse: connection to 127.0.0.1:4455 lost (the connection was closed) — reconnecting for up to 10m-  synapse: retrying 127.0.0.1:4455 in 4s (4s of 10m)-  synapse: reconnected to 127.0.0.1:4455 after 8s-  ```--- **A read is sent again; a write is not.** A method is a read when its-  schema's `group` is `read` (else when its name is a read's: `get`, `list`,-  `watch`, …); anything else is a write. A-  write whose request went out before the connection was lost may have-  happened, so synapse says so and **exits 75** (`connection to … lost-  before an answer — the write may have happened; check before sending it-  again`). A write that never left (the backend was down when it was-  sent) is sent once the backend is back.-- **A stream resumes.** `watch`, `await_reply` and any other streaming read-  are subscribed again with the same params. A method that takes `since`-  (menger's `await_reply`) gets `since` = the unix time the call began-  unless you gave one, so an answer given during the outage is still-  delivered. Under `-j` a line marks the resume, in the stream on stdout:--  ```json-  {"type":"reconnected","outage_secs":8,"attempts":4,"since":1792204276}-  ```--  (`since` only when the resumed call carried it.) The resumed stream-  starts as a new call does — `await_reply` says `waiting` again. Without-  `since`, events during the gap may be missing: re-read what you need.-  Other modes say it on stderr.-- **After the window**, synapse **exits 69** with the reason (`… unreachable-  for 10m (connection refused) — giving up`). It never hangs.-- **A closed stdout is not an outage** (SYNAPSE-26, 3.17.2). When the-  reader of synapse's stdout goes — `… | head -1`, `… | grep -m1` — synapse-  stops at once and **exits 141** (what a shell says of a filter its pipe-  closed on), saying nothing: no retry, no reconnect, a stream unsubscribed,-  a write sent once. Whatever window `--reconnect-for` sets, and on `-j` and-  the plain printer alike. (Before 3.17.2 the EPIPE was taken for a lost-  connection and a write was sent again for as long as the pipe stayed-  closed.) The socket's own broken pipe — the service gone — is still an-  outage. A stream notices its reader is gone only when it next prints: once-  `tickets watch | head -1` has its line, synapse keeps running until the-  next event arrives, then exits 141 — with no event, it waits. A run-  already ending with a code of its own — 75, 77, 69 — keeps it; 141 only-  replaces a success.--Many agents' calls at once ride out a restart too (SYNAPSE-15): a call-whose stored session the restart ended signs in again from its key under a-lock on that session, and a call that waited for the lock takes the session-the first one made. Sixteen or thirty-two parallel calls after a restart-sign in once and all succeed; a connection refused for the server's-connection limits (429) is waited out like any outage.--| exit | meaning |-| -- | -- |-| 69 | the backend stayed unreachable for the whole window |-| 75 | a write went out and its answer never came — it may have happened |-| 77 | the service refused the call (AUTH-8) |-| 73 | `-o FILE` could not be made (SYNAPSE-39): nothing was sent |-| 74 | a write to `-o`'s FILE failed (SYNAPSE-39): the call ended there |-| 141 | stdout's reader closed the pipe (SYNAPSE-26): nothing more was sent |--Through the connection holder (SYNAPSE-28, below) all of this holds as it is.--## One round trip a call (SYNAPSE-28, 3.16.0)--A call costs one round trip and the server's time. Against app.menger.sh-(77 ms away) `tickets health` takes **81 ms**, where it took 4.6 s.--```-$ synapse --url wss://app.menger.sh/ws --as builder menger tickets health   # the first: 2.6 s-$ synapse --url wss://app.menger.sh/ws --as builder menger tickets health   # every one after: 81 ms-```--Two things make it so:--- **A connection held between runs**, as ssh's ControlMaster holds one. The-  first call starts a holder (`synapse _hold`, a process of synapse's own)-  that keeps the signed-in WebSocket open and listens on a unix socket:-  `$XDG_RUNTIME_DIR/synapse/holder-6.sock` (0600, in a 0700 directory of-  yours). Later runs hand it their requests and read the replies back, so-  the TCP, TLS and upgrade handshakes (about 0.3 s to a hosted service) are-  paid once. Since 3.17.4 it is **one holder for all your calls**-  (SYNAPSE-40, below), a connection in it per address and agent (`--as`),-  never shared between agents; it exits after **10 minutes** holding nothing-  (`--hold-for 30m`, or `SYNAPSE_HOLD_FOR`). `--no-hold` (`SYNAPSE_NO_HOLD=1`)-  skips it: that run dials one connection of its own and closes it. A call-  that brings its own credential (`-t`, `--token-file`, `--cookie`,-  `--header`, `PLEXUS_SESSION`) never uses a holder.-- **Send first, check on failure.** synapse keeps what a call needs from the-  backend in `~/.cache/synapse/schemas-4/` (`$XDG_CACHE_HOME`): where the-  backend is, its `_info` as your agent was answered, each activation's-  schema (`PATH@VERSION-HASH.json`, pinned by `PATH.pin`) and a **plan** per-  method (its schema, its activation's deprecation, the types its flags parse-  by: kilobytes, where menger's `tickets` schema is 2.6 MB). A call to a-  method it has a plan for is built from the plan and sent: no probe, no-  schema fetch. The probe and the fetch run, on the same connection, only-  when that fails as the schema explains: a method or flag the cache does not-  know, or the server refusing what the cache said (a method it does not-  have, under the AUTH gate one only admin holds; params with a field-  missing, unknown or of another type). Those refusals come before the-  method runs, so the call is then sent again, a write too; the plans it-  misled are forgotten. Help, listings, `-s`, `-i` and `_find` always read-  the server.--Everything else is as before. Outages are ridden out by the same rules, a-read sent again and a write never resent blind (exits 69 and 75), because-the holder reports a lost connection, and whether the request had gone out,-exactly as a connection of the run's own would. A session that ended is made-again from the key by the run, and the holder dials a connection with the-new one beside the old, closing the old when idle. A run that goes away-mid-stream (Ctrl-C) ends its call at the server. Twenty runs starting at-once share one connection, and the reads they all ask first (the schema,-`_info`) are asked once.--Measured against app.menger.sh (ping 77 ms), 2026-10-22:--| | 3.15.0 | 3.16.0 |-| -- | -- | -- |-| `tickets health`, warm | 4,615 ms | 81 ms |-| `tickets queued`, warm | 7,398 ms | 84 ms |-| 20 `tickets health` at once, warm | 31.6 s | 107 ms |-| the first call (no holder, nothing cached) | — | 2.6 s |-| the first call after the holder exited (cache warm) | — | 380 ms |-| `--no-hold`, cache warm | — | 382 ms |-| 20 at once, no holder, nothing cached | — | 3.1 s |--The 0.9 s that went before every call in 3.15.0 was a second `_info` probe,-made anonymously on a connection of its own to check the name the first-probe had already answered; a run now probes at most once.--## One holder for the user (SYNAPSE-40, 3.17.4)--Through 3.17.3 the holder was one process per address and agent, each-living its 10 idle minutes after its server had gone; a test loop calling-throwaway servers on fresh ports left one per port, 1,634 of them (24.9 GB)-on 2026-11-02. Now one process holds every connection your runs keep,-however many services and agents you call — `synapse _hold`, at-`$XDG_RUNTIME_DIR/synapse/holder-6.sock` — and inside it a connection per-address, agent and credential. A call as one agent never rides another-agent's connection, even when neither carries a credential; a session made-again from the key is a connection beside the old one, which closes once-idle.--- **A connection whose server is gone is let go at once.** A server that-  stops closes its end; the holder notices within a second (a close or a-  reset ends the connection's reader; a peer gone silent is caught by the-  keepalive, 15 s idle + 10 s) and holds nothing for it from then on. The-  next call dials again, and a dial that fails holds nothing, so riding out-  an outage stays the run's (SYNAPSE-20: a read sent again, a write never-  resent blind, exits 69 and 75).-- **Idle, closed.** A connection is kept idle for the `--hold-for` of the-  last call on it (10 minutes unless the call says), then closed; the-  holder exits once it has held nothing, with no call, for its own-  `--hold-for` (the run that started it said).-- **A cap**: 256 connections (`SYNAPSE_HOLD_MAX`, read when the holder-  starts; 0: none). Past it the one idle longest is closed first; one-  carrying a call never is, so a burst of open calls may pass it until they-  end. A live connection costs the holder about 96 kB (403 held: 17.2 MB →-  55.8 MB), so at the cap it stays under about 45 MB.-- **What it holds**: `synapse _hold status` prints it as JSON — its pid,-  version and protocol, the cap, and each connection's address, agent,-  calls under way and seconds idle (never a credential); exit 1 when no-  holder answers.-- **SIGTERM / SIGHUP** stop it taking runs at once and give the calls under-  way ten seconds; a stream still open then is told its connection was-  lost and resumes through the next holder (SYNAPSE-20).-- **The newest synapse holds.** The holder says its version when it takes a-  request; a run of a newer synapse then puts its own holder in its place-  (the old one lets go of the socket at once, closes what is idle,-  finishes what it carries and exits), and a run of an older one never-  replaces a newer, so the newest in use serves every run and two never-  take turns.-- **What it takes from the run that starts it**: nothing it does not need.-  It starts in `/` (it keeps no directory in use), without the run's-  `PLEXUS_KEY`, `PLEXUS_SESSION`, `SYNAPSE_TOKEN` or `PLEXUS_KEEPALIVE`-  (one run's keepalive would be every connection's). It does keep that-  run's other environment (`SYSTEM_CERTIFICATE_PATH`, say) and its cgroup:-  a holder first started inside a systemd unit stops with the unit, and-  the calls it carried then end as an outage does (a read sent again, a-  write that went out exit 75).--The socket's name carries the holder's protocol (2): a synapse that changes-the wire or what the holder does bumps it and gets a holder of its own.-synapse 3.16.0 to 3.17.3 keep their holder per address and agent-(`ADDRESS@AGENT-VERSION.sock`, in the same directory), which this one never-opens, removes or answers, so a pinned older binary goes on as it was. A-loop over throwaway servers still sets `SYNAPSE_NO_HOLD=1` while any agent-there runs one.--Measured on 2026-11-02 (hold-test, the built synapse against mock services-in the test's process):--| | 3.17.3 | 3.17.4 |-| -- | -- | -- |-| holders, 3 addresses × 2 agents | 6 | 1 |-| holders, a loop of 20 calls to 20 short-lived servers | 20 | 1 |-| a loop of 500 calls to 500 short-lived servers | — | 1 holder, 103 s; RSS 29.8 MB at call 50, 31.2 MB at 500; nothing held 10 s on |-| connections held to stopped servers, 10 s on | each holder's, for 10 min | 0 (let go within a second) |--## A stream in: `--input` (BIDIR-18)--A method with an input half (`Input<T>`, plexus-wire spec/10: its schema-has `input` beside `params`) takes a stream in beside its stream out.-stdin (`--input -`) or a file (`--input @path`) is that stream:--```bash-tail -f build.log | synapse --url wss://app.menger.sh/ws --as runner menger runs append_log --run 41 --input --synapse -P 4460 svc ingest tokens --run r1 --input @tokens.jsonl-arecord -q -f S16_LE -r 16000 -c 1 | synapse -P 4460 voice listen --input - --chunk 640-# stderr, at the end or on a disconnect:-# input: sent 1,204 items in 1,204 frames · acked through seq 1,179 · 25 unacked-```--- **What an item is** comes from the item's schema: a string is a line; an-  `Input<Bytes>` (`"x-plexus-binary": true`) is the bytes as they come, up-  to `--chunk N` (4096 unless said, at most 16 MiB) a frame — what the-  source has is sent, never held to fill a chunk — each a WebSocket binary frame-  (`[0x01][subscription u64][seq u64][payload]`); anything else is NDJSON,-  one JSON value a line — a line that is not one is named by its number,-  no frame carries it, the call is ended and synapse exits 65.-- **Under credit**: items are read only as the service grants credit, so-  with none, synapse reads nothing more and the pipe in front of it is the-  buffer — its memory stays flat however far the writer runs ahead. What is-  ready goes out together (up to 256 items a frame), and a whole line goes-  out while the next is still arriving. At the end of the input,-  `<ns>.end` — at once, credit or none; only the end of the input ends it-  (a failed read ends the call with exit 74, no `end`). The answer prints-  as any call's.-- **Never sent twice** (spec/10: no resume). A connection lost during the-  call is said on stderr every time, with what was sent and acked, and the-  run exits 69. A typed close exits by its kind: `past_credit` 70 (a bug in-  synapse), `invalid_input` / `out_of_sequence` / `too_much_input` 65, an-  input closed for a revoked or ended sign-in 77.-- `--progress` prints sent / acked / credit on stderr once a second; `-n`-  prints the open frame and the first input frame and sends nothing; a-  method's `--help` and `_find` say it takes a stream in. A parameter named-  `input` keeps `--input` (the stream is then `--input-stream`; `--chunk`-  and `--progress` likewise become `--input-chunk` / `--input-progress`).-- The frames go through the connection holder (holder protocol 4) or, with-  `--no-hold`, on the run's own socket — the same frames either way.--## Code Generation--Synapse emits a structured Intermediate Representation for building typed clients:--```bash-$ synapse --emit-ir <backend> conformance > conformance.ir.json-```--IR 3.1 (plexus 0.7; 3.1 is 3.0 without the bidir keys, ASK-1) carries each-method's contract as its schema states it: its item type (`mdReturns`), its-error type when it can say no (`mdError`), its progress type when it reports-progress (`mdProgress`), and whether it yields one item or many-(`mdCardinality`); 3.0's `mdBidir*` are gone and read past. An excerpt of RETURNS-7's-conformance fixture, whose whole IR is-`plexus-macros/fixtures/conformance/expected/ir.json`:--```json-{-  "irVersion": "3.1",-  "irTypes": {-    "conformance.Loaded": {-      "tdKind": {"tag": "KindStruct", "ksFields": [-        {"fdName": "items", "fdRequired": true, "fdType": {"tag": "RefPrimitive", "contents": ["integer", "uint32"]}}-      ]}-    },-    "conformance.LoadError": {-      "tdKind": {"tag": "KindEnum", "keDiscriminator": "type", "keVariants": [-        {"vdName": "too_many", "vdFields": [-          {"fdName": "max", "fdRequired": true, "fdType": {"tag": "RefPrimitive", "contents": ["integer", "uint32"]}},-          {"fdName": "n", "fdRequired": true, "fdType": {"tag": "RefPrimitive", "contents": ["integer", "uint32"]}}-        ]}-      ]}-    }-  },-  "irMethods": {-    "conformance.load": {-      "mdCardinality": "many",-      "mdParams": [-        {"pdName": "n", "pdType": {"tag": "RefPrimitive", "contents": ["integer", "uint32"]}, "pdRequired": true}-      ],-      "mdReturns": {"tag": "RefNamed", "contents": {"qnNamespace": "conformance", "qnLocalName": "Loaded"}},-      "mdError": {"tag": "RefNamed", "contents": {"qnNamespace": "conformance", "qnLocalName": "LoadError"}},-      "mdProgress": {"tag": "RefNamed", "contents": {"qnNamespace": "conformance", "qnLocalName": "LoadStep"}}-    }-  }-}-```--Nothing is inferred: `mdCardinality` is the schema's `cardinality`, and every-`RefNamed` has a `TypeDef` — a struct, a tagged enum (`keDiscriminator` is the-property every variant gives a `const`, whatever it is called; a newtype-variant over a struct carries the struct's fields), a string enum or an alias.-One title in one namespace is one type: two methods whose schemas give a title-the same shape share one `TypeDef`, and two shapes under one title fail the-build, naming both methods. Identical types in different namespaces are then-deduplicated (prefer the parent namespace, then the shortest).--### IR 2.1: read whole, or refused by name (SYNAPSE-CC-8, 3.17.0)--Every schema is read whole or refused; nothing is dropped. The reader-(`src/Synapse/IR/Read.hs`) is pure: a value and the refusals met.--- **Unions.** A `oneOf` / `anyOf` is a string enum (every member an `enum`-  or a `const` of strings: `TransitionField` is `status, kind, archive`), a-  tagged enum (`KindEnum`, `keDiscriminator` the property every member gives-  a string `const` — `type`, `kind`, `event`, …; a newtype variant carries-  its struct's fields), an externally tagged enum (`keRepr: "external"`,-  `keDiscriminator: ""`: `{"browser": {…}}`), an untagged union of named-  types (`keRepr: "untagged"`, each variant's `vdRef`), or a nullable-  (`RefOptional`). `keRepr` is left out when internal, so 2.0's enums read-  as before. Any other union is refused, naming the member it could not read.-- **Refusals.** `irRefusals` lists each site the IR cannot type-  (`rfSite`, `rfKeyword`, `rfVariant`, `rfDetail`; left out when empty).-  Where a refused site stood the IR says `RefUnknown`; a refused type is left-  out and its uses say `RefUnknown`. With refusals, `synapse -i` still prints-  the IR on stdout, names each site on stderr and **exits 65**; no generator-  may run on it. Calls, help, flags and `_find` ignore refusals.-- **Sites** are `<ns.Type>[.<variant>].<field>`, `<method path>(<param>)`,-  `<method path> returns`, with `[]` (element), `?` (optional), `{}` (map-  value) and `.N` (tuple element): `tickets.Component.preview[].0`.-- **The JSON type.** A `serde_json::Value` is a type, not a gap: `true`,-  `{}`, annotations only, `type` naming all six JSON types (`["null",-  "boolean", "number", "string", "array", "object"]`, as plexus-core writes-  it since SYNAPSE-CC-9) or a `$ref` to a definition named `Json` is-  `RefJson` (`{"tag": "RefJson"}`): `JsonValue` / `Json` /-  `serde_json::Value` in a client. Still refused: a bare `{"type":-  "object"}` (neither properties nor additionalProperties), an array with no-  items, a type list that is neither one type (± null) nor all six. IR 2.0's-  `RefAny` reads as `RefJson`.-- **New refs.** `RefMap V` (an object with `additionalProperties: V` and no-  properties), `RefTuple [..]` (`prefixItems` with `minItems = maxItems` =-  its length), `RefRefined base {minimum, maxLength, …}` (only a bound the-  format does not imply: `minimum: 0` on a `uint64` adds nothing), and-  `RefChild "<path>"` (a static or dynamic child's return: its client). An-  rpc method with no `returns` is refused at `<path> returns`.-- **Injected params** (`x-plexus-source` other than `rpc`) are not in-  `mdParams`: they are `mdInjected` (`ipName`, `ipSource` verbatim,-  `ipDescription`; left out when empty). Help still shows them.-- **`mdInput`** is a method's `input` schema as a type, reserved for-  BIDIR-6; left out when absent (no server sends it yet).-- **The closed keyword list.** A schema in a type position uses only `type-  $ref properties required additionalProperties items prefixItems oneOf-  anyOf enum const format minimum maximum exclusiveMinimum exclusiveMaximum-  minLength maxLength pattern minItems maxItems default description title-  examples deprecated $schema $defs definitions x-plexus-source-  x-plexus-values`, and `allOf` as IR 3.0 reads it (`allOf: [X]` is X;-  `allOf: [{"$ref": S}]` beside a tag is a newtype variant over S); any-  other (`multipleOf`, an `allOf` of more, …) is refused by name.-- **Where a shared type lives.** The same type (name and structure) in-  several namespaces is kept once, in the namespace whose methods and types-  refer to it most; a tie goes to the namespace that is an ancestor of the-  others, then the shortest name, then alphabetical; the protocol root `""`-  only when no generated namespace has a copy.-- **Caches.** A plan or a `_find` catalogue holding another IR version-  (3.16.0's 2.0) is not read; it is built again.--`bench/IRBench.hs` (`cabal bench ir-bench`) times the builder alone over-menger's 2026-10-29 schemas (`test/fixtures/ir-coverage`), with no network;-`ir-coverage-test` holds one fixture per construct, menger whole (21-refusals; the IR equal to `menger-2026-10-29.ir-2.1.json`), and the guard-that every construct 2.0 already typed serializes as before.--### Servers on the published 0.7.0 line (RETURNS-36)--synapse 4.0 reads plexus 0.8's schema and frames strictly, and the-published 0.7.0 line's too, by what that server itself declares-(plexus-protocol 0.6, as plexus-core's child seam reads an old peer): a-method with `streaming` and no `cardinality` is many when the flag is-true, else one, and its missing `returns` is `{}`; an error frame with no-typed `error` is typed from its `error_kind`, else its `code` (its fields-kept); a progress frame with no `content` is `Note {message,-percentage}`. A method that states neither `cardinality` nor `streaming`-is refused. `--emit-ir` against a 0.7.0 server writes IR 3.0 with those-cardinalities.--### Where IR 3.0 is built (RETURNS-36)--- The types and the version: `src/Synapse/IR/Types.hs` — `IR`,-  `MethodDef` (`mdReturns`, `mdError`, `mdProgress`, `mdCardinality`),-  `TypeDef`/`TypeKind`/`TypeRef`, and `currentIrVersion = "3.0"`, which-  `emptyIR` and the metadata's `gmIrVersion` carry.-- The reader: `src/Synapse/IR/Read.hs` (`readRoot`, `readDefs`,-  `readType`, `rootNamed`) — each schema position read whole or refused.-- The builder: `src/Synapse/IR/Builder.hs` — `buildIR` (a walk),-  `buildIRFromSchema backend path schema` (pure: one `PluginSchema`, no-  metadata), `finalizeIR` (placement, dangling refs to `RefUnknown`,-  refusals sorted), `checkTitles` (one title, one type: `TitleCollision`).-- The golden: `test/IR3Spec.hs` builds `buildIRFromSchema "conformance"-  ["conformance"]` from `plexus-macros/fixtures/conformance/expected/schema.json`-  and compares it byte for byte (keys sorted, two-space indent, one-  newline) with `ir.json` beside it; `CONFORMANCE_FIXTURE_DIR` points it-  at a copy, `SYNAPSE_GOLDEN_ACCEPT=1` rewrites `ir.json`.--## Client Generation (synapse-cc)--[**synapse-cc**](../synapse-cc/) (Synapse Compiler Collection) is a separate project that consumes Synapse's IR to produce typed client libraries. It imports plexus-synapse as a library, generates IR from a live backend, pipes it through [service-codegen](../service-codegen/) (a stateless Rust code generator), then handles merging, dependencies, building, and testing.--```bash-synapse-cc init                    # scaffold synapse.config.json-synapse-cc build                   # generate typed client from config-synapse-cc watch substrate         # rebuild on schema changes-```--The generated client gives you typed methods matching the backend 1:1:--```typescript-const client = new SubstrateClient("ws://localhost:4444");--for await (const event of client.echo.echo({ message: "hello", count: 3 })) {-  console.log(event.message, event.count);-}-```--Three-way merge preserves user edits across regeneration. See the [synapse-cc architecture doc](docs/architecture/16673264336036332543_synapse-cc-pipeline.md) for the full pipeline, config format, and caching strategy.--## Error Messages--```bash-$ synapse substrate invalid-plugin-Command not found: 'invalid-plugin' at substrate--Available at substrate:-  Methods:-    schema              - Get schema information-    health              - Health check endpoint--  Child plugins:-    arbor               - Tree-structured conversation storage-    bash                - Execute bash commands-    cone                - Conversational AI sessions--$ synapse substrate cone chat --mesage "hello"-Unknown parameter: --mesage--Did you mean: --message?-```--## Debugging & Testing--Synapse provides built-in tools for debugging connections and validating protocol compliance.--### Connection Debugging--Test the complete connection stack (TCP → HTTP → WebSocket → RPC):--```bash-synapse _self debug localhost 5001 substrate-```--This tests each layer sequentially:-- **TCP**: Can we reach the port?-- **HTTP**: Does the server respond to HTTP?-- **WebSocket**: Can we upgrade to WebSocket?-- **RPC**: Can we call `_info`?--### Protocol Validation--Run the full protocol compliance test suite:--```bash-synapse _self validate localhost 5001 substrate-```--This calls the `_debug.*` endpoints (enabled with `PLEXUS_DEBUG=true` on the server) and validates:-- StreamDone messages are sent-- Metadata structure is correct-- Field naming follows conventions-- Progress percentages are in range--### Test Arbitrary Methods--Test any method with protocol validation:--```bash-# Use CLI flags for connection settings-synapse -P 5001 _self test substrate.ping.pong --message "test"--# Test with schema validation-synapse -P 5001 _self test substrate.echo.echo --message "hello" --count 3--# Allow unknown parameters (warns but passes through)-synapse -P 5001 _self test --allow-unknown substrate.echo.echo --fake "value"--# Use raw JSON (skips schema validation)-synapse -P 5001 _self test --raw '{"message":"hello"}' substrate.echo.echo-```--**Important**: Connection settings come from `-H`/`--host` (default: `127.0.0.1`) and `-P`/`--port` (default: `4444`) flags, not positional arguments. This ensures the test uses the same connection that discovery validated.--### Port Scanning--Discover backends running on common ports:--```bash-synapse _self scan-# Scans ports 4440-4459 for Plexus backends-```--## Architecture--Synapse treats the plugin hierarchy as a **category** and implements operations as **algebras** over recursion schemes:--```haskell-type SynapseM = ExceptT SynapseError (ReaderT SynapseEnv IO)---- Navigate to a path (paramorphism — fold with access to original structure)-navigate :: Path -> SynapseM SchemaView---- Walk the full tree (hylomorphism — fused unfold + fold, no intermediate tree)-walkSchema :: (SchemaF a -> SynapseM a) -> Path -> SynapseM a---- Build IR (hylomorphism with parallel child fetching)-buildIR :: Path -> SynapseM IR-```--The base functor:--```haskell-data SchemaF a-  = PluginF PluginSchema Path [a]   -- Interior node (namespace with children)-  | MethodF MethodSchema Text Path  -- Leaf (invocable method)-```--Schemas are fetched lazily during navigation, cached by content hash, with cycle detection for recursive plugin graphs.--## Project Structure--```-synapse/-  app/Main.hs              # CLI entry, two-phase arg parsing, dispatch-  src/Synapse/-    Monad.hs               # SynapseM effect stack, error types-    Transport.hs           # WebSocket JSON-RPC bridge-    Schema/-      Types.hs             # Path, PluginSchema, MethodSchema, NavError-      Functor.hs           # SchemaF base functor, Fix-    Algebra/-      Recursion.hs         # cata, ana, hylo, para, apo (pure + monadic)-      Navigate.hs          # Path navigation (paramorphism)-      Walk.hs              # Tree walking (hylomorphism)-      Render.hs            # Schema → text rendering-    CLI/-      Parse.hs             # IR-driven --flag parsing → typed JSON-      Help.hs              # Auto-generated help from IR-      Transform.hs         # Path expansion, env var substitution-      Template.hs          # Mustache template generation from IR-    IR/-      Types.hs             # IR, TypeDef, MethodDef, TypeRef-      Builder.hs           # Schema → IR (hylomorphism + type dedup)-    Backend/-      Discovery.hs         # Registry discovery, health checks-    Self/-      Commands.hs          # _self meta-commands (scan, templates)--../plexus-protocol/        # Shared Plexus types (sibling package)-```--## Docker--Synapse can be run in a Docker container for easy deployment and testing.--### Build Docker Image--```bash-# From the synapse directory-docker build -t synapse:latest .--# Or use docker-compose-docker-compose build-```--### Run with Docker--```bash-# Show help-docker run --rm synapse:latest--# Call a method (requires --network host to access local backends)-docker run --rm --network host synapse:latest substrate echo.echo --message "hello"--# Enable debug logging-docker run --rm --network host -e LOG_LEVEL=debug synapse:latest substrate hash--# Connect to remote backend-docker run --rm synapse:latest -H 192.168.1.100 -P 5001 backend method--# Run protocol validation-docker run --rm --network host synapse:latest _self debug localhost 4444 substrate-```--### Docker Compose--```bash-# Show help-docker-compose run --rm synapse--# Run a method-docker-compose run --rm synapse synapse substrate echo.echo --message "hello"--# Debug connection-BACKEND=substrate PLEXUS_PORT=4444 docker-compose --profile debug up--# With environment variables-LOG_LEVEL=debug docker-compose run --rm synapse synapse substrate hash-```--### Image Details--- **Base**: debian:bookworm-slim (minimal runtime)-- **Size**: ~200MB (multi-stage build)-- **User**: Non-root user (uid 1000)-- **Default log level**: error (quiet mode)-- **Network**: Use `--network host` to access localhost backends--## Development--```bash-cabal build                        # Build-cabal test                         # Run tests (needs backend on localhost:4444)-cabal install                      # Install synapse binary-cabal build -f build-examples      # Build optional examples-scripts/naming-gate.sh             # The naming gate: each line that says the retired word (-c: the count)-```--A Plexus backend is a *service* (NAMING-9; `~/AGENTS.md` "Naming"):-`test-suite naming-gate` runs the gate, so `cabal test` fails the day the-retired word is written again.--## License--MIT+# synapse++The command line of every Plexus RPC service: it reads a service's own+schema and offers its activations, methods and flags.++## Most people want plexus-rpc++[plexus-rpc](https://github.com/hypermemetic-ai/plexus-rpc) is the front+door to Plexus RPC: its README builds a service in a few lines of Rust and+calls it. The service in every example below is that one: `myservice`, with+an `echo` activation, on `ws://127.0.0.1:4444`.++## Install++The package is `plexus-synapse` and its executable is `synapse`. It builds+with GHC 9.8.4 and cabal. Version 4.2.0 builds from this repository, with+[plexus-protocol](https://github.com/hypermemetic-ai/plexus-protocol) 0.8+checked out beside it:++```sh+git clone https://github.com/hypermemetic-ai/synapse+git clone https://github.com/hypermemetic-ai/plexus-protocol+cd synapse+echo 'packages: ../plexus-protocol/' > cabal.project.local+cabal update+cabal install exe:synapse -w ghc-9.8.4+synapse --version+```++[Hackage](https://hackage.haskell.org/package/plexus-synapse) holds+`plexus-synapse` 4.1.0.++## An example++Name the service, then an activation, and synapse lists its methods.++<!-- plexus-rpc: examples/echo/out/echo.txt -->+```console+$ synapse myservice echo+echo v0.1.0+  Say things back.++USAGE+  synapse myservice echo <method> [flags]++METHODS+  count     Ticks from 1 up to `to`.+  schema    Get plugin or method schema++Run 'synapse myservice echo <method> --help' for its options.+Run 'synapse --help' for synapse's own options.+```++A method's flags are its parameters.++<!-- plexus-rpc: examples/echo/out/help.txt -->+```console+$ synapse myservice echo count --help+Ticks from 1 up to `to`.++Usage: synapse myservice echo count --to <TO>++Options:+  --to <uint32>  the last tick++A value may be read from a file (--flag @FILE) or stdin (--flag -);+@@text sends a literal @text.++Example:+  synapse myservice echo count --to 1++Run 'synapse --help' for synapse's own options.+```++A call prints each item of the answer as it arrives.++<!-- plexus-rpc: examples/echo/out/count.txt -->+```console+$ synapse myservice echo count --to 3+n: 1+type: tick+n: 2+type: tick+n: 3+type: tick+```++On a service with sign-in, a caller signs in once with a key, and every+later call carries the session.++<!-- plexus-rpc: examples/users/out/login.txt -->+```console+$ synapse _login myservice --key dev --as dev+signed in to myservice at 127.0.0.1:4444 as dev+  principal key:b379e10bed307ff7a5f367ef07433434729d4ab7589cace401cd957da8c73549+  scope     the key's own grants+  until     2026-11-12 03:22:56 UTC+  kept in   ~/.plexus/sessions/127.0.0.1_4444/dev.json+```++<!-- plexus-rpc: examples/users/out/hello.txt -->+```console+$ synapse myservice echo hello+you: key:b379e10bed307ff7a5f367ef07433434729d4ab7589cace401cd957da8c73549+```++Each block above is a file under plexus-rpc's+[`examples/`](https://github.com/hypermemetic-ai/plexus-rpc/tree/main/examples),+which `scripts/examples.sh` there writes again from synapse's own output.++## More++- [Invoking](docs/invoking.md): the order of a command line, flags, lists, values from a file or stdin.+- [Finding a service](docs/finding-a-service.md): the registry, `-H` and `-P`, `--url` and TLS.+- [Signing in](docs/signing-in.md): keys, `_login`, `_logout`, sessions, `--as`.+- [Credentials](docs/credentials.md): `--token`, `--cookie`, `--header` and a service's stored defaults.+- [Output](docs/output.md): `-j`, `--raw`, `-o FILE`, templates, exit codes.+- [Discovery](docs/discovery.md): listings, `--help`, `_find`, `-s`.+- [Outages and the connection holder](docs/outages.md): `--reconnect-for`, `_hold`, `--no-hold`, the schema cache.+- [A stream in](docs/input-streams.md): `--input` from stdin or a file.+- [The IR](docs/ir.md): `-i`, what a client generator reads.+- [Developing](docs/developing.md): building, the tests, the `_self` checks.+- [Changelog](CHANGELOG.md)++MIT.
app/Main.hs view
@@ -30,7 +30,7 @@ import qualified Data.Text.Encoding as TE import Options.Applicative import qualified Options.Applicative.Help.Pretty as Pretty-import System.Environment (getEnvironment)+import System.Environment (getArgs, getEnvironment) import Data.Version (showVersion) import qualified Paths_plexus_synapse as Meta import System.Directory (getHomeDirectory)@@ -78,6 +78,7 @@ import Synapse.Transport import Synapse.CLI.Transform (TransformEnv(..), mkTransformEnv, transformParams, defaultTransformers, injectBooleanDefaults, injectSmartDefaults) import Synapse.CLI.Source (SourceEnv, mkSourceEnv, expandSources, expandValue, stdinWasRead, renderSourceError)+import qualified Synapse.Watch as Watch import Synapse.IR.Builder (buildIR) import Synapse.Renderer (RendererConfig, defaultRendererConfig, renderItem, prettyValue, withMethodPath) import System.Directory (createDirectoryIfMissing, doesFileExist, getHomeDirectory)@@ -142,6 +143,7 @@   , soNoHold        :: Bool          -- ^ SYNAPSE-28: no connection held between runs   , soHoldFor       :: Maybe Text    -- ^ SYNAPSE-28: how long the holder waits with nothing to do (10m)   , soOutput        :: Maybe FilePath  -- ^ SYNAPSE-39: -o FILE, the answer written to FILE whole (- = stdout)+  , soWatch         :: Bool          -- ^ --watch: the call made again on every change of a file it reads   }   deriving Show @@ -401,10 +403,31 @@   args0 <- execParser argsInfo   -- SYNAPSE-28: the connection holder a run started (synapse _hold …)   when (argBackend args0 == Just "_hold") $ runHold (argPath args0)+  -- --watch: the call made again on every change of a file it reads, each+  -- call a run of its own — so before -o takes stdout: every call writes+  -- FILE whole itself+  when (soWatch (argOpts args0)) $ runWatched args0   -- SYNAPSE-39: -o FILE — stdout is FILE's temporary file from here on,   -- renamed into place when the run ends with 0   Output.withOutputFile (soOutput (argOpts args0)) (runArgs args0) +-- | @--watch@ ("Synapse.Watch"): what the command reads from files is+-- followed, and the command run again (without @--watch@) on every change.+-- Refused, 2, for anything that is not a call to a service, and for a call+-- with nothing to follow.+runWatched :: Args -> IO ()+runWatched args = do+  let refuse m = hPutStrLn stderr ("synapse: " <> T.unpack m) >> exitWith (ExitFailure 2)+  case argBackend args of+    Nothing -> refuse "--watch is for a call: a service, a method, and a value read from a file (@FILE)"+    Just b | "_" `T.isPrefixOf` b -> refuse ("--watch is for a call to a service, not " <> b)+    _ -> pure ()+  te <- mkTransformEnv+  env <- mkSourceEnv (teCwd te) (teHome te)+  case Watch.watchedFiles env (soParams (argOpts args)) (argPath args) of+    Left why -> refuse (Watch.renderRefusal why)+    Right files -> getArgs >>= Watch.runWatch files . Watch.childArgs+ -- | The run, once the arguments are read (and stdout is where -o put it). runArgs :: Args -> IO () runArgs args0 = do@@ -1736,7 +1759,15 @@       , "                      @text. -p @params.json and -p - take the whole object the"       , "                      same way. No argument then carries the value, so a body"       , "                      can be as large as the backend accepts"+      , "  --list.field VALUE  one record of a list, a field a flag: --sources.name clock"+      , "                      --sources.source @clock.svelte; a field given again"+      , "                      begins the next record"       , ""+      , "Following a file (before the backend):"+      , "  --watch             the call is made now, and again each time a file it reads"+      , "                      with @FILE changes; stderr says what changed and how long"+      , "                      after the save the answer was whole; Ctrl-C ends it"+      , ""       , "Where the service is (before the backend):"       , "  -P PORT / -H HOST   plain ws://HOST:PORT/ (default 127.0.0.1:4444, the registry)"       , "  --url wss://HOST/ws a service behind TLS (every hosted app), or ws://HOST:PORT/PATH;"@@ -2169,6 +2200,9 @@   soHoldFor <- optional $ T.pack <$> strOption     ( long "hold-for" <> metavar "DURATION"    <> help "How long the connection holder keeps the signed-in socket open with nothing to do (10m, 90s, 1h; else SYNAPSE_HOLD_FOR, else 10m)" )+  soWatch <- switch+    ( long "watch"+   <> help "Make the call now, and again each time a file it reads (--flag @FILE, -p @FILE) changes: the command as written, the file read anew; what changed, how the call ended and how long after the save are said on stderr; Ctrl-C ends it" )   soOutput <- optional $ strOption     ( long "output" <> short 'o' <> metavar "FILE"    <> help "Write the answer to FILE, not stdout: whole, in the same form (-j lines with -j), renamed into place when the call succeeds (a failed call leaves no FILE); 0600; a stream's items appended as they come; - is stdout" )
plexus-synapse.cabal view
@@ -1,6 +1,6 @@ cabal-version:      3.0 name:               plexus-synapse-version:            4.1.0+version:            4.2.0 synopsis:           Schema-driven CLI for Plexus RPC servers description:        Synapse is the command-line frontend for Plexus RPC. It discovers a                     server's methods at runtime and builds its commands, help text,@@ -96,6 +96,7 @@     Synapse.Auth.Loopback     Synapse.Hold     Synapse.Input+    Synapse.Watch     Synapse.SchemaStore   other-modules:    Paths_plexus_synapse   autogen-modules:  Paths_plexus_synapse@@ -103,7 +104,7 @@     base >= 4.17 && < 5,     -- SYNAPSE-28: setCallRouter, substrateRpcSub, unsubscribe; RETURNS-12:     -- the plexus 0.7 schema and envelope-    plexus-protocol >= 0.7 && < 0.8,+    plexus-protocol >= 0.8 && < 0.9,     aeson >= 2.0 && < 2.3,     aeson-pretty >= 0.8 && < 0.9,     text >= 2.0 && < 2.2,@@ -521,6 +522,8 @@   -- of the ticket's Required behavior table.   type:             exitcode-stdio-1.0   main-is:          IR3Spec.hs+  other-modules:    Paths_plexus_synapse+  autogen-modules:  Paths_plexus_synapse   build-depends:     base >= 4.17 && < 5,     plexus-protocol,@@ -654,7 +657,8 @@   -- 500) through one holder whose memory stays flat.   type:             exitcode-stdio-1.0   main-is:          HoldSpec.hs-  other-modules:    MockService, Plexus07+  other-modules:    MockService, Plexus07, Paths_plexus_synapse+  autogen-modules:  Paths_plexus_synapse   build-tool-depends: plexus-synapse:synapse   build-depends:     base >= 4.17 && < 5,@@ -719,6 +723,35 @@   -- resent, a write that went out exit 75).   type:             exitcode-stdio-1.0   main-is:          PipeSpec.hs+  other-modules:    MockService, Plexus07, Paths_plexus_synapse+  autogen-modules:  Paths_plexus_synapse+  build-tool-depends: plexus-synapse:synapse+  build-depends:+    base >= 4.17 && < 5,+    aeson >= 2.2 && < 2.3,+    bytestring >= 0.11 && < 0.13,+    containers >= 0.6 && < 0.8,+    directory >= 1.3 && < 1.4,+    filepath >= 1.4 && < 1.6,+    network >= 3.1 && < 3.3,+    process >= 1.6 && < 1.7,+    temporary >= 1.3 && < 1.4,+    text >= 2.0 && < 2.2,+    vector >= 0.12 && < 0.14,+    websockets >= 0.13 && < 0.14,+    hspec >= 2.10 && < 2.12+  hs-source-dirs:   test+  default-language: GHC2021+  default-extensions:+    OverloadedStrings+  ghc-options:      -threaded++test-suite nav-dynamic-test+  -- NEST-21: the built synapse steps into a dynamic child's names+  -- (plexus-core's config.{key}) by asking the service for the instance's+  -- schema; an unknown name is still Command not found.+  type:             exitcode-stdio-1.0+  main-is:          NavDynamicSpec.hs   other-modules:    MockService, Plexus07   build-tool-depends: plexus-synapse:synapse   build-depends:@@ -750,10 +783,45 @@   -- nothing sent.   type:             exitcode-stdio-1.0   main-is:          OutputSpec.hs+  other-modules:    MockService, Plexus07, Paths_plexus_synapse+  autogen-modules:  Paths_plexus_synapse+  build-tool-depends: plexus-synapse:synapse+  build-depends:+    base >= 4.17 && < 5,+    aeson >= 2.2 && < 2.3,+    bytestring >= 0.11 && < 0.13,+    containers >= 0.6 && < 0.8,+    directory >= 1.3 && < 1.4,+    filepath >= 1.4 && < 1.6,+    network >= 3.1 && < 3.3,+    process >= 1.6 && < 1.7,+    temporary >= 1.3 && < 1.4,+    text >= 2.0 && < 2.2,+    unix >= 2.7 && < 2.9,+    vector >= 0.12 && < 0.14,+    websockets >= 0.13 && < 0.14,+    hspec >= 2.10 && < 2.12+  hs-source-dirs:   test+  default-language: GHC2021+  default-extensions:+    OverloadedStrings+  ghc-options:      -threaded++test-suite watch-test+  -- synapse --watch: Synapse.Watch's own parts (which files a command+  -- reads, the two commands that cannot be watched, the wait for a change:+  -- a write, a truncate and its write, a save by rename, a file gone and+  -- back), and the built synapse against the mock service — the call at+  -- once and again on a change with the new contents, answers alone on+  -- stdout, a failing call that ends nothing, -o FILE whole per call, the+  -- refusals, Ctrl-C 130.+  type:             exitcode-stdio-1.0+  main-is:          WatchSpec.hs   other-modules:    MockService, Plexus07   build-tool-depends: plexus-synapse:synapse   build-depends:     base >= 4.17 && < 5,+    plexus-synapse,     aeson >= 2.2 && < 2.3,     bytestring >= 0.11 && < 0.13,     containers >= 0.6 && < 0.8,
src/Synapse/Algebra/Navigate.hs view
@@ -32,8 +32,9 @@ import Data.List (find)  import Synapse.Schema.Types+import Plexus.Schema.Recursive (MethodRole(..), isSlotRole) import Synapse.Monad-import Synapse.Transport (fetchSchemaAt)+import Synapse.Transport (fetchSchemaAt, fetchSlotSchemaAt) import Synapse.Cache (fetchCached)  -- | The navigation algebra type (conceptual)@@ -72,6 +73,17 @@ -- | Navigate from a given schema -- visited: path taken so far -- target: remaining path to navigate+--+-- SYNAPSE-41 (NEST-21's start): a schema's slots are open names. A slot is+-- a method whose role is a dynamic child (NEST-5, @config.{key}@: its names+-- sit directly under the activation) or a peer slot (NEST-7, @dyn.peer@: its+-- names sit under the method, @dyn.peer.<name>@). A name a schema does not+-- list is asked of the service (@<path>.<name>.schema@) and stepped into if+-- the service answers it; one it says is not there is @Command not found@;+-- any other failure (an outage, a refusal, a sign-in) is that failure. A+-- slot's instance is a tree of its own — a peer is another service, a key+-- one more instance of the slot's type — so its hashes are no cycle with+-- the path that reached it. navigateFrom :: PluginSchema -> Path -> Path -> SynapseM SchemaView navigateFrom schema visited = \case   -- Empty target: we've arrived@@ -82,20 +94,59 @@     -- First check if seg is a child namespace     case findChild seg schema of       Just child -> do-        -- Check for cycle before descending-        checkCycle (csHash child) (visited ++ [seg])-        -- Fetch child schema (with caching)-        childSchema <- fetchCached (csHash child) (fetchSchemaAt (visited ++ [seg]))-        -- Recurse into child-        navigateFrom childSchema (visited ++ [seg]) rest+        let here = visited ++ [seg]+            -- a slot's listed instance starts a tree of its own+            fresh = if hasSlot schema then withFreshVisited else id+        fresh $ do+          -- Check for cycle before descending+          checkCycle (csHash child) here+          -- Fetch child schema (with caching)+          childSchema <- fetchCached (csHash child) (fetchSchemaAt here)+          -- Recurse into child+          navigateFrom childSchema here rest        Nothing ->         -- Not a child — check if it's a method         case findMethod seg schema of           Just method+            -- a peer slot the schema does not list as a child: the next+            -- segment is a peer's name+            | MethodRolePeer{} <- methodRole method+            , (name:rest') <- rest ->+                stepIntoSlot (visited ++ [seg]) name rest' (NotFound name (visited ++ [seg]) Nothing)             | null rest -> pure $ ViewMethod method (visited ++ [seg])             | otherwise -> throwNav $ MethodNotTerminal seg visited-          Nothing -> throwNav $ NotFound seg visited (Just schema)+          Nothing+            -- a dynamic child's key: a name directly under the activation+            | hasDynamicChild schema ->+                stepIntoSlot visited seg rest (NotFound seg visited (Just schema))+            | otherwise -> throwNav $ NotFound seg visited (Just schema)++-- | SYNAPSE-41: step into the name @name@ of a slot at @path@ — asked of the+-- service, a tree of its own — or say @notFound@ when the service says it+-- is not there.+stepIntoSlot :: Path -> Text -> Path -> NavError -> SynapseM SchemaView+stepIntoSlot path name rest notFound = do+  let here = path ++ [name]+  found <- fetchSlotSchemaAt here+  case found of+    Nothing -> throwNav notFound+    Just instanceSchema -> withFreshVisited $ do+      checkCycle (psHash instanceSchema) here+      navigateFrom instanceSchema here rest++-- | NEST-21: whether a schema has a dynamic child slot (its names directly+-- under it).+hasDynamicChild :: PluginSchema -> Bool+hasDynamicChild = any (isDynamic . methodRole) . psMethods+  where+    isDynamic MethodRoleDynamicChild{} = True+    isDynamic _ = False++-- | SYNAPSE-41: whether a schema has a slot of either kind — its children+-- are then a slot and its instances.+hasSlot :: PluginSchema -> Bool+hasSlot = any (isSlotRole . methodRole) . psMethods  -- | Find a child by namespace findChild :: Text -> PluginSchema -> Maybe ChildSummary
src/Synapse/CLI/Parse.hs view
@@ -234,6 +234,8 @@ fieldType :: IR -> TypeRef -> Text -> Maybe TypeRef fieldType ir ref name = case ref of   RefOptional inner -> fieldType ir inner name+  -- a list of records: the field is one record's (--sources.name)+  RefArray inner -> fieldType ir inner name   RefNamed qn -> case tdKind <$> Map.lookup (qualifiedNameFull qn) (irTypes ir) of     Just (KindStruct fields) -> fdType <$> find ((== name) . fdName) fields     Just (KindEnum _ variants _) -> fdType <$> find ((== name) . fdName) (concatMap vdFields variants)@@ -372,17 +374,23 @@    RefArray innerType ->     -- Collect all repeated --key value entries; for a list of scalars each-    -- entry is itself a comma-separated record (objects/lists/any stay whole)-    let rawValues = [val | ("", val) <- kvs]-        elements val+    -- entry is itself a comma-separated record (objects/lists/any stay whole).+    -- A record of the list may also be written a field a flag+    -- (--sources.name clock --sources.source @clock.svelte), which is how+    -- one of its fields is read from a file: the record is built by the+    -- element's type, as a nested parameter is, and a field given a second+    -- time begins the next record. Records and whole values keep the order+    -- they were written in.+    let elements val           | isScalarElement ir innerType =               either (Left . MalformedListValue (pdName param) val) Right (splitListValue val)           | otherwise = Right [val]-    in if null rawValues+        built = \case+          Left val -> map (buildTypedValue ir innerType) <$> elements val+          Right fields -> (: []) <$> buildParamValue ir param { pdType = innerType } fields+    in if null kvs        then Left $ InvalidValue (pdName param) "array requires at least one value"-       else do-         values <- concat <$> traverse elements rawValues-         Right $ Array $ V.fromList $ map (buildTypedValue ir innerType) values+       else Array . V.fromList . concat <$> traverse built (listPieces kvs)    RefJson ->     -- Dynamic type, try to parse as JSON or use as string@@ -405,6 +413,21 @@     wholeJson = case lookup "" kvs of       Just val -> Right $ inferValue val       Nothing -> Left $ InvalidValue (pdName param) "pass the value as JSON (or the whole params with -p)"++-- | A list's flags in the order they were written: a whole value+-- (@--sources '{…}'@, 'Left') or one record's fields (@--sources.name a+-- --sources.source b@, 'Right'). A record ends at a whole value and where a+-- field is given a second time, which begins the next.+listPieces :: [(Text, Text)] -> [Either Text [(Text, Text)]]+listPieces = go []+  where+    go cur [] = flush cur+    go cur (("", val) : rest) = flush cur ++ Left val : go [] rest+    go cur (kv@(k, _) : rest)+      | k `elem` map fst cur = flush cur ++ go [kv] rest+      | otherwise = go (cur ++ [kv]) rest+    flush [] = []+    flush cur = [Right cur]  -- | Build value from a TypeDef buildFromTypeDef :: IR -> Text -> TypeDef -> [(Text, Text)] -> Either ParseError Value
src/Synapse/CLI/Source.hs view
@@ -25,6 +25,7 @@   , mkSourceEnv   , expandSources   , expandValue+  , sourcePath   , stdinWasRead   , renderSourceError   ) where@@ -92,15 +93,25 @@ -- | One value: @-@ is stdin, @\@\@x@ is the literal @\@x@, @\@path@ is that -- file, anything else is itself. expandValue :: SourceEnv -> Text -> Text -> IO (Either SourceError Text)-expandValue env@SourceEnv{..} key val+expandValue env key val   | val == "-" = Right <$> readStdinOnce env   | "@@" `T.isPrefixOf` val = pure (Right (T.drop 1 val))-  | Just path <- T.stripPrefix "@" val, not (T.null path) = do-      r <- try (BS.readFile (resolve path)) :: IO (Either IOException BS.ByteString)+  | Just file <- sourcePath env val = do+      r <- try (BS.readFile file) :: IO (Either IOException BS.ByteString)       pure $ case r of         Left e -> Left SourceUnreadable { seKey = key, seSource = val, seWhy = T.pack (ioeGetErrorString e) }         Right bytes -> Right (decode bytes)   | otherwise = pure (Right val)++-- | The file a value names (@\@path@): where 'expandValue' reads it from —+-- @~/@ the home directory, a relative path under the working directory.+-- 'Nothing' for a value that is itself: no leading @\@@, the literal+-- @\@\@x@, a lone @\@@. @--watch@ follows exactly these files.+sourcePath :: SourceEnv -> Text -> Maybe FilePath+sourcePath SourceEnv{..} val+  | "@@" `T.isPrefixOf` val = Nothing+  | Just path <- T.stripPrefix "@" val, not (T.null path) = Just (resolve path)+  | otherwise = Nothing   where     resolve p = case (T.unpack p, seHome) of       ('~' : '/' : rest, Just home) -> home </> rest
src/Synapse/Transport.hs view
@@ -7,6 +7,7 @@ module Synapse.Transport   ( -- * Schema Fetching     fetchSchema+  , fetchSlotSchemaAt   , fetchSchemaAt   , fetchServiceIR   , rootSchemaKnown@@ -154,6 +155,42 @@           pure schema       liftIO $ modifyIORef' memo (Map.insert path schema)       pure schema++-- | SYNAPSE-41: the schema of a name in a slot (a dynamic child's key, a+--   peer's name) — @Nothing@ when the service says there is nothing there+--   (activation or method not found, a slot's @not_found@). Every other+--   failure propagates as 'fetchSchemaAt' raises it: an outage, a refusal,+--   a sign-in, an unreadable answer, and a cache miss (which sends the call+--   to the server, SYNAPSE-28). Memoized and cached as 'fetchSchemaAt'.+fetchSlotSchemaAt :: Path -> SynapseM (Maybe PluginSchema)+fetchSlotSchemaAt path = do+  memo <- asks seFetched+  known <- liftIO $ Map.lookup path <$> readIORef memo+  case known of+    Just schema -> pure (Just schema)+    Nothing -> do+      src <- asks seSchemaSource+      found <- case src of+        FromCache st -> do+          cached <- liftIO $ Store.readSchema st path+          maybe (throwError (CacheMiss ("no cached schema at " <> showPath path))) (pure . Just) cached+        FromServer st -> do+          logger <- getLogger+          cfg <- getConfig+          result <- liftIO $ R.retrying (whereOf cfg) $ ST.fetchSchemaAtIfAny cfg path+          case result of+            Left err -> do+              Log.logInfo logger Log.SubsystemSchema $+                "Slot schema fetch failed: " <> showPath path <> " - " <> transportErrorToText err+              throwNav $ FetchError (transportErrorToText err) path+            Right Nothing -> do+              Log.logDebug logger Log.SubsystemSchema $ "Nothing in the slot at " <> showPath path+              pure Nothing+            Right (Just schema) -> do+              liftIO $ mapM_ (\s -> Store.writeSchema s path schema) st+              pure (Just schema)+      forM_ found $ \schema -> liftIO $ modifyIORef' memo (Map.insert path schema)+      pure found  -- | RETURNS-40: the service's own IR of the walk from @path@ — one call, --   @<backend>.ir@ with the path as its namespace (none: the whole
+ src/Synapse/Watch.hs view
@@ -0,0 +1,227 @@+{-# LANGUAGE LambdaCase #-}+{-# LANGUAGE OverloadedStrings #-}+{-# LANGUAGE ScopedTypeVariables #-}+{-# LANGUAGE TupleSections #-}++-- | @--watch@: a call made again each time a file it reads changes.+--+-- The owner, 2026-11-16, of writing a component against a running service+-- and seeing it drawn as it is written: "write the change into synapse for+-- now". A value read from a file (@--flag \@FILE@, @-p \@FILE@, SYNAPSE-10)+-- is read once, so every save was the command run again by hand. With+-- @--watch@ synapse does that:+--+-- @+-- synapse --watch -P 4460 menger ui author --bundle live \\+--   --sources.name clock --sources.profile svelte/1 --sources.source \@clock.svelte+-- @+--+-- * the call is made at once, then again on every change of a file the+--   command names with @\@@ — the command as written, the files read anew;+-- * __each call is a process of its own__ (this binary, the same arguments+--   without @--watch@), so a call under @--watch@ is the call run by hand:+--   the same answer, the same exit code, the same @-o FILE@ written whole,+--   and nothing of one call's state left for the next. The connection is+--   the holder's (SYNAPSE-28), so a call is still one round trip;+-- * a file is looked at every 20 ms (its modification time and size — no+--   watcher's library, and a save by rename is seen as any other), and+--   read once it has stopped changing for 15 ms, so an editor that+--   truncates and writes is one change, not two;+-- * changes that arrive while a call runs are one more call when it ends,+--   however many they were: the last contents are what is sent;+-- * a call that fails ends nothing — its failure is on stderr as it would+--   be, and the next change is the next call. Ctrl-C ends it, 130.+--+-- It is the client's half of writing against a running service, and no+-- faster than the method it calls: a save is one call, answered when the+-- service has done with it.+--+-- stdout carries the calls' answers and nothing else; what the watch has to+-- say (what it follows, and after each call which file changed, how the+-- call ended, how long it took and how long after the save that was) goes+-- to stderr.+--+-- Refused, 2, before anything is called: a command that reads no file+-- (nothing would ever change), and one that reads stdin (it is read once).+module Synapse.Watch+  ( -- * What is watched+    WatchRefusal(..)+  , watchedFiles+  , renderRefusal+  , childArgs++    -- * A file's state+  , Stamp(..)+  , stampOf+  , awaitChange+  , pollMicros+  , settleMicros++    -- * The loop+  , runWatch+  , reportLine+  ) where++import Control.Concurrent (threadDelay)+import Control.Exception (AsyncException(..), IOException, catch, throwIO)+import Control.Monad (when)+import Data.List (intercalate, nub)+import Data.Maybe (listToMaybe, mapMaybe)+import Data.Text (Text)+import qualified Data.Text as T+import Data.Time.Clock (NominalDiffTime, UTCTime, diffUTCTime, getCurrentTime)+import System.Directory (getCurrentDirectory, getFileSize, getModificationTime)+import System.Environment (getExecutablePath)+import System.Exit (ExitCode(..), exitWith)+import System.FilePath (makeRelative)+import System.IO (hFlush, hPutStrLn, stderr, stdout)+import System.Process (CreateProcess(..), proc, waitForProcess, withCreateProcess)++import Synapse.CLI.Source (SourceEnv, sourcePath)++-- ============================================================================+-- What is watched+-- ============================================================================++-- | Why a command cannot be watched.+data WatchRefusal+  = NothingToWatch+    -- ^ no value of the command is read from a file+  | ReadsStdin Text+    -- ^ a value is read from stdin: the flag as written (@-p@, @--body@)+  deriving (Show, Eq)++-- | The files a command reads, in the order it names them, each once:+-- @-p@'s value and every value after the service's name. The values are+-- taken as written, before any flag is paired with its parameter (the+-- method is not known yet): a token that begins with @\@@ is a file exactly+-- when 'Synapse.CLI.Source.expandValue' would read it as one.+watchedFiles :: SourceEnv -> Maybe Text -> [Text] -> Either WatchRefusal [FilePath]+watchedFiles env params path+  | Just flag <- listToMaybe [f | (f, "-") <- values] = Left (ReadsStdin flag)+  | null files = Left NothingToWatch+  | otherwise = Right (nub files)+  where+    values = [("-p", v) | Just v <- [params]] ++ flagValues path+    files = mapMaybe (sourcePath env . snd) values++-- | Each value after the service's name with the flag it follows:+-- @--key value@ and @--key=value@. A token that is no flag's value (a path+-- segment, the method) is paired with the empty flag, and is no file.+flagValues :: [Text] -> [(Text, Text)]+flagValues = go ""+  where+    go _ [] = []+    go prev (t : rest)+      | Just kv <- T.stripPrefix "--" t, not (T.null kv) =+          case T.breakOn "=" kv of+            (k, v) | not (T.null v) -> ("--" <> k, T.drop 1 v) : go "" rest+            _ -> go t rest+      | otherwise = (prev, t) : go "" rest++renderRefusal :: WatchRefusal -> Text+renderRefusal = \case+  NothingToWatch ->+    "--watch follows the files a call reads, and this one reads none: give a value as @FILE "+      <> "(--body @body.md, -p @params.json), and the call is made again each time that file changes"+  ReadsStdin flag ->+    "--watch cannot follow stdin (" <> flag <> " -): stdin is read once. Give the value as @FILE"++-- | The arguments of one call: the command's own, without @--watch@. The+-- option is synapse's, so it stands before the service's name, and the+-- first one is it.+childArgs :: [String] -> [String]+childArgs args = case break (== "--watch") args of+  (before, _ : after) -> before ++ after+  (before, []) -> before++-- ============================================================================+-- A file's state+-- ============================================================================++-- | What is known of a file without reading it: when it was last written+-- and how long it is, or that it is not there.+data Stamp = Gone | Stamp UTCTime Integer+  deriving (Show, Eq)++stampOf :: FilePath -> IO Stamp+stampOf f = (Stamp <$> getModificationTime f <*> getFileSize f)+  `catch` \(_ :: IOException) -> pure Gone++-- | How often the files are looked at, and how long they must have stood+-- still before they are read (microseconds).+pollMicros, settleMicros :: Int+pollMicros = 20000+settleMicros = 15000++-- | Waits until the files are no longer as @seen@ and have stopped+-- changing; answers them as they are now, and which changed. A file that+-- was there and is gone is waited for — a save by rename has it missing+-- for a moment, and a file deleted for good has nothing to send.+awaitChange :: Int -> Int -> [(FilePath, Stamp)] -> IO ([(FilePath, Stamp)], [FilePath])+awaitChange poll settle seen = look >>= waiting+  where+    look = mapM (\(f, _) -> (f,) <$> stampOf f) seen+    vanished now = or [was /= Gone && is == Gone | ((_, was), (_, is)) <- zip seen now]+    waiting now+      | map snd now == map snd seen || vanished now = threadDelay poll >> look >>= waiting+      | otherwise = settling now+    settling prev = do+      threadDelay settle+      now <- look+      if map snd now /= map snd prev || vanished now+        then settling now+        else if map snd now == map snd seen+          -- it changed and changed back (a touch undone): nothing to send+          then waiting now+          else pure (now, [f | ((f, is), (_, was)) <- zip now seen, is /= was])++-- ============================================================================+-- The loop+-- ============================================================================++-- | What stderr says after a call: which call it was, what changed, how it+-- ended, how long the call took and — for a change — how long after the+-- save its answer was whole. A call that ended 0 was /answered/, and no+-- more is claimed: what a service refuses in band (a source that does not+-- compile) is an answer, printed above this line as any answer is.+reportLine :: Int -> [FilePath] -> ExitCode -> NominalDiffTime -> Maybe NominalDiffTime -> String+reportLine n changed code took sinceSave =+  "synapse: #" <> show n <> " " <> what <> ": " <> ended <> " in " <> ms took+    <> maybe "" (\d -> ", " <> ms d <> " after the save") sinceSave+  where+    what = if null changed then "the call as it stands" else intercalate ", " changed <> " changed"+    ended = case code of+      ExitSuccess -> "answered"+      ExitFailure c -> "exit " <> show c+    ms d = show (round (realToFrac d * 1000 :: Double) :: Integer) <> " ms"++-- | The watch: the call now, then again on every change of @files@, each a+-- process of its own running this binary with @args@. Never returns: it+-- ends by Ctrl-C (130), or with a call that was itself interrupted.+runWatch :: [FilePath] -> [String] -> IO a+runWatch files args = do+  exe <- getExecutablePath+  cwd <- getCurrentDirectory+  let shown = makeRelative cwd+  say $ "synapse: watching " <> intercalate ", " (map shown files)+    <> " \x2014 the call is made now, and again on every change; Ctrl-C ends it"+  seen <- mapM (\f -> (f,) <$> stampOf f) files+  let go :: Int -> [FilePath] -> [(FilePath, Stamp)] -> IO a+      go n changed now = do+        t0 <- getCurrentTime+        code <- withCreateProcess (proc exe args) { delegate_ctlc = True } $ \_ _ _ ph -> waitForProcess ph+        t1 <- getCurrentTime+        hFlush stdout+        let saved = [t | (f, Stamp t _) <- now, f `elem` changed]+            sinceSave = if null saved then Nothing else Just (diffUTCTime t1 (maximum saved))+        say (reportLine n (map shown changed) code (diffUTCTime t1 t0) sinceSave)+        -- the call was interrupted (Ctrl-C reaches it too): so is the watch+        when (code == ExitFailure 130) $ exitWith code+        (now', changed') <- awaitChange pollMicros settleMicros now+        go (n + 1) changed' now'+  go 1 [] seen `catch` \case+    UserInterrupt -> exitWith (ExitFailure 130)+    e -> throwIO e+  where+    say = hPutStrLn stderr
test/HoldSpec.hs view
@@ -51,6 +51,8 @@ import System.IO.Temp (withSystemTempDirectory) import System.Posix.Signals (signalProcess, sigKILL, sigTERM) import System.Process (CreateProcess(..), proc, readCreateProcessWithExitCode)+import Data.Version (showVersion)+import qualified Paths_plexus_synapse as Paths import Test.Hspec  import Plexus.Client (SubstrateConfig(..), LostConnection(..), defaultConfig)@@ -362,7 +364,8 @@ cliSpec exe = do   it "is this build" $ do     (_, out, _) <- readCreateProcessWithExitCode (proc exe ["--version"]) ""-    out `shouldStartWith` "4.0"+    -- the built synapse, at this package's version (cabal test puts it on PATH)+    out `shouldStartWith` showVersion Paths.version    -- re-review #5: help names the holder's socket as it is   it "help names holder-6.sock" $ do
test/IR12MethodRoleSpec.hs view
@@ -106,6 +106,7 @@             MethodRoleDynamicChild               { listMethod   = Just "planet_names"               , searchMethod = Nothing+              , childSchema  = Nothing               }      it "decodes StaticChild" $ do@@ -130,6 +131,7 @@       let role = MethodRoleDynamicChild             { listMethod   = Just "planet_names"             , searchMethod = Nothing+            , childSchema  = Nothing             }           encoded = Aeson.toJSON role       case encoded of@@ -151,6 +153,7 @@             { mdRole = MethodRoleDynamicChild                 { listMethod   = Just "planet_names"                 , searchMethod = Nothing+                , childSchema  = Nothing                 }             }           encoded = Aeson.toJSON md@@ -169,6 +172,7 @@             { mdRole = MethodRoleDynamicChild                 { listMethod   = Just "planet_names"                 , searchMethod = Just "search_planets"+                , childSchema  = Nothing                 }             }       case eitherDecode (encode original) :: Either String MethodDef of
test/IR3Spec.hs view
@@ -35,6 +35,8 @@ import qualified Data.Text.Encoding as TE import System.Environment (lookupEnv) import System.FilePath ((</>))+import Data.Version (showVersion)+import qualified Paths_plexus_synapse as Paths import Test.Hspec  import Plexus.Schema.Recursive (MethodSchema(..), PluginSchema(..))@@ -226,7 +228,8 @@     danglingRefs ir `shouldBe` []    it "reports synapse's own version" $-    synapseVersion `shouldBe` "4.0.0"+    -- the package's version, as the cabal file states it+    synapseVersion `shouldBe` T.pack (showVersion Paths.version)  -- ============================================================================ -- The Required behavior table, one row at a time
test/MockService.hs view
@@ -570,6 +570,8 @@       [ "kind" .= ("method_not_found" :: Text), "activation" .= T.dropEnd 1 a, "method" .= dm ]   | Just a <- T.stripPrefix "Activation not found: " m = object       [ "kind" .= ("activation_not_found" :: Text), "activation" .= a ]+  | lookup "error_kind" extra == Just (String "not_found") = object+      [ "kind" .= ("not_found" :: Text), "name" .= m ]   | otherwise = object [ "kind" .= ("execution" :: Text), "message" .= m ]   where     field k = maybe (String "") id (lookup k extra)@@ -598,6 +600,12 @@  override <- readIORef schemaOverride  let ns = if inner == "menger.schema" then "" else T.dropEnd (T.length ".schema") inner  case override >>= lookup ns of+  -- SYNAPSE-41: a schema the override says is refused, or (as a slot+  -- answers an unknown name: plexus-core's PeerError) not there+  Just (String "forbidden") | ".schema" `T.isSuffixOf` inner ->+    err ("needs `" <> inner <> "`") [("error_kind", "forbidden"), ("grant", String inner), ("scope", "*")]+  Just (String "not_found") | ".schema" `T.isSuffixOf` inner ->+    err ("no peer named `" <> ns <> "`") [("error_kind", "not_found")]   Just v | ".schema" `T.isSuffixOf` inner -> dat inner v   _ -> callMethod' sc signedIn inner args dat err 
+ test/NavDynamicSpec.hs view
@@ -0,0 +1,164 @@+{-# LANGUAGE OverloadedStrings #-}+{-# LANGUAGE ScopedTypeVariables #-}++-- | NEST-21: synapse steps into a dynamic child (NEST-5's slot, plexus-core's+-- @config.{key}@): a segment that is neither a child nor a method of a+-- schema with a @dynamic_child@ slot is asked of the service as the slot's+-- instance (@config.transport.schema@) and navigated into —+-- @synapse … config transport insecure_ws get@. A name the service does not+-- answer is still @Command not found@.+--+-- SYNAPSE-41: a peer slot's names too (NEST-7, plexus-dyn's @dyn.peer@), and+-- a refusal or an outage while asking for a name is that failure, never+-- @Command not found@.+module Main (main) where++import Control.Exception (SomeException, try)+import Control.Monad (forM_)+import Data.Aeson+import Data.IORef+import Data.List (isInfixOf)+import Data.Text (Text)+import System.Directory (createDirectoryIfMissing, findExecutable)+import System.Environment (getEnvironment)+import System.Exit (ExitCode(..))+import System.FilePath ((</>))+import System.IO.Temp (withSystemTempDirectory)+import System.Process+import Test.Hspec++import MockService++main :: IO ()+main = hspec $ do+  synapse <- runIO (findExecutable "synapse")+  case synapse of+    Nothing -> it "(the synapse executable is not on PATH)" $ pendingWith "cabal test puts it there"+    Just exe -> navSpec exe++-- | A root with @config@; @config@ a slot @key@ of nodes, each a slot again;+-- @config.transport@ a group, @config.transport.insecure_ws@ a key.+configSchemas :: [(Text, Value)]+configSchemas =+  [ ("", object+      [ "namespace" .= ("menger" :: Text), "version" .= ("1.0.0" :: Text), "description" .= ("Central routing" :: Text)+      , "hash" .= ("r-config" :: Text)+      , "children" .=+          [ object ["namespace" .= ("config" :: Text), "description" .= ("Settings" :: Text), "hash" .= ("c0" :: Text)]+          , object ["namespace" .= ("dyn" :: Text), "description" .= ("Runtime peers" :: Text), "hash" .= ("d0" :: Text)]+          , object ["namespace" .= ("slot" :: Text), "description" .= ("Peers, unlisted" :: Text), "hash" .= ("s0" :: Text)] ] ])+  , ("config", node "config" "c0")+  , ("config.transport", node "config_key" "k0")+  , ("config.transport.insecure_ws", node "config_key" "k0")+    -- SYNAPSE-41: a key the caller may not read: a refusal, not "not found"+  , ("config.secret", String "forbidden")+  ] ++ peerSchemas+  where+    node :: Text -> Text -> Value+    node ns h = object+      [ "namespace" .= ns, "version" .= ("0.11.0" :: Text), "hash" .= h, "description" .= ("A setting" :: Text)+      , "methods" .=+          [ object [ "name" .= ("get" :: Text), "description" .= ("The setting as it stands" :: Text), "hash" .= ("g0" :: Text), "returns" .= object [] ]+          , object [ "name" .= ("names" :: Text), "description" .= ("The names below" :: Text), "hash" .= ("n0" :: Text), "returns" .= object [] ]+          , object [ "name" .= ("key" :: Text), "description" .= ("A setting, or a group of them" :: Text), "hash" .= ("y0" :: Text), "returns" .= object []+                   , "role" .= object ["kind" .= ("dynamic_child" :: Text), "list_method" .= ("names" :: Text)] ]+          ] ]++-- | SYNAPSE-41: peer slots (NEST-7) as plexus-dyn serves them. @dyn@ lists+-- its slot @peer@ as a child and as a method marked @peer@; @dyn.peer@+-- lists the peers it has (@far@) under an untyped dynamic child. A peer is a+-- service of its own: @far@'s @dyn@ has the host's @dyn@'s hash, which is no+-- cycle. @slot@ is a peer slot that lists nothing: its names are asked.+peerSchemas :: [(Text, Value)]+peerSchemas =+  [ ("dyn", act "dyn" "d0" [rpc "names" "The peers' names", peerSlot "peer"]+      [child "peer" "A peer by name" "p0"])+  , ("dyn.peer", act "peer" "p0" [slotMethod "peer"] [child "far" "the peer `far`" "f0"])+  , ("dyn.peer.far", act "far" "f0" [rpc "schema" "Get plugin or method schema"] [child "dyn" "Runtime peers" "d0"])+  , ("dyn.peer.far.dyn", act "dyn" "d0" [rpc "names" "The far side's peers' names", peerSlot "peer"] [])+  , ("dyn.peer.ghost", String "not_found")+  , ("slot", act "slot" "s0" [rpc "names" "The peers' names", peerSlot "peer"] [])+  , ("slot.peer.far", act "far" "f0" [rpc "ping" "Answer pong"] [])+  , ("slot.peer.ghost", String "not_found")+  , ("slot.peer.locked", String "forbidden")+  ]+  where+    act :: Text -> Text -> [Value] -> [Value] -> Value+    act ns h ms cs = object $+      [ "namespace" .= ns, "version" .= ("0.1.0" :: Text), "hash" .= h, "description" .= ns, "methods" .= ms ]+      ++ [ "children" .= cs | not (null cs) ]+    child :: Text -> Text -> Text -> Value+    child ns d h = object ["namespace" .= ns, "description" .= d, "hash" .= h]+    rpc :: Text -> Text -> Value+    rpc n d = object [ "name" .= n, "description" .= d, "hash" .= (n <> "0"), "returns" .= object [] ]+    peerSlot :: Text -> Value+    peerSlot n = object+      [ "name" .= n, "description" .= ("A peer, by name" :: Text), "hash" .= (n <> "1"), "returns" .= object []+      , "role" .= object ["kind" .= ("static_child" :: Text), "peer" .= True, "list_method" .= ("names" :: Text)] ]+    slotMethod :: Text -> Value+    slotMethod n = object+      [ "name" .= n, "description" .= ("A peer, by name" :: Text), "hash" .= (n <> "2"), "returns" .= object []+      , "role" .= object ["kind" .= ("dynamic_child" :: Text)] ]++navSpec :: FilePath -> Spec+navSpec exe = describe "a dynamic child's names (NEST-21)" $ do+  it "steps into config transport insecure_ws" $ withRun $ \run -> do+    (code, out, err) <- run ["config", "transport", "insecure_ws", "get", "--help"]+    (code, err) `shouldBe` (ExitSuccess, "")+    out `shouldSatisfy` ("The setting as it stands" `isInfixOf`)+  it "lists a node's methods" $ withRun $ \run -> do+    (code, out, _) <- run ["config", "transport"]+    code `shouldBe` ExitSuccess+    out `shouldSatisfy` ("get" `isInfixOf`)+  it "still says Command not found for a name the service does not answer" $ withRun $ \run -> do+    (code, _, err) <- run ["config", "nothing", "get"]+    code `shouldBe` ExitFailure 1+    err `shouldSatisfy` ("Command not found: 'nothing'" `isInfixOf`)+  it "says a refusal of a key as the refusal, never as Command not found" $ withRun $ \run -> do+    (code, _, err) <- run ["config", "secret", "get"]+    code `shouldNotBe` ExitSuccess+    err `shouldNotSatisfy` ("Command not found" `isInfixOf`)+    err `shouldSatisfy` ("config.secret.schema" `isInfixOf`)++  describe "a peer slot's names (SYNAPSE-41)" $ do+    it "steps through a listed peer into its own dyn, the same hash as the host's (no cycle)" $ withRun $ \run -> do+      (code, out, err) <- run ["dyn", "peer", "far", "dyn", "names", "--help"]+      (code, err) `shouldBe` (ExitSuccess, "")+      out `shouldSatisfy` ("The far side's peers' names" `isInfixOf`)+    it "lists a peer's own commands" $ withRun $ \run -> do+      (code, out, _) <- run ["dyn", "peer", "far"]+      code `shouldBe` ExitSuccess+      out `shouldSatisfy` ("dyn" `isInfixOf`)+    it "says Command not found for a peer the slot does not have" $ withRun $ \run -> do+      (code, _, err) <- run ["dyn", "peer", "ghost", "dyn", "names"]+      code `shouldBe` ExitFailure 1+      err `shouldSatisfy` ("Command not found: 'ghost'" `isInfixOf`)+    it "asks an unlisted peer's name of the slot, after the slot method" $ withRun $ \run -> do+      (code, out, err) <- run ["slot", "peer", "far", "ping", "--help"]+      (code, err) `shouldBe` (ExitSuccess, "")+      out `shouldSatisfy` ("Answer pong" `isInfixOf`)+    it "says Command not found for an unlisted name the slot does not have" $ withRun $ \run -> do+      (code, _, err) <- run ["slot", "peer", "ghost", "ping"]+      code `shouldBe` ExitFailure 1+      err `shouldSatisfy` ("Command not found: 'ghost'" `isInfixOf`)+    it "says a refused peer as the refusal" $ withRun $ \run -> do+      (code, _, err) <- run ["slot", "peer", "locked", "ping"]+      code `shouldNotBe` ExitSuccess+      err `shouldNotSatisfy` ("Command not found" `isInfixOf`)+    it "still shows the slot method itself" $ withRun $ \run -> do+      (code, out, _) <- run ["slot", "peer", "--help"]+      code `shouldBe` ExitSuccess+      out `shouldSatisfy` ("A peer, by name" `isInfixOf`)+  where+    withRun act = withSystemTempDirectory "nest21" $ \dir -> withMockService todaysService $ \port -> do+      forM_ ["home", "cache", "run"] $ \d -> createDirectoryIfMissing True (dir </> d)+      env0 <- getEnvironment+      let env = [ (k, v) | (k, v) <- env0, k `notElem` ["HOME", "XDG_CACHE_HOME", "XDG_RUNTIME_DIR", "SYNAPSE_AS", "PLEXUS_SESSION"] ]+              ++ [ ("HOME", dir </> "home"), ("XDG_CACHE_HOME", dir </> "cache"), ("XDG_RUNTIME_DIR", dir </> "run")+                 , ("PLEXUS_KEYCHAIN", "off"), ("SYNAPSE_NO_HOLD", "1") ]+          run args = readCreateProcessWithExitCode+            ((proc exe (["--url", "ws://127.0.0.1:" <> show port <> "/ws", "menger"] ++ args)) { env = Just env }) ""+      writeIORef schemaOverride (Just configSchemas)+      r <- try (act run)+      writeIORef schemaOverride Nothing+      either (\(e :: SomeException) -> ioError (userError (show e))) pure r
test/OutputSpec.hs view
@@ -40,6 +40,8 @@ import System.Posix.Files (fileMode, getFileStatus) import System.Process import System.Timeout (timeout)+import Data.Version (showVersion)+import qualified Paths_plexus_synapse as Paths import Test.Hspec  import MockService@@ -55,7 +57,8 @@ outputSpec exe = describe "synapse -o FILE (SYNAPSE-39)" $ do   it "is this build" $ do     (_, out, _) <- readProcessWithExitCode exe ["--version"] ""-    out `shouldStartWith` "4.0.0"+    -- the built synapse, at this package's version (cabal test puts it on PATH)+    out `shouldStartWith` showVersion Paths.version    forM_ [ ([], "", ["tickets", "get", "--id", "MENGER-12"])         , (["-j"], " with -j", ["tickets", "get", "--id", "MENGER-12"])
test/ParseSpec.hs view
@@ -207,6 +207,42 @@         parseParams listIR method [("blocked_by", "\"a,b"), ("title", "t")]           `shouldBe` Left [MalformedListValue "blocked_by" "\"a,b" "a quoted element has no closing quote"] +  describe "a list of records, a field a flag (--links.id a --links.kind b)" $ do+    let links = listParam "links" (RefArray (named "Link"))+        link i k = object [(K.fromText "id", String i), (K.fromText "kind", String k)]+        build = buildParamValue listIR links++    it "dotted flags are one record, built by the element's type" $+      build [("id", "a"), ("kind", "blocks")] `shouldBe` arr [link "a" "blocks"]++    it "a field given a second time begins the next record" $+      build [("id", "a"), ("kind", "blocks"), ("id", "b"), ("kind", "relates")]+        `shouldBe` arr [link "a" "blocks", link "b" "relates"]++    it "the fields of a record may come in any order" $+      build [("kind", "blocks"), ("id", "a"), ("kind", "relates"), ("id", "b")]+        `shouldBe` arr [link "a" "blocks", link "b" "relates"]++    it "a whole value and a record keep the order they were written in" $+      build [("id", "a"), ("kind", "blocks"), ("", "{\"id\":\"b\"}"), ("id", "c"), ("kind", "relates")]+        `shouldBe` arr [link "a" "blocks", String "{\"id\":\"b\"}", link "c" "relates"]++    it "a record missing a required field is refused, naming it" $+      build [("id", "a")] `shouldBe` Left (MissingRequired "links.kind")++    it "an optional list of records is built the same way" $+      buildParamValue listIR (listParam "links" (RefOptional (RefArray (named "Link")))) [("id", "a"), ("kind", "k")]+        `shouldBe` arr [link "a" "k"]++    it "a list with no value at all is still refused" $+      build [] `shouldBe` Left (InvalidValue "links" "array requires at least one value")++    it "from the command line: a field's value is the next argument, whatever it begins with" $ do+      let method = methodWith [links]+          (_, _, flags, _) = parsePathAndParams ["t", "create", "--links.id", "--dashed", "--links.kind", "@@at"]+      (pairFlags listIR method flags >>= parseParams listIR method)+        `shouldBe` Right (object [(K.fromText "links", Array (V.fromList [link "--dashed" "@@at"]))])+   describe "help for list parameters" $ do     it "a list of scalars names the comma form" $       renderParamHelp listIR (listParam "blocked_by" (RefOptional (RefArray (RefPrimitive "string" Nothing))))
test/PipeSpec.hs view
@@ -32,6 +32,8 @@ import System.Process import System.Timeout (timeout) import Control.Concurrent (threadDelay)+import Data.Version (showVersion)+import qualified Paths_plexus_synapse as Paths import Test.Hspec  import MockService@@ -47,7 +49,8 @@ pipeSpec exe = describe "a closed stdout (SYNAPSE-26)" $ do   it "is this build" $ do     (_, out, _) <- readProcessWithExitCode exe ["--version"] ""-    out `shouldStartWith` "4.0"+    -- the built synapse, at this package's version (cabal test puts it on PATH)+    out `shouldStartWith` showVersion Paths.version    -- one reader takes a byte and closes, one closes before anything is   -- printed
+ test/WatchSpec.hs view
@@ -0,0 +1,309 @@+{-# LANGUAGE OverloadedStrings #-}+{-# LANGUAGE ScopedTypeVariables #-}++-- | @synapse --watch@: a call made again each time a file it reads changes.+--+-- In process, "Synapse.Watch"'s own parts: which files a command reads+-- (and the two commands that cannot be watched), the arguments of one+-- call, what is said after a call, and the wait for a change — a write, a+-- truncate-then-write, a save by rename, a file gone and back.+--+-- End to end, the built synapse against the mock service (a home, a cache+-- and a runtime directory of the test's own): the call at once and again on+-- a change with the file's new contents, the answers alone on stdout and+-- what the watch says on stderr, a failing call that ends nothing, @-o+-- FILE@ written whole by every call, the refusals, and Ctrl-C.+module Main (main) where++import Control.Concurrent (forkIO, threadDelay)+import Control.Exception (SomeException, try)+import Control.Monad (forM_, void)+import Data.Aeson+import qualified Data.Aeson.Key as Key+import qualified Data.ByteString as BS+import qualified Data.ByteString.Char8 as BS8+import Data.IORef+import Data.List (isInfixOf, isPrefixOf)+import Data.Text (Text)+import System.Directory (createDirectoryIfMissing, findExecutable, removeFile, renameFile)+import System.Environment (getEnvironment)+import System.Exit (ExitCode(..))+import System.FilePath ((</>))+import System.IO (Handle, hClose, hGetLine, hIsEOF)+import System.IO.Temp (withSystemTempDirectory)+import System.Posix.Signals (sigINT, signalProcess)+import System.Process+import System.Timeout (timeout)+import Test.Hspec++import MockService+import Synapse.CLI.Source (SourceEnv(..))+import Synapse.Watch++main :: IO ()+main = hspec $ do+  unitSpec+  synapse <- runIO (findExecutable "synapse")+  case synapse of+    Nothing -> it "(the synapse executable is not on PATH)" $ pendingWith "cabal test puts it there"+    Just exe -> endToEnd exe++-- ============================================================================+-- In process+-- ============================================================================++unitSpec :: Spec+unitSpec = describe "Synapse.Watch" $ do+  describe "the files a command reads" $ do+    let files params path = do+          cache <- newIORef Nothing+          let env = SourceEnv { seCwd = "/work", seHome = Just "/home/ada", seStdin = pure "", seCache = cache }+          pure (watchedFiles env params path)++    it "a flag's value that names a file, under the working directory" $+      files Nothing ["ui", "author", "--bundle", "live", "--sources.source", "@src/clock.svelte"]+        `shouldReturn` Right ["/work/src/clock.svelte"]++    it "--flag=@FILE, an absolute path and ~/" $+      files Nothing ["t", "amend", "--body=@/tmp/body.md", "--title", "@~/title.txt"]+        `shouldReturn` Right ["/tmp/body.md", "/home/ada/title.txt"]++    it "-p @FILE, first" $+      files (Just "@params.json") ["t", "amend", "--body", "@body.md"]+        `shouldReturn` Right ["/work/params.json", "/work/body.md"]++    it "a file named twice is watched once" $+      files Nothing ["t", "amend", "--body", "@body.md", "--title", "@body.md"]+        `shouldReturn` Right ["/work/body.md"]++    it "@@text is text, and a lone @ is itself: neither is a file" $+      files Nothing ["t", "amend", "--body", "@@handle", "--title", "@", "--id", "@id.txt"]+        `shouldReturn` Right ["/work/id.txt"]++    it "a command that reads no file is refused" $ do+      files Nothing ["t", "amend", "--body", "text"] `shouldReturn` Left NothingToWatch+      files (Just "{\"id\":\"x\"}") ["t", "amend"] `shouldReturn` Left NothingToWatch++    it "a command that reads stdin is refused, naming the flag" $ do+      files Nothing ["t", "amend", "--id", "@id.txt", "--body", "-"] `shouldReturn` Left (ReadsStdin "--body")+      files Nothing ["t", "amend", "--id", "@id.txt", "--body=-"] `shouldReturn` Left (ReadsStdin "--body")+      files (Just "-") ["t", "amend", "--id", "@id.txt"] `shouldReturn` Left (ReadsStdin "-p")++  describe "the arguments of one call" $ do+    it "are the command's without --watch" $+      childArgs ["-P", "4460", "--watch", "-j", "menger", "t", "amend", "--id", "@id.txt"]+        `shouldBe` ["-P", "4460", "-j", "menger", "t", "amend", "--id", "@id.txt"]++    it "only synapse's own: a method's --watch, after it, stays" $+      childArgs ["--watch", "menger", "t", "list", "--watch", "true"]+        `shouldBe` ["menger", "t", "list", "--watch", "true"]++  describe "what is said after a call" $ do+    it "the first call: that it is the call as it stands, how it ended and how long it took" $+      reportLine 1 [] ExitSuccess 0.0834 Nothing+        `shouldBe` "synapse: #1 the call as it stands: answered in 83 ms"++    it "a change: the file, and how long after the save the answer was whole" $+      reportLine 4 ["src/clock.svelte"] ExitSuccess 0.412 (Just 0.4551)+        `shouldBe` "synapse: #4 src/clock.svelte changed: answered in 412 ms, 455 ms after the save"++    it "a call that failed says its exit" $+      reportLine 2 ["a.md", "b.md"] (ExitFailure 1) 0.02 (Just 0.06)+        `shouldBe` "synapse: #2 a.md, b.md changed: exit 1 in 20 ms, 60 ms after the save"++  describe "the wait for a change" $ do+    let scratch act = withSystemTempDirectory "synapse-watch" $ \dir -> do+          let a = dir </> "a.txt"; b = dir </> "b.txt"+          writeFile a "one"; writeFile b "one"+          seen <- mapM (\f -> (,) f <$> stampOf f) [a, b]+          act dir a b seen+        waited = timeout 5000000 . awaitChange pollMicros settleMicros+        later act = void (forkIO (threadDelay 150000 >> act))++    it "does not end while nothing changes" $ scratch $ \_ _ _ seen ->+      timeout 400000 (awaitChange pollMicros settleMicros seen) `shouldReturn` Nothing++    it "ends on a write, naming the file that changed and no other" $ scratch $ \_ a _ seen -> do+      later (writeFile a "two, longer")+      Just (now, changed) <- waited seen+      changed `shouldBe` [a]+      now `shouldNotBe` seen++    it "a truncate and the write after it are one change, read when it is whole" $ scratch $ \_ a _ seen -> do+      later (writeFile a "" >> threadDelay 5000 >> writeFile a "the whole of it")+      Just (_, changed) <- waited seen+      changed `shouldBe` [a]+      readFile a `shouldReturn` "the whole of it"++    it "a save by rename is a change" $ scratch $ \dir a _ seen -> do+      later (writeFile (dir </> "a.tmp") "renamed into place" >> renameFile (dir </> "a.tmp") a)+      Just (_, changed) <- waited seen+      changed `shouldBe` [a]++    it "a file gone is waited for, and is a change once it is back" $ scratch $ \_ a _ seen -> do+      removeFile a+      timeout 300000 (awaitChange pollMicros settleMicros seen) `shouldReturn` Nothing+      later (writeFile a "back")+      Just (_, changed) <- waited seen+      changed `shouldBe` [a]++    it "two files changed together are one change naming both" $ scratch $ \_ a b seen -> do+      later (writeFile a "two!" >> writeFile b "two!")+      Just (_, changed) <- waited seen+      changed `shouldBe` [a, b]++-- ============================================================================+-- The built synapse+-- ============================================================================++endToEnd :: FilePath -> Spec+endToEnd exe = describe "synapse --watch, the built synapse against the mock service" $ do+  it "makes the call at once, and again with the file's new contents when it changes" $+    withRun $ \dir spawn -> do+      let idFile = dir </> "id.txt"+      writeFile idFile "MENGER-1"+      writeIORef callsMade []+      watching (spawn ["--watch", "-j"] ["tickets", "amend", "--id", "@" <> idFile, "--body", "x"]) $ \out err _ -> do+        saidBy err "#1 " `shouldReturn` True+        writeFile idFile "MENGER-2"+        saidBy err "#2 " `shouldReturn` True+        said <- readIORef err+        -- what the watch says: what it follows, then each call+        head said `shouldSatisfy` ("synapse: watching " `isPrefixOf`)+        head said `shouldSatisfy` ("id.txt" `isInfixOf`)+        line "#1 " said `shouldSatisfy` ("synapse: #1 the call as it stands: answered in " `isPrefixOf`)+        line "#2 " said `shouldSatisfy` (\l -> "id.txt changed: answered in " `isInfixOf` l && " after the save" `isInfixOf` l)+        -- stdout: the answers and nothing else, the second with the new contents+        answers <- readIORef out+        filter ("MENGER-1" `isInfixOf`) answers `shouldNotBe` []+        filter ("MENGER-2" `isInfixOf`) answers `shouldNotBe` []+        filter ("synapse:" `isInfixOf`) answers `shouldBe` []+        -- two calls, each sent once+        (length . filter (== "tickets.amend") <$> readIORef callsMade) `shouldReturn` 2++  it "a call that fails ends nothing: the next change is the next call" $+    withRun $ \dir spawn -> do+      let params = dir </> "params.json"+      writeFile params "{\"id\":\"MENGER-1\",\"body\":\"x\"}"+      watching (spawn ["--watch", "-j", "-p", "@" <> params] ["tickets", "amend"]) $ \out err _ -> do+        saidBy err "#1 " `shouldReturn` True+        writeFile params "{\"id\":"+        saidBy err "#2 " `shouldReturn` True+        writeFile params "{\"id\":\"MENGER-3\",\"body\":\"x\"}"+        saidBy err "#3 " `shouldReturn` True+        said <- readIORef err+        line "#2 " said `shouldSatisfy` ("params.json changed: exit " `isInfixOf`)+        line "#3 " said `shouldSatisfy` ("params.json changed: answered in " `isInfixOf`)+        (filter ("MENGER-3" `isInfixOf`) <$> readIORef out) >>= (`shouldNotBe` [])++  it "-o FILE is written whole by every call" $+    withRun $ \dir spawn -> do+      let idFile = dir </> "id.txt"; answer = dir </> "answer.out"+      writeFile idFile "MENGER-1"+      watching (spawn ["--watch", "-j", "-o", answer] ["tickets", "amend", "--id", "@" <> idFile, "--body", "x"]) $ \out err _ -> do+        saidBy err "#1 " `shouldReturn` True+        (BS8.unpack <$> BS.readFile answer) >>= (`shouldSatisfy` ("MENGER-1" `isInfixOf`))+        writeFile idFile "MENGER-2"+        saidBy err "#2 " `shouldReturn` True+        now <- BS8.unpack <$> BS.readFile answer+        now `shouldSatisfy` ("MENGER-2" `isInfixOf`)+        now `shouldSatisfy` (not . ("MENGER-1" `isInfixOf`))+        readIORef out `shouldReturn` []++  it "Ctrl-C ends it, 130" $+    withRun $ \dir spawn -> do+      let idFile = dir </> "id.txt"+      writeFile idFile "MENGER-1"+      watching (spawn ["--watch"] ["tickets", "amend", "--id", "@" <> idFile, "--body", "x"]) $ \_ err ph -> do+        saidBy err "#1 " `shouldReturn` True+        Just pid <- getPid ph+        signalProcess sigINT pid+        timeout 5000000 (waitForProcess ph) `shouldReturn` Just (ExitFailure 130)++  forM_ [ ("a call that reads no file", ["tickets", "amend", "--id", "MENGER-1"], "reads none")+        , ("a call that reads stdin", ["tickets", "amend", "--id", "@id.txt", "--body", "-"], "cannot follow stdin (--body -)") ]+    $ \(what, call, why) ->+   it (what <> " is refused, 2, and nothing is called") $+    withRun $ \_ spawn -> do+      writeIORef callsMade []+      (code, out, err) <- readCreateProcessWithExitCode (spawn ["--watch"] call) { std_in = NoStream } ""+      (code, out) `shouldBe` (ExitFailure 2, "")+      err `shouldSatisfy` (why `isInfixOf`)+      readIORef callsMade `shouldReturn` []++  it "--watch is for a call to a service: a meta-command is refused, 2" $+    withRun $ \_ _ -> do+      (code, _, err) <- readProcessWithExitCode exe ["--watch", "_key", "list"] ""+      code `shouldBe` ExitFailure 2+      err `shouldSatisfy` ("--watch is for a call to a service, not _key" `isInfixOf`)+  where+    -- a run of the built synapse against a fresh mock service; @spawn+    -- globals args@+    withRun act = withSystemTempDirectory "synapse-watch" $ \dir -> withMockService todaysService $ \port -> do+      forM_ ["home", "cache", "run"] $ \d -> createDirectoryIfMissing True (dir </> d)+      env0 <- getEnvironment+      let env' = [ (k, v) | (k, v) <- env0, k `notElem` ["HOME", "XDG_CACHE_HOME", "XDG_RUNTIME_DIR", "SYNAPSE_AS", "PLEXUS_SESSION", "SYNAPSE_RECONNECT_FOR"] ]+              ++ [ ("HOME", dir </> "home"), ("XDG_CACHE_HOME", dir </> "cache"), ("XDG_RUNTIME_DIR", dir </> "run")+                 , ("PLEXUS_KEYCHAIN", "off"), ("SYNAPSE_HOLD_FOR", "3s") ]+          spawn globals args = (proc exe (globals ++ ["--url", "ws://127.0.0.1:" <> show port <> "/ws", "menger"] ++ args))+            { env = Just env', std_in = CreatePipe, std_out = CreatePipe, std_err = CreatePipe }+      writeIORef schemaOverride (Just [("tickets", ticketsWithWrites)])+      r <- try (act dir spawn)+      writeIORef schemaOverride Nothing+      either (\(e :: SomeException) -> ioError (userError (show e))) pure r++    -- a watch running: its stdout and stderr gathered a line at a time+    -- (oldest first), ended when the body is over+    watching :: CreateProcess -> (IORef [String] -> IORef [String] -> ProcessHandle -> IO a) -> IO a+    watching cp body = do+      (Just inp, Just out, Just err, ph) <- createProcess cp+      hClose inp+      outLines <- gather out+      errLines <- gather err+      r <- try (body outLines errLines ph)+      terminateProcess ph+      _ <- timeout 5000000 (waitForProcess ph)+      either (\(e :: SomeException) -> ioError (userError (show e))) pure r++    gather :: Handle -> IO (IORef [String])+    gather h = do+      ref <- newIORef []+      let loop = do+            eof <- hIsEOF h+            if eof then pure () else do+              l <- hGetLine h+              atomicModifyIORef' ref (\ls -> (ls ++ [l], ()))+              loop+      _ <- forkIO (void (try loop :: IO (Either SomeException ())))+      pure ref++    -- whether a line saying @what@ has come, within 20 s+    saidBy :: IORef [String] -> String -> IO Bool+    saidBy ref what = go (400 :: Int)+      where+        go 0 = pure False+        go n = do+          ls <- readIORef ref+          if any (what `isInfixOf`) ls then pure True else threadDelay 50000 >> go (n - 1)++    line what ls = case filter (what `isInfixOf`) ls of+      (l : _) -> l+      [] -> ""++-- | menger's tickets in miniature: a read and a write.+ticketsWithWrites :: Value+ticketsWithWrites = object+  [ "namespace" .= ("tickets" :: Text), "version" .= ("0.5.0" :: Text), "hash" .= ("t0" :: Text)+  , "description" .= ("Plans as data" :: Text)+  , "methods" .=+      [ m "get" "One ticket by id" (Just "read") [("id", True)]+      , m "amend" "Replace a ticket's body" (Just "write") [("id", True), ("body", False)] ] ]+  where+    m :: Text -> Text -> Maybe Text -> [(Text, Bool)] -> Value+    m n d g ps = object $+      [ "name" .= n, "description" .= d, "hash" .= (n <> "0"), "streaming" .= False+      , "params" .= object+          [ "type" .= ("object" :: Text)+          , "required" .= [ p | (p, True) <- ps ]+          , "properties" .= object [ Key.fromText p .= object ["type" .= ("string" :: Text)] | (p, _) <- ps ] ] ]+      <> maybe [] (\g' -> ["group" .= g']) g