dsh-diff-approval 0.29.0 → 0.30.1

package/lib/types/types.d.ts

@@ -4,6 +4,7 @@
  * @module dsh-diff-approval/types
  */
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { CommentLineRange } from './comment-lines.ts';
 /**
  * One file's pending entry, global and unique per `path`: the complete set of
  * unhandled changes folded into a single cumulative span across every session
@@ -72,6 +73,42 @@ export interface DiffApprovalListValue {
      * told about it simply finds the list gone later, with nothing to explain it (issue #6).
      */
     persistError?: string | undefined;
+    /**
+     * The last failure to write a COMMENT file, or absent while those writes are working.
+     * Separate from `persistError` because the two live in different files and one may be
+     * writable while the other is not; a comment that only exists in memory is erased by a
+     * restart exactly like an unpersisted list, and the panel says so once.
+     */
+    commentPersistError?: string | undefined;
+    /**
+     * The requested session's comment threads, oldest first. They ride the list read
+     * so a poll sees the entries and the comments that hang off them in one
+     * consistent snapshot — a comment list that arrived on its own channel could
+     * name an entry the same read had already dropped.
+     */
+    comments: CommentRecord[];
+    /**
+     * The new-file lines each comment sits on NOW, keyed by comment id — where its quote was found in
+     * the entry's current content (see `resolveCommentLines`, which both halves import).
+     *
+     * DERIVED on every read and never persisted: a resolved line written to the comment file would
+     * outlive the content it was true of, and a stale stored figure is worse than none. A comment the
+     * host cannot place — its quote is gone from the content — is simply ABSENT here, and a caller
+     * then falls back to `record.anchor`: the line the comment was WRITTEN on, which is what an
+     * outdated thread shows anyway. Both panes draw this one map, so the list and the open card
+     * cannot name two lines for one comment (issue: one comment read `[382]` in the list while its
+     * card read 378, because only the open file's pane had resolved it).
+     */
+    commentLines: Record<string, CommentLineRange>;
+    /** Bumped on every comment change, so a poller can tell "nothing new" from "re-read". */
+    commentsRevision: number;
+    /**
+     * The answer text for the questions the session has answered, keyed by the
+     * question's `requestId` (see `CommentAsk`). DERIVED on every read from the
+     * session's own transcript and never stored: the transcript is the one source of
+     * truth for what the agent said, so a stored copy could only ever disagree with it.
+     */
+    commentAnswers: Record<string, string>;
 }
 /** What the open endpoint asks the OS to do with a file. */
 export type DiffApprovalOpenAction = 'open' | 'reveal';
@@ -223,3 +260,142 @@ export interface DiffApprovalAddValue {
     /** Failure detail for `outcome: 'failed'`. */
     message?: string | undefined;
 }
