It’s great to see more tools taking advantage of the markdown syntax.
I’m the creator of Mask[0], a very similar tool built with Rust. I was originally inspired by Maid[1], which is an older take on this idea built with Node and no longer maintained I believe.
I see this is based on Node as well, and I appreciate that it currently has zero dependencies. Nice work!
I'm the creator of mask which is another alternative, written in Rust. Our approaches slightly differ. It looks like xc parses the README.md file for commands while mask looks for a maskfile.md by default, though you can provide a --maskfile arg to specify any markdown file that follows the expected format.
In the docs for iommi we've tried both the documentation-centric and the code-centric approaches.
We started with the documentation-centric approach because we had a lot of documentation and wanted to check if the code examples in them worked. So I wrote a bad parser that extracted the code from rST and put them into python files that we then ran. This worked... ok-ish.
Then we switched to the code-centric approach that we use today where we write tests that we generate the documentation from. There are specially marked documentation strings plus some tags for parts of the tests that shouldn't be included in the generated documentation, and some other cool little features like saving down the output of test requests to their own html files and then embedding them with iframes instead of using screenshots.
I am a programmer so I like the code-centric approach more, but they are pretty similar. The big thing is that you need to control the file format/parser yourself.
Before mask, I used a custom bash command runner which relied on a directory structure to implement the command and subcommand tree. This was pretty simple and nice to use. So if it’s working for you, there’s no reason to look for alternatives.
Mask takes advantage of the markdown structure in a few ways. Headings define top-level commands and subheadings represent nested subcommands, which makes it extremely easy to structure a command tree. Also, mask checks the code block lang code (ruby, python, js, fish, etc…) and executes the script using that runtime as long as you have it installed. There’s other features, but those two are great examples why markdown works well as a command definition format.
Use case, I'm on Mac OS X (aka not Linux, not Windows). I have an Apple M1 processor (aka not x86_64). I have 8GB of RAM (silly mistake on my end, I know). Therefore, Docker + virtual machine based solutions are too expensive memory wise.
However, I also like to think in terms of "let me separate this functionality into say... a Kubernetes workload like a pod"
There's no good containerization solution for Mac OS.
Can something like `mask` be used to achieve basically a "poor man's k8s" for a long running service?
Basically, run these 5 or 6 services in parallel, let me be able to see their logs individually.
If not, I completely understand. I just can't tell if there is an actual need for a solution like this, if it already exists and I just can't find it, etc.
Mask can't directly solve this problem by itself, it just runs whatever script you give it. If you can write a python/js/bash/etc script to achieve what you want, you can stick it inside a maskfile with the rest of your commands.
Regarding docker, I haven't tried it on M1 yet. However, I've been using Ubuntu multipass [1] for over a year now and I'm very happy with it. It makes it easy to set up and manage VMs for different projects, and it seems to run very efficiently on macOS in my experience. When a project needs a docker container like postgres, I just run docker compose inside the VM rather than running it directly in macOS. You can also limit the amount of CPU/RAM the VM uses to keep things under control.
Have you tried using a process manager like supervisord[1] or pm2[2]? The former has a pretty clean declarative interface that you could view as a replacement for something like a docker-compose file or a k8s pod config.
You don't get any containerization/isolation benefits obviously, but it sounds like you've already accepted that.
Foreman is a nice, easy to use local process manager. It's what heroku and such use with a simple Procfile for defining multiple processes, but it would work fine for running multiple developer tools, testing services/dependencies, etc.
A bit of feedback: please don't rotate the puzzle piece for me! A huge part of sorting out where a piece goes is figuring out its orientation in space and if you tell em automatically, I miss out on that whole part of the process, and suddenly all the pieces are sorted for me.
This looks fun! One question, your terms mention payments, but I couldn't find any paid content in my short session. What is the business model? Is there a pricing page?
Good question and sorry for the confusion! I originally launched with an optional paid tier which I have since removed. Currently there is no business model. I happily run this at a loss as my costs are very low.
The smudge tool radius idea was especially interesting and something I’ll need to think about further. Very curious how it would affect the UX for beginners vs power users. Could be a great improvement for touchscreen devices as well.
Thank you! I’m aiming to provide a more polished and user-friendly experience than the alternatives out there, and I have many plans to differentiate ever further. Glad you had a good time playing.
Thanks, glad you enjoyed it! As another reply mentioned, single click/tap on a piece auto rotates it to the correct orientation.
Many have pointed out the auto rotation is either too easy or annoying, so I am considering alternatives. I originally started with single click to rotate 90deg but was told by early users it was too hard. Reconsidering ways to introduce this that is friendly to all users.
i tried this trick, and saw a few interesting bugs. obviously this whole trick is an edge case, but i had some visual doubling of my large piece after certain clicks, and also i had an event happen where i heard the click sound stacked up 100 times then the app became unresponsive
Thanks for the report! Firefox was the browser I used during development and also needed the most work regarding performance. The image quality is heavily tied to rendering performance, so I’ll need to consider ways to improve this further.
I solved a hard puzzle on chromium and noticed a lag when picking pieces up but dragging them around was smooth.
Another tip is to make scrolling or some keyboard buttons rotate the pieces, snapping to 90° angles would be a good start. Making the pieces only snap when placed down instead of just when they are close to a compatible piece might also be good.
These things could be togglable or vary between the difficulty modes.
I’m the creator of Mask[0], a very similar tool built with Rust. I was originally inspired by Maid[1], which is an older take on this idea built with Node and no longer maintained I believe.
I see this is based on Node as well, and I appreciate that it currently has zero dependencies. Nice work!
[0]: https://github.com/jacobdeichert/mask
[1]: https://github.com/egoist/maid