@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/engage/index.ts

@@ -0,0 +1,217 @@
+import { ConfigError, RetryableError } from "@vfrey/contracts";
+import { classifyComment, reviewReply, type ReplyTone } from "@vfrey/contracts";
+import type { Account, AppConfig } from "@vfrey/contracts";
+import { requestJson } from "@vfrey/contracts";
+import type { LlmClient } from "../llm/client.js";
+import type { Store } from "../queue/store.js";
+
+export interface OwnedPost {
+  platform: "youtube" | "instagram" | "facebook";
+  externalId: string;
+}
+
+export async function engageAccount(input: {
+  config: AppConfig;
+  account: Account;
+  posts: OwnedPost[];
+  tokenFor: (platform: OwnedPost["platform"]) => Promise<string>;
+  llm: LlmClient;
+  store: Store;
+  fetchImpl: typeof fetch;
+  now: Date;
+  dryRun: boolean;
+}): Promise<number> {
+  if (!input.account.engage.enabled) return 0;
+  let replied = 0;
+  const since = new Date(input.now.getTime() - 24 * 60 * 60 * 1000).toISOString();
+  for (const post of input.posts) {
+    const comments = await listComments(input, post);
+    for (const comment of comments) {
+      if (input.store.commentHandled(post.platform, comment.id)) continue;
+      const decision = classifyComment(comment.text, input.account.engage.allowSpicy);
+      if (!decision.reply) {
+        input.store.recordComment({
+          platform: post.platform,
+          commentId: comment.id,
+          accountId: input.account.id,
+          action: "skipped",
+          tone: null,
+          replyText: null,
+          at: input.now,
+          commentText: comment.text,
+          dryRun: input.dryRun,
+        });
+        continue;
+      }
+      if (input.store.repliesSince(input.account.id, since) >= input.account.engage.maxRepliesPerDay) return replied;
+      const last = input.store.lastReplyAt(input.account.id);
+      if (last && input.now.getTime() - last.getTime() < input.account.engage.minSecondsBetweenReplies * 1000) {
+        // End the pass. The reply gap is ours; the next tick continues from the comments not yet handled.
+        return replied;
+      }
+      const raw = await input.llm.complete({
+        system: [
+          "You reply to a comment on the creator's own video.",
+          "Match the requested tone. Spicy means a sharp one-beat pushback with no insult and no slur.",
+          "Never claim to be a doctor, lawyer, or financial adviser.",
+          "No links. Under 400 characters. Return JSON {tone, text}.",
+        ].join(" "),
+        user: `TASK:REPLY\nTONE: ${decision.tone}\nCOMMENT: ${comment.text.replace(/\n/g, " ")}\nVIDEO: ${comment.videoTitle}`,
+        temperature: decision.tone === "spicy" ? 0.8 : 0.4,
+        maxTokens: 300,
+      });
+      const parsed = JSON.parse(extractJson(raw)) as { tone?: ReplyTone; text?: string };
+      const draft = { tone: decision.tone, text: String(parsed.text ?? "") };
+      const review = reviewReply(draft);
+      if (!review.ok) {
+        input.store.recordComment({
+          platform: post.platform,
+          commentId: comment.id,
+          accountId: input.account.id,
+          action: "blocked",
+          tone: decision.tone,
+          replyText: null,
+          at: input.now,
+          commentText: comment.text,
+          dryRun: input.dryRun,
+        });
+        continue;
+      }
+      if (!input.dryRun) {
+        const token = await input.tokenFor(post.platform);
+        try {
+          await sendReply(input.fetchImpl, input.config, post.platform, token, comment, draft.text);
+        } catch (error) {
+          if (!(error instanceof ReplyRefused)) throw error;
+          // A deleted comment or closed comments will not change. Record it so it is never tried again.
+          input.store.recordComment({
+            platform: post.platform,
+            commentId: comment.id,
+            accountId: input.account.id,
+            action: "skipped",
+            tone: decision.tone,
+            replyText: null,
+            at: input.now,
+            code: error.code,
+            commentText: comment.text,
+          });
+          continue;
+        }
+      }
+      input.store.recordComment({
+        platform: post.platform,
+        commentId: comment.id,
+        accountId: input.account.id,
+        action: "replied",
+        tone: decision.tone,
+        replyText: draft.text,
+        at: input.now,
+        commentText: comment.text,
+        dryRun: input.dryRun,
+      });
+      replied += 1;
+    }
+  }
+  return replied;
+}
+
+interface CommentItem {
+  id: string;
+  text: string;
+  videoTitle: string;
+  parentId: string | null;
+}
+
+/** The platform refused this one reply for a reason that will not change. */
+class ReplyRefused extends Error {
+  constructor(readonly code: string, message: string) {
+    super(message);
+  }
+}
+
+const QUOTA_REASON = /^(quotaExceeded|rateLimitExceeded|dailyLimitExceeded|userRateLimitExceeded)$/;
+
+function googleReason(json: unknown): string {
+  return String((json as { error?: { errors?: Array<{ reason?: string }> } } | null)?.error?.errors?.[0]?.reason ?? "");
+}
+
+async function listComments(
+  input: { config: AppConfig; fetchImpl: typeof fetch; tokenFor: (platform: OwnedPost["platform"]) => Promise<string>; dryRun: boolean },
+  post: OwnedPost,
+): Promise<CommentItem[]> {
+  if (input.dryRun) return [];
+  const token = await input.tokenFor(post.platform);
+  if (post.platform === "youtube") {
+    const url =
+      `https://www.googleapis.com/youtube/v3/commentThreads?part=snippet&videoId=${encodeURIComponent(post.externalId)}` +
+      `&maxResults=20&order=time&textFormat=plainText`;
+    const result = await requestJson(input.fetchImpl, url, { headers: { authorization: `Bearer ${token}` } });
+    if (result.status === 401) throw new ConfigError("youtube_token", "YouTube token is expired or revoked");
+    if (result.status === 403 || result.status === 400) {
+      const reason = googleReason(result.json);
+      if (QUOTA_REASON.test(reason)) throw new RetryableError("youtube_comments", "YouTube comment quota", 60 * 60_000);
+      // Comments are off or this video is gone: there is nothing to answer.
+      if (reason === "commentsDisabled" || reason === "videoNotFound") return [];
+      throw new RetryableError("youtube_comments", `YouTube comment read HTTP ${result.status}`, 60 * 60_000);
+    }
+    const items = (result.json as { items?: Array<{ id?: string; snippet?: { topLevelComment?: { id?: string; snippet?: { textDisplay?: string } } } }> }).items ?? [];
+    return items.map((item) => ({
+      id: item.snippet?.topLevelComment?.id ?? item.id ?? "",
+      text: item.snippet?.topLevelComment?.snippet?.textDisplay ?? "",
+      videoTitle: post.externalId,
+      parentId: null,
+    })).filter((item) => item.id && item.text);
+  }
+  const version = input.config.meta.graphVersion;
+  const result = await requestJson(
+    input.fetchImpl,
+    `https://graph.facebook.com/${version}/${post.externalId}/comments?fields=id,message&limit=20`,
+    { headers: { authorization: `Bearer ${token}` } },
+  );
+  if (result.status === 429) throw new RetryableError("meta_comments", "Comment read rate limit");
+  const data = (result.json as { data?: Array<{ id?: string; message?: string }> }).data ?? [];
+  return data
+    .map((item) => ({ id: item.id ?? "", text: item.message ?? "", videoTitle: post.externalId, parentId: null }))
+    .filter((item) => item.id && item.text);
+}
+
+async function sendReply(
+  fetchImpl: typeof fetch,
+  config: AppConfig,
+  platform: OwnedPost["platform"],
+  token: string,
+  comment: CommentItem,
+  message: string,
+): Promise<void> {
+  if (platform === "youtube") {
+    const result = await requestJson(fetchImpl, "https://www.googleapis.com/youtube/v3/comments?part=snippet", {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify({ snippet: { parentId: comment.id, textOriginal: message } }),
+    });
+    if (result.status === 401) throw new ConfigError("youtube_token", "YouTube token is expired or revoked");
+    if (result.status === 429 || result.status >= 500) throw new RetryableError("youtube_reply", `YouTube reply HTTP ${result.status}`);
+    if (result.status >= 400) {
+      if (QUOTA_REASON.test(googleReason(result.json))) {
+        throw new RetryableError("youtube_reply", "YouTube reply quota", 30 * 60_000);
+      }
+      throw new ReplyRefused(`youtube_reply_${result.status}`, `YouTube reply HTTP ${result.status}`);
+    }
+    return;
+  }
+  const version = config.meta.graphVersion;
+  const path = platform === "instagram" ? `${comment.id}/replies` : `${comment.id}/comments`;
+  const result = await requestJson(fetchImpl, `https://graph.facebook.com/${version}/${path}`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ message }),
+  });
+  if (result.status === 401) throw new ConfigError("meta_token", "Meta token is expired or invalid");
+  if (result.status === 429 || result.status >= 500) throw new RetryableError("meta_reply", `Reply HTTP ${result.status}`);
+  if (result.status >= 400) throw new ReplyRefused(`${platform}_reply_${result.status}`, `Reply HTTP ${result.status}`);
+}
+
+function extractJson(text: string): string {
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+  return (fenced?.[1] ?? text).trim();
+}

