@magneticjs/cli 0.1.0

package/scripts/install-server.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * install-server.js — Downloads the prebuilt magnetic-v8-server binary
+ * for the current platform during `npm install @magnetic/cli`.
+ *
+ * Update strategy:
+ *   - Version is read from ../package.json (matches @magnetic/cli version)
+ *   - When user runs `npm update @magnetic/cli`, this script re-runs
+ *   - Binary version is tracked in bin/.version
+ *   - If version mismatch → re-download; if match → skip
+ *
+ * Binary distribution:
+ *   GitHub Releases: magnetic-v8-server-{target}.tar.gz
+ *   Targets: x86_64-apple-darwin, aarch64-apple-darwin, x86_64-unknown-linux-gnu
+ *
+ * Falls back gracefully if download fails — user can build from source.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'fs';
+import { join, dirname } from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgDir = join(__dirname, '..');
+const binDir = join(pkgDir, 'bin');
+const binPath = join(binDir, 'magnetic-v8-server');
+const versionFile = join(binDir, '.version');
+
+// Read version from package.json (stays in sync with npm version)
+const pkg = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf-8'));
+const version = pkg.version;
+
+// Check if installed binary matches current CLI version
+if (existsSync(binPath) && existsSync(versionFile)) {
+  const installed = readFileSync(versionFile, 'utf-8').trim();
+  if (installed === version) {
+    console.log(`[magnetic] Server binary v${version} already installed, skipping`);
+    process.exit(0);
+  }
+  console.log(`[magnetic] Server binary outdated (${installed} → ${version}), updating...`);
+}
+
+// Determine platform target
+function getTarget() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  if (platform === 'darwin' && arch === 'arm64') return 'aarch64-apple-darwin';
+  if (platform === 'darwin' && arch === 'x64') return 'x86_64-apple-darwin';
+  if (platform === 'linux' && arch === 'x64') return 'x86_64-unknown-linux-gnu';
+  if (platform === 'linux' && arch === 'arm64') return 'aarch64-unknown-linux-gnu';
+  return null;
+}
+
+const target = getTarget();
+if (!target) {
+  console.warn(`[magnetic] No prebuilt binary for ${process.platform}-${process.arch}`);
+  console.warn('[magnetic] Build from source: cargo build --release -p magnetic-v8-server');
+  process.exit(0);
+}
+
+const baseUrl = process.env.MAGNETIC_BINARY_URL ||
+  `https://github.com/inventhq/magnetic/releases/download/v${version}`;
+const filename = `magnetic-v8-server-${target}.tar.gz`;
+const url = `${baseUrl}/${filename}`;
+
+console.log(`[magnetic] Downloading server binary for ${target}...`);
+console.log(`[magnetic] ${url}`);
+
+try {
+  mkdirSync(binDir, { recursive: true });
+  // Use curl or wget — available on all platforms
+  try {
+    execSync(`curl -fsSL "${url}" | tar xz -C "${binDir}"`, { stdio: 'pipe' });
+  } catch {
+    execSync(`wget -qO- "${url}" | tar xz -C "${binDir}"`, { stdio: 'pipe' });
+  }
+
+  if (existsSync(binPath)) {
+    chmodSync(binPath, 0o755);
+    writeFileSync(versionFile, version);
+    console.log(`[magnetic] ✓ Server binary v${version} installed: ${binPath}`);
+  } else {
+    throw new Error('Binary not found after extraction');
+  }
+} catch (err) {
+  console.warn(`[magnetic] Could not download prebuilt binary: ${err.message}`);
+  console.warn('[magnetic] The CLI will still work, but you need the server binary for `magnetic dev`.');
+  console.warn('[magnetic] Build from source: cargo build --release -p magnetic-v8-server');
+  // Don't fail the install — just warn
+  process.exit(0);
+}

package/src/bundler.ts

