@meadow-studio/platform 0.0.0-stage → 0.1.0

package/docs/PROJECT_BRIEF.md

@@ -0,0 +1,501 @@
+# Meadow Platform — Project Brief
+
+## Purpose
+
+Meadow Platform is a private internal platform for building, shipping, and maintaining a growing portfolio of small mobile apps.
+
+There are already 15+ planned apps, and more are expected over time.
+
+The motivation comes primarily from building Stay Light. Developing the core product was only part of the work required to make the app release-ready. A significant amount of time was spent repeatedly solving infrastructure and release problems such as:
+
+- RevenueCat integration
+- Analytics
+- Native iOS/Android configuration
+- App Store and Google Play configuration
+- Privacy and GDPR considerations
+- Store metadata
+- Screenshots and marketing assets
+- Build configuration
+- Testing
+- Release preparation
+
+Meadow Platform exists to make this work reusable, standardized, and increasingly automated.
+
+The core principle is:
+
+> Never solve the same generic app infrastructure problem twice.
+
+## Overall Architecture
+
+Apps may conceptually use three layers:
+
+```text
+Meadow Design
+    ↓
+Meadow Platform
+    ↓
+Individual App
+```
+
+Or:
+
+```text
+Meadow Design   → How apps look
+Meadow Platform → How apps work and get shipped
+App          → The unique product/domain logic
+```
+
+Meadow Design and Meadow Platform are separate concerns.
+
+Meadow Design is an optional reusable design system. It is not part of the generated platform
+foundation, and applications such as 24h Pushups can own a completely different visual language.
+
+Meadow Platform provides reusable application infrastructure, integrations, configuration, tooling,
+and release guardrails, with further automation added only when real release work proves its value.
+
+Individual apps should contain as little generic infrastructure as reasonably possible.
+
+## Repository Strategy
+
+Meadow Platform and Meadow Design live as independent projects in the same private repository. They
+have separate package manifests, builds, tests, and ownership boundaries. Meadow Design remains
+optional for every application; the platform does not depend on it.
+
+Individual apps live in their own repositories. Each repository keeps the mobile app at its root
+and a separate, app-owned `website/` project for its public app reference, support, and legal pages.
+This keeps the app and site together for review and release work without making the website a
+platform runtime dependency. A planned base domain can give each app a subdomain; hosting and domain
+ownership remain outside the CLI.
+
+Example:
+
+```text
+meadow-platform/
+  platform/
+  design/
+
+stay-light/
+24h-pushups/
+media-archive/
+swipe-for-dinner/
+...
+```
+
+Meadow Platform should initially be distributed as ONE dependency:
+
+```text
+@meadow-studio/platform
+```
+
+Do NOT prematurely split the platform into many packages such as:
+
+```text
+@meadow/analytics
+@meadow/purchases
+@meadow/privacy
+@meadow/storage
+```
+
+Internal modularization is encouraged, but externally the platform should remain one dependency until there is a concrete reason to split it.
+
+This keeps dependency management and versioning simple across many apps.
+
+## Privacy / Ownership
+
+`@meadow-studio/platform` is a public npm package so new app repositories can install it and run CI
+without per-repository credentials. The source repository may remain private, but everything in
+the published package can be downloaded and inspected. Applications pin exact npm versions.
+
+Secrets must NEVER be included in Meadow Platform.
+
+Examples:
+
+- RevenueCat credentials
+- Firebase credentials/secrets
+- App Store credentials
+- Google Play credentials
+- Signing credentials
+
+App/environment-specific configuration must be supplied externally.
+
+## Versioning
+
+Meadow Platform is versioned independently from applications.
+
+Example:
+
+```text
+@meadow-studio/platform 0.1.0
+```
+
+Applications should be able to stay on known working platform versions and upgrade intentionally.
+
+During early development, prefer explicit/pinned versions rather than automatically accepting platform upgrades.
+
+Use semantic versioning:
+
+```text
+PATCH → backwards-compatible bug fix
+MINOR → backwards-compatible functionality
+MAJOR → breaking platform API change
+```
+
+The platform should maintain a deliberately small public API.
+
+Avoid exposing implementation details of third-party services.
+
+For example, applications should ideally use:
+
+```ts
+purchases.isPremium();
+```
+
+rather than directly depending on:
+
+```ts
+RevenueCatCustomerInfo.entitlements.active[...]
+```
+
+Similarly:
+
+```ts
+analytics.track('challenge_created');
+```
+
+rather than importing and using Firebase throughout application code.
+
+This allows underlying providers to change without requiring large migrations across every app.
+
+## Technology Context
+
+The current shared app foundation uses:
+
+- Angular 22
+- Capacitor 8
+- TypeScript
+- Firebase Analytics and Crashlytics
+
+Ionic and Meadow Design are app-owned choices, not Meadow Platform dependencies.
+
+Stay Light is the first major reference application.
+
+24h Pushups is the first POC consumer of Meadow Platform.
+
+## Development Philosophy
+
+Do NOT attempt to design the entire platform upfront.
+
+Meadow Platform should grow organically from actual repeated needs discovered while building applications.
+
+The intended progression is:
+
+```text
+Stay Light
+    ↓
+Extract proven generic patterns
+    ↓
+Meadow Platform v0.1
+    ↓
+24h Pushups
+    ↓
+Discover repeated infrastructure/problems
+    ↓
+Meadow Platform v0.2
+    ↓
+App #3
+    ↓
+Meadow Platform v0.3
+    ↓
+...
+    ↓
+15+ apps
+```
+
+Stay Light acts as a donor/reference implementation.
+
+Do not blindly copy Stay Light architecture into Meadow Platform.
+
+Whenever code is considered for extraction, ask:
+
+> Is this genuinely generic application infrastructure, or is this Stay Light-specific product logic?
+
+Only generic concerns belong in Meadow Platform.
+
+## Original MVP
+
+This section records the intentionally small v0.1 boundary that established the package before the
+current CLI foundation existed. See [PLATFORM_GUIDE.md](PLATFORM_GUIDE.md) for current capabilities.
+
+The first goal is NOT:
+
+> Automate everything required to ship an app.
+
+The first goal is:
+
+> Prove that the second app can reuse infrastructure instead of rebuilding it.
+
+Initial candidates include:
+
+### App configuration
+
+Provide a typed central configuration mechanism.
+
+Conceptually:
+
+```ts
+provideMeadowPlatform({
+  app: {
+    name: '24h Pushups',
+    supportEmail: '...',
+    privacyUrl: '...'
+  },
+
+  analytics: {
+    enabled: true
+  },
+
+  purchases: {
+    enabled: true,
+    entitlement: 'premium'
+  }
+});
+```
+
+Exact APIs are not finalized.
+
+Do not treat examples in this document as immutable API requirements.
+
+### Analytics
+
+Extract/generalize the proven analytics approach from Stay Light.
+
+Applications should interact with a Meadow abstraction rather than Firebase directly.
+
+Conceptually:
+
+```ts
+analytics.track('challenge_created');
+```
+
+The implementation may initially use Firebase.
+
+### Purchases
+
+Generalize the RevenueCat integration proven in Stay Light.
+
+Meadow Platform should eventually encapsulate concerns such as:
+
+- initialization
+- entitlement state
+- premium state
+- purchases
+- restore purchases
+- customer info
+- errors
+- synchronization
+
+Applications should not need intimate knowledge of RevenueCat APIs.
+
+Conceptually:
+
+```ts
+purchases.isPremium();
+purchases.purchase(...);
+purchases.restore();
+```
+
+Do not prematurely move application-specific premium UI into the platform.
+
+Meadow Design/application code can remain responsible for UI until a genuinely reusable pattern emerges.
+
+### App Information
+
+Provide simple generic access to information such as:
+
+- application version
+- build number
+- platform
+
+This can later be used by About pages, diagnostics, feedback, etc.
+
+### Environment / Configuration
+
+Establish a consistent mechanism for supplying app-specific and environment-specific configuration.
+
+Meadow Platform itself must not contain application secrets.
+
+## Explicitly NOT v0.1
+
+This section records the original v0.1 boundary. The create-app CLI, screenshot automation, and
+release checks were later explicitly requested and are implemented as the v0.2 tooling direction.
+
+The create-app CLI, screenshot testing, and release checks were later implemented after explicit
+product requirements established their value.
+
+The following remain outside the current platform unless real app work proves the need:
+
+- App Store upload automation
+- Google Play upload automation
+- privacy policy generator
+- GDPR generator
+- Supabase abstraction
+- storage abstraction
+- feedback backend
+- feature flag framework
+- release dashboard
+- complex plugin architecture
+
+These should only be introduced when actual application development demonstrates the need.
+
+Avoid platform-building for hypothetical future requirements.
+
+## Current and future tooling direction
+
+Meadow Platform has expanded beyond runtime infrastructure into developer tooling. The current entry
+points are:
+
+```text
+meadow new media-archive
+meadow init
+```
+
+The developer can create a complete foundation or conservatively add the Meadow control plane to a
+supported existing app. Core app metadata, devices, RevenueCat and Supabase setup can be configured,
+and local data or local notifications can be added after creation. A generated repository includes Angular, Capacitor,
+Firebase dependencies, native projects, tests, screenshot comparison, CI, and release guardrails.
+
+Additional proven capability recipes may eventually include cloud sync or other
+infrastructure that appears repeatedly across real applications.
+
+The result is a release-oriented starting point rather than a blank application. Further tooling
+should be added only when real app work demonstrates that it removes repeated effort.
+
+## Release automation direction
+
+One of the largest goals remains reducing the work between:
+
+```text
+"The product works"
+```
+
+and:
+
+```text
+"The product is released."
+```
+
+The current release gate is:
+
+```text
+meadow release-check
+```
+
+It currently combines configuration diagnostics with formatting, linting, unit tests, production
+web builds, screenshot comparisons, and selected native builds. Generated app CI runs the same
+categories on pull requests.
+
+The generated release checklist and configuration also cover:
+
+- successful production builds
+- application icons
+- splash assets
+- bundle/application identifiers
+- version numbers
+- privacy configuration
+- RevenueCat configuration
+- production analytics configuration
+- store metadata
+- support/privacy URLs
+- native manifests
+- tests
+- development URLs accidentally included in production
+- other release prerequisites
+
+Meadow Platform does not currently submit an app to either store. Future automation may assist with:
+
+- App Store screenshot layouts
+- Google Play screenshot layouts
+- store metadata
+- privacy questionnaires/checklists
+- App Store Connect uploads
+- Google Play uploads
+- TestFlight/internal testing releases
+
+Implement these only when a concrete app release proves the workflow and the automation saves
+meaningful repeated work.
+
+## App creation model
+
+Creating an app is now configuration plus domain development. `meadow new` collects app identity,
+store links, platforms, orientation, devices, and optional service choices, then writes validated
+`meadow.config.json` metadata and the complete repository foundation. The version 2 configuration is
+the source of truth for durable project intent; `meadow sync` deterministically updates Meadow-owned web,
+native, dependency, testing, and runtime configuration, while `meadow sync --check` prevents drift in
+CI.
+
+The configuration schema is versioned and exported by `@meadow-studio/platform`. Before the first external
+consumer, prefer a clean current contract over compatibility layers. Extend the schema deliberately
+when a proven capability needs persistent project metadata; do not put secrets in it or turn it
+into a speculative feature catalogue.
+
+## Success Criteria
+
+The long-term goal is:
+
+> Go from an app idea to a release-ready Angular/Capacitor foundation in under an hour.
+
+At that point development should immediately focus on the functionality that makes the application unique.
+
+Likewise, once an application becomes feature-complete, getting it into App Store / Google Play should be a reproducible process rather than another project.
+
+## Important Engineering Principles
+
+When working on Meadow Platform:
+
+1. Prefer proven requirements over hypothetical requirements.
+2. Keep the public API small.
+3. Hide third-party implementation details.
+4. Prefer configuration over duplicated implementation.
+5. Do not prematurely create abstractions.
+6. Do not prematurely split the platform into multiple packages.
+7. Keep application-specific UI and domain logic outside the platform.
+8. Never include secrets.
+9. Preserve backwards compatibility where practical.
+10. Prefer boring, maintainable solutions over clever framework machinery.
+11. Optimize for a solo developer maintaining 15+ relatively small apps.
+12. Every platform feature should save meaningful work in multiple applications.
+13. A feature being reusable in theory is not sufficient reason to add it.
+14. Stay Light is a reference implementation, not the architecture specification.
+15. 24h Pushups should be used as the first real validation of whether the abstractions are useful.
+
+## Current State
+
+Meadow Platform is currently version `0.1.0` and has three working surfaces:
+
+- the `meadow` CLI for app creation and existing-app adoption, capability recipes, integration setup,
+  diagnostics, versioning, and release checks;
+- the public `@meadow-studio/platform` Angular/Capacitor runtime with app configuration, app information,
+  consent-gated Firebase analytics and crash reporting, provider-neutral native purchases, and
+  native app-rating and local-notification behavior; and
+- the optional `@meadow-studio/platform/ui` entry point for small infrastructure-oriented components.
+
+Generated apps use the Angular 22 and Capacitor 8 baseline and receive web, iOS, Android, unit,
+visual, CI, and release foundations. The package release gate validates version consistency, unit
+tests, the packed contents, and installation/type-check/runtime behavior in a clean consumer.
+
+Not every installed provider is a complete runtime capability. Firebase observability has a
+Meadow-owned consent and delivery boundary, RevenueCat sits behind a Meadow-owned purchase API, and
+local notifications sit behind a Meadow-owned permission, scheduling, and tap-action API.
+A Meadow-owned Supabase abstraction remains a future vertical slice. The
+[platform guide](PLATFORM_GUIDE.md) is the canonical current capability map.
+
+Continue incrementally. Do not introduce large architectural changes or dependencies without a
+concrete repeated need from real applications.
+
+## North Star
+
+Meadow Platform should make each subsequent app easier to build than the previous one.
+
+If building Meadow Platform begins delaying application development more than it accelerates it, the platform is becoming too complex.
+
+The applications drive the platform — not the other way around.

