heyhank 0.1.0 → 0.2.0

package/server/socialview/types.ts

@@ -0,0 +1,166 @@
+// ─── SocialView Types ────────────────────────────────────────────────────────
+// Browser-based social media viewing tool. User logs in manually via noVNC,
+// backend uses Playwright to navigate and extract posts on command.
+
+export type SocialPlatform =
+  | "instagram"
+  | "twitter"
+  | "linkedin"
+  | "facebook"
+  | "tiktok";
+
+export const SOCIAL_PLATFORMS: SocialPlatform[] = [
+  "instagram",
+  "twitter",
+  "linkedin",
+  "facebook",
+  "tiktok",
+];
+
+/** URLs the browser navigates to when opening a platform (login page or feed). */
+export const PLATFORM_URLS: Record<SocialPlatform, string> = {
+  instagram: "https://www.instagram.com/",
+  twitter: "https://x.com/home",
+  linkedin: "https://www.linkedin.com/feed/",
+  facebook: "https://www.facebook.com/",
+  tiktok: "https://www.tiktok.com/",
+};
+
+export interface SocialViewStatus {
+  platform: SocialPlatform;
+  running: boolean;
+  /** Heuristic: true if current URL suggests user is logged in (not on login page). */
+  loggedIn: boolean | null;
+  currentUrl: string | null;
+  startedAt: number | null;
+}
+
+/** A single post captured into the reference library — used as few-shot
+ *  examples when the content agent generates new posts. */
+export interface LibraryPost {
+  id: string;
+  platform: SocialPlatform;
+  /** "own" = Markus's accounts, "role-model" = other top performers we learn from. */
+  source: "own" | "role-model";
+  url: string;
+  author: {
+    handle: string;
+    displayName?: string;
+    followers?: number;
+    verified?: boolean;
+  };
+  text: string;
+  /** First 1–2 sentences isolated — the opening hook. */
+  hook: string;
+  /** Detected call-to-action (question, link, imperative). Null if none detected. */
+  cta: string | null;
+  hashtags: string[];
+  mentions: string[];
+  media: Array<{
+    type: "image" | "video";
+    localPath: string | null;
+    remoteUrl: string | null;
+    /** Claude Vision description of the image/video frame. */
+    description: string;
+  }>;
+  engagement: {
+    likes: number | null;
+    comments: number | null;
+    shares: number | null;
+    views: number | null;
+    saves: number | null;
+  };
+  /** (likes + comments + shares) / followers. Used for quality filtering. */
+  engagementRate: number | null;
+  postType: "image" | "carousel" | "reel" | "video" | "text" | "unknown";
+  postedAt: string | null;
+  /** Manual tags set by user. */
+  tags: string[];
+  /** Marked as gold standard after manual review. Only "gold" posts feed the agent. */
+  isGold: boolean;
+  /** When we captured this record. */
+  extractedAt: string;
+  notes: string;
+}
+
+export interface LibraryQuery {
+  platform?: SocialPlatform;
+  source?: "own" | "role-model";
+  goldOnly?: boolean;
+  minEngagementRate?: number;
+  tags?: string[];
+  limit?: number;
+}
+
+/**
+ * Distilled writing-style profile derived from all library posts of a single
+ * handle. Used as an "instruction block" in the content-generation prompt so
+ * the agent writes in the role-model's voice without us having to ship 5+ raw
+ * example posts every time (token-efficient + interpretable).
+ *
+ * One profile per (platform, handle). Saved at:
+ *   ~/.heyhank/socialview/style-profiles/<platform>-<handle>.json
+ */
+export interface StyleProfile {
+  id: string;
+  platform: SocialPlatform;
+  handle: string;
+  displayName: string;
+
+  /** How many library posts the profile was distilled from. */
+  basedOnPostCount: number;
+  /** Library post IDs used in the analysis (for re-runs / audit). */
+  basedOnPostIds: string[];
+
+  /** Avg word count across analyzed posts. */
+  averageWordCount: number;
+  /** Coarse length descriptor — useful as a one-word hint to the LLM. */
+  lengthCategory: "kompakt" | "mittel" | "lang";
+
+  /** Common opening-hook patterns and their relative frequency [0..1]. */
+  hookPatterns: Array<{
+    type: string;
+    frequency: number;
+    examples: string[];
+  }>;
+
+  /** Common closing/CTA patterns and frequency. */
+  ctaPatterns: Array<{
+    type: string;
+    frequency: number;
+    examples: string[];
+  }>;
+
+  emojiStyle: "keine" | "sparsam" | "moderat" | "dicht";
+  /** Frequently used emojis (most-common first). */
+  emojiList: string[];
+
+  hashtagStyle: "keine" | "wenige" | "viele";
+
+  /** High-level content themes the handle posts about. */
+  contentPillars: string[];
+
+  /** Free-form description of voice/tone. */
+  toneOfVoice: string;
+
+  /**
+   * Engagement strategy observed in the post-author's own comments under
+   * their posts. Captures patterns like "antwortet mit Frage zurück" or
+   * "ergänzt CTA in erstem Eigenkommentar". May be empty if no own-comments
+   * were extracted.
+   */
+  commentEngagementPattern: string;
+
+  /**
+   * Synthesis of the visual style across all analyzed posts: composition,
+   * color palette, recurring overlay patterns, production quality. Distilled
+   * from the per-post image descriptions. Empty string if no images present.
+   */
+  visualStyle: string;
+
+  /** Full LLM analysis as prose — for transparency / manual editing. */
+  rawAnalysis: string;
+
+  createdAt: string;
+  updatedAt: string;
+}

