@tai42/studio-sdk 25.0.1 → 26.0.0

package/src/marketplace-install/mount-install.tsx

@@ -0,0 +1,290 @@
+/**
+ * The route-mounting install / update form: a base prefix per route-carrying item, a
+ * live preview of the resulting absolute paths, loud collision blocking, explicit
+ * acceptance of the routes served without authentication, and — on install — the
+ * preview's missing env collected in the same form. `MountInstallForm` renders it in
+ * place; `MountInstallDialog` renders it in a dialog.
+ */
+import type { MarketplaceInstallPreview, MarketplaceInstallResult } from '@tai42/api-client';
+import { type ReactNode, useRef } from 'react';
+
+import { Badge } from '../components/badge';
+import { Checkbox } from '../components/checkbox';
+import { Field } from '../components/field';
+import { FormDialog } from '../components/form-dialog';
+import { XCircleIcon } from '../components/icons';
+import { TextInput } from '../components/inputs';
+import { ErrorState, Skeleton } from '../components/primitives';
+import { EnvVarFields } from './env-var-fields';
+import { InstallShell, storeOffNote } from './install-shell';
+import type { RouteItem } from './route-items';
+import { useInstallAction } from './use-install-action';
+import { type MountInstallModel, useMountInstall } from './use-mount-install';
+
+export interface MountInstallDialogProps {
+  readonly refValue: string;
+  readonly version: string | null;
+  readonly verb: 'Install' | 'Update';
+  readonly routeItems: readonly RouteItem[];
+  /**
+   * On UPDATE, the installed row's stored `{item_name: base}` — the CURRENT mount each
+   * base input seeds from (declared default only for an item with no stored mount).
+   * Absent on INSTALL, where every input seeds from the declared default.
+   */
+  readonly storedMounts?: Record<string, string>;
+  /** The server's per-var secret-ness: a toggle for a `true` var is locked on. */
+  readonly requiredEnvSecret?: Record<string, boolean>;
+  /** Per-var "which item needs it" hint. */
+  readonly envHints?: Record<string, string>;
+  /** After a 2xx install or update. */
+  readonly onDone: (result: MarketplaceInstallResult) => void;
+  /** After a failed call, already rendered in place. */
+  readonly onFailed?: (error: unknown) => void;
+  /** The user closed or cancelled without a completed call. */
+  readonly onDismiss: () => void;
+}
+
+/** The resolved routes for one item, from the live preview. */
+function ItemRoutes({
+  item,
+  preview,
+}: {
+  readonly item: RouteItem;
+  readonly preview: MarketplaceInstallPreview | undefined;
+}): ReactNode {
+  if (preview === undefined) return <Skeleton height={48} />;
+  const resolved = preview.items.find((row) => row.item === item.name);
+  if (resolved === undefined) return null;
+  return (
+    <ul style={{ margin: 0, paddingLeft: 'var(--tai-space-4)' }}>
+      {resolved.routes.map((route) => (
+        <li key={`${route.path}/${route.methods.join(',')}`}>
+          <code className="tai-mono">{route.full_path}</code>{' '}
+          <span className="tai-muted">{route.methods.join(', ')}</span>{' '}
+          {route.public ? <Badge variant="warning">public</Badge> : null}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/**
+ * The loud collision block: each clashing route, its owner, and the remap remedy.
+ * `role="alert"` on the error ground, with its own headline — a collision is a
+ * refusal the operator resolves, not a malfunction, so it never wears the generic
+ * "something went wrong".
+ */
+function CollisionBlock({
+  collisions,
+}: {
+  readonly collisions: MarketplaceInstallPreview['collisions'];
+}): ReactNode {
+  return (
+    <div role="alert" className="tai-error-state tai-stack tai-stack-2">
+      <strong className="tai-error-state-title">
+        <XCircleIcon />
+        Route collision
+      </strong>
+      <p style={{ margin: 0 }}>
+        These routes already have an owner. Remap the base above until they no longer clash.
+      </p>
+      <ul style={{ margin: 0, paddingLeft: 'var(--tai-space-4)' }}>
+        {collisions.map((collision) => (
+          <li key={`${collision.item}/${collision.full_path}/${collision.methods.join(',')}`}>
+            <code className="tai-mono">{collision.full_path}</code>{' '}
+            <span className="tai-muted">{collision.methods.join(', ')}</span> — owned by{' '}
+            <strong>{collision.conflict_owner}</strong>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+/**
+ * The public-route acceptance block: it names every route that will answer WITHOUT
+ * authentication and gates submit on an explicit checkbox.
+ */
+function PublicAcceptance({
+  rows,
+  accepted,
+  onAccept,
+}: {
+  readonly rows: MarketplaceInstallPreview['new_public_routes'];
+  readonly accepted: boolean;
+  readonly onAccept: (checked: boolean) => void;
+}): ReactNode {
+  return (
+    <div role="alert" className="tai-warn-state tai-stack tai-stack-2">
+      <strong className="tai-status-warn">Public routes</strong>
+      <p style={{ margin: 0 }}>
+        These routes are served WITHOUT API-key authentication — anyone who can reach the server can
+        call them.
+      </p>
+      <ul style={{ margin: 0, paddingLeft: 'var(--tai-space-4)' }}>
+        {rows.map((row) => (
+          <li key={`${row.item}/${row.full_path}/${row.methods.join(',')}`}>
+            <code className="tai-mono">{row.full_path}</code>{' '}
+            <span className="tai-muted">{row.methods.join(', ')}</span>
+          </li>
+        ))}
+      </ul>
+      <Checkbox
+        checked={accepted}
+        onCheckedChange={onAccept}
+        label="I accept these routes are served without authentication"
+      />
+    </div>
+  );
+}
+
+/** The form body both frames render: the bases, the preview, and the env to collect. */
+function MountInstallFields({
+  model,
+  refValue,
+  version,
+  verb,
+  routeItems,
+  requiredEnvSecret,
+  envHints,
+}: {
+  readonly model: MountInstallModel;
+  readonly refValue: string;
+  readonly version: string | null;
+  readonly verb: 'Install' | 'Update';
+  readonly routeItems: readonly RouteItem[];
+  readonly requiredEnvSecret?: Record<string, boolean>;
+  readonly envHints?: Record<string, string>;
+}): ReactNode {
+  return (
+    <div className="tai-stack tai-stack-3">
+      <p style={{ margin: 0 }}>
+        {verb} {refValue}
+        {version !== null ? ` v${version}` : ''}? Its routes mount under the bases below. Remap a
+        base to move where a route answers.
+      </p>
+      {routeItems.map((item) => (
+        <div key={item.name} className="tai-stack tai-stack-2">
+          <Field label={`${item.name} base`}>
+            <TextInput
+              value={model.bases[item.name] ?? ''}
+              onChange={(event) => {
+                const next = event.currentTarget.value;
+                model.setBases((prev) => ({ ...prev, [item.name]: next }));
+              }}
+            />
+          </Field>
+          <ItemRoutes item={item} preview={model.preview} />
+        </div>
+      ))}
+      {model.previewIsError ? (
+        <ErrorState message="The install preview failed. Fix the error and edit a base to retry." />
+      ) : null}
+      {model.collisions.length > 0 ? <CollisionBlock collisions={model.collisions} /> : null}
+      {model.requiresAccept ? (
+        <PublicAcceptance
+          rows={model.publicRows}
+          accepted={model.accepted}
+          onAccept={model.setAccepted}
+        />
+      ) : null}
+      {model.envToCollect.length > 0 ? (
+        <EnvVarFields
+          requiredVars={model.envToCollect}
+          values={model.envValues}
+          secret={model.envSecretMap}
+          requiredSecret={requiredEnvSecret}
+          hints={envHints}
+          onChangeValue={(name, value) => {
+            model.setEnvValues((prev) => ({ ...prev, [name]: value }));
+          }}
+          onToggleSecret={(name, checked) => {
+            model.setEnvSecretOverride((prev) => ({ ...prev, [name]: checked }));
+          }}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+/** The mount form in place, with its own Cancel and submit buttons. */
+export function MountInstallForm(props: MountInstallDialogProps): ReactNode {
+  const { refValue, version, verb, routeItems, requiredEnvSecret, envHints } = props;
+  const model = useMountInstall(props);
+  const action = useInstallAction(refValue, verb);
+  const failure = action.state.status === 'failed' ? action.state.error : null;
+  return (
+    <InstallShell
+      layout="panel"
+      title={`${verb} plugin`}
+      submitLabel={verb}
+      pendingLabel={verb === 'Install' ? 'Installing' : 'Updating'}
+      isPending={action.state.status === 'pending'}
+      error={storeOffNote(failure) === undefined ? failure : null}
+      disabledNote={storeOffNote(failure)}
+      submitDisabled={model.blocked}
+      onSubmit={() => {
+        action.run(model.extras()).then(props.onDone, (error: unknown) => {
+          props.onFailed?.(error);
+        });
+      }}
+      onDismiss={props.onDismiss}
+    >
+      <MountInstallFields
+        model={model}
+        refValue={refValue}
+        version={version}
+        verb={verb}
+        routeItems={routeItems}
+        requiredEnvSecret={requiredEnvSecret}
+        envHints={envHints}
+      />
+    </InstallShell>
+  );
+}
+
+/**
+ * The mount form in a dialog. It previews the resolved routes on open and on every
+ * (debounced) base edit, blocks submit on a collision or an unaccepted public route,
+ * and closes only after a 2xx; a failure renders in the dialog and it stays open.
+ */
+export function MountInstallDialog(props: MountInstallDialogProps): ReactNode {
+  const { refValue, version, verb, routeItems, requiredEnvSecret, envHints } = props;
+  const model = useMountInstall(props);
+  const action = useInstallAction(refValue, verb);
+  // The dialog's own close after a 2xx is not a dismissal.
+  const doneRef = useRef(false);
+  const submit = async (): Promise<void> => {
+    let result: MarketplaceInstallResult;
+    try {
+      result = await action.run(model.extras());
+    } catch (error: unknown) {
+      props.onFailed?.(error);
+      throw error;
+    }
+    doneRef.current = true;
+    props.onDone(result);
+  };
+  return (
+    <FormDialog
+      title={`${verb} plugin`}
+      submitLabel={verb}
+      pendingLabel={verb === 'Install' ? 'Installing' : 'Updating'}
+      submitDisabled={model.blocked}
+      onSubmit={submit}
+      onClose={() => {
+        if (!doneRef.current) props.onDismiss();
+      }}
+    >
+      <MountInstallFields
+        model={model}
+        refValue={refValue}
+        version={version}
+        verb={verb}
+        routeItems={routeItems}
+        requiredEnvSecret={requiredEnvSecret}
+        envHints={envHints}
+      />
+    </FormDialog>
+  );
+}

package/src/marketplace-install/plugin-detail.ts

@@ -0,0 +1,60 @@
+/** Pure readings of a marketplace plugin's detail that the install forms seed from. */
+import type { MarketplaceDelivery, MarketplacePluginDetail } from '@tai42/api-client';
+
+/**
+ * How the listing's latest version is delivered, derived exactly the way the server
+ * derives it — from whether the spec names a package. The registry's plugin-detail
+ * body carries no `delivery` field (that is server-computed and rides the installed
+ * rows and the install preview), so the detail is read off the listing's `package`:
+ * `null` (a descriptor listing that names none) ⇒ `descriptor`, else `package`.
+ */
+export function deliveryOf(detail: MarketplacePluginDetail): MarketplaceDelivery {
+  return detail.package === null ? 'descriptor' : 'package';
+}
+
+/**
+ * The env picture a listing's items declare, folded across the detail: each
+ * required var's derived `secret`-ness and the item(s) that need it. This is a
+ * SUPPLEMENTARY fallback only — the registry's plugin-detail body carries no per-item
+ * required_env, so in production this is empty; the install PREVIEW is the authority.
+ */
+interface RequiredEnvEntry {
+  readonly secret: boolean;
+  readonly items: string[];
+}
+
+function requiredEnvIndex(detail: MarketplacePluginDetail): Map<string, RequiredEnvEntry> {
+  const index = new Map<string, RequiredEnvEntry>();
+  for (const item of detail.latest?.items ?? []) {
+    // The registry omits per-item required_env (undefined); only a fixture/preview
+    // that declares it drives these pre-dialog hints.
+    for (const req of item.required_env ?? []) {
+      const entry = index.get(req.name);
+      if (entry === undefined) {
+        index.set(req.name, { secret: req.secret, items: [item.name] });
+      } else {
+        index.set(req.name, {
+          secret: entry.secret || req.secret,
+          items: [...entry.items, item.name],
+        });
+      }
+    }
+  }
+  return index;
+}
+
+export interface RequiredEnvHints {
+  readonly requiredEnvSecret: Record<string, boolean>;
+  readonly requiredEnvHints: Record<string, string>;
+}
+
+/** The detail's declared env folded into the secret band and per-var hint the forms seed from. */
+export function requiredEnvFromDetail(detail: MarketplacePluginDetail): RequiredEnvHints {
+  const requiredEnvSecret: Record<string, boolean> = {};
+  const requiredEnvHints: Record<string, string> = {};
+  for (const [envName, entry] of requiredEnvIndex(detail)) {
+    requiredEnvSecret[envName] = entry.secret;
+    requiredEnvHints[envName] = entry.items.join(', ');
+  }
+  return { requiredEnvSecret, requiredEnvHints };
+}

package/src/marketplace-install/plugin-install.tsx

@@ -0,0 +1,221 @@
+/**
+ * The install of one marketplace plugin, in place (`PluginInstallPanel`) or in a
+ * dialog (`PluginInstallDialog`). A plugin with route-carrying items installs through
+ * the mount form, which also collects the preview's missing env; any other plugin
+ * previews once and either collects the env the preview names or shows a plain
+ * confirm.
+ */
+import type {
+  MarketplaceInstallBody,
+  MarketplaceInstallResult,
+  MarketplacePluginDetail,
+} from '@tai42/api-client';
+import { type ReactNode, useMemo, useState } from 'react';
+
+import { Skeleton } from '../components/primitives';
+import { EnvVarFields } from './env-var-fields';
+import { installEnvBands } from './install-env';
+import { collectEnv } from './install-mount';
+import { InstallFailure, type InstallLayout, InstallShell, storeOffNote } from './install-shell';
+import { MountInstallDialog, MountInstallForm } from './mount-install';
+import { deliveryOf, requiredEnvFromDetail } from './plugin-detail';
+import { routeItemsOf } from './route-items';
+import { useInstallAction } from './use-install-action';
+import { type InstallPreviewState, useInstallPreview } from './use-install-preview';
+
+export interface PluginInstallProps {
+  readonly refValue: string;
+  readonly version: string | null;
+  readonly detail: MarketplacePluginDetail;
+  /** After a 2xx install; the host invalidates its own caches and renders the report. */
+  readonly onInstalled: (result: MarketplaceInstallResult) => void;
+  /** After a failed install, already rendered in place; the host may record a store-off refusal. */
+  readonly onFailed?: (error: unknown) => void;
+  /** The user closed or cancelled without installing. */
+  readonly onDismiss: () => void;
+}
+
+/** The env-collecting body: one value per var the deployment does not already provide. */
+function EnvInstallFields({
+  refValue,
+  version,
+  missingVars,
+  values,
+  secretMap,
+  lockedSecret,
+  envHints,
+  onChangeValue,
+  onToggleSecret,
+}: {
+  readonly refValue: string;
+  readonly version: string | null;
+  readonly missingVars: readonly string[];
+  readonly values: Record<string, string>;
+  readonly secretMap: Record<string, boolean>;
+  readonly lockedSecret: Record<string, boolean>;
+  readonly envHints: Record<string, string>;
+  readonly onChangeValue: (name: string, value: string) => void;
+  readonly onToggleSecret: (name: string, checked: boolean) => void;
+}): ReactNode {
+  return (
+    <div className="tai-stack tai-stack-3">
+      <p style={{ margin: 0 }}>
+        Install {refValue}
+        {version !== null ? ` v${version}` : ''}?
+        {missingVars.length > 0
+          ? ' This plugin needs these values to install. Leave a field blank if the deployment already provides it.'
+          : ''}
+      </p>
+      {missingVars.length > 0 ? (
+        <EnvVarFields
+          requiredVars={missingVars}
+          values={values}
+          secret={secretMap}
+          requiredSecret={lockedSecret}
+          hints={envHints}
+          onChangeValue={onChangeValue}
+          onToggleSecret={onToggleSecret}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * The install of a plugin with no route-carrying item. Whether it needs install-time
+ * env is the install PREVIEW's call — the server authority — because the registry's
+ * plugin-detail body carries no per-item required_env. A preview naming required or
+ * missing env collects one value per missing var (a secret var's toggle is locked
+ * on, a free var starts off; a blank field is omitted, the deployment may still
+ * provide it). A clean no-env preview shows the plain confirm. The submit stays
+ * blocked while the preview loads or after it failed: the env picture is unverified.
+ */
+function NonRouteInstall({
+  layout,
+  refValue,
+  version,
+  detail,
+  onInstalled,
+  onFailed,
+  onDismiss,
+}: PluginInstallProps & { readonly layout: InstallLayout }): ReactNode {
+  const request = useMemo(() => ({ ref: refValue, version }), [refValue, version]);
+  const { state: previewState } = useInstallPreview(request);
+  const action = useInstallAction(refValue, 'Install');
+  const { requiredEnvSecret, requiredEnvHints } = requiredEnvFromDetail(detail);
+  const [values, setValues] = useState<Record<string, string>>({});
+  const [secretOverride, setSecretOverride] = useState<Record<string, boolean>>({});
+
+  const preview = previewState.status === 'ready' ? previewState.preview : null;
+  const needsEnv =
+    preview !== null && (preview.required_env.length > 0 || preview.missing_env.length > 0);
+  const missingVars = preview?.missing_env ?? [];
+  // The secret band merges the preview's per-var authority, the detail-derived
+  // fallback, and the operator override; a preview/detail-secret var is LOCKED on.
+  const { secretMap, lockedSecret } = installEnvBands(
+    missingVars,
+    preview?.required_env ?? [],
+    requiredEnvSecret,
+    secretOverride,
+  );
+
+  const failure = action.state.status === 'failed' ? action.state.error : null;
+  const submit = (): void => {
+    let body: Omit<MarketplaceInstallBody, 'ref'> = {};
+    if (needsEnv) {
+      const { env, secretKeys } = collectEnv(missingVars, values, secretMap);
+      // Every var pre-satisfied → a plain install body.
+      if (Object.keys(env).length > 0) body = { env, secret_keys: secretKeys };
+    }
+    action.run(body).then(onInstalled, (error: unknown) => {
+      onFailed?.(error);
+    });
+  };
+
+  return (
+    <InstallShell
+      layout={layout}
+      title="Install plugin"
+      submitLabel="Install"
+      pendingLabel="Installing"
+      isPending={action.state.status === 'pending'}
+      error={storeOffNote(failure) === undefined ? failure : null}
+      disabledNote={previewNote(previewState) ?? storeOffNote(failure)}
+      onSubmit={submit}
+      onDismiss={onDismiss}
+    >
+      {needsEnv ? (
+        <EnvInstallFields
+          refValue={refValue}
+          version={version}
+          missingVars={missingVars}
+          values={values}
+          secretMap={secretMap}
+          lockedSecret={lockedSecret}
+          envHints={requiredEnvHints}
+          onChangeValue={(name, value) => {
+            setValues((prev) => ({ ...prev, [name]: value }));
+          }}
+          onToggleSecret={(name, checked) => {
+            setSecretOverride((prev) => ({ ...prev, [name]: checked }));
+          }}
+        />
+      ) : (
+        <p style={{ margin: 0 }}>
+          Install {refValue}
+          {detail.latest !== null ? ` v${detail.latest.version}` : ''}?{' '}
+          {/* A descriptor plugin installs nothing but its manifest entry; a packaged
+              plugin is pip-installed. */}
+          {deliveryOf(detail) === 'descriptor'
+            ? 'The app will register this plugin and reload.'
+            : 'The app will pip-install the package and reload.'}
+        </p>
+      )}
+    </InstallShell>
+  );
+}
+
+/** What the preview puts in the failure slot: a skeleton while it loads, its failure after. */
+function previewNote(state: InstallPreviewState): ReactNode {
+  if (state.status === 'loading') return <Skeleton height={48} />;
+  if (state.status === 'failed') return <InstallFailure error={state.error} />;
+  return undefined;
+}
+
+function PluginInstall({
+  layout,
+  ...props
+}: PluginInstallProps & { readonly layout: InstallLayout }): ReactNode {
+  const { refValue, version, detail, onInstalled, onFailed, onDismiss } = props;
+  const routeItems = useMemo(() => routeItemsOf(detail.latest?.items ?? []), [detail]);
+  if (routeItems.length === 0) return <NonRouteInstall layout={layout} {...props} />;
+  const { requiredEnvSecret, requiredEnvHints } = requiredEnvFromDetail(detail);
+  const Mount = layout === 'dialog' ? MountInstallDialog : MountInstallForm;
+  return (
+    <Mount
+      refValue={refValue}
+      version={version}
+      verb="Install"
+      routeItems={routeItems}
+      requiredEnvSecret={requiredEnvSecret}
+      envHints={requiredEnvHints}
+      onDone={onInstalled}
+      onFailed={onFailed}
+      onDismiss={onDismiss}
+    />
+  );
+}
+
+/** The install in place, with its own Install button. */
+export function PluginInstallPanel(props: PluginInstallProps): ReactNode {
+  return <PluginInstall layout="panel" {...props} />;
+}
+
+/** The install in a dialog titled "Install plugin". */
+export function PluginInstallDialog(props: PluginInstallProps): ReactNode {
+  return <PluginInstall layout="dialog" {...props} />;
+}
+
+/** The line that stands in for an Install control this session's grant does not admit. */
+export const INSTALL_NO_GRANT =
+  'This session cannot install from the marketplace. Installing needs administrator access to POST /api/marketplace/install; ask an administrator to install it.';

package/src/marketplace-install/route-items.ts

@@ -0,0 +1,20 @@
+import type { MarketplaceRoutesDecl } from '@tai42/api-client';
+
+/** A route-carrying item as the install form drives it: its name, kind, and declaration. */
+export interface RouteItem {
+  readonly name: string;
+  readonly kind: string;
+  readonly routes: MarketplaceRoutesDecl;
+}
+
+/** The route-carrying items of a published version, in declaration order. */
+export function routeItemsOf(
+  items: readonly { kind: string; name: string; routes?: MarketplaceRoutesDecl | null }[],
+): RouteItem[] {
+  const out: RouteItem[] = [];
+  for (const item of items) {
+    if (item.routes === null || item.routes === undefined) continue;
+    out.push({ name: item.name, kind: item.kind, routes: item.routes });
+  }
+  return out;
+}

package/src/marketplace-install/use-debounced-value.ts

@@ -0,0 +1,18 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Track a value that only settles `delayMs` after it last changed. The first
+ * value settles immediately, so a read keyed on it fires on mount before any edit.
+ */
+export function useDebouncedValue<T>(value: T, delayMs: number): T {
+  const [settled, setSettled] = useState(value);
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setSettled(value);
+    }, delayMs);
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [value, delayMs]);
+  return settled;
+}

package/src/marketplace-install/use-install-action.ts

@@ -0,0 +1,60 @@
+/**
+ * The one install / update call path (`POST /api/marketplace/install` or
+ * `/update`), as a plain state machine through `useApi`. The ref is closed over;
+ * the caller supplies the rest of the body.
+ */
+import type { MarketplaceInstallBody, MarketplaceInstallResult } from '@tai42/api-client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { useApi } from '../hooks/useApi';
+
+export type InstallActionState =
+  | { readonly status: 'idle' }
+  | { readonly status: 'pending' }
+  | { readonly status: 'done'; readonly result: MarketplaceInstallResult }
+  | { readonly status: 'failed'; readonly error: unknown };
+
+export interface InstallAction {
+  readonly state: InstallActionState;
+  /** Resolves with the receipt; rejects with the server error after recording `failed`. */
+  readonly run: (body: Omit<MarketplaceInstallBody, 'ref'>) => Promise<MarketplaceInstallResult>;
+  /** Back to `idle`. */
+  readonly reset: () => void;
+}
+
+export function useInstallAction(refValue: string, verb: 'Install' | 'Update'): InstallAction {
+  const api = useApi();
+  const [state, setState] = useState<InstallActionState>({ status: 'idle' });
+  // A reply landing after unmount must not set state.
+  const mountedRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const run = useCallback(
+    async (body: Omit<MarketplaceInstallBody, 'ref'>): Promise<MarketplaceInstallResult> => {
+      setState({ status: 'pending' });
+      try {
+        const result =
+          verb === 'Install'
+            ? await api.installMarketplacePlugin({ ref: refValue, ...body })
+            : await api.updateMarketplacePlugin({ ref: refValue, ...body });
+        if (mountedRef.current) setState({ status: 'done', result });
+        return result;
+      } catch (error: unknown) {
+        if (mountedRef.current) setState({ status: 'failed', error });
+        throw error;
+      }
+    },
+    [api, refValue, verb],
+  );
+
+  const reset = useCallback(() => {
+    setState({ status: 'idle' });
+  }, []);
+
+  return { state, run, reset };
+}