@public-tauri/raycast-convert 1.0.1 → 1.1.0

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@public-tauri/raycast-convert",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Convert Raycast extensions into Public Tauri plugins.",
   "type": "module",
   "files": [
     "dist",
     "src",
+    "templates",
+    "tsconfig.json",
     "README.md",
     "package.json"
   ],
@@ -22,8 +24,10 @@
   },
   "devDependencies": {
     "@types/node": "^24.1.0",
+    "@types/react": "^19.2.14",
+    "@types/react-reconciler": "^0.33.0",
     "eslint": "^9.32.0",
-    "tsdown": "^0.21.7",
+    "tsdown": "^0.22.1",
     "typescript": "~5.9.2"
   },
   "publishConfig": {
@@ -33,6 +37,7 @@
   "scripts": {
     "build": "tsdown",
     "convert": "tsx src/cli.ts",
-    "lint": "eslint src"
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   }
 }

package/src/cli.ts

@@ -46,7 +46,6 @@ export const runCli = async () => {
     outputDir: values.out,
     build: values.build,
     mode: getConvertMode(values.mode),
-    invocationDir: process.cwd(),
   });
 
   console.log(`Converted ${report.convertedCommands.length} command(s) to ${report.output}`);

package/src/commands.ts

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { exists } from './files';
-import type { ConvertedCommand, RaycastCommand } from './types';
+import type { ConvertedCommand, RaycastCommand, RaycastCommandArgument } from './types';
 
 const findCommandEntry = async (inputDir: string, command: RaycastCommand) => {
   const candidates = [
@@ -19,26 +19,75 @@ const findCommandEntry = async (inputDir: string, command: RaycastCommand) => {
   return null;
 };
 
-export const resolveNoViewCommands = async (inputDir: string, sourceCommands: RaycastCommand[]) => {
+const SUPPORTED_COMMAND_MODES = new Set(['no-view', 'view']);
+const SUPPORTED_COMMAND_ARGUMENT_TYPES = new Set(['text', 'password', 'dropdown']);
+
+const isObject = (value: unknown): value is Record<string, unknown> => (
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+);
+
+const validateCommandArguments = (command: RaycastCommand): string | null => {
+  const args = command.arguments;
+  if (!args) return null;
+  if (!Array.isArray(args)) return 'arguments must be an array';
+  if (args.length > 3) return 'arguments length exceeds Raycast limit (3)';
+
+  for (const item of args) {
+    const arg = item as RaycastCommandArgument;
+    if (!isObject(arg)) return 'argument item must be an object';
+    if (!arg.name || typeof arg.name !== 'string') return 'argument.name is required';
+    if (!arg.type || typeof arg.type !== 'string' || !SUPPORTED_COMMAND_ARGUMENT_TYPES.has(arg.type)) {
+      return `argument "${arg.name}" has unsupported type: ${String(arg.type)}`;
+    }
+    if (arg.required !== undefined && typeof arg.required !== 'boolean') {
+      return `argument "${arg.name}" has invalid required field`;
+    }
+    if (arg.placeholder !== undefined && typeof arg.placeholder !== 'string') {
+      return `argument "${arg.name}" has invalid placeholder field`;
+    }
+    if (arg.type === 'dropdown') {
+      if (!Array.isArray(arg.data) || arg.data.length === 0) {
+        return `dropdown argument "${arg.name}" requires non-empty data`;
+      }
+      for (const option of arg.data) {
+        if (!isObject(option) || typeof option.value !== 'string') {
+          return `dropdown argument "${arg.name}" has invalid option value`;
+        }
+      }
+    }
+  }
+  return null;
+};
+
+export const resolveSupportedCommands = async (inputDir: string, sourceCommands: RaycastCommand[]) => {
   const convertedCommands: ConvertedCommand[] = [];
   const skippedCommands: { name: string, reason: string }[] = [];
 
   for (const command of sourceCommands) {
-    if (command.mode !== 'no-view') {
+    const mode = command.mode || 'view';
+    if (!SUPPORTED_COMMAND_MODES.has(mode)) {
       skippedCommands.push({ name: command.name, reason: `Unsupported mode: ${command.mode || '<empty>'}` });
       continue;
     }
+    const argumentErr = validateCommandArguments(command);
+    if (argumentErr) {
+      skippedCommands.push({ name: command.name, reason: `Invalid arguments: ${argumentErr}` });
+      continue;
+    }
     const entry = await findCommandEntry(inputDir, command);
     if (!entry) {
       skippedCommands.push({ name: command.name, reason: 'Command entry not found under src/' });
       continue;
     }
-    convertedCommands.push({ ...command, entry });
+    convertedCommands.push({ ...command, mode: mode as ConvertedCommand['mode'], entry });
   }
 
   if (!convertedCommands.length) {
-    throw new Error('No Raycast no-view commands were converted');
+    throw new Error('No supported Raycast commands were converted');
   }
 
   return { convertedCommands, skippedCommands };
 };
+
+/** @deprecated Use {@link resolveSupportedCommands} */
+export const resolveNoViewCommands = resolveSupportedCommands;

package/src/files.ts

@@ -17,8 +17,30 @@ export const exists = async (filePath: string) => {
   }
 };
 
-export const copyAssetsDir = async (inputDir: string, assetsDir: string) => {
-  const source = path.join(inputDir, 'assets');
-  if (!await exists(source)) return;
-  await fs.cp(source, assetsDir, { recursive: true });
+/** Names skipped when mirroring the Raycast plugin into outDir (see README). */
+export const PLUGIN_COPY_SKIP_NAMES = new Set([
+  'package.json',
+  'node_modules',
+  'pnpm-lock.yaml',
+  'package-lock.json',
+  'yarn.lock',
+]);
+
+/**
+ * Recursively copy the Raycast plugin directory into `outputDir`, except entries in `skipNames`.
+ * Source `package.json` is never copied; generated `package.json` is written separately.
+ */
+export const copyPluginSourceToOutput = async (
+  inputDir: string,
+  outputDir: string,
+  skipNames: ReadonlySet<string> = PLUGIN_COPY_SKIP_NAMES,
+) => {
+  await fs.mkdir(outputDir, { recursive: true });
+  const entries = await fs.readdir(inputDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (skipNames.has(entry.name)) continue;
+    const from = path.join(inputDir, entry.name);
+    const to = path.join(outputDir, entry.name);
+    await fs.cp(from, to, { recursive: true });
+  }
 };

package/src/generate/copy-templates.ts

@@ -0,0 +1,88 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const templateDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '../../templates');
+
+const workerViewRelPaths = [
+  'json-patch.ts',
+  'raycast-view-protocol.ts',
+  'raycast-worker-runtime.ts',
+  'host-instance.ts',
+  'virtual-serialize.ts',
+] as const;
+
+function copyTemplateFile(relativePath: string, buildDir: string) {
+  const dest = path.join(buildDir, relativePath);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(path.join(templateDir, relativePath), dest);
+}
+
+/** 自 startDir 向上查找 monorepo 根（与 options.ts 一致） */
+export function findPublicTauriRepoRoot(startDir: string): string | null {
+  let dir = path.resolve(startDir);
+  const { root } = path.parse(dir);
+  while (dir !== root) {
+    const ws = path.join(dir, 'pnpm-workspace.yaml');
+    const apiPkg = path.join(dir, 'packages', 'api', 'package.json');
+    if (fs.existsSync(ws) && fs.existsSync(apiPkg)) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function getTemplateRaycastViewDistDir(repoRoot: string): string {
+  return path.join(repoRoot, 'packages/template/dist');
+}
+
+/** 若尚未 build，则在 repo 根执行 `pnpm --filter @public-tauri/template build` */
+export function ensureRaycastViewTemplateBuilt(repoRoot: string): void {
+  const marker = path.join(getTemplateRaycastViewDistDir(repoRoot), 'raycast.html');
+  if (fs.existsSync(marker)) {
+    return;
+  }
+  const result = spawnSync(
+    'pnpm',
+    ['--filter', '@public-tauri/template', 'run', 'build'],
+    {
+      cwd: repoRoot,
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+    },
+  );
+  if (result.status !== 0) {
+    throw new Error(
+      'Building @public-tauri/template failed. From the repo root run: pnpm --filter @public-tauri/template build',
+    );
+  }
+}
+
+/**
+ * 将 `packages/template` 的 Vite 应用产物复制到插件 `dist/view/`（与 `dist/server.js` 并列）。
+ * wujie `publicPlugin.html` 指向 `./dist/view/raycast.html`。
+ */
+export function copyRaycastViewTemplateAppDist(repoRoot: string, pluginDistDir: string): void {
+  const srcDir = getTemplateRaycastViewDistDir(repoRoot);
+  const marker = path.join(srcDir, 'raycast.html');
+  if (!fs.existsSync(marker)) {
+    throw new Error(`Missing ${marker}; build @public-tauri/template first.`);
+  }
+  const destDir = path.join(pluginDistDir, 'view');
+  fs.rmSync(destDir, { recursive: true, force: true });
+  fs.cpSync(srcDir, destDir, { recursive: true });
+}
+
+/** 将 Worker 侧 view 模板（reconciler + 宿主类型 + 序列化 + 组件）复制到 `.raycast-build` */
+export function copyRaycastWorkerViewBundle(buildDir: string) {
+  for (const rel of workerViewRelPaths) {
+    copyTemplateFile(rel, buildDir);
+  }
+}
+
+/** @deprecated 使用 {@link copyRaycastWorkerViewBundle}；保留签名以兼容旧调用（按 dest 所在目录复制整套 Worker 模板） */
+export const copyRaycastWorkerRuntimeTemplate = (destAbsolutePath: string) => {
+  copyRaycastWorkerViewBundle(path.dirname(destAbsolutePath));
+};

package/src/generate/server-module.ts

@@ -1,50 +1,59 @@
+import path from 'node:path';
 import type { ConvertedCommand } from '../types';
 
-const toImportName = (index: number) => `command${index}`;
+const commandEntryImportSpecifier = (
+  inputDir: string,
+  outputDir: string,
+  buildDir: string,
+  entry: string,
+) => {
+  const outputEntry = path.join(outputDir, path.relative(path.resolve(inputDir), path.resolve(entry)));
+  let rel = path.relative(path.resolve(buildDir), outputEntry);
+  rel = rel.split(path.sep).join('/');
+  if (rel && !rel.startsWith('.') && !rel.startsWith('/')) {
+    return `./${rel}`;
+  }
+  return rel;
+};
 
 export const generateServerModule = (
-  commands: ConvertedCommand[],
+  commands: { noView: ConvertedCommand[]; view: ConvertedCommand[] },
   packageName: string,
   publicCommands: Record<string, unknown>[],
+  layout: { inputDir: string, outputDir: string, buildDir: string },
 ) => {
-  const imports = commands.map((command, index) => `import * as ${toImportName(index)} from ${JSON.stringify(command.entry)};`).join('\n');
-  const commandMapEntries = commands.map((command, index) => `  ${JSON.stringify(command.name)}: ${toImportName(index)},`).join('\n');
-  const commandManifests = JSON.stringify(publicCommands, null, 2);
-  return `import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { channel } from '@public-tauri/api/node';
-import { __setRaycastContext } from '@public-tauri/api/raycast';
+  const nvLoaders = commands.noView.map(command => `  ${JSON.stringify(command.name)}: () => import(${JSON.stringify(commandEntryImportSpecifier(layout.inputDir, layout.outputDir, layout.buildDir, command.entry))}),`).join('\n');
+  const vvLoaders = commands.view.map(command => `  ${JSON.stringify(command.name)}: () => import(${JSON.stringify(commandEntryImportSpecifier(layout.inputDir, layout.outputDir, layout.buildDir, command.entry))}),`).join('\n');
 
-${imports}
+  const commandManifests = JSON.stringify(publicCommands, null, 2);
 
-const commandModules: Record<string, any> = {
-${commandMapEntries}
-};
+  const viewRuntimeImport = commands.view.length
+    ? 'import { createRaycastViewSession, __setRaycastViewContext } from \'./raycast-worker-runtime\';'
+    : '';
 
-const distDir = path.dirname(fileURLToPath(import.meta.url));
-const pluginRoot = path.dirname(distDir);
-const commandManifests = ${commandManifests};
-
-channel.handle('raycast:run', async (payload = {}) => {
+  const raycastRunHandler = commands.noView.length
+    ? `channel.handle('raycast:run', async (payload = {}) => {
   const commandName = String(payload.commandName || '');
-  const commandModule = commandModules[commandName];
-  if (!commandModule) {
+  const loadCommandModule = commandModuleLoaders[commandName];
+  if (!loadCommandModule) {
     throw new Error(\`Unknown Raycast command: \${commandName}\`);
   }
-  const run = commandModule.default;
-  if (typeof run !== 'function') {
-    throw new Error(\`Raycast command \${commandName} has no default function export\`);
-  }
   const launchPayload = payload.options?.payload || {};
   __setRaycastContext({
     pluginName: ${JSON.stringify(packageName)},
     commandName,
+    commandMode: 'no-view',
     commands: commandManifests,
     launchType: launchPayload.launchType,
     preferences: payload.preferences || {},
     supportPath: path.join(pluginRoot, '.raycast-compat'),
     assetsPath: path.join(pluginRoot, 'assets'),
   });
+  const commandModule = await loadCommandModule();
+  const run = commandModule.default;
+  if (typeof run !== 'function') {
+    throw new Error(\`Raycast command \${commandName} has no default function export\`);
+  }
   return await run({
     arguments: launchPayload.arguments || {},
     fallbackText: launchPayload.fallbackText ?? payload.query ?? '',
@@ -52,5 +61,104 @@ channel.handle('raycast:run', async (payload = {}) => {
     launchType: launchPayload.launchType || 'userInitiated',
   });
 });
+`
+    : '';
+
+  const viewHandlers = commands.view.length
+    ? `const viewSessions = new Map();
+
+channel.handle('raycast:view:mount', async (payload = {}) => {
+  const commandName = String(payload.commandName || '');
+  const existingSession = viewSessions.get(commandName);
+  if (existingSession) {
+    existingSession.unmount();
+    viewSessions.delete(commandName);
+  }
+  const loadViewCommandModule = viewCommandModuleLoaders[commandName];
+  if (!loadViewCommandModule) {
+    throw new Error(\`Unknown Raycast view command: \${commandName}\`);
+  }
+  __setRaycastViewContext({
+    pluginName: ${JSON.stringify(packageName)},
+    commandName,
+    preferences: payload.preferences || {},
+    supportPath: path.join(pluginRoot, '.raycast-compat'),
+    assetsPath: path.join(pluginRoot, 'assets'),
+    launchProps: {
+      arguments: payload.options?.payload?.arguments || {},
+      fallbackText: payload.options?.payload?.fallbackText ?? payload.query ?? '',
+      launchContext: payload.options?.payload?.context ?? payload,
+      launchType: payload.options?.payload?.launchType || 'userInitiated',
+    },
+  });
+  const commandModule = await loadViewCommandModule();
+  const Command = commandModule.default;
+  if (typeof Command !== 'function') {
+    throw new Error(\`Raycast view command \${commandName} has no default function export\`);
+  }
+
+  const session = createRaycastViewSession({
+    emitSnapshot: (snapshot) => channel.emit('raycast:view:snapshot', snapshot),
+    emitPatch: (patches) => channel.emit('raycast:view:patch', patches),
+  });
+  viewSessions.set(commandName, session);
+  await session.mount(Command);
+  return true;
+});
+
+channel.handle('raycast:view:run-action', async (payload = {}) => {
+  const session = viewSessions.get(String(payload.commandName || ''));
+  if (!session) throw new Error(\`No Raycast view session for \${String(payload.commandName || '')}\`);
+  const rawArgs = payload.args;
+  const args = Array.isArray(rawArgs) ? rawArgs : [];
+  await session.dispatchHostEvent(String(payload.hostId || ''), String(payload.event || 'onAction'), args);
+  return true;
+});
+
+channel.handle('raycast:view:unmount', async (payload = {}) => {
+  const commandName = String(payload.commandName || '');
+  const session = viewSessions.get(commandName);
+  if (session) {
+    session.unmount();
+    viewSessions.delete(commandName);
+  }
+  // 无活跃 view 会话时退出 Worker，配合宿主按需加载下次再拉起线程
+  if (viewSessions.size === 0) {
+    queueMicrotask(() => process.exit(0));
+  }
+  return true;
+});
+`
+    : '';
+
+  const nvMapBlock = commands.noView.length
+    ? `const commandModuleLoaders: Record<string, () => Promise<any>> = {
+${nvLoaders}
+};
+`
+    : 'const commandModuleLoaders: Record<string, () => Promise<any>> = {};';
+
+  const vvMapBlock = commands.view.length
+    ? `const viewCommandModuleLoaders: Record<string, () => Promise<any>> = {
+${vvLoaders}
+};
+`
+    : 'const viewCommandModuleLoaders: Record<string, () => Promise<any>> = {};';
+
+  return `import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { channel } from '@public-tauri/api/node';
+import { __setRaycastContext } from '@public-tauri/api/raycast';
+${viewRuntimeImport}
+
+${nvMapBlock}
+${vvMapBlock}
+
+const distDir = path.dirname(fileURLToPath(import.meta.url));
+const pluginRoot = path.dirname(distDir);
+const commandManifests = ${commandManifests};
+
+${raycastRunHandler}
+${viewHandlers}
 `;
 };

package/src/generate/tsdown-config.ts

@@ -10,13 +10,23 @@ const formatAliasProperty = (aliases: Record<string, string>) => {
   return entries ? `    alias: {\n${entries}\n    },` : '    alias: {},';
 };
 
-const getServerAliases = (): Record<string, string> => ({
-  '@raycast/api': '@public-tauri/api/raycast',
-  '@raycast/utils': '@public-tauri/api/raycast/utils',
-});
+/** Server 入口：`@raycast/api` → `@public-tauri/api/raycast` 源码；view 与 no-view 一致。 */
+const getServerAliases = (outputDir: string): Record<string, string> => {
+  const apiSrc = path.join(outputDir, 'node_modules', '@public-tauri', 'api', 'src');
+  return {
+    '@raycast/api': path.join(apiSrc, 'raycast.ts'),
+    '@public-tauri/api/node': path.join(apiSrc, 'node.ts'),
+  };
+};
+
+export const generateTsdownConfig = (
+  options: ResolvedConvertOptions,
+  flags: { hasPublicMain: boolean },
+) => {
+  const entries: string[] = [];
 
-export const generateTsdownConfig = (options: ResolvedConvertOptions) => `export default [
-  {
+  if (flags.hasPublicMain) {
+    entries.push(`  {
     entry: ${JSON.stringify(path.join(options.buildDir, 'public-main.ts'))},
     format: 'esm',
     platform: 'browser',
@@ -27,8 +37,10 @@ export const generateTsdownConfig = (options: ResolvedConvertOptions) => `export
       alwaysBundle: () => true,
     },
 ${formatAliasProperty({})}
-  },
-  {
+  },`);
+  }
+
+  entries.push(`  {
     entry: ${JSON.stringify(path.join(options.buildDir, 'server.ts'))},
     format: 'esm',
     platform: 'node',
@@ -38,7 +50,11 @@ ${formatAliasProperty({})}
     deps: {
       alwaysBundle: () => true,
     },
-${formatAliasProperty(getServerAliases())}
-  },
+${formatAliasProperty(getServerAliases(options.outputDir))}
+  },`);
+
+  return `export default [
+${entries.join('\n')}
 ];
 `;
+};