dsh-zen-remote 2.2.9 → 2.3.1

package/src/client/wizard/WizardCard.tsx

@@ -0,0 +1,81 @@
+/**
+ * WizardCard (GW-10): the modal popup for steps the user must perform
+ * ELSEWHERE — creating the Cloudflare token, configuring their own
+ * reverse proxy. Numbered steps in the page locale, copy-to-clipboard for
+ * the value or snippet at hand, Esc / backdrop / button to close. Scoped
+ * under `[data-zen-remote="wizard-card"]`.
+ *
+ * Deliberately NO react-dom portal: `react-dom` is not a seed word of the
+ * host browser module table (GW-fix-4 — `check-client-externals` gates the
+ * allowlist), so the overlay renders IN PLACE as a `position: fixed`
+ * layer. That keeps the plugin version-agnostic; the z-index floor of
+ * 1000 clears the Plugins page chrome, and no ancestor of the detail page
+ * establishes a containing block that could clip it.
+ */
+
+import { useEffect, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+
+export interface WizardCardProps {
+  title: string
+  /** The card's body — numbered steps and/or a config snippet. */
+  children: ReactNode
+  /** The copy button's payload; absent means no copy button. */
+  copyText?: string | null
+  copyLabel: string
+  copiedLabel: string
+  closeLabel: string
+  /** Optional primary action button rendered alongside the close button. */
+  primaryAction?: ReactNode
+  onClose: () => void
+}
+
+export function WizardCard({ title, children, copyText, copyLabel, copiedLabel, closeLabel, primaryAction, onClose }: WizardCardProps): ReactNode {
+  const [copied, setCopied] = useState(false)
+  const copiedTimer = useRef<ReturnType<typeof setTimeout>>()
+
+  useEffect(() => {
+    const onKey = (event: KeyboardEvent): void => {
+      if (event.key === 'Escape') onClose()
+    }
+    document.addEventListener('keydown', onKey)
+    return () => {
+      document.removeEventListener('keydown', onKey)
+      if (copiedTimer.current !== undefined) clearTimeout(copiedTimer.current)
+    }
+  }, [onClose])
+
+  const copy = async (): Promise<void> => {
+    if (copyText === undefined || copyText === null || copyText === '') return
+    try {
+      await navigator.clipboard.writeText(copyText)
+      setCopied(true)
+      if (copiedTimer.current !== undefined) clearTimeout(copiedTimer.current)
+      copiedTimer.current = setTimeout(() => setCopied(false), 2000)
+    } catch {
+      // Clipboard denial (permissions, non-secure context): the snippet is
+      // selectable text anyway.
+    }
+  }
+
+  return (
+    <div data-zen-remote="wizard-card" onClick={onClose}>
+      <div className="zr-wizard-cardPanel" onClick={(event) => event.stopPropagation()}>
+        <div className="zr-wizard-cardHeader">
+          <p className="zr-wizard-cardTitle">{title}</p>
+          <button type="button" className="zr-wizard-cardCloseIcon" aria-label={closeLabel} onClick={onClose}>×</button>
+        </div>
+        <div className="zr-wizard-cardBody">
+          {children}
+        </div>
+        <div className="zr-wizard-cardActions">
+          <button type="button" className="zr-wizard-btn" onClick={onClose}>{closeLabel}</button>
+          {copyText !== undefined && copyText !== null && copyText !== '' ? (
+            <button type="button" className="zr-wizard-btn" onClick={() => { void copy() }}>{copied ? copiedLabel : copyLabel}</button>
+          ) : null}
+          {primaryAction}
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/client/wizard/cards/MigrateCard.tsx

@@ -0,0 +1,42 @@
+/**
+ * MigrateCard (GW-11): the six-step domain-to-Cloudflare walkthrough for
+ * the tunnel path's precondition, with the 「重新检查」 button that closes
+ * the card so the user re-runs the form's own check.
+ */
+
+import type { ReactNode } from 'react'
+import type { WizardT } from './TokenCard.tsx'
+import { WizardCard } from '../WizardCard.tsx'
+
+export interface MigrateCardProps {
+  t: WizardT
+  /** Closes the card so the caller can re-run its precondition check. */
+  onRecheck: () => void
+  onClose: () => void
+}
+
+const STEPS = ['migrateStep1', 'migrateStep2', 'migrateStep3', 'migrateStep4', 'migrateStep5', 'migrateStep6'] as const
+
+export function MigrateCard({ t, onRecheck, onClose }: MigrateCardProps): ReactNode {
+  return (
+    <WizardCard
+      title={t('wizard.card.migrateTitle')}
+      copyText={null}
+      copyLabel={t('wizard.card.copy')}
+      copiedLabel={t('wizard.card.copied')}
+      closeLabel={t('wizard.card.close')}
+      primaryAction={(
+        <button type="button" className="zr-wizard-btn zr-wizard-btnPrimary" onClick={onRecheck}>
+          {t('wizard.card.migrateRecheck')}
+        </button>
+      )}
+      onClose={onClose}
+    >
+      <div className="zr-wizard-cardSteps">
+        {STEPS.map((key, index) => (
+          <p key={key} className="zr-wizard-cardStep">{`${index + 1}. ${t(`wizard.card.${key}`)}`}</p>
+        ))}
+      </div>
+    </WizardCard>
+  )
+}

package/src/client/wizard/cards/PortForwardCard.tsx

@@ -0,0 +1,37 @@
+/**
+ * PortForwardCard (GW-11): the router port-forwarding steps for path A on
+ * a non-443 HTTPS port — the certificate rides DNS-01 (no inbound needed
+ * for issuance), but the HTTPS service port itself must be reachable.
+ */
+
+import type { ReactNode } from 'react'
+import type { WizardT } from './TokenCard.tsx'
+import { WizardCard } from '../WizardCard.tsx'
+
+export interface PortForwardCardProps {
+  t: WizardT
+  /** The HTTPS port to forward. */
+  port: number
+  onClose: () => void
+}
+
+const STEPS = ['portForwardStep1', 'portForwardStep2', 'portForwardStep3', 'portForwardStep4'] as const
+
+export function PortForwardCard({ t, port, onClose }: PortForwardCardProps): ReactNode {
+  return (
+    <WizardCard
+      title={t('wizard.card.portForwardTitle')}
+      copyText={null}
+      copyLabel={t('wizard.card.copy')}
+      copiedLabel={t('wizard.card.copied')}
+      closeLabel={t('wizard.card.close')}
+      onClose={onClose}
+    >
+      <div className="zr-wizard-cardSteps">
+        {STEPS.map((key, index) => (
+          <p key={key} className="zr-wizard-cardStep">{`${index + 1}. ${t(`wizard.card.${key}`, { port: String(port) })}`}</p>
+        ))}
+      </div>
+    </WizardCard>
+  )
+}

package/src/client/wizard/cards/ProxyCard.tsx

@@ -0,0 +1,56 @@
+/**
+ * ProxyCard (GW-11): the reverse-proxy snippets for the user's OWN proxy,
+ * tabbed nginx / Caddy / Lucky, with the snippet copy button and the
+ * 「我配好了，检查」 button that hands control back to the wizard's
+ * verification step.
+ */
+
+import { useState } from 'react'
+import type { ReactNode } from 'react'
+import { caddySnippetText, luckyStepTexts, nginxSnippetText, SNIPPET_KINDS, type SnippetKind } from '../../../client-data/wizard.ts'
+import type { WizardT } from './TokenCard.tsx'
+import { WizardCard } from '../WizardCard.tsx'
+
+export interface ProxyCardProps {
+  t: WizardT
+  /** Snippet inputs — the domain as typed, the gateway's ACTUAL port. */
+  domain: string
+  upstreamPort: number
+  /** 「我配好了，检查」: closes the card and starts the verification. */
+  onCheck: () => void
+  onClose: () => void
+}
+
+export function ProxyCard({ t, domain, upstreamPort, onCheck, onClose }: ProxyCardProps): ReactNode {
+  const [tab, setTab] = useState<SnippetKind>('nginx')
+  const input = { domain, upstreamHost: '127.0.0.1', upstreamPort }
+  const text = tab === 'nginx'
+    ? nginxSnippetText(input)
+    : tab === 'caddy' ? caddySnippetText(input) : (luckyStepTexts(input) ?? []).join('\n')
+  return (
+    <WizardCard
+      title={t('wizard.card.proxyTitle')}
+      copyText={text}
+      copyLabel={t('wizard.card.copy')}
+      copiedLabel={t('wizard.card.copied')}
+      closeLabel={t('wizard.card.close')}
+      primaryAction={(
+        <button type="button" className="zr-wizard-btn zr-wizard-btnPrimary" onClick={() => { onCheck(); onClose() }}>
+          {t('wizard.card.proxyCheck')}
+        </button>
+      )}
+      onClose={onClose}
+    >
+      <div className="zr-wizard-cardTabs">
+        {SNIPPET_KINDS.map((kind) => (
+          <button key={kind} type="button" className="zr-wizard-cardTab" data-selected={tab === kind} onClick={() => setTab(kind)}>
+            {kind}
+          </button>
+        ))}
+      </div>
+      {text === null
+        ? <p className="zr-wizard-cardStep">{t('wizard.badDomain')}</p>
+        : <pre className="zr-wizard-cardCode">{text}</pre>}
+    </WizardCard>
+  )
+}

package/src/client/wizard/cards/TokenCard.tsx

@@ -0,0 +1,81 @@
+/**
+ * TokenCard (GW-11): the Cloudflare API-token creation walkthrough — eight
+ * numbered steps, the permission checklist as a small table, and a
+ * paste-in box that hands the token back to the wizard's form (`onUse`).
+ * The token never persists in component state beyond the box and never
+ * leaves this machine except inside the wizard's own POST.
+ */
+
+import { useState } from 'react'
+import type { ReactNode } from 'react'
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
+import { NS } from '../../locales.ts'
+import { WizardCard } from '../WizardCard.tsx'
+
+/** The wizard's translate function, straight from the shared locale contract. */
+export type WizardT = PropsLocale<typeof NS>['t']
+
+export interface TokenCardProps {
+  t: WizardT
+  /** Hands the pasted token back to the wizard's form field. */
+  onUse: (token: string) => void
+  onClose: () => void
+}
+
+const STEPS = ['tokenStep1', 'tokenStep2', 'tokenStep3', 'tokenStep4', 'tokenStep5', 'tokenStep6', 'tokenStep7', 'tokenStep8'] as const
+
+export function TokenCard({ t, onUse, onClose }: TokenCardProps): ReactNode {
+  const [pasted, setPasted] = useState('')
+  return (
+    <WizardCard
+      title={t('wizard.card.tokenTitle')}
+      copyText={null}
+      copyLabel={t('wizard.card.copy')}
+      copiedLabel={t('wizard.card.copied')}
+      closeLabel={t('wizard.card.close')}
+      primaryAction={(
+        <button type="button" className="zr-wizard-btn zr-wizard-btnPrimary" disabled={pasted.trim() === ''} onClick={() => onUse(pasted.trim())}>
+          {t('wizard.card.tokenUse')}
+        </button>
+      )}
+      onClose={onClose}
+    >
+      <div className="zr-wizard-cardSteps">
+        {STEPS.map((key, index) => (
+          <p key={key} className="zr-wizard-cardStep">{`${index + 1}. ${t(`wizard.card.${key}`)}`}</p>
+        ))}
+      </div>
+      <p className="zr-wizard-cardSubhead">{t('wizard.card.tokenPerms')}</p>
+      <table className="zr-wizard-cardTable">
+        <tbody>
+          <tr>
+            <td className="zr-wizard-cardPerm">{t('wizard.card.tokenPermDns')}</td>
+            <td className="zr-wizard-cardWhy">{t('wizard.card.tokenPermDnsWhy')}</td>
+          </tr>
+          <tr>
+            <td className="zr-wizard-cardPerm">{t('wizard.card.tokenPermTunnel')}</td>
+            <td className="zr-wizard-cardWhy">{t('wizard.card.tokenPermTunnelWhy')}</td>
+          </tr>
+          <tr>
+            <td className="zr-wizard-cardPerm">{t('wizard.card.tokenPermAccount')}</td>
+            <td className="zr-wizard-cardWhy">{t('wizard.card.tokenPermAccountWhy')}</td>
+          </tr>
+          <tr>
+            <td className="zr-wizard-cardPerm">{t('wizard.card.tokenPermZoneRead')}</td>
+            <td className="zr-wizard-cardWhy">{t('wizard.card.tokenPermZoneReadWhy')}</td>
+          </tr>
+        </tbody>
+      </table>
+      <div className="zr-wizard-field">
+        <label className="zr-wizard-label" htmlFor="zr-wizard-token-paste">{t('wizard.card.tokenPaste')}</label>
+        <input
+          id="zr-wizard-token-paste"
+          className="zr-wizard-input"
+          type="password"
+          value={pasted}
+          onChange={(event) => setPasted(event.target.value)}
+        />
+      </div>
+    </WizardCard>
+  )
+}

package/src/client/wizard/register-wizard.ts

@@ -0,0 +1,99 @@
+/**
+ * Wizard registration for the plugin DETAIL page — the piece that must
+ * run BEFORE apply's desktop-shell gate (same discipline as
+ * register-settings.ts, and for the same reason: the desktop app IS the
+ * main server, and the wizard is exactly where it is most useful).
+ *
+ * Registered on `plugins.bundle.config` (keyed by `'dsh-zen-remote'`), which
+ * `PackageDetail` renders as the FIRST section at the top of the bundle
+ * detail page (above `RowsSection`「插件组件」and `SourceSection`「来源」),
+ * and which `RowDetail` (the component detail page) never renders.
+ *
+ * `configForms` never joins the top-level inject: a composition without
+ * the settings service keeps the whole browser half loadable, and the lazy
+ * `ctx.inject(['configForms'], …)` below simply never fires there — a
+ * composition that cannot stage row edits has no use for a wizard that
+ * writes rows.
+ */
+import type { ClientContext } from '../compat/types.ts'
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+// Type-only: the renderer declares `ctx.slots` on the cordis Context.
+import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
+import { DEVICE_TOKEN_FIELD, ZenRemoteSettingsForm } from '../../client-data/settings-form.ts'
+import { NS } from '../locales.ts'
+import { SETTINGS_ENTRY_ID } from '../settings/register-settings.ts'
+import { WIZARD_CSS } from './wizard-css.ts'
+import type { GatewayWizard } from './GatewayWizard.tsx'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    /**
+     * One bundle's top configuration block on the plugin DETAIL page — a
+     * keyed seat (`key = pkg.name`) rendered at the top of `PackageDetail`
+     * above the component rows and source sections, and absent from
+     * `RowDetail` (structural mirror of the plugin-manager's declaration).
+     */
+    'plugins.bundle.config': {
+      kind: 'keyed'
+      scope: 'root'
+      owner: { readonly view: 'page' }
+    }
+  }
+}
+
+/** `plugins.bundle.config` key: the bundle's package name. */
+export const WIZARD_BUNDLE_KEY = 'dsh-zen-remote'
+
+export interface SaveRowFieldsOptions {
+  /** Field names to remove (`op: 'unset'`) in the same atomic mutation. */
+  unset?: readonly string[]
+}
+
+/**
+ * Register the wizard stylesheet and (lazily, only where the settings
+ * service exists) the bundle detail-page top block.
+ * @param ctx - client root context.
+ * @param section - the block component; a parameter so this module stays
+ *   JSX-free and importable under Node's type stripping.
+ */
+export function registerGatewayWizard(ctx: ClientContext, section: typeof GatewayWizard): void {
+  ctx.effect(() => {
+    const tag = document.createElement('style')
+    tag.dataset.plugin = 'dsh-zen-remote-wizard'
+    tag.textContent = WIZARD_CSS
+    document.head.appendChild(tag)
+    return () => { tag.remove() }
+  }, 'dsh-zen-remote: wizard styles')
+
+  ctx.inject(['configForms'], (formsCtx) => {
+    const scope = formsCtx.configForms.get(SETTINGS_ENTRY_ID)
+    // Follow the describe sidecar when available so client-mode pairing can
+    // see whether `deviceToken` is configured (degrades to false in minimal
+    // test harnesses that omit `describe`).
+    const describe = typeof formsCtx.configForms.describe === 'function' ? formsCtx.configForms.describe() : undefined
+    const secretConfigured = (): boolean => {
+      const namespaces = describe?.getSnapshot().view?.namespaces ?? []
+      const row = namespaces.find((candidate) => candidate.ns === SETTINGS_ENTRY_ID)
+      return (row?.secrets ?? []).some(
+        (secret) => secret.path.length === 1 && secret.path[0] === DEVICE_TOKEN_FIELD && secret.set,
+      )
+    }
+    const config = new ZenRemoteSettingsForm(scope, secretConfigured)
+    const offDescribe = describe !== undefined ? describe.subscribe(() => { config.refresh() }) : () => {}
+    formsCtx.effect(() => () => { offDescribe(); config.dispose() }, 'dsh-zen-remote: wizard form')
+    const saveRowFields = async (fields: Record<string, unknown>, options?: SaveRowFieldsOptions): Promise<void> => {
+      const snapshot = scope.getSnapshot()
+      const ops = [
+        ...Object.entries(fields).map(([key, value]) => ({ op: 'set' as const, path: [key], value })),
+        ...(options?.unset ?? []).map((key) => ({ op: 'unset' as const, path: [key] })),
+      ]
+      await scope.mutate(ops, snapshot.revision)
+    }
+    formsCtx.effect(() => formsCtx.slots.inject('plugins.bundle.config', () => formsCtx.slots.register({
+      name: 'plugins.bundle.config',
+      key: WIZARD_BUNDLE_KEY,
+      locale: NS,
+      inject: () => ({ config, saveRowFields }),
+    }, section)), 'dsh-zen-remote: wizard section')
+  })
+}