PSX: The Project Structure Checker

You know that feeling when you start a new project and spend the first hour just setting up folders, config files, and all the boring stuff? Or when you clone a repo and realize half the essential files are missing?

Yeah — I got tired of that too. So I built PSX.

What is PSX?

PSX is a command-line tool that validates your project structure and fixes it automatically. Think of it as a linter, but for your entire project layout instead of just code.

It checks for:

• Essential files (README, LICENSE, .gitignore, CHANGELOG)
• Proper folder structure (src/, tests/, docs/, cmd/, internal/, pkg/ depending on project type)
• Documentation (CONTRIBUTING, SECURITY, API docs, ADRs)
• CI / DevOps basics (Docker, docker-compose, minimal CI/workflow templates)
• Basic quality tools and standards (EditorConfig, Go linter integration)

And the best part? It doesn't just tell you what's wrong — it fixes it.

Why I Built This

I was working on multiple projects — Node.js, Go, some experiments — and every single time I had to:

1. Create the same folders over and over
2. Copy-paste .gitignore from old projects
3. Write boilerplate README files
4. Set up the same (or half-broken) CI templates
5. Remember which files go where

It was repetitive and boring. So I automated it.

How It Works

Installation

Quick install for Linux/macOS:

curl -sSL https://raw.githubusercontent.com/m-mdy-m/psx/main/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/m-mdy-m/psx/main/scripts/install.ps1 | iex

For a full step-by-step installation guide, see the official INSTALLATION page:
docs/INSTALLATION.md

Or grab binaries from the releases on GitHub: releases

Important: Project Type

PSX focuses on Go and Node.js projects. You must tell PSX which type of project you're working on. Add a small config (psx.yml) in your project root:

project:
  type: "go"      # or "nodejs"

PSX uses project.type to decide which rules and templates to apply. If you don't set it, PSX will ask you to set it in the config.

Basic Usage

Check your project:

cd my-project
psx check

You’ll get output like:

Detected: go  (based on project.type in psx.yml)

ERRORS (2)
✗ README_REQUIRED
    README.md file not found in project root

✗ LICENSE_REQUIRED
    No LICENSE file found

Summary: 2 errors, 0 warnings
Status: FAILED ✗

Now fix it:

psx fix

PSX will ask before creating each file (interactive mode). Or run:

psx fix --all

and everything gets created automatically based on the templates and your configuration.

The Cool Parts

1. Explicit, predictable project types

PSX targets Go and Node.js workflows and applies type-specific rules when you set project.type. This keeps behavior predictable and templates focused.

• Node.js: Expects package.json, checks for src/ or lib/, looks for test files and basic Node layouts.
• Go: Expects go.mod, checks for cmd/, internal/, pkg/ and common Go conventions.

2. Custom Rules (psx.yml)

Don't like the defaults? Create a psx.yml:

version: 1

project:
  type: "nodejs"

rules:
  readme: error      # Must have
  license: warning   # Should have
  changelog: info    # Nice to have

ignore:
  - node_modules/
  - dist/

You can define which items are errors/warnings/infos and add custom files and folder structures.

3. Templates for everything

PSX ships with language-specific templates and organized resource files (README templates, multiple LICENSE types, .gitignore snippets, Docker configs, ADR/docs templates). Templates live with the embedded resources and are easy to customize. ADR and documentation templates are grouped for clarity so you can find and adapt them quickly.

4. Custom files & folders

Need project-specific structure? Add custom config:

custom:
  files:
    - path: ".env.example"
      content: |
        NODE_ENV=development
        PORT=3000

  folders:
    - path: "src/api"
      structure:
        controllers: {}
        middlewares: {}
        routes: {}

See the example config in examples/psx.examples.yml for more advanced setups.

5. CI / Docker support

PSX can scaffold Docker files and simplified CI/workflow templates that are appropriate for the selected project type. The templates are intentionally minimal and focused — PSX won't push a huge set of opinionated, hard-to-maintain workflows. If you want complex, highly custom CI, you can keep your own workflows and use PSX to maintain the basics.

6. Designed for automation

PSX outputs machine-friendly JSON and has flags suitable for CI:

- name: Validate Structure
  run: |
    psx check --output json

Use --fail-on warning in pipelines if you want stricter enforcement.

How It's Built

PSX is written in Go 1.25 — a single static binary, no runtime dependencies, works everywhere.

Key components (linked so you can read the code/templates directly):

1. Config Loader — internal/config/ — Reads YAML configs and validates them against the schema.
2. Rules Engine — internal/rules/ — Runs checks in parallel, using a centralized, simplified rules implementation.
3. Resources — internal/resources/ — Where templates and message files live; templates are organized for discoverability.
4. Fixer — internal/rules/fixer.go — Creates missing files and folders using the embedded templates.
5. Reporter — internal/reporter/ — Table or JSON output for humans and automation.

The codebase was refactored to be simpler and easier to maintain: consolidated checker/fixer flows, clearer resource separation, and a smaller, more focused command surface (check and fix). You can browse the rest of the internals here: internal/

What PSX Doesn’t Do

• PSX is intentionally narrow: it focuses on practical, repeatable scaffolding for Go and Node.js.
• It doesn't try to auto-detect project type — you set project.type so behaviour is explicit.
• It doesn't scaffold every possible CI/quality tool; instead it provides minimal, maintainable templates and a clear place for you to extend things via configs and custom templates.
• Plugin system and multi-project scanning are not part of the core (for now).

Want to Contribute?

PSX is open source (MIT). If you:

• Find bugs → Open an issue
• Want features → Start a discussion
• Have ideas → Pull requests welcome

The code is structured to be easy to extend:

• New rules? Edit rules.yml/internal/resources and add templates.
• New templates? Place updated YAML templates under the resources area and rebuild.

Philosophy

I built PSX with one principle: Don't make me think about boring stuff.

When I start a project, I want to write code, not spend 30 minutes setting up folders and config files. When I clone a repo, I want to know it has proper structure without manual inspection.

PSX handles the boring parts so you can focus on the interesting parts.

Try It

# Install
curl -sSL https://raw.githubusercontent.com/m-mdy-m/psx/main/scripts/install.sh | bash

# Check a project
cd your-project
# make sure psx.yml contains `project.type: "go"` or `"nodejs"`
psx check

# Fix issues
psx fix

# Customize
echo "version: 1" > psx.yml
# Add your rules...

Contribute or Share Your Ideas!

PSX is under active development and the idea is still evolving. If you like the project, please star the repo, open issues, submit pull requests, or share your ideas on GitHub: https://github.com/m-mdy-m/psx. Whether you spot a bug, want a new rule or template — your feedback matters.

I’d love to hear your thoughts — does PSX’s focused, type-first design make project setup more predictable and useful for you? Would you prefer broader language support, a plugin system, or richer CI templates? Start a discussion on GitHub, or email suggestions and security reports to [e-mail]. Let’s build something that actually saves time.