paseo-open-with 0.1.1 → 0.2.1

package/paseo-plugin.json

@@ -1,15 +1,18 @@
 {
   "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.",
+  "description": "Open the workspace, or a file link in an agent reply, in Fork, VS Code, Cursor, a terminal, or any app you add. Right-click a file link or image to show it in its folder or copy its path.",
   "icon": "assets/icon.png",
   "media": [
+    "docs/images/promo.png",
     "docs/images/menu.png",
-    "docs/images/settings.png"
+    "docs/images/file-menu.png",
+    "docs/images/settings.png",
+    "docs/images/file-menu-zh-CN.png"
   ],
   "translations": {
     "zh-CN": {
-      "description": "在顶栏两次点击，用 Fork、GitHub Desktop、VS Code、Cursor、终端或你添加的任何程序打开 workspace 目录。"
+      "description": "用 Fork、VS Code、Cursor、终端或你添加的任何程序，打开 workspace 或 Agent 回复里的文件链接。右击文件链接或图片，可以在文件夹中显示、复制路径。"
     }
   },
   "requirements": {

package/server/apps.ts

@@ -30,6 +30,8 @@ interface Preset {
   commands(runtime: Runtime): string[];
   /** Where to read the program icon when the command is a script. */
   iconFrom?(runtime: Runtime): string[];
+  /** What the app opens for a file: its folder, or the git repository that holds it. */
+  target?: "folder" | "repo";
 }
 
 const home = (runtime: Runtime) => runtime.env.HOME ?? runtime.env.USERPROFILE ?? "";
@@ -57,6 +59,7 @@ export const PRESETS: Record<PresetId, Preset> = {
         : r.platform === "darwin"
           ? [...macApp(r, "Fork", "Contents/Resources/fork_cli"), "fork"]
           : [],
+    target: "repo",
   },
   "github-desktop": {
     name: "GitHub Desktop",
@@ -68,6 +71,7 @@ export const PRESETS: Record<PresetId, Preset> = {
           ? [...macApp(r, "GitHub Desktop", "Contents/Resources/app/static/github.sh"), "github"]
           : ["github-desktop"],
     iconFrom: (r) => (r.platform === "win32" ? winCandidates(r, ["GitHubDesktop\\GitHubDesktop.exe"], []) : []),
+    target: "repo",
   },
   vscode: {
     name: "VS Code",
@@ -104,6 +108,7 @@ export const PRESETS: Record<PresetId, Preset> = {
         : r.platform === "darwin"
           ? ["/usr/bin/open"]
           : ["x-terminal-emulator", "gnome-terminal", "konsole"],
+    target: "folder",
   },
   "file-manager": {
     name: "File Manager",
@@ -113,12 +118,20 @@ export const PRESETS: Record<PresetId, Preset> = {
   },
 };
 
-/** Arguments that differ by platform for one preset, where `{path}` alone is not enough. */
-function presetArgs(preset: PresetId, runtime: Runtime): string {
+/**
+ * Arguments that differ by platform for one preset, where `{path}` alone is not enough.
+ * `command` is the program that runs, because Linux terminals take different options.
+ */
+function presetArgs(preset: PresetId, command: string | null, 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}"`;
+    const program = command ? posix.basename(command) : "";
+    if (program === "konsole") return `--workdir "${PATH_TOKEN}"`;
+    if (program === "gnome-terminal") return `--working-directory="${PATH_TOKEN}"`;
+    // x-terminal-emulator can be any terminal. It starts in the folder because
+    // `launch` sets the working directory.
+    return "";
   }
   return `"${PATH_TOKEN}"`;
 }
@@ -166,13 +179,14 @@ export function expandEnv(value: string, runtime: Runtime): string {
 /** 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 defaultCommand = preset ? resolveCommand(preset.commands(runtime), runtime) : null;
+  const command = entry.command ? resolveCommand([entry.command], runtime) : defaultCommand;
   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}"`,
+    command: defaultCommand,
+    args: preset ? presetArgs(entry.preset as PresetId, command, runtime) : `"${PATH_TOKEN}"`,
   };
-  const command = entry.command ? resolveCommand([entry.command], runtime) : defaults.command;
   return {
     id: entry.id,
     preset: entry.preset,
@@ -185,6 +199,19 @@ export function describeEntry(entry: Entry, runtime: Runtime): App {
   };
 }
 
+/** The path an app gets for a file or folder. Git clients get the repository, terminals the folder. */
+export function targetPath(app: App, path: string, isDirectory: boolean, runtime: Runtime): string {
+  const kind = app.preset ? PRESETS[app.preset as PresetId].target : undefined;
+  if (!kind) return path;
+  const api = runtime.platform === "win32" ? win32 : posix;
+  const folder = isDirectory ? path : api.dirname(path);
+  if (kind === "folder") return folder;
+  for (let dir = folder; ; dir = api.dirname(dir)) {
+    if (runtime.exists(api.join(dir, ".git"))) return dir;
+    if (api.dirname(dir) === dir) return folder;
+  }
+}
+
 export interface Command {
   executable: string;
   args: string[];

package/server/file-links.ts

@@ -0,0 +1,191 @@
+import { spawn } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { RpcInput, RpcOutput } from "@getpaseo/plugin";
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import { fileLinkRpc, parseLocalHref } from "../shared/file-links";
+import type { OpenResult } from "./open-with";
+
+type FileLinkInput = RpcInput<typeof fileLinkRpc>;
+type FileLinkOutput = RpcOutput<typeof fileLinkRpc>;
+type PaseoApi = PluginHandlerContext["paseo"];
+
+export interface Command {
+  executable: string;
+  args: string[];
+  verbatim?: boolean;
+  /** Wait for the exit code, and try the next command when it is not 0. */
+  check?: boolean;
+}
+
+/** Opens a file or folder in an app from the Open With list. */
+export type OpenApp = (appId: string, path: string, isDirectory: boolean) => Promise<OpenResult>;
+
+class FileLinkError extends Error {
+  constructor(
+    readonly reason: "invalid" | "no-base",
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+function pathApi(platform: NodeJS.Platform) {
+  return platform === "win32" ? win32 : posix;
+}
+
+/** Turns an href into an absolute path. `base` is only read for relative paths. */
+export async function hrefToAbsolutePath(
+  href: string,
+  base: () => Promise<string | null>,
+  platform: NodeJS.Platform = process.platform,
+): Promise<string> {
+  const local = parseLocalHref(href);
+  if (!local) {
+    throw new FileLinkError("invalid", "The link has no local path.");
+  }
+  const path = pathApi(platform);
+  if (local.kind === "file-url") {
+    try {
+      return path.resolve(fileURLToPath(local.url, { windows: platform === "win32" }));
+    } catch {
+      throw new FileLinkError("invalid", "The file URL is not valid.");
+    }
+  }
+
+  const raw = local.path;
+  if (raw === "~" || /^~[\\/]/.test(raw)) {
+    return path.resolve(homedir(), raw.slice(2));
+  }
+  if (path.isAbsolute(raw)) {
+    return path.resolve(raw);
+  }
+  const root = await base();
+  if (!root) {
+    throw new FileLinkError("no-base", "The workspace folder is unknown.");
+  }
+  return path.resolve(root, raw);
+}
+
+/** The commands to try in order. `reveal` selects the file or folder in its parent folder. */
+export function buildCommands(
+  action: "reveal" | "open",
+  filePath: string,
+  platform: NodeJS.Platform = process.platform,
+): Command[] {
+  if (platform === "win32") {
+    // explorer.exe needs the quotes inside the `/select,` argument, so pass it verbatim.
+    const quoted = `"${filePath}"`;
+    return [{ executable: "explorer.exe", args: [action === "reveal" ? `/select,${quoted}` : quoted], verbatim: true }];
+  }
+  if (platform === "darwin") {
+    return [{ executable: "/usr/bin/open", args: action === "reveal" ? ["-R", filePath] : [filePath] }];
+  }
+  if (action === "open") {
+    return [{ executable: "xdg-open", args: [filePath] }];
+  }
+  // Most Linux file managers select items through this D-Bus call. Others get the parent folder.
+  const uri = "file://" + filePath.split("/").map(encodeURIComponent).join("/");
+  return [
+    {
+      executable: "dbus-send",
+      args: [
+        "--session",
+        "--print-reply",
+        "--dest=org.freedesktop.FileManager1",
+        "/org/freedesktop/FileManager1",
+        "org.freedesktop.FileManager1.ShowItems",
+        `array:string:${uri}`,
+        "string:",
+      ],
+      check: true,
+    },
+    { executable: "xdg-open", args: [posix.dirname(filePath)] },
+  ];
+}
+
+function run(command: Command): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command.executable, command.args, {
+      detached: !command.check,
+      stdio: "ignore",
+      shell: false,
+      windowsVerbatimArguments: command.verbatim === true,
+    });
+    child.once("error", reject);
+    if (command.check) {
+      child.once("exit", (code) => (code === 0 ? resolve() : reject(new Error(`exit ${code}`))));
+      return;
+    }
+    // explorer.exe exits with code 1 even on success, so only a spawn failure counts.
+    child.once("spawn", () => {
+      child.unref();
+      resolve();
+    });
+  });
+}
+
+async function runFirst(commands: Command[]): Promise<void> {
+  let failure: unknown;
+  for (const command of commands) {
+    try {
+      return await run(command);
+    } catch (error) {
+      failure = error;
+    }
+  }
+  throw failure;
+}
+
+async function workspaceRoot(input: FileLinkInput, paseo: PaseoApi): Promise<string | null> {
+  if (input.agentId) {
+    const agent = paseo.agents.ref(input.agentId);
+    await agent.refresh();
+    if (agent.cwd) {
+      return agent.cwd;
+    }
+  }
+  if (input.workspaceId) {
+    const workspace = await paseo.workspaces.ref(input.workspaceId).refresh();
+    return workspace?.workspaceDirectory ?? null;
+  }
+  return null;
+}
+
+export async function actOnFileLink(
+  input: FileLinkInput,
+  paseo: PaseoApi,
+  openApp: OpenApp,
+): Promise<FileLinkOutput> {
+  let filePath: string;
+  try {
+    filePath = await hrefToAbsolutePath(input.href, () => workspaceRoot(input, paseo));
+  } catch (error) {
+    return { ok: false, reason: error instanceof FileLinkError ? error.reason : "failed" };
+  }
+
+  let isDirectory: boolean;
+  try {
+    isDirectory = (await stat(filePath)).isDirectory();
+  } catch {
+    return { ok: false, reason: "not-found", path: filePath };
+  }
+
+  if (input.action === "app") {
+    if (!input.appId) {
+      return { ok: false, reason: "unknown-app", path: filePath };
+    }
+    const result = await openApp(input.appId, filePath, isDirectory);
+    return result.ok ? { ok: true, path: filePath, isDirectory } : { ...result, path: filePath };
+  }
+  if (input.action !== "resolve") {
+    try {
+      await runFirst(buildCommands(input.action, filePath));
+    } catch {
+      return { ok: false, reason: "failed", path: filePath };
+    }
+  }
+  return { ok: true, path: filePath, isDirectory };
+}

package/server/open-with.ts

@@ -1,13 +1,14 @@
 import { stat } from "node:fs/promises";
+import { dirname } from "node:path";
 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 { buildCommand, describeEntry, launch, nodeRuntime, PRESETS, resolveCommand, targetPath } from "./apps";
 import { readIcons } from "./icons";
 import type { PresetId } from "../shared/open-with";
 
 type Paseo = PluginHandlerContext["paseo"];
-type Settings = PluginSettings<typeof settingsSchema>;
+export type Settings = PluginSettings<typeof settingsSchema>;
 
 async function storedEntries(settings: Settings) {
   const state = await settings.read();
@@ -41,24 +42,40 @@ async function workspaceFolder(paseo: Paseo, workspaceId: string): Promise<strin
   return workspace?.workspaceDirectory ?? ref.directory ?? null;
 }
 
-export async function launchApp(
-  input: RpcInput<typeof launchRpc>,
+export type OpenResult =
+  | { ok: true }
+  | { ok: false; reason: "unknown-app" | "not-installed" | "failed"; message?: string };
+
+/** Opens a file or folder in one app from the list. */
+export async function openInApp(
+  appId: string,
+  path: string,
+  isDirectory: boolean,
   settings: Settings,
-  paseo: Paseo,
-): Promise<RpcOutput<typeof launchRpc>> {
-  const entry = (await storedEntries(settings)).find((e) => e.id === input.appId);
+): Promise<OpenResult> {
+  const entry = (await storedEntries(settings)).find((e) => e.id === 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" };
-  }
+  const target = targetPath(app, path, isDirectory, nodeRuntime);
+  const cwd = target === path && !isDirectory ? dirname(path) : target;
   try {
-    await launch(buildCommand(app, folder, nodeRuntime), folder);
+    await launch(buildCommand(app, target, nodeRuntime), cwd);
     return { ok: true };
   } catch (error) {
     return { ok: false, reason: "failed", message: error instanceof Error ? error.message : String(error) };
   }
 }
+
+export async function launchApp(
+  input: RpcInput<typeof launchRpc>,
+  settings: Settings,
+  paseo: Paseo,
+): Promise<RpcOutput<typeof launchRpc>> {
+  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" };
+  }
+  return openInApp(input.appId, folder, true, settings);
+}

package/shared/file-links.ts

@@ -0,0 +1,109 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+/** `app` opens the file in the Open With app given by `appId`. */
+export const fileLinkActionSchema = z.enum(["resolve", "reveal", "open", "app"]);
+export type FileLinkAction = z.infer<typeof fileLinkActionSchema>;
+
+export const fileLinkFailureSchema = z.enum([
+  "invalid",
+  "no-base",
+  "not-found",
+  "failed",
+  "unknown-app",
+  "not-installed",
+]);
+export type FileLinkFailure = z.infer<typeof fileLinkFailureSchema>;
+
+export const fileLinkRpc = defineRpc({
+  name: "open-with.file",
+  input: z.object({
+    href: z.string().min(1).max(16_384),
+    action: fileLinkActionSchema,
+    appId: z.string().min(1).max(64).optional(),
+    agentId: z.string().min(1).max(512).optional(),
+    workspaceId: z.string().min(1).max(512).optional(),
+  }),
+  output: z.discriminatedUnion("ok", [
+    z.object({ ok: z.literal(true), path: z.string(), isDirectory: z.boolean() }),
+    z.object({
+      ok: z.literal(false),
+      reason: fileLinkFailureSchema,
+      path: z.string().optional(),
+      message: z.string().optional(),
+    }),
+  ]),
+});
+
+export type LocalHref =
+  | { kind: "file-url"; url: string }
+  | { kind: "path"; path: string };
+
+const LINE_FRAGMENT = /#L[0-9]+(?:C[0-9]+)?(?:-L?[0-9]+(?:C[0-9]+)?)?$/i;
+const COLON_LINE_SUFFIX = /:[0-9]+(?::[0-9]+)?(?:-[0-9]+(?::[0-9]+)?)?$/;
+const PAREN_LINE_SUFFIX = /\([0-9]+(?:,[0-9]+)?(?:-[0-9]+(?:,[0-9]+)?)?\)$/;
+const WINDOWS_DRIVE = /^[A-Za-z]:[\\/]/;
+const URL_SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+
+function safeDecode(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+/** Removes `:12`, `:12:3`, `#L12-L20` and `(12,3)` so the link points at the file itself. */
+export function stripSourcePosition(value: string): string {
+  return value
+    .replace(LINE_FRAGMENT, "")
+    .replace(COLON_LINE_SUFFIX, "")
+    .replace(PAREN_LINE_SUFFIX, "");
+}
+
+/** Returns the local file target of an assistant link, or null for web and app links. */
+export function parseLocalHref(href: string): LocalHref | null {
+  const trimmed = href.trim();
+  if (!trimmed || trimmed.startsWith("#")) {
+    return null;
+  }
+  if (/^file:/i.test(trimmed)) {
+    return { kind: "file-url", url: trimmed.replace(LINE_FRAGMENT, "") };
+  }
+
+  const path = stripSourcePosition(safeDecode(trimmed)).trim();
+  if (!path) {
+    return null;
+  }
+  if (WINDOWS_DRIVE.test(path) || path.startsWith("\\\\")) {
+    return { kind: "path", path };
+  }
+  if (URL_SCHEME.test(path)) {
+    return null;
+  }
+  return { kind: "path", path };
+}
+
+export interface RouteContext {
+  serverId?: string;
+  agentId?: string;
+  workspaceId?: string;
+}
+
+export function getRouteContext(pathname: string): RouteContext {
+  const pathOnly = pathname.split(/[?#]/, 1)[0] ?? "";
+  const host = pathOnly.match(/^\/h\/([^/]+)(?:\/|$)/);
+  if (!host?.[1]) {
+    return {};
+  }
+  const serverId = safeDecode(host[1]);
+  const agent = pathOnly.match(/^\/h\/[^/]+\/agent\/([^/]+)(?:\/|$)/);
+  if (agent?.[1]) {
+    return { serverId, agentId: safeDecode(agent[1]) };
+  }
+  const workspace = pathOnly.match(/^\/h\/[^/]+\/workspace\/([^/]+)(?:\/|$)/);
+  if (workspace?.[1]) {
+    return { serverId, workspaceId: safeDecode(workspace[1]) };
+  }
+  return { serverId };
+}