social-agent-cli 1.0.0

package/README.md

@@ -0,0 +1,226 @@
+# social-agent-cli
+
+AI-powered social media automation tool with self-healing browser automation. Teach it any action on any platform — it learns, adapts, and recovers from errors automatically.
+
+## How It Works
+
+```
+You: "like this tweet and retweet it: https://x.com/..."
+
+  1. [Planner]   → Parses natural language command
+  2. [Knowledge] → Loads platform-specific knowledge (URLs, selectors, limits)
+  3. [Map Check] → Checks learned action maps
+  4. [Learn]     → If missing, opens Chrome, takes screenshot + DOM, AI creates selector map
+  5. [Runner]    → Executes steps sequentially
+  6. [Heal]      → On failure: screenshots page, AI re-plans remaining steps (effort escalates)
+```
+
+## Features
+
+- **Natural language commands** — `social-agent run x "like and retweet this tweet"`
+- **Self-healing** — When selectors break, AI sees the screen and re-plans from where it left off
+- **Learning** — Teach any action once, reuse forever. Maps are saved as JSON
+- **Combination** — Chains multiple learned actions in a single command
+- **Real Chrome profile** — Uses your actual Chrome profile via CDP. No bot detection
+- **Zero hardcode** — No platform-specific selectors in code. Everything is AI-learned
+- **Free API drivers** — Mastodon, Bluesky, Telegram via direct API (no browser needed)
+- **Browser automation** — X, LinkedIn, Instagram, Facebook via Chrome
+- **Post history** — Logs every action. AI matches your tone in future posts
+- **Git hook** — Notifies you after `git push` to suggest social media posts
+- **Claude Code integration** — `claude-social` mode + `/social` slash command
+
+## Install
+
+```bash
+npm install -g social-agent-cli
+social-agent setup
+```
+
+The setup wizard asks your name, social handles, API tokens, and configures everything — Chrome profile selection, git hooks, shell aliases.
+
+## Quick Start
+
+```bash
+# 1. First-time setup
+social-agent setup
+
+# 2. Login to browser platforms (one-time)
+social-agent login x
+social-agent login linkedin
+
+# 3. Teach actions
+social-agent learn x                                    # learn to post (default)
+social-agent learn "learn to like tweets" x             # learn liking
+social-agent learn "learn to send connection request" linkedin
+
+# 4. Use with natural language
+social-agent run x "like this tweet: https://x.com/user/status/123"
+social-agent run x "like and retweet: https://x.com/user/status/123"
+social-agent run linkedin "send connection requests to 3 people"
+social-agent post "New feature released!" --platforms mastodon,bluesky
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `social-agent setup` | First-time setup wizard |
+| `social-agent login <platform>` | Select Chrome profile and verify login |
+| `social-agent learn "<task>" <platform>` | AI learns a new action from the page |
+| `social-agent run <platform> "<command>"` | Execute with natural language |
+| `social-agent post "<text>" --platforms x,mastodon` | Post to platforms |
+| `social-agent status` | Show connected platforms |
+| `social-agent history` | Show action history |
+
+## Supported Platforms
+
+### API-based (free, no browser needed)
+| Platform | Auth | Features |
+|----------|------|----------|
+| **Mastodon** | Access token | Post, media upload, like, boost, follow |
+| **Bluesky** | App password | Post, media, like, repost, follow |
+| **Telegram** | Bot token | Send messages, photos, videos to channels |
+
+### Browser-based (Chrome automation)
+| Platform | Method | Notes |
+|----------|--------|-------|
+| **X (Twitter)** | CDP + real Chrome | Free tier friendly, no API costs |
+| **LinkedIn** | CDP + real Chrome | Connection requests, posts, reactions |
+| **Instagram** | CDP + real Chrome | Aggressive anti-bot, use with caution |
+| **Facebook** | CDP + real Chrome | Checkpoint system, careful usage |
+
+## Self-Healing
+
+When a step fails, AI doesn't just retry — it **sees the screen and re-plans**:
+
+```
+Step 6: Click "Post" button ✗
+  [heal] AI analyzing screen (effort: low)...
+  → "Post button is inside a scrollable container, need to scroll first"
+  → New plan: scroll down + click with updated selector
+
+Step 6 (new): Scroll down ✓
+Step 7 (new): Click post button ✓
+```
+
+Effort escalates on repeated failures: `low → medium → medium`
+
+## Selector Maps
+
+Learned actions are saved as JSON in `~/.social-agent/maps/`:
+
+```json
+{
+  "platform": "x",
+  "action": "like_tweet",
+  "parameters": ["{{TWEET_URL}}"],
+  "steps": [
+    { "action": "goto", "url": "{{TWEET_URL}}" },
+    { "action": "wait", "waitMs": 2000 },
+    { "action": "click", "selector": "[data-testid='like']",
+      "fallbackSelectors": ["[aria-label*='Like']"] },
+    { "action": "wait", "waitMs": 1000 }
+  ]
+}
+```
+
+## Chrome Integration
+
+- **CDP (Chrome DevTools Protocol)** connection
+- Chrome open → connects to existing instance, opens new tab
+- Chrome closed → launches with your selected profile
+- Only closes the tab, **never kills Chrome**
+- `navigator.webdriver = false` to avoid detection
+- `--enable-automation` flag removed
+
+## Claude Code Integration
+
+### `claude-social` mode
+Run Claude with social media awareness. It suggests posts at milestones:
+
+```bash
+claude-social
+
+# While working...
+# AI: "This feature is worth sharing. Type /social to create a post."
+```
+
+### `/social` slash command
+Creates a post from your current work context:
+1. Analyzes conversation history + git log + project info
+2. Reads post history for tone matching
+3. Asks which platforms
+4. Generates platform-optimized content
+5. Creates image (optional, platform-sized)
+6. Posts in background after approval
+
+## Data Directory
+
+Everything lives in `~/.social-agent/`:
+
+```
+~/.social-agent/
+├── config.json              # API keys and settings
+├── social-mode-prompt.md    # AI assistant personality (editable)
+├── profile-map.json         # Platform → Chrome profile mapping
+├── history.json             # Action log
+├── knowledge/               # Platform knowledge files
+│   ├── x.md                 # X/Twitter: selectors, URLs, limits
+│   ├── linkedin.md          # LinkedIn: aria-labels, anti-bot
+│   ├── instagram.md         # Instagram: aggressive anti-bot docs
+│   ├── facebook.md          # Facebook: checkpoint system
+│   ├── mastodon.md          # Mastodon: full API reference
+│   ├── bluesky.md           # Bluesky: AT Protocol API
+│   └── telegram.md          # Telegram: Bot API
+├── maps/                    # Learned action maps (JSON)
+├── profiles/                # Chrome CDP working directory
+└── screenshots/             # AI analysis screenshots
+```
+
+## Adding New Platforms
+
+No code changes needed:
+
+1. Add URL to `BROWSER_PLATFORMS` in `cli.ts`
+2. Create `knowledge/platform.md`
+3. `social-agent login platform`
+4. `social-agent learn platform`
+5. `social-agent run platform "do something"`
+
+## Architecture
+
+```
+social-agent/
+├── bin/social-agent.js         # Global CLI entry point
+├── cli.ts                      # Command router
+├── install.ts                  # Setup wizard
+├── core/
+│   ├── config.ts               # Config & paths (~/.social-agent/)
+│   ├── types.ts                # TypeScript interfaces
+│   ├── profiles.ts             # Chrome profile discovery & selection
+│   ├── history.ts              # Action logging
+│   └── screenshot.ts           # HTML → JPEG converter
+├── ai/
+│   ├── mapper.ts               # Claude -p: create/heal selector maps
+│   ├── planner.ts              # Natural language → execution plan
+│   ├── runner.ts               # Execute plan with heal-on-failure
+│   └── knowledge.ts            # Platform knowledge reader
+├── platforms/
+│   ├── mastodon.ts             # Mastodon API driver
+│   ├── bluesky.ts              # Bluesky AT Protocol driver
+│   └── browser/
+│       └── driver.ts           # Playwright + Chrome CDP + anti-detection
+├── knowledge/                  # Platform knowledge (7 platforms, 7000+ lines)
+└── hooks/
+    └── post-push               # Git hook for post suggestions
+```
+
+## Requirements
+
+- Node.js 18+
+- Google Chrome (macOS — Linux/Windows support planned)
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (`npm install -g @anthropic-ai/claude-code`)
+
+## License
+
+MIT

package/bin/postinstall.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import { execSync } from "node:child_process";
+
+try {
+  console.log("  Playwright Chromium yükleniyor...");
+  execSync("npx playwright install chromium", { stdio: "pipe" });
+  console.log("  ✓ Playwright Chromium yüklendi");
+} catch {
+  console.log("  ⚠ Playwright Chromium otomatik yüklenemedi.");
+  console.log("    Manuel kur: npx playwright install chromium");
+}
+
+console.log(`
+  ✓ social-agent kuruldu!
+
+  Başlamak için:
+    social-agent setup
+`);

package/bin/social-agent.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { execSync, spawn } from "node:child_process";
+import { homedir } from "node:os";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_DIR = join(__dirname, "..");
+
+// Kullanıcının data dizini (~/.social-agent/)
+const DATA_DIR = join(homedir(), ".social-agent");
+
+// Data dizinini oluştur
+for (const dir of ["maps", "profiles", "screenshots", "knowledge"]) {
+  mkdirSync(join(DATA_DIR, dir), { recursive: true });
+}
+
+// Knowledge dosyalarını kopyala (yoksa)
+const knowledgeSrc = join(PKG_DIR, "knowledge");
+const knowledgeDest = join(DATA_DIR, "knowledge");
+if (existsSync(knowledgeSrc)) {
+  const { readdirSync, copyFileSync } = await import("node:fs");
+  for (const file of readdirSync(knowledgeSrc)) {
+    const dest = join(knowledgeDest, file);
+    if (!existsSync(dest)) {
+      copyFileSync(join(knowledgeSrc, file), dest);
+    }
+  }
+}
+
+const [,, command, ...args] = process.argv;
+
+// Komuta göre doğru ts dosyasını çalıştır
+const tsxPath = join(PKG_DIR, "node_modules", ".bin", "tsx");
+const cwd = DATA_DIR;
+
+function run(file, extraArgs = []) {
+  const proc = spawn(tsxPath, [join(PKG_DIR, file), ...extraArgs], {
+    cwd: DATA_DIR,
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      SOCIAL_AGENT_DATA: DATA_DIR,
+      SOCIAL_AGENT_PKG: PKG_DIR,
+    },
+  });
+  proc.on("close", (code) => process.exit(code || 0));
+}
+
+switch (command) {
+  case "setup":
+    run("install.ts");
+    break;
+
+  case "login":
+  case "learn":
+  case "run":
+  case "post":
+  case "test":
+  case "status":
+  case "history":
+    run("cli.ts", [command, ...args]);
+    break;
+
+  case undefined:
+  case "--help":
+  case "-h":
+    console.log(`
+  social-agent - AI destekli sosyal medya otomasyon aracı
+
+  Kurulum:
+    social-agent setup              İlk kurulum (isim, profil, platformlar)
+
+  Komutlar:
+    social-agent login <platform>   Chrome profil seç ve giriş yap
+    social-agent learn "<görev>" <platform>  AI ile aksiyon öğret
+    social-agent run <platform> "<komut>"    Doğal dil ile çalıştır
+    social-agent post "<metin>" --platforms x,mastodon  Post at
+    social-agent status             Bağlı platformları göster
+    social-agent history            Post geçmişi
+
+  Örnekler:
+    social-agent setup
+    social-agent login x
+    social-agent learn "tweet beğenmeyi öğren" x
+    social-agent run x "şu tweeti beğen: https://x.com/..."
+    social-agent run linkedin "3 insana bağlantı isteği gönder"
+    social-agent post "Yeni özellik!" --platforms x,mastodon
+
+  Ayarlar:
+    ~/.social-agent/                Data dizini
+    ~/.social-agent/config.json     Platform API ayarları
+    ~/.social-agent/social-mode-prompt.md  AI asistan profili (düzenlenebilir)
+    ~/.social-agent/knowledge/      Platform bilgileri
+    ~/.social-agent/maps/           Öğrenilmiş aksiyonlar
+    ~/.social-agent/history.json    Post geçmişi
+
+  Claude Code entegrasyonu:
+    claude-social                   Sosyal medya farkındalıklı mod
+    /social                         Elle post oluştur
+`);
+    break;
+
+  default:
+    console.log(`Bilinmeyen komut: ${command}. --help ile kullanımı gör.`);
+    process.exit(1);
+}

package/config.example.json

@@ -0,0 +1,20 @@
+{
+  "mastodon": {
+    "instanceUrl": "https://mastodon.scot",
+    "accessToken": "mastodon-access-token-buraya"
+  },
+  "bluesky": {
+    "identifier": "kullanici.bsky.social",
+    "password": "app-password-buraya"
+  },
+  "telegram": {
+    "botToken": "123456:ABC-DEF...",
+    "chatId": "@kanal_adi"
+  },
+  "browser": {
+    "headless": true
+  },
+  "claude": {
+    "model": "sonnet"
+  }
+}

package/hooks/post-push

@@ -0,0 +1,69 @@
+#!/bin/bash
+# ============================================================
+# Git Post-Push Hook
+# Push sonrası Claude Code'a post önerisi yapması için bildirim gönderir
+#
+# Kurulum:
+#   npx tsx install.ts (otomatik kurar)
+#   veya manuel: git config --global core.hooksPath ~/.git-hooks
+# ============================================================
+
+SOCIAL_AGENT_DIR="${SOCIAL_AGENT_DIR:-/Volumes/harici_ssd/postiz/social-agent}"
+
+# Config yoksa sessizce çık
+if [[ ! -f "$SOCIAL_AGENT_DIR/config.json" ]]; then
+  exit 0
+fi
+
+# Profil bilgisini al
+PROMPT_FILE="$SOCIAL_AGENT_DIR/social-mode-prompt.md"
+if [[ -f "$PROMPT_FILE" ]]; then
+  NAME=$(grep "Kullanıcının adı:" "$PROMPT_FILE" | head -1 | sed 's/.*: //')
+else
+  NAME="Developer"
+fi
+
+# Mevcut repo bilgisi
+REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Sadece önemli branch'lerde çalış
+case "$BRANCH" in
+  main|master|dev|develop|release/*) ;;
+  *) exit 0 ;;
+esac
+
+# Son push'taki commitler
+COMMITS=$(git log --oneline -5 2>/dev/null)
+COMMIT_COUNT=$(echo "$COMMITS" | wc -l | tr -d ' ')
+
+if [[ -z "$COMMITS" ]]; then
+  exit 0
+fi
+
+# Diff özeti
+DIFF_STAT=$(git diff --stat HEAD~1..HEAD 2>/dev/null | tail -1)
+
+# Önemsiz commit'leri atla
+if echo "$COMMITS" | head -1 | grep -qiE "^[a-f0-9]+ (typo|fix typo|merge|bump|chore|docs:|ci:)"; then
+  exit 0
+fi
+
+# macOS bildirimi gönder
+if command -v osascript &>/dev/null; then
+  osascript -e "display notification \"$REPO_NAME: $COMMIT_COUNT yeni commit. /social ile paylaşabilirsin.\" with title \"Social Agent\" subtitle \"$NAME, post önerisi var!\" sound name \"Glass\"" 2>/dev/null || true
+fi
+
+# Terminal'e bilgi yaz
+echo ""
+echo "┌─────────────────────────────────────────────┐"
+echo "│  Social Agent: Post önerisi                 │"
+echo "├─────────────────────────────────────────────┤"
+echo "│  $REPO_NAME ($BRANCH) - $COMMIT_COUNT commit"
+echo "│  $DIFF_STAT"
+echo "│                                             │"
+echo "│  claude-social ile çalışırken /social yaz   │"
+echo "│  veya: cd $SOCIAL_AGENT_DIR                 │"
+echo "│        npx tsx cli.ts run x \"post at: ...\"  │"
+echo "└─────────────────────────────────────────────┘"
+echo ""