Soc’s Blog

Released: sendkeys 2.0

2021-01-04T21:47:58+00:00

I’m happy to announce the release of sendkeys 2.0. 🚀🎉!

This is a major release and includes the following:

Rewrite from JavaScript to Swift.
Installable via homebrew.
Support for automating mouse events!!!

Installation

brew install socsieng/tap/sendkeys

Example usage

sendkeys --application-name "Notes" --characters "Hello<p:1> world<c:left:option,shift><c:i:command>"

Activates the Notes application and types Hello (followed by a 1 second pause) and world, and then selects the word world and changes the font to italics with command + i.

sendkeys -c "<m:100,300,300,300:0.5><p:0.5><m:100,300:0.5>"

Moves the mouse cursor from (100, 300) to (300, 300), pausing for 0.5 seconds and moving back to (100, 300).

Why rewrite?

You might be wondering about why anyone would bother rewriting anything from JavaScript to Swift. In my case, it was to provide mouse automation capabilties and overall simplification. With the rewrite, I was able to unify how keyboard and mouse events are dispatched to macOS using Quartz instead of AppleScript (osascript for keyboard) and Quartz for mouse.

Prerequisites

sendkeys requires macOS 10.11 or later.

When running from the terminal, ensure that the terminal has permission to use accessibility features. This can be done by navigating to System Preferences > Security & Privacy > Privacy > Accessibility and adding your terminal application there.

What’s next?

There are some additional features and learnings that I got out of this release that I plan to cover in subsequent posts. Keep an eye out for:

Recording and replaying mouse events, and
Automating releases with GitHub Actions and brew.

Released: sendkeys-macos Now Stable 🎉

2020-09-17T03:57:49+00:00

I’ve just released a stable version of sendkeys-macos as v1.0.1.

I’ve been wanting to do this for a while now, but the main thing stopping was the absence of unit tests and some additional project hygiene.

Hygiene related activities include:

Unit tests
Automation
- Add Prettier for consistent automatic code formatting
- Add Husky git hooks
- Auto-generating change logs with release-please
- Automated publish to npm

Checkout the project on github. Let me know if you have any issues. Pull requests welcome.

The latest example of the sendkeys-macos in action (and gratuitous animation).

Eleventy as a JavaScript Blogging Platform

2020-09-14T02:41:46+00:00

Eleventy High Performance Blog made it into my feed today. I hadn’t even heard of Eleventy (11ty) before today so I thought I’d check it out.

What piqued my interest about Eleventy was this:

A simpler static site generator. An alternative to Jekyll. Written in JavaScript. Transforms a directory of templates (of varying types) into HTML.

Emphasis mine.

It’s actually more like:

I’m much more familiar with JavaScript than I am with Ruby (Jekyll is built with Ruby). While the idea of being able easily make changes to the static site generator sounds compelling, the truth is that I just don’t have the time. Had I known about Eleventy when I started blogging (or done some more up front analysis), I may have chosen it as my blogging platform.

As a software engineer, I feel like I am constantly being tempted by the next new thing whether it’s a new platform, language, or framework. I think it’s important to be aware of what is happening around you, but to also think objectively about the benefits. In this case, it would be a new capability that I have no plans to use. As such, I’ve got no plans to switch.

Automated Code Formatting With Prettier

2020-09-11T02:46:00+00:00

If you’re not using an automatic code formatter, you’re wasting time (and money). Boost your team’s productivity by integrating one into your workflow today.

Consistency is important when maintaining large code bases, across multiple contributors (especially for open source projects). If consistency is important to you, then there are a few ways to maintain consistency in your code base:

Code review
Linting
Automatic formatting

Each option is built on top of the options before them.

During code review

I order to maintain consistency during code reviews, you need to start with a coding standards/guidelines.

It ~~could~~ should be as simple as:

We use the Airbnb JavaScript Style Guide here.

Stick to a well known style guide unless you have a good reason not to… and don’t forget to actually do the code review.

Linting

Linting builds on top of guidelines. It takes these guidelines and codifies them, identifying violations before the code is reviewed by another human.

ESLint is pretty much the standard for linting JavaScript.

Automatic formatting

