paseo-finder-links 0.1.0

package/LICENSE

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

@@ -0,0 +1,53 @@
+# Paseo Finder Links
+
+Reveal local file links from Paseo in the operating system's file manager. The plugin selects files
+in macOS Finder or Windows File Explorer, while web links and source references such as
+`src/app.ts:42` keep Paseo's native behavior.
+
+## Installation
+
+Enable plugins in Paseo under **Settings > Plugins**, then install the public Git repository:
+
+```bash
+paseo plugin add npm:paseo-finder-links@0.1.0
+paseo plugin ls paseo-finder-links
+```
+
+Paseo plugins are trusted, unsandboxed code. Review this repository before installing it.
+
+## Behavior
+
+The client intercepts only unmodified primary clicks on local-file anchors rendered by assistant
+messages. The daemon then:
+
+1. resolves relative paths against the active agent or workspace;
+2. verifies that the target exists;
+3. invokes the native file manager with separated arguments and no shell.
+
+| Platform | File | Directory |
+| --- | --- | --- |
+| macOS | Selected in Finder with `/usr/bin/open -R` | Revealed in Finder |
+| Windows | Selected in File Explorer with `explorer.exe /select,PATH` | Opened in File Explorer |
+
+Windows drive paths, `file:///C:/...` URLs, paths containing spaces, and UNC `file://server/share/...`
+URLs are supported.
+
+## Known limitations
+
+- Linux is not supported in version 0.1.0.
+- The click integration is available in Paseo's web-based desktop client, not native mobile clients.
+- Source-position links remain inside Paseo by design.
+
+## Development
+
+```bash
+npm ci
+npm test
+npm run typecheck
+```
+
+CI runs the test and typecheck suite on both macOS and Windows.
+
+## License
+
+MIT

package/client/web.ts

@@ -0,0 +1,92 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { Platform } from "react-native";
+import {
+  getRouteContext,
+  isFinderEligibleHref,
+  revealInFinderRpc,
+} from "../shared/reveal";
+
+interface ClickTarget {
+  closest(selector: string): AnchorElement | null;
+}
+
+interface AnchorElement {
+  getAttribute(name: string): string | null;
+}
+
+interface ClickEvent {
+  readonly button: number;
+  readonly target: unknown;
+  readonly altKey: boolean;
+  readonly ctrlKey: boolean;
+  readonly metaKey: boolean;
+  readonly shiftKey: boolean;
+  preventDefault(): void;
+  stopPropagation(): void;
+  stopImmediatePropagation(): void;
+}
+
+interface WebDocument {
+  addEventListener(type: "click", listener: (event: ClickEvent) => void, capture: boolean): void;
+  removeEventListener(type: "click", listener: (event: ClickEvent) => void, capture: boolean): void;
+}
+
+declare const document: WebDocument;
+declare const location: { readonly pathname: string };
+
+function asClickTarget(value: unknown): ClickTarget | null {
+  if (!value || typeof value !== "object" || !("closest" in value)) {
+    return null;
+  }
+  return value as ClickTarget;
+}
+
+function isAssistantFileAnchor(anchor: AnchorElement): boolean {
+  const style = anchor.getAttribute("style") ?? "";
+  return /(?:^|;)\s*display:\s*contents\s*(?:;|$)/i.test(style);
+}
+
+export function installFinderFileLinks(client: PluginClientContext): () => void {
+  if (Platform.OS !== "web") {
+    return () => {};
+  }
+
+  const handleClick = (event: ClickEvent) => {
+    if (
+      event.button !== 0 ||
+      event.altKey ||
+      event.ctrlKey ||
+      event.metaKey ||
+      event.shiftKey
+    ) {
+      return;
+    }
+
+    const anchor = asClickTarget(event.target)?.closest("a[href]");
+    const href = anchor?.getAttribute("href") ?? "";
+    if (!anchor || !isAssistantFileAnchor(anchor) || !isFinderEligibleHref(href)) {
+      return;
+    }
+
+    event.preventDefault();
+    event.stopPropagation();
+    event.stopImmediatePropagation();
+
+    void client
+      .rpc(revealInFinderRpc, {
+        href,
+        ...getRouteContext(location.pathname),
+      })
+      .then((result) => {
+        if (!result.ok) {
+          console.error("[paseo-finder-links] " + result.error);
+        }
+      })
+      .catch((error: unknown) => {
+        console.error("[paseo-finder-links] Failed to reveal file", error);
+      });
+  };
+
+  document.addEventListener("click", handleClick, true);
+  return () => document.removeEventListener("click", handleClick, true);
+}

