EssaLab.Socotra 1.0.0-beta1

Socotra CLI

<p align="center"> <img src="icon.png" alt="Socotra CLI" width="128"> </p>

<p align="center"> <a href="https://github.com/Redaessa7/socotra/actions"><img src="https://github.com/Redaessa7/socotra/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://www.nuget.org/packages/EssaLab.Socotra"><img src="https://img.shields.io/nuget/v/EssaLab.Socotra" alt="NuGet"></a> <img src="https://img.shields.io/badge/.NET-10.0-512BD4" alt=".NET 10"> <img src="https://img.shields.io/github/license/Redaessa7/socotra" alt="License"> </p>

State-driven .NET project management --- inspired by Terraform, built for .NET developers.

Overview

Socotra CLI transforms .NET project setup from a series of manual, repetitive commands into a declarative, state-driven workflow. Define your desired project structure in a single socotra.yaml file, preview the changes, and apply them with confidence.

Your socotra.yaml  ->  socotra plan  ->  socotra apply  ->  Your .NET solution
(Desired State)        (Preview)         (Execute)         (Actual State)

Key Features

• Declarative Configuration --- Define solutions, modules, layers, packages, references, and templates in a single YAML file
• State-Driven Workflow --- plan/apply cycle with automatic drift detection between desired and actual state
• Pipeline Architecture --- 8 modular components, each with single responsibility and no circular dependencies
• Extensible Template System --- 11 built-in DDD templates (base-entity, value-object, aggregate-root, etc.) plus GitHub and local custom templates
• Safe by Default --- Non-destructive writes, automatic rollback on failure, atomic file operations, pre-existing file protection
• CI/CD Ready --- --output json for machine-readable output, --detailed-exit-codes for automation integration

Design Principles

• Non-destructive by default --- never overwrites user-written code
• Transparent --- always shows what will happen before doing it
• Reproducible --- share your architecture via a single YAML file
• Safe --- automatic rollback on any failure

Installation

dotnet tool install -g EssaLab.Socotra

Requires .NET SDK 10.0 or later.

Quick Start

# 1. Initialize a new project
mkdir MyApp && cd MyApp
socotra init

# 2. Validate your configuration
socotra validate

# 3. Preview the changes (safe --- no writes)
socotra plan

# 4. Apply the execution plan
socotra apply

Commands

All commands support --verbose for detailed output, --working-dir for directory selection, and --output json for machine-readable output.

Example socotra.yaml

socotra:
  version: "1.1"

  solution:
    name: "EcommerceApp"
    rootNamespace: "Ecommerce"
    dotnetVersion: "net9.0"

  architecture:
    pattern: "modular-monolith"
    enforceLayerConstraints: true

  modules:
    - name: "Orders"
      layers:
        - name: "Domain"
          templates: ["base-entity", "domain-event"]
        - name: "Application"
          references: ["Orders.Domain"]
          templates: ["repository-interface", "command", "query"]
        - name: "Infrastructure"
          references: ["Orders.Application"]
          packages: ["Microsoft.EntityFrameworkCore.SqlServer:8.0.0"]
        - name: "Api"
          references: ["Orders.Application"]

  shared:
    - name: "SharedKernel"
      templates: ["base-entity", "result-pattern"]

  host:
    name: "EcommerceApp.Api.Host"
    type: "webapi"
    references: ["**/*.Api"]

Documentation

Architecture

socotra.yaml  ->  Parser  ->  StateReader  ->  DiffEngine  ->  PlanEngine  ->  Executor
   (YAML)        (Parse)    (Scan FS)       (Detect Drift)  (Order Steps)  (Apply)

Each component is an independent .NET project with a single responsibility and no circular dependencies. Data flows unidirectionally through the pipeline using the Result<T> monad pattern.

See the Architecture Overview for detailed diagrams, project dependency graphs, and data flow documentation.

Built-in Templates

Contributing

See CONTRIBUTING.md for development setup, code conventions, testing guidelines, and the PR checklist.

License

MIT