@deerdesign/deertools 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# deertools — DeerTools CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Logujesz się raz z laptopa, a Twój agent AI dostaje dostęp do API produktów DeerTools: **w Twoim imieniu, nie szerzej niż Ty, w ograniczonym zakresie**.
+
+Produkty: `kosztorys`, `katalog`, `dostawy`, `supplier`, `rendermind`. Adresy produkcyjne: Kosztorys i Katalog na `https://connect.deerdesign.pl/kosztorys/` i `/katalog/`, Dostawy `https://ship.deergroup.pl/`, Supplier Hub `https://supplier.deergroup.pl/`, RenderMind `https://rendermind.deergroup.pl/`.
+
+## Instalacja na dowolnym komputerze
+
+Wymaga Node.js ≥ 18. Pakiet jest opublikowany w publicznym rejestrze npm:
+
+```bash
+# Opcja 1: Uruchomienie bezpośrednio bez wcześniejszej instalacji:
+npx @deerdesign/deertools login kosztorys
+
+# Opcja 2: Instalacja globalna w systemie (udostępnia komendy 'deertools' oraz 'deer'):
+npm install -g @deerdesign/deertools
+deertools --help
+# lub krócej:
+deer whoami
+```
+
+## Logowanie
+
+```bash
+deertools login kosztorys          # jeden produkt, zakres: tylko odczyt (read)
+deertools login katalog --write    # odczyt i zapis
+deertools login all                # kolejno wszystkie produkty
+deertools whoami                   # status, zakres, ważność
+deertools logout kosztorys
+```
+
+Jak to działa (OAuth 2.1, kod autoryzacyjny + PKCE, RFC 8252):
+
+1. CLI uruchamia serwer na `127.0.0.1` (losowy port), otwiera przeglądarkę na stronie `…/oauth/authorize` produktu.
+2. Logujesz się w produkcie (Microsoft w Kosztorysie; kod lub link z e-maila gdzie indziej) i klikasz „Zezwól na dostęp”. Możesz obniżyć zakres do samego odczytu.
+3. Przeglądarka wraca do CLI wyłącznie z **jednorazowym kodem** (ważnym 60 s). Klucza API nie ma w adresie.
+4. CLI wymienia kod na klucz bezpośrednio z serwerem produktu (dowód PKCE) i zapisuje go w `~/.deertools/credentials.json` z uprawnieniami `600`.
+
+Klucz: `deer_<produkt>_live_…`, ważny 90 dni, unieważnisz go w produkcie (Ustawienia → Dostęp API). Zakres domyślny to **read**; `write` wymaga `--write` i zgody w przeglądarce. Adresy autoryzacji i wymiany kodu CLI pobiera z `…/.well-known/oauth-authorization-server` produktu (RFC 8414) i odmawia logowania, gdy produkt nie deklaruje PKCE (S256).
+
+## Użycie przez agenta
+
+```bash
+deertools docs <produkt>               # llms.txt: czym jest produkt, jak się uwierzytelnić (publiczne)
+deertools docs <produkt> openapi       # pełna specyfikacja OpenAPI
+deertools endpoints <produkt>          # lista endpointów z zakresem (read/write)
+deertools api <produkt> GET /ścieżka --query k=v
+deertools api <produkt> POST /ścieżka --data '{"a":1}'
+deertools skill install [produkt|all]  # instaluje skill agenta z produktu do ~/.gemini/config/skills
+deertools estimate --file rzut.pdf     # wycena rzutu (Kosztorys)
+```
+
+`deertools api` wysyła klucz **wyłącznie** pod adres API produktu (tylko ścieżki względne) i podpowiada, co zrobić przy 401, 403 i 429. Kody wyjścia: `0` ok · `1` błąd żądania · `2` błędne użycie · `3` brak lub wygasłe logowanie · `4` brak dokumentacji lub adresu API.
+
+Zmienne środowiskowe dla CI i agentów: `DEERTOOLS_<PRODUKT>_KEY` (np. `DEERTOOLS_KATALOG_KEY`), `DEERTOOLS_HOME` (katalog poświadczeń).
+
+## Rozwój i publikacja
+
+```bash
+npm test        # testy węzła (node --test), bez zależności
+```
+
+Publikacja (GitHub Packages): zawartość tego katalogu jest korzeniem repozytorium `DeerDesign/deertools-cli`. Zwiększ wersję w `package.json`, zatwierdź i wypchnij tag `v<wersja>`; workflow `.github/workflows/publish-package.yml` uruchomi testy, sprawdzi zgodność tagu z wersją i opublikuje pakiet. Ręcznie: `npm login --scope=@deerdesign --registry=https://npm.pkg.github.com`, potem `npm publish` (token z `write:packages`).

