@deerdesign/deertools 1.0.4 → 1.2.1

package/docs/prezentacja-it-deertools.md

@@ -0,0 +1,182 @@
+# DeerTools CLI & MCP Ecosystem
+## Prezentacja Architektoniczna dla Zespołu IT
+
+> **Wersja:** 1.1.0 · Node.js 18+  
+> **Organizacja:** [github.com/DeerDesign/deertools-cli](https://github.com/DeerDesign/deertools-cli)  
+> **Paczka npm:** `@deerdesign/deertools`  
+> **Wersja interaktywna HTML:** [docs/prezentacja-it-deertools.html](./prezentacja-it-deertools.html)
+
+---
+
+## Slajd 1 · Cover
+### DeerTools CLI & MCP Ecosystem
+*Standard narzędziowy i mostek protokołu MCP dla zespołów IT oraz Agentów AI*
+
+- **Zakres:** Architektura zero-dependency, bezpieczeństwo OAuth 2.0 PKCE, integracja 5 domen Deer oraz lokalny silnik BaseLinker Hub & MCP Proxy.
+- **Autorzy:** Deer Design AI & Architecture Team
+
+---
+
+## Slajd 2 · Agenda
+
+1. **Filozofia Zero-Dependency Engine:** silnik Node.js >= 18 bez podatności supply-chain.
+2. **Dystrybucja i instalacja:** npm global, ad-hoc npx, klonowanie repozytorium GitHub.
+3. **Model Bezpieczeństwa:** OAuth 2.0 Authorization Code Flow + PKCE S256, uprawnienia 0600, obsługa CI/CD.
+4. **Ekosystem 5 domen:** Kosztorys, Katalog, Dostawy, Supplier Hub, RenderMind.
+5. **BaseLinker Hub & MCP (v1.1.0):** 204 metody API offline, Token Bucket Rate Limiter (95 req/min), lokalny Web Hub.
+6. **Integracja z Agentami AI:** konfiguracja Cursor IDE, Antigravity i Claude Desktop.
+7. **Narzędzia IT:** `doctor`, `audit`, `profile` i autouzupełnianie powłoki.
+
+---
+
+## Slajd 3 · Architektura & Zero-Dependency Engine
+
+- **0 zewnętrznych zależności w `package.json`:**
+  - 100% wykorzystanie wbudowanych modułów standardowych: `node:http`, `node:crypto`, `node:fs`, `node:test`.
+  - Zero ryzyka ataku na łańcuch dostaw (supply-chain attack) i zero problemów licencyjnych.
+  - Czas startu binarki < 50ms.
+- **Dwustronna rola w ekosystemie IT:**
+  - **Dla Inżyniera / DevOpsa:** wygodne narzędzie wiersza poleceń do zarządzania kluczami, audytu, przełączania profili oraz weryfikacji zdrowia serwisów (`doctor`).
+  - **Dla Agenta AI (Cursor / Antigravity / Claude):** natywny serwer protokołu MCP (Model Context Protocol) komunikujący się przez strumienie stdio (JSON-RPC) lub Server-Sent Events (SSE).
+
+---
+
+## Slajd 4 · Instalacja & Wdrożenie
+
+### 1. Globalna instalacja (zalecana dla deweloperów):
+```bash
+npm install -g @deerdesign/deertools
+
+# Rejestruje 2 aliasy w systemie:
+deertools --version   # 1.1.0
+deer whoami           # skrócony alias
+```
+
+### 2. Uruchomienie ad-hoc bez instalacji:
+```bash
+npx @deerdesign/deertools doctor
+```
+
+### 3. Klonowanie repozytorium (wersja deweloperska):
+```bash
+git clone https://github.com/DeerDesign/deertools-cli.git
+cd deertools-cli
+npm test              # uruchamia 31/31 wbudowanych testów
+npm link              # podpina lokalną wersję do ścieżki PATH
+```
+
+**Wymagania:** Node.js >= 18.0.0 (macOS, Linux, Windows WSL).
+
+---
+
+## Slajd 5 · Bezpieczeństwo & Model Poświadczeń
+
+### Przepływ OAuth 2.0 PKCE S256 (RFC 7636):
+1. CLI generuje kryptograficznie bezpieczny `code_verifier` (43+ znaki) oraz jego hash `code_challenge` (SHA-256 base64url).
+2. Otwiera przeglądarkę i uruchamia lokalny serwer loopback pod adresem `127.0.0.1:3000`.
+3. Po autoryzacji serwer loopback odbiera jednorazowy `code` i dokonuje bezpośredniej wymiany na klucz API w bezpiecznym kanale back-channel HTTPS.
+4. **Klucze i tokeny nigdy nie trafiają do parametrów URL przeglądarki ani do historii.**
+
+### Ochrona kluczy na dysku & CI/CD:
+- Poświadczenia zapisywane są w pliku `~/.deertools/credentials.json` z restrykcyjnymi uprawnieniami pliku **0600** (dostępny wyłącznie dla procesu właściciela).
+- W środowiskach bezgłowych (Headless) i pipeline'ach CI/CD klucze można przekazywać przez zmienne środowiskowe:
+```bash
+export DEERTOOLS_CATALOG_KEY="deer_catalog_live_..."
+export DEERTOOLS_ESTIMATE_KEY="deer_kosztorys_live_..."
+export DEERTOOLS_DELIVERIES_KEY="deer_dostawy_live_..."
+export DEERTOOLS_SUPPLIER_KEY="deer_supplier_live_..."
+export DEERTOOLS_RENDERMIND_KEY="deer_rendermind_live_..."
+export DEERTOOLS_BASELINKER_TOKEN="4000000-..."
+```
+
+---
+
+## Slajd 6 · Ekosystem 5 Domen DeerTools
+
+| Domena | ID CLI | Opis i Możliwości |
+|---|---|---|
+| **Kosztorys** | `estimate` | Kalkulacja marż i kosztów wykończenia dla pakietów Smart, Modern i High Life. Algorytmy obmiarów i wyceny. |
+| **Katalog** | `catalog` | Dostęp do bazy ~17 000 produktów wykończeniowych, atrybuty techniczne, warianty i synchronizacja cen. |
+| **Dostawy** | `deliveries` | Delivery Hub: dokumenty WZ, magazyny, statusy kurierskie, zarządzanie dostawami na budowy. |
+| **Supplier Hub** | `supplier` | Łańcuch marżowy, rabaty producenckie, promocje sprzedaży i reguły cenowe dla lokalizacji. |
+| **RenderMind** | `rendermind` | Silnik fotorealistycznych renderów wnętrz, estymacje z rzutów PDF i analiza szkiców pCon. |
+
+---
+
+## Slajd 7 · BaseLinker Hub & Proxy MCP (Nowość w v1.1.0)
+
+- **204 Metody API offline:**
+  - 93 metody katalogowe (`Product catalog`), 51 metod zamówień, 21 metod zwrotów, 16 metod kurierskich.
+  - Kompletny zrzut parametrów, typów i opisów z oficjalnej dokumentacji BaseLinkera zapisany w lokalnym cache.
+- **Token Bucket Rate Limiter:**
+  - Sztywny bufor **95 req / 60 sekund** zapobiega przekroczeniu limitu 100 req/min i błędom HTTP 429.
+- **Wysokopoziomowe narzędzia katalogu:**
+  - Budowanie relacji produktów (`related`, `substitution`, `upsell`, `downsell`, `crosssell`).
+  - Zarządzanie galerią zdjęć na pozycjach 0–15 (URL i base64).
+  - Warianty, zestawy (bundle), kategorie, producenci i tagi.
+  - Masowe aktualizacje cen i stanów magazynowych do 1000 sztuk w jednym wywołaniu.
+- **Lokalny serwer Web Hub:**
+  - Uruchomienie: `deertools baselinker serve --port 3456`
+  - Dashboard przeglądarkowy z formularzem tokena, testem połączenia i strumieniem zdarzeń SSE dla Agenta AI.
+
+---
+
+## Slajd 8 · Integracja z Agentami AI (MCP Protocol 2024-11-05)
+
+### Automatyczna instalacja konfiguracji:
+```bash
+deertools mcp install       # Rejestruje serwery MCP w plikach konfiguracyjnych IDE
+deertools skill install all # Instaluje definicje umiejętności (SKILL.md) dla agentów
+```
+
+### Obsługiwane środowiska:
+1. **Cursor IDE:**
+   - Globalnie: `~/.cursor/mcp.json`
+   - Projektowo: `.cursor/mcp.json`
+2. **Google Antigravity / Gemini Workspace:**
+   - Projektowo: `.agents/mcp_config.json`
+3. **Claude Desktop / Ollama / Inne narzędzia LLM:**
+   - Dedykowany mostek stdio: `deertools mcp serve` lub `deertools baselinker mcp`.
+
+### Ochrona budżetu kontekstowego LLM:
+- Domyślnie serwer eksponuje **15 kluczowych narzędzi wysokopoziomowych** + uniwersalne `bl_search_methods` i `bl_call_api`.
+- Opcjonalna flaga `--all` eksponuje pełne 219 narzędzi dla modeli o bardzo dużym oknie kontekstowym.
+
+---
+
+## Slajd 9 · Diagnostyka, Audyt i Multi-Profiling
+
+### 1. `deertools doctor`
+- Kompleksowa diagnostyka środowiska wykonawczego:
+  - Wersja Node.js i stan uprawnień pliku poświadczeń (0600).
+  - Sprawdzenie wolnych portów lokalnych (3000 dla OAuth, 3456 dla BaseLinkera).
+  - Test łączności i czasy ping HTTP do wszystkich 5 serwisów produkcyjnych i BaseLinkera.
+  - Sprawdzenie ważności tokenów i kluczy API.
+  - Test poprawności bazy schematów (204 metody) oraz handshake JSON-RPC MCP.
+  - Weryfikacja rejestracji serwerów w plikach konfiguracyjnych agentów.
+  - Flaga `--json` umożliwia wpięcie w systemy automatycznego monitoringu IT.
+
+### 2. `deertools audit`
+- Lokalny rejestr wywołań API przez agentów AI.
+- Monitorowanie metody, czasu wykonania, parametrów i kodów odpowiedzi.
+- Opcje: `deertools audit --limit 50`, `deertools audit --clear`.
+
+### 3. `deertools profile`
+- Zarządzanie wieloma profilami poświadczeń (np. produkcja, staging, dev-lokalny).
+- Komendy: `deertools profile list`, `deertools profile add <nazwa>`, `deertools profile use <nazwa>`.
+
+### 4. `deertools completion`
+- Generowanie skryptów autouzupełniania komend i flag dla powłoki:
+```bash
+eval "$(deertools completion zsh)"  # lub bash
+```
+
+---
+
+## Slajd 10 · Podsumowanie
+
+- **Bezpieczeństwo przede wszystkim:** Brak zewnętrznych zależności npm, bezpieczny OAuth PKCE, pliki 0600.
+- **Standaryzacja AI:** Jedno spójne CLI i serwer MCP łączący całą infrastrukturę Deer Design i BaseLinkera.
+- **Gotowe do użycia:** Repozytorium na GitHubie, pełny zestaw 31 testów automatycznych, CI/CD i dokumentacja.
+
+**Repozytorium:** [https://github.com/DeerDesign/deertools-cli](https://github.com/DeerDesign/deertools-cli)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deerdesign/deertools",
-  "version": "1.0.4",
+  "version": "1.2.1",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -35,6 +35,7 @@
   "files": [
     "bin",
     "src",
+    "docs",
     "README.md"
   ],
   "engines": {

package/src/audit.js

@@ -0,0 +1,65 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { c, formatTable } = require('./formatters');
+
+function getAuditFilePath() {
+  const home = process.env.DEERTOOLS_HOME || path.join(os.homedir(), '.deertools');
+  return path.join(home, 'audit.log');
+}
+
+function logAudit(entry) {
+  try {
+    const file = getAuditFilePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      ...entry,
+    }) + '\n';
+    fs.appendFileSync(file, line, { mode: 0o600 });
+  } catch (_) {
+    // Non-blocking
+  }
+}
+
+async function cmdAudit(pos, flags) {
+  const file = getAuditFilePath();
+  if (flags.clear) {
+    if (fs.existsSync(file)) fs.unlinkSync(file);
+    process.stdout.write('✓ Historia audytu została wyczyszczona.\n');
+    return;
+  }
+
+  if (!fs.existsSync(file)) {
+    process.stdout.write('Brak wpisów audytu (plik ~/.deertools/audit.log nie istnieje).\n');
+    return;
+  }
+
+  const raw = fs.readFileSync(file, 'utf8').trim().split('\n').filter(Boolean);
+  const limit = flags.limit ? Number(flags.limit) : 25;
+  const entries = raw.slice(-limit).map(l => {
+    try { return JSON.parse(l); } catch (_) { return null; }
+  }).filter(Boolean).reverse();
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(entries, null, 2) + '\n');
+    return;
+  }
+
+  process.stdout.write(`\n${c.bold}Historia operacji CLI i API (ostatnie ${entries.length}):${c.reset}\n`);
+  const headers = ['Czas', 'Produkt', 'Metoda', 'Ścieżka', 'Status', 'Czas (ms)'];
+  const rows = entries.map(e => [
+    e.ts ? e.ts.slice(11, 19) : '',
+    e.product || 'system',
+    e.method || 'CLI',
+    e.path || e.action || '',
+    e.status != null ? (e.status >= 200 && e.status < 300 ? `${c.green}${e.status}${c.reset}` : `${c.red}${e.status}${c.reset}`) : `${c.gray}–${c.reset}`,
+    e.duration_ms != null ? `${e.duration_ms}ms` : '',
+  ]);
+
+  process.stdout.write(formatTable(headers, rows) + '\n\n');
+  process.stdout.write(`${c.dim}Wyczyść historię: deertools audit --clear${c.reset}\n`);
+}
+
+module.exports = { logAudit, cmdAudit };

