zelune 0.0.0-stage → 1.5.1

package/bin/cli.mjs

@@ -0,0 +1,427 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const defaultPackageRoot = path.resolve(__dirname, '..');
+const requireFromCli = createRequire(import.meta.url);
+
+const SCREEN_DIR_CANDIDATES = ['src/screens', 'screens', 'app', 'src/app'];
+const IGNORED_SCAN_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  '.expo',
+  '.turbo',
+  'ios',
+  'android',
+  'vendor',
+  'coverage',
+  '.agents',
+  '.gemini',
+]);
+
+function isHostPortFree(port, host) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.on('error', (err) => {
+      if (err && (err.code === 'EADDRNOTAVAIL' || err.code === 'EAFNOSUPPORT')) {
+        resolve(true);
+        return;
+      }
+      resolve(false);
+    });
+    server.listen({ port, host, exclusive: true }, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+export async function isPortFree(port) {
+  const [ipv4Free, ipv6Free] = await Promise.all([
+    isHostPortFree(port, '127.0.0.1'),
+    isHostPortFree(port, '::1'),
+  ]);
+  return ipv4Free && ipv6Free;
+}
+
+export async function findAvailablePort(startPort = 5173, maxAttempts = 25) {
+  for (let offset = 0; offset < maxAttempts; offset++) {
+    const candidate = startPort + offset;
+    if (await isPortFree(candidate)) {
+      return candidate;
+    }
+  }
+  return startPort;
+}
+
+function countScreenFilesInDirectory(screensDir, maxDepth = 4) {
+  let count = 0;
+  function walk(curr, depth) {
+    if (depth > maxDepth) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(curr, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      if (entry.isDirectory()) {
+        if (
+          entry.name === 'node_modules' ||
+          entry.name === '__tests__' ||
+          entry.name === 'components'
+        ) {
+          continue;
+        }
+        walk(path.join(curr, entry.name), depth + 1);
+      } else if (entry.isFile()) {
+        const f = entry.name;
+        if (f.startsWith('_') || f.startsWith('+')) continue;
+        if (f === 'index.ts' || f === 'index.js') continue;
+        if (f.includes('.test.') || f.includes('.spec.') || f.endsWith('.d.ts')) continue;
+        if (f.endsWith('.tsx') || f.endsWith('.jsx')) {
+          count++;
+        }
+      }
+    }
+  }
+  walk(screensDir, 0);
+  return count;
+}
+
+function hasDirectScreens(dirPath) {
+  for (const rel of SCREEN_DIR_CANDIDATES) {
+    const full = path.join(dirPath, rel);
+    try {
+      if (fs.existsSync(full) && fs.statSync(full).isDirectory()) {
+        const count = countScreenFilesInDirectory(full);
+        if (count > 0) {
+          return { found: true, relDir: rel, count };
+        }
+      }
+    } catch {
+      // Ignore
+    }
+  }
+  return { found: false, relDir: null, count: 0 };
+}
+
+function scoreMobileCandidate(dirPath, screenCount) {
+  let score = screenCount;
+  const folderName = path.basename(dirPath).toLowerCase();
+  if (/mobile|native|expo|app|client/.test(folderName)) {
+    score += 10;
+  }
+  if (fs.existsSync(path.join(dirPath, 'app.json')) || fs.existsSync(path.join(dirPath, 'eas.json'))) {
+    score += 25;
+  }
+  try {
+    const pkgPath = path.join(dirPath, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkgRaw = fs.readFileSync(pkgPath, 'utf8');
+      if (pkgRaw.includes('"react-native"') || pkgRaw.includes('"expo"')) {
+        score += 20;
+      }
+    }
+  } catch {
+    // Ignore
+  }
+  return score;
+}
+
+export function findMobileAppRoot(rawRoot) {
+  const normalizedRoot = path.resolve(rawRoot);
+  if (!fs.existsSync(normalizedRoot)) {
+    return normalizedRoot;
+  }
+
+  const direct = hasDirectScreens(normalizedRoot);
+  if (direct.found) {
+    return normalizedRoot;
+  }
+
+  let bestCandidate = null;
+  let bestScore = -1;
+
+  function scanSubdirs(parentDir, depth) {
+    if (depth > 2) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(parentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+      if (IGNORED_SCAN_DIRS.has(entry.name)) continue;
+
+      const subPath = path.join(parentDir, entry.name);
+      const check = hasDirectScreens(subPath);
+      if (check.found) {
+        const score = scoreMobileCandidate(subPath, check.count);
+        if (score > bestScore) {
+          bestScore = score;
+          bestCandidate = subPath;
+        }
+      } else if (depth < 2) {
+        scanSubdirs(subPath, depth + 1);
+      }
+    }
+  }
+
+  scanSubdirs(normalizedRoot, 1);
+  return bestCandidate ?? normalizedRoot;
+}
+
+function detectScreensDirectory(targetProject) {
+  const mobileRoot = findMobileAppRoot(targetProject);
+  // First check directories with .tsx/.jsx screen files
+  for (const rel of SCREEN_DIR_CANDIDATES) {
+    const full = path.join(mobileRoot, rel);
+    if (fs.existsSync(full) && fs.statSync(full).isDirectory() && countScreenFilesInDirectory(full) > 0) {
+      const relFromTarget = path.relative(targetProject, full).replace(/\\/g, '/');
+      return relFromTarget || rel;
+    }
+  }
+  // Fallback to existing empty candidate directory (e.g. newly initialized project)
+  for (const rel of SCREEN_DIR_CANDIDATES) {
+    const full = path.join(mobileRoot, rel);
+    if (fs.existsSync(full) && fs.statSync(full).isDirectory()) {
+      const relFromTarget = path.relative(targetProject, full).replace(/\\/g, '/');
+      return relFromTarget || rel;
+    }
+  }
+  return null;
+}
+
+function addCanvasScriptToPackageJson(dirPath) {
+  const pkgJsonPath = path.join(dirPath, 'package.json');
+  if (!fs.existsSync(pkgJsonPath)) return false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+    pkg.scripts = pkg.scripts || {};
+    if (pkg.name !== 'zelune' && !pkg.scripts.canvas) {
+      pkg.scripts.canvas = 'zelune';
+      fs.writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+      return true;
+    }
+  } catch {
+    // Ignore malformed package.json
+  }
+  return false;
+}
+
+export function initProject(targetProject, packageRoot = defaultPackageRoot) {
+  const resolvedTarget = path.resolve(targetProject);
+  const mobileRoot = findMobileAppRoot(resolvedTarget);
+  const screensDir = detectScreensDirectory(resolvedTarget);
+
+  // 1. Update package.json with "canvas": "zelune" script in target root (and nested mobile root if different)
+  let updatedPackageJson = addCanvasScriptToPackageJson(resolvedTarget);
+  if (mobileRoot !== resolvedTarget) {
+    const updatedNested = addCanvasScriptToPackageJson(mobileRoot);
+    updatedPackageJson = updatedPackageJson || updatedNested;
+  }
+
+  // 2. Create or merge mcp_config.json with the zelune MCP server entry
+  const mcpConfigPath = path.join(resolvedTarget, 'mcp_config.json');
+  let mcpConfig = { mcpServers: {} };
+  if (fs.existsSync(mcpConfigPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(mcpConfigPath, 'utf8'));
+      if (parsed && typeof parsed === 'object') {
+        mcpConfig = parsed;
+        mcpConfig.mcpServers = mcpConfig.mcpServers || {};
+      }
+    } catch {
+      mcpConfig = { mcpServers: {} };
+    }
+  }
+  mcpConfig.mcpServers.zelune = {
+    command: 'npx',
+    args: ['-y', 'zelune', '--mcp', '--project', mobileRoot],
+  };
+  fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2) + '\n', 'utf8');
+
+  // 3. Install AI Agent Skill into .agents/skills/zelune/SKILL.md
+  const sourceSkillPath = path.join(packageRoot, 'skills/rn-canvas/SKILL.md');
+  const destSkillDir = path.join(resolvedTarget, '.agents/skills/zelune');
+  const destSkillPath = path.join(destSkillDir, 'SKILL.md');
+  if (fs.existsSync(sourceSkillPath)) {
+    fs.mkdirSync(destSkillDir, { recursive: true });
+    fs.copyFileSync(sourceSkillPath, destSkillPath);
+  }
+
+  // 4. Copy starter DESIGN.md & PRODUCT.md if not already present
+  let createdDesignMd = false;
+  const sourceDesignPath = path.join(packageRoot, 'DESIGN.md');
+  const destDesignPath = path.join(resolvedTarget, 'DESIGN.md');
+  if (fs.existsSync(sourceDesignPath) && !fs.existsSync(destDesignPath)) {
+    fs.copyFileSync(sourceDesignPath, destDesignPath);
+    createdDesignMd = true;
+  }
+
+  let createdProductMd = false;
+  const sourceProductPath = path.join(packageRoot, 'PRODUCT.md');
+  const destProductPath = path.join(resolvedTarget, 'PRODUCT.md');
+  if (fs.existsSync(sourceProductPath) && !fs.existsSync(destProductPath)) {
+    fs.copyFileSync(sourceProductPath, destProductPath);
+    createdProductMd = true;
+  }
+
+  // 5. Ensure .canvas-layout.json is listed in .gitignore
+  const gitignorePath = path.join(resolvedTarget, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    const currentIgnore = fs.readFileSync(gitignorePath, 'utf8');
+    if (!currentIgnore.split(/\r?\n/).includes('.canvas-layout.json')) {
+      const prefix = currentIgnore.endsWith('\n') || currentIgnore.length === 0 ? '' : '\n';
+      fs.writeFileSync(
+        gitignorePath,
+        `${currentIgnore}${prefix}.canvas-layout.json\n`,
+        'utf8'
+      );
+    }
+  } else {
+    fs.writeFileSync(gitignorePath, '.canvas-layout.json\n', 'utf8');
+  }
+
+  return {
+    targetProject: resolvedTarget,
+    mobileRoot,
+    screensDir: screensDir ?? 'src/screens (or app/)',
+    updatedPackageJson,
+    mcpConfigPath,
+    skillPath: destSkillPath,
+    createdDesignMd,
+    createdProductMd,
+  };
+}
+
+async function runCli() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Zelune — React Native Visual Canvas & AST Sync MCP Server
+
+Usage:
+  zelune                       Launch visual canvas for current project (auto-selects free port & opens browser)
+  zelune init                  One-command setup for the current React Native / Expo project
+  zelune --project <dir>       Target a specific React Native / Expo project directory
+  zelune --port <number>       Use a specific port (default: auto-detects from 5173)
+  zelune --no-open             Do not automatically open the browser on launch
+  zelune --mcp                 Start the Zelune stdio MCP server for Google Antigravity / Cursor / Claude Code
+`);
+    process.exit(0);
+  }
+
+  const isMcpMode = args.includes('--mcp');
+  const isInitMode = args[0] === 'init' || args[0] === 'setup';
+
+  let targetProject = process.cwd();
+  const projectFlagIdx = args.indexOf('--project');
+  if (projectFlagIdx !== -1 && args[projectFlagIdx + 1]) {
+    targetProject = path.resolve(args[projectFlagIdx + 1]);
+  }
+
+  if (isInitMode) {
+    const result = initProject(targetProject, defaultPackageRoot);
+    console.log(`\n✨ Zelune initialized in ${result.targetProject}`);
+    if (result.mobileRoot !== result.targetProject) {
+      console.log(`   • Detected nested mobile app: ${result.mobileRoot}`);
+    }
+    console.log(`   • Screens directory: ${result.screensDir}`);
+    if (result.updatedPackageJson) {
+      console.log(`   • Added "canvas": "zelune" script to package.json`);
+    }
+    console.log(`   • Configured MCP server in mcp_config.json`);
+    console.log(`   • Installed AI skill in .agents/skills/zelune/SKILL.md`);
+    if (result.createdDesignMd || result.createdProductMd) {
+      console.log(`   • Created starter DESIGN.md & PRODUCT.md governance docs`);
+    }
+    console.log(`\n👉 Run "npx zelune" (or "npm run canvas") to open your screens in the visual canvas!\n`);
+    process.exit(0);
+  }
+
+  const resolvedMobileRoot = findMobileAppRoot(targetProject);
+  const env = {
+    ...process.env,
+    ANTIGRAVITY_TARGET_PROJECT: resolvedMobileRoot,
+  };
+
+  if (isMcpMode) {
+    const mcpServerPath = path.join(defaultPackageRoot, 'mcp/server.ts');
+    const child = spawn('npx', ['tsx', mcpServerPath], {
+      cwd: defaultPackageRoot,
+      env,
+      stdio: 'inherit',
+    });
+    child.on('exit', (code) => process.exit(code ?? 0));
+    return;
+  }
+
+  const portFlagIdx = args.indexOf('--port');
+  let port;
+  if (portFlagIdx !== -1 && args[portFlagIdx + 1]) {
+    const parsedPort = Number.parseInt(String(args[portFlagIdx + 1]), 10);
+    if (!Number.isInteger(parsedPort) || parsedPort < 1 || parsedPort > 65535) {
+      console.error(
+        `Error: Invalid --port value "${args[portFlagIdx + 1]}". Must be an integer between 1 and 65535.`
+      );
+      process.exit(1);
+    }
+    port = String(parsedPort);
+  } else {
+    const resolvedPort = await findAvailablePort(5173);
+    port = String(resolvedPort);
+  }
+
+  const shouldOpenBrowser = !args.includes('--no-open');
+  const viteCliFlags = ['--host', '127.0.0.1', '--port', port];
+  if (shouldOpenBrowser) {
+    viteCliFlags.push('--open');
+  }
+
+  console.log(`\n🚀 Zelune — React Native Visual Canvas & MCP`);
+  console.log(`📂 Workspace Root: ${targetProject}`);
+  if (resolvedMobileRoot !== targetProject) {
+    console.log(`📱 Mobile App Dir: ${resolvedMobileRoot}`);
+  }
+  console.log(`🌐 Studio URL:     http://127.0.0.1:${port}\n`);
+
+  let child;
+  try {
+    const viteBinPath = requireFromCli.resolve('vite/bin/vite.js');
+    child = spawn(process.execPath, [viteBinPath, ...viteCliFlags], {
+      cwd: defaultPackageRoot,
+      env,
+      stdio: 'inherit',
+    });
+  } catch {
+    child = spawn('npx', ['vite', ...viteCliFlags], {
+      cwd: defaultPackageRoot,
+      env,
+      stdio: 'inherit',
+    });
+  }
+
+  child.on('exit', (code) => process.exit(code ?? 0));
+}
+
+const isDirectExecution =
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href;
+
+if (isDirectExecution) {
+  runCli();
+}

