uc-config 0.2.5 → 0.3.1

package/CHANGELOG.md

@@ -9,6 +9,38 @@ npx uc-config init --refresh-docs
 npx uc-config compile && npx uc-config plan   # must show 0 operations
 ```
 
+## 0.3.1
+
+Action required: optional, run `npx uc-config init --refresh-docs` to get the
+backup instructions in AGENTS.md.
+
+- `backup` takes no arguments now: it saves the remote's full native backup to
+  `backups/<model>-<timestamp>.tar` (extension from the remote's filename) and
+  never overwrites, so older backups are kept. `--out` still works.
+- `backup --list` lists existing backups without contacting the remote.
+  `doctor` reports how many there are, or suggests making the first one.
+- `backup` writes `backups/.gitignore` so archives (unencrypted, with
+  integration credentials) stay out of git even in existing workspaces. New
+  workspaces also ignore `backups/` in the top-level `.gitignore`.
+- AGENTS.md: agents offer a first backup when none exists, always ask before
+  running one, and never restore.
+
+## 0.3.0
+
+Action required: run `npx uc-config init --refresh-docs`. The agent
+instructions now start every change with `sync`.
+
+- New `sync` command: pulls the live remote into `remote.config.ts`, local
+  state and `generated/devices.ts` in one step, with a three-way merge. Remote
+  edits are pulled, unapplied local edits are kept, edits on both sides are
+  reported as conflicts and left alone. Remote-only resources are added and
+  remote deletions (confirmed by a direct re-read) are removed. Never writes to
+  the remote. `--dry-run` reports without writing.
+- On a folder with no `remote.config.ts`, `sync` does the whole first import:
+  import, bindings and adoption. Setup is now `init`, `sync`, `check`.
+- `sync` only rewrites the plain form that `import` writes. A config using
+  helpers or code is refused with a pointer to the manual steps.
+
 ## 0.2.5
 
 Action required: none.

package/README.md

@@ -162,21 +162,17 @@ npm run uc -- auth
 # 4. Verify connectivity and API coverage
 npm run uc -- doctor
 
-# 5. Snapshot what is on the remote
-npm run uc -- inventory --bindings generated/devices.ts   # entity IDs + commands
-npm run uc -- import --out remote.config.ts               # editable config
-npm run uc -- diagnose                                    # health check
+# 5. Import and take ownership (local only; writes nothing to the remote).
+#    Writes remote.config.ts and generated/devices.ts, and adopts everything.
+npm run uc -- sync
+npm run uc -- diagnose                        # health check
 
-# 6. Take ownership (local only; writes nothing to the remote)
+# 6. Confirm convergence
 npm run uc -- compile
-npm run uc -- plan --out .uc/plan.json        # expect only "= adopt" operations
-npm run uc -- apply .uc/plan.json --adopt-only
-
-# 7. Confirm convergence
 npm run uc -- check                           # 0 operations, 0 conflicts
 ```
 
-After step 7 the workspace is ready. Every later change follows the edit loop below.
+After step 6 the workspace is ready. Every later change follows the edit loop below.
 
 Notes for agents:
 
@@ -194,7 +190,11 @@ Notes for agents:
 
 ## The edit loop
 
+The remote is the source of truth and this folder is a working copy, so pull
+first: `sync` brings in anything changed on the remote since the last run.
+
 ```sh
+npm run uc -- sync              # pull remote edits; keeps your unapplied edits
 # edit remote.config.ts
 npm run check:examples          # typecheck config + examples
 npm run uc -- compile           # evaluate TS -> .uc/build.json (offline)
@@ -210,7 +210,7 @@ needs no apply. See [docs/snippets.md](docs/snippets.md) for common edits.
 
 **If the plan touches things you didn't edit, stop.** Those operations are
 earlier source changes that were never applied, or edits made on the remote
-since. Don't apply them along with your change: sync with the live remote first
+since. Don't apply them along with your change: run `sync` first
 (see [Pull changes made in the web configurator](docs/snippets.md#pull-changes-made-in-the-web-configurator)),
 then replan until only your change is left.
 
@@ -289,12 +289,14 @@ buttons, pages, macros).
 > **Integration updates can drop configured entities**, even when the manager
 > says configuration is preserved. Every activity using them becomes orphaned.
 > Keep the manager's _Auto update_ setting off, and after every integration
-> update run:
+> update run this in your config workspace:
 >
 > ```sh
