@appeeky/spec 0.0.0-stage → 0.1.0

package/dist/schema.js

@@ -0,0 +1,218 @@
+import { z } from "zod";
+/** Stores a spec can describe. The ids double as folder names under `appeeky/store/`. */
+export const STORES = ["app-store", "google-play"];
+/** How a store is reached: the local store CLI with your own key, or Appeeky's hosted gateway. */
+export const transportMode = z.enum(["auto", "local", "hosted"]);
+const countryCode = z
+    .string()
+    .regex(/^[a-z]{2}$/i, "Use a two-letter storefront code such as us, gb or tr")
+    .transform((s) => s.toLowerCase());
+const appStoreConfig = z
+    .object({
+    /** Numeric App Store id (or a bundle id; the local CLI resolves it). */
+    appId: z.string().min(1),
+    platform: z.enum(["IOS", "MAC_OS", "TV_OS", "VISION_OS"]).default("IOS"),
+    via: transportMode.default("auto"),
+    /** Named account of the local `appstore` CLI. */
+    account: z.string().optional(),
+})
+    .strict();
+const googlePlayConfig = z
+    .object({
+    packageName: z.string().regex(/^[A-Za-z][\w]*(\.[A-Za-z_][\w]*)+$/, "Use the package name, e.g. com.example.app"),
+    via: transportMode.default("auto"),
+    /** Named account of the local `gps` CLI (`gps accounts add`). */
+    account: z.string().optional(),
+    /** Old name for `account`. */
+    profile: z.string().optional(),
+})
+    .strict();
+/** Meta ad campaigns that promote this app. Insights come through the Meta connection in Appeeky. */
+const metaAdsConfig = z
+    .object({
+    /** Ad account (act_…); defaults to the one picked in Appeeky. */
+    adAccount: z.string().optional(),
+    campaigns: z.array(z.string().min(1)).min(1),
+})
+    .strict();
+/** TikTok ad campaigns that promote this app. Reports come through the TikTok connection in Appeeky. */
+const tiktokAdsConfig = z
+    .object({
+    /** Advertiser id; defaults to the one picked in Appeeky. */
+    advertiser: z.string().optional(),
+    campaigns: z.array(z.string().min(1)).min(1),
+})
+    .strict();
+/** One thing people ask AI assistants for, and the prompts that ask it. */
+const aiIntent = z
+    .object({
+    label: z.string().min(8, "An intent label needs at least 8 characters"),
+    description: z.string().optional(),
+    prompts: z.array(z.string().min(15, "A prompt needs at least 15 characters")).default([]),
+})
+    .strict();
+/** Store charts a category rank is read from. */
+export const CHARTS = ["top-free", "top-paid", "top-grossing"];
+/** `appeeky.spec.yaml`: who the app is, where it ships, and what it should be found for. */
+export const specFileSchema = z
+    .object({
+    version: z.literal(1),
+    app: z
+        .object({
+        name: z.string().min(1),
+        /** Locale the store falls back to when a storefront has no localization of its own. */
+        primaryLocale: z.string().default("en-US"),
+    })
+        .strict(),
+    stores: z
+        .object({
+        appStore: appStoreConfig.optional(),
+        googlePlay: googlePlayConfig.optional(),
+    })
+        .strict()
+        .default({}),
+    /** Target keywords per storefront: the searches this app should be found for. */
+    targets: z.record(countryCode, z.array(z.string().min(1)).default([])).default({}),
+    /** Override which listing locales a storefront indexes (App Store). */
+    storefronts: z.record(countryCode, z.array(z.string().min(2)).min(1)).default({}),
+    /**
+     * Paid channels outside the store. Apple Search Ads needs nothing here: it is
+     * matched to the app in Appeeky. Meta and TikTok campaigns are listed by id.
+     */
+    ads: z
+        .object({
+        meta: metaAdsConfig.optional(),
+        tiktok: tiktokAdsConfig.optional(),
+    })
+        .strict()
+        .default({}),
+    /** Apps you compete with. `competitors pull` writes each one to appeeky/competitors/. */
+    competitors: z
+        .array(z
+        .object({
+        name: z.string().optional(),
+        appStore: z.string().regex(/^\d+$/, "Use the numeric App Store id").optional(),
+        googlePlay: z.string().optional(),
+    })
+        .strict()
+        .refine((c) => c.appStore || c.googlePlay, "Give an appStore id or a googlePlay package name"))
+        .default([]),
+    /**
+     * Install attribution from Appeeky Analytics: organic search, Search Ads keywords,
+     * smart links, with the revenue each led to. `via: self` reads your own server on
+     * Cloudflare (`url`, ATTRIBUTION_TOKEN); `via: hosted` reads Appeeky's (APPEEKY_API_KEY).
+     */
+    attribution: z
+        .object({
+        via: z.enum(["self", "hosted"]).default("hosted"),
+        url: z.string().url().optional(),
+        /**
+         * The app's id in Appeeky Analytics. An app there is one platform, so an app on both
+         * stores gives one per store: `{ app-store: …, google-play: … }`.
+         */
+        app: z.union([
+            z.string().min(1),
+            z
+                .object({ "app-store": z.string().min(1).optional(), "google-play": z.string().min(1).optional() })
+                .strict()
+                .refine((m) => m["app-store"] || m["google-play"], "give the app id for app-store, google-play or both"),
+        ]),
+    })
+        .strict()
+        .refine((a) => a.via !== "self" || a.url, "via: self needs the url of your Appeeky Analytics server")
+        .optional(),
+    /**
+     * Where `data pull` writes store analytics, ads and revenue. They are your private
+     * business numbers, so by default they stay in .appeeky/data/ (gitignored).
+     * `commit: true` writes them to appeeky/data/ so they are versioned with the spec.
+     */
+    data: z.object({ commit: z.boolean().default(false) }).strict().default({}),
+    /**
+     * Whether ChatGPT, Claude, Gemini and Perplexity name the app when people ask
+     * for one like it. Intents are what people want ("fall asleep to rain sounds"),
+     * prompts are how they ask; both are tracked per storefront in Appeeky AI Visibility.
+     */
+    aiVisibility: z
+        .object({
+        /** Which app to watch when it is on both stores; defaults to the App Store app. */
+        store: z.enum(STORES).optional(),
+        /** Storefronts to watch; defaults to the first storefront under targets. */
+        countries: z.array(countryCode).min(1).optional(),
+        /** What people ask AI assistants, per storefront. `visibility sync` sends them to Appeeky. */
+        intents: z.record(countryCode, z.array(aiIntent)).default({}),
+    })
+        .strict()
+        .optional(),
+    /** Rank in the app's category chart (top 100), recorded daily by `category pull`. */
+    category: z
+        .object({
+        /** App Store genre id, e.g. "6013" for Health & Fitness; read from the app when left out. */
+        appStore: z.string().regex(/^\d+$/, "Use the numeric App Store genre id, e.g. 6013").optional(),
+        /** Google Play category, e.g. HEALTH_AND_FITNESS. */
+        googlePlay: z.string().regex(/^[A-Z_]+$/, "Use the Google Play category id, e.g. HEALTH_AND_FITNESS").optional(),
+        /** Defaults to top-paid for a paid App Store app, top-free otherwise. */
+        chart: z.enum(CHARTS).optional(),
+        /** Storefronts to record; defaults to the storefronts under targets. */
+        countries: z.array(countryCode).min(1).optional(),
+    })
+        .strict()
+        .optional(),
+    /** Who the app is for. Experiments, screenshots and UGC refer to these by id. */
+    personas: z
+        .array(z
+        .object({
+        id: z.string().regex(/^[a-z0-9-]+$/),
+        name: z.string().min(1),
+        description: z.string().optional(),
+        /** How this persona searches: seeds for targets and keyword ideas. */
+        searches: z.array(z.string()).default([]),
+    })
+        .strict())
+        .default([]),
+})
+    .strict();
+/**
+ * One App Store locale: `appeeky/store/app-store/<locale>.yaml`.
+ * A field left out is not managed by the spec: it is never diffed or pushed.
+ */
+export const appStoreListingSchema = z
+    .object({
+    name: z.string().optional(),
+    subtitle: z.string().optional(),
+    keywords: z.string().optional(),
+    promotionalText: z.string().optional(),
+    description: z.string().optional(),
+    whatsNew: z.string().optional(),
+    marketingUrl: z.string().url().optional(),
+    supportUrl: z.string().url().optional(),
+})
+    .strict();
+/** One Google Play language: `appeeky/store/google-play/<language>.yaml`. */
+export const googlePlayListingSchema = z
+    .object({
+    title: z.string().optional(),
+    shortDescription: z.string().optional(),
+    fullDescription: z.string().optional(),
+    video: z.string().url().optional(),
+})
+    .strict();
+export const APP_STORE_FIELDS = [
+    "name",
+    "subtitle",
+    "keywords",
+    "promotionalText",
+    "description",
+    "whatsNew",
+    "marketingUrl",
+    "supportUrl",
+];
+export const GOOGLE_PLAY_FIELDS = [
+    "title",
+    "shortDescription",
+    "fullDescription",
+    "video",
+];
+export function fieldsFor(store) {
+    return store === "app-store" ? APP_STORE_FIELDS : GOOGLE_PLAY_FIELDS;
+}
+//# sourceMappingURL=schema.js.map

