@benz-ai-x/dsh-md-preview 0.1.1 → 0.2.0

package/lib/index.js

@@ -52,6 +52,18 @@ var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializ
 function failure(code, message) {
 	return new RemoteError(code, message, {});
 }
+/**
+* `FsErrorCode` of a caught fs-layer error, duck-typed off the `code` property
+* so the Host bundle keeps zero runtime imports beyond its declared peers.
+* @param error - anything thrown by `ctx.fs`.
+* @returns the stable fs code, or undefined for a foreign error shape.
+*/
+function fsErrorCode(error) {
+	if (error !== null && typeof error === "object" && "code" in error) {
+		const code = error.code;
+		if (typeof code === "string") return code;
+	}
+}
 /** Lowercased dot-prefixed extension of a path, or the empty string. */
 function extensionOf(path) {
 	const name = path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1);
@@ -70,10 +82,12 @@ let MdPreviewService = (() => {
 	let _classSuper = TypertRemoteService;
 	let _instanceExtraInitializers = [];
 	let _read_decorators;
+	let _write_decorators;
 	return class MdPreviewService extends _classSuper {
 		static {
 			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
 			_read_decorators = [Remote];
+			_write_decorators = [Remote];
 			__esDecorate(this, null, _read_decorators, {
 				kind: "method",
 				name: "read",
@@ -85,6 +99,17 @@ let MdPreviewService = (() => {
 				},
 				metadata: _metadata
 			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _write_decorators, {
+				kind: "method",
+				name: "write",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "write" in obj,
+					get: (obj) => obj.write
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
 			if (_metadata) Object.defineProperty(this, Symbol.metadata, {
 				enumerable: true,
 				configurable: true,
@@ -150,7 +175,60 @@ let MdPreviewService = (() => {
 			if (content.length > this.config.maxBytes) throw failure("md-preview/too-large", `mdPreview/read refuses "${path}" above the configured byte cap`);
 			return {
 				path,
-				content
+				content,
+				fingerprint: info.version
+			};
+		}
+		/**
+		* Write one previewable file back into the session's workspace.
+		* @param sessionId - owning session; its header cwd roots the write.
+		* @param path - path as it appeared in the conversation.
+		* @param content - the complete new file content.
+		* @param fingerprint - freshness token from the backing read; required
+		*   unless `force` opts into an unconditional overwrite.
+		* @param force - skip the freshness guard (the conflict prompt's override).
+		* @param signal - caller cancellation carried through every fs call.
+		* @returns the saved path with its new freshness token.
+		* @throws RemoteError with a stable MdPreview failure code.
+		*/
+		async write(sessionId, path, content, fingerprint, force, signal) {
+			if (path.trim().length === 0) throw failure("md-preview/bad-request", "mdPreview/write requires a non-empty path");
+			if (!isAllowedExtension(path, this.config.allowedExtensions)) throw failure("md-preview/unsupported-extension", `mdPreview/write refuses non-previewable path "${path}"`);
+			const session = this.ctx.sessions.get(sessionId);
+			if (session === void 0) throw failure("md-preview/unknown-session", `mdPreview/write cannot resolve session "${sessionId}"`);
+			const cwd = session.header.cwd;
+			if (cwd === void 0) throw failure("md-preview/no-workspace", `mdPreview/write session "${sessionId}" has no working directory`);
+			const root = await this.resolveWorkspacePath(cwd, signal);
+			let target;
+			try {
+				target = await this.resolveWorkspacePath(path, signal, cwd);
+			} catch (error) {
+				if (signal.aborted) throw error;
+				throw failure("md-preview/not-found", `mdPreview/write cannot resolve path "${path}"`);
+			}
+			if (!this.ctx.fs.contains(root, target)) throw failure("md-preview/forbidden", "mdPreview/write refuses paths outside the session workspace");
+			const info = await this.ctx.fs.stat(target, signal);
+			if (info === void 0) throw failure("md-preview/not-found", `mdPreview/write cannot find "${path}"`);
+			if (info.type !== "file") throw failure("md-preview/unsupported-extension", `mdPreview/write target "${path}" is not a regular file`);
+			if (content.length > this.config.maxBytes) throw failure("md-preview/too-large", `mdPreview/write refuses "${path}" above the configured byte cap`);
+			if (fingerprint === void 0 && !force) throw failure("md-preview/bad-request", "mdPreview/write requires a fingerprint or force");
+			const expected = fingerprint === void 0 ? void 0 : {
+				kind: "replaceIfVersion",
+				version: fingerprint
+			};
+			let outcome;
+			try {
+				outcome = await this.ctx.fs.writeText(target, content, expected, signal);
+			} catch (error) {
+				if (signal.aborted) throw error;
+				const code = fsErrorCode(error);
+				if (code === "FS_STALE_VERSION") throw failure("md-preview/conflict", `mdPreview/write refuses "${path}": the file changed since read`);
+				if (code === "FS_NOT_FOUND") throw failure("md-preview/not-found", `mdPreview/write cannot find "${path}"`);
+				throw failure("md-preview/unavailable", `mdPreview/write failed for "${path}": ${error instanceof Error ? error.message : String(error)}`);
+			}
+			return {
+				path,
+				fingerprint: outcome.version
 			};
 		}
 		/** Resolve one path against the workspace, with a plain not-found mapping. */
@@ -181,6 +259,7 @@ const MD_PREVIEW_FAILURE_CODES = [
 	"md-preview/forbidden",
 	"md-preview/not-found",
 	"md-preview/too-large",
+	"md-preview/conflict",
 	"md-preview/unavailable"
 ];
 //#endregion

package/lib/typert/remote-client.js

@@ -14,7 +14,15 @@ const readSessionId$schema = z.string();
 const readPath$schema = z.string().min(1);
 const readResult$schema = z.object({
 	path: z.string(),
-	content: z.string()
+	content: z.string(),
+	fingerprint: z.string()
+});
+const writeContent$schema = z.string();
+const writeFingerprint$schema = z.string().optional();
+const writeForce$schema = z.boolean().optional();
+const writeResult$schema = z.object({
+	path: z.string(),
+	fingerprint: z.string()
 });
 /** The MdPreview contribution mounted by this package's browser entry. */
 const TYPERT_REMOTE = {
@@ -50,6 +58,70 @@ const TYPERT_REMOTE = {
 			typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/read:result",
 			schema: readResult$schema
 		}
+	}, {
+		id: "@benz-ai-x/dsh-md-preview#mdPreview/write",
+		service: "mdPreview",
+		namespace: "mdPreview",
+		method: "write",
+		invocation: { kind: "direct" },
+		parameters: [
+			{
+				name: "sessionId",
+				wire: "sessionId",
+				source: "json",
+				codec: {
+					mode: "strict",
+					typeSymbol: "@deepseek-ai/dsh-session/types#SessionId",
+					schema: readSessionId$schema
+				}
+			},
+			{
+				name: "path",
+				wire: "path",
+				source: "json",
+				codec: {
+					mode: "strict",
+					typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:path",
+					schema: readPath$schema
+				}
+			},
+			{
+				name: "content",
+				wire: "content",
+				source: "json",
+				codec: {
+					mode: "strict",
+					typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:content",
+					schema: writeContent$schema
+				}
+			},
+			{
+				name: "fingerprint",
+				wire: "fingerprint",
+				source: "json",
+				codec: {
+					mode: "strict",
+					typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:fingerprint",
+					schema: writeFingerprint$schema
+				}
+			},
+			{
+				name: "force",
+				wire: "force",
+				source: "json",
+				codec: {
+					mode: "strict",
+					typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:force",
+					schema: writeForce$schema
+				}
+			}
+		],
+		cancellation: { parameter: "signal" },
+		result: {
+			mode: "strict",
+			typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:result",
+			schema: writeResult$schema
+		}
 	}]
 };
 //#endregion

package/lib/types/client/PreviewOverlay.d.ts

@@ -2,9 +2,9 @@ import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
 import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
-import type { MdPreviewFile } from '../protocol.ts';
+import type { MdPreviewFile, MdPreviewWriteResult } from '../protocol.ts';
 import type { MdPreviewState } from './preview-state.ts';
-/** Read RPC and panel dismissal, created in the plugin's apply world. */
+/** Read/write RPCs and panel dismissal, created in the plugin's apply world. */
 export interface PreviewOverlayInjected {
     hooks: {
         /** Current preview target; null while the panel is closed. */
@@ -14,6 +14,8 @@ export interface PreviewOverlayInjected {
     close(): void;
     /** One bounded read; the transport carries the AbortSignal. */
     read(sessionId: SessionId, path: string, signal: AbortSignal): Promise<RemoteResult<MdPreviewFile>>;
+    /** One guarded write; `fingerprint` comes from the backing read. */
+    write(sessionId: SessionId, path: string, content: string, fingerprint: string | undefined, force: boolean, signal: AbortSignal): Promise<RemoteResult<MdPreviewWriteResult>>;
 }
 /** Full composed panel props. */
 export type PreviewOverlayProps = PropsRuntime<'shell.overlay'> & InjectFace<PreviewOverlayInjected> & PropsLocale<'md-preview'>;
@@ -22,5 +24,5 @@ export type PreviewOverlayProps = PropsRuntime<'shell.overlay'> & InjectFace<Pre
  * @param props - target hook, read RPC, dismissal, and the locale seat.
  * @returns the docked panel, or null while closed.
  */
-export declare function PreviewOverlay({ usePreviewTarget, close, read, t }: PreviewOverlayProps): import("react").JSX.Element | null;
+export declare function PreviewOverlay({ usePreviewTarget, close, read, write, t }: PreviewOverlayProps): import("react").JSX.Element | null;
 //# sourceMappingURL=PreviewOverlay.d.ts.map

package/lib/types/client/editor.d.ts

@@ -0,0 +1,16 @@
+/** Props the panel hands to the editor. */
+export interface MarkdownEditorProps {
+    /** Document text at edit-session start; a changed value remounts the editor. */
+    initialValue: string;
+    /** Reports every document change (the panel's draft). */
+    onChange: (value: string) => void;
+    /** Cmd/Ctrl-S from the editor's keymap. */
+    onSave: () => void;
+}
+/**
+ * Render one CodeMirror editor bound to the panel's edit session.
+ * @param props - initial document plus change and save callbacks.
+ * @returns the editor host element.
+ */
+export declare function MarkdownEditor({ initialValue, onChange, onSave }: MarkdownEditorProps): import("react").JSX.Element;
+//# sourceMappingURL=editor.d.ts.map

package/lib/types/client/locale.d.ts

@@ -9,6 +9,15 @@ export declare const zh: {
     'panel.empty': string;
     'panel.error': string;
     'panel.retry': string;
+    'panel.edit': string;
+    'panel.save': string;
+    'panel.cancel': string;
+    'panel.conflict.title': string;
+    'panel.conflict.reload': string;
+    'panel.conflict.force': string;
+    'panel.unsaved.title': string;
+    'panel.unsaved.discard': string;
+    'panel.unsaved.keep': string;
     'chip.preview': string;
     'chip.open': string;
     'action.label': string;

package/lib/types/protocol.d.ts

@@ -1,14 +1,23 @@
 /** Wire-level vocabulary shared by the Host service and the browser face. */
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
-/** One rendered-preview payload: the requested path and its full text content. */
+/** One rendered-preview payload: the requested path, its full text, and freshness. */
 export interface MdPreviewFile {
     /** The path exactly as requested by the caller (tool-produced spelling). */
     readonly path: string;
     /** The complete file content, capped by the configured byte limit. */
     readonly content: string;
+    /** Opaque fs freshness token; pass it back to `write` to guard the save. */
+    readonly fingerprint: string;
+}
+/** One persisted write: the saved path and its new freshness token. */
+export interface MdPreviewWriteResult {
+    /** The path exactly as requested by the caller. */
+    readonly path: string;
+    /** Freshness token of the file after the write; guards the next save. */
+    readonly fingerprint: string;
 }
 /** Stable failure codes carried by `RemoteError` across the wire. */
-export declare const MD_PREVIEW_FAILURE_CODES: readonly ["md-preview/bad-request", "md-preview/unknown-session", "md-preview/no-workspace", "md-preview/unsupported-extension", "md-preview/forbidden", "md-preview/not-found", "md-preview/too-large", "md-preview/unavailable"];
+export declare const MD_PREVIEW_FAILURE_CODES: readonly ["md-preview/bad-request", "md-preview/unknown-session", "md-preview/no-workspace", "md-preview/unsupported-extension", "md-preview/forbidden", "md-preview/not-found", "md-preview/too-large", "md-preview/conflict", "md-preview/unavailable"];
 /** One stable MdPreview failure code. */
 export type MdPreviewFailureCode = (typeof MD_PREVIEW_FAILURE_CODES)[number];
 declare module '@deepseek-ai/dsh-typert-protocol' {
@@ -27,6 +36,8 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
         'md-preview/not-found': {};
         /** The file exceeds the configured byte cap. */
         'md-preview/too-large': {};
+        /** The file changed since the read backing this write's fingerprint. */
+        'md-preview/conflict': {};
         /** The read itself failed. */
         'md-preview/unavailable': {};
     }

package/lib/types/remote.d.ts

@@ -8,7 +8,7 @@ import type { Context } from '@deepseek-ai/cordis';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import type { Config } from './config.ts';
-import type { MdPreviewFile } from './protocol.ts';
+import type { MdPreviewFile, MdPreviewWriteResult } from './protocol.ts';
 /** Whether a candidate extension passes the configured allowlist. */
 export declare function isAllowedExtension(path: string, allowedExtensions: readonly string[]): boolean;
 /**
@@ -37,6 +37,19 @@ export declare class MdPreviewService extends TypertRemoteService {
      * @throws RemoteError with a stable MdPreview failure code.
      */
     read(sessionId: SessionId, path: string, signal: AbortSignal): Promise<MdPreviewFile>;
+    /**
+     * Write one previewable file back into the session's workspace.
+     * @param sessionId - owning session; its header cwd roots the write.
+     * @param path - path as it appeared in the conversation.
+     * @param content - the complete new file content.
+     * @param fingerprint - freshness token from the backing read; required
+     *   unless `force` opts into an unconditional overwrite.
+     * @param force - skip the freshness guard (the conflict prompt's override).
+     * @param signal - caller cancellation carried through every fs call.
+     * @returns the saved path with its new freshness token.
+     * @throws RemoteError with a stable MdPreview failure code.
+     */
+    write(sessionId: SessionId, path: string, content: string, fingerprint: string | undefined, force: boolean, signal: AbortSignal): Promise<MdPreviewWriteResult>;
     /** Resolve one path against the workspace, with a plain not-found mapping. */
     private resolveWorkspacePath;
 }

package/lib/types/typert/remote-client.d.ts

@@ -1,10 +1,16 @@
 import type { RemoteResult, TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol';
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
-import type { MdPreviewFile } from '../protocol.ts';
+import type { MdPreviewFile, MdPreviewWriteResult } from '../protocol.ts';
 /** Browser face of the mounted `mdPreview` Remote namespace. */
 export interface MdPreviewRemote {
     /** Read one previewable document of a session's workspace. */
     read(sessionId: SessionId, path: string, signal?: AbortSignal): Promise<RemoteResult<MdPreviewFile>>;
+    /**
+     * Write one previewable document back into a session's workspace. Pass the
+     * `fingerprint` from the backing read to guard the save, or `force` to
+     * overwrite unconditionally (the conflict prompt's override).
+     */
+    write(sessionId: SessionId, path: string, content: string, fingerprint?: string, force?: boolean, signal?: AbortSignal): Promise<RemoteResult<MdPreviewWriteResult>>;
 }
 declare module '@deepseek-ai/dsh-typert-protocol' {
     interface TypertRemoteNamespaceMap {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benz-ai-x/dsh-md-preview",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "DSH markdown preview: clicking a markdown document in the conversation opens a rendered preview panel docked to the right of the chat.",
   "license": "MIT",
   "repository": {