@_linked/cli 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 1.14.0
+
+### Minor Changes
+
+- [#81](https://github.com/linked-cm/cli/pull/81) [`d1c0729`](https://github.com/linked-cm/cli/commit/d1c07296a9470ed3c995ce83a9ade22c0632395c) Thanks [@flyon](https://github.com/flyon)! - `create-app --template react-native` now scaffolds the Linked backend next to the app.
+
+  - `services/api`: an API-only Linked backend (`linked start --api-only`) on `@_linked/server`, with Fuseki through `linked.backend.datasets.json`, a local file store (or `S3FileStore` when the S3 variables are set), a Fuseki reachability check and `node --test` unit tests.
+  - A root `docker-compose.yml` for Fuseki (`secoresearch/fuseki:5.5.0`, host port `FUSEKI_PORT`), root scripts `fuseki:up`, `fuseki:down`, `api`, `check:react`, `lint`, `typecheck`, `test` and `test:integration`, a root ESLint flat config (with a rule that keeps `apps/mobile` on `@_linked/server` subpath imports) and a "Before every PR" checklist in the README (the template ships no CI workflow).
+  - Pins `@_linked/server` 2.3.0, `@_linked/server-utils` 1.2.0 and `@_linked/cli` 1.13.0.
+  - `apps/mobile/babel.config.js` registers a Babel plugin that strips JSON import attributes (`import('x.json', { with: { type: 'json' } })`), so Metro bundles Linked ontology packages.
+  - `resolveApiUrl` ignores a non-string `extra.apiUrl`: the dev-client manifest delivers `null` as `{}`, which crashed the app with "LincdServerProxy requires a root URL".
+  - `apps/mobile` imports `@_linked/react/native` (1.5.0) instead of its own render defaults, resolves the API URL in `app.config.ts` and `src/shell/env.ts`, and sends queries to the API through `BackendAPIStore`. The root `overrides` entry is gone.
+  - An example add/edit/delete screen (`PersonOverview`, `PersonPreview`), ported from the web app-template to React Native with `@_linked/schema`'s `Person`, with a Jest integration test against the running API and Fuseki.
+  - The shapes package sets `"linked": {"extensionlessImports": true}`, so `linked build` emits Node-loadable `lib/esm`.
+  - With `linked.extensionlessImports`, `linked build` fails when `lib/esm` was not emitted (no `tsconfig-esm.json`), finishes "with warnings" listing every relative specifier it could not resolve, and handles `'.'`, `'..'` and `'./dir/'`. `linked build` now exits non-zero when the build fails.
+  - README: documents `linked start --api-only` / `server.apiOnly`, the `extensionlessImports` flag, and the react-native template as it is now.
+  - Integration tests only reset a Fuseki that is this repo's Compose `fuseki` on localhost (`docker compose port fuseki 3030`) with a `-test` dataset. They read `services/api/.env` (the shell wins), pass every `FUSEKI_*` variable to the API explicitly, blank the S3 variables (removing `AWS_REGION`, which `@_linked/s3` rejects when empty), and kill the API's process group on timeout, early exit, SIGINT, SIGTERM and exit. `INTEGRATION_API_BIN` and `INTEGRATION_API_TIMEOUT_MS` exist for testing that cleanup.
+  - Load order is enforced by imports: `storage.ts` imports `env.ts`, and the example linked components import `storage.ts`. The default API port is shared from `apps/mobile/src/shell/apiPort.json`.
+  - `wait-for-fuseki.mjs` honours `WAIT_FOR_FUSEKI_TIMEOUT_MS`. New tests: `storage.test.ts` (load order) and `waitForFuseki.test.mjs`. Local uploads go to `services/api/data/uploads/`, which is gitignored.
+  - `linked call` (a direct `callBackendMethod`) now prints the error and exits 1 when the method is unmatched or fails, instead of an unhandled rejection.
+  - The Fuseki dataset names (`<prefix>-dev`, `<prefix>-test`) are stamped from the app prefix.
+  - Shipped dotfiles are restored at any depth, and `env.example.template` becomes `.env.example`.
+
+## 1.13.0
+
+### Minor Changes
+
+- [#79](https://github.com/linked-cm/cli/pull/79) [`fd27a8d`](https://github.com/linked-cm/cli/commit/fd27a8d827b591c2d6db6bd2a7db1aa1de94b71d) Thanks [@flyon](https://github.com/flyon)! - Add `linked start --api-only` for a Linked backend without a web frontend.
+
+  - No `vite.config.*` is required: without one, Vite runs with the `createViteConfig()` defaults inline, so TypeScript, decorators and extensionless imports in source-only shape packages still work.
+  - No `src/App.tsx` or `src/routes.tsx` is loaded. The CLI sets `server.apiOnly` on the LinkedServer config instead of the page rendering hooks, so `/call/...` and `/api/...` routes are served and page requests get a 404 (needs a `@_linked/server` release that honours `server.apiOnly`).
+  - The mode is explicit and never inferred from missing files. `server.apiOnly: true` in `linked.config.js` turns it on too.
+  - `LinkedServerConfig` gains the `apiOnly` field.
+
+  Add `"linked": {"extensionlessImports": true}` to a package's `package.json` for packages whose source uses extensionless relative imports (for example, shapes shared with React Native, where Metro does not map `.js` specifiers to `.ts` source).
+
+  - `linked build` skips the "Checking imports" step for that package and logs that it did.
+  - After compiling ESM, it appends `.js` (or `/index.js` for a directory) to extensionless `./` and `../` specifiers of static imports, exports and `import()` calls in `lib/esm/**/*.js`, so the output loads under Node. Specifiers it cannot resolve are left unchanged with a warning. `.d.ts` files are not rewritten.
+  - Packages without the field build exactly as before.
+
+  Fix linked-package discovery in `linked start` for apps inside an npm/yarn workspaces monorepo: dependencies are now resolved the way Node resolves them, walking up parent `node_modules` directories to the workspace root. A linked package hoisted to the root `node_modules` is found, so the app no longer falls into standalone mode (which dropped the `development` export condition).
+
+  In workspace mode, `linked start` now bundles only the discovered source workspaces through Vite SSR (`ssr.noExternal`). Published framework packages installed in `node_modules` (such as `@_linked/core`) stay external and load through Node. Before, every `@_linked/*` package was force-bundled, so Vite ran its own `@_linked/core` while a store loaded by core's `loadStores` through a native `import()` (for example `@_linked/fuseki/shapes/FusekiStore`) pulled in a second, Node-loaded core. That split the shape registry ("Cannot resolve an rdf:type for shape"). An installed package that depends (directly or transitively, through `dependencies` or `peerDependencies`) on a discovered workspace is bundled too. For example, when `@_linked/core` is itself a source workspace, a published `@_linked/fuseki` goes through Vite and uses the same core. Only the dependency closure of the app and its workspaces is scanned.
+
 ## 1.12.0
 
 ### Minor Changes

package/README.md

@@ -62,6 +62,7 @@ linked setup-publish --scope community      # use NPM_AUTH_TOKEN_CM instead of N
 
 ```bash
 linked start                      # run the dev server (app)
+linked start --api-only           # run only the backend API (no page rendering, no vite.config needed)
 linked dev                        # file-watch rebuild (package)
 linked yarn <args>                # safe-yarn: run yarn at root while preserving nested yarn.lock files
 ```
@@ -88,6 +89,45 @@ The CLI recognizes two flags in `package.json`:
 
 The legacy `lincd: true` / `lincdApp: true` flags are no longer read. Migrate to `linkedPackage` / `linkedApp`.
 
+### `"linked": {"extensionlessImports": true}`
+
+```json
+{
+  "linkedPackage": true,
+  "type": "module",
+  "linked": {"extensionlessImports": true}
+}
+```
+
+By default `linked build` rejects relative imports without an extension (`./shapes/Example`), because Node's ESM
+loader cannot resolve them. Set this flag when the package source must use extensionless imports, for example a
+shapes package consumed as TypeScript source by Metro (which does not map `.js` specifiers to `.ts` files).
+With the flag, `linked build`:
+
+- skips the import check;
+- after compiling ESM, rewrites every relative specifier in `lib/esm` (static imports and exports, `export * as`,
+  side-effect imports and `import()` with a literal) to `./x.js` or `./dir/index.js`, so Node can load the output;
+- fails if `lib/esm` was not emitted;
+- finishes "with warnings" and lists each specifier it could not resolve (left unchanged).
+
+Requirements: `"linkedPackage": true`, `"type": "module"` and a `tsconfig-esm.json` in the package.
+
+## API-only backend
+
+`linked start --api-only`, or `server.apiOnly: true` in `linked.config.js`, serves only the backend API
+(`/call/...`, `/api/...` and provider routes). There is no server-side page rendering, page requests get a 404,
+and no `vite.config.*` is required. Use it for a backend whose frontend lives elsewhere, such as a React Native
+app:
+
+```js
+// linked.config.js
+export default {
+  server: {apiOnly: true},
+};
+```
+
+API-only mode is never inferred: a web app without a `vite.config.*` and without the flag still fails at startup.
+
 ## Development
 
 ```bash
@@ -110,68 +150,71 @@ Templates live in `defaults/`:
 
 `linked create-app <name>` copies `defaults/app-with-backend/` to the new app's folder, substitutes `${name}` / `${hyphen_name}` / `${app_prefix}` / `${app_domain}` placeholders in selected files, and copies `linked.backend.datasets.example.json` → `linked.backend.datasets.json` so first boot works zero-config.
 
-Storage configuration follows the two-layer pattern from [backlog 016](https://github.com/create-now/docs/blob/main/docs/backlog/016-ejection-export-flow.md) (canonical spec) + the symmetric backend/frontend split:
-
-| File | Side | Role | Git |
-|---|---|---|---|
-| `linked.backend.storage.ts` | backend | Shape→alias routing. Uses `parseDatasetsConfig` + `loadStores` from `@_linked/core`; calls `LinkedStorage.setDefaultDataset(...)` / `setDatasetForShapes(...)`. | committed |
-| `linked.backend.datasets.json` | backend | Alias → `{ store, config }`. `store` is an npm import path; `config` is the store class's constructor arg. `${VAR:-default}` placeholders resolved at boot. | **gitignored** |
-| `linked.backend.datasets.example.json` | backend | Template / seed for the gitignored file. Has placeholders matching env vars. | committed |
-| `src/linked.frontend.storage.ts` | frontend | Same shape→alias model; imports store classes explicitly (webpack-bundle-safe), constructs per alias. | committed |
-| `src/linked.frontend.datasets.json` | frontend | Frontend alias → `{ store, config }`. Public values only — never put secrets here, it ships in the browser bundle. | committed |
-
-Conventions:
-- Aliases on the two sides are **independent**. The framework re-routes by shape on each side; matching alias names between FE and BE is convention, not a framework requirement.
-- The backend dispatcher is registry-free (dynamic `await import(entry.store)`). The frontend hardcodes each `new StoreClass(config)` because webpack can't bundle dynamic imports of arbitrary npm specifiers.
-- Each store class accepts a single config-object constructor argument — `new FusekiStore({ endpoint, credentials? })`, `new BackendAPIStore({ name?, id? })`.
-
-### `linked create-app --template react-native`
+Storage configuration follows the two-layer pattern from [backlog 016](https://github.com/c### `linked create-app --template react-native`
 
 `linked create-app <name> --template react-native` (with the usual `--app-name`, `--app-prefix`, `--app-domain`,
 `--skip-install`) copies `defaults/app-react-native/` instead of cloning the web template. The result is an npm
-workspaces monorepo for Expo SDK 57 / React Native 0.86 / React 19.2:
+workspaces monorepo for Expo SDK 57 / React Native 0.86 / React 19.2 with an API-only Linked backend on Fuseki:
 
 ```
 <name>/
-  package.json              workspaces (enumerated) + overrides pinning @_linked/react's react to 19.2.3
-  .gitignore                node_modules/, packages/*, !packages/<prefix>-shapes/
-  apps/mobile/              Expo app: app.json, App.tsx, index.ts, metro.config.js, jest config in package.json
-    .gitignore              includes /ios and /android
-    src/shell/linkedDefaults.tsx   React Native loader/error defaults for @_linked/react
-    __tests__/              shapes.test.ts, linkedDefaults.test.tsx
-  packages/<prefix>-shapes/ Linked shapes package, TypeScript source, extensionless imports, no build step
-  services/api/             backend stub
+  package.json              enumerated workspaces; scripts fuseki:up/down, api, check:react, lint, typecheck,
+                            test, test:integration
+  docker-compose.yml        local Fuseki (secoresearch/fuseki, host port FUSEKI_PORT, default 3030)
+  eslint.config.js          flat config; keeps apps/mobile on @_linked/server subpath imports
+  apps/mobile/              Expo app (ios/ and android/ are generated, not committed)
+    App.tsx                 imports ./src/shell/env, @_linked/react/native, ./src/shell/storage
+    babel.config.js         registers babel/stripJsonImportAttributes.js
+    src/shell/              env.ts (API URL), storage.ts (BackendAPIStore)
+    src/components/         PersonOverview / PersonPreview: example add/edit/delete screen
+    __tests__/              unit tests; __tests__/integration/ runs against the API and Fuseki
+  packages/<prefix>-shapes/ Linked shapes package: TypeScript source, extensionless imports,
+                            "linked": {"extensionlessImports": true} so `linked build` emits Node-loadable lib/esm
+  services/api/             API-only backend (`linked start --api-only`) on @_linked/server, Fuseki through
+                            linked.backend.datasets.json, node --test unit tests
 ```
 
 What the scaffold does:
 
 - Refuses, before writing anything, a prefix that does not match `^[a-z][a-z0-9-]*$`, and a target folder that
   exists and is not empty.
-- Renames `gitignore.template` files to `.gitignore`. npm strips real `.gitignore` files from the CLI tarball.
+- Restores shipped dotfiles at any depth (`gitignore.template` becomes `.gitignore`, `env.example.template`
+  becomes `.env.example`). npm strips real dotfiles like `.gitignore` from the CLI tarball.
 - Renames `packages/app-shapes` to `packages/<prefix>-shapes`, and replaces the literal `app-shapes` token in
   every text file.
 - Sets the root `name` to `<hyphen-name>-monorepo`, and `app.json` `expo.name`, `expo.slug` and
-  `expo.ios.bundleIdentifier`. The bundle ID is the reversed domain plus the prefix, e.g.
-  `com.formaestudios.formae`.
+  `expo.ios.bundleIdentifier`. The bundle ID is the reversed domain plus the prefix, e.g. `com.example.demo`.
+- Stamps the Fuseki dataset names `<prefix>-dev` and `<prefix>-test` from the prefix.
 - Never runs the `${…}` placeholder substitution, so template literals in the sources are left alone.
 - Installs with `npm install` (never Yarn) unless `--skip-install` is given. If the install fails, the files
   stay and the command exits non-zero; run `npm install` in the folder to retry.
 
-`ios/` (and `android/`) are **generated, not committed**: `npx expo run:ios` (or `npx expo prebuild`) creates
-them from `app.json`, and `apps/mobile/.gitignore` ignores them.
+The generated app:
 
-Quick commands in the generated app:
+- **Render defaults** come from `@_linked/react/native`, which replaces `@_linked/react`'s `<svg>` loader and
+  error elements (they crash on React Native).
+- **Person example.** `PersonOverview` and `PersonPreview` list, add, edit and delete `@_linked/schema`'s
+  `Person` through `BackendAPIStore` → API → Fuseki. A Jest integration test covers it.
+- **Babel plugin.** Metro rejects `import('x.json', { with: { type: 'json' } })`, which Linked ontology packages
+  use; `apps/mobile/babel/stripJsonImportAttributes.js` drops that options argument.
+- **Before every PR.** The template ships no CI workflow. Its README has a checklist to run locally and paste
+  into the PR:
 
 ```bash
-npm ls react                                    # exactly one react@19.2.3
-npm test -w apps/mobile                         # Jest: shape registration + render defaults
-cd apps/mobile && npx expo export --platform ios --output-dir /tmp/export   # Metro bundle check
-cd apps/mobile && npx expo run:ios              # build the dev client and run on the iOS Simulator
+npm run check:react
+npm run lint
+npm run typecheck
+npm test
+npm run fuseki:up && npm run test:integration
+cd apps/mobile && npx expo export --platform ios --output-dir /tmp/export
 ```
 
-Tests for this template in this repo: `yarn test:unit` covers the scaffold offline. It scaffolds the fixture in
-`tests/fixtures/app-react-native-min` and the real template. `npm run test:template` builds nothing itself. It
-runs the built CLI with install, then the three checks above. It needs network and takes several minutes.
+To run it: `npm run fuseki:up`, `npm run api`, then `cd apps/mobile && npx expo run:ios`.
+
+Tests for this template in this repo: `yarn test:unit` covers the scaffold offline, using the fixture in
+`tests/fixtures/app-react-native-min` and the real template. `npm run test:template` runs the built CLI with
+install, then checks the generated files, `check:react`, lint, typecheck, `npm test`, the shapes build and a
+Metro iOS bundle. It builds nothing itself, needs network and takes several minutes.
 
 ## Repository
 

package/defaults/app-react-native/README.md

@@ -1,42 +1,67 @@
 # Linked React Native monorepo
 
 An npm-workspaces monorepo for a [Linked](https://github.com/linked-cm) app on Expo SDK 57 / React Native 0.86 /
-React 19.2.
+React 19.2, with an API-only Linked backend on Fuseki.
 
 ```
 apps/mobile/          Expo app (continuous native generation: ios/ is generated, not committed)
-  src/shell/          app shell, including the React Native render defaults for @_linked/react
-  __tests__/          shape registration and render-default tests
-packages/app-shapes/  Linked shapes package, consumed as TypeScript source (no build step)
-services/api/         backend stub
+  src/shell/          env (API URL) and storage (BackendAPIStore) wiring
+  src/components/     PersonOverview / PersonPreview: example add/edit/delete screen, safe to replace
+  __tests__/          unit tests; __tests__/integration/ runs against a real API and Fuseki
+packages/app-shapes/  Linked shapes package, consumed as TypeScript source; `linked build` for Node
+services/api/         Linked backend (`linked start --api-only`), see services/api/README.md
+docker-compose.yml    local Fuseki
 ```
 
 ## Run
 
+Requires Node `^22.13 || >=24` and Docker. iOS builds need macOS 26.2+ and Xcode 26.4+ with the iOS platform
+component installed.
+
 ```bash
 npm install
-npm test -w apps/mobile          # Jest
-cd apps/mobile && npx expo run:ios   # generates ios/, builds a development build with expo-dev-client, starts Metro
+cp services/api/.env.example services/api/.env   # once
+npm run fuseki:up                                # Fuseki on :3030 (Docker Compose)
+npm run api                                      # API-only backend on :4000
+cd apps/mobile && npx expo run:ios               # generates ios/, builds a dev client, starts Metro
 ```
 
 `expo-dev-client` is a dependency of `apps/mobile`, so `expo run:ios` produces a custom dev client (not Expo Go),
-which is what native modules need.
+which is what native modules need. The app finds the API on the dev machine's host (see "API URL" below).
 
-Requires Node `^22.13 || >=24`. iOS builds need macOS 26.2+ and Xcode 26.4+ with the iOS platform component
-installed.
+If port 3030 is taken, see "Port 3030 taken" in `services/api/README.md`: set `FUSEKI_PORT` in a root `.env`
+and `FUSEKI_BASE_URL` in `services/api/.env`.
 
-## Quick checks
+## Checks
 
 | Command | What it proves |
 |---|---|
-| `npm ls react` (root) | exactly one React 19.2.3 in the tree |
-| `npm test -w apps/mobile` | shapes register at runtime; Linked components render React Native elements while loading and on error |
+| `npm run check:react` | `apps/mobile`, `@_linked/react` and `react-native` resolve one React 19.2.3 |
+| `npm run typecheck` | `tsc --noEmit` in every workspace |
+| `npm run lint` | ESLint over every workspace, including the `@_linked/server` subpath rule for `apps/mobile` |
+| `npm test` | app Jest (shapes, render defaults, API URL) and the API's `node --test` unit tests |
+| `npm run fuseki:up && npm run test:integration` | the example screen lists, adds and deletes through `BackendAPIStore` → API → Fuseki (starts its own API on :4100 with the in-memory `app-test` dataset) |
+| `npm run build -w packages/app-shapes` | `linked build` emits `lib/esm` with `.js` specifiers, loadable by Node |
 | `cd apps/mobile && npx expo export --platform ios --output-dir /tmp/export` | Metro resolves `@_linked/*` (including subpaths) and the workspace packages |
 
+## Before every PR
+
+There is no CI workflow. Run every check locally before opening or updating a PR, and paste the results into the
+PR description:
+
+```bash
+npm run check:react
+npm run lint
+npm run typecheck
+npm test
+npm run fuseki:up && npm run test:integration
+cd apps/mobile && npx expo export --platform ios --output-dir /tmp/export
+```
+
 ## React Native specifics
 
-- **One React.** `@_linked/react` still declares a React 18 peer, so the root `package.json` `overrides` pins its
-  `react` to 19.2.3. Remove the override once the peer range is widened upstream. Do not use
+- **One React.** `npm ls react` lists extra React copies nested under `@_linked/server` and
+  `@_linked/server-utils`; the app never loads them, which `npm run check:react` verifies. Do not use
   `--legacy-peer-deps`: it would hide a duplicate React.
 - **Workspaces are enumerated**, never globbed, so foreign repositories checked out under `packages/` are not
   adopted. `.gitignore` uses `packages/*` plus a negation per workspace package (`packages/` cannot be negated).
@@ -46,11 +71,26 @@ installed.
   subpaths.
 - **Jest** maps `@_linked/*` to its ESM build with a scoped `moduleNameMapper`. A global
   `customExportConditions` would break `@babel/runtime`. Add every workspace package to
-  `transformIgnorePatterns`.
-- **Render defaults.** `@_linked/react`'s built-in loader and error elements are `<svg>`, which crash on React
-  Native. `apps/mobile/src/shell/linkedDefaults.tsx` replaces them app-wide and must be the first import of
-  `App.tsx`. `__tests__/linkedDefaults.test.tsx` fails if the defaults are not applied.
+  `transformIgnorePatterns`. The integration config restores Node's `fetch`, which jest-expo replaces with a
+  stub that never sends a request.
+- **Render defaults.** `@_linked/react`'s root loader and error elements are `<svg>`, which crash on React
+  Native. Importing `@_linked/react/native` installs React Native defaults; `__tests__/nativeDefaults.test.tsx`
+  guards it.
+- **API URL.** `app.config.ts` passes `EXPO_PUBLIC_API_URL` (if set) and the API port (`defaultApiPort` in
+  `src/shell/apiPort.json`, shared with `env.ts`) to `src/shell/env.ts`,
+  which falls back to the dev machine's host from Expo's `hostUri`, then `localhost`, and sets
+  `process.env.SITE_ROOT` and `DATA_ROOT` for `BackendAPIStore`. The app identity (name, slug, bundle id) stays in
+  `app.json`.
+- **Load order is enforced by imports:** `App.tsx` imports `@_linked/react/native` first, and every module that
+  needs the API store imports `src/shell/storage`, which imports `src/shell/env`.
+- **`@_linked/server` by subpath only** in `apps/mobile` (for example
+  `@_linked/server/shapes/quadstores/BackendAPIStore`): the root barrel pulls express, webpack and react-dom.
+  ESLint `no-restricted-imports` enforces it.
 - **Shapes package imports are extensionless** (`./shapes/Example`, not `./shapes/Example.js`): Metro does not
-  map `.js` specifiers to `.ts` source. For the same reason the package is never built with `linked build`,
-  whose import check rejects extensionless imports.
-- **Decorators** work with the stock `babel-preset-expo`; no extra Babel plugin is needed.
+  map `.js` specifiers to `.ts` source. `"linked": {"extensionlessImports": true}` in its `package.json` makes
+  `linked build` skip the import check and add `.js` to the emitted `lib/esm` specifiers. The app, Jest and the
+  API in development consume `src/` through the `react-native` and `development` export conditions.
+- **Decorators** work with the stock `babel-preset-expo`. The one custom Babel plugin,
+  `apps/mobile/babel/stripJsonImportAttributes.js`, strips `with { type: 'json' }` from dynamic `import()`, which
+  Metro rejects and Linked ontology packages use; `__tests__/stripJsonImportAttributes.test.ts` covers it. After
+  editing `babel.config.js` or the plugin, restart with `npx expo start --clear`.

package/defaults/app-react-native/apps/mobile/App.tsx

@@ -1,9 +1,11 @@
-// Must stay the first import: replaces @_linked/react's <svg> loader and error defaults app-wide.
-import './src/shell/linkedDefaults';
+// @_linked/react/native first: it installs the React Native render defaults before any component renders. Modules
+// that need the API store import ./src/shell/storage themselves, which imports ./src/shell/env.
+import '@_linked/react/native';
+import { Example } from 'app-shapes';
 
 import { StyleSheet, Text, View } from 'react-native';
 import { getShapeClass } from '@_linked/core/utils/ShapeClass';
-import { Example } from 'app-shapes';
+import { PersonOverview } from './src/components/PersonOverview';
 
 export default function App() {
   const registered = getShapeClass(Example.shape.id) === Example;
@@ -12,6 +14,7 @@ export default function App() {
       {/* @linkedShape adds static packageName at runtime; it is not on the class type. */}
       <Text>{(Example as any).packageName}</Text>
       <Text>{registered ? 'shapes registered' : 'shapes not registered'}</Text>
+      <PersonOverview />
     </View>
   );
 }

