uc-config 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+Each release says whether upgrading needs any **action**. To upgrade a config
+workspace:
+
+```sh
+npm install uc-config@latest
+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
+scaffolded AGENTS.md, whose upgrade instructions were wrong.
+
+- `init --refresh-docs` updates AGENTS.md and CLAUDE.md to the installed
+  version. Files you edited are kept, and the new version is written beside
+  them as `.new`.
+- `doctor` prints a notice when a newer version is published. Set
+  `UC_NO_UPDATE_CHECK=1` to disable it.
+- The scaffolded upgrade instructions use `npm install uc-config@latest`.
+  `npm update` doesn't move between 0.x minor versions.
+
+## 0.2.0
+
+Action required: none.
+
+- `init` asks for the remote's IP and the web configurator PIN, then connects
+  and authenticates. It can be rerun safely.
+- `init` writes CLAUDE.md, which points Claude Code at AGENTS.md.
+
+## 0.1.0
+
+First release.

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,41 @@ 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:
+
+```sh
+npm install uc-config@latest
+npx uc-config init --refresh-docs     # refresh AGENTS.md / CLAUDE.md
+npx uc-config compile && npx uc-config plan    # must show 0 operations
+```
+
+Use `npm install uc-config@latest` rather than `npm update`: before 1.0,
+`npm update` doesn't move between minor versions (0.2 → 0.3). `--refresh-docs`
+keeps files you've edited and writes the new version beside them as `.new`.
+`doctor` tells you when a newer version is available. See
+[CHANGELOG.md](CHANGELOG.md) for what changed and whether a release needs any
+action.
+
 ## Requirements
 
 - Node.js 22+ and npm

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")
@@ -194,6 +202,31 @@ async function authenticate(name, pin) {
         console.log("API key saved in .uc/credentials.json (mode 0600, gitignored). Approve it on the remote if requested, then run doctor.");
     }
 }
+/** Latest published version, or undefined if offline/disabled. Never throws. */
+async function latestVersion() {
+    if (process.env.UC_NO_UPDATE_CHECK)
+        return undefined;
+    try {
+        const res = await fetch("https://registry.npmjs.org/uc-config/latest", {
+            signal: AbortSignal.timeout(3000),
+        });
+        if (!res.ok)
+            return undefined;
+        const v = (await res.json()).version;
+        return typeof v === "string" ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function newer(a, b) {
+    const p = (v) => v.split("-")[0].split(".").map(Number);
+    const [x, y] = [p(a), p(b)];
+    for (let i = 0; i < 3; i++)
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) > (y[i] ?? 0);
+    return false;
+}
 async function question(label) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
@@ -210,6 +243,9 @@ program
     const { client, target } = await load(o.target);
     await client.verifyTarget(target);
     console.log(`Identity verified; core ${target.version.core}, reported API ${target.version.api}`);
+    const latest = await latestVersion();
+    if (latest && newer(latest, pkgVersion))
+        console.log(`Update available: uc-config ${pkgVersion} -> ${latest}. Run: npm install uc-config@latest && npx uc-config init --refresh-docs (see CHANGELOG.md)`);
     for (const path of [
         "/entities",
         "/activities",
@@ -537,26 +573,45 @@ 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) => {
-    const r = await init(root(), pkgVersion);
+    const r = await init(root(), pkgVersion, { refreshDocs: o.refreshDocs });
     for (const f of r.written)
         console.log(`created ${f}`);
     if (r.packageJsonUpdated)
         console.log("added uc-config to package.json");
+    for (const f of r.refreshed)
+        console.log(`updated ${f} to v${pkgVersion}`);
+    for (const f of r.conflicts)
+        console.log(`kept ${f} (edited); wrote ${f}.new. Merge your changes, then delete ${f}.new`);
     for (const f of r.skipped)
         console.log(`kept existing ${f}`);
+    if (o.refreshDocs) {
+        if (r.conflicts.length)
+            process.exitCode = 2;
+        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.d.ts

@@ -1,7 +1,15 @@
+/** True when the file is unedited generated output from any uc-config version. */
+export declare function isPristine(content: string): boolean;
 export interface InitResult {
     written: string[];
     skipped: string[];
     packageJsonUpdated: boolean;
+    /** Generated docs replaced by --refresh-docs. */
+    refreshed: string[];
+    /** Edited docs kept; the new version was written to `<name>.new`. */
+    conflicts: string[];
 }
 /** Scaffold a private config workspace. Never overwrites existing files. */
-export declare function init(dir: string, version: string): Promise<InitResult>;
+export declare function init(dir: string, version: string, options?: {
+    refreshDocs?: boolean;
+}): Promise<InitResult>;

package/dist/init.js

@@ -1,5 +1,23 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { createHash } from "node:crypto";
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
+const MARKER = /^<!-- uc-config:generated v(\S+) sha256:([0-9a-f]{64}) -->\n/;
+/** Prefix generated docs with a marker so --refresh-docs can detect edits. */
+const stamp = (version, body) => `<!-- uc-config:generated v${version} sha256:${sha256(body)} -->\n${body}`;
+/** Exact output of releases that predate the marker (0.1.0, 0.2.0). */
+const LEGACY = new Set([
+    "053dd83c530adb91f58ad52148c9d858cc28864a137b7b5e65c4563338e91b4f",
+    "159e847a6a5b6c5cb9ed96f400e8f5d58cd9acae2e68bf666fc3fae2e4ad249b",
+    "d71e02c349b769c916d166a6b26cc14d80da4142042fa90564bda85c897a9b07",
+]);
+/** True when the file is unedited generated output from any uc-config version. */
+export function isPristine(content) {
+    const m = MARKER.exec(content);
+    if (m)
+        return sha256(content.slice(m[0].length)) === m[2];
+    return LEGACY.has(sha256(content));
+}
 const agents = (version) => `# Remote 3 configuration (uc-config)
 
 This folder holds the user's Unfolded Circle Remote 3 configuration. It is