Automatic code formatting takes linting one step further. Instead of simply reporting violations, automatic code formatting can fix these violations for you. Why waste your time adding a semicolon here, comma there? Put those idle clock cycles to work.

Prettier with editor plugins is a great way to automatically format your code on save.

Prettier in action with Visual Studio Code.

I personally spend a lot of time with Visual Studio Code working with TypeScript and JavaScript so Prettier works really well for me. If you’re working with other technologies, look around for their equivalent tools.

Getting started with Prettier

Using Prettier on a new code base is straight forward:

Install Prettier into your npm project: npm install --save-dev prettier
Install Prettier plugin for your editor (VSCode extension)

Recommended: configure VSCode to format on save with .vscode/settings.json:
```
{
  "editor.formatOnSave": true
}
```

Configure Prettier (start with the defaults and tweak to your liking)

This is the .prettierrc.yml for one of my projects:

arrowParens: avoid
printWidth: 120
quoteProps: consistent
semi: true
singleQuote: true
tabWidth: 2
trailingComma: all
overrides:
  - files: '*.md'
    options:
      parser: markdown
      proseWrap: always

I recommend adding a couple of scripts to your package.json to help with integration into automated builds
```
{
  "scripts": {
    "pretty": "prettier . --write --loglevel warn",
    "pretty:check": "prettier . --check"
  }
}
```
I use the first with husky on pre-commit to fix up formatting where I’ve used an editor without the plugin, and the second as a verification step on build as a catch-all where the git hook hasn’t been installed. An example might be external contributors who use a different set of tools.

Using Prettier on an established code base

It’s easy to add Prettier to a new or small code base, but what about a large/established code base?

You’ve got two options:

Just Do It: let your team know what you’re about to do, get those outstanding pull requests merged… Any pull requests the haven’t been merged in time are going to have a rough time with merge conflicts.
Softly-softly: turn Prettier on for new files only, and gradually enable it for the rest of your project one file at a time.

If you choose the second option the .prettierignore file is your friend.

Add an entry for all the files that you’re not ready to switch over into .prettierignore. Any new files added to your project will have automated code formatting applied and when you’re ready to enable Prettier on an existing file, simply remove it from .prettierignore.

Do your team a favor

Automatic code formatting will help boost your team’s productivity and produce more consistent code. You’ll no longer have to worry about the little things like whitespace, commas, and semicolons, and you can focus on the things that matter… the actual code.

In my previous post, I show how you can fix one the few issues that I have with Prettier.

Making Prettier Prettier

2020-09-10T01:44:03+00:00

I like having consistently formatted code, but I hate formatting code. I’m also super pedantic about how my code should be formatted.

In this post, I’ll show you how to apply a work-around for Prettier that for me was always a blemish on an otherwise awesome code formatter. But first, some context.

Context

Prettier describes itself as an opinionated code formatter which I’m cool with, as long as these opinions are the same as mine.

Where Prettier and I diverge is whether or not operators should appear at the beginning or the end of a line.

Prettier:

// prettier-ignore
const booleanResult =
  condition1 === true &&
  condition2 === true &&
  condition3 === true;

Me (plus a number of people on GitHub):

// prettier-ignore
const booleanResult =
  condition1 === true
  && condition2 === true
  && condition3 === true;

Prettier is so useful that I was willing to overlook the cancerous eyesore 🤮 that is the first example if it mean that I didn’t have to format the code myself. So I sucked it up and moved on… That was until this weekend when I stumbled upon some new activity on a related Github issue. @btmills had updated his pull request and included instructions on how to use it. 🎉

I applied it to one of repositories that I manage but found that it wasn’t completely straight forward so I thought I’d share the additional steps required to get it working.

Environment

I’m using npm (instead of yarn) with the following npm scripts in my package.json which is where I think the problem lies:

{
  "scripts": {
    "pretty": "prettier . --write --loglevel warn",
    "pretty:check": "prettier . --check"
  }
}

Installation

npm install --save-dev prettier@npm:@btmills/prettier@^2.1.1

For some reason, prettier@npm:@btmills/prettier@^2.1.1 does not create an executable under node_modules/.bin/prettier, however, prettier does. So as a work-around, I referenced node_modules/prettier/bin-prettier.js directly instead of prettier in my package.json:

