Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• README.md
• doc/design.md
• doc/faq-architectural.md
• doc/faq.md
• doc/testing.md
• package.json
• src/test/startup.test.ts

This document provides guidance for troubleshooting common issues encountered by users and developers of Ghostbird. It covers connection problems, configuration settings, and the development/debugging workflow. For architectural details that may aid in advanced troubleshooting, refer to the design documentation.

Sources: README.md, doc/faq.md

Common User Issues

This section addresses problems that users might encounter during normal use of the Ghostbird add-on.

Connection Issues

The most frequent issue is a failure to connect to the GhostText server running in the text editor. The state of the Ghostbird button in the Thunderbird compose window provides an immediate visual indicator of the connection status.

Sources: README.md:65-67

Button Status Indicators

The color of the Ghostbird button indicates the current connection state.

Button Color	Icon	Meaning
Gray	<img alt="Gray button" src="https://github.com/exteditor/ghostbird/raw/main/ext/gray.svg%22 width="24" height="24">	Initial state, disconnected.
Blue	<img alt="Blue button" src="https://github.com/exteditor/ghostbird/raw/main/ext/blue.svg%22 width="24" height="24">	Connection successful and session is active.
Red	<img alt="Red button" src="https://github.com/exteditor/ghostbird/raw/main/ext/red.svg%22 width="24" height="24">	Connection failed.

Sources: README.md:65-67

Connection Flow and Checks

When the Ghostbird button is clicked, it attempts to establish a WebSocket connection with the GhostText server. A failure typically occurs if the server is not running or is not listening on the configured port.

The following diagram illustrates the connection sequence.

This diagram shows the connection attempt from Ghostbird's background script to the GhostText server.

To troubleshoot a red button status:

1. Ensure the GhostText server is started and running in your text editor (e.g., with :GhostTextStart in Vim).
2. Verify the server is listening on the correct port (default is 4001). This can be configured in Ghostbird's options.
3. Check for firewall rules that might be blocking the connection on localhost.

Sources: README.md:63-67, doc/faq.md:28-30, doc/design.md:38-55

HTML vs. Plain Text Mode

Ghostbird's behavior can be affected by Thunderbird's composition format settings. If you are experiencing issues with the text format, you may need to adjust your account settings.

• Problem: The editing mode (HTML or Plain Text) is not what you expect.
• Solution: In recent Thunderbird versions, the composition format cannot be switched after an email is started. You must set it beforehand in Account Settings > Composition & Addressing. Check or uncheck the Compose messages in HTML format option and then start a new message.

This setting is per-account and determines the format you see while composing, as opposed to the profile-wide "Sending Format" which determines what the recipient sees.

Sources: doc/faq.md:35-52

Developer Troubleshooting

This section is for developers contributing to Ghostbird and covers debugging, build issues, and testing.

Setting up the Debug Environment

A typical debugging workflow involves building the extension, loading it into Thunderbird, and making changes.

The following diagram outlines the debugging process.

This diagram shows the iterative development cycle for debugging Ghostbird.

Key steps for debugging:

1. Copy .web-ext-config.example.mjs to .web-ext-config.mjs and adjust the path to your Thunderbird executable.
2. Use yarn start to launch Thunderbird with the extension temporarily loaded. This command uses web-ext run.
3. For a persistent testing environment, use the --keep-profile-changes flag with web-ext to create a dedicated testing profile.
4. VSCode can be used as a debugger. Copy .vscode/launch.example.json to .vscode/launch.json and edit paths as needed.

Sources: CONTRIBUTING.md:46-52, 80-87

Build and Test Scripts

The project uses yarn to manage dependencies and run scripts for building, testing, and formatting. These are defined in package.json.

Command	Description
yarn build	Runs checks, tests, and builds the final .xpi file in dist/.
yarn watch	Watches for source file changes and rebuilds automatically.
yarn start	Launches Thunderbird with the extension loaded for debugging.
yarn test	Runs all unit tests.
yarn test:watch	Runs tests continuously as you edit files.
yarn test:ui	Opens the Vitest UI in a browser to visualize test results.
yarn check	Checks code style and types.
yarn fix	Automatically fixes linting and formatting issues.
yarn doc	Generates API documentation.

Sources: CONTRIBUTING.md:50-78, package.json:23-53

Running Tests

The project has a suite of unit tests and a process for manual testing.

Unit Tests

• Run with yarn test.
• Test files are located in src/test/ for integration-style tests and as in-source tests within module files (if (import.meta.vitest) { ... }).
• The testing policy focuses on the core logic in src/ghosttext-session/ and src/ghosttext-runner/.
• Test results are output to the build/test/ directory. If yarn test fails, build/test/result.xml should be attached to any issue report.

Sources: doc/testing.md:3-16, CONTRIBUTING.md:49

Manual Tests

• Ensure a GhostText server is running.
• Open a compose window in Thunderbird and click the Ghostbird button.
• Perform various actions to check for expected behavior and try to break the functionality.

Sources: doc/testing.md:18-23

Architectural Issues

For complex bugs, understanding the application's architecture is crucial.

Dependency Injection and Startup

Ghostbird uses a custom dependency injection (DI) mechanism to instantiate and wire classes at startup. This is intended to improve testability and maintainability.

• Classes that should be managed by the DI container have a static isSingleton: boolean property.
• The startup logic in src/root/startup/startup_*.ts scans for these classes and instantiates them, injecting their dependencies via the constructor.
• An incorrect dependency declaration or a missing class can cause startup failures.

Sources: doc/design.md:162-192, doc/faq-architectural.md:3-6

Dependency Graph

If you suspect a problem with dependency resolution, you can inspect the generated dependency graph.

• After running yarn test, a file named build/test/dependency_tree.md is generated.
• This file contains a Mermaid diagram of the dependency graph for all auto-instantiated classes, which can be used to visualize how components are connected.
• The test test("All collected classes refers to given dependencies", ...) in src/test/startup.test.ts is responsible for generating this file.

Sources: doc/faq-architectural.md:15-17, src/test/startup.test.ts:60-66