storemeta 0.1.0

package/docs/RELEASE_VERIFICATION.md

@@ -0,0 +1,70 @@
+# Release Verification
+
+This project includes a local verification script and templates for final release checks.
+
+## Local Verification
+
+Run checks that do not require Apple or Google credentials:
+
+```bash
+npm run verify:release
+```
+
+This runs:
+
+- TypeScript check
+- test suite
+- build
+- `npm pack --dry-run`
+
+## Real Store Verification
+
+Create local files from the templates:
+
+```bash
+cp storemeta.release.example.yml storemeta.release.yml
+cp .env.release.example .env.release.local
+```
+
+Fill these values in `storemeta.release.yml`:
+
+- Apple `appId`
+- Google `packageName`
+- target locale list
+
+Fill these values in `.env.release.local`:
+
+- `STORE_APPLE_ISSUER_ID`
+- `STORE_APPLE_KEY_ID`
+- `STORE_APPLE_PRIVATE_KEY_PATH`
+- `STORE_GOOGLE_SERVICE_ACCOUNT_PATH`
+
+Run all real-store checks:
+
+```bash
+npm run verify:release -- --real-store
+```
+
+Run only one platform:
+
+```bash
+npm run verify:release -- --real-store --platform apple
+npm run verify:release -- --real-store --platform google
+```
+
+Run one platform and one locale:
+
+```bash
+npm run verify:release -- --real-store --platform apple --locale tr
+npm run verify:release -- --real-store --platform google --locale tr-TR
+```
+
+The real-store mode runs:
+
+- `storemeta validate`
+- metadata pull
+- metadata push with `--dry-run`
+- screenshots pull
+- screenshots push with `--dry-run`
+
+Do not commit `storemeta.release.yml` or `.env.release.local` if they contain real app identifiers or credential paths.

package/docs/TODO.md

