@dbx-tools/cli-service 0.9.36

package/src/_host.ts

@@ -0,0 +1,249 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import * as systrayModule from "systray2";
+import type SysTrayType from "systray2";
+import type { MenuItem } from "systray2";
+
+import { readServiceDefinition } from "./_config.ts";
+import {
+  closeServiceControl,
+  listenForServiceControl,
+  type ServiceControlResponse,
+} from "./_control.ts";
+import { defaultRuntimeContext, resolveServicePaths, type ServicePaths } from "./_paths.ts";
+import type { CliServiceCommand, CliServiceDefinition, CliServiceMenuItem } from "./definition.ts";
+
+const CHILD_STOP_TIMEOUT_MILLISECONDS = 5_000;
+const SysTray = systrayConstructor();
+
+interface ActionMenuItem extends MenuItem {
+  readonly click?: () => void;
+}
+
+function systrayConstructor(): typeof SysTrayType {
+  const loaded: unknown = systrayModule.default;
+  if (typeof loaded === "function") return loaded as typeof SysTrayType;
+  const nested =
+    loaded && typeof loaded === "object" ? (loaded as { default?: unknown }).default : undefined;
+  if (typeof nested === "function") return nested as typeof SysTrayType;
+  throw new TypeError("systray2 did not provide a constructor");
+}
+
+class CliServiceHost {
+  private readonly definition: CliServiceDefinition;
+  private readonly paths: ServicePaths;
+  private readonly requestStop: () => void;
+  private tray?: SysTrayType;
+  private service?: ChildProcess;
+  private control?: Awaited<ReturnType<typeof listenForServiceControl>>;
+  private stopping = false;
+
+  constructor(definition: CliServiceDefinition, paths: ServicePaths, requestStop: () => void) {
+    this.definition = definition;
+    this.paths = paths;
+    this.requestStop = requestStop;
+  }
+
+  async start(): Promise<void> {
+    await mkdir(this.paths.directory, { recursive: true });
+    this.service = this.definition.command
+      ? this.startProcess(this.definition.command, true)
+      : undefined;
+    this.tray = this.createTray();
+    await this.tray.ready();
+    this.tray.onError((error) => {
+      void logError(this.paths.hostLog, error);
+      this.requestStop();
+    });
+    this.tray.onExit((code, signal) => {
+      if (this.stopping) return;
+      void logMessage(this.paths.hostLog, `system tray exited (${signal ?? String(code)})`);
+      this.requestStop();
+    });
+    await this.tray.onClick((action) => {
+      const item = action.item as ActionMenuItem;
+      item.click?.();
+    });
+    this.control = await listenForServiceControl(
+      this.paths.controlAddress,
+      () => this.status(),
+      this.requestStop,
+    );
+  }
+
+  async stop(): Promise<void> {
+    if (this.stopping) return;
+    this.stopping = true;
+    if (this.control) {
+      await closeServiceControl(this.control, this.paths.controlAddress);
+      this.control = undefined;
+    }
+    if (this.tray) {
+      if (this.tray.process.exitCode === null && this.tray.process.signalCode === null) {
+        await this.tray.kill(false);
+      }
+      this.tray = undefined;
+    }
+    if (this.service) {
+      await stopProcess(this.service);
+      this.service = undefined;
+    }
+  }
+
+  private status(): ServiceControlResponse {
+    return {
+      running: true,
+      pid: process.pid,
+      ...(this.service?.pid ? { servicePid: this.service.pid } : {}),
+    };
+  }
+
+  private startProcess(command: CliServiceCommand, managed: boolean): ChildProcess {
+    if (!command.executable) {
+      throw new Error("installed service commands require an executable");
+    }
+    const logDescriptor = openSync(this.paths.processLog, "a");
+    const child = spawn(command.executable, command.arguments ?? [], {
+      cwd: command.cwd,
+      env: { ...process.env, ...command.environment },
+      stdio: ["ignore", logDescriptor, logDescriptor],
+    });
+    closeSync(logDescriptor);
+    child.once("error", (error) => {
+      void logError(this.paths.hostLog, error);
+      if (managed) this.requestStop();
+    });
+    child.once("exit", (code, signal) => {
+      if (!this.stopping && managed) {
+        void logMessage(this.paths.hostLog, `managed service exited (${signal ?? String(code)})`);
+        this.requestStop();
+      }
+    });
+    return child;
+  }
+
+  private createTray(): SysTrayType {
+    return new SysTray({
+      menu: {
+        icon: this.definition.icon,
+        title: "",
+        tooltip: `${this.definition.name} ${this.definition.version}`,
+        items: this.menuItems(),
+        isTemplateIcon: this.definition.isTemplateIcon,
+      },
+      debug: false,
+      copyDir: false,
+    });
+  }
+
+  private menuItems(): ActionMenuItem[] {
+    const custom = (this.definition.menu ?? []).map((item) => this.menuItem(item));
+    return [
+      {
+        title: `${this.definition.name} - ${this.definition.version}`,
+        tooltip: "",
+        enabled: false,
+      },
+      ...custom,
+      { ...SysTray.separator },
+      {
+        title: "Quit",
+        tooltip: `Stop ${this.definition.name}`,
+        click: this.requestStop,
+      },
+    ];
+  }
+
+  private menuItem(item: CliServiceMenuItem): ActionMenuItem {
+    if (item.type === "separator") return { ...SysTray.separator };
+    if (item.type === "url") {
+      return {
+        title: item.label,
+        tooltip: item.url,
+        click: () => {
+          this.openUrl(item.url);
+        },
+      };
+    }
+    return {
+      title: item.label,
+      tooltip: "",
+      click: () => {
+        const child = this.startProcess(item.command, false);
+        child.unref();
+      },
+    };
+  }
+
+  private openUrl(url: string): void {
+    const command =
+      process.platform === "darwin"
+        ? { executable: "open", arguments: [url] }
+        : process.platform === "win32"
+          ? {
+              executable: "rundll32.exe",
+              arguments: ["url.dll,FileProtocolHandler", url],
+            }
+          : { executable: "xdg-open", arguments: [url] };
+    const child = this.startProcess(command, false);
+    child.unref();
+  }
+}
+
+async function runCliServiceHost(configFile: string): Promise<void> {
+  process.chdir(dirname(process.execPath));
+  const definition = await readServiceDefinition(configFile);
+  const runtime = defaultRuntimeContext();
+  const paths = resolveServicePaths(definition, runtime);
+  let requestStop: () => void = () => {};
+  const stopped = new Promise<void>((resolve) => {
+    requestStop = resolve;
+  });
+  const host = new CliServiceHost(definition, paths, requestStop);
+  process.once("SIGINT", requestStop);
+  process.once("SIGTERM", requestStop);
+  try {
+    await host.start();
+    await stopped;
+  } finally {
+    await host.stop();
+  }
+}
+
+async function stopProcess(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  const exited = new Promise<void>((resolve) => child.once("exit", () => resolve()));
+  child.kill("SIGTERM");
+  const timedOut = new Promise<"timeout">((resolve) => {
+    setTimeout(() => resolve("timeout"), CHILD_STOP_TIMEOUT_MILLISECONDS);
+  });
+  if ((await Promise.race([exited, timedOut])) === "timeout") {
+    child.kill("SIGKILL");
+    await exited;
+  }
+}
+
+async function logError(path: string, error: unknown): Promise<void> {
+  await logMessage(path, error instanceof Error ? (error.stack ?? error.message) : String(error));
+}
+
+async function logMessage(path: string, message: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await appendFile(path, `${new Date().toISOString()} ${message}\n`, "utf8");
+}
+
+function argumentValue(name: string): string | undefined {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+const configFile = argumentValue("--service-config");
+if (configFile) {
+  void runCliServiceHost(configFile).catch(async (error: unknown) => {
+    await logError(join(dirname(configFile), "host.log"), error);
+    process.exitCode = 1;
+  });
+}

package/src/_package.ts

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import * as projectUtils from "@dbx-tools/core/project-utils";
+
+export interface ServicePackage {
+  readonly directory: string;
+  readonly name: string;
+  readonly version: string;
+  bin(name?: string): string;
+  dependencies(): Readonly<Record<string, string>>;
+}
+
+export function resolveServicePackage(
+  reference: string,
+  cwd: string = process.cwd(),
+): ServicePackage {
+  const local = localManifest(reference);
+  if (local) return servicePackage(local);
+
+  const name = reference;
+  const installed = installedManifest(name);
+  if (installed) return servicePackage(installed, name);
+
+  const root = projectUtils.root(cwd);
+  if (!root) throw new Error(`could not resolve package: ${name}`);
+  const manifest = readRecord(join(root, "package.json"));
+  const workspaces = Array.isArray(manifest.workspaces) ? manifest.workspaces : [];
+  for (const member of workspaces) {
+    if (typeof member !== "string" || /[*?[\]{}]/.test(member)) continue;
+    const path = join(root, member, "package.json");
+    if (!existsSync(path)) continue;
+    const candidate = readRecord(path);
+    if (candidate.name === name) return servicePackage(path, name);
+  }
+  throw new Error(`could not resolve installed or workspace package: ${name}`);
+}
+
+export function servicePackageDefaults(pkg: ServicePackage): {
+  id: string;
+  name: string;
+} {
+  const segments = pkg.name.replace(/^@/, "").split("/");
+  const rawName = segments.at(-1)!;
+  const rawScope = segments.length > 1 ? segments[0]!.split("-")[0]! : "";
+  const name = rawName.replace(/^cli-/, "").replaceAll("-", " ");
+  return {
+    id: pkg.name
+      .replace(/^@/, "")
+      .replaceAll("/", ".")
+      .replace(/[^a-z0-9._-]+/gi, "-"),
+    name: [rawScope, name].filter(Boolean).join(" "),
+  };
+}
+
+function localManifest(reference: string): string | undefined {
+  let path: string;
+  if (reference.startsWith("file:")) {
+    path = fileURLToPath(reference);
+  } else if (isAbsolute(reference)) {
+    path = reference;
+  } else {
+    return undefined;
+  }
+  let current = existsSync(path) ? dirname(path) : path;
+  while (true) {
+    const manifest = join(current, "package.json");
+    if (existsSync(manifest)) return manifest;
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+function installedManifest(name: string): string | undefined {
+  try {
+    return createRequire(import.meta.url).resolve(`${name}/package.json`);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "MODULE_NOT_FOUND") return undefined;
+    throw error;
+  }
+}
+
+function servicePackage(manifestPath: string, expectedName?: string): ServicePackage {
+  const manifest = readRecord(manifestPath);
+  if (typeof manifest.name !== "string" || !manifest.name) {
+    throw new Error(`package has no name: ${manifestPath}`);
+  }
+  if (expectedName && manifest.name !== expectedName) {
+    throw new Error(`resolved package name does not match ${expectedName}: ${manifestPath}`);
+  }
+  if (typeof manifest.version !== "string" || !manifest.version) {
+    throw new Error(`package has no version: ${manifestPath}`);
+  }
+  const directory = dirname(manifestPath);
+  return {
+    directory,
+    name: manifest.name,
+    version: manifest.version,
+    bin(name) {
+      return resolveBin(directory, manifest.bin, name);
+    },
+    dependencies() {
+      const dependencies = isRecord(manifest.dependencies)
+        ? Object.keys(manifest.dependencies)
+        : [];
+      const require = createRequire(manifestPath);
+      return Object.fromEntries(
+        dependencies.map((dependency) => {
+          const path = require.resolve(`${dependency}/package.json`);
+          const resolved = readRecord(path);
+          if (typeof resolved.version !== "string" || !resolved.version) {
+            throw new Error(`dependency has no version: ${path}`);
+          }
+          return [dependency, resolved.version];
+        }),
+      );
+    },
+  };
+}
+
+function resolveBin(directory: string, value: unknown, name?: string): string {
+  if (typeof value === "string") {
+    if (name) throw new Error(`package exposes one unnamed bin, not ${name}`);
+    return resolve(directory, value);
+  }
+  if (!isRecord(value)) throw new Error("package has no bin");
+  if (name) {
+    const target = value[name];
+    if (typeof target !== "string") throw new Error(`package has no bin named ${name}`);
+    return resolve(directory, target);
+  }
+  const targets = Object.values(value).filter(
+    (target): target is string => typeof target === "string",
+  );
+  if (targets.length !== 1) {
+    throw new Error("package has multiple bins; command.binName is required");
+  }
+  return resolve(directory, targets[0]!);
+}
+
+function readRecord(path: string): Record<string, unknown> {
+  const value: unknown = JSON.parse(readFileSync(path, "utf8"));
+  if (!isRecord(value)) throw new Error(`package manifest is not an object: ${path}`);
+  return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/_paths.ts

@@ -0,0 +1,104 @@
+import { createHash } from "node:crypto";
+import { homedir, tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+
+import type { CliServiceDefinition } from "./definition.ts";
+
+export interface ServiceRuntimeContext {
+  readonly platform: NodeJS.Platform;
+  readonly environment: Readonly<NodeJS.ProcessEnv>;
+  readonly homeDirectory: string;
+  readonly temporaryDirectory: string;
+}
+
+export interface ServicePaths {
+  readonly directory: string;
+  readonly configFile: string;
+  readonly hostLog: string;
+  readonly processLog: string;
+  readonly controlAddress: string;
+  readonly startupFile: string;
+}
+
+export function defaultRuntimeContext(): ServiceRuntimeContext {
+  return {
+    platform: process.platform,
+    environment: process.env,
+    homeDirectory: homedir(),
+    temporaryDirectory: tmpdir(),
+  };
+}
+
+export function resolveServicePaths(
+  definition: CliServiceDefinition,
+  runtime: ServiceRuntimeContext,
+): ServicePaths {
+  const directory = definition.dataDirectory
+    ? resolve(definition.dataDirectory)
+    : join(configurationRoot(runtime), definition.id);
+  return {
+    directory,
+    configFile: join(directory, "service.json"),
+    hostLog: join(directory, "host.log"),
+    processLog: join(directory, "service.log"),
+    controlAddress: controlAddress(definition.id, runtime),
+    startupFile: startupFile(definition.id, runtime),
+  };
+}
+
+function configurationRoot(runtime: ServiceRuntimeContext): string {
+  if (runtime.platform === "darwin") {
+    return join(runtime.homeDirectory, "Library", "Application Support");
+  }
+  if (runtime.platform === "win32") {
+    return resolveEnvironmentPath(
+      runtime.environment.APPDATA,
+      join(runtime.homeDirectory, "AppData", "Roaming"),
+    );
+  }
+  return resolveEnvironmentPath(
+    runtime.environment.XDG_CONFIG_HOME,
+    join(runtime.homeDirectory, ".config"),
+  );
+}
+
+function controlAddress(id: string, runtime: ServiceRuntimeContext): string {
+  const token = createHash("sha256").update(id).digest("hex").slice(0, 16);
+  if (runtime.platform === "win32") {
+    return `\\\\.\\pipe\\dbx-tools-cli-service-${token}`;
+  }
+  return join(runtime.temporaryDirectory, `dbx-tools-cli-service-${token}.sock`);
+}
+
+function startupFile(id: string, runtime: ServiceRuntimeContext): string {
+  if (runtime.platform === "darwin") {
+    return join(runtime.homeDirectory, "Library", "LaunchAgents", `${id}.plist`);
+  }
+  if (runtime.platform === "win32") {
+    return join(
+      resolveEnvironmentPath(
+        runtime.environment.APPDATA,
+        join(runtime.homeDirectory, "AppData", "Roaming"),
+      ),
+      "Microsoft",
+      "Windows",
+      "Start Menu",
+      "Programs",
+      "Startup",
+      `${id}.cmd`,
+    );
+  }
+  return join(
+    resolveEnvironmentPath(
+      runtime.environment.XDG_CONFIG_HOME,
+      join(runtime.homeDirectory, ".config"),
+    ),
+    "autostart",
+    `${id}.desktop`,
+  );
+}
+
+function resolveEnvironmentPath(value: string | undefined, fallback: string): string {
+  if (!value) return fallback;
+  return isAbsolute(value) ? value : resolve(value);
+}

package/src/_runtime.ts

@@ -0,0 +1,66 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import * as exec from "@dbx-tools/core/exec";
+
+export function externalRuntimePackages(dependencies: Readonly<Record<string, string>>): string[] {
+  return Object.keys(dependencies).filter((name) => !name.startsWith("@dbx-tools/"));
+}
+
+export async function installServiceRuntime(
+  bunExecutable: string,
+  directory: string,
+  dependencies: Readonly<Record<string, string>>,
+): Promise<void> {
+  await mkdir(directory, { recursive: true });
+  const manifestPath = join(directory, "package.json");
+  const current = await readOptionalRecord(manifestPath);
+  await writeFile(
+    manifestPath,
+    `${JSON.stringify(
+      {
+        ...current,
+        name: "@dbx-tools/service-runtime",
+        private: true,
+        dependencies: {
+          ...stringRecord(current.dependencies),
+          ...dependencies,
+        },
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+  await exec.spawn(bunExecutable, ["install", "--production", "--cwd", directory], {
+    check: true,
+    cwd: directory,
+    stdin: "ignore",
+    stdout: "capture",
+    stderr: "capture",
+  });
+}
+
+async function readOptionalRecord(path: string): Promise<Record<string, unknown>> {
+  try {
+    const value: unknown = JSON.parse(await readFile(path, "utf8"));
+    if (!isRecord(value)) throw new Error(`JSON file is not an object: ${path}`);
+    return value;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+function stringRecord(value: unknown): Record<string, string> {
+  if (!isRecord(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    ),
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/_startup.ts

@@ -0,0 +1,106 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import type { ServicePaths, ServiceRuntimeContext } from "./_paths.ts";
+import type { CliServiceDefinition } from "./definition.ts";
+
+export interface ServiceLaunch {
+  readonly executable: string;
+  readonly arguments: readonly string[];
+}
+
+export async function installStartup(
+  definition: CliServiceDefinition,
+  paths: ServicePaths,
+  runtime: ServiceRuntimeContext,
+  launch: ServiceLaunch,
+): Promise<void> {
+  await mkdir(dirname(paths.startupFile), { recursive: true });
+  const content =
+    runtime.platform === "darwin"
+      ? renderLaunchAgent(definition, launch)
+      : runtime.platform === "win32"
+        ? renderWindowsStartup(launch)
+        : renderDesktopEntry(definition, launch);
+  await writeFile(paths.startupFile, content, {
+    encoding: "utf8",
+    mode: runtime.platform === "win32" ? undefined : 0o644,
+  });
+}
+
+export async function removeStartup(paths: ServicePaths): Promise<void> {
+  await rm(paths.startupFile, { force: true });
+}
+
+export function renderLaunchAgent(definition: CliServiceDefinition, launch: ServiceLaunch): string {
+  const argumentsXml = [launch.executable, ...launch.arguments]
+    .map((argument) => `      <string>${escapeXml(argument)}</string>`)
+    .join("\n");
+  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>${escapeXml(definition.id)}</string>`,
+    "    <key>ProgramArguments</key>",
+    "    <array>",
+    argumentsXml,
+    "    </array>",
+    "    <key>RunAtLoad</key>",
+    "    <true/>",
+    "    <key>ProcessType</key>",
+    "    <string>Interactive</string>",
+    "  </dict>",
+    "</plist>",
+    "",
+  ].join("\n");
+}
+
+export function renderDesktopEntry(
+  definition: CliServiceDefinition,
+  launch: ServiceLaunch,
+): string {
+  return [
+    "[Desktop Entry]",
+    "Type=Application",
+    `Name=${escapeDesktopValue(definition.name)}`,
+    `Exec=${[launch.executable, ...launch.arguments].map(quoteDesktopArgument).join(" ")}`,
+    "Terminal=false",
+    "X-GNOME-Autostart-enabled=true",
+    "",
+  ].join("\n");
+}
+
+export function renderWindowsStartup(launch: ServiceLaunch): string {
+  const command = [launch.executable, ...launch.arguments].map(quoteWindowsArgument).join(" ");
+  return `@echo off\r\nstart "" /b ${command}\r\n`;
+}
+
+function escapeDesktopValue(value: string): string {
+  return value.replaceAll("\\", "\\\\").replaceAll("\n", "\\n");
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+function quoteDesktopArgument(value: string): string {
+  return `"${value
+    .replaceAll("\\", "\\\\")
+    .replaceAll('"', '\\"')
+    .replaceAll("`", "\\`")
+    .replaceAll("$", "\\$")}"`;
+}
+
+function quoteWindowsArgument(value: string): string {
+  const escapedPercent = value.replaceAll("%", "%%");
+  const escapedQuotes = escapedPercent.replace(/(\\*)"/g, '$1$1\\"');
+  const escapedTrailingSlashes = escapedQuotes.replace(/(\\+)$/, "$1$1");
+  return `"${escapedTrailingSlashes}"`;
+}