uc-config 0.1.0 → 0.2.0

package/README.md

@@ -16,24 +16,71 @@ hardware. Humans can use it directly too.
 > for copy-paste recipes. Ask the user only for what you cannot discover:
 > the remote's IP address and the web configurator PIN.
 
-## Quick start
+## Quick start (for humans)
 
-Before you start: install Node.js 22+, and on the remote enable the web
-configurator (Settings → Profile → Web configurator). Note the remote's IP and PIN.
+### 1. Before you start
+
+- Install [Node.js](https://nodejs.org/) 22 or newer.
+- 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.
+
+### 2. Create your config folder
 
 ```sh
 mkdir my-remote && cd my-remote
-npx uc-config init        # package.json, tsconfig, .gitignore, AGENTS.md
+npx uc-config init
 npm install
 ```
 
-Then start your coding agent in that folder and prompt:
+`init` creates the project files, then asks for the remote's IP address and
+the web configurator PIN. The PIN is typed hidden in your terminal and is only
+used once, to create an API key saved in `.uc/credentials.json`. Press Enter at
+either prompt to skip it; you can rerun `npx uc-config init` at any time and it
+picks up where it left off without overwriting anything.
+
+If `init` says a key named `uc-config` already exists, revoke that key in the
+web configurator and run `npx uc-config init` again.
+
+This folder holds your remote's configuration. It's yours, not part of this
+repo.
+
+### 3. Let your coding agent set it up
+
+Start your coding agent (Claude Code, Codex, Cursor, etc.) in that folder and
+prompt:
 
 > Set up my Remote 3 at `<IP>`
 
-When the agent asks you to authenticate, run `npx uc-config auth` in your own
-terminal and enter the PIN. Don't paste the PIN into chat. That folder is your
-configuration; commit it to a **private** git repo.
+The agent imports your current setup into `remote.config.ts` and records which
+resources it manages. This writes nothing to the remote.
+
+If you skipped the PIN during `init`, the agent will ask you to run
+`npx uc-config auth` in your own terminal. **Don't paste the PIN into the
+chat.**
+
+`init` also writes `CLAUDE.md`, which points Claude Code at `AGENTS.md`;
+Claude Code reads `CLAUDE.md` rather than `AGENTS.md`.
+
+### 4. Save your config
+
+Commit the folder to a **private** git repo. It contains your device IDs and
+IP addresses. `.uc/` (credentials and state) is already gitignored; back it up
+separately.
+
+### Day to day
+
+Ask your agent for changes in plain language, for example:
+
+> Make the NEXT button skip chapters in the movie activity
+
+> Add a page to Watch TV with buttons for Netflix and YouTube
+
+> Something on the remote says "orphaned entity". Fix it.
+
+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.
 
 ## Requirements
 
@@ -57,6 +104,9 @@ npm install
 npm run build
 npm test                                   # offline, uses a mock Core API
 
+# Steps 2-3 are usually already done by `npx uc-config init`. Skip them if
+# .uc/targets/*.json and .uc/credentials.json exist.
+
 # 2. Register the remote under a target name ("home" here). With a single
 #    target, later commands pick it automatically; otherwise pass --target.
 npm run uc -- connect home --host http://<REMOTE_IP>

package/dist/cli.js

@@ -4,7 +4,7 @@ import { writeFile, mkdir } from "node:fs/promises";
 import { resolve, join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { Writable } from "node:stream";
-import { CoreClient, resolveSecrets } from "./client.js";
+import { ApiError, CoreClient, resolveSecrets } from "./client.js";
 import { Adapter } from "./adapter.js";
 import { compile, validateConfig } from "./compiler.js";
 import { Engine, PendingSetup } from "./engine.js";
@@ -123,7 +123,18 @@ program
     .requiredOption("--host <url>")
     .option("--token-env <name>", "API key environment variable", "UC_API_KEY")
     .action(async (name, o) => {
-    const client = new CoreClient(o.host);
+    await connectTarget(name, o.host, o.tokenEnv);
+});
+program
+    .command("auth")
+    .option("--target <name>", "target", defaultTarget)
+    .action(async (o) => {
+    await load(o.target); // fail on a missing target before prompting
+    const pin = process.env.UC_PIN ?? (await hiddenPrompt("Web configurator PIN: "));
+    await authenticate(o.target, pin);
+});
+async function connectTarget(name, host, tokenEnv = "UC_API_KEY") {
+    const client = new CoreClient(host);
     const version = await client.version();
     if (version.model !== "UCR3" || typeof version.address !== "string")
         throw new Error("Expected an identifiable Remote 3");
@@ -131,7 +142,7 @@ program
         host: client.base.origin,
         identity: version.address,
         version,
-        tokenEnv: o.tokenEnv,
+        tokenEnv,
     };
     try {
         const old = await readJson(targetFile(name));
@@ -144,35 +155,54 @@ program
     }
     await saveJson(targetFile(name), target);
     console.log(`Connected ${name}: ${version.model}, core ${version.core}, API ${version.api}. No configuration changed.`);
-});
-program
-    .command("auth")
-    .option("--target <name>", "target", defaultTarget)
-    .action(async (o) => {
-    const { target } = await load(o.target);
-    const pin = process.env.UC_PIN ?? (await hiddenPrompt("Web configurator PIN: "));
-    const client = new CoreClient(target.host);
-    validateRequest("/auth/api_keys", "POST", {
-        name: "uc-config",
-        scopes: ["admin"],
-    });
-    const { data } = await client.request("POST", "/auth/api_keys", { name: "uc-config", scopes: ["admin"] }, {
-        Authorization: `Basic ${Buffer.from(`web-configurator:${pin}`).toString("base64")}`,
-    });
-    if (typeof data.api_key !== "string")
-        throw new Error("No API key returned");
-    let credentials = {};
+    return target;
+}
+async function hasCredentials(target) {
+    if (process.env[target.tokenEnv])
+        return true;
     try {
-        credentials = await readJson(local("credentials.json"));
+        const c = await readJson(local("credentials.json"));
+        return typeof c[target.identity] === "string";
     }
-    catch (e) {
-        if (e.code !== "ENOENT")
-            throw e;
+    catch {
+        return false;
     }
-    credentials[target.identity] = data.api_key;
-    await saveJson(local("credentials.json"), credentials);
-    console.log("API key saved in .uc/credentials.json (mode 0600, gitignored). Approve it on the remote if requested, then run doctor.");
-});
+}
+async function authenticate(name, pin) {
+    {
+        const { target } = await load(name);
+        const client = new CoreClient(target.host);
+        validateRequest("/auth/api_keys", "POST", {
+            name: "uc-config",
+            scopes: ["admin"],
+        });
+        const { data } = await client.request("POST", "/auth/api_keys", { name: "uc-config", scopes: ["admin"] }, {
+            Authorization: `Basic ${Buffer.from(`web-configurator:${pin}`).toString("base64")}`,
+        });
+        if (typeof data.api_key !== "string")
+            throw new Error("No API key returned");
+        let credentials = {};
+        try {
+            credentials = await readJson(local("credentials.json"));
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+        }
+        credentials[target.identity] = data.api_key;
+        await saveJson(local("credentials.json"), credentials);
+        console.log("API key saved in .uc/credentials.json (mode 0600, gitignored). Approve it on the remote if requested, then run doctor.");
+    }
+}
+async function question(label) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(label)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
 program
     .command("doctor")
     .option("--target <name>", "target", defaultTarget)
