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

package/src/cli/commands/models.ts

@@ -0,0 +1,122 @@
+import { assert } from "es-toolkit";
+import type { Command } from "commander";
+import { resolveContext, type CommandHost } from "../context";
+import {
+  archiveModel,
+  createModel,
+  downloadModelVersion,
+  getBaseModel,
+  getModel,
+  listBaseModels,
+  listModels,
+  listModelVersions,
+  parseBaseModelId,
+} from "../models";
+import { MISSING_PROJECT_ID_MESSAGE } from "../project-context";
+
+export const registerModelCommands = (program: Command, host: CommandHost): void => {
+  const { context, globals } = host;
+
+  const baseModel = program
+    .command("base-model")
+    .description("inspect the global base model catalog");
+  baseModel
+    .command("list")
+    .option("--json", "print JSON", false)
+    .description("list base models")
+    .action(async (options: { json: boolean }) => {
+      const { client } = await resolveContext(globals(), context);
+      await listBaseModels(client, { json: options.json }, context.io);
+    });
+  baseModel
+    .command("get")
+    .argument("<id>", "base model ID")
+    .option("--json", "print JSON", false)
+    .description("show one base model")
+    .action(async (id: string, options: { json: boolean }) => {
+      const { client } = await resolveContext(globals(), context);
+      await getBaseModel(client, { id: parseBaseModelId(id), json: options.json }, context.io);
+    });
+
+  const model = program
+    .command("model")
+    .description("manage project Models and immutable versions");
+  model
+    .command("list")
+    .option("--json", "print JSON", false)
+    .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);
+      await listModels(client, { projectId, json: options.json }, context.io);
+    });
+  model
+    .command("get")
+    .argument("<name-or-id>", "project Model name or ID")
+    .option("--json", "print JSON", false)
+    .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);
+      await getModel(client, { projectId, nameOrId, json: options.json }, context.io);
+    });
+  model
+    .command("versions")
+    .argument("<name-or-id>", "project Model name or ID")
+    .option("--json", "print JSON", false)
+    .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);
+      await listModelVersions(client, { projectId, nameOrId, json: options.json }, context.io);
+    });
+  model
+    .command("create")
+    .argument("<name>", "new Model name")
+    .requiredOption("--base <id>", "base model ID")
+    .option("--description <text>", "Model description")
+    .option("--json", "print JSON", false)
+    .description("create project Model metadata without a Model Version")
+    .action(
+      async (name: string, options: { base: string; description?: string; json: boolean }) => {
+        const { client, projectId } = await resolveContext(globals(), context);
+        assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+        await createModel(
+          client,
+          {
+            projectId,
+            name,
+            description: options.description,
+            baseModelId: parseBaseModelId(options.base),
+            json: options.json,
+          },
+          context.io,
+        );
+      },
+    );
+  model
+    .command("archive")
+    .option("--json", "print JSON", false)
+    .argument("<name-or-id>", "project Model name or ID")
+    .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);
+      await archiveModel(client, { projectId, nameOrId, json: options.json }, context.io);
+    });
+
+  const modelVersion = model.command("version").description("manage one immutable Model Version");
+  modelVersion
+    .command("download")
+    .argument("<model-version>", "Model Version ID or Model@name")
+    .requiredOption("--out <directory>", "output directory")
+    .description("download and verify Model Version content")
+    .action(async (modelVersionId: string, options: { out: string }) => {
+      const { client, projectId } = await resolveContext(globals(), context);
+      await downloadModelVersion(
+        client,
+        { projectId, modelVersionId, out: options.out },
+        context.io,
+      );
+    });
+};

package/src/cli/commands/pipeline.ts

