@nocobase/app-plugin-releases 0.1.0-beta.2 → 0.1.0-beta.20

package/dist/server/routes/schemas.js

@@ -1,16 +1,25 @@
 import { z } from 'zod';
 import { BUSINESS_ACTIONS, BUSINESS_KEYS, PAGES, SETTINGS_KEYS, } from '../../shared/access.js';
 import { ACTOR_KINDS, APP_ACTIVATIONS, REGISTRY_SECRET_KEYS, } from '../../shared/releases.js';
+import { ENVIRONMENT_PURPOSES, RUN_STATES, } from '../../shared/releases.js';
 const id = z.string().min(1);
-export const EnvironmentParams = z.object({ environmentId: id });
+export const EnvironmentParams = z.object({ environmentId: id.describe('The environment identifier.') });
 export const RegistryParams = z.object({
-    registryId: id,
+    registryId: id.describe('The registry identifier.'),
+});
+export const AppParams = z.object({
+    appId: id.describe('The application identifier.'),
+});
+export const ReleaseParams = z.object({
+    appId: id.describe('The application identifier.'),
+    releaseId: id.describe('The release identifier to deploy.'),
+});
+export const DeploymentParams = z.object({
+    appId: id.describe('The application identifier.'),
+    deploymentId: id.describe('The deployment identifier.'),
 });
-export const AppParams = z.object({ appId: id });
-export const ReleaseParams = z.object({ appId: id, releaseId: id });
-export const DeploymentParams = z.object({ appId: id, deploymentId: id });
 export const RequestParams = z.object({
-    requestId: id,
+    requestId: id.describe('The request identifier.'),
 });
 const page = z.coerce.number().int().min(1).default(1);
 const pageSize = z.coerce.number().int().min(1).max(100).default(20);
@@ -19,15 +28,28 @@ const labelFilter = z
     .union([z.string(), z.array(z.string())])
     .optional()
     .transform((value) => value === undefined ? [] : Array.isArray(value) ? value : [value]);
