social-autoposter 1.1.3 → 1.2.0

package/README.md

@@ -1,84 +1,140 @@
 # social-autoposter
 
-Automated social posting pipeline for Reddit, X/Twitter, LinkedIn, and Moltbook. Install as an AI agent skill or use the standalone Python scripts.
+Automated social posting pipeline for Reddit, X/Twitter, LinkedIn, and Moltbook. Ships as a Claude Code skill plus a set of standalone Python helpers and macOS launchd jobs.
 
-The current storage backend is Neon Postgres via `DATABASE_URL` in `~/social-autoposter/.env`. Any legacy `database` key in old local configs or leftover `*.db` files are not used by the current scripts.
+Posts are written to a shared Neon Postgres database via `DATABASE_URL` in `~/social-autoposter/.env`. Each platform drives its own persistent Playwright MCP browser profile, so logins survive across runs.
 
-## Install as a skill
+## Prerequisites
+
+A new machine needs all of these before the pipeline can run end to end:
+
+- **macOS** (the launchd plists are mac-only; Linux users can crib the cron snippets from `setup/SKILL.md` Step 7)
+- **Node.js 16+** (for `npx`, the installer, and `@playwright/mcp` at runtime)
+- **Python 3.9+** with `pip3` (helper scripts; `psycopg2-binary` is auto-installed by the installer)
+- **Claude Code CLI** on `PATH` (the cron scripts shell out to `claude -p` with a per-platform MCP config)
+- **`psql`** on `PATH` (a few scripts query Neon directly)
+- One Chromium install per platform (created on first run by `@playwright/mcp` against the persistent profile dirs)
+
+Optional:
+
+- `MOLTBOOK_API_KEY` in `.env` for Moltbook posting and scanning
+- `RESEND_API_KEY` and `NOTIFICATION_EMAIL` in `.env` for DM-escalation emails
+
+## Install
 
 ```bash
 npx social-autoposter init
 ```
 
-Then tell your agent: **"set up social autoposter"** — the setup skill walks you through config, DB creation, browser logins, and a test run.
+`bin/cli.js` does all of the wiring in one shot:
+
+1. Copies `scripts/`, `skill/`, `setup/`, `SKILL.md`, `schema-postgres.sql`, and `browser-agent-configs/` into `~/social-autoposter/`
+2. Creates `config.json` from `config.example.json` and `.env` from `.env.example` (the shared Neon `DATABASE_URL` is pre-filled)
+3. Installs `psycopg2-binary` via `pip3` if missing
+4. Generates launchd plists in `~/social-autoposter/launchd/` with the user's actual `HOME` and `PATH`
+5. Installs the Playwright MCP configs to `~/.claude/browser-agent-configs/` (twitter, reddit, linkedin) with `__HOME__` and `__NODE_BIN__` placeholders substituted. Existing files are left alone, so any window-position tweaks survive `npx social-autoposter update`.
+6. Creates empty persistent browser profile dirs at `~/.claude/browser-profiles/{twitter,reddit,linkedin}`
+7. Symlinks `~/.claude/skills/social-autoposter` and `~/.claude/skills/social-autoposter-setup` to the install dir
+
+To refresh code without touching user files (`config.json`, `.env`, `SKILL.md`, or any browser config you customized):
 
-To update scripts without touching your config or database:
 ```bash
 npx social-autoposter update
 ```
 
-Or set up manually:
-```bash
-cp config.example.json config.json   # edit with your accounts
-psql "$DATABASE_URL" -f schema-postgres.sql  # initialize the Neon DB
-bash setup.sh                        # symlinks + launchd (macOS)
-```
+## Configure
 
-## How it works
+Tell your Claude Code agent: **"set up social autoposter"**. The interactive wizard in `setup/SKILL.md` walks through:
 
