DEV Community: Luke Barnard

Morgen Assist + OpenAI generate my daily plan + send it to my Slack. Here’s how.

Luke Barnard — Mon, 30 Oct 2023 10:22:43 +0000

Originally written by Luke for morgen.so

This year, I had the great pleasure of joining a very exciting startup, which has a mission to revolutionise the way teams automate their time management.

Morgen recently launched a new product – Morgen Assist – which we think is really going to supercharge calendar automation and see 1000s of awesome workflows and apps come to market, with Morgen powering the whole thing.

But don’t take my word for it, follow along and find out how easy it is to write, test and deploy your own calendar workflows from your very own environment.

And I’m sorry but putting OpenAI in the title was the easiest way to get you to click but I promise it is necessary for this <100 line app that intelligently summarises calendar events from any-and-all of your calendars*.

Google and O365 supported currently, CalDAV coming Soon™️

“What am I doing today?”

You might have wondered this question, coffee in hand, staring blankly into your remote working office having rolled out of bed and into the living room this morning.

With 50+ new slack messages from the PM, design team, marketing and support channel, you might forget to check your calendar, which is currently lost amidst a sea of Firefox tabs, terminals and well… more terminals.

And that’s where the the Morning Schedule Workflow comes in.

A slack message is delivered every morning (or evening) straight to your DMs informing you of any upcoming meetings, including retrospectives, 1-1s, other sprint meetings, customer calls, all in the language and tone of your choice.

As a demonstration I have submitted the following text to OpenAI’s ChatGPT model:

You are the legendary Apple founder, Steve Jobs delivering a key note

Please summarise all of these upcoming events listed in a way typical with your
classic presentation style.

- 1-1 with David

- Retrospective on the last sprint

- Customer Call /w Apple

And this is what I got back:

Ladies and gentlemen,

Today, I'm here to give you a brief update on some upcoming events that are of utmost importance to our company.

First on the list, we have a 1-1 session scheduled with David. This is a fantastic opportunity for us to connect on a personal level, exchange ideas, and align our vision. Such interactions are …

And it goes on. The full keynote is truly inspiring but you’ll have to see that for yourself.

So we have the central piece of the puzzle, but how does this fit within a Morgen Assist workflow?

Getting Started with Morgen Assist

Next up, you’re going to need an account with Morgen Assist. You’ll only need an email address and a calendar account which is either provided by Microsoft O365 or Google.

Creating a custom workflow

We will first need a custom workflow on the Morgen Assist platform, which you can find here.

Don’t forget to add a calendar integration to your account, you’ll need that shortly. You can ignore the slack integration for now - this is for a slightly different use-case.

Then follow these steps:

Set the trigger type to “timed” at a time of day of your choosing (e.g. 6pm)
Select a calendar to source the events to summarise
And finally insert code into the User Script section according to the instructions below.

✨ Note that if you want that hacker 10x engineer experience, you can also write and deploy your workflow via the SDK, which has a TypeScript API client for making requests to our backend. Currently your code has to fit entirely into the run function, which I’ll explain below. Some interaction is still necessary in the web app, but we’re looking at improving this in future.

Writing the Script

Thankfully, a version of this workflow has already been written and can be accessed in a form that is compatible with both the Morgen Assist SDK and the Morgen Assist Web Interface.

You can find it here: https://github.com/morgen-so/morgen-cw-sdk/blob/main/examples/openai-tomorrow-summary.ts

I will now break this script down.

First up, we’re going to need to include a couple of utilities to make requests to Morgen and OpenAI. Paste the following into the top of your user script:

async function fetchMorgen(url, opts) {
  return fetch(
    url,
    {
      headers: {
        Authorization: `Bearer ${JSON.parse(global.TOKEN)}`,
        Accept: 'application/json',
        ["Content-Type"]: 'application/json',
        ...opts.headers,
      },
      ...opts,
    }
  );
}
async function getOpenAIResponse(prompt) {
  const resp = fetch(
    "https://api.openai.com/v1/chat/completions",
    {
      method: 'POST',
      headers: {
        Authorization: 'Bearer [YOUR-TOKEN]',
        Accepts: 'application/json',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        "model": "gpt-3.5-turbo",
        "messages": [{
          "role": "user",
          "content": prompt
        }],
        "temperature": 0.7
      })
    }
  )
  const parsed = JSON.parse(resp);
  if (parsed.error) {
    throw new Error('Error with OpenAI: ' + JSON.stringify(parsed.error));
    return;
  }
  return parsed.choices[0].message.content;
}

Note that you’ll need an OpenAI token for this to all work as expected. Once you create an OpenAI account, you can create tokens here: https://platform.openai.com/account/api-keys

Let’s get the Slack token ready as well:

Create a new app here: https://api.slack.com/apps
- (this is how the summary bot will access and appear in Slack)
Set your app's appearance and permissions
- Go to “OAuth & Permissions”, find the “Bot Token Scopes” section
- Add the “chat:write” permission
Scroll up to the “Oauth Tokens for Your Workspace” section and click “Install to Workspace”, click “Allow” on the confirmation page
Find the xorb-... token under “OAuth & Permissions”

Okay, now let’s write a basic run function. This function will be called when the workflow is triggered.

async function run(trigger) {
  const slackToken = "xorb-...";
  const openAIToken = "k-...";
  // Logic goes here
}

Finally let’s look at the actual logic of this workflow.

Fetching tomorrow’s events

To do this, we need to make an API call to the Morgen API with a start/end range that captures tomorrow midnight until midnight the day after.


// fetchMorgen () { ... }
// getOpenAIResponse () { ... }

