@dimina/desktop-sdk 0.0.0-stage → 1.9.0-beta.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (C) 2017 Beijing Didi Infinity Technology and Development Co.,Ltd. All rights reserved.
+
+   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.

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @dimina/desktop-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+供 Node.js / Electron 主进程和 Tauri 前端调用的 Dimina 独立窗口容器 SDK。Node/Electron 入口零 npm 运行时依赖，使用配套的桌面运行时；不会自动下载或安装运行时。
+
+```js
+import { Dimina } from '@dimina/desktop-sdk'
+
+const desktop = await Dimina.start({ runtimePath, packagesDir, dataDir })
+const window = await desktop.openApp({ appId: 'your-app-id', name: '我的小程序' })
+await window.focus()
+await window.close()
+await desktop.dispose()
+```
+
+三个目录/文件路径都必须是绝对路径。`runtimePath` 在 macOS 指向完整 `.app` 内的可执行文件；Windows 指向配套 `.exe`；Linux 指向配套可执行文件。`packagesDir` 包含按 appId 命名的 Dimina 编译产物目录，`dataDir` 由当前产品独占。
+
+还提供 `windows()`、`closeAll()`、`importApp(absolutePath)`。重复打开同 appId 会复用已有窗口；首次打开可传 `path` 指定入口。客户端退出时等待 `dispose()`，不要把 SDK 实例暴露给 renderer 或小程序。
+
+主进程可用 `await desktop.registerApi(name, handler, { appIds, timeoutMs })` 注册原生能力，为移动 SDK 已有 API 提供桌面原生实现。处理器接收 `(params, { appId, windowId, signal })`，返回 JSON 对象或 Promise；异步操作可使用 `signal` 参与取消。
+
+完整构建、平台依赖和分发说明见仓库 `desktop/sdk/README.md`。
+
+Tauri 2 前端使用 `import { Dimina } from '@dimina/desktop-sdk/tauri'`，注册配套 Rust 插件和权限后调用 `await Dimina.start()`。运行时路径由 Rust 宿主配置，完整接入步骤见 `desktop/sdk/tauri/README.md`。
+
+源码开发时运行 `pnpm test` 需要 Node.js 22+ 和 Go 1.27.3+，测试会编译跨平台的原生进程夹具；Go 可通过 `GO_BIN` 指定。CI 使用 `DIMINA_TEST_RUNTIME` 指向预编译夹具。业务集成不需要安装这些测试工具。

package/index.d.ts

@@ -0,0 +1,21 @@
+export interface DesktopOptions {
+  runtimePath: string
+  packagesDir: string
+  dataDir: string
+  startupTimeoutMs?: number
+  onLog?: (message: string) => void
+}
+import type { OpenAppOptions, ImportedApp, DiminaWindow, NativeApiHandler, NativeApiOptions } from './types.js'
+export * from './types.js'
+export declare class Dimina {
+  private constructor()
+  static start(options: DesktopOptions): Promise<Dimina>
+  registerApi(name: string, handler: NativeApiHandler, options?: NativeApiOptions): Promise<void>
+  openApp(options: OpenAppOptions): Promise<DiminaWindow>
+  focus(id: string): Promise<void>
+  closeApp(id: string): Promise<void>
+  closeAll(): Promise<void>
+  windows(): Promise<DiminaWindow[]>
+  importApp(path: string): Promise<ImportedApp>
+  dispose(): Promise<void>
+}

package/index.js

