From e8288f73bd0e57eb322bcf5ffe7378d796a5f08d Mon Sep 17 00:00:00 2001 From: Pier-Paolo Mammi Date: Thu, 16 Jul 2026 15:27:53 +0200 Subject: [PATCH] add skill for markdown also move some files around --- .../docs}/APM-050525-0947-1550.pdf | Bin .../SKILL.md | 46 ---- .agents/skills/markdown-linting/SKILL.md | 203 ++++++++++++++++++ .github/copilot-instructions.md | 13 -- docs/debug-api-vscode-docker.md | 82 ++++--- 5 files changed, 253 insertions(+), 91 deletions(-) rename {docs => .agents/docs}/APM-050525-0947-1550.pdf (100%) delete mode 100644 .agents/skills/debug-api-php-con-vs-code-e-docker/SKILL.md create mode 100644 .agents/skills/markdown-linting/SKILL.md delete mode 100644 .github/copilot-instructions.md diff --git a/docs/APM-050525-0947-1550.pdf b/.agents/docs/APM-050525-0947-1550.pdf similarity index 100% rename from docs/APM-050525-0947-1550.pdf rename to .agents/docs/APM-050525-0947-1550.pdf diff --git a/.agents/skills/debug-api-php-con-vs-code-e-docker/SKILL.md b/.agents/skills/debug-api-php-con-vs-code-e-docker/SKILL.md deleted file mode 100644 index 3e32863..0000000 --- a/.agents/skills/debug-api-php-con-vs-code-e-docker/SKILL.md +++ /dev/null @@ -1,46 +0,0 @@ -# Debug API PHP con VS Code e Docker - -Questa sezione descrive la procedura per fare debug delle API PHP servite da Docker in questa repository. - -## Passaggi - -1. Avvia il container Docker dalla root del progetto: - ```bash - docker compose up --build - ``` - -2. Apri Visual Studio Code e vai su "Run and Debug". - -3. Seleziona la configurazione: - ```text - Debug PHP in Docker - ``` - -4. Premi F5 per avviare il debugger. - -5. Imposta un breakpoint in un controller, ad esempio in: - ```text - src/Api/Controllers/V1/UsersController.php - ``` - -6. Richiama l’endpoint tramite browser o curl: - ```bash - curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users - ``` - -## Nota - -Il container deve esporre: -- porta `8000` per HTTP -- porta `9003` per Xdebug - -Il progetto contiene già i file necessari per il debug: -- `.docker/php/Dockerfile` -- `docker-compose.yml` -- `.vscode/launch.json` -- `.vscode/settings.json` - -## Problemi comuni - -- Se VS Code non si ferma sul breakpoint, verifica che Xdebug sia abilitato nel container e che la configurazione `client_host` punti a `host.docker.internal`. -- Se il container non si avvia, controlla che Docker Desktop sia in esecuzione. diff --git a/.agents/skills/markdown-linting/SKILL.md b/.agents/skills/markdown-linting/SKILL.md new file mode 100644 index 0000000..63196ef --- /dev/null +++ b/.agents/skills/markdown-linting/SKILL.md @@ -0,0 +1,203 @@ +--- +name: markdown-linting +description: Markdown formatting standards following markdownlint practices +applyTo: [markdown] +--- + +# Markdown Linting Skill + +This skill documents markdown formatting standards for this project, following markdownlint practices. + +## Core Rules + +### Headings +- Use `#` for headings (not underlines with `===` or `---`) +- Headings must have space after `#`: `# Heading` ✓, `#Heading` ✗ +- Heading levels must increment by 1: `# > ## > ###` (don't skip levels) +- File must start with a level 1 heading (H1) +- Use sentence case for headings (capitalize only first word unless proper noun) + +### Line Endings & Spacing +- Trim trailing whitespace at end of lines +- No more than one blank line between elements +- Use consistent list marker spacing: 1 space after marker +- Between major sections: exactly 1 blank line + +### Lists +- Use `-` for unordered lists (not `*` or `+`) +- Lists must be indented consistently (2 spaces or 4 spaces) +- Ordered lists use `1. 2. 3.` (always `1.` for first item) +- List items with multiple paragraphs: indent continuation 4 spaces +- Blank line before and after lists (if between other content) + +### Code +- Inline code with backticks: `` `code` `` +- Code blocks use triple backticks with language: ` ```php `, ` ```bash `, ` ```json ` +- Blank line before code block +- Blank line after code block +- Use fenced code blocks (` ``` `), not indentation + +### Links & Images +- Use reference-style or inline links: `[text](url)` +- Image syntax: `![alt text](path/to/image.png)` +- URLs must be valid and properly formatted +- Don't use bare URLs (wrap in `<>` or use markdown link syntax) + +### Emphasis +- Use `**bold**` for bold (not `__bold__`) +- Use `*italic*` for italic (not `_italic_`) +- Underscores on word boundaries only + +### Line Length +- Keep lines under 120 characters where practical +- Long URLs and code blocks are exceptions +- Wrap long text at sentence boundaries + +### Blockquotes +- Use `>` for blockquotes with space after: `> quote` ✓ +- Blank line after blockquote if followed by text + +## Template Structure + +### Documentation Files + +```markdown +# Main Title + +Brief introduction (1-2 sentences). + +## Section One + +Content here. + +### Subsection + +Details. + +## Section Two + +More content. + +## See Also + +- [Link text](url) +``` + +### API Documentation + +```markdown +# API Endpoint Name + +Brief description. + +## Overview + +What this does. + +## Prerequisites + +- Prerequisite 1 +- Prerequisite 2 + +## Usage + +### Request + +```bash +curl command +``` + +### Response + +```json +json example +``` + +## Configuration + +- Option 1: description +- Option 2: description + +## Troubleshooting + +### Problem + +Solution. + +## See Also + +- [Related](link) +``` + +### Guides & Tutorials + +```markdown +# Tutorial Title + +Brief intro. + +## Prerequisites + +- Item 1 + +## Step 1: Title + +Description and code. + +## Step 2: Title + +Description and code. + +## Verification + +How to test. + +## Troubleshooting + +Issues and fixes. +``` + +## Quick Checklist + +- [ ] File starts with `# Title` (H1) +- [ ] Headings have space after `#` +- [ ] No heading level jumps +- [ ] No trailing whitespace +- [ ] Max 1 blank line between sections +- [ ] Lists use `-` consistently +- [ ] Code blocks have language specified +- [ ] Inline code uses backticks +- [ ] Links are properly formatted +- [ ] No bare URLs +- [ ] Lines under 120 chars where practical +- [ ] Bold uses `**text**`, italic uses `*text*` +- [ ] All section transitions are clear + +## Common Violations to Avoid + +❌ `#No space after hash` +✓ `# Space after hash` + +❌ `# Heading\n\n\n## Next` (two blank lines) +✓ `# Heading\n\n## Next` (one blank line) + +❌ `* or + for lists` +✓ `- for all lists` + +❌ Bare URL `http://example.com` +✓ Wrapped URL `` +✓ Link `[text](http://example.com)` + +❌ Indented code blocks +✓ Fenced code blocks ` ``` ` + +❌ `# Skip to ### level` +✓ `# Then ## Then ###` + +❌ __emphasis with underscores__ +✓ **emphasis with asterisks** + +## References + +- [Markdownlint Rules](https://github.com/markdownlint/markdownlint/blob/main/README.md) +- [CommonMark Spec](https://spec.commonmark.org/) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index 0371607..0000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,13 +0,0 @@ -# Istruzioni per lo sviluppo di questa repository - -## Debug delle API PHP con Docker - -Quando si lavora su questa repository e si deve fare debug delle API PHP servite via Docker, usare il setup seguente: - -- avviare il container con `docker compose up --build` -- usare la configurazione VS Code `Debug PHP in Docker` -- mettere breakpoint nei controller sotto `src/Api/Controllers` -- testare le richieste su `http://localhost:8000` -- se il debugger non parte, usare `curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users` - -Queste istruzioni valgono anche per eventuali problemi di routing o di esecuzione delle API. diff --git a/docs/debug-api-vscode-docker.md b/docs/debug-api-vscode-docker.md index c6e17b9..9eef838 100644 --- a/docs/debug-api-vscode-docker.md +++ b/docs/debug-api-vscode-docker.md @@ -8,7 +8,21 @@ Queste istruzioni permettono di fare debug delle API PHP servite con Docker dire - Visual Studio Code - Estensione PHP per VS Code -## 1. Avvia il container +## 1. Configurazione del progetto + +Il progetto contiene già i file necessari per il debug: + +- `.docker/php/Dockerfile` - container PHP con Xdebug +- `docker-compose.yml` - configurazione Docker +- `.vscode/launch.json` - configurazione di avvio VS Code +- `.vscode/settings.json` - impostazioni VS Code + +Il container espone: + +- **porta `8000`** per HTTP +- **porta `9003`** per Xdebug + +## 2. Avvia il container Dalla root del progetto esegui: @@ -22,52 +36,56 @@ Il server PHP sarà disponibile su: http://localhost:8000 ``` -## 2. Avvia il debug in VS Code +## 3. Avvia il debug in VS Code -Apri la sezione Run and Debug e seleziona la configurazione: +1. Apri la sezione **Run and Debug** in VS Code (Ctrl+Shift+D) +2. Seleziona la configurazione: **Debug PHP in Docker** +3. Premi **F5** per avviare il debugger -```text -Debug PHP in Docker -``` +## 4. Imposta un breakpoint e testa -Poi premi F5. +1. Aggiungi un breakpoint in un controller, ad esempio: -## 3. Imposta un breakpoint + ```text + src/Api/Controllers/V1/UsersController.php + ``` -Aggiungi un breakpoint in un controller, ad esempio in: +2. Richiama un endpoint tramite browser: -```text -src/Api/Controllers/V1/UsersController.php -``` + ```text + http://localhost:8000/api/users + ``` -Quindi richiama un endpoint come: +3. Oppure usa curl con il trigger Xdebug: -```text -http://localhost:8000/api/users -``` + ```bash + curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users + ``` -## 4. Se il debugger non parte +Il debugger dovrebbe fermarsi sul breakpoint e permetterti di ispezionare le variabili. -Prova a inviare la richiesta con il trigger Xdebug: +## 5. Risoluzione dei problemi -```bash -curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users -``` +### VS Code non si ferma sul breakpoint -## 5. Configurazione attesa +- Verifica che Xdebug sia abilitato nel container +- Controlla che la configurazione `client_host` nel Dockerfile punti a `host.docker.internal` +- Verifica che la porta 9003 sia disponibile e non bloccata dal firewall -Il progetto contiene già: +### Il container non si avvia -- un Dockerfile PHP con Xdebug -- un file docker-compose.yml -- una configurazione di avvio VS Code in .vscode/launch.json +- Assicurati che Docker Desktop sia in esecuzione +- Verifica che le porte 8000 e 9003 non siano già in uso +- Controlla i log di Docker per errori specifici -## 6. Nota importante +### "Failed to fetch" dalle richieste del frontend -Il server PHP viene eseguito con: +- Verifica che il frontend abbia il CORS correttamente configurato +- Controlla che `allowed_origins` in `config/config.php` includa l'origine del frontend +- Testa con l'endpoint di diagnostica `/cors-check` -```bash -php -S 0.0.0.0:8000 -t public public/index.php -``` +## Note -Questa modalità è adatta per il debug delle API HTTP del progetto. +- La procedura di debug influisce solo sulla sessione VS Code, il server continua a funzionare normalmente +- È possibile debug con i breakpoint condizionali per limitare i fermi +- Usa la console di debug di VS Code per eseguire comandi PHP durante il debug