Add docs

LICENCE.txt

@@ -0,0 +1,26 @@
+Firefox Assistant - Alfred workflow for Firefox
+
+The MIT License (MIT)
+---------------------
+
+Copyright (c) 2020 Dean Jackson <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

README.md

@@ -1,5 +1,50 @@
+<div align="center">
+ <img src="icon.png" alt="Alfred-Firefox icon" title="Alfred-Firefox icon"/>
+</div>
+
 Alfred Firefox Assistant
 ========================
 
 Search and manipulate Firefox's bookmarks, history and tabs from Alfred.
 
+![Animated demo of workflow in use][demo]
+
+
+Installation
+------------
+
+1. Download and install the [latest version of the workflow][workflow]
+2. Install [the Firefox extension][addon]
+
+See [Setup](doc/setup.md) for more details.
+
+
+Usage
+-----
+
+- `bm <query>` — Search bookmarks
+- `bml <query>` — Search bookmarklets
+- `hist <query>` — Search history
+- `dl [<query>]` — Search downloads
+- `tab [<query>]` — Search tabs
+- `ffass [<query>]` — Workflow status and links
+
+See [Usage](doc/usage.md) in the documentation for full details.
+
+
+Licensing & thanks
+------------------
+
+This workflow and extension are released under the [MIT licence][licence].
+
+It is written in [Go][go] and heavily based on the [AwGo library][awgo], and the icons are based on [Font Awesome][fontawesome].
+
+
+[addon]: https://blah
+[licence]: LICENCE.txt
+[workflow]: https://github.com/deanishe/alfred-firefox/releases/latest
+[demo]: demo.gif
+[go]: https://golang.org
+[awgo]: https://github.com/deanishe/awgo
+[fontawesome]: https://fontawesome.com/
+

actions.go

@@ -133,6 +133,7 @@ func (a uAction) Run(URL string) error {
  return err
 }
 
+// URL action to open a URL in a new incognito window
 type openIncognito struct{}
 
 func (a openIncognito) Name() string { return "Open in Incognito Window" }

client.go

