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

package/src/cli/format-error.ts

@@ -1,4 +1,5 @@
 import { PotatoApiError } from "../errors";
+import { formatHint, TolokaCliError } from "./cli-error";
 
 export const apiErrorDetails = (error: PotatoApiError): string | undefined => {
   const details =
@@ -10,10 +11,52 @@ export const apiErrorDetails = (error: PotatoApiError): string | undefined => {
   return details === undefined || details.length === 0 ? undefined : details;
 };
 
+const apiErrorHint = (error: PotatoApiError): string | undefined => {
+  if (error.code === "wait_timeout") {
+    return "Hint: The job is still running. Check it later with its status command; commands that accept --timeout can wait longer.";
+  }
+  if (error.status === 401 || error.status === 403) {
+    return "Hint: Run toloka whoami to see which key and platform are in use; toloka login stores a new key.";
+  }
+  if (error.status === 404) {
+    return "Hint: Check the id against toloka project current and the matching list command; ids belong to one project on one platform.";
+  }
+  if (error.status === 429) {
+    return "Hint: The platform is rate limiting this key; wait a moment and retry.";
+  }
+  if (error.status !== undefined && error.status >= 500) {
+    return "Hint: The platform failed to handle the request. Retry; if it keeps failing, write a report as the toloka-report-issue skill describes and send it with toloka report <report.md>.";
+  }
+  return undefined;
+};
+
+const joinLines = (lines: ReadonlyArray<string | undefined>): string =>
+  lines.filter((line) => line !== undefined && line.length > 0).join("\n");
+
+export const findPotatoApiError = (error: unknown): PotatoApiError | undefined => {
+  if (error instanceof PotatoApiError) return error;
+  if (error instanceof AggregateError) {
+    for (const nested of error.errors) {
+      const apiError = findPotatoApiError(nested);
+      if (apiError !== undefined) return apiError;
+    }
+  }
+  return error instanceof Error ? findPotatoApiError(error.cause) : undefined;
+};
+
 export const formatCliError = (error: unknown): string => {
+  if (error instanceof TolokaCliError) {
+    const cause = findPotatoApiError(error.cause);
+    const causeLines =
+      cause === undefined
+        ? []
+        : cause.message === error.message
+          ? [apiErrorDetails(cause)]
+          : [cause.message, apiErrorDetails(cause)];
+    return joinLines([error.message, ...causeLines, formatHint(error.hint)]);
+  }
   if (error instanceof PotatoApiError) {
-    const details = apiErrorDetails(error);
-    return details === undefined ? error.message : `${error.message}\n${details}`;
+    return joinLines([error.message, apiErrorDetails(error), apiErrorHint(error)]);
   }
   return error instanceof Error ? error.message : String(error);
 };

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";
+import { assertCli } from "./cli-error";
 
-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`;
@@ -109,14 +106,16 @@ const locateBlock = (source: string, markers: BlockMarkers, path: string) => {
   const beginIndex = source.indexOf(markers.begin);
   const endIndex = source.indexOf(markers.end);
   if (beginIndex === -1 && endIndex === -1) return undefined;
-  assert(
+  assertCli(
     beginIndex !== -1 && endIndex !== -1 && beginIndex < endIndex,
     `Malformed Toloka block in ${path}: expected one ${markers.begin} followed by one ${markers.end}. Repair the file by hand, then re-run \`toloka init\`.`,
+    { hint: { disabled: true } },
   );
-  assert(
+  assertCli(
     !source.includes(markers.begin, beginIndex + markers.begin.length) &&
       !source.includes(markers.end, endIndex + markers.end.length),
     `Multiple Toloka blocks in ${path}: keep exactly one ${markers.begin} ... ${markers.end} block, then re-run \`toloka init\`.`,
+    { hint: { disabled: true } },
   );
   return { beginIndex, endIndex: endIndex + markers.end.length };
 };