{
  "scripts": {
    "pretty": "node_modules/prettier/bin-prettier.js . --write --loglevel warn",
    "pretty:check": "node_modules/prettier/bin-prettier.js . --check"
  }
}

I’m told that the package name format (prettier@npm:@btmills/prettier@^2.1.1) is specific to yarn, and works as expected with yarn.

As an alternative, I could have used the github package name npm install --save-dev prettier/prettier#pull/7111/head but I found that the installation process was significantly slower than prettier@npm:@btmills/prettier@^2.1.1. I also liked the fact that the yarn syntax references an npm package and is therefore immutable. So I stuck with that.

Looking forward

Yes, this is a work-around that I’d prefer not to have to make, but at the same time, it doesn’t cause my eyes to tear up when I see my operators in the wrong location.

I plan to stick to this until Prettier 3.0 is released with the correct opinion applied.

Using GitHub Actions Over GitHub Pages

2020-09-07T20:30:19+00:00

I’m making the move from GitHub’s built-in Jekyll integration to GitHub Actions.

Jekyll lists a number of advantages of using GitHub Actions, however, I’m primarily interested in:

Improved indexing for related_posts with --lsi (latent semantic indexing) which is not available with GitHub pages,
Access to more plugins (not just those permitted by GitHub pages),
More fine-grained control over how the site is generated - the current GitHub pages set up is a bit too magic-y and I don’t have visibility of what is actually happening when I commit changes, and
Using the latest version of Jekyll

Reverting to the latest version of Jekyll

Step 1: Remove github-pages from Gemfile, and add jekyll

# gem "github-pages", group: :jekyll_plugins
gem "jekyll", "~> 4.1.1"

One of the things that broke for me was that the theme I was using didn’t work with the latest version of jekyll. So I carefully copied the files from gems/jekyll-theme-midnight-0.1.1 into the root of my repository, and added the plugins that the theme referenced into my Gemfile:

group :jekyll_plugins do
  # ...
  gem "jekyll-seo-tag", "~> 2.0"
end

Verify that the site continues to work as expected.

Adding latent semantic indexing (locally)

Latent semantic indexing support requires the classifier-reborn plugin. This is added by updating the Gemfile:

group :jekyll_plugins do
  # ...
  gem "classifier-reborn", "~> 2.2.0"
end

And then enabling it with the --lsi option:

# install plugin
bundle install

# start server locally
bundle exec jekyll serve --lsi

This is the list of related posts before:

Related posts

Maintaining a Jekyll Blog with Gitpod

Scripting a New Blog Post

We Don’t Look Alike

Automation Challenge: Image Optimization

Customizing The Blog With Related Posts

How Breaking My Hand Improved My Typing

Adding Google Analytics

Updating the Blog’s Theme

Blogging for free with Jekyll

And after:

Related posts

Blogging for free with Jekyll

Using GitHub Actions Over GitHub Pages

Updating the Blog’s Theme

Customizing The Blog With Related Posts

Automation Challenge: Image Optimization

How Breaking My Hand Improved My Typing

Adding Google Analytics

Maintaining a Jekyll Blog with Gitpod

Scripting a New Blog Post

We Don’t Look Alike

Trust me, the updated list is much more relevant than a recent posts list

Adding the GitHub Action workflow

Previously, socsieng.github.io was automatically setup to build a static Jekyll site and publish to GitHub Pages. Without this automatic process, I now need publish my static site to a GitHub Pages branch (gh-pages by convention).

Jekyll provides a sample workflow file, which I use as a starting point for .github/workflows/jekyll.yml:

name: jekyll build

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      # Use GitHub Actions' cache to shorten build times and decrease load on servers
      - uses: actions/cache@v1
        with:
          path: vendor/bundle
          key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
          restore-keys: |
            ${{ runner.os }}-gems-

      - uses: socsieng/jekyll-action@master
        with:
          target_branch: gh-pages
        env:
          JEKYLL_PAT: ${{ secrets.JEKYLL_PAT }}
          JEKYLL_ARGS: --lsi

I’ve had a look at the helaili/jekyll-action repository that the Jekyll documentation referenced and used some of the sample configuration there as well.

Note that I’ve forked helaili/jekyll-action to add support for additional JEKYLL_ARGS parameters so that I can pass in the --lsi. I’ve also raised a pull request back to the original repository.

