mapples 0.2.0-beta.9 → 0.2.0

package/dist/runtime/runtimeFiles.js

@@ -0,0 +1,183 @@
+// The documents the exported app's behaviour runtime executes (@mapples/app
+// `MapplesApp` → `MapplesRuntime`), written next to theme.ts and resolved by
+// `mapplesResolver` (`@mapples/app/expo`) as `mapples::navigation`,
+// `mapples::api` and `mapples::variables`:
+//
+//   mapples/navigation.ts — the navigation document (guards, on-enter actions,
+//                           navigate targets) + each route's expo-router
+//                           screen names, from the same plan as the layouts.
+//   mapples/api.ts        — the API document (requests, environments), the
+//                           secrets its requests name, read from
+//                           EXPO_PUBLIC_MAPPLES_SECRET_<NAME>, and the
+//                           environment override EXPO_PUBLIC_MAPPLES_API_ENVIRONMENT.
+//   mapples/variables.ts  — the project variables (`vars.*`).
+//
+// All three are CLI-OWNED like `_layout.tsx`: regenerated every sync, never
+// pushed back (Creator edits these documents), a user file in their place is
+// deprecated, never overwritten.
+//
+// Secrets outside Creator: Creator runs requests through its backend proxy,
+// which holds the project's secrets. An exported app has no such proxy, so
+// the default transport calls the API directly and applies each request's
+// auth from build-time `EXPO_PUBLIC_MAPPLES_SECRET_<NAME>` variables
+// (`.env.local`). Those values are compiled into the app bundle — fine for
+// publishable/anon keys (Supabase `apikey`, public API keys), wrong for
+// anything that must stay secret: route such requests through your own
+// backend by passing `transport` to `MapplesApp`.
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { ProjectDocumentError } from '../api/client.js';
+import { deprecateFile } from '../merge/deprecate.js';
+export const NAVIGATION_MODULE = join('mapples', 'navigation.ts');
+export const API_MODULE = join('mapples', 'api.ts');
+export const VARIABLES_MODULE = join('mapples', 'variables.ts');
+const HEADER = /^\/\/\s*GENERATED by Mapples/;
+function header(what) {
+    return [
+        `// GENERATED by Mapples — DO NOT EDIT. ${what}`,
+        '// Regenerated on every `mapples sync`; edit it in Creator instead.',
+        '// @mapples/app runs it (MapplesApp reads this file through `mapplesResolver`).',
+    ].join('\n');
+}
+const json = (value) => JSON.stringify(value, null, 2);
+/**
+ * Write a CLI-owned module. A file there the CLI did not generate is the
+ * user's: deprecated (`_depr_<ts>_…`), never overwritten; `content: null`
+ * removes a generated one whose document is gone.
+ */
+function writeOwnedModule(root, file, content, report) {
+    const abs = join(root, file);
+    const existed = existsSync(abs);
+    if (existed) {
+        const current = readFileSync(abs, 'utf8');
+        if (current === content)
+            return;
+        if (!HEADER.test(current)) {
+            const deprecated = relative(root, deprecateFile(abs));
+            report.files.push({
+                file,
+                action: 'deprecated',
+                detail: `${file} is generated from Creator — yours is kept at ${deprecated}`,
+            });
+        }
+        else if (content === null) {
+            unlinkSync(abs);
+            report.files.push({
+                file,
+                action: 'deprecated',
+                detail: 'generated for a Creator document that is gone — removed',
+            });
+            return;
+        }
+    }
+    if (content === null)
+        return;
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+    report.files.push({
+        file,
+        action: existed ? 'updated' : 'created',
+        detail: 'CLI-owned runtime document',
+    });
+}
+/** `mapples/navigation.ts`: the navigation document and each route's screen names. */
+export function writeNavigationModule(root, navigation, screensByRoute, report) {
+    const routes = Object.fromEntries([...screensByRoute].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    const content = [
+        header('The Creator navigation the app runtime executes.'),
+        "import type { NavigationDocument } from '@mapples/types';",
+        '',
+        '/** Guards, on-enter actions and navigate targets resolve against this document. */',
+        `export const navigation = ${json(navigation)} as NavigationDocument;`,
+        '',
+        '/** Route id → its expo-router screen names, from the root navigator down. */',
+        `export const routes: Record<string, string[]> = ${json(routes)};`,
+        '',
+    ].join('\n');
+    writeOwnedModule(root, NAVIGATION_MODULE, content, report);
+}
+/** The env variable a secret reads from: `API_KEY` → `EXPO_PUBLIC_MAPPLES_SECRET_API_KEY`. */
+export function secretEnvName(secretRef) {
+    return `EXPO_PUBLIC_MAPPLES_SECRET_${secretRef.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`;
+}
+function apiModule(document) {
+    // Response samples are design-time data for Creator's pickers and preview;
+    // the app only ever shows real responses.
+    const requests = {};
+    const secretRefs = new Set();
+    for (const [id, request] of Object.entries(document.requests ?? {})) {
+        const rest = { ...request };
+        delete rest.responseSample;
+        requests[id] = rest;
+        if (request.auth?.secretRef)
+            secretRefs.add(request.auth.secretRef);
+    }
+    const refs = [...secretRefs].sort();
+    // Expo inlines `process.env.EXPO_PUBLIC_*` only as literal member reads.
+    const secretLines = refs.map((ref) => `  ${JSON.stringify(ref)}: process.env.${secretEnvName(ref)},`);
+    return [
+        header('The Creator API requests the app runtime executes.'),
+        "import type { ApiDocument } from '@mapples/types';",
+        '',
+        `export const api = ${json({ ...document, requests })} as ApiDocument;`,
+        '',
+        '/**',
+        ' * Secrets the requests name, from build-time env variables (put them in',
+        ' * `.env.local`). They are compiled into the app bundle: only use this for',
+        ' * keys that are safe to ship in a client (publishable / anon keys). For',
+        ' * real secrets pass your own `transport` to <MapplesApp> and keep them on',
+        ' * a server.',
+        ...(refs.length > 0
+            ? [' *', ...refs.map((ref) => ` *   ${secretEnvName(ref)}  (${ref})`)]
+            : []),
+        ' */',
+        `export const secrets: Record<string, string | undefined> = {${secretLines.length > 0 ? `\n${secretLines.join('\n')}\n` : ''}};`,
+        '',
+        '/** The environment to run against (its name or id); unset → the one active in Creator. */',
+        'export const environment = process.env.EXPO_PUBLIC_MAPPLES_API_ENVIRONMENT;',
+        '',
+    ].join('\n');
+}
+function variablesModule(document) {
+    return [
+        header('The Creator variables (`vars.*`) the app runtime holds.'),
+        "import type { VariablesDocument } from '@mapples/types';",
+        '',
+        `export const variables = ${json(document)} as VariablesDocument;`,
+        '',
+    ].join('\n');
+}
+/**
+ * Pull the API and variables documents and write their runtime modules. A
+ * project without one gets no module (the runtime is inert for it). A
+ * document the backend refuses to hand to this project key is reported —
+ * the app then runs without it — and its last generated module is left as
+ * it was rather than guessed at.
+ */
+export async function syncRuntimeDocuments(root, client, report) {
+    const documents = [
+        { kind: 'apidef', file: API_MODULE, render: apiModule, label: 'API requests' },
+        {
+            kind: 'variablesdef',
+            file: VARIABLES_MODULE,
+            render: variablesModule,
+            label: 'variables',
+        },
+    ];
+    for (const { kind, file, render, label } of documents) {
+        let document;
+        try {
+            document = await client.projectDocument(kind);
+        }
+        catch (err) {
+            if (!(err instanceof ProjectDocumentError) || (err.status !== 401 && err.status !== 403)) {
+                throw err;
+            }
+            report.notes.push(`runtime: the Creator ${label} were not pulled — the backend refuses this project key for ${kind} (${err.message}). ` +
+                `The app runs without them until it allows it; ${file} is left as it was.`);
+            continue;
+        }
+        writeOwnedModule(root, file, document === null ? null : render(document), report);
+    }
+}
+//# sourceMappingURL=runtimeFiles.js.map

package/dist/runtime/runtimeFiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeFiles.js","sourceRoot":"","sources":["../../src/runtime/runtimeFiles.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,6EAA6E;AAC7E,oEAAoE;AACpE,2CAA2C;AAC3C,EAAE;AACF,+EAA+E;AAC/E,yEAAyE;AACzE,6EAA6E;AAC7E,2EAA2E;AAC3E,iEAAiE;AACjE,uEAAuE;AACvE,sFAAsF;AACtF,8DAA8D;AAC9D,EAAE;AACF,4EAA4E;AAC5E,6EAA6E;AAC7E,iCAAiC;AACjC,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,0EAA0E;AAC1E,qEAAqE;AACrE,2EAA2E;AAC3E,wEAAwE;AACxE,uEAAuE;AACvE,kDAAkD;AAElD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEpD,OAAO,EAAE,oBAAoB,EAAqB,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGtD,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;AAClE,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AACpD,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;AAEhE,MAAM,MAAM,GAAG,8BAA8B,CAAC;AAE9C,SAAS,MAAM,CAAC,IAAY;IAC1B,OAAO;QACL,0CAA0C,IAAI,EAAE;QAChD,qEAAqE;QACrE,iFAAiF;KAClF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,IAAI,GAAG,CAAC,KAAc,EAAU,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AAExE;;;;GAIG;AACH,SAAS,gBAAgB,CACvB,IAAY,EACZ,IAAY,EACZ,OAAsB,EACtB,MAAkB;IAElB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7B,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC1C,IAAI,OAAO,KAAK,OAAO;YAAE,OAAO;QAChC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1B,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC;YACtD,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;gBAChB,IAAI;gBACJ,MAAM,EAAE,YAAY;gBACpB,MAAM,EAAE,GAAG,IAAI,iDAAiD,UAAU,EAAE;aAC7E,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YAC5B,UAAU,CAAC,GAAG,CAAC,CAAC;YAChB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;gBAChB,IAAI;gBACJ,MAAM,EAAE,YAAY;gBACpB,MAAM,EAAE,yDAAyD;aAClE,CAAC,CAAC;YACH,OAAO;QACT,CAAC;IACH,CAAC;IACD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO;IAC7B,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC5B,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;QAChB,IAAI;QACJ,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;QACvC,MAAM,EAAE,4BAA4B;KACrC,CAAC,CAAC;AACL,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,qBAAqB,CACnC,IAAY,EACZ,UAAmB,EACnB,cAAqC,EACrC,MAAkB;IAElB,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAC/B,CAAC,GAAG,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACrE,CAAC;IACF,MAAM,OAAO,GAAG;QACd,MAAM,CAAC,kDAAkD,CAAC;QAC1D,2DAA2D;QAC3D,EAAE;QACF,qFAAqF;QACrF,6BAA6B,IAAI,CAAC,UAAU,CAAC,yBAAyB;QACtE,EAAE;QACF,+EAA+E;QAC/E,mDAAmD,IAAI,CAAC,MAAM,CAAC,GAAG;QAClE,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAC7D,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,OAAO,8BAA8B,SAAS,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,EAAE,CAAC;AAC7F,CAAC;AAOD,SAAS,SAAS,CAAC,QAA0B;IAC3C,2EAA2E;IAC3E,0CAA0C;IAC1C,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC,cAAc,CAAC;QAC3B,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;QACpB,IAAI,OAAO,CAAC,IAAI,EAAE,SAAS;YAAE,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC;IACpC,yEAAyE;IACzE,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAC1B,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,iBAAiB,aAAa,CAAC,GAAG,CAAC,GAAG,CACxE,CAAC;IACF,OAAO;QACL,MAAM,CAAC,oDAAoD,CAAC;QAC5D,oDAAoD;QACpD,EAAE;QACF,sBAAsB,IAAI,CAAC,EAAE,GAAG,QAAQ,EAAE,QAAQ,EAAE,CAAC,kBAAkB;QACvE,EAAE;QACF,KAAK;QACL,0EAA0E;QAC1E,4EAA4E;QAC5E,0EAA0E;QAC1E,4EAA4E;QAC5E,cAAc;QACd,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;YACjB,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,aAAa,CAAC,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;YACtE,CAAC,CAAC,EAAE,CAAC;QACP,KAAK;QACL,+DAA+D,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI;QAChI,EAAE;QACF,4FAA4F;QAC5F,6EAA6E;QAC7E,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,eAAe,CAAC,QAAiB;IACxC,OAAO;QACL,MAAM,CAAC,yDAAyD,CAAC;QACjE,0DAA0D;QAC1D,EAAE;QACF,4BAA4B,IAAI,CAAC,QAAQ,CAAC,wBAAwB;QAClE,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAY,EACZ,MAAoB,EACpB,MAAkB;IAElB,MAAM,SAAS,GAAG;QAChB,EAAE,IAAI,EAAE,QAAiB,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,EAAE;QACvF;YACE,IAAI,EAAE,cAAuB;YAC7B,IAAI,EAAE,gBAAgB;YACtB,MAAM,EAAE,eAAe;YACvB,KAAK,EAAE,WAAW;SACnB;KACF,CAAC;IACF,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,SAAS,EAAE,CAAC;QACtD,IAAI,QAAiB,CAAC;QACtB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,CAAC,GAAG,YAAY,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,EAAE,CAAC;gBACzF,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,MAAM,CAAC,KAAK,CAAC,IAAI,CACf,wBAAwB,KAAK,+DAA+D,IAAI,KAAK,GAAG,CAAC,OAAO,KAAK;gBACnH,iDAAiD,IAAI,qBAAqB,CAC7E,CAAC;YACF,SAAS;QACX,CAAC;QACD,gBAAgB,CACd,IAAI,EACJ,IAAI,EACJ,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,QAA4B,CAAC,EAC/D,MAAM,CACP,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/services/appDeps.d.ts

@@ -0,0 +1,41 @@
+export type PackageManager = 'yarn' | 'pnpm' | 'bun' | 'npm';
+/**
+ * Refuse an app `init` cannot make runnable. Mapples writes screens as
+ * expo-router route files (`app/(mapples)/…`), so the app must be an Expo app
+ * that boots expo-router, with its dependencies installed (the Expo SDK's
+ * native-module versions are read from the installed `expo`).
+ */
+export declare function assertLinkableApp(root: string): void;
+/**
+ * The installed Expo SDK's native-module pins (`expo/bundledNativeModules.json`),
+ * or `null` when the app's dependencies are not installed yet (a fresh
+ * `mapples create`) — callers then use the versions they were given.
+ */
+export declare function installedSdkPins(root: string): Record<string, string> | null;
+export interface AddedDependency {
+    name: string;
+    spec: string;
+    dev: boolean;
+}
+/**
+ * Add every dependency of the `mapples create` app that this app lacks
+ * (never changes an existing entry). Versions: `@mapples/*` get the one
+ * runtime spec, Expo SDK modules the version the installed SDK bundles,
+ * everything else the template's. Returns what was added (empty = nothing to do)
+ * plus existing `@mapples/*` entries whose spec differs from the runtime spec.
+ */
+export declare function addRuntimeDependencies(root: string): {
+    added: AddedDependency[];
+    mismatched: {
+        name: string;
+        spec: string;
+        expected: string;
+    }[];
+};
+/** The app's package manager, from its lockfile (npm when there is none). */
+export declare function detectPackageManager(root: string): PackageManager;
+/**
+ * Run `<pm> install` in the app, output streamed. Throws when it fails;
+ * `retry` is what the user runs once the install is fixed.
+ */
+export declare function runInstall(root: string, pm: PackageManager, retry?: string): void;

package/dist/services/appDeps.js

@@ -0,0 +1,152 @@
+// `mapples init` on an existing app: check the app can host Mapples routes
+// (an Expo app on expo-router) BEFORE anything is written, then add the
+// runtime dependencies the synced files import and install them with the
+// app's own package manager. The template package.json is the source of the
+// dependency list, so `create` and `init` apps depend on the same things.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { cliVersion, mapplesRuntimeSpec } from '../version.js';
+import { templatesDir } from './scaffold.js';
+function readPackageJson(root) {
+    return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+}
+function hasDep(pkg, name) {
+    return Boolean(pkg.dependencies?.[name] ?? pkg.devDependencies?.[name]);
+}
+/** True when the app boots through expo-router (`main` is its entry, or a local entry file that imports it). */
+function bootsExpoRouter(root, pkg) {
+    if (pkg.main === 'expo-router/entry')
+        return true;
+    if (!pkg.main)
+        return false; // Expo's default entry renders App.tsx
+    const entry = resolve(root, pkg.main);
+    const candidates = [entry, `${entry}.js`, `${entry}.ts`, `${entry}.tsx`];
+    const file = candidates.find((c) => existsSync(c));
+    return file ? /['"]expo-router\/entry['"]/.test(readFileSync(file, 'utf8')) : false;
+}
+/**
+ * Refuse an app `init` cannot make runnable. Mapples writes screens as
+ * expo-router route files (`app/(mapples)/…`), so the app must be an Expo app
+ * that boots expo-router, with its dependencies installed (the Expo SDK's
+ * native-module versions are read from the installed `expo`).
+ */
+export function assertLinkableApp(root) {
+    const pkg = readPackageJson(root);
+    if (!hasDep(pkg, 'expo')) {
+        throw new Error('`mapples init` links an Expo app, and this package.json has no `expo` dependency.\n' +
+            '  Start a new app with `npx mapples create <name>` instead.');
+    }
+    if (!hasDep(pkg, 'expo-router') || !bootsExpoRouter(root, pkg)) {
+        throw new Error([
+            `this app does not use expo-router (package.json "main" is ${JSON.stringify(pkg.main ?? 'expo/AppEntry')}),`,
+            '  but Mapples syncs screens as expo-router routes — nothing would render them. Nothing was changed.',
+            '  Either start from `npx mapples create <name>` (a ready expo-router app), or move this app to',
+            '  expo-router first (https://docs.expo.dev/router/installation/#modify-project-configuration):',
+            '    npx expo install expo-router expo-linking expo-constants react-native-screens react-native-safe-area-context',
+            '    set "main": "expo-router/entry" in package.json and a "scheme" in app.json (expo install adds the plugin),',
+            '    move App.tsx into app/index.tsx — then re-run `mapples init`.',
+        ].join('\n'));
+    }
+    bundledNativeModules(root); // throws when dependencies are not installed yet
+}
+function bundledNativeModules(root) {
+    const require = createRequire(join(root, 'package.json'));
+    let path;
+    try {
+        path = require.resolve('expo/bundledNativeModules.json');
+    }
+    catch (err) {
+        throw new Error(`cannot find the installed \`expo\` package in ${root} — install the app's dependencies first, then re-run \`mapples init\``, { cause: err });
+    }
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+/**
+ * The installed Expo SDK's native-module pins (`expo/bundledNativeModules.json`),
+ * or `null` when the app's dependencies are not installed yet (a fresh
+ * `mapples create`) — callers then use the versions they were given.
+ */
+export function installedSdkPins(root) {
+    let path;
+    try {
+        path = createRequire(join(root, 'package.json')).resolve('expo/bundledNativeModules.json');
+    }
+    catch (err) {
+        if (err.code === 'MODULE_NOT_FOUND')
+            return null;
+        throw err;
+    }
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+/**
+ * Add every dependency of the `mapples create` app that this app lacks
+ * (never changes an existing entry). Versions: `@mapples/*` get the one
+ * runtime spec, Expo SDK modules the version the installed SDK bundles,
+ * everything else the template's. Returns what was added (empty = nothing to do)
+ * plus existing `@mapples/*` entries whose spec differs from the runtime spec.
+ */
+export function addRuntimeDependencies(root) {
+    const pkg = readPackageJson(root);
+    const template = JSON.parse(readFileSync(join(templatesDir(), 'package.json'), 'utf8'));
+    const bundled = bundledNativeModules(root);
+    const expoDeps = JSON.parse(readFileSync(createRequire(join(root, 'package.json')).resolve('expo/package.json'), 'utf8')).dependencies ?? {};
+    const runtime = mapplesRuntimeSpec();
+    const added = [];
+    const mismatched = [];
+    const specFor = (name, templateSpec) => {
+        if (name.startsWith('@mapples/'))
+            return runtime;
+        if (templateSpec === '__CLI_VERSION__')
+            return cliVersion();
+        // The installed SDK's own pins first (native modules, then expo's direct
+        // deps such as babel-preset-expo), the template's for everything else.
+        return bundled[name] ?? expoDeps[name] ?? templateSpec;
+    };
+    for (const [field, dev] of [
+        ['dependencies', false],
+        ['devDependencies', true],
+    ]) {
+        for (const [name, templateSpec] of Object.entries(template[field] ?? {})) {
+            const existing = pkg.dependencies?.[name] ?? pkg.devDependencies?.[name];
+            if (existing) {
+                if (name.startsWith('@mapples/') && existing !== runtime) {
+                    mismatched.push({ name, spec: existing, expected: runtime });
+                }
+                continue;
+            }
+            const spec = specFor(name, templateSpec);
+            pkg[field] = { ...(pkg[field] ?? {}), [name]: spec };
+            added.push({ name, spec, dev });
+        }
+        const deps = pkg[field];
+        if (deps)
+            pkg[field] = Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a.localeCompare(b)));
+    }
+    if (added.length > 0)
+        writeFileSync(join(root, 'package.json'), JSON.stringify(pkg, null, 2) + '\n');
+    return { added, mismatched };
+}
+/** The app's package manager, from its lockfile (npm when there is none). */
+export function detectPackageManager(root) {
+    if (existsSync(join(root, 'yarn.lock')))
+        return 'yarn';
+    if (existsSync(join(root, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (existsSync(join(root, 'bun.lock')) || existsSync(join(root, 'bun.lockb')))
+        return 'bun';
+    return 'npm';
+}
+/**
+ * Run `<pm> install` in the app, output streamed. Throws when it fails;
+ * `retry` is what the user runs once the install is fixed.
+ */
+export function runInstall(root, pm, retry = '`mapples init`') {
+    const result = spawnSync(pm, ['install'], { cwd: root, stdio: 'inherit' });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0) {
+        throw new Error(`\`${pm} install\` failed (exit ${result.status}) — package.json already lists the Mapples dependencies; fix the install and re-run ${retry}`);
+    }
+}
+//# sourceMappingURL=appDeps.js.map

package/dist/services/appDeps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appDeps.js","sourceRoot":"","sources":["../../src/services/appDeps.ts"],"names":[],"mappings":"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"}

package/dist/services/appPackages.d.ts

@@ -0,0 +1,46 @@
+import { type JpatchClient } from '../api/client.js';
+import { type PackagesDocument } from '../packages/resolve.js';
+import { type PackageManager } from './appDeps.js';
+export declare const PACKAGES_STATE_FILE: string;
+export interface PackagesOutcome {
+    /** `document`: read from the project's packages document; `canvas`: derived (no document yet). */
+    source: 'document' | 'canvas';
+    iconFamily: string;
+    added: {
+        name: string;
+        spec: string;
+        package: string;
+    }[];
+    removed: {
+        name: string;
+        spec: string;
+    }[];
+    /** Not needed by the project any more, left in place — remove by hand if unused. */
+    removable: {
+        name: string;
+        reason: string;
+    }[];
+    pluginsAdded: string[];
+    pluginsRemoved: string[];
+    /** Plugins to register by hand (the app config is code, not app.json). */
+    pluginsManual: string[];
+    /** package.json changed: the app needs `<pm> install`. */
+    installNeeded: boolean;
+    packageManager: PackageManager;
+    notes: string[];
+}
+/** The project's packages document, `null` when it has none yet (404). Any other refusal stops the command. */
+export declare function fetchPackagesDocument(client: JpatchClient): Promise<PackagesDocument | null>;
+/**
+ * Bring package.json (and app.json's plugins) in line with the project's
+ * packages. Reads the synced canvas from the base, so call it after a
+ * successful sync. A transport failure propagates (the caller reports
+ * offline); a refused or malformed document stops the command.
+ */
+export declare function syncAppPackages(root: string, client: JpatchClient): Promise<PackagesOutcome | {
+    skipped: string;
+}>;
+/** Human lines for the command output (the JSON report carries the outcome itself). */
+export declare function renderPackagesOutcome(outcome: PackagesOutcome | {
+    skipped: string;
+}): string[];