@uns-kit/cli 2.0.29 → 2.0.30

package/README.md

@@ -1,39 +1,33 @@
 # @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.
+Command line scaffolding tool for the UNS toolkit. Bootstraps new projects with `@uns-kit/core` preconfigured and ready to extend with plugins. Also provides configure and upgrade commands for existing projects.
 
 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/core`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-core) | Base runtime (UnsProxyProcess, MQTT helpers, config tooling, gRPC gateway). |
+| [`@uns-kit/api`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-api) | Express plugin — HTTP endpoints, JWT/JWKS auth, Swagger, UNS metadata. |
 | [`@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. |
+| [`@uns-kit/cli`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-cli) | CLI 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)
+- Node.js 22 or newer
+- `pnpm`, `npm`, or `yarn`
+- `git` on PATH (used to initialise new projects and for `configure-devops`)
 
-## Usage
+## Create a new project
 
 ```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:
+After scaffolding:
 
 ```bash
 cd my-uns-app
@@ -41,7 +35,7 @@ pnpm install
 pnpm run dev
 ```
 
-When `git` is available on your PATH the scaffold also initializes a fresh repository so you can commit immediately.
+The scaffold creates a project directory from the default TypeScript template, pins `@uns-kit/core` to the current version, and initialises a git repository if `git` is available.
 
 ### Create from a service bundle
 
@@ -51,53 +45,38 @@ 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 ...`.
+Bundle-driven create uses `service.bundle.json` as the source of truth. The CLI scaffolds the base app, copies the bundle into the project root, generates `SERVICE_SPEC.md` and `AGENTS.md`, and applies supported bundle features (`vscode`, `devops`, etc.). Only bundles with `scaffold.stack = "ts"` are accepted by this CLI; use `uns-kit-py` for Python bundles.
 
 ## 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.
+### `uns-kit create <name>`
+Scaffold a new project from the default TypeScript template.
 
-### Configure multiple features at once
+### `uns-kit create --bundle <path> [--dest <dir>] [--allow-existing]`
+Scaffold from a `service.bundle.json` descriptor.
 
-Chain several add-ons without running each subcommand manually:
+### `uns-kit configure [dir] [features...]`
+Apply one or more feature templates to an existing project in one go.
 
 ```bash
-uns-kit configure --all
-uns-kit configure ./apps/gateway devops vscode codegen
+uns-kit configure                        # prompts for features
+uns-kit configure --all                  # apply all available features
+uns-kit configure ./my-app api cron      # add API and cron scaffolding
+uns-kit configure ./my-app --overwrite   # refresh existing files from latest templates
 ```
 
-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
+Available feature names: `devops`, `vscode`, `codegen`, `api`, `cron`, `python`, `uns-reference`.
 
-Need a template that is not wired into a configure feature (or added in a newer release)? Use:
+### `uns-kit configure-templates [dir] [templates...]`
+Copy any template directory by name.
 
 ```bash
 uns-kit configure-templates --all
-uns-kit configure-templates ./apps/gateway uns-dictionary uns-measurements --overwrite
+uns-kit configure-templates uns-dictionary uns-measurements --overwrite
 ```
 
-### Configure Azure DevOps
-
-Run inside a scaffolded project to add the Azure DevOps pull-request tooling:
+### `uns-kit configure-devops [dir]`
+Add Azure DevOps pull-request tooling. Requires a git repository.
 
 ```bash
 uns-kit configure-devops
@@ -105,70 +84,83 @@ 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`.
+### `uns-kit configure-vscode [dir]`
+Copy `.vscode/launch.json` and a workspace file. Skips existing files unless `--overwrite` is passed.
 
-### Configure GraphQL code generation
+### `uns-kit configure-codegen [dir]`
+Scaffold GraphQL code generation (`codegen.ts`, placeholder types in `src/uns/`).
 
 ```bash
 uns-kit configure-codegen
 pnpm install
-pnpm run codegen
-pnpm run refresh-uns
+pnpm run generate-codegen   # regenerate strongly-typed GraphQL operations
 ```
 
-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
+### `uns-kit configure-api [dir]`
+Copy API example stubs (`src/examples/api-example.ts`) and add `@uns-kit/api`.
 
 ```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`.
+The example shows both GET and POST endpoint registration with JWT auth, query params, request body schemas, and event handlers. Rename and adapt `api-example.ts` to `index.ts` as your starting point.
 
-### Add cron-based scaffolding
+### `uns-kit configure-cron [dir]`
+Copy cron example stubs and add `@uns-kit/cron`.
 
 ```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`.
+### `uns-kit configure-python [dir]`
+Copy Python gRPC gateway client scaffolding (no npm dependency required).
 