+/** A repeatable query value: one arrives as a string, several as an array. */
+const repeated = (item) => z
+    .union([item, z.array(item)])
+    .optional()
+    .transform((value) => value === undefined ? [] : Array.isArray(value) ? value : [value]);
 export const ListAppsQuery = z.object({
-    page,
-    pageSize,
-    q: z.string().trim().max(100).optional(),
-    environmentId: z.string().optional(),
-    label: labelFilter,
-});
-export const ListReleasesQuery = z.object({ page, pageSize, label: labelFilter });
-export const PageQuery = z.object({ page, pageSize });
+    page: page.describe('The page number, starting at 1.'),
+    pageSize: pageSize.describe('The maximum number of records to return.'),
+    q: z.string().trim().max(100).optional().describe('Text to search for.'),
+    environmentId: repeated(z.string().min(1)).describe('An environment identifier; repeat for Apps of any of them.'),
+    runtimeState: repeated(z.enum(RUN_STATES)).describe('A runtime state (`running`, `starting`, `pending`, `waiting`, `stopped`, `failed`, `unknown`); repeat for Apps in any of them. Applied before the page is cut.'),
+    label: labelFilter.describe('A label for this resource.'),
+});
+export const ListReleasesQuery = z.object({
+    page: page.describe('The page number, starting at 1.'),
+    pageSize: pageSize.describe('The maximum number of records to return.'),
+    label: labelFilter.describe('A label for this resource.'),
+});
+export const PageQuery = z.object({
+    page: page.describe('The page number, starting at 1.'),
+    pageSize: pageSize.describe('The maximum number of records to return.'),
+});
 const REQUEST_STATUSES = [
     'pending',
     'approved',
@@ -37,11 +59,17 @@ const REQUEST_STATUSES = [
     'failed',
 ];
 export const ListRequestsQuery = z.object({
-    page,
-    pageSize,
-    appId: z.string().optional(),
-    status: z.enum(REQUEST_STATUSES).optional(),
-    awaitingMe: z.enum(['true', 'false']).optional(),
+    page: page.describe('The page number, starting at 1.'),
+    pageSize: pageSize.describe('The maximum number of records to return.'),
+    appId: z.string().optional().describe('The application identifier.'),
+    status: z
+        .enum(REQUEST_STATUSES)
+        .optional()
+        .describe('The status to set or filter by.'),
+    awaitingMe: z
+        .enum(['true', 'false'])
+        .optional()
+        .describe('Only requests waiting for the caller’s approval.'),
 });
 export const DeleteAppQuery = z.object({
     confirm: z.string().optional(),
@@ -59,82 +87,161 @@ const LOG_LEVELS = [
  * the same token later returns what was appended since. A read returns one bounded chunk, so there is no `pageSize`.
  */
 export const LogQuery = z.object({
-    pageToken: z.string().optional(),
-    level: z.enum(LOG_LEVELS).optional(),
-    source: z.string().optional(),
-    q: z.string().optional(),
-    since: z.iso.datetime({ offset: true }).optional(),
-    until: z.iso.datetime({ offset: true }).optional(),
-    fromStart: z.enum(['true', 'false']).optional(),
+    pageToken: z
+        .string()
+        .optional()
+        .describe('The continuation token returned by the previous page.'),
+    level: z
+        .enum(LOG_LEVELS)
+        .optional()
+        .describe('The log severity to filter by.'),
+    source: z
+        .string()
+        .optional()
+        .describe('The source context associated with this record.'),
+    q: z.string().optional().describe('Text to search for.'),
+    since: z.iso
+        .datetime({ offset: true })
+        .optional()
+        .describe('Return logs at or after this timestamp.'),
+    until: z.iso
+        .datetime({ offset: true })
+        .optional()
+        .describe('Return logs before this timestamp.'),
+    fromStart: z
+        .enum(['true', 'false'])
+        .optional()
+        .describe('Read from the beginning rather than the latest logs.'),
 });
 const labels = z.record(z.string(), z.string());
 // A driver's settings and credentials follow the schema the driver itself declares, which the service checks.
 const driverObject = z.record(z.string(), z.unknown());
 const nullableCount = z.number().nullable();
 const environmentFields = {
-    name: z.string(),
-    config: driverObject.optional(),
-    secret: driverObject.nullable().optional(),
-    secretChanges: driverObject.optional(),
-    publicUrl: z.string().nullable().optional(),
+    name: z.string().describe('The name to display.'),
+    config: driverObject
+        .optional()
+        .describe('Configuration values for the selected environment or application.'),
+    secret: driverObject
+        .nullable()
+        .optional()
+        .describe('Secret configuration values.'),
+    secretChanges: driverObject
+        .optional()
+        .describe('Secret values to set or remove.'),
+    publicUrl: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('The public URL applications in this environment use.'),
     protected: z.boolean().optional().meta({
         description: 'Every deployment goes through a deployment request an approver approves; nothing deploys directly.',
     }),
-    approvers: z.array(z.string()).optional(),
-    maxApps: nullableCount.optional(),
-    defaultIdleStopMinutes: nullableCount.optional(),
-    defaultDormantAfterHours: nullableCount.optional(),
-    registryId: z.string().nullable().optional(),
+    approvers: z
+        .array(z.string())
+        .optional()
+        .describe('Users who may approve deployments to this environment.'),
+    maxApps: nullableCount
+        .optional()
+        .describe('The maximum number of applications in this environment; null means unlimited.'),
+    defaultIdleStopMinutes: nullableCount
+        .optional()
+        .describe('Default idle stop timeout in minutes for applications.'),
+    defaultDormantAfterHours: nullableCount
+        .optional()
+        .describe('Default dormant timeout in hours for applications.'),
+    registryId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('The registry identifier.'),
     sampleDataOnFirstDeploy: z.boolean().optional().meta({
         description: 'An App’s first deployment here loads its sample data (`APP_SAMPLE_DATA=true`).',
     }),
+    purpose: z.enum(ENVIRONMENT_PURPOSES).optional().meta({
+        description: 'What the environment is for: `preview` (pull request previews) or `test`; `test` when created without one.',
+    }),
 };
-export const CreateEnvironmentBody = z.strictObject({ ...environmentFields, id, driver: z.string() });
+export const CreateEnvironmentBody = z.strictObject({
+    ...environmentFields,
+    id: id.describe('The record identifier.'),
+    driver: z.string().describe('The environment driver configuration.'),
+});
 export const UpdateEnvironmentBody = z.strictObject({
     ...environmentFields,
-    name: environmentFields.name.optional(),
-    driver: z.string().optional(),
+    name: environmentFields.name.optional().describe('The name to display.'),
+    driver: z
+        .string()
+        .optional()
+        .describe('The environment driver configuration.'),
 });
 export const CheckEnvironmentBody = z.strictObject({
-    id: z.string().optional(),
-    name: z.string().optional(),
-    driver: z.string(),
-    config: driverObject.optional(),
-    secret: driverObject.nullable().optional(),
-    secretChanges: driverObject.optional(),
-    publicUrl: z.string().nullable().optional(),
+    id: z.string().optional().describe('The record identifier.'),
+    name: z.string().optional().describe('The name to display.'),
+    driver: z.string().describe('The environment driver configuration.'),
+    config: driverObject
+        .optional()
+        .describe('Configuration values for the selected environment or application.'),
+    secret: driverObject
+        .nullable()
+        .optional()
+        .describe('Secret configuration values.'),
+    secretChanges: driverObject
+        .optional()
+        .describe('Secret values to set or remove.'),
+    publicUrl: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('The public URL applications in this environment use.'),
 });
 const registryFields = {
-    name: z.string().optional(),
-    url: z.string().optional(),
-    namespace: z.string().nullable().optional(),
-    pullUsername: z.string().nullable().optional(),
+    name: z.string().optional().describe('The name to display.'),
+    url: z.string().optional().describe('The resource URL.'),
+    namespace: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('The container registry namespace.'),
+    pullUsername: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('The username used to pull container images.'),
     secretChanges: z
         .partialRecord(z.enum(REGISTRY_SECRET_KEYS), z.string().nullable())
-        .optional(),
+        .optional()
+        .describe('Secret values to set or remove.'),
 };
 export const CreateRegistryBody = z.strictObject({
     ...registryFields,
-    id,
-    name: z.string(),
-    url: z.string(),
+    id: id.describe('The record identifier.'),
+    name: z.string().describe('The name to display.'),
+    url: z.string().describe('The resource URL.'),
 });
 export const UpdateRegistryBody = z.strictObject(registryFields);
 /** Unsaved settings to try; `id` names the stored registry whose passwords fill the gaps. */
 export const CheckRegistryBody = z.strictObject({
     ...registryFields,
-    id: z.string().optional(),
+    id: z.string().optional().describe('The record identifier.'),
 });
 const runtimePolicy = {
-    activation: z.enum(APP_ACTIVATIONS).optional(),
-    idleStopMinutes: nullableCount.optional(),
-    dormantAfterHours: nullableCount.optional(),
+    activation: z
+        .enum(APP_ACTIVATIONS)
+        .optional()
+        .describe('The policy for starting the application.'),
+    idleStopMinutes: nullableCount
+        .optional()
+        .describe('Minutes without activity before stopping; null disables idle stopping.'),
+    dormantAfterHours: nullableCount
+        .optional()
+        .describe('Hours without activity before marking the app dormant; null disables it.'),
 };
 export const CreateAppBody = z.strictObject({
-    id,
-    name: z.string(),
-    environmentId: z.string(),
-    description: z.string().optional(),
+    id: id.describe('The record identifier.'),
+    name: z.string().describe('The name to display.'),
+    environmentId: z.string().describe('The environment identifier.'),
+    description: z.string().optional().describe('A description of the record.'),
     labels: labels.optional(),
     previewOf: z.string().optional().meta({
         description: 'Makes it a preview App of that App, removed with it.',
@@ -142,19 +249,24 @@ export const CreateAppBody = z.strictObject({
     ...runtimePolicy,
 });
 export const UpdateAppBody = z.strictObject({
-    name: z.string().optional(),
-    description: z.string().nullable().optional(),
+    name: z.string().optional().describe('The name to display.'),
+    description: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('A description of the record.'),
     labels: labels.optional(),
     ...runtimePolicy,
 });
 export const UpdateConfigBody = z.strictObject({
-    content: z.string(),
+    content: z.string().describe('The Markdown content.'),
     secretChanges: z
         .array(z.strictObject({
         path: z.array(z.union([z.string(), z.number().int().min(0)])),
         value: z.string().nullable(),
     }))
-        .optional(),
+        .optional()
+        .describe('Secret values to set or remove.'),
 });
 export const LabelReleaseBody = z.strictObject({ labels });
 const generator = z.enum(['secret', 'secretKeys', 'password']);
@@ -188,18 +300,21 @@ export const RegisterImageReleaseBody = z.strictObject({
     deploy: z.boolean().optional().meta({
         description: 'Deploy it once registered; the answer then names the deployment (`deploymentId`).',
     }),
-    version: z.string(),
-    ref: z.string(),
-    digest: z.string(),
-    platform: z.string().optional(),
-    sourceCommit: z.string().optional(),
-    build: z.string().optional(),
+    version: z.string().describe('The release version label.'),
+    ref: z.string().describe('The image reference or Git revision.'),
+    digest: z.string().describe('The immutable container image digest.'),
+    platform: z.string().optional().describe('The container image platform.'),
+    sourceCommit: z.string().optional().describe('The source Git commit.'),
+    build: z.string().optional().describe('Build metadata for the image.'),
     labels: labels.optional(),
     variables: variablesManifest.optional().meta({
         description: 'The build’s variables manifest (`dist/variables.json`), which an image carries no other way; `--variables-file dist/variables.json` on the command line.',
     }),
 });
-export const PromoteBody = z.strictObject({ toAppId: id, labels: labels.optional() });
+export const PromoteBody = z.strictObject({
+    toAppId: id.describe('The destination application identifier.'),
+    labels: labels.optional(),
+});
 export const CreateUploadTicketBody = z.strictObject({
     deploy: z.boolean().optional(),
     ttlSeconds: z.number().int().optional(),
@@ -210,31 +325,38 @@ export const DeployQuery = z.object({
     }),
 });
 export const DeployBody = z.strictObject({
-    releaseId: id,
+    releaseId: id.describe('The release identifier to deploy.'),
     config: z
         .strictObject({
         mode: z.enum(['file', 'external']),
         content: z.string().optional(),
     })
-        .optional(),
+        .optional()
+        .describe('Configuration values for the selected environment or application.'),
     idempotencyKey: z.string().optional(),
 });
 export const RollbackBody = z.strictObject({
-    deploymentId: id,
+    deploymentId: id.describe('The deployment identifier.'),
 });
 export const IdempotencyHeaders = z.object({ 'idempotency-key': z.string().optional() });
 export const CreateRequestBody = z.strictObject({
-    releaseId: z.string().optional(),
-    rollbackToDeploymentId: z.string().optional(),
-    note: z.string().optional(),
+    releaseId: z
+        .string()
+        .optional()
+        .describe('The release identifier to deploy.'),
+    rollbackToDeploymentId: z
+        .string()
+        .optional()
+        .describe('The deployment to restore.'),
+    note: z.string().optional().describe('A note explaining this change.'),
     labels: labels.optional(),
 });
 export const ApproveRequestBody = z.strictObject({
-    note: z.string().optional(),
+    note: z.string().optional().describe('A note explaining this change.'),
     confirm: z.string().optional(),
 });
 export const RejectRequestBody = z.strictObject({
-    note: z.string().optional(),
+    note: z.string().optional().describe('A note explaining this change.'),
 });
 export const EmptyBody = z.strictObject({});
 /**
@@ -254,6 +376,16 @@ export const UploadHeaders = z.object({
 // --- Response schemas, typed against the views the services return. ---
 const dateTime = z.string().meta({ format: 'date-time' });
 const nullableDateTime = dateTime.nullable();
+const hostHoldReason = z.enum([
+    'requests',
+    'connections',
+    'starting',
+    'operation',
+    'resident',
+    'busy',
+    'recent',
+]);
+const hostWaitReason = z.enum(['capacity', 'memory', 'recycle']);
 const outputLabels = z
     .record(z.string(), z.string())
     .meta({ ref: 'ReleasesLabels', description: 'Opaque key/value labels.' });
@@ -313,8 +445,7 @@ export const ReleasesDriverSchema = z.object({
         .nullable()
         .meta({ description: 'How the application configured the driver itself.' }),
 });
-export const ReleasesEnvironmentSchema = z
-    .object({
+const environmentRecordFields = {
     id: z.string(),
     name: z.string(),
     driver: z.string(),
@@ -330,6 +461,9 @@ export const ReleasesEnvironmentSchema = z
     defaultIdleStopMinutes: z.number().nullable(),
     defaultDormantAfterHours: z.number().nullable(),
     registryId: z.string().nullable(),
+    purpose: z.enum(ENVIRONMENT_PURPOSES).meta({
+        description: 'What the environment is for: `preview` (pull request previews) or `test`.',
+    }),
     sampleDataOnFirstDeploy: z.boolean().meta({
         description: 'An App’s first deployment here loads its sample data (`APP_SAMPLE_DATA=true`).',
     }),
@@ -350,8 +484,20 @@ export const ReleasesEnvironmentSchema = z
     }),
     createdAt: dateTime,
     updatedAt: dateTime,
-})
+};
+export const ReleasesEnvironmentSchema = z
+    .object(environmentRecordFields)
     .meta({ ref: 'ReleasesEnvironment' });
+/** An environment in the list, with how many Apps it holds. */
+export const ReleasesEnvironmentListItemSchema = z
+    .object({
+    ...environmentRecordFields,
+    appCount: z
+        .number()
+        .int()
+        .meta({ description: 'How many Apps the environment holds.' }),
+})
+    .meta({ ref: 'ReleasesEnvironmentListItem' });
 export const ReleasesEnvironmentCheckSchema = z.object({
     ok: z.boolean(),
     message: z.string().optional(),
@@ -405,6 +551,35 @@ const appView = z
     updatedAt: dateTime,
 })
     .meta({ ref: 'ReleasesAppView' });
+const appHostFields = {
+    id: z.string().meta({
+        description: 'The runtime, the same for every environment and App on it.',
+    }),
+    memory: z
+        .object({
+        heapUsed: z.number(),
+        heapLimit: z.number(),
+        rss: z.number(),
+        available: z.number(),
+    })
+        .nullable()
+        .meta({
+        description: 'The shared process’s memory in bytes, never divided among its Apps.',
+    }),
+    recycling: z.enum(['pending', 'restarting']).nullable(),
+    deployed: z.number().int().nonnegative(),
+    running: z.number().int().nonnegative().meta({
+        description: 'Apps running or starting on it; a failed App holds nothing and is not counted.',
+    }),
+    maxActive: z.number().int().positive().nullable().meta({
+        description: 'How many Apps may run or start on it at once; null when nothing limits it.',
+    }),
+    failedEnvironments: z.array(z.object({
+        id: z.string(),
+        name: z.string().nullable(),
+        error: z.string().nullable(),
+    })),
+};
 export const ReleasesAppSchema = z
     .object({
     app: appView,
@@ -429,11 +604,27 @@ export const ReleasesAppSchema = z
         startedAt: nullableDateTime,
         error: z.string().nullable(),
         lastAccessedAt: nullableDateTime,
+        holds: z.array(hostHoldReason).optional().meta({
+            description: 'Why a running or starting App holds a slot on its shared runtime.',
+        }),
+        waiting: hostWaitReason.optional().meta({
+            description: 'Why its last start was refused, for a minute or until it starts.',
+        }),
+        unrestored: z.boolean().optional().meta({
+            description: 'Its shared runtime restarted and could not put this App back; retried in the background.',
+        }),
     }),
     url: z.string().nullable(),
     currentVersion: z.string().nullable(),
     hasReleases: z.boolean(),
     hasPendingDeployment: z.boolean(),
+    pendingDeployment: z
+        .object({
+        status: z.enum(['queued', 'deploying', 'cancelling']),
+        queueAhead: z.number().int().nonnegative().nullable(),
+    })
+        .nullable()
+        .optional(),
     allowed: z.array(z.enum(BUSINESS_ACTIONS['rel.apps'])).optional().meta({
         description: 'What the caller may do on this App; only the single-App read answers it.',
     }),
@@ -446,6 +637,9 @@ export const ReleasesAppSchema = z
         .meta({
         description: 'The current release’s required variables nothing supplies, and whether a value changed since the running deployment; only the single-App read answers it.',
     }),
+    host: z.object(appHostFields).nullable().optional().meta({
+        description: 'The runtime the App shares with other Apps, every environment on it included; only the single-App read answers it.',
+    }),
 })
     .meta({ ref: 'ReleasesApp' });
 export const ReleasesConfigSchema = z
@@ -463,6 +657,22 @@ export const ReleasesConfigTemplateSchema = z.object({
         .nullable()
         .meta({ description: 'The release’s configuration template, if any.' }),
 });
+export const ReleasesSharedHostSchema = z
+    .object({
+    ...appHostFields,
+    environments: z
+        .array(z.object({
+        id: z.string(),
+        name: z.string(),
+        running: z.number().int().meta({
+            description: 'How many of the environment’s Apps run or start on this runtime (part of `running`).',
+        }),
+    }))
+        .meta({
+        description: 'The environments with Apps on this runtime.',
+    }),
+})
+    .meta({ ref: 'ReleasesSharedHost' });
 const releaseArtifact = z.discriminatedUnion('kind', [
     z.object({
         kind: z.literal('tarball'),
@@ -527,6 +737,8 @@ export const ReleasesUploadTicketSchema = z.object({
 });
 const deploymentPhase = z.enum([
     'queued',
+    'cancelling',
+    'cancelled',
     'resolving',
     'verifying',
     'extracting',
@@ -545,7 +757,16 @@ export const ReleasesDeploymentSchema = z
     kind: z.enum(['deploy', 'rollback']),
     rollbackTargetDeploymentId: z.string().nullable(),
     previousDeploymentId: z.string().nullable(),
-    status: z.enum(['queued', 'deploying', 'succeeded', 'failed']),
+    status: z.enum([
+        'queued',
+        'deploying',
+        'cancelling',
+        'cancelled',
+        'succeeded',
+        'failed',
+    ]),
+    queueAhead: z.number().int().nonnegative().nullable().optional(),
+    cancellable: z.boolean().optional(),
     phase: deploymentPhase,
     configMode: z.enum(['file', 'external']),
     error: z.string().nullable(),
@@ -650,16 +871,26 @@ export const ReleasesLogMeta = z
     .meta({ ref: 'ReleasesLogMeta' });
 // --- Variables --------------------------------------------------------------------------------------------------
 export const VariableParams = z.object({
-    name: z.string().min(1).max(128),
+    name: z.string().min(1).max(128).describe('The name to display.'),
+});
+export const EnvironmentVariableParams = z.object({
+    environmentId: id.describe('The environment identifier.'),
+    name: z.string().min(1).max(128).describe('The name to display.'),
+});
+export const AppVariableParams = z.object({
+    appId: id.describe('The application identifier.'),
+    name: z.string().min(1).max(128).describe('The name to display.'),
 });
-export const EnvironmentVariableParams = z.object({ environmentId: id, name: z.string().min(1).max(128) });
-export const AppVariableParams = z.object({ appId: id, name: z.string().min(1).max(128) });
 export const SetEnvironmentVariableBody = z.strictObject({
     value: z.string().meta({ description: 'The value; at most 64 KiB.' }),
     secret: z.boolean().optional().meta({
         description: 'Never shown again once set. Inferred from the name when left out (`…_PASSWORD`, `…_SECRET`, `…_TOKEN`, `…_KEY`).',
     }),
-    description: z.string().nullable().optional(),
+    description: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('A description of the record.'),
 });
 export const SetAppVariableBody = z.strictObject({
     value: z.string().meta({ description: 'The value; at most 64 KiB.' }),