norskeld / arx

Simple and user-friendly command-line tool for declarative scaffolding.

Hello! 👋

I'm a Rust, TypeScript, and functional programming aficionado fascinated by design of compilers and programming languages. Sometimes I write music, mostly drone-ambient, which is available for free on my Bandcamp and Spotify.

Stuff

Web

• nrsk.dev Astro TypeScript Tailwind — Personal website & blog.

Interpreters/languages

• zeal Rust — Statically-typed, GC-less programming language.
• attolog F# — Minimal Prolog interpreter.

Command-line apps

• diceware Rust — Rust crate and CLI for generating Diceware passphrases.
• pingmole Rust — CLI that helps to filter Mullvad VPN servers and pick the closest one.
• arx Rust — Simple and user-friendly command-line tool for declarative scaffolding.
• rsx Rust — Micro CLI for interactive execution of npm & yarn scripts.

Libraries

• sigma TypeScript — TypeScript parser combinator library for building fast and convenient parsers.
• backpack TypeScript — MessagePack implementation with back-referencing extension.
• astropress TypeScript — Astro integration for images and SVG compression.
• unindent TypeScript — Microlibrary for unindenting multiline strings.

arx's Issues

feat: allow to use local repositories

Description

This will allow one to run arx like this...

arx file:~/templates/repo

...to scaffold a new repository in the current working directory using /Users/vm/templates/repo as the template.

Implementation

This will essentially add a variant to RepositoryHost enum, e.g. RepositoryHost::Local or RepositoryHost::File. The latter looks a bit more natural since it resembles file:// protocol or local file:.. dependencies in npm packages.

Regarding the actual "fetching", I think leveraging git would be the way to go, because it is easier and more consistent. Hopefully git ls-tree or git ls-files will do:

git ls-tree --full-tree -r --name-only HEAD

Or:

git ls-files

Why not just copy the repo directory? Well, this is needed to avoid copying files and directories that are .gitignored and present (node_modules, dist, .idea, and so on). And then we can simply copy them & kick off replacements and actions.

Notes

• Check arguments and options for git ls-tree and git ls-files to make sure it still will be possible to specify branches, tags or commits.
• Rewrite parser a bit to allow arbitrary paths after file: host specifier.
• Make sure the shell expansions (~, $(), {} and so on) still work (why wouldn't they though?).

feat: cache

Implement caching mechanisms to avoid fetching tarballs if they were downloaded and saved in the cache.

feat: allow to specify config name/path

Defaults to arx.kdl at the repository root. Should work with #14.

fix: warn on unknown injects

Right now only unknown actions get reported.

feat: allow to specify subdirectory as source

While you can't download a specific directory from a repository using GitHub API or direct links, such functionality would be useful/desirable in some cases.

For instance, we may have a repository with multiple templates located in different subdirectories:

repository
├── code-style
│   └── arx.kdl
├── frontend
│   └── arx.kdl
└── server
    └── arx.kdl

We should be able to use one of them as the template. What should be added:

• CLI option, e.g. arx remote user/repo#ac75a88 --path frontend
• Ability to specify a directory using the source syntax, e.g. arx remote user/repo@frontend#ac75a88

feat: add output verbosity control/levels

By design arx is verbose (and pretty!). One should be able to opt-out via a CLI option. Not sure about introducing "levels" (e.g. "all", "warnings", "none"), I would rather implement a kill switch that completely turns off everything except errors.

feat: implement conditional execution of actions

Description

It would be nice to be able to run actions conditionally, e.g. based on user input from prompt actions or depending on the user OS (#11 probably should be closed in favor of this feature, but I'm not sure).

Example

actions {
  confirm "should_commit" {
    hint "Whether to stage and commit everything on finish"
    default false
  }

  number "magic_number" {
    hint "Enter magic number"
  }

  run when="should_commit == true && (magic_number == 42 || magic_number == 420)" r#"
    git add .
    git commit -S -m 'chore: init repository'
  "#
}

Notes

• I'll need to implement a simple expression parser (with precedence and grouping) and evaluator.
• It'd be a good idea to add a distinct prompt for numbers. Done.

feat: allow to restrict on which OSes actions allowed to run

Could be useful to allow specifying OS requirements, both on single actions and suites. Allowed OS values will map to std::env::consts::OS + explicit "all" (which should be the default).

With single actions:

actions {
  run "command" os="all"
  run "command" os="windows"
  run "command" os="linux"
}

With suites:

actions {
  suite "init os="all" { ... }
  suite "win-specific" os="windows" { ... }
}

With actions in suites (overrides value defined in a suite node):

actions {
  suite "init" os="all" {
    run "command" os="macos"
    run "command" os="windows"
  }
}

fix: do not try to process replacements on binary files

It's a good idea to check if a file is binary to skip processing replacements on it.

content_inspector should be enough to cover most of the cases.

feat: mvp

What should be implemented in MVP:

• Downloading repository tarball allowing to specify branch, commit or tag.
• Parsing of the arx config.
• Running actions.

Comprehensive example with rules is here.

Basic output/logging for actions with something like fern + log wouldn't hurt either.

refactor: look into using `ripgrep` crates

Specifically https://docs.rs/ignore looks very interesting since it provides parallel recursive directory iterator (WalkParallel) which may come in very handy.

Not that my (admittedly, poorly written) Traverser does a bad job, but it definitely could be improved.

feat: cleanup on failures

I think this should be opt-in via CLI flag. This should not remove existing target directory in case of failure (and it will fail, since we don't allow scaffolding into existing directory).

feat: allow to use git-less local templates

Basically the title. Right now it is required a template to be a git repository, which may be inconvenient in some cases.

feat: report which replacements were actually performed