dsh-over-ssh 0.1.0 → 0.1.1

package/lib/types/src/client/flows/session-directory.d.ts

@@ -1,415 +0,0 @@
-/**
- * The **session entry**: add a directory to the workspace the current session is in, without leaving the
- * conversation and **without creating a workspace**.
- *
- * What the user asked for: "不要在设置中加，不方便" (adding directories through the settings page is
- * inconvenient), and the directory-flow hole is no answer to it either - that hole's owner
- * (`ui-workspace`) adopts a picked path by calling `createWorkspace({ path })`, which **creates a new
- * workspace**. This entry is the other shape: it registers the directory as one of this plugin's roots
- * (the same `/api/over-ssh/roots` action the settings panel uses), and nothing else. The root is
- * live immediately, so the session that is already open - and every other one - can read and write under
- * it through the router. No workspace is created, no session is moved.
- *
- * Where it lives: `conversation.input.left`, a `list`-kind, session-scoped hole in the composer tool row
- * ("compact controls at the left of the composer tool row"). It is the only one of the four candidate
- * holes that is **inside the conversation**: the two `sidebar.workspaces.session.*` holes are row actions
- * of the sidebar list (they hand out a `sessionId`, not the composer), and `conversation.input.right` sits
- * next to the submit button, where a mis-click costs more than it saves. `ctx.slots.inject` is used rather
- * than a bare `register`, because the hole belongs to `ui-conversation` and may be declared after this
- * plugin (a bare register into an undeclared slot **throws** and would take the settings section down with
- * it), and the registration re-runs on `locale/change` for the same reason the other two surfaces do.
- *
- * Where "the current workspace" comes from: the framework hands every session-scoped occupant a
- * `sessionId` seat plus the `useSessions` / `useWorkspaces` selector hooks. The session's `cwd` comes from
- * the session list; when that seat is absent the workspace containing the session is looked up by
- * `sessionIds` instead. **Neither is guaranteed**: a composition without those packages hands out neither, and
- * then the entry says so in the panel (`sessionAddWorkspaceUnknown`) and **refuses to add anything** — every
- * root this card can list is scoped to a workspace, so with no workspace there is nothing to scope one to. It
- * used to write an unscoped root "which is in effect for every session anyway"; that sentence was wrong twice
- * over (audit 0056): unscoped roots are listed by no session, and the tool layer resolves by cwd/anchor rather
- * than by workspace, so "in effect for every session" was never something the list could promise. The entry
- * never guesses a path.
- *
- * The card is **portalled** through `./portal.ts`, exactly like the directory-flow dialog: a container on
- * `document.body` while the card is up. The composer tool row is a flex row this plugin does not own, and a
- * `position: fixed` card *inside* it would still be re-anchored by any ancestor with a `transform` or
- * `contain`; from `body` there is no such ancestor to worry about. The trigger stays where it is, so closing
- * hands focus back to it (it is whatever held focus before the card opened).
- *
- * **Unverified** (see `doc/02-platform/workspace-directory-flow.md`): the portal has not been looked at in a
- * real GUI.
- *
- * @module dsh-over-ssh/client/session-directory
- */
-import { type ReactNode } from 'react';
-import { type DirectoryBrowserIo } from './directory-browser.ts';
-import type { OverSshKey } from '../core/locale.ts';
-import { type CardPortalTarget } from '../core/portal.ts';
-import { type ApiResult, type FetchLike, type MessageKey, type RootRow } from '../roots/roots-panel.ts';
-import { type RootsPanelCopy } from '../roots/roots-panel-view.ts';
-/** The hole this entry fills: a `list`-kind, session-scoped seat at the left of the composer tool row. */
-export declare const SESSION_DIRECTORY_SLOT = "conversation.input.left";
-/**
- * The hole's declaration, mirrored.
- *
- * `@deepseek-ai/dsh-client-ui-conversation` declares this key (and its `session` scope) but is **not** a
- * dependency of this repository, while the registration below has to type-check here. The shape is quoted
- * from `packages/client/ui-conversation/src/client/contract/slots.ts`:
- * `'conversation.input.left': { kind: 'list'; scope: 'session' }`.
- */
-declare module '@deepseek-ai/dsh-client-ui-slots' {
-    interface SlotMap {
-        /** Compact controls at the left of the composer tool row. */
-        'conversation.input.left': {
-            kind: 'list';
-            scope: 'session';
-        };
-    }
-}
-/** Stable entry id, so a locale-driven re-registration replaces the same row instead of adding a second. */
-export declare const SESSION_DIRECTORY_ID = "over-ssh-add-directory";
-/** Placement among the shipped composer controls (the platform uses 100-steps). */
-export declare const SESSION_DIRECTORY_ORDER = 200;
-/**
- * Classes of the body-level container this entry's card is portalled into: the floating shell
- * (`CLASS.portal`) plus this surface's own name (`CLASS.portalComposer`). Both placements now centre the card
- * in the window; the class distinguishes the surface, not the geometry (see `styles.ts`).
- */
-export declare const SESSION_DIRECTORY_PORTAL_CLASS: string;
-/**
- * The card's click sink: the composer entry sits in the conversation and its dialog is modal, so pointer input has
- * to stop at the card (audit 2026-11-01b ui P2-1).
- */
-export declare const SESSION_DIRECTORY_BACKDROP_CLASS: "dsh-rw-backdrop";
-/** One root as this entry adds it. Local roots carry no connection; remote ones must. */
-export interface SessionDirectoryRootDraft {
-    readonly location: 'local' | 'remote';
-    readonly path: string;
-    readonly connectionId?: string;
-    /** The workspace this directory is added to; the card lists only roots that carry it. */
-    readonly workspaces?: readonly string[];
-    /** The conversation this directory is added to — the strict scope (ADR-0013). */
-    readonly sessions?: readonly string[];
-}
-/** The calls this entry makes: the browser's three plus the one write. */
-export interface SessionDirectoryIo extends DirectoryBrowserIo {
-    /**
-     * Register one root and answer the **anchor path** the host computed, when it reports one.
-     *
-     * The anchor is not needed here (this entry creates no workspace) but it is what the host answers, and
-     * dropping it would make this call diverge from the settings panel's for no gain.
-     */
-    addRoot(draft: SessionDirectoryRootDraft): Promise<ApiResult<{
-        readonly anchorPath?: string;
-    }>>;
-    /** The plugin's roots as the route reports them (narrowed locally; no credential field survives). */
-    loadRoots(workspacePath: string | undefined, sessionId?: string): Promise<ApiResult<readonly RootRow[]>>;
-    /**
-     * Drop one root from **this** workspace.
-     *
-     * `workspaces` is a union on the add side, so a root can be listed by several workspaces; removing it from
-     * one must not take it from the others. The host removes the root itself only when the last workspace drops
-     * it (the global delete, which the settings panel performs, omits `workspace`).
-     */
-    removeRoot(key: string, workspacePath?: string, sessionId?: string): Promise<ApiResult<unknown>>;
-    /**
-     * 宿主系统的原生目录选择框；`null` 表示用户取消，缺席表示这个组合没有这个能力。
-     *
-     * 可选：没有它时对话框照旧用内置浏览器，只是少一颗「浏览…」按钮。
-     */
-    pickLocal?: (() => Promise<string | null>) | undefined;
-}
-/**
- * Bind the entry's calls to this plugin's route.
- *
- * @param options - `fetch` (same-origin in the app) and a route override for tests.
- * @returns the calls the entry uses.
- */
-export declare function createSessionDirectoryIo(options: {
-    readonly fetchImpl: FetchLike;
-    readonly path?: string;
-    /** 原生目录选择框；见 {@link SessionDirectoryIo.pickLocal}。 */
-    readonly pickLocal?: (() => Promise<string | null>) | undefined;
-}): SessionDirectoryIo;
-/** Everything the entry renders from. */
-export interface SessionDirectoryState {
-    /** True while the floating card is up. */
-    readonly open: boolean;
-    /** True while the add-root request is in flight. */
-    readonly pending: boolean;
-    /** The workspace the session is in, as the framework seats reported it; absent when unavailable. */
-    readonly workspacePath?: string;
-    /** The conversation this card acts for, when the platform handed one over (ADR-0013). */
-    readonly sessionId?: string;
-    /** The directory that was just added (the path the user chose). */
-    readonly added?: string;
-    /** The last refusal or failure. */
-    readonly notice?: MessageKey;
-    /** The plugin's roots as last read; empty until the first answer. */
-    readonly roots: readonly RootRow[];
-    /** True while a roots read or a removal is in flight. */
-    readonly rootsPending: boolean;
-    /**
-     * True while the card is **reading** its roots list.
-     *
-     * Separate from {@link SessionDirectoryState.rootsPending}, which is the removal gate: the card used to render
-     * 「还没有添加目录。点「浏览…」…」 during the first read, i.e. it claimed the list was empty before it had an
-     * answer (audit 2026-11-01b ui P2-3).
-     */
-    readonly rootsReading: boolean;
-    /** True while the browser **step** is open (the card shows the picker instead of its buttons). */
-    readonly browsing: boolean;
-    /** The root key being removed, so its own row can hold still. */
-    readonly removing?: string;
-}
-/** What the reducer accepts. */
-export type SessionDirectoryAction = {
-    readonly type: 'toggled';
-} | {
-    readonly type: 'closed';
-} | {
-    readonly type: 'workspace-known';
-    readonly path?: string | undefined;
-} | {
-    readonly type: 'session-known';
-    readonly sessionId?: string | undefined;
-} | {
-    readonly type: 'submitted';
-} | {
-    readonly type: 'added';
-    readonly path: string;
-} | {
-    readonly type: 'refused';
-    readonly message: MessageKey;
-} | {
-    readonly type: 'failed';
-    readonly reason: string;
-} | {
-    readonly type: 'browse-toggled';
-}
-/** A roots read started; the list keeps what it had and the card may say "reading". */
- | {
-    readonly type: 'roots-reading';
-} | {
-    readonly type: 'roots-loaded';
-    readonly roots: readonly RootRow[];
-} | {
-    readonly type: 'roots-failed';
-    readonly reason: string;
-} | {
-    readonly type: 'root-removing';
-    readonly key: string;
-} | {
-    readonly type: 'root-removed';
-    readonly key: string;
-};
-/** @returns the state a freshly mounted entry holds. */
-export declare function initialSessionDirectoryState(): SessionDirectoryState;
-/**
- * The entry's state machine. Pure: an action that changes nothing returns the **same object**.
- *
- * `workspace-known` is dispatched by the shell on every render (the seat can resolve later); it is a no-op
- * when the path has not moved, so the panel is not re-rendered by an unchanged fact.
- *
- * @param state - the current state.
- * @param action - what happened.
- * @returns the next state.
- */
-export declare function sessionDirectoryReducer(state: SessionDirectoryState, action: SessionDirectoryAction): SessionDirectoryState;
-/** The complete render input. */
-export interface SessionDirectoryView {
-    /** True while the floating card is up. */
-    readonly visible: boolean;
-    /** True while the add-root request is in flight. */
-    readonly pending: boolean;
-    /** The workspace the session is in, or `undefined` when the seats could not answer. */
-    readonly workspacePath?: string;
-    /** The directory that was just added. */
-    readonly added?: string;
-    /** The refusal or failure text, resolved against the active dictionary. */
-    readonly notice: string;
-    /** The workspace line, resolved against the active dictionary. */
-    readonly workspaceLine: string;
-    /** The directories this session can use, ready to render. */
-    readonly roots: readonly SessionRootRow[];
-    /** True while the list is being read or a row is being removed. */
-    readonly rootsPending: boolean;
-    /** True while the list is being read (so the empty state must not be shown). */
-    readonly rootsReading: boolean;
-    /** True while the browser step is open. */
-    readonly browsing: boolean;
-}
-/** One directory row of the session card; text is already localized. */
-export interface SessionRootRow {
-    readonly key: string;
-    readonly title: string;
-    readonly subtitle: string;
-    /** 「本地」/「远端」 — the one fact a path alone cannot state. */
-    readonly badge: string;
-    /** Only a root in the plugin's own file can be removed; a profile-declared one cannot. */
-    readonly removable: boolean;
-}
-/**
- * Turn the state into render input, resolving the two dynamic lines through the active dictionary.
- *
- * @param state - the entry state.
- * @param copy - the dictionary of the active locale.
- * @returns the flags and the resolved text.
- */
-export declare function selectSessionDirectoryView(state: SessionDirectoryState, copy: RootsPanelCopy): SessionDirectoryView;
-/** What the controller needs. */
-export interface SessionDirectoryDeps {
-    readonly io: SessionDirectoryIo;
-    /** The dictionary of the active locale; a thunk, because the locale can change under a mounted entry. */
-    readonly copy: () => RootsPanelCopy;
-}
-/** The calls the container makes. */
-export interface SessionDirectoryController {
-    readonly getState: () => SessionDirectoryState;
-    readonly subscribe: (listener: () => void) => () => void;
-    /** Open or close the floating card. */
-    readonly toggle: () => void;
-    readonly close: () => void;
-    /** Push the workspace the framework seats reported (or `undefined` when they could not). */
-    readonly setWorkspacePath: (path: string | undefined) => void;
-    /** Push the conversation this card acts for (ADR-0013), or `undefined` when the seat could not answer. */
-    readonly setSessionId: (sessionId: string | undefined) => void;
-    /** Validate and register the picked directory; the world comes from whether a connection was used. */
-    readonly commit: (path: string, connectionId: string | undefined) => Promise<void>;
-    /** Open or close the browser step. */
-    readonly browse: () => void;
-    /** Re-read the plugin's roots (on open, and after every change). */
-    readonly refreshRoots: () => Promise<void>;
-    /** Drop one root from this plugin's list. */
-    readonly removeRoot: (key: string) => Promise<void>;
-    /** Re-arm after a mount (React's development replay runs the cleanup once before the real lifetime). */
-    readonly activate: () => void;
-    readonly dispose: () => void;
-}
-/**
- * Build the stateful half of the entry.
- *
- * The write goes through `validateRootDraft` - the same authority the settings panel and the directory-flow
- * dialog use - so a local path that is not absolute, or a remote path with `..` in it, is refused here
- * before anything reaches the host. A `remote` pick without a connection is refused the same way.
- *
- * @param deps - the injected calls and the active dictionary.
- * @returns the controller the container subscribes to.
- */
-export declare function createSessionDirectory(deps: SessionDirectoryDeps): SessionDirectoryController;
-/** What the entry's controls call. */
-export interface SessionDirectorySectionActions {
-    readonly onToggle: () => void;
-    readonly onClose: () => void;
-    /** Open or close the browser step. */
-    readonly onBrowse: () => void;
-    /** Drop one directory from this session's list. */
-    readonly onRemoveRoot: (key: string) => void;
-}
-/** Props of the pure template: copy, state, callbacks and the browser the shell mounted (or `null` in tests). */
-export interface SessionDirectorySectionProps {
-    readonly copy: RootsPanelCopy;
-    readonly state: SessionDirectoryState;
-    readonly actions: SessionDirectorySectionActions;
-    /** The directory browser element, built by the container; `null` renders the card without one. */
-    readonly browser?: ReactNode;
-    /**
-     * The body-level portal the card is mounted into. Absent renders the card **in place**, which is the
-     * DOM-less degradation (SSR, a direct template call): a runtime without a document has no composer row to
-     * escape either.
-     */
-    readonly portal?: CardPortalTarget | undefined;
-    /**
-     * `id` of the card's heading, referenced by `aria-labelledby`.
-     *
-     * **Required**, and supplied by the caller (`useId()` in the container). It used to default to a module-level
-     * constant — one id for every mount — which is the shape the id audit (2026-10-31 client.md §2.4) is about.
-     */
-    readonly titleId: string;
-}
-/**
- * Render the session entry. Pure: calling it twice with the same props yields the same tree.
- *
- * @param props - copy, state, callbacks, the browser element, the portal and the heading's id.
- * @returns the trigger and, while open, the card (inside the portal when one is given).
- */
-export declare function SessionDirectorySection({ copy, state, actions, browser, portal, titleId, }: SessionDirectorySectionProps): ReactNode;
-/** The minimal shape of the session list snapshot this module reads (a structural mirror). */
-interface SessionListLike {
-    readonly byId?: Readonly<Record<string, {
-        readonly cwd?: string;
-    } | undefined>>;
-}
-/** The minimal shape of the workspace snapshot this module reads (a structural mirror). */
-interface WorkspaceSnapshotLike {
-    readonly items?: readonly {
-        readonly path?: string;
-        readonly sessionIds?: readonly string[];
-    }[];
-}
-/**
- * One framework selector seat, as this module calls it.
- *
- * Structural on purpose: `useSessions` / `useWorkspaces` are merged into `GlobalStandardProps` by packages
- * that are **not** dependencies of this repository, so the seat is described by the one call this module
- * makes instead of imported.
- */
-export type SessionSeatHook<Snapshot> = (selector: (snapshot: Snapshot) => unknown) => unknown;
-/** Props of the React shell: the injected calls plus whatever seats the renderer handed this occurrence. */
-export interface SessionDirectoryContainerProps {
-    /** The active locale's dictionary; the shell resolves its own dynamic keys through it. */
-    readonly copy: RootsPanelCopy;
-    /** The injected calls. Created once by the entry, never by the component. */
-    readonly io: SessionDirectoryIo;
-    /** Session identity (the `sessionId` seat of a session-scoped slot); absent without `ui-session`. */
-    readonly sessionId?: string | undefined;
-    /** The `useSessions` seat; absent without `ui-session`. */
-    readonly useSessions?: SessionSeatHook<SessionListLike> | undefined;
-    /** The `useWorkspaces` seat; absent without `ui-workspace`. */
-    readonly useWorkspaces?: SessionSeatHook<WorkspaceSnapshotLike> | undefined;
-}
-/**
- * Read the current workspace path from whichever framework seat can answer.
- *
- * The session's own `cwd` is preferred (it is the directory the session actually runs in); the workspace
- * containing the session is the fallback, looked up by `sessionIds`. Both are `undefined` in a composition
- * that hands out neither seat, which the panel states rather than hides.
- *
- * Exported so the preference order and the fallback are asserted offline: the seats are plain callbacks, and
- * a test needs no renderer to drive them.
- *
- * @param props - the shell props carrying the seats.
- * @returns the workspace path, or `undefined`.
- */
-export declare function readWorkspacePath(props: SessionDirectoryContainerProps): string | undefined;
-/**
- * The identity of a roots read: which workspace the list is scoped to, or that the card is closed.
- *
- * A read is only valid for the workspace it was issued for, so this value is what decides **when a re-read is
- * owed**. It is a named pure function rather than a bare dependency array because this repository's tests do
- * not render hooks (`client-roots-view.test.ts` says why): an effect's dependency list cannot be executed by a
- * test, so the *decision* is extracted here where it can be. (A mutation that drops the dependency from the
- * effect used to leave every test green — found by the round-2 mutation experiment.)
- *
- * Why it matters: the seats that answer "which workspace is this session in" can answer **after** the card is
- * already open. Reading only on `open` made the first (unknown-workspace) answer final, so a late seat left the
- * list empty until the card was closed and reopened (audit 0056, review T3).
- *
- * @param state - the entry state.
- * @returns `closed` when the card is closed, otherwise a key that changes when the workspace does.
- */
-export declare function rootsQueryKey(state: SessionDirectoryState): string;
-/**
- * Subscribe to a per-mount entry and render {@link SessionDirectorySection}.
- *
- * The card is **portalled** (`./portal.ts`): one container per mount, attached to `document.body` while the
- * card is up and removed when it closes. The trigger alone stays in the composer row. Opening also moves focus
- * into the card and remembers the trigger, so Esc closes and closing hands focus back.
- *
- * @param props - the injected dictionary and calls plus the framework seats.
- * @returns the trigger and, while open, the card with its browser.
- */
-export declare function SessionDirectoryContainer(props: SessionDirectoryContainerProps): ReactNode;
-/** The dictionary keys this module renders, so a test can assert the two locales carry them. */
-export type SessionDirectoryKey = Extract<OverSshKey, 'sessionAddOpen' | 'sessionAddTitle' | 'sessionAddHint' | 'sessionAddWorkspace' | 'sessionAddWorkspaceUnknown' | 'sessionAddDone' | 'sessionAddFailed' | 'sessionAddPick' | 'sessionBrowse' | 'sessionBrowseBack' | 'sessionRootsTitle' | 'sessionRootsEmpty' | 'sessionRootsHint' | 'sessionRootsFailed' | 'rootsRemove' | 'close' | 'flowPending'>;
-export {};