@marktiderman/genesis-cli 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -51,6 +51,109 @@ from the live database.
51
51
 
52
52
  The output is deterministic: a re-run with no schema change writes the same bytes.
53
53
 
54
+ ```bash
55
+ npx @marktiderman/genesis-cli features build # or: features check (for CI)
56
+ ```
57
+
58
+ Writes the marked feature block in `AGENTS.md` (and a JSON copy with `--json <file>`) from the
59
+ repo's `src/features.ts`; `check` exits 1 when that output is stale or a feature's `links.code`
60
+ path doesn't exist. See [genesis-features](../features/README.md) for the registry and the options.
61
+
62
+ ## Expo config plugin
63
+
64
+ `withGenesis()` keeps an Expo app's `app.config.ts` to a name, ids and plugins:
65
+
66
+ ```ts
67
+ // app.config.ts
68
+ import type { ExpoConfig } from "expo/config";
69
+
70
+ export default (): ExpoConfig => ({
71
+ name: "My App",
72
+ slug: "my-app",
73
+ scheme: "myapp",
74
+ ios: { bundleIdentifier: "com.example.myapp" },
75
+ android: { package: "com.example.myapp" },
76
+ plugins: ["expo-router", "@marktiderman/genesis-cli"],
77
+ });
78
+ ```
79
+
80
+ Install the CLI in the app (`pnpm add -D @marktiderman/genesis-cli`); Expo finds the plugin
81
+ through the package's `app.plugin.js`. To pass options, use `["@marktiderman/genesis-cli", { … }]`,
82
+ or call it yourself: `import { withGenesis } from "@marktiderman/genesis-cli/expo"`.
83
+
84
+ | Step | What it sets | Option to turn it off |
85
+ | --- | --- | --- |
86
+ | App variants | `APP_VARIANT` = `development` / `preview` / `production` (default) suffixes `ios.bundleIdentifier` and `android.package` with `.dev` / `.preview` and `name` with ` (Dev)` / ` (Preview)`, so the three install side by side. Any other value fails. A value that already ends in the suffix is left alone. Change the suffixes with `variants: { development: { id: ".debug", name: " (Debug)" } }`. | pass `variant: "production"` |
87
+ | Links | `ios.associatedDomains` (`applinks:` and, unless `links.webcredentials` is `false`, `webcredentials:` per host) and one Android `intentFilters` entry with `autoVerify`, from the `links` block of `genesis.config.json`. | `links: false` |
88
+ | Privacy manifest | `ios.privacyManifests.NSPrivacyAccessedAPITypes` for the packages in `dependencies`: `@react-native-async-storage/async-storage` needs FileTimestamp, reason `C617.1` (what its own `PrivacyInfo.xcprivacy` declares). | `privacyManifest: false` |
89
+ | Export compliance | `ios.config.usesNonExemptEncryption = false`. | `exportCompliance: false` |
90
+ | Runtime version | `runtimeVersion: { policy: "fingerprint" }`. | `fingerprint: false` |
91
+
92
+ The app's own values always win: the plugin fills gaps and appends to lists, merges privacy
93
+ reasons into an entry the app already declares, never overwrites or removes anything, and
94
+ running it twice changes nothing.
95
+
96
+ ### Setting APP_VARIANT
97
+
98
+ `APP_VARIANT` has to be the same wherever the config is evaluated for a build, not only in
99
+ `eas build`. `eas update` and EAS fingerprint checks evaluate the config too, and they don't read
100
+ the `env` of a build profile in `eas.json`. If an update is published without the variant, it is
101
+ built for the production ids and runtime, and preview and development builds never receive it.
102
+
103
+ Set it per EAS environment instead, so builds, updates and fingerprints all see it:
104
+
105
+ ```bash
106
+ eas env:create --environment preview --name APP_VARIANT --value preview --visibility plaintext
107
+ eas env:create --environment development --name APP_VARIANT --value development --visibility plaintext
108
+ ```
109
+
110
+ Point each build profile at its environment (`"preview": { "environment": "preview" }`), and
111
+ publish with `eas update --environment preview` (SDK 55 requires `--environment`). On SDK 54 or
112
+ earlier without EAS environments, set it on the command line every time:
113
+ `APP_VARIANT=preview eas update --branch preview`.
114
+
115
+ ### Links
116
+
117
+ The `links` block in `genesis.config.json` is validated by the same loader the doctor uses, so a
118
+ bad block fails `genesis doctor` too:
119
+
120
+ ```json
121
+ {
122
+ "links": { "hosts": ["example.com", "app.example.com"], "paths": ["/invite", "/c"], "webcredentials": true }
123
+ }
124
+ ```
125
+
126
+ `hosts` are bare lower-case host names (`*.example.com` allowed; no scheme, path or port);
127
+ `paths` are optional prefixes, each starting with `/`; `webcredentials` (default `true`) adds the
128
+ `webcredentials:` domains for password autofill. Set it to `false` if the site doesn't share
129
+ credentials with the app.
130
+
131
+ The web side has to list every variant you want links to open, because each variant is a
132
+ different app to Apple and Google:
133
+
134
+ - `/.well-known/apple-app-site-association`: one app id per variant, `TEAMID.com.example.myapp`,
135
+ `TEAMID.com.example.myapp.dev` and `TEAMID.com.example.myapp.preview`, under `applinks` (in
136
+ `details[].appIDs`) and, when `webcredentials` is on, under `webcredentials.apps`.
137
+ - `/.well-known/assetlinks.json`: one entry per package (`com.example.myapp`,
138
+ `com.example.myapp.dev`, `com.example.myapp.preview`), each with that build's own signing
139
+ certificate SHA-256 fingerprint (`eas credentials` shows it).
140
+
141
+ A variant the web files leave out installs fine, but its links open in the browser.
142
+
143
+ ### Determinism
144
+
145
+ The plugin reads exactly two committed files in the project root, `genesis.config.json` and
146
+ `package.json`, and one environment variable, `APP_VARIANT`. It makes no network calls and reads
147
+ no clock or other environment, so for a given commit and `APP_VARIANT` it always gives the same
148
+ config. That makes the EAS fingerprint (`runtimeVersion` policy `fingerprint`) stable only when
149
+ `APP_VARIANT` is set the same way in every place the config is evaluated: builds, `eas update` and
150
+ fingerprint checks (see [Setting APP_VARIANT](#setting-app_variant)). Keep the rest of the config
151
+ in committed files too.
152
+
153
+ `@expo/config-plugins` and `@expo/config-types` are optional peer dependencies used for types
154
+ only; the plugin bundles neither and has no runtime dependency on them. Node 20.19 or 22.12+ is
155
+ needed (Expo `require()`s `app.plugin.js`, which is an ES module).
156
+
54
157
  ## Settings in comments
55
158
 
56
159
  Put labels and widgets next to the schema, in table and column comments:
package/app.plugin.js ADDED
@@ -0,0 +1,4 @@
1
+ // The Expo config plugin: `plugins: ["@marktiderman/genesis-cli"]` in app.config.ts.
2
+ // Expo require()s this file; Node's require(esm) (Node 20.19+, 22.12+) loads it
3
+ // and Expo calls its default export. See README "Expo config plugin".
4
+ export { default } from "./dist/expo.js";