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
17 changes: 17 additions & 0 deletions .changeset/cli-contract-update.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
---
"@managers/server": minor
---

`managers update`, `managers doctor`, and `service install --refresh`

Wave F3 of the CLI-contract rollout (edspencer/cli-contract SPEC 0.2), ported from Paddock 0.82 and the contract's `reference/`.

**New: `managers update [--check] [--to <version|tag>] [--yes] [--force] [--json]`** (`upgrade` is a hidden alias). It asks the registry, checks the running instance is not busy, stops the service, installs with the package manager this copy came from, hands over to the new CLI to rewrite the unit, waits for `/api/health` to report the new version, and **rolls back** if it doesn't. Exit codes a script can see: **5** this install can't update itself (a checkout, npx, a container, or a managed install: the right command is printed), **6** the update failed and the old version is running again, **7** it failed and could not be rolled back, **75** busy, **2** no terminal and no `--yes`. `--check` exits 0 whether or not there is an update; read `updateAvailable` from `--json`. Nothing contacts the registry on its own.

**New: `managers doctor [--json] [--offline]`.** SPEC §1's eight checks (Node against `engines`, the install method, the unit, the running version, the port, linger, the data dir, a newer version), then Managers' own: the configuration loads, and **the security posture `/api/security` reports** (no authentication, trusted-header, any-audience JWTs, batch drive mode), asked of the running instance or computed from this shell's configuration by the server's own rule. Exits 1 if any check failed.

**New: `managers service install --refresh`** re-renders an existing unit from the settings it records (port, host, data dir), and exits 4 with nothing installed. `service status` repeats what the last `update --check` or `doctor` found (`update` in `--json`, absent rather than null when there's nothing). `service start` and `restart` run `systemctl --user reset-failed` first. A first `service install` that launchd or systemd refuses no longer leaves a unit behind (so `status` doesn't report it installed); a refused reinstall keeps the unit it had.

**The image** sets `MANAGERS_IN_DOCKER=1` and puts `managers` on `PATH`, so `docker exec <container> managers busy` works as a pre-update hook and `managers update` inside it prints the image to pull and exits 5. Set `MANAGERS_UPDATE_HINT` to have `update` print your own upgrade command instead (for a container or install managed by Ansible, say).

`--check`, `--to`, `--yes`, `--refresh` and `--offline` exit 2 on commands that can't act on them. See UPDATING.md.
46 changes: 44 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,8 @@ jobs:
conformance:
name: CLI conformance
runs-on: ubuntu-latest
timeout-minutes: 15
# The update checks install the package several times from the runner's local registry.
timeout-minutes: 30
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
Expand Down Expand Up @@ -84,7 +85,7 @@ jobs:
service:
name: Service (real ${{ matrix.os == 'macos-latest' && 'launchd' || 'systemd' }})
runs-on: ${{ matrix.os }}
timeout-minutes: 20
timeout-minutes: 35
strategy:
fail-fast: false
matrix:
Expand All @@ -109,6 +110,47 @@ jobs:
env:
MANAGERS_REAL_SERVICE: "1"
run: node scripts/service-real.mjs
# The conformance runner's update checks that need a real service manager: install the
# service at the packed version, update it from the runner's local registry, and update it
# to a build that doesn't start, which must roll back with exit 6. CI_REAL_SERVICE (and CI)
# is what lets the runner install a service under this runner's real home.
- name: Stage the npm package again
run: npm run pack:npm
- name: Conformance, with the real service manager
env:
CI_REAL_SERVICE: "1"
run: npx cli-conformance --dir dist-npm --config cli-contract.json --only update-service,update-rollback

