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

**The CLI contract's remaining `service` and `serve` options (SPEC §1, §3).** What a script can see:

- **`paddock 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.
- **`service install` refuses a port something else holds**, exit **1**, rather than writing a service that can only crash-loop. A Paddock on the port (a reinstall) is fine, and so is the unit's own running service.
- **`--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 7233.
- **`paddock serve --quiet` (`-q`)** prints only the first line, `Paddock <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.
- A first `service install` that systemd or launchd refuses no longer leaves its unit behind (re-synced with cli-contract's `reference/service/`); a reinstall that fails keeps the unit that was there.
93 changes: 89 additions & 4 deletions packages/server/src/cli/args.ts
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,20 @@ export interface CliOptions {
* (SPEC §1). Every other check is local.
*/
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 `Paddock <version>: <url>` line and nothing else (SPEC §3). */
quiet?: boolean;
}

/**
Expand Down Expand Up @@ -324,6 +338,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 `Paddock <version>: <url>` line.",
},
{
flag: "--offline",
read: (o) => o.offline === true,
Expand Down Expand Up @@ -478,6 +527,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 @@ -577,6 +638,7 @@ Usage
paddock serve [options] the same thing, said out loud
(\`paddock start\` is a permanent alias)
paddock service install [options] run it in the background from login
(--dry-run prints the unit instead)
paddock service uninstall stop it and remove the unit
paddock service status [--json] installed? running? which version?
paddock service start start an installed service
Expand Down Expand Up @@ -604,6 +666,7 @@ Options
--host <host> Bind address (default 127.0.0.1)
-d, --data-dir <path> Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)
-o, --open Open the app in your browser once it is listening
-q, --quiet Print only the first line, \`Paddock <version>: <url>\`
--verbose Show the server's own logs (quiet by default)
-v, --version Print the Paddock version and exit
-h, --help Show this help
Expand Down Expand Up @@ -723,6 +786,7 @@ export const SERVICE_USAGE = `paddock service — keep Paddock running in the ba
Usage
paddock service install [options] register it and start it now
paddock service install --refresh re-write the unit, keeping its settings
paddock service install --dry-run print the unit it would write; write nothing
paddock service uninstall stop it and deregister it
paddock 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 PADDOCK_DATA_DIR in this shell.
This is what \`paddock 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 7233.

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,20 +878,26 @@ 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/paddock && paddock service install

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

It also refuses when something that isn't Paddock holds the port: pick
another with --port.

A note on access
Paddock binds loopback with authentication off, which is right for a laptop.
A service is up for as long as you are logged in rather than as long as a
Expand Down
36 changes: 1 addition & 35 deletions packages/server/src/cli/doctor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@
* two cannot disagree about what is installed and what is running.
*/
import fs from "node:fs";
import net from "node:net";
import os from "node:os";
import path from "node:path";
import { MIN_NODE_MAJOR, type CliOptions } from "./args.js";
Expand All @@ -36,7 +35,7 @@ import {
import { defaultDataDir, DEFAULT_PORT } from "./service/spec.js";
import { missingPaths, which } from "./service/path-env.js";
import type { LingerState, ServiceManager } from "./service/manager.js";
import { fetchHealth } from "./service/ready.js";
import { identifyPaddock as identify, isListening } from "./service/ready.js";
import { describeInstall, detectInstall, updateCommand, type InstallInfo } from "./update/install-method.js";
import { npmConfigGet, npmGlobalRoot } from "./update/package-manager.js";
import { RegistryError, resolveRegistry, resolveTarget } from "./update/registry.js";
Expand Down Expand Up @@ -659,36 +658,3 @@ function urlHost(host: string): string {
function firstLine(s: string): string {
return s.split("\n")[0] ?? s;
}

function isListening(host: string, port: number): Promise<boolean> {
return new Promise((resolve) => {
const s = net.connect({ host, port });
s.setTimeout(1000);
s.once("connect", () => {
s.destroy();
resolve(true);
});
s.once("timeout", () => {
s.destroy();
resolve(false);
});
s.once("error", () => resolve(false));
});
}

/**
* Is this a Paddock? `/api/health`'s `{ ok, version }` is the contract's, so
* every tool answers it; `/api/busy`'s `counts.chat` is Paddock's own.
*/
async function identify(url: string): Promise<{ paddock: boolean; version?: string } | undefined> {
const health = await fetchHealth(url);
if (health === undefined) return undefined;
try {
const res = await fetch(`${url}/api/busy`, { signal: AbortSignal.timeout(2_000) });
const body = (await res.json()) as { counts?: Record<string, unknown> };
const paddock = health.ok && typeof body.counts?.chat === "number" && "background" in (body.counts ?? {});
return { paddock, ...(health.version !== undefined ? { version: health.version } : {}) };
} catch {
return { paddock: false, ...(health.version !== undefined ? { version: health.version } : {}) };
}
}
8 changes: 7 additions & 1 deletion packages/server/src/cli/paddock.ts
Original file line number Diff line number Diff line change
Expand Up @@ -391,7 +391,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.PADDOCK_DATA_DIR = dataDir;

Expand Down Expand Up @@ -445,6 +447,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(`${PADDOCK_NAME} ${PADDOCK_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