@@ -0,0 +1,132 @@
+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 {
+  cancelPipelineRun,
+  listLivePipelines,
+  listPipelineRuns,
+  pipelineRunResults,
+  pipelineRunStatus,
+  startPipelineRun,
+} from "../runs";
+
+export const registerPipelineCommands = (program: Command, host: CommandHost): void => {
+  const { context, exitCode, globals } = host;
+  const pipelineNameHelp =
+    "pipeline name or id; required unless a TTY picker can choose among several";
+  const pipeline = program
+    .command("pipeline")
+    .description("operate on a live pipeline in the selected project");
+  pipeline
+    .command("list")
+    .option("--limit <n>", "maximum pipelines to list", positiveInteger)
+    .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);
+      const result = await listLivePipelines({
+        client,
+        projectId,
+        state,
+        ...(options.limit === undefined ? {} : { limit: options.limit }),
+      });
+      context.io.stdout(result.output);
+    });
+  pipeline
+    .command("run")
+    .argument("[name]", pipelineNameHelp)
+    .option("--wait", "wait for the run to reach a terminal state", false)
+    .option("--timeout <ms>", "how long to wait", positiveInteger)
+    .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);
+      const result = await startPipelineRun(client, {
+        projectId,
+        state,
+        ...(name === undefined ? {} : { pipeline: name }),
+        wait: options.wait,
+        ...(options.timeout === undefined ? {} : { timeoutMs: options.timeout }),
+        ...(context.io.select === undefined ? {} : { select: context.io.select }),
+      });
+      context.io.stdout(result.output);
+      exitCode.value = exitCodeForOutcome(result.outcome);
+    });
+  pipeline
+    .command("status")
+    .argument("[name]", pipelineNameHelp)
+    .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);
+      const result = await pipelineRunStatus(client, {
+        projectId,
+        state,
+        ...(name === undefined ? {} : { pipeline: name }),
+        ...(context.io.select === undefined ? {} : { select: context.io.select }),
+      });
+      context.io.stdout(result.output);
+      exitCode.value = exitCodeForOutcome(result.outcome);
+    });
+  pipeline
+    .command("runs")
+    .argument("[name]", pipelineNameHelp)
+    .option("--limit <n>", "how many runs to list", positiveInteger)
+    .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);
+      const result = await listPipelineRuns(client, {
+        projectId,
+        state,
+        ...(name === undefined ? {} : { pipeline: name }),
+        ...(options.limit === undefined ? {} : { limit: options.limit }),
+        ...(context.io.select === undefined ? {} : { select: context.io.select }),
+      });
+      context.io.stdout(result.output);
+    });
+  pipeline
+    .command("cost")
+    .argument("[name]", pipelineNameHelp)
+    .option("--item-limit <n>", "cap how many items to price", positiveInteger)
+    .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);
+      const result = await estimatePipelineCost(client, {
+        projectId,
+        state,
+        ...(name === undefined ? {} : { pipeline: name }),
+        ...(options.itemLimit === undefined ? {} : { itemLimit: options.itemLimit }),
+        ...(context.io.select === undefined ? {} : { select: context.io.select }),
+      });
+      context.io.stdout(result.output);
+    });
+  pipeline
+    .command("cancel")
+    .argument("<runId>", "run to cancel")
+    .description("request cancellation of a run")
+    .action(async (runId: string) => {
+      const { client } = await resolveContext(globals(), context);
+      const result = await cancelPipelineRun(client, { runId });
+      context.io.stdout(result.output);
+    });
+  pipeline
+    .command("results")
+    .argument("<runId>", "run to read")
+    .option("--limit <n>", "how many items to scan", positiveInteger)
+    .option("--failed", "only report failed items", false)
+    .description("report a run's items")
+    .action(async (runId: string, options: { limit?: number; failed: boolean }) => {
+      const { client } = await resolveContext(globals(), context);
+      const result = await pipelineRunResults(client, {
+        runId,
+        failedOnly: options.failed,
+        ...(options.limit === undefined ? {} : { limit: options.limit }),
+      });
+      context.io.stdout(result.output);
+      exitCode.value = exitCodeForOutcome(result.outcome);
+    });
+};

package/src/cli/commands/project.ts

