Skip to content

feat: automation with controlfs:// protocol links and command-line flags - #277

Merged
nextestudios merged 1 commit into
mainfrom
feature/automation-protocol
Sep 30, 2026
Merged

nextestudios merged 1 commit into
mainfrom
feature/automation-protocol

Conversation

@lippdev

@lippdev lippdev commented Sep 30, 2026

Copy link
Copy Markdown
Collaborator

Adds automation support for launching, focusing, and cleanly closing ControlFS via custom URI protocol links (\controlfs://start, \controlfs://stop, \controlfs://show) and command-line arguments (--start, --stop, --show, --close). This enables seamless integration between external tools such as Console Mode, Stream Deck buttons, and user automation scripts:

  • Protocol & CLI Parsing (\ControlFS.Core.Automation.AppProtocol):
    • Pure parsing logic for \controlfs://start\ (alias \open), \controlfs://stop\ (aliases \close, \quit), and \controlfs://show.
    • Handles CLI flags: --start, --open, --stop, --close, --quit, --show.
    • Tolerant to trailing slashes, query parameters, fragments, and case variations.
  • Single-Instance Coordination (\ControlFS.Infrastructure.Windows.Automation):
    • Enforces a single instance per Windows user session via named mutex \Local\ControlFS.Instance.
    • Passing --render-screens\ bypasses single-instance checks so smoke runs are completely unaffected.
    • If already running: \controlfs://start, \controlfs://show\ or running \ControlFS.exe\ signals the active instance to restore from minimized and bring itself to foreground (\Local\ControlFS.Show\ + Win32 \BringToForeground), exiting the new process immediately without starting WinUI.
    • Invoking \controlfs://stop\ or \ControlFS.exe --stop\ cleanly signals \Local\ControlFS.Close, canceling any active operations and saving settings via \AppController.RequestAutomationExit(). If nothing is running, exits cleanly.
  • Protocol Registration (\ControlFS.Infrastructure.Windows.Shell.ProtocolRegistration\ & \�uild/ControlFS.iss):
    • Registers \HKCU\Software\Classes\controlfs\ with \URL Protocol\ and \shell\open\command\ in Inno Setup.
    • Dynamic runtime registration ensures portable builds and path moves update the registry automatically.
  • Tests:
    • 47 new unit tests in \AppProtocolTests\ covering URI formats, CLI flags, query strings, case tolerance, and invalid URLs.
    • Windows integration tests in \ProtocolRegistrationIntegrationTests\ and \SingleInstanceIntegrationTests\ verifying registry writing and inter-process event signaling (\Show/\Close).
  • Docs & Changelogs:
    • Updated \README.md\ and \README.pt-BR.md.
    • Added Automation section to \docs/GUIDE.md\ and \docs/GUIDE.pt-BR.md.
    • Added checklist items in \docs/TESTING.md.
    • Updated \CHANGELOG.md\ and \CHANGELOG.en-US.md\ under ## [Unreleased].

@nextestudios
nextestudios merged commit 9bf5d29 into main Sep 30, 2026
3 checks passed
@nextestudios
nextestudios deleted the feature/automation-protocol branch September 30, 2026 17:43
nextestudios added a commit that referenced this pull request Sep 30, 2026
…es no registry trace, relaunch waits for the old instance (#278)

Follow-up to #277 review.

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants