paseo-open-with 0.0.0-bootstrap.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephen Zhou
+
+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/OVERVIEW.md

@@ -0,0 +1,19 @@
+Open With adds a button to the workspace header. Click it, then click an app, and the workspace folder opens in that app.
+
+The menu starts with Fork, GitHub Desktop, VS Code, Cursor, a terminal, and the file manager. It shows only the apps it finds on the computer that runs the daemon. Where it can, it shows each app's own icon.
+
+## Add your own apps
+
+Choose **Edit apps…** at the bottom of the menu, or open the plugin settings. There you can:
+
+- Add any program, with its path and its arguments. `{path}` in the arguments is the workspace folder. Put double quotes around a value with spaces, for example `-d "{path}"`.
+- Change the program path of a built-in app, for example when it is installed in an unusual folder.
+- Turn apps off, and move them up or down in the menu.
+
+The settings belong to each daemon, because apps are installed in different places on each computer.
+
+## Limits
+
+The daemon starts the app, so the app opens on the computer that runs the daemon. On a remote host, it opens on that host.
+
+Built-in paths are known for Windows and macOS. On Linux, the built-in apps must be on `PATH`. Program icons are read on Windows only. On other systems the menu shows a generic icon.

package/OVERVIEW.zh-CN.md

@@ -0,0 +1,19 @@
+Open With 在 workspace 顶栏加一个按钮。点按钮，再点一个程序，就用这个程序打开 workspace 目录。
+
+菜单预置了 Fork、GitHub Desktop、VS Code、Cursor、终端和文件管理器。菜单只显示在运行 daemon 的电脑上找到的程序。能读到程序图标时，显示程序自己的图标。
+
+## 添加自己的程序
+
+点菜单底部的 **编辑程序…**，或打开插件设置。在设置里可以：
+
+- 添加任何程序，填写程序路径和参数。参数里的 `{path}` 代表 workspace 目录。值里有空格时，用双引号括起来，例如 `-d "{path}"`。
+- 修改预置程序的路径，例如程序装在不常见的目录时。
+- 关闭不用的程序，在菜单里上移或下移程序。
+
+设置按 daemon 分别保存，因为每台电脑上程序的安装位置不同。
+
+## 限制
+
+程序由 daemon 启动，所以程序在运行 daemon 的电脑上打开。连接远程主机时，程序在那台主机上打开。
+
+预置程序的路径支持 Windows 和 macOS。在 Linux 上，预置程序必须在 `PATH` 里。只在 Windows 上读取程序图标，其他系统显示通用图标。

package/README.md

@@ -1,3 +1,91 @@
-# paseo-open-with
+# Open With for Paseo
 
