/setup

Claude-Dogma: Lint/Prettier Setup

You are executing the /dogma:lint:setup command. Your task is to interactively set up Prettier and related linting tools for the current project.

Step 1: NVM/Node Check

1.1 Check if nvm is installed

nvm -v 2>/dev/null

If nvm is NOT installed:

Detect OS and shell:

# OS detection
OSTYPE="$OSTYPE"
uname -s

# Shell detection
echo "$SHELL"

Ask the user:

nvm is not installed. It helps manage Node.js versions.

Would you like installation instructions?
1. Yes, show me how to install nvm
2. No, I already have Node.js managed differently

If yes, provide OS-specific instructions:

• macOS/Linux (bash/zsh):

  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
  

• Fish shell:

  # Use fisher: fisher install jorgebucaran/nvm.fish
  

• Windows: Recommend nvm-windows from https://github.com/coreybutler/nvm-windows

1.2 Check Node.js version

node -v 2>/dev/null

If Node.js version < 20:

Node.js version is $(node -v), but v20+ is recommended for modern tooling.

Would you like to upgrade?
1. Yes, run: nvm install 20 && nvm use 20
2. No, keep current version

1.3 Create .nvmrc

If nvm is available and no .nvmrc exists:

echo "v20" > .nvmrc

Report:

Created .nvmrc with v20
Run 'nvm use' to switch to this version.

Step 2: Project Analysis

2.1 Detect file types in project

# Find all source file extensions
# Respects .gitignore AND .git/info/exclude
git ls-files --cached --others --exclude-standard 2>/dev/null \
  | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20

2.2 Map extensions to Prettier plugins

Extension	Plugin	Notes
.php	@prettier/plugin-php	Requires phpVersion config
.vue	(built-in)	No extra plugin needed
.twig	@shopify/prettier-plugin-liquid	Uses liquid-html parser
.astro	prettier-plugin-astro	For Astro projects
.ts/.tsx/.js/.jsx	(built-in)	No extra plugin needed
.json/.yaml/.yml	(built-in)	No extra plugin needed
.md	(built-in)	No extra plugin needed
.scss/.css	(built-in)	No extra plugin needed

2.3 Check existing configuration

# Check for existing Prettier config
ls -la .prettierrc* prettier.config.* 2>/dev/null

# Check package.json for prettier config
grep -l '"prettier"' package.json 2>/dev/null

# Check for .editorconfig
ls -la .editorconfig 2>/dev/null

# Check for existing package.json
ls -la package.json 2>/dev/null

2.4 Report findings

Project Analysis Complete

File types detected:
- TypeScript/JavaScript: 42 files
- PHP: 15 files
- Vue: 8 files
- SCSS: 12 files

Existing configuration:
- package.json: [Found/Missing]
- .prettierrc: [Found/Missing]
- .editorconfig: [Found/Missing]

Recommended plugins:
- @prettier/plugin-php (for .php files)

Step 3: Dependencies

3.1 Create package.json if missing

If no package.json exists:

No package.json found.

Would you like to create one?
1. Yes, create minimal package.json
2. No, skip (Prettier setup requires package.json)

If yes, create with this base structure:

{
    "scripts": {
        "format": "prettier --write .",
        "format:check": "prettier --check ."
    },
    "devDependencies": {
        "@prettier/plugin-php": "^0.22.2",
        "@shopify/prettier-plugin-liquid": "^1.4.1",
        "prettier": "^3.2.5"
    }
}

Then run:

npm install

Note: Adapt devDependencies based on detected file types (Step 2). Remove plugins for languages not used in the project.

3.2 Determine required packages

Build list of packages to install:

• prettier (always required)
• Plugins based on detected file types (Step 2)

3.3 Install packages

npm install --save-dev prettier @prettier/plugin-php @shopify/prettier-plugin-liquid

Report each installation:

Installing prettier@3.2.5... OK
Installing @prettier/plugin-php@0.22.2... OK

Step 4: Configuration Files

4.1 Create .editorconfig

Use this template for .editorconfig:

# this is the global editor configuration which should always be chosen to set group/team-wide configuration for the IDE

root = true

# global config (maybe get's overridden below)
[*]
charset = utf-8
end_of_line = lf
indent_size = 4
indent_style = space
insert_final_newline = true
max_line_length = 120
tab_width = 4
trim_trailing_whitespace = true
ij_formatter_off_tag = @formatter:off
ij_formatter_on_tag = @formatter:on

# Markdown
[{*.markdown,*.md}]
trim_trailing_whitespace = false

Ask user:

Create .editorconfig for consistent editor settings?

Preview:
- charset: utf-8
- indent: 4 spaces
- line ending: LF
- max line length: 120

1. Yes, create with these settings
2. No, skip
3. Customize settings first

4.2 Create .prettierrc

Use this as base template (full-stack with PHP/Twig support):

