@agimon-ai/doompi-git 0.0.1-alpha.0

package/src/types/webWorktrees.ts

@@ -0,0 +1,31 @@
+/**
+ * The cockpit's view of this session's worktrees.
+ *
+ * DESIGN PATTERNS:
+ * - Declarations only. The channel frame type is a constant so the hub and the
+ *   page cannot drift apart on a string.
+ * - A view is the subset of a record the dock needs, not the record. The
+ *   registry may hold paths and provenance the page has no business rendering.
+ *
+ * AVOID:
+ * - Adding behaviour here. This file is imported by browser code, so it must
+ *   stay free of node builtins.
+ */
+
+/** The data channel carrying one session's worktrees to the page. */
+export const GIT_WORKTREES_TYPE = 'git_worktrees';
+
+/** One worktree, as the activity dock and its panel render it. */
+export interface WorktreeView {
+  id: string;
+  branch: string;
+  path: string;
+  /** The session the hub started for this worktree, when it is still live. */
+  sessionId: string | null;
+  /** True once the directory the record names has gone missing. */
+  orphaned: boolean;
+}
+
+export interface GitWorktreesPayload {
+  worktrees: WorktreeView[];
+}

package/src/types/worktreeRegistry.ts

@@ -0,0 +1,69 @@
+/**
+ * The worktree registry: what this package knows about the worktrees it made.
+ *
+ * It deliberately does not mirror `git worktree list`. Git knows which
+ * worktrees exist; only this registry knows which of them this package created,
+ * which session runs in each, and which process to signal. Reconciling the two
+ * is how orphans are found, so the two views are kept separate on purpose.
+ */
+
+/**
+ * A worktree's lifecycle as this package sees it.
+ *
+ * `orphaned` is a finding, not a cleanup: the session process is gone or the
+ * directory has vanished, but the worktree may still hold uncommitted work, so
+ * the record is kept until someone decides what to do with it.
+ */
+export type WorktreeStatus = 'spawning' | 'running' | 'closing' | 'orphaned';
+
+export const WORKTREE_RECORD_VERSION = 1;
+
+export interface WorktreeRecord {
+  version: typeof WORKTREE_RECORD_VERSION;
+  /** This registry's own id, distinct from the session id, and stable across restarts. */
+  id: string;
+  /** The branch checked out in the worktree. */
+  branch: string;
+  /** The ref the branch was created from, kept so a merge can name its base. */
+  baseRef: string;
+  /** Absolute path to the worktree directory. */
+  path: string;
+  /** Absolute path to the repository the worktree belongs to. */
+  repositoryRoot: string;
+  /** The session spawned into the worktree. */
+  sessionId: string;
+  /** The session that asked for the worktree; the rail nests one under the other. */
+  parentSessionId: string;
+  status: WorktreeStatus;
+  /** ISO 8601. */
+  createdAt: string;
+}
+
+export interface WorktreeRegistryFile {
+  version: typeof WORKTREE_RECORD_VERSION;
+  entries: readonly WorktreeRecord[];
+}
+
+/** Reads the registry back, treating anything unusable as an empty registry. */
+export interface WorktreeRegistryStore {
+  list(): WorktreeRecord[];
+  /** Replaces the whole file. One writer per repository, so no merge is attempted. */
+  replace(entries: readonly WorktreeRecord[]): void;
+}
+
+/** The git operations this package needs, named in its own vocabulary. */
+export interface WorktreeGit {
+  addWorktree(input: { repositoryRoot: string; path: string; branch: string; baseRef: string }): Promise<void>;
+  removeWorktree(input: { repositoryRoot: string; path: string; force: boolean }): Promise<void>;
+  pruneWorktrees(repositoryRoot: string): Promise<void>;
+  /** Paths git currently lists for the repository, used to find orphans. */
+  listWorktreePaths(repositoryRoot: string): Promise<string[]>;
+  /** Files with uncommitted changes, empty when the tree is clean. */
+  dirtyFiles(path: string): Promise<string[]>;
+  /** The repository root for a directory, or undefined when it is not a repository. */
+  repositoryRoot(cwd: string): Promise<string | undefined>;
+  /** The branch currently checked out, used as the default base ref. */
+  currentBranch(cwd: string): Promise<string | undefined>;
+  /** Merges a worktree's branch into whatever the given root has checked out. */
+  mergeBranch(input: { repositoryRoot: string; branch: string; message?: string }): Promise<void>;
+}

