uc-config 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -9,6 +9,22 @@ 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

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,7 +12,7 @@ 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";
@@ -267,7 +267,7 @@ program
             process.exitCode = 1;
         }
     }
-    const backups = listBackups(root());
+    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");
@@ -610,6 +610,8 @@ program
     .option("--target <name>", "target", defaultTarget)
     .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());
@@ -623,7 +625,7 @@ program
         await client.verifyTarget(target);
         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 ext = archiveExtension(bytes, filename);
         const stamp = new Date()
             .toISOString()
             .replace(/:/g, "")
@@ -637,6 +639,39 @@ program
             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 ${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";
@@ -649,7 +684,7 @@ function listBackups(dir) {
     try {
         const d = join(dir, BACKUP_DIR);
         return readdirSync(d)
-            .filter((f) => /\.(tar\.gz|tgz|tar|zip)$/i.test(f))
+            .filter((f) => /\.(tar\.gz|tgz|tar|zip|bin)$|-intg-manager\.json$/i.test(f))
             .sort()
             .map((f) => ({
             file: join(BACKUP_DIR, f),

package/dist/init.js

@@ -78,9 +78,17 @@ The remote is the source of truth; this folder is a working copy of it.
 ## 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.
+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.
@@ -90,8 +98,9 @@ and IR codes, and is what you restore after a factory reset.
   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.
+- 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
 

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] [--list]`                    | stops intgs       | Full native backup to `backups/<timestamp>`; keeps older ones. Ask first.      |
+| `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

@@ -320,13 +320,23 @@ npm run uc -- apply .uc/rollback.json
 
 ```sh
 npx uc-config backup --list   # existing backups (no remote access)
-npx uc-config backup          # new backups/<model>-<timestamp>.tar
+npx uc-config backup          # new backups/<model>-<timestamp>.zip
 ```
 
 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.
+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.
@@ -334,7 +344,8 @@ saves somewhere else.
   `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.
+- 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.1",
+  "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",