create-river-miniapp 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# create-river-miniapp
+
+River 小程序脚手架，支持 `html` / `vue` / `react` 三种模板，并内置构建与打包脚本。
+
+## 使用
+
+```bash
+npx create-river-miniapp my-miniapp
+```
+
+或指定模板：
+
+```bash
+npx create-river-miniapp my-miniapp --template vue
+npx create-river-miniapp my-miniapp --template react
+```
+
+无交互模式：
+
+```bash
+npx create-river-miniapp my-miniapp --template html --id local.my_miniapp --name "我的小程序" --yes
+```
+
+## 生成项目常用命令
+
+```bash
+npm install
+npm run dev
+npm run build
+npm run package:miniapp
+```
+
+`npm run package:miniapp` 会输出：
+
+- `miniapp_output/packages/<app_id>.zip`
+- `miniapp_output/miniapps.partial.json`
+
+可将 `miniapps.partial.json` 的条目合并到你的 `miniapps.json` 中。

package/bin/create-river-miniapp.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+const { run } = require('../lib/create');
+
+run(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`\n[create-river-miniapp] ${message}`);
+  process.exit(1);
+});

package/lib/create.js

@@ -0,0 +1,259 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline/promises');
+const { stdin, stdout } = require('node:process');
+
+const TEMPLATE_NAMES = ['html', 'vue', 'react'];
+const TEXT_EXTENSIONS = new Set([
+  '.json',
+  '.js',
+  '.mjs',
+  '.ts',
+  '.tsx',
+  '.vue',
+  '.html',
+  '.css',
+  '.md',
+  '.txt',
+  '.yml',
+  '.yaml',
+]);
+
+function printHelp() {
+  console.log(`
+create-river-miniapp
+
+Usage:
+  create-river-miniapp [target-dir] [options]
+
+Options:
+  -t, --template <html|vue|react>  Template type
+  --id <miniapp-id>                Mini-app id (default: local.<project_name>)
+  --name <display-name>            Mini-app display name
+  -y, --yes                        Skip all prompts
+  -h, --help                       Show help
+`);
+}
+
+function parseArgs(args) {
+  const parsed = {
+    targetDir: '',
+    template: '',
+    appId: '',
+    appName: '',
+    yes: false,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '-h' || arg === '--help') {
+      parsed.help = true;
+      continue;
+    }
+    if (arg === '-y' || arg === '--yes') {
+      parsed.yes = true;
+      continue;
+    }
+    if (arg === '-t' || arg === '--template') {
+      parsed.template = (args[i + 1] || '').trim();
+      i += 1;
+      continue;
+    }
+    if (arg === '--id') {
+      parsed.appId = (args[i + 1] || '').trim();
+      i += 1;
+      continue;
+    }
+    if (arg === '--name') {
+      parsed.appName = (args[i + 1] || '').trim();
+      i += 1;
+      continue;
+    }
+    if (!arg.startsWith('-') && !parsed.targetDir) {
+      parsed.targetDir = arg.trim();
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+  return parsed;
+}
+
+function sanitizeName(value) {
+  return value
+    .trim()
+    .replace(/[^\w.-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+}
+
+function defaultAppId(projectName) {
+  const safe = projectName.replace(/[^\w.-]+/g, '_');
+  return `local.${safe || 'miniapp'}`;
+}
+
+async function askQuestion(rl, question, fallback = '') {
+  const answer = await rl.question(question);
+  const text = answer.trim();
+  if (text) {
+    return text;
+  }
+  return fallback;
+}
+
+async function askTemplate(rl, fallback) {
+  console.log('\n请选择模板:');
+  TEMPLATE_NAMES.forEach((name, index) => {
+    console.log(`  ${index + 1}. ${name}`);
+  });
+  const raw = await askQuestion(rl, `模板 [${fallback}]: `, fallback);
+  const lowered = raw.toLowerCase();
+  if (TEMPLATE_NAMES.includes(lowered)) {
+    return lowered;
+  }
+  const index = Number.parseInt(raw, 10);
+  if (!Number.isNaN(index) && index >= 1 && index <= TEMPLATE_NAMES.length) {
+    return TEMPLATE_NAMES[index - 1];
+  }
+  throw new Error(`Unsupported template: ${raw}`);
+}
+
+function ensureDirEmpty(targetDir) {
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+    return;
+  }
+  const files = fs.readdirSync(targetDir);
+  if (files.length > 0) {
+    throw new Error(`Target directory is not empty: ${targetDir}`);
+  }
+}
+
+function copyDir(src, dst) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const outName = entry.name === '_gitignore' ? '.gitignore' : entry.name;
+    const dstPath = path.join(dst, outName);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, dstPath);
+      continue;
+    }
+    fs.copyFileSync(srcPath, dstPath);
+  }
+}
+
+function applyTemplateVariables(targetDir, variables) {
+  const walk = (dir) => {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const filePath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(filePath);
+        continue;
+      }
+      const ext = path.extname(entry.name).toLowerCase();
+      if (!TEXT_EXTENSIONS.has(ext)) {
+        continue;
+      }
+      let text = fs.readFileSync(filePath, 'utf-8');
+      Object.entries(variables).forEach(([key, value]) => {
+        text = text.replaceAll(`{{${key}}}`, value);
+      });
+      fs.writeFileSync(filePath, text, 'utf-8');
+    }
+  };
+  walk(targetDir);
+}
+
+async function run(rawArgs) {
+  const args = parseArgs(rawArgs);
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const cwd = process.cwd();
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    let targetName = args.targetDir.trim();
+    if (!targetName && args.yes) {
+      throw new Error('Target directory is required in --yes mode.');
+    }
+    if (!targetName) {
+      targetName = await askQuestion(rl, '项目目录名: ');
+    }
+    if (!targetName) {
+      throw new Error('Project directory name is required.');
+    }
+
+    const normalizedTarget = targetName.replace(/[\\/]+/g, path.sep);
+    const projectDir = path.resolve(cwd, normalizedTarget);
+    const projectName = sanitizeName(path.basename(projectDir));
+    if (!projectName) {
+      throw new Error(`Invalid project name: ${targetName}`);
+    }
+
+    let template = args.template.trim().toLowerCase();
+    if (template && !TEMPLATE_NAMES.includes(template)) {
+      throw new Error(`Unsupported template: ${template}`);
+    }
+    if (!template && args.yes) {
+      template = 'html';
+    }
+    if (!template) {
+      template = await askTemplate(rl, 'html');
+    }
+
+    let appId = args.appId.trim();
+    if (!appId && args.yes) {
+      appId = defaultAppId(projectName);
+    }
+    if (!appId) {
+      appId = await askQuestion(rl, `小程序 ID [${defaultAppId(projectName)}]: `, defaultAppId(projectName));
+    }
+    if (!appId) {
+      throw new Error('Mini-app id is required.');
+    }
+
+    let appName = args.appName.trim();
+    const defaultName = projectName;
+    if (!appName && args.yes) {
+      appName = defaultName;
+    }
+    if (!appName) {
+      appName = await askQuestion(rl, `小程序名称 [${defaultName}]: `, defaultName);
+    }
+    if (!appName) {
+      throw new Error('Mini-app display name is required.');
+    }
+
+    ensureDirEmpty(projectDir);
+
+    const templateDir = path.resolve(__dirname, '..', 'templates', template);
+    if (!fs.existsSync(templateDir)) {
+      throw new Error(`Template directory not found: ${templateDir}`);
+    }
+    copyDir(templateDir, projectDir);
+
+    applyTemplateVariables(projectDir, {
+      PROJECT_NAME: projectName,
+      APP_ID: appId,
+      APP_NAME: appName,
+      TEMPLATE: template,
+      YEAR: String(new Date().getFullYear()),
+    });
+
+    console.log(`\n项目已创建: ${projectDir}`);
+    console.log('\n下一步:');
+    console.log(`  cd ${path.relative(cwd, projectDir) || '.'}`);
+    console.log('  npm install');
+    console.log('  npm run dev');
+    console.log('  npm run package:miniapp');
+  } finally {
+    rl.close();
+  }
+}
+
+module.exports = { run };

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "create-river-miniapp",
+  "version": "0.1.0",
+  "description": "Scaffold River mini-app projects with html/vue/react templates",
+  "bin": {
+    "create-river-miniapp": "./bin/create-river-miniapp.js"
+  },
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node ./bin/create-river-miniapp.js --help"
+  },
+  "keywords": [
+    "miniapp",
+    "river",
+    "scaffold",
+    "vue",
+    "react",
+    "html"
+  ],
+  "license": "MIT"
+}

