uc-config 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# 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.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

@@ -82,6 +82,23 @@ 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.
 
+## 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

@@ -194,6 +194,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 +235,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",
@@ -539,14 +567,24 @@ program
     .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")
+    .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.";
     if (!o.connect)

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
@@ -55,8 +73,13 @@ the UC Integration Manager (http://<remote>:9999); run diagnose after any update
 
 ## 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 +108,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 +181,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.1",
   "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": {