@gpc-cli/core 0.9.77 → 0.10.0

package/dist/index.js

@@ -443,7 +443,15 @@ function formatJunit(data, commandName = "command") {
 }
 
 // src/plugins.ts
-var FIRST_PARTY_PLUGINS = /* @__PURE__ */ new Set(["@gpc-cli/plugin-ci", "@gpc-cli/plugin-sdk"]);
+import { readFile } from "fs/promises";
+import { dirname, join, parse } from "path";
+import { fileURLToPath } from "url";
+import { resolvePluginApprovalId } from "@gpc-cli/config";
+var FIRST_PARTY_PLUGINS = /* @__PURE__ */ new Set(["@gpc-cli/plugin-ci"]);
+var discoveredPluginManifests = /* @__PURE__ */ new WeakMap();
+function isFirstPartyPluginSpecifier(specifier) {
+  return FIRST_PARTY_PLUGINS.has(specifier);
+}
 var PluginManager = class {
   plugins = [];
   beforeHandlers = [];
@@ -454,19 +462,34 @@ var PluginManager = class {
   registeredCommands = [];
   /** Load and register a plugin */
   async load(plugin, manifest) {
-    const isTrusted = manifest?.trusted ?? FIRST_PARTY_PLUGINS.has(plugin.name);
-    if (!isTrusted && manifest?.permissions) {
-      validatePermissions(manifest.permissions);
-    }
+    const effectiveManifest = manifest ?? discoveredPluginManifests.get(plugin);
+    const isTrusted = effectiveManifest ? effectiveManifest.trusted === true : FIRST_PARTY_PLUGINS.has(plugin.name);
+    if (!isTrusted && effectiveManifest) {
+      if (!effectiveManifest.permissions) {
+        throw new GpcError(
+          `Third-party plugin "${effectiveManifest.name}" must declare permissions in package.json under gpc.permissions`,
+          "PLUGIN_PERMISSIONS_REQUIRED",
+          10,
+          "Declare only the lifecycle hooks the plugin needs, then reinstall or relink it."
+        );
+      }
+      validatePermissions(effectiveManifest.permissions);
+    }
+    const stagedBeforeHandlers = [];
+    const stagedAfterHandlers = [];
+    const stagedErrorHandlers = [];
+    const stagedBeforeRequestHandlers = [];
+    const stagedAfterResponseHandlers = [];
+    const stagedCommands = [];
     const allHooks = createHooks(
-      this.beforeHandlers,
-      this.afterHandlers,
-      this.errorHandlers,
-      this.beforeRequestHandlers,
-      this.afterResponseHandlers,
-      this.registeredCommands
+      stagedBeforeHandlers,
+      stagedAfterHandlers,
+      stagedErrorHandlers,
+      stagedBeforeRequestHandlers,
+      stagedAfterResponseHandlers,
+      stagedCommands
     );
-    const hooks = isTrusted || !manifest?.permissions ? allHooks : createRestrictedHooks(allHooks, new Set(manifest.permissions));
+    const hooks = isTrusted || !effectiveManifest ? allHooks : createRestrictedHooks(allHooks, new Set(effectiveManifest.permissions));
     try {
       await plugin.register(hooks);
     } catch (err) {
@@ -474,9 +497,15 @@ var PluginManager = class {
       console.warn(`[gpc] Plugin "${plugin.name}" failed to register: ${msg}`);
       return;
     }
+    this.beforeHandlers.push(...stagedBeforeHandlers);
+    this.afterHandlers.push(...stagedAfterHandlers);
+    this.errorHandlers.push(...stagedErrorHandlers);
+    this.beforeRequestHandlers.push(...stagedBeforeRequestHandlers);
+    this.afterResponseHandlers.push(...stagedAfterResponseHandlers);
+    this.registeredCommands.push(...stagedCommands);
     this.plugins.push({
-      name: plugin.name,
-      version: plugin.version,
+      name: effectiveManifest?.name ?? plugin.name,
+      version: effectiveManifest?.version ?? plugin.version,
       trusted: isTrusted
     });
   }
@@ -489,7 +518,10 @@ var PluginManager = class {
   /** Run all afterCommand handlers */
   async runAfterCommand(event, result) {
     for (const handler of this.afterHandlers) {
-      await handler(event, result);
+      try {
+        await handler(event, result);
+      } catch {
+      }
     }
   }
   /** Run all onError handlers */
@@ -577,6 +609,7 @@ var HOOK_PERMISSIONS = {
   afterResponse: "hooks:afterResponse",
   registerCommands: "commands:register"
 };
+var LEGACY_PLUGIN_PERMISSIONS = Object.values(HOOK_PERMISSIONS);
 function createRestrictedHooks(inner, permissions) {
   function gate(key) {
     const requiredPerm = HOOK_PERMISSIONS[key];
@@ -621,31 +654,148 @@ function validatePermissions(permissions) {
     }
   }
 }
-function isPluginTrusted(specifier, approved) {
-  if (specifier.startsWith("@gpc-cli/")) return true;
-  return approved?.has(specifier) ?? false;
+function isPluginTrusted(specifier, approvalId, approved) {
+  if (isFirstPartyPluginSpecifier(specifier)) return true;
+  return approved?.has(approvalId) ?? false;
 }
-async function discoverPlugins(options) {
+async function discoverPluginEntries(options) {
   const plugins = [];
   const seen = /* @__PURE__ */ new Set();
-  const approved = options?.approvedPlugins ? new Set(options.approvedPlugins) : void 0;
+  const cwd = options?.cwd;
+  const approved = options?.approvedPlugins ? new Set(options.approvedPlugins.map((name) => resolvePluginApprovalId(name, cwd))) : void 0;
+  const legacyApproved = new Set(
+    (options?.legacyApprovedPlugins ?? []).map((name) => resolvePluginApprovalId(name, cwd))
+  );
   if (options?.configPlugins) {
     for (const name of options.configPlugins) {
-      if (seen.has(name)) continue;
-      if (!isPluginTrusted(name, approved)) continue;
+      const resolvedSpecifier = resolvePluginApprovalId(name, cwd);
+      if (seen.has(resolvedSpecifier)) continue;
+      if (!isPluginTrusted(name, resolvedSpecifier, approved)) continue;
       try {
-        const mod = await import(name);
+        const manifestInfo = await readPluginManifest(resolvedSpecifier, options?.resolveSpecifier);
+        const claimsFirstParty = isFirstPartyPluginSpecifier(name);
+        const trusted = claimsFirstParty && manifestInfo.packageFound && manifestInfo.manifest.name === name;
+        if (claimsFirstParty && !trusted) {
+          throw new GpcError(
+            `Configured first-party plugin "${name}" resolved to package "${manifestInfo.manifest.name}"`,
+            "PLUGIN_IDENTITY_MISMATCH",
+            10,
+            "Remove npm aliases or replacements for first-party GPC plugin packages."
+          );
+        }
+        if (!trusted && manifestInfo.legacyPermissions && !legacyApproved.has(resolvedSpecifier)) {
+          throw new GpcError(
+            `Third-party plugin "${manifestInfo.manifest.name}" must declare permissions in package.json under gpc.permissions`,
+            "PLUGIN_PERMISSIONS_REQUIRED",
+            10,
+            "Ask the plugin author to publish an explicit permission list before approving it."
+          );
+        }
+        if (!trusted) validatePermissions(manifestInfo.manifest.permissions ?? []);
+        const mod = await import(resolvedSpecifier);
         const plugin = resolvePlugin(mod);
         if (plugin) {
-          plugins.push(plugin);
-          seen.add(name);
+          const manifest = trusted ? {
+            name: manifestInfo.manifest.name,
+            version: manifestInfo.manifest.version,
+            trusted: true
+          } : manifestInfo.manifest;
+          const entry = {
+            plugin,
+            manifest,
+            legacyPermissions: manifestInfo?.legacyPermissions ?? false
+          };
+          discoveredPluginManifests.set(plugin, entry.manifest);
+          plugins.push(entry);
+          seen.add(resolvedSpecifier);
+        }
+      } catch (error) {
+        if (error instanceof GpcError && error.code.startsWith("PLUGIN_")) {
+          console.warn(`[gpc] Skipping plugin "${name}": ${error.message}`);
         }
-      } catch {
       }
     }
   }
   return plugins;
 }
+async function discoverPlugins(options) {
+  const compatibilityOptions = options?.legacyApprovedPlugins === void 0 ? { ...options, legacyApprovedPlugins: options?.approvedPlugins } : options;
+  const entries = await discoverPluginEntries(compatibilityOptions);
+  return entries.map(({ plugin }) => plugin);
+}
+async function validatePluginForApproval(specifier, cwd) {
+  const resolvedSpecifier = resolvePluginApprovalId(specifier, cwd);
+  const manifestInfo = await readPluginManifest(resolvedSpecifier);
+  if (manifestInfo.legacyPermissions) {
+    throw new GpcError(
+      `Third-party plugin "${manifestInfo.manifest.name}" must declare permissions in package.json under gpc.permissions`,
+      "PLUGIN_PERMISSIONS_REQUIRED",
+      10,
+      "Ask the plugin author to publish an explicit permission list before approving it."
+    );
+  }
+  validatePermissions(manifestInfo.manifest.permissions ?? []);
+  return { specifier: resolvedSpecifier, manifest: manifestInfo.manifest };
+}
+async function readPluginManifest(specifier, resolveSpecifier) {
+  const { packageJson, adjacent } = await findPackageJson(specifier, resolveSpecifier);
+  const gpc = packageJson?.["gpc"] && typeof packageJson["gpc"] === "object" ? packageJson["gpc"] : void 0;
+  const permissionDeclaration = gpc?.["permissions"];
+  const declaresPluginMetadata = permissionDeclaration !== void 0;
+  const identifyByPath = specifier.startsWith("file:") && !declaresPluginMetadata && !adjacent;
+  const packageName = !identifyByPath && typeof packageJson?.["name"] === "string" ? packageJson["name"] : specifier;
+  const packageVersion = !identifyByPath && typeof packageJson?.["version"] === "string" ? packageJson["version"] : "unknown";
+  if (permissionDeclaration !== void 0 && !Array.isArray(permissionDeclaration)) {
+    throw new GpcError(
+      `Plugin "${packageName}" must declare gpc.permissions as an array`,
+      "PLUGIN_INVALID_PERMISSION",
+      10,
+      "Declare permissions as a JSON array of supported permission names."
+    );
+  }
+  const permissions = permissionDeclaration;
+  return {
+    manifest: {
+      name: packageName,
+      version: packageVersion,
+      permissions: permissions ?? [...LEGACY_PLUGIN_PERMISSIONS],
+      trusted: false
+    },
+    legacyPermissions: permissions === void 0,
+    packageFound: packageJson !== void 0
+  };
+}
+async function findPackageJson(specifier, resolveSpecifier = import.meta.resolve) {
+  let resolved;
+  try {
+    resolved = resolveSpecifier(specifier);
+  } catch {
+    return { adjacent: false };
+  }
+  if (!resolved.startsWith("file:")) return { adjacent: false };
+  const moduleDirectory = dirname(fileURLToPath(resolved));
+  let directory = moduleDirectory;
+  const root = parse(directory).root;
+  while (directory !== root) {
+    let contents;
+    try {
+      contents = await readFile(join(directory, "package.json"), "utf8");
+    } catch (error) {
+      if (error.code !== "ENOENT") return { adjacent: false };
+      directory = dirname(directory);
+      continue;
+    }
+    try {
+      return {
+        packageJson: JSON.parse(contents),
+        adjacent: directory === moduleDirectory
+      };
+    } catch {
+      return { adjacent: false };
+    }
+  }
+  return { adjacent: false };
+}
 function resolvePlugin(mod) {
   if (!mod || typeof mod !== "object") return void 0;
   const m = mod;
@@ -820,8 +970,8 @@ async function validateImage(filePath, imageType) {
 }
 
 // src/utils/fastlane.ts
-import { readFile, writeFile, mkdir, readdir, stat as stat2 } from "fs/promises";
-import { join } from "path";
+import { readFile as readFile2, writeFile, mkdir, readdir, stat as stat2 } from "fs/promises";
+import { join as join2 } from "path";
 var FILE_MAP = {
   "title.txt": "title",
   "short_description.txt": "shortDescription",
@@ -846,7 +996,7 @@ async function readListingsFromDir(dir) {
   const SAFE_LANG2 = /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/;
   for (const lang of entries) {
     if (!SAFE_LANG2.test(lang)) continue;
-    const langDir = join(dir, lang);
+    const langDir = join2(dir, lang);
     const langStat = await stat2(langDir);
     if (!langStat.isDirectory()) continue;
     const listing = {
@@ -856,9 +1006,9 @@ async function readListingsFromDir(dir) {
       fullDescription: ""
     };
     for (const [fileName, field] of Object.entries(FILE_MAP)) {
-      const filePath = join(langDir, fileName);
+      const filePath = join2(langDir, fileName);
       if (await exists(filePath)) {
-        const content = await readFile(filePath, "utf-8");
+        const content = await readFile2(filePath, "utf-8");
         listing[field] = content.trimEnd();
       }
     }
@@ -868,12 +1018,12 @@ async function readListingsFromDir(dir) {
 }
 async function writeListingsToDir(dir, listings) {
   for (const listing of listings) {
-    const langDir = join(dir, listing.language);
+    const langDir = join2(dir, listing.language);
     await mkdir(langDir, { recursive: true });
     for (const [field, fileName] of Object.entries(FIELD_TO_FILE)) {
       const value = listing[field];
       if (value !== void 0 && value !== "") {
-        await writeFile(join(langDir, fileName), value + "\n", "utf-8");
+        await writeFile(join2(langDir, fileName), value + "\n", "utf-8");
       }
     }
   }
@@ -1248,7 +1398,7 @@ var ALL_IMAGE_TYPES = [
 ];
 async function exportImages(client, packageName, dir, options) {
   const { mkdir: mkdir9, writeFile: writeFile10 } = await import("fs/promises");
-  const { join: join13 } = await import("path");
+  const { join: join14 } = await import("path");
   const edit = await client.edits.insert(packageName);
   try {
     let languages;
@@ -1279,7 +1429,7 @@ async function exportImages(client, packageName, dir, options) {
       const batch = tasks.slice(i, i + concurrency);
       const results = await Promise.all(
         batch.map(async (task) => {
-          const dirPath = join13(dir, task.language, task.imageType);
+          const dirPath = join14(dir, task.language, task.imageType);
           await mkdir9(dirPath, { recursive: true });
           const response = await fetch(task.url);
           if (!response.ok) {
@@ -1291,7 +1441,7 @@ async function exportImages(client, packageName, dir, options) {
             );
           }
           const buffer = Buffer.from(await response.arrayBuffer());
-          const filePath = join13(dirPath, `${task.index}.png`);
+          const filePath = join14(dirPath, `${task.index}.png`);
           await writeFile10(filePath, buffer);
           return buffer.length;
         })
@@ -1327,8 +1477,8 @@ async function updateAppDetails(client, packageName, details, commitOptions) {
 }
 
 // src/commands/migrate.ts
-import { readdir as readdir2, readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2, access } from "fs/promises";
-import { join as join2 } from "path";
+import { readdir as readdir2, readFile as readFile3, writeFile as writeFile2, mkdir as mkdir2, access } from "fs/promises";
+import { join as join3 } from "path";
 var COMPLEX_RUBY_RE = /\b(begin|rescue|ensure|if |unless |case |while |until |for )\b/;
 async function fileExists(path) {
   try {
@@ -1348,14 +1498,14 @@ async function detectFastlane(cwd) {
     metadataLanguages: [],
     parseWarnings: []
   };
-  const fastlaneDir = join2(cwd, "fastlane");
+  const fastlaneDir = join3(cwd, "fastlane");
   const hasFastlaneDir = await fileExists(fastlaneDir);
-  const fastfilePath = hasFastlaneDir ? join2(fastlaneDir, "Fastfile") : join2(cwd, "Fastfile");
-  const appfilePath = hasFastlaneDir ? join2(fastlaneDir, "Appfile") : join2(cwd, "Appfile");
+  const fastfilePath = hasFastlaneDir ? join3(fastlaneDir, "Fastfile") : join3(cwd, "Fastfile");
+  const appfilePath = hasFastlaneDir ? join3(fastlaneDir, "Appfile") : join3(cwd, "Appfile");
   result.hasFastfile = await fileExists(fastfilePath);
   result.hasAppfile = await fileExists(appfilePath);
-  result.hasGemfile = await fileExists(join2(cwd, "Gemfile"));
-  const metadataDir = hasFastlaneDir ? join2(fastlaneDir, "metadata", "android") : join2(cwd, "metadata", "android");
+  result.hasGemfile = await fileExists(join3(cwd, "Gemfile"));
+  const metadataDir = hasFastlaneDir ? join3(fastlaneDir, "metadata", "android") : join3(cwd, "metadata", "android");
   result.hasMetadata = await fileExists(metadataDir);
   if (result.hasMetadata) {
     try {
@@ -1367,7 +1517,7 @@ async function detectFastlane(cwd) {
   }
   if (result.hasFastfile) {
     try {
-      const content = await readFile2(fastfilePath, "utf-8");
+      const content = await readFile3(fastfilePath, "utf-8");
       result.lanes = parseFastfile(content);
       if (COMPLEX_RUBY_RE.test(content)) {
         result.parseWarnings.push(
@@ -1380,7 +1530,7 @@ async function detectFastlane(cwd) {
   }
   if (result.hasAppfile) {
     try {
-      const content = await readFile2(appfilePath, "utf-8");
+      const content = await readFile3(appfilePath, "utf-8");
       const parsed = parseAppfile(content);
       result.packageName = parsed.packageName;
       result.jsonKeyPath = parsed.jsonKeyPath;
@@ -1500,11 +1650,11 @@ async function writeMigrationOutput(result, dir) {
   await mkdir2(dir, { recursive: true });
   const files = [];
   if (Object.keys(result.config).length > 0) {
-    const configPath = join2(dir, ".gpcrc.json");
+    const configPath = join3(dir, ".gpcrc.json");
     await writeFile2(configPath, JSON.stringify(result.config, null, 2) + "\n", "utf-8");
     files.push(configPath);
   }
-  const migrationPath = join2(dir, "MIGRATION.md");
+  const migrationPath = join3(dir, "MIGRATION.md");
   const lines = [
     "# Fastlane to GPC Migration",
     "",
@@ -2796,17 +2946,17 @@ function watchVitalsWithAutoHalt(reporting, packageName, options) {
 }
 
 // src/commands/status.ts
-import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
+import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
 import { execFile } from "child_process";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 import { getCacheDir } from "@gpc-cli/config";
 var DEFAULT_TTL_SECONDS = 3600;
 function cacheFilePath(packageName) {
-  return join3(getCacheDir(), `status-${packageName}.json`);
+  return join4(getCacheDir(), `status-${packageName}.json`);
 }
 async function loadStatusCache(packageName, ttlSeconds = DEFAULT_TTL_SECONDS) {
   try {
-    const raw = await readFile3(cacheFilePath(packageName), "utf-8");
+    const raw = await readFile4(cacheFilePath(packageName), "utf-8");
     const entry = JSON.parse(raw);
     const age = (Date.now() - new Date(entry.fetchedAt).getTime()) / 1e3;
     if (age > (entry.ttl ?? ttlSeconds)) return null;
@@ -3265,13 +3415,13 @@ async function runWatchLoop(opts) {
   }
 }
 function breachStateFilePath(packageName) {
-  return join3(getCacheDir(), `breach-state-${packageName}.json`);
+  return join4(getCacheDir(), `breach-state-${packageName}.json`);
 }
 async function trackBreachState(packageName, isBreaching) {
   const filePath = breachStateFilePath(packageName);
   let prevBreaching = false;
   try {
-    const raw = await readFile3(filePath, "utf-8");
+    const raw = await readFile4(filePath, "utf-8");
     prevBreaching = JSON.parse(raw).breaching;
   } catch {
   }
@@ -3548,8 +3698,8 @@ async function runWatch(client, reporting, config, callbacks) {
 }
 
 // src/commands/iap.ts
-import { readdir as readdir3, readFile as readFile4 } from "fs/promises";
-import { join as join4 } from "path";
+import { readdir as readdir3, readFile as readFile5 } from "fs/promises";
+import { join as join5 } from "path";
 import { paginateAll as paginateAll3 } from "@gpc-cli/api";
 async function listInAppProducts(client, packageName, options) {
   if (options?.limit || options?.nextPage) {
@@ -3638,7 +3788,7 @@ async function readProductsFromDir(dir) {
   const jsonFiles = files.filter((f) => f.endsWith(".json"));
   const localProducts = [];
   for (const file of jsonFiles) {
-    const content = await readFile4(join4(dir, file), "utf-8");
+    const content = await readFile5(join5(dir, file), "utf-8");
     try {
       localProducts.push(JSON.parse(content));
     } catch {
@@ -3843,6 +3993,255 @@ async function convertRegionPrices(client, packageName, currencyCode, amount) {
   });
 }
 
+// src/reports/errors.ts
+function reportAccessDeniedError(bucket) {
+  return new GpcError(
+    `Access denied reading the Play reports bucket "${bucket}".`,
+    "REPORT_ACCESS_DENIED",
+    4,
+    "Grant the service account access: Play Console -> Users & permissions -> the service account -> Account permissions -> enable 'View app information and download bulk reports (read-only)', then wait a few minutes for it to propagate."
+  );
+}
+function reportAuthRejectedError(bucket) {
+  return new GpcError(
+    `Authentication was rejected reading the Play reports bucket "${bucket}".`,
+    "REPORT_AUTH_REJECTED",
+    3,
+    "The access token was not accepted. Check the service account key is valid (gpc auth status) and that your system clock is accurate, then retry."
+  );
+}
+function reportBucketNotFoundError(bucket) {
+  return new GpcError(
+    `Play reports bucket "${bucket}" was not found.`,
+    "REPORT_BUCKET_NOT_FOUND",
+    4,
+    "Confirm the bucket name. Copy the exact Cloud Storage URI from Play Console -> Download reports, then set it with --bucket or the 'reports.bucket' config key. The default is pubsite_prod_<developerId>."
+  );
+}
+function reportObjectNotFoundError(opts) {
+  const { reportType, month, dimension, available } = opts;
+  const dimPart = dimension ? ` dimension "${dimension}"` : "";
+  const availPart = available && available.length ? ` Available: ${available.join(", ")}.` : " No matching report objects were found for that month.";
+  return new GpcError(
+    `No "${reportType}" report found for ${month}${dimPart}.`,
+    "REPORT_OBJECT_NOT_FOUND",
+    4,
+    `Check the month is complete and the report type/dimension exist.${availPart} Reports for the current month may not be published until it ends.`
+  );
+}
+
+// src/reports/gcs.ts
+var GCS_API_BASE = "https://storage.googleapis.com/storage/v1/b";
+var LIST_TIMEOUT_MS = 6e4;
+var DOWNLOAD_TIMEOUT_MS = 12e4;
+function networkError(bucket, cause) {
+  const detail = cause instanceof Error ? cause.message : String(cause);
+  return new GpcError(
+    `Network error reading the Play reports bucket "${bucket}": ${detail}`,
+    "NETWORK_ERROR",
+    5,
+    "Check your internet connection and retry. Google Cloud Storage may also be briefly unavailable."
+  );
+}
+function maxRetries() {
+  const parsed = Number(process.env["GPC_MAX_RETRIES"]);
+  return Number.isInteger(parsed) && parsed >= 0 && parsed <= 10 ? parsed : 3;
+}
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+async function gcsFetch(auth, bucket, url, timeoutMs) {
+  const retries = maxRetries();
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (attempt > 0) {
+      await new Promise((r) => setTimeout(r, Math.min(1e3 * 2 ** (attempt - 1), 8e3)));
+    }
+    const token = await auth.getAccessToken();
+    let res;
+    try {
+      res = await fetch(url, {
+        headers: { authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+    } catch (err) {
+      lastError = err;
+      continue;
+    }
+    if (RETRYABLE_STATUSES.has(res.status) && attempt < retries) {
+      continue;
+    }
+    if (res.status === 401) {
+      throw reportAuthRejectedError(bucket);
+    }
+    if (res.status === 403) {
+      throw reportAccessDeniedError(bucket);
+    }
+    return res;
+  }
+  throw networkError(bucket, lastError ?? new Error("retries exhausted"));
+}
+async function listReportObjects(auth, bucket, options) {
+  const params = new URLSearchParams({ prefix: options.prefix });
+  if (options.maxResults) params.set("maxResults", String(options.maxResults));
+  if (options.pageToken) params.set("pageToken", options.pageToken);
+  const url = `${GCS_API_BASE}/${encodeURIComponent(bucket)}/o?${params.toString()}`;
+  const res = await gcsFetch(auth, bucket, url, LIST_TIMEOUT_MS);
+  if (res.status === 404) {
+    throw reportBucketNotFoundError(bucket);
+  }
+  if (!res.ok) {
+    throw new GpcError(
+      `Google Cloud Storage returned HTTP ${res.status} listing the reports bucket "${bucket}".`,
+      "REPORT_LIST_FAILED",
+      4,
+      "Retry in a moment. If the error persists, verify the bucket name and the service account's report access."
+    );
+  }
+  let body;
+  try {
+    body = await res.json();
+  } catch (err) {
+    throw networkError(bucket, err);
+  }
+  const objects = (body.items ?? []).filter((item) => typeof item.name === "string").map((item) => ({
+    name: item.name,
+    size: Number(item.size ?? 0),
+    updated: item.updated
+  }));
+  return { objects, nextPageToken: body.nextPageToken };
+}
+async function downloadReportObject(auth, bucket, objectName) {
+  const url = `${GCS_API_BASE}/${encodeURIComponent(bucket)}/o/${encodeURIComponent(objectName)}?alt=media`;
+  const res = await gcsFetch(auth, bucket, url, DOWNLOAD_TIMEOUT_MS);
+  if (res.status === 404) {
+    throw new GpcError(
+      `Report object "${objectName}" was not found in bucket "${bucket}".`,
+      "REPORT_OBJECT_NOT_FOUND",
+      4,
+      "List available reports first: gpc reports list <report-type> --month <YYYY-MM>"
+    );
+  }
+  if (!res.ok) {
+    throw new GpcError(
+      `Google Cloud Storage returned HTTP ${res.status} downloading "${objectName}".`,
+      "REPORT_DOWNLOAD_FAILED",
+      4,
+      "Retry in a moment. If the error persists, list the reports to confirm the object still exists."
+    );
+  }
+  try {
+    return Buffer.from(await res.arrayBuffer());
+  } catch (err) {
+    throw networkError(bucket, err);
+  }
+}
+
+// src/reports/decode.ts
+import { gunzipSync } from "zlib";
+import { fromBuffer } from "yauzl";
+var GZIP_MAGIC = [31, 139];
+var ZIP_MAGIC = [80, 75];
+function isGzip(buf) {
+  return buf.length >= 2 && buf[0] === GZIP_MAGIC[0] && buf[1] === GZIP_MAGIC[1];
+}
+function isZip(buf) {
+  return buf.length >= 2 && buf[0] === ZIP_MAGIC[0] && buf[1] === ZIP_MAGIC[1];
+}
+var MAX_INFLATED_BYTES = 512 * 1024 * 1024;
+function gunzipIfNeeded(buf) {
+  return isGzip(buf) ? gunzipSync(buf, { maxOutputLength: MAX_INFLATED_BYTES }) : buf;
+}
+function decodeCsvText(buf) {
+  if (buf.length >= 2 && buf[0] === 255 && buf[1] === 254) {
+    return buf.subarray(2).toString("utf16le");
+  }
+  if (buf.length >= 2 && buf[0] === 254 && buf[1] === 255) {
+    const swapped = Buffer.from(buf.subarray(2));
+    swapped.swap16();
+    return swapped.toString("utf16le");
+  }
+  if (buf.length >= 3 && buf[0] === 239 && buf[1] === 187 && buf[2] === 191) {
+    return buf.subarray(3).toString("utf8");
+  }
+  return buf.toString("utf8");
+}
+function decodeStatsCsv(buf) {
+  return decodeCsvText(gunzipIfNeeded(buf));
+}
+var ZIP_READ_TIMEOUT_MS = 3e4;
+function extractCsvEntriesFromZip(buffer) {
+  return new Promise((resolve2, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      settleReject(new Error("Timed out reading report archive"));
+    }, ZIP_READ_TIMEOUT_MS);
+    timer.unref?.();
+    function settleResolve(v) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve2(v);
+    }
+    function settleReject(e) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(e);
+    }
+    try {
+      fromBuffer(buffer, { lazyEntries: true }, (err, openedZip) => {
+        if (err || !openedZip) {
+          settleReject(err ?? new Error("Failed to open report archive"));
+          return;
+        }
+        const zipfile = openedZip;
+        const entries = [];
+        let pending = 0;
+        let entriesDone = false;
+        function fail(e) {
+          try {
+            zipfile.close();
+          } catch {
+          }
+          settleReject(e);
+        }
+        function maybeResolve() {
+          if (!settled && entriesDone && pending === 0) settleResolve(entries);
+        }
+        zipfile.on("entry", (entry) => {
+          if (/\/$/.test(entry.fileName) || !/\.csv$/i.test(entry.fileName)) {
+            zipfile.readEntry();
+            return;
+          }
+          pending++;
+          zipfile.openReadStream(entry, (streamErr, stream) => {
+            if (streamErr || !stream) {
+              fail(streamErr ?? new Error(`Failed to read ${entry.fileName}`));
+              return;
+            }
+            const chunks = [];
+            stream.on("data", (c) => chunks.push(c));
+            stream.on("error", fail);
+            stream.on("end", () => {
+              entries.push({ name: entry.fileName, text: decodeStatsCsv(Buffer.concat(chunks)) });
+              pending--;
+              zipfile.readEntry();
+              maybeResolve();
+            });
+          });
+        });
+        zipfile.on("end", () => {
+          entriesDone = true;
+          maybeResolve();
+        });
+        zipfile.on("error", fail);
+        zipfile.readEntry();
+      });
+    } catch (e) {
+      settleReject(e instanceof Error ? e : new Error(String(e)));
+    }
+  });
+}
+
 // src/commands/reports.ts
 var FINANCIAL_REPORT_TYPES = /* @__PURE__ */ new Set([
   "earnings",
@@ -3865,6 +4264,7 @@ var VALID_DIMENSIONS = /* @__PURE__ */ new Set([
   "device",
   "app_version",
   "carrier",
+  "traffic_source",
   "overview"
 ]);
 function isFinancialReportType(type) {
@@ -3901,22 +4301,131 @@ function parseMonth(monthStr) {
   }
   return { year, month };
 }
-async function listReports(_client, _packageName, reportType, _year, _month) {
-  throw new GpcError(
-    `Report listing for "${reportType}" is not available through the Google Play Developer API.`,
-    "REPORT_NOT_SUPPORTED",
-    1,
-    isFinancialReportType(reportType) ? "Financial reports are delivered via Google Cloud Storage. Access them from Play Console \u2192 Download reports \u2192 Financial." : "Stats reports are delivered via Google Cloud Storage. For real-time metrics, use 'gpc vitals' commands."
-  );
+function monthToken(parsed) {
+  return `${parsed.year}${String(parsed.month).padStart(2, "0")}`;
 }
-async function downloadReport(_client, _packageName, reportType, _year, _month) {
+function nameHasMonth(name, token) {
+  return new RegExp(`(?<![0-9])${token}(?![0-9])`).test(name);
+}
+function resolveReportsBucket(config) {
+  const explicit = config.reports?.bucket?.trim();
+  if (explicit) {
+    const reduced = explicit.replace(/^gs:\/\//, "").replace(/\/.*$/, "");
+    if (!/^[a-z0-9][a-z0-9._-]{1,221}$/.test(reduced)) {
+      throw new GpcError(
+        `Invalid reports bucket name "${reduced}".`,
+        "REPORT_BUCKET_INVALID",
+        2,
+        "Copy the exact Cloud Storage URI from Play Console -> Download reports. The bucket name looks like pubsite_prod_<developerId>."
+      );
+    }
+    return reduced;
+  }
+  if (config.developerId) {
+    return `pubsite_prod_${config.developerId}`;
+  }
   throw new GpcError(
-    `Report download for "${reportType}" is not available through the Google Play Developer API.`,
-    "REPORT_NOT_SUPPORTED",
-    1,
-    isFinancialReportType(reportType) ? "Financial reports are delivered via Google Cloud Storage. Access them from Play Console \u2192 Download reports \u2192 Financial." : "Stats reports are delivered via Google Cloud Storage. For real-time metrics, use 'gpc vitals' commands."
+    "Cannot determine the Play reports bucket: no bucket configured and no developer id set.",
+    "REPORT_BUCKET_UNKNOWN",
+    2,
+    "Set your developer id (gpc config set developerId <id> or GPC_DEVELOPER_ID) so the default pubsite_prod_<developerId> bucket can be derived, or pass the bucket directly with --bucket / GPC_REPORTS_BUCKET / the reports.bucket config key. The exact URI is shown in Play Console -> Download reports."
   );
 }
+function reportPrefix(reportType, packageName) {
+  switch (reportType) {
+    case "earnings":
+      return "earnings/";
+    case "sales":
+    case "estimated_sales":
+      return "sales/";
+    case "play_balance":
+      return "play_balance/";
+    case "reviews":
+      return packageName ? `reviews/reviews_${packageName}_` : "reviews/";
+    case "subscriptions":
+      return packageName ? `financial-stats/subscriptions/subscriptions_${packageName}_` : "financial-stats/subscriptions/";
+    default:
+      return packageName ? `stats/${reportType}/${reportType}_${packageName}_` : `stats/${reportType}/`;
+  }
+}
+async function listReports(auth, bucket, reportType, options = {}) {
+  const packageName = isStatsReportType(reportType) ? options.packageName : void 0;
+  const basePrefix = reportPrefix(reportType, packageName);
+  const serverSideMonth = Boolean(packageName && options.month);
+  const prefix = serverSideMonth ? `${basePrefix}${monthToken(options.month)}` : basePrefix;
+  const { objects, nextPageToken } = await listReportObjects(auth, bucket, {
+    prefix,
+    maxResults: options.maxResults,
+    pageToken: options.pageToken
+  });
+  const reports = options.month && !serverSideMonth ? objects.filter((o) => nameHasMonth(o.name, monthToken(options.month))) : objects;
+  return { reports, nextPageToken };
+}
+async function downloadStatsReport(auth, bucket, packageName, reportType, month, dimension) {
+  const token = monthToken(month);
+  const prefix = `${reportPrefix(reportType, packageName)}${token}`;
+  const { objects } = await listReportObjects(auth, bucket, { prefix });
+  const wanted = reportType === "reviews" ? objects.find((o) => o.name.endsWith(`${token}.csv`)) : objects.find((o) => o.name.endsWith(`${token}_${dimension}.csv`));
+  if (!wanted) {
+    const available = objects.map((o) => new RegExp(`(?<![0-9])${token}_([a-z_]+)\\.csv$`).exec(o.name)?.[1]).filter((d) => Boolean(d));
+    throw reportObjectNotFoundError({
+      reportType,
+      month: `${month.year}-${String(month.month).padStart(2, "0")}`,
+      dimension: reportType === "reviews" ? void 0 : dimension,
+      available: [...new Set(available)]
+    });
+  }
+  const bytes = await downloadReportObject(auth, bucket, wanted.name);
+  try {
+    return { objectName: wanted.name, csv: decodeStatsCsv(bytes) };
+  } catch (err) {
+    throw new GpcError(
+      `Could not decode the report "${wanted.name}": ${err instanceof Error ? err.message : String(err)}`,
+      "REPORT_DECODE_FAILED",
+      4,
+      "Re-download in case the transfer was corrupted. If the error persists, the object may be malformed; download it from Play Console -> Download reports to compare."
+    );
+  }
+}
+async function downloadFinancialReport(auth, bucket, reportType, month, options = {}) {
+  const token = monthToken(month);
+  const { objects } = await listReportObjects(auth, bucket, {
+    prefix: reportPrefix(reportType)
+  });
+  const matches = objects.filter((o) => nameHasMonth(o.name, token));
+  if (matches.length === 0) {
+    const availableMonths = [
+      ...new Set(
+        objects.map((o) => /(?<![0-9])(\d{4})(\d{2})(?![0-9])/.exec(o.name)).filter((m) => m !== null).map((m) => `${m[1]}-${m[2]}`)
+      )
+    ].slice(-6);
+    throw reportObjectNotFoundError({
+      reportType,
+      month: `${month.year}-${String(month.month).padStart(2, "0")}`,
+      available: availableMonths
+    });
+  }
+  const chosen = matches[matches.length - 1];
+  const bytes = await downloadReportObject(auth, bucket, chosen.name);
+  if (isZip(bytes)) {
+    if (options.extractEntries === false) {
+      return { objectName: chosen.name, kind: "zip", entries: [], raw: bytes };
+    }
+    let entries;
+    try {
+      entries = await extractCsvEntriesFromZip(bytes);
+    } catch (err) {
+      throw new GpcError(
+        `Could not read the report archive "${chosen.name}": ${err instanceof Error ? err.message : String(err)}`,
+        "REPORT_ARCHIVE_UNREADABLE",
+        4,
+        "Save the raw archive instead (--output-file report.zip) and open it locally, or re-download in case the transfer was corrupted."
+      );
+    }
+    return { objectName: chosen.name, kind: "zip", entries, raw: bytes };
+  }
+  return { objectName: chosen.name, kind: "csv", text: decodeStatsCsv(bytes) };
+}
 
 // src/commands/users.ts
 import { paginateAll as paginateAll5 } from "@gpc-cli/api";
@@ -4017,7 +4526,7 @@ async function deleteGrant(client, developerId, email, packageName) {
 }
 
 // src/commands/testers.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile6 } from "fs/promises";
 async function listTesters(client, packageName, track) {
   const edit = await client.edits.insert(packageName);
   try {
@@ -4064,7 +4573,7 @@ async function removeTesters(client, packageName, track, groupEmails, commitOpti
   }
 }
 async function importTestersFromCsv(client, packageName, track, csvPath, commitOptions) {
-  const content = await readFile5(csvPath, "utf-8");
+  const content = await readFile6(csvPath, "utf-8");
   const emails = content.split(/[,\n\r]+/).map((e) => e.trim()).filter((e) => e.length > 0 && e.includes("@"));
   if (emails.length === 0) {
     throw new GpcError(
@@ -4207,7 +4716,7 @@ async function addRecoveryTargeting(client, packageName, actionId, targeting) {
 }
 
 // src/commands/data-safety.ts
-import { readFile as readFile6, stat as stat4 } from "fs/promises";
+import { readFile as readFile7, stat as stat4 } from "fs/promises";
 var MAX_CSV_BYTES = 1 * 1024 * 1024;
 async function updateDataSafety(client, packageName, data) {
   return client.dataSafety.update(packageName, data);
@@ -4240,7 +4749,7 @@ async function importDataSafety(client, packageName, filePath) {
       "The CSV should be a few KB. Check that you are passing the correct file."
     );
   }
-  const csvContent = await readFile6(filePath, "utf-8");
+  const csvContent = await readFile7(filePath, "utf-8");
   return updateDataSafety(client, packageName, { safetyLabels: csvContent });
 }
 
@@ -4540,16 +5049,16 @@ function createSpinner(message) {
 }
 
 // src/utils/train-state.ts
-import { mkdir as mkdir4, readFile as readFile7, writeFile as writeFile4 } from "fs/promises";
-import { dirname, join as join5 } from "path";
+import { mkdir as mkdir4, readFile as readFile8, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname2, join as join6 } from "path";
 import { getCacheDir as getCacheDir2 } from "@gpc-cli/config";
 function stateFile(packageName) {
-  return join5(getCacheDir2(), `train-${packageName}.json`);
+  return join6(getCacheDir2(), `train-${packageName}.json`);
 }
 async function readTrainState(packageName) {
   const path = stateFile(packageName);
   try {
-    const raw = await readFile7(path, "utf-8");
+    const raw = await readFile8(path, "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -4557,7 +5066,7 @@ async function readTrainState(packageName) {
 }
 async function writeTrainState(packageName, state) {
   const path = stateFile(packageName);
-  const dir = dirname(path);
+  const dir = dirname2(path);
   await mkdir4(dir, { recursive: true });
   await writeFile4(path, JSON.stringify(state, null, 2), "utf-8");
 }
@@ -4703,8 +5212,8 @@ async function executeStage(apiClient, packageName, state, stageIndex) {
 }
 
 // src/commands/games.ts
-import { mkdir as mkdir5, readdir as readdir4, readFile as readFile8, writeFile as writeFile5 } from "fs/promises";
-import { extname as extname2, join as join6 } from "path";
+import { mkdir as mkdir5, readdir as readdir4, readFile as readFile9, writeFile as writeFile5 } from "fs/promises";
+import { extname as extname2, join as join7 } from "path";
 async function listLeaderboards(client, packageName) {
   const result = await client.leaderboards.list(packageName);
   return result.items ?? [];
@@ -4848,7 +5357,7 @@ async function readConfigDir(dir) {
   const entries = (await readdir4(dir)).filter((f) => f.toLowerCase().endsWith(".json"));
   const out = [];
   for (const file of entries) {
-    const raw = await readFile8(join6(dir, file), "utf-8");
+    const raw = await readFile9(join7(dir, file), "utf-8");
     let parsed;
     try {
       parsed = JSON.parse(raw);
@@ -4901,7 +5410,7 @@ async function pullAchievementConfigs(client, applicationId, dir) {
     for (const config of result.items ?? []) {
       const id = config.id ?? "unknown";
       await writeFile5(
-        join6(dir, safeConfigFilename(id)),
+        join7(dir, safeConfigFilename(id)),
         JSON.stringify(config, null, 2) + "\n",
         "utf-8"
       );
@@ -4940,7 +5449,7 @@ async function pullLeaderboardConfigs(client, applicationId, dir) {
     for (const config of result.items ?? []) {
       const id = config.id ?? "unknown";
       await writeFile5(
-        join6(dir, safeConfigFilename(id)),
+        join7(dir, safeConfigFilename(id)),
         JSON.stringify(config, null, 2) + "\n",
         "utf-8"
       );
@@ -4964,8 +5473,8 @@ async function publishEnterpriseApp(client, params) {
 }
 
 // src/audit.ts
-import { appendFile, chmod, mkdir as mkdir6, readFile as readFile9, writeFile as writeFile6 } from "fs/promises";
-import { join as join7 } from "path";
+import { appendFile, chmod, mkdir as mkdir6, readFile as readFile10, writeFile as writeFile6 } from "fs/promises";
+import { join as join8 } from "path";
 var auditDir = null;
 function initAudit(configDir) {
   auditDir = configDir;
@@ -4974,7 +5483,7 @@ async function writeAuditLog(entry) {
   if (!auditDir) return;
   try {
     await mkdir6(auditDir, { recursive: true, mode: 448 });
-    const logPath = join7(auditDir, "audit.log");
+    const logPath = join8(auditDir, "audit.log");
     const redactedEntry = redactAuditArgs(entry);
     const line = JSON.stringify(redactedEntry) + "\n";
     await appendFile(logPath, line, { encoding: "utf-8", mode: 384 });
@@ -5029,10 +5538,10 @@ function createAuditEntry(command, args, app) {
 }
 async function listAuditEvents(options) {
   if (!auditDir) return [];
-  const logPath = join7(auditDir, "audit.log");
+  const logPath = join8(auditDir, "audit.log");
   let content;
   try {
-    content = await readFile9(logPath, "utf-8");
+    content = await readFile10(logPath, "utf-8");
   } catch {
     return [];
   }
@@ -5067,10 +5576,10 @@ async function searchAuditEvents(query) {
 }
 async function clearAuditLog(options) {
   if (!auditDir) return { deleted: 0, remaining: 0 };
-  const logPath = join7(auditDir, "audit.log");
+  const logPath = join8(auditDir, "audit.log");
   let content;
   try {
-    content = await readFile9(logPath, "utf-8");
+    content = await readFile10(logPath, "utf-8");
   } catch {
     return { deleted: 0, remaining: 0 };
   }
@@ -5159,7 +5668,7 @@ function safePathWithin(userPath, baseDir) {
 
 // src/commands/init.ts
 import { mkdir as mkdir7, writeFile as writeFile7, stat as stat5 } from "fs/promises";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 async function exists2(path) {
   try {
     await stat5(path);
@@ -5194,7 +5703,7 @@ async function initProject(options) {
     null,
     2
   );
-  await safeWrite(join8(dir, ".gpcrc.json"), gpcrc + "\n", created, skipped, skipExisting);
+  await safeWrite(join9(dir, ".gpcrc.json"), gpcrc + "\n", created, skipped, skipExisting);
   const preflightrc = JSON.stringify(
     {
       failOn: "error",
@@ -5208,27 +5717,27 @@ async function initProject(options) {
     2
   );
   await safeWrite(
-    join8(dir, ".preflightrc.json"),
+    join9(dir, ".preflightrc.json"),
     preflightrc + "\n",
     created,
     skipped,
     skipExisting
   );
-  const metaDir = join8(dir, "metadata", "android", "en-US");
-  await safeWrite(join8(metaDir, "title.txt"), "", created, skipped, skipExisting);
-  await safeWrite(join8(metaDir, "short_description.txt"), "", created, skipped, skipExisting);
-  await safeWrite(join8(metaDir, "full_description.txt"), "", created, skipped, skipExisting);
-  await safeWrite(join8(metaDir, "video.txt"), "", created, skipped, skipExisting);
-  const ssDir = join8(metaDir, "images", "phoneScreenshots");
+  const metaDir = join9(dir, "metadata", "android", "en-US");
+  await safeWrite(join9(metaDir, "title.txt"), "", created, skipped, skipExisting);
+  await safeWrite(join9(metaDir, "short_description.txt"), "", created, skipped, skipExisting);
+  await safeWrite(join9(metaDir, "full_description.txt"), "", created, skipped, skipExisting);
+  await safeWrite(join9(metaDir, "video.txt"), "", created, skipped, skipExisting);
+  const ssDir = join9(metaDir, "images", "phoneScreenshots");
   await mkdir7(ssDir, { recursive: true });
-  await safeWrite(join8(ssDir, ".gitkeep"), "", created, skipped, skipExisting);
+  await safeWrite(join9(ssDir, ".gitkeep"), "", created, skipped, skipExisting);
   if (ci === "github") {
     const workflow = githubActionsTemplate(pkg);
-    const workflowDir = join8(dir, ".github", "workflows");
-    await safeWrite(join8(workflowDir, "gpc-release.yml"), workflow, created, skipped, skipExisting);
+    const workflowDir = join9(dir, ".github", "workflows");
+    await safeWrite(join9(workflowDir, "gpc-release.yml"), workflow, created, skipped, skipExisting);
   } else if (ci === "gitlab") {
     const pipeline = gitlabCiTemplate(pkg);
-    await safeWrite(join8(dir, ".gitlab-ci-gpc.yml"), pipeline, created, skipped, skipExisting);
+    await safeWrite(join9(dir, ".gitlab-ci-gpc.yml"), pipeline, created, skipped, skipExisting);
   }
   return { created, skipped };
 }
@@ -5324,13 +5833,13 @@ var DEFAULT_PREFLIGHT_CONFIG = {
 };
 
 // src/preflight/config.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 var VALID_SEVERITIES = /* @__PURE__ */ new Set(["critical", "error", "warning", "info"]);
 async function loadPreflightConfig(configPath) {
   const path = configPath || ".preflightrc.json";
   let raw;
   try {
-    raw = await readFile10(path, "utf-8");
+    raw = await readFile11(path, "utf-8");
   } catch {
     return { ...DEFAULT_PREFLIGHT_CONFIG };
   }
@@ -5375,8 +5884,8 @@ async function loadPreflightConfig(configPath) {
 }
 
 // src/preflight/aab-reader.ts
-import { readFile as readFile11 } from "fs/promises";
-import { fromBuffer } from "yauzl";
+import { readFile as readFile12 } from "fs/promises";
+import { fromBuffer as fromBuffer2 } from "yauzl";
 
 // src/preflight/manifest-parser.ts
 import protobuf from "protobufjs";
@@ -5573,7 +6082,7 @@ async function readAab(aabPath) {
   const manifestPath = detectManifestPath(aabPath);
   let buffer;
   try {
-    buffer = await readFile11(aabPath);
+    buffer = await readFile12(aabPath);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     throw new Error(`Could not read ${aabPath}: ${msg}`, { cause: err });
@@ -5637,7 +6146,7 @@ function openAndScan(buffer, manifestPath = AAB_MANIFEST_PATH) {
       reject(error);
     }
     try {
-      fromBuffer(buffer, { lazyEntries: true }, (err, zipfile) => {
+      fromBuffer2(buffer, { lazyEntries: true }, (err, zipfile) => {
         if (err || !zipfile) {
           settleReject(err ?? new Error("Failed to open AAB file"));
           return;
@@ -6297,8 +6806,8 @@ ${fileList}` + (hasPageSizeCompat ? "\nandroid:pageSizeCompat is set, so the app
 }
 
 // src/preflight/scanners/metadata-scanner.ts
-import { readdir as readdir5, stat as stat6, readFile as readFile12 } from "fs/promises";
-import { join as join9 } from "path";
+import { readdir as readdir5, stat as stat6, readFile as readFile13 } from "fs/promises";
+import { join as join10 } from "path";
 var SAFE_LANG = /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/;
 var FILE_MAP2 = {
   "title.txt": "title",
@@ -6349,14 +6858,14 @@ var metadataScanner = {
       return findings;
     }
     for (const lang of locales) {
-      const langDir = join9(dir, lang);
+      const langDir = join10(dir, lang);
       const langStat = await stat6(langDir).catch(() => null);
       if (!langStat?.isDirectory()) continue;
       const fields = {};
       for (const [fileName, field] of Object.entries(FILE_MAP2)) {
-        const filePath = join9(langDir, fileName);
+        const filePath = join10(langDir, fileName);
         try {
-          const content = await readFile12(filePath, "utf-8");
+          const content = await readFile13(filePath, "utf-8");
           fields[field] = content.trimEnd();
         } catch {
         }
@@ -6395,7 +6904,7 @@ var metadataScanner = {
       let totalScreenshots = 0;
       let phoneScreenshots = 0;
       for (const ssDir of SCREENSHOT_DIRS) {
-        const ssPath = join9(langDir, "images", ssDir);
+        const ssPath = join10(langDir, "images", ssDir);
         try {
           const ssEntries = await readdir5(ssPath);
           const imageFiles = ssEntries.filter((f) => /\.(png|jpe?g|webp)$/i.test(f));
@@ -6427,9 +6936,9 @@ var metadataScanner = {
       }
     }
     const defaultLang = locales.includes("en-US") ? "en-US" : locales[0];
-    const privacyPath = join9(dir, defaultLang, "privacy_policy_url.txt");
+    const privacyPath = join10(dir, defaultLang, "privacy_policy_url.txt");
     try {
-      const url = await readFile12(privacyPath, "utf-8");
+      const url = await readFile13(privacyPath, "utf-8");
       if (!url.trim()) throw new Error("empty");
     } catch {
       findings.push({
@@ -6454,11 +6963,11 @@ var metadataScanner = {
 };
 
 // src/preflight/scanners/secrets-scanner.ts
-import { readFile as readFile13 } from "fs/promises";
+import { readFile as readFile14 } from "fs/promises";
 
 // src/preflight/scan-files.ts
 import { readdir as readdir6, stat as stat7 } from "fs/promises";
-import { join as join10, extname as extname3 } from "path";
+import { join as join11, extname as extname3 } from "path";
 var DEFAULT_SKIP_DIRS = /* @__PURE__ */ new Set([
   ".git",
   "node_modules",
@@ -6481,7 +6990,7 @@ async function collectSourceFiles(dir, extensions, skipDirs = DEFAULT_SKIP_DIRS,
   }
   for (const entry of entries) {
     if (skipDirs.has(entry)) continue;
-    const fullPath = join10(dir, entry);
+    const fullPath = join11(dir, entry);
     const s = await stat7(fullPath).catch(() => null);
     if (!s) continue;
     if (s.isDirectory()) {
@@ -6574,7 +7083,7 @@ var secretsScanner = {
     for (const filePath of files) {
       let content;
       try {
-        content = await readFile13(filePath, "utf-8");
+        content = await readFile14(filePath, "utf-8");
       } catch {
         continue;
       }
@@ -6602,7 +7111,7 @@ var secretsScanner = {
 };
 
 // src/preflight/scanners/billing-scanner.ts
-import { readFile as readFile14 } from "fs/promises";
+import { readFile as readFile15 } from "fs/promises";
 var BILLING_PATTERNS = [
   {
     ruleId: "billing-stripe-sdk",
@@ -6663,7 +7172,7 @@ var billingScanner = {
     for (const filePath of files) {
       let content;
       try {
-        content = await readFile14(filePath, "utf-8");
+        content = await readFile15(filePath, "utf-8");
       } catch {
         continue;
       }
@@ -6689,7 +7198,7 @@ var billingScanner = {
 };
 
 // src/preflight/scanners/privacy-scanner.ts
-import { readFile as readFile15 } from "fs/promises";
+import { readFile as readFile16 } from "fs/promises";
 var TRACKING_SDKS = [
   {
     name: "Facebook SDK",
@@ -6729,7 +7238,7 @@ var privacyScanner = {
     for (const filePath of files) {
       let content;
       try {
-        content = await readFile15(filePath, "utf-8");
+        content = await readFile16(filePath, "utf-8");
       } catch {
         continue;
       }
@@ -6879,6 +7388,19 @@ var policyScanner = {
       suggestion: "Run `gpc verify checklist` to review readiness, including registration of every app on your account. This is a distribution-market and account-registration reminder, not an AAB/APK defect.",
       policyUrl: "https://developer.android.com/developer-verification"
     });
+    const foregroundServicePerms = manifest.permissions.filter((p) => p.startsWith("android.permission.FOREGROUND_SERVICE")).sort();
+    if (foregroundServicePerms.length > 0) {
+      const shortNames = foregroundServicePerms.map((p) => p.replace("android.permission.", ""));
+      findings.push({
+        scanner: "policy",
+        ruleId: "policy-app-content-declaration",
+        severity: "info",
+        title: "Foreground service permissions require an App content declaration",
+        message: `This app requests ${shortNames.join(", ")}. Google Play requires a completed "Foreground service permissions" declaration under App content before it will accept a release. The declaration is stored in Play Console, so it cannot be verified from the AAB.`,
+        suggestion: "Complete Play Console \u2192 your app \u2192 Policy \u2192 App content \u2192 Foreground service permissions before releasing. If it is incomplete, the Play API rejects the upload with a 403 whose wording resembles a service account permission error; GPC reports that as API_DECLARATION_REQUIRED.",
+        policyUrl: "https://support.google.com/googleplay/android-developer/answer/13392821"
+      });
+    }
     if (perms.has("android.permission.SYSTEM_ALERT_WINDOW")) {
       findings.push({
         scanner: "policy",
@@ -7091,13 +7613,13 @@ async function runPreflight(options) {
 
 // src/commands/plugin-scaffold.ts
 import { mkdir as mkdir8, writeFile as writeFile8 } from "fs/promises";
-import { join as join11 } from "path";
+import { join as join12 } from "path";
 async function scaffoldPlugin(options) {
   const { name, dir, description = `GPC plugin: ${name}` } = options;
   const pluginName = name.startsWith("gpc-plugin-") ? name : `gpc-plugin-${name}`;
   const shortName = pluginName.replace(/^gpc-plugin-/, "");
-  const srcDir = join11(dir, "src");
-  const testDir = join11(dir, "tests");
+  const srcDir = join12(dir, "src");
+  const testDir = join12(dir, "tests");
   await mkdir8(srcDir, { recursive: true });
   await mkdir8(testDir, { recursive: true });
   const files = [];
@@ -7115,6 +7637,9 @@ async function scaffoldPlugin(options) {
       }
     },
     files: ["dist"],
+    gpc: {
+      permissions: ["hooks:beforeCommand", "hooks:afterCommand"]
+    },
     scripts: {
       build: "tsup src/index.ts --format esm --dts",
       dev: "tsup src/index.ts --format esm --dts --watch",
@@ -7133,7 +7658,7 @@ async function scaffoldPlugin(options) {
       vitest: "^3.0.0"
     }
   };
-  await writeFile8(join11(dir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+  await writeFile8(join12(dir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
   files.push("package.json");
   const tsconfig = {
     compilerOptions: {
@@ -7149,7 +7674,7 @@ async function scaffoldPlugin(options) {
     },
     include: ["src"]
   };
-  await writeFile8(join11(dir, "tsconfig.json"), JSON.stringify(tsconfig, null, 2) + "\n");
+  await writeFile8(join12(dir, "tsconfig.json"), JSON.stringify(tsconfig, null, 2) + "\n");
   files.push("tsconfig.json");
   const srcContent = `import { definePlugin } from "@gpc-cli/plugin-sdk";
 import type { CommandEvent, CommandResult } from "@gpc-cli/plugin-sdk";
@@ -7169,7 +7694,8 @@ export const plugin = definePlugin({
       // Example: send notifications, update dashboards, etc.
     });
 
-    // Uncomment to add custom commands:
+    // To add custom commands, first add "commands:register" to
+    // package.json#gpc.permissions, then uncomment this block:
     // hooks.registerCommands((registry) => {
     //   registry.add({
     //     name: "${shortName}",
@@ -7182,7 +7708,7 @@ export const plugin = definePlugin({
   },
 });
 `;
-  await writeFile8(join11(srcDir, "index.ts"), srcContent);
+  await writeFile8(join12(srcDir, "index.ts"), srcContent);
   files.push("src/index.ts");
   const testContent = `import { describe, it, expect, vi } from "vitest";
 import { plugin } from "../src/index";
@@ -7207,7 +7733,7 @@ describe("${pluginName}", () => {
   });
 });
 `;
-  await writeFile8(join11(testDir, "plugin.test.ts"), testContent);
+  await writeFile8(join12(testDir, "plugin.test.ts"), testContent);
   files.push("tests/plugin.test.ts");
   return { dir, files };
 }
@@ -7398,7 +7924,7 @@ async function downloadGeneratedApk(client, packageName, versionCode, apkId, out
 }
 
 // src/commands/bundle-analysis.ts
-import { readFile as readFile16, stat as stat8 } from "fs/promises";
+import { readFile as readFile17, stat as stat8 } from "fs/promises";
 var EOCD_SIGNATURE = 101010256;
 var CD_SIGNATURE = 33639248;
 var MODULE_SUBDIRS = /* @__PURE__ */ new Set(["dex", "manifest", "res", "assets", "lib", "resources.pb", "root"]);
@@ -7478,7 +8004,7 @@ async function analyzeBundle(filePath) {
   if (!fileInfo || !fileInfo.isFile()) {
     throw new Error(`File not found: ${filePath}`);
   }
-  const buf = await readFile16(filePath);
+  const buf = await readFile17(filePath);
   const cdEntries = parseCentralDirectory(buf);
   const fileType = detectFileType2(filePath);
   const isAab = fileType === "aab";
@@ -7564,7 +8090,7 @@ function topFiles(analysis, n = 20) {
 async function checkBundleSize(analysis, configPath = ".bundlesize.json") {
   let config;
   try {
-    const raw = await readFile16(configPath, "utf-8");
+    const raw = await readFile17(configPath, "utf-8");
     config = JSON.parse(raw);
   } catch {
     return { passed: true, violations: [] };
@@ -8926,7 +9452,7 @@ async function sha256File(filePath) {
 
 // src/commands/image-sync.ts
 import { readdir as readdir7, stat as stat10 } from "fs/promises";
-import { join as join12, extname as extname5 } from "path";
+import { join as join13, extname as extname5 } from "path";
 import { PlayApiError } from "@gpc-cli/api";
 var IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg"]);
 var ALL_IMAGE_TYPES2 = [
@@ -8981,7 +9507,7 @@ async function syncImages(client, packageName, dir, options) {
   try {
     for (const language of languages) {
       for (const imageType of imageTypes) {
-        const localDir = join12(dir, language, imageType);
+        const localDir = join13(dir, language, imageType);
         const localFiles = await scanLocalImages(localDir);
         let remoteImages;
         try {
@@ -8996,12 +9522,12 @@ async function syncImages(client, packageName, dir, options) {
         const remoteSha256Set = new Set(remoteImages.map((img) => img.sha256.toLowerCase()));
         const localHashes = /* @__PURE__ */ new Map();
         for (const file of localFiles) {
-          const hash = await sha256File(join12(localDir, file));
+          const hash = await sha256File(join13(localDir, file));
           localHashes.set(file, hash);
         }
         const uploadLocal = async (file, reason) => {
           if (!options?.dryRun) {
-            const filePath = join12(localDir, file);
+            const filePath = join13(localDir, file);
             const check = await validateImage(filePath, imageType);
             if (!check.valid) {
               throw new GpcError(
@@ -9035,7 +9561,13 @@ async function syncImages(client, packageName, dir, options) {
           if (inOrder) {
             for (const file of localFiles) {
               skipped++;
-              details.push({ language, imageType, file, action: "skip", reason: "already in order" });
+              details.push({
+                language,
+                imageType,
+                file,
+                action: "skip",
+                reason: "already in order"
+              });
             }
             continue;
           }
@@ -9045,7 +9577,13 @@ async function syncImages(client, packageName, dir, options) {
             }
             for (const img of remoteImages) {
               deleted++;
-              details.push({ language, imageType, file: img.id, action: "delete", reason: "reordering" });
+              details.push({
+                language,
+                imageType,
+                file: img.id,
+                action: "delete",
+                reason: "reordering"
+              });
             }
           }
           for (const file of localFiles) {
@@ -9444,7 +9982,9 @@ export {
   createTranslator,
   deactivateBasePlan,
   deactivateOffer,
+  decodeCsvText,
   decodeNotification,
+  decodeStatsCsv,
   defaultGitRunner,
   deferSubscriptionPurchase,
   deferSubscriptionV2,
@@ -9470,12 +10010,16 @@ export {
   diffOneTimeProduct,
   diffReleases,
   diffSubscription,
+  discoverPluginEntries,
   discoverPlugins,
   dispatchWebhook,
+  downloadFinancialReport,
   downloadGeneratedApk,
-  downloadReport,
+  downloadReportObject,
+  downloadStatsReport,
   exportImages,
   exportReviews,
+  extractCsvEntriesFromZip,
   fetchAggregateCost,
   fetchChangelog,
   fetchReleaseNotes,
@@ -9534,6 +10078,7 @@ export {
   getVitalsRendering,
   getVitalsStartup,
   gradeFromPercent,
+  gunzipIfNeeded,
   handleBreach,
   importDataSafety,
   importTestersFromCsv,
@@ -9541,11 +10086,13 @@ export {
   initProject,
   inviteUser,
   isFinancialReportType,
+  isGzip,
   isStatsReportType,
   isValidBcp47,
   isValidReportType,
   isValidStatsDimension,
   isVersionedNotesDir,
+  isZip,
   lintListing,
   lintListings,
   lintLocalListings,
@@ -9564,6 +10111,7 @@ export {
   listOneTimeOffers,
   listOneTimeProducts,
   listRecoveryActions,
+  listReportObjects,
   listReports,
   listReviews,
   listSubscriptions,
@@ -9575,6 +10123,7 @@ export {
   loadStatusCache,
   maybePaginate,
   migratePrices,
+  monthToken,
   moreResultsFooter,
   normalizeFingerprint,
   parseAppfile,
@@ -9616,8 +10165,13 @@ export {
   renderPlayStorePrompt,
   renderPrompt,
   replyToReview,
+  reportAccessDeniedError,
+  reportBucketNotFoundError,
+  reportObjectNotFoundError,
+  reportPrefix,
   resolveAiConfig,
   resolveLocales,
+  resolveReportsBucket,
   retryOnUploadNotComplete,
   revokeSubscriptionPurchase,
   runPreflight,
@@ -9667,6 +10221,7 @@ export {
   validateImage,
   validateLanguageCode,
   validatePackageName,
+  validatePluginForApproval,
   validatePreSubmission,
   validateReleaseNotes,
   validateSku,