@uns-kit/cli 2.0.51 → 2.0.53

package/dist/index.js

@@ -9,7 +9,7 @@ import process from "node:process";
 import readline from "node:readline/promises";
 import { promisify } from "node:util";
 import * as azdev from "azure-devops-node-api";
-import { generateAgentsMarkdown, generateServiceSpecMarkdown, readAndValidateServiceBundle, } from "./service-bundle.js";
+import { generateAgentsMarkdown, generateServiceSpecMarkdown, getServiceBundleOutputPublisherContracts, readAndValidateServiceBundle, } from "./service-bundle.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const require = createRequire(import.meta.url);
@@ -254,6 +254,7 @@ async function createProjectFromBundle(options) {
         allowExisting: options.allowExisting,
         templateName: bundle.scaffold.template,
     });
+    await writeBundlePublisherExample(targetDir, bundle);
     await applyTsBundleFeatures(targetDir, bundle);
     await writeServiceBundleArtifacts(targetDir, bundle, raw);
     printTsCreateSuccess(targetDir, result.packageName, initializedGitNextSteps(result.initializedGit, "pnpm run dev"));
@@ -277,8 +278,13 @@ async function scaffoldTsProject(projectName, targetDir, options = {}) {
     return { packageName, initializedGit };
 }
 async function applyTsBundleFeatures(targetDir, bundle) {
+    const appliedFeatures = new Set();
     for (const featureName of bundle.scaffold.features) {
-        const resolvedFeature = resolveConfigureFeatureName(featureName);
+        const resolvedFeature = resolveBundleConfigureFeatureName(featureName);
+        if (!resolvedFeature || appliedFeatures.has(resolvedFeature)) {
+            continue;
+        }
+        appliedFeatures.add(resolvedFeature);
         if (resolvedFeature === "devops") {
             await configureDevopsFromBundle(targetDir, bundle);
             continue;
@@ -305,6 +311,90 @@ async function configureDevopsFromBundle(targetDir, bundle) {
     });
     logDevopsResult(result, { includeRemoteDetails: false });
 }
+async function writeBundlePublisherExample(targetDir, bundle) {
+    const contracts = getServiceBundleOutputPublisherContracts(bundle);
+    if (!contracts.length) {
+        return;
+    }
+    await writeFile(path.join(targetDir, "src", "index.ts"), renderBundlePublisherExample(bundle, contracts), "utf8");
+}
+function renderBundlePublisherExample(bundle, contracts) {
+    const outputContracts = contracts.map((contract) => ({
+        fullPath: contract.fullPath,
+        topicPrefix: contract.pathParts.topicPrefix,
+        asset: contract.pathParts.asset,
+        objectType: contract.pathParts.objectType,
+        objectId: contract.pathParts.objectId,
+        attribute: contract.pathParts.attribute,
+        expectedIntervalMs: contract.expectedIntervalMs,
+    }));
+    const processName = JSON.stringify(bundle.metadata.name);
+    const contractJson = JSON.stringify(outputContracts, null, 2)
+        .split("\n")
+        .map((line) => `  ${line}`)
+        .join("\n")
+        .trimStart();
+    return `import { ConfigFile, UnsProxyProcess } from "@uns-kit/core";
+import type { ISO8601 } from "@uns-kit/core/uns/uns-interfaces.js";
+
+type OutputContract = {
+  fullPath: string;
+  topicPrefix: string;
+  asset: string;
+  objectType: string;
+  objectId: string;
+  attribute: string;
+  expectedIntervalMs: number;
+};
+
+const outputContracts = ${contractJson} satisfies readonly OutputContract[];
+
+function topicPrefixForPublish(topicPrefix: string): string {
+  return topicPrefix.endsWith("/") ? topicPrefix : \`\${topicPrefix}/\`;
+}
+
+async function main(): Promise<void> {
+  const config = await ConfigFile.loadConfig();
+  const processName = config.uns.processName ?? ${processName};
+  const unsProcess = new UnsProxyProcess(config.infra.host ?? "localhost", {
+    processName,
+  });
+
+  const mqttOutput = await unsProcess.createUnsMqttProxy(
+    config.output?.host ?? "localhost",
+    "defaultOutput",
+    config.uns.instanceMode ?? "wait",
+    config.uns.handover ?? true,
+  );
+
+  const time = new Date().toISOString() as ISO8601;
+
+  for (const output of outputContracts) {
+    await mqttOutput.publishMqttMessage({
+      topic: topicPrefixForPublish(output.topicPrefix),
+      asset: output.asset,
+      objectType: output.objectType,
+      objectId: output.objectId,
+      attributes: {
+        attribute: output.attribute,
+        description: \`Generated example publisher for \${output.fullPath}\`,
+        data: {
+          time,
+          value: 0,
+          dataGroup: "service-bundle-output",
+        },
+        validityMode: "interval",
+        expectedIntervalMs: output.expectedIntervalMs,
+      },
+    });
+  }
+
+  console.log(\`UNS process '\${processName}' published \${outputContracts.length} interval example output(s).\`);
+}
+
+void main();
+`;
+}
 async function writeServiceBundleArtifacts(targetDir, bundle, rawBundle) {
     await writeFile(path.join(targetDir, "service.bundle.json"), rawBundle, "utf8");
     await writeFile(path.join(targetDir, "SERVICE_SPEC.md"), generateServiceSpecMarkdown(bundle), "utf8");
@@ -1078,6 +1168,15 @@ function resolveConfigureFeatureName(input) {
     }
     return feature;
 }
+function resolveBundleConfigureFeatureName(input) {
+    if (typeof input === "string") {
+        const normalized = input.trim().toLowerCase();
+        if (normalized === "workspace" || normalized === "configure-workspace") {
+            return "vscode";
+        }
+    }
+    return resolveConfigureFeatureName(input);
+}
 async function ensureGitRepository(dir) {
     try {
         const { stdout } = await execFileAsync("git", ["rev-parse", "--is-inside-work-tree"], {

package/dist/service-bundle.d.ts

@@ -41,6 +41,20 @@ export type ServiceBundle = {
         };
     };
 };
+export type ServiceBundlePathParts = {
+    topicPrefix: string;
+    asset: string;
+    objectType: string;
+    objectId: string;
+    attribute: string;
+};
+export type ServiceBundlePublisherContract = {
+    mode: "uns-topic-publish";
+    fullPath: string;
+    pathParts: ServiceBundlePathParts;
+    validityMode: "interval";
+    expectedIntervalMs: number;
+};
 type ReadBundleOptions = {
     expectedStack: SupportedBundleStack;
     cliName: string;
@@ -52,4 +66,5 @@ export declare function readAndValidateServiceBundle(bundlePath: string, options
 }>;
 export declare function generateServiceSpecMarkdown(bundle: ServiceBundle): string;
 export declare function generateAgentsMarkdown(bundle: ServiceBundle): string;
+export declare function getServiceBundleOutputPublisherContracts(bundle: ServiceBundle): ServiceBundlePublisherContract[];
 export {};

package/dist/service-bundle.js

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+const DEFAULT_PUBLISHER_EXPECTED_INTERVAL_MS = 60_000;
 export async function readAndValidateServiceBundle(bundlePath, options) {
     const raw = await readFile(bundlePath, "utf8");
     const parsed = parseJsonObject(raw, bundlePath);
@@ -45,12 +46,17 @@ export function generateServiceSpecMarkdown(bundle) {
         ]));
     }
     if (bundle.domain) {
+        const outputPublisherContracts = getServiceBundleOutputPublisherContracts(bundle);
         lines.push("", "## Domain Inputs", ...renderUnknownList(bundle.domain.inputs), "", "## Domain Outputs", ...renderUnknownList(bundle.domain.outputs));
+        if (outputPublisherContracts.length) {
+            lines.push("", "## Output Publisher Contracts", ...outputPublisherContracts.map((contract) => `- ${contract.fullPath}: validityMode: "interval", expectedIntervalMs: ${contract.expectedIntervalMs}`));
+        }
     }
     lines.push("", "## Goals", ...renderStringList(bundle.docs.serviceSpec.goals), "", "## Non-Goals", ...renderStringList(bundle.docs.serviceSpec.nonGoals), "", "## Acceptance Criteria", ...renderStringList(bundle.docs.serviceSpec.acceptanceCriteria), "");
     return lines.join("\n");
 }
 export function generateAgentsMarkdown(bundle) {
+    const outputPublisherContracts = getServiceBundleOutputPublisherContracts(bundle);
     const lines = [
         "# AGENTS",
         "",
@@ -64,21 +70,89 @@ export function generateAgentsMarkdown(bundle) {
             ["Template", bundle.scaffold.template],
         ]),
         "",
-        "## Project Context",
-        ...renderStringList(bundle.docs.agents.projectContext),
-        "",
-        "## Guardrails",
-        ...renderStringList(bundle.docs.agents.guardrails),
-        "",
-        "## First Tasks",
-        ...renderStringList(bundle.docs.agents.firstTasks),
+        "## Bundle Source",
         "",
-        "## Verification",
-        ...renderStringList(bundle.docs.agents.verification),
+        "- 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.",
         "",
     ];
+    if (outputPublisherContracts.length) {
+        lines.push("## Output Publishing", ...outputPublisherContracts.flatMap((contract) => [
+            `- ${contract.fullPath} publishes interval data with validityMode: "interval" and expectedIntervalMs: ${contract.expectedIntervalMs}.`,
+            "- Do not publish interval attributes without both fields.",
+        ]), "");
+    }
+    lines.push("## Project Context", ...renderStringList(bundle.docs.agents.projectContext), "", "## Guardrails", ...renderStringList(bundle.docs.agents.guardrails), "", "## First Tasks", ...renderStringList(bundle.docs.agents.firstTasks), "", "## Verification", ...renderStringList(bundle.docs.agents.verification), "");
     return lines.join("\n");
 }