package/index.client.tsx

@@ -0,0 +1,6 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { installFinderFileLinks } from "./client/web";
+
+export default function contribute(client: PluginClientContext) {
+  return installFinderFileLinks(client);
+}

package/index.server.ts

@@ -0,0 +1,8 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { revealInFinder } from "./server/reveal";
+import { revealInFinderRpc } from "./shared/reveal";
+
+export default function contribute(server: PluginServerContext) {
+  server.handle(revealInFinderRpc, (input, context) => revealInFinder(input, context.paseo));
+  return () => {};
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "paseo-finder-links",
+  "version": "0.1.0",
+  "description": "Reveal local file links from Paseo in Finder or File Explorer.",
+  "author": "Matteo Zampieri",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/themattvision/paseo-finder-links.git"
+  },
+  "homepage": "https://github.com/themattvision/paseo-finder-links#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "paseo",
+    "paseo-plugin",
+    "finder",
+    "file-explorer"
+  ],
+  "type": "module",
+  "files": [
+    "paseo-plugin.json",
+    "index.client.ts",
+    "index.client.tsx",
+    "index.server.ts",
+    "index.server.tsx",
+    "client/",
+    "server/",
+    "shared/"
+  ],
+  "scripts": {
+    "test": "node --experimental-strip-types --test shared/reveal.test.ts server/reveal.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@getpaseo/client": "^0.9.2",
+    "@getpaseo/plugin": "^0.9.2",
+    "@getpaseo/protocol": "^0.9.2",
+    "@tanstack/react-query": "^5.90.11",
+    "@types/node": "^22.20.4",
+    "@types/react": "~19.2.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "^5.9.3",
+    "zod": "^4.4.3"
+  }
+}

package/paseo-plugin.json

@@ -0,0 +1,7 @@
+{
+  "id": "paseo-finder-links",
+  "description": "Reveal local file links in macOS Finder or Windows File Explorer without replacing Paseo's source navigation.",
+  "requirements": {
+    "paseo": ">=0.9.2"
+  }
+}

package/server/reveal.test.ts

@@ -0,0 +1,58 @@
+import assert from "node:assert/strict";
+import { dirname, resolve } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import { buildRevealCommand, hrefToPath, resolveExistingPath } from "./reveal.ts";
+
+const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+test("resolves a relative file inside the active workspace", async () => {
+  const paseo = {
+    workspaces: {
+      ref: () => ({
+        refresh: async () => ({ workspaceDirectory: pluginRoot }),
+      }),
+    },
+  } as unknown as PluginHandlerContext["paseo"];
+
+  const resolved = await resolveExistingPath(
+    { href: "README.md", workspaceId: "test-workspace" },
+    paseo,
+  );
+
+  assert.equal(resolved, resolve(pluginRoot, "README.md"));
+});
+
+test("converts Windows file URLs and UNC shares to native paths", () => {
+  assert.equal(
+    hrefToPath("file:///C:/Users/Matteo/My%20File.zip", "win32"),
+    String.raw`C:\Users\Matteo\My File.zip`,
+  );
+  assert.equal(
+    hrefToPath("file://server/share/My%20File.zip", "win32"),
+    String.raw`\\server\share\My File.zip`,
+  );
+});
+
+test("builds safe native commands without a shell", () => {
+  assert.deepEqual(buildRevealCommand("/tmp/My File.zip", false, "darwin"), {
+    executable: "/usr/bin/open",
+    args: ["-R", "/tmp/My File.zip"],
+  });
+  assert.deepEqual(
+    buildRevealCommand(String.raw`C:\Users\Matteo\My File.zip`, false, "win32"),
+    {
+      executable: "explorer.exe",
+      args: [String.raw`/select,C:\Users\Matteo\My File.zip`],
+    },
+  );
+  assert.deepEqual(buildRevealCommand(String.raw`C:\Users\Matteo\Downloads`, true, "win32"), {
+    executable: "explorer.exe",
+    args: [String.raw`C:\Users\Matteo\Downloads`],
+  });
+  assert.throws(
+    () => buildRevealCommand("/tmp/My File.zip", false, "linux"),
+    /macOS Finder and Windows File Explorer/,
+  );
+});