package/defaults/app-react-native/apps/mobile/__tests__/env.test.ts

@@ -0,0 +1,39 @@
+import { apiUrl, resolveApiUrl } from '../src/shell/env';
+
+// Explicit, so the module-level resolution does not depend on jest-expo's expo-constants mock.
+jest.mock('expo-constants', () => ({
+  __esModule: true,
+  default: { expoConfig: { extra: { apiUrl: null, apiPort: 4000 }, hostUri: '192.168.1.5:8081' } },
+}));
+
+describe('resolveApiUrl', () => {
+  test('explicit url wins', () => {
+    expect(
+      resolveApiUrl({ extra: { apiUrl: 'http://api.test:9000', apiPort: 4000 }, hostUri: '192.168.1.5:8081' }),
+    ).toBe('http://api.test:9000');
+  });
+
+  test('derives from hostUri', () => {
+    expect(resolveApiUrl({ extra: { apiUrl: null, apiPort: 4000 }, hostUri: '192.168.1.5:8081' })).toBe(
+      'http://192.168.1.5:4000',
+    );
+  });
+
+  test('ignores a non-string apiUrl (the dev-client manifest turns null into {})', () => {
+    expect(resolveApiUrl({ extra: { apiUrl: {}, apiPort: 4000 }, hostUri: '192.168.1.5:8081' })).toBe(
+      'http://192.168.1.5:4000',
+    );
+  });
+
+  test('falls back to localhost', () => {
+    expect(resolveApiUrl({ extra: { apiUrl: null, apiPort: 4000 }, hostUri: undefined })).toBe(
+      'http://localhost:4000',
+    );
+  });
+
+  test('sets process.env', () => {
+    expect(apiUrl).toBe('http://192.168.1.5:4000');
+    expect(process.env.SITE_ROOT).toBe(apiUrl);
+    expect(process.env.DATA_ROOT).toBe(`${apiUrl}/data`);
+  });
+});

