@yufengtadian/freedom-cli 1.0.0

package/templates/go/gen_config.go

@@ -0,0 +1,19 @@
+package main
+
+import "freedom-cli-shell/pkg/freedom"
+
+// appConfig 返回应用窗口配置。
+// 本文件由 freedom CLI 在 build 阶段根据 freedom.config.js 重新生成，
+// 不要手动修改（手动修改会在下次 build 时被覆盖）。
+func appConfig() freedom.Config {
+	return freedom.Config{
+		Title:     "Freedom App",
+		TitleBar:  freedom.TitleBarNative,
+		Width:     1024,
+		Height:    720,
+		MinWidth:  400,
+		MinHeight: 300,
+		Center:    true,
+		Debug:     false,
+	}
+}

package/templates/go/go.mod

@@ -0,0 +1,5 @@
+module freedom-cli-shell
+
+go 1.22
+
+require github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6

package/templates/go/main.go

@@ -0,0 +1,12 @@
+package main
+
+import "freedom-cli-shell/pkg/freedom"
+
+// main 是 Freedom 壳层应用入口。
+// 窗口与标题栏配置来自 build 阶段生成的 gen_config.go（appConfig），
+// 前端页面由 pkg/freedom 的 assets_embed.go 嵌入（build 阶段把打包后的 index.html 放进去）。
+func main() {
+	cfg := appConfig()
+	app := freedom.New(cfg)
+	app.Run()
+}

package/templates/go/pkg/freedom/assets/freedom.js

@@ -0,0 +1,97 @@
+// Freedom 前端 SDK。
+// window.__freedom_bridge 由 go-webview2 的 Bind 机制注册（异步桥接函数，返回 Promise），
+// 注入脚本与 SDK 的执行先后顺序不固定，因此 SDK 采用"每次调用时动态读取"策略，
+// 保证与注入顺序无关。
+(function () {
+  'use strict';
+
+  function getBridge() {
+    return (typeof window.__freedom_bridge === 'function') ? window.__freedom_bridge : null;
+  }
+
+  var listeners = {};
+
+  function call(method) {
+    var params = Array.prototype.slice.call(arguments, 1);
+    var bridge = getBridge();
+    if (!bridge) {
+      return Promise.reject(new Error('[freedom] 未检测到原生桥接（__freedom_bridge），当前不在桌面壳内运行。'));
+    }
+    return bridge(method, JSON.stringify(params));
+  }
+
+  function on(event, cb) {
+    if (typeof cb !== 'function') return function () {};
+    (listeners[event] = listeners[event] || []).push(cb);
+    return function () { off(event, cb); };
+  }
+
+  function off(event, cb) {
+    var l = listeners[event] || [];
+    var i = l.indexOf(cb);
+    if (i >= 0) l.splice(i, 1);
+  }
+
+  // 后端通过 app.Emit(event, data) 触发（Eval 调用本函数）。
+  function emit(event, data) {
+    var l = listeners[event] || [];
+    for (var i = 0; i < l.length; i++) {
+      try { l[i](data); } catch (e) { /* 监听器异常不影响其余监听器 */ }
+    }
+  }
+
+  var freedom = {
+    call: call,
+    invoke: call,
+    on: on,
+    off: off,
+    emit: emit,
+    window: {
+      // 窗口控制（无边框/隐藏标题栏模式下前端自绘按钮使用）。
+      // 全部经桥接调用原生实现，返回 Promise。
+      minimize: function () { return windowAction('minimize'); },
+      maximize: function () { return windowAction('maximize'); },
+      unmaximize: function () { return windowAction('unmaximize'); },
+      toggleMaximize: function () { return windowAction('toggleMaximize'); },
+      close: function () { return windowAction('close'); },
+      isMaximized: function () { return windowAction('isMaximized'); },
+      isFrameless: function () { return windowAction('isFrameless'); },
+    },
+  };
+
+  // 前端自绘按钮的便捷绑定：把按钮 DOM 接到窗口控制。
+  // freedom.window.bindButtons({ min: '#minBtn', max: '#maxBtn', close: '#closeBtn' })
+  freedom.window.bindButtons = function (sel) {
+    var q = function (s) { return typeof s === 'string' ? document.querySelector(s) : s; };
+    var min = q(sel && sel.min), max = q(sel && sel.max), close = q(sel && sel.close);
+    var self = this;
+    if (min) min.addEventListener('click', function () { self.minimize(); });
+    if (max) max.addEventListener('click', function () {
+      self.isMaximized().then(function (m) {
+        if (m) self.unmaximize(); else self.maximize();
+      });
+    });
+    if (close) close.addEventListener('click', function () { self.close(); });
+  };
+
+  function windowAction(action) {
+    // __freedom_window 是 webview_go Bind 注入的异步全局函数（返回 Promise）
+    if (typeof window.__freedom_window !== 'function') {
+      return Promise.reject(new Error('[freedom] 未检测到原生窗口控制桥接。'));
+    }
+    return window.__freedom_window(action);
+  }
+
+  Object.defineProperty(freedom, 'isDesktop', {
+    get: function () { return !!getBridge(); },
+  });
+
+  // 兼容 Wails 风格：window.go 对象，便于迁移既有代码。
+  var go = {};
+  Object.defineProperty(go, 'backend', {
+    get: function () { return { call: call, invoke: call }; },
+  });
+  window.go = go;
+
+  window.freedom = freedom;
+})();

