@workbench-kit/shell-react 0.0.2-prototype.0.2.10

package/src/extensions/management-model.ts

@@ -0,0 +1,313 @@
+import {
+  BUILTIN_WORKBENCH_EXTENSIONS,
+  SAMPLE_WORKBENCH_EXTENSIONS,
+  createExtensionFeatureSpec,
+  createExtensionInstallPlan,
+  resolveBundledExtensionByManifestUrl,
+  type ExtensionCatalogEntry,
+  type ExtensionFeatureInspection,
+  type ExtensionFeatureSpec,
+  type ExtensionInstallPlan,
+  type ExtensionInstallPlanInstallSource,
+  type ExtensionRegistry,
+  type InstalledExtensionRecord,
+  type WorkbenchExtensionDescription,
+} from '@workbench-kit/workbench-core';
+import type {
+  ExtensionCatalogBrowseEntry,
+  ExtensionManagementDiagnosticSummary,
+  ExtensionManagementEntry,
+  ExtensionManagementFeatureSummary,
+} from '@workbench-kit/react/workbench/management';
+
+export const BUNDLED_EXTENSIONS = [
+  ...BUILTIN_WORKBENCH_EXTENSIONS,
+  ...SAMPLE_WORKBENCH_EXTENSIONS,
+] as const;
+
+export interface CreateExtensionManagementEntriesInput {
+  readonly extensionRegistry: ExtensionRegistry;
+  readonly installedRecords: readonly InstalledExtensionRecord[];
+}
+
+export interface CreateExtensionCatalogBrowseEntriesInput extends CreateExtensionManagementEntriesInput {
+  readonly catalogEntries: readonly ExtensionCatalogEntry[];
+}
+
+export interface ExtensionInstallPlanningContext extends CreateExtensionManagementEntriesInput {
+  readonly availableExtensions: readonly WorkbenchExtensionDescription[];
+  readonly enabledExtensionIds: readonly string[];
+  readonly hostCapabilityIds: readonly string[];
+  readonly installSources: readonly ExtensionInstallPlanInstallSource[];
+}
+
+export function createExtensionManagementEntries({
+  extensionRegistry,
+  installedRecords,
+}: CreateExtensionManagementEntriesInput): readonly ExtensionManagementEntry[] {
+  const installedById = new Map(installedRecords.map((record) => [record.id, record]));
+  const extensionFeatures = createExtensionManagementFeatureMaps(extensionRegistry);
+  const bundledEntries = BUNDLED_EXTENSIONS.map((extension) => {
+    const installed = installedById.get(extension.manifest.id);
+    const isBuiltin = extension.manifest.id.startsWith('workbench-kit.builtin.');
+    const featureState = resolveExtensionManagementFeatureState(
+      extension.manifest.id,
+      extensionFeatures,
+    );
+
+    return {
+      category: installed?.category ?? (isBuiltin ? 'builtin' : 'sample'),
+      description: extension.manifest.displayName,
+      diagnostics: featureState.diagnostics,
+      displayName: extension.manifest.displayName,
+      enabled: isBuiltin ? true : (installed?.enabled ?? false),
+      features: featureState.features,
+      id: extension.manifest.id,
+      installedAt: installed?.installedAt,
+      manifestUrl: installed?.manifestUrl,
+      source: isBuiltin ? ('bundled' as const) : ('installed' as const),
+    } satisfies ExtensionManagementEntry;
+  }).filter((entry) => entry.source === 'bundled' || installedById.has(entry.id));
+
+  const activeExtensions = extensionRegistry
+    .getExtensions()
+    .filter(
+      (extension) =>
+        !BUNDLED_EXTENSIONS.some((bundled) => bundled.manifest.id === extension.manifest.id),
+    )
+    .map((extension) => {
+      const installed = installedById.get(extension.manifest.id);
+      const featureState = resolveExtensionManagementFeatureState(
+        extension.manifest.id,
+        extensionFeatures,
+      );
+
+      return {
+        category: installed?.category ?? 'installed',
+        description: extension.manifest.displayName,
+        diagnostics: featureState.diagnostics,
+        displayName: extension.manifest.displayName,
+        enabled: installed?.enabled ?? true,
+        features: featureState.features,
+        id: extension.manifest.id,
+        installedAt: installed?.installedAt,
+        manifestUrl: installed?.manifestUrl,
+        source: 'installed',
+      } satisfies ExtensionManagementEntry;
+    });
+
+  return [...bundledEntries, ...activeExtensions].sort((left, right) =>
+    left.displayName.localeCompare(right.displayName),
+  );
+}
+
+export function createExtensionCatalogBrowseEntries({
+  catalogEntries,
+  extensionRegistry,
+  installedRecords,
+}: CreateExtensionCatalogBrowseEntriesInput): readonly ExtensionCatalogBrowseEntry[] {
+  const installedIds = new Set(installedRecords.map((record) => record.id));
+  const installContext = createExtensionInstallPlanningContext({
+    catalogEntries,
+    extensionRegistry,
+    installedRecords,
+  });
+
+  return catalogEntries.map((entry) => {
+    const bundledExtension = resolveBundledExtensionByManifestUrl(
+      entry.manifestUrl,
+      installContext.availableExtensions,
+    );
+    const extensionId = bundledExtension?.manifest.id ?? entry.id;
+    const plan = createCatalogEntryInstallPlan(entry, installContext);
+
+    return {
+      category: entry.category,
+      description: entry.description,
+      displayName: entry.displayName,
+      icon: entry.icon,
+      id: extensionId,
+      installPlan: plan ? toExtensionInstallPlanSummary(plan) : undefined,
+      installed: installedIds.has(extensionId),
+      manifestUrl: entry.manifestUrl,
+    };
+  });
+}
+
+export function createExtensionInstallPlanningContext({
+  catalogEntries,
+  extensionRegistry,
+  installedRecords,
+}: CreateExtensionCatalogBrowseEntriesInput): ExtensionInstallPlanningContext {
+  const availableExtensions = mergeUniqueExtensionDescriptions([
+    ...BUNDLED_EXTENSIONS,
+    ...extensionRegistry.getExtensions(),
+  ]);
+
+  return {
+    availableExtensions,
+    enabledExtensionIds: extensionRegistry
+      .getExtensions()
+      .map((extension) => extension.manifest.id),
+    extensionRegistry,
+    hostCapabilityIds: extensionRegistry.capabilityRegistry.listProviderIds(),
+    installSources: createExtensionInstallSources(catalogEntries, availableExtensions),
+    installedRecords,
+  };
+}
+
+export function createCatalogEntryInstallPlan(
+  entry: Pick<ExtensionCatalogBrowseEntry, 'manifestUrl'>,
+  {
+    availableExtensions,
+    enabledExtensionIds,
+    hostCapabilityIds,
+    installedRecords,
+    installSources,
+  }: ExtensionInstallPlanningContext,
+): ExtensionInstallPlan | undefined {
+  const bundledExtension = resolveBundledExtensionByManifestUrl(
+    entry.manifestUrl,
+    availableExtensions,
+  );
+  if (!bundledExtension) {
+    return undefined;
+  }
+
+  return createExtensionInstallPlan({
+    availableExtensions,
+    enabledExtensionIds,
+    hostCapabilityIds,
+    installSources,
+    installedRecords,
+    targetExtensionId: bundledExtension.manifest.id,
+  });
+}
+
+function createExtensionInstallSources(
+  catalogEntries: readonly ExtensionCatalogEntry[],
+  availableExtensions: readonly WorkbenchExtensionDescription[],
+): readonly ExtensionInstallPlanInstallSource[] {
+  const byId = new Map<string, ExtensionInstallPlanInstallSource>();
+  for (const entry of catalogEntries) {
+    const bundledExtension = resolveBundledExtensionByManifestUrl(
+      entry.manifestUrl,
+      availableExtensions,
+    );
+    const extensionId = bundledExtension?.manifest.id ?? entry.id;
+    byId.set(extensionId, {
+      category: entry.category,
+      id: extensionId,
+      manifestUrl: entry.manifestUrl,
+    });
+  }
+
+  return [...byId.values()];
+}
+
+function mergeUniqueExtensionDescriptions(
+  descriptions: readonly WorkbenchExtensionDescription[],
+): readonly WorkbenchExtensionDescription[] {
+  const byId = new Map<string, WorkbenchExtensionDescription>();
+  for (const description of descriptions) {
+    byId.set(description.manifest.id, description);
+  }
+  return [...byId.values()];
+}
+
+function createExtensionManagementFeatureMaps(extensionRegistry: ExtensionRegistry) {
+  return {
+    bundledFeaturesById: new Map(
+      BUNDLED_EXTENSIONS.map((extension) => [
+        extension.manifest.id,
+        createExtensionFeatureSpec(extension),
+      ]),
+    ),
+    inspectionsById: new Map(
+      extensionRegistry
+        .getFeatureInspections()
+        .map((inspection) => [inspection.feature.id, inspection]),
+    ),
+  };
+}
+
+function resolveExtensionManagementFeatureState(
+  extensionId: string,
+  {
+    bundledFeaturesById,
+    inspectionsById,
+  }: {
+    bundledFeaturesById: ReadonlyMap<string, ExtensionFeatureSpec>;
+    inspectionsById: ReadonlyMap<string, ExtensionFeatureInspection>;
+  },
+): {
+  readonly diagnostics?: readonly ExtensionManagementDiagnosticSummary[] | undefined;
+  readonly features?: ExtensionManagementFeatureSummary | undefined;
+} {
+  const inspection = inspectionsById.get(extensionId);
+  const feature = inspection?.feature ?? bundledFeaturesById.get(extensionId);
+
+  return {
+    diagnostics: inspection?.diagnostics.map(({ message, severity }) => ({ message, severity })),
+    features: feature ? toExtensionManagementFeatureSummary(feature) : undefined,
+  };
+}
+
+function toExtensionManagementFeatureSummary(
+  feature: ExtensionFeatureSpec,
+): ExtensionManagementFeatureSummary {
+  const commandTitlesById = new Map(feature.commands.map((command) => [command.id, command.title]));
+
+  return {
+    capabilities: feature.capabilities,
+    commands: feature.commands.map((command) => ({
+      description: command.description,
+      id: command.id,
+      label: command.title,
+    })),
+    documentViews: feature.documentViews.map((view) => ({
+      id: view.id,
+      label: view.label,
+    })),
+    menus: feature.menus.map((menu) => ({
+      description: formatMenuContributionDescription(menu.group, menu.order),
+      id: `${menu.menu}:${menu.command}`,
+      label: `${menu.menu}: ${commandTitlesById.get(menu.command) ?? menu.command}`,
+    })),
+    permissions: feature.permissions,
+    settings: feature.settings.map((setting) => ({
+      description: setting.description,
+      id: setting.key,
+      label: setting.key,
+    })),
+    views: feature.views.map((view) => ({
+      id: view.id,
+      label: view.name,
+    })),
+  };
+}
+
+function toExtensionInstallPlanSummary(
+  plan: ExtensionInstallPlan,
+): ExtensionCatalogBrowseEntry['installPlan'] {
+  return {
+    blocked: plan.blocked,
+    diagnostics: plan.diagnostics.map(({ message, severity }) => ({ message, severity })),
+    enableExtensionIds: plan.enableExtensionIds,
+    installExtensionIds: plan.installExtensionIds,
+    permissions: plan.permissions,
+    requiresApproval: plan.requiresApproval,
+  };
+}
+
+function formatMenuContributionDescription(
+  group: string | undefined,
+  order: number | undefined,
+): string | undefined {
+  const parts = [
+    group ? `group: ${group}` : undefined,
+    order !== undefined ? `order: ${order}` : undefined,
+  ].filter((part): part is string => part !== undefined);
+
+  return parts.length > 0 ? parts.join(', ') : undefined;
+}