{
    "arrowParens": "always",
    "printWidth": 120,
    "semi": false,
    "singleQuote": true,
    "trailingComma": "es5",
    "htmlWhitespaceSensitivity": "ignore",
    "vueIndentScriptAndStyle": true,
    "singleAttributePerLine": true,
    "plugins": [
        "@prettier/plugin-php",
        "@shopify/prettier-plugin-liquid"
    ],
    "phpVersion": "8.2",
    "overrides": [
        {
            "files": [
                "*.js"
            ],
            "options": {
                "parser": "babel"
            }
        },
        {
            "files": [
                "*.html"
            ],
            "options": {
                "parser": "html"
            }
        },
        {
            "files": "*.php",
            "options": {
                "parser": "php"
            }
        },
        {
            "files": [
                "*.vue"
            ],
            "options": {
                "parser": "vue"
            }
        },
        {
            "files": [
                "*.scss"
            ],
            "options": {
                "parser": "scss"
            }
        },
        {
            "files": [
                "*.twig"
            ],
            "options": {
                "parser": "liquid-html"
            }
        },
        {
            "files": [
                "*.json"
            ],
            "options": {
                "parser": "json"
            }
        },
        {
            "files": [
                "*.graphql"
            ],
            "options": {
                "parser": "graphql"
            }
        }
    ]
}

Adapt to detected file types:

• Remove plugins/overrides for languages NOT detected in project
• Keep only relevant parsers
• Ask user before removing anything

Build config based on detected file types:

• Include only plugins for detected languages
• Set appropriate overrides
• Configure phpVersion if PHP detected

Ask user:

Create .prettierrc?

Settings:
- printWidth: 120
- semi: false
- singleQuote: true
- trailingComma: es5
- Plugins: [list detected plugins]

1. Yes, create
2. No, skip
3. Customize settings

4.3 Create .prettierignore

Use this template for .prettierignore:

# Prettier is automatically considering .gitignore paths by manually running `npm run prettier-path`,
# see also $npm_package_config_prettier in package.json.
#
# In this ignore file there are explicit prettier ignores to prevent prettier on save hook and in all other circumstances

# IDE
.vscode/*
.git/*
.svn/*
.hg/*
.husky/*
.idea/*
.run/*
**/.git
**/.svn
**/.hg

# generated/artifacts
node_modules/*
vendor/*
dist/*
build
coverage

# resources
material/*

# other
deploy.php
package-lock.json
.prettierrc
**/*.svg
**/*.lock
**/*.sql
**/*.map
**/*.legacy
**/*.meta
**/*.log
**/*.example

Ask user:

Create .prettierignore?

Will ignore:
- node_modules, vendor, dist, build
- .git, .idea, .vscode
- Lock files, binary files
- [any additional project-specific paths]

1. Yes, create
2. No, skip
3. Customize paths

4.4 Add npm scripts to package.json

Read current package.json and add scripts:

{
  "scripts": {
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "format:staged": "prettier --write $(git diff --cached --name-only --diff-filter=ACMR | grep -E '\\.(js|ts|jsx|tsx|json|md|css|scss|vue|php)$' | xargs)"
  }
}

Ask user:

Add Prettier scripts to package.json?

Scripts to add:
- format: Format all files
- format:check: Check formatting without changes
- format:staged: Format only staged files

1. Yes, add scripts
2. No, skip

Step 5: IDE Configuration

5.1 Ask which IDE

Which IDE do you use?

1. PhpStorm/WebStorm/IntelliJ
2. VS Code
3. Other/None

5.2 PhpStorm/WebStorm/IntelliJ

Create .idea/prettier.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
  <component name="PrettierConfiguration">
    <option name="myConfigurationMode" value="AUTOMATIC" />
    <option name="myRunOnSave" value="true" />
    <option name="myRunOnReformat" value="true" />
  </component>
</project>

Report:

Created .idea/prettier.xml
Prettier will run on save and on reformat (Ctrl+Alt+L / Cmd+Alt+L)

5.3 VS Code

Create or update .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[javascript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[typescript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[json]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[vue]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[php]": { "editor.defaultFormatter": "esbenp.prettier-vscode" }
}

Report:

Updated .vscode/settings.json
Install the 'Prettier - Code formatter' extension if not already installed.

5.4 Other IDEs

If user selects "Other":

Would you like me to search for Prettier integration instructions for your IDE?

Enter your IDE name, or skip:
1. Search for [IDE name]
2. Skip IDE configuration

If searching, use WebSearch to find instructions.

Step 6: Summary

Lint/Prettier Setup Complete

Created:
+ .nvmrc (v20)
+ .editorconfig
+ .prettierrc
+ .prettierignore
+ .vscode/settings.json (or .idea/prettier.xml)

Installed:
+ prettier@3.2.5
+ @prettier/plugin-php@0.22.2
+ @shopify/prettier-plugin-liquid@1.4.1

Scripts added:
+ npm run format
+ npm run format:check
+ npm run format:staged

Next steps:
1. Run 'npm run format' to format all files
2. Review changes with 'git diff'
3. Consider enabling /dogma:lint stop hook (ENV: CLAUDE_MB_DOGMA_LINT_ON_STOP=true)

Important Rules

1. Ask before creating - Never create files without user confirmation
2. Adapt to project - Only include plugins for detected file types
3. Preserve existing - Merge with existing configs, don't overwrite blindly
4. Explain choices - User should understand why each setting is recommended

Error Handling

• npm not installed: Suggest installing Node.js/nvm first
• Write permission denied: Report and suggest manual creation
• Package install fails: Show error, suggest alternatives
• Config parsing fails: Report which file and why

---

Reference: Detailed Setup Instructions

This section contains detailed instructions for manual reference. Use these when users need more context or troubleshooting help.

Why Prettier

https://prettier.io/docs/en/why-prettier

Der bei weitem wichtigste Grund fuer die Einfuehrung von Prettier ist das Beenden der staendigen Debatten ueber Coding Styles. Es ist allgemein anerkannt, dass ein gemeinsamer Styleguide fuer ein Projekt und ein Team wertvoll ist, aber der Weg dorthin ist ein sehr schmerzhafter und wenig lohnender Prozess. Die Leute werden sehr emotional, wenn es um bestimmte Arten, Code zu schreiben, geht, und niemand verbringt gerne Zeit mit dem Schreiben und dem Empfang von Kritikpunkten.

Quick Start (Full Stack with PHP)

npm install --save-dev prettier @prettier/plugin-php @shopify/prettier-plugin-liquid prettier-plugin-multiline-arrays

Plugins explained:

• prettier - Core formatter
• @prettier/plugin-php - PHP support
• @shopify/prettier-plugin-liquid - Twig support (uses liquid-html parser)
• prettier-plugin-multiline-arrays - Multiline array support in TS, JS, JSON (not PHP yet)

PHP multiline array workaround:

$foo = [
  "bar" //
]

PhpStorm/WebStorm Configuration (Detailed)

Prettier Settings

File | Settings | Languages & Frameworks | JavaScript | Prettier

• Manual Prettier configuration
  • Prettier package: Path to node_modules/prettier in project
  • ON: Run on 'Reformat Code' action
• Run for files (glob pattern):

**/*.{js,jsx,ts,tsx,html,twig,php,vue,css,scss,sass,less,json,yaml,yml,md,markdown,mdx,cjs,cts,mjs,mts,vue,astro}

