@toloka-platform/sdk 0.2.0-preview.2 → 0.2.0-preview.4

package/src/cli/context.ts

@@ -0,0 +1,251 @@
+import { InvalidArgumentError, type Command } from "commander";
+import { resolve } from "node:path";
+import { createClient } from "../client";
+import type { PotatoClient } from "../client";
+import { readTolokaState } from "../state";
+import type { TolokaState } from "../state";
+import type { AuthPrompt } from "./auth";
+import type { CliAnalytics } from "./analytics";
+import type { checkProject } from "./check";
+import { PRODUCTION_BASE_URL, resolveTolokaConfig } from "./config";
+import type { TolokaEnvironment } from "./config";
+import { findCommandCredentials } from "./credentials";
+import type { StoredCredentials } from "./credentials";
+import { resolveProjectContext } from "./project-context";
+import { findSourceRoot } from "./source";
+import type { TrainingDraftOptions } from "./trainings";
+import type { RunOutcome } from "./runs";
+
+export type CliIo = {
+  readonly stdout: (text: string) => void;
+  readonly stderr: (text: string) => void;
+  readonly readStdin: () => Promise<string>;
+  readonly prompt?: AuthPrompt;
+  readonly select?: (choices: readonly { name: string; value: string }[]) => Promise<string>;
+};
+
+export type ProgramContext = {
+  readonly environment: TolokaEnvironment;
+  readonly io: CliIo;
+  readonly injectedClient?: PotatoClient;
+  readonly runChecks?: typeof checkProject;
+  readonly analytics?: CliAnalytics;
+};
+
+export type GlobalOptions = {
+  readonly sourceRoot?: string;
+  readonly apiKey?: string;
+  readonly baseUrl?: string;
+  readonly projectId?: string;
+};
+
+export type CreatedProgram = {
+  readonly program: Command;
+  readonly exitCode: { value: number };
+};
+
+export type Resolved = {
+  readonly sourceRoot: string;
+  readonly client: PotatoClient;
+  readonly baseUrl: string;
+  readonly state: TolokaState | undefined;
+  readonly stored: StoredCredentials | undefined;
+  readonly projectId?: string;
+};
+
+export const CREDENTIAL_PRECEDENCE = [
+  "Credentials resolve in this order, highest first:",
+  "  1. --api-key / --base-url",
+  "  2. TOLOKA_API_KEY / TOLOKA_BASE_URL",
+  "  3. the file written by toloka login",
+  `The platform defaults to ${PRODUCTION_BASE_URL}.`,
+].join("\n");
+
+export const authoredByOption = (raw: string): "human" | "agent" => {
+  if (raw !== "human" && raw !== "agent")
+    throw new InvalidArgumentError('Expected "human" or "agent".');
+  return raw;
+};
+
+export const positiveInteger = (raw: string): number => {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0)
+    throw new InvalidArgumentError("Expected a positive integer.");
+  return value;
+};
+
+export const nonNegativeInteger = (raw: string): number => {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0)
+    throw new InvalidArgumentError("Expected a non-negative integer.");
+  return value;
+};
+
+export const trainingMethod = (raw: string): "sft" | "gisting" => {
+  if (raw !== "sft" && raw !== "gisting") {
+    throw new InvalidArgumentError('Expected training method "sft" or "gisting".');
+  }
+  return raw;
+};
+
+export const trainingLoraRank = (raw: string): 8 | 16 | 32 => {
+  const value = Number(raw);
+  if (value !== 8 && value !== 16 && value !== 32) {
+    throw new InvalidArgumentError("Expected a LoRA rank of 8, 16, or 32.");
+  }
+  return value;
+};
+
+export const trainingGistTokens = (raw: string): 8 | 32 | 64 => {
+  const value = Number(raw);
+  if (value !== 8 && value !== 32 && value !== 64) {
+    throw new InvalidArgumentError("Expected 8, 32, or 64 gist tokens.");
+  }
+  return value;
+};
+
+export const trainingEpochs = (raw: string): number => {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1 || value > 5) {
+    throw new InvalidArgumentError("Expected epochs from 1 through 5.");
+  }
+  return value;
+};
+
+export const trainingLearningRate = (raw: string): number => {
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new InvalidArgumentError("Expected a positive learning rate, for example 0.00015.");
+  }
+  return value;
+};
+
+export const trainingBatchSize = (raw: string): 8 | 16 | 32 | 64 => {
+  const value = Number(raw);
+  if (value !== 8 && value !== 16 && value !== 32 && value !== 64) {
+    throw new InvalidArgumentError("Expected a batch size of 8, 16, 32, or 64.");
+  }
+  return value;
+};
+
+export const trainingMaxSequenceLength = (raw: string): number => {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 64 || value > 16384) {
+    throw new InvalidArgumentError("Expected a maximum sequence length from 64 through 16384 tokens.");
+  }
+  return value;
+};
+
+export type RawTrainingDraftOptions = {
+  method?: TrainingDraftOptions["method"];
+  baseModel?: TrainingDraftOptions["baseModelId"];
+  modelVersion?: string;
+  dataset?: string;
+  validationDataset?: string;
+  trainFilter?: string;
+  validationFilter?: string;
+  loraRank?: TrainingDraftOptions["loraRank"];
+  gistTokens?: TrainingDraftOptions["gistTokens"];
+  epochs?: number;
+  learningRate?: number;
+  batchSize?: TrainingDraftOptions["batchSize"];
+  maxSequenceLength?: number;
+  promptFile?: string;
+};
+
+export const trainingDraftOptions = (options: RawTrainingDraftOptions): TrainingDraftOptions => ({
+  method: options.method,
+  baseModelId: options.baseModel,
+  modelVersionId: options.modelVersion,
+  datasetId: options.dataset,
+  validationDatasetId: options.validationDataset,
+  trainingFilter: options.trainFilter,
+  validationFilter: options.validationFilter,
+  loraRank: options.loraRank,
+  gistTokens: options.gistTokens,
+  epochs: options.epochs,
+  learningRate: options.learningRate,
+  batchSize: options.batchSize,
+  maxSequenceLength: options.maxSequenceLength,
+  promptFilePath: options.promptFile,
+});
+
+export const exitCodeForOutcome = (outcome: RunOutcome): number => {
+  if (outcome === "failed") return 1;
+  if (outcome === "timedOut") return 2;
+  return 0;
+};
+
+export const resolveSourceRoot = async (globals: GlobalOptions, io: CliIo): Promise<string> => {
+  if (globals.sourceRoot !== undefined) return resolve(globals.sourceRoot);
+
+  const workingDirectory = process.cwd();
+  const discovered = await findSourceRoot(workingDirectory);
+  if (discovered === undefined || discovered === workingDirectory) return workingDirectory;
+
+  io.stderr(`Using project root ${discovered} (found from ${workingDirectory}).`);
+  return discovered;
+};
+
+export const resolveInitRoot = (globals: GlobalOptions): string =>
+  globals.sourceRoot === undefined ? process.cwd() : resolve(globals.sourceRoot);
+
+export const readCommandCredentials = async (globals: GlobalOptions, context: ProgramContext) => {
+  const { found, warning } = await findCommandCredentials(
+    context.environment,
+    globals.apiKey ?? context.environment.TOLOKA_API_KEY,
+  );
+  if (warning !== undefined) context.io.stderr(warning);
+  return found?.credentials;
+};
+
+export const identifyClientUser = async (
+  client: PotatoClient,
+  analytics: CliAnalytics | undefined,
+) => {
+  if (analytics?.shouldIdentify !== true) return;
+  try {
+    analytics.identifyCurrentUser(await client.me());
+  } catch {}
+};
+
+export const resolveContext = async (
+  globals: GlobalOptions,
+  context: ProgramContext,
+): Promise<Resolved> => {
+  const sourceRoot = await resolveSourceRoot(globals, context.io);
+  const state = await readTolokaState(sourceRoot);
+  const stored = await readCommandCredentials(globals, context);
+  const config = resolveTolokaConfig(globals, state, context.environment, stored);
+  const client =
+    context.injectedClient ?? createClient({ apiKey: config.apiKey, baseUrl: config.baseUrl });
+  await identifyClientUser(client, context.analytics);
+
+  return {
+    sourceRoot,
+    client,
+    baseUrl: config.baseUrl,
+    state,
+    stored,
+    ...(config.projectId === undefined ? {} : { projectId: config.projectId }),
+  };
+};
+
+export const resolveSelectedProject = (
+  globals: GlobalOptions,
+  context: ProgramContext,
+  stored: StoredCredentials | undefined,
+  state: TolokaState | undefined,
+) =>
+  resolveProjectContext({
+    flags: globals,
+    environment: context.environment,
+    stored,
+    ...(state === undefined ? {} : { state }),
+  });
+
+export type CommandHost = {
+  readonly context: ProgramContext;
+  readonly exitCode: { value: number };
+  readonly globals: () => GlobalOptions;
+};

