@khorsheed/dsh-file-preview 0.1.1 → 0.3.0

package/lib/index.js

@@ -1,9 +1,7 @@
-import { readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import z from "@deepseek-ai/schemastery";
 import { homedir, release } from "node:os";
+import { resolve } from "node:path";
 import { runNativeCommand } from "@deepseek-ai/dsh-native-command";
 //#region lib/types/bash-writes.js
 /**
@@ -271,7 +269,7 @@ var BashWriteCollector = class {
 	#replay(session) {
 		this.#pending.set(session.id, /* @__PURE__ */ new Map());
 		this.#captured.set(session.id, /* @__PURE__ */ new Map());
-		for (const event of session.events) this.#onEvent(session, event);
+		for (const event of session.snapshotEvents()) this.#onEvent(session, event);
 	}
 	#onEvent(session, event) {
 		if (event.type === "tool/call") {
@@ -381,9 +379,11 @@ function diffsFromResultMeta(meta) {
 * first-seen order and deduplicated by display path; a later occurrence
 * refreshes the entry's op and location without moving it, and each write/edit
 * tool result appends its change's diff to the entry's `diffs` in event order.
-* Nested Code Mode file dispatches (`tool/code-dispatch` events) count too —
-* they carry no turn/step of their own, so the entry borrows the enclosing
-* root call's location.
+* Nested PTC file dispatches (`tool/ptc-dispatch` events — the host's Code
+* Mode name through 0.1.2, renamed with the 0.1.5 format; the v2→v3 log
+* migration renames persisted rows, so only the ptc name is matched) count
+* too — they carry no turn/step of their own, so the entry borrows the
+* enclosing root call's location.
 * @param events - the session's events in ascending seq order.
 * @param maxFiles - cap on returned entries; excess files are dropped in
 *   first-seen order after the cap is reached.
@@ -391,7 +391,7 @@ function diffsFromResultMeta(meta) {
 */
 function foldFilePreview(events, maxFiles) {
 	const entries = /* @__PURE__ */ new Map();
-	/** Root tool/call locations, so nested code dispatches borrow their turn/step. */
+	/** Root tool/call locations, so nested dispatches borrow their turn/step. */
 	const callSites = /* @__PURE__ */ new Map();
 	let asOfSeq = -1;
 	/** Upsert one touched path, refreshing a repeat in place and keeping its diffs. */
@@ -424,7 +424,7 @@ function foldFilePreview(events, maxFiles) {
 			record(target, event.seq, event.data.turn, event.data.step);
 			continue;
 		}
-		if (event.type === "tool/code-dispatch") {
+		if (event.type === "tool/ptc-dispatch") {
 			if (event.data.isError) continue;
 			const target = targetFromArguments(event.data.name, event.data.arguments);
 			if (target === void 0) continue;
@@ -508,11 +508,12 @@ function resultCallFacts(message) {
 * single source of truth. Unlike {@link foldFilePreview}, this does NOT dedupe
 * a path to its last occurrence: a file touched in two turns appears in BOTH
 * turn maps, so each turn's card lists exactly what that turn mutated.
-* write/edit calls register with their own turn; nested Code Mode dispatches
-* borrow the enclosing root call's turn (dispatch events carry none); a
-* `tool/result` whose presentation meta carries diffs registers its paths (the
-* render-intent vocabulary) with the result's turn, and per-turn line deltas
-* are summed from the diffs. A `write` whose result carries no diffs is a
+* Reads leave no card entry (the card is the mutation vocabulary — write/edit
+* only), so a pure-read call never registers; write/edit calls register with
+* their own turn; nested PTC dispatches borrow the enclosing root call's
+* turn (dispatch events carry none); a `tool/result` whose presentation meta
+* carries diffs registers its paths (the render-intent vocabulary) with the
+* result's turn, and per-turn line deltas are summed from the diffs. A `write` whose result carries no diffs is a
 * create (the write tool records no diffs when the file had no prior content):
 * its full written content — read from the call arguments, which the log keeps
 * — is the added-line count, once per file per turn.
@@ -520,7 +521,7 @@ function resultCallFacts(message) {
 * Count discipline: a write/edit tool/call only registers the path's location
 * and never touches counts (its counted result follows); the first count
 * contribution for a turn+path is adopted verbatim, later ones accumulate per
-* field with unknown-wins — an uncounted mutation (a Code Mode dispatch, or a
+* field with unknown-wins — an uncounted mutation (a PTC dispatch, or a
 * diff whose side reports no prior content) poisons that field to undefined
 * rather than reporting a misleading partial.
 * @param events - the session's events in ascending seq order.
@@ -528,7 +529,7 @@ function resultCallFacts(message) {
 */
 function foldFilePreviewByTurn(events) {
 	const byTurn = /* @__PURE__ */ new Map();
-	/** Root tool/call locations, so nested code dispatches borrow their turn/step. */
+	/** Root tool/call locations, so nested dispatches borrow their turn/step. */
 	const callSites = /* @__PURE__ */ new Map();
 	/** Write-tool calls keyed by callId (create fallback; see {@link WriteCallFacts}). */
 	const writeCalls = /* @__PURE__ */ new Map();
@@ -566,7 +567,7 @@ function foldFilePreviewByTurn(events) {
 	*  a turn+path is adopted verbatim (a count-less placeholder from a
 	*  preceding tool/call must not poison it); later contributions accumulate
 	*  per field with unknown-wins. `unknown` marks an uncountable mutation (a
-	*  Code Mode dispatch): it poisons both fields. */
+	*  PTC dispatch): it poisons both fields. */
 	const recordContribution = (path, turn, seq, step, added, removed, unknown) => {
 		const map = turnMap(turn);
 		const key = countKey(turn, path);
@@ -609,6 +610,7 @@ function foldFilePreviewByTurn(events) {
 			});
 			const target = pathFromToolCall(event.data.name, event.data.arguments);
 			if (target === void 0) continue;
+			if (target.op === "read") continue;
 			if (target.op === "write") {
 				const content = contentFromWriteCall(event.data.arguments);
 				if (content !== void 0) {
@@ -624,10 +626,11 @@ function foldFilePreviewByTurn(events) {
 			recordLocation(target.path, event.data.turn, event.seq, event.data.step);
 			continue;
 		}
-		if (event.type === "tool/code-dispatch") {
+		if (event.type === "tool/ptc-dispatch") {
 			if (event.data.isError) continue;
 			const target = targetFromArguments(event.data.name, event.data.arguments);
 			if (target === void 0) continue;
+			if (target.op === "read") continue;
 			const site = callSites.get(String(event.data.rootCallId)) ?? {
 				turn: 0,
 				step: 0
@@ -654,6 +657,68 @@ function foldFilePreviewByTurn(events) {
 	return byTurn;
 }
 //#endregion
+//#region lib/types/open-external.js
+/**
+* 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
+*/
+/** 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. */
+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.
+*/
+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 === void 0) throw new Error(`unknown application id "${appId}"`);
+	await (internals.run ?? runNativeCommand)("open", [
+		"-a",
+		app,
+		path
+	], signal);
+}
+//#endregion
 //#region lib/types/reveal.js
 /**
 * Cross-platform native "show in folder, selecting the file" dispatch used by
@@ -771,45 +836,6 @@ var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializ
 	if (target) Object.defineProperty(target, contextIn.name, descriptor);
 	done = true;
 };
-/**
-* 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 === void 0) {
-		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 === void 0 || description === void 0 || content === void 0) {
-			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 = /* @__PURE__ */ new Set([
 	".pdf",
@@ -900,8 +926,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.
@@ -909,17 +936,32 @@ 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",
@@ -964,6 +1006,17 @@ let FilePreviewService = (() => {
 				},
 				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,
@@ -988,6 +1041,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. */
@@ -1008,6 +1063,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,
@@ -1028,7 +1084,10 @@ let FilePreviewService = (() => {
 					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;
@@ -1104,52 +1163,84 @@ 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 /* @__PURE__ */ new Set();
+			const cwd = agent.session.header.cwd;
+			const existing = /* @__PURE__ */ new Set();
+			for (const path of paths) {
+				if (existing.has(path)) continue;
+				try {
+					const target = await this.fs.resolve(path, cwd === void 0 ? {} : { cwd });
+					if ((await this.fs.stat(target))?.type === "file") existing.add(path);
+				} catch {}
+			}
+			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 === void 0 || 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 !== void 0 && 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;
@@ -1182,8 +1273,12 @@ let FilePreviewService = (() => {
 					files: files.sort((a, b) => a.seq - b.seq)
 				});
 			}
+			const existing = await this.retainExisting(agent, turns.flatMap((group) => group.files.map((file) => file.path)));
 			return {
-				turns,
+				turns: turns.map((group) => ({
+					turn: group.turn,
+					files: group.files.filter((file) => existing.has(file.path))
+				})).filter((group) => group.files.length > 0),
 				asOfSeq
 			};
 		}
@@ -1333,6 +1428,63 @@ let FilePreviewService = (() => {
 				};
 			}
 		}
+		/**
+		* 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) === void 0) return {
+				opened: false,
+				reason: "unknown-app"
+			};
+			const cwd = agent.session.header.cwd;
+			let target;
+			try {
+				target = await this.fs.resolve(path, cwd === void 0 ? { signal } : {
+					cwd,
+					signal
+				});
+			} catch {
+				return {
+					opened: false,
+					reason: "missing"
+				};
+			}
+			let info;
+			try {
+				info = await this.fs.stat(target, signal);
+			} catch {
+				info = void 0;
+			}
+			if (info === void 0) return {
+				opened: false,
+				reason: "missing"
+			};
+			try {
+				await this.openExternalNative(this.fs.processPath(target), app, signal);
+				return { opened: true };
+			} catch (error) {
+				return {
+					opened: false,
+					reason: (error instanceof Error ? error.message : String(error)).startsWith("open-in-app is unsupported on ") ? "unsupported-platform" : "launch-failed"
+				};
+			}
+		}
 	};
 })();
 //#endregion