react-native-flux-desktop-packer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keyon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# react-native-flux-desktop-packer
+
+[**English**](./README.md) | [简体中文](./README.zh-CN.md)
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/react-native-flux-desktop-packer"><img src="https://img.shields.io/npm/v/react-native-flux-desktop-packer?style=flat-square&color=cb3837" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/react-native-flux-desktop-packer"><img src="https://img.shields.io/npm/dm/react-native-flux-desktop-packer?style=flat-square" alt="npm downloads"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/platform-win32-lightgrey?style=flat-square" alt="win32 only">
+</p>
+
+Turn a [react-native-flux-desktop](https://www.npmjs.com/package/react-native-flux-desktop) app into a **single self-contained Windows `.exe`** — no Electron, no installer, no Node.js required on the target machine. End users double-click one file and get a native window.
+
+## How it works
+
+```
+app.json ──▶ [1] stage payload      dist/ + node_modules/ + assets/ + your node.exe
+           ──▶ [2] zip              payload.zip (Optimal deflate)
+           ──▶ [3] icon             app.png → .syso via go-winres (optional)
+           ──▶ [4] go build         Go launcher with go:embed payload + -H windowsgui
+           ──▶ [5] deliver          <output>/<Name>-<version>.exe
+```
+
+The launcher is a tiny Go binary with the whole runtime **embedded** (`go:embed`). On first launch it self-extracts to `%LOCALAPPDATA%\<AppName>\app-<content-hash>\` (with zip-slip protection, atomic rename), then runs your entry JS with the bundled `node.exe`. The hash key means a new build re-extracts automatically, while unchanged builds open instantly.
+
+No Go on the build machine? The packer **falls back** to a portable folder + `run.cmd` — the app still runs, it's just not one file.
+
+## Install
+
+```sh
+npm install --save-dev react-native-flux-desktop-packer
+```
+
+Requirements (build machine): Node.js ≥ 18 on Windows. Optional: [Go](https://go.dev) for the single-exe path, [`go-winres`](https://github.com/tc-hib/go-winres) for a custom exe icon — both degrade gracefully when missing.
+
+## Usage
+
+**1.** Make sure your app has an `app.json` at the project root:
+
+```json
+{
+  "name": "MyApp",
+  "version": "0.1.0",
+  "icon": "assets/icon.png",
+  "main": "dist/App.js",
+  "output": "output"
+}
+```
+
+| Field | Used for |
+|---|---|
+| `name` | window title, exe file name, cache & data directory name (**required**) |
+| `version` | exe file name suffix + Windows version resource |
+| `icon` | PNG embedded as the exe icon (optional; default icon otherwise) |
+| `main` | compiled entry JS; falls back to `package.json`'s `main` |
+| `output` | where the exe lands (default `build`) |
+| `pack` | payload whitelist, default `["dist","node_modules","assets","package.json","app.json"]` |
+
+**2.** Build your app, then pack:
+
+```sh
+npm run build      # your tsc step — produces dist/
+npx flux-pack      # → output/MyApp-0.1.0.exe
+```
+
+CLI flags:
+
+```
+flux-pack                   pack the project in the current directory
+flux-pack --project <dir>   point at another project root
+flux-pack --keep            keep the intermediate .flux-pack/ work dir (debugging)
+```
+
+**Programmatic API:**
+
+```js
+const { pack } = require('react-native-flux-desktop-packer');
+await pack({ projectRoot: __dirname, keep: false });
+```
+
+## What ships in the payload
+
+The stage copies your `dist/`, `node_modules/`, `assets/`, `package.json` and `app.json`, plus the **`node.exe` running the packer** (N-API is ABI-stable across majors, so the bundled node loads your `.node` addon fine). Platform-specific prebuilds that can't run on win32-x64 (darwin/linux canvas binaries, `ffmpeg-static`) are filtered out to keep the exe small.
+
+At runtime the launcher sets `FLUX_PACKAGED=1` and `FLUX_APP_DIR=<AppName>`, so the library routes KV/log data to `%APPDATA%\<AppName>\` — no writable-path issues even when the exe sits in `Program Files`.
+
+## Pre-flight validation
+
+The packer fails fast, before copying anything:
+
+- missing `app.json` or `name` → error with the exact fix
+- entry JS does not exist → "run your build first"
+- entry JS is **older than any source file** (you forgot to recompile) → error naming both files and mtimes — this one has saved more than one release
+
+## Repository layout
+
+```
+bin/flux-pack.js     CLI entry (npx flux-pack)
+lib/                 config reader / icon builder / orchestration
+launcher/            Go launcher source + placeholder payload.zip (go:embed stub)
+test/entry-check.js  smoke test for the entry validator
+```
+
+## Related
+
+- [react-native-flux-desktop](https://www.npmjs.com/package/react-native-flux-desktop) — the desktop rendering stack this packs apps for.
+- [react-native-flux](https://github.com/keyonByIos/react-native-flux) — parent repository.
+
+## License
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,111 @@
+# react-native-flux-desktop-packer（中文）
+
+[English](./README.md) | **简体中文**
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/react-native-flux-desktop-packer"><img src="https://img.shields.io/npm/v/react-native-flux-desktop-packer?style=flat-square&color=cb3837" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/react-native-flux-desktop-packer"><img src="https://img.shields.io/npm/dm/react-native-flux-desktop-packer?style=flat-square" alt="npm downloads"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/platform-win32-lightgrey?style=flat-square" alt="win32 only">
+</p>
+
+把 [react-native-flux-desktop](https://www.npmjs.com/package/react-native-flux-desktop) 应用打包成**单个自包含的 Windows `.exe`**——不用 Electron、不需要安装器、目标机器也不需要装 Node.js。终端用户双击一个文件，直接得到原生窗口。
+
+## 工作原理
+
+```
+app.json ──▶ [1] 组装载        dist/ + node_modules/ + assets/ + 你的 node.exe
+           ──▶ [2] 压缩         payload.zip（Optimal deflate）
+           ──▶ [3] 图标         app.png → .syso（经 go-winres，可选）
+           ──▶ [4] go build     Go 启动器 go:embed 内嵌负载 + -H windowsgui
+           ──▶ [5] 交付         <output>/<Name>-<version>.exe
+```
+
+启动器是一个极小的 Go 二进制，整个运行时**内嵌**其中（`go:embed`）。首次启动时自解压到 `%LOCALAPPDATA%\<AppName>\app-<内容哈希>\`（含 zip-slip 防护、原子 rename），然后用捆绑的 `node.exe` 运行入口 JS。按内容哈希缓存意味着：新版本自动重解压，未变化的构建秒开。
+
+打包机没装 Go？packer 会**自动降级**为「便携文件夹 + run.cmd」——应用照样跑，只是不再是单文件。
+
+## 安装
+
+```sh
+npm install --save-dev react-native-flux-desktop-packer
+```
+
+要求（打包机）：Windows + Node.js ≥ 18。可选：[Go](https://go.dev)（单 exe 路径）、[`go-winres`](https://github.com/tc-hib/go-winres)（自定义 exe 图标）——缺失时都会优雅降级。
+
+## 使用
+
+**1.** 项目根目录准备 `app.json`：
+
+```json
+{
+  "name": "MyApp",
+  "version": "0.1.0",
+  "icon": "assets/icon.png",
+  "main": "dist/App.js",
+  "output": "output"
+}
+```
+
+| 字段 | 用途 |
+|---|---|
+| `name` | 窗口标题、exe 文件名、缓存与数据目录名（**必填**） |
+| `version` | exe 文件名后缀 + Windows 版本资源 |
+| `icon` | 嵌入 exe 的 PNG 图标（可选，缺省用默认图标） |
+| `main` | 编译后的入口 JS；缺省回落 `package.json` 的 `main` |
+| `output` | 产物落地目录（默认 `build`） |
+| `pack` | 负载白名单，默认 `["dist","node_modules","assets","package.json","app.json"]` |
+
+**2.** 先编译应用，再打包：
+
+```sh
+npm run build      # 你的 tsc 步骤——产出 dist/
+npx flux-pack      # → output/MyApp-0.1.0.exe
+```
+
+CLI 参数：
+
+```
+flux-pack                   在当前目录的项目打包（读 app.json）
+flux-pack --project <dir>   指定项目根
+flux-pack --keep            保留中间工作目录 .flux-pack/（调试用）
+```
+
+**编程式 API：**
+
+```js
+const { pack } = require('react-native-flux-desktop-packer');
+await pack({ projectRoot: __dirname, keep: false });
+```
+
+## 负载里装了什么
+
+stage 阶段会拷贝你的 `dist/`、`node_modules/`、`assets/`、`package.json`、`app.json`，外加**正在运行 packer 的那个 `node.exe`**（N-API 跨大版本 ABI 稳定，捆绑的 node 加载你的 `.node` 原生插件没有问题）。win32-x64 上用不到的平台专属预编译包（darwin/linux 的 canvas 二进制、`ffmpeg-static`）会被过滤掉以控制体积。
+
+运行时启动器会注入 `FLUX_PACKAGED=1` 和 `FLUX_APP_DIR=<AppName>`，库会据此把 KV/日志数据路由到 `%APPDATA%\<AppName>\`——exe 放进 `Program Files` 也没有可写路径问题。
+
+## 打包前硬校验
+
+复制动作开始之前，packer 会快速失败：
+
+- 缺 `app.json` 或缺 `name` → 报错并给出修复动作
+- 入口 JS 不存在 → 提示先执行编译
+- 入口 JS 比任何源文件都**旧**（忘了重新编译）→ 报错并列出两个文件与修改时间——这一条救过不止一次发版
+
+## 仓库结构
+
+```
+bin/flux-pack.js     CLI 入口（npx flux-pack）
+lib/                 配置读取 / 图标构建 / 主流程编排
+launcher/            Go 启动器源码 + 占位 payload.zip（满足 go:embed 静态检查）
+test/entry-check.js  入口校验器的冒烟测试
+```
+
+## 相关仓库
+
+- [react-native-flux-desktop](https://www.npmjs.com/package/react-native-flux-desktop) —— 本工具打包的对象：桌面渲染栈。
+- [react-native-flux](https://github.com/keyonByIos/react-native-flux) —— 父仓库。
+
+## 许可证
+
+[MIT](./LICENSE)

package/bin/flux-pack.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// flux-pack —— react-native-flux-desktop 打包 CLI。
+// 用法（在含 app.json 的项目根执行）：
+//   flux-pack                 # 读当前目录 app.json，产 exe 到 app.json.output
+//   flux-pack --project <dir> # 指定项目根
+//   flux-pack --keep          # 保留中间工作目录 .flux-pack（调试用）
+'use strict';
+const path = require('path');
+const { pack } = require('../lib');
+
+function parseArgs(argv) {
+  const opts = { projectRoot: process.cwd(), keep: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--project' || a === '-p') opts.projectRoot = path.resolve(argv[++i] || '.');
+    else if (a === '--keep') opts.keep = true;
+    else if (a === '--help' || a === '-h') opts.help = true;
+  }
+  return opts;
+}
+
+function help() {
+  console.log(
+    [
+      'flux-pack —— 把 react-native-flux-desktop 应用打包成自包含 Windows exe',
+      '',
+      '用法：',
+      '  flux-pack                  在当前项目根打包（读 app.json）',
+      '  flux-pack --project <dir>  指定项目根',
+      '  flux-pack --keep           保留中间目录 .flux-pack',
+      '',
+      'app.json 需含：name / version / icon / output / main（main 缺省回落 package.json.main）',
+    ].join('\n'),
+  );
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    help();
+    return;
+  }
+  try {
+    await pack(opts);
+  } catch (e) {
+    console.error('\n\x1b[31m✘ 打包失败：\x1b[0m' + (e && e.message ? e.message : e));
+    process.exit(1);
+  }
+}
+
+main();

package/launcher/go.mod

@@ -0,0 +1,3 @@
+module fluxpacker-launcher
+
+go 1.27

package/launcher/main.go

@@ -0,0 +1,166 @@
+// 通用自解压启动器（由 react-native-flux-desktop-packer 构建时注入参数）。
+// 把整个运行目录（node.exe + dist + 原生插件 + node_modules）作为 payload.zip 内嵌进本 exe。
+// 双击时解压到 %LOCALAPPDATA%\<AppName>\app-<hash>\（按内容哈希缓存，命中即秒开），
+// 再从缓存目录用 node.exe 跑入口 JS。对外只需这一个 exe，可放任意位置、免装 Node。
+//
+// 构建期经 -ldflags "-X main.Entry=... -X main.AppName=..." 注入：
+//
+//	Entry   缓存根下的相对入口 JS 路径（如 dist\Gallery.js）
+//	AppName 应用名（用于缓存目录 %LOCALAPPDATA%\<AppName>\）
+//	ExeName 出错弹框标题（一般 = 产物 exe 名）
+//
+// GUI 子系统编译（-H windowsgui），HideWindow 隐藏 node 控制台；出错弹框提示。
+package main
+
+import (
+	"archive/zip"
+	"bytes"
+	"crypto/sha256"
+	_ "embed"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"unsafe"
+)
+
+// payload 由构建期 go:embed 注入的 payload.zip（真实负载在 launcher-build 目录，
+// launcher/ 下同名为满足 go:embed 静态检查的占位空 zip，构建时不会被使用）。
+//
+//go:embed payload.zip
+var payload []byte
+
+// 构建期注入的默认值；留空则回落到通用默认。
+var (
+	Entry   = "dist\\main.js"
+	AppName = "Flux"
+	ExeName = "Flux"
+)
+
+var (
+	user32  = syscall.NewLazyDLL("user32.dll")
+	msgBoxW = user32.NewProc("MessageBoxW")
+)
+
+func showFatal(title, msg string) {
+	tp, _ := syscall.UTF16PtrFromString(title)
+	mp, _ := syscall.UTF16PtrFromString(msg)
+	msgBoxW.Call(0, uintptr(unsafe.Pointer(mp)), uintptr(unsafe.Pointer(tp)), 0x10) // MB_ICONERROR
+	os.Exit(1)
+}
+
+// 按内嵌负载哈希定缓存目录，内容变了自动重解
+func cacheDir() (string, error) {
+	base := os.Getenv("LOCALAPPDATA")
+	if base == "" {
+		base = os.Getenv("TEMP")
+	}
+	if base == "" {
+		h, _ := os.UserHomeDir()
+		base = filepath.Join(h, ".cache")
+	}
+	sum := sha256.Sum256(payload)
+	tag := hex.EncodeToString(sum[:])[:12]
+	app := sanitize(AppName)
+	if app == "" {
+		app = "Flux"
+	}
+	return filepath.Join(base, app, "app-"+tag), nil
+}
+
+// 去掉文件系统/注册表不友好的字符，用于目录名
+func sanitize(s string) string {
+	repl := strings.NewReplacer(" ", "-", "/", "-", "\\", "-", ":", "-", "*", "-", "?-", "\"-", "<", "-", ">", "-", "|", "-")
+	return strings.TrimSpace(repl.Replace(s))
+}
+
+// 解压到临时目录再原子 rename，避免半解压损坏；含 zip-slip 防护
+func extractTo(dest string) error {
+	zr, err := zip.NewReader(bytes.NewReader(payload), int64(len(payload)))
+	if err != nil {
+		return err
+	}
+	tmp := dest + ".tmp"
+	_ = os.RemoveAll(tmp)
+	if err := os.MkdirAll(tmp, 0o755); err != nil {
+		return err
+	}
+	prefix := filepath.Clean(tmp) + string(os.PathSeparator)
+	for _, f := range zr.File {
+		target := filepath.Join(tmp, f.Name)
+		if filepath.Clean(target) != filepath.Clean(tmp) && !strings.HasPrefix(filepath.Clean(target), prefix) {
+			return fmt.Errorf("非法压缩包路径: %s", f.Name)
+		}
+		if f.FileInfo().IsDir() {
+			_ = os.MkdirAll(target, 0o755)
+			continue
+		}
+		if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
+			return err
+		}
+		rc, err := f.Open()
+		if err != nil {
+			return err
+		}
+		out, err := os.OpenFile(target, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o755)
+		if err != nil {
+			rc.Close()
+			return err
+		}
+		_, cpErr := io.Copy(out, rc)
+		out.Close()
+		rc.Close()
+		if cpErr != nil {
+			return cpErr
+		}
+	}
+	_ = os.RemoveAll(dest)
+	return os.Rename(tmp, dest)
+}
+
+func main() {
+	if len(payload) == 0 {
+		showFatal(ExeName, "内嵌负载为空（构建未打包 payload.zip）")
+	}
+	dest, err := cacheDir()
+	if err != nil {
+		showFatal(ExeName, "无法确定缓存目录:\n"+err.Error())
+	}
+	ready := filepath.Join(dest, ".ready")
+	if _, err := os.Stat(ready); err != nil {
+		if err := extractTo(dest); err != nil {
+			showFatal(ExeName, "首次解压失败:\n"+err.Error())
+		}
+		_ = os.WriteFile(ready, []byte("ok"), 0o644)
+	}
+
+	node := filepath.Join(dest, "node.exe")
+	entry := filepath.Join(dest, Entry)
+	if _, err := os.Stat(node); err != nil {
+		showFatal(ExeName, "解压后缺少 node.exe:\n"+node)
+	}
+	if _, err := os.Stat(entry); err != nil {
+		showFatal(ExeName, "解压后缺少入口:\n"+entry)
+	}
+
+	args := append([]string{entry}, os.Args[1:]...)
+	cmd := exec.Command(node, args...)
+	cmd.Dir = dest // cwd=缓存根，资源按 process.cwd 相对解析；插件 __dirname 约束天然满足
+	// 关键：置 FLUX_PACKAGED=1，让库的 db.ts dataDir() 走 %APPDATA% 分支，
+	// 而非 dev 分支去写不存在的 src/。再透传 FLUX_APP_DIR=<AppName>（已 sanitize，与缓存目录同源），
+	// 使数据/日志落到按应用隔离的 %APPDATA%\<AppName>\，避免同框架多项目撞车。继承原环境再追加。
+	dataAppName := sanitize(AppName)
+	if dataAppName == "" {
+		dataAppName = "Flux"
+	}
+	cmd.Env = append(os.Environ(), "FLUX_PACKAGED=1", "FLUX_APP_DIR="+dataAppName)
+	cmd.SysProcAttr = &syscall.SysProcAttr{HideWindow: true}
+	if err := cmd.Start(); err != nil {
+		showFatal(ExeName, "启动失败:\n"+err.Error())
+	}
+	_ = cmd.Wait()
+}

package/lib/config.js

@@ -0,0 +1,142 @@
+// config.js —— 读取并规整 app.json（消费方项目根）。缺字段回落内置默认，缺文件直接抛清晰错误。
+// app.json 约定字段：
+//   name        应用名（窗口标题 / exe 文件名 / 缓存目录名）
+//   description 描述（写进 exe 版本资源 FileDescription）
+//   version     版本号（写进 exe 版本资源）
+//   icon        图标 PNG 路径（相对项目根；缺失则 exe 用默认图标，不阻断打包）
+//   output      打包产物目录（相对项目根或绝对；默认 "build"）
+//   main        编译后入口 JS（相对项目根；缺省回落 package.json 的 main）
+const fs = require('fs');
+const path = require('path');
+
+function readJson(p) {
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function loadConfig(projectRoot) {
+  const appJsonPath = path.join(projectRoot, 'app.json');
+  if (!fs.existsSync(appJsonPath)) {
+    throw new Error(`未找到 app.json：${appJsonPath}\n（打包器需要在项目根放一个 app.json，至少含 name 字段）`);
+  }
+  const app = readJson(appJsonPath);
+  if (!app.name || typeof app.name !== 'string') {
+    throw new Error('app.json 缺少必填字段 name（应用名）');
+  }
+
+  // package.json 的 main 作为入口兜底
+  let pkgMain;
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      pkgMain = readJson(pkgPath).main;
+    } catch {
+      /* ignore */
+    }
+  }
+
+  const main = app.main || pkgMain;
+  if (!main || typeof main !== 'string') {
+    throw new Error('无法确定入口 JS：请在 app.json 加 "main"（或在 package.json 写 "main"）');
+  }
+
+  const version = typeof app.version === 'string' ? app.version : '0.0.0';
+  const output = app.output || 'build';
+
+  const cfg = {
+    projectRoot,
+    name: app.name,
+    description: typeof app.description === 'string' ? app.description : app.name,
+    version,
+    icon: typeof app.icon === 'string' ? app.icon : null,
+    outputAbs: path.isAbsolute(output) ? output : path.join(projectRoot, output),
+    outputRel: output,
+    // 归一化入口为平台分隔（Go 里用 dist\\Gallery.js）
+    mainRel: main.split('/').join(path.sep),
+    appJson: app,
+  };
+
+  // 打包前一致性校验（尽早失败，避免装完半个负载才报入口问题）：
+  // 入口产物必须存在且非陈旧——曾踩「app.json 指向历史遗留 dist/Gallery.js，文件在但早于源码，打包成功却跑错/旧产物」。
+  validateEntry(cfg, projectRoot);
+
+  return cfg;
+}
+
+// 入口产物校验：① 存在（不存在=配置错或未编译）；② 非陈旧（产物 mtime 不早于任何源码文件，否则=改了源码没重编）。
+// 二者均为硬错，因为一个旧/错的入口正是本次要拦的事故；报错信息直接给出修复动作（重编 + 校正 main）。
+function validateEntry(cfg, projectRoot) {
+  const entryAbs = path.join(projectRoot, cfg.mainRel);
+  if (!fs.existsSync(entryAbs)) {
+    throw new Error(
+      `入口产物不存在：${cfg.mainRel}\n` +
+        `（app.json/package.json 的 main 指向的文件缺失；请先在项目内编译出产物，例如 npm run build，再确认 main 指向当前入口）`
+    );
+  }
+  if (!fs.statSync(entryAbs).isFile()) {
+    throw new Error(`入口不是一个文件：${cfg.mainRel}`);
+  }
+  const entryMtime = fs.statSync(entryAbs).mtimeMs;
+  const newest = newestSourceMtime(projectRoot);
+  if (newest && newest.mtimeMs > entryMtime) {
+    const rel = path.relative(projectRoot, newest.file);
+    throw new Error(
+      `入口产物疑似陈旧：${cfg.mainRel}（改于 ${new Date(entryMtime).toISOString()}）早于源码 ${rel}（改于 ${new Date(newest.mtimeMs).toISOString()}）。\n` +
+        `（产物没重编译，或 main 指向了历史遗留文件；请先 npm run build 重新产出，再核对 app.json 的 main）`
+    );
+  }
+}
+
+// 扫描项目源码（排除 node_modules/dist/output/.flux-pack 等产物与构建目录），返回修改时间最新的源文件。
+// 只计 .ts/.tsx（本栈为 TS→JS 管线，dist 由它们编译而来）；不计根级 .js 配置（metro/babel 等），
+// 否则打包器自身触碰配置文件会造成假陈旧。
+function newestSourceMtime(projectRoot) {
+  const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'output', 'target', 'release', 'assets', '.git', '.flux-pack']);
+  const SRC_EXT = new Set(['.ts', '.tsx']);
+  let best = null;
+  const walk = (dir) => {
+    let items;
+    try {
+      items = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const it of items) {
+      const abs = path.join(dir, it.name);
+      if (it.isDirectory()) {
+        if (SKIP_DIRS.has(it.name) || it.name.startsWith('.')) continue;
+        walk(abs);
+      } else if (SRC_EXT.has(path.extname(it.name))) {
+        let st;
+        try {
+          st = fs.statSync(abs);
+        } catch {
+          continue;
+        }
+        if (!best || st.mtimeMs > best.mtimeMs) best = { file: abs, mtimeMs: st.mtimeMs };
+      }
+    }
+  };
+  walk(projectRoot);
+  return best;
+}
+
+// 版本号补成 4 段（winres fixed file_version 需 a.b.c.d）
+function fourPart(v) {
+  const parts = String(v)
+    .replace(/^v/, '')
+    .split(/[.\-+]/)
+    .filter((s) => /^\d+$/.test(s))
+    .map((s) => String(parseInt(s, 10) & 0xffff));
+  while (parts.length < 4) parts.push('0');
+  return parts.slice(0, 4).join('.');
+}
+
+// exe / 目录名净化：去非法字符、空格转 '-'
+function safeName(s) {
+  return String(s)
+    .replace(/[<>:"/\\|?*\u0000-\u001f]/g, '')
+    .replace(/\s+/g, '-')
+    .trim();
+}
+
+module.exports = { loadConfig, fourPart, safeName, validateEntry, newestSourceMtime };

package/lib/icon.js

@@ -0,0 +1,88 @@
+// icon.js —— 把 app.json.icon 指的 PNG 编成 exe 资源（.syso）。
+// 流程：@napi-rs/canvas（从消费方 node_modules 解析）缩放多尺寸 → 写 winres/ + winres.json → go-winres make。
+// 任一前置缺失（无图标文件 / 无 canvas / 无 go-winres）都优雅降级返回 null，让打包继续（exe 用默认图标）。
+const fs = require('fs');
+const path = require('path');
+const { ensureDir, which, run, warn, ok } = require('./util');
+const { fourPart } = require('./config');
+
+async function buildIconSyso({ projectRoot, iconRel, outDir, name, version, description }) {
+  if (!iconRel) {
+    warn('app.json 未配置 icon，跳过图标（exe 使用默认图标）');
+    return null;
+  }
+  const iconPath = path.isAbsolute(iconRel) ? iconRel : path.join(projectRoot, iconRel);
+  if (!fs.existsSync(iconPath)) {
+    warn(`图标文件不存在：${iconPath}（跳过图标）`);
+    return null;
+  }
+
+  // 从消费方项目解析 @napi-rs/canvas（packer 自身不依赖它）
+  let canvas;
+  try {
+    const modPath = require.resolve('@napi-rs/canvas', { paths: [projectRoot] });
+    canvas = require(modPath);
+  } catch {
+    warn('消费方未安装 @napi-rs/canvas，无法缩放图标（跳过图标）');
+    return null;
+  }
+
+  const goWinres = which(path.join(process.env.USERPROFILE || '', 'go', 'bin', 'go-winres.exe')) || which('go-winres');
+  if (!goWinres) {
+    warn('未找到 go-winres（go install github.com/tc-hib/go-winres@latest），跳过图标');
+    return null;
+  }
+
+  ensureDir(outDir);
+  const winresDir = path.join(outDir, 'winres');
+  ensureDir(winresDir);
+  const SIZES = [16, 24, 32, 48, 64, 128, 256];
+  const img = await canvas.loadImage(iconPath);
+  const files = [];
+  for (const s of SIZES) {
+    const c = canvas.createCanvas(s, s);
+    const ctx = c.getContext('2d');
+    ctx.imageSmoothingEnabled = true;
+    ctx.imageSmoothingQuality = 'high';
+    ctx.drawImage(img, 0, 0, img.width, img.height, 0, 0, s, s);
+    const fname = `icon-${s}x${s}.png`;
+    fs.writeFileSync(path.join(winresDir, fname), c.toBuffer('image/png'));
+    files.push(fname);
+  }
+
+  const v = fourPart(version);
+  const json = {
+    RT_GROUP_ICON: { APP: { '0000': files } },
+    RT_VERSION: {
+      '#1': {
+        '0000': {
+          fixed: { file_version: v, product_version: v },
+          info: {
+            '0409': {
+              FileDescription: description,
+              ProductName: name,
+              OriginalFilename: name + '.exe',
+              FileVersion: v,
+              ProductVersion: v,
+              InternalName: name,
+            },
+          },
+        },
+      },
+    },
+  };
+  const jsonPath = path.join(winresDir, 'winres.json');
+  fs.writeFileSync(jsonPath, JSON.stringify(json, null, 2));
+
+  // go-winres make → 产出 rsrc_windows_amd64.syso 于 outDir
+  run(goWinres, ['make', '--in', jsonPath, '--out', path.join(outDir, 'rsrc'), '--arch', 'amd64'], { stdio: 'ignore' });
+  const syso = path.join(outDir, 'rsrc_windows_amd64.syso');
+  if (!fs.existsSync(syso)) {
+    warn('go-winres 未产出 .syso（跳过图标）');
+    return null;
+  }
+  ok(`图标已编入资源：${path.basename(syso)}`);
+  return syso;
+}
+
+module.exports = { buildIconSyso };

package/lib/index.js

@@ -0,0 +1,156 @@
+// index.js —— react-native-flux-desktop-packer 主流程（Windows）。
+// 读 app.json → 组装自包含负载（node.exe + dist + node_modules + assets + app.json）→ 压 payload.zip
+// → go-winres 编图标 → go build（go:embed 内嵌负载）产单文件 exe → 落到 app.json.output。
+// 前置：本机 Go（缺则回落「便携文件夹 + .cmd」，仍产可运行 app）；图标需 go-winres（缺则默认图标）。
+const fs = require('fs');
+const path = require('path');
+const { step, ok, warn, rmrf, ensureDir, copyTree, dirSize, fmtMB, which, run } = require('./util');
+const { loadConfig, safeName } = require('./config');
+const { buildIconSyso } = require('./icon');
+
+const PKG_ROOT = path.join(__dirname, '..');
+const LAUNCHER_DIR = path.join(PKG_ROOT, 'launcher');
+
+// node_modules 里剔除：非 win32-x64 的 canvas 预编译包 + 可选大二进制（ffmpeg-static，缺失运行时自动降级）
+function nodeModulesFilter(abs) {
+  const n = abs.split(path.sep).join('/');
+  if (/@napi-rs\/canvas-(darwin|linux)-/.test(n)) return false;
+  if (/\/@napi-rs\/canvas-(android|freebsd|openbsd|wasm32)-/.test(n)) return false;
+  if (/\/ffmpeg-static(\/|$)/.test(n)) return false;
+  return true;
+}
+
+async function pack(options = {}) {
+  const projectRoot = path.resolve(options.projectRoot || process.cwd());
+  const keepWork = !!options.keep;
+  const cfg = loadConfig(projectRoot);
+  const exeBase = safeName(cfg.name) || 'App';
+  // 产物文件名带版本后缀；但注入的 AppName/ExeName 仍用无版本 exeBase（缓存目录稳定、错误框标题干净）
+  const fileBase = `${exeBase}-${safeName(cfg.version)}`;
+
+  console.log('\x1b[1mreact-native-flux-desktop-packer\x1b[0m');
+  console.log(`  项目根：${projectRoot}`);
+  console.log(`  应用名：${cfg.name}   版本：${cfg.version}`);
+  console.log(`  入口　：${cfg.mainRel}`);
+  console.log(`  产物到：${cfg.outputAbs}`);
+
+  const work = path.join(projectRoot, '.flux-pack');
+  const stage = path.join(work, 'stage');
+  const zip = path.join(work, 'payload.zip');
+  const buildDir = path.join(work, 'launcher-build');
+  rmrf(work);
+  ensureDir(stage);
+
+  // ---- 1) 组装载 ----
+  step('[1/5] 组装自包含负载');
+  const include = Array.isArray(cfg.appJson.pack) ? cfg.appJson.pack : ['dist', 'node_modules', 'assets', 'package.json', 'app.json'];
+  for (const item of include) {
+    const src = path.join(projectRoot, item);
+    if (!fs.existsSync(src)) {
+      warn(`跳过（不存在）：${item}`);
+      continue;
+    }
+    const st = fs.lstatSync(src);
+    if (item === 'node_modules') {
+      copyTree(src, path.join(stage, item), (abs) => nodeModulesFilter(abs));
+    } else if (st.isDirectory()) {
+      copyTree(src, path.join(stage, item));
+    } else {
+      ensureDir(path.dirname(path.join(stage, item)));
+      fs.copyFileSync(src, path.join(stage, item));
+    }
+  }
+  // 捆绑当前 node.exe（napi ABI 稳定，跨大版本可加载）
+  fs.copyFileSync(process.execPath, path.join(stage, 'node.exe'));
+  ok(`node.exe 来自：${process.execPath}`);
+
+  // 入口存在性校验（相对 stage 根）
+  const entryInStage = path.join(stage, cfg.mainRel);
+  if (!fs.existsSync(entryInStage)) {
+    rmrf(work);
+    throw new Error(`入口 JS 不存在：${cfg.mainRel}\n（请先在项目里编译出 dist，例如 npm run build）`);
+  }
+  ok(`负载体积：${fmtMB(dirSize(stage))}`);
+
+  // ---- 2) 压 payload.zip ----
+  step('[2/5] 压缩负载 payload.zip');
+  run('powershell', [
+    '-NoProfile',
+    '-ExecutionPolicy', 'Bypass',
+    '-Command',
+    `Add-Type -AssemblyName System.IO.Compression.FileSystem; [System.IO.Compression.ZipFile]::CreateFromDirectory('${stage}','${zip}',[System.IO.Compression.CompressionLevel]::Optimal,$false)`,
+  ], { stdio: 'ignore' });
+  ok(`payload.zip = ${fmtMB(fs.statSync(zip).size)}`);
+
+  // ---- 3) 图标 ----
+  step('[3/5] 生成 exe 图标资源');
+  let syso = null;
+  try {
+    syso = await buildIconSyso({
+      projectRoot,
+      iconRel: cfg.icon,
+      outDir: work,
+      name: cfg.name,
+      version: cfg.version,
+      description: cfg.description,
+    });
+  } catch (e) {
+    warn(`图标处理失败（忽略，用默认图标）：${e.message}`);
+  }
+
+  // ---- 4) go build ----
+  step('[4/5] 编译启动器 exe');
+  const goExe = which('go');
+  ensureDir(cfg.outputAbs);
+  let delivered;
+  if (!goExe) {
+    warn('未检测到 Go，无法产单文件 exe → 回落「便携文件夹 + .cmd」（同样可直接运行）');
+    delivered = emitPortableFolder({ stage, outAbs: cfg.outputAbs, exeBase: fileBase, mainRel: cfg.mainRel });
+  } else {
+    ensureDir(buildDir);
+    fs.copyFileSync(path.join(LAUNCHER_DIR, 'main.go'), path.join(buildDir, 'main.go'));
+    fs.copyFileSync(path.join(LAUNCHER_DIR, 'go.mod'), path.join(buildDir, 'go.mod'));
+    fs.copyFileSync(zip, path.join(buildDir, 'payload.zip'));
+    if (syso) fs.copyFileSync(syso, path.join(buildDir, path.basename(syso)));
+    const outExe = path.join(buildDir, fileBase + '.exe');
+    // 用生成的 .cmd 显式控制引号：go 的 -ldflags 必须是「单个带引号字符串」，
+    // 而 Node 直接 spawn go 会把内层引号拆坏。值均用无空格 ASCII（exeBase / mainRel）。
+    const ld = `-H windowsgui -X main.Entry=${cfg.mainRel} -X main.AppName=${exeBase} -X main.ExeName=${exeBase}`;
+    const cmdFile = path.join(buildDir, 'build-launcher.cmd');
+    const goLine = `"${goExe}" build -trimpath -ldflags "${ld}" -o "${outExe}" .`;
+    fs.writeFileSync(cmdFile, ['@echo off', 'cd /d "' + buildDir + '"', goLine, ''].join('\r\n'), 'utf8');
+    const r = require('child_process').spawnSync('cmd.exe', ['/c', cmdFile], { cwd: buildDir, windowsHide: true, encoding: 'utf8' });
+    if (r.stdout) process.stdout.write(r.stdout);
+    if (r.stderr) process.stderr.write(r.stderr);
+    if (r.status !== 0) throw new Error('go build 失败（见上方输出）');
+    const finalExe = path.join(cfg.outputAbs, fileBase + '.exe');
+    fs.copyFileSync(outExe, finalExe);
+    ok(`exe = ${fmtMB(fs.statSync(finalExe).size)}`);
+    delivered = finalExe;
+  }
+
+  // ---- 5) 收尾 ----
+  step('[5/5] 完成');
+  if (!keepWork) rmrf(work);
+  else warn(`保留工作目录：${work}`);
+  console.log('\n\x1b[32m✔ 打包完成 →\x1b[0m ' + delivered);
+  return { exe: delivered };
+}
+
+// 无 Go 时的回落：把 stage 目录整体搬到 output/<name>/，写 run.cmd（置 FLUX_PACKAGED=1）
+function emitPortableFolder({ stage, outAbs, exeBase, mainRel }) {
+  const dest = path.join(outAbs, exeBase);
+  rmrf(dest);
+  copyTree(stage, dest);
+  const cmd = [
+    '@echo off',
+    'cd /d "%~dp0"',
+    'set FLUX_PACKAGED=1',
+    `"%~dp0node.exe" "%~dp0${mainRel}" %*`,
+    '',
+  ].join('\r\n');
+  fs.writeFileSync(path.join(dest, 'run.cmd'), cmd, 'utf8');
+  return dest;
+}
+
+module.exports = { pack };

package/lib/util.js

@@ -0,0 +1,91 @@
+// util.js —— 打包用的通用小工具：递归拷贝（可过滤）、命令探测、目录体积、日志。
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function log(msg) {
+  console.log(msg);
+}
+function step(msg) {
+  console.log('\n\x1b[36m==> ' + msg + '\x1b[0m');
+}
+function ok(msg) {
+  console.log('\x1b[32m    ' + msg + '\x1b[0m');
+}
+function warn(msg) {
+  console.log('\x1b[33m    ! ' + msg + '\x1b[0m');
+}
+
+function rmrf(p) {
+  fs.rmSync(p, { recursive: true, force: true });
+}
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+// 递归拷贝 src → dest。filter(relAbs, isDir) 返回 false 则跳过该项。
+function copyTree(src, dest, filter) {
+  const st = fs.statSync(src);
+  if (st.isDirectory()) {
+    ensureDir(dest);
+    for (const name of fs.readdirSync(src)) {
+      const s = path.join(src, name);
+      const d = path.join(dest, name);
+      const isDir = fs.lstatSync(s).isDirectory();
+      if (filter && !filter(s, isDir)) continue;
+      copyTree(s, d, filter);
+    }
+  } else if (st.isFile()) {
+    ensureDir(path.dirname(dest));
+    fs.copyFileSync(src, dest);
+  }
+}
+
+// 目录体积（字节）
+function dirSize(p) {
+  let total = 0;
+  try {
+    for (const name of fs.readdirSync(p)) {
+      const s = path.join(p, name);
+      const st = fs.lstatSync(s);
+      if (st.isDirectory()) total += dirSize(s);
+      else if (st.isFile()) total += st.size;
+    }
+  } catch {
+    /* ignore */
+  }
+  return total;
+}
+
+function fmtMB(bytes) {
+  return (bytes / 1024 / 1024).toFixed(1) + ' MB';
+}
+
+// 探测命令是否可用（返回可执行路径或 null）。cmd 可为绝对路径。
+function which(cmd) {
+  if (path.isAbsolute(cmd)) return fs.existsSync(cmd) ? cmd : null;
+  const probe = spawnSync(cmd, ['--version'], { windowsHide: true });
+  if (probe.error || probe.status !== 0) {
+    // 有些工具（go）用 version 而非 --version
+    const probe2 = spawnSync(cmd, ['version'], { windowsHide: true });
+    if (probe2.error || probe2.status !== 0) return null;
+  }
+  // 用 where 定位真实路径
+  const w = spawnSync('where', [cmd], { windowsHide: true });
+  if (!w.error && w.status === 0) {
+    const first = String(w.stdout).split(/\r?\n/).map((s) => s.trim()).filter(Boolean)[0];
+    if (first) return first;
+  }
+  return cmd; // 已知能跑，但拿不到绝对路径
+}
+
+// 运行命令，失败抛错。返回 stdout。
+function run(cmd, args, opts) {
+  const r = spawnSync(cmd, args, Object.assign({ stdio: 'inherit', windowsHide: true }, opts || {}));
+  if (r.error) throw new Error(`执行失败 ${cmd}: ${r.error.message}`);
+  if (r.status !== 0) throw new Error(`${cmd} ${args.join(' ')} 退出码 ${r.status}`);
+  return r;
+}
+
+module.exports = { log, step, ok, warn, rmrf, ensureDir, copyTree, dirSize, fmtMB, which, run };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "react-native-flux-desktop-packer",
+  "version": "0.1.0",
+  "description": "Package a react-native-flux-desktop app into a self-contained Windows .exe (Go launcher + go:embed payload). Install as a devDependency, add `output`/`main` to app.json, then run `flux-pack`.",
+  "license": "MIT",
+  "author": "keyon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keyonByIos/react-native-flux-desktop-packer.git"
+  },
+  "homepage": "https://github.com/keyonByIos/react-native-flux-desktop-packer#readme",
+  "bugs": {
+    "url": "https://github.com/keyonByIos/react-native-flux-desktop-packer/issues"
+  },
+  "private": false,
+  "main": "lib/index.js",
+  "scripts": {
+    "test": "node test/entry-check.js"
+  },
+  "bin": {
+    "flux-pack": "bin/flux-pack.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "launcher"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "win32"
+  ],
+  "keywords": [
+    "react-native-flux-desktop",
+    "packer",
+    "electron-alternative",
+    "windows",
+    "launcher"
+  ]
+}