package/src/web/components/RunWorktreeToolMessage.tsx

@@ -0,0 +1,37 @@
+import type { ToolMessageRenderProps } from '@agimon-ai/doompi-web-contracts';
+
+const ACTION_LABEL: Readonly<Record<string, string>> = {
+  spawn_worktree: 'Create worktree',
+  close_worktree: 'Close worktree',
+  list: 'List worktrees',
+  status: 'Worktree status',
+  merge: 'Merge worktree',
+  prune: 'Prune worktrees',
+  send: 'Message worktree',
+  messages: 'Read worktree messages',
+};
+
+/**
+ * The timeline item for `run_worktree`.
+ *
+ * The action and its subject go in the heading because that is what a reader
+ * scanning a transcript needs: "close_worktree a1b2c3d4" answers the question
+ * the raw JSON arguments make them decode.
+ */
+export function RunWorktreeToolMessage({ args, output, running, isError }: ToolMessageRenderProps) {
+  const action = typeof args.action === 'string' ? args.action : '';
+  const subject = typeof args.branch === 'string' ? args.branch : typeof args.id === 'string' ? args.id : '';
+
+  return (
+    <div className="flex flex-col gap-0.5">
+      <span className="text-[11px] font-bold text-doom-hi">
+        {ACTION_LABEL[action] ?? 'Worktree'}
+        {subject === '' ? '' : ` ${subject}`}
+        {running ? ' …' : ''}
+      </span>
+      {output !== '' && (
+        <pre className={`whitespace-pre-wrap text-[10px] ${isError ? 'text-doom-red' : 'text-doom-dim'}`}>{output}</pre>
+      )}
+    </div>
+  );
+}

package/src/web/components/WorktreesActivitySection.tsx

