paseo-open-with 0.1.0 → 0.2.0

package/OVERVIEW.md

@@ -1,19 +1,40 @@
+Open With opens the workspace folder, or a file link in an agent reply, in another app.
+
+## Open the workspace
+
 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.
 
+## Open a file link
+
+Right-click a local file link in an agent reply, for example `src/app.ts:42` or `D:\out\chart.png`:
+
+- **Show in Folder** opens File Explorer or Finder with the file selected.
+- **Open** opens the file with its default app.
+- **Open With ›** opens the file in an app from your list. Fork and GitHub Desktop get the git repository that holds the file, and the terminal gets its folder.
+- **Copy Path** copies the absolute path.
+
+Right-click an image in an agent reply to get **Copy Image** too. Left-click keeps Paseo's own behavior.
+
 ## Add your own apps
 
-Choose **Edit apps…** at the bottom of the menu, or open the plugin settings. There you can:
+Choose **Edit apps…** in either 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}"`.
+- Add any program, with its path and its arguments. `{path}` in the arguments is the workspace folder, or the file you right-clicked. 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.
 
+## Move from File Links
+
+Open With includes the File Links plugin. If you have File Links, remove it, or every file link gets two right-click menus.
+
 ## 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.
+
+The right-click menu works in the desktop and web apps. The mobile app has no right-click.

package/OVERVIEW.zh-CN.md

@@ -1,19 +1,40 @@
+Open With 用其他程序打开 workspace 目录，或 Agent 回复里的文件链接。
+
+## 打开 workspace
+
 Open With 在 workspace 顶栏加一个按钮。点按钮，再点一个程序，就用这个程序打开 workspace 目录。
 
 菜单预置了 Fork、GitHub Desktop、VS Code、Cursor、终端和文件管理器。菜单只显示在运行 daemon 的电脑上找到的程序。能读到程序图标时，显示程序自己的图标。
 
+## 打开文件链接
+
+右击 Agent 回复里的本地文件链接，例如 `src/app.ts:42` 或 `D:\out\chart.png`：
+
+- **在文件夹中显示**：打开资源管理器或 Finder，并选中这个文件。
+- **打开**：用默认程序打开文件。
+- **打开方式 ›**：用列表里的程序打开文件。Fork 和 GitHub Desktop 打开文件所在的 git 仓库，终端打开文件所在的目录。
+- **复制路径**：复制绝对路径。
+
+右击 Agent 回复里的图片，还可以 **复制图片**。左键单击保持 Paseo 原来的行为。
+
 ## 添加自己的程序
 
-点菜单底部的 **编辑程序…**，或打开插件设置。在设置里可以：
+点任一菜单里的 **编辑程序…**，或打开插件设置。在设置里可以：
 
-- 添加任何程序，填写程序路径和参数。参数里的 `{path}` 代表 workspace 目录。值里有空格时，用双引号括起来，例如 `-d "{path}"`。
+- 添加任何程序，填写程序路径和参数。参数里的 `{path}` 代表 workspace 目录，或你右击的文件。值里有空格时，用双引号括起来，例如 `-d "{path}"`。
 - 修改预置程序的路径，例如程序装在不常见的目录时。
 - 关闭不用的程序，在菜单里上移或下移程序。
 
 设置按 daemon 分别保存，因为每台电脑上程序的安装位置不同。
 
+## 从 File Links 迁移
+
+Open With 已包含 File Links 插件的功能。如果装了 File Links，请删除它，否则每个文件链接会出现两个右键菜单。
+
 ## 限制
 
 程序由 daemon 启动，所以程序在运行 daemon 的电脑上打开。连接远程主机时，程序在那台主机上打开。
 
 预置程序的路径支持 Windows 和 macOS。在 Linux 上，预置程序必须在 `PATH` 里。只在 Windows 上读取程序图标，其他系统显示通用图标。
+
+右键菜单支持桌面版和网页版。移动版没有右键。

package/README.md

@@ -1,11 +1,17 @@
 # Open With for Paseo
 
