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

package/src/cli/runs.ts

@@ -1,9 +1,9 @@
 import select from "@inquirer/select";
-import { assert } from "es-toolkit";
 import type { Pipeline, PotatoClient } from "../client";
 import { PotatoApiError } from "../errors";
 import type { TolokaState } from "../state";
 import type { RunItem, RunJob } from "../index";
+import { assertCli } from "./cli-error";
 
 export type PipelineRef = {
   readonly pipelineId: string;
@@ -131,10 +131,18 @@ const uniqueMatch = (
   ambiguous: string,
   unknown: string,
 ): PipelineRef | undefined => {
-  assert(matches.length <= 1, ambiguous);
+  assertCli(
+    matches.length <= 1,
+    ambiguous,
+    { hint: { description: "Pass the pipeline id shown by toloka pipeline list instead of the name." } },
+  );
   if (matches.length !== 1) return undefined;
   const [ref] = matches;
-  assert(ref, unknown);
+  assertCli(
+    ref,
+    unknown,
+    { hint: { description: "Run toloka pipeline list to see the pipelines of this project." } },
+  );
   return ref;
 };
 
@@ -174,7 +182,11 @@ const resolveToken = (token: string, live: readonly PipelineRef[]): PipelineRef
   );
   if (basename !== undefined) return basename;
 
