qbit-tools/README.md

QQQ Tools

A first-class Tools app for discovering, installing and connecting QQQ companion applications. It covers the CLI and terminal UI, Android scanners, and the Windows Print Client. The compatible Next admin frontend also places a shortcut to the same app in the account menu.

Tools is an application Qbit, with no database, background jobs or credential store. It uses the existing metadata and widget APIs. Printing and scanner administration remain in their respective apps.

Install in a host

Requires Java 21, QQQ 4.1.0-RC.21, and a Next frontend containing the QQQ_TOOLS renderer. The compatible frontend change is Next PR 204. Release preparation and publication status are tracked in RELEASING.md; older Next and Material builds do not support this widget.

<dependency>
   <groupId>com.kingsrook.qbits</groupId>
   <artifactId>qbit-tools</artifactId>
   <version>0.1.0-SNAPSHOT</version>
</dependency>

Register during instance construction:

new ToolsQBitProducer()
   .withServerUrl("https://your-qqq.example.com")
   .produce(instance, "tools");

Import com.kingsrook.qbits.tools.ToolsQBitProducer. The public URL is the server root, including any reverse-proxy prefix, without /qqq/v1. It must be a public HTTPS URL without credentials, query parameters or a fragment. When omitted, the frontend derives the root from its configured API address; ambiguous addresses show an administrator-help message instead of an incorrect command. Loopback HTTP is identified as local development and unsuitable for other devices.

Optionally call .withScannerDownloadUrl("https://your-downloads.example.com/scanners") with the approved APK or managed distribution page. By default, the scanner links to the signed 1.0.0 preview release (forge sign-in required). USB scripts install that exact preview; an organization-specific download override does not change their pinned artifact. The product's published scanner status must not be represented as a general production app-store release.

The app name is qqqTools; its widget is qqqToolsCatalog. Hosts can apply their ordinary QQQ permission rules to those metadata entries. The account shortcut derives from visible app/widget metadata rather than a hardcoded route or label. Management links derive from the user's visible navigation tree. Access to Tools never grants device or print-job permissions.

User experience

• Tools appears in normal navigation and the account menu, with one destination.
• Supported tools appear first. Unavailable services appear under a collapsed More tools section with an explanation, without download or setup actions.
• CLI/TUI is always offered. Scanner availability follows the installed mobileDevice table; printing follows the installed printing app. Detection happens when rendering, so producer registration order does not matter.
• A compact chooser keeps all available tools visible. The selected tool opens a shared setup panel with installation and connection guidance.
• Platform and method selectors expose copyable CLI/TUI Scoop (Windows), Homebrew (macOS/Linux), and curl (macOS/Linux) install commands. Print Client includes a complete PowerShell installer; scanner setup includes Windows/macOS/Linux USB install scripts and direct Android instructions. Only actually supported methods are offered.
• Long commands scroll horizontally; multiline scripts retain newlines, have bounded previews, and offer a prominent Copy install script action.
• The instance address and CLI sign-in commands are copyable. Failed clipboard access leaves selectable text and an explicit recovery message.
• Existing scanner approval and print enrollment flows remain authoritative. No tokens, credentials or newly invented QR/deep-link protocol are embedded in this page.
• Installer scripts pin reviewed releases: Print Client 1.0.1 (checksum and signed publisher verification), and scanner preview 1.0.0 (pinned APK SHA-256). Update the scripts when adopting a newer release. Android scripts obtain adb from the official Google Platform Tools distribution, open the authenticated release page, and ask for the downloaded APK before USB installation. They never uninstall or reset a device to bypass signature mismatches. See https://developer.android.com/tools/releases/platform-tools for prerequisites. Printer/CLI links follow the distribution channels documented by their projects.

Verify

.\mvnw.cmd verify

Use ./mvnw verify on Unix. Verification includes the shared Kingsrook Checkstyle configuration and catalog/registration tests. The serialization test writes target/tools-catalog.json; the Next browser tests consume a checked-in copy of this public example fixture at tests/e2e/fixtures/tools-catalog.json.

In the sibling Next repository run its typecheck, lint, src/components/tools/ToolsWidget.test.tsx, widget dispatcher tests, and tests/e2e/tools.spec.ts. Browser tests use isolated mocked API responses, not a live customer's devices or server.

Publication, host dependency adoption, and deploying the matching frontend are separate release steps. No existing running server is changed by building this library.