@meadow-studio/platform 0.0.0-stage → 0.1.0

package/docs/V0.1_PATH.md

@@ -0,0 +1,310 @@
+# Meadow Platform v0.1 — First Path
+
+> This is the historical POC path and dated implementation record. For current capabilities and
+> usage, read [PLATFORM_GUIDE.md](PLATFORM_GUIDE.md). For exact CLI behavior, read
+> [CLI.md](CLI.md).
+
+## POC outcome
+
+Prove that the early 24h Pushups prototype can consume one private `@meadow-studio/platform` dependency without slowing concept development.
+
+The first POC is complete when 24h Pushups can:
+
+1. consume the local platform package at its exact `0.1.0` version and validate its packed contents;
+2. provide typed app and environment configuration;
+3. read app version, build number, and native platform through a Meadow-owned API;
+4. pass its existing unit tests and production/device builds; and
+5. build and run on its existing Android target.
+
+The POC does not require Firebase, analytics consent, RevenueCat, private-registry publishing, or a generated iOS project. Those are separate adoption decisions after package consumption is proven.
+
+## Why this slice comes first
+
+Configuration is required by every later integration. App information is small, observable, and exercises Capacitor cleanly. Together they prove the package boundary without introducing infrastructure that an exploratory prototype does not yet need.
+
+Analytics, consent, and purchases have native setup and product-policy consequences. They should reuse the configuration and provider boundaries proven by the first POC rather than defining those boundaries themselves.
+
+## Phase 0 — Establish the package contract
+
+Keep one package and a small root API.
+
+Deliverables:
+
+- use the shared proven baseline: Angular 20.3, Capacitor 7, TypeScript 5.9, RxJS 7.8, and Node 22;
+- use `npm pack --dry-run` to verify published contents and a local file dependency for the first consumer integration;
+- add package exports so consumers use public entry points only;
+- add a minimal test runner and package-consumer smoke test;
+- confirm the packed artifact contains only intended runtime and declaration files; and
+- document the rule that application credentials are supplied by the consuming app.
+
+After the POC is useful in practice, publish immutable versions through GitHub Packages or another private registry. Registry setup is not part of proving the code boundary.
+
+## Phase 1 — Typed configuration
+
+Create a small, immutable configuration contract containing only values immediately needed by the first consumer.
+
+Initial shape to validate:
+
+```ts
+export interface MeadowPlatformConfig {
+  app: {
+    name: string;
+    id: string;
+    supportEmail?: string;
+    privacyUrl?: string;
+  };
+  environment: 'development' | 'device' | 'production';
+}
+```
+
+Requirements:
+
+- fail early with useful errors for invalid required values;
+- keep credentials and environment selection in the consuming app;
+- do not create a general plugin system;
+- do not include analytics or purchases configuration until those slices establish their real needs; and
+- expose configuration through one documented initialization path.
+
+Both real apps use standalone Angular configuration and Angular dependency injection. Start with an Angular provider API. Do not add a framework-neutral core or adapter layer until a non-Angular consumer creates that requirement.
+
+## Phase 2 — App information
+
+Expose a Meadow-owned value shape rather than Capacitor types.
+
+```ts
+export interface MeadowAppInfo {
+  version: string | null;
+  buildNumber: string | null;
+  platform: 'ios' | 'android' | 'web';
+}
+```
+
+Requirements:
+
+- use Capacitor behind the package boundary;
+- return `null` native metadata on web and when the native plugin is unavailable;
+- avoid exposing native plugin result types; and
+- verify values in a small build-information row in 24h Pushups settings.
+
+## Phase 3 — Validate the first POC
+
+Validate the locally packed dependency in the actual 24h Pushups prototype.
+
+POC gate:
+
+- the platform package builds and its public types compile;
+- `npm pack --dry-run` contains only intended files;
+- 24h Pushups resolves the local file dependency as `@meadow-studio/platform@0.1.0`;
+- the app provides its name, application ID, and current environment through the platform API;
+- the Settings page reads version/build/platform through the platform service;
+- existing 24h Pushups tests, lint, production build, and device build pass;
+- the existing Android project synchronizes and builds; and
+- the consumer does not import platform implementation internals.
+
+Stop here and assess whether the integration removed duplication while remaining easier to understand than local app code.
+
+## Phase 4 — Analytics vertical slice
+
+Inventory the analytics behavior already proven in Stay Light before designing the public interface.
+
+Start with the minimum consumer capability:
+
+```ts
+analytics.track('challenge_created');
+```
+
+Requirements:
+
+- application code imports only Meadow Platform analytics types/functions;
+- disabled analytics is a safe no-op;
+- event names and properties remain app-owned;
+- Firebase-specific initialization and types stay behind the package boundary;
+- provider failures do not break the core app flow; and
+- one real 24h Pushups event is observable in the configured analytics environment.
+
+Do not add screen tracking, identity, consent orchestration, event schemas, batching, or multiple providers until an existing app demonstrates the requirement.
+
+## Phase 5 — Validate and release v0.1
+
+Validate the package in the actual consumer rather than only in unit tests.
+
+Release gate:
+
+- the platform package builds and its public types compile;
+- a clean consumer install works from the chosen private source;
+- the 24h Pushups web and Android builds succeed;
+- app information is correct on-device;
+- analytics disabled mode and one enabled event both work;
+- the app contains no direct Firebase analytics imports outside native/configuration setup where unavoidable;
+- no credentials or generated app-specific configuration exist in the package;
+- the public API is documented with a minimal integration example; and
+- 24h Pushups pins the released platform version.
+
+Generate and validate the iOS consumer only when iOS work begins in 24h Pushups. Tag the proven platform release as `0.1.0`. Treat changes discovered during consumer integration as design feedback, not as exceptions to work around in the app.
+
+## Next slice — Purchases
+
+After v0.1 proves the package and provider boundary, inventory Stay Light's RevenueCat integration and implement the smallest end-to-end purchase capability needed by 24h Pushups.
+
+Start by validating these operations only if the consumer needs them:
+
+- initialize with externally supplied configuration;
+- observe premium status;
+- purchase one product/package;
+- restore purchases; and
+- translate provider errors into a small Meadow-owned error model.
+
+Keep paywall UI and product-specific messaging in the app. Do not expose RevenueCat customer-info or entitlement types through the public API.
+
+### Purchase capability completion — 2026-09-18
+
+The slice is now implemented as `MeadowPurchaseService`. It loads app-configured offering packages,
+exposes normalized product and entitlement signals, derives premium state, performs purchase and
+restore, refreshes/listens for customer-info changes, returns a support identifier, and translates
+provider failures into Meadow-owned outcomes and error categories. Generated apps keep platform
+public SDK keys in `.env.meadow.local`, generate an ignored runtime asset before builds, and validate
+the dependency, enabled-platform keys, and catalog identifiers through `meadow doctor`.
+
+Paywall UI, product taxonomy and IDs, pricing and entitlement policy, analytics, and store catalog
+remain app-owned. Unit tests, packed-consumer checks, CLI configuration, and clean Android/iOS
+simulator builds validate the shared foundation; real store sandbox transactions remain an app
+release check.
+
+## First concrete work session
+
+Before writing platform abstractions:
+
+1. add explicit package exports and align supported peer/runtime versions with the shared app baseline;
+2. add a minimal test runner and a packed-package smoke test;
+3. implement an Angular `provideMeadowPlatform(...)` configuration entry point;
+4. implement app information behind a Meadow-owned interface; and
+5. integrate the packed artifact into 24h Pushups and show build information in Settings.
+
+This creates a small review point before Firebase or RevenueCat dependencies become part of the package contract.
+
+## POC implementation status — 2026-09-14
+
+The first POC is implemented:
+
+- `@meadow-studio/platform` exposes explicit package exports and Angular/Capacitor peer ranges;
+- `provideMeadowPlatform(...)` validates and freezes typed app/environment configuration;
+- `MeadowAppInfoService` returns native version, build number, and platform behind a Meadow-owned interface;
+- web runtimes receive an honest `null` for unavailable native metadata;
+- the Capacitor App module is loaded only when native metadata is requested;
+- platform unit tests and the package dry-run pass;
+- 24h Pushups consumes the package through a local file dependency;
+- development, device, and production builds supply distinct platform environments;
+- Settings displays `Web preview` on web and native version/build/platform on a device;
+- all 48 consumer tests and lint pass; and
+- production, device, Capacitor sync, and Android debug APK builds pass.
+
+Native metadata has not been observed on a physical device because no Android device was connected during verification. The production web build also retains its bundle-budget warning: after the analytics foundation, the initial bundle is 4.49 kB over the configured 675 kB warning threshold.
+
+## Release readiness status — 2026-09-14
+
+The reproducible private-package path is implemented:
+
+- CI runs on pushes, pull requests, and manual dispatches with Node 22.15;
+- `npm run version:set -- <patch|minor|major|x.y.z>` updates the package manifest, lockfile, and public runtime version together;
+- `npm run version:check` detects version drift;
+- `npm run test:consumer` creates the real tarball, rejects unexpected packaged files, installs it in a clean temporary consumer, type-checks the public API, and exercises it at runtime;
+- `npm run release:check` runs the complete local release gate; and
+- `docs/RELEASING.md` defines immutable private Git-tag installation and application upgrades.
+
+24h Pushups deliberately remains on the local file dependency while the platform changes are under development. After the reviewed platform commit and `v0.1.0` tag exist on the private remote, switch the app dependency to the exact Git tag and regenerate its lockfile. Do not point the app at a tag that is not yet remotely installable.
+
+## Analytics foundation status — 2026-09-14
+
+The provider-neutral portion of the analytics slice is implemented:
+
+- collection starts disabled and can only become effective in a production environment when analytics is configured as available;
+- event names and property names are app-owned allowlists supplied through typed configuration;
+- unexpected events, unexpected properties, nullish values, and non-finite numbers are dropped;
+- enablement updates are serialized for asynchronous providers;
+- provider setup and delivery failures never interrupt application flows;
+- 24h Pushups owns a focused `PushupAnalyticsService` and records `pushups_logged` only after the domain action succeeds; and
+- 24h Pushups keeps analytics disabled, so this integration emits no data.
+
+The Firebase transport, native Firebase configuration, persisted consent choice, consent UI, and observable native event delivery remain future work. They should be introduced together when 24h Pushups is ready to collect real product analytics.
+
+### Firebase observability completion — 2026-09-17
+
+The platform work identified above is now implemented. Analytics and Crashlytics use Meadow-owned
+runtime services backed by native Firebase transports, separate persisted explicit consent, and
+production-only enforcement. `meadow configure firebase`, `meadow sync`, and `meadow doctor` now own the
+repeatable Android and iOS setup, including native collection-off defaults and bundling the iOS
+Firebase configuration resource. An app still owns its consent experience and must confirm one
+event and one test crash against its real Firebase project before release.
+
+## App rating foundation status — 2026-09-14
+
+The first reusable native capability after the POC is implemented:
+
+- `MeadowAppRatingService` presents the system-owned App Store or Play Store rating surface;
+- the private package carries its own Capacitor iOS and Android plugin code, so consuming apps do not copy native files;
+- web and unavailable native runtimes safely return without presenting anything;
+- concurrent requests share one attempt and native failures never interrupt app behavior;
+- Meadow avoids requesting twice for the same app version, waits 120 days between attempts, and caps attempts at two per rolling year;
+- 24h Pushups owns its product qualification and asks only after 100 total pushups and a three-day winning streak;
+- the packed consumer check includes and validates the native package files;
+- 24h Pushups discovers the package as a Capacitor plugin and its Android debug APK compiles with it; and
+- the iOS Swift source type-checks against Capacitor 7, while full 24h iOS integration remains deferred until that app generates an iOS project.
+
+No custom rating modal was added. Ratings use the operating-system interface; reusable custom dialogs remain a Meadow Design concern.
+
+## CLI foundation status — 2026-09-16
+
+The explicitly requested idea-to-release tooling now forms the v0.2 development baseline:
+
+- `meadow new <name>` creates a standalone application repository on Angular 22 and Capacitor 8;
+- the generated stack excludes Ionic and Meadow Design while leaving both as app-owned choices;
+- creation installs exact dependencies, generates iOS and Android, validates the app, creates
+  phone/tablet Playwright baselines, and makes an initial gitmoji commit;
+- optional prompts add RevenueCat and Supabase client dependencies without platform-owned secrets;
+- `meadow configure` covers Firebase, RevenueCat, Supabase, assets, signing guidance, store metadata,
+  and GitHub repository creation;
+- `meadow doctor`, `meadow version`, and `meadow release-check` provide repeatable diagnostics and release
+  gates;
+- every generated repository includes GitHub CI for formatting, linting, dependency audit,
+  coverage-gated Vitest tests, web build, Playwright screenshot comparison, Android compilation,
+  and an unsigned iOS simulator build; and
+- a clean generated project has been validated through dependency audit, web/device builds, unit
+  and screenshot tests, Android assembly, and iOS simulator compilation.
+
+The historical v0.1 notes above remain evidence of the original POC baseline. New apps use the
+v0.2 CLI baseline documented in [CLI.md](CLI.md).
+
+## Local-data recipe status — 2026-09-16
+
+The first optional post-creation capability is implemented as `meadow add local-data`:
+
+- native apps use `@capacitor-community/sqlite`, while browser development uses its
+  IndexedDB-persisted SQLite runtime;
+- the recipe generates a small Meadow-owned database boundary, sequential migrations, transactions,
+  and a typed JSON document store;
+- app-specific schemas, decoders, and repositories remain in the consuming app;
+- dependency and runtime versions are pinned, native projects are synchronized, and the complete
+  generated-app check runs before the config is marked ready;
+- Android cloud backup is disabled by default for local app data; and
+- the generated release checklist covers migration upgrades, reset/deletion behavior, restore
+  policy, and native SQLCipher export-compliance review.
+
+This slice is based on the validated repositories in 24h Pushups and the Capacitor SQLite use in
+Nyttebjerggaard, while keeping Stay Light's more specialized recovery behavior app-owned until a
+second app proves that it belongs in the shared foundation.
+
+Validation in a clean generated app passed formatting, linting, unit tests, production web build,
+Capacitor synchronization, an Android debug build, and an actual browser SQLite write/read followed
+by an IndexedDB-backed reload. That runtime check caught and fixed an ABI mismatch by pinning
+`sql.js` 1.11.0 to the version used by `jeep-sqlite` 2.8.0. The iOS graph successfully resolved the
+SQLite and SQLCipher packages, but the broader Xcode package update then remained idle and was
+stopped; a full iOS simulator compile for this optional recipe still needs a clean resolver run.
+
+## Local-notification capability status — 2026-10-06
+
+The later platform work added `meadow add notifications` and a provider-neutral
+`MeadowNotificationService` based on repeated needs in 24h Pushups and Stay Light. The service keeps
+permission prompting explicit, supports one-off and recurring calendar schedules,
+replace/cancel/pending operations, Android channels, and tap actions, and remains safe when disabled
+or running on web. Product copy, IDs, timing policy, navigation, and analytics remain app-owned.
+Android schedules are deliberately inexact by default.

