dsh-diff-approval 0.2.0

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

@@ -0,0 +1,62 @@
+/** Pending-edit review UI dictionaries. */
+export declare const NS = "diff-approval";
+/** Simplified Chinese pending-edit review messages. */
+export declare const zh: {
+    'panel.title': string;
+    'panel.empty': string;
+    'panel.loading': string;
+    'panel.readFailed': string;
+    'panel.group.current': string;
+    'panel.group.others': string;
+    'panel.aria': string;
+    'panel.stats': string;
+    'panel.selectHint': string;
+    'panel.missing': string;
+    'panel.missingHint': string;
+    'panel.createHint': string;
+    'row.create': string;
+    'action.keep': string;
+    'action.revert': string;
+    'action.busy': string;
+    'action.prevDiff': string;
+    'action.nextDiff': string;
+    'action.copyRange': string;
+    'action.copied': string;
+    'status.kept': string;
+    'status.reverted': string;
+    'status.missing': string;
+};
+/** Translation keys owned by the pending-edit review namespace. */
+export type DiffApprovalKey = keyof typeof zh;
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Pending-edit review UI copy. */
+        'diff-approval': DiffApprovalKey;
+    }
+}
+/** English pending-edit review messages. */
+export declare const en: {
+    'panel.title': string;
+    'panel.empty': string;
+    'panel.loading': string;
+    'panel.readFailed': string;
+    'panel.group.current': string;
+    'panel.group.others': string;
+    'panel.aria': string;
+    'panel.stats': string;
+    'panel.selectHint': string;
+    'panel.missing': string;
+    'panel.missingHint': string;
+    'panel.createHint': string;
+    'row.create': string;
+    'action.keep': string;
+    'action.revert': string;
+    'action.busy': string;
+    'action.prevDiff': string;
+    'action.nextDiff': string;
+    'action.copyRange': string;
+    'action.copied': string;
+    'status.kept': string;
+    'status.reverted': string;
+    'status.missing': string;
+};

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

@@ -0,0 +1,24 @@
+/**
+ * Connection-channel port: narrows `ctx.connection.rpc.call` to this
+ * package's business verbs and validates the wire values it receives. The
+ * host half owns the channel; this module is the browser's one caller.
+ * @module dsh-diff-approval/client/port
+ */
+import type { ClientConnectionRpc, SessionId } from '@deepseek-ai/dsh-client-connection/client';
+import type { DiffApprovalActionValue, PendingFileDiff } from '../types.ts';
+/** The channel the host half registers and this port calls. */
+export declare const DIFF_APPROVAL_CHANNEL = "/diff-approval";
+/** This package's business verbs over the review channel. */
+export interface DiffApprovalPort {
+    /** Read one session's pending entries, oldest capture first. */
+    list(sessionId: SessionId): Promise<PendingFileDiff[]>;
+    /** Keep one operation. */
+    keep(sessionId: SessionId, id: string): Promise<DiffApprovalActionValue>;
+    /** Revert one operation. */
+    revert(sessionId: SessionId, id: string): Promise<DiffApprovalActionValue>;
+}
+/** Build the port over one generic RPC caller.
+ * @param rpc - the connection's channel caller.
+ * @returns the typed port.
+ */
+export declare function createDiffApprovalPort(rpc: ClientConnectionRpc): DiffApprovalPort;

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

