@khorsheed/dsh-file-preview 0.1.0

package/lib/types/index.js

@@ -0,0 +1,517 @@
+/** Read-only file-preview Remote service over live sessions and the filesystem.
+ * @module @khorsheed/dsh-file-preview
+ */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    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 { 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 }));
+    }
+    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',
+    '.woff', '.woff2', '.ttf', '.otf', '.eot',
+    '.wasm', '.node', '.dylib', '.so', '.dll', '.exe', '.kext',
+    '.class', '.jar', '.pyc', '.sqlite', '.db',
+    '.DS_Store', '.a', '.o',
+]);
+/** Image extensions served to the browser through the image route. */
+const IMAGE_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.bmp', '.ico', '.svg',
+]);
+/** MIME type per image extension for the image route's Content-Type header. */
+const IMAGE_MIME = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.bmp': 'image/bmp',
+    '.ico': 'image/x-icon',
+    '.svg': 'image/svg+xml',
+};
+/** NUL bytes in decoded text mark a file as binary despite a successful decode. */
+function hasNulByte(content) {
+    return content.slice(0, 4096).includes('\u0000');
+}
+/** Detect a binary file from its display path extension. */
+function isBinaryPath(path) {
+    const dot = path.lastIndexOf('.');
+    return dot >= 0 && BINARY_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+/** Detect an image from its display path extension. */
+function isImagePath(path) {
+    const dot = path.lastIndexOf('.');
+    return dot >= 0 && IMAGE_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+/** HTML extensions served through the sandboxed render channel. */
+const HTML_EXTENSIONS = new Set(['.html', '.htm']);
+/** Detect an HTML document from its display path extension. */
+function isHtmlPath(path) {
+    const dot = path.lastIndexOf('.');
+    return dot >= 0 && HTML_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+/** Best-effort scripted-HTML detection: any `<script>` tag, inline event
+ *  handler (`on*="…"`), or `javascript:` URL marks the document as scripted.
+ *  Only a hint for default-mode selection and warning — never a trust
+ *  decision; the sandbox and the Tier1 CSP are the real boundary. The scan
+ *  runs on the read content as delivered (a truncated read may miss markers
+ *  in the tail; acceptable for a hint). */
+function isScriptedHtml(content) {
+    return /<\s*script[\s>]/i.test(content)
+        || /\son[a-z]+\s*=/i.test(content)
+        || /javascript:/i.test(content);
+}
+/** Stable error text for a failed read, without leaking backend internals. */
+function readErrorMessage(error) {
+    return error instanceof Error ? error.message : String(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
+ * 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.
+ */
+let FilePreviewService = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _list_decorators;
+    let _turnFiles_decorators;
+    let _read_decorators;
+    let _reveal_decorators;
+    return class FilePreviewService extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _list_decorators = [Remote('list')];
+            _turnFiles_decorators = [Remote('turnFiles')];
+            _read_decorators = [Remote('read')];
+            _reveal_decorators = [Remote('reveal')];
+            __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);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        static inject = ['fs'];
+        static Config = z.object({
+            maxReadBytes: z.natural().min(1).default(512 * 1024),
+            htmlMaxReadBytes: z.natural().min(1).default(4 * 1024 * 1024),
+            maxFiles: z.natural().min(1).default(500),
+            captureBashWrites: z.boolean().default(true),
+        });
+        /** URL prefix the image route answers under. */
+        static IMAGE_ROUTE = '/file-preview-image';
+        resolved = __runInitializers(this, _instanceExtraInitializers);
+        /** Whether a web server is present to host the image route; image reads
+         * answer `binary` without it (the headless face has no browser to serve). */
+        imageRoute;
+        /** The agents service when present (image route only; null headless). */
+        agents;
+        /** Native reveal runner; a constructor seam for deterministic tests. */
+        revealNative;
+        /** Bash-write collector (S2 seam), or undefined when disabled in config. */
+        collector;
+        /** Per-session by-turn fold cache, invalidated by the log watermark. */
+        turnCache = new Map();
+        /**
+         * @param ctx - owning Cordis Context carrying `fs`; `webServer` and `agents`
+         *   are optional (the image route needs them, headless faces lack both).
+         * @param config - optional deployment tuning; defaults cap reads and lists,
+         *   and enable the bash-write collector.
+         * @param deps - test seam for the native reveal dispatch.
+         */
+        constructor(ctx, config = {}, deps = {}) {
+            super(ctx, 'filePreview');
+            this.resolved = {
+                maxReadBytes: config.maxReadBytes ?? 512 * 1024,
+                htmlMaxReadBytes: config.htmlMaxReadBytes ?? 4 * 1024 * 1024,
+                maxFiles: config.maxFiles ?? 500,
+                captureBashWrites: config.captureBashWrites ?? true,
+            };
+            this.revealNative = deps.revealNative ?? revealNativePath;
+            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');
+            }
+            else {
+                this.collector = undefined;
+            }
+            const webServer = ctx.get('webServer');
+            this.agents = ctx.get('agents');
+            this.imageRoute = webServer !== undefined && this.agents !== undefined;
+            if (this.imageRoute && webServer !== undefined) {
+                ctx.effect(() => webServer.register({
+                    kind: 'prefix',
+                    path: FilePreviewService.IMAGE_ROUTE,
+                    /* v8 ignore next 2 -- the handler body is the request path; the
+                       unit tests drive serveImage directly, the real server reaches it
+                       through this registration */
+                    handler: (req, res) => { void this.serveImage(req, res); },
+                }), 'file-preview: image route');
+            }
+            registerArtifactSkill(ctx);
+        }
+        get fs() {
+            return this.ctx.fs;
+        }
+        /**
+         * Serve one image file's bytes for a browser `<img>` request. The URL is
+         * `IMAGE_ROUTE/<sessionId>/<encodeURIComponent(path)>`; the session must be
+         * live (the same scope `read` serves) and the path resolves against its cwd.
+         * @param req - the incoming image request.
+         * @param res - the response to fill with bytes or an error status.
+         */
+        async serveImage(req, res) {
+            /* v8 ignore next -- split('?')[0] is always a string when url is defined; the fallback guards a future parse change */
+            const pathname = req.url === undefined ? '' : req.url.split('?')[0] ?? '';
+            const rest = pathname.slice(FilePreviewService.IMAGE_ROUTE.length + 1);
+            const slash = rest.indexOf('/');
+            if (slash <= 0) {
+                res.writeHead(400).end('file preview: expected /<sessionId>/<path>');
+                return;
+            }
+            const sessionId = rest.slice(0, slash);
+            const encoded = rest.slice(slash + 1);
+            let display;
+            try {
+                display = decodeURIComponent(encoded);
+            }
+            catch {
+                res.writeHead(400).end('file preview: malformed path');
+                return;
+            }
+            const agent = this.agents?.get(sessionId);
+            if (agent === undefined) {
+                res.writeHead(404).end('file preview: session not found');
+                return;
+            }
+            if (!isImagePath(display)) {
+                res.writeHead(400).end('file preview: not an image path');
+                return;
+            }
+            const cwd = agent.session.header.cwd;
+            let target;
+            try {
+                target = await this.fs.resolve(display, cwd === undefined ? {} : { cwd });
+            }
+            catch (error) {
+                res.writeHead(404).end(readErrorMessage(error));
+                return;
+            }
+            let info;
+            try {
+                info = await this.fs.stat(target);
+            }
+            catch (error) {
+                res.writeHead(404).end(readErrorMessage(error));
+                return;
+            }
+            if (info === undefined || info.type !== 'file') {
+                res.writeHead(404).end('file preview: not a file');
+                return;
+            }
+            if (info.size !== undefined && info.size > this.resolved.maxReadBytes) {
+                res.writeHead(413).end('file preview: image exceeds the read cap');
+                return;
+            }
+            let bytes;
+            try {
+                bytes = await this.fs.readBytes(target, undefined, this.resolved.maxReadBytes);
+            }
+            catch (error) {
+                res.writeHead(404).end(readErrorMessage(error));
+                return;
+            }
+            const dot = display.lastIndexOf('.');
+            /* v8 ignore next -- every IMAGE_EXTENSIONS entry has a MIME mapping; the fallback guards a future extension */
+            const mime = IMAGE_MIME[display.slice(dot).toLowerCase()] ?? 'application/octet-stream';
+            res.writeHead(200, {
+                'Content-Type': mime,
+                'Cache-Control': 'no-store',
+            });
+            res.end(Buffer.from(bytes));
+        }
+        /**
+         * 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.
+         * @param agent - owning live agent; its session log is the data source.
+         * @returns first-seen files capped by `maxFiles`, with the log watermark.
+         */
+        list(agent) {
+            const folded = foldFilePreview(agent.session.events, 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: [] });
+            }
+            if (extra.length === 0)
+                return folded;
+            return {
+                entries: [...folded.entries, ...extra],
+                asOfSeq: folded.asOfSeq,
+                truncated: folded.truncated || folded.entries.length + extra.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
+         * 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.
+         * @param agent - owning live agent; its session log is the data source.
+         * @returns per-turn file groups plus the scanned watermark.
+         */
+        turnFiles(agent) {
+            const session = agent.session;
+            const events = session.events;
+            const asOfSeq = events.length === 0 ? -1 : events[events.length - 1].seq;
+            const cached = this.turnCache.get(session.id);
+            let byTurn;
+            if (cached === undefined || cached.asOfSeq !== asOfSeq) {
+                byTurn = foldFilePreviewByTurn(events);
+                this.turnCache.set(session.id, { asOfSeq, byTurn });
+            }
+            else {
+                byTurn = cached.byTurn;
+            }
+            const captured = this.collector?.captured(session.id);
+            const turns = [];
+            // One pass over the turn keys in ascending order (turn numbers are small).
+            const turnNumbers = new Set(byTurn.keys());
+            if (captured !== undefined) {
+                for (const write of captured.values())
+                    turnNumbers.add(write.turn);
+            }
+            for (const turn of [...turnNumbers].sort((a, b) => a - b)) {
+                const files = [];
+                const map = byTurn.get(turn);
+                if (map !== undefined)
+                    files.push(...map.values());
+                if (captured !== undefined) {
+                    for (const [path, write] of captured) {
+                        if (write.turn !== turn || files.some(file => file.path === path))
+                            continue;
+                        files.push({ path, seq: write.seq, step: write.step });
+                    }
+                }
+                if (files.length === 0)
+                    continue;
+                turns.push({ turn, files: files.sort((a, b) => a.seq - b.seq) });
+            }
+            return { turns, asOfSeq };
+        }
+        /**
+         * Read the current content of one recorded file, resolved against the
+         * session cwd and capped by `maxReadBytes`.
+         * @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.
+         * @returns the classified read; `text` carries content, `image` carries a
+         *   browser URL, other kinds carry the size or a human-readable reason.
+         */
+        async read(agent, path, signal) {
+            if (typeof path !== 'string' || path.length === 0) {
+                return { path, kind: 'error', message: 'file preview requires a non-empty path' };
+            }
+            const cwd = agent.session.header.cwd;
+            let target;
+            try {
+                target = await this.fs.resolve(path, cwd === undefined ? { signal } : { cwd, signal });
+            }
+            catch (error) {
+                return { path, kind: 'error', message: readErrorMessage(error) };
+            }
+            let info;
+            try {
+                info = await this.fs.stat(target, signal);
+            }
+            catch (error) {
+                return { path, kind: 'error', message: readErrorMessage(error) };
+            }
+            if (info === undefined || info.type !== 'file') {
+                return { path, kind: 'missing' };
+            }
+            // HTML gets its own, wider render-channel cap; every other text read
+            // keeps `maxReadBytes`. Images keep the base cap (their route serves
+            // bytes, not the render channel).
+            const html = isHtmlPath(path);
+            const cap = html ? this.resolved.htmlMaxReadBytes : this.resolved.maxReadBytes;
+            if (info.size !== undefined && info.size > cap) {
+                return { path, kind: 'too-large', size: info.size };
+            }
+            if (isImagePath(path)) {
+                if (this.imageRoute) {
+                    const encoded = encodeURIComponent(path);
+                    return {
+                        path,
+                        kind: 'image',
+                        url: `${FilePreviewService.IMAGE_ROUTE}/${agent.session.id}/${encoded}`,
+                        ...(info.size === undefined ? {} : { size: info.size }),
+                    };
+                }
+                // No web face to serve bytes: an image is binary, never decoded as text.
+                return { path, kind: 'binary', ...(info.size === undefined ? {} : { size: info.size }) };
+            }
+            if (isBinaryPath(path)) {
+                return { path, kind: 'binary', ...(info.size === undefined ? {} : { size: info.size }) };
+            }
+            try {
+                const content = await this.fs.readText(target, signal);
+                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,
+                    truncated,
+                    ...(html && isScriptedHtml(content) ? { htmlScripted: true } : {}),
+                    ...(info.size === undefined ? {} : { size: info.size }),
+                };
+            }
+            catch (error) {
+                return { path, kind: 'error', message: readErrorMessage(error) };
+            }
+        }
+        /**
+         * Reveal one recorded file in the host file manager — open its folder and
+         * select the file (macOS Finder, Windows Explorer, or a select-capable
+         * desktop file manager). The display path resolves against the session cwd;
+         * the native reveal runs on the host. A path that does not resolve to an
+         * existing target, or a platform that cannot select, answers `revealed:
+         * false` and the caller opens the parent folder instead (the pre-reveal
+         * "show in folder" behavior), so the gesture always lands somewhere visible.
+         * @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 signal - cooperative cancellation from the calling UI request.
+         * @returns whether the file manager selected the file, or why not.
+         */
+        async reveal(agent, path, signal) {
+            if (typeof path !== 'string' || path.length === 0) {
+                return { revealed: false, reason: 'missing' };
+            }
+            const cwd = agent.session.header.cwd;
+            let target;
+            try {
+                target = await this.fs.resolve(path, cwd === undefined ? { signal } : { cwd, signal });
+            }
+            catch (error) {
+                // Unresolvable recorded path: the file is gone; the caller opens the parent.
+                return { revealed: false, reason: 'missing' };
+            }
+            let info;
+            try {
+                info = await this.fs.stat(target, signal);
+            }
+            catch {
+                // A stat failure is treated as missing; the caller still opens the parent.
+                info = undefined;
+            }
+            if (info === undefined) {
+                return { revealed: false, reason: 'missing' };
+            }
+            try {
+                // processPath hands the canonical path a host subprocess can open; the
+                // recorded display path may be relative or backend-normalized.
+                await this.revealNative(this.fs.processPath(target), signal);
+                return { revealed: true };
+            }
+            catch {
+                // No select-capable file manager (or a failed launch): fall back to the
+                // parent-folder open rather than failing the whole gesture.
+                return { revealed: false, reason: 'select-failed' };
+            }
+        }
+    };
+})();
+export { FilePreviewService };
+export default FilePreviewService;

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-file-preview`.
+ * @module @khorsheed/dsh-file-preview/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "file-preview-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,oCAAoC;AACpC,eAAO,MAAM,IAAI,2BAA2B,CAAA;AAC5C,2EAA2E;AAC3E,eAAO,MAAM,MAAM,UAAiB,CAAA;AAUpC;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAS,OAAO,KAAG,OAAO,CAAC,MAAM,IAAI,CACU,CAAA"}

package/lib/types/invariant.js

@@ -0,0 +1,23 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-file-preview`.
+ * @module @khorsheed/dsh-file-preview/invariant
+ */
+const PACKAGE_NAME = '@khorsheed/dsh-file-preview';
+/** Cordis companion plugin name. */
+export const name = 'file-preview-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: the service owns no durable package-local state and
+ * writes nothing — `list` is a pure deterministic fold over the session log
+ * (unit-tested), and `read` re-reads the filesystem through `ctx.fs`, whose
+ * own invariants own that relationship.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */

package/lib/types/reveal.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 { type NativeCommandRunner } from '@deepseek-ai/dsh-native-command';
+/** Injectable platform facts for deterministic adapter tests. */
+export interface RevealInternals {
+    platform?: NodeJS.Platform;
+    /** Kernel release override used to distinguish WSL from desktop Linux. */
+    osRelease?: string;
+    /** Environment used for the WSL markers. */
+    env?: NodeJS.ProcessEnv;
+    run?: NativeCommandRunner;
+}
+/**
+ * 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 declare function revealNativePath(path: string, signal: AbortSignal, internals?: RevealInternals): Promise<void>;
+//# sourceMappingURL=reveal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reveal.d.ts","sourceRoot":"","sources":["../../src/reveal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AAE5F,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAA;IAC1B,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,GAAG,CAAC,EAAE,mBAAmB,CAAA;CAC1B;AAiBD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,SAAS,GAAE,eAAoB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAoCf"}