-> npm run uc -- diagnose && npm run uc -- plan
+> npx uc-config diagnose && npx uc-config plan
 > ```
 >
+> (From a clone of this repo, use `npm run uc -- diagnose && npm run uc -- plan`.)
+>
 > Updates marked as _not preserving configuration_ additionally require
 > re-running that integration's setup.
 
@@ -305,8 +307,9 @@ with `npx uc-config init` (see [Quick start](#quick-start)), in a **private**
 git repo. `init` gitignores `.uc/`, which holds credentials.
 
 Alternatively, use `--workspace <dir>` to point the CLI at any directory holding
-`remote.config.ts` and `.uc/`. Back up `.uc/state` and `.uc/journals`
-privately; losing them makes the next plan an adoption pass.
+`remote.config.ts` and `.uc/`. Nothing here is irreplaceable: the remote holds
+the configuration, and if `.uc/state` or `remote.config.ts` is lost, `sync`
+rebuilds both from it. Git is useful as a history of changes, not as a backup.
 
 ## Reference
 

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { writeFile, mkdir } from "node:fs/promises";
+import { writeFile, mkdir, readFile, rename } from "node:fs/promises";
+import { syncConfig, parseSource, renderSource, formatSync, remoteGone, } from "./sync.js";
 import { resolve, join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { Writable } from "node:stream";
@@ -16,7 +17,7 @@ import { rollbackPlan } from "./recovery.js";
 import { validateRequest } from "./schema.js";
 import { diagnose, formatDiagnosis } from "./diagnose.js";
 import { init } from "./init.js";
-import { readFileSync, readdirSync } from "node:fs";
+import { readFileSync, readdirSync, statSync } from "node:fs";
 const pkgVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const program = new Command()
     .name("uc-config")
@@ -266,6 +267,10 @@ program
             process.exitCode = 1;
         }
     }
+    const backups = listBackups(root());
+    console.log(backups.length
+        ? `Full backups: ${backups.length} (latest ${backups.at(-1).file})`
+        : "No full backup yet. Offer the user one: npx uc-config backup");
 });
 program
     .command("inventory")
@@ -297,6 +302,74 @@ program
     await saveJson(local("import-warnings.json"), warnings);
     console.log(`Wrote ${o.out}; no ownership or remote changes.\n${warnings.map((w) => `- ${w}`).join("\n")}`);
 });
+program
+    .command("sync")
+    .description("Pull the live remote into remote.config.ts and state; keeps unapplied local edits. Never writes to the remote.")
+    .option("--target <name>", "target", defaultTarget)
+    .option("--config <file>", "TypeScript source", "remote.config.ts")
+    .option("--bindings <file>", "device bindings to refresh", "generated/devices.ts")
+    .option("--dry-run", "report what would change without writing files")
+    .action(async (o) => {
+    await withLock(local(`locks/${targetName(o.target)}.lock`), async () => {
+        const { target, client, state, adapter } = await load(o.target);
+        await client.verifyTarget(target);
+        if (state.identity !== target.identity)
+            throw new Error("State belongs to a different remote");
+        try {
+            const journal = await readJson(journalFile(o.target));
+            if (journal.status === "failed" || journal.status === "running")
+                throw new Error("Previous apply is unresolved; run resume before syncing");
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+        }
+        const file = resolve(root(), o.config);
+        let text;
+        try {
+            text = await readFile(file, "utf8");
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+        }
+        // First run: no config yet. Import and adopt everything as it is.
+        if (text === undefined && Object.keys(state.bindings).length)
+            throw new Error(`${o.config} is missing but local state still manages ${Object.keys(state.bindings).length} resources. Restore the file (e.g. from git) rather than re-importing.`);
+        const source = text === undefined
+            ? { schemaVersion: 1, resources: {} }
+            : parseSource(text);
+        if (!source)
+            throw new Error(`${o.config} isn't in the plain form import writes (it uses helpers or code), so sync can't rewrite it without losing that. Use the manual steps in docs/snippets.md ("Pull changes made in the web configurator").`);
+        validateConfig(source);
+        const inv = await inventory(client);
+        const { config: live } = await importConfig(client);
+        const result = await syncConfig(source, state, live, remoteGone(adapter, state));
+        validateConfig(result.config);
+        const firstRun = text === undefined;
+        console.log(firstRun
+            ? `Imported and adopted ${result.changes.length} resources from the remote.`
+            : formatSync(result.changes));
+        const conflicts = result.changes.some((c) => c.action === "conflict");
+        if (conflicts)
+            process.exitCode = 2;
+        if (o.dryRun)
+            return console.log("Dry run: no files written.");
+        const touched = result.changes.some((c) => ["pull", "add", "remove", "applied"].includes(c.action));
+        if (touched) {
+            const tmp = `${file}.sync.tmp`;
+            await writeFile(tmp, renderSource(result.config), { mode: 0o600 });
+            await saveJson(stateFile(o.target), result.state);
+            await rename(tmp, file);
+        }
+        const bindings = resolve(root(), o.bindings);
+        await mkdir(resolve(bindings, ".."), { recursive: true });
+        await writeFile(bindings, generateBindings(inv));
+        console.log(touched
+            ? `Updated ${o.config}, ${o.bindings} and local state. No remote changes. Next: compile, then plan should show only your own edits.`
+            : `${o.config} already matches the remote. Refreshed ${o.bindings}.`);
+    });
+});
 program
     .command("compile")
     .description("Compile TypeScript configuration into a local JSON snapshot")
@@ -533,20 +606,60 @@ program
 });
 program
     .command("backup")
+    .description("Full native backup of the remote into backups/ (timestamped; never overwrites). Briefly stops integrations and docks.")
     .option("--target <name>", "target", defaultTarget)
-    .requiredOption("--out <file>", "native backup archive")
+    .option("--out <file>", "archive path (default: backups/<timestamp>)")
+    .option("--list", "list existing backups; no remote access")
     .action(async (o) => {
+    if (o.list) {
+        const list = listBackups(root());
+        console.log(list.length
+            ? list.map((b) => `${b.file}  ${b.size}`).join("\n")
+            : "No full backups in backups/. Run: npx uc-config backup");
+        return;
+    }
     await withLock(local(`locks/${targetName(o.target)}.lock`), async () => {
         const { client, target } = await load(o.target);
         await client.verifyTarget(target);
-        console.log("Exporting native backup: the remote temporarily stops integrations and docks. Keep the archive private; it may contain credentials.");
-        const bytes = await client.download("/system/backup/export");
-        const file = resolve(root(), o.out);
-        await mkdir(resolve(file, ".."), { recursive: true });
+        console.log("Exporting full backup: the remote stops integrations and docks for a few seconds, then restarts them.");
+        const { bytes, filename } = await client.downloadFile("/system/backup/export");
+        const ext = /\.(tar\.gz|tgz|tar|zip)$/i.exec(filename ?? "")?.[0] ?? ".tar";
+        const stamp = new Date()
+            .toISOString()
+            .replace(/:/g, "")
+            .replace(/\..+/, "");
+        const out = o.out ??
+            join(BACKUP_DIR, `${target.version.model.toLowerCase()}-${stamp}${ext}`);
+        const file = resolve(root(), out);
+        await mkdir(resolve(file, ".."), { recursive: true, mode: 0o700 });
+        // The archive holds integration credentials: keep backups/ out of git.
+        if (resolve(file, "..") === resolve(root(), BACKUP_DIR))
+            await writeFile(resolve(root(), BACKUP_DIR, ".gitignore"), "# Full remote backups contain credentials. Never commit them.\n*\n");
         await writeFile(file, bytes, { mode: 0o600, flag: "wx" });
-        console.log(`Backup saved to ${o.out}`);
+        console.log(`Backup saved to ${out} (${formatSize(bytes.length)}). It is unencrypted and contains integration credentials: keep it private. Restore it from the web configurator.`);
     });
 });
+const BACKUP_DIR = "backups";
+function formatSize(n) {
+    return n > 1048576
+        ? `${(n / 1048576).toFixed(1)} MB`
+        : `${Math.ceil(n / 1024)} KB`;
+}
+function listBackups(dir) {
+    try {
+        const d = join(dir, BACKUP_DIR);
+        return readdirSync(d)
+            .filter((f) => /\.(tar\.gz|tgz|tar|zip)$/i.test(f))
+            .sort()
+            .map((f) => ({
+            file: join(BACKUP_DIR, f),
+            size: formatSize(statSync(join(d, f)).size),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
 const ir = program.command("ir");
 ir.command("learn <emitterId>")
     .option("--target <name>", "target", defaultTarget)

package/dist/client.d.ts

@@ -19,6 +19,11 @@ export declare class CoreClient {
     maybe(path: string): Promise<ObjectValue | null>;
     list(path: string): Promise<ObjectValue[]>;
     download(path: string): Promise<Uint8Array>;
+    /** Bytes plus the server-suggested filename (Content-Disposition), if any. */
+    downloadFile(path: string): Promise<{
+        bytes: Uint8Array;
+        filename?: string;
+    }>;
     version(): Promise<Version>;
     verifyTarget(target: Target): Promise<void>;
 }

package/dist/client.js

@@ -122,6 +122,10 @@ export class CoreClient {
         throw new Error(`${path}: pagination limit exceeded`);
     }
     async download(path) {
+        return (await this.downloadFile(path)).bytes;
+    }
+    /** Bytes plus the server-suggested filename (Content-Disposition), if any. */
+    async downloadFile(path) {
         if (!path.startsWith("/") || path.startsWith("//") || path.includes(".."))
             throw new Error("Invalid API path");
         const response = await this.transport(new URL(path.slice(1), this.base), {
@@ -131,7 +135,12 @@ export class CoreClient {
         });
         if (!response.ok)
             throw new ApiError(response.status, "GET", path);
-        return new Uint8Array(await response.arrayBuffer());
+        const disposition = response.headers.get("content-disposition") ?? "";
+        const m = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(disposition);
+        return {
+            bytes: new Uint8Array(await response.arrayBuffer()),
+            ...(m ? { filename: decodeURIComponent(m[1]) } : {}),
+        };
     }
     async version() {
         return this.get("/pub/version");

package/dist/init.js

@@ -40,19 +40,30 @@ exists, and skip steps that are done:
    enabled on the remote). Never ask for the PIN in chat, and never run \`auth\`
    yourself; it needs a real terminal.
 3. \`npx uc-config doctor\`
-4. \`npx uc-config inventory --bindings generated/devices.ts\`
-5. \`npx uc-config import --out remote.config.ts\`
-6. \`npx uc-config compile && npx uc-config plan --out .uc/plan.json\`. Expect only \`= adopt\` operations.
-7. \`npx uc-config apply .uc/plan.json --adopt-only && npx uc-config check\`
-8. \`git init && git add -A && git commit -m "Import Remote 3 config"\`
+4. \`npx uc-config sync\`. With no remote.config.ts yet, it imports the remote,
+   writes remote.config.ts and generated/devices.ts, and adopts everything. It
+   never writes to the remote.
+5. \`npx uc-config compile && npx uc-config check\` (must be 0 operations).
+6. \`git init && git add -A && git commit -m "Import Remote 3 config"\`
+7. If \`npx uc-config backup --list\` shows no backups, offer the user a full
+   backup (see "Full backup" below). Ask first; don't run it unprompted.
 
-If \`.uc/\` already exists, reuse it. Don't re-auth, re-import or re-adopt.
+If \`.uc/\` already exists, reuse it. Don't re-auth. If remote.config.ts or
+\`.uc/state\` is lost, the remote still has everything: run sync again.
 
 ## Every change
 
-Edit remote.config.ts, then: \`npx tsc --noEmit\`, \`npx uc-config compile\`,
-\`npx uc-config plan --out .uc/plan.json\`, review, \`npx uc-config apply .uc/plan.json\`,
-\`npx uc-config check\` (must be 0 operations).
+The remote is the source of truth; this folder is a working copy of it.
+
+1. \`npx uc-config sync\` first. It pulls edits made on the remote (web
+   configurator, driver updates) into remote.config.ts and refreshes
+   generated/devices.ts, keeping any unapplied local edits. If it reports a
+   conflict (\`!\`), stop and ask the user which value to keep.
+2. Edit remote.config.ts.
+3. \`npx tsc --noEmit\`, \`npx uc-config compile\`,
+   \`npx uc-config plan --out .uc/plan.json\`, review,
+   \`npx uc-config apply .uc/plan.json\`, \`npx uc-config check\` (must be 0 operations).
+4. Commit, so git keeps a history of what changed.
 
 - Use only entity IDs and cmd_ids from generated/devices.ts or a fresh inventory.
   Never invent command names.
@@ -64,6 +75,24 @@ Edit remote.config.ts, then: \`npx tsc --noEmit\`, \`npx uc-config compile\`,
 - Never use --overwrite-drift or --prune without the user's say-so.
 - Never put secrets in remote.config.ts or print .uc/credentials.json.
 
+## Full backup
+
+\`npx uc-config backup\` saves the remote's own full backup (the same archive
+as the web configurator's backup page) to \`backups/<model>-<timestamp>.tar\`.
+It covers activities, macros, pages, integrations and their settings, icons
+and IR codes, and is what you restore after a factory reset.
+
+- Whenever you work in this folder and \`backup --list\` (or \`doctor\`) shows
+  no backup, ask the user once whether they'd like one now.
+- Always ask before running it, and tell the user first: integrations and docks
+  stop for a few seconds and the remote shouldn't be used meanwhile.
+- Each run adds a new file; older backups are kept. \`backup --list\` lists them.
+  Only delete old ones when the user asks.
+- Archives are unencrypted and contain integration credentials. backups/ is
+  gitignored: never commit, upload or print them.
+- Restoring replaces the remote's configuration: the user does that in the web
+  configurator. Never restore from here.
+
 ## When something is broken
 
 Run \`npx uc-config diagnose\`. It is read-only and prints a \`fix:\` per issue.
@@ -117,6 +146,8 @@ const tsconfig = {
 const gitignore = `node_modules/
 # Credentials, state and journals. Back up .uc/state and .uc/journals privately.
 .uc/
