taskmonkey-cli 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskmonkey-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "TaskMonkey CLI — Remote dev tools for tenant config editing and tool testing",
   "bin": {
     "tm": "./bin/tm.js",

package/src/commands/pull.js

@@ -55,6 +55,14 @@ export async function pull() {
       written++;
     }
 
+    // Create AGENTS.md (for Codex, Copilot, etc.) if it doesn't exist
+    const agentsMdPath = join(config._configDir, 'AGENTS.md');
+    if (!existsSync(agentsMdPath)) {
+      writeFileSync(agentsMdPath, generateAgentsMd(config.tenant));
+      console.log(chalk.cyan(`  AGENTS.md (created)`));
+      written++;
+    }
+
     // Install Claude Code skills to .claude/commands/
     const skillsInstalled = installSkills(config._configDir);
     written += skillsInstalled;
@@ -90,76 +98,309 @@ function installSkills(targetDir) {
 function generateClaudeMd(tenant) {
   return `# TaskMonkey Tenant: ${tenant}
 
-## Was ist das?
+Willkommen! Du arbeitest an der Konfiguration des **${tenant}**-Tenants auf der TaskMonkey-Plattform.
+TaskMonkey ist eine KI-Chat-Plattform mit konfigurierbaren Tools, Prompts und Monkey Tasks.
+
+## Erste Schritte
+
+1. Lies \`docs/TenantConfig.md\` — die vollständige Referenz aller Config-Keys
+2. Schau dir die bestehenden Dateien an, besonders \`monkey_tasks/\` und \`prompts/\`
+3. Starte \`tm watch\` in einem separaten Terminal für Auto-Sync
+4. Teste Änderungen mit \`tm chat\` oder \`tm test-chat "deine nachricht"\`
+
+## CLI Befehle (\`tm\`)
 
-Dieses Verzeichnis enthält die Konfiguration für den Tenant **${tenant}** der TaskMonkey-Plattform.
-Du kannst hier Prompts, Tools und Einstellungen bearbeiten und sie mit dem \`tm\` CLI auf den Server synchronisieren.
+| Befehl | Beschreibung |
+|--------|-------------|
+| \`tm pull\` | Config-Dateien vom Server herunterladen |
+| \`tm sync\` | Lokale Dateien zum Server hochladen |
+| \`tm watch\` | Auto-Sync bei Dateiänderung (in separatem Terminal laufen lassen) |
+| \`tm chat\` | Interaktiver Chat im Terminal |
+| \`tm chat --task inventur\` | Chat mit spezifischem Monkey Task |
+| \`tm chat --public\` | Öffentlicher Chat (wie Endkunde) |
+| \`tm test-tool <name> key=value\` | Einzelnes Tool testen |
+| \`tm test-chat "nachricht"\` | Einzelne Chat-Nachricht testen |
+| \`tm test-conversations\` | Alle conversation_tests ausführen |
+| \`tm optimize-prompt\` | GPT-4 analysiert Test-Failures und schlägt Prompt-Verbesserungen vor |
+| \`tm logs\` | Server-Logs live streamen |
 
 ## Verzeichnisstruktur
 
 \`\`\`
-.tmrc                    # Login-Daten (nicht committen!)
-CLAUDE.md                # Diese Datei
-docs/                    # Dokumentation (TenantConfig.md etc.)
-monkey_tasks/            # Monkey Task Definitionen (Name, Tools, Prompts)
-prompts/                 # Allgemeine Prompts (System, First Message)
+monkey_tasks/            # Monkey Task Definitionen
+  inventur.php           #   Name, Tools, Prompt, sheetView etc.
+  wareneingang.php       #   Jeder Task in einer Datei
+prompts/                 # Allgemeine Prompts
+  system.php             #   System-Prompt für öffentlichen Chat
+  first_message.php      #   Begrüßungsnachricht
 tools/                   # Tool-Konfigurationen
-  jtl/                   # JTL-spezifische Tools
-  lieferschein/          # Lieferschein/Wareneingang Tools
-  google_sheets/         # Google Sheets Tools
-  support/               # Support Tools
+  jtl/items/             #   z.B. searchItems.php, updateStock.php
+  google_sheets/         #   z.B. readFromGoogleSheet.php
 scan.php                 # Barcode/QR Scanner Konfiguration
-apis.php                 # API-Verbindungen (JTL etc.)
+apis.php                 # API-Verbindungen
+docs/                    # Dokumentation (TenantConfig.md, ToolRunner.md)
+.tmrc                    # Login-Daten (NICHT committen!)
 \`\`\`
 
-## CLI Befehle
-
-\`\`\`bash
-tm login                              # Einloggen und Tenant wählen
-tm pull                               # Config-Dateien vom Server herunterladen
-tm sync                               # Lokale Dateien zum Server hochladen
-tm watch                              # Auto-Sync bei Dateiänderung
-tm test-tool <name> [key=value ...]   # Tool auf dem Server testen
-tm test-tool <name> --dry-run         # Tool im Simulationsmodus testen
-tm logs                               # Server-Logs live streamen
-\`\`\`
-
-## Workflow
-
-1. **Datei bearbeiten** — z.B. einen Prompt in \`monkey_tasks/inventur.php\` ändern
-2. **Synchronisieren** — \`tm sync\` oder \`tm watch\` für Auto-Sync
-3. **Testen** — Im Chat ausprobieren oder \`tm test-tool\` für direktes Tool-Testing
-4. **Logs prüfen** — \`tm logs\` bei Problemen
-
 ## Config-Format
 
-Jede .php Datei gibt ein Array zurück mit Dot-Notation Keys:
+Jede .php Datei gibt ein Array mit Dot-Notation Keys zurück:
 
 \`\`\`php
 <?php
 return [
     'monkey_tasks.inventur' => [
         'name' => 'Inventur',
-        'description' => 'Lagerbestand erfassen',
+        'description' => 'Lagerbestand erfassen und aktualisieren',
         'icon' => '✅',
-        'tools' => ['searchItems', 'updateStock', ...],
+        'tools' => ['searchItems', 'getStockBySku', 'updateStock'],
     ],
     'monkey_tasks.inventur.prompt' => <<<'PROMPT'
-    Du bist der Inventur-Assistent...
+    Du bist der Inventur-Assistent.
+    Wenn der User eine SKU oder einen Artikelnamen nennt, suche mit searchItems.
     PROMPT,
 ];
 \`\`\`
 
-Siehe \`docs/TenantConfig.md\` für die vollständige Dokumentation aller Config-Keys.
+## Tool-Konfiguration
+
+Tools können auf drei Arten definiert werden:
+
+### 1. API-Only (einfache API-Calls)
+\`\`\`php
+'tools.getCustomer' => [
+    'api' => 'jtl',
+    'endpoint' => 'customers/{customerId}',
+    'method' => 'GET',
+    'description' => 'Holt Kundendaten',
+    'parameters' => [
+        'type' => 'object',
+        'properties' => [
+            'customerId' => ['type' => 'integer'],
+        ],
+        'required' => ['customerId'],
+    ],
+],
+\`\`\`
+
+### 2. API + Pre/Postprocess
+\`\`\`php
+'tools.getOrderItems' => [
+    'api' => 'jtl',
+    'endpoint' => 'salesOrders/{orderId}/lineitems',
+    'method' => 'GET',
+    'preprocess' => function(array \\$args, array \\$ctx): array {
+        // Lookup oder Validierung vor dem API-Call
+        return ['orderId' => \\$ctx['tool']('verifyOrder', \\$args)['orderId']];
+    },
+    'postprocess' => function(array \\$results, array \\$args, array \\$ctx): array {
+        // Ergebnis filtern/transformieren
+        return ['items' => array_filter(\\$results, fn(\\$i) => \\$i['Type'] === 1)];
+    },
+],
+\`\`\`
+
+### 3. Handler (komplexe Logik)
+\`\`\`php
+'tools.myCustomTool' => [
+    'description' => 'Beschreibung für die KI',
+    'internal' => true,
+    'handler' => function(array \\$results, array \\$args, array \\$ctx): array {
+        \\$logger = \\$ctx['logger'];
+        \\$logger->info("Starte...");
+
+        // Andere Tools aufrufen
+        \\$item = \\$ctx['tool']('searchItems', ['searchSku' => \\$args['sku']]);
+
+        // API-Calls via Cake HTTP Client
+        \\$api = \\$ctx['config']['apis']['jtl'];
+        \\$http = new \\Cake\\Http\\Client(['timeout' => 60]);
+        \\$response = \\$http->get(\\$api['base_url'] . '/items', [], ['headers' => \\$api['headers']]);
+
+        \\$logger->success("Fertig");
+        return ['success' => true, 'data' => \\$response->getJson()];
+    },
+    'parameters' => [
+        'type' => 'object',
+        'properties' => [
+            'sku' => ['type' => 'string', 'description' => 'Artikel-SKU'],
+        ],
+        'required' => ['sku'],
+    ],
+],
+\`\`\`
+
+## Verfügbare Tool-Handler-Klassen
+
+Diese PHP-Klassen stehen als Handler zur Verfügung (Referenz: \`[ClassName, 'methodName']\`):
+
+| Klasse | Methoden | Beschreibung |
+|--------|----------|-------------|
+| \`JtlTools\` | searchItems, findBySku, getStockBySku, updateStock, verifyOrder, getOrderLineItems, ... | JTL Wawi API (Artikel, Bestellungen, Lager) |
+| \`GoogleSheetsTools\` | readFromGoogleSheet, writeToGoogleSheet | Google Sheets lesen/schreiben |
+| \`GoogleDriveTools\` | listFiles, readFile, uploadFile, createFile, searchFiles | Google Drive |
+| \`BankingTools\` | getBalance, searchTransactions, listAccounts, matchInvoiceData | Banking/FinAPI |
+| \`DropboxTools\` | uploadToDropbox, listDropboxFiles, readDropboxFile | Dropbox |
+| \`PdfTools\` | extractInvoiceFromPdf, extractTextFromPdf | PDF-Verarbeitung |
+| \`DatabaseGatewayTools\` | deployGateway, executeQuery, removeGateway | Remote-SQL via temporärem Gateway |
+| \`BloomifyTools\` | getProducts, createComplaint, createSupportRequest | Bloomify-spezifisch |
+| \`SuggestionsTools\` | setSuggestions | Chat-Suggestions setzen |
+
+## Handler-Kontext (\`\\$ctx\`)
+
+Jeder Handler bekommt einen Kontext mit:
+
+\`\`\`php
+\\$ctx['config']     // Tenant-Konfiguration (APIs, Tools, etc.)
+\\$ctx['tenant']     // Tenant-Code (z.B. "bloomify")
+\\$ctx['logger']     // TaskLogger: ->info(), ->success(), ->error(), ->warning()
+\\$ctx['tool']       // Funktion zum Aufrufen anderer Tools: \\$ctx['tool']('toolName', \\$args)
+\\$ctx['chat_id']    // Chat-Session ID
+\\$ctx['testMode']   // true wenn im Simulationsmodus
+\`\`\`
+
+## Verfügbare Vendor-Libraries
+
+\`\`\`php
+\\Cake\\Http\\Client       // HTTP-Requests (GET, POST, etc.)
+\\Cake\\Cache\\Cache       // Caching (read, write, delete)
+\\Cake\\ORM\\TableRegistry // Datenbank-Zugriff
+\\Cake\\Core\\Configure    // App-Konfiguration lesen
+\\Google_Service_Sheets   // Google Sheets API
+\\Google_Service_Drive    // Google Drive API
+\\GuzzleHttp\\Client       // Alternative HTTP-Library
+\`\`\`
+
+## Conversation Tests
+
+Definiere Tests um Prompt-Änderungen automatisch zu validieren:
+
+\`\`\`php
+'conversation_tests' => [
+    [
+        'description' => 'Erdbeere suchen',
+        'user_message' => 'welche erdbeeren habt ihr?',
+        'expect_tool_calls' => ['getProducts'],
+        'expect_response_contains' => ['Erdbeere', 'Preis'],
+    ],
+    [
+        'description' => 'Bestand abfragen',
+        'user_message' => 'wie viele Tomaten haben wir?',
+        'expect_tool_calls' => ['searchItems', 'getStockBySku'],
+    ],
+],
+\`\`\`
+
+Ausführen: \`tm test-conversations\`
+Optimieren: \`tm optimize-prompt\`
 
 ## Wichtige Regeln
 
-- **Nur .php Dateien** werden synchronisiert
-- **PHP-Syntax wird geprüft** vor dem Schreiben auf dem Server
-- **\`.tmrc\` nie committen** — enthält Login-Token
-- **Prompts** definieren das Verhalten der KI im Chat
-- **Tools** definieren welche Aktionen die KI ausführen kann
-- **\`internal: true\`** bei Tools bedeutet: nur für Monkey Tasks, nicht für öffentliche Chats
+- Nur \`.php\` Dateien werden synchronisiert
+- PHP-Syntax wird vor dem Schreiben auf dem Server geprüft
+- \`.tmrc\` nie committen (enthält Login-Token)
+- \`internal: true\` bei Tools = nur für Monkey Tasks, nicht für öffentliche Chats
+- Handler-Signatur: \`function(array \\$results, array \\$args, array \\$ctx): array\`
+- Immer \`['success' => true/false]\` im Return-Array
+- \`\\$ctx['tool']('name', \\$args)\` für verschachtelte Tool-Aufrufe
 `;
 }
 
+function generateAgentsMd(tenant) {
+  return `# TaskMonkey Tenant: ${tenant}
+
+This directory contains the configuration for the **${tenant}** tenant on the TaskMonkey AI platform.
+Use the \`tm\` CLI to sync changes and test.
+
+## Setup
+
+\`\`\`bash
+npm install -g taskmonkey-cli
+tm login
+tm pull
+\`\`\`
+
+## Commands
+
+- \`tm sync\` — Upload local config files to server
+- \`tm watch\` — Auto-sync on file change
+- \`tm test-tool <name> key=value\` — Run a tool on the server
+- \`tm test-chat "message"\` — Test a single chat message
+- \`tm chat\` — Interactive chat REPL
+- \`tm test-conversations\` — Run all conversation tests
+- \`tm optimize-prompt\` — GPT-4 prompt optimization based on test failures
+- \`tm logs\` — Stream server logs
+
+## File Structure
+
+- \`monkey_tasks/*.php\` — Task definitions (name, tools, prompt)
+- \`prompts/*.php\` — System prompts and greetings
+- \`tools/**/*.php\` — Tool configurations (API calls, handlers)
+- \`docs/TenantConfig.md\` — Full config reference
+
+## Config Format
+
+Each .php file returns an array with dot-notation keys:
+
+\`\`\`php
+<?php
+return [
+    'monkey_tasks.myTask' => [
+        'name' => 'My Task',
+        'tools' => ['searchItems', 'updateStock'],
+    ],
+    'monkey_tasks.myTask.prompt' => <<<'PROMPT'
+    You are an assistant that...
+    PROMPT,
+];
+\`\`\`
+
+## Tool Patterns
+
+### API-only
+\`\`\`php
+'tools.getName' => ['api' => 'myapi', 'endpoint' => 'items/{id}', 'method' => 'GET']
+\`\`\`
+
+### Handler
+\`\`\`php
+'tools.myTool' => [
+    'handler' => function(array $results, array $args, array $ctx): array {
+        $item = $ctx['tool']('searchItems', ['searchSku' => $args['sku']]);
+        return ['success' => true, 'item' => $item];
+    },
+]
+\`\`\`
+
+## Available Handler Classes
+
+| Class | Key Methods |
+|-------|------------|
+| JtlTools | searchItems, findBySku, getStockBySku, updateStock, verifyOrder |
+| GoogleSheetsTools | readFromGoogleSheet, writeToGoogleSheet |
+| GoogleDriveTools | listFiles, readFile, uploadFile |
+| BankingTools | getBalance, searchTransactions, matchInvoiceData |
+| PdfTools | extractInvoiceFromPdf, extractTextFromPdf |
+| DatabaseGatewayTools | deployGateway, executeQuery |
+
+## Handler Context
+
+\`\`\`php
+$ctx['config']   // Tenant config (APIs, tools)
+$ctx['tenant']   // Tenant code
+$ctx['logger']   // Logger: ->info(), ->success(), ->error()
+$ctx['tool']     // Call other tools: $ctx['tool']('name', $args)
+\`\`\`
+
+## Testing
+
+Define conversation tests in config, run with \`tm test-conversations\`:
+
+\`\`\`php
+'conversation_tests' => [
+    ['description' => 'Find product', 'user_message' => 'show me strawberries',
+     'expect_tool_calls' => ['getProducts'], 'expect_response_contains' => ['Strawberry']],
+]
+\`\`\`
+`;
+}