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

package/src/cli/project-context.ts

@@ -1,4 +1,4 @@
-import { assert } from "es-toolkit";
+import { PotatoApiError } from "../errors";
 import { readTolokaState, TOLOKA_STATE_FILENAME, writeTolokaState } from "../state";
 import type { TolokaState } from "../state";
 import type { AuthPrompt } from "./auth";
@@ -6,6 +6,8 @@ import type { TolokaCliFlags, TolokaEnvironment } from "./config";
 import { resolveInternalBaseUrl } from "./config";
 import { normalizeBaseUrl, requireStoredCredentials, writeStoredCredentials } from "./credentials";
 import type { CliEnvironment, StoredCredentials, StoredProjectAlias } from "./credentials";
+import { apiErrorDetails } from "./format-error";
+import { assertCli, TolokaCliError } from "./cli-error";
 
 type ProjectRecord = { readonly id: string; readonly name: string; readonly teamId: string };
 
@@ -24,20 +26,26 @@ export type ProjectGetApi = {
   };
 };
 
+export type AccountTeam = { readonly id: string; readonly writable: boolean; readonly internal?: boolean };
+
 export type ProjectCreateApi = {
+  readonly me: () => Promise<{ readonly teams?: readonly AccountTeam[] }>;
   readonly projects: {
     readonly create: (input: {
       readonly teamId: string;
       readonly name?: string;
       readonly deliveryOrderId?: string;
     }) => Promise<ProjectRecord>;
-    readonly listAll: (params?: object) => AsyncIterable<ProjectRecord>;
   };
 };
 
 export const MISSING_PROJECT_ID_MESSAGE =
   "Missing project ID. Pass --project-id, set TOLOKA_PROJECT_ID, use a bound toloka.json, run toloka project create for a new project, or run toloka project add for an existing project.";
 
+export function assertProjectSelected(projectId: string | undefined): asserts projectId is string {
+  assertCli(projectId, MISSING_PROJECT_ID_MESSAGE, { hint: { disabled: true } });
+}
+
 export const NO_PROJECT_SELECTED_MESSAGE =
   "No project selected. Run toloka project create for a new project, toloka project add for an existing project, or cd into a checkout.";
 
