@siteoshq/cli 1.2.0 → 1.4.0

package/dist/cli.js

@@ -483,7 +483,8 @@ var siteOSServiceAudienceSchema = z.enum([
   "siteos-cookie",
   "siteos-forms",
   "siteos-pulse",
-  "siteos-search"
+  "siteos-search",
+  "siteos-seo"
 ]);
 var siteOSServiceScopeSchema = z.string().min(1).max(160).regex(/^[a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*){2,}$/);
 var scopeNamespaceByAudience = {
@@ -493,7 +494,8 @@ var scopeNamespaceByAudience = {
   "siteos-cookie": "cookie",
   "siteos-forms": "forms",
   "siteos-pulse": "pulse",
-  "siteos-search": "search"
+  "siteos-search": "search",
+  "siteos-seo": "seo"
 };
 function matchingServiceScopes(value, context) {
   const prefix = `${scopeNamespaceByAudience[value.audience]}:`;
@@ -1442,7 +1444,8 @@ var PROJECT_SERVICES = [
   "cookie",
   "forms",
   "search",
-  "trace"
+  "trace",
+  "seo"
 ];
 var ProjectSchema = z4.object({
   id: z4.string().min(1),
@@ -1496,7 +1499,7 @@ var OverviewSchema = z4.object({
 });
 function createProjectApi(input) {
   const origin = resolveSiteOSAuthBaseUrl(input.env);
-  async function request(path29, schema, body, method) {
+  async function request(path30, schema, body, method) {
     const scope = body === void 0 ? "projects:workspace:read" : "projects:workspace:write";
     const grant = await input.grants.acquire({
       audience: "siteos-projects",
@@ -1510,7 +1513,7 @@ function createProjectApi(input) {
         message: "SiteOS API access is unavailable."
       });
     const response = await input.fetchImpl(
-      `${origin}/api/projects/v1/projects${path29}`,
+      `${origin}/api/projects/v1/projects${path30}`,
       {
         method: method ?? (body === void 0 ? "GET" : "POST"),
         headers: {
@@ -1706,14 +1709,14 @@ async function commonServiceContext(options, service, environmentSlug) {
   const binding = attachment.environments.find(
     (item) => item.environmentId === context.environment.id
   );
-  if (["pulse", "cookie"].includes(service) && !binding)
+  if (["pulse", "cookie", "seo"].includes(service) && !binding)
     throw new SiteOSAuthApiError({
       code: "PROJECT_ENVIRONMENT_NOT_CONFIGURED",
       message: `Set up ${service} in ${context.environment.name} with \`siteos project connect ${service}\`.`
     });
   return {
     ...context,
-    resourceId: ["pulse", "cookie"].includes(service) ? binding.resourceId : attachment.resourceId,
+    resourceId: ["pulse", "cookie", "seo"].includes(service) ? binding.resourceId : attachment.resourceId,
     environmentBinding: binding
   };
 }
@@ -2933,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";
@@ -2968,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),
@@ -2990,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",
@@ -2997,6 +3075,8 @@ var formsErrorCodeSchema = z9.enum([
   "UNAUTHORIZED",
   "IDENTITY_REQUIRED",
   "NOT_ALLOWED",
+  "FORM_ARCHIVED",
+  "FORM_DELETED",
   "NOT_FOUND",
   "PROJECT_NOT_FOUND",
   "PROJECT_CONFLICT",
@@ -3009,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.",
@@ -3016,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.",
@@ -3050,7 +3135,59 @@ function resolveSiteOSFormsBaseUrl(env = process.env) {
 }
 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)}`;
   return {
+    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 },
@@ -3404,25 +3541,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)) {
@@ -3503,6 +3655,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]
@@ -3510,6 +3667,9 @@ 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 submit --input <path> [--json]
 
 Manage SiteOS Forms Environments, definitions, credentials, and submission smoke tests.`;
@@ -3531,6 +3691,8 @@ async function runFormsCommand(options) {
       };
     }
   }
+  if (args2[0] === "submissions")
+    return runSubmissionsCommand({ ...options, args: args2.slice(1) });
   if (args2[0] === "definition") {
     return runDefinitionCommand({
       ...options,
@@ -3574,6 +3736,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)) {
@@ -4014,6 +4266,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,
@@ -4028,6 +4284,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,
@@ -4710,8 +5085,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,
@@ -8752,13 +9127,13 @@ Usage:
   siteos project use <id-or-slug> [--json]
   siteos project update [--name <name>] [--slug <slug>] [--url <production-url>] [--json]
   siteos project status [--json]
-  siteos project connect <pulse|cookie|forms|search|trace> [--resource <id>] [--json]
+  siteos project connect <pulse|cookie|forms|search|trace|seo> [--resource <id>] [--json]
   siteos project environment list [--json]
   siteos project environment create --name <name> --slug <slug> [--url <url>] [--json]
   siteos project environment use <slug> [--json]
   siteos project environment update <slug> [--name <name>] [--url <url>] [--json]
-  siteos project environment resources <pulse|cookie|forms|search|trace> [--json]
-  siteos project environment connect <pulse|cookie|forms|search|trace> --environment <slug> [--resource <id>] [--json]
+  siteos project environment resources <pulse|cookie|forms|search|trace|seo> [--json]
+  siteos project environment connect <pulse|cookie|forms|search|trace|seo> --environment <slug> [--resource <id>] [--json]
 
 Select a Project once per repository. Service commands use its configured resources.
 Connect creates a draft workspace, or explicitly attaches an existing resource.
@@ -8856,7 +9231,7 @@ Run \`siteos project status\` to inspect its services.`;
         const service = parsed.positionals[0];
         if (!PROJECT_SERVICES.includes(service))
           throw new Error(
-            "Choose pulse, cookie, forms, search or trace. Organization connections use `siteos integrations`. "
+            "Choose pulse, cookie, forms, search, trace or seo. Organization connections use `siteos integrations`. "
           );
         overview = await api.connect(
           overview.project.id,
@@ -8912,7 +9287,7 @@ async function runEnvironmentCommand3(options) {
     throw new Error("Environment create requires --name and --slug.");
   const service = positionals[0];
   if ((action === "connect" || action === "resources") && !PROJECT_SERVICES.includes(service))
-    throw new Error("Choose pulse, cookie, forms, search or trace.");
+    throw new Error("Choose pulse, cookie, forms, search, trace or seo.");
   if (action === "connect" && !values.environment)
     throw new Error("Choose a Project environment with --environment <slug>.");
   const context = await readCommonProject(
@@ -9359,6 +9734,382 @@ async function runServiceCommand(service, options) {
   }
 }
 
+// src/services/seo-command.ts
+import { writeFile as writeFile8 } from "fs/promises";
+import path29 from "path";
+import { parseArgs as parseArgs4 } from "util";
+import { z as z16 } from "zod";
+var SEO_HELP = `Audit public HTML in the selected Project environment.
+
+Usage:
+  siteos seo status [--environment <slug>] [--json]
+  siteos seo audit run [--environment <slug>] [--json]
+  siteos seo audit list [--environment <slug>] [--json]
+  siteos seo audit show <id> [--environment <slug>] [--json]
+  siteos seo audit cancel <id> [--environment <slug>] [--json]
+  siteos seo pages [--audit <id>] [--query <text>] [--url <url>] [--page <number>] [--environment <slug>] [--json]
+  siteos seo issues [--audit <id>] [--rule <id>] [--page <number>] [--environment <slug>] [--json]
+  siteos seo changes [--audit <id>] [--state <new|reopened|still_present|resolved|not_rechecked>] [--page <number>] [--environment <slug>] [--json]
+  siteos seo recheck --audit <id> --url <url> [--environment <slug>] [--json]
+  siteos seo issue <ignore|restore> --audit <id> --url <url> --rule <id> --reason <text> --revision <number> [--environment <slug>] [--json]
+  siteos seo schedule show [--environment <slug>] [--json]
+  siteos seo schedule set --enabled <true|false> --weekday <1-7> --time <HH:mm> --timezone <IANA> --revision <number> [--environment <slug>] [--json]
+  siteos seo notifications retry <notification-id> [--environment <slug>] [--json]
+  siteos seo notifications show [--environment <slug>] [--json]
+  siteos seo notifications destinations [--environment <slug>] [--json]
+  siteos seo notifications set --enabled <true|false> [--destination <candidate-id>] --severity <error|warning> --failures <true|false> --revision <number> [--environment <slug>] [--json]
+  siteos seo export --audit <id> --kind <pages|issues|changes> --format <csv|json> --output <new-file> [--query <text>] [--rule <id>] [--severity <error|warning|notice>] [--state <page-or-change-state>] [--environment <slug>] [--json]
+
+Schedule and notification writes require an owner/admin and the saved revision (initially 0).
+Export writes all matching rows to a new file; existing files are never overwritten.
+Runs are queued. Read audit show until terminal; an accepted run is not a completed check.
+Recheck accepts a URL observed in the source audit. Cross-page rules require a full audit.
+Read the current disposition revision before ignore/restore; use 0 if no decision exists.
+Setup: siteos project connect seo. No crawl runs during setup.`;
+async function runSeoCommand(options) {
+  if (!options.args.length || options.args.some((arg) => ["--help", "-h"].includes(arg)))
+    return { exitCode: 0, stdout: SEO_HELP };
+  const json = options.args.includes("--json");
+  try {
+    const { positionals, values } = parseArgs4({
+      args: options.args,
+      strict: true,
+      allowPositionals: true,
+      options: {
+        json: { type: "boolean" },
+        environment: { type: "string" },
+        audit: { type: "string" },
+        url: { type: "string" },
+        rule: { type: "string" },
+        reason: { type: "string" },
+        revision: { type: "string" },
+        query: { type: "string" },
+        page: { type: "string" },
+        state: { type: "string" },
+        enabled: { type: "string" },
+        weekday: { type: "string" },
+        time: { type: "string" },
+        timezone: { type: "string" },
+        destination: { type: "string" },
+        severity: { type: "string" },
+        failures: { type: "string" },
+        kind: { type: "string" },
+        format: { type: "string" },
+        output: { type: "string" }
+      }
+    });
+    const route = positionals.slice(0, 2).join(" ");
+    const action = positionals[0];
+    const operations = {
+      status: { flags: [], args: 1 },
+      "schedule show": { flags: [], args: 2 },
+      "schedule set": {
+        flags: ["enabled", "weekday", "time", "timezone", "revision"],
+        args: 2
+      },
+      "notifications retry": { flags: [], args: 3 },
+      "notifications show": { flags: [], args: 2 },
+      "notifications destinations": { flags: [], args: 2 },
+      "notifications set": {
+        flags: ["enabled", "destination", "severity", "failures", "revision"],
+        args: 2
+      },
+      export: {
+        flags: [
+          "audit",
+          "kind",
+          "format",
+          "output",
+          "query",
+          "rule",
+          "severity",
+          "state"
+        ],
+        args: 1
+      },
+      "audit run": { flags: [], args: 2 },
+      "audit list": { flags: [], args: 2 },
+      "audit show": { flags: [], args: 3 },
+      "audit cancel": { flags: [], args: 3 },
+      pages: { flags: ["audit", "url", "query", "page"], args: 1 },
+      issues: { flags: ["audit", "rule", "page"], args: 1 },
+      changes: { flags: ["audit", "state", "page"], args: 1 },
+      recheck: { flags: ["audit", "url"], args: 1 },
+      "issue ignore": {
+        flags: ["audit", "url", "rule", "reason", "revision"],
+        args: 2
+      },
+      "issue restore": {
+        flags: ["audit", "url", "rule", "reason", "revision"],
+        args: 2
+      }
+    };
+    const operation = operations[route];
+    if (!operation || positionals.length !== operation.args || Object.keys(values).some(
+      (key) => !["json", "environment", ...operation.flags].includes(key)
+    ))
+      throw new Error(
+        "Invalid SEO operation or flags. Run `siteos seo --help`."
+      );
+    if (action === "recheck" && (!values.audit || !values.url))
+      throw new Error("Recheck requires --audit and --url.");
+    if (action === "issue" && ["audit", "url", "rule", "reason", "revision"].some(
+      (key) => !values[key]
+    ))
+      throw new Error(
+        "Issue decisions require --audit, --url, --rule, --reason and --revision."
+      );
+    if (values.page && !/^[1-9]\d{0,5}$/u.test(values.page))
+      throw new Error("Use a positive page number.");
+    if (values.revision && !/^\d{1,9}$/u.test(values.revision))
+      throw new Error("Use a non-negative revision.");
+    if (values.reason && (values.reason.trim().length < 3 || values.reason.length > 500))
+      throw new Error("Use a reason between 3 and 500 characters.");
+    const pageStateFilter = action === "export" && values.kind !== "changes";
+    if (values.state && !(pageStateFilter ? ["analyzed", "unavailable", "excluded", "non_html"] : ["new", "reopened", "still_present", "resolved", "not_rechecked"]).includes(values.state))
+      throw new Error("Use a documented page or change state for this export.");
+    const automation = ["schedule", "notifications"].includes(action ?? "");
+    const setting = automation && positionals[1] === "set";
+    if (setting && (!values.revision || !["true", "false"].includes(values.enabled ?? "")))
+      throw new Error("Settings require --enabled true|false and --revision.");
+    if (route === "schedule set") {
+      if (!/^[1-7]$/u.test(values.weekday ?? "") || !/^([01]\d|2[0-3]):[0-5]\d$/u.test(values.time ?? "") || !values.timezone)
+        throw new Error("Use weekday 1\u20137, HH:mm and an IANA time zone.");
+      try {
+        new Intl.DateTimeFormat("en", { timeZone: values.timezone });
+      } catch {
+        throw new Error("Use a valid IANA time zone.");
+      }
+    }
+    if (route === "notifications set" && (!["error", "warning"].includes(values.severity ?? "") || !["true", "false"].includes(values.failures ?? "") || values.enabled === "true" && !values.destination))
+      throw new Error(
+        "Notifications require --severity, --failures and an available --destination when enabled."
+      );
+    if (action === "export" && (!values.audit || !["pages", "issues", "changes"].includes(values.kind ?? "") || !["csv", "json"].includes(values.format ?? "") || !values.output))
+      throw new Error(
+        "Export requires --audit, --kind, --format and --output."
+      );
+    if (values.severity && !["error", "warning", "notice"].includes(values.severity))
+      throw new Error("Use a documented severity.");
+    const context = await commonServiceContext(
+      options,
+      "seo",
+      values.environment
+    );
+    if (!context)
+      throw new Error(
+        "Select a SiteOS Project with `siteos project use` first."
+      );
+    const runtime = commonProjectRuntime(options);
+    const retryNotification = route === "notifications retry";
+    const writing = retryNotification || setting || [
+      "audit run",
+      "audit cancel",
+      "recheck",
+      "issue ignore",
+      "issue restore"
+    ].includes(route);
+    const scope = retryNotification ? "seo:notifications:write" : setting ? action === "schedule" ? "seo:schedule:write" : "seo:notifications:write" : !writing ? "seo:workspace:read" : action === "issue" ? "seo:issues:write" : "seo:audits:write";
+    const grant = await runtime.grants.acquire({
+      audience: "siteos-seo",
+      scopes: [scope]
+    });
+    if (grant.grant.audience !== "siteos-seo" || grant.grant.scopes.length !== 1 || grant.grant.scopes[0] !== scope || grant.grant.organizationId !== context.overview.project.organizationId)
+      throw new SiteOSAuthApiError({
+        code: "AUTH_INVALID_RESPONSE",
+        message: "The SEO grant does not match this Project and operation."
+      });
+    const query = new URLSearchParams();
+    for (const [flag, name] of [
+      ["audit", "audit"],
+      ["rule", "rule"],
+      ["query", "q"],
+      ["url", "pageUrl"],
+      ["page", "page"],
+      ["state", "change"],
+      ["kind", "kind"],
+      ["format", "format"],
+      ["severity", "severity"]
+    ])
+      if (values[flag] && !writing) query.set(name, values[flag]);
+    if (pageStateFilter && values.state) {
+      query.delete("change");
+      query.set("state", values.state);
+    }
+    if (route === "audit show") query.set("audit", positionals[2]);
+    const suffix = retryNotification ? "/notification-retries" : automation ? setting ? `/${action}` : route === "notifications destinations" ? "/destinations" : "/automation" : action === "export" ? `/export?${query}` : route === "audit run" ? "/audits" : route === "audit cancel" ? `/audits/${encodeURIComponent(positionals[2])}/cancel` : action === "recheck" ? "/rechecks" : action === "issue" ? "/dispositions" : `?${query}`;
+    const body = retryNotification ? { notificationId: positionals[2] } : route === "schedule set" ? {
+      enabled: values.enabled === "true",
+      weekday: Number(values.weekday),
+      time: values.time,
+      timeZone: values.timezone,
+      expectedRevision: Number(values.revision)
+    } : route === "notifications set" ? {
+      enabled: values.enabled === "true",
+      candidateId: values.destination ?? null,
+      minimumSeverity: values.severity,
+      includeFailures: values.failures === "true",
+      expectedRevision: Number(values.revision)
+    } : action === "recheck" ? { auditId: values.audit, urls: [values.url] } : action === "issue" ? {
+      auditId: values.audit,
+      url: values.url,
+      ruleId: values.rule,
+      reason: values.reason,
+      expectedRevision: Number(values.revision),
+      ignored: positionals[1] === "ignore"
+    } : void 0;
+    if (!options.fetchImpl)
+      throw new Error("SiteOS API access is unavailable.");
+    const response = await options.fetchImpl(
+      `${runtime.api.origin}/api/seo/v1/resources/${encodeURIComponent(context.resourceId)}${suffix}`,
+      {
+        method: setting ? "PATCH" : writing ? "POST" : "GET",
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${grant.accessToken}`,
+          ...body ? { "Content-Type": "application/json" } : {}
+        },
+        ...body ? { body: JSON.stringify(body) } : {},
+        signal: AbortSignal.timeout(3e4)
+      }
+    );
+    if (action === "export" && response.ok) {
+      if (!(response instanceof Response))
+        throw new Error("The API transport does not support file exports.");
+      const mime = values.format === "csv" ? "text/csv" : "application/json";
+      const rows = Number(response.headers.get("X-SEO-Export-Rows"));
+      if (response.headers.get("X-SEO-Audit-Id") !== values.audit || !response.headers.get("Content-Type")?.startsWith(mime) || !response.headers.has("X-SEO-Export-Rows") || !Number.isSafeInteger(rows) || rows < 0)
+        throw new Error(
+          "The export response does not match the requested audit."
+        );
+      const text = await response.text();
+      if (values.format === "json")
+        z16.object({
+          contractVersion: z16.literal(1),
+          audit: z16.object({
+            id: z16.literal(values.audit),
+            resourceId: z16.literal(context.resourceId)
+          }),
+          kind: z16.literal(values.kind),
+          totalRows: z16.literal(rows),
+          rows: z16.array(z16.unknown()).length(rows)
+        }).parse(JSON.parse(text));
+      const output = path29.resolve(options.cwd ?? process.cwd(), values.output);
+      await writeFile8(output, text, { flag: "wx", mode: 384 });
+      return {
+        exitCode: 0,
+        stdout: JSON.stringify(
+          {
+            auditId: values.audit,
+            kind: values.kind,
+            format: values.format,
+            rows,
+            output
+          },
+          null,
+          2
+        )
+      };
+    }
+    const data = await response.json();
+    if (!response.ok) {
+      const result = z16.object({
+        error: z16.object({ code: z16.string(), message: z16.string().max(500) })
+      }).safeParse(data);
+      throw new SiteOSAuthApiError({
+        code: result.success ? result.data.error.code : "SEO_REQUEST_FAILED",
+        message: result.success ? result.data.error.message : "The SEO request failed.",
+        status: response.status
+      });
+    }
+    const record = z16.object({ contractVersion: z16.literal(1) }).passthrough().parse(data);
+    if (automation) {
+      z16.literal(context.resourceId).parse(record.resourceId);
+      const schedule = z16.object({
+        enabled: z16.boolean(),
+        weekday: z16.number().int().min(1).max(7),
+        time: z16.string(),
+        timeZone: z16.string(),
+        revision: z16.number().int().min(0),
+        nextRunAt: z16.string().nullable()
+      });
+      const notificationRoute = z16.object({
+        enabled: z16.boolean(),
+        minimumSeverity: z16.enum(["error", "warning"]),
+        includeFailures: z16.boolean(),
+        revision: z16.number().int().min(0),
+        destinationId: z16.string().nullable()
+      });
+      if (retryNotification) {
+        z16.literal(true).parse(record.retryQueued);
+        z16.literal(positionals[2]).parse(record.notificationId);
+      } else if (route === "notifications destinations")
+        z16.object({
+          candidates: z16.array(
+            z16.object({
+              candidateId: z16.string(),
+              label: z16.string(),
+              availability: z16.literal("available")
+            })
+          )
+        }).parse(record);
+      else if (setting) {
+        const value = action === "schedule" ? schedule.parse(record.schedule) : notificationRoute.parse(record.route);
+        if (value.revision !== Number(values.revision) + 1 || value.enabled !== (values.enabled === "true"))
+          throw new Error("The saved settings do not match this change.");
+      } else {
+        schedule.parse(record.schedule);
+        notificationRoute.parse(record.route);
+      }
+    } else if (!writing) {
+      const validated = z16.object({
+        resource: z16.object({
+          id: z16.literal(context.resourceId),
+          organizationId: z16.literal(context.overview.project.organizationId)
+        }),
+        audits: z16.array(z16.object({ id: z16.string() }).passthrough()),
+        audit: z16.object({
+          id: z16.string(),
+          resourceId: z16.literal(context.resourceId)
+        }).passthrough().nullable(),
+        pages: z16.array(z16.unknown()),
+        issues: z16.array(z16.unknown()),
+        changes: z16.array(z16.unknown()),
+        totalChanges: z16.number(),
+        dispositions: z16.array(z16.unknown())
+      }).passthrough().parse(record);
+      const selected = query.get("audit");
+      if (selected && validated.audit?.id !== selected)
+        throw new Error("The SEO response does not match the requested audit.");
+    } else if (record.audit)
+      z16.object({
+        id: z16.string(),
+        resourceId: z16.literal(context.resourceId),
+        organizationId: z16.literal(context.overview.project.organizationId),
+        state: z16.literal("queued")
+      }).parse(record.audit);
+    else if (route === "audit cancel") z16.literal(true).parse(record.cancelled);
+    else if (action === "issue")
+      z16.object({
+        url: z16.literal(values.url),
+        ruleId: z16.literal(values.rule),
+        ignored: z16.literal(positionals[1] === "ignore"),
+        revision: z16.literal(Number(values.revision) + 1)
+      }).parse(record.disposition);
+    else throw new Error("The SEO service returned an invalid response.");
+    return { exitCode: 0, stdout: JSON.stringify(record, null, 2) };
+  } catch (cause) {
+    const error = {
+      code: cause instanceof SiteOSAuthApiError ? cause.code : "SEO_COMMAND_FAILED",
+      message: cause instanceof z16.ZodError ? "The SEO service returned an invalid response." : cause instanceof Error ? cause.message : "The SEO command failed."
+    };
+    return {
+      exitCode: cause instanceof SiteOSAuthApiError ? 1 : 2,
+      ...json ? { stdout: JSON.stringify({ error }) } : { stderr: error.message }
+    };
+  }
+}
+
 // src/cli.ts
 var [command, ...args] = process.argv.slice(2);
 var HELP_FLAGS5 = /* @__PURE__ */ new Set(["--help", "-h"]);
@@ -9392,6 +10143,12 @@ if (!command || command === "--help" || command === "-h") {
 }
 function rootCommandRegistry() {
   return createCommandRegistry({
+    seo: (args2) => runSeoCommand({
+      args: args2,
+      cwd: process.cwd(),
+      env: process.env,
+      fetchImpl: globalThis.fetch
+    }),
     "health-check": runHealthCheck,
     project: (args2) => runProjectCommand4({
       args: args2,
@@ -9499,6 +10256,7 @@ Usage:
   siteos project --help
   siteos cookie --help
   siteos trace --help
+  siteos seo --help
   siteos integrations --help
   siteos pulse --help
   siteos search --help
@@ -9510,6 +10268,7 @@ Commands:
   project       Select one Project and configure its services and environments.
   cookie        Configure, publish, and inspect the Project\u2019s cookie banner.
   trace         Configure analytics observation and inspect evidence.
+  seo           Audit HTML, inspect changes and verify fixes.
   integrations  Manage Organization connections and destinations.
   pulse         Manage monitoring checks, tests, and deployments.
   search        Run SiteOS search operations for a project environment.