@siteoshq/cli 1.11.0 → 1.13.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, SEO and Integrations. This source prepares version 1.11.0; publishing is a separate release.
+Search, Trace, SEO/GEO and Integrations. This source is version 1.13.0; source changes require a separate release to reach npm.
 Node.js 22 or newer is required.
 
 ## Install and authenticate
@@ -167,11 +167,17 @@ snippet is unavailable until runtime publication succeeds. Integrations connecti
 Organization; provider authorization opens the shared browser flow, and notification destinations
 are connected explicitly by each service.
 
-### SEO (prepared for release)
+### SEO/GEO
 
-Check `siteos seo --help` before use; install a matching release only after it is published. An
-SEO-capable server returns SEO in its Project service catalog, which older strict CLI parsers may
-reject. Coordinate the CLI update before that server rollout, then publish the matching plugin.
+The application calls this service **SEO/GEO**; its command and Project service key remain `seo`.
+GEO means generative engine optimization, including technical AI-search accessibility and
+AI mentions/citations. Check `siteos seo --help` against the installed CLI and server version.
+
+Site Audit checks public HTML, canonical, robots.txt, sitemaps, snippets and basic structured data.
+Its crawler-policy checks do not prove access from actual provider IPs. Performance adds
+selected-page Lighthouse and response/rendered HTML comparisons. Brand lookup and Prompt checks
+provide separate AI visibility evidence. No autonomous agent journey or target API/MCP audit is
+performed by these commands, and no result guarantees AI inclusion or a universal AI rank.
 
 ```sh
 siteos project connect seo --json
@@ -192,13 +198,17 @@ observed URL. Read the returned audit ID until a terminal state; a queued respon
 `issue ignore` and `issue restore` require `--audit`, `--url`, `--rule`, `--reason` and the current
 `--revision` (0 before the first decision). They use a distinct issue-write scope. Read back the
 decision after success; a revision conflict requires refreshing it. Ignore never means resolved.
-All SEO commands resolve the selected common Project and explicit environment binding. Current
-The source CLI also supports SEO research and GSC Insights with a matching server release:
+All SEO/GEO commands resolve the selected common Project and explicit environment binding.
+Research and GSC Insights use these commands with a matching server release:
 
 ```sh
 siteos seo research summary --json
 siteos seo research history --kind keywords --json
 siteos seo research show <run-id> --json
+siteos seo research serp show <run-id> --keyword "website analytics" --json
+siteos seo research serp ensure <run-id> --keyword "website analytics" --json
+siteos seo research serp wait <run-id> --keyword "website analytics" --json
+siteos seo research serp export <run-id> --keyword "website analytics" --format json --output ./serp-report.json --json
 siteos seo research plan --input ./research-request.json --json
 siteos seo research run --input ./research-request.json --idempotency-key <retry-key> --json
 siteos seo research wait <run-id> --json
@@ -209,7 +219,12 @@ siteos seo gsc export --dataset queries --format csv --output ./gsc-queries.csv
 ```
 
 Run `siteos seo --help` for request JSON, limits, saved inputs, cancellation and GSC settings.
-Research supports keywords, rankings, competitors, backlinks, brand and AI visibility without GSC.
+Research supports keywords, Domain Overview (`domain`), rankings, backlinks, brand and AI visibility without GSC.
+Domain Overview collects domain totals, up to 100 ranking keywords, pages and competitors for a market.
+`--kind domain` includes legacy `competitors` history; existing `competitors` inputs keep their original two-part plan.
+New request example: `{"kind":"domain","target":"example.com","country":"US","language":"en"}`.
+SERP `ensure` collects at most one saved snapshot per returned keyword and Keyword Research report. Repeat calls reuse the saved job, including failures. SERP show/wait/export only read; market and device come from the parent report.
+
 Reading/planning/saving spends no research credits. Launch uses Organization credits and the same
 server admission as the interface. Keep the retry key after an uncertain response; no paid retries
 are automatic. Wait exit 3 means pending; exit 4 failed/cancelled. Partial evidence remains readable.

package/dist/cli.js

@@ -10516,17 +10516,24 @@ var RESEARCH_HELP = `
   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 serp show <run-id> --keyword <word> [--environment <slug>] [--json]
