heyhank 0.1.0 → 0.2.0

package/server/socialview/image-describe.ts

@@ -0,0 +1,188 @@
+// ─── Image Description (via Claude Code Subscription) ───────────────────────
+// Downloads remote post images to ~/.heyhank/socialview/media/<postId>.<ext>
+// and feeds them to Claude Code's Read tool to produce a textual description.
+// Used to backfill `media[].description` for posts whose visual signal would
+// otherwise be missing from the persona analysis.
+
+import { spawn } from "node:child_process";
+import { mkdirSync, writeFileSync, existsSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { HEYHANK_HOME } from "../paths.js";
+import { savePost } from "./library.js";
+import type { LibraryPost } from "./types.js";
+
+const MEDIA_ROOT = join(HEYHANK_HOME, "socialview", "media");
+
+const DESCRIBE_PROMPT = `Beschreibe dieses Social-Media-Post-Bild für einen Content-Agent (3-5 prägnante Bullets, unter 120 Wörter total):
+- Motiv & Komposition (was ist im Bild, wie ist es arrangiert)
+- Farbpalette & Stimmung (warm/kühl, gesättigt/gedämpft, dominante Farben)
+- Text-Overlays falls vorhanden (wörtlich zitieren)
+- Stil (flatlay, portrait, candid, stock-ish, UGC, studio, meme, infographic)
+- Produktionsqualität-Signale (natürliches Licht, Tiefenschärfe, Markenkonsistenz)
+
+Nur die Bullets, kein Vorwort.`;
+
+/** Download a remote image to local disk. Returns the local path or null on failure. */
+async function downloadImage(url: string, postId: string, idx: number): Promise<string | null> {
+  try {
+    mkdirSync(MEDIA_ROOT, { recursive: true });
+    const safeId = postId.replace(/[^a-z0-9._-]/gi, "_");
+    const ext = guessExtension(url);
+    const localPath = join(MEDIA_ROOT, `${safeId}-${idx}.${ext}`);
+
+    if (existsSync(localPath) && statSync(localPath).size > 0) {
+      return localPath;
+    }
+
+    const res = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+    if (!res.ok) return null;
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.length === 0) return null;
+    writeFileSync(localPath, buf);
+    return localPath;
+  } catch {
+    return null;
+  }
+}
+
+function guessExtension(url: string): string {
+  try {
+    const path = new URL(url).pathname.toLowerCase();
+    if (path.endsWith(".png")) return "png";
+    if (path.endsWith(".webp")) return "webp";
+    if (path.endsWith(".gif")) return "gif";
+    return "jpg";
+  } catch {
+    return "jpg";
+  }
+}
+
+/** Spawn `claude -p` with Read enabled, point it at the image, capture stdout. */
+function describeImageViaClaudeCode(imagePath: string, timeoutMs = 90_000): Promise<string> {
+  return new Promise((resolve) => {
+    const childEnv: Record<string, string | undefined> = { ...process.env, NO_COLOR: "1" };
+    delete childEnv.CLAUDECODE;
+    delete childEnv.CLAUDE_CODE_ENTRYPOINT;
+
+    // Pre-approve Read via the settings glob pattern (Read(*)). The plain
+    // `--tools "Read"` enables Read but still demands interactive permission,
+    // which blocks under root (where --dangerously-skip-permissions is denied).
+    const args = [
+      "-p",
+      "--allowedTools", "Read(*)",
+      "--add-dir", dirname(imagePath),
+      "--no-session-persistence",
+      "--model", "sonnet",
+      `${DESCRIBE_PROMPT}\n\nLies das Bild unter: ${imagePath}`,
+    ];
+
+    let child;
+    try {
+      child = spawn("claude", args, {
+        env: childEnv,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch {
+      resolve("");
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    child.stdout.on("data", (d) => { stdout += d.toString(); });
+    child.stderr.on("data", (d) => { stderr += d.toString(); });
+
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill("SIGKILL");
+      resolve("");
+    }, timeoutMs);
+
+    child.on("error", () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve("");
+    });
+
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (code === 0) {
+        resolve(stdout.trim());
+      } else {
+        // eslint-disable-next-line no-console
+        console.warn(`[image-describe] claude exit ${code}:`, stderr.slice(-200));
+        resolve("");
+      }
+    });
+  });
+}
+
+/**
+ * For each post with image media that has empty description, download the image
+ * (if not already cached) and describe it via Claude Code. Mutates the posts
+ * in-place AND persists the updated post to library disk so future persona
+ * analyses won’t re-do the work.
+ *
+ * Optimizations vs. naive serial loop:
+ *  - Only describes the FIRST image per post (the dominant visual). For style
+ *    analysis a single visual sample per post is sufficient and 25 posts × N
+ *    images would explode runtime under nginx’s proxy timeout.
+ *  - Runs up to CONCURRENCY describe-jobs in parallel.
+ *
+ * Returns the same array (with updated description fields) for chaining.
+ */
+export async function backfillImageDescriptions(
+  posts: LibraryPost[],
+): Promise<LibraryPost[]> {
+  const CONCURRENCY = 4;
+
+  type Job = { post: LibraryPost; idx: number };
+  const jobs: Job[] = [];
+  for (const post of posts) {
+    // First image only — style analysis needs one visual signal per post,
+    // not all carousel slides.
+    const idx = post.media.findIndex(
+      (m) => m.type === "image" && !(m.description && m.description.trim()) && !!m.remoteUrl,
+    );
+    if (idx === -1) continue;
+    jobs.push({ post, idx });
+  }
+
+  if (jobs.length === 0) return posts;
+
+  let cursor = 0;
+  const dirtyPosts = new Set<LibraryPost>();
+
+  async function worker() {
+    while (true) {
+      const myIdx = cursor++;
+      if (myIdx >= jobs.length) return;
+      const { post, idx } = jobs[myIdx]!;
+      const m = post.media[idx]!;
+
+      let localPath: string | null = m.localPath ?? null;
+      if (!localPath || !existsSync(localPath)) {
+        localPath = await downloadImage(m.remoteUrl!, post.id, idx);
+      }
+      if (!localPath) continue;
+
+      const desc = await describeImageViaClaudeCode(localPath);
+      if (!desc) continue;
+
+      m.localPath = localPath;
+      m.description = desc;
+      dirtyPosts.add(post);
+    }
+  }
+
+  await Promise.all(Array.from({ length: CONCURRENCY }, () => worker()));
+
+  for (const post of dirtyPosts) savePost(post);
+  return posts;
+}