package/templates/go/pkg/freedom/assets_embed.go

@@ -0,0 +1,18 @@
+package freedom
+
+import _ "embed"
+
+// jsSDK 是注入到每个前端页面的 Freedom 前端 SDK，暴露 window.freedom 全局对象。
+// 用法见 assets/freedom.js 顶部注释。
+//
+//go:embed assets/freedom.js
+var jsSDK string
+
+// indexHTML 是前端打包产物（Vite 单文件 HTML），build 阶段写入 assets/index.html，
+// 运行时通过 SetHtml 从内存加载。
+//
+//go:embed assets/index.html
+var indexHTML string
+
+// defaultHTML 兼容框架默认占位页语义：无自定义前端时回退到 indexHTML。
+var defaultHTML = indexHTML

package/templates/go/pkg/freedom/backend.go

@@ -0,0 +1,21 @@
+package freedom
+
+import "encoding/json"
+
+// Backend 是 Freedom 的后端抽象。一个 Freedom 应用在任意时刻绑定一个后端，
+// 前端的所有 window.freedom.call(...) 最终都路由到该后端的 Handle。
+//
+// Freedom 内置两种后端实现：
+//   - EmbedBackend：Go 方法直接注册在壳进程内（传统模式，app.Bind 使用）。
+//   - ProcBackend：后端是任意语言实现的独立进程，通过 stdio NDJSON/JSON-RPC
+//     与壳通信。这是"后端任意语言 + 三平台"的核心能力。
+type Backend interface {
+	// Handle 处理一次前端调用。method 是方法名，params 是参数列表的 JSON 编码
+	// 数组（每个元素是一个 json.RawMessage）。
+	// 返回值 result 会经 JSON 序列化后回传前端 Promise 的 resolve；
+	// 返回非 nil error 时前端 Promise 走 reject。
+	Handle(method string, params []json.RawMessage) (interface{}, error)
+
+	// Close 释放后端资源（内嵌后端为空操作；进程后端会终止子进程）。
+	Close() error
+}

package/templates/go/pkg/freedom/backend_proc.go

