dsh-diff-approval 0.30.1 → 0.31.0

package/lib/types/pending.d.ts

@@ -51,10 +51,11 @@ export declare class PendingDiffStore {
     /** Fold a captured entry into the path's single global entry. */
     private merge;
     /**
-     * Combine a stored entry and a new capture. `oldText` comes from the earlier
-     * capture (the file's original basis), `newText` from the later (latest
-     * content), and the session set is the union — so the entry always spans the
-     * whole pending change regardless of which session contributed which part.
+     * Combine a stored entry and a new capture. `oldText` comes from the earlier capture (the file's
+     * original basis) — except where that capture was the file's creation and this one edits it, when
+     * the creation's own content becomes the basis — and `newText` from the later (latest content).
+     * The session set is the union, so the entry always spans the whole pending change regardless of
+     * which session contributed which part.
      */
     private mergeEntry;
     /**
@@ -82,6 +83,15 @@ export declare class PendingDiffStore {
     /**
      * Advance one entry's tracked content after a block-level keep/revert. The
      * entry keeps its path; only the given side's text and capture time move.
+     *
+     * A keep that advances `oldText` also ends the entry's life as a creation. `earlierVersion` is the fact
+     * "this file did not exist before", and once part of the file has been accepted there IS an earlier
+     * version to restore — what the reader kept. The whole-file action must therefore become 回退, not 删除:
+     * deleting would throw away the part they just accepted. (Leaving the field alone kept a partly-kept new
+     * file offering to delete itself, which is what sent the reader here.)
+     *
+     * Every caller of this is a reader action — a block keep or revert, a refresh from version control — so it
+     * also takes the unseen dot down: the reader has just handled this file.
      * @param path - the file path.
      * @param patch - the side to advance (`oldText` for keep, `newText` for revert).
      * @returns whether the entry changed.
@@ -90,6 +100,22 @@ export declare class PendingDiffStore {
         oldText?: string;
         newText?: string;
     }): boolean;
+    /**
+     * Mark paths the reader has now seen — the file was opened, or its row was acted on. The dot is about
+     * attention rather than content, so this and the entry leaving the list are the only ways it goes out, and
+     * nothing brings it back except a new capture.
+     * @param paths - one path, or several.
+     * @returns whether anything changed.
+     */
+    markSeen(paths: string | readonly string[]): boolean;
+    /**
+     * Raise the dot for paths whose content moved WITHOUT the reader asking — a writer outside the panel, a
+     * second process. The capture sites set the field on the entry they fold; this is for the changes the
+     * plugin notices by itself while refreshing, which do not come through a capture.
+     * @param paths - one path, or several.
+     * @returns whether anything changed.
+     */
+    markUnseen(paths: string | readonly string[]): boolean;
     /**
      * Restore one entry exactly as given (an undo/redo replays a snapshot). The
      * entry is inserted or replaced by path.

package/lib/types/types.d.ts

@@ -5,6 +5,26 @@
  */
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import type { CommentLineRange } from './comment-lines.ts';
+/**
+ * Where a session sits in the lineage a merged view groups by.
+ *
+ * Read off the session's own header when an entry is CAPTURED (`SessionHeader.parentSession`, `.origin`,
+ * `.delegationDepth`, `.cwd`) and carried on the entry, so a client can group without a second wire
+ * field. Every part is optional and absent when the header — or that one field of it — was not
+ * available: an ordinary root session has no parent by design, and a host older than these header
+ * fields reports none of them. An unknown lineage is recorded as unknown; guessing a root would file a
+ * session under the wrong one. Nothing reads this yet: the record is written for the merged view to use.
+ */
+export interface SessionLineage {
+    /** The session this one was forked from, or absent for an ordinary root. */
+    parentSessionId?: SessionId | undefined;
+    /** The header's coarse product classification — `'subagent'` for a subagent child. */
+    origin?: string | undefined;
+    /** How deep below its root the session was delegated, when the shell reports it. */
+    delegationDepth?: number | undefined;
+    /** The session's own working directory, when its header names one. */
+    cwd?: string | undefined;
+}
 /**
  * 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
@@ -17,8 +37,12 @@ export interface PendingEntry {
     id: string;
     /** 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;
+    /**
+     * Whether there is an earlier version of the file to restore: `'file'` when
+     * the whole-file action writes the earlier text back, `'none'` when the file
+     * did not exist, so the whole-file action deletes it.
+     */
+    earlierVersion: PendingEntryKind;
     /** File content before the first captured operation (empty for a creation). */
     oldText: string;
     /** File content after the latest captured operation. */
@@ -29,14 +53,70 @@ export interface PendingEntry {
     sessionId: SessionId;
     /** Every session that touched the file (drives the per-session list filter). */
     sessionIds: SessionId[];
+    /**
+     * Where this entry's session sits in its lineage, as the shell reported it when the entry was
+     * CAPTURED — display-only data for a merged view. The entry keeps its real `sessionId`/`sessionIds`
+     * either way: grouping by lineage never rewrites who did the work. Absent on a record written before
+     * this field existed, on a session whose header carried none of it, and on an ordinary root (which
+     * has no parent by design) — so a reader must treat absent as "not known", never as "a root".
+     */
+    lineage?: SessionLineage | undefined;
+    /**
+     * Whether a change the reader has not looked at yet arrived on this path — the dot beside its row. Set
+     * when an agent operation (or an agent-side admission) changes the entry, cleared when the reader opens
+     * the file or acts on the row, and deliberately NOT part of an undo snapshot: a snapshot restores
+     * CONTENT, and having seen something is not content.
+     */
+    unseen?: boolean | undefined;
 }
-/** What one captured operation did to the file. */
-export type PendingEntryKind = 'edit' | 'create';
+/** Whether an entry has an earlier version of its file to restore. */
+export type PendingEntryKind = 'file' | 'none';
+/**
+ * Which way a row's other contributor sits relative to the session LISTING it, walked from the recorded
+ * subagent parent links (see `lineageView` on the host).
+ *
+ * `child` — the other session descends from the lister (the lister is on the other's upward chain).
+ * `parent` — the other session is ABOVE the lister (the lister descends from it). It means an ANCESTOR,
+ *   possibly more than one hop up, not only the direct parent: the Chinese 上级 says exactly that without
+ *   ambiguity, so the English copy and this name keep that meaning.
+ * `sibling` — same lineage root, neither is on the other's chain (two children of one parent, say).
+ * `mixed` — non-requester owners of DIFFERENT directions: never one of them, and never a guess at one.
+ */
+export type LineageDirection = 'child' | 'parent' | 'sibling' | 'mixed';
 /**
  * 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 this row reached the list through the LINEAGE MERGE rather than because the LISTING session
+     * itself touched it. The HOST computes it per read (`listWithState`), because only the host can walk a
+     * lineage — the client cannot, and must not try: it is what lets the panel show a child session's row
+     * without re-deriving the merge in the browser. Absent on a host older than the merge and absent on a
+     * row this session touched, so a client that does not know the field behaves exactly as it did before.
+     */
+    viaLineage?: boolean | undefined;
+    /**
+     * Whether some session OTHER than the listing one — and inside the listing session's lineage — also
+     * contributed to this row, so a row the session touched itself still says a child had a hand in it. Kept
+     * apart from `viaLineage` on purpose: that one answers "why is this row here" (visibility), this one
+     * answers "whose change does it carry" (the mark). Only a session in the same lineage counts: entries are
+     * keyed by path globally, so an unrelated session's touch of the same file must never be called a child's
+     * work. Host-computed per read (`listWithState`), absent on a host older than the mark.
+     */
+    hasChildContribution?: boolean | undefined;
+    /**
+     * WHICH WAY the row's other contributor stands, so the marker's sentence tells the truth from the seat it
+     * is drawn in: the same row is a child's change in its parent's panel and a parent's change in its
+     * child's. Host-computed per read from the SAME recorded parent links the merge walks, and carried to the
+     * browser like `viaLineage` — the client never infers lineage.
+     *
+     * Absent whenever no mark applies (the lister is the only contributor), and absent on a host older than
+     * this field — in which case the client says the neutral sentence rather than picking a direction.
+     * `mixed` is likewise the honest answer when the row carries non-requester owners of different
+     * directions; it is never resolved to one of them.
+     */
+    lineageDirection?: LineageDirection | undefined;
     /**
      * Whether the file no longer exists (or cannot be resolved). Reverting a
      * missing entry restores its old content, which recreates the file.
@@ -110,6 +190,47 @@ export interface DiffApprovalListValue {
      */
     commentAnswers: Record<string, string>;
 }
