nixamp 0.22.1 → 0.23.0

package/dist/main.js

@@ -56,6 +56,7 @@ const HELP = `nixamp — it really whips the terminal's ass.
   nixamp token create|list|revoke  tokens for a machine that cannot sign in
   nixamp dns [set|rm]           names under your handle, for your servers
   nixamp library [folder]       where the media is; the daemon serves this and nothing outside it
+  nixamp sync [save|load|status] your settings on every machine, against your account (--force, --dry-run)
   nixamp server list|add|remove  the machines you run, kept against your account
   nixamp party list|join|host   watch parties, here and on the sites nixamp is connected to
   nixamp mcp                     speak Model Context Protocol on stdin, for an agent
@@ -497,6 +498,11 @@ export async function main() {
         process.exitCode = await dns(rest);
         return;
     }
+    if (first === "sync") {
+        const { syncCommand } = await import("./sync.js");
+        process.exitCode = await syncCommand(rest);
+        return;
+    }
     if (first === "library") {
         const { libraryCommand } = await import("./library.js");
         process.exitCode = await libraryCommand(rest);

package/dist/server.d.ts

@@ -18,6 +18,7 @@ import { CompressionService } from "./compression/service.ts";
 import { Enricher } from "./enrich.ts";
 import { Follows } from "./follows.ts";
 import { Favorites } from "./favorites.ts";
+import { SettingsSync } from "./settings-sync.ts";
 import { Catalogs } from "./catalogs.ts";
 import { Names } from "./names.ts";
 import { Certs } from "./certs.ts";
@@ -654,6 +655,8 @@ export interface HandlerOptions {
     follows?: Follows;
     /** The servers an account hearted. nixamp.com only, like follows. */
     favorites?: Favorites;
+    /** Settings sync, on the directory: a member's settings under revisions, reached by the same session. */
+    settingsSync?: SettingsSync;
     /** Scheduled and live sessions, kept by NixAmp and shared by branded clients. */
     events?: LiveEvents;
     /** Versioned panel layouts, including event and user overrides. */

package/dist/server.js

@@ -47,6 +47,7 @@ import { CALL_IN_NUMBER, OPT_IN_PATH, optInPage } from "./optin.js";
 import pg from "pg";
 import { Follows, phoneFrom } from "./follows.js";
 import { Favorites, favoriteUrl } from "./favorites.js";
+import { SettingsSync, SETTINGS_BODY_LIMIT } from "./settings-sync.js";
 import { Catalogs, shownCatalog, shownEntry } from "./catalogs.js";
 import { Porkbun, isIPv4, isIPv6 } from "./dns.js";
 import { NameError, Names } from "./names.js";
@@ -1562,6 +1563,31 @@ export function createHandler(engine, options) {
             json(response, 405, { error: "GET, PUT or DELETE" });
             return;
         }
+        // --- settings sync: your settings on every machine, against the account ----
+        //
+        // The compression policy and the remembered channels, as one snapshot
+        // under a revision (@profullstack/synconfig). The directory stores what
+        // the client sent and hands it back; it never reads the files inside.
+        if ((path === "/api/v1/settings" || path === "/api/v1/settings/revisions") && options.settingsSync && options.accounts) {
+            const me = await options.accounts.whoIs(tokenFrom(request.headers));
+            if (me === null) {
+                json(response, 401, { error: "sign in to sync settings" });
+                return;
+            }
+            let body;
+            if (request.method === "PUT") {
+                try {
+                    body = JSON.parse(await readBody(request, SETTINGS_BODY_LIMIT));
+                }
+                catch {
+                    json(response, 400, { error: "bad JSON" });
+                    return;
+                }
+            }
+            const reply = await options.settingsSync.handle(request.method ?? "GET", path, me.id, body);
+            json(response, reply.status, reply.body);
+            return;
+        }
         if (path.startsWith("/api/v1/follows") && options.follows && options.accounts) {
             const me = await options.accounts.whoIs(tokenFrom(request.headers));
             if (me === null) {
@@ -4554,6 +4580,7 @@ export async function serve(argv, version = "0.1.0") {
         : undefined;
     const follows = pool ? new Follows(pool) : undefined;
     const favorites = pool ? new Favorites(pool) : undefined;
+    const settingsSync = pool ? new SettingsSync(pool) : undefined;
     const nixampSite = (process.env["NIXAMP_SITE"] ?? DEFAULT_DIRECTORY).replace(/\/+$/, "");
     const events = pool ? new LiveEvents(pool) : undefined;
     const layouts = pool ? new Layouts(pool) : undefined;
@@ -4968,6 +4995,7 @@ export async function serve(argv, version = "0.1.0") {
         ...(directory ? { directory } : {}),
         ...(follows ? { follows, vapidPublicKey } : {}),
         ...(favorites ? { favorites } : {}),
+        ...(settingsSync ? { settingsSync } : {}),
         ...(events ? { events } : {}),
         ...(layouts ? { layouts } : {}),
         ...(rooms ? { rooms } : {}),

package/dist/settings-sync.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Settings sync, the account half: a member's nixamp settings as one snapshot
+ * under a revision, kept on nixamp.com against the account like favourites
+ * and layouts are.
+ *
+ * The rules (one digest both sides compute, a conflict rather than a merge
+ * when two machines both saved, ten revisions kept) are @profullstack/synconfig's;
+ * this file is the store over the directory's Postgres and the three routes,
+ * answered the way the rest of the API answers.
+ *
+ *   GET  /api/v1/settings            the latest snapshot, or { empty: true }
+ *   PUT  /api/v1/settings            { snapshot, ifRevision } → a revision, or 409
+ *   GET  /api/v1/settings/revisions  what is kept
+ */
+import { type HandlerReply, type Snapshot, type SnapshotStore, type StoredSnapshot } from "@profullstack/synconfig/server";
+import type { Queryable } from "./follows.ts";
+/** A snapshot PUT may be this large; the rest of the API reads 64 KB bodies. */
+export declare const SETTINGS_BODY_LIMIT: number;
+export declare class SettingsSync {
+    private readonly db;
+    private ready;
+    readonly store: SnapshotStore;
+    constructor(db: Queryable);
+    private ensure;
+    latest(accountId: string): Promise<StoredSnapshot | null>;
+    /**
+     * The revision is chosen inside the INSERT and the precondition is checked
+     * there, by a HAVING on the same aggregate, so two machines saving at once
+     * produce one revision and one conflict. The primary key is the backstop.
+     */
+    insert(accountId: string, entry: {
+        digest: string;
+        host: string | null;
+        version: string | null;
+        size: number;
+        body: Snapshot;
+    }, ifRevision: number | null): Promise<{
+        conflict: true;
+        revision: number;
+        savedAt?: undefined;
+    } | {
+        conflict?: undefined;
+        revision: number;
+        savedAt: string;
+    }>;
+    list(accountId: string, limit: number): Promise<{
+        revision: number;
+        digest: string;
+        host: string | null;
+        version: string | null;
+        size: number;
+        savedAt: string;
+    }[]>;
+    /** One request, once the account is known. Pure over the store, so the route test needs no socket. */
+    handle(method: string, path: string, accountId: string, body: unknown): Promise<HandlerReply>;
+}

package/dist/settings-sync.js

@@ -0,0 +1,114 @@
+/**
+ * Settings sync, the account half: a member's nixamp settings as one snapshot
+ * under a revision, kept on nixamp.com against the account like favourites
+ * and layouts are.
+ *
+ * The rules (one digest both sides compute, a conflict rather than a merge
+ * when two machines both saved, ten revisions kept) are @profullstack/synconfig's;
+ * this file is the store over the directory's Postgres and the three routes,
+ * answered the way the rest of the API answers.
+ *
+ *   GET  /api/v1/settings            the latest snapshot, or { empty: true }
+ *   PUT  /api/v1/settings            { snapshot, ifRevision } → a revision, or 409
+ *   GET  /api/v1/settings/revisions  what is kept
+ */
+import { KEEP_REVISIONS, handleGet, handlePut, handleRevisions } from "@profullstack/synconfig/server";
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS settings_snapshots (
+    account_id  TEXT NOT NULL,
+    revision    INTEGER NOT NULL,
+    digest      TEXT NOT NULL,
+    host        TEXT,
+    version     TEXT,
+    size        INTEGER NOT NULL,
+    body        JSONB NOT NULL,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (account_id, revision)
+  );
+`;
+/** A snapshot PUT may be this large; the rest of the API reads 64 KB bodies. */
+export const SETTINGS_BODY_LIMIT = 300 * 1024;
+const shape = (row) => ({
+    revision: Number(row["revision"]),
+    digest: String(row["digest"]),
+    host: row["host"] ?? null,
+    version: row["version"] ?? null,
+    size: Number(row["size"]),
+    body: (typeof row["body"] === "string" ? JSON.parse(row["body"]) : row["body"]),
+    savedAt: new Date(row["created_at"]).toISOString(),
+});
+export class SettingsSync {
+    db;
+    ready = null;
+    store;
+    constructor(db) {
+        this.db = db;
+        this.store = {
+            latest: (accountId) => this.latest(accountId),
+            insert: (accountId, entry, ifRevision) => this.insert(accountId, entry, ifRevision),
+            list: (accountId, limit) => this.list(accountId, limit),
+        };
+    }
+    async ensure() {
+        this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+        await this.ready;
+    }
+    async latest(accountId) {
+        await this.ensure();
+        const { rows } = await this.db.query(`SELECT revision, digest, host, version, size, body, created_at FROM settings_snapshots
+        WHERE account_id = $1 ORDER BY revision DESC LIMIT 1`, [accountId]);
+        return rows[0] ? shape(rows[0]) : null;
+    }
+    /**
+     * The revision is chosen inside the INSERT and the precondition is checked
+     * there, by a HAVING on the same aggregate, so two machines saving at once
+     * produce one revision and one conflict. The primary key is the backstop.
+     */
+    async insert(accountId, entry, ifRevision) {
+        await this.ensure();
+        let rows;
+        try {
+            ({ rows } = await this.db.query(`INSERT INTO settings_snapshots (account_id, revision, digest, host, version, size, body)
+         SELECT $1, COALESCE(MAX(revision), 0) + 1, $2, $3, $4, $5, $6::jsonb
+           FROM settings_snapshots WHERE account_id = $1
+         HAVING $7::int IS NULL OR COALESCE(MAX(revision), 0) = $7::int
+         RETURNING revision, created_at`, [accountId, entry.digest, entry.host, entry.version, entry.size, JSON.stringify(entry.body), ifRevision]));
+        }
+        catch (error) {
+            if (/duplicate key|unique/i.test(String(error.message)))
+                rows = [];
+            else
+                throw error;
+        }
+        if (!rows[0]) {
+            const current = await this.latest(accountId);
+            return { conflict: true, revision: current?.revision ?? 0 };
+        }
+        const revision = Number(rows[0]["revision"]);
+        await this.db.query(`DELETE FROM settings_snapshots WHERE account_id = $1 AND revision <= $2`, [accountId, revision - KEEP_REVISIONS]);
+        return { revision, savedAt: new Date(rows[0]["created_at"]).toISOString() };
+    }
+    async list(accountId, limit) {
+        await this.ensure();
+        const { rows } = await this.db.query(`SELECT revision, digest, host, version, size, created_at FROM settings_snapshots
+        WHERE account_id = $1 ORDER BY revision DESC LIMIT $2`, [accountId, limit]);
+        return rows.map((row) => {
+            const { body: _body, ...rest } = shape({ ...row, body: "{}" });
+            void _body;
+            return rest;
+        });
+    }
+    /** One request, once the account is known. Pure over the store, so the route test needs no socket. */
+    async handle(method, path, accountId, body) {
+        if (path === "/api/v1/settings/revisions") {
+            if (method !== "GET")
+                return { status: 405, body: { error: "GET only" } };
+            return handleRevisions(this.store, accountId);
+        }
+        if (method === "GET")
+            return handleGet(this.store, accountId, { emptyStatus: 200 });
+        if (method === "PUT")
+            return handlePut(this.store, accountId, body);
+        return { status: 405, body: { error: "GET or PUT" } };
+    }
+}

