[GH-ISSUE #587] epic(metadata): fastlane-parity metadata workflows in asc style + migration path #162

New issue

Closed

opened 2026-02-26 21:33:50 +03:00 by kerem · 0 comments

kerem commented

2026-02-26 21:33:50 +03:00

Owner

Originally created by @rudrankriyam on GitHub (Feb 17, 2026).
Original GitHub issue: https://github.com/rudrankriyam/App-Store-Connect-CLI/issues/587

Originally assigned to: @rudrankriyam on GitHub.

Epic Summary

Build fastlane-deliver-level metadata workflow parity in asc style:

explicit flags
JSON-first outputs
deterministic plans
non-interactive/safe mutations

This epic turns metadata sync into a complete workflow:

pull from App Store Connect into git,
edit locally,
validate offline,
preview exact changes (--dry-run),
apply changes safely,
migrate teams already using fastlane.

Existing Support (already in repo)

We already support fastlane migration primitives today:

asc migrate import
asc migrate export
asc migrate validate

This epic keeps migrate stable while introducing metadata-first UX and parity behaviors.

Target CLI Surface

Core metadata workflow

asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata"
asc metadata validate --dir "./metadata"
asc metadata push --app "APP_ID" --version "1.2.3" --dir "./metadata" --dry-run
asc metadata push --app "APP_ID" --version "1.2.3" --dir "./metadata"

Migration-first UX (for existing fastlane users)

asc migrate import --app "APP_ID" --version-id "VERSION_ID" --fastlane-dir ./fastlane
asc migrate export --app "APP_ID" --version-id "VERSION_ID" --output-dir ./fastlane
asc migrate validate --fastlane-dir ./fastlane

# metadata-first compatibility aliases (planned)
asc metadata import --from fastlane --dir ./fastlane
asc metadata export --to fastlane --dir ./fastlane

Canonical Metadata Layout (phase-1)

metadata/app-info/<locale>.json
metadata/version/<version>/<locale>.json

Phase-1 fields:

Version: description, keywords, marketingUrl, promotionalText, supportUrl, whatsNew
App-info: name, subtitle, privacyPolicyUrl, privacyChoicesUrl, privacyPolicyText

Execution Plan (acts as plan.md)

Workstreams / Issues

#687 — Foundation: canonical schema, strict decoding, deterministic/safe file I/O
#688 — metadata pull with deterministic git-safe output
#689 — metadata validate with strict schema + limits
#690 — metadata push --dry-run deterministic plan artifact
#691 — metadata push apply mode (create/update/delete + guardrails)
#692 — fastlane parity behaviors in asc style
#693 — migration UX for existing fastlane users

Phase Order

Phase 0: Foundation (#687)
Phase 1: Read/validate path (#688, #689)
Phase 2: Plan path (#690)
Phase 3: Apply path (#691)
Phase 4: Parity behavior gaps (#692)
Phase 5: Migration UX polish (#693)

Engineering Guardrails

Unknown keys must fail fast (usage error, exit code 2)
Deterministic output ordering for CI artifacts
No interactive prompts; destructive operations require explicit flags
Reuse shared safe file operations (symlink protections, safe overwrite)
Planner/apply must share one source of truth to avoid drift
Respect request timeout behavior (ASC_TIMEOUT)

Test Strategy (TDD-first)

Cmdtests for all flags/exit-code behavior and output formats
Determinism tests for file output and dry-run plan JSON
HTTP fixture tests for remote state resolution and mutations
Validation tests for schema, required fields, and length limits
Migration compatibility tests with representative fastlane directory fixtures

Open Decisions (must resolve before apply parity is “done”)

Delete semantics policy:
- field clear vs locale delete vs both
- destructive gating flags (--allow-deletes, --confirm)
--version resolution semantics:
- if version string is ambiguous, require explicit platform/ID
Default locale behavior parity:
- how fastlane default maps into canonical asc model

Done Criteria (Epic)

asc metadata pull/push/validate are self-documenting and stable
push --dry-run emits deterministic CI-suitable plan artifact
Apply mode is safe, explicit, and idempotent
Fastlane migration path is clear, documented, and tested
Existing migrate behavior remains functional and documented
make format, make lint, and ASC_BYPASS_KEYCHAIN=1 make test pass for all landed work

Originally created by @rudrankriyam on GitHub (Feb 17, 2026). Original GitHub issue: https://github.com/rudrankriyam/App-Store-Connect-CLI/issues/587 Originally assigned to: @rudrankriyam on GitHub. ## Epic Summary Build fastlane-deliver-level metadata workflow parity in **asc style**: - explicit flags - JSON-first outputs - deterministic plans - non-interactive/safe mutations This epic turns metadata sync into a complete workflow: 1) pull from App Store Connect into git, 2) edit locally, 3) validate offline, 4) preview exact changes (`--dry-run`), 5) apply changes safely, 6) migrate teams already using fastlane. ## Existing Support (already in repo) We already support fastlane migration primitives today: - `asc migrate import` - `asc migrate export` - `asc migrate validate` This epic keeps `migrate` stable while introducing metadata-first UX and parity behaviors. ## Target CLI Surface ### Core metadata workflow ```bash asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata" asc metadata validate --dir "./metadata" asc metadata push --app "APP_ID" --version "1.2.3" --dir "./metadata" --dry-run asc metadata push --app "APP_ID" --version "1.2.3" --dir "./metadata" ``` ### Migration-first UX (for existing fastlane users) ```bash asc migrate import --app "APP_ID" --version-id "VERSION_ID" --fastlane-dir ./fastlane asc migrate export --app "APP_ID" --version-id "VERSION_ID" --output-dir ./fastlane asc migrate validate --fastlane-dir ./fastlane # metadata-first compatibility aliases (planned) asc metadata import --from fastlane --dir ./fastlane asc metadata export --to fastlane --dir ./fastlane ``` ## Canonical Metadata Layout (phase-1) - `metadata/app-info/<locale>.json` - `metadata/version/<version>/<locale>.json` Phase-1 fields: - Version: `description`, `keywords`, `marketingUrl`, `promotionalText`, `supportUrl`, `whatsNew` - App-info: `name`, `subtitle`, `privacyPolicyUrl`, `privacyChoicesUrl`, `privacyPolicyText` ## Execution Plan (acts as plan.md) ### Workstreams / Issues - [ ] #687 — Foundation: canonical schema, strict decoding, deterministic/safe file I/O - [ ] #688 — `metadata pull` with deterministic git-safe output - [ ] #689 — `metadata validate` with strict schema + limits - [ ] #690 — `metadata push --dry-run` deterministic plan artifact - [ ] #691 — `metadata push` apply mode (create/update/delete + guardrails) - [ ] #692 — fastlane parity behaviors in asc style - [ ] #693 — migration UX for existing fastlane users ### Phase Order - **Phase 0**: Foundation (`#687`) - **Phase 1**: Read/validate path (`#688`, `#689`) - **Phase 2**: Plan path (`#690`) - **Phase 3**: Apply path (`#691`) - **Phase 4**: Parity behavior gaps (`#692`) - **Phase 5**: Migration UX polish (`#693`) ## Engineering Guardrails - Unknown keys must fail fast (usage error, exit code `2`) - Deterministic output ordering for CI artifacts - No interactive prompts; destructive operations require explicit flags - Reuse shared safe file operations (symlink protections, safe overwrite) - Planner/apply must share one source of truth to avoid drift - Respect request timeout behavior (`ASC_TIMEOUT`) ## Test Strategy (TDD-first) - Cmdtests for all flags/exit-code behavior and output formats - Determinism tests for file output and dry-run plan JSON - HTTP fixture tests for remote state resolution and mutations - Validation tests for schema, required fields, and length limits - Migration compatibility tests with representative fastlane directory fixtures ## Open Decisions (must resolve before apply parity is “done”) - Delete semantics policy: - field clear vs locale delete vs both - destructive gating flags (`--allow-deletes`, `--confirm`) - `--version` resolution semantics: - if version string is ambiguous, require explicit platform/ID - Default locale behavior parity: - how fastlane `default` maps into canonical asc model ## Done Criteria (Epic) - [ ] `asc metadata pull/push/validate` are self-documenting and stable - [ ] `push --dry-run` emits deterministic CI-suitable plan artifact - [ ] Apply mode is safe, explicit, and idempotent - [ ] Fastlane migration path is clear, documented, and tested - [ ] Existing `migrate` behavior remains functional and documented - [ ] `make format`, `make lint`, and `ASC_BYPASS_KEYCHAIN=1 make test` pass for all landed work