+/**
+ * Value returned by the channel's `list-count` endpoint: how many rows a full `list` read for the same
+ * session would carry.
+ *
+ * The badge needs a number once a second, and a full read is enormously more than a number: it ships
+ * every visible entry's whole `oldText`+`newText` (measured at 6.77 MB across 302 stored entries, with
+ * single rows at 1.2-1.6 MB). So this is the LIGHT read — the same visibility rule (`lineageView().sees`
+ * for the requesting session) and the same `ensureLoaded` discipline as `list`, and nothing else.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO: it reads no file content (`ctx.fs.readText` is never called), so it
+ * computes no diff, adopts no external change, creates no undo checkpoint, sweeps no comments and does not
+ * persist anything. It sends no texts, no comment records, no `commentLines`, no revision and no errors —
+ * `count` is the whole answer.
+ *
+ * WHAT THAT COSTS THE CALLER: a count is not a list. It asks `stat` about each visible row (the cheap
+ * liveness signal) and drops a row whose file is GONE, which is the one state `list` also drops without
+ * reading — but a file that is present and merely unreadable cannot be told from a readable one without
+ * reading it, so it is counted here and dropped by the next full read. The number can therefore be one
+ * poll stale, and the next full read is what corrects it; nothing else in this value is authoritative.
+ */
+export interface DiffApprovalListCountValue {
+    /** How many rows this session's next full `list` read would carry. */
+    count: number;
+}
+/**
+ * Value returned by the channel's `update-check` endpoint: whether a newer release of
+ * this package is published, and what changed since the installed one.
+ *
+ * The comparison itself is the HOST's (`src/version.ts`): it is the side that knows the
+ * installed version, and the only side that can reach the registry (the browser cannot —
+ * `registry.npmjs.org` sends no CORS header). `newer` is therefore an ANSWER, not a hint:
+ * the client never re-derives it, so exactly one rule decides "is this newer".
+ */
+export interface DiffApprovalUpdateValue {
+    /** The installed version as this host read it; empty when it could not be read at all. */
+    current: string;
+    /** The published version; absent when the registry was unreachable or answered nonsense. */
+    latest?: string | undefined;
+    /** Whether `latest` is STRICTLY newer than `current`; always false when either is unparsable. */
+    newer: boolean;
+}
 /** What the open endpoint asks the OS to do with a file. */
 export type DiffApprovalOpenAction = 'open' | 'reveal';
 /** Value returned by the channel's open endpoint. */