package/src/cli/credentials.ts

@@ -1,7 +1,8 @@
-import { assert } from "es-toolkit";
 import { chmod, lstat, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { assertCli, TolokaCliError } from "./cli-error";
+import type { TolokaCliErrorOptions } from "./cli-error";
 
 export type StoredProjectAlias = {
   readonly id: string;
@@ -28,8 +29,8 @@ export type CommandCredentialLookup = {
   readonly warning?: string;
 };
 
-export class CredentialsError extends Error {
-  constructor(message: string, options?: { readonly cause?: unknown }) {
+export class CredentialsError extends TolokaCliError {
+  constructor(message: string, options: TolokaCliErrorOptions) {
     super(message, options);
     this.name = "CredentialsError";
   }
@@ -168,6 +169,7 @@ export async function findStoredCredentials(
     if (primary === "invalid") {
       throw new CredentialsError(
         `Invalid credentials file at ${path}. Run toloka logout, then toloka login.`,
+        { hint: { disabled: true } },
       );
     }
     return { credentials: primary.credentials, path, legacy: false };
@@ -181,6 +183,7 @@ export async function findStoredCredentials(
   if (legacy === "invalid") {
     throw new CredentialsError(
       `Invalid credentials file at ${legacyPath}. Run toloka logout, then toloka login.`,
+      { hint: { disabled: true } },
     );
   }
   return { credentials: legacy.credentials, path: legacyPath, legacy: true };
@@ -211,6 +214,7 @@ export async function requireStoredCredentials(
   if (found !== undefined) return found;
   throw new CredentialsError(
     `No stored credentials found at ${credentialsPath(environment)}. Run toloka login.`,
+    { hint: { disabled: true } },
   );
 }
 
@@ -228,7 +232,11 @@ const serializedCredentials = (credentials: StoredCredentials): StoredCredential
 const assertNotSymbolicLink = async (path: string): Promise<void> => {
   try {
     const entry = await lstat(path);
-    assert(!entry.isSymbolicLink(), `Refusing to write through symbolic link ${path}.`);
+    assertCli(
+      !entry.isSymbolicLink(),
+      `Refusing to write through symbolic link ${path}.`,
+      { hint: { description: "Replace the symbolic link with a regular file or directory, then retry." } },
+    );
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") return;
     throw error;

package/src/cli/data.ts

@@ -1,4 +1,3 @@
-import { assert } from "es-toolkit";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname } from "node:path";
 import type { Dataset, InferredField, PotatoClient, UploadId } from "../client";
@@ -7,18 +6,20 @@ import { generateFieldDeclarationsSource } from "../importer";
 import { readTolokaState } from "../state";
 import type { WaitForOptions } from "../wait-for";
 import { desiredDatasets } from "./project";
-import { MISSING_PROJECT_ID_MESSAGE } from "./project-context";
+import { assertProjectSelected } from "./project-context";
 import { loadProjectSource } from "./source";
 import type { ProjectSource } from "./source";
+import { assertCli, REPORT_HINT, RETRY_OR_REPORT_HINT, TolokaCliError } from "./cli-error";
+import type { TolokaCliErrorOptions } from "./cli-error";
 
 const RAW_UPLOAD_FIELD_NAME = "uploaded";
 const DATASET_ID_PATTERN =
   /^ds\.[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
 const FINALIZE_UPLOAD_ATTEMPTS = 3;
 
-class DatasetUploadError extends Error {
-  constructor(message: string, cause: unknown) {
-    super(message, { cause });
+class DatasetUploadError extends TolokaCliError {
+  constructor(message: string, options: TolokaCliErrorOptions) {
+    super(message, options);
     this.name = "DatasetUploadError";
   }
 }
@@ -171,7 +172,7 @@ const resolveLiveDataset = async (
 ): Promise<DatasetRef> => {
   const state = await readTolokaState(options.sourceRoot);
   const projectId = options.projectId ?? state?.projectId;
-  assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+  assertProjectSelected(projectId);
   const token = options.datasetName;
   const live = await collectLiveDatasets(client, projectId);
   const nameIsUnique = (name: string) =>
@@ -186,13 +187,14 @@ const resolveLiveDataset = async (
   }
 
   const byName = live.filter((dataset) => dataset.name === token);
-  assert(
+  assertCli(
     byName.length <= 1,
     `Project ${projectId} has multiple datasets named "${token}": ${byName.map(formatDatasetChoice).join(", ")}.`,
+    { hint: { description: "Pass the dataset id (ds.…) instead of the name." } },
   );
   if (byName.length === 1) {
     const [dataset] = byName;
-    assert(dataset, `Dataset "${token}" has no resolved ID.`);
+    assertCli(dataset, `Dataset "${token}" has no resolved ID.`, { hint: REPORT_HINT });
     return { datasetId: dataset.id, name: dataset.name, nameIsUnique: true };
   }
 
@@ -204,16 +206,18 @@ const resolveLiveDataset = async (
     }
   }
 
-  assert(
+  assertCli(
     createWhenMissing && datasetId === undefined,
     live.length === 0
-      ? `Dataset "${token}" does not exist in project ${projectId}. Run toloka apply first.`
+      ? `Dataset "${token}" does not exist in project ${projectId}. Run toloka dataset create ${JSON.stringify(token)} first, or toloka apply for a dataset a pipeline declares.`
       : `Dataset "${token}" does not exist in project ${projectId}. This project has: ${live.map(formatDatasetChoice).join(", ")}.`,
+    { hint: { disabled: true } },
   );
 
-  assert(
+  assertCli(
     (await declaredDatasetFields(options)).length > 0,
-    `Dataset "${token}" does not exist in project ${projectId} and no pipeline in source declares it. Bind a pipeline to it in source so its columns are known, or upload to an existing dataset.`,
+    `Dataset "${token}" does not exist in project ${projectId} and no pipeline in source declares it. Run toloka dataset create ${JSON.stringify(token)} to create it empty, bind a pipeline to it in source so its columns are known, or upload to an existing dataset.`,
+    { hint: { disabled: true } },
   );
   const created = await client.datasets.create({ projectId, name: token });
   return { datasetId: created.id, name: created.name, nameIsUnique: true };
@@ -226,7 +230,11 @@ const resolveDatasetUploadFormat = (filename: string): DatasetUploadFormat => {
   if (normalizedFilename.endsWith(".jsonl")) return "jsonl";
   if (normalizedFilename.endsWith(".csv")) return "csv";
 
-  assert(false, `${filename} must have a .json, .jsonl, or .csv extension`);
+  assertCli(
+    false,
+    `${filename} must have a .json, .jsonl, or .csv extension`,
+    { hint: { description: "Rename the file with the extension that matches its format." } },
+  );
 };
 
 const readDatasetUpload = async (filePath: string) => {
@@ -243,9 +251,17 @@ const readDatasetUpload = async (filePath: string) => {
       try {
         value = JSON.parse(line);
       } catch {
-        assert(false, `${filename}:${lineNumber} is not valid JSON`);
+        assertCli(
+          false,
+          `${filename}:${lineNumber} is not valid JSON`,
+          { hint: { description: "Fix the JSON on that line; every line of a JSONL file must be one complete object." } },
+        );
       }
-      assert(isJsonObject(value), `${filename}:${lineNumber} must contain a JSON object`);
+      assertCli(
+        isJsonObject(value),
+        `${filename}:${lineNumber} must contain a JSON object`,
+        { hint: { description: "Wrap the value in an object with named fields, one object per line." } },
+      );
     }
   }
 
@@ -265,16 +281,22 @@ const cancelStartedUpload = async (
     await client.datasets.cancelUpload({ uploadId });
   } catch (cancelError) {
     const cancelReason = cancelError instanceof Error ? cancelError.message : String(cancelError);
-    throw new AggregateError(
-      [error, cancelError],
+    throw new DatasetUploadError(
       `Dataset upload ${uploadId} failed and could not be canceled. Upload error: ${reason}. Cancellation error: ${cancelReason}.`,
+      {
+        cause: new AggregateError([error, cancelError]),
+        hint: {
+          description:
+            "Check toloka dataset list before re-running toloka dataset upload; an upload that never finalized is cleaned up automatically.",
+        },
+      },
     );
   }
 
-  throw new DatasetUploadError(
-    `Dataset upload ${uploadId} failed and was canceled: ${reason}`,
-    error,
-  );
+  throw new DatasetUploadError(`Dataset upload ${uploadId} failed and was canceled: ${reason}`, {
+    cause: error,
+    hint: { description: "Fix the upload error above, then re-run toloka dataset upload." },
+  });
 };
 
 const transferAndFinalizeUpload = async ({
@@ -310,10 +332,9 @@ const transferAndFinalizeUpload = async ({
     return cancelStartedUpload(
       client,
       started.job.id,
-      new DatasetUploadError(
-        `Dataset upload failed with HTTP ${uploadResponse.status}.`,
-        undefined,
-      ),
+      new DatasetUploadError(`Dataset upload failed with HTTP ${uploadResponse.status}.`, {
+        hint: RETRY_OR_REPORT_HINT,
+      }),
     );
   }
 
@@ -334,7 +355,7 @@ const transferAndFinalizeUpload = async ({
           started.job.id,
           new DatasetUploadError(
             `Storage remained unavailable after ${FINALIZE_UPLOAD_ATTEMPTS} finalization attempts.`,
-            error,
+            { cause: error, hint: RETRY_OR_REPORT_HINT },
           ),
         );
       }
@@ -346,6 +367,28 @@ const transferAndFinalizeUpload = async ({
   }
 };
 
+export type CreateDatasetResult = {
+  readonly datasetId: string;
+  readonly output: string;
+};
+
+export async function createDataset(
+  client: Pick<PotatoClient, "datasets">,
+  options: { readonly projectId: string; readonly name: string },
+): Promise<CreateDatasetResult> {
+  const name = options.name.trim();
+  assertCli(
+    name.length > 0,
+    "Dataset name cannot be empty.",
+    { hint: { description: "Pass a non-empty dataset name." } },
+  );
+  const created = await client.datasets.create({ projectId: options.projectId, name });
+  return {
+    datasetId: created.id,
+    output: `Created dataset ${created.name} (${created.id}). Upload rows with toloka dataset upload ${created.id} <file>.`,
+  };
+}
+
 export async function uploadDataset(
   client: PotatoClient,
   options: UploadDatasetOptions,
@@ -388,9 +431,10 @@ export async function uploadDataset(
     completed.error?.startsWith("Schema incompatible with existing upload") === true
       ? `\nRun toloka dataset fields ${JSON.stringify(fieldsHint)} to inspect the inferred schema stored from the first successful upload.`
       : "";
-  assert(
+  assertCli(
     completed.status === "succeeded",
     `${completed.error ?? `Dataset upload ${completed.id} failed.`}${compatibilityHint}`,
+    { hint: { disabled: true } },
   );
 
   const uploadedOutput = `Uploaded ${completed.result.itemsIngested} rows to dataset ${resolved.name}.`;
@@ -455,20 +499,32 @@ const downloadExportRows = async (options: {
   readonly fetch: typeof globalThis.fetch;
 }): Promise<Record<string, unknown>[]> => {
   const download = await options.fetch(options.downloadUrl);
-  assert(download.ok, `Dataset export download failed with HTTP ${download.status}.`);
+  assertCli(
+    download.ok,
+    `Dataset export download failed with HTTP ${download.status}.`,
+    { hint: RETRY_OR_REPORT_HINT },
+  );
   const text = await download.text();
   let parsed: unknown;
   try {
     parsed = JSON.parse(text);
   } catch (error) {
-    throw new Error(`Dataset export ${options.exportId} is not valid JSON.`, { cause: error });
+    throw new TolokaCliError(`Dataset export ${options.exportId} is not valid JSON.`, {
+      cause: error,
+      hint: REPORT_HINT,
+    });
   }
-  assert(Array.isArray(parsed), `Dataset export ${options.exportId} is not a JSON array.`);
+  assertCli(
+    Array.isArray(parsed),
+    `Dataset export ${options.exportId} is not a JSON array.`,
+    { hint: REPORT_HINT },
+  );
   const rows: Record<string, unknown>[] = [];
   for (const [index, element] of parsed.entries()) {
-    assert(
+    assertCli(
       isJsonObject(element),
       `Dataset export ${options.exportId} row ${index} is not a JSON object.`,
+      { hint: REPORT_HINT },
     );
     rows.push(element);
   }
@@ -485,7 +541,11 @@ export async function loadDataset(
     if (field.internal || field.name === RAW_UPLOAD_FIELD_NAME) continue;
     fieldNames.push(field.name);
   }
-  assert(fieldNames.length > 0, `Dataset ${resolved.name} has no fields to export.`);
+  assertCli(
+    fieldNames.length > 0,
+    `Dataset ${resolved.name} has no fields to export.`,
+    { hint: { description: "Upload rows first with toloka dataset upload <name> <file>." } },
+  );
 
   const started = await client.datasets.startExport({
     datasetId: resolved.datasetId,
@@ -498,16 +558,18 @@ export async function loadDataset(
       options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs },
     );
   } catch (error) {
-    assert(
+    assertCli(
       !(error instanceof PotatoApiError && error.code === "wait_timeout"),
       `Stopped waiting for dataset export ${started.id}; raise --timeout to wait longer.`,
+      { hint: { disabled: true } },
     );
     throw error;
   }
 
-  assert(
+  assertCli(
     completed.result.downloadUrl,
     `Dataset export ${completed.id} succeeded without a download URL.`,
+    { hint: REPORT_HINT },
   );
 
   const rows = await downloadExportRows({

package/src/cli/delivery-orders.ts

@@ -0,0 +1,47 @@
+import { PotatoApiError } from "../errors";
+import { TolokaCliError } from "./cli-error";
+
+export type DeliveryOrderRecord = {
+  readonly id: string;
+  readonly name: string;
+  readonly mondayId: string;
+  readonly status: string;
+  readonly clientName: string | null;
+};
+
+export type DeliveryOrderListApi = {
+  readonly deliveryOrders: {
+    readonly list: () => Promise<readonly DeliveryOrderRecord[]>;
+  };
+};
+
+export async function listDeliveryOrders(options: {
+  readonly client: DeliveryOrderListApi;
+}): Promise<{ readonly output: string }> {
+  let orders: readonly DeliveryOrderRecord[];
+  try {
+    orders = await options.client.deliveryOrders.list();
+  } catch (error) {
+    if (error instanceof PotatoApiError && error.status === 403) {
+      throw new TolokaCliError("Delivery orders are available to internal teams only.", {
+        cause: error,
+        hint: {
+          description:
+            "Run toloka whoami; when it prints Internal: false, create the project without --delivery-order-id.",
+        },
+      });
+    }
+    throw error;
+  }
+  if (orders.length === 0) {
+    return { output: "No delivery orders visible." };
+  }
+  return {
+    output: [
+      "ID\tNAME\tSTATUS\tCLIENT",
+      ...orders.map(
+        (order) => `${order.id}\t${order.name}\t${order.status}\t${order.clientName ?? "-"}`,
+      ),
+    ].join("\n"),
+  };
+}

package/src/cli/environment.ts

@@ -0,0 +1,26 @@
+import type { TolokaEnvironment } from "./config";
+
+const LEGACY_ENVIRONMENT_NAMES: Readonly<Record<string, string>> = {
+  POTATO_API_KEY: "TOLOKA_API_KEY",
+  POTATO_BASE_URL: "TOLOKA_BASE_URL",
+  POTATO_PROJECT_ID: "TOLOKA_PROJECT_ID",
+};
+
+export const API_KEY_ENVIRONMENT_NAMES = ["TOLOKA_API_KEY", "POTATO_API_KEY"];
+
+export type NormalizedEnvironment = {
+  readonly environment: TolokaEnvironment;
+  readonly warnings: readonly string[];
+};
+
+export const normalizeEnvironment = (environment: TolokaEnvironment): NormalizedEnvironment => {
+  const normalized: Record<string, string | undefined> = { ...environment };
+  const warnings: string[] = [];
+  for (const [legacy, current] of Object.entries(LEGACY_ENVIRONMENT_NAMES)) {
+    const value = environment[legacy];
+    if (value === undefined) continue;
+    normalized[current] ??= value;
+    warnings.push(`${legacy} is deprecated and will stop being read; set ${current} instead.`);
+  }
+  return { environment: normalized, warnings };
+};

package/src/cli/file-system.ts

@@ -1,6 +1,6 @@
-import { assert } from "es-toolkit";
 import { lstat } from "node:fs/promises";
 import { join } from "node:path";
+import { assertCli } from "./cli-error";
 
 export const hasErrorCode = (error: unknown, ...codes: readonly string[]) =>
   error instanceof Error &&
@@ -29,6 +29,10 @@ export const assertSafeDestination = async (
     currentPath = join(currentPath, segment);
     const entry = await entryStats(currentPath);
     if (entry === undefined) return;
-    assert(!entry.isSymbolicLink(), `Refusing to ${action} through symbolic link ${currentPath}.`);
+    assertCli(
+      !entry.isSymbolicLink(),
+      `Refusing to ${action} through symbolic link ${currentPath}.`,
+      { hint: { description: "Replace the symbolic link with a regular directory, or point the command at the real path." } },
+    );
   }
 };