package/server/socialview/vision.ts

@@ -0,0 +1,127 @@
+// ─── Claude Vision for post images ───────────────────────────────────────────
+// Thin wrapper around the Anthropic Messages API with an image input. Used to
+// describe the visual style of reference posts so the content agent can learn
+// what "high visual quality" looks like per platform.
+
+import { getSettings } from "../settings-manager.js";
+
+const VISION_MODEL = "claude-sonnet-4-6";
+const VISION_MAX_TOKENS = 512;
+
+/** Prompt focused on the things the content agent actually needs to reproduce. */
+const DESCRIBE_PROMPT = `Describe this social media post image for a content agent that needs to learn what works visually.
+
+Cover (in 3–5 concise bullet points, under 120 words total):
+- Subject & composition (what's in frame, how it's arranged)
+- Color palette & mood (warm/cool, saturated/muted, dominant colors)
+- Text overlays if any (quote them verbatim)
+- Style (flatlay, portrait, candid, stock-ish, UGC, studio, meme, infographic)
+- Production quality signals (natural light, shallow depth of field, brand consistency)
+
+No preamble, just the bullets.`;
+
+function resolveAnthropicKey(): string | null {
+  const s = getSettings();
+  const key = (s.anthropicApiKey as string | undefined)?.trim();
+  return key || null;
+}
+
+/** Describe an image at an HTTP(S) URL via Claude Vision. Returns empty string on failure. */
+export async function describeImageByUrl(url: string, timeoutMs = 30_000): Promise<string> {
+  const apiKey = resolveAnthropicKey();
+  if (!apiKey) {
+    // eslint-disable-next-line no-console
+    console.warn("[socialview/vision] no anthropicApiKey configured — skipping vision");
+    return "";
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const res = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+      },
+      body: JSON.stringify({
+        model: VISION_MODEL,
+        max_tokens: VISION_MAX_TOKENS,
+        messages: [
+          {
+            role: "user",
+            content: [
+              { type: "image", source: { type: "url", url } },
+              { type: "text", text: DESCRIBE_PROMPT },
+            ],
+          },
+        ],
+      }),
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      // eslint-disable-next-line no-console
+      console.warn(`[socialview/vision] ${res.status} ${res.statusText}`);
+      return "";
+    }
+
+    const data = (await res.json()) as { content?: Array<{ type: string; text?: string }> };
+    const text = data.content?.find((b) => b.type === "text")?.text ?? "";
+    return text.trim();
+  } catch (e) {
+    // eslint-disable-next-line no-console
+    console.warn("[socialview/vision] error:", e instanceof Error ? e.message : e);
+    return "";
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Describe an image from a base64 string. Useful when we download the file locally. */
+export async function describeImageBase64(
+  base64Data: string,
+  mediaType: "image/jpeg" | "image/png" | "image/webp" | "image/gif",
+  timeoutMs = 30_000,
+): Promise<string> {
+  const apiKey = resolveAnthropicKey();
+  if (!apiKey) return "";
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const res = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+      },
+      body: JSON.stringify({
+        model: VISION_MODEL,
+        max_tokens: VISION_MAX_TOKENS,
+        messages: [
+          {
+            role: "user",
+            content: [
+              { type: "image", source: { type: "base64", media_type: mediaType, data: base64Data } },
+              { type: "text", text: DESCRIBE_PROMPT },
+            ],
+          },
+        ],
+      }),
+      signal: controller.signal,
+    });
+
+    if (!res.ok) return "";
+    const data = (await res.json()) as { content?: Array<{ type: string; text?: string }> };
+    return (data.content?.find((b) => b.type === "text")?.text ?? "").trim();
+  } catch {
+    return "";
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/server/socialview/vnc-manager.ts

@@ -0,0 +1,110 @@
+// ─── VNC Manager ─────────────────────────────────────────────────────────────
+// Runs x11vnc attached to Xvfb :99, and websockify serving noVNC on
+// 127.0.0.1:6080. Nginx proxies /socialview/vnc/ to this port, so the frontend
+// can iframe the noVNC client.
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createConnection } from "node:net";
+
+const VNC_DISPLAY = ":99";
+const VNC_PORT = 5900;
+const WEBSOCKIFY_PORT = 6080;
+const NOVNC_WEB_ROOT = "/usr/share/novnc";
+
+let x11vncProc: ChildProcess | null = null;
+let websockifyProc: ChildProcess | null = null;
+
+function isAlive(p: ChildProcess | null): boolean {
+  return !!p && !p.killed && p.exitCode === null;
+}
+
+/** Probe a local TCP port — more reliable than tracking ChildProcess when the
+ *  spawned daemon forks itself off (x11vnc does this). */
+function probePort(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const sock = createConnection({ host: "127.0.0.1", port }, () => {
+      sock.end();
+      resolve(true);
+    });
+    sock.on("error", () => resolve(false));
+    sock.setTimeout(500, () => {
+      sock.destroy();
+      resolve(false);
+    });
+  });
+}
+
+/** Start x11vnc + websockify if not running. Idempotent. */
+export async function ensureVnc(): Promise<void> {
+  if (!existsSync(NOVNC_WEB_ROOT)) {
+    // eslint-disable-next-line no-console
+    console.warn(`[socialview] noVNC not installed at ${NOVNC_WEB_ROOT}; VNC viewer disabled`);
+    return;
+  }
+
+  // Check actual port, not just ChildProcess handle, because x11vnc forks.
+  const x11vncUp = await probePort(VNC_PORT);
+  if (!x11vncUp && !isAlive(x11vncProc)) {
+    // eslint-disable-next-line no-console
+    console.log(`[socialview] starting x11vnc on display ${VNC_DISPLAY} port ${VNC_PORT}`);
+    x11vncProc = spawn(
+      "x11vnc",
+      [
+        "-display", VNC_DISPLAY,
+        "-rfbport", String(VNC_PORT),
+        "-localhost", // bind only to 127.0.0.1
+        "-forever",
+        "-shared",
+        "-nopw", // auth is enforced by nginx basic auth + heyhank token on the outer proxy
+        "-quiet",
+        "-noxdamage",
+      ],
+      { stdio: "ignore" },
+    );
+    x11vncProc.on("exit", (code) => {
+      // eslint-disable-next-line no-console
+      console.log(`[socialview] x11vnc exited with code ${code}`);
+      x11vncProc = null;
+    });
+  }
+
+  const wsUp = await probePort(WEBSOCKIFY_PORT);
+  if (!wsUp && !isAlive(websockifyProc)) {
+    // eslint-disable-next-line no-console
+    console.log(`[socialview] starting websockify on 127.0.0.1:${WEBSOCKIFY_PORT}`);
+    websockifyProc = spawn(
+      "websockify",
+      [
+        `127.0.0.1:${WEBSOCKIFY_PORT}`,
+        `127.0.0.1:${VNC_PORT}`,
+        `--web=${NOVNC_WEB_ROOT}`,
+      ],
+      { stdio: "ignore" },
+    );
+    websockifyProc.on("exit", (code) => {
+      // eslint-disable-next-line no-console
+      console.log(`[socialview] websockify exited with code ${code}`);
+      websockifyProc = null;
+    });
+  }
+
+  // Give processes a moment to bind.
+  await new Promise((r) => setTimeout(r, 300));
+}
+
+export async function getVncStatus(): Promise<{ x11vnc: boolean; websockify: boolean; port: number }> {
+  const [vncUp, wsUp] = await Promise.all([probePort(VNC_PORT), probePort(WEBSOCKIFY_PORT)]);
+  return { x11vnc: vncUp, websockify: wsUp, port: WEBSOCKIFY_PORT };
+}
+
+export async function shutdownVnc(): Promise<void> {
+  if (x11vncProc && !x11vncProc.killed) {
+    x11vncProc.kill();
+    x11vncProc = null;
+  }
+  if (websockifyProc && !websockifyProc.killed) {
+    websockifyProc.kill();
+    websockifyProc = null;
+  }
+}

