STAC-22599: Adding stackpack scaffold command to generate Stackpack from a template

[viliakov]

The scaffold subcommand creates a new StackPack project structure from configurable templates, streamlining the initial setup process for StackPack development. The command supports both local directory templates and GitHub-hosted templates.

The GitHub Archive API is used to fetch from Github.

• Pros: It is a simple HTTP request.
• Cons: It fetches the archive of the entire branch.

Command Flags and Options

Environment variables:

⚠️ The subcommand is disabled by default and only available if the environment variable STS_EXPERIMENTAL_STACKPACK_SCAFFOLD is set to any value

Required Flags:

• --name (string): Name of the StackPack being created (used for template variable substitution)

Template Source Flags (mutually exclusive):

• --template-local-dir (string): Path to local directory containing template subdirectories
• --template-github-repo (string): GitHub repository in format 'owner/repo' (default: stackvista/stackpack-templates)

GitHub Template Configuration:

• --template-github-ref (string): Git reference (branch, tag, or commit SHA) (default: main)
• --template-github-path (string): Path within repository containing template subdirectories (default: templates)

General Options:

• --template-name (string): Name of the template subdirectory to use (default: generic)
• --display-name (string): Name that's displayed on both the StackPack listing page and on the title of the StackPack page. If not provided, the value of --name will be used
• --destination-dir (string): Target directory for scaffolded files (default: .)
• --force (boolean): Overwrite existing files without prompting (default: false)

When no template source is specified, the command defaults to using the GitHub repository stackvista/stac-22599 with the main branch, looking in the templates/ directory for the generic template.

Scaffolding steps

1. Validation: Validates all arguments and template source availability
2. Destination Check: Ensures destination directory exists (creates if needed)
3. Template Fetch: Downloads/accesses template from GitHub or local directory
4. Template Rendering: Processes template files with variable substitution using Go templates with << >> delimiters
5. Conflict Detection: Scans for existing files that would be overwritten (unless --force is used)
6. File Copy: Copies processed template files to destination
7. Cleanup: Removes temporary files and provides next steps guidance
8. Guiding on the next steps: explain to a user what to do next.

Templating

Template Variables

Templates support variable substitution with the following context:

• <<.Name>>: The StackPack name provided via --name
• <<.TemplateName>>: The template name used (e.g., "generic", "webapp")

Template Processing

• Text Files: Processed through Go's template engine with custom << >> delimiters to avoid conflicts with {{ }} used by the Stackpack parser.
• Binary Files: Copied as-is without processing
• Directory Structure: Preserved from template source

Usage

Basic usage with defaults (GitHub template)
sts stackpack scaffold --name my-stackpack

Use local template directory
sts stackpack scaffold --name my-stackpack --template-local-dir ./templates --template-name webapp

Use specific GitHub repository and template
sts stackpack scaffold --name my-stackpack --template-github-repo myorg/templates --template-name microservice

Force overwrite existing files
sts stackpack scaffold --name my-stackpack --force

Command output

> go run main.go stackpack scaffold --name testpack --destination-dir stackpack
✓ Validating arguments...
✓ Checking destination directory...
✓ Fetching template from github:stackvista/stac-22599@main:templates
✓ Rendering templates...
✓ Validating rendered templates...
✓ Copying files to destination...
Files copied:
  src/main/stackpack/provisioning/monitors/example/description
  src/main/stackpack/provisioning/monitors/example/monitor.sty
  src/main/stackpack/provisioning/templates/stackpack.sty
  src/main/stackpack/resources/default.md
  src/main/stackpack/resources/logo.png
  src/main/stackpack/resources/overview.md
  src/main/stackpack/stackpack.conf
  src/test/scala/com/stackstate/stackpack/example/ExampleProvisioningTest.scala
  src/test/scala/com/stackstate/stackpack/example/ExampleTemplateTest.scala
  src/test/scala/com/stackstate/stackpack/example/ExampleValidStackPackTest.scala
  version.sbt
✅ ✓ Scaffold complete!

Next steps:
1. Review the generated files in: stackpack
2. Customize the stackpack configuration as needed
3. Build your stackpack locally
...

Example of the stackpack template stored in Github https://github.com/StackVista/stac-22599/tree/main/templates/generic

TODO:

• Replace the default Github source with real template.
• Validate rendered template in pkg/scaffold/scaffolder.go:validateRenderedTemplates
• Improve next steps guidance cmd/stackpack/stackpack_scaffold:displayNextSteps()