@@ -0,0 +1,250 @@
+package freedom
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"sync"
+	"time"
+)
+
+// ProcBackend 使用任意语言实现的独立后端进程。
+//
+// 通信协议（语言无关，换行分隔 JSON / NDJSON，走 stdin/stdout）：
+//
+//	壳 -> 后端（写 stdin）：
+//	    {"id":1,"method":"Greet","params":["老板"]}
+//	后端 -> 壳（写 stdout）：
+//	    {"id":1,"result":{...}}         调用成功响应（result 可为任意 JSON 或 null）
+//	    {"id":1,"error":"boom"}         调用失败响应
+//	    {"event":"tick","data":{...}}   主动事件推送（无 id 字段）
+//
+// 后端的 stderr 仅用于人类日志，壳原样转发到控制台，不参与协议。
+//
+// 壳启动后端进程时注入环境变量：FREEDOM_BACKEND=1、FREEDOM_IPC=stdio，
+// 后端可据此判断自己运行在 Freedom 壳内。
+type ProcBackend struct {
+	cmd     *exec.Cmd
+	stdin   io.WriteCloser
+	mu      sync.Mutex
+	pending map[int64]chan procResp
+	nextID  int64
+	closed  bool
+	onEvent func(event string, data interface{})
+	timeout time.Duration
+}
+
+// procResp 是一次调用在壳侧的等待结果。
+type procResp struct {
+	result json.RawMessage
+	err    error
+}
+
+// procMessage 是协议的统一消息结构。
+type procMessage struct {
+	ID     int64           `json:"id,omitempty"`
+	Method string          `json:"method,omitempty"`
+	Params json.RawMessage `json:"params,omitempty"`
+	Event  string          `json:"event,omitempty"`
+	Data   json.RawMessage `json:"data,omitempty"`
+	Result json.RawMessage `json:"result,omitempty"`
+	Error  string          `json:"error,omitempty"`
+}
+
+// NewProcBackend 创建一个进程后端。command 是任意语言后端可执行文件的启动命令
+// （如 "node"、"python"、"./backend.py" 或可执行文件绝对路径），后续参数原样透传。
+// 返回的 ProcBackend 在 App.Run 启动窗口时自动拉起后端进程。
+func NewProcBackend(command ...string) *ProcBackend {
+	if len(command) == 0 {
+		panic("freedom: NewProcBackend requires at least one command argument")
+	}
+	cmd := exec.Command(command[0], command[1:]...)
+	hideWindow(cmd) // Windows 下隐藏后端的 cmd 黑窗（跨平台空实现）
+	return &ProcBackend{
+		cmd:     cmd,
+		pending: map[int64]chan procResp{},
+		timeout: 60 * time.Second,
+	}
+}
+
+// SetTimeout 设置单次调用的最大等待时间（默认 60s）。<=0 表示不超时。
+func (p *ProcBackend) SetTimeout(d time.Duration) *ProcBackend {
+	p.timeout = d
+	return p
+}
+
+// OnEvent 注册后端进程推送事件时的回调（由框架在 Run 时注入）。
+func (p *ProcBackend) OnEvent(fn func(event string, data interface{})) {
+	p.mu.Lock()
+	p.onEvent = fn
+	p.mu.Unlock()
+}
+
+// start 启动后端进程并开始读取其 stdout。幂等，可从任意 goroutine 调用。
+func (p *ProcBackend) start() error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	if p.stdin != nil {
+		return nil // 已启动
+	}
+	p.cmd.Env = append(os.Environ(), "FREEDOM_BACKEND=1", "FREEDOM_IPC=stdio")
+	p.cmd.Stderr = os.Stderr // 后端 stderr 日志原样转发
+	stdin, err := p.cmd.StdinPipe()
+	if err != nil {
+		return fmt.Errorf("freedom: proc backend stdin pipe: %w", err)
+	}
+	stdout, err := p.cmd.StdoutPipe()
+	if err != nil {
+		return fmt.Errorf("freedom: proc backend stdout pipe: %w", err)
+	}
+	if err := p.cmd.Start(); err != nil {
+		return fmt.Errorf("freedom: proc backend start %q: %w", p.cmd.Path, err)
+	}
+	p.stdin = stdin
+	go p.readLoop(stdout)
+	return nil
+}
+
+// Handle 实现 Backend 接口：把一次前端调用转发给后端进程并等待其响应。
+func (p *ProcBackend) Handle(method string, params []json.RawMessage) (interface{}, error) {
+	paramsJSON, err := json.Marshal(params)
+	if err != nil {
+		return nil, fmt.Errorf("freedom: proc backend: marshal params: %w", err)
+	}
+
+	p.mu.Lock()
+	if p.closed || p.stdin == nil {
+		p.mu.Unlock()
+		return nil, fmt.Errorf("freedom: proc backend is not running")
+	}
+	p.nextID++
+	id := p.nextID
+	ch := make(chan procResp, 1)
+	p.pending[id] = ch
+	msg := procMessage{ID: id, Method: method, Params: paramsJSON}
+	line, _ := json.Marshal(msg)
+	_, err = p.stdin.Write(append(line, '\n'))
+	p.mu.Unlock()
+
+	if err != nil {
+		p.cancel(id, fmt.Errorf("freedom: proc backend write: %w", err))
+		return nil, err
+	}
+
+	var resp procResp
+	if p.timeout > 0 {
+		select {
+		case resp = <-ch:
+		case <-time.After(p.timeout):
+			p.cancel(id, fmt.Errorf("freedom: proc backend: method %q timed out after %s", method, p.timeout))
+			return nil, fmt.Errorf("freedom: proc backend: method %q timed out after %s", method, p.timeout)
+		}
+	} else {
+		resp = <-ch
+	}
+	if resp.err != nil {
+		return nil, resp.err
+	}
+	if resp.result == nil {
+		return nil, nil
+	}
+	var out interface{}
+	if err := json.Unmarshal(resp.result, &out); err != nil {
+		return nil, fmt.Errorf("freedom: proc backend: bad result: %w", err)
+	}
+	return out, nil
+}
+
+// cancel 移除并唤醒一个等待中的调用（超时 / 写失败 / 进程退出）。
+func (p *ProcBackend) cancel(id int64, err error) {
+	p.mu.Lock()
+	if ch, ok := p.pending[id]; ok {
+		delete(p.pending, id)
+		ch <- procResp{err: err}
+	}
+	p.mu.Unlock()
+}
+
+// readLoop 持续读取后端 stdout，解析协议消息并分发。
+func (p *ProcBackend) readLoop(stdout io.Reader) {
+	sc := bufio.NewScanner(stdout)
+	sc.Buffer(make([]byte, 0, 64*1024), 16*1024*1024)
+	for sc.Scan() {
+		var msg procMessage
+		if err := json.Unmarshal(sc.Bytes(), &msg); err != nil {
+			fmt.Fprintf(os.Stderr, "freedom: proc backend: bad message: %v\n", err)
+			continue
+		}
+		if msg.Event != "" {
+			p.dispatchEvent(msg.Event, msg.Data)
+			continue
+		}
+		p.finish(msg)
+	}
+	// 后端进程已退出：唤醒所有仍等待中的调用。
+	err := fmt.Errorf("freedom: proc backend exited unexpectedly")
+	p.mu.Lock()
+	for id, ch := range p.pending {
+		delete(p.pending, id)
+		ch <- procResp{err: err}
+	}
+	p.mu.Unlock()
+}
+
+func (p *ProcBackend) finish(msg procMessage) {
+	p.mu.Lock()
+	ch, ok := p.pending[msg.ID]
+	delete(p.pending, msg.ID)
+	p.mu.Unlock()
+	if !ok {
+		return
+	}
+	if msg.Error != "" {
+		ch <- procResp{err: fmt.Errorf("%s", msg.Error)}
+		return
+	}
+	ch <- procResp{result: msg.Result}
+}
+
+func (p *ProcBackend) dispatchEvent(event string, dataJSON json.RawMessage) {
+	var data interface{}
+	if len(dataJSON) > 0 {
+		_ = json.Unmarshal(dataJSON, &data)
+	}
+	p.mu.Lock()
+	fn := p.onEvent
+	p.mu.Unlock()
+	if fn != nil {
+		fn(event, data)
+	}
+}
+
+// Close 终止后端进程。先关闭 stdin 通知其优雅退出，超时则强杀。线程安全。
+func (p *ProcBackend) Close() error {
+	p.mu.Lock()
+	if p.closed {
+		p.mu.Unlock()
+		return nil
+	}
+	p.closed = true
+	cmd := p.cmd
+	if p.stdin != nil {
+		_ = p.stdin.Close() // stdin EOF，后端可自行退出
+	}
+	p.mu.Unlock()
+
+	done := make(chan struct{})
+	go func() { _ = cmd.Wait(); close(done) }()
+	select {
+	case <-done:
+	case <-time.After(3 * time.Second):
+		if cmd.Process != nil {
+			_ = cmd.Process.Kill()
+			<-done
+		}
+	}
+	return nil
+}

