fix(hub-ui-onboard): confirm installs in the terminal through a configurable hook

Author: antfubot

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

@@ -15,12 +15,10 @@ A hub UI provider, its Vue runtime, and the devframes it mounts add tens of mega
 
 The button sits at the bottom left, dimmed until hovered. It opens a panel with the product name and logo, one sentence, the exact command the install will run (for example `pnpm add -D @nuxt/devtools`), and three actions:
 
-- **Install** runs the command in the project. The panel shows progress, then either the real dock replaces the button in place, or the panel asks for a restart.
+- **Install** runs the command in the project after the developer allows it in the terminal (below). The panel shows progress, then either the real dock replaces the button in place, or the panel asks for a restart.
 - **Hide for now** removes the button for the current browser tab.
 - **Disable entirely** writes a state file so the host stops injecting the button on every later start.
 
-Install and Disable entirely first ask for a 6-digit code that the dev server prints in the terminal (below).
-
 The panel follows the shared design tokens, the host's `primaryColor`, and the user's hub color scheme, so the swap to the real dock looks like one product.
 
 ## Create the onboarding
@@ -43,15 +41,28 @@ const onboarding = createOnboarding({
 
 `packages` are package specs as the package manager accepts them. The package manager comes from the lockfile (`npm`, `pnpm`, `yarn`, `bun`, `deno`), `dev: true` adds `-D`, and `cwd` (default `process.cwd()`) is the project that receives the dependency. In a workspace, point `cwd` at the package that runs the dev server. The packages are fixed at creation.
 
-## Confirm with the terminal code
+## Confirm the install
+
+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. By default, the onboarding asks in the terminal that runs the dev server:
+
+1. The user clicks Install. The panel shows "Confirm in your terminal..." and its request waits.
+2. The terminal prints [DF9005](/errors/DF9005). The developer types `y` and presses Enter to allow the install. Any other answer refuses it.
+3. The install runs. After a refusal, the panel says that the dev server did not allow the install.
 
-Install and Disable entirely change the project, and a dev server can listen on the network. So the onboarding accepts them only from a person who can read the terminal:
+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.
 
-1. The first `POST` from the panel has no code. The onboarding prints [DF9005](/errors/DF9005) with a 6-digit code and answers `401`.
-2. The panel shows a field for the code. The user types it, and the panel sends it again in the `x-devframes-onboard-code` header.
-3. After five wrong codes, both actions answer `429` with [DF9006](/errors/DF9006) until the dev server restarts.
+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`:
+
+```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' }),
+})
+```
 
-The code stays the same for the life of the process, so Retry after a failed install does not ask again. A `POST` from another origin is also refused with `403`. The host has nothing to configure.
+Disable entirely does not ask. It changes only the state file in `node_modules/.devframe`.
 
 ## Hand the base to the hub
 

docs/content/6.errors/DF9005.md

@@ -1,20 +1,22 @@
 ---
-title: 'DF9005: Onboarding Code Requested'
-description: 'A browser asked to {action}. To allow it, enter this code in the panel: {code}'
+title: 'DF9005: Confirm the Install'
+description: 'A browser asked to run `{command}`. Type y and press Enter to allow it.'
 ---
 
 ## Message
 
-> A browser asked to `{action}`. To allow it, enter this code in the panel: `{code}`
+> A browser asked to run `{command}`. Type y and press Enter to allow it.
 
 ## Cause
 
-Install and Disable change the project, and a dev server can listen on the network. So the onboarding panel must send a 6-digit code that only the terminal shows. A request to `POST <base>__onboard/install` or `POST <base>__onboard/disable` came without the `x-devframes-onboard-code` header, and `createOnboarding()` printed the code. The code stays the same until the process exits.
+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.
 
 ## Fix
 
-If you clicked Install or Disable entirely, type the code into the panel. If you did not, another device or page can reach this dev server. Do not enter the code anywhere, and bind the dev server to `localhost`.
+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()`.
 
 ## Source
 
-- [`packages/hub-ui-onboard/src/index.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/index.ts): `authorize()` prints this and answers with status 401 when the request has no code.
+- [`packages/hub-ui-onboard/src/terminal-confirm.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/terminal-confirm.ts): `confirmInTerminal()` prints this, then reads one line from stdin.