async function run(trigger) {
  const slackToken = "xorb-...";
  const openAIToken = "k-...";

  // Fetch events from tomorrow

  // Get the first calendar selected in workflow config web page
  const calId = trigger.accounts.calendar[0].calendarId;

  // Set the start of the range to the start of tomorrow
  const now = luxon.DateTime.now();
  const startTs = now
    .startOf('day')
    .plus({days:1})
    .toISO({includeOffset: false, suppressMilliseconds: true});

  // Set the end of the range to the start of the day after tomorrow
  const endTs = now
    .startOf('day')
    .plus({days:2})
    .toISO({includeOffset: false, suppressMilliseconds: true});

  // Make a API request with fetchMorgen utility we added before
  const mresp = await fetchMorgen(
    `https://sync.morgen.so/v1/events/list` +
    `?calendarIds=${calId}` +
    `&start=${startTs}` +
    `&end=${endTs}`, 
    {
      method: 'GET',
    });
  const evs = JSON.parse(mresp);

  log(JSON.stringify(evs, null, 2));
}

If you run this, provided there are events in your selected calendar for tomorrow, you should see them listed below the editor after you click “Run & Save”.

Note that it might take a while for anything to happen, we’re working on improving this part of the custom workflows feature.

You should see a JSON blob logged that corresponds to a list of events in your calendar tomorrow. :party:

Next we’re going to send the titles of these events to OpenAI to see what it can come up with.

ChatGPT, do your thing

Let’s take our events and get ChatGPT to summarise them in a simple format:

async function run() {
  ...
  const evs = JSON.parse(mresp);

  // Get all busy events and format for ChatGPT
  const list = [];
  for (let ev of evs.data.events) {
    if (ev.freeBusyStatus == "free") continue;
    list.push({
      title: ev.title,
      start: ev.start,
      duration: ev.duration,
    });
  }

  // ChatGPT gets confused if we don't order things chronologically
  list.sort((a,b) => a.start > b.start ? -1 : 1);

  // Generate a nice summary
  const summary = await getOpenAIResponse(
    "Summarise the following calendar events in an easily " + 
    "digestable chronological bullet list: " +
    JSON.stringify(list) +
    "\nExample: Events today:\n" + 
    "\t9:00 –\tStandup 15 minutes\n" +
    "\t12:00 –\tLunch\n" +
    "\t15:00 –\tCatchup" +
    "\nResponse: "
  );
  log(summary);
}

Now we have that summary, you can try running this to see that it correctly logs a nice bullet-pointed summary of events for tomorrow.

Of course, you can tweak this to be pretty much anything, for example you might want the movie trailer edition.

const summary = await getOpenAIResponse(
    "Summarise the following calendar events " +
    "in the form of a short movie trailer: " + 
    JSON.stringify(list) +
    "\nResponse: "
  );

And the response is hilarious as required:

In a world filled with challenges and opportunities, a team comes together to conquer the day. Brace yourself for an epic journey through the world of corporate endeavor.

In the early morning light, the team gathers for their gripping "Morning Standup". Witness the camaraderie and determination as they share their progress, align their goals, and prepare for the battles ahead. With each member showcasing their skills and expertise, it's a spectacle that will leave you inspired.

But victory is not without reflection. As the sun sets and shadows deepen, our heroes find themselves in the midst of an awe-inspiring "Retrospective". Together, they venture into the past, analyzing their triumphs and challenges in order to emerge stronger than ever…

Or a poem perhaps?

In morning's golden light, we convene,
A team united in purpose, it seems,
The standup whispers tales of tasks anew,
Sharing progress, challenges, and breakthroughs.

With hearts filled with hope and eyes wide awake,
We march towards goals, no time to forsake.
A symphony of voices, ideas flow,
As the morning standup sparks our shared glow.

But when shadows grow long, and day takes its toll,
We gather once more, to reflect as a whole…

Brilliant. Something for everyone here with these event summaries. And of course it will always reflect the events of the day.

I will leave it as an exercise to the reader to try these modifications:

Ignore recurring events
Write a prompt to handle the case where there are no events scheduled
Add a description of tasks that are due to be completed today and this week

But how do I send this to Slack?

So long as you have set up your Slack app, as described in the previous section, you should be able to start sending messages on behalf of a bot user that can be controlled with the token you copied.

