Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .changeset/cli-contract-shoulds.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
"@managers/server": minor
---

**The CLI contract's remaining `service` and `serve` options (SPEC §1, §3), ported from Paddock ([paddock#996](https://github.com/edspencer/paddock/pull/996)).** What a script can see:

- **`managers service install --dry-run`** prints the unit it would write (the systemd unit or the launchd plist) on stdout, says where it would go on stderr, and writes nothing — not the unit, not a folder. It works with `--refresh` too, and with `--json` (`{ ok, action, dryRun, unit, contents }`).
- **`service install` refuses to run from a git checkout** (or an `npm link`), exit **1**, unless you add **`--from-checkout`**: a unit that runs a working tree follows every rebuild, branch switch and move of it. A global install is unaffected. The npx refusal now suggests `npm i -g @edspencer/managers` rather than `npm link`, which this refusal would catch.
- **`service install` refuses a port something else holds**, exit **1**, rather than writing a service that can only crash-loop. A Managers on the port (a reinstall) is fine, and so is the unit's own running service. A Paddock on the port counts as something else.
- **`--json` on `service install`, `uninstall`, `start`, `stop` and `restart`**: one document on stdout, `{ ok, action, error?, …the service's status afterwards }` (the same fields as `service status --json`), with every word of prose on stderr. The exit codes don't change; `error` is `busy` for a 75 and `not installed` for a 4.
- **Running `service install` again keeps the installed unit's settings** — its port, host, data dir and verbosity — unless a flag says otherwise (SPEC §1). It used to do that only with `--refresh`, so a plain reinstall over a `--port 9000` service moved it to 7234.
- **`managers serve --quiet` (`-q`)** prints only the first line, `Managers <version>: <url>`.
- **Flags belong to their commands:** `--dry-run` and `--from-checkout` (`service install` only), `--quiet` (`serve` only) and **`--json` on a command that has no JSON document — `serve`, `service logs`, `config eject` — now exit 2**. They used to be accepted and ignored.
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,10 @@ Each GitHub Release also carries a self-contained tarball.
said out loud (`managers start` is a permanent alias). `managers service install`
runs it in the background from login (a launchd LaunchAgent on macOS, a
`systemd --user` unit on Linux), with `uninstall`, `start`, `stop`, `restart`,
`status [--json]` and `logs [-f] [-n <lines>]`. `service status` exits **0** when
`status [--json]` and `logs [-f] [-n <lines>]`; `install --dry-run` prints the unit
and writes nothing, a reinstall keeps the unit's port, host and data dir, and
`install` refuses a git checkout (unless `--from-checkout`) and a port something else
holds. `service status` exits **0** when
it is up and answering, **3** when installed but not, and **4** when there is no
unit; a bad command, flag or value exits **2**. `managers busy` exits **75** while
a chat turn or trigger run is in flight (0 when idle, 3 when nothing is running),
Expand Down
5 changes: 4 additions & 1 deletion UPDATING.md
Original file line number Diff line number Diff line change
Expand Up @@ -199,4 +199,7 @@ managers service status
`service install --refresh` is the one worth remembering: it re-renders the unit from
what the **existing** one records, rather than from the flags and environment of the shell
you happen to be in. With nothing installed it exits 4 rather than quietly performing a
first install with defaults.
first install with defaults. A plain `managers service install` keeps the installed unit's
port, host and data dir too, unless you give new ones; `--refresh` differs in ignoring
`MANAGERS_DATA_DIR` in your shell, and in refusing to do a first install.
`managers service install --dry-run` prints the unit either would write, and writes nothing.
7 changes: 6 additions & 1 deletion packages/server/NPM-README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,14 +59,19 @@ the API as you. The UI shows a permanent banner saying so.
--host <host> Bind address (default 127.0.0.1)
-d, --data-dir <path> Projects + state (default ~/.managers)
-o, --open Open the app in your browser once it is listening
-q, --quiet Print only the first line, `Managers <version>: <url>`
--verbose Show the server's own logs (quiet by default)
-v, --version Print the version
-h, --help Show help
```

`managers service install` keeps it running in the background from login
(launchd on macOS, a systemd user unit on Linux; it refuses to install from the
`npx` cache, so `npm i -g` first). `managers config show --resolved` prints every
`npx` cache or a git checkout, so `npm i -g` first, and refuses a port something
else holds). Running it again keeps the port, host and data dir the installed unit
records unless you give new ones; `--dry-run` prints the unit and writes nothing,
and `--json` on `install`, `uninstall`, `start`, `stop` and `restart` prints one
JSON document. `managers config show --resolved` prints every
effective setting and where it came from.

Your projects, objectives, tasks, memory, chats and settings persist in
Expand Down
95 changes: 90 additions & 5 deletions packages/server/src/cli/args.ts
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,20 @@ export interface CliOptions {
refresh?: boolean;
/** `doctor --offline`: skip the one check that asks the npm registry (SPEC §1). */
offline?: boolean;
/**
* `service install --dry-run`: print the unit it would write, and write
* nothing — not the unit, not a folder (SPEC §1).
*/
dryRun?: boolean;
/**
* `service install --from-checkout`: install a unit that runs THIS copy even
* though it is a git checkout (SPEC §1). Without it, `install` refuses: a unit
* pointing into a working tree breaks the next time it is rebuilt, switched
* to another branch or moved.
*/
fromCheckout?: boolean;
/** `serve --quiet` / `-q`: print the `Managers <version>: <url>` line and nothing else (SPEC §3). */
quiet?: boolean;
}

/**
Expand Down Expand Up @@ -321,6 +335,41 @@ const SCOPED_FLAGS: readonly {
where: ["update"],
why: "`update` is the only command that asks a question.",
},
{
flag: "--json",
read: (o) => o.json === true,
where: [
"service status",
"service install",
"service uninstall",
"service start",
"service stop",
"service restart",
"busy",
"update",
"doctor",
"config show",
],
why: "It prints one JSON document on stdout, and those are the commands that have one.",
},
{
flag: "--dry-run",
read: (o) => o.dryRun === true,
where: ["service install"],
why: "It prints the unit `install` would write, and writes nothing.",
},
{
flag: "--from-checkout",
read: (o) => o.fromCheckout === true,
where: ["service install"],
why: "It lets `install` write a unit that runs a git checkout.",
},
{
flag: "--quiet",
read: (o) => o.quiet === true,
where: ["serve"],
why: "It keeps `serve` to its one `Managers <version>: <url>` line.",
},
{
flag: "--offline",
read: (o) => o.offline === true,
Expand Down Expand Up @@ -475,6 +524,18 @@ export function parseArgs(argv: string[]): CliOptions {
case "--refresh":
opts.refresh = true;
break;
// `service install` (SPEC §1).
case "--dry-run":
opts.dryRun = true;
break;
case "--from-checkout":
opts.fromCheckout = true;
break;
// `serve --quiet` (SPEC §3).
case "-q":
case "--quiet":
opts.quiet = true;
break;
// `doctor --offline` (SPEC §1).
case "--offline":
opts.offline = true;
Expand Down Expand Up @@ -574,6 +635,7 @@ Usage
managers serve [options] the same thing, said out loud
(\`managers start\` is a permanent alias)
managers service install [options] run it in the background from login
(--dry-run prints the unit instead)
managers service uninstall stop it and remove the unit
managers service status [--json] installed? running? which version?
managers service start start an installed service
Expand All @@ -600,6 +662,7 @@ Options
--host <host> Bind address (default 127.0.0.1)
-d, --data-dir <path> Projects + state (default ~/.managers, or $MANAGERS_DATA_DIR)
-o, --open Open the app in your browser once it is listening
-q, --quiet Print only the first line, \`Managers <version>: <url>\`
--verbose Show the server's own logs (quiet by default)
-v, --version Print the Managers version and exit
-h, --help Show this help
Expand Down Expand Up @@ -723,6 +786,7 @@ export const SERVICE_USAGE = `managers service — keep Managers running in the
Usage
managers service install [options] register it and start it now
managers service install --refresh re-write the unit, keeping its settings
managers service install --dry-run print the unit it would write; write nothing
managers service uninstall stop it and deregister it
managers service status [--json] is it registered, is it running, which
version, where are the logs
Expand All @@ -738,17 +802,32 @@ Options (logs)
Options (stop, restart)
--force stop it even though it is busy

