problem: command source files are implicitly wrapped by a function

[meleu]

Description

I have a pet peeve with the way we need to deal with the "command source files".

I'm talking about the fact that we're handling code that will be wrapped by a function and this fact is not explicit.

Two bad things results from this:

1. It's a cognitive load. Something the developer needs to remember. I'm already used to it but when I'm onboarding a new contributor I need to explain this detail.
2. It confuses some tools, like linters and LLMs.

example

In a previous conversation @DannyBen mentioned:

you should not shellcheck the partial snippets, but just the final script.

Some points about this:

• I really enjoy having a linter right into the editor, highlighting issues as I type them, exactly where they are, in a way where I can quickly handle them.
  • Also, my colleagues are not bash nerds like me. So having shellcheck in their editors is useful for them, as a learning tool
• If I only shellcheck the final script, I need to configure pre-commit git-hooks/CI validation and spend human resources in the PR process

So... What I always end up doing is tweaking a .shellcheckrc and some # shellcheck disable=XXX here and there in order to still use shellcheck in bashly partials.

proposed solution

Note: I'm not taking into consideration the challenge of actually implementing it, just sharing what I think would be ideal as a bashly user.

A "command source file" should explicitly have a function, named with the same pattern it has today: <app>_<subcommand>_command.

What I see as ideal is bashly build automatically validating if the file has a function with the right name, interrupting the build if not.

[DannyBen]

I am considering this:

1. We add some setting like explicit_command_functions: true or some other easier name.
2. If it is true, all the command templates will be generated with the som_command() { wrapper in the files, and bashly will no longer generate it internally
3. There will be no parsing of the bash partials to ensure this is done by the user. If not done, things will break. Similar to how functions in lib are not checked that they are functions.

To my understanding, the only real advantage this brings is to stop confusing in-editor linters.

This is so far the only implementation I feel somewhat comfortable with.

Interested to hear opinions. @meleu, @pcrockett and anyone who has an opinion on the matter.

[meleu]

That solves the problem I described.

Automatic checking would be a plus, but as an explicit opt-in, the user is/should be aware of what they need to do.

Summing up: that's a nice solution! 👍

[DannyBen]

There are a few concerns with this proposal that I think are worth considering.

Today, Bashly owns the generated command function and the user owns only its body. In an explicit mode, responsibility for the function name moves to the user. This creates two sources of truth: the command and optional function name in bashly.yml, and the function declaration in the command partial. Renaming or restructuring a command would then require updating both places.

If they get out of sync, the generated script may still build successfully, with the error becoming visible only when that particular command is executed. We could consider validating the function declaration during generation, but that would mean inspecting user-supplied Bash and deciding how strict or flexible that inspection should be.

The generated function is also more than an implicit wrapper around the partial. It is a Bashly-owned insertion point. For example, command-level variables: are currently generated at the beginning of the function, before the user's code. An explicit function would leave Bashly without a clean place to insert that code: it would need to modify or interpret the user's function, generate the declarations somewhere else, or make the two features incompatible. The same question could arise for future features that need to prepend command-specific setup.

None of these points necessarily decides whether explicit command functions should be supported, but they make the change broader than conditionally omitting the generated opening and closing braces.

[DannyBen]

I have another possible approach that may address the main concerns raised here without introducing a separate command-source mode.

We could allow command partials to optionally use a reserved bashly_command() envelope:

bashly_command() {
  local filename="${args[filename]}"
  echo "$filename"
}

When loading the partial, Bashly would recognize this exact envelope, remove its opening and closing lines, and insert the body into the real generated command function as it does today. The body would be inserted verbatim rather than indented again, since it is already formatted as a function body.

The generated result would remain:

cli_download_command() {
  # Any Bashly-generated command setup, such as variables, remains here.
  local filename="${args[filename]}"
  echo "$filename"
}

This would be optional. Existing unwrapped partials would continue working exactly as they do now.

The reserved function is only an editor-friendly envelope; its name is not used in the generated script. Bashly therefore retains ownership of the real function name, and bashly.yml remains the single source of truth. Renaming or restructuring a command would not require changing its partial.

At the same time, the partial becomes a complete function as seen by developers, linters, and other editor tooling. Constructs such as local and return are then understood in their actual function context.

This also preserves Bashly's ability to prepend generated code inside the real command function. For example, command-level variables: can continue to be emitted before the user's body, without modifying the user-owned partial or generating them in a different scope.

Since the enveloped body is already indented by the user, Bashly would preserve it instead of dedenting and reindenting it. This should also preserve heredocs exactly as written.

The contract could remain intentionally narrow: recognize the canonical bashly_command() { opening and a final }. This avoids trying to parse arbitrary Bash while giving users who value editor linting and explicit function context a natural way to opt into it on a file-by-file basis.

Thoughts on this approach?

[meleu]

We could allow command partials to optionally use a reserved bashly_command() envelope

I'm not comfortable with this approach.

It can solve the confusing in-editor linters issue, but the cognitive load persists. The developer still need to be aware of a "bashly-thing" to handle in their code.

---

The generated function is also more than an implicit wrapper around the partial. It is a Bashly-owned insertion point. (...) An explicit function would leave Bashly without a clean place to insert that code

Maybe in the run's case $action options, before calling the command function.

(Unfortunately I don't have enough context of bashly implementation challenges to provide valuable options here, so my input here is mostly with the user's point of view.)

[DannyBen]

The developer still need to be aware of a "bashly-thing"

This is an important point. The command code is a "bashly thing". Hiding this fact is a disservice to the developer.
Unlike the "regular" lib functions, which are just brought in as is, and of no concern to bashly, your command code is the joint between what bashly does, and what the developer does. It is NOT a regular function, and masking it as such will pretend it is something it is not.

I was trying to solve the linter problems without jeopardizing the integrity of the script and without communicating a false sense of ownership over the function name and role.

Maybe in the run's case $action options, before calling the command function.

Thought about that. It is not how I would write my command function - the injection to the head of the function is specifically designed like this and polluting the case statement is just trading one problem with another set of problems.