@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.4

package/lib/types/core/worktree/paths.js

@@ -0,0 +1,118 @@
+/**
+ * Path and naming helpers shared between the host manager and the browser
+ * side (browser side uses these for display only — it never writes to the
+ * filesystem). All paths are POSIX; the host normalizes the separators at
+ * the git boundary.
+ * @module @dsh-cove/dsh-client-ui-worktree/core
+ */
+import { isValidBranchName } from "./invariant.js";
+/** The directory inside each repo that owns linked worktrees. */
+export const WORKSPACE_DIR = '.dsh/workspaces';
+/** The manifest filename inside `WORKSPACE_DIR`. */
+export const MANIFEST_FILENAME = 'manifest.json';
+/** The "main" pseudo-worktree name — never a real on-disk worktree. */
+export const MAIN_WORKTREE = '<main>';
+/** Compose `<repo>/.dsh/workspaces` for a given repo path. */
+export function worktreeRoot(repoPath) {
+    if (typeof repoPath !== 'string' || repoPath.length === 0) {
+        throw new TypeError('repoPath must be a non-empty string');
+    }
+    const trimmed = stripTrailingSeparator(repoPath);
+    return `${trimmed}/${WORKSPACE_DIR}`;
+}
+/** Compose `<repo>/.dsh/workspaces/<branch>` for a given repo + branch. */
+export function worktreeDir(repoPath, branch) {
+    if (!isValidBranchName(branch)) {
+        throw new Error(`invalid branch name: ${JSON.stringify(branch)}`);
+    }
+    return `${worktreeRoot(repoPath)}/${branch}`;
+}
+/**
+ * Whether a path is one of this plugin's lane directories
+ * (`<repo>/.dsh/workspaces/<branch>`).
+ *
+ * Used to keep the lane lifecycle's bookkeeping — retiring a lane's workspace
+ * registration once its conversations are archived — away from workspaces the
+ * user registered themselves. Workspace ids are opaque, so the path is the only
+ * thing that identifies a lane in a workspace list.
+ */
+export function isLaneDirectory(path) {
+    if (typeof path !== 'string' || path === '')
+        return false;
+    return path.replace(/\\/g, '/').includes(`/${WORKSPACE_DIR}/`);
+}
+/** Strip a single trailing `/` (defensive only — POSIX paths usually lack it). */
+function stripTrailingSeparator(path) {
+    return path.endsWith('/') && path.length > 1 ? path.slice(0, -1) : path;
+}
+/** Short sha (first 7 chars) — same display rule as `git rev-parse --short`. */
+export function shortSha(sha) {
+    if (typeof sha !== 'string' || sha.length === 0)
+        return null;
+    return sha.length > 7 ? sha.slice(0, 7) : sha;
+}
+/**
+ * Truncate a path for the sidebar row (replace the leading `<repo>/.dsh/`
+ * with a visual marker so the full path is still in the title attr).
+ */
+export function displayPath(absolute) {
+    const marker = `/${WORKSPACE_DIR}/`;
+    const idx = absolute.indexOf(marker);
+    if (idx < 0)
+        return absolute;
+    return `.dsh/workspaces/${absolute.slice(idx + marker.length)}`;
+}
+/**
+ * Whether `target` is `root` itself or lies beneath it (POSIX, segment-aware).
+ *
+ * Applied to keep mutations inside the workspaces the host has registered: a
+ * plain string prefix would let `/repo-other` read as "inside `/repo`".
+ */
+export function isInsidePath(root, target) {
+    const posix = (value) => value.replace(/\\/g, '/');
+    const base = posix(root);
+    const candidate = posix(target);
+    const trimmedBase = base.length > 1 && base.endsWith('/') ? base.slice(0, -1) : base;
+    const trimmed = candidate.length > 1 && candidate.endsWith('/') ? candidate.slice(0, -1) : candidate;
+    if (trimmedBase === '/' || trimmedBase === '')
+        return trimmed.startsWith('/');
+    return trimmed === trimmedBase || trimmed.startsWith(`${trimmedBase}/`);
+}
+/** Compare two paths for equality after normalization (POSIX separators). */
+export function samePath(a, b) {
+    if (a === b)
+        return true;
+    const na = a.replace(/\\/g, '/');
+    const nb = b.replace(/\\/g, '/');
+    if (na === nb)
+        return true;
+    const sa = na.endsWith('/') && na.length > 1 ? na.slice(0, -1) : na;
+    const sb = nb.endsWith('/') && nb.length > 1 ? nb.slice(0, -1) : nb;
+    return sa === sb;
+}
+/**
+ * Parse a GitHub remote URL into `{ owner, repo }`. Accepts the https
+ * (`https://github.com/owner/repo[.git]`), ssh scp-like
+ * (`git@github.com:owner/repo.git`), and ssh URL (`ssh://git@github.com/owner/repo`)
+ * spellings. Returns null for non-GitHub remotes so the caller can fall
+ * back to the compare-URL path.
+ */
+export function githubOwnerRepo(remoteUrl) {
+    const match = remoteUrl.trim().match(/(?:github\.com[/:])([^/]+)\/([^/.]+?)(?:\.git)?$/);
+    if (match === null)
+        return null;
+    const [, owner, repo] = match;
+    if (owner === undefined || repo === undefined || owner === '' || repo === '')
+        return null;
+    return { owner, repo };
+}
+/**
+ * GitHub compare URL for one PR candidate: base...head with the editor
+ * expanded. Returns null when the remote is not a GitHub URL.
+ */
+export function githubCompareUrl(remoteUrl, base, branch) {
+    const parsed = githubOwnerRepo(remoteUrl);
+    if (parsed === null)
+        return null;
+    return `https://github.com/${parsed.owner}/${parsed.repo}/compare/${encodeURIComponent(base)}...${encodeURIComponent(branch)}?expand=1`;
+}

