@uns-kit/cli 2.0.71 → 2.0.73

package/README.md

@@ -139,7 +139,12 @@ uns-kit upgrade           # upgrade current directory
 uns-kit upgrade ./my-app  # upgrade a specific project
 ```
 
-Removes scripts that have been superseded (`generate-uns-dictionary`, `generate-uns-measurements`, `generate-uns-reference`, `generate-uns-metadata`) and ensures `sync-uns-schema` is present.
+Removes scripts that have been superseded (`generate-uns-dictionary`, `generate-uns-measurements`, `generate-uns-reference`, `generate-uns-metadata`), ensures the `sync-uns-*` scripts are present, and adds an idempotent managed section to `AGENTS.md` that directs agents to version-bounded `@uns-kit/core` migrations. Existing project-specific agent instructions are preserved.
+
+The installed migration guide is `node_modules/@uns-kit/core/MIGRATIONS.md`.
+For example, an upgrade crossing `<2.0.71` to `>=2.0.71` must review MQTT
+shutdown ownership, while an upgrade starting at `2.0.71` or newer must not
+rewrite shutdown code solely because of that migration.
 
 ### `uns-kit help`
 Display usage information.

package/dist/index.js

@@ -507,6 +507,52 @@ const OBSOLETE_SCRIPTS = [
     "generate-uns-reference",
     "generate-uns-metadata",
 ];
+const AGENT_MIGRATION_START = "<!-- uns-kit:migrations:start -->";
+const AGENT_MIGRATION_END = "<!-- uns-kit:migrations:end -->";
+const AGENT_MIGRATION_BLOCK = [
+    AGENT_MIGRATION_START,
+    "## UNS Kit dependency upgrades",
+    "",
+    "- Before changing any `@uns-kit/*` version, record the installed source version and intended target version.",
+    "- After installing the target version, read `node_modules/@uns-kit/core/MIGRATIONS.md` and apply every migration whose version boundary is crossed. Do not apply unrelated migrations.",
+    "- When crossing `<2.0.71` to `>=2.0.71`, inspect MQTT proxy ownership and follow the documented shutdown migration. Process-owned and standalone proxies have different shutdown paths.",
+    AGENT_MIGRATION_END,
+].join("\n");
+async function ensureAgentMigrationGuidance(targetDir) {
+    const agentsPath = path.join(targetDir, "AGENTS.md");
+    let existing;
+    try {
+        existing = await readFile(agentsPath, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+        await writeFile(agentsPath, `# AGENTS\n\n${AGENT_MIGRATION_BLOCK}\n`, "utf8");
+        return "created";
+    }
+    const startIndex = existing.indexOf(AGENT_MIGRATION_START);
+    const endIndex = existing.indexOf(AGENT_MIGRATION_END);
+    const hasStart = startIndex >= 0;
+    const hasEnd = endIndex >= 0;
+    if (hasStart !== hasEnd || (hasStart && endIndex < startIndex)) {
+        throw new Error(`Malformed UNS Kit migration block in ${agentsPath}. Remove the unmatched migration marker and run upgrade again.`);
+    }
+    let next;
+    if (hasStart) {
+        const afterEnd = endIndex + AGENT_MIGRATION_END.length;
+        next = existing.slice(0, startIndex) + AGENT_MIGRATION_BLOCK + existing.slice(afterEnd);
+    }
+    else {
+        const separator = existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+        next = `${existing}${separator}${AGENT_MIGRATION_BLOCK}\n`;
+    }
+    if (next === existing) {
+        return "unchanged";
+    }
+    await writeFile(agentsPath, next, "utf8");
+    return "updated";
+}
 async function configureDevops(targetPath, options) {
     const targetDir = path.resolve(process.cwd(), targetPath ?? ".");
     await ensureGitRepository(targetDir);
@@ -944,7 +990,9 @@ async function upgradeProject(targetPath) {
     }
     const syncScriptsChanged = ensureUnsReferenceScripts(scripts);
     changed = syncScriptsChanged || changed;
-    if (changed) {
+    const agentGuidanceResult = await ensureAgentMigrationGuidance(targetDir);
+    changed = agentGuidanceResult !== "unchanged" || changed;
+    if (removed.length > 0 || syncScriptsChanged) {
         await writeFile(packagePath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
     }
     console.log(`\nUpgrade complete for ${targetDir}`);
@@ -960,6 +1008,15 @@ async function upgradeProject(targetPath) {
     else {
         console.log("  Ensured: sync-uns-schema, sync-uns-metadata");
     }
+    if (agentGuidanceResult === "created") {
+        console.log("  Created AGENTS.md with version-bounded migration guidance.");
+    }
+    else if (agentGuidanceResult === "updated") {
+        console.log("  Added/updated version-bounded migration guidance in AGENTS.md.");
+    }
+    else {
+        console.log("  Ensured version-bounded migration guidance in AGENTS.md.");
+    }
     if (!changed) {
         console.log("  Already up to date.");
     }

package/dist/service-bundle.js

@@ -75,6 +75,14 @@ export function generateAgentsMarkdown(bundle) {
         "- Read `service.bundle.json` first when planning or generating service-specific code; it is the project source of truth.",
         "- Keep `SERVICE_SPEC.md` and this file aligned with `service.bundle.json` when the bundle changes.",
         "",
+        "<!-- uns-kit:migrations:start -->",
+        "## UNS Kit dependency upgrades",
+        "",
+        "- Before changing any `@uns-kit/*` version, record the installed source version and intended target version.",
+        "- After installing the target version, read `node_modules/@uns-kit/core/MIGRATIONS.md` and apply every migration whose version boundary is crossed. Do not apply unrelated migrations.",
+        "- When crossing `<2.0.71` to `>=2.0.71`, inspect MQTT proxy ownership and follow the documented shutdown migration. Process-owned and standalone proxies have different shutdown paths.",
+        "<!-- uns-kit:migrations:end -->",
+        "",
     ];
     if (outputPublisherContracts.length) {
         lines.push("## Output Publishing", ...outputPublisherContracts.flatMap((contract) => [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uns-kit/cli",
-  "version": "2.0.71",
+  "version": "2.0.73",
   "description": "Command line scaffolding tool for UNS applications",
   "type": "module",
   "license": "MIT",
@@ -26,13 +26,14 @@
   ],
   "dependencies": {
     "azure-devops-node-api": "^15.1.1",
-    "@uns-kit/core": "2.0.71"
+    "@uns-kit/core": "2.0.73"
   },
   "unsKitPackages": {
-    "@uns-kit/core": "2.0.71",
-    "@uns-kit/api": "2.0.71",
-    "@uns-kit/cron": "2.0.71",
-    "@uns-kit/database": "2.0.71"
+    "@uns-kit/core": "2.0.73",
+    "@uns-kit/api": "2.0.73",
+    "@uns-kit/cron": "2.0.73",
+    "@uns-kit/database": "2.0.73",
+    "@uns-kit/assistant-workflow": "2.0.73"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/templates/cron/AGENTS.md

@@ -9,6 +9,7 @@ Pointers for AI/code-assist tools when working in this generated project.
 - `src/examples/*.ts` for cron-driven publish patterns and description registration.
 - Installed docs (under `node_modules`):
   - `@uns-kit/core/README.md`
+  - `@uns-kit/core/MIGRATIONS.md`
   - `@uns-kit/api/README.md` (if installed)
   - `@uns-kit/cron/README.md` (if installed)
   - `@uns-kit/cli/README.md` (if installed)
@@ -18,3 +19,11 @@ Pointers for AI/code-assist tools when working in this generated project.
 - `pnpm run generate-codegen` -> GraphQL codegen (after configure-codegen)
 - `pnpm run sync-uns-schema -- --controller-url ... --token ...` -> pulls `uns-dictionary.json` + `uns-measurements.json` from the controller and regenerates local TS helpers
 - `pnpm run sync-uns-metadata -- --controller-url ... --token ...` -> pulls topics/tags/assets from the controller and regenerates local TS helpers
+
+<!-- uns-kit:migrations:start -->
+## UNS Kit dependency upgrades
+
+- Before changing any `@uns-kit/*` version, record the installed source version and intended target version.
+- After installing the target version, read `node_modules/@uns-kit/core/MIGRATIONS.md` and apply every migration whose version boundary is crossed. Do not apply unrelated migrations.
+- When crossing `<2.0.71` to `>=2.0.71`, inspect MQTT proxy ownership and follow the documented shutdown migration. Process-owned and standalone proxies have different shutdown paths.
+<!-- uns-kit:migrations:end -->

package/templates/default/AGENTS.md

@@ -9,6 +9,7 @@ Pointers for AI/code-assist tools when working in this generated project.
 - `src/examples/*.ts` for idiomatic publishing (multi-attribute) and description registration.
 - Installed docs (under `node_modules`):
   - `@uns-kit/core/README.md`
+  - `@uns-kit/core/MIGRATIONS.md`
   - `@uns-kit/api/README.md` (if installed)
   - `@uns-kit/cron/README.md` (if installed)
   - `@uns-kit/cli/README.md` (if installed)
@@ -18,3 +19,11 @@ Pointers for AI/code-assist tools when working in this generated project.
 - `pnpm run generate-codegen` -> GraphQL codegen (after configure-codegen)
 - `pnpm run sync-uns-schema -- --controller-url ... --token ...` -> pulls `uns-dictionary.json` + `uns-measurements.json` from the controller and regenerates local TS helpers
 - `pnpm run sync-uns-metadata -- --controller-url ... --token ...` -> pulls topics/tags/assets from the controller and regenerates local TS helpers
+
+<!-- uns-kit:migrations:start -->
+## UNS Kit dependency upgrades
+
+- Before changing any `@uns-kit/*` version, record the installed source version and intended target version.
+- After installing the target version, read `node_modules/@uns-kit/core/MIGRATIONS.md` and apply every migration whose version boundary is crossed. Do not apply unrelated migrations.
+- When crossing `<2.0.71` to `>=2.0.71`, inspect MQTT proxy ownership and follow the documented shutdown migration. Process-owned and standalone proxies have different shutdown paths.
+<!-- uns-kit:migrations:end -->