@nativescript/cloudflare-cli 0.0.0-stage → 0.1.0-beta.1

package/README.md

@@ -1,3 +1,14 @@
-# Temporary Holding Version
+# @nativescript/cloudflare-cli
 
-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.
+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 watch        # push, then every save
+npx ns-edge qr           # print the pairing QR code again
+```
+
+Also: `ns-edge push` uploads `app/` and `server/` once, `ns-edge pull` downloads the project's files.
+
+`ns-edge create` writes `.ns-edge.json` (project id and keys; keep it out of git). In a Vite config, `@nativescript/cloudflare-cli/vite` mirrors `app/` and `server/` on every save.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import { watch } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { 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 [cmd = 'help', ...args] = process.argv.slice(2);
+/**
+ * Editors and tools write temp, swap and backup files next to the real one
+ * (sed -i's `.!123!file`, vim's `.file.swp`, `file~`). Skipped like collect()
+ * skips dotfiles: one such path in a batch makes the edge reject the whole batch.
+ */
+const isScratch = (rel) => rel.split('/').some((part) => part.startsWith('.')) || rel.endsWith('~');
+const flag = (name) => {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 ? args[i + 1] : undefined;
+};
+const root = process.cwd();
+async function loadRef() {
+    let ref;
+    try {
+        ref = JSON.parse(await readFile(join(root, CONFIG), 'utf8'));
+    }
+    catch {
+        throw new Error(`No ${CONFIG} here. Run \`ns-edge create --server <url>\` first.`);
+    }
+    // Copies meant to be shared (the IDE's StackBlitz export) leave the write key out of the file,
+    // so it is asked for here and kept in memory only.
+    ref.writeKey ||= process.env.NS_EDGE_WRITE_KEY || (await ask("Paste this project's write key (the IDE copied it to your clipboard): "));
+    if (!ref.writeKey)
+        throw new Error(`No write key: add it to ${CONFIG} or set NS_EDGE_WRITE_KEY.`);
+    return ref;
+}
+async function ask(question) {
+    if (!process.stdin.isTTY)
+        return '';
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(question)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+async function printPairing(ref) {
+    const url = projectUrl(ref);
+    const device = `${url}#${ref.deviceKey}`;
+    console.log(await QRCode.toString(`${ref.pairScheme ?? 'nsedge'}://pair?url=${encodeURIComponent(device)}`, { type: 'terminal', small: true }));
+    console.log(`  device  ${device}`);
+    console.log(`  ide     ${url}/#key=${ref.writeKey}`);
+}
+const commands = {
+    async create() {
+        const server = flag('server') ?? 'http://localhost:5173';
+        const ref = await createProject(server, flag('token') ?? process.env.NS_EDGE_CREATE_TOKEN);
+        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);
+    },
+    async push() {
+        const ref = await loadRef();
+        const files = await collect(root);
+        report(await applyChanges(ref, files));
+    },
+    async pull() {
+        const ref = await loadRef();
+        const list = (await (await fetch(`${projectUrl(ref)}/files`)).json());
+        const { mkdir } = await import('node:fs/promises');
+        const { dirname } = await import('node:path');
+        for (const { path } of list) {
+            const content = await (await fetch(`${projectUrl(ref)}/files/${path}`)).text();
+            await mkdir(dirname(join(root, path)), { recursive: true });
+            await writeFile(join(root, path), content);
+            console.log(`  ↓ ${path}`);
+        }
+    },
+    async watch() {
+        const ref = await loadRef();
+        await printPairing(ref);
+        report(await applyChanges(ref, await collect(root)));
+        const pending = new Set();
+        let timer;
+        const flush = async () => {
+            const paths = [...pending];
+            pending.clear();
+            const changes = await Promise.all(paths.map(async (path) => ({ path, content: await readFile(join(root, path), 'utf8').catch(() => null) })));
+            report(await applyChanges(ref, changes));
+        };
+        const changed = (rel) => {
+            pending.add(rel);
+            clearTimeout(timer);
+            timer = setTimeout(() => void flush().catch((e) => console.error(`  ✖ ${e.message}`)), DEBOUNCE_MS);
+        };
+        try {
+            watch(root, { recursive: true }, (_event, file) => {
+                if (!file)
+                    return;
+                const rel = file.split(sep).join('/');
+                if (SYNCED.test(rel) && !isScratch(rel))
+                    changed(rel);
+            });
+        }
+        catch {
+            // Runtimes without recursive fs.watch (some sandboxes and WebContainers) compare snapshots instead.
+            let last = new Map((await collect(root)).map((c) => [c.path, c.content]));
+            setInterval(async () => {
+                const now = new Map((await collect(root)).map((c) => [c.path, c.content]));
+                for (const [path, content] of now)
+                    if (last.get(path) !== content)
+                        changed(path);
+                for (const path of last.keys())
+                    if (!now.has(path))
+                        changed(path);
+                last = now;
+            }, 1000);
+        }
+        console.log('  watching app/ and server/ …');
+    },
+    async qr() {
+        await printPairing(await loadRef());
+    },
+    async help() {
+        console.log(`ns-edge <command>
+
+  create [--server <url>] [--token <t>]
+                            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`);
+    },
+};
+const run = commands[cmd] ?? commands.help;
+run().catch((e) => {
+    console.error(e.message);
+    process.exit(1);
+});

package/dist/sync.d.ts

