feat: migrate messages and assets onto the wire services

- messages: drops its commonRpcFunctions registration for a
  devframes:plugin:messages:open-file bridge that resolves
  workspace-relative file positions server-side and delegates to
  @devframes/service-open (declared in the definition's services); the
  panel gates its affordance on the service advertisement
- assets: open-in-editor / reveal-in-folder delegate to service-open,
  installed at setup with the managed dir as an extra allowed root; the
  SPA hides both buttons until the service is advertised, and text-asset
  previews render server-highlighted through @devframes/service-shiki
  (declared optional) with the plain <pre> as fallback
- docs + skill point at the service over the deprecated recipes

Author: antfubot

docs/helpers/common-rpc-functions.md

@@ -4,6 +4,9 @@ outline: deep
 
 # Common RPC Functions
 
+> [!WARNING]
+> Deprecated in favor of the [`@devframes/service-open` wire service](/guide/services#built-in-services) — one host-level installation shared by every plugin, feature-detectable from clients, with workspace-root path containment on top of the editor gating. The recipe keeps working; removal lands in a future major.
+
 Prebuilt RPC actions for the two file-system actions every CLI devtool needs — opening a file in the editor, revealing a path in the OS file explorer. Use the recipe instead of re-implementing them so every devframe converges on the same registered names and payload shape.
 
 ```ts

docs/plugins/assets.md

@@ -95,12 +95,12 @@ All functions are namespaced `devframes:plugin:assets:*`:
 | `list` | `query`, `snapshot: true` | Every file under the managed directory, with type, size, and last-modified time. |
 | `capabilities` | `query`, `snapshot: true` | Whether write actions are enabled, and the upload allow-list — lets the UI gate itself proactively. |
 | `read-image-meta` | `query` | Width, height, and orientation for an image asset. |
-| `read-text` | `query` | Truncated text content, for preview. |
+| `read-text` | `query` | Truncated text content, for preview. When the host advertises the [`@devframes/service-shiki` wire service](/guide/services#built-in-services), the panel renders it server-highlighted; otherwise it falls back to a plain `<pre>`. |
 | `upload` | `action` | Allocates a streaming upload slot; the client pipes the file's bytes over the paired channel. |
 | `rename` | `action` | Renames an asset within its folder, preserving its extension. |
 | `delete` | `action` | Deletes one or more assets in a single call. |
 | `mkdir` | `action` | Creates a folder, including missing parents. |
-| `open-in-editor` / `reveal-in-folder` | `action` | Launch the asset in your editor, or reveal its containing folder in the OS file manager. Always registered, regardless of `write`. |
+| `open-in-editor` / `reveal-in-folder` | `action` | Launch the asset in your editor, or reveal its containing folder in the OS file manager, delegating to the [`@devframes/service-open` wire service](/guide/services#built-in-services) (installed by the plugin with the managed dir as an allowed root). Always registered, regardless of `write`. |
 
 `upload` / `rename` / `delete` / `mkdir` are registered only when `write` is enabled.
 

plugins/assets/package.json

@@ -48,18 +48,23 @@
   },
   "peerDependencies": {
     "@devframes/plugin-assets--assets": "workspace:*",
+    "@devframes/service-shiki": "workspace:*",
     "devframe": "workspace:*",
     "vite": "^7.0.0 || ^8.0.0"
   },
   "peerDependenciesMeta": {
     "@devframes/plugin-assets--assets": {
       "optional": true
     },
+    "@devframes/service-shiki": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     }
   },
   "dependencies": {
+    "@devframes/service-open": "workspace:*",
     "cac": "catalog:deps",
     "chokidar": "catalog:deps",
     "image-meta": "catalog:deps",
@@ -71,6 +76,7 @@
   "devDependencies": {
     "@antfu/design": "catalog:frontend",
     "@devframes/plugin-assets--assets": "workspace:*",
+    "@devframes/service-shiki": "workspace:*",
     "@devframes/vite": "workspace:*",
     "@iconify-json/ph": "catalog:frontend",
     "@storybook/addon-a11y": "catalog:storybook",

plugins/assets/src/diagnostics.ts

@@ -34,5 +34,9 @@ export const diagnostics = defineDiagnostics({
       why: 'The upload streaming channel is unavailable because this devframe was set up with `write: false`.',
       fix: 'This indicates an internal registration bug — `upload` should never be reachable without `write: true`. Please report it.',
     },
+    DP_ASSETS_0008: {
+      why: 'Cannot open the asset: the "@devframes/service-open" wire service is not installed on this host.',
+      fix: 'Install the service package next to the assets plugin (it installs it during setup), or install it host-side via `ctx.services.install(createOpenService())`.',
+    },
   },
 })

plugins/assets/src/index.ts

@@ -124,9 +124,20 @@ export function createAssetsDevframe(options: AssetsDevframeOptions = {}): Devfr
       },
     },
     dock: { category: '~builtin' },
+    // Server-highlighted text previews; the SPA falls back to a plain
+    // `<pre>` when the service isn't advertised.
+    services: [{ package: '@devframes/service-shiki' }],
     async setup(ctx, info) {
       const readOnlyFlag = info?.flags?.readOnly === true
       const dir = options.dir ? resolve(ctx.cwd, options.dir) : resolve(ctx.cwd, 'public')
+      // Backs open-in-editor / reveal-in-folder. Installed here (not in the
+      // declarative `services` list) because the managed dir — contributed
+      // as an extra allowed root, since it may live outside the workspace —
+      // is only known at setup time.
+      void ctx.services.install(
+        { package: '@devframes/service-open', options: { roots: [dir] } },
+        { resolveFrom: pkg.name },
+      )
       await setupAssets(ctx, {
         dir,
         write: readOnlyFlag ? false : write,

plugins/assets/src/rpc/functions/open-in-editor.ts

@@ -1,16 +1,17 @@
 import type { DevframeNodeContext } from 'devframe'
+import { OPEN_SERVICE_PACKAGE } from '@devframes/service-open'
 import { createDefineWrapperWithContext } from 'devframe/rpc'
-import { launchEditor } from 'devframe/utils/launch-editor'
 import { s } from 'devframe/utils/simple-schema'
+import { diagnostics } from '../../diagnostics'
 import { getAssetsContext } from '../../node/context'
 
 const defineAssetsRpc = createDefineWrapperWithContext<DevframeNodeContext>()
 
 /**
- * Reuses devframe's `launchEditor` utility (the same one backing the core
- * `devframe:open-in-editor` recipe) but resolves the path against the
- * managed directory first, so the client only ever sends a root-relative
- * path — never the server's absolute filesystem layout.
+ * Delegates to the `@devframes/service-open` wire service (installed by the
+ * plugin's setup with the managed dir as an allowed root), resolving the
+ * path against the managed directory first — so the client only ever sends
+ * a root-relative path, never the server's absolute filesystem layout.
  */
 export const openInEditor = defineAssetsRpc({
   name: 'devframes:plugin:assets:open-in-editor',
@@ -29,7 +30,10 @@ export const openInEditor = defineAssetsRpc({
     return {
       // See `list.ts` for why the async handler is cast.
       handler: (async (path: string): Promise<void> => {
-        launchEditor(assets.resolvePath(path))
+        const open = ctx.services.get(OPEN_SERVICE_PACKAGE)
+        if (!open)
+          throw diagnostics.DP_ASSETS_0008()
+        await open.openInEditor({ path: assets.resolvePath(path) })
       }) as any,
     }
   },

plugins/assets/src/rpc/functions/reveal-in-folder.ts

@@ -1,17 +1,18 @@
 import type { DevframeNodeContext } from 'devframe'
+import { OPEN_SERVICE_PACKAGE } from '@devframes/service-open'
 import { createDefineWrapperWithContext } from 'devframe/rpc'
-import { open } from 'devframe/utils/open'
 import { s } from 'devframe/utils/simple-schema'
 import { dirname } from 'pathe'
+import { diagnostics } from '../../diagnostics'
 import { getAssetsContext } from '../../node/context'
 
 const defineAssetsRpc = createDefineWrapperWithContext<DevframeNodeContext>()
 
 /**
- * Reuses devframe's `open` utility (the same one backing the core
- * `devframe:open-in-finder` recipe), opening the asset's containing folder
- * so it's revealed in the OS file manager rather than launched with its
- * default app (which `download` already covers).
+ * Delegates to the `@devframes/service-open` wire service's `openInFinder`,
+ * opening the asset's containing folder so it's revealed in the OS file
+ * manager rather than launched with its default app (which `download`
+ * already covers).
  */
 export const revealInFolder = defineAssetsRpc({
   name: 'devframes:plugin:assets:reveal-in-folder',
@@ -30,7 +31,10 @@ export const revealInFolder = defineAssetsRpc({
     return {
       // See `list.ts` for why the async handler is cast.
       handler: (async (path: string): Promise<void> => {
-        await open(dirname(assets.resolvePath(path)))
+        const open = ctx.services.get(OPEN_SERVICE_PACKAGE)
+        if (!open)
+          throw diagnostics.DP_ASSETS_0008()
+        await open.openInFinder({ path: dirname(assets.resolvePath(path)) })
       }) as any,
     }
   },

plugins/assets/src/spa/app/components/AssetDetails.vue

@@ -7,6 +7,7 @@ import FormTextInput from '@antfu/design/components/Form/FormTextInput.vue'
 import OverlayModal from '@antfu/design/components/Overlay/OverlayModal.vue'
 import { computed, ref, watch } from 'vue'
 import { fileNameOf, formatFileSize, formatTimeAgo } from '../utils/format'
+import { highlightAsset } from '../utils/highlight'
 import { buildSnippets } from '../utils/snippets'
 import AssetPreview from './AssetPreview.vue'
 import CodeSnippets from './CodeSnippets.vue'
@@ -23,6 +24,7 @@ const SUPPORTS_PREVIEW = new Set(['image', 'text', 'video', 'audio', 'font'])
 
 const imageMeta = ref<AssetImageMeta | null>(null)
 const textContent = ref<string | null>(null)
+const highlightedHtml = ref<string | null>(null)
 const deleteOpen = ref(false)
 const renameOpen = ref(false)
 const newName = ref('')
@@ -32,14 +34,38 @@ const errorNotice = ref<string | null>(null)
 watch(() => props.asset.path, (path) => {
   imageMeta.value = null
   textContent.value = null
+  highlightedHtml.value = null
   errorNotice.value = null
   const rpc = props.rpc
   if (!rpc)
     return
   if (props.asset.type === 'image')
     void rpc.call('devframes:plugin:assets:read-image-meta', path).then((m) => { imageMeta.value = m })
-  if (props.asset.type === 'text')
-    void rpc.call('devframes:plugin:assets:read-text', path, 5000).then((c) => { textContent.value = c })
+  if (props.asset.type === 'text') {
+    void rpc.call('devframes:plugin:assets:read-text', path, 5000).then(async (c) => {
+      textContent.value = c
+      // Server-highlighted preview via the shiki wire service; `null` when
+      // it isn't advertised — the preview keeps its plain `<pre>`.
+      const html = c == null ? null : await highlightAsset(rpc, path, c)
+      if (props.asset.path === path)
+        highlightedHtml.value = html
+    })
+  }
+}, { immediate: true })
+
+// The open/reveal affordances delegate to the `@devframes/service-open`
+// wire service; hide them until the host advertises it.
+const openServiceAvailable = ref(false)
+watch(() => props.rpc, (rpc) => {
+  if (!rpc)
+    return
+  openServiceAvailable.value = rpc.services.has('@devframes/service-open')
+  rpc.services.state()
+    .then((state) => {
+      openServiceAvailable.value = rpc.services.has('@devframes/service-open')
+      state.on('updated', () => (openServiceAvailable.value = rpc.services.has('@devframes/service-open')))
+    })
+    .catch(() => {})
 }, { immediate: true })
 
 function gcd(a: number, b: number): number {
@@ -127,6 +153,7 @@ function openInBrowser(): void {
         :asset="asset"
         detail
         :text-content="textContent"
+        :highlighted-html="highlightedHtml"
         class="max-h-80 min-h-20 w-auto min-w-20 rounded border border-base"
       />
     </div>
@@ -192,10 +219,10 @@ function openInBrowser(): void {
       <ActionButton variant="primary" icon="i-ph-download-simple-duotone" @click="openInBrowser">
         Download
       </ActionButton>
-      <ActionButton icon="i-ph-code-duotone" :disabled="busy" @click="handleOpenInEditor">
+      <ActionButton v-if="openServiceAvailable" icon="i-ph-code-duotone" :disabled="busy" @click="handleOpenInEditor">
         Open in Editor
       </ActionButton>
-      <ActionButton icon="i-ph-folder-open-duotone" :disabled="busy" @click="handleRevealInFolder">
+      <ActionButton v-if="openServiceAvailable" icon="i-ph-folder-open-duotone" :disabled="busy" @click="handleRevealInFolder">
         Reveal in Folder
       </ActionButton>
       <ActionButton v-if="canWrite" icon="i-ph-text-aa-duotone" @click="openRenameDialog">

plugins/assets/src/spa/app/components/AssetPreview.vue

@@ -5,6 +5,11 @@ import FontPreview from './FontPreview.vue'
 defineProps<{
   asset: AssetInfo
   textContent?: string | null
+  /**
+   * Server-highlighted HTML for text assets (from the `@devframes/service-shiki`
+   * wire service); the plain `textContent` `<pre>` is the fallback.
+   */
+  highlightedHtml?: string | null
   /** Larger, interactive preview (autoplay/controls) for the details panel. */
   detail?: boolean
 }>()
@@ -21,6 +26,15 @@ const BASE = 'flex items-center justify-center overflow-hidden bg-active p-1'
     <FontPreview :asset="asset" class="self-stretch p-2 text-2xl" />
   </div>
 
+  <!-- Shiki output is server-generated from server-read content over the
+       trusted devframe RPC (shiki escapes the code itself), so direct
+       injection matches the repo's handling of self-generated markup. -->
+  <div
+    v-else-if="asset.type === 'text' && highlightedHtml"
+    class="asset-code-preview w-full items-start p-4"
+    :class="BASE"
+    v-html="highlightedHtml"
+  />
   <div v-else-if="asset.type === 'text' && textContent" class="w-full items-start p-4" :class="BASE">
     <pre class="max-h-40 w-full overflow-hidden text-xs font-mono">{{ textContent }}</pre>
   </div>
@@ -41,3 +55,24 @@ const BASE = 'flex items-center justify-center overflow-hidden bg-active p-1'
     <span class="i-ph-file-duotone text-3xl op-mute" />
   </div>
 </template>
+
+<!-- Unscoped: `v-html` content is invisible to scoped styles. The dark rules
+     are Shiki's standard dual-theme toggle (`--shiki-dark` variables). -->
+<style>
+.asset-code-preview pre {
+  margin: 0;
+  max-height: 10rem;
+  width: 100%;
+  overflow: hidden;
+  font-size: 0.75rem;
+  line-height: 1rem;
+  background-color: transparent !important;
+}
+.dark .asset-code-preview .shiki,
+.dark .asset-code-preview .shiki span {
+  color: var(--shiki-dark) !important;
+  font-style: var(--shiki-dark-font-style) !important;
+  font-weight: var(--shiki-dark-font-weight) !important;
+  text-decoration: var(--shiki-dark-text-decoration) !important;
+}
+</style>

plugins/assets/src/spa/app/utils/highlight.ts

@@ -0,0 +1,27 @@
+// Types-only: loads the service's RPC/scope augmentations so the scoped
+// `call('highlight', …)` below is fully typed.
+import type {} from '@devframes/service-shiki'
+import type { DevframeRpcClient } from 'devframe/client'
+
+const SHIKI_SERVICE = '@devframes/service-shiki'
+
+/**
+ * Server-highlight a text asset through the `@devframes/service-shiki` wire
+ * service, when the host advertises it. Resolves `null` when the service is
+ * absent or highlighting fails — the preview then falls back to a plain
+ * `<pre>`. The language is inferred from the file extension; unknown ones
+ * degrade to plain text server-side.
+ */
+export async function highlightAsset(rpc: DevframeRpcClient, path: string, code: string): Promise<string | null> {
+  const shiki = rpc.services.get(SHIKI_SERVICE)
+  if (!shiki)
+    return null
+  const lang = /\.([^./\\]+)$/.exec(path)?.[1]?.toLowerCase()
+  try {
+    const { html } = await shiki.rpc.call('highlight', { code, lang })
+    return html
+  }
+  catch {
+    return null
+  }
+}