+# Full remote backups: unencrypted, contain integration credentials.
+backups/
 .env
 .env.*
 `;

package/dist/sync.d.ts

@@ -0,0 +1,44 @@
+import type { Adapter } from "./adapter.js";
+import type { Config, ObjectValue, State } from "./model.js";
+/**
+ * What sync did (or would do) to one resource.
+ *
+ * - pull: changed on the remote, unchanged locally; source and baseline now match live.
+ * - add: exists only on the remote; added to source and adopted.
+ * - remove: deleted on the remote; removed from source and ownership dropped.
+ * - local: unapplied local edit, remote unchanged; kept for the next plan.
+ * - applied: the local edit is already live; baseline updated.
+ * - conflict: changed both locally and on the remote; nothing touched.
+ */
+export interface SyncChange {
+    key: string;
+    action: "pull" | "add" | "remove" | "local" | "applied" | "conflict";
+    fields?: string[];
+    note?: string;
+}
+export interface SyncResult {
+    config: Config;
+    state: State;
+    changes: SyncChange[];
+}
+export declare function changedFields(a: ObjectValue, b: ObjectValue): string[];
+/**
+ * Three-way merge of the live remote into local source and state.
+ *
+ * `live` is a fresh `import` of the remote. Source resources are matched to live
+ * ones by (kind, parent's native id, native id), never by logical key, so
+ * hand-chosen keys survive. `confirmGone` re-reads a resource the import did not
+ * return, so an endpoint the import skipped is never mistaken for a deletion.
+ * Pure apart from `confirmGone`; never writes to the remote.
+ */
+export declare function syncConfig(source: Config, state: State, live: Config, confirmGone: (key: string) => Promise<boolean>): Promise<SyncResult>;
+/** confirmGone for syncConfig: true only when a direct read proves absence. */
+export declare const remoteGone: (adapter: Adapter, state: State) => (key: string) => Promise<boolean>;
+/** Source text in the form `import` writes: plain JSON inside defineRemote(). */
+export declare function renderSource(config: Config): string;
+/**
+ * The config from an imported-form remote.config.ts, or null when the file uses
+ * code (helpers, variables, imports) that sync can't rewrite without losing it.
+ */
+export declare function parseSource(text: string): Config | null;
+export declare function formatSync(changes: SyncChange[]): string;

package/dist/sync.js

@@ -0,0 +1,241 @@
+import { configurationView } from "./planner.js";
+import { equal, get, isObject, leaves, merge, references } from "./util.js";
+/** Kinds that `import` reproduces, so their absence from an import means something. */
+const IMPORTED = new Set([
+    "activity",
+    "macro",
+    "profile",
+    "profilePage",
+    "profileGroup",
+    "activityGroup",
+    "activityPage",
+    "remotePage",
+    "activityButton",
+    "remoteButton",
+    "integration",
+    "dock",
+    "remote",
+    "irCode",
+    "entity",
+    "driver",
+    "settings",
+]);
+export function changedFields(a, b) {
+    const paths = new Map();
+    for (const [p] of [...leaves(a), ...leaves(b)])
+        paths.set(p.join("."), p);
+    return [...paths]
+        .filter(([, p]) => !equal(get(a, p), get(b, p)))
+        .map(([name]) => name)
+        .sort();
+}
+const identity = (kind, parent, id) => JSON.stringify([kind, parent ?? "", id]);
+/**
+ * Three-way merge of the live remote into local source and state.
+ *
+ * `live` is a fresh `import` of the remote. Source resources are matched to live
+ * ones by (kind, parent's native id, native id), never by logical key, so
+ * hand-chosen keys survive. `confirmGone` re-reads a resource the import did not
+ * return, so an endpoint the import skipped is never mistaken for a deletion.
+ * Pure apart from `confirmGone`; never writes to the remote.
+ */
+export async function syncConfig(source, state, live, confirmGone) {
+    const config = structuredClone(source);
+    const next = structuredClone(state);
+    const changes = [];
+    const sourceParent = (p) => {
+        if (typeof p === "string")
+            return p;
+        if (isObject(p) && typeof p.$ref === "string")
+            return next.bindings[p.$ref]?.id ?? config.resources[p.$ref]?.id;
+        return undefined;
+    };
+    const sourceIndex = new Map();
+    for (const [key, r] of Object.entries(config.resources)) {
+        const id = next.bindings[key]?.id ?? r.id;
+        if (id)
+            sourceIndex.set(identity(r.kind, sourceParent(r.parent), id), key);
+    }
+    const liveParent = (p) => {
+        if (typeof p === "string")
+            return p;
+        if (isObject(p) && typeof p.$ref === "string")
+            return live.resources[p.$ref]?.id;
+        return undefined;
+    };
+    const liveToSource = new Map();
+    const seen = new Set();
+    for (const [liveKey, lr] of Object.entries(live.resources)) {
+        if (!lr.id)
+            continue;
+        const ident = identity(lr.kind, liveParent(lr.parent), lr.id);
+        seen.add(ident);
+        const key = sourceIndex.get(ident);
+        if (key) {
+            liveToSource.set(liveKey, key);
+            const s = config.resources[key];
+            const binding = next.bindings[key];
+            if (!binding)
+                continue; // in source but never adopted: plan adopts it
+            const S = s.data;
+            const B = binding.baseline;
+            const liveOwned = configurationView(lr.data, B, B);
+            const sourceChanged = !equal(S, B);
+            const liveChanged = !equal(liveOwned, B);
+            if (!liveChanged) {
+                if (sourceChanged)
+                    changes.push({ key, action: "local", fields: changedFields(B, S) });
+                continue;
+            }
+            if (!sourceChanged) {
+                changes.push({
+                    key,
+                    action: "pull",
+                    fields: changedFields(B, liveOwned),
+                });
+                s.data = liveOwned;
+                binding.baseline = structuredClone(liveOwned);
+                binding.resource = structuredClone(s);
+                continue;
+            }
+            const liveWanted = configurationView(lr.data, merge(B, S), B);
+            if (equal(liveWanted, S)) {
+                changes.push({ key, action: "applied", fields: changedFields(B, S) });
+                binding.baseline = structuredClone(S);
+                binding.resource = structuredClone(s);
+                continue;
+            }
+            changes.push({
+                key,
+                action: "conflict",
+                fields: [
+                    ...new Set([...changedFields(B, S), ...changedFields(B, liveOwned)]),
+                ].sort(),
+                note: "changed locally and on the remote; resolve by hand",
+            });
+            continue;
+        }
+        // Only on the remote: add under the import's readable key, adopted as-is.
+        let parent = lr.parent;
+        if (isObject(lr.parent) && typeof lr.parent.$ref === "string") {
+            const mapped = liveToSource.get(lr.parent.$ref);
+            if (!mapped)
+                continue; // parent is in conflict or unmatched; skip child
+            parent = { $ref: mapped };
+        }
+        let newKey = liveKey;
+        for (let n = 2; newKey in config.resources; n++)
+            newKey = `${liveKey}_${n}`;
+        const r = {
+            ...structuredClone(lr),
+            ...(parent ? { parent } : {}),
+        };
+        config.resources[newKey] = r;
+        next.bindings[newKey] = {
+            id: lr.id,
+            resource: structuredClone(r),
+            baseline: structuredClone(lr.data),
+        };
+        liveToSource.set(liveKey, newKey);
+        sourceIndex.set(ident, newKey);
+        changes.push({ key: newKey, action: "add" });
+    }
+    // Owned resources the import no longer returns.
+    const removed = new Set();
+    for (const [key, r] of Object.entries(config.resources)) {
+        const binding = next.bindings[key];
+        if (!binding || !IMPORTED.has(r.kind))
+            continue;
+        if (seen.has(identity(r.kind, sourceParent(r.parent), binding.id)))
+            continue;
+        if (!(await confirmGone(key)))
+            continue;
+        if (!equal(r.data, binding.baseline)) {
+            changes.push({
+                key,
+                action: "conflict",
+                note: "deleted on the remote but has unapplied local edits",
+            });
+            continue;
+        }
+        removed.add(key);
+    }
+    // Children of a removed resource go with it.
+    for (let grew = true; grew;) {
+        grew = false;
+        for (const [key, r] of Object.entries(config.resources))
+            if (!removed.has(key) &&
+                [...references(r), ...(r.dependsOn ?? [])].some((d) => removed.has(d))) {
+                removed.add(key);
+                grew = true;
+            }
+    }
+    for (const key of removed) {
+        delete config.resources[key];
+        delete next.bindings[key];
+        changes.push({ key, action: "remove" });
+    }
+    if (!equal(next.bindings, state.bindings))
+        next.revision = state.revision + 1;
+    return { config, state: next, changes };
+}
+/** confirmGone for syncConfig: true only when a direct read proves absence. */
+export const remoteGone = (adapter, state) => async (key) => {
+    const b = state.bindings[key];
+    if (!b)
+        return false;
+    try {
+        const obs = await adapter.observe({ ...b.resource, id: b.id }, state, key);
+        return (obs.value === null ||
+            (b.resource.kind.endsWith("Button") &&
+                Object.keys(obs.value).length === 0));
+    }
+    catch {
+        return false; // can't prove it's gone; leave it alone
+    }
+};
+const HEADER = "import { defineRemote } from 'uc-config';\n\n";
+/** Source text in the form `import` writes: plain JSON inside defineRemote(). */
+export function renderSource(config) {
+    return `${HEADER}export default defineRemote(${JSON.stringify(config, null, 2)});\n`;
+}
+/**
+ * The config from an imported-form remote.config.ts, or null when the file uses
+ * code (helpers, variables, imports) that sync can't rewrite without losing it.
+ */
+export function parseSource(text) {
+    const m = /^\s*import\s*\{\s*defineRemote\s*\}\s*from\s*['"]uc-config['"];?\s*export\s+default\s+defineRemote\(([\s\S]*)\);?\s*$/.exec(text);
+    if (!m)
+        return null;
+    try {
+        const value = JSON.parse(m[1]);
+        return isObject(value) && isObject(value.resources)
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function formatSync(changes) {
+    const sign = {
+        pull: "<",
+        add: "+",
+        remove: "-",
+        local: "~",
+        applied: "=",
+        conflict: "!",
+    };
+    const words = {
+        pull: "pulled from remote",
+        add: "added from remote",
+        remove: "deleted on remote",
+        local: "unapplied local edit kept",
+        applied: "local edit already live",
+        conflict: "conflict",
+    };
+    const lines = changes.map((c) => `${sign[c.action]} ${c.key}: ${words[c.action]}${c.fields?.length ? ` (${c.fields.join(", ")})` : ""}${c.note ? `; ${c.note}` : ""}`);
+    const count = (a) => changes.filter((c) => c.action === a).length;
+    lines.push(`${count("pull")} pulled, ${count("add")} added, ${count("remove")} removed, ${count("local")} local edits kept, ${count("conflict")} conflicts`);
+    return lines.join("\n");
+}

package/docs/cli.md

@@ -19,6 +19,7 @@ the workspace's only target if exactly one is connected; otherwise `home`.
 | `diagnose [--json]`                            | no                | Orphaned entity references, disconnected integrations, suggested fixes.        |
 | `inventory [--out f] [--bindings f.ts]`        | no                | Raw (redacted) remote state; optional typed entity/command bindings.           |
 | `import [--out f.ts]`                          | no                | Generate editable config from the live remote. Never overwrites.               |
+| `sync [--dry-run]`                             | no                | Pull the live remote into source, state and bindings; keeps local edits.       |
 | `compile [--config f] [--out f]`               | no                | Evaluate TS config into `.uc/build.json`. Offline.                             |
 | `plan [--out f] [--prune] [--overwrite-drift]` | no                | Three-way diff: source vs last-applied vs live.                                |
 | `apply <plan> [--adopt-only]`                  | yes               | Execute a saved plan after re-verifying preconditions.                         |
@@ -29,7 +30,7 @@ the workspace's only target if exactly one is connected; otherwise `home`.
 | `ir learn/capture <emitterId>`                 | yes               | Learn IR codes from a physical remote.                                         |
 | `state adopt <key> <id>` / `forget` / `move`   | no                | Edit local ownership bindings.                                                 |
 | `rollback [--out f]`                           | no                | Build a compensating plan from the last journal.                               |
-| `backup --out f`                               | stops intgs       | Native full backup. Disruptive; not for routine use.                           |
+| `backup [--out f] [--list]`                    | stops intgs       | Full native backup to `backups/<timestamp>`; keeps older ones. Ask first.      |
 | `api <METHOD> <path> [--data json] [--write]`  | only with --write | Raw authenticated Core API call; output redacted.                              |
 
 Exit codes: `0` ok, `1` error, `2` drift/conflicts/deferred/diagnose findings,

package/docs/snippets.md

@@ -277,15 +277,36 @@ npm run uc -- apply .uc/plan.json --adopt-only
 ## Pull changes made in the web configurator
 
 ```sh
