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

package/src/cli/analytics.ts

@@ -8,7 +8,7 @@ import type { TolokaEnvironment } from "./config";
 import type { CliEnvironment } from "./credentials";
 import { credentialsPath, preparePrivateFilePath } from "./credentials";
 import { isFalseyFlag, isTruthyFlag } from "./boolean-flag";
-import { SDK_VERSION } from "./init";
+import { SDK_VERSION } from "./sdk-version";
 
 export const POSTHOG_PROJECT_KEY = "phc_kqHt0f53B5MVqURyzWpW1aNlbOmYt1YbUYza0JPcg19";
 export const POSTHOG_HOST = "https://eu.posthog.com";
@@ -56,6 +56,11 @@ export type PosthogLike = {
     properties?: Record<string, unknown>;
     disableGeoip: boolean;
   }) => void;
+  captureException: (
+    error: unknown,
+    distinctId: string,
+    properties?: Record<string, unknown>,
+  ) => void;
   alias: (event: { distinctId: string; alias: string }) => void;
   flush: () => Promise<void>;
   on?: (event: "error", listener: (error: Error) => void) => void;
@@ -84,6 +89,7 @@ const COMMAND_GROUPS: Readonly<Record<string, Readonly<Record<string, true>>>> =
     results: true,
   },
   dataset: { list: true, fields: true, load: true, upload: true },
+  "delivery-order": { list: true },
   secret: { set: true },
   skill: { list: true, search: true, install: true },
   config: { get: true, set: true },
@@ -136,14 +142,34 @@ export function commandNameFromArgv(argv: readonly string[]): string {
   return nameFromTokens(tokens);
 }
 
+const findPotatoApiError = (error: unknown): PotatoApiError | undefined => {
+  if (error instanceof PotatoApiError) return error;
+
+  if (error instanceof AggregateError) {
+    for (const nested of error.errors) {
+      const apiError = findPotatoApiError(nested);
+      if (apiError !== undefined) return apiError;
+    }
+  }
+
+  return error instanceof Error ? findPotatoApiError(error.cause) : undefined;
+};
+
 export function classifyCliError(error: unknown): { readonly error_code: string } {
   if (error === undefined) return { error_code: "command_failed" };
-  if (error instanceof PotatoApiError || error instanceof PipelineGraphValidationError) {
-    return { error_code: error.code };
-  }
+  const apiError = findPotatoApiError(error);
+  if (apiError !== undefined) return { error_code: apiError.code };
+  if (error instanceof PipelineGraphValidationError) return { error_code: error.code };
   return { error_code: error instanceof Error ? "error" : "unknown" };
 }
 
+const cliErrorProperties = (error: unknown): Record<string, unknown> => {
+  const apiError = findPotatoApiError(error);
+  return apiError === undefined
+    ? {}
+    : { status_code: apiError.status, request_id: apiError.requestId };
+};
+
 const anonymousIdPath = (environment: CliEnvironment): string =>
   join(dirname(credentialsPath(environment)), "anonymous-id");
 
