@deepseek-ai/dsh-experimental-client-ui-forge 0.0.0-stage → 0.2.2-alpha.3

package/lib/types/local-diff.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Local changes of a Session's checkout: where the `branch` scope forks, the
+ * patch of one scope with its untracked files, the new-side text of one file,
+ * and the size of the `branch` scope for the panel's card. Git runs through
+ * the Session's Git runner; untracked and working-tree files are read through
+ * `ctx.fs`, both within `maxDiffBytes`.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { Git, GitConfig, Inspection } from './git.ts';
+import type { ForgeLocalChanges, ForgeLocalDiff, ForgeLocalScope, ForgeSessionWorktree } from './types.ts';
+/** Git limits plus the size limits of local diffs. */
+export interface DiffConfig extends GitConfig {
+    /** Largest patch, untracked file, or new-side file in bytes. */
+    readonly maxDiffBytes: number;
+    /** Most untracked files listed. */
+    readonly maxUntrackedFiles: number;
+}
+/** The commit the `branch` scope compares with and the name the panel shows for it. */
+export interface ForkPoint {
+    /** Full commit object name. */
+    readonly commit: string;
+    /** Remote branch such as `origin/master`, the created worktree's base branch, or an abbreviated commit. */
+    readonly label: string;
+}
+/** Thrown when a patch, a file list, or a file exceeds `maxDiffBytes`. */
+export declare class DiffTooLarge extends Error {
+    name: string;
+}
+/** Thrown when filter configuration cannot be read completely; no comparison has run. */
+export declare class FilterConfigError extends Error {
+    name: string;
+}
+/** Thrown for the `branch` scope of a checkout without a fork point. */
+export declare class NoForkPoint extends Error {
+    name: string;
+}
+/**
+ * Find where the `branch` scope forks: the base commit of the worktree the
+ * Session created while the checkout is that worktree, else the merge base of
+ * HEAD with the default branch of the first remote that names one, in the
+ * order the panel recognizes code hosts.
+ * @param git - runner bound to the checkout.
+ * @param inspection - the checkout and its remotes.
+ * @param created - worktree the Session created, or null.
+ * @returns the fork point, or null when no remote names a default branch or HEAD shares no history with it.
+ */
+export declare function forkPoint(git: Git, inspection: Inspection, created: ForgeSessionWorktree | null): Promise<ForkPoint | null>;
+/**
+ * Read changes at `root` with command-local clean/process filter overrides and without
+ * submodule working-tree inspection. Git's built-in newline, ident, and encoding conversions still apply.
+ * @param ctx - context that provides `fs`, `subprocess`, `sandbox`, and `sandboxPolicy`.
+ * @param config - Git and size limits.
+ * @param session - Session whose sandbox policy and execution world apply.
+ * @param root - top-level directory of the checkout.
+ * @param fork - fork point of the `branch` scope, or null without one.
+ * @param scope - which changes to read.
+ * @param signal - cancellation of every command and read.
+ * @returns tracked files in Git's order, then untracked files unless the scope is `staged`.
+ * @throws NoForkPoint for the `branch` scope without `fork`; FilterConfigError when filter configuration
+ * cannot be read within `maxDiffBytes`; DiffTooLarge for oversized comparison output; an Error when Git fails.
+ */
+export declare function localDiff(ctx: Context, config: DiffConfig, session: Session, root: string, fork: ForkPoint | null, scope: ForgeLocalScope, signal: AbortSignal): Promise<ForgeLocalDiff>;
+/**
+ * Read the new side of one file in a scope, which supplies the unchanged
+ * lines between hunks: the index for `staged`, else the working tree.
+ * @param ctx - context that provides `fs`, `subprocess`, `sandbox`, and `sandboxPolicy`.
+ * @param config - Git and size limits.
+ * @param session - Session whose sandbox policy and execution world apply.
+ * @param root - top-level directory of the checkout.
+ * @param scope - the scope whose new side to read.
+ * @param path - path relative to `root`, as the diff names it.
+ * @param signal - cancellation.
+ * @returns the text.
+ * @throws DiffTooLarge over `maxDiffBytes`; an Error for a path outside the checkout, binary content, or a failed read.
+ */
+export declare function localText(ctx: Context, config: DiffConfig, session: Session, root: string, scope: ForgeLocalScope, path: string, signal: AbortSignal): Promise<string>;
+/**
+ * Measure the `branch` scope for the panel's card.
+ * @param ctx - context that provides `fs`, `subprocess`, `sandbox`, and `sandboxPolicy`.
+ * @param config - Git and size limits.
+ * @param session - Session whose sandbox policy and execution world apply.
+ * @param inspection - the checkout and its remotes.
+ * @param created - worktree the Session created, or null.
+ * @param signal - cancellation of every command and read.
+ * @returns the base and the changed files, or null without a fork point.
+ * @throws FilterConfigError when filter configuration cannot be read within `maxOutputBytes`;
+ * DiffTooLarge when the untracked file list exceeds `maxDiffBytes`; an Error when Git fails.
+ */
+export declare function localChanges(ctx: Context, config: DiffConfig, session: Session, inspection: Inspection, created: ForgeSessionWorktree | null, signal: AbortSignal): Promise<ForgeLocalChanges | null>;
+/**
+ * Count the commits the checkout has beyond a change request's head, which a
+ * change request diff does not show yet.
+ * @param git - runner bound to the Session's directory.
+ * @param branch - the change request's head branch.
+ * @param commit - the change request's head commit.
+ * @returns the count, or null on another branch, outside a checkout, or without the commit locally.
+ */
+export declare function aheadOf(git: Git, branch: string, commit: string): Promise<number | null>;
+//# sourceMappingURL=local-diff.d.ts.map