A prerequisite to enabling this workflow is that you need to provide and configure a GitHub Personal Access Token with the public_repo scope for the workflow to use to publish site changes. I strongly recommend creating a new token instead of reusing an existing one.

Configuring GitHub pages

Once the workflow executes, a new branch is created gh-pages (updated if you already had this branch).

The final step is to configure GitHub Pages to use this new branch:

Configure GitHub Pages.

Summing up

I switched over to GitHub Actions so that I could have more control over how my Jekyll site is generated. It is more involved than simply using the default GitHub/Jekyll integration, but I think it will pay off in the long run with more control and flexibility at my finger tips.

I hope this helps anybody else thinking about making the switch.

Maintaining a Jekyll Blog with Gitpod

2020-09-05T05:00:16+00:00

I’m editing this post with on my iPad with gitpod.io, and I’m very impressed. And I’m not easily impressed.

I first heard about gitpod.io when saw their post about how Gitpod is now Open Source 🎉. When I started looking for solutions to manage the blog on my iPad, I thought I’d give it a try.

The environment is so familiar. It is pretty much Visual Studio in the browser, with some linux based environment accessible through the integrated terminal.

Almost everything that I’ve tried so far has worked (note that I’m not trying to break it… just use it):

command + shift + p to toggle word wrap,
Install prettier extension to automatically format posts as I save them,
Executing and running the Jekyll server (bundle exec jekyll serve --watch),
Previewing the site on Gitpod,
Creating a new post with a custom script (scripts/new-post.sh tools "Maintaining a Jekyll Blog with Gitpod"),
Syntax highlighting,
Commit files locally, and
Push files to GitHub.

Things that don’t work:

Upload an image (e.g. screenshot) via Gitpod (haven’t figured out how to do this yet),
Terminating a command in the terminal with ctrl + c (at lease on the iPad with the Smart Keyboard),

I haven’t spent very long with Gitpod, but I’m happy with the experience so far. It isn’t going to replace my laptop environment, but I think its a viable alternative for when I’m on the iPad (with the Apple Smart Keyboard).

I’ll keep this post updated as I learn more.

Scripting a New Blog Post

2020-09-04T20:02:27+00:00

I’m tired of manually creating a new Jekyll blog post which for me included copying an existing post, renaming the file with today’s date and the title of the post, updating the title attribute of the markdown file, and deleting the contents of the copied post.

That workflow ends today.

I’ve created a script (scripts/new-post.sh):

#!/usr/bin/env bash
set -e

repo_folder=`git rev-parse --show-toplevel`

category=$1
title=$2
timestamp=`date "+%F %T %z"`
date_value=`date "+%F"`
file=`echo $title | awk '{print tolower($0)}' | sed -e 's/[^a-zA-Z0-9]/-/g'`
file_path="$repo_folder/_posts/$date_value-$file.md"

echo "---
layout: post
title: '$title'
date: $timestamp
categories: $category
tags: $category
---
" > $file_path

echo $file_path

Usage:

scripts/new-post.sh <category> "<title>"

It takes two arguments. category and title. Your title will probably contain spaces so you’ll want to generally wrap your blog post title in quotes.

Example:

scripts/new-post.sh blogging "My New Post"

I’ve decided to write the new file path to stdout so that I can command + click the file name to quickly start editing in Visual Studio Code.

Demo:

Edit:

Since writing this post, I found out that there is a plugin jekyll-compose which provides this functionality as well as more. I plan to stick with this script though. Its one less dependency, and does everything I need.

We Don’t Look Alike

2020-09-03T07:53:00+00:00

My wife saw U.S. Representative Ted Lieu on TV today and thinks we look the same. For the record, we don’t.

For anyone else who thinks they’re the same people, that’s me on the left and Ted Lieu on the right.

I think she might be racist. That or she needs new glasses.

The sad thing is that Ted is 11 years my senior and looks younger than me. 😭.

Automation Challenge: Image Optimization

2020-09-03T03:13:00+00:00

I’m looking for things to automate and I challenge you to do the same.

In this post, I’m going to automate a task that does not spark joy. This time I’ve decided that it’s going to be optimizing images for this blog.

Optimizing images