package/bin/deertools.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+'use strict';
+require('../src/cli').main(process.argv.slice(2)).then((code) => { process.exitCode = code; });

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@deerdesign/deertools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "description": "DeerTools CLI: logowanie z laptopa i dostęp agenta AI do API produktów DeerTools (Kosztorys, Katalog, Dostawy, Supplier Hub, RenderMind)",
+  "bin": {
+    "deertools": "bin/deertools.js",
+    "deer": "bin/deertools.js"
+  },
+  "main": "./src/cli.js",
+  "scripts": {
+    "start": "node ./bin/deertools.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "deerdesign",
+    "deertools",
+    "kosztorys",
+    "katalog",
+    "dostawy",
+    "rendermind",
+    "antigravity",
+    "oauth",
+    "cli"
+  ],
+  "author": "Deer Design AI Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deerdesign/deertools-cli.git"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.js

@@ -0,0 +1,43 @@
+'use strict';
+const c = require('./commands');
+
+function parseArgs(argv) {
+  const pos = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      const key = eq === -1 ? a.slice(2) : a.slice(2, eq);
+      let val = eq === -1 ? undefined : a.slice(eq + 1);
+      if (val === undefined) {
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith('--') && !['write', 'json', 'raw', 'no-open'].includes(key)) { val = next; i++; } else val = true;
+      }
+      if (flags[key] === undefined) flags[key] = val;
+      else flags[key] = [].concat(flags[key], val);
+    } else pos.push(a);
+  }
+  return { pos, flags };
+}
+
+async function main(argv) {
+  const { pos, flags } = parseArgs(argv);
+  const cmd = pos.shift() || 'help';
+  const table = {
+    login: c.cmdLogin, logout: c.cmdLogout, whoami: c.cmdWhoami, docs: c.cmdDocs,
+    endpoints: c.cmdEndpoints, api: c.cmdApi, estimate: c.cmdEstimate, skill: c.cmdSkill,
+  };
+  if (cmd === 'help' || cmd === '--help' || flags.help) { process.stdout.write(c.HELP); return 0; }
+  if (cmd === '--version' || cmd === 'version') { process.stdout.write(`${require('../package.json').version}\n`); return 0; }
+  if (!table[cmd]) { process.stderr.write(`Nieznana komenda „${cmd}”.\n${c.HELP}`); return 2; }
+  try {
+    await table[cmd](pos, flags);
+    return 0;
+  } catch (e) {
+    if (!e.silent) process.stderr.write(`Błąd: ${e.message}\n`);
+    return e.exitCode || 1;
+  }
+}
+
+module.exports = { main, parseArgs };

package/src/commands.js

