docs: desktop D3 (studios, accounts, store-only apps, owner actions, writes) and R&D note on a fastlane importer and a RevenueCat adapter

This commit is contained in:
CRTkafa 2026-10-11 04:26:57 +08:00
parent ba58895d3a
commit c3454e352d
2 changed files with 197 additions and 2 deletions

View file

@ -25,8 +25,15 @@ Types of the protocol: `cli/lib/desktop-protocol.ts`; pure portfolio logic: `cli
the sidecar's stdin. Write methods are dry runs unless the call carries a confirm token: HMAC-SHA256 over the the sidecar's stdin. Write methods are dry runs unless the call carries a confirm token: HMAC-SHA256 over the
method, the canonical `{ project, args }` and a 60 s expiry, single use. The host mints one only after the owner method, the canonical `{ project, args }` and a 60 s expiry, single use. The host mints one only after the owner
pressed Apply in a native dialog that shows the summary and the dry run (`write_with_confirm`). pressed Apply in a native dialog that shows the summary and the dry run (`write_with_confirm`).
- No method submits for review, releases, publishes, resumes or completes a rollout. Under `serve`, the CLI's own - No method submits for review, releases an approved version, publishes, cancels a submission, sends a build to
terminal confirmations always answer no. external testers or removes testers. Under `serve`, the CLI's own terminal confirmations answer no, with one
exception: the **owner actions** (`owner.play_rollout` share / halt / resume / complete, `owner.ios_phased`
on / pause / resume / complete, `owner.reply_send` one approved draft, `owner.testflight_testers` adds the testers
of `.storebound/testers.csv`). They are desktop-only (never MCP tools), dry runs from the window like every write,
and their real run needs the host token. Only then serve sets `STOREBOUND_OWNER_CONFIRMED` for that one child,
which answers the command's question. The native dialog names the action on its button ("Yes: Change the Play
staged rollout"). `tests/desktop-d3.test.ts` and `src-tauri/tests/d3_writes.rs` pin the token binding of every
write the window offers.
- The webview gets no plugin API. It may call the app commands (each re-checks the window label and the page origin - The webview gets no plugin API. It may call the app commands (each re-checks the window label and the page origin
in Rust) and listen to two events. Strict CSP, no remote content. `src-tauri/tests/security.rs` pins all of it. in Rust) and listen to two events. Strict CSP, no remote content. `src-tauri/tests/security.rs` pins all of it.
- Store keys (Play service account JSON, App Store Connect key id, issuer id and .p8) are picked in native dialogs, - Store keys (Play service account JSON, App Store Connect key id, issuer id and .p8) are picked in native dialogs,
@ -61,6 +68,84 @@ Types of the protocol: `cli/lib/desktop-protocol.ts`; pure portfolio logic: `cli
(CI) checks keys, empty messages and placeholders. **Theme**: text tokens keep 7:1 contrast in both themes (CI) checks keys, empty messages and placeholders. **Theme**: text tokens keep 7:1 contrast in both themes
(`tests/theme.test.ts`), motion at most 200 ms and off with reduced motion. (`tests/theme.test.ts`), motion at most 200 ms and off with reduced motion.
## Studios, accounts and store-only apps (D3)
### Accounts and studios
- A **studio** is a name, a colour and an optional logo. It groups any number of store accounts:
- a Play service account, which can be invited to several Play developer accounts and then sees all their apps;
- an App Store Connect team key, one per team.
- Keys stay in the keychain. The state file keeps labels and studio ids only.
- `storebound apps check` gives each account's health, with the fix in words:
- ok;
- no-apps;
- permission (Play: "invite <service account> in Play Console > Users and permissions with ...");
- revoked;
- api-disabled.
- `storebound apps list` reads the apps an account can see:
- App Store Connect: `GET /v1/apps`, the newest version, and an icon from the newest build's `iconAssetToken`,
fetched by the CLI and returned as a data URL;
- Play: the Reporting API `apps:search`.
- Serve exposes both as `apps.list` and `account.check` (kind `account`, one account's key per call, run in an
empty temp folder). The host caches app lists under `acct:<id>`.
### One card per app
`src/lib/identity.ts` builds one card per app, pure and tested:
1. A folder takes the store apps its config names. Order: an explicit link, then the App Store app id, then the
bundle id or package name. The folder's mapped accounts win.
2. The remaining store apps pair iOS + Android, in this order:
- manual pairs;
- the same id;
- a close id (`.ios` / `.android` suffixes, case, punctuation);
- the same name.
Unpairs block automatic pairs.
3. What is left is a single-store app.
Overrides (pairs, unpairs, links, studio moves, the ignore list of apps, folders and whole accounts) live in the
host state file (`overrides_set`, every key checked in `workspace.rs`).
### Store-only apps
- A store-only app has no folder. It is read through a **store target**:
`store:ios:<account>:<app id>:<bundle>;android:<account>:<package>`.
- The host checks the target and the account kinds, and passes `virtual: { name, apple, play }`. The sidecar writes
a minimal `storebound.config.json` (store ids, placeholder links) into its temp folder.
- Only `apple.status`, `play.status`, `health`, `reviews.list`, `apple.testflight_status` and `apple.ppo_status` work
this way, and `portfolio.status` takes store-only entries.
- "Link a folder" or "Start an app folder here" turn it into a full app.
### Settings
- Studios and accounts.
- Pairing and the ignore list.
- Store reads: on launch, every 15 min to 12 h (off by default), apps at a time 1-8, icons.
- Offline cache: size, keep 7 / 30 / 90 / 365 days or always, clear.
- Language, theme and motion.
- Notifications, after a read, never on the first one: review / release state changes, new 1-2 star reviews, crash
or ANR over the Play threshold.
- Dependencies and the CLI sidecar.
- Privacy, with a button that reveals the data folder.
- Shortcuts.
- Update channel (placeholder until the updater ships).
- Reset: native confirmation, then the keychain entries and every saved state are removed.
### Writes in the window
Each write is a dry run, then the native dialog, then the real run, with one progress toast and Cancel:
- **Listings tab:** Play listing text, App Store version and text, Play graphics, App Store screenshots and
previews; local render jobs (screenshots, previews, icons, gallery).
- **Catalog tab:** Play products and subscriptions, App Store IAPs and subscriptions, price export. Price import
stays a terminal step.
- **Releases tab:** rollout and phased release owner actions.
- **TestFlight tab:** What to Test, internal groups, testers.
- **Reviews tab:** reply editor (`reviews.reply`), approve, send (owner action).
R&D on a fastlane importer and a RevenueCat adapter: `docs/research/fastlane-revenuecat.md`.
## Dependencies screen ## Dependencies screen
storebound needs no local tool for store work. Screenshots, app previews, icons and captures use: storebound needs no local tool for store work. Screenshots, app previews, icons and captures use:

