@crievo/omni 0.0.0-stage → 0.1.1

package/tools/lib/publish/publish.mjs

@@ -0,0 +1,244 @@
+/* ============================================================================
+   Publishing decisions shared by the CLI and a future cloud runner: the
+   publish config with its defaults, the post texts (footer, hashtags, the
+   platforms' limits), the per-platform gate before uploading and the record
+   written back to publication.json. Pure.
+   ============================================================================ */
+
+export const PLATFORMS = ["youtube", "instagram", "tiktok"];
+export const PRIVACIES = ["private", "unlisted", "public"];
+export const TIKTOK_PRIVACIES = ["SELF_ONLY", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "PUBLIC_TO_EVERYONE"];
+export const TEXT_FIELDS = ["title", "description", "caption", "tags"];
+
+/**
+ * publish.* in the config with the defaults filled in.
+ * @param {Record<string, any>} [cfg] the config's `publish`
+ */
+export function publishConfig(cfg = {}) {
+  const P = {
+    auto: { approved: false, platforms: [], requires_approved_preview: true, ...(cfg.auto ?? {}) },
+    text: { footer_youtube: "", footer_instagram: "", footer_tiktok: "", hashtags: [], ...(cfg.text ?? {}) },
+    youtube: {
+      privacy: "public",
+      audited: false,
+      category: "22",
+      language: "pt-BR",
+      made_for_kids: false,
+      synthetic_content: false,
+      ...(cfg.youtube ?? {}),
+    },
+    instagram: { api_version: "v23.0", share_to_feed: true, cover_at_s: null, ...(cfg.instagram ?? {}) },
+    tiktok: {
+      mode: "direct",
+      privacy: "PUBLIC_TO_EVERYONE",
+      audited: false,
+      comments: true,
+      duet: false,
+      stitch: false,
+      ai_content: true,
+      cover_at_s: null,
+      ...(cfg.tiktok ?? {}),
+    },
+    schedule: { max_delay_h: 12, attempts: 3, interval_min: 10, ...(cfg.schedule ?? {}) },
+  };
+  /* a config not yet migrated may still say "rascunho"/"direto": never publish directly by mistake */
+  P.tiktok.mode = { rascunho: "draft", direto: "direct" }[/** @type {string} */ (P.tiktok.mode)] ?? P.tiktok.mode;
+  return P;
+}
+
+/** @typedef {ReturnType<typeof publishConfig>} PublishConfig */
+
+const HASHTAG = /#[\p{L}\p{N}_]+/gu;
+
+/**
+ * The footer and the fixed hashtags go at the end, without repeating what the text has.
+ * @param {string} text @param {string | null | undefined} footer @param {string[]} hashtags
+ */
+export function withFixed(text, footer, hashtags) {
+  const present = new Set((text.match(HASHTAG) ?? []).map(h => h.toLowerCase()));
+  const tags = hashtags
+    .map(h => `#${String(h).trim().replace(/^#/, "")}`)
+    .filter(h => h.length > 1 && !present.has(h.toLowerCase()));
+  const f = String(footer ?? "").trim();
+  return [text, f && !text.includes(f) ? f : "", tags.join(" ")].filter(Boolean).join("\n\n");
+}
+
+/**
+ * The Instagram caption's own limits (2200 characters, 30 hashtags).
+ * @param {string} caption
+ * @returns {string | null} the problem, or null
+ */
+export function instagramCaptionProblem(caption) {
+  if (caption.length > 2200) return `legenda do Instagram com ${caption.length} caracteres (até 2200)`;
+  if ((caption.match(HASHTAG) ?? []).length > 30) return "legenda do Instagram com mais de 30 hashtags";
+  return null;
+}
+
+/**
+ * Each platform's texts and their limits, checked before uploading anything.
+ * @param {{ pub: Record<string, any>, defaultTitle: () => string, text: PublishConfig["text"] }} p
+ */
+export function metadata({ pub, defaultTitle, text }) {
+  const title = String(pub.title ?? defaultTitle()).trim();
+  const base = String(pub.description ?? "").trim();
+  const tags = (pub.tags ?? []).map((/** @type {unknown} */ t) => String(t).trim()).filter(Boolean);
+  const description = withFixed(base, text.footer_youtube, text.hashtags);
+  const social =
+    String(pub.caption ?? pub.caption_instagram ?? "").trim() || [title, base].filter(Boolean).join("\n\n");
+  const caption = withFixed(social, text.footer_instagram, text.hashtags);
+  const tiktokCaption = withFixed(social, text.footer_tiktok, text.hashtags);
+  const problems = [];
+  if (!title) problems.push("título vazio");
+  if (title.length > 100) problems.push(`título com ${title.length} caracteres (YouTube: até 100)`);
+  if (/[<>]/.test(title + description)) problems.push("o YouTube não aceita < nem > no título ou na descrição");
+  if (new TextEncoder().encode(description).byteLength > 5000) problems.push("descrição passa de 5000 bytes (YouTube)");
+  if (tags.join(",").length > 500) problems.push("tags passam de 500 caracteres (YouTube)");
+  if (caption.length > 2200) problems.push(`legenda do Instagram com ${caption.length} caracteres (até 2200)`);
+  if ((caption.match(HASHTAG) ?? []).length > 30) problems.push("legenda do Instagram com mais de 30 hashtags");
+  /* TikTok counts UTF-16 units, which is JS .length */
+  if (tiktokCaption.length > 2200) problems.push(`legenda do TikTok com ${tiktokCaption.length} caracteres (até 2200)`);
+  return { title, description, tags, caption, tiktokCaption, problems };
+}
+
+/**
+ * The title when publication.json has none: scenes.json's, the script's heading, or the folder name.
+ * @param {{ scenesTitle?: string | null, script: string, dirName: string }} p
+ */
+export function defaultTitle({ scenesTitle, script, dirName }) {
+  if (scenesTitle) return scenesTitle;
+  /* the `# Roteiro · ` heading is PT content parsed as is */
+  return script.match(/^#\s+(?:Roteiro\s*·\s*)?(.+)$/m)?.[1]?.trim() ?? dirName.replace(/^\d{4}-\d{2}-\d{2}-/, "");
+}
+
+/**
+ * Without a model: the script's title, the thesis as description and the hook (first quote) as caption.
+ * @param {string} script @param {string} title
+ */
+export function textFromScript(script, title) {
+  /** @param {string} s */
+  const clean = s => s.replace(/\*\*|`/g, "").trim();
+  const thesis = script.match(/^\*\*Tese:\*\*\s*(.+)$/m)?.[1];
+  const hook = script.match(/^>\s*(.+)$/m)?.[1];
+  return { title, description: thesis ? clean(thesis) : "", caption: hook ? clean(hook) : "", tags: [] };
+}
+
+/** The prompt that turns the script (on stdin) into the post texts. */
+export const TEXT_PROMPT = `Você escreve o texto de publicação de um vídeo curto a partir do roteiro dele, que vem na entrada.
+Responda só com um objeto JSON, sem markdown nem comentário:
+{"title": "...", "description": "...", "caption": "...", "tags": ["..."]}
+
+- title (YouTube): até 90 caracteres, a promessa do vídeo, em português do Brasil. Sem < nem >, sem hashtag, sem aspas em volta. Não é o nome do arquivo nem começa com "Roteiro".
+- description (YouTube): 2 a 4 linhas curtas com o que a pessoa leva do vídeo. Não repete o título palavra por palavra. Sem < nem >.
+- caption (Instagram e TikTok): 1 a 3 linhas no tom de quem fala, abrindo pelo gancho do vídeo, e até 3 hashtags do assunto no fim.
+- tags: até 8 palavras-chave do assunto, sem #.
+
+Use só o que o roteiro diz: não invente número, nome, dado nem promessa. Ignore as notas de produção (ajustes para a voz, fontes, tabela de duração). Não acrescente rodapé, link nem chamada para seguir: isso entra depois, sozinho.`;
+
+/**
+ * The model's answer to TEXT_PROMPT, cleaned. Throws when it is not usable.
+ * @param {string} out
+ */
+export function parseModelText(out) {
+  const raw = /\{[\s\S]*\}/.exec(out)?.[0];
+  let j;
+  try {
+    j = JSON.parse(/** @type {string} */ (raw));
+  } catch {
+    throw new Error(`claude não devolveu JSON: ${out.trim().slice(0, 200)}`);
+  }
+  const title = String(j.title ?? "")
+    .replace(/[<>]/g, "")
+    .trim()
+    .slice(0, 100);
+  if (!title) throw new Error("claude devolveu título vazio");
+  return {
+    title,
+    description: String(j.description ?? "")
+      .replace(/[<>]/g, "")
+      .trim(),
+    caption: String(j.caption ?? "").trim(),
+    tags: (Array.isArray(j.tags) ? j.tags : [])
+      .map((/** @type {unknown} */ t) => String(t).replace(/^#/, "").trim())
+      .filter(Boolean)
+      .slice(0, 8),
+  };
+}
+
+/**
+ * Which text fields are to be (re)written. The old Instagram caption is moved to `caption` (mutates `pub`).
+ * @param {Record<string, any>} pub @param {boolean} redo
+ */
+export function missingText(pub, redo) {
+  if (pub.caption == null && pub.caption_instagram) {
+    pub.caption = pub.caption_instagram;
+    delete pub.caption_instagram;
+  }
+  /** @param {string} k */
+  const empty = k => (k === "tags" ? !pub.tags?.length : !String(pub[k] ?? "").trim());
+  return TEXT_FIELDS.filter(k => redo || empty(k));
+}
+
+/**
+ * Before uploading to one platform: skip (already up), refuse (limits) or go, with warnings.
+ * @param {{ platform: string, before: Record<string, any> | undefined, video: { w: number, h: number, duration: number }, again: boolean,
+ *   format: (iso: string) => string }} p
+ * @returns {{ action: "skip", message: string } | { action: "refuse", message: string, warnings: string[] } | { action: "go", warnings: string[] }}
+ */
+export function platformGate({ platform, before, video, again, format }) {
+  if (before?.id && !again)
+    return {
+      action: "skip",
+      message: `${platform}: já publicado em ${format(before.published_at)}: ${before.url ?? before.id} (--again sobe outra vez)`,
+    };
+  const warnings = [];
+  if (platform !== "youtube" && video.h <= video.w)
+    warnings.push(`aviso: o vídeo não é vertical; o ${platform === "tiktok" ? "TikTok" : "Reels"} mostra com faixas`);
+  if (platform === "instagram" && (video.duration < 3 || video.duration > 900))
+    return {
+      action: "refuse",
+      message: `instagram: Reels pela API vai de 3 s a 15 min; este tem ${video.duration.toFixed(1)} s`,
+      warnings,
+    };
+  if (platform === "tiktok" && video.duration < 3)
+    return {
+      action: "refuse",
+      message: `tiktok: o vídeo precisa de pelo menos 3 s; este tem ${video.duration.toFixed(1)} s`,
+      warnings,
+    };
+  return { action: "go", warnings };
+}
+
+/**
+ * The previous ids when a platform goes up again.
+ * @param {Record<string, any> | undefined} before
+ */
+export const previousOf = before =>
+  before?.id
+    ? [...(before.previous ?? []), { id: before.id, url: before.url, published_at: before.published_at }]
+    : before?.previous;
+
+/**
+ * The platform's entry in publication.json after an upload.
+ * @param {{ result: Record<string, any>, before: Record<string, any> | undefined, mp4: string, mp4Mtime: number,
+ *   scheduledFor?: string | null, now: number }} p
+ */
+export function publishedEntry({ result, before, mp4, mp4Mtime, scheduledFor, now }) {
+  const previous = previousOf(before);
+  return {
+    ...result,
+    published_at: new Date(now).toISOString(),
+    mp4,
+    mp4_mtime: mp4Mtime,
+    ...(scheduledFor ? { scheduled_for: scheduledFor } : {}),
+    ...(previous?.length ? { previous } : {}),
+  };
+}
+
+/**
+ * The platform's entry after a failed attempt: what was there, plus the error.
+ * @param {Record<string, any> | undefined} before @param {string} message @param {number} now
+ */
+export const failedEntry = (before, message, now) => ({
+  ...(before ?? {}),
+  last_error: { at: new Date(now).toISOString(), message },
+});

package/tools/lib/schedule/schedule.mjs

@@ -0,0 +1,191 @@
+/* ============================================================================
+   Scheduled publishing: the decisions, without the runner. A schedule lives in
+   publication.json (`schedule`); these functions say when it is due, when it
+   is missed, how an attempt starts and what its outcome becomes (done, retry
+   later, or failed). The caller runs the upload (a child publish.mjs on the
+   CLI, the core upload in a cloud function) and persists the result.
+   ============================================================================ */
+
+import { HOUR } from "../http.mjs";
+
+/**
+ * @typedef {object} Schedule
+ * @property {string} when ISO
+ * @property {string[]} platforms
+ * @property {string} privacy
+ * @property {string} tiktok_privacy
+ * @property {boolean} republish
+ * @property {"scheduled" | "publishing" | "failed" | "missed"} state
+ * @property {number} attempts
+ * @property {string} [created_at]
+ * @property {string} [origin]
+ * @property {number} [pid]
+ * @property {string} [started_at]
+ * @property {string} [next_attempt]
+ * @property {string} [rescheduled_at]
+ * @property {{ at: string, message: string }} [last_error]
+ */
+
+/**
+ * @typedef {object} ScheduleSettings publish.schedule in the config
+ * @property {number} max_delay_h past this delay a never-tried schedule is missed
+ * @property {number} attempts
+ * @property {number} interval_min between attempts
+ */
+
+/** The defaults of publish.schedule. */
+export const SCHEDULE_DEFAULTS = { max_delay_h: 12, attempts: 3, interval_min: 10 };
+
+/**
+ * "2026-10-14 18:00" or "2026-10-14T18:00" is the local time of the runtime;
+ * with Z or an offset, the text's. Throws with the CLI's message when invalid
+ * or less than 1 min ahead.
+ * @param {string | undefined} s
+ * @param {{ now: number, format: (d: Date) => string }} p
+ * @returns {Date}
+ */
+export function parseWhen(s, { now, format }) {
+  if (!s) throw new Error('diga quando: --when "2026-10-14 18:00" (hora desta máquina)');
+  const t = String(s)
+    .trim()
+    .replace(/^(\d{4}-\d{2}-\d{2})\s+/, "$1T");
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(t)) throw new Error(`quando: use AAAA-MM-DD HH:MM (veio "${s}")`);
+  const d = new Date(t);
+  if (Number.isNaN(d.getTime())) throw new Error(`quando: data inválida "${s}"`);
+  if (d.getTime() < now + 60_000)
+    throw new Error(`${format(d)} já passou (ou é daqui a menos de 1 min): para agora, publique sem agendar`);
+  return d;
+}
+
+/**
+ * A new schedule for a confirmed request.
+ * @param {{ when: Date, platforms: string[], privacy: string, tiktokPrivacy: string, republish: boolean, now: number, origin: string }} p
+ * @returns {Schedule}
+ */
+export const newSchedule = ({ when, platforms, privacy, tiktokPrivacy, republish, now, origin }) => ({
+  when: when.toISOString(),
+  platforms,
+  privacy,
+  tiktok_privacy: tiktokPrivacy,
+  republish,
+  state: "scheduled",
+  attempts: 0,
+  created_at: new Date(now).toISOString(),
+  origin,
+});
+
+/**
+ * Another time for the same request: platforms, privacy and text stay; the attempt count restarts.
+ * @param {Schedule} sch @param {Date} when @param {number} now
+ * @returns {Schedule}
+ */
+export function reschedule(sch, when, now) {
+  const { pid, last_error, next_attempt, started_at, ...rest } = sch;
+  return {
+    ...rest,
+    when: when.toISOString(),
+    state: "scheduled",
+    attempts: 0,
+    rescheduled_at: new Date(now).toISOString(),
+  };
+}
+
+/**
+ * Published by hand where it was scheduled: the platform leaves the schedule
+ * (the whole schedule goes when none is left). Mutates `pub`.
+ * @param {{ schedule?: Schedule }} pub @param {string} platform
+ * @returns {boolean} whether the platform was in the schedule
+ */
+export function dropPlatform(pub, platform) {
+  if (!pub.schedule?.platforms?.includes(platform)) return false;
+  pub.schedule.platforms = pub.schedule.platforms.filter(p => p !== platform);
+  if (!pub.schedule.platforms.length) delete pub.schedule;
+  return true;
+}
+
+/**
+ * Is it time? "publishing" without a live process is a run that died midway:
+ * it counts as a new attempt.
+ * @param {Schedule | undefined} sch
+ * @param {{ now: number, alive: (pid: number | undefined) => boolean, settings: ScheduleSettings }} p
+ * @returns {{ action: "skip" } | { action: "run" } | { action: "missed", message: string }}
+ */
+export function dueAction(sch, { now, alive, settings }) {
+  if (!sch) return { action: "skip" };
+  if (sch.state === "publishing" && alive(sch.pid)) return { action: "skip" };
+  if (!["scheduled", "publishing"].includes(sch.state)) return { action: "skip" };
+  const at = Date.parse(sch.when);
+  if (!(at <= now)) return { action: "skip" };
+  if (sch.next_attempt && Date.parse(sch.next_attempt) > now) return { action: "skip" };
+  const delay = (now - at) / HOUR;
+  if (!sch.attempts && delay > settings.max_delay_h)
+    return {
+      action: "missed",
+      message: `o Mac estava dormindo ou desligado na hora: ${delay.toFixed(1)} h de atraso passa do limite de ${settings.max_delay_h} h (publish.schedule.max_delay_h)`,
+    };
+  return { action: "run" };
+}
+
+/**
+ * Marks a schedule missed. Mutates and returns it.
+ * @param {Schedule} sch @param {string} message @param {number} now
+ */
+export function markMissed(sch, message, now) {
+  sch.state = "missed";
+  sch.last_error = { at: new Date(now).toISOString(), message };
+  return sch;
+}
+
+/**
+ * Marks the start of an attempt. Mutates and returns it.
+ * @param {Schedule} sch @param {{ pid: number, startedAt: string }} p
+ */
+export function startAttempt(sch, { pid, startedAt }) {
+  Object.assign(sch, { state: "publishing", pid, started_at: startedAt, attempts: (sch.attempts ?? 0) + 1 });
+  delete sch.next_attempt;
+  return sch;
+}
+
+/**
+ * The reason of a failed attempt, from the child's stderr (warnings and the
+ * "erro: " prefix dropped; the last three lines).
+ * @param {{ stderr?: string | null, error?: Error | null, status?: number | null }} p
+ */
+export function failureReason({ stderr, error, status }) {
+  const lines = (stderr ?? "")
+    .split("\n")
+    .map(l => l.trim().replace(/^erro: /, ""))
+    .filter(l => l && !l.startsWith("aviso:"));
+  return error?.message ?? (lines.slice(-3).join(" · ") || `publish.mjs saiu com ${status}`);
+}
+
+/**
+ * What an attempt became. `after` is publication.json read after the upload.
+ * A platform is done if it went up in this run, or was already up and was not
+ * meant to go up again; the rest retries every interval_min until attempts runs out.
+ * @param {{ sch: Schedule, after: Record<string, any>, startedAt: string, reason: () => string, now: number, settings: ScheduleSettings }} p
+ * @returns {{ done: true } | { done: false, schedule: Schedule, missing: string[], giveUp: boolean, reason: string }}
+ */
+export function attemptOutcome({ sch, after, startedAt, reason, now, settings }) {
+  const base = { ...sch, ...(after.schedule ?? {}) };
+  /** @param {string} p */
+  const done = p => (after[p]?.published_at ?? "") >= startedAt || (!sch.republish && after[p]?.id);
+  const missing = sch.platforms.filter(p => !done(p));
+  if (!missing.length) return { done: true };
+  const why = reason();
+  const giveUp = base.attempts >= settings.attempts;
+  delete base.pid;
+  return {
+    done: false,
+    missing,
+    giveUp,
+    reason: why,
+    schedule: {
+      ...base,
+      platforms: missing,
+      state: giveUp ? "failed" : "scheduled",
+      last_error: { at: new Date(now).toISOString(), message: why },
+      ...(giveUp ? {} : { next_attempt: new Date(now + settings.interval_min * 60_000).toISOString() }),
+    },
+  };
+}

package/tools/lib/service.mjs

@@ -0,0 +1,134 @@
+/* The studio kept on by launchd (macOS): `bun studio.ts` in <code root>/studio, started at login and again
+   whenever it stops (30 s apart, so a studio already open in a terminal holding the port just waits its
+   turn). PATH goes along because launchd starts with a minimal one, without claude, ffmpeg or the venv's
+   python; OMNI_HOME goes along when the workspace is not the code root (tools/lib/paths.mjs).
+
+   Used by `tools/runner.mjs service` (this repo) and `omni up` (the installed CLI). Throws Errors in
+   Portuguese; the callers print them. */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { CODE_ROOT, DATA_ROOT, homeEnvPlist } from "./paths.mjs";
+
+export const AGENT = "com.omnivideo.studio";
+export const PLIST = join(homedir(), "Library", "LaunchAgents", `${AGENT}.plist`);
+export const LOG_FILE = join(DATA_ROOT, ".runner", "studio.log");
+const domain = () => `gui/${process.getuid?.()}`;
+const launchctl = (/** @type {string[]} */ ...a) => spawnSync("launchctl", a, { encoding: "utf8" });
+
+/** the bun to run the studio with: the CLI package's own (the `bun` dependency), else the one installed */
+export function bunPath(codeRoot = CODE_ROOT) {
+  const found = spawnSync("/bin/sh", ["-lc", "command -v bun"], { encoding: "utf8" }).stdout.trim();
+  return [
+    join(codeRoot, "node_modules", ".bin", "bun"),
+    join(codeRoot, "..", "..", ".bin", "bun"),
+    found,
+    join(homedir(), ".bun", "bin", "bun"),
+    "/opt/homebrew/bin/bun",
+    "/usr/local/bin/bun",
+  ].find(p => p && existsSync(p));
+}
+
+/** what launchd says about the studio's agent */
+export function service() {
+  const installed = existsSync(PLIST);
+  const printed = installed ? launchctl("print", `${domain()}/${AGENT}`) : null;
+  const pid = printed?.status === 0 ? Number(/\bpid = (\d+)/.exec(printed.stdout)?.[1] ?? 0) : 0;
+  return { installed, loaded: printed?.status === 0, pid: pid || null, log: LOG_FILE };
+}
+
+/** the plist the agent would have now: reinstalling only when it changed keeps a running studio running */
+function plist(/** @type {string} */ bun, /** @type {string} */ codeRoot) {
+  const x = (/** @type {string} */ v) => v.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  const path = [
+    ...new Set([
+      dirname(bun),
+      dirname(process.execPath),
+      "/opt/homebrew/bin",
+      "/usr/local/bin",
+      ...(process.env.PATH ?? "").split(":"),
+      "/usr/bin",
+      "/bin",
+      "/usr/sbin",
+      "/sbin",
+    ]),
+  ]
+    .filter(Boolean)
+    .join(":");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${AGENT}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${x(bun)}</string>
+    <string>studio.ts</string>
+  </array>
+  <key>WorkingDirectory</key><string>${x(join(codeRoot, "studio"))}</string>
+  <key>EnvironmentVariables</key>
+  <dict><key>PATH</key><string>${x(path)}</string>${homeEnvPlist(x)}</dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>30</integer>
+  <key>StandardOutPath</key><string>${x(LOG_FILE)}</string>
+  <key>StandardErrorPath</key><string>${x(LOG_FILE)}</string>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * Installs (or replaces) the agent. With `onlyIfChanged`, an agent already loaded with the same plist is
+ * left alone, so `omni up` on every session start never restarts a studio that is working.
+ * @param {{ codeRoot?: string, onlyIfChanged?: boolean, log?: (line: string) => void }} [o]
+ * @returns {{ changed: boolean }}
+ */
+export function serviceInstall({ codeRoot = CODE_ROOT, onlyIfChanged = false, log = () => {} } = {}) {
+  if (process.platform !== "darwin") throw new Error("o serviço é do macOS (launchd)");
+  const bun = bunPath(codeRoot);
+  if (!bun) throw new Error("não achei o bun: instale com curl -fsSL https://bun.sh/install | bash");
+  const text = plist(bun, codeRoot);
+  let current = "";
+  try {
+    current = existsSync(PLIST) ? String(spawnSync("cat", [PLIST], { encoding: "utf8" }).stdout) : "";
+  } catch {
+    current = "";
+  }
+  if (onlyIfChanged && current === text && service().loaded) return { changed: false };
+  /* this repo pins the studio's dependencies with its lockfile; the CLI package has them installed by npm */
+  if (existsSync(join(codeRoot, "studio", "bun.lock"))) {
+    const deps = spawnSync(bun, ["install", "--frozen-lockfile", "--silent"], {
+      cwd: join(codeRoot, "studio"),
+      stdio: "inherit",
+    });
+    if (deps.status !== 0) throw new Error("bun install falhou em studio/");
+  }
+  mkdirSync(dirname(LOG_FILE), { recursive: true });
+  mkdirSync(dirname(PLIST), { recursive: true });
+  writeFileSync(PLIST, text);
+  /* reinstalling replaces what was loaded; launchd sometimes takes a moment to release the old one */
+  launchctl("bootout", `${domain()}/${AGENT}`);
+  let r = launchctl("bootstrap", domain(), PLIST);
+  for (let i = 0; i < 6 && r.status !== 0; i++) {
+    spawnSync("sleep", ["0.5"]);
+    r = launchctl("bootstrap", domain(), PLIST);
+  }
+  if (r.status !== 0) throw new Error(`launchctl bootstrap: ${(r.stderr || r.stdout).trim()}`);
+  if (spawnSync("lsof", ["-nP", "-iTCP:5432", "-sTCP:LISTEN"], { encoding: "utf8" }).stdout.includes("LISTEN"))
+    log("aviso: já há um studio aberto na porta 5432 (num terminal?): feche-o e o serviço assume em até 30 s");
+  return { changed: true };
+}
+
+export function serviceUninstall() {
+  launchctl("bootout", `${domain()}/${AGENT}`);
+  if (existsSync(PLIST)) unlinkSync(PLIST);
+}
+
+export function serviceRestart() {
+  if (!service().loaded) throw new Error("o serviço não está ligado");
+  const r = launchctl("kickstart", "-k", `${domain()}/${AGENT}`);
+  if (r.status !== 0) throw new Error(`launchctl kickstart: ${(r.stderr || r.stdout).trim()}`);
+}