@siteoshq/cli 1.4.0 → 1.5.0

package/README.md

@@ -267,3 +267,17 @@ answers from the working database, retaining only a reserved-key tombstone. That
 reused. Shared Environment credentials remain active for other forms. Sync refuses archived/deleted
 keys and never removes forms missing from a local manifest. Backups follow deployment retention;
 they are not an in-app restore mechanism.
+
+### Automatic Forms deployment
+
+Generate Forms JSON from the shared host validation schema during build. Install a release-only
+key once with `siteos forms deployment-key issue --environment production --install --json`.
+Store `SITEOS_FORMS_DEPLOYMENT_KEY` in the CI secret store and configure explicit
+`SITEOS_FORMS_PUBLIC_URL`. Keep the submission credential on the website server.
+
+Run `siteos forms deploy --manifest .siteos/forms/manifest.json --json` before routing traffic to a
+new release. This needs no interactive Auth or local Project state and publishes atomically.
+Definitions include a generated SHA-256 `sourceExportId`; runtime sends it as `contractVersion`.
+A changed field requires a normal build/release, not a second hand-edited validation schema.
+`forms deployment-key list|revoke` manages release keys; submission keys cannot publish.
+See the SiteOS Forms skill for the portable generator and version serialization contract.

package/dist/cli.js

@@ -3133,11 +3133,33 @@ 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,
@@ -3212,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,
@@ -3236,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({
@@ -3244,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({
@@ -3254,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,
@@ -3288,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({
@@ -3381,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) {
@@ -3393,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 {
@@ -3419,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
           });
@@ -3457,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"
     );
@@ -3485,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) => {
@@ -3670,6 +3698,10 @@ var FORMS_HELP = `Usage:
   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.`;
@@ -3681,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);
@@ -3717,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,
@@ -4052,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({
@@ -4123,7 +4169,7 @@ Environment: ${parsed.environmentSlug}`
       credential,
       environment: parsed.environmentSlug,
       installed: {
-        variable: SITEOS_FORMS_SUBMISSION_CREDENTIAL_ENV
+        variable
       },
       operation: action === "issue" ? "issued" : "rotated"
     };
@@ -4133,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) {
@@ -4144,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,
@@ -5255,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";
@@ -5299,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),
@@ -5404,7 +5506,7 @@ function createPulseApiClient(input) {
         grant: options.grant,
         method: "POST",
         path: "/api/cli/v1/deployments",
-        schema: deploymentResponseSchema
+        schema: deploymentResponseSchema2
       });
     }
   };