bashly-framework/bashly

1. What this repo is

Bashly is a Ruby-based CLI framework and generator whose primary output is a single generated Bash script. The Ruby app is the build-time engine; the generated Bash script is the runtime artifact used by end users.

2. Top-level execution boundary

The main entrypoint is bin/bashly, which loads the Ruby library under lib/bashly. From there, the app exposes subcommands such as init, generate, add, render, validate, doc, preview, shell, and completions.

3. Command-line application layer

lib/bashly/cli.rb and lib/bashly/commands/* define the user-facing tool behavior. This layer handles orchestration: parsing CLI arguments for Bashly itself, dispatching to a subcommand, and coordinating file I/O and output generation.

4. Configuration input model

Bashly is driven by YAML config files, with schema definitions under schemas/ and templates under lib/bashly/templates/. The key inputs are the CLI spec file (bashly.yml), optional settings, and optional strings/override files. These define commands, subcommands, flags, arguments, env vars, and doc output.

5. Domain model for generated scripts

The lib/bashly/script/ directory contains the internal representation of the target Bash program: commands, flags, arguments, dependencies, environment variables, variables, catch-alls, and wrappers. This is the core abstraction layer that turns YAML configuration into a structured script model.

6. Validation and introspection

The script/introspection/ and config_validator.rb code enforce structural rules before generation. This is where Bashly checks things like uniqueness, required fields, flag/argument constraints, command naming, and visibility/private/public behavior so invalid CLIs fail early.

7. Rendering pipeline

The generation step uses a template/rendering system under lib/bashly/views/ and lib/bashly/render_context.rb / render_source.rb. The views are .gtx templates for assembling the final Bash script sections: wrapper, parsing, usage text, command dispatch, validations, hooks, and helpers. This is the main transformation boundary from model to output.

8. Generated script composition

The script output is intentionally modular before being flattened into one file. The views include reusable pieces for command filtering, arg parsing, help text, global flags, initialization hooks, and command bodies. That design makes the final script standalone while keeping generation maintainable in Ruby.

9. Optional framework-style libraries

lib/bashly/libraries/ contains built-in reusable assets that can be injected into generated CLIs, such as:

- completions support

- colors

- INI/config management

- YAML helpers

- stacktrace handling

- validations

- hooks

These are treated as reusable bundled features rather than part of the core parser.

10. Docs, completion, and auxiliary outputs

Bashly also generates supporting artifacts: shell completions, Markdown/manpage docs, and example command/help output. The render-specific libraries under lib/bashly/libraries/render/ and the docs templates under lib/bashly/docs/ support these secondary outputs.

11. Examples as architectural contracts

The large examples/ tree is not just samples; it documents supported shapes of the configuration and generated script behavior. Each example is a small end-to-end workspace with its own src/bashly.yml, command files, optional libs/settings, and test script, showing how the generator behaves across features.

12. Test strategy

spec/approvals/ captures approved outputs for generated scripts, docs, and examples, while spec/bashly/ contains unit and integration coverage for the Ruby generator itself. This strongly suggests the repo is validated by output comparison, not only by internal unit tests.

13. Distribution and packaging

The project is published as a Ruby gem and also packaged as a Docker image. That means the generator is meant to run both in a local Ruby environment and in containerized CI/tooling workflows, but the architecture remains centered on “Ruby generator -> Bash output.”

14. Overall data flow

The main flow is: user config files and command source files go into the Ruby generator, the config is validated and converted into an internal script model, templates render the model into a standalone Bash script, and optional docs/completions/support files are emitted alongside it.