@siteoshq/cli 1.1.1 → 1.3.0

package/dist/cli.js

@@ -1,4 +1,438 @@
 #!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/services/cookie-verification.ts
+var cookie_verification_exports = {};
+__export(cookie_verification_exports, {
+  VerificationInstallation: () => VerificationInstallation,
+  assessCookieObservations: () => assessCookieObservations,
+  verificationTarget: () => verificationTarget,
+  verifyCookieWebsite: () => verifyCookieWebsite
+});
+import { z as z14 } from "zod";
+function verificationTarget(websiteUrl, candidate) {
+  const website = new URL(websiteUrl);
+  const target = new URL(candidate ?? websiteUrl, website);
+  if (target.origin !== website.origin || target.username || target.password || target.hash || !["https:", "http:"].includes(target.protocol))
+    throw new Error(
+      "Verify a URL on the selected Project environment's origin, without credentials or fragments."
+    );
+  return target.toString();
+}
+function matchesName(value, names) {
+  return Boolean(
+    names && (names.exact.includes(value) || names.prefixes.some((prefix) => value.startsWith(prefix)))
+  );
+}
+function assessCookieObservations(input) {
+  const issues = [];
+  const unknownOrigins = /* @__PURE__ */ new Set();
+  const unknownStorage = /* @__PURE__ */ new Set();
+  const services = input.envelope.config.services;
+  for (const request of input.requests) {
+    const matches = services.filter(
+      (service) => service.lifecycle && [
+        ...service.lifecycle.scriptOrigins,
+        ...service.lifecycle.iframeOrigins,
+        ...service.lifecycle.pixelOrigins
+      ].some((url) => new URL(url).origin === request.origin)
+    );
+    const state = input.observations.find(
+      (item) => item.scenario === request.scenario
+    )?.state;
+    if (matches.length) {
+      const allowed = matches.some(
+        (service) => state?.services.find((item) => item.key === service.key)?.allowed
+      );
+      const advancedGoogle = input.envelope.config.integrations.googleConsentMode === "advanced" && matches.every(
+        (service) => ["google-analytics", "google-ads"].includes(service.key)
+      );
+      if (!allowed && !advancedGoogle)
+        issues.push({
+          code: "request_without_permission",
+          scenario: request.scenario,
+          detail: request.origin
+        });
+    } else if (request.origin !== input.firstPartyOrigin && !input.deliveryOrigins.includes(request.origin))
+      unknownOrigins.add(request.origin);
+  }
+  for (const observation of input.observations) {
+    for (const service of services) {
+      const allowed = observation.state.services.find(
+        (item) => item.key === service.key
+      )?.allowed;
+      const stored = observation.cookies.some(
+        (name) => matchesName(name, service.lifecycle?.firstPartyCookies)
+      ) || observation.localStorage.some(
+        (name) => matchesName(name, service.lifecycle?.localStorage)
+      );
+      if (!allowed && stored)
+        issues.push({
+          code: "storage_without_permission",
+          scenario: observation.scenario,
+          detail: service.key
+        });
+    }
+    for (const name of observation.cookies) {
+      if (name !== "siteos_consent" && !services.some(
+        (service) => matchesName(name, service.lifecycle?.firstPartyCookies)
+      ))
+        unknownStorage.add(`cookie:${name}`);
+    }
+    for (const name of observation.localStorage) {
+      if (!name.startsWith("siteos-cookie:") && !services.some(
+        (service) => matchesName(name, service.lifecycle?.localStorage)
+      ))
+        unknownStorage.add(`localStorage:${name}`);
+    }
+  }
+  return {
+    issues,
+    unknownOrigins: [...unknownOrigins].sort(),
+    unknownStorage: [...unknownStorage].sort()
+  };
+}
+async function verifyCookieWebsite(input) {
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const issues = [];
+  const requests = [];
+  const observations = [];
+  let envelope = null;
+  let scenario = "first-visit";
+  let overflow = false;
+  const installation = input.installation;
+  const browser = await (input.launch ?? (async () => {
+    const playwright = await import("playwright");
+    try {
+      return await playwright[input.browserName].launch({ headless: true });
+    } catch {
+      throw new Error(
+        `The ${input.browserName} browser is unavailable. Run npx playwright@1.61.1 install ${input.browserName}, then retry.`
+      );
+    }
+  }))();
+  const readState = async (page) => State.parse(
+    await page.evaluate(
+      () => window.SiteOSCookie.getDebugState()
+    )
+  );
+  const waitForRuntime = async (page) => {
+    await page.waitForFunction(
+      () => Boolean(
+        window.SiteOSCookie?.getDebugState().resolved
+      ),
+      void 0,
+      { timeout: 15e3 }
+    );
+  };
+  try {
+    for (const gpc of [false, true]) {
+      const context = await browser.newContext({
+        serviceWorkers: "block",
+        ...gpc ? { extraHTTPHeaders: { "Sec-GPC": "1" } } : {}
+      });
+      if (gpc)
+        await context.addInitScript(
+          () => Object.defineProperty(navigator, "globalPrivacyControl", {
+            get: () => true
+          })
+        );
+      const page = await context.newPage();
+      page.setDefaultTimeout(15e3);
+      page.setDefaultNavigationTimeout(25e3);
+      const pending = /* @__PURE__ */ new Set();
+      page.on("request", (request) => {
+        if (!/^https?:/u.test(request.url())) return;
+        if (requests.length >= 2e3) {
+          overflow = true;
+          return;
+        }
+        requests.push({
+          origin: new URL(request.url()).origin,
+          type: request.resourceType(),
+          scenario
+        });
+      });
+      page.on("response", (response) => {
+        const expectedUrl = new URL(installation.delivery.configUrl);
+        const responseUrl = new URL(response.url());
+        if (responseUrl.origin !== expectedUrl.origin || responseUrl.pathname !== expectedUrl.pathname)
+          return;
+        const responseScenario = scenario;
+        const reading = (async () => {
+          let timeout;
+          try {
+            const raw = await Promise.race([
+              response.body(),
+              new Promise((_, reject) => {
+                timeout = setTimeout(() => reject(new Error("timeout")), 5e3);
+              })
+            ]);
+            if (raw.byteLength > 512 * 1024) throw new Error("size");
+            const parsed = Envelope.parse(JSON.parse(raw.toString()));
+            if (parsed.publicKey !== installation.publicKey || parsed.revision !== installation.currentPublishedRevision)
+              throw new Error("revision");
+            envelope = parsed;
+          } catch {
+            issues.push({
+              code: "configuration_mismatch",
+              scenario: responseScenario,
+              detail: "Configuration is unavailable, invalid, or differs from the published revision."
+            });
+          } finally {
+            clearTimeout(timeout);
+          }
+        })();
+        pending.add(reading);
+        void reading.finally(() => pending.delete(reading));
+      });
+      scenario = gpc ? "gpc-first-visit" : "first-visit";
+      try {
+        await page.goto(input.url, { waitUntil: "domcontentloaded" });
+        if (new URL(page.url()).origin !== new URL(input.url).origin)
+          throw new Error("The website redirected to another origin.");
+        await waitForRuntime(page);
+        await Promise.all([...pending]);
+        const capture = async () => {
+          await page.waitForTimeout(1500);
+          if (new URL(page.url()).origin !== new URL(input.url).origin)
+            throw new Error("The website navigated to another origin.");
+          await waitForRuntime(page);
+          const state = await readState(page);
+          if (state.preview || state.resolved?.publicKey !== installation.publicKey || state.resolved?.revision !== installation.currentPublishedRevision)
+            issues.push({
+              code: "runtime_mismatch",
+              scenario,
+              detail: "The loaded runtime is a preview or uses another publication."
+            });
+          if (Number(state.runtimeVersion.split(".")[0]) < 11)
+            issues.push({
+              code: "runtime_outdated",
+              scenario,
+              detail: state.runtimeVersion
+            });
+          observations.push({
+            scenario,
+            state,
+            cookies: [
+              ...new Set(
+                (await context.cookies()).map((cookie) => cookie.name)
+              )
+            ].sort(),
+            localStorage: await page.evaluate(
+              () => Object.keys(localStorage).sort()
+            )
+          });
+        };
+        await capture();
+        if (gpc) {
+          const state = observations.at(-1).state;
+          if (!state.consent.globalPrivacyControl || !state.consent.privacyChoices.saleOrShareOptOut || !state.consent.privacyChoices.targetedAdvertisingOptOut)
+            issues.push({
+              code: "gpc_not_applied",
+              scenario,
+              detail: "GPC must be visible and both privacy opt-outs applied."
+            });
+        } else {
+          for (const action of [
+            "reject",
+            "accept",
+            "granular",
+            "withdraw"
+          ]) {
+            scenario = action;
+            try {
+              await page.evaluate(async (choice) => {
+                const api = window.SiteOSCookie;
+                if (choice === "accept") await api.acceptAll();
+                else if (choice === "granular")
+                  await api.updateConsent(
+                    api.getConsent().categories.filter((key) => key !== "necessary").slice(0, 1)
+                  );
+                else await api.rejectAll();
+              }, action);
+            } catch (error) {
+              if (!(error instanceof Error) || !/Execution context was destroyed/u.test(error.message))
+                throw error;
+            }
+            await capture();
+            const state = observations.at(-1).state;
+            if ((action === "reject" || action === "withdraw") && state.consent.categories.some((key) => key !== "necessary"))
+              issues.push({
+                code: "refusal_not_applied",
+                scenario,
+                detail: "Optional categories remain granted."
+              });
+          }
+          scenario = "returning-after-refusal";
+          await page.reload({ waitUntil: "domcontentloaded" });
+          await capture();
+          if (observations.at(-1).state.consent.categories.some((key) => key !== "necessary"))
+            issues.push({
+              code: "refusal_not_persisted",
+              scenario,
+              detail: "Refusal was not preserved across reload."
+            });
+        }
+      } catch {
+        issues.push({
+          code: "scenario_incomplete",
+          scenario,
+          detail: "The page or Cookie runtime did not complete this scenario within the time limit."
+        });
+      } finally {
+        await context.close();
+        await Promise.all([...pending]);
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+  const assessment = envelope ? assessCookieObservations({
+    envelope,
+    observations,
+    requests,
+    firstPartyOrigin: new URL(input.url).origin,
+    deliveryOrigins: Object.values(installation.delivery).filter((url) => typeof url === "string").map((url) => new URL(url).origin)
+  }) : { issues: [], unknownOrigins: [], unknownStorage: [] };
+  issues.push(...assessment.issues);
+  if (!envelope)
+    issues.push({
+      code: "configuration_not_observed",
+      scenario: "all",
+      detail: "No matching public configuration response was observed."
+    });
+  if (overflow)
+    issues.push({
+      code: "request_limit",
+      scenario: "all",
+      detail: "The request limit was reached; this run is incomplete."
+    });
+  const config = envelope;
+  const status = issues.length ? "failed" : assessment.unknownOrigins.length || assessment.unknownStorage.length || config?.config.integrations.googleConsentMode === "advanced" ? "needs-review" : "passed";
+  return {
+    schemaVersion: 1,
+    status,
+    startedAt,
+    completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1e3).toISOString(),
+    target: {
+      origin: new URL(input.url).origin,
+      path: new URL(input.url).pathname
+    },
+    browser: input.browserName,
+    publicKey: installation.publicKey,
+    revision: installation.currentPublishedRevision,
+    region: config?.trustedSignals?.region ?? null,
+    issues: [
+      ...new Map(
+        issues.map((issue) => [JSON.stringify(issue), issue])
+      ).values()
+    ],
+    unknownOrigins: assessment.unknownOrigins,
+    unknownStorage: assessment.unknownStorage,
+    observations,
+    requestCounts: [
+      ...new Set(requests.map((item) => `${item.scenario} ${item.origin}`))
+    ].map((key) => ({
+      scenario: key.split(" ")[0],
+      origin: key.split(" ")[1],
+      count: requests.filter(
+        (item) => `${item.scenario} ${item.origin}` === key
+      ).length
+    })),
+    limits: [
+      "One route, fresh local browser, 1.5-second observation per scenario, at most 2000 requests.",
+      "Consent actions use the public runtime API. Visual, keyboard and GTM Tag Assistant acceptance remain separate.",
+      "Unknown origins/storage need classification. First-party or server-side tracking and delayed/interaction-only resources require a source audit.",
+      "Geography is this browser's actual Edge location. Use regions resolve for simulations; do not spoof production geography.",
+      "No cookie values, request query strings, bodies, credentials or visitor identifiers are included. A pass covers only the observed scope, not legal compliance."
+    ]
+  };
+}
+var Names, Service, Envelope, State, VerificationInstallation;
+var init_cookie_verification = __esm({
+  "src/services/cookie-verification.ts"() {
+    "use strict";
+    Names = z14.object({
+      exact: z14.array(z14.string()),
+      prefixes: z14.array(z14.string())
+    });
+    Service = z14.object({
+      key: z14.string(),
+      purposeKey: z14.string(),
+      lifecycle: z14.object({
+        scriptOrigins: z14.array(z14.string()),
+        iframeOrigins: z14.array(z14.string()),
+        pixelOrigins: z14.array(z14.string()),
+        firstPartyCookies: Names,
+        localStorage: Names
+      }).optional()
+    });
+    Envelope = z14.object({
+      publicKey: z14.string(),
+      revision: z14.number(),
+      ruleKey: z14.string(),
+      profileKey: z14.string(),
+      trustedSignals: z14.object({
+        region: z14.object({
+          countryCode: z14.string().nullable(),
+          subdivisionCode: z14.string().nullable()
+        }).optional()
+      }).optional(),
+      config: z14.object({
+        services: z14.array(Service),
+        categories: z14.array(z14.object({ key: z14.string(), required: z14.boolean() })),
+        integrations: z14.object({ googleConsentMode: z14.string() })
+      })
+    });
+    State = z14.object({
+      runtimeVersion: z14.string(),
+      preview: z14.boolean(),
+      resolved: z14.object({
+        publicKey: z14.string(),
+        revision: z14.number(),
+        ruleKey: z14.string(),
+        profileKey: z14.string()
+      }).nullable(),
+      consent: z14.object({
+        categories: z14.array(z14.string()),
+        decision: z14.string(),
+        globalPrivacyControl: z14.boolean(),
+        privacyChoices: z14.object({
+          saleOrShareOptOut: z14.boolean(),
+          targetedAdvertisingOptOut: z14.boolean()
+        })
+      }),
+      services: z14.array(
+        z14.object({
+          key: z14.string(),
+          allowed: z14.boolean(),
+          footprintPresent: z14.boolean()
+        })
+      )
+    });
+    VerificationInstallation = z14.object({
+      publicKey: z14.string(),
+      currentPublishedRevision: z14.number().int().positive(),
+      delivery: z14.object({
+        runtimeUrl: z14.string().url(),
+        configUrl: z14.string().url(),
+        analyticsUrl: z14.string().url().nullable(),
+        receiptsUrl: z14.string().url(),
+        handshakeUrl: z14.string().url()
+      })
+    });
+  }
+});
 
 // src/health-check.ts
 import path10 from "path";
@@ -49,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 = {
@@ -59,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]}:`;
@@ -1008,7 +1444,8 @@ var PROJECT_SERVICES = [
   "cookie",
   "forms",
   "search",
-  "trace"
+  "trace",
+  "seo"
 ];
 var ProjectSchema = z4.object({
   id: z4.string().min(1),
@@ -1062,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",
@@ -1076,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: {
@@ -1272,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
   };
 }
@@ -8318,13 +8755,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.
@@ -8422,7 +8859,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,
@@ -8478,7 +8915,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(
@@ -8563,13 +9000,18 @@ async function runEnvironmentCommand3(options) {
 import { readFile as readFile16, stat } from "fs/promises";
 import path28 from "path";
 import { parseArgs as parseArgs3 } from "util";
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 var SERVICE_HELP = {
   cookie: `Manage Cookie for the selected SiteOS Project.
 
 Usage:
   siteos cookie status [--json]
   siteos cookie installation [--json]
+  siteos cookie schema [--json]
+  siteos cookie validate --input <draft.json> [--json]
+  siteos cookie regions resolve [--country <ISO>] [--subdivision <code>] [--source <draft|published>] [--json]
+  siteos cookie verify [--url <same-origin-url>] [--browser <chromium|webkit>] [--json]
+  siteos cookie restore --input <restore.json> [--json]
   siteos cookie draft get [--json]
   siteos cookie draft save --input <draft.json> [--json]
   siteos cookie publish --input <publication.json> [--json]
@@ -8618,7 +9060,12 @@ async function runServiceCommand(service, options) {
         "range-days": { type: "string" },
         query: { type: "string" },
         cursor: { type: "string" },
-        channel: { type: "string" }
+        channel: { type: "string" },
+        country: { type: "string" },
+        subdivision: { type: "string" },
+        source: { type: "string" },
+        url: { type: "string" },
+        browser: { type: "string" }
       }
     });
     const [action, subaction] = positionals;
