ledge-server 0.0.1 → 0.0.3

package/README.md

@@ -1,89 +1,141 @@
 # ledge-server
 
-The server half of [Ledge](https://github.com/ledgesh/ledge), the macOS notebook for developers and DevOps.
+The server half of [Ledge](https://ledge.sh), the Markdown notebook that runs
+code. Install it on a machine whose notes and shells you want to reach from
+the Ledge app on a Mac or an iPhone. The machine keeps the notes, runs the
+commands, and holds the vault. The app is the window onto it.
 
-Install this on a machine whose notes and shells you want to reach from the Ledge app on your Mac or iPhone. The machine keeps the notes, runs the commands, and holds the vault. Your client keeps nothing but the window.
-
-The package installs one command, `ledge`. Its server verbs are what the apps run over ssh, and its other verbs are your notes from that machine's own shell.
+The package installs one command, `ledge`. Its server verbs are what the apps
+run over ssh, and its other verbs read the notes from that machine's own
+shell.
 
 ## Install
 
-The server runs on [Bun](https://bun.sh), and where Bun goes decides where the server goes: Bun puts global commands beside itself. Installing Bun into `/usr/local` puts both names in `/usr/local/bin`, which is where the short PATH of an ssh command looks.
+Signed in as the account Ledge should use:
 
 ```sh
-curl -fsSL https://bun.sh/install | sudo BUN_INSTALL=/usr/local bash
+curl -fsSL https://ledge.sh/server.sh | sh
 ```
 
-Then the server itself, into the same place:
+This puts the package and a private copy of Bun under `~/.ledge/.server`. It
+needs no `sudo`, opens no port, and starts no service: Ledge starts the server
+over ssh when a device connects, and it exits on its own a minute after the
+last device leaves.
+
+Then print a pairing code:
 
 ```sh
-sudo BUN_INSTALL=/usr/local bun add -g ledge-server
+ledge pair
 ```
 
-The variable on the second command is not optional. Without it the package installs into the home directory of whoever ran it, where an incoming ssh will not find it.
-
-macOS and Linux, on arm64 or x64. On Linux the floor is glibc 2.29, which means Debian 11, Ubuntu 20.04, RHEL 9, or anything newer. Alpine and other musl systems are not supported.
+It lists the machine's addresses, with what each one reaches, and asks which
+one your other devices should use. Scan the code with Ledge on a phone, or paste the
+link under it into the Mac app's Add Server form. The code carries the
+address, the account, and the host key.
 
-## Check that an incoming ssh can find it
+If the machine already has Bun, the same package installs with it. On Linux,
+Bun has to live in `/usr/local` so that an incoming ssh finds both commands:
 
-This is the one step worth not skipping, because Ledge reports what it catches as a server that is not installed: a remote shell that cannot find a command says only that. Ledge starts the server by running `ledge serve` over ssh, and a command run that way gets a short PATH and no shell profile. Both `ledge` and the `bun` its shebang names have to be on that PATH.
+```sh
+curl -fsSL https://bun.sh/install | sudo BUN_INSTALL=/usr/local bash
+sudo BUN_INSTALL=/usr/local bun add -g ledge-server
+```
 
-From your Mac:
+On a Mac, install Bun for the account and add its directory to `~/.zshenv`,
+which zsh reads for commands run over ssh:
 
 ```sh
-ssh you@machine 'command -v ledge; command -v bun'
+curl -fsSL https://bun.sh/install | bash
+echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshenv
+source ~/.zshenv
+bun add -g ledge-server
 ```
 
-Two paths printed means you are done. Nothing printed means the install landed somewhere an incoming ssh does not look, which is what a machine with a per-user Bun on it already gives you. Bun puts global commands beside itself, so `bun pm bin -g` on that machine says where they went, and linking both into a system directory fixes it without reinstalling:
+The server runs on macOS and Linux, arm64 or x64. Linux needs glibc 2.29 or
+newer: Debian 11, Ubuntu 20.04, RHEL 9, or anything later. Alpine and other
+musl systems are not supported.
+
+## Connect
+
+In the Ledge app, run "Notes On…" from the command palette, choose Add, and
+give the machine's ssh destination, or paste a pairing code. The app then
+opens the connection with your own ssh credentials by running:
 
 ```sh
-sudo ln -s "$(bun pm bin -g)/ledge" /usr/local/bin/ledge
-sudo ln -s "$(command -v bun)" /usr/local/bin/bun
+ssh you@machine 'PATH=$HOME/.ledge/.server/bin:$PATH ledge serve'
 ```
 
-## Use
+The machine's own sshd is the only thing listening, and the key or password
+you already use is the credential. Ledge speaks its protocol over ssh's stdin
+and stdout.
 
-You do not normally run this yourself. Add the machine in the Ledge app under Servers, and the app opens a connection with your own ssh credentials:
+To check that an incoming ssh can find the command, run the same thing from
+your Mac with `command -v ledge` in place of `ledge serve`. One path printed
+means the machine is ready. Nothing printed means the install landed
+somewhere ssh does not look, which happens with a `bun add -g` into a
+per-user Bun. Link both commands into a system directory to fix it:
 
 ```sh
-ssh you@machine ledge serve
+sudo ln -s "$(bun pm bin -g)/ledge" /usr/local/bin/ledge
+sudo ln -s "$(command -v bun)" /usr/local/bin/bun
 ```
 
-No port is opened and no daemon is installed. Ledge speaks its protocol over ssh's stdin and stdout, so the machine's own sshd is the only thing listening, and the key you already use is the credential.
-
-The verbs, if you want them:
+## The verbs
 
 | Verb | What it does |
 | --- | --- |
-| `ledge serve` | Move the protocol between stdin, stdout, and this machine's daemon. Starts the daemon if nothing answers. |
+| `ledge serve` | The protocol on stdin and stdout, attached to this machine's daemon. Starts the daemon if nothing answers. What a client runs. |
 | `ledge daemon` | Be this machine's server. Holds the notes, the shells, and the watchers, and runs until stopped. |
+| `ledge pair` | Print a pairing code for this machine, after asking which of its addresses your other devices should use. `--user`, `--host`, and `--port` override what it describes. |
 | `ledge backup` | Back this machine up to an S3-compatible bucket: `setup`, `now`, `status`, `snapshots`, `restore`, `paths`, `restic`. |
-| `ledge pair` | Print a pairing code a phone scans to add this server. |
 | `ledge mcp` | The Ledge MCP server on stdin and stdout, for an agent running on this machine. |
-| `ledge ls`, `ledge cat`, ... | Notes from this machine's own shell. `ledge help` lists them. |
+| `ledge ls`, `ledge cat`, `ledge search`, ... | Notes from this machine's own shell. `ledge help` lists them all. |
 
-The daemon outlives the connections to it, which is what lets a build keep running after your laptop closes and lets a reconnecting client pick the output back up.
+The daemon outlives the connections to it. A build keeps running after your
+laptop closes, and a reconnecting client picks the output back up.
 
 ## Restrict the key
 
-Optional, and worth doing on a server you care about. In that machine's `~/.ssh/authorized_keys`:
+A key in that machine's `~/.ssh/authorized_keys` can be limited to Ledge's
+protocol and nothing else:
 
 ```
-restrict,command="/usr/local/bin/ledge serve" ssh-ed25519 AAAA... ledge@laptop
+restrict,command="PATH=$HOME/.ledge/.server/bin:$PATH ledge serve" ssh-ed25519 AAAA... ledge@laptop
 ```
 
-That key can then speak Ledge's protocol and nothing else. No shell, no port forwarding, no file transfer.
+That key cannot forward a port, run `scp`, or open a shell. It can still run
+every block in every note, because running them is what the protocol does.
+A phone's key arrives with this prefix already on its line.
 
-An absolute path here settles half of the PATH question above, since sshd runs this string instead of whatever the client asked for. The other half stays: the file it names begins `#!/usr/bin/env bun`, so `bun` still has to be findable.
+Keep your usual key on the machine as well if you also ssh to it from a
+terminal. The restricted line is for Ledge alone.
 
 ## Where the data lives
 
-Most of what the server owns sits under one directory: the notes, the workspace registry, the vault, the layout, and the logs. It is `~/.ledge` by default, and `LEDGE_NOTES_ROOT` moves it. Two things live outside it: the profiles, at `~/.config/ledge/profiles`, so credentials stay out of the folder people sync; and any workspace folder attached from elsewhere on the machine.
+The notes, the workspace registry, the vault, the layout, and the logs sit
+under `~/.ledge`. `LEDGE_NOTES_ROOT` moves that directory. Two things live
+outside it: profiles, at `~/.config/ledge/profiles`, so secrets stay out of
+the folder people sync; and any workspace folder attached from elsewhere on
+the machine.
 
 ## Back it up
 
-`ledge backup setup` asks for an S3-compatible bucket and its key, then keeps an encrypted copy of all of the above there: every hour while the server is up, and once more before it exits. `ledge backup status` says how it is going, and `ledge backup restore` brings files back. See [Back Up Your Notes to S3](https://github.com/ledgesh/ledge/blob/main/docs/user/21-tutorial-back-up-your-notes-to-s3.md) in the manual.
+`ledge backup setup` asks for an S3-compatible bucket and its key, then keeps
+an encrypted copy of all of the above there: every hour while the server is
+up, and once more before it exits. `ledge backup status` reports on it, and
+`ledge backup restore` brings files back. See
+[Back Up Your Notes to S3](https://ledge.sh/docs/tutorial-back-up-your-notes-to-s3).
+
+## Documentation
+
+- [Keep Notes on a Remote Server](https://ledge.sh/docs/keep-notes-on-a-remote-server):
+  the reference for connections, sharing a server, and what a dropped
+  connection does.
+- [Set Up a Ledge Server](https://ledge.sh/docs/tutorial-set-up-a-ledge-server):
+  a fresh Linux VPS, from a new account to a hardened sshd.
+- [Ledge on Your Phone](https://ledge.sh/docs/ledge-on-your-phone): pairing
+  and what a phone does with a server.
 
 ## License
 
-Apache-2.0
+[Apache-2.0](https://github.com/ledgesh/ledge/blob/main/LICENSE)

package/lib/serve.js

@@ -6047,6 +6047,8 @@ A server with no pinned key has no code, since the code names the key. Edit the
 
 Every row in the picker carries three controls: a QR code icon to show its pairing code, a pencil to change it and a bin to remove it. Press \u232B on a focused row to remove it without reaching for either.
 
+Removing asks first, and the dialog says what goes with the record: the address, the host key you pinned, and the password if that connection uses one. The notes on that machine stay where they are. Adding the server back means comparing its fingerprint again.
+
 Editing opens the same form. A rename, or a change of account on the same machine, saves in one step, because neither changes which machine the pinned key belongs to.
 
 Changing the address to a different machine does not. The button reads "Continue" instead of "Save", Ledge asks that machine for its host key, and you compare the fingerprint again before anything is stored. A key pinned for one machine says nothing about another, and carrying it across would refuse every later connection with a warning about a changed host key.
@@ -6234,7 +6236,7 @@ Run them as the account the server runs as, on the machine the server runs on.
 
 | Verb | What it does |
 | --- | --- |
-| \`ledge backup setup\` | Asks for the bucket and its key, fetches restic if none is installed, writes the credentials to the \`backup\` profile, creates the repository, and takes the first backup. \`--existing\` joins a repository that already has backups in it. |
+| \`ledge backup setup\` | Asks for the bucket and its key, fetches restic if none is installed, writes the credentials to the \`backup\` profile, creates the repository, and takes the first backup. \`--existing\` joins a repository that already has backups in it, and takes no first backup, since a machine that has just joined has nothing on it to back up. |
 | \`ledge backup now\` | Takes a backup and thins old snapshots. |
 | \`ledge backup status\` | When the last backup ran and how it went, when the next is due, and any attached folder the last run could not find. |
 | \`ledge backup snapshots\` | The snapshots in the repository, newest first. |
@@ -6413,13 +6415,13 @@ A pairing code names a server and its host keys, so the phone can add it without
 ledge pair
 \`\`\`
 
-It prints the code as a QR code, then the account, host, port, and host keys it holds, then the same code as a link. It reads the address from your ssh session, or uses the machine's name when there is no session. When the phone cannot reach the server by that name, give the address yourself with \`--host\`. \`ledge pair --help\` lists the other flags.
+On a terminal, it first lists every address the machine has, with a note on which devices reach each one: its tailnet name and address, the address your ssh session reached, its public address when it runs in a cloud, its other network addresses, and its name. Type a number to pick one, or an address of your own as \`host\` or \`host:port\`, or press Return for the first. It then prints the code as a QR code, then the account, host, port, and host keys it holds, then the same code as a link. Without a terminal, it takes the first address and lists the rest under the code, and \`--host\` names one on the next run. \`ledge pair --help\` lists the other flags.
 
 A Mac that already has the server in its list can show the same code without a terminal: the QR code icon on the server's row in Notes On\u2026 ("Show a pairing code for a server" on [[Keep Notes on a Remote Server]]). The same link pastes into the Mac app's Add Server form ("Add a server from a pairing code" on that page).
 
-The code names one address, and the phone dials exactly that. \`ledge pair\` over ssh names the address your session reached, so a machine you reached over your home network or tailnet gets that address, which works from a phone on the same network or tailnet. A machine behind a router's port forward needs \`--host\` and \`--port\` for the outside address, since the session only knows the inside one. A Mac's code names the address the Mac dials, with the same reach.
+The code names one address, and the reader connects to exactly that, so pick the one your other devices reach from where they will be. A tailnet name works from anywhere a device is on the tailnet. A home network address works from a device on that network. A cloud machine's public address works from anywhere, when its sshd is reachable from outside. A machine behind a router's port forward has an outside address no source knows: type it at the menu with its port, or give them with \`--host\` and \`--port\`. A Mac's code names the address the Mac dials, with the same reach.
 
-On the phone, tap Scan a pairing code on the first screen and point the camera at the QR code. Scan it from Ledge rather than the Camera app, which opens the code in Safari. Ledge shows what the code names and connects only when you tap Connect. Choose how to sign in first, the same way as in "Pair by address": with a key, whose line still has to be in the server's \`authorized_keys\`, or with a password. Ledge signs in only if the server offers one of the host keys in the code, so there is no fingerprint to check by eye.
+On the phone, tap Scan a pairing code on the first screen, or in Add Server\u2026 inside the app ("More than one server" below), and point the camera at the QR code. Scan it from Ledge rather than the Camera app, which opens the code in Safari. Ledge shows what the code names and connects only when you tap Connect. Choose how to sign in first, the same way as in "Pair by address": with a key, whose line still has to be in the server's \`authorized_keys\`, or with a password. Ledge signs in only if the server offers one of the host keys in the code, so there is no fingerprint to check by eye.
 
 The code holds no password and no key. Someone who photographs it learns where the server is and which account to try, and nothing that signs them in.
 
@@ -6497,6 +6499,8 @@ Removing the last server returns the phone to the first screen. Deleting the app
 
 Inside the app the connection bar works as on a Mac: tap it to add, edit, remove, or switch servers, with the same fingerprint step ([[Keep Notes on a Remote Server]]). The form shows the phone's key line where a Mac's shows a key path, with Share Line beside Copy Line.
 
+Add Server\u2026 starts with Scan a pairing code, where a Mac's form has a field for the pasted link. It opens the camera, then the same "Pair with a server" screen as the first launch, and the app reopens on the new server once you tap Connect there. Cancel returns you to the form, where you can type the address instead. Editing a server has no scan: a code never replaces a host key the phone already has.
+
 A phone and a Mac can be on one server at once. Each keeps its own tabs, and a note's terminal has one owner between them.
 
 ## What a phone does
@@ -7172,6 +7176,18 @@ Nothing else needs installing: no timer, no unit file, no line in a crontab. One
 
 \`ledge backup now\` takes a backup at any time and is safe to run beside the schedule.
 
+Old snapshots are thinned after each backup, and what survives is fixed:
+
+| Kept | For |
+| --- | --- |
+| The ten newest snapshots | however close together they were taken |
+| One an hour | a day |
+| One a day | a month |
+| One a week | a quarter |
+| One a month | two years |
+
+Only the snapshots Ledge took are thinned, so a bucket shared with another tool's backups keeps those whatever this policy says.
+
 ## 4. Check on it
 
 \`\`\`sh norun
@@ -7207,13 +7223,13 @@ On a fresh machine with Ledge installed, the app on a Mac or the server on a VPS
 ledge backup setup --existing
 \`\`\`
 
-It asks the same questions plus the password, opens the repository instead of creating one, and writes the profile. Then, with the app quit or the daemon stopped:
+It asks the same questions plus the password, opens the repository instead of creating one, writes the profile, and prints the newest snapshot in it. It takes no backup, since there is nothing on this machine to back up yet. Then, with the app quit or the daemon stopped:
 
 \`\`\`sh norun
 ledge backup restore --in-place
 \`\`\`
 
-The paths inside the backup are absolute, so this puts the app home, the attached folders, and the profiles back where they were. Then open Ledge, or connect to the server. Your workspaces, images, trash, profiles, and vault are all there, and locked notes open with the passphrase they had ([[Note Locking]]). Backups continue on the new machine with the same repository.
+The paths inside the backup are absolute, so this puts the app home, the attached folders, and the profiles back where they were. \`--snapshot ID\` restores an older one than the newest. Then open Ledge, or connect to the server. Your workspaces, images, trash, profiles, and vault are all there, and locked notes open with the passphrase they had ([[Note Locking]]). Backups continue on the new machine with the same repository.
 
 ## Run restic yourself
 
@@ -11447,7 +11463,7 @@ function createOpLog(opts) {
 }
 
 // src/shared/version.ts
-var BUILD_VERSION = "0.0.1";
+var BUILD_VERSION = "0.0.3";
 
 // src/bun/daemon.ts
 var SOCKET_PATH = join16(APP_HOME, ".server.sock");
@@ -11713,6 +11729,65 @@ import { randomBytes as randomBytes2 } from "crypto";
 import { homedir as homedir7 } from "os";
 import { join as join19 } from "path";
 
+// src/bun/ask.ts
+var reader = null;
+var pending = "";
+async function readLine() {
+  reader ??= Bun.stdin.stream().getReader();
+  const decoder2 = new TextDecoder;
+  for (;; ) {
+    const nl = pending.indexOf(`
+`);
+    if (nl >= 0) {
+      const line = pending.slice(0, nl);
+      pending = pending.slice(nl + 1);
+      return line.replace(/\r$/, "");
+    }
+    const { value, done } = await reader.read();
+    if (done) {
+      const line = pending;
+      pending = "";
+      return line;
+    }
+    pending += decoder2.decode(value, { stream: true });
+  }
+}
+async function readHidden() {
+  const stdin = process.stdin;
+  stdin.setRawMode?.(true);
+  reader ??= Bun.stdin.stream().getReader();
+  let line = "";
+  try {
+    for (;; ) {
+      const { value, done } = await reader.read();
+      if (done)
+        return line;
+      for (const byte of value) {
+        if (byte === 3)
+          process.exit(130);
+        if (byte === 13 || byte === 10)
+          return line;
+        if (byte === 127 || byte === 8)
+          line = line.slice(0, -1);
+        else if (byte >= 32)
+          line += String.fromCharCode(byte);
+      }
+    }
+  } finally {
+    stdin.setRawMode?.(false);
+  }
+}
+async function ask(question, o = {}) {
+  process.stderr.write(`${question}: `);
+  if (o.hidden && process.stdin.isTTY) {
+    const line = await readHidden();
+    process.stderr.write(`
+`);
+    return line.trim();
+  }
+  return (await readLine()).trim();
+}
+
 // src/bun/backup.ts
 import { join as join17 } from "path";
 function backupSet(input) {
@@ -11797,7 +11872,7 @@ function versionAtLeast(version, min) {
 var BACKUP_EVERY_MS = 60 * 60 * 1000;
 var PRUNE_EVERY_MS = 24 * 60 * 60 * 1000;
 var IDLE_EXIT_MIN_GAP_MS = 10 * 60 * 1000;
-var KEEP = { hourly: 24, daily: 30, weekly: 12, monthly: 24 };
+var KEEP = { last: 10, hourly: 24, daily: 30, weekly: 12, monthly: 24 };
 var SNAPSHOT_TAG = "ledge";
 var EMPTY_STATE = {
   version: 1,
@@ -11848,6 +11923,9 @@ function isOverdue(state, now, every = BACKUP_EVERY_MS) {
 function pruneDue(state, now, every = PRUNE_EVERY_MS) {
   return !state.lastPrune || Date.parse(state.lastPrune) + every <= now.getTime();
 }
+function forgetDue(state) {
+  return state.lastSnapshot !== null;
+}
 function idleExitWorthIt(state, now, gap = IDLE_EXIT_MIN_GAP_MS) {
   return !state.lastOk || Date.parse(state.lastOk) + gap <= now.getTime();
 }
@@ -11869,6 +11947,8 @@ function forgetArgs(prune) {
     "forget",
     "--tag",
     SNAPSHOT_TAG,
+    "--keep-last",
+    String(KEEP.last),
     "--keep-hourly",
     String(KEEP.hourly),
     "--keep-daily",
@@ -12184,7 +12264,8 @@ async function runBackup(o = { reason: "now" }) {
       const out = parseBackupOutput(backed.stdout);
       for (const e of out.errors)
         log(`[backup] restic: ${e}`);
-      const previous = readState().lastSnapshot;
+      const state = readState();
+      const previous = state.lastSnapshot;
       if (out.snapshot && previous && previous !== out.snapshot) {
         const diff = await runRestic(restic.path, diffArgs(previous, out.snapshot), env);
         if (diff.code === 0 && parseDiffChanges(diff.stdout) === 0) {
@@ -12195,9 +12276,12 @@ async function runBackup(o = { reason: "now" }) {
             out.snapshot = null;
         }
       }
-      const prune = pruneDue(readState(), at);
-      const forgot = await runRestic(restic.path, forgetArgs(prune), env);
-      if (forgot.code !== 0) {
+      const thin = forgetDue(state);
+      const prune = thin && pruneDue(state, at);
+      if (!thin)
+        log("[backup] the first backup from this machine: the snapshots already in the repository are left as they are");
+      const forgot = thin ? await runRestic(restic.path, forgetArgs(prune), env) : null;
+      if (forgot && forgot.code !== 0) {
         const error = `snapshot ${out.snapshot?.slice(0, 8) ?? "kept"}, but restic forget failed: ${resticSaid(forgot)}`;
         log(`[backup] ${error}`);
         writeState(recordRun(readState(), { at, ok: false, error, snapshot: out.snapshot, skipped }));
@@ -12420,33 +12504,54 @@ async function setup(args) {
       vars["RESTIC_PASSWORD"] = generated;
     }
   }
-  await writeProfile(BACKUP_PROFILE, backupProfileText(vars));
-  const read = readConfig();
-  if (!("config" in read)) {
-    say(`${PROFILE_PATH} is missing ${read.missing.join(", ")}`);
+  const proposed = parseBackupConfig(backupProfileText(vars));
+  if (!("config" in proposed)) {
+    say(`a backup needs ${proposed.missing.join(", ")}`);
     return 1;
   }
-  const env = resticEnv(read.config);
+  const env = resticEnv(proposed.config);
+  const unchanged = already ? `
+Nothing here changed: this machine still backs up to ${already.repository}.` : `
+Nothing was written.`;
   if (existing) {
-    say(`Opening ${read.config.repository}...`);
+    say(`Opening ${proposed.config.repository}...`);
     const r = await runRestic(restic.path, ["cat", "config"], env);
     if (r.code !== 0) {
-      say(`Could not open the repository: ${resticSaid(r)}
-The profile is written at ${PROFILE_PATH}; fix it and run setup again with --replace.`);
+      say(`Could not open the repository: ${resticSaid(r)}${unchanged}`);
       return 1;
     }
   } else {
-    say(`Creating the repository at ${read.config.repository}...`);
+    say(`Creating the repository at ${proposed.config.repository}...`);
     const r = await runRestic(restic.path, ["init"], env);
     if (r.code !== 0) {
       const said = resticSaid(r);
       const hint = /already (exists|initialized)/i.test(said) ? `
-That repository already has backups in it. Run setup again with --existing and its password.` : `
-The profile is written at ${PROFILE_PATH}; fix it and run setup again with --replace.`;
-      say(`Could not create the repository: ${said}${hint}`);
+That repository already has backups in it. Run setup again with --existing and its password.` : "";
+      say(`Could not create the repository: ${said}${hint}${unchanged}`);
       return 1;
     }
   }
+  await writeProfile(BACKUP_PROFILE, backupProfileText(vars));
+  if (existing) {
+    const listed = await listSnapshots();
+    say("");
+    if ("error" in listed)
+      say(`The repository opened, though its snapshots could not be listed: ${listed.error}`);
+    else if (listed.snapshots.length === 0)
+      say("The repository opened. It holds no snapshots yet.");
+    else {
+      const newest = listed.snapshots[0];
+      say(`The repository opened. Its newest snapshot is ${newest.short_id}, from ${snapshotTime(newest.time)}; \`ledge backup snapshots\` lists the rest.`);
+    }
+    say("");
+    say("Nothing has been backed up from this machine yet. To restore this machine, with the app quit or the daemon stopped:");
+    say("");
+    say("    ledge backup restore --in-place");
+    say("");
+    say("Backups run every hour while this machine's Ledge server is up, and once more before it exits.");
+    say(`The repository and its credentials are in ${PROFILE_PATH}, the "${BACKUP_PROFILE}" profile.`);
+    return 0;
+  }
   say("Taking the first backup...");
   await loadWorkspaces();
   const result = await runBackup({ log: say, reason: "setup" });
@@ -12503,9 +12608,12 @@ async function snapshots() {
     return 1;
   }
   for (const s2 of r.snapshots)
-    out(`${s2.short_id}  ${s2.time.replace(/\.\d+/, "").replace("T", " ")}  ${s2.hostname}  ${s2.paths.length} path${s2.paths.length === 1 ? "" : "s"}`);
+    out(`${s2.short_id}  ${snapshotTime(s2.time)}  ${s2.hostname}  ${s2.paths.length} path${s2.paths.length === 1 ? "" : "s"}`);
   return 0;
 }
+function snapshotTime(time) {
+  return time.replace(/\.\d+/, "").replace("T", " ");
+}
 async function restore(args) {
   const config = configured();
   if (!config) {
@@ -12578,63 +12686,6 @@ function valueOf(args, flag) {
   const at = args.indexOf(flag);
   return at >= 0 ? args[at + 1] ?? null : null;
 }
-var reader = null;
-var pending = "";
-async function readLine() {
-  reader ??= Bun.stdin.stream().getReader();
-  const decoder2 = new TextDecoder;
-  for (;; ) {
-    const nl = pending.indexOf(`
-`);
-    if (nl >= 0) {
-      const line = pending.slice(0, nl);
-      pending = pending.slice(nl + 1);
-      return line.replace(/\r$/, "");
-    }
-    const { value, done } = await reader.read();
-    if (done) {
-      const line = pending;
-      pending = "";
-      return line;
-    }
-    pending += decoder2.decode(value, { stream: true });
-  }
-}
-async function readHidden() {
-  const stdin = process.stdin;
-  stdin.setRawMode?.(true);
-  reader ??= Bun.stdin.stream().getReader();
-  let line = "";
-  try {
-    for (;; ) {
-      const { value, done } = await reader.read();
-      if (done)
-        return line;
-      for (const byte of value) {
-        if (byte === 3)
-          process.exit(130);
-        if (byte === 13 || byte === 10)
-          return line;
-        if (byte === 127 || byte === 8)
-          line = line.slice(0, -1);
-        else if (byte >= 32)
-          line += String.fromCharCode(byte);
-      }
-    }
-  } finally {
-    stdin.setRawMode?.(false);
-  }
-}
-async function ask(question, o = {}) {
-  process.stderr.write(`${question}: `);
-  if (o.hidden && process.stdin.isTTY) {
-    const line = await readHidden();
-    process.stderr.write(`
-`);
-    return line.trim();
-  }
-  return (await readLine()).trim();
-}
 
 // node_modules/uqr/dist/index.mjs
 var QrCodeDataType = /* @__PURE__ */ ((QrCodeDataType2) => {
@@ -13315,20 +13366,179 @@ function sshServerAddress(sshConnection) {
     return null;
   return { host: ip, port: port === DEFAULT_PORT ? PORT_UNSET : port };
 }
-function pairAddress(args, sshConnection, hostname) {
+function addressKind(ip) {
+  const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(ip);
+  if (!match)
+    return null;
+  const [a, b, c, d] = match.slice(1).map(Number);
+  if (a > 255 || b > 255 || c > 255 || d > 255)
+    return null;
+  if (a === 127)
+    return "loopback";
+  if (a === 169 && b === 254)
+    return "linkLocal";
+  if (a === 100 && b >= 64 && b <= 127)
+    return "tailnet";
+  if (a === 10 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168)
+    return "private";
+  return "public";
+}
+function sshClientAddress(sshConnection) {
+  const parts = (sshConnection ?? "").trim().split(/\s+/);
+  if (parts.length !== 4)
+    return null;
+  const ip = parts[0].replace(/^::ffff:/i, "");
+  return addressKind(ip) === null ? null : ip;
+}
+var VIRTUAL_INTERFACE = /^(docker|br-|veth|virbr|lxc|lxd|cni|flannel|podman|vmnet|vboxnet)/;
+var NOTES = {
+  tailnetName: "this machine's tailnet name, reachable from anywhere on the tailnet",
+  tailnetAddress: "this machine's tailnet address, reachable from anywhere on the tailnet",
+  ssh: "the address this ssh session reached",
+  sshInside: "the address this ssh session reached, inside a NAT the session came through; a device outside needs the outside address",
+  cloud: "this machine's public address, from the cloud's metadata service",
+  public: (name) => `the public address on ${name}`,
+  private: (name) => `the local network address on ${name}`,
+  name: "this machine's name"
+};
+function addressCandidates(inputs) {
+  const out2 = [];
+  const seen = new Set;
+  const add = (host, source, note) => {
+    const key2 = host.toLowerCase();
+    if (host === "" || seen.has(key2))
+      return;
+    seen.add(key2);
+    out2.push({ host, source, note });
+  };
+  if (inputs.tailnet?.name)
+    add(inputs.tailnet.name, "tailnet", NOTES.tailnetName);
+  for (const ip of inputs.tailnet?.addresses ?? [])
+    if (addressKind(ip) === "tailnet")
+      add(ip, "tailnet", NOTES.tailnetAddress);
+  for (const i of inputs.interfaces)
+    if (addressKind(i.address) === "tailnet")
+      add(i.address, "tailnet", NOTES.tailnetAddress);
+  const session = sshServerAddress(inputs.sshConnection);
+  const client = sshClientAddress(inputs.sshConnection);
+  const crossedNat = session !== null && addressKind(session.host) === "private" && client !== null && addressKind(client) === "public";
+  const cloud = inputs.cloudAddress && addressKind(inputs.cloudAddress) === "public" ? inputs.cloudAddress : null;
+  if (session && !crossedNat)
+    add(session.host, "ssh", NOTES.ssh);
+  if (cloud)
+    add(cloud, "cloud", NOTES.cloud);
+  if (session && crossedNat)
+    add(session.host, "ssh", NOTES.sshInside);
+  const usable = inputs.interfaces.filter((i) => !VIRTUAL_INTERFACE.test(i.name));
+  for (const i of usable)
+    if (addressKind(i.address) === "public")
+      add(i.address, "interface", NOTES.public(i.name));
+  for (const i of usable)
+    if (addressKind(i.address) === "private")
+      add(i.address, "interface", NOTES.private(i.name));
+  add(inputs.hostname, "name", NOTES.name);
+  return out2;
+}
+function tailscaleSelf(json) {
+  let status2;
+  try {
+    status2 = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  if (typeof status2 !== "object" || status2 === null)
+    return null;
+  const { BackendState, Self } = status2;
+  if (BackendState !== "Running" || typeof Self !== "object" || Self === null)
+    return null;
+  const name = typeof Self.DNSName === "string" ? Self.DNSName.replace(/\.$/, "") : "";
+  const ips = Array.isArray(Self.TailscaleIPs) ? Self.TailscaleIPs : [];
+  const addresses = ips.filter((ip) => typeof ip === "string" && addressKind(ip) === "tailnet");
+  return { name: name === "" ? null : name, addresses };
+}
+var METADATA_ORIGIN = "http://169.254.169.254";
+var METADATA_PATHS = [
+  { cloud: "Google Cloud", path: "/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip", headers: { "Metadata-Flavor": "Google" } },
+  {
+    cloud: "Azure",
+    path: "/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2021-02-01&format=text",
+    headers: { Metadata: "true" }
+  },
+  { cloud: "DigitalOcean", path: "/metadata/v1/interfaces/public/0/ipv4/address" },
+  { cloud: "Hetzner", path: "/hetzner/v1/metadata/public-ipv4" }
+];
+var AWS_TOKEN_PATH = "/latest/api/token";
+var DMI_DIR = "/sys/class/dmi/id";
+var DMI_FIELDS = ["sys_vendor", "bios_version", "chassis_asset_tag"];
+var AZURE_ASSET_TAG = "7783-7084-3265-9085-8269-3286-77";
+function inCloud(dmi) {
+  const vendor = (dmi.sys_vendor ?? "").trim();
+  if (/^(Amazon|Google|DigitalOcean|Hetzner)\b/i.test(vendor))
+    return true;
+  if (/amazon/i.test(dmi.bios_version ?? ""))
+    return true;
+  return (dmi.chassis_asset_tag ?? "").trim() === AZURE_ASSET_TAG;
+}
+var TAILSCALE_PATHS = [
+  "/usr/bin/tailscale",
+  "/usr/local/bin/tailscale",
+  "/opt/homebrew/bin/tailscale",
+  "/Applications/Tailscale.app/Contents/MacOS/Tailscale"
+];
+var AWS_ADDRESS_PATH = "/latest/meta-data/public-ipv4";
+function publicAddressAnswer(body) {
+  const answer = body.trim();
+  return addressKind(answer) === "public" ? answer : null;
+}
+function candidateMenu(candidates) {
+  const width = Math.max(...candidates.map((c) => c.host.length));
+  const lines = ["Which address should Ledge on your other devices use to reach this server?"];
+  candidates.forEach((c, i) => lines.push(`  ${String(i + 1).padStart(2)}  ${c.host.padEnd(width)}  ${c.note}`));
+  return `${lines.join(`
+`)}
+`;
+}
+var CHOICE_PROMPT = "A number, or an address as host or host:port [1]";
+function pairAddress(args, sshConnection, candidates, answer) {
   const session = sshServerAddress(sshConnection);
   let port = session?.port ?? PORT_UNSET;
+  let host;
+  let source;
+  let note = "";
+  if (args.host !== undefined) {
+    host = args.host;
+    source = "flag";
+  } else if (answer !== undefined && answer.trim() !== "") {
+    const typed = answer.trim();
+    if (/^\d+$/.test(typed)) {
+      const pick = candidates[Number(typed) - 1];
+      if (!pick)
+        return { error: `There is no address ${typed} in the list.` };
+      ({ host, source, note } = pick);
+    } else {
+      const colon = typed.indexOf(":");
+      host = colon < 0 ? typed : typed.slice(0, colon);
+      source = "typed";
+      if (colon >= 0) {
+        const parsed = parsePort(typed.slice(colon + 1));
+        if (parsed === null || parsed === PORT_UNSET)
+          return { error: `"${typed.slice(colon + 1)}" is not a port from 1 to 65535.` };
+        port = parsed === DEFAULT_PORT ? PORT_UNSET : parsed;
+      }
+    }
+  } else {
+    const pick = candidates[0];
+    if (!pick)
+      return { error: "This machine has no address to put in the code. Run again with --host." };
+    ({ host, source, note } = pick);
+  }
   if (args.port !== undefined) {
     const parsed = parsePort(args.port);
     if (parsed === null || parsed === PORT_UNSET)
       return { error: `"${args.port}" is not a port from 1 to 65535.` };
     port = parsed === DEFAULT_PORT ? PORT_UNSET : parsed;
   }
-  if (args.host !== undefined)
-    return { host: args.host, port, hostFrom: "flag" };
-  if (session)
-    return { host: session.host, port, hostFrom: "ssh" };
-  return { host: hostname, port, hostFrom: "name" };
+  return { host, port, source, note };
 }
 function phoneHostKeys(keygenOutput) {
   const keys = [];
@@ -13374,12 +13584,18 @@ function terminalQR(text) {
 function terminalQRWidth(text) {
   return encode(text, QR_OPTIONS).size;
 }
-var HOST_NOTES = {
-  flag: "",
-  ssh: " (the address this ssh session reached)",
-  name: " (this machine's name; if your phone cannot reach it by that name, run again with --host)"
-};
-function pairReport({ code, keys, hostFrom, columns }) {
+function othersNote(others) {
+  if (others.length === 0)
+    return "";
+  const width = Math.max(...others.map((c) => c.host.length));
+  const lines = ["Other addresses this machine has (run again with --host to use one):"];
+  for (const c of others)
+    lines.push(`  ${c.host.padEnd(width)}  ${c.note}`);
+  return `${lines.join(`
+`)}
+`;
+}
+function pairReport({ code, keys, note, columns }) {
   const link = pairingLink(code);
   const width = terminalQRWidth(link);
   const out2 = [];
@@ -13388,7 +13604,7 @@ function pairReport({ code, keys, hostFrom, columns }) {
   } else {
     out2.push(...terminalQR(link));
   }
-  out2.push("", "Scan the code with Ledge on your phone. It names this server and its host keys, and holds no password or key.", "", `  Account    ${code.user}`, `  Host       ${code.host}${HOST_NOTES[hostFrom]}`, `  Port       ${code.port === PORT_UNSET ? DEFAULT_PORT : code.port}`, ...keys.map((k, i) => `  ${i === 0 ? "Host keys" : "         "}  ${k.fingerprint} (${k.keyType})`), "", link);
+  out2.push("", "Scan the code with Ledge on your phone, or paste the link below into the Mac app's Add Server form. It names this server and its host keys, and holds no password or key.", "", `  Account    ${code.user}`, `  Host       ${code.host}${note === "" ? "" : ` (${note})`}`, `  Port       ${code.port === PORT_UNSET ? DEFAULT_PORT : code.port}`, ...keys.map((k, i) => `  ${i === 0 ? "Host keys" : "         "}  ${k.fingerprint} (${k.keyType})`), "", link);
   return `${out2.join(`
 `)}
 `;
@@ -13401,7 +13617,7 @@ function pairCode(user, address, keys) {
 
 // src/bun/serve.ts
 import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync4 } from "fs";
-import { hostname, userInfo } from "os";
+import { hostname, networkInterfaces, userInfo } from "os";
 import { join as join20 } from "path";
 async function serve2() {
   const upstream = await connectToDaemon();
@@ -13458,9 +13674,18 @@ ${PAIR_USAGE}`, 2);
     if (refusal)
       return fail2(refusal);
   }
-  const address = pairAddress(args, process.env.SSH_CONNECTION, hostname());
+  const candidates = args.host === undefined ? await gatherCandidates() : [];
+  const interactive = args.host === undefined && args.keys !== "-" && process.stdin.isTTY && process.stdout.isTTY;
+  let answer;
+  if (interactive) {
+    process.stderr.write(candidateMenu(candidates));
+    answer = await ask(CHOICE_PROMPT);
+  }
+  const address = pairAddress(args, process.env.SSH_CONNECTION, candidates, answer);
   if ("error" in address)
     return fail2(address.error, 2);
+  if (!interactive)
+    process.stderr.write(othersNote(candidates.filter((c) => c.host !== address.host)));
   let keyText = "";
   if (args.keys === "-")
     keyText = await Bun.stdin.text();
@@ -13503,13 +13728,70 @@ ${PAIR_USAGE}`, 2);
   if ("error" in code)
     return fail2(code.error);
   const columns = process.stdout.isTTY ? process.stdout.columns : undefined;
-  process.stdout.write(pairReport({ code, keys, hostFrom: address.hostFrom, columns }));
+  process.stdout.write(pairReport({ code, keys, note: address.note, columns }));
   return 0;
 }
+async function gatherCandidates() {
+  const interfaces = [];
+  for (const [name, list] of Object.entries(networkInterfaces())) {
+    for (const i of list ?? [])
+      if (i.family === "IPv4" && !i.internal)
+        interfaces.push({ name, address: i.address });
+  }
+  const [tailnet, cloud] = await Promise.all([tailnetSelf(), process.platform === "linux" && inCloud(dmi()) ? cloudAddress() : null]);
+  return addressCandidates({ sshConnection: process.env.SSH_CONNECTION, hostname: hostname(), tailnet, cloudAddress: cloud, interfaces });
+}
+var LOOKUP_MS = 1500;
+function dmi() {
+  const out2 = {};
+  for (const field of DMI_FIELDS) {
+    try {
+      out2[field] = readFileSync4(join20(DMI_DIR, field), "utf8");
+    } catch {}
+  }
+  return out2;
+}
+async function tailnetSelf() {
+  const path = TAILSCALE_PATHS.find((p) => existsSync3(p));
+  if (!path)
+    return null;
+  try {
+    const p = Bun.spawn([path, "status", "--json"], { stdin: "ignore", stdout: "pipe", stderr: "ignore" });
+    const timer = setTimeout(() => p.kill(), LOOKUP_MS);
+    const json = await new Response(p.stdout).text();
+    clearTimeout(timer);
+    return tailscaleSelf(json);
+  } catch {
+    return null;
+  }
+}
+async function metadata(path, init = {}) {
+  try {
+    const res = await fetch(`${METADATA_ORIGIN}${path}`, { ...init, signal: AbortSignal.timeout(LOOKUP_MS) });
+    return res.ok ? await res.text() : null;
+  } catch {
+    return null;
+  }
+}
+async function cloudAddress() {
+  const aws = (async () => {
+    const token = await metadata(AWS_TOKEN_PATH, { method: "PUT", headers: { "X-aws-ec2-metadata-token-ttl-seconds": "60" } });
+    return metadata(AWS_ADDRESS_PATH, token ? { headers: { "X-aws-ec2-metadata-token": token } } : {});
+  })();
+  const others = METADATA_PATHS.map((m) => metadata(m.path, { headers: m.headers }));
+  const answers = await Promise.all([aws, ...others]);
+  for (const body of answers) {
+    const address = body === null ? null : publicAddressAnswer(body);
+    if (address)
+      return address;
+  }
+  return null;
+}
 var PAIR_USAGE = [
   "usage: ledge pair [--user NAME] [--host ADDRESS] [--port N] [--keys FILE]",
-  "  --user   the account a phone signs in as (default: whoever runs pair)",
-  "  --host   the name or IPv4 address a phone dials (default: this ssh session's address, or the machine's name)",
+  "  --user   the account Ledge signs in as (default: whoever runs pair)",
+  "  --host   the name or IPv4 address Ledge connects to (default: a menu of this machine's addresses on a terminal,",
+  "           else the first of them: its tailnet name, this ssh session's address, its public address, its name)",
   "  --port   sshd's port (default: this ssh session's port, or 22)",
   "  --keys   public host keys to describe, - for stdin (default: /etc/ssh/ssh_host_*_key.pub)"
 ].join(`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ledge-server",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "The Ledge server: your notes and shells on another machine, reached over ssh.",
   "license": "Apache-2.0",
   "type": "module",