ledge-server 0.0.2 → 0.0.3

package/README.md

@@ -29,7 +29,7 @@ ledge pair
 ```
 
 It lists the machine's addresses, with what each one reaches, and asks which
-one the phone should dial. Scan the code with Ledge on a phone, or paste the
+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.
 
@@ -86,7 +86,7 @@ sudo ln -s "$(command -v bun)" /usr/local/bin/bun
 | --- | --- |
 | `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 a phone should dial. `--user`, `--host`, and `--port` override what it describes. |
+| `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 mcp` | The Ledge MCP server on stdin and stdout, for an agent running on this machine. |
 | `ledge ls`, `ledge cat`, `ledge search`, ... | Notes from this machine's own shell. `ledge help` lists them all. |

package/lib/serve.js

@@ -6236,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. |
@@ -6415,11 +6415,11 @@ A pairing code names a server and its host keys, so the phone can add it without
 ledge pair
 \`\`\`
 
-On a terminal, it first lists every address the machine has, with a note on which phones 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.
+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, so pick the one the phone reaches from where it will be. A tailnet name works from anywhere the phone is on the tailnet. A home network address works from a phone 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.
+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, 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.
 
@@ -7176,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
@@ -7211,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
 
@@ -11451,7 +11463,7 @@ function createOpLog(opts) {
 }
 
 // src/shared/version.ts
-var BUILD_VERSION = "0.0.2";
+var BUILD_VERSION = "0.0.3";
 
 // src/bun/daemon.ts
 var SOCKET_PATH = join16(APP_HOME, ".server.sock");
@@ -11860,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,
@@ -11911,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();
 }
@@ -11932,6 +11947,8 @@ function forgetArgs(prune) {
     "forget",
     "--tag",
     SNAPSHOT_TAG,
+    "--keep-last",
+    String(KEEP.last),
     "--keep-hourly",
     String(KEEP.hourly),
     "--keep-daily",
@@ -12247,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) {
@@ -12258,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 }));
@@ -12483,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" });
@@ -12566,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) {
@@ -13347,14 +13392,14 @@ function sshClientAddress(sshConnection) {
 }
 var VIRTUAL_INTERFACE = /^(docker|br-|veth|virbr|lxc|lxd|cni|flannel|podman|vmnet|vboxnet)/;
 var NOTES = {
-  tailnetName: "this machine's tailnet name; a phone on the tailnet reaches it from anywhere",
-  tailnetAddress: "this machine's tailnet address; a phone on the tailnet reaches it from anywhere",
+  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 phone outside needs the outside address",
+  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}; a phone on that network reaches it`,
-  name: "this machine's name; a phone on the same network may resolve it"
+  private: (name) => `the local network address on ${name}`,
+  name: "this machine's name"
 };
 function addressCandidates(inputs) {
   const out2 = [];
@@ -13447,7 +13492,7 @@ function publicAddressAnswer(body) {
 }
 function candidateMenu(candidates) {
   const width = Math.max(...candidates.map((c) => c.host.length));
-  const lines = ["Which address should a phone dial?"];
+  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(`
 `)}
@@ -13484,7 +13529,7 @@ function pairAddress(args, sshConnection, candidates, answer) {
   } else {
     const pick = candidates[0];
     if (!pick)
-      return { error: "This machine has no address a phone could dial. Run again with --host." };
+      return { error: "This machine has no address to put in the code. Run again with --host." };
     ({ host, source, note } = pick);
   }
   if (args.port !== undefined) {
@@ -13559,7 +13604,7 @@ function pairReport({ code, keys, note, 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}${note === "" ? "" : ` (${note})`}`, `  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(`
 `)}
 `;
@@ -13744,8 +13789,8 @@ async function cloudAddress() {
 }
 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: a menu of this machine's addresses on a terminal,",
+  "  --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)"

package/package.json

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