+  siteos seo research serp ensure <run-id> --keyword <word> [--environment <slug>] [--json]
+  siteos seo research serp wait <run-id> --keyword <word> [--timeout <seconds>] [--environment <slug>] [--json]
+  siteos seo research serp export <run-id> --keyword <word> --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.
+Research kinds: keywords, domain, rankings, backlinks, brand, ai-visibility.
+Domain Overview: {"kind":"domain","target":"example.com","country":"US","language":"en"}.
+Domain collects summary, ranking keywords, top pages and competitors. The legacy competitors kind retains its two-part plan; domain history includes those reports.
 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.
+SERP ensure collects one saved organic snapshot for a keyword returned by the selected completed Keyword Research report. It uses research credits once; repeating the same report/word returns the saved job, including failures. Show/wait/export only read and never spend. New reports can collect fresh snapshots.
 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.
@@ -10539,7 +10546,10 @@ var kinds = [
   "brand",
   "ai-visibility"
 ];
-var requestSchema = z19.object({ kind: z19.enum(kinds), target: z19.string().min(1).max(253) }).passthrough();
+var requestSchema = z19.object({
+  kind: z19.enum(["domain", ...kinds]).transform((kind) => kind === "domain" ? "competitors" : kind),
+  target: z19.string().min(1).max(253)
+}).passthrough();
 var runStates = z19.enum([
   "queued",
   "running",
@@ -10564,6 +10574,7 @@ async function runSeoResearchCommand(options) {
         json: { type: "boolean" },
         environment: { type: "string" },
         kind: { type: "string" },
+        keyword: { type: "string" },
         input: { type: "string" },
         name: { type: "string" },
         id: { type: "string" },
@@ -10573,9 +10584,13 @@ async function runSeoResearchCommand(options) {
         output: { type: "string" }
       }
     });
-    const action = positionals[0] === "saved" ? positionals.slice(0, 2).join(" ") : positionals[0] ?? "";
-    const id = positionals[action.startsWith("saved ") ? 2 : 1];
+    const action = ["saved", "serp"].includes(positionals[0] ?? "") ? positionals.slice(0, 2).join(" ") : positionals[0] ?? "";
+    const id = positionals[action.includes(" ") ? 2 : 1];
     const operations = {
+      "serp show": { args: 3, flags: ["keyword"] },
+      "serp ensure": { args: 3, flags: ["keyword"] },
+      "serp wait": { args: 3, flags: ["keyword", "timeout"] },
+      "serp export": { args: 3, flags: ["keyword", "format", "output"] },
       summary: { args: 1, flags: [] },
       status: { args: 1, flags: ["kind"] },
       history: { args: 1, flags: ["kind"] },
@@ -10596,6 +10611,11 @@ async function runSeoResearchCommand(options) {
       throw new Error(
         "Invalid research operation or flags. Run siteos seo --help."
       );
+    if (action.startsWith("serp ") && (!values.keyword?.trim() || values.keyword.length > 200))
+      throw new Error(
+        "Provide --keyword with 1 to 200 characters from the selected keyword report."
+      );
+    if (values.kind === "domain") values.kind = "competitors";
     if (operation.flags.includes("kind") && !kinds.includes(values.kind))
       throw new Error("Choose a documented --kind.");
     if (operation.flags.includes("input") && !values.input)
@@ -10607,7 +10627,7 @@ async function runSeoResearchCommand(options) {
     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 ?? "")))
+    if (["export", "serp export"].includes(action) && (!values.output || !["json", "csv"].includes(values.format ?? "")))
       throw new Error(
         "Export requires --format json|csv and --output for a new file."
       );
@@ -10659,6 +10679,109 @@ async function runSeoResearchCommand(options) {
     );
     const query = `?kind=${encodeURIComponent(values.kind ?? "rankings")}`;
     let record;
+    if (action.startsWith("serp ")) {
+      const snapshotSchema = z19.object({
+        id: z19.string(),
+        organizationId: z19.literal(client.organizationId),
+        resourceId: z19.literal(client.resourceId),
+        sourceRunId: z19.literal(id),
+        request: requestSchema,
+        keywordKey: z19.literal(
+          values.keyword.normalize("NFKC").trim().toLowerCase().replace(/\s+/gu, " ")
+        ),
+        state: z19.enum([
+          "queued",
+          "running",
+          "completed",
+          "failed",
+          "cancelled"
+        ]),
+        dataset: z19.object({
+          type: z19.literal("serp"),
+          keyword: z19.string(),
+          country: z19.string(),
+          language: z19.string(),
+          device: z19.enum(["desktop", "mobile"]),
+          observedAt: z19.string(),
+          rows: z19.array(
+            z19.object({
+              position: z19.number(),
+              title: z19.string(),
+              url: z19.string(),
+              domain: z19.string(),
+              description: z19.string()
+            })
+          )
+        }).nullable()
+      }).passthrough();
+      const suffix = `/runs/${encodeURIComponent(id)}/serp`;
+      const read = () => get(`${suffix}?keyword=${encodeURIComponent(values.keyword)}`);
+      record = action === "serp ensure" ? await get(suffix, "run", { keyword: values.keyword }) : await read();
+      const deadline = Date.now() + timeout * 1e3;
+      let snapshot = record.serp == null ? null : snapshotSchema.parse(record.serp);
+      if (action === "serp ensure" && !snapshot)
+        throw new Error(
+          "The server did not return the admitted SERP snapshot."
+        );
+      while (action === "serp wait" && snapshot && ["queued", "running"].includes(snapshot.state)) {
+        if (Date.now() >= deadline)
+          return {
+            exitCode: 3,
+            stdout: JSON.stringify({ ...record, timedOut: true }, null, 2)
+          };
+        await setTimeout2(Math.min(2e3, Math.max(0, deadline - Date.now())));
+        record = await read();
+        snapshot = record.serp == null ? null : snapshotSchema.parse(record.serp);
+      }
+      if (action === "serp export") {
+        if (!snapshot)
+          throw new Error("No saved SERP exists for this report and keyword.");
+        const data = snapshot.dataset;
+        const content = values.format === "json" ? JSON.stringify(record, null, 2) : [
+          [
+            "report_id",
+            "keyword",
+            "country",
+            "language",
+            "device",
+            "state",
+            "observed_at",
+            "error",
+            "position",
+            "title",
+            "url",
+            "description"
+          ],
+          ...(data?.rows.length ? data.rows : [null]).map((row) => [
+            id,
+            values.keyword,
+            data?.country,
+            data?.language,
+            data?.device,
+            snapshot.state,
+            data?.observedAt,
+            snapshot.error,
+            row?.position,
+            row?.title,
+            row?.url,
+            row?.description
+          ])
+        ].map((row) => row.map(csvCell).join(",")).join("\r\n");
+        const output = await writeSeoReport(options, values.output, content);
+        record = {
+          contractVersion: 1,
+          runId: id,
+          keyword: values.keyword,
+          state: snapshot.state,
+          format: values.format,
+          output
+        };
+      }
+      return {
+        exitCode: action === "serp wait" && (!snapshot || ["failed", "cancelled"].includes(snapshot.state)) ? 4 : 0,
+        stdout: JSON.stringify(record, null, 2)
+      };
+    }
     if (action === "plan" || action === "run" || action === "saved save") {
       const plan = await get("/plan", "read", input);
       resourceSchema.parse(plan.resource);
@@ -11273,7 +11396,15 @@ async function runSeoPerformanceCommand(options) {
 }
 
 // src/services/seo-command.ts
-var SEO_HELP = `Audit SEO and work with search and AI research in the selected Project environment.
+var SEO_HELP = `SEO/GEO: audit your website and research search-engine and AI visibility in the selected Project environment.
+
+Site Audit checks public HTML, canonical, robots.txt, sitemap and technical GEO signals.
+Performance measures selected pages with Lighthouse and compares response/rendered HTML.
+Research covers keywords, rankings, competitors, backlinks, Brand lookup and Prompt checks.
+GSC Insights reads your connected property's Google Search Console data; other research needs no GSC.
+Technical GEO checks crawler policies, content, snippets and structured-data syntax/shape.
+These checks do not measure autonomous agent journeys or guarantee AI inclusion or citations.
+The service is named SEO/GEO in the application; its command remains siteos seo.
 
 Usage:
   siteos seo status [--environment <slug>] [--json]
@@ -11820,7 +11951,7 @@ Commands:
   cookie        Configure, publish, and inspect the Project\u2019s cookie banner.
   trace         Configure analytics observation and inspect evidence.
   analytics     Configure website Analytics, events and realtime reports.
-  seo           Audit HTML, inspect changes and verify fixes.
+  seo           SEO/GEO audits, keyword research and AI visibility reports.
   integrations  Manage Organization connections and destinations.
   pulse         Manage monitoring checks, tests, and deployments.
   search        Run SiteOS search operations for a project environment.