@viraatdas/rudder 3.8.2 → 3.9.0

package/README.md

@@ -286,6 +286,18 @@ the highlighted one's result below it, and `Esc` backs out. `review` stays inlin
 up to five rows — merge-ready work should be one keystroke away — and collapses the
 same way past that, because a 25-row review section is not scannable either.
 
+## Agent skills
+
+Rudder installs capability skills for every Claude Code and Codex agent it runs
+(user-level, as `rudder-<name>`):
+
+- **rudder-google-cloud**: create and name Google Cloud projects, enable APIs,
+  and set up "Sign in with Google" so the consent screen shows your product's
+  name, with a checker that verifies redirect URIs and the app name the way a
+  signed-out user sees them.
+
+Set `RUDDER_DISABLE_AGENT_SKILLS=1` to skip.
+
 ## Commands and Orchestrator Skills
 
 Type these in the bottom task input. When an interactive Claude orchestrator is

package/assets/skills/google-cloud/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: rudder-google-cloud
+description: Use for any Google Cloud or Google API setup — creating or naming a GCP project, enabling APIs (Gmail, Calendar, Drive, Gemini, …), "Sign in with Google" / Google OAuth clients, the consent screen (app name, logo, domains, scopes, verification, test users), redirect_uri_mismatch and other OAuth errors, gcloud auth, service accounts and keys, and storing the resulting secrets. Makes sure users see the product's own name on Google's screens, never a stray project like "My First Project".
+---
+
+# Google Cloud, done properly
+
+The failure this skill exists to prevent: a user clicks "Sign in with Google" and
+sees **"to continue to e2mail-494301"** or **"My First Project"** (or an
+unverified-app wall) because the OAuth client was dropped into whatever project
+was lying around. Every step below ends with a check of what a real user sees.
+
+Helper: `node <this skill dir>/scripts/gcp.mjs <command>` (Node 18+, no deps).
+It finds credentials from `gcloud`, gcloud's stored login, or ADC; run
+`whoami` first.
+
+## The rules
+
+1. **One project per product, named after the product.** Display name = the
+   product name exactly as marketed ("Tempo"); project ID = `<product>-<org>`
+   (immutable, globally unique, 6–30 chars). Never reuse another product's
+   project, a "My First Project", or a `gen-lang-client-*` Gemini project.
+   Create it under the user's organization (the helper picks the only org
+   automatically).
+2. **The consent screen's App name is what users read**, not the project name
+   and not the client name. Set it on the Branding page to the product name,
+   with the product's own support email, home page, privacy and terms URLs, and
+   the product's domain as an authorized domain.
+3. **Ask for the narrowest scopes that work.** Basic (openid/email/profile) can go
+   straight to production. Sensitive (Calendar, gmail.send) need verification.
+   Restricted (Gmail read/modify/compose, Drive full) need verification **and**
+   a CASA security assessment before more than 100 users; until then keep the
+   app in Testing and add test users. Tell the user this up front.
+4. **Secrets never touch chat or git.** Read the client secret once, write it
+   straight into the host's secret store (`fly secrets set`, `vercel env add`,
+   GitHub secrets), and refer to it by name afterwards.
+5. **Done means verified from outside**: `check-client` passes for every
+   redirect URI with the expected app name, and one real sign-in in a browser
+   reaches the app.
+
+## Workflow
+
+```bash
+G="node <skill dir>/scripts/gcp.mjs"
+$G whoami                                     # account, scopes, org
+$G projects --filter <product>                # is there already a right project?
+$G ensure-project --id <product>-<org> --name "<Product>"   # create, or fix the display name
+$G enable --project <id> --apis gmail,calendar              # aliases: drive sheets docs people gemini vertex run storage …
+$G audit --project <id>                       # name, parent, enabled APIs
+$G oauth-plan --project <id> --name "<Product>" --home https://<domain> \
+   --support <owner email> --redirect https://<domain>/<callback> [--redirect …] \
+   [--scopes gmail.readonly,calendar.readonly]
+```
+
+`oauth-plan` prints the exact Console pages and the value for every field.
+**Branding, Audience, Data access and Clients have no public API** (the old
+`gcloud alpha iap oauth-*` commands were shut down in March 2026; `gcloud iam
+oauth-clients` is for workforce identity, not "Sign in with Google"). Do them:
+
+- **With browser tools** (Claude in Chrome or the built-in browser): open each
+  URL from the plan, confirm the signed-in account chip is an owner of the
+  project, fill the fields verbatim, save. On the client page, copy the ID and
+  secret before closing the dialog — the secret is not shown again. Never type
+  the user's Google password; if the browser is signed out, stop and ask the
+  user to sign in.
+- **Without a browser**: hand the user the plan output as a checklist and ask
+  them to paste back the client ID and secret, or to set the secrets on the
+  host themselves (`! fly secrets set …`).
+
+Then store and verify:
+
+```bash
+fly secrets set -a <app> GOOGLE_CLIENT_ID=<id> GOOGLE_CLIENT_SECRET=<secret>   # or vercel env add / gh secret set
+$G check-client --client-id <id> --expect-name "<Product>" \
+   --redirect https://<domain>/<callback> [--redirect …]
+```
+
+`check-client` asks Google's real authorization endpoint, signed out, exactly
+as a new user's browser would. It catches `redirect_uri_mismatch`,
+`invalid_client`, `deleted_client`, Internal-only audiences and a wrong app
+name ("continue to e2mail-494301") without anyone signing in. Finish with one
+real sign-in in a browser and say in your report what the screen showed.
+
+## Getting the details right
+
+- **Redirect URIs match byte for byte**: scheme, host, port, path and trailing
+  slash. `https` only, except `http://localhost`/`127.0.0.1` for local dev. Add
+  the production URI and the local one if the app is developed locally; keep
+  staging on its own client if its domain differs.
+- **Authorized JavaScript origins** are only for the Google Identity Services
+  button/One Tap (browser-side flows); server-side redirect flows don't need them.
+- **Native apps** (iOS/Android/desktop) get their own client of that type; iOS
+  uses the reversed client ID as a URL scheme. Don't reuse the web client.
+- **Testing vs production**: in Testing only listed test users can sign in and
+  refresh tokens expire after 7 days — fine for a demo, wrong for real users.
+  Publish as soon as the scopes allow it.
+- **Logo**: uploading one triggers brand verification; leave it off until the
+  user is ready to verify. The name, links and domain still show.
+- **Internal user type** restricts sign-in to the org's Workspace accounts — only
+  right for internal tools.
+- **Verification** (sensitive/restricted scopes): needs the home page on the
+  authorized domain, a privacy policy describing Google data use (Limited Use),
+  a demo video of the consent flow, and for restricted scopes a CASA
+  assessment. Domain ownership is verified in Search Console by the same
+  account. Note it as a follow-up with the 100-user cap; don't silently ship.
+- **Service accounts** for server-to-server: prefer workload identity / attached
+  service accounts over JSON keys; if a key is unavoidable, create it with
+  `gcloud iam service-accounts keys create` straight into the secret store and
+  delete the local file.
+- **Billing** isn't needed for OAuth, Gmail or Calendar; it is for Maps, Vertex,
+  Cloud Run and most paid APIs. Check before promising those.
+- **Renaming later** is safe for the project display name (`ensure-project`
+  again) and the consent App name (Branding page). The project ID can never
+  change — choose it once, deliberately.
+
+## Report
+
+Say which project (ID and display name), which APIs, which client (ID, never
+the secret), where the secrets live, the `check-client` result per redirect
+URI, what the real sign-in screen showed, the publishing status, and any
+verification still owed (with the user cap it implies).

