utils/deep_link/deep_link_handler library

Deep Link Handler

Faithful port of neomage/src/utils/deepLink/*.ts Covers: parseDeepLink.ts, terminalLauncher.ts, registerProtocol.ts, protocolHandler.ts, banner.ts, terminalPreference.ts

Provides:

  • neomage-cli:// URI parsing with security validation
  • Terminal emulator detection and launch (macOS/Linux/Windows)
  • OS protocol handler registration (.app bundle, .desktop, Windows registry)
  • Deep link origin banner for security awareness
  • Terminal preference capture for deep link handling

Classes

DeepLinkAction
Parsed deep link action.
DeepLinkBannerInfo
Info needed to build the deep link origin banner.
DeepLinkController
Sint controller managing deep link state and operations.
TerminalInfo
Terminal emulator information.

Constants

appName → const String
Display name for the URL handler app.
deepLinkProtocol → const String
The custom URI protocol scheme.
desktopFileName → const String
Desktop file name for Linux registration.
failureBackoffMs → const int
Failure backoff period (24 hours).
longPrefillThreshold → const int
Long prefill threshold for banner warning.
macosAppName → const String
macOS app bundle name.
macosBundleId → const String
macOS bundle ID for the URL handler app.
maxCwdLength → const int
Maximum length for cwd parameter. PATH_MAX on Linux is 4096.
maxQueryLength → const int
Maximum length for pre-filled prompts. 5000 chars — practical ceiling considering Windows cmd.exe limits.
staleFetchWarnMs → const int
Stale FETCH_HEAD warning threshold (7 days).

Functions

Build a neomage-cli:// deep link URL.
buildDeepLinkBanner(DeepLinkBannerInfo info) → String
Build the warning banner for a deep-link-originated session.
captureTerminalPreference() → String?
Capture the current terminal from TERM_PROGRAM and return the app name. Returns null if not on macOS or TERM_PROGRAM not recognized.
detectTerminal({String? storedPreference}) → Future<TerminalInfo?>
Detect the user's preferred terminal emulator.
ensureDeepLinkProtocolRegistered() → Future<void>
Auto-register the protocol handler when missing or stale.
handleDeepLinkUri(String uri) → Future<int>
Handle an incoming deep link URI. Called from the CLI entry point when --handle-uri is passed.
isProtocolHandlerCurrent(String neomagePath) → Future<bool>
Check whether the OS-level protocol handler is current.
launchInTerminal(String neomagePath, DeepLinkAction action, {String? storedPreference}) → Future<bool>
Launch Neomage in the detected terminal emulator.
Parse a neomage-cli:// URI into a structured action. Throws FormatException if the URI is malformed or contains dangerous characters.
readLastFetchTime(String cwd) → Future<DateTime?>
Read the mtime of .git/FETCH_HEAD.
registerProtocolHandler([String? neomagePath]) → Future<void>
Register the neomage-cli:// protocol handler with the operating system.