-  assert(false, unknown);
+  assertCli(
+    false,
+    unknown,
+    { hint: { description: "Run toloka pipeline list to see the pipelines of this project." } },
+  );
 };
 
 export async function resolvePipelineRef(options: {
@@ -188,7 +200,11 @@ export async function resolvePipelineRef(options: {
 
   if (options.pipeline !== undefined) return resolveToken(options.pipeline, live);
 
-  assert(live.length > 0, "This project has no pipelines.");
+  assertCli(
+    live.length > 0,
+    "This project has no pipelines.",
+    { hint: { description: "Run toloka apply to create the pipelines declared in source." } },
+  );
 
   if (live.length > 1 && options.select !== undefined) {
     const chosen = await options.select(
@@ -199,13 +215,22 @@ export async function resolvePipelineRef(options: {
 
   if (live.length === 1) {
     const [only] = live;
-    assert(only, "This project has no pipelines.");
-    assert(false, `Pass a pipeline name. This project has: ${formatPipelineChoice(only)}.`);
+    assertCli(
+      only,
+      "This project has no pipelines.",
+      { hint: { description: "Run toloka apply to create the pipelines declared in source." } },
+    );
+    assertCli(
+      false,
+      `Pass a pipeline name. This project has: ${formatPipelineChoice(only)}.`,
+      { hint: { disabled: true } },
+    );
   }
 
-  assert(
+  assertCli(
     false,
     `This project tracks several pipelines, so name one: ${live.map(formatPipelineChoice).join(", ")}.`,
+    { hint: { disabled: true } },
   );
 }
 

package/src/cli/settings.ts

@@ -3,6 +3,8 @@ import { join } from "node:path";
 import { isFalseyFlag, isTruthyFlag } from "./boolean-flag";
 import type { CliEnvironment } from "./credentials";
 import { configDirectory, preparePrivateFilePath } from "./credentials";
+import { TolokaCliError } from "./cli-error";
+import type { TolokaCliErrorOptions } from "./cli-error";
 
 export const AUTO_UPDATE_SETTING = "auto-update";
 
@@ -14,8 +16,8 @@ export const DEFAULT_CLI_SETTINGS: CliSettings = {
   autoUpdate: true,
 };
 
-export class SettingsError extends Error {
-  constructor(message: string, options?: { readonly cause?: unknown }) {
+export class SettingsError extends TolokaCliError {
+  constructor(message: string, options: TolokaCliErrorOptions) {
     super(message, options);
     this.name = "SettingsError";
   }
@@ -59,7 +61,9 @@ export async function writeCliSettings(
 export const parseBooleanSetting = (value: string): boolean => {
   if (isTruthyFlag(value)) return true;
   if (isFalseyFlag(value)) return false;
-  throw new SettingsError(`Expected a boolean (true or false), got ${JSON.stringify(value)}.`);
+  throw new SettingsError(`Expected a boolean (true or false), got ${JSON.stringify(value)}.`, {
+    hint: { description: "Run toloka config set auto-update true or false." },
+  });
 };
 
 export const formatCliSettings = (settings: CliSettings): string =>
@@ -71,7 +75,9 @@ export const getCliSetting = (
 ): { readonly output: string } => {
   if (name === undefined || name.length === 0) return { output: formatCliSettings(settings) };
   if (name !== AUTO_UPDATE_SETTING) {
-    throw new SettingsError(`Unknown setting "${name}". Known settings: ${AUTO_UPDATE_SETTING}.`);
+    throw new SettingsError(`Unknown setting "${name}". Known settings: ${AUTO_UPDATE_SETTING}.`, {
+      hint: { disabled: true },
+    });
   }
   return { output: String(settings.autoUpdate) };
 };
@@ -82,7 +88,9 @@ export async function setCliSetting(
   value: string,
 ): Promise<{ readonly output: string; readonly settings: CliSettings }> {
   if (name !== AUTO_UPDATE_SETTING) {
-    throw new SettingsError(`Unknown setting "${name}". Known settings: ${AUTO_UPDATE_SETTING}.`);
+    throw new SettingsError(`Unknown setting "${name}". Known settings: ${AUTO_UPDATE_SETTING}.`, {
+      hint: { disabled: true },
+    });
   }
   const settings = { autoUpdate: parseBooleanSetting(value) };
   await writeCliSettings(settings, environment);

package/src/cli/skill.ts

@@ -1,10 +1,10 @@
-import { assert } from "es-toolkit";
 import { createHash } from "node:crypto";
 import { copyFile, mkdir, mkdtemp, readFile, realpath, rename, rm, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { assertSafeDestination, entryStats, hasErrorCode } from "./file-system";
 import { formatCliError } from "./format-error";
 import { releaseChannelFor, SDK_PACKAGE_NAME, SDK_VERSION } from "./sdk-version";
+import { assertCli, REINSTALL_HINT, TolokaCliError } from "./cli-error";
 
 export const SKILL_CATALOG_MANIFEST = "catalog.json";
 export const SKILL_INSTALL_ROOT = ".agents/skills";
@@ -76,31 +76,51 @@ const isSafeRelativePath = (path: string) =>
   path.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
 
 const parseDescriptor = (value: unknown, invalid: (detail: string) => string): SkillDescriptor => {
-  assert(isRecord(value), invalid("every skill must be an object."));
+  assertCli(isRecord(value), invalid("every skill must be an object."), { hint: REINSTALL_HINT });
   const { id, name, description, tags, version, digest, files } = value;
-  assert(
+  assertCli(
     isSafeSkillId(id),
     invalid(
       `skill id ${JSON.stringify(id)} must be at most ${MAX_SKILL_ID_LENGTH} lowercase letters, digits, and single hyphens.`,
     ),
+    { hint: REINSTALL_HINT },
   );
-  assert(isNonEmptyString(name), invalid(`skill ${id} needs a name.`));
-  assert(isNonEmptyString(description), invalid(`skill ${id} needs a description.`));
-  assert(isStringArray(tags), invalid(`skill ${id} tags must be strings.`));
-  assert(isNonEmptyString(version), invalid(`skill ${id} needs a version.`));
-  assert(
+  assertCli(isNonEmptyString(name), invalid(`skill ${id} needs a name.`), { hint: REINSTALL_HINT });
+  assertCli(
+    isNonEmptyString(description),
+    invalid(`skill ${id} needs a description.`),
+    { hint: REINSTALL_HINT },
+  );
+  assertCli(
+    isStringArray(tags),
+    invalid(`skill ${id} tags must be strings.`),
+    { hint: REINSTALL_HINT },
+  );
+  assertCli(
+    isNonEmptyString(version),
+    invalid(`skill ${id} needs a version.`),
+    { hint: REINSTALL_HINT },
+  );
+  assertCli(
     typeof digest === "string" && DIGEST_PATTERN.test(digest),
     invalid(`skill ${id} digest must be the sha256 hex digest of its files.`),
+    { hint: REINSTALL_HINT },
   );
-  assert(
+  assertCli(
     isStringArray(files) && files.includes(SKILL_ENTRY_POINT),
     invalid(`skill ${id} files must include ${SKILL_ENTRY_POINT}.`),
+    { hint: REINSTALL_HINT },
   );
-  assert(
+  assertCli(
     files.every(isSafeRelativePath),
     invalid(`skill ${id} files must be relative paths inside its directory.`),
+    { hint: REINSTALL_HINT },
+  );
+  assertCli(
+    new Set(files).size === files.length,
+    invalid(`skill ${id} lists a file more than once.`),
+    { hint: REINSTALL_HINT },
   );
-  assert(new Set(files).size === files.length, invalid(`skill ${id} lists a file more than once.`));
   return { id, name, description, tags, version, digest, files };
 };
 
@@ -108,7 +128,10 @@ const parseManifest = (source: string, manifestPath: string): unknown => {
   try {
     return JSON.parse(source);
   } catch (error) {
-    throw new Error(`Invalid skill catalog ${manifestPath}: ${formatCliError(error)}`);
+    throw new TolokaCliError(`Invalid skill catalog ${manifestPath}: ${formatCliError(error)}`, {
+      cause: error,
+      hint: REINSTALL_HINT,
+    });
   }
 };
 
@@ -140,9 +163,10 @@ export async function resolveBundledSkillCatalogRoot(
     entry === undefined
       ? "process.argv[1] names no runtime entry"
       : `none exists between ${entry} and the filesystem root`;
-  assert(
+  assertCli(
     workingDirectoryRoot !== undefined,
     `Cannot locate the bundled skill catalog. An installed @toloka-platform/sdk must ship ${SKILL_CATALOG_DIRECTORY}/${SKILL_CATALOG_MANIFEST} in a directory above its runtime entry, but ${searched}, and no ${SKILL_CATALOG_DIRECTORY}/${SKILL_CATALOG_MANIFEST} exists above ${process.cwd()} either. Reinstall @toloka-platform/sdk.`,
+    { hint: { disabled: true } },
   );
   return workingDirectoryRoot;
 }
@@ -154,23 +178,30 @@ export async function loadSkillCatalog(catalogRoot: string): Promise<SkillCatalo
   const manifestPath = join(catalogRoot, SKILL_CATALOG_MANIFEST);
   const invalid = (detail: string) => `Invalid skill catalog ${manifestPath}: ${detail}`;
   const { size } = await stat(manifestPath);
-  assert(
+  assertCli(
     size <= MAX_MANIFEST_BYTES,
     invalid(`the manifest is ${size} bytes; the limit is ${MAX_MANIFEST_BYTES} bytes.`),
+    { hint: REINSTALL_HINT },
   );
   const manifest = parseManifest(await readFile(manifestPath, "utf8"), manifestPath);
-  assert(
+  assertCli(
     isRecord(manifest) && Array.isArray(manifest.skills),
     invalid("expected an object with a skills array."),
+    { hint: REINSTALL_HINT },
   );
-  assert(
+  assertCli(
     manifest.skills.length <= MAX_SKILL_COUNT,
     invalid(`${manifest.skills.length} skills exceed the limit of ${MAX_SKILL_COUNT}.`),
+    { hint: REINSTALL_HINT },
   );
   const skills = manifest.skills.map((skill) => parseDescriptor(skill, invalid));
   const ids = new Set<string>();
   for (const skill of skills) {
-    assert(!ids.has(skill.id), invalid(`skill id ${skill.id} appears more than once.`));
+    assertCli(
+      !ids.has(skill.id),
+      invalid(`skill id ${skill.id} appears more than once.`),
+      { hint: REINSTALL_HINT },
+    );
     ids.add(skill.id);
   }
   return { root: catalogRoot, manifestPath, skills };
@@ -253,9 +284,14 @@ const swapDirectories = async (
     try {
       await renameEntry(backup, destination);
     } catch (restoreError) {
-      throw new Error(
+      throw new TolokaCliError(
         `Failed to replace ${destination}; the previous version is preserved at ${backup}. ${formatCliError(restoreError)}`,
-        { cause: error },
+        {
+          cause: error,
+          hint: {
+            description: `Move ${backup} back to ${destination} by hand, then re-run toloka skill install <skill-id> --force.`,
+          },
+        },
       );
     }
     throw error;
@@ -271,17 +307,19 @@ export async function installSkill({
   rename: renameEntry = rename,
 }: InstallSkillOptions): Promise<InstalledSkill> {
   const skill = catalog.skills.find((candidate) => candidate.id === skillId);
-  assert(
+  assertCli(
     skill,
     `Skill ${JSON.stringify(skillId)} is not in the catalog bundled with ${SDK_PACKAGE_NAME} ${SDK_VERSION}. Run \`toloka skill list\` to see the available skills; a newer release may ship it (${UPGRADE_HINT}).`,
+    { hint: { disabled: true } },
   );
   const relativeDestination = `${SKILL_INSTALL_ROOT}/${skill.id}`;
   await assertSafeDestination(sourceRoot, relativeDestination);
   const destination = join(sourceRoot, relativeDestination);
   const existing = await entryStats(destination);
-  assert(
+  assertCli(
     existing === undefined || force,
     `${relativeDestination} already exists. Re-run with --force to replace it with the catalog version of ${skill.id}.`,
+    { hint: { disabled: true } },
   );
 
   const skillsRoot = dirname(destination);
@@ -293,9 +331,10 @@ export async function installSkill({
       await mkdir(dirname(target), { recursive: true });
       await copyFile(join(catalog.root, skill.id, path), target);
     }
-    assert(
+    assertCli(
       (await computeSkillDigest(temporary, skill.files)) === skill.digest,
       `Skill ${skill.id} failed its digest check: the packaged files do not match the catalog digest ${skill.digest}. Nothing was installed.`,
+      { hint: REINSTALL_HINT },
     );
     if (existing === undefined) {
       await renameEntry(temporary, destination);

package/src/cli/source.ts

@@ -1,9 +1,9 @@
-import { assert } from "es-toolkit";
 import { readdir, stat } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { validatePipelineDefinition } from "../authoring";
 import type { PipelineDefinition } from "../authoring";
+import { assertCli } from "./cli-error";
 
 export type ProjectPipelineSource = {
   readonly sourceDirectory: string;
@@ -64,9 +64,10 @@ export async function loadProjectSource(sourceRoot: string): Promise<ProjectSour
       const moduleUrl = pathToFileURL(modulePath);
       moduleUrl.searchParams.set("version", `${moduleStat.mtimeMs}-${moduleStat.size}`);
       const module: unknown = await import(moduleUrl.href);
-      assert(
+      assertCli(
         typeof module === "object" && module !== null,
         `Invalid ${modulePath}: expected a module`,
+        { hint: { description: "Make the file a TypeScript module that exports the pipeline definition." } },
       );
       const definition: unknown = Reflect.get(module, "default");
       validatePipelineDefinition(definition);

package/src/cli/terminal-io.ts

@@ -2,6 +2,15 @@ import { createInterface } from "node:readline/promises";
 import type { AuthPrompt } from "./auth";
 import type { CliIo } from "./context";
 import { pickPipeline } from "./runs";
+import { TolokaCliError } from "./cli-error";
+
+const stdinClosedError = () =>
+  new TolokaCliError("Standard input closed before an API key was entered.", {
+    hint: {
+      description:
+        "Run toloka login in an interactive terminal, or pipe the key with toloka login --api-key-stdin.",
+    },
+  });
 
 const readStandardInput = async (): Promise<string> => {
   process.stdin.setEncoding("utf8");
@@ -35,7 +44,7 @@ const readMaskedLine = async (question: string): Promise<string> => {
 
   const onEnd = () => {
     finish();
-    reject(new Error("Standard input closed before an API key was entered."));
+    reject(stdinClosedError());
   };
 
   const onError = (error: Error) => {
@@ -53,11 +62,9 @@ const readMaskedLine = async (question: string): Promise<string> => {
       if (character === "\u0003" || character === "\u0004") {
         finish();
         reject(
-          new Error(
-            character === "\u0003"
-              ? "Canceled."
-              : "Standard input closed before an API key was entered.",
-          ),
+          character === "\u0003"
+            ? new TolokaCliError("Canceled.", { hint: { disabled: true } })
+            : stdinClosedError(),
         );
         return;
       }