@khorsheed/dsh-file-preview 0.1.0

package/lib/types/reveal.js

@@ -0,0 +1,77 @@
+/**
+ * Cross-platform native "show in folder, selecting the file" dispatch used by
+ * the file-preview Remote's `reveal` method.
+ *
+ * The official host opener only opens a path with the default application —
+ * it has no select-in-folder intent — so this plugin carries its own
+ * shell-free dispatch: macOS `open -R` (Finder reveals and selects), Windows
+ * `explorer /select,<path>` (Explorer reveals and selects), WSL translates the
+ * path to the Windows spelling first, and desktop Linux tries the
+ * select-capable file managers (`nautilus` / `dolphin` / `nemo` `--select`) in
+ * order, falling back to the caller's parent-folder open when none is
+ * installed. Every command runs through the official
+ * `@deepseek-ai/dsh-native-command` runner — no shell, abort propagation.
+ * @module @khorsheed/dsh-file-preview
+ */
+import { release as osRelease } from 'node:os';
+import { runNativeCommand } from '@deepseek-ai/dsh-native-command';
+/** Whether one environment marker is set to a non-empty value. */
+function present(value) {
+    return value !== undefined && value !== '';
+}
+/** Distinguish WSL from desktop Linux using its process and kernel markers. */
+function isWsl(internals) {
+    const env = internals.env ?? process.env;
+    if (present(env.WSL_DISTRO_NAME) || present(env.WSL_INTEROP))
+        return true;
+    return (internals.osRelease ?? osRelease()).toLowerCase().includes('microsoft');
+}
+/** Desktop file managers with a documented `--select <path>` flag, tried in order. */
+const SELECT_FILE_MANAGERS = ['nautilus', 'dolphin', 'nemo'];
+/**
+ * Reveal one path in the host file manager, opening its folder and selecting
+ * the path. Throws when the platform cannot select (no select-capable file
+ * manager, unsupported platform) — the caller then opens the parent folder.
+ * @param path - absolute path in the host's execution world (caller owns
+ *   resolution, typically `FileSystem.processPath`).
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - platform and environment seam for deterministic tests.
+ */
+export async function revealNativePath(path, signal, internals = {}) {
+    const platform = internals.platform ?? process.platform;
+    const run = internals.run ?? runNativeCommand;
+    if (platform === 'linux' && isWsl(internals)) {
+        const translated = await run('wslpath', ['-w', path], signal);
+        signal.throwIfAborted();
+        const windowsPath = translated.stdout.replace(/[\r\n]+$/, '');
+        if (windowsPath === '')
+            throw new Error('wslpath returned no Windows path');
+        await run('explorer.exe', [`/select,${windowsPath}`], signal);
+        return;
+    }
+    if (platform === 'darwin') {
+        await run('open', ['-R', path], signal);
+        return;
+    }
+    if (platform === 'win32') {
+        await run('explorer.exe', [`/select,${path}`], signal);
+        return;
+    }
+    if (platform === 'linux') {
+        let lastError;
+        for (const manager of SELECT_FILE_MANAGERS) {
+            try {
+                await run(manager, ['--select', path], signal);
+                return;
+            }
+            catch (error) {
+                // A missing manager (ENOENT) or a failed launch: try the next one.
+                lastError = error;
+            }
+        }
+        throw lastError instanceof Error
+            ? lastError
+            : new Error('no select-capable file manager found');
+    }
+    throw new Error(`native path reveal is unsupported on ${platform}`);
+}

package/lib/types/types.d.ts