@@ -0,0 +1,38 @@
+/**
+ * Reference labels for the selection toolbar: a file name plus a 1-based line
+ * range, using the short name when unambiguous and the full path otherwise.
+ * Pure derivation so the display rule is unit-testable without the panel.
+ * @module dsh-diff-approval/client/reference
+ */
+import type { PendingFileDiff } from '../types.ts';
+/**
+ * Last path segment of a file path, any separator style.
+ * @param path - the path to shorten.
+ * @returns the segment after the final separator.
+ */
+export declare function basenameOf(path: string): string;
+/**
+ * The path shown in a copied reference: the short name when no other listed
+ * file shares it, the full path otherwise.
+ * @param path - the selected file's path.
+ * @param files - every currently listed pending file.
+ * @returns the display path for a copied reference.
+ */
+export declare function copyDisplayPath(path: string, files: readonly PendingFileDiff[]): string;
+/**
+ * Format one line range as a reference suffix: a single line number, or the
+ * inclusive range when the selection spans more than one line.
+ * @param start - first selected line number.
+ * @param end - last selected line number (at least `start`).
+ * @returns the range label.
+ */
+export declare function lineRangeLabel(start: number, end: number): string;
+/**
+ * Build the clipboard text for a selected line range.
+ * @param path - the selected file's path.
+ * @param files - every currently listed pending file.
+ * @param start - first selected line number.
+ * @param end - last selected line number.
+ * @returns the `path:range` reference text.
+ */
+export declare function referenceOf(path: string, files: readonly PendingFileDiff[], start: number, end: number): string;

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

