uc-config 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -9,6 +9,30 @@ npx uc-config init --refresh-docs
 npx uc-config compile && npx uc-config plan   # must show 0 operations
 ```
 
+## 0.2.3
+
+Action required: none. Docs only.
+
+- README: what to do when a plan contains operations you didn't make, how to
+  read full sequence changes from `.uc/plan.json`, telling a sleeping remote
+  from a machine without LAN access, and what `deferred` means.
+- Snippets: corrected the entity-swap recipe. Swapped-in commands are deferred
+  until the `entity_ids` change is applied, rather than failing with
+  `Cannot verify command`.
+
+## 0.2.2
+
+Action required: optional. Run `npx uc-config init --refresh-docs` to get the
+new AGENTS.md sections.
+
+- Multiple remotes: documented as one folder per remote. `init` refuses to add
+  a second remote to a folder, and commands that can't pick a target list the
+  targets the folder has.
+- `init` ends by suggesting the prompt "Set up my Remote 3" (the address is
+  already saved).
+- Docs: dock or wake the remote during setup; AGENTS.md says what to do when the
+  remote stops responding.
+
 ## 0.2.1
 
 Action required: run `npx uc-config init --refresh-docs`. It updates the

package/README.md

@@ -24,7 +24,12 @@ hardware. Humans can use it directly too.
 - On the remote, enable the web configurator: **Settings → Profile → Web
   configurator**. Note the **PIN** it shows.
 - Find the remote's **IP address**. It's shown in the remote's network
-  settings, or in your router's device list. The computer you use must be on the same network as the remote.
+  settings, or in your router's device list. The computer you use must be on
+  the same network as the remote.
+- **Dock the remote** (or keep picking it up) during setup. It doesn't need the
+  dock to work, but it goes to sleep when idle and drops off Wi-Fi, which
+  interrupts setup. The Integration Manager's web page is also only available
+  while docked.
 
 ### 2. Create your config folder
 
@@ -51,7 +56,10 @@ repo.
 Start your coding agent (Claude Code, Codex, Cursor, etc.) in that folder and
 prompt:
 
-> Set up my Remote 3 at `<IP>`
+> Set up my Remote 3
+
+`init` already saved the remote's address, so you don't need to repeat it. (If
+you skipped the IP prompt, include it: "Set up my Remote 3 at 192.168.1.50".)
 
 The agent imports your current setup into `remote.config.ts` and records which
 resources it manages. This writes nothing to the remote.
@@ -82,6 +90,24 @@ Ask your agent for changes in plain language, for example:
 The agent shows a plan of what will change before applying it. After you update
 an integration in the Integration Manager, ask the agent to run diagnostics.
 
+## Multiple remotes
+
+Use **one folder per remote**:
+
+```sh
+mkdir -p remotes/living-room && cd remotes/living-room && npx uc-config init
+mkdir -p remotes/bedroom && cd remotes/bedroom && npx uc-config init
+```
+
+Each folder has its own `remote.config.ts`, state and API key, and an agent
+working in one folder can't touch the other remote. The folders can share one
+private git repo. Two remotes rarely have identical configs, because entity IDs
+include each remote's integration IDs; to share a macro or layout, put it in a
+common `.ts` file and import it, using each folder's own `generated/devices.ts`
+for the IDs.
+
+`init` refuses to add a second remote to a folder that already has one.
+
 ## Updating
 
 Ask your agent to "update uc-config", or run in your config folder:
@@ -182,6 +208,19 @@ npm run uc -- check             # must report 0 operations
 remote identity, firmware and preconditions first. A plan with zero operations
 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
+(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.
+
+**The plan output shortens long sequences.** To see the exact step-by-step
+change, compare each operation's `before` with its `desired` in `.uc/plan.json`:
+
+```sh
+jq '.operations[] | {key, action, before, desired}' .uc/plan.json
+```
+
 ## Diagnostics and fixing problems
 
 Run `diagnose` whenever something looks wrong on the remote, after any
@@ -209,14 +248,15 @@ For each orphan it proposes a fix:
 
 Plan/apply problems:
 
-| Message                                         | Meaning and fix                                                                                                                                                                         |
-| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Drift at <fields>`                             | Someone (or a driver update) changed an owned field on the remote. Copy the live value into source, or rerun `plan --overwrite-drift` only if the user wants the source value restored. |
-| `Managed resource disappeared`                  | Resource was deleted on the remote. Run `diagnose`; re-add or remove from source.                                                                                                       |
-| `Cannot verify command`                         | `cmd_id` isn't advertised by that entity, or the entity isn't in the activity's `entity_ids`. Check `generated/devices.ts`, refresh inventory.                                          |
-| `Remote firmware changed; reconnect and replan` | Remote auto-updated. Rerun `connect <name> --host ...` (keeps credentials), then plan.                                                                                                  |
-| `transport failed` / timeouts                   | Remote asleep (wake it) or no LAN access from this machine.                                                                                                                             |
-| Uncertain writes after a crash                  | Run `resume`. Never blindly rerun apply; use `state adopt KEY ID` if a create actually succeeded.                                                                                       |
+| Message                                          | Meaning and fix                                                                                                                                                                                    |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Drift at <fields>`                              | Someone (or a driver update) changed an owned field on the remote. Copy the live value into source, or rerun `plan --overwrite-drift` only if the user wants the source value restored.            |
+| `Managed resource disappeared`                   | Resource was deleted on the remote. Run `diagnose`; re-add or remove from source.                                                                                                                  |
+| `Cannot verify command`                          | `cmd_id` isn't advertised by that entity, or the entity isn't in the activity's `entity_ids`. Check `generated/devices.ts`, refresh inventory.                                                     |
+| `Remote firmware changed; reconnect and replan`  | Remote auto-updated. Rerun `connect <name> --host ...` (keeps credentials), then plan.                                                                                                             |
+| `transport failed` / timeouts                    | Remote asleep, or this machine has no LAN access. Ping the router and another LAN device: if they fail too, it's this machine (on macOS, Local Network privacy), and waking the remote won't help. |
+| `deferred ...: apply prerequisites, then replan` | The item depends on another change in the same plan (e.g. a new entity in `entity_ids`). Apply the plan, then plan again for the deferred items.                                                   |
+| Uncertain writes after a crash                   | Run `resume`. Never blindly rerun apply; use `state adopt KEY ID` if a create actually succeeded.                                                                                                  |
 
 `npm run uc -- api GET <path>` makes a raw authenticated Core API read (output
 redacted). Non-GET methods require `--write` and should only be used for the

package/dist/cli.js

@@ -23,23 +23,27 @@ const program = new Command()
     .description("TypeScript configuration and provisioning for Unfolded Circle Remote 3")
     .version(pkgVersion)
     .option("--workspace <path>", "project directory", process.cwd());
-// UC_TARGET, else the workspace's only target, else "home".
-function implicitTarget() {
-    if (process.env.UC_TARGET)
-        return process.env.UC_TARGET;
-    const ws = process.argv.indexOf("--workspace");
-    const dir = resolve(ws > 0 ? process.argv[ws + 1] : process.cwd());
+function workspaceTargets(dir) {
+    if (!dir) {
+        const ws = process.argv.indexOf("--workspace");
+        dir = resolve(ws > 0 ? process.argv[ws + 1] : process.cwd());
+    }
     try {
-        const names = readdirSync(join(dir, ".uc", "targets"))
+        return readdirSync(join(dir, ".uc", "targets"))
             .filter((f) => f.endsWith(".json"))
-            .map((f) => f.slice(0, -5));
-        if (names.length === 1)
-            return names[0];
+            .map((f) => f.slice(0, -5))
+            .sort();
     }
     catch {
-        // no targets yet
+        return []; // no targets yet
     }
-    return "home";
+}
+// UC_TARGET, else the workspace's only target, else "home".
+function implicitTarget() {
+    if (process.env.UC_TARGET)
+        return process.env.UC_TARGET;
+    const names = workspaceTargets();
+    return names.length === 1 ? names[0] : "home";
 }
 const defaultTarget = implicitTarget();
 const root = () => resolve(program.opts().workspace);
@@ -58,8 +62,12 @@ async function load(name) {
         target = await readJson(targetFile(name));
     }
     catch (e) {
-        if (e.code === "ENOENT")
-            throw new Error(`No target "${name}" in this workspace. Run: uc-config connect ${name} --host http://<REMOTE_IP>`);
+        if (e.code === "ENOENT") {
+            const names = workspaceTargets(root());
+            throw new Error(names.length
+                ? `No target "${name}" in this workspace. It has: ${names.join(", ")}. Pass --target <name> or set UC_TARGET.`
+                : `No target "${name}" in this workspace. Run: uc-config connect ${name} --host http://<REMOTE_IP>`);
+        }
         throw e;
     }
     let token = process.env[target.tokenEnv];
