@toloka-platform/sdk 0.1.0-preview.6 → 0.1.0-preview.8

package/src/cli/auto-update.ts

@@ -0,0 +1,367 @@
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { realpathSync } from "node:fs";
+import { chmod, readFile, writeFile } from "node:fs/promises";
+import { join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { CliEnvironment } from "./credentials";
+import { configDirectory, preparePrivateFilePath } from "./credentials";
+import { SDK_VERSION } from "./init";
+import { commandNameFromArgv } from "./analytics";
+import { readCliSettings } from "./settings";
+import { CHECK_RESULT_FILE_ENV } from "./check";
+import { isFalseyFlag, isTruthyFlag } from "./boolean-flag";
+import packageMetadata from "../../package.json" with { type: "json" };
+
+export const AUTO_UPDATE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export const AUTO_UPDATE_QUARANTINE_MS = 24 * 60 * 60 * 1000;
+export const SDK_PACKAGE_NAME = packageMetadata.name;
+export const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org/";
+
+const SKIP_COMMANDS: Readonly<Record<string, true>> = {
+  config: true,
+  help: true,
+  version: true,
+};
+
+export type AutoUpdateState = {
+  readonly lastCheckedAt: string;
+};
+
+export type NpmPackageView = {
+  readonly "dist-tags"?: Readonly<Record<string, string>>;
+  readonly time?: Readonly<Record<string, string>>;
+};
+
+export type AutoUpdateInstall = (options: {
+  readonly packageName: string;
+  readonly version: string;
+  readonly registry: string;
+  readonly environment: CliEnvironment;
+}) => Promise<void>;
+
+export type AutoUpdateReexec = (options: {
+  readonly argv: readonly string[];
+  readonly environment: CliEnvironment;
+}) => Promise<number>;
+
+export type AutoUpdateHooks = {
+  readonly now?: () => Date;
+  readonly fetchRegistry?: (url: string) => Promise<NpmPackageView>;
+  readonly install?: AutoUpdateInstall;
+  readonly reexec?: AutoUpdateReexec;
+  readonly isGlobalInstall?: () => boolean | Promise<boolean>;
+};
+
+export type AutoUpdateResult =
+  | { readonly status: "continue" }
+  | { readonly status: "reexec"; readonly exitCode: number };
+
+type CliIoWriter = {
+  readonly stderr: (text: string) => void;
+};
+
+type UpdateCheck = { readonly status: "skip" } | { readonly status: "check"; readonly now: Date };
+
+type UpdateCandidate =
+  | { readonly status: "skip" }
+  | { readonly status: "update"; readonly currentVersion: string; readonly version: string };
+
+export const autoUpdateStatePath = (environment: CliEnvironment = process.env): string =>
+  join(configDirectory(environment), "auto-update.json");
+
+export const npmRegistryUrl = (): string => DEFAULT_NPM_REGISTRY;
+
+export const npmPackageMetadataUrl = (packageName: string): string =>
+  new URL(encodeURIComponent(packageName), DEFAULT_NPM_REGISTRY).toString();
+
+export const parseSdkVersion = (version: string): readonly number[] | undefined => {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-preview\.(\d+))?$/u.exec(version);
+  if (match === null) return undefined;
+  const [, major, minor, patch, preview] = match;
+  return [
+    Number(major),
+    Number(minor),
+    Number(patch),
+    preview === undefined ? Number.POSITIVE_INFINITY : Number(preview),
+  ];
+};
+
+export const compareSdkVersions = (left: string, right: string): number | undefined => {
+  const parsedLeft = parseSdkVersion(left);
+  const parsedRight = parseSdkVersion(right);
+  if (parsedLeft === undefined || parsedRight === undefined) return undefined;
+  const length = Math.max(parsedLeft.length, parsedRight.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = parsedLeft[index] ?? 0;
+    const rightPart = parsedRight[index] ?? 0;
+    if (leftPart < rightPart) return -1;
+    if (leftPart > rightPart) return 1;
+  }
+  return 0;
+};
+
+const asStringRecord = (value: unknown): Readonly<Record<string, string>> | undefined => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const record: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry !== "string") return undefined;
+    record[key] = entry;
+  }
+  return record;
+};
+
+export const asNpmPackageView = (payload: unknown): NpmPackageView | undefined => {
+  if (typeof payload !== "object" || payload === null) return undefined;
+  const tags = asStringRecord(Reflect.get(payload, "dist-tags"));
+  const time = asStringRecord(Reflect.get(payload, "time"));
+  if (tags === undefined && time === undefined) return {};
+  return {
+    ...(tags === undefined ? {} : { "dist-tags": tags }),
+    ...(time === undefined ? {} : { time }),
+  };
+};
+
+export const latestPublishedVersion = (view: NpmPackageView): string | undefined => {
+  const tags = view["dist-tags"];
+  if (tags === undefined) return undefined;
+  const preview = tags.preview;
+  if (typeof preview === "string" && preview.length > 0) return preview;
+  const latest = tags.latest;
+  return typeof latest === "string" && latest.length > 0 ? latest : undefined;
+};
+
+const publishedAt = (view: NpmPackageView, version: string): Date | undefined => {
+  const raw = view.time?.[version];
+  if (typeof raw !== "string" || raw.length === 0) return undefined;
+  const date = new Date(raw);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+};
+
+const asState = (payload: unknown): AutoUpdateState | undefined => {
+  if (typeof payload !== "object" || payload === null) return undefined;
+  const lastCheckedAt = Reflect.get(payload, "lastCheckedAt");
+  if (typeof lastCheckedAt !== "string" || lastCheckedAt.length === 0) return undefined;
+  const date = new Date(lastCheckedAt);
+  if (Number.isNaN(date.getTime())) return undefined;
+  return { lastCheckedAt };
+};
+
+export async function readAutoUpdateState(
+  environment: CliEnvironment = process.env,
+): Promise<AutoUpdateState | undefined> {
+  try {
+    return asState(JSON.parse(await readFile(autoUpdateStatePath(environment), "utf8")));
+  } catch {
+    return undefined;
+  }
+}
+
+export async function writeAutoUpdateState(
+  state: AutoUpdateState,
+  environment: CliEnvironment = process.env,
+): Promise<string> {
+  const path = autoUpdateStatePath(environment);
+  await preparePrivateFilePath(path);
+  await writeFile(path, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  await chmod(path, 0o600);
+  return path;
+}
+
+const BUN_GLOBAL_MARKER = `${sep}install${sep}global${sep}`;
+
+export const isGlobalCliInstall = (
+  entry = process.argv[1],
+  runtimePath = fileURLToPath(import.meta.url),
+): boolean =>
+  [entry, runtimePath].some((path) => {
+    if (typeof path !== "string") return false;
+    try {
+      return realpathSync(path).includes(BUN_GLOBAL_MARKER);
+    } catch {
+      return path.includes(BUN_GLOBAL_MARKER);
+    }
+  });
+
+export function autoUpdateEnabled(
+  environment: CliEnvironment,
+  settings: { readonly autoUpdate: boolean },
+): boolean {
+  if (isTruthyFlag(environment.TOLOKA_SKIP_AUTO_UPDATE)) return false;
+  const explicit = environment.TOLOKA_AUTO_UPDATE;
+  if (isFalseyFlag(explicit)) return false;
+  if (isTruthyFlag(explicit)) return true;
+  if (environment[CHECK_RESULT_FILE_ENV] !== undefined) return false;
+  if (isTruthyFlag(environment.CI)) return false;
+  if (isTruthyFlag(environment.VITEST)) return false;
+  return settings.autoUpdate;
+}
+
+const skippedCommand = (argv: readonly string[]): boolean => {
+  const command = commandNameFromArgv(argv);
+  return SKIP_COMMANDS[command] === true || command.startsWith("config ");
+};
+
+const collectOutput = async (stream: NodeJS.ReadableStream | null): Promise<string> => {
+  if (stream === null) return "";
+  const chunks: Buffer[] = [];
+  stream.on("data", (chunk: Buffer | string) => {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  });
+  await once(stream, "end").catch(() => undefined);
+  return Buffer.concat(chunks).toString("utf8");
+};
+
+class RegistryError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RegistryError";
+  }
+}
+
+const defaultFetchRegistry = async (url: string): Promise<NpmPackageView> => {
+  const response = await fetch(url, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(3000),
+  });
+  if (!response.ok) throw new RegistryError(`npm registry responded ${response.status}`);
+  const view = asNpmPackageView(await response.json());
+  if (view === undefined) throw new RegistryError("npm registry returned invalid package metadata");
+  return view;
+};
+
+const defaultInstall: AutoUpdateInstall = async ({
+  packageName,
+  version,
+  registry,
+  environment,
+}) => {
+  const child = spawn(
+    process.execPath,
+    ["add", "--global", `${packageName}@${version}`, `--registry=${registry}`],
+    {
+      env: { ...process.env, ...environment },
+      stdio: ["ignore", "pipe", "pipe"],
+    },
+  );
+  const [close, stdout, stderr] = await Promise.all([
+    once(child, "close"),
+    collectOutput(child.stdout),
+    collectOutput(child.stderr),
+  ]);
+  const exitCode = close[0];
+  if (exitCode === 0) return;
+  const detail = [stderr.trim(), stdout.trim()].filter((part) => part.length > 0).join("\n");
+  throw new Error(
+    detail.length > 0
+      ? `bun add --global failed: ${detail}`
+      : `bun add --global exited ${String(exitCode)}`,
+  );
+};
+
+const defaultReexec: AutoUpdateReexec = async ({ argv, environment }) => {
+  const entry = process.argv[1];
+  const child = spawn(process.execPath, entry === undefined ? [...argv] : [entry, ...argv], {
+    env: { ...process.env, ...environment, TOLOKA_SKIP_AUTO_UPDATE: "1" },
+    stdio: "inherit",
+  });
+  const [code] = await once(child, "close");
+  return typeof code === "number" ? code : 1;
+};
+
+const continueResult = (): AutoUpdateResult => ({ status: "continue" });
+
+const shouldCheckForUpdate = async (options: {
+  readonly argv: readonly string[];
+  readonly environment: CliEnvironment;
+  readonly hooks: AutoUpdateHooks;
+}): Promise<UpdateCheck> => {
+  const { argv, environment, hooks } = options;
+  if (skippedCommand(argv)) return { status: "skip" };
+  const isGlobal = hooks.isGlobalInstall ?? (() => isGlobalCliInstall());
+  if (!(await isGlobal())) return { status: "skip" };
+  const settings = await readCliSettings(environment);
+  if (!autoUpdateEnabled(environment, settings)) return { status: "skip" };
+
+  const now = hooks.now?.() ?? new Date();
+  const state = await readAutoUpdateState(environment);
+  if (state !== undefined) {
+    const lastCheckedAt = new Date(state.lastCheckedAt).getTime();
+    if (now.getTime() - lastCheckedAt < AUTO_UPDATE_INTERVAL_MS) return { status: "skip" };
+  }
+  return { status: "check", now };
+};
+
+const selectUpdateCandidate = async (options: {
+  readonly environment: CliEnvironment;
+  readonly io: CliIoWriter;
+  readonly now: Date;
+  readonly currentVersion: string;
+  readonly fetchRegistry: (url: string) => Promise<NpmPackageView>;
+}): Promise<UpdateCandidate> => {
+  const { environment, io, now, currentVersion, fetchRegistry } = options;
+  try {
+    await writeAutoUpdateState({ lastCheckedAt: now.toISOString() }, environment);
+  } catch {}
+
+  let view: NpmPackageView;
+  try {
+    view = await fetchRegistry(npmPackageMetadataUrl(SDK_PACKAGE_NAME));
+  } catch (error) {
+    io.stderr(
+      `Auto-update check failed: ${error instanceof Error ? error.message : String(error)}.`,
+    );
+    return { status: "skip" };
+  }
+
+  const version = latestPublishedVersion(view);
+  if (version === undefined) return { status: "skip" };
+  const order = compareSdkVersions(currentVersion, version);
+  if (order === undefined || order >= 0) return { status: "skip" };
+  const published = publishedAt(view, version);
+  if (published === undefined) return { status: "skip" };
+  if (now.getTime() - published.getTime() < AUTO_UPDATE_QUARANTINE_MS) return { status: "skip" };
+  return { status: "update", currentVersion, version };
+};
+
+export async function maybeAutoUpdate(options: {
+  readonly argv: readonly string[];
+  readonly environment: CliEnvironment;
+  readonly io: CliIoWriter;
+  readonly currentVersion?: string;
+  readonly hooks?: AutoUpdateHooks;
+}): Promise<AutoUpdateResult> {
+  const { argv, environment, io, hooks = {} } = options;
+  const check = await shouldCheckForUpdate({ argv, environment, hooks });
+  if (check.status === "skip") return continueResult();
+
+  const candidate = await selectUpdateCandidate({
+    environment,
+    io,
+    now: check.now,
+    currentVersion: options.currentVersion ?? SDK_VERSION,
+    fetchRegistry: hooks.fetchRegistry ?? defaultFetchRegistry,
+  });
+  if (candidate.status === "skip") return continueResult();
+
+  const install = hooks.install ?? defaultInstall;
+  try {
+    await install({
+      packageName: SDK_PACKAGE_NAME,
+      version: candidate.version,
+      registry: npmRegistryUrl(),
+      environment,
+    });
+  } catch (error) {
+    io.stderr(
+      `Auto-update to ${candidate.version} failed: ${error instanceof Error ? error.message : String(error)}.`,
+    );
+    return continueResult();
+  }
+
+  io.stderr(
+    `Updated ${SDK_PACKAGE_NAME} from ${candidate.currentVersion} to ${candidate.version}.`,
+  );
+  const reexec = hooks.reexec ?? defaultReexec;
+  return { status: "reexec", exitCode: await reexec({ argv, environment }) };
+}

package/src/cli/boolean-flag.ts

@@ -0,0 +1,13 @@
+export const isTruthyFlag = (value: string | undefined): boolean => {
+  if (value === undefined) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+};
+
+export const isFalseyFlag = (value: string | undefined): boolean => {
+  if (value === undefined) return false;
+  const normalized = value.trim().toLowerCase();
+  return (
+    normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off"
+  );
+};