@@ -0,0 +1,28 @@
+/** The panel's injected business face and its observable snapshot. */
+import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
+import type { PendingFileDiff } from '../types.ts';
+/** What the panel reads and drives: the pending list plus in-flight entries. */
+export interface PendingDiffSnapshot {
+    /** Whether a list read has completed at least once. */
+    read: boolean;
+    /** Pending entries, one per file, oldest capture first. */
+    files: PendingFileDiff[];
+    /** A read failure's message; absent while the latest read succeeded. */
+    error?: string;
+    /** Entry ids whose keep/revert is in flight; their controls are disabled. */
+    busy: ReadonlySet<string>;
+}
+/** The injected face the panel component receives from the plugin body. */
+export interface PendingPanelFace {
+    hooks: {
+        /** Live pending-diff snapshot for the current page. */
+        pending: HostObservable<PendingDiffSnapshot>;
+    };
+    /** Read the pending list for the current session into the snapshot. */
+    onRefresh: (sessionId: SessionId | undefined) => void;
+    /** Keep one operation (remove it from the pending list). */
+    onKeep: (sessionId: SessionId, id: string) => Promise<void>;
+    /** Revert one operation (restore its prior content, or remove a created file). */
+    onRevert: (sessionId: SessionId, id: string) => Promise<void>;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Pending-diff observable store: the page's one reading of the host's pending
+ * list. Refreshed on panel open, on an interval while the panel stays open,
+ * and after each action; a successful action also removes its path locally so
+ * the row leaves without waiting for the next poll.
+ * @module dsh-diff-approval/client/store
+ */
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
+import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots';
+import type { PendingDiffSnapshot } from './slots.ts';
+import type { DiffApprovalPort } from './port.ts';
+/** The observable the panel reads and the plugin body drives. */
+export interface PendingDiffStore extends HostObservable<PendingDiffSnapshot> {
+    /** Re-read one session's pending list (an absent session empties the view). */
+    refresh: (sessionId: SessionId | undefined) => Promise<void>;
+    /** Keep one operation. */
+    keep: (sessionId: SessionId, id: string) => Promise<void>;
+    /** Revert one operation. */
+    revert: (sessionId: SessionId, id: string) => Promise<void>;
+    /** Drop every local fact (used on connection reset). */
+    reset: () => void;
+}
+/**
+ * Create the store over the review-channel port.
+ * @param port - the typed channel port.
+ * @returns the observable store.
+ */
+export declare function createPendingDiffStore(port: DiffApprovalPort): PendingDiffStore;

package/lib/types/client/whole-file-diff.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Whole-file diff model for the pending review viewer: one unified row list
+ * over the complete old and new contents, so the viewer renders the entire
+ * file with changed lines marked and unchanged lines as context. Pure
+ * derivation; the panel owns rendering. The `diff` package is browser-safe.
+ * @module dsh-diff-approval/client/whole-file-diff
+ */
+/** One rendered body line of the whole-file view. */
+export interface WholeFileDiffRow {
+    /** `context` lines are unchanged, `del`/`add` mark the removed/added sides. */
+    kind: 'context' | 'del' | 'add';
+    /** The line's text, without the terminating newline. */
+    text: string;
+    /** 1-based line number on the old side; absent on `add` lines. */
+    oldLine: number | undefined;
+    /** 1-based line number on the new side; absent on `del` lines. */
+    newLine: number | undefined;
+}
+/** The derived view: a flat row list plus the +/- totals. */
+export interface WholeFileDiff {
+    /** Body rows in file order; every line of both sides appears once. */
+    rows: WholeFileDiffRow[];
+    /** Number of removed lines. */
+    removed: number;
+    /** Number of added lines. */
+    added: number;
+}
+/**
+ * Compute the whole-file view between two contents. The context budget is the
+ * side lengths, so every hunk covers the file and unchanged lines survive as
+ * context rows; the `` patch marker is annotation
+ * and never becomes a row.
+ * @param oldText - the file content before the pending change.
+ * @param newText - the file content after the pending change.
+ * @returns the complete row list with totals.
+ */
+export declare function computeWholeFileDiff(oldText: string, newText: string): WholeFileDiff;

package/lib/types/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Pending-edit review, host half. Captures every successful `edit` and `write`
+ * tool result (an unscoped `tools/result` listener receives per-session tool
+ * executions because scoped emissions route through the shared root hook
+ * table), folds each operation into its file's entry in the
+ * {@link PendingDiffStore} (one entry per path), serves the `/diff-approval`
+ * connection RPC channel (list/keep/revert), and applies a revert by writing
+ * the entry's `oldText` back through `ctx.fs` (a created file's revert
+ * removes it, and a tracked file that has since disappeared is restored by
+ * its revert).
+ *
+ * Mount this row in any profile's `cordis.patch.yml`:
+ *
+ * ```yaml
+ * - insert:
+ *     - id: diff-approval
+ *       name: 'dsh-diff-approval'
+ *       # Optional: relocate durable pending state (defaults to
+ *       # <dshHome>/diff-approval/workspaces).
+ *       # config:
+ *       #   storageDir: ~/.dsh/diff-approval/workspaces
+ * ```
+ *
+ * Pending entries persist per (workspace, session) so an unhandled operation
+ * survives a harness restart; the list endpoint re-reads the live file, so a
+ * change or deletion made after the tracked operation is reported after
+ * restart exactly as it is mid-session.
+ *
+ * @module dsh-diff-approval
+ */
+import { Context } from '@deepseek-ai/cordis';
+export type { DiffApprovalActionOutcome, DiffApprovalActionValue, DiffApprovalListValue, PendingEntry, PendingEntryKind, PendingFileDiff, } from './types.ts';
+export { PendingDiffStore } from './pending.ts';
+export { PendingPersistence, defaultStorageDir } from './persist.ts';
+/** Stable Cordis plugin name. */
+export declare const name = "diff-approval";
+/** Services required before the review surface activates. */
+export declare const inject: string[];
+/** The connection RPC channel this plugin serves. */
+export declare const DIFF_APPROVAL_CHANNEL = "/diff-approval";
+/**
+ * Plugin configuration overridable from the profile's `cordis.patch.yml`.
+ */
+export interface DiffApprovalConfig {
+    /**
+     * Root directory for durable pending state, defaulting to
+     * `<dshHome>/diff-approval/workspaces`. Must be a non-empty string when set;
+     * `~` prefixes expand to the OS home.
+     */
+    storageDir?: string;
+}
+/**
+ * Mount the pending-edit review surface.
+ * @param ctx - Cordis context carrying the filesystem, connection, and workspace registry services.
+ * @param config - optional plugin configuration (`storageDir` relocates durable state).
+ */
+export declare function apply(ctx: Context, config?: DiffApprovalConfig): void;

package/lib/types/pending.d.ts