Options (install, uninstall, start, stop, restart, status)
--json One JSON document on stdout: ok, action, and the
service's status afterwards (the same fields as
\`status --json\`), plus error on a failure. All
prose goes to stderr. The exit code is unchanged

Options (install)
--dry-run Print the unit (and where it would go) and write
nothing — not the unit, not a folder
--from-checkout Install from a git checkout anyway. Without it,
install refuses: a unit that runs a working tree
breaks when you rebuild, switch branch or move it
--refresh Re-render the unit from the settings the EXISTING one
carries — its port, host, data dir and verbosity —
rather than from this shell's flags and environment.
and never from MANAGERS_DATA_DIR in this shell.
This is what \`managers update\` runs, through the new
version's CLI, so the unit is written in the format
that version writes. Exit 4 with nothing installed:
there is no unit to refresh, and doing a first
install with defaults instead is how a --port 9000
service comes back on 7234.

Running install again is safe: it keeps the port, host, data dir and
verbosity the installed unit records, unless you give new ones, and
restarts the running service onto the new unit.

Busy
\`stop\` and \`restart\` ask the running instance whether it is busy first, and
refuse with exit 75 if it is — a chat turn in flight, a background task, a
Expand Down Expand Up @@ -799,19 +878,25 @@ Where it lives
itself at 8 MB, keeping three older generations beside it.

Exit codes
0 it is installed, running and answering
0 it is installed, running and answering (status), or done
3 installed, but not running or not answering
4 not installed: there is no unit (status, logs, start, stop, restart)
1 something failed
2 usage: an unknown action or flag, or a bad value
75 busy, and --force was not given (stop, restart)

Installed from npx?
Installed from npx, or running from a checkout?
\`service install\` refuses. An npx cache path is hash-keyed and npm may prune
it, so the unit would work until it silently didn't, at some future login.
Install properly first:
A checkout is yours to rebuild, switch and move, and the unit would follow
it. Install properly first:

npm i -g @edspencer/managers && managers service install

(--from-checkout installs from the checkout anyway, for working on Managers.)

npm link -w packages/server && managers service install (from a built checkout)
It also refuses when something that isn't Managers holds the port: pick
another with --port.

A note on access
Managers binds loopback, and the managers command runs it with authentication
Expand Down
8 changes: 7 additions & 1 deletion packages/server/src/cli/managers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -400,7 +400,9 @@ async function main(): Promise<number> {
// Precedence is explicit flag > existing env > our default.
const dataDir = resolveDataDir(opts);

noteFirstRun(dataDir);
// `--quiet` (SPEC §3): the banner line and nothing else, so not the
// first-run note either (it is prose on stderr, but prose all the same).
if (opts.quiet !== true) noteFirstRun(dataDir);

process.env.MANAGERS_DATA_DIR = dataDir;

Expand Down Expand Up @@ -463,6 +465,10 @@ async function main(): Promise<number> {
// runner, and by anything that wants the URL without guessing the port — so
// the friendly block below it stays, but below it.
console.log(`${MANAGERS_NAME} ${MANAGERS_VERSION}: ${url}`);
if (opts.quiet === true) {
if (opts.open) openBrowser(url);
return EXIT.OK;
}
// Still name the data dir, even though it no longer varies with cwd: "which
// instance am I looking at" is a real question the moment anyone passes
// `--data-dir`, and the answer should be readable off the two lines the tool
Expand Down
Loading
Loading