package/templates/html/README.md

@@ -0,0 +1,21 @@
+# {{APP_NAME}}
+
+由 `create-river-miniapp` 生成（HTML 模板）。
+
+## 开发
+
+```bash
+npm install
+npm run dev
+```
+
+## 打包
+
+```bash
+npm run package:miniapp
+```
+
+产物：
+
+- `miniapp_output/packages/{{APP_ID}}.zip`
+- `miniapp_output/miniapps.partial.json`

package/templates/html/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+miniapp_output
+.DS_Store

package/templates/html/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" type="image/svg+xml" href="./icon.svg" />
+    <title>{{APP_NAME}}</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./src/main.js"></script>
+  </body>
+</html>

package/templates/html/miniapp.config.json

@@ -0,0 +1,15 @@
+{
+  "id": "{{APP_ID}}",
+  "name": "{{APP_NAME}}",
+  "slug": "{{PROJECT_NAME}}",
+  "description": "Generated by create-river-miniapp (html template)",
+  "entry": "index.html",
+  "icon": "icon.svg",
+  "requires_auth": false,
+  "enabled": true,
+  "bridge_version": "1.0.0",
+  "tags": [
+    "html",
+    "template"
+  ]
+}

package/templates/html/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "check": "node scripts/check-miniapp.mjs",
+    "package:miniapp": "npm run build && node scripts/package-miniapp.mjs",
+    "package:miniapp:no-build": "node scripts/package-miniapp.mjs"
+  },
+  "devDependencies": {
+    "archiver": "^7.0.1",
+    "vite": "^7.3.1"
+  }
+}