@@ -0,0 +1,60 @@
+/**
+ * In-memory pending-diff store: one entry per (session, path), holding the
+ * file's full set of unhandled changes as one cumulative span. Every later
+ * operation to a tracked path folds into its entry — `oldText` stays the
+ * earliest basis, `newText` takes the latest content — even when the chain
+ * breaks (an outside writer changed the file between operations): the list
+ * still shows one element per file. Pure state and transitions; the plugin
+ * body owns the `tools/result` observation, the RPC surface, and the
+ * filesystem I/O.
+ * @module dsh-diff-approval/src/pending
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { PendingEntry } from './types.ts';
+/**
+ * The pending-diff store. Keep/Revert decides one whole file at a time.
+ */
+export declare class PendingDiffStore {
+    private readonly entries;
+    private readonly pathIndex;
+    /** Merge one operation into the store, keyed by (session, path). */
+    private merge;
+    /**
+     * Fold one captured operation into its file's entry. A no-op (equal before
+     * and after) folds nothing.
+     * @param entry - the captured operation (id assigned by the caller).
+     * @returns whether the stored entry changed.
+     */
+    fold(entry: PendingEntry): boolean;
+    /**
+     * Merge persisted entries into the store, one per path after folding. An
+     * already-keyed live entry wins over a persisted one: the live entry is
+     * newer by construction (it was captured after the persisted state was
+     * written), so the path's whole persisted run is skipped.
+     * @param sessionId - the session the entries belong to.
+     * @param entries - persisted entries, oldest capture first, to fold in.
+     */
+    hydrate(sessionId: SessionId, entries: readonly PendingEntry[]): void;
+    /**
+     * Copy the session's entries, oldest capture first.
+     * @param sessionId - the session whose entries to list.
+     * @returns detached entries in capture order.
+     */
+    list(sessionId: SessionId): PendingEntry[];
+    /**
+     * Read one entry without removing it.
+     * @param sessionId - the owning session.
+     * @param id - the entry id.
+     * @returns the entry, or `undefined` when the pair has none.
+     */
+    get(sessionId: SessionId, id: string): PendingEntry | undefined;
+    /**
+     * Remove one entry.
+     * @param sessionId - the owning session.
+     * @param id - the entry id.
+     * @returns whether an entry was removed.
+     */
+    remove(sessionId: SessionId, id: string): boolean;
+    /** Total entry count across all sessions. */
+    get size(): number;
+}

package/lib/types/persist.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Durable pending-entry persistence under the harness home. One JSON file per
+ * workspace holds every session's entries, at
+ * `<storageDir>/<workspaceId>.json`; the default root is
+ * `<dshHome>/diff-approval/workspaces` and the plugin's `storageDir` config
+ * relocates it. `save` rewrites the whole workspace file so sibling sessions
+ * survive; a session with no entries leaves the file, and a workspace with no
+ * sessions loses its file. Writes are serialized per file, staged as a
+ * sibling temp file, and atomically renamed, so a crash leaves either the old
+ * or the new file. Missing files read as empty; corrupt content and unknown
+ * versions throw so the caller can fail loud instead of silently dropping
+ * persisted data.
+ * @module dsh-diff-approval/src/persist
+ */
+import type { PendingEntry } from './types.ts';
+/** Default persistence root: this plugin's own directory under the harness home. */
+export declare function defaultStorageDir(): string;
+/**
+ * File-backed pending entries keyed by (workspace, session).
+ */
+export declare class PendingPersistence {
+    private readonly root;
+    private readonly tails;
+    /**
+     * @param root - directory holding one JSON file per workspace.
+     */
+    constructor(root: string);
+    private fileOf;
+    /** Read one workspace file; a missing file reads as empty. */
+    private readWorkspace;
+    /** Stage the envelope as a sibling temp file and atomically rename it into place. */
+    private writeWorkspace;
+    /**
+     * Load one session's entries from its workspace file, oldest capture first.
+     * @param workspaceId - the owning workspace's stable id.
+     * @param sessionId - the session whose entries to load.
+     * @returns the persisted entries; empty when none were saved.
+     */
+    load(workspaceId: string, sessionId: string): Promise<PendingEntry[]>;
+    /**
+     * Replace one session's entries durably. Saves to one file are serialized;
+     * a previous save's failure does not block the next one.
+     * @param workspaceId - the owning workspace's stable id.
+     * @param sessionId - the session whose entries to replace.
+     * @param entries - the session's complete entry list, possibly empty.
+     * @returns resolution after the file is durable.
+     */
+    save(workspaceId: string, sessionId: string, entries: readonly PendingEntry[]): Promise<void>;
+}

