@nativescript/cloudflare-expo-desktop 0.0.0-stage → 0.1.0-alpha.0

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# @nativescript/cloudflare-expo-desktop
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runs an ns-edge project made from the `expo` template on a Mac, in the ns-edge Expo Desktop shell: React Native for macOS on Hermes, with AppKit and Foundation through `@nativescript/react-native` worklets. The app's window streams to the project's browser IDE, where people click into it.
+
+```sh
+npx @nativescript/cloudflare-cli live --expo                                       # create a project and run it here
+npx @nativescript/cloudflare-expo-desktop '<device link>' [--yes] [--allow-eval]   # run an existing one
+```
+
+The first run of each version unpacks the shell to `~/Library/Caches/ns-edge/expo-desktop/<version>/`. The shell asks before joining: the project's code runs in a sandboxed app that can reach the network, and anyone with the write key can watch and click its window. `--allow-eval` lets the agent's `runOnDevice` run code on the app's main thread.
+
+Projects import `react`, `react-native` and `@nativescript/react-native`, which the shell links. The edge compiles each module to CommonJS for Hermes, including `"worklet"` functions, so the shell needs no bundler. If a new version throws while rendering, the shell keeps showing the last version that rendered.
+
+The shell is `apps/expo-desktop-shell` in the ns-cloudflare repo; `npm pack` here packs its Release build (`NS_EXPO_APP` points at another build). `NS_EDGE_DEBUG=1` shows the app's own log output.
+
+Apple Silicon, macOS 14.4 or later, Node 22.15 or later.

package/bin.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// Starts the ns-edge Expo Desktop shell on a project.
+//   npx @nativescript/cloudflare-expo-desktop '<device link>' [--yes] [--allow-eval]
+import { execFileSync, spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { homedir, release } from 'node:os';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { parseArgs } from 'node:util';
+
+const USAGE = `Usage: ns-edge-expo-desktop <device link> [options]
+
+Runs an ns-edge expo project on this Mac and streams its window to the project's IDE.
+The device link is the project's https://<host>/p/<id>#<device key> link.
+
+Options:
+  --yes            Join without asking
+  --allow-eval     Let the project's agent run arbitrary code in the app (runOnDevice)
+
+NS_EDGE_DEBUG=1 shows the app's own log output too.
+`;
+const LINK = /^https?:\/\/[^/#]+\/p\/[0-9a-f]{32}\/?#[0-9a-f]{32}$/;
+/** Lines kept from the app's own output, shown if it crashes. */
+const TAIL_LINES = 30;
+
+const out = (line) => process.stderr.write(`${line}\n`);
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      yes: { type: 'boolean', default: false },
+      'allow-eval': { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+  });
+  const link = positionals[0]?.trim();
+  if (values.help || !link) return out(USAGE);
+  if (!LINK.test(link)) throw new Error(`Not a device link: ${link}\nExpected https://<host>/p/<project id>#<device key>`);
+
+  const [major, minor] = release().split('.').map(Number);
+  if (process.platform !== 'darwin' || process.arch !== 'arm64' || major < 23 || (major === 23 && minor < 4)) {
+    throw new Error('The Expo Desktop shell runs on an Apple Silicon Mac with macOS 14.4 or later.');
+  }
+
+  out(`Project: ${link.replace(/#.*$/, '')}`);
+  out("Its code will run in a sandboxed app that can reach the network, and anyone with the project's write key");
+  out(`can watch and click its window${values['allow-eval'] ? ' and run code in it' : ''}.`);
+  if (!values.yes) {
+    if (!process.stdin.isTTY) throw new Error('Not a terminal: pass --yes to join without asking.');
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const answer = await rl.question('Join? [y/N] ');
+    rl.close();
+    if (!/^y(es)?$/i.test(answer.trim())) return out('Not joined.');
+  }
+
+  const app = extractedApp();
+  const child = spawn(join(app, 'Contents/MacOS/NSEdgeExpo'), [link, ...(values['allow-eval'] ? ['--allow-eval'] : [])], {
+    stdio: ['ignore', 'ignore', 'pipe'],
+  });
+  const tail = [];
+  createInterface({ input: child.stderr }).on('line', (line) => {
+    if (line.startsWith('[ns-edge]') || process.env.NS_EDGE_DEBUG) return out(line);
+    tail.push(line);
+    if (tail.length > TAIL_LINES) tail.shift();
+  });
+  for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => child.kill(signal));
+  child.on('exit', (code, signal) => {
+    if ((signal && signal !== 'SIGINT' && signal !== 'SIGTERM') || (code !== null && code !== 0)) {
+      out(`[ns-edge] the Expo Desktop shell stopped (${signal ?? `code ${code}`}). Its last output:\n${tail.join('\n')}`);
+      process.exit(1);
+    }
+    process.exit(0);
+  });
+}
+
+/**
+ * The app ships as a tarball (npm drops the symlinks an .app's frameworks
+ * need) and is unpacked once per package version, outside the npx cache so
+ * it survives cache cleanups.
+ */
+function extractedApp() {
+  const pkg = import.meta.dirname;
+  const { version } = JSON.parse(readFileSync(join(pkg, 'package.json'), 'utf8'));
+  const dir = join(homedir(), 'Library/Caches/ns-edge/expo-desktop', version);
+  const app = join(dir, 'NSEdgeExpo.app');
+  if (existsSync(app)) return app;
+  out('[ns-edge] unpacking the Expo Desktop shell (once per version)…');
+  const staging = `${dir}.partial-${process.pid}`;
+  rmSync(staging, { recursive: true, force: true });
+  mkdirSync(staging, { recursive: true });
+  execFileSync('tar', ['-xzf', join(pkg, 'NSEdgeExpo.app.tar.gz'), '-C', staging]);
+  mkdirSync(join(dir, '..'), { recursive: true });
+  rmSync(dir, { recursive: true, force: true });
+  renameSync(staging, dir);
+  return app;
+}
+
+main().catch((e) => {
+  out(String(e instanceof Error ? e.message : e));
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@nativescript/cloudflare-expo-desktop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.0",
+  "description": "Runs an ns-edge expo project on a Mac: React Native for macOS on Hermes with NativeScript's AppKit access, its window streamed to the browser IDE",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "ns-edge-expo-desktop": "./bin.mjs"
+  },
+  "engines": {
+    "node": ">=22.15"
+  },
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "scripts": {
+    "prepack": "node scripts/app.mjs"
+  },
+  "files": [
+    "bin.mjs",
+    "NSEdgeExpo.app.tar.gz"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  }
+}