package/dist/screenshots.d.ts

@@ -0,0 +1,23 @@
+import type { Issue } from "./lint.js";
+import type { RemoteState } from "./stores/types.js";
+import type { OpsTransport } from "./transport.js";
+/**
+ * Screenshots live next to the listings:
+ * `appeeky/screenshots/app-store/<locale>/<DISPLAY_TYPE>/01.png`.
+ * `screenshots pull` downloads the live set; `check` validates sizes and counts.
+ */
+export declare function screenshotsDir(root: string): string;
+/** Portrait sizes App Store Connect accepts per display type (landscape is the same, swapped). */
+export declare const SCREENSHOT_SIZES: Record<string, Array<[number, number]>>;
+/** Width and height from a PNG or JPEG header, without decoding the image. */
+export declare function imageSize(file: string): Promise<{
+    width: number;
+    height: number;
+} | null>;
+/** Sizes and counts of every screenshot set in the spec. */
+export declare function checkScreenshots(root: string): Promise<Issue[]>;
+/** Download the live App Store screenshots of every locale into the spec. */
+export declare function pullScreenshots(root: string, transport: OpsTransport, state: RemoteState, options?: {
+    locales?: string[];
+    fetcher?: typeof fetch;
+}): Promise<number>;

package/dist/screenshots.js

