empuno 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lutfios LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# empuno 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.
+[empuno](https://empuno.com) İK platformunun komut satırı. Yönetim panelinde
+yapabildiğiniz **her işlemi** — izin onayı, bordro dönemi, vardiya planı,
+zimmet, PDKS, masraf, işe alım, evrak — yapay zekâ ajanlarınıza ve
+otomasyonlarınıza açar.
+
+> Command-line client for the empuno HR platform (Turkey). Every admin-panel
+> action is a command; output is always JSON. Docs: https://empuno.com/api-docs/agent
+
+## Kurulum
+
+```bash
+npm i -g empuno        # Node.js 18+
+# ya da kurmadan:
+npx empuno whoami
+```
+
+## Giriş
+
+empuno panelinde **Firma Ayarları → API & Ajan → Yeni Anahtar → Tür: Ajan**
+ile bir anahtar oluşturun ve modül yetkilerini seçin. Sonra:
+
+```bash
+echo "emp_live_…" | empuno login --key-stdin    # anahtar kabuk geçmişine düşmez
+empuno whoami
+```
+
+Ya da ortam değişkeniyle: `EMPUNO_API_KEY=emp_live_… empuno whoami`.
+
+## Kullanım
+
+```bash
+empuno commands izin                         # komut ara (Türkçe başlıklarla)
+empuno describe leave-requests.reject        # yol parametreleri, alanlar, gereken yetki
+empuno leave-requests.index --status pending
+empuno leave-requests.approve 123
+empuno leave-requests.reject 124 --rejection_reason "Yoğun dönem"
+empuno employees.documents.store 45 --document_type is_sozlesmesi --file file=./sozlesme.pdf
+empuno leave-reports.download 12 --output ./rapor.pdf
+empuno call POST /manager/leave-requests/123/approve    # ham çağrı
+empuno api leaves --status approved                     # salt-okuma Company API
+```
+
+Komutlar sunucudaki katalogdan okunur: panele yeni bir özellik geldiğinde
+komutu CLI güncellemesi olmadan görünür.
+
+- Yol parametreleri sırayla verilir; `--alan değer` bayrakları okuma
+  komutunda sorgu parametresi, yazma komutunda JSON gövdesi olur.
+- `--alan @dosya` ya da `--file alan=dosya` → multipart yükleme.
+- `--json '{…}'` / `--json @govde.json`, `--dry-run`, `--output yol`,
+  `--profile ad` (birden çok firma).
+
+## Çıktı sözleşmesi
+
+- stdout **her zaman JSON** (TTY'de girintili).
+- Okuma: `{"ok": true, "page": "…", "data": {…}}`
+- Yazma: `{"ok": true, "message": "…", "redirect": {"command": "…", "params": {…}}}`
+- Hata: `{"ok": false, "error": "…", "message": "…", "errors": {…}}`
+- Çıkış kodu: `0` başarı, `1` API hatası, `2` kullanım hatası, `3` ağ hatası.
+
+## Ajanınıza verin
+
+```text
+empuno İK sistemine `empuno` CLI ile erişimin var. Önce `empuno commands <anahtar kelime>`
+ile komutu bul, `empuno describe <komut>` ile parametrelerini öğren, sonra çalıştır.
+422 → `errors` alanlarını düzeltip tekrar dene; 403 → yetki yetmiyor, kullanıcıya
+`required_permission`ı söyle. Geri alınamaz işlemlerden önce kullanıcıdan onay al.
+```
+
+## Güvenlik
+
+Ajan anahtarı, onu oluşturan kişinin adına ve seçilen modül yetkileriyle
+çalışır; etkin yetki hiçbir zaman o kişinin yetkisini aşamaz. Her yazma işlemi
+panelde anahtarın işlem günlüğünde görünür. Anahtar panelden anında iptal
+edilir. Yerel yapılandırma `~/.config/empuno/config.json` (0600) dosyasındadır.
+
+Belgeler: https://empuno.com/api-docs/agent · düz metin: https://empuno.com/api-docs/agent.txt

package/empuno.mjs

@@ -0,0 +1,774 @@
+#!/usr/bin/env node
+// empuno CLI — ajanlar (ve insanlar) için empuno komut satırı.
+//
+// Tek dosya, bağımlılıksız, Node >= 18. Komutlar sunucudaki katalogdan
+// (GET /api/company/v1/catalog) okunur: panelde olan her yönetim işlemi
+// burada da vardır; yeni özellikler CLI güncellemesi gerektirmeden görünür.
+//
+//   Kurulum : npm i -g empuno        (ya da kurmadan: npx empuno …)
+//             curl -fsSL https://empuno.com/cli/empuno.mjs -o ~/.local/bin/empuno && chmod +x ~/.local/bin/empuno
+//   Giriş   : empuno login            (anahtar: Firma Ayarları → API → Ajan anahtarı)
+//   Keşif   : empuno commands izin    → empuno describe leave-requests.approve
+//   Çalıştır: empuno leave-requests.approve 123
+//
+// Çıktı sözleşmesi: stdout HER ZAMAN JSON (TTY değilse tek satır, TTY'de
+// girintili; --text ile insan okunur liste). Çıkış kodu: 0 başarı, 1 API
+// hatası (4xx/5xx — gövde yine stdout'ta JSON), 2 kullanım hatası, 3 ağ hatası.
+// Belgeler: https://empuno.com/api-docs/agent
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const VERSION = '1.0.1'; // EMPUNO_CLI_VERSION — config/agent_api.php cli_version + package.json ile aynı tutulur
+const NPM_PACKAGE = 'empuno';
+const DEFAULT_URL = 'https://empuno.com';
+const CATALOG_TTL_MS = 10 * 60 * 1000;
+
+// ─── yardımcılar ───────────────────────────────────────────────────────────
+
+const isTTY = process.stdout.isTTY === true;
+let outputMode = null; // 'json' | 'text' | null(otomatik)
+let prettyFlag = null;
+
+class UsageError extends Error {}
+
+function print(value) {
+    const pretty = prettyFlag ?? isTTY;
+    process.stdout.write(JSON.stringify(value, null, pretty ? 2 : 0) + '\n');
+}
+
+function wantsText() {
+    if (outputMode) return outputMode === 'text';
+    return isTTY;
+}
+
+function warn(msg) {
+    process.stderr.write(`empuno: ${msg}\n`);
+}
+
+function configDir() {
+    const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+    return path.join(base, 'empuno');
+}
+
+function cacheDir() {
+    const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+    return path.join(base, 'empuno');
+}
+
+function configPath() {
+    return process.env.EMPUNO_CONFIG || path.join(configDir(), 'config.json');
+}
+
+function readConfig() {
+    try {
+        return JSON.parse(fs.readFileSync(configPath(), 'utf8'));
+    } catch {
+        return { default: 'default', profiles: {} };
+    }
+}
+
+function writeConfig(cfg) {
+    const file = configPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+
+function maskKey(key) {
+    return key ? `${key.slice(0, 13)}…${key.slice(-4)}` : null;
+}
+
+/** Etkin profil: --key/--url bayrağı > EMPUNO_API_KEY/EMPUNO_URL > config dosyası. */
+function resolveAuth(flags) {
+    const cfg = readConfig();
+    const profileName = flags.profile || process.env.EMPUNO_PROFILE || cfg.default || 'default';
+    const profile = cfg.profiles?.[profileName] || {};
+    const key = flags.key || process.env.EMPUNO_API_KEY || profile.key || null;
+    const url = (flags.url || process.env.EMPUNO_URL || profile.url || DEFAULT_URL).replace(/\/+$/, '');
+    return { key, url, profileName };
+}
+
+function requireKey(auth) {
+    if (!auth.key) {
+        throw new UsageError('API anahtarı yok. `empuno login` çalıştırın ya da EMPUNO_API_KEY ortam değişkenini ayarlayın. Anahtar: empuno paneli → Firma Ayarları → API → "Ajan" türünde anahtar.');
+    }
+    if (!auth.key.startsWith('emp_live_')) {
+        throw new UsageError('Geçersiz anahtar biçimi (emp_live_ ile başlamalı).');
+    }
+}
+
+// ─── argüman ayrıştırma ────────────────────────────────────────────────────
+
+const GLOBAL_FLAGS = new Set(['key', 'url', 'profile', 'pretty', 'compact', 'text', 'json-out', 'dry-run', 'output', 'refresh', 'all', 'full', 'module', 'writes', 'reads', 'help', 'key-stdin', 'query', 'json', 'file', 'quiet']);
+const BOOLEAN_FLAGS = new Set(['pretty', 'compact', 'text', 'json-out', 'dry-run', 'refresh', 'all', 'full', 'writes', 'reads', 'help', 'key-stdin', 'quiet']);
+
+/**
+ * argv → { positional: [], flags: {global}, fields: [[name, rawValue]] }.
+ * `--ad değer`, `--ad=değer`, tekrar eden bayrak → dizi, `--` sonrası hep positional.
+ */
+function parseArgs(argv) {
+    const positional = [];
+    const flags = { query: [], file: [] };
+    const fields = [];
+    let i = 0;
+    let rest = false;
+
+    while (i < argv.length) {
+        const arg = argv[i];
+        if (rest || !arg.startsWith('--') || arg === '--') {
+            if (arg === '--' && !rest) { rest = true; i++; continue; }
+            positional.push(arg);
+            i++;
+            continue;
+        }
+
+        let name = arg.slice(2);
+        let value;
+        const eq = name.indexOf('=');
+        if (eq !== -1) {
+            value = name.slice(eq + 1);
+            name = name.slice(0, eq);
+        }
+
+        if (GLOBAL_FLAGS.has(name) && BOOLEAN_FLAGS.has(name)) {
+            flags[name] = value === undefined ? true : !['0', 'false', 'no'].includes(value);
+            i++;
+            continue;
+        }
+
+        if (value === undefined) {
+            const next = argv[i + 1];
+            if (next === undefined || (next.startsWith('--') && next.length > 2)) {
+                value = 'true'; // değersiz alan bayrağı → true
+                i++;
+            } else {
+                value = next;
+                i += 2;
+            }
+        } else {
+            i++;
+        }
+
+        if (name === 'query' || name === 'file') {
+            flags[name].push(value);
+        } else if (GLOBAL_FLAGS.has(name)) {
+            flags[name] = value;
+        } else {
+            fields.push([name, value]);
+        }
+    }
+
+    if (flags.text) outputMode = 'text';
+    if (flags['json-out']) outputMode = 'json';
+    if (flags.pretty) prettyFlag = true;
+    if (flags.compact) prettyFlag = false;
+
+    return { positional, flags, fields };
+}
+
+/** "true"/"12"/"[1,2]" → JSON değeri; baştaki sıfır ("0532…") ve diğerleri string kalır. */
+function coerce(raw) {
+    if (typeof raw !== 'string') return raw;
+    if (raw === 'true') return true;
+    if (raw === 'false') return false;
+    if (raw === 'null') return null;
+    if (/^-?(0|[1-9]\d{0,14})(\.\d+)?$/.test(raw)) return Number(raw);
+    if ((raw.startsWith('{') && raw.endsWith('}')) || (raw.startsWith('[') && raw.endsWith(']'))) {
+        try { return JSON.parse(raw); } catch { /* düz metin */ }
+    }
+    return raw;
+}
+
+/** a.b.0.c=x → {a:{b:[{c:x}]}} ; tekrar eden anahtar → dizi. */
+function setDeep(target, dotted, value) {
+    const parts = dotted.replace(/\[\]$/, '').replace(/\[(\w*)\]/g, '.$1').split('.').filter((p) => p !== '');
+    let node = target;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const key = parts[i];
+        const nextIsIndex = /^\d+$/.test(parts[i + 1]);
+        if (node[key] === undefined || typeof node[key] !== 'object') node[key] = nextIsIndex ? [] : {};
+        node = node[key];
+    }
+    const last = parts[parts.length - 1];
+    const forceArray = dotted.endsWith('[]');
+    if (node[last] !== undefined && !Array.isArray(value)) {
+        node[last] = Array.isArray(node[last]) ? [...node[last], value] : [node[last], value];
+    } else {
+        node[last] = forceArray && !Array.isArray(value) ? [value] : value;
+    }
+}
+
+function readJsonArg(raw) {
+    const text = raw.startsWith('@') ? fs.readFileSync(raw.slice(1), 'utf8') : raw;
+    try {
+        return JSON.parse(text);
+    } catch (e) {
+        throw new UsageError(`--json geçerli JSON değil: ${e.message}`);
+    }
+}
+
+// ─── HTTP ──────────────────────────────────────────────────────────────────
+
+let versionWarned = false;
+
+function checkServerVersion(res) {
+    const latest = res.headers.get('x-empuno-cli-version');
+    if (!versionWarned && latest && compareVersions(latest, VERSION) > 0) {
+        versionWarned = true;
+        warn(`yeni CLI sürümü var (${VERSION} → ${latest}): ${installedViaNpm() ? `npm i -g ${NPM_PACKAGE}@latest` : 'empuno update'}`);
+    }
+}
+
+function compareVersions(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+    }
+    return 0;
+}
+
+async function request(auth, method, urlPath, { query = {}, body = null, files = [], output = null, dryRun = false } = {}) {
+    const url = new URL(urlPath.startsWith('http') ? urlPath : auth.url + urlPath);
+    for (const [k, v] of Object.entries(query)) {
+        if (Array.isArray(v)) v.forEach((item) => url.searchParams.append(`${k}[]`, String(item)));
+        else if (v !== undefined && v !== null) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
+    }
+
+    const headers = {
+        Authorization: `Bearer ${auth.key}`,
+        Accept: 'application/json',
+        'User-Agent': `empuno-cli/${VERSION} node/${process.versions.node}`,
+        'X-Empuno-Cli': VERSION,
+    };
+
+    let sendMethod = method;
+    let payload;
+
+    if (files.length > 0) {
+        const form = new FormData();
+        appendForm(form, body || {});
+        for (const { field, file } of files) {
+            const buffer = fs.readFileSync(file);
+            form.append(field, new Blob([buffer]), path.basename(file));
+        }
+        // PHP, PUT/PATCH multipart gövdesini ayrıştırmaz → POST + _method.
+        if (!['GET', 'POST'].includes(method)) {
+            form.append('_method', method);
+            sendMethod = 'POST';
+        }
+        payload = form;
+    } else if (body && Object.keys(body).length > 0 && method !== 'GET') {
+        headers['Content-Type'] = 'application/json';
+        payload = JSON.stringify(body);
+    }
+
+    if (dryRun) {
+        return {
+            dryRun: true,
+            result: {
+                method: sendMethod,
+                url: url.toString(),
+                headers: { ...headers, Authorization: `Bearer ${maskKey(auth.key)}` },
+                body: files.length ? { fields: body, files } : body,
+            },
+        };
+    }
+
+    let res;
+    try {
+        res = await fetch(url, { method: sendMethod, headers, body: payload, redirect: 'manual' });
+    } catch (e) {
+        const err = new Error(`ağ hatası: ${e.cause?.message || e.message}`);
+        err.exitCode = 3;
+        throw err;
+    }
+
+    checkServerVersion(res);
+
+    const type = res.headers.get('content-type') || '';
+    let result;
+
+    if (type.includes('application/json')) {
+        const text = await res.text();
+        try { result = JSON.parse(text); } catch { result = { ok: false, error: 'invalid_json', body: text.slice(0, 2000) }; }
+    } else if (res.status >= 300 && res.status < 400) {
+        result = { ok: false, error: 'unexpected_redirect', status: res.status, location: res.headers.get('location') };
+    } else if (res.ok && (output || isDownload(res, type))) {
+        result = await saveDownload(res, type, output);
+    } else {
+        const text = await res.text();
+        result = { ok: res.ok, status: res.status, content_type: type, body: text.slice(0, 4000) };
+    }
+
+    return { status: res.status, ok: res.ok, result };
+}
+
+function appendForm(form, value, prefix = '') {
+    if (value === null || value === undefined) return;
+    if (Array.isArray(value)) {
+        value.forEach((item, i) => appendForm(form, item, `${prefix}[${i}]`));
+    } else if (typeof value === 'object') {
+        for (const [k, v] of Object.entries(value)) appendForm(form, v, prefix ? `${prefix}[${k}]` : k);
+    } else {
+        form.append(prefix, typeof value === 'boolean' ? (value ? '1' : '0') : String(value));
+    }
+}
+
+function isDownload(res, type) {
+    const disposition = res.headers.get('content-disposition') || '';
+    return disposition.includes('attachment') || /pdf|octet-stream|spreadsheet|excel|zip|image\//.test(type);
+}
+
+async function saveDownload(res, type, output) {
+    const disposition = res.headers.get('content-disposition') || '';
+    const match = /filename\*=UTF-8''([^;]+)|filename="?([^";]+)"?/i.exec(disposition);
+    const suggested = match ? decodeURIComponent(match[1] || match[2]) : `empuno-${Date.now()}${extensionFor(type)}`;
+    let target = output || suggested;
+    if (output && fs.existsSync(output) && fs.statSync(output).isDirectory()) target = path.join(output, path.basename(suggested));
+    const buffer = Buffer.from(await res.arrayBuffer());
+    fs.writeFileSync(target, buffer);
+    return { ok: true, saved: path.resolve(target), bytes: buffer.length, content_type: type };
+}
+
+function extensionFor(type) {
+    if (type.includes('pdf')) return '.pdf';
+    if (type.includes('spreadsheet') || type.includes('excel')) return '.xlsx';
+    if (type.includes('csv')) return '.csv';
+    if (type.includes('html')) return '.html';
+    if (type.includes('png')) return '.png';
+    if (type.includes('jpeg')) return '.jpg';
+    return '.bin';
+}
+
+// ─── katalog ───────────────────────────────────────────────────────────────
+
+async function loadCatalog(auth, { refresh = false, all = false } = {}) {
+    const id = crypto.createHash('sha256').update(`${auth.url}|${auth.key}|${all}`).digest('hex').slice(0, 16);
+    const file = path.join(cacheDir(), `catalog-${id}.json`);
+
+    if (!refresh) {
+        try {
+            const stat = fs.statSync(file);
+            if (Date.now() - stat.mtimeMs < CATALOG_TTL_MS) return JSON.parse(fs.readFileSync(file, 'utf8'));
+        } catch { /* önbellek yok */ }
+    }
+
+    const { ok, result } = await request(auth, 'GET', '/api/company/v1/catalog', { query: all ? { all: 1 } : {} });
+    if (!ok) {
+        const err = new Error(result?.message || 'katalog alınamadı');
+        err.payload = result;
+        err.exitCode = 1;
+        throw err;
+    }
+
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(file, JSON.stringify(result), { mode: 0o600 });
+    } catch { /* önbellek yazılamazsa sorun değil */ }
+
+    return result;
+}
+
+async function findCommand(auth, name, flags) {
+    const catalog = await loadCatalog(auth, { refresh: flags.refresh });
+    let cmd = catalog.commands.find((c) => c.command === name);
+    if (cmd) return cmd;
+
+    if (catalog.access === 'read') {
+        const err = new UsageError('bu anahtar salt-okuma ("read") türünde: panel komutlarını çalıştıramaz, yalnız `empuno api …`. Firma Ayarları → API sekmesinden "Ajan" anahtarı oluşturun.');
+        err.payload = { ok: false, error: 'read_only_key' };
+        throw err;
+    }
+
+    // Önbellek eskiyse bir kez tazele; yoksa kapsam dışı mı, hiç yok mu söyle.
+    const full = await loadCatalog(auth, { refresh: true, all: true });
+    cmd = full.commands.find((c) => c.command === name);
+    if (cmd && cmd.allowed) return cmd;
+
+    if (cmd) {
+        const need = cmd.requires_company_admin ? ['company_admin'] : cmd.permissions;
+        const err = new UsageError(`"${name}" bu anahtarın kapsamında değil. Gereken yetki: ${need.join(', ') || '—'}. Anahtar kapsamını panelden genişletin (Firma Ayarları → API).`);
+        err.payload = { ok: false, error: 'scope_required', command: name, required: need };
+        throw err;
+    }
+
+    const suggestions = full.commands
+        .map((c) => c.command)
+        .filter((c) => c.includes(name.split('.')[0]) || name.includes(c.split('.')[0]))
+        .slice(0, 8);
+    const err = new UsageError(`bilinmeyen komut "${name}".${suggestions.length ? ` Şunlardan biri mi: ${suggestions.join(', ')}` : ' `empuno commands` ile listeleyin.'}`);
+    err.payload = { ok: false, error: 'unknown_command', command: name, suggestions };
+    throw err;
+}
+
+// ─── alt komutlar ──────────────────────────────────────────────────────────
+
+async function cmdLogin(args) {
+    const { flags } = args;
+    let key = flags.key || process.env.EMPUNO_API_KEY || args.positional[0];
+
+    if (flags['key-stdin'] || (!key && !process.stdin.isTTY)) {
+        key = fs.readFileSync(0, 'utf8').trim();
+    } else if (!key) {
+        key = await prompt('API anahtarı (emp_live_…): ');
+    }
+
+    const url = (flags.url || process.env.EMPUNO_URL || DEFAULT_URL).replace(/\/+$/, '');
+    const profileName = flags.profile || 'default';
+    const auth = { key: key?.trim(), url, profileName };
+    requireKey(auth);
+
+    const { ok, result } = await request(auth, 'GET', '/api/company/v1/me');
+    if (!ok) {
+        print(result);
+        return 1;
+    }
+
+    const cfg = readConfig();
+    cfg.profiles = cfg.profiles || {};
+    cfg.profiles[profileName] = { url, key: auth.key };
+    if (!cfg.default || !cfg.profiles[cfg.default]) cfg.default = profileName;
+    writeConfig(cfg);
+
+    print({ ok: true, profile: profileName, config: configPath(), company: result.company, access: result.api_key?.access, acts_as: result.agent?.acts_as ?? null });
+    if (result.api_key?.access !== 'agent') {
+        warn('bu anahtar salt-okuma ("read") türünde: yalnız `empuno api …` uçları çalışır. Panel işlemleri için "Ajan" anahtarı oluşturun.');
+    }
+    return 0;
+}
+
+function prompt(question) {
+    return new Promise((resolve) => {
+        process.stderr.write(question);
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+            if (data.includes('\n')) {
+                process.stdin.pause();
+                resolve(data.split('\n')[0]);
+            }
+        });
+    });
+}
+
+function cmdLogout(args) {
+    const cfg = readConfig();
+    const name = args.flags.profile || cfg.default || 'default';
+    const existed = Boolean(cfg.profiles?.[name]);
+    if (existed) delete cfg.profiles[name];
+    if (cfg.default === name) cfg.default = Object.keys(cfg.profiles || {})[0] || 'default';
+    writeConfig(cfg);
+    print({ ok: true, removed_profile: existed ? name : null, note: 'Anahtar sunucuda hâlâ geçerli; tamamen kapatmak için panelden iptal edin.' });
+    return 0;
+}
+
+async function cmdWhoami(args) {
+    const auth = resolveAuth(args.flags);
+    requireKey(auth);
+    const { ok, result } = await request(auth, 'GET', '/api/company/v1/me');
+    print({ ...result, cli: { version: VERSION, profile: auth.profileName, url: auth.url, key: maskKey(auth.key) } });
+    return ok ? 0 : 1;
+}
+
+async function cmdCommands(args) {
+    const { flags, positional } = args;
+    const auth = resolveAuth(flags);
+    requireKey(auth);
+    const catalog = await loadCatalog(auth, { refresh: flags.refresh, all: flags.all });
+    const needle = positional.join(' ').toLocaleLowerCase('tr');
+
+    let list = catalog.commands;
+    if (flags.module) list = list.filter((c) => c.module === flags.module);
+    if (flags.writes) list = list.filter((c) => c.kind === 'write');
+    if (flags.reads) list = list.filter((c) => c.kind === 'read');
+    if (needle) {
+        list = list.filter((c) => `${c.command} ${c.title || ''} ${c.summary} ${c.description || ''} ${c.module} ${c.module_label || ''}`.toLocaleLowerCase('tr').includes(needle));
+    }
+
+    if (wantsText()) {
+        let currentModule = null;
+        for (const c of [...list].sort((a, b) => a.module.localeCompare(b.module) || a.command.localeCompare(b.command))) {
+            if (c.module !== currentModule) {
+                currentModule = c.module;
+                process.stdout.write(`\n[${c.module}] ${c.module_label || ''}\n`);
+            }
+            const lock = c.allowed === false ? ' (kapsam dışı)' : '';
+            process.stdout.write(`  ${c.command.padEnd(44)} ${c.method.padEnd(6)} ${c.title || c.summary}${lock}\n`);
+        }
+        process.stdout.write(`\n${list.length} komut. Ayrıntı: empuno describe <komut>\n`);
+        return 0;
+    }
+
+    print({
+        count: list.length,
+        commands: flags.full ? list : list.map((c) => ({ command: c.command, method: c.method, path: c.path, kind: c.kind, module: c.module, title: c.title, ...(c.summary !== c.title ? { summary: c.summary } : {}), ...(c.allowed === false ? { allowed: false } : {}) })),
+        hint: 'Ayrıntı (parametreler, alanlar, yetki): empuno describe <komut>',
+    });
+    return 0;
+}
+
+async function cmdDescribe(args) {
+    const name = args.positional[0];
+    if (!name) throw new UsageError('kullanım: empuno describe <komut>');
+    const auth = resolveAuth(args.flags);
+    requireKey(auth);
+    let cmd;
+    try {
+        cmd = await findCommand(auth, name, args.flags);
+    } catch (e) {
+        // Kapsam dışı komut da açıklanır: ajan, kullanıcıdan hangi yetkiyi isteyeceğini bilsin.
+        if (e.payload?.error !== 'scope_required') throw e;
+        const full = await loadCatalog(auth, { all: true });
+        cmd = full.commands.find((c) => c.command === name);
+    }
+
+    const example = ['empuno', cmd.command, ...cmd.path_params.map((p) => `<${p}>`)];
+    for (const [field, rule] of Object.entries(cmd.fields || {}).slice(0, 4)) {
+        if (field.includes('*')) continue;
+        example.push(`--${field}`, /file|image|mimes/.test(rule) ? '@./dosya.pdf' : '<değer>');
+    }
+
+    print({
+        ...cmd,
+        usage: example.join(' '),
+        notes: [
+            cmd.allowed === false ? `Bu anahtar bu komutu çalıştıramaz; gereken yetki: ${(cmd.requires_company_admin ? ['company_admin'] : cmd.permissions).join(', ')}.` : null,
+            cmd.kind === 'read' ? 'Okuma komutu: alan bayrakları sorgu parametresi olarak gider (?per_page=…).' : 'Yazma komutu: alan bayrakları JSON gövdesi olarak gider; dosya için --alan @yol.',
+            cmd.fields ? 'fields: sunucunun doğrulama kuralları (best-effort).' : 'fields bilinmiyor: eksik alanlar 422 yanıtının `errors` nesnesinde listelenir.',
+            cmd.path_params.length ? `Yol parametreleri sırayla positional verilir: ${cmd.path_params.join(', ')}.` : null,
+        ].filter(Boolean),
+    });
+    return 0;
+}
+
+async function cmdRun(args, name) {
+    const { flags, fields } = args;
+    const auth = resolveAuth(flags);
+    requireKey(auth);
+    const cmd = await findCommand(auth, name, flags);
+
+    // Yol parametreleri: önce positional, sonra aynı adlı bayrak.
+    const positional = [...args.positional];
+    const named = new Map();
+    const bodyFields = [];
+    for (const [k, v] of fields) {
+        if (cmd.path_params.includes(k)) named.set(k, v);
+        else bodyFields.push([k, v]);
+    }
+
+    let urlPath = cmd.path;
+    for (const param of cmd.path_params) {
+        const value = named.get(param) ?? positional.shift();
+        if (value === undefined) throw new UsageError(`eksik yol parametresi: ${param} (kullanım: empuno describe ${cmd.command})`);
+        urlPath = urlPath.replace(new RegExp(`\\{${param}\\??\\}`), encodeURIComponent(value));
+    }
+    if (positional.length) throw new UsageError(`fazla argüman: ${positional.join(' ')}`);
+
+    return execute(auth, cmd.method, urlPath, flags, bodyFields);
+}
+
+async function cmdCall(args) {
+    const [method, urlPath, ...extra] = args.positional;
+    if (!method || !urlPath || extra.length) throw new UsageError('kullanım: empuno call <METHOD> </manager/yol> [--alan değer …]');
+    const auth = resolveAuth(args.flags);
+    requireKey(auth);
+    return execute(auth, method.toUpperCase(), urlPath.startsWith('/') ? urlPath : `/${urlPath}`, args.flags, args.fields);
+}
+
+async function cmdApi(args) {
+    const [sub, ...extra] = args.positional;
+    if (!sub || extra.length) throw new UsageError('kullanım: empuno api <leaves|expenses|employees|…> [--status approved …]');
+    const auth = resolveAuth(args.flags);
+    requireKey(auth);
+    return execute(auth, 'GET', `/api/company/v1/${sub.replace(/^\/+/, '')}`, args.flags, args.fields);
+}
+
+async function execute(auth, method, urlPath, flags, fieldPairs) {
+    let body = flags.json ? readJsonArg(flags.json) : {};
+    const files = [];
+
+    for (const raw of flags.file) {
+        const eq = raw.indexOf('=');
+        if (eq === -1) throw new UsageError('--file alan=yol biçiminde olmalı');
+        files.push({ field: raw.slice(0, eq), file: raw.slice(eq + 1).replace(/^@/, '') });
+    }
+
+    for (const [name, raw] of fieldPairs) {
+        if (typeof raw === 'string' && raw.startsWith('@') && raw.length > 1 && fs.existsSync(raw.slice(1))) {
+            files.push({ field: name, file: raw.slice(1) });
+            continue;
+        }
+        setDeep(body, name, coerce(raw));
+    }
+
+    for (const { file } of files) {
+        if (!fs.existsSync(file)) throw new UsageError(`dosya bulunamadı: ${file}`);
+    }
+
+    const query = {};
+    for (const raw of flags.query) {
+        const eq = raw.indexOf('=');
+        if (eq === -1) throw new UsageError('--query anahtar=değer biçiminde olmalı');
+        setDeep(query, raw.slice(0, eq), coerce(raw.slice(eq + 1)));
+    }
+
+    // GET'te alanlar sorguya gider.
+    if (method === 'GET' && Object.keys(body).length) {
+        Object.assign(query, body);
+        body = {};
+    }
+
+    const response = await request(auth, method, urlPath, { query, body, files, output: flags.output, dryRun: flags['dry-run'] });
+    print(response.result);
+    if (response.dryRun) return 0;
+    return response.ok ? 0 : 1;
+}
+
+/** npm ile kurulduysa (global ya da npx önbelleği) dosya node_modules altındadır. */
+function installedViaNpm() {
+    try {
+        return fs.realpathSync(process.argv[1]).split(path.sep).includes('node_modules');
+    } catch {
+        return false;
+    }
+}
+
+async function cmdUpdate(args) {
+    if (installedViaNpm()) {
+        // npm'in yönettiği dosyanın üzerine yazmak sürüm kaydını bozar.
+        print({ ok: false, error: 'managed_by_npm', version: VERSION, hint: `npm i -g ${NPM_PACKAGE}@latest` });
+        return 1;
+    }
+
+    const auth = resolveAuth(args.flags);
+    const target = fs.realpathSync(process.argv[1]);
+    const res = await fetch(`${auth.url}/cli/empuno.mjs`, { headers: { 'User-Agent': `empuno-cli/${VERSION}` } });
+    if (!res.ok) {
+        print({ ok: false, error: 'download_failed', status: res.status });
+        return 1;
+    }
+    const text = await res.text();
+    const match = /const VERSION = '([^']+)'/.exec(text);
+    if (!text.startsWith('#!/usr/bin/env node') || !match) {
+        print({ ok: false, error: 'invalid_download' });
+        return 1;
+    }
+    if (compareVersions(match[1], VERSION) <= 0 && !args.flags.all) {
+        print({ ok: true, updated: false, version: VERSION, note: 'Zaten güncel.' });
+        return 0;
+    }
+    const mode = fs.statSync(target).mode;
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, text, { mode });
+    fs.renameSync(tmp, target);
+    print({ ok: true, updated: true, from: VERSION, to: match[1], path: target });
+    return 0;
+}
+
+const HELP = `empuno ${VERSION} — empuno İK sistemini komut satırından (ve ajanlardan) yönetin
+
+KURULUM
+  npm i -g empuno                    # ya da kurmadan: npx empuno <komut>
+  curl -fsSL https://empuno.com/cli/empuno.mjs -o ~/.local/bin/empuno && chmod +x ~/.local/bin/empuno   # npm'siz
+  empuno login                       # anahtar: panel → Firma Ayarları → API → "Ajan" anahtarı
+  echo "$KEY" | empuno login --key-stdin   # geçmişe düşmeden
+
+KEŞİF
+  empuno whoami                      # firma, anahtar türü, kimin adına çalıştığı
+  empuno commands [ara] [--module leaves] [--writes|--reads] [--all] [--full]
+  empuno describe <komut>            # yöntem, yol, yol parametreleri, alanlar/kurallar, gereken yetki
+
+ÇALIŞTIRMA (komut = panel rotası; listeden)
+  empuno leave-requests.index --status pending --per_page 50
+  empuno leave-requests.approve 123
+  empuno leave-requests.reject 123 --rejection_reason "Yoğun dönem"
+  empuno employees.documents.store 45 --document_type is_sozlesmesi --file file=./sozlesme.pdf
+  empuno leave-reports.download 12 --output ./rapor.pdf             # dosya indir
+  empuno call POST /manager/leave-requests/123/approve      # ham çağrı
+  empuno api leaves --status approved                       # salt-okuma Company API
+
+ALANLAR
+  --ad değer | --ad=değer            # true/false/null/sayı/JSON otomatik; baştaki sıfır string kalır
+  --dizi a --dizi b | --dizi[] a     # dizi;  --a.b.0.c x → iç içe nesne
+  --json '{"..."}' | --json @govde.json
+  --alan @./dosya.pdf | --file alan=./dosya.pdf   # multipart yükleme
+  --query anahtar=değer              # yazma isteğinde ek sorgu parametresi
+
+GENEL BAYRAKLAR
+  --profile ad   --key emp_live_…   --url https://empuno.com   --dry-run   --output yol
+  --text | --json-out   --pretty | --compact   --refresh (katalog önbelleğini tazele)
+
+ORTAM: EMPUNO_API_KEY, EMPUNO_URL, EMPUNO_PROFILE, EMPUNO_CONFIG
+ÇIKTI: stdout her zaman JSON (TTY'de girintili). Çıkış kodu 0 başarı, 1 API hatası, 2 kullanım, 3 ağ.
+YANIT: okuma → {ok, page, data}; yazma → {ok, message, redirect:{command, params}} veya 422 {ok:false, message, errors}
+BELGE: https://empuno.com/api-docs/agent
+`;
+
+// ─── giriş noktası ─────────────────────────────────────────────────────────
+
+async function main() {
+    const argv = process.argv.slice(2);
+    const args = parseArgs(argv);
+    const [sub, ...rest] = args.positional;
+    args.positional = rest;
+
+    if (!sub || sub === 'help' || (args.flags.help && !sub)) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (args.flags.help) {
+        args.positional = [sub];
+        return cmdDescribe(args);
+    }
+
+    switch (sub) {
+        case 'version':
+        case '--version':
+            print({ version: VERSION, node: process.versions.node });
+            return 0;
+        case 'login':
+            return cmdLogin(args);
+        case 'logout':
+            return cmdLogout(args);
+        case 'whoami':
+        case 'me':
+            return cmdWhoami(args);
+        case 'commands':
+        case 'ls':
+            return cmdCommands(args);
+        case 'describe':
+            return cmdDescribe(args);
+        case 'call':
+            return cmdCall(args);
+        case 'api':
+            return cmdApi(args);
+        case 'update':
+            return cmdUpdate(args);
+        case 'run':
+            if (!args.positional[0]) throw new UsageError('kullanım: empuno run <komut> …');
+            return cmdRun({ ...args, positional: args.positional.slice(1) }, args.positional[0]);
+        default:
+            return cmdRun(args, sub);
+    }
+}
+
+main()
+    .then((code) => { process.exitCode = code ?? 0; })
+    .catch((e) => {
+        if (e instanceof UsageError) {
+            if (e.payload) print(e.payload);
+            warn(e.message);
+            process.exitCode = 2;
+            return;
+        }
+        if (e.payload) print(e.payload);
+        else print({ ok: false, error: e.exitCode === 3 ? 'network_error' : 'cli_error', message: e.message });
+        warn(e.message);
+        process.exitCode = e.exitCode || 1;
+    });

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "empuno",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "empuno İK platformunun komut satırı: yönetim panelindeki tüm işlemleri (izin, bordro, vardiya, PDKS, zimmet, masraf, işe alım) yapay zekâ ajanlarına ve otomasyonlara açar.",
+  "type": "module",
+  "bin": {
+    "empuno": "empuno.mjs"
+  },
+  "files": [
+    "empuno.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "empuno",
+    "cli",
+    "ai-agent",
+    "hr",
+    "ik",
+    "insan-kaynaklari",
+    "bordro",
+    "izin",
+    "pdks",
+    "turkey"
+  ],
+  "homepage": "https://empuno.com/api-docs/agent",
+  "author": "Lutfios LLC (https://empuno.com)",
+  "license": "MIT"
+}