refactor(hub-ui-onboard): rename confirm option to onConfirm

Author: antfubot

docs/content/1.guide/23.hub-ui-onboard.md

@@ -51,14 +51,14 @@ Install changes `package.json` and the lockfile, and a dev server can be reachab
 
 When stdin is not a TTY (CI, a detached container, a task runner that pipes stdin), nobody can answer. The onboarding then refuses at once with [DF9006](/errors/DF9006). Only one question is open at a time: more clicks while it is open share its answer. A `POST` from another origin is refused with `403` before any question.
 
-To ask in another way, pass `confirm`. It gets the `packages`, the exact `command`, and the panel's `request`, and returns `true` to allow the install. For example, a Nuxt module can ask through `consola`:
+To ask in another way, pass `onConfirm`. It gets the `packages`, the exact `command`, and the panel's `request`, and returns `true` to allow the install. For example, a Nuxt module can ask through `consola`:
 
 ```ts
 import { consola } from 'consola'
 
 const onboarding = createOnboarding({
   packages: ['@nuxt/devtools'],
-  confirm: ({ command }) => consola.prompt(`Run \`${command.join(' ')}\` for the browser that asked?`, { type: 'confirm' }),
+  onConfirm: ({ command }) => consola.prompt(`Run \`${command.join(' ')}\` for the browser that asked?`, { type: 'confirm' }),
 })
 ```
 

docs/content/6.errors/DF9005.md

@@ -9,13 +9,13 @@ description: 'A browser asked to run `{command}`. Type y and press Enter to allo
 
 ## Cause
 
-Install changes `package.json` and the lockfile, and a dev server can be reachable from other devices. So each install that the panel asks for needs the developer's permission. The panel's `POST <base>__onboard/install` waits until you answer. Without a `confirm` option, `createOnboarding()` asks in the terminal that runs the dev server.
+Install changes `package.json` and the lockfile, and a dev server can be reachable from other devices. So each install that the panel asks for needs the developer's permission. The panel's `POST <base>__onboard/install` waits until you answer. Without an `onConfirm` option, `createOnboarding()` asks in the terminal that runs the dev server.
 
 ## Fix
 
 If you clicked Install, type `y` and press Enter. Any other answer refuses the install, and the panel tells the user. If you did not click Install, press Enter. Another device or page can reach this dev server, so bind it to `localhost`.
 
-To ask in another way, for example with your own logger, pass a `confirm` function to `createOnboarding()`.
+To ask in another way, for example with your own logger, pass an `onConfirm` function to `createOnboarding()`.
 
 ## Source
 

docs/content/6.errors/DF9006.md

@@ -9,11 +9,11 @@ description: 'A browser asked to run `{command}`, but no interactive terminal ca
 
 ## Cause
 
-Each install that the panel asks for needs the developer's permission ([DF9005](/errors/DF9005)). Without a `confirm` option, `createOnboarding()` asks in the terminal. Here stdin is not a TTY, so nobody can answer. This happens in CI, in a detached container, or when a task runner pipes stdin. The install is refused at once, and the panel tells the user.
+Each install that the panel asks for needs the developer's permission ([DF9005](/errors/DF9005)). Without an `onConfirm` option, `createOnboarding()` asks in the terminal. Here stdin is not a TTY, so nobody can answer. This happens in CI, in a detached container, or when a task runner pipes stdin. The install is refused at once, and the panel tells the user.
 
 ## Fix
 
-Run the command from the panel in a terminal yourself. Or pass a `confirm` function to `createOnboarding()` that asks in another way.
+Run the command from the panel in a terminal yourself. Or pass an `onConfirm` function to `createOnboarding()` that asks in another way.
 
 ## Source
 

docs/content/8.references/6.hub-api.md

@@ -98,13 +98,13 @@ What `createOnboarding()` from `@devframes/hub-ui-onboard` accepts and serves: [
 | `branding` | `{}` | `productName` (default `Devframes`), `logo` (URL or `{ light, dark }`), `primaryColor` |
 | `messages` | derived from `productName` | Overrides for `title`, `description`, `install`, `confirming`, `refused`, `hide`, `disable`, `installing`, `restart`, `retry` |
 | `onInstalled` | none | Runs after a verified install, or on the first request when the packages already exist; a returned handler takes over `base` |
-| `confirm` | `y/N` in the terminal | Gets `{ packages, command, request }` before each install the panel asks for; return `true` to allow it. Refuses when stdin is not a TTY |
+| `onConfirm` | `y/N` in the terminal | Gets `{ packages, command, request }` before each install the panel asks for; return `true` to allow it. Refuses when stdin is not a TTY |
 
 | Route | Serves |
 | --- | --- |
 | `GET <base>embedded.js` | the floating button, a self-contained ES module |
 | `GET <base>__onboard/status` | `{ state, command, branding, messages, error? }` |
-| `POST <base>__onboard/install` | waits for `confirm`, then starts the install (`202`) or refuses it (`403`); same-origin only |
+| `POST <base>__onboard/install` | waits for `onConfirm`, then starts the install (`202`) or refuses it (`403`); same-origin only |
 | `POST <base>__onboard/disable` | writes the state file (`204`), same-origin only |
 
 | `state` | Meaning |

packages/hub-ui-onboard/src/diagnostics.ts

@@ -35,7 +35,7 @@ export const diagnostics = defineDiagnostics({
     },
     DF9006: {
       why: (p: { command: string }) => `A browser asked to run \`${p.command}\`, but no interactive terminal can confirm it. The install was refused.`,
