@khorsheed/dsh-file-preview 0.1.1 → 0.3.0

package/lib/types/index.js

@@ -35,54 +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 skillFile = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', '3d-artifact', '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' }));
-    }
-    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',
@@ -145,8 +103,9 @@ function readErrorMessage(error) {
 }
 /**
  * The `filePreview` Remote service: session-scoped read-only file inspection
- * for web surfaces. `list` is a pure fold over the session log (no filesystem
- * access); `read` resolves the path against the session cwd and serves current
+ * for web surfaces. `list` is a fold over the session log, then filtered to the
+ * paths that still exist on disk (resolved against the session cwd and stat-ed
+ * per call); `read` resolves the path against the session cwd and serves current
  * text content through `ctx.fs` (or a browser URL for images), capped by
  * config. Image bytes ride a dedicated host route so the browser loads them
  * natively without bloating the RPC channel.
@@ -154,21 +113,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'];
@@ -188,6 +153,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. */
@@ -208,6 +175,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');
@@ -228,7 +196,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;
@@ -310,48 +281,85 @@ let FilePreviewService = (() => {
             });
             res.end(Buffer.from(bytes));
         }
+        /** Resolve the session's recorded display paths against its cwd and keep only
+         *  those that currently exist as a regular file. The products surfaces fold
+         *  the session log (which is history, not disk state): a path the log wrote
+         *  may have been cleaned up since (a temp script the turn deleted), and such
+         *  a path is not a product to list. Existence is checked fresh on every call
+         *  (never cached), so a deletion that lands after a fold is visible on the
+         *  next fetch. Unresolvable/unstat-able paths are treated as absent.
+         * @param agent - owning live agent; its session cwd anchors relative paths.
+         * @param paths - the display paths to probe.
+         * @returns the subset that resolves to an existing regular file.
+         */
+        async retainExisting(agent, paths) {
+            if (paths.length === 0)
+                return new Set();
+            const cwd = agent.session.header.cwd;
+            const existing = new Set();
+            for (const path of paths) {
+                if (existing.has(path))
+                    continue;
+                try {
+                    const target = await this.fs.resolve(path, cwd === undefined ? {} : { cwd });
+                    const info = await this.fs.stat(target);
+                    if (info?.type === 'file')
+                        existing.add(path);
+                }
+                catch {
+                    // Unresolvable or stat failed: the path is not present to list.
+                }
+            }
+            return existing;
+        }
         /**
          * List the files one session wrote or edited: the log fold plus any
          * bash-written files the collector verified (the S2 seam), merged so a
-         * captured path the fold already knows keeps its log-derived entry.
+         * captured path the fold already knows keeps its log-derived entry. Only
+         * paths that currently exist on disk are returned — a file the session
+         * wrote and later deleted is history, not a product.
          * @param agent - owning live agent; its session log is the data source.
-         * @returns first-seen files capped by `maxFiles`, with the log watermark.
+         * @returns existing first-seen files capped by `maxFiles`, with the log watermark.
          */
-        list(agent) {
-            const folded = foldFilePreview(agent.session.events, this.resolved.maxFiles);
+        async list(agent) {
+            const folded = foldFilePreview(agent.session.snapshotEvents(), this.resolved.maxFiles);
             const captured = this.collector?.captured(agent.session.id);
-            if (captured === undefined || captured.size === 0)
-                return folded;
-            const seen = new Set(folded.entries.map(entry => entry.path));
-            const extra = [];
-            for (const [path, write] of captured) {
-                if (seen.has(path) || folded.entries.length + extra.length >= this.resolved.maxFiles)
-                    continue;
-                extra.push({ path, op: 'write', seq: write.seq, turn: write.turn, step: write.step, diffs: [] });
+            let entries = folded.entries;
+            if (captured !== undefined && captured.size > 0) {
+                const seen = new Set(entries.map(entry => entry.path));
+                const extra = [];
+                for (const [path, write] of captured) {
+                    if (seen.has(path) || entries.length + extra.length >= this.resolved.maxFiles)
+                        continue;
+                    extra.push({ path, op: 'write', seq: write.seq, turn: write.turn, step: write.step, diffs: [] });
+                }
+                entries = [...entries, ...extra];
             }
-            if (extra.length === 0)
-                return folded;
+            const existing = await this.retainExisting(agent, entries.map(entry => entry.path));
             return {
-                entries: [...folded.entries, ...extra],
+                entries: entries.filter(entry => existing.has(entry.path)),
                 asOfSeq: folded.asOfSeq,
-                truncated: folded.truncated || folded.entries.length + extra.length >= this.resolved.maxFiles,
+                truncated: folded.truncated || entries.length >= this.resolved.maxFiles,
             };
         }
         /**
          * 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
          * watermark, so repeated card fetches do not refold. A path touched in two
-         * turns appears in BOTH turn groups — per-turn attribution is exact.
+         * turns appears in BOTH turn groups — per-turn attribution is exact. Only
+         * paths that currently exist on disk are returned (a deleted temp script is
+         * history, not a product); existence is probed fresh on every call, so the
+         * cached fold is filtered per request rather than cached.
          * @param agent - owning live agent; its session log is the data source.
-         * @returns per-turn file groups plus the scanned watermark.
+         * @returns existing per-turn file groups plus the scanned watermark.
          */
-        turnFiles(agent) {
+        async turnFiles(agent) {
             const session = agent.session;
-            const events = session.events;
+            const events = session.snapshotEvents();
             const asOfSeq = events.length === 0 ? -1 : events[events.length - 1].seq;
             const cached = this.turnCache.get(session.id);
             let byTurn;
@@ -386,7 +394,15 @@ let FilePreviewService = (() => {
                     continue;
                 turns.push({ turn, files: files.sort((a, b) => a.seq - b.seq) });
             }
-            return { turns, asOfSeq };
+            // Filter the assembled groups to paths that still exist on disk (fresh per
+            // call — the fold cache is by log watermark, existence moves independently).
+            const existing = await this.retainExisting(agent, turns.flatMap(group => group.files.map(file => file.path)));
+            return {
+                turns: turns
+                    .map(group => ({ turn: group.turn, files: group.files.filter(file => existing.has(file.path)) }))
+                    .filter(group => group.files.length > 0),
+                asOfSeq,
+            };
         }
         /**
          * Read the current content of one recorded file, resolved against the
@@ -511,6 +527,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/package.json

@@ -7,7 +7,7 @@
     "cordis",
     "file-preview"
   ],
-  "version": "0.1.1",
+  "version": "0.3.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -42,7 +42,6 @@
     "lib/typert.remote-client.d.ts",
     "lib/typert.remote-client.js",
     "cordis.patch.yml",
-    "skills/**/*.md",
     "LICENSE",
     "CHANGELOG.md"
   ],
@@ -59,24 +58,25 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-fs": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-loader-smoke": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-native-command": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-skill": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.1-rc.1"
+    "@deepseek-ai/dsh-agent": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-fs": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-loader-smoke": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-native-command": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-skill": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-util-values": "^0.1.5-rc.1"
   },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
     "compat": {
-      "minHost": "0.1.0-rc.6",
-      "verifiedHost": "0.1.1-rc.2"
+      "minHost": "0.1.5-rc.1",
+      "verifiedHost": "0.1.5-rc.1"
     }
   }
 }