This blog is built with Jekyll and is running on GitHub pages. Jekyll is built with Ruby (a new language to me), so I’ll be using a Ruby gem called image_optim to apply the optimizations. I do this by adding the dependency to my Gemfile:

group :development do
  gem "image_optim", require: false
  gem "image_optim_pack", require: false
end

And then installing the dependency:

bundle install

I’m going to organize scripts in the aptly named scripts folder, and the Ruby script to optimize images will be named scripts/optimize-images.rb 🤯:

#!/usr/bin/env ruby

require 'rubygems'
require 'bundler/setup'
require 'image_optim'

# resolve the root folder of the repository
root_folder = `git rev-parse --show-toplevel`.strip
if !File.directory?(root_folder)
  root_folder = `pwd`.strip
end

# files to optimize: jpg, png, and gif files under assets/img
target_files = "#{root_folder}/assets/img/*.{jpg,png,gif}"

# instantiate ImageOtim with configuration options
image_optim = ImageOptim.new(
  :pngout => false,
  :svgo => false,
  :cache_dir => "#{root_folder}/temp"
)

# execute image optimization
image_optim.optimize_images!(Dir[target_files]) do |unoptimized, optimized|
  if optimized
    # print filename to stdout
    puts "#{optimized}"
  end
end

Nothing too crazy going on here. Its not rocket surgery… 🚀🩺

A couple of things to note:

I’ve specified the option :cache_dir which is a performance optimization. This allows image_optim to remember that it has already seen and optimized an image, and it won’t do it again. The image optimization process can be slow and taxing on the CPU.
I am writing the file path of the optimized image (puts "#{optimized}"). This will come in handy later.

I can trigger an image optimization by executing the following command:

ruby scripts/optimize-images.rb

Automation

Having a script to optimize images is a great first step, but it still doesn’t spark any joy.

I need to figure out which event I should use as a trigger and I’ve settled on pre-commit (instead of something like build). The reason being that this is required step in my workflow which is create/edit a post locally on my computer, commit the changes, and push to GitHub.

I’m creating a script called scripts/pre-commit.sh:

#!/usr/bin/env bash
set -e

# get the repository root
repo_folder=`git rev-parse --show-toplevel`

# use repository root if there is a value, otherwise use the current folder
root_folder=${repo_folder:-`pwd`}

echo "Performing image optimization for the first time can take a while. Sit tight..."

# execute image optimization and store results in a variable
optimized_images=`ruby $root_folder/scripts/optimize-images.rb`

if [ -n "$optimized_images" ]
then
  echo "$optimized_images" | while read image; do
    echo " - Optimized $image"
    git add "$image"
  done
fi

echo "Done."

Don’t forget to make sure this script is executable (chmod +x scripts/pre-commit.sh).

This is where output-ing the file path from the scripts/optimize-images.rb script comes into play. It is assigned to the $optimized_images variable where we loop over each of them optimized images and stage them to the repository with git add.

In order to get this script executed on pre-commit, I need to install it as a git pre-commit hook which can be done by copying this file to .git/hooks/pre-commit (without the .sh extension). I’ve created a little script to help me install it in case I need to re-install it on another device (scripts/install-pre-commit.sh):

#!/usr/bin/env bash
set -e

script_folder=`cd $(dirname $0) && pwd`
repo_folder=`git rev-parse --show-toplevel`

cp -f $script_folder/pre-commit.sh $repo_folder/.git/hooks/pre-commit

Again, don’t forget to make this script executable. Install using scripts/install-pre-commit.sh.

Once installed, any images that have not already been optimized every time I call git commit.

Sparking joy

With very little effort, I’ve been able to automate an otherwise mindless activity.

And here are the results:

Image	Size before	Size after	Improvement
github-pages-config.png	102K	51K	51K (50%)
google-pay-vue.gif	2.9M	2.4M	0.5M (17%)
jekyll-screenshot.png	520K	272K	248K (48%)
jekyll-theming-1.png	570K	307K	263K (46%)
jekyll-theming-2.png	536K	285K	251K (47%)
jekyll-theming-3.png	569K	311K	258K (45%)

I’m sure Marie Kondo would approve.

I challenge you to find something/anything to automate. I want to hear about it: @aussoc.