+1. Verifying the Neon connection
+2. Filling in `~/social-autoposter/config.json` with handles for Reddit, Twitter, LinkedIn, optional Moltbook
+3. A 5-question interview to draft your `content_angle`
+4. Capturing `projects` with `topics` (used by the tiered reply strategy)
+5. Verifying browser logins per platform via the dedicated MCP agent. The first time each platform runs you'll be asked to log in once; cookies persist into the userDataDir under `~/.claude/browser-profiles/`.
+6. A dry-run of `find_threads.py --limit 3`
+7. Optional: loading the launchd plists into `~/Library/LaunchAgents/`
+
+## How the runtime is wired
+
+```
+launchd  ──▶  skill/run-{platform}.sh  ──▶  claude -p  --strict-mcp-config  --mcp-config ~/.claude/browser-agent-configs/{platform}-agent-mcp.json
+                       │                                        │
+                       │                                        └──▶  @playwright/mcp@latest
+                       │                                                       │
+                       │                                                       └──▶  ~/.claude/browser-profiles/{platform}/  (persistent userDataDir)
+                       │
+                       ├──▶  scripts/find_{tweets,threads}.py  (no browser, API + DB dedup)
+                       ├──▶  scripts/pick_project.py            (weighted project rotation)
+                       ├──▶  scripts/top_performers.py          (feedback report from past stats)
+                       └──▶  Neon Postgres                      (DATABASE_URL in .env)
 ```
-SKILL.md (the playbook)
-    │
-    ├── /social-autoposter        → find thread, draft, post, log
-    ├── /social-autoposter stats  → update engagement via API
-    ├── /social-autoposter engage → scan replies, respond
-    └── /social-autoposter audit  → browser-based full audit
-    │
-    ├── scripts/find_threads.py   → thread discovery (no browser)
-    ├── scripts/scan_replies.py   → reply scanning (no browser)
-    └── scripts/update_stats.py   → stats fetching (no browser)
-    │
-    ├── skill/run.sh              → launchd wrapper (hourly)
-    ├── skill/stats.sh            → launchd wrapper (6-hourly)
-    └── skill/engage.sh           → launchd wrapper (2-hourly)
+
+Each `skill/run-*.sh`:
+
+1. Controlled by launchd (load/unload). Use the dashboard Pause All / Resume All button, or `launchctl unload/load` directly
+2. Acquires a per-platform lock from `skill/lock.sh` (waits up to 60 min for any prior run)
+3. Sources `~/social-autoposter/.env`
+4. Picks a project, builds a feedback report, fetches `llms.txt` for product context
+5. Calls `find_*.py` for API-side candidates already deduped against the DB
+6. Spawns a child Claude process with `--strict-mcp-config` so it only sees the one platform's browser MCP
+
+The launchd schedules from `bin/cli.js`:
+
+| Job | Cadence |
+|-----|---------|
+| `com.m13v.social-autoposter` (`run.sh`) | every 3600 s (hourly) |
+| `com.m13v.social-stats` (`stats.sh`) | every 21600 s (6 h) |
+| `com.m13v.social-engage` (`engage.sh`) | every 21600 s (6 h) |
+
+Per-platform plists in `launchd/` (twitter, reddit, linkedin, moltbook, github, octolens, audit, dm-replies, scan-replies, etc.) use either `StartInterval` or `StartCalendarInterval` for fixed wall-clock times. Activate them with:
+
+```bash
+ln -sf ~/social-autoposter/launchd/com.m13v.social-twitter.plist ~/Library/LaunchAgents/
+launchctl load ~/Library/LaunchAgents/com.m13v.social-twitter.plist
 ```
 
