@toloka-platform/sdk 0.1.0-preview.3

package/src/cli/project-context.ts

@@ -0,0 +1,468 @@
+import { assert } from "es-toolkit";
+import { readTolokaState, writeTolokaState } from "../state";
+import type { TolokaState } from "../state";
+import type { AuthPrompt } from "./auth";
+import type { TolokaCliFlags, TolokaEnvironment } from "./config";
+import { resolveInternalBaseUrl } from "./config";
+import { normalizeBaseUrl, requireStoredCredentials, writeStoredCredentials } from "./credentials";
+import type { CliEnvironment, StoredCredentials, StoredProjectAlias } from "./credentials";
+
+type ProjectRecord = { readonly id: string; readonly name: string; readonly teamId: string };
+
+export type ProjectListApi = {
+  readonly projects: {
+    readonly listAll: (params?: object) => AsyncIterable<ProjectRecord>;
+  };
+};
+
+export type ProjectGetApi = {
+  readonly projects: {
+    readonly get: (args: { readonly projectId: string }) => Promise<ProjectRecord>;
+  };
+};
+
+export type ProjectCreateApi = {
+  readonly projects: {
+    readonly create: (input: {
+      readonly teamId: string;
+      readonly name?: string;
+    }) => Promise<ProjectRecord>;
+    readonly listAll: (params?: object) => AsyncIterable<ProjectRecord>;
+  };
+};
+
+export const MISSING_PROJECT_ID_MESSAGE =
+  "Missing project ID. Pass --project-id, set TOLOKA_PROJECT_ID, set projectId in toloka.json, or run toloka project add.";
+
+export const NO_PROJECT_SELECTED_MESSAGE =
+  "No project selected. Run toloka project add, or cd into a checkout.";
+
+const NETWORK_MISMATCH_MESSAGE =
+  "project add writes the machine registry; unset --api-key / --base-url / POTATO_API_KEY / POTATO_BASE_URL, or run login against that platform first.";
+
+const ALIAS_PATTERN = /^[^/\s]+$/u;
+
+export type ProjectContextSource =
+  | "flag"
+  | "toloka-project-id"
+  | "potato-project-id"
+  | "toloka.json"
+  | "registry";
+
+export type ProjectContext = {
+  readonly id: string;
+  readonly source: ProjectContextSource;
+  readonly alias?: string;
+  readonly name?: string;
+};
+
+export type ResolveProjectContextOptions = {
+  readonly flags?: TolokaCliFlags;
+  readonly state?: TolokaState;
+  readonly environment?: TolokaEnvironment;
+  readonly stored?: StoredCredentials;
+  readonly effectiveBaseUrl?: string;
+};
+
+export type ProjectIo = {
+  readonly stdout: (text: string) => void;
+  readonly prompt?: AuthPrompt;
+};
+
+export const validateProjectAlias = (alias: string): string => {
+  const trimmed = alias.trim();
+  assert(
+    trimmed.length > 0 && ALIAS_PATTERN.test(trimmed),
+    "Project alias must be non-empty and contain no / or whitespace.",
+  );
+  return trimmed;
+};
+
+const firstNonEmpty = (value: string | undefined): string | undefined => {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? undefined : trimmed;
+};
+
+const effectiveNetworkBaseUrl = (
+  flags: TolokaCliFlags | undefined,
+  environment: TolokaEnvironment | undefined,
+  stored: StoredCredentials | undefined,
+): string | undefined =>
+  firstNonEmpty(flags?.baseUrl) ??
+  firstNonEmpty(environment?.POTATO_BASE_URL) ??
+  resolveInternalBaseUrl(environment ?? {}) ??
+  firstNonEmpty(stored?.baseUrl);
+
+const ownProject = (
+  projects: Readonly<Record<string, StoredProjectAlias>> | undefined,
+  alias: string,
+): StoredProjectAlias | undefined =>
+  projects !== undefined && Object.hasOwn(projects, alias) ? projects[alias] : undefined;
+
+const attachAlias = (
+  id: string,
+  stored: StoredCredentials | undefined,
+  allowRegistry: boolean,
+): Pick<ProjectContext, "alias" | "name"> => {
+  if (!allowRegistry || stored?.projects === undefined) return {};
+  if (stored.current !== undefined) {
+    const current = ownProject(stored.projects, stored.current);
+    if (current?.id === id) {
+      return current.name === undefined
+        ? { alias: stored.current }
+        : { alias: stored.current, name: current.name };
+    }
+  }
+  for (const alias of Object.keys(stored.projects).toSorted()) {
+    const project = ownProject(stored.projects, alias);
+    if (project?.id !== id) continue;
+    return project.name === undefined ? { alias } : { alias, name: project.name };
+  }
+  return {};
+};
+
+export function resolveProjectContext(
+  options: ResolveProjectContextOptions = {},
+): ProjectContext | undefined {
+  const flags = options.flags ?? {};
+  const environment = options.environment ?? {};
+  const stored = options.stored;
+  const effectiveBaseUrl =
+    options.effectiveBaseUrl ?? effectiveNetworkBaseUrl(flags, environment, stored);
+  const registryMatchesPlatform =
+    stored !== undefined &&
+    effectiveBaseUrl !== undefined &&
+    normalizeBaseUrl(effectiveBaseUrl) === normalizeBaseUrl(stored.baseUrl);
+
+  const candidates: Array<{
+    readonly id: string | undefined;
+    readonly source: ProjectContextSource;
+  }> = [
+    { id: firstNonEmpty(flags.projectId), source: "flag" },
+    { id: firstNonEmpty(environment.TOLOKA_PROJECT_ID), source: "toloka-project-id" },
+    { id: firstNonEmpty(environment.POTATO_PROJECT_ID), source: "potato-project-id" },
+    { id: firstNonEmpty(options.state?.projectId), source: "toloka.json" },
+    {
+      id:
+        registryMatchesPlatform && stored.current !== undefined
+          ? firstNonEmpty(stored.projects?.[stored.current]?.id)
+          : undefined,
+      source: "registry",
+    },
+  ];
+
+  const winner = candidates.find((candidate) => candidate.id !== undefined);
+  if (winner?.id === undefined) return undefined;
+  return {
+    id: winner.id,
+    source: winner.source,
+    ...attachAlias(winner.id, stored, registryMatchesPlatform),
+  };
+}
+
+export const formatProjectContextLine = (
+  project: ProjectContext | undefined,
+  stored?: StoredCredentials,
+): string => {
+  if (project === undefined) return "Project:  (none). Run toloka project add.";
+  const alias = project.alias === undefined ? "" : `alias ${project.alias}, `;
+  const registryNote =
+    project.source !== "registry" && stored?.current !== undefined
+      ? `; registry current is ${stored.current}`
+      : "";
+  return `Project:  ${project.id} (${alias}from ${project.source}${registryNote})`;
+};
+
+const assertStoredNetworkMatches = (
+  flags: TolokaCliFlags,
+  environment: TolokaEnvironment,
+  stored: StoredCredentials,
+) => {
+  const flagOrEnvKey = firstNonEmpty(flags.apiKey) ?? firstNonEmpty(environment.POTATO_API_KEY);
+  const flagOrEnvBase =
+    firstNonEmpty(flags.baseUrl) ??
+    firstNonEmpty(environment.POTATO_BASE_URL) ??
+    resolveInternalBaseUrl(environment);
+  assert(flagOrEnvKey === undefined || flagOrEnvKey === stored.apiKey, NETWORK_MISMATCH_MESSAGE);
+  assert(
+    flagOrEnvBase === undefined ||
+      normalizeBaseUrl(flagOrEnvBase) === normalizeBaseUrl(stored.baseUrl),
+    NETWORK_MISMATCH_MESSAGE,
+  );
+};
+
+const writeRegistry = async (
+  next: StoredCredentials,
+  environment: CliEnvironment,
+): Promise<void> => {
+  await writeStoredCredentials(next, environment);
+};
+
+const withAlias = (
+  stored: StoredCredentials,
+  alias: string,
+  project: { readonly id: string; readonly name?: string },
+): StoredCredentials => {
+  const projects = Object.assign(Object.create(null), stored.projects ?? {}, {
+    [alias]: project.name === undefined ? { id: project.id } : project,
+  }) as Record<string, StoredProjectAlias>;
+  return { ...stored, current: alias, projects };
+};
+
+const promptOrFail = async (
+  io: ProjectIo | undefined,
+  question: string,
+  missing: string,
+): Promise<string> => {
+  assert(io?.prompt, missing);
+  const value = (await io.prompt(question)).trim();
+  assert(value.length > 0, missing);
+  return value;
+};
+
+export async function listRemoteProjects(options: {
+  readonly client: ProjectListApi;
+  readonly context?: ProjectContext;
+  readonly io: ProjectIo;
+}): Promise<{ readonly output: string }> {
+  const lines: string[] = [];
+  for await (const project of options.client.projects.listAll()) {
+    const mark = options.context?.id === project.id ? "*" : " ";
+    const alias =
+      options.context?.id === project.id && options.context.alias !== undefined
+        ? `\t${options.context.alias}`
+        : "";
+    lines.push(`${mark}\t${project.id}\t${project.name}${alias}`);
+  }
+  const output = lines.length === 0 ? "No projects visible." : lines.join("\n");
+  options.io.stdout(output);
+  return { output };
+}
+
+export async function addProject(options: {
+  readonly environment: CliEnvironment;
+  readonly flags?: TolokaCliFlags;
+  readonly client: ProjectGetApi;
+  readonly io?: ProjectIo;
+  readonly alias?: string;
+  readonly projectId?: string;
+  readonly afterPreflight?: () => Promise<void>;
+}): Promise<{ readonly output: string; readonly alias: string; readonly projectId: string }> {
+  const found = await requireStoredCredentials(options.environment);
+  assertStoredNetworkMatches(options.flags ?? {}, options.environment, found.credentials);
+
+  const alias = validateProjectAlias(
+    options.alias ??
+      (await promptOrFail(
+        options.io,
+        "Alias: ",
+        "Missing project alias. Pass an alias or run this in a terminal.",
+      )),
+  );
+  const projectId =
+    firstNonEmpty(options.projectId) ??
+    (await promptOrFail(
+      options.io,
+      "Project id: ",
+      "Missing project ID. Pass a project id or run this in a terminal.",
+    ));
+
+  const existing = ownProject(found.credentials.projects, alias);
+
+  assert(
+    existing === undefined || existing.id === projectId,
+    `Alias ${alias} already points at ${existing?.id}. Run toloka project remove ${alias} first.`,
+  );
+
+  await options.afterPreflight?.();
+  const live = await options.client.projects.get({ projectId });
+
+  await writeRegistry(
+    withAlias(found.credentials, alias, { id: live.id, name: live.name }),
+    options.environment,
+  );
+  const output = `Using project ${live.id} as ${alias}.`;
+  options.io?.stdout(output);
+  return { output, alias, projectId: live.id };
+}
+
+export async function switchProject(options: {
+  readonly environment: CliEnvironment;
+  readonly flags?: TolokaCliFlags;
+  readonly alias: string;
+  readonly io?: ProjectIo;
+}): Promise<{ readonly output: string }> {
+  const found = await requireStoredCredentials(options.environment);
+  assertStoredNetworkMatches(options.flags ?? {}, options.environment, found.credentials);
+  const alias = validateProjectAlias(options.alias);
+  const project = ownProject(found.credentials.projects, alias);
+  assert(project, `Unknown project alias ${alias}.`);
+
+  await writeRegistry({ ...found.credentials, current: alias }, options.environment);
+  const output = `Using project ${project.id} as ${alias}.`;
+  options.io?.stdout(output);
+  return { output };
+}
+
+export async function removeProject(options: {
+  readonly environment: CliEnvironment;
+  readonly flags?: TolokaCliFlags;
+  readonly alias: string;
+  readonly io?: ProjectIo;
+}): Promise<{ readonly output: string }> {
+  const found = await requireStoredCredentials(options.environment);
+  assertStoredNetworkMatches(options.flags ?? {}, options.environment, found.credentials);
+  const alias = validateProjectAlias(options.alias);
+  const projects = Object.assign(Object.create(null), found.credentials.projects ?? {}) as Record<
+    string,
+    StoredProjectAlias
+  >;
+  assert(ownProject(projects, alias), `Unknown project alias ${alias}.`);
+  delete projects[alias];
+
+  const current = found.credentials.current === alias ? undefined : found.credentials.current;
+  await writeRegistry(
+    {
+      baseUrl: found.credentials.baseUrl,
+      apiKey: found.credentials.apiKey,
+      ...(current === undefined ? {} : { current }),
+      ...(Object.keys(projects).length === 0 ? {} : { projects }),
+    },
+    options.environment,
+  );
+  const output = `Removed local alias ${alias}.`;
+  options.io?.stdout(output);
+  return { output };
+}
+
+export function currentProject(options: {
+  readonly flags?: TolokaCliFlags;
+  readonly state?: TolokaState;
+  readonly environment?: TolokaEnvironment;
+  readonly stored?: StoredCredentials;
+  readonly io?: ProjectIo;
+}): { readonly output: string; readonly project?: ProjectContext } {
+  const project = resolveProjectContext(options);
+  const output =
+    project === undefined
+      ? NO_PROJECT_SELECTED_MESSAGE
+      : formatProjectContextLine(project, options.stored);
+  options.io?.stdout(output);
+  return project === undefined ? { output } : { output, project };
+}
+
+const uniqueTeamId = (projects: ReadonlyArray<{ readonly teamId: string }>): string | undefined => {
+  const teams = [...new Set(projects.map((project) => project.teamId))];
+  return teams.length === 1 ? teams[0] : undefined;
+};
+
+const resolveTeamId = async (
+  client: ProjectCreateApi,
+  teamId: string | undefined,
+): Promise<string> => {
+  const explicit = firstNonEmpty(teamId);
+  if (explicit !== undefined) return explicit;
+  const visible: Array<{ readonly teamId: string }> = [];
+  for await (const project of client.projects.listAll()) visible.push(project);
+  const inferred = uniqueTeamId(visible);
+  assert(
+    inferred,
+    "Missing team id. Pass --team-id. Visible projects do not share a single team, or none are visible.",
+  );
+  return inferred;
+};
+
+const bindCheckout = async (
+  sourceRoot: string,
+  existingState: TolokaState | undefined,
+  created: ProjectRecord,
+  alias: string,
+): Promise<string | undefined> => {
+  if (existingState === undefined) {
+    try {
+      await writeTolokaState(sourceRoot, {
+        projectId: created.id,
+        pipelines: {},
+        datasets: {},
+      });
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        [
+          `Created project ${created.id} as ${alias}.`,
+          `Failed to write toloka.json: ${reason}`,
+        ].join("\n"),
+        { cause: error },
+      );
+    }
+    return undefined;
+  }
+  if (existingState.projectId === created.id) return undefined;
+  return `Checkout still uses ${existingState.projectId}; it overrides the new registry current.`;
+};
+
+export async function createProject(options: {
+  readonly environment: CliEnvironment;
+  readonly flags?: TolokaCliFlags;
+  readonly client: ProjectCreateApi;
+  readonly io?: ProjectIo;
+  readonly alias?: string;
+  readonly name?: string;
+  readonly teamId?: string;
+  readonly sourceRoot?: string;
+  readonly afterPreflight?: () => Promise<void>;
+}): Promise<{ readonly output: string; readonly projectId: string; readonly alias: string }> {
+  const found = await requireStoredCredentials(options.environment);
+  assertStoredNetworkMatches(options.flags ?? {}, options.environment, found.credentials);
+
+  const alias = validateProjectAlias(
+    options.alias ??
+      (await promptOrFail(
+        options.io,
+        "Alias: ",
+        "Missing project alias. Pass an alias or run this in a terminal.",
+      )),
+  );
+  assert(
+    found.credentials.projects?.[alias] === undefined,
+    `Alias ${alias} already exists. Run toloka project remove ${alias} first.`,
+  );
+
+  const existingState =
+    options.sourceRoot === undefined ? undefined : await readTolokaState(options.sourceRoot);
+
+  await options.afterPreflight?.();
+
+  const teamId = await resolveTeamId(options.client, options.teamId);
+  const created = await options.client.projects.create({
+    teamId,
+    name: firstNonEmpty(options.name) ?? alias,
+  });
+
+  try {
+    await writeRegistry(
+      withAlias(found.credentials, alias, { id: created.id, name: created.name }),
+      options.environment,
+    );
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      [
+        `Created ${created.id} but failed to update the local registry: ${reason}`,
+        `Run: toloka project add ${alias} ${created.id}`,
+      ].join("\n"),
+      { cause: error },
+    );
+  }
+
+  const lines = [`Created project ${created.id} as ${alias}.`];
+  if (options.sourceRoot !== undefined) {
+    const extra = await bindCheckout(options.sourceRoot, existingState, created, alias);
+    if (extra !== undefined) lines.push(extra);
+  }
+
+  const output = lines.join("\n");
+  options.io?.stdout(output);
+  return { output, projectId: created.id, alias };
+}