@@ -0,0 +1,308 @@
+# TODO
+
+This file is the implementation checklist for `storemeta`, ordered to minimize rework and unblock end-to-end development as early as possible.
+
+## 0. Security And Repo Hygiene
+
+- [ ] Rotate any previously used Apple and Google credentials before anything public is pushed.
+- [x] Ensure `reference/` stays ignored and is never added to Git history.
+- [x] Add any additional local-only secret paths to `.gitignore` if needed.
+- [x] Confirm the repo contains no machine-specific paths or private metadata.
+
+## 1. Project Scaffold
+
+- [x] Create `package.json`.
+- [x] Set package name to `storemeta`.
+- [x] Set the CLI binary name to `storemeta` via the `bin` field.
+- [x] Add `type`, `engines`, `files`, `scripts`, and initial metadata to `package.json`.
+- [x] Create `tsconfig.json`.
+- [x] Create the initial source tree under `src/`.
+- [x] Add a build output target such as `dist/`.
+- [x] Add a minimal `.npmignore` or rely on `package.json` `files`.
+- [x] Add a basic `CONTRIBUTING.md`.
+
+## 2. Tooling And Dependency Setup
+
+- [x] Choose the CLI framework or parser.
+- [x] Add TypeScript runtime and build dependencies.
+- [x] Add a YAML parser.
+- [x] Add an HTTP client strategy.
+- [x] Add a schema validation library for config and metadata validation.
+- [x] Add test tooling.
+- [ ] Add linting and formatting tooling if desired.
+
+## 3. Source Structure
+
+- [x] Create `src/cli/`.
+- [x] Create `src/config/`.
+- [x] Create `src/formats/`.
+- [x] Create `src/locales/`.
+- [x] Create `src/writers/`.
+- [x] Create `src/validation/`.
+- [x] Create `src/auth/apple/`.
+- [x] Create `src/auth/google/`.
+- [x] Create `src/platforms/apple/metadata/`.
+- [x] Create `src/platforms/apple/screenshots/`.
+- [x] Create `src/platforms/google/metadata/`.
+- [x] Create `src/platforms/google/screenshots/`.
+
+## 4. Core Domain Types
+
+- [x] Define shared config types.
+- [x] Define shared metadata document types.
+- [x] Define Apple metadata mapping types.
+- [x] Define Google metadata mapping types.
+- [x] Define screenshot descriptor types.
+- [x] Define locale mapping and grouping types.
+- [x] Define command result and summary types.
+- [x] Define reusable error types.
+
+## 5. Config System
+
+- [x] Implement loading for `storemeta.yml`.
+- [x] Support `--config <path>`.
+- [x] Implement schema validation for the root config.
+- [x] Support single-app usage cleanly.
+- [x] Support multi-app config structure even if only one app is used initially.
+- [x] Implement app selection logic via `project.defaultApp` and `--app`.
+- [x] Validate required platform identifiers.
+- [x] Validate configured credential env var names.
+- [x] Validate base directory paths.
+
+## 6. Credential Loading
+
+- [x] Implement Apple credential loading from environment variables.
+- [x] Implement Google credential loading from environment variables.
+- [x] Validate missing credential cases with clear errors.
+- [x] Ensure secrets never appear in logs.
+- [x] Add helpers for resolved credential state without exposing secret values.
+
+## 7. Metadata File Parsing
+
+- [x] Implement YAML parsing for `.yml`.
+- [x] Implement YAML parsing for `.yaml`.
+- [x] Implement YAML parsing for `.md` file contents.
+- [x] Add deterministic serialization for pulled metadata files.
+- [x] Preserve stable key ordering in written files.
+- [x] Add platform-aware schema validation for Apple metadata documents.
+- [x] Add platform-aware schema validation for Google metadata documents.
+
+## 8. Locale System
+
+- [x] Implement locale normalization utilities.
+- [x] Implement explicit per-platform locale mapping support.
+- [x] Implement screenshot grouping support from config.
+- [x] Validate that locale groups resolve deterministically.
+- [x] Add tests for locale edge cases such as `zh-Hans`, `zh-Hant`, `he-IL`, and grouped English locales.
+
+## 9. Deterministic File Writers
+
+- [x] Implement metadata file writing helpers.
+- [x] Implement screenshot path resolution helpers.
+- [x] Implement deterministic screenshot filename ordering.
+- [x] Ensure directories are created safely as needed.
+- [x] Prevent accidental writes outside configured base directories.
+
+## 10. CLI Shell
+
+- [x] Implement the `storemeta` entry point.
+- [x] Implement global option parsing.
+- [x] Implement shared command context creation.
+- [x] Implement shared summary and error rendering.
+- [x] Implement `--verbose`.
+- [x] Implement non-zero exit behavior for failures.
+
+## 11. `storemeta init`
+
+- [x] Implement starter config generation for `storemeta.yml`.
+- [x] Generate example metadata directories.
+- [x] Generate example screenshot directories.
+- [x] Avoid overwriting existing files by default.
+- [x] Use fake values only in generated examples.
+
+## 12. `storemeta validate`
+
+- [x] Validate root config structure.
+- [x] Validate selected app and platform targets.
+- [x] Validate credential presence.
+- [x] Validate metadata files and schema.
+- [x] Validate metadata length constraints for Google Play.
+- [x] Validate screenshot folder structure.
+- [x] Validate supported screenshot file extensions.
+- [x] Validate numeric screenshot ordering.
+- [x] Print a clear validation summary.
+
+## 13. Google Platform Client
+
+- [x] Implement service account authentication.
+- [x] Implement a shared Google Play API client wrapper.
+- [x] Implement edit session creation.
+- [x] Implement edit session commit.
+- [x] Implement safe edit session lifecycle handling for failures.
+
+## 14. Google Metadata Pull
+
+- [x] Implement listing fetch for one locale.
+- [x] Implement listing fetch for all target locales.
+- [x] Normalize remote listing data into the local metadata schema.
+- [x] Write one file per locale.
+- [x] Support `--locale`.
+- [x] Support `--platform google`.
+
+## 15. Google Metadata Push
+
+- [x] Load and validate local Google metadata files.
+- [x] Map local metadata into Google API payloads.
+- [x] Upload listing text through an edit session.
+- [x] Support `--dry-run`.
+- [x] Print per-locale progress and final results.
+
+## 16. Google Screenshots Pull
+
+- [x] Implement image listing for configured locales and image types.
+- [x] Download remote screenshots into the canonical local directory layout.
+- [x] Write deterministic filenames such as `1.png`, `2.png`, `3.png`.
+- [x] Support configured screenshot groups where relevant.
+- [x] Handle empty sets cleanly.
+
+## 17. Google Screenshots Push
+
+- [x] Load and validate local screenshot sets.
+- [x] Map local screenshots to target locales and image types.
+- [x] Implement optional clearing of existing screenshots before upload.
+- [x] Upload screenshots through the Google edit session.
+- [x] Support `--dry-run`.
+- [x] Print per-locale and per-image-type progress.
+
+## 18. Apple Platform Client
+
+- [x] Implement JWT generation from Apple credentials.
+- [x] Implement a shared App Store Connect API client.
+- [x] Implement paginated GET helpers where needed.
+- [x] Implement safe POST and PATCH wrappers.
+- [x] Ensure auth and API errors are rendered clearly without leaking secrets.
+
+## 19. Apple Metadata Pull
+
+- [x] Fetch app info localizations.
+- [x] Fetch app store version localizations.
+- [x] Join the two localization models into one local metadata document per locale.
+- [x] Normalize fields into the local Apple metadata schema.
+- [x] Write one file per locale.
+- [x] Support `--locale`.
+
+## 20. Apple Metadata Push
+
+- [x] Load and validate local Apple metadata files.
+- [x] Resolve the target app info resource.
+- [x] Resolve the target editable app store version resource.
+- [x] Update existing app info localizations.
+- [x] Create missing app info localizations when allowed.
+- [x] Update existing app store version localizations.
+- [x] Create missing app store version localizations when allowed.
+- [x] Support `--dry-run`.
+- [x] Print per-locale progress and final results.
+
+## 21. Apple Screenshots Pull
+
+- [x] Fetch localization resources for the target version.
+- [x] Fetch screenshot sets per localization.
+- [x] Fetch screenshots within each set.
+- [x] Download screenshot binaries into the canonical local directory layout.
+- [x] Preserve deterministic ordering.
+- [x] Support locale filtering.
+
+## 22. Apple Screenshots Push
+
+- [x] Load and validate local screenshot sets.
+- [x] Resolve or create required localizations.
+- [x] Resolve or create screenshot sets by display type.
+- [x] Delete existing screenshots when replacement behavior is selected.
+- [x] Reserve upload slots.
+- [x] Upload binaries to Apple-provided URLs.
+- [x] Commit uploads with checksums.
+- [x] Support `--dry-run`.
+- [x] Print per-locale and per-display-type progress.
+
+## 23. Shared Error Handling And UX
+
+- [x] Define consistent error messages for config, auth, validation, API, and filesystem failures.
+- [x] Standardize command headers and summaries.
+- [ ] Add true partial-failure aggregation for multi-target command summaries.
+- [x] Make destructive behavior explicit in command output.
+
+## 24. Fixtures And Sample Project
+
+- [x] Add a fake example `storemeta.yml`.
+- [x] Add fake sample metadata files for Apple and Google.
+- [x] Add fake sample screenshot directories.
+- [x] Ensure all examples are safe to publish.
+
+## 25. Automated Tests
+
+- [x] Add unit tests for config loading and validation.
+- [x] Add unit tests for metadata parsing and serialization.
+- [x] Add unit tests for locale normalization and grouping.
+- [x] Add unit tests for screenshot ordering and path resolution.
+- [x] Add unit tests for Apple metadata mapping.
+- [x] Add unit tests for Google metadata mapping.
+- [x] Add tests for dry-run behavior.
+- [x] Add command-level smoke tests.
+- [x] Add mocked API tests for Apple flows.
+- [x] Add mocked API tests for Google flows.
+
+## 26. Documentation Completion
+
+- [x] Update `README.md` with install and usage examples once the CLI exists.
+- [x] Add command examples for each implemented command.
+- [x] Add config examples that match the real implementation.
+- [x] Add troubleshooting guidance for Apple and Google auth setup.
+- [x] Add contributor setup instructions.
+- [x] Add dedicated auth setup documentation for Apple and Google credentials.
+
+## 26.1 Product Polish Commands
+
+- [x] Add `storemeta auth check`.
+- [x] Add `storemeta config doctor`.
+- [x] Add `storemeta locales list`.
+- [x] Add `storemeta metadata diff`.
+- [x] Add `storemeta screenshots diff`.
+- [x] Add `storemeta scaffold`.
+- [x] Print next-step auth guidance after `storemeta init`.
+
+## 27. npm Packaging
+
+- [x] Confirm the published package metadata is correct.
+- [x] Confirm only intended files are included in the npm package.
+- [x] Verify `npm pack` contents locally.
+- [x] Verify the generated CLI works from the packed tarball.
+- [x] Set initial version for the first release.
+
+## 28. Pre-Release Verification
+
+- [x] Run `storemeta init` in a clean temp directory.
+- [x] Run `storemeta validate` against the generated sample project.
+- [x] Add release verification config and environment templates.
+- [x] Add release verification script for local and real-store checks.
+- [x] Verify Apple metadata pull with a real test app.
+- [x] Verify Apple metadata push with `--dry-run` against a real test app.
+- [x] Verify Apple screenshots pull with a real test app.
+- [x] Verify Apple screenshots push with `--dry-run` against a real test app.
+- [x] Verify Google metadata pull with a real test app.
+- [x] Verify Google metadata push with `--dry-run` against a real test app.
+- [x] Verify Google screenshots pull with a real test app.
+- [x] Verify Google screenshots push with `--dry-run` against a real test app.
+- [x] Verify packed tarball install in a clean temp project.
+- [x] Verify `storemeta --help`, `storemeta init`, and `storemeta validate` from the packed install.
+- [x] Audit logs, examples, package contents, and docs for secrets.
+- [x] Audit git history for secrets before public push.
+- [x] Decide whether partial validation summary aggregation is required before first release: defer until after initial release.
+- [x] Decide whether lint and formatting tooling is required before first release: defer until after initial release.
+
+## 29. First Public Release
+
+- [x] Commit the implementation.
+- [x] Push to GitHub.
+- [ ] Publish the initial npm package.
+- [ ] Tag the release.
+- [x] Confirm the public repository contains no ignored or secret material.

