@siteoshq/cli 1.1.1 → 1.2.0

package/README.md

@@ -1,7 +1,7 @@
 # SiteOS CLI
 
 `@siteoshq/cli` exposes one `siteos` binary for Auth, common Projects, Pulse, Cookie, Forms,
-Search, Trace and Integrations. This source prepares version 1.1.1; publishing is a separate release.
+Search, Trace and Integrations. This source prepares version 1.2.0; publishing is a separate release.
 Node.js 22 or newer is required.
 
 ## Install and authenticate
@@ -22,7 +22,7 @@ grants; the durable session never reaches a product endpoint.
 
 ## Hosted origins
 
-CLI 1.1.1 defaults to `https://app.siteos.sh` for Auth and every service. Existing credentials
+CLI 1.2.0 defaults to `https://app.siteos.sh` for Auth and every service. Existing credentials
 and repository bindings retain their selected origin; sign in again when moving installations.
 Never copy private state between production and staging.
 
@@ -183,3 +183,22 @@ pnpm --dir packages/cli pack:check
 ```
 
 `pack:check` creates the publishable tarball locally. It does not publish the package.
+
+## Cookie verification
+
+CLI 1.2.0 adds `cookie schema`, `cookie validate --input draft.json`,
+`cookie regions resolve --country GB --source published` and `cookie restore --input restore.json`.
+Restore changes the draft only. Validation makes no write and reports a stale draft version.
+
+From the selected website repository, run `siteos cookie verify --json` or
+`siteos cookie verify --url /pricing --browser webkit --json`. Install the matching local browser
+when requested with `npx playwright@1.61.1 install chromium` or `npx playwright@1.61.1 install webkit`.
+The check opens fresh contexts, exercises the public consent API and reports request origins and
+storage names without values, query strings, request bodies or authenticated sessions. These are
+real visits; normal installation/aggregate signals may be recorded. Reports remain local.
+
+A report records the revision, runtime, observed Edge location, scenario scope and 24-hour expiry.
+`passed` exits 0; `needs-review` and `failed` exit 1. Unknown origins/storage require classification.
+The check covers one route and a bounded observation window, not hidden first-party/server-side
+tracking, every delayed interaction, visual accessibility or legal compliance. Repeat after
+website/publication changes and preserve a separate GTM Tag Assistant check where applicable.

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";
@@ -8563,13 +8997,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 +9057,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 +9071,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 +9155,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 +9180,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 +9265,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 +9292,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 +9354,7 @@ 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."
     };
   }
 }