Forgix

CLI project scaffolding tool with template versioning, post-scaffold hooks, governance checks, registry support, and composition. Generates production-ready project structures with lifecycle management.

npm install -g @fourlinx/forgix
# or use without installing
npx @fourlinx/forgix create my-app --template react-vite --ts --ci --docker

Forgix copies a template into a new directory, injects variables, runs your package manager's install, executes post-scaffold hooks, and writes a .scaffold-lock.yaml tracking the template version. Optionally initializes git, CI, linting, testing, and Docker — in one command.

For CI/CD pipelines, it runs non-interactively when all required flags are provided.

npm install -g @fourlinx/forgix
# or
npx @fourlinx/forgix create

Requires: Node.js >= 22, Git (optional, for --git and remote templates).

Verify setup:

forgix doctor

forgix create [name] [options]

If name or --template is omitted, Forgix prompts interactively.

# Interactive
forgix create

# Non-interactive, full stack
forgix create my-app -t react-vite-ts --pm pnpm --ts --eslint --prettier --test --ci --docker --git

# Preview what would be created
forgix create my-app -t react-vite --dry-run

# From a GitHub repo
forgix create my-app -t github:user/repo --trust-remote

# With composition layers
forgix create my-app -t my-base --layers auth database testing

cd my-app
forgix add docker

Templates can include a hooks.yaml that runs scripts after scaffolding.

# hooks.yaml (in template root)
post_scaffold:
  - id: init-git
    name: Initialize Git
    run: "git init && git add . && git commit -m 'initial'"
    on_error: warn
    condition: "not_exists(.git)"

  - id: setup-ci
    name: Configure CI
    run: "cp .ci/github-actions.yml .github/workflows/ci.yml"

  - id: notify
    name: Notify Slack
    run: "curl -X POST $SLACK_WEBHOOK -d '{\"text\": \"Project created\"}'"
    on_error: ignore
    async: true

Every scaffolded project gets a .scaffold-lock.yaml tracking its template origin:

template:
  name: react-vite-ts
  version: "1.0.0"
  source: local
scaffolded_at: "2026-04-18T16:00:00Z"
engine_version: "1.1.0"
files_generated:
  - src/index.ts
  - package.json
variables:
  projectName: my-app
  author: Developer
  license: MIT
hooks_ran:
  - init-git
patches_applied: []

Templates can include a template.yaml manifest:

# template.yaml
name: react-vite-ts
version: "2.1.0"
description: "React + TypeScript + Vite"
author: "Team"
license: MIT
min_engine_version: "1.1.0"
hooks: true

Preview what files would be created without writing anything:

forgix create my-app -t react-vite --dry-run

Output (human):

  Preview — files that would be created/modified:

  src/
  + src/index.ts 1.2KB
  + src/App.tsx 0.8KB
  + package.json 0.5KB

  Summary:
    + 15 files to create
    3 directories
    Total: 12.4KB

Output (JSON, with -n):

{
  "total_files": 15,
  "total_size": 12697,
  "directories": 3,
  "files": [{ "action": "create", "path": "src/index.ts", "size": 1234 }]
}

Audit any project against best practices:

forgix check [dir]
forgix check . --deps --json

Checks:

• Scaffold lock file present
• Git initialized
• License file exists
• README present
• .gitignore configured
• Package metadata complete
• Dependency lock file
• No dangerous install scripts
• Test script configured
• node_modules excluded
• .env files not exposed
• Dockerfile non-root user
• CI/CD configured
• No hardcoded secrets

Scoring: 0-100% based on pass/warn/fail. Exits non-zero if score < 50%.

--deps flag adds dependency analysis: deprecated packages, npm audit vulnerabilities, missing lock files.

Publish and fetch templates from npm:

# Search for templates
forgix registry search react

# List configured registries
forgix registry list

# Add a private registry
forgix registry add company --url https://npm.internal.company.com

# Publish a template
forgix registry publish ./my-template @company/react-service

# Install from registry (during create)
forgix create my-app -t @company/react-service

Templates published to npm should include template.yaml and use the forgix-template keyword.

Templates can declare layers in composition.yaml:

base: base/
layers:
  - name: auth
    path: layers/auth/
    description: "JWT authentication"
    conflicts: overwrite
  - name: database
    path: layers/database/
    description: "PostgreSQL + Prisma"
    conflicts: skip
  - name: testing
    path: layers/testing/
    description: "Jest + Testing Library"

Usage:

forgix create my-app -t my-base --layers auth testing

Set persistent defaults via forgix config:

forgix config

Config file: ~/.forgix-config.json (permissions: 0600)

Options: default template, package manager, author name, license, and auto-apply flags (--git, --open, --eslint, etc.).

Link a local directory as a named template:

forgix link my-org-template ./path/to/template
forgix create my-app -t my-org-template

Links stored in: ~/.forgix-links.json

Files in templates can contain these placeholders, replaced at scaffold time:

Binary files (images, archives, etc.) are skipped automatically.

All commands support non-interactive mode for CI pipelines, scripts, and AI agents.

Set FORGIX_NON_INTERACTIVE=1 or pass -n/--non-interactive.

forgix create --non-interactive outputs a JSON summary on success.

Full reference: see AGENT.md.

src/
  cli/index.ts          Entry point, command registration
  commands/
    create.ts           Interactive create flow (prompts + flags)
    add.ts              Plugin injection
    config.ts           Profile configuration
    check.ts            Governance audit command
    doctor.ts           System health checks
    registry.ts         Registry management
    list.ts             Template/plugin listing
    link.ts             Custom template registration
  core/
    create.ts           Template copy, variable injection, hooks, lock file
    hooks.ts            Post-scaffold hook execution engine
    versioning.ts       Template manifest + .scaffold-lock.yaml
    dry-run.ts          Preview mode file scanner
    composition.ts      Template layer system
    registry.ts         npm publish/install for templates
    check.ts            Governance checks (security, best practices)
    deps-intel.ts       Dependency analysis (deprecated, vulnerable)
    install.ts          Package manager abstraction
    template-engine.ts  Recursive {{variable}} replacement
    config.ts           Read/write ~/.forgix-config.json
templates/              Built-in project templates
plugins/                Injectable feature modules

MIT