README

A flexible, framework-agnostic scaffolding tool for any programming language or architecture.

Key Features

Multi-language support: Scaffold projects in any language by defining your own modes.
Customizable modes: Each mode defines directory structures, templates, naming conventions, and scaffolding rules.
CLI-driven workflow: Easily scaffold components, directories, and units from the command line.
Template engine support: Use Mustache, Twig, or Blade-style templates.
Pre- and post-scaffold hooks: Run custom commands automatically before or after scaffolding.
Portable and framework-agnostic: Not tied to any specific framework or programming style.

How It Works

ForgeFoundary reads configuration from YAML mode files, which define:

Component paths and names
Directory structures and units
Template files, placeholders, and extensions
Naming conventions (PascalCase, camelCase, etc.)
CLI flags and overrides for flexible scaffolding

Philosophy

ForgeFoundary is designed for developers who value automation, consistency, and flexibility in project setup. By separating scaffolding logic into configurable modes, it ensures repeatable and predictable project structures, no matter the language, framework, or team.

Installation Options

Requirements

Before installing ForgeFoundary, make sure you have the following installed:

PHP (version 8.5 or higher) Download PHP
Composer (PHP dependency manager) Download Composer

ForgeFoundary depends on PHP and Composer to run and manage dependencies.

Manual Installation (Directly from the installation script)

You can fetch the installation script directly from the repository and run it. This works on Unix/Linux/macOS and Windows.

Unix / Linux / macOS

curl -o install.sh https://raw.githubusercontent.com/omarSemgey/ForgeFoundary/main/InstallationScripts/install.sh
chmod +x install.sh
./install.sh

The script will:

Ask for the installation directory (default: ~/ForgeFoundary).
Clone the ForgeFoundary repository to the specified folder.
Install PHP dependencies using Composer.
Attempt to make the ForgeFoundary command available globally (requires write access to /usr/local/bin).
If the script cannot link globally, you can manually add the install directory to your PATH.

Windows

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/omarSemgey/ForgeFoundary/main/InstallationScripts/install.ps1" -OutFile "install.ps1"
Set-ExecutionPolicy Bypass -Scope Process -Force
.\install.ps1

The script will:

Ask for the installation directory (default: $HOME\ForgeFoundary).
Clone the ForgeFoundary repository to the specified folder.
Install PHP dependencies using Composer.
Optionally guide you to make ForgeFoundary accessible globally.

Automatic Installation

ForgeFoundary can also be installed using the following ways:

Docker Installation

The fastest way to run ForgeFoundary without installing PHP, Composer, or dependencies on your host machine.

Pull the Image

docker pull omarsemgey/forgefoundary

Run Anywhere Since Docker runs in a container, you must mount your current directory so the tool can see your project files:

docker run --rm -it -v "$(pwd):/app" -w /app omarsemgey/forgefoundary [command]

(Optional) Set an Alias To run it just by typing ForgeFoundary, add an alias to your shell profile:

Linux/macOS (.bashrc or .zshrc):

alias ForgeFoundary='docker run --rm -it -v "$(pwd):/app" -w /app omarsemgey/forgefoundary'

Windows (PowerShell $PROFILE):

function ForgeFoundary { docker run --rm -it -v "${PWD}:/app" -w /app omarsemgey/forgefoundary $args }

Docker Environment Constraints

Because Docker runs in a secure, isolated "sandbox," there are specific behaviors you need to be aware of:

Host Dependency Limitation: Post-process hooks (like npm install or local system scripts) will fail because the container cannot "see" your host's installed binaries. Only tools included in the image (PHP, Composer, Git) will function.
Path Isolation: The container only has access to the directory you "mount" into it. Absolute paths from your host machine will not work. You must use relative paths (e.g., ./output) to ensure files are written to your project folder.
Permissions (Linux Users): Files created via Docker may be owned by root. Use the -u flag (detailed below) to avoid permission issues.

AUR / yay (Arch Linux)

yay -S forgefoundary

Quick Start

ForgeFoundary dry-run

Further Instructions

For detailed instructions, examples, and a map of available documentation, refer to the Docs. it provides an organized overview of all other documentation files included with ForgeFoundary.

omarsemgey / forgefoundary

Maintainers

Package info

Statistics

Security