@@ -0,0 +1,124 @@
+/** Wire payload vocabulary of the file-preview Remote service. @module @khorsheed/dsh-file-preview/types */
+/** The model-facing operation recorded on a file. */
+export type FilePreviewOp = 'read' | 'write' | 'edit';
+/** One file the session read, wrote, or edited, with the location of its last occurrence. */
+export interface FilePreviewEntry {
+    /** Display path exactly as the tool call recorded it (relative to the session cwd when it was). */
+    readonly path: string;
+    /** The last recorded operation. */
+    readonly op: FilePreviewOp;
+    /** Seq of the last `tool/call` event recorded for this path. */
+    readonly seq: number;
+    /** Turn of the last occurrence. */
+    readonly turn: number;
+    /** Step of the last occurrence. */
+    readonly step: number;
+    /** Each write/edit change's diff, captured from the tool results' presentation meta, in event order. */
+    readonly diffs: readonly FilePreviewDiff[];
+    /** The last write/edit change's diff (the final `diffs` entry, for callers that want just the latest). */
+    readonly lastDiff?: {
+        readonly oldText: string | null;
+        readonly newText: string;
+    } | undefined;
+}
+/** One write/edit change of a file, in event order, with where it happened. */
+export interface FilePreviewDiff {
+    /** Seq of the `tool/result` event whose meta carried this diff. */
+    readonly seq: number;
+    /** Turn of the change. */
+    readonly turn: number;
+    /** Step of the change. */
+    readonly step: number;
+    /** Prior content, or null for a new file / an overwrite. */
+    readonly oldText: string | null;
+    /** Content after the change. */
+    readonly newText: string;
+}
+/** Whole-list response of `filePreview.list`. */
+export interface FilePreviewList {
+    /** Files in first-seen order, deduplicated by display path. */
+    readonly entries: readonly FilePreviewEntry[];
+    /** Seq of the last scanned session event (`-1` for an empty log). */
+    readonly asOfSeq: number;
+    /** Whether the list was capped at the service's `maxFiles` limit. */
+    readonly truncated: boolean;
+}
+/** Read outcome classification of `filePreview.read`. */
+export type FilePreviewReadKind = 'text' | 'image' | 'binary' | 'missing' | 'too-large' | 'error';
+/** One `filePreview.read` response; exactly one of the content arms is populated. */
+export interface FilePreviewRead {
+    /** The resolved display path of the read target. */
+    readonly path: string;
+    /** Outcome classification; `text`/`image` carry a renderable value, `error` carries message. */
+    readonly kind: FilePreviewReadKind;
+    /** Current text content for `text` reads, capped by the service's `maxReadBytes`
+     * (HTML files by `htmlMaxReadBytes`). */
+    readonly content?: string;
+    /** Browser-loadable URL for `image` reads (host-served bytes, session-scoped). */
+    readonly url?: string;
+    /** Whether `content` was truncated to the byte cap. */
+    readonly truncated?: boolean;
+    /** HTML files only: best-effort hint that the document contains scripts
+     * (`<script>` tags, inline event handlers, or `javascript:` URLs). A hint
+     * for default-mode selection and warning — never a trust decision; the
+     * sandbox and CSP are the real boundary. Absent for non-HTML reads and for
+     * HTML without script markers. */
+    readonly htmlScripted?: boolean;
+    /** Byte size of the file when the backend reported one. */
+    readonly size?: number;
+    /** Human-readable failure detail for `error` reads. */
+    readonly message?: string;
+}
+/** Service configuration, validated by schemastery and documented in the config catalog. */
+export interface FilePreviewConfig {
+    /** Byte cap for a single `read`; larger files answer `too-large` without reading. */
+    readonly maxReadBytes?: number;
+    /** Byte cap for reading HTML/HTM files — the sandboxed render channel can
+     * handle far larger documents than the code view, so HTML gets its own,
+     * wider cap (default 4 MiB) while every other text read keeps
+     * `maxReadBytes`. */
+    readonly htmlMaxReadBytes?: number;
+    /** Cap on the number of entries `list` returns. */
+    readonly maxFiles?: number;
+    /** Whether the bash-write collector watches sessions for files bash wrote
+     * (heredocs, `>` redirects, `tee`, `sed -i`) and adds them to `list`. On by
+     * default; disable to keep the list log-derived only. */
+    readonly captureBashWrites?: boolean;
+}
+/** Outcome of a `filePreview.reveal` call (the "show in folder" gesture). */
+export type FilePreviewReveal = {
+    /** The host file manager opened the file's folder with the file selected. */
+    readonly revealed: true;
+} | {
+    /** The file could not be revealed; the caller opens the parent folder instead. */
+    readonly revealed: false;
+    /** 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';
+};
+/** 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). */
+    readonly path: string;
+    /** Seq of the first mutation recorded for this path in this turn (stable ordering). */
+    readonly seq: number;
+    readonly step: number;
+    /** 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
+     *  total. */
+    readonly removed?: number;
+}
+/** One turn's file-mutation group for the turn-tail card. */
+export interface FilePreviewTurnGroup {
+    readonly turn: number;
+    readonly files: readonly FilePreviewTurnFile[];
+}
+/** Whole-response of `filePreview.turnFiles`: every turn's mutation groups. */
+export interface FilePreviewTurnMap {
+    /** Files mutated per turn, in event order within each turn. */
+    readonly turns: readonly FilePreviewTurnGroup[];
+    /** Seq of the last scanned session event (cache invalidation watermark). */
+    readonly asOfSeq: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/lib/types/types.js

@@ -0,0 +1,2 @@
+/** Wire payload vocabulary of the file-preview Remote service. @module @khorsheed/dsh-file-preview/types */
+export {};

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@khorsheed/dsh-file-preview",
+  "description": "Read-only file-preview Remote service: lists the files a session wrote or edited and serves their current text content",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "cordis",
+    "file-preview"
+  ],
+  "version": "0.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./typert": {
+      "types": "./lib/typert.host.d.ts",
+      "default": "./lib/typert.host.js"
+    },
+    "./remote": {
+      "types": "./lib/typert.remote-client.d.ts",
+      "default": "./lib/typert.remote-client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "lib/typert.host.d.ts",
+    "lib/typert.host.js",
+    "lib/typert.remote-client.d.ts",
+    "lib/typert.remote-client.js",
+    "cordis.patch.yml",
+    "skills/**/*.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-fs": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-native-command": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.6",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@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-tools": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compat": {
+      "minHost": "0.1.0-rc.6",
+      "verifiedHost": "0.1.1-rc.2"
+    }
+  }
+}