-A [Paseo](https://paseo.sh) plugin that opens the workspace folder in another app,
-in two clicks from the workspace header.
+A [Paseo](https://paseo.sh) plugin that opens the workspace folder, or a file
+link in an agent reply, in another app.
+
+![Open With: the workspace header menu, and the right-click menu on a file link](docs/images/promo.png)
 
 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.
+apps off, and put them in your order. The same list is in the right-click menu of
+file links and images in agent replies.
+
+Open With 0.2 includes the File Links plugin. If you have File Links, remove it
+(see [Move from File Links](#move-from-file-links)).
 
 ## Install
 
@@ -15,12 +21,15 @@ Requires **Paseo 0.13.2 or later**.
 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).
+If the button or the menu does not show, reload the Paseo window (**Ctrl+R**, or
+**Cmd+R** on macOS).
 
-## Use
+## Open the workspace
 
 Click the button in the workspace header, then click an app.
 
+![The Open With menu in the workspace header](docs/images/menu.png)
+
 Built-in apps:
 
 | App | Windows | macOS | Linux |
@@ -34,9 +43,52 @@ Built-in apps:
 
 The menu shows only the apps it finds. Apps on `PATH` are found too.
 
+## Open a file link
+
+Right-click a local file link in an agent reply:
+
+| Item | What it does |
+| --- | --- |
+| **Show in Folder** | Opens File Explorer or Finder with the file or folder selected. |
+| **Open** | Opens the file with its default app, or opens the folder. |
+| **Open With ›** | Opens the file in an app from your list. |
+| **Copy Path** | Copies the absolute path. |
+
+![Right-click a file link, then choose Open With and an app](docs/images/file-menu.png)
+
+In **Open With ›**, each app gets what it can use:
+
+| App | Gets |
+| --- | --- |
+| Fork, GitHub Desktop | the git repository that holds the file |
+| Terminal | the folder that holds the file |
+| VS Code, Cursor, and apps you add | the file itself |
+
+Right-click an image in an agent reply to get **Copy Image** too. The file items
+show only when the image comes from a local file.
+
+Left-click keeps Paseo's own behavior. To get the browser menu instead, hold
+**Shift** (or any other modifier key) while you right-click.
+
+### Supported links
+
+- Windows paths: `D:\work\report.md`, `\\server\share\a.txt`
+- `file://` URLs
+- Absolute POSIX paths: `/home/me/a.md`
+- Home paths: `~/notes.md`
+- Paths relative to the workspace: `src/app.ts`
+
+Line suffixes such as `:42`, `:42:7`, `(42,7)` and `#L42` are ignored, so the menu
+acts on the file. Web links (`https://…`, `mailto:`) keep the normal menu.
+
+If the file does not exist, the menu shows **File not found** and keeps
+**Copy Path** available. Images that an agent reads are often temporary copies, so
+**Show in Folder** can open a temp folder.
+
 ## Add an app
 
-Choose **Edit apps…** at the bottom of the menu. Then choose **Add app** and fill in:
+Choose **Edit apps…** at the bottom of either menu. Then choose **Add app** and
+fill in:
 
 | Field | Example |
 | --- | --- |
@@ -45,21 +97,51 @@ Choose **Edit apps…** at the bottom of the menu. Then choose **Add app** and f
 | 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`.
+`{path}` is the workspace folder, or the file you right-clicked. 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.
 
+![The Open With settings, with a custom app open for editing](docs/images/settings.png)
+
 ## 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.
+The daemon finds the apps, reads their icons (Windows only), and starts the app.
+So the app opens on the computer that runs the daemon, not on a remote client.
+A launch error shows as a toast in the header menu, and in the right-click menu.
+
+On Linux, **Show in Folder** asks the file manager to select the file through
+D-Bus (`org.freedesktop.FileManager1`). When no file manager answers, it opens the
+folder.
+
+The right-click menu works in the desktop and web apps. The mobile app has no
+right-click. Both menus follow Paseo's app language. Simplified Chinese is
+translated; other languages show English.
+
+![The right-click menu in Simplified Chinese](docs/images/file-menu-zh-CN.png)
+
+## Move from File Links
+
+File Links (`file-links`) is now part of Open With. To move:
+
+```bash
+paseo plugin remove file-links
+paseo plugin install https://github.com/stv1024/paseo-open-with   # or: paseo plugin update open-with
+```
+
+Remove File Links, or every file link gets two right-click menus.
+
+## Update
+
+```bash
+paseo plugin update open-with --check
+paseo plugin update open-with
+```
 
 ## Develop
 
@@ -70,6 +152,14 @@ npm test
 paseo plugin install .
 ```
 
+Run `paseo plugin reload open-with` after each change.
+
+The images in `docs/images` are rendered from the HTML mockups in
+`docs/media-src`: `node docs/media-src/render.mjs`. The script uses Chrome Headless
+Shell when Playwright has installed it (`npx playwright install chromium --only-shell`),
+and a local Chrome or Edge when not. On Windows, prefer the Shell: full Chrome can
+check the Windows account password when it creates a new profile.
+
 ### Release
 
 Releases go to npm as `paseo-open-with` through
@@ -80,7 +170,7 @@ 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
+git tag -a v0.2.0 -m "Open With 0.2.0" && git push origin v0.2.0
 ```
 
 The tag push publishes the tarball. Then create the GitHub release from the tag.