Command Runner

[jdc-pub]

Proposal

Thanks for your careful work on this project! I suspect AsciiDoc will be really helpful for technical documents as LLM workflows continue. I have an idea for a feature that's entirely out of the current scope, but I thought I'd run it by you in case there's interest in keeping the functionality here in this repository. Otherwise, I'll make another repository as an extension.

I'm proposing a new acdc run command runner which can read commands from .adoc files, with attributes used to encode command metadata. If you think this repository would be a good home for this functionality, I'd like to contribute the feature and help maintain it. Like I said above, otherwise I'm happy to make a new extension repository and import this project's crates as external dependencies.

Usage

README files often contain commands to help build packages, install dependencies, etc. We could use block attributes to mark a verbatim / source block as a command, and list dependencies on other commands. For example, see the build and test command examples immediately below: user could invoke acdc run build and have build instructions pulled automatically (from the README by default).

== Building

This project uses the `cargo xtask` convention.

[command, id=build]
[source, bash]
----
cargo xtask build
----

## Testing

Similarly, use `cargo xtask` to test all components.

[command, id=test, deps=build]
[source, bash]
----
cargo xtask test
----

Mechanics

We could use a particular attribute, e.g. command, as a sentinel value indicating that block should be treated as an executable command. Document level metadata could be used to set the default shell, and specify other global configuration options. The actual source, bash specifier would only be for clear rendering in forges, e.g. GitHub.

Optionally, users could add substitution capability to their verbatim/source blocks, which could be a powerful feature for a command runner.

Alternatives

I see this acdc run proposal as combining just with mask, but with AsciiDoc instead of Markdown.

Forward Work

If you wanted to collaborate on this here in this repository, I'd sketch up an MVP on a branch for your review to get a feel for how this could work. Regardless, thanks for your time and acdc!

[nlopes]

Oooh that's a neat idea. Let me get to the weekend and then I can give it a proper think. If you'd like to get started and do a MVP on a branch, then go for it but if not, I'll get to it over the weekend.

[jdc-pub]

Oooh that's a neat idea. Let me get to the weekend and then I can give it a proper think. If you'd like to get started and do a MVP on a branch, then go for it but if not, I'll get to it over the weekend.

I'm working on an MVP this morning in jdc-pub/acdx! Happy to move it into this repository too, I just didn't want to mess with forks while I tried it out.

[jdc-pub]

Well, the MVP is done! I didn't intend to close the issue. I had pushed a commit with a Resolves trailer set to https://github.com/nlopes/acdc/issues/396, and I guess GitHub used that trailer. TIL. If I could, I would reopen this issue!

I'll send a bit more information about the MVP tomorrow!

[nlopes]

If I could, I would reopen this issue!

All sorted and no worries!

I'll send a bit more information about the MVP tomorrow!

🙏

[jdc-pub]

I think it's ready for review. I still think it may be a fit for this project. If not, I recall you mentioning (perhaps in a recent commit message, or on Bluesky?) that you're considering adding extension support; I'd be interested in being the first extension, if that's a better fit.

(Another extension I'd love: acdc lint!)

Here's the gist for acdx as it's written today...

• I use petgraph to make a VERY simple workflow engine; every command block has a unique id, an optional interpreter (lang), and optional prerequisite commands (deps).
• When parsing the AsciiDoc, commands are added one-by-one to a command builder instance.
• When the full document is parsed, commands are built into a topologically sorted DAG.
• The DAG can be filtered for commands via the queue_for function.

The README in the repository is a working example of an executable AsciiDoc document.

git clone https://github.com/jdc-pub/acdx
cd acdx

cargo run -- test --dry-run

    Finished `dev` profile [unoptimized + debuginfo] target(s) in 12.05s
     Running `target/debug/acdx test --dry-run`
cargo nextest run

[nlopes]

Thank you. I couldn't check this over the weekend as I've been quite sick this week, will sort as soon as I can.

Can you tell me more about acdc lint? My expectation would be that running acdc convert does linting (i.e: it gives you warnings/errors about what is wrong)

[jdc-pub]

...I've been quite sick this week...

Sorry to hear that, hope you're feeling better soon. Please no rush on this.

Can you tell me more about acdc lint?

I envision something like rumdl, but for AsciiDoc instead of Markdown. I think it would basically require an AsciiDoc to AsciiDoc converter, with parameterized rules for how that's formatted. (The rule I most want enforced when writing with Markdown/AsciiDoc is one sentence per line.

---

On acdx, I just added some formatting using figue, a reflection-based approach to command-line argument parsing. The idea is acdx (or acdc run, or whatever the final design looks like) can have its help dialogue built at runtime after parsing the AsciiDoc. (This is not actually using reflection, it's iterating over CommandGraph, but facet enables some nice error formatting and debugging visuals out of the box.)

[nlopes]

I envision something like rumdl, but for AsciiDoc instead of Markdown. I think it would basically require an AsciiDoc to AsciiDoc converter, with parameterized rules for how that's formatted. (The rule I most want enforced when writing with Markdown/AsciiDoc is one sentence per line.

Ah got it, basically encode https://asciidoctor.org/docs/asciidoc-recommended-practices/ into a lint command.

[jdc-pub]

@nlopes do you see acdx as more of an external extension (a separate repository) or an internal extension (in the monorepo)?

I think it might make sense to add to the acdc Cargo workspace. If you agree I'll put up a pull request, and could help maintain if you're open to adding contributors to the repository.

Otherwise I can of course support the crate where it is.

[nlopes]

I'd definitely say as an internal extension. I'd be happy to bring it into the acdc-cli as its own runtask (or some other name - naming is hard)