@uns-kit/cli 2.0.26 → 2.0.28

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2023 Aljoša Vister
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2023 Aljoša Vister
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,175 +1,175 @@
-# @uns-kit/cli
-
-Command line scaffolding tool for the UNS toolkit. It bootstraps a new project with `@uns-kit/core` preconfigured and ready to extend with additional plugins.
-
-Note: Apps built with uns-kit are intended to be managed by the **UNS Datahub controller**.
-
-## uns-kit in context
-
-uns-kit is a batteries-included toolkit for Unified Namespace applications. It standardizes MQTT wiring, auth, config schemas, and scaffolding so you can focus on your domain logic. The toolkit packages are:
-
-| Package | Description |
-| --- | --- |
-| [`@uns-kit/core`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-core) | Base runtime utilities (UnsProxyProcess, MQTT helpers, configuration tooling, gRPC gateway support). |
-| [`@uns-kit/api`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-api) | Express plugin that exposes HTTP endpoints, handles JWT/JWKS auth, and republishes API metadata to UNS. |
-| [`@uns-kit/cron`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-cron) | Cron-driven scheduler that emits UNS events on a fixed cadence. |
-| [`@uns-kit/temporal`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-temporal) | Temporal.io integration that wires workflows into UnsProxyProcess. |
-| [`@uns-kit/cli`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-cli) | Command line tool for scaffolding new UNS applications. |
-
-## Prerequisites
-
-- Node.js 18 or newer (ES2022 runtime features)
-- A package manager such as `pnpm`, `npm`, or `yarn`
-- `git` available on PATH (required for `configure-devops`, used to initialize new projects automatically)
-
-## Usage
-
-```bash
-pnpm --package=@uns-kit/cli dlx uns-kit create my-uns-app
-# or with npx
-npx @uns-kit/cli create my-uns-app
-# or after installing globally
-npm install -g @uns-kit/cli
-uns-kit create my-uns-app
-```
-
-The command creates a new directory, copies the starter template, and pins `@uns-kit/core` to the currently published version. After the scaffold finishes:
-
-```bash
-cd my-uns-app
-pnpm install
-pnpm run dev
-```
-
-When `git` is available on your PATH the scaffold also initializes a fresh repository so you can commit immediately.
-
-### Create from a service bundle
-
-```bash
-uns-kit create --bundle ./service.bundle.json
-uns-kit create --bundle ./service.bundle.json --dest ./my-dir
-uns-kit create --bundle ./service.bundle.json --dest . --allow-existing
-```
-
-Bundle-driven create uses `service.bundle.json` as the source of truth. The CLI:
-
-- scaffolds the base TypeScript app from the existing default template
-- copies the original bundle into the project root as `service.bundle.json`
-- generates `SERVICE_SPEC.md` and `AGENTS.md`
-- applies supported bundle features such as `vscode` and `devops`
-
-When `--bundle` is used, the default destination is `./<metadata.name>`. The TypeScript CLI only accepts bundles with `scaffold.stack = "ts"` and currently supports `scaffold.template = "default"` for this MVP. If the bundle targets Python instead, use `uns-kit-py create --bundle ...`.
-
-## Commands
-
-- `uns-kit create <name>` – create a new UNS project in the specified directory.
-- `uns-kit create --bundle <path> [--dest <dir>] [--allow-existing]` – create a new TypeScript UNS project from `service.bundle.json`.
-- `uns-kit configure [path] [features...]` – run multiple configure templates in sequence (`--all`, `--overwrite`).
-- `uns-kit configure-templates [path] [templates...]` – copy any template directory (`--all`, `--overwrite`).
-- `uns-kit configure-devops [path]` – add Azure DevOps tooling (dependencies, script, config) to an existing project.
-- `uns-kit configure-vscode [path]` – copy VS Code launch/workspace files into an existing project.
-- `uns-kit configure-codegen [path]` – scaffold GraphQL code generation and UNS refresh scripts.
-- `uns-kit configure-api [path]` – copy UNS API examples and add `@uns-kit/api`.
-- `uns-kit configure-cron [path]` – copy UNS cron examples and add `@uns-kit/cron`.
-- `uns-kit configure-temporal [path]` – copy UNS Temporal examples and add `@uns-kit/temporal`.
-- `uns-kit configure-python [path]` – copy Python gateway client scaffolding (no npm dependency required).
-- `uns-kit help` – display usage information.
-
-### Configure multiple features at once
-
-Chain several add-ons without running each subcommand manually:
-
-```bash
-uns-kit configure --all
-uns-kit configure ./apps/gateway devops vscode codegen
-```
-
-Mix and match feature names after an optional target directory. Use `--all` to apply every available template in one shot. Add `--overwrite` to refresh files from newer template versions.
-
-### Copy arbitrary templates
-
-Need a template that is not wired into a configure feature (or added in a newer release)? Use:
-
-```bash
-uns-kit configure-templates --all
-uns-kit configure-templates ./apps/gateway uns-dictionary uns-measurements --overwrite
-```
-
-### Configure Azure DevOps
-
-Run inside a scaffolded project to add the Azure DevOps pull-request tooling:
-
-```bash
-uns-kit configure-devops
-pnpm install
-pnpm run pull-request
-```
-
-The command prompts for your Azure DevOps organization/project, ensures the remote repository exists, and updates `config.json` along with the necessary dev dependencies.
-
-### Configure VS Code workspace
-
-```bash
-uns-kit configure-vscode
-```
-
-Copies `.vscode/launch.json` plus a baseline workspace file into the project. Existing files are skipped unless you pass `--overwrite`.
-
-### Configure GraphQL code generation
-
-```bash
-uns-kit configure-codegen
-pnpm install
-pnpm run codegen
-pnpm run refresh-uns
-```
-
-Adds `codegen.ts`, seeds `src/uns/` placeholder types, and wires the GraphQL Code Generator / `refresh-uns` script into `package.json`. After installing the new dev dependencies you can regenerate strongly-typed operations (`pnpm run codegen`) and rebuild UNS topics/tags from your environment (`pnpm run refresh-uns`).
-After installing the new dev dependencies you can regenerate strongly-typed operations (`pnpm run codegen`) and rebuild UNS metadata (topics/tags/assets) from your environment (`pnpm run generate-uns-metadata`).
-
-### Add UNS API scaffolding
-
-```bash
-uns-kit configure-api
-pnpm install
-```
-
-Copies API-oriented examples (under `src/examples/`) and adds `@uns-kit/api` to your project dependencies.
-Use `--overwrite` to refresh the examples after updating `uns-kit`.
-
-### Add cron-based scaffolding
-
-```bash
-uns-kit configure-cron
-pnpm install
-```
-
-Adds cron-oriented example stubs and installs `@uns-kit/cron`.
-Use `--overwrite` to refresh the examples after updating `uns-kit`.
-
-### Add Temporal scaffolding
-
-```bash
-uns-kit configure-temporal
-pnpm install
-```
-
-Copies Temporal example placeholders and installs `@uns-kit/temporal`.
-Use `--overwrite` to refresh the examples after updating `uns-kit`.
-
-### Add Python gateway scaffolding
-
-```bash
-uns-kit configure-python
-```
-
-Copies the Python gateway client template (examples, scripts, requirements, proto) into your project so you can iterate on the gRPC gateway from Python alongside your TypeScript project.
-Use `--overwrite` to refresh the examples after updating `uns-kit`.
-
-### Extend the Config Schema
-
-Edit `src/config/project.config.extension.ts` inside your generated project and run `pnpm run generate-config-schema`. This regenerates `config.schema.json` and `src/config/app-config.ts`, augmenting `@uns-kit/core`'s `AppConfig` so editors and runtime types stay in sync. If completions lag, reload the TypeScript server in your editor.
-
-## License
-
-MIT © Aljoša Vister
+# @uns-kit/cli
+
+Command line scaffolding tool for the UNS toolkit. It bootstraps a new project with `@uns-kit/core` preconfigured and ready to extend with additional plugins.
+
+Note: Apps built with uns-kit are intended to be managed by the **UNS Datahub controller**.
+
+## uns-kit in context
+
+uns-kit is a batteries-included toolkit for Unified Namespace applications. It standardizes MQTT wiring, auth, config schemas, and scaffolding so you can focus on your domain logic. The toolkit packages are:
+
+| Package | Description |
+| --- | --- |
+| [`@uns-kit/core`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-core) | Base runtime utilities (UnsProxyProcess, MQTT helpers, configuration tooling, gRPC gateway support). |
+| [`@uns-kit/api`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-api) | Express plugin that exposes HTTP endpoints, handles JWT/JWKS auth, and republishes API metadata to UNS. |
+| [`@uns-kit/cron`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-cron) | Cron-driven scheduler that emits UNS events on a fixed cadence. |
+| [`@uns-kit/temporal`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-temporal) | Temporal.io integration that wires workflows into UnsProxyProcess. |
+| [`@uns-kit/cli`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-cli) | Command line tool for scaffolding new UNS applications. |
+
+## Prerequisites
+
+- Node.js 18 or newer (ES2022 runtime features)
+- A package manager such as `pnpm`, `npm`, or `yarn`
+- `git` available on PATH (required for `configure-devops`, used to initialize new projects automatically)
+
+## Usage
+
+```bash
+pnpm --package=@uns-kit/cli dlx uns-kit create my-uns-app
+# or with npx
+npx @uns-kit/cli create my-uns-app
+# or after installing globally
+npm install -g @uns-kit/cli
+uns-kit create my-uns-app
+```
+
+The command creates a new directory, copies the starter template, and pins `@uns-kit/core` to the currently published version. After the scaffold finishes:
+
+```bash
+cd my-uns-app
+pnpm install
+pnpm run dev
+```
+
+When `git` is available on your PATH the scaffold also initializes a fresh repository so you can commit immediately.
+
+### Create from a service bundle
+
+```bash
+uns-kit create --bundle ./service.bundle.json
+uns-kit create --bundle ./service.bundle.json --dest ./my-dir
+uns-kit create --bundle ./service.bundle.json --dest . --allow-existing
+```
+
+Bundle-driven create uses `service.bundle.json` as the source of truth. The CLI:
+
+- scaffolds the base TypeScript app from the existing default template
+- copies the original bundle into the project root as `service.bundle.json`
+- generates `SERVICE_SPEC.md` and `AGENTS.md`
+- applies supported bundle features such as `vscode` and `devops`
+
+When `--bundle` is used, the default destination is `./<metadata.name>`. The TypeScript CLI only accepts bundles with `scaffold.stack = "ts"` and currently supports `scaffold.template = "default"` for this MVP. If the bundle targets Python instead, use `uns-kit-py create --bundle ...`.
+
+## Commands
+
+- `uns-kit create <name>` – create a new UNS project in the specified directory.
+- `uns-kit create --bundle <path> [--dest <dir>] [--allow-existing]` – create a new TypeScript UNS project from `service.bundle.json`.
+- `uns-kit configure [path] [features...]` – run multiple configure templates in sequence (`--all`, `--overwrite`).
+- `uns-kit configure-templates [path] [templates...]` – copy any template directory (`--all`, `--overwrite`).
+- `uns-kit configure-devops [path]` – add Azure DevOps tooling (dependencies, script, config) to an existing project.
+- `uns-kit configure-vscode [path]` – copy VS Code launch/workspace files into an existing project.
+- `uns-kit configure-codegen [path]` – scaffold GraphQL code generation and UNS refresh scripts.
+- `uns-kit configure-api [path]` – copy UNS API examples and add `@uns-kit/api`.
+- `uns-kit configure-cron [path]` – copy UNS cron examples and add `@uns-kit/cron`.
+- `uns-kit configure-temporal [path]` – copy UNS Temporal examples and add `@uns-kit/temporal`.
+- `uns-kit configure-python [path]` – copy Python gateway client scaffolding (no npm dependency required).
+- `uns-kit help` – display usage information.
+
+### Configure multiple features at once
+
+Chain several add-ons without running each subcommand manually:
+
+```bash
+uns-kit configure --all
+uns-kit configure ./apps/gateway devops vscode codegen
+```
+
+Mix and match feature names after an optional target directory. Use `--all` to apply every available template in one shot. Add `--overwrite` to refresh files from newer template versions.
+
+### Copy arbitrary templates
+
+Need a template that is not wired into a configure feature (or added in a newer release)? Use:
+
+```bash
+uns-kit configure-templates --all
+uns-kit configure-templates ./apps/gateway uns-dictionary uns-measurements --overwrite
+```
+
+### Configure Azure DevOps
+
+Run inside a scaffolded project to add the Azure DevOps pull-request tooling:
+
+```bash
+uns-kit configure-devops
+pnpm install
+pnpm run pull-request
+```
+
+The command prompts for your Azure DevOps organization/project, ensures the remote repository exists, and updates `config.json` along with the necessary dev dependencies.
+
+### Configure VS Code workspace
+
+```bash
+uns-kit configure-vscode
+```
+
+Copies `.vscode/launch.json` plus a baseline workspace file into the project. Existing files are skipped unless you pass `--overwrite`.
+
+### Configure GraphQL code generation
+
+```bash
+uns-kit configure-codegen
+pnpm install
+pnpm run codegen
+pnpm run refresh-uns
+```
+
+Adds `codegen.ts`, seeds `src/uns/` placeholder types, and wires the GraphQL Code Generator / `refresh-uns` script into `package.json`. After installing the new dev dependencies you can regenerate strongly-typed operations (`pnpm run codegen`) and rebuild UNS topics/tags from your environment (`pnpm run refresh-uns`).
+After installing the new dev dependencies you can regenerate strongly-typed operations (`pnpm run codegen`) and rebuild UNS metadata (topics/tags/assets) from your environment (`pnpm run generate-uns-metadata`).
+
+### Add UNS API scaffolding
+
+```bash
+uns-kit configure-api
+pnpm install
+```
+
+Copies API-oriented examples (under `src/examples/`) and adds `@uns-kit/api` to your project dependencies.
+Use `--overwrite` to refresh the examples after updating `uns-kit`.
+
+### Add cron-based scaffolding
+
+```bash
+uns-kit configure-cron
+pnpm install
+```
+
+Adds cron-oriented example stubs and installs `@uns-kit/cron`.
+Use `--overwrite` to refresh the examples after updating `uns-kit`.
+
+### Add Temporal scaffolding
+
+```bash
+uns-kit configure-temporal
+pnpm install
+```
+
+Copies Temporal example placeholders and installs `@uns-kit/temporal`.
+Use `--overwrite` to refresh the examples after updating `uns-kit`.
+
+### Add Python gateway scaffolding
+
+```bash
+uns-kit configure-python
+```
+
+Copies the Python gateway client template (examples, scripts, requirements, proto) into your project so you can iterate on the gRPC gateway from Python alongside your TypeScript project.
+Use `--overwrite` to refresh the examples after updating `uns-kit`.
+
+### Extend the Config Schema
+
+Edit `src/config/project.config.extension.ts` inside your generated project and run `pnpm run generate-config-schema`. This regenerates `config.schema.json` and `src/config/app-config.ts`, augmenting `@uns-kit/core`'s `AppConfig` so editors and runtime types stay in sync. If completions lag, reload the TypeScript server in your editor.
+
+## License
+
+MIT © Aljoša Vister

