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

package/src/cli/context.ts

@@ -0,0 +1,213 @@
+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;
+  readonly internalUser?: boolean;
+};
+
+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 trainingRegime = (raw: string): "low" | "medium" | "high" => {
+  if (raw !== "low" && raw !== "medium" && raw !== "high") {
+    throw new InvalidArgumentError('Expected regime "low", "medium", or "high".');
+  }
+  return raw;
+};
+
+export type RawTrainingDraftOptions = {
+  method?: TrainingDraftOptions["method"];
+  baseModel?: TrainingDraftOptions["baseModelId"];
+  modelVersion?: string;
+  dataset?: string;
+  validationDataset?: string;
+  trainFilter?: string;
+  validationFilter?: string;
+  regime?: TrainingDraftOptions["regime"];
+  epochs?: number;
+  evalSteps?: 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,
+  regime: options.regime,
+  epochs: options.epochs,
+  evalSteps: options.evalSteps,
+  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 resolveInternalUser = async (client: PotatoClient): Promise<boolean | undefined> => {
+  try {
+    return (await client.me()).internal;
+  } catch {
+    return undefined;
+  }
+};
+
+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/delivery-orders.ts

@@ -0,0 +1,30 @@
+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 }> {
+  const orders = await options.client.deliveryOrders.list();
+  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/init.ts

@@ -1,14 +1,11 @@
 import { assert } from "es-toolkit";
 import { lstat, mkdir, readdir, readFile, realpath, rm, rmdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import packageMetadata from "../../package.json" with { type: "json" };
 import { readTolokaState, writeTolokaState } from "../state";
 import { assertSafeDestination, entryStats, isMissingFileError } from "./file-system";
+import { SDK_PACKAGE_NAME, SDK_VERSION } from "./sdk-version";
 import { SKILL_ENTRY_POINT, SKILL_INSTALL_ROOT } from "./skill";
 
-export const SDK_VERSION = packageMetadata.version;
-
-const SDK_PACKAGE_NAME = "@toloka-platform/sdk";
 const BOOTSTRAP_NAME = "toloka-bootstrap";
 const CLAUDE_POINTER_PATH = `.claude/skills/${BOOTSTRAP_NAME}/SKILL.md`;
 const CURSOR_POINTER_PATH = `.cursor/rules/${BOOTSTRAP_NAME}.mdc`;