@khorsheed/dsh-file-preview 0.2.0 → 0.3.1

package/lib/types/index.js

@@ -35,64 +35,12 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import z from '@deepseek-ai/schemastery';
 import { BashWriteCollector } from './bash-writes.js';
 import { foldFilePreview, foldFilePreviewByTurn } from './fold.js';
+import { openExternalNative, macAppName } from './open-external.js';
 import { revealNativePath } from './reveal.js';
-/**
- * Register the 3d-artifact skill — the generation-side contract for
- * sandbox-runnable interactive 3D / digital-twin single-file HTML (self-
- * contained, zero runtime network, GLB-inline zero-fetch models). Pull-based
- * discovery: an agent whose task involves generating such an HTML page finds
- * the contract through the skill catalog — no per-session push notice.
- * Optional: compositions without the skill capability skip the registration.
- * A missing/malformed shipped SKILL.md degrades to a warning — a discovery
- * aid must never take a boot down; the pack-smoke test owns the file's
- * presence in the tarball.
- * @param ctx - plugin context.
- */
-function registerArtifactSkill(ctx) {
-    const skills = ctx.get('skills');
-    if (skills === undefined) {
-        // Not a crash: file preview degrades without the skill (and a minimal
-        // composition may legitimately lack the capability). The line exists so a
-        // host-API migration that drops or renames the skills service shows up in
-        // boot logs instead of failing silently — same diagnostic as ankh-guard's
-        // restart-skill registration; grep "skill .* not registered".
-        ctx.logger.warn('file-preview: skills capability absent — the 3d-artifact skill is not registered');
-        return;
-    }
-    try {
-        const skillDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', '3d-artifact');
-        const skillFile = join(skillDir, 'SKILL.md');
-        const raw = readFileSync(skillFile, 'utf8');
-        const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(raw);
-        const name = /^name: (.+)$/m.exec(match?.[1] ?? '')?.[1]?.trim();
-        const description = /^description: (.+)$/m.exec(match?.[1] ?? '')?.[1]?.trim();
-        const content = match?.[2];
-        if (match === null || name === undefined || description === undefined || content === undefined) {
-            ctx.logger.warn('file-preview: shipped SKILL.md is malformed — the 3d-artifact skill is not registered');
-            return;
-        }
-        ctx.effect(() => skills.register({
-            name,
-            description,
-            content,
-            source: 'runtime',
-            provider: 'file-preview',
-            // Content-only (only SKILL.md in the bundle): no `resourceBase`, so the
-            // catalog renders a virtual single-SKILL.md node. Add `resourceBase`
-            // only when the bundle later gains scripts/assets beside SKILL.md.
-        }));
-    }
-    catch (error) {
-        ctx.logger.warn(`file-preview: shipped SKILL.md unreadable (${String(error)}) — the 3d-artifact skill is not registered`);
-    }
-}
 /** Extensions treated as binary without reading (their text decode is meaningless). */
 const BINARY_EXTENSIONS = new Set([
     '.pdf', '.zip', '.gz', '.tar', '.7z', '.zstd', '.br',
@@ -121,6 +69,10 @@ const IMAGE_MIME = {
 function hasNulByte(content) {
     return content.slice(0, 4096).includes('\u0000');
 }
+/** Shared non-fatal UTF-8 decoder for the bounded byte-window read: invalid
+ * sequences become U+FFFD (a cut multi-byte character at the window edge
+ * included) instead of failing the read. */
+const utf8Decoder = new TextDecoder();
 /** Detect a binary file from its display path extension. */
 function isBinaryPath(path) {
     const dot = path.lastIndexOf('.');
@@ -165,21 +117,27 @@ function readErrorMessage(error) {
 let FilePreviewService = (() => {
     let _classSuper = TypertRemoteService;
     let _instanceExtraInitializers = [];
+    let _capabilities_decorators;
     let _list_decorators;
     let _turnFiles_decorators;
     let _read_decorators;
     let _reveal_decorators;
+    let _openExternal_decorators;
     return class FilePreviewService extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _capabilities_decorators = [Remote('capabilities')];
             _list_decorators = [Remote('list')];
             _turnFiles_decorators = [Remote('turnFiles')];
             _read_decorators = [Remote('read')];
             _reveal_decorators = [Remote('reveal')];
+            _openExternal_decorators = [Remote('openExternal')];
+            __esDecorate(this, null, _capabilities_decorators, { kind: "method", name: "capabilities", static: false, private: false, access: { has: obj => "capabilities" in obj, get: obj => obj.capabilities }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _list_decorators, { kind: "method", name: "list", static: false, private: false, access: { has: obj => "list" in obj, get: obj => obj.list }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _turnFiles_decorators, { kind: "method", name: "turnFiles", static: false, private: false, access: { has: obj => "turnFiles" in obj, get: obj => obj.turnFiles }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _read_decorators, { kind: "method", name: "read", static: false, private: false, access: { has: obj => "read" in obj, get: obj => obj.read }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _reveal_decorators, { kind: "method", name: "reveal", static: false, private: false, access: { has: obj => "reveal" in obj, get: obj => obj.reveal }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _openExternal_decorators, { kind: "method", name: "openExternal", static: false, private: false, access: { has: obj => "openExternal" in obj, get: obj => obj.openExternal }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         static inject = ['fs'];
@@ -199,6 +157,8 @@ let FilePreviewService = (() => {
         agents;
         /** Native reveal runner; a constructor seam for deterministic tests. */
         revealNative;
+        /** Native open-in-app runner; a constructor seam for deterministic tests. */
+        openExternalNative;
         /** Bash-write collector (S2 seam), or undefined when disabled in config. */
         collector;
         /** Per-session by-turn fold cache, invalidated by the log watermark. */
@@ -219,6 +179,7 @@ let FilePreviewService = (() => {
                 captureBashWrites: config.captureBashWrites ?? true,
             };
             this.revealNative = deps.revealNative ?? revealNativePath;
+            this.openExternalNative = deps.openExternalNative ?? openExternalNative;
             if (config.captureBashWrites !== false) {
                 this.collector = new BashWriteCollector({ fs: this.fs, maxFiles: this.resolved.maxFiles });
                 ctx.effect(() => this.collector.attach(ctx), 'file-preview: bash-write capture');
@@ -239,7 +200,10 @@ let FilePreviewService = (() => {
                     handler: (req, res) => { void this.serveImage(req, res); },
                 }), 'file-preview: image route');
             }
-            registerArtifactSkill(ctx);
+        }
+        /** Zero-session availability handshake for browser companions. */
+        capabilities() {
+            return { protocolVersion: 1 };
         }
         get fs() {
             return this.ctx.fs;
@@ -385,7 +349,7 @@ let FilePreviewService = (() => {
         /**
          * Every turn's file mutations for the turn-tail card — the single source of
          * truth the card renders (the client's old write/edit-only fold retired).
-         * Built by folding the session log per turn (write/edit calls, Code Mode
+         * Built by folding the session log per turn (write/edit calls, PTC
          * dispatches borrowing the root call's turn, and render-intent paths from
          * result diff meta) and merging the collector's bash-written captures by
          * their own turn. The fold is cached per session and invalidated by the log
@@ -446,7 +410,10 @@ let FilePreviewService = (() => {
         }
         /**
          * Read the current content of one recorded file, resolved against the
-         * session cwd and capped by `maxReadBytes`.
+         * session cwd and capped by `maxReadBytes`. The text read is a bounded byte
+         * window (`readByteRange` of cap + 1 bytes), so an oversized file costs the
+         * cap, never its full size; a known oversized stat still short-circuits to
+         * `too-large` before any bytes move.
          * @param agent - owning live agent; its session cwd anchors relative paths.
          * @param path - the display path recorded by the write/edit tool call.
          * @param signal - cooperative cancellation from the calling UI request.
@@ -500,15 +467,18 @@ let FilePreviewService = (() => {
                 return { path, kind: 'binary', ...(info.size === undefined ? {} : { size: info.size }) };
             }
             try {
-                const content = await this.fs.readText(target, signal);
+                // Bounded by the window, not the file: at most cap + 1 bytes are
+                // transferred (the extra byte decides `truncated`), never the whole file.
+                const bytes = await this.fs.readByteRange(target, { offset: 0, length: cap + 1 }, signal);
+                const truncated = bytes.length > cap;
+                const content = utf8Decoder.decode(truncated ? bytes.subarray(0, cap) : bytes);
                 if (hasNulByte(content)) {
                     return { path, kind: 'binary', ...(info.size === undefined ? {} : { size: info.size }) };
                 }
-                const truncated = content.length > cap;
                 return {
                     path,
                     kind: 'text',
-                    content: truncated ? content.slice(0, cap) : content,
+                    content,
                     truncated,
                     ...(html && isScriptedHtml(content) ? { htmlScripted: true } : {}),
                     ...(info.size === undefined ? {} : { size: info.size }),
@@ -567,6 +537,53 @@ let FilePreviewService = (() => {
                 return { revealed: false, reason: 'select-failed' };
             }
         }
+        /**
+         * Open one recorded file in a specific host application (the "open in IDE"
+         * gesture). The official open-in-app route only accepts directories — a
+         * file path 404s — so file-exact opens go through this method: macOS
+         * `open -a <App> <path>` via the same native-command runner reveal uses.
+         * The browser names the application by official open-in-app catalog id
+         * (probed from `/open-in-app/apps`); the id → app-name map lives in
+         * open-external.ts. Non-macOS hosts and unknown ids answer without
+         * launching, and the client hides the gesture.
+         * @param agent - owning live agent; its session cwd anchors relative paths.
+         * @param path - the display path recorded by the read/write/edit tool call.
+         * @param app - official open-in-app catalog id (e.g. `cursor`).
+         * @param signal - cooperative cancellation from the calling UI request.
+         * @returns whether the application launched, or why not.
+         */
+        async openExternal(agent, path, app, signal) {
+            if (typeof path !== 'string' || path.length === 0 || typeof app !== 'string' || app.length === 0) {
+                return { opened: false, reason: 'missing' };
+            }
+            if (macAppName(app) === undefined)
+                return { opened: false, reason: 'unknown-app' };
+            const cwd = agent.session.header.cwd;
+            let target;
+            try {
+                target = await this.fs.resolve(path, cwd === undefined ? { signal } : { cwd, signal });
+            }
+            catch {
+                return { opened: false, reason: 'missing' };
+            }
+            let info;
+            try {
+                info = await this.fs.stat(target, signal);
+            }
+            catch {
+                info = undefined;
+            }
+            if (info === undefined)
+                return { opened: false, reason: 'missing' };
+            try {
+                await this.openExternalNative(this.fs.processPath(target), app, signal);
+                return { opened: true };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return { opened: false, reason: message.startsWith('open-in-app is unsupported on ') ? 'unsupported-platform' : 'launch-failed' };
+            }
+        }
     };
 })();
 export { FilePreviewService };

package/lib/types/open-external.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Native "open this file in a specific application" dispatch used by the
+ * file-preview Remote's `openExternal` method (the "open in IDE" gesture).
+ *
+ * The official open-in-app route (`POST /open-in-app/open`) only accepts
+ * directories — a file path 404s — so file-exact opens carry their own
+ * dispatch here. macOS only: `open -a <App> <path>` through the official
+ * `@deepseek-ai/dsh-native-command` runner (no shell, abort propagation),
+ * mirroring `reveal.ts`'s discipline. The browser picks the application by
+ * official open-in-app catalog id (probed from `/open-in-app/apps`); the
+ * id → `.app` name map below mirrors the official catalog's darwin entries
+ * (packages/host/open-in-app/src/catalog.ts at 0.1.5-rc.1 — re-check on every
+ * host upgrade). Other platforms and unknown ids answer unsupported, and the
+ * client hides the gesture.
+ * @module @khorsheed/dsh-file-preview
+ */
+import { type NativeCommandRunner } from '@deepseek-ai/dsh-native-command';
+/** Injectable platform facts for deterministic adapter tests. */
+export interface OpenExternalInternals {
+    platform?: NodeJS.Platform;
+    run?: NativeCommandRunner;
+}
+/** The application name one catalog id maps to, or undefined when unknown. */
+export declare function macAppName(appId: string): string | undefined;
+/**
+ * Open one file in the named application. Throws when the platform is not
+ * macOS or the catalog id is unknown — the caller maps both to an
+ * `unsupported`/`unknown-app` answer and the client hides the gesture. A
+ * launch failure propagates as the runner's rejection.
+ * @param path - absolute path in the host's execution world (caller owns
+ *   resolution, typically `FileSystem.processPath`).
+ * @param appId - official open-in-app catalog id (e.g. `cursor`).
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - platform seam for deterministic tests.
+ */
+export declare function openExternalNative(path: string, appId: string, signal: AbortSignal, internals?: OpenExternalInternals): Promise<void>;
+//# sourceMappingURL=open-external.d.ts.map

package/lib/types/open-external.js

@@ -0,0 +1,61 @@
+/**
+ * Native "open this file in a specific application" dispatch used by the
+ * file-preview Remote's `openExternal` method (the "open in IDE" gesture).
+ *
+ * The official open-in-app route (`POST /open-in-app/open`) only accepts
+ * directories — a file path 404s — so file-exact opens carry their own
+ * dispatch here. macOS only: `open -a <App> <path>` through the official
+ * `@deepseek-ai/dsh-native-command` runner (no shell, abort propagation),
+ * mirroring `reveal.ts`'s discipline. The browser picks the application by
+ * official open-in-app catalog id (probed from `/open-in-app/apps`); the
+ * id → `.app` name map below mirrors the official catalog's darwin entries
+ * (packages/host/open-in-app/src/catalog.ts at 0.1.5-rc.1 — re-check on every
+ * host upgrade). Other platforms and unknown ids answer unsupported, and the
+ * client hides the gesture.
+ * @module @khorsheed/dsh-file-preview
+ */
+import { runNativeCommand } from '@deepseek-ai/dsh-native-command';
+/** Official catalog id → macOS application name (darwin entries of the official catalog). */
+const MAC_APP_NAMES = {
+    cursor: 'Cursor',
+    vscode: 'Visual Studio Code',
+    vscodeinsiders: 'Visual Studio Code - Insiders',
+    windsurf: 'Windsurf',
+    zed: 'Zed',
+    sublimetext: 'Sublime Text',
+    xcode: 'Xcode',
+    androidstudio: 'Android Studio',
+    intellij: 'IntelliJ IDEA',
+    pycharm: 'PyCharm',
+    webstorm: 'WebStorm',
+    phpstorm: 'PhpStorm',
+    goland: 'GoLand',
+    rider: 'Rider',
+    rustrover: 'RustRover',
+};
+/** The application name one catalog id maps to, or undefined when unknown. */
+export function macAppName(appId) {
+    return MAC_APP_NAMES[appId];
+}
+/**
+ * Open one file in the named application. Throws when the platform is not
+ * macOS or the catalog id is unknown — the caller maps both to an
+ * `unsupported`/`unknown-app` answer and the client hides the gesture. A
+ * launch failure propagates as the runner's rejection.
+ * @param path - absolute path in the host's execution world (caller owns
+ *   resolution, typically `FileSystem.processPath`).
+ * @param appId - official open-in-app catalog id (e.g. `cursor`).
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - platform seam for deterministic tests.
+ */
+export async function openExternalNative(path, appId, signal, internals = {}) {
+    const platform = internals.platform ?? process.platform;
+    if (platform !== 'darwin') {
+        throw new Error(`open-in-app is unsupported on ${platform}`);
+    }
+    const app = macAppName(appId);
+    if (app === undefined)
+        throw new Error(`unknown application id "${appId}"`);
+    const run = internals.run ?? runNativeCommand;
+    await run('open', ['-a', app, path], signal);
+}

package/lib/types/types.d.ts

@@ -95,6 +95,16 @@ export type FilePreviewReveal = {
     /** Why: `missing` = the recorded path does not resolve to an existing target; `select-failed` = the host could not select the file. */
     readonly reason: 'missing' | 'select-failed';
 };
+/** Outcome of a `filePreview.openExternal` call (the "open in IDE" gesture). */
+export type FilePreviewOpenExternal = {
+    /** The application launched on the file. */
+    readonly opened: true;
+} | {
+    /** The file could not be opened in the named application. */
+    readonly opened: false;
+    /** Why: `missing` = the recorded path does not resolve to an existing target; `unknown-app` = the catalog id is not mapped; `unsupported-platform` = the host is not macOS; `launch-failed` = the native launch rejected. */
+    readonly reason: 'missing' | 'unknown-app' | 'unsupported-platform' | 'launch-failed';
+};
 /** One file's mutation facts within one turn — the turn card's vocabulary. */
 export interface FilePreviewTurnFile {
     /** The display path (absolute for bash-captured writes; as-recorded otherwise). */
@@ -105,7 +115,7 @@ export interface FilePreviewTurnFile {
     /** Lines added across the turn's mutations of this path. */
     readonly added?: number;
     /** Lines removed; 0 for a create; absent when an uncounted mutation (a write
-     *  whose prior content was not diffable, a Code Mode dispatch) reported no
+     *  whose prior content was not diffable, a PTC dispatch) reported no
      *  total. */
     readonly removed?: number;
 }

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "File Preview",
+    "description": "Read-only listing of session-written files with their current content."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "文件预览",
+    "description": "只读列出会话写过、改过的文件并提供当前文本。"
+  }
+}

package/package.json

@@ -7,7 +7,7 @@
     "cordis",
     "file-preview"
   ],
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -33,6 +33,7 @@
       "default": "./lib/typert.remote-client.js"
     },
     "./src/*": "./src/*",
+    "./locale/*.json": "./locale/*.json",
     "./package.json": "./package.json"
   },
   "files": [
@@ -42,7 +43,7 @@
     "lib/typert.remote-client.d.ts",
     "lib/typert.remote-client.js",
     "cordis.patch.yml",
-    "skills/**/*.md",
+    "locale/*.json",
     "LICENSE",
     "CHANGELOG.md"
   ],
@@ -57,27 +58,16 @@
     "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.6",
     "@deepseek-ai/cordis": "^4.0.1"
   },
-  "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-fs": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-loader-smoke": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-native-command": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-skill": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-util-values": "^0.1.2-rc.1"
+  "dependencies": {
+    "zod": "^4.4.3"
   },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
     "compat": {
-      "minHost": "0.1.2-rc.1",
-      "verifiedHost": "0.1.2-rc.1"
+      "minHost": "0.1.5-rc.1",
+      "verifiedHost": "0.1.5-rc.1"
     }
   }
 }