package/ios/Sources/MeadowPlatformPlugin/MeadowAppRatingPlugin.swift

@@ -0,0 +1,39 @@
+import Capacitor
+import StoreKit
+import UIKit
+
+/// Presents Apple's system-owned rating surface. StoreKit intentionally does
+/// not disclose whether the person submitted a rating or dismissed the sheet.
+@objc(MeadowAppRatingPlugin)
+public class MeadowAppRatingPlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "MeadowAppRatingPlugin"
+    public let jsName = "MeadowAppRating"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "requestReview", returnType: CAPPluginReturnPromise),
+    ]
+
+    @objc public func requestReview(_ call: CAPPluginCall) {
+        // StoreKit ignores review requests in TestFlight. Do not consume Meadow's
+        // cooldown when the operating system cannot attempt to show the sheet.
+        #if !DEBUG
+        if Bundle.main.appStoreReceiptURL?.lastPathComponent == "sandboxReceipt" {
+            call.resolve(["attempted": false])
+            return
+        }
+        #endif
+
+        DispatchQueue.main.async {
+            guard let scene = self.bridge?.viewController?.view.window?.windowScene else {
+                call.reject("No active window is available for the App Store review prompt")
+                return
+            }
+
+            if #available(iOS 18.0, *) {
+                AppStore.requestReview(in: scene)
+            } else {
+                SKStoreReviewController.requestReview(in: scene)
+            }
+            call.resolve(["attempted": true])
+        }
+    }
+}