-      fix: 'Run the command yourself, or pass a `confirm` function to `createOnboarding()`.',
+      fix: 'Run the command yourself, or pass an `onConfirm` function to `createOnboarding()`.',
     },
   },
 })

packages/hub-ui-onboard/src/index.ts

@@ -195,14 +195,14 @@ export function createOnboarding(options: CreateOnboardingOptions): Onboarding {
 
   // The dev server can be reachable from other devices, and a non-browser
   // request can send any `Origin`. So the developer allows each install.
-  const confirm = options.confirm ?? (({ command }) => confirmInTerminal(command))
+  const onConfirm = options.onConfirm ?? (({ command }) => confirmInTerminal(command))
   let asking: Promise<boolean> | undefined
 
   async function startInstall(request: Request): Promise<Response> {
     if (state !== 'idle' && state !== 'error')
       return new Response(null, { status: 202 })
     asking ??= commandLine()
-      .then(command => confirm({ packages: plan.packages, command, request }))
+      .then(command => onConfirm({ packages: plan.packages, command, request }))
       .finally(() => {
         asking = undefined
       })

packages/hub-ui-onboard/src/terminal-confirm.ts

@@ -4,7 +4,7 @@ import process from 'node:process'
 import { diagnostics } from './diagnostics'
 
 /**
- * The default `confirm`: a `y/N` question in the terminal that runs the dev
+ * The default `onConfirm`: a `y/N` question in the terminal that runs the dev
  * server. Without an interactive terminal nobody can answer, so it refuses.
  */
 export function confirmInTerminal(command: string[], input: Readable & { isTTY?: boolean } = process.stdin): Promise<boolean> {

packages/hub-ui-onboard/src/types.ts

@@ -17,9 +17,9 @@ export interface OnboardingMessages {
   /** Short sentence under the heading. */
   description: string
   install: string
-  /** Install button label while `confirm` waits for the developer. */
+  /** Install button label while `onConfirm` waits for the developer. */
   confirming: string
-  /** Shown when `confirm` refused the install. */
+  /** Shown when `onConfirm` refused the install. */
   refused: string
   /** Hides the button for this browser tab (`sessionStorage`). */
   hide: string
@@ -34,7 +34,7 @@ export interface OnboardingMessages {
 /** A web-standard request handler the hub exposes once installed. */
 export type OnboardingHandler = (request: Request) => Response | Promise<Response>
 
-/** What `confirm` receives when the panel asks to install. */
+/** What `onConfirm` receives when the panel asks to install. */
 export interface OnboardingConfirmation {
   /** The packages Install adds, as given in `packages`. */
   packages: string[]
@@ -71,7 +71,7 @@ export interface CreateOnboardingOptions {
    * Default: a `y/N` question in the terminal, or a refusal when stdin is
    * not a TTY.
    */
-  confirm?: (confirmation: OnboardingConfirmation) => boolean | Promise<boolean>
+  onConfirm?: (confirmation: OnboardingConfirmation) => boolean | Promise<boolean>
 }
 
 export type OnboardingState = 'idle' | 'installing' | 'installed' | 'ready' | 'error' | 'disabled'

packages/hub-ui-onboard/test/onboarding.test.ts

@@ -108,13 +108,13 @@ describe('createOnboarding', () => {
     expect((await status(origin)).state).toBe('idle')
   })
 
-  it('installs only after `confirm` allows it', async () => {
+  it('installs only after `onConfirm` allows it', async () => {
     const asked: OnboardingConfirmation[] = []
     let allowed = false
     const origin = await serve(createOnboarding({
       cwd: tempProject(),
       packages: ['file:/nonexistent/onboard-missing'],
-      confirm: (confirmation) => {
+      onConfirm: (confirmation) => {
         asked.push(confirmation)
         return allowed
       },
@@ -140,7 +140,7 @@ describe('createOnboarding', () => {
     const onboarding = createOnboarding({
       cwd: tempProject(),
       packages: ['x'],
-      confirm: () => {
+      onConfirm: () => {
         calls++
         return new Promise(resolve => answer = resolve)
       },
@@ -155,7 +155,7 @@ describe('createOnboarding', () => {
   })
 
   it('refuses an install when no terminal can confirm it', async () => {
-    // Vitest gives its workers a piped stdin, so the default `confirm` sees no TTY.
+    // Vitest gives its workers a piped stdin, so the default `onConfirm` sees no TTY.
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
     cleanups.push(() => warn.mockRestore())
     const origin = await serve(createOnboarding({ cwd: tempProject(), packages: ['x'] }))
@@ -183,7 +183,7 @@ describe('createOnboarding', () => {
       cwd,
       packages: [`file:${FIXTURE}`],
       onInstalled: () => () => new Response('hub here'),
-      confirm: allow,
+      onConfirm: allow,
     })
     const origin = await serve(onboarding)
 
@@ -220,7 +220,7 @@ describe('createOnboarding', () => {
 
   it('reports a failed install as an error the client can retry', async () => {
     const cwd = tempProject()
-    const origin = await serve(createOnboarding({ cwd, packages: ['file:/nonexistent/onboard-missing'], confirm: allow }))
+    const origin = await serve(createOnboarding({ cwd, packages: ['file:/nonexistent/onboard-missing'], onConfirm: allow }))
     await fetch(`${origin}/__devframes/__onboard/install`, { method: 'POST', headers: { origin } })
     const final = await waitFor(() => status(origin), s => s.state === 'error')
     expect(final.error?.code).toBe('DF9001')
@@ -229,7 +229,7 @@ describe('createOnboarding', () => {
 
   it('asks for a restart when onInstalled returns nothing', async () => {
     const cwd = tempProject()
-    const origin = await serve(createOnboarding({ cwd, packages: [`file:${FIXTURE}`], dev: false, confirm: allow }))
+    const origin = await serve(createOnboarding({ cwd, packages: [`file:${FIXTURE}`], dev: false, onConfirm: allow }))
     await fetch(`${origin}/__devframes/__onboard/install`, { method: 'POST', headers: { origin } })
     const final = await waitFor(() => status(origin), settled)
     expect(final.state).toBe('installed')

tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts

@@ -11,7 +11,7 @@ export interface CreateOnboardingOptions {
   branding?: OnboardingBranding;
   messages?: Partial<OnboardingMessages>;
   onInstalled?: () => void | OnboardingHandler | Promise<void | OnboardingHandler>;
-  confirm?: (_: OnboardingConfirmation) => boolean | Promise<boolean>;
+  onConfirm?: (_: OnboardingConfirmation) => boolean | Promise<boolean>;
 }
 export interface Onboarding {
   handler: OnboardingHandler;