+export function getServiceBundleOutputPublisherContracts(bundle) {
+    const outputs = Array.isArray(bundle.domain?.outputs) ? bundle.domain.outputs : [];
+    return outputs
+        .map((output) => readOutputPublisherContract(output))
+        .filter((contract) => Boolean(contract));
+}
+function readOutputPublisherContract(output) {
+    if (!isRecord(output)) {
+        return null;
+    }
+    const rawPublisherContract = isRecord(output.publisherContract) ? output.publisherContract : null;
+    if (!rawPublisherContract) {
+        return null;
+    }
+    const mode = readOptionalString(rawPublisherContract.mode);
+    if (mode && mode !== "uns-topic-publish") {
+        return null;
+    }
+    const validityMode = readOptionalString(rawPublisherContract.validityMode);
+    if (validityMode && validityMode !== "interval") {
+        return null;
+    }
+    const fullPath = readOptionalString(rawPublisherContract.fullPath) ?? readOptionalString(output.topic);
+    const pathParts = readPathParts(rawPublisherContract.pathParts) ?? readPathParts(output.pathParts);
+    if (!fullPath || !pathParts) {
+        return null;
+    }
+    return {
+        mode: "uns-topic-publish",
+        fullPath,
+        pathParts,
+        validityMode: "interval",
+        expectedIntervalMs: readPositiveInteger(rawPublisherContract.expectedIntervalMs) ??
+            readPositiveInteger(output.expectedIntervalMs) ??
+            DEFAULT_PUBLISHER_EXPECTED_INTERVAL_MS,
+    };
+}
+function readPathParts(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const topicPrefix = readOptionalString(value.topicPrefix);
+    const asset = readOptionalString(value.asset);
+    const objectType = readOptionalString(value.objectType);
+    const objectId = readOptionalString(value.objectId);
+    const attribute = readOptionalString(value.attribute);
+    if (!topicPrefix || !asset || !objectType || !objectId || !attribute) {
+        return null;
+    }
+    return { topicPrefix, asset, objectType, objectId, attribute };
+}
+function readOptionalString(value) {
+    return typeof value === "string" && value.trim().length ? value.trim() : undefined;
+}
+function readPositiveInteger(value) {
+    const parsed = typeof value === "number"
+        ? value
+        : typeof value === "string" && value.trim().length
+            ? Number(value.trim())
+            : NaN;
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return undefined;
+    }
+    return Math.floor(parsed);
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
 function validateServiceBundle(value, options) {
     const schemaVersion = value.schemaVersion;
     if (schemaVersion !== 1) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uns-kit/cli",
-  "version": "2.0.51",
+  "version": "2.0.53",
   "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.51"
+    "@uns-kit/core": "2.0.53"
   },
   "unsKitPackages": {
-    "@uns-kit/core": "2.0.51",
-    "@uns-kit/api": "2.0.51",
-    "@uns-kit/cron": "2.0.51",
-    "@uns-kit/database": "2.0.51"
+    "@uns-kit/core": "2.0.53",
+    "@uns-kit/api": "2.0.53",
+    "@uns-kit/cron": "2.0.53",
+    "@uns-kit/database": "2.0.53"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/templates/config-files/config-localhost.json

@@ -19,13 +19,13 @@
     "password": "secret"
   },
   "infra": {
-    "host": "localhost:1883"
+    "host": "localhost"
   },
   "output": {
-    "host": "localhost:1883"
+    "host": "localhost"
   },
   "input": {
-    "host": "localhost:1883"
+    "host": "localhost"
   },
   "devops": {
     "provider": "azure-devops",

package/templates/default/src/index.ts

@@ -1,14 +1,23 @@
-import { UnsProxyProcess } from "@uns-kit/core";
+import { ConfigFile, UnsProxyProcess } from "@uns-kit/core";
+import type { ISO8601 } from "@uns-kit/core/uns/uns-interfaces.js";
 
 async function main(): Promise<void> {
-  const name = "__APP_NAME__";
-  const process = new UnsProxyProcess("localhost:1883", {
-    processName: name,
+  const config = await ConfigFile.loadConfig();
+  const processName = config.uns.processName ?? "__APP_NAME__";
+  const unsProcess = new UnsProxyProcess(config.infra.host ?? "localhost", {
+    processName,
   });
 
-  const proxy = await process.createMqttProxy("ts-output");
+  const mqttOutput = await unsProcess.createUnsMqttProxy(
+    config.output?.host ?? "localhost",
+    "defaultOutput",
+    config.uns.instanceMode ?? "wait",
+    config.uns.handover ?? true,
+  );
 
-  await proxy.publishMqttMessage({
+  const time = new Date().toISOString() as ISO8601;
+
+  await mqttOutput.publishMqttMessage({
     topic: "example/site/area/line/",
     asset: "demo-asset",
     objectType: "utility-resource",
@@ -17,9 +26,8 @@ async function main(): Promise<void> {
       attribute: "status",
       description: "Service startup marker",
       data: {
-        time: new Date().toISOString(),
+        time,
         value: "started",
-        uom: "state",
         dataGroup: "runtime",
       },
       validityMode: "lifecycle",
@@ -27,7 +35,7 @@ async function main(): Promise<void> {
     },
   });
 
-  console.log(`UNS process '${name}' is ready. Edit src/index.ts to add your logic.`);
+  console.log(`UNS process '${processName}' is ready. Edit src/index.ts to add your logic.`);
 }
 
 void main();