@@ -325,7 +325,7 @@ func runTabs(_ []string) error {
  Var("TITLE", t.Title)
 
  it.NewModifier(aw.ModCmd).
- Subtitle("Other Actions").
+ Subtitle("Other Actions…").
  Arg("").
  Icon(iconMore).
  Var("CMD", "actions")

doc/bookmarklets.md

@@ -0,0 +1,40 @@
+Bookmarklets
+============
+
+The workflow can run [bookmarklets][bookmarklets] from your Firefox bookmarks in arbitrary tabs.
+
+You can use the keyword `bml` to filter your bookmarklets and run them in the active tab, but you can also assign them to specific Hotkeys to run them on arbitrary tabs when filtering tabs (keyword `tab`) or add them to the `Other Actions…` list for tabs.
+
+Bookmarklets are assigned to alternative hotkeys in a similar way to [scripts][scripts], but using the form `TAB_<KEY>` instead of `URL_<KEY>`, and the variables set in [Alfred's workflow configuration sheet][config-sheet] must follow a specific format:
+
+| Variable name | Variable value | Effect |
+|--|--|--|
+| `TAB_OPT` | `bml:seoxED9MBuqi,Add to Pinboard` | Run your `Add to Pinboard` bookmarklet in the selected tab |
+| `TAB_CMD_SHIFT` | `bml:uFJCA875bTEt,Open in GoDoc` | Run your `Open in GoDoc` bookmarklet in the selected tab |
+
+The value for a bookmarklet *must* have the form `bml:<bookmark ID>,<name>`. You can get the appropriate value by hitting `⌘C` (copy) on a bookmarklet in the bookmarklet list (default keyword: `bml`).
+
+You can change the name (what's after the first comma) to anything you want, and you can assign a custom icon to the bookmarklet by adding an image file with the same basename (i.e. without file extension) as the name you've assigned to the bookmarklet to the `scripts` directory. So for example, you could set a custom icon for the above `Open in GoDoc` bookmarklet by putting a file `Open in GoDoc.png` in the `scripts` subdirectory of the workflow's data directory. See [Script icons][script-icons] for details.
+
+
+Bookmarklets without hotkeys
+----------------------------
+
+You can also add bookmarklets to the `Other Actions…` list without assigning them a hotkey. To do this add a workflow variable with a name of the form `TAB_<BLAH>` with a valid value for a bookmarklet (as described above). If `<BLAH>` is not a valid combination of hotkeys, the bookmarklet will be shown in the `Other Actions…` list, but will not be assigned to an alternative hotkey:
+
+| Variable name | Variable value | Effect |
+|--|--|--|
+| `TAB_PINBOARD` | `bml:seoxED9MBuqi,Add to Pinboard` | Add `Add to Pinboard` action to `Other Actions…` list |
+| `TAB_GODOC` | `bml:uFJCA875bTEt,Open in GoDoc` | Add `Open in GoDoc` action to `Other Actions…` list |
+
+
+---
+
+[^ Documentation index](index.md).
+
+
+[config-sheet]: https://www.alfredapp.com/help/workflows/advanced/variables/#environment
+[bookmarklets]: https://en.wikipedia.org/wiki/Bookmarklet
+[scripts]: scripts.md
+[script-icons]: scripts.md#script-icons
+

doc/index.md

@@ -0,0 +1,18 @@
+Alfred-Firefox Documentation
+============================
+
+
+- [Installation and setup][setup]
+- [Usage][usage]
+- Customisation
+ - [Scripts][scripts]
+ - [Bookmarklets][bookmarklets]
+- [Troubleshooting][troubleshooting]
+
+
+[setup]: setup.md
+[usage]: usage.md
+[scripts]: scripts.md
+[bookmarklets]: bookmarklets.md
+[troubleshooting]: troubleshooting.md
+

doc/scripts.md

@@ -0,0 +1,48 @@
+Scripts
+=======
+
+The workflow can do arbitrary things with URLs via scripts. Most of the built-in URL Actions are implemented via scripts in the internal `scripts` directory, and you can add your own scripts (with optional icons) to extend the workflow's functionality.
+
+Place your custom scripts in the `scripts` subdirectory of the workflow's data directory (which can be quickly accessed via the `ffass` keyword and `Open Scripts Directory` item). **Do not add your own scripts to the workflow's internal `scripts` directory**: they'll be removed when you update the workflow.
+
+
+How URL scripts work
+--------------------
+
+Scripts are called with the URL (from a bookmark, tab etc.) as the first command-line argument (i.e. `$1`). A script can be an executable file or any of the script types (determined via file extension) [supported by AwGo][script-types].
+
+Scripts can be run via the `Other Actions…` menu (`⌘↩` on a bookmark/tab) or directly via alternative hotkeys (e.g. `^↩`) by setting an appropriate variable [in the workflow's configuration sheet][config-sheet]. To assign a hotkey to a script, create a workflow variable of the form `URL_<KEY>` with the script's name (without extension) as the value, e.g.:
+
+| Variable name | Variable value | Effect |
+|---------------|----------------|--------|
+| `URL_CTRL` | `Open in Safari`| Open URL in Safari when `^↩` is pressed on a result |
+| `URL_OPT_CTRL` | `Open in Chrome`| Open URL in Google Chrome when `^⌥↩` is pressed on a result |
+
+Modifier keys (`OPT`, `CMD`, `SHIFT`, `CTRL`) can be arbitrarily combined by joining them with underscores, e.g.: `URL_OPT_SHIFT_CMD`, `URL_CTRL_OPT_SHIFT` etc.).
+
+You can quickly grab the name of a script by using `CMD+C` (copy) on an action in the `Other Actions…` list, which will copy the script's name to the clipboard.
+
+
+Script icons
+------------
+
+You can optionally assign a custom icon to a script by putting an image file with the same basename (i.e. excluding extension) in the `scripts` directory. Icons of type PNG, GIF, JPG and ICNS are supported.
+
+For example, if your script is called `Add to Pinboard.py`, you can assign it a custom icon by putting a file called `Add to Pinboard.png` (or `Add to Pinboard.icns` etc.) in the `scripts` directory.
+
+
+Bookmarklets
+------------
+
+The workflow can also run bookmarklets (read from your Firefox bookmarks), but these work slightly differently to scripts. See [bookmarklets][bookmarklets] for details.
+
+
+---
+
+[^ Documentation index](index.md).
+
+
+[script-types]: https://godoc.org/github.com/deanishe/awgo/util#Runner
+[config-sheet]: https://www.alfredapp.com/help/workflows/advanced/variables/#environment
+[bookmarklets]: bookmarklets.md
+

doc/setup.md

@@ -0,0 +1,47 @@
+Setup
+=====
+
+Unfortunately, this workflow requires a relatively complex setup :(
+
+Due to Firefox's preposterous lack of support for AppleScript, it's not possible for external programs to directly interact with Firefox in any non-trivial way.
+
+As a result, in addition to the workflow, you must also install the corresponding [browser extension][addon] which enables communication between Firefox and the workflow.
+
+Setup is *slightly* easier if you install (and run) [the workflow][workflow] first, and then the [browser extension][addon].
+
+
+Installation
+------------
+
+1. Download and install the workflow from [GitHub][workflow]
+2. Download and install the Firefox extension from [blah][addon]
+
+
+Setup
+-----
+
+When you first run the workflow, it will install the native-application manifest that tells Firefox where to find the workflow. Without this, the Firefox extension won't work. At this point, you'll probaby see the following error, but this is expected:
+
+![Workflow cannot-connect message](workflow-error.png)
+
+The workflow has installed the native-application manifest, and will connect to Firefox as soon as the extension is installed. Once you've installed the extension, you should see the following when you click on its icon:
+
+![Extension connected popup](extension-connected.png)
+
+If you've installed the browser extension before you've run the workflow, you'll see the following error because Firefox doesn't know where to find the workflow:
+
+![Extension disconnected popup](extension-error.png)
+
+Now you need to install the workflow, run it, and then click on the extension's icon again to cause it to try to reconnect to the native application. After a second or so, the extension should indicate that it's connected to the workflow:
+
+![Extension connected popup](extension-connected.png)
+
+At this point, you should be able to search Firefox's bookmarks, history, downloads and tabs from Alfred.
+
+
+---
+
+[^ Documentation index](index.md).
+
+[workflow]: https://github.com/deanishe/alfred-firefox/releases/latest
+[addon]: https://blah.com

doc/troubleshooting.md

@@ -0,0 +1,44 @@
+Troubleshooting
+===============
+
+If the workflow isn't connecting to the extension, first try this:
+
+1. Run `ffass` > `Register Workflow with Firefox` in Alfred to re-install the native app manifest (which tells Firefox where to find the workflow).
+2. Open the extension's popup in Firefox, which causes the extension to try to restart the native client.
+
+If that doesn't work, check the workflow's log files and Firefox's extension debugger for error messages.
+
+
+Log files
+---------
+
+The workflow writes two log files, both stored in the workflow's cache directory. Open the cache directory by entering `ffass workflow:cache` into Alfred.
+
+- `net.deanishe.alfred.firefox-assistant.log` — Log written by the Alfred workflow.
+- `net.deanishe.alfred.firefox-assistant.server.log` — Log written by the extension client/workflow RPC server that connects the workflow with Firefox.
+
+
+Firefox extension debugger
+--------------------------
+
+The extension logs messages and errors to console in Firefox's extension debugger. To open the debugger, open the following URL in Firefox:
+
+```
+about:devtools-toolbox?type=extension&id=alfredfirefox%40deanishe.net
+```
+
+This is equivalent to opening the `about:debugging` screen and clicking the extension's `Inspect` button:
+
+![Inspect button](firefox-inspect-extension.png)
+
+
+File an issue
+-------------
+
+If none of that helps, please file an issue on [the workflow's issue tracker][issues].
+
+---
+
+[^ Documentation index](index.md).
+
+[issues]: https://github.com/deanishe/alfred-firefox/issues

doc/usage.md

@@ -0,0 +1,40 @@
+Usage
+=====
+
+The workflow has the following keywords:
+
+- `bm <query>` — Search Firefox bookmarks
+ - `↩` — Open URL using default action
+ - `⌘↩` — Show all URL actions
+ - `...` — Run user-defined actions
+- `bml <query>` — Search Firefox bookmarklets
+ - `↩` — Run selected bookmarklet in active tab
+ - `⌘C` — Copy bookmarklet ID & name to clipboard to set up a [custom tab action](bookmarklets.md)
+- `tab [<query>]` — Filter tabs
+ - `↩` — Activate tab
+ - `⌘↩` — Show all tab & URL actions
+ - `...` — Run user-defined action or bookmarklet
+- `hist <query>` — Search Firefox history
+ - `↩` — Open URL using default action
+ - `⌘↩` — Show all URL actions
+ - `...` — Run user-defined actions
+- `dl [<query>]` — Search downloads
+ - `↩` — Open downloaded file
+ - `⌘↩` — Reveal downloaded file in Finder
+- `ffass [<query>]` — Workflow status & setup
+ - "Connected to Firefox" / "No Connection to Firefox" — Whether workflow can connect to Firefox
+ - "Register Workflow with Firefox" — Install native app manifest so Firefox knows where to find the workflow. This should only be necessary if you've moved the workflow.
+ - "Workflow is Up to Date" / "Update Available" — Whether a newer version of the workflow is available.
+ - "Open Scripts Directory" — Open the custom scripts directory. You can add your own URL actions and/or icons here. See [Scripts](scripts.md) for details.
+ - "Documentation" — Open these help pages in your browser.
+ - "Report Issue" — Open the workflow's issue tracker in your browser.
+
+
+See [Scripts](scripts.md) for more information on assigning custom hotkeys to URL actions and adding your own actions and icons.
+
+See [Bookmarklets](bookmarklets.md) for more information on assigning custom hotkeys and icons to bookmarklets.
+
+---
+
+[^ Documentation index](index.md).
+

firefox.go

@@ -33,7 +33,7 @@ type command struct {
 }
 
 func (c command) String() string {
- return fmt.Sprintf("command(%s) - %q", c.ID, c.Name)
+ return fmt.Sprintf("command #%s - %q", c.ID, c.Name)
 }
 
 // encode command into extension STDIO format.
@@ -48,19 +48,21 @@ func (c command) encode() ([]byte, error) {
  return b, nil
 }
 
-// response is a generic response from the browser.
+// response is a generic response from the browser extension.
+// The full JSON response from the extension is contained in data to
+// be unmarshalled by the receiver.
 type response struct {
- ID string `json:"id"`
- Err string `json:"error"`
- data []byte
- err error
+ ID string `json:"id"` // ID of the command this is a response to
+ Err string `json:"error"` // error message returned by extension
+ data []byte // full JSON response
+ err error // error encountered decoding response
 }
 
 func (r response) String() string {
- return fmt.Sprintf("response(%s) - %d bytes", r.ID, len(r.data))
+ return fmt.Sprintf("response #%s - %d bytes", r.ID, len(r.data))
 }
 
-// firefox communicates with the browser (extension).
+// firefox communicates with the browser extension via STDIN/STOUT.
 type firefox struct {
  commands chan command
  responses chan response

info.plist

@@ -1102,7 +1102,7 @@ variables={allvars}
  <key>variables</key>
  <dict>
  <key>TAB_CTRL</key>
- <string>bml:seoxED9MBuqi,Add to Pinboard</string>
+ <string>bml:yrdLTEE3tXtT,Add to Pinboard</string>
  <key>TAB_GODOC</key>
  <string>bml:uFJCA875bTEt,Open in GoDoc</string>
  <key>URL_DEFAULT</key>
@@ -1112,7 +1112,6 @@ variables={allvars}
  </dict>
  <key>variablesdontexport</key>
  <array>
- <string>TAB_CTRL</string>
  <string>TAB_GODOC</string>
  </array>
  <key>version</key>