@@ -287,6 +408,20 @@ export interface CommentAsk {
      * has admitted anything.
      */
     requestId: string;
+    /**
+     * The SESSION THIS QUESTION WAS SUBMITTED INTO — the transcript that will carry its answer.
+     *
+     * It is not always the comment's own `sessionId`: once a lineage reads every seat's threads (`list`
+     * fans the read out across the lineage root), any seat may ask a question on a thread another seat
+     * wrote, and the prompt goes into the seat the human is using. The answer fold then has to know which
+     * transcript to read for which question, and turn numbers are only unique WITHIN one session — so this
+     * is what `markTurnEnded` matches on as well.
+     *
+     * Absent on a question asked before this field existed, when the only session a question could have
+     * gone to was the comment's own: the fold reads the comment's `sessionId` for those (see
+     * `askTranscript` in the comment store), which is exactly where their answers already are.
+     */
+    sessionId?: SessionId | undefined;
     /**
      * 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
@@ -352,12 +487,53 @@ export interface CommentRecord {
      * something the reader said would put words in their mouth. Absent means the reader.
      */
     author?: 'agent' | undefined;
+    /**
+     * Which CLASS of annotation this one belongs to, as the calling agent named it (see
+     * `annotate-tool.ts`'s `category` argument).
+     *
+     * The panel draws it as a coloured round dot on the comment list's row, so an agent that annotates
+     * several passes or topics can be told apart at a glance. OPAQUE to every reader of this record: the
+     * panel hashes the string to pick a colour and shows the string itself in the mark's own label, and
+     * nothing parses it, orders it or validates its shape. Absent means "no class, no dot" — which is
+     * every comment the reader writes themselves, and every annotation written before this field existed.
+     * Short by construction (the tool trims it and caps it at `MAX_ANNOTATION_CATEGORY_CHARS`).
+     */
+    category?: string | 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;
+    /**
+     * Whether something the reader has not looked at yet arrived in this thread — the dot beside its
+     * card. Set when an agent-authored annotation is written or when an answer lands in the thread,
+     * cleared when the card comes into view, and deliberately NOT part of an undo snapshot: a snapshot
+     * restores CONTENT, and having seen something is not content.
+     */
+    unseen?: boolean | undefined;
+    /**
+     * The answer text the reader has already been told about, keyed by question id.
+     *
+     * The answer's text is deliberately absent from this record (see the doc above) — the transcript is
+     * the one source
+     * of truth for what the agent said — but "is this the answer I have already seen?" cannot be
+     * answered from the transcript alone, because a read has nothing to compare against. This is the
+     * baseline the comparison takes: the host writes the current answer here when the card goes out of
+     * the reader's way, and an answer whose text differs from this is news. Persisted rather than held
+     * in memory, so a restart does not light a dot the reader had already cleared.
+     */
+    answerSeen?: Record<string, string> | undefined;
+    /**
+     * The latest answer text the host has observed for each question, keyed by question id.
+     *
+     * The other half of the comparison above, and kept apart from it on purpose: this follows what the
+     * agent said, while `answerSeen` follows what the reader has looked at. An answer whose text differs
+     * from its stored `answerSeen` entry is what lights the dot — and an answer that disappears leaves
+     * this empty rather than looking like a change, so a transcript that cannot be read never re-lights
+     * a thread the reader already read.
+     */
+    answerNow?: Record<string, string> | undefined;
 }
 /** Value returned by the channel's comment-add endpoint. */
 export interface DiffApprovalCommentAddValue {

package/lib/types/vcs.d.ts

@@ -34,7 +34,8 @@ export interface VcsRoot {
 export interface VcsChange {
     /** Absolute path of the changed file (inside the workspace). */
     path: string;
-    kind: 'edit' | 'create';
+    /** Whether an earlier version of the file exists: `'file'` restores it, `'none'` deletes the file. */
+    earlierVersion: 'file' | 'none';
     /** Baseline (pre-change) content; empty for a brand-new file. */
     oldText: string;
     /** Working content; empty for a deleted file. */

package/lib/types/version.d.ts

@@ -0,0 +1,162 @@
+/**
+ * "Is a newer release published?" — the host's half of the panel's update notice.
+ *
+ * The check lives on the host because the browser cannot make it: `registry.npmjs.org`
+ * sends no CORS header, and only the host knows which version of this package is
+ * actually installed (it reads its own `package.json`). The client asks once through
+ * this plugin's existing channel and renders whatever comes back.
+ *
+ * Everything here FAILS SOFT: a timeout, a refused connection, a registry answer that
+ * is not JSON, a package with no `version` — all of them end as `undefined`, never as a
+ * throw. A reader on a plane must not see a network error in their review panel, and the
+ * panel must never wait on this to draw.
+ *
+ * The dialog shows NOTHING but the versions and a button, so this module asks for nothing
+ * but the version: there is no changelog to slice and no URL to hand over.
+ *
+ * @module dsh-diff-approval/version
+ */
+import type { DiffApprovalUpdateValue } from './types.ts';
+/** The published name this check asks the registry about. */
+export declare const UPDATE_PACKAGE = "dsh-diff-approval";
+/** The registry's "latest" document for this package: `{ version, … }`. */
+export declare const UPDATE_REGISTRY = "https://registry.npmjs.org/dsh-diff-approval/latest";
+/**
+ * How long the request may take. Short on purpose: this is a nicety in a status bar,
+ * and the client-side request is issued in the background — but the host's own worker
+ * should not be held by a hanging socket either.
+ */
+export declare const UPDATE_TIMEOUT_MS = 3000;
+/**
+ * How long a registry answer may be reused before asking again: TEN MINUTES.
+ *
+ * The cache exists for the network cost of the REMOTE answer only (see {@link createUpdateCheck}), so this is
+ * the one staleness a reader can be shown. Ten minutes because a release cadence is measured in days: the
+ * figure is far shorter than any release gap, so a genuinely new release reaches an already-running host
+ * without a restart, and far longer than a page load, so reloading a page — or opening a second seat — does
+ * not hammer a public registry. It is deliberately NOT permanent: the process-lifetime memo this replaced
+ * kept serving a verdict computed before an upgrade, which is exactly how a reader saw "a new version" for a
+ * version they had already installed.
+ */
+export declare const UPDATE_CACHE_TTL_MS: number;
+/** A parsed `major.minor.patch`. */
+export type Version = readonly [number, number, number];
+/** One HTTP answer, as much of it as this module reads. */
+export interface FetchResponseFace {
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+}
+/** The one call this module makes on the network, injected so tests need no socket. */
+export type FetchFace = (url: string, init: {
+    signal: AbortSignal;
+    headers: Record<string, string>;
+}) => Promise<FetchResponseFace>;
+/** Where to ask, and how. Every field has a production default. */
+export interface UpdateProbe {
+    /** Registry `latest` document. */
+    registryUrl?: string;
+    /** Per-request budget, in ms. */
+    timeoutMs?: number;
+    /** The transport; defaults to the runtime's global `fetch`. */
+    fetchImpl?: FetchFace;
+}
+/** How {@link createUpdateCheck} reads and asks; every field has a production default. */
+export interface UpdateCheckOptions {
+    /** The manifest the INSTALLED version is read from; the package's own `package.json` by default. */
+    manifestUrl?: URL;
+    /** Registry `latest` document. */
+    registryUrl?: string;
+    /** Per-request budget, in ms. */
+    timeoutMs?: number;
+    /** The transport; defaults to the runtime's global `fetch`. */
+    fetchImpl?: FetchFace;
+    /** How long a fetched registry answer may be reused, in ms; {@link UPDATE_CACHE_TTL_MS} by default. */
+    ttlMs?: number;
+    /**
+     * The clock, in ms since the epoch; `Date.now` by default. Injected so a test can age the cached REMOTE
+     * answer without waiting ten real minutes — the TTL is the one thing here a test cannot otherwise reach.
+     */
+    now?: () => number;
+}
+/**
+ * Parse `major.minor.patch`, and NOTHING else.
+ *
+ * Deliberately strict, because the alternative is a bogus "newer": a pre-release
+ * (`0.31.0-rc.1`), a range (`^0.31.0`), a dist-tag (`latest`) or a stray suffix all
+ * answer `undefined`, and an unparsable side of a comparison is never allowed to look
+ * newer. A leading `v` is tolerated because tags carry one.
+ *
+ * @param text - the candidate, from a registry document or a `package.json`.
+ * @returns the three numbers, or `undefined` when the text is not exactly that shape.
+ */
+export declare function parseVersion(text: unknown): Version | undefined;
+/**
+ * Is `latest` strictly newer than `current`?
+ *
+ * Strictly: equal versions are NOT newer, and neither side parsing means NOT newer —
+ * the rule the code above exists to make safe. Comparison is component-wise on the
+ * three numbers, so `0.9.0` precedes `0.10.0` (string comparison would get that wrong).
+ *
+ * @param latest - the published version.
+ * @param current - the installed version.
+ * @returns whether a notice is warranted.
+ */
+export declare function isNewerVersion(latest: unknown, current: unknown): boolean;
+/**
+ * Compare two already-parsed versions.
+ *
+ * Component-wise, because a string comparison gets `0.9.0` vs `0.10.0` wrong — the reason both
+ * callers go through here rather than comparing something textual.
+ *
+ * @param left - one version.
+ * @param right - the other.
+ * @returns negative, zero or positive, as a comparator should.
+ */
+export declare function compareVersions(left: Version, right: Version): number;
+/**
+ * The version installed in this package, read from the `package.json` beside the built
+ * `lib/` — the only authority on what the reader is running, and the value the registry
+ * answer is compared against.
+ *
+ * Resolved relative to this module, so it holds for the bundled `lib/index.js`
+ * (`../package.json` is the package root) and for the source under test (`../package.json`
+ * is the repository root) alike.
+ *
+ * @param manifestUrl - the manifest to read; the package's own `package.json` unless a caller
+ *   says otherwise. It is a parameter because a test runner can serve modules over a non-file
+ *   URL, where the default cannot be resolved — the production path is the default, and the
+ *   end-to-end case is what proves the default itself.
+ * @returns the version, or `undefined` when the file is missing or has none.
+ */
+export declare function installedVersion(manifestUrl?: URL): Promise<string | undefined>;
+/**
+ * Ask the registry for the published version.
+ *
+ * @param probe - where to ask and how; every field defaults (see {@link UpdateProbe}).
+ * @returns the version, or `undefined` on any failure — including an answer that is not
+ *   a version, which must never become a notice.
+ */
+export declare function fetchLatestVersion(probe?: UpdateProbe): Promise<string | undefined>;
+/**
+ * Build the answer behind the `update-check` endpoint: one function a host calls per request.
+ *
+ * WHAT IS CACHED, AND FOR HOW LONG — the whole point of this factory:
+ *
+ * - The REMOTE answer (the registry's latest version) is cached, because that is the network cost. It is held
+ *   for {@link UPDATE_CACHE_TTL_MS} and then fetched again, so a release published while the host is running
+ *   still reaches the reader without a restart. A FAILED fetch is not cached at all: remembering a failure
+ *   would hide the notice for the whole TTL after one offline moment, and there is no network cost to save.
+ * - The INSTALLED version is read from the manifest on EVERY call. It is a file read, not a request, and it is
+ *   the side that changes when the reader upgrades — so a verdict computed before that upgrade must never be
+ *   replayed. Caching it was a real defect: a host that answered while an older version was installed kept
+ *   announcing "a newer release" to every page until it was restarted.
+ *
+ * `newer` is therefore decided afresh on every call, from today's manifest against the cached registry answer.
+ * NEVER THROWS: every failure — no manifest, an unreachable registry, a nonsense answer — ends as "nothing to
+ * say" (`newer: false`), so a network problem can never become an error in the reader's status bar.
+ *
+ * @param options - where to read and how; every field defaults (see {@link UpdateCheckOptions}).
+ * @returns the check itself; call it as often as you like.
+ */
+export declare function createUpdateCheck(options?: UpdateCheckOptions): () => Promise<DiffApprovalUpdateValue>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-diff-approval",
-  "version": "0.30.1",
+  "version": "0.31.0",
   "description": "DeepSeek Harness plugin: pending-edit review with whole-file diff and Keep/Revert",
   "packageManager": "pnpm@11.21.0",
   "author": "Wu Zhiwei",
@@ -60,10 +60,12 @@
     "test": "vitest run",
     "e2e": "playwright test",
     "compat": "node scripts/dsh-compat.mjs",
+    "compat:newer": "node scripts/dsh-compat.mjs --newer",
+    "verify:release": "node scripts/verify-release.mjs",
     "fonts:check": "python -m scripts.fonts.build --check",
     "fonts:plan": "python -m scripts.fonts.build --plan",
     "prepare": "tsc -b tsconfig.json && tsdown --env.DSH_BUILD_FACE client",
-    "release": "release-it"
+    "release": "release-it && node scripts/verify-release.mjs"
   },
   "license": "MIT",
   "dependencies": {