package/dist/sync.d.ts

@@ -0,0 +1,6 @@
+import { type SyncContext, type SyncPolicy } from "@profullstack/synconfig";
+export declare const SYNC_POLICY: SyncPolicy;
+/** The account the snapshot lives at. Null when not signed in. */
+export declare function syncContext(fetcher?: typeof fetch): SyncContext | null;
+/** `nixamp sync [status|save|load|revisions] [--force] [--dry-run]`. Returns the exit code. */
+export declare function syncCommand(argv: string[], fetcher?: typeof fetch): Promise<number>;

package/dist/sync.js

@@ -0,0 +1,124 @@
+/**
+ * `nixamp sync`: your settings on every machine, through your nixamp.com account.
+ *
+ * What syncs is what you decided, not what a machine is: the compression
+ * policy (compression.json) and the channels you remembered (channels.json).
+ * The library path is a place on one disk, the session and the share keys
+ * are credentials, the catalogs carry provider URLs with credentials in
+ * them, and the daemon's state belongs to one box; none of those leave.
+ *
+ * The mechanism is @profullstack/synconfig: one snapshot under a revision,
+ * a conflict rather than a merge when two machines both saved, and a marker
+ * so a load never overwrites an unsynced local edit.
+ */
+import { hostname } from "node:os";
+import { createClient, load, save, status } from "@profullstack/synconfig";
+import { stateDir } from "./daemon.js";
+import { readSession } from "./session.js";
+import { version } from "./meta.js";
+export const SYNC_POLICY = {
+    files: [
+        { path: "compression.json", json: true, label: "compression policy" },
+        { path: "channels.json", json: true, label: "remembered channels" },
+    ],
+    never: ["config.json", "session.json", "keys.json", "cookies.txt", "daemon.json", "index.json", "enrich.json", "sync.json"],
+    neverPrefixes: ["tls", "catalogs", "relay-cache"],
+    neverSuffixes: [".log", ".pem", ".pid", ".sock"],
+};
+/** The account the snapshot lives at. Null when not signed in. */
+export function syncContext(fetcher = fetch) {
+    const session = readSession();
+    if (session === null)
+        return null;
+    return {
+        rootDir: stateDir(),
+        policy: SYNC_POLICY,
+        client: createClient({ baseUrl: session.site, path: "/api/v1/settings", token: session.token, fetchImpl: fetcher }),
+        api: session.site,
+        host: hostname(),
+        app: `nixamp ${version()}`,
+    };
+}
+const when = (iso) => (iso ? iso.slice(0, 16).replace("T", " ") : "never");
+/** `nixamp sync [status|save|load|revisions] [--force] [--dry-run]`. Returns the exit code. */
+export async function syncCommand(argv, fetcher = fetch) {
+    const [command = "status", ...rest] = argv;
+    const force = rest.includes("--force");
+    const dryRun = rest.includes("--dry-run");
+    const ctx = syncContext(fetcher);
+    if (ctx === null) {
+        console.error("nixamp: not signed in. Try `nixamp login`; settings sync keeps them on your account.");
+        return 1;
+    }
+    try {
+        if (command === "status") {
+            const state = await status(ctx);
+            console.log(`here     ${state.marker ? `revision ${state.marker.revision}, synced ${when(state.marker.at)}` : "never synced"}`);
+            console.log(`account  ${state.serverRevision !== undefined ? `revision ${state.serverRevision}, saved ${when(state.serverSavedAt)}${state.serverHost ? ` from ${state.serverHost}` : ""}` : "nothing yet"}`);
+            if (state.drifted.length)
+                console.log(`changed here: ${state.drifted.join(", ")}  (nixamp sync save)`);
+            if (state.behind)
+                console.log("the account is newer  (nixamp sync load)");
+            if (state.marker && !state.drifted.length && !state.behind)
+                console.log("in sync.");
+            return 0;
+        }
+        if (command === "save") {
+            const result = await save(ctx, { force });
+            for (const skip of result.skipped)
+                console.error(`  skipped ${skip.path}: ${skip.reason}`);
+            if (result.status === "saved")
+                console.log(`saved revision ${result.revision}: ${result.files} file${result.files === 1 ? "" : "s"}`);
+            else if (result.status === "unchanged")
+                console.log(`nothing changed since revision ${result.revision}`);
+            else if (result.status === "empty")
+                console.log("nothing to save: no compression policy or remembered channels here yet");
+            else {
+                console.error(`nixamp: not saved; another machine saved revision ${result.serverRevision} first. \`nixamp sync load\` to take theirs, or \`nixamp sync save --force\`.`);
+                return 1;
+            }
+            return 0;
+        }
+        if (command === "load") {
+            const result = await load(ctx, { force, dryRun });
+            for (const reject of result.rejected)
+                console.error(`  ignored ${reject.path}: ${reject.reason}`);
+            switch (result.status) {
+                case "empty":
+                    console.log("nothing on the account yet. `nixamp sync save` on the machine whose settings you want.");
+                    return 0;
+                case "same":
+                    console.log(`already at revision ${result.revision}`);
+                    return 0;
+                case "planned":
+                    for (const entry of result.plan)
+                        console.log(`  ${entry.status.padEnd(8)} ${entry.path}`);
+                    console.log(`would take revision ${result.revision}; nothing written`);
+                    return 0;
+                case "newer":
+                    console.error("nixamp: the account holds settings saved by a newer nixamp. `nixamp update` first.");
+                    return 1;
+                case "local_changes":
+                    console.error(`nixamp: not loaded; ${result.drifted.join(", ")} changed here since the last sync. \`nixamp sync save\` to keep yours, \`nixamp sync load --force\` to replace them.`);
+                    return 1;
+                case "loaded":
+                    console.log(`loaded revision ${result.revision}: ${result.written.join(", ")}`);
+                    return 0;
+            }
+        }
+        if (command === "revisions") {
+            const revisions = await ctx.client.revisions();
+            if (!revisions.length)
+                console.log("nothing saved yet");
+            for (const entry of revisions)
+                console.log(`${String(entry.revision).padStart(4)}  ${when(entry.savedAt)}  ${(entry.host ?? "").padEnd(16)}  ${entry.version ?? ""}  ${entry.size} bytes`);
+            return 0;
+        }
+        console.error(`nixamp sync: unknown action ${command}. Try status, save, load or revisions.`);
+        return 64;
+    }
+    catch (error) {
+        console.error(`nixamp: ${error.message}`);
+        return 1;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.22.1",
+  "version": "0.23.0",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",
@@ -46,6 +46,7 @@
   "dependencies": {
     "@profullstack/auth-system": "^0.6.0",
     "@profullstack/hqtui": "^0.5.0",
+    "@profullstack/synconfig": "^0.1.2",
     "@profullstack/throttle": "0.2.2",
     "@profullstack/x402-gateway": "0.6.0",
     "acme-client": "5.4.0",

package/src/main.ts

@@ -80,6 +80,7 @@ const HELP = `nixamp — it really whips the terminal's ass.
   nixamp token create|list|revoke  tokens for a machine that cannot sign in
   nixamp dns [set|rm]           names under your handle, for your servers
   nixamp library [folder]       where the media is; the daemon serves this and nothing outside it
+  nixamp sync [save|load|status] your settings on every machine, against your account (--force, --dry-run)
   nixamp server list|add|remove  the machines you run, kept against your account
   nixamp party list|join|host   watch parties, here and on the sites nixamp is connected to
   nixamp mcp                     speak Model Context Protocol on stdin, for an agent
@@ -526,6 +527,11 @@ export async function main(): Promise<void> {
     process.exitCode = await dns(rest);
     return;
   }
+  if (first === "sync") {
+    const { syncCommand } = await import("./sync.ts");
+    process.exitCode = await syncCommand(rest);
+    return;
+  }
   if (first === "library") {
     const { libraryCommand } = await import("./library.ts");
     process.exitCode = await libraryCommand(rest);

package/src/server.ts

@@ -68,6 +68,7 @@ import { CALL_IN_NUMBER, OPT_IN_PATH, optInPage } from "./optin.ts";
 import pg from "pg";
 import { Follows, phoneFrom } from "./follows.ts";
 import { Favorites, favoriteUrl } from "./favorites.ts";
+import { SettingsSync, SETTINGS_BODY_LIMIT } from "./settings-sync.ts";
 import { Catalogs, shownCatalog, shownEntry } from "./catalogs.ts";
 import { Porkbun, isIPv4, isIPv6, type DnsZone } from "./dns.ts";
 import { NameError, Names } from "./names.ts";
@@ -1593,6 +1594,8 @@ export interface HandlerOptions {
   follows?: Follows;
   /** The servers an account hearted. nixamp.com only, like follows. */
   favorites?: Favorites;
+  /** Settings sync, on the directory: a member's settings under revisions, reached by the same session. */
+  settingsSync?: SettingsSync;
   /** Scheduled and live sessions, kept by NixAmp and shared by branded clients. */
   events?: LiveEvents;
   /** Versioned panel layouts, including event and user overrides. */
@@ -2013,6 +2016,31 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
       return;
     }
 
+    // --- settings sync: your settings on every machine, against the account ----
+    //
+    // The compression policy and the remembered channels, as one snapshot
+    // under a revision (@profullstack/synconfig). The directory stores what
+    // the client sent and hands it back; it never reads the files inside.
+    if ((path === "/api/v1/settings" || path === "/api/v1/settings/revisions") && options.settingsSync && options.accounts) {
+      const me = await options.accounts.whoIs(tokenFrom(request.headers));
+      if (me === null) {
+        json(response, 401, { error: "sign in to sync settings" });
+        return;
+      }
+      let body: unknown;
+      if (request.method === "PUT") {
+        try {
+          body = JSON.parse(await readBody(request, SETTINGS_BODY_LIMIT)) as unknown;
+        } catch {
+          json(response, 400, { error: "bad JSON" });
+          return;
+        }
+      }
+      const reply = await options.settingsSync.handle(request.method ?? "GET", path, me.id, body);
+      json(response, reply.status, reply.body);
+      return;
+    }
+
     if (path.startsWith("/api/v1/follows") && options.follows && options.accounts) {
       const me = await options.accounts.whoIs(tokenFrom(request.headers));
       if (me === null) {
@@ -5156,6 +5184,7 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
       : undefined;
   const follows = pool ? new Follows(pool) : undefined;
   const favorites = pool ? new Favorites(pool) : undefined;
+  const settingsSync = pool ? new SettingsSync(pool) : undefined;
   const nixampSite = (process.env["NIXAMP_SITE"] ?? DEFAULT_DIRECTORY).replace(/\/+$/, "");
   const events = pool ? new LiveEvents(pool) : undefined;
   const layouts = pool ? new Layouts(pool) : undefined;
@@ -5587,6 +5616,7 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     ...(directory ? { directory } : {}),
     ...(follows ? { follows, vapidPublicKey } : {}),
     ...(favorites ? { favorites } : {}),
+    ...(settingsSync ? { settingsSync } : {}),
     ...(events ? { events } : {}),
     ...(layouts ? { layouts } : {}),
     ...(rooms ? { rooms } : {}),

package/src/settings-sync.ts

@@ -0,0 +1,126 @@
+/**
+ * Settings sync, the account half: a member's nixamp settings as one snapshot
+ * under a revision, kept on nixamp.com against the account like favourites
+ * and layouts are.
+ *
+ * The rules (one digest both sides compute, a conflict rather than a merge
+ * when two machines both saved, ten revisions kept) are @profullstack/synconfig's;
+ * this file is the store over the directory's Postgres and the three routes,
+ * answered the way the rest of the API answers.
+ *
+ *   GET  /api/v1/settings            the latest snapshot, or { empty: true }
+ *   PUT  /api/v1/settings            { snapshot, ifRevision } → a revision, or 409
+ *   GET  /api/v1/settings/revisions  what is kept
+ */
+import { KEEP_REVISIONS, handleGet, handlePut, handleRevisions, type HandlerReply, type Snapshot, type SnapshotStore, type StoredSnapshot } from "@profullstack/synconfig/server";
+import type { Queryable } from "./follows.ts";
+
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS settings_snapshots (
+    account_id  TEXT NOT NULL,
+    revision    INTEGER NOT NULL,
+    digest      TEXT NOT NULL,
+    host        TEXT,
+    version     TEXT,
+    size        INTEGER NOT NULL,
+    body        JSONB NOT NULL,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (account_id, revision)
+  );
+`;
+
+/** A snapshot PUT may be this large; the rest of the API reads 64 KB bodies. */
+export const SETTINGS_BODY_LIMIT = 300 * 1024;
+
+const shape = (row: Record<string, unknown>): StoredSnapshot => ({
+  revision: Number(row["revision"]),
+  digest: String(row["digest"]),
+  host: (row["host"] as string | null) ?? null,
+  version: (row["version"] as string | null) ?? null,
+  size: Number(row["size"]),
+  body: (typeof row["body"] === "string" ? JSON.parse(row["body"] as string) : row["body"]) as Snapshot,
+  savedAt: new Date(row["created_at"] as string | Date).toISOString(),
+});
+
+export class SettingsSync {
+  private ready: Promise<void> | null = null;
+  readonly store: SnapshotStore;
+
+  constructor(private readonly db: Queryable) {
+    this.store = {
+      latest: (accountId) => this.latest(accountId),
+      insert: (accountId, entry, ifRevision) => this.insert(accountId, entry, ifRevision),
+      list: (accountId, limit) => this.list(accountId, limit),
+    };
+  }
+
+  private async ensure(): Promise<void> {
+    this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+    await this.ready;
+  }
+
+  async latest(accountId: string): Promise<StoredSnapshot | null> {
+    await this.ensure();
+    const { rows } = await this.db.query(
+      `SELECT revision, digest, host, version, size, body, created_at FROM settings_snapshots
+        WHERE account_id = $1 ORDER BY revision DESC LIMIT 1`,
+      [accountId],
+    );
+    return rows[0] ? shape(rows[0]) : null;
+  }
+
+  /**
+   * The revision is chosen inside the INSERT and the precondition is checked
+   * there, by a HAVING on the same aggregate, so two machines saving at once
+   * produce one revision and one conflict. The primary key is the backstop.
+   */
+  async insert(accountId: string, entry: { digest: string; host: string | null; version: string | null; size: number; body: Snapshot }, ifRevision: number | null) {
+    await this.ensure();
+    let rows: Record<string, unknown>[];
+    try {
+      ({ rows } = await this.db.query(
+        `INSERT INTO settings_snapshots (account_id, revision, digest, host, version, size, body)
+         SELECT $1, COALESCE(MAX(revision), 0) + 1, $2, $3, $4, $5, $6::jsonb
+           FROM settings_snapshots WHERE account_id = $1
+         HAVING $7::int IS NULL OR COALESCE(MAX(revision), 0) = $7::int
+         RETURNING revision, created_at`,
+        [accountId, entry.digest, entry.host, entry.version, entry.size, JSON.stringify(entry.body), ifRevision],
+      ));
+    } catch (error) {
+      if (/duplicate key|unique/i.test(String((error as Error).message))) rows = [];
+      else throw error;
+    }
+    if (!rows[0]) {
+      const current = await this.latest(accountId);
+      return { conflict: true as const, revision: current?.revision ?? 0 };
+    }
+    const revision = Number(rows[0]["revision"]);
+    await this.db.query(`DELETE FROM settings_snapshots WHERE account_id = $1 AND revision <= $2`, [accountId, revision - KEEP_REVISIONS]);
+    return { revision, savedAt: new Date(rows[0]["created_at"] as string | Date).toISOString() };
+  }
+
+  async list(accountId: string, limit: number) {
+    await this.ensure();
+    const { rows } = await this.db.query(
+      `SELECT revision, digest, host, version, size, created_at FROM settings_snapshots
+        WHERE account_id = $1 ORDER BY revision DESC LIMIT $2`,
+      [accountId, limit],
+    );
+    return rows.map((row) => {
+      const { body: _body, ...rest } = shape({ ...row, body: "{}" });
+      void _body;
+      return rest;
+    });
+  }
+
+  /** One request, once the account is known. Pure over the store, so the route test needs no socket. */
+  async handle(method: string, path: string, accountId: string, body: unknown): Promise<HandlerReply> {
+    if (path === "/api/v1/settings/revisions") {
+      if (method !== "GET") return { status: 405, body: { error: "GET only" } };
+      return handleRevisions(this.store, accountId);
+    }
+    if (method === "GET") return handleGet(this.store, accountId, { emptyStatus: 200 });
+    if (method === "PUT") return handlePut(this.store, accountId, body);
+    return { status: 405, body: { error: "GET or PUT" } };
+  }
+}

package/src/sync.ts

@@ -0,0 +1,116 @@
+/**
+ * `nixamp sync`: your settings on every machine, through your nixamp.com account.
+ *
+ * What syncs is what you decided, not what a machine is: the compression
+ * policy (compression.json) and the channels you remembered (channels.json).
+ * The library path is a place on one disk, the session and the share keys
+ * are credentials, the catalogs carry provider URLs with credentials in
+ * them, and the daemon's state belongs to one box; none of those leave.
+ *
+ * The mechanism is @profullstack/synconfig: one snapshot under a revision,
+ * a conflict rather than a merge when two machines both saved, and a marker
+ * so a load never overwrites an unsynced local edit.
+ */
+import { hostname } from "node:os";
+import { createClient, load, save, status, type SyncContext, type SyncPolicy } from "@profullstack/synconfig";
+import { stateDir } from "./daemon.ts";
+import { readSession } from "./session.ts";
+import { version } from "./meta.ts";
+
+export const SYNC_POLICY: SyncPolicy = {
+  files: [
+    { path: "compression.json", json: true, label: "compression policy" },
+    { path: "channels.json", json: true, label: "remembered channels" },
+  ],
+  never: ["config.json", "session.json", "keys.json", "cookies.txt", "daemon.json", "index.json", "enrich.json", "sync.json"],
+  neverPrefixes: ["tls", "catalogs", "relay-cache"],
+  neverSuffixes: [".log", ".pem", ".pid", ".sock"],
+};
+
+/** The account the snapshot lives at. Null when not signed in. */
+export function syncContext(fetcher: typeof fetch = fetch): SyncContext | null {
+  const session = readSession();
+  if (session === null) return null;
+  return {
+    rootDir: stateDir(),
+    policy: SYNC_POLICY,
+    client: createClient({ baseUrl: session.site, path: "/api/v1/settings", token: session.token, fetchImpl: fetcher }),
+    api: session.site,
+    host: hostname(),
+    app: `nixamp ${version()}`,
+  };
+}
+
+const when = (iso?: string): string => (iso ? iso.slice(0, 16).replace("T", " ") : "never");
+
+/** `nixamp sync [status|save|load|revisions] [--force] [--dry-run]`. Returns the exit code. */
+export async function syncCommand(argv: string[], fetcher: typeof fetch = fetch): Promise<number> {
+  const [command = "status", ...rest] = argv;
+  const force = rest.includes("--force");
+  const dryRun = rest.includes("--dry-run");
+  const ctx = syncContext(fetcher);
+  if (ctx === null) {
+    console.error("nixamp: not signed in. Try `nixamp login`; settings sync keeps them on your account.");
+    return 1;
+  }
+
+  try {
+    if (command === "status") {
+      const state = await status(ctx);
+      console.log(`here     ${state.marker ? `revision ${state.marker.revision}, synced ${when(state.marker.at)}` : "never synced"}`);
+      console.log(`account  ${state.serverRevision !== undefined ? `revision ${state.serverRevision}, saved ${when(state.serverSavedAt)}${state.serverHost ? ` from ${state.serverHost}` : ""}` : "nothing yet"}`);
+      if (state.drifted.length) console.log(`changed here: ${state.drifted.join(", ")}  (nixamp sync save)`);
+      if (state.behind) console.log("the account is newer  (nixamp sync load)");
+      if (state.marker && !state.drifted.length && !state.behind) console.log("in sync.");
+      return 0;
+    }
+    if (command === "save") {
+      const result = await save(ctx, { force });
+      for (const skip of result.skipped) console.error(`  skipped ${skip.path}: ${skip.reason}`);
+      if (result.status === "saved") console.log(`saved revision ${result.revision}: ${result.files} file${result.files === 1 ? "" : "s"}`);
+      else if (result.status === "unchanged") console.log(`nothing changed since revision ${result.revision}`);
+      else if (result.status === "empty") console.log("nothing to save: no compression policy or remembered channels here yet");
+      else {
+        console.error(`nixamp: not saved; another machine saved revision ${result.serverRevision} first. \`nixamp sync load\` to take theirs, or \`nixamp sync save --force\`.`);
+        return 1;
+      }
+      return 0;
+    }
+    if (command === "load") {
+      const result = await load(ctx, { force, dryRun });
+      for (const reject of result.rejected) console.error(`  ignored ${reject.path}: ${reject.reason}`);
+      switch (result.status) {
+        case "empty":
+          console.log("nothing on the account yet. `nixamp sync save` on the machine whose settings you want.");
+          return 0;
+        case "same":
+          console.log(`already at revision ${result.revision}`);
+          return 0;
+        case "planned":
+          for (const entry of result.plan) console.log(`  ${entry.status.padEnd(8)} ${entry.path}`);
+          console.log(`would take revision ${result.revision}; nothing written`);
+          return 0;
+        case "newer":
+          console.error("nixamp: the account holds settings saved by a newer nixamp. `nixamp update` first.");
+          return 1;
+        case "local_changes":
+          console.error(`nixamp: not loaded; ${result.drifted.join(", ")} changed here since the last sync. \`nixamp sync save\` to keep yours, \`nixamp sync load --force\` to replace them.`);
+          return 1;
+        case "loaded":
+          console.log(`loaded revision ${result.revision}: ${result.written.join(", ")}`);
+          return 0;
+      }
+    }
+    if (command === "revisions") {
+      const revisions = await ctx.client.revisions();
+      if (!revisions.length) console.log("nothing saved yet");
+      for (const entry of revisions) console.log(`${String(entry.revision).padStart(4)}  ${when(entry.savedAt)}  ${(entry.host ?? "").padEnd(16)}  ${entry.version ?? ""}  ${entry.size} bytes`);
+      return 0;
+    }
+    console.error(`nixamp sync: unknown action ${command}. Try status, save, load or revisions.`);
+    return 64;
+  } catch (error) {
+    console.error(`nixamp: ${(error as Error).message}`);
+    return 1;
+  }
+}

package/web/dist/sw.js

@@ -1,5 +1,5 @@
 /* nixamp service worker — generated, do not edit */
-const CACHE = "nixamp-1789264893886";
+const CACHE = "nixamp-1789266472824";
 const PRECACHE = [
   "/",
   "/.well-known/openaccess.json",