@crievo/omni 0.0.0-stage → 0.1.0

package/tools/lib/omnichat/text.mjs

@@ -0,0 +1,315 @@
+/* The rule's texts: the DM, the public reply, the rule checks and the
+   classifier prompt for uncertain comments. Pure. */
+
+import { buttonMessage } from "../platforms/instagram.mjs";
+import { BUTTON_TEXT_LIMIT, BUTTON_TITLE_LIMIT, DM_BYTE_LIMIT } from "./config.mjs";
+
+/** @typedef {import("./match.mjs").Rule} Rule */
+/** @typedef {import("./config.mjs").OmnichatConfig} OmnichatConfig */
+
+/**
+ * {username} (legacy {usuario}); without the name (the API did not send it) the comma and @
+ * before it go too: "Oi, @{username}!" becomes "Oi!".
+ * @param {string} t @param {string | null | undefined} username
+ */
+export const withUsername = (t, username) =>
+  username
+    ? t.replaceAll("{username}", username).replaceAll("{usuario}", username)
+    : t.replace(/[,\s]*@?\{(?:username|usuario)\}/g, "").replace(/^[,\s]+/, "");
+
+/**
+ * The shortcode of a post link.
+ * @param {string | null | undefined} url
+ */
+export const postCode = url => /\/(?:reels?|p|tv)\/([\w-]+)/.exec(url ?? "")?.[1] ?? null;
+
+/** The sample Reel link (terminal previews, and the worst case of the byte limit). */
+export const SAMPLE_POST = "https://www.instagram.com/reel/XXXXXXXXXXX/";
+/** The sample carousel link. */
+export const SAMPLE_CAROUSEL = "https://www.instagram.com/p/XXXXXXXXXXX/";
+
+/**
+ * The DM. The post is not a message in the conversation, so it is quoted by its link,
+ * which Instagram shows as the post card: {post} puts it wherever the DM wants; without
+ * {post}, quote_post puts it on the first line. A DM that already has the link does not repeat it.
+ * @param {Rule} rule @param {string | null | undefined} username @param {string | null | undefined} post
+ * @param {{ default_dm: string }} C
+ */
+export function dmText(rule, username, post, C) {
+  let t = withUsername(rule.dm || C.default_dm, username);
+  if (rule.link) t = t.includes("{link}") ? t.replaceAll("{link}", rule.link) : `${t.trimEnd()}\n${rule.link}`;
+  t = t.replaceAll("{link}", "");
+  if (t.includes("{post}")) t = post ? t.replaceAll("{post}", post) : t.replace(/[ \t]*\{post\}[ \t]*/g, " ");
+  else if (rule.quote_post && post && !t.includes(`/${postCode(post)}/`)) t = `${post}\n${t.trim()}`;
+  return t.trim();
+}
+
+/** @param {Rule} rule @param {{ default_link_label: string }} C */
+export const linkLabel = (rule, C) => (rule.link_label || C.default_link_label).trim();
+
+/** Does the link go in a button? Only with a link to open. @param {Rule} rule */
+export const linkInButton = rule => !!(rule.link_button && rule.link);
+
+/**
+ * The DM's text when the link goes in a button: {link} comes out, and so does what was left
+ * hanging before it ("Aqui está o link: {link}" becomes "Aqui está o link"). quote_post does not apply: inside
+ * a button message the post's link is plain text, without the card ({post} written in the DM still goes).
+ * @param {Rule} rule @param {string | null | undefined} username @param {string | null | undefined} post
+ * @param {{ default_dm: string }} C
+ */
+export function dmTextWithoutLink(rule, username, post, C) {
+  const dm = (rule.dm || C.default_dm).replace(/[\s:–-]*\{link\}/g, "");
+  /* a DM that was only {link} has nothing left: empty, not the default DM */
+  return dm.trim() ? dmText({ ...rule, link: "", quote_post: false, dm }, username, post, C) : "";
+}
+
+/**
+ * What the delivery sends: the DM as text, or with link_button the text and a button that opens the link.
+ * @param {Rule} rule @param {string | null | undefined} username @param {string | null | undefined} post
+ * @param {{ default_dm: string, default_link_label: string }} C
+ * @returns {string | Record<string, any>}
+ */
+export const deliveryMessage = (rule, username, post, C) =>
+  linkInButton(rule)
+    ? buttonMessage(dmTextWithoutLink(rule, username, post, C), [{ title: linkLabel(rule, C), url: rule.link }])
+    : dmText(rule, username, post, C);
+
+/**
+ * The delivery as one line, for previews: the text and [label] when the link goes in a button.
+ * @param {Rule} rule @param {string | null | undefined} username @param {string | null | undefined} post
+ * @param {{ default_dm: string, default_link_label: string }} C
+ */
+export const deliveryPreview = (rule, username, post, C) =>
+  linkInButton(rule)
+    ? `${dmTextWithoutLink(rule, username, post, C)} [${linkLabel(rule, C)} → ${rule.link}]`
+    : dmText(rule, username, post, C);
+
+/**
+ * Does the rule gate the delivery behind a button tap (and, optionally, a follow)?
+ * @param {Rule} rule
+ */
+export const gateOn = rule => !!(rule.button || rule.require_follow);
+
+/**
+ * The DM that carries the button, before the tap.
+ * @param {Rule} rule @param {string | null | undefined} username @param {{ default_opening_dm: string }} C
+ */
+export const openingText = (rule, username, C) =>
+  withUsername(rule.opening_dm || C.default_opening_dm, username).trim();
+
+/**
+ * What goes out when the person taps without following the account.
+ * @param {Rule} rule @param {string | null | undefined} username @param {{ default_not_following_dm: string }} C
+ */
+export const notFollowingText = (rule, username, C) =>
+  withUsername(rule.not_following_dm || C.default_not_following_dm, username).trim();
+
+/** @param {Rule} rule @param {{ default_button_label: string }} C */
+export const buttonLabel = (rule, C) => (rule.button_label || C.default_button_label).trim();
+
+/** @param {Rule} rule @param {{ default_retry_label: string }} C */
+export const retryLabel = (rule, C) => (rule.retry_label || C.default_retry_label).trim();
+
+/**
+ * Whoever taps "já sigo" without following gets, the second time, a button that delivers anyway: on unless
+ * the rule says follow_skip false.
+ * @param {Rule} rule
+ */
+export const followSkipOn = rule => rule.follow_skip !== false;
+
+/** @param {Rule} rule @param {{ default_skip_label: string }} C */
+export const skipLabel = (rule, C) => (rule.skip_label || C.default_skip_label).trim();
+
+/**
+ * What "Receber sem seguir" delivers: the rule's delivery (link, link button, quote_post) with the skip DM as text.
+ * @param {Rule} rule @param {string | null | undefined} username @param {string | null | undefined} post
+ * @param {{ default_dm: string, default_skip_dm: string, default_link_label: string }} C
+ * @returns {string | Record<string, any>}
+ */
+export const skipDeliveryMessage = (rule, username, post, C) =>
+  deliveryMessage({ ...rule, dm: rule.skip_dm || C.default_skip_dm }, username, post, C);
+
+/**
+ * The skip delivery as one line, for previews.
+ * @param {Rule} rule @param {string | null | undefined} username @param {string | null | undefined} post
+ * @param {{ default_dm: string, default_skip_dm: string, default_link_label: string }} C
+ */
+export const skipDeliveryPreview = (rule, username, post, C) =>
+  deliveryPreview({ ...rule, dm: rule.skip_dm || C.default_skip_dm }, username, post, C);
+
+/**
+ * One public reply picked at random, or null (DM only).
+ * @param {Rule} rule @param {string | null | undefined} username
+ * @param {{ default_public_replies: string[] }} C @param {() => number} [random]
+ */
+export function publicReplyText(rule, username, C, random = Math.random) {
+  const list = rule.public_replies ?? C.default_public_replies;
+  return list.length ? withUsername(list[Math.floor(random() * list.length)], username).trim() : null;
+}
+
+/**
+ * A new rule: born disabled.
+ * @param {OmnichatConfig} C
+ * @returns {Rule}
+ */
+export const newRule = C => ({
+  enabled: false,
+  keywords: [],
+  any_comment: false,
+  link: "",
+  dm: C.default_dm,
+  public_replies: C.default_public_replies,
+  quote_post: !!C.quote_post,
+  button: false,
+  require_follow: false,
+});
+
+/**
+ * What doesn't add up in a rule (empty: it can be enabled).
+ * @param {Rule} r @param {OmnichatConfig} C
+ * @returns {string[]}
+ */
+export function ruleProblems(r, C) {
+  const p = [];
+  if (!r.any_comment && !(r.keywords ?? []).some(x => x.trim()))
+    p.push("diga a palavra-chave (--keyword QUERO) ou --any");
+  if (r.link && !/^https?:\/\/\S+$/.test(r.link))
+    p.push(`link precisa começar com http:// ou https:// (veio "${r.link}")`);
+  if (
+    !r.link &&
+    !/\S/.test((r.dm || C.default_dm).replaceAll("{link}", "").replaceAll("{username}", "").replaceAll("{usuario}", ""))
+  )
+    p.push("sem link, a DM precisa de texto");
+  /* a placeholder left to fill in, like the default DM's <artefato>: never goes out as is */
+  const blank = /<[^<>\s]+>/.exec(r.dm || C.default_dm)?.[0];
+  if (blank) p.push(`a DM ainda tem ${blank}: troque pelo que ela entrega`);
+  if (!r.link && (r.dm || C.default_dm).includes("{link}"))
+    p.push("a DM usa {link}, mas a regra não tem link (--link https://…)");
+  /* the worst case: a username with Instagram's maximum length (30) */
+  const bytes = new TextEncoder().encode(dmText(r, "x".repeat(30), SAMPLE_POST, C)).byteLength;
+  if (bytes > DM_BYTE_LIMIT) p.push(`a DM passa do limite do Instagram: ${bytes} de ${DM_BYTE_LIMIT} bytes`);
+  if (r.link_button) {
+    if (!r.link) p.push("o botão de link precisa do link (--link https://…)");
+    if (linkLabel(r, C).length > BUTTON_TITLE_LIMIT)
+      p.push(`o rótulo do botão de link passa de ${BUTTON_TITLE_LIMIT} caracteres`);
+    if (r.link && dmTextWithoutLink(r, "x".repeat(30), SAMPLE_POST, C).length > BUTTON_TEXT_LIMIT)
+      p.push(`com o botão de link, a DM passa de ${BUTTON_TEXT_LIMIT} caracteres`);
+    if (r.link && !dmTextWithoutLink(r, "x".repeat(30), SAMPLE_POST, C))
+      p.push("com o botão de link, a DM precisa de texto além do {link}");
+  }
+  if (gateOn(r)) {
+    const who = "x".repeat(30);
+    if (openingText(r, who, C).length > BUTTON_TEXT_LIMIT)
+      p.push(`o texto acima do botão passa de ${BUTTON_TEXT_LIMIT} caracteres`);
+    if (buttonLabel(r, C).length > BUTTON_TITLE_LIMIT)
+      p.push(`o rótulo do botão passa de ${BUTTON_TITLE_LIMIT} caracteres`);
+    if (r.require_follow) {
+      if (notFollowingText(r, who, C).length > BUTTON_TEXT_LIMIT)
+        p.push(`a mensagem de quem não segue passa de ${BUTTON_TEXT_LIMIT} caracteres`);
+      if (retryLabel(r, C).length > BUTTON_TITLE_LIMIT)
+        p.push(`o rótulo do botão de quem não segue passa de ${BUTTON_TITLE_LIMIT} caracteres`);
+      if (followSkipOn(r)) {
+        if (skipLabel(r, C).length > BUTTON_TITLE_LIMIT)
+          p.push(`o rótulo do botão de receber sem seguir passa de ${BUTTON_TITLE_LIMIT} caracteres`);
+        const skipDm = { ...r, dm: r.skip_dm || C.default_skip_dm };
+        const skipBytes = new TextEncoder().encode(dmText(skipDm, who, SAMPLE_POST, C)).byteLength;
+        if (skipBytes > DM_BYTE_LIMIT)
+          p.push(
+            `a mensagem de receber sem seguir passa do limite do Instagram: ${skipBytes} de ${DM_BYTE_LIMIT} bytes`,
+          );
+        if (r.link_button && r.link && dmTextWithoutLink(skipDm, who, SAMPLE_POST, C).length > BUTTON_TEXT_LIMIT)
+          p.push(`com o botão de link, a mensagem de receber sem seguir passa de ${BUTTON_TEXT_LIMIT} caracteres`);
+      }
+    }
+  }
+  for (const t of r.public_replies ?? []) if (t.length > 2200) p.push("resposta pública com mais de 2.200 caracteres");
+  return p;
+}
+
+/**
+ * A list from an array or a comma/newline separated text.
+ * @param {unknown} v
+ * @returns {string[]}
+ */
+export const toList = v =>
+  (Array.isArray(v) ? v : String(v ?? "").split(/[,\n]/)).map(s => String(s).trim()).filter(Boolean);
+
+/**
+ * Applies the studio's JSON edit to a rule (only the fields present). Mutates and returns `r`.
+ * @param {Rule} r @param {Record<string, any>} j
+ */
+export function applyRuleJson(r, j) {
+  if (j.keywords !== undefined) r.keywords = toList(j.keywords);
+  if (j.any_comment !== undefined) r.any_comment = !!j.any_comment;
+  if (j.link !== undefined) r.link = String(j.link ?? "").trim();
+  if (j.dm !== undefined) r.dm = String(j.dm ?? "").trim();
+  if (j.public_replies !== undefined)
+    r.public_replies = toList(
+      Array.isArray(j.public_replies) ? j.public_replies : String(j.public_replies ?? "").split("\n"),
+    );
+  if (j.generic_phrases !== undefined) r.generic_phrases = j.generic_phrases !== false;
+  if (j.offer !== undefined) r.offer = String(j.offer ?? "").trim();
+  if (j.quote_post !== undefined) r.quote_post = j.quote_post === true;
+  if (j.button !== undefined) r.button = j.button === true;
+  if (j.require_follow !== undefined) r.require_follow = j.require_follow === true;
+  if (j.link_button !== undefined) r.link_button = j.link_button === true;
+  if (j.follow_skip !== undefined) r.follow_skip = j.follow_skip !== false;
+  for (const k of [
+    "opening_dm",
+    "button_label",
+    "not_following_dm",
+    "retry_label",
+    "link_label",
+    "skip_label",
+    "skip_dm",
+  ])
+    if (j[k] !== undefined) r[k] = String(j[k] ?? "").trim();
+  if (j.already_replied !== undefined) r.already_replied = j.already_replied === "send" ? "send" : "skip";
+  if (j.already_replied_if !== undefined)
+    r.already_replied_if = toList(
+      Array.isArray(j.already_replied_if) ? j.already_replied_if : String(j.already_replied_if ?? "").split("\n"),
+    );
+  return r;
+}
+
+/**
+ * What the post offers, for the classifier: the rule's offer, the caption, the link and the keyword.
+ * @param {Rule} rule @param {Record<string, any> | null} pub publication.json
+ */
+export function offerText(rule, pub) {
+  const p = pub ?? {};
+  const caption = String(p.caption || [p.title, p.description].filter(Boolean).join("\n") || "").slice(0, 600);
+  return [
+    rule.offer,
+    caption && `Legenda do post: ${caption}`,
+    rule.link && `O que a DM manda: ${rule.link}`,
+    (rule.keywords ?? []).length && `Palavra-chave pedida no post: ${rule.keywords.join(", ")}`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+/**
+ * The prompt that asks a model which uncertain comments request the delivery.
+ * The input is `classifyInput(items)`; the answer is parsed by `parseClassification`.
+ * @param {string} offer
+ */
+export const classifyPrompt =
+  offer => `Você lê comentários de um post do Instagram. Quem comenta pedindo recebe por mensagem direta o que o post oferece:
+
+${offer}
+
+Para cada comentário da entrada (um objeto {id: texto}), diga se a pessoa está pedindo para receber isso (true) ou se "quero", "manda", "link" e afins aparecem por outro motivo, como um desejo qualquer, um elogio ou uma conversa (false). "eu quero que faça sol hoje" é false; "quero muito testar isso" é true. Na dúvida, false.
+Responda só com um objeto JSON {"<id>": true|false}, sem markdown nem comentário.`;
+
+/**
+ * @param {Array<[string, { text: string }]>} items
+ */
+export const classifyInput = items => JSON.stringify(Object.fromEntries(items.map(([id, c]) => [id, c.text])));
+
+/**
+ * The model's answer as { id: boolean }, or throws when it is not JSON.
+ * @param {string} out
+ * @returns {Record<string, boolean>}
+ */
+export const parseClassification = out => JSON.parse(/** @type {string} */ (/\{[\s\S]*\}/.exec(out)?.[0]));

package/tools/lib/omnichat/webhook.mjs

@@ -0,0 +1,166 @@
+/* ============================================================================
+   The Instagram messaging webhook, as a pure request handler: the verification handshake, the
+   signature, the taps in the payload and one `handleTap` per tap. The CLI serves it on a local port
+   (behind a tunnel); a cloud function can call the same `handleWebhook` with its own storage.
+   ============================================================================ */
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { withDefaults } from "../http.mjs";
+import { handleTap, parseTapPayload } from "./gate.mjs";
+
+/** @typedef {import("../http.mjs").Deps} Deps */
+/** @typedef {import("./config.mjs").OmnichatConfig} OmnichatConfig */
+/** @typedef {import("./match.mjs").Rule} Rule */
+/** @typedef {import("./gate.mjs").Tap} Tap */
+/** @typedef {import("../platforms/instagram.mjs").InstagramClient} InstagramClient */
+
+/** The webhook fields the gate needs: the tap (`messaging_postbacks`) and the quick reply (`messages`). */
+export const WEBHOOK_FIELDS = ["messages", "messaging_postbacks"];
+
+/**
+ * The handshake Meta does when the callback URL is saved: echoes `hub.challenge` if the token matches.
+ * @param {Record<string, string | undefined>} query @param {string} verifyToken
+ * @returns {string | null}
+ */
+export function verifyChallenge(query, verifyToken) {
+  if (!verifyToken || query["hub.mode"] !== "subscribe" || query["hub.verify_token"] !== verifyToken) return null;
+  return query["hub.challenge"] ?? "";
+}
+
+/**
+ * `X-Hub-Signature-256` is `sha256=` + the HMAC-SHA256 of the raw body with the app secret.
+ * @param {string | Uint8Array} raw @param {string | null | undefined} header @param {string} secret
+ */
+export function validSignature(raw, header, secret) {
+  if (!secret || !header?.startsWith("sha256=")) return false;
+  const want = createHmac("sha256", secret).update(raw).digest();
+  const got = Buffer.from(header.slice(7), "hex");
+  return got.length === want.length && timingSafeEqual(got, want);
+}
+
+/**
+ * The taps of a webhook payload: button postbacks and quick replies whose payload is ours.
+ * Echoes (the account's own messages) and everything else are left out.
+ * @param {any} body
+ * @returns {Array<Tap & { recipientId: string | null }>}
+ */
+export function tapsIn(body) {
+  /** @type {Array<Tap & { recipientId: string | null }>} */
+  const taps = [];
+  for (const entry of body?.entry ?? []) {
+    for (const m of entry.messaging ?? []) {
+      if (m.message?.is_echo) continue;
+      const mid = m.postback?.mid ?? m.message?.mid ?? null;
+      const parsed = parseTapPayload(m.postback?.payload ?? m.message?.quick_reply?.payload);
+      if (!parsed || !m.sender?.id) continue;
+      taps.push({ ...parsed, senderId: String(m.sender.id), mid, recipientId: m.recipient?.id ?? entry.id ?? null });
+    }
+  }
+  return taps;
+}
+
+/**
+ * The posts with a new comment from someone else (the `comments` field): each one deserves a pass now,
+ * instead of waiting for the next check. The account's own comments (its public replies) are left out.
+ * @param {any} body
+ * @returns {string[]} media ids, without repeats
+ */
+export function commentedMedia(body) {
+  const media = new Set();
+  for (const entry of body?.entry ?? []) {
+    for (const ch of entry.changes ?? []) {
+      const v = ch.value ?? {};
+      if (ch.field !== "comments" || !v.media?.id) continue;
+      if (v.from?.id && String(v.from.id) === String(entry.id)) continue;
+      media.add(String(v.media.id));
+    }
+  }
+  return [...media];
+}
+
+/**
+ * What the handler needs to work on one post: its rule and record, behind the caller's lock/storage.
+ * `withRecord` loads the rule and the record, runs `fn`, saves the record when `fn` returns true.
+ * @typedef {object} Target
+ * @property {string} name for the log
+ * @property {string | null} post the post's link
+ * @property {(fn: (s: { rule: Rule, record: any }) => Promise<boolean>) => Promise<void>} withRecord
+ */
+
+/**
+ * One webhook request. GET is the handshake; POST is the events: signature checked on the raw body,
+ * then each tap handled. Answers 200 only when every tap was handled (or is not ours), 500 otherwise,
+ * so Meta delivers the failed event again (handled events are not repeated: see `mids`).
+ * @param {{ method: string, query?: Record<string, string | undefined>, raw?: string | Uint8Array,
+ *   signature?: string | null, secret: string, verifyToken: string,
+ *   resolveTarget: (media: string) => Promise<Target | null>,
+ *   account: () => Promise<{ client: InstagramClient, id: string }>,
+ *   onComments?: (media: string[]) => void, C: OmnichatConfig } & Deps} p
+ *   `onComments` gets the posts with a new comment (see commentedMedia); it should not hold the answer
+ * @returns {Promise<{ status: number, body: string }>}
+ */
+export async function handleWebhook({
+  method,
+  query = {},
+  raw = "",
+  signature,
+  secret,
+  verifyToken,
+  resolveTarget,
+  account,
+  onComments,
+  C,
+  ...deps
+}) {
+  const d = withDefaults(deps);
+  if (method === "GET") {
+    const challenge = verifyChallenge(query, verifyToken);
+    return challenge === null
+      ? { status: 403, body: "token de verificação não confere" }
+      : { status: 200, body: challenge };
+  }
+  if (method !== "POST") return { status: 405, body: "método não aceito" };
+  if (!validSignature(raw, signature, secret)) return { status: 401, body: "assinatura inválida" };
+  let body;
+  try {
+    body = JSON.parse(typeof raw === "string" ? raw : new TextDecoder().decode(raw));
+  } catch {
+    return { status: 400, body: "corpo não é JSON" };
+  }
+  const commented = commentedMedia(body);
+  if (commented.length) onComments?.(commented);
+  const taps = tapsIn(body);
+  if (!taps.length) return { status: 200, body: "ok" };
+  let failed = 0;
+  let acct;
+  for (const tap of taps) {
+    try {
+      acct ??= await account();
+      if (tap.recipientId && tap.recipientId !== acct.id) continue;
+      const target = await resolveTarget(tap.media);
+      if (!target) {
+        d.log(`${new Date(d.now()).toISOString()} webhook: toque em um post sem regra (${tap.media}), ignorado`);
+        continue;
+      }
+      const { client, id } = acct;
+      await target.withRecord(async ({ rule, record }) => {
+        const r = await handleTap({ tap, rule, record, account: { client, id }, post: target.post, C, ...d });
+        d.log(
+          `${new Date(d.now()).toISOString()} ${target.name}: toque de @${r.username ?? "?"} → ${
+            {
+              unknown: "comentário desconhecido",
+              duplicate: "evento repetido",
+              delivered: "enviado",
+              not_following: "não segue, pedi para seguir",
+            }[r.status]
+          }`,
+        );
+        return r.status !== "unknown";
+      });
+    } catch (e) {
+      failed++;
+      d.warn(`${new Date(d.now()).toISOString()} webhook: ${/** @type {Error} */ (e).message}`);
+    }
+  }
+  return failed ? { status: 500, body: "falhou, tente de novo" } : { status: 200, body: "ok" };
+}

package/tools/lib/pairing.mjs

@@ -0,0 +1,99 @@
+/* Pairing this Mac with the hosted studio (cloud/studio): the device authorization flow (RFC 8628) of the
+   studio's Better Auth, then the trade of the short session for the Mac's own key at /runner/register.
+   Used by `tools/runner.mjs login` and by the runner itself when the cloud refuses its key
+   (studio/runner/runner.ts). Pure: fetch, sleep and the clock are injected, so the tests run without a
+   network. Messages in Portuguese: they reach the user as they are. */
+
+export const RUNNER_CLIENT_ID = "omnivideo-runner";
+
+/**
+ * @typedef {{ fetch?: typeof fetch, sleep?: (ms: number) => Promise<void>, now?: () => number }} Deps
+ * @typedef {{ device_code: string, user_code: string, verification_uri_complete: string,
+ *   interval?: number, expires_in: number }} DeviceCode
+ */
+
+/** @param {string} url @param {string} path @param {{ body?: unknown, token?: string, method?: string }} o @param {typeof fetch} f */
+async function call(url, path, { body, token, method = "POST" }, f) {
+  const r = await f(`${url}${path}`, {
+    method,
+    headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const j = await r.json().catch(() => ({}));
+  return { status: r.status, ok: r.ok, body: /** @type {any} */ (j) };
+}
+
+/** Asks the studio for a pairing code. @param {string} url @param {Deps} [d] @returns {Promise<DeviceCode>} */
+export async function startPairing(url, d = {}) {
+  const r = await call(url, "/auth/device/code", { body: { client_id: RUNNER_CLIENT_ID } }, d.fetch ?? fetch);
+  if (!r.ok)
+    throw new Error(
+      `o studio não abriu o pareamento (${r.status}: ${r.body?.error_description ?? r.body?.error ?? "?"})`,
+    );
+  return r.body;
+}
+
+/**
+ * Waits for the code to be approved at <studio>/runner/pair and trades it for this Mac's key.
+ * @param {string} url @param {DeviceCode} code @param {string} name the Mac's name in the list of Macs
+ * @param {Deps} [d]
+ * @returns {Promise<{ key: string, name: string }>}
+ */
+export async function finishPairing(url, code, name, d = {}) {
+  const f = d.fetch ?? fetch;
+  const sleep = d.sleep ?? (ms => new Promise(r => setTimeout(r, ms)));
+  const now = d.now ?? Date.now;
+  let wait = (code.interval || 3) * 1000;
+  const deadline = now() + code.expires_in * 1000;
+  let session = "";
+  while (now() < deadline) {
+    await sleep(wait);
+    const t = await call(
+      url,
+      "/auth/device/token",
+      {
+        body: {
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+          device_code: code.device_code,
+          client_id: RUNNER_CLIENT_ID,
+        },
+      },
+      f,
+    );
+    if (t.ok && t.body?.access_token) {
+      session = t.body.access_token;
+      break;
+    }
+    const e = t.body?.error;
+    if (e === "authorization_pending") continue;
+    if (e === "slow_down") {
+      wait += 5000;
+      continue;
+    }
+    if (e === "access_denied") throw new Error("o pareamento foi recusado na página");
+    if (e === "expired_token") throw new Error("o código do pareamento expirou");
+    throw new Error(`o studio recusou o pareamento (${t.status}: ${t.body?.error_description ?? e ?? "?"})`);
+  }
+  if (!session) throw new Error("o código do pareamento expirou");
+  const reg = await call(url, "/runner/register", { body: { name }, token: session }, f);
+  if (!reg.ok || !reg.body?.key)
+    throw new Error(`o studio não entregou a chave do Mac (${reg.status}: ${reg.body?.error ?? "?"})`);
+  return { key: reg.body.key, name: reg.body.name };
+}
+
+/**
+ * Whether the studio still takes this key: `valid` false only when it answered that the key is refused
+ * (an unreachable studio is not a verdict on the key).
+ * @param {string} url @param {string} token @param {Deps} [d]
+ * @returns {Promise<{ valid: boolean | null, name?: string, online?: boolean, error?: string }>}
+ */
+export async function checkKey(url, token, d = {}) {
+  try {
+    const r = await call(url, "/runner/whoami", { method: "GET", token }, d.fetch ?? fetch);
+    if (r.ok) return { valid: true, name: r.body.name, online: !!r.body.online };
+    if (r.status === 401) return { valid: false, error: r.body?.error ?? "chave recusada" };
+    return { valid: null, error: r.body?.error ?? `HTTP ${r.status}` };
+  } catch (e) {
+    return { valid: null, error: String(/** @type {Error} */ (e).message) };
+  }
+}

package/tools/lib/paths.mjs

@@ -0,0 +1,41 @@
+/* The two roots every tool works from (docs/specs/phase-2-plugin-cli.md, step 1).
+
+     CODE_ROOT  where tools/, templates/, studio/, docs/ and the .venv live: this repo, or the folder
+                the `omni` CLI extracts its tools into (~/.omni/bin/<version>/). OMNI_CODE_ROOT points it
+                elsewhere, for code bundled into the compiled studio, whose own path is /$bunfs/….
+     DATA_ROOT  where videos/, omnivideo.config.json, .env, channel/, kit/ and the dot folders live: the
+                workspace. OMNI_HOME points it elsewhere; without it, it is the code root, so this repo
+                works as it always has.
+
+   isMainModule(import.meta.url) replaces `process.argv[1] === fileURLToPath(import.meta.url)`: inside
+   a compiled binary every bundled module's path equals argv[1], so that check fires on import. */
+
+import { realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const OWN_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+export const CODE_ROOT = resolve(process.env.OMNI_CODE_ROOT || OWN_ROOT);
+export const DATA_ROOT = resolve(process.env.OMNI_HOME || CODE_ROOT);
+
+/* a path inside a Bun compiled binary (/$bunfs/… on macOS and Linux, B:/~BUN/… on Windows) */
+const bundled = (/** @type {string} */ p) => p.startsWith("/$bunfs/") || /^[A-Za-z]:[\\/]~BUN[\\/]/.test(p);
+
+/** true when the module at `url` is the script node was started with, false when it was imported
+ *  @param {string} url */
+export function isMainModule(url) {
+  const self = fileURLToPath(url);
+  const arg = process.argv[1];
+  if (!arg || bundled(self)) return false;
+  try {
+    return realpathSync(arg) === realpathSync(self);
+  } catch {
+    return false;
+  }
+}
+
+/** the launchd plist fragment that carries OMNI_HOME to an agent, or nothing when the data root is
+ *  the code root  @param {(s: string) => string} esc */
+export const homeEnvPlist = esc =>
+  DATA_ROOT === CODE_ROOT ? "" : `<key>OMNI_HOME</key><string>${esc(DATA_ROOT)}</string>`;