uc-config 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -9,6 +9,19 @@ npx uc-config init --refresh-docs
 npx uc-config compile && npx uc-config plan   # must show 0 operations
 ```
 
+## 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:

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/package.json

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