Every commentware command acts on one server’s database, and nothing typed on
the command line has to say which. A flag is something each person has to
remember on every run, and an environment variable lives in one person’s shell.
A directory says it instead, in a file committed with it: the config file,
commentware.config.json.
A file that travels with the checkout
Put a config file in a directory and every command run at or below it reaches the same server: yours, your teammates’ and your agents’, because the file arrives with the checkout. Nobody sets anything up. A command run three directories down reaches the same server as one run at the top, because the search walks up, and paths in the file resolve against the file’s own directory rather than against where you stand.
With no file in the directory or above it, a command reaches the server your
own config file names, the one commentware init -g writes and every directory
without a file of its own falls back to. With none of either, it reaches this
machine’s own server. That is the default for one person, and a directory
needs a file only when its comments should be kept apart: a client project, or a
checkout a whole team shares.
One file, never merged
A command takes every value from the first file it finds, and none from the others. That makes “why is this server here” a question with an answer: one file you can open. A checkout that says where its comments go beats your own file outright, because a committed path that your own file could reshape would mean different things on two machines.
For the same reason a --config path that does not exist is refused rather
than skipped. Falling back to the next file would hand you a server you did not
name.
What stays out of it
Settings live in the database, not in the file. The file is what says which database to open, and a setting is read out of that database, so a setting in the file would be a value read before the place it is kept is known.
No access key goes in it. A key in a config file is a key in a commit, so there is no field for one.
It is JSON, and nothing in it runs. A command reads whichever config file is
above the directory you are in, including in a checkout somebody else wrote,
and a config format that runs code would run theirs. ${VAR} is the one thing
the file computes, and it is not a step toward expressions.
A schema URL with a version in it
commentware init writes a $schema line once, and it stays in the file for as
long as the file exists. If the URL named “the format”, an editor opening a
file written two releases ago would check it against rules it was never written
against. So the URL names a version of the format, and a file the document at
it accepted, it goes on accepting.
When something else answers for the server
Behind a reverse proxy, the server binds loopback and the proxy answers on a
public name. The server is never told that name: a request’s Host header is
whatever the proxy put there, and a permalink outlives the request that carried
it. So an address the server builds and hands out names the address it binds,
which nobody outside the machine can dial, until the config file says where the
server is reached. That is publicOrigin.
Next steps
- commentware.config.json: look up every key, its type and its default.
- Manage a server: give a directory its own server.