package/server/style-injector.ts

@@ -0,0 +1,135 @@
+// ─── Persona Style Injector ──────────────────────────────────────────────────
+// Scans a free-text task description for known SocialView persona references
+// (display name or handle) and produces a binding "STIL-PROFIL"-block that
+// downstream agents (Content Agent etc.) can apply as hard rules.
+//
+// Used by `run_agent` executor to enrich the task automatically — neither
+// Hank nor the agent need to remember to load the profile.
+
+import { listProfiles } from "./socialview/style-profiles.js";
+import type { StyleProfile } from "./socialview/types.js";
+
+/**
+ * Find personas mentioned in `text`. A persona matches if its handle OR
+ * display-name (case-insensitive, multi-token) appears in the text.
+ * Returns the matched profiles, deduped, ordered by length of the matched
+ * token (longer = more specific match wins).
+ */
+function findMentionedPersonas(text: string): StyleProfile[] {
+  if (!text || !text.trim()) return [];
+  const haystack = text.toLowerCase();
+  const profiles = listProfiles();
+  const hits: Array<{ profile: StyleProfile; matchLen: number }> = [];
+  const seen = new Set<string>();
+
+  for (const p of profiles) {
+    const key = `${p.platform}:${p.handle.toLowerCase()}`;
+    if (seen.has(key)) continue;
+
+    const candidates: string[] = [];
+    if (p.handle) candidates.push(p.handle.toLowerCase());
+    if (p.displayName) {
+      const dn = p.displayName.toLowerCase().trim();
+      if (dn && dn !== p.handle.toLowerCase()) {
+        candidates.push(dn);
+        // Also try last-name only (e.g. "remsik" matches "rene remsik")
+        const tokens = dn.split(/\s+/).filter((t) => t.length >= 4);
+        if (tokens.length > 1) candidates.push(tokens[tokens.length - 1]!);
+      }
+    }
+
+    for (const c of candidates) {
+      // Word-boundary check so "rene" in "renewable" doesn't match.
+      const re = new RegExp(`\\b${c.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i");
+      if (re.test(haystack)) {
+        hits.push({ profile: p, matchLen: c.length });
+        seen.add(key);
+        break;
+      }
+    }
+  }
+
+  hits.sort((a, b) => b.matchLen - a.matchLen);
+  return hits.map((h) => h.profile);
+}
+
+/**
+ * Render a single profile as a markdown block with binding rules. Designed
+ * to be appended verbatim to an agent task so the LLM treats it as
+ * authoritative.
+ */
+function renderProfileBlock(p: StyleProfile): string {
+  const lines: string[] = [];
+  lines.push(`## STIL-PROFIL: ${p.displayName || p.handle} (@${p.handle} auf ${p.platform})`);
+  lines.push("");
+  lines.push("DIESE REGELN SIND BINDEND und überschreiben die Plattform-Defaults im System-Prompt:");
+  lines.push("");
+  lines.push(`- **Tonfall**: ${p.toneOfVoice || "(nicht spezifiziert)"}`);
+  lines.push(`- **Länge**: ${p.lengthCategory} (Ø ${p.averageWordCount} Wörter)`);
+  lines.push(`- **Hashtag-Stil**: ${p.hashtagStyle}${p.hashtagStyle === "keine" ? " — VERWENDE KEINE HASHTAGS, auch wenn der Plattform-Default welche vorschlägt" : ""}`);
+  lines.push(`- **Emoji-Stil**: ${p.emojiStyle}${p.emojiStyle === "keine" ? " — VERWENDE KEINE EMOJIS" : ""}`);
+
+  if (p.hookPatterns.length > 0) {
+    const top = p.hookPatterns.slice().sort((a, b) => b.frequency - a.frequency).slice(0, 3);
+    lines.push(`- **Bevorzugte Hooks** (verwende einen davon, NICHT die Standard-Hook-Liste):`);
+    for (const h of top) {
+      const ex = h.examples[0] ? ` — z.B. "${h.examples[0].slice(0, 100)}"` : "";
+      lines.push(`  - ${h.type}${ex}`);
+    }
+  }
+
+  if (p.ctaPatterns.length > 0) {
+    const top = p.ctaPatterns.slice().sort((a, b) => b.frequency - a.frequency).slice(0, 2);
+    lines.push(`- **CTA-Muster**:`);
+    for (const c of top) {
+      const ex = c.examples[0] ? ` — z.B. "${c.examples[0].slice(0, 100)}"` : "";
+      lines.push(`  - ${c.type}${ex}`);
+    }
+  }
+
+  if (p.contentPillars.length > 0) {
+    lines.push(`- **Content-Säulen**: ${p.contentPillars.join(", ")}`);
+  }
+
+  if (p.commentEngagementPattern && p.commentEngagementPattern.trim()) {
+    lines.push(`- **Eigenkommentar-Pattern**: ${p.commentEngagementPattern}`);
+  }
+
+  if (p.visualStyle && p.visualStyle.trim()) {
+    lines.push("");
+    lines.push("### Visueller Stil (für Bildgenerierung)");
+    lines.push(p.visualStyle);
+  }
+
+  if (p.rawAnalysis && p.rawAnalysis.trim()) {
+    lines.push("");
+    lines.push("### Gesamteinschätzung");
+    lines.push(p.rawAnalysis);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Public entry: given a task text, return a string that should be APPENDED
+ * to the task. Empty string if no persona is mentioned.
+ */
+export function buildStyleProfileBlockFromText(text: string): string {
+  const matches = findMentionedPersonas(text);
+  if (matches.length === 0) return "";
+  // Cap to top 2 to keep the prompt focused.
+  const blocks = matches.slice(0, 2).map(renderProfileBlock);
+  return [
+    "",
+    "---",
+    "",
+    "# AUTOMATISCH ERKANNTE PERSONA-REFERENZ",
+    "",
+    "Der User hat oben eine Persona genannt. Wende das folgende Profil als",
+    "BINDENDE Schreib- und Bildregel an. Die Profil-Regeln gewinnen IMMER",
+    "gegen die Plattform-Defaults im System-Prompt (z.B. Hashtag-Anzahl,",
+    "Hook-Liste, Emoji-Verwendung).",
+    "",
+    blocks.join("\n\n"),
+  ].join("\n");
+}