catalyst

# 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

```txt
catalyst/
├── lib/
│   ├── catalyst.ex                 # Main Pipeline
│   ├── catalyst/
│   │   ├── action.ex               # Action Behaviour
│   │   ├── config.ex               # Configuration Structs
│   │   ├── plugin.ex               # Plugin Behaviour
│   │   ├── 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/
│           └── catalyst.run.ex     # CLI Entry Point
└── mix.exs
```

## Commands

Catalyst runs from a config file:

> mix catalyst.run path/to/config.exs

Official plugins live in a sibling `catalyst_plugins` package/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`):

```elixir
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`):

```elixir
alias Catalyst.Config
alias Catalyst.Plugins

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