-Placeholder. See https://github.com/stv1024/paseo-open-with.
+A [Paseo](https://paseo.sh) plugin that opens the workspace folder in another app,
+in two clicks from the workspace header.
+
+Paseo's own "Open in" button has a fixed list of editors, and you cannot add an
+app such as Fork. Open With has a menu that you can change: add any program, turn
+apps off, and put them in your order.
+
+## Install
+
+Requires **Paseo 0.13.2 or later**.
+
+```bash
+paseo plugin install https://github.com/stv1024/paseo-open-with
+```
+
+If the button does not show, reload the Paseo window (**Ctrl+R**, or **Cmd+R** on macOS).
+
+## Use
+
+Click the button in the workspace header, then click an app.
+
+Built-in apps:
+
+| App | Windows | macOS | Linux |
+| --- | --- | --- | --- |
+| Fork | `%LOCALAPPDATA%\Fork` | `/Applications/Fork.app` | - |
+| GitHub Desktop | `%LOCALAPPDATA%\GitHubDesktop` | `/Applications/GitHub Desktop.app` | `github-desktop` |
+| VS Code | user or system install, or `code` | `/Applications/Visual Studio Code.app`, or `code` | `code` |
+| Cursor | user or system install, or `cursor` | `/Applications/Cursor.app`, or `cursor` | `cursor` |
+| Terminal | Windows Terminal (`wt`) | Terminal.app | `x-terminal-emulator`, `gnome-terminal`, `konsole` |
+| File Manager | File Explorer | Finder | `xdg-open` |
+
+The menu shows only the apps it finds. Apps on `PATH` are found too.
+
+## Add an app
+
+Choose **Edit apps…** at the bottom of the menu. Then choose **Add app** and fill in:
+
+| Field | Example |
+| --- | --- |
+| Program | `C:\Program Files\Sublime Merge\sublime_merge.exe` |
+| Arguments | `"{path}"` |
+| Name | `Sublime Merge` |
+| Icon | a [Lucide](https://lucide.dev/icons) icon name, used when Paseo cannot read the program icon |
+
+`{path}` is the workspace folder. Arguments split on spaces. Double quotes keep a
+value with spaces together, and backslashes stay as they are. `%VAR%` (Windows) and
+a leading `~` in the program path are expanded. A program name without a folder is
+looked up on `PATH`.
+
+To change a built-in app, click it and fill in only the fields to change. **Reset**
+returns it to the defaults.
+
+Settings are saved per daemon, so each computer keeps its own list.
+
+## How it works
+
+The daemon finds the apps, reads their icons (Windows only), and starts the app
+with the workspace folder. So the app opens on the computer that runs the daemon.
+A launch error shows as a toast.
+
+## Develop
+
+```bash
+npm install
+npm run typecheck
+npm test
+paseo plugin install .
+```
+
+### Release
+
+Releases go to npm as `paseo-open-with` through
+[`.github/workflows/release.yml`](.github/workflows/release.yml), with npm Trusted
+Publishing (no npm token). Bump `version` in `package.json`, add a `CHANGELOG.md`
+section, then commit, tag and push:
+
+```bash
+npm run typecheck && npm test && npm run pack:npm   # check the packed file list
+git push origin main
+git tag -a v0.1.0 -m "Open With 0.1.0" && git push origin v0.1.0
+```
+
+The tag push publishes the tarball. Then create the GitHub release from the tag.
+The official registry opens a bump PR for each new npm version.
+
+## License
+
+MIT

package/client/menu.tsx

@@ -0,0 +1,134 @@
+import type { ComponentType } from "react";
+import { Image } from "react-native";
+import type {
+  PluginButtonBehavior,
+  PluginButtonIconProps,
+  PluginButtonMenuEntry,
+  PluginButtonRegistration,
+  PluginClientContext,
+} from "@getpaseo/plugin/client";
+import { appsRpc, launchRpc, type App } from "../shared/open-with";
+import { messages } from "./messages";
+
+export const SETTINGS_ID = "open-with";
+const REFRESH_MS = 10 * 60 * 1000;
+
+const imageIcons = new Map<string, ComponentType<PluginButtonIconProps>>();
+
+/** One component per image, so menus keep a stable icon identity across refreshes. */
+function imageIcon(uri: string): ComponentType<PluginButtonIconProps> {
+  let icon = imageIcons.get(uri);
+  if (!icon) {
+    icon = ({ size }: PluginButtonIconProps) => <Image source={{ uri }} style={{ width: size, height: size }} />;
+    imageIcons.set(uri, icon);
+  }
+  return icon;
+}
+
+export interface OpenWithMenu {
+  /** Reads the app list again and rebuilds every menu. */
+  refresh(): Promise<void>;
+  dispose(): void;
+}
+
+export function installMenu(client: PluginClientContext): OpenWithMenu {
+  const buttons = new Map<string, PluginButtonRegistration>();
+  let apps: App[] = [];
+  let disposed = false;
+
+  const open = async (workspaceId: string, app: App) => {
+    const result = await client.rpc(launchRpc, { workspaceId, appId: app.id });
+    if (result.ok) return;
+    const text =
+      result.reason === "not-installed"
+        ? client.i18n.t(messages, "notInstalled", { name: app.name })
+        : result.reason === "no-folder"
+          ? client.i18n.t(messages, "noFolder")
+          : client.i18n.t(messages, "failed", { name: app.name });
+    // Paseo shows a rejected press as an error.
+    throw new Error(result.message ? `${text}: ${result.message}` : text);
+  };
+
+  const behavior = (workspaceId: string): PluginButtonBehavior => {
+    const items: PluginButtonMenuEntry[] = apps
+      .filter((app) => app.enabled && app.command)
+      .map((app) => ({
+        kind: "item",
+        id: app.id,
+        title: app.name,
+        icon: app.image ? imageIcon(app.image) : app.icon,
+        behavior: { kind: "action", onPress: () => open(workspaceId, app) },
+      }));
+    if (items.length === 0) {
+      items.push({ kind: "item", id: "none", title: client.i18n.t(messages, "noApps"), disabled: true, behavior: { kind: "action", onPress() {} } });
+    }
+    items.push(
+      { kind: "separator", id: "settings-separator" },
+      {
+        kind: "item",
+        id: "settings",
+        title: client.i18n.t(messages, "edit"),
+        icon: "Settings2",
+        behavior: { kind: "action", onPress: () => client.openSettings(SETTINGS_ID) },
+      },
+    );
+    return { kind: "menu", items };
+  };
+
+  const addButton = (workspaceId: string) => {
+    if (disposed || buttons.has(workspaceId)) return;
+    buttons.set(
+      workspaceId,
+      client.addHeaderButton({
+        id: "open-with",
+        workspaceId,
+        button: { title: client.i18n.t(messages, "button"), icon: "SquareArrowOutUpRight", behavior: behavior(workspaceId) },
+      }),
+    );
+  };
+
+  const removeButton = (workspaceId: string) => {
+    buttons.get(workspaceId)?.remove();
+    buttons.delete(workspaceId);
+  };
+
+  const refresh = async () => {
+    try {
+      apps = (await client.rpc(appsRpc, {})).apps;
+    } catch (error) {
+      console.error("[open-with] cannot read apps", error);
+      return;
+    }
+    if (disposed) return;
+    for (const [workspaceId, button] of buttons) button.update({ behavior: behavior(workspaceId) });
+  };
+
+  const unsubscribe = client.paseo.workspaces.subscribe((update) => {
+    if (update.kind === "upsert") addButton(update.workspace.id);
+    else removeButton(update.id);
+  });
+
+  void (async () => {
+    await refresh();
+    let cursor: string | undefined;
+    do {
+      const page = await client.paseo.workspaces.list({ page: { limit: 200, cursor } });
+      page.entries.forEach((workspace) => addButton(workspace.id));
+      cursor = page.pageInfo.hasMore ? (page.pageInfo.nextCursor ?? undefined) : undefined;
+    } while (cursor && !disposed);
+  })().catch((error: unknown) => console.error("[open-with] cannot list workspaces", error));
+
+  // Picks up apps installed or removed while Paseo stays open.
+  const timer = setInterval(() => void refresh(), REFRESH_MS);
+
+  return {
+    refresh,
+    dispose() {
+      disposed = true;
+      clearInterval(timer);
+      unsubscribe();
+      buttons.forEach((button) => button.remove());
+      buttons.clear();
+    },
+  };
+}

package/client/messages.ts

@@ -0,0 +1,64 @@
+import { defineTranslations } from "@getpaseo/plugin/client";
+
+export const messages = defineTranslations({
+  resources: {
+    en: {
+      button: "Open with",
+      settings: "Open With",
+      edit: "Edit apps…",
+      noApps: "No apps found",
+      notInstalled: "{{name}} is not installed",
+      noFolder: "Workspace folder not found",
+      failed: "Could not open {{name}}",
+      apps: "Apps",
+      notFound: "Not found",
+      name: "Name",
+      command: "Program",
+      args: "Arguments",
+      argsHint: "{path} is the workspace folder. Use double quotes around values with spaces.",
+      icon: "Icon",
+      iconHint: "A Lucide icon name. The program icon is used when Paseo can read it.",
+      add: "Add app",
+      remove: "Remove",
+      reset: "Reset",
+      moveUp: "Move up",
+      moveDown: "Move down",
+      save: "Save",
+      saved: "Saved",
+      loading: "Loading…",
+      reload: "Reload",
+      restoreDefaults: "Restore defaults",
+      newApp: "New app",
+      commandRequired: "Enter a program for each app you added.",
+    },
+    "zh-CN": {
+      button: "用其他程序打开",
+      settings: "Open With",
+      edit: "编辑程序…",
+      noApps: "没有找到程序",
+      notInstalled: "没有安装 {{name}}",
+      noFolder: "找不到 workspace 目录",
+      failed: "无法打开 {{name}}",
+      apps: "程序",
+      notFound: "未找到",
+      name: "名称",
+      command: "程序",
+      args: "参数",
+      argsHint: "{path} 代表 workspace 目录。值里有空格时，用双引号括起来。",
+      icon: "图标",
+      iconHint: "Lucide 图标名。能读到程序图标时，用程序图标。",
+      add: "添加程序",
+      remove: "删除",
+      reset: "恢复默认",
+      moveUp: "上移",
+      moveDown: "下移",
+      save: "保存",
+      saved: "已保存",
+      loading: "正在加载…",
+      reload: "重新加载",
+      restoreDefaults: "恢复默认设置",
+      newApp: "新程序",
+      commandRequired: "请给每个添加的程序填写程序路径。",
+    },
+  },
+});

package/client/settings.tsx

@@ -0,0 +1,227 @@
+import { useCallback, useEffect, useState } from "react";
+import { Image, Pressable, Switch, Text, View } from "react-native";
+import { useRpc, useSettings, useTranslation, type PluginSurfaceProps } from "@getpaseo/plugin/client";
+import { Icon, SettingsAction, SettingsCard, SettingsInput, SettingsRow, SettingsSection } from "@getpaseo/plugin/client/ui";
+import { appsRpc, mergeEntries, openWithSettings, type App, type Entry } from "../shared/open-with";
+import { messages } from "./messages";
+
+type Props = PluginSurfaceProps & { onSaved(): void };
+
+export function SettingsScreen(props: Props) {
+  const state = useSettings(openWithSettings);
+  const { t } = useTranslation(messages);
+  const c = props.theme.colors;
+  if (state.status !== "ready") {
+    return (
+      <View style={{ padding: 24, gap: 12 }}>
+        <Text style={{ color: state.status === "loading" ? c.foregroundMuted : c.statusDanger }}>
+          {state.status === "loading" ? t("loading") : state.error}
+        </Text>
+        {state.status !== "loading" && (
+          <SettingsCard>
+            <SettingsAction label={t("reload")} actionLabel={t("reload")} onPress={() => void state.reload()} />
+            {state.status === "invalid" && (
+              <SettingsAction label={t("restoreDefaults")} actionLabel={t("reset")} onPress={() => void state.reset()} />
+            )}
+          </SettingsCard>
+        )}
+      </View>
+    );
+  }
+  return (
+    <Editor
+      key={state.revision}
+      {...props}
+      stored={state.values.entries}
+      saving={state.saving}
+      saveError={state.saveError}
+      save={(entries) => state.save({ entries }, state.revision)}
+    />
+  );
+}
+
+function Editor({
+  theme,
+  stored,
+  saving,
+  saveError,
+  save,
+  onSaved,
+}: Props & {
+  stored: Entry[];
+  saving: boolean;
+  saveError: string | null;
+  save(entries: Entry[]): Promise<boolean>;
+}) {
+  const { t } = useTranslation(messages);
+  const c = theme.colors;
+  const listApps = useRpc(appsRpc);
+  const [draft, setDraft] = useState(() => mergeEntries(stored));
+  const [apps, setApps] = useState<Map<string, App>>(new Map());
+  const [editing, setEditing] = useState<string | null>(null);
+  const [error, setError] = useState("");
+  const [saved, setSaved] = useState(false);
+
+  const loadApps = useCallback(() => {
+    void listApps({})
+      .then((result) => setApps(new Map(result.apps.map((app) => [app.id, app]))))
+      .catch(() => {});
+  }, [listApps]);
+  useEffect(loadApps, [loadApps]);
+
+  const change = (next: Entry[]) => {
+    setDraft(next);
+    setSaved(false);
+    setError("");
+  };
+  const patch = (id: string, fields: Partial<Entry>) =>
+    change(draft.map((entry) => (entry.id === id ? { ...entry, ...fields } : entry)));
+  const move = (index: number, by: number) => {
+    const next = [...draft];
+    const [entry] = next.splice(index, 1);
+    next.splice(index + by, 0, entry!);
+    change(next);
+  };
+  const add = () => {
+    const id = `custom-${Date.now().toString(36)}`;
+    change([...draft, { id, preset: "", name: "", icon: "", command: "", args: "", enabled: true }]);
+    setEditing(id);
+  };
+
+  const saveNow = async () => {
+    if (draft.some((entry) => !entry.preset && !entry.command.trim())) {
+      setError(t("commandRequired"));
+      return;
+    }
+    if (await save(draft)) {
+      setSaved(true);
+      onSaved();
+    }
+  };
+
+  const iconButton = (name: string, label: string, onPress: () => void, disabled = false) => (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={label}
+      disabled={disabled}
+      onPress={onPress}
+      style={{ padding: 6, opacity: disabled ? 0.3 : 1 }}
+    >
+      <Icon name={name} size={16} color={c.foregroundMuted} />
+    </Pressable>
+  );
+
+  return (
+    <View style={{ gap: 16 }}>
+      <SettingsSection title={t("apps")}>
+        <SettingsCard>
+          {draft.map((entry, index) => {
+            const app = apps.get(entry.id);
+            const name = entry.name || app?.defaults.name || entry.command || t("newApp");
+            const open = editing === entry.id;
+            return (
+              <View key={entry.id}>
+                <Pressable
+                  accessibilityRole="button"
+                  accessibilityLabel={name}
+                  onPress={() => setEditing(open ? null : entry.id)}
+                  style={{ flexDirection: "row", alignItems: "center", gap: 10, paddingHorizontal: 16, paddingVertical: 10 }}
+                >
+                  {app?.image ? (
+                    <Image source={{ uri: app.image }} style={{ width: 20, height: 20 }} />
+                  ) : (
+                    <Icon name={entry.icon || app?.icon || "AppWindow"} size={20} color={c.foreground} />
+                  )}
+                  <View style={{ flex: 1, minWidth: 0 }}>
+                    <Text style={{ color: c.foreground, fontWeight: "500" }} numberOfLines={1}>
+                      {name}
+                    </Text>
+                    {app && (
+                      <Text style={{ color: c.foregroundMuted, fontSize: 12 }} numberOfLines={1}>
+                        {app.command ?? t("notFound")}
+                      </Text>
+                    )}
+                  </View>
+                  {iconButton("ChevronUp", t("moveUp"), () => move(index, -1), index === 0)}
+                  {iconButton("ChevronDown", t("moveDown"), () => move(index, 1), index === draft.length - 1)}
+                  <Switch value={entry.enabled} onValueChange={(enabled) => patch(entry.id, { enabled })} />
+                </Pressable>
+                {open && (
+                  <EntryFields
+                    key={`${entry.id}:${entry.preset ? JSON.stringify([entry.name, entry.command, entry.args, entry.icon]) : ""}`}
+                    entry={entry}
+                    app={app}
+                    patch={(fields) => patch(entry.id, fields)}
+                    remove={() => change(draft.filter((e) => e.id !== entry.id))}
+                  />
+                )}
+              </View>
+            );
+          })}
+          <SettingsAction label="" actionLabel={t("add")} onPress={add} />
+        </SettingsCard>
+      </SettingsSection>
+      {(error || saveError) && <Text style={{ color: c.statusDanger }}>{error || saveError}</Text>}
+      <SettingsCard>
+        <SettingsAction
+          label={saved ? t("saved") : ""}
+          actionLabel={t("save")}
+          disabled={saving}
+          onPress={() => void saveNow()}
+        />
+      </SettingsCard>
+    </View>
+  );
+}
+
+function EntryFields({
+  entry,
+  app,
+  patch,
+  remove,
+}: {
+  entry: Entry;
+  app: App | undefined;
+  patch(fields: Partial<Entry>): void;
+  remove(): void;
+}) {
+  const { t } = useTranslation(messages);
+  const defaults = app?.defaults;
+  return (
+    <View>
+      <SettingsInput
+        label={t("name")}
+        initialValue={entry.name}
+        placeholder={defaults?.name}
+        onChangeText={(name) => patch({ name })}
+      />
+      <SettingsInput
+        label={t("command")}
+        initialValue={entry.command}
+        placeholder={defaults?.command ?? (entry.preset ? t("notFound") : "C:\\Program Files\\App\\App.exe")}
+        onChangeText={(command) => patch({ command })}
+      />
+      <SettingsInput
+        label={t("args")}
+        hint={t("argsHint")}
+        initialValue={entry.args}
+        placeholder={defaults?.args ?? '"{path}"'}
+        onChangeText={(args) => patch({ args })}
+      />
+      <SettingsInput
+        label={t("icon")}
+        hint={t("iconHint")}
+        initialValue={entry.icon}
+        placeholder={defaults?.icon ?? "AppWindow"}
+        onChangeText={(icon) => patch({ icon })}
+      />
+      <SettingsRow label="">
+        {entry.preset ? (
+          <SettingsAction label="" actionLabel={t("reset")} onPress={() => patch({ name: "", command: "", args: "", icon: "" })} />
+        ) : (
+          <SettingsAction label="" actionLabel={t("remove")} onPress={remove} />
+        )}
+      </SettingsRow>
+    </View>
+  );
+}

package/index.client.tsx

@@ -0,0 +1,24 @@
+import { ScrollView } from "react-native";
+import type { PluginClientContext, PluginSurfaceProps } from "@getpaseo/plugin/client";
+import { installMenu, SETTINGS_ID } from "./client/menu";
+import { messages } from "./client/messages";
+import { SettingsScreen } from "./client/settings";
+
+export default function contribute(client: PluginClientContext) {
+  const menu = installMenu(client);
+  const Settings = (props: PluginSurfaceProps) => (
+    <ScrollView contentContainerStyle={{ padding: 18, maxWidth: 720 }}>
+      <SettingsScreen {...props} onSaved={() => void menu.refresh()} />
+    </ScrollView>
+  );
+  const removeSettings = client.addSettingsScreen({
+    id: SETTINGS_ID,
+    title: client.i18n.t(messages, "settings"),
+    icon: "SquareArrowOutUpRight",
+    Component: Settings,
+  });
+  return () => {
+    removeSettings();
+    menu.dispose();
+  };
+}

package/index.server.ts

@@ -0,0 +1,10 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { appsRpc, launchRpc, openWithSettings } from "./shared/open-with";
+import { launchApp, listApps } from "./server/open-with";
+
+export default function contribute(server: PluginServerContext) {
+  const settings = server.registerSettings(openWithSettings);
+  server.handle(appsRpc, () => listApps(settings));
+  server.handle(launchRpc, (input, { paseo }) => launchApp(input, settings, paseo));
+  return () => {};
+}

package/package.json

@@ -1,10 +1,52 @@
 {
   "name": "paseo-open-with",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder that sets up npm Trusted Publishing. Install the latest version instead.",
-  "license": "MIT",
+  "version": "0.1.0",
+  "files": [
+    "assets/",
+    "paseo-plugin.json",
+    "OVERVIEW.md",
+    "OVERVIEW.*.md",
+    "index.client.ts",
+    "index.client.tsx",
+    "index.server.ts",
+    "index.server.tsx",
+    "client/",
+    "server/",
+    "shared/",
+    "LICENSE",
+    "!**/*.test.ts"
+  ],
+  "devDependencies": {
+    "@getpaseo/plugin": "0.13.2",
+    "@tanstack/react-query": "^5.90.11",
+    "@types/node": "^22.20.5",
+    "@types/react": "~19.2.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "zod": "^4.4.3"
+  },
+  "description": "Paseo plugin: a header menu that opens the workspace folder in Fork, GitHub Desktop, VS Code, Cursor, a terminal, or any app you add.",
+  "author": "stv1024",
+  "homepage": "https://github.com/stv1024/paseo-open-with#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stv1024/paseo-open-with.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stv1024/paseo-open-with/issues"
+  },
+  "license": "MIT",
+  "keywords": [
+    "paseo",
+    "paseo-plugin",
+    "open-with",
+    "fork",
+    "editor"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   }
 }

package/paseo-plugin.json

@@ -0,0 +1,13 @@
+{
+  "id": "open-with",
+  "name": "Open With",
+  "description": "Open the workspace folder in Fork, GitHub Desktop, VS Code, Cursor, a terminal, or any app you add, in two clicks from the header.",
+  "icon": "assets/icon.png",
+  "media": [],
+  "translations": {
+    "zh-CN": { "description": "在顶栏两次点击，用 Fork、GitHub Desktop、VS Code、Cursor、终端或你添加的任何程序打开 workspace 目录。" }
+  },
+  "requirements": {
+    "paseo": ">=0.13.2"
+  }
+}

package/server/apps.ts

@@ -0,0 +1,234 @@
+import { spawn } from "node:child_process";
+import { existsSync, lstatSync } from "node:fs";
+import { posix, win32 } from "node:path";
+import { PATH_TOKEN, splitArgs, type App, type Entry, type PresetId } from "../shared/open-with";
+
+export interface Runtime {
+  platform: NodeJS.Platform;
+  env: NodeJS.ProcessEnv;
+  /** True for files and for Windows app execution aliases, which `existsSync` reports as missing. */
+  exists(path: string): boolean;
+}
+
+export const nodeRuntime: Runtime = {
+  platform: process.platform,
+  env: process.env,
+  exists(path) {
+    if (existsSync(path)) return true;
+    try {
+      return lstatSync(path).isSymbolicLink();
+    } catch {
+      return false;
+    }
+  },
+};
+
+interface Preset {
+  name: string;
+  icon: string;
+  /** Candidates in order. A bare name is looked up on PATH. */
+  commands(runtime: Runtime): string[];
+  /** Where to read the program icon when the command is a script. */
+  iconFrom?(runtime: Runtime): string[];
+}
+
+const home = (runtime: Runtime) => runtime.env.HOME ?? runtime.env.USERPROFILE ?? "";
+
+function winCandidates(runtime: Runtime, local: string[], programFiles: string[]): string[] {
+  const out: string[] = [];
+  if (runtime.env.LOCALAPPDATA) out.push(...local.map((p) => `${runtime.env.LOCALAPPDATA}\\${p}`));
+  for (const root of [runtime.env.ProgramFiles, runtime.env["ProgramFiles(x86)"]]) {
+    if (root) out.push(...programFiles.map((p) => `${root}\\${p}`));
+  }
+  return out;
+}
+
+function macApp(runtime: Runtime, app: string, binary: string): string[] {
+  return [`/Applications/${app}.app/${binary}`, `${home(runtime)}/Applications/${app}.app/${binary}`];
+}
+
+export const PRESETS: Record<PresetId, Preset> = {
+  fork: {
+    name: "Fork",
+    icon: "GitFork",
+    commands: (r) =>
+      r.platform === "win32"
+        ? winCandidates(r, ["Fork\\current\\Fork.exe", "Fork\\Fork.exe"], [])
+        : r.platform === "darwin"
+          ? [...macApp(r, "Fork", "Contents/Resources/fork_cli"), "fork"]
+          : [],
+  },
+  "github-desktop": {
+    name: "GitHub Desktop",
+    icon: "Github",
+    commands: (r) =>
+      r.platform === "win32"
+        ? [...winCandidates(r, ["GitHubDesktop\\bin\\github.bat"], []), "github"]
+        : r.platform === "darwin"
+          ? [...macApp(r, "GitHub Desktop", "Contents/Resources/app/static/github.sh"), "github"]
+          : ["github-desktop"],
+    iconFrom: (r) => (r.platform === "win32" ? winCandidates(r, ["GitHubDesktop\\GitHubDesktop.exe"], []) : []),
+  },
+  vscode: {
+    name: "VS Code",
+    icon: "Code",
+    commands: (r) =>
+      r.platform === "win32"
+        ? [
+            ...winCandidates(r, ["Programs\\Microsoft VS Code\\Code.exe"], ["Microsoft VS Code\\Code.exe"]),
+            "code",
+          ]
+        : r.platform === "darwin"
+          ? [...macApp(r, "Visual Studio Code", "Contents/Resources/app/bin/code"), "code"]
+          : ["code"],
+  },
+  cursor: {
+    name: "Cursor",
+    icon: "MousePointer2",
+    commands: (r) =>
+      r.platform === "win32"
+        ? [...winCandidates(r, ["Programs\\cursor\\Cursor.exe"], ["Cursor\\Cursor.exe"]), "cursor"]
+        : r.platform === "darwin"
+          ? [...macApp(r, "Cursor", "Contents/Resources/app/bin/cursor"), "cursor"]
+          : ["cursor"],
+  },
+  terminal: {
+    name: "Terminal",
+    icon: "SquareTerminal",
+    commands: (r) =>
+      r.platform === "win32"
+        ? [
+            ...(r.env.LOCALAPPDATA ? [`${r.env.LOCALAPPDATA}\\Microsoft\\WindowsApps\\wt.exe`] : []),
+            "wt",
+          ]
+        : r.platform === "darwin"
+          ? ["/usr/bin/open"]
+          : ["x-terminal-emulator", "gnome-terminal", "konsole"],
+  },
+  "file-manager": {
+    name: "File Manager",
+    icon: "Folder",
+    commands: (r) =>
+      r.platform === "win32" ? ["explorer.exe"] : r.platform === "darwin" ? ["/usr/bin/open"] : ["xdg-open"],
+  },
+};
+
+/** Arguments that differ by platform for one preset, where `{path}` alone is not enough. */
+function presetArgs(preset: PresetId, runtime: Runtime): string {
+  if (preset === "terminal") {
+    if (runtime.platform === "win32") return `-d "${PATH_TOKEN}"`;
+    if (runtime.platform === "darwin") return `-a Terminal "${PATH_TOKEN}"`;
+    return `--working-directory="${PATH_TOKEN}"`;
+  }
+  return `"${PATH_TOKEN}"`;
+}
+
+function isAbsolute(path: string, platform: NodeJS.Platform) {
+  return platform === "win32" ? win32.isAbsolute(path) : posix.isAbsolute(path);
+}
+
+/** Finds a candidate on disk or on PATH, like a shell would. */
+export function resolveCommand(candidates: readonly string[], runtime: Runtime): string | null {
+  const windows = runtime.platform === "win32";
+  const pathValue = runtime.env.PATH ?? runtime.env.Path ?? "";
+  const dirs = pathValue.split(windows ? ";" : ":").filter(Boolean);
+  for (const raw of candidates) {
+    const candidate = expandEnv(raw, runtime);
+    if (isAbsolute(candidate, runtime.platform)) {
+      if (runtime.exists(candidate)) return candidate;
+      continue;
+    }
+    const extensions =
+      windows && !win32.extname(candidate) ? [".exe", ".cmd", ".bat", ".com"] : [""];
+    for (const dir of dirs) {
+      for (const extension of extensions) {
+        const full = (windows ? win32 : posix).join(dir, candidate + extension);
+        if (runtime.exists(full)) return full;
+      }
+    }
+  }
+  return null;
+}
+
+/** Expands `%NAME%` on Windows and a leading `~` everywhere. */
+export function expandEnv(value: string, runtime: Runtime): string {
+  let out = value.trim();
+  if (out === "~" || out.startsWith("~/") || out.startsWith("~\\")) out = home(runtime) + out.slice(1);
+  if (runtime.platform === "win32") {
+    out = out.replace(/%([^%]+)%/g, (match, name: string) => {
+      const key = Object.keys(runtime.env).find((k) => k.toLowerCase() === name.toLowerCase());
+      return key ? (runtime.env[key] ?? match) : match;
+    });
+  }
+  return out;
+}
+
+/** The menu entry after merging stored fields over the preset. */
+export function describeEntry(entry: Entry, runtime: Runtime): App {
+  const preset = entry.preset ? PRESETS[entry.preset as PresetId] : undefined;
+  const defaults = {
+    name: preset?.name ?? "",
+    icon: preset?.icon ?? "AppWindow",
+    command: preset ? resolveCommand(preset.commands(runtime), runtime) : null,
+    args: preset ? presetArgs(entry.preset as PresetId, runtime) : `"${PATH_TOKEN}"`,
+  };
+  const command = entry.command ? resolveCommand([entry.command], runtime) : defaults.command;
+  return {
+    id: entry.id,
+    preset: entry.preset,
+    enabled: entry.enabled,
+    name: entry.name || defaults.name || entry.command || entry.id,
+    icon: entry.icon || defaults.icon,
+    command,
+    args: entry.args || defaults.args,
+    defaults,
+  };
+}
+
+export interface Command {
+  executable: string;
+  args: string[];
+  /** Windows batch files run through cmd.exe, which needs its own quoting. */
+  shell: boolean;
+}
+
+const CMD_SPECIAL = /[\s"&|^<>()!%]/;
+
+function quoteForCmd(value: string): string {
+  if (!value || CMD_SPECIAL.test(value)) return `"${value.replace(/"/g, '""')}"`;
+  return value;
+}
+
+export function buildCommand(app: App, folder: string, runtime: Runtime): Command {
+  if (!app.command) throw new Error(`${app.name} is not installed`);
+  const args = splitArgs(app.args).map((arg) => arg.split(PATH_TOKEN).join(folder));
+  const script = runtime.platform === "win32" && /\.(cmd|bat)$/i.test(app.command);
+  if (script) {
+    return { executable: quoteForCmd(app.command), args: args.map(quoteForCmd), shell: true };
+  }
+  return { executable: app.command, args, shell: false };
+}
+
+/** Keys the daemon sets for itself. Child apps must not inherit them. */
+const DAEMON_ENV = ["PASEO_NODE_ENV", "PASEO_DESKTOP_MANAGED", "PASEO_SUPERVISED", "ELECTRON_RUN_AS_NODE", "ELECTRON_NO_ATTACH_CONSOLE"];
+
+export function launch(command: Command, cwd: string, runtime: Runtime = nodeRuntime): Promise<void> {
+  const env = { ...runtime.env };
+  for (const key of DAEMON_ENV) delete env[key];
+  return new Promise((resolve, reject) => {
+    const child = spawn(command.executable, command.args, {
+      cwd,
+      env,
+      detached: true,
+      stdio: "ignore",
+      shell: command.shell,
+      windowsHide: command.shell,
+    });
+    child.once("error", reject);
+    // explorer.exe exits with code 1 even on success, so only a spawn failure counts.
+    child.once("spawn", () => {
+      child.unref();
+      resolve();
+    });
+  });
+}

package/server/icons.ts

@@ -0,0 +1,66 @@
+import { execFile } from "node:child_process";
+
+/**
+ * Reads PNG icons of Windows programs. Paths go in through an environment variable as
+ * base64 UTF-8 lines, and icons come back one base64 line per path, so no path text
+ * crosses the console code page.
+ */
+const SCRIPT = `
+$ErrorActionPreference = 'SilentlyContinue'
+Add-Type -AssemblyName System.Drawing
+$text = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($env:OPEN_WITH_ICON_PATHS))
+foreach ($p in $text.Split([char]10)) {
+  $png = '-'
+  $icon = $null
+  if (Test-Path -LiteralPath $p) { $icon = [System.Drawing.Icon]::ExtractAssociatedIcon($p) }
+  if ($icon) {
+    $bmp = $icon.ToBitmap()
+    $ms = New-Object IO.MemoryStream
+    $bmp.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png)
+    $png = [Convert]::ToBase64String($ms.ToArray())
+  }
+  [Console]::Out.WriteLine($png)
+}
+`;
+
+const cache = new Map<string, string | null>();
+
+/** PNG data URLs keyed by path. Paths without an icon are missing from the result. */
+export async function readIcons(paths: readonly string[]): Promise<Map<string, string>> {
+  const result = new Map<string, string>();
+  const missing = [...new Set(paths)].filter((path) => !cache.has(path));
+  if (process.platform === "win32" && missing.length > 0) {
+    const pngs = await runScript(missing).catch(() => null);
+    missing.forEach((path, index) => {
+      const png = pngs?.[index];
+      // A failed run is not cached, so the next menu load tries again.
+      if (pngs) cache.set(path, png ? `data:image/png;base64,${png}` : null);
+    });
+  }
+  for (const path of paths) {
+    const url = cache.get(path);
+    if (url) result.set(path, url);
+  }
+  return result;
+}
+
+function runScript(paths: readonly string[]): Promise<string[]> {
+  return new Promise((resolve, reject) => {
+    execFile(
+      "powershell.exe",
+      ["-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(SCRIPT, "utf16le").toString("base64")],
+      {
+        env: { ...process.env, OPEN_WITH_ICON_PATHS: Buffer.from(paths.join("\n"), "utf8").toString("base64") },
+        timeout: 15_000,
+        windowsHide: true,
+        maxBuffer: 8 * 1024 * 1024,
+      },
+      (error, stdout) => {
+        if (error) return reject(error);
+        const lines = stdout.split(/\r?\n/).filter(Boolean);
+        if (lines.length !== paths.length) return reject(new Error("Unexpected icon output"));
+        resolve(lines.map((line) => (line === "-" ? "" : line)));
+      },
+    );
+  });
+}

package/server/open-with.ts

@@ -0,0 +1,64 @@
+import { stat } from "node:fs/promises";
+import type { RpcInput, RpcOutput } from "@getpaseo/plugin";
+import type { PluginHandlerContext, PluginSettings } from "@getpaseo/plugin/server";
+import { appsRpc, launchRpc, mergeEntries, settingsSchema, type App } from "../shared/open-with";
+import { buildCommand, describeEntry, launch, nodeRuntime, PRESETS, resolveCommand } from "./apps";
+import { readIcons } from "./icons";
+import type { PresetId } from "../shared/open-with";
+
+type Paseo = PluginHandlerContext["paseo"];
+type Settings = PluginSettings<typeof settingsSchema>;
+
+async function storedEntries(settings: Settings) {
+  const state = await settings.read();
+  return mergeEntries(state.status === "ready" ? state.values.entries : []);
+}
+
+/** Where to read each app's icon: the program, or a sibling exe when the program is a script. */
+function iconSource(app: App): string | null {
+  if (app.preset && app.command === app.defaults.command) {
+    const iconFrom = PRESETS[app.preset as PresetId].iconFrom?.(nodeRuntime);
+    if (iconFrom) return resolveCommand(iconFrom, nodeRuntime);
+  }
+  return app.command && /\.exe$/i.test(app.command) ? app.command : null;
+}
+
+export async function listApps(settings: Settings): Promise<RpcOutput<typeof appsRpc>> {
+  const apps = (await storedEntries(settings)).map((entry) => describeEntry(entry, nodeRuntime));
+  const sources = apps.map(iconSource);
+  const icons = await readIcons(sources.filter((s): s is string => s !== null));
+  return {
+    apps: apps.map((app, index) => {
+      const image = sources[index] ? icons.get(sources[index]) : undefined;
+      return image ? { ...app, image } : app;
+    }),
+  };
+}
+
+async function workspaceFolder(paseo: Paseo, workspaceId: string): Promise<string | null> {
+  const ref = paseo.workspaces.ref(workspaceId);
+  const workspace = await ref.refresh();
+  return workspace?.workspaceDirectory ?? ref.directory ?? null;
+}
+
+export async function launchApp(
+  input: RpcInput<typeof launchRpc>,
+  settings: Settings,
+  paseo: Paseo,
+): Promise<RpcOutput<typeof launchRpc>> {
+  const entry = (await storedEntries(settings)).find((e) => e.id === input.appId);
+  if (!entry) return { ok: false, reason: "unknown-app" };
+  const app = describeEntry(entry, nodeRuntime);
+  if (!app.command) return { ok: false, reason: "not-installed" };
+
+  const folder = await workspaceFolder(paseo, input.workspaceId).catch(() => null);
+  if (!folder || !(await stat(folder).then((s) => s.isDirectory(), () => false))) {
+    return { ok: false, reason: "no-folder" };
+  }
+  try {
+    await launch(buildCommand(app, folder, nodeRuntime), folder);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, reason: "failed", message: error instanceof Error ? error.message : String(error) };
+  }
+}

package/shared/open-with.ts

@@ -0,0 +1,127 @@
+import { defineRpc, defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+
+/** Built-in apps, in their default menu order. The daemon finds where each one is installed. */
+export const PRESET_IDS = ["fork", "github-desktop", "vscode", "cursor", "terminal", "file-manager"] as const;
+export type PresetId = (typeof PRESET_IDS)[number];
+
+/** Replaced with the workspace folder in each argument. */
+export const PATH_TOKEN = "{path}";
+
+export const entrySchema = z.object({
+  id: z.string().min(1).max(64),
+  /** A preset id, or "" for an app the user added. */
+  preset: z.string().max(64).default(""),
+  /** Empty fields fall back to the preset. */
+  name: z.string().trim().max(80).default(""),
+  icon: z.string().trim().max(64).default(""),
+  command: z.string().trim().max(1024).default(""),
+  args: z.string().trim().max(2048).default(""),
+  enabled: z.boolean().default(true),
+});
+export type Entry = z.infer<typeof entrySchema>;
+
+export const settingsSchema = z.object({
+  entries: z.array(entrySchema).max(64).default([]),
+});
+export type Settings = z.infer<typeof settingsSchema>;
+
+/** Host scope: each computer keeps its own app list, because install paths differ. */
+export const openWithSettings = defineSettings({
+  id: "apps",
+  scope: "host",
+  version: 1,
+  schema: settingsSchema,
+});
+
+export function isPresetId(value: string): value is PresetId {
+  return (PRESET_IDS as readonly string[]).includes(value);
+}
+
+export function presetEntry(preset: PresetId): Entry {
+  return { id: preset, preset, name: "", icon: "", command: "", args: "", enabled: true };
+}
+
+/** Stored entries in their order, then every preset the user has not stored yet. */
+export function mergeEntries(stored: readonly Entry[]): Entry[] {
+  const ids = new Set<string>();
+  const merged: Entry[] = [];
+  for (const entry of stored) {
+    if (ids.has(entry.id)) continue;
+    if (entry.preset && !isPresetId(entry.preset)) continue;
+    ids.add(entry.id);
+    merged.push(entry);
+  }
+  const storedPresets = new Set(merged.map((entry) => entry.preset));
+  for (const preset of PRESET_IDS) {
+    if (!storedPresets.has(preset) && !ids.has(preset)) merged.push(presetEntry(preset));
+  }
+  return merged;
+}
+
+/**
+ * Splits an argument line on spaces. Double quotes group a value with spaces.
+ * Backslashes stay literal, so Windows paths need no escaping.
+ */
+export function splitArgs(line: string): string[] {
+  const args: string[] = [];
+  let current = "";
+  let quoted = false;
+  let started = false;
+  for (const char of line) {
+    if (char === '"') {
+      quoted = !quoted;
+      started = true;
+    } else if (!quoted && /\s/.test(char)) {
+      if (started) args.push(current);
+      current = "";
+      started = false;
+    } else {
+      current += char;
+      started = true;
+    }
+  }
+  if (started) args.push(current);
+  return args;
+}
+
+export const appSchema = z.object({
+  id: z.string(),
+  preset: z.string(),
+  enabled: z.boolean(),
+  name: z.string(),
+  icon: z.string(),
+  /** A PNG data URL of the program icon, when the daemon could read one. */
+  image: z.string().optional(),
+  /** The program that runs, or null when it is not installed. */
+  command: z.string().nullable(),
+  args: z.string(),
+  defaults: z.object({
+    name: z.string(),
+    icon: z.string(),
+    command: z.string().nullable(),
+    args: z.string(),
+  }),
+});
+export type App = z.infer<typeof appSchema>;
+
+export const appsRpc = defineRpc({
+  name: "open-with.apps",
+  input: z.object({}),
+  output: z.object({ apps: z.array(appSchema) }),
+});
+
+export const launchFailureSchema = z.enum(["unknown-app", "not-installed", "no-folder", "failed"]);
+export type LaunchFailure = z.infer<typeof launchFailureSchema>;
+
+export const launchRpc = defineRpc({
+  name: "open-with.launch",
+  input: z.object({
+    workspaceId: z.string().min(1).max(512),
+    appId: z.string().min(1).max(64),
+  }),
+  output: z.discriminatedUnion("ok", [
+    z.object({ ok: z.literal(true) }),
+    z.object({ ok: z.literal(false), reason: launchFailureSchema, message: z.string().optional() }),
+  ]),
+});