@@ -0,0 +1,158 @@
+import { spawn } from 'node:child_process'
+import { createInterface } from 'node:readline'
+import { isAbsolute } from 'node:path'
+
+import { DiminaWindow } from './window.js'
+export { DiminaWindow } from './window.js'
+
+/** Call from Node.js or Electron's main process, never expose the host to a renderer. */
+export class Dimina {
+  #process
+  #base
+  #token
+  #stopped = false
+  #exit
+  #disposal
+  #apis = new Map()
+  #calls = new Map()
+
+  static async start(options) {
+    for (const name of ['runtimePath', 'packagesDir', 'dataDir']) {
+      if (!isAbsolute(options[name] || '')) throw new Error(`${name} must be an absolute path`)
+    }
+    const child = spawn(options.runtimePath, ['--sdk-host', '--packages-dir', options.packagesDir, '--data-dir', options.dataDir], {
+      stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true,
+    })
+    const host = new Dimina()
+    host.#process = child
+    child.stdin.on('error', () => {})
+    host.#exit = new Promise(resolve => child.once('exit', resolve))
+    child.once('exit', () => {
+      host.#stopped = true
+      for (const controller of host.#calls.values()) controller.abort()
+      host.#calls.clear()
+    })
+    let diagnostics = ''
+    child.stderr.on('data', bytes => {
+      diagnostics = (diagnostics + bytes).slice(-4096)
+      try { options.onLog?.(String(bytes)) } catch { /* Logging is an optional host hook. */ }
+    })
+    const lines = createInterface({ input: child.stdout })
+    try {
+      const hello = await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('Dimina runtime startup timed out')), options.startupTimeoutMs ?? 30000)
+        const error = value => { clearTimeout(timer); reject(value) }
+        child.once('error', error)
+        child.once('exit', code => error(new Error(`Dimina runtime exited (${code}): ${diagnostics}`)))
+        lines.once('line', line => {
+          clearTimeout(timer)
+          try { resolve(JSON.parse(line)) } catch { reject(new Error('Invalid Dimina runtime handshake')) }
+        })
+      })
+      const base = new URL(hello.baseUrl)
+      if (hello.protocol !== 1 || base.protocol !== 'http:' || base.hostname !== '127.0.0.1'
+        || !base.pathname.endsWith('/sdk/control/') || !/^[a-f0-9]{48}$/.test(hello.token)) {
+        throw new Error('Unsupported Dimina runtime handshake')
+      }
+      host.#base = base
+      host.#token = hello.token
+      lines.on('line', line => {
+        try { host.#native(JSON.parse(line)) } catch { /* Ignore non-protocol output. */ }
+      })
+      child.once('exit', () => lines.close())
+      return host
+    } catch (error) {
+      child.stdin.end()
+      child.kill('SIGKILL')
+      lines.close()
+      child.stdout.resume()
+      throw error
+    }
+  }
+
+  #native(message) {
+    if (message.type === 'native-cancel') {
+      this.#calls.get(message.id)?.abort()
+      this.#calls.delete(message.id)
+      return
+    }
+    if (message.type !== 'native-call' || this.#stopped) return
+    const controller = new AbortController()
+    this.#calls.set(message.id, controller)
+    const context = { appId: message.appId, windowId: message.windowId, signal: controller.signal }
+    const respond = response => {
+      if (!controller.signal.aborted && !this.#stopped) {
+        let encoded = JSON.stringify({ type: 'native-result', id: message.id, ...response })
+        if (Buffer.byteLength(encoded) > 1 << 20) encoded = JSON.stringify({ type: 'native-result', id: message.id, error: 'Native API result exceeds 1 MiB' })
+        this.#process.stdin.write(encoded + '\n')
+      }
+    }
+    Promise.resolve().then(() => {
+      if (controller.signal.aborted || this.#stopped) return
+      const handler = this.#apis.get(message.name)
+      if (!handler) throw new Error('Native API handler is unavailable')
+      return handler(message.params, context)
+    }).then(value => {
+      if (value != null && (typeof value !== 'object' || Array.isArray(value))) throw new Error('Native API must return a JSON object')
+      respond({ value: value ?? {} })
+    }).catch(error => {
+      try { respond({ error: error?.message || String(error) }) } catch { /* The host may already be exiting. */ }
+    }).finally(() => this.#calls.delete(message.id))
+  }
+
+  async registerApi(name, handler, options = {}) {
+    if (typeof handler !== 'function') throw new TypeError('Native API handler must be a function')
+    const previous = this.#apis.get(name)
+    this.#apis.set(name, handler)
+    try { await this.#call('registerApi', { name, appIds: options.appIds, timeoutMs: options.timeoutMs }) }
+    catch (error) {
+      if (this.#apis.get(name) === handler) {
+        if (previous) this.#apis.set(name, previous)
+        else this.#apis.delete(name)
+      }
+      throw error
+    }
+  }
+
+  async #call(method, payload, verb = 'POST') {
+    if (this.#stopped || this.#disposal) throw new Error('Dimina runtime is stopped')
+    return this.#request(method, payload, verb)
+  }
+
+  async #request(method, payload, verb = 'POST', signal = AbortSignal.timeout(100000)) {
+    const response = await fetch(new URL(method, this.#base), {
+      method: verb,
+      headers: { Authorization: `Bearer ${this.#token}`, 'Content-Type': 'application/json' },
+      body: verb === 'GET' ? undefined : JSON.stringify(payload ?? {}),
+      signal,
+    })
+    let result
+    try { result = await response.json() } catch { throw new Error(`Invalid runtime response (HTTP ${response.status})`) }
+    if (!response.ok || result.error) throw new Error(result.error || `Runtime HTTP ${response.status}`)
+    return result.value
+  }
+
+  async openApp(options) { return new DiminaWindow(this, await this.#call('open', options)) }
+  focus(id) { return this.#call('focus', { id }) }
+  closeApp(id) { return this.#call('close', { id }) }
+  closeAll() { return this.#call('closeAll') }
+  async windows() { return (await this.#call('windows', undefined, 'GET')).map(info => new DiminaWindow(this, info)) }
+  importApp(path) { return this.#call('import', { path }) }
+
+  dispose() {
+    return this.#disposal ??= this.#disposeRuntime()
+  }
+  async #disposeRuntime() {
+    if (this.#stopped) return
+    try { await this.#request('closeAll', undefined, 'POST', AbortSignal.timeout(3000)) } finally {
+      this.#stopped = true
+      for (const controller of this.#calls.values()) controller.abort()
+      this.#calls.clear()
+      this.#process.stdin.end()
+      const timer = setTimeout(() => this.#process.kill('SIGKILL'), 3000)
+      try { await this.#exit } finally { clearTimeout(timer) }
+    }
+  }
+  async [Symbol.asyncDispose]() { await this.dispose() }
+}
+

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@dimina/desktop-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.9.0-beta.1",
+  "license": "Apache-2.0",
+  "description": "Standalone Dimina mini-program windows for Node.js, Electron and Tauri hosts",
+  "homepage": "https://github.com/didi/dimina/tree/main/desktop/sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/didi/dimina.git",
+    "directory": "desktop/sdk/node"
+  },
+  "bugs": {
+    "url": "https://github.com/didi/dimina/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./tauri": {
+      "types": "./tauri.d.ts",
+      "default": "./tauri.js"
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "*.js",
+    "*.d.ts",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@tauri-apps/api": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tauri-apps/api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tauri-apps/api": "^2.0.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "typecheck": "tsc --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 test/types.ts"
+  }
+}

package/tauri.d.ts

@@ -0,0 +1,14 @@
+import type { OpenAppOptions, ImportedApp, DiminaWindow } from './types.js'
+export * from './types.js'
+/** One runtime is shared by the trusted frontend windows of a Tauri app. */
+export declare class Dimina {
+  private constructor()
+  static start(): Promise<Dimina>
+  openApp(options: OpenAppOptions): Promise<DiminaWindow>
+  focus(id: string): Promise<void>
+  closeApp(id: string): Promise<void>
+  closeAll(): Promise<void>
+  windows(): Promise<DiminaWindow[]>
+  importApp(path: string): Promise<ImportedApp>
+  dispose(): Promise<void>
+}

package/tauri.js

@@ -0,0 +1,28 @@
+import { invoke } from '@tauri-apps/api/core'
+import { DiminaWindow } from './window.js'
+export { DiminaWindow } from './window.js'
+
+/** Uses the runtime configured by the host's tauri-plugin-dimina instance. */
+export class Dimina {
+  #stopped = false
+
+  static async start() {
+    await invoke('plugin:dimina|start')
+    return new Dimina()
+  }
+  #call(method, args) {
+    if (this.#stopped) return Promise.reject(new Error('Dimina runtime is stopped'))
+    return invoke(`plugin:dimina|${method}`, args)
+  }
+  async openApp(options) { return new DiminaWindow(this, await this.#call('open', { options })) }
+  focus(id) { return this.#call('focus', { id }) }
+  closeApp(id) { return this.#call('close', { id }) }
+  closeAll() { return this.#call('close_all') }
+  async windows() { return (await this.#call('windows')).map(info => new DiminaWindow(this, info)) }
+  importApp(path) { return this.#call('import', { path }) }
+  async dispose() {
+    if (this.#stopped) return
+    await this.#call('dispose')
+    this.#stopped = true
+  }
+}

package/types.d.ts

@@ -0,0 +1,14 @@
+export interface OpenAppOptions { appId: string; path?: string; name?: string }
+export interface ImportedApp { appId: string; name: string; path: string; imported: boolean }
+export interface NativeApiOptions { appIds?: string[]; timeoutMs?: number }
+export interface NativeApiContext { appId: string; windowId: string; signal: AbortSignal }
+export type NativeApiHandler = (params: Record<string, unknown>, context: NativeApiContext) => Record<string, unknown> | void | Promise<Record<string, unknown> | void>
+export declare class DiminaWindow {
+  private constructor()
+  readonly id: string
+  readonly appId: string
+  readonly name: string
+  readonly ready: boolean
+  focus(): Promise<void>
+  close(): Promise<void>
+}

package/window.js

@@ -0,0 +1,11 @@
+export class DiminaWindow {
+  constructor(host, info) {
+    this.host = host
+    this.id = info.id
+    this.appId = info.appId
+    this.name = info.name
+    this.ready = info.ready
+  }
+  focus() { return this.host.focus(this.id) }
+  close() { return this.host.closeApp(this.id) }
+}