package/defaults/app-react-native/apps/mobile/__tests__/integration/apiEnv.ts

@@ -0,0 +1,49 @@
+/// <reference types="node" />
+// Shared by globalSetup, globalTeardown and the tests: where the test API and Fuseki live.
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const API_PORT = 4100;
+export const API_URL = `http://localhost:${API_PORT}`;
+// globalSetup deletes this dataset, so it must end in `-test` (checked there).
+export const FUSEKI_DATASET = 'app-test';
+
+export const repoRoot = resolve(__dirname, '../../../..');
+export const apiDir = resolve(repoRoot, 'services/api');
+
+/** Minimal KEY=VALUE parser for services/api/.env: no expansion, no multi-line values. */
+export function parseEnvFile(text: string): Record<string, string> {
+  const vars: Record<string, string> = {};
+  for (const line of text.split(/\r?\n/)) {
+    const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/.exec(line);
+    if (!match) continue;
+    vars[match[1]] = match[2].replace(/^(['"])(.*)\1$/, '$2');
+  }
+  return vars;
+}
+
+/** services/api/.env as key/value pairs; empty when the file does not exist. */
+export function readApiEnvFile(): Record<string, string> {
+  const envFile = resolve(apiDir, '.env');
+  return existsSync(envFile) ? parseEnvFile(readFileSync(envFile, 'utf8')) : {};
+}
+
+export type FusekiEnv = { baseUrl: string; user: string; password: string };
+
+/**
+ * The Fuseki the tests talk to. services/api/.env is the source, and the shell wins: FUSEKI_BASE_URL, or
+ * FUSEKI_PORT (the Compose host port) as a shorthand for localhost.
+ */
+export function resolveFusekiEnv(env: NodeJS.ProcessEnv = process.env): FusekiEnv {
+  const file = readApiEnvFile();
+  const baseUrl =
+    env.FUSEKI_BASE_URL ||
+    (env.FUSEKI_PORT ? `http://localhost:${env.FUSEKI_PORT}` : '') ||
+    file.FUSEKI_BASE_URL ||
+    'http://localhost:3030';
+  return {
+    baseUrl: baseUrl.replace(/\/$/, ''),
+    user: env.FUSEKI_USER || file.FUSEKI_USER || 'admin',
+    password: env.FUSEKI_PASSWORD || file.FUSEKI_PASSWORD || 'admin',
+  };
+}

package/defaults/app-react-native/apps/mobile/__tests__/integration/globalSetup.ts

@@ -0,0 +1,156 @@
+/// <reference types="node" />
+// Before the integration tests: check that the target is this repo's Compose Fuseki, reset the in-memory test
+// dataset, start the API-only backend.
+import { type ChildProcess, spawn, spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+import { API_PORT, API_URL, FUSEKI_DATASET, apiDir, readApiEnvFile, repoRoot, resolveFusekiEnv } from './apiEnv';
+
+// The variables that select S3FileStore (services/api/src/fileStoreEnv.ts); blanked even when unset anywhere.
+const S3_ENV_KEYS = ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_REGION', 'S3_BUCKET_ENDPOINT', 'S3_FILES_BUCKET_NAME'];
+
+// Test hooks: INTEGRATION_API_BIN replaces `linked` (e.g. with a process that never answers) and
+// INTEGRATION_API_TIMEOUT_MS shortens the wait, to exercise the failure cleanup.
+const apiBin = process.env.INTEGRATION_API_BIN || resolve(repoRoot, 'node_modules/.bin/linked');
+const startTimeoutMs = Number(process.env.INTEGRATION_API_TIMEOUT_MS) || 60_000;
+
+async function answers(url: string): Promise<boolean> {
+  try {
+    await fetch(url, { signal: AbortSignal.timeout(1000) });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Refuses unless the target is safe to wipe: the dataset name ends in `-test`, and the Fuseki URL is on localhost at
+ * the host port Docker Compose publishes for this repo's `fuseki` service (so never another project's Fuseki).
+ */
+function assertSafeTarget(baseUrl: string) {
+  const target = `${baseUrl}/$/datasets/${FUSEKI_DATASET}`;
+  const refuse = (reason: string): never => {
+    throw new Error(`Refusing to reset ${target}: ${reason}`);
+  };
+  if (!FUSEKI_DATASET.endsWith('-test')) refuse('the dataset name does not end in "-test".');
+
+  const url = new URL(baseUrl);
+  if (!['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) refuse(`${url.hostname} is not localhost.`);
+  const urlPort = url.port || (url.protocol === 'https:' ? '443' : '80');
+
+  const compose = spawnSync('docker', ['compose', 'port', 'fuseki', '3030'], { cwd: repoRoot, encoding: 'utf8' });
+  const composePort = compose.status === 0 ? /:(\d+)\s*$/.exec(compose.stdout.trim())?.[1] : undefined;
+  if (!composePort) {
+    refuse(
+      `this repo's Compose Fuseki is not running (\`docker compose port fuseki 3030\`: ` +
+        `${(compose.stderr || compose.error?.message || compose.stdout || '').trim()}). Run \`npm run fuseki:up\`.`,
+    );
+  }
+  if (composePort !== urlPort) {
+    refuse(`port ${urlPort} is not the Compose Fuseki port ${composePort}. Set FUSEKI_PORT=${composePort}.`);
+  }
+}
+
+/** Kills the API's whole process group; safe to call repeatedly and after it exited. */
+function killGroup(api: ChildProcess, signal: NodeJS.Signals = 'SIGTERM') {
+  if (!api.pid) return;
+  try {
+    process.kill(-api.pid, signal);
+  } catch {
+    // Already gone.
+  }
+}
+
+export default async function globalSetup() {
+  const fuseki = resolveFusekiEnv();
+
+  // 1. Refuse a foreign target before anything is deleted.
+  assertSafeTarget(fuseki.baseUrl);
+
+  // 2. Fail fast when Fuseki is down. FUSEKI_BASE_URL is passed so the script does not read services/api/.env.
+  const wait = spawnSync(process.execPath, [resolve(apiDir, 'scripts/wait-for-fuseki.mjs')], {
+    env: { ...process.env, FUSEKI_BASE_URL: fuseki.baseUrl },
+    encoding: 'utf8',
+  });
+  if (wait.status !== 0) throw new Error(wait.stderr.trim() || `wait-for-fuseki exited ${wait.status}`);
+
+  if (await answers(API_URL)) {
+    throw new Error(`Port ${API_PORT} is already in use; stop the process on it before running integration tests.`);
+  }
+
+  // 3. Reset: drop the dataset; the API's ensureDatasetExists() recreates it empty on boot.
+  const auth = `Basic ${Buffer.from(`${fuseki.user}:${fuseki.password}`).toString('base64')}`;
+  const del = await fetch(`${fuseki.baseUrl}/$/datasets/${FUSEKI_DATASET}`, {
+    method: 'DELETE',
+    headers: { Authorization: auth },
+  });
+  if (!del.ok && del.status !== 404) {
+    throw new Error(`Deleting Fuseki dataset ${FUSEKI_DATASET} failed: ${del.status} ${await del.text()}`);
+  }
+
+  // 4. Start the API. Every Fuseki variable is explicit, and the S3 ones are blanked, so nothing is taken from
+  // services/api/.env (`linked start` does not override variables that are already set, even when empty).
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  const s3Keys = [...Object.keys(process.env), ...Object.keys(readApiEnvFile()), ...S3_ENV_KEYS];
+  for (const key of s3Keys) if (/^(AWS|S3)_/.test(key)) env[key] = '';
+  // Except AWS_REGION: @_linked/s3 builds a client at import with `AWS_REGION ?? 'us-east-1'`, and an empty region
+  // throws "Region is missing". Removed instead; the blank S3_FILES_BUCKET_NAME already rules out S3FileStore.
+  delete env.AWS_REGION;
+  Object.assign(env, {
+    NODE_ENV: 'development',
+    PORT: String(API_PORT),
+    SITE_ROOT: API_URL,
+    DATA_ROOT: `${API_URL}/data`,
+    FUSEKI_BASE_URL: fuseki.baseUrl,
+    FUSEKI_USER: fuseki.user,
+    FUSEKI_PASSWORD: fuseki.password,
+    FUSEKI_DATASET,
+    FUSEKI_DB_TYPE: 'mem',
+  });
+
+  let output = '';
+  const api = spawn(apiBin, ['start', '--api-only'], {
+    cwd: apiDir,
+    env,
+    // `linked start` spawns its own children (Vite, the server). `detached` gives the CLI its own process group, so
+    // one `kill(-pid)` stops all of them; killing only the CLI's PID would leave the server listening on the port.
+    detached: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  api.stdout?.on('data', (d) => (output += d));
+  api.stderr?.on('data', (d) => (output += d));
+  let exited: number | null = null;
+  api.on('exit', (code) => (exited = code ?? -1));
+
+  // A detached group outlives Jest unless it is killed: on exit, Ctrl+C and SIGTERM too, not only in teardown.
+  const onExit = () => killGroup(api, 'SIGKILL');
+  const onSignal = (signal: NodeJS.Signals) => {
+    killGroup(api);
+    // Re-raise when no one else handles it, so the default (terminate) still happens.
+    if (process.listenerCount(signal) === 0) process.kill(process.pid, signal);
+  };
+  process.once('exit', onExit);
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+  const stop = () => {
+    process.off('exit', onExit);
+    process.off('SIGINT', onSignal);
+    process.off('SIGTERM', onSignal);
+    killGroup(api);
+  };
+  (globalThis as any).__LINKED_API__ = { api, stop, killGroup: (signal: NodeJS.Signals) => killGroup(api, signal) };
+
+  const fail = (message: string): never => {
+    stop();
+    throw new Error(message);
+  };
+
+  // 5. Wait until it answers HTTP (page routes 404, which is fine).
+  const deadline = Date.now() + startTimeoutMs;
+  while (Date.now() < deadline) {
+    if (exited !== null) fail(`The API exited with ${exited} before it answered:\n${output}`);
+    if (await answers(API_URL)) return;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  fail(`The API did not answer on ${API_URL} within ${startTimeoutMs / 1000} s:\n${output}`);
+}

package/defaults/app-react-native/apps/mobile/__tests__/integration/globalTeardown.ts

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+// Stops the API started by globalSetup (its whole process group) and removes its exit and signal handlers.
+import type { ChildProcess } from 'node:child_process';
+
+type StartedApi = { api: ChildProcess; stop: () => void; killGroup: (signal: NodeJS.Signals) => void };
+
+export default async function globalTeardown() {
+  const started: StartedApi | undefined = (globalThis as any).__LINKED_API__;
+  if (!started) return;
+  const { api, stop, killGroup } = started;
+  if (!api.pid || api.exitCode !== null || api.signalCode !== null) {
+    stop();
+    return;
+  }
+  const exited = new Promise((r) => api.once('exit', r));
+  stop();
+  const timer = setTimeout(() => killGroup('SIGKILL'), 5000);
+  await exited;
+  clearTimeout(timer);
+}