@_linked/cli 1.13.0 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 1.15.0
+
+### Minor Changes
+
+- [#86](https://github.com/linked-cm/cli/pull/86) [`1f8908f`](https://github.com/linked-cm/cli/commit/1f8908fa276a5b65ed3ffe1c1e3bc23417ef9043) Thanks [@flyon](https://github.com/flyon)! - Always rewrite emitted ESM import specifiers
+
+  `linked build` appends `.js` (or `/index.js`) to relative specifiers in `lib/esm` for every package, with no
+  opt-in. The rewrite covers the emitted `.d.ts` declarations as well as the `.js`, so consumers on TypeScript
+  `node16`/`nodenext` resolution get valid declarations. For a package that already writes `.js` specifiers the
+  rewrite is a no-op.
+
+  It runs at the end of the build, after the assets and hand-written declarations have been copied into `lib` and
+  after stale output has been removed, so every specifier is resolved against the files the package actually ships.
+  Asset imports such as `./styles.scss` resolve and are left as written, copied `.d.ts` files are rewritten too, and
+  a leftover `x.js` can no longer make `./x` point at a file the cleanup then deletes.
+
+  Also in this release:
+
+  - The `missing_extension` rule is gone from the import check, in the build gate and in `linked check-imports`.
+    Extensionless relative imports in source no longer fail the build; the rewrite warns about any relative
+    specifier it cannot resolve, and Vite, Metro and `tsc` catch the rest. `outside_package` and the
+    internal-import rule remain hard errors for every package.
+  - The rule that stops a package reaching into another Linked package's internals now actually fires. It matched
+    only import paths containing the literal string `lincd`, so after the rename to the `@_linked/*` scope it was a
+    no-op for every current package: `@_linked/core/lib/esm/utils/Shape` passed. It now matches `@_linked/<pkg>/...`
+    as well as `lincd`-prefixed package names, on a `/src/` or `/lib/` path segment, and is called
+    `isInternalLinkedImport`. This can fail builds that previously passed — which is the point: such an import
+    breaks when the other package changes its build layout and bypasses its exports map. Import the public subpath
+    instead. Relative specifiers are exempt, so a local `./lib/helpers` is still fine.
+  - Both import rules now see every form that names a module — `export ... from`, `import()` in value and type
+    position, and `import x = require()` — not just `import ... from`.
+  - `linked check-imports` prints the report and exits 1 when an import is invalid, instead of exiting 0.
+  - `linked build` reports failures accurately: a step that fails names itself instead of a bare "Build failed",
+    and a failed build always exits non-zero, including under `--silent` and when building updated packages.
+  - `isImportOutsideOfPackage` normalises the path before judging it, so `./a..b` is no longer flagged and
+    `../a/../b` is counted as the one level it actually climbs.
+  - A relative specifier with a trailing slash (`./file/`) names a directory, so it resolves to `./file/index.js`
+    and never to a sibling `./file.js`.
+
+  A package without a `tsconfig-esm.json` has no ESM build, so the rewrite step is skipped rather than failing. When
+  `tsconfig-esm.json` is present but `lib/esm` was not emitted, the build fails.
+
+## 1.14.1
+
+### Patch Changes
+
+- [#83](https://github.com/linked-cm/cli/pull/83) [`566cb44`](https://github.com/linked-cm/cli/commit/566cb44f8728f25e852987ed4426063df9575492) Thanks [@flyon](https://github.com/flyon)! - React Native template: the integration test setup now tells apart "Docker is not installed", "Docker Compose is unavailable" and "Compose Fuseki is not running" (unit-tested in the scaffold); the integration Jest config comment says "Integration tests". README: document that `linked build` exits 1 whenever the build does not succeed (including in a `linkedApp` or a package without `linkedPackage: true`), and 0 with warnings. Reworded a stale migration comment in `linked start`.
+
+## 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

package/README.md

@@ -41,6 +41,10 @@ linked build-updated              # incremental: only packages that changed sinc
 linked build-package <file>       # walk up from a file path to find its package and rebuild
 ```
 
+`linked build` exits with code 1 whenever the build does not succeed, including when it is run in a `linkedApp` or
+in a package without `"linkedPackage": true` (it used to exit 0 there). A build that finishes with warnings still
+exits 0.
+
 ### Publishing / release
 
 ```bash
@@ -62,6 +66,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 +93,38 @@ The CLI recognizes two flags in `package.json`:
 
 The legacy `lincd: true` / `lincdApp: true` flags are no longer read. Migrate to `linkedPackage` / `linkedApp`.
 
+### Extensionless relative imports
+
+Package source may use extensionless relative imports (`./shapes/Example` rather than `./shapes/Example.js`) —
+useful for a shapes package consumed as TypeScript source by Metro, which does not map `.js` specifiers to `.ts`
+files. No configuration is needed. After compiling ESM, `linked build` rewrites every relative specifier in
+`lib/esm` — in the emitted `.js` and in the `.d.ts` declarations beside them, so consumers on TypeScript
+`node16`/`nodenext` resolution get valid declarations — to `./x.js` or `./dir/index.js`, so Node can load the
+output. For a package that already writes `.js` specifiers the rewrite is a no-op.
+
+The build finishes "with warnings" and lists each relative specifier it could not resolve (left unchanged), and
+fails when `tsconfig-esm.json` is present but `lib/esm` was not emitted. A package without a `tsconfig-esm.json`
+has no ESM build, so the step is skipped.
+
+The import check (`linked check-imports`, also run as the first build step) still fails the build for imports
+that reach outside the package source root, and for imports into another linked package's `/src/` or `/lib/`.
+
+## 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 +147,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 with extensionless imports; `linked build`
+                            rewrites the emitted specifiers so lib/esm is Node-loadable
+  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. No configuration is needed — `linked build` always adds `.js` to the
+  relative specifiers in the emitted `lib/esm` JS and declarations. 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__/composePort.test.ts

@@ -0,0 +1,33 @@
+import { describeComposePortFailure } from './integration/apiEnv';
+
+describe('describeComposePortFailure', () => {
+  test('docker not installed', () => {
+    const error = Object.assign(new Error('spawnSync docker ENOENT'), { code: 'ENOENT' });
+    expect(describeComposePortFailure({ error, status: null })).toMatch(/^Docker is not installed/);
+  });
+
+  test('docker compose unavailable', () => {
+    const message = describeComposePortFailure({
+      status: 1,
+      stderr: "docker: 'compose' is not a docker command.\nSee 'docker --help'",
+    });
+    expect(message).toMatch(/^Docker Compose is not available/);
+    expect(message).toContain('is not a docker command');
+  });
+
+  test('non-zero exit mentioning compose', () => {
+    expect(describeComposePortFailure({ status: 125, stderr: 'unknown command: docker compose' })).toMatch(
+      /^Docker Compose is not available/,
+    );
+  });
+
+  test('service not running', () => {
+    const message = describeComposePortFailure({ status: 1, stderr: 'service "fuseki" is not running' });
+    expect(message).toMatch(/Compose Fuseki is not running/);
+    expect(message).toContain('npm run fuseki:up');
+  });
+
+  test('exit 0 without a port counts as not running', () => {
+    expect(describeComposePortFailure({ status: 0, stdout: '' })).toMatch(/Compose Fuseki is not running/);
+  });
+});

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,75 @@
+/// <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')) : {};
+}
+
+/** The parts of a `spawnSync('docker', ['compose', 'port', 'fuseki', '3030'])` result that explain a failure. */
+export type ComposePortResult = {
+  error?: (Error & { code?: string }) | undefined;
+  status: number | null;
+  stdout?: string | null;
+  stderr?: string | null;
+};
+
+/**
+ * Why `docker compose port fuseki 3030` gave no port: Docker is not installed, Docker Compose is unavailable, or
+ * this repo's Compose Fuseki is not running.
+ */
+export function describeComposePortFailure(result: ComposePortResult): string {
+  const output = (result.stderr || result.error?.message || result.stdout || '').trim();
+  if (result.error?.code === 'ENOENT') {
+    return 'Docker is not installed or not on PATH (`docker` could not be started). Install Docker, then run `npm run fuseki:up`.';
+  }
+  const composeMissing =
+    /is not a docker command/i.test(output) ||
+    (result.status !== 0 && /compose/i.test(output) && !/not running|no container/i.test(output));
+  if (composeMissing) {
+    return `Docker Compose is not available (\`docker compose port fuseki 3030\`: ${output}). Install the Docker Compose plugin, then run \`npm run fuseki:up\`.`;
+  }
+  return `this repo's Compose Fuseki is not running (\`docker compose port fuseki 3030\`: ${output}). Run \`npm run fuseki:up\`.`;
+}
+
+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',
+  };
+}