+/** The rows a comment was written about, as new-file line numbers. */
+export interface CommentAnchor {
+    /** First new-file line of the annotation. */
+    startLine: number;
+    /** Last new-file line of the annotation. */
+    endLine: number;
+}
+/** The gutter pair of one quoted line, kept so an outdated thread can lay its quote out. */
+export interface CommentQuoteLine {
+    /** Old-file number, absent on a row the old side does not have (an added line). */
+    old?: number | undefined;
+    /** New-file number — the second gutter — absent on a removed line. */
+    new?: number | undefined;
+    /** Which side of the change the row was on when the thread quoted it. */
+    kind?: 'add' | 'del' | 'context' | undefined;
+}
+/** One question asked inside a comment thread, and what became of it. */
+export interface CommentAsk {
+    /**
+     * The identity of the prompt request this question was submitted as. The session
+     * persists it on the exact user message it accepted (`source.rpcId`), so it is the
+     * join key between the question and its message in the transcript — and it is the
+     * idempotency key: a request carrying it again is the same submission, not a second
+     * one. Minted by this plugin, so a question knows its own message before the session
+     * has admitted anything.
+     */
+    requestId: string;
+    /**
+     * The question's own words, as the reader typed them — without the marker, the
+     * `(path:lines)` reference and the answer rules that wrap them in the submitted
+     * prompt. The prompt is what the agent is asked; this is what the thread shows, so a
+     * follow-up is drawn as the words that were written. Set for every question asked
+     * now; absent only on a record written before this field existed, whose words are
+     * not recoverable from anywhere.
+     */
+    text?: string | undefined;
+    /** The turn that claimed the message, when the session reported one. */
+    turn?: number | undefined;
+    /**
+     * The session discarded the message before any turn claimed it (a stopped turn, a
+     * cancelled queue). Nothing is coming, and the reader is told so rather than left
+     * waiting — this is what the client used to infer from its own queue snapshot.
+     */
+    dropped?: boolean | undefined;
+    /**
+     * The turn that claimed this question has stopped. A question whose turn is over and
+     * that the transcript shows no answer for was cut off: the reader is told that and
+     * offered another try, instead of a block that waits forever on a turn that ended.
+     * Only ever set when true.
+     */
+    ended?: boolean | undefined;
+}
+/**
+ * One comment thread's durable record: the annotation, where it was written, and the
+ * questions asked inside it.
+ *
+ * The ANSWER's text is deliberately absent: `asks[].requestId` names each question's
+ * message, and the session transcript stays the one source of truth for what the agent
+ * said — a client renders an answer by reading the transcript at that id, and the list
+ * read carries the derived text keyed by the same id. Row indices are absent too: they
+ * are model-relative and meaningless after a reload, so the record keeps new-file LINE
+ * numbers plus the quote the reader was looking at, which is what a re-anchor needs.
+ */
+export interface CommentRecord {
+    /** Stable comment id, minted by the host when the annotation is written. */
+    id: string;
+    /** The session the comment belongs to: comments never cross sessions. */
+    sessionId: SessionId;
+    /** The pending entry the comment hangs off (its id, which is its path). */
+    entryId: string;
+    /** The entry's display path when the comment was written. */
+    path: string;
+    /** The lines the annotation was made on, as NEW-file line numbers: the numbers every label,
+     *  jump and reference shows, and the ones the host resolves the quote against. */
+    anchor: CommentAnchor;
+    /** The anchored lines as they read then (the re-anchor fingerprint). */
+    quote: string;
+    /** `quote` with one row of context on each side, as it read then. */
+    quoteContext?: string | undefined;
+    /** The gutter numbers of `quote`'s lines, in the same order. */
+    quoteLines?: CommentQuoteLine[] | undefined;
+    /** The annotation itself: what the reader wrote. */
+    text: string;
+    /**
+     * Who wrote `text`, when it was not the reader.
+     *
+     * The panel draws a thread's first turn as the reader's own words, which is what it is for every
+     * comment the reader makes. An AGENT-authored annotation is the other direction (see
+     * `annotate-tool.ts`): the panel is showing the agent's explanation on those lines, and drawing it as
+     * something the reader said would put words in their mouth. Absent means the reader.
+     */
+    author?: 'agent' | undefined;
+    /** Epoch milliseconds the comment was written. */
+    createdAt: number;
+    /** Epoch milliseconds of the last change to this record. */
+    updatedAt: number;
+    /** The questions asked in this thread, oldest first; empty until one is asked. */
+    asks?: CommentAsk[] | undefined;
+}
+/** Value returned by the channel's comment-add endpoint. */
+export interface DiffApprovalCommentAddValue {
+    /**
+     * What the request did. `missing` means the named entry is not in the session's
+     * list — a comment on a file that has left it is refused rather than stored,
+     * which is the first of the two guards against a comment outliving its entry.
+     */
+    outcome: 'added' | 'missing';
+    /** The stored comment; present only when `outcome` is `added`. */
+    comment?: CommentRecord | undefined;
+}
+/** Value returned by the channel's comment-remove endpoint. */
+export interface DiffApprovalCommentRemoveValue {
+    /** What the request did; `missing` means no such comment in that session. */
+    outcome: 'removed' | 'missing';
+}
+/** Value returned by the channel's comment-remove-many endpoint. */
+export interface DiffApprovalCommentRemoveManyValue {
+    /**
+     * How many of the named comments the request dropped.
+     *
+     * The ids that were not there are not named back: the reader asked for those comments to be
+     * gone, and one that another client already ended is gone. What is left to say is how many
+     * the request itself did, which is what a test and a log can hold on to.
+     */
+    removed: number;
+}
+/** Value returned by the channel's comment-ask endpoint. */
+export interface DiffApprovalCommentAskValue {
+    /**
+     * What the request did. `missing` means no such comment in that session;
+     * `no-agent` means the session has no live agent to ask (it ended, or this host
+     * drives no agent for it), and `failed` carries `message`.
+     */
+    outcome: 'asked' | 'missing' | 'no-agent' | 'failed';
+    /** The request identity the comment now carries (present when `outcome` is `asked`). */
+    requestId?: string | undefined;
+    /** Failure detail for `outcome: 'failed'`. */
+    message?: string | undefined;
+}