@@ -506,7 +536,10 @@ ir.command("capture <emitterId>")
 program
     .command("init")
     .description("Scaffold a private config workspace (package.json, tsconfig, .gitignore, AGENTS.md)")
-    .action(async () => {
+    .option("--host <ip>", "remote IP address (skips the prompt)")
+    .option("--target <name>", "target name", "home")
+    .option("--no-connect", "only create files; don't connect or authenticate")
+    .action(async (o) => {
     const r = await init(root(), pkgVersion);
     for (const f of r.written)
         console.log(`created ${f}`);
@@ -514,7 +547,69 @@ program
         console.log("added uc-config to package.json");
     for (const f of r.skipped)
         console.log(`kept existing ${f}`);
-    console.log("Next: npm install, then start your coding agent here and ask it to set up your Remote 3.");
+    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.";
+    if (!o.connect)
+        return console.log(next);
+    const name = o.target;
+    // 1. Connect (unless already connected).
+    let target;
+    try {
+        target = await readJson(targetFile(name));
+        console.log(`Already connected to ${target.host} as "${name}".`);
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    if (!target) {
+        const host = o.host ??
+            (interactive
+                ? await question("Remote 3 IP address (blank to skip): ")
+                : "");
+        if (!host) {
+            console.log(`Skipped connecting. Later: npx uc-config connect ${name} --host http://<IP>\n${next}`);
+            return;
+        }
+        try {
+            target = await connectTarget(name, host);
+        }
+        catch (e) {
+            console.log(`Could not reach a Remote 3 at ${host}: ${e.message}\n` +
+                "Check the IP, that this computer is on the same network, and that the remote is awake (pick it up).\n" +
+                `Retry: npx uc-config init --host <IP>  (files already created are kept)`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // 2. Authenticate (unless a key is already available).
+    if (await hasCredentials(target)) {
+        console.log("Already authenticated.");
+        return console.log(next);
+    }
+    const pin = process.env.UC_PIN ??
+        (interactive
+            ? await hiddenPrompt("Web configurator PIN (Settings → Profile → Web configurator; blank to skip): ")
+            : "");
+    if (!pin) {
+        console.log("Skipped authentication. Run `npx uc-config auth` in this folder when ready.\n" +
+            next);
+        return;
+    }
+    try {
+        await authenticate(name, pin);
+    }
+    catch (e) {
+        const status = e instanceof ApiError ? e.status : 0;
+        console.log(status === 401 || status === 403
+            ? "The remote rejected the PIN. Check that the web configurator is enabled and the PIN is current, then run `npx uc-config auth`."
+            : status === 400 || status === 409 || status === 422
+                ? 'An API key named "uc-config" already exists on the remote. Revoke it in the web configurator, then run `npx uc-config auth`.'
+                : `Authentication failed: ${e.message}. Retry with \`npx uc-config auth\`.`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(next);
 });
 program
     .command("diagnose")

package/dist/init.js

@@ -10,11 +10,17 @@ managed with the \`uc-config\` CLI (v${version}). Reference docs ship with the p
 - node_modules/uc-config/docs/cli.md: every command, recovery
 - node_modules/uc-config/docs/configuration-authoring.md: config syntax and ownership
 
-## First run (no .uc/targets/ yet)
+## First run
 
-1. \`npx uc-config connect home --host http://<IP>\`. Ask the user for the IP if not given.
-2. Ask the user to run \`npx uc-config auth\` in their own terminal (the web
-   configurator must be enabled on the remote). Never ask for the PIN in chat.
+\`npx uc-config init\` usually already connected and authenticated. Check what
+exists, and skip steps that are done:
+
+1. No \`.uc/targets/*.json\`: run \`npx uc-config connect home --host http://<IP>\`.
+   Ask the user for the IP if not given.
+2. No \`.uc/credentials.json\` (and no \`UC_API_KEY\` env): ask the user to run
+   \`npx uc-config auth\` in their own terminal (the web configurator must be
+   enabled on the remote). Never ask for the PIN in chat, and never run \`auth\`
+   yourself; it needs a real terminal.
 3. \`npx uc-config doctor\`
 4. \`npx uc-config inventory --bindings generated/devices.ts\`
 5. \`npx uc-config import --out remote.config.ts\`
@@ -52,6 +58,15 @@ the UC Integration Manager (http://<remote>:9999); run diagnose after any update
 \`npm update uc-config\`, then compile and plan. The plan must show 0 operations
 before you make any other change.
 `;
+// Claude Code reads CLAUDE.md, not AGENTS.md. Newer releases follow the
+// @-import; the prose line covers releases that don't support imports.
+const claude = `# Remote 3 configuration (uc-config)
+
+Read AGENTS.md in this folder before doing anything. It is the authoritative
+guide for working here: setup steps, editing rules and safety limits.
+
+@AGENTS.md
+`;
 const tsconfig = {
     compilerOptions: {
         target: "ES2023",
@@ -120,5 +135,6 @@ 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);
     return result;
 }

package/docs/cli.md

@@ -9,33 +9,37 @@ the workspace's only target if exactly one is connected; otherwise `home`.
 
 ## Commands
 
-| Command                                        | Writes to remote  | Purpose                                                                 |
-| ---------------------------------------------- | ----------------- | ----------------------------------------------------------------------- |
-| `init`                                         | no                | Scaffold a private config workspace. Never overwrites files.            |
-| `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.             |
-| `diagnose [--json]`                            | no                | Orphaned entity references, disconnected integrations, suggested fixes. |
-| `inventory [--out f] [--bindings f.ts]`        | no                | Raw (redacted) remote state; optional typed entity/command bindings.    |
-| `import [--out f.ts]`                          | no                | Generate editable config from the live remote. Never overwrites.        |
-| `compile [--config f] [--out f]`               | no                | Evaluate TS config into `.uc/build.json`. Offline.                      |
-| `plan [--out f] [--prune] [--overwrite-drift]` | no                | Three-way diff: source vs last-applied vs live.                         |
-| `apply <plan> [--adopt-only]`                  | yes               | Execute a saved plan after re-verifying preconditions.                  |
-| `check`                                        | no                | Re-plan and exit 2 if anything differs.                                 |
-| `resume`                                       | maybe             | Continue paused setup; reconcile an interrupted apply.                  |
-| `setup status/respond <key>`                   | yes               | Drive interactive integration/dock setup.                               |
-| `pairing status/respond <remoteId>`            | yes               | Bluetooth pairing steps.                                                |
-| `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.                    |
-| `api <METHOD> <path> [--data json] [--write]`  | only with --write | Raw authenticated Core API call; output redacted.                       |
+| 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. |
+| `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.                    |
+| `diagnose [--json]`                            | no                | Orphaned entity references, disconnected integrations, suggested fixes.        |
+| `inventory [--out f] [--bindings f.ts]`        | no                | Raw (redacted) remote state; optional typed entity/command bindings.           |
+| `import [--out f.ts]`                          | no                | Generate editable config from the live remote. Never overwrites.               |
+| `compile [--config f] [--out f]`               | no                | Evaluate TS config into `.uc/build.json`. Offline.                             |
+| `plan [--out f] [--prune] [--overwrite-drift]` | no                | Three-way diff: source vs last-applied vs live.                                |
+| `apply <plan> [--adopt-only]`                  | yes               | Execute a saved plan after re-verifying preconditions.                         |
+| `check`                                        | no                | Re-plan and exit 2 if anything differs.                                        |
+| `resume`                                       | maybe             | Continue paused setup; reconcile an interrupted apply.                         |
+| `setup status/respond <key>`                   | yes               | Drive interactive integration/dock setup.                                      |
+| `pairing status/respond <remoteId>`            | yes               | Bluetooth pairing steps.                                                       |
+| `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.                           |
+| `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,
 `3` paused for a human step.
 
 ## Authentication
 
+`init` runs `connect` and `auth` for you when started in a terminal. Without a
+terminal (e.g. run by an agent) it only scaffolds files unless `--host` and
+`UC_PIN` are supplied. Steps already completed are skipped on reruns.
+
 `auth` prompts for the web configurator PIN. Enable the web configurator on the
 remote first, and approve the key on the remote if asked. Non-interactive
 options: set `UC_PIN`, or set `UC_API_KEY` to an existing key (`connect

package/package.json

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