Code Style Settings (Global)

File | Settings | Editor | Code Style

Scheme: Default (not Project!)

• General:
  • Line separator: System-Dependent
  • Hard wrap at: 120 | OFF: Wrap on typing
  • ON: Detect and use existing file indents for editing
  • ON: Enable EditorConfig support
• Formatter:
  • Do not format: **/*.{svg,lock,sql,map,legacy,meta,log,example};/*/**/var/**/*
  • ON: Turn formatter on/off with markers in code comments
    • Off: @formatter:off
    • On: @formatter:on

Commit Checks (Disable Initially)

File | Settings | Version Control | Commit

• OFF: Reformat code
• OFF: Rearrange code
• OFF: Optimize imports

Enable only after entire project is formatted with Prettier.

Usage Shortcuts

• Ctrl+Shift+L - Reformat with Prettier
• Ctrl+Shift+Alt+P - Prettier action
• Right-click > "Reformat with Prettier"

Recommended Plugins

• Prettier - Required for IDE integration
• PHP Annotation (Optional) - Better @Annotation, Import, Use support
• Twig (Optional) - Better Twig formatting support

Troubleshooting

If sections should NOT be formatted by Prettier, use prettier-ignore: https://prettier.io/docs/en/ignore.html#javascript

// prettier-ignore
const uglyCode = {foo: "bar", baz:    "qux"};

---

Reference: NVM Installation

Prerequisites

npm -v  # Must output a version

Ubuntu/Linux (bash/zsh)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

Add to ~/.bashrc if not present:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

Restart terminal and verify:

nvm -v && node -v && npm -v

Common Commands

nvm list              # Show installed versions
nvm install stable    # Install stable version
nvm install 20        # Install specific version
nvm use stable        # Activate version
nvm use 20            # Activate specific version

Fish Shell

Use Fisher plugin:

fisher install jorgebucaran/nvm.fish

Windows

Download from: https://github.com/coreybutler/nvm-windows/releases (Assets > nvm-setup.exe)

Install and let it set PATH.

Windows Commands

nvm version      # Show nvm version
nvm install 20   # Install Node 20
nvm use 20       # Activate Node 20

macOS

Same as Ubuntu/Linux, or use Homebrew:

brew install nvm

Add to shell config (~/.zshrc or ~/.bash_profile):

export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"