add-daemon-method
/add-daemon-method
Dodaje metodę do demona, czyli żądanie na gnieździe Unix, i polecenie CLI, które je wywołuje.
- Autor
- NolwennD ↗
- Repozytorium
- gabier ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 13.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Dodaje metodę do demona, czyli żądanie na gnieździe Unix, i polecenie CLI, które je wywołuje.
Argumenty
/add-daemon-method <method name and what it answers>
Oryginalny opis (EN)
Use to add a method to the daemon (a request the cli or another client can send on its Unix socket), such as an operation of the catalogue (diagnostics, rename) or a new administrative call. Also use to add the cli command that calls it.
Jak działa
- Steps
- A method that answers more than once (a stream)
Podgląd SKILL.md
---
name: add-daemon-method
description: Use to add a method to the daemon (a request the cli or another client can send on its Unix socket), such as an operation of the catalogue (diagnostics, rename) or a new administrative call. Also use to add the cli command that calls it.
argument-hint: '<method name and what it answers>'
---
# Add a method to the daemon
The daemon answers JSON-RPC 2.0, one JSON object per line, on its Unix socket. Its method table is the list given to
`RequestHandler` in the constructor of `DaemonServer` (`modules/daemon`). A method is one small class; nothing else in
the server changes. `status` (answers with a result) and `stop` (answers, then acts) are the two models.
## Steps
1. **Write the test first**, against `RequestHandler` and no socket (`RequestHandlerTest`, `DaemonMethodsTest`): the
method's name, the `result` it answers, what it does once the answer is written, and its refusals. A refusal is an
exception of the shared error package (`GeneratorException` with an `ErrorKey`, `badRequest` for a refused request,
`internalServerError` for a failure of gabier): the handler turns it into the JSON-RPC error that holds the problem
object, and any other exception into the generic internal error. Never catch it in the method. A method of the
catalogue is run against the fake language server (`.claude/rules/workflow.md`, "Fake it until you run it"), never
against a jdtls, in `check`: `DiagnosticsMethodTest` is the model (a `FakeJavaLanguageServer` scripted by the
scenarios of the core, the request line through `RequestHandler`, the result read back with its `protocol` type).
2. **Write the method**: a package-private record implementing `DaemonMethod` (`name()`, `call()` returning an
`Outcome` with the JSON of the result and, when needed, the `afterReply` to run once the answer is written, which is
how `stop` answers before it stops). **Parameters**: the request carries them in `params`, an object of strings
(`RpcRequest.params()`). The method declares the names it needs by overriding `parameters()` (none by default, all
required) and reads them in `call(Map<String, String> params)`, which receives exactly those names: `RequestHandler`
refuses before the call a request with a parameter the method does not take (`unknown-parameter`) or without one it
needs (`missing-parameter`), as a `badRequest` whose `parameters` name it (the unknown one first, the first by name).
The method never checks that they are
there; it checks what they mean (a path that does not exist is its own refusal, like `fileMissing`; a value that
cannot be read as what the method needs is `ParameterException.invalid`, key `invalid-parameter`). A value that is
not a string, and a key repeated in `params`, are refused by `RpcRequest.parse`; a number or a list is written as a
string and read by the method. Every refusal that names a `parameter` in its problem object is answered with the
JSON-RPC code `-32602` (`JsonRpc.PARAMETER`): a refusal of your own that is about one parameter does the same, with
`addParameter(JsonRpc.PARAMETER, name)`; one that is not keeps `-32000`.
Test it with the scripted method of `RequestHandlerTest` (`Reading`): its parameters, what it read, and that a
refused request never reaches `call`. The client writes them with `DaemonClient.call(method, params)` (in `eu.gabier.cli.infrastructure.secondary`).
A method of the catalogue is a record around the use case of the core (`DiagnosticsMethod(Diagnose)`), which maps
the domain types to the `protocol` ones; the positions stay 0-based in the protocol.
A request has no optional parameter: an operation that can be asked in two ways is two methods (`rename`, by position,
and `rename-token`, by identifier), which share the reading of their parameters (`ChangeRequest`, with
`organize-imports`, which takes a file and `dryRun` only) and answer the same
`protocol` type (`ChangedFiles`, which every operation that changes files will answer). A flag is a parameter whose
value is `true` or `false`, anything else being an `invalid-parameter`; a method of the catalogue that writes files
takes `dryRun`.
3. **Register it** in the `List.of(...)` of the `DaemonServer` constructor (which receives the `JavaLanguageServer` the
use cases are built on: the `ServedProject` of the daemon, which starts jdtls at the first request that needs it). A
test on a real socket (`DaemonServerTest`, a temporary directory, never the default path, the fake server) shows it
answers there.
4. **A structured result is a type of `protocol`**, written and read with `Json` (`DaemonStatus` is the model: `toJson()`
for the daemon, `of(Map)` for the client, which refuses a result that is not the expected one with an
`InvalidResponseException`). The cli has no third-party library, so nothing else may parse it. A member that is not
always there is an `Optional` of the record, written only when present and read as absent when missing
(`DaemonStatus.jdtlsFailure`, the reason jdtls failed, is the model). A text that comes from jdtls (a reason, a
message) is hostile input: the result carries it exactly, and whatever prints it for a person goes through
`TerminalText.neutralise`, as the text of `gabier status` does.
5. **The cli command**, if there is one: a **capability** of `modules/cli`, a class of its own that holds its help text,
in the package `eu.gabier.cli.infrastructure.primary` (the command line, with `Capabilities` and `CommandLine`).
Five things, and the line of the operation in `kindOf` of `OperationRunner` (below), and no other file changes:
- the **operation**, declared once in `eu.gabier.cli.domain.Operations` (no protocol type, no JSON): a constant
`public static final Operation <NAME> = new Operation(method, summary, notes, refusals, parameters)`, added to
`all()` in the order of the table of `docs/protocol.md`. It is the one place that names the **typed parameters**
of the method (`Parameter.string`, `.position`, `.integer`, `.bool`, `.array`: name as the daemon reads it,
description; every parameter of a method is required; a line or a column is a `.position`, counted from 1 on this
side, and the description says so; `.integer` is a whole number that is no position, sent as it is). The notes and the
refusals name no option of the command line (`--wait`) and no `gabier <command>`: another front end shows them too. The
one-line **summary**, the optional **notes** (a warning to read before the call: `move-type-to-file` and `inline`
are the models) and the **refusals** of the method, `<key>: <meaning>`, in the order `gabier help` lists them. A
refusal that more than one operation answers is a constant of `Refusals` (the file, the language server and the
stale edit ones), not a copy; a parameter that more than one shares is one of `Parameters`. An operation that can be
asked in two ways is two operations (`RENAME`, `RENAME_TOKEN`; `DIAGNOSTICS`, `DIAGNOSTICS_ALL`, the second with no parameter). A key of the method that says the language server
declined the operation (`language-server-not-...`) goes into `DECLINED_OPERATIONS` of `Problems` (`eu.gabier.cli.application`), so that its
refusal ends with the pointer to `gabier help <name>`, on the command line and in the failed call of the MCP tool.
The MCP server (`gabier mcp`) builds its tool from this descriptor, not from the command line, and calls it
through `OperationRunner`: a new operation is a tool by itself, with no other file edited (`tools/list`, the
schema, the call); one that answers with a new kind of
result also adds the case to the `switch` of `ToolCalls` (it does not compile without it). `ToolsTest` fails on a
command-line word (`--json`, `gabier <command>`) in the description of any tool or of its parameters: what only a
person at the command line reads (an option, the text it prints, `line:column`) goes in `.withNotes(...)` of its
`Command`, which `help` prints after the notes of the operation. If an agent should know the tool before it needs it,
name it between backticks in `mcp-instructions.md` (a test checks that every tool named there is listed, and that
every tool that changes code, one with no `readOnlyHint`, is named there: a new one fails it until the text says it);
a parameter that holds a path is `Parameter.path` (or `paths`), so that the runner refuses it empty and the MCP server
(`ProjectOperations`) refuses it relative and sends the call to the daemon of the project of the file;
- a final class implementing `Capability` (`command()`, `run(Invocation)`), named after the command (`Rename`,
`OrganizeImports`; `Diagnostics`, `Status` are the models). It declares what is the command line's own, once, as
the constant `static final Command COMMAND = Command.called("<name>")`, which a step builder fills one part after
the other, so that a part left out does not compile: `.usage(...)` (one line per form, each starting with
`gabier [--json] <name>`), `.example(...)` (a call on a line that starts with `$ gabier `, and its answer), then
the family of refusals and the operations it runs: `.asksTheDaemon(Operations.X...)` for a command that asks the
daemon, starting it if need be (`usage-error`, `daemon-start-failed` and `daemon-connection-failed` are added to the
refusals of its operations; a command with two operations, `rename`, has one usage line for each, in the order of
its operations), `.asksARunningDaemon(Operations.X)` for one that never starts it (`status`, `stop`), or
`.standalone(summary, refusals...)` for one that never talks to it (`help`, `init-agent`: they are no operation of
the daemon, so they hold their own summary and refusals, and `.withNotes(...)` for their notes). The summary, the
notes and the refusals that `gabier help` prints are those of the operations. The invariants (the usage names the
command, the example starts with `$ gabier `) are `Assert`s of the compact constructor of `Command`. `command()`
returns `COMMAND`. `gabier help`, `gabier help <command>` and `gabier <command> --help` (handled once, in the dispatch of
`Gabier`, for every command) print it, and `UsageException` points to them: nothing else lists the commands, so the
usage text is not edited. The refusals are the keys of the operation in `Operations` (the help is the documentation of
the command, `.claude/rules/help.md`): `RefusalKeysTest` fails when one is the key of no `ErrorKey` of the code. `run` reads the words with `invocation.arguments()`
(`Arguments`: `dryRun()`, `has(option)`, `operands(count, options...)` which takes `--dry-run` and the options out
and refuses a wrong count, `exactly(count)` which keeps every word, `file(i)` as an absolute path, `position(i)` for
`line:column` and `position(i, j)` for two numbers, both counted from 1 by the user and kept from 1; every refusal is
the one usage error), runs its operation and prints. A command of the catalogue (it asks for work on the project)
reduces to two steps, "words to named values" and "result to output", and builds no parameter of the daemon: it calls
`invocation.operations().run(Operations.X, values)`, where `values` are the named values of the descriptor (a
`String`, an `Integer` position counted from 1, a `Boolean`, a `List<String>`; any `Number` with no fraction is a
whole number), and gets an `OperationResult`
(`Changed`, `Diagnosed`, `Referenced`, `Offered`: the `protocol` type, decoded). `invocation.operations()` is the
`OperationRunner` of `eu.gabier.cli.application`, the one entry point of every front end: it checks the values
against the descriptor (a required value missing, an unknown one, one of another kind, a position below 1: the
refusal `operation-invalid-values`), sends the positions from 0, a boolean as `true` or `false` and a list one
element to a line (the form the daemon reads: an element with a line break, or an empty one, is refused), asks the port, and decodes the
answer. **A new operation is also named in `kindOf` of `OperationRunner`** (the `case` list of the operations that
answer with changed files, or the case of `diagnostics`, `references`, `actions`); a method it does not list is
refused with an `IllegalArgumentException`, and `OperationRunnerTest` shows it. One that answers with a new kind of
result is a new case of `OperationRunner` and a new record of `OperationResult`. The port is `Daemon` of `eu.gabier.cli.domain`
(a method with string parameters in, the members of the result out as a `DaemonReply`, a refusal thrown as a
`DaemonRefusal` that holds the problem as plain fields, no `protocol` type, which the runner lets through). Its adapter, `SocketDaemon` in `eu.gabier.cli.infrastructure.secondary`
(with `DaemonClient`, `DaemonLauncher`, `DaemonException`, `WaitNotice`), starts `gabier-daemon` when nothing
answers (`DaemonLauncher`) and is built by `Gabier` (in `eu.gabier.cli`, which hands it to `CommandLine`), the one class outside the adapters that names it (a rule of
`HexagonalArchTest`); a new way to the daemon is a method of the port, with its adapter. An
administrative command that must not start the daemon calls `invocation.daemon().askRunning(method, awaitEnd)`
(`stop`), or runs its operation through the runner when the runner asks a daemon that runs (`status`, kind
`REPORTED` of `OperationRunner`).
A command that answers with changed files shares `ChangedFilesReply` (`ask(invocation, operation, values)`, `print`,
`printSayingNothingToChange`: the dry run, the warnings, the list of files and the diff, which is
`ResultText.report`, shared with the MCP server), by composition, not by inheritance. A command that does not talk to the daemon (`help`)
asks nothing and has no row in `docs/protocol.md`. Its output is text by default and the result with `--json`, a
refusal of the daemon printed as its problem object with the exit code of its category (`DaemonRefusal`, turned into the `Problem` by `Gabier`);
- the row of the method in the table of `docs/protocol.md`, with the same parameters: `OperationParametersTest`
fails when the parameters of the operation, those of the usage line of its command (`<new-name>` for `newName`,
`<line>:<column>` for `line` and `column`, two of them for the four of a range; a word it does not know fails the
test, and is added to its table) and the row disagree, or when a row has no operation;
- its name in the `permits` clause of the sealed interface `Capability`: a capability left out does not compile;
- one `new` in the list of `Capabilities`, at its place in the order of `gabier help`. The list rejects two
capabilities with one name when the class loads; no test compares it with `permits`.
Test the rules of reading in `ArgumentsTest` when they are new (no socket), and the command in a test class of its own
(`RenamingTest`, `InliningTest`), which extends `CliTest` and runs against `ScriptedDaemon` (a real socket, scripted
answers; `daemonAnswering(result)`). That class holds only what is the command's own: the request it sends for a
position, its special outputs. What every command shares is not rewritten: a command that returns changed files adds
a `@Nested` class that implements `ChangesCommandContract` and gives its name, what follows the file on its command
line and its request (`InliningTest.ReturningChangedFiles` is the model), and inherits the tests of the absolute path,
`--dry-run`, the list and the diff, the terminal escapes and `--json`; add its command line to `DaemonAnswersTest`
(refusal as text and as JSON, a result it cannot read) and the lines that are not its usage to `UnknownUsageTest`.
Document it in the help, not in a page (`.claude/rules/help.md`): the summary, the notes (output, limits, what to run
after) and the refusals in `Operations`, the usage and the example in the command, one line in the "Capabilities" list
of the README that points to `gabier help <command>`, and a row in the table of methods of `docs/protocol.md`. A file
given on the command line is sent as an absolute path (the daemon's working directory is not the cli's), and a
position is shown from 1 in the text and kept from 0 with `--json`.
6. **Prove it end to end**: add the check of the command to the class of its area in `bin/ci.d/native/` (the one of the
commands of its kind: `RewriteChecks`, `ExtractChecks`, `MoveChecks`, `QueryChecks`, `DiagnosticsChecks`, `LifecycleChecks`;
a new area is a new class that extends `Checks`) and its call to `Session.check`: the stage `40-native` starts that
program, which runs the native `gabier` against the installed `gabier-daemon`. Then run `bin/ci` (the `native` stage). A command of the catalogue is run there
against the daemon served by the fake language server (`:daemon:installFakeServed`, main class `FakeServedMain` in
the source set `fakeServed` of `modules/daemon`): it is a distribution of its own, never the one a user installs, and
it is the only way to the fake (no option, no request). A new answer to script is a scenario of the core
(`.claude/skills/add-scenario`) added to the list of `FakeServedMain`; the files of its project are written under the
folder given as the argument of `gabier-daemon-fake`.
## A method that answers more than once (a stream)
A method that follows something (`watch`, `watch-all`, `watch-affected-tests`) answers its request once, as any method does, then goes on
writing **notifications** on the same connection: JSON-RPC messages with no `id` (`{"jsonrpc":"2.0","method":"problems",
"params":{...}}`), which the client does not answer. The notifications of the daemon today are `problems` (the params are
the result of `diagnostics`, for the files whose list changed; an empty list is a file that became clean), `notice` (a
`message` for the person who reads), `ended` (the params are the error object of a failed request: the reason the
subscription ends, after which nothing is written), and, for the tests, `affected-tests` (the params are the result of
`affected-tests`) and `refusal` (the error object of a refusal the subscription goes on after). `RpcMessage.parse` reads a
line of the daemon as an `RpcResponse` or an `RpcNotification`; `JsonRpc.problems`, `affectedTests`, `refusal`, `notice`
and `ended` write them. Rules:
1. **The method is a `StreamingMethod`** (a `DaemonMethod` whose `call(params, peer)` also gets the `Peer` of the client),
and does its work that can fail (the refusals) **before** it asks the peer to listen: a request that is refused
follows nothing. `peer.listen(notifications, merge, whenGone)` makes the connection write what `notifications` turns the
states it is offered into, **after the answer** to the request (the answer is always the first line), and runs
`whenGone` once when the connection ends, whatever the reason, which is where the method gives up its subscription.
A connection follows one thing: a second `listen` is refused with `already-watching`.
2. **One writer thread per connection** (`Outbox`) writes every line, answers and notifications, so two lines never mix
and the order of what is offered is kept. Nobody else writes to a socket. A state that the writer has not taken yet is
**replaced** by the next one the method offers (`Peer.Listener.offer`: `merge` is `(waiting, offered) -> offered`), so a
client that does not read costs the daemon one blocked writer and one state, and holds up neither the method, nor
another client, nor the daemon; what such a client is told is the latest state, not every state. That holds for a
state that is the whole truth (the problems of the project). A state that is something that happened (the tests that
a change affects, whose changes were used up) is **put together** with the next one by a `merge` that keeps both
(`AffectedTestsUpdate.then`), so no answer is lost. `offer`, `say` and `end` never block.
3. **A client that disconnects ends its subscription and nothing else**: the reader of the connection goes on reading
while the writer writes, so the end of its input is seen, the connection ends, and `whenGone` runs. What the method
shares between clients (the reader of the project, `ProjectFeed`, which follows the disk with one thread and one
watcher for every kind of client, and reads each thing that is followed once for all the listeners of its kind, and
only while one listens: a read that uses something up, the tests, must not be made for nobody) stops with the last of them, and leaves no thread. A client that is connected counts for the
idle stop of the daemon: it does not stop while someone watches.
4. **Test it** with `ConnectionFollowingTest` (the handler, the writer and the order, over streams), the real socket of
`DaemonServerTest` (`Watching`: a disconnected client, a client that does not read, the stop of the daemon, no thread
left) and the method against a scripted peer (`WatchMethodsTest`). The fake of a source of change is `ScriptedDisk`
behind `DiskChanges`; the real one is `FolderWatch`.
5. **The cli side**: a method that streams is not run through `OperationRunner.run` but `OperationRunner.follow`, which
returns where the client starts and a `Daemon.Following` whose `next()` waits for the next notification and fails with
the connection failure when the daemon goes away. The command prints each line and flushes it. The operation is
declared in `Operations` like any other (and has its row in `docs/protocol.md`), and is named in `NOT_TOOLS` of
`Tools`: an MCP tool answers once, so it is not served as one (the page of `diagnostics` says what a client that
cannot read a stream does instead). The test of the command runs against `ScriptedStreamingDaemon`, which writes the
lines when the test says so.
Wersje
W bazie nie ma innych skilli o nazwie add-daemon-method.
Migawka bazy z 13.11.2026 · wersja paczki 8c64907c3281 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100unix-cli
Podaje wytyczne projektowania narzędzi wiersza poleceń w duchu UNIX: konwencje POSIX, kody wyjścia, strumienie stdout i stderr, sygnały oraz skrypty powłoki. - 100rust-cli
Projektuje, implementuje, testuje i wydaje aplikacje wiersza poleceń w Rust: podpolecenia, kody wyjścia, konfigurację, potoki i clap. - 84unix-architect
Pisze ADR i recenzuje PR oraz propozycje architektoniczne z perspektywy filozofii UNIX, zapisując uzasadnienie decyzji. - 95add-command
Dodaje obsługę nowego polecenia CLI, pisze jego handler i wpisuje je na listę SIMPLE_SAFE. - 96build-method
Prawdopodobnie prowadzi przez metodę budowania i projektowania oprogramowania. - 86add-rpc
Dodaje metodę RPC do usługi gRPC w protobufie, regeneruje kod i testuje ją przez sieć.