-### Add Temporal scaffolding
+```bash
+uns-kit configure-python
+```
+
+### `uns-kit configure-uns-reference [dir]`
+Copy UNS dictionary and measurements JSON files into the project and add the `sync-uns-schema` script to `package.json`.
 
 ```bash
-uns-kit configure-temporal
-pnpm install
+uns-kit configure-uns-reference
+pnpm run sync-uns-schema   # pull latest schema from the controller
 ```
 
-Copies Temporal example placeholders and installs `@uns-kit/temporal`.
-Use `--overwrite` to refresh the examples after updating `uns-kit`.
+### `uns-kit upgrade [dir]`
+Remove obsolete scripts from `package.json` and migrate to current conventions.
+
+```bash
+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.
+
+### `uns-kit help`
+Display usage information.
 
-### Add Python gateway scaffolding
+## Extend the config schema
+
+Edit `src/config/project.config.extension.ts` inside your project and run:
 
 ```bash
-uns-kit configure-python
+pnpm run generate-config-schema
 ```
 
-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`.
+This regenerates `config.schema.json` and `src/config/app-config.ts` so editors and runtime types stay in sync with your extensions.
+
+## Sync the UNS schema
 
-### Extend the Config Schema
+After scaffolding (or at any time) pull the latest UNS dictionary and measurements from the controller:
+
+```bash
+pnpm run sync-uns-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.
+The controller URL is read from `config.json` (`uns.rest`) automatically. You will be prompted for the bearer token if `UNS_CONTROLLER_TOKEN` is not set.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uns-kit/cli",
-  "version": "2.0.29",
+  "version": "2.0.30",
   "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.29"
+    "@uns-kit/core": "2.0.30"
   },
   "unsKitPackages": {
-    "@uns-kit/core": "2.0.29",
-    "@uns-kit/api": "2.0.29",
-    "@uns-kit/cron": "2.0.29",
-    "@uns-kit/temporal": "2.0.28"
+    "@uns-kit/core": "2.0.30",
+    "@uns-kit/api": "2.0.30",
+    "@uns-kit/cron": "2.0.30",
+    "@uns-kit/temporal": "2.0.30"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/templates/api/src/examples/api-example.ts

@@ -1,5 +1,17 @@
 /**
  * Change this file according to your specifications and rename it to index.ts
+ *
+ * This example shows how to register GET and POST API endpoints using @uns-kit/api.
+ * Each endpoint is tied to a UNS topic/asset/objectType/objectId/attribute path and
+ * is automatically registered with the UNS controller and exposed via Swagger.
+ *
+ * Endpoint signature:
+ *   api.get(topic, asset, objectType, objectId, attribute, options?)
+ *   api.post(topic, asset, objectType, objectId, attribute, options?)
+ *
+ * Events:
+ *   apiGetEvent  — fired for every incoming GET request
+ *   apiPostEvent — fired for every incoming POST request
  */
 import { UnsProxyProcess, ConfigFile } from "@uns-kit/core";
 import { IApiProxyOptions } from "@uns-kit/core";
@@ -10,14 +22,16 @@ import { type UnsProxyProcessWithApi } from "@uns-kit/api";
 /**
  * Load the configuration from a file.
  * On the server, this file is provided by the `uns-datahub-controller`.
- * In the development environment, you are responsible for creating and maintaining this file and its contents.
+ * In the development environment, you are responsible for creating and maintaining this file.
  */
 const config = await ConfigFile.loadConfig();
 
 /**
- * Connect to the API proxy process
+ * Create the API proxy.
+ * Auth is automatically applied to every registered endpoint.
+ * Use jwksWellKnownUrl (preferred in production) or jwtSecret (dev/simple deployments).
  */
-const unsProxyProcess = new UnsProxyProcess(config.infra.host!, {processName: config.uns.processName}) as UnsProxyProcessWithApi;
+const unsProxyProcess = new UnsProxyProcess(config.infra.host!, { processName: config.uns.processName }) as UnsProxyProcessWithApi;
 const apiOptions: IApiProxyOptions = config.uns?.jwksWellKnownUrl
   ? {
       jwks: {
@@ -32,60 +46,110 @@ const apiOptions: IApiProxyOptions = config.uns?.jwksWellKnownUrl
     };
 const apiInput = await unsProxyProcess.createApiProxy("templateUnsApiInput", apiOptions);
 
+// ─── GET endpoints ────────────────────────────────────────────────────────────
+
 /**
- * Register an API endpoint and event handler
+ * Register a GET endpoint.
+ * Query params are validated automatically; required params return 400 when missing.
+ * chatCanonical maps natural-language field names to query params for LLM tooling.
  */
-apiInput.get(
+await apiInput.get(
   "enterprise/site/area/line/",
   "line-3-furnace",
   "energy-resource",
   "main-bus",
-  "summary-1",
+  "current",
   {
-    tags: ["Tag1"],
-    apiDescription: "Test API endpoint 1",
+    tags: ["Energy"],
+    apiDescription: "Current reading for line-3-furnace main-bus",
     queryParams: [
-      { name: "filter", type: "string", required: true, description: "Filter za podatke" },
-      { name: "limit", type: "number", required: false, description: "Koliko podatkov želiš" },
+      { name: "from", type: "string", required: false, description: "Start of time range (ISO 8601)", chatCanonical: "from" },
+      { name: "to",   type: "string", required: false, description: "End of time range (ISO 8601)",   chatCanonical: "to"   },
+      { name: "limit", type: "number", required: false, description: "Maximum number of records",     chatCanonical: "limit", defaultValue: 100 },
     ],
+    chatDefaults: { limit: 100 },
   }
 );
 
-apiInput.get(
+await apiInput.get(
   "enterprise/site/area/line/",
   "line-3-compressor",
   "utility-resource",
   "air-loop-1",
-  "summary-2",
+  "pressure",
   {
-    tags: ["Tag2"],
-    apiDescription: "Test API endpoint 2",
+    tags: ["Utility"],
+    apiDescription: "Pressure reading for line-3-compressor air-loop-1",
     queryParams: [
-      { name: "filter", type: "string", required: true, description: "Filter za podatke" },
-      { name: "limit", type: "number", required: false, description: "Koliko podatkov želiš" },
+      { name: "limit", type: "number", required: false, description: "Maximum number of records", defaultValue: 50 },
     ],
   }
 );
 
+// ─── POST endpoints ───────────────────────────────────────────────────────────
+
 /**
- * Optional: register a catch-all API mapping for a topic prefix.
- * This does not create per-attribute API nodes; the controller treats it as a fallback handler.
- * You can provide a separate Swagger doc for catch-all so it stays distinct from normal APIs (optional).
+ * Register a POST endpoint.
+ * Use POST when the caller needs to send a request body (commands, write operations, etc.).
+ * The requestBody schema is published to Swagger so clients know what to send.
  */
-await apiInput.registerCatchAll("sij/acroni/#", {
-  apiDescription: "Catch-all handler for sij/acroni/*",
-  tags: ["CatchAll"],
-  queryParams: [
-    { name: "filter", type: "string", required: false, description: "Filter parameter" },
-  ]
-});
+await apiInput.post(
+  "enterprise/site/area/line/",
+  "line-3-furnace",
+  "energy-resource",
+  "main-bus",
+  "setpoint",
+  {
+    tags: ["Energy"],
+    apiDescription: "Write a new setpoint for line-3-furnace main-bus",
+    requestBody: {
+      description: "Setpoint payload",
+      required: true,
+      schema: {
+        type: "object",
+        required: ["value"],
+        properties: {
+          value: { type: "number", description: "Target setpoint value" },
+          unit:  { type: "string", description: "Unit of measurement, e.g. A" },
+        },
+      },
+    },
+  }
+);
+
+// ─── Event handlers ───────────────────────────────────────────────────────────
 
+/**
+ * Handle all GET requests.
+ * event.req is the Express Request; event.res is the Express Response.
+ * Use event.req.query for query parameters and event.req.appContext for UNS context.
+ */
 apiInput.event.on("apiGetEvent", (event: UnsEvents["apiGetEvent"]) => {
   try {
-    const appContext = event.req.appContext;
-    // Add SQL query or any other code here
-    event.res.send("OK");
+    // const { from, to, limit } = event.req.query;
+    // Add your data-fetching logic here (e.g. SQL query, time-series lookup)
+    event.res.json({ status: "ok", data: [] });
   } catch (error) {
-    event.res.status(400).send("Error");
-  }    
+    event.res.status(400).json({ error: "Bad request" });
+  }
 });
+
+/**
+ * Handle all POST requests.
+ * event.req.body contains the parsed JSON body (Express json() middleware is pre-configured).
+ */
+apiInput.event.on("apiPostEvent", (event: UnsEvents["apiPostEvent"]) => {
+  try {
+    const body = event.req.body as { value?: number; unit?: string };
+    // Add your write/command logic here
+    event.res.json({ status: "ok", received: body });
+  } catch (error) {
+    event.res.status(400).json({ error: "Bad request" });
+  }
+});
+
+// ─── NOTE: registerCatchAll ───────────────────────────────────────────────────
+//
+// registerCatchAll() is used ONLY by the uns-api-global microservice, which acts
+// as a catch-all gateway for an entire topic namespace. Regular microservices
+// do NOT call this — use get() / post() above for per-attribute endpoints.