@devkong/cli 0.0.67-alpha.1 → 0.0.67-alpha.10

package/assets/python-install.bat

@@ -1,28 +1,28 @@
-@echo off
-
-set EXTENSION_DIR=%1
-echo %EXTENSION_DIR%
-
-where python >nul 2>&1
-if %errorlevel% equ 0 (
-    set PYTHON_CMD=python
-) else (
-    set PYTHON_CMD=python3
-)
-
-where pip >nul 2>&1
-if %errorlevel% equ 0 (
-    set PIP_CMD=pip
-) else (
-    set PIP_CMD=pip3
-)
-
-cd %EXTENSION_DIR%
-
-%PYTHON_CMD% -m venv .venv
-
-call .venv\Scripts\activate.bat
-
-%PIP_CMD% freeze > requirements-lock.txt
-%PIP_CMD% install --default-timeout=120 -r requirements.txt -r requirements-dev.txt
-%PIP_CMD% freeze > requirements-lock.txt
+@echo off
+
+set EXTENSION_DIR=%1
+echo %EXTENSION_DIR%
+
+where python >nul 2>&1
+if %errorlevel% equ 0 (
+    set PYTHON_CMD=python
+) else (
+    set PYTHON_CMD=python3
+)
+
+cd %EXTENSION_DIR%
+
+REM Recreate the venv from scratch so a stale interpreter path (e.g. left over
+REM after a Python upgrade or a moved/copied project) can't leave pip pointing
+REM at a missing binary.
+%PYTHON_CMD% -m venv --clear .venv
+if errorlevel 1 exit /b 1
+
+call .venv\Scripts\activate.bat
+
+REM Invoke pip via `python -m pip` rather than the pip/pip3 wrapper so we don't
+REM depend on the wrapper script's (possibly stale) shebang.
+python -m pip freeze > requirements-lock.txt
+python -m pip install --default-timeout=120 -r requirements.txt -r requirements-dev.txt
+if errorlevel 1 exit /b 1
+python -m pip freeze > requirements-lock.txt

package/assets/python-install.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -e
 
 EXTENSION_DIR=$1
 
@@ -8,18 +9,17 @@ else
     PYTHON_CMD="python3"
 fi
 
-if [ -x "$(command -v python)" ]; then
-    PIP_CMD="pip"
-else
-    PIP_CMD="pip3"
-fi
-
 cd "$EXTENSION_DIR" || exit
 
-$PYTHON_CMD -m venv .venv
+# Recreate the venv from scratch so a stale interpreter path (e.g. left over
+# after a Python/nvm/pyenv upgrade) can't leave pip pointing at a missing
+# binary, which fails with "cannot execute: required file not found".
+$PYTHON_CMD -m venv --clear .venv
 
 source .venv/bin/activate
 
-$PIP_CMD freeze > requirements-lock.txt
-$PIP_CMD install --default-timeout=120 -r requirements-dev.txt -r requirements.txt
-$PIP_CMD freeze > requirements-lock.txt
+# Invoke pip via `python -m pip` rather than the pip/pip3 wrapper so we don't
+# depend on the wrapper script's (possibly stale) shebang.
+python -m pip freeze > requirements-lock.txt
+python -m pip install --default-timeout=120 -r requirements-dev.txt -r requirements.txt
+python -m pip freeze > requirements-lock.txt

package/index.js