@@ -0,0 +1,175 @@
+import { assert } from "es-toolkit";
+import type { Command } from "commander";
+import { createClient } from "../../client";
+import {
+  identifyClientUser,
+  positiveInteger,
+  readCommandCredentials,
+  resolveContext,
+  resolveSelectedProject,
+  resolveSourceRoot,
+  type CommandHost,
+} from "../context";
+import { requireStoredCredentials } from "../credentials";
+import {
+  MISSING_PROJECT_ID_MESSAGE,
+  addProject,
+  createProject,
+  currentProject,
+  listRemoteProjects,
+  removeProject,
+  switchProject,
+  untrackProjectResource,
+} from "../project-context";
+import { readTolokaState } from "../../state";
+
+export const registerProjectCommands = (program: Command, host: CommandHost): void => {
+  const { context, exitCode, globals } = host;
+  const project = program
+    .command("project")
+    .description("select and manage the current platform project");
+  project
+    .command("list")
+    .option("--limit <n>", "maximum projects to list", positiveInteger)
+    .description("list remote projects this key can see")
+    .action(async (options: { limit?: number }) => {
+      const flags = globals();
+      const { client, stored, state } = await resolveContext(flags, context);
+      const selected = resolveSelectedProject(flags, context, stored, state);
+      await listRemoteProjects({
+        client,
+        io: context.io,
+        ...(selected === undefined ? {} : { context: selected }),
+        ...(options.limit === undefined ? {} : { limit: options.limit }),
+      });
+    });
+  project
+    .command("add")
+    .argument("[alias]", "local name for this project")
+    .argument("[projectId]", "platform project id")
+    .description("register a live project and select it")
+    .action(async (alias?: string, projectId?: string) => {
+      const flags = globals();
+      const found = await requireStoredCredentials(context.environment);
+      const client = context.injectedClient ?? createClient(found.credentials);
+      await addProject({
+        environment: context.environment,
+        flags,
+        client,
+        io: context.io,
+        afterPreflight: async () => identifyClientUser(client, context.analytics),
+        ...(alias === undefined ? {} : { alias }),
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+    });
+
+  project
+    .command("switch")
+    .argument("<alias>", "local project alias")
+    .description("select a registered project")
+    .action(async (alias: string) => {
+      await switchProject({
+        environment: context.environment,
+        flags: globals(),
+        alias,
+        io: context.io,
+      });
+    });
+  project
+    .command("current")
+    .description("show the project this command would use")
+    .action(async () => {
+      const flags = globals();
+      const stored = await readCommandCredentials(flags, context);
+      const sourceRoot = await resolveSourceRoot(flags, context.io);
+      const state = await readTolokaState(sourceRoot);
+      const result = currentProject({
+        flags,
+        environment: context.environment,
+        stored,
+        ...(state === undefined ? {} : { state }),
+        io: context.io,
+      });
+      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")
+    .argument("<alias>", "local project alias")
+    .description("forget a local project alias")
+    .action(async (alias: string) => {
+      await removeProject({
+        environment: context.environment,
+        flags: globals(),
+        alias,
+        io: context.io,
+      });
+    });
+  project
+    .command("untrack")
+    .argument("<type>", "pipeline or dataset")
+    .argument("<name>", "tracked resource name")
+    .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(
+        type === "pipeline" || type === "dataset",
+        "Resource type must be pipeline or dataset.",
+      );
+      const sourceRoot = await resolveSourceRoot(globals(), context.io);
+      await untrackProjectResource({
+        sourceRoot,
+        type,
+        name,
+        confirm: options.confirm,
+        io: context.io,
+      });
+    });
+  const create = project
+    .command("create")
+    .argument("[alias]", "local name for the new project")
+    .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.action(
+    async (
+      alias: string | undefined,
+      options: { name?: string; teamId?: string; deliveryOrderId?: string },
+    ) => {
+      const flags = globals();
+      const found = await requireStoredCredentials(context.environment);
+      const client = context.injectedClient ?? createClient(found.credentials);
+      const sourceRoot = await resolveSourceRoot(flags, context.io);
+      await createProject({
+        environment: context.environment,
+        flags,
+        client,
+        io: context.io,
+        sourceRoot,
+        afterPreflight: async () => identifyClientUser(client, context.analytics),
+        ...(alias === undefined ? {} : { alias }),
+        ...(options.name === undefined ? {} : { name: options.name }),
+        ...(options.teamId === undefined ? {} : { teamId: options.teamId }),
+        ...(options.deliveryOrderId === undefined
+          ? {}
+          : { deliveryOrderId: options.deliveryOrderId }),
+      });
+    },
+  );
+};

package/src/cli/commands/report.ts

@@ -0,0 +1,39 @@
+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";
+
+export const registerReportCommand = (program: Command, host: CommandHost): void => {
+  const { context, exitCode, globals } = host;
+  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.TOLOKA_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,
+        });
+      },
+    );
+};

package/src/cli/commands/secret.ts

@@ -0,0 +1,39 @@
+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";
+
+export const registerSecretCommands = (program: Command, host: CommandHost): void => {
+  const { context, exitCode, globals } = host;
+  const secret = program.command("secret").description("manage project secrets");
+  secret
+    .command("set")
+    .argument("<name>", "secret name referenced by a code node")
+    .option(
+      "--from-env <variable>",
+      "read the value from this environment variable instead of stdin",
+    )
+    .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);
+
+      const value =
+        options.fromEnv === undefined
+          ? (await context.io.readStdin()).replace(/\r?\n$/u, "")
+          : context.environment[options.fromEnv];
+      assert(
+        value !== undefined,
+        `Missing secret value. Set ${options.fromEnv ?? "the named environment variable"} or pipe it to stdin.`,
+      );
+
+      try {
+        const result = await setProjectSecret(client, { projectId, name, value });
+        context.io.stdout(result.output);
+      } catch {
+        context.io.stderr(`Failed to set secret ${name}.`);
+        exitCode.value = 1;
+      }
+    });
+};

package/src/cli/commands/skill.ts

@@ -0,0 +1,36 @@
+import type { Command } from "commander";
+import { resolveSourceRoot, type CommandHost } from "../context";
+import { skillInstallCommand, skillListCommand, skillSearchCommand } from "../skill";
+
+export const registerSkillCommands = (program: Command, host: CommandHost): void => {
+  const { context, globals } = host;
+  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 });
+    });
+};