package/src/generate/index.ts

@@ -0,0 +1,110 @@
+import { QualityError, RetryableError } from "@vfrey/contracts";
+import { assertNoAdvicePersona, assertNotVerbatim } from "@vfrey/contracts";
+import { assertSubjectBinding, fitBeats } from "@vfrey/contracts";
+import type { Beat, Candidate, ContentPackage, VariationPlan } from "@vfrey/contracts";
+import { parseModelJson, type LlmClient } from "../llm/client.js";
+
+export async function writePackage(input: {
+  llm: LlmClient;
+  candidate: Candidate;
+  plan: VariationPlan;
+  niche: string;
+  language: string;
+  hashtagPool: string[];
+}): Promise<Omit<ContentPackage, "voiceoverPath" | "outputPath" | "durationSec"> & { beats: Beat[]; durationSec: number }> {
+  let lastError: Error | null = null;
+  for (let attempt = 1; attempt <= 3; attempt += 1) {
+    const raw = await input.llm.complete({
+      system: [
+        "You write an original short-form video. Return JSON only.",
+        "The viewer value has to be specific to this source. Do not write a generic list that could fit any topic.",
+        "Do not copy 12 or more consecutive words from the source.",
+        "Do not role-play a doctor, lawyer, or financial adviser.",
+        "Do not claim the footage is a recording of a real event.",
+        `Niche: ${input.niche}. Language: ${input.language}.`,
+        `Hook pattern: ${input.plan.hookPattern}. Structure: ${input.plan.structure}.`,
+      ].join("\n"),
+      user: [
+        "TASK:PACKAGE",
+        `SOURCE_TITLE: ${input.candidate.title}`,
+        `SOURCE_EXCERPT: ${input.candidate.excerpt}`,
+        `HOOK_PATTERN: ${input.plan.hookPattern}`,
+        `STRUCTURE: ${input.plan.structure}`,
+        `HASHTAG_STRATEGY: ${input.plan.hashtagStrategy}`,
+        lastError ? `PREVIOUS_DRAFT_REJECTED: ${lastError.message}` : "",
+        "JSON keys: title, hook, caption, description, hashtags, thumbnailPrompt, imagePrompts, beats.",
+        "beats is an array of {role, text, caption, seconds}. Roles: hook, setup, turn, evidence, payoff, cta. At least 4 beats.",
+      ].join("\n"),
+      temperature: 0.7,
+      maxTokens: 1800,
+    });
+    try {
+      const parsed = parseModelJson(raw) as Record<string, unknown>;
+      const beats = fitBeats(asBeats(parsed.beats), input.plan.templateId);
+      const hook = String(parsed.hook ?? beats[0]?.text ?? "").trim();
+      const title = String(parsed.title ?? "").trim();
+      if (!title || !hook) throw new QualityError("thin_script", "Model omitted a title or hook.");
+      const script = beats.map((beat) => beat.text).join(" ");
+      assertSubjectBinding(script, input.candidate.title);
+      assertNotVerbatim(`${title} ${script}`, `${input.candidate.title} ${input.candidate.excerpt}`);
+      assertNoAdvicePersona(script);
+      const hashtags = normalizeHashtags(
+        Array.isArray(parsed.hashtags) ? parsed.hashtags.map(String) : [],
+        input.hashtagPool,
+        input.plan.hashtagStrategy,
+      );
+      const durationSec = round1(beats.reduce((sum, beat) => sum + beat.seconds, 0));
+      return {
+        candidate: input.candidate,
+        plan: input.plan,
+        title,
+        hook,
+        beats,
+        caption: String(parsed.caption ?? hook),
+        description: String(parsed.description ?? script),
+        hashtags,
+        thumbnailPrompt: String(parsed.thumbnailPrompt ?? title),
+        imagePrompts: Array.isArray(parsed.imagePrompts) ? parsed.imagePrompts.map(String).slice(0, 4) : [],
+        voiceoverScript: beats.map((beat) => beat.text).join("\n"),
+        durationSec,
+      };
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (error instanceof RetryableError) throw error;
+    }
+  }
+  throw lastError ?? new QualityError("generation", "Generation failed three times.");
+}
+
+function asBeats(value: unknown): Array<{ role: string; text: string; caption: string; seconds: number }> {
+  if (!Array.isArray(value)) throw new QualityError("thin_script", "Model returned no beats.");
+  return value.map((beat) => {
+    const row = beat as Record<string, unknown>;
+    return {
+      role: String(row.role ?? "turn"),
+      text: String(row.text ?? ""),
+      caption: String(row.caption ?? row.text ?? ""),
+      seconds: typeof row.seconds === "number" ? row.seconds : 3,
+    };
+  });
+}
+
+export function normalizeHashtags(modelTags: string[], pool: string[], strategy: string): string[] {
+  const cleaned = modelTags
+    .map((tag) => tag.trim().replace(/\s+/g, ""))
+    .map((tag) => (tag.startsWith("#") ? tag : `#${tag}`))
+    .filter((tag) => tag.length > 1);
+  const extra = strategy === "plain-language" ? pool.slice(0, 1) : pool.slice(1, 2);
+  const merged = [...cleaned, ...extra.map((tag) => (tag.startsWith("#") ? tag : `#${tag}`))];
+  const unique: string[] = [];
+  for (const tag of merged) {
+    if (!unique.some((item) => item.toLowerCase() === tag.toLowerCase())) unique.push(tag);
+    if (unique.length >= 6) break;
+  }
+  if (!unique.some((tag) => tag.toLowerCase() === "#shorts")) unique.push("#Shorts");
+  return unique.slice(0, 8);
+}
+
+function round1(value: number): number {
+  return Math.round(value * 10) / 10;
+}