@@ -237,18 +263,38 @@ export function createCliAnalytics(options: {
         .then(() => {
           if (client === undefined || distinctId === undefined) return;
           const shared = sharedProperties();
+          const command = nameFromTokens(event.command.split(" "));
+
           if (event.outcome === "failed") {
             const classified = classifyCliError(event.error);
+            const errorProperties = cliErrorProperties(event.error);
+
+            if (event.error !== undefined) {
+              const exception = new Error(`CLI command failed: ${classified.error_code}`);
+              exception.name = "PotatoCliError";
+              client.captureException(exception, distinctId, {
+                ...shared,
+                command,
+                duration_ms: event.durationMs,
+                exit_code: event.exitCode,
+                $process_person_profile: false,
+                $geoip_disable: true,
+                ...classified,
+                ...errorProperties,
+              });
+            }
+
             client.capture({
               distinctId,
               event: "sdk_cli_command_failed",
               disableGeoip: true,
               properties: {
                 ...shared,
-                command: nameFromTokens(event.command.split(" ")),
+                command,
                 duration_ms: event.durationMs,
                 exit_code: event.exitCode,
                 ...classified,
+                ...errorProperties,
               },
             });
             return;
@@ -259,7 +305,7 @@ export function createCliAnalytics(options: {
             disableGeoip: true,
             properties: {
               ...shared,
-              command: nameFromTokens(event.command.split(" ")),
+              command,
               duration_ms: event.durationMs,
               exit_code: event.exitCode,
               outcome: event.outcome,

package/src/cli/auth.ts

@@ -1,5 +1,6 @@
 import { assert } from "es-toolkit";
 import { createClient } from "../client";
+import { PotatoApiError } from "../errors";
 import { PRODUCTION_BASE_URL, consoleUrlFor, resolveInternalBaseUrl } from "./config";
 import {
   clearStoredCredentials,
@@ -19,6 +20,40 @@ import type {
 import type { ProjectContext } from "./project-context";
 import { formatProjectContextLine } from "./project-context";
 
+type ProbeFailureKind = "rejected" | "unreachable" | "platform";
+
+type ProbeFailure = { readonly kind: ProbeFailureKind; readonly reason: string };
+
+const classifyProbeFailure = (error: unknown): ProbeFailure => {
+  const reason = error instanceof Error ? error.message : String(error);
+  if (!(error instanceof PotatoApiError) || error.status === undefined)
+    return { kind: "unreachable", reason };
+  return {
+    kind: error.status === 401 || error.status === 403 ? "rejected" : "platform",
+    reason,
+  };
+};
+
+const PROBE_FAILURE_HEADLINE: Record<ProbeFailureKind, string> = {
+  rejected: "Rejected",
+  unreachable: "Not reachable",
+  platform: "Platform error",
+};
+
+const LOGIN_FAILURE_ADVICE: Record<ProbeFailureKind, (baseUrl: string) => string> = {
+  rejected: () => "Check that the key was copied whole and has not been revoked.",
+  unreachable: (baseUrl) =>
+    `${baseUrl} did not answer, so the key was not evaluated. Check network access, VPN, or proxy settings and retry.`,
+  platform: () => "The platform failed before confirming the key. Retry later.",
+};
+
+const STATUS_FAILURE_ADVICE: Record<ProbeFailureKind, (baseUrl: string) => string> = {
+  rejected: () => "Run toloka login to store a working key.",
+  unreachable: (baseUrl) =>
+    `Check network access to ${baseUrl}; the stored key was not evaluated.`,
+  platform: () => "The platform failed before confirming the key. Retry later.",
+};
+
 export const apiKeyInstructions = (baseUrl: string): string => {
   const console = consoleUrlFor(baseUrl);
   const where =
@@ -54,6 +89,7 @@ export type AuthProbe = {
       readonly pagination: { readonly total: number };
     }>;
   };
+  readonly me?: () => Promise<{ readonly internal: boolean }>;
 };
 
 export type LoginOptions = {
@@ -76,16 +112,16 @@ export async function login(options: LoginOptions = {}): Promise<LoginResult> {
   const write = options.write ?? (() => undefined);
   const baseUrl = normalizeBaseUrl(
     options.baseUrl ??
-      environment.POTATO_BASE_URL ??
+      environment.TOLOKA_BASE_URL ??
       resolveInternalBaseUrl(environment) ??
       PRODUCTION_BASE_URL,
   );
 
-  let apiKey = options.apiKey ?? environment.POTATO_API_KEY;
+  let apiKey = options.apiKey ?? environment.TOLOKA_API_KEY;
   if (apiKey === undefined) {
     assert(
       options.prompt,
-      "Missing API key. Pass --api-key, or set POTATO_API_KEY, when stdin is not a terminal.",
+      "Missing API key. Without a terminal, pipe the key to toloka login --api-key-stdin, pass --api-key, or set TOLOKA_API_KEY.",
     );
     write(`\n${apiKeyInstructions(baseUrl)}\n`);
     apiKey = (await options.prompt("API key: ", { mask: true })).trim();
@@ -99,12 +135,12 @@ export async function login(options: LoginOptions = {}): Promise<LoginResult> {
     const page = await probe.projects.listPage({ limit: 1 });
     reachable = `Authenticated against ${baseUrl}: ${page.pagination.total} project(s) visible.`;
   } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
+    const failure = classifyProbeFailure(error);
     throw new Error(
       [
-        `Could not authenticate against ${baseUrl}: ${reason}`,
+        `Could not authenticate against ${baseUrl}: ${failure.reason}`,
         "",
-        "Nothing was saved. Check that the key was copied whole and has not been revoked.",
+        `Nothing was saved. ${LOGIN_FAILURE_ADVICE[failure.kind](baseUrl)}`,
       ].join("\n"),
       { cause: error },
     );
@@ -136,7 +172,7 @@ export async function login(options: LoginOptions = {}): Promise<LoginResult> {
       reachable,
       `Saved credentials to ${credentialsFile}.`,
       "",
-      "toloka reads them automatically. --api-key and POTATO_API_KEY still win when set.",
+      "toloka reads them automatically. --api-key and TOLOKA_API_KEY still win when set.",
     ].join("\n"),
   };
 }
@@ -183,9 +219,9 @@ const resolveApiKey = (
     options.flagApiKey === undefined
       ? undefined
       : { value: options.flagApiKey, source: "from --api-key" },
-    environment.POTATO_API_KEY === undefined
+    environment.TOLOKA_API_KEY === undefined
       ? undefined
-      : { value: environment.POTATO_API_KEY, source: "from POTATO_API_KEY" },
+      : { value: environment.TOLOKA_API_KEY, source: "from TOLOKA_API_KEY" },
     found === undefined
       ? undefined
       : { value: found.credentials.apiKey, source: `stored in ${storedPath}` },
@@ -202,9 +238,9 @@ const resolvePlatform = (
       options.flagBaseUrl === undefined
         ? undefined
         : { value: options.flagBaseUrl.replace(/\/+$/u, ""), source: "from --base-url" },
-      environment.POTATO_BASE_URL === undefined
+      environment.TOLOKA_BASE_URL === undefined
         ? undefined
-        : { value: environment.POTATO_BASE_URL, source: "from POTATO_BASE_URL" },
+        : { value: environment.TOLOKA_BASE_URL, source: "from TOLOKA_BASE_URL" },
       internalBaseUrl === undefined
         ? undefined
         : { value: internalBaseUrl, source: `from ENV=${environment.ENV}` },
@@ -213,11 +249,21 @@ const resolvePlatform = (
   );
 };
 
+const internalStatusLine = async (probe: AuthProbe): Promise<string | undefined> => {
+  if (probe.me === undefined) return undefined;
+  try {
+    const me = await probe.me();
+    return `Internal: ${me.internal}`;
+  } catch {
+    return undefined;
+  }
+};
+
 export async function authStatus(options: AuthStatusOptions = {}): Promise<AuthStatusResult> {
   const environment = options.environment ?? process.env;
   const credentialLookup =
     options.credentialLookup ??
-    (await findCommandCredentials(environment, options.flagApiKey ?? environment.POTATO_API_KEY));
+    (await findCommandCredentials(environment, options.flagApiKey ?? environment.TOLOKA_API_KEY));
   const { found, warning } = credentialLookup;
   const storedPath = found?.path ?? credentialsPath(environment);
   const apiKey = resolveApiKey(options, environment, found, storedPath);
@@ -244,8 +290,8 @@ export async function authStatus(options: AuthStatusOptions = {}): Promise<AuthS
     projectLine,
   );
 
-  if (environment.POTATO_API_KEY !== undefined && found !== undefined) {
-    lines.push("", `POTATO_API_KEY is set, so the key stored in ${found.path} is ignored.`);
+  if (environment.TOLOKA_API_KEY !== undefined && found !== undefined) {
+    lines.push("", `TOLOKA_API_KEY is set, so the key stored in ${found.path} is ignored.`);
   }
   if (found?.legacy === true) {
     lines.push(
@@ -260,10 +306,17 @@ export async function authStatus(options: AuthStatusOptions = {}): Promise<AuthS
   try {
     const page = await probe.projects.listPage({ limit: 1 });
     lines.push("", `Reachable: ${page.pagination.total} project(s) visible.`);
+    const internalLine = await internalStatusLine(probe);
+    if (internalLine !== undefined) lines.push(internalLine);
     return { authenticated: true, output: lines.join("\n") };
   } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
-    lines.push("", `Not reachable: ${reason}`, "", "Run toloka login to store a working key.");
+    const failure = classifyProbeFailure(error);
+    lines.push(
+      "",
+      `${PROBE_FAILURE_HEADLINE[failure.kind]}: ${failure.reason}`,
+      "",
+      STATUS_FAILURE_ADVICE[failure.kind](baseUrl),
+    );
     return { authenticated: false, output: lines.join("\n") };
   }
 }

package/src/cli/auto-update.ts

@@ -6,16 +6,20 @@ import { join, sep } from "node:path";
 import { findCliEntry } from "./cli-entry";
 import type { CliEnvironment } from "./credentials";
 import { configDirectory, preparePrivateFilePath } from "./credentials";
-import { SDK_VERSION } from "./init";
+import {
+  compareSdkVersions,
+  releaseChannelFor,
+  SDK_PACKAGE_NAME,
+  SDK_VERSION,
+  type ReleaseChannel,
+} from "./sdk-version";
 import { commandNameFromArgv } from "./analytics";
 import { readCliSettings } from "./settings";
 import { CHECK_RESULT_FILE_ENV } from "./check";
 import { isFalseyFlag, isTruthyFlag } from "./boolean-flag";
-import packageMetadata from "../../package.json" with { type: "json" };
 
 export const AUTO_UPDATE_INTERVAL_MS = 24 * 60 * 60 * 1000;
 export const AUTO_UPDATE_QUARANTINE_MS = 24 * 60 * 60 * 1000;
-export const SDK_PACKAGE_NAME = packageMetadata.name;
 export const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org/";
 
 const SKIP_COMMANDS: Readonly<Record<string, true>> = {
@@ -75,32 +79,6 @@ export const npmRegistryUrl = (): string => DEFAULT_NPM_REGISTRY;
 export const npmPackageMetadataUrl = (packageName: string): string =>
   new URL(encodeURIComponent(packageName), DEFAULT_NPM_REGISTRY).toString();
 
-export const parseSdkVersion = (version: string): readonly number[] | undefined => {
-  const match = /^(\d+)\.(\d+)\.(\d+)(?:-preview\.(\d+))?$/u.exec(version);
-  if (match === null) return undefined;
-  const [, major, minor, patch, preview] = match;
-  return [
-    Number(major),
-    Number(minor),
-    Number(patch),
-    preview === undefined ? Number.POSITIVE_INFINITY : Number(preview),
-  ];
-};
-
-export const compareSdkVersions = (left: string, right: string): number | undefined => {
-  const parsedLeft = parseSdkVersion(left);
-  const parsedRight = parseSdkVersion(right);
-  if (parsedLeft === undefined || parsedRight === undefined) return undefined;
-  const length = Math.max(parsedLeft.length, parsedRight.length);
-  for (let index = 0; index < length; index += 1) {
-    const leftPart = parsedLeft[index] ?? 0;
-    const rightPart = parsedRight[index] ?? 0;
-    if (leftPart < rightPart) return -1;
-    if (leftPart > rightPart) return 1;
-  }
-  return 0;
-};
-
 const asStringRecord = (value: unknown): Readonly<Record<string, string>> | undefined => {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
   const record: Record<string, string> = {};
@@ -122,9 +100,22 @@ export const asNpmPackageView = (payload: unknown): NpmPackageView | undefined =
   };
 };
 
-export const latestPublishedVersion = (view: NpmPackageView): string | undefined => {
-  const latest = view["dist-tags"]?.latest;
-  return typeof latest === "string" && latest.length > 0 ? latest : undefined;
+export const latestPublishedVersion = (
+  view: NpmPackageView,
+  currentVersion: string,
+): string | undefined => {
+  const tags = view["dist-tags"];
+  if (tags === undefined) return undefined;
+  const channels: readonly ReleaseChannel[] =
+    releaseChannelFor(currentVersion) === "preview" ? ["latest", "preview"] : ["latest"];
+  let newest: string | undefined;
+  for (const channel of channels) {
+    const candidate = tags[channel];
+    if (candidate === undefined || candidate.length === 0) continue;
+    if (newest === undefined || (compareSdkVersions(candidate, newest) ?? 0) > 0)
+      newest = candidate;
+  }
+  return newest;
 };
 
 const publishedAt = (view: NpmPackageView, version: string): Date | undefined => {
@@ -310,7 +301,7 @@ const selectUpdateCandidate = async (options: {
     return { status: "skip" };
   }
 
-  const version = latestPublishedVersion(view);
+  const version = latestPublishedVersion(view, currentVersion);
   if (version === undefined) return { status: "skip" };
   const order = compareSdkVersions(currentVersion, version);
   if (order === undefined || order >= 0) return { status: "skip" };

package/src/cli/check.ts

@@ -25,6 +25,7 @@ import {
   type TestEvidenceKind,
 } from "../testing/test-evidence";
 import { resolveCliEntry } from "./cli-entry";
+import { API_KEY_ENVIRONMENT_NAMES } from "./environment";
 import { loadProjectSource, type ProjectSource } from "./source";
 
 export type CheckStatus = "passed" | "failed" | "missing" | "partial" | "infrastructure_error";
@@ -269,18 +270,19 @@ const loadSourceWithoutPlatformCredentials = async (
   sourceRoot: string,
   environment: NodeJS.ProcessEnv,
 ): Promise<ProjectSource> => {
-  const environments = new Map<NodeJS.ProcessEnv, string | undefined>([
-    [process.env, process.env.POTATO_API_KEY],
-    [environment, environment.POTATO_API_KEY],
-  ]);
-  for (const current of environments.keys()) delete current.POTATO_API_KEY;
+  const targets = [process.env, environment];
+  const saved = targets.map((current) => API_KEY_ENVIRONMENT_NAMES.map((name) => current[name]));
+  for (const current of targets) for (const name of API_KEY_ENVIRONMENT_NAMES) delete current[name];
   try {
     return await loadProjectSource(sourceRoot);
   } finally {
-    for (const [current, apiKey] of environments) {
-      if (apiKey === undefined) delete current.POTATO_API_KEY;
-      else current.POTATO_API_KEY = apiKey;
-    }
+    targets.forEach((current, target) => {
+      API_KEY_ENVIRONMENT_NAMES.forEach((name, index) => {
+        const value = saved[target]?.[index];
+        if (value === undefined) delete current[name];
+        else current[name] = value;
+      });
+    });
   }
 };
 
@@ -683,7 +685,7 @@ export async function checkProject(
   try {
     const selectedPipeline = selected.pipelines.length === 1 ? selected.pipelines[0] : undefined;
     const checkEnvironment = { ...(options.environment ?? process.env) };
-    delete checkEnvironment.POTATO_API_KEY;
+    for (const name of API_KEY_ENVIRONMENT_NAMES) delete checkEnvironment[name];
     const environment = {
       ...checkEnvironment,
       [TEST_EVIDENCE_DIR_ENV]: evidenceDirectory,

package/src/cli/commands/auth.ts

@@ -0,0 +1,89 @@
+import type { Command } from "commander";
+import { createClient } from "../../client";
+import { authStatus, login, logout } from "../auth";
+import {
+  identifyClientUser,
+  resolveSelectedProject,
+  resolveSourceRoot,
+  type CommandHost,
+} from "../context";
+import { findCommandCredentials, readStoredCredentials } from "../credentials";
+import { resolveTolokaConfig } from "../config";
+import { readTolokaState } from "../../state";
+
+export const registerAuthCommands = (program: Command, host: CommandHost): void => {
+  const { context, exitCode, globals } = host;
+
+  program
+    .command("login")
+    .description("store an API key for this machine after verifying it")
+    .option("--api-key-stdin", "read the API key from standard input instead of prompting", false)
+    .action(async (options: { apiKeyStdin: boolean }) => {
+      const apiKey = options.apiKeyStdin ? (await context.io.readStdin()).trim() : globals().apiKey;
+      const injectedClient = context.injectedClient;
+      const result = await login({
+        ...(apiKey === undefined ? {} : { apiKey }),
+        ...(globals().baseUrl === undefined ? {} : { baseUrl: globals().baseUrl }),
+        ...(context.io.prompt === undefined ? {} : { prompt: context.io.prompt }),
+        ...(injectedClient === undefined ? {} : { probe: () => injectedClient }),
+        write: context.io.stdout,
+        environment: context.environment,
+      });
+      context.io.stdout(result.output);
+      try {
+        const stored = await readStoredCredentials(context.environment);
+        if (stored === undefined) return;
+        const client = context.injectedClient ?? createClient(stored);
+        await identifyClientUser(client, context.analytics);
+      } catch {}
+    });
+
+  program
+    .command("logout")
+    .description("remove stored credentials from this machine")
+    .action(async () => {
+      const result = await logout(context.environment);
+      context.io.stdout(result.output);
+    });
+
+  program
+    .command("auth-status")
+    .alias("whoami")
+    .description("show which platform and key the CLI would use")
+    .option("--show-token", "print the API key instead of masking it", false)
+    .action(async (options: { showToken: boolean }) => {
+      const flags = globals();
+      const credentialLookup = await findCommandCredentials(
+        context.environment,
+        flags.apiKey ?? context.environment.TOLOKA_API_KEY,
+      );
+      const stored = credentialLookup.found?.credentials;
+      const sourceRoot = await resolveSourceRoot(flags, context.io);
+      const state = await readTolokaState(sourceRoot);
+      const project = resolveSelectedProject(flags, context, stored, state);
+      const injectedClient = context.injectedClient;
+
+      const result = await authStatus({
+        environment: context.environment,
+        showToken: options.showToken,
+        credentialLookup,
+        ...(flags.apiKey === undefined ? {} : { flagApiKey: flags.apiKey }),
+        ...(flags.baseUrl === undefined ? {} : { flagBaseUrl: flags.baseUrl }),
+        ...(injectedClient === undefined ? {} : { probe: () => injectedClient }),
+        ...(project === undefined ? {} : { project }),
+      });
+
+      context.io.stdout(result.output);
+      if (!result.authenticated) {
+        exitCode.value = 1;
+        return;
+      }
+      try {
+        const config = resolveTolokaConfig(flags, state, context.environment, stored);
+        const client =
+          context.injectedClient ??
+          createClient({ apiKey: config.apiKey, baseUrl: config.baseUrl });
+        await identifyClientUser(client, context.analytics);
+      } catch {}
+    });
+};

package/src/cli/commands/config.ts

@@ -0,0 +1,28 @@
+import type { Command } from "commander";
+import type { CommandHost } from "../context";
+import { getCliSetting, readCliSettings, setCliSetting } from "../settings";
+
+export const registerConfigCommands = (program: Command, host: CommandHost): void => {
+  const config = program.command("config").description("read and write machine CLI settings");
+  config
+    .command("get")
+    .argument("[name]", "setting name; omit to print every setting")
+    .description("print a CLI setting, or every setting")
+    .action(async (name?: string) => {
+      const settings = await readCliSettings(host.context.environment);
+      host.context.io.stdout(getCliSetting(settings, name).output);
+    });
+  config
+    .command("set")
+    .argument("<name>", "setting name")
+    .argument("<value>", "setting value")
+    .description("write a CLI setting for this machine")
+    .action(async (name: string, value: string) => {
+      const result = await setCliSetting(host.context.environment, name, value);
+      host.context.io.stdout(result.output);
+    });
+  config.action(async () => {
+    const settings = await readCliSettings(host.context.environment);
+    host.context.io.stdout(getCliSetting(settings, undefined).output);
+  });
+};

package/src/cli/commands/dataset.ts

@@ -0,0 +1,75 @@
+import { assert } from "es-toolkit";
+import { resolve } from "node:path";
+import type { Command } from "commander";
+import { positiveInteger, resolveContext, type CommandHost } from "../context";
+import {
+  generateDatasetFieldDeclarations,
+  listProjectDatasets,
+  loadDataset,
+  uploadDataset,
+} from "../data";
+import { MISSING_PROJECT_ID_MESSAGE } from "../project-context";
+
+export const registerDatasetCommands = (program: Command, host: CommandHost): void => {
+  const { context, globals } = host;
+  const dataset = program
+    .command("dataset")
+    .description("inspect and move dataset catalog and rows");
+  dataset
+    .command("list")
+    .description("list live datasets in the selected project")
+    .action(async () => {
+      const { client, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      const result = await listProjectDatasets(client, { projectId });
+      context.io.stdout(result.output);
+    });
+  dataset
+    .command("fields")
+    .argument("<name>", "dataset name or id")
+    .description("print field declarations inferred from uploaded rows")
+    .action(async (name: string) => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await generateDatasetFieldDeclarations(client, {
+        sourceRoot,
+        datasetName: name,
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+      context.io.stdout(result.output);
+    });
+  dataset
+    .command("load")
+    .argument("<name>", "dataset name or id")
+    .requiredOption("--out <file>", "JSONL file to write")
+    .option("--limit <n>", "how many rows to keep after download", positiveInteger)
+    .option("--timeout <ms>", "how long to wait for the export", positiveInteger)
+    .description("download live dataset rows into a JSONL file")
+    .action(async (name: string, options: { out: string; limit?: number; timeout?: number }) => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await loadDataset(client, {
+        sourceRoot,
+        datasetName: name,
+        outPath: resolve(options.out),
+        ...(projectId === undefined ? {} : { projectId }),
+        ...(options.limit === undefined ? {} : { limit: options.limit }),
+        ...(options.timeout === undefined ? {} : { timeoutMs: options.timeout }),
+      });
+      context.io.stdout(result.output);
+    });
+  dataset
+    .command("upload")
+    .argument("<name>", "dataset name or id")
+    .argument("<file>", "JSON array, JSONL, or CSV file")
+    .description("append rows to a dataset")
+    .action(async (name: string, file: string) => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await uploadDataset(client, {
+        sourceRoot,
+        datasetName: name,
+        filePath: resolve(file),
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+      context.io.stdout(result.output);
+      if (result.warning !== undefined) context.io.stderr(result.warning);
+    });
+};

package/src/cli/commands/delivery-order.ts

@@ -0,0 +1,18 @@
+import type { Command } from "commander";
+import { resolveContext, type CommandHost } from "../context";
+import { listDeliveryOrders } from "../delivery-orders";
+
+export const registerDeliveryOrderCommands = (program: Command, host: CommandHost): void => {
+  const { context, globals } = host;
+  const deliveryOrder = program
+    .command("delivery-order")
+    .description("list Sunday delivery orders for project create");
+  deliveryOrder
+    .command("list")
+    .description("list active Sunday delivery orders this key can attach")
+    .action(async () => {
+      const { client } = await resolveContext(globals(), context);
+      const result = await listDeliveryOrders({ client });
+      context.io.stdout(result.output);
+    });
+};