# `managers update` against a LOCAL registry serving three real packed builds
# (scripts/update-registry.mjs). It runs a real `npm install -g` into a throwaway prefix, with a
# throwaway HOME, XDG_CONFIG_HOME, MANAGERS_DATA_DIR and npm cache, and refuses to start unless
# `npm root -g` really resolves inside its temp directory.
#
# Both OSes run everything except the service-backed scenarios; those need the stand-in
# systemctl (scripts/standin-systemctl.mjs) and so are Linux-only. The real managers' side of
# `update` is in the `service` job above, which since C2 installs at one version and updates to
# the next against the same local registry.
#
# This is also the only job that is NOT root, which matters for one scenario: the non-writable
# global folder (SPEC §5 step 5) cannot be proven as root, because root ignores the mode bits.
# The script skips it with a printed reason on a box where it is root, and runs it here.
update:
name: Update (fake registry, ${{ matrix.os == 'macos-latest' && 'macOS' || 'ubuntu' }})
runs-on: ${{ matrix.os }}
timeout-minutes: 30
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest]
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
- run: npm ci
- name: Update, against a local registry
run: node scripts/update-registry.mjs

# Fails on a high/critical npm advisory that is not a documented exception
# (docs/security/npm-audit.md). Reads only the lockfile, so no `npm ci`.
Expand Down
22 changes: 21 additions & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,8 @@ ENV NODE_ENV=production \
PORT=7234 \
HOST=0.0.0.0 \
MANAGERS_DATA_DIR=/data \
HOME=/data
HOME=/data \
MANAGERS_IN_DOCKER=1

# System deps + GitHub CLI + the Claude CLI (the CLI runtime's PATH binary; the
# SDK runtime ships its own — see the header).
Expand Down Expand Up @@ -117,6 +118,25 @@ COPY LICENSE ./
COPY --from=build /app/packages/server/dist packages/server/dist
COPY --from=build /app/packages/web/dist packages/web/dist

# `managers` on PATH, which the CLI contract requires of an image (SPEC §9) and which is what makes
# `docker exec <container> managers busy` and `docker exec <container> managers update --check` work.
#
# A shim rather than a global npm install, because the app in this image is not an npm install: it
# is a copied `dist/` with its dependencies at /app/node_modules. The shim invokes the interpreter
# explicitly, for the same reason the service unit does (spec.ts) — a `#!/usr/bin/env node` has to
# find `node` on PATH, and that is one more thing to be true at a moment nobody is watching.
#
# `MANAGERS_IN_DOCKER=1` above is what makes `managers update` in here print the image-pull command
# and exit 5 rather than trying to npm-install over a read-only app directory (SPEC §6 row 1). It
# is set by this Dockerfile and nothing else: `/.dockerenv` is deliberately NOT the signal, because
# dev containers have it too and a global npm install inside one is a legitimate thing to update.
#
# An operator who manages this container with something that knows how to upgrade it — Ansible, a
# Helm chart, a Watchtower label — sets MANAGERS_UPDATE_HINT at `docker run` time, and `update`
# prints that sentence instead of guessing at a `docker compose` line (see UPDATING.md).
RUN printf '#!/bin/sh\nexec node /app/packages/server/dist/cli/managers.js "$@"\n' > /usr/local/bin/managers \
&& chmod +x /usr/local/bin/managers

# Configure git auth from GITHUB_TOKEN (if provided) then exec the server.
RUN printf '#!/bin/sh\nif [ -n "$GITHUB_TOKEN" ]; then\n git config --global url."https://x-access-token:${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"\nfi\nmkdir -p "$MANAGERS_DATA_DIR"\nexec "$@"\n' > /usr/local/bin/docker-entrypoint.sh \
&& chmod +x /usr/local/bin/docker-entrypoint.sh
Expand Down
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,10 @@ unit; a bad command, flag or value exits **2**. `managers busy` exits **75** whi
a chat turn or trigger run is in flight (0 when idle, 3 when nothing is running),
and `service stop`/`restart` refuse with 75 unless given `--force`. A SIGTERM
waits briefly for in-flight work, then records what it cut short; under Docker,
give the container a `stop_grace_period` of 20 s or more. The CLI follows the shared
give the container a `stop_grace_period` of 20 s or more. `managers update` installs
a newer release and puts the service back up, rolling back if the new version
doesn't answer ([UPDATING.md](UPDATING.md)); `managers doctor` checks the install,
the service, the configuration and the security posture. The CLI follows the shared
[CLI contract](https://github.com/edspencer/cli-contract) (`cli-contract.json`
says which of its checks apply).