package/dist/index.js

@@ -145,6 +145,17 @@ async function main() {
         }
         return;
     }
+    if (command === "upgrade") {
+        const targetPath = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
+        try {
+            await upgradeProject(targetPath);
+        }
+        catch (error) {
+            console.error(error.message);
+            process.exitCode = 1;
+        }
+        return;
+    }
     if (command === "create") {
         try {
             const createOptions = parseCreateArgs(args.slice(1));
@@ -184,6 +195,7 @@ function printHelp() {
         "  configure-temporal [dir] Copy UNS Temporal examples and add @uns-kit/temporal\n" +
         "  configure-python [dir]   Copy Python gateway client scaffolding\n" +
         "  configure-uns-reference [dir]  Copy UNS dictionaries (objects/attributes/measurements)\n" +
+        "  upgrade [dir]           Remove obsolete scripts and update to current conventions\n" +
         "  help                    Show this message\n");
 }
 function parseCreateArgs(args) {
@@ -374,6 +386,22 @@ async function initGitRepository(targetDir) {
         return false;
     }
 }
+function setPackageScript(scripts, name, command) {
+    if (scripts[name] === command) {
+        return false;
+    }
+    scripts[name] = command;
+    return true;
+}
+function ensureUnsReferenceScripts(scripts) {
+    return setPackageScript(scripts, "sync-uns-schema", "node ./node_modules/@uns-kit/core/dist/tools/sync-uns-schema.js");
+}
+const OBSOLETE_SCRIPTS = [
+    "generate-uns-dictionary",
+    "generate-uns-measurements",
+    "generate-uns-reference",
+    "generate-uns-metadata",
+];
 async function configureDevops(targetPath, options) {
     const targetDir = path.resolve(process.cwd(), targetPath ?? ".");
     await ensureGitRepository(targetDir);
@@ -689,8 +717,6 @@ async function configureCodegen(targetPath, options = {}) {
         scripts["generate-codegen"] = "graphql-code-generator --config codegen.ts";
         pkgChanged = true;
     }
-    scripts["generate-uns-metadata"] = "node ./node_modules/@uns-kit/core/dist/tools/refresh-uns.js";
-    pkgChanged = true;
     if (pkgChanged) {
         await writeFile(packagePath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
     }
@@ -762,6 +788,7 @@ async function configurePython(targetPath, options = {}) {
     });
 }
 async function configureUnsReference(targetPath, options = {}) {
+    const targetDir = path.resolve(process.cwd(), targetPath ?? ".");
     await configurePlugin({
         targetPath,
         templateName: "uns-dictionary",
@@ -774,6 +801,74 @@ async function configureUnsReference(targetPath, options = {}) {
         label: "UNS measurements (units)",
         overwrite: options.overwrite,
     });
+    const packagePath = path.join(targetDir, "package.json");
+    let pkgRaw;
+    try {
+        pkgRaw = await readFile(packagePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Could not find package.json in ${targetDir}`);
+        }
+        throw error;
+    }
+    const pkg = JSON.parse(pkgRaw);
+    const scripts = (pkg.scripts ??= {});
+    const pkgChanged = ensureUnsReferenceScripts(scripts);
+    if (pkgChanged) {
+        await writeFile(packagePath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+        console.log("  Updated package.json schema scripts.");
+    }
+    else {
+        console.log("  Existing package.json already contained schema scripts.");
+    }
+}
+async function upgradeProject(targetPath) {
+    const targetDir = path.resolve(process.cwd(), targetPath ?? ".");
+    const packagePath = path.join(targetDir, "package.json");
+    let pkgRaw;
+    try {
+        pkgRaw = await readFile(packagePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Could not find package.json in ${targetDir}`);
+        }
+        throw error;
+    }
+    const pkg = JSON.parse(pkgRaw);
+    const scripts = (pkg.scripts ??= {});
+    let changed = false;
+    const removed = [];
+    for (const name of OBSOLETE_SCRIPTS) {
+        if (scripts[name] !== undefined) {
+            delete scripts[name];
+            removed.push(name);
+            changed = true;
+        }
+    }
+    // Ensure sync-uns-schema is present if any uns-reference scripts were present
+    const hadUnsReference = removed.some((name) => name.startsWith("generate-uns"));
+    if (hadUnsReference && !scripts["sync-uns-schema"]) {
+        scripts["sync-uns-schema"] = "node ./node_modules/@uns-kit/core/dist/tools/sync-uns-schema.js";
+        changed = true;
+    }
+    if (changed) {
+        await writeFile(packagePath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+    }
+    console.log(`\nUpgrade complete for ${targetDir}`);
+    if (removed.length > 0) {
+        console.log("  Removed obsolete scripts:");
+        for (const name of removed) {
+            console.log(`    - ${name}`);
+        }
+    }
+    if (hadUnsReference && !scripts["sync-uns-schema"]) {
+        console.log("  Added: sync-uns-schema");
+    }
+    if (!changed) {
+        console.log("  Already up to date.");
+    }
 }
 const configureFeatureHandlers = {
     devops: configureDevops,

package/package.json

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