@@ -124,9 +123,10 @@ const locateBlock = (source: string, markers: BlockMarkers, path: string) => {
 const mergeBootstrap = (source: string, path: string) => {
   const current = locateBlock(source, CURRENT_BLOCK, path);
   const legacy = locateBlock(source, LEGACY_BLOCK, path);
-  assert(
+  assertCli(
     current === undefined || legacy === undefined,
     `Ambiguous Toloka blocks in ${path}: both ${CURRENT_BLOCK.begin} and ${LEGACY_BLOCK.begin} are present. Keep one, then re-run \`toloka init\`.`,
+    { hint: { disabled: true } },
   );
   const lineEnding = source.includes("\r\n") ? "\r\n" : "\n";
   const block = BOOTSTRAP_BLOCK.replaceAll("\n", lineEnding);
@@ -149,9 +149,10 @@ const hasSdkDependency = async (targetDirectory: string) => {
   const source = await readOptionalFile(join(targetDirectory, "package.json"));
   if (source === undefined) return false;
   const manifest: unknown = JSON.parse(source);
-  assert(
+  assertCli(
     typeof manifest === "object" && manifest !== null,
     "package.json must contain a JSON object.",
+    { hint: { description: "Fix package.json in the source root, then re-run toloka init." } },
   );
   return ["dependencies", "devDependencies"].some((key) => {
     const dependencies = Reflect.get(manifest, key);
@@ -173,9 +174,10 @@ const writeIfChanged = async (path: string, source: string) => {
 const assertRefreshablePointer = async (targetRoot: string, relativePath: string) => {
   const path = join(targetRoot, relativePath);
   const existing = await readOptionalFile(path);
-  assert(
+  assertCli(
     existing === undefined || isGenerated(existing),
     `Refusing to overwrite ${path}: it carries no \`<!-- toloka:sdk-version ... -->\` marker, so it is not a pointer generated by ${SDK_PACKAGE_NAME}. Move it aside, then re-run \`toloka init\`.`,
+    { hint: { disabled: true } },
   );
 };
 
@@ -218,9 +220,10 @@ const bindCheckout = async (
 ): Promise<string | undefined> => {
   if (projectId === undefined) return undefined;
   const existing = await readTolokaState(targetRoot);
-  assert(
+  assertCli(
     existing === undefined || existing.projectId === projectId,
     `This directory is already bound to ${existing?.projectId}.`,
+    { hint: { description: "Run toloka init without --project-id to keep the current binding, or remove toloka.json to bind another project." } },
   );
   if (existing !== undefined) return undefined;
   await writeTolokaState(targetRoot, { projectId, pipelines: {}, datasets: {} });

package/src/cli/models.ts

@@ -5,9 +5,9 @@ import { isAbsolute, relative, resolve, sep } from "node:path";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 
-import { assert } from "es-toolkit";
 
 import type { BaseModel, BaseModelId, Model, ModelVersion, PotatoClient } from "../client";
+import { assertCli, REPORT_HINT, RETRY_OR_REPORT_HINT } from "./cli-error";
 
 type ModelApi = Pick<PotatoClient, "baseModels" | "models">;
 type ModelIo = { readonly stdout: (text: string) => void };
@@ -46,6 +46,7 @@ const formatBaseModel = (model: BaseModel): string =>
     ["Provider", model.provider],
     ["Upstream model", model.upstreamModel],
     ["Upstream revision", model.upstreamRevision],
+    ["Upstream snapshot", model.upstreamUrl],
   ]);
 
 const formatModel = (model: Model): string =>
@@ -62,7 +63,11 @@ const formatModel = (model: Model): string =>
 
 export const parseBaseModelId = (value: string): BaseModelId => {
   const modelId = BASE_MODEL_IDS.find((candidate) => candidate === value);
-  assert(modelId, `Unknown base model ${value}.`);
+  assertCli(
+    modelId,
+    `Unknown base model ${value}.`,
+    { hint: { description: "Run toloka base-model list to see the catalog." } },
+  );
   return modelId;
 };
 
@@ -76,7 +81,11 @@ const resolveModel = async (
   for await (const model of client.models.listAll({ projectId, limit: 100 })) {
     if (model.name === nameOrId) matches.push(model);
   }
-  assert(matches.length === 1, `Model ${nameOrId} was not found or is ambiguous.`);
+  assertCli(
+    matches.length === 1,
+    `Model ${nameOrId} was not found or is ambiguous.`,
+    { hint: { description: "Run toloka model list and pass the model id (mdl.…)." } },
+  );
   return matches[0]!;
 };
 
@@ -87,8 +96,16 @@ const resolveModelVersion = async (
 ): Promise<ModelVersion> => {
   if (nameOrId.startsWith("mdv.")) return client.models.getVersion({ modelVersionId: nameOrId });
   const separator = nameOrId.lastIndexOf("@");
-  assert(separator > 0, `Model Version ${nameOrId} was not found. Use mdv.<id> or Model@name.`);
-  assert(projectId, "Select a project to resolve Model Version names.");
+  assertCli(
+    separator > 0,
+    `Model Version ${nameOrId} was not found. Use mdv.<id> or Model@name.`,
+    { hint: { disabled: true } },
+  );
+  assertCli(
+    projectId,
+    "Select a project to resolve Model Version names.",
+    { hint: { description: "Select a project with toloka project add or toloka project switch, or pass the version id (mdv.…) directly." } },
+  );
   const model = await resolveModel(client, projectId, nameOrId.slice(0, separator));
   const versionName = nameOrId.slice(separator + 1);
   const matches: ModelVersion[] = [];
@@ -99,7 +116,11 @@ const resolveModelVersion = async (
   })) {
     if (version.name === versionName) matches.push(version);
   }
-  assert(matches.length === 1, `Model Version ${nameOrId} was not found or is ambiguous.`);
+  assertCli(
+    matches.length === 1,
+    `Model Version ${nameOrId} was not found or is ambiguous.`,
+    { hint: { description: "Run toloka model versions <model> and pass the version id (mdv.…)." } },
+  );
   return matches[0]!;
 };
 
@@ -116,12 +137,14 @@ export const listBaseModels = async (
     models.length === 0
       ? "No base models found."
       : formatTable([
-          ["ID", "NAME", "PROVIDER", "UPSTREAM MODEL"],
+          ["ID", "NAME", "PROVIDER", "UPSTREAM MODEL", "REVISION", "UPSTREAM SNAPSHOT"],
           ...models.map((model) => [
             model.id,
             model.displayName,
             model.provider,
             model.upstreamModel,
+            model.upstreamRevision.slice(0, 12),
+            model.upstreamUrl,
           ]),
         ]),
   );
@@ -238,25 +261,31 @@ export const downloadModelVersion = async (
   for (const file of descriptor.files) {
     const target = resolve(root, file.path);
     const relativeTarget = relative(root, target);
-    assert(
+    assertCli(
       relativeTarget !== "" &&
         relativeTarget !== ".." &&
         !relativeTarget.startsWith(`..${sep}`) &&
         !isAbsolute(relativeTarget),
       `Invalid Model Version file path: ${file.path}`,
+      { hint: REPORT_HINT },
     );
     let parent = root;
     for (const segment of file.path.split("/").slice(0, -1)) {
       parent = resolve(parent, segment);
       await mkdir(parent, { recursive: true });
       const realParent = await realpath(parent);
-      assert(
+      assertCli(
         realParent === realRoot || realParent.startsWith(`${realRoot}${sep}`),
         `Invalid Model Version file path: ${file.path}`,
+        { hint: REPORT_HINT },
       );
     }
     const response = await fetch(file.url, { redirect: "error" });
-    assert(response.ok && response.body, `Failed to download Model Version file ${file.path}.`);
+    assertCli(
+      response.ok && response.body,
+      `Failed to download Model Version file ${file.path}.`,
+      { hint: RETRY_OR_REPORT_HINT },
+    );
     const hash = createHash("sha256");
     let byteSize = 0;
     const verify = new Transform({
@@ -274,13 +303,15 @@ export const downloadModelVersion = async (
         0o600,
       );
       await pipeline(Readable.from(response.body), verify, handle.createWriteStream());
-      assert(
+      assertCli(
         byteSize === file.byteSize,
         `Downloaded Model Version file ${file.path} has an unexpected size.`,
+        { hint: { description: "Delete the partial download and retry; if it keeps failing, run toloka report." } },
       );
-      assert(
+      assertCli(
         hash.digest("hex") === file.sha256,
         `Downloaded Model Version file ${file.path} has an invalid hash.`,
+        { hint: { description: "Delete the partial download and retry; if it keeps failing, run toloka report." } },
       );
       await rename(temporary, target);
     } catch (error) {