uc-config 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -9,6 +9,26 @@ npx uc-config init --refresh-docs
 npx uc-config compile && npx uc-config plan   # must show 0 operations
 ```
 
+## 0.2.4
+
+Action required: none. Existing configs keep their keys.
+
+- `import` builds readable keys from display names (`activity.play_ps5`,
+  `activity.play_ps5.button.mute_short_press`, `entity.living_room_lamp`)
+  instead of `activity8`. Duplicate names get `_2`, `_3`. To rename keys in an
+  existing config, use `state move OLD NEW`.
+
+## 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

package/README.md

@@ -208,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
@@ -235,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/inventory.d.ts

@@ -7,6 +7,8 @@ export interface Inventory {
     unsupported: string[];
 }
 export declare function inventory(client: CoreClient): Promise<Inventory>;
+/** snake_case key segment; falls back to the id when the name has no letters/digits. */
+export declare function slug(name: string | undefined, fallback: string): string;
 export declare function importConfig(client: CoreClient): Promise<{
     config: Config;
     warnings: string[];

package/dist/inventory.js

@@ -58,13 +58,38 @@ export async function inventory(client) {
     }
     return result;
 }
+/** Display name from a string or a localized {en: ...} map. */
+function nameOf(item) {
+    const n = isObject(item) ? item.name : undefined;
+    if (typeof n === "string")
+        return n;
+    if (isObject(n)) {
+        const v = n.en ?? Object.values(n).find((x) => typeof x === "string");
+        if (typeof v === "string")
+            return v;
+    }
+    return undefined;
+}
+/** snake_case key segment; falls back to the id when the name has no letters/digits. */
+export function slug(name, fallback) {
+    const s = (x) => x
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return s(name ?? "") || s(fallback) || "item";
+}
 export async function importConfig(client) {
     const inv = await inventory(client);
     const resources = {};
     const warnings = [...inv.unsupported.map((p) => `Unsupported endpoint ${p}`)];
-    let serial = 0;
-    const add = (r) => {
-        const key = `${r.kind}${++serial}`;
+    // Readable keys from display names ("Play PS5" -> activity.play_ps5);
+    // collisions get _2, _3, ... in import order.
+    const add = (r, base) => {
+        let key = base;
+        for (let n = 2; key in resources; n++)
+            key = `${base}_${n}`;
         resources[key] = r;
         return key;
     };
@@ -93,7 +118,7 @@ export async function importConfig(client) {
                 warnings.push(`${id}: secret-bearing settings require manual secret() references`);
                 continue;
             }
-            const key = add(r);
+            const key = add(r, `${kind}.${slug(nameOf(item), id)}`);
             if (kind === "integration" || kind === "dock")
                 warnings.push(`${key}: existing resource imported; supply create/setup inputs and secret references to reproduce on a new target`);
             if (kind === "remote" && collection !== "externalRemotes")
@@ -112,7 +137,7 @@ export async function importConfig(client) {
                                     parent: { $ref: key },
                                     id: `${b.button}/${press}`,
                                     data: { [press]: b[press] },
-                                });
+                                }, `${key}.button.${slug(String(b.button), "button")}_${press}`);
                     const pages = await client.list(`/${prefix}/${encodeURIComponent(id)}/ui/pages`);
                     for (const p of pages)
                         add({
@@ -120,7 +145,7 @@ export async function importConfig(client) {
                             parent: { $ref: key },
                             id: String(p.page_id),
                             data: writable(`/${prefix}/{entityId}/ui/pages/{pageId}`, "patch", p),
-                        });
+                        }, `${key}.page.${slug(nameOf(p), String(p.page_id))}`);
                 }
                 catch (e) {
                     if (e instanceof ApiError && [404, 405].includes(e.status))
@@ -139,7 +164,7 @@ export async function importConfig(client) {
                             parent: { $ref: key },
                             id: String(c[group ? "group_id" : "page_id"]),
                             data: writable(`/profiles/{profileId}/${child}/{${group ? "groupId" : "pageId"}}`, "patch", c),
-                        });
+                        }, `${key}.${group ? "group" : "page"}.${slug(nameOf(c), String(c[group ? "group_id" : "page_id"]))}`);
                     }
                 }
             if (collection === "irRemotes") {
@@ -158,7 +183,7 @@ export async function importConfig(client) {
                                     format: code.code.format,
                                     value: code.code.value,
                                 },
-                            });
+                            }, `${key}.ir.${slug(code.cmd_id, "code")}`);
             }
         }
     }
@@ -172,7 +197,7 @@ export async function importConfig(client) {
             id: String(item.entity_id),
             parent: item.integration_id,
             data: writable("/entities/{entityId}", "patch", item),
-        });
+        }, `entity.${slug(nameOf(item), String(item.entity_id))}`);
     }
     const usedDrivers = new Set((inv.collections.integrations ?? []).map((i) => i.driver_id));
     for (const item of inv.collections.drivers ?? []) {
@@ -185,7 +210,7 @@ export async function importConfig(client) {
             warnings.push(`${item.driver_id}: driver settings contain secrets; provide secret references manually`);
             continue;
         }
-        add({ kind: "driver", id: String(item.driver_id), data });
+        add({ kind: "driver", id: String(item.driver_id), data }, `driver.${slug(nameOf(item), String(item.driver_id))}`);
     }
     for (const [section, data] of Object.entries(inv.settings)) {
         const picked = writable(`/cfg/${section}`, "patch", data);
@@ -198,7 +223,7 @@ export async function importConfig(client) {
         if (!Object.keys(picked).length)
             continue;
         if (!secretFields(picked).length)
-            add({ kind: "settings", id: section, data: picked });
+            add({ kind: "settings", id: section, data: picked }, `settings.${section}`);
         else
             warnings.push(`${section}: secret-bearing settings omitted; configure secret references`);
     }

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:
@@ -275,8 +276,9 @@ npm run uc -- compile --config .uc/imported-$(date +%F).config.ts --out .uc/impo
 diff <(jq -S . .uc/build.json) <(jq -S . .uc/imported-build.json) | less
 ```
 
-Imported keys are generic (`activity3`). Match resources by `kind` + `id` and
-copy the changed fields into `remote.config.ts`. Then `plan` should report
+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.
 
 ## Undo the last apply

package/package.json

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