joerdav/xc

Markdown defined task runner.

xc - Simple, Convenient, Markdown-based task runner.

Docs | Getting Started | Github

xc is a task runner similar to Make or npm run, that aims to be more discoverable and approachable.

The problem xc is intended to solve is scripts maintained separately from their documentation. Often a Makefile or a package.json will contain some useful scripts for developing on a project, then the README.md will surface and describe these scripts. In such a case, since the documentation is separate, it may not be updated when scripts are changed or added. xc aims to solve this by defining the scripts inline with the documentation.

xc is designed to maximise convenience, and minimise complexity. Each xc task is defined in simple, human-readable Markdown. This means that even people without the xc tool installed can use the README.md (or whatever Markdown file contains the tasks) as a source of useful commands for the project.

Installation

Installation instructions are described at https://xcfile.dev/getting-started/#installation.

Features

• Tasks defined in Markdown files as code blocks.
• Editor integration:
  • VSCode (list and run xc tasks)
  • Vim (recommended config for listing and running xc tasks)

Example

Take the tag task in the README.md of the xc repository:

## tag

Deploys a new tag for the repo.

Requires: test

```
export VERSION=`git rev-list --count HEAD`
echo Adding git tag with version v0.0.${VERSION}
git tag v0.0.${VERSION}
git push origin v0.0.${VERSION}
```

The task could be run simply with xc tag, but a side-effect of it being an xc task is that the steps for pushing a tag without the use of xc are clearly documented too.

$ xc tag
+ go test ./...
?       github.com/joerdav/xc/cmd/xc   [no test files]
?       github.com/joerdav/xc/models   [no test files]
ok      github.com/joerdav/xc/parser   (cached)
ok      github.com/joerdav/xc/run      (cached)
+ export VERSION=78
+ echo Adding git tag with version v0.0.78
Adding git tag with version v0.0.78
+ git tag v0.0.78
+ git push origin v0.0.78 Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
To github.com:joerdav/xc
 * [new tag]         v0.0.78 -> v0.0.78

Tasks

test

Test the project.

go test ./...

lint

Run linters.

golangci-lint run

build

Builds the xc binary.

go build ./cmd/xc

tag

Deploys a new tag for the repo.

Specify major/minor/patch with VERSION

Inputs: VERSION

Requires: test

# https://github.com/unegma/bash-functions/blob/main/update.sh