@@ -0,0 +1,203 @@
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const credentials = require('./credentials');
+const { getProduct, resolveProducts, ALL_IDS } = require('./registry');
+const { login, normalizeScope } = require('./login');
+const { discover, fetchText, apiRequest, explain } = require('./http');
+const { listOperations, parseFrontmatterName } = require('./openapi');
+
+const out = (s = '') => process.stdout.write(`${s}\n`);
+const err = (s = '') => process.stderr.write(`${s}\n`);
+
+function fail(message, exitCode = 1) {
+  const e = new Error(message);
+  e.exitCode = exitCode;
+  throw e;
+}
+
+function needProduct(flags, pos) {
+  if (!pos[0]) fail(`Podaj produkt: ${ALL_IDS.join(' | ')}`, 2);
+  return getProduct(pos[0]);
+}
+
+async function cmdLogin(pos, flags) {
+  const products = resolveProducts(pos[0]);
+  const scope = flags.write ? 'read write' : normalizeScope(flags.scope || 'read');
+  let failures = 0;
+  for (const product of products) {
+    out(`\n=== ${product.name} ===`);
+    try {
+      const entry = await login(product, { scope, port: flags.port ? Number(flags.port) : 0, clientName: flags.name, openBrowser: flags['no-open'] ? null : undefined, log: out });
+      out(`✓ Zalogowano${entry.email ? ` jako ${entry.email}` : ''}. Zakres: ${entry.scope}${entry.expires_at ? `, ważny do ${entry.expires_at.slice(0, 10)}` : ''}.`);
+      out(`  Dokumentacja dla agenta: deertools docs ${product.id}   |   skill: deertools skill install ${product.id}`);
+    } catch (e) {
+      failures += 1;
+      err(`✗ ${product.name}: ${e.message}`);
+    }
+  }
+  if (failures) fail(`Nie udało się zalogować do ${failures} z ${products.length} produktów.`, 1);
+}
+
+async function cmdLogout(pos) {
+  for (const product of resolveProducts(pos[0])) {
+    out(credentials.removeProduct(product.id) ? `✓ Wylogowano z ${product.name} (klucz usunięty lokalnie).` : `– ${product.name}: nie byłeś zalogowany.`);
+  }
+  out('Klucz możesz też unieważnić w produkcie: Ustawienia → Dostęp API.');
+}
+
+async function cmdWhoami(pos, flags) {
+  const rows = [];
+  for (const product of resolveProducts(pos[0])) {
+    const found = credentials.getKey(product);
+    if (!found) { rows.push({ id: product.id, status: 'niezalogowany' }); continue; }
+    const exp = credentials.expiryInfo(found.entry);
+    const row = {
+      id: product.id,
+      status: exp.expired ? 'WYGASŁ' : 'zalogowany',
+      key: credentials.mask(found.key),
+      email: found.entry && found.entry.email,
+      scope: found.entry ? found.entry.scope : '(z zmiennej środowiskowej)',
+      expires: found.entry && found.entry.expires_at ? `${found.entry.expires_at.slice(0, 10)}${exp.daysLeft != null ? ` (${exp.daysLeft} dni)` : ''}` : null,
+      source: found.source,
+    };
+    rows.push(row);
+  }
+  if (flags.json) { out(JSON.stringify(rows, null, 2)); return; }
+  for (const r of rows) {
+    out(`${r.id.padEnd(11)} ${r.status}`);
+    if (r.key) out(`${''.padEnd(11)} klucz ${r.key} · zakres ${r.scope}${r.email ? ` · ${r.email}` : ''}${r.expires ? ` · ważny do ${r.expires}` : ''} · źródło ${r.source}`);
+  }
+}
+
+async function cmdDocs(pos, flags) {
+  const product = needProduct(flags, pos);
+  const what = (pos[1] || 'llms').toLowerCase();
+  if (what === 'llms') {
+    const r = await fetchText(`${product.site}/llms.txt`);
+    if (!r.ok) fail(`Brak dokumentacji dla agenta (${product.site}/llms.txt zwraca ${r.status}). Produkt jeszcze jej nie opublikował.`, 4);
+    out(r.text);
+  } else if (what === 'openapi') {
+    const d = await discover(product);
+    if (!d.openapi) fail(`Brak openapi.json produktu ${product.name}.`, 4);
+    out(JSON.stringify(d.openapi, null, 2));
+  } else if (what === 'skill') {
+    const r = await fetchText(`${product.site}/skill/SKILL.md`);
+    if (!r.ok) fail(`Brak skilla (${product.site}/skill/SKILL.md zwraca ${r.status}).`, 4);
+    out(r.text);
+  } else {
+    fail('Użycie: deertools docs <produkt> [llms|openapi|skill]', 2);
+  }
+}
+
+async function cmdEndpoints(pos, flags) {
+  const product = needProduct(flags, pos);
+  const d = await discover(product);
+  if (!d.openapi) fail(`Produkt ${product.name} nie udostępnia jeszcze openapi.json (sprawdź: deertools docs ${product.id}).`, 4);
+  const ops = listOperations(d.openapi);
+  if (flags.json) { out(JSON.stringify({ apiBase: d.apiBase, operations: ops }, null, 2)); return; }
+  out(`${product.name} — ${d.apiBase}`);
+  for (const o of ops) out(`  ${o.method.padEnd(6)} ${o.path.padEnd(48)} [${o.scope}] ${o.summary}`.trimEnd());
+}
+
+function parseQuery(list) {
+  const q = {};
+  for (const item of [].concat(list || [])) {
+    const i = String(item).indexOf('=');
+    if (i < 1) fail(`Zły parametr zapytania „${item}” — użyj --query klucz=wartość`, 2);
+    q[item.slice(0, i)] = item.slice(i + 1);
+  }
+  return q;
+}
+
+async function cmdApi(pos, flags) {
+  const product = needProduct(flags, pos);
+  const method = String(pos[1] || '').toUpperCase();
+  const p = pos[2];
+  if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method) || !p) fail('Użycie: deertools api <produkt> <GET|POST|PUT|PATCH|DELETE> </ścieżka> [--query k=v] [--data \'{"a":1}\' | --data-file plik.json]', 2);
+  let body;
+  if (flags['data-file']) body = fs.readFileSync(flags['data-file'], 'utf8');
+  else if (flags.data !== undefined && flags.data !== true) body = String(flags.data);
+  const res = await apiRequest(product, { method, path: p, query: parseQuery(flags.query), body });
+  if (!res.ok) {
+    err(explain(res.status, res.json, product) + (res.retryAfter ? ` Spróbuj za ${res.retryAfter} s.` : ''));
+    if (res.text) err(res.text.slice(0, 1000));
+    const e = new Error('');
+    e.exitCode = res.status === 401 ? 3 : 1;
+    e.silent = true;
+    throw e;
+  }
+  out(res.json ? JSON.stringify(res.json, null, flags.raw ? 0 : 2) : res.text);
+}
+
+async function cmdEstimate(pos, flags) {
+  const file = flags.file || pos[0];
+  if (!file) fail('Użycie: deertools estimate --file <rzut.pdf> [--kitchen 6]', 2);
+  if (!fs.existsSync(file)) fail(`Plik nie istnieje: ${file}`, 2);
+  const bytes = fs.readFileSync(file);
+  if (bytes.length > 10 * 1024 * 1024) fail('Plik jest większy niż 10 MB (limit analizy rzutu).', 2);
+  const ext = path.extname(file).toLowerCase().slice(1);
+  const mime = { pdf: 'application/pdf', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp' }[ext];
+  if (!mime) fail('Obsługiwane formaty: PDF, PNG, JPG, WEBP.', 2);
+  const kitchen = flags.kitchen ? Number(String(flags.kitchen).replace(',', '.')) : 6;
+  if (!(kitchen >= 2 && kitchen <= 30)) fail('--kitchen musi być w zakresie 2–30 m².', 2);
+  const product = getProduct('kosztorys');
+  out(`Analizuję ${path.basename(file)} (aneks ${kitchen} m²) — to trwa do ok. minuty…`);
+  const res = await apiRequest(product, {
+    method: 'POST',
+    path: '/estimate-from-floor-plan',
+    body: { file_url: `data:${mime};base64,${bytes.toString('base64')}`, file_name: path.basename(file), file_type: mime, kitchen_open_area_m2: kitchen },
+    base: product.fallbackApiBase,
+  });
+  if (!res.ok) fail(explain(res.status, res.json, product), res.status === 401 ? 3 : 1);
+  if (flags.json) { out(JSON.stringify(res.json, null, 2)); return; }
+  const d = res.json || {};
+  const s = d.summary || {};
+  out(`\nŁączny metraż: ${s.total_area_m2} m² · pokoje: ${s.rooms} · aneks wydzielony: ${s.kitchen_open_area_m2} m²`);
+  for (const r of d.rooms || []) out(`  • ${String(r.name).padEnd(26)} ${r.area_m2} m²`);
+  out('\nPakiety (brutto / netto):');
+  const fmt = (n) => new Intl.NumberFormat('pl-PL', { maximumFractionDigits: 0 }).format(Math.round(n));
+  for (const p of d.packages || []) out(`  ▶ ${String(p.name).padEnd(12)} ${fmt(p.total_gross)} zł / ${fmt(p.total_net)} zł${p.is_lump_sum ? '  (ryczałt < 45 m²)' : ''}`);
+}
+
+async function cmdSkill(pos, flags) {
+  if ((pos[0] || 'install') !== 'install') fail('Użycie: deertools skill install [produkt|all] [--dir <katalog skilli>]', 2);
+  const products = resolveProducts(pos[1]);
+  const dir = flags.dir || path.join(os.homedir(), '.gemini', 'config', 'skills');
+  let installed = 0;
+  for (const product of products) {
+    const r = await fetchText(`${product.site}/skill/SKILL.md`);
+    if (!r.ok) { err(`– ${product.name}: brak skilla (${product.site}/skill/SKILL.md → ${r.status})`); continue; }
+    const name = parseFrontmatterName(r.text) || `deer-${product.id}`;
+    const target = path.join(dir, name);
+    fs.mkdirSync(target, { recursive: true });
+    fs.writeFileSync(path.join(target, 'SKILL.md'), r.text);
+    out(`✓ ${product.name}: ${path.join(target, 'SKILL.md')}`);
+    installed += 1;
+  }
+  if (!installed) fail('Nie zainstalowano żadnego skilla.', 4);
+}
+
+const HELP = `
+DeerTools CLI — logowanie z laptopa i dostęp agenta AI do API produktów DeerTools
+
+Produkty: ${ALL_IDS.join(', ')}
+
+  deertools login <produkt|all> [--write] [--scope "read write"] [--no-open] [--name <komputer>]
+      Loguje przez przeglądarkę i zapisuje klucz API (zakres domyślnie tylko odczyt: read).
+      Klucz działa w Twoim imieniu, nie ma więcej uprawnień niż Ty, wygasa po 90 dniach.
+  deertools logout [produkt|all]            Usuwa lokalny klucz.
+  deertools whoami [produkt|all] [--json]   Status logowania, zakres, ważność.
+  deertools docs <produkt> [llms|openapi|skill]   Dokumentacja dla agenta (publiczna).
+  deertools endpoints <produkt> [--json]    Lista endpointów z zakresem (z openapi.json).
+  deertools api <produkt> <METODA> </ścieżka> [--query k=v] [--data JSON | --data-file plik]
+      Wywołuje API produktu z Twoim kluczem (tylko adres produktu, klucz nie trafia nigdzie indziej).
+  deertools estimate --file <rzut.pdf> [--kitchen 6] [--json]   Wycena rzutu (Kosztorys).
+  deertools skill install [produkt|all] [--dir <katalog>]   Instaluje skill agenta z produktu.
+
+Zmienne środowiskowe (CI/agenty): DEERTOOLS_<PRODUKT>_KEY, DEERTOOLS_HOME.
+Kody wyjścia: 0 ok · 1 błąd żądania · 2 błędne użycie · 3 brak/wygasłe logowanie · 4 brak dokumentacji lub adresu API.
+`;
+
+module.exports = { cmdLogin, cmdLogout, cmdWhoami, cmdDocs, cmdEndpoints, cmdApi, cmdEstimate, cmdSkill, HELP, parseQuery };

package/src/credentials.js

@@ -0,0 +1,68 @@
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function homeDir() {
+  return process.env.DEERTOOLS_HOME || path.join(os.homedir(), '.deertools');
+}
+function credentialsFile() {
+  return path.join(homeDir(), 'credentials.json');
+}
+
+function readAll() {
+  try {
+    const data = JSON.parse(fs.readFileSync(credentialsFile(), 'utf8'));
+    if (data && data.version === 2 && data.products && typeof data.products === 'object') return data;
+  } catch (_) { /* brak pliku lub stary format */ }
+  return { version: 2, products: {} };
+}
+
+function writeAll(data) {
+  const dir = homeDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try { fs.chmodSync(dir, 0o700); } catch (_) { /* Windows */ }
+  const file = credentialsFile();
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  try { fs.chmodSync(file, 0o600); } catch (_) { /* Windows */ }
+}
+
+function saveProduct(productId, entry) {
+  const data = readAll();
+  data.products[productId] = entry;
+  writeAll(data);
+}
+
+function removeProduct(productId) {
+  const data = readAll();
+  const existed = Boolean(data.products[productId]);
+  delete data.products[productId];
+  writeAll(data);
+  return existed;
+}
+
+/** Klucz z zmiennej środowiskowej ma pierwszeństwo (CI, agenty); zwraca też źródło. */
+function getKey(product) {
+  const envName = `DEERTOOLS_${product.id.toUpperCase()}_KEY`;
+  const fromEnv = process.env[envName] || (process.env.DEER_API_KEY && process.env.DEER_API_KEY.startsWith(product.keyPrefix) ? process.env.DEER_API_KEY : '');
+  if (fromEnv) return { key: fromEnv, source: `env:${envName}`, entry: null };
+  const entry = readAll().products[product.id];
+  if (!entry || !entry.key) return null;
+  return { key: entry.key, source: 'file', entry };
+}
+
+function expiryInfo(entry) {
+  if (!entry || !entry.expires_at) return { expired: false, daysLeft: null };
+  const ms = Date.parse(entry.expires_at) - Date.now();
+  if (Number.isNaN(ms)) return { expired: false, daysLeft: null };
+  return { expired: ms <= 0, daysLeft: Math.floor(ms / 86400000) };
+}
+
+function mask(key) {
+  if (!key) return '';
+  return `${key.slice(0, 12)}…${key.slice(-4)}`;
+}
+
+module.exports = { homeDir, credentialsFile, readAll, saveProduct, removeProduct, getKey, expiryInfo, mask };

package/src/http.js

@@ -0,0 +1,97 @@
+'use strict';
+const credentials = require('./credentials');
+
+const REQUEST_TIMEOUT_MS = 120000;
+
+async function fetchText(url, { headers = {}, timeoutMs = 30000 } = {}) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { headers: { 'User-Agent': 'deertools-cli', ...headers }, signal: ctrl.signal });
+    return { status: res.status, ok: res.ok, headers: res.headers, text: await res.text() };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+/** Wykrywa openapi.json z publicznego llms.txt produktu i czyta z niego adres bazowy API. */
+async function discover(product) {
+  const result = { llmsTxt: null, openapiUrl: null, openapi: null, apiBase: product.fallbackApiBase };
+  try {
+    const llms = await fetchText(`${product.site}/llms.txt`);
+    if (llms.ok) {
+      result.llmsTxt = llms.text;
+      const m = llms.text.match(/https?:\/\/[^\s)>"'`]+openapi\.json/i);
+      if (m) result.openapiUrl = m[0];
+    }
+  } catch (_) { /* brak sieci — zostaje fallback */ }
+  if (result.openapiUrl) {
+    try {
+      const spec = await fetchText(result.openapiUrl);
+      if (spec.ok) {
+        result.openapi = JSON.parse(spec.text);
+        const server = result.openapi.servers && result.openapi.servers[0] && result.openapi.servers[0].url;
+        if (server) result.apiBase = server.replace(/\/+$/, '');
+      }
+    } catch (_) { /* uszkodzony openapi — zostaje fallback */ }
+  }
+  return result;
+}
+
+function ensureRelativePath(p) {
+  if (typeof p !== 'string' || !p.startsWith('/') || p.startsWith('//') || /^\/[a-z][a-z0-9+.-]*:/i.test(p) || p.includes('..')) {
+    const err = new Error('Podaj ścieżkę względną zaczynającą się od „/”, np. /products. CLI nie wysyła klucza pod obce adresy.');
+    err.exitCode = 2;
+    throw err;
+  }
+  return p;
+}
+
+function explain(status, json, product) {
+  const msg = json && json.error ? `: ${json.error}` : '';
+  if (status === 401) return `401 Brak dostępu${msg}. Zaloguj się: deertools login ${product.id}`;
+  if (status === 403) return `403 Za mały zakres klucza${msg}. Zaloguj się z zapisem: deertools login ${product.id} --write`;
+  if (status === 429) return `429 Przekroczono limit żądań${msg}.`;
+  return `${status}${msg}`;
+}
+
+async function apiRequest(product, { method = 'GET', path, query, body, base }) {
+  const found = credentials.getKey(product);
+  if (!found) {
+    const err = new Error(`Nie jesteś zalogowany do produktu ${product.name}. Użyj: deertools login ${product.id}`);
+    err.exitCode = 3;
+    throw err;
+  }
+  const { expired } = credentials.expiryInfo(found.entry);
+  if (expired) {
+    const err = new Error(`Klucz do produktu ${product.name} wygasł. Zaloguj się ponownie: deertools login ${product.id}`);
+    err.exitCode = 3;
+    throw err;
+  }
+  ensureRelativePath(path);
+  const apiBase = base || (await discover(product)).apiBase;
+  if (!apiBase) {
+    const err = new Error(`Nie znam adresu API produktu ${product.name} (brak openapi.json w ${product.site}/llms.txt).`);
+    err.exitCode = 4;
+    throw err;
+  }
+  const url = new URL(apiBase + path);
+  for (const [k, v] of Object.entries(query || {})) url.searchParams.set(k, v);
+  const headers = { 'x-api-key': found.key, Accept: 'application/json' };
+  let payload;
+  if (body !== undefined) { headers['Content-Type'] = 'application/json'; payload = typeof body === 'string' ? body : JSON.stringify(body); }
+
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { method, headers, body: payload, signal: ctrl.signal });
+    const text = await res.text();
+    let json = null;
+    try { json = JSON.parse(text); } catch (_) { /* nie-JSON */ }
+    return { status: res.status, ok: res.ok, json, text, retryAfter: res.headers.get('retry-after') };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+module.exports = { fetchText, discover, ensureRelativePath, explain, apiRequest };

package/src/login.js

@@ -0,0 +1,189 @@
+'use strict';
+const http = require('http');
+const crypto = require('crypto');
+const os = require('os');
+const { exec } = require('child_process');
+const credentials = require('./credentials');
+
+const CLIENT_ID = 'deertools-cli';
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+const VALID_SCOPES = ['read', 'write'];
+
+const b64url = (buf) => Buffer.from(buf).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+
+/** PKCE (RFC 7636): verifier 43 znaki, challenge = BASE64URL(SHA256(verifier)). */
+function createPkce(verifier = b64url(crypto.randomBytes(32))) {
+  return { verifier, challenge: b64url(crypto.createHash('sha256').update(verifier).digest()) };
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+
+function normalizeScope(input) {
+  const list = String(input || 'read').split(/[\s,]+/).filter(Boolean);
+  const bad = list.filter((s) => !VALID_SCOPES.includes(s));
+  if (bad.length) {
+    const err = new Error(`Nieznany zakres: ${bad.join(', ')}. Dozwolone: ${VALID_SCOPES.join(', ')}.`);
+    err.exitCode = 2;
+    throw err;
+  }
+  const set = new Set(list.length ? list : ['read']);
+  if (set.has('write')) set.add('read'); // zapis zakłada odczyt
+  return VALID_SCOPES.filter((s) => set.has(s)).join(' ');
+}
+
+function buildAuthorizeUrl(authorizationEndpoint, { redirectUri, state, scope, clientName, challenge }) {
+  const u = new URL(authorizationEndpoint);
+  u.searchParams.set('client_id', CLIENT_ID);
+  u.searchParams.set('redirect_uri', redirectUri);
+  u.searchParams.set('response_type', 'code');
+  u.searchParams.set('code_challenge', challenge);
+  u.searchParams.set('code_challenge_method', 'S256');
+  u.searchParams.set('state', state);
+  u.searchParams.set('scope', scope);
+  u.searchParams.set('client_name', String(clientName).slice(0, 60));
+  return u.toString();
+}
+
+function timingSafeEqualStr(a, b) {
+  const x = Buffer.from(String(a));
+  const y = Buffer.from(String(b));
+  return x.length === y.length && crypto.timingSafeEqual(x, y);
+}
+
+/** Czysta funkcja: ocenia parametry powrotu z przeglądarki (oczekujemy wyłącznie jednorazowego kodu). */
+function evaluateCallback(query, { expectedState }) {
+  if (!query.state || !timingSafeEqualStr(query.state, expectedState)) {
+    return { ok: false, status: 400, message: 'Nieprawidłowy parametr state — logowanie przerwano ze względów bezpieczeństwa.' };
+  }
+  if (query.error) {
+    return { ok: false, status: 400, message: query.error === 'access_denied' ? 'Odmówiono dostępu w przeglądarce.' : `Błąd logowania: ${query.error}` };
+  }
+  if (!query.code || query.code.length < 16) {
+    return { ok: false, status: 400, message: 'Produkt nie zwrócił kodu autoryzacyjnego.' };
+  }
+  return { ok: true, status: 200, code: query.code };
+}
+
+/** Wymiana kodu na klucz: bezpośrednie zapytanie CLI -> serwer (klucz nigdy nie przechodzi przez przeglądarkę). */
+async function exchangeCode(product, tokenEndpoint, { code, verifier, redirectUri, fetchImpl = fetch }) {
+  let res;
+  try {
+    res = await fetchImpl(tokenEndpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+      body: JSON.stringify({ grant_type: 'authorization_code', code, code_verifier: verifier, redirect_uri: redirectUri, client_id: CLIENT_ID }),
+    });
+  } catch (e) {
+    throw new Error(`Nie udało się połączyć z serwerem produktu ${product.name}: ${e.message}`);
+  }
+  let json = null;
+  try { json = await res.json(); } catch (_) { /* nie-JSON */ }
+  if (!res.ok || !json || !json.access_token) {
+    throw new Error(`Wymiana kodu na klucz nie powiodła się (${res.status}${json && json.error ? `: ${json.error}` : ''}). Spróbuj zalogować się ponownie.`);
+  }
+  if (!String(json.access_token).startsWith(product.keyPrefix)) {
+    throw new Error(`Produkt zwrócił nieoczekiwany klucz (oczekiwano prefiksu ${product.keyPrefix}…).`);
+  }
+  return {
+    key: json.access_token,
+    email: json.email || null,
+    scope: json.scope || 'read',
+    expires_at: json.expires_at || null,
+    logged_at: new Date().toISOString(),
+  };
+}
+
+/** Adresy OAuth z metadanych serwera (RFC 8414) opublikowanych przez produkt. */
+async function discoverOAuth(product, fetchImpl = fetch) {
+  const url = `${product.site}/.well-known/oauth-authorization-server`;
+  let res;
+  try { res = await fetchImpl(url, { headers: { Accept: 'application/json', 'User-Agent': 'deertools-cli' } }); } catch (e) {
+    throw new Error(`Nie można pobrać metadanych OAuth produktu ${product.name} (${url}): ${e.message}`);
+  }
+  if (!res.ok) throw new Error(`Produkt ${product.name} nie opublikował jeszcze metadanych OAuth (${url} → ${res.status}). Logowanie z CLI nie jest tam dostępne.`);
+  let meta;
+  try { meta = JSON.parse(await res.text()); } catch (_) { throw new Error(`Metadane OAuth produktu ${product.name} nie są poprawnym JSON-em.`); }
+  if (!meta.authorization_endpoint || !meta.token_endpoint) throw new Error(`Metadane OAuth produktu ${product.name} nie zawierają authorization_endpoint / token_endpoint.`);
+  if (!(meta.code_challenge_methods_supported || []).includes('S256')) throw new Error(`Produkt ${product.name} nie obsługuje PKCE (S256) — odmawiam logowania.`);
+  for (const k of ['authorization_endpoint', 'token_endpoint']) {
+    if (new URL(meta[k]).protocol !== 'https:') throw new Error(`Adres ${k} produktu ${product.name} nie jest HTTPS.`);
+  }
+  return meta;
+}
+
+function page(title, body, ok) {
+  const color = ok ? '#10b981' : '#ef4444';
+  return `<!doctype html><html lang="pl"><meta charset="utf-8"><title>DeerTools CLI</title><body style="font-family:-apple-system,Segoe UI,Roboto,sans-serif;background:#09090b;color:#f4f4f5;text-align:center;padding:60px 20px"><div style="max-width:480px;margin:0 auto;background:#18181b;border:1px solid #27272a;border-radius:16px;padding:40px"><h1 style="color:${color};font-size:22px">${escapeHtml(title)}</h1><p style="color:#a1a1aa;line-height:1.5">${escapeHtml(body)}</p></div></body></html>`;
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === 'win32' ? `start "" "${url}"` : process.platform === 'darwin' ? `open "${url}"` : `xdg-open "${url}"`;
+  exec(cmd, () => { /* gdy się nie uda, użytkownik ma adres wypisany w terminalu */ });
+}
+
+/**
+ * Logowanie OAuth 2.1 dla aplikacji natywnej (RFC 8252): kod autoryzacyjny + PKCE, powrót na 127.0.0.1 (losowy port).
+ * opts.metadata pozwala podać adresy bez pobierania (testy). Zwraca wpis poświadczeń zapisany na dysku.
+ */
+async function login(product, opts = {}) {
+  const scope = normalizeScope(opts.scope);
+  const meta = opts.metadata || (await discoverOAuth(product, opts.fetchImpl));
+  const state = b64url(crypto.randomBytes(24));
+  const pkce = createPkce();
+  const clientName = opts.clientName || os.hostname();
+  const timeoutMs = opts.timeoutMs || LOGIN_TIMEOUT_MS;
+  const open = opts.openBrowser === undefined ? openBrowser : opts.openBrowser;
+  const log = opts.log || (() => {});
+
+  return new Promise((resolve, reject) => {
+    let finished = false;
+    let redirectUri = null;
+
+    const server = http.createServer(async (req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      if (url.pathname !== '/callback') { res.writeHead(404); res.end(); return; }
+      const result = evaluateCallback(Object.fromEntries(url.searchParams.entries()), { expectedState: state });
+      const headers = { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' };
+      if (!result.ok) {
+        res.writeHead(result.status, headers);
+        res.end(page('Nie udało się zalogować', result.message, false));
+        done(new Error(result.message));
+        return;
+      }
+      try {
+        const entry = await exchangeCode(product, meta.token_endpoint, { code: result.code, verifier: pkce.verifier, redirectUri, fetchImpl: opts.fetchImpl });
+        credentials.saveProduct(product.id, entry);
+        res.writeHead(200, headers);
+        res.end(page('Zalogowano', `Klucz do produktu ${product.name} został zapisany w terminalu. Możesz zamknąć to okno.`, true));
+        done(null, entry);
+      } catch (e) {
+        res.writeHead(502, headers);
+        res.end(page('Nie udało się zalogować', e.message, false));
+        done(e);
+      }
+    });
+
+    const timer = setTimeout(() => done(new Error(`Upłynął czas na zalogowanie (${Math.round(timeoutMs / 60000) || '<1'} min). Spróbuj ponownie.`)), timeoutMs);
+
+    function done(err, entry) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      server.close();
+      if (err) reject(err); else resolve(entry);
+    }
+
+    server.on('error', (e) => done(e));
+    server.listen(opts.port || 0, '127.0.0.1', () => {
+      redirectUri = `http://127.0.0.1:${server.address().port}/callback`;
+      const url = buildAuthorizeUrl(meta.authorization_endpoint, { redirectUri, state, scope, clientName, challenge: pkce.challenge });
+      log(`Zakres: ${scope}. Otwieram przeglądarkę — zaloguj się w produkcie ${product.name} i kliknij „Zezwól na dostęp”.`);
+      log(`Jeśli przeglądarka się nie otworzy, wejdź na:\n${url}\n`);
+      if (open) open(url);
+    });
+  });
+}
+
+module.exports = { CLIENT_ID, createPkce, normalizeScope, buildAuthorizeUrl, evaluateCallback, exchangeCode, discoverOAuth, login };

package/src/openapi.js

@@ -0,0 +1,27 @@
+'use strict';
+const METHODS = ['get', 'put', 'post', 'patch', 'delete', 'head'];
+
+function scopeFor(method, op) {
+  if (op && op['x-required-scope']) return op['x-required-scope'];
+  return ['get', 'head', 'options'].includes(method) ? 'read' : 'write';
+}
+
+function listOperations(spec) {
+  const out = [];
+  for (const [p, item] of Object.entries((spec && spec.paths) || {})) {
+    for (const m of METHODS) {
+      if (!item[m]) continue;
+      out.push({ method: m.toUpperCase(), path: p, scope: scopeFor(m, item[m]), summary: item[m].summary || item[m].description || '' });
+    }
+  }
+  return out.sort((a, b) => (a.path === b.path ? a.method.localeCompare(b.method) : a.path.localeCompare(b.path)));
+}
+
+function parseFrontmatterName(text) {
+  const m = String(text).match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  const n = m[1].match(/^name:\s*["']?([a-zA-Z0-9._-]+)["']?\s*$/m);
+  return n ? n[1] : null;
+}
+
+module.exports = { listOperations, scopeFor, parseFrontmatterName };

package/src/registry.js

@@ -0,0 +1,62 @@
+'use strict';
+/**
+ * Rejestr produktów DeerTools. Każdy produkt ma własny adres autoryzacji, własny prefiks klucza
+ * i własne API. Adres bazowy API i lista endpointów pochodzą z publicznego openapi.json produktu
+ * (wykrywanego z llms.txt), więc CLI nie zna endpointów na sztywno.
+ */
+const PRODUCTS = {
+  kosztorys: {
+    name: 'Kosztorys',
+    site: 'https://connect.deerdesign.pl/kosztorys',
+    authorizeUrl: 'https://connect.deerdesign.pl/kosztorys/oauth/authorize',
+    keyPrefix: 'deer_kosztorys_live_',
+    fallbackApiBase: 'https://vlemuxlubrowuuxpgllk.supabase.co/functions/v1',
+  },
+  katalog: {
+    name: 'Katalog Connect',
+    site: 'https://connect.deerdesign.pl/katalog',
+    authorizeUrl: 'https://connect.deerdesign.pl/katalog/oauth/authorize',
+    keyPrefix: 'deer_catalog_live_',
+    fallbackApiBase: null,
+  },
+  dostawy: {
+    name: 'Dostawy',
+    site: 'https://ship.deergroup.pl',
+    authorizeUrl: 'https://ship.deergroup.pl/oauth/authorize',
+    keyPrefix: 'deer_dostawy_live_',
+    fallbackApiBase: null,
+  },
+  supplier: {
+    name: 'Supplier Hub',
+    site: 'https://supplier.deergroup.pl',
+    authorizeUrl: 'https://supplier.deergroup.pl/oauth/authorize',
+    keyPrefix: 'deer_supplier_live_',
+    fallbackApiBase: null,
+  },
+  rendermind: {
+    name: 'RenderMind',
+    site: 'https://rendermind.deergroup.pl',
+    authorizeUrl: 'https://rendermind.deergroup.pl/oauth/authorize',
+    keyPrefix: 'deer_rendermind_live_',
+    fallbackApiBase: null,
+  },
+};
+
+const ALL_IDS = Object.keys(PRODUCTS);
+
+function getProduct(id) {
+  const key = String(id || '').toLowerCase();
+  if (!PRODUCTS[key]) {
+    const err = new Error(`Nieznany produkt „${id}”. Dostępne: ${ALL_IDS.join(', ')}.`);
+    err.exitCode = 2;
+    throw err;
+  }
+  return { id: key, ...PRODUCTS[key] };
+}
+
+function resolveProducts(arg) {
+  if (!arg || arg === 'all') return ALL_IDS.map(getProduct);
+  return String(arg).split(',').map((s) => getProduct(s.trim()));
+}
+
+module.exports = { PRODUCTS, ALL_IDS, getProduct, resolveProducts };