From a0219520bf718312398173659be27e645f5e3a80 Mon Sep 17 00:00:00 2001 From: Murphy Freelance <70611945+murphy-freelance@users.noreply.github.com> Date: Sat, 4 Jul 2026 19:06:57 +0200 Subject: [PATCH] feat: add guided /gw-triage:setup for Jira token Replaces the manual shell-profile steps in the README: the skill verifies the token before saving it to ~/.claude/settings.json env, where Claude Code injects it shell-independently. --- .claude-plugin/plugin.json | 2 +- README.md | 40 +++++-------- skills/setup/SKILL.md | 118 +++++++++++++++++++++++++++++++++++++ skills/triage/SKILL.md | 11 ++-- 4 files changed, 141 insertions(+), 30 deletions(-) create mode 100644 skills/setup/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index d3ddde6..5102e68 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "gw-triage", "description": "Da screenshot + messaggio Telegram a issue Jira instradata al dev giusto", - "version": "0.1.1", + "version": "0.2.0", "author": { "name": "GrowingWay" } diff --git a/README.md b/README.md index 0f709cf..56dbc8a 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ assegnata al dev giusto. `/plugin marketplace add https://git.growingway.com/giuse/gw-triage.git` `/plugin install gw-triage` 4. **Token API** (per allegare gli screenshot — facoltativo ma - consigliato): sezione sotto. + consigliato): esegui `/gw-triage:setup` e segui le istruzioni. ## Token API Jira @@ -22,34 +22,26 @@ Serve solo ad allegare gli screenshot alle issue (l'MCP Atlassian non supporta gli allegati). Senza token tutto funziona lo stesso: viene saltato solo l'allegato. -1. Apri - (login con l'account Atlassian aziendale). -2. **Create API token** → etichetta `gw-triage` → scegli la scadenza → - **copia subito il token** (viene mostrato una volta sola). -3. Aggiungi le credenziali al profilo della shell: - - bash/zsh: `export JIRA_EMAIL="tu@azienda.it"` e - `export JIRA_API_TOKEN=""` - - fish: `set -Ux JIRA_EMAIL tu@azienda.it` e - `set -Ux JIRA_API_TOKEN ` -4. Verifica: - `curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" https://growingway.atlassian.net/rest/api/3/myself` - deve restituire il tuo profilo in JSON. +Esegui `/gw-triage:setup` in Claude Code: ti guida nella creazione del +token dalla pagina Atlassian, te lo chiede, lo verifica e lo salva da +solo. Niente configurazione manuale della shell. -⚠️ Il token agisce a tuo nome su Jira: non committarlo mai. Se trapela, -revocalo dalla stessa pagina. Quando scade, `/gw-triage:triage` continua a -funzionare — salta solo l'allegato finché non ne esporti uno nuovo. +⚠️ Il token agisce a tuo nome su Jira: non condividerlo. Se trapela, +revocalo da . +Quando scade, `/gw-triage:triage` continua a funzionare — salta solo +l'allegato: rilancia `/gw-triage:setup` per sostituirlo. ## Uso quotidiano -1. Salva lo screenshot dal messaggio Telegram. -2. In Claude Code: **trascina il file nel prompt** (così può essere - allegato alla issue), incolla il messaggio e invoca +1. In Claude Code allega uno screenshot (**trascina il file nel + prompt**, così può essere allegato alla issue) e/o scrivi una breve + descrizione del problema, sufficiente a identificarlo, poi invoca `/gw-triage:triage`. -3. Rispondi all'eventuale domanda di chiarimento, conferma la bozza → +2. Rispondi all'eventuale domanda di chiarimento, conferma la bozza → la issue viene creata e ricevi il link. -Funziona anche senza screenshot (solo testo) o con l'immagine incollata -dagli appunti — in quel caso l'allegato va trascinato in Jira a mano. +Se l'immagine è incollata dagli appunti anziché trascinata come file, +l'allegato va poi trascinato in Jira a mano. ## Aggiornare la conoscenza dei repo @@ -61,8 +53,8 @@ il profilo aggiornato viene pushato qui e gli altri lo ricevono con ## Problemi comuni - **"MCP Atlassian non disponibile"** → passi 1–2 dell'installazione. -- **"Allegato saltato"** → controlla `JIRA_EMAIL` / `JIRA_API_TOKEN` - (sezione Token API). +- **"Allegato saltato"** → esegui `/gw-triage:setup` (token mancante, + scaduto o sessione da riavviare). - **La issue finisce nell'epic sbagliata** → correggi in Jira e apri una issue su questo repo per aggiustare `config/routing.json` o il profilo in `knowledge/`. diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md new file mode 100644 index 0000000..72e9387 --- /dev/null +++ b/skills/setup/SKILL.md @@ -0,0 +1,118 @@ +--- +name: setup +description: Use when configuring the Jira API credentials for gw-triage — first-time setup, an "allegato saltato" warning from triage, missing or expired JIRA_EMAIL/JIRA_API_TOKEN, or replacing a revoked token. Triggers on /gw-triage:setup, "configura il token", "gli allegati non funzionano". +--- + +# Setup — token API Jira guidato + +You guide the user through creating a Jira API token and storing it so +the `triage` skill can attach screenshots to issues. + +**All interaction with the user happens in Italian.** This file is +English for precision; never quote it to the user. + +The only consumer of the token is the `triage` skill (its curl +attachment call), which runs inside Claude Code. Credentials therefore +go in the `env` block of `~/.claude/settings.json` — Claude Code +injects them into every session, regardless of the user's shell. Never +touch shell profiles. + +**Keep the token out of replies and displayed commands.** Refer to it +as "il token" and never repeat its value. Never inline a literal token +on a shell command line — it ends up in the transcript and the process +list. Shell variables may be passed as unexpanded `$VAR` references; +literal values (pasted or read from a file) go through the temp netrc +file described in Step 0.3. + +## Step 0 — Check existing configuration + +1. Run `test -n "$JIRA_EMAIL" && test -n "$JIRA_API_TOKEN" && echo session || echo unset`. +2. Read `~/.claude/settings.json` (if it exists) and note whether + `env.JIRA_EMAIL` / `env.JIRA_API_TOKEN` are present. +3. If credentials exist in either place, verify them. The check call is + + curl -s -o /dev/null -w "%{http_code}" \ + \ + https://growingway.atlassian.net/rest/api/3/myself + + (host = the `site` in `${CLAUDE_PLUGIN_ROOT}/config/routing.json`, + without the scheme). For ``: + - session env vars set → `-u "$JIRA_EMAIL:$JIRA_API_TOKEN"`, with the + `$` references left unexpanded for the shell to fill in — never + substitute the values yourself. + - literal values (from settings.json or a paste) → use the Write + tool to create a netrc file in the session scratchpad directory: + + machine growingway.atlassian.net + login + password + + `chmod 600` it and pass `--netrc-file ` instead of `-u`. + Delete this file before the skill ends, whatever the outcome. + + Result: + - `200` → tell the user (Italian) the token already works and ask + whether they want to replace it anyway. If not, stop. + - anything else → tell them the stored token no longer works + (probably expired or revoked) and continue. + +## Step 1 — Token creation (user, in the browser) + +Print in Italian, compactly: + +1. Apri + (login con l'account Atlassian aziendale). +2. **Create API token** → nome `gw-triage` → scegli la scadenza → + **copia subito il token** (viene mostrato una volta sola). +3. Incolla qui email aziendale e token (vanno bene anche su due righe). + +Add one line: il token verrà salvato in chiaro in +`~/.claude/settings.json` sul suo computer, quindi non condividere né il +file né questa conversazione. + +End the turn and wait. If the reply contains only one of the two +values, ask for the missing one. If the user can't create the token +(no permission, page unreachable), stop and suggest asking whoever +manages the Atlassian accounts. + +## Step 2 — Verify before saving + +Run the Step 0.3 check with the pasted values — literals, so via the +temp netrc file, never `-u` on the command line. + +- `200` → proceed to Step 3. +- `401`/`403` → wrong email or token (a common cause: copied with a + trailing space or truncated). Ask the user to re-copy and re-paste, + then verify again; stop after the third failed verification overall + and suggest creating a fresh token. +- Anything else (timeout, DNS) → network problem, not credentials: + report it and stop; the pasted token stays valid for a later retry. + +## Step 3 — Save to settings.json + +Update `~/.claude/settings.json` with Read + Edit/Write (never shell +text-mangling): + +- File missing → create it containing only + `{"env": {"JIRA_EMAIL": "", "JIRA_API_TOKEN": ""}}`. +- Valid JSON → add or overwrite the two keys inside the existing `env` + object (create the object if absent). Preserve every other key + untouched. +- Invalid JSON → do NOT overwrite; show the user the parse error and + stop. + +Leftover check: old installs configured the shell profile instead. Run +`fish -c 'set -U' 2>/dev/null | grep -i jira` and +`grep -l JIRA_API_TOKEN ~/.config/fish/config.fish ~/.config/fish/conf.d/*.fish ~/.zshrc ~/.bashrc ~/.zprofile ~/.profile 2>/dev/null`. +If anything turns up, tell the user (Italian) to remove it so it can't +shadow the new token (fish: `set -e JIRA_EMAIL; set -e JIRA_API_TOKEN`; +altrimenti togliere gli `export` dal file indicato). + +## Step 4 — Report + +Delete the temp netrc file if one was created. + +In Italian: token verificato e salvato. Vale dalle **prossime** sessioni +di Claude Code — quelle già aperte vanno riavviate prima che l'allegato +automatico funzioni. Per sostituirlo o dopo una revoca basta rilanciare +`/gw-triage:setup`. diff --git a/skills/triage/SKILL.md b/skills/triage/SKILL.md index 2b1b93a..b370f5e 100644 --- a/skills/triage/SKILL.md +++ b/skills/triage/SKILL.md @@ -25,11 +25,12 @@ them in ONE ToolSearch call before Step 0: - esegui `/mcp`, seleziona `atlassian` e completa il login nel browser con l'account aziendale - poi rilancia `/gw-triage:triage` 2. Run `test -n "$JIRA_EMAIL" && test -n "$JIRA_API_TOKEN" && echo ok || echo missing`. - If `missing`: continue, but tell the user (Italian) that the - screenshot cannot be attached automatically and point them to the - "Token API Jira" section of the plugin README - (`${CLAUDE_PLUGIN_ROOT}/README.md`) — show the 4 token steps inline, - once, then proceed. + If `missing`: check whether `~/.claude/settings.json` has + `env.JIRA_EMAIL`/`env.JIRA_API_TOKEN`. If yes, the session predates + the config: tell the user (Italian) to restart Claude Code to enable + automatic attachments. If no, tell them the screenshot cannot be + attached automatically and that `/gw-triage:setup` configures it in + a couple of minutes. Either way, say it once and proceed. ## Step 1 — Input