@nativescript/cloudflare-cli 0.1.0-beta.1 → 0.1.0-beta.11

package/README.md

@@ -1,10 +1,21 @@
 # @nativescript/cloudflare-cli
 
+```sh
+npx @nativescript/cloudflare-cli live          # a phone app: opens the IDE and prints a QR code for NativeScript Preview
+npx @nativescript/cloudflare-cli live --react  # the same with a framework: --ng (Angular), --react, --vue, --svelte or --solid
+npx @nativescript/cloudflare-cli live --mac    # a Mac app: opens the IDE and runs the app on this Mac, streamed into the IDE
+npx @nativescript/cloudflare-cli live --electron   # an Electron app with native views, run the same way
+```
+
+`live` creates a project on preview.nativescript.org (`--server` or `NS_EDGE_SERVER` for another edge), saves it to `.ns-edge.json` and opens its IDE. The framework flags are `ns create`'s (`--ng`/`--angular`, `--react`, `--vue`, `--svelte`, `--solid`, `--ts`); without one a phone project is plain TypeScript with XML views. Run it again in the same folder to reopen that project (no flag needed), or add `--new` for another; a flag for a different kind of project than the folder's asks for `--new`. `--from <sample>` starts from a copy of a shared project instead: a sample's name (`--from expo-settings`; `samples` lists them), or any project's link or bare id. While `live` runs a Mac app it restarts the app if it crashes, unless it crashes three times in a minute. Without a create token the project is free: a few hosted agent turns a day, no backend, deleted after 30 days unused. `--no-open` skips the browser; with `--mac` or `--electron`, `--allow-eval` lets the agent run code on this Mac.
+
+## Mirror a local project
+
 Mirror a NativeScript project into an ns-edge project from a terminal or a Vite dev server.
 
 ```sh
 npm i -D @nativescript/cloudflare-cli@beta
-npx ns-edge create --server https://preview.nativescript.org --token <create token>
+npx ns-edge create --server https://preview.nativescript.org --token <create token>   # --template vue for nativescript-vue
 npx ns-edge watch        # push, then every save
 npx ns-edge qr           # print the pairing QR code again
 ```

package/dist/bin.js

@@ -1,12 +1,46 @@
 #!/usr/bin/env node
-import { watch } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { existsSync, watch } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
-import { join, sep } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import QRCode from 'qrcode';
 import { applyChanges, collect, createProject, projectUrl, report, SYNCED } from './sync.js';
 const CONFIG = '.ns-edge.json';
 const DEBOUNCE_MS = 120;