package/templates/html/public/icon.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#12457A"/>
+      <stop offset="1" stop-color="#2174F1"/>
+    </linearGradient>
+  </defs>
+  <rect width="96" height="96" rx="22" fill="url(#g)"/>
+  <path d="M23 66V30h17.8c7.7 0 12.8 4.4 12.8 11.3 0 4.3-2.1 7.4-5.8 9.2l8.6 15.5H45l-7.2-13.4h-4.4V66H23zm10.4-21.6h6.6c2.9 0 4.9-1.8 4.9-4.4 0-2.7-2-4.4-4.9-4.4h-6.6v8.8z" fill="#fff"/>
+  <circle cx="70" cy="27" r="8" fill="#fff" fill-opacity=".86"/>
+</svg>

package/templates/html/scripts/check-miniapp.mjs

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = process.cwd();
+const configPath = path.join(root, 'miniapp.config.json');
+const distIndex = path.join(root, 'dist', 'index.html');
+
+if (!fs.existsSync(configPath)) {
+  console.error('Missing miniapp.config.json');
+  process.exit(1);
+}
+
+const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+const required = ['id', 'name', 'slug', 'entry', 'icon', 'bridge_version'];
+for (const key of required) {
+  const value = String(config[key] ?? '').trim();
+  if (!value) {
+    console.error(`miniapp.config.json missing field: ${key}`);
+    process.exit(1);
+  }
+}
+
+if (!fs.existsSync(distIndex)) {
+  console.error('Missing dist/index.html. Please run `npm run build` first.');
+  process.exit(1);
+}
+
+console.log('Mini-app check passed.');

package/templates/html/scripts/package-miniapp.mjs

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import archiver from 'archiver';
+
+const root = process.cwd();
+const configPath = path.join(root, 'miniapp.config.json');
+const packageJsonPath = path.join(root, 'package.json');
+const distDir = path.join(root, 'dist');
+
+if (!fs.existsSync(configPath)) {
+  throw new Error('Missing miniapp.config.json');
+}
+if (!fs.existsSync(distDir)) {
+  throw new Error('Missing dist directory. Please run `npm run build` first.');
+}
+
+const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+
+const safeId = String(config.id).replace(/[^\w.-]+/g, '_');
+const outputRoot = path.join(root, 'miniapp_output');
+const packageDir = path.join(outputRoot, 'packages');
+const zipName = `${safeId}.zip`;
+const zipPath = path.join(packageDir, zipName);
+
+fs.mkdirSync(packageDir, { recursive: true });
+
+await new Promise((resolve, reject) => {
+  const output = fs.createWriteStream(zipPath);
+  const archive = archiver('zip', { zlib: { level: 9 } });
+  output.on('close', resolve);
+  output.on('error', reject);
+  archive.on('error', reject);
+  archive.pipe(output);
+  archive.directory(distDir, false);
+  archive.finalize();
+});
+
+const sha256 = crypto
+  .createHash('sha256')
+  .update(fs.readFileSync(zipPath))
+  .digest('hex');
+
+const slug = String(config.slug || safeId);
+const iconPath = `./miniapps/${slug}/${config.icon}`;
+const manifest = {
+  version: '1.0.0',
+  updated_at: new Date().toISOString(),
+  apps: [
+    {
+      id: String(config.id),
+      name: String(config.name),
+      version: String(packageJson.version || '1.0.0'),
+      url: `./miniapps/${slug}/${config.entry}`,
+      icon: iconPath,
+      package_url: `./packages/${zipName}`,
+      package_sha256: sha256,
+      description: String(config.description || ''),
+      requires_auth: Boolean(config.requires_auth),
+      enabled: Boolean(config.enabled ?? true),
+      order: Number(config.order ?? 0),
+      bridge_version: String(config.bridge_version || '1.0.0'),
+      tags: Array.isArray(config.tags) ? config.tags : [],
+    },
+  ],
+};
+
+fs.mkdirSync(outputRoot, { recursive: true });
+fs.writeFileSync(
+  path.join(outputRoot, 'miniapps.partial.json'),
+  `${JSON.stringify(manifest, null, 2)}\n`,
+  'utf-8',
+);
+
+console.log(`Packed: ${zipPath}`);
+console.log(`SHA256: ${sha256}`);
+console.log('Manifest snippet: miniapp_output/miniapps.partial.json');