package/lib/types/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Client-safe wire vocabulary shared by this package's host half and browser
+ * half. Type-only and Node-free.
+ * @module dsh-diff-approval/types
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+/**
+ * One file's pending entry in one session: the complete set of unhandled
+ * changes folded into a single cumulative span. `oldText` is the earliest
+ * captured basis and `newText` the latest captured content, so Keep/Revert
+ * decides the whole file at once.
+ */
+export interface PendingEntry {
+    /** Stable per-entry id (generated at capture; persisted with the entry). */
+    id: string;
+    /** The session whose agent ran the operation. */
+    sessionId: SessionId;
+    /** Backend-resolved display path (the tool's output `path`). */
+    path: string;
+    /** What the operation did: an in-place change or a file creation. */
+    kind: PendingEntryKind;
+    /** File content before the operation (empty for a creation). */
+    oldText: string;
+    /** File content after the operation. */
+    newText: string;
+    /** Epoch milliseconds of the capture. */
+    updatedAt: number;
+}
+/** What one captured operation did to the file. */
+export type PendingEntryKind = 'edit' | 'create';
+/**
+ * One listed pending entry: the stored operation plus the live file state the
+ * list endpoint computes by reading the file's current content.
+ */
+export interface PendingFileDiff extends PendingEntry {
+    /**
+     * Whether the file no longer exists (or cannot be resolved). Reverting a
+     * missing entry restores its old content, which recreates the file.
+     */
+    missing: boolean;
+    /**
+     * Whether the file's current content no longer equals the newest tracked
+     * content for its path. The cause is not attributed: any writer — another
+     * tool, an editor, a second process — may have changed it after the tracked
+     * operations. A Revert on a diverged entry overwrites whatever the file now
+     * holds.
+     */
+    diverged: boolean;
+}
+/** Value returned by the channel's list endpoint. */
+export interface DiffApprovalListValue {
+    /** Pending entries for the requested session, oldest capture first. */
+    files: PendingFileDiff[];
+}
+/** Outcome of one keep/revert request. */
+export type DiffApprovalActionOutcome = 'kept' | 'reverted' | 'missing';
+/** Value returned by the channel's keep and revert endpoints. */
+export interface DiffApprovalActionValue {
+    /** What the request did; `missing` means no pending entry existed. */
+    outcome: DiffApprovalActionOutcome;
+}

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "dsh-diff-approval",
+  "version": "0.2.0",
+  "description": "DeepSeek Harness plugin: pending-edit review with whole-file diff and Keep/Revert",
+  "author": "Wu Zhiwei",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/9087/dsh-diff-approval.git"
+  },
+  "homepage": "https://github.com/9087/dsh-diff-approval#readme",
+  "bugs": {
+    "url": "https://github.com/9087/dsh-diff-approval/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-sidebar"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc -b tsconfig.json",
+    "build": "tsc -b tsconfig.json && tsdown --env.DSH_BUILD_FACE client",
+    "test": "vitest run",
+    "prepare": "tsc -b tsconfig.json && tsdown --env.DSH_BUILD_FACE client",
+    "release": "release-it"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.5",
+    "@shikijs/langs": "^4.4.3",
+    "diff": "^9.0.0",
+    "shiki": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.1",
+    "@deepseek-ai/dsh-client-connection": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-runtime": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-ui-sidebar": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-fs": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-host-apiproxy": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-session": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-workspace": ">=0.1.0-rc.5",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-fs": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-host-apiproxy": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-workspace": "^0.1.0-rc.5",
+    "@release-it/conventional-changelog": "^12.0.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "~18.3.1",
+    "jsdom": "^29.1.1",
+    "lightningcss": "^1.32.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "release-it": "^21.0.2",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}