package/examples/README.md

@@ -0,0 +1,8 @@
+# Examples
+
+Everything in this directory is fake and safe to publish.
+
+- App IDs, package names, URLs, and environment variable names are placeholders.
+- Screenshot files are text placeholders with image file extensions. They only demonstrate directory layout.
+- Do not upload these files to App Store Connect or Google Play.
+- Do not store real credentials or production metadata in this directory.

package/examples/metadata/apple/en-US.yml

@@ -0,0 +1,11 @@
+locale: en-US
+app_name: Storemeta Example
+subtitle: Localize store listings safely
+privacy_policy_url: https://example.com/privacy
+description: |
+  Storemeta Example shows how localized App Store metadata can live in YAML files.
+keywords: metadata, screenshots, localization
+marketing_url: https://example.com
+promotional_text: Sync App Store metadata from your repository.
+support_url: https://example.com/support
+whats_new: Added example App Store metadata.

package/examples/metadata/apple/tr.yml

@@ -0,0 +1,11 @@
+locale: tr
+app_name: Storemeta Ornek
+subtitle: Magaza metinlerini guvenli yonetin
+privacy_policy_url: https://example.com/privacy
+description: |
+  Storemeta Ornek, App Store metinlerinin YAML dosyalarinda nasil tutuldugunu gosterir.
+keywords: metadata, ekran goruntusu, yerlestirme
+marketing_url: https://example.com
+promotional_text: App Store metinlerini depodan esitleyin.
+support_url: https://example.com/support
+whats_new: Ornek App Store metinleri eklendi.

