@siteoshq/cli 1.3.0 → 1.5.0

package/dist/cli.js

@@ -2936,6 +2936,8 @@ function isCliExitCode(value) {
 import { readFile as readFile5 } from "fs/promises";
 import path12 from "path";
 import { z as z10 } from "zod";
+import { Ajv } from "ajv";
+import addFormats from "ajv-formats";
 
 // src/siteos-forms-api.ts
 import { z as z9 } from "zod";
@@ -2971,12 +2973,82 @@ var formDefinitionSyncResponseSchema = z9.object({
   success: z9.literal(true),
   version: z9.number().int().positive()
 }).strict();
+var definitionSchema = z9.object({
+  id: opaqueIdentifierSchema,
+  environmentId: opaqueIdentifierSchema,
+  formKey: opaqueIdentifierSchema,
+  name: z9.string(),
+  sourcePagePath: z9.string().nullable(),
+  activeVersion: z9.number().int().positive(),
+  activeVersionId: opaqueIdentifierSchema,
+  status: z9.enum(["active", "inactive"]),
+  submissionCount: z9.number().int().nonnegative(),
+  lastSubmittedAt: z9.string().datetime({ offset: true }).nullable(),
+  createdAt: z9.string().datetime({ offset: true }),
+  updatedAt: z9.string().datetime({ offset: true })
+});
+var definitionListSchema = z9.object({
+  definitions: z9.array(definitionSchema)
+});
+var definitionContextSchema = z9.object({
+  definition: definitionSchema,
+  revision: z9.number().int().positive(),
+  canManage: z9.boolean(),
+  project: z9.object({ id: opaqueIdentifierSchema, name: z9.string() }),
+  environment: z9.object({
+    id: opaqueIdentifierSchema,
+    name: z9.string(),
+    slug: z9.string()
+  })
+});
+var definitionChangeResponseSchema = z9.object({
+  deleted: z9.boolean(),
+  formId: opaqueIdentifierSchema
+});
 var formSubmissionResponseSchema = z9.object({
   formId: opaqueIdentifierSchema,
   receivedAt: z9.string().datetime({ offset: true }),
   submissionId: opaqueIdentifierSchema,
   success: z9.literal(true)
 }).strict();
+var formsSubmissionStatusSchema = z9.enum([
+  "new",
+  "read",
+  "archived",
+  "spam"
+]);
+var submissionSummarySchema = z9.object({
+  id: opaqueIdentifierSchema,
+  formId: opaqueIdentifierSchema,
+  normalized: z9.record(
+    z9.union([z9.string(), z9.number(), z9.boolean(), z9.null()])
+  ),
+  status: formsSubmissionStatusSchema,
+  submittedAt: z9.string().datetime({ offset: true })
+});
+var submissionDetailSchema = submissionSummarySchema.extend({
+  payload: z9.record(z9.unknown()),
+  fields: z9.array(
+    z9.object({
+      key: z9.string(),
+      label: z9.string().optional(),
+      kind: z9.string().optional(),
+      displayRole: z9.enum(["primary", "secondary"]).optional(),
+      multiple: z9.boolean().optional(),
+      options: z9.array(z9.object({ value: z9.string(), label: z9.string() })).optional()
+    })
+  ),
+  version: z9.number().int().positive(),
+  versionId: opaqueIdentifierSchema
+});
+var submissionPageSchema = z9.object({
+  submissions: z9.array(submissionSummarySchema),
+  total: z9.number().int().nonnegative(),
+  nextCursor: z9.string().nullable()
+});
+var submissionDetailResponseSchema = z9.object({
+  submission: submissionDetailSchema
+});
 var formsCredentialMetadataSchema = z9.object({
   createdAt: z9.string().datetime({ offset: true }),
   id: z9.string().trim().min(1).max(255),
@@ -2993,6 +3065,9 @@ var formsCredentialExchangeSchema = formsCredentialMetadataSchema.extend({
   token: z9.string().regex(/^pfs_[A-Za-z0-9_-]{22}$/)
 });
 var formsErrorCodeSchema = z9.enum([
+  "AUTHENTICATION_REQUIRED",
+  "FORBIDDEN",
+  "CONFLICT",
   "INVALID_REQUEST",
   "INVALID_INPUT",
   "VALIDATION_FAILED",
@@ -3000,6 +3075,8 @@ var formsErrorCodeSchema = z9.enum([
   "UNAUTHORIZED",
   "IDENTITY_REQUIRED",
   "NOT_ALLOWED",
+  "FORM_ARCHIVED",
+  "FORM_DELETED",
   "NOT_FOUND",
   "PROJECT_NOT_FOUND",
   "PROJECT_CONFLICT",
@@ -3012,6 +3089,9 @@ var formsErrorCodeSchema = z9.enum([
   "INTERNAL_ERROR"
 ]);
 var safeFormsErrorMessages = {
+  AUTHENTICATION_REQUIRED: "Sign in to SiteOS before reading Forms submissions.",
+  FORBIDDEN: "Forms management access is denied.",
+  CONFLICT: "The resource changed or this idempotency key belongs to different data. Read the current state before retrying.",
   INVALID_REQUEST: "The Forms request is invalid.",
   INVALID_INPUT: "Invalid input data.",
   VALIDATION_FAILED: "Validation failed.",
@@ -3019,6 +3099,8 @@ var safeFormsErrorMessages = {
   UNAUTHORIZED: "Forms management authorization is invalid.",
   IDENTITY_REQUIRED: "Forms browser identity is required.",
   NOT_ALLOWED: "Forms management access is denied.",
+  FORM_ARCHIVED: "This form is archived. Restore it explicitly before syncing or sending new submissions.",
+  FORM_DELETED: "This form was permanently deleted. Use a new form key for a new form.",
   NOT_FOUND: "The requested resource was not found.",
   PROJECT_NOT_FOUND: "The Forms Project was not found.",
   PROJECT_CONFLICT: "The Forms Project already exists.",
@@ -3051,9 +3133,83 @@ function resolveSiteOSFormsBaseUrl(env = process.env) {
     env[SITEOS_FORMS_BASE_URL_ENV]?.trim() || DEFAULT_SITEOS_FORMS_BASE_URL
   );
 }
+var deploymentResponseSchema = z9.object({
+  environmentId: opaqueIdentifierSchema,
+  forms: z9.array(
+    z9.object({
+      formKey: opaqueIdentifierSchema,
+      formId: opaqueIdentifierSchema,
+      contractVersion: z9.string().regex(/^sha256:[a-f0-9]{64}$/),
+      versionId: opaqueIdentifierSchema,
+      version: z9.number().int().positive()
+    })
+  )
+});
 function createSiteOSFormsApiClient(options) {
   const apiBaseUrl = normalizeFormsOrigin(options.apiBaseUrl);
+  const inboxPath = (input) => `/api/v1/forms/environments/${encodeURIComponent(input.environmentId)}/forms/${encodeURIComponent(input.formId)}/submissions`;
+  const definitionPath = (input) => `/api/v1/forms/environments/${encodeURIComponent(input.environmentId)}/forms/${encodeURIComponent(input.formId)}`;
+  const keyCollection = (input) => options.deploymentKeys ? `${environmentItemPath(input)}/deployment-keys` : credentialCollectionPath(input);
   return {
+    publishDefinitions: (input) => requestJson2({
+      apiBaseUrl,
+      fetchImpl: options.fetchImpl,
+      method: "POST",
+      path: "/api/forms/deployments",
+      body: { definitions: input.definitions },
+      headers: { "x-siteos-forms-deployment-key": input.credential },
+      responseSchema: deploymentResponseSchema
+    }),
+    listDefinitions: (input) => requestJson2({
+      apiBaseUrl,
+      fetchImpl: options.fetchImpl,
+      headers: managementHeaders(input),
+      method: "GET",
+      path: `/api/v1/forms/environments/${encodeURIComponent(input.environmentId)}/definitions?status=${input.status}`,
+      responseSchema: definitionListSchema
+    }),
+    readDefinition: (input) => requestJson2({
+      apiBaseUrl,
+      fetchImpl: options.fetchImpl,
+      headers: managementHeaders(input),
+      method: "GET",
+      path: definitionPath(input),
+      responseSchema: definitionContextSchema
+    }),
+    changeDefinition: (input) => requestJson2({
+      apiBaseUrl,
+      fetchImpl: options.fetchImpl,
+      headers: managementHeaders(input),
+      method: "PATCH",
+      path: definitionPath(input),
+      body: input.change,
+      responseSchema: definitionChangeResponseSchema
+    }),
+    listSubmissions: (input) => requestJson2({
+      apiBaseUrl,
+      fetchImpl: options.fetchImpl,
+      headers: managementHeaders(input),
+      method: "GET",
+      path: `${inboxPath(input)}?${input.filters}`,
+      responseSchema: submissionPageSchema
+    }),
+    readSubmission: (input) => requestJson2({
+      apiBaseUrl,
+      fetchImpl: options.fetchImpl,
+      headers: managementHeaders(input),
+      method: "GET",
+      path: `${inboxPath(input)}/${encodeURIComponent(input.submissionId)}`,
+      responseSchema: submissionDetailResponseSchema
+    }),
+    updateSubmissionStatus: (input) => requestJson2({
+      apiBaseUrl,
+      fetchImpl: options.fetchImpl,
+      headers: managementHeaders(input),
+      method: "PATCH",
+      path: `${inboxPath(input)}/${encodeURIComponent(input.submissionId)}`,
+      body: { status: input.status, expectedStatus: input.expectedStatus },
+      responseSchema: submissionDetailResponseSchema
+    }),
     createProject: (input) => requestJson2({
       apiBaseUrl,
       body: { name: input.name, slug: input.slug },
@@ -3078,8 +3234,10 @@ function createSiteOSFormsApiClient(options) {
       fetchImpl: options.fetchImpl,
       headers: managementHeaders(input),
       method: "POST",
-      path: credentialCollectionPath(input),
-      responseSchema: formsCredentialExchangeSchema
+      path: keyCollection(input),
+      responseSchema: options.deploymentKeys ? formsCredentialExchangeSchema.extend({
+        token: z9.string().regex(/^pfd_[A-Za-z0-9_-]{43}$/)
+      }) : formsCredentialExchangeSchema
     }),
     listEnvironments: (input) => requestJson2({
       apiBaseUrl,
@@ -3102,7 +3260,7 @@ function createSiteOSFormsApiClient(options) {
       fetchImpl: options.fetchImpl,
       headers: managementHeaders(input),
       method: "GET",
-      path: credentialCollectionPath(input),
+      path: keyCollection(input),
       responseSchema: formsCredentialListSchema
     }),
     revokeCredential: (input) => requestJson2({
@@ -3110,7 +3268,7 @@ function createSiteOSFormsApiClient(options) {
       fetchImpl: options.fetchImpl,
       headers: managementHeaders(input),
       method: "DELETE",
-      path: credentialItemPath(input),
+      path: options.deploymentKeys ? `${keyCollection(input)}/${encodeURIComponent(input.credentialId)}` : credentialItemPath(input),
       responseSchema: formsCredentialMetadataSchema
     }),
     rotateCredential: (input) => requestJson2({
@@ -3120,7 +3278,9 @@ function createSiteOSFormsApiClient(options) {
       headers: managementHeaders(input),
       method: "POST",
       path: credentialRotatePath(input),
-      responseSchema: formsCredentialExchangeSchema
+      responseSchema: options.deploymentKeys ? formsCredentialExchangeSchema.extend({
+        token: z9.string().regex(/^pfd_[A-Za-z0-9_-]{43}$/)
+      }) : formsCredentialExchangeSchema
     }),
     submitForm: (input) => requestJson2({
       apiBaseUrl,
@@ -3154,7 +3314,9 @@ async function requestJson2(options) {
         ...options.body === void 0 ? {} : { "Content-Type": "application/json" },
         ...options.headers
       },
-      method: options.method
+      method: options.method,
+      redirect: "error",
+      signal: AbortSignal.timeout(3e4)
     });
   } catch {
     throw new SiteOSFormsApiError({
@@ -3247,7 +3409,7 @@ import {
 } from "fs/promises";
 import path11 from "path";
 var SITEOS_FORMS_SUBMISSION_CREDENTIAL_ENV = "SITEOS_FORMS_SUBMISSION_CREDENTIAL";
-var credentialPattern = /^pfs_[A-Za-z0-9_-]{22}$/;
+var SITEOS_FORMS_DEPLOYMENT_KEY_ENV = "SITEOS_FORMS_DEPLOYMENT_KEY";
 var SiteOSFormsCredentialStorageError = class extends Error {
   code;
   constructor(code) {
@@ -3259,6 +3421,8 @@ var SiteOSFormsCredentialStorageError = class extends Error {
   }
 };
 async function prepareSiteOSFormsCredentialInstallation(options) {
+  const variable = options.deployment ? SITEOS_FORMS_DEPLOYMENT_KEY_ENV : SITEOS_FORMS_SUBMISSION_CREDENTIAL_ENV;
+  const credentialPattern = options.deployment ? /^pfd_[A-Za-z0-9_-]{43}$/ : /^pfs_[A-Za-z0-9_-]{22}$/;
   const projectRoot = path11.resolve(options.projectRoot);
   const dotenvPath = path11.join(projectRoot, ".env");
   try {
@@ -3285,7 +3449,7 @@ async function prepareSiteOSFormsCredentialInstallation(options) {
           }
           const currentContent = await readSafeDotenv(dotenvPath);
           await writeCredentialAtomically({
-            content: setCredential(currentContent, credential),
+            content: setCredential(currentContent, credential, variable),
             dotenvPath,
             projectRoot
           });
@@ -3323,7 +3487,10 @@ async function readSafeDotenv(dotenvPath) {
     );
   }
   const content = dotenvStats ? await readFile4(dotenvPath, "utf8") : "";
-  if (countCredentialEntries(content) > 1) {
+  if ([
+    SITEOS_FORMS_SUBMISSION_CREDENTIAL_ENV,
+    SITEOS_FORMS_DEPLOYMENT_KEY_ENV
+  ].some((variable) => countCredentialEntries(content, variable) > 1)) {
     throw new SiteOSFormsCredentialStorageError(
       "FORMS_CREDENTIAL_STORAGE_INVALID"
     );
@@ -3351,21 +3518,16 @@ async function writeCredentialAtomically(options) {
     await rm3(temporaryPath, { force: true }).catch(() => void 0);
   }
 }
-function setCredential(content, credential) {
-  const assignment = `${SITEOS_FORMS_SUBMISSION_CREDENTIAL_ENV}=${credential}`;
-  const existing = new RegExp(
-    `^${SITEOS_FORMS_SUBMISSION_CREDENTIAL_ENV}=[^\\r\\n]*(?=\\r?$)`,
-    "m"
-  );
+function setCredential(content, credential, variable) {
+  const assignment = `${variable}=${credential}`;
+  const existing = new RegExp(`^${variable}=[^\\r\\n]*(?=\\r?$)`, "m");
   if (existing.test(content)) return content.replace(existing, assignment);
   const newline = content.includes("\r\n") ? "\r\n" : "\n";
   if (content.length === 0) return `${assignment}${newline}`;
   return `${content}${content.endsWith("\n") ? "" : newline}${assignment}${newline}`;
 }
-function countCredentialEntries(content) {
-  return content.split(/\r?\n/u).filter(
-    (line) => line.startsWith(`${SITEOS_FORMS_SUBMISSION_CREDENTIAL_ENV}=`)
-  ).length;
+function countCredentialEntries(content, variable) {
+  return content.split(/\r?\n/u).filter((line) => line.startsWith(`${variable}=`)).length;
 }
 function isDotenvIgnored(projectRoot) {
   return new Promise((resolve, reject) => {
@@ -3407,25 +3569,40 @@ var SLUG_FLAG = "--slug";
 var CREDENTIAL_FLAG = "--credential";
 var REPLACE_FLAG = "--replace";
 var normalizedFieldOptionSchema = z10.object({
-  label: z10.string().trim().min(1),
-  value: z10.string().trim().min(1)
+  label: z10.string().trim().min(1).max(255),
+  value: z10.string().trim().min(1).max(255)
 });
 var normalizedFieldSchema = z10.object({
-  key: z10.string().trim().min(1),
-  kind: z10.string().trim().min(1).optional(),
-  label: z10.string().trim().min(1).optional(),
+  key: z10.string().trim().min(1).max(255),
+  kind: z10.string().trim().min(1).max(64).optional(),
+  label: z10.string().trim().min(1).max(255).optional(),
   displayRole: z10.enum(["primary", "secondary"]).optional(),
   multiple: z10.boolean().optional(),
-  options: z10.array(normalizedFieldOptionSchema).optional()
-}).passthrough();
+  options: z10.array(normalizedFieldOptionSchema).max(500).optional()
+}).strict();
 var definitionSyncInputSchema = z10.object({
-  formKey: z10.string().trim().min(1),
-  name: z10.string().trim().min(1),
-  normalizedFieldsJson: z10.array(normalizedFieldSchema).min(1),
+  formKey: z10.string().trim().min(1).max(255),
+  name: z10.string().trim().min(1).max(255),
+  normalizedFieldsJson: z10.array(normalizedFieldSchema).min(1).max(500),
   schemaJson: z10.record(z10.unknown()),
-  sourceExportId: z10.string().trim().min(1).optional(),
-  sourcePagePath: z10.string().trim().min(1).optional()
-}).passthrough().superRefine((definition, context) => {
+  sourceExportId: z10.string().trim().min(1).max(255).optional(),
+  sourcePagePath: z10.string().trim().min(1).max(2048).optional()
+}).strict().superRefine((definition, context) => {
+  const ajv = new Ajv({
+    allErrors: true,
+    removeAdditional: false,
+    strict: true
+  });
+  addFormats.default(ajv);
+  try {
+    ajv.compile(definition.schemaJson);
+  } catch {
+    context.addIssue({
+      code: z10.ZodIssueCode.custom,
+      message: "schemaJson must be an executable JSON Schema supported by SiteOS Forms.",
+      path: ["schemaJson"]
+    });
+  }
   const fields = definition.normalizedFieldsJson;
   const duplicateKeys = fields.map((field) => field.key).filter((key, index, keys) => keys.indexOf(key) !== index);
   for (const key of new Set(duplicateKeys)) {
@@ -3506,6 +3683,11 @@ var FORMS_HELP = `Usage:
   siteos forms environment create --slug <slug> --name <name> [--json]
   siteos forms definition sync --environment <slug> --input <path> [--json]
   siteos forms definition sync --environment <slug> --manifest <path> [--json]
+  siteos forms definition list --environment <slug> [--status <active|inactive|all>] [--json]
+  siteos forms definition read --environment <slug> --form <form-id> [--json]
+  siteos forms definition archive --environment <slug> --form <form-id> --expected-revision <revision> [--json]
+  siteos forms definition restore --environment <slug> --form <form-id> --expected-revision <revision> [--json]
+  siteos forms definition delete --environment <slug> --form <form-id> [--apply --confirm <form-key> --expected-revision <revision> --expected-submissions <count>] [--json]
   siteos forms definition check --input <path> [--json]
   siteos forms definition check --manifest <path> [--json]
   siteos forms credential list --environment <slug> [--json]
@@ -3513,6 +3695,13 @@ var FORMS_HELP = `Usage:
   siteos forms credential rotate --environment <slug> --install [--name <name>] [--json]
   siteos forms credential revoke --environment <slug> --credential <credential-id> [--json]
   siteos forms credentials issue --environment <slug> [--name <name>] [--json]
+  siteos forms submissions list --environment <slug> --form <form-id> [--query <text>] [--status <status>] [--from <ISO>] [--to <ISO>] [--limit <1-100>] [--cursor <cursor>] [--json]
+  siteos forms submissions read --environment <slug> --form <form-id> --submission <id> [--json]
+  siteos forms submissions status --environment <slug> --form <form-id> --submission <id> --status <new|read|archived|spam> --expected-status <status> [--json]
+  siteos forms deploy --manifest <path> [--json]
+  siteos forms deployment-key issue --environment <slug> --install [--name <name>] [--json]
+  siteos forms deployment-key list --environment <slug> [--json]
+  siteos forms deployment-key revoke --environment <slug> --credential <id> [--json]
   siteos forms submit --input <path> [--json]
 
 Manage SiteOS Forms Environments, definitions, credentials, and submission smoke tests.`;
@@ -3524,6 +3713,8 @@ async function runFormsCommand(options) {
       stdout: FORMS_HELP
     };
   }
+  if (args2[0] === "deploy")
+    return runDeployment({ ...options, args: args2.slice(1) });
   if (args2[0] !== "submit" && args2[0] !== "project") {
     try {
       args2 = await commonEnvironmentArguments(options, "forms", args2);
@@ -3534,6 +3725,8 @@ async function runFormsCommand(options) {
       };
     }
   }
+  if (args2[0] === "submissions")
+    return runSubmissionsCommand({ ...options, args: args2.slice(1) });
   if (args2[0] === "definition") {
     return runDefinitionCommand({
       ...options,
@@ -3558,6 +3751,13 @@ async function runFormsCommand(options) {
       args: args2.slice(1)
     });
   }
+  if (args2[0] === "deployment-key") {
+    return runCredentialCommand({
+      ...options,
+      args: args2.slice(1),
+      deployment: true
+    });
+  }
   if (args2[0] === "credential") {
     return runCredentialCommand({
       ...options,
@@ -3577,6 +3777,96 @@ async function runFormsCommand(options) {
   }
   return usageError2("Unknown SiteOS forms command.");
 }
+async function runSubmissionsCommand(options) {
+  const action = options.args[0];
+  if (!action || !["list", "read", "status"].includes(action))
+    return usageError2("Unknown Forms submissions command.");
+  const parsed = parseFlags(options.args.slice(1), {
+    allowed: /* @__PURE__ */ new Set([
+      "--environment",
+      "--form",
+      "--json",
+      ...action === "list" ? ["--query", "--status", "--from", "--to", "--limit", "--cursor"] : [
+        "--submission",
+        ...action === "status" ? ["--status", "--expected-status"] : []
+      ]
+    ]),
+    boolean: /* @__PURE__ */ new Set(["--json"]),
+    rejectDuplicates: true
+  });
+  if (!parsed.ok) return usageError2(parsed.error);
+  if (parsed.positionals.length)
+    return usageError2("Unexpected positional arguments.");
+  const value = (key) => readStringFlag(parsed.flags, `--${key}`);
+  const environmentSlug = value("environment");
+  const formId = value("form");
+  const submissionId = value("submission");
+  if (!environmentSlug || !isValidEnvironmentSlug(environmentSlug) || !formId || formId.length > 255)
+    return usageError2("Provide a valid --environment and --form.");
+  if (action !== "list" && (!submissionId || submissionId.length > 255))
+    return usageError2("Provide --submission.");
+  const status = formsSubmissionStatusSchema.safeParse(value("status"));
+  const expected = formsSubmissionStatusSchema.safeParse(
+    value("expected-status")
+  );
+  if (value("status") && !status.success || action === "status" && (!status.success || !expected.success))
+    return usageError2(
+      "Use new, read, archived or spam for --status and --expected-status."
+    );
+  const filters = new URLSearchParams();
+  for (const key of ["query", "status", "from", "to", "limit", "cursor"]) {
+    const item = value(key);
+    if (item) filters.set(key, item);
+  }
+  const limit = Number(value("limit") ?? 50);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+    return usageError2("--limit must be between 1 and 100.");
+  if ((value("query")?.length ?? 0) > 200 || (value("cursor")?.length ?? 0) > 2048)
+    return usageError2("The query or cursor is too long.");
+  for (const key of ["from", "to"])
+    if (value(key) && !z10.string().datetime({ offset: true }).safeParse(value(key)).success)
+      return usageError2(
+        `--${key} must be an ISO timestamp including a timezone.`
+      );
+  if (value("from") && value("to") && Date.parse(value("from")) >= Date.parse(value("to")))
+    return usageError2("--from must be earlier than --to (exclusive).");
+  const context = await loadFormsManagementContext(
+    options,
+    "forms:workspace:write"
+  );
+  if (!context.ok) return context.error;
+  try {
+    const { environments } = await context.client.listEnvironments({
+      grant: context.grant,
+      projectId: context.project.id
+    });
+    requireEnvironmentProjectConvergence(environments, context.project.id);
+    const environment = environments.find(
+      (item) => item.slug === environmentSlug
+    );
+    if (!environment)
+      return usageError2(
+        "The selected Forms Environment does not exist. Run forms environment list."
+      );
+    const input = {
+      grant: context.grant,
+      environmentId: environment.id,
+      formId
+    };
+    const response = action === "list" ? await context.client.listSubmissions({ ...input, filters }) : action === "read" ? await context.client.readSubmission({
+      ...input,
+      submissionId
+    }) : await context.client.updateSubmissionStatus({
+      ...input,
+      submissionId,
+      status: status.data,
+      expectedStatus: expected.data
+    });
+    return { exitCode: 0, stdout: stringifySafeJson(response) };
+  } catch (error) {
+    return formatApiError(error);
+  }
+}
 async function runProjectCommand(options) {
   const action = options.args[0];
   if (!action || !["create", "list", "status", "use"].includes(action)) {
@@ -3803,6 +4093,11 @@ async function runCredentialCommand(options) {
   if (!action || !["issue", "list", "revoke", "rotate"].includes(action)) {
     return usageError2("Unknown SiteOS forms credential command.");
   }
+  if (options.deployment && action === "rotate")
+    return usageError2(
+      "Issue a new deployment key, update the release secret, then revoke the old key."
+    );
+  const variable = options.deployment ? SITEOS_FORMS_DEPLOYMENT_KEY_ENV : SITEOS_FORMS_SUBMISSION_CREDENTIAL_ENV;
   const parsed = parseCredentialFlags(action, options.args.slice(1));
   if (!parsed.ok) return parsed.error;
   const context = await loadCredentialManagementContext({
@@ -3874,7 +4169,7 @@ Environment: ${parsed.environmentSlug}`
       credential,
       environment: parsed.environmentSlug,
       installed: {
-        variable: SITEOS_FORMS_SUBMISSION_CREDENTIAL_ENV
+        variable
       },
       operation: action === "issue" ? "issued" : "rotated"
     };
@@ -3884,7 +4179,7 @@ Environment: ${parsed.environmentSlug}`
         `SiteOS Forms credential ${output.operation} and installed.`,
         `Credential: ${credential.id}`,
         `Environment: ${parsed.environmentSlug}`,
-        `Variable: ${SITEOS_FORMS_SUBMISSION_CREDENTIAL_ENV}`
+        `Variable: ${variable}`
       ].join("\n")
     };
   } catch (error) {
@@ -3895,14 +4190,21 @@ async function loadCredentialManagementContext(options) {
   try {
     const local = await readLocalCommonProject(options);
     const rootDir = local?.rootDir ?? (await requireFormsProjectReference(options.cwd ?? process.cwd())).rootDir;
-    const installation = options.install ? await (options.prepareCredentialInstallation ?? prepareSiteOSFormsCredentialInstallation)({ projectRoot: rootDir }) : void 0;
+    const installation = options.install ? await (options.prepareCredentialInstallation ?? prepareSiteOSFormsCredentialInstallation)({
+      projectRoot: rootDir,
+      ...options.deployment ? { deployment: true } : {}
+    }) : void 0;
     const context = await loadFormsManagementContext(
       options,
       "forms:credential:manage"
     );
     if (!context.ok) return context;
     return {
-      client: context.client,
+      client: options.deployment ? createSiteOSFormsApiClient({
+        apiBaseUrl: context.apiBaseUrl,
+        fetchImpl: options.fetchImpl ?? fetch,
+        deploymentKeys: true
+      }) : context.client,
       grant: context.grant,
       ...installation ? { installation } : {},
       ok: true,
@@ -4017,6 +4319,10 @@ async function requireFormsProjectReference(cwd) {
   return reference;
 }
 async function runDefinitionCommand(options) {
+  if (["list", "read", "archive", "restore", "delete"].includes(
+    options.args[0] ?? ""
+  ))
+    return runDefinitionLifecycle(options);
   if (options.args[0] === "sync") {
     return runDefinitionSync({
       ...options,
@@ -4031,6 +4337,125 @@ async function runDefinitionCommand(options) {
   }
   return usageError2("Unknown SiteOS forms definition command.");
 }
+async function runDefinitionLifecycle(options) {
+  const action = options.args[0];
+  const parsed = parseFlags(options.args.slice(1), {
+    allowed: /* @__PURE__ */ new Set([
+      "--environment",
+      "--json",
+      ...action === "list" ? ["--status"] : ["--form"],
+      ...["archive", "restore", "delete"].includes(action) ? ["--expected-revision"] : [],
+      ...action === "delete" ? ["--apply", "--confirm", "--expected-submissions"] : []
+    ]),
+    boolean: /* @__PURE__ */ new Set(["--json", "--apply"]),
+    rejectDuplicates: true
+  });
+  if (!parsed.ok) return usageError2(parsed.error);
+  if (parsed.positionals.length)
+    return usageError2("Unexpected positional arguments.");
+  const value = (key) => readStringFlag(parsed.flags, `--${key}`);
+  const environmentSlug = value("environment");
+  const formId = value("form");
+  if (!environmentSlug || !isValidEnvironmentSlug(environmentSlug) || action !== "list" && (!formId || formId.length > 255))
+    return usageError2("Provide a valid --environment and --form.");
+  const status = value("status") ?? "active";
+  if (!["active", "inactive", "all"].includes(status))
+    return usageError2("Use active, inactive or all for --status.");
+  const apply = parsed.flags.get("--apply") === true;
+  const revision = Number(value("expected-revision"));
+  const count = Number(value("expected-submissions"));
+  const confirmKey = value("confirm");
+  if ((action === "archive" || action === "restore" || apply) && (!Number.isSafeInteger(revision) || revision < 1))
+    return usageError2(
+      "Read the form first, then provide its --expected-revision."
+    );
+  if (apply && (!confirmKey || confirmKey.length > 255 || !Number.isSafeInteger(count) || count < 0))
+    return usageError2(
+      "Deletion requires --confirm with the exact form key and --expected-submissions from the preview."
+    );
+  if (action === "delete" && !apply && ["confirm", "expected-revision", "expected-submissions"].some(
+    (key) => value(key) !== void 0
+  ))
+    return usageError2(
+      "Delete is a read-only preview. Add --apply with all confirmation values to delete."
+    );
+  const context = await loadFormsManagementContext(
+    options,
+    "forms:workspace:write"
+  );
+  if (!context.ok) return context.error;
+  try {
+    const { environments } = await context.client.listEnvironments({
+      grant: context.grant,
+      projectId: context.project.id
+    });
+    requireEnvironmentProjectConvergence(environments, context.project.id);
+    const environment = environments.find(
+      (item) => item.slug === environmentSlug
+    );
+    if (!environment)
+      return usageError2(
+        "The selected Forms Environment does not exist. Run forms environment list."
+      );
+    const input = {
+      grant: context.grant,
+      environmentId: environment.id,
+      formId: formId ?? ""
+    };
+    if (action === "list")
+      return {
+        exitCode: 0,
+        stdout: stringifySafeJson(
+          await context.client.listDefinitions({
+            ...input,
+            status
+          })
+        )
+      };
+    if (action === "read" || action === "delete" && !apply) {
+      const preview = await context.client.readDefinition(input);
+      if (preview.project.id !== context.project.id || preview.environment.id !== environment.id || preview.definition.id !== formId || preview.definition.environmentId !== environment.id)
+        throw new SiteOSFormsApiError({
+          code: "INVALID_RESPONSE",
+          message: "The form does not match the selected Project and Environment."
+        });
+      return {
+        exitCode: 0,
+        stdout: stringifySafeJson(
+          action === "read" ? preview : {
+            ...preview,
+            action: "delete",
+            applied: false,
+            warning: "Permanently removes this form, all versions and all submitted answers. This cannot be undone. The form key remains reserved.",
+            confirmation: {
+              confirmKey: preview.definition.formKey,
+              expectedRevision: preview.revision,
+              expectedSubmissionCount: preview.definition.submissionCount
+            }
+          }
+        )
+      };
+    }
+    const response = await context.client.changeDefinition({
+      ...input,
+      change: action === "delete" ? {
+        action,
+        confirmKey,
+        expectedRevision: revision,
+        expectedSubmissionCount: count
+      } : {
+        action,
+        expectedRevision: revision
+      }
+    });
+    return {
+      exitCode: 0,
+      stdout: stringifySafeJson({ ...response, action, applied: true })
+    };
+  } catch (error) {
+    return formatApiError(error);
+  }
+}
 async function runDefinitionSync(options) {
   const parsed = parseDefinitionSourceFlags(options.args, {
     environmentRequired: true,
@@ -4713,8 +5138,8 @@ function formatApiError(error) {
       error.status ? `Status: ${error.status}` : void 0,
       `Code: ${error.code}`,
       error.message,
-      error.status === 404 && error.code === "NOT_FOUND" ? "The form was not found. Run definition sync before testing submissions." : void 0,
-      error.status === 409 && error.code === "PROJECT_FORM_SUBMISSION_EXISTS" ? "The submission idempotency key was already used. Retry with a new idempotency key." : void 0
+      error.status === 404 && error.code === "NOT_FOUND" ? "Verify the selected Project, Environment and form ID. The server must support this command." : void 0,
+      error.status === 409 && error.code === "PROJECT_FORM_SUBMISSION_EXISTS" ? "The submission idempotency key was already used. Keep it for an unchanged retry and check the existing receipt before sending again." : void 0
     ].filter((line) => Boolean(line));
     return {
       exitCode: 1,
@@ -4883,6 +5308,55 @@ function createFormsUiOutput(input) {
     url
   };
 }
+async function runDeployment(options) {
+  const parsed = parseDefinitionSourceFlags(options.args, {
+    environmentRequired: false,
+    usage: "Usage: siteos forms deploy --manifest <path> [--json]"
+  });
+  if (!parsed.ok) return parsed.error;
+  const loaded = await loadFormDefinitions({
+    cwd: options.cwd,
+    source: parsed.source
+  });
+  if (!loaded.ok) return loaded.error;
+  const env = options.env ?? process.env;
+  const credential = env[SITEOS_FORMS_DEPLOYMENT_KEY_ENV]?.trim();
+  const apiBaseUrl = env.SITEOS_FORMS_PUBLIC_URL?.trim();
+  if (!credential || !/^pfd_[A-Za-z0-9_-]{43}$/.test(credential) || !apiBaseUrl)
+    return {
+      exitCode: 1,
+      stderr: "Configure SITEOS_FORMS_PUBLIC_URL and SITEOS_FORMS_DEPLOYMENT_KEY in the release environment."
+    };
+  try {
+    const client = createSiteOSFormsApiClient({
+      apiBaseUrl,
+      fetchImpl: options.fetchImpl ?? fetch
+    });
+    const result = await client.publishDefinitions({
+      credential,
+      definitions: loaded.definitions.map((item) => item.value)
+    });
+    const expected = new Map(
+      loaded.definitions.map((item) => [
+        item.value.formKey,
+        item.value.sourceExportId
+      ])
+    );
+    if (result.forms.length !== expected.size || new Set(result.forms.map((item) => item.formKey)).size !== expected.size || result.forms.some(
+      (item) => !expected.has(item.formKey) || expected.get(item.formKey) !== item.contractVersion
+    ))
+      return {
+        exitCode: 1,
+        stderr: "The published Forms versions do not match this build."
+      };
+    return {
+      exitCode: 0,
+      stdout: parsed.json ? stringifySafeJson(result) : `Published ${result.forms.length} Forms contracts for Environment ${result.environmentId}.`
+    };
+  } catch (error) {
+    return formatApiError(error);
+  }
+}
 
 // src/package-metadata.ts
 import { readFileSync } from "fs";
@@ -4927,7 +5401,7 @@ var projectSchema = z11.object({
 }).strict();
 var projectListSchema = z11.object({ projects: z11.array(projectSchema) }).strict();
 var projectResponseSchema = z11.object({ project: projectSchema }).strict();
-var deploymentResponseSchema = z11.object({
+var deploymentResponseSchema2 = z11.object({
   checks: z11.array(
     z11.object({
       checkId: z11.string().min(1),
@@ -5032,7 +5506,7 @@ function createPulseApiClient(input) {
         grant: options.grant,
         method: "POST",
         path: "/api/cli/v1/deployments",
-        schema: deploymentResponseSchema
+        schema: deploymentResponseSchema2
       });
     }
   };