+const LIVE_SERVER = process.env.NS_EDGE_SERVER ?? 'https://preview.nativescript.org';
+/** The hosts `live --desktop` (or `--mac`, `--windows`), `--electron` and `--expo` run; bump them with each host release this CLI is tested against. */
+const DESKTOP_HOSTS = {
+    macos: { spec: '@nativescript/cloudflare-desktop@0.1.0-alpha.6', bin: 'ns-edge-desktop' },
+    electron: { spec: '@nativescript/cloudflare-electron@0.1.0-alpha.3', bin: 'ns-edge-electron' },
+    expo: { spec: '@nativescript/cloudflare-expo-desktop@0.1.0-alpha.1', bin: 'ns-edge-expo-desktop' },
+};
+const DESKTOP_TEMPLATES = new Set(['macos', 'electron', 'expo']);
+/** The macos template is the desktop one: it runs on a Mac with AppKit and on Windows with WinUI, so all three flags pick it. */
+const DESKTOP_FLAGS = { macos: ['desktop', 'mac', 'windows'], electron: ['electron'], expo: ['expo'] };
+/** The NativeScript CLI's `ns create` framework flags, so `live` and `create` take the same ones. */
+const FRAMEWORK_FLAGS = {
+    angular: ['ng', 'angular'],
+    react: ['react', 'reactjs'],
+    vue: ['vue', 'vuejs'],
+    svelte: ['svelte'],
+    solid: ['solid', 'solidjs'],
+    core: ['ts', 'tsc', 'typescript'],
+};
+const TEMPLATE_KINDS = {
+    core: 'a phone',
+    angular: 'an Angular phone',
+    react: 'a React phone',
+    vue: 'a Vue phone',
+    svelte: 'a Svelte phone',
+    solid: 'a Solid phone',
+    macos: 'a desktop',
+    electron: 'an Electron',
+    expo: 'an Expo Desktop',
+};
+const MAX_CRASHES = 3;
+const CRASH_WINDOW_MS = 60_000;
+const RESTART_DELAY_MS = 1000;
 const [cmd = 'help', ...args] = process.argv.slice(2);
 /**
  * Editors and tools write temp, swap and backup files next to the real one
@@ -18,6 +52,23 @@ const flag = (name) => {
     const i = args.indexOf(`--${name}`);
     return i >= 0 ? args[i + 1] : undefined;
 };
+const has = (name) => args.includes(`--${name}`);
+/** The template --template, a framework flag or a desktop flag asks for, if any; asking for two is an error. */
+function requestedTemplate() {
+    const asked = new Set();
+    const named = flag('template');
+    if (named)
+        asked.add(named);
+    for (const [template, names] of Object.entries(FRAMEWORK_FLAGS))
+        if (names.some((name) => has(name)))
+            asked.add(template);
+    for (const [template, names] of Object.entries(DESKTOP_FLAGS))
+        if (names.some((name) => has(name)))
+            asked.add(template);
+    if (asked.size > 1)
+        throw new Error(`Pick one kind of project: this asked for ${[...asked].join(' and ')}.`);
+    return [...asked][0];
+}
 const root = process.cwd();
 async function loadRef() {
     let ref;
@@ -52,10 +103,172 @@ async function printPairing(ref) {
     console.log(`  device  ${device}`);
     console.log(`  ide     ${url}/#key=${ref.writeKey}`);
 }
+/** This folder's project, if it has one the server still knows. */
+/**
+ * The project `--from` names: a link to it (its IDE, read-only or device link),
+ * a bare id, or a sample's name on this CLI's server, with what it was made as.
+ */
+async function sourceProject(from) {
+    let server = flag('server') ?? LIVE_SERVER;
+    let id = from;
+    if (!/^[0-9a-f]{32}$/.test(from)) {
+        if (URL.canParse(from) && /^https?:$/.test(new URL(from).protocol)) {
+            const link = new URL(from);
+            const match = link.pathname.match(/^\/p\/([0-9a-f]{32})(?:\/|$)/) ?? link.pathname.match(/^\/p\/([a-z0-9-]+)\/?$/);
+            if (!match)
+                throw new Error(`--from takes a sample's name, a project link (https://…/p/<id>) or its id, not '${from}'.`);
+            server = link.origin;
+            id = match[1];
+        }
+        if (!/^[0-9a-f]{32}$/.test(id))
+            id = await sampleId(server, id);
+    }
+    const res = await fetch(`${server}/p/${id}/details`).catch(() => null);
+    if (!res?.ok)
+        throw new Error(`There's no project ${id} on ${server} to start from.`);
+    const { template, title } = (await res.json());
+    return { server, id, template, title };
+}
+async function listSamples(server) {
+    const res = await fetch(`${server}/api/samples`).catch(() => null);
+    if (!res?.ok || !res.headers.get('content-type')?.includes('json'))
+        return null;
+    return (await res.json());
+}
+async function sampleId(server, name) {
+    const res = await fetch(`${server}/api/samples/${encodeURIComponent(name)}`).catch(() => null);
+    if (!res)
+        throw new Error(`Couldn't reach ${server} to look up the sample '${name}'.`);
+    if (res.ok && res.headers.get('content-type')?.includes('json'))
+        return (await res.json()).id;
+    const names = (await listSamples(server))?.map((s) => s.name) ?? [];
+    const known = names.length ? ` Its samples: ${names.join(', ')}.` : '';
+    throw new Error(`There's no sample named '${name}' on ${server}.${known} --from also takes a project link or its full 32-character id.`);
+}
+async function savedProject() {
+    if (!existsSync(join(root, CONFIG)))
+        return null;
+    const ref = JSON.parse(await readFile(join(root, CONFIG), 'utf8'));
+    if (!ref.writeKey)
+        return null;
+    const res = await fetch(`${projectUrl(ref)}/files`).catch(() => null);
+    return res?.ok ? ref : null;
+}
+function openInBrowser(url) {
+    const [command, ...rest] = process.platform === 'darwin' ? ['open', url] : process.platform === 'win32' ? ['cmd', '/c', 'start', '""', url.replace(/&/g, '^&')] : ['xdg-open', url];
+    spawn(command, rest, { stdio: 'ignore', detached: true }).on('error', () => { }).unref();
+}
+const COMPUTER = process.platform === 'win32' ? 'PC' : 'Mac';
+/**
+ * How to run npx. On Windows it's npx.cmd, which Node won't spawn without a
+ * shell (and a shell would re-parse the arguments), so npm's own npx-cli.js
+ * runs with this Node instead when it's where Node's installer puts it.
+ */
+function npx() {
+    if (process.platform !== 'win32')
+        return ['npx'];
+    const cli = join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npx-cli.js');
+    return existsSync(cli) ? [process.execPath, cli] : ['npx.cmd'];
+}
+/**
+ * Runs the desktop host for a desktop project until it quits or Ctrl+C. A host
+ * that crashes is started again, since nothing in the browser can reach this
+ * computer to do it, unless it keeps crashing. The host says what joining allows.
+ */
+async function runDesktopHost(ref) {
+    const mac = process.platform === 'darwin' && process.arch === 'arm64';
+    const windows = process.platform === 'win32' && (process.arch === 'x64' || process.arch === 'arm64');
+    if (ref.template === 'expo' && !mac && !(windows && process.arch === 'x64')) {
+        throw new Error('Expo Desktop projects run on an Apple Silicon Mac (macOS 14.4 or later) or a Windows x64 PC. Run the same command on one.');
+    }
+    if (!mac && !windows) {
+        throw new Error('Desktop projects run on an Apple Silicon Mac (macOS 14.4 or later) or a Windows 10 (1903 or later) or Windows 11 PC. Run the same command there.');
+    }
+    const device = `${projectUrl(ref)}#${ref.deviceKey}`;
+    const extra = has('allow-eval') ? ['--allow-eval'] : [];
+    const host = DESKTOP_HOSTS[ref.template ?? 'macos'] ?? DESKTOP_HOSTS.macos;
+    // NS_EDGE_HOST runs another spec of the host (a version, or file:<packed .tgz>) to test a release before publishing it.
+    const spec = process.env.NS_EDGE_HOST ?? host.spec;
+    let child;
+    let stopping = false;
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        process.on(signal, () => {
+            stopping = true;
+            child?.kill(signal);
+        });
+    }
+    const crashes = [];
+    for (;;) {
+        const [command, ...prefix] = npx();
+        child = spawn(command, [...prefix, '-y', '--package', spec, '--', host.bin, device, '--yes', ...extra], { stdio: 'inherit' });
+        const exit = await new Promise((resolve, reject) => {
+            child.on('error', reject);
+            child.on('exit', (code, signal) => resolve({ code, signal }));
+        });
+        if (stopping || exit.code === 0)
+            return;
+        const now = Date.now();
+        crashes.push(now);
+        while (crashes[0] < now - CRASH_WINDOW_MS)
+            crashes.shift();
+        const why = exit.signal ?? `code ${exit.code}`;
+        if (crashes.length > MAX_CRASHES) {
+            throw new Error(`The desktop host crashed ${crashes.length} times in a minute (last: ${why}), so it wasn't restarted. Fix the error above, then run this command again.`);
+        }
+        console.log(`\nThe desktop host stopped (${why}). Starting it again…\n`);
+        await new Promise((r) => setTimeout(r, RESTART_DELAY_MS));
+    }
+}
 const commands = {
+    async live() {
+        for (const later of ['ios', 'android', 'all']) {
+            if (has(later))
+                throw new Error(`--${later} isn't available yet. Run \`live\` for a phone app, or \`live --desktop\`, \`--electron\` or \`--expo\` for a desktop app.`);
+        }
+        const fromArg = flag('from');
+        const source = fromArg ? await sourceProject(fromArg) : null;
+        let ref = has('new') || source ? null : await savedProject();
+        const requested = requestedTemplate();
+        if (source && requested && requested !== source.template) {
+            throw new Error(`--from names ${TEMPLATE_KINDS[source.template] ?? `a ${source.template}`} project, so leave out the flag asking for ${TEMPLATE_KINDS[requested] ?? `a ${requested}`} one.`);
+        }
+        // Without a template flag, this folder's project runs as whatever it was made as.
+        const template = source?.template ?? requested ?? ref?.template ?? 'core';
+        const desktop = DESKTOP_TEMPLATES.has(template);
+        if (ref && requested && (ref.template ?? 'core') !== requested) {
+            const current = TEMPLATE_KINDS[ref.template ?? 'core'] ?? `a ${ref.template}`;
+            throw new Error(`This folder's project (${CONFIG}) is ${current} project. Add --new to start ${TEMPLATE_KINDS[requested] ?? `a ${requested}`} one, or run this in another folder.`);
+        }
+        if (ref) {
+            console.log(`Opening this folder's project ${ref.id} (${CONFIG})`);
+        }
+        else {
+            ref = await createProject(source?.server ?? flag('server') ?? LIVE_SERVER, flag('token') ?? process.env.NS_EDGE_CREATE_TOKEN, template, source?.id);
+            await writeFile(join(root, CONFIG), JSON.stringify(ref, null, 2) + '\n');
+            const made = source ? `your copy of ${source.title ? `"${source.title}"` : `project ${source.id}`}` : `${TEMPLATE_KINDS[template] ?? `a ${template}`} project`;
+            console.log(`Created ${made}, saved to ${CONFIG} (it holds the project's keys: keep it private and out of git).`);
+            if (ref.free) {
+                console.log(`It's a free project: ${ref.free.agentTurnsPerDay} hosted agent turn${ref.free.agentTurnsPerDay === 1 ? '' : 's'} a day, deleted after ${ref.free.idleDays} days unused. ` +
+                    'For an unlimited agent, add your own API key in the agent panel or connect Claude Code from Connect agent.');
+            }
+        }
+        const ide = `${projectUrl(ref)}/#key=${ref.writeKey}`;
+        console.log(`\n  IDE  ${ide}\n`);
+        if (!has('no-open'))
+            openInBrowser(ide);
+        if (desktop) {
+            const first = template === 'electron' ? ' (the first run downloads Electron)' : template === 'expo' ? ' (the first run downloads the Expo Desktop shell)' : '';
+            console.log(`Starting the app on this ${COMPUTER}${first}. Its window streams to the IDE's Device pane. Press Ctrl+C to stop.\n`);
+            return runDesktopHost(ref);
+        }
+        const device = `${projectUrl(ref)}#${ref.deviceKey}`;
+        console.log(await QRCode.toString(`${ref.pairScheme ?? 'nsedge'}://pair?url=${encodeURIComponent(device)}`, { type: 'terminal', small: true }));
+        console.log(`Scan with your phone's camera to open it in ${ref.pairScheme === 'nspreview' ? 'NativeScript Preview' : 'the edge shell'}, then edit in the IDE.`);
+        console.log('Run this command again in this folder to reopen the project.');
+    },
     async create() {
         const server = flag('server') ?? 'http://localhost:5173';
-        const ref = await createProject(server, flag('token') ?? process.env.NS_EDGE_CREATE_TOKEN);
+        const ref = await createProject(server, flag('token') ?? process.env.NS_EDGE_CREATE_TOKEN, requestedTemplate());
         await writeFile(join(root, CONFIG), JSON.stringify(ref, null, 2) + '\n');
         console.log(`Created project ${ref.id} (saved to ${CONFIG}; it holds the project keys, keep it out of git)`);
         await printPairing(ref);
@@ -122,15 +335,35 @@ const commands = {
     async qr() {
         await printPairing(await loadRef());
     },
+    async samples() {
+        const server = flag('server') ?? LIVE_SERVER;
+        const list = await listSamples(server);
+        if (!list)
+            throw new Error(`Couldn't list the samples on ${server}.`);
+        if (!list.length)
+            return console.log(`${server} has no named samples yet.`);
+        const width = Math.max(...list.map((s) => s.name.length));
+        for (const s of list)
+            console.log(`  ${s.name.padEnd(width)}  ${s.title}`);
+        console.log(`\nStart from one with: npx @nativescript/cloudflare-cli live --from <name>`);
+    },
     async help() {
         console.log(`ns-edge <command>
 
-  create [--server <url>] [--token <t>]
+  live [--ng|--react|--vue|--svelte|--solid|--desktop|--electron|--expo] [--new] [--from <sample>] [--no-open] [--allow-eval]
+                            create a project (or reopen this folder's), open its IDE, and print a QR code
+                            for your phone; --ng, --react, --vue, --svelte or --solid picks the framework
+                            (plain TypeScript with XML views otherwise); --desktop (or --mac, --windows)
+                            or --electron runs it on this Mac or Windows PC instead, with that OS's own
+                            controls; --expo runs an Expo Desktop app on this Mac or Windows x64 PC;
+                            --from starts from a copy of a shared project: a sample's name, link or id
+  create [--server <url>] [--token <t>] [--ng|--react|--vue|--svelte|--solid|--template <name>]
                             create an edge project and save .ns-edge.json
   push                      upload app/ and server/ in one transaction
   watch                     push, then stream every save to the edge
   pull                      download the project's files here
-  qr                        print the pairing QR code`);
+  qr                        print the pairing QR code
+  samples                   list the samples --from can start from by name`);
     },
 };
 const run = commands[cmd] ?? commands.help;

package/dist/sync.d.ts

@@ -5,6 +5,12 @@ export interface ProjectRef {
     deviceKey: string;
     /** URL scheme of the app the server pairs with, from its create response. */
     pairScheme?: string;
+    template?: string;
+    /** Set on free projects: their daily agent allowance and how long they last unused. */
+    free?: {
+        agentTurnsPerDay: number;
+        idleDays: number;
+    };
 }
 export interface ApplyResult {
     changed: string[];
@@ -17,7 +23,8 @@ export interface ApplyResult {
 /** Project-relative paths that are mirrored to the edge. */
 export declare const SYNCED: RegExp;
 export declare function projectUrl(ref: ProjectRef): string;
-export declare function createProject(server: string, token?: string): Promise<ProjectRef>;
+/** With `from`, the project starts as a copy of that one, which must be a `template` project. */
+export declare function createProject(server: string, token?: string, template?: string, from?: string): Promise<ProjectRef>;
 /** Sends a batch as one edge transaction, so devices see one consistent update. */
 export declare function applyChanges(ref: ProjectRef, changes: {
     path: string;

package/dist/sync.js

@@ -1,19 +1,25 @@
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 /** Project-relative paths that are mirrored to the edge. */
-export const SYNCED = /^(app|server)\/.+\.(ts|mts|js|mjs|xml|css|json)$/;
+export const SYNCED = /^(app|server)\/.+\.(ts|tsx|mts|js|jsx|mjs|vue|svelte|xml|html|css|json)$/;
 export function projectUrl(ref) {
     return `${ref.server.replace(/\/$/, '')}/p/${ref.id}`;
 }
-export async function createProject(server, token) {
-    const res = await fetch(`${server.replace(/\/$/, '')}/api/projects`, {
+/** With `from`, the project starts as a copy of that one, which must be a `template` project. */
+export async function createProject(server, token, template, from) {
+    const query = from ? `?from=${encodeURIComponent(from)}` : template ? `?template=${encodeURIComponent(template)}` : '';
+    const res = await fetch(`${server.replace(/\/$/, '')}/api/projects${query}`, {
         method: 'POST',
         headers: token ? { authorization: `Bearer ${token}` } : {},
     });
+    if (res.status === 401)
+        throw new Error(`${server} creates projects only with a create token: pass --token or set NS_EDGE_CREATE_TOKEN.`);
+    if (res.status === 404 && from)
+        throw new Error(`There's no project ${from} on ${server} to start from.`);
     if (!res.ok)
-        throw new Error(`create failed: ${res.status} ${await res.text()}`);
-    const { id, writeKey, deviceKey, pair } = (await res.json());
-    return { server, id, writeKey, deviceKey, pairScheme: pair?.split('://')[0] };
+        throw new Error(`Couldn't create a project (${res.status}): ${await res.text()}`);
+    const { id, writeKey, deviceKey, pair, free } = (await res.json());
+    return { server, id, writeKey, deviceKey, pairScheme: pair?.split('://')[0], template: template ?? 'core', ...(free && { free }) };
 }
 /** Sends a batch as one edge transaction, so devices see one consistent update. */
 export async function applyChanges(ref, changes) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nativescript/cloudflare-cli",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.11",
   "description": "Mirror a NativeScript project into an ns-edge project from a terminal or a Vite dev server",
   "license": "Apache-2.0",
   "type": "module",