package/lib/types/panel.d.ts

@@ -0,0 +1,135 @@
+/** Live panel state of one followed Session, shared by all of its followers. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
+import type { ProjectionHandle } from '@deepseek-ai/dsh-session-projection';
+import type { GitConfig } from './git.ts';
+import type { DiffConfig } from './local-diff.ts';
+import type { ForgeMissingWorktree, ForgePanelState, ForgeWorktreeState } from './types.ts';
+import type { WorktreeCreations } from './worktree.ts';
+/** Git and diff limits plus the sign-in probe deadline. */
+export interface PanelConfig extends DiffConfig {
+    /** Deadline in milliseconds for one provider sign-in probe. */
+    readonly readinessTimeoutMs: number;
+}
+/**
+ * Panel state of one Session. Construction starts the first checkout
+ * inspection and watches the Session's change requests. Inspections run one at
+ * a time; a request that arrives during one runs once more after it, and a
+ * result for a directory the Session has since left is dropped. A sign-in
+ * probe runs when an inspection recognizes a new code host and on `refresh`;
+ * a probe result for a host the panel no longer shows is dropped. Each change
+ * request keeps the latest snapshot a poll returned while later polls fail.
+ * When an inspection finds an upstream branch on a remote a provider
+ * recognizes, the open change requests of that branch are bound as discovered,
+ * once per remote and branch until a refresh. The
+ * worktree facts follow the `forgeWorktree` projection, the live creation, and the last failed one;
+ * each inspection also decides whether the Session's sandbox can write the
+ * checkout and its shared Git directory, which a new worktree needs, whether
+ * the worktree the Session created and works in is gone, and how many lines
+ * the `branch` scope changes; a measurement that fails leaves that null.
+ */
+export declare class SessionPanel {
+    private readonly ctx;
+    private readonly config;
+    readonly session: Session;
+    private readonly worktreeStates;
+    private readonly creations;
+    private readonly onIdle;
+    private current;
+    private readonly followers;
+    private readonly lifetime;
+    private readonly tasks;
+    private readonly stopWatching;
+    private readonly snapshots;
+    private blocker;
+    private missing;
+    private inspection;
+    private rerun;
+    /** Remote URL and branch of the upstream that the last branch lookup covered, until a refresh. */
+    private discovered;
+    /**
+     * @param ctx - service context that provides the forge, Session, directory, and process services.
+     * @param config - Git limits and the sign-in probe deadline.
+     * @param session - Session the panel describes.
+     * @param worktreeStates - reads the `forgeWorktree` projection of the Session.
+     * @param creations - reads the running creation and restoration, the last failed creation, and what a message of the
+     * Session waits for.
+     * @param onIdle - called when the last follower leaves.
+     */
+    constructor(ctx: Context, config: PanelConfig, session: Session, worktreeStates: ProjectionHandle<ForgeWorktreeState>, creations: Pick<WorktreeCreations, 'of' | 'restorationOf' | 'failureOf' | 'waitingOf'>, onIdle: () => void);
+    /**
+     * Yield the current state, then each later state, until `signal` aborts or the panel stops.
+     * @param signal - ends this follower.
+     * @returns the states in publication order; intermediate states may be skipped.
+     */
+    follow(signal: AbortSignal): AsyncGenerator<ForgePanelState>;
+    /**
+     * React to one committed event of the Session: a directory change moves the
+     * panel and reinspects; a tool result reinspects, because the tool may have
+     * changed the checkout; a sandbox mode change reinspects, because it decides
+     * whether a worktree can be created; the first turn, the first step, and
+     * worktree records update the worktree facts.
+     * @param event - committed Session event.
+     */
+    observe(event: SessionEvent): void;
+    /** Republish the worktree facts when they changed, such as after a creation moved or a worktree service appeared or left. */
+    updateWorktree(): void;
+    /** Forget the missing worktree once it was checked out again; the next publication carries it, and a reinspection confirms it. */
+    restored(): void;
+    /** Reinspect the checkout, such as after its directory was created again. */
+    reinspect(): void;
+    /**
+     * Check again whether the worktree the Session works in is gone, publishing a change.
+     * @param signal - cancellation of the check.
+     * @returns the unavailable worktree, or null for a valid checkout or a Session working elsewhere.
+     * @throws when the filesystem or Git cannot answer.
+     */
+    checkMissing(signal: AbortSignal): Promise<ForgeMissingWorktree | null>;
+    /**
+     * Reinspect the checkout, probe sign-in again, and poll every bound change request at once.
+     * @returns settles once the inspection and the sign-in probe have ended; each poll publishes its result when it finishes.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Stop inspections, probes, and the change request watch, end every follower, and wait for pending work.
+     * @returns settles once pending inspections and probes have ended.
+     */
+    dispose(): Promise<void>;
+    private entries;
+    private worktree;
+    private publish;
+    /** Track `task` for disposal; the returned promise resolves once it settles, whatever the outcome. */
+    private run;
+    /**
+     * Inspect the checkout, one inspection at a time; calls during an
+     * inspection share one trailing rerun.
+     * @returns resolves once an inspection that started after the call has ended.
+     */
+    private inspect;
+    private inspectOnce;
+    /** The upstream branch with the first URL of its remote that a provider recognizes. */
+    private upstreamOf;
+    /** Bind the open change requests of the upstream branch, once per remote and branch until a refresh. */
+    private discover;
+    /** Decide whether the Session's sandbox lets the worktree service write the checkout and its shared Git directory. */
+    private blockerOf;
+    /** Measure the `branch` scope; a failed measurement only hides the local changes card. */
+    private localOf;
+    private recognize;
+    /** Probe sign-in on the repository's host; resolves once the probe has ended. */
+    private probe;
+}
+/**
+ * Decide whether a Session works inside the worktree it created while that
+ * worktree's directory is gone, and whether its branch still exists.
+ * @param ctx - context that provides `fs` and the process services.
+ * @param config - Git limits.
+ * @param session - Session to check.
+ * @param state - recorded worktree and restoration completion.
+ * @param directory - the Session's current directory.
+ * @param signal - cancellation of the check.
+ * @returns the unavailable worktree, or null for a valid checkout or a Session working elsewhere.
+ * @throws when the filesystem or Git cannot answer.
+ */
+export declare function missingWorktree(ctx: Context, config: GitConfig, session: Session, state: ForgeWorktreeState, directory: string, signal: AbortSignal): Promise<ForgeMissingWorktree | null>;
+//# sourceMappingURL=panel.d.ts.map