@@ -147,7 +155,7 @@ async function connectTarget(name, host, tokenEnv = "UC_API_KEY") {
     try {
         const old = await readJson(targetFile(name));
         if (old.identity !== target.identity)
-            throw new Error("Target name already refers to another remote; use a new name");
+            throw new Error("This folder is already connected to a different remote. Use one folder per remote (mkdir ../other-remote && cd ../other-remote && npx uc-config init).");
     }
     catch (e) {
         if (e.code !== "ENOENT")
@@ -565,7 +573,7 @@ program
     .command("init")
     .description("Scaffold a private config workspace (package.json, tsconfig, .gitignore, AGENTS.md)")
     .option("--host <ip>", "remote IP address (skips the prompt)")
-    .option("--target <name>", "target name", "home")
+    .option("--target <name>", "target name (default: the folder's existing target, else home)")
     .option("--no-connect", "only create files; don't connect or authenticate")
     .option("--refresh-docs", "update AGENTS.md/CLAUDE.md to this version (edited files get a .new copy)")
     .action(async (o) => {
@@ -586,15 +594,24 @@ program
         return;
     }
     const interactive = Boolean(process.stdin.isTTY);
-    const next = "Next: npm install, then start your coding agent here and ask it to set up your Remote 3.";
+    const next = 'Next: npm install, then start your coding agent here and ask it to "Set up my Remote 3".';
     if (!o.connect)
         return console.log(next);
-    const name = o.target;
+    const existing = workspaceTargets(root());
+    const name = o.target ?? (existing.length === 1 ? existing[0] : "home");
+    if (existing.length && !existing.includes(name)) {
+        console.log(`This folder already manages ${existing.join(", ")}. Use one folder per remote:\n` +
+            "  mkdir ../other-remote && cd ../other-remote && npx uc-config init");
+        process.exitCode = 1;
+        return;
+    }
     // 1. Connect (unless already connected).
     let target;
     try {
         target = await readJson(targetFile(name));
         console.log(`Already connected to ${target.host} as "${name}".`);
+        if (o.host)
+            console.log(`Ignoring --host: this folder already manages "${name}". For another remote, use a new folder.`);
     }
     catch (e) {
         if (e.code !== "ENOENT")

package/dist/init.js

@@ -71,6 +71,19 @@ Re-adding a dropped entity the integration still offers is safe to do
 directly. Ask before anything else. Integration installs and updates belong to
 the UC Integration Manager (http://<remote>:9999); run diagnose after any update.
 
+## Multiple remotes
+
+This folder manages exactly one remote (one target in \`.uc/targets/\`). For
+another remote, create a sibling folder and run \`npx uc-config init\` there.
+Never connect a second remote here, and never copy \`.uc/\` between folders.
+Shared pieces can be imported from a common .ts file, but entity IDs must come
+from each folder's own generated/devices.ts.
+
+## If the remote doesn't respond
+
+\`transport failed\` or timeouts usually mean the remote went to sleep. Ask the
+user to pick it up or dock it, then retry. Don't change the host.
+
 ## Upgrading the tool
 
 1. \`npm install uc-config@latest\` (not \`npm update\`: it won't cross 0.x minor versions).

package/docs/snippets.md

@@ -254,9 +254,10 @@ npm run uc -- compile && npm run uc -- plan --out .uc/plan.json && npm run uc --
 npm run uc -- diagnose
 ```
 
-If the plan reports `Cannot verify command` for the swapped entity, the
-activity's live `included_entities` still lists the old one. Apply the
-`entity_ids` change first, then replan for the buttons and sequences.
+Buttons and sequences that use the new entity show up as **deferred** until the
+activity's `entity_ids` change is on the remote. Apply the plan, then plan and
+apply again for the deferred items. `check` must report 0 operations at the
+end.
 
 **Drift from a driver renaming something** (`Drift at data.name`): copy the
 live value (shown in the plan) into source, then:

package/package.json

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