docs/content/6.errors/DF9006.md

@@ -1,20 +1,20 @@
 ---
-title: 'DF9006: Too Many Wrong Onboarding Codes'
-description: 'Five wrong onboarding codes were entered. Install and Disable are blocked until the dev server restarts.'
+title: 'DF9006: No Terminal to Confirm the Install'
+description: 'A browser asked to run `{command}`, but no interactive terminal can confirm it. The install was refused.'
 ---
 
 ## Message
 
-> Five wrong onboarding codes were entered. Install and Disable are blocked until the dev server restarts.
+> A browser asked to run `{command}`, but no interactive terminal can confirm it. The install was refused.
 
 ## Cause
 
-Install and Disable need the code that [DF9005](/errors/DF9005) prints. After five wrong codes, `createOnboarding()` refuses both actions for the rest of the process, so nobody can guess the code.
+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.
 
 ## Fix
 
-Restart the dev server. It prints a new code the next time you click Install or Disable entirely. If you did not enter the wrong codes, another device or page can reach this dev server: bind it to `localhost`. You can also run the install command from the panel in a terminal.
+Run the command from the panel in a terminal yourself. Or pass a `confirm` function to `createOnboarding()` that asks in another way.
 
 ## Source
 
-- [`packages/hub-ui-onboard/src/index.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/index.ts): `authorize()` reports this on the fifth wrong code, then answers each later Install or Disable with status 429 and this code.
+- [`packages/hub-ui-onboard/src/terminal-confirm.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/terminal-confirm.ts): `confirmInTerminal()` reports this and returns `false` when stdin is not a TTY.

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