@@ -0,0 +1,116 @@
+import { existsSync } from "node:fs";
+import { mkdir, open, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { SPEC_DIR } from "./files.js";
+/**
+ * Screenshots live next to the listings:
+ * `appeeky/screenshots/app-store/<locale>/<DISPLAY_TYPE>/01.png`.
+ * `screenshots pull` downloads the live set; `check` validates sizes and counts.
+ */
+export function screenshotsDir(root) {
+    return join(root, SPEC_DIR, "screenshots", "app-store");
+}
+/** Portrait sizes App Store Connect accepts per display type (landscape is the same, swapped). */
+export const SCREENSHOT_SIZES = {
+    APP_IPHONE_67: [[1290, 2796], [1320, 2868], [1260, 2736]],
+    APP_IPHONE_65: [[1242, 2688], [1284, 2778]],
+    APP_IPHONE_61: [[1179, 2556], [1206, 2622], [1170, 2532]],
+    APP_IPHONE_58: [[1125, 2436], [1080, 2340]],
+    APP_IPHONE_55: [[1242, 2208]],
+    APP_IPAD_PRO_3GEN_129: [[2048, 2732], [2064, 2752]],
+    APP_IPAD_PRO_129: [[2048, 2732]],
+    APP_IPAD_PRO_3GEN_11: [[1668, 2388], [1640, 2360]],
+};
+const MAX_PER_SET = 10;
+/** Width and height from a PNG or JPEG header, without decoding the image. */
+export async function imageSize(file) {
+    const fh = await open(file, "r");
+    try {
+        const head = Buffer.alloc(64 * 1024);
+        const { bytesRead } = await fh.read(head, 0, head.length, 0);
+        const b = head.subarray(0, bytesRead);
+        if (b.length >= 24 && b.readUInt32BE(0) === 0x89504e47)
+            return { width: b.readUInt32BE(16), height: b.readUInt32BE(20) };
+        if (b[0] === 0xff && b[1] === 0xd8) {
+            let i = 2;
+            while (i + 9 < b.length) {
+                if (b[i] !== 0xff)
+                    return null;
+                const marker = b[i + 1];
+                const len = b.readUInt16BE(i + 2);
+                if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
+                    return { height: b.readUInt16BE(i + 5), width: b.readUInt16BE(i + 7) };
+                }
+                i += 2 + len;
+            }
+        }
+        return null;
+    }
+    finally {
+        await fh.close();
+    }
+}
+/** Sizes and counts of every screenshot set in the spec. */
+export async function checkScreenshots(root) {
+    const base = screenshotsDir(root);
+    if (!existsSync(base))
+        return [];
+    const issues = [];
+    for (const locale of await readdir(base)) {
+        const localeDir = join(base, locale);
+        if (!(await readdir(localeDir).catch(() => null)))
+            continue;
+        for (const type of await readdir(localeDir)) {
+            const files = (await readdir(join(localeDir, type)).catch(() => [])).filter((f) => /\.(png|jpe?g)$/i.test(f)).sort();
+            const at = (severity, message) => issues.push({ severity, rule: "screenshots", store: "app-store", locale, field: type, message });
+            if (files.length > MAX_PER_SET)
+                at("error", `${type} has ${files.length} screenshots; the limit is ${MAX_PER_SET}.`);
+            const sizes = SCREENSHOT_SIZES[type];
+            if (!sizes)
+                continue;
+            for (const f of files) {
+                const size = await imageSize(join(localeDir, type, f));
+                if (!size)
+                    continue;
+                const ok = sizes.some(([w, h]) => (size.width === w && size.height === h) || (size.width === h && size.height === w));
+                if (!ok)
+                    at("error", `${f} is ${size.width}×${size.height}; ${type} takes ${sizes.map(([w, h]) => `${w}×${h}`).join(", ")}.`);
+            }
+        }
+    }
+    return issues;
+}
+const list = (doc) => {
+    const d = doc?.data;
+    return Array.isArray(d) ? d : [];
+};
+/** Download the live App Store screenshots of every locale into the spec. */
+export async function pullScreenshots(root, transport, state, options = {}) {
+    const ctx = state.context;
+    const doFetch = options.fetcher ?? fetch;
+    let count = 0;
+    for (const [locale, localizationId] of Object.entries(ctx.versionLocIds)) {
+        if (options.locales && !options.locales.includes(locale))
+            continue;
+        const sets = list(await transport.call("appstore_list_screenshot_sets", { localizationId, limit: 50 }));
+        for (const set of sets) {
+            const type = set.attributes?.screenshotDisplayType ?? "UNKNOWN";
+            const shots = list(await transport.call("appstore_list_screenshots", { setId: set.id, limit: 50 }));
+            const dir = join(screenshotsDir(root), locale, type);
+            await mkdir(dir, { recursive: true });
+            for (const [i, shot] of shots.entries()) {
+                const asset = shot.attributes?.imageAsset;
+                if (!asset?.templateUrl || !asset.width || !asset.height)
+                    continue;
+                const url = asset.templateUrl.replace("{w}", String(asset.width)).replace("{h}", String(asset.height)).replace("{f}", "png");
+                const res = await doFetch(url);
+                if (!res.ok)
+                    continue;
+                await writeFile(join(dir, `${String(i + 1).padStart(2, "0")}.png`), Buffer.from(await res.arrayBuffer()));
+                count++;
+            }
+        }
+    }
+    return count;
+}
+//# sourceMappingURL=screenshots.js.map