@@ -0,0 +1,30 @@
+export interface ProjectRef {
+    server: string;
+    id: string;
+    writeKey: string;
+    deviceKey: string;
+    /** URL scheme of the app the server pairs with, from its create response. */
+    pairScheme?: string;
+}
+export interface ApplyResult {
+    changed: string[];
+    diagnostics: {
+        path: string;
+        error: string;
+    }[];
+    version: number;
+}
+/** 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>;
+/** Sends a batch as one edge transaction, so devices see one consistent update. */
+export declare function applyChanges(ref: ProjectRef, changes: {
+    path: string;
+    content: string | null;
+}[]): Promise<ApplyResult>;
+export declare function collect(root: string): Promise<{
+    path: string;
+    content: string;
+}[]>;
+export declare function report(result: ApplyResult, log?: (s: string) => void): void;

package/dist/sync.js

@@ -0,0 +1,61 @@
+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 function projectUrl(ref) {
+    return `${ref.server.replace(/\/$/, '')}/p/${ref.id}`;
+}
+export async function createProject(server, token) {
+    const res = await fetch(`${server.replace(/\/$/, '')}/api/projects`, {
+        method: 'POST',
+        headers: token ? { authorization: `Bearer ${token}` } : {},
+    });
+    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] };
+}
+/** Sends a batch as one edge transaction, so devices see one consistent update. */
+export async function applyChanges(ref, changes) {
+    const res = await fetch(`${projectUrl(ref)}/files`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${ref.writeKey}`, 'content-type': 'application/json' },
+        body: JSON.stringify({ changes }),
+    });
+    if (!res.ok)
+        throw new Error(`sync failed: ${res.status} ${await res.text()}`);
+    return (await res.json());
+}
+export async function collect(root) {
+    const out = [];
+    const walk = async (dir) => {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            if (entry.name === 'node_modules' || entry.name.startsWith('.'))
+                continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory())
+                await walk(full);
+            else {
+                const rel = relative(root, full).split(sep).join('/');
+                if (SYNCED.test(rel))
+                    out.push({ path: rel, content: await readFile(full, 'utf8') });
+            }
+        }
+    };
+    for (const top of ['app', 'server']) {
+        const dir = join(root, top);
+        if (await stat(dir).then((s) => s.isDirectory(), () => false))
+            await walk(dir);
+    }
+    return out;
+}
+export function report(result, log = console.log) {
+    if (result.diagnostics.length) {
+        for (const d of result.diagnostics)
+            log(`  ✖ ${d.error}`);
+        log('  devices kept the previous version');
+    }
+    else if (result.changed.length) {
+        log(`  v${result.version} ← ${result.changed.join(', ')}`);
+    }
+}

package/dist/vite.d.ts

@@ -0,0 +1,8 @@
+import type { Plugin } from 'vite';
+import { type ProjectRef } from './sync.js';
+/**
+ * Mirrors a project's app/ and server/ folders into an edge project while
+ * `vite dev` runs, so every phone paired with that project hot-reloads from
+ * the nearest Cloudflare location, not from this machine.
+ */
+export declare function nsEdge(ref: ProjectRef): Plugin;

package/dist/vite.js

@@ -0,0 +1,40 @@
+import { readFile } from 'node:fs/promises';
+import { relative, sep } from 'node:path';
+import { applyChanges, collect, report, SYNCED } from './sync.js';
+/**
+ * Mirrors a project's app/ and server/ folders into an edge project while
+ * `vite dev` runs, so every phone paired with that project hot-reloads from
+ * the nearest Cloudflare location, not from this machine.
+ */
+export function nsEdge(ref) {
+    let root = process.cwd();
+    return {
+        name: 'ns-edge',
+        apply: 'serve',
+        configResolved(config) {
+            root = config.root;
+        },
+        async configureServer(server) {
+            const log = (s) => server.config.logger.info(`[ns-edge] ${s}`, { timestamp: true });
+            report(await applyChanges(ref, await collect(root)), log);
+            const pending = new Map();
+            let timer;
+            const queue = (file, deleted) => {
+                const rel = relative(root, file).split(sep).join('/');
+                if (!SYNCED.test(rel))
+                    return;
+                pending.set(rel, deleted ? null : file);
+                clearTimeout(timer);
+                timer = setTimeout(async () => {
+                    const batch = [...pending];
+                    pending.clear();
+                    const changes = await Promise.all(batch.map(async ([path, abs]) => ({ path, content: abs ? await readFile(abs, 'utf8') : null })));
+                    report(await applyChanges(ref, changes), log);
+                }, 80);
+            };
+            server.watcher.on('add', (f) => queue(f, false));
+            server.watcher.on('change', (f) => queue(f, false));
+            server.watcher.on('unlink', (f) => queue(f, true));
+        },
+    };
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@nativescript/cloudflare-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.1",
+  "description": "Mirror a NativeScript project into an ns-edge project from a terminal or a Vite dev server",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "ns-edge": "./dist/bin.js"
+  },
+  "exports": {
+    ".": "./dist/sync.js",
+    "./vite": "./dist/vite.js"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "typecheck": "tsc -p . --noEmit",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "qrcode": "^1.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/qrcode": "^1.5.6",
+    "typescript": "^6.0.0",
+    "vite": "^8.3.5"
+  },
+  "peerDependencies": {
+    "vite": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  }
+}