package/templates/html/src/main.js

@@ -0,0 +1,44 @@
+import './style.css';
+
+const app = document.querySelector('#app');
+
+const callBridge = async (action, payload = {}) => {
+  if (!window.RiverMiniApp || typeof window.RiverMiniApp.call !== 'function') {
+    return { ok: false, message: 'Bridge 未注入，当前为普通浏览器模式。' };
+  }
+  try {
+    const result = await window.RiverMiniApp.call(action, payload);
+    return { ok: true, result };
+  } catch (error) {
+    return { ok: false, message: String(error) };
+  }
+};
+
+app.innerHTML = `
+  <main class="container">
+    <section class="card">
+      <h1>{{APP_NAME}}</h1>
+      <p>模板：HTML · 项目：{{PROJECT_NAME}}</p>
+      <div class="actions">
+        <button id="btn-context">获取上下文</button>
+        <button id="btn-title">修改标题</button>
+        <button id="btn-close">关闭小程序</button>
+      </div>
+      <pre id="output">等待操作...</pre>
+    </section>
+  </main>
+`;
+
+const output = document.querySelector('#output');
+document.querySelector('#btn-context').addEventListener('click', async () => {
+  const data = await callBridge('getContext');
+  output.textContent = JSON.stringify(data, null, 2);
+});
+document.querySelector('#btn-title').addEventListener('click', async () => {
+  const data = await callBridge('setTitle', { title: '{{APP_NAME}} 已连接' });
+  output.textContent = JSON.stringify(data, null, 2);
+});
+document.querySelector('#btn-close').addEventListener('click', async () => {
+  const data = await callBridge('close');
+  output.textContent = JSON.stringify(data, null, 2);
+});

package/templates/html/src/style.css

@@ -0,0 +1,74 @@
+:root {
+  color-scheme: light;
+  font-family: 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', sans-serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: linear-gradient(160deg, #f6f8fc 0%, #eef3ff 100%);
+  color: #172033;
+}
+
+.container {
+  min-height: 100dvh;
+  display: grid;
+  place-items: center;
+  padding: 24px;
+}
+
+.card {
+  width: min(680px, 100%);
+  border-radius: 20px;
+  background: #ffffffcc;
+  backdrop-filter: blur(10px);
+  border: 1px solid #dde6fa;
+  box-shadow: 0 20px 50px #12457a1a;
+  padding: 20px;
+}
+
+h1 {
+  margin: 0 0 8px;
+  font-size: 28px;
+}
+
+p {
+  margin: 0 0 16px;
+  color: #4b607e;
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  margin-bottom: 16px;
+}
+
+button {
+  border: 0;
+  border-radius: 12px;
+  padding: 10px 14px;
+  background: #12457a;
+  color: white;
+  cursor: pointer;
+  font-weight: 600;
+}
+
+button:hover {
+  background: #0e3863;
+}
+
+pre {
+  margin: 0;
+  border-radius: 12px;
+  padding: 12px;
+  min-height: 120px;
+  overflow: auto;
+  background: #eff4ff;
+  border: 1px solid #d5e2fb;
+  font-size: 12px;
+  line-height: 1.45;
+}

package/templates/html/vite.config.js

@@ -0,0 +1,5 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  base: './',
+});

package/templates/react/README.md

@@ -0,0 +1,21 @@
+# {{APP_NAME}}
+
+由 `create-river-miniapp` 生成（React 模板）。
+
+## 开发
+
+```bash
+npm install
+npm run dev
+```
+
+## 打包
+
+```bash
+npm run package:miniapp
+```
+
+产物：
+
+- `miniapp_output/packages/{{APP_ID}}.zip`
+- `miniapp_output/miniapps.partial.json`

package/templates/react/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+miniapp_output
+.DS_Store