package/package.json

@@ -1,6 +1,91 @@
 {
   "name": "@meadow-studio/platform",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "description": "Meadow app platform to support app development",
+  "bin": {
+    "meadow": "dist/cli/meadow.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui/index.d.ts",
+      "import": "./dist/ui/index.js"
+    },
+    "./schema/meadow-config.schema.json": "./schema/meadow-config.schema.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "schema",
+    "android/src/main",
+    "android/build.gradle",
+    "ios/Sources",
+    "Package.swift",
+    "MeadowPlatform.podspec"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.15 <25",
+    "npm": ">=11 <12"
+  },
+  "scripts": {
+    "test": "npm run build && node --test test/*.test.mjs",
+    "test:consumer": "node scripts/test-packed-consumer.mjs",
+    "build": "ngc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "pack:check": "npm pack --dry-run --cache .cache/npm",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run release:check",
+    "version:check": "node scripts/version.mjs check",
+    "version:set": "node scripts/version.mjs set",
+    "check": "npm run version:check && npm test && npm run test:consumer",
+    "release:check": "npm run check && npm run pack:check && git diff --check"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nyttebjerggaard/meadow-studio.git",
+    "directory": "platform"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/nyttebjerggaard/meadow-studio/issues"
+  },
+  "homepage": "https://github.com/nyttebjerggaard/meadow-studio/tree/main/platform#readme",
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    },
+    "android": {
+      "src": "android"
+    }
+  },
+  "peerDependencies": {
+    "@angular/core": "^22.1.6",
+    "@capacitor/app": "^8.1.1",
+    "@capacitor/core": "^8.4.3"
+  },
+  "devDependencies": {
+    "@angular/compiler": "22.1.6",
+    "@angular/compiler-cli": "22.1.6",
+    "@angular/core": "22.1.6",
+    "@capacitor/app": "8.1.1",
+    "@capacitor/core": "8.5.2",
+    "@types/node": "24.10.1",
+    "rxjs": "7.8.2",
+    "typescript": "6.0.3",
+    "zone.js": "0.16.0"
+  }
+}