---
description: No complex node -e one-liners — use temp .js files or sed/awk instead
paths:
  - "force-app/main/default/webapplications/**/*"
---

# A4D Enforcement: No `node -e` One-Liners

This project **forbids** using `node -e` (or `node -p`, `node --eval`) one-liners for any operation—file manipulation, string replacement, reading/writing configs, or shell automation.

## Why This Exists

Complex `node -e '...'` one-liners **silently break in Zsh** (the default macOS shell) because of:

- **`!` (history expansion):** Zsh interprets `!` inside double quotes as history expansion, causing `event not found` errors or silent corruption.
- **Backtick interpolation:** Template literals (`` ` ``) are interpreted as command substitution by the shell before Node.js ever sees them.
- **Nested quoting:** Multi-line JS crammed into a single shell string requires fragile quote escaping that differs between Bash and Zsh.

These failures are **silent and intermittent**—the command may appear to succeed while producing corrupt output.

## What To Do Instead

### For multi-line file edits or transforms

1. **Write a temporary `.js` script**, run it, then delete it:

```bash
cat > /tmp/_transform.js << 'SCRIPT'
const fs = require('fs');
const data = JSON.parse(fs.readFileSync('package.json', 'utf8'));
data.name = 'my-app';
fs.writeFileSync('package.json', JSON.stringify(data, null, 2) + '\n');
SCRIPT
node /tmp/_transform.js && rm /tmp/_transform.js
```

2. **Use `sed` or `awk`** for simple, single-pattern replacements with careful escaping:

```bash
sed -i '' 's/old-value/new-value/g' path/to/file
```

3. **Use `jq`** for JSON edits:

```bash
jq '.name = "my-app"' package.json > tmp.json && mv tmp.json package.json
```

4. **Use the IDE/agent file-editing tools** (replace_in_file, write_to_file, StrReplace, Write) whenever available—these bypass the shell entirely.

### For simple, truly one-line expressions

A trivial `node -e "console.log(1+1)"` with no special characters is acceptable, but **if the expression contains any of these, use a temp file instead:**
- Template literals (backticks)
- `!` characters
- Nested quotes
- Multi-line strings
- `fs` read/write operations

## Violation Handling

- If any prior step used a complex `node -e` one-liner, **revert and redo** using one of the approved methods above.
- If a shell command fails with `event not found`, `unexpected token`, or produces garbled output, check for a `node -e` violation first.

**Cross-reference:** This rule is also summarized in **webapp.md** (MUST FOLLOW #1). Both apply.