package/dist/setup.d.ts

@@ -0,0 +1,45 @@
+import type { Project, StoreId } from "./schema.js";
+import type { RankSource } from "./verify.js";
+type Fetcher = typeof fetch;
+export interface FoundApp {
+    id: string;
+    name: string;
+    developer: string;
+    bundleId: string;
+    rating?: number;
+}
+/** App Store apps matching a name, from Apple's public search. */
+export declare function findApps(term: string, country?: string, fetcher?: Fetcher): Promise<FoundApp[]>;
+/** Whether a Google Play package has a public store page. */
+export declare function playPackageExists(pkg: string, fetcher?: Fetcher): Promise<boolean>;
+/**
+ * Searches the listing already speaks to: the parts of the name and subtitle between
+ * punctuation ("Sleep Sounds: Rain & Ocean" → "sleep sounds", "rain", "ocean"), their two-word
+ * runs, and keyword-field entries. The brand (the name's first part, alone) is left out.
+ */
+export declare function targetCandidates(project: Project, limit?: number, storeName?: string): string[];
+export interface RankedCandidate {
+    keyword: string;
+    rank: number | null;
+}
+/**
+ * The searches to start with: the ones the app already ranks for (a target you are near is
+ * the cheapest win), best first, then two-word phrases from the listing.
+ */
+export declare function suggestTargets(candidates: string[], appId: string | undefined, country: string, source: RankSource, count?: number): Promise<RankedCandidate[]>;
+export declare const WORKFLOWS: Record<string, string>;
+export type CheckStatus = "ok" | "warn" | "fail";
+export interface DoctorCheck {
+    area: string;
+    status: CheckStatus;
+    detail: string;
+    /** How to fix it, when it is not ok. */
+    fix?: string;
+}
+/** Where each store CLI keeps its saved accounts (`appstore accounts add`, `gps accounts add`). */
+export declare function savedAccountsFile(store: StoreId, env?: NodeJS.ProcessEnv): string;
+/** Names of the accounts saved with the store CLI, if any. */
+export declare function savedAccounts(store: StoreId, env?: NodeJS.ProcessEnv): string[];
+/** What is set up for this repo, and what is missing. Works without a spec (it says so). */
+export declare function diagnose(root: string, project: Project | null, env?: NodeJS.ProcessEnv, nodeVersion?: string): DoctorCheck[];
+export {};

