Hallucigenia

Sections

• Purpose
• Dependencies
• Installation
• Usage
  • Setting up repositories
  • Branches & Side Effects
  • Watcher
  • Checking and deleting connection
• Developing
• Motivation
• Limitations
• TODO's

Purpose

• Register your BitBucket repositories;
• Mark branches to be observed;
• Clone on detecting changes;
• Run side effects locally over them;

Dependencies

• git

Installation

install the CLI globally using your preferred package manager.

npm install -g hallucigenia

Usage

First of all, type hallucigenia on your terminal to run the CLI.

Setting up new repository

Follow the steps on the video bellow to set up a new remote connection with Bitbucket repository.

NOTE: The repository access token only needs the "read" permission on repository level.

Observing branches and writing side effects

Follow the steps on the video bellow to mark the branches on certain repositories to be observed and how to write side effects to run when they get updated.

Make sure to read the instructions shown when you are about to write a new side effect, they are important!

NOTE: the text editor opened to write the side effects is the default of your system.

Watcher

The following video shows how to run the watcher mode and the result of a side effect

The watcher mode will look for changes on observed branches of all repositories which may result on multiple calls to the Bitbucket API, for that reason we have a fixed cool down of 1 minute between checks so you don't DDoS them.

Note that we use the $UPDATED_BRANCH_PATH environment variable on the side effect script to know where the cloned branch is located and move it.

Checking and deleting connection

If you have problems watching a branch or updating the branch list of a repository, your access token might have been revoked, in that case you can check the connection with the repository as shown on the following video and delete the connection before setting it up again.

NOTE: soon will be possible to edit the connection details!

Developing

After cloning the repository, open the folder on your terminal and install the dependencies using your preferred package manager.

npm install

Build all the .ts files to a single hallucigenia_d.js on the /dist folder and execute it with the dev command.

npm run dev

Alternatively, you could run build:esbuild and link the project to make the "hallucigenia" command available on your terminal, but if you already have the package installed globally it may confuse your package manager(dunno, didn't tried tbh ¯\_(ツ)_/¯).

// not recommended

npm run build:esbuild

npm --global link

hallucigenia

Motivation

This CLI was intended to be only used internally by a client, which needed a simple way to deploy and test(locally) whenever some branches from his bitbucket repository got updated. Since I saw some people looking for something similar while doing my research, I decided to make it public.

Limitations

WIP

TODO's

[ ] Encrypt data on .conf files [ ] Make the "watching" feature an independent process