-npm run uc -- import --out .uc/imported-$(date +%F).config.ts
-npm run uc -- compile --config .uc/imported-$(date +%F).config.ts --out .uc/imported-build.json
+npx uc-config sync --dry-run   # what would change; writes nothing
+npx uc-config sync             # update remote.config.ts, generated/devices.ts and state
+```
+
+`sync` never writes to the remote. Per resource it prints:
+
+| Mark | Meaning                                        | What sync does                                 |
+| ---- | ---------------------------------------------- | ---------------------------------------------- |
+| `<`  | changed on the remote only                     | copies the live value into source and state    |
+| `+`  | exists only on the remote                      | adds it to source and adopts it                |
+| `-`  | deleted on the remote (confirmed by a re-read) | removes it (and its pages/buttons) from source |
+| `~`  | unapplied local edit, remote unchanged         | keeps it; the next plan applies it             |
+| `=`  | local edit already live                        | updates state                                  |
+| `!`  | changed both locally and on the remote         | touches nothing; exit 2. Pick a value by hand  |
+
+Resources are matched by kind and native id, so keys you renamed are kept. Run
+it before every change; afterwards `plan` contains only your own edits.
+
+`sync` rewrites `remote.config.ts`, so it only runs on the plain form that
+`import`/`sync` write. If you converted the file to helpers or added code, sync
+refuses. Then pull by hand:
+
+```sh
+npx uc-config import --out .uc/imported-$(date +%F).config.ts
+npx uc-config compile --config .uc/imported-$(date +%F).config.ts --out .uc/imported-build.json
 diff <(jq -S . .uc/build.json) <(jq -S . .uc/imported-build.json) | less
 ```
 
-Imported keys come from display names (`activity.watch_tv`), so they usually
-match yours, but a renamed activity gets a different key. Match resources by
-`kind` + `id` and copy the changed fields into `remote.config.ts`. Then `plan` should report
-0 operations.
+Match resources by `kind` + `id`, copy the changed fields into
+`remote.config.ts`, and `plan` should report 0 operations.
 
 ## Undo the last apply
 
@@ -295,18 +316,25 @@ npm run uc -- rollback --out .uc/rollback.json   # builds a compensating plan
 npm run uc -- apply .uc/rollback.json
 ```
 