package/dist/setup.js

@@ -0,0 +1,226 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { SPEC_DIR, SPEC_FILE } from "./files.js";
+import { normalize, words } from "./text.js";
+import { STORE_CLIS, onPath } from "./transport.js";
+/** App Store apps matching a name, from Apple's public search. */
+export async function findApps(term, country = "us", fetcher = fetch) {
+    const url = `https://itunes.apple.com/search?media=software&entity=software&limit=6&country=${encodeURIComponent(country)}&term=${encodeURIComponent(term)}`;
+    const res = await fetcher(url, { headers: { "User-Agent": "appeeky-spec" } });
+    if (!res.ok)
+        return [];
+    const json = (await res.json());
+    return (json.results ?? [])
+        .filter((r) => r.trackId && r.trackName)
+        .map((r) => ({
+        id: String(r.trackId),
+        name: r.trackName,
+        developer: r.sellerName ?? r.artistName ?? "",
+        bundleId: r.bundleId ?? "",
+        ...(r.averageUserRating ? { rating: Math.round(r.averageUserRating * 10) / 10 } : {}),
+    }));
+}
+/** Whether a Google Play package has a public store page. */
+export async function playPackageExists(pkg, fetcher = fetch) {
+    try {
+        const res = await fetcher(`https://play.google.com/store/apps/details?id=${encodeURIComponent(pkg)}&hl=en`, { method: "HEAD", headers: { "User-Agent": "Mozilla/5.0 appeeky-spec" } });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Targets ─────────────────────────────────────────────────────────────────
+/** Words nobody searches with, at the start or the end of a phrase ("AI-powered", "the best"). */
+const FILLER = new Set("a an the and or for with your my our to of in on by best top new free app apps powered based simple easy fast smart ultimate official".split(" "));
+/**
+ * Searches the listing already speaks to: the parts of the name and subtitle between
+ * punctuation ("Sleep Sounds: Rain & Ocean" → "sleep sounds", "rain", "ocean"), their two-word
+ * runs, and keyword-field entries. The brand (the name's first part, alone) is left out.
+ */
+export function targetCandidates(project, limit = 14, storeName) {
+    const locale = project.spec.app.primaryLocale;
+    const asc = project.listings["app-store"][locale];
+    const play = project.listings["google-play"][locale] ?? Object.values(project.listings["google-play"])[0];
+    const name = asc?.name ?? play?.title ?? storeName ?? project.spec.app.name;
+    const subtitle = asc?.subtitle ?? play?.shortDescription ?? "";
+    const brand = normalize(project.spec.app.name).trim();
+    const out = [];
+    const add = (phrase) => {
+        const ws = words(phrase);
+        const p = ws.join(" ");
+        if (!p || p.length < 3 || p === brand || out.includes(p) || ws.length > 3)
+            return;
+        if (FILLER.has(ws[0]) || FILLER.has(ws[ws.length - 1]))
+            return;
+        out.push(p);
+    };
+    for (const text of [name, subtitle]) {
+        for (const part of text.split(/[:\-–—|,&+/()]| and | for | with /i)) {
+            add(part);
+            const ws = words(part);
+            for (let i = 0; i + 1 < ws.length; i++)
+                add(`${ws[i]} ${ws[i + 1]}`);
+        }
+    }
+    for (const k of (asc?.keywords ?? "").split(","))
+        add(k);
+    return out.slice(0, limit);
+}
+/**
+ * The searches to start with: the ones the app already ranks for (a target you are near is
+ * the cheapest win), best first, then two-word phrases from the listing.
+ */
+export async function suggestTargets(candidates, appId, country, source, count = 5) {
+    const ranks = appId ? await source.ranks("app-store", appId, country, candidates).catch(() => ({})) : {};
+    const ranked = candidates.map((keyword) => ({ keyword, rank: ranks[keyword] ?? null }));
+    const found = ranked.filter((r) => r.rank !== null).sort((a, b) => a.rank - b.rank);
+    const rest = ranked.filter((r) => r.rank === null).sort((a, b) => b.keyword.split(" ").length - a.keyword.split(" ").length);
+    return [...found, ...rest].slice(0, count);
+}
+// ── GitHub workflows ────────────────────────────────────────────────────────
+export const WORKFLOWS = {
+    "listing-check.yml": `# Appeeky Spec: report listing changes on every pull request.
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write     # to comment
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0     # the report compares with main
+      - uses: appeeky/appeeky-spec@v0
+`,
+    "listing-push.yml": `# Appeeky Spec: push the listing to the stores when a change is merged.
+on:
+  push:
+    branches: [main]
+    paths: ["appeeky/store/**", "appeeky.spec.yaml"]
+permissions:
+  contents: write          # to commit the release file
+jobs:
+  push:
+    runs-on: ubuntu-latest
+    environment: stores    # optional: a required approval before it runs
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx @appeeky/spec push --yes --note "\${{ github.event.head_commit.message }}"
+        env:
+          APPEEKY_API_KEY: \${{ secrets.APPEEKY_API_KEY }}
+      - run: |
+          git config user.name "appeeky-spec"
+          git config user.email "spec@users.noreply.github.com"
+          git add appeeky && git commit -m "Record release" && git push || true
+`,
+    "listing-daily.yml": `# Appeeky Spec: record the category rank and AI visibility, measure releases on day 7 and 14, refresh reviews and competitors.
+on:
+  schedule: [{ cron: "0 6 * * *" }]   # 06:00 UTC
+  workflow_dispatch:
+permissions:
+  contents: write
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          npx @appeeky/spec category pull || true
+          npx @appeeky/spec visibility pull || true
+          npx @appeeky/spec verify --playbook
+          npx @appeeky/spec reviews pull || true
+          npx @appeeky/spec competitors pull || true
+        env:
+          APPEEKY_API_KEY: \${{ secrets.APPEEKY_API_KEY }}
+      - run: |
+          git config user.name "appeeky-spec"
+          git config user.email "spec@users.noreply.github.com"
+          git add appeeky && git commit -m "Daily: category, AI visibility, verify, reviews, competitors" && git push || true
+`,
+};
+const ok = (area, detail) => ({ area, status: "ok", detail });
+const warn = (area, detail, fix) => ({ area, status: "warn", detail, fix });
+const fail = (area, detail, fix) => ({ area, status: "fail", detail, fix });
+const hasLocalKeys = (store, env) => store === "app-store"
+    ? Boolean(env.ASC_KEY_ID && (env.ASC_PRIVATE_KEY || env.ASC_PRIVATE_KEY_PATH))
+    : Boolean(env.GPS_CREDENTIALS || env.GOOGLE_PLAY_CREDENTIALS || env.GOOGLE_APPLICATION_CREDENTIALS);
+/** Where each store CLI keeps its saved accounts (`appstore accounts add`, `gps accounts add`). */
+export function savedAccountsFile(store, env = process.env) {
+    const base = env.XDG_CONFIG_HOME ?? join(env.HOME ?? env.USERPROFILE ?? "", ".config");
+    return join(base, store === "app-store" ? "appstore" : "gps", "config.json");
+}
+/** Names of the accounts saved with the store CLI, if any. */
+export function savedAccounts(store, env = process.env) {
+    try {
+        const config = JSON.parse(readFileSync(savedAccountsFile(store, env), "utf8"));
+        const accounts = config.accounts;
+        return Array.isArray(accounts) ? accounts.map((a) => String(a.name ?? a)) : Object.keys(accounts ?? {});
+    }
+    catch {
+        return [];
+    }
+}
+/** What is set up for this repo, and what is missing. Works without a spec (it says so). */
+export function diagnose(root, project, env = process.env, nodeVersion = process.versions.node) {
+    const out = [];
+    const major = Number(nodeVersion.split(".")[0]);
+    out.push(major >= 20 ? ok("node", `Node ${nodeVersion}`) : fail("node", `Node ${nodeVersion}`, "Install Node 20 or newer."));
+    if (!project) {
+        out.push(fail("spec", `No ${SPEC_FILE} here or above`, "Run `npx @appeeky/spec init` in your app's repo."));
+        return out;
+    }
+    out.push(ok("spec", `${SPEC_FILE} · ${project.spec.app.name}`));
+    const key = Boolean(env.APPEEKY_API_KEY);
+    const stores = [...(project.spec.stores.appStore ? ["app-store"] : []), ...(project.spec.stores.googlePlay ? ["google-play"] : [])];
+    if (stores.length === 0)
+        out.push(fail("stores", "No store in the spec", "Add stores.appStore.appId or stores.googlePlay.packageName, or run `init` again."));
+    for (const store of stores) {
+        const cli = STORE_CLIS[store];
+        const label = store === "app-store" ? "App Store" : "Google Play";
+        const via = (store === "app-store" ? project.spec.stores.appStore?.via : project.spec.stores.googlePlay?.via) ?? "auto";
+        const local = onPath(cli.bin, env);
+        // The CLI runs from PATH or through npx; either way it reads keys from the environment or its saved accounts.
+        const accounts = savedAccounts(store, env);
+        const keys = hasLocalKeys(store, env) ? "keys in the environment" : accounts.length ? `saved account${accounts.length > 1 ? "s" : ""} ${accounts.join(", ")}` : "";
+        const runner = local ? `${cli.bin} CLI` : `npx ${cli.npmPackage}`;
+        if (via === "hosted")
+            out.push(key ? ok(label, "hosted through your Appeeky connection (APPEEKY_API_KEY)") : fail(label, "via: hosted, but APPEEKY_API_KEY is not set", "Set APPEEKY_API_KEY (appeeky.com/dashboard/settings)."));
+        else if (keys && (via === "local" || local || !key))
+            out.push(ok(label, `your own key: ${runner}, ${keys}`));
+        else if (via !== "local" && key)
+            out.push(ok(label, "hosted through your Appeeky connection (APPEEKY_API_KEY)"));
+        else if (local)
+            out.push(fail(label, `${cli.bin} CLI is installed but has no saved account and no keys in the environment`, cli.setupHint));
+        else
+            out.push(fail(label, `No store key saved, no ${cli.bin} CLI and no APPEEKY_API_KEY`, cli.setupHint));
+        const files = Object.keys(project.listings[store]).length;
+        out.push(files ? ok(`${label} listing`, `${files} locale${files === 1 ? "" : "s"} in ${SPEC_DIR}/store/${store}/`) : warn(`${label} listing`, "Not pulled yet", `Run \`npx @appeeky/spec pull --store ${store}\`.`));
+    }
+    const targets = Object.entries(project.spec.targets).filter(([, list]) => list.length > 0);
+    const count = targets.reduce((n, [, list]) => n + list.length, 0);
+    out.push(count ? ok("targets", `${count} in ${targets.map(([cc]) => cc).join(", ")}`) : fail("targets", "None yet: coverage and verify have nothing to measure", "Add the searches to win under targets:, or run `npx @appeeky/spec suggest`."));
+    if (targets.length === 1)
+        out.push(warn("control group", "Targets in one storefront only", "Add a few targets for a second country: verify compares the storefronts a release changed with the ones it did not."));
+    out.push(key ? ok("Appeeky API", "APPEEKY_API_KEY set: popularity, both stores' ranks, conversion, revenue, ads") : warn("Appeeky API", "Not set: App Store ranks only, no popularity or outcome metrics", "Optional: set APPEEKY_API_KEY."));
+    const attribution = project.spec.attribution;
+    if (!attribution)
+        out.push(warn("attribution", "Not set up: releases are judged on ranks and store numbers", "Optional: `npx @appeeky/spec attribution init`."));
+    else if (attribution.via === "self" && !env.ATTRIBUTION_TOKEN)
+        out.push(fail("attribution", "via: self, but ATTRIBUTION_TOKEN is not set", "Set ATTRIBUTION_TOKEN to your server's ADMIN_TOKEN."));
+    else if (attribution.via === "hosted" && !key)
+        out.push(fail("attribution", "via: hosted, but APPEEKY_API_KEY is not set", "Set APPEEKY_API_KEY."));
+    else
+        out.push(ok("attribution", `${attribution.via === "self" ? attribution.url : "Appeeky hosted"}`));
+    const workflows = join(root, ".github", "workflows");
+    const found = existsSync(workflows) ? readdirSync(workflows).filter((f) => /\.ya?ml$/.test(f) && /appeeky\/appeeky-spec|@appeeky\/spec/.test(readFileSync(join(workflows, f), "utf8"))) : [];
+    out.push(found.length ? ok("GitHub Actions", found.join(", ")) : warn("GitHub Actions", "No workflow runs the spec", "Optional: `npx @appeeky/spec init --ci` writes the pull request check, push on merge and daily verify."));
+    const skills = [".claude/skills/appeeky-spec", ".agents/skills/appeeky-spec", ".cursor/skills/appeeky-spec"].some((p) => existsSync(join(root, p)));
+    out.push(skills ? ok("agent skills", "installed") : warn("agent skills", "Not installed in this repo", "Optional: `npx skills add appeeky/appeeky-spec`."));
+    const ignore = existsSync(join(root, ".gitignore")) ? readFileSync(join(root, ".gitignore"), "utf8") : "";
+    if (!/\.appeeky\/?(\s|$)|\.appeeky\/data|\.appeeky\/\*/m.test(ignore))
+        out.push(warn(".gitignore", ".appeeky/ is not ignored: data and cache could be committed", "Add `.appeeky/` to .gitignore."));
+    return out;
+}
+//# sourceMappingURL=setup.js.map

package/dist/storefronts.d.ts

@@ -0,0 +1,15 @@
+import type { Project } from "./schema.js";
+/**
+ * Listing locales each App Store storefront is commonly observed to index, in
+ * order of preference. Apple does not publish this list and it changes, so it
+ * is a starting point: override any storefront with `storefronts:` in
+ * `appeeky.spec.yaml`. Storefronts not listed here fall back to the app's
+ * primary locale.
+ */
+export declare const DEFAULT_STOREFRONT_LOCALES: Record<string, string[]>;
+/** Listing locales that count for a storefront, limited to locales the spec has. */
+export declare function indexedLocales(project: Project, country: string): string[];
+/** Best Google Play language for a storefront: exact match first, then the bare language, then the primary locale. */
+export declare function playLanguageFor(project: Project, country: string): string | undefined;
+/** The Google Play language for an App Store locale (`tr` → `tr-TR`, `zh-Hans` → `zh-CN`). */
+export declare function playLanguageCode(appStoreLocale: string): string;