trdr-ds-install 1.2.5 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trdr-ds-install",
-  "version": "1.2.5",
+  "version": "1.3.1",
   "description": "Installs the TRDR Design System skill for Claude Code",
   "bin": {
     "trdr-ds-install": "./bin/install.js"
@@ -9,7 +9,8 @@
     "sync-components": "node scripts/sync-components.js",
     "sync-tokens": "node scripts/sync-tokens.js",
     "sync": "node scripts/sync-tokens.js && node scripts/sync-components.js",
-    "sync:local": "node scripts/sync-tokens.js --local ../trdr-design-hub && node scripts/sync-components.js --local ../trdr-design-hub"
+    "sync:local": "node scripts/sync-tokens.js --local ../trdr-design-hub && node scripts/sync-components.js --local ../trdr-design-hub",
+    "postpublish": "node bin/install.js"
   },
   "files": [
     "bin/",

package/plugins/trdr-design-system/skills/trdr-ds/SKILL.md

@@ -1,11 +1,14 @@
 ---
 name: trdr-ds
-description: Applies the TRDR Design System to any project. Runs a two-phase workflow - first analyzes the project and presents a migration plan for approval, then executes the full implementation (tokens, components, CLAUDE.md, violation fixes). Trigger when developer mentions "apply design system", "implement TRDR DS", "add TRDR tokens", "design system setup", "migrar design system", "aplicar design system", or invokes /trdr-ds.
+description: Applies the TRDR Design System to any project. Runs a two-phase workflow - first analyzes the project and presents a migration plan for approval, then executes the full implementation (tokens, components, CLAUDE.md, violation fixes). For large projects (50+ violations), execution is batched by folder with progress saved to DS_PROGRESS.md and resumable at any time. Trigger when developer mentions "apply design system", "implement TRDR DS", "add TRDR tokens", "design system setup", "migrar design system", "aplicar design system", or invokes /trdr-ds.
 user-invocable: true
-argument-hint: "[analyze|apply|sync]"
+argument-hint: "[analyze|apply|resume|status|sync|batch N]"
 allowed-tools: [Read, Glob, Grep, Edit, Write, Bash, WebFetch]
 ---
 
+**Skill version:** 1.3.0
+**npm package:** trdr-ds-install
+
 You are implementing the **TRDR Design System** in a developer's project. The Design Hub is the single source of truth and lives at **https://trdr.mrocontent.com.br**.
 
 This skill ships with two **offline-first snapshots** of the Hub:
@@ -25,6 +28,9 @@ Execute in two clearly separated phases: **PHASE 1: ANALYZE → PHASE 2: EXECUTE
 |-----|-----------|
 | `analyze` *(default when none given)* | Run Phase 1 only — produce a migration plan, do not modify any project file |
 | `apply` | Run Phase 1 + Phase 2 |
+| `resume` | Read `DS_PROGRESS.md` from the project root and continue from the last checkpoint (Phase 2 batching only) |
+| `status` | Read `DS_PROGRESS.md` and display a progress summary table — no files modified |
+| `batch [N]` | Override default batch size for Phase 2 (default: 25 files/batch) |
 | `sync` | Re-fetch `https://trdr.mrocontent.com.br/components.json` and `https://trdr.mrocontent.com.br/tokens.css`, overwrite `data/components.json` and `references/tokens.css` in the skill directory, report the diff. No project changes. |
 | `--latest` *(modifier on `analyze` or `apply`)* | Same as `sync` first, then continue normally |
 
@@ -34,6 +40,58 @@ Execute in two clearly separated phases: **PHASE 1: ANALYZE → PHASE 2: EXECUTE
 
 Scan the project and produce a structured migration plan. Do NOT modify any project files yet.
 
+### Step 0 — Check for skill updates, then detect previous progress
+
+**Version check (runs on every invocation):**
+
+Run this command silently via Bash:
+```bash
+npm show trdr-ds-install version 2>/dev/null
+```
+
+Compare the result with the **Skill version** constant at the top of this file (`1.3.0`).
+
+- If the command fails or returns empty (no internet / npm unavailable): skip silently, continue.
+- If registry version == local version: skip silently, continue.
+- If registry version > local version:
+  ```
+  🔄 Nova versão da skill disponível: trdr-ds-install@[registry-version] (instalada: 1.3.0)
+
+  Responda:
+  - `"atualizar"` / `"update"` — instalar a nova versão agora (requer reiniciar /trdr-ds após)
+  - `"continuar"` / `"skip"` — usar a versão atual desta sessão
+  ```
+  **STOP.** Wait for reply.
+
+  If reply is `"atualizar"` / `"update"`:
+  - Run Bash: `npx trdr-ds-install@latest`
+  - Output:
+    ```
+    ✅ Skill atualizada para trdr-ds-install@[registry-version].
+    Use /trdr-ds novamente para continuar com a versão mais recente.
+    ```
+  - STOP. Do not continue with the current (old) instructions.
+
+**After version check, detect previous progress:**
+
+Check if `DS_PROGRESS.md` exists at the project root.
+
+**If found AND `Status:` line is NOT `COMPLETE`:**
+```
+⚠️ Previous TRDR DS migration found (status: [IN_PROGRESS/PAUSED]).
+
+Reply with:
+- `"resume"` — continue from last checkpoint (Batch [N])
+- `"restart"` — discard progress and run a fresh analysis
+- `"status"` — see a progress summary without modifying anything
+```
+**STOP HERE. Wait for the developer's reply.**
+
+**If found AND `Status: COMPLETE`:**
+Inform the dev that a previous migration was already completed (show date). Offer to re-run analysis to detect new files added since then. Continue only if the dev explicitly says so.
+
+**If not found:** Continue normally to Step 1.
+
 ### Step 1 — Detect framework
 
 Read `package.json` at the project root. Identify:
@@ -89,6 +147,11 @@ Flag any gradient that doesn't reference a TRDR gradient token (`var(--gradient-
 **H — Hardcoded font-size in px** (should use .trdr-h* / .trdr-body-* text style classes):
 Search: `font-size:\s*\d+px` in CSS/SCSS files (skip tokens.css itself)
 
+Track:
+- `total_violations` = sum of all A–H occurrences
+- `total_files_with_violations` = count of unique files with ≥ 1 violation
+- `violations_by_folder` = map of `{ folder: string, files: string[], count: number }[]` grouped by first-level folder inside `src/` (or project root if no `src/`)
+
 ### Step 3.5 — Detect component replacement candidates
 
 Scan the project for UI patterns that indicate elements replaceable by TRDR implemented components.
@@ -176,7 +239,11 @@ Use the loaded data throughout the rest of the workflow. Track:
 
 ### Step 5 — Present the migration plan and STOP
 
-Output the following report and **do not proceed** until the developer explicitly approves:
+Output the following report and **do not proceed** until the developer explicitly approves.
+
+Determine execution mode based on thresholds:
+- **Small project** (`total_violations <= 50` AND `total_files_with_violations <= 30`): standard monolithic execution — no batching, no DS_PROGRESS.md
+- **Large project** (`total_violations > 50` OR `total_files_with_violations > 30`): batched execution — include the large project warning below
 
 ```markdown
 ## TRDR Design System — Migration Plan
@@ -230,11 +297,21 @@ Output the following report and **do not proceed** until the developer explicitl
 
 > **Implementados:** o CSS já estará em `components.css` após a Fase 2 — o dev só precisa trocar as classes.
 > **Stubs:** receberão banner comment com tokens recomendados + entrada em `MISSING_COMPONENTS.md`.
-> **Não listados aqui:** componentes específicos da TRDR (boleta, janela) — verificar manualmente se o projeto os usa.
 
 ### SCOPE ESTIMATE: [Small / Medium / Large]
 Small = <10 violations | Medium = 10–50 | Large = 50+
 
+[ONLY for large projects — include this block:]
+### ⚠️ LARGE PROJECT DETECTED
+[total_violations] violations across [total_files_with_violations] files.
+Phase 2 will run in **BATCHES BY FOLDER** to prevent context overflow and allow resuming.
+
+Default batch: 25 files/batch → ~[ceil(total_files_with_violations/25)] batches estimated
+Progress saved to `DS_PROGRESS.md` — resumable anytime with `/trdr-ds resume`.
+
+To change batch size: reply with `"Apply, batch 15"` or `"Apply, batch 40"`.
+[END large project block]
+
 ### WHAT WILL NOT BE TOUCHED:
 - Images, SVGs, fonts files
 - node_modules/, .next/, dist/, build/, out/
@@ -245,6 +322,7 @@ Small = <10 violations | Medium = 10–50 | Large = 50+
 
 **Reply with one of:**
 - `"Apply"` or `"Executar"` — proceed with everything above
+- `"Apply, batch [N]"` — proceed with custom batch size (large projects only)
 - `"Apply, skip [file or directory]"` — proceed but exclude specific paths
 - `"Only tokens"` — only create tokens.css, components.css, and CLAUDE.md (no violation fixes)
 - `"Change [detail]"` — adjust a specific part of the plan before executing
@@ -257,7 +335,55 @@ Small = <10 violations | Medium = 10–50 | Large = 50+
 
 ## PHASE 2: EXECUTION (only after explicit approval)
 
-Execute in order. Report progress after each major step.
+Parse the developer's reply:
+- Extract batch size override from `"Apply, batch N"` → use N; otherwise default to 25.
+- Extract skip paths from `"Apply, skip [path]"` → exclude those from violation processing.
+- `"Only tokens"` → skip Steps 5 and 6 (no violation fixes, no component banners).
+
+Report progress after each major step.
+
+### Step 0 — Initialize checkpoint
+
+**Determine execution mode:**
+```
+if total_violations <= 50 AND total_files_with_violations <= 30:
+  mode = MONOLITHIC  (no DS_PROGRESS.md created — skip to Step 1)
+else:
+  mode = BATCHED     (create DS_PROGRESS.md, execute in batches)
+```
+
+**For BATCHED mode — create `DS_PROGRESS.md` at the project root:**
+
+```markdown
+# TRDR DS Migration — Progress
+Started: [ISO datetime]
+Project: [project name from package.json]
+Batch size: [N]
+Status: IN_PROGRESS
+
+## Foundation
+- [ ] tokens.css
+- [ ] components.css
+- [ ] CLAUDE.md
+- [ ] @import no CSS global
+
+## Lotes de Violações
+Total de arquivos com violações: [total_files_with_violations]
+Total de violações: [total_violations]
+Total de lotes: [N]
+
+[For each folder in violations_by_folder, sorted alphabetically.
+ If a folder has more files than batch_size, split into sub-batches labeled "1a", "1b", etc.
+ Files at the project root (not inside src/) go in a final "raiz" batch.]
+
+### Lote 1 — [folder/] ([N] arquivos) — PENDING
+### Lote 2 — [folder/] ([N] arquivos) — PENDING
+...
+### Lote [n] — raiz ([N] arquivos) — PENDING
+
+## Padrões Sem Token (revisão manual)
+[empty — filled during execution]
+```
 
 ### Step 1 — Create tokens.css
 
@@ -274,6 +400,11 @@ If `references/tokens.css` is missing in the skill directory:
 1. Try `WebFetch: https://trdr.mrocontent.com.br/tokens.css`, save it to the skill dir, then proceed.
 2. If the Hub is also unreachable → STOP with error message asking the maintainer to run `npm run sync`.
 
+**For BATCHED mode:** After writing tokens.css, update `DS_PROGRESS.md`:
+```
+- [x] tokens.css — [path]/tokens.css
+```
+
 ### Step 2 — Create components.css
 
 Build `components.css` by concatenating the `.code.css` block of every implemented component plus the typography utility classes.
@@ -312,6 +443,11 @@ After all component CSS blocks, append the text style utility classes:
 .trdr-label-l3 { font-family: var(--font-secondary); font-size: 14px; font-weight: 600; line-height: 1.4; }
 ```
 
+**For BATCHED mode:** Update `DS_PROGRESS.md`:
+```
+- [x] components.css — [path]/components.css
+```
+
 ### Step 3 — Update global CSS
 
 Find the main global CSS file (globals.css, main.css, index.css, app.css) and add at the very top:
@@ -325,6 +461,11 @@ Adjust the relative path if tokens.css is in a subdirectory.
 
 If the project already imports a different design system's variables and there are naming conflicts, warn the developer before proceeding.
 
+**For BATCHED mode:** Update `DS_PROGRESS.md`:
+```
+- [x] @import — [global-css-file]
+```
+
 ### Step 4 — Create CLAUDE.md
 
 Create `CLAUDE.md` at the project root, populated dynamically from the catalog:
@@ -383,9 +524,62 @@ bg.primary (base) → bg.secondary/tertiary (content areas) → surface.* (cards
 → interactive components → overlays/modals/tooltips
 ```
 
+**For BATCHED mode:** Update `DS_PROGRESS.md`:
+```
+- [x] CLAUDE.md — CLAUDE.md
+```
+
+Then output:
+```
+✅ Foundation complete — tokens.css, components.css, CLAUDE.md, @import all done.
+Starting violation processing in [N] batches of up to [batch_size] files each.
+```
+
 ### Step 5 — Migrate violations
 
-For each violation found in Phase 1, apply the semantic token replacement.
+**MONOLITHIC mode:** Process all files with violations in one pass. Apply all replacements below. Continue to Step 6.
+
+**BATCHED mode:** Process one batch at a time, with a STOP between batches.
+
+For each batch listed as PENDING in `DS_PROGRESS.md`:
+
+1. Update `DS_PROGRESS.md` — change batch status to `IN_PROGRESS`
+2. For each file in the batch:
+   - Apply all applicable violation fixes (see mapping tables below)
+   - Count violations fixed
+3. Update `DS_PROGRESS.md` — change batch status to `COMPLETED`:
+   ```
+   ### Lote [N] — [folder/] ([N] arquivos) — COMPLETED
+   Violações corrigidas: [N] | Arquivos: [N]/[N]
+   ```
+   Add any unfixable patterns to the "Padrões Sem Token" section of `DS_PROGRESS.md`.
+4. Output batch summary:
+   ```
+   ✅ Lote [N] concluído — [folder/] ([N] arquivos, [N] violações corrigidas)
+   Progresso geral: [done]/[total] lotes | [total_fixed] violações corrigidas
+   ```
+5. If more batches are PENDING:
+
+   **STOP HERE.** Output:
+   ```
+   Próximo: **Lote [N+1] — [folder/]** ([N] arquivos)
+   Responda:
+   - "continuar" / "continue" — processar próximo lote
+   - "pular [pasta]" — skip this folder and go to the next batch
+   - "parar" / "stop" — save progress and stop here (resume later with `/trdr-ds resume`)
+   - "tudo" / "all" — process all remaining batches without pausing
+   ```
+   **Wait for developer reply.**
+
+   If reply is `"tudo"` / `"all"`: process all remaining batches without pausing (update DS_PROGRESS.md after each).
+   If reply is `"pular [pasta]"`: mark that batch as SKIPPED in DS_PROGRESS.md and move to the next.
+   If reply is `"parar"`: set `Status: PAUSED` in DS_PROGRESS.md. STOP. Do not proceed to Step 6 or 7.
+
+6. After ALL batches are COMPLETED (or skipped): continue to Step 6.
+
+---
+
+**Violation mapping tables (used in Steps 5 for both modes):**
 
 **Color mapping (hardcoded → semantic):**
 | Hardcoded value | Context | Replace with |
@@ -430,17 +624,17 @@ For each violation found in Phase 1, apply the semantic token replacement.
 **rgba() mapping:**
 | Hardcoded pattern | Context | Replace with |
 |-------------------|---------|-------------|
-| `rgba(0,0,0,*)` | box-shadow | No TRDR shadow token exists → flag in DS_MIGRATION.md as "Missing shadow token" |
+| `rgba(0,0,0,*)` | box-shadow | No TRDR shadow token exists → flag in DS_PROGRESS.md / DS_MIGRATION.md as "Missing shadow token" |
 | `rgba(255,255,255,.29)` approx | overlay/backdrop | `var(--bg-overlay)` |
-| `rgba(255,255,255,*)` other | overlay | flag in DS_MIGRATION.md |
+| `rgba(255,255,255,*)` other | overlay | flag |
 | Any other `rgba(N,N,N,*)` | various | Map to nearest semantic alpha token (--surface-brand, --surface-info, --action-*-alpha, etc.) or flag |
 
 **Gradient mapping:**
 | Pattern | Replace with |
 |---------|-------------|
 | `linear-gradient(...)` using only TRDR brand colors | `var(--gradient-text-brand)`, `var(--gradient-bg-hero)`, or `var(--gradient-bg-fade)` as appropriate |
-| `linear-gradient(...)` using any non-DS colors | Flag in DS_MIGRATION.md as non-compliant — developer must decide: remove, replace with a TRDR gradient token, or add a new token to the Hub |
-| Gradient inside SVG data URI embedded in CSS | Flag in DS_MIGRATION.md |
+| `linear-gradient(...)` using any non-DS colors | Flag — developer must decide: remove, replace with TRDR gradient token, or add new token to Hub |
+| Gradient inside SVG data URI embedded in CSS | Flag |
 
 **Font-size mapping:**
 | Hardcoded value | Replace with |
@@ -457,14 +651,14 @@ For each violation found in Phase 1, apply the semantic token replacement.
 | `font-size: 14px` | `.trdr-body-b3` or `.trdr-label-l3` (check weight context) |
 | `font-size: 12px` | `.trdr-body-b4` or `.trdr-body-aux` (check letter-spacing) |
 | `font-size: 10px` | `.trdr-body-b5` class |
-| `font-size: [other px]` | Nearest text style class — flag in DS_MIGRATION.md if no match |
+| `font-size: [other px]` | Nearest text style class — flag if no match |
 
 **Do NOT replace:**
 - Hex values inside binary image files (PNG, JPG, GIF)
-- SVG external files — flag them in DS_MIGRATION.md but do not auto-edit
+- SVG external files — flag them but do not auto-edit
 - Values in commented-out code
 
-**All other values MUST be replaced or flagged.** There are no exceptions for "decorative" gradients, shadows, or overlays. If no semantic token exists for a given pattern, flag it in DS_MIGRATION.md under "Missing DS tokens" and notify the developer to request the token in the Hub.
+**All other values MUST be replaced or flagged.** No exceptions for "decorative" gradients, shadows, or overlays.
 
 ### Step 6 — Apply component code (smart fallback)
 
@@ -490,7 +684,7 @@ Use the `replacementCandidates[]` list built in Phase 1 Step 3.5. For each entry
      - Status: ⚠️ stub — code blocks pending
      ```
 4. **If no slug matches** the detected pattern:
-   - Flag the pattern in `MISSING_COMPONENTS.md` under "Unmapped patterns" with the file location and a one-line description of the UI need. The maintainer can then decide whether to add a stub to the catalog.
+   - Flag the pattern in `MISSING_COMPONENTS.md` under "Unmapped patterns" with the file location and a one-line description of the UI need.
 
 ### Step 7 — Generate DS_MIGRATION.md
 
@@ -509,6 +703,7 @@ Hub: https://trdr.mrocontent.com.br
 - ✅ [N] violations fixed in [M] files
 - ✅ [global-css] updated with @import
 - ⚠️ [S] stub components flagged in MISSING_COMPONENTS.md (if any)
+[If batched: - ✅ Migrated in [N] batches — see DS_PROGRESS.md for batch-level detail]
 
 ## Files modified
 [List each file and what changed]
@@ -522,11 +717,10 @@ Hub: https://trdr.mrocontent.com.br
   - Others: add Google Fonts `<link>` in HTML head
 - [ ] **Dark/light mode**: tokens.css uses [data-theme="light"] for overrides — add `data-theme="light"` to `<html>` to activate light mode
 - [ ] **Trading UI**: If this project has price/position displays, verify context.trading.* tokens are applied (see Hub: /tokens/semanticos)
-- [ ] **Stubs**: Review MISSING_COMPONENTS.md and decide whether to wait for canonical implementation in the Hub or hand-roll the component now using the listed tokens
+- [ ] **Stubs**: Review MISSING_COMPONENTS.md and decide whether to wait for canonical implementation in the Hub or hand-roll using the listed tokens
 - [ ] **Skipped files**: [list any files excluded from migration]
 
 ## Missing DS tokens (flagged — no semantic token available)
-[List patterns found in the project that have no TRDR token yet — request these in the Hub]
 | Pattern | File | Suggestion |
 |---------|------|-----------|
 | `box-shadow: rgba(0,0,0,*)` | [file:line] | Request shadow token in Hub |
@@ -543,6 +737,12 @@ Hub: https://trdr.mrocontent.com.br
 - Rules: https://trdr.mrocontent.com.br/para-ia
 ```
 
+**For BATCHED mode:** After writing DS_MIGRATION.md, update `DS_PROGRESS.md`:
+```
+Status: COMPLETE
+Completed: [ISO datetime]
+```
+
 ---
 
 ## EXECUTION SUMMARY
@@ -558,6 +758,7 @@ Created:
   • CLAUDE.md (design system context for Claude Code)
   • DS_MIGRATION.md (migration log + manual checklist)
   • MISSING_COMPONENTS.md ([S] stubs flagged) — only if applicable
+  [If batched: • DS_PROGRESS.md (migration log — status: COMPLETE)]
 
 Modified:
   • [global-css] — @import added
@@ -571,6 +772,63 @@ Hub: https://trdr.mrocontent.com.br
 
 ---
 
+## RESUME MODE (when invoked with `resume` argument)
+
+1. Look for `DS_PROGRESS.md` at the project root.
+   - If not found: output `❌ No previous migration found. Run /trdr-ds to start a new one.`
+   - If `Status: COMPLETE`: output `✅ Migration already complete (finished [date]). Run /trdr-ds to check for new violations.`
+
+2. Read `DS_PROGRESS.md`. Find the first batch with status `IN_PROGRESS` or `PENDING`.
+
+3. Output a resume summary:
+   ```
+   Resuming TRDR DS migration — [project name]
+   Foundation: ✅ complete
+   Batches completed: [done]/[total] | Violations fixed so far: [N]
+   Resuming at: **Lote [N] — [folder/]** ([N] files)
+   ```
+
+4. Continue Phase 2 Step 5 from that batch. Follow the same STOP-between-batches flow.
+
+5. After all batches finish: run Steps 6 and 7 (component banners + DS_MIGRATION.md).
+
+---
+
+## STATUS MODE (when invoked with `status` argument)
+
+1. Look for `DS_PROGRESS.md` at the project root.
+   - If not found: output `No migration in progress. Run /trdr-ds to start.`
+
+2. Read `DS_PROGRESS.md` and output a progress table — do NOT modify any files:
+
+```
+## TRDR DS — Migration Status
+
+Project: [name] | Started: [date] | Status: [IN_PROGRESS/PAUSED/COMPLETE]
+
+### Foundation
+| Step | File | Status |
+|------|------|--------|
+| tokens.css | [path] | ✅ / ⏳ |
+| components.css | [path] | ✅ / ⏳ |
+| CLAUDE.md | CLAUDE.md | ✅ / ⏳ |
+| @import | [global-css] | ✅ / ⏳ |
+
+### Violation Batches
+| Lote | Pasta | Arquivos | Violações | Status |
+|------|-------|----------|-----------|--------|
+| 1 | src/components/ | 12 | 34 | ✅ COMPLETED |
+| 2 | src/pages/ | 8 | 12 | 🔄 IN_PROGRESS |
+| 3 | src/app/ | 15 | — | ⏳ PENDING |
+| 4 | src/styles/ | 6 | — | ⏳ PENDING |
+
+Progress: [N]% ([done]/[total] batches — [violations_fixed]/[total_violations] violations fixed)
+
+To continue: `/trdr-ds resume`
+```
+
+---
+
 ## SYNC MODE (when invoked as `/trdr-ds sync`)
 
 1. WebFetch `https://trdr.mrocontent.com.br/components.json` → save as `<skill-dir>/data/components.json`
@@ -581,7 +839,7 @@ Hub: https://trdr.mrocontent.com.br
    - Removed: [list slugs no longer in catalog]
 4. No project files are touched.
 
-If either fetch fails, report which one and exit with a non-zero status. Do NOT touch the snapshot if the fetch succeeded but the response is malformed (e.g., missing `components` array).
+If either fetch fails, report which one and exit. Do NOT touch the snapshot if the response is malformed (e.g., missing `components` array).
 
 ---