@devframes/service-open 0.9.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Anthony Fu <https://github.com/antfu>
+
+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/dist/index.d.mts

@@ -0,0 +1,66 @@
+import { KnownEditor } from "devframe/recipes/common-rpc-functions";
+import { DevframeServiceDefinition } from "devframe/types";
+//#region src/index.d.ts
+declare const OPEN_SERVICE_PACKAGE = "@devframes/service-open";
+declare const OPEN_SERVICE_SCOPE = "devframes:service:open";
+interface OpenServiceOptions {
+  /**
+   * Preferred editor command — one of the `KNOWN_EDITORS` `launch-editor`
+   * recognizes. Auto-detected (via `LAUNCH_EDITOR` and common defaults)
+   * when omitted. On merge, the later installer's choice wins.
+   */
+  editor?: KnownEditor;
+  /**
+   * Additional directories files may be opened from, on top of the
+   * context's `workspaceRoot` — e.g. a plugin's managed storage dir that
+   * lives outside the workspace. Merged as a union across installers.
+   */
+  roots?: string[];
+}
+interface OpenInEditorInput {
+  /**
+   * File to open — absolute, or relative to the service's `workspaceRoot`
+   * (so a client with only a workspace-relative path, e.g. a message's file
+   * position, can call this directly without a server-side bridge).
+   */
+  path: string;
+  line?: number;
+  column?: number;
+  /** Per-call editor override (one of `KNOWN_EDITORS`). */
+  editor?: KnownEditor;
+}
+interface OpenServiceApi {
+  /** Open a file (optionally at a line/column) in the user's editor. */
+  openInEditor: (input: OpenInEditorInput) => Promise<void>;
+  /** Reveal a path in the OS file explorer. */
+  openInFinder: (input: {
+    path: string;
+  }) => Promise<void>;
+}
+declare module 'devframe' {
+  interface DevframeRpcServerFunctions {
+    'devframes:service:open:open-in-editor': (input: OpenInEditorInput) => Promise<void>;
+    'devframes:service:open:open-in-finder': (input: {
+      path: string;
+    }) => Promise<void>;
+  }
+  interface DevframeServicesRegistry {
+    '@devframes/service-open': OpenServiceApi;
+  }
+  interface DevframeServicesScopeRegistry {
+    '@devframes/service-open': 'devframes:service:open';
+  }
+}
+/**
+ * The open wire service — `open-in-editor` / `open-in-finder` RPC shared by
+ * every plugin on the host, replacing per-plugin registrations of the
+ * (deprecated) `devframe/recipes/common-rpc-functions` recipes. Paths may be
+ * absolute or relative to the `workspaceRoot`; the service refuses paths
+ * outside the workspace root and the configured extra
+ * {@link OpenServiceOptions.roots} (`DS_OPEN_0002`), and gates editor
+ * commands to the `KNOWN_EDITORS` picklist so the RPC surface can't spawn an
+ * arbitrary command.
+ */
+declare function createOpenService(options?: OpenServiceOptions): DevframeServiceDefinition<OpenServiceApi, OpenServiceOptions>;
+//#endregion
+export { OPEN_SERVICE_PACKAGE, OPEN_SERVICE_SCOPE, OpenInEditorInput, OpenServiceApi, OpenServiceOptions, createOpenService, createOpenService as default };

package/dist/index.mjs

