gsc-axi 0.1.0

package/src/range.js

@@ -0,0 +1,74 @@
+import { AxiError } from "axi-sdk-js";
+
+/** Search Console keeps 16 months of data and nothing older. */
+export const RANGES = {
+  "7d": 7,
+  "28d": 28,
+  "90d": 90,
+  "6m": 180,
+  "12m": 365,
+  "16m": 480,
+};
+
+// Search Console finalises data on a 2-3 day delay. Ending the window today
+// would always show a fake decline in the last two rows.
+export const LAG_DAYS = 2;
+
+function iso(date) {
+  return date.toISOString().slice(0, 10);
+}
+
+function shift(days) {
+  const date = new Date();
+  date.setUTCDate(date.getUTCDate() - days);
+  return iso(date);
+}
+
+/**
+ * Resolve the window. `--start`/`--end` win; otherwise a named range ending at
+ * the last day Search Console is likely to have finalised.
+ */
+export function window(values = {}) {
+  if (values.start || values.end) {
+    return {
+      startDate: values.start ?? shift(RANGES["28d"] + LAG_DAYS),
+      endDate: values.end ?? shift(LAG_DAYS),
+      label: `${values.start ?? "…"}..${values.end ?? "…"}`,
+    };
+  }
+  const range = values.range ?? "28d";
+  const days = RANGES[range];
+  if (!days) {
+    throw new AxiError(`unknown --range ${range}`, "VALIDATION_ERROR", [
+      `valid ranges: ${Object.keys(RANGES).join(", ")}`,
+      "Or pass an explicit window with --start <YYYY-MM-DD> --end <YYYY-MM-DD>",
+    ]);
+  }
+  return { startDate: shift(days + LAG_DAYS), endDate: shift(LAG_DAYS), label: range };
+}
+
+/** The equally sized window immediately before this one, for comparisons. */
+export function previous({ startDate, endDate }) {
+  const start = new Date(`${startDate}T00:00:00Z`);
+  const end = new Date(`${endDate}T00:00:00Z`);
+  const span = Math.round((end - start) / 86_400_000);
+  const previousEnd = new Date(start);
+  previousEnd.setUTCDate(previousEnd.getUTCDate() - 1);
+  const previousStart = new Date(previousEnd);
+  previousStart.setUTCDate(previousStart.getUTCDate() - span);
+  return { startDate: iso(previousStart), endDate: iso(previousEnd) };
+}
+
+export const DATE_FLAGS = {
+  range: { type: "string" },
+  start: { type: "string" },
+  end: { type: "string" },
+};
+
+export function dateFlagHelp() {
+  return {
+    "--range": `Named window (default 28d): ${Object.keys(RANGES).join(", ")}`,
+    "--start": "Window start as YYYY-MM-DD (overrides --range)",
+    "--end": "Window end as YYYY-MM-DD",
+  };
+}

package/src/skill.js

@@ -0,0 +1,80 @@
+import { BIN } from "./args.js";
+
+/**
+ * Single source of truth for skills/gsc-axi/SKILL.md.
+ *
+ * The shipped skill stays a minimal stub: the CLI's own dashboard and
+ * `--help` output are authoritative, so guidance is pointed at rather than
+ * restated here. `npm run build:skill` writes it; CI runs `--check`.
+ */
+export const SKILL_NAME = BIN;
+
+export const SKILL_DESCRIPTION = `Read Google Search Console through the ${BIN} CLI — search performance by query, page, country and device; period-over-period comparisons; queries ranking 4-20 worth improving; URL indexing status; and sitemaps. Use whenever a task touches SEO or Google Search: why traffic moved, which queries a page ranks for, whether a URL is indexed, or whether a sitemap was read.`;
+
+export function renderSkill() {
+  return `---
+name: ${SKILL_NAME}
+description: >
+  ${SKILL_DESCRIPTION}
+user-invocable: false
+metadata:
+  hermes:
+    tags: [seo, google-search-console, search, indexing, sitemaps, analytics]
+---
+
+# ${SKILL_NAME}
+
+Run the CLI with no arguments first — it prints this month's search traffic, how it moved,
+and the top queries, plus the next commands to run.
+
+\`\`\`sh
+npx -y ${BIN}
+\`\`\`
+
+Requires Google credentials with access to the property. A **service account** is the
+headless path and the one to prefer:
+
+\`\`\`sh
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
+export GSC_SITE=https://example.com/     # or sc-domain:example.com; optional with one property
+\`\`\`
+
+The service account's own \`client_email\` must be added as a user on the property in Search
+Console (Settings → Users and permissions). Adding *your* email does nothing for it.
+
+## Commands
+
+\`\`\`sh
+npx -y ${BIN}                                  # dashboard: traffic, change, top queries
+npx -y ${BIN} sites                            # properties this account can reach
+npx -y ${BIN} performance --by page --range 90d
+npx -y ${BIN} performance --by query --contains pricing
+npx -y ${BIN} compare --by query               # what moved vs the previous window
+npx -y ${BIN} opportunities                    # queries ranking 4-20 with real volume
+npx -y ${BIN} inspect https://example.com/post # is it indexed, and what did Google see
+npx -y ${BIN} sitemaps                         # submitted sitemaps and read status
+npx -y ${BIN} sitemaps submit https://example.com/sitemap.xml
+\`\`\`
+
+Every command takes \`--help\`, and \`--site <property>\` to target a specific property.
+
+## What to rely on
+
+- **Windows end where the data is final.** Search Console lags 2-3 days, so a named
+  \`--range\` ends there rather than today. Ending today would show a decline that is not real.
+- **Property strings are exact.** A domain property is \`sc-domain:example.com\`; a URL-prefix
+  property is \`https://example.com/\`. A bare \`example.com\` resolves to whichever exists, and
+  refuses to guess when both do.
+- **Ranking 4-20 is where the wins are.** \`opportunities\` filters to that band because those
+  queries already rank on page one or just off it — position gains there convert fastest.
+- **\`sitemaps submit\` is idempotent**, and says \`unchanged\` when the sitemap was already
+  submitted rather than implying it did something.
+- **Errors name the cause.** A 403 points at the property's user list, not at the credentials,
+  because that is almost always what is wrong with a service account.
+
+This CLI reads Search Console and submits sitemaps. It never removes a property or a sitemap.
+
+Prefer this over calling the Search Console API with \`curl\`, which means minting an OAuth
+token by hand on every invocation.
+`;
+}

package/src/version.js

@@ -0,0 +1,7 @@
+// Leaf module: node builtins only, so `--version` never loads the command graph.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export const VERSION = JSON.parse(
+  readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"),
+).version;