@@ -8627,6 +9074,11 @@ async function runServiceCommand(service, options) {
       cookie: {
         status: [],
         installation: [],
+        schema: [],
+        validate: ["input"],
+        "regions resolve": ["country", "subdivision", "source"],
+        verify: ["url", "browser"],
+        restore: ["input"],
         "draft get": [],
         "draft save": ["input"],
         publish: ["input"],
@@ -8706,8 +9158,8 @@ async function runServiceCommand(service, options) {
       );
       const result2 = await response.json();
       if (!response.ok) {
-        const error = z14.object({
-          error: z14.object({ code: z14.string(), message: z14.string().max(500) })
+        const error = z15.object({
+          error: z15.object({ code: z15.string(), message: z15.string().max(500) })
         }).safeParse(result2);
         throw new SiteOSAuthApiError({
           code: error.success ? error.data.error.code : "SERVICE_REQUEST_FAILED",
@@ -8731,14 +9183,60 @@ async function runServiceCommand(service, options) {
     if (service === "cookie") {
       if (action === "status" && positionals.length === 1)
         result = await request(site);
-      else if (action === "installation")
+      else if (action === "schema") result = await request(`${site}/schema`);
+      else if (action === "validate") {
+        result = await request(
+          `${site}/validate`,
+          "POST",
+          await inputFile(),
+          "cookie:workspace:read"
+        );
+        const validation = z15.object({
+          valid: z15.boolean(),
+          draftVersionMatches: z15.boolean().optional()
+        }).parse(result);
+        if (!validation.valid || validation.draftVersionMatches === false)
+          return { exitCode: 2, stdout: JSON.stringify(result, null, 2) };
+      } else if (action === "restore")
+        result = await request(`${site}/restore`, "POST", await inputFile());
+      else if (action === "regions") {
+        const query = new URLSearchParams();
+        for (const key of ["country", "subdivision", "source"])
+          if (values[key]) query.set(key, values[key]);
+        result = await request(`${site}/regions?${query}`);
+      } else if (action === "verify") {
+        const {
+          VerificationInstallation: VerificationInstallation2,
+          verificationTarget: verificationTarget2,
+          verifyCookieWebsite: verifyCookieWebsite2
+        } = await Promise.resolve().then(() => (init_cookie_verification(), cookie_verification_exports));
+        const browserName = values.browser ?? "chromium";
+        if (browserName !== "chromium" && browserName !== "webkit")
+          throw new Error("Choose chromium or webkit.");
+        if (!common.environment.url)
+          throw new Error(
+            "Set the selected Project environment URL before verification."
+          );
+        const url = verificationTarget2(common.environment.url, values.url);
+        result = await verifyCookieWebsite2({
+          installation: VerificationInstallation2.parse(
+            await request(`${site}/installation`)
+          ),
+          url,
+          browserName
+        });
+        return {
+          exitCode: result.status === "passed" ? 0 : 1,
+          stdout: JSON.stringify(result, null, 2)
+        };
+      } else if (action === "installation")
         result = await request(`${site}/installation`);
       else if (action === "draft" && subaction === "get" && positionals.length === 2) {
-        const response = z14.object({
-          name: z14.string(),
-          hostname: z14.string(),
-          draftVersion: z14.number(),
-          draft: z14.unknown()
+        const response = z15.object({
+          name: z15.string(),
+          hostname: z15.string(),
+          draftVersion: z15.number(),
+          draft: z15.unknown()
         }).parse(await request(site));
         result = {
           name: response.name,
@@ -8770,9 +9268,9 @@ async function runServiceCommand(service, options) {
       else if (action === "environments" && positionals.length === 1)
         result = await request(`${site}/environments`);
       else if (action === "report" || action === "installation" || action === "tracking-plan") {
-        const response = z14.object({
-          environments: z14.array(
-            z14.object({ id: z14.string(), slug: z14.string() })
+        const response = z15.object({
+          environments: z15.array(
+            z15.object({ id: z15.string(), slug: z15.string() })
           )
         }).parse(await request(`${site}/environments`));
         const environment = common.overview.project.environments.find(
@@ -8797,11 +9295,11 @@ async function runServiceCommand(service, options) {
           );
         const base = `/environments/${encodeURIComponent(matches[0].id)}`;
         if (action === "report" && positionals.length === 1) {
-          const detail = z14.object({
-            site: z14.object({
-              id: z14.literal(common.resourceId),
-              environments: z14.array(
-                z14.object({ id: z14.string(), evidence: z14.unknown() })
+          const detail = z15.object({
+            site: z15.object({
+              id: z15.literal(common.resourceId),
+              environments: z15.array(
+                z15.object({ id: z15.string(), evidence: z15.unknown() })
               )
             })
           }).parse(await request(site));
@@ -8859,7 +9357,383 @@ async function runServiceCommand(service, options) {
   } catch (cause) {
     return {
       exitCode: cause instanceof SiteOSAuthApiError ? 1 : 2,
-      stderr: cause instanceof SiteOSAuthApiError || !(cause instanceof z14.ZodError) && cause instanceof Error ? cause.message : "The service returned an invalid response."
+      stderr: cause instanceof SiteOSAuthApiError || !(cause instanceof z15.ZodError) && cause instanceof Error ? cause.message : "The service returned an invalid response."
+    };
+  }
+}
+
+// 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 }
     };
   }
 }
@@ -8897,6 +9771,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,
@@ -9004,6 +9884,7 @@ Usage:
   siteos project --help
   siteos cookie --help
   siteos trace --help
+  siteos seo --help
   siteos integrations --help
   siteos pulse --help
   siteos search --help
@@ -9015,6 +9896,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.