package/lib/types/vcs.d.ts

@@ -9,13 +9,17 @@
  * directory.
  *
  * Scope of one import (mirrors the panel's preferences):
- * - modified files (git: working tree vs index — "仅未暂存"; svn: vs BASE;
- *   p4: opened edits), imported as `edit` (old = baseline, new = working);
+ * - modified files, imported as `edit` (old = baseline, new = working). The GIT baseline is the
+ *   last commit, not the index: this list answers "what is not committed yet", so a change the
+ *   reader already `git add`ed is as much a review item as one they have not — staging is a step
+ *   towards a commit, not a decision this panel records (`git diff HEAD` semantics). svn compares
+ *   against BASE and p4 against `#have`, which are their "last commit" already;
  * - deleted files, imported as `edit` with an empty new side (revert restores);
- * - new/untracked files (git `??`, svn `?`, p4 not-yet-opened files), imported
- *   as `create` ONLY when the untracked preference is on. For p4 that means a
- *   full workspace scan (`p4 status`, which can be slow); with the preference
- *   off only already-opened files are read.
+ * - new/untracked files, imported as `create` ONLY when the untracked preference is on: git `??`
+ *   (never added), svn unversioned, p4 not-yet-opened. For p4 that means a full workspace scan
+ *   (`p4 status`, which can be slow); with the preference off only already-opened files are read.
+ *   A file that is new but already under version control (git `A`, svn `added`) needs no
+ *   preference: it is an uncommitted change like any other.
  * @module dsh-diff-approval/vcs
  */
 /** The version-control systems this integration knows. */
@@ -36,26 +40,47 @@ export interface VcsChange {
     /** Working content; empty for a deleted file. */
     newText: string;
 }
-/** The subset of `ctx.shell`'s executor this module calls (kept structural so
- * the module stays dependency-light and testable with a fake). */
+/**
+ * The subset of `ctx.shell`'s executor this module calls — for BOTH eras of that seam.
+ *
+ * Kept structural so the module stays dependency-light and testable with a fake, and both eras are here
+ * because the seam changed under this plugin. Up to 0.1.6 the executor was `resolve(request)` +
+ * `run(spec)`, and 0.1.7 replaced `run` with `execute(spec)`, which resolves to a PROCESS HANDLE whose
+ * foreground projection is `result()` (measured in `@deepseek-ai/dsh-shell`: `abstract resolve`,
+ * `abstract execute`, `ShellExecution.result(): Promise<ShellRunResult>`). On 0.1.7 the old shape failed
+ * with `shell.run is not a function` — the whole text the import button could show — so both are
+ * accepted, and an executor offering neither is reported by the methods it does have.
+ */
 export interface ShellExecutorLike {
-    resolve(request: {
-        command: string;
-        workdir?: string | undefined;
-        timeoutMs?: number | undefined;
-        signal?: AbortSignal | undefined;
-        /** Foreground stdout capture budget in bytes; absent uses the executor's cap. */
-        stdoutMaxBytes?: number | undefined;
-    }): unknown;
-    run(spec: unknown): Promise<{
-        exitCode: number | null;
-        stdout: {
-            text: string;
-        };
-        stderr: {
-            text: string;
-        };
-    }>;
+    /** 0.1.7: apply the implementation's defaults and caps before execution. */
+    resolve?(request: ShellExecRequestLike): unknown;
+    /** 0.1.7: prepare and spawn; the returned handle carries `result()`. */
+    execute?(spec: unknown): Promise<ShellExecutionLike>;
+    /** Up to 0.1.6: resolve and run in one call. */
+    run?(spec: unknown): Promise<ShellRunResultLike>;
+}
+/** One command, as the seam's request takes it (`workdir`/`timeoutMs` are required only on the spec). */
+interface ShellExecRequestLike {
+    command: string;
+    workdir: string;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+    /** Foreground stdout capture budget in bytes; absent uses the executor's cap. */
+    stdoutMaxBytes?: number | undefined;
+}
+/** 0.1.7's execution handle, reduced to the part this module reads. */
+interface ShellExecutionLike {
+    result?: (() => Promise<ShellRunResultLike>) | undefined;
+}
+/** The outcome this module reads, in the shape both eras report it. */
+interface ShellRunResultLike {
+    exitCode: number | null;
+    stdout: {
+        text: string;
+    };
+    stderr: {
+        text: string;
+    };
 }
 /** Reads one file's working content; undefined when the file is absent. */
 export type VcsFileReader = (absolutePath: string) => Promise<string | undefined>;
@@ -95,3 +120,4 @@ export declare function detectVcsRoot(start: string): VcsRoot | undefined;
  * @returns the changes; an absent/unusable VCS surfaces as a thrown error.
  */
 export declare function listVcsChanges(input: VcsImportInput): Promise<VcsChange[]>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-diff-approval",
-  "version": "0.29.0",
+  "version": "0.30.1",
   "description": "DeepSeek Harness plugin: pending-edit review with whole-file diff and Keep/Revert",
   "packageManager": "pnpm@11.21.0",
   "author": "Wu Zhiwei",
@@ -48,6 +48,7 @@
         "@deepseek-ai/dsh-client-runtime",
         "@deepseek-ai/dsh-client-connection",
         "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
         "@deepseek-ai/dsh-client-ui-sidebar"
       ],
       "platform": "web"