@@ -60750,10 +60750,8 @@ async function spawnCommand(commandText, logger = null, shell = false) {
 }
 async function spawnCommandWithArgs(command, commandArgs, logger = null, shell = false) {
   return new Promise((resolve2, reject) => {
-    const child = (0, import_child_process.spawn)(command, commandArgs, {
-      shell: shell || process.platform !== "win32",
-      stdio: ["pipe", "pipe", "pipe"]
-    });
+    const useShell = shell || process.platform !== "win32";
+    const child = useShell ? (0, import_child_process.spawn)([command, ...commandArgs].join(" "), { shell: true, stdio: ["pipe", "pipe", "pipe"] }) : (0, import_child_process.spawn)(command, commandArgs, { shell: false, stdio: ["pipe", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
     child.stdout.on("data", (data) => {
@@ -60797,13 +60795,6 @@ function printError(message2, error) {
 function escapePathSpaces(sourcePath) {
   return sourcePath.indexOf(" ") <= 0 ? sourcePath : `"${sourcePath}"`;
 }
-function renderProgressBar(elapsedSeconds, timeoutSeconds, status) {
-  const width = 24;
-  const ratio = timeoutSeconds > 0 ? Math.min(1, elapsedSeconds / timeoutSeconds) : 0;
-  const filled = Math.round(width * ratio);
-  const bar = "\u2588".repeat(filled) + "\u2591".repeat(width - filled);
-  return `[${bar}] ${elapsedSeconds}s / ${timeoutSeconds}s \xB7 ${status}`;
-}
 
 // packages/kong-cli/src/common/profile.ts
 var KONG_CONFIG_DIR = import_path3.default.join((0, import_os.homedir)(), ".kong");
@@ -60854,14 +60845,14 @@ var ConfigureCommand = class {
     const { profileName } = await dist_default14.prompt({
       type: "select",
       name: "profileName",
-      message: "Select a profile to configure:",
+      message: "select a profile to configure:",
       choices: [...profileNames, "Create a new profile"]
     });
     if (profileName === "Create a new profile") {
       const { newProfileName } = await dist_default14.prompt({
         type: "input",
         name: "newProfileName",
-        message: "Enter name for the new profile:",
+        message: "enter name for the new profile:",
         validate: (input) => profileNames.includes(input) ? "Profile already exists!" : true
       });
       return [newProfileName, createEmptyProfile()];
@@ -60872,20 +60863,20 @@ var ConfigureCommand = class {
     const answerUrl = await dist_default14.prompt({
       type: "input",
       name: "kongUrl",
-      message: `Enter URL for profile "${name}":`,
+      message: `enter URL for profile "${name}":`,
       default: profile.kongBaseUrl
     });
     const answerUserName = await dist_default14.prompt({
       type: "input",
       name: "userName",
-      message: `Enter user name for profile "${name}":`,
+      message: `enter user name for profile "${name}":`,
       default: profile.userName
     });
     const answerPassword = await dist_default14.prompt({
       type: "password",
       name: "password",
       mask: "*",
-      message: `Enter password for user "${answerUserName.userName}":`,
+      message: `enter password for user "${answerUserName.userName}":`,
       default: ""
     });
     const updated = {
@@ -60897,7 +60888,7 @@ var ConfigureCommand = class {
       const entry = new import_keyring.Entry(updated.kongBaseUrl, updated.userName);
       entry.setPassword(answerPassword.password);
     }
-    console.log(`Configuration for profile "${name}" has been updated`);
+    console.log(`configuration for profile "${name}" has been updated`);
     return updated;
   }
 };
@@ -62932,7 +62923,7 @@ var InstallCommand = class {
   async execute(workspaceDirectory) {
     await new Listr([
       {
-        title: "Installing dependencies with pip",
+        title: "installing dependencies with pip",
         task: async (_2, task) => {
           const scriptPath = this.scriptPath();
           await spawnCommandWithArgs(
@@ -63103,12 +63094,12 @@ var ManagementClient = class {
     const url2 = joinUrlAndPath(this.baseUrl, "v1/extensions", extensionId, "/aliases");
     return (await axios_default.get(url2, await this.requestConfigProvider())).data;
   }
-  async getAuditLog(objectType2, objectId) {
+  async getAuditLog(objectType2, objectId, createdAfter) {
     const url2 = joinUrlAndPath(this.baseUrl, "v1/audit");
     const config = await this.requestConfigProvider();
     const response = await axios_default.get(url2, {
       ...config,
-      params: { ...config.params, objectType: objectType2, objectId }
+      params: { ...config.params, objectType: objectType2, objectId, createdAfter }
     });
     return response.data;
   }
@@ -63128,17 +63119,19 @@ var ListAliasesCommand = class {
     await new Listr(
       [
         {
-          title: "List extension aliases",
+          title: "list extension aliases",
           task: async (ctx, task) => {
             const kongJson = getKongJson();
             const aliases = await this.managementClient.getExtensionSnapshotAliases(kongJson.id);
             if (aliases.length === 0) {
-              task.output = "No aliases available";
+              task.output = "no aliases available";
             } else {
               const result = [];
               for (const alias of aliases) {
                 for (const item of alias.use) {
-                  result.push(`${alias.name}, ${item.snapshot.version}, ${item.balance}%`);
+                  result.push(
+                    `${alias.name}, ${item.snapshot.version}, ${item.balance ? `${item.balance}%` : "shadow"}`
+                  );
                 }
               }
               task.output = result.join("\n");
@@ -63174,12 +63167,12 @@ var ListVersionsCommand = class {
     await new Listr(
       [
         {
-          title: "List extension snapshot versions",
+          title: "list extension snapshot versions",
           task: async (ctx, task) => {
             const kongJson = getKongJson();
             const versions = await this.managementClient.getExtensionSnapshotVersions(kongJson.id);
             if (versions.length === 0) {
-              task.output = "No versions available";
+              task.output = "no versions available";
             } else {
               const result = [];
               for (const ver of versions) {
@@ -63270,7 +63263,7 @@ var PublishVersionCommand = class {
     const kongJson = getKongJson();
     if (kongJson.sdk === "kotlin" && !this.contractPath) {
       yield {
-        title: "Build extension",
+        title: "build extension",
         task: async (ctx, task) => {
           const logger = new ListrTaskLogger(task, this.verbose ? 3 /* DEBUG */ : 0 /* INFO */);
           const cmdText = this.getKotlinBuildCmdTask();
@@ -63281,7 +63274,7 @@ var PublishVersionCommand = class {
       };
     }
     yield {
-      title: "Generate schema",
+      title: "generate schema",
       task: async (ctx, task) => {
         const logger = new ListrTaskLogger(task, this.verbose ? 3 /* DEBUG */ : 0 /* INFO */);
         if (this.contractPath) {
@@ -63296,13 +63289,13 @@ var PublishVersionCommand = class {
       rendererOptions: this.defaultRendererOptions
     };
     yield {
-      title: "Get publish details",
+      title: "get publish details",
       task: async (ctx) => {
         ctx.publishDetails = await this.registryClient.getPublishDetails(appName);
       }
     };
     yield {
-      title: "Docker login",
+      title: "docker login",
       task: async (ctx, task) => {
         const publishDetails = ctx.publishDetails;
         const regUrl = this.resolveRegistryUrl(publishDetails.repoName);
@@ -63314,7 +63307,7 @@ var PublishVersionCommand = class {
       rendererOptions: this.defaultRendererOptions
     };
     yield {
-      title: "Docker build",
+      title: "docker build",
       task: async (ctx, task) => {
         const publishDetails = ctx.publishDetails;
         const regUrl = this.resolveRegistryUrl(publishDetails.repoName);
@@ -63327,7 +63320,7 @@ var PublishVersionCommand = class {
       rendererOptions: this.defaultRendererOptions
     };
     yield {
-      title: "Docker push",
+      title: "docker push",
       task: async (ctx, task) => {
         const cmd = this.dockerPushCmdText(ctx.fullImageName);
         await spawnCommand(
@@ -63338,7 +63331,7 @@ var PublishVersionCommand = class {
       rendererOptions: this.defaultRendererOptions
     };
     yield {
-      title: "Save publish details",
+      title: "save publish details",
       task: async (ctx, task) => {
         const publishDetails = ctx.publishDetails;
         let autoGeneratedContract;
@@ -63407,7 +63400,7 @@ var PublishVersionCommand = class {
         });
         await this.managementClient.createExtensionSnapshot(kongJson.id, snapshot);
         task.output = [
-          `The version ${publishDetails.imageVersion} has been successfully published!`,
+          `the version ${publishDetails.imageVersion} has been successfully published!`,
           joinUrlAndPath(this.profile.kongBaseUrl, "/extensions/aliases")
         ].join("\n");
       },
@@ -63441,7 +63434,7 @@ var PublishVersionCommand = class {
 
 // packages/kong-cli/src/common/deployment.ts
 var DEPLOY_SUCCESS_ACTIONS = /* @__PURE__ */ new Set(["deployment completed"]);
-var DEPLOY_FAILURE_ACTIONS = /* @__PURE__ */ new Set(["deployment failed", "save deployment details"]);
+var DEPLOY_FAILURE_ACTIONS = /* @__PURE__ */ new Set(["deployment failed"]);
 function isFailureEvent(event) {
   return event.eventType === "error" || DEPLOY_FAILURE_ACTIONS.has(event.action);
 }
@@ -63462,24 +63455,42 @@ function analyzeDeployment(events) {
 }
 async function getDeploymentLog(management, query) {
   const [aliasEvents, baseEvents] = await Promise.all([
-    management.getAuditLog(query.objectType, `${query.basedOnId}-${query.aliasName}`),
-    management.getAuditLog(query.objectType, query.basedOnId)
+    management.getAuditLog(
+      query.objectType,
+      `${query.basedOnId}-${query.aliasName}`,
+      query.createdAfter
+    ),
+    management.getAuditLog(query.objectType, query.basedOnId, query.createdAfter)
   ]);
   return [...aliasEvents, ...baseEvents].sort((a, b) => b.created.localeCompare(a.created));
 }
+function deploymentErrorMessage(events) {
+  const failure = events.find(isFailureEvent);
+  if (!failure) {
+    return "Deployment failed.";
+  }
+  const data = failure.eventData;
+  const detail = typeof data?.message === "string" ? data.message : typeof data?.error === "string" ? data.error : void 0;
+  return detail ? `${failure.action}: ${detail}` : failure.action;
+}
 var sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
 async function pollDeployment(management, input) {
   const interval = input.intervalMs ?? 2e3;
   const startedAt = Date.now();
   const deadline = startedAt + input.timeoutSeconds * 1e3;
   const elapsed = () => Math.min(input.timeoutSeconds, Math.round((Date.now() - startedAt) / 1e3));
-  const report = (status) => input.onProgress?.({ status, elapsedSeconds: elapsed(), timeoutSeconds: input.timeoutSeconds });
+  const report = (current) => input.onProgress?.({
+    status: current.status,
+    events: current.events,
+    elapsedSeconds: elapsed(),
+    timeoutSeconds: input.timeoutSeconds
+  });
   let result = analyzeDeployment(await getDeploymentLog(management, input));
-  report(result.status);
+  report(result);
   while (!result.terminal && Date.now() < deadline) {
     await sleep(interval);
     result = analyzeDeployment(await getDeploymentLog(management, input));
-    report(result.status);
+    report(result);
   }
   return {
     ...result,
@@ -63511,6 +63522,24 @@ function validateName(value) {
     );
   }
 }
+var DEPLOY_STEPS = [
+  "create deployment",
+  "save deployment details",
+  "deployment completed"
+];
+function createDeploySteps() {
+  return DEPLOY_STEPS.map((action) => {
+    const handlers = {
+      resolve: () => void 0,
+      reject: () => void 0
+    };
+    const done = new Promise((resolve2, reject) => {
+      handlers.resolve = resolve2;
+      handlers.reject = reject;
+    });
+    return { action, done, settle: (error) => error ? handlers.reject(error) : handlers.resolve() };
+  });
+}
 var SetAliasCommand = class {
   constructor(profile) {
     this.profile = profile;
@@ -63520,10 +63549,12 @@ var SetAliasCommand = class {
   }
   async execute(aliasName, extensionVersion, timeoutSeconds) {
     validateName(aliasName);
+    const startedAt = utcNow(DEFAULT_TIMEZONE);
+    const steps = createDeploySteps();
     await new Listr(
       [
         {
-          title: "Get snapshot details",
+          title: "get snapshot details",
           task: async (ctx, task) => {
             ctx.kongJson = getKongJson();
             ctx.snapshot = await this.managementClient.getExtensionSnapshot(
@@ -63536,7 +63567,7 @@ var SetAliasCommand = class {
           }
         },
         {
-          title: "Assign extension alias",
+          title: "assign extension alias",
           task: async (ctx, task) => {
             const now = utcNow(DEFAULT_TIMEZONE);
             const aliasUse = {
@@ -63566,45 +63597,12 @@ var SetAliasCommand = class {
               updatedBy: ""
             };
             await this.publicClient.assignExtensionAlias(ctx.kongJson.id, alias);
-            task.output = [
-              "Please wait a moment for it to appear in the UI",
-              joinUrlAndPath(this.profile.kongBaseUrl, "/extensions/aliases")
-            ].join("\n");
+            this.pollDeploymentSteps(steps, ctx.kongJson.id, aliasName, startedAt, timeoutSeconds);
           },
           rendererOptions: { persistentOutput: true }
         },
-        {
-          title: "Wait for deployment",
-          task: async (ctx, task) => {
-            let status = "pending";
-            const startedAt = Date.now();
-            const render = () => {
-              const elapsed = Math.min(timeoutSeconds, Math.round((Date.now() - startedAt) / 1e3));
-              task.output = renderProgressBar(elapsed, timeoutSeconds, status);
-            };
-            render();
-            const ticker = setInterval(render, 1e3);
-            try {
-              const result = await pollDeployment(this.managementClient, {
-                objectType: "extension_alias" /* EXTENSION_ALIAS */,
-                basedOnId: ctx.kongJson.id,
-                aliasName,
-                timeoutSeconds,
-                onProgress: (progress) => {
-                  status = progress.status;
-                  render();
-                }
-              });
-              if (result.status === "failed") {
-                throw new AppError("Deployment failed. Check the alias logs in the UI.");
-              }
-              task.output = result.timedOut ? `Still deploying after ${result.waitedSeconds}s \u2014 check the UI for completion.` : `Deployment ${result.status} in ${result.waitedSeconds}s.`;
-            } finally {
-              clearInterval(ticker);
-            }
-          },
-          rendererOptions: { persistentOutput: true }
-        }
+        // Known deployment steps as a checklist; each ticks off on its event.
+        ...steps.map((step) => ({ title: step.action, task: () => step.done }))
       ],
       {
         renderer: "default",
@@ -63616,6 +63614,47 @@ var SetAliasCommand = class {
       }
     ).run();
   }
+  /**
+   * Poll the deployment audit log and settle one step per matching event. Runs
+   * detached from the task list; it settles a step as its event arrives and
+   * fails the rest on a failed/timed-out deployment, stopping on the failed or
+   * "deployment completed" event (poll terminal).
+   */
+  pollDeploymentSteps(steps, basedOnId, aliasName, createdAfter, timeoutSeconds) {
+    const pending = new Map(steps.map((step) => [step.action, step]));
+    const seen = /* @__PURE__ */ new Set();
+    void pollDeployment(this.managementClient, {
+      objectType: "EXTENSION_ALIAS",
+      basedOnId,
+      aliasName,
+      createdAfter,
+      timeoutSeconds,
+      onProgress: (progress) => {
+        for (const event of [...progress.events].reverse()) {
+          if (seen.has(event.action)) {
+            continue;
+          }
+          seen.add(event.action);
+          pending.get(event.action)?.settle();
+        }
+      }
+    }).then((result) => {
+      if (result.status === "failed") {
+        const error = new AppError(deploymentErrorMessage(result.events));
+        steps.forEach((step) => step.settle(error));
+      } else if (result.timedOut) {
+        const error = new AppError(
+          `Still deploying after ${result.waitedSeconds}s \u2014 check the UI for completion.`
+        );
+        steps.forEach((step) => step.settle(error));
+      } else {
+        steps.forEach((step) => step.settle());
+      }
+    }).catch((error) => {
+      const wrapped = error instanceof Error ? error : new AppError(String(error));
+      steps.forEach((step) => step.settle(wrapped));
+    });
+  }
 };
 
 // packages/kong-cli/src/common/cli.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devkong/cli",
-  "version": "0.0.67-alpha.1",
+  "version": "0.0.67-alpha.10",
   "type": "commonjs",
   "main": "./index.js",
   "typings": "./index.d.ts",

package/packages/kong-cli/src/commands/setAliasCommand.d.ts

@@ -5,4 +5,11 @@ export declare class SetAliasCommand {
     private managementClient;
     constructor(profile: Profile);
     execute(aliasName: string, extensionVersion: number, timeoutSeconds: number): Promise<void>;
+    /**
+     * Poll the deployment audit log and settle one step per matching event. Runs
+     * detached from the task list; it settles a step as its event arrives and
+     * fails the rest on a failed/timed-out deployment, stopping on the failed or
+     * "deployment completed" event (poll terminal).
+     */
+    private pollDeploymentSteps;
 }

package/packages/kong-cli/src/common/deployment.d.ts

@@ -1,12 +1,19 @@
-import { AppAuditLog, AuditObjectType } from "@kong/contract";
+import { AppAuditLog } from "@kong/contract";
 import { Loading } from "@kong/ts";
 import { ManagementClient } from "../services/managementClient";
-/** Audit object types that carry a deployment trail. */
-export type DeployObjectType = AuditObjectType.EXTENSION_ALIAS | AuditObjectType.PROCESS_ALIAS;
+/**
+ * Audit object types that carry a deployment trail. These are the management
+ * `AuditObjectType` JVM enum *constant names* (not the `extension_alias` JSON
+ * wire value): the `/v1/audit` `objectType` query param is resolved server-side
+ * via `Enum.valueOf`, which matches the constant name.
+ */
+export type DeployObjectType = "EXTENSION_ALIAS" | "PROCESS_ALIAS";
 export interface DeploymentQuery {
     objectType: DeployObjectType;
     basedOnId: string;
     aliasName: string;
+    /** Only fetch audit events created at/after this UTC timestamp (ISO-8601). */
+    createdAfter?: string;
 }
 export interface DeploymentResult {
     /**
@@ -31,9 +38,17 @@ export declare function analyzeDeployment(events: AppAuditLog[]): DeploymentResu
  * `basedOnId`, so both object ids are fetched and merged newest-first.
  */
 export declare function getDeploymentLog(management: ManagementClient, query: DeploymentQuery): Promise<AppAuditLog[]>;
+/**
+ * Best-effort human-readable reason for a failed deployment, pulled from the
+ * first failure event's `eventData` (falling back to its action label) so the
+ * actual backend error can be surfaced to the console.
+ */
+export declare function deploymentErrorMessage(events: AppAuditLog[]): string;
 export interface PollProgress {
     /** Latest analyzed deployment status. */
     status: Loading;
+    /** Full deployment audit log analyzed so far, newest first. */
+    events: AppAuditLog[];
     /** Seconds elapsed since polling started (capped at `timeoutSeconds`). */
     elapsedSeconds: number;
     /** The configured deploy-wait budget. */

package/packages/kong-cli/src/common/utils.d.ts

@@ -1,4 +1,4 @@
-import { Loading, Optional, ShortUUID } from "@kong/ts";
+import { Optional, ShortUUID } from "@kong/ts";
 export interface ILogger {
     info(message: string): void;
     debug(message: string): void;
@@ -14,5 +14,3 @@ export declare function spawnCommand(commandText: string, logger?: ILogger | nul
 export declare function spawnCommandWithArgs(command: string, commandArgs: string[], logger?: ILogger | null, shell?: boolean): Promise<string>;
 export declare function printError(message: string, error: unknown): void;
 export declare function escapePathSpaces(sourcePath: string): string;
-/** Render a fixed-width textual progress bar for live task output. */
-export declare function renderProgressBar(elapsedSeconds: number, timeoutSeconds: number, status: Loading): string;

package/packages/kong-cli/src/services/managementClient.d.ts

@@ -1,5 +1,6 @@
-import { AppAuditLog, AppExtension, AppExtensionAlias, AppSnapshot, AppSnapshotDetails, AuditObjectType } from "@kong/contract";
+import { AppAuditLog, AppExtension, AppExtensionAlias, AppSnapshot, AppSnapshotDetails } from "@kong/contract";
 import { Optional, UrlText } from "@kong/ts";
+import { DeployObjectType } from "../common/deployment";
 import { RequestConfigProvider } from "./api";
 export declare class ManagementClient {
     private requestConfigProvider;
@@ -10,5 +11,5 @@ export declare class ManagementClient {
     getExtensionSnapshot(extensionId: AppExtension["id"], extensionSnapshotVersion: AppSnapshot["version"]): Promise<Optional<AppSnapshotDetails>>;
     getExtensionSnapshotVersions(extensionId: AppExtension["id"]): Promise<AppSnapshot[]>;
     getExtensionSnapshotAliases(extensionId: AppExtension["id"]): Promise<AppExtensionAlias[]>;
-    getAuditLog(objectType: AuditObjectType, objectId: string): Promise<AppAuditLog[]>;
+    getAuditLog(objectType: DeployObjectType, objectId: string, createdAfter?: string): Promise<AppAuditLog[]>;
 }

package/packages/kong-spec/src/index.d.ts

@@ -1,7 +1,7 @@
 export { makeServerlessJavaAppProps, serverlessFlowBuilder, stringifyServerlessFlow, } from "./lib/kongServerless";
 export type { FloweyServerlessBuilder } from "./lib/kongServerless";
 export type { KongSpecJobSession } from "./lib/kongSession";
-export type { KongSpecAction, KongSpecActionCallFunction, KongSpecActionCallProcess, KongSpecActionDelay, KongSpecActionInject, KongSpecActionSendEvent, KongSpecAnnotation, KongSpecBranch, KongSpecCache, KongSpecCallModel, KongSpecCircuitBreaker, KongSpecCondition, KongSpecEffect, KongSpecEffectStatus, KongSpecError, KongSpecEventBroker, KongSpecEventConnection, KongSpecFeatureCompensation, KongSpecFlow, KongSpecFunctionRef, KongSpecHowToInvoke, KongSpecHowToOutput, KongSpecHowToStore, KongSpecOutputAppend, KongSpecProcessRef, KongSpecRecord, KongSpecRecordHeader, KongSpecRetry, KongSpecRule, KongSpecSecretRef, KongSpecSecretType, KongSpecState, KongSpecStateCallFunction, KongSpecStateCallProcess, KongSpecStateCompensate, KongSpecStateDelay, KongSpecStateExit, KongSpecStateFail, KongSpecStateForeach, KongSpecStateInject, KongSpecStateParallel, KongSpecStateResult, KongSpecStateRule, KongSpecStateSendEvent, KongSpecStateStart, KongSpecStateSucceed, KongSpecStateSwitch, KongSpecStateWaitEvent, KongSpecStoreRetryControl, KongSpecSupportsActions, KongSpecSupportsErrors, KongSpecSupportsInvoke, KongSpecSupportsOutputSample, KongSpecSupportsOutputStore, KongSpecSupportsTransition, } from "./lib/kongSpec";
+export type { KongSpecAction, KongSpecActionCallFunction, KongSpecActionCallProcess, KongSpecActionDelay, KongSpecActionInject, KongSpecActionSendEvent, KongSpecAnnotation, KongSpecBranch, KongSpecCache, KongSpecCallModel, KongSpecCircuitBreaker, KongSpecCondition, KongSpecEffect, KongSpecEffectStatus, KongSpecError, KongSpecEventBroker, KongSpecEventConnection, KongSpecFeatureCompensation, KongSpecFlow, KongSpecFunctionRef, KongSpecHowToInvoke, KongSpecHowToOutput, KongSpecHowToStore, KongSpecOutputAppend, KongSpecProcessRef, KongSpecRecord, KongSpecRecordHeader, KongSpecRetry, KongSpecRule, KongSpecSecretRef, KongSpecSecretType, KongSpecState, KongSpecStateCallFunction, KongSpecStateCallProcess, KongSpecStateCompensate, KongSpecStateDelay, KongSpecStateExit, KongSpecStateFail, KongSpecStateForeach, KongSpecStateInject, KongSpecStateParallel, KongSpecStateResult, KongSpecStateRule, KongSpecStateSendEvent, KongSpecStateStart, KongSpecStateSucceed, KongSpecStateSwitch, KongSpecStateWaitEvent, KongSpecStoreRetryControl, KongSpecSupportsActions, KongSpecSupportsErrors, KongSpecSupportsInvoke, KongSpecSupportsOutputSample, KongSpecSupportsOutputStore, KongSpecSupportsTaskMode, KongSpecSupportsTransition, } from "./lib/kongSpec";
 export { KongSpecBuild } from "./lib/kongSpecBuild";
 export { KongSpecDoc } from "./lib/kongSpecDoc";
 export { KongSpecEnv } from "./lib/kongSpecEnv";
@@ -14,5 +14,7 @@ export { KongSpecRef } from "./lib/kongSpecRef";
 export type { KongSpecActionPath, KongSpecStatePath } from "./lib/kongSpecRef";
 export { convertSpecToServerless } from "./lib/kongSpecToServerless";
 export { findSourceState, getActions, getConnectedExitStates, getDependencies, outputAggregator, outputAggregatorUnsafe, parallelStateOutputAggregator, parallelStateOutputAggregatorUnsafe, quoteSecretReferences, traverseFlowUp, } from "./lib/kongSpecUtils";
+export { getKongFunctionOperations, getKongFunctionOperationSchema, getKongSpecXUI, getKongSpecXUIComponentConfig, isKongFunctionContractSchema, } from "./lib/kongSpecFunctionContract";
+export type { KongSpecXUIComponentConfig, KongSpecXUIConfig, KongSpecXUIFormConfig, KongSpecXUISecretConfig, } from "./lib/kongSpecFunctionContract";
 export { validate } from "./lib/kongSpecValidate";
 export type { KongSpecValidationIssue, KongSpecValidators } from "./lib/kongSpecValidate";

package/packages/kong-spec/src/lib/kongSpec.d.ts

@@ -106,7 +106,10 @@ export interface KongSpecSupportsDataGuards {
 export interface KongSpecSupportsOutputSample {
     outputSample: Optional<JsonText>;
 }
-export interface KongSpecCallModel extends KongSpecSupportsInput, KongSpecSupportsOutputFilter, KongSpecSupportsOutputStore, KongSpecSupportsOutputAppend, KongSpecSupportsOutputSample, KongSpecSupportsDataGuards, KongSpecSupportsInvoke {
+export interface KongSpecSupportsTaskMode {
+    mode: "blocking" | "non-blocking";
+}
+export interface KongSpecCallModel extends KongSpecSupportsInput, KongSpecSupportsOutputFilter, KongSpecSupportsOutputStore, KongSpecSupportsOutputAppend, KongSpecSupportsOutputSample, KongSpecSupportsDataGuards, KongSpecSupportsTaskMode, KongSpecSupportsInvoke {
 }
 export interface KongSpecSupportsErrors {
     errors: KongSpecError[];

package/packages/kong-spec/src/lib/kongSpecDoc.d.ts

@@ -15,6 +15,7 @@ export declare class KongSpecDoc {
     static aboutIdentify: string;
     static aboutSizeLimit: (bytes: string) => string;
     static aboutCallFunction: string;
+    static aboutMode: string;
     static aboutCallProcess: string;
     static aboutCompensate: string;
     static aboutFail: string;

package/packages/kong-spec/src/lib/kongSpecFunctionContract.d.ts

@@ -0,0 +1,26 @@
+import { Optional } from "@kong/ts";
+import { JSONSchema7 } from "json-schema";
+import { KongSpecSecretType } from "./kongSpec";
+export interface KongSpecXUISecretConfig {
+    purpose: string;
+    types: Array<KongSpecSecretType>;
+}
+export interface KongSpecXUIComponentConfig {
+    type: "TEXT_AREA";
+}
+export type KongSpecXUIFormConfig = Record<string, KongSpecXUIComponentConfig>;
+export interface KongSpecXUIConfig {
+    version?: number;
+    secrets: Array<KongSpecXUISecretConfig>;
+    form: KongSpecXUIFormConfig;
+}
+/** Reads the `x-ui` block of a schema, if present. */
+export declare function getKongSpecXUI(schema: Optional<JSONSchema7> | null): Optional<KongSpecXUIConfig>;
+/** Reads the `x-ui.form` component config for a property path (e.g. `[".notes"]`). */
+export declare function getKongSpecXUIComponentConfig(schema: Optional<JSONSchema7> | null, path: string[]): Optional<KongSpecXUIComponentConfig>;
+/** True when the schema describes a KongFunctionContract (i.e. it exposes a `request` envelope). */
+export declare function isKongFunctionContractSchema(schema: Optional<JSONSchema7> | null): boolean;
+/** The operation names of a contract schema — all object properties except `request`. */
+export declare function getKongFunctionOperations(schema: Optional<JSONSchema7> | null): string[];
+/** The sub-schema describing the payload of a single operation. */
+export declare function getKongFunctionOperationSchema(schema: Optional<JSONSchema7> | null, operation: string): Optional<JSONSchema7>;

package/packages/kong-spec/src/lib/kongSpecUtils.d.ts

@@ -8,7 +8,7 @@ interface TestItem {
 interface Dependency {
     type: "function" | "process";
     tenant: SessionTenant;
-    basedOn: KongSpecFunctionRef["basedOn"] | KongSpecFunctionRef["basedOn"];
+    basedOn: KongSpecFunctionRef["basedOn"] | KongSpecProcessRef["basedOn"];
     aliasName: KongSpecFunctionRef["aliasName"] | KongSpecProcessRef["aliasName"];
     usage: Array<KongSpecAction["name"] | KongSpecState["name"]>;
 }

package/packages/kong-ts-contract/src/lib/appAliasUse.d.ts

@@ -1,5 +1,5 @@
 import { AppSnapshot } from "./appSnapshot";
 export interface AppAliasUse {
     snapshot: AppSnapshot;
-    balance: number;
+    balance: number | null;
 }

package/packages/kong-ts-contract/src/lib/appAliasUseDetails.d.ts

@@ -3,7 +3,7 @@ import { AppAliasUse } from "./appAliasUse";
 import { AppSnapshotDetails } from "./appSnapshotDetails";
 export interface AppAliasUseDetails extends AppAliasUse {
     snapshot: AppSnapshotDetails;
-    balance: number;
+    balance: number | null;
     inputFilter?: JqFilter;
     outputFilter?: JqFilter;
 }