social-autoposter 1.1.3 → 1.3.0

package/README.md

@@ -1,84 +1,139 @@
 # 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 Neon Postgres database via `DATABASE_URL` in `~/social-autoposter/.env`. Bring your own Neon DB and apply `schema-postgres.sql` once. 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 writes a blank `.env` template (fill in your own `DATABASE_URL` and optional `MOLTBOOK_API_KEY`)
+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_threads.py, top_twitter_queries.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 generated by `bin/cli.js` on install:
+
+| Job | Cadence |
+|-----|---------|
+| `com.m13v.social-stats` (`stats.sh`) | every 21600 s (6 h) |
+| `com.m13v.social-engage` (`engage.sh`) | every 21600 s (6 h) |
+
+All per-platform plists live in `launchd/` (reddit-search, reddit-threads, twitter-cycle, linkedin, moltbook, github, octolens, audit, dm-replies-*, link-edit-*, scan-reddit-replies, scan-moltbook-replies, etc.) and use either `StartInterval` or `StartCalendarInterval` for fixed wall-clock times. Activate any of them with:
+
+```bash
+ln -sf ~/social-autoposter/launchd/com.m13v.social-twitter-cycle.plist ~/Library/LaunchAgents/
+launchctl load ~/Library/LaunchAgents/com.m13v.social-twitter-cycle.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 |
@@ -53,7 +53,8 @@ Standalone Python scripts — no LLM needed.
 
 ```bash
 python3 ~/social-autoposter/scripts/find_threads.py --include-moltbook