-## Structure
+## Skill commands
+
+| Command | What it does |
+|---------|-------------|
+| `/social-autoposter` | Comment run: find threads, draft, post, log (cron-safe) |
+| `/social-autoposter post` | Create an original post or thread (manual only) |
+| `/social-autoposter stats` | Update engagement stats via API |
+| `/social-autoposter engage` | Scan and reply to responses on our posts |
+| `/social-autoposter audit` | Full browser audit of all posts |
+
+View live stats at `https://s4l.ai/stats/<your-handle>` once posts start landing in Neon.
+
+## Repo layout
 
 ```
 social-autoposter/
-├── SKILL.md               <- skill playbook (generic, publishable)
-├── config.example.json    <- config template (accounts, subreddits, content angle)
-├── schema-postgres.sql    <- Neon Postgres DB schema
-├── setup.sh               <- creates symlinks, loads launchd agents
-├── setup/
-│   └── SKILL.md           <- interactive setup wizard skill
-├── scripts/
-│   ├── db.py              <- Neon Postgres connection wrapper
-│   ├── find_threads.py    <- find candidate threads via Reddit/Moltbook API
-│   ├── scan_replies.py    <- scan for new replies to our posts via API
-│   └── update_stats.py    <- fetch engagement stats via API
-├── skill/
-│   ├── SKILL.md           <- personal skill (hardcoded accounts)
-│   ├── run.sh             <- hourly posting (launchd wrapper)
-│   ├── stats.sh           <- 6-hourly stats (launchd wrapper)
-│   ├── engage.sh          <- 2-hourly engagement (launchd wrapper)
-│   └── logs/              <- runtime logs (gitignored)
-└── launchd/               <- macOS LaunchAgent plists
+├── SKILL.md                  the playbook (locked, immutable)
+├── bin/cli.js                installer + dashboard launcher
+├── browser-agent-configs/    Playwright MCP templates (twitter/reddit/linkedin)
+├── config.example.json       config template
+├── schema-postgres.sql       Neon schema
+├── setup/SKILL.md            interactive setup wizard skill (locked)
+├── scripts/                  Python and JS helpers (no browser, no LLM)
+├── skill/                    shell wrappers invoked by launchd
+└── launchd/                  generated macOS LaunchAgent plists
 ```
 
 ## For other AI agents
 
-The skill is designed to work with any agent that has:
-- **Shell access** (to run Python scripts and psql)
-- **Browser automation** (Playwright, Selenium, etc. for posting)
-- **An LLM** (for drafting comments in the right tone)
+The skill works with any agent that has shell access, browser automation, and an LLM. The Python and JS helpers in `scripts/` handle thread discovery, reply scanning, and stats updates without needing a browser. `SKILL.md` is the playbook; any agent can read it and execute the workflows with its own tools.
 
-The Python scripts handle thread discovery, reply scanning, and stats updates without needing a browser or LLM. The SKILL.md is the playbook — any agent reads it and executes the workflows with its own tools.
+## Pause and resume
 
-## Accounts
+Use the dashboard at `localhost:3141` (Pause All / Resume All button), or manually:
 
-- **Reddit**: u/Deep_Ad1959
-- **X/Twitter**: @m13v_
-- **LinkedIn**: Matthew Diakonov
-- **Moltbook**: matthew-autoposter
+```bash
+# Pause: unload all jobs + kill running processes
+for plist in ~/Library/LaunchAgents/com.m13v.social-*.plist; do launchctl unload "$plist"; done
+
+# Resume: reload all jobs
+for plist in ~/social-autoposter/launchd/com.m13v.social-*.plist; do
+  ln -sf "$plist" ~/Library/LaunchAgents/
+  launchctl load ~/Library/LaunchAgents/$(basename "$plist")
+done
+```

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: social-autoposter
-description: "Automate social media posting across Reddit, X/Twitter, LinkedIn, and Moltbook. Find threads, post comments, create original posts, track engagement stats. Use when: 'post to social', 'social autoposter', 'find threads to comment on', 'create a post', 'audit social posts', 'update post stats', or after completing any task (mandatory per CLAUDE.md)."
+description: "Automate social media posting across Reddit, X/Twitter, LinkedIn, and Moltbook. Find threads, post comments, create original posts, track engagement stats. Use when: 'post to social', 'social autoposter', 'find threads to comment on', 'create a post', 'audit social posts', 'update post stats'."
 user_invocable: true
 ---
 
@@ -13,7 +13,7 @@ Automates finding, posting, and tracking social media comments and original post
 | Command | What it does |
 |---------|-------------|
 | `/social-autoposter` | Comment run — find threads + post comment + log (cron-safe) |
