@sprid/scout 0.1.0

package/src/quick.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+"use strict";
+
+// The fast lane on macOS: read a profile or a hashtag through the Chrome the
+// user is already signed in to, instead of the dedicated research profile.
+//
+// It costs no login, because it borrows a session that already exists. What it
+// costs instead is a browser-wide permission (View → Developer → Allow
+// JavaScript from Apple Events), which lets any local script run JavaScript in
+// any tab that browser has open. That is a real trade and the skill states it
+// in those words; this file does not decide it for anyone.
+//
+// It opens its own tab and closes it again, so it never takes over the tab in
+// front of the user.
+//
+// What it can and cannot do, measured rather than assumed:
+//   - The feed endpoint is signature-gated. Called directly it answers 200 with
+//     an empty body, and the page signs its own requests, so there is no way to
+//     ask it for JSON from here.
+//   - Patching fetch and XHR catches nothing either: a profile grid arrives
+//     with the document, and scrolling it produced no API calls at all.
+//   - What is there is the rendered grid: every post as a link, with its view
+//     count where the page prints one. That is enough to collect what to pull,
+//     and not enough to measure an account over a time window, because a tile
+//     carries no date. Measurement stays on the dedicated-profile lane.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { execFile } = require("node:child_process");
+const util = require("node:util");
+const { ROOT } = require("./config");
+const { captureSource, writeFrames, DEFAULT_OFFSETS } = require("./frames");
+const { sheetFromFrames, wallFromFrames, ffmpegAvailable } = require("./sheet");
+
+const run = util.promisify(execFile);
+
+const NOT_ENABLED =
+  "Chrome refused the JavaScript. Turn on View → Developer → Allow JavaScript from Apple Events " +
+  "in the Chrome the user is signed in to, or use the dedicated-profile lane instead " +
+  "(npm run login, then the normal tools).";
+
+/** AppleScript string literal: backslashes and quotes only. */
+function osaString(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+async function osascript(lines) {
+  const args = lines.flatMap((line) => ["-e", line]);
+  try {
+    const { stdout } = await run("osascript", args, { maxBuffer: 64 * 1024 * 1024 });
+    return stdout.trim();
+  } catch (error) {
+    const text = String(error.stderr || error.message);
+    if (/-1723|not allowed|javascript through applescript|-2700/i.test(text)) throw new Error(NOT_ENABLED);
+    if (/Application isn't running|-600/.test(text)) {
+      throw new Error("Google Chrome is not running. Open it, signed in to TikTok, and try again.");
+    }
+    throw new Error(text.split("\n")[0]);
+  }
+}
+
+/** "@handle", "handle", "#tag" or "tag:name" → the page to open. */
+function targetUrl(target) {
+  const value = String(target).trim();
+  if (/^#/.test(value)) return { kind: "hashtag", name: value.slice(1), url: `https://www.tiktok.com/tag/${encodeURIComponent(value.slice(1))}` };
+  if (/^tag:/i.test(value)) return { kind: "hashtag", name: value.slice(4), url: `https://www.tiktok.com/tag/${encodeURIComponent(value.slice(4))}` };
+  const handle = value.replace(/^@/, "");
+  return { kind: "account", name: handle, url: `https://www.tiktok.com/@${handle}` };
+}
+
+// Apple Events JavaScript is synchronous: it hands back the value of the last
+// expression and cannot wait for a promise, so an async body returns nothing at
+// all. The work is started in one call, parked on `window`, and collected by a
+// second call that polls for it.
+function starterScript(rounds) {
+  return `(() => { window.__SCOUT_RESULT__ = null; (async () => {
+  const seen = new Map();
+  const viewsOf = (tile) => {
+    const el = tile.querySelector('[data-e2e*="views"], strong');
+    const raw = el ? el.textContent.trim() : '';
+    const m = raw.match(/^([\\d.,]+)\\s*([KMB])?$/i);
+    if (!m) return null;
+    const n = parseFloat(m[1].replace(/,/g, ''));
+    const mult = { k: 1e3, m: 1e6, b: 1e9 }[(m[2] || '').toLowerCase()] || 1;
+    return Math.round(n * mult);
+  };
+  const collect = () => {
+    for (const a of document.querySelectorAll('a[href*="/video/"], a[href*="/photo/"]')) {
+      const m = a.href.match(/tiktok\\.com\\/@([^/]+)\\/(video|photo)\\/(\\d+)/);
+      if (!m || seen.has(m[3])) continue;
+      const tile = a.closest('[data-e2e="challenge-item"], [data-e2e="user-post-item"], div');
+      seen.set(m[3], { url: a.href.split('?')[0], handle: m[1], type: m[2] === 'photo' ? 'slideshow' : 'video', id: m[3], views: tile ? viewsOf(tile) : null });
+    }
+  };
+  try {
+    collect();
+    for (let round = 0; round < ${rounds}; round++) {
+      const before = seen.size;
+      window.scrollTo(0, document.body.scrollHeight);
+      await new Promise((r) => setTimeout(r, 1500));
+      collect();
+      if (seen.size === before && round > 1) break;
+    }
+    const el = document.getElementById('__UNIVERSAL_DATA_FOR_REHYDRATION__');
+    const scope = el ? JSON.parse(el.textContent).__DEFAULT_SCOPE__ : null;
+    const info = scope && scope['webapp.user-detail'] && scope['webapp.user-detail'].userInfo;
+    const stats = info ? Object.assign({}, info.stats, info.statsV2) : null;
+    window.__SCOUT_RESULT__ = JSON.stringify({
+      user: info && info.user ? { username: info.user.uniqueId, display_name: info.user.nickname,
+        bio: info.user.signature, verified: !!info.user.verified,
+        followers: Number(stats.followerCount) || 0, posts: Number(stats.videoCount) || 0 } : null,
+      title: document.title,
+      posts: [...seen.values()],
+    });
+  } catch (e) { window.__SCOUT_RESULT__ = JSON.stringify({ error: String((e && e.message) || e) }); }
+})(); return 'started'; })()`;
+}
+
+const COLLECT_SCRIPT = '(() => window.__SCOUT_RESULT__ || "")()';
+
+/** Opens its own tab, reads the grid, closes it. Never touches the tab in front. */
+async function collect(target, { rounds = 10, timeoutMs = 90_000 } = {}) {
+  const where = targetUrl(target);
+  await osascript([
+    'tell application "Google Chrome"',
+    `  make new tab at end of tabs of front window with properties {URL:${osaString(where.url)}}`,
+    "end tell",
+  ]);
+  // The document has to exist before anything can read it. This is a settle,
+  // not a load wait: the grid arrives with the document.
+  await new Promise((resolve) => setTimeout(resolve, 4000));
+  let raw = "";
+  try {
+    await osascript([
+      'tell application "Google Chrome"',
+      "  set t to last tab of front window",
+      `  execute t javascript ${osaString(starterScript(rounds))}`,
+      "end tell",
+    ]);
+    const deadline = Date.now() + timeoutMs;
+    while (!raw && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 800));
+      raw = await osascript([
+        'tell application "Google Chrome"',
+        "  set t to last tab of front window",
+        `  execute t javascript ${osaString(COLLECT_SCRIPT)}`,
+        "end tell",
+      ]);
+    }
+  } finally {
+    await osascript([
+      'tell application "Google Chrome"',
+      "  try",
+      "    close last tab of front window",
+      "  end try",
+      "end tell",
+    ]).catch(() => {});
+  }
+  if (!raw) throw new Error("Chrome returned nothing before the timeout. The page may not have loaded.");
+  const payload = JSON.parse(raw);
+  if (payload.error) throw new Error(`The page answered: ${payload.error}`);
+  const posts = payload.posts ?? [];
+  return {
+    lane: "your own Chrome, via Apple Events",
+    target: where.name,
+    kind: where.kind,
+    url: where.url,
+    user: payload.user,
+    found: posts.length,
+    slideshows: posts.filter((p) => p.type === "slideshow").length,
+    posts: posts.sort((a, b) => (b.views ?? 0) - (a.views ?? 0)),
+    next: "Pull the media with the download tool, passing these urls as links.",
+  };
+}
+
+const POST_URL = /tiktok\.com\/@([^/]+)\/(video|photo)\/(\d+)/;
+
+/**
+ * One post, read as frames off its own player, through the Chrome the user is
+ * already signed in to. The same capture the dedicated lane runs; only the
+ * bridge into the page differs.
+ */
+async function captureFrames(url, { offsets = DEFAULT_OFFSETS, outDir } = {}) {
+  const match = String(url).match(POST_URL);
+  if (!match) throw new Error("Give the url of a post, e.g. https://www.tiktok.com/@handle/video/123");
+  await osascript([
+    'tell application "Google Chrome"',
+    `  make new tab at end of tabs of front window with properties {URL:${osaString(url)}}`,
+    "end tell",
+  ]);
+  await new Promise((resolve) => setTimeout(resolve, 7000));
+  const starter = `(() => { window.__SCOUT_FRAMES__ = null; (${captureSource(offsets)})
+    .then((value) => { window.__SCOUT_FRAMES__ = value; })
+    .catch((e) => { window.__SCOUT_FRAMES__ = JSON.stringify({ error: String((e && e.message) || e) }); });
+  return "started"; })()`;
+  let raw = "";
+  try {
+    await osascript([
+      'tell application "Google Chrome"',
+      "  set t to last tab of front window",
+      `  execute t javascript ${osaString(starter)}`,
+      "end tell",
+    ]);
+    const deadline = Date.now() + 90_000;
+    while (!raw && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 900));
+      raw = await osascript([
+        'tell application "Google Chrome"',
+        "  set t to last tab of front window",
+        `  execute t javascript ${osaString('(() => window.__SCOUT_FRAMES__ || "")()')}`,
+        "end tell",
+      ]);
+    }
+  } finally {
+    await osascript([
+      'tell application "Google Chrome"',
+      "  try",
+      "    close last tab of front window",
+      "  end try",
+      "end tell",
+    ]).catch(() => {});
+  }
+  if (!raw) throw new Error("The player gave nothing back before the timeout.");
+  const payload = JSON.parse(raw);
+  if (payload.error) throw new Error(payload.error);
+
+  const dir = outDir ?? path.join(ROOT, "frames", `${match[1]}_${match[3]}`);
+  const frames = writeFrames(payload.shots, dir);
+  let sheet = null;
+  if (await ffmpegAvailable()) {
+    sheet = await sheetFromFrames(frames, path.join(dir, "sheet.png")).catch(() => null);
+  }
+  return {
+    lane: "your own Chrome, via Apple Events",
+    url,
+    handle: match[1],
+    id: match[3],
+    duration_seconds: payload.duration,
+    directory: dir,
+    frames: frames.map((f) => ({ at: f.at, file: path.basename(f.file) })),
+    sheet: sheet ? path.basename(sheet.file) : null,
+    read_it:
+      "Tiles left to right at those offsets. Frame 0 is the cover the feed shows before anyone presses anything.",
+  };
+}
+
+
+/**
+ * The same instant across many posts, as one image.
+ *
+ * `captureFrames` reads one post down time; this reads a niche across posts at
+ * a fixed second. Frame 0 is the default because that is the cover the feed
+ * shows, and a wall of covers is the fastest way to see what a category has
+ * agreed on and what nobody is doing.
+ */
+async function captureWall(urls, { at = 0, outDir, cols = 4 } = {}) {
+  const dir = outDir ?? path.join(ROOT, "walls", `${Date.now()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  const cells = [];
+  const failures = [];
+  for (const [index, url] of urls.entries()) {
+    try {
+      const one = await captureFrames(url, { offsets: [at], outDir: path.join(dir, `cell_${index}`) });
+      const frame = path.join(one.directory, one.frames[0].file);
+      cells.push({ at, file: frame, url, handle: one.handle });
+    } catch (error) {
+      failures.push({ url, why: String(error.message).slice(0, 120) });
+    }
+  }
+  if (cells.length === 0) throw new Error("No post gave a frame back.");
+  const wall = (await ffmpegAvailable())
+    ? await wallFromFrames(cells, path.join(dir, `wall_${at}s.png`), { cols })
+    : null;
+  return {
+    lane: "your own Chrome, via Apple Events",
+    at_seconds: at,
+    directory: dir,
+    cells: cells.map((c, i) => ({ position: i + 1, handle: c.handle, url: c.url })),
+    wall: wall ? path.basename(wall.file) : null,
+    skipped: failures,
+    read_it:
+      `Left to right, top to bottom, in the order listed. Every cell is the same second (${at}s) of a different post, ` +
+      "so what repeats across the wall is the category's habit and what appears once is the opening.",
+  };
+}
+
+module.exports = { collect, captureFrames, captureWall, targetUrl, NOT_ENABLED };
+
+if (require.main === module) {
+  const [target, ...rest] = process.argv.slice(2);
+  if (!target) {
+    console.error("Usage: sprid-scout-quick <@handle | #hashtag | post-url> [--rounds 10] [--links-only] [--at 0,1,2,5,10]\n       sprid-scout-quick wall <post-url> <post-url> ... [--at-second 0]");
+    process.exit(1);
+  }
+  const roundsAt = rest.indexOf("--rounds");
+  const atAt = rest.indexOf("--at");
+  const offsets = atAt === -1 ? undefined : String(rest[atAt + 1]).split(",").map(Number).filter((n) => Number.isFinite(n));
+  const tAt = rest.indexOf("--at-second");
+  const wallUrls = target === "wall" ? rest.filter((a) => POST_URL.test(a)) : [];
+  const work =
+    target === "wall"
+      ? captureWall(wallUrls, { at: tAt === -1 ? 0 : Number(rest[tAt + 1]) })
+      : POST_URL.test(target)
+        ? captureFrames(target, { offsets })
+        : collect(target, { rounds: roundsAt === -1 ? 10 : Number(rest[roundsAt + 1]) });
+  work
+    .then((result) => {
+      if (rest.includes("--links-only") && result.posts) {
+        for (const post of result.posts) console.log(post.url);
+        return;
+      }
+      console.log(JSON.stringify(result, null, 2));
+    })
+    .catch((error) => {
+      console.error(error.message);
+      process.exit(1);
+    });
+}

package/src/register.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+"use strict";
+
+// Registers this server with the agents that speak MCP over stdio. The skill
+// that teaches an agent how to use it ships with the Sprid plugin, so nothing
+// is copied into a skills directory from here: one text, one home.
+
+const path = require("node:path");
+const { execFileSync } = require("node:child_process");
+const { NAME } = require("./config");
+
+const SERVER = path.join(__dirname, "server.js");
+const ADD = ["mcp", "add", "--transport", "stdio", "--scope", "user", NAME, "--", process.execPath, SERVER];
+
+try {
+  execFileSync("claude", ["mcp", "remove", "--scope", "user", NAME], { stdio: "ignore" });
+} catch {}
+
+try {
+  const output = execFileSync("claude", ADD, { encoding: "utf8" });
+  console.log(`- Claude Code: ${output.trim() || "registered"}`);
+} catch {
+  console.log("- Claude Code: could not run `claude mcp add`. Register it by hand with:");
+  console.log(`\n    claude mcp add --transport stdio --scope user ${NAME} -- ${process.execPath} ${SERVER}\n`);
+}
+
+console.log("\nDone. Start a new session, then ask it to log in to TikTok.");