package/templates/go/pkg/freedom/bridge.go

@@ -0,0 +1,129 @@
+package freedom
+
+import (
+	"encoding/json"
+	"fmt"
+	"reflect"
+	"sync"
+)
+
+var errorType = reflect.TypeOf((*error)(nil)).Elem()
+
+// EmbedBackend 是把 Go 方法集合直接注册在壳进程内的后端（传统模式）。
+// 前端调用 window.freedom.call(name, ...args) 时，桥接层按方法签名反射调用。
+type EmbedBackend struct {
+	methods map[string]reflect.Value
+	mu      sync.RWMutex
+}
+
+// NewEmbedBackend 创建一个内嵌 Go 后端。
+func NewEmbedBackend() *EmbedBackend {
+	return &EmbedBackend{methods: map[string]reflect.Value{}}
+}
+
+// Bind 把后端 Go 方法暴露给前端。
+//
+//   - fn 必须是函数。
+//   - 参数与返回值通过 JSON 编解码，前端用 window.freedom.call(name, ...args) 调用，
+//     返回 Promise（resolve 为返回值，reject 为 error 的字符串表示）。
+//   - 返回值约定：可返回 (T, error) 或仅 (T) 或仅 error 或空。
+func (b *EmbedBackend) Bind(name string, fn interface{}) error {
+	v := reflect.ValueOf(fn)
+	if v.Kind() != reflect.Func {
+		return fmt.Errorf("freedom: Bind(%q): only functions can be bound", name)
+	}
+	if n := v.Type().NumOut(); n > 2 {
+		return fmt.Errorf("freedom: Bind(%q): function may return at most a value and an error", name)
+	}
+	b.mu.Lock()
+	b.methods[name] = v
+	b.mu.Unlock()
+	return nil
+}
+
+// Unbind 移除先前 Bind 的方法。
+func (b *EmbedBackend) Unbind(name string) {
+	b.mu.Lock()
+	delete(b.methods, name)
+	b.mu.Unlock()
+}
+
+// Handle 实现 Backend 接口：按方法名反射调用已绑定的 Go 函数。
+func (b *EmbedBackend) Handle(method string, params []json.RawMessage) (interface{}, error) {
+	b.mu.RLock()
+	fn, ok := b.methods[method]
+	b.mu.RUnlock()
+	if !ok {
+		return nil, fmt.Errorf("freedom: method %q is not bound", method)
+	}
+	return callFunction(fn, params)
+}
+
+// Close 内嵌后端没有需要释放的资源。
+func (b *EmbedBackend) Close() error { return nil }
+
+// callFunction 反射调用一个已绑定的 Go 函数。
+// 返回值约定：0 个（忽略）、1 个（值或 error）、2 个（值, error）。
+func callFunction(fn reflect.Value, params []json.RawMessage) (interface{}, error) {
+	t := fn.Type()
+
+	if t.IsVariadic() {
+		fixed := t.NumIn() - 1
+		if len(params) < fixed {
+			return nil, fmt.Errorf("freedom: arg count mismatch: want >=%d got %d", fixed, len(params))
+		}
+		args := make([]reflect.Value, len(params))
+		for i, p := range params {
+			var typ reflect.Type
+			if i < fixed {
+				typ = t.In(i)
+			} else {
+				typ = t.In(fixed).Elem()
+			}
+			ptr := reflect.New(typ)
+			if err := json.Unmarshal(p, ptr.Interface()); err != nil {
+				return nil, fmt.Errorf("freedom: arg %d: %w", i, err)
+			}
+			args[i] = ptr.Elem()
+		}
+		return collectResults(fn.Call(args))
+	}
+
+	if len(params) != t.NumIn() {
+		return nil, fmt.Errorf("freedom: arg count mismatch: want %d got %d", t.NumIn(), len(params))
+	}
+	args := make([]reflect.Value, len(params))
+	for i, p := range params {
+		ptr := reflect.New(t.In(i))
+		if err := json.Unmarshal(p, ptr.Interface()); err != nil {
+			return nil, fmt.Errorf("freedom: arg %d: %w", i, err)
+		}
+		args[i] = ptr.Elem()
+	}
+	return collectResults(fn.Call(args))
+}
+
+func collectResults(res []reflect.Value) (interface{}, error) {
+	switch len(res) {
+	case 0:
+		return nil, nil
+	case 1:
+		if res[0].Type().Implements(errorType) {
+			if !res[0].IsNil() {
+				return nil, res[0].Interface().(error)
+			}
+			return nil, nil
+		}
+		return res[0].Interface(), nil
+	case 2:
+		if !res[1].Type().Implements(errorType) {
+			return nil, fmt.Errorf("freedom: second return value must be error")
+		}
+		if !res[1].IsNil() {
+			return res[0].Interface(), res[1].Interface().(error)
+		}
+		return res[0].Interface(), nil
+	default:
+		return nil, fmt.Errorf("freedom: function may return at most a value and an error")
+	}
+}