-| `/social-autoposter post` | Create an original post/thread (manual only, never cron) |
+| `/social-autoposter post` | Create an original post/thread (manual or cron-driven for Reddit threads) |
 | `/social-autoposter stats` | Update engagement stats via API |
 | `/social-autoposter engage` | Scan and reply to responses on our posts |
 | `/social-autoposter audit` | Full browser audit of all posts |
@@ -121,15 +121,17 @@ Verify: fetch post by UUID, check `verification_status` is `"verified"`.
 ```sql
 INSERT INTO posts (platform, thread_url, thread_author, thread_author_handle,
   thread_title, thread_content, our_url, our_content, our_account,
-  source_summary, project_name, status, posted_at)
-VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, 'active', NOW());
+  source_summary, project_name, engagement_style, feedback_report_used, status, posted_at)
+VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, TRUE, 'active', NOW());
 ```
 
 Set `project_name` to the matching project name from `config.json` (e.g., 'Fazm', 'Cyrano', 'Terminator'). Every post/comment MUST be labeled with its target project. If engagement is general/unrelated to any project, use 'general'.
 
+Set `engagement_style` to the style you chose for this post (e.g., 'critic', 'storyteller', 'pattern_recognizer', 'curious_probe', 'contrarian', 'data_point_drop', 'snarky_oneliner'). Every post MUST have an engagement_style.
+
 Use the account value from `config.json` for `our_account`.
 
-If `sync_script` is set in config.json, run it after logging.
+Posts are written directly to the Neon Postgres database. No separate post-sync step is required.
 
 ---
 
@@ -176,10 +178,12 @@ Choose the single best subreddit from `config.json → subreddits` for this topi
 ```sql
 INSERT INTO posts (platform, thread_url, thread_author, thread_author_handle,
   thread_title, thread_content, our_url, our_content, our_account,
-  source_summary, project_name, status, posted_at)
-VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, 'active', NOW());
+  source_summary, project_name, engagement_style, feedback_report_used, status, posted_at)
+VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, TRUE, 'active', NOW());
 ```
 
+Set `engagement_style` to the style you chose (e.g., 'critic', 'storyteller', 'pattern_recognizer'). Every post MUST have an engagement_style.
+
 Set `project_name` to the matching project name from `config.json`. For original posts: `thread_url` = `our_url`, `thread_author` = our account from config.json.
 
 ### 6. Mandatory engagement plan
@@ -192,13 +196,39 @@ After posting, you MUST:
 
 ---
 