@@ -0,0 +1,90 @@
+import { defineRpcFunction } from "devframe";
+import { KNOWN_EDITORS } from "devframe/recipes/common-rpc-functions";
+import { s } from "devframe/utils/simple-schema";
+import { isAbsolute, relative, resolve } from "pathe";
+import { defineDiagnostics } from "devframe/utils/nostics";
+//#region package.json
+var version = "0.9.0";
+//#endregion
+//#region src/diagnostics.ts
+const diagnostics = defineDiagnostics({
+	docsBase: "https://devfra.me/errors",
+	codes: { DS_OPEN_0002: {
+		why: (p) => `Refusing to open "${p.path}": the path is outside the workspace root and every configured extra root.`,
+		fix: "The open service only touches files under the workspace root by default. Pass additional allowed directories via the service's `roots` option when your tool manages files elsewhere (e.g. a global storage dir)."
+	} }
+});
+//#endregion
+//#region src/index.ts
+const OPEN_SERVICE_PACKAGE = "@devframes/service-open";
+const OPEN_SERVICE_SCOPE = "devframes:service:open";
+/**
+* The open wire service — `open-in-editor` / `open-in-finder` RPC shared by
+* every plugin on the host, replacing per-plugin registrations of the
+* (deprecated) `devframe/recipes/common-rpc-functions` recipes. Paths may be
+* absolute or relative to the `workspaceRoot`; the service refuses paths
+* outside the workspace root and the configured extra
+* {@link OpenServiceOptions.roots} (`DS_OPEN_0002`), and gates editor
+* commands to the `KNOWN_EDITORS` picklist so the RPC surface can't spawn an
+* arbitrary command.
+*/
+function createOpenService(options) {
+	return {
+		package: OPEN_SERVICE_PACKAGE,
+		version,
+		scope: OPEN_SERVICE_SCOPE,
+		options,
+		setup(ctx, { options }) {
+			const allowedRoots = [ctx.workspaceRoot, ...options?.roots ?? []].map((root) => resolve(root));
+			/**
+			* Resolve `path` (relative paths against `workspaceRoot`) and assert it
+			* lands inside one of the allowed roots, or throw.
+			*/
+			function assertAllowedPath(path) {
+				const resolved = isAbsolute(path) ? resolve(path) : resolve(ctx.workspaceRoot, path);
+				if (!allowedRoots.some((root) => {
+					const rel = relative(root, resolved);
+					return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+				})) throw diagnostics.DS_OPEN_0002({ path });
+				return resolved;
+			}
+			const api = {
+				async openInEditor(input) {
+					const path = assertAllowedPath(input.path);
+					const target = input.line != null ? `${path}:${input.line}${input.column != null ? `:${input.column}` : ""}` : path;
+					const { launchEditor } = await import("devframe/utils/launch-editor");
+					launchEditor(target, input.editor ?? options?.editor);
+				},
+				async openInFinder(input) {
+					const path = assertAllowedPath(input.path);
+					const { open } = await import("devframe/utils/open");
+					await open(path);
+				}
+			};
+			ctx.rpc.register(defineRpcFunction({
+				name: "open-in-editor",
+				type: "action",
+				jsonSerializable: true,
+				args: [s.object({
+					path: s.string(),
+					line: s.optional(s.number()),
+					column: s.optional(s.number()),
+					editor: s.optional(s.picklist(KNOWN_EDITORS))
+				})],
+				returns: s.void(),
+				handler: (input) => api.openInEditor(input)
+			}));
+			ctx.rpc.register(defineRpcFunction({
+				name: "open-in-finder",
+				type: "action",
+				jsonSerializable: true,
+				args: [s.object({ path: s.string() })],
+				returns: s.void(),
+				handler: (input) => api.openInFinder(input)
+			}));
+			return api;
+		}
+	};
+}
+//#endregion
+export { OPEN_SERVICE_PACKAGE, OPEN_SERVICE_SCOPE, createOpenService, createOpenService as default };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@devframes/service-open",
+  "type": "module",
+  "version": "0.9.0",
+  "description": "Devframe wire service that opens files in the user's editor or reveals them in the OS file explorer.",
+  "author": "Anthony Fu <anthonyfu117@hotmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/devframes/devframe#readme",
+  "repository": {
+    "directory": "services/open",
+    "type": "git",
+    "url": "git+https://github.com/devframes/devframe.git"
+  },
+  "bugs": "https://github.com/devframes/devframe/issues",
+  "keywords": [
+    "devframe",
+    "devframe-service",
+    "devtools",
+    "open-in-editor"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "devframe": "0.9.1"
+  },
+  "dependencies": {
+    "pathe": "^2.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "tsdown": "^0.22.14",
+    "vitest": "^4.1.10",
+    "devframe": "0.9.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}