@@ -0,0 +1,62 @@
+/**
+ * The '# git' group's body in the activity dock.
+ *
+ * DESIGN PATTERNS:
+ * - One line per worktree, the same rule the runners rail follows: enough to
+ *   notice it, not enough to work with it. The group's own name opens the tab
+ *   that has room.
+ * - Idle still shows the launcher. A repository with no worktrees is the state
+ *   where someone most wants to make one.
+ *
+ * AVOID:
+ * - Doing work here. This section reports and launches; the panel and the tool
+ *   own everything else.
+ */
+import { Button } from '@agimon-ai/doompi-web-components';
+import type { WebPluginSlotProps } from '@agimon-ai/doompi-web-contracts';
+import { useStore } from '@tanstack/react-store';
+import type { WorktreeView } from '../../types/webWorktrees.ts';
+import { worktreeActivity } from '../stores/worktreesActivityStore.ts';
+import { worktreesTab } from './WorktreesPanel.tsx';
+
+export function WorktreesActivitySection({ sessionId, openTransientTab }: WebPluginSlotProps) {
+  const session = useStore(worktreeActivity.store, (state) => worktreeActivity.select(state, sessionId));
+
+  if (session.worktrees.length === 0) {
+    return (
+      <div className="flex items-center gap-2 px-1">
+        <p data-testid="activity-summary-git" className="px-1 text-[10px] text-doom-faint">
+          idle
+        </p>
+        {sessionId === null ? null : (
+          <Button
+            variant="link"
+            size="xs"
+            data-testid="activity-git-create"
+            className="px-0"
+            onClick={() => openTransientTab(worktreesTab())}
+          >
+            create a worktree
+          </Button>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div data-testid="activity-git-worktrees" className="flex flex-col gap-0.5">
+      {session.worktrees.map((worktree: WorktreeView) => (
+        <button
+          key={worktree.id}
+          type="button"
+          data-testid={`activity-git-worktree-${worktree.id}`}
+          className="flex items-center gap-2 px-1 text-left text-[11px] text-doom-dim hover:text-doom-bright"
+          onClick={() => openTransientTab(worktreesTab())}
+        >
+          <span className="truncate">{worktree.branch}</span>
+          {worktree.orphaned ? <span className="text-[10px] text-doom-faint">orphaned</span> : null}
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/web/components/WorktreesPanel.tsx

@@ -0,0 +1,109 @@
+/**
+ * The '# git' group's tab: this session's worktrees, and the form that makes one.
+ *
+ * DESIGN PATTERNS:
+ * - Lives in the activity dock, opened by the group's name. A worktree is work
+ *   in progress belonging to the session that started it, so it sits beside
+ *   agents, runners and workflows rather than in a settings screen.
+ * - Local form state is never reset by a data refresh. The hub republishes this
+ *   list on a timer, and a half-typed branch name must survive that.
+ * - Acts by asking the agent, so a worktree made here and one made by the tool
+ *   take exactly the same path.
+ *
+ * AVOID:
+ * - Deriving form state from props or store data. That is what wiped the
+ *   fields on every poll.
+ */
+import { Button, Input } from '@agimon-ai/doompi-web-components';
+import type { TransientTab, WebPluginSlotProps } from '@agimon-ai/doompi-web-contracts';
+import { useStore } from '@tanstack/react-store';
+import { useState } from 'react';
+import type { WorktreeView } from '../../types/webWorktrees.ts';
+import { requestWorktreeClose, requestWorktreeCreate, worktreeActivity } from '../stores/worktreesActivityStore.ts';
+
+const WORKTREES_TAB_ID = 'git-worktrees';
+
+export function worktreesTab(): TransientTab {
+  return { id: WORKTREES_TAB_ID, label: 'worktrees', panel: WorktreesPanel };
+}
+
+export function WorktreesPanel({ sessionId, sendSessionFrame }: WebPluginSlotProps) {
+  const session = useStore(worktreeActivity.store, (state) => worktreeActivity.select(state, sessionId));
+  const [branch, setBranch] = useState('');
+  const [baseRef, setBaseRef] = useState('');
+
+  const canCreate = sessionId !== null && branch.trim() !== '';
+
+  const create = (): void => {
+    if (sessionId === null || !canCreate) return;
+    requestWorktreeCreate(sendSessionFrame, sessionId, branch, baseRef);
+    setBranch('');
+    setBaseRef('');
+  };
+
+  return (
+    <div className="flex flex-col gap-3 p-3" data-testid="git-worktrees-panel">
+      <div className="flex flex-col gap-1">
+        <div className="flex items-center gap-2">
+          <Input
+            data-testid="git-worktree-branch"
+            aria-label="Branch"
+            placeholder="wt/fix-auth"
+            value={branch}
+            onChange={(event) => setBranch(event.target.value)}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter') create();
+            }}
+          />
+          <Input
+            data-testid="git-worktree-base"
+            aria-label="Base ref"
+            placeholder="base (current)"
+            value={baseRef}
+            onChange={(event) => setBaseRef(event.target.value)}
+            className="w-40"
+          />
+          <Button data-testid="git-worktree-create" size="xs" disabled={!canCreate} onClick={create}>
+            Create
+          </Button>
+        </div>
+        <p className="text-[10px] text-doom-faint">
+          Creates the worktree outside the repository, installs its dependencies, then starts a session nested under
+          this one. The install is what makes the wait; a warm store is under a minute.
+        </p>
+      </div>
+
+      {session.worktrees.length === 0 ? (
+        <p className="text-[11px] text-doom-faint">No worktrees yet.</p>
+      ) : (
+        <ul className="flex flex-col gap-1">
+          {session.worktrees.map((worktree: WorktreeView) => (
+            <li
+              key={worktree.id}
+              data-testid={`git-worktree-${worktree.id}`}
+              className="flex items-center justify-between gap-2 border border-doom-line px-2 py-1"
+            >
+              <div className="flex min-w-0 flex-col">
+                <span className="truncate text-[11px] text-doom-bright">{worktree.branch}</span>
+                <span className="truncate text-[10px] text-doom-faint">{worktree.path}</span>
+              </div>
+              <div className="flex items-center gap-2">
+                {worktree.orphaned ? <span className="text-[10px] text-doom-faint">orphaned</span> : null}
+                {sessionId === null ? null : (
+                  <Button
+                    variant="link"
+                    size="xs"
+                    data-testid={`git-worktree-close-${worktree.id}`}
+                    onClick={() => requestWorktreeClose(sendSessionFrame, sessionId, worktree.id)}
+                  >
+                    close
+                  </Button>
+                )}
+              </div>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/web/components/toolRenderers.ts

@@ -0,0 +1,7 @@
+import type { ToolRendererContribution } from '@agimon-ai/doompi-web-contracts';
+import { RunWorktreeToolMessage } from './RunWorktreeToolMessage.tsx';
+
+/** The timeline items for this package's tools. */
+export const gitToolRenderers: ToolRendererContribution[] = [
+  { tools: ['run_worktree'], message: RunWorktreeToolMessage },
+];

package/src/web/index.ts

@@ -0,0 +1,27 @@
+import { defineWebPlugin } from '@agimon-ai/doompi-web-contracts';
+import { gitToolRenderers } from './components/toolRenderers.ts';
+import { WorktreesActivitySection } from './components/WorktreesActivitySection.tsx';
+import { worktreesTab } from './components/WorktreesPanel.tsx';
+import { worktreeActivitySource, worktreesChannel } from './stores/worktreesActivityStore.ts';
+
+/** The named export the generated plugin registry imports. */
+export const webPlugin = defineWebPlugin({
+  id: 'git',
+  channels: [worktreesChannel],
+  activityGroups: [
+    {
+      name: 'git',
+      keys: 'g w',
+      // The source keeps the group present while idle, which is exactly when
+      // its launcher matters: a repository with no worktrees is where someone
+      // wants to make the first one.
+      activeSource: worktreeActivitySource,
+      // A standing worktree is not background work in progress; it is state.
+      marksBackgroundWork: false,
+      transientTab: worktreesTab,
+      order: 30,
+    },
+  ],
+  activitySections: [{ id: 'git', component: WorktreesActivitySection }],
+  toolRenderers: gitToolRenderers,
+});

package/src/web/stores/worktreesActivityStore.ts

@@ -0,0 +1,78 @@
+/**
+ * The dock's view of this session's worktrees.
+ *
+ * DESIGN PATTERNS:
+ * - Session-scoped store fed by one hub channel. The hub is authoritative; the
+ *   page never reads a registry and never guesses.
+ * - Actions are prompts, the same route the runner's launcher takes. The agent
+ *   owns the tool, so the panel asks for the work rather than performing it,
+ *   and a worktree made from the dock is indistinguishable from one the agent
+ *   made on its own.
+ *
+ * AVOID:
+ * - Calling the hub package API from here. A dock slot gets no sealed request
+ *   transport, and raw fetch breaks the remote cockpit.
+ */
+import { defineSessionStore, type SessionFrameSender } from '@agimon-ai/doompi-web-contracts';
+import { GIT_WORKTREES_TYPE, type WorktreeView } from '../../types/webWorktrees.ts';
+
+export interface WorktreesSession {
+  /** The worktrees the hub last reported for this session's repository. */
+  worktrees: WorktreeView[];
+}
+
+export const worktreeActivity = defineSessionStore<WorktreesSession>({ worktrees: [] });
+
+/**
+ * Keeps the group visible whenever this repository has worktrees.
+ *
+ * A worktree is standing state, not a burst of work: it stays until someone
+ * closes it, so its presence is what the dock reports.
+ */
+export const worktreeActivitySource = {
+  subscribe(listener: () => void) {
+    const subscription = worktreeActivity.store.subscribe(listener);
+    return () => subscription.unsubscribe();
+  },
+  isActive(sessionId: string | null) {
+    return worktreeActivity.select(worktreeActivity.store.state, sessionId).worktrees.length > 0;
+  },
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** The plugin's session data channel: 'git_worktrees' payloads into the store. */
+export const worktreesChannel = worktreeActivity.channel<WorktreesSession>({
+  channel: GIT_WORKTREES_TYPE,
+  parse(input) {
+    if (!isRecord(input) || !Array.isArray(input.worktrees)) return null;
+    return { worktrees: input.worktrees.filter(isRecord) as unknown as WorktreeView[] };
+  },
+  reduce(_current, next) {
+    return next;
+  },
+});
+
+/** Asks the agent for a worktree, through the tool it already owns. */
+export function requestWorktreeCreate(
+  send: SessionFrameSender,
+  sessionId: string,
+  branch: string,
+  baseRef: string,
+): void {
+  const base = baseRef.trim() === '' ? '' : ` from ${baseRef.trim()}`;
+  send(sessionId, {
+    type: 'prompt',
+    message: `Create a git worktree on branch ${branch.trim()}${base} using the run_worktree tool.`,
+  });
+}
+
+/** Asks the agent to close one worktree. Refusal on a dirty tree stays the tool's call. */
+export function requestWorktreeClose(send: SessionFrameSender, sessionId: string, id: string): void {
+  send(sessionId, {
+    type: 'prompt',
+    message: `Close the git worktree ${id} using the run_worktree tool.`,
+  });
+}

package/src/web/stores/worktreesStore.ts

@@ -0,0 +1,114 @@
+import { Store } from '@tanstack/store';
+import type { WorktreeRecord } from '../../types/worktreeRegistry.ts';
+
+const API_BASE = '/api/plugin/git';
+
+/**
+ * The host's transport, not the global fetch.
+ *
+ * A cockpit reached through the remote tunnel routes package API calls through
+ * a sealed transport; calling `fetch` directly works locally and then fails for
+ * exactly the users who are hardest to debug for.
+ */
+export type HostRequest = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface WorktreesState {
+  /** Keyed by repository, because the panel follows the focused session. */
+  byRepository: Record<string, readonly WorktreeRecord[]>;
+  loading: boolean;
+  /** The last failure, shown in place of a silent empty list. */
+  error: string | undefined;
+  busy: boolean;
+}
+
+export const worktreesStore = new Store<WorktreesState>({
+  byRepository: {},
+  loading: false,
+  error: undefined,
+  busy: false,
+});
+
+export function selectWorktrees(state: WorktreesState, repositoryId: string | null): readonly WorktreeRecord[] {
+  return repositoryId === null ? [] : (state.byRepository[repositoryId] ?? []);
+}
+
+async function readError(response: Response): Promise<string> {
+  const body = (await response.json().catch(() => ({}))) as { error?: string };
+  return body.error ?? `Request failed (${String(response.status)}).`;
+}
+
+/** Loads the worktrees for a repository, replacing whatever was shown. */
+export async function loadWorktrees(request: HostRequest, repositoryId: string): Promise<void> {
+  worktreesStore.setState((state) => ({ ...state, loading: true, error: undefined }));
+  try {
+    const response = await request(`${API_BASE}/worktrees?repositoryId=${encodeURIComponent(repositoryId)}`);
+    if (!response.ok) throw new Error(await readError(response));
+    const body = (await response.json()) as { worktrees: WorktreeRecord[] };
+    worktreesStore.setState((state) => ({
+      ...state,
+      loading: false,
+      byRepository: { ...state.byRepository, [repositoryId]: body.worktrees },
+    }));
+  } catch (error) {
+    worktreesStore.setState((state) => ({ ...state, loading: false, error: (error as Error).message }));
+  }
+}
+
+export interface CreateWorktreeInput {
+  repositoryId: string;
+  branch: string;
+  baseRef?: string;
+  name?: string;
+}
+
+/**
+ * Creates a worktree and its session through the hub.
+ *
+ * The same route the `run_worktree` tool calls. One path for both so the panel
+ * and the agent cannot drift into two different ideas of what creating a
+ * worktree means.
+ */
+export async function createWorktree(request: HostRequest, input: CreateWorktreeInput): Promise<boolean> {
+  worktreesStore.setState((state) => ({ ...state, busy: true, error: undefined }));
+  try {
+    const response = await request(`${API_BASE}/worktrees?repositoryId=${encodeURIComponent(input.repositoryId)}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        branch: input.branch,
+        ...(input.baseRef === undefined || input.baseRef === '' ? {} : { baseRef: input.baseRef }),
+        ...(input.name === undefined || input.name === '' ? {} : { name: input.name }),
+      }),
+    });
+    if (!response.ok) throw new Error(await readError(response));
+    await loadWorktrees(request, input.repositoryId);
+    worktreesStore.setState((state) => ({ ...state, busy: false }));
+    return true;
+  } catch (error) {
+    worktreesStore.setState((state) => ({ ...state, busy: false, error: (error as Error).message }));
+    return false;
+  }
+}
+
+/** Closes a worktree. `force` discards uncommitted work and is never implicit. */
+export async function closeWorktree(
+  request: HostRequest,
+  repositoryId: string,
+  id: string,
+  force: boolean,
+): Promise<boolean> {
+  worktreesStore.setState((state) => ({ ...state, busy: true, error: undefined }));
+  try {
+    const query = new URLSearchParams({ repositoryId, ...(force ? { force: 'true' } : {}) });
+    const response = await request(`${API_BASE}/worktrees/${encodeURIComponent(id)}?${query.toString()}`, {
+      method: 'DELETE',
+    });
+    if (!response.ok) throw new Error(await readError(response));
+    await loadWorktrees(request, repositoryId);
+    worktreesStore.setState((state) => ({ ...state, busy: false }));
+    return true;
+  } catch (error) {
+    worktreesStore.setState((state) => ({ ...state, busy: false, error: (error as Error).message }));
+    return false;
+  }
+}

package/src/web/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noImplicitAny": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [".", "../types/worktreeRegistry.ts", "../types/webWorktrees.ts", "../exports/webClient.ts"]
+}