package/src/extensions/use-extension-management.ts

@@ -0,0 +1,241 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import {
+  DEFAULT_EXTENSION_CATALOG_TRUST_POLICY,
+  DEFAULT_EXTENSION_INSTALL_TRUST_STORAGE_KEY,
+  DEFAULT_INSTALLED_EXTENSIONS_STORAGE_KEY,
+  ExtensionInstallApprovalRequiredError,
+  applyExtensionInstallPlanToRecords,
+  assertExtensionCatalogUrlAllowed,
+  loadExtensionInstallTrustRecords,
+  loadInstalledExtensions,
+  parseExtensionCatalog,
+  recordExtensionInstallTrust,
+  saveExtensionInstallTrustRecords,
+  saveInstalledExtensions,
+  toggleInstalledExtensionEnabled,
+  type ExtensionCatalogEntry,
+  type ExtensionCatalogTrustPolicy,
+  type ExtensionInstallTrustRecord,
+  type InstalledExtensionRecord,
+} from '@workbench-kit/workbench-core';
+import type {
+  ExtensionCatalogBrowseEntry,
+  ExtensionInstallOptions,
+  ExtensionManagementEntry,
+  ExtensionManagementPendingAction,
+} from '@workbench-kit/react/workbench/management';
+
+import {
+  createCatalogEntryInstallPlan,
+  createExtensionCatalogBrowseEntries,
+  createExtensionInstallPlanningContext,
+  createExtensionManagementEntries,
+} from './management-model.js';
+import { useWorkbench, type WorkbenchStorageAdapter } from '../shell/provider.js';
+
+export interface UseExtensionManagementModelOptions {
+  catalogTrustPolicy?: ExtensionCatalogTrustPolicy | undefined;
+  catalogUrl?: string | undefined;
+  installedExtensionsStorage?: WorkbenchStorageAdapter | undefined;
+  installedExtensionsStorageKey?: string | undefined;
+  installTrustStorage?: WorkbenchStorageAdapter | undefined;
+  installTrustStorageKey?: string | undefined;
+}
+
+export function useExtensionManagementModel({
+  catalogTrustPolicy = DEFAULT_EXTENSION_CATALOG_TRUST_POLICY,
+  catalogUrl = '/extension-catalog.json',
+  installedExtensionsStorage,
+  installedExtensionsStorageKey,
+  installTrustStorage,
+  installTrustStorageKey = DEFAULT_EXTENSION_INSTALL_TRUST_STORAGE_KEY,
+}: UseExtensionManagementModelOptions = {}) {
+  const workbench = useWorkbench();
+  const { extensionRegistry } = workbench;
+  const resolvedInstalledExtensionsStorage =
+    installedExtensionsStorage ?? workbench.installedExtensionsStorage;
+  const resolvedInstalledExtensionsStorageKey =
+    installedExtensionsStorageKey ??
+    workbench.installedExtensionsStorageKey ??
+    DEFAULT_INSTALLED_EXTENSIONS_STORAGE_KEY;
+  const resolvedInstallTrustStorage = installTrustStorage ?? resolvedInstalledExtensionsStorage;
+  const [catalogEntries, setCatalogEntries] = useState<readonly ExtensionCatalogEntry[]>([]);
+  const [catalogLoading, setCatalogLoading] = useState(Boolean(catalogUrl));
+  const [catalogError, setCatalogError] = useState<string | undefined>();
+  const [pendingAction, setPendingAction] = useState<
+    ExtensionManagementPendingAction | undefined
+  >();
+  const [installedRecords, setInstalledRecords] = useState<readonly InstalledExtensionRecord[]>(
+    () =>
+      loadInstalledExtensions(
+        resolvedInstalledExtensionsStorageKey,
+        resolvedInstalledExtensionsStorage,
+      ),
+  );
+  const [installTrustRecords, setInstallTrustRecords] = useState<
+    readonly ExtensionInstallTrustRecord[]
+  >(() => loadExtensionInstallTrustRecords(installTrustStorageKey, resolvedInstallTrustStorage));
+
+  useEffect(() => {
+    setInstalledRecords(
+      loadInstalledExtensions(
+        resolvedInstalledExtensionsStorageKey,
+        resolvedInstalledExtensionsStorage,
+      ),
+    );
+  }, [resolvedInstalledExtensionsStorage, resolvedInstalledExtensionsStorageKey]);
+
+  useEffect(() => {
+    setInstallTrustRecords(
+      loadExtensionInstallTrustRecords(installTrustStorageKey, resolvedInstallTrustStorage),
+    );
+  }, [installTrustStorageKey, resolvedInstallTrustStorage]);
+
+  useEffect(() => {
+    if (!catalogUrl) {
+      setCatalogEntries([]);
+      setCatalogLoading(false);
+      setCatalogError(undefined);
+      return;
+    }
+
+    let cancelled = false;
+    setCatalogLoading(true);
+    setCatalogError(undefined);
+
+    void Promise.resolve()
+      .then(() => {
+        assertExtensionCatalogUrlAllowed(catalogUrl, catalogTrustPolicy);
+        return fetch(catalogUrl);
+      })
+      .then(async (response) => {
+        if (!response.ok) {
+          throw new Error(`Catalog request failed with status ${response.status}.`);
+        }
+
+        const catalog = parseExtensionCatalog(await response.json());
+        if (!cancelled) {
+          setCatalogEntries(catalog.entries);
+        }
+      })
+      .catch((error: unknown) => {
+        if (!cancelled) {
+          setCatalogEntries([]);
+          setCatalogError(
+            error instanceof Error ? error.message : 'Failed to load extension catalog.',
+          );
+        }
+      })
+      .finally(() => {
+        if (!cancelled) {
+          setCatalogLoading(false);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [catalogTrustPolicy, catalogUrl]);
+
+  const installedEntries = useMemo<readonly ExtensionManagementEntry[]>(() => {
+    return createExtensionManagementEntries({ extensionRegistry, installedRecords });
+  }, [extensionRegistry, installedRecords]);
+
+  const browseEntries = useMemo<readonly ExtensionCatalogBrowseEntry[]>(() => {
+    return createExtensionCatalogBrowseEntries({
+      catalogEntries,
+      extensionRegistry,
+      installedRecords,
+    });
+  }, [catalogEntries, extensionRegistry, installedRecords]);
+
+  const installCatalogEntry = useCallback(
+    (entry: ExtensionCatalogBrowseEntry, options?: ExtensionInstallOptions) => {
+      const installContext = createExtensionInstallPlanningContext({
+        catalogEntries,
+        extensionRegistry,
+        installedRecords,
+      });
+      const plan = createCatalogEntryInstallPlan(entry, installContext);
+      if (!plan || plan.blocked) {
+        return;
+      }
+
+      // Align with core hard gate: unapproved privileged installs must not persist.
+      if (plan.requiresApproval && options?.approved !== true) {
+        throw new ExtensionInstallApprovalRequiredError();
+      }
+
+      const next = applyExtensionInstallPlanToRecords({
+        approved: options?.approved === true,
+        currentRecords: installedRecords,
+        installSources: installContext.installSources,
+        plan,
+      });
+      saveInstalledExtensions(
+        next,
+        resolvedInstalledExtensionsStorageKey,
+        resolvedInstalledExtensionsStorage,
+      );
+      setInstalledRecords(next);
+      setPendingAction({ entryId: entry.id, kind: 'install' });
+      if (typeof window !== 'undefined') {
+        window.requestAnimationFrame(() => {
+          window.location.reload();
+        });
+      }
+    },
+    [
+      catalogEntries,
+      extensionRegistry,
+      installedRecords,
+      resolvedInstalledExtensionsStorage,
+      resolvedInstalledExtensionsStorageKey,
+    ],
+  );
+
+  const toggleInstalledEntry = useCallback(
+    (entry: ExtensionManagementEntry, enabled: boolean) => {
+      if (entry.source === 'bundled' && entry.id.startsWith('workbench-kit.builtin.')) {
+        return;
+      }
+
+      const next = toggleInstalledExtensionEnabled(
+        entry.id,
+        enabled,
+        resolvedInstalledExtensionsStorageKey,
+        resolvedInstalledExtensionsStorage,
+      );
+      setInstalledRecords(next);
+      setPendingAction({ entryId: entry.id, kind: 'toggle' });
+      if (typeof window !== 'undefined') {
+        window.requestAnimationFrame(() => {
+          window.location.reload();
+        });
+      }
+    },
+    [resolvedInstalledExtensionsStorage, resolvedInstalledExtensionsStorageKey],
+  );
+
+  const rememberInstallTrust = useCallback(
+    (entry: ExtensionCatalogBrowseEntry) => {
+      const permissions = entry.installPlan?.permissions ?? [];
+      const next = recordExtensionInstallTrust(entry.id, permissions, installTrustRecords);
+      saveExtensionInstallTrustRecords(next, installTrustStorageKey, resolvedInstallTrustStorage);
+      setInstallTrustRecords(next);
+    },
+    [installTrustRecords, installTrustStorageKey, resolvedInstallTrustStorage],
+  );
+
+  return {
+    browseEntries,
+    catalogError,
+    catalogLoading,
+    installCatalogEntry,
+    installedEntries,
+    installTrustRecords,
+    pendingAction,
+    rememberInstallTrust,
+    toggleInstalledEntry,
+  };
+}

package/src/extensions/view-data.ts

@@ -0,0 +1,19 @@
+export const BUILTIN_EXTENSIONS_VIEW_RENDER_KIND = 'workbench-kit.builtin.extensions.view' as const;
+export const BUILTIN_EXTENSIONS_VIEW_CONTAINER_ID = 'extensions' as const;
+export const BUILTIN_EXTENSIONS_FOCUS_COMMAND_ID =
+  'workbench-kit.builtin.extensions.focus' as const;
+
+export interface BuiltinExtensionsViewRenderData {
+  readonly kind: typeof BUILTIN_EXTENSIONS_VIEW_RENDER_KIND;
+}
+
+export function isBuiltinExtensionsViewRenderData(
+  value: unknown,
+): value is BuiltinExtensionsViewRenderData {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'kind' in value &&
+    (value as BuiltinExtensionsViewRenderData).kind === BUILTIN_EXTENSIONS_VIEW_RENDER_KIND
+  );
+}

package/src/extensions/view.tsx

@@ -0,0 +1,63 @@
+import { useCallback } from 'react';
+import { ExtensionManagementSidebar } from '@workbench-kit/react/workbench/management';
+import {
+  isExtensionInstallTrusted,
+  type ExtensionCatalogTrustPolicy,
+} from '@workbench-kit/workbench-core';
+
+import {
+  BUILTIN_EXTENSIONS_VIEW_RENDER_KIND,
+  isBuiltinExtensionsViewRenderData,
+  type BuiltinExtensionsViewRenderData,
+} from './view-data.js';
+import { useExtensionManagementModel } from './use-extension-management.js';
+import { useWorkbench } from '../shell/provider.js';
+
+export type { BuiltinExtensionsViewRenderData };
+export { BUILTIN_EXTENSIONS_VIEW_RENDER_KIND, isBuiltinExtensionsViewRenderData };
+
+export function BuiltinExtensionsView({
+  catalogTrustPolicy,
+  catalogUrl,
+}: {
+  catalogTrustPolicy?: ExtensionCatalogTrustPolicy | undefined;
+  catalogUrl?: string | undefined;
+}) {
+  const { missingExtensionIds } = useWorkbench();
+  const {
+    browseEntries,
+    catalogError,
+    catalogLoading,
+    installCatalogEntry,
+    installedEntries,
+    installTrustRecords,
+    pendingAction,
+    rememberInstallTrust,
+    toggleInstalledEntry,
+  } = useExtensionManagementModel({ catalogTrustPolicy, catalogUrl });
+
+  const isInstallTrusted = useCallback(
+    (entry: (typeof browseEntries)[number]) =>
+      isExtensionInstallTrusted(
+        entry.id,
+        entry.installPlan?.permissions ?? [],
+        installTrustRecords,
+      ),
+    [installTrustRecords],
+  );
+
+  return (
+    <ExtensionManagementSidebar
+      browseEntries={browseEntries}
+      catalogError={catalogError}
+      catalogLoading={catalogLoading}
+      installedEntries={installedEntries}
+      isInstallTrusted={isInstallTrusted}
+      missingExtensionIds={missingExtensionIds}
+      pendingAction={pendingAction}
+      onInstall={installCatalogEntry}
+      onRememberInstallTrust={rememberInstallTrust}
+      onToggleEnabled={toggleInstalledEntry}
+    />
+  );
+}