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

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,
@@ -27,6 +26,8 @@ import {
 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 =
@@ -118,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;
@@ -358,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 };
@@ -373,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 };
 };
@@ -789,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 }),
@@ -822,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");
@@ -831,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,
@@ -864,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,
@@ -899,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 },
     );
   }
 
@@ -915,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,
     });
   }
 
@@ -924,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 },
     );
   }
 };
@@ -958,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/dataset.ts

@@ -1,14 +1,14 @@
-import { assert } from "es-toolkit";
 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 { MISSING_PROJECT_ID_MESSAGE } from "../project-context";
+import { assertProjectSelected } from "../project-context";
 
 export const registerDatasetCommands = (program: Command, host: CommandHost): void => {
   const { context, globals } = host;
@@ -20,10 +20,20 @@ export const registerDatasetCommands = (program: Command, host: CommandHost): vo
     .description("list live datasets in the selected project")
     .action(async () => {
       const { client, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      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")

package/src/cli/commands/models.ts

@@ -1,4 +1,3 @@
-import { assert } from "es-toolkit";
 import type { Command } from "commander";
 import { resolveContext, type CommandHost } from "../context";
 import {
@@ -12,7 +11,7 @@ import {
   listModelVersions,
   parseBaseModelId,
 } from "../models";
-import { MISSING_PROJECT_ID_MESSAGE } from "../project-context";
+import { assertProjectSelected } from "../project-context";
 
 export const registerModelCommands = (program: Command, host: CommandHost): void => {
   const { context, globals } = host;
@@ -47,7 +46,7 @@ export const registerModelCommands = (program: Command, host: CommandHost): void
     .description("list Models owned by the selected project")
     .action(async (options: { json: boolean }) => {
       const { client, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       await listModels(client, { projectId, json: options.json }, context.io);
     });
   model
@@ -57,7 +56,7 @@ export const registerModelCommands = (program: Command, host: CommandHost): void
     .description("show one project Model")
     .action(async (nameOrId: string, options: { json: boolean }) => {
       const { client, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       await getModel(client, { projectId, nameOrId, json: options.json }, context.io);
     });
   model
@@ -67,7 +66,7 @@ export const registerModelCommands = (program: Command, host: CommandHost): void
     .description("list immutable versions of a model")
     .action(async (nameOrId: string, options: { json: boolean }) => {
       const { client, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       await listModelVersions(client, { projectId, nameOrId, json: options.json }, context.io);
     });
   model
@@ -80,7 +79,7 @@ export const registerModelCommands = (program: Command, host: CommandHost): void
     .action(
       async (name: string, options: { base: string; description?: string; json: boolean }) => {
         const { client, projectId } = await resolveContext(globals(), context);
-        assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+        assertProjectSelected(projectId);
         await createModel(
           client,
           {
@@ -101,7 +100,7 @@ export const registerModelCommands = (program: Command, host: CommandHost): void
     .description("archive a project Model")
     .action(async (nameOrId: string, options: { json: boolean }) => {
       const { client, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       await archiveModel(client, { projectId, nameOrId, json: options.json }, context.io);
     });
 

package/src/cli/commands/pipeline.ts

@@ -1,8 +1,7 @@
-import { assert } from "es-toolkit";
 import type { Command } from "commander";
 import { estimatePipelineCost } from "../cost";
 import { exitCodeForOutcome, positiveInteger, resolveContext, type CommandHost } from "../context";
-import { MISSING_PROJECT_ID_MESSAGE } from "../project-context";
+import { assertProjectSelected } from "../project-context";
 import {
   cancelPipelineRun,
   listLivePipelines,
@@ -25,7 +24,7 @@ export const registerPipelineCommands = (program: Command, host: CommandHost): v
     .description("list live pipelines in the selected project")
     .action(async (options: { limit?: number }) => {
       const { client, projectId, state } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       const result = await listLivePipelines({
         client,
         projectId,
@@ -42,7 +41,7 @@ export const registerPipelineCommands = (program: Command, host: CommandHost): v
     .description("start a run on a deployed pipeline")
     .action(async (name: string | undefined, options: { wait: boolean; timeout?: number }) => {
       const { client, state, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       const result = await startPipelineRun(client, {
         projectId,
         state,
@@ -60,7 +59,7 @@ export const registerPipelineCommands = (program: Command, host: CommandHost): v
     .description("report the latest run's state and item counts")
     .action(async (name: string | undefined) => {
       const { client, state, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       const result = await pipelineRunStatus(client, {
         projectId,
         state,
@@ -77,7 +76,7 @@ export const registerPipelineCommands = (program: Command, host: CommandHost): v
     .description("list recent runs")
     .action(async (name: string | undefined, options: { limit?: number }) => {
       const { client, state, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       const result = await listPipelineRuns(client, {
         projectId,
         state,
@@ -94,7 +93,7 @@ export const registerPipelineCommands = (program: Command, host: CommandHost): v
     .description("forecast what a run of this pipeline would bill")
     .action(async (name: string | undefined, options: { itemLimit?: number }) => {
       const { client, state, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       const result = await estimatePipelineCost(client, {
         projectId,
         state,

package/src/cli/commands/project.ts

@@ -1,4 +1,3 @@
-import { assert } from "es-toolkit";
 import type { Command } from "commander";
 import { createClient } from "../../client";
 import {
@@ -11,17 +10,9 @@ import {
   type CommandHost,
 } from "../context";
 import { requireStoredCredentials } from "../credentials";
-import {
-  MISSING_PROJECT_ID_MESSAGE,
-  addProject,
-  createProject,
-  currentProject,
-  listRemoteProjects,
-  removeProject,
-  switchProject,
-  untrackProjectResource,
-} from "../project-context";
+import { addProject, assertProjectSelected, createProject, currentProject, listRemoteProjects, removeProject, switchProject, untrackProjectResource } from "../project-context";
 import { readTolokaState } from "../../state";
+import { assertCli } from "../cli-error";
 
 export const registerProjectCommands = (program: Command, host: CommandHost): void => {
   const { context, exitCode, globals } = host;
@@ -97,7 +88,7 @@ export const registerProjectCommands = (program: Command, host: CommandHost): vo
     .description("print the current project URL")
     .action(async () => {
       const { baseUrl, client, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       const live = await client.projects.get({ projectId });
       const url = new URL(
         `/teams/${encodeURIComponent(live.teamId)}/projects/${encodeURIComponent(live.id)}`,
@@ -125,9 +116,10 @@ export const registerProjectCommands = (program: Command, host: CommandHost): vo
     .option("--confirm", "confirm untracking in a non-interactive environment", false)
     .description("remove a pipeline or dataset from local tracking without deleting it")
     .action(async (type: string, name: string, options: { confirm: boolean }) => {
-      assert(
+      assertCli(
         type === "pipeline" || type === "dataset",
         "Resource type must be pipeline or dataset.",
+        { hint: { description: "Run toloka project untrack pipeline <name> or toloka project untrack dataset <name>." } },
       );
       const sourceRoot = await resolveSourceRoot(globals(), context.io);
       await untrackProjectResource({
@@ -144,9 +136,10 @@ export const registerProjectCommands = (program: Command, host: CommandHost): vo
     .option("--name <name>", "platform project name")
     .option("--team-id <id>", "team that owns the project")
     .description("create a live project and select it");
-  if (context.internalUser === true) {
-    create.option("--delivery-order-id <id>", "Sunday delivery order id (internal users only)");
-  }
+  create.option(
+    "--delivery-order-id <id>",
+    "Sunday delivery order id (required when the owning team is internal)",
+  );
   create.action(
     async (
       alias: string | undefined,

package/src/cli/commands/report.ts

@@ -1,8 +1,8 @@
-import { assert } from "es-toolkit";
 import type { Command } from "commander";
 import { authoredByOption, resolveInitRoot, type CommandHost } from "../context";
 import { PRODUCTION_BASE_URL, resolveInternalBaseUrl } from "../config";
 import { submitIssueReport, type IssueReportAuthor } from "../report";
+import { assertCli } from "../cli-error";
 
 export const registerReportCommand = (program: Command, host: CommandHost): void => {
   const { context, exitCode, globals } = host;
@@ -17,7 +17,11 @@ export const registerReportCommand = (program: Command, host: CommandHost): void
         markdownPath: string,
         options: { authoredBy: IssueReportAuthor; confirm: boolean },
       ) => {
-        assert(context.analytics, "Issue reporting requires CLI analytics.");
+        assertCli(
+          context.analytics,
+          "Issue reporting requires CLI analytics.",
+          { hint: { description: "Set TOLOKA_TELEMETRY=1 to enable analytics, then re-run toloka report." } },
+        );
         const sourceRoot = resolveInitRoot(globals());
         const baseUrl =
           globals().baseUrl ??

package/src/cli/commands/secret.ts

@@ -1,8 +1,8 @@
-import { assert } from "es-toolkit";
 import type { Command } from "commander";
 import { resolveContext, type CommandHost } from "../context";
 import { setProjectSecret } from "../data";
-import { MISSING_PROJECT_ID_MESSAGE } from "../project-context";
+import { assertProjectSelected } from "../project-context";
+import { assertCli } from "../cli-error";
 
 export const registerSecretCommands = (program: Command, host: CommandHost): void => {
   const { context, exitCode, globals } = host;
@@ -17,15 +17,16 @@ export const registerSecretCommands = (program: Command, host: CommandHost): voi
     .description("set a secret value without writing it to disk")
     .action(async (name: string, options: { fromEnv?: string }) => {
       const { client, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
 
       const value =
         options.fromEnv === undefined
           ? (await context.io.readStdin()).replace(/\r?\n$/u, "")
           : context.environment[options.fromEnv];
-      assert(
+      assertCli(
         value !== undefined,
         `Missing secret value. Set ${options.fromEnv ?? "the named environment variable"} or pipe it to stdin.`,
+        { hint: { disabled: true } },
       );
 
       try {

package/src/cli/commands/source.ts

@@ -1,4 +1,3 @@
-import { assert } from "es-toolkit";
 import { writeFile } from "node:fs/promises";
 import type { Command } from "commander";
 import {
@@ -12,8 +11,9 @@ import {
 import { resolveContext, resolveInitRoot, resolveSourceRoot, type CommandHost } from "../context";
 import { initProject } from "../init";
 import { applyProject, importProject, planProject, validateProject } from "../project";
-import { MISSING_PROJECT_ID_MESSAGE, resolveProjectContext } from "../project-context";
+import { assertProjectSelected, resolveProjectContext } from "../project-context";
 import { readTolokaState } from "../../state";
+import { assertCli, REPORT_HINT } from "../cli-error";
 
 const runChecksInterruptibly = async (
   options: CheckProjectOptions,
@@ -77,7 +77,7 @@ export const registerSourceCommands = (program: Command, host: CommandHost): voi
         projectId: selectedProjectId,
       } = await resolveContext(globals(), context);
       const id = projectId ?? selectedProjectId;
-      assert(id, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(id);
       const result = await importProject(client, {
         sourceRoot,
         projectId: id,
@@ -192,7 +192,7 @@ export const registerSourceCommands = (program: Command, host: CommandHost): voi
         exitCode.value = checked.exitCode;
         return;
       }
-      assert(checked.source, "Passing checks must return project source");
+      assertCli(checked.source, "Passing checks must return project source", { hint: REPORT_HINT });
       const { client, projectId } = await resolveContext(globals(), context);
       const result = await applyProject(client, {
         sourceRoot,

package/src/cli/commands/status.ts

@@ -1,8 +1,7 @@
-import { assert } from "es-toolkit";
 import type { Command } from "commander";
 import { resolveContext, type CommandHost } from "../context";
 import { projectStatus } from "../project";
-import { MISSING_PROJECT_ID_MESSAGE } from "../project-context";
+import { assertProjectSelected } from "../project-context";
 
 export const registerStatusCommand = (program: Command, host: CommandHost): void => {
   const { context, globals } = host;
@@ -11,7 +10,7 @@ export const registerStatusCommand = (program: Command, host: CommandHost): void
     .description("report project health: live counts and pending source changes")
     .action(async () => {
       const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
-      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      assertProjectSelected(projectId);
       const result = await projectStatus(client, { sourceRoot, projectId });
       context.io.stdout(result.output);
     });