package/lib/types/parse.d.ts

@@ -0,0 +1,57 @@
+/** Parsers for the porcelain output of the read-only Git commands the panel runs. */
+/** One remote with the URLs `git remote -v` prints for it. */
+export interface GitRemote {
+    /** Remote name such as `origin`. */
+    readonly name: string;
+    /** Distinct URLs, fetch URL first. */
+    readonly urls: readonly string[];
+}
+/**
+ * Read the first line that `git rev-parse` prints for a directory query such as `--show-toplevel`.
+ * @param output - stdout of the command.
+ * @returns the directory.
+ * @throws when the output is empty.
+ */
+export declare function parseTopLevel(output: string): string;
+/**
+ * Read the first line of a one-name output such as `git symbolic-ref --short HEAD`.
+ * @param output - stdout of the command.
+ * @returns the name, or null when the command printed none.
+ */
+export declare function parseName(output: string): string | null;
+/**
+ * Order worktree base branches: the checked-out branch first, then the other
+ * listed branches in listed order.
+ * @param current - checked-out branch, or null when HEAD is detached.
+ * @param output - stdout of `git for-each-ref --format=%(refname:lstrip=2) refs/heads/`.
+ * @param limit - most names to return.
+ * @returns distinct branch names, at most `limit`.
+ */
+export declare function baseBranches(current: string | null, output: string, limit: number): string[];
+/**
+ * Group the lines of `git remote -v` by remote.
+ * @param output - stdout of the command.
+ * @returns remotes in first-listed order.
+ */
+export declare function parseRemotes(output: string): GitRemote[];
+/**
+ * Split an upstream branch such as `origin/feature/x` into its remote and the
+ * branch on that remote. The remote is the longest remote name followed by `/`
+ * at the start of the upstream branch.
+ * @param upstream - upstream branch such as `origin/main`, or null.
+ * @param remotes - remotes in listed order.
+ * @returns the remote and branch, or undefined without an upstream or a remote it starts with.
+ */
+export declare function upstreamBranch(upstream: string | null, remotes: readonly GitRemote[]): {
+    readonly remote: GitRemote;
+    readonly branch: string;
+} | undefined;
+/**
+ * Order remotes for code host recognition: the upstream's remote first, then
+ * `origin`, then the rest in listed order.
+ * @param upstream - upstream branch such as `origin/main`, or null.
+ * @param remotes - remotes in listed order.
+ * @returns the same remotes in recognition order.
+ */
+export declare function remoteOrder(upstream: string | null, remotes: readonly GitRemote[]): GitRemote[];
+//# sourceMappingURL=parse.d.ts.map