package/lib/types/core/worktree/pr-create.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Pull-request creation wire contract and pure argv/input helpers.
+ *
+ * Host execution lives in the worktree service. This module stays runtime-neutral
+ * so both host and client programs compile the same request/result contract.
+ */
+export interface PrCreateInput {
+    /** Any path inside the project. `repoPath` remains accepted by the host as a legacy alias. */
+    cwd?: string;
+    /** Local branch to publish. `name` remains accepted by the host as a legacy alias. */
+    branch?: string;
+    /** Pull-request title. Defaults to the branch for legacy callers. */
+    title?: string;
+    /** Pull-request body. Defaults to an empty body for legacy callers. */
+    body?: string;
+    /** Target branch. `baseRef` remains accepted by the host as a legacy alias. */
+    base?: string;
+    /** GitHub head selector, usually a branch or `owner:branch`. Defaults to `branch`. */
+    head?: string;
+    /** Create the pull request as a draft. */
+    draft?: boolean;
+    /** Legacy project-root field. */
+    repoPath?: string;
+    /** Legacy worktree-name field. */
+    name?: string;
+    /** Legacy base-branch field. */
+    baseRef?: string;
+}
+export interface PrCreateResult {
+    url: string;
+    number: number;
+    /** Legacy result field retained for the previous browser client. */
+    prUrl: string;
+    /** Legacy discriminator: gh creates the pull request through GitHub's API. */
+    method: 'api';
+}
+export type PrCreateErrorCode = 'invalid-input' | 'gh-not-installed' | 'gh-not-authenticated' | 'pr-already-exists' | 'timeout' | 'gh-failed' | 'invalid-gh-response';
+export interface NormalizedPrCreateInput {
+    cwd: string;
+    branch: string;
+    title: string;
+    body: string;
+    base?: string;
+    head: string;
+    draft: boolean;
+}
+export type PrCreateInputValidation = {
+    ok: true;
+    value: NormalizedPrCreateInput;
+} | {
+    ok: false;
+    message: string;
+};
+/** Git's branch-name restrictions, without invoking a subprocess. */
+export declare function isSafeBranchName(value: string): boolean;
+/** GitHub accepts either a branch or `owner:branch` for --head. */
+export declare function isSafeHead(value: string): boolean;
+/** Normalize current and legacy request fields, rejecting malformed or unsafe values. */
+export declare function normalizePrCreateInput(input: PrCreateInput): PrCreateInputValidation;
+/** Build an argv-only GitHub CLI invocation. Values never pass through a shell. */
+export declare function ghPrCreateArgv(input: Omit<NormalizedPrCreateInput, 'cwd'>): string[];
+/** Extract the PR URL and numeric id from `gh pr create` output. */
+export declare function parseGhPrCreateOutput(stdout: string): {
+    url: string;
+    number: number;
+} | undefined;
+//# sourceMappingURL=pr-create.d.ts.map

