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

CLI per installare, aggiornare e gestire la skill q01-refapp-add-mfe per Claude Code.

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.

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.

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.

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.

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)

# 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:

{
  "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.