To do this, use the following code:

  ... 

  // Send summary to Slack user
  const resp = await fetch(
    "https://api.slack.com/api/chat.postMessage", {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${slackToken}`,
      Accept: 'application/json',
      ["Content-Type"]: 'application/json',
    },
    body: JSON.stringify({
      channel: '@Luke',
      text: summary
    })
  });
}

Notice that I sent the message to the “@Luke” channel, which is how to send a direct message using the Slack API. You’ll have to change that to your username in the workspace that your app is installed under.

And with that, the workflow is complete. You can try running it, and expect it to run at the configured time in the “Trigger” section.

Conclusion

Thanks for making it to the end of my blog, I’m really grateful for it and if you’re interested in finding out more about Morgen Assist, here are some links to get you started:

Find out more about how to develop your own Custom Workflows from our Morgen Developer Documentation
Check out our pre-alpha SDK for deploying Custom Workflows from your own environment on GitHub
Come join the discussion on Discord

Emulating Xmonad in Javascript - Part 5

Luke Barnard — Tue, 03 Mar 2020 21:47:04 +0000

It's a whole year since I first started developing nomad! I recently made some changes that I thought were worth highlighting with a blog, so here it is!

New control sequence parsing

I decided to reimplement the logic that nomad uses to parse control sequences from program output. This meant ditching a few regex sequences that were mostly created through trial and error and replacing them with something that consumes control sequences character-by-character, checking against a list of known sequences.

Now when I say "known", I mean documented by some folks who very much appreciate the importance of this weird language known as ANSI. I copied a bunch of documentation from a great resource on these sequences that can be found here: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html

The code in question can be found here: https://github.com/lukebarnard1/nomad-term/blob/0fd7f1c8b60b6d319c0283a9d63fd6ee961495c6/ctlseqs.js

Essentially what it does is it takes a bunch of templates that look a bit like the documentation in the above resource:

CSI Pm m

and creates a function that will match a given input string to this particular sequence if the string is a prefix of it.

I opted to not optimise this code too much so that I could focus on being confident that the matches were valid and that the outputs were restricted. After all, sending all of your program output through one program should require a high level of scrutiny.

There are definitely some more optimisations to be made here - for example, most sequences start with a CSI (Control Sequence Initiator) of ESC[ followed by a sequence of digits and semi-colons. One potential optimisation here could be to consume a series of characters matching [0-9;] without even testing against any individual sequences. I'll be making these optimisations soon!

Changing the parsing of control sequences also meant changing the internal representation of them, which required changes to the (sub)terminal implementation itself. The integration tests I had written were fairly useful but it turns out they may have recorded an incorrect snapshot before, so the actual output wasn't totally useful...

I still haven't gotten around to writing my dream unit tests of "start with an empty terminal, following these control sequences expect state to have updated in this way". I'll get around to do it! I think this would be a great candidate for some test-driven development of more separate updating of different terminal state.

Let's just say there's a lot of work left over for a rainy day.

New help screen

I showed nomad to my boss and he let me know that when he run nomad, it was "blocked". When he showed me what he meant it was clear that nomad was doing a poor job at giving the user an idea of how to control it! So I decided to make the controls a lot more accessible.

So there it is, a preview of the help box that follows you around when using nomad.

Try it!!

You got this far, why not try nomad out! Bear in mind that all of everything you type goes through nomad and everything a program sends to stdout also goes through nomad and is stored in memory. This is true of your actual terminal (e.g. gnome-terminal, Terminal.app etc.) but they're used by the whole world.

The repo is here: https://github.com/lukebarnard1/nomad-term :)

Functional components vs. Feature components

Luke Barnard — Sat, 01 Feb 2020 11:29:10 +0000

I've been working as part of a product team for a while now and I've started to pick up on a pattern. It comes back to whether development is focused on building what I'm calling features or functions.

These terms are quite similar and are quite frequently used interchangeably in software engineering - they're very similar in definition.

Here I'll define them to avoid any doubt:

Feature - part of the product that the user can use directly
Function - a system component that can exist in isolation from any feature that uses it

When building a feature, a trade-off between reusability and extensibility exists whereby features that are developed entirely isolated from each other are infinitely extensible whereas features that share as many components as is technically possible are less extensible.

If a feature exists in total isolation, none of its components are used by other features. For example, this could be part of an app dedicated to listing blog posts that allows filtering by category and full-text search. If built in isolation, none of the other parts of the app would share any of the same components.

By nature, isolation lends itself to extensibility and so the app page in the example above could theoretically be changed in any way without impacting other parts of the app.

But this comes at a cost - building everything from scratch takes longer.

So naturally most systems are not built in this way and there are hundreds of ways to consider how to architect a system that I won't go into here.

But one thing that I've seen a lot first-hand is how the feature design process influences the boundaries of each component in a system.

Which brings me to an observation:

feature-specific components are bound to a feature and therefore cannot be reused by other features
function-specific components are used by a feature and can be reused by other features

By designing a system component to be explicitly bound to a feature, reuse is actively discouraged, whether it's a service, an API endpoint, a button in the UI or anything really. What this allows is for individual features to be changed frequently and without much consequence to other parts of the system (although by nature system components are never totally isolated).

This might be suitable for certain products that need to change frequently, or that have a short shelf life. But in the long-run features will be developed repeatedly that are similar in nature but differ in their components.

This can become costly - a lot of dev time that could be spent investing in components for the future is instead spent building components for today.

By designing a system component to be explicitly bound to a function, reuse is a fundamental consideration because by the definition above it can be used by new features in the future. The more features that can utilise a component, the more extensible the product is overall.

The thought process becomes more about separating the functional requirements of a feature from the feature itself - system components become functional requirements.

As an example, take a dashboard for monitoring a service that tracks employee workload by monitoring how many email threads they are active in in a single day. Let's suppose the product team wants to add a page to the dashboard that let's the user view a graph that shows the workload over time for a specific group of employees.

One way of delivering the feature is to create a new service dedicated to this page, have it expose an API that provides the data, which is stored in a new database called group_workload_stats. The service updates the table over time and the API will return an updated view when that happens.

It's easy to see that none of the above can be reused as part of another feature.

To rethink this implementation, we could consider making each component function-specific.

For example, the new service could be dedicated to the function of returning workload data over time - something that is predictably reusable, something required by other features that are planned for the future. It's true that this restricts new features by constraining them to the functionality provided, but it is possible to build such
services with extensibility in mind.

In summary, I think there are a lot of benefits to thinking of system components in terms of whether they are feature-specific or function-specific. This in theory encourages features comprised of functional components, which in turn saves time in the long run.

In a later post I'd like to discuss how this relates to design patterns such as microservices and how some parts of the system must define the composition of functions in order to deliver features.

When to criticise constructively when building a product

Luke Barnard — Mon, 11 Nov 2019 23:33:25 +0000

I used to complain a lot whilst doing my job. Not because things were actually bad or worth complaining over, but because my ruthless perfectionism caused me to notice things that I knew could be improved, and, to their dismay, the whole team had to hear about it.

This lead to some lengthy discussions surrounding the possibility of changing parts of the system. One good example was the state management in a React app I was working on. This was my first production app so with fresh curiosity and perfectionism abundant, I drew everyone's attention to what I thought to be obvious: we weren't using Redux.

Not only that but the app was making use of dozens of what were essentially singletons, each with their own method of managing state. It was similar to MVC, where a set of controllers expose the model to the view, allowing the view to manipulate the underlying model.

This is quite a well known pattern and remains a decent approach for many projects. But having just learned about Flux and Redux, I had a new found energy for pointing out that things would be easier if we used another abstraction.

What I failed to realise at the time was two-fold:

I didn't realise that shipping new features at the time was more important than finding the perfect abstraction and
I didn't realise that introducing a second abstraction would actually make things harder for everyone.

I'll circle back to the second one later, but let's focus on why shipping features might have been the right call at the time.

Every team has its trade-offs and I cannot stress how important it is to know which ones are currently being made. Sometimes you just have to ship functionality - it just has to work. Sometimes users are frustrated with a certain bit of the app and the UX needs to be improved. Other times the technical debt is so high that it's actually slowing down addition of more features and is making it impossible to fix bugs.

Whatever the current situation, trade-offs need to be made to rebalance the scales and stop the project from toppling over.

During this project, the main target was growing the user base - a familiar one for any B2C app. Secondary to that was improving the UX of the app because a lot of users found it confusing relative to other similar apps they were using.

Although I didn't realise it, to come to the table with the problem of the app using the wrong abstraction was probably the least productive thing I could have done at that point. But I was convinced it would help us debug the app more easily and implement new features more quickly, so I got buy-in from a few colleagues and started merging changes that were written differently to other parts of the app.

I justified the changes to myself, "it can't be worse to add an abstraction that adds structure - other parts of the app have no structure!"

This brings me to the second thing I had failed to realise. Abstractions increase complexity. When something is made generic, a tradeoff is made where uniformity is bought in exchange for rigidity and potentially hidden complexity.

What I thought I had done was to slowly start moving the app towards a more generic, easier to understand place but what had actually happened was that I had introduced a new concept that was actually incompatible with existing parts of the app. It even required extra complexity to be compatible with the layer in the stack that made API requests.

Some new features could be implemented with this new abstract and that's what I would try to do. My colleagues agreed with me that the code was easier to read and they bought into the idea as more features were developed this way.

But then we had to debug them. The added complexity that we acquired in the tradeoff bit us when bugs arose in the parts of the app using the new abstraction. This obviously was not great for morale and it was all too easy to blame the abstraction itself (Flux/Redux) over the actual problem - increased complexity.

My goal was actually to decrease complexity and the irony wasn't lost on me; I learned a few lessons as a result.

Untangling such an architecture would take more than a new paradigm to shift it away from unscalable "ball-of-mud" territory. I think the real problem was probably the API and the fact that it required a sizeable, stateful SDK to manage all of the client-side objects. This left the view and the controllers highly coupled to the SDK.

In hindsight, it's possible that with a lot of pain the app could be rewritten using React hooks. I remember a lot of the controllers in the app were essentially complex hooks (minus the abstraction now built into React itself).

But of course, this might not actually make things better - certainly cleaner but not necessarily less complex or easier to debug.

To summarise:

Nothing exists in a vacuum. Understanding the current trade-offs is crucial.
Buy-in is not always worth it. If you have to work hard to convince your coworkers of something, back it up with concrete evidence (e.g. a POC) and make sure you've convinced yourself first that you're really solving a problem.
No framework/paradigm is a silver bullet. An abstraction will likely increase complexity.
Multiple competing paradigms might be more confusing than a single one that isn't strict.

To that end, remember to know your trade-offs and hopefully you can make sure that your team is at least making them consciously and planning on rebalancing the scales at some point.

(Not) Building a Decentralised Blog

Luke Barnard — Sat, 26 Oct 2019 17:04:45 +0000

journal is exactly where I left it a few months ago, looking a bit dated and not being easy to use and not having the features I wanted in my blog site.

Meanwhile, the main purpose of journal remains unfulfilled. The work to expose a matrix room as a journal blog was never done as I haven’t had the time or the will to go and make it happen.

My original decision to replace the client-based version of journal was a little short-sighted. It’s true that it took a long time to load a blog, but it worked and had live updates and allowed posting of blogs and comments. In hindsight I could have enhanced this with a server that exposed a room as a set of markdown files to be consumed by the frontend.

But when you think about it, trying to optimise the bit that content management systems have already solved would also have been a bit short-sighted.

The other way of looking at it is that if the client-based journal could have avoided doing the main blog article bit, it might have actually been a useable solution and a widely compatible one. For example, it could have been embedded into a blog that was already deployed via a CMS.

Content management is a well developed area of open source, with a lot of different options (e.g. Ghost, Hugo, Jekyll), all that produce static content in a customisable way. Any solution for blogs on matrix should clearly make use of the work that has been done here.

Disqus is an example of a centralised discussion thread embed which I think is an obvious solution for the matrix community to clone. The matrix equivalent could be highly customisable and integrate with popular matrix clients via a “matrix.to” link (e.g. “Open discussion in Riot.im”).

For other features that I intended to implement with journal, there are existing solutions that are already widely used. For example, twitter, mastodon or email can be used to notify readers of a new blog (or a message in a matrix room, which could even be the start of the embedded discussion thread!).

Regardless of the direction I took journal in, I clearly didn’t have time to maintain such a project in it’s entirety. My current plan is to stop maintaining it, eventually replace my personal blog with Hugo and who knows, maybe I’ll have a go at making a Disqus clone for Matrix one day.

Thanks for reading and showing interest in this project.

Happy decentralising 😄

Writing a Relevant CV

Luke Barnard — Tue, 17 Sep 2019 22:56:20 +0000

For the last few months I've been helping out with the frontend developer hiring process at Tessian (that's right, we're hiring - send me a DM!) and I'd like to share some thoughts on keeping your CV relevant. I must note, these views are entirely my own - not Tessian's.

This will be the first in a series of posts that I want to share from the perspective of someone who has been looking at A LOT of CVs with the sole aim of finding really incredible engineers to join an already awesome tech team.

Context > Breadth of Knowledge

The first thing I notice when I look at a CV is the number of technologies and frameworks mentioned. I find that lists of entire A-Z of libraries, frameworks, architectures or paradigms can distract from the information that matters the most. A CV that really stands out is one that brings to light the unique parts of someone's experience. Mentioning relevant technologies with your previous roles and projects will help give a much clearer idea of how much experience you've had with a particular bit of tech. It also gives context - reading "PHP" on it's own doesn't give as much insight as "helped rewrite PHP monolith as a set of micr-frontends".

I've also seen some CVs that show how comfortable someone is with certain technologies with graphs or ratings out of 5. When it comes to indicating relative proficiency in certain technologies, I think it's best to stick to the facts, which in this case are previous employment and projects.

In any case, remember that you can learn anything in time - there should be nothing stopping you from becoming more proficient with a given stack. The projects you list on your CV will showcase this.

Remember that giving context is more important than the number of technologies you can list.

Impact > Work

I've noticed a lot of CVs mention very common tasks that you might do as a developer. In particular I notice most people tend to mention one of the below:

Developed UI components
Fixed bugs
Wrote unit tests
Participated in SCRUM meetings

Every time I read this I find myself wishing that I could ask the candidate what they really achieved on a particular project and how they had an impact.

My advice is to focus on the unique aspects of a particular project and the impact of the tasks you did, e.g.:

Optimised the performance of the checkout page, which lead to an increase in successful purchases
Helped rearchitect a Rails monolith to a set of micro frontends to increase maintainability and decouple key products
Introduced BDD practice to the team to increase stability in new features
Merged multiple repositories into a monorepo, which decreased lead time
Maintained development environment for the frontend team to speed up local testing

And if you can't think of many achievements for a particular role, try describing the project and what it achieved or parts of the software that you built and maintained.

Remember, the impact of your work is more important than the work itself.

Humility > Exaggeration

When writing your CV it can be tempting to exaggerate or show off about the things you've achieved. This might seem appropriate given that you want to wow a potential employer and appear to be superior to other candidates. For instance, I've seen a few CVs that decorate experience or projects with adjectives and impressive numbers.

The problem with this is that it has unintended biases in the mind of the reader. Exaggeration distracts from the facts themselves. The experience on your CV should be able to stand alone without any exaggeration. Being transparent and humble will go a long way, if the facts are impressive they should impress without the extra additives.

As an example, let's say I decided to write on my CV:

Optimised the SEO of the landing page which lead to a dramatic increase of traffic (x10)

Compare this with the following:

Optimised the SEO of the landing page which lead to an increase in the number of users registering

With a small adjustment, the statement is more humble, and focusses more on the impact of the completed task.

Remember, your experience got you to where you are today - it doesn't need exaggeration.

Conclusion

To summarise, here are three tips for writing a CV:

Giving context is important, your work doesn't exist in a vacuum
The impact that your work has is more important than the work itself
Exaggeration only serves to distract, humility will go a long way

Thanks for reading, for more like this follow me here on dev.to or on twitter! 🚀

*NB: I re-wrote this post because I felt it was too negative and that's really not how I want to share my ideas. Any criticism is hugely valuable for me, so please leave any constructive feedback in the comments.

Micro Dark Theme

Luke Barnard — Sat, 22 Jun 2019 15:28:07 +0000

I'm rewriting my personal website at the moment to make it easier to update and add things to. In the process I'm trying to keep things as simple as possible.

When I started designing it, I decided to keep the colour scheme completely black and white, with a few splashes of colour. What I realised was that some might prefer a darker colour scheme as opposed to the brilliant white pages I was developing.

But in my mission for simplicity I was determined to use the simplest implementation to achieve my dark theme.

It just so happens that the W3C is drafting up a new standard for a CSS media query that indicates whether the user has requested a light or dark colour theme for the current website. A few browsers support this today including Chrome, Firefox and Safari. See MDN for the details.

By offloading the responsibility of theme preference to the browser, a dark theme implementation can be as simple as a few lines of CSS:

      #root {
        background: white;
      }     

      @media (prefers-color-scheme: dark) {
        #root, img, .no-invert {
          filter: invert(100%);
        }
      }

The way this works is fairly straight-forward:

When the OS or browser "dark mode" is activated, the CSS in the media tag is applied.
The #root element is inverted from a white background with black text to black with white text (the background colour is required for this to work).
Elements within the root element are inverted again to appear as they normally do.

As expected, elements inverted twice are displayed correctly - see the pills in the top-right:

And for some interesting modifications, other filters could be used in conjunction with invert() such as contrast():

Oh and if you hadn't already guessed, there's also a draft for prefers-contrast in the works - find the draft here - so that the user can avoid a low contrast theme altogether with a bit of CSS!

Fin

Thanks for reading! Follow me for more posts like this 🚀

Emulating Xmonad in JavaScript - Part 4

Luke Barnard — Mon, 27 May 2019 01:40:49 +0000

A lot has changed since I last posted. Namely I have finally given this project a GitHub repo for anyone who wants to follow my progress or even give it a test drive.

The short version

Here's a quick list of updates:

The project is no longer called "shmonad", but rather nomad. This is for two reasons: anyone using this is almost certainly a development environment nomad and secondly, it's an anagram of xmonad when you remove the "x". See what I did there?
As I mentioned, nomad now has a GitHub page, although it is not officially released - use at your own risk.
Nomad now supports background and foreground colours!
The implementation for the sub terminal buffer and scrolling margins is now much more robust.

The longer version

This update has been made possible by my new favourite resource for implementing a terminal, https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences. I have been studying this page in order to better my understanding of terminals but also to realise an improved underlying model of nomad.

The two biggest additions are support for formatting sequences and for scrolling margins.

Formatting

nomad now supports foreground and background colours. The biggest challenge here was understanding how to model ANSI terminal format state and how to apply it when text is inserted. Essentially the problem can be divided according to this diagram:

        // Diagrams to show the insertion of format and
        // it's effect on existing formats, f and the resulting
        // formats, r.
        //
        // format         |---------|
        // f0:              |--|
        // r0:            |---------|
        //
        // f1: |------------------------------|
        // r1: |----------|---------|---------|
        //
        // f2:                   |--------------|
        // r2:            |---------|-----------|
        //
        // f3: |--------------|
        // r3: |----------|---------|

The above diagram shows how nomad splits the underlying format state when a new string of text is inserted. Each line contains a string of text equal in length to the width of the viewport. Each line has a sequence of format states which contain a start index, a length and a definition for how to colour the text it contains.

The method I chose to implement the function responsible for updating the format sequence of a line was TDD. The tests created here have become the first tests for nomad and I hope to add more to cover the vast majority of terminal features. More on this some other time! Suffice to say, a big refactor would really help to make components of nomad more testable.

Scrolling Margins

Some programs (like vim) require correct implementation of scroll margins within which lines of the buffer are shifted when inserting lines, deleting lines and of course scrolling up and down. Previously, nomad worked on the basis of a "scroll offset" - a single scalar value that indicated the viewport offset within the buffer. This is not generally how terminals represent state and was mostly my own estimation.

ANSI terminals in fact use a region of the viewport that represents which lines to scroll under certain conditions and which lines to leave unaffected. This is useful for title bars and footers in GUI-based programs.

As part of my debugging, I found it very useful to carefully look at the output sequences from vim. It allowed me to discern what vim was attempting to do during certain interactions and what nomad was doing wrong in response to that.

Ideally this could have been another opportunity for a TDD-based approach, but in this case nomad is not written in a way that easily allows for this. My current thinking is that each part of terminal state can be considered separate and therefore easily testable.

Fin

Please feel free to leave a comment and share your thoughts and if you're keen for more posts like this, follow me! :)

See you next time folks, thanks for reading.

Emulating Xmonad in JavaScript - Part 3

Luke Barnard — Sun, 24 Mar 2019 23:03:10 +0000

Look! I made more progress!

This week has mostly been bug-fixing and reverse-engineering the functionality of certain control sequences.

One method I've found very useful is opening Terminal.app and running

 $ printf '\e#8'   # fill the terminal screen with "E" (no really)
 $ printf '\e[XXX'

to see what happens!

I'm slowly starting to realise (a) how complicated terminals are, (b) how tricky ANSI control sequences are as an API and (c) that I'm trying to write an ASNI-compliant terminal in Node.js...

This week's post is a short one, and I'll make sure to post another one ASAP.

Fin

Please feel free to leave a comment and share your thoughts and if you're keen for more posts like this, follow me! :)

See you next time folks, thanks for reading.

Emulating Xmonad in JavaScript - Part 2

Luke Barnard — Mon, 18 Mar 2019 23:34:50 +0000

If you squint at the above GIF, you can see that I've made quite a bit of progress since my last post - a great introduction, pls read for context.

Shmonad.js can now spawn multiple child processes and handle their output, buffering it into an appropriately-sized viewport. For now, formatting control sequences are stripped out - these would normally produce a vast array of pretty colours. There are also many, many control sequences that are not yet handled, and I'm still figuring out which ones to prioritise.

My ultimate goal would be to handle enough control sequences to be able to run, say, vim. At the moment, the best it can do is to handle top, which is hugely satisfying to watch, but not very useful on it's own.

bash seems to run pretty well, with auto-complete and reverse-i-search kind of working, but they seem to rely on some control sequences that aren't yet supported.

All in good time!

So how have I made this progress? Well, I took a another deep dive after my last dig into terminals and control sequences. This time, I learned all about pseudo terminals.

Let's take a look!

Pseudo Terminals

Having achieved most of the functionality of Xmonad itself in my previous efforts, I switched focus to the other important part of this project - spawning processes.

In itself, this is not a complicated task. There are well-defined APIs provided by the OS for this and Node.js exposes them in a fairly straight-forward way.

However, programs and their creators have made things complicated.

I'd like to start this journey by looking at the well-known less command. Commonly used for manually scanning and jumping through a file or program output, the incredibly useful and powerful less has been around since 1984 (according to man less).

Piping hot output

When I ran less package.json in my project directory in an earlier version of shmonad, an unexpected thing happened. less appeared to output the entire file from stdout. The whole point of less is that it only outputs a portion of the file to the terminal! So what gives?

I began to look for clues that might indicate what was going on here. A useful tool for debugging the output of a program designed to run in a terminal is cat -v. Piping program output into cat -v will display all control sequences escaped so that they can be displayed in a terminal without being interpreted.

For example, running nvim | cat -v produces the control sequences and text that Neovim uses to render its UI. If you try this yourself, you'll notice the characteristic "[No Name]" somewhere in the mess of "["s. When nvim is running in a terminal, the text "[No Name]" is inserted at a position determined by the current cursor position of the terminal. This in turn depends on the control sequences (and characters) that were previously sent to the terminal.

So you might think - as did I - that running less package.json | cat -v would produce a similar output. However, this is not the case.

The more seasoned POSIX-based developer would be familiar with the fact that piping output from less into another command basically does nothing (without specifying any options to less).

The key difference between Neovim and less in this case is their behaviour when running in a terminal as opposed to streaming output to something that is not attached to a TTY (a legacy acronym that used to mean one of these things):

credit: http://www.classiccmp.org/

Anyway. Vintage terminals aside.

When faced with this difference in behaviour, my first thought was:

There must be a control sequence that tells less that it's running in a terminal.

And I was wrong, again.

Going back to Node.js, I started wondering about the API for accessing stdout and stdin. Part of this API indicates whether stdout/stdin is attached to a terminal, called .isTTY.

This flag is always true for a process that is started within a terminal - useful for when it makes sense to behave differently in a terminal.

Having realised that Node.js provides an interface for such a thing, I naturally assumed that there would likewise be an interface provided by Node.js that allows the program to spawn a process in a way that makes it think it was spawned within a terminal. But these two concepts are very much disassociated: one is an API provided to the current program, another requires creation of processes attached to stdin/stdout streams that are in turn (kind of) attached to a TTY.

Initially, I confused this for "raw" mode of terminals, which is a whole other thing. If you're interested in the 2.5h I spent digging deep into the depths of all this, see this twitter thread. As part of my deep dive, I came across a term "Pseudo Terminals" and decided to take a closer look at these strange creatures. https://en.wikipedia.org/wiki/Pseudoterminal

In some operating systems, including Unix, a pseudoterminal, pseudotty, or PTY is a pair of pseudo-devices, one of which, the slave, emulates a hardware text terminal device, the other of which, the master, provides the means by which a terminal emulator process controls the slave.

At this point, I was like "why didn't search for that before??"

A quick search in my fave search engine provided exactly what I was looking for: a set of Node.js bindings for "Getting certain programs to think you're a terminal, such as when you need a program to send you control sequences - node-pty.

node-pty is an Open Source library for spawning processes in the context of a pseudo terminal. It also supports a lot of different operating systems, which is pretty cool! It also happens to power VSCode, Hyper and a bunch of other really cool terminal emulators.

Having struck this gold mine (yay for Open Source <3), I proceeded to add node-pty to shmonad and with very little modification; it worked like a charm!

The next steps will be to continue to add support for more and more control sequences. The results should be quite amazing, especially when I get around to implementing formatting (which would warrant it's own blog post!)

Prior to supporting all the control sequences in the world, shmonad needs a bit of a refactor.

For now, I'll leave you with more TTYs.

vc303: credit http://www.classiccmp.org

vc404: credit http://www.classiccmp.org

vt100*: credit http://www.classiccmp.org

*: the TTY to popularise ANSI control sequences!!

Fin

Please feel free to leave a comment and share your thoughts and if you're keen for more posts like this, follow me! :)

See you next time folks, thanks for reading.

Emulating Xmonad in JavaScript

Luke Barnard — Sat, 02 Mar 2019 23:29:18 +0000

One of my biggest obsessions is developing as fast as I can type on a keyboard. It has gotten so bad at times that previous managers of mine have suggested adding another column to the Kanban board for dev env optimisation just for me!

You might have seen another post that I wrote about how I deal with the pain of organising my terminals in macOS. Having used xmonad at work for over two years, I couldn't be happier - it's simple, quick and I feel unrestricted despite only using a single monitor. Xmonad does support multiple monitors but I find switching between monitors quite slow, not least for the increased cursor action.

Anyway, I want to explain my most recent project to reinvent my dev env at home. This is an attempt to use the same environment whether I'm at home or work. I'm sure many are faced with a similar dilemma where a Mac is best at home and of course linux is best at work (aside from those working hard on programs that must be developed on macOS or Windows or other proprietary software environents).

To that end, here is my progress so far. This GIF shows shmonad.js (renaming TBC) with the user giving some very basic interactions.

In the GIF, you can see a few boxes being drawn into the terminal. It's not much but eventually this will be a fully-fledged grid-organised terminal multiplexer that I will absolutely put on GitHub for those interested in running it.

Longer term I imagine a plugin-based system that allows for more functionality but let's not get ahead of the game.

How does this work?

Terminal Control Sequences

A while back, terminals were physical devices that came complete with a keyboard, a screen and that's about it. Until floating windows and cursors came along, this was all there was in the way of computer interaction.

In 1978, the VT100 video terminal was introduced by Digital Equipment Corporation, one of the first terminals to support ANSI escape codes.

If you haven't heard of escape codes or escape sequences in the context of terminals, fair enough - you'll almost never encounter them in your daily usage of a terminal as an end user. Essentially, these control sequences allow control of the terminal itself via the output of a program. These control sequences allow programs to control, for example, the colour of the text being sent to standard output or the current location of the cursor within a terminal.

At the time, each terminal shipped with different control sequences and so programs using control sequences were either only compatible with certain terminals or they were forced to use libraries such as Termcap in order to maintain portability.

The ANSI escape codes were proposed as a standard that all terminals could use, making portability of terminal interfaces much simpler. The resulting standard was adopted in 1976 as ECMA-48 (you may recognise ECMA from ECMAScript or ECMA-262, of which JavaScript is a well-know implementation).

Anyway, history lesson over. What are these control sequences and how do they manifest?

You may have encountered them more than you might expect.

Take for example, the very popular shell program, Bash. Bash is a widely-used shell program that allows the user to run commands, build scripts and view program output in a fairly intuitive way. A common misconception is that Bash is a terminal. This is actually false, Bash is a shell program that is most commonly run in a terminal.

For example, I'm writing this article in the following stack:

Vim
(Bash)
Terminal.app
...
macOS

So in my case, Bash (a shell) happens to be running in Terminal.app (the ... terminal).

As I type these words, they appear in within Vim, which displays a text editor GUI in my terminal. It does this by sending control sequences to my terminal (via Bash). Bash isn't doing anything at the moment but if I hit <CTRL-Z>, Bash actually interrupts Vim by pausing it and giving me direct access to Bash again.

You might not think about it too much when you're running commands in Bash, but Bash (and other shell programs) also use control sequences to provide features including coloured text, tab completion, history selection, that annoying "ding" or "beep" you hear when you reach the end of history or if there's nothing to complete when you hit tab, and many more!

Fin

I hope that gave you a better understanding of the foundation upon which my new project rests upon.

Let's call it a day and I'll post another update soon about the inner workings of this terminal multiplexer I'm writing.

Thanks for reading. Leave a comment! See you next time!

Using a text editor for task tracking

Luke Barnard — Thu, 11 Oct 2018 21:44:59 +0000

I find tracking tasks super useful, whether it's work or life admin or shopping, keeping it tracked all in one place can help a lot.

Having recently abandoned iPhone for an Android, I've lost my favourite todo-list app, Clear. Until I've made my replacement (my first Android app!) I've been making do with my text editor to keep things simple.

Simple Task Tracking

First of all, make a log directory to keep task files and a notes directory for taking notes about projects.

Keeping all dev-related stuff in the same place also helps when finding projects, notes, logs etc. quickly. Here's an example directory structure:

ls ~/dev
 log
 notes
 projects
 snippets

log: for task files
notes: for notes about projects, in-depth notes on tasks, etc.
projects: for code whether personal projects or remotely pulled git repos
snippets: for odd bits of code that don't belong in projects

Creating a Task File

Start of by using your editor to create a new file, name it month-year.md, e.g. oct-2018.md.

# Sunday 7th October 2018

Albeit slightly redundant, I find keeping tasks organised by the date they were completed (not created) very useful. Importantly, incomplete tasks are carried over to the next day giving a feeling of baggage - an incentive to get them done ASAP.

After the date, writing a little intro to the day is like a personal pep-talk/complaint section to collect thoughts quickly and succinctly. Mention general goals but nothing structured. Keep it short!

# Sunday 7th October 2018

Feeling positive about getting this stuff done this 
evening. Hoping to share my task-tracking habits with 
others.

 - [ ] Write a blog post about task tracking
 - [ ] Take a look at a personal project

Completing tasks

I'm not certain that Markdown is the best format but so far I've found it quite intuitive and simple but expressive enough for my needs. It's also vaguely future-proof for when I want to write tools to make the process easier.

What Markdown (or at least the GitHub flavour) importantly allows for is marking tasks as done:

 - [x] Start writing a blog post
 - [ ] Publish blog post

Time-based Logging

Recently I've also started adding timestamps to my log so that my thoughts are a little more collected. I think the utility here is in writing, not in reading my thoughts back, but I do occasionally find it useful to see a more detailed view of what I was doing yesterday or last week (especially for pain/happy points in a retrospective sprint review).


# Thursday 11th October 2018

 + 22:18 getting pretty sleepy, might try to finish 
         this blog before nodding off

 - [ ] Finish this blog post
 - [ ] Sleep

Not Completing Tasks

Sometimes the amount of time given to a task is underestimated and it becomes necessary to plan to do the task later. To do this, I move tasks from yesterday to today.

The physical actions of performing this movement of text somehow builds up a sense of baggage and I find it dissuades me from planning to do too much in the day.

Planned Tasks

Occasionally, tasks cannot be done today but only in the future. For these tasks, simply stack a list of date headers at the bottom of the task file, ready for completion when that day comes around. If a task has a time associated with it (e.g. a meeting scheduled during the day), I've found it useful to include the notation @ 10:30 or similar.


# Thursday 11th October 2018

## Log
 + 10:00 forgot to get milk yesterday!! Looking forward to
         banana bread on Saturday though

Kitchen
 - [ ] Buy milk

# Saturday 13th October 2018

 - [ ] Meet with friends @ 14:00
 - [ ] Get ingredients for banana bread

Task Categories

One thing I've found useful is putting headers above groups of related tasks. This is nice for separating tasks at home from those at work, "admin" tasks from leisure tasks, for example.

Me
 - [ ] Netflix
 - [ ] Chocolate
Admin
 - [ ] Setup password manager

(The "Me" category is a personal favourite. Remembering to give yourself "Me" time should be part of your daily routine.)

Prior Work

I'll leave you with some prior work that I want to take a look at. Org mode looks to be task tracking for hax0rs running emacs.

Plain-text task tracking has been done before and I encourage the reader to consider their own system.

Thanks for reading, follow me for more! 🚀