package/src/baselinker/browser-login.js

@@ -0,0 +1,214 @@
+'use strict';
+const http = require('http');
+const { exec } = require('child_process');
+const { saveBaseLinkerToken } = require('../credentials');
+const { BaseLinkerClient } = require('./client');
+
+function openBrowser(url) {
+  const cmd = process.platform === 'win32' ? `start "" "${url}"` : process.platform === 'darwin' ? `open "${url}"` : `xdg-open "${url}"`;
+  exec(cmd, () => {});
+}
+
+function renderLoginPage(error = null, success = false, inventoriesCount = 0) {
+  return `<!DOCTYPE html>
+<html lang="pl">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>DeerTools · Logowanie do BaseLinker</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <style>
+    :root {
+      --bg: #0B0F17;
+      --card-bg: rgba(22, 29, 43, 0.85);
+      --card-border: rgba(255, 255, 255, 0.08);
+      --primary: #C5A880;
+      --primary-hover: #D4BA94;
+      --text: #F1F5F9;
+      --text-muted: #94A3B8;
+      --success: #10B981;
+      --danger: #EF4444;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; font-family: 'Plus Jakarta Sans', sans-serif; }
+    body {
+      background: var(--bg); color: var(--text); min-height: 100vh;
+      display: flex; align-items: center; justify-content: center; padding: 24px 16px;
+    }
+    .card {
+      background: var(--card-bg); border: 1px solid var(--card-border); border-radius: 20px;
+      padding: 36px; max-width: 480px; width: 100%; box-shadow: 0 24px 60px rgba(0,0,0,0.5);
+      backdrop-filter: blur(16px); text-align: left;
+    }
+    .logo-badge { display: flex; align-items: center; gap: 12px; margin-bottom: 20px; }
+    .badge {
+      background: rgba(197, 168, 128, 0.15); color: var(--primary);
+      padding: 4px 10px; border-radius: 999px; font-size: 12px; font-weight: 600;
+      border: 1px solid rgba(197, 168, 128, 0.3);
+    }
+    h1 { font-size: 22px; font-weight: 700; color: #fff; margin-bottom: 8px; letter-spacing: -0.5px; }
+    p { font-size: 14px; color: var(--text-muted); line-height: 1.5; margin-bottom: 20px; }
+    .info-box {
+      background: rgba(11, 15, 23, 0.6); border: 1px solid var(--card-border);
+      border-radius: 10px; padding: 12px 14px; font-size: 13px; color: var(--text-muted); margin-bottom: 20px;
+    }
+    .info-box b { color: #fff; }
+    .alert {
+      padding: 12px 14px; border-radius: 10px; font-size: 13px; margin-bottom: 20px; font-weight: 500;
+    }
+    .alert-danger { background: rgba(239, 68, 68, 0.15); border: 1px solid rgba(239, 68, 68, 0.3); color: #FCA5A5; }
+    .alert-success { background: rgba(16, 185, 129, 0.15); border: 1px solid rgba(16, 185, 129, 0.3); color: #6EE7B7; text-align: center; }
+    .form-group { margin-bottom: 20px; }
+    label { display: block; font-size: 13px; font-weight: 600; color: var(--text); margin-bottom: 8px; }
+    input[type="password"] {
+      width: 100%; background: rgba(11, 15, 23, 0.9); border: 1px solid var(--card-border);
+      border-radius: 10px; padding: 12px 16px; color: #fff; font-size: 15px; outline: none;
+      transition: all 0.2s;
+    }
+    input[type="password"]:focus { border-color: var(--primary); box-shadow: 0 0 0 3px rgba(197, 168, 128, 0.2); }
+    button {
+      width: 100%; padding: 13px 20px; border-radius: 10px; font-size: 14px; font-weight: 700;
+      cursor: pointer; border: none; background: var(--primary); color: #000; transition: all 0.2s;
+    }
+    button:hover { background: var(--primary-hover); transform: translateY(-1px); }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="logo-badge">
+      <svg width="26" height="26" viewBox="0 0 24 24" fill="none" stroke="#C5A880" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z"></path><polyline points="3.27 6.96 12 12.01 20.73 6.96"></polyline><line x1="12" y1="22.08" x2="12" y2="12"></line></svg>
+      <span class="badge">DeerTools Local Auth</span>
+    </div>
+
+    ${success ? `
+      <div class="alert alert-success">
+        <h2 style="font-size: 18px; margin-bottom: 6px; color: #fff;">✓ Zalogowano pomyślnie!</h2>
+        <p style="margin-bottom: 8px; color: inherit;">Połączenie z BaseLinker aktywne (katalogi: <b>${inventoriesCount}</b>).</p>
+        <p style="font-size: 12px; margin-bottom: 0;">Klucz zapisany w <code>~/.deertools/credentials.json</code>.<br>Możesz zamknąć tę kartę przeglądarki.</p>
+      </div>
+    ` : `
+      <h1>Logowanie do BaseLinker</h1>
+      <p>Podaj swój klucz API BaseLinkera, aby umożliwić agentom AI bezpieczny dostęp do Twojego katalogu produktów.</p>
+
+      <div class="info-box">
+        Gdzie znaleźć klucz? Zaloguj się w panelu BaseLinkera i przejdź do zakładki: <b>Konto / inne &rarr; Moje konto &rarr; API</b>.
+      </div>
+
+      ${error ? `<div class="alert alert-danger">${error}</div>` : ''}
+
+      <form method="POST" action="/submit">
+        <div class="form-group">
+          <label for="token">Klucz API (X-BLToken)</label>
+          <input type="password" id="token" name="token" placeholder="Wklej token np. 3001234-45678-ABCDEF..." autofocus required>
+        </div>
+        <button type="submit">Zaloguj i połącz</button>
+      </form>
+    `}
+  </div>
+</body>
+</html>`;
+}
+
+/**
+ * Uruchamia lokalny serwer logowania dla BaseLinkera i otwiera przeglądarkę,
+ * działając identycznie jak logowanie OAuth pozostałych produktów.
+ */
+async function loginBaseLinkerBrowser(opts = {}) {
+  const timeoutMs = opts.timeoutMs || 5 * 60 * 1000;
+  const open = opts.openBrowser === undefined ? openBrowser : opts.openBrowser;
+  const log = opts.log || console.log;
+
+  return new Promise((resolve, reject) => {
+    let finished = false;
+
+    const server = http.createServer(async (req, res) => {
+      const parsedUrl = new URL(req.url, `http://${req.headers.host || '127.0.0.1'}`);
+
+      if (req.method === 'GET') {
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(renderLoginPage());
+        return;
+      }
+
+      if (req.method === 'POST' && parsedUrl.pathname === '/submit') {
+        let body = '';
+        req.on('data', chunk => body += chunk);
+        req.on('end', async () => {
+          try {
+            const formData = new URLSearchParams(body);
+            const token = formData.get('token')?.trim();
+            if (!token) {
+              res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+              res.end(renderLoginPage('Proszę podać token API.'));
+              return;
+            }
+
+            // Weryfikacja tokena z oficjalnym API BaseLinkera
+            let test;
+            if (opts.verifyToken) {
+              test = await opts.verifyToken(token);
+            } else {
+              const client = new BaseLinkerClient(token);
+              test = await client.testConnection();
+            }
+
+            if (!test.ok) {
+              res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+              res.end(renderLoginPage(`Błąd połączenia z BaseLinkerem: ${test.error}`));
+              return;
+            }
+
+            // Zapisz poświadczenia
+            saveBaseLinkerToken(token);
+
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(renderLoginPage(null, true, (test.inventories || []).length));
+
+            const entry = {
+              key: token,
+              scope: 'api catalog',
+              source: 'file',
+              inventories: test.inventories
+            };
+
+            setTimeout(() => done(null, entry), 500);
+          } catch (err) {
+            res.writeHead(500, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(renderLoginPage(`Wystąpił błąd: ${err.message}`));
+          }
+        });
+        return;
+      }
+
+      res.writeHead(404);
+      res.end('Not Found');
+    });
+
+    const timer = setTimeout(() => {
+      done(new Error('Upłynął czas oczekiwania na logowanie do BaseLinker (5 min).'));
+    }, timeoutMs);
+
+    if (opts.signal) {
+      opts.signal.addEventListener('abort', () => done(new Error('Aborted')));
+    }
+
+    function done(err, entry) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      server.close();
+      if (err) reject(err); else resolve(entry);
+    }
+
+    server.on('error', err => done(err));
+    server.listen(opts.port || 0, '127.0.0.1', () => {
+      const port = server.address().port;
+      const loginUrl = `http://127.0.0.1:${port}/`;
+      log(`Otwieram przeglądarkę pod adresem:\n${loginUrl}\nAby się zalogować, wklej swój token API BaseLinker (X-BLToken).`);
+      if (open) open(loginUrl);
+    });
+  });
+}
+
+module.exports = { loginBaseLinkerBrowser };