@@ -70,9 +78,10 @@ export type ProjectIo = {
 
 export const validateProjectAlias = (alias: string): string => {
   const trimmed = alias.trim();
-  assert(
+  assertCli(
     trimmed.length > 0 && ALIAS_PATTERN.test(trimmed),
     "Project alias must be non-empty and contain no / or whitespace.",
+    { hint: { description: "Use letters, digits, dashes, or underscores, for example my-project." } },
   );
   return trimmed;
 };
@@ -183,11 +192,16 @@ const assertStoredNetworkMatches = (
     firstNonEmpty(flags.baseUrl) ??
     firstNonEmpty(environment.TOLOKA_BASE_URL) ??
     resolveInternalBaseUrl(environment);
-  assert(flagOrEnvKey === undefined || flagOrEnvKey === stored.apiKey, NETWORK_MISMATCH_MESSAGE);
-  assert(
+  assertCli(
+    flagOrEnvKey === undefined || flagOrEnvKey === stored.apiKey,
+    NETWORK_MISMATCH_MESSAGE,
+    { hint: { disabled: true } },
+  );
+  assertCli(
     flagOrEnvBase === undefined ||
       normalizeBaseUrl(flagOrEnvBase) === normalizeBaseUrl(stored.baseUrl),
     NETWORK_MISMATCH_MESSAGE,
+    { hint: { disabled: true } },
   );
 };
 
@@ -214,9 +228,9 @@ const promptOrFail = async (
   question: string,
   missing: string,
 ): Promise<string> => {
-  assert(io?.prompt, missing);
+  assertCli(io?.prompt, missing, { hint: { disabled: true } });
   const value = (await io.prompt(question)).trim();
-  assert(value.length > 0, missing);
+  assertCli(value.length > 0, missing, { hint: { disabled: true } });
   return value;
 };
 
@@ -254,27 +268,37 @@ export async function untrackProjectResource(options: {
   readonly io: ProjectIo;
 }): Promise<{ readonly output: string }> {
   const state = await readTolokaState(options.sourceRoot);
-  assert(state, `No ${TOLOKA_STATE_FILENAME} found in ${options.sourceRoot}.`);
+  assertCli(
+    state,
+    `No ${TOLOKA_STATE_FILENAME} found in ${options.sourceRoot}.`,
+    { hint: { description: "Run toloka init in the source root, or cd into the checkout that holds toloka.json." } },
+  );
   const bindings = options.type === "pipeline" ? state.pipelines : state.datasets;
   const binding = bindings[options.name];
-  assert(
+  assertCli(
     binding,
     `${options.type === "pipeline" ? "Pipeline" : "Dataset"} ${options.name} is not tracked.`,
+    { hint: { description: "Open toloka.json to see the tracked pipelines and datasets." } },
   );
   const id = "pipelineId" in binding ? binding.pipelineId : binding.datasetId;
   const label = `${options.type} ${options.name} (${id})`;
 
   if (!options.confirm) {
-    assert(
+    assertCli(
       options.io.prompt,
       `Refusing to untrack ${label} without confirmation. Pass --confirm after reviewing ${TOLOKA_STATE_FILENAME}.`,
+      { hint: { disabled: true } },
     );
     const answer = (
       await options.io.prompt(`Untrack ${label}? The live resource will not be deleted. [y/N] `)
     )
       .trim()
       .toLowerCase();
-    assert(answer === "y" || answer === "yes", "Untrack canceled.");
+    assertCli(
+      answer === "y" || answer === "yes",
+      "Untrack canceled.",
+      { hint: { disabled: true } },
+    );
   }
 
   const remaining = Object.fromEntries(
@@ -319,9 +343,10 @@ export async function addProject(options: {
 
   const existing = ownProject(found.credentials.projects, alias);
 
-  assert(
+  assertCli(
     existing === undefined || existing.id === projectId,
     `Alias ${alias} already points at ${existing?.id}. Run toloka project remove ${alias} first.`,
+    { hint: { disabled: true } },
   );
 
   await options.afterPreflight?.();
@@ -346,7 +371,11 @@ export async function switchProject(options: {
   assertStoredNetworkMatches(options.flags ?? {}, options.environment, found.credentials);
   const alias = validateProjectAlias(options.alias);
   const project = ownProject(found.credentials.projects, alias);
-  assert(project, `Unknown project alias ${alias}.`);
+  assertCli(
+    project,
+    `Unknown project alias ${alias}.`,
+    { hint: { description: "Run toloka project add <alias> <project-id> to register it, or check the alias spelling." } },
+  );
 
   await writeRegistry({ ...found.credentials, current: alias }, options.environment);
   const output = `Using project ${project.id} as ${alias}.`;
@@ -367,7 +396,11 @@ export async function removeProject(options: {
     string,
     StoredProjectAlias
   >;
-  assert(ownProject(projects, alias), `Unknown project alias ${alias}.`);
+  assertCli(
+    ownProject(projects, alias),
+    `Unknown project alias ${alias}.`,
+    { hint: { description: "Run toloka project add <alias> <project-id> to register it, or check the alias spelling." } },
+  );
   delete projects[alias];
 
   const current = found.credentials.current === alias ? undefined : found.credentials.current;
@@ -401,25 +434,71 @@ export function currentProject(options: {
   return project === undefined ? { output } : { output, project };
 }
 
-const uniqueTeamId = (projects: ReadonlyArray<{ readonly teamId: string }>): string | undefined => {
-  const teams = [...new Set(projects.map((project) => project.teamId))];
-  return teams.length === 1 ? teams[0] : undefined;
-};
-
 const resolveTeamId = async (
   client: ProjectCreateApi,
   teamId: string | undefined,
 ): Promise<string> => {
   const explicit = firstNonEmpty(teamId);
   if (explicit !== undefined) return explicit;
-  const visible: Array<{ readonly teamId: string }> = [];
-  for await (const project of client.projects.listAll()) visible.push(project);
-  const inferred = uniqueTeamId(visible);
-  assert(
-    inferred,
-    "Missing team id. Pass --team-id. Visible projects do not share a single team, or none are visible.",
+  const { teams } = await client.me();
+  assertCli(
+    teams !== undefined,
+    "Missing team id. Pass --team-id. This platform does not report team memberships, so the team cannot be inferred.",
+    {
+      hint: {
+        description: "Copy the team id from the platform URL after /teams/, or update the platform.",
+      },
+    },
+  );
+  const writable = teams.filter((team) => team.writable).map((team) => team.id);
+  assertCli(
+    writable.length > 0,
+    "This account has no writable team, so it cannot create a project. Ask a team admin for write access or use toloka project add for an existing project.",
+    { hint: { disabled: true } },
   );
-  return inferred;
+  const [single] = writable;
+  assertCli(
+    single !== undefined && writable.length === 1,
+    `Missing team id. Pass --team-id. This account can create projects in several teams: ${writable.join(", ")}.`,
+    { hint: { disabled: true } },
+  );
+  return single;
+};
+
+const DELIVERY_ORDER_HINT =
+  "Internal teams attach a Sunday delivery order to every project: run toloka delivery-order list, then re-run toloka project create with --delivery-order-id <id>.";
+
+const DELIVERY_ORDER_NOT_ALLOWED_HINT =
+  "The owning team is not internal, so re-run toloka project create without --delivery-order-id. toloka whoami marks internal teams (internal) on its Teams: line.";
+
+const deliveryOrderHint = (
+  input: Parameters<ProjectCreateApi["projects"]["create"]>[0],
+  details: string,
+): string | undefined => {
+  if (!details.includes("deliveryOrderId")) return undefined;
+  if (input.deliveryOrderId === undefined && details.includes("required")) return DELIVERY_ORDER_HINT;
+  if (input.deliveryOrderId !== undefined && details.includes("only be set")) {
+    return DELIVERY_ORDER_NOT_ALLOWED_HINT;
+  }
+  return undefined;
+};
+
+const createLiveProject = async (
+  client: ProjectCreateApi,
+  input: Parameters<ProjectCreateApi["projects"]["create"]>[0],
+): Promise<ProjectRecord> => {
+  try {
+    return await client.projects.create(input);
+  } catch (error) {
+    if (error instanceof PotatoApiError && error.status === 400) {
+      const details = apiErrorDetails(error);
+      const hint = details === undefined ? undefined : deliveryOrderHint(input, details);
+      if (hint !== undefined) {
+        throw new TolokaCliError(error.message, { cause: error, hint: { description: hint } });
+      }
+    }
+    throw error;
+  }
 };
 
 const bindCheckout = async (
@@ -437,12 +516,17 @@ const bindCheckout = async (
       });
     } catch (error) {
       const reason = error instanceof Error ? error.message : String(error);
-      throw new Error(
+      throw new TolokaCliError(
         [
           `Created project ${created.id} as ${alias}.`,
           `Failed to write toloka.json: ${reason}`,
         ].join("\n"),
-        { cause: error },
+        {
+          cause: error,
+          hint: {
+            description: `The project exists. Make ${sourceRoot} writable, then run toloka --project-id ${created.id} init to bind it.`,
+          },
+        },
       );
     }
     return undefined;
@@ -474,9 +558,10 @@ export async function createProject(options: {
         "Missing project alias. Pass an alias or run this in a terminal.",
       )),
   );
-  assert(
+  assertCli(
     found.credentials.projects?.[alias] === undefined,
     `Alias ${alias} already exists. Run toloka project remove ${alias} first.`,
+    { hint: { disabled: true } },
   );
 
   const existingState =
@@ -486,7 +571,7 @@ export async function createProject(options: {
 
   const teamId = await resolveTeamId(options.client, options.teamId);
   const deliveryOrderId = firstNonEmpty(options.deliveryOrderId);
-  const created = await options.client.projects.create({
+  const created = await createLiveProject(options.client, {
     teamId,
     name: firstNonEmpty(options.name) ?? alias,
     ...(deliveryOrderId === undefined ? {} : { deliveryOrderId }),
@@ -499,12 +584,12 @@ export async function createProject(options: {
     );
   } catch (error) {
     const reason = error instanceof Error ? error.message : String(error);
-    throw new Error(
+    throw new TolokaCliError(
       [
         `Created ${created.id} but failed to update the local registry: ${reason}`,
         `Run: toloka project add ${alias} ${created.id}`,
       ].join("\n"),
-      { cause: error },
+      { cause: error, hint: { disabled: true } },
     );
   }
 

package/src/cli/project.ts

@@ -1,4 +1,3 @@
-import { assert } from "es-toolkit";
 import { mkdir, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import type {
@@ -12,10 +11,11 @@ import type { Dataset, DatasetField, Pipeline, PotatoClient } from "../client";
 import { generatePipelineSourceTree } from "../importer";
 import { readTolokaState, TOLOKA_STATE_FILENAME, writeTolokaState } from "../state";
 import type { TolokaState } from "../state";
-import { MISSING_PROJECT_ID_MESSAGE } from "./project-context";
+import { assertProjectSelected } from "./project-context";
 import { collectGraphSecretNames } from "./secrets";
 import { loadProjectSource } from "./source";
 import type { ProjectPipelineSource, ProjectSource } from "./source";
+import { assertCli, REPORT_HINT } from "./cli-error";
 
 export type PipelinePlanChange = {
   readonly kind: "node" | "connection" | "field" | "layout";
@@ -296,9 +296,10 @@ export const desiredDatasets = (source: ProjectSource): readonly DesiredDataset[
     }
     for (const field of pipeline.definition.graph.fields) {
       const existing = fields.get(field.name);
-      assert(
+      assertCli(
         existing === undefined || valueKey(existing.jsonSchema) === valueKey(field.jsonSchema),
         `Dataset "${pipeline.definition.dataset}" has conflicting schemas for field "${field.name}".`,
+        { hint: { description: "Give the field one JSON schema across all pipelines that share the dataset." } },
       );
       if (existing === undefined) fields.set(field.name, field);
     }
@@ -314,13 +315,15 @@ export const desiredDatasets = (source: ProjectSource): readonly DesiredDataset[
 const validateSource = (source: ProjectSource) => {
   const sourceDirectories = new Set<string>();
   for (const pipeline of source.pipelines) {
-    assert(
+    assertCli(
       sourceDirectoryPattern.test(pipeline.sourceDirectory),
       `Invalid pipeline source directory ${pipeline.sourceDirectory}`,
+      { hint: { description: "Use a relative path without backslashes, // or . and .. segments." } },
     );
-    assert(
+    assertCli(
       !sourceDirectories.has(pipeline.sourceDirectory),
       `Pipeline source directory ${pipeline.sourceDirectory} is declared more than once`,
+      { hint: { description: "Give each pipeline its own source directory." } },
     );
     sourceDirectories.add(pipeline.sourceDirectory);
     validatePipelineDefinition(pipeline.definition);
@@ -338,14 +341,19 @@ const liveDatasetFor = (
       ? undefined
       : datasets.find((dataset) => dataset.id === binding.datasetId);
   if (bound !== undefined) {
-    assert(
+    assertCli(
       bound.name === name,
       `Dataset ${bound.id} is bound as "${name}" but is named "${bound.name}".`,
+      { hint: { description: "Rename the dataset in source to match the platform, or run toloka project untrack dataset <name> and bind it again with toloka apply." } },
     );
     return bound;
   }
   const matching = datasets.filter((dataset) => dataset.name === name);
-  assert(matching.length <= 1, `Project has multiple datasets named "${name}".`);
+  assertCli(
+    matching.length <= 1,
+    `Project has multiple datasets named "${name}".`,
+    { hint: { description: "Rename the duplicate datasets in the platform, or reference the dataset by id." } },
+  );
   return matching[0];
 };
 
@@ -360,7 +368,11 @@ const livePipelineFor = (
       : pipelines.find((pipeline) => pipeline.id === binding.pipelineId);
   if (bound !== undefined) return bound;
   const matching = pipelines.filter((pipeline) => pipeline.name === source.name);
-  assert(matching.length <= 1, `Project has multiple pipelines named "${source.name}".`);
+  assertCli(
+    matching.length <= 1,
+    `Project has multiple pipelines named "${source.name}".`,
+    { hint: { description: "Rename the duplicate pipelines in the platform, then re-run the command." } },
+  );
   return matching[0];
 };
 
@@ -542,7 +554,7 @@ const inspectProject = async (
   validateSource(source);
   const state = await readTolokaState(options.sourceRoot);
   const projectId = options.projectId ?? state?.projectId;
-  assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+  assertProjectSelected(projectId);
 
   const bindings = state?.projectId === projectId ? state : undefined;
   const requiredSecrets = new Set(
@@ -627,7 +639,11 @@ export async function importProject(
   const datasetIds = new Set<string>();
   for (const snapshot of snapshots) {
     const rootNode = snapshot.graph.nodes.find((node) => node.type === "root");
-    assert(rootNode?.settings.datasetId, "Every imported pipeline must have a bound dataset.");
+    assertCli(
+      rootNode?.settings.datasetId,
+      "Every imported pipeline must have a bound dataset.",
+      { hint: { description: "Bind a dataset to the pipeline in the platform, then re-run toloka import." } },
+    );
     datasetIds.add(rootNode.settings.datasetId);
   }
   const projectDatasets = await collectAsync(
@@ -636,7 +652,11 @@ export async function importProject(
   const datasets: Dataset[] = [];
   for (const datasetId of [...datasetIds].toSorted()) {
     const dataset = projectDatasets.find((candidate) => candidate.id === datasetId);
-    assert(dataset, `Project ${options.projectId} has no dataset ${datasetId}.`);
+    assertCli(
+      dataset,
+      `Project ${options.projectId} has no dataset ${datasetId}.`,
+      { hint: { description: "Check toloka dataset list; the pipeline's dataset binding must point at a dataset of this project." } },
+    );
     datasets.push(dataset);
   }
   const datasetsById = new Map<string, Dataset>(datasets.map((dataset) => [dataset.id, dataset]));
@@ -646,22 +666,32 @@ export async function importProject(
   const stateDatasets: Record<string, { readonly datasetId: string }> = {};
   for (const [index, pipeline] of pipelines.entries()) {
     const snapshot = snapshots[index];
-    assert(snapshot, `Pipeline ${pipeline.id} has no graph snapshot.`);
+    assertCli(snapshot, `Pipeline ${pipeline.id} has no graph snapshot.`, { hint: REPORT_HINT });
     const rootNode = snapshot.graph.nodes.find((node) => node.type === "root");
-    assert(rootNode?.settings.datasetId, `Pipeline ${pipeline.id} has no dataset binding.`);
+    assertCli(
+      rootNode?.settings.datasetId,
+      `Pipeline ${pipeline.id} has no dataset binding.`,
+      { hint: { description: "Bind a dataset to the pipeline in the platform, then re-run toloka import." } },
+    );
     const dataset = datasetsById.get(rootNode.settings.datasetId);
-    assert(
+    assertCli(
       dataset,
       `Pipeline ${pipeline.id} references unknown dataset ${rootNode.settings.datasetId}.`,
+      { hint: { description: "Check toloka dataset list; the pipeline's dataset binding must point at a dataset of this project." } },
     );
     const existingDatasetBinding = stateDatasets[dataset.name];
-    assert(
+    assertCli(
       existingDatasetBinding === undefined || existingDatasetBinding.datasetId === dataset.id,
       `Project has multiple referenced datasets named "${dataset.name}".`,
+      { hint: { description: "Rename the duplicate datasets in the platform, then re-run toloka import." } },
     );
     stateDatasets[dataset.name] = { datasetId: dataset.id };
     const sourceDirectory = directories.get(pipeline.id);
-    assert(sourceDirectory, `Pipeline ${pipeline.id} has no source directory.`);
+    assertCli(
+      sourceDirectory,
+      `Pipeline ${pipeline.id} has no source directory.`,
+      { hint: REPORT_HINT },
+    );
     statePipelines[sourceDirectory] = { pipelineId: pipeline.id };
     for (const [relativePath, source] of Object.entries(
       generatePipelineSourceTree(snapshot.graph, { dataset: dataset.name }),
@@ -678,9 +708,10 @@ export async function importProject(
   } catch (error) {
     if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") throw error;
   }
-  assert(
+  assertCli(
     !pipelinesRootExists || options.force === true,
     `Folder already exists: ${pipelinesRoot}. Pass --force to replace it.`,
+    { hint: { disabled: true } },
   );
   if (pipelinesRootExists) await rm(pipelinesRoot, { recursive: true, force: true });
 
@@ -725,7 +756,7 @@ export async function projectStatus(
   options: PlanProjectOptions,
 ): Promise<ProjectStatusResult> {
   const projectId = options.projectId;
-  assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+  assertProjectSelected(projectId);
   const live = await client.projects.get({ projectId });
   const inspection = await inspectProject(client, { ...options, listAllSecrets: true });
   const pending = inspection.changes.length;
@@ -751,24 +782,28 @@ export async function applyProject(
   options: ApplyProjectOptions,
 ): Promise<ApplyProjectResult> {
   const inspection = await inspectProject(client, options);
-  assert(
+  assertCli(
     inspection.removedPipelines.length === 0,
     `Refusing to delete pipelines absent from source: ${inspection.removedPipelines.join(", ")}.`,
+    { hint: { description: "Restore the pipeline in source, or run toloka project untrack pipeline <name> to stop managing it." } },
   );
-  assert(
+  assertCli(
     inspection.removedDatasets.length === 0,
     `Refusing to delete datasets absent from source: ${inspection.removedDatasets.join(", ")}. Dataset items are never deleted.`,
+    { hint: { description: "Restore the dataset in source, or run toloka project untrack dataset <name> to stop managing it." } },
   );
-  assert(
+  assertCli(
     inspection.missingSecrets.length === 0,
     `Required secrets are missing: ${inspection.missingSecrets.join(", ")}. Run toloka secret set <name> before apply.`,
+    { hint: { disabled: true } },
   );
   const conflictingFields = inspection.datasets.flatMap((dataset) =>
     dataset.conflictingFields.map((field) => `${dataset.name}.${field.name}`),
   );
-  assert(
+  assertCli(
     conflictingFields.length === 0,
     `Dataset field schemas conflict with source: ${conflictingFields.join(", ")}. Existing fields are never rewritten.`,
+    { hint: { description: "Add the changed columns under new field names, or create a new dataset for the new schema." } },
   );
 
   let writes = 0;
@@ -798,9 +833,10 @@ export async function applyProject(
   const pipelineIds = new Map<string, string>();
   for (const pipelineInspection of inspection.pipelines) {
     const datasetId = datasetIds.get(pipelineInspection.source.definition.dataset);
-    assert(
+    assertCli(
       datasetId,
       `Dataset ${pipelineInspection.source.definition.dataset} has no resolved ID.`,
+      { hint: REPORT_HINT },
     );
     const desiredGraph = resolvePipelineDefinition(pipelineInspection.source.definition, {
       datasetId,
@@ -819,7 +855,11 @@ export async function applyProject(
     pipelineIds.set(pipelineInspection.source.sourceDirectory, pipelineInspection.pipeline.id);
     if (pipelineInspection.graphChanges.length === 0) continue;
     const snapshot = pipelineInspection.snapshot;
-    assert(snapshot, `Pipeline ${pipelineInspection.pipeline.id} has no graph snapshot.`);
+    assertCli(
+      snapshot,
+      `Pipeline ${pipelineInspection.pipeline.id} has no graph snapshot.`,
+      { hint: REPORT_HINT },
+    );
     await client.pipelines.replaceGraph({
       pipelineId: pipelineInspection.pipeline.id,
       graph: graphWithLiveState(desiredGraph, snapshot.graph),
@@ -833,14 +873,18 @@ export async function applyProject(
     pipelines: Object.fromEntries(
       inspection.source.pipelines.map((pipeline) => {
         const pipelineId = pipelineIds.get(pipeline.sourceDirectory);
-        assert(pipelineId, `Pipeline ${pipeline.sourceDirectory} has no resolved ID.`);
+        assertCli(
+          pipelineId,
+          `Pipeline ${pipeline.sourceDirectory} has no resolved ID.`,
+          { hint: REPORT_HINT },
+        );
         return [pipeline.sourceDirectory, { pipelineId }];
       }),
     ),
     datasets: Object.fromEntries(
       inspection.datasets.map((dataset) => {
         const datasetId = datasetIds.get(dataset.name);
-        assert(datasetId, `Dataset ${dataset.name} has no resolved ID.`);
+        assertCli(datasetId, `Dataset ${dataset.name} has no resolved ID.`, { hint: REPORT_HINT });
         return [dataset.name, { datasetId }];
       }),
     ),
@@ -957,8 +1001,16 @@ export async function validateProject(
   const lines = results.flatMap((result) => {
     if (result.skipped !== undefined)
       return [`- ${result.sourceDirectory}: skipped (${result.skipped})`];
-    assert(result.report, `Pipeline ${result.sourceDirectory} is missing a validation report`);
-    assert(result.status, `Pipeline ${result.sourceDirectory} is missing a validation status`);
+    assertCli(
+      result.report,
+      `Pipeline ${result.sourceDirectory} is missing a validation report`,
+      { hint: REPORT_HINT },
+    );
+    assertCli(
+      result.status,
+      `Pipeline ${result.sourceDirectory} is missing a validation status`,
+      { hint: REPORT_HINT },
+    );
     const header = `- ${result.sourceDirectory}: ${result.status.replace("_", "-")}`;
     return [header, ...formatValidationIssues(result.report)];
   });

package/src/cli/report.ts

@@ -1,9 +1,9 @@
-import { assert } from "es-toolkit";
 import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { lstat, open, type FileHandle } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import type { CliAnalytics } from "./analytics";
+import { assertCli, TolokaCliError } from "./cli-error";
 
 export type IssueReportAuthor = "human" | "agent";
 
@@ -31,9 +31,10 @@ const assertNoSymlinkParents = async (absolutePath: string, sourceRoot: string):
   for (let index = 1; index < segments.length; index += 1) {
     const directory = join(sourceRoot, ...segments.slice(0, index));
     const stats = await lstat(directory);
-    assert(
+    assertCli(
       !stats.isSymbolicLink(),
       `Report file ${absolutePath} is inside the symbolic link ${directory}; select a path that does not traverse symbolic links.`,
+      { hint: { disabled: true } },
     );
   }
 };
@@ -49,20 +50,30 @@ const openReportFile = async (
   try {
     handle = await open(absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
   } catch (error) {
-    assert(
+    assertCli(
       !(error instanceof Error && "code" in error && error.code === "ELOOP"),
       `Report file ${absolutePath} is a symbolic link; select the file it points to directly.`,
+      { hint: { disabled: true } },
     );
     throw error;
   }
 
   try {
     const stats = await handle.stat();
-    assert(stats.isFile(), `Report file ${absolutePath} is not a regular file.`);
-    assert(stats.size > 0, `Report file ${absolutePath} is empty.`);
-    assert(
+    assertCli(
+      stats.isFile(),
+      `Report file ${absolutePath} is not a regular file.`,
+      { hint: { description: "Pass the path of a Markdown or text file." } },
+    );
+    assertCli(
+      stats.size > 0,
+      `Report file ${absolutePath} is empty.`,
+      { hint: { description: "Write the report first; the toloka-report-issue skill describes the format." } },
+    );
+    assertCli(
       stats.size <= ISSUE_REPORT_MAX_BYTES,
       `Report file ${absolutePath} is ${stats.size} bytes; the limit is 256 KiB.`,
+      { hint: { description: "Trim the report to under 256 KiB, for example by shortening logs." } },
     );
     return { handle, absolutePath, size: stats.size };
   } catch (error) {
@@ -75,14 +86,17 @@ const readReportText = async (path: string, sourceRoot: string, cwd: string): Pr
   const opened = await openReportFile(path, sourceRoot, cwd);
   try {
     const bytes = await opened.handle.readFile();
-    assert(
+    assertCli(
       bytes.byteLength === opened.size,
       `${opened.absolutePath} changed while it was being read.`,
+      { hint: { description: "Re-run toloka report once the file is no longer being written." } },
     );
     try {
       return REPORT_DECODER.decode(bytes);
     } catch {
-      throw new Error(`Report file ${opened.absolutePath} is not valid UTF-8.`);
+      throw new TolokaCliError(`Report file ${opened.absolutePath} is not valid UTF-8.`, {
+        hint: { description: "Save the report as UTF-8 text." },
+      });
     }
   } finally {
     await opened.handle.close();
@@ -107,9 +121,10 @@ export async function submitIssueReport(options: {
   readonly io: IssueReportIo;
 }): Promise<number> {
   const { analytics, io } = options;
-  assert(
+  assertCli(
     analytics.issueReportingEnabled,
     "Issue reporting is disabled. Re-run with TOLOKA_TELEMETRY=1.",
+    { hint: { disabled: true } },
   );
   const reportText = await readReportText(options.path, options.sourceRoot, options.cwd);
   io.stdout("Issue report preview:");