package/templates/go/pkg/freedom/center_other.go

@@ -0,0 +1,7 @@
+//go:build !windows
+
+package freedom
+
+// applyCenter 在 macOS / Linux 下保持空实现：窗口初始位置由窗口管理器决定，
+// 如需精确居中可在目标平台扩展（macOS 用 NSWindow center，Linux 用 Gtk 定位）。
+func (a *App) applyCenter() {}

package/templates/go/pkg/freedom/center_windows.go

@@ -0,0 +1,42 @@
+//go:build windows
+
+package freedom
+
+import (
+	"syscall"
+	"unsafe"
+)
+
+var (
+	user32           = syscall.NewLazyDLL("user32.dll")
+	getSystemMetrics = user32.NewProc("GetSystemMetrics")
+	moveWindow       = user32.NewProc("MoveWindow")
+)
+
+const (
+	smCxScreen = 16
+	smCyScreen = 17
+)
+
+// applyCenter 在 Windows 上把窗口置于屏幕中央（需在 SetSize 之后调用）。
+// webview_go 未提供 SetPosition，这里通过原生 HWND + MoveWindow 定位。
+func (a *App) applyCenter() {
+	if !a.cfg.Center || a.view == nil {
+		return
+	}
+	hwnd := uintptr(unsafe.Pointer(a.view.Window()))
+	if hwnd == 0 {
+		return
+	}
+	sw, _, _ := getSystemMetrics.Call(smCxScreen)
+	sh, _, _ := getSystemMetrics.Call(smCyScreen)
+	x := int(sw/2) - a.cfg.Width/2
+	y := int(sh/2) - a.cfg.Height/2
+	if x < 0 {
+		x = 0
+	}
+	if y < 0 {
+		y = 0
+	}
+	moveWindow.Call(hwnd, uintptr(x), uintptr(y), uintptr(a.cfg.Width), uintptr(a.cfg.Height), 1)
+}