package/assets/skills/google-cloud/scripts/gcp.mjs

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+// Google Cloud helper for agents. No dependencies; Node 18+.
+//
+// Does everything Google exposes an API for (identity, projects, APIs) and,
+// for the parts that only exist in the Cloud Console (OAuth branding and
+// clients), prints the exact pages and values, then verifies the result from
+// the outside the way a user would see it.
+//
+//   node gcp.mjs whoami
+//   node gcp.mjs projects [--filter text]
+//   node gcp.mjs ensure-project --id tempo-exla --name "Tempo" [--org 123 | --folder 456]
+//   node gcp.mjs enable --project tempo-exla --apis gmail,calendar
+//   node gcp.mjs audit --project tempo-exla
+//   node gcp.mjs oauth-plan --project tempo-exla --name "Tempo" --home https://tempo.example.com \
+//        --support you@example.com --redirect https://tempo.example.com/api/auth/callback/google [--redirect …] \
+//        [--scopes gmail.readonly,calendar.readonly] [--privacy URL] [--terms URL] [--domain example.com]
+//   node gcp.mjs check-client --client-id ID --redirect URI [--redirect …] [--expect-name "Tempo"] [--scopes …]
+//
+// Auth, in order: GOOGLE_OAUTH_ACCESS_TOKEN, `gcloud auth print-access-token`,
+// gcloud's stored user credentials, application-default credentials.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const API_ALIASES = {
+  gmail: "gmail.googleapis.com",
+  calendar: "calendar-json.googleapis.com",
+  drive: "drive.googleapis.com",
+  sheets: "sheets.googleapis.com",
+  docs: "docs.googleapis.com",
+  people: "people.googleapis.com",
+  contacts: "people.googleapis.com",
+  youtube: "youtube.googleapis.com",
+  maps: "maps-backend.googleapis.com",
+  places: "places.googleapis.com",
+  gemini: "generativelanguage.googleapis.com",
+  vertex: "aiplatform.googleapis.com",
+  firebase: "firebase.googleapis.com",
+  run: "run.googleapis.com",
+  storage: "storage.googleapis.com",
+  secretmanager: "secretmanager.googleapis.com",
+  pubsub: "pubsub.googleapis.com",
+};
+
+// Scope shorthands → full scope, and Google's sensitivity class (drives verification).
+const SCOPES = {
+  "openid": ["openid", "basic"],
+  "email": ["https://www.googleapis.com/auth/userinfo.email", "basic"],
+  "profile": ["https://www.googleapis.com/auth/userinfo.profile", "basic"],
+  "gmail.readonly": ["https://www.googleapis.com/auth/gmail.readonly", "restricted"],
+  "gmail.modify": ["https://www.googleapis.com/auth/gmail.modify", "restricted"],
+  "gmail.compose": ["https://www.googleapis.com/auth/gmail.compose", "restricted"],
+  "gmail.send": ["https://www.googleapis.com/auth/gmail.send", "sensitive"],
+  "gmail.metadata": ["https://www.googleapis.com/auth/gmail.metadata", "restricted"],
+  "calendar.readonly": ["https://www.googleapis.com/auth/calendar.readonly", "sensitive"],
+  "calendar.events": ["https://www.googleapis.com/auth/calendar.events", "sensitive"],
+  "calendar": ["https://www.googleapis.com/auth/calendar", "sensitive"],
+  "drive.file": ["https://www.googleapis.com/auth/drive.file", "basic"],
+  "drive.readonly": ["https://www.googleapis.com/auth/drive.readonly", "restricted"],
+  "drive": ["https://www.googleapis.com/auth/drive", "restricted"],
+  "contacts.readonly": ["https://www.googleapis.com/auth/contacts.readonly", "sensitive"],
+};
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const flags = {};
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (!a.startsWith("--")) continue;
+    const key = a.slice(2);
+    const value = rest[i + 1] && !rest[i + 1].startsWith("--") ? rest[++i] : "true";
+    (flags[key] ??= []).push(value);
+  }
+  const one = (k) => flags[k]?.[flags[k].length - 1];
+  const many = (k) => (flags[k] ?? []).flatMap((v) => v.split(",")).map((v) => v.trim()).filter(Boolean);
+  return { command, one, many };
+}
+
+function fail(message) {
+  console.error(`✗ ${message}`);
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+
+function gcloudConfigDir() {
+  return process.env.CLOUDSDK_CONFIG || join(homedir(), ".config", "gcloud");
+}
+
+function activeAccount() {
+  try {
+    return execFileSync("gcloud", ["config", "get-value", "account"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+  } catch {}
+  const dir = gcloudConfigDir();
+  try {
+    const active = readFileSync(join(dir, "active_config"), "utf8").trim() || "default";
+    const config = readFileSync(join(dir, "configurations", `config_${active}`), "utf8");
+    return config.match(/^\s*account\s*=\s*(.+)$/m)?.[1]?.trim() ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function refresh(cred) {
+  const response = await fetch("https://oauth2.googleapis.com/token", {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ client_id: cred.client_id, client_secret: cred.client_secret, refresh_token: cred.refresh_token, grant_type: "refresh_token" }),
+  });
+  const data = await response.json();
+  if (!response.ok) throw new Error(`token refresh failed: ${data.error_description || data.error}`);
+  return data.access_token;
+}
+
+let cachedToken;
+async function token() {
+  if (cachedToken) return cachedToken;
+  if (process.env.GOOGLE_OAUTH_ACCESS_TOKEN) return (cachedToken = process.env.GOOGLE_OAUTH_ACCESS_TOKEN);
+  try {
+    const t = execFileSync("gcloud", ["auth", "print-access-token"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    if (t) return (cachedToken = t);
+  } catch {}
+  const dir = gcloudConfigDir();
+  const account = activeAccount();
+  const candidates = [];
+  if (account) candidates.push(join(dir, "legacy_credentials", account, "adc.json"));
+  if (existsSync(join(dir, "legacy_credentials"))) {
+    for (const a of readdirSync(join(dir, "legacy_credentials"))) candidates.push(join(dir, "legacy_credentials", a, "adc.json"));
+  }
+  candidates.push(process.env.GOOGLE_APPLICATION_CREDENTIALS ?? "", join(dir, "application_default_credentials.json"));
+  for (const file of candidates) {
+    if (!file || !existsSync(file)) continue;
+    const cred = JSON.parse(readFileSync(file, "utf8"));
+    if (cred.type === "authorized_user") return (cachedToken = await refresh(cred));
+  }
+  fail("No Google credentials. Ask the user to run `! gcloud auth login` (and `! gcloud auth application-default login` for ADC), or install the SDK: https://cloud.google.com/sdk/docs/install");
+}
+
+async function api(method, url, body) {
+  const response = await fetch(url, {
+    method,
+    headers: { Authorization: `Bearer ${await token()}`, "content-type": "application/json" },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await response.text();
+  const data = text ? JSON.parse(text) : {};
+  if (!response.ok) {
+    const err = new Error(`${method} ${url.replace(/^https:\/\//, "")}: ${response.status} ${data.error?.message ?? text.slice(0, 300)}`);
+    err.status = response.status;
+    throw err;
+  }
+  return data;
+}
+
+async function wait(operation, base) {
+  let op = operation;
+  for (let i = 0; i < 60 && !op.done; i++) {
+    await new Promise((r) => setTimeout(r, 2000));
+    op = await api("GET", `${base}/${op.name}`);
+  }
+  if (op.error) throw new Error(`operation failed: ${op.error.message}`);
+  return op;
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+async function whoami() {
+  const info = await api("GET", "https://www.googleapis.com/oauth2/v3/userinfo").catch(() => null);
+  const tokenInfo = await (await fetch(`https://oauth2.googleapis.com/tokeninfo?access_token=${await token()}`)).json();
+  console.log(`account: ${info?.email ?? tokenInfo.email ?? activeAccount() ?? "unknown"}`);
+  console.log(`scopes:  ${(tokenInfo.scope ?? "").split(" ").map((s) => s.replace("https://www.googleapis.com/auth/", "")).join(", ")}`);
+  const orgs = await api("POST", "https://cloudresourcemanager.googleapis.com/v1/organizations:search", {}).catch(() => ({}));
+  for (const o of orgs.organizations ?? []) console.log(`org:     ${o.displayName} (${o.name.split("/")[1]})`);
+}
+
+async function listProjects(filter) {
+  const out = [];
+  let pageToken;
+  do {
+    const page = await api("GET", `https://cloudresourcemanager.googleapis.com/v1/projects?pageSize=500${pageToken ? `&pageToken=${pageToken}` : ""}`);
+    out.push(...(page.projects ?? []));
+    pageToken = page.nextPageToken;
+  } while (pageToken);
+  return out.filter((p) => p.lifecycleState === "ACTIVE" && (!filter || `${p.projectId} ${p.name}`.toLowerCase().includes(filter.toLowerCase())));
+}
+
+async function projects(filter) {
+  const list = await listProjects(filter);
+  for (const p of list) console.log(`${p.projectId.padEnd(34)} ${JSON.stringify(p.name).padEnd(30)} ${p.parent ? `${p.parent.type}/${p.parent.id}` : "no parent"}`);
+  console.log(`${list.length} project(s)`);
+}
+
+const PROJECT_ID = /^[a-z][a-z0-9-]{4,28}[a-z0-9]$/;
+
+async function ensureProject(id, name, org, folder) {
+  if (!id || !name) fail("--id and --name are required (name is what people see; use the product's name)");
+  if (!PROJECT_ID.test(id)) fail(`"${id}" is not a valid project ID: 6-30 chars, lowercase letters, digits, hyphens, starts with a letter`);
+  if (/^(my first project|untitled|test|default|new project)$/i.test(name)) fail(`"${name}" is a placeholder; name the project after the product`);
+  let existing = await api("GET", `https://cloudresourcemanager.googleapis.com/v3/projects/${id}`).catch((e) => (e.status === 403 || e.status === 404 ? null : Promise.reject(e)));
+  if (existing && existing.state !== "ACTIVE") fail(`${id} exists but is ${existing.state}; pick another ID or restore it`);
+  if (!existing) {
+    if (!org && !folder) {
+      const orgs = (await api("POST", "https://cloudresourcemanager.googleapis.com/v1/organizations:search", {}).catch(() => ({}))).organizations ?? [];
+      if (orgs.length === 1) org = orgs[0].name.split("/")[1];
+    }
+    const parent = folder ? `folders/${folder}` : org ? `organizations/${org}` : undefined;
+    console.log(`creating ${id} "${name}"${parent ? ` under ${parent}` : ""}…`);
+    try {
+      await wait(await api("POST", "https://cloudresourcemanager.googleapis.com/v3/projects", { projectId: id, displayName: name, ...(parent ? { parent } : {}) }), "https://cloudresourcemanager.googleapis.com/v3");
+    } catch (error) {
+      if (/already exists|ALREADY_EXISTS/i.test(error.message)) fail(`project ID ${id} is taken globally (by someone else); choose another, e.g. ${id}-app`);
+      throw error;
+    }
+    existing = await api("GET", `https://cloudresourcemanager.googleapis.com/v3/projects/${id}`);
+  } else if (existing.displayName !== name) {
+    console.log(`renaming ${id}: "${existing.displayName}" → "${name}"`);
+    await wait(await api("PATCH", `https://cloudresourcemanager.googleapis.com/v3/projects/${id}?updateMask=displayName`, { displayName: name }), "https://cloudresourcemanager.googleapis.com/v3");
+    existing = await api("GET", `https://cloudresourcemanager.googleapis.com/v3/projects/${id}`);
+  }
+  console.log(`✓ project ${existing.projectId} "${existing.displayName}" (number ${existing.name.split("/")[1]}, parent ${existing.parent ?? "none"})`);
+}
+
+function serviceIds(list) {
+  return list.map((a) => API_ALIASES[a] ?? (a.includes(".") ? a : `${a}.googleapis.com`));
+}
+
+async function enable(project, apis) {
+  if (!project || !apis.length) fail("--project and --apis are required");
+  const ids = serviceIds(apis);
+  await wait(await api("POST", `https://serviceusage.googleapis.com/v1/projects/${project}/services:batchEnable`, { serviceIds: ids }), "https://serviceusage.googleapis.com/v1");
+  console.log(`✓ enabled on ${project}: ${ids.join(", ")}`);
+}
+
+async function audit(project) {
+  if (!project) fail("--project is required");
+  const p = await api("GET", `https://cloudresourcemanager.googleapis.com/v3/projects/${project}`);
+  console.log(`project:  ${p.projectId}  name "${p.displayName}"  state ${p.state}  parent ${p.parent ?? "none"}`);
+  if (/^(my first project|untitled)/i.test(p.displayName) || p.displayName === p.projectId) {
+    console.log(`  ! the display name is a placeholder; run ensure-project --id ${p.projectId} --name "<Product>"`);
+  }
+  const services = [];
+  let pageToken;
+  do {
+    const page = await api("GET", `https://serviceusage.googleapis.com/v1/projects/${project}/services?filter=state:ENABLED&pageSize=200${pageToken ? `&pageToken=${pageToken}` : ""}`);
+    services.push(...(page.services ?? []).map((s) => s.config.name));
+    pageToken = page.nextPageToken;
+  } while (pageToken);
+  console.log(`apis:     ${services.filter((s) => !/^(bigquery|cloudapis|cloudtrace|datastore|logging|monitoring|servicemanagement|serviceusage|sql-component|storage-api|storage-component|cloudasset|dataform|dataplex|analyticshub|bigquery\w*)\./.test(s)).join(", ") || "(only defaults)"}`);
+  console.log(`console:  https://console.cloud.google.com/auth/overview?project=${project}`);
+  console.log("note:     OAuth branding and clients have no public API; check them in the Console or with check-client.");
+}
+
+function oauthPlan(o) {
+  const project = o.one("project");
+  const name = o.one("name");
+  const home = o.one("home");
+  const support = o.one("support");
+  const redirects = o.many("redirect");
+  if (!project || !name || !home || !support || !redirects.length) fail("--project, --name, --home, --support and at least one --redirect are required");
+  const homeUrl = new URL(home);
+  const domain = o.one("domain") ?? homeUrl.hostname.split(".").slice(-2).join(".");
+  const privacy = o.one("privacy") ?? `${homeUrl.origin}/privacy`;
+  const terms = o.one("terms") ?? `${homeUrl.origin}/terms`;
+  const scopes = ["openid", "email", "profile", ...o.many("scopes")];
+  const resolved = scopes.map((s) => [s, ...(SCOPES[s] ?? [s.startsWith("http") ? s : `https://www.googleapis.com/auth/${s}`, "unknown"])]);
+  const worst = resolved.some((r) => r[2] === "restricted") ? "restricted" : resolved.some((r) => r[2] === "sensitive") ? "sensitive" : "basic";
+  const bad = redirects.filter((r) => {
+    try {
+      const u = new URL(r);
+      return !(u.protocol === "https:" || (u.protocol === "http:" && /^(localhost|127\.0\.0\.1|\[::1\])$/.test(u.hostname)));
+    } catch {
+      return true;
+    }
+  });
+  if (bad.length) fail(`redirect URIs must be https (or http://localhost): ${bad.join(", ")}`);
+  const base = "https://console.cloud.google.com/auth";
+  const q = `?project=${project}`;
+  console.log(`OAuth setup for "${name}" in project ${project}. None of this has a public API: do it in the Console`);
+  console.log(`(Claude in Chrome / the user's browser), signed in as an owner of ${project}. Check the account chip first.\n`);
+  console.log(`1. Branding        ${base}/branding${q}`);
+  console.log(`   App name ............ ${name}        ← exactly what users see: "Sign in to continue to ${name}"`);
+  console.log(`   User support email .. ${support}`);
+  console.log(`   App logo ............ optional (a logo sends the app to brand verification; skip it until you verify)`);
+  console.log(`   Application home .... ${homeUrl.origin}`);
+  console.log(`   Privacy policy ...... ${privacy}`);
+  console.log(`   Terms of service .... ${terms}`);
+  console.log(`   Authorized domains .. ${domain}`);
+  console.log(`   Developer contact ... ${support}`);
+  console.log(`2. Audience        ${base}/audience${q}`);
+  console.log(`   User type External (Internal only lets accounts in your Workspace sign in).`);
+  console.log(worst === "basic"
+    ? "   Publishing status: Publish app → In production (basic scopes need no review)."
+    : `   Keep "Testing" and add test users until verified; in Testing, refresh tokens expire after 7 days and only test users can sign in.`);
+  console.log(`3. Data access     ${base}/scopes${q}`);
+  for (const [short, full, kind] of resolved) console.log(`   ${kind.padEnd(10)} ${full === "openid" ? "openid" : full}${short !== full ? `  (${short})` : ""}`);
+  if (worst === "restricted") console.log("   Restricted scopes need Google verification + a CASA security assessment before > 100 users / non-test users. Prefer narrower scopes if they work.");
+  else if (worst === "sensitive") console.log("   Sensitive scopes need Google verification (a demo video + justification) before the unverified-app warning goes away.");
+  console.log(`4. Clients         ${base}/clients/create${q}`);
+  console.log(`   Application type: Web application     Name: ${name} web`);
+  for (const r of redirects) console.log(`   Authorized redirect URI: ${r}`);
+  console.log("   Create, then copy the client ID and secret at once (the secret is not shown again; download the JSON).");
+  console.log("5. Store, never print. e.g.");
+  console.log("   fly secrets set -a <app> GOOGLE_CLIENT_ID=… GOOGLE_CLIENT_SECRET=…   |   vercel env add GOOGLE_CLIENT_SECRET production");
+  console.log("6. Verify from outside:");
+  console.log(`   node ${process.argv[1]} check-client --client-id <ID> --expect-name "${name}"${redirects.map((r) => ` --redirect ${r}`).join("")}`);
+  console.log("   then do one real sign-in in a browser and confirm the consent screen says the right name.");
+}
+
+function pageText(html) {
+  return html
+    .replace(/<script[\s\S]*?<\/script>|<style[\s\S]*?<\/style>/g, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&#39;|&#x27;/g, "'")
+    .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, "&")
+    .replace(/\s+/g, " ");
+}
+
+// What a signed-out user's browser gets for this client + redirect. Google
+// validates the client and redirect before asking anyone to sign in, and the
+// sign-in page names the app from the consent screen's Branding.
+async function probe(clientId, redirect, scopes) {
+  const url = new URL("https://accounts.google.com/o/oauth2/v2/auth");
+  url.search = new URLSearchParams({ client_id: clientId, redirect_uri: redirect, response_type: "code", scope: scopes.join(" "), prompt: "select_account" }).toString();
+  const response = await fetch(url, { redirect: "follow", headers: { "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36", "accept-language": "en-US" } });
+  const text = pageText(await response.text());
+  const error = text.match(/Error 400: (\w+)/)?.[1] ?? text.match(/Error 401: (\w+)/)?.[1] ?? text.match(/Error 403: (\w+)/)?.[1] ?? (response.url.includes("/signin/oauth/error") ? "unknown_error" : null);
+  const appName = text.match(/to continue to ([^.]+?)(?:\s+(?:Email|Forgot|Not your|Create account|Next)\b|$)/)?.[1]?.trim() ?? null;
+  return { error, appName, finalUrl: response.url };
+}
+
+async function checkClient(o) {
+  const clientId = o.one("client-id");
+  const redirects = o.many("redirect");
+  const expect = o.one("expect-name");
+  const scopes = ["openid", "email", ...o.many("scopes").map((s) => SCOPES[s]?.[0] ?? s)];
+  if (!clientId || !redirects.length) fail("--client-id and at least one --redirect are required");
+  if (!/\.apps\.googleusercontent\.com$/.test(clientId)) fail("that doesn't look like a Google OAuth client ID (…apps.googleusercontent.com)");
+  let ok = true;
+  for (const redirect of redirects) {
+    const r = await probe(clientId, redirect, scopes);
+    if (r.error) {
+      ok = false;
+      const hint = {
+        redirect_uri_mismatch: `add exactly ${redirect} to the client's Authorized redirect URIs (scheme, host, path and trailing slash must match)`,
+        invalid_client: "the client ID is wrong, or the client was deleted",
+        deleted_client: "this client was deleted; create a new one",
+        invalid_request: "the request is malformed (often a non-https redirect or a scope typo)",
+        access_denied: "the app is blocked (org policy, or Testing mode without this user as a test user)",
+        org_internal: "the consent screen is Internal; switch Audience to External",
+      }[r.error] ?? "see the Console's client page";
+      console.log(`✗ ${redirect}: ${r.error}. Fix: ${hint}.`);
+      continue;
+    }
+    if (!r.appName) {
+      console.log(`? ${redirect}: accepted, but the app name wasn't readable (Google changed the page?). Check by signing in once.`);
+      continue;
+    }
+    const nameOk = !expect || r.appName.toLowerCase() === expect.toLowerCase();
+    if (!nameOk) ok = false;
+    console.log(`${nameOk ? "✓" : "✗"} ${redirect}: accepted; Google shows "continue to ${r.appName}"${nameOk ? "" : `, expected "${expect}". Fix the App name on the Branding page (it is not the project name).`}`);
+  }
+  if (!ok) process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+
+const o = parseArgs(process.argv.slice(2));
+try {
+  switch (o.command) {
+    case "whoami": await whoami(); break;
+    case "projects": await projects(o.one("filter")); break;
+    case "ensure-project": await ensureProject(o.one("id"), o.one("name"), o.one("org"), o.one("folder")); break;
+    case "enable": await enable(o.one("project"), o.many("apis")); break;
+    case "audit": await audit(o.one("project")); break;
+    case "oauth-plan": oauthPlan(o); break;
+    case "check-client": await checkClient(o); break;
+    default:
+      console.log(readFileSync(new URL(import.meta.url), "utf8").split("\n").slice(1, 19).map((l) => l.replace(/^\/\/ ?/, "")).join("\n"));
+      process.exit(o.command ? 1 : 0);
+  }
+} catch (error) {
+  fail(error.message);
+}

package/dist/agent-skills.d.ts

@@ -0,0 +1,16 @@
+export type AgentSkillTarget = {
+    agent: "claude" | "codex";
+    dir: string;
+};
+export declare function agentSkillsSourceDir(): string;
+export declare function agentSkillTargets(home?: string, env?: NodeJS.ProcessEnv): AgentSkillTarget[];
+export type InstallResult = {
+    installed: string[];
+    updatedFiles: number;
+};
+export declare function installAgentSkills(options?: {
+    sourceDir?: string;
+    targets?: AgentSkillTarget[];
+}): Promise<InstallResult>;
+/** Best effort: a read-only home or odd permissions must never block a run. */
+export declare function ensureAgentSkills(env?: NodeJS.ProcessEnv): Promise<void>;

package/dist/agent-skills.js

@@ -0,0 +1,68 @@
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export function agentSkillsSourceDir() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "assets", "skills");
+}
+export function agentSkillTargets(home = os.homedir(), env = process.env) {
+    return [
+        { agent: "claude", dir: path.join(env.CLAUDE_CONFIG_DIR || path.join(home, ".claude"), "skills") },
+        { agent: "codex", dir: path.join(env.CODEX_HOME || path.join(home, ".codex"), "skills") },
+    ];
+}
+async function listFiles(root, rel = "") {
+    const entries = await fsp.readdir(path.join(root, rel), { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const child = path.join(rel, entry.name);
+        if (entry.isDirectory())
+            files.push(...(await listFiles(root, child)));
+        else if (entry.isFile())
+            files.push(child);
+    }
+    return files;
+}
+export async function installAgentSkills(options = {}) {
+    const sourceDir = options.sourceDir ?? agentSkillsSourceDir();
+    const targets = options.targets ?? agentSkillTargets();
+    let skills;
+    try {
+        skills = (await fsp.readdir(sourceDir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return { installed: [], updatedFiles: 0 };
+    }
+    const installed = [];
+    let updatedFiles = 0;
+    for (const skill of skills) {
+        const files = await listFiles(path.join(sourceDir, skill));
+        if (!files.includes("SKILL.md"))
+            continue;
+        for (const target of targets) {
+            const dest = path.join(target.dir, `rudder-${skill}`);
+            for (const file of files) {
+                const from = path.join(sourceDir, skill, file);
+                const to = path.join(dest, file);
+                const content = await fsp.readFile(from);
+                const current = await fsp.readFile(to).catch(() => null);
+                if (current && current.equals(content))
+                    continue;
+                await fsp.mkdir(path.dirname(to), { recursive: true });
+                await fsp.writeFile(to, content);
+                if (file.startsWith(`scripts${path.sep}`))
+                    await fsp.chmod(to, 0o755);
+                updatedFiles++;
+            }
+            installed.push(`${target.agent}:rudder-${skill}`);
+        }
+    }
+    return { installed, updatedFiles };
+}
+/** Best effort: a read-only home or odd permissions must never block a run. */
+export async function ensureAgentSkills(env = process.env) {
+    if (env.RUDDER_DISABLE_AGENT_SKILLS === "1")
+        return;
+    await installAgentSkills().catch(() => undefined);
+}
+//# sourceMappingURL=agent-skills.js.map

package/dist/agent-skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-skills.js","sourceRoot":"","sources":["../src/agent-skills.ts"],"names":[],"mappings":"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"}

package/dist/attach-session.d.ts

@@ -23,6 +23,7 @@ export type SessionOptions = {
 };
 export declare const KITTY_KEYBOARD_PUSH = "\u001B[>5u";
 export declare const KITTY_KEYBOARD_POP = "\u001B[<u";
+export declare const KEYBOARD_RESET = "\u001B[<99u\u001B[=0;1u\u001B[>4m\u001B[?1004l";
 export declare function containsCtrlC(data: Buffer): boolean;
 export declare class AttachSession {
     /** Sent as `?client=`: the relay lets this terminal take its own place back. */