npm package: @q01/claude-skill-refapp-add-mfe
Description: CLI per installare, aggiornare e gestire la skill q01-refapp-add-mfe per Claude Code
Latest version: 1.1.0

# @q01/claude-skill-refapp-add-mfe

CLI per installare, aggiornare e gestire la skill **q01-refapp-add-mfe** per [Claude Code](https://claude.ai/download).

La skill fornisce un framework governato per integrare nuovi microfrontend in una refapp Q01 compatibile, direttamente tramite Claude Code.

---

## Requisiti

- Node.js >= 16
- Claude Code installato nel PATH

---

## Comandi

### `install`

Installa la skill in Claude Code.

```bash
npx @q01/claude-skill-refapp-add-mfe install
```

- Copia `SKILL.md`, `directives/`, `schemas/` in `~/.claude/skills/q01-refapp-add-mfe/`
- Copia `commands/` in `~/.claude/commands/q01-refapp-add-mfe/`
- Inietta il blocco di configurazione in `~/.claude/CLAUDE.md` (idempotente)
- Crea backup se trova una versione già installata
- Scrive un manifest in `~/.claude/skills/q01-refapp-add-mfe/.install-manifest.json`

### `update`

Aggiorna la skill con backup e reinstallazione sicura.

```bash
npx @q01/claude-skill-refapp-add-mfe update
```

- Verifica installazione esistente (se assente, esegue `install`)
- Crea backup di skills dir, commands dir e `CLAUDE.md`
- Sostituisce i file con la versione del package
- In caso di errore, ripristina automaticamente il backup

### `uninstall`

Rimuove la skill da Claude Code.

```bash
npx @q01/claude-skill-refapp-add-mfe uninstall
```

- Legge il manifest per sapere esattamente quali file rimuovere
- Rimuove le directory `~/.claude/skills/q01-refapp-add-mfe/` e `~/.claude/commands/q01-refapp-add-mfe/`
- Rimuove il blocco della skill da `~/.claude/CLAUDE.md`
- Non cancella file non appartenenti alla skill
- Crea backup di `CLAUDE.md` prima di modificarlo

### `doctor`

Verifica lo stato dell'installazione.

```bash
npx @q01/claude-skill-refapp-add-mfe doctor
```

Controlla:
- Prerequisiti (Node.js >= 16, Claude Code nel PATH)
- Presenza del manifest
- Versione installata vs versione package
- Presenza di tutti i file essenziali
- Iniezione del blocco in `CLAUDE.md`
- Coerenza manifest / filesystem

Exit code `0` se tutto ok, `1` se ci sono problemi critici.

---

## Variabili d'ambiente

| Variabile | Descrizione | Default |
|---|---|---|
| `Q01_CLAUDE_SKILL_TARGET` | Override del path base di installazione | `~/.claude` |
| `NO_COLOR` | Disabilita output colorato | — |
| `DEBUG` | Mostra stack trace in caso di errori | — |

`Q01_CLAUDE_SKILL_TARGET` è utile per test locali o ambienti CI senza toccare `~/.claude` reale.

---

## Uso locale (prima della pubblicazione)

```bash
# Clona/naviga nel repository
cd q01-refapp-add-mfe

# Test
node test/run-tests.js

# Esegui comandi direttamente
node bin/cli.js install
node bin/cli.js doctor
node bin/cli.js update
node bin/cli.js uninstall

# Testa su directory temporanea
Q01_CLAUDE_SKILL_TARGET=/tmp/test-install node bin/cli.js install
Q01_CLAUDE_SKILL_TARGET=/tmp/test-install node bin/cli.js doctor

# Prepara tarball locale
npm pack
# Genera: q01-claude-skill-refapp-add-mfe-1.1.0.tgz
# Installabile con: npm install -g ./q01-claude-skill-refapp-add-mfe-1.1.0.tgz
```

---

## Struttura del progetto

```
├── bin/
│   └── cli.js                    # Entry point CLI (bin)
├── src/
│   ├── index.js                  # Entry point programmatico
│   ├── commands/
│   │   ├── install.js
│   │   ├── update.js
│   │   ├── uninstall.js
│   │   └── doctor.js
│   └── lib/
│       ├── paths.js              # Risoluzione path target + env override
│       ├── fs-utils.js           # copyDir, removeDir, readText, writeText
│       ├── backup.js             # createBackup, restoreBackup
│       ├── manifest.js           # readManifest, writeManifest, buildManifest
│       ├── claude-md.js          # inject/remove blocco CLAUDE.md (sentinel)
│       └── logger.js             # [OK] [SKIP] [ERROR] [WARN] [INFO] colorati
├── skill/                        # File distribuibili della skill (sorgente canonica)
│   ├── SKILL.md
│   ├── CUSTOM_CLAUDE.md
│   ├── commands/
│   │   └── add-mfe.md
│   ├── directives/
│   │   ├── refapp_compatibility.md
│   │   ├── conventions.md
│   │   ├── integrate_microfrontend.md
│   │   └── validate_refapp_integration.md
│   └── schemas/
│       └── microfrontend.schema.json
├── test/
│   └── run-tests.js              # Test suite (21 test, usa dir temporanea)
├── package.json
└── README.md
```

---

## Come funziona la skill

La skill guida Claude Code nell'integrazione di microfrontend in una refapp Q01 seguendo questo ordine governato:

1. **Compatibility check** — verifica il profilo architetturale della refapp
2. **Input validation** — valida l'input JSON contro `microfrontend.schema.json`
3. **Apply conventions** — applica le regole di naming e mapping
4. **Integration** — modifica i 4 file autorizzati della refapp
5. **Validation** — checklist finale di coerenza

Per usarla, una volta installata, apri Claude Code nel progetto refapp e lancia:

```
/q01-refapp-add-mfe
```

---

## Manifest di installazione

Il file `~/.claude/skills/q01-refapp-add-mfe/.install-manifest.json` traccia l'installazione:

```json
{
  "version": "1.1.0",
  "installedAt": "2026-03-19T...",
  "updatedAt": null,
  "files": [ "...path assoluti dei file installati..." ],
  "claudeMdModified": true
}
```

`uninstall` e `doctor` usano questo manifest per operare in modo preciso e sicuro.