@@ -53,10 +71,28 @@ 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
 
-\`npm update uc-config\`, then compile and plan. The plan must show 0 operations
-before you make any other change.
+1. \`npm install uc-config@latest\` (not \`npm update\`: it won't cross 0.x minor versions).
+2. \`npx uc-config init --refresh-docs\` to update this file and CLAUDE.md.
+   Files the user edited are kept; the new version is written beside them as \`.new\`.
+3. Read node_modules/uc-config/CHANGELOG.md for any "Action required" notes.
+4. \`npx uc-config compile && npx uc-config plan\`. It must show 0 operations
+   before you make any other change. If not, the upgrade changed how the config
+   is read: show the user the plan and don't apply it.
 `;
 // Claude Code reads CLAUDE.md, not AGENTS.md. Newer releases follow the
 // @-import; the prose line covers releases that don't support imports.
@@ -85,12 +121,36 @@ const gitignore = `node_modules/
 .env.*
 `;
 /** Scaffold a private config workspace. Never overwrites existing files. */
-export async function init(dir, version) {
+export async function init(dir, version, options = {}) {
     await mkdir(dir, { recursive: true });
     const result = {
         written: [],
         skipped: [],
         packageJsonUpdated: false,
+        refreshed: [],
+        conflicts: [],
+    };
+    const doc = async (name, contents) => {
+        let existing;
+        try {
+            existing = await readFile(join(dir, name), "utf8");
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+        }
+        if (existing === undefined)
+            return put(name, contents);
+        if (!options.refreshDocs || existing === contents)
+            return void result.skipped.push(name);
+        if (isPristine(existing)) {
+            await writeFile(join(dir, name), contents);
+            result.refreshed.push(name);
+        }
+        else {
+            await writeFile(join(dir, `${name}.new`), contents);
+            result.conflicts.push(name);
+        }
     };
     const put = async (name, contents) => {
         try {
@@ -134,7 +194,7 @@ export async function init(dir, version) {
     }
     await put("tsconfig.json", JSON.stringify(tsconfig, null, 2) + "\n");
     await put(".gitignore", gitignore);
-    await put("AGENTS.md", agents(version));
-    await put("CLAUDE.md", claude);
+    await doc("AGENTS.md", stamp(version, agents(version)));
+    await doc("CLAUDE.md", stamp(version, claude));
     return result;
 }

package/docs/cli.md

@@ -12,6 +12,7 @@ the workspace's only target if exactly one is connected; otherwise `home`.
 | Command                                        | Writes to remote  | Purpose                                                                        |
 | ---------------------------------------------- | ----------------- | ------------------------------------------------------------------------------ |
 | `init [--host ip] [--no-connect]`              | API key only      | Scaffold a workspace, then prompt for IP and PIN (connect + auth). Rerunnable. |
+| `init --refresh-docs`                          | no                | Update AGENTS.md/CLAUDE.md; edited files are kept and get a `.new` copy.       |
 | `connect <name> --host <url>`                  | no                | Record a target (identity, firmware). Rerun after firmware updates.            |
 | `auth`                                         | API key only      | Exchange the web-configurator PIN (`UC_PIN` or prompt) for an API key.         |
 | `doctor`                                       | no                | Verify identity and read access to every required endpoint.                    |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uc-config",
-  "version": "0.2.0",
+  "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",
@@ -36,6 +36,7 @@
     "examples",
     "remote.config.example.ts",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {