@magneticjs/cli 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# @magnetic/cli
+
+Build, develop, and deploy Magnetic server-driven UI apps.
+
+## Installation
+
+```bash
+npm install -g @magnetic/cli
+```
+
+This also downloads the `magnetic-v8-server` binary for your platform via postinstall.
+
+## Commands
+
+### `magnetic dev`
+
+Start a local development server with hot rebuild on file changes.
+
+```bash
+cd my-app
+magnetic dev                    # http://localhost:3003
+magnetic dev --port 4000        # custom port
+magnetic dev --dir ./my-app     # specify app directory
+```
+
+What happens:
+1. Scans `pages/` for TSX page components
+2. Detects `server/state.ts` for business logic
+3. Auto-generates the V8 bridge (route map + state wiring)
+4. Bundles with esbuild into a single IIFE
+5. Starts `magnetic-v8-server` on the specified port
+6. Watches for changes, rebuilds + restarts on save
+
+### `magnetic build`
+
+Generate the production bundle without starting a server.
+
+```bash
+magnetic build --dir ./my-app
+magnetic build --dir ./my-app --minify --verbose
+```
+
+Output: `dist/app.js` (~15KB typical)
+
+### `magnetic push`
+
+Build and deploy to a Magnetic platform server.
+
+```bash
+magnetic push --dir ./my-app --server https://platform.magnetic.app --name my-app
+```
+
+Or configure in `magnetic.json`:
+```json
+{
+  "name": "my-app",
+  "server": "https://platform.magnetic.app"
+}
+```
+
+Then just: `magnetic push`
+
+## How It Works
+
+The CLI is a **build tool**, not a runtime. It:
+- Scans your `pages/` directory and maps filenames to routes
+- Generates a bridge file that wires pages + state + router
+- Bundles everything into a single JS file for the V8 engine
+- The Rust V8 server executes this bundle to render JSON DOM descriptors
+
+**You write**: pages, components, state
+**CLI generates**: bridge, bundle
+**Rust server runs**: V8 + HTTP + SSE
+
+## File Conventions
+
+| File | Route |
+|------|-------|
+| `pages/IndexPage.tsx` | `/` |
+| `pages/AboutPage.tsx` | `/about` |
+| `pages/SettingsPage.tsx` | `/settings` |
+| `pages/[id].tsx` | `/:id` (dynamic) |
+| `pages/NotFoundPage.tsx` | `*` (catch-all) |
+
+## Server Binary
+
+The Rust binary (`magnetic-v8-server`) is automatically downloaded during
+`npm install`. If the download fails, you can build from source:
+
+```bash
+cd rs/crates/magnetic-v8-server
+cargo build --release
+```
+
+Supported platforms: macOS (ARM64, x64), Linux (x64, ARM64)
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,498 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { resolve as resolve3, join as join4 } from "node:path";
+import { existsSync as existsSync4, readFileSync as readFileSync3 } from "node:fs";
+
+// src/generator.ts
+import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { join, relative, extname, basename } from "node:path";
+var PAGE_EXTENSIONS = [".tsx", ".jsx", ".ts", ".js"];
+var CATCH_ALL_NAMES = ["notfound", "404", "notfoundpage", "_404", "error"];
+var INDEX_NAMES = ["index", "indexpage", "home", "homepage", "tasks", "taskspage", "main", "mainpage"];
+function scanApp(appDir, monorepoRoot) {
+  const pagesDir = join(appDir, "pages");
+  const pages = [];
+  if (existsSync(pagesDir)) {
+    scanDir(pagesDir, "", pages);
+  }
+  const stateCandidates = [
+    "state.ts",
+    "state.tsx",
+    "server/state.ts",
+    "server/state.tsx",
+    "store.ts",
+    "store.tsx"
+  ];
+  let statePath = null;
+  let hasViewModel = false;
+  for (const candidate of stateCandidates) {
+    const full = join(appDir, candidate);
+    if (existsSync(full)) {
+      statePath = "./" + candidate;
+      const content = readFileSync(full, "utf-8");
+      hasViewModel = /export\s+(function|const)\s+toViewModel/.test(content);
+      break;
+    }
+  }
+  let serverPkgPath;
+  if (monorepoRoot) {
+    const relPath = relative(appDir, join(monorepoRoot, "js/packages/magnetic-server/src"));
+    serverPkgPath = relPath.startsWith(".") ? relPath : "./" + relPath;
+  } else {
+    serverPkgPath = "@magneticjs/server";
+  }
+  return { pages, statePath, hasViewModel, serverPkgPath };
+}
+function scanDir(dir, pathPrefix, pages, rootPagesDir) {
+  const pagesRoot = rootPagesDir || dir;
+  const entries = readdirSync(dir).sort();
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      let segment = entry;
+      if (entry.startsWith("[") && entry.endsWith("]")) {
+        segment = ":" + entry.slice(1, -1);
+      }
+      scanDir(fullPath, pathPrefix + "/" + segment, pages, pagesRoot);
+      continue;
+    }
+    const ext = extname(entry);
+    if (!PAGE_EXTENSIONS.includes(ext)) continue;
+    const nameNoExt = basename(entry, ext);
+    if (nameNoExt.startsWith("_") && !CATCH_ALL_NAMES.includes(nameNoExt.toLowerCase())) continue;
+    if (nameNoExt === "layout") continue;
+    const importName = nameNoExt;
+    const nameLower = nameNoExt.toLowerCase().replace(/page$/, "");
+    let routePath;
+    let isCatchAll = false;
+    if (CATCH_ALL_NAMES.includes(nameLower)) {
+      routePath = "*";
+      isCatchAll = true;
+    } else if (INDEX_NAMES.includes(nameLower)) {
+      routePath = pathPrefix || "/";
+    } else if (nameNoExt.startsWith("[") && nameNoExt.endsWith("]")) {
+      const param = nameNoExt.slice(1, -1);
+      routePath = pathPrefix + "/:" + param;
+    } else {
+      routePath = pathPrefix + "/" + nameLower;
+    }
+    const relFromPagesRoot = relative(pagesRoot, fullPath).replace(/\\/g, "/");
+    const filePath = "pages/" + relFromPagesRoot;
+    pages.push({ filePath, importName, routePath, isCatchAll });
+  }
+}
+function generateBridge(scan) {
+  const lines = [];
+  lines.push("// AUTO-GENERATED by @magnetic/cli \u2014 do not edit");
+  lines.push(`import { createRouter } from '${scan.serverPkgPath}/router.ts';`);
+  const catchAllPage = scan.pages.find((p) => p.isCatchAll);
+  for (const page of scan.pages) {
+    lines.push(`import { ${page.importName} } from './${page.filePath}';`);
+  }
+  if (scan.statePath) {
+    lines.push(`import { initialState, reduce as _reduce${scan.hasViewModel ? ", toViewModel" : ""} } from '${scan.statePath}';`);
+  } else {
+    lines.push("");
+    lines.push("// No state.ts found \u2014 using minimal default state");
+    lines.push("function initialState() { return {}; }");
+    lines.push("function _reduce(state, action, payload) { return state; }");
+  }
+  if (!scan.hasViewModel && scan.statePath) {
+    lines.push("function toViewModel(s) { return s; }");
+  } else if (!scan.statePath) {
+    lines.push("function toViewModel(s) { return s; }");
+  }
+  lines.push("");
+  lines.push("const router = createRouter([");
+  for (const page of scan.pages) {
+    if (!page.isCatchAll) {
+      lines.push(`  { path: '${page.routePath}', page: ${page.importName} },`);
+    }
+  }
+  if (catchAllPage) {
+    lines.push(`  { path: '*', page: ${catchAllPage.importName} },`);
+  }
+  lines.push("]);");
+  lines.push("");
+  lines.push("let state = initialState();");
+  lines.push("");
+  lines.push("export function render(path) {");
+  lines.push("  const vm = toViewModel(state);");
+  lines.push("  const result = router.resolve(path, vm);");
+  if (catchAllPage) {
+    lines.push(`  if (!result) return ${catchAllPage.importName}({ params: {} });`);
+  } else {
+    lines.push('  if (!result) return { tag: "div", text: "Not Found" };');
+  }
+  lines.push("  if (result.kind === 'redirect') {");
+  lines.push("    const r2 = router.resolve(result.to, vm);");
+  lines.push("    if (r2 && r2.kind === 'render') return r2.dom;");
+  if (catchAllPage) {
+    lines.push(`    return ${catchAllPage.importName}({ params: {} });`);
+  } else {
+    lines.push('    return { tag: "div", text: "Not Found" };');
+  }
+  lines.push("  }");
+  lines.push("  return result.dom;");
+  lines.push("}");
+  lines.push("");
+  lines.push("export function reduce(ap) {");
+  lines.push("  const { action, payload = {}, path = '/' } = ap;");
+  lines.push("  state = _reduce(state, action, payload);");
+  lines.push("  return render(path);");
+  lines.push("}");
+  return lines.join("\n") + "\n";
+}
+
+// src/bundler.ts
+import { build } from "esbuild";
+import { join as join2 } from "node:path";
+import { mkdirSync, existsSync as existsSync2, statSync as statSync2, readdirSync as readdirSync2, readFileSync as readFileSync2 } from "node:fs";
+async function bundleApp(opts) {
+  const outDir = opts.outDir || join2(opts.appDir, "dist");
+  const outFile = opts.outFile || "app.js";
+  const outPath = join2(outDir, outFile);
+  if (!existsSync2(outDir)) {
+    mkdirSync(outDir, { recursive: true });
+  }
+  const alias = {};
+  if (opts.monorepoRoot) {
+    const serverPkg = join2(opts.monorepoRoot, "js/packages/magnetic-server/src");
+    alias["@magneticjs/server"] = serverPkg;
+    alias["@magneticjs/server/jsx-runtime"] = join2(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 = statSync2(outPath);
+  return {
+    outPath,
+    sizeBytes: stat.size
+  };
+}
+async function buildForDeploy(opts) {
+  const bundle = await bundleApp({ ...opts, minify: true });
+  const publicDir = join2(opts.appDir, "public");
+  const assets = {};
+  if (existsSync2(publicDir)) {
+    const entries = readdirSync2(publicDir);
+    for (const entry of entries) {
+      const fullPath = join2(publicDir, entry);
+      if (statSync2(fullPath).isFile()) {
+        const ext = entry.split(".").pop() || "";
+        const textExts = ["css", "js", "json", "html", "svg", "txt", "xml"];
+        if (textExts.includes(ext)) {
+          assets[entry] = readFileSync2(fullPath, "utf-8");
+        } else {
+          assets[entry] = readFileSync2(fullPath).toString("base64");
+        }
+      }
+    }
+  }
+  return {
+    bundlePath: bundle.outPath,
+    bundleSize: bundle.sizeBytes,
+    assets
+  };
+}
+
+// src/dev.ts
+import { watch } from "node:fs";
+import { join as join3 } from "node:path";
+import { existsSync as existsSync3 } from "node:fs";
+import { spawn } from "node:child_process";
+async function startDev(opts) {
+  const {
+    appDir,
+    port = 3003,
+    monorepoRoot
+  } = opts;
+  const staticDir = join3(appDir, "public");
+  const outDir = join3(appDir, "dist");
+  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 = null;
+  async function rebuild() {
+    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} \u2192 ${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) {
+      console.error(`[magnetic] Build failed: ${err.message}`);
+      return null;
+    }
+  }
+  function startServer(bundlePath2) {
+    const args2 = [
+      "--bundle",
+      bundlePath2,
+      "--port",
+      String(port),
+      "--static",
+      staticDir
+    ];
+    console.log(`[magnetic] Starting V8 server on :${port}`);
+    const proc = spawn(serverBin, args2, {
+      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;
+    }
+  }
+  const bundlePath = await rebuild();
+  if (!bundlePath) {
+    console.error("[magnetic] Initial build failed. Fix errors and save to retry.");
+  } else {
+    serverProcess = startServer(bundlePath);
+  }
+  const watchDirs = [join3(appDir, "pages"), join3(appDir, "components")];
+  const watchFiles = ["state.ts", "state.tsx", "server/state.ts", "server/state.tsx"].map((f) => join3(appDir, f));
+  let rebuildTimer = 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);
+  }
+  for (const dir of watchDirs) {
+    if (existsSync3(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 (existsSync3(file)) {
+      watch(file, () => scheduleRebuild());
+      console.log(`[magnetic] Watching ${file}`);
+    }
+  }
+  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}
+`);
+}
+function findServerBinary(searchRoot) {
+  const cliPkgBin = join3(import.meta.dirname || __dirname, "..", "bin", "magnetic-v8-server");
+  const candidates = [
+    // npm-installed binary (from postinstall)
+    cliPkgBin,
+    // Monorepo development paths
+    join3(searchRoot, "rs/crates/magnetic-v8-server/target/debug/magnetic-v8-server"),
+    join3(searchRoot, "rs/crates/magnetic-v8-server/target/release/magnetic-v8-server"),
+    join3(searchRoot, "target/debug/magnetic-v8-server"),
+    join3(searchRoot, "target/release/magnetic-v8-server")
+  ];
+  for (const path of candidates) {
+    if (existsSync3(path)) return path;
+  }
+  return null;
+}
+
+// src/cli.ts
+var args = process.argv.slice(2);
+var command = args[0];
+function log(level, msg) {
+  const ts = (/* @__PURE__ */ new Date()).toISOString().slice(11, 23);
+  const prefix = level === "error" ? "\u2717" : level === "warn" ? "\u26A0" : level === "debug" ? "\xB7" : "\u2192";
+  const stream = level === "error" ? process.stderr : process.stdout;
+  stream.write(`[${ts}] ${prefix} ${msg}
+`);
+}
+function findMonorepoRoot(from) {
+  let dir = from;
+  for (let i = 0; i < 10; i++) {
+    if (existsSync4(join4(dir, "js/packages/magnetic-server"))) return dir;
+    const parent = resolve3(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function getArg(flag) {
+  const idx = args.indexOf(flag);
+  return idx >= 0 ? args[idx + 1] : void 0;
+}
+function usage() {
+  console.log(`
+  @magnetic/cli \u2014 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 = resolve3(getArg("--dir") || ".");
+  const monorepoRoot = findMonorepoRoot(appDir);
+  const port = parseInt(getArg("--port") || "3003", 10);
+  let config = {};
+  const configPath = join4(appDir, "magnetic.json");
+  if (existsSync4(configPath)) {
+    config = JSON.parse(readFileSync3(configPath, "utf-8"));
+  }
+  switch (command) {
+    case "dev": {
+      await startDev({
+        appDir,
+        port,
+        monorepoRoot: monorepoRoot || void 0
+      });
+      break;
+    }
+    case "build": {
+      log("info", `Building ${appDir}`);
+      const buildStart = Date.now();
+      const scan = scanApp(appDir, monorepoRoot || void 0);
+      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)} \u2190 ${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 || void 0
+      });
+      const kb = (result.sizeBytes / 1024).toFixed(1);
+      const elapsed = Date.now() - buildStart;
+      log("info", `\u2713 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 || void 0);
+      log("info", `Scanned: ${scan.pages.length} pages, state: ${scan.statePath || "none"}`);
+      const bridgeCode = generateBridge(scan);
+      const deploy = await buildForDeploy({ appDir, bridgeCode, monorepoRoot: monorepoRoot || void 0 });
+      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 = readFileSync3(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();
+        log("info", `\u2713 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/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@magneticjs/cli",
+  "version": "0.1.0",
+  "description": "Magnetic CLI — build, dev, and deploy server-driven UI apps",
+  "type": "module",
+  "bin": {
+    "magnetic": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "esbuild src/cli.ts --bundle --platform=node --format=esm --outfile=dist/cli.js --external:esbuild",
+    "dev": "tsx src/cli.ts",
+    "postinstall": "node scripts/install-server.js || true"
+  },
+  "files": ["dist", "src", "scripts"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@magneticjs/server": "^0.1.0",
+    "esbuild": "^0.27.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "tsx": "^4.21.0"
+  },
+  "repository": { "type": "git", "url": "https://github.com/inventhq/magnetic.git", "directory": "js/packages/magnetic-cli" },
+  "homepage": "https://github.com/inventhq/magnetic#readme",
+  "keywords": ["magnetic", "cli", "server-driven-ui", "build-tool"],
+  "license": "MIT"
+}