@vfrey/vfrey 0.0.1 → 1.0.0-beta.1

package/src/tick-report.ts

@@ -0,0 +1,205 @@
+import path from "node:path";
+import { storedVideoPath } from "./project/videos.js";
+import { findDashboard, type Desk } from "./dashboard-link.js";
+import { ensureDashboard, type EnsureOptions, type EnsureResult } from "./dashboard-start.js";
+import type { Store } from "./queue/store.js";
+import type { CheckResult } from "./pipeline/review.js";
+
+export interface TickJobReport {
+  id: string;
+  series: string;
+  status: string;
+  mp4: string | null;
+  transcript: string | null;
+  /** The engine that rendered the video. Null when nothing rendered (dry run, or it failed first). */
+  engine: { id: string; label: string; source?: string } | null;
+  /** The rendered file's length in seconds, from ffprobe. Null when it was not probed (dry run, or no render). */
+  durationSec: number | null;
+  /** How the picture was made: an agent-written scene (kept at `dir`) or the default template. Null when nothing rendered. */
+  scene: { source: "agent" | "default"; dir: string | null; kind: "html" | "tsx" | null } | null;
+  /** The rendered file's size in pixels, from ffprobe. */
+  width: number | null;
+  height: number | null;
+  error: string | null;
+  publish: Array<{ platform: string; status: string; code: string | null; dryRun: boolean }>;
+  /** How the reply stage ended: `succeeded`, or `skipped` with a code such as `no_keys`. Null when it never ran. */
+  engage: { status: string; code: string | null } | null;
+  /** The run page on a dashboard that is listening now. Null when none is. */
+  runUrl: string | null;
+  /** Every quality-gate check that ran, with pass, fail, or skipped, and the Fix for a failure. Empty when none ran. */
+  checks: CheckResult[];
+  /** Who wrote the lines: the agent (`--script`), a configured model, or vfrey's stand-in writer. */
+  scriptSource: ScriptSource;
+  /** Set when the job waits for review (status `awaiting_review`): what the person runs to let it render, or to stop it. */
+  review: { approve: string; reject: string } | null;
+}
+
+export type ScriptSource = "agent" | "stand-in" | "model";
+
+export interface TickReport {
+  processed: number;
+  scriptSource: ScriptSource;
+  jobs: TickJobReport[];
+  /** Why a series made nothing, one entry per series. */
+  notes: Array<{ series: string; message: string }>;
+  /** The project this tick ran in, or null on the machine desk or under an env override. */
+  project?: { name: string; root: string } | null;
+}
+
+/** What a tick made, read back from the queue so the summary matches what the dashboard shows. */
+export function buildTickReport(store: Store, jobIds: string[], notes: Array<{ series: string; message: string }> = [], scriptSource: ScriptSource = "model", dataDir?: string): TickReport {
+  const jobs: TickJobReport[] = [];
+  for (const id of jobIds) {
+    const job = store.job(id);
+    if (!job) continue;
+    const content = job.payload.content;
+    const ended = store.eventsFor(id).filter((event) => event.stage === "engage" && event.status !== "running").at(-1);
+    const rendered = (job.payload as { rendered?: { durationSec: number; width: number; height: number } | null }).rendered ?? null;
+    const mp4 = content?.outputPath ? (dataDir ? storedVideoPath(dataDir, content.outputPath) : path.resolve(content.outputPath)) : null;
+    jobs.push({
+      id: job.id,
+      series: job.accountId,
+      status: job.status,
+      mp4,
+      engine: (job.payload as { engine?: { id: string; label: string; source?: string } }).engine ?? null,
+      transcript: mp4 && content?.voiceoverScript?.trim() ? mp4.replace(/\.mp4$/, ".txt") : null,
+      durationSec: rendered?.durationSec ?? null,
+      scene: sceneOf(job.payload),
+      width: rendered?.width ?? null,
+      height: rendered?.height ?? null,
+      error: job.lastError,
+      publish: Object.entries(job.payload.platforms).map(([platform, session]) => ({
+        platform,
+        status: session?.phase ?? "idle",
+        code: session?.errorCode ?? null,
+        // A dry-run publication carries the external id "dry-run": the video was never sent anywhere.
+        dryRun: session?.externalId === "dry-run",
+      })),
+      engage: ended ? { status: ended.status, code: ended.code } : null,
+      runUrl: null,
+      checks: checksOf(job.payload),
+      scriptSource,
+      review:
+        job.status === "awaiting_review"
+          ? { approve: `npx vfrey desk job approve --id ${job.id}`, reject: `npx vfrey desk job reject --id ${job.id} --reason "<why>"` }
+          : null,
+    });
+  }
+  return { processed: jobIds.length, scriptSource, jobs, notes };
+}
+
+/**
+ * Fills runUrl on every job so "See it:" is a live link. The tick ensures this desk's dashboard (the same code path as
+ * `vfrey open`, without the browser) unless VFREY_NO_DASHBOARD=1; with it set, a dashboard that is already listening is
+ * still used. A dashboard that cannot start never fails the tick: the line falls back to the command, and the reason goes to `warn`.
+ */
+export async function attachRunUrls(
+  report: TickReport,
+  desk: Desk,
+  env: Record<string, string | undefined> = process.env,
+  warn: (text: string) => void = () => {},
+  ensure: (options: EnsureOptions) => Promise<EnsureResult> = ensureDashboard,
+): Promise<void> {
+  if (report.jobs.length === 0) return;
+  let origin: string | null = null;
+  if (env.VFREY_NO_DASHBOARD === "1") {
+    origin = await findDashboard(desk, env);
+  } else {
+    const result = await ensure({ desk, env });
+    if (result.ok) origin = result.origin;
+    else warn(`✗ ${result.message}\nFix: ${result.fix}\n`);
+  }
+  if (origin) for (const job of report.jobs) job.runUrl = `${origin}/runs/${job.id}`;
+}
+
+function publishLine(item: TickJobReport["publish"][number], series: string): string {
+  if (item.status === "done" && item.dryRun) {
+    return `Dry run: nothing was uploaded to ${item.platform}. To post for real: npx vfrey desk series live --id ${series} --confirm <channel id>`;
+  }
+  if (item.status === "skipped" && item.code === "publish_off") return `Upload skipped on ${item.platform}: the series' publish switch is off`;
+  if (item.status === "skipped" && item.code === "missing_key") return `Upload skipped: no key for ${item.platform}`;
+  if (item.status === "skipped") return `Upload skipped on ${item.platform}${item.code ? `: ${item.code}` : ""}`;
+  if (item.status === "done") return `Published to ${item.platform}`;
+  if (item.status === "failed") return `Upload failed on ${item.platform}${item.code ? `: ${item.code}` : ""}`;
+  return `Upload to ${item.platform}: ${item.status}${item.code ? ` (${item.code})` : ""}`;
+}
+
+export interface TickReportView {
+  /** The run already asked for a video now (--now, --about, or --script). */
+  forced?: boolean;
+  /** The data folder this run used, for the VFREY_HOME hint. */
+  home?: string;
+}
+
+/** What to try next after an empty run. It never repeats the command that was just run. */
+function nextSteps(report: TickReport, view: TickReportView): string[] {
+  const steps: string[] = [];
+  const paused = report.notes.filter((note) => note.message === "paused");
+  for (const note of paused) steps.push(`Resume it: npx vfrey desk series resume --id ${note.series}`);
+  const busy = report.notes.some((note) => /in progress|waits to retry/.test(note.message));
+  if (busy) steps.push('Cancel that job (command above), or make a one-off video that does not wait for it: npx vfrey tick --now --about "<subject>"');
+  if (!view.forced && report.notes.some((note) => note.message.startsWith("not due"))) {
+    steps.push("Run `npx vfrey tick --now` to make a video now.");
+  }
+  if (view.forced) {
+    steps.push(`This desk is ${view.home ?? "~/.vfrey"}. If you expected another one, set VFREY_HOME to its folder.`);
+  }
+  return steps;
+}
+
+function checksOf(payload: unknown): CheckResult[] {
+  const checks = (payload as { checks?: unknown }).checks;
+  return Array.isArray(checks) ? (checks as CheckResult[]) : [];
+}
+
+function sceneOf(payload: unknown): TickJobReport["scene"] {
+  const scene = (payload as { scene?: { source?: string; dir?: string | null; kind?: "html" | "tsx" | null } }).scene;
+  if (!scene || (scene.source !== "agent" && scene.source !== "default")) return null;
+  return { source: scene.source, dir: scene.dir ?? null, kind: scene.kind ?? null };
+}
+
+export function formatTickReport(report: TickReport, view: TickReportView = {}): string {
+  if (report.jobs.length === 0) {
+    const why = report.notes.map((note) => `  ${note.series}: ${note.message}`);
+    return ["Nothing was made.", ...why, ...nextSteps(report, view), ""].join("\n");
+  }
+  const lines: string[] = [];
+  for (const job of report.jobs) {
+    if (job.review) {
+      const ran = job.checks.filter((check) => check.status !== "skipped").length;
+      lines.push(`⏸ Waiting for your review: ${job.series} (job ${job.id})`);
+      lines.push("  Script and scene passed the checks" + (ran > 0 ? ` (${ran} ran)` : "") + ". Nothing is rendered or published until you decide.");
+      lines.push(`  Approve: ${job.review.approve}`);
+      lines.push(`  Reject:  ${job.review.reject}`);
+      lines.push(job.runUrl ? `  Review it: ${job.runUrl.replace(/\/runs\/[^/]+$/, "/review")}` : "  Review it: npx vfrey open");
+      continue;
+    }
+    if (job.mp4 && !["rejected", "blocked", "dead"].includes(job.status)) {
+      const facts = job.durationSec !== null ? ` (${job.durationSec} s${job.width && job.height ? `, ${job.width}×${job.height}` : ""})` : "";
+      lines.push(`✓ Video ready: ${job.mp4}${facts}`);
+      if (job.engine) lines.push(`  Engine: ${job.engine.label}${job.engine.source === "project" ? " (from vfrey.json)" : ""}`);
+      if (job.scene) lines.push(`  Scene: ${job.scene.source === "agent" ? "agent-written" : "default template (plain text). Design one next time: npx vfrey scene init scenes/<idea>"}`);
+      if (job.transcript) lines.push(`  Transcript: ${job.transcript}`);
+      const ran = job.checks.filter((check) => check.status !== "skipped").length;
+      if (ran > 0) lines.push(`  Checks: ${ran} passed`);
+      if (job.scriptSource === "stand-in") {
+        lines.push("  Script: placeholder from vfrey's stand-in writer. For a real script, pass --script (see npx vfrey tick --script-template).");
+      }
+      for (const item of job.publish.filter((entry) => !(entry.status === "skipped" && !entry.code))) lines.push(`  ${publishLine(item, job.series)}`);
+      if (job.engage?.status === "skipped") {
+        lines.push(job.engage.code === "no_keys" ? "  Replies skipped: no platform keys" : `  Replies skipped${job.engage.code ? `: ${job.engage.code}` : ""}`);
+      }
+    } else {
+      // An engine failure carries its own Fix line. Show it on a line of its own, like the other refusals.
+      const [what, fix] = (job.error ?? "").split(" Fix: ");
+      lines.push(`✗ ${job.series}: no video (${job.status}${what ? `: ${what}` : ""})`);
+      if (fix) lines.push(`  Fix: ${fix}`);
+      for (const check of job.checks.filter((item) => item.status === "fail")) {
+        lines.push(`  Check failed: ${check.id} (${check.severity}): ${check.message}`);
+        if (check.fix && check.fix !== fix) lines.push(`    Fix: ${check.fix}`);
+      }
+    }
+    lines.push(job.runUrl ? `  See it: ${job.runUrl}` : `  See it: npx vfrey open ${job.id}`);
+  }
+  return lines.join("\n") + "\n";
+}

