@uns-kit/core 2.0.68 → 2.0.69

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,312 +1,312 @@
-# @uns-kit/core
-
-Core utilities and runtime building blocks for Unified Namespace (UNS) applications. The package bundles the process lifecycle manager, MQTT integrations, gRPC gateway helpers, configuration tooling, and shared type definitions that power the UNS ecosystem.
-
-Note: Apps built with uns-kit are intended to be managed by the **UNS Datahub controller**.
-
-## uns-kit in context
-
-| Package | Description |
-| --- | --- |
-| [`@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/cli`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-cli) | CLI for scaffolding new UNS applications. |
-
-## Installation
-
-```bash
-pnpm add @uns-kit/core
-# or
-npm install @uns-kit/core
-```
-
-## Key concepts
-
-- **UnsProxyProcess** — the central runtime class. It manages the MQTT connection, plugin lifecycle, and the instance status topic. Plugins (`@uns-kit/api`, `@uns-kit/cron`) augment it with domain-specific proxy factories.
-- **UnsProxy** — base class extended by all plugin proxies. Tracks produced topics, API endpoints, and catch-all mappings; re-publishes them to the controller on a 60-second cadence.
-- **ConfigFile** — loads and validates `config.json` at startup. On a real server this file is provided by the UNS Datahub controller; in development you maintain it yourself.
-- **MQTT helpers** — resilient publishers, topic builders, throttled queues, and handover support.
-- **gRPC gateway** — infrastructure to bridge Python workers into the UNS message fabric.
-
-## Basic usage
-
-```ts
-import UnsProxyProcess from "@uns-kit/core/uns/uns-proxy-process";
-import { ConfigFile } from "@uns-kit/core";
-
-const config = await ConfigFile.loadConfig();
-
-// Connect to MQTT broker; processName identifies this service in the controller.
-const proc = new UnsProxyProcess(config.infra.host!, { processName: config.uns.processName });
-```
-
-Publish retained service metadata when a runtime should be discoverable by the
-controller as a core service, addon, or built-in capability:
-
-```ts
-await proc.publishServiceMetadata({
-  serviceId: "uns-bridge-mqtt",
-  kind: "addon",
-  addonId: "uns-bridge-mqtt",
-  capabilities: ["mqtt-source-browser", "runtime-mappings"],
-  apiRoutes: [
-    {
-      path: "/api/system/bridge/mqtt/runtime/service/bridge/health",
-      kind: "health",
-    },
-  ],
-});
-```
-
-The metadata is retained on
-`uns-infra/<package>/<version>/<processName>/service-metadata`. Controllers
-combine this identity/capability payload with live process telemetry and route
-health before marking a service healthy.
-
-Extend it with plugins:
-
-```ts
-import "@uns-kit/api";
-import "@uns-kit/cron";
-import { type UnsProxyProcessWithApi } from "@uns-kit/api";
-import { type UnsProxyProcessWithCron } from "@uns-kit/cron";
-
-const proc = new UnsProxyProcess(config.infra.host!, { processName: config.uns.processName })
-  as UnsProxyProcessWithApi & UnsProxyProcessWithCron;
-
-const api  = await proc.createApiProxy("my-service", { jwtSecret: "CHANGEME" });
-const cron = await proc.createCrontabProxy("*/5 * * * *", { event: "tick" });
-```
-
-## Datahub client (last value + history)
-
-`UnsClient` provides a minimal REST client for the UNS Datahub API, including batch last-value, single-topic catch-all history, and batch range endpoints. Prefer a long-lived service token if available; you can pass it directly and skip username/password auth.
-
-```ts
-import { UnsClient } from "@uns-kit/core";
-import { ConfigFile } from "@uns-kit/core";
-
-const config = await ConfigFile.loadConfig();
-
-const client = new UnsClient("https://datahub.example.com", {
-  token: process.env.UNS_SERVICE_TOKEN ?? config.uns.token,
-});
-
-const values = await client.lastValue([
-  "raw/data/line-1/motor/main/temperature",
-  "raw/data/line-1/motor/main/status",
-]);
-console.log(values);
-
-const data = await client.getAttributeData("sij/acroni/vv/hrm-furnace/equipment/pusher/output-quantity", {
-  from: "2026-05-07T11:17:01.157Z",
-  to: "2026-05-07T11:22:01.157Z",
-  table: "uns_sij_hrm_furnace_data",
-  aggregate: "last",
-  dedupe: false,
-});
-console.log(data?.toRecords());
-
-const customData = await client.getData("/projects/project-name/path-to-data/data", {
-  fromDate: "20260325",
-});
-console.log(await customData.json());
-
-const batchHistory = await client.history([
-  "sij/acroni/vv/hrm-furnace/equipment/zone-1/temperature",
-  "sij/acroni/vv/hrm-furnace/equipment/zone-2/temperature",
-], {
-  from: "2026-04-09T06:00:00Z",
-  to: "2026-04-09T07:00:00Z",
-  limit: 500,
-});
-console.log(batchHistory?.byTopic);
-```
-
-## Sub-Asset Publishing
-
-Sub-assets use the same publish fields as normal assets. Set `topic` to the full
-parent asset path and set `asset` to the leaf sub-asset:
-
-```ts
-await proxy.publishMqttMessage({
-  topic: "sij/acroni/jek/pp/",
-  asset: "furnace-1",
-  objectType: "material",
-  objectId: "main",
-  attributes: {
-    attribute: "daily-production",
-    data: {
-      time: new Date().toISOString(),
-      value: 42,
-      uom: "t",
-    },
-  },
-});
-```
-
-This publishes
-`sij/acroni/jek/pp/furnace-1/material/main/daily-production`. Consumers that
-persist the existing QuestDB identity columns should store
-`topic = "sij/acroni/jek/pp"` and `asset = "furnace-1"`. Do not use `dataGroup`
-for sub-asset hierarchy; it is storage/routing metadata.
-
-## Validity / Liveliness
-
-UNS attributes can declare how the controller decides whether they are live or stale; in most apps this is primarily used to drive UI liveliness/activity indicators. In app-level modeling we use two modes only:
-
-- `interval`: continuously refreshed values (stale after ~2× `expectedIntervalMs`)
-- `lifecycle`: event-driven activity that stays active until a defined end value (`lifecycleEndValue`)
-
-```ts
-await proxy.publishMqttMessage({
-  topic: "raw/data/",
-  asset: "line-1",
-  objectType: "motor",
-  objectId: "main",
-  attributes: {
-    attribute: "status",
-    data: { time: new Date().toISOString(), value: "RUNNING" },
-    validityMode: "lifecycle",
-    lifecycleEndValue: "STOPPED",
-  },
-});
-```
-
-## Counter Attributes
-
-Publish cumulative counters as raw counter state. Do not use producer-side
-delta modes for new code; `MessageMode.Delta`, `MessageMode.Both`, and gRPC
-`value_is_cumulative` are deprecated because producer memory is lost across
-service restarts. Datahub history APIs should calculate delta/rate from
-persisted rows.
-
-For a `Data` attribute, mark the series directly:
-
-```ts
-await proxy.publishMqttMessage({
-  topic: "raw/data/",
-  asset: "line-1",
-  objectType: "energy-resource",
-  objectId: "main",
-  attributes: {
-    attribute: "active-energy-total",
-    description: "Cumulative active energy counter",
-    valueType: "number",
-    presentationKind: "counter",
-    defaultAggregation: "last",
-    counterResetPolicy: "new-value",
-    data: {
-      time: new Date().toISOString(),
-      value: 12345.6,
-      uom: "kWh",
-      dataGroup: "metering",
-    },
-  },
-});
-```
-
-For a `Table` attribute, keep the table as the source row and mark chartable
-counter columns with `tableColumns`:
-
-```ts
-await proxy.publishMqttMessage({
-  topic: "raw/data/",
-  asset: "line-1",
-  objectType: "energy-resource",
-  objectId: "main",
-  attributes: {
-    attribute: "measurements",
-    description: "Metering table",
-    tableColumns: [
-      {
-        name: "active_energy_total",
-        valueType: "number",
-        presentationKind: "counter",
-        defaultAggregation: "last",
-        counterResetPolicy: "new-value",
-      },
-    ],
-    table: {
-      time: new Date().toISOString(),
-      dataGroup: "metering",
-      columns: [
-        { name: "active_energy_total", type: "double", value: 12345.6, uom: "kWh" },
-        { name: "power", type: "double", value: 42.1, uom: "kW" },
-      ],
-    },
-  },
-});
-```
-
-`dataGroup` is a storage/routing hint for consumers such as archivers. It is not
-part of the UNS identity path and is not the same as `objectType`. For example,
-an archiver may persist a `table` packet with `dataGroup: "metering"` into a
-separate physical table family while the UNS path still comes from
-`topic/asset/objectType/objectId/attribute`.
-
-## Sync UNS schema from the controller
-
-`sync-uns-schema` fetches the canonical UNS dictionary and measurements from the controller REST API and refreshes local JSON files and generated TypeScript artifacts.
-
-```bash
-# Run inside a generated microservice project:
-pnpm run sync-uns-schema
-
-# The controller URL is read from config.json (uns.rest) automatically.
-# You will be prompted for the bearer token if not set via env var.
-```
-
-Or with explicit options:
-
-```bash
-pnpm run sync-uns-schema --controller-url http://localhost:3200 --token <bearer-token>
-```
-
-**What it updates (inside a generated project):**
-- `uns-dictionary.json`
-- `uns-measurements.json`
-- `src/uns/uns-dictionary.generated.ts`
-- `src/uns/uns-measurements.generated.ts`
-
-**Options:**
-
-| Flag | Default | Description |
-|---|---|---|
-| `--controller-url` | from `config.json` `uns.rest` or `UNS_CONTROLLER_URL` | Controller base URL |
-| `--token` | interactive prompt or `UNS_CONTROLLER_TOKEN` | Admin bearer token |
-| `--status` | `active` | Dictionary filter: `active`, `draft`, `deprecated`, `all` |
-| `--dry-run` | — | Report changes without writing |
-| `--dictionary-only` | — | Skip measurements sync |
-| `--measurements-only` | — | Skip dictionary sync |
-| `--skip-generate` | — | Skip TS regeneration |
-| `--project-root <dir>` | auto-detect | Target project root |
-
-## Config schema generation
-
-Edit `src/config/project.config.extension.ts` inside your project and run:
-
-```bash
-pnpm run generate-config-schema
-```
-
-This regenerates `config.schema.json` and `src/config/app-config.ts`, keeping editor completions and runtime types in sync with your config extensions.
-
-## Infisical secret resolution
-
-- Looks for `INFISICAL_TOKEN` / `INFISICAL_PERSONAL_TOKEN`, then `/run/secrets/infisical_token`.
-- If unavailable, logs a warning and returns `default` (or `undefined` for `optional: true` secrets).
-- Required secrets throw with the original error message when Infisical is unreachable.
-- Call `resolveInfisicalConfig()` to inspect the resolved token/projectId/siteUrl.
-
-## Development
-
-```bash
-pnpm run typecheck   # type-check sources
-pnpm run build       # emit JS + declarations to dist/
-```
-
-## License
-
-MIT © Aljoša Vister
+# @uns-kit/core
+
+Core utilities and runtime building blocks for Unified Namespace (UNS) applications. The package bundles the process lifecycle manager, MQTT integrations, gRPC gateway helpers, configuration tooling, and shared type definitions that power the UNS ecosystem.
+
+Note: Apps built with uns-kit are intended to be managed by the **UNS Datahub controller**.
+
+## uns-kit in context
+
+| Package | Description |
+| --- | --- |
+| [`@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/cli`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-cli) | CLI for scaffolding new UNS applications. |
+
+## Installation
+
+```bash
+pnpm add @uns-kit/core
+# or
+npm install @uns-kit/core
+```
+
+## Key concepts
+
+- **UnsProxyProcess** — the central runtime class. It manages the MQTT connection, plugin lifecycle, and the instance status topic. Plugins (`@uns-kit/api`, `@uns-kit/cron`) augment it with domain-specific proxy factories.
+- **UnsProxy** — base class extended by all plugin proxies. Tracks produced topics, API endpoints, and catch-all mappings; re-publishes them to the controller on a 60-second cadence.
+- **ConfigFile** — loads and validates `config.json` at startup. On a real server this file is provided by the UNS Datahub controller; in development you maintain it yourself.
+- **MQTT helpers** — resilient publishers, topic builders, throttled queues, and handover support.
+- **gRPC gateway** — infrastructure to bridge Python workers into the UNS message fabric.
+
+## Basic usage
+
+```ts
+import UnsProxyProcess from "@uns-kit/core/uns/uns-proxy-process";
+import { ConfigFile } from "@uns-kit/core";
+
+const config = await ConfigFile.loadConfig();
+
+// Connect to MQTT broker; processName identifies this service in the controller.
+const proc = new UnsProxyProcess(config.infra.host!, { processName: config.uns.processName });
+```
+
+Publish retained service metadata when a runtime should be discoverable by the
+controller as a core service, addon, or built-in capability:
+
+```ts
+await proc.publishServiceMetadata({
+  serviceId: "uns-bridge-mqtt",
+  kind: "addon",
+  addonId: "uns-bridge-mqtt",
+  capabilities: ["mqtt-source-browser", "runtime-mappings"],
+  apiRoutes: [
+    {
+      path: "/api/system/bridge/mqtt/runtime/service/bridge/health",
+      kind: "health",
+    },
+  ],
+});
+```
+
+The metadata is retained on
+`uns-infra/<package>/<version>/<processName>/service-metadata`. Controllers
+combine this identity/capability payload with live process telemetry and route
+health before marking a service healthy.
+
+Extend it with plugins:
+
+```ts
+import "@uns-kit/api";
+import "@uns-kit/cron";
+import { type UnsProxyProcessWithApi } from "@uns-kit/api";
+import { type UnsProxyProcessWithCron } from "@uns-kit/cron";
+
+const proc = new UnsProxyProcess(config.infra.host!, { processName: config.uns.processName })
+  as UnsProxyProcessWithApi & UnsProxyProcessWithCron;
+
+const api  = await proc.createApiProxy("my-service", { jwtSecret: "CHANGEME" });
+const cron = await proc.createCrontabProxy("*/5 * * * *", { event: "tick" });
+```
+
+## Datahub client (last value + history)
+
+`UnsClient` provides a minimal REST client for the UNS Datahub API, including batch last-value, single-topic catch-all history, and batch range endpoints. Prefer a long-lived service token if available; you can pass it directly and skip username/password auth.
+
+```ts
+import { UnsClient } from "@uns-kit/core";
+import { ConfigFile } from "@uns-kit/core";
+
+const config = await ConfigFile.loadConfig();
+
+const client = new UnsClient("https://datahub.example.com", {
+  token: process.env.UNS_SERVICE_TOKEN ?? config.uns.token,
+});
+
+const values = await client.lastValue([
+  "raw/data/line-1/motor/main/temperature",
+  "raw/data/line-1/motor/main/status",
+]);
+console.log(values);
+
+const data = await client.getAttributeData("sij/acroni/vv/hrm-furnace/equipment/pusher/output-quantity", {
+  from: "2026-05-07T11:17:01.157Z",
+  to: "2026-05-07T11:22:01.157Z",
+  table: "uns_sij_hrm_furnace_data",
+  aggregate: "last",
+  dedupe: false,
+});
+console.log(data?.toRecords());
+
+const customData = await client.getData("/projects/project-name/path-to-data/data", {
+  fromDate: "20260325",
+});
+console.log(await customData.json());
+
+const batchHistory = await client.history([
+  "sij/acroni/vv/hrm-furnace/equipment/zone-1/temperature",
+  "sij/acroni/vv/hrm-furnace/equipment/zone-2/temperature",
+], {
+  from: "2026-04-09T06:00:00Z",
+  to: "2026-04-09T07:00:00Z",
+  limit: 500,
+});
+console.log(batchHistory?.byTopic);
+```
+
+## Sub-Asset Publishing
+
+Sub-assets use the same publish fields as normal assets. Set `topic` to the full
+parent asset path and set `asset` to the leaf sub-asset:
+
+```ts
+await proxy.publishMqttMessage({
+  topic: "sij/acroni/jek/pp/",
+  asset: "furnace-1",
+  objectType: "material",
+  objectId: "main",
+  attributes: {
+    attribute: "daily-production",
+    data: {
+      time: new Date().toISOString(),
+      value: 42,
+      uom: "t",
+    },
+  },
+});
+```
+
+This publishes
+`sij/acroni/jek/pp/furnace-1/material/main/daily-production`. Consumers that
+persist the existing QuestDB identity columns should store
+`topic = "sij/acroni/jek/pp"` and `asset = "furnace-1"`. Do not use `dataGroup`
+for sub-asset hierarchy; it is storage/routing metadata.
+
+## Validity / Liveliness
+
+UNS attributes can declare how the controller decides whether they are live or stale; in most apps this is primarily used to drive UI liveliness/activity indicators. In app-level modeling we use two modes only:
+
+- `interval`: continuously refreshed values (stale after ~2× `expectedIntervalMs`)
+- `lifecycle`: event-driven activity that stays active until a defined end value (`lifecycleEndValue`)
+
+```ts
+await proxy.publishMqttMessage({
+  topic: "raw/data/",
+  asset: "line-1",
+  objectType: "motor",
+  objectId: "main",
+  attributes: {
+    attribute: "status",
+    data: { time: new Date().toISOString(), value: "RUNNING" },
+    validityMode: "lifecycle",
+    lifecycleEndValue: "STOPPED",
+  },
+});
+```
+
+## Counter Attributes
+
+Publish cumulative counters as raw counter state. Do not use producer-side
+delta modes for new code; `MessageMode.Delta`, `MessageMode.Both`, and gRPC
+`value_is_cumulative` are deprecated because producer memory is lost across
+service restarts. Datahub history APIs should calculate delta/rate from
+persisted rows.
+
+For a `Data` attribute, mark the series directly:
+
+```ts
+await proxy.publishMqttMessage({
+  topic: "raw/data/",
+  asset: "line-1",
+  objectType: "energy-resource",
+  objectId: "main",
+  attributes: {
+    attribute: "active-energy-total",
+    description: "Cumulative active energy counter",
+    valueType: "number",
+    presentationKind: "counter",
+    defaultAggregation: "last",
+    counterResetPolicy: "new-value",
+    data: {
+      time: new Date().toISOString(),
+      value: 12345.6,
+      uom: "kWh",
+      dataGroup: "metering",
+    },
+  },
+});
+```
+
+For a `Table` attribute, keep the table as the source row and mark chartable
+counter columns with `tableColumns`:
+
+```ts
+await proxy.publishMqttMessage({
+  topic: "raw/data/",
+  asset: "line-1",
+  objectType: "energy-resource",
+  objectId: "main",
+  attributes: {
+    attribute: "measurements",
+    description: "Metering table",
+    tableColumns: [
+      {
+        name: "active_energy_total",
+        valueType: "number",
+        presentationKind: "counter",
+        defaultAggregation: "last",
+        counterResetPolicy: "new-value",
+      },
+    ],
+    table: {
+      time: new Date().toISOString(),
+      dataGroup: "metering",
+      columns: [
+        { name: "active_energy_total", type: "double", value: 12345.6, uom: "kWh" },
+        { name: "power", type: "double", value: 42.1, uom: "kW" },
+      ],
+    },
+  },
+});
+```
+
+`dataGroup` is a storage/routing hint for consumers such as archivers. It is not
+part of the UNS identity path and is not the same as `objectType`. For example,
+an archiver may persist a `table` packet with `dataGroup: "metering"` into a
+separate physical table family while the UNS path still comes from
+`topic/asset/objectType/objectId/attribute`.
+
+## Sync UNS schema from the controller
+
+`sync-uns-schema` fetches the canonical UNS dictionary and measurements from the controller REST API and refreshes local JSON files and generated TypeScript artifacts.
+
+```bash
+# Run inside a generated microservice project:
+pnpm run sync-uns-schema
+
+# The controller URL is read from config.json (uns.rest) automatically.
+# You will be prompted for the bearer token if not set via env var.
+```
+
+Or with explicit options:
+
+```bash
+pnpm run sync-uns-schema --controller-url http://localhost:3200 --token <bearer-token>
+```
+
+**What it updates (inside a generated project):**
+- `uns-dictionary.json`
+- `uns-measurements.json`
+- `src/uns/uns-dictionary.generated.ts`
+- `src/uns/uns-measurements.generated.ts`
+
+**Options:**
+
+| Flag | Default | Description |
+|---|---|---|
+| `--controller-url` | from `config.json` `uns.rest` or `UNS_CONTROLLER_URL` | Controller base URL |
+| `--token` | interactive prompt or `UNS_CONTROLLER_TOKEN` | Admin bearer token |
+| `--status` | `active` | Dictionary filter: `active`, `draft`, `deprecated`, `all` |
+| `--dry-run` | — | Report changes without writing |
+| `--dictionary-only` | — | Skip measurements sync |
+| `--measurements-only` | — | Skip dictionary sync |
+| `--skip-generate` | — | Skip TS regeneration |
+| `--project-root <dir>` | auto-detect | Target project root |
+
+## Config schema generation
+
+Edit `src/config/project.config.extension.ts` inside your project and run:
+
+```bash
+pnpm run generate-config-schema
+```
+
+This regenerates `config.schema.json` and `src/config/app-config.ts`, keeping editor completions and runtime types in sync with your config extensions.
+
+## Infisical secret resolution
+
+- Looks for `INFISICAL_TOKEN` / `INFISICAL_PERSONAL_TOKEN`, then `/run/secrets/infisical_token`.
+- If unavailable, logs a warning and returns `default` (or `undefined` for `optional: true` secrets).
+- Required secrets throw with the original error message when Infisical is unreachable.
+- Call `resolveInfisicalConfig()` to inspect the resolved token/projectId/siteUrl.
+
+## Development
+
+```bash
+pnpm run typecheck   # type-check sources
+pnpm run build       # emit JS + declarations to dist/
+```
+
+## License
+
+MIT © Aljoša Vister