uc-config 0.3.0 → 0.3.2

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.2
+
+Action required: optional, run `npx uc-config init --refresh-docs`. Backups
+made with 0.3.1 are zip files saved as `.tar`; rename them to `.zip`.
+
+- `backup` detects the archive type from its contents. The remote sends no
+  filename and the archive is a zip, so 0.3.1 saved it with a `.tar` extension.
+- `backup` also saves the UC Integration Manager's export beside the archive
+  (`<name>-intg-manager.json`). The native backup doesn't hold the setup of
+  community integrations (Onkyo, Oppo, Kaleidescape, ...); the manager's export
+  does. Default `http://<remote>:9999`; `--intg-manager <url>` sets and
+  remembers another address; `--no-intg-manager` skips it. A missing manager
+  never fails the backup.
+- Docs and AGENTS.md no longer claim the native backup covers all integration
+  settings.
+
+## 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

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { Command } from "commander";
 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 { resolve, join, relative } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { Writable } from "node:stream";
 import { ApiError, CoreClient, resolveSecrets } from "./client.js";
@@ -12,12 +12,12 @@ import { Engine, PendingSetup } from "./engine.js";
 import { formatPlan, makePlan } from "./planner.js";
 import { inventory, importConfig, generateBindings } from "./inventory.js";
 import { emptyState, } from "./model.js";
-import { readJson, saveJson, redact, withLock, isObject } from "./util.js";
+import { readJson, saveJson, redact, withLock, isObject, archiveExtension, } from "./util.js";
 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")
@@ -267,6 +267,10 @@ program
             process.exitCode = 1;
         }
     }
+    const backups = listBackups(root()).filter((b) => !b.file.endsWith("-intg-manager.json"));
+    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")
@@ -602,20 +606,95 @@ 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")
+    .option("--intg-manager <url>", "Integration Manager base URL (remembered); default http://<remote>:9999")
+    .option("--no-intg-manager", "skip the Integration Manager backup")
     .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 = archiveExtension(bytes, filename);
+        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.`);
+        if (o.intgManager === false)
+            return;
+        // Community integrations keep their setup data outside the native backup;
+        // the Integration Manager's export is what holds it.
+        const saved = local("intg-manager.json");
+        if (typeof o.intgManager === "string")
+            await saveJson(saved, { url: new URL(o.intgManager).origin });
+        let base = `${new URL(target.host).protocol}//${new URL(target.host).hostname}:9999`;
+        try {
+            base = (await readJson(saved)).url;
+        }
+        catch {
+            /* default */
+        }
+        const companion = file.replace(/(\.tar\.gz|\.[a-z0-9]+)$/i, "") + "-intg-manager.json";
+        try {
+            const res = await fetch(`${base}/api/v1/backups/export`, {
+                signal: AbortSignal.timeout(60000),
+                redirect: "error",
+            });
+            const body = await res.text();
+            const json = res.ok ? JSON.parse(body) : undefined;
+            if (!isObject(json) || !isObject(json.remotes))
+                throw new Error(`HTTP ${res.status}, not a manager backup`);
+            if (!Object.keys(json.remotes).some((k) => k.replace(/_/g, ":").toUpperCase() ===
+                target.identity.toUpperCase()))
+                console.log("Note: the Integration Manager backup has no entry for this remote.");
+            await writeFile(companion, body, { mode: 0o600, flag: "wx" });
+            console.log(`Integration Manager backup saved to ${relative(root(), companion)} (community integration settings; restore it in the Integration Manager).`);
+        }
+        catch (e) {
+            console.log(`No Integration Manager backup (${base}: ${e.message}). If you use community integrations and the manager runs elsewhere, rerun with --intg-manager http://<host>:9999.`);
+        }
     });
 });
+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|bin)$|-intg-manager\.json$/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

@@ -45,6 +45,8 @@ exists, and skip steps that are done:
    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. If remote.config.ts or
 \`.uc/state\` is lost, the remote still has everything: run sync again.
@@ -73,6 +75,33 @@ The remote is the source of truth; this folder is a working copy of it.
 - 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>.zip\`.
+It covers activities, macros, pages, profiles, icons, IR codes and the
+built-in integrations' settings, and is what you restore after a factory reset.
+
+It does **not** hold the setup of community integrations installed through the
+UC Integration Manager. When the manager is reachable (default
+\`http://<remote>:9999\`; pass \`--intg-manager <url>\` once if it runs
+elsewhere), \`backup\` also saves its export beside the archive as
+\`<name>-intg-manager.json\`. If it reports no manager backup and the user has
+community integrations, tell them those integrations would need setting up
+again after a restore.
+
+- 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 restores the archive
+  in the web configurator, then the manager file in the Integration Manager.
+  Never restore from here.
+
 ## When something is broken
 
 Run \`npx uc-config diagnose\`. It is read-only and prints a \`fix:\` per issue.
@@ -126,6 +155,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/util.d.ts

@@ -15,4 +15,6 @@ export declare function withLock<T>(file: string, fn: () => Promise<T>): Promise
 export declare function resolveRefs<T>(value: T, state: State): T;
 export declare function references(value: unknown): string[];
 export declare function redact(value: unknown): unknown;
+/** Archive type from its magic bytes; the remote may not send a filename. */
+export declare function archiveExtension(bytes: Uint8Array, filename?: string): string;
 export declare function secretFields(v: unknown, path?: string[]): string[];

package/dist/util.js

@@ -129,6 +129,17 @@ export function redact(value) {
         sensitive.test(k) ? "[REDACTED]" : redact(v),
     ]));
 }
+/** Archive type from its magic bytes; the remote may not send a filename. */
+export function archiveExtension(bytes, filename) {
+    if (bytes[0] === 0x50 && bytes[1] === 0x4b)
+        return ".zip";
+    if (bytes[0] === 0x1f && bytes[1] === 0x8b)
+        return ".tar.gz";
+    if (bytes.length > 262 &&
+        String.fromCharCode(...bytes.slice(257, 262)) === "ustar")
+        return ".tar";
+    return /\.(tar\.gz|tgz|tar|zip)$/i.exec(filename ?? "")?.[0] ?? ".bin";
+}
 export function secretFields(v, path = []) {
     if (!isObject(v) && !Array.isArray(v))
         return [];

package/docs/cli.md

@@ -30,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] [--intg-manager u]` | stops intgs       | Native backup + Integration Manager export to `backups/`; keeps old ones.      |
 | `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

@@ -316,18 +316,36 @@ 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>.zip
 ```
 
-`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, profiles, icons, IR codes and the
+built-in integrations' settings. Each run adds a file and keeps the older ones.
+`--out <path>` saves somewhere else.
+
+**Community integrations** (installed through the UC Integration Manager, e.g.
+Onkyo, Oppo, Kaleidescape, Lutron) keep their setup data outside this archive.
+`backup` therefore also downloads the manager's export
+(`/api/v1/backups/export`) and saves it beside the archive as
+`<name>-intg-manager.json`. It tries `http://<remote>:9999` by default; if the
+manager runs elsewhere (Docker, another host), pass
+`--intg-manager http://<host>:9999` once and it is remembered.
+`--no-intg-manager` skips it. If the manager can't be reached, the native
+backup is still saved and the command says so.
+
+- 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 the archive in the web configurator, then the `-intg-manager.json`
+  file in the Integration Manager. uc-config never restores.
 
 ## Nightly health check (for an agent cron job)
 

package/package.json

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