Expand Down
202 changes: 202 additions & 0 deletions UPDATING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
# Updating Managers

`managers update` installs the new version, refreshes the service unit, waits for it to answer — and puts the old version back if it doesn't.

```bash
managers update
```

That is the whole thing. It asks npm what the latest version is, asks you to confirm,
stops your service, installs, starts it again on the new version, and waits until
`/api/health` reports the version it just installed. If that never happens, it reinstalls
the version you were on and tells you so.

```
Managers 0.4.0 is available (you have 0.3.1).
Run: managers update
Changes: https://github.com/edspencer/managers/releases/tag/v0.4.0
```

## Look before you leap

`managers update --check` asks the registry, prints what it found, and changes nothing. It
exits **0** whether or not there is an update — a script reads `updateAvailable` from the
JSON rather than the exit code:

```bash
managers update --check --json | jq '.updateAvailable, .target'
```

What it found is cached in `<data-dir>/update-check.json`, and `managers service status`
repeats it. **Nothing in Managers contacts the registry on its own** — not the server, not
at startup, not in the background. Only `update`, `update --check` and `doctor` ask, and
only when you run them.

## Updating while something is running

`update` asks the running instance whether it is busy before it stops anything, and
refuses if it is:

```
managers: Managers is busy: 2 chat turns are running. Run it from a terminal, not from
inside a Managers chat.
```

A chat turn is a live `claude` subprocess writing a transcript, and it cannot be resumed
from where it was interrupted — so a restart loses it. A trigger run (a scheduled wake, a
report, a consolidation) counts too, from the moment its run record is written until it is
finished and committed. Wait, or override the check with
`--force`. `--force` skips **only** that check: the health check and the rollback still run.

> **Run it from a terminal, not from a chat.** Managers' agents can drive Managers. A keeper chat that runs `managers update` is itself one
of the chat turns the busy check counts, so it will always see itself as busy — and
`--force` from there stops the service that is running the chat, which then never gets to
tell you what happened. This is why the refusal says where to run it from.

## Going somewhere particular

```bash
managers update --to 0.3.1 # a version — the only way to go BACK
managers update --to next # a dist-tag
```

`update` never goes backwards by accident: a registry whose `latest` is *older* than what
you have is reported and ignored, and a `latest` that points at a prerelease is not
installed unless `--to` names it.

## Without a terminal

`update` asks a question, and a question needs a terminal. In a script, a cron job or an
Ansible task there is none, so it exits **2** and says `--yes` is required rather than
guessing:

```bash
managers update --yes
```

## When it goes wrong

The exit code is the whole report, and the two failure codes mean different things:

| Code | What happened | What you do |
|---|---|---|
| 0 | Updated, or already up to date | nothing |
| 2 | No terminal to ask, so `--yes` is required | add `--yes` |
| 5 | This install can't update itself — the right command was printed | run that command |
| 6 | The new version didn't start. **The old one is running again** | read the log it printed, then report it |
| 7 | The new version didn't start **and the old one could not be restored** | run the commands it printed |
| 75 | Busy | wait, or `--force` |

On a rollback, `update` prints the last 20 lines of the service log before it puts the old
version back — which is usually enough to see why the new one did not come up.

## Installs that can't update themselves (exit 5)

Managers works out where it is running from, and five layouts are not its to replace. Each
prints the command that *would* work:

| Where it is running from | What it tells you |
|---|---|
| A container image | `docker compose pull && docker compose up -d` |
| A managed install (`MANAGERS_UPDATE_HINT` is set) | whatever that variable says |
| `npx` / `pnpm dlx` | `npx @edspencer/managers@latest` — npx already runs the latest each time |
| A checkout | `git pull && npm install && npm run build` |
| A dependency of another project | update it in that project |

A global **npm**, **pnpm**, **bun** or **volta** install updates in place.