@@ -0,0 +1,113 @@
+// bundler.ts — esbuild wrapper for Magnetic apps
+// Takes generated bridge code and bundles it into an IIFE for V8
+
+import { build } from 'esbuild';
+import { join, resolve } from 'node:path';
+import { mkdirSync, existsSync, writeFileSync, statSync, readdirSync, readFileSync } from 'node:fs';
+
+export interface BundleOptions {
+  /** Absolute path to the app directory */
+  appDir: string;
+  /** Generated bridge source code (from generator) */
+  bridgeCode: string;
+  /** Output directory (default: dist/) */
+  outDir?: string;
+  /** Output filename (default: app.js) */
+  outFile?: string;
+  /** Minify output */
+  minify?: boolean;
+  /** Monorepo root (for resolving @magneticjs/server) */
+  monorepoRoot?: string;
+}
+
+export interface BundleResult {
+  outPath: string;
+  sizeBytes: number;
+}
+
+/**
+ * Bundle the generated bridge code into an IIFE for V8 consumption.
+ * Uses esbuild with stdin so no temp file is needed.
+ */
+export async function bundleApp(opts: BundleOptions): Promise<BundleResult> {
+  const outDir = opts.outDir || join(opts.appDir, 'dist');
+  const outFile = opts.outFile || 'app.js';
+  const outPath = join(outDir, outFile);
+
+  if (!existsSync(outDir)) {
+    mkdirSync(outDir, { recursive: true });
+  }
+
+  // Resolve @magneticjs/server — in monorepo use actual path, otherwise npm package
+  const alias: Record<string, string> = {};
+  if (opts.monorepoRoot) {
+    const serverPkg = join(opts.monorepoRoot, 'js/packages/magnetic-server/src');
+    alias['@magneticjs/server'] = serverPkg;
+    alias['@magneticjs/server/jsx-runtime'] = join(serverPkg, 'jsx-runtime.ts');
+  }
+
+  const result = await build({
+    stdin: {
+      contents: opts.bridgeCode,
+      resolveDir: opts.appDir,
+      loader: 'tsx',
+    },
+    bundle: true,
+    format: 'iife',
+    globalName: 'MagneticApp',
+    outfile: outPath,
+    minify: opts.minify || false,
+    sourcemap: false,
+    target: 'es2020',
+    jsx: 'automatic',
+    jsxImportSource: '@magneticjs/server',
+    alias,
+    logLevel: 'warning',
+  });
+
+  const stat = statSync(outPath);
+
+  return {
+    outPath,
+    sizeBytes: stat.size,
+  };
+}
+
+/**
+ * Bundle and also prepare the assets manifest for deployment.
+ * Returns the bundle path + a map of public/ files.
+ */
+export async function buildForDeploy(opts: BundleOptions): Promise<{
+  bundlePath: string;
+  bundleSize: number;
+  assets: Record<string, string>;
+}> {
+  const bundle = await bundleApp({ ...opts, minify: true });
+
+  // Collect public/ files as a map for upload
+  const publicDir = join(opts.appDir, 'public');
+  const assets: Record<string, string> = {};
+
+  if (existsSync(publicDir)) {
+    const entries = readdirSync(publicDir);
+    for (const entry of entries) {
+      const fullPath = join(publicDir, entry);
+      if (statSync(fullPath).isFile()) {
+        // For text files, include as string; for binary, base64 encode
+        const ext = entry.split('.').pop() || '';
+        const textExts = ['css', 'js', 'json', 'html', 'svg', 'txt', 'xml'];
+        if (textExts.includes(ext)) {
+          assets[entry] = readFileSync(fullPath, 'utf-8');
+        } else {
+          assets[entry] = readFileSync(fullPath).toString('base64');
+        }
+      }
+    }
+  }
+
+  return {
+    bundlePath: bundle.outPath,
+    bundleSize: bundle.sizeBytes,
+    assets,
+  };
+}