package/skills/3d-artifact/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: 3d-artifact
+description: Generate sandbox-runnable interactive 3D / digital-twin single-file HTML that obeys the strict sandbox CSP — self-contained, zero runtime network, GLB-inline zero-fetch models. Load when the task asks for a 3D visualization, simulation, digital twin, or WebGL scene delivered as one standalone HTML page.
+---
+
+# 3d-artifact — generating sandbox-runnable interactive 3D / digital-twin single-file HTML
+
+## When to load
+
+Load this skill when the task asks to produce a **self-contained HTML page that renders 3D content** — visualizations, simulations, digital twins, WebGL scenes (three.js, etc.) — that must run inside a sandboxed preview iframe under a strict CSP (e.g. the dsh file-view / deliverables preview).
+
+## The hard contract — violations fail silently in the sandbox; this is the #1 cause of "dead" artifacts
+
+1. **Single file, fully self-contained.** All JS/CSS inline. Images as `data:` URIs. No external stylesheets or fonts.
+2. **Zero runtime network.** No `fetch` / XHR / WebSocket / EventSource. Never `loader.load(url)`.
+   - 3D models MUST be inlined as **GLB base64** and decoded by hand: `atob` → `Uint8Array` → `GLTFLoader.parse(arrayBuffer, ...)`.
+   - **Never** embed a `.gltf` JSON whose buffer uses a `data:...` URI. three.js's GLTFLoader resolves `data:` URIs through `fetch`, which the sandbox CSP (`connect-src 'none'`) blocks — verified against three r152.
+3. **Libraries may load only from whitelisted CDNs** (the CSP's `script-src` allows exactly these): `https://cdn.jsdelivr.net` and `https://cdnjs.cloudflare.com`. Use ESM + an inline `<script type="importmap">`. Never derive a resource URL from user/data input at runtime.
+4. **Embed this Tier1 CSP meta tag** in `<head>`:
+
+```html
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'unsafe-inline'; img-src data: blob:; font-src data:; connect-src 'none'; worker-src blob:; object-src 'none'; base-uri 'none'; form-action 'none'; upgrade-insecure-requests; block-all-mixed-content">
+```
+
+5. **Size red lines**: GLB ≤ 6 MB raw (≈8 MB base64); total page ≤ 16 MB. Base64 inflates ×4/3. Prefer procedural geometry, SVG, and compressed textures (KTX2/DRACO) over big assets.
+6. **Performance**: cap `renderer.setPixelRatio` (≤2); keep the scene interactive within ~1 s of load; prefer `InstancedMesh` for repeated objects (vehicles, clamps, turbines); defer heavy DOM with `content-visibility`-style techniques; merge many small geometries (e.g. `BufferGeometryUtils.mergeGeometries`).
+
+## Recommended stack
+
+- three.js ESM + OrbitControls via the importmap pattern:
+
+```html
+<script type="importmap">{"imports":{"three":"https://cdn.jsdelivr.net/npm/three@0.152.2/build/three.module.js","three/addons/":"https://cdn.jsdelivr.net/npm/three@0.152.2/examples/jsm/"}}</script>
+```
+
+- Procedural geometry + vertex colors beat downloaded assets for reliability and size.
+
+## Self-check before finishing
+
+- [ ] No external URL anywhere except whitelisted CDN scripts used by the importmap.
+- [ ] No `fetch(` / `XMLHttpRequest` / `WebSocket` / `loader.load(` anywhere in the page.
+- [ ] Any model is GLB base64 decoded via `atob` → `parse(arrayBuffer)` — never a `data:` URI buffer.
+- [ ] The Tier1 CSP meta tag above is present in `<head>`.
+- [ ] Page + all inline assets ≤ 16 MB.
+- [ ] Opens and renders in a plain browser within ~2 s — that is the sandbox experience.
+
+## Authoring tips for realism (超写实 / 数字孪生 scenes)
+
+- Golden-hour lighting: warm directional sun + hemisphere fill + exponential fog for depth.
+- ACES filmic tone mapping + sRGB output (`renderer.outputEncoding`).
+- Layered composition: hero object (bridge), midground (valley, road), background (mountain silhouettes, turbines, power towers), atmosphere (fog, mist).
+- Digital-twin overlays read best as translucent DOM panels + in-scene markers (sensor nodes, point clouds, BIM wireframes, heatmaps, drone paths).