If the global folder is not writable, `update` prints the same command with `sudo` and
exits 5. **It never runs `sudo` itself** — that is a decision for the person at the
keyboard, not for a tool that has just decided to replace its own files.

## In Docker

Nothing installs anything inside a container. The image sets `MANAGERS_IN_DOCKER=1`, so
`update` there prints the image to pull and exits 5:

```bash
docker exec managers managers update --check
```

```
Managers 0.4.0 is available (you have 0.3.1).
Run: docker compose pull && docker compose up -d (image ghcr.io/edspencer/managers:0.4.0)
```

`managers` is on `PATH` in the image, so `docker exec managers managers busy` works too —
which is what lets an automatic updater wait for a quiet moment — for example Watchtower's
pre-update hook:

```yaml
labels:
com.centurylinklabs.watchtower.lifecycle.pre-update: managers busy
# and on the Watchtower container: WATCHTOWER_LIFECYCLE_HOOKS=true
```

Give the container a `stop_grace_period` of at least 20 seconds. On SIGTERM, Managers waits
up to 8 seconds for in-flight chat turns and trigger runs to finish, then records any it has
to cut short (each run is marked `failed`, `interrupted by shutdown`); Docker's default
10-second stop timeout leaves too little room for that.

If something else manages the container — Ansible, a Helm chart, a deploy job — set
`MANAGERS_UPDATE_HINT` to the command that actually upgrades it, and `update` prints that
instead of guessing:

```bash
docker run -e MANAGERS_UPDATE_HINT='ansible-playbook -i prod managers.yml' …
```

## What it does, step by step

Worth knowing if you are automating around it, or if it stops half way:

1. takes `<data-dir>/update.lock`, so two updates cannot interleave;
2. works out how this copy was installed;
3. asks the registry for the target version and its `engines.node`;
4. compares — and stops here with `--check`;
5. checks the global folder is writable;
6. asks the running instance whether it is **busy**, before anything is stopped;
7. asks you, unless `--yes`;
8. fetches **both** the new and the current version into the npm cache, while the old
version is still serving, so a rollback has its package to hand even if the network
has gone;
9. stops the service;
10. installs with the package manager this copy came from;
11. hands over to the **new** CLI, which re-writes the service unit in its own format
with the port and data dir the old one recorded (`managers service install --refresh`);
12. waits for `/api/health` to report the version it installed — not merely for the URL
to answer, because the old server, a sibling instance and a supervisor that restarted
the old unit all answer too;
13. and if any of 10–12 fails, puts the old version back.

The registry it asks is `npm_config_registry`, else `npm config get registry`, else
`https://registry.npmjs.org`.

## Checking it afterwards

```bash
managers doctor # every check, with a fix for each failure
managers doctor --offline # the same, without asking the registry
```

`doctor` checks this Node against the package's `engines`, how Managers was installed, the
service unit, that the running version is the installed one, the port, linger (Linux), the
data dir, whether a newer version exists, that the configuration loads, and the security
posture `/api/security` reports. It exits 1 if anything failed.

## Updating by hand

There is nothing magic about `update` — it runs the commands you would:

```bash
managers busy # 0 not busy, 75 busy, 3 nothing running
managers service stop
npm install -g @edspencer/managers@latest
managers service install --refresh # re-write the unit, keeping its settings
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.
23 changes: 22 additions & 1 deletion cli-contract.json
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,27 @@
"busy": true,
"busy-json": true,
"serve-banner": true,
"serve-health": true
"serve-health": true,
"update-up-to-date": true,
"update-check-json": true,
"update-no-tty": true,
"update-busy": true,
"update-npx": true,
"update-checkout": true,
"update-not-writable": true,
"update": true,
"update-to-lower": true,
"update-service": true,
"update-rollback": true
},
"update": {
"runtimeFile": "{home}/managers/runtime.json",
"serviceInstall": [
"service",
"install",
"--port",
"{port}"
],
"timeoutMs": 600000
}
}
Loading
Loading