package/server/socialview/library.ts

@@ -0,0 +1,119 @@
+// ─── SocialView Library ──────────────────────────────────────────────────────
+// File-based storage for reference posts. Layout:
+//   ~/.heyhank/socialview/library/<platform>/<id>.json
+//   ~/.heyhank/socialview/media/<id>-<i>.<ext>
+// No database: a flat directory is plenty for a few thousand posts and makes
+// backup/inspection trivial.
+
+import { mkdirSync, readFileSync, writeFileSync, readdirSync, existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { HEYHANK_HOME } from "../paths.js";
+import type { LibraryPost, LibraryQuery, SocialPlatform } from "./types.js";
+import { SOCIAL_PLATFORMS } from "./types.js";
+
+const LIBRARY_ROOT = join(HEYHANK_HOME, "socialview", "library");
+export const MEDIA_ROOT = join(HEYHANK_HOME, "socialview", "media");
+
+function platformDir(platform: SocialPlatform): string {
+  return join(LIBRARY_ROOT, platform);
+}
+
+function postPath(platform: SocialPlatform, id: string): string {
+  return join(platformDir(platform), `${id}.json`);
+}
+
+export function ensureDirs(): void {
+  mkdirSync(MEDIA_ROOT, { recursive: true });
+  for (const p of SOCIAL_PLATFORMS) {
+    mkdirSync(platformDir(p), { recursive: true });
+  }
+}
+
+export function savePost(post: LibraryPost): void {
+  ensureDirs();
+  writeFileSync(postPath(post.platform, post.id), JSON.stringify(post, null, 2));
+}
+
+export function getPost(platform: SocialPlatform, id: string): LibraryPost | null {
+  const path = postPath(platform, id);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as LibraryPost;
+  } catch {
+    return null;
+  }
+}
+
+export function deletePost(platform: SocialPlatform, id: string): boolean {
+  const path = postPath(platform, id);
+  if (!existsSync(path)) return false;
+  try {
+    unlinkSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** List posts across all platforms, newest first, with optional filters. */
+export function listPosts(q: LibraryQuery = {}): LibraryPost[] {
+  ensureDirs();
+  const platforms = q.platform ? [q.platform] : SOCIAL_PLATFORMS;
+  const out: LibraryPost[] = [];
+
+  for (const p of platforms) {
+    const dir = platformDir(p);
+    if (!existsSync(dir)) continue;
+    for (const file of readdirSync(dir)) {
+      if (!file.endsWith(".json")) continue;
+      try {
+        const post = JSON.parse(readFileSync(join(dir, file), "utf-8")) as LibraryPost;
+        if (!matchesQuery(post, q)) continue;
+        out.push(post);
+      } catch {
+        // skip malformed
+      }
+    }
+  }
+
+  out.sort((a, b) => (b.extractedAt > a.extractedAt ? 1 : -1));
+  if (q.limit && out.length > q.limit) return out.slice(0, q.limit);
+  return out;
+}
+
+function matchesQuery(post: LibraryPost, q: LibraryQuery): boolean {
+  if (q.source && post.source !== q.source) return false;
+  if (q.goldOnly && !post.isGold) return false;
+  if (typeof q.minEngagementRate === "number") {
+    if ((post.engagementRate ?? 0) < q.minEngagementRate) return false;
+  }
+  if (q.tags && q.tags.length > 0) {
+    const tagset = new Set(post.tags);
+    for (const t of q.tags) if (!tagset.has(t)) return false;
+  }
+  return true;
+}
+
+export function updatePost(
+  platform: SocialPlatform,
+  id: string,
+  patch: Partial<Pick<LibraryPost, "tags" | "isGold" | "notes" | "source">>,
+): LibraryPost | null {
+  const existing = getPost(platform, id);
+  if (!existing) return null;
+  const updated: LibraryPost = { ...existing, ...patch };
+  savePost(updated);
+  return updated;
+}
+
+/** Top-N posts for agent few-shot. Prefers gold + high engagement on the platform. */
+export function selectForFewShot(platform: SocialPlatform, limit: number = 5): LibraryPost[] {
+  const candidates = listPosts({ platform, goldOnly: true });
+  // Sort by engagementRate desc (nulls last)
+  candidates.sort((a, b) => {
+    const ar = a.engagementRate ?? -1;
+    const br = b.engagementRate ?? -1;
+    return br - ar;
+  });
+  return candidates.slice(0, limit);
+}

package/server/socialview/poster.ts

@@ -0,0 +1,276 @@
+// ─── SocialView Poster ───────────────────────────────────────────────────────
+// Browser-based posting for X (Twitter) and TikTok. Reuses the persistent
+// Playwright context from browser-manager.ts, so the user's manual login
+// (via noVNC) carries over. No headless — user can watch actions live.
+//
+// Scope v1:
+//   - X: text + optional single image
+//   - TikTok: video + description
+//
+// Selectors are stable `data-testid` attributes (X) / reasonably stable ARIA
+// roles (TikTok). If UI changes break a selector, the caller surfaces the
+// error and the user can inspect via noVNC.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+import type { Page } from "playwright";
+import { HEYHANK_HOME } from "../paths.js";
+
+// ─── Media resolution (mirrors postiz-adapter) ───────────────────────────────
+
+const MIME_BY_EXT: Record<string, string> = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  mp4: "video/mp4",
+  mov: "video/quicktime",
+  webm: "video/webm",
+};
+
+/** Detect MIME from file's magic bytes. See postiz-adapter.ts for rationale. */
+function detectMimeFromBytes(buf: Uint8Array): string | null {
+  if (buf.length < 12) return null;
+  if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return "image/jpeg";
+  if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) return "image/png";
+  if (buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x38) return "image/gif";
+  if (
+    buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 &&
+    buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50
+  ) return "image/webp";
+  if (buf[4] === 0x66 && buf[5] === 0x74 && buf[6] === 0x79 && buf[7] === 0x70) return "video/mp4";
+  return null;
+}
+
+function extForMime(mime: string): string {
+  switch (mime) {
+    case "image/jpeg": return "jpg";
+    case "image/png": return "png";
+    case "image/gif": return "gif";
+    case "image/webp": return "webp";
+    case "video/mp4": return "mp4";
+    case "video/quicktime": return "mov";
+    case "video/webm": return "webm";
+    default: return "bin";
+  }
+}
+
+function extractLocalMediaFilename(url: string): string | null {
+  try {
+    const withoutHost = url.replace(/^https?:\/\/[^/]+/i, "");
+    const match = withoutHost.match(/^\/api\/media\/file\/([^/?#]+)/);
+    if (!match) return null;
+    return basename(decodeURIComponent(match[1]));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a media URL to a local disk path that Playwright's
+ * `setInputFiles` can consume. Handles:
+ *   - local HeyHank media (/api/media/file/<name>) — reads from ~/.heyhank/media
+ *   - absolute http(s) URLs — downloaded to /tmp
+ * Applies magic-byte detection so a JPEG saved with a .png extension
+ * is renamed to .jpg before being handed to the browser upload widget.
+ */
+export async function resolveMediaToDiskPath(url: string): Promise<string> {
+  const localName = extractLocalMediaFilename(url);
+  let buf: Uint8Array;
+  let originalName: string;
+
+  if (localName) {
+    const local = join(HEYHANK_HOME, "media", localName);
+    if (!existsSync(local)) throw new Error(`Local media file not found: ${localName}`);
+    buf = readFileSync(local);
+    originalName = localName;
+  } else if (/^https?:\/\//i.test(url)) {
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`Failed to fetch media URL ${url}: ${res.status}`);
+    buf = new Uint8Array(await res.arrayBuffer());
+    const urlPath = url.split(/[?#]/)[0];
+    originalName = basename(urlPath) || `media_${randomUUID()}`;
+  } else {
+    throw new Error(`Unsupported media URL: ${url}`);
+  }
+
+  const extFromName = originalName.split(".").pop()?.toLowerCase() ?? "";
+  const sniffed = detectMimeFromBytes(buf);
+  const correctExt = sniffed ? extForMime(sniffed) : (MIME_BY_EXT[extFromName] ? extFromName : "bin");
+  const finalName =
+    correctExt && correctExt !== extFromName
+      ? `${originalName.replace(/\.[^.]+$/, "")}.${correctExt}`
+      : originalName;
+
+  const stageDir = join(tmpdir(), "heyhank-browser-upload");
+  mkdirSync(stageDir, { recursive: true });
+  const finalPath = join(stageDir, `${Date.now()}_${randomUUID()}_${finalName}`);
+  writeFileSync(finalPath, buf);
+  return finalPath;
+}
+
+// ─── Humanized delays ────────────────────────────────────────────────────────
+
+function humanDelay(minMs = 50, maxMs = 200): Promise<void> {
+  const ms = minMs + Math.floor(Math.random() * (maxMs - minMs));
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+export interface PostResult {
+  url: string | null;
+}
+
+// ─── X (Twitter) ─────────────────────────────────────────────────────────────
+
+export interface PostToXOpts {
+  text: string;
+  imagePath?: string;
+}
+
+export async function postToX(page: Page, opts: PostToXOpts): Promise<PostResult> {
+  // The dedicated compose URL pops the composer dialog directly, avoiding
+  // the timeline's "What's happening?" inline-vs-modal ambiguity.
+  await page.goto("https://x.com/compose/post", { waitUntil: "domcontentloaded" });
+  await humanDelay(600, 1100);
+
+  // 1) Find the tweet textarea. X uses a stable data-testid.
+  const textareaSelector = '[data-testid="tweetTextarea_0"]';
+  await page.waitForSelector(textareaSelector, { timeout: 30_000 });
+  const textarea = await page.$(textareaSelector);
+  if (!textarea) throw new Error("X tweet textarea not found");
+
+  await textarea.click();
+  await humanDelay(80, 180);
+  await page.keyboard.type(opts.text, { delay: 25 });
+  await humanDelay(300, 700);
+
+  // 2) Optional single image upload via the hidden file input.
+  if (opts.imagePath) {
+    const fileInput = await page.$('[data-testid="fileInput"]') ?? await page.$('input[type="file"]');
+    if (!fileInput) throw new Error("X file input not found");
+    await fileInput.setInputFiles(opts.imagePath);
+    // Wait for the inline preview tile so we know the upload is accepted.
+    try {
+      await page.waitForSelector('[data-testid="attachments"]', { timeout: 30_000 });
+    } catch {
+      // Some variants render the preview without that testid; soft-fail.
+    }
+    await humanDelay(500, 1000);
+  }
+
+  // 3) Click the Post button. X uses two ids depending on context.
+  const postBtn =
+    (await page.$('[data-testid="tweetButtonInline"]')) ??
+    (await page.$('[data-testid="tweetButton"]'));
+  if (!postBtn) throw new Error("X Post button not found");
+
+  // Wait for the button to be enabled (text + media validation passes).
+  for (let i = 0; i < 40; i++) {
+    const ariaDisabled = await postBtn.getAttribute("aria-disabled");
+    if (ariaDisabled !== "true") break;
+    await humanDelay(200, 400);
+  }
+
+  await postBtn.click();
+
+  // 4) After post, the composer closes and we end up on the timeline.
+  //    The toast "Your post was sent" appears briefly. We don't reliably
+  //    capture the new tweet's URL — return null and let the caller treat
+  //    the absence of an exception as success.
+  try {
+    await page.waitForFunction(
+      () => !location.pathname.includes("/compose"),
+      { timeout: 30_000 },
+    );
+  } catch {
+    // Composer may stay open if there was a validation issue — surface as error.
+    const stillThere = await page.$(textareaSelector);
+    if (stillThere) throw new Error("X post did not complete (composer still open)");
+  }
+
+  return { url: null };
+}
+
+// ─── TikTok ──────────────────────────────────────────────────────────────────
+
+export interface PostToTiktokOpts {
+  description: string;
+  videoPath: string;
+}
+
+export async function postToTiktok(page: Page, opts: PostToTiktokOpts): Promise<PostResult> {
+  await page.goto("https://www.tiktok.com/tiktokstudio/upload", { waitUntil: "domcontentloaded" });
+  await humanDelay(800, 1400);
+
+  // 1) The upload input is a hidden <input type="file" accept="video/*">.
+  //    TikTok sometimes nests it inside a shadow-ish iframe; try top-level first.
+  let fileInput = await page.$('input[type="file"][accept*="video"]');
+  if (!fileInput) {
+    // Fallback: any type=file input on the page.
+    fileInput = await page.$('input[type="file"]');
+  }
+  if (!fileInput) throw new Error("TikTok video file input not found");
+
+  await fileInput.setInputFiles(opts.videoPath);
+  await humanDelay(600, 1200);
+
+  // 2) Wait until processing finishes. TikTok shows a progress indicator
+  //    while the video is being uploaded + transcoded. Heuristic: wait
+  //    until we see the caption/description editor become editable.
+  const descSelector = 'div[contenteditable="true"]';
+  await page.waitForSelector(descSelector, { timeout: 120_000 });
+
+  // Give transcoding a moment to settle so the Post button becomes enabled.
+  await humanDelay(1500, 2500);
+
+  // 3) Fill the description. TikTok's composer is a contenteditable div;
+  //    it may pre-populate with the filename, so clear it first.
+  const descEl = await page.$(descSelector);
+  if (!descEl) throw new Error("TikTok description editor not found");
+  await descEl.click();
+  await humanDelay(100, 200);
+  await page.keyboard.press("Control+A");
+  await humanDelay(50, 150);
+  await page.keyboard.press("Delete");
+  await humanDelay(100, 200);
+  await page.keyboard.type(opts.description, { delay: 25 });
+  await humanDelay(400, 800);
+
+  // 4) Click Post. TikTok's Studio uses a button with text "Post".
+  //    Try a few shapes — a dedicated data-e2e first, then role=button.
+  const postButton =
+    (await page.$('[data-e2e="post_video_button"]')) ??
+    (await page.$('button:has-text("Post")'));
+  if (!postButton) throw new Error("TikTok Post button not found");
+
+  // Button may start disabled while upload finalizes; wait until enabled.
+  for (let i = 0; i < 60; i++) {
+    const disabled = await postButton.getAttribute("disabled");
+    const ariaDisabled = await postButton.getAttribute("aria-disabled");
+    if (!disabled && ariaDisabled !== "true") break;
+    await humanDelay(500, 800);
+  }
+
+  await postButton.click();
+
+  // 5) After post, TikTok Studio typically navigates to the content manager
+  //    or shows a success modal. We don't reliably get back the public URL,
+  //    so we just wait for navigation away from /upload.
+  try {
+    await page.waitForFunction(
+      () => !location.pathname.includes("/upload"),
+      { timeout: 60_000 },
+    );
+  } catch {
+    // Some versions keep you on /upload and just clear the form. If the
+    // description editor is gone, treat as success.
+    const stillHasEditor = await page.$(descSelector);
+    if (stillHasEditor) throw new Error("TikTok post did not complete");
+  }
+
+  // v1: we don't attempt to fish the public video URL out of the studio UI.
+  return { url: null };
+}