package/src/cli.ts

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+// cli.ts — Magnetic CLI entry point
+// Commands: dev, build, push
+
+import { resolve, join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { scanApp, generateBridge } from './generator.ts';
+import { bundleApp, buildForDeploy } from './bundler.ts';
+import { startDev } from './dev.ts';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+// Structured logging
+function log(level: 'info' | 'warn' | 'error' | 'debug', msg: string) {
+  const ts = new Date().toISOString().slice(11, 23);
+  const prefix = level === 'error' ? '✗' : level === 'warn' ? '⚠' : level === 'debug' ? '·' : '→';
+  const stream = level === 'error' ? process.stderr : process.stdout;
+  stream.write(`[${ts}] ${prefix} ${msg}\n`);
+}
+
+function findMonorepoRoot(from: string): string | null {
+  let dir = from;
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(join(dir, 'js/packages/magnetic-server'))) return dir;
+    const parent = resolve(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function getArg(flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  return idx >= 0 ? args[idx + 1] : undefined;
+}
+
+function usage() {
+  console.log(`
+  @magnetic/cli — Build and deploy server-driven UI apps
+
+  Usage:
+    magnetic dev              Start dev mode (watch + rebuild + serve)
+    magnetic build            Build the app bundle for deployment
+    magnetic push             Build and deploy to a Magnetic platform server
+
+  Options:
+    --port <n>                Dev server port (default: 3003)
+    --dir <path>              App directory (default: current directory)
+    --server <url>            Platform server URL for push
+    --name <name>             App name for push (default: from magnetic.json)
+    --minify                  Minify the output bundle
+
+  Developer workflow:
+    1. Write pages in pages/*.tsx
+    2. Write business logic in state.ts (optional)
+    3. Run \`magnetic dev\` to develop locally
+    4. Run \`magnetic push\` to deploy
+  `);
+}
+
+async function main() {
+  if (!command || command === '--help' || command === '-h') {
+    usage();
+    process.exit(0);
+  }
+
+  const appDir = resolve(getArg('--dir') || '.');
+  const monorepoRoot = findMonorepoRoot(appDir);
+  const port = parseInt(getArg('--port') || '3003', 10);
+
+  // Load magnetic.json if it exists
+  let config: any = {};
+  const configPath = join(appDir, 'magnetic.json');
+  if (existsSync(configPath)) {
+    config = JSON.parse(readFileSync(configPath, 'utf-8'));
+  }
+
+  switch (command) {
+    case 'dev': {
+      await startDev({
+        appDir,
+        port,
+        monorepoRoot: monorepoRoot || undefined,
+      });
+      break;
+    }
+
+    case 'build': {
+      log('info', `Building ${appDir}`);
+      const buildStart = Date.now();
+      const scan = scanApp(appDir, monorepoRoot || undefined);
+      log('info', `Scanned: ${scan.pages.length} pages, state: ${scan.statePath || 'none (using defaults)'}`);
+
+      for (const page of scan.pages) {
+        log('debug', `  route ${page.routePath.padEnd(15)} ← ${page.filePath}`);
+      }
+
+      const bridgeCode = generateBridge(scan);
+      log('debug', `Bridge generated: ${bridgeCode.split('\n').length} lines`);
+
+      if (args.includes('--verbose')) {
+        console.log('\n--- Generated bridge ---');
+        console.log(bridgeCode);
+        console.log('--- End bridge ---\n');
+      }
+
+      const result = await bundleApp({
+        appDir,
+        bridgeCode,
+        minify: args.includes('--minify'),
+        monorepoRoot: monorepoRoot || undefined,
+      });
+
+      const kb = (result.sizeBytes / 1024).toFixed(1);
+      const elapsed = Date.now() - buildStart;
+      log('info', `✓ Built ${result.outPath} (${kb}KB) in ${elapsed}ms`);
+      break;
+    }
+
+    case 'push': {
+      const serverUrl = getArg('--server') || config.server;
+      const appName = getArg('--name') || config.name;
+
+      if (!serverUrl) {
+        console.error('[magnetic] No server URL. Use --server <url> or set "server" in magnetic.json');
+        process.exit(1);
+      }
+      if (!appName) {
+        console.error('[magnetic] No app name. Use --name <name> or set "name" in magnetic.json');
+        process.exit(1);
+      }
+
+      log('info', `Building for deploy...`);
+      const scan = scanApp(appDir, monorepoRoot || undefined);
+      log('info', `Scanned: ${scan.pages.length} pages, state: ${scan.statePath || 'none'}`);
+      const bridgeCode = generateBridge(scan);
+      const deploy = await buildForDeploy({ appDir, bridgeCode, monorepoRoot: monorepoRoot || undefined });
+
+      log('info', `Bundle: ${(deploy.bundleSize / 1024).toFixed(1)}KB (minified)`);
+      log('info', `Assets: ${Object.keys(deploy.assets).length} files`);
+      for (const [name, content] of Object.entries(deploy.assets)) {
+        log('debug', `  asset: ${name} (${(content.length / 1024).toFixed(1)}KB)`);
+      }
+      log('info', `Pushing to ${serverUrl}/api/apps/${appName}/deploy...`);
+
+      const bundleContent = readFileSync(deploy.bundlePath, 'utf-8');
+
+      const resp = await fetch(`${serverUrl}/api/apps/${appName}/deploy`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          bundle: bundleContent,
+          assets: deploy.assets,
+        }),
+      });
+
+      if (resp.ok) {
+        const data = await resp.json() as any;
+        log('info', `✓ Deployed! ${data.url || serverUrl + '/apps/' + appName + '/'}`);
+        log('info', `  Live at: ${serverUrl}/apps/${appName}/`);
+      } else {
+        const text = await resp.text();
+        log('error', `Deploy failed (${resp.status}): ${text}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    default:
+      console.error(`[magnetic] Unknown command: ${command}`);
+      usage();
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(`[magnetic] Fatal: ${err.message}`);
+  process.exit(1);
+});

package/src/dev.ts

@@ -0,0 +1,188 @@
+// dev.ts — Dev mode: watch pages/, auto-rebuild, start V8 server
+// Gives developers instant feedback as they edit TSX pages
+
+import { watch } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { spawn, ChildProcess } from 'node:child_process';
+import { scanApp, generateBridge } from './generator.ts';
+import { bundleApp } from './bundler.ts';
+
+export interface DevOptions {
+  /** Absolute path to the app directory */
+  appDir: string;
+  /** Port for the V8 server (default: 3003) */
+  port?: number;
+  /** Path to the magnetic-v8-server binary */
+  serverBin?: string;
+  /** Monorepo root (for resolving @magneticjs/server) */
+  monorepoRoot?: string;
+}
+
+/**
+ * Start dev mode:
+ * 1. Scan pages/ and generate bridge
+ * 2. Bundle with esbuild
+ * 3. Start the Rust V8 server
+ * 4. Watch for file changes → rebuild → restart server
+ */
+export async function startDev(opts: DevOptions): Promise<void> {
+  const {
+    appDir,
+    port = 3003,
+    monorepoRoot,
+  } = opts;
+
+  const staticDir = join(appDir, 'public');
+  const outDir = join(appDir, 'dist');
+
+  // Find the V8 server binary
+  const serverBin = opts.serverBin || findServerBinary(monorepoRoot || appDir);
+  if (!serverBin) {
+    console.error('[magnetic] Cannot find magnetic-v8-server binary.');
+    console.error('  Build it with: cargo build --release -p magnetic-v8-server');
+    process.exit(1);
+  }
+
+  let serverProcess: ChildProcess | null = null;
+
+  async function rebuild(): Promise<string | null> {
+    const start = Date.now();
+    try {
+      const scan = scanApp(appDir, monorepoRoot);
+      console.log(`[magnetic] Scanned ${scan.pages.length} pages, state: ${scan.statePath || 'none'}`);
+
+      for (const page of scan.pages) {
+        console.log(`  ${page.routePath} → ${page.filePath} (${page.importName})`);
+      }
+
+      const bridgeCode = generateBridge(scan);
+      const result = await bundleApp({
+        appDir,
+        bridgeCode,
+        outDir,
+        monorepoRoot,
+      });
+
+      const ms = Date.now() - start;
+      const kb = (result.sizeBytes / 1024).toFixed(1);
+      console.log(`[magnetic] Built ${result.outPath} (${kb}KB) in ${ms}ms`);
+      return result.outPath;
+    } catch (err: any) {
+      console.error(`[magnetic] Build failed: ${err.message}`);
+      return null;
+    }
+  }
+
+  function startServer(bundlePath: string): ChildProcess {
+    const args = [
+      '--bundle', bundlePath,
+      '--port', String(port),
+      '--static', staticDir,
+    ];
+
+    console.log(`[magnetic] Starting V8 server on :${port}`);
+    const proc = spawn(serverBin!, args, {
+      stdio: ['ignore', 'inherit', 'inherit'],
+    });
+
+    proc.on('exit', (code) => {
+      if (code !== null && code !== 0) {
+        console.error(`[magnetic] Server exited with code ${code}`);
+      }
+    });
+
+    return proc;
+  }
+
+  function stopServer() {
+    if (serverProcess) {
+      serverProcess.kill('SIGTERM');
+      serverProcess = null;
+    }
+  }
+
+  // Initial build + start
+  const bundlePath = await rebuild();
+  if (!bundlePath) {
+    console.error('[magnetic] Initial build failed. Fix errors and save to retry.');
+  } else {
+    serverProcess = startServer(bundlePath);
+  }
+
+  // Watch for changes
+  const watchDirs = [join(appDir, 'pages'), join(appDir, 'components')];
+  const watchFiles = ['state.ts', 'state.tsx', 'server/state.ts', 'server/state.tsx']
+    .map(f => join(appDir, f));
+
+  let rebuildTimer: ReturnType<typeof setTimeout> | null = null;
+
+  function scheduleRebuild() {
+    if (rebuildTimer) clearTimeout(rebuildTimer);
+    rebuildTimer = setTimeout(async () => {
+      console.log('\n[magnetic] Change detected, rebuilding...');
+      stopServer();
+      const path = await rebuild();
+      if (path) {
+        serverProcess = startServer(path);
+      }
+    }, 200); // Debounce 200ms
+  }
+
+  for (const dir of watchDirs) {
+    if (existsSync(dir)) {
+      watch(dir, { recursive: true }, (event, filename) => {
+        if (filename && /\.(tsx?|jsx?|css)$/.test(filename)) {
+          scheduleRebuild();
+        }
+      });
+      console.log(`[magnetic] Watching ${dir}`);
+    }
+  }
+
+  for (const file of watchFiles) {
+    if (existsSync(file)) {
+      watch(file, () => scheduleRebuild());
+      console.log(`[magnetic] Watching ${file}`);
+    }
+  }
+
+  // Handle cleanup
+  process.on('SIGINT', () => {
+    console.log('\n[magnetic] Shutting down...');
+    stopServer();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    stopServer();
+    process.exit(0);
+  });
+
+  console.log(`[magnetic] Dev mode ready. Edit pages/ and save to rebuild.`);
+  console.log(`[magnetic] http://localhost:${port}\n`);
+}
+
+/**
+ * Look for the magnetic-v8-server binary in common locations.
+ */
+function findServerBinary(searchRoot: string): string | null {
+  // __dirname equivalent for the CLI package
+  const cliPkgBin = join(import.meta.dirname || __dirname, '..', 'bin', 'magnetic-v8-server');
+
+  const candidates = [
+    // npm-installed binary (from postinstall)
+    cliPkgBin,
+    // Monorepo development paths
+    join(searchRoot, 'rs/crates/magnetic-v8-server/target/debug/magnetic-v8-server'),
+    join(searchRoot, 'rs/crates/magnetic-v8-server/target/release/magnetic-v8-server'),
+    join(searchRoot, 'target/debug/magnetic-v8-server'),
+    join(searchRoot, 'target/release/magnetic-v8-server'),
+  ];
+
+  for (const path of candidates) {
+    if (existsSync(path)) return path;
+  }
+
+  return null;
+}