@nebula-rn/cli 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @nebula-rn/cli
+
+The command-line tool for [Nebula](https://github.com/Hector-Zhuang/nebula), an
+enterprise-grade SuperApp framework for React Native. Scaffold host apps and
+MiniApps, develop them against a universal Dev Runner, build production
+bundles, and upload versions to Nebula Cloud.
+
+> The bare npm name `nebula` belongs to an unrelated package. Always install
+> and invoke the CLI via the `@nebula-rn/cli` package; the installed binary is
+> named `nebula`.
+
+## Quick start
+
+```bash
+# Scaffold a MiniApp
+npx @nebula-rn/cli create miniapp my-miniapp
+cd my-miniapp
+npm install
+
+# Develop with the universal Dev Runner
+npx @nebula-rn/cli miniapp dev
+
+# Build production bundles (iOS + Android) under build/
+npx @nebula-rn/cli miniapp build
+```
+
+You can also install it globally:
+
+```bash
+npm install -g @nebula-rn/cli
+nebula create host my-host
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `nebula create host <name>` | Scaffold a native host project |
+| `nebula create miniapp <name>` | Scaffold a pure-JS MiniApp project |
+| `nebula create runner <name>` | Scaffold a development runner |
+| `nebula miniapp dev` | Start Metro and launch the Dev Runner |
+| `nebula miniapp build` | Build iOS and Android production bundles |
+| `nebula miniapp upload` | Build and upload a version to Nebula Cloud |
+| `nebula auth login` / `logout` | Authenticate against Nebula Cloud |
+| `nebula config server` | Configure the Nebula Cloud API URL |
+
+Scaffolding flags: `--app-id`, `--display-name`, `--bundle-id`, `--directory`.
+Dev flags: `--platform ios|android`, `--no-runner`.
+
+## Requirements
+
+- Node.js >= 20
+- A React Native development environment (Xcode / Android Studio) for running
+  the Dev Runner
+
+## Documentation
+
+- Getting started and guides:
+  https://github.com/Hector-Zhuang/nebula/tree/main/packages/nebula-docs/content/docs
+- CLI reference:
+  https://github.com/Hector-Zhuang/nebula/blob/main/packages/nebula-docs/content/docs/reference/cli.mdx
+
+## License
+
+Apache-2.0

package/dist/create.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createProject = createProject;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const PACKAGED_TEMPLATE_ROOT = path.resolve(__dirname, '../templates');
 const TEMPLATE_PACKAGE_ROOT = path.resolve(__dirname, '../../template');
 const TEXT_TEMPLATE_EXTENSIONS = new Set([
     '.js',
@@ -75,6 +76,10 @@ function readPackageVersion(packageDir) {
     return packageJson.version || '0.0.1';
 }
 function resolvePackageVersions() {
+    const packagedVersionsPath = path.join(PACKAGED_TEMPLATE_ROOT, 'versions.json');
+    if (fs.existsSync(packagedVersionsPath)) {
+        return JSON.parse(fs.readFileSync(packagedVersionsPath, 'utf8'));
+    }
     const packagesDir = path.resolve(__dirname, '../..');
     return {
         sdk: readPackageVersion(path.join(packagesDir, 'nebula-sdk')),
@@ -131,9 +136,13 @@ function ensureTargetDirectory(targetDir) {
     }
 }
 function getTemplateRoot(kind) {
-    const templateRoot = path.join(TEMPLATE_PACKAGE_ROOT, kind);
-    if (!fs.existsSync(templateRoot)) {
-        fail(`Missing ${kind} template at ${templateRoot}`);
+    const candidates = [
+        path.join(PACKAGED_TEMPLATE_ROOT, kind),
+        path.join(TEMPLATE_PACKAGE_ROOT, kind),
+    ];
+    const templateRoot = candidates.find(candidate => fs.existsSync(candidate));
+    if (!templateRoot) {
+        fail(`Missing ${kind} template. Looked in: ${candidates.join(', ')}`);
     }
     return templateRoot;
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@nebula-rn/cli",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Nebula CLI - build, bundle and upload mini-apps",
   "author": "Hector Zhuang",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Hector-Zhuang/nebula.git",
@@ -13,17 +13,30 @@
     "url": "https://github.com/Hector-Zhuang/nebula/issues"
   },
   "homepage": "https://github.com/Hector-Zhuang/nebula/tree/main/packages/cli#readme",
-  "keywords": ["nebula", "superapp", "miniapp", "cli"],
+  "keywords": [
+    "nebula",
+    "superapp",
+    "miniapp",
+    "cli"
+  ],
   "main": "./dist/cli.js",
   "types": "./dist/cli.d.ts",
   "bin": {
     "nebula": "./dist/cli.js"
   },
-  "files": ["dist", "bin", "README.md"],
-  "publishConfig": { "access": "public" },
+  "files": [
+    "dist",
+    "bin",
+    "templates",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc",
-    "prepack": "npm run build"
+    "bundle:templates": "node scripts/copy-templates.mjs",
+    "prepack": "npm run build && npm run bundle:templates"
   },
   "dependencies": {
     "archiver": "^8.0.0"
@@ -31,4 +44,4 @@
   "devDependencies": {
     "@types/archiver": "^8.0.0"
   }
-}
+}

package/templates/host/.eslintrc.js

@@ -0,0 +1,7 @@
+module.exports = {
+  parserOptions: {
+    babelOptions: {
+      configFile: __dirname + '/babel.config.js',
+    },
+  },
+};

package/templates/host/App.tsx

@@ -0,0 +1,118 @@
+import React from 'react';
+import { ScrollView, StyleSheet, Text, View } from 'react-native';
+import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
+import { defaultHostApis } from '@nebula-rn/host-apis';
+import type { MiniappLoadingResolveContext } from '@nebula-rn/sdk';
+import { NebulaAPI } from '@nebula-rn/sdk';
+
+function DefaultMiniappLoadingScreen({
+  title,
+  appId,
+  status,
+}: MiniappLoadingResolveContext) {
+  return (
+    <View style={styles.loadingOverlay}>
+      <View style={styles.loadingCard}>
+        <Text style={styles.loadingEyebrow}>Nebula</Text>
+        <Text style={styles.loadingTitle}>{title || appId}</Text>
+        <Text style={styles.loadingMessage}>
+          {status === 'installing'
+            ? 'Installing miniapp...'
+            : status === 'error'
+              ? 'Something went wrong while opening the miniapp.'
+              : 'Opening miniapp...'}
+        </Text>
+      </View>
+    </View>
+  );
+}
+
+function HostAppContent() {
+  return (
+    <SafeAreaProvider>
+      <SafeAreaView style={styles.screen}>
+        <ScrollView contentContainerStyle={styles.content}>
+          <Text style={styles.title}>Nebula Host Starter</Text>
+          <Text style={styles.subtitle}>
+            This starter is a clean Nebula host shell. Register your own host
+            APIs, connect Nebula Cloud, and decide how your host opens miniapps.
+          </Text>
+
+          <View style={styles.section}>
+            <Text style={styles.sectionTitle}>What is included</Text>
+            <Text style={styles.sectionBody}>• Nebula runtime wrapper</Text>
+            <Text style={styles.sectionBody}>
+              • Default host API set from @nebula-rn/host-apis
+            </Text>
+            <Text style={styles.sectionBody}>
+              • A minimal loading screen for miniapp startup
+            </Text>
+          </View>
+
+          <View style={styles.section}>
+            <Text style={styles.sectionTitle}>Next steps</Text>
+            <Text style={styles.sectionBody}>
+              1. Configure serverBaseURL for Nebula Cloud
+            </Text>
+            <Text style={styles.sectionBody}>
+              2. Register your own host APIs where needed
+            </Text>
+            <Text style={styles.sectionBody}>
+              3. Open installed miniapps by appId or dev bundle URL
+            </Text>
+          </View>
+        </ScrollView>
+      </SafeAreaView>
+    </SafeAreaProvider>
+  );
+}
+
+export default NebulaAPI.wrap({
+  hostApis: [...defaultHostApis],
+  miniappLoading: {
+    component: DefaultMiniappLoadingScreen,
+    delayMs: 300,
+    enterContentDelayMs: 120,
+  },
+})(HostAppContent);
+
+const styles = StyleSheet.create({
+  screen: { flex: 1, backgroundColor: '#f8fafc' },
+  content: { padding: 20, gap: 16 },
+  title: { fontSize: 28, fontWeight: '700', color: '#0f172a' },
+  subtitle: { fontSize: 16, lineHeight: 24, color: '#475569' },
+  section: {
+    borderRadius: 18,
+    backgroundColor: '#ffffff',
+    borderWidth: 1,
+    borderColor: '#dbe4f0',
+    padding: 18,
+    gap: 8,
+  },
+  sectionTitle: { fontSize: 16, fontWeight: '700', color: '#0f172a' },
+  sectionBody: { fontSize: 14, lineHeight: 22, color: '#475569' },
+  loadingOverlay: {
+    flex: 1,
+    backgroundColor: 'rgba(15, 23, 42, 0.14)',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 24,
+  },
+  loadingCard: {
+    width: '100%',
+    maxWidth: 420,
+    borderRadius: 24,
+    backgroundColor: '#ffffff',
+    padding: 24,
+    gap: 10,
+  },
+  loadingEyebrow: {
+    fontSize: 12,
+    fontWeight: '700',
+    letterSpacing: 1.2,
+    color: '#2563eb',
+    textTransform: 'uppercase',
+  },
+  loadingTitle: { fontSize: 24, fontWeight: '700', color: '#0f172a' },
+  loadingMessage: { fontSize: 15, lineHeight: 22, color: '#475569' },
+});

package/templates/host/Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+
+# You may use http://rbenv.org/ or https://rvm.io/ to install and use this version
+ruby ">= 2.6.10"
+
+# Exclude problematic versions of cocoapods and activesupport that causes build failures.
+gem 'cocoapods', '>= 1.13', '!= 1.15.0', '!= 1.15.1'
+gem 'activesupport', '>= 6.1.7.5', '!= 7.1.0'
+gem 'xcodeproj', '< 1.26.0'
+gem 'concurrent-ruby', '< 1.3.4'
+
+# Ruby 3.4.0 has removed some libraries from the standard library.
+gem 'bigdecimal'
+gem 'logger'
+gem 'benchmark'
+gem 'mutex_m'

package/templates/host/__tests__/App.test.tsx

@@ -0,0 +1,13 @@
+/**
+ * @format
+ */
+
+import React from 'react';
+import ReactTestRenderer from 'react-test-renderer';
+import App from '../App';
+
+test('renders correctly', async () => {
+  await ReactTestRenderer.act(() => {
+    ReactTestRenderer.create(<App />);
+  });
+});

package/templates/host/android/app/build.gradle

@@ -0,0 +1,55 @@
+apply plugin: "com.android.application"
+apply plugin: "org.jetbrains.kotlin.android"
+apply plugin: "com.facebook.react"
+
+react {
+    autolinkLibrariesWithApp()
+}
+
+def enableProguardInReleaseBuilds = false
+def jscFlavor = 'io.github.react-native-community:jsc-android:2026004.+'
+
+android {
+    ndkVersion rootProject.ext.ndkVersion
+    buildToolsVersion rootProject.ext.buildToolsVersion
+    compileSdk rootProject.ext.compileSdkVersion
+
+    namespace "__BUNDLE_ID__"
+    defaultConfig {
+        applicationId "__BUNDLE_ID__"
+        minSdkVersion rootProject.ext.minSdkVersion
+        targetSdkVersion rootProject.ext.targetSdkVersion
+        versionCode 1
+        versionName "1.0"
+        manifestPlaceholders = [nebulaUrlScheme: "nebula"]
+    }
+    signingConfigs {
+        debug {
+            storeFile file('debug.keystore')
+            storePassword 'android'
+            keyAlias 'androiddebugkey'
+            keyPassword 'android'
+        }
+    }
+    buildTypes {
+        debug {
+            signingConfig signingConfigs.debug
+        }
+        release {
+            signingConfig signingConfigs.debug
+            minifyEnabled enableProguardInReleaseBuilds
+            proguardFiles getDefaultProguardFile("proguard-android.txt"), "proguard-rules.pro"
+        }
+    }
+}
+
+dependencies {
+    implementation("com.facebook.react:react-android")
+    implementation("androidx.appcompat:appcompat:1.7.1")
+
+    if (hermesEnabled.toBoolean()) {
+        implementation("com.facebook.react:hermes-android")
+    } else {
+        implementation jscFlavor
+    }
+}

package/templates/host/android/app/proguard-rules.pro

@@ -0,0 +1,10 @@
+# Add project specific ProGuard rules here.
+# By default, the flags in this file are appended to flags specified
+# in /usr/local/Cellar/android-sdk/24.3.3/tools/proguard/proguard-android.txt
+# You can edit the include path and order by changing the proguardFiles
+# directive in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# Add any project specific keep options here:

package/templates/host/android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,54 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-permission android:name="android.permission.DETECT_SCREEN_CAPTURE" />
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
+    <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
+    <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
+    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
+    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="28" />
+
+    <application
+      android:name=".MainApplication"
+      android:label="@string/app_name"
+      android:icon="@mipmap/ic_launcher"
+      android:roundIcon="@mipmap/ic_launcher_round"
+      android:allowBackup="false"
+      android:theme="@style/AppTheme"
+      android:usesCleartextTraffic="${usesCleartextTraffic}"
+      android:supportsRtl="true">
+      <activity
+        android:name=".MainActivity"
+        android:label="@string/app_name"
+        android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"
+        android:launchMode="singleTask"
+        android:windowSoftInputMode="adjustResize"
+        android:exported="true">
+        <intent-filter>
+            <action android:name="android.intent.action.MAIN" />
+            <category android:name="android.intent.category.LAUNCHER" />
+        </intent-filter>
+        <intent-filter>
+            <action android:name="android.intent.action.VIEW" />
+            <category android:name="android.intent.category.DEFAULT" />
+            <category android:name="android.intent.category.BROWSABLE" />
+            <data android:scheme="${nebulaUrlScheme}" android:host="review" android:pathPrefix="/install/" />
+            <data android:scheme="${nebulaUrlScheme}" android:host="miniapp" android:pathPrefix="/install/" />
+        </intent-filter>
+      </activity>
+      <activity
+        android:name="com.hectorzhuang.nebula.NebulaActivity"
+        android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"
+        android:windowSoftInputMode="adjustResize"
+        android:exported="false" />
+      <activity
+        android:name="com.hectorzhuang.nebula.NebulaHostModalActivity"
+        android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"
+        android:theme="@style/NebulaHostModalTheme"
+        android:windowSoftInputMode="adjustResize"
+        android:exported="false" />
+    </application>
+</manifest>

package/templates/host/android/app/src/main/java/com/SuperApp/MainActivity.kt

@@ -0,0 +1,28 @@
+package com.SuperApp
+
+import android.content.Intent
+import android.os.Bundle
+import com.facebook.react.ReactActivity
+import com.facebook.react.ReactActivityDelegate
+import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
+import com.facebook.react.defaults.DefaultReactActivityDelegate
+import com.hectorzhuang.nebula.NebulaHost
+
+class MainActivity : ReactActivity() {
+
+  override fun getMainComponentName(): String = "__COMPONENT_NAME__"
+
+  override fun createReactActivityDelegate(): ReactActivityDelegate =
+      DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled)
+
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    NebulaHost.handleIncomingUrl(this, intent?.data)
+  }
+
+  override fun onNewIntent(intent: Intent) {
+    super.onNewIntent(intent)
+    setIntent(intent)
+    NebulaHost.handleIncomingUrl(this, intent.data)
+  }
+}

package/templates/host/android/app/src/main/java/com/SuperApp/MainApplication.kt

@@ -0,0 +1,35 @@
+package com.SuperApp
+
+import android.app.Application
+import com.hectorzhuang.nebula.NebulaHost
+import com.hectorzhuang.nebula.NebulaHostDelegate
+import com.facebook.react.PackageList
+import com.facebook.react.ReactApplication
+import com.facebook.react.ReactHost
+import com.facebook.react.ReactPackage
+import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
+import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
+
+class MainApplication : Application(), ReactApplication {
+
+  override val reactHost: ReactHost by lazy {
+    getDefaultReactHost(
+      context = applicationContext,
+      packageList = PackageList(this).packages,
+    )
+  }
+
+  override fun onCreate() {
+    super.onCreate()
+    loadReactNative(this)
+    NebulaHost.initialize(
+      this,
+      object : NebulaHostDelegate {
+        override fun isDebugBuild(): Boolean = BuildConfig.DEBUG
+
+        override fun createMiniAppPackages(application: Application): List<ReactPackage> =
+          PackageList(this@MainApplication).packages
+      },
+    )
+  }
+}

package/templates/host/android/app/src/main/res/drawable/rn_edit_text_material.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (C) 2014 The Android Open Source Project
+
+     Licensed under the Apache License, Version 2.0 (the "License");
+     you may not use this file except in compliance with the License.
+     You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+     Unless required by applicable law or agreed to in writing, software
+     distributed under the License is distributed on an "AS IS" BASIS,
+     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+     See the License for the specific language governing permissions and
+     limitations under the License.
+-->
+<inset xmlns:android="http://schemas.android.com/apk/res/android"
+       android:insetLeft="@dimen/abc_edit_text_inset_horizontal_material"
+       android:insetRight="@dimen/abc_edit_text_inset_horizontal_material"
+       android:insetTop="@dimen/abc_edit_text_inset_top_material"
+       android:insetBottom="@dimen/abc_edit_text_inset_bottom_material"
+       >
+
+    <selector>
+        <!--
+          This file is a copy of abc_edit_text_material (https://bit.ly/3k8fX7I).
+          The item below with state_pressed="false" and state_focused="false" causes a NullPointerException.
+          NullPointerException:tempt to invoke virtual method 'android.graphics.drawable.Drawable android.graphics.drawable.Drawable$ConstantState.newDrawable(android.content.res.Resources)'
+
+          <item android:state_pressed="false" android:state_focused="false" android:drawable="@drawable/abc_textfield_default_mtrl_alpha"/>
+
+          For more info, see https://bit.ly/3CdLStv (react-native/pull/29452) and https://bit.ly/3nxOMoR.
+        -->
+        <item android:state_enabled="false" android:drawable="@drawable/abc_textfield_default_mtrl_alpha"/>
+        <item android:drawable="@drawable/abc_textfield_activated_mtrl_alpha"/>
+    </selector>
+
+</inset>

package/templates/host/android/app/src/main/res/values/strings.xml

@@ -0,0 +1,3 @@
+<resources>
+    <string name="app_name">__DISPLAY_NAME__</string>
+</resources>

package/templates/host/android/app/src/main/res/values/styles.xml

@@ -0,0 +1,16 @@
+<resources>
+
+    <!-- Base application theme. -->
+    <style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
+        <!-- Customize your theme here. -->
+        <item name="android:editTextBackground">@drawable/rn_edit_text_material</item>
+    </style>
+
+    <style name="NebulaHostModalTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
+        <item name="android:windowIsTranslucent">true</item>
+        <item name="android:windowBackground">@android:color/transparent</item>
+        <item name="android:backgroundDimEnabled">false</item>
+        <item name="android:windowAnimationStyle">@null</item>
+    </style>
+
+</resources>

package/templates/host/android/build.gradle

@@ -0,0 +1,21 @@
+buildscript {
+    ext {
+        buildToolsVersion = "36.0.0"
+        minSdkVersion = 24
+        compileSdkVersion = 36
+        targetSdkVersion = 36
+        ndkVersion = "27.1.12297006"
+        kotlinVersion = "2.1.20"
+    }
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath("com.android.tools.build:gradle")
+        classpath("com.facebook.react:react-native-gradle-plugin")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin")
+    }
+}
+
+apply plugin: "com.facebook.react.rootproject"

package/templates/host/android/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.0.0-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists