@crievo/omni 0.1.4 → 0.1.6

package/tools/lib/oauth-client.mjs

@@ -1,6 +1,6 @@
 /* The CLI side of the studio's OAuth login (cloud/studio/src/oauth.mjs; docs/specs/phase-2-plugin-cli.md,
-   step 2): PKCE, the loopback callback, the token exchange, and the tokens in the macOS Keychain, refreshed
-   under a lock.
+   step 2): PKCE, the loopback callback, the token exchange, and the tokens in the system's credential vault
+   (tools/lib/vault.mjs: the macOS Keychain, Windows Credential Manager), refreshed under a lock.
 
      login(studioUrl, …)   opens the approval page in the browser, waits on http://127.0.0.1:<port>/callback,
                            trades the code and stores the tokens
@@ -9,18 +9,19 @@
 
    Two processes (the studio's runner and a CLI command) may refresh at once. The server treats a rotated
    refresh token used twice as a leak and signs the machine out, so a refresh holds a lock and rereads the
-   Keychain inside it: the second process finds the tokens the first one just stored.
+   vault inside it: the second process finds the tokens the first one just stored.
 
-   The Keychain item: service "omni", account = the studio's host, the password a JSON with the tokens.
-   `security` (and the lock dir, the clock, fetch, the browser) are injected for the tests. Messages in
-   Portuguese: they reach the user as they are. */
+   The vault item: service "omni", account = the studio's host, the secret a JSON with the tokens. The vault
+   (and the lock dir, the clock, fetch, the browser) are injected for the tests. Messages in Portuguese: they
+   reach the user as they are. */
 
