@public-tauri/raycast-convert 1.0.1 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 将 Raycast 插件转换为 Public Tauri 插件。
 
-当前阶段暂时只支持 Raycast `no-view` 命令；Raycast view 插件的适配正在进行中。
+转换器支持 Raycast `no-view` 与 **view（MVP）** 命令：`no-view` 走 Node Worker + 浏览器 `public-main`；`view` 在 Worker 内用 React reconciler 执行组件，通过 snapshot 协议由 wujie 加载 **`@public-tauri/template`** 中的 **`raycast.html`** 入口（Vue 渲染；构建产物拷贝到插件 **`dist/view/`**）。
 
 仓库根目录提供了以下脚本：
 
@@ -17,33 +17,51 @@ pnpm raycast:convert:production <raycast-plugin-dir> --out <public-plugin-dir> [
 raycast-convert <raycast-plugin-dir> --out <public-plugin-dir> [--build] [--mode development|production]
 ```
 
+## 关键步骤（转换逻辑）
+
+转换器按固定顺序处理，核心步骤如下：
+
+1. **准备输出目录**  
+   删除目标 `outDir`（若存在），保证输出是一次干净的生成结果。
+
+2. **复制 Raycast 源码树**  
+   将输入插件目录下的文件与子目录**递归复制**到 `outDir`。  
+   **不复制** `package.json`（由下一步生成）。  
+   为便于在 `outDir` 内重新解析依赖，同时**跳过** `node_modules` 以及常见 lockfile（`pnpm-lock.yaml`、`package-lock.json`、`yarn.lock`）。  
+   其它文件（含 `src/`、`assets/`、`tsconfig.json` 等）原样保留。
+
+3. **生成 Public 插件清单与打包入口**  
+   - 写入 **`package.json`**：`publicPlugin` manifest、`@public-tauri/api` 依赖、合并后的 `dependencies` / `devDependencies`（仅移除 **`@raycast/api`**；**`@raycast/utils`** 若存在则保留原声明）、以及 `build` 脚本等。  
+   - 存在 **no-view** 命令时写入 **`.raycast-build/public-main.ts`**（浏览器侧 `raycast:run` 桥接）。  
+   - 写入 **`.raycast-build/server.ts`**（Node / Worker 侧入口：`raycast:run` 与 `raycast:view:*`）。  
+   - 存在 **view** 命令时写入 `.raycast-build/raycast-view-protocol.ts`、Worker 侧 **`raycast-worker-runtime.ts`**（及宿主序列化等）。**`development`**（CLI 默认）：`publicPlugin.html` 为 **`http://localhost:5173/raycast.html`**，指向本仓库 **`@public-tauri/template`** 的 Vite 开发服务器，**不**拷贝 `dist/view`，便于先执行 `pnpm --filter @public-tauri/template dev` 再打开 `/raycast.html` 调试 view。**`production`**（或 `pnpm raycast:convert:production`）：将 **`packages/template` 的 `dist/`** 复制到插件 **`dist/view/`**，`publicPlugin.html` 为 **`./dist/view/raycast.html`**。浏览器逻辑（wujie、`channel`、Markdown）均在模板应用 bundle 内；插件侧 **tsdown 只打 `server.js`**（及可选 **`public-main.js`**）。依赖侧为 Worker 补充 **`react`** / **`react-reconciler`**。  
+   - 写入 **`tsdown.config.ts`**：no-view 时的 browser 入口 + **node（server）入口**，产出写入 **`dist/`**（与 **`dist/view/`** 并列）。  
+   - 写入 **`raycast-conversion-report.json`**：已转换命令、跳过命令与 warnings。
+
+4. **安装依赖并打包（可选）**  
+   若传入 `--build`，在 **`outDir`** 内依次执行：  
+   `pnpm install` → `pnpm exec tsdown --config tsdown.config.ts` → **再次将 `packages/template` 的构建产物拷入 `dist/view/`**（tsdown 会清空 `dist/`）。
+
+原始 Raycast 插件目录不会被修改；依赖安装与构建仅在生成的 `outDir` 中进行。
+
 ## 功能
 
 转换器读取一个 Raycast 插件目录，并生成一个 Public Tauri 插件目录。
 
+转换后 `package.json` 的 `name` 固定为 `@public-tauri-raycast/<slug>`（由 Raycast 包名或输入目录名推导），与 Public 应用商店中已发布的包名空间区分。`raycast-conversion-report.json` 中记录 `sourcePackageName`（源 `package.json` 的 `name`，可能缺失）与 `convertedPackageName`。
+
 生成的插件包含：
 
-- `package.json`，包含 `publicPlugin` manifest。
-- `.raycast-build/public-main.ts`，浏览器侧桥接入口。
-- `.raycast-build/server.ts`，Node 侧命令运行入口。
+- `package.json`，包含 `publicPlugin` manifest（含 `server`；有 no-view 时有 `main`；有 view 时有 `html` 指向 **`dist/view/raycast.html`**）。
+- `.raycast-build/server.ts`，Node / Worker 命令与 view session 入口。
+- 有 no-view 命令时：`.raycast-build/public-main.ts`。
+- 有 view 命令时：**`dist/view/`**（完整 Vite 子应用）及 `.raycast-build` 内 Worker runtime / protocol 等源码。
 - `tsdown.config.ts`，用于打包转换后的插件。
 - `raycast-conversion-report.json`，记录已转换命令、跳过命令和 warnings。
-- `assets/`，当 Raycast 插件存在资源目录时会复制过来。
+- 自 Raycast 插件目录复制的其余源码与资源（不含上述跳过项）。
 
 如果传入 `--build`，转换器会在生成的 Public Tauri 插件目录中安装依赖，并执行 `tsdown` 构建。
 
-## 转换流程
-
-```text
-Raycast 插件源码
--> 生成 Public Tauri 插件文件
--> 写入 package.json 和 tsdown.config.ts
--> 在生成的插件目录执行 pnpm install
--> pnpm exec tsdown --config tsdown.config.ts
-```
-
-原始 Raycast 插件源码目录不会被安装依赖，也不会被修改。
-
 ## 模式
 
 ### development
@@ -74,31 +92,36 @@ Raycast 插件源码
 
 ## Raycast API 映射
 
-生成的 `tsdown.config.ts` 会将 Raycast API 映射到 Public Tauri 的兼容层：
+- **Node（server）入口**（no-view 与 view 相同）：将 **`@raycast/api`** 解析到已安装的 **`@public-tauri/api/src/raycast.ts`**（与包导出 **`@public-tauri/api/raycast`** 同源）。**`@raycast/utils`** 不配置别名，仍使用 `package.json` 中的 npm 包。**浏览器（public-main）入口** 不使用 `@raycast/api` 别名。  
+- **含 view 命令**：**`server.ts`** 会引入 **`.raycast-build/raycast-worker-runtime.ts`**，其中提供 **`createRaycastViewSession`** / **`__setRaycastViewContext`**：在 Worker 内挂 **React reconciler**，把业务组件树打成 snapshot，经 `channel` 交给 wujie 里 **`@public-tauri/template`** 的 **`raycast.html`**（`dist/view/raycast.html`）用 Vue 渲染。业务代码仍只从 **`@raycast/api`** 导入 `List`、`Detail`、`Action` 等与 API，与 no-view 一致。
 
-```ts
-alias: {
-  '@raycast/api': '@public-tauri/api/raycast',
-  '@raycast/utils': '@public-tauri/api/raycast/utils',
-}
-```
-
-原 Raycast 插件中的其它依赖会保留。
+原 Raycast 插件中除 **`@raycast/api`**（由 `@public-tauri/api` + 上述别名替代）外的其它依赖会保留在生成的 `package.json` 中。
 
 ## 当前支持范围
 
-目前暂时只转换以下类型的 Raycast 命令：
+转换器支持：
 
-```json
-{
-  "mode": "no-view"
-}
-```
+- Raycast `mode: "no-view"`：转换为 Public Tauri 命令 `mode: "none"`，由 Node Worker 执行默认导出函数。
+- Raycast `mode: "view"`（未写 `mode` 时 Raycast 默认为 view）：转换为 Public Tauri `mode: "view"`，React 组件在 Worker 内执行，snapshot 由 wujie 加载的 **`packages/template`**（`raycast.html`）子应用以 Vue 渲染。
+
+**MVP 已支持：**
+
+- `List`、`List.Item`、`Detail`、`ActionPanel`、`Action`
+- Raycast command `arguments`（`text` / `password` / `dropdown`）参数表单前置并透传至 `LaunchProps.arguments`
+- `Detail.markdown` 在浏览器侧由 **`packages/template`** 产物内的 `markdown-it` 渲染为 HTML（禁用 raw HTML）
+- React 函数组件、`useState`、`useEffect`
+- Worker 侧 action 回调与 snapshot 更新
+- `CopyToClipboard`、`Paste`、`OpenInBrowser`、`ShowInFinder`、`Action.Pop`（`Action.Push` 会抛出明确错误）
+
+**暂不支持：**
+
+- `Grid`、`Form`、`MenuBarExtra`
+- OAuth / BrowserExtension
+- 依赖完整 Raycast runtime 的复杂 `@raycast/utils` hooks
 
-其它 command mode 会被跳过，并写入 `raycast-conversion-report.json`。这不是该包的长期边界，Raycast view 插件的适配正在进行中。
+其它 command mode（如 `menuBar`）会被跳过并记入 `raycast-conversion-report.json`。
 
 ## 限制
 
-- 暂时不转换 Raycast React UI 命令。
-- 命令入口文件需要符合常见 Raycast 布局，例如 `src/<command>.ts`、`src/<command>.tsx` 或 `src/<command>/index.ts`。
-- 运行时能力取决于 `@public-tauri/api/raycast` 提供的兼容层。
+- 命令入口文件需符合常见 Raycast 布局，例如 `src/<command>.ts`、`src/<command>.tsx` 或 `src/<command>/index.ts`。
+- Worker 侧兼容能力仍受 `@public-tauri/api/raycast` 与上述 MVP 组件集合约束。

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as convertRaycastPlugin } from "./src-DPoXoCnp.mjs";
+import { n as convertRaycastPlugin } from "./src-Re0YIJP-.mjs";
 import path from "node:path";
 import { parseArgs } from "node:util";
 //#region src/cli.ts
@@ -36,8 +36,7 @@ const runCli = async () => {
 		inputDir: path.resolve(inputArg),
 		outputDir: values.out,
 		build: values.build,
-		mode: getConvertMode(values.mode),
-		invocationDir: process.cwd()
+		mode: getConvertMode(values.mode)
 	});
 	console.log(`Converted ${report.convertedCommands.length} command(s) to ${report.output}`);
 	if (report.skippedCommands.length) console.log(`Skipped ${report.skippedCommands.length} command(s). See raycast-conversion-report.json`);

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { t as convertRaycastPlugin } from "./src-DPoXoCnp.mjs";
-export { convertRaycastPlugin };
+import { a as resolveRaycastSlug, i as resolveConvertedPackageName, n as convertRaycastPlugin, o as sanitizeSlug, r as RAYCAST_CONVERTED_SCOPE, t as RAYCAST_VIEW_TEMPLATE_DEV_ENTRY } from "./src-Re0YIJP-.mjs";
+export { RAYCAST_CONVERTED_SCOPE, RAYCAST_VIEW_TEMPLATE_DEV_ENTRY, convertRaycastPlugin, resolveConvertedPackageName, resolveRaycastSlug, sanitizeSlug };