@devframes/hub-ui-onboard 1.2.4 → 1.2.6

package/dist/client/embedded.js

@@ -119,10 +119,14 @@ function p(e) {
 		U(e), e.state === "installing" && setTimeout(() => void W(), n);
 	}
 	async function G() {
+		if (P.disabled = !0, I.textContent = h.confirming, !(await i("install", { method: "POST" })).ok) {
+			await W(), N.hidden = !1, N.textContent = h.refused;
+			return;
+		}
 		U({
 			...e,
 			state: "installing"
-		}), await i("install", { method: "POST" }), await W();
+		}), await W();
 	}
 	async function K() {
 		(await i("disable", { method: "POST" })).ok && t.remove();

package/dist/index.d.mts

@@ -19,6 +19,10 @@ interface OnboardingMessages {
   /** Short sentence under the heading. */
   description: string;
   install: string;
+  /** Install button label while `onConfirm` waits for the developer. */
+  confirming: string;
+  /** Shown when `onConfirm` refused the install. */
+  refused: string;
   /** Hides the button for this browser tab (`sessionStorage`). */
   hide: string;
   /** Writes the state file; the host stops injecting the button. */
@@ -30,6 +34,15 @@ interface OnboardingMessages {
 }
 /** A web-standard request handler the hub exposes once installed. */
 type OnboardingHandler = (request: Request) => Response | Promise<Response>;
+/** What `onConfirm` receives when the panel asks to install. */
+interface OnboardingConfirmation {
+  /** The packages Install adds, as given in `packages`. */
+  packages: string[];
+  /** The exact command Install runs. */
+  command: string[];
+  /** The panel's request, for example to read its `Origin` or `User-Agent`. */
+  request: Request;
+}
 interface CreateOnboardingOptions {
   /** Packages to install when the user clicks Install. Package specs as the package manager accepts them. */
   packages: string[];
@@ -50,6 +63,15 @@ interface CreateOnboardingOptions {
    * user to restart the dev server.
    */
   onInstalled?: () => void | OnboardingHandler | Promise<void | OnboardingHandler>;
+  /**
+   * Ask the developer to allow an install that the panel requested; the
+   * dev server can be reachable from other devices. Return `true` to run
+   * it. Only one call is open at a time: clicks meanwhile share its answer.
+   * Default: a `y/N` question in the terminal. It refuses at once when stdin
+   * is not a TTY or another reader holds it in raw mode, and after 5 minutes
+   * without an answer.
+   */
+  onConfirm?: (confirmation: OnboardingConfirmation) => boolean | Promise<boolean>;
 }
 type OnboardingState = 'idle' | 'installing' | 'installed' | 'ready' | 'error' | 'disabled';
 /** The `GET <base>__onboard/status` body. */
@@ -90,4 +112,4 @@ export declare function defaultMessages(productName: string): OnboardingMessages
  */
 export declare function createOnboarding(options: CreateOnboardingOptions): Onboarding;
 //#endregion
-export type { CreateOnboardingOptions, Onboarding, OnboardingBranding, OnboardingHandler, OnboardingLogo, OnboardingMessages, OnboardingState, OnboardingStatus };
+export type { CreateOnboardingOptions, Onboarding, OnboardingBranding, OnboardingConfirmation, OnboardingHandler, OnboardingLogo, OnboardingMessages, OnboardingState, OnboardingStatus };

package/dist/index.mjs

@@ -38,6 +38,22 @@ const diagnostics = defineDiagnostics({
 		DF9004: {
 			why: (p) => `The onboarding state file ${p.file} could not be read or written.`,
 			fix: "Make sure that `stateDir` is writable, or point it at another directory."
+		},
+		DF9005: {
+			why: (p) => `A browser asked to run \`${p.command}\`. Type y and press Enter within ${p.minutes} minutes to allow it.`,
+			fix: "If you did not click Install, press Enter to refuse. Another device can reach this dev server, so bind it to localhost."
+		},
+		DF9006: {
+			why: (p) => `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 an `onConfirm` function to `createOnboarding()`."
+		},
+		DF9007: {
+			why: (p) => `A browser asked to run \`${p.command}\`, but another program reads this terminal key by key, so it cannot show the question. The install was refused.`,
+			fix: "Run the command yourself. If a CLI owns the terminal, pass an `onConfirm` function to `createOnboarding()` that asks through that CLI."
+		},
+		DF9008: {
+			why: (p) => `Nobody allowed \`${p.command}\` within ${p.minutes} minutes. The install was refused.`,
+			fix: "Click Install again and answer in the terminal that runs the dev server. If the answer does not arrive, another program reads that terminal: pass an `onConfirm` function to `createOnboarding()`."
 		}
 	}
 });
@@ -94,6 +110,46 @@ function packageName(spec) {
 	return /^((?:@[\w.~-]+\/)?[\w.~-]+)(?:@[^/]*)?$/.exec(spec)?.[1];
 }
 //#endregion
+//#region src/terminal-confirm.ts
+const ANSWER_MINUTES = 5;
+/**
+* The default `onConfirm`: a `y/N` question in the terminal that runs the dev
+* server. When nobody can answer it, it refuses.
+*/
+function confirmInTerminal(command, input = process.stdin) {
+	const line = command.join(" ");
+	if (!input.isTTY) {
+		diagnostics.DF9006({ command: line });
+		return Promise.resolve(false);
+	}
+	if (input.isRaw) {
+		diagnostics.DF9007({ command: line });
+		return Promise.resolve(false);
+	}
+	diagnostics.DF9005({
+		command: line,
+		minutes: ANSWER_MINUTES
+	});
+	const flowing = input.readableFlowing;
+	return new Promise((resolve) => {
+		const timer = setTimeout(() => {
+			diagnostics.DF9008({
+				command: line,
+				minutes: ANSWER_MINUTES
+			});
+			settle(false);
+		}, ANSWER_MINUTES * 6e4);
+		const onData = (chunk) => settle(/^y(?:es)?$/i.test(String(chunk).trim()));
+		function settle(allowed) {
+			clearTimeout(timer);
+			input.off("data", onData);
+			if (!flowing) input.pause();
+			resolve(allowed);
+		}
+		input.on("data", onData);
+	});
+}
+//#endregion
 //#region src/index.ts
 const STATE_FILE = "hub-ui-onboard.json";
 /** `devframes` → `/devframes/`, same rule as `normalizeHubBase` in `@devframes/hub`. */
@@ -115,6 +171,8 @@ function defaultMessages(productName) {
 		title: productName,
 		description: `${productName} enables development features in your project. Install it with:`,
 		install: `Install ${productName}`,
+		confirming: "Confirm in your terminal...",
+		refused: "The dev server did not allow the install. Check its terminal, or run the command above yourself.",
 		hide: "Hide in this session",
 		disable: "Disable entirely",
 		installing: "Installing...",
@@ -258,11 +316,29 @@ function createOnboarding(options) {
 		state = "disabled";
 		return new Response(null, { status: 204 });
 	}
+	const commandLine = async () => {
+		const resolved = await getCommand();
+		return [resolved.command, ...resolved.args];
+	};
+	const onConfirm = options.onConfirm ?? (({ command }) => confirmInTerminal(command));
+	let asking;
+	async function startInstall(request) {
+		if (state !== "idle" && state !== "error") return new Response(null, { status: 202 });
+		asking ??= commandLine().then((command) => onConfirm({
+			packages: plan.packages,
+			command,
+			request
+		})).finally(() => {
+			asking = void 0;
+		});
+		if (!await asking) return new Response(null, { status: 403 });
+		if (state === "idle" || state === "error") install();
+		return new Response(null, { status: 202 });
+	}
 	async function status() {
-		const command = await getCommand();
 		return {
 			state,
-			command: [command.command, ...command.args],
+			command: await commandLine(),
 			branding,
 			messages,
 			error
@@ -281,9 +357,7 @@ function createOnboarding(options) {
 		if (route === "GET __onboard/status") return json(await status());
 		if (route === "POST __onboard/install" || route === "POST __onboard/disable") {
 			if (!isSameOrigin(request)) return new Response(null, { status: 403 });
-			if (route.endsWith("disable")) return disable();
-			if (state === "idle" || state === "error") install();
-			return new Response(null, { status: 202 });
+			return route.endsWith("disable") ? disable() : startInstall(request);
 		}
 		return new Response(null, { status: 404 });
 	};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@devframes/hub-ui-onboard",
   "type": "module",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "A tiny stand-in for the devframe hub UI: a floating button that installs it on demand.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",