package/lib/types/patch-cache.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Change request patches kept in memory, so the changes view reads no diff
+ * from the code host again while a change request keeps its head commit and base branch.
+ */
+import type { ChangeRequestKey } from '@deepseek-ai/dsh-experimental-forge';
+/**
+ * One patch per change request, bounded by the total UTF-8 size of the kept
+ * patches; the least recently read patch leaves first.
+ */
+export declare class PatchCache {
+    private readonly maxBytes;
+    private readonly entries;
+    private bytes;
+    /** @param maxBytes - most UTF-8 bytes kept together; a larger patch is not kept. */
+    constructor(maxBytes: number);
+    /**
+     * Read the patch kept for a change request at a version, marking it the most recently read.
+     * @param key - the change request.
+     * @param version - head commit and base branch the reader needs.
+     * @returns the patch, or undefined when none is kept at that version.
+     */
+    get(key: ChangeRequestKey, version: string): string | undefined;
+    /**
+     * Keep a patch in place of the change request's earlier one, then drop the
+     * least recently read patches until the rest fit within `maxBytes`.
+     * @param key - the change request.
+     * @param version - head commit and base branch the patch was read at.
+     * @param patch - the patch.
+     */
+    set(key: ChangeRequestKey, version: string, patch: string): void;
+    private remove;
+}
+//# sourceMappingURL=patch-cache.d.ts.map

