---
description: CLI command generation rules — no node -e one-liners; safe quoting and scripts
paths:
  - "**/webapplications/**/*"
---

# A4D Enforcement: CLI Command Generation & No `node -e` One-Liners

When **generating any CLI/shell commands** (for the user or for automation), follow the rules below. Default shell is **Zsh** (macOS); commands must work there without Bash-only syntax.

---

## 1. Never Use Complex `node -e` One-Liners

**Forbidden:** `node -e` (or `node -p`, `node --eval`) for file manipulation, string replacement, reading/writing configs, or multi-line logic.

**Why:** In Zsh, `node -e '...'` **silently breaks** due to:
- **`!` (history expansion):** Zsh expands `!` in double-quoted strings → `event not found` or wrong output.
- **Backticks:** `` ` `` is command substitution; the shell runs it before Node sees the string.
- **Nested quoting:** Escaping differs between Bash and Zsh; multi-line JS in one string is fragile.

**Allowed:** Trivial one-line only if it has **no** backticks, no `!`, no nested quotes, no multi-line, no `fs` usage. Example: `node -e "console.log(1+1)"`. If in doubt, **use a script file**.

---

## 2. How To Generate CLI Commands Correctly

### Run Node scripts by path, not inline code

- **Do:** `node scripts/setup-cli.mjs --target-org myorg`
- **Do:** `node path/to/script.mjs arg1 arg2`
- **Do not:** `node -e "require('fs').writeFileSync(...)"` or any non-trivial inline JS.

### For file edits or transforms

1. **Prefer IDE/agent file tools** (StrReplace, Write, etc.) — they avoid the shell.
2. **Otherwise:** write a **temporary `.js` or `.mjs` file**, run it, then remove it. Use a **heredoc with quoted delimiter** so the shell does not interpret `$`, `` ` ``, or `!`:

```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
```

3. **Simple replacements:** `sed -i '' 's/old/new/g' path/to/file` (macOS: `-i ''`).
4. **JSON:** `jq '.name = "my-app"' package.json > tmp.json && mv tmp.json package.json`.

### Quoting and shell safety

- Use **single quotes** around the outer shell string when the inner content has `$`, `` ` ``, or `!`.
- For heredocs that must be literal, use **`<< 'END'`** (quoted delimiter) so the body is not expanded.
- **Do not** generate commands that rely on Bash-only features (e.g. `[[ ]]` is fine in Zsh; avoid `source` vs `.` if you need POSIX).

### Paths and working directory

- **State where to run from** when it matters, e.g. "From project root" or "From `force-app/main/default/webapplications/<appName>`".
- Prefer **explicit paths** or `cd <dir> && ...` so the command is copy-paste safe.
- This project: setup is `node scripts/setup-cli.mjs --target-org <alias>` from **project root**. Web app commands (`npm run dev`, `npm run build`, `npm run lint`) run from the **web app directory** (e.g. `force-app/main/default/webapplications/<appName>` or `**/webapplications/<appName>`).

### npm / npx

- Use **exact package names** (e.g. `npx @salesforce/webapps-features-experimental list`).
- For app-specific scripts, **cd to the web app directory first**, then run `npm run <script>` or `npm install ...`.
- Chain steps with `&&`; one logical command per line is clearer than one giant line.

### Summary checklist when generating a command

- [ ] No `node -e` / `node -p` / `node --eval` with complex or multi-line code.
- [ ] If Node logic is needed, use `node path/to/script.mjs` or a temp script with heredoc `<< 'SCRIPT'`.
- [ ] No unescaped `!`, `` ` ``, or `$` in double-quoted strings in Zsh.
- [ ] Working directory and required args (e.g. `--target-org`) are clear.
- [ ] Prefer file-editing tools over shell one-liners when editing project files.

---

## 3. Violation Handling

- If a generated command used a complex `node -e` one-liner, **revert and redo** using a script file, `sed`/`jq`, or IDE file tools.
- If the user sees `event not found`, `unexpected token`, or garbled output, **check for**:
  - `node -e` with special characters,
  - Double-quoted strings containing `!` or backticks,
  - Wrong working directory or missing args.

**Cross-reference:** **webapp.md** (MUST FOLLOW #1) summarizes the no–`node -e` rule; this file is the full reference for CLI command generation and alternatives.