CURRENT_VERSION=`git describe --abbrev=0 --tags 2>/dev/null`
CURRENT_VERSION_PARTS=(${CURRENT_VERSION//./ })
VNUM1=${CURRENT_VERSION_PARTS[0]}
VNUM2=${CURRENT_VERSION_PARTS[1]}
VNUM3=${CURRENT_VERSION_PARTS[2]}

if [[ $VERSION == 'major' ]]
then
  VNUM1=$((VNUM1+1))
  VNUM2=0
  VNUM3=0
elif [[ $VERSION == 'minor' ]]
then
  VNUM2=$((VNUM2+1))
  VNUM3=0
elif [[ $VERSION == 'patch' ]]
then
  VNUM3=$((VNUM3+1))
else
  echo "Invalid version"
  exit 1
fi

NEW_TAG="$VNUM1.$VNUM2.$VNUM3"

echo Adding git tag with version ${NEW_TAG}
git tag ${NEW_TAG}
git push origin ${NEW_TAG}

update-nix

Updates nix flake.

sh ./update-nix.sh

install-hugo

Install hugo via go install.

go install github.com/gohugoio/hugo@latest

run-docs

Run the hugo development server.

Directory: doc

hugo serve

build-docs

Build production docs site.

Directory: doc

./build.sh

xc's Issues

Ability to use a separate tasks file for dev environment

Having tasks auto-documented by using xc is a strong selling point for the tool, however for projects/repo's with a huge amount of existing tasks, it's daunting to transition if you'd end up with a README that's 4 pages long.

There's currently the -f flag to point to a specific file to be used for running tasks, however I think a QoL addition would be to add a --dev flag that automatically looks at a specific dev tasks file (TASKS.dev.md for example).

Using a flag means it's obvious what's happening and we avoid conflicts with task names, such as if a team has a task dev and a subcommand was added for dev tasks (xc dev task1) there would be conflicts between the task and the subcommand and this could break some existing workflows.

Alternative markdown syntax to define `Tasks section`

Is your feature request related to a problem? Please describe.
Referring to this: https://www.markdownguide.org/basic-syntax/#alternate-syntax

When using:

Tasks
---

Should also be allowed to define the Tasks section as it is an allowed alternative syntax to the H2 header. Currently xc doesn't detect it

Describe the solution you'd like
XC cli works with the alternative syntax

Describe alternatives you've considered
An alternative is to just keep as-is, but document clearly that it's not supported

Tagged in `v0.0.159`

# GitHub CLI api

https://cli.github.com/manual/gh_api

gh api
--method DELETE
-H "Accept: application/vnd.github+json"
-H "X-GitHub-Api-Version: 2022-11-28"
/repos/OWNER/REPO/actions/artifacts/ARTIFACT_ID

Support for mutli-line tasks

I wanted to create a multi-line task, but it's outputting a single line:

Is that expected?

### serve-local-tests

Run a local Gemini server.

```sh
echo add '127.0.0.1       a-h.gemini' to your /etc/hosts file
openssl ecparam -genkey -name secp384r1 -out server.key
openssl req -new -x509 -sha256 -key server.key -out server.crt -days 3650 -subj "/C=/ST=/L=/O=/OU=/CN=a-h.gemini"
go run ./cmd/main.go serve --domain=a-h.gemini --certFile=server.crt --keyFile=server.key --path=./tests
```

:sloth: Feature request > Interactive xc (TUI)

❔ About

Being able to run/discover tasks in an interactive way can be very convenient.

Today, we can run xc to get the list of available tasks.

👉 The purpose of this tasks is to offer a new (and cool 🤓 ) way to achieve this.

🎯 Feature request

The main idea would to offer a cool TUI user experience on top of xc with the following Charm tools

• bubbles
• lipgloss
• gum

At this end, we could run :

xc --interactive
xc -i

... and land on the following kind of user experience (eg. interactively list/run tasks):

feature: add executed task to shell history

I'm enjoying using the interactive mode. One thing I've noticed, is that I'll often run xc, select docker-build and it will start.

Then I'll make some changes, and want to run it again, so I'll press the up arrow on the keyboard, or I'll use Ctrl+R to search, but docker-build is not in the history.

I think it would be a case of adding a line to either .zsh_history if the shell is zsh, or .bash_history is the shell is bash.

I can put a PR for that together if you like.

Include a demo gif of xc being used in command line

https://github.com/charmbracelet/vhs

ℹ️ I can make one for you and PR the code and webm, gif & mp4 if you want to

Support for other task languages

Many markdown renderers, including Github&Gitlab Flavored markdown support specifying a language for syntax highlighting.

It'd be awesome to use this to specify a different shell/interpreter for tasks

eg,

```bash
cp foo bar
```

will explicitly run bash

and

```python
import json
print(json.load(open('foobar.json')))
```

would invoke python instead

passing args to tasks

When we were doing exe/md we supported passing args.

I wouldn’t say it was a homerun, it had caveats we hadn't resolved.

Anyway, thoughts?

Update Requires attribute to allow inputs to be specified

Currently a task dependency can only be defined if the required task has no inputs, or if the inputs are provided via environment variables.

The following should become valid:

# Task-a

Inputs: A

```
echo $A
```

# Task-b

Requires: Task-a hello

Require environment variables to be set

In C projects (and others), it's common practice to require an environment variable to be set to inject things like WIFI SSIDs.

https://gitlab.com/slimhazard/picow-http-example

$ cmake -DPICO_BOARD=pico_w -DWIFI_SSID=my_wifi -DWIFI_PASSWORD=wifi_pass \
        -DHOSTNAME=picow-sample -DPICO_MBEDTLS_PATH=${PWD}/../lib/mbedtls ..

It would be awesome if XC could require that an environment variable is set from outside, or could pick up a file that could be .gitignored to load that.

Associative array support

Hello!

Does the tool support associative arrays?

I tried to define a task with arrays something like this one:

declare -A demo                       
demo["main"]="Main demo"              
demo["json-min"]="JSON min"           
demo["load-session"]="Load session"   
                                      
for i in ${!demo[@]}; do              
 	echo "$i-> ${demo[$i]}"            
done                                  

output of xc:

imgur｜ + demo='Main demo'
imgur｜ + demo='JSON min'
imgur｜ + demo='Load session'
imgur｜ + for i in ${!demo[@]}
imgur｜ + echo '0 -> Load session'
imgur｜ 0 -> Load session

Add a motivations/benefits section to the README

Hi,
can you clarify what are the benefits of xc vs make?
Regards,
Andrea

Run dependencies only once

Given the following README.md:

## Tasks

### a
```sh
 echo "a"
```
### b
Requires: a
```sh
echo "b"
```
### c
Requires: a
```sh
echo "c"
```
### d
Requires: b, c
```sh
echo "d"
```

Running xc d gives me:

$ xc d
+ echo a
a
+ echo b
b
+ echo a
a
+ echo c
c
+ echo d
d

I'd expect task a to be run only once. Is there a way to get that behavior?

Using variadic inputs to pass cli arguments

I'm not sure if this is an anti-pattern or a bug. I'm trying to use a task for both testing during local development as well as generating a test report in a CI pipeline.

<!-- README.md -->

## Tasks

### test

```bash
poetry run pytest $@
```

When I am testing locally I can run xc test no problem. If I have the CI run xc test --junitxml=junit.xml I get this error:

xc: failed to compose script: invalid option: "--"

:sloth: Feature request > Support emojis in tasks names

❔ About

While reading a markdown with sections, it's comfortable for humans to get an emoji at the beginning of section name.... but when we want to get or call a task from its name, it's more comfortable to only call the alpha version (no emoji) of the task.

This issue is about that

🎯 Feature request

• Be able to set an emoji in front of the Tasks section
• Be able to put an emoji in front of any tasks name (## :heavy_check_mark: mytask... but be able to call them just by calling xc mytask

💰 Benefits

• Nicer readme's
• Makes a better description of the tasks
• Make xc tasks seamless
• Encourage people to package tasks with xc
• Give more meaning to the tasks as emojis can help illustrate and describe things

Feature request: Env: support backticks?

Not sure if this is just my vim config, but the underscores aren't liked by Markdown.

This would usually lead me to putting them in backtick fences, but not sure if xc supports this.

Compare with other Markdown task runners

It would be useful if the documentation compared xc with its closest alternatives, maid and mask. It looks like maid, mask, and xc are the three prominent task runners based on Markdown.

Support short/long option aliases

Most options of the CLI have both a short and a long version. Notable exceptions are -version, which only has a long version, and -y, which only has a short one. For consistency, these two could have both variants.

Here's what I'd suggest:

• -V as the short variant of -version (since -v is often used for --verbose)
• -noprompt as the long variant of -y

Additionally, perhaps consider changing -md to -n/-dry-run, since the format of the task definition document should not be relevant — i.e., it should be possible to eventually make xc support AsciiDoc, reStructuredText, and other lightweight markup formats.

create a github action runnner

Would be good to have a github action on the marketplace to avoid having to install xc mannually in GHA

banner

unable to get description for given task name

hello!

I had a script which used to do this

xc $(xc -f docs/TASKS.md -s | fzf --preview 'xc -md {} | mdcat')

it looks like the -md flag has been removed, but I cannot see when or why

Running task dependencies async

I am testing this out from using Mage, and one thing I liked was that dependencies were run async.

This enabled a nice development experience where I could run mage watch:all and have it run different watchers (server, npm, templates) asynchronously.

However, in XC, it appears that dependencies are run in sequence which means I cannot easily achieve the same unless I write a custom script for this.

Is there a way around this?

Run tasks defined in a parent directory.

Is your feature request related to a problem? Please describe.
When in a sub-directory of a project that has an xc file defined at the root, you can't run tasks defined said xc file.

Describe the solution you'd like
When running xc in a folder that does not contain a README.md with tasks definied, search in parent directories.

Describe alternatives you've considered
An alternative is to just keep as-is, to prevent (potentially) unexpected behaviour.

I'm a fan of this idea, I just want to make sure all the options have been thought about!

          I'm a fan of this idea, I just want to make sure all the options have been thought about!

The things I'm thinking about when I'm looking at features for xc are:

• Would the running of the task be convenient? (In this case yes, an additional flag isn't too bad)

• Is it a pain to construct it? Nope, it's the same as other xc tasks but in a different file.

# GitHub CLI api

https://cli.github.com/manual/gh_api

gh api
--method DELETE
-H "Accept: application/vnd.github+json"
-H "X-GitHub-Api-Version: 2022-11-28"
/repos/OWNER/REPO/actions/artifacts/ARTIFACT_ID# GitHub CLI api

https://cli.github.com/manual/gh_api

gh api
--method DELETE
-H "Accept: application/vnd.github+json"
-H "X-GitHub-Api-Version: 2022-11-28"
/repos/OWNER/REPO/actions/artifacts/ARTIFACT_ID

Make `xtrace` optional

xtrace output is useful in some cases, but in general would be better if not enabled. This is on by default and it seems there is no way to disable it for xc. A -x or -v flag would be useful for enabling this output when desired.

Add adriens tutorial on xc to the docs site

https://dev.to/adriens/runnable-readmes-w-xc-1c6d

:pray: feature request > auto complete

it would be awesome so, like in make to be able to autocomplete (TAB) xc targets 🙏

feature request / idea: interactive menu

From Vim, it would be great if you could hit, leader t or something, to list xc tasks and run one.

So you'd press leader t, then 1, 2 etc. to run that task, or escape to quit.

:map <leader>t :!xc build<cr>

Unfortunately, interactive commands produce a mess of escape codes in Vim.

However, something like https://github.com/christoomey/vim-run-interactive would need to be used to provide the interactivity of the picklist.

Support for multiple shells(os specific)

Right now it is not possible to use runner in different OS, but it would be so nice to have this options. It could be implemented throw OS/shell specific comment or any other way.

Configurable 'tasks' heading?

Love the idea of xc. Thank you. I'm coming at this from a slightly different angle, is there any appetite for making the name of the tasks header configurable?

I would really like to use xc to check that the examples in our docs work. Being able to use "Examples" as the header instead of "Tasks" means the docs would still make sense for the reader.

Error pages for docs site

The docs site currently has no custom 404 page.

Pass colorized output to log from underlying command

If the task being run has a colorized output when run without xc, I think xc should pass that colorized output through.

Trivial example:

A more valid example is that when using testing suites like pytest where successful tests are shown in green and failures in red.

Support markup languages other than markdown

It would be nice if xc supported task definition documents in formats other than markdown — for example AsciiDoc, reStructuredText, and other lightweight markup formats.

Note: This is just speculative at this point, according to @joerdav's comment here:

at this point I think sticking to markdown and getting it working well with that format is where I want to work on for the time being.

Change required inputs message

First of all, thank you for this magnificent tool. It always makes me happy to see markdown and code combined together (I implemented a ruby gem that runs tests embedded in markdown :)

One minor suggestion:

When there is a required input that is not entered, the error message is:

Task has required inputs:
        xc hello [NAME] [HEIGHT]
        NAME=[NAME] HEIGHT=[HEIGHT] xc hello

I believe the square brackets are incorrect in this context, as they denote "optional".

Perhaps this?

Task has required inputs:
        xc hello NAME HEIGHT
        NAME=... HEIGHT=... xc hello

or, the below which creates a distinction between an environment variable name (CAPS), and a <placeholder> string:

Task has required inputs:
        xc hello <name> <height>
        NAME=<name> HEIGHT=<height> xc hello

Note that in this case, it is common to have the string between <...> in lowercase.

Required tasks should inherit inputs (Or be able to map inputs for task X to inputs for required task Y)

Given:

• a task X with zero or more inputs
• a task Y with one or more inputs
• a requires relationship from X to Y
  When:
• i execute task X with inputs needed for task Y
  Then:
• The execution of task Y should have access to inputs provided when running task X

For example, given a readme:

Tasks

y

Inputs: v

echo my inputs are $v

x

Requires: y

echo 'hello world'

this invocation will work:
v=hello xc x

but this one will fail:
xc x hello

Likewise, this readme will also fail in the same way as described above:

Tasks

y

Inputs: v

echo my inputs are $v

x

Inputs: v
Requires: y

echo "$v world"

Document github actions on xcfile.dev

:name_badge: Please provide a ready-to-use md badge :memo:

❔ About

We tend to use xc on vairous projects and I would like peple to be aware that the reposiotry uses xc to describe various available tasks.

👉 Providing a badge would help a lot 🦥

🎯 Feature request

• Provide a ready to use markdown badge we could copy/paste on top of our README.md
• Make it clickable so it makes people land to https://xcfile.dev/

💰 Benefits

• No need to tell people what the README is capable of... nor how to use it 🦥

Support for multiple commands in subdirectories

I'm trying to build something that requires changing directory.

My first attempt didn't work:

### build

Builds the project.

```sh
cd api && go build ./...
cd cdk && go build ./...
```

So I broke it down into two steps:

### build-api

Directory: ./api

Builds the API.

```sh
go build ./...
```

### build-cdk

Directory: ./cdk

Builds the CDK project.

```sh
go build ./...
```

### build

Requires: build-api, build-cdk

Builds the project.

However, this produces the error:

missing command: near ### run-dynamodb-local

If I put in an empty command block, then I get:

.: 
fork/exec : no such file or directory

Suggest allowing empty commands which have "Requires" sections, or identifying where a shell expression is being used via backtick denotion of sh and using shell execute instead of locating the binary on the path.