@siteoshq/cli 1.10.0 → 1.11.0

package/dist/cli.js

@@ -1502,7 +1502,7 @@ var OverviewSchema = z4.object({
 });
 function createProjectApi(input) {
   const origin = resolveSiteOSAuthBaseUrl(input.env);
-  async function request(path32, schema, body, method) {
+  async function request(path33, schema, body, method) {
     const scope = body === void 0 ? "projects:workspace:read" : "projects:workspace:write";
     const grant = await input.grants.acquire({
       audience: "siteos-projects",
@@ -1516,7 +1516,7 @@ function createProjectApi(input) {
         message: "SiteOS API access is unavailable."
       });
     const response = await input.fetchImpl(
-      `${origin}/api/projects/v1/projects${path32}`,
+      `${origin}/api/projects/v1/projects${path33}`,
       {
         method: method ?? (body === void 0 ? "GET" : "POST"),
         headers: {
@@ -2394,7 +2394,10 @@ var AUTH_HELP = `Usage:
   siteos auth select --organization <organization-id> [--json]
   siteos auth logout [--json]
 
-Authenticate the SiteOS CLI with a user-level session.`;
+Authenticate the SiteOS CLI with a user-level session.
+A personal organization is set up automatically on first sign-in.
+
+Manual organization creation is team administration, available only to verified @pixelpoint.io accounts.`;
 async function runAuthCommand(options) {
   if (options.args.length === 0 || options.args.some((arg) => HELP_FLAGS.has(arg))) {
     return { exitCode: 0, stdout: AUTH_HELP };
@@ -7176,7 +7179,8 @@ async function runDeployCommand(options, args2) {
     },
     strict: true
   });
-  const repositoryRoot = await findRepositoryRoot(options.cwd ?? process.cwd());
+  const projectRoot = path25.resolve(options.cwd ?? process.cwd());
+  const repositoryRoot = await findRepositoryRoot(projectRoot);
   const common = await commonServiceContext(options, "pulse");
   if (common && (!common.environmentBinding?.slug || !common.environment.url))
     throw new CliError(
@@ -7192,14 +7196,14 @@ async function runDeployCommand(options, args2) {
       }
     } : {},
     output: values.output,
-    projectRoot: repositoryRoot
+    projectRoot
   });
   if (values["dry-run"]) {
     return success(
       values.json,
       { dryRun: true, manifest },
       [
-        `Bundle: ${path25.relative(repositoryRoot, manifest.archivePath)}`,
+        `Bundle: ${path25.relative(projectRoot, manifest.archivePath)}`,
         `Checksum: ${manifest.checksum}`,
         `Files: ${manifest.fileCount}`,
         "Dry run complete; nothing was uploaded."
@@ -7207,7 +7211,7 @@ async function runDeployCommand(options, args2) {
     );
   }
   const apiOrigin = await resolvePulseApiOrigin({
-    cwd: repositoryRoot,
+    cwd: projectRoot,
     env: options.env,
     requireConfig: true
   });
@@ -7216,7 +7220,7 @@ async function runDeployCommand(options, args2) {
     apiOrigin,
     fetchImpl: options.fetchImpl
   });
-  const snapshot = await loadChecksConfigSnapshot(repositoryRoot);
+  const snapshot = await loadChecksConfigSnapshot(projectRoot);
   const selected = await requireSelectedProject({
     options,
     apiOrigin,
@@ -7242,7 +7246,7 @@ async function runDeployCommand(options, args2) {
     values.json,
     { deployment, dryRun: false, manifest },
     [
-      `Bundle: ${path25.relative(repositoryRoot, manifest.archivePath)}`,
+      `Bundle: ${path25.relative(projectRoot, manifest.archivePath)}`,
       `Checksum: ${manifest.checksum}`,
       `Files: ${manifest.fileCount}`,
       `Project ${deployment.projectId} deployed.`,
@@ -10031,8 +10035,8 @@ var ANALYTICS_HELP = `Set up website Analytics in the selected Project environme
 Usage:
   siteos analytics status [--environment <slug>] [--json]
   siteos analytics installation [--environment <slug>] [--json]
-  siteos analytics report [--days <1|7|28>] [--event <name>] [--country <ISO|unknown>] [--campaign <id>] [--environment <slug>] [--json]
-  siteos analytics realtime [--country <ISO|unknown>] [--campaign <id>] [--environment <slug>] [--json]
+  siteos analytics report [--days <1|7|28>] [--event <name>] [--country <ISO|unknown>] [--campaign <id>] [--filters <json>] [--environment <slug>] [--json]
+  siteos analytics realtime [--country <ISO|unknown>] [--campaign <id>] [--filters <json>] [--environment <slug>] [--json]
   siteos analytics settings show [--environment <slug>] [--json]
   siteos analytics settings set --revision <number> [--enabled <true|false>] [--cookie-events <true|false>] [--minimal-realtime <true|false>] [--environment <slug>] [--json]
   siteos analytics events list [--environment <slug>] [--json]
@@ -10135,6 +10139,7 @@ async function runAnalyticsCommand(options) {
         event: { type: "string" },
         country: { type: "string" },
         campaign: { type: "string" },
+        filters: { type: "string" },
         revision: { type: "string" },
         enabled: { type: "string" },
         "cookie-events": { type: "string" },
@@ -10146,8 +10151,11 @@ async function runAnalyticsCommand(options) {
     const operations = {
       status: { args: 1, flags: [] },
       installation: { args: 1, flags: [] },
-      report: { args: 1, flags: ["days", "event", "country", "campaign"] },
-      realtime: { args: 1, flags: ["country", "campaign"] },
+      report: {
+        args: 1,
+        flags: ["days", "event", "country", "campaign", "filters"]
+      },
+      realtime: { args: 1, flags: ["country", "campaign", "filters"] },
       "settings show": { args: 2, flags: [] },
       "settings set": {
         args: 2,
@@ -10261,7 +10269,13 @@ async function runAnalyticsCommand(options) {
         message: "The Analytics grant does not match this Project and operation."
       });
     const query = new URLSearchParams();
-    for (const key of ["days", "event", "country", "campaign"])
+    for (const key of [
+      "days",
+      "event",
+      "country",
+      "campaign",
+      "filters"
+    ])
       if (values[key]) query.set(key, values[key]);
     const suffix = action === "realtime" ? `/realtime?${query}` : setting ? "/settings" : creating || archive ? `/${action}` : route === "monitoring prepare" ? "/monitoring" : `?${query}`;
     if (!options.fetchImpl)
@@ -10379,18 +10393,643 @@ async function runAnalyticsCommand(options) {
 }
 
 // src/services/seo-command.ts
-import { writeFile as writeFile9 } from "fs/promises";
-import path31 from "path";
-import { parseArgs as parseArgs6 } from "util";
-import { z as z19 } from "zod";
+import { writeFile as writeFile10 } from "fs/promises";
+import path32 from "path";
+import { parseArgs as parseArgs8 } from "util";
+import { z as z22 } from "zod";
 
-// src/services/seo-performance-command.ts
+// src/services/seo-research-command.ts
 import { randomUUID as randomUUID6 } from "crypto";
-import { writeFile as writeFile8 } from "fs/promises";
-import path30 from "path";
 import { setTimeout as setTimeout2 } from "timers/promises";
-import { parseArgs as parseArgs5 } from "util";
+import { isDeepStrictEqual, parseArgs as parseArgs5 } from "util";
+import { z as z19 } from "zod";
+
+// src/services/seo-report-client.ts
+import { open, writeFile as writeFile8 } from "fs/promises";
+import path30 from "path";
 import { z as z18 } from "zod";
+async function seoReportClient(options, environment) {
+  const context = await commonServiceContext(options, "seo", environment);
+  if (!context)
+    throw new Error("Select a SiteOS Project with siteos project use first.");
+  const runtime = commonProjectRuntime(options);
+  return {
+    resourceId: context.resourceId,
+    organizationId: context.overview.project.organizationId,
+    async request(suffix, scope, body) {
+      const grant = await runtime.grants.acquire({
+        audience: "siteos-seo",
+        scopes: [scope]
+      });
+      if (grant.grant.audience !== "siteos-seo" || grant.grant.organizationId !== context.overview.project.organizationId || grant.grant.scopes.length !== 1 || grant.grant.scopes[0] !== scope)
+        throw new SiteOSAuthApiError({
+          code: "AUTH_INVALID_RESPONSE",
+          message: "The SEO grant does not match this Project and operation."
+        });
+      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: body === void 0 ? "GET" : "POST",
+          headers: {
+            Accept: "application/json",
+            Authorization: `Bearer ${grant.accessToken}`,
+            ...body === void 0 ? {} : { "Content-Type": "application/json" }
+          },
+          ...body === void 0 ? {} : { body: JSON.stringify(body) },
+          signal: AbortSignal.timeout(3e4)
+        }
+      );
+      if (!response.ok) {
+        const result = z18.object({
+          error: z18.object({ code: z18.string(), message: z18.string().max(500) })
+        }).safeParse(await response.json());
+        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
+        });
+      }
+      if (!(response instanceof Response))
+        throw new Error("The API transport does not support SEO reports.");
+      return response;
+    }
+  };
+}
+var versionedReport = z18.object({ contractVersion: z18.literal(1) }).passthrough();
+async function readSeoInput(cwd, filename) {
+  const file = await open(path30.resolve(cwd ?? process.cwd(), filename), "r");
+  try {
+    const stat3 = await file.stat();
+    if (!stat3.isFile() || stat3.size > 32e3)
+      throw new Error("Use a JSON request file of at most 32,000 bytes.");
+    const buffer = Buffer.alloc(32001);
+    let bytes = 0;
+    while (bytes < buffer.length) {
+      const read = await file.read(buffer, bytes, buffer.length - bytes, null);
+      if (!read.bytesRead) break;
+      bytes += read.bytesRead;
+    }
+    if (bytes > 32e3)
+      throw new Error("Use a JSON request file of at most 32,000 bytes.");
+    try {
+      return JSON.parse(buffer.subarray(0, bytes).toString("utf8"));
+    } catch {
+      throw new Error("The request file must contain valid JSON.");
+    }
+  } finally {
+    await file.close();
+  }
+}
+async function writeSeoReport(options, filename, content) {
+  const output = path30.resolve(options.cwd ?? process.cwd(), filename);
+  await writeFile8(output, content, { flag: "wx", mode: 384 });
+  return output;
+}
+function seoReportFailure(cause, json, idempotencyKey) {
+  const error = {
+    code: cause instanceof SiteOSAuthApiError ? cause.code : "SEO_COMMAND_FAILED",
+    message: cause instanceof z18.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,
+        ...idempotencyKey ? { idempotencyKey } : {}
+      })
+    } : {
+      stderr: `${error.message}${idempotencyKey ? ` Retry key: ${idempotencyKey}` : ""}`
+    }
+  };
+}
+
+// src/services/seo-research-command.ts
+var RESEARCH_HELP = `
+  siteos seo research summary [--environment <slug>] [--json]
+  siteos seo research status --kind <kind> [--environment <slug>] [--json]
+  siteos seo research history --kind <kind> [--environment <slug>] [--json]
+  siteos seo research show <run-id> [--environment <slug>] [--json]
+  siteos seo research plan --input <request.json> [--environment <slug>] [--json]
+  siteos seo research run --input <request.json> [--idempotency-key <key>] [--environment <slug>] [--json]
+  siteos seo research wait <run-id> [--timeout <seconds>] [--environment <slug>] [--json]
+  siteos seo research cancel <run-id> [--environment <slug>] [--json]
+  siteos seo research export <run-id> --format <json|csv> --output <new-file> [--environment <slug>] [--json]
+  siteos seo research saved list --kind <kind> [--environment <slug>] [--json]
+  siteos seo research saved save --input <request.json> --name <name> [--id <saved-id>] [--environment <slug>] [--json]
+  siteos seo research saved remove <saved-id> [--environment <slug>] [--json]
+
+Research kinds: keywords, rankings, competitors, backlinks, brand, ai-visibility.
+Request JSON: {"kind":"keywords","target":"example.com","keywords":["website analytics"],"country":"US","language":"en"}.
+Rankings accepts up to 10 keywords and 5 competitors. AI visibility requires brand, prompt and platforms.
+Markets: US, GB, ES, DE, FR, CA, AU. Languages: en, es, de, fr, pt, it, nl, ru.
+Platforms: chat_gpt, claude, gemini, perplexity. Brand lookup uses brandPlatform chat_gpt|google and brandMatch domain|brand.
+Plan validates the request and shows planned parts and available research credits without enqueueing work.
+Run consumes Organization research credits through the same worker as the interface. Preserve the retry key after an uncertain response.
+History returns the latest 30 checks per kind; show/export can address older retained run IDs. Saved checks are limited to 100 per resource.
+Wait defaults to 120 seconds (maximum 900); exit 3 means still pending, exit 4 means failed or cancelled. Partial evidence stays accessible.
+Exports preserve scope, dates and partial state. CSV stores one dataset row as JSON per row, including failed parts; it never converts missing metrics to zero.
+`;
+var kinds = [
+  "keywords",
+  "rankings",
+  "competitors",
+  "backlinks",
+  "brand",
+  "ai-visibility"
+];
+var requestSchema = z19.object({ kind: z19.enum(kinds), target: z19.string().min(1).max(253) }).passthrough();
+var runStates = z19.enum([
+  "queued",
+  "running",
+  "completed",
+  "partial",
+  "failed",
+  "cancelled"
+]);
+var csvCell = (value) => {
+  let text = value == null ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
+  if (/^[\s]*[=+@-]/u.test(text) || /^[\t\r\n]/u.test(text)) text = `'${text}`;
+  return `"${text.replaceAll('"', '""')}"`;
+};
+async function runSeoResearchCommand(options) {
+  let idempotencyKey;
+  try {
+    const { values, positionals } = parseArgs5({
+      args: options.args.slice(1),
+      strict: true,
+      allowPositionals: true,
+      options: {
+        json: { type: "boolean" },
+        environment: { type: "string" },
+        kind: { type: "string" },
+        input: { type: "string" },
+        name: { type: "string" },
+        id: { type: "string" },
+        "idempotency-key": { type: "string" },
+        timeout: { type: "string" },
+        format: { type: "string" },
+        output: { type: "string" }
+      }
+    });
+    const action = positionals[0] === "saved" ? positionals.slice(0, 2).join(" ") : positionals[0] ?? "";
+    const id = positionals[action.startsWith("saved ") ? 2 : 1];
+    const operations = {
+      summary: { args: 1, flags: [] },
+      status: { args: 1, flags: ["kind"] },
+      history: { args: 1, flags: ["kind"] },
+      show: { args: 2, flags: [] },
+      plan: { args: 1, flags: ["input"] },
+      run: { args: 1, flags: ["input", "idempotency-key"] },
+      wait: { args: 2, flags: ["timeout"] },
+      cancel: { args: 2, flags: [] },
+      export: { args: 2, flags: ["format", "output"] },
+      "saved list": { args: 2, flags: ["kind"] },
+      "saved save": { args: 2, flags: ["input", "name", "id"] },
+      "saved remove": { args: 3, flags: [] }
+    };
+    const operation = operations[action];
+    if (!operation || operation.args !== positionals.length || Object.keys(values).some(
+      (key) => !["json", "environment", ...operation.flags].includes(key)
+    ))
+      throw new Error(
+        "Invalid research operation or flags. Run siteos seo --help."
+      );
+    if (operation.flags.includes("kind") && !kinds.includes(values.kind))
+      throw new Error("Choose a documented --kind.");
+    if (operation.flags.includes("input") && !values.input)
+      throw new Error("Provide --input with a research request JSON file.");
+    if (action === "saved save" && (!values.name?.trim() || values.name.length > 100))
+      throw new Error("Use --name with 1 to 100 characters.");
+    if (values.id && values.id.length > 100)
+      throw new Error("The saved ID is too long.");
+    const timeout = Number(values.timeout ?? 120);
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > 900)
+      throw new Error("Use a wait timeout between 1 and 900 seconds.");
+    if (action === "export" && (!values.output || !["json", "csv"].includes(values.format ?? "")))
+      throw new Error(
+        "Export requires --format json|csv and --output for a new file."
+      );
+    let input;
+    if (values.input) {
+      input = await readSeoInput(options.cwd, values.input);
+      if (!requestSchema.safeParse(input).success)
+        throw new Error(
+          "The request file needs a research kind and target domain. Run siteos seo --help."
+        );
+    }
+    if (action === "run") {
+      idempotencyKey = values["idempotency-key"] ?? randomUUID6();
+      if (!/^[a-zA-Z0-9_-]{8,100}$/u.test(idempotencyKey))
+        throw new Error(
+          "Use an idempotency key of 8 to 100 letters, digits, underscores or hyphens."
+        );
+    }
+    const client = await seoReportClient(options, values.environment);
+    const resourceSchema = z19.object({
+      id: z19.literal(client.resourceId),
+      organizationId: z19.literal(client.organizationId)
+    }).passthrough();
+    const runSchema = z19.object({
+      id: z19.string(),
+      resourceId: z19.literal(client.resourceId),
+      organizationId: z19.literal(client.organizationId),
+      websiteUrl: z19.string(),
+      request: requestSchema,
+      state: runStates,
+      createdAt: z19.string(),
+      finishedAt: z19.string().nullable(),
+      parts: z19.array(
+        z19.object({
+          key: z19.string(),
+          state: z19.enum(["completed", "failed"]),
+          error: z19.string().nullable(),
+          dataset: z19.record(z19.unknown()).nullable(),
+          observedAt: z19.string()
+        }).passthrough()
+      )
+    }).passthrough();
+    const get = async (suffix, scope = "read", body) => versionedReport.parse(
+      await (await client.request(
+        `/research${suffix}`,
+        `seo:research:${scope}`,
+        body
+      )).json()
+    );
+    const query = `?kind=${encodeURIComponent(values.kind ?? "rankings")}`;
+    let record;
+    if (action === "plan" || action === "run" || action === "saved save") {
+      const plan = await get("/plan", "read", input);
+      resourceSchema.parse(plan.resource);
+      const canonical = requestSchema.parse(plan.request);
+      if (canonical.kind !== requestSchema.parse(input).kind)
+        throw new Error("The plan does not match the requested research kind.");
+      if (action === "run") {
+        record = await get("/runs", "run", { request: input, idempotencyKey });
+        const run = runSchema.parse(record.run);
+        if (!isDeepStrictEqual(run.request, plan.request))
+          throw new Error(
+            "The admitted check does not match the validated research request."
+          );
+        record = { ...record, idempotencyKey };
+      } else if (action === "saved save") {
+        record = await get("/saved", "write", {
+          request: input,
+          name: values.name.trim(),
+          ...values.id ? { id: values.id } : {}
+        });
+        const saved = z19.object({
+          id: z19.string(),
+          name: z19.literal(values.name.trim()),
+          request: requestSchema
+        }).parse(record.saved);
+        if (values.id && saved.id !== values.id || !isDeepStrictEqual(saved.request, plan.request))
+          throw new Error(
+            "The saved check does not match the requested settings."
+          );
+      } else record = plan;
+    } else if (action === "cancel" || action === "saved remove") {
+      record = await get(
+        `/${action === "cancel" ? "runs" : "saved"}/${encodeURIComponent(id)}/${action === "cancel" ? "cancel" : "remove"}`,
+        action === "cancel" ? "run" : "write",
+        {}
+      );
+      z19.literal(true).parse(
+        record[action === "cancel" ? "cancelled" : "removed"]
+      );
+    } else if (action === "summary") {
+      record = await get("/summary");
+      resourceSchema.parse(record.resource);
+      z19.array(z19.object({ kind: z19.enum(kinds), summary: z19.unknown() })).parse(
+        record.checks
+      );
+    } else if (["status", "history", "saved list"].includes(action)) {
+      const view = await get(query);
+      resourceSchema.parse(view.resource);
+      const runs = z19.array(runSchema).parse(view.runs);
+      const saved = z19.array(
+        z19.object({
+          id: z19.string(),
+          name: z19.string(),
+          request: requestSchema
+        }).passthrough()
+      ).parse(view.saved);
+      if (runs.some((r) => r.request.kind !== values.kind) || saved.some((r) => r.request.kind !== values.kind))
+        throw new Error(
+          "The response does not match the requested research kind."
+        );
+      if (view.run != null) {
+        const selected = runSchema.parse(view.run);
+        if (selected.request.kind !== values.kind)
+          throw new Error("The selected report has a different research kind.");
+      }
+      record = {
+        contractVersion: 1,
+        resource: view.resource,
+        kind: values.kind,
+        ...action === "history" ? { runs, limit: 30 } : action === "saved list" ? { saved, limit: 100 } : { connection: view.connection, run: view.run }
+      };
+    } else {
+      const deadline = Date.now() + timeout * 1e3;
+      while (true) {
+        record = await get(`/runs/${encodeURIComponent(id)}`);
+        resourceSchema.parse(record.resource);
+        const run = runSchema.parse(record.run);
+        if (run.id !== id)
+          throw new Error(
+            "The response does not match the selected research check."
+          );
+        if (record.previous) runSchema.parse(record.previous);
+        if (action !== "wait" || !["queued", "running"].includes(run.state))
+          break;
+        if (Date.now() >= deadline)
+          return {
+            exitCode: 3,
+            stdout: JSON.stringify({ ...record, timedOut: true }, null, 2)
+          };
+        await setTimeout2(Math.min(3e3, Math.max(0, deadline - Date.now())));
+      }
+      if (action === "export") {
+        const run = runSchema.parse(record.run);
+        const parts = run.parts.length ? run.parts : [
+          {
+            key: null,
+            state: null,
+            observedAt: null,
+            error: run.error,
+            dataset: null
+          }
+        ];
+        const rows = parts.flatMap((part) => {
+          const dataset = part.dataset;
+          const entries = dataset && Array.isArray(dataset.rows) ? dataset.rows : [dataset];
+          return (entries.length ? entries : [null]).map((row) => [
+            run.id,
+            run.websiteUrl,
+            run.request.kind,
+            run.request.target,
+            run.createdAt,
+            run.state,
+            run.error,
+            part.key,
+            part.state,
+            part.observedAt,
+            part.error,
+            dataset?.type,
+            run.request,
+            dataset ? Object.fromEntries(
+              Object.entries(dataset).filter(([key]) => key !== "rows")
+            ) : null,
+            row
+          ]);
+        });
+        const content = values.format === "json" ? JSON.stringify(record, null, 2) : [
+          [
+            "run_id",
+            "website_url",
+            "kind",
+            "target",
+            "created_at",
+            "run_state",
+            "run_error",
+            "part",
+            "part_state",
+            "observed_at",
+            "error",
+            "dataset_type",
+            "request_json",
+            "dataset_metadata_json",
+            "data_json"
+          ],
+          ...rows
+        ].map((row) => row.map(csvCell).join(",")).join("\r\n");
+        const output = await writeSeoReport(options, values.output, content);
+        record = {
+          contractVersion: 1,
+          runId: id,
+          state: run.state,
+          format: values.format,
+          output
+        };
+      }
+      if (action === "wait" && ["failed", "cancelled"].includes(runSchema.parse(record.run).state))
+        return { exitCode: 4, stdout: JSON.stringify(record, null, 2) };
+    }
+    return { exitCode: 0, stdout: JSON.stringify(record, null, 2) };
+  } catch (cause) {
+    return seoReportFailure(
+      cause,
+      options.args.includes("--json"),
+      idempotencyKey
+    );
+  }
+}
+
+// src/services/seo-gsc-command.ts
+import { parseArgs as parseArgs6 } from "util";
+import { z as z20 } from "zod";
+var GSC_HELP = `
+  siteos seo gsc status [--environment <slug>] [--json]
+  siteos seo gsc report [--dataset <pages|queries>] [--query <text>] [--filter <all|issues|declining>] [--sort <clicks|change|impressions>] [--page <number>] [--url <page-url>] [--environment <slug>] [--json]
+  siteos seo gsc export --format <json|csv> --output <new-file> [--dataset <pages|queries>] [--query <text>] [--filter <all|issues|declining>] [--sort <clicks|change|impressions>] [--environment <slug>] [--json]
+  siteos seo gsc sync [--environment <slug>] [--json]
+  siteos seo gsc bind --connection <id> --property <site-url> --website <environment-url> --revision <number> [--environment <slug>] [--json]
+  siteos seo gsc disconnect --revision <number> [--environment <slug>] [--json]
+
+GSC Insights reads saved Google Search Console reports; it requires a connected property for this environment.
+Status lists the property directory, binding, latest synchronization and report freshness. Connect Google OAuth interactively in SiteOS first.
+Report defaults to all pages and shows 25 rows per page, measured totals and coverage. --url includes the selected page and its query evidence.
+Export includes every matching row of the selected saved comparison (up to 20,000), with report dates and truncation metadata; --page is not an export filter.
+Sync queues the existing background worker and does not wait for completion. Read status until the returned run finishes.
+Bind/disconnect require a current revision and separate settings authority. Disconnect removes only this environment binding, not the Google account.
+`;
+async function runSeoGscCommand(options) {
+  try {
+    const { values, positionals } = parseArgs6({
+      args: options.args.slice(1),
+      strict: true,
+      allowPositionals: true,
+      options: {
+        json: { type: "boolean" },
+        environment: { type: "string" },
+        dataset: { type: "string" },
+        query: { type: "string" },
+        filter: { type: "string" },
+        sort: { type: "string" },
+        page: { type: "string" },
+        url: { type: "string" },
+        format: { type: "string" },
+        output: { type: "string" },
+        connection: { type: "string" },
+        property: { type: "string" },
+        website: { type: "string" },
+        revision: { type: "string" }
+      }
+    });
+    const action = positionals[0] ?? "";
+    const operations = {
+      status: [],
+      report: ["dataset", "query", "filter", "sort", "page", "url"],
+      export: ["dataset", "query", "filter", "sort", "format", "output"],
+      sync: [],
+      bind: ["connection", "property", "website", "revision"],
+      disconnect: ["revision"]
+    };
+    if (!operations[action] || positionals.length !== 1 || Object.keys(values).some(
+      (key) => !["json", "environment", ...operations[action]].includes(key)
+    ))
+      throw new Error("Invalid GSC operation or flags. Run siteos seo --help.");
+    if (values.dataset && !["pages", "queries"].includes(values.dataset))
+      throw new Error("Use --dataset pages or queries.");
+    if (values.filter && !["all", "issues", "declining"].includes(values.filter))
+      throw new Error("Use --filter all, issues or declining.");
+    if (values.sort && !["clicks", "change", "impressions"].includes(values.sort))
+      throw new Error("Use --sort clicks, change or impressions.");
+    if (values.page && (!/^[1-9]\d{0,3}$/u.test(values.page) || Number(values.page) > 4e3))
+      throw new Error("Use a page number between 1 and 4000.");
+    if ((values.query?.length ?? 0) > 160 || (values.url?.length ?? 0) > 2048)
+      throw new Error("The report filter is too long.");
+    if (action === "export" && (!values.output || !["csv", "json"].includes(values.format ?? "")))
+      throw new Error(
+        "Export requires --format csv|json and --output for a new file."
+      );
+    if (["bind", "disconnect"].includes(action) && (!/^\d{1,9}$/u.test(values.revision ?? "") || action === "disconnect" && Number(values.revision) < 1))
+      throw new Error(
+        "Use the current binding --revision (0 only before the first binding)."
+      );
+    if (action === "bind" && (!values.connection || !values.property || !values.website))
+      throw new Error(
+        "Binding requires --connection, --property, --website and --revision."
+      );
+    const client = await seoReportClient(options, values.environment);
+    const query = new URLSearchParams({
+      dataset: values.dataset ?? "pages",
+      filter: values.filter ?? "all"
+    });
+    for (const [flag, key] of [
+      ["query", "q"],
+      ["sort", "sort"],
+      ["page", "page"],
+      ["url", "pageUrl"],
+      ["format", "format"]
+    ])
+      if (values[flag]) query.set(key, values[flag]);
+    const writing = ["sync", "bind", "disconnect"].includes(action);
+    const suffix = action === "bind" ? "/binding" : writing ? `/${action}` : action === "export" ? `/export?${query}` : `?${query}`;
+    const body = action === "bind" ? {
+      connectionId: values.connection,
+      siteUrl: values.property,
+      websiteUrl: values.website,
+      expectedRevision: Number(values.revision)
+    } : action === "disconnect" ? { expectedRevision: Number(values.revision) } : writing ? {} : void 0;
+    const response = await client.request(
+      `/search-console${suffix}`,
+      `seo:search:${action === "sync" ? "sync" : writing ? "write" : "read"}`,
+      body
+    );
+    const runSchema = z20.object({
+      id: z20.string(),
+      resourceId: z20.literal(client.resourceId),
+      organizationId: z20.literal(client.organizationId),
+      websiteUrl: z20.string(),
+      siteUrl: z20.string(),
+      state: z20.enum([
+        "queued",
+        "running",
+        "completed",
+        "partial",
+        "failed",
+        "cancelled"
+      ]),
+      dates: z20.unknown()
+    }).passthrough();
+    const bindingSchema = z20.object({
+      resourceId: z20.literal(client.resourceId),
+      organizationId: z20.literal(client.organizationId),
+      websiteUrl: z20.string(),
+      siteUrl: z20.string(),
+      revision: z20.number().int().positive()
+    }).passthrough();
+    const metrics = z20.object({
+      clicks: z20.number(),
+      impressions: z20.number(),
+      ctr: z20.number(),
+      position: z20.number()
+    }).passthrough().nullable();
+    const validateView = (data) => {
+      const record2 = versionedReport.parse(data);
+      z20.literal(client.resourceId).parse(record2.resourceId);
+      bindingSchema.nullable().parse(record2.binding);
+      runSchema.nullable().parse(record2.latest);
+      runSchema.nullable().parse(record2.report);
+      z20.array(
+        z20.object({ key: z20.string(), current: metrics, previous: metrics }).passthrough()
+      ).parse(record2.rows);
+      z20.number().int().nonnegative().parse(record2.total);
+      z20.literal(values.dataset ?? "pages").parse(record2.dataset);
+      return record2;
+    };
+    if (action === "export") {
+      const rows = Number(response.headers.get("X-SEO-Export-Rows"));
+      const reportId = response.headers.get("X-SEO-Search-Id");
+      const truncated = response.headers.get("X-SEO-Export-Truncated");
+      if (response.headers.get("X-SEO-Resource-Id") !== client.resourceId || !reportId || !response.headers.has("X-SEO-Export-Rows") || !Number.isSafeInteger(rows) || rows < 0 || !["true", "false"].includes(truncated ?? "") || !response.headers.get("Content-Type")?.startsWith(
+        values.format === "csv" ? "text/csv" : "application/json"
+      ))
+        throw new Error(
+          "The export response does not match this SEO resource."
+        );
+      const text = await response.text();
+      if (values.format === "json") {
+        const report = validateView(JSON.parse(text));
+        z20.literal(reportId).parse(runSchema.parse(report.report).id);
+        z20.array(z20.unknown()).length(rows).parse(report.rows);
+        z20.literal(truncated === "true").parse(report.truncated);
+      }
+      const output = await writeSeoReport(options, values.output, text);
+      return {
+        exitCode: 0,
+        stdout: JSON.stringify(
+          {
+            contractVersion: 1,
+            resourceId: client.resourceId,
+            reportId,
+            rows,
+            truncated: truncated === "true",
+            format: values.format,
+            output
+          },
+          null,
+          2
+        )
+      };
+    }
+    const record = versionedReport.parse(await response.json());
+    if (action === "disconnect") z20.literal(true).parse(record.unbound);
+    else if (writing) {
+      runSchema.parse(record.run);
+      if (action === "bind") {
+        const binding = bindingSchema.parse(record.binding);
+        if (binding.siteUrl !== values.property || binding.websiteUrl !== values.website || binding.revision !== Number(values.revision) + 1)
+          throw new Error(
+            "The saved binding does not match the requested property and revision."
+          );
+      }
+    } else validateView(record);
+    return { exitCode: 0, stdout: JSON.stringify(record, null, 2) };
+  } catch (cause) {
+    return seoReportFailure(cause, options.args.includes("--json"));
+  }
+}
+
+// src/services/seo-performance-command.ts
+import { randomUUID as randomUUID7 } from "crypto";
+import { writeFile as writeFile9 } from "fs/promises";
+import path31 from "path";
+import { setTimeout as setTimeout3 } from "timers/promises";
+import { parseArgs as parseArgs7 } from "util";
+import { z as z21 } from "zod";
 var PERFORMANCE_HELP = `
   siteos seo performance run --audit <id> --url <url> [--url <url>...] [--device <mobile|desktop>] [--idempotency-key <key>] [--environment <slug>] [--json]
   siteos seo performance list [--device <mobile|desktop>] [--environment <slug>] [--json]
@@ -10407,7 +11046,7 @@ Reuse the returned idempotency key after an uncertain run response. Wait default
 async function runSeoPerformanceCommand(options) {
   let idempotencyKey;
   try {
-    const { values, positionals } = parseArgs5({
+    const { values, positionals } = parseArgs7({
       args: options.args.slice(1),
       strict: true,
       allowPositionals: true,
@@ -10462,7 +11101,7 @@ async function runSeoPerformanceCommand(options) {
         "Export requires --format csv|json and --output for a new file."
       );
     if (action === "run") {
-      idempotencyKey = values["idempotency-key"] ?? randomUUID6();
+      idempotencyKey = values["idempotency-key"] ?? randomUUID7();
       if (!/^[a-zA-Z0-9_-]{16,100}$/u.test(idempotencyKey))
         throw new Error(
           "Use an idempotency key of 16 to 100 letters, digits, underscores or hyphens."
@@ -10478,12 +11117,12 @@ async function runSeoPerformanceCommand(options) {
     const runtime = commonProjectRuntime(options);
     const writing = ["run", "cancel"].includes(action);
     const scope = writing ? "seo:audits:write" : "seo:workspace:read";
-    const batchSchema = z18.object({
-      id: z18.string(),
-      resourceId: z18.literal(context.resourceId),
-      organizationId: z18.literal(context.overview.project.organizationId),
-      sourceAuditId: z18.string(),
-      state: z18.enum([
+    const batchSchema = z21.object({
+      id: z21.string(),
+      resourceId: z21.literal(context.resourceId),
+      organizationId: z21.literal(context.overview.project.organizationId),
+      sourceAuditId: z21.string(),
+      state: z21.enum([
         "queued",
         "running",
         "completed",
@@ -10491,8 +11130,8 @@ async function runSeoPerformanceCommand(options) {
         "failed",
         "cancelled"
       ]),
-      device: z18.enum(["mobile", "desktop"]),
-      urls: z18.array(z18.string()).min(1).max(10)
+      device: z21.enum(["mobile", "desktop"]),
+      urls: z21.array(z21.string()).min(1).max(10)
     }).passthrough();
     const query = new URLSearchParams();
     if (values.device) query.set("device", values.device);
@@ -10540,21 +11179,21 @@ async function runSeoPerformanceCommand(options) {
           );
         const text = await response.text();
         if (values.format === "json") {
-          const parsed = z18.object({
-            contractVersion: z18.literal(1),
+          const parsed = z21.object({
+            contractVersion: z21.literal(1),
             batch: batchSchema,
-            pages: z18.array(z18.unknown())
+            pages: z21.array(z21.unknown())
           }).parse(JSON.parse(text));
           if (parsed.batch.id !== id)
             throw new Error(
               "The export response does not match the selected check."
             );
         }
-        const output = path30.resolve(
+        const output = path31.resolve(
           options.cwd ?? process.cwd(),
           values.output
         );
-        await writeFile8(output, text, { flag: "wx", mode: 384 });
+        await writeFile9(output, text, { flag: "wx", mode: 384 });
         return {
           exitCode: 0,
           stdout: JSON.stringify(
@@ -10566,8 +11205,8 @@ async function runSeoPerformanceCommand(options) {
       }
       const data = await response.json();
       if (!response.ok) {
-        const error = z18.object({
-          error: z18.object({ code: z18.string(), message: z18.string().max(500) })
+        const error = z21.object({
+          error: z21.object({ code: z21.string(), message: z21.string().max(500) })
         }).safeParse(data);
         throw new SiteOSAuthApiError({
           code: error.success ? error.data.error.code : "SEO_REQUEST_FAILED",
@@ -10575,8 +11214,8 @@ async function runSeoPerformanceCommand(options) {
           status: response.status
         });
       }
-      const record = z18.object({ contractVersion: z18.literal(1) }).passthrough().parse(data);
-      if (action === "cancel") z18.literal(true).parse(record.cancelled);
+      const record = z21.object({ contractVersion: z21.literal(1) }).passthrough().parse(data);
+      if (action === "cancel") z21.literal(true).parse(record.cancelled);
       else if (action === "run") {
         const accepted = batchSchema.parse(record.batch);
         const normalize = (url) => {
@@ -10589,8 +11228,8 @@ async function runSeoPerformanceCommand(options) {
             "The queued check does not match the requested source, device and URLs."
           );
       } else {
-        z18.literal(context.resourceId).parse(record.resourceId);
-        z18.array(batchSchema).parse(record.batches);
+        z21.literal(context.resourceId).parse(record.resourceId);
+        z21.array(batchSchema).parse(record.batches);
         const selected = batchSchema.nullable().parse(record.batch);
         if (id && selected?.id !== id)
           throw new Error(
@@ -10612,12 +11251,12 @@ async function runSeoPerformanceCommand(options) {
           exitCode: 3,
           stdout: JSON.stringify({ ...record, timedOut: true }, null, 2)
         };
-      await setTimeout2(Math.min(3e3, Math.max(0, deadline - Date.now())));
+      await setTimeout3(Math.min(3e3, Math.max(0, deadline - Date.now())));
     }
   } catch (cause) {
     const error = {
       code: cause instanceof SiteOSAuthApiError ? cause.code : "SEO_COMMAND_FAILED",
-      message: cause instanceof z18.ZodError ? "The SEO service returned an invalid response." : cause instanceof Error ? cause.message : "The performance command failed."
+      message: cause instanceof z21.ZodError ? "The SEO service returned an invalid response." : cause instanceof Error ? cause.message : "The performance command failed."
     };
     return {
       exitCode: cause instanceof SiteOSAuthApiError ? 1 : 2,
@@ -10634,7 +11273,7 @@ async function runSeoPerformanceCommand(options) {
 }
 
 // src/services/seo-command.ts
-var SEO_HELP = `Audit public HTML in the selected Project environment.
+var SEO_HELP = `Audit SEO and work with search and AI research in the selected Project environment.
 
 Usage:
   siteos seo status [--environment <slug>] [--json]
@@ -10655,6 +11294,8 @@ Usage:
   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]
 ${PERFORMANCE_HELP.trim().split("\n\n")[0]}
+${RESEARCH_HELP.trim().split("\n\n")[0]}
+${GSC_HELP.trim().split("\n\n")[0]}
 
 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.
@@ -10662,15 +11303,19 @@ Runs are queued. Read audit show until terminal; an accepted run is not a comple
 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.
-${PERFORMANCE_HELP.trim().split("\n\n").slice(1).join("\n\n")}`;
+${PERFORMANCE_HELP.trim().split("\n\n").slice(1).join("\n\n")}
+${RESEARCH_HELP.trim().split("\n\n").slice(1).join("\n\n")}
+${GSC_HELP.trim().split("\n\n").slice(1).join("\n\n")}`;
 async function runSeoCommand(options) {
   if (!options.args.length || options.args.some((arg) => ["--help", "-h"].includes(arg)))
     return { exitCode: 0, stdout: SEO_HELP };
   if (options.args[0] === "performance")
     return runSeoPerformanceCommand(options);
+  if (options.args[0] === "research") return runSeoResearchCommand(options);
+  if (options.args[0] === "gsc") return runSeoGscCommand(options);
   const json = options.args.includes("--json");
   try {
-    const { positionals, values } = parseArgs6({
+    const { positionals, values } = parseArgs8({
       args: options.args,
       strict: true,
       allowPositionals: true,
@@ -10883,18 +11528,18 @@ async function runSeoCommand(options) {
         );
       const text = await response.text();
       if (values.format === "json")
-        z19.object({
-          contractVersion: z19.literal(1),
-          audit: z19.object({
-            id: z19.literal(values.audit),
-            resourceId: z19.literal(context.resourceId)
+        z22.object({
+          contractVersion: z22.literal(1),
+          audit: z22.object({
+            id: z22.literal(values.audit),
+            resourceId: z22.literal(context.resourceId)
           }),
-          kind: z19.literal(values.kind),
-          totalRows: z19.literal(rows),
-          rows: z19.array(z19.unknown()).length(rows)
+          kind: z22.literal(values.kind),
+          totalRows: z22.literal(rows),
+          rows: z22.array(z22.unknown()).length(rows)
         }).parse(JSON.parse(text));
-      const output = path31.resolve(options.cwd ?? process.cwd(), values.output);
-      await writeFile9(output, text, { flag: "wx", mode: 384 });
+      const output = path32.resolve(options.cwd ?? process.cwd(), values.output);
+      await writeFile10(output, text, { flag: "wx", mode: 384 });
       return {
         exitCode: 0,
         stdout: JSON.stringify(
@@ -10912,8 +11557,8 @@ async function runSeoCommand(options) {
     }
     const data = await response.json();
     if (!response.ok) {
-      const result = z19.object({
-        error: z19.object({ code: z19.string(), message: z19.string().max(500) })
+      const result = z22.object({
+        error: z22.object({ code: z22.string(), message: z22.string().max(500) })
       }).safeParse(data);
       throw new SiteOSAuthApiError({
         code: result.success ? result.data.error.code : "SEO_REQUEST_FAILED",
@@ -10921,34 +11566,34 @@ async function runSeoCommand(options) {
         status: response.status
       });
     }
-    const record = z19.object({ contractVersion: z19.literal(1) }).passthrough().parse(data);
+    const record = z22.object({ contractVersion: z22.literal(1) }).passthrough().parse(data);
     if (automation) {
-      z19.literal(context.resourceId).parse(record.resourceId);
-      const schedule = z19.object({
-        enabled: z19.boolean(),
-        weekday: z19.number().int().min(1).max(7),
-        time: z19.string(),
-        timeZone: z19.string(),
-        revision: z19.number().int().min(0),
-        nextRunAt: z19.string().nullable()
+      z22.literal(context.resourceId).parse(record.resourceId);
+      const schedule = z22.object({
+        enabled: z22.boolean(),
+        weekday: z22.number().int().min(1).max(7),
+        time: z22.string(),
+        timeZone: z22.string(),
+        revision: z22.number().int().min(0),
+        nextRunAt: z22.string().nullable()
       });
-      const notificationRoute = z19.object({
-        enabled: z19.boolean(),
-        minimumSeverity: z19.enum(["error", "warning"]),
-        includeFailures: z19.boolean(),
-        revision: z19.number().int().min(0),
-        destinationId: z19.string().nullable()
+      const notificationRoute = z22.object({
+        enabled: z22.boolean(),
+        minimumSeverity: z22.enum(["error", "warning"]),
+        includeFailures: z22.boolean(),
+        revision: z22.number().int().min(0),
+        destinationId: z22.string().nullable()
       });
       if (retryNotification) {
-        z19.literal(true).parse(record.retryQueued);
-        z19.literal(positionals[2]).parse(record.notificationId);
+        z22.literal(true).parse(record.retryQueued);
+        z22.literal(positionals[2]).parse(record.notificationId);
       } else if (route === "notifications destinations")
-        z19.object({
-          candidates: z19.array(
-            z19.object({
-              candidateId: z19.string(),
-              label: z19.string(),
-              availability: z19.literal("available")
+        z22.object({
+          candidates: z22.array(
+            z22.object({
+              candidateId: z22.string(),
+              label: z22.string(),
+              availability: z22.literal("available")
             })
           )
         }).parse(record);
@@ -10961,46 +11606,46 @@ async function runSeoCommand(options) {
         notificationRoute.parse(record.route);
       }
     } else if (!writing) {
-      const validated = z19.object({
-        resource: z19.object({
-          id: z19.literal(context.resourceId),
-          organizationId: z19.literal(context.overview.project.organizationId)
+      const validated = z22.object({
+        resource: z22.object({
+          id: z22.literal(context.resourceId),
+          organizationId: z22.literal(context.overview.project.organizationId)
         }),
-        audits: z19.array(z19.object({ id: z19.string() }).passthrough()),
-        audit: z19.object({
-          id: z19.string(),
-          resourceId: z19.literal(context.resourceId)
+        audits: z22.array(z22.object({ id: z22.string() }).passthrough()),
+        audit: z22.object({
+          id: z22.string(),
+          resourceId: z22.literal(context.resourceId)
         }).passthrough().nullable(),
-        pages: z19.array(z19.unknown()),
-        issues: z19.array(z19.unknown()),
-        changes: z19.array(z19.unknown()),
-        totalChanges: z19.number(),
-        dispositions: z19.array(z19.unknown())
+        pages: z22.array(z22.unknown()),
+        issues: z22.array(z22.unknown()),
+        changes: z22.array(z22.unknown()),
+        totalChanges: z22.number(),
+        dispositions: z22.array(z22.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)
-      z19.object({
-        id: z19.string(),
-        resourceId: z19.literal(context.resourceId),
-        organizationId: z19.literal(context.overview.project.organizationId),
-        state: z19.literal("queued")
+      z22.object({
+        id: z22.string(),
+        resourceId: z22.literal(context.resourceId),
+        organizationId: z22.literal(context.overview.project.organizationId),
+        state: z22.literal("queued")
       }).parse(record.audit);
-    else if (route === "audit cancel") z19.literal(true).parse(record.cancelled);
+    else if (route === "audit cancel") z22.literal(true).parse(record.cancelled);
     else if (action === "issue")
-      z19.object({
-        url: z19.literal(values.url),
-        ruleId: z19.literal(values.rule),
-        ignored: z19.literal(positionals[1] === "ignore"),
-        revision: z19.literal(Number(values.revision) + 1)
+      z22.object({
+        url: z22.literal(values.url),
+        ruleId: z22.literal(values.rule),
+        ignored: z22.literal(positionals[1] === "ignore"),
+        revision: z22.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 z19.ZodError ? "The SEO service returned an invalid response." : cause instanceof Error ? cause.message : "The SEO command failed."
+      message: cause instanceof z22.ZodError ? "The SEO service returned an invalid response." : cause instanceof Error ? cause.message : "The SEO command failed."
     };
     return {
       exitCode: cause instanceof SiteOSAuthApiError ? 1 : 2,