package/docs/RELEASING.md

@@ -0,0 +1,49 @@
+# Releasing Meadow Platform
+
+`@meadow-studio/platform` is published as a public npm package. Each app pins an exact version and
+commits its lockfile. App installation and CI need no Meadow package credentials or access to the
+private source repository. The published package contents are public, so inspect the tarball before
+each release and keep all credentials and app-specific configuration out of it.
+
+## Prepare
+
+From `platform/`, check the current version and run the release gate:
+
+```sh
+npm run version:check
+npm run release:check
+```
+
+Use `npm run version:set -- patch`, `minor`, `major`, or an exact `x.y.z` value when a new version
+is needed, then rerun the gate. The release gate builds and tests the package, installs its actual
+tarball in a clean consumer, verifies package contents, and checks for whitespace errors. Review
+the `npm pack --dry-run` file list before publishing; files listed in `package.json` are available
+to anyone after publication. Never include secrets or app-specific Firebase files.
+
+## Publish
+
+The publisher needs an npm account with publish rights in the `@meadow-studio` scope and npm's required
+publishing authentication. Once the reviewed version is ready:
+
+```sh
+npm publish --access public
+```
+
+`publishConfig` also fixes public access and the npm registry in the package manifest. The
+`prepublishOnly` script reruns the release gate. npm versions are immutable; publish a new version
+for every subsequent release. Keep the source repository private if desired, knowing that the
+published tarball is public.
+
+## Consume and upgrade
+
+Generated apps use an exact dependency, for example:
+
+```json
+"@meadow-studio/platform": "0.1.0"
+```
+
+Run `npm install` and commit the app manifest and lockfile. `meadow new` and `meadow init` also
+accept `--platform-spec file:/absolute/path/to/platform` for local development before the npm
+release exists. Replace that temporary spec with a published version and regenerate the lockfile
+before relying on independent app CI. To upgrade, change the exact version, install, and run the
+app checks and native builds.