Bootwitch CLI Scaffold — Technical
The interesting part of a project starter is what happens after it creates the folders. Here's how the templates, script generator, and documentation work together.
README · ARCHITECTURE · TECHNICAL · source
A base, then a shell layer
Every project needs a few of the same things: project information, documents, and a place to start. The base template supplies those. The shell layer adds scripts, wrappers, modules, tests, and README generation.
That gives me one common foundation and a place for workflow-specific pieces. Base and shell are the templates covered by the current version; other templates can grow from that structure later.
Project information stays simple
The metadata reader accepts a small set of known fields and reads their values with awk. It's text describing the project, so Bootwitch reads it as text rather than running it as shell code.
That makes the format deliberately small. It only needs to answer questions like what the project is called and where its main wrapper lives. The metadata excerpt shows the reader itself.
Build the project, then give it its final name
Bootwitch puts the project together in a staging directory beside its destination. It combines the templates, fills in the project information, sets executable permissions, and optionally initializes local Git. A small Python helper then publishes the finished directory with an exclusive rename.
The useful detail is that the final step still checks the destination. If another project has appeared there, the completed stage remains available and Bootwitch tells you where to find it. The publication excerpt shows that final operation.
Different parts of the toolkit write in different ways:
| Operation | How it works |
|---|---|
| Project creation | Publish the complete staged directory with an exclusive rename |
| README refresh | Prepare and validate the new content, then replace the README |
| New script | Create a new file without replacing an existing script, then make it executable |
The README follows the scripts
A marked header describes a script's purpose, arguments, dependencies, inputs, outputs, and example usage. The README builder finds those comments, reads them as text, and puts the resulting reference in a consistent order.
The generated section has a pair of markers. Everything outside those markers belongs to the person writing the README. That gives the project both a reference that can be refreshed and an introduction that still sounds like its author.
After a new script is created, the generator runs the README wrapper in a separate Bash process. When the script exists but the refresh needs another try, the command returns status 3 and prints a README-only retry command. The documentation excerpt follows that handoff.
The toolkit checks its own output
The development workflow checks Bash syntax, runs ShellCheck, generates projects, and exercises their scripts and documentation. ShellCheck is pinned locally through an explicit setup step; the generated project has its own runtime requirements.
The demo also runs the generated tests twice and compares a rebuilt README with the previous version. Those checks are useful ways to see whether repeating the workflow changes anything unexpectedly. You can follow the demo steps or read how this snapshot was checked.