package/src/generate/script.ts

@@ -0,0 +1,152 @@
+import { fitBeats } from "@vfrey/contracts";
+import { assertNoAdvicePersona, assertNotVerbatim, assertSubjectBinding } from "@vfrey/contracts";
+import type { Beat, Candidate, ContentPackage, VariationPlan } from "@vfrey/contracts";
+import { normalizeHashtags } from "./index.js";
+
+/** A script the coding agent wrote itself. `tick --script FILE` reads one of these instead of calling a model. */
+export interface ScriptFile {
+  title: string;
+  hook: string;
+  lines: string[];
+  hashtags: string[];
+  subject?: string;
+}
+
+export const SCRIPT_LIMITS = { titleMax: 100, linesMin: 4, linesMax: 12, lineMax: 220, hashtagsMax: 8 } as const;
+
+export type ScriptCheck = { ok: true; script: ScriptFile } | { ok: false; field: string; message: string; fix: string };
+
+/** The JSON `npx vfrey tick --script-template` prints. */
+export function scriptTemplate(): string {
+  const example: ScriptFile = {
+    title: "Why honey never spoils",
+    hook: "Honey never spoils, and the reason is plain chemistry.",
+    lines: [
+      "Honey never spoils, and the reason is plain chemistry.",
+      "It holds very little water, so microbes cannot grow in it.",
+      "It is also acidic, which most bacteria dislike.",
+      "As honey ripens, an enzyme called glucose oxidase makes a little hydrogen peroxide.",
+      "And the bees seal the comb, so no new moisture gets in.",
+      "That is why honey never spoils. It can still crystallize, but crystals are not spoilage.",
+    ],
+    hashtags: ["#honey", "#science", "#facts"],
+    subject: "why honey never spoils",
+  };
+  return JSON.stringify(example, null, 2) + "\n";
+}
+
+function bad(field: string, message: string, fix: string): ScriptCheck {
+  return { ok: false, field, message, fix };
+}
+
+/** Checks the agent's JSON. The first bad field is named, with the way to fix it. */
+export function validateScript(text: string): ScriptCheck {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    return bad("file", `The script file is not valid JSON (${error instanceof Error ? error.message : String(error)}).`, "write one JSON object; `npx vfrey tick --script-template` prints an example.");
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return bad("file", "The script file must hold one JSON object.", "see `npx vfrey tick --script-template`.");
+  }
+  const body = raw as Record<string, unknown>;
+  const { titleMax, linesMin, linesMax, lineMax, hashtagsMax } = SCRIPT_LIMITS;
+  const title = typeof body.title === "string" ? body.title.trim() : "";
+  if (!title) return bad("title", "title is required.", `set "title" to a short string of ${titleMax} characters or fewer.`);
+  if (title.length > titleMax) return bad("title", `title is ${title.length} characters; the limit is ${titleMax}.`, `shorten "title" to ${titleMax} characters or fewer.`);
+  const hook = typeof body.hook === "string" ? body.hook.trim() : "";
+  if (!hook) return bad("hook", "hook is required.", 'set "hook" to the opening sentence of the video.');
+  if (!Array.isArray(body.lines)) return bad("lines", "lines must be an array of spoken lines.", `set "lines" to ${linesMin} to ${linesMax} strings.`);
+  if (body.lines.length < linesMin || body.lines.length > linesMax) {
+    return bad("lines", `lines has ${body.lines.length} entries; it needs ${linesMin} to ${linesMax}.`, `write ${linesMin} to ${linesMax} short spoken lines (6 to 10 is best).`);
+  }
+  const lines: string[] = [];
+  for (const [index, line] of body.lines.entries()) {
+    const value = typeof line === "string" ? line.trim() : "";
+    if (!value) return bad(`lines[${index}]`, `lines[${index}] must be a non-empty string.`, "remove the empty line or write it.");
+    if (value.length > lineMax) {
+      return bad(`lines[${index}]`, `lines[${index}] is ${value.length} characters; the limit is ${lineMax}.`, `split it into shorter spoken lines of ${lineMax} characters or fewer.`);
+    }
+    lines.push(value);
+  }
+  if (!Array.isArray(body.hashtags) || body.hashtags.length < 1 || body.hashtags.length > hashtagsMax) {
+    const found = Array.isArray(body.hashtags) ? body.hashtags.length : 0;
+    return bad("hashtags", `hashtags has ${found} entries; it needs 1 to ${hashtagsMax}.`, `set "hashtags" to 1 to ${hashtagsMax} strings that start with #.`);
+  }
+  const hashtags: string[] = [];
+  for (const [index, tag] of body.hashtags.entries()) {
+    const value = typeof tag === "string" ? tag.trim() : "";
+    if (!/^#\S+$/.test(value)) return bad(`hashtags[${index}]`, `hashtags[${index}] must start with # and have no spaces.`, 'write each hashtag like "#honey".');
+    hashtags.push(value);
+  }
+  const script: ScriptFile = { title, hook, lines, hashtags };
+  if (body.subject !== undefined) {
+    const subject = typeof body.subject === "string" ? body.subject.trim() : "";
+    if (!subject) return bad("subject", "subject must be a non-empty string when it is set.", 'remove "subject" or set it to the topic.');
+    script.subject = subject;
+  }
+  return { ok: true, script };
+}
+
+const MIDDLE_ROLES = ["setup", "turn", "evidence", "payoff"];
+const MAX_BEATS = 8;
+
+/** Spoken lines to beats. More than eight lines share beats, because a film holds eight; the voice still reads every line. */
+export function linesToBeats(lines: string[]): Array<{ role: string; text: string; caption: string; seconds: number }> {
+  const groups: string[][] = lines.map((line) => [line]);
+  while (groups.length > MAX_BEATS) {
+    // Join the neighbouring pair with the fewest words.
+    let at = 0;
+    let least = Infinity;
+    for (let i = 0; i < groups.length - 1; i += 1) {
+      const size = groups[i]!.join(" ").length + groups[i + 1]!.join(" ").length;
+      if (size < least) {
+        least = size;
+        at = i;
+      }
+    }
+    groups.splice(at, 2, [...groups[at]!, ...groups[at + 1]!]);
+  }
+  return groups.map((group, index) => {
+    const text = group.join(" ");
+    const words = text.split(/\s+/).filter(Boolean).length;
+    return {
+      role: index === 0 ? "hook" : index === groups.length - 1 ? "payoff" : MIDDLE_ROLES[(index - 1) % 3]!,
+      text,
+      caption: text,
+      seconds: Math.max(2, Math.round((words / 2.6) * 10) / 10),
+    };
+  });
+}
+
+/** The content package for an agent-written script, built the way the writer builds one. */
+export function packageFromScript(input: {
+  script: ScriptFile;
+  candidate: Candidate;
+  plan: VariationPlan;
+  hashtagPool: string[];
+}): Omit<ContentPackage, "voiceoverPath" | "outputPath"> & { beats: Beat[] } {
+  const { script, candidate, plan } = input;
+  const beats = fitBeats(linesToBeats(script.lines), plan.templateId);
+  const spoken = script.lines.join("\n");
+  const text = script.lines.join(" ");
+  assertSubjectBinding(text, candidate.title);
+  assertNotVerbatim(`${script.title} ${text}`, `${candidate.title} ${candidate.excerpt}`);
+  assertNoAdvicePersona(text);
+  const durationSec = Math.round(beats.reduce((sum, beat) => sum + beat.seconds, 0) * 10) / 10;
+  return {
+    candidate,
+    plan,
+    title: script.title,
+    hook: script.hook,
+    beats,
+    caption: script.hook,
+    description: text,
+    hashtags: normalizeHashtags(script.hashtags, input.hashtagPool, plan.hashtagStrategy),
+    thumbnailPrompt: script.title,
+    imagePrompts: [],
+    voiceoverScript: spoken,
+    durationSec,
+  };
+}