package/server/reveal.ts

@@ -0,0 +1,123 @@
+import { execFile } 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 { promisify } from "node:util";
+import type { RpcInput, RpcOutput } from "@getpaseo/plugin";
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import { hasSourcePosition, revealInFinderRpc } from "../shared/reveal.ts";
+
+const execFileAsync = promisify(execFile);
+
+type RevealInput = RpcInput<typeof revealInFinderRpc>;
+type RevealOutput = RpcOutput<typeof revealInFinderRpc>;
+type PaseoApi = PluginHandlerContext["paseo"];
+
+function decodePath(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+export function hrefToPath(href: string, platform: NodeJS.Platform = process.platform): string | null {
+  const trimmed = href.trim();
+  if (!trimmed || hasSourcePosition(trimmed)) {
+    return null;
+  }
+
+  if (/^file:/i.test(trimmed)) {
+    try {
+      const url = new URL(trimmed);
+      if (url.protocol !== "file:") {
+        return null;
+      }
+      return fileURLToPath(url, { windows: platform === "win32" });
+    } catch {
+      return null;
+    }
+  }
+
+  const pathOnly = trimmed.split(/[?#]/, 1)[0] ?? "";
+  return decodePath(pathOnly);
+}
+
+async function getWorkspaceRoot(input: RevealInput, paseo: PaseoApi): Promise<string | null> {
+  if (input.agentId) {
+    return (await paseo.agents.ref(input.agentId).refresh())?.agent.cwd ?? null;
+  }
+  if (input.workspaceId) {
+    return (await paseo.workspaces.ref(input.workspaceId).refresh())?.workspaceDirectory ?? null;
+  }
+  return null;
+}
+
+export async function resolveExistingPath(
+  input: RevealInput,
+  paseo: PaseoApi,
+  platform: NodeJS.Platform = process.platform,
+): Promise<string> {
+  const rawPath = hrefToPath(input.href, platform);
+  if (!rawPath) {
+    throw new Error("Il link non contiene un percorso locale valido.");
+  }
+
+  const path = platform === "win32" ? win32 : posix;
+  let filePath: string;
+  if (rawPath === "~" || rawPath.startsWith("~/")) {
+    filePath = path.resolve(homedir(), rawPath.slice(2));
+  } else if (path.isAbsolute(rawPath)) {
+    filePath = path.resolve(rawPath);
+  } else {
+    const workspaceRoot = await getWorkspaceRoot(input, paseo);
+    if (!workspaceRoot) {
+      throw new Error("Non riesco a determinare la cartella del workspace corrente.");
+    }
+    filePath = path.resolve(workspaceRoot, rawPath);
+  }
+
+  await stat(filePath);
+  return filePath;
+}
+
+export interface RevealCommand {
+  executable: string;
+  args: string[];
+}
+
+export function buildRevealCommand(
+  filePath: string,
+  isDirectory: boolean,
+  platform: NodeJS.Platform = process.platform,
+): RevealCommand {
+  if (platform === "darwin") {
+    return { executable: "/usr/bin/open", args: ["-R", filePath] };
+  }
+  if (platform === "win32") {
+    return {
+      executable: "explorer.exe",
+      args: isDirectory ? [filePath] : [`/select,${filePath}`],
+    };
+  }
+  throw new Error("This plugin supports macOS Finder and Windows File Explorer.");
+}
+
+export async function revealInFinder(input: RevealInput, paseo: PaseoApi): Promise<RevealOutput> {
+  try {
+    const filePath = await resolveExistingPath(input, paseo);
+    const fileStats = await stat(filePath);
+    const command = buildRevealCommand(filePath, fileStats.isDirectory());
+    await execFileAsync(command.executable, command.args, { shell: false });
+    return { ok: true, path: filePath };
+  } catch (error) {
+    return {
+      ok: false,
+      error:
+        error instanceof Error
+          ? error.message
+          : "Unable to reveal the path in the system file manager.",
+    };
+  }
+}

package/shared/reveal.test.ts

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { getRouteContext, hasSourcePosition, isFinderEligibleHref } from "./reveal.ts";
+
+test("extracts the active agent or workspace from Paseo routes", () => {
+  assert.deepEqual(getRouteContext("/h/local/agent/agent%201"), { agentId: "agent 1" });
+  assert.deepEqual(getRouteContext("/h/local/workspace/workspace-1/tab/file"), {
+    workspaceId: "workspace-1",
+  });
+  assert.deepEqual(getRouteContext("/settings"), {});
+});
+
+test("keeps source-position links inside Paseo", () => {
+  for (const href of ["src/app.ts:42", "src/app.ts:42:8", "src/app.ts#L42", "src/app.ts(42)"]) {
+    assert.equal(hasSourcePosition(href), true, href);
+    assert.equal(isFinderEligibleHref(href), false, href);
+  }
+});
+
+test("routes plain local files to the native file manager and leaves web links alone", () => {
+  for (const href of [
+    "/Users/matteo/Downloads/archive.zip",
+    "file:///Users/matteo/Downloads/archive.zip",
+    "docs/README.md",
+    "~/Downloads/archive.zip",
+    String.raw`C:\Users\Matteo\Downloads\archive.zip`,
+    "file:///C:/Users/Matteo/Downloads/archive.zip",
+  ]) {
+    assert.equal(isFinderEligibleHref(href), true, href);
+  }
+  for (const href of ["https://example.com/file.zip", "mailto:test@example.com", ""]) {
+    assert.equal(isFinderEligibleHref(href), false, href);
+  }
+});

package/shared/reveal.ts

@@ -0,0 +1,73 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+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 WORD_LINE_SUFFIX = /\s+lines?\s+[0-9]+(?:-[0-9]+)?$/i;
+
+export const revealInFinderRpc = defineRpc({
+  name: "finder-links.reveal",
+  input: z.object({
+    href: z.string().min(1).max(16_384),
+    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() }),
+    z.object({ ok: z.literal(false), error: z.string() }),
+  ]),
+});
+
+export interface RouteContext {
+  agentId?: string;
+  workspaceId?: string;
+}
+
+function decodeSegment(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+export function getRouteContext(pathname: string): RouteContext {
+  const pathOnly = pathname.split(/[?#]/, 1)[0] ?? "";
+  const agentMatch = pathOnly.match(/^\/h\/[^/]+\/agent\/([^/]+)(?:\/|$)/);
+  if (agentMatch?.[1]) {
+    return { agentId: decodeSegment(agentMatch[1]) };
+  }
+
+  const workspaceMatch = pathOnly.match(/^\/h\/[^/]+\/workspace\/([^/]+)(?:\/|$)/);
+  if (workspaceMatch?.[1]) {
+    return { workspaceId: decodeSegment(workspaceMatch[1]) };
+  }
+
+  return {};
+}
+
+export function hasSourcePosition(href: string): boolean {
+  const trimmed = href.trim();
+  const hashIndex = trimmed.lastIndexOf("#");
+  if (hashIndex >= 0 && LINE_FRAGMENT.test(trimmed.slice(hashIndex))) {
+    return true;
+  }
+  const withoutHash = hashIndex >= 0 ? trimmed.slice(0, hashIndex) : trimmed;
+  return (
+    COLON_LINE_SUFFIX.test(withoutHash) ||
+    PAREN_LINE_SUFFIX.test(withoutHash) ||
+    WORD_LINE_SUFFIX.test(withoutHash)
+  );
+}
+
+export function isFinderEligibleHref(href: string): boolean {
+  const trimmed = href.trim();
+  if (!trimmed || hasSourcePosition(trimmed)) {
+    return false;
+  }
+  if (/^(?:https?|mailto|tel|data|javascript):/i.test(trimmed)) {
+    return false;
+  }
+  return true;
+}