From e411f24cf3f972a73bf9c7d6832002e3c9476bdc Mon Sep 17 00:00:00 2001 From: Cloak-HQ Date: Thu, 5 Mar 2026 07:49:08 +0100 Subject: [PATCH] feat: first-launch welcome message for all install methods MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Show welcome banner once per install (Python, JS, Docker). Uses marker file in ~/.cloakbrowser/ — resets on cache clear or update. Replaces logger.info() calls that were invisible by default. Bump to v0.3.8. --- Dockerfile | 4 +++- cloakbrowser/_version.py | 2 +- cloakbrowser/download.py | 24 +++++++++++++++++++++--- js/package.json | 2 +- js/src/download.ts | 33 ++++++++++++++++++++++++--------- 5 files changed, 50 insertions(+), 15 deletions(-) diff --git a/Dockerfile b/Dockerfile index 482fa42..5a51ab0 100644 --- a/Dockerfile +++ b/Dockerfile @@ -30,7 +30,9 @@ RUN cd js && npm install && npm run build COPY examples/ examples/ # Pre-download stealth Chromium binary during build (not at runtime) -RUN python -c "from cloakbrowser import ensure_binary; ensure_binary()" +# Remove welcome marker so users see it on first container run +RUN python -c "from cloakbrowser import ensure_binary; ensure_binary()" \ + && rm -f ~/.cloakbrowser/.welcome_shown # CLI shortcuts COPY bin/cloaktest /usr/local/bin/cloaktest diff --git a/cloakbrowser/_version.py b/cloakbrowser/_version.py index 8879c6c..4ad67eb 100644 --- a/cloakbrowser/_version.py +++ b/cloakbrowser/_version.py @@ -1 +1 @@ -__version__ = "0.3.7" +__version__ = "0.3.8" diff --git a/cloakbrowser/download.py b/cloakbrowser/download.py index 8cd8fbe..cc636c7 100644 --- a/cloakbrowser/download.py +++ b/cloakbrowser/download.py @@ -50,6 +50,25 @@ DOWNLOAD_TIMEOUT = 600.0 UPDATE_CHECK_INTERVAL = 3600 +def _show_welcome() -> None: + """Show welcome message on first launch. Uses a marker file to show only once.""" + marker = get_cache_dir() / ".welcome_shown" + if marker.exists(): + return + print() + print(" CloakBrowser — stealth Chromium for automation") + print(" https://github.com/CloakHQ/CloakBrowser") + print() + print(" Issues? https://github.com/CloakHQ/CloakBrowser/issues") + print(" Star us if CloakBrowser helps your project!") + print() + try: + marker.parent.mkdir(parents=True, exist_ok=True) + marker.write_text("") + except OSError: + pass + + def ensure_binary() -> str: """Ensure the stealth Chromium binary is available. Download if needed. @@ -77,6 +96,7 @@ def ensure_binary() -> str: if binary_path.exists() and _is_executable(binary_path): logger.debug("Binary found in cache: %s (version %s)", binary_path, effective) + _show_welcome() _maybe_trigger_update_check() return str(binary_path) @@ -146,9 +166,7 @@ def _download_and_extract(version: str | None = None) -> None: _verify_download_checksum(tmp_path, version) _extract_archive(tmp_path, binary_dir, binary_path) - logger.info("Visit https://cloakbrowser.dev for docs and release notifications.") - logger.info("Issues? https://github.com/CloakHQ/CloakBrowser/issues") - logger.info("Star us if CloakBrowser helps: https://github.com/CloakHQ/CloakBrowser") + _show_welcome() finally: # Clean up temp file tmp_path.unlink(missing_ok=True) diff --git a/js/package.json b/js/package.json index 846904b..e20713f 100644 --- a/js/package.json +++ b/js/package.json @@ -1,6 +1,6 @@ { "name": "cloakbrowser", - "version": "0.3.7", + "version": "0.3.8", "description": "Stealth Chromium that passes every bot detection test. Drop-in Playwright/Puppeteer replacement with source-level fingerprint patches.", "type": "module", "main": "dist/index.js", diff --git a/js/src/download.ts b/js/src/download.ts index 70223fc..ef41f6f 100644 --- a/js/src/download.ts +++ b/js/src/download.ts @@ -65,6 +65,7 @@ export async function ensureBinary(): Promise { const binaryPath = getBinaryPath(effective); if (fs.existsSync(binaryPath) && isExecutable(binaryPath)) { + showWelcome(); maybeTriggerUpdateCheck(); return binaryPath; } @@ -138,6 +139,28 @@ export async function checkForUpdate(): Promise { return latest; } +// --------------------------------------------------------------------------- +// Welcome message (shown once per install) +// --------------------------------------------------------------------------- + +function showWelcome(): void { + const marker = path.join(getCacheDir(), ".welcome_shown"); + if (fs.existsSync(marker)) return; + console.log(); + console.log(" CloakBrowser — stealth Chromium for automation"); + console.log(" https://github.com/CloakHQ/CloakBrowser"); + console.log(); + console.log(" Issues? https://github.com/CloakHQ/CloakBrowser/issues"); + console.log(" Star us if CloakBrowser helps your project!"); + console.log(); + try { + fs.mkdirSync(getCacheDir(), { recursive: true }); + fs.writeFileSync(marker, ""); + } catch { + // Non-fatal + } +} + // --------------------------------------------------------------------------- // Internal helpers // --------------------------------------------------------------------------- @@ -177,15 +200,7 @@ async function downloadAndExtract(version?: string): Promise { } await extractArchive(tmpPath, binaryDir, binaryPath); - console.log( - `[cloakbrowser] Visit https://cloakbrowser.dev for docs and release notifications.` - ); - console.log( - `[cloakbrowser] Issues? https://github.com/CloakHQ/CloakBrowser/issues` - ); - console.log( - `[cloakbrowser] Star us if CloakBrowser helps: https://github.com/CloakHQ/CloakBrowser` - ); + showWelcome(); } finally { // Clean up temp file if (fs.existsSync(tmpPath)) {