-python3 ~/social-autoposter/scripts/scan_replies.py
+python3 ~/social-autoposter/scripts/scan_reddit_replies.py
+python3 ~/social-autoposter/scripts/scan_moltbook_replies.py
 python3 ~/social-autoposter/scripts/update_stats.py --quiet
 ```
 
@@ -121,15 +122,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 +179,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 +197,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 guidance comes from `projects[].voice` (tone, never)
+- `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)
+- `subreddit_bans` filter: `banned` (can't post or comment) + `skip_threads` (threads blocked, comments OK)
+- 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.
 
 ---
 
@@ -206,7 +237,8 @@ After running, view updated stats at `https://s4l.ai/stats/[handle]`. The DB syn
 
 ### Phase A: Scan for replies (no browser)
 ```bash
-python3 ~/social-autoposter/scripts/scan_replies.py
+python3 ~/social-autoposter/scripts/scan_reddit_replies.py
+python3 ~/social-autoposter/scripts/scan_moltbook_replies.py
 ```
 
 ### Phase B: Respond to pending replies
@@ -275,6 +307,22 @@ GOOD title: "just did my 7th course, some things that surprised me"
 BAD body: Structured with headers, bold, numbered lists, "As a tech founder..."
 GOOD body: Paragraphs, incomplete thoughts, personal details, casual tone, ends with a genuine question
 
+### Bad vs Good (DM Replies)
+
+DM replies are texting-style. 1 to 3 sentences. Always reference something specific from the inbound. No unearned call offers, no fabricated links, no time-bound commitments. Booking links only when the matched project has `booking_link_auto_share: true` AND `qualification_status=qualified` on the DM row.
+
+BAD: "Hey! I saw your comment on r/startups about agent orchestration. I'd love to share what we're working on, would you be open to a quick call?" (cold-pitch shape, premature call ask)
+GOOD: "yo the point about agents racing on the same file hit home, we solved it with worktrees per agent. what's your setup?"
+
+BAD: "Great question! Our product handles exactly that scenario. Check out [link] for more details." (sales register, leading with link in an early DM)
+GOOD: "we hit that too, ended up using the accessibility API route because screenshot-based kept flaking on retina displays"
+
+BAD: "Absolutely! Let's do Thursday at 3pm, I'll send an invite." (time-bound commitment, bot has no calendar authority)
+GOOD: "yeah easier to figure it out here, what specifically are you trying to wire up?"
+
+BAD: "I totally understand your hesitation. But our solution is different because..." (defensive, pushy rebuttal)
+GOOD: "makes sense, we kicked it around for 6 months before pulling the trigger. what's been the blocker on your end?"
+
 ---
 
 ## Tiered Reply Strategy

package/bin/auth.js

@@ -0,0 +1,110 @@
+'use strict';
+
+// Firebase auth for the dashboard when CLIENT_MODE=1.
+// When CLIENT_MODE is unset (local operator use), authorize() is a no-op
+// and returns a synthetic admin principal so every existing route keeps
+// working unchanged.
+
+let _admin = null;
+
+function getAdmin() {
+  if (_admin) return _admin;
+  const admin = require('firebase-admin');
+  if (!admin.apps.length) {
+    const projectId = process.env.FIREBASE_PROJECT_ID || 's4l-app-prod';
+    admin.initializeApp({ projectId });
+  }
+  _admin = admin;
+  return _admin;
+}
+
+const CLIENT_MODE = process.env.CLIENT_MODE === '1';
+
+// Routes that require an admin claim even when authenticated.
+// Clients authenticated with only a project scope cannot hit these.
+const ADMIN_ONLY_PATTERNS = [
+  /^\/api\/pause$/,
+  /^\/api\/resume$/,
+  /^\/api\/jobs\/[^/]+\/(toggle|run|stop|interval)$/,
+  /^\/api\/phase\/[^/]+\/interval$/,
+  /^\/api\/config$/,
+  /^\/api\/env$/,
+  /^\/api\/logs(\/.*)?$/,
+  /^\/api\/webhooks(\/.*)?$/,
+  /^\/api\/status$/,
+  /^\/api\/pending$/,
+];
+
+function isAdminOnly(pathname) {
+  return ADMIN_ONLY_PATTERNS.some(re => re.test(pathname));
+}
+
+function extractToken(req) {
+  const h = req.headers['authorization'] || req.headers['Authorization'];
+  if (!h) return null;
+  const m = String(h).match(/^Bearer\s+(.+)$/);
+  return m ? m[1].trim() : null;
+}
+
+async function verifyAuth(req, pathname) {
+  if (!CLIENT_MODE) {
+    return { ok: true, user: { uid: 'local', email: 'local', admin: true, projects: [] } };
+  }
+  const token = extractToken(req);
+  if (!token) {
+    console.warn(JSON.stringify({ event: 'auth_reject', reason: 'missing_token', path: pathname, authHeaderPresent: !!(req.headers['authorization'] || req.headers['Authorization']) }));
+    return { ok: false, status: 401, error: 'missing_token' };
+  }
+  try {
+    const decoded = await getAdmin().auth().verifyIdToken(token);
+    const user = {
+      uid: decoded.uid,
+      email: decoded.email || null,
+      admin: decoded.admin === true,
+      projects: Array.isArray(decoded.projects) ? decoded.projects : [],
+    };
+    if (isAdminOnly(pathname) && !user.admin) {
+      console.warn(JSON.stringify({ event: 'auth_reject', reason: 'admin_required', path: pathname, uid: user.uid, email: user.email }));
+      return { ok: false, status: 403, error: 'admin_required' };
+    }
+    return { ok: true, user };
+  } catch (e) {
+    console.warn(JSON.stringify({ event: 'auth_reject', reason: 'invalid_token', path: pathname, errCode: e.code || null, errMessage: e.message, tokenHead: token.slice(0, 20), tokenLen: token.length }));
+    return { ok: false, status: 401, error: 'invalid_token', detail: e.message };
+  }
+}
+
+function scopedProjects(user, requested) {
+  if (user.admin) {
+    return requested && requested !== 'all' ? [requested] : null;
+  }
+  if (!user.projects.length) return [];
+  if (!requested || requested === 'all') return user.projects.slice();
+  return user.projects.includes(requested) ? [requested] : [];
+}
+
+// Returns { clause, ok } where clause is a " AND <column> IN ('a','b')" fragment
+// (possibly empty when admin + no filter) and ok=false means the user has no
+// access (non-admin with empty projects claim) so the handler should 403.
+// Project names are validated against a conservative charset; single quotes
+// are also SQL-escaped below as defense in depth. Spaces are allowed because
+// real config.json names include them ('WhatsApp MCP', 'AI Browser Profile',
+// 'macOS MCP', 'macOS Session Replay').
+const PROJECT_NAME_RE = /^[A-Za-z0-9 _\-]{1,64}$/;
+
+function projectClause(user, column, requested) {
+  const list = scopedProjects(user, requested);
+  if (list === null) return { clause: '', ok: true }; // admin, unfiltered
+  const safe = list.filter(p => PROJECT_NAME_RE.test(p));
+  if (!safe.length) return { clause: '', ok: false };
+  const quoted = safe.map(p => `'${p.replace(/'/g, "''")}'`).join(',');
+  return { clause: ` AND ${column} IN (${quoted})`, ok: true, list: safe };
+}
+
+module.exports = {
+  CLIENT_MODE,
+  verifyAuth,
+  isAdminOnly,
+  scopedProjects,
+  projectClause,
+};