-## Back up everything (scheduled job friendly)
+## Full remote backup
 
 ```sh
-D=backups/$(date +%F); mkdir -p "$D"
-npm run -s uc -- inventory --out "$D/inventory.json"           # redacted raw state
-npm run -s uc -- import --out "$D/remote.config.ts"            # readable snapshot
-tar czf "$D/dotuc.tgz" --exclude credentials.json .uc          # ownership state
-curl -sf http://<REMOTE_IP>:9999/api/backups/download -o "$D/intg-manager.json"  # Integration Manager
+npx uc-config backup --list   # existing backups (no remote access)
+npx uc-config backup          # new backups/<model>-<timestamp>.tar
 ```
 
-`npm run uc -- backup --out PRIVATE_PATH` produces the remote's native full
-backup, but it **temporarily stops integrations and docks**, so don't schedule it.
+This is the remote's own full backup, the same archive the web configurator
+downloads: activities, macros, pages, integrations and their settings, icons
+and IR codes. Each run adds a file and keeps the older ones. `--out <path>`
+saves somewhere else.
+
+- It **stops integrations and docks for a few seconds**. Ask the user first,
+  and don't schedule it.
+- The archive is unencrypted and contains integration credentials.
+  `backups/` is gitignored (and gets its own `.gitignore`); keep it private.
+- It does not include Wi-Fi settings, the admin or web-configurator PIN, or
+  API keys, so `npx uc-config auth` is needed again after a restore.
+- Restore it in the web configurator. uc-config never restores.
 
 ## Nightly health check (for an agent cron job)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uc-config",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "type": "module",
   "description": "Configuration-as-code for the Unfolded Circle Remote 3, designed to be driven by coding agents",
   "license": "MIT",