uc-config 0.3.0 → 0.3.1

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.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

@@ -17,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")
@@ -267,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")
@@ -602,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

@@ -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,24 @@ 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>.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.
@@ -126,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/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]`                    | 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

@@ -316,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.3.0",
+  "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",