-import { spawnSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { mkdirSync, rmSync, statSync } from "node:fs";
 import { createServer } from "node:http";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { openUrl } from "./platform.mjs";
+import { defaultVault } from "./vault.mjs";
 
 export const CLI_CLIENT = "omnivideo-cli";
 /* an access token's prefix (cloud/studio/src/oauth.mjs): tells it from a Phase 1 key (`ovr_`) */
@@ -43,7 +44,7 @@ export function pkce() {
  * @typedef {{
  *   fetch?: typeof fetch,
  *   now?: () => number,
- *   security?: string,
+ *   vault?: import("./vault.mjs").Vault,
  *   lockDir?: string,
  *   open?: (url: string) => void,
  *   log?: (line: string) => void,
@@ -52,18 +53,16 @@ export function pkce() {
 
 const hostOf = (/** @type {string} */ studioUrl) => new URL(studioUrl).host;
 
-/* --- the Keychain ------------------------------------------------------------------------ */
+/* --- the vault --------------------------------------------------------------------------- */
+
+const vaultOf = (/** @type {Deps} */ d) => d.vault ?? defaultVault();
 
 /** @param {string} studioUrl @param {Deps} [d] @returns {Tokens | null} */
 export function readTokens(studioUrl, d = {}) {
-  const r = spawnSync(
-    d.security ?? "security",
-    ["find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", hostOf(studioUrl), "-w"],
-    { encoding: "utf8" },
-  );
-  if (r.status !== 0) return null;
+  const secret = vaultOf(d).get(KEYCHAIN_SERVICE, hostOf(studioUrl));
+  if (!secret) return null;
   try {
-    const t = JSON.parse(r.stdout.trim());
+    const t = JSON.parse(secret);
     return t?.access_token && t?.refresh_token ? t : null;
   } catch {
     return null;
@@ -72,32 +71,12 @@ export function readTokens(studioUrl, d = {}) {
 
 /** @param {string} studioUrl @param {Tokens} tokens @param {Deps} [d] */
 export function writeTokens(studioUrl, tokens, d = {}) {
-  /* -U updates the item in place; the secret goes as an argument, which `security` has no other way to take */
-  const r = spawnSync(
-    d.security ?? "security",
-    [
-      "add-generic-password",
-      "-U",
-      "-s",
-      KEYCHAIN_SERVICE,
-      "-a",
-      hostOf(studioUrl),
-      "-l",
-      "OmniVideo",
-      "-w",
-      JSON.stringify(tokens),
-    ],
-    { encoding: "utf8" },
-  );
-  if (r.status !== 0)
-    throw new Error(`não consegui gravar o login no Keychain: ${r.stderr.trim() || `código ${r.status}`}`);
+  vaultOf(d).set(KEYCHAIN_SERVICE, hostOf(studioUrl), JSON.stringify(tokens));
 }
 
 /** @param {string} studioUrl @param {Deps} [d] */
 export function forgetTokens(studioUrl, d = {}) {
-  spawnSync(d.security ?? "security", ["delete-generic-password", "-s", KEYCHAIN_SERVICE, "-a", hostOf(studioUrl)], {
-    encoding: "utf8",
-  });
+  vaultOf(d).delete(KEYCHAIN_SERVICE, hostOf(studioUrl));
 }
 
 /* --- the token endpoint ------------------------------------------------------------------ */
@@ -216,7 +195,7 @@ export async function login(studioUrl, o) {
     }))
       url.searchParams.set(k, v);
     log(`Abrindo o navegador para entrar. Se ele não abrir, use este link:\n  ${url}`);
-    (o.open ?? openBrowser)(url.toString());
+    (o.open ?? openUrl)(url.toString());
 
     const timeout = new Promise(r =>
       setTimeout(() => r({ error: "o login não voltou em 10 minutos" }), LOGIN_TIMEOUT_MS).unref(),
@@ -287,9 +266,3 @@ export async function logout(studioUrl, d = {}) {
   forgetTokens(studioUrl, d);
   return confirmed;
 }
-
-/** @param {string} url */
-function openBrowser(url) {
-  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
-  spawnSync(cmd, [url], { stdio: "ignore" });
-}

package/tools/lib/platform.mjs

@@ -0,0 +1,102 @@
+/* What differs between macOS, Windows and Linux for the tools, in one place (docs/specs/phase-2-plugin-cli.md,
+   "Windows"). macOS stays what it always was; each helper has the Mac behavior first and the Windows one beside it.
+
+     openUrl(url)         the browser (or an app) on a URL: open · rundll32 url.dll · xdg-open
+     listeningOn(port)    whether something listens on a local TCP port: lsof · netstat
+     venvPython(root)     the app's venv Python, as each OS lays a venv out
+     SYSTEM_PYTHON        the Python on PATH when there is no venv: python3 · python
+     npmCommand()         how to run npm without a shell (npm is a .cmd on Windows)
+     sleepSync(ms)        a blocking pause, without a `sleep` binary
+     localAgents          whether the launchd agents (agenda, métricas, omnichat) exist here
+     noLocalAgent(what)   the Portuguese notice that says the cloud does that work where there is no launchd
+
+   Everything takes `platform` as an argument (default: this machine's) so the tests can ask for the other OS. */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export const IS_WINDOWS = process.platform === "win32";
+
+/** the OS by the name the user knows  @param {string} [platform] */
+export const osName = (platform = process.platform) =>
+  ({ darwin: "macOS", win32: "Windows", linux: "Linux" })[/** @type {"darwin"} */ (platform)] ?? platform;
+
+/** the app's venv Python, as each OS lays a venv out  @param {string} codeRoot @param {string} [platform] */
+export const venvPython = (codeRoot, platform = process.platform) =>
+  platform === "win32" ? join(codeRoot, ".venv", "Scripts", "python.exe") : join(codeRoot, ".venv", "bin", "python");
+
+/** the Python to fall back on when the project has no venv: Windows has no `python3` */
+export const SYSTEM_PYTHON = IS_WINDOWS ? "python" : "python3";
+
+/** the first Python that exists: the project's venv, then `others` (the config's), else the system one
+ *  @param {string} codeRoot @param {string[]} [others] */
+export const pickPython = (codeRoot, others = []) =>
+  [venvPython(codeRoot), ...others].find(p => p && existsSync(p)) ?? SYSTEM_PYTHON;
+
+/** the program and arguments that open `url`, or `url` in `app` (macOS only: `open -a`)
+ *  @param {string} url @param {{ app?: string, platform?: string }} [o] @returns {[string, string[]]} */
+export function openCommand(url, { app, platform = process.platform } = {}) {
+  if (platform === "darwin") return ["open", [...(app ? ["-a", app] : []), url]];
+  /* no shell: a URL with & stays one argument, which `cmd /c start` would split */
+  if (platform === "win32") return ["rundll32", ["url.dll,FileProtocolHandler", url]];
+  return ["xdg-open", [url]];
+}
+
+/**
+ * Opens a URL in the user's browser, or in `app` (macOS only).
+ * @param {string} url @param {{ app?: string, platform?: string }} [o]
+ * @returns {{ status: number | null, stderr: string }}
+ */
+export function openUrl(url, o = {}) {
+  const [cmd, args] = openCommand(url, o);
+  const r = spawnSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "ignore", "pipe"] });
+  return { status: r.status, stderr: String(r.stderr ?? "") };
+}
+
+/** whether `netstat -ano -p TCP` shows a listener on `port`. The state column is translated ("LISTENING",
+ *  "OUVINDO"…); a listener is the row whose foreign address is 0.0.0.0:0 or [::]:0  @param {string} out @param {number} port */
+export const netstatListening = (out, port) =>
+  out.split(/\r?\n/).some(l => new RegExp(`^\\s*TCP\\s+\\S+:${port}\\s+(?:0\\.0\\.0\\.0|\\[::\\]):0\\s`).test(l));
+
+/**
+ * Whether some process listens on a local TCP port.
+ * @param {number} port @param {string} [platform]
+ */
+export function listeningOn(port, platform = process.platform) {
+  if (platform === "win32")
+    return netstatListening(spawnSync("netstat", ["-ano", "-p", "TCP"], { encoding: "utf8" }).stdout ?? "", port);
+  return !!spawnSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN"], { encoding: "utf8" }).stdout?.includes("LISTEN");
+}
+
+/** the command that runs npm without a shell: npm is `npm.cmd` on Windows, which Node won't spawn on its own.
+ *  It runs npm's own script with the same node.  @returns {{ cmd: string, prefix: string[] }} */
+export function npmCommand(platform = process.platform, env = process.env, execPath = process.execPath) {
+  if (platform !== "win32") return { cmd: "npm", prefix: [] };
+  const found = [
+    join(dirname(execPath), "node_modules", "npm", "bin", "npm-cli.js"),
+    /* under npx, npm_execpath is npx-cli.js, next to npm-cli.js */
+    env.npm_execpath ? join(dirname(env.npm_execpath), "npm-cli.js") : "",
+    env.npm_execpath ?? "",
+  ].find(p => p && /npm-cli\.js$/.test(p) && existsSync(p));
+  return found ? { cmd: execPath, prefix: [found] } : { cmd: "npm.cmd", prefix: [] };
+}
+
+/** a blocking pause  @param {number} ms */
+export function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/* --- the local agents (launchd) ---------------------------------------------------------- */
+
+/** whether the launchd agents (agenda, métricas, omnichat) exist on this machine  @param {string} [platform] */
+export const localAgents = (platform = process.platform) => platform === "darwin";
+
+/**
+ * The notice for a machine without launchd: the work those agents do is the cloud's here.
+ * @param {"a agenda de publicação" | "a coleta de métricas" | "as respostas do omnichat"} what
+ * @param {"schedule" | "metrics" | "omnichat"} key the `cloud.<key>` switch that turns it on
+ * @param {string} [platform]
+ */
+export const noLocalAgent = (what, key, platform = process.platform) =>
+  `aviso: no ${osName(platform)} não há agente local (o launchd é do macOS): ${what} fica com a cloud. Ligue cloud.${key} no omnivideo.config.json e rode cloud push.`;

package/tools/lib/service-run.mjs

@@ -0,0 +1,124 @@
+/* Keeps the studio running on Windows, the way launchd's KeepAlive does on macOS
+   (tools/lib/service-windows.mjs installs a scheduled task that runs this at login):
+
+     node service-run.mjs <studio-service.json> [state file]
+
+   It starts the command in the spec, and each time it exits starts it again, never sooner than `throttle_s`
+   after the previous start (launchd's ThrottleInterval: a studio already open in a terminal holding the port
+   just waits its turn). The command's output, and these notes, go to the spec's log. The pids go to the state
+   file, which is how `service()` knows the studio is up and how it is stopped. Ending the supervisor ends the
+   command with it. The spec is JSON, written at install time:
+
+     { "command": "<bun>", "args": ["studio.ts"], "cwd": "<code root>/studio", "log": "<.runner/studio.log>",
+       "throttle_s": 30, "env": { "PATH": "…", "OMNI_HOME": "…" } }
+
+   Runs under any OS (the tests run it on macOS and Linux too). Notes in Portuguese: they land in a log the
+   user reads. */
+
+import { spawn } from "node:child_process";
+import { mkdirSync, openSync, readFileSync, rmSync, writeFileSync, writeSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isMainModule } from "./paths.mjs";
+
+/**
+ * @typedef {{ command: string, args?: string[], cwd?: string, log: string, throttle_s?: number, throttle_ms?: number,
+ *   env?: Record<string, string> }} Spec
+ */
+
+/** `base` with `extra` laid over it. Windows names are case-blind (Path, PATH): an extra PATH replaces the
+ *  Path already there instead of sitting beside it  @param {NodeJS.ProcessEnv} base @param {Record<string, string>} extra */
+export function mergeEnv(base, extra, caseBlind = process.platform === "win32") {
+  const out = { ...base };
+  for (const [k, v] of Object.entries(extra)) {
+    if (caseBlind) for (const key of Object.keys(out)) if (key.toLowerCase() === k.toLowerCase()) delete out[key];
+    out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Runs the spec's command until the supervisor is stopped (or `maxStarts` runs have ended: the tests).
+ * @param {Spec} spec
+ * @param {{ stateFile?: string, maxStarts?: number, signals?: boolean }} [o]
+ * @returns {Promise<{ starts: number }>}
+ */
+export async function supervise(spec, { stateFile, maxStarts = Number.POSITIVE_INFINITY, signals = true } = {}) {
+  mkdirSync(dirname(spec.log), { recursive: true });
+  const logFd = openSync(spec.log, "a");
+  const say = (/** @type {string} */ line) => {
+    try {
+      writeSync(logFd, `[omni ${new Date().toISOString()}] ${line}\n`);
+    } catch {
+      /* the log is a copy of what happened; the loop goes on */
+    }
+  };
+  const throttleMs = spec.throttle_ms ?? (spec.throttle_s ?? 30) * 1000;
+  /** @type {import("node:child_process").ChildProcess | null} */
+  let child = null;
+  let stopping = false;
+  let wake = () => {};
+
+  const writeState = (/** @type {number | null} */ pid) => {
+    if (!stateFile) return;
+    try {
+      writeFileSync(stateFile, `${JSON.stringify({ supervisor: process.pid, child: pid })}\n`);
+    } catch {
+      /* the state is a convenience for status */
+    }
+  };
+  const stop = () => {
+    stopping = true;
+    child?.kill();
+    wake();
+  };
+  if (signals) for (const sig of ["SIGTERM", "SIGINT", "SIGBREAK"]) process.on(sig, stop);
+
+  let starts = 0;
+  while (!stopping && starts < maxStarts) {
+    const startedAt = Date.now();
+    starts++;
+    const exit = await new Promise(resolve => {
+      try {
+        child = spawn(spec.command, spec.args ?? [], {
+          cwd: spec.cwd,
+          env: mergeEnv(process.env, spec.env ?? {}),
+          stdio: ["ignore", logFd, logFd],
+          windowsHide: true,
+        });
+      } catch (e) {
+        say(`não consegui abrir ${spec.command}: ${/** @type {Error} */ (e).message}`);
+        resolve("erro");
+        return;
+      }
+      writeState(child.pid ?? null);
+      say(`studio aberto (pid ${child.pid})`);
+      child.once("error", e => {
+        say(`erro ao abrir ${spec.command}: ${e.message}`);
+        resolve("erro");
+      });
+      child.once("exit", (code, signal) => resolve(code ?? signal));
+    });
+    child = null;
+    writeState(null);
+    if (stopping || starts >= maxStarts) break;
+    const wait = Math.max(0, throttleMs - (Date.now() - startedAt));
+    say(`o studio saiu (${exit}); abro de novo em ${Math.ceil(wait / 1000)} s`);
+    await new Promise(resolve => {
+      wake = /** @type {() => void} */ (resolve);
+      setTimeout(resolve, wait);
+    });
+  }
+  say("supervisor encerrado");
+  if (stateFile) rmSync(stateFile, { force: true });
+  return { starts };
+}
+
+if (isMainModule(import.meta.url)) {
+  const [specFile, stateArg] = process.argv.slice(2);
+  if (!specFile) {
+    console.error("uso: node service-run.mjs <studio-service.json> [arquivo de estado]");
+    process.exit(2);
+  }
+  const spec = /** @type {Spec} */ (JSON.parse(readFileSync(specFile, "utf8")));
+  await supervise(spec, { stateFile: stateArg ?? join(dirname(specFile), "studio-service.state.json") });
+}

package/tools/lib/service-windows.mjs

@@ -0,0 +1,240 @@
+/* The studio kept on at login on Windows: a scheduled task, the equivalent of the launchd agent in
+   tools/lib/service.mjs (docs/specs/phase-2-plugin-cli.md, "Windows"). No administrator and no extra program:
+   `schtasks`, which every Windows has, registers it for the current user.
+
+     the task      runs at the user's logon, in the user's own session (so the credential vault answers),
+                   with no time limit, one instance, on battery too; Task Scheduler's own restart-on-failure
+                   is the net under the supervisor
+     the action    PowerShell, hidden, running node on tools/lib/service-run.mjs: the supervisor keeps the
+                   studio up and restarts it when it exits (launchd's KeepAlive), writing to .runner/studio.log
+     the files     .runner/studio-service.json (what to run), studio-task.xml (the task as registered, to
+                   tell whether a reinstall would change anything), studio-service.state.json (the pids)
+
+   Everything that touches the machine goes through `deps` (schtasks, taskkill, liveness), so the tests drive it
+   from any OS. Throws Errors in Portuguese; the callers print them. */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { userInfo } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+
+export const TASK_NAME = "OmniVideoStudio";
+export const SPEC_FILE = "studio-service.json";
+export const TASK_FILE = "studio-task.xml";
+export const STATE_FILE = "studio-service.state.json";
+
+/** @typedef {{ status: number | null, stdout: string, stderr: string }} Run */
+/** @typedef {{ bun: string, codeRoot: string, dataRoot: string, binDir: string, path: string }} InstallOptions */
+/** @typedef {{ schtasks: (args: string[]) => Run, killTree: (pid: number) => void, isAlive: (pid: number) => boolean, user: () => string }} Deps */
+
+/** the real machine  @returns {Deps} */
+export const realDeps = () => ({
+  schtasks: args => {
+    const r = spawnSync("schtasks", args, { encoding: "utf8", windowsHide: true });
+    return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+  },
+  killTree: pid => {
+    spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true });
+  },
+  isAlive: pid => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (e) {
+      return /** @type {NodeJS.ErrnoException} */ (e).code === "EPERM";
+    }
+  },
+  user: () => (process.env.USERDOMAIN ? `${process.env.USERDOMAIN}\\${process.env.USERNAME}` : userInfo().username),
+});
+
+/* --- what gets written ------------------------------------------------------------------- */
+
+/**
+ * What the supervisor runs: bun on studio.ts from the studio folder, with a PATH that has ~/.omni/bin first
+ * (ffmpeg, the venv's Python, yt-dlp) and OMNI_HOME when the workspace is not the code root.
+ * @param {{ bun: string, codeRoot: string, dataRoot: string, binDir: string, nodeDir: string, path: string, log: string, throttleS?: number, delimiter?: string }} o
+ */
+export function serviceSpec(o) {
+  const sep = o.delimiter ?? delimiter;
+  const dirs = [o.binDir, dirname(o.bun), o.nodeDir, ...o.path.split(sep)].filter(Boolean);
+  return {
+    command: o.bun,
+    args: ["studio.ts"],
+    cwd: join(o.codeRoot, "studio"),
+    log: o.log,
+    throttle_s: o.throttleS ?? 30,
+    env: {
+      PATH: [...new Set(dirs)].join(sep),
+      ...(o.dataRoot === o.codeRoot ? {} : { OMNI_HOME: o.dataRoot }),
+    },
+  };
+}
+
+const xmlText = (/** @type {string} */ v) => v.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/** a PowerShell single-quoted string: the only escape is doubling the quote */
+const psQuote = (/** @type {string} */ v) => `'${v.replace(/'/g, "''")}'`;
+
+/** the PowerShell arguments: hidden window, no profile, node on the supervisor with the spec and state files */
+export function powershellArguments(
+  /** @type {{ node: string, runScript: string, specFile: string, stateFile: string }} */ o,
+) {
+  const call = `& ${psQuote(o.node)} ${psQuote(o.runScript)} ${psQuote(o.specFile)} ${psQuote(o.stateFile)}; exit $LASTEXITCODE`;
+  return `-NoProfile -NonInteractive -WindowStyle Hidden -Command "${call}"`;
+}
+
+/**
+ * The task definition (Task Scheduler's XML schema 1.2). LogonType InteractiveToken + LeastPrivilege: it runs as
+ * the user, in the user's session, with no password stored and no administrator.
+ * @param {{ user: string, node: string, runScript: string, specFile: string, stateFile: string }} o
+ */
+export function taskXml(o) {
+  const user = xmlText(o.user);
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>OmniVideo: o studio deste computador, aberto no login e reaberto se parar</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${user}</UserId>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>${user}</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>999</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>powershell.exe</Command>
+      <Arguments>${xmlText(powershellArguments(o))}</Arguments>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+
+/** schtasks reads the definition as UTF-16 with a byte order mark  @param {string} xml */
+export const encodeTaskXml = xml => Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(xml, "utf16le")]);
+
+/* --- the service ------------------------------------------------------------------------- */
+
+/**
+ * @param {{ dir: string, logFile: string, runScript: string, nodePath?: string, deps?: Deps }} cfg
+ *   dir: where the files above live (.runner/); logFile: the studio's log; runScript: the supervisor's path
+ */
+export function windowsService({ dir, logFile, runScript, nodePath = process.execPath, deps = realDeps() }) {
+  const file = (/** @type {string} */ name) => join(dir, name);
+  const readState = () => {
+    try {
+      return JSON.parse(readFileSync(file(STATE_FILE), "utf8"));
+    } catch {
+      return {};
+    }
+  };
+  const registered = () => deps.schtasks(["/Query", "/TN", TASK_NAME]).status === 0;
+
+  /** the two files an install writes, as text and bytes  @param {InstallOptions} o */
+  const plan = o => ({
+    spec: `${JSON.stringify(serviceSpec({ ...o, nodeDir: dirname(nodePath), log: logFile }), null, 2)}\n`,
+    xml: encodeTaskXml(
+      taskXml({
+        user: deps.user(),
+        node: nodePath,
+        runScript,
+        specFile: file(SPEC_FILE),
+        stateFile: file(STATE_FILE),
+      }),
+    ),
+  });
+
+  /** ends the task and, to be sure, the processes it left: Task Scheduler's End takes the tree down, taskkill is the net */
+  const stop = () => {
+    deps.schtasks(["/End", "/TN", TASK_NAME]);
+    const { supervisor, child } = readState();
+    for (const pid of [supervisor, child]) if (pid && deps.isAlive(pid)) deps.killTree(pid);
+    rmSync(file(STATE_FILE), { force: true });
+  };
+
+  return {
+    /** what Task Scheduler and the supervisor say: registered, and the studio's pid when it is up */
+    status() {
+      const installed = registered();
+      const child = readState().child;
+      const pid = installed && child && deps.isAlive(child) ? child : null;
+      return { installed, loaded: installed, pid, log: logFile };
+    },
+
+    /** the studio folder the installed service runs from (the spec's cwd), or "" */
+    workingDir() {
+      try {
+        return String(JSON.parse(readFileSync(file(SPEC_FILE), "utf8")).cwd ?? "");
+      } catch {
+        return "";
+      }
+    },
+
+    /** whether installing `o` would change nothing: same spec, same task, and the task is registered
+     *  @param {InstallOptions} o */
+    upToDate(o) {
+      const { spec, xml } = plan(o);
+      return (
+        existsSync(file(SPEC_FILE)) &&
+        existsSync(file(TASK_FILE)) &&
+        readFileSync(file(SPEC_FILE), "utf8") === spec &&
+        readFileSync(file(TASK_FILE)).equals(xml) &&
+        registered()
+      );
+    },
+
+    /**
+     * Registers (or replaces) the task and starts it now, which a logon trigger would only do at the next login.
+     * @param {InstallOptions} o
+     */
+    install(o) {
+      const { spec, xml } = plan(o);
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(file(SPEC_FILE), spec);
+      writeFileSync(file(TASK_FILE), xml);
+      /* a reinstall replaces what runs: stop the old one first, like bootout before bootstrap */
+      stop();
+      const created = deps.schtasks(["/Create", "/TN", TASK_NAME, "/XML", file(TASK_FILE), "/F"]);
+      if (created.status !== 0) throw new Error(`schtasks /Create: ${(created.stderr || created.stdout).trim()}`);
+      const started = deps.schtasks(["/Run", "/TN", TASK_NAME]);
+      if (started.status !== 0) throw new Error(`schtasks /Run: ${(started.stderr || started.stdout).trim()}`);
+    },
+
+    uninstall() {
+      stop();
+      deps.schtasks(["/Delete", "/TN", TASK_NAME, "/F"]);
+      for (const name of [SPEC_FILE, TASK_FILE, STATE_FILE]) rmSync(file(name), { force: true });
+    },
+
+    restart() {
+      if (!registered()) throw new Error("o serviço não está ligado");
+      stop();
+      const r = deps.schtasks(["/Run", "/TN", TASK_NAME]);
+      if (r.status !== 0) throw new Error(`schtasks /Run: ${(r.stderr || r.stdout).trim()}`);
+    },
+  };
+}