@@ -96,17 +96,16 @@ What `createOnboarding()` from `@devframes/hub-ui-onboard` accepts and serves: [
 | `stateDir` | `<cwd>/node_modules/.devframe` | Directory of the `hub-ui-onboard.json` state file |
 | `dev` | `true` | Install as a devDependency |
 | `branding` | `{}` | `productName` (default `Devframes`), `logo` (URL or `{ light, dark }`), `primaryColor` |
-| `messages` | derived from `productName` | Overrides for `title`, `description`, `install`, `code`, `wrongCode`, `hide`, `disable`, `installing`, `restart`, `retry` |
+| `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 |
 
 | 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` | starts the install (`202`), with the terminal code only |
-| `POST <base>__onboard/disable` | writes the state file (`204`), with the terminal code only |
-
-Both `POST` routes answer `403` to another origin. Without the `x-devframes-onboard-code` header, they print the code ([DF9005](/errors/DF9005)) and answer `401`. A wrong code also gets `401`. After five wrong codes, they answer `429` with [DF9006](/errors/DF9006) until the process restarts.
+| `POST <base>__onboard/install` | waits for `confirm`, 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 |
 | --- | --- |

examples/hub-onboard-vite/README.md

@@ -6,14 +6,12 @@ A Vite host that ships only `@devframes/hub-ui-onboard` (about 20 kB in the brow
 pnpm --filter hub-onboard-vite dev
 ```
 
-Open the printed URL. The button at the bottom left opens a panel with three actions:
+Open the printed URL. The button at the bottom left opens a panel with two actions:
 
-- Install runs `pnpm add -D @devframes/hub @devframes/hub-ui @devframes/plugin-git` in this directory. When it finishes, the host starts the real hub on `/__devframes/` in the same process and the button swaps itself for the floating dock.
+- Install asks you to type `y` in the terminal that runs Vite, then runs `pnpm add -D @devframes/hub @devframes/hub-ui @devframes/plugin-git` in this directory. When it finishes, the host starts the real hub on `/__devframes/` in the same process and the button swaps itself for the floating dock.
 - Hide for now hides the button for this browser tab.
 - Disable entirely writes `node_modules/.devframe/hub-ui-onboard.json`. The host reads `onboarding.disabled` on the next start and injects no script.
 
-Install and Disable entirely ask for the 6-digit code that the dev server prints in the terminal (`DF9005`).
-
 When the three packages are already installed, the button never shows: the host's `onInstalled` runs on the first request and the real dock appears directly.
 
 Install changes this example's `package.json` and the lockfile. Run `git checkout -- examples/hub-onboard-vite pnpm-lock.yaml` and delete the state file to reset the demo.

packages/hub-ui-onboard/playground/index.html

@@ -14,14 +14,15 @@
   </head>
   <body>
     <h1>hub-ui-onboard</h1>
-    <p>The floating button loads from <code>src/client</code> and talks to a mock <code>__onboard</code> API. When Install or Disable asks for the terminal code, enter <code>123456</code>.</p>
+    <p>The floating button loads from <code>src/client</code> and talks to a mock <code>__onboard</code> API.</p>
     <fieldset>
       <legend>State</legend>
       <button data-state="idle">idle</button>
       <button data-state="installing">installing</button>
       <button data-state="installed">installed</button>
       <button data-state="error">error</button>
       <button data-state="idle" data-outcome="error">idle (install fails)</button>
+      <button data-state="idle" data-outcome="refused">idle (install refused)</button>
     </fieldset>
     <fieldset>
       <legend>Theme</legend>

packages/hub-ui-onboard/playground/vite.config.ts

@@ -4,22 +4,20 @@ import { spawn } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { defineConfig } from 'vite'
 import { defaultMessages } from '../src/index'
-import { CODE_HEADER } from '../src/protocol'
 
 const root = fileURLToPath(new URL('..', import.meta.url))
 const productName = 'Devframes'
-const MOCK_CODE = '123456'
 
 /**
  * A fake of the `__onboard/*` routes `createOnboarding` serves. The client
  * resolves them next to its own module (`/src/client/`). The playground page
- * picks the state through `/__mock/state`; Install runs a timer instead of a
- * package manager and ends in `installed` or `error`. Install and Disable
- * accept only the code `123456`.
+ * picks the state through `/__mock/state`; Install waits as if the developer
+ * answered in the terminal, then is refused, or runs a timer instead of a
+ * package manager and ends in `installed` or `error`.
  */
 function mockOnboarding(): Plugin {
   let state: OnboardingState = 'idle'
-  let outcome: 'installed' | 'error' = 'installed'
+  let outcome: 'installed' | 'error' | 'refused' = 'installed'
   let timer: ReturnType<typeof setTimeout> | undefined
 
   const status = (): OnboardingStatus => ({
@@ -43,23 +41,28 @@ function mockOnboarding(): Plugin {
         if (url.pathname === '/__mock/state') {
           clearTimeout(timer)
           state = (url.searchParams.get('state') ?? 'idle') as OnboardingState
-          outcome = url.searchParams.get('outcome') === 'error' ? 'error' : 'installed'
+          const requested = url.searchParams.get('outcome')
+          outcome = requested === 'error' || requested === 'refused' ? requested : 'installed'
           return send({ state, outcome })
         }
         if (!url.pathname.startsWith('/src/client/__onboard/'))
           return next()
         const route = url.pathname.split('/').pop()
-        if (route !== 'status' && req.headers[CODE_HEADER] !== MOCK_CODE) {
-          res.statusCode = 401
-          return res.end()
-        }
         if (route === 'install') {
-          state = 'installing'
-          timer = setTimeout(() => (state = outcome), 2500)
+          setTimeout(() => {
+            if (outcome === 'refused') {
+              res.statusCode = 403
+              return res.end()
+            }
+            const end = outcome
+            state = 'installing'
+            timer = setTimeout(() => (state = end), 2500)
+            send({ ok: true })
+          }, 1500)
+          return
         }
-        else if (route === 'disable') {
+        if (route === 'disable')
           state = 'disabled'
-        }
         send(route === 'status' ? status() : { ok: true })
       })
     },

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

@@ -1,5 +1,4 @@
 import type { OnboardingBranding, OnboardingStatus } from '../types'
-import { CODE_HEADER } from '../protocol'
 import css from './.generated/css'
 import { DEVFRAME_LOGO } from './logo'
 
@@ -190,32 +189,9 @@ function mount(initial: OnboardingStatus): void {
   commandRow.className = 'devframes-onboard-command-row'
   commandRow.append(command, copy)
 
-  // Shown when the server asks for the code it printed in the terminal.
-  // A form, so Enter repeats the action that asked for it.
-  let pending: 'install' | 'disable' = 'install'
-  const codeForm = document.createElement('form')
-  codeForm.hidden = true
-  const codeField = document.createElement('label')
-  codeField.className = 'flex flex-col gap-1 text-xs color-muted'
-  const codeInput = document.createElement('input')
-  codeInput.className = 'devframes-onboard-code'
-  codeInput.inputMode = 'numeric'
-  codeInput.autocomplete = 'one-time-code'
-  codeInput.maxLength = 6
-  codeField.append(messages.code, codeInput)
-  codeForm.append(codeField)
-  codeForm.addEventListener('submit', (event) => {
-    event.preventDefault()
-    void (pending === 'install' ? startInstall() : disableDevtools())
-  })
-
   const note = document.createElement('p')
-  note.className = 'm-0 text-xs text-red-600 dark:text-red-400'
+  note.className = 'm-0 text-xs'
   note.hidden = true
-  const showNote = (text: string) => {
-    note.hidden = !text
-    note.textContent = text
-  }
 
   const install = button('btn-primary text-sm justify-center gap-1', messages.install, () => void startInstall())
   // The spinner takes its space from the line height, so the button keeps its size.
@@ -237,7 +213,7 @@ function mount(initial: OnboardingStatus): void {
   actions.className = 'flex flex-col gap-2'
   actions.append(secondary, install)
 
-  panel.append(heading, description, commandRow, codeForm, note, actions)
+  panel.append(heading, description, commandRow, note, actions)
   scheme.append(glow, pill, panel)
 
   let open = false
@@ -270,7 +246,11 @@ function mount(initial: OnboardingStatus): void {
       : state === 'installed'
         ? messages.restart
         : state === 'error' ? messages.retry : messages.install
-    showNote(state === 'error' ? `${status.error?.code}: ${status.error?.message}` : '')
+    note.hidden = state !== 'error'
+    note.className = 'm-0 text-xs text-red-600 dark:text-red-400'
+    note.textContent = state === 'error'
+      ? `${status.error?.code}: ${status.error?.message}`
+      : ''
   }
 
   async function poll(): Promise<void> {
@@ -285,38 +265,24 @@ function mount(initial: OnboardingStatus): void {
       setTimeout(() => void poll(), POLL_MS)
   }
 
-  /** POST `action` with the entered code; `true` when the server accepted it. */
-  async function send(action: typeof pending): Promise<boolean> {
-    pending = action
-    // Kept after success, so Retry does not ask again.
-    const code = codeInput.value.trim()
-    const response = await api(action, { method: 'POST', headers: code ? { [CODE_HEADER]: code } : {} })
-    if (response.status === 401) {
-      showNote(code ? messages.wrongCode : '')
-      codeInput.value = ''
-      codeForm.hidden = false
-      codeInput.focus()
-      return false
-    }
-    if (!response.ok) {
-      // A `DF90xx` body: too many wrong codes, or the state file failed.
-      const error: OnboardingStatus['error'] = await response.json().catch(() => undefined)
-      showNote(error ? `${error.code}: ${error.message}` : '')
-      return false
-    }
-    codeForm.hidden = true
-    return true
-  }
-
   async function startInstall(): Promise<void> {
-    if (!await send('install'))
+    // The request stays open until the developer answers in the terminal.
+    install.disabled = true
+    installLabel.textContent = messages.confirming
+    const response = await api('install', { method: 'POST' })
+    if (!response.ok) {
+      await poll()
+      note.hidden = false
+      note.textContent = messages.refused
       return
+    }
     render({ ...initial, state: 'installing' })
     await poll()
   }
 
   async function disableDevtools(): Promise<void> {
-    if (await send('disable'))
+    const response = await api('disable', { method: 'POST' })
+    if (response.ok)
       host.remove()
   }
 

packages/hub-ui-onboard/src/client/style.css

@@ -57,11 +57,6 @@
   --uno: transition-opacity duration-200;
 }
 
-.devframes-onboard-code {
-  --uno: w-full min-w-0 rounded border border-base bg-base color-base px-2.5 py-1 font-mono text-sm tabular-nums tracking-widest;
-  --uno: outline-none transition focus-visible:border-active focus-visible:ring-2 ring-primary-400;
-}
-
 .devframes-onboard-spinner[hidden] {
   --uno: hidden;
 }