package/src/tts.ts

@@ -0,0 +1,124 @@
+import { execFile } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { mkdir, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { ConfigError, RetryableError } from "@vfrey/contracts";
+
+const execFileAsync = promisify(execFile);
+
+/** Each OpenAI voice name maps to its own macOS voice, so a series that rotates voices sounds different. */
+const LOCAL_VOICES: Record<string, string> = {
+  alloy: "Samantha",
+  ash: "Alex",
+  ballad: "Victoria",
+  coral: "Karen",
+  echo: "Daniel",
+  fable: "Moira",
+  nova: "Tessa",
+  onyx: "Fred",
+  sage: "Ava",
+  shimmer: "Allison",
+  verse: "Tom",
+};
+
+type Env = Record<string, string | undefined>;
+
+function onPath(command: string, env: Env): boolean {
+  for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+    if (!dir) continue;
+    try {
+      accessSync(path.join(dir, command), constants.X_OK);
+      return true;
+    } catch {
+      /* not here */
+    }
+  }
+  return false;
+}
+
+/** The sentence to show when the local voice cannot run on this machine, or null when it can. */
+export function localVoiceProblem(env: Env): { message: string; fix: string } | null {
+  if (!onPath("say", env)) {
+    return {
+      message: "The local voice needs the macOS `say` command, and it is not on this machine.",
+      fix: "Set TTS_PROVIDER=openai with TTS_API_KEY, or set TTS_PROVIDER=none for captions only.",
+    };
+  }
+  if (!onPath("ffmpeg", env)) {
+    return {
+      message: "The local voice needs `ffmpeg`, and it is not on this machine.",
+      fix: "Install ffmpeg, or set TTS_PROVIDER=none for captions only.",
+    };
+  }
+  return null;
+}
+
+export async function synthesize(input: {
+  provider: "openai" | "local" | "none";
+  baseUrl: string;
+  apiKey: string | null;
+  model: string;
+  voice: string;
+  text: string;
+  outputPath: string;
+  fetchImpl: typeof fetch;
+  /** Where the local voice looks for `say`. Defaults to process.env. */
+  env?: Env;
+}): Promise<string | null> {
+  if (input.provider === "none") return null;
+  if (input.provider === "local") return synthesizeLocal(input.text, input.outputPath, input.voice, input.env ?? process.env);
+  if (!input.apiKey) throw new ConfigError("tts_auth", "TTS_API_KEY is not set. Fix: set TTS_API_KEY, or set TTS_PROVIDER=none.");
+  await mkdir(path.dirname(input.outputPath), { recursive: true });
+  const response = await input.fetchImpl(`${input.baseUrl}/audio/speech`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${input.apiKey}`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({
+      model: input.model,
+      voice: input.voice,
+      input: input.text.slice(0, 4000),
+    }),
+  });
+  if (response.status === 429 || response.status >= 500) {
+    throw new RetryableError("tts_rate", `TTS HTTP ${response.status}`);
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new ConfigError("tts_auth", `TTS refused the key (HTTP ${response.status}). Fix: check TTS_API_KEY and its permissions.`);
+  }
+  if (response.status === 404) {
+    throw new ConfigError("tts_model", "TTS did not find the model or endpoint (HTTP 404). Fix: check TTS_MODEL and TTS_BASE_URL.");
+  }
+  if (!response.ok) throw new RetryableError("tts_error", `TTS HTTP ${response.status}`);
+  const bytes = Buffer.from(await response.arrayBuffer());
+  await writeFile(input.outputPath, bytes);
+  return input.outputPath;
+}
+
+function speakerVoice(voice: string): string {
+  const trimmed = voice.trim();
+  if (!trimmed) return "Samantha";
+  return LOCAL_VOICES[trimmed.toLowerCase()] ?? trimmed;
+}
+
+async function synthesizeLocal(text: string, outputPath: string, voice: string, env: Env): Promise<string> {
+  const problem = localVoiceProblem(env);
+  if (problem) throw new ConfigError("tts_local_missing", `${problem.message} Fix: ${problem.fix}`);
+  const spoken = text.replace(/\s+/g, " ").trim().slice(0, 4000);
+  if (!spoken) throw new RetryableError("tts_error", "There is no script to speak.");
+  await mkdir(path.dirname(outputPath), { recursive: true });
+  const wav = outputPath.replace(/\.[^.]+$/, "") + ".wav";
+  const aiff = wav.replace(/\.wav$/, ".aiff");
+  try {
+    await execFileAsync("say", ["-v", speakerVoice(voice), "-o", aiff, "--", spoken], { env: env as NodeJS.ProcessEnv });
+    await execFileAsync("ffmpeg", ["-y", "-i", aiff, "-ar", "44100", "-ac", "1", wav], { env: env as NodeJS.ProcessEnv });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "local voice failed";
+    throw new RetryableError("tts_error", message);
+  } finally {
+    await unlink(aiff).catch(() => undefined);
+  }
+  return wav;
+}

package/vendor/@vfrey/contracts/dist/account.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Accounts and billing: the shapes the vfrey server and the CLI agree on (spec 014).
+ * Types plus pure helpers. No I/O.
+ */
+/** What a paid feature is called on the wire. */
+export type Entitlement = "topics" | "creators" | "mail";
+export declare const ENTITLEMENTS: readonly Entitlement[];
+/** Plans live in server code. `mail` is an add-on, not a plan. */
+export type PlanId = "free" | "pro" | "research";
+export declare const PLAN_IDS: readonly PlanId[];
+/** A monthly meter, for example `topics.requests` or `creators.profiles`. */
+export type UsageMeter = string;
+export type OrgRole = "owner" | "admin" | "member";
+export interface UsageReading {
+    used: number;
+    /** `null` means the plan has no cap on this meter. */
+    limit: number | null;
+    /** ISO 8601 time the meter resets. */
+    resetsAt: string;
+}
+/** `GET /api/v1/me` */
+export interface MeResponse {
+    user: {
+        id: string;
+        email: string;
+    };
+    org: {
+        id: string;
+        name: string;
+        role: OrgRole;
+    };
+    plan: PlanId;
+    entitlements: Record<Entitlement, boolean>;
+    usage: Record<UsageMeter, UsageReading>;
+    /** Prepaid credits. `expiringSoon` is the part that expires within the warning window. */
+    credits: {
+        balance: number;
+        expiringSoon: number;
+    };
+    upgradeUrl: string;
+}
+export type ApiErrorCode = "unauthorized" | "plan_required" | "limit_reached" | "credits_required" | "capacity_paused" | "rate_limited" | "bad_request" | "not_found" | "internal";
+/** Every non-2xx API response has this body. */
+export interface ApiError {
+    error: {
+        code: ApiErrorCode | (string & {});
+        message: string;
+        upgradeUrl?: string;
+        /** ISO 8601 time a `limit_reached` meter resets. */
+        resetsAt?: string;
+        /** `credits_required` (402): where to buy credits, what the call costs, and what the org has. */
+        buyCreditsUrl?: string;
+        required?: number;
+        balance?: number;
+    };
+}
+export declare function isApiError(value: unknown): value is ApiError;
+/** The one client id the CLI uses for the device flow. */
+export declare const CLI_CLIENT_ID = "vfrey-cli";
+/** `POST /api/v1/device/code` */
+export interface DeviceCodeRequest {
+    client_id: string;
+}
+export interface DeviceCodeResponse {
+    device_code: string;
+    /** Shown as `ABCD-EFGH`. */
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    /** Seconds. 600 today. */
+    expires_in: number;
+    /** Seconds between polls. 5 today. */
+    interval: number;
+}
+/** `POST /api/v1/device/token` */
+export interface DeviceTokenRequest {
+    device_code: string;
+    client_id: string;
+}
+export type DeviceTokenErrorCode = "authorization_pending" | "slow_down" | "access_denied" | "expired_token";
+export interface DeviceTokenSuccess {
+    access_token: string;
+    token_type: "bearer";
+    org: {
+        id: string;
+        name: string;
+    };
+}
+export interface DeviceTokenError {
+    error: DeviceTokenErrorCode;
+}
+export type DeviceTokenResponse = DeviceTokenSuccess | DeviceTokenError;
+export declare function isDeviceTokenSuccess(value: DeviceTokenResponse): value is DeviceTokenSuccess;
+/** Format a raw 8-character user code as `ABCD-EFGH`. Other lengths pass through upper-cased. */
+export declare function formatUserCode(code: string): string;
+/** An API token starts with this prefix. Used to redact, never to authenticate. */
+export declare const API_TOKEN_PREFIX = "vfr_";

package/vendor/@vfrey/contracts/dist/account.js

@@ -0,0 +1,27 @@
+/**
+ * Accounts and billing: the shapes the vfrey server and the CLI agree on (spec 014).
+ * Types plus pure helpers. No I/O.
+ */
+export const ENTITLEMENTS = ["topics", "creators", "mail"];
+export const PLAN_IDS = ["free", "pro", "research"];
+export function isApiError(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const error = value.error;
+    if (typeof error !== "object" || error === null)
+        return false;
+    const e = error;
+    return typeof e.code === "string" && typeof e.message === "string";
+}
+/** The one client id the CLI uses for the device flow. */
+export const CLI_CLIENT_ID = "vfrey-cli";
+export function isDeviceTokenSuccess(value) {
+    return "access_token" in value;
+}
+/** Format a raw 8-character user code as `ABCD-EFGH`. Other lengths pass through upper-cased. */
+export function formatUserCode(code) {
+    const clean = code.replace(/[\s-]/g, "").toUpperCase();
+    return clean.length === 8 ? `${clean.slice(0, 4)}-${clean.slice(4)}` : clean;
+}
+/** An API token starts with this prefix. Used to redact, never to authenticate. */
+export const API_TOKEN_PREFIX = "vfr_";

package/vendor/@vfrey/contracts/dist/checks.d.ts

@@ -0,0 +1,8 @@
+export declare const REVIEW_CHECK_IDS: readonly ["pace", "frames", "style", "svg", "logo", "copy", "disclosure"];
+export type ReviewCheckId = (typeof REVIEW_CHECK_IDS)[number];
+export type ReviewFailureStatus = "rejected" | "blocked";
+export interface ReviewFailure {
+    id: ReviewCheckId;
+    status: ReviewFailureStatus;
+    reason: string;
+}

package/vendor/@vfrey/contracts/dist/checks.js

@@ -0,0 +1 @@
+export const REVIEW_CHECK_IDS = ["pace", "frames", "style", "svg", "logo", "copy", "disclosure"];

package/vendor/@vfrey/contracts/dist/credentials/crypto.d.ts

@@ -0,0 +1,4 @@
+export declare function credentialsKey(raw: string): Buffer;
+export declare function encryptSecret(plain: string, key: Buffer): string;
+export declare function decryptSecret(stored: string, key: Buffer): string;
+export declare function isEncrypted(value: string | null | undefined): boolean;

package/vendor/@vfrey/contracts/dist/credentials/crypto.js

@@ -0,0 +1,38 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+const PREFIX = "enc:v1";
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+export function credentialsKey(raw) {
+    const key = Buffer.from(raw, "base64");
+    if (key.length !== 32) {
+        throw new Error("CREDENTIALS_KEY must be 32 bytes, base64-encoded");
+    }
+    return key;
+}
+export function encryptSecret(plain, key) {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", key, iv, { authTagLength: TAG_BYTES });
+    const data = Buffer.concat([cipher.update(plain, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return [PREFIX, iv.toString("base64url"), tag.toString("base64url"), data.toString("base64url")].join(":");
+}
+export function decryptSecret(stored, key) {
+    const parts = stored.split(":");
+    if (parts.length !== 5 || parts[0] !== "enc" || parts[1] !== "v1") {
+        throw new Error("Stored credential is not enc:v1");
+    }
+    const iv = Buffer.from(parts[2] ?? "", "base64url");
+    const tag = Buffer.from(parts[3] ?? "", "base64url");
+    if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) {
+        throw new Error("Stored credential is not enc:v1 (bad IV or tag length)");
+    }
+    const decipher = createDecipheriv("aes-256-gcm", key, iv, { authTagLength: TAG_BYTES });
+    decipher.setAuthTag(tag);
+    return Buffer.concat([
+        decipher.update(Buffer.from(parts[4] ?? "", "base64url")),
+        decipher.final(),
+    ]).toString("utf8");
+}
+export function isEncrypted(value) {
+    return typeof value === "string" && value.startsWith(`${PREFIX}:`);
+}

package/vendor/@vfrey/contracts/dist/domain/advice-persona.d.ts

@@ -0,0 +1,10 @@
+/**
+ * One definition of "the script or reply claims to be a licensed professional
+ * giving advice". Shared by the disclosure gate and the reply safety gate.
+ *
+ * It matches first-person claims ("As a doctor, I recommend", "I'm your
+ * lawyer", "I am a licensed nurse", "Financial advisor here"). Third-person
+ * mentions ("my doctor said", "ask your lawyer") do not match.
+ */
+export declare const ADVICE_PERSONA: RegExp;
+export declare function claimsAdvicePersona(text: string): boolean;

package/vendor/@vfrey/contracts/dist/domain/advice-persona.js

@@ -0,0 +1,24 @@
+/**
+ * One definition of "the script or reply claims to be a licensed professional
+ * giving advice". Shared by the disclosure gate and the reply safety gate.
+ *
+ * It matches first-person claims ("As a doctor, I recommend", "I'm your
+ * lawyer", "I am a licensed nurse", "Financial advisor here"). Third-person
+ * mentions ("my doctor said", "ask your lawyer") do not match.
+ */
+const PRO = "(?:doctor|physician|nurse|lawyer|attorney|therapist|psychiatrist|psychologist|cpa|(?:financial|investment|tax)\\s+(?:advis[eo]r|planner))";
+const MOD = "(?:[a-z-]+\\s+){0,3}";
+const APOS = "['’]";
+export const ADVICE_PERSONA = new RegExp([
+    // "as your doctor"
+    `\\bas\\s+your\\s+${MOD}${PRO}\\b`,
+    // "as a doctor, I recommend ..." / "as a doctor myself"
+    `\\bas\\s+an?\\s+${MOD}${PRO}\\b(?:\\s+myself\\b|[^.!?]{0,30}\\b(?:i|i${APOS}(?:m|d|ve|ll)|my|me|we|let\\s+me)\\b)`,
+    // "I'm your doctor", "I am a licensed nurse", "I'm the attorney"
+    `\\bi(?:\\s+am|${APOS}m)\\s+(?:your|an?|the)\\s+${MOD}${PRO}\\b`,
+    // "Doctor here:", "Financial advisor speaking"
+    `(?:^|[.!?]\\s+)${PRO}\\s+(?:here|speaking)\\b`,
+].join("|"), "i");
+export function claimsAdvicePersona(text) {
+    return ADVICE_PERSONA.test(text);
+}

package/vendor/@vfrey/contracts/dist/domain/backoff.d.ts

@@ -0,0 +1,13 @@
+export interface BackoffInput {
+    attempt: number;
+    baseMs?: number;
+    capMs?: number;
+    /** 0..1 fraction of the delay added as deterministic jitter when random is omitted. */
+    jitterRatio?: number;
+    random?: () => number;
+    /** Server-provided wait. Never capped. */
+    retryAfterMs?: number;
+}
+/** Exponential backoff with a cap. Attempt 1 is the first retry. */
+export declare function backoffMs(input: BackoffInput): number;
+export declare function parseRetryAfter(header: string | null, nowMs: number): number | undefined;

package/vendor/@vfrey/contracts/dist/domain/backoff.js

@@ -0,0 +1,27 @@
+/** Exponential backoff with a cap. Attempt 1 is the first retry. */
+export function backoffMs(input) {
+    const base = input.baseMs ?? 2_000;
+    const cap = input.capMs ?? 15 * 60_000;
+    const jitterRatio = input.jitterRatio ?? 0.2;
+    const attempt = Math.max(1, input.attempt);
+    const exponential = Math.min(cap, base * 2 ** (attempt - 1));
+    const random = input.random ?? Math.random;
+    const jitter = Math.floor(exponential * jitterRatio * random());
+    const computed = Math.min(cap, exponential + jitter);
+    if (input.retryAfterMs !== undefined && Number.isFinite(input.retryAfterMs) && input.retryAfterMs > 0) {
+        // A server-provided Retry-After is honored in full. Only computed backoff is capped.
+        return Math.max(computed, input.retryAfterMs);
+    }
+    return computed;
+}
+export function parseRetryAfter(header, nowMs) {
+    if (!header)
+        return undefined;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const when = Date.parse(header);
+    if (Number.isFinite(when))
+        return Math.max(0, when - nowMs);
+    return undefined;
+}

package/vendor/@vfrey/contracts/dist/domain/cadence.d.ts

@@ -0,0 +1,29 @@
+export interface Cadence {
+    timezone: string;
+    /** Minimum hours between successful publishes for this account. */
+    minHoursBetweenPosts: number;
+    maxPostsPerDay: number;
+    /** Local windows, "HH:MM-HH:MM", start inclusive, end exclusive. Empty means all day. */
+    windows: string[];
+}
+export interface ZonedParts {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+}
+export declare function zonedParts(date: Date, timeZone: string): ZonedParts;
+export declare function localDayKey(date: Date, timeZone: string): string;
+/** Throws ConfigError for a timezone Intl rejects, malformed windows, or non-sensible limits. */
+export declare function validateCadence(cadence: Cadence): void;
+export interface CadenceDecision {
+    due: boolean;
+    reason: string;
+}
+export declare function cadenceDecision(input: {
+    cadence: Cadence;
+    now: Date;
+    lastPublishedAt: Date | null;
+    postsOnLocalDay: number;
+}): CadenceDecision;