@toloka-platform/sdk 0.1.0-preview.3 → 0.1.0-preview.5

package/src/cli/program.ts

@@ -4,14 +4,13 @@ import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { createClient } from "../client";
 import type { PotatoClient } from "../client";
-import { PotatoApiError } from "../errors";
 import { readTolokaState } from "../state";
 import type { TolokaState } from "../state";
 import { authStatus, login, logout } from "./auth";
 import type { AuthPrompt } from "./auth";
 import { commandNameFromArgv, createCliAnalytics } from "./analytics";
 import type { CliAnalytics, CliAnalyticsCommandOutcome } from "./analytics";
-import { PRODUCTION_BASE_URL, resolveTolokaConfig } from "./config";
+import { PRODUCTION_BASE_URL, resolveInternalBaseUrl, resolveTolokaConfig } from "./config";
 import type { TolokaEnvironment } from "./config";
 import {
   findCommandCredentials,
@@ -26,7 +25,7 @@ import {
   setProjectSecret,
   uploadDataset,
 } from "./data";
-import { initProject, readAgentSkillStalenessWarning } from "./init";
+import { SDK_VERSION, initProject, readAgentSkillStalenessWarning } from "./init";
 import {
   applyProject,
   importProject,
@@ -45,6 +44,9 @@ import {
   switchProject,
 } from "./project-context";
 import { estimatePipelineCost } from "./cost";
+import { submitIssueReport } from "./report";
+import type { IssueReportAuthor } from "./report";
+import { formatCliError } from "./format-error";
 import {
   cancelPipelineRun,
   listLivePipelines,
@@ -56,6 +58,7 @@ import {
 } from "./runs";
 
 import type { RunOutcome } from "./runs";
+import { skillInstallCommand, skillListCommand, skillSearchCommand } from "./skill";
 import { findSourceRoot } from "./source";
 
 export type CliIo = {
@@ -88,6 +91,12 @@ const CREDENTIAL_PRECEDENCE = [
   `The platform defaults to ${PRODUCTION_BASE_URL}.`,
 ].join("\n");
 
+const authoredByOption = (raw: string): IssueReportAuthor => {
+  if (raw !== "human" && raw !== "agent")
+    throw new InvalidArgumentError('Expected "human" or "agent".');
+  return raw;
+};
+
 const positiveInteger = (raw: string): number => {
   const value = Number(raw);
   if (!Number.isInteger(value) || value <= 0)
@@ -104,6 +113,7 @@ const exitCodeForOutcome = (outcome: RunOutcome): number => {
 type Resolved = {
   readonly sourceRoot: string;
   readonly client: PotatoClient;
+  readonly baseUrl: string;
   readonly state: TolokaState | undefined;
   readonly stored: StoredCredentials | undefined;
   readonly projectId?: string;
@@ -154,6 +164,7 @@ const resolveContext = async (
   return {
     sourceRoot,
     client,
+    baseUrl: config.baseUrl,
     state,
     stored,
     ...(config.projectId === undefined ? {} : { projectId: config.projectId }),
@@ -187,6 +198,7 @@ export function createProgram(context: ProgramContext): CreatedProgram {
     .description(
       "Preview. Build and operate Toloka pipeline projects from TypeScript source. The public API may change.",
     )
+    .version(SDK_VERSION, "-v, --version", "output the current version")
     .option(
       "--source-root <directory>",
       "project root; discovered from the working directory when omitted",
@@ -203,19 +215,30 @@ export function createProgram(context: ProgramContext): CreatedProgram {
 
   const globals = (): GlobalOptions => program.opts<GlobalOptions>();
 
-  program.hook("postAction", async (thisCommand) => {
+  program.hook("postAction", async (_thisCommand, actionCommand) => {
     if (warnedAboutStaleSkills) return;
     const commandNames = [];
-    for (let current: Command | null = thisCommand; current !== null; current = current.parent) {
+    for (let current: Command | null = actionCommand; current !== null; current = current.parent) {
       commandNames.push(current.name());
     }
-    if (commandNames.includes("init") || commandNames.includes("help")) return;
+    if (
+      commandNames.includes("init") ||
+      commandNames.includes("help") ||
+      commandNames.includes("report") ||
+      commandNames.includes("url") ||
+      commandNames.includes("version")
+    )
+      return;
     const sourceRoot = await resolveSourceRoot(globals(), context.io);
     const warning = await readAgentSkillStalenessWarning(sourceRoot).catch(() => undefined);
     if (warning === undefined) return;
     warnedAboutStaleSkills = true;
     context.io.stderr(warning);
   });
+  program
+    .command("version")
+    .description("print the current CLI version")
+    .action(() => context.io.stdout(SDK_VERSION));
 
   program
     .command("login")
@@ -351,6 +374,19 @@ export function createProgram(context: ProgramContext): CreatedProgram {
       });
       if (result.project === undefined) exitCode.value = 1;
     });
+  project
+    .command("url")
+    .description("print the current project URL")
+    .action(async () => {
+      const { baseUrl, client, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      const live = await client.projects.get({ projectId });
+      const url = new URL(
+        `/teams/${encodeURIComponent(live.teamId)}/projects/${encodeURIComponent(live.id)}`,
+        baseUrl,
+      );
+      context.io.stdout(url.href);
+    });
 
   project
     .command("remove")
@@ -390,7 +426,7 @@ export function createProgram(context: ProgramContext): CreatedProgram {
 
   program
     .command("init")
-    .description("initialize this project directory and install agent skills")
+    .description("initialize this project directory and install the agent bootstrap")
     .action(async () => {
       const flags = globals();
       const sourceRoot = resolveInitRoot(flags);
@@ -677,6 +713,66 @@ export function createProgram(context: ProgramContext): CreatedProgram {
       const result = await projectStatus(client, { sourceRoot, projectId });
       context.io.stdout(result.output);
     });
+  program
+    .command("report")
+    .argument("<markdownPath>", "path to a UTF-8 Markdown report")
+    .option("--authored-by <who>", "human or agent", authoredByOption, "human")
+    .option("--confirm", "confirm submission in a non-interactive environment", false)
+    .description("preview and send an issue report to Toloka through PostHog")
+    .action(
+      async (
+        markdownPath: string,
+        options: { authoredBy: IssueReportAuthor; confirm: boolean },
+      ) => {
+        assert(context.analytics, "Issue reporting requires CLI analytics.");
+        const sourceRoot = resolveInitRoot(globals());
+        const baseUrl =
+          globals().baseUrl ??
+          context.environment.POTATO_BASE_URL ??
+          resolveInternalBaseUrl(context.environment) ??
+          PRODUCTION_BASE_URL;
+        exitCode.value = await submitIssueReport({
+          path: markdownPath,
+          authoredBy: options.authoredBy,
+          platform: new URL(baseUrl).origin,
+          confirm: options.confirm,
+          sourceRoot,
+          cwd: process.cwd(),
+          analytics: context.analytics,
+          io: context.io,
+        });
+      },
+    );
+
+  const skill = program
+    .command("skill")
+    .description("discover bundled agent skills and install them into .agents/skills");
+  skill
+    .command("list")
+    .option("--json", "print Skill Descriptors with their status as JSON", false)
+    .description("list bundled skills as not-installed, current, or stale")
+    .action(async (options: { json: boolean }) => {
+      const sourceRoot = await resolveSourceRoot(globals(), context.io);
+      await skillListCommand({ sourceRoot, json: options.json, io: context.io });
+    });
+  skill
+    .command("search")
+    .argument("<query>", "text matched case-insensitively against id, name, description, and tags")
+    .option("--json", "print matching Skill Descriptors with their status as JSON", false)
+    .description("find bundled skills for a task")
+    .action(async (query: string, options: { json: boolean }) => {
+      const sourceRoot = await resolveSourceRoot(globals(), context.io);
+      await skillSearchCommand({ sourceRoot, query, json: options.json, io: context.io });
+    });
+  skill
+    .command("install")
+    .argument("<skillId>", "skill id from toloka skill list")
+    .option("-f, --force", "replace an existing .agents/skills/<skillId> directory", false)
+    .description("copy one bundled skill into .agents/skills/<skillId>")
+    .action(async (skillId: string, options: { force: boolean }) => {
+      const sourceRoot = await resolveSourceRoot(globals(), context.io);
+      await skillInstallCommand({ sourceRoot, skillId, force: options.force, io: context.io });
+    });
 
   return { program, exitCode };
 }
@@ -785,20 +881,6 @@ type CommandResult = {
   readonly outcome: CliAnalyticsCommandOutcome;
   readonly error?: unknown;
 };
-const formatCliError = (error: unknown): string => {
-  if (error instanceof PotatoApiError) {
-    const details =
-      typeof error.body === "string"
-        ? error.body
-        : error.body === undefined
-          ? undefined
-          : JSON.stringify(error.body);
-    return details === undefined || details.length === 0
-      ? error.message
-      : `${error.message}\n${details}`;
-  }
-  return error instanceof Error ? error.message : String(error);
-};
 
 const runProgram = async (
   program: Command,

package/src/cli/report.ts

@@ -0,0 +1,144 @@
+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";
+
+export type IssueReportAuthor = "human" | "agent";
+
+type IssueReportIo = {
+  readonly stdout: (text: string) => void;
+  readonly stderr: (text: string) => void;
+  readonly prompt?: (question: string) => Promise<string>;
+};
+
+const ISSUE_REPORT_MAX_BYTES = 256 * 1024;
+const REPORT_DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+const assertNoSymlinkParents = async (absolutePath: string, sourceRoot: string): Promise<void> => {
+  const relativePath = relative(sourceRoot, absolutePath);
+  if (
+    relativePath === "" ||
+    relativePath === ".." ||
+    relativePath.startsWith(`..${sep}`) ||
+    isAbsolute(relativePath)
+  ) {
+    return;
+  }
+
+  const segments = relativePath.split(sep);
+  for (let index = 1; index < segments.length; index += 1) {
+    const directory = join(sourceRoot, ...segments.slice(0, index));
+    const stats = await lstat(directory);
+    assert(
+      !stats.isSymbolicLink(),
+      `Report file ${absolutePath} is inside the symbolic link ${directory}; select a path that does not traverse symbolic links.`,
+    );
+  }
+};
+
+const openReportFile = async (
+  path: string,
+  sourceRoot: string,
+  cwd: string,
+): Promise<{ handle: FileHandle; absolutePath: string; size: number }> => {
+  const absolutePath = resolve(cwd, path);
+  await assertNoSymlinkParents(absolutePath, sourceRoot);
+  let handle: FileHandle;
+  try {
+    handle = await open(absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+  } catch (error) {
+    assert(
+      !(error instanceof Error && "code" in error && error.code === "ELOOP"),
+      `Report file ${absolutePath} is a symbolic link; select the file it points to directly.`,
+    );
+    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(
+      stats.size <= ISSUE_REPORT_MAX_BYTES,
+      `Report file ${absolutePath} is ${stats.size} bytes; the limit is 256 KiB.`,
+    );
+    return { handle, absolutePath, size: stats.size };
+  } catch (error) {
+    await handle.close();
+    throw error;
+  }
+};
+
+const readReportText = async (path: string, sourceRoot: string, cwd: string): Promise<string> => {
+  const opened = await openReportFile(path, sourceRoot, cwd);
+  try {
+    const bytes = await opened.handle.readFile();
+    assert(
+      bytes.byteLength === opened.size,
+      `${opened.absolutePath} changed while it was being read.`,
+    );
+    try {
+      return REPORT_DECODER.decode(bytes);
+    } catch {
+      throw new Error(`Report file ${opened.absolutePath} is not valid UTF-8.`);
+    }
+  } finally {
+    await opened.handle.close();
+  }
+};
+
+const confirmed = async (io: IssueReportIo, confirm: boolean): Promise<boolean> => {
+  if (confirm) return true;
+  if (io.prompt === undefined) return false;
+  const answer = (await io.prompt("Send this report to Toloka? [y/N] ")).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
+};
+
+export async function submitIssueReport(options: {
+  readonly path: string;
+  readonly authoredBy: IssueReportAuthor;
+  readonly platform: string;
+  readonly confirm: boolean;
+  readonly sourceRoot: string;
+  readonly cwd: string;
+  readonly analytics: CliAnalytics;
+  readonly io: IssueReportIo;
+}): Promise<number> {
+  const { analytics, io } = options;
+  assert(
+    analytics.issueReportingEnabled,
+    "Issue reporting is disabled. Re-run with TOLOKA_TELEMETRY=1.",
+  );
+  const reportText = await readReportText(options.path, options.sourceRoot, options.cwd);
+  io.stdout("Issue report preview:");
+  io.stdout("");
+  io.stdout(
+    reportText.replace(
+      /(?![\t\n])(?!\r\n)(?:\p{Cc}|\p{Bidi_Control})/gu,
+      (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`,
+    ),
+  );
+  io.stdout("");
+  io.stdout(`Authored by: ${options.authoredBy}`);
+  io.stdout(`Platform: ${options.platform}`);
+  io.stdout("");
+
+  if (!(await confirmed(io, options.confirm))) {
+    io.stderr(
+      "Refusing to submit without confirmation in a non-interactive environment. Pass --confirm after reviewing the preview above.",
+    );
+    return 1;
+  }
+
+  const reportId = randomUUID();
+  await analytics.submitIssueReport({
+    reportId,
+    reportText,
+    authoredBy: options.authoredBy,
+    platform: options.platform,
+  });
+  io.stdout(`Submitted issue report: ${reportId}`);
+  return 0;
+}