From 0d89c51c368b98921d1a37e5465cac6390fc82ba Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Mon, 2 Nov 2026 08:47:57 +0100 Subject: [PATCH] feat(plugins): New workspace items set the branch and workspace metadata addNewWorkspaceItem mounts a plugin field on the New workspace screen, and useNewWorkspace() exposes host, project, isolation, base ref, branch and metadata with commands that follow the composer item rules: they act on the screen's state when they run, resolve once applied, reject while the screen is locked, and take JSON payloads. Host and project are read-only because a command that switched them would unmount the item that called it. The screen's pickable state (base selection, manual isolation, branch, metadata) moves into one plain store so pickers and plugin commands write to the same place; the screen reports derived facts to it on each render. The branch is sent as source.branchName only for a branch-off worktree, and metadata on workspace.create. Items render through ComposerControl with a new "field" surface (badge on desktop, full-width field when compact). Combobox ships here: Paseo owns the loading and error states, keeps previous results, and drops superseded searches. --- docs/plugins.md | 31 ++++ .../plugin-new-workspace-items.spec.ts | 20 +++ .../helpers/plugin-new-workspace-items.ts | 85 ++++++++++ packages/app/src/components/ui/combobox.tsx | 10 +- .../agent-controls/composer-control.tsx | 150 ++++++++++++++---- packages/app/src/i18n/resources/ar.ts | 5 + packages/app/src/i18n/resources/en.ts | 5 + packages/app/src/i18n/resources/es.ts | 5 + packages/app/src/i18n/resources/fr.ts | 5 + packages/app/src/i18n/resources/ja.ts | 5 + packages/app/src/i18n/resources/ko.ts | 5 + packages/app/src/i18n/resources/pt-BR.ts | 5 + packages/app/src/i18n/resources/ru.ts | 5 + packages/app/src/i18n/resources/zh-CN.ts | 5 + .../app/src/plugins/buttons/model.test.ts | 1 + .../command-center/contributions.test.ts | 1 + .../app/src/plugins/composer-items/index.tsx | 50 +----- .../src/plugins/composer-items/model.test.ts | 1 + packages/app/src/plugins/evaluate.ts | 17 ++ .../plugins/installation-provider.test.tsx | 1 + packages/app/src/plugins/item-host.tsx | 74 +++++++++ .../src/plugins/new-workspace-items/index.tsx | 101 ++++++++++++ .../src/plugins/new-workspace-items/model.ts | 40 +++++ .../composer-controls.browser.test.tsx | 142 +++++++++++++++++ .../react-native/composer-controls.tsx | 110 ++++++++++++- packages/app/src/plugins/react-native/ui.ts | 2 +- packages/app/src/plugins/registry.ts | 1 + .../app/src/plugins/sidebar-groups.test.ts | 1 + .../src/plugins/surface-contribution.test.ts | 1 + packages/app/src/plugins/theme.test.ts | 1 + .../app/src/plugins/timeline/model.test.ts | 1 + packages/app/src/plugins/types.ts | 3 + .../workspace-panels/resolution.test.ts | 1 + .../src/screens/new-workspace-picker-item.ts | 2 +- .../app/src/screens/new-workspace-screen.tsx | 120 +++++++++++--- .../src/screens/new-workspace/form/index.tsx | 6 +- .../screens/new-workspace/setup-model.test.ts | 87 ++++++++++ .../src/screens/new-workspace/setup-model.ts | 128 +++++++++++++++ packages/plugin/src/boundaries.test.ts | 45 ++++++ packages/plugin/src/client/contracts.ts | 2 + packages/plugin/src/client/host.ts | 1 + packages/plugin/src/client/index.ts | 6 + packages/plugin/src/client/new-workspace.tsx | 65 ++++++++ packages/plugin/src/client/ui.ts | 29 +++- .../new-workspace-issues/README.md | 17 ++ .../client/issue-field.tsx | 31 ++++ .../new-workspace-issues/index.client.tsx | 7 + .../new-workspace-issues/index.server.ts | 8 + .../new-workspace-issues/paseo-plugin.json | 4 + .../new-workspace-issues/server/issues.ts | 26 +++ .../new-workspace-issues/shared/issues.ts | 18 +++ public-docs/plugins/index.md | 1 + public-docs/plugins/index.zh-CN.md | 2 +- public-docs/plugins/reference.md | 71 +++++++++ public-docs/plugins/reference.zh-CN.md | 57 +++++++ 55 files changed, 1517 insertions(+), 106 deletions(-) create mode 100644 packages/app/e2e/browser/plugin-new-workspace-items.spec.ts create mode 100644 packages/app/e2e/support/helpers/plugin-new-workspace-items.ts create mode 100644 packages/app/src/plugins/item-host.tsx create mode 100644 packages/app/src/plugins/new-workspace-items/index.tsx create mode 100644 packages/app/src/plugins/new-workspace-items/model.ts create mode 100644 packages/app/src/plugins/react-native/composer-controls.browser.test.tsx create mode 100644 packages/app/src/screens/new-workspace/setup-model.test.ts create mode 100644 packages/app/src/screens/new-workspace/setup-model.ts create mode 100644 packages/plugin/src/client/new-workspace.tsx create mode 100644 plugin-examples/new-workspace-issues/README.md create mode 100644 plugin-examples/new-workspace-issues/client/issue-field.tsx create mode 100644 plugin-examples/new-workspace-issues/index.client.tsx create mode 100644 plugin-examples/new-workspace-issues/index.server.ts create mode 100644 plugin-examples/new-workspace-issues/paseo-plugin.json create mode 100644 plugin-examples/new-workspace-issues/server/issues.ts create mode 100644 plugin-examples/new-workspace-issues/shared/issues.ts diff --git a/docs/plugins.md b/docs/plugins.md index 79220ef80a..847cbc3009 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -673,6 +673,37 @@ The overflow sheet's content portals to the app root, away from the composer. Pa `useComposerSheetBridge()` as the sheet's `contextBridge`, or `useComposer()` returns nothing and the sheet draws no plugin rows. +## Contribute New workspace items + +`addNewWorkspaceItem` mounts a plugin component on the New workspace screen. The public contract +is the [New workspace items reference](../public-docs/plugins/reference.md#new-workspace-items). + +The screen's choices that a plugin may change live in one plain store, +`createNewWorkspaceSetup` (`packages/app/src/screens/new-workspace/setup-model.ts`): the base +picker selection, the manual isolation, the branch name and the workspace metadata. The pickers and +the plugin commands write to it, so a command sees what an earlier command left. Project and host +stay in the screen's hooks (`useNewWorkspaceHostSelector` reconciles them against each other), and +they are read-only to plugins; a command that switched them would unmount the item that called it. + +The screen reports what it derives from those hooks (the lock, the project, whether the project +can make worktrees, whether the host supports metadata, and the pickers' own handlers) to the store +with `setup.report` on every render. Commands read it when they run, never from the render that +built them. `chooseIsolation` and `chooseBase` are the pickers' handlers, so a plugin command has the +effects of a pick. Add a capability by extending the store and its facts; do not read screen state +from a plugin component. + +`ensureWorkspace` sends the store's `branch` as `source.branchName` only for a branch-off worktree +(`checkoutRequest.action === "branch-off"`), and its `metadata` on `workspace.create` when it is +not empty. The server uses `branchName ?? worktreeSlug` as the new branch. + +Items render through `ComposerControl` with `surface="field"`: a `FieldTrigger` (a badge on +desktop, a full-width field when compact) and the same pending state, error toast and list as the +composer's controls. `ComposerControlLockProvider` carries the screen's lock to them. Plugin +`Combobox` is a `select` item with `remoteSearch`: the app `Combobox` does not filter locally, and +`PluginCombobox` (`plugins/react-native/composer-controls.tsx`) runs `search` through +`useFetchQuery` with `dataShape: "list"`, which keeps the previous results while a newer query runs. +`plugins/item-host.tsx` is the host shared by composer and New workspace items. + ## Contribute timeline items Timeline transformers and renderers are client contributions. The daemon's canonical rows and diff --git a/packages/app/e2e/browser/plugin-new-workspace-items.spec.ts b/packages/app/e2e/browser/plugin-new-workspace-items.spec.ts new file mode 100644 index 0000000000..3460464fb3 --- /dev/null +++ b/packages/app/e2e/browser/plugin-new-workspace-items.spec.ts @@ -0,0 +1,20 @@ +import { expect, test } from "../support/fixtures"; +import { withNewWorkspaceIssuesExample } from "../support/helpers/plugin-new-workspace-items"; + +for (const layout of [ + { name: "desktop", compact: false }, + { name: "compact", compact: true }, +]) { + test(`a plugin's New workspace item sets the branch and metadata on ${layout.name}`, async ({ + page, + }) => { + test.setTimeout(180_000); + await withNewWorkspaceIssuesExample(page, { compact: layout.compact }, async (screen) => { + await screen.chooseWorktree(); + await screen.chooseIssue("PAS-102 Crash on resume"); + const created = await screen.createWorkspace(); + expect(created.branch).toBe("pas-102-crash-on-resume"); + expect(created.metadata).toEqual({ "new-workspace-issues.issue": "PAS-102" }); + }); + }); +} diff --git a/packages/app/e2e/support/helpers/plugin-new-workspace-items.ts b/packages/app/e2e/support/helpers/plugin-new-workspace-items.ts new file mode 100644 index 0000000000..8655ded6e5 --- /dev/null +++ b/packages/app/e2e/support/helpers/plugin-new-workspace-items.ts @@ -0,0 +1,85 @@ +import { expect, test, type Page } from "@playwright/test"; +import { gotoAppShell } from "./app"; +import { + archiveWorkspaceFromDaemon, + assertNewWorkspaceSidebarAndHeader, + connectNewWorkspaceDaemonClient, + openNewWorkspaceComposer, + openProjectViaDaemon, + submitNewWorkspacePrompt, +} from "./new-workspace"; +import { copyPluginExample } from "./plugin-fixture"; +import { getServerId } from "./server-id"; +import { createTempGitRepo } from "./workspace"; +import { waitForSidebarHydration } from "./workspace-ui"; + +const PLUGIN_ID = "new-workspace-issues-example"; +const COMPACT = { width: 500, height: 800 }; + +/** Runs `run` on the New workspace screen with the new-workspace-issues example installed. */ +export async function withNewWorkspaceIssuesExample( + page: Page, + options: { compact: boolean }, + run: (screen: { + chooseWorktree(): Promise; + chooseIssue(label: string): Promise; + createWorkspace(): Promise<{ branch: string | null; metadata: unknown }>; + }) => Promise, +) { + const client = await connectNewWorkspaceDaemonClient(); + const previous = await client.getDaemonConfig(); + const example = await copyPluginExample("new-workspace-issues"); + const repo = await createTempGitRepo("new-workspace-issues-", { branches: ["main"] }); + let createdDirectory: string | null = null; + try { + await client.patchDaemonConfig({ pluginsEnabled: true }); + await client.installDirectoryPlugin(example.directory); + const project = await openProjectViaDaemon(client, repo.path); + await gotoAppShell(page); + await waitForSidebarHydration(page); + await openNewWorkspaceComposer(page, project); + // The sidebar rows used to reach the screen exist only at desktop width. + if (options.compact) await page.setViewportSize(COMPACT); + await run({ + chooseWorktree: () => + test.step("choose a new worktree", async () => { + await page.getByTestId("workspace-create-isolation-trigger").click(); + await page.getByTestId("workspace-create-isolation-worktree").click(); + }), + chooseIssue: (label) => + test.step(`choose the issue "${label}"`, async () => { + await page.getByRole("button", { name: "Issue", exact: true }).click(); + await page.getByText(label, { exact: true }).click(); + }), + createWorkspace: () => + test.step("create the workspace and read what it carries", async () => { + await submitNewWorkspacePrompt(page); + const created = await assertNewWorkspaceSidebarAndHeader(page, { + serverId: getServerId(), + client, + previousWorkspaceId: project.workspaceId, + projectDisplayName: project.projectDisplayName, + // The sidebar is closed at compact width. + assertSidebarRow: !options.compact, + }); + createdDirectory = created.workspaceDirectory; + const { entries } = await client.fetchWorkspaces(); + const workspace = entries.find((entry) => entry.id === created.workspaceId); + expect(workspace).toBeDefined(); + return { + branch: workspace?.gitRuntime?.currentBranch ?? null, + metadata: workspace?.metadata, + }; + }), + }); + } finally { + if (createdDirectory) { + await archiveWorkspaceFromDaemon(client, createdDirectory).catch(() => undefined); + } + await client.removePlugin(PLUGIN_ID).catch(() => undefined); + await client.patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled }); + await client.close(); + await example.cleanup(); + await repo.cleanup(); + } +} diff --git a/packages/app/src/components/ui/combobox.tsx b/packages/app/src/components/ui/combobox.tsx index adcd91afcb..18d575d3e0 100644 --- a/packages/app/src/components/ui/combobox.tsx +++ b/packages/app/src/components/ui/combobox.tsx @@ -89,6 +89,8 @@ export interface ComboboxProps { }) => ReactElement; onSearchQueryChange?: (query: string) => void; searchable?: boolean; + /** The caller answers the search query itself, so the options are shown as given. */ + remoteSearch?: boolean; placeholder?: string; searchPlaceholder?: string; emptyText?: string; @@ -1292,6 +1294,10 @@ function DesktopComboboxBody(props: DesktopBodyProps): ReactElement | null { ); } +function filtersLocally(input: { searchable: boolean; remoteSearch?: boolean }): boolean { + return input.searchable && !input.remoteSearch; +} + export function Combobox({ options, value, @@ -1299,6 +1305,7 @@ export function Combobox({ renderOption, onSearchQueryChange, searchable = true, + remoteSearch, placeholder, searchPlaceholder, emptyText, @@ -1458,7 +1465,7 @@ export function Combobox({ buildVisibleComboboxOptions({ options, searchQuery, - searchable, + searchable: filtersLocally({ searchable, remoteSearch }), allowCustomValue, customValuePrefix, customValueDescription, @@ -1470,6 +1477,7 @@ export function Combobox({ customValueKind, customValuePrefix, options, + remoteSearch, searchQuery, searchable, ], diff --git a/packages/app/src/composer/agent-controls/composer-control.tsx b/packages/app/src/composer/agent-controls/composer-control.tsx index 80536846f8..f98be7261f 100644 --- a/packages/app/src/composer/agent-controls/composer-control.tsx +++ b/packages/app/src/composer/agent-controls/composer-control.tsx @@ -1,5 +1,6 @@ import { createContext, + forwardRef, useCallback, useContext, useMemo, @@ -14,6 +15,9 @@ import { StyleSheet } from "react-native-unistyles"; import type { AgentControlIcon } from "@/agent-controls/icons"; import type { SheetHeader } from "@/components/adaptive-modal-sheet"; import { Combobox, type ComboboxOption } from "@/components/ui/combobox"; +import { useIsCompactFormFactor } from "@/constants/layout"; +import { FieldTrigger } from "@/screens/new-workspace/form/field-trigger"; +import { ICON_SIZE } from "@/styles/theme"; import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"; import { AgentControlTrigger } from "@/composer/agent-controls/control"; import { useToast } from "@/contexts/toast-api-context"; @@ -39,8 +43,9 @@ export interface ComposerControlChoice { } /** - * One control in the composer's toolbar, drawn from data. Provider option controls, thinking and - * plugin controls all come through here, so each is an icon in the toolbar and a row in the sheet. + * One control, drawn from data. Provider option controls, thinking and plugin controls all come + * through here, so each is an icon in the composer toolbar, a row in its sheet, or, in a New + * workspace item, a field. The name stays from when the composer was the only place it drew. */ export type ComposerControlItem = | (ComposerControlBase & { @@ -52,11 +57,17 @@ export type ComposerControlItem = type: "select"; value: string | null; choices: readonly ComposerControlChoice[]; + /** Names a value the choices do not list, such as a pick that a search no longer returns. */ + valueLabel?: string; onChange: (value: string) => void | Promise; /** The toolbar trigger shows only the icon. */ iconOnly?: boolean; showCaret?: boolean; searchable?: boolean; + /** The list answers `onSearchQueryChange` itself, so it is not filtered again. */ + remoteSearch?: boolean; + onSearchQueryChange?: (query: string) => void; + emptyText?: string; desktopMinWidth?: number; renderOption?: (args: { option: ComboboxOption; @@ -70,12 +81,21 @@ export type ComposerControlItem = onPress: () => void | Promise; }); -export type ComposerControlSurface = "toolbar" | "sheet"; +/** `field`: a New workspace setup field, a badge on desktop and a full-width field when compact. */ +export type ComposerControlSurface = "toolbar" | "sheet" | "field"; const ComposerControlSurfaceContext = createContext("toolbar"); export const ComposerControlSurfaceProvider = ComposerControlSurfaceContext.Provider; -/** Where the control being drawn sits: the toolbar, or a row in the overflow sheet. */ +const ComposerControlLockContext = createContext(false); +/** Disables every control below it, for a surface that is not a composer and has its own lock. */ +export const ComposerControlLockProvider = ComposerControlLockContext.Provider; + +export function useComposerControlLocked(): boolean { + return useContext(ComposerControlLockContext); +} + +/** Where the control being drawn sits: the toolbar, a row in the overflow sheet, or a field. */ export function useComposerControlSurface(): ComposerControlSurface { return useContext(ComposerControlSurfaceContext); } @@ -133,7 +153,9 @@ function describeControl( }; } const choiceLabel = - item.choices.find((choice) => choice.value === item.value)?.label ?? item.title; + item.choices.find((choice) => choice.value === item.value)?.label ?? + item.valueLabel ?? + item.title; const iconOnly = item.iconOnly === true; return { options: item.choices.map((choice) => ({ @@ -150,22 +172,24 @@ function describeControl( }; } -export function ComposerControl({ - item, - surface, - disabled = false, - open, - onOpenChange, - onActionComplete, -}: ComposerControlProps) { - const { t } = useTranslation(); - const anchorRef = useRef(null); - const isSheet = surface === "sheet"; - const sheetHeader = useMemo(() => ({ title: item.title }), [item.title]); - const view = useMemo(() => describeControl(item, surface, t), [item, surface, t]); +type SelectItem = Extract; - // A command that returns a promise keeps the control pending until it settles, and a failure - // reaches the user the way a built-in live control's does. +/** The list options only a select carries; a toggle's two-choice list has none of them. */ +function listProps(select: SelectItem | null) { + if (!select) return { searchable: false }; + return { + desktopMinWidth: select.desktopMinWidth, + searchable: select.searchable, + remoteSearch: select.remoteSearch, + onSearchQueryChange: select.onSearchQueryChange, + emptyText: select.emptyText, + renderOption: select.renderOption, + }; +} + +// A command that returns a promise keeps the control pending until it settles, and a failure +// reaches the user the way a built-in live control's does. +function usePendingRun() { const toast = useToast(); const [pending, setPending] = useState(false); const run = useCallback( @@ -183,6 +207,25 @@ export function ComposerControl({ }, [toast], ); + return { pending, run }; +} + +export function ComposerControl({ + item, + surface, + disabled = false, + open, + onOpenChange, + onActionComplete, +}: ComposerControlProps) { + const { t } = useTranslation(); + const anchorRef = useRef(null); + const isSheet = surface === "sheet"; + const isField = surface === "field"; + const sheetHeader = useMemo(() => ({ title: item.title }), [item.title]); + const view = useMemo(() => describeControl(item, surface, t), [item, surface, t]); + + const { pending, run } = usePendingRun(); const handlePress = useCallback(() => { if (item.type === "toggle") run(() => item.onChange(!item.value)); else if (item.type === "action") run(item.onPress); @@ -198,7 +241,17 @@ export function ComposerControl({ ); const select = item.type === "select" ? item : null; - const trigger = ( + const accessibilityLabel = item.accessibilityLabel ?? view.tooltip; + const trigger = isField ? ( + + ) : ( ); return ( <> - {isSheet ? ( + {isSheet || isField ? ( trigger ) : ( @@ -239,10 +292,8 @@ export function ComposerControl({ onOpenChange={onOpenChange} anchorRef={anchorRef} presentation={isSheet ? "push" : undefined} - desktopPlacement={isSheet ? undefined : "top-start"} - desktopMinWidth={select?.desktopMinWidth} - searchable={select ? select.searchable : false} - renderOption={select?.renderOption} + desktopPlacement={DESKTOP_PLACEMENT[surface]} + {...listProps(select)} header={isSheet ? sheetHeader : undefined} /> ) : null} @@ -250,6 +301,50 @@ export function ComposerControl({ ); } +/** Where a list opens on desktop; the sheet has its own presentation. */ +const DESKTOP_PLACEMENT = { + toolbar: "top-start", + sheet: undefined, + field: "bottom-start", +} as const; + +/** What a field shows: a badge has no label, so a toggle names itself beside its state. */ +function fieldValue(item: ComposerControlItem, view: ControlView, compact: boolean): string { + if (item.type === "action") return item.title; + if (item.type === "toggle" && !compact) return `${item.title}: ${view.value}`; + return view.value; +} + +const FieldControlTrigger = forwardRef< + View, + { + item: ComposerControlItem; + view: ControlView; + accessibilityLabel: string; + disabled: boolean; + onPress: () => void; + } +>(function FieldControlTrigger({ item, view, accessibilityLabel, disabled, onPress }, ref) { + const compact = useIsCompactFormFactor(); + const Icon = item.icon; + const iconColor = item.highlight ? styles[item.highlight].color : styles.fieldIcon.color; + const icon = useMemo(() => , [Icon, iconColor]); + return ( + + ); +}); + interface ComposerControlsProps { items: readonly ComposerControlItem[]; surface: ComposerControlSurface; @@ -296,6 +391,7 @@ function ComposerControlSlot({ } const styles = StyleSheet.create((theme) => ({ + fieldIcon: { color: theme.colors.foregroundMuted }, blue: { color: theme.colors.palette.blue[400] }, green: { color: theme.colors.palette.green[400] }, yellow: { color: theme.colors.palette.yellow[400] }, diff --git a/packages/app/src/i18n/resources/ar.ts b/packages/app/src/i18n/resources/ar.ts index 8d7c2a2950..d30c6b3007 100644 --- a/packages/app/src/i18n/resources/ar.ts +++ b/packages/app/src/i18n/resources/ar.ts @@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en"; import { pluginSettings } from "./plugin-settings"; export const ar: TranslationResources = { + pluginCombobox: { + searching: "جارٍ البحث…", + empty: "لا توجد نتائج", + failed: "فشل البحث: {{message}}", + }, paneFind: { connectionFailure: "تعذر البحث في هذه المحادثة. تحقق من الاتصال بالمضيف وأعد المحاولة.", historyChangedFailure: "تغيّرت المحادثة أثناء البحث. أعد البحث.", diff --git a/packages/app/src/i18n/resources/en.ts b/packages/app/src/i18n/resources/en.ts index 1f61a83f12..0b69744fde 100644 --- a/packages/app/src/i18n/resources/en.ts +++ b/packages/app/src/i18n/resources/en.ts @@ -1,4 +1,9 @@ export const en = { + pluginCombobox: { + searching: "Searching…", + empty: "No results", + failed: "Search failed: {{message}}", + }, paneFind: { connectionFailure: "Could not search this chat. Check the host connection and retry.", historyChangedFailure: "The chat changed while searching. Search again.", diff --git a/packages/app/src/i18n/resources/es.ts b/packages/app/src/i18n/resources/es.ts index 7e5a1d41e6..186f164317 100644 --- a/packages/app/src/i18n/resources/es.ts +++ b/packages/app/src/i18n/resources/es.ts @@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en"; import { pluginSettings } from "./plugin-settings"; export const es: TranslationResources = { + pluginCombobox: { + searching: "Buscando…", + empty: "Sin resultados", + failed: "La búsqueda falló: {{message}}", + }, paneFind: { connectionFailure: "No se pudo buscar en este chat. Comprueba la conexión con el host y vuelve a intentarlo.", diff --git a/packages/app/src/i18n/resources/fr.ts b/packages/app/src/i18n/resources/fr.ts index 551f4a4158..115ea515d9 100644 --- a/packages/app/src/i18n/resources/fr.ts +++ b/packages/app/src/i18n/resources/fr.ts @@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en"; import { pluginSettings } from "./plugin-settings"; export const fr: TranslationResources = { + pluginCombobox: { + searching: "Recherche…", + empty: "Aucun résultat", + failed: "Échec de la recherche : {{message}}", + }, paneFind: { connectionFailure: "Impossible de rechercher dans cette conversation. Vérifiez la connexion à l’hôte et réessayez.", diff --git a/packages/app/src/i18n/resources/ja.ts b/packages/app/src/i18n/resources/ja.ts index 4b1b8b6f64..4657a49548 100644 --- a/packages/app/src/i18n/resources/ja.ts +++ b/packages/app/src/i18n/resources/ja.ts @@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en"; import { pluginSettings } from "./plugin-settings"; export const ja: TranslationResources = { + pluginCombobox: { + searching: "検索中…", + empty: "結果がありません", + failed: "検索に失敗しました: {{message}}", + }, paneFind: { connectionFailure: "このチャットを検索できませんでした。ホストへの接続を確認して再試行してください。", diff --git a/packages/app/src/i18n/resources/ko.ts b/packages/app/src/i18n/resources/ko.ts index b9e33b4eba..6737f13c1e 100644 --- a/packages/app/src/i18n/resources/ko.ts +++ b/packages/app/src/i18n/resources/ko.ts @@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en"; import { pluginSettings } from "./plugin-settings"; export const ko: TranslationResources = { + pluginCombobox: { + searching: "검색 중…", + empty: "결과 없음", + failed: "검색 실패: {{message}}", + }, paneFind: { connectionFailure: "이 채팅을 검색할 수 없습니다. 호스트 연결을 확인하고 다시 시도하세요.", historyChangedFailure: "검색 중에 채팅이 변경되었습니다. 다시 검색하세요.", diff --git a/packages/app/src/i18n/resources/pt-BR.ts b/packages/app/src/i18n/resources/pt-BR.ts index 2fa6c30c8e..6b751f0e32 100644 --- a/packages/app/src/i18n/resources/pt-BR.ts +++ b/packages/app/src/i18n/resources/pt-BR.ts @@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en"; import { pluginSettings } from "./plugin-settings"; export const ptBR: TranslationResources = { + pluginCombobox: { + searching: "Pesquisando…", + empty: "Nenhum resultado", + failed: "Falha na pesquisa: {{message}}", + }, paneFind: { connectionFailure: "Não foi possível pesquisar nesta conversa. Verifique a conexão com o host e tente novamente.", diff --git a/packages/app/src/i18n/resources/ru.ts b/packages/app/src/i18n/resources/ru.ts index 9a6eb5b0e2..fb0fad1dd7 100644 --- a/packages/app/src/i18n/resources/ru.ts +++ b/packages/app/src/i18n/resources/ru.ts @@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en"; import { pluginSettings } from "./plugin-settings"; export const ru: TranslationResources = { + pluginCombobox: { + searching: "Поиск…", + empty: "Нет результатов", + failed: "Не удалось выполнить поиск: {{message}}", + }, paneFind: { connectionFailure: "Не удалось выполнить поиск в чате. Проверьте подключение к хосту и повторите попытку.", diff --git a/packages/app/src/i18n/resources/zh-CN.ts b/packages/app/src/i18n/resources/zh-CN.ts index 553d8212b4..5f4d8638eb 100644 --- a/packages/app/src/i18n/resources/zh-CN.ts +++ b/packages/app/src/i18n/resources/zh-CN.ts @@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en"; import { pluginSettings } from "./plugin-settings"; export const zhCN: TranslationResources = { + pluginCombobox: { + searching: "搜索中…", + empty: "无结果", + failed: "搜索失败：{{message}}", + }, paneFind: { connectionFailure: "无法搜索此聊天。请检查主机连接后重试。", historyChangedFailure: "搜索期间聊天已更改。请重新搜索。", diff --git a/packages/app/src/plugins/buttons/model.test.ts b/packages/app/src/plugins/buttons/model.test.ts index 7f7a1da2b4..a17ce80cff 100644 --- a/packages/app/src/plugins/buttons/model.test.ts +++ b/packages/app/src/plugins/buttons/model.test.ts @@ -24,6 +24,7 @@ function installation(): InstalledPlugin { legacySidebarItems: [], filePanels: [], composerItems: [], + newWorkspaceItems: [], workspacePanels: [], commandCenterItems: [], clientSlashCommands: [], diff --git a/packages/app/src/plugins/command-center/contributions.test.ts b/packages/app/src/plugins/command-center/contributions.test.ts index 9eccfab943..e4a388cbb9 100644 --- a/packages/app/src/plugins/command-center/contributions.test.ts +++ b/packages/app/src/plugins/command-center/contributions.test.ts @@ -84,6 +84,7 @@ function plugin(onAgentSelect: AgentCommandItem["onSelect"]): InstalledPlugin { legacySidebarItems: [], filePanels: [], composerItems: [], + newWorkspaceItems: [], workspacePanels: [ { id: "details", diff --git a/packages/app/src/plugins/composer-items/index.tsx b/packages/app/src/plugins/composer-items/index.tsx index 309dac4c36..b116da2a09 100644 --- a/packages/app/src/plugins/composer-items/index.tsx +++ b/packages/app/src/plugins/composer-items/index.tsx @@ -7,25 +7,12 @@ import { type ComposerControlSurface, } from "@/composer/agent-controls/composer-control"; import { useComposerAgent, useComposerInput } from "@/composer/session"; -import { useIsCompactFormFactor } from "@/constants/layout"; -import { useToast } from "@/contexts/toast-api-context"; -import { useHosts } from "@/runtime/host-runtime"; -import type { Theme } from "@/styles/theme"; -import { createPluginClientStateSource } from "../client-state/source"; -import { resolvePluginPlatform } from "../platform"; -import { PluginEnvironmentProvider, type PluginEnvironment } from "../popover"; +import { PluginItemList, pluginThemeMapping, usePluginItemHost } from "../item-host"; +import { PluginEnvironmentProvider } from "../popover"; import { useInstalledPlugins } from "../registry"; -import { SurfaceErrorBoundary } from "../surface-error-boundary"; -import { toPluginTheme } from "../theme"; import type { InstalledPlugin } from "../types"; import { toPluginComposer } from "./model"; -const pluginThemeMapping = (theme: Theme) => ({ theme: toPluginTheme(theme) }); - -function renderNothing() { - return null; -} - function useServerPlugins(serverId: string | null): InstalledPlugin[] { const installed = useInstalledPlugins(); return useMemo( @@ -76,52 +63,23 @@ function PluginComposerItemsHost({ }) { const agent = useComposerAgent(); const composerInput = useComposerInput(); - const toast = useToast(); - const compact = useIsCompactFormFactor(); - const hosts = useHosts(); - const hostLabel = - hosts.find((host) => host.serverId === plugin.serverId)?.label ?? plugin.serverId; + const { environment, props } = usePluginItemHost(plugin, theme); const textSource = composerInput?.textSource; const prompt = useSyncExternalStore( textSource?.subscribe ?? subscribeNothing, textSource?.getSnapshot ?? emptyText, textSource?.getSnapshot ?? emptyText, ); - const environment = useMemo( - () => ({ - installation: plugin, - toast, - state: createPluginClientStateSource(plugin.serverId), - }), - [plugin, toast], - ); const composer = useMemo( () => agent && composerInput ? toPluginComposer({ plugin, agent, composerInput, prompt }) : null, [agent, composerInput, plugin, prompt], ); - const props = useMemo( - () => ({ - theme, - host: { id: plugin.serverId, label: hostLabel }, - layout: { compact, platform: resolvePluginPlatform() }, - }), - [compact, hostLabel, plugin.serverId, theme], - ); if (!composer) return null; return ( - {plugin.composerItems.map(({ id, Component }) => ( - - - - ))} + ); diff --git a/packages/app/src/plugins/composer-items/model.test.ts b/packages/app/src/plugins/composer-items/model.test.ts index e75585e36f..0e1fa9718b 100644 --- a/packages/app/src/plugins/composer-items/model.test.ts +++ b/packages/app/src/plugins/composer-items/model.test.ts @@ -27,6 +27,7 @@ function installed(): InstalledPlugin { legacySidebarItems: [], filePanels: [], composerItems: [], + newWorkspaceItems: [], workspacePanels: [], commandCenterItems: [], clientSlashCommands: [], diff --git a/packages/app/src/plugins/evaluate.ts b/packages/app/src/plugins/evaluate.ts index c2a7e82838..ab7d3cac9f 100644 --- a/packages/app/src/plugins/evaluate.ts +++ b/packages/app/src/plugins/evaluate.ts @@ -132,6 +132,7 @@ export function runPluginClientBundle( legacySidebarItems: [], filePanels: [], composerItems: [], + newWorkspaceItems: [], workspacePanels: [], commandCenterItems: [], clientSlashCommands: [], @@ -148,6 +149,7 @@ export function runPluginClientBundle( }; const filePanelIds = new Set(); const composerItemIds = new Set(); + const newWorkspaceItemIds = new Set(); const workspacePanelIds = new Set(); const commandCenterItemIds = new Set(); const clientSlashCommandNames = new Set(); @@ -285,6 +287,20 @@ export function runPluginClientBundle( () => composerItemIds.delete(normalizedId), ); }, + addNewWorkspaceItem(contribution) { + const normalizedId = requireId(contribution.id, "New workspace item id"); + if (newWorkspaceItemIds.has(normalizedId)) + throw new Error(`Duplicate New workspace item: ${normalizedId}`); + if (!isComponentType(contribution.Component)) { + throw new Error(`New workspace item ${normalizedId} is not a component`); + } + newWorkspaceItemIds.add(normalizedId); + return register( + collector.newWorkspaceItems, + { id: normalizedId, Component: contribution.Component }, + () => newWorkspaceItemIds.delete(normalizedId), + ); + }, addSidebarHeaderItem(contribution: PluginSidebarItemContribution) { return addSidebarItem("header", contribution); }, @@ -602,6 +618,7 @@ export function runPluginClientBundle( legacySidebarItems: collector.legacySidebarItems, filePanels: collector.filePanels, composerItems: collector.composerItems, + newWorkspaceItems: collector.newWorkspaceItems, workspacePanels: collector.workspacePanels as EvaluatedPlugin["workspacePanels"], commandCenterItems: collector.commandCenterItems, clientSlashCommands: collector.clientSlashCommands, diff --git a/packages/app/src/plugins/installation-provider.test.tsx b/packages/app/src/plugins/installation-provider.test.tsx index 8744ed78bd..5c7828cdc5 100644 --- a/packages/app/src/plugins/installation-provider.test.tsx +++ b/packages/app/src/plugins/installation-provider.test.tsx @@ -37,6 +37,7 @@ function installation(invoked: string[]): InstalledPlugin { legacySidebarItems: [], filePanels: [], composerItems: [], + newWorkspaceItems: [], workspacePanels: [], commandCenterItems: [], clientSlashCommands: [], diff --git a/packages/app/src/plugins/item-host.tsx b/packages/app/src/plugins/item-host.tsx new file mode 100644 index 0000000000..2df4198e7a --- /dev/null +++ b/packages/app/src/plugins/item-host.tsx @@ -0,0 +1,74 @@ +import { useMemo, type ComponentType } from "react"; +import type { PluginHostProps } from "@getpaseo/plugin/client"; +import { useIsCompactFormFactor } from "@/constants/layout"; +import { useToast } from "@/contexts/toast-api-context"; +import { useHosts } from "@/runtime/host-runtime"; +import type { Theme } from "@/styles/theme"; +import { createPluginClientStateSource } from "./client-state/source"; +import { resolvePluginPlatform } from "./platform"; +import type { PluginEnvironment } from "./popover"; +import { SurfaceErrorBoundary } from "./surface-error-boundary"; +import { toPluginTheme } from "./theme"; +import type { InstalledPlugin } from "./types"; + +/** `withUnistyles` mapping that hands a host the plugin theme. */ +export const pluginThemeMapping = (theme: Theme) => ({ theme: toPluginTheme(theme) }); + +function renderNothing() { + return null; +} + +/** What a plugin's items on a host surface (composer, New workspace) share: environment and props. */ +export function usePluginItemHost( + plugin: InstalledPlugin, + theme: PluginHostProps["theme"], +): { environment: PluginEnvironment; props: PluginHostProps } { + const toast = useToast(); + const compact = useIsCompactFormFactor(); + const hosts = useHosts(); + const hostLabel = + hosts.find((host) => host.serverId === plugin.serverId)?.label ?? plugin.serverId; + const environment = useMemo( + () => ({ + installation: plugin, + toast, + state: createPluginClientStateSource(plugin.serverId), + }), + [plugin, toast], + ); + const props = useMemo( + () => ({ + theme, + host: { id: plugin.serverId, label: hostLabel }, + layout: { compact, platform: resolvePluginPlatform() }, + }), + [compact, hostLabel, plugin.serverId, theme], + ); + return { environment, props }; +} + +/** Mounts each item behind its own boundary; a throwing item draws nothing. */ +export function PluginItemList({ + plugin, + items, + props, +}: { + plugin: InstalledPlugin; + items: readonly { id: string; Component: ComponentType }[]; + props: PluginHostProps; +}) { + return ( + <> + {items.map(({ id, Component }) => ( + + + + ))} + + ); +} diff --git a/packages/app/src/plugins/new-workspace-items/index.tsx b/packages/app/src/plugins/new-workspace-items/index.tsx new file mode 100644 index 0000000000..3522fee987 --- /dev/null +++ b/packages/app/src/plugins/new-workspace-items/index.tsx @@ -0,0 +1,101 @@ +import { useMemo } from "react"; +import type { PluginHostProps } from "@getpaseo/plugin/client"; +import { PluginNewWorkspaceProvider } from "@getpaseo/plugin/client/host"; +import { withUnistyles } from "react-native-unistyles"; +import { + ComposerControlLockProvider, + ComposerControlSurfaceProvider, +} from "@/composer/agent-controls/composer-control"; +import type { PickerItem } from "@/screens/new-workspace-picker-item"; +import { + useNewWorkspaceSetupState, + type NewWorkspaceSetup, +} from "@/screens/new-workspace/setup-model"; +import { PluginItemList, pluginThemeMapping, usePluginItemHost } from "../item-host"; +import { PluginEnvironmentProvider } from "../popover"; +import { useInstalledPlugins } from "../registry"; +import type { InstalledPlugin } from "../types"; +import { toPluginNewWorkspace } from "./model"; + +/** What the screen derives and the items read; the rest is in the setup model. */ +export interface NewWorkspaceItemsScreen { + project: { id: string; name: string } | null; + isolation: "local" | "worktree"; + baseItem: PickerItem | null; + locked: boolean; +} + +function useServerPlugins(serverId: string): InstalledPlugin[] { + const installed = useInstalledPlugins(); + return useMemo( + () => + installed.filter( + (plugin) => plugin.serverId === serverId && plugin.newWorkspaceItems.length > 0, + ), + [installed, serverId], + ); +} + +/** + * The selected host's plugin items on the New workspace screen, drawn as setup fields. They read + * the screen's choices and command them through the setup model. + */ +export function PluginNewWorkspaceItems({ + serverId, + screen, + setup, +}: { + serverId: string; + screen: NewWorkspaceItemsScreen; + setup: NewWorkspaceSetup; +}) { + const plugins = useServerPlugins(serverId); + return ( + + + {plugins.map((plugin) => ( + + ))} + + + ); +} + +function PluginNewWorkspaceItemsHost({ + plugin, + theme, + screen, + setup, +}: { + plugin: InstalledPlugin; + theme: PluginHostProps["theme"]; + screen: NewWorkspaceItemsScreen; + setup: NewWorkspaceSetup; +}) { + const { environment, props } = usePluginItemHost(plugin, theme); + const { branch, metadata } = useNewWorkspaceSetupState(setup); + const newWorkspace = useMemo( + () => + toPluginNewWorkspace({ + host: props.host, + view: { ...screen, branch, metadata }, + commands: setup.commands, + }), + [branch, metadata, props.host, screen, setup.commands], + ); + return ( + + + + + + ); +} + +const ThemedPluginNewWorkspaceItems = withUnistyles(PluginNewWorkspaceItemsHost); diff --git a/packages/app/src/plugins/new-workspace-items/model.ts b/packages/app/src/plugins/new-workspace-items/model.ts new file mode 100644 index 0000000000..ce8cba4c38 --- /dev/null +++ b/packages/app/src/plugins/new-workspace-items/model.ts @@ -0,0 +1,40 @@ +import type { JsonValue } from "@getpaseo/protocol/agent-types"; +import type { PluginHostProps, PluginNewWorkspace } from "@getpaseo/plugin/client"; +import { branchNameFromRef, type PickerItem } from "@/screens/new-workspace-picker-item"; +import type { SetupCommands } from "@/screens/new-workspace/setup-model"; +import { cloneAndFreeze } from "../freeze"; + +/** What the New workspace screen shows at render; the plugin reads it, never writes it. */ +export interface NewWorkspaceView { + project: { id: string; name: string } | null; + /** What the screen will create. */ + isolation: "local" | "worktree"; + baseItem: PickerItem | null; + branch: string | null; + metadata: Readonly>; + locked: boolean; +} + +function toBaseRef(item: PickerItem | null): PluginNewWorkspace["baseRef"] { + if (!item) return null; + return item.kind === "branch" + ? { type: "branch", name: branchNameFromRef(item.refName) } + : { type: "change-request", number: item.item.number }; +} + +export function toPluginNewWorkspace(input: { + host: PluginHostProps["host"]; + view: NewWorkspaceView; + commands: SetupCommands; +}): PluginNewWorkspace { + const { host, view, commands } = input; + return { + host: { id: host.id, label: host.label }, + project: cloneAndFreeze(view.project), + isolation: view.isolation, + baseRef: toBaseRef(view.baseItem), + branch: view.branch, + metadata: cloneAndFreeze(view.metadata), + ...commands, + }; +} diff --git a/packages/app/src/plugins/react-native/composer-controls.browser.test.tsx b/packages/app/src/plugins/react-native/composer-controls.browser.test.tsx new file mode 100644 index 0000000000..be894186c5 --- /dev/null +++ b/packages/app/src/plugins/react-native/composer-controls.browser.test.tsx @@ -0,0 +1,142 @@ +import React from "react"; +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import type { ComboboxItem } from "@getpaseo/plugin/client/ui"; +import type { ToastApi } from "@/components/toast-host"; +import { ComposerControlSurfaceProvider } from "@/composer/agent-controls/composer-control"; +import { ToastApiProvider } from "@/contexts/toast-api-context"; +import { i18n } from "@/i18n/i18next"; +import { Combobox } from "./composer-controls"; + +beforeEach(async () => { + vi.stubGlobal("React", React); + await i18n.changeLanguage("en"); +}); +afterEach(cleanup); + +interface Issue extends ComboboxItem { + branch: string; +} + +const ONE: Issue = { id: "1", label: "Slow sidebar", branch: "one" }; +const TWO: Issue = { id: "2", label: "Crash on resume", branch: "two" }; + +interface Search { + query: string; + resolve(items: Issue[]): void; + reject(error: Error): void; +} + +/** A search the test settles by hand, so it decides which one finishes first. */ +function controlledSearch() { + const searches: Search[] = []; + const search = ({ query }: { query: string }) => + new Promise((resolve, reject) => { + searches.push({ query, resolve, reject }); + }); + const forQuery = (query: string) => { + const found = searches.find((candidate) => candidate.query === query); + if (!found) throw new Error(`No search for "${query}" yet`); + return found; + }; + return { search, forQuery, queries: () => searches.map((candidate) => candidate.query) }; +} + +const toast = { error: vi.fn() } as unknown as ToastApi; +const ignoreSelect = () => undefined; + +function Harness({ + search, + value, + onSelect = ignoreSelect, +}: { + search: (event: { query: string }) => Promise; + value: ComboboxItem | null; + onSelect?: (event: { item: Issue }) => void; +}) { + const [queryClient] = React.useState(() => new QueryClient()); + return ( + + + + + + + + ); +} + +function renderCombobox(input: { + search: (event: { query: string }) => Promise; + value?: ComboboxItem | null; + onSelect?: (event: { item: Issue }) => void; +}) { + render(); + fireEvent.click(screen.getByRole("button", { name: "Issue" })); +} + +describe("plugin Combobox", () => { + it("searches when the list opens, shows the results, and hands the picked item back", async () => { + const controlled = controlledSearch(); + const onSelect = vi.fn(); + renderCombobox({ search: controlled.search, onSelect }); + + await waitFor(() => expect(controlled.queries()).toEqual([""])); + expect(screen.getByText("Searching…")).toBeTruthy(); + controlled.forQuery("").resolve([ONE, TWO]); + + fireEvent.click(await screen.findByText("Crash on resume")); + expect(onSelect).toHaveBeenCalledWith({ item: TWO }); + }); + + it("shows the error and not stale results when the search fails", async () => { + const controlled = controlledSearch(); + renderCombobox({ search: controlled.search }); + + await waitFor(() => expect(controlled.queries()).toEqual([""])); + controlled.forQuery("").reject(new Error("tracker is down")); + + expect(await screen.findByText("Search failed: tracker is down")).toBeTruthy(); + }); + + it("keeps the previous results while a newer search runs and ignores a superseded one", async () => { + const controlled = controlledSearch(); + renderCombobox({ search: controlled.search }); + await waitFor(() => expect(controlled.queries()).toEqual([""])); + controlled.forQuery("").resolve([ONE, TWO]); + await screen.findByText("Slow sidebar"); + + const input = screen.getByRole("textbox"); + fireEvent.change(input, { target: { value: "c" } }); + await waitFor(() => expect(controlled.queries()).toEqual(["", "c"])); + expect(screen.getByText("Slow sidebar")).toBeTruthy(); + + fireEvent.change(input, { target: { value: "cr" } }); + await waitFor(() => expect(controlled.queries()).toEqual(["", "c", "cr"])); + controlled.forQuery("cr").resolve([TWO]); + await waitFor(() => expect(screen.queryByText("Slow sidebar")).toBeNull()); + controlled.forQuery("c").resolve([ONE]); + + await new Promise((resolve) => setTimeout(resolve, 50)); + expect(screen.getByText("Crash on resume")).toBeTruthy(); + expect(screen.queryByText("Slow sidebar")).toBeNull(); + }); + + it("shows a chosen value that the search no longer returns", async () => { + const controlled = controlledSearch(); + renderCombobox({ search: controlled.search, value: { id: "9", label: "PAS-9 Old issue" } }); + + expect(screen.getByRole("button", { name: "Issue" }).textContent).toContain("PAS-9 Old issue"); + await waitFor(() => expect(controlled.queries()).toEqual([""])); + controlled.forQuery("").resolve([ONE]); + await screen.findByText("Slow sidebar"); + expect(screen.getByRole("button", { name: "Issue" }).textContent).toContain("PAS-9 Old issue"); + }); +}); diff --git a/packages/app/src/plugins/react-native/composer-controls.tsx b/packages/app/src/plugins/react-native/composer-controls.tsx index eb4d05a09b..4a6688444d 100644 --- a/packages/app/src/plugins/react-native/composer-controls.tsx +++ b/packages/app/src/plugins/react-native/composer-controls.tsx @@ -1,11 +1,21 @@ -import type { ActionProps, SelectProps, ToggleProps } from "@getpaseo/plugin/client/ui"; -import { useMemo, useState } from "react"; +import type { + ActionProps, + ComboboxItem, + ComboboxProps, + SelectProps, + ToggleProps, +} from "@getpaseo/plugin/client/ui"; +import { useEffect, useId, useMemo, useState } from "react"; +import { useTranslation } from "react-i18next"; import { ComposerControl, + useComposerControlLocked, useComposerControlSurface, type ComposerControlItem, } from "@/composer/agent-controls/composer-control"; import { useComposerLocked } from "@/composer/session"; +import { useFetchQuery } from "@/data/query"; +import { toErrorMessage } from "@/utils/error-messages"; import { parsePluginIcon, pluginIconComponent } from "../icons"; /** Icons resolve at render, so an invalid one throws to the item's boundary. */ @@ -13,24 +23,35 @@ function usePluginControlIcon(icon: ToggleProps["icon"]) { return useMemo(() => pluginIconComponent(parsePluginIcon("Composer control", icon)), [icon]); } -/** Draws one plugin control where its composer item sits: inline, or as a row in the sheet. */ +/** Draws one plugin control where its item sits: inline, a row in the sheet, or a field. */ function PluginComposerControl({ item, disabled, + onOpenChange, }: { item: ComposerControlItem; disabled: boolean | undefined; + onOpenChange?: (open: boolean) => void; }) { const surface = useComposerControlSurface(); - const locked = useComposerLocked(); + const composerLocked = useComposerLocked(); + const fieldLocked = useComposerControlLocked(); + const locked = composerLocked || fieldLocked; const [open, setOpen] = useState(false); + const handleOpenChange = useMemo( + () => (next: boolean) => { + setOpen(next); + onOpenChange?.(next); + }, + [onOpenChange], + ); return ( ); } @@ -85,3 +106,82 @@ export function Action({ title, icon, disabled, onPress }: ActionProps) { ); return ; } + +const SEARCH_DEBOUNCE_MS = 200; +const NO_RESULTS: readonly never[] = []; + +/** The query settles after the user stops typing; an empty query applies at once. */ +function useDebounced(query: string): string { + const [settled, setSettled] = useState(query); + useEffect(() => { + if (query === "") return setSettled(""); + const timer = setTimeout(() => setSettled(query), SEARCH_DEBOUNCE_MS); + return () => clearTimeout(timer); + }, [query]); + return settled; +} + +/** + * Searches while the list is open. The search runs once per settled query, keeps the previous + * results on screen while the next one loads, and drops a search a newer one replaced. + */ +export function Combobox({ + title, + icon, + disabled, + value, + search, + onSelect, +}: ComboboxProps) { + const { t } = useTranslation(); + const Icon = usePluginControlIcon(icon); + const instanceId = useId(); + const [open, setOpen] = useState(false); + const [query, setQuery] = useState(""); + const settled = useDebounced(query); + const results = useFetchQuery({ + queryKey: ["plugin-combobox", instanceId, settled], + queryFn: () => search({ query: settled }), + dataShape: "list", + staleTimeMs: 0, + enabled: open, + gcTime: 0, + retry: false, + }); + const items: readonly Item[] = results.data ?? NO_RESULTS; + const item = useMemo(() => { + const choices = items.map(({ id, label, description }) => ({ value: id, label, description })); + return { + id: "plugin-combobox", + type: "select", + title, + icon: Icon, + value: value?.id ?? null, + valueLabel: value?.label, + choices, + onChange: (id) => { + const picked = items.find((candidate) => candidate.id === id); + return picked ? onSelect({ item: picked }) : undefined; + }, + searchable: true, + remoteSearch: true, + onSearchQueryChange: setQuery, + emptyText: comboboxEmptyText({ t, results, query, settled }), + showCaret: true, + }; + }, [Icon, items, onSelect, query, results, settled, t, title, value]); + return ; +} + +function comboboxEmptyText(input: { + t: (key: string, options?: Record) => string; + results: { isError: boolean; isFetching: boolean; error: unknown }; + query: string; + settled: string; +}): string { + const { t, results, query, settled } = input; + if (results.isError) + return t("pluginCombobox.failed", { message: toErrorMessage(results.error) }); + if (results.isFetching || query !== settled) return t("pluginCombobox.searching"); + return t("pluginCombobox.empty"); +} diff --git a/packages/app/src/plugins/react-native/ui.ts b/packages/app/src/plugins/react-native/ui.ts index 01d008574d..8b7d17216d 100644 --- a/packages/app/src/plugins/react-native/ui.ts +++ b/packages/app/src/plugins/react-native/ui.ts @@ -20,7 +20,7 @@ export { FilePanelLoading as Loading } from "@/file-panels/loading"; export { SettingsGroup } from "@/components/settings"; export { Icon } from "../icons"; -export { Action, Select, Toggle } from "./composer-controls"; +export { Action, Combobox, Select, Toggle } from "./composer-controls"; export { Modal } from "./modal"; export { ScrollView, FlatList } from "./scroll-view"; export { TextInput } from "./text-input"; diff --git a/packages/app/src/plugins/registry.ts b/packages/app/src/plugins/registry.ts index ce449d205b..f82ac14702 100644 --- a/packages/app/src/plugins/registry.ts +++ b/packages/app/src/plugins/registry.ts @@ -107,6 +107,7 @@ export class PluginRegistry { legacySidebarItems: [], filePanels: [], composerItems: [], + newWorkspaceItems: [], workspacePanels: [], commandCenterItems: [], clientSlashCommands: [], diff --git a/packages/app/src/plugins/sidebar-groups.test.ts b/packages/app/src/plugins/sidebar-groups.test.ts index fc0dfd7854..3994c0f862 100644 --- a/packages/app/src/plugins/sidebar-groups.test.ts +++ b/packages/app/src/plugins/sidebar-groups.test.ts @@ -35,6 +35,7 @@ function installed( legacySidebarItems, filePanels: [], composerItems: [], + newWorkspaceItems: [], workspacePanels: [], commandCenterItems: [], clientSlashCommands: [], diff --git a/packages/app/src/plugins/surface-contribution.test.ts b/packages/app/src/plugins/surface-contribution.test.ts index dd44e940d5..f3f9298380 100644 --- a/packages/app/src/plugins/surface-contribution.test.ts +++ b/packages/app/src/plugins/surface-contribution.test.ts @@ -37,6 +37,7 @@ function installation( })), filePanels: [], composerItems: [], + newWorkspaceItems: [], workspacePanels: [], commandCenterItems: [], clientSlashCommands: [], diff --git a/packages/app/src/plugins/theme.test.ts b/packages/app/src/plugins/theme.test.ts index 83e7b2dc1f..07887bfc4d 100644 --- a/packages/app/src/plugins/theme.test.ts +++ b/packages/app/src/plugins/theme.test.ts @@ -62,6 +62,7 @@ function installed(serverId: string, themes: PluginThemeContribution[]): Install legacySidebarItems: [], filePanels: [], composerItems: [], + newWorkspaceItems: [], workspacePanels: [], commandCenterItems: [], clientSlashCommands: [], diff --git a/packages/app/src/plugins/timeline/model.test.ts b/packages/app/src/plugins/timeline/model.test.ts index 33297a2d9a..97a27bad19 100644 --- a/packages/app/src/plugins/timeline/model.test.ts +++ b/packages/app/src/plugins/timeline/model.test.ts @@ -25,6 +25,7 @@ function plugin(input: { legacySidebarItems: [], filePanels: [], composerItems: [], + newWorkspaceItems: [], workspacePanels: [], commandCenterItems: [], clientSlashCommands: [], diff --git a/packages/app/src/plugins/types.ts b/packages/app/src/plugins/types.ts index 60b8aeb696..a34ab0f9e9 100644 --- a/packages/app/src/plugins/types.ts +++ b/packages/app/src/plugins/types.ts @@ -12,6 +12,7 @@ import type { PluginCommandCenterItemContribution as SDKPluginCommandCenterItemContribution, PluginClientSlashCommandContribution as SDKPluginClientSlashCommandContribution, PluginComposerItemContribution, + PluginNewWorkspaceItemContribution, PluginComposerPillContribution as SDKPluginComposerPillContribution, PluginSidebarContribution as SDKPluginSidebarContribution, PluginSidebarItemContribution as SDKPluginSidebarItemContribution, @@ -55,6 +56,7 @@ export interface EvaluatedPlugin { legacySidebarItems: PluginSidebarContribution[]; filePanels: PluginFilePanelContribution[]; composerItems: PluginComposerItemContribution[]; + newWorkspaceItems: PluginNewWorkspaceItemContribution[]; workspacePanels: EvaluatedPluginWorkspacePanelContribution[]; commandCenterItems: PluginCommandCenterItemContribution[]; clientSlashCommands: PluginClientSlashCommandContribution[]; @@ -85,6 +87,7 @@ export type { PluginCommandCenterItemContribution, PluginClientSlashCommandContribution, PluginComposerItemContribution, + PluginNewWorkspaceItemContribution, PluginComposerPillContribution, PluginSidebarContribution, PluginSidebarItemContribution, diff --git a/packages/app/src/plugins/workspace-panels/resolution.test.ts b/packages/app/src/plugins/workspace-panels/resolution.test.ts index 3dffea5558..b75880b543 100644 --- a/packages/app/src/plugins/workspace-panels/resolution.test.ts +++ b/packages/app/src/plugins/workspace-panels/resolution.test.ts @@ -22,6 +22,7 @@ function installed(): InstalledPlugin { legacySidebarItems: [], filePanels: [], composerItems: [], + newWorkspaceItems: [], workspacePanels: [ { id: "details", diff --git a/packages/app/src/screens/new-workspace-picker-item.ts b/packages/app/src/screens/new-workspace-picker-item.ts index d02c7a0bf2..be35e13309 100644 --- a/packages/app/src/screens/new-workspace-picker-item.ts +++ b/packages/app/src/screens/new-workspace-picker-item.ts @@ -132,7 +132,7 @@ export interface BaseRefCheckoutStatus { // Display only. The exact ref is what every request carries; this is just how a ref reads in // a row label, so "refs/remotes/origin/other-name" shows as "other-name". -function branchNameFromRef(refName: string): string { +export function branchNameFromRef(refName: string): string { if (refName.startsWith("refs/heads/")) return refName.slice("refs/heads/".length); if (refName.startsWith(REMOTE_TRACKING_PREFIX)) { const remainder = refName.slice(REMOTE_TRACKING_PREFIX.length); diff --git a/packages/app/src/screens/new-workspace-screen.tsx b/packages/app/src/screens/new-workspace-screen.tsx index fd03037fa1..f2f50ad4e4 100644 --- a/packages/app/src/screens/new-workspace-screen.tsx +++ b/packages/app/src/screens/new-workspace-screen.tsx @@ -5,7 +5,7 @@ import type { import type { AgentSnapshotPayload, CreationSnapshot } from "@getpaseo/protocol/messages"; import { encodeImages } from "@/utils/encode-images"; import { getHostRuntimeStore } from "@/runtime/host-runtime"; -import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react"; +import { useCallback, useEffect, useMemo, useRef, useState } from "react"; import type { ReactNode } from "react"; import { useTranslation } from "react-i18next"; import { router } from "expo-router"; @@ -79,7 +79,7 @@ import type { MessagePayload } from "@/composer/types"; import type { UserComposerAttachment } from "@/attachments/types"; import type { AgentAttachment, ForgeSearchItem } from "@getpaseo/protocol/messages"; import type { DaemonClient } from "@getpaseo/client/internal/daemon-client"; -import type { AgentProvider } from "@getpaseo/protocol/agent-types"; +import type { AgentProvider, JsonValue } from "@getpaseo/protocol/agent-types"; import type { WorkspaceDraftTabSetup, WorkspaceTabTarget } from "@/workspace-tabs/model"; import { isEmptyWorkspaceSubmission, runCreateEmptyWorkspace } from "./new-workspace-empty"; import { @@ -98,10 +98,18 @@ import { } from "./new-workspace-picker-item"; import { clearPickerPrAttachmentForTargetChange, - initialPickerSelectionState, - reducePickerSelection, syncPickerPrAttachment, } from "./new-workspace-picker-state"; +import { + PluginNewWorkspaceItems, + type NewWorkspaceItemsScreen, +} from "@/plugins/new-workspace-items"; +import { + createNewWorkspaceSetup, + useNewWorkspaceSetupState, + type NewWorkspaceSetup, + type SetupFacts, +} from "./new-workspace/setup-model"; import { resolveNewWorkspaceAutomaticServerId, resolveNewWorkspaceInitialServerId, @@ -195,13 +203,14 @@ interface WorkspaceIsolationState { function useWorkspaceIsolation(input: { supportsMultiplicity: boolean; worktreeSupport: "supported" | "unsupported" | "unknown"; + manualIsolation: "local" | "worktree" | null; + setManualIsolation: (value: "local" | "worktree") => void; }): WorkspaceIsolationState { - const { supportsMultiplicity, worktreeSupport } = input; + const { supportsMultiplicity, worktreeSupport, manualIsolation, setManualIsolation } = input; // The last isolation choice is remembered alongside the other New Workspace // form preferences (provider, model, mode). A manual in-screen pick overrides // the remembered default until the screen remounts. const { preferences, updatePreferences } = useFormPreferences(); - const [manualIsolation, setManualIsolation] = useState<"local" | "worktree" | null>(null); const isolation = manualIsolation ?? preferences.isolation ?? "local"; const canCreateWorktree = supportsMultiplicity && worktreeSupport !== "unsupported"; const isWorktree = isolation === "worktree" && canCreateWorktree; @@ -211,7 +220,7 @@ function useWorkspaceIsolation(input: { setManualIsolation(value); void updatePreferences({ isolation: value }); }, - [updatePreferences], + [setManualIsolation, updatePreferences], ); return { @@ -288,6 +297,10 @@ async function createMultiplicityWorkspace(input: { project: HostProjectListItem; sourceDirectory: string; checkoutRequest: PickerCheckoutRequest | undefined; + /** Names the new branch of a worktree cut from a branch. */ + branchName: string | null; + /** Stored on the created workspace. */ + metadata: Readonly>; withInitialAgent: boolean; agent?: CreateWorkspaceRequestOptions["agent"]; onEvent?: (snapshot: CreationSnapshot) => void; @@ -318,6 +331,9 @@ async function createMultiplicityWorkspace(input: { projectId, worktreeSlug: input.worktreeSlug, ...input.checkoutRequest, + ...(input.branchName && input.checkoutRequest?.action === "branch-off" + ? { branchName: input.branchName } + : {}), } : { kind: "directory", @@ -325,6 +341,7 @@ async function createMultiplicityWorkspace(input: { projectId, }, ...(firstAgentContext ? { firstAgentContext } : {}), + ...(Object.keys(input.metadata).length > 0 ? { metadata: { ...input.metadata } } : {}), }); if (payload.error || !payload.workspace) { throw new Error(payload.error ?? input.createFailedMessage); @@ -1002,22 +1019,24 @@ export function NewWorkspaceScreen({ }), }); const composerState = chatDraft.composerState; - const [pickerSelection, dispatchPickerSelection] = useReducer( - reducePickerSelection, - initialPickerSelectionState, - ); - const selectedItem = pickerSelection.selectedItem; + const [setup] = useState(createNewWorkspaceSetup); + const setupState = useNewWorkspaceSetupState(setup); + const dispatchPickerSelection = setup.dispatchPicker; + const selectedItem = setupState.pickerSelection.selectedItem; const handleForgeChangeRequestDetected = useCallback(() => { dispatchPickerSelection({ type: "pr-detected" }); - }, []); + }, [dispatchPickerSelection]); - const handleForgeChangeRequestAutoAttach = useCallback((item: ForgeSearchItem) => { - dispatchPickerSelection({ - type: "pr-added", - item: { kind: "github-pr", item }, - }); - }, []); + const handleForgeChangeRequestAutoAttach = useCallback( + (item: ForgeSearchItem) => { + dispatchPickerSelection({ + type: "pr-added", + item: { kind: "github-pr", item }, + }); + }, + [dispatchPickerSelection], + ); const withConnectedClient = useCallback(() => { const connectedClient = getHostRuntimeStore().getClient(selectedServerId); @@ -1044,6 +1063,8 @@ export function NewWorkspaceScreen({ useWorkspaceIsolation({ supportsMultiplicity: supportsWorkspaceMultiplicity, worktreeSupport, + manualIsolation: setupState.manualIsolation, + setManualIsolation: setup.setManualIsolation, }); const branchSuggestionsQuery = useQuery({ @@ -1117,9 +1138,21 @@ export function NewWorkspaceScreen({ chatDraft.setAttachments(nextAttachments); setPickerOpen(false); }, - [chatDraft], + [chatDraft, dispatchPickerSelection], ); + const pluginScreen = usePluginSetup({ + setup, + serverId: selectedServerId, + project: selectedProject, + baseItem, + isolation: effectiveIsolation, + canCreateWorktree, + locked: isPending, + chooseIsolation: setIsolation, + chooseBase: selectPickerItem, + }); + const handleSelectOption = useCallback( (id: string) => { const item = itemById.get(id); @@ -1140,7 +1173,7 @@ export function NewWorkspaceScreen({ chatDraft.setAttachments(nextAttachments); dispatchPickerSelection({ type: "target-changed" }); }, - [chatDraft], + [chatDraft, dispatchPickerSelection], ); const handleSelectProjectOption = useCallback( @@ -1260,6 +1293,8 @@ export function NewWorkspaceScreen({ project: selectedProject, sourceDirectory: selectedSourceDirectory, checkoutRequest, + branchName: setup.getSnapshot().branch, + metadata: setup.getSnapshot().metadata, withInitialAgent: input.withInitialAgent, prompt: input.prompt, attachments: input.attachments, @@ -1282,6 +1317,7 @@ export function NewWorkspaceScreen({ selectedProject, selectedServerId, selectedSourceDirectory, + setup, supportsWorkspaceMultiplicity, t, withConnectedClient, @@ -1462,6 +1498,9 @@ export function NewWorkspaceScreen({ const formStack = useNewWorkspaceForm({ isCompact, isPending, + pluginItems: ( + + ), project: { anchorRef: projectPickerAnchorRef, open: openProjectPicker, @@ -1603,6 +1642,45 @@ export function NewWorkspaceScreen({ } /** Terminal and chat launches edit in separate sessions; the screen follows the mounted one. */ +/** Reports the screen's current facts to the setup model, which plugin commands read when they run. */ +function usePluginSetup(input: { + setup: NewWorkspaceSetup; + serverId: string | null; + project: Parameters[0] | null; + baseItem: PickerItem | null; + isolation: NewWorkspaceItemsScreen["isolation"]; + canCreateWorktree: boolean; + locked: boolean; + chooseIsolation: SetupFacts["chooseIsolation"]; + chooseBase: SetupFacts["chooseBase"]; +}): NewWorkspaceItemsScreen { + const { setup, serverId, project, baseItem, isolation, locked } = input; + const { canCreateWorktree, chooseIsolation, chooseBase } = input; + const supportsMetadata = useHostFeature(serverId, "entityMetadata"); + const projectId = project && serverId ? getHostProjectId(project, serverId) : null; + const projectName = project?.projectName ?? null; + const screen = useMemo( + () => ({ + project: projectId && projectName ? { id: projectId, name: projectName } : null, + isolation, + baseItem, + locked, + }), + [baseItem, isolation, locked, projectId, projectName], + ); + useEffect(() => { + setup.report({ + locked: screen.locked, + project: screen.project, + canCreateWorktree, + supportsMetadata, + chooseIsolation, + chooseBase, + }); + }, [canCreateWorktree, chooseBase, chooseIsolation, screen, setup, supportsMetadata]); + return screen; +} + function useNewWorkspaceComposerEditing() { const terminal = useComposerEditingSession("terminal"); const chat = useComposerEditingSession("chat"); diff --git a/packages/app/src/screens/new-workspace/form/index.tsx b/packages/app/src/screens/new-workspace/form/index.tsx index c1cf1e2482..3b2040d389 100644 --- a/packages/app/src/screens/new-workspace/form/index.tsx +++ b/packages/app/src/screens/new-workspace/form/index.tsx @@ -33,6 +33,8 @@ interface PickerControl { export interface NewWorkspaceFormProps { isCompact: boolean; isPending: boolean; + /** Plugin fields, drawn after the base ref. */ + pluginItems: ReactNode; project: PickerControl & { options: ComboboxOption[]; projectByOptionId: Map; @@ -165,7 +167,7 @@ function useRefRenderOption(itemById: Map, isPending: boolea */ export function useNewWorkspaceForm(props: NewWorkspaceFormProps): ReactElement { const { t } = useTranslation(); - const { isCompact, isPending, project, host, isolation, base, launch } = props; + const { isCompact, isPending, pluginItems, project, host, isolation, base, launch } = props; const variant: FieldTriggerVariant = isCompact ? "field" : "badge"; const projectPicker = useProjectPicker(project, isPending); const isolationPicker = useIsolationPicker(isolation, isPending); @@ -337,6 +339,7 @@ export function useNewWorkspaceForm(props: NewWorkspaceFormProps): ReactElement {hostField} {isolationField} {baseField} + {pluginItems} {launchField} {/* Isolation and Base come and go with the project; their rows stay reserved so the stack keeps one height and nothing above the composer jumps. */} @@ -353,6 +356,7 @@ export function useNewWorkspaceForm(props: NewWorkspaceFormProps): ReactElement {hostField} {isolationField ? {isolationField} : null} {baseField ? {baseField} : null} + {pluginItems} {launchField} {pickers} diff --git a/packages/app/src/screens/new-workspace/setup-model.test.ts b/packages/app/src/screens/new-workspace/setup-model.test.ts new file mode 100644 index 0000000000..65bd44a4cc --- /dev/null +++ b/packages/app/src/screens/new-workspace/setup-model.test.ts @@ -0,0 +1,87 @@ +import { describe, expect, it } from "vitest"; +import type { PickerItem } from "../new-workspace-picker-item"; +import { createNewWorkspaceSetup, type SetupFacts } from "./setup-model"; + +function readyFacts(overrides: Partial = {}): SetupFacts { + return { + locked: false, + project: { id: "p1", name: "repo" }, + canCreateWorktree: true, + supportsMetadata: true, + chooseIsolation: () => {}, + chooseBase: () => {}, + ...overrides, + }; +} + +describe("New workspace setup commands", () => { + it("applies commands that run back to back without waiting for a render", async () => { + const setup = createNewWorkspaceSetup(); + setup.report(readyFacts()); + + void setup.commands.setBranch("pas-101"); + void setup.commands.setMetadata({ issue: "PAS-101", keep: true }); + await setup.commands.setMetadata({ keep: null }); + + expect(setup.getSnapshot().branch).toBe("pas-101"); + expect(setup.getSnapshot().metadata).toEqual({ issue: "PAS-101" }); + }); + + it("passes a base branch and an isolation choice to the picker's own handlers", async () => { + const setup = createNewWorkspaceSetup(); + const chosen: PickerItem[] = []; + const isolations: string[] = []; + setup.report( + readyFacts({ + chooseBase: (item) => chosen.push(item), + chooseIsolation: (isolation) => isolations.push(isolation), + }), + ); + + await setup.commands.setBaseRef({ type: "branch", name: " release " }); + await setup.commands.setIsolation("worktree"); + + expect(chosen).toMatchObject([{ kind: "branch", name: "release", refName: "release" }]); + expect(isolations).toEqual(["worktree"]); + }); + + it("rejects every command while the screen is locked, as the pickers do", async () => { + const setup = createNewWorkspaceSetup(); + setup.report(readyFacts({ locked: true })); + + const results = await Promise.allSettled([ + setup.commands.setBranch("x"), + setup.commands.setMetadata({ a: 1 }), + setup.commands.setIsolation("local"), + setup.commands.setBaseRef({ type: "branch", name: "main" }), + ]); + + expect(results.map((result) => result.status)).toEqual(Array(4).fill("rejected")); + expect(setup.getSnapshot().branch).toBeNull(); + expect(setup.getSnapshot().metadata).toEqual({}); + }); + + it("reads the facts when a command runs, so a project change after render is seen", async () => { + const setup = createNewWorkspaceSetup(); + setup.report(readyFacts()); + const pending = setup.commands.setBaseRef({ type: "branch", name: "main" }); + setup.report(readyFacts({ project: null })); + await pending; + await expect(setup.commands.setBaseRef({ type: "branch", name: "main" })).rejects.toThrow( + "Choose a project first.", + ); + }); + + it("rejects what the project or host cannot do", async () => { + const setup = createNewWorkspaceSetup(); + setup.report(readyFacts({ canCreateWorktree: false, supportsMetadata: false })); + + await expect(setup.commands.setIsolation("worktree")).rejects.toThrow( + "cannot create worktrees", + ); + await expect(setup.commands.setMetadata({ a: 1 })).rejects.toThrow("Update the host"); + await expect(setup.commands.setBranch(" ")).rejects.toThrow("needs a name"); + await setup.commands.setBranch(null); + expect(setup.getSnapshot().branch).toBeNull(); + }); +}); diff --git a/packages/app/src/screens/new-workspace/setup-model.ts b/packages/app/src/screens/new-workspace/setup-model.ts new file mode 100644 index 0000000000..4bc3c94c51 --- /dev/null +++ b/packages/app/src/screens/new-workspace/setup-model.ts @@ -0,0 +1,128 @@ +import { useSyncExternalStore } from "react"; +import type { JsonValue } from "@getpaseo/protocol/agent-types"; +import { applyMetadataPatch } from "@/composer/draft/metadata"; +import type { PickerItem } from "../new-workspace-picker-item"; +import { + initialPickerSelectionState, + reducePickerSelection, + type PickerSelectionEvent, + type PickerSelectionState, +} from "../new-workspace-picker-state"; + +type Isolation = "local" | "worktree"; + +/** What the user has chosen on the New workspace screen, apart from project and host. */ +interface SetupState { + pickerSelection: PickerSelectionState; + manualIsolation: Isolation | null; + /** The name for a new worktree branch; null lets Paseo pick one. */ + branch: string | null; + /** The created workspace's metadata. */ + metadata: Readonly>; +} + +/** + * What the screen derives from its hooks and reports on every render, so a command reads it at the + * moment it runs rather than from the render that built the command. + */ +export interface SetupFacts { + locked: boolean; + project: { id: string; name: string } | null; + canCreateWorktree: boolean; + supportsMetadata: boolean; + /** The picker's own handlers, so a command has the effects a pick has. */ + chooseIsolation(isolation: Isolation): void; + chooseBase(item: PickerItem): void; +} + +export interface SetupCommands { + setIsolation(isolation: Isolation): Promise; + setBaseRef(ref: { type: "branch"; name: string }): Promise; + setBranch(name: string | null): Promise; + setMetadata(patch: Record): Promise; +} + +export interface NewWorkspaceSetup { + subscribe(listener: () => void): () => void; + getSnapshot(): SetupState; + dispatchPicker(event: PickerSelectionEvent): void; + setManualIsolation(isolation: Isolation): void; + report(facts: SetupFacts): void; + commands: SetupCommands; +} + +const LOCKED_MESSAGE = "The New workspace screen is locked while the workspace is being created."; + +/** + * The New workspace screen's choices as one plain model. The pickers and the plugin commands + * write to it, so a command sees what an earlier command or pick left, and applies the same rules + * as the picker it stands in for. + */ +export function createNewWorkspaceSetup(): NewWorkspaceSetup { + let state: SetupState = { + pickerSelection: initialPickerSelectionState, + manualIsolation: null, + branch: null, + metadata: {}, + }; + let facts: SetupFacts | null = null; + const listeners = new Set<() => void>(); + const update = (patch: Partial) => { + state = { ...state, ...patch }; + for (const listener of listeners) listener(); + }; + const unlocked = (): SetupFacts => { + if (!facts) throw new Error("The New workspace screen is not ready."); + if (facts.locked) throw new Error(LOCKED_MESSAGE); + return facts; + }; + return { + subscribe(listener) { + listeners.add(listener); + return () => listeners.delete(listener); + }, + getSnapshot: () => state, + dispatchPicker: (event) => + update({ pickerSelection: reducePickerSelection(state.pickerSelection, event) }), + setManualIsolation: (manualIsolation) => update({ manualIsolation }), + report: (next) => { + facts = next; + }, + commands: { + async setIsolation(isolation) { + const current = unlocked(); + if (isolation === "worktree" && !current.canCreateWorktree) { + throw new Error("This project cannot create worktrees."); + } + current.chooseIsolation(isolation); + }, + async setBaseRef({ name }) { + const current = unlocked(); + const refName = name.trim(); + if (!current.project) throw new Error("Choose a project first."); + if (!refName) throw new Error("A base branch needs a name."); + current.chooseBase({ + kind: "branch", + name: refName, + refName, + accessibilityLabel: `${refName}, branch`, + }); + }, + async setBranch(name) { + unlocked(); + const branch = name === null ? null : name.trim(); + if (branch === "") throw new Error("A branch needs a name."); + update({ branch }); + }, + async setMetadata(patch) { + const current = unlocked(); + if (!current.supportsMetadata) throw new Error("Update the host to use metadata."); + update({ metadata: applyMetadataPatch(state.metadata, patch) }); + }, + }, + }; +} + +export function useNewWorkspaceSetupState(setup: NewWorkspaceSetup): SetupState { + return useSyncExternalStore(setup.subscribe, setup.getSnapshot, setup.getSnapshot); +} diff --git a/packages/plugin/src/boundaries.test.ts b/packages/plugin/src/boundaries.test.ts index 168acbaf27..b44e7f5309 100644 --- a/packages/plugin/src/boundaries.test.ts +++ b/packages/plugin/src/boundaries.test.ts @@ -250,6 +250,51 @@ describe("plugin composer SDK boundary", () => { }); }); +describe("plugin New workspace SDK boundary", () => { + it("lets a New workspace item read the setup and change it through typed commands and a Combobox", () => { + expect( + typeErrors(` + import { useNewWorkspace, type PluginClientContext } from "@getpaseo/plugin/client"; + import { Combobox } from "@getpaseo/plugin/client/ui"; + interface Issue { id: string; label: string; branch: string } + function Item() { + const newWorkspace = useNewWorkspace(); + const isolation: "local" | "worktree" = newWorkspace.isolation; + const branch: string | null = newWorkspace.branch; + const project: string | undefined = newWorkspace.project?.name; + const host: string = newWorkspace.host.label; + const base = newWorkspace.baseRef; + if (base?.type === "branch") { const name: string = base.name; } + // @ts-expect-error project is read-only + newWorkspace.project = null; + // @ts-expect-error host is read-only + newWorkspace.setHost("other"); + // @ts-expect-error metadata reads are not writable + newWorkspace.metadata.key = "x"; + newWorkspace.setIsolation("worktree").then(() => newWorkspace.setBaseRef({ type: "branch", name: "main" })); + newWorkspace.setBranch(null); + newWorkspace.setMetadata({ issue: "1", stale: null }); + // @ts-expect-error commands take JSON values + newWorkspace.setMetadata({ fn: () => {} }); + return ( + + title="Issue" + icon="CircleDot" + value={{ id: "1", label: "One" }} + search={async ({ query }: { query: string }) => [{ id: query, label: query, branch: "b" }]} + onSelect={({ item }) => newWorkspace.setBranch(item.branch)} + /> + ); + } + export default function contribute(client: PluginClientContext) { + client.addNewWorkspaceItem({ id: "item", Component: Item }); + return () => {}; + } + `), + ).toEqual([]); + }); +}); + describe("plugin agent tools SDK boundary", () => { it("lets a session hook attach typed tools without exposing their transport", () => { expect( diff --git a/packages/plugin/src/client/contracts.ts b/packages/plugin/src/client/contracts.ts index 9764ad204e..b85cbaddc0 100644 --- a/packages/plugin/src/client/contracts.ts +++ b/packages/plugin/src/client/contracts.ts @@ -5,6 +5,7 @@ import type { AgentTimelineItem, JsonValue } from "@getpaseo/protocol/agent-type import type { ZodType, input as ZodInput, output as ZodOutput } from "zod"; import type { PluginFile } from "./file.js"; import type { PluginComposerItemContribution } from "./composer.js"; +import type { PluginNewWorkspaceItemContribution } from "./new-workspace.js"; import type { PluginRpcContract } from "../rpc.js"; import type { PluginButtonRegistration, @@ -196,6 +197,7 @@ export interface PluginClientContext extends PluginCommandCapabilities, PluginCl ): PluginButtonRegistration; addAttachmentSource(contribution: PluginAttachmentSourceContribution): PluginCleanup; addComposerItem(contribution: PluginComposerItemContribution): PluginCleanup; + addNewWorkspaceItem(contribution: PluginNewWorkspaceItemContribution): PluginCleanup; addTheme(contribution: PluginThemeContribution): PluginCleanup; addFilePanel(contribution: PluginFilePanelContribution): PluginCleanup; addTimelineTransformer( diff --git a/packages/plugin/src/client/host.ts b/packages/plugin/src/client/host.ts index c09cb3b215..ea1f27c6d4 100644 --- a/packages/plugin/src/client/host.ts +++ b/packages/plugin/src/client/host.ts @@ -2,6 +2,7 @@ import type { PluginText } from "../text.js"; import { PluginAttachmentSearchPayloadSchema } from "../attachments.js"; export { PluginClientStateProvider, type PluginClientStateSource } from "./client-state.js"; export { PluginComposerProvider } from "./composer.js"; +export { PluginNewWorkspaceProvider } from "./new-workspace.js"; export { usePluginRuntimeContextBridge, type PluginRuntimeContextBridge, diff --git a/packages/plugin/src/client/index.ts b/packages/plugin/src/client/index.ts index e4de9dcaf4..49b7d3d485 100644 --- a/packages/plugin/src/client/index.ts +++ b/packages/plugin/src/client/index.ts @@ -78,6 +78,12 @@ export type { PluginComposerItemContribution, PluginComposerItemProps, } from "./composer.js"; +export { useNewWorkspace } from "./new-workspace.js"; +export type { + PluginNewWorkspace, + PluginNewWorkspaceItemContribution, + PluginNewWorkspaceItemProps, +} from "./new-workspace.js"; export { useRpc } from "./rpc-context.js"; import type { SettingsDefinition } from "../settings.js"; import type { SettingsState } from "./contracts.js"; diff --git a/packages/plugin/src/client/new-workspace.tsx b/packages/plugin/src/client/new-workspace.tsx new file mode 100644 index 0000000000..ca144fc4c5 --- /dev/null +++ b/packages/plugin/src/client/new-workspace.tsx @@ -0,0 +1,65 @@ +import { createContext, useContext, type ComponentType, type ReactNode } from "react"; +import type { JsonValue } from "@getpaseo/protocol/agent-types"; +import type { PluginHostProps } from "./contracts.js"; + +/** + * The New workspace setup the item sits in. `host` and `project` are the user's choices and are + * read-only. The commands change what the created workspace is built from, under the same rules as + * the screen's own pickers. + */ +export interface PluginNewWorkspace { + readonly host: { readonly id: string; readonly label: string }; + readonly project: { readonly id: string; readonly name: string } | null; + /** What the screen will create. A project that cannot make worktrees reads `"local"`. */ + readonly isolation: "local" | "worktree"; + /** What a new worktree starts from; `null` until the project's default is known. */ + readonly baseRef: + | { readonly type: "branch"; readonly name: string } + | { readonly type: "change-request"; readonly number: number } + | null; + /** + * The name of the branch a new worktree is created on; `null` lets Paseo pick one. It is kept + * while isolation is local or the base is a change request, and applies only to a worktree + * created from a branch. + */ + readonly branch: string | null; + /** The workspace's metadata, not the first agent's. */ + readonly metadata: Readonly>; + /** Rejects `"worktree"` for a project that cannot make worktrees. */ + setIsolation(isolation: "local" | "worktree"): Promise; + /** Starts the workspace from a branch. Rejects while no project is chosen. */ + setBaseRef(ref: { type: "branch"; name: string }): Promise; + setBranch(name: string | null): Promise; + /** Top-level keys replace; `null` removes the key. Rejects on a host without metadata support. */ + setMetadata(patch: Record): Promise; +} + +export interface PluginNewWorkspaceItemProps extends PluginHostProps {} + +export interface PluginNewWorkspaceItemContribution { + id: string; + Component: ComponentType; +} + +const PluginNewWorkspaceContext = createContext(null); + +export function PluginNewWorkspaceProvider({ + newWorkspace, + children, +}: { + newWorkspace: PluginNewWorkspace; + children: ReactNode; +}) { + return ( + + {children} + + ); +} + +/** The New workspace setup this item sits in. Call it from a component registered with `addNewWorkspaceItem`. */ +export function useNewWorkspace(): PluginNewWorkspace { + const newWorkspace = useContext(PluginNewWorkspaceContext); + if (!newWorkspace) throw new Error("useNewWorkspace must run inside a New workspace item"); + return newWorkspace; +} diff --git a/packages/plugin/src/client/ui.ts b/packages/plugin/src/client/ui.ts index 5130141332..30ad3e178a 100644 --- a/packages/plugin/src/client/ui.ts +++ b/packages/plugin/src/client/ui.ts @@ -210,10 +210,35 @@ export interface ActionPressEvent {} export interface ActionProps extends ComposerControlProps { onPress(event: ActionPressEvent): void | Promise; } +/** One result of a `Combobox` search. Extra fields ride along to `onSelect`. */ +export interface ComboboxItem { + id: string; + label: string; + description?: string; +} +export interface ComboboxSearchEvent { + /** Empty when the list opens. */ + query: string; +} +export interface ComboboxProps< + Item extends ComboboxItem = ComboboxItem, +> extends ComposerControlProps { + /** What the control shows. It need not be among the search results. */ + value: ComboboxItem | null; + /** + * Called when the list opens and again, debounced, as the user types. Paseo shows the loading + * and error states, keeps the previous results while a search runs, and ignores a search that a + * newer one replaced. + */ + search(event: ComboboxSearchEvent): Promise; + onSelect(event: { item: Item }): void | Promise; +} /** - * Composer controls. Render them from a composer item's `Component`. Paseo draws them inline when - * the composer has room and as rows in its overflow sheet when it does not. + * Paseo's controls. Render them from a composer item's or a New workspace item's `Component`. + * Paseo draws them where the item sits: inline when the composer has room and as rows in its + * overflow sheet when it does not, and as a field in the New workspace setup. */ export declare const Toggle: ComponentType; export declare function Select(props: SelectProps): ReactNode; export declare const Action: ComponentType; +export declare function Combobox(props: ComboboxProps): ReactNode; diff --git a/plugin-examples/new-workspace-issues/README.md b/plugin-examples/new-workspace-issues/README.md new file mode 100644 index 0000000000..3ad55f49ca --- /dev/null +++ b/plugin-examples/new-workspace-issues/README.md @@ -0,0 +1,17 @@ +# New workspace issues + +Install this directory as a plugin and open New workspace. An **Issue** field appears beside the +project, host, and branch pickers: a field on a phone, a badge on desktop. + +Choosing an issue: + +- Calls `newWorkspace.setBranch(issue.branch)`, so a worktree is created on that branch name. +- Calls `newWorkspace.setMetadata({ "new-workspace-issues.issue": issue.id })`, so the created + workspace carries the issue id. + +`Combobox` runs `search` when the list opens and again as the user types. Paseo shows the loading +and error states and drops results that a newer search replaced. The server handler in +[server/issues.ts](server/issues.ts) filters a fixed list; a real plugin would call its tracker. + +[client/issue-field.tsx](client/issue-field.tsx) is the field; [index.client.tsx](index.client.tsx) +registers it with `addNewWorkspaceItem`. diff --git a/plugin-examples/new-workspace-issues/client/issue-field.tsx b/plugin-examples/new-workspace-issues/client/issue-field.tsx new file mode 100644 index 0000000000..3786a1128f --- /dev/null +++ b/plugin-examples/new-workspace-issues/client/issue-field.tsx @@ -0,0 +1,31 @@ +import { useCallback, useMemo } from "react"; +import { useNewWorkspace, useRpc } from "@getpaseo/plugin/client"; +import { Combobox } from "@getpaseo/plugin/client/ui"; +import { searchIssuesRpc, type Issue } from "../shared/issues"; + +const ISSUE_KEY = "new-workspace-issues.issue"; + +/** Starts the workspace on the issue's branch and records which issue it is for. */ +export function IssueField() { + const newWorkspace = useNewWorkspace(); + const searchIssues = useRpc(searchIssuesRpc); + const issueId = newWorkspace.metadata[ISSUE_KEY]; + const value = useMemo( + () => (typeof issueId === "string" ? { id: issueId, label: issueId } : null), + [issueId], + ); + const search = useCallback( + async ({ query }: { query: string }) => (await searchIssues({ query })).issues, + [searchIssues], + ); + const select = useCallback( + async ({ item }: { item: Issue }) => { + await newWorkspace.setBranch(item.branch); + await newWorkspace.setMetadata({ [ISSUE_KEY]: item.id }); + }, + [newWorkspace], + ); + return ( + + ); +} diff --git a/plugin-examples/new-workspace-issues/index.client.tsx b/plugin-examples/new-workspace-issues/index.client.tsx new file mode 100644 index 0000000000..1d1132923e --- /dev/null +++ b/plugin-examples/new-workspace-issues/index.client.tsx @@ -0,0 +1,7 @@ +import type { PluginClientContext } from "@getpaseo/plugin/client"; +import { IssueField } from "./client/issue-field"; + +export default function contribute(client: PluginClientContext) { + client.addNewWorkspaceItem({ id: "issue", Component: IssueField }); + return () => {}; +} diff --git a/plugin-examples/new-workspace-issues/index.server.ts b/plugin-examples/new-workspace-issues/index.server.ts new file mode 100644 index 0000000000..544ab0081c --- /dev/null +++ b/plugin-examples/new-workspace-issues/index.server.ts @@ -0,0 +1,8 @@ +import type { PluginServerContext } from "@getpaseo/plugin/server"; +import { searchIssues } from "./server/issues"; +import { searchIssuesRpc } from "./shared/issues"; + +export default function contribute(server: PluginServerContext) { + server.handle(searchIssuesRpc, searchIssues); + return () => {}; +} diff --git a/plugin-examples/new-workspace-issues/paseo-plugin.json b/plugin-examples/new-workspace-issues/paseo-plugin.json new file mode 100644 index 0000000000..7a1bb2513d --- /dev/null +++ b/plugin-examples/new-workspace-issues/paseo-plugin.json @@ -0,0 +1,4 @@ +{ + "id": "new-workspace-issues-example", + "requirements": { "paseo": ">=0.8.0" } +} diff --git a/plugin-examples/new-workspace-issues/server/issues.ts b/plugin-examples/new-workspace-issues/server/issues.ts new file mode 100644 index 0000000000..a89ea0e3e3 --- /dev/null +++ b/plugin-examples/new-workspace-issues/server/issues.ts @@ -0,0 +1,26 @@ +import type { RpcInput } from "@getpaseo/plugin"; +import { searchIssuesRpc, type Issue } from "../shared/issues"; + +// A real plugin would ask its tracker. A fixed list keeps the example self-contained. +const ISSUES: Issue[] = [ + { + id: "PAS-101", + label: "PAS-101 Slow sidebar", + description: "Lists lag at 200 rows", + branch: "pas-101-slow-sidebar", + }, + { + id: "PAS-102", + label: "PAS-102 Crash on resume", + description: "Agent resume throws", + branch: "pas-102-crash-on-resume", + }, + { id: "PAS-103", label: "PAS-103 Dark theme contrast", branch: "pas-103-dark-theme-contrast" }, +]; + +export async function searchIssues({ query }: RpcInput) { + const needle = query.trim().toLowerCase(); + return { + issues: ISSUES.filter((issue) => issue.label.toLowerCase().includes(needle)), + }; +} diff --git a/plugin-examples/new-workspace-issues/shared/issues.ts b/plugin-examples/new-workspace-issues/shared/issues.ts new file mode 100644 index 0000000000..3f04c5afff --- /dev/null +++ b/plugin-examples/new-workspace-issues/shared/issues.ts @@ -0,0 +1,18 @@ +import { defineRpc } from "@getpaseo/plugin"; +import { z } from "zod"; + +export const IssueSchema = z.object({ + id: z.string(), + label: z.string(), + description: z.string().optional(), + /** The branch the issue's work goes on. */ + branch: z.string(), +}); + +export type Issue = z.infer; + +export const searchIssuesRpc = defineRpc({ + name: "issues.search", + input: z.object({ query: z.string() }), + output: z.object({ issues: z.array(IssueSchema) }), +}); diff --git a/public-docs/plugins/index.md b/public-docs/plugins/index.md index a9c7915a73..d4d12cc238 100644 --- a/public-docs/plugins/index.md +++ b/public-docs/plugins/index.md @@ -15,6 +15,7 @@ A plugin is a TypeScript project installed into one Paseo daemon. It can add [Command Center items](/docs/plugins/reference#command-center-items), [slash commands](/docs/plugins/reference#slash-commands), [composer items](/docs/plugins/reference#composer-items), +[New workspace items](/docs/plugins/reference#new-workspace-items), [composer pills](/docs/plugins/reference#composer-pills), [timeline items](/docs/plugins/reference#timeline-items), [themes](/docs/plugins/reference#contribute-a-theme), diff --git a/public-docs/plugins/index.zh-CN.md b/public-docs/plugins/index.zh-CN.md index 07a79d2922..d1367dac47 100644 --- a/public-docs/plugins/index.zh-CN.md +++ b/public-docs/plugins/index.zh-CN.md @@ -6,7 +6,7 @@ nav: 快速上手 # 插件快速上手 {#plugin-quickstart} -插件是安装到某个 Paseo daemon 中的 TypeScript 项目。它可以添加[界面和侧边栏项](/docs/plugins/reference#screens-and-sidebar-items)、[工作区面板](/docs/plugins/reference#workspace-panels)、[文件面板](/docs/plugins/reference#file-panels)、[Command Center 项](/docs/plugins/reference#command-center-items)、[斜杠命令](/docs/plugins/reference#slash-commands)、[Composer 项](/docs/plugins/reference#composer-items)、[Composer 标签](/docs/plugins/reference#composer-pills)、[时间线条目](/docs/plugins/reference#timeline-items)、[主题](/docs/plugins/reference#contribute-a-theme)、[附件来源](/docs/plugins/reference#add-a-composer-attachment-source)和 [daemon 端 RPC](/docs/plugins/reference#add-plugin-specific-backend-behavior)。它还可以[把编程 Agent 接入为 Provider](/docs/plugins/providers)。客户端贡献会在连接到该 daemon 的每个 Paseo 客户端上运行，包括移动端。 +插件是安装到某个 Paseo daemon 中的 TypeScript 项目。它可以添加[界面和侧边栏项](/docs/plugins/reference#screens-and-sidebar-items)、[工作区面板](/docs/plugins/reference#workspace-panels)、[文件面板](/docs/plugins/reference#file-panels)、[Command Center 项](/docs/plugins/reference#command-center-items)、[斜杠命令](/docs/plugins/reference#slash-commands)、[Composer 项](/docs/plugins/reference#composer-items)、[新建工作区项](/docs/plugins/reference#new-workspace-items)、[Composer 标签](/docs/plugins/reference#composer-pills)、[时间线条目](/docs/plugins/reference#timeline-items)、[主题](/docs/plugins/reference#contribute-a-theme)、[附件来源](/docs/plugins/reference#add-a-composer-attachment-source)和 [daemon 端 RPC](/docs/plugins/reference#add-plugin-specific-backend-behavior)。它还可以[把编程 Agent 接入为 Provider](/docs/plugins/providers)。客户端贡献会在连接到该 daemon 的每个 Paseo 客户端上运行，包括移动端。 浏览[已发布的插件](https://paseo.sh/plugins)，然后在你的 daemon 上安装一个： diff --git a/public-docs/plugins/reference.md b/public-docs/plugins/reference.md index 453f6899d1..4d21997054 100644 --- a/public-docs/plugins/reference.md +++ b/public-docs/plugins/reference.md @@ -1981,6 +1981,77 @@ control. The [composer controls example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/composer-controls) registers a `Select`, two `Toggle`s (one writes a provider option) and an `Action`. +## New workspace items + +`client.addNewWorkspaceItem({ id, Component })` puts a field on the New workspace screen, beside +the project, host and branch pickers. `useNewWorkspace()` reads and changes what the screen will +create, and `Combobox`, `Select`, `Toggle` and `Action` from `@getpaseo/plugin/client/ui` draw the +fields. On desktop an item is a badge in the setup row; on a phone it is a full-width field. + +```tsx +import { useNewWorkspace, useRpc, type PluginClientContext } from "@getpaseo/plugin/client"; +import { Combobox } from "@getpaseo/plugin/client/ui"; +import { searchIssuesRpc } from "../shared/issues"; + +function IssueField() { + const newWorkspace = useNewWorkspace(); + const searchIssues = useRpc(searchIssuesRpc); + const issueId = newWorkspace.metadata["issues.id"]; + return ( + (await searchIssues({ query })).issues} + onSelect={async ({ item }) => { + await newWorkspace.setBranch(item.branch); + await newWorkspace.setMetadata({ "issues.id": item.id }); + }} + /> + ); +} + +export default function contribute(client: PluginClientContext) { + client.addNewWorkspaceItem({ id: "issue", Component: IssueField }); + return () => {}; +} +``` + +`useNewWorkspace()` returns the setup the item sits in: + +| Field or command | Meaning | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `host`, `project` | The user's choices, `{ id, label }` and `{ id, name } \| null`. Read-only: an item cannot switch host or project. | +| `isolation`, `setIsolation` | `"local"` or `"worktree"`. A project that cannot make worktrees reads `"local"`, and `setIsolation("worktree")` rejects. | +| `baseRef`, `setBaseRef` | What a new worktree starts from: `{ type: "branch", name }`, `{ type: "change-request", number }`, or `null` until the default is known. `setBaseRef({ type: "branch", name })` rejects while no project is chosen. | +| `branch`, `setBranch` | The name of the branch a new worktree is created on. `null` lets Paseo pick one. It is kept while isolation is local or the base is a change request, and it applies only to a worktree created from a branch. | +| `metadata`, `setMetadata` | The created workspace's [metadata](/docs/plugins/hooks#metadata), not the first agent's. Top-level keys replace; `null` removes a key. Rejects on a host that does not support metadata with "Update the host to use metadata." | + +Commands follow the [composer item](#composer-items) rules: each one acts on the screen's state +when it runs, so `await newWorkspace.setBranch(name)` followed by `newWorkspace.setMetadata(patch)` +changes both, and its promise resolves once the change has taken effect. Payloads are JSON values. +`metadata` is a frozen copy. While the screen creates the workspace it is locked: your fields render +disabled and every command rejects with "The New workspace screen is locked while the workspace is +being created." A callback that returns a promise keeps the control disabled until it settles, and a +rejection reaches the user as an error toast. + +`Combobox` is a field with a searchable list whose results come from your code: + +| Prop | Meaning | +| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `value` | `{ id, label, description? } \| null`, what the field shows. It need not be among the search results, so it can show a choice made earlier. | +| `search` | `({ query }) => Promise`. Called with `""` when the list opens and again, debounced, as the user types. Each `Item` is `{ id, label, description? }` plus any fields you add. | +| `onSelect` | `({ item }) => void \| Promise`. `item` is the object `search` returned. | + +Paseo shows "Searching…" while a search runs, "Search failed" with the error message when it +rejects, and an empty state for no results. It keeps the previous results while a newer search runs +and ignores a search that a newer one replaced, so `search` needs no cancellation of its own. +`Combobox` takes the same `title`, `icon` and `disabled` as the other controls, and draws as a row +with a list in the composer's overflow sheet too. + +The [New workspace issues example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/new-workspace-issues) +searches a fixed issue list from a daemon handler and sets the branch and metadata from the choice. + ## Composer pills `client.addComposerPill({ id, workspaceId, agentId, button })` uses the same [button descriptor](#button-descriptor) diff --git a/public-docs/plugins/reference.zh-CN.md b/public-docs/plugins/reference.zh-CN.md index 9ed5eb1b8a..a5b2b0a29e 100644 --- a/public-docs/plugins/reference.zh-CN.md +++ b/public-docs/plugins/reference.zh-CN.md @@ -1665,6 +1665,63 @@ export default function contribute(client: PluginClientContext) { [Composer 控件示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/composer-controls)注册了一个 `Select`、两个 `Toggle`（其中一个写入 Provider 选项）和一个 `Action`。 +## 新建工作区项 {#new-workspace-items} + +`client.addNewWorkspaceItem({ id, Component })` 在新建工作区界面上放置一个字段，位于项目、主机和分支选择器旁边。`useNewWorkspace()` 读取并修改界面将要创建的内容，`@getpaseo/plugin/client/ui` 中的 `Combobox`、`Select`、`Toggle` 和 `Action` 负责绘制字段。桌面端的项是设置行中的徽章；手机上是整行宽度的字段。 + +```tsx +import { useNewWorkspace, useRpc, type PluginClientContext } from "@getpaseo/plugin/client"; +import { Combobox } from "@getpaseo/plugin/client/ui"; +import { searchIssuesRpc } from "../shared/issues"; + +function IssueField() { + const newWorkspace = useNewWorkspace(); + const searchIssues = useRpc(searchIssuesRpc); + const issueId = newWorkspace.metadata["issues.id"]; + return ( + (await searchIssues({ query })).issues} + onSelect={async ({ item }) => { + await newWorkspace.setBranch(item.branch); + await newWorkspace.setMetadata({ "issues.id": item.id }); + }} + /> + ); +} + +export default function contribute(client: PluginClientContext) { + client.addNewWorkspaceItem({ id: "issue", Component: IssueField }); + return () => {}; +} +``` + +`useNewWorkspace()` 返回该项所在的设置： + +| 字段或命令 | 含义 | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `host`、`project` | 用户的选择，分别是 `{ id, label }` 和 `{ id, name } \| null`。只读：项不能切换主机或项目。 | +| `isolation`、`setIsolation` | `"local"` 或 `"worktree"`。无法创建 worktree 的项目读取为 `"local"`，此时 `setIsolation("worktree")` 会被拒绝。 | +| `baseRef`、`setBaseRef` | 新 worktree 的起点：`{ type: "branch", name }`、`{ type: "change-request", number }`，默认值未知时为 `null`。未选择项目时，`setBaseRef({ type: "branch", name })` 会被拒绝。 | +| `branch`、`setBranch` | 新 worktree 所创建的分支名称。`null` 表示由 Paseo 选择名称。隔离为本地或起点为变更请求时会保留该值，它只对从分支创建的 worktree 生效。 | +| `metadata`、`setMetadata` | 所创建工作区的[元数据](/docs/plugins/hooks#metadata)，而不是第一个 Agent 的元数据。顶层键替换，`null` 删除该键。主机不支持元数据时以 “Update the host to use metadata.” 拒绝。 | + +命令遵循 [Composer 项](#composer-items)的规则：每个命令都按界面运行时的状态执行，所以 `await newWorkspace.setBranch(name)` 之后再调用 `newWorkspace.setMetadata(patch)` 会同时生效，命令的 Promise 在更改生效后完成。载荷是 JSON 值。`metadata` 是冻结的副本。界面创建工作区期间会被锁定：你的字段显示为禁用，所有命令都会以 "The New workspace screen is locked while the workspace is being created." 拒绝。返回 Promise 的回调在完成之前会让控件保持禁用，被拒绝时会以错误提示向用户显示。 + +`Combobox` 是带可搜索列表的字段，结果由你的代码提供： + +| 属性 | 含义 | +| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `value` | `{ id, label, description? } \| null`，字段显示的内容。它不必出现在搜索结果中，因此可以显示之前所做的选择。 | +| `search` | `({ query }) => Promise`。列表打开时以 `""` 调用，之后随用户输入防抖调用。每个 `Item` 是 `{ id, label, description? }` 加上你添加的字段。 | +| `onSelect` | `({ item }) => void \| Promise`。`item` 就是 `search` 返回的对象。 | + +搜索进行时 Paseo 显示 “Searching…”，搜索被拒绝时显示 “Search failed” 和错误信息，没有结果时显示空状态。新搜索进行期间会保留之前的结果，并忽略已被更新搜索取代的结果，所以 `search` 不需要自己处理取消。`Combobox` 接收与其他控件相同的 `title`、`icon` 和 `disabled`。 + +[新建工作区 Issue 示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/new-workspace-issues)通过守护进程处理器搜索一个固定的 Issue 列表，并根据所选项设置分支和元数据。 + ## Composer 胶囊 {#composer-pills} `client.addComposerPill({ id, workspaceId, agentId, button })` 使用同样的[按钮描述符](#button-descriptor)，