package/examples/metadata/google/en-US.yml

@@ -0,0 +1,6 @@
+locale: en-US
+title: Storemeta Example
+short_description: Sync mobile store listings from YAML.
+full_description: |
+  Storemeta Example shows how Google Play listing metadata can live in repository files.
+video: https://example.com/video

package/examples/metadata/google/tr.yml

@@ -0,0 +1,6 @@
+locale: tr
+title: Storemeta Ornek
+short_description: Mobil magaza metinlerini YAML ile yonetin.
+full_description: |
+  Storemeta Ornek, Google Play metinlerinin depoda nasil saklanabilecegini gosterir.
+video: https://example.com/video

package/examples/screenshots/apple/en-US/APP_IPHONE_65/1.png

@@ -0,0 +1 @@
+placeholder apple screenshot

package/examples/screenshots/apple/tr/APP_IPHONE_65/1.png

@@ -0,0 +1 @@
+placeholder apple screenshot

package/examples/screenshots/google/en-US/phoneScreenshots/1.png

@@ -0,0 +1 @@
+placeholder google screenshot

package/examples/screenshots/google/tr/phoneScreenshots/1.png

@@ -0,0 +1 @@
+placeholder google screenshot

package/examples/storemeta.yml

@@ -0,0 +1,29 @@
+version: 1
+project:
+  name: Storemeta Example
+  defaultApp: example-app
+apps:
+  example-app:
+    metadata:
+      baseDir: metadata
+      format: yaml
+    screenshots:
+      baseDir: screenshots
+    apple:
+      appId: "0000000000"
+      credentials:
+        issuerIdEnv: APPLE_ISSUER_ID
+        keyIdEnv: APPLE_KEY_ID
+        privateKeyPathEnv: APPLE_PRIVATE_KEY_PATH
+      locales:
+        default:
+          - en-US
+          - tr
+    google:
+      packageName: com.example.storemeta
+      credentials:
+        serviceAccountPathEnv: GOOGLE_SERVICE_ACCOUNT_PATH
+      locales:
+        default:
+          - en-US
+          - tr

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "storemeta",
+  "version": "0.1.0",
+  "description": "CLI for pulling, validating, and pushing App Store Connect and Google Play metadata and screenshots.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "storemeta": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    ".env.release.example",
+    "storemeta.release.example.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node ./scripts/build.mjs",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "verify:release": "node ./scripts/verify-release.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sezaienesyildizhan/storemeta.git"
+  },
+  "homepage": "https://github.com/sezaienesyildizhan/storemeta#readme",
+  "bugs": {
+    "url": "https://github.com/sezaienesyildizhan/storemeta/issues"
+  },
+  "keywords": [
+    "cli",
+    "app-store-connect",
+    "google-play",
+    "metadata",
+    "screenshots"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "google-auth-library": "^10.6.2",
+    "jose": "^6.2.2",
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
+  }
+}

package/storemeta.release.example.yml

@@ -0,0 +1,27 @@
+version: 1
+project:
+  name: Storemeta Release Verification
+  defaultApp: release-app
+apps:
+  release-app:
+    metadata:
+      baseDir: metadata
+      format: yaml
+    screenshots:
+      baseDir: screenshots
+    apple:
+      appId: "YOUR_APP_STORE_CONNECT_APP_ID"
+      credentials:
+        issuerIdEnv: STORE_APPLE_ISSUER_ID
+        keyIdEnv: STORE_APPLE_KEY_ID
+        privateKeyPathEnv: STORE_APPLE_PRIVATE_KEY_PATH
+      locales:
+        default:
+          - en-US
+    google:
+      packageName: com.example.yourapp
+      credentials:
+        serviceAccountPathEnv: STORE_GOOGLE_SERVICE_ACCOUNT_PATH
+      locales:
+        default:
+          - en-US