package/index.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en" class="dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Zelune — React Native Visual Canvas &amp; AST Studio</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&family=Plus+Jakarta+Sans:wght@400;500;600;700;800&display=swap"
+      rel="stylesheet"
+    />
+  </head>
+  <body class="bg-[#08090C] text-[#F1F5F9] antialiased selection:bg-sky-500/25 overflow-hidden">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/mcp/server.ts

@@ -0,0 +1,196 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import {
+  discoverScreens,
+  inspectElement,
+  patchElement,
+  reorderElement,
+  type StyleValue,
+} from '../src/server/astEngine.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WORKSPACE_ROOT = path.resolve(__dirname, '..');
+
+const server = new Server(
+  {
+    name: 'zelune',
+    version: '1.5.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'list_canvas_screens',
+        description:
+          'Lists all discovered React Native screens on the visual canvas along with their element counts and outgoing navigation flow edges.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+      {
+        name: 'inspect_screen_element',
+        description:
+          'Inspects a specific JSX element inside a React Native screen by its relative file path and AST index path.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            file: {
+              type: 'string',
+              description: 'Relative path to the screen file (e.g. src/screens/HomeScreen.tsx)',
+            },
+            astPath: {
+              type: 'string',
+              description: 'Preorder AST index of the JSX element (e.g. "0", "4")',
+            },
+          },
+          required: ['file', 'astPath'],
+        },
+      },
+      {
+        name: 'patch_screen_element',
+        description:
+          'Surgically patches the text copy or StyleSheet properties of a React Native JSX element.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            file: {
+              type: 'string',
+              description: 'Relative path to the screen file (e.g. src/screens/HomeScreen.tsx)',
+            },
+            astPath: {
+              type: 'string',
+              description: 'Preorder AST index of the JSX element',
+            },
+            text: {
+              type: 'string',
+              description: 'Optional new static text content for <Text> elements',
+            },
+            styles: {
+              type: 'object',
+              description: 'Optional map of React Native style properties to update',
+            },
+          },
+          required: ['file', 'astPath'],
+        },
+      },
+      {
+        name: 'reorder_screen_element',
+        description:
+          'Surgically reorders a React Native JSX element among its Flexbox siblings in the .tsx AST.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            file: {
+              type: 'string',
+              description: 'Relative path to the screen file (e.g. src/screens/HomeScreen.tsx)',
+            },
+            astPath: {
+              type: 'string',
+              description: 'Preorder AST index of the JSX element to move',
+            },
+            direction: {
+              type: 'string',
+              enum: ['up', 'down'],
+              description: 'Optional relative direction ("up" or "down") among siblings',
+            },
+            targetAstPath: {
+              type: 'string',
+              description: 'Optional AST index of the sibling to place before/after',
+            },
+            placement: {
+              type: 'string',
+              enum: ['before', 'after'],
+              description: 'Whether to insert before or after targetAstPath',
+            },
+          },
+          required: ['file', 'astPath'],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  if (name === 'list_canvas_screens') {
+    const screens = await discoverScreens(WORKSPACE_ROOT);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(screens, null, 2) }],
+    };
+  }
+
+  if (name === 'inspect_screen_element') {
+    const file = String(args?.file ?? '');
+    const astPath = String(args?.astPath ?? '0');
+    const element = await inspectElement(WORKSPACE_ROOT, { file, astPath });
+    return {
+      content: [{ type: 'text', text: JSON.stringify(element, null, 2) }],
+    };
+  }
+
+  if (name === 'patch_screen_element') {
+    const file = String(args?.file ?? '');
+    const astPath = String(args?.astPath ?? '0');
+    const text = typeof args?.text === 'string' ? args.text : undefined;
+    const styles = (args?.styles as Record<string, StyleValue> | undefined) ?? undefined;
+
+    const result = await patchElement(WORKSPACE_ROOT, {
+      file,
+      astPath,
+      text,
+      styles,
+    });
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  }
+
+  if (name === 'reorder_screen_element') {
+    const file = String(args?.file ?? '');
+    const astPath = String(args?.astPath ?? '0');
+    const direction =
+      args?.direction === 'up' || args?.direction === 'down' ? args.direction : undefined;
+    const targetAstPath =
+      typeof args?.targetAstPath === 'string' ? args.targetAstPath : undefined;
+    const placement =
+      args?.placement === 'before' || args?.placement === 'after' ? args.placement : undefined;
+
+    const result = await reorderElement(WORKSPACE_ROOT, {
+      file,
+      astPath,
+      direction,
+      targetAstPath,
+      placement,
+    });
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  }
+
+  throw new Error(`Unknown MCP tool: ${name}`);
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error('MCP Server Error:', err);
+  process.exit(1);
+});

package/mcp_config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "zelune": {
+      "command": "npx",
+      "args": ["-y", "zelune", "--mcp"]
+    }
+  }
+}