package/src/generate/title.ts

@@ -0,0 +1,78 @@
+import { copyTokens, significantTokens } from "@vfrey/contracts";
+
+/**
+ * Longest title the platforms accept, and the longest run of words the verbatim gate lets through (12).
+ * The gate counts tokens, not spaces ("Board's" is two, "17," is one), so the cap is on both.
+ */
+export const TITLE_MAX_CHARS = 100;
+export const TITLE_MAX_WORDS = 11;
+
+/**
+ * A source title or `--about` subject, made fit to be a video title: whitespace collapsed, trailing
+ * punctuation dropped, first letter capitalised, and cut at a word boundary to 100 characters (and 11 words,
+ * so a long title never trips the 12-word verbatim-copy gate).
+ */
+export function cleanTitle(value: string): string {
+  let text = value.replace(/\s+/g, " ").trim();
+  text = stripEdges(text);
+  const kept: string[] = [];
+  let tokenCount = 0;
+  for (const word of text.split(" ").filter(Boolean)) {
+    tokenCount += copyTokens(word).length;
+    if (kept.length >= TITLE_MAX_WORDS || tokenCount > TITLE_MAX_WORDS) break;
+    kept.push(word);
+  }
+  text = kept.join(" ");
+  const chars = Array.from(text);
+  if (chars.length > TITLE_MAX_CHARS) {
+    const cut = chars.slice(0, TITLE_MAX_CHARS);
+    const boundary = chars[TITLE_MAX_CHARS] === " " ? TITLE_MAX_CHARS : cut.lastIndexOf(" ");
+    text = (boundary > 0 ? cut.slice(0, boundary) : cut).join("");
+  }
+  text = stripEdges(text);
+  const first = Array.from(text)[0];
+  if (first && first.toUpperCase() !== first) text = first.toUpperCase() + text.slice(first.length);
+  return text;
+}
+
+function stripEdges(value: string): string {
+  let text = value.replace(/[\s:;,.\-–—]+$/u, "").trim();
+  // A title wrapped whole in matching quotes loses them.
+  const pairs: Array<[string, string]> = [['"', '"'], ["'", "'"], ["“", "”"], ["‘", "’"]];
+  for (const [open, close] of pairs) {
+    if (text.length > 2 && text.startsWith(open) && text.endsWith(close) && !text.slice(1, -1).includes(open)) {
+      text = text.slice(1, -1).replace(/[\s:;,.\-–—]+$/u, "").trim();
+    }
+  }
+  return text;
+}
+
+/** One hashtag made from the subject: its first word of four letters or more (else its first word). Null when it has none. */
+export function subjectTag(subject: string): string | null {
+  const words = subject.split(/\s+/).map((word) => word.replace(/[^\p{L}\p{N}]/gu, "")).filter(Boolean);
+  const word = words.find((item) => Array.from(item).length >= 4) ?? words[0];
+  return word ? `#${word.toLowerCase()}` : null;
+}
+
+/** The subject with a lowercase first letter, for use inside a sentence. Acronyms and mixed-case names are left alone. */
+export function lowerFirst(subject: string): string {
+  const first = subject.split(/\s+/)[0] ?? "";
+  if (/\p{Lu}/u.test(first.slice(1))) return subject;
+  const char = Array.from(subject)[0];
+  return char ? char.toLowerCase() + subject.slice(char.length) : subject;
+}
+
+/**
+ * The shortest form of the subject that still binds a script to it: the first two significant words
+ * (the gate needs two), lowercase, joined with "and". Falls back to the lowercase-initial subject.
+ */
+export function subjectGist(subject: string): string {
+  const words = Array.from(new Set(significantTokens(subject))).slice(0, 2);
+  return words.length > 0 ? words.join(" and ") : lowerFirst(subject);
+}
+
+/** A title for the stand-in writer: the cleaned subject plus ", briefly" when that fits in 100 characters. */
+export function standInTitle(subject: string): string {
+  const withTail = `${subject}, briefly`;
+  return Array.from(withTail).length <= TITLE_MAX_CHARS ? withTail : subject;
+}