@@ -57,6 +58,7 @@
     "typecheck": "tsc -b tsconfig.json",
     "build": "tsc -b tsconfig.json && tsdown --env.DSH_BUILD_FACE client",
     "test": "vitest run",
+    "e2e": "playwright test",
     "compat": "node scripts/dsh-compat.mjs",
     "fonts:check": "python -m scripts.fonts.build --check",
     "fonts:plan": "python -m scripts.fonts.build --plan",
@@ -90,6 +92,7 @@
     "@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",
+    "@playwright/test": "^1.63.0",
     "@release-it/conventional-changelog": "^12.0.0",
     "@testing-library/react": "^16.1.0",
     "@types/node": "^22.0.0",

package/lib/types/client/chat-bridge.d.ts

@@ -1,70 +0,0 @@
-/**
- * The panel's one connection to the session's chat: send one prompt, and watch
- * the transcript so a discussion can show its answer where it was asked.
- *
- * Everything here is deliberately defensive. The surfaces it uses (the scoped
- * `conversation` input face, the `sessions` binding, the `chat` view target) are
- * public types but not plugin-documented API, so a build that lacks one reports
- * "unavailable" and the caller falls back to the composer route it already had.
- *
- * @module dsh-diff-approval/client/chat-bridge
- */
-import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
-import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
-/** One human-visible transcript node, reduced to what a discussion shows. */
-export interface ChatNodeView {
-    /** `user`, `assistant`, or the node's own kind for anything else. */
-    kind: string;
-    /** The node's text blocks joined; empty for nodes that carry no prose. */
-    text: string;
-    /**
-     * The runtime froze this assistant node when the turn was stopped (`interrupted` on
-     * the durable node). A stopped turn leaves one of these, often with no text, which is
-     * how a caller can tell "the answer was cut off" from "the answer is still coming".
-     * Only ever set when true.
-     */
-    interrupted?: boolean;
-}
-/** What a discussion needs to know about the session's chat right now. */
-export interface ChatView {
-    /** A turn is running for this session. */
-    running: boolean;
-    /** The durable transcript, in order. */
-    nodes: readonly ChatNodeView[];
-    /** The in-flight assistant text, or '' when nothing is streaming. */
-    partial: string;
-    /** The session's recorded prompt error, when there is one. */
-    error: string | undefined;
-    /**
-     * The prompts the session is still holding — its inbox queue plus the local
-     * submission echoes that have not become durable yet — or `undefined` on a build
-     * that does not publish them. A prompt that is not in the transcript is either one
-     * of these (still waiting) or gone (dropped with a stopped turn); without the
-     * evidence a caller can only keep waiting.
-     */
-    queued: readonly string[] | undefined;
-}
-/** The session chat as the panel uses it. */
-export interface ChatBridge {
-    /**
-     * Send one prompt into the session as a real turn.
-     * @param sessionId - the session to prompt.
-     * @param text - the prompt text, sent verbatim.
-     * @returns whether the send verb was available (false means "not sent").
-     */
-    ask: (sessionId: SessionId, text: string) => boolean;
-    /**
-     * Watch the session's transcript and turn state.
-     * @param sessionId - the session to watch.
-     * @param listener - called with the current view, then on every change.
-     * @returns the unsubscribe function.
-     */
-    watch: (sessionId: SessionId, listener: (view: ChatView) => void) => () => void;
-}
-/**
- * Build the bridge over the client context. Every verb takes the session it
- * addresses, so one bridge serves whichever session the panel is showing.
- * @param ctx - the plugin's client context.
- * @returns the bridge (its verbs report unavailability instead of throwing).
- */
-export declare function createChatBridge(ctx: ClientContext): ChatBridge;