Problem:

We currently use just and Justfiles to help document and automate tasks which developers do when working on the code bases.
This works fine, but has some limitations.
We would also like to reduce the number of minimum dependencies required to work on a Catalyst Project to:

1. Docker
2. Earthly
3. Catalyst Forge CLI

Solution:

Replace just with a command runner built inside Catalyst Forge.
We follow a principle outlined in: https://en.wikipedia.org/wiki/Literate_programming

Proposal.
In a Project we currently require two files:

• Earthfile
• blueprint.cue

To these we add a third optional file, which lives beside these files in the repo (for discoverability):

• Developer.md

Developer.md is both Documentation that developers need in order to be able to effectively and quickly work on the project, and embeds common tasks which developers do regularly.
In essence, this file is a regular markdown file, and code blocks can contain scripts which are executable, on demand by the forge cli.
This approach should improve our developer documentation and on-boarding.

We employ a certain structure to the markdown to allow documentation to be extracted, and for commands to be reliably found.

The Forge CLI will be enhanced using this library to parse the Developer.md files:
https://github.com/yuin/goldmark

Tasks

• Create initial subcommand to work with the markdown definition #65
• Add autocompletion when looking up commands from the markdown definition #66
• Implement markdown files discovery within the working repository #73
• Implement the markdown file to support target parameters.
• Implement the markdown file to support target platforms.
• Implement the markdown file to support denpendencies commands.
• Define proper documentation/specification