Crates.io | spawn_point |
lib.rs | spawn_point |
version | 1.1.0 |
source | src |
created_at | 2025-04-28 01:33:32.329067+00 |
updated_at | 2025-04-28 20:08:08.903524+00 |
description | A CLI tool for generating project scaffolds from templates with built-in validation. |
homepage | https://github.com/normano/spawnpoint |
repository | https://github.com/normano/spawnpoint |
max_upload_size | |
id | 1651648 |
size | 154,126 |
spawnpoint
) CLI ✨Spawn Point (spawnpoint
) is a fast, flexible, and robust command-line tool for generating project scaffolds from templates. Built in Rust, it focuses on ensuring template quality and maintainability through an integrated validation system.
(Work in Progress - Expect changes and rapid development!)
Creating new projects consistently can be tedious. Scaffolding tools help, but templates often break silently over time ("template rot"). Spawn Point addresses this with:
validate
command runs build/test steps defined in the template manifest, ensuring templates produce working code before you use them. This drastically improves template reliability and maintainability.PascalCase
, kebab-case
, etc., from input.target
, .git
, .DS_Store
) from template processing.(Instructions to be added once build/release process is defined. Typically involves cargo install spawn-point
or downloading binaries.)
# Example (replace with actual instructions later)
# Install from source after cloning the repository:
cargo install --path .
# OR
# Download binary from releases page...
The main command is spawnpoint
.
spawnpoint [OPTIONS] <COMMAND>
Commands:
list
: List available project templates.generate
: Generate a new project from a template.validate
: Validate that a template generates a working project.Common Options:
-v, --verbose
: Increase output verbosity (e.g., -v
for info, -vv
for debug, -vvv
for trace).--templates-dir <PATH>
: Specify a custom directory containing templates (overrides default locations and SPAWNPOINT_TEMPLATES_DIR
env var).-h, --help
: Print help information.--version
: Print version information.Spawn Point needs to find where your template directories are stored. It searches in the following locations, using the first valid directory it finds:
--templates-dir <PATH>
(CLI Flag): The path provided via the command-line argument. This always takes precedence.SPAWNPOINT_TEMPLATES_DIR
(Environment Variable): The path specified in this environment variable.templates
subdirectory within the standard user configuration location. This is the recommended place for users to store their templates after installing spawnpoint
. Paths vary by OS:
$XDG_CONFIG_HOME/spawnpoint/templates
(often ~/.config/spawnpoint/templates
)~/Library/Application Support/spawnpoint/templates
%APPDATA%\spawnpoint\templates
(e.g., C:\Users\Username\AppData\Roaming\spawnpoint\templates
)templates
subdirectory located in the same directory as the spawnpoint
executable itself. Useful for portable distributions or development setups where templates are bundled.templates
subdirectory within the directory where you run the spawnpoint
command. This is the last resort and primarily useful during development when working directly inside the spawnpoint
project repository.If no valid directory is found in any of these locations, commands like list
or generate
will report an error or find no templates.
spawnpoint list
Displays discovered templates from the determined templates directory.
Example:
spawnpoint list
Output:
Available Spawn Point Templates:
Name | Language | Description
--------------------------|---------------|-----------------------------------------------------------------
Node.js Base v1 | nodejs | Minimal Node.js/TypeScript project setup.
Java Gradle CLI App v1 | java | A basic Java command-line application using Gradle.
Java Maven CLI App v1 | java | A basic Java command-line application using Maven.
Rust CLI App v1 | rust | A basic command-line application written in Rust using Clap.
Rust Leptos CSR App v1 | rust-leptos | A basic client-side rendered web application using Rust and Leptos.
# ... other templates
spawnpoint generate
Generates a new project. Can be run interactively or with flags.
Options:
-l, --language <LANG>
: Specify the language/framework of the template (e.g., nodejs
, rust
). Skips language selection prompt.-t, --template <NAME>
: Specify the exact template name (must match the name
in scaffold.yaml
). Skips template selection prompt.-o, --output-dir <PATH>
: Directory to generate the project into (defaults to current directory .
).--var name=value
)Examples:
Fully Interactive:
spawnpoint generate
scaffold.yaml
.Specify Template, Interactive Variables:
spawnpoint generate -l rust -t "Rust CLI App v1" -o ./my-new-rust-cli
crateName
, crateDescription
, etc.)../my-new-rust-cli
.Specify Output Directory Only:
spawnpoint generate -o ./output
./output
.spawnpoint validate
Validates a specific template by generating it in a temporary location and running predefined commands (install, build, test, etc.) from its scaffold.yaml
. This is crucial for template maintainers.
Arguments:
<LANGUAGE>
: The language identifier of the template (e.g., nodejs
, rust
).<TEMPLATE>
: The exact name of the template (from scaffold.yaml
, e.g., "Node.js Base v1"
).Example:
# Validate the basic Rust CLI template
spawnpoint validate rust "Rust CLI App v1"
# Validate the Java Gradle template with more detailed output
# Uses 'java' as the language identifier from its scaffold.yaml
spawnpoint -vv validate java "Java Gradle CLI App v1"
How Validation Works:
validation
section in its scaffold.yaml
.testVariables
defined in the manifest (no interactive prompts). Excludes files/directories listed in exclude
.setup
commands (if any).steps
commands sequentially inside the temp directory. These usually include:
npm install
, cargo build
, gradle assemble
, etc.)eslint
, cargo fmt --check
, etc.)npm run build
, cargo build --release
, etc.)npm test
, cargo test
, gradle test
, etc.)teardown
commands (if any), even if previous steps failed (if alwaysRun: true
).PATH
) from spawnpoint
by default. You can add or override variables using the env
map within a specific ValidationStep
.Benefits: This ensures that templates stay functional and produce working projects as dependencies and best practices evolve. It's a crucial tool for template maintainers.
This tool comes with several example templates to demonstrate its capabilities:
Node.js Base v1
(nodejs
): A minimal Node.js/TypeScript setup. Demonstrates basic substitution, transformations (kebabCase
, PascalCase
), conditional files (Dockerfile
), and hooks (git init
).Rust CLI App v1
(rust
): A simple Rust CLI using clap
. Shows Rust-specific validation steps (cargo fmt
, clippy
, build
, test
). Includes exclude: [ "target" ]
.Java Gradle CLI App v1
(java
): A standard Java CLI project using Gradle. Demonstrates Java project structure, Gradle validation, and filename placeholders for package structure.Java Maven CLI App v1
(java
): A standard Java CLI project using Maven.Rust Leptos CSR App v1
(rust-leptos
): A basic client-side rendered Leptos web app. Shows WASM build validation using wasm-pack
.Explore the templates/
directory (found via the Locating Templates logic) and their scaffold.yaml
files to see how they are configured.
~/.config/spawnpoint/templates/my-python-api
.--my-placeholder--
) where values need to be replaced. Do not include build artifact directories like target/
, node_modules/
, dist/
, etc.scaffold.yaml
file in the root of your template directory.name
, description
, language
.variables
with name
, prompt
, and the exact placeholderValue
used in your files. Add transformations
if needed. Add validation_regex
for input validation if desired (requires regex
feature).placeholderFilenames
, conditionalPaths
, preGenerate
, postGenerate
as required.binaryExtensions
(e.g., .png
, .lock
) and binaryFiles
(e.g., .DS_Store
) for files that should be copied without processing content.exclude
with a list of file or directory names (e.g., target
, .git
, .mypy_cache
) that should be completely ignored during generation. This is primarily for ignoring files/directories that might accidentally be present in the template source but shouldn't be copied.validation
section:
testVariables
with realistic values for testing.env
maps within steps if specific environment variables are needed (otherwise the parent environment is inherited).steps
that install dependencies, build, lint, and test the generated project. Use flags like --no-daemon
for tools like Gradle if needed.spawnpoint validate <lang> "<Your Template Name>"
.spawnpoint generate ...
.This section provides instructions for developing spawnpoint
itself.
Prerequisites:
Building:
git clone <repository-url>
cd spawnpoint # Or your repo name
cargo build
cargo build --release
target/debug/spawnpoint
or target/release/spawnpoint
.Running Locally:
You can run the development version directly using cargo run
. Any arguments after --
will be passed directly to spawnpoint
:
# Run the list command (using templates in ./templates/ if it exists)
cargo run -- list
# Generate using a specific template directory
cargo run -- --templates-dir /path/to/your/templates generate -l rust -t "My Dev Template"
# Validate a template with high verbosity
cargo run -- -vvv --templates-dir /path/to/your/templates validate rust "My Dev Template"
Testing:
Run the test suite using:
cargo test
Tips for Development:
--templates-dir path/to/your/test/templates
flag frequently to test against templates you are developing locally without needing to install them globally or rely on default locations.-v
, -vv
, or -vvv
flags with cargo run -- ...
to get detailed logging output, which is helpful for debugging generation or validation issues.regex
), use cargo run --features regex -- ...
or cargo build --features regex
.