+## Workflow: Cron-driven Reddit Threads (`run-reddit-threads.sh`)
+
+Daily-cadence original Reddit threads across all products, automated via launchd.
+
+**Config lives per-project** under `projects[].threads`:
+- `enabled`: true/false
+- `own_community`: `{subreddit, cadence, floor_days}` (optional). Defaults to 1-day floor.
+- `external_subreddits`: list of external subs (default 3-day floor, override via `external_floor_days`)
+- `topic_angles`: discussion-starter ideas the agent picks from
+- `voice_notes`: per-thread voice guidance on top of `projects[].voice`
+- `content_sources.guide_dir` / `link_base`: optional source paths/URLs
+- `dynamic_context.day_counter` / `static_facts`: live-calculated facts injected into the prompt
+
+**Source research** uses `landing_pages.repo` + `landing_pages.product_source[]` (same schema as the SEO pipeline). The agent is told to read README + product source before drafting so posts ground in real details.
+
+**Picker** (`scripts/pick_thread_target.py`): weighted project selection with:
+- Per-sub floor-days filter (queries `posts` table for this account's last original thread)
+- `banned_subreddits` filter (top-level config, all groups flattened)
+- Own-community candidates always picked first when eligible
+
+**Schedule**: `com.m13v.social-reddit-threads.plist` fires 4x/day at 00:15, 06:15, 12:15, 18:15.
+
+**Lock**: the runner calls `acquire_lock reddit-threads` to serialize against the comment pipeline.
+
+---
+
 ## Workflow: Stats (`/social-autoposter stats`)
 
 ```bash
 python3 ~/social-autoposter/scripts/update_stats.py
 ```
 
-After running, view updated stats at `https://s4l.ai/stats/[handle]`. The DB syncs to Neon Postgres via `syncfield.sh` (called automatically by `stats.sh`). Changes appear on the website within ~5 minutes.
+After running, view updated stats at `https://s4l.ai/stats/[handle]`. Stats are read from the same Neon Postgres database used by the posting pipeline. Changes appear on the website within ~5 minutes.
 
 ---
 

package/bin/cli.js

@@ -19,11 +19,24 @@ const COPY_TARGETS = [
   'SKILL.md',
   'skill',
   'setup',
+  'browser-agent-configs',
 ];
 
 // Never overwrite these user files during update
 const USER_FILES = new Set(['config.json', '.env', 'SKILL.md']);
 
+// Browser agent config templates -> install path under ~/.claude/browser-agent-configs/
+const BROWSER_AGENT_CONFIGS = [
+  'twitter-agent-mcp.json',
+  'twitter-agent.json',
+  'reddit-agent-mcp.json',
+  'reddit-agent.json',
+  'linkedin-agent-mcp.json',
+  'linkedin-agent.json',
+];
+
+const BROWSER_PROFILES = ['twitter', 'reddit', 'linkedin'];
+
 function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
@@ -42,6 +55,40 @@ function linkOrRelink(target, linkPath) {
   fs.symlinkSync(target, linkPath);
 }
 
+function installBrowserAgentConfigs() {
+  const nodeBin = path.dirname(process.execPath);
+  const srcDir = path.join(PKG_ROOT, 'browser-agent-configs');
+  const destDir = path.join(HOME, '.claude', 'browser-agent-configs');
+  fs.mkdirSync(destDir, { recursive: true });
+
+  let installed = 0;
+  let skipped = 0;
+  for (const name of BROWSER_AGENT_CONFIGS) {
+    const src = path.join(srcDir, name);
+    const dest = path.join(destDir, name);
+    if (!fs.existsSync(src)) continue;
+    if (fs.existsSync(dest)) {
+      skipped++;
+      continue;
+    }
+    const tpl = fs.readFileSync(src, 'utf8');
+    const out = tpl
+      .replace(/__HOME__/g, HOME)
+      .replace(/__NODE_BIN__/g, nodeBin);
+    fs.writeFileSync(dest, out);
+    installed++;
+  }
+  console.log(`  browser agent configs -> ${destDir} (installed ${installed}, skipped ${skipped} existing)`);
+
+  // Create empty persistent profile dirs so Playwright has somewhere to land cookies
+  const profilesDir = path.join(HOME, '.claude', 'browser-profiles');
+  fs.mkdirSync(profilesDir, { recursive: true });
+  for (const p of BROWSER_PROFILES) {
+    fs.mkdirSync(path.join(profilesDir, p), { recursive: true });
+  }
+  console.log(`  browser profile dirs ready -> ${profilesDir}/{${BROWSER_PROFILES.join(',')}}`);
+}
+
 function generatePlists() {
   // Detect PATH for launchd (include node, homebrew, system)
   const nodeBin = path.dirname(process.execPath);
@@ -128,6 +175,9 @@ function init() {
   // Generate launchd plists with user's actual HOME
   generatePlists();
 
+  // Install browser agent MCP configs + profile dirs (skips existing files)
+  installBrowserAgentConfigs();
+
   // config.json — only if it doesn't exist
   const configDest = path.join(DEST, 'config.json');
   if (!fs.existsSync(configDest)) {
@@ -209,6 +259,9 @@ function update() {
   // Regenerate launchd plists with correct paths
   generatePlists();
 
+  // Top up browser agent configs (won't overwrite user customizations)
+  installBrowserAgentConfigs();
+
   // Remove stale skill/SKILL.md if it exists (SKILL.md lives at repo root only)
   const skillMd = path.join(DEST, 'skill', 'SKILL.md');
   try { fs.rmSync(skillMd, { force: true }); } catch {}