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

package/src/cli/check.ts

@@ -6,7 +6,6 @@ import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 
-import { assert } from "es-toolkit";
 import {
   createBundledTaskUiTypechecker,
   findPostprocessKeyCollisions,
@@ -25,7 +24,10 @@ import {
   type TestEvidenceKind,
 } from "../testing/test-evidence";
 import { resolveCliEntry } from "./cli-entry";
+import { API_KEY_ENVIRONMENT_NAMES } from "./environment";
 import { loadProjectSource, type ProjectSource } from "./source";
+import { assertCli, REPORT_HINT, TolokaCliError } from "./cli-error";
+import type { TolokaCliErrorOptions } from "./cli-error";
 
 export type CheckStatus = "passed" | "failed" | "missing" | "partial" | "infrastructure_error";
 export type CheckKind =
@@ -117,10 +119,10 @@ export type CheckProjectResult = {
 
 export type FreshCheckFailurePhase = "spawn" | "execute" | "read_result" | "parse_result";
 
-export class FreshCheckProcessError extends Error {
+export class FreshCheckProcessError extends TolokaCliError {
   readonly phase: FreshCheckFailurePhase;
 
-  constructor(phase: FreshCheckFailurePhase, message: string, options?: ErrorOptions) {
+  constructor(phase: FreshCheckFailurePhase, message: string, options: TolokaCliErrorOptions) {
     super(message, options);
     this.name = "FreshCheckProcessError";
     this.phase = phase;
@@ -269,18 +271,19 @@ const loadSourceWithoutPlatformCredentials = async (
   sourceRoot: string,
   environment: NodeJS.ProcessEnv,
 ): Promise<ProjectSource> => {
-  const environments = new Map<NodeJS.ProcessEnv, string | undefined>([
-    [process.env, process.env.POTATO_API_KEY],
-    [environment, environment.POTATO_API_KEY],
-  ]);
-  for (const current of environments.keys()) delete current.POTATO_API_KEY;
+  const targets = [process.env, environment];
+  const saved = targets.map((current) => API_KEY_ENVIRONMENT_NAMES.map((name) => current[name]));
+  for (const current of targets) for (const name of API_KEY_ENVIRONMENT_NAMES) delete current[name];
   try {
     return await loadProjectSource(sourceRoot);
   } finally {
-    for (const [current, apiKey] of environments) {
-      if (apiKey === undefined) delete current.POTATO_API_KEY;
-      else current.POTATO_API_KEY = apiKey;
-    }
+    targets.forEach((current, target) => {
+      API_KEY_ENVIRONMENT_NAMES.forEach((name, index) => {
+        const value = saved[target]?.[index];
+        if (value === undefined) delete current[name];
+        else current[name] = value;
+      });
+    });
   }
 };
 
@@ -356,13 +359,15 @@ const filterInventory = (
             pipeline.sourceDirectory.split("/").at(-1) === pipelineSelector,
         );
   if (pipelineSelector !== undefined) {
-    assert(
+    assertCli(
       pipelines.length > 0,
       `Unknown pipeline ${JSON.stringify(pipelineSelector)}. Available: ${inventory.map((item) => item.sourceDirectory).join(", ")}`,
+      { hint: { description: "Pass one of the listed source directories." } },
     );
-    assert(
+    assertCli(
       pipelines.length === 1,
       `Pipeline selector ${JSON.stringify(pipelineSelector)} is ambiguous: ${pipelines.map((item) => item.sourceDirectory).join(", ")}`,
+      { hint: { description: "Pass the full source directory of the pipeline you mean." } },
     );
   }
   if (nodeSelector === undefined) return { pipelines };
@@ -371,11 +376,12 @@ const filterInventory = (
       .filter((node) => node.id === nodeSelector || node.name === nodeSelector)
       .map((node) => ({ pipeline, node })),
   );
-  assert(
+  assertCli(
     matches.length === 1,
     matches.length === 0
       ? `Unknown checkable node ${JSON.stringify(nodeSelector)}.`
       : `Node selector ${JSON.stringify(nodeSelector)} is ambiguous across pipelines.`,
+    { hint: { description: "Pass the pipeline selector together with the node id." } },
   );
   return { pipelines: [matches[0]!.pipeline], nodeId: matches[0]!.node.id };
 };
@@ -683,7 +689,7 @@ export async function checkProject(
   try {
     const selectedPipeline = selected.pipelines.length === 1 ? selected.pipelines[0] : undefined;
     const checkEnvironment = { ...(options.environment ?? process.env) };
-    delete checkEnvironment.POTATO_API_KEY;
+    for (const name of API_KEY_ENVIRONMENT_NAMES) delete checkEnvironment[name];
     const environment = {
       ...checkEnvironment,
       [TEST_EVIDENCE_DIR_ENV]: evidenceDirectory,
@@ -787,28 +793,47 @@ const isCheckStatus = (value: unknown): value is CheckStatus =>
   value === "infrastructure_error";
 
 const parseFreshCheckDiagnostic = (value: unknown): CheckDiagnostic => {
-  assert(typeof value === "object" && value !== null, "Fresh check returned invalid diagnostics");
+  assertCli(
+    typeof value === "object" && value !== null,
+    "Fresh check returned invalid diagnostics",
+    { hint: REPORT_HINT },
+  );
   const message = Reflect.get(value, "message");
   const severity = Reflect.get(value, "severity");
   const setting = Reflect.get(value, "setting");
   const line = Reflect.get(value, "line");
   const column = Reflect.get(value, "column");
   const code = Reflect.get(value, "code");
-  assert(typeof message === "string", "Fresh check diagnostic has no message");
-  assert(
+  assertCli(
+    typeof message === "string",
+    "Fresh check diagnostic has no message",
+    { hint: REPORT_HINT },
+  );
+  assertCli(
     severity === undefined || severity === "error" || severity === "warning",
     "Fresh check diagnostic has invalid severity",
+    { hint: REPORT_HINT },
   );
-  assert(
+  assertCli(
     setting === undefined || typeof setting === "string",
     "Fresh check diagnostic has invalid setting",
+    { hint: REPORT_HINT },
+  );
+  assertCli(
+    line === undefined || Number.isInteger(line),
+    "Fresh check diagnostic has invalid line",
+    { hint: REPORT_HINT },
   );
-  assert(line === undefined || Number.isInteger(line), "Fresh check diagnostic has invalid line");
-  assert(
+  assertCli(
     column === undefined || Number.isInteger(column),
     "Fresh check diagnostic has invalid column",
+    { hint: REPORT_HINT },
+  );
+  assertCli(
+    code === undefined || typeof code === "string",
+    "Fresh check diagnostic has invalid code",
+    { hint: REPORT_HINT },
   );
-  assert(code === undefined || typeof code === "string", "Fresh check diagnostic has invalid code");
   return {
     message,
     ...(severity === undefined ? {} : { severity }),
@@ -820,7 +845,11 @@ const parseFreshCheckDiagnostic = (value: unknown): CheckDiagnostic => {
 };
 
 const parseFreshCheckResultItem = (value: unknown): CheckResult => {
-  assert(typeof value === "object" && value !== null, "Fresh check returned an invalid result");
+  assertCli(
+    typeof value === "object" && value !== null,
+    "Fresh check returned an invalid result",
+    { hint: REPORT_HINT },
+  );
   const scope = Reflect.get(value, "scope");
   const kind = Reflect.get(value, "kind");
   const status = Reflect.get(value, "status");
@@ -829,25 +858,33 @@ const parseFreshCheckResultItem = (value: unknown): CheckResult => {
   const pipeline = Reflect.get(value, "pipelineFingerprint");
   const nodeId = Reflect.get(value, "nodeId");
   const truncated = Reflect.get(value, "truncatedDiagnosticCount");
-  assert(isCheckScope(scope), "Fresh check returned an invalid scope");
-  assert(isCheckKind(kind), "Fresh check returned an invalid kind");
-  assert(isCheckStatus(status), "Fresh check returned an invalid status");
-  assert(Array.isArray(diagnostics), "Fresh check returned invalid diagnostics");
-  assert(
+  assertCli(isCheckScope(scope), "Fresh check returned an invalid scope", { hint: REPORT_HINT });
+  assertCli(isCheckKind(kind), "Fresh check returned an invalid kind", { hint: REPORT_HINT });
+  assertCli(isCheckStatus(status), "Fresh check returned an invalid status", { hint: REPORT_HINT });
+  assertCli(
+    Array.isArray(diagnostics),
+    "Fresh check returned invalid diagnostics",
+    { hint: REPORT_HINT },
+  );
+  assertCli(
     sourceDirectory === undefined || typeof sourceDirectory === "string",
     "Fresh check returned an invalid source directory",
+    { hint: REPORT_HINT },
   );
-  assert(
+  assertCli(
     pipeline === undefined || typeof pipeline === "string",
     "Fresh check returned an invalid pipeline fingerprint",
+    { hint: REPORT_HINT },
   );
-  assert(
+  assertCli(
     nodeId === undefined || typeof nodeId === "string",
     "Fresh check returned an invalid node id",
+    { hint: REPORT_HINT },
   );
-  assert(
+  assertCli(
     truncated === undefined || (Number.isInteger(truncated) && Number(truncated) >= 0),
     "Fresh check returned an invalid truncated count",
+    { hint: REPORT_HINT },
   );
   return {
     scope,
@@ -862,14 +899,19 @@ const parseFreshCheckResultItem = (value: unknown): CheckResult => {
 };
 
 const parseFreshCheckResult = (value: unknown, json: boolean): CheckProjectResult => {
-  assert(typeof value === "object" && value !== null, "Fresh check returned invalid JSON");
+  assertCli(
+    typeof value === "object" && value !== null,
+    "Fresh check returned invalid JSON",
+    { hint: REPORT_HINT },
+  );
   const exitCode = Reflect.get(value, "exitCode");
   const rawResults = Reflect.get(value, "results");
-  assert(
+  assertCli(
     exitCode === 0 || exitCode === 1 || exitCode === 2,
     "Fresh check returned an invalid exit code",
+    { hint: REPORT_HINT },
   );
-  assert(Array.isArray(rawResults), "Fresh check returned no results");
+  assertCli(Array.isArray(rawResults), "Fresh check returned no results", { hint: REPORT_HINT });
   const results = rawResults.map(parseFreshCheckResultItem);
   return {
     exitCode,
@@ -897,13 +939,16 @@ export const readFreshCheckResult = async (
         output.length === 0
           ? `Local check process exited ${run.exitCode} before producing results`
           : `Local check process failed before producing results:\n${output}`,
-        { cause: error },
+        {
+          cause: error,
+          hint: { description: "Fix the errors printed above, then re-run toloka check." },
+        },
       );
     }
     throw new FreshCheckProcessError(
       "read_result",
       "Local check process completed without producing a result file",
-      { cause: error },
+      { cause: error, hint: REPORT_HINT },
     );
   }
 
@@ -913,6 +958,7 @@ export const readFreshCheckResult = async (
   } catch (error) {
     throw new FreshCheckProcessError("parse_result", "Local check process returned invalid JSON", {
       cause: error,
+      hint: REPORT_HINT,
     });
   }
 
@@ -922,7 +968,7 @@ export const readFreshCheckResult = async (
     throw new FreshCheckProcessError(
       "parse_result",
       `Local check process returned an invalid result: ${error instanceof Error ? error.message : String(error)}`,
-      { cause: error },
+      { cause: error, hint: REPORT_HINT },
     );
   }
 };
@@ -956,7 +1002,10 @@ export const runFreshCheck = async (options: CheckProjectOptions): Promise<Check
       throw new FreshCheckProcessError(
         "spawn",
         `Unable to start the local check process: ${error instanceof Error ? error.message : String(error)}`,
-        { cause: error },
+        {
+          cause: error,
+          hint: { description: "Check that bun is installed and on PATH, then re-run toloka check." },
+        },
       );
     }
     return await readFreshCheckResult(

package/src/cli/cli-entry.ts

@@ -1,6 +1,6 @@
-import { assert } from "es-toolkit";
 import { existsSync, realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { assertCli } from "./cli-error";
 
 const CLI_ENTRY = join("bin", "toloka.js");
 
@@ -33,9 +33,10 @@ export const resolveCliEntry = (runtimeEntry: string | undefined = process.argv[
     return entry;
   }
   const workingDirectoryEntry = findCliEntryAbove(process.cwd());
-  assert(
+  assertCli(
     workingDirectoryEntry !== undefined,
     `Cannot locate the toloka CLI entry point. An installed @toloka-platform/sdk ships ${CLI_ENTRY} in a directory above its runtime entry, but none exists above ${runtimeEntry ?? "the unset process.argv[1]"} or above ${process.cwd()}. Reinstall @toloka-platform/sdk.`,
+    { hint: { disabled: true } },
   );
   return workingDirectoryEntry;
 };

package/src/cli/cli-error.ts

@@ -0,0 +1,43 @@
+export type CliErrorHint =
+  | { readonly description: string; readonly disabled?: never }
+  | { readonly disabled: true; readonly description?: never };
+
+export type TolokaCliErrorOptions = {
+  readonly hint: CliErrorHint;
+  readonly cause?: unknown;
+};
+
+export class TolokaCliError extends Error {
+  readonly hint: CliErrorHint;
+
+  constructor(message: string, options: TolokaCliErrorOptions) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "TolokaCliError";
+    this.hint = options.hint;
+  }
+}
+
+export function assertCli(
+  condition: unknown,
+  message: string,
+  options: TolokaCliErrorOptions,
+): asserts condition {
+  if (!condition) throw new TolokaCliError(message, options);
+}
+
+export const formatHint = (hint: CliErrorHint): string | undefined =>
+  "disabled" in hint ? undefined : `Hint: ${hint.description}`;
+
+export const REPORT_HINT: CliErrorHint = {
+  description:
+    "This looks like a defect in the CLI or the platform. Write a report as the toloka-report-issue skill describes, then send it with toloka report <report.md>.",
+};
+
+export const RETRY_OR_REPORT_HINT: CliErrorHint = {
+  description:
+    "Retry the command; if it keeps failing, write a report as the toloka-report-issue skill describes and send it with toloka report <report.md>.",
+};
+
+export const REINSTALL_HINT: CliErrorHint = {
+  description: "Reinstall @toloka-platform/sdk to restore the bundled files.",
+};

package/src/cli/commands/auth.ts

@@ -0,0 +1,89 @@
+import type { Command } from "commander";
+import { createClient } from "../../client";
+import { authStatus, login, logout } from "../auth";
+import {
+  identifyClientUser,
+  resolveSelectedProject,
+  resolveSourceRoot,
+  type CommandHost,
+} from "../context";
+import { findCommandCredentials, readStoredCredentials } from "../credentials";
+import { resolveTolokaConfig } from "../config";
+import { readTolokaState } from "../../state";
+
+export const registerAuthCommands = (program: Command, host: CommandHost): void => {
+  const { context, exitCode, globals } = host;
+
+  program
+    .command("login")
+    .description("store an API key for this machine after verifying it")
+    .option("--api-key-stdin", "read the API key from standard input instead of prompting", false)
+    .action(async (options: { apiKeyStdin: boolean }) => {
+      const apiKey = options.apiKeyStdin ? (await context.io.readStdin()).trim() : globals().apiKey;
+      const injectedClient = context.injectedClient;
+      const result = await login({
+        ...(apiKey === undefined ? {} : { apiKey }),
+        ...(globals().baseUrl === undefined ? {} : { baseUrl: globals().baseUrl }),
+        ...(context.io.prompt === undefined ? {} : { prompt: context.io.prompt }),
+        ...(injectedClient === undefined ? {} : { probe: () => injectedClient }),
+        write: context.io.stdout,
+        environment: context.environment,
+      });
+      context.io.stdout(result.output);
+      try {
+        const stored = await readStoredCredentials(context.environment);
+        if (stored === undefined) return;
+        const client = context.injectedClient ?? createClient(stored);
+        await identifyClientUser(client, context.analytics);
+      } catch {}
+    });
+
+  program
+    .command("logout")
+    .description("remove stored credentials from this machine")
+    .action(async () => {
+      const result = await logout(context.environment);
+      context.io.stdout(result.output);
+    });
+
+  program
+    .command("auth-status")
+    .alias("whoami")
+    .description("show which platform and key the CLI would use")
+    .option("--show-token", "print the API key instead of masking it", false)
+    .action(async (options: { showToken: boolean }) => {
+      const flags = globals();
+      const credentialLookup = await findCommandCredentials(
+        context.environment,
+        flags.apiKey ?? context.environment.TOLOKA_API_KEY,
+      );
+      const stored = credentialLookup.found?.credentials;
+      const sourceRoot = await resolveSourceRoot(flags, context.io);
+      const state = await readTolokaState(sourceRoot);
+      const project = resolveSelectedProject(flags, context, stored, state);
+      const injectedClient = context.injectedClient;
+
+      const result = await authStatus({
+        environment: context.environment,
+        showToken: options.showToken,
+        credentialLookup,
+        ...(flags.apiKey === undefined ? {} : { flagApiKey: flags.apiKey }),
+        ...(flags.baseUrl === undefined ? {} : { flagBaseUrl: flags.baseUrl }),
+        ...(injectedClient === undefined ? {} : { probe: () => injectedClient }),
+        ...(project === undefined ? {} : { project }),
+      });
+
+      context.io.stdout(result.output);
+      if (!result.authenticated) {
+        exitCode.value = 1;
+        return;
+      }
+      try {
+        const config = resolveTolokaConfig(flags, state, context.environment, stored);
+        const client =
+          context.injectedClient ??
+          createClient({ apiKey: config.apiKey, baseUrl: config.baseUrl });
+        await identifyClientUser(client, context.analytics);
+      } catch {}
+    });
+};

package/src/cli/commands/config.ts

@@ -0,0 +1,28 @@
+import type { Command } from "commander";
+import type { CommandHost } from "../context";
+import { getCliSetting, readCliSettings, setCliSetting } from "../settings";
+
+export const registerConfigCommands = (program: Command, host: CommandHost): void => {
+  const config = program.command("config").description("read and write machine CLI settings");
+  config
+    .command("get")
+    .argument("[name]", "setting name; omit to print every setting")
+    .description("print a CLI setting, or every setting")
+    .action(async (name?: string) => {
+      const settings = await readCliSettings(host.context.environment);
+      host.context.io.stdout(getCliSetting(settings, name).output);
+    });
+  config
+    .command("set")
+    .argument("<name>", "setting name")
+    .argument("<value>", "setting value")
+    .description("write a CLI setting for this machine")
+    .action(async (name: string, value: string) => {
+      const result = await setCliSetting(host.context.environment, name, value);
+      host.context.io.stdout(result.output);
+    });
+  config.action(async () => {
+    const settings = await readCliSettings(host.context.environment);
+    host.context.io.stdout(getCliSetting(settings, undefined).output);
+  });
+};

package/src/cli/commands/dataset.ts

@@ -0,0 +1,85 @@
+import { resolve } from "node:path";
+import type { Command } from "commander";
+import { positiveInteger, resolveContext, type CommandHost } from "../context";
+import {
+  createDataset,
+  generateDatasetFieldDeclarations,
+  listProjectDatasets,
+  loadDataset,
+  uploadDataset,
+} from "../data";
+import { assertProjectSelected } from "../project-context";
+
+export const registerDatasetCommands = (program: Command, host: CommandHost): void => {
+  const { context, globals } = host;
+  const dataset = program
+    .command("dataset")
+    .description("inspect and move dataset catalog and rows");
+  dataset
+    .command("list")
+    .description("list live datasets in the selected project")
+    .action(async () => {
+      const { client, projectId } = await resolveContext(globals(), context);
+      assertProjectSelected(projectId);
+      const result = await listProjectDatasets(client, { projectId });
+      context.io.stdout(result.output);
+    });
+  dataset
+    .command("create")
+    .argument("<name>", "dataset name")
+    .description("create an empty dataset in the selected project")
+    .action(async (name: string) => {
+      const { client, projectId } = await resolveContext(globals(), context);
+      assertProjectSelected(projectId);
+      const result = await createDataset(client, { projectId, name });
+      context.io.stdout(result.output);
+    });
+  dataset
+    .command("fields")
+    .argument("<name>", "dataset name or id")
+    .description("print field declarations inferred from uploaded rows")
+    .action(async (name: string) => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await generateDatasetFieldDeclarations(client, {
+        sourceRoot,
+        datasetName: name,
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+      context.io.stdout(result.output);
+    });
+  dataset
+    .command("load")
+    .argument("<name>", "dataset name or id")
+    .requiredOption("--out <file>", "JSONL file to write")
+    .option("--limit <n>", "how many rows to keep after download", positiveInteger)
+    .option("--timeout <ms>", "how long to wait for the export", positiveInteger)
+    .description("download live dataset rows into a JSONL file")
+    .action(async (name: string, options: { out: string; limit?: number; timeout?: number }) => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await loadDataset(client, {
+        sourceRoot,
+        datasetName: name,
+        outPath: resolve(options.out),
+        ...(projectId === undefined ? {} : { projectId }),
+        ...(options.limit === undefined ? {} : { limit: options.limit }),
+        ...(options.timeout === undefined ? {} : { timeoutMs: options.timeout }),
+      });
+      context.io.stdout(result.output);
+    });
+  dataset
+    .command("upload")
+    .argument("<name>", "dataset name or id")
+    .argument("<file>", "JSON array, JSONL, or CSV file")
+    .description("append rows to a dataset")
+    .action(async (name: string, file: string) => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await uploadDataset(client, {
+        sourceRoot,
+        datasetName: name,
+        filePath: resolve(file),
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+      context.io.stdout(result.output);
+      if (result.warning !== undefined) context.io.stderr(result.warning);
+    });
+};

package/src/cli/commands/delivery-order.ts

@@ -0,0 +1,18 @@
+import type { Command } from "commander";
+import { resolveContext, type CommandHost } from "../context";
+import { listDeliveryOrders } from "../delivery-orders";
+
+export const registerDeliveryOrderCommands = (program: Command, host: CommandHost): void => {
+  const { context, globals } = host;
+  const deliveryOrder = program
+    .command("delivery-order")
+    .description("list Sunday delivery orders for project create");
+  deliveryOrder
+    .command("list")
+    .description("list active Sunday delivery orders this key can attach")
+    .action(async () => {
+      const { client } = await resolveContext(globals(), context);
+      const result = await listDeliveryOrders({ client });
+      context.io.stdout(result.output);
+    });
+};