package/lib/types/core/worktree/pr-create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-create.d.ts","sourceRoot":"","sources":["../../../../src/core/worktree/pr-create.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,aAAa;IAC5B,8FAA8F;IAC9F,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0CAA0C;IAC1C,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,MAAM,EAAE,KAAK,CAAA;CACd;AAED,MAAM,MAAM,iBAAiB,GACzB,eAAe,GACf,kBAAkB,GAClB,sBAAsB,GACtB,mBAAmB,GACnB,SAAS,GACT,WAAW,GACX,qBAAqB,CAAA;AAEzB,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,MAAM,uBAAuB,GAC/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,uBAAuB,CAAA;CAAE,GAC5C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAKlC,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOvD;AAED,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOjD;AAED,yFAAyF;AACzF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,aAAa,GAAG,uBAAuB,CA+CpF;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,uBAAuB,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,CAKpF;AAED,oEAAoE;AACpE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAYjG"}

package/lib/types/core/worktree/pr-create.js

@@ -0,0 +1,118 @@
+/**
+ * Pull-request creation wire contract and pure argv/input helpers.
+ *
+ * Host execution lives in the worktree service. This module stays runtime-neutral
+ * so both host and client programs compile the same request/result contract.
+ */
+const MAX_TITLE_LENGTH = 256;
+const MAX_BODY_LENGTH = 64 * 1024;
+/** Git's branch-name restrictions, without invoking a subprocess. */
+export function isSafeBranchName(value) {
+    if (value === '' || value.length > 255 || value === '@' || value.startsWith('-'))
+        return false;
+    if (/\s|[~^:?*\\\[\x00-\x1f\x7f]/u.test(value))
+        return false;
+    if (value.includes('..') || value.includes('@{') || value.includes('//'))
+        return false;
+    if (value.startsWith('/') || value.endsWith('/') || value.startsWith('.') || value.endsWith('.'))
+        return false;
+    if (value.endsWith('.lock'))
+        return false;
+    return value.split('/').every(part => part !== '' && !part.startsWith('.') && !part.endsWith('.'));
+}
+/** GitHub accepts either a branch or `owner:branch` for --head. */
+export function isSafeHead(value) {
+    const colon = value.indexOf(':');
+    if (colon === -1)
+        return isSafeBranchName(value);
+    if (colon === 0 || colon !== value.lastIndexOf(':'))
+        return false;
+    const owner = value.slice(0, colon);
+    const branch = value.slice(colon + 1);
+    return /^[A-Za-z0-9_.-]+$/u.test(owner) && isSafeBranchName(branch);
+}
+/** Normalize current and legacy request fields, rejecting malformed or unsafe values. */
+export function normalizePrCreateInput(input) {
+    const cwdValue = input.cwd ?? input.repoPath;
+    const branchValue = input.branch ?? input.name;
+    const baseValue = input.base ?? input.baseRef;
+    if (input.cwd !== undefined && typeof input.cwd !== 'string')
+        return { ok: false, message: 'cwd must be a string' };
+    if (input.repoPath !== undefined && typeof input.repoPath !== 'string')
+        return { ok: false, message: 'repoPath must be a string' };
+    if (typeof cwdValue !== 'string' || cwdValue.trim() === '')
+        return { ok: false, message: 'cwd is required' };
+    if (typeof branchValue !== 'string' || !isSafeBranchName(branchValue.trim())) {
+        return { ok: false, message: 'branch is invalid' };
+    }
+    if (input.branch !== undefined && typeof input.branch !== 'string')
+        return { ok: false, message: 'branch must be a string' };
+    if (input.name !== undefined && typeof input.name !== 'string')
+        return { ok: false, message: 'name must be a string' };
+    if (input.title !== undefined && typeof input.title !== 'string')
+        return { ok: false, message: 'title must be a string' };
+    if (input.body !== undefined && typeof input.body !== 'string')
+        return { ok: false, message: 'body must be a string' };
+    if (input.base !== undefined && typeof input.base !== 'string')
+        return { ok: false, message: 'base must be a string' };
+    if (input.baseRef !== undefined && typeof input.baseRef !== 'string')
+        return { ok: false, message: 'baseRef must be a string' };
+    if (input.head !== undefined && typeof input.head !== 'string')
+        return { ok: false, message: 'head must be a string' };
+    if (input.draft !== undefined && typeof input.draft !== 'boolean')
+        return { ok: false, message: 'draft must be a boolean' };
+    const branch = branchValue.trim();
+    const title = input.title?.trim() || branch;
+    const body = input.body ?? '';
+    const base = baseValue?.trim();
+    const head = input.head?.trim() || branch;
+    if (title.length > MAX_TITLE_LENGTH || /[\r\n\x00]/u.test(title)) {
+        return { ok: false, message: `title must be one line and at most ${MAX_TITLE_LENGTH} characters` };
+    }
+    if (body.length > MAX_BODY_LENGTH || body.includes('\0')) {
+        return { ok: false, message: `body must not contain NUL and must be at most ${MAX_BODY_LENGTH} characters` };
+    }
+    if (base !== undefined && (base === '' || !isSafeBranchName(base)))
+        return { ok: false, message: 'base is invalid' };
+    if (!isSafeHead(head))
+        return { ok: false, message: 'head is invalid' };
+    return {
+        ok: true,
+        value: {
+            cwd: cwdValue.trim(),
+            branch,
+            title,
+            body,
+            ...(base === undefined ? {} : { base }),
+            head,
+            draft: input.draft === true,
+        },
+    };
+}
+/** Build an argv-only GitHub CLI invocation. Values never pass through a shell. */
+export function ghPrCreateArgv(input) {
+    const argv = ['pr', 'create', '--title', input.title, '--body', input.body, '--head', input.head];
+    if (input.base !== undefined)
+        argv.push('--base', input.base);
+    if (input.draft)
+        argv.push('--draft');
+    return argv;
+}
+/** Extract the PR URL and numeric id from `gh pr create` output. */
+export function parseGhPrCreateOutput(stdout) {
+    const match = stdout.match(/https?:\/\/[^\s]+\/pull\/(\d+)(?:\b|\/)?/u);
+    if (match === null)
+        return undefined;
+    const number = Number(match[1]);
+    if (!Number.isSafeInteger(number) || number <= 0)
+        return undefined;
+    try {
+        const url = new URL(match[0].replace(/[),.;]+$/u, ''));
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return undefined;
+        return { url: url.href.replace(/\/$/u, ''), number };
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/types/core/worktree/protocol.d.ts

@@ -0,0 +1,7 @@
+/**
+ * worktree 跨半区 wire 契约（host 与 client 双 program 编译）。
+ * 纯常量：/worktree 与 /workspace-model 前缀。
+ */
+export declare const WORKTREE_API_PREFIX = "/worktree";
+export declare const WORKSPACE_MODEL_PREFIX = "/workspace-model";
+//# sourceMappingURL=protocol.d.ts.map

package/lib/types/core/worktree/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../../src/core/worktree/protocol.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,mBAAmB,cAAc,CAAA;AAC9C,eAAO,MAAM,sBAAsB,qBAAqB,CAAA"}

package/lib/types/core/worktree/protocol.js

@@ -0,0 +1,6 @@
+/**
+ * worktree 跨半区 wire 契约（host 与 client 双 program 编译）。
+ * 纯常量：/worktree 与 /workspace-model 前缀。
+ */
+export const WORKTREE_API_PREFIX = '/worktree';
+export const WORKSPACE_MODEL_PREFIX = '/workspace-model';

package/lib/types/core/worktree/types.d.ts

@@ -0,0 +1,292 @@
+/**
+ * Domain types shared between the host half and the browser half. Anything
+ * that crosses the HTTP boundary lands here first so the JSON contract is
+ * one source of truth.
+ *
+ * The plugin deliberately mirrors the official `ctx.workspaces` /
+ * `ctx.sessions` client-service shapes where it can — the browser side
+ * mirrors the official `@deepseek-ai/dsh-workspace` / `@deepseek-ai/dsh-session` faces
+ * (type-only) and aligns its derivation to the same `sessionIds` account
+ * the official WorkspaceBrowser uses, so a single source of truth
+ * governs session grouping and workspace display across both surfaces.
+ * @module @dsh-cove/dsh-client-ui-worktree/core
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
+import type { WorktreeErrorCode } from './invariant.ts';
+export type { SessionId } from '@deepseek-ai/dsh-session/types';
+export type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
+/** One linked worktree entry as the browser renders it under a project row. */
+export interface WorktreeView {
+    /** Stable name (= worktree dir name under `.dsh/workspaces/`). */
+    name: string;
+    /** Absolute filesystem path. */
+    path: string;
+    /** The checked-out branch (or null when detached). */
+    branch: string | null;
+    /** HEAD sha (short) when known. */
+    head: string | null;
+    /** True when the worktree directory exists on disk. */
+    exists: boolean;
+    /** DSH workspace id when registered; null when the path is not a workspace. */
+    workspaceId: WorkspaceId | null;
+    /** Session bound to this lane (session-bound lanes only); null otherwise.
+     *  This binding — not `workspaceId` — is what makes a lane a lane. */
+    sessionId: SessionId | null;
+}
+/** One git project (repo) in the host worktree index. */
+export interface WorktreeProject {
+    /** Canonical absolute path of the repository. */
+    repoPath: string;
+    /** Absolute path of the main worktree (== repoPath on a normal repo). */
+    mainPath: string;
+    /** DSH workspace id for the main worktree path, when registered. */
+    mainWorkspaceId: WorkspaceId | null;
+    /** The repository's basename (e.g. `dsh-cove`). */
+    name: string;
+    /** The main worktree's HEAD branch (or null when detached / unknown). */
+    mainBranch: string | null;
+    /** Number of uncommitted files in the main working tree (>=0); null when not probed. */
+    dirty: number | null;
+    /** Linked worktrees under `<repo>/.dsh/workspaces/`. The main worktree is NOT in this list. */
+    worktrees: WorktreeView[];
+}
+/**
+ * Host response: the per-repo worktree index for the management panel.
+ * Sessions are never carried through the HTTP layer.
+ */
+export interface WorktreeIndex {
+    /** Every registered workspace path that resolves to a git repository. */
+    projects: WorktreeProject[];
+}
+/** Result shape for worktree mutations returned over HTTP. */
+export interface MutationResult<T = void> {
+    ok: true;
+    value: T;
+}
+/** Domain error shape returned over HTTP (status >= 400). */
+export interface WorktreeErrorView {
+    ok: false;
+    code: WorktreeErrorCode;
+    message: string;
+}
+/** Discriminated union for HTTP responses. */
+export type WorktreeResponse<T = void> = MutationResult<T> | WorktreeErrorView;
+/** Parameters for `POST /worktree/create`. */
+export interface CreateWorktreeInput {
+    /** Repository root (must be a registered workspace). */
+    repoPath: string;
+    /** Branch name (also used as the worktree dir name under `.dsh/workspaces/`).
+     *  The branch is cut at `base` and checked out in the worktree. */
+    branch: string;
+    /** Optional base commit-ish the new branch starts at; defaults to HEAD. */
+    base?: string;
+}
+/** Parameters for `POST /worktree/lane/create` — the worktree behind a branch. */
+export interface CreateLaneInput {
+    /** Repository root (any directory inside it resolves). */
+    repoPath: string;
+    /** Branch the lane checks out. An existing local branch is ATTACHED (its own
+     *  worktree is created); otherwise the branch is cut at `base`. */
+    branch: string;
+    /** Base commit-ish for a branch that has to be created; defaults to HEAD. */
+    base?: string;
+}
+/**
+ * A prepared lane: the branch's worktree, ready to host the conversation that
+ * asked for it.
+ *
+ * The lane directory is registered as a DSH workspace, and that is a platform
+ * requirement rather than a design taste: the registry accounts a session to a
+ * workspace only while the session's cwd equals that workspace's path (its
+ * `sessionIds` filters by the session's path, and `attachSession` refuses any
+ * other cwd), `session.create` takes a workspace id XOR a bare cwd, and a blank
+ * conversation that no workspace accounts for renders its composer inert
+ * ("choose a workspace to start"). A lane session created with a bare cwd is
+ * therefore a conversation the user cannot type into.
+ *
+ * Ownership still sits with the conversation: the lane is recorded against the
+ * session that asked for it (`/worktree/lane/bind`), that binding is what the
+ * teardown guards read, and the header chip — not the workspace row — is where
+ * its lifecycle lives. Teardown unregisters the workspace with the directory, so
+ * the sidebar only carries lanes that are still alive.
+ */
+export interface LaneHandle {
+    /** Lane name == branch name. */
+    name: string;
+    /** Checked-out branch. */
+    branch: string;
+    /** Absolute worktree path — the directory a lane session runs in. */
+    path: string;
+    /** Short HEAD of the lane. */
+    head: string | null;
+    /** False when an existing worktree was reused instead of created. */
+    created: boolean;
+    /** The lane's registered workspace, which is how a blank draft is moved onto
+     *  it; null when the registry refused (the lane still exists on disk, but no
+     *  conversation can be started in it). */
+    workspaceId: WorkspaceId | null;
+}
+/** Result of `POST /worktree/lane/create`. */
+export type CreateLaneResult = LaneHandle;
+/** Parameters for `POST /worktree/lane/bind` — attach a created session to its lane. */
+export interface BindLaneInput {
+    /** Repository root owning the lane. */
+    repoPath: string;
+    /** Branch the lane cuts (its manifest name). */
+    branch: string;
+    /** Session the platform created on the lane workspace. */
+    sessionId: string;
+}
+/** Result of `POST /worktree/lane/bind`. */
+export interface BindLaneResult {
+    /** The lane after binding (null when it cannot be resolved). */
+    lane: LaneView | null;
+    /** Whether the lane's required permission preset is now applied. */
+    permissionPresetApplied: boolean;
+}
+/** Parameters for `POST /worktree/lane` — resolve the lane a path/session belongs to. */
+export interface LaneLookupInput {
+    /** Absolute path inside the lane (usually the session cwd). */
+    path?: string;
+    /** Session id; the host resolves its cwd when `path` is absent. */
+    sessionId?: string;
+}
+/**
+ * One lane as the conversation header chip and the panel render it.
+ * `name`/`branch` identify the lane; the status fields mirror
+ * `WorktreeStatusView` so a single host probe serves both surfaces.
+ */
+export interface LaneView {
+    /** Lane name == branch name. */
+    name: string;
+    /** Checked-out branch (null when detached). */
+    branch: string | null;
+    /** Absolute lane path. */
+    path: string;
+    /** Repository root owning the lane. */
+    repoPath: string;
+    /** True when the lane directory exists on disk. */
+    exists: boolean;
+    /** DSH workspace id when registered. */
+    workspaceId: WorkspaceId | null;
+    /** Session recorded as bound to this lane, when one was created through us. */
+    sessionId: SessionId | null;
+    /** Whether the required lane preset applied; null for older/non-session lanes. */
+    permissionPresetApplied: boolean | null;
+    /** Uncommitted file count (null when the directory is gone). */
+    dirty: number | null;
+    /** Remote-tracking ref for the branch exists after fetch. */
+    pushed: boolean;
+    /** Branch gone from the remote after having been pushed (merged signal). */
+    remoteBranchGone: boolean;
+    /** Branch is merged into its base. */
+    merged: boolean;
+    /** Recorded PR url, when one was created through this plugin. */
+    prUrl: string | null;
+    /** Recorded GitHub PR number. */
+    prNumber: number | null;
+}
+/** Parameters for `POST /worktree/remove`. */
+export interface RemoveWorktreeInput {
+    /** Repository root. */
+    repoPath: string;
+    /** Worktree directory name under `.dsh/workspaces/`. */
+    name: string;
+    /** Pass --force to git so uncommitted changes are dropped. */
+    force?: boolean;
+    /**
+     * The conversation asking for the teardown, when it is the lane's own
+     * conversation. A live session blocks removal so a running conversation never
+     * loses its directory; that interlock must not make a lane the conversation
+     * itself sits on unremovable, so the lane's own recorded session may excuse
+     * itself (and is archived by the teardown like any other). Any other id —
+     * including one the lane does not record — excuses nothing.
+     */
+    sessionId?: string;
+}
+/** Parameters for `POST /worktree/init`. */
+export interface InitWorktreeInput {
+    /** Repository root. */
+    repoPath: string;
+    /** Create the first branch on HEAD (default: `main`). */
+    initialBranch?: string;
+}
+/** Parameters for `POST /worktree/pr-create`. */
+export interface PrCreateInput {
+    /** Repository root (must be a registered workspace). */
+    repoPath: string;
+    /** Worktree name == branch name. */
+    name: string;
+    /** PR target base branch; defaults to the repo's resolved base (manifest
+     *  `baseBranch`, else the remote default branch, else `main`). */
+    baseRef?: string;
+    /** Optional PR title; defaults to the branch name. */
+    title?: string;
+}
+/** Result of `POST /worktree/pr-create`. */
+export interface PrCreateResult {
+    /** The PR page URL (compare URL when created via 'url', html_url when 'api'). */
+    prUrl: string;
+    /** How the PR was created: compare URL opened in the browser, or the
+     *  GitHub REST API (requires the `pr.tokenEnv` credential). */
+    method: 'url' | 'api';
+}
+/** Parameters for `POST /worktree/status`. */
+export interface StatusInput {
+    /** Repository root. */
+    repoPath: string;
+    /** Status for one named worktree only; omit for every linked worktree. */
+    name?: string;
+    /**
+     * Probe the remote again instead of answering from the host cache. The
+     * explicit "refresh status" action sets it; opening the panel does not,
+     * because a status probe runs `git fetch` and `ls-remote` per lane.
+     */
+    force?: boolean;
+}
+/** Per-worktree PR/merge status as the panel renders it. */
+export interface WorktreeStatusView {
+    /** Worktree name (== branch name). */
+    name: string;
+    /** Absolute worktree path. */
+    path: string;
+    /** Checked-out branch (null when detached). */
+    branch: string | null;
+    /** True when the remote-tracking ref for the branch exists after fetch. */
+    pushed: boolean;
+    /** True when the branch was pushed before but the remote branch is now gone. */
+    remoteBranchGone: boolean;
+    /** True when the branch is merged into the base (branch gone on remote, or
+     *  the branch tip is an ancestor of the base tip). */
+    merged: boolean;
+    /** The recorded PR url, when one was created through this plugin. */
+    prUrl: string | null;
+}
+/** Host response: per-repo PR/merge status index. */
+export interface WorktreeStatusIndex {
+    /** Base branch every status was resolved against. */
+    baseBranch: string;
+    worktrees: WorktreeStatusView[];
+    /**
+     * Candidate branches for dialogs: local branch short names, then remote
+     * `origin/*` names with the `origin/` prefix stripped, deduplicated in
+     * that order. Serves base-ref / base-commit dropdowns without another
+     * round trip (the panel probes one status per repo on open).
+     */
+    branches: string[];
+}
+/** Parameters for `POST /worktree/cleanup`. */
+export interface CleanupWorktreeInput {
+    /** Repository root. */
+    repoPath: string;
+    /** Worktree directory name under `.dsh/workspaces/`. */
+    name: string;
+    /** Force cleanup even when the branch is not merged (abandons the branch
+     *  and drops uncommitted changes). */
+    force?: boolean;
+    /** The conversation asking for the teardown, when it is the lane's own
+     *  conversation; see {@link RemoveWorktreeInput.sessionId}. */
+    sessionId?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/core/worktree/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/core/worktree/types.ts"],"names":[],"mappings":"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"}

package/lib/types/core/worktree/types.js

@@ -0,0 +1,14 @@
+/**
+ * Domain types shared between the host half and the browser half. Anything
+ * that crosses the HTTP boundary lands here first so the JSON contract is
+ * one source of truth.
+ *
+ * The plugin deliberately mirrors the official `ctx.workspaces` /
+ * `ctx.sessions` client-service shapes where it can — the browser side
+ * mirrors the official `@deepseek-ai/dsh-workspace` / `@deepseek-ai/dsh-session` faces
+ * (type-only) and aligns its derivation to the same `sessionIds` account
+ * the official WorkspaceBrowser uses, so a single source of truth
+ * governs session grouping and workspace display across both surfaces.
+ * @module @dsh-cove/dsh-client-ui-worktree/core
+ */
+export {};