Catalyst

Catalyst is a dynamic patching system and "meta-framework" for scaffolding production-ready Elixir applications.

Goals

• Automation: Eliminate repetitive manual setup for new client projects (CI/CD, Linters, Docker, Security).
• Consistency: Enforce architectural standards (folder structure, naming conventions) from line one.
• Flexibility: Allow features to be toggled via a configuration struct rather than maintaining multiple massive "boilerplate" repos.
• Safety: Use AST (Abstract Syntax Tree) manipulation for code editing, avoiding brittle regex replacements.

High-Level Architecture

Catalyst operates on a Declarative Pipeline model. It does not execute logic immediately; instead, it resolves a list of intent (Actions) which are then executed by a central engine.

Core Concepts:

• Configuration
• Plugin System
• Action Engine
• Executor

Project Structure

catalyst/
├── lib/
│   ├── catalyst.ex                 # Main Pipeline
│   ├── catalyst/
│   │   ├── action.ex               # Action Behaviour
│   │   ├── config.ex               # Configuration Structs
│   │   ├── plugin.ex               # Plugin Behaviour
│   │   ├── cli/                    # CLI support and registry lookup
│   │   ├── actions.ex              # Actions Type Contract
│   │   ├── actions/
│   │   │   ├── add_file.ex         # Action Struct + Runner
│   │   │   ├── add_dependency.ex   # Action Struct + Runner
│   │   │   ├── system_command.ex   # Action Struct + Runner
│   │   │   └── executor.ex         # Central Action Dispatcher
│   └── mix/tasks/                  # Global Mix archive commands
│       ├── catalyst.run.ex
│       ├── catalyst.plugin.ex
│       └── catalyst.registry.ex
└── mix.exs

Commands

Catalyst runs from a config file:

mix catalyst.run path/to/config.exs

Catalyst can generate a plugin registry from plugin source files:

mix catalyst.registry --out registry.json lib/catalyst/plugins/*.ex

Use --check in CI to verify the registry is up to date:

mix catalyst.registry --check --out registry.json lib/catalyst/plugins/*.ex

Official plugins live in the sibling catalyst-plugins repository. The core package owns the engine, action APIs, and plugin behavior; the plugins package owns built-in plugin modules and their templates.

Configuration

Catalyst config supports two modes:

• mode: :new — scaffold a brand-new project at app.path
• mode: :existing — run Catalyst actions against an existing Mix project

Example (mode: :new):

alias Catalyst.Config
alias Catalyst.Plugins

%Config{
	version: 1,
	mode: :new,
	app: %Config.App{
		name: "My App",
		path: "my_app",
		module: "MyApp"
	},
	plugins: [
		{Plugins.PhoenixBase,
		 phoenix: "1.18.4",
		 flags: [install: false, ecto: false, mailer: false]},
		{Plugins.Credo},
		{Plugins.Sobelow, strict_post_validate: false}
	]
}

Example (mode: :existing):

alias Catalyst.Config
alias Catalyst.Plugins

%Config{
	version: 1,
	mode: :existing,
	app: %Config.App{
		path: "."
	},
	plugins: [
		{Plugins.Credo},
		{Plugins.Sobelow, strict_post_validate: false}
	]
}