package/lib/types/states.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The last known state of every change request that a listed Session binds,
+ * for the Session list. One run starts with the first stream and stops with
+ * the last: it reads the stored states, lists the Sessions with their
+ * bindings, follows binding changes of loaded Sessions, and polls each bound
+ * change request, once however many Sessions bind it. The forge service
+ * owns polling cadence and terminal-state refresh. Every state change is stored, so a restart shows it before the
+ * first poll.
+ */
+import { z } from 'zod';
+import type { ChangeRequestListener, ChangeRequestRef } from '@deepseek-ai/dsh-experimental-forge/types';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { ForgeChangeRequestListState, ForgeChangeRequestStatesFrame } from './types.ts';
+/** Stored states keyed by {@link storedKey}; derived data, so a record that fails its schema is set aside. */
+export declare const changeRequestStatesDomain: {
+    name: string;
+    version: number;
+    layout: "per-record";
+    invalidRecords: "backup-and-skip";
+    tables: {
+        states: {
+            valueSchema: z.ZodType<ForgeChangeRequestListState, unknown, z.core.$ZodTypeInternals<ForgeChangeRequestListState, unknown>>;
+        };
+    };
+};
+/**
+ * The storage key of a change request's state: a path-safe digest of its URL.
+ * @param url - the change request's web URL.
+ * @returns the key.
+ */
+export declare function storedKey(url: string): string;
+/** The stored states the run reads and writes. */
+export interface StoredStates {
+    /** The state stored under a key. */
+    get(key: string): ForgeChangeRequestListState | undefined;
+    /** Every stored state. */
+    entries(): IterableIterator<[string, ForgeChangeRequestListState]>;
+    /** Store a state durably. */
+    put(key: string, value: ForgeChangeRequestListState): Promise<void>;
+    /** Remove a stored state durably. */
+    delete(key: string): Promise<boolean>;
+}
+/** One run's storage handle; closing releases its domain for the next run. */
+export interface OpenedStates {
+    readonly table: StoredStates;
+    /** Close the domain after the run's accepted writes settle. */
+    close(): Promise<void>;
+}
+/** One listed Session and the URLs of its visible bindings, undefined when they are not known without loading it. */
+export interface ListedSession {
+    readonly id: SessionId;
+    readonly urls: readonly string[] | undefined;
+}
+/** What a run reads, follows, and polls. */
+export interface ChangeRequestStateSources {
+    /** List every Session with its visible bindings. */
+    readonly sessions: (signal: AbortSignal) => Promise<readonly ListedSession[]>;
+    /** Follow the visible bindings of loaded Sessions; returns the disposer. */
+    readonly onBindings: (listener: (id: SessionId, urls: readonly string[]) => void) => () => void;
+    /** The change request a URL names, or undefined when no provider recognizes it. */
+    readonly refOf: (url: string) => ChangeRequestRef | undefined;
+    /** Poll a change request until the returned disposer runs. */
+    readonly watch: (ref: ChangeRequestRef, listener: ChangeRequestListener) => () => void;
+    /** Open the stored states; the run owns and closes the returned handle. */
+    readonly open: () => Promise<OpenedStates>;
+    /** Report a failed durable write; the state stays in memory. */
+    readonly report: (error: unknown) => void;
+}
+/** Streams the states of the change requests that listed Sessions bind. */
+export declare class ChangeRequestStates {
+    private readonly sources;
+    private readonly readers;
+    private stopping;
+    private disposed;
+    private run;
+    /** @param sources - what runs read, follow, and poll. */
+    constructor(sources: ChangeRequestStateSources);
+    /**
+     * Stream the known states the reader may see first, then each state that
+     * changes or becomes visible to it. The stream ends when `signal` aborts or
+     * the hub is disposed.
+     * @param allowed - whether the reader may read a Session.
+     * @param signal - ends the stream.
+     * @returns frames in publication order.
+     */
+    stream(allowed: (id: SessionId) => boolean, signal: AbortSignal): AsyncIterable<ForgeChangeRequestStatesFrame>;
+    /**
+     * End every stream, stop polling, and wait for initialization, accepted writes, and storage closure.
+     * @returns settles after all owned work stops; subsequent streams end without starting work.
+     */
+    dispose(): Promise<void>;
+    private ensureRun;
+    private stopRun;
+}
+//# sourceMappingURL=states.d.ts.map