View file

@ -0,0 +1,110 @@
# R&D: a fastlane importer and a RevenueCat adapter
Two questions for after desktop D3. Facts come from the official docs linked in each section; the
recommendations are ours.
## 1. `storebound import fastlane`
**What fastlane keeps on disk**
- **deliver (App Store)**, under `fastlane/metadata/`
([docs.fastlane.tools/actions/deliver](https://docs.fastlane.tools/actions/deliver/)):
- One folder per language: `name.txt`, `subtitle.txt`, `description.txt`, `keywords.txt`, `promotional_text.txt`,
`release_notes.txt`, `support_url.txt`, `marketing_url.txt`, `privacy_url.txt`.
- Non-localized files at the root: `copyright.txt`, `primary_category.txt`, `secondary_category.txt` and the
sub-category files.
- `review_information/`: `first_name.txt`, `last_name.txt`, `phone_number.txt`, `email_address.txt`,
`demo_user.txt`, `demo_password.txt`, `notes.txt`.
- A `default/` folder that fills any language without its own files.
- Screenshots and app previews in one folder per language. The device comes from the image size or the file name.
- **supply (Google Play)**, under `fastlane/metadata/android/<locale>/`
([docs.fastlane.tools/actions/supply](https://docs.fastlane.tools/actions/supply/)):
- `title.txt`, `short_description.txt`, `full_description.txt`, `video.txt`.
- `changelogs/<versionCode>.txt` and `changelogs/default.txt`.
- `images/`: `icon`, `featureGraphic`, `promoGraphic`, `tvBanner`, plus `phoneScreenshots/`, `sevenInchScreenshots/`
and `tenInchScreenshots/`.
- **Appfile / Deliverfile / Fastfile** are Ruby:
- `app_identifier`, `apple_id`, `team_id` / `itc_team_id`, `json_key_file`, `package_name`.
- Deliverfile options such as `languages`, `submit_for_review`, `automatic_release`, `phased_release`,
`price_tier`, `app_rating_config_path`.
**What an importer would do.** It would only read, it would never run Ruby, and it would write with `--dry` first.
1. **Store ids.** Parse the simple `key("value")` / `key "value"` lines of `Appfile` and `Deliverfile` with a strict
regex. That gives `apple.bundleId`, `play.packageName` and the languages. Ruby logic (conditionals, `ENV[...]`,
lanes) is reported as "set by hand", never guessed.
2. **Languages.** Join the deliver locales and the supply locales into storebound `languages[]` (`apple`, `play` codes).
3. **Listing text.**
- Write `store/appstore.md` and `store/listing.md` from the `.txt` files, mapping `default/` into every language
that lacks a file.
- The newest `changelogs/<versionCode>.txt` becomes `whatsNew`.
- Check lengths against the store limits (`storebound check`).
4. **Art.** Copy or link the screenshot folders into the renders layout (per language and size), or list them as
`shots.frames` when they look like raw captures. The supply icon and feature graphic go to the configured paths.
5. **Secrets and personal data.**
- `json_key_file` and `review_information/*` (contact, demo user and password) go to
`.storebound/credentials.json`, which is gitignored, and never to the config (AGENTS.md rules 4 and 9).
- The importer prints that it moved them, masked.
6. **Not imported, with a note:**
- Submission and release flags (`submit_for_review`, `automatic_release`). storebound never submits.
- `price_tier`. Prices live in the products / CSV flow.
- The age rating config (answered with the owner in `store-declarations`).
- Fastfile lanes.
**Worth it? Yes.** fastlane is the most common existing setup, and its metadata folder maps almost one to one onto
storebound's listing files. A read-only importer gives a migration path that keeps the store text, the screenshots
and the credentials layout in a few seconds, and a dry run shows exactly what lands where.
**Effort:** about 2 to 3 days with tests on fixture folders: an Appfile / Deliverfile line parser, the two metadata
walkers, a dry-run report, and the `.storebound/` hand-off. Ship it as `storebound import fastlane [--dir fastlane]
[--dry]`, then as an "Import from fastlane" choice in the desktop first-run guide.
## 2. A RevenueCat adapter
**What the API offers.** RevenueCat REST API v2 lives at `https://api.revenuecat.com/v2`. It uses Bearer v2 secret
keys with per-endpoint permissions, set in the project settings ([revenuecat.com/docs/api-v2](https://www.revenuecat.com/docs/api-v2)).
It covers:
- Apps.
- Products: `/projects/{project_id}/products`.
- Entitlements, with `.../entitlements/{entitlement_id}/actions/attach_products`.
- Offerings and Packages.
So the RevenueCat catalog can be created and kept in sync by API.
**What storebound already replaces.** The store-side catalog: one product and subscription list in the config,
created and priced on both stores (`play products / subscriptions`, `apple iap / subscriptions`, the regional price
CSV), with cross-store parity (`catalog diff`). Teams that use RevenueCat only as a way to "set up the products"
don't need it for that.
**What storebound cannot replace.**
- Runtime receipt and purchase-token validation.
- Entitlement state per user, server notifications (App Store Server Notifications, Play RTDN).
- Renewals, grace periods, refunds, customer history, paywall experiments and charts.
- The client SDKs.
All of that runs on a server, against live users. It is outside a release tool, and storebound should not try.
**What an optional adapter could do:** `storebound revenuecat sync [--dry]`.
- Key: `REVENUECAT_API_KEY` (v2 secret) and project id, from the environment or `.storebound/` only.
- Source of truth: the storebound catalog. For every config product or subscription id and each store:
1. Create the RevenueCat product (store identifier, app id, type).
2. Create the entitlements named in a new optional config field (`products[].entitlements: ['pro']`) and attach
the products.
3. Optionally create one default offering whose packages map to the subscriptions (`$rc_monthly` / `$rc_annual`
by period).
- Idempotent: match by store identifier. A dry-run diff comes first, as with every storebound write. Nothing is
deleted.
- Read-only parity: show "missing in RevenueCat" in `catalog diff` and in the desktop Catalog tab.
**Recommendation.** Build the fastlane importer first: it is the migration path and the bigger win.
Make RevenueCat a small, optional adapter later, scoped to catalog sync (products, entitlements, a default offering)
plus parity in `catalog diff`. Market it as "keep RevenueCat in step with the stores", not as a replacement:
- storebound owns the store-side catalog and the release.
- RevenueCat (or the app's own server) owns runtime entitlements.
Do not add webhooks, customers or any runtime data, so storebound stays a local tool with no server and no user data.