@toloka-platform/sdk 0.1.0-preview.4 → 0.1.0-preview.6

package/src/cli/init.ts

@@ -1,45 +1,39 @@
 import { assert } from "es-toolkit";
-import { createHash } from "node:crypto";
-import { lstat, mkdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
-import { dirname, join, sep } from "node:path";
+import { lstat, mkdir, readdir, readFile, realpath, rm, rmdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import packageMetadata from "../../package.json" with { type: "json" };
 import { readTolokaState, writeTolokaState } from "../state";
+import { assertSafeDestination, entryStats, isMissingFileError } from "./file-system";
+import { SKILL_ENTRY_POINT, SKILL_INSTALL_ROOT } from "./skill";
 
 export const SDK_VERSION = packageMetadata.version;
 
 const SDK_PACKAGE_NAME = "@toloka-platform/sdk";
-const SKILL_NAME = "toloka-build";
-const CLAUDE_SKILL_PATH = `.claude/skills/${SKILL_NAME}/SKILL.md`;
-const CURSOR_RULE_PATH = `.cursor/rules/${SKILL_NAME}.mdc`;
+const BOOTSTRAP_NAME = "toloka-bootstrap";
+const CLAUDE_POINTER_PATH = `.claude/skills/${BOOTSTRAP_NAME}/SKILL.md`;
+const CURSOR_POINTER_PATH = `.cursor/rules/${BOOTSTRAP_NAME}.mdc`;
 const AGENTS_PATH = "AGENTS.md";
-const BLOCK_BEGIN = "<!-- toloka:begin -->";
-const BLOCK_END = "<!-- toloka:end -->";
+const MANAGED_PATHS = [CLAUDE_POINTER_PATH, CURSOR_POINTER_PATH, AGENTS_PATH];
+const CURRENT_BLOCK = { begin: "<toloka>", end: "</toloka>" };
+const LEGACY_BLOCK = { begin: "<!-- toloka:begin -->", end: "<!-- toloka:end -->" };
 const VERSION_PATTERN = /<!-- toloka:sdk-version ([^\s>]+) -->/u;
-const DIGEST_PATTERN = /<!-- toloka:skill-digest sha256:([a-f0-9]{64}) -->/u;
-const AGENT_ENTRY_PATHS = [CLAUDE_SKILL_PATH, CURSOR_RULE_PATH, AGENTS_PATH];
-const LEGACY_SKILL_NAME = "toloka-pipeline-as-code";
-const LEGACY_SKILL_DIRECTORY = join(".claude", "skills", LEGACY_SKILL_NAME);
-const LEGACY_CURSOR_RULE = join(".cursor", "rules", `${LEGACY_SKILL_NAME}.mdc`);
-const LEGACY_PATHS = [LEGACY_SKILL_DIRECTORY, LEGACY_CURSOR_RULE];
-const LEGACY_ENTRY_PATHS = [join(LEGACY_SKILL_DIRECTORY, "SKILL.md"), LEGACY_CURSOR_RULE];
-const BUNDLED_SKILL_FILES = [
-  ["SKILL.md", new URL("../../skills/SKILL.md", import.meta.url)],
-  [
-    "references/node-semantics.md",
-    new URL("../../skills/references/node-semantics.md", import.meta.url),
-  ],
-  [
-    "references/workflow-and-cli.md",
-    new URL("../../skills/references/workflow-and-cli.md", import.meta.url),
+type LegacyEntry = { readonly file: string; readonly directory?: string };
+
+const LEGACY_ENTRIES: readonly LegacyEntry[] = ["toloka-build", "toloka-pipeline-as-code"].flatMap(
+  (skillName): LegacyEntry[] => [
+    { file: `.claude/skills/${skillName}/SKILL.md`, directory: `.claude/skills/${skillName}` },
+    { file: `.cursor/rules/${skillName}.mdc` },
   ],
-] satisfies ReadonlyArray<readonly [string, URL]>;
+);
+
+type BlockMarkers = { readonly begin: string; readonly end: string };
 
 export type InitProjectResult = {
   readonly targetDirectory: string;
   readonly files: readonly string[];
   readonly writtenFiles: readonly string[];
+  readonly removedFiles: readonly string[];
   readonly sdkVersion: string;
-  readonly skillDigest: string;
   readonly dependencyReady: boolean;
   readonly output: string;
   readonly warning?: string;
@@ -50,9 +44,6 @@ type AgentEntry = {
   readonly source: string;
 };
 
-const isMissingFileError = (error: unknown) =>
-  error instanceof Error && "code" in error && error.code === "ENOENT";
-
 const readOptionalFile = async (path: string) => {
   try {
     return await readFile(path, "utf8");
@@ -71,116 +62,85 @@ const isDirectory = async (path: string) => {
   }
 };
 
-const isFile = async (path: string) => {
-  try {
-    return (await lstat(path)).isFile();
-  } catch (error) {
-    if (isMissingFileError(error)) return false;
-    throw error;
-  }
-};
+const isGenerated = (source: string) => VERSION_PATTERN.test(source);
 
-const assertSafeDestination = async (targetDirectory: string, relativePath: string) => {
-  let currentPath = targetDirectory;
-  for (const segment of relativePath.split("/")) {
-    currentPath = join(currentPath, segment);
-    try {
-      const entry = await lstat(currentPath);
-      assert(!entry.isSymbolicLink(), `Refusing to write through symbolic link ${currentPath}.`);
-    } catch (error) {
-      if (isMissingFileError(error)) return;
-      throw error;
-    }
-  }
-};
+const PROVENANCE = `Generated by \`${SDK_PACKAGE_NAME}\` version \`${SDK_VERSION}\`.
+<!-- toloka:sdk-version ${SDK_VERSION} -->`;
 
-export async function computeBundledSkillDigest(): Promise<string> {
-  const digest = createHash("sha256");
-  for (const [relativePath, url] of BUNDLED_SKILL_FILES) {
-    digest.update(relativePath);
-    digest.update("\0");
-    digest.update(await readFile(url));
-    digest.update("\0");
-  }
-  return digest.digest("hex");
-}
+const BOOTSTRAP_BLOCK = `${CURRENT_BLOCK.begin}
 
-const BUNDLED_SKILL_BODY = new URL("../../skills/SKILL.md", import.meta.url);
-const INSTALLED_REFERENCE_PREFIX = `node_modules/${SDK_PACKAGE_NAME}/skills/references/`;
-
-const bundledSkillBody = async (sectionHeading: "##" | "###"): Promise<string> => {
-  const source = await readFile(BUNDLED_SKILL_BODY, "utf8");
-  const withoutFrontmatter = source.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/u, "");
-  const withoutTitle = withoutFrontmatter.replace(/^#\s.*\r?\n+/u, "");
-  const withInstalledReferences = withoutTitle
-    .replaceAll("](references/", `](${INSTALLED_REFERENCE_PREFIX}`)
-    .replaceAll("](../examples/", `](node_modules/${SDK_PACKAGE_NAME}/examples/`);
-  return sectionHeading === "##"
-    ? withInstalledReferences
-    : withInstalledReferences.replaceAll(/^## /gmu, "### ");
-};
+## Toloka Agent Bootstrap
 
-const guidance = async (
-  sectionHeading: "##" | "###",
-  skillDigest: string,
-) => `Generated by \`${SDK_PACKAGE_NAME}\` version \`${SDK_VERSION}\`.
-<!-- toloka:sdk-version ${SDK_VERSION} -->
-<!-- toloka:skill-digest sha256:${skillDigest} -->
+${PROVENANCE}
+Re-run \`toloka init\` to refresh this block. Keep your own instructions outside it.
 
-${await bundledSkillBody(sectionHeading)}
-Use the globally installed \`toloka\` binary. Install it with \`curl -fsSL https://platform.toloka.ai/cli/install.sh | sh\` if it is not on \`PATH\`.
+This repository works with the Toloka platform through the \`toloka\` CLI. Before starting a Toloka task:
 
-If the reference paths above are missing, keep following the workflow and constraints in this file, do not invent SDK helpers or CLI commands, and install the project's declared dependencies before validating, planning, or applying. When no project is selected, use \`toloka project add\` to adopt one or \`toloka project create\` to create one. Adopt live source with \`toloka import\`.
+1. Run \`toloka --help\`, then \`toloka <resource> --help\` for the resource you need.
+2. Run \`toloka skill search <query>\` to find a bundled skill for the task; \`toloka skill list\` shows every skill and whether it is installed.
+3. Run \`toloka skill install <skill-id>\` and read \`${SKILL_INSTALL_ROOT}/<skill-id>/${SKILL_ENTRY_POINT}\` before acting; add \`--force\` to refresh a stale skill.
+4. Follow the installed skill. When no skill matches, continue with the CLI help and never invent commands or SDK helpers.
+5. To report a Toloka platform problem or unexpected failure to support, run \`toloka skill search report-issue\` and install \`toloka-report-issue\` before collecting evidence.
 
-`;
+${CURRENT_BLOCK.end}`;
 
-const claudeSkillSource = async (skillDigest: string) => `---
-name: ${SKILL_NAME}
-description: Build, inspect, and change Toloka platform pipeline projects as TypeScript source with @toloka-platform/sdk and toloka. Use when the user wants to create, adopt, inspect, plan, or apply a pipeline project as code.
----
+const POINTER_BODY = `# Toloka Agent Bootstrap pointer
 
-# Build Toloka pipelines as code
+${PROVENANCE}
 
-${await guidance("##", skillDigest)}`;
+Read the \`${CURRENT_BLOCK.begin}\` block in \`${AGENTS_PATH}\` at the source root and follow it before doing Toloka work. It tells you to run \`toloka --help\`, search the bundled Skill Catalog with \`toloka skill search <query>\`, install the match with \`toloka skill install <skill-id>\`, and read \`${SKILL_INSTALL_ROOT}/<skill-id>/${SKILL_ENTRY_POINT}\` before acting.
+`;
 
-const cursorRuleSource = async (skillDigest: string) => `---
-description: Build, inspect, and change Toloka platform pipeline projects as TypeScript source with @toloka-platform/sdk and toloka
-alwaysApply: false
+const CLAUDE_POINTER_SOURCE = `---
+name: ${BOOTSTRAP_NAME}
+description: Toloka platform work with the toloka CLI and ${SDK_PACKAGE_NAME}, such as pipeline projects, datasets, runs, secrets, and issue reporting. Use when the user mentions Toloka or the toloka CLI. Start by reading the ${CURRENT_BLOCK.begin} Agent Bootstrap block in ${AGENTS_PATH}, then find and install the matching skill.
 ---
 
-# Build Toloka pipelines as code
+${POINTER_BODY}`;
 
-${await guidance("##", skillDigest)}`;
+const CURSOR_POINTER_SOURCE = `---
+description: Toloka Agent Bootstrap pointer for the toloka CLI and ${SDK_PACKAGE_NAME}
+alwaysApply: true
+---
 
-const agentsBlockSource = async (skillDigest: string) => `${BLOCK_BEGIN}
-## Build Toloka pipelines as code
+${POINTER_BODY}`;
 
-${(await guidance("###", skillDigest)).trimEnd()}
-${BLOCK_END}`;
+const locateBlock = (source: string, markers: BlockMarkers, path: string) => {
+  const beginIndex = source.indexOf(markers.begin);
+  const endIndex = source.indexOf(markers.end);
+  if (beginIndex === -1 && endIndex === -1) return undefined;
+  assert(
+    beginIndex !== -1 && endIndex !== -1 && beginIndex < endIndex,
+    `Malformed Toloka block in ${path}: expected one ${markers.begin} followed by one ${markers.end}. Repair the file by hand, then re-run \`toloka init\`.`,
+  );
+  assert(
+    !source.includes(markers.begin, beginIndex + markers.begin.length) &&
+      !source.includes(markers.end, endIndex + markers.end.length),
+    `Multiple Toloka blocks in ${path}: keep exactly one ${markers.begin} ... ${markers.end} block, then re-run \`toloka init\`.`,
+  );
+  return { beginIndex, endIndex: endIndex + markers.end.length };
+};
 
-const mergeAgentsBlock = (source: string, block: string) => {
-  const beginIndex = source.indexOf(BLOCK_BEGIN);
-  const endIndex = source.indexOf(BLOCK_END);
-  const hasBegin = beginIndex !== -1;
-  const hasEnd = endIndex !== -1;
-  const lineEnding = source.includes("\r\n") ? "\r\n" : "\n";
-  const normalizedBlock = block.replaceAll("\n", lineEnding);
-  if (!hasBegin && !hasEnd) {
-    if (source.length === 0) return `${normalizedBlock}${lineEnding}`;
-    const gap = source.endsWith(`${lineEnding}${lineEnding}`)
-      ? ""
-      : source.endsWith(lineEnding)
-        ? lineEnding
-        : `${lineEnding}${lineEnding}`;
-    return `${source}${gap}${normalizedBlock}${lineEnding}`;
-  }
-  assert(hasBegin && hasEnd && beginIndex < endIndex, `Malformed toloka block in ${AGENTS_PATH}.`);
+const mergeBootstrap = (source: string, path: string) => {
+  const current = locateBlock(source, CURRENT_BLOCK, path);
+  const legacy = locateBlock(source, LEGACY_BLOCK, path);
   assert(
-    !source.includes(BLOCK_BEGIN, beginIndex + BLOCK_BEGIN.length) &&
-      !source.includes(BLOCK_END, endIndex + BLOCK_END.length),
-    `Multiple toloka blocks found in ${AGENTS_PATH}.`,
+    current === undefined || legacy === undefined,
+    `Ambiguous Toloka blocks in ${path}: both ${CURRENT_BLOCK.begin} and ${LEGACY_BLOCK.begin} are present. Keep one, then re-run \`toloka init\`.`,
   );
-  return `${source.slice(0, beginIndex)}${normalizedBlock}${source.slice(endIndex + BLOCK_END.length)}`;
+  const lineEnding = source.includes("\r\n") ? "\r\n" : "\n";
+  const block = BOOTSTRAP_BLOCK.replaceAll("\n", lineEnding);
+  const existing = current ?? legacy;
+  if (existing !== undefined) {
+    return `${source.slice(0, existing.beginIndex)}${block}${source.slice(existing.endIndex)}`;
+  }
+  if (source.length === 0) return `${block}${lineEnding}`;
+  const gap = source.endsWith(`${lineEnding}${lineEnding}`)
+    ? ""
+    : source.endsWith(lineEnding)
+      ? lineEnding
+      : `${lineEnding}${lineEnding}`;
+  return `${source}${gap}${block}${lineEnding}`;
 };
 
 const hasSdkDependency = async (targetDirectory: string) => {
@@ -210,43 +170,46 @@ const writeIfChanged = async (path: string, source: string) => {
   return true;
 };
 
-const entryStats = async (path: string) => {
-  try {
-    return await lstat(path);
-  } catch (error) {
-    if (isMissingFileError(error)) return undefined;
-    throw error;
-  }
+const assertRefreshablePointer = async (targetRoot: string, relativePath: string) => {
+  const path = join(targetRoot, relativePath);
+  const existing = await readOptionalFile(path);
+  assert(
+    existing === undefined || isGenerated(existing),
+    `Refusing to overwrite ${path}: it carries no \`<!-- toloka:sdk-version ... -->\` marker, so it is not a pointer generated by ${SDK_PACKAGE_NAME}. Move it aside, then re-run \`toloka init\`.`,
+  );
 };
 
-const removeLegacyEntryPoints = async (targetRoot: string): Promise<string[]> => {
-  const removed = await Promise.all(
-    LEGACY_PATHS.map(async (relativePath) => {
-      const path = join(targetRoot, relativePath);
-      const entry = await entryStats(path);
-      if (entry === undefined) return undefined;
-      assert(
-        !entry.isSymbolicLink(),
-        `Refusing to remove legacy agent entry point through symbolic link ${path}.`,
-      );
-      await assertSafeDestination(targetRoot, relativePath.split(sep).join("/"));
-      await rm(path, { recursive: true, force: true });
-      return relativePath;
+const recognizeLegacyEntries = async (targetRoot: string): Promise<LegacyEntry[]> => {
+  const recognized = await Promise.all(
+    LEGACY_ENTRIES.map(async (entry) => {
+      const path = join(targetRoot, entry.file);
+      if ((await entryStats(path)) === undefined) return undefined;
+      await assertSafeDestination(targetRoot, entry.file, "remove legacy agent entry point");
+      return isGenerated(await readFile(path, "utf8")) ? entry : undefined;
     }),
   );
-  return removed.filter((relativePath): relativePath is string => relativePath !== undefined);
+  return recognized.filter((entry): entry is LegacyEntry => entry !== undefined);
+};
+
+const removeLegacyEntry = async (targetRoot: string, entry: LegacyEntry) => {
+  await rm(join(targetRoot, entry.file), { force: true });
+  if (entry.directory === undefined) return;
+  const directory = join(targetRoot, entry.directory);
+  if ((await readdir(directory)).length === 0) await rmdir(directory);
 };
 
 const formatInitOutput = (
   targetRoot: string,
   files: readonly string[],
   writtenFiles: readonly string[],
-  removedLegacyFiles: readonly string[],
+  removedFiles: readonly string[],
 ): string =>
   [
-    `${writtenFiles.length === 0 ? "Agent entry points are up to date" : "Initialized agent entry points"} for ${SDK_PACKAGE_NAME} ${SDK_VERSION} in ${targetRoot}:`,
+    `${writtenFiles.length === 0 && removedFiles.length === 0 ? "Agent entry points are up to date" : "Initialized agent entry points"} for ${SDK_PACKAGE_NAME} ${SDK_VERSION} in ${targetRoot}:`,
     ...files.map((file) => `  ${file}`),
-    ...removedLegacyFiles.map((file) => `  removed ${file} (renamed to ${SKILL_NAME})`),
+    ...removedFiles.map(
+      (file) => `  removed ${file} (replaced by the ${AGENTS_PATH} Agent Bootstrap)`,
+    ),
   ].join("\n");
 
 const bindCheckout = async (
@@ -270,44 +233,27 @@ export async function initProject(
 ): Promise<InitProjectResult> {
   await mkdir(targetDirectory, { recursive: true });
   const targetRoot = await realpath(targetDirectory);
-  const boundCheckout = await bindCheckout(targetRoot, options.projectId);
-  const [hasClaude, hasCursor, hasAgents, skillDigest] = await Promise.all([
+  const agentsPath = join(targetRoot, AGENTS_PATH);
+  const existingAgents = await readOptionalFile(agentsPath);
+  const agentsSource = mergeBootstrap(existingAgents ?? "", agentsPath);
+  const [hasClaude, hasCursor] = await Promise.all([
     isDirectory(join(targetRoot, ".claude")),
     isDirectory(join(targetRoot, ".cursor", "rules")),
-    isFile(join(targetRoot, AGENTS_PATH)),
-    computeBundledSkillDigest(),
   ]);
-  const useDefaults = !hasClaude && !hasCursor && !hasAgents;
-  const candidates = [
-    {
-      relativePath: CLAUDE_SKILL_PATH,
-      wanted: hasClaude || useDefaults,
-      source: () => claudeSkillSource(skillDigest),
-    },
-    {
-      relativePath: CURSOR_RULE_PATH,
-      wanted: hasCursor,
-      source: () => cursorRuleSource(skillDigest),
-    },
-    {
-      relativePath: AGENTS_PATH,
-      wanted: hasAgents || useDefaults,
-      source: async () => {
-        const existingSource = await readOptionalFile(join(targetRoot, AGENTS_PATH));
-        return mergeAgentsBlock(existingSource ?? "", await agentsBlockSource(skillDigest));
-      },
-    },
+  const useDefaults = !hasClaude && !hasCursor && existingAgents === undefined;
+  const pointers: AgentEntry[] = [
+    ...(hasClaude || useDefaults
+      ? [{ relativePath: CLAUDE_POINTER_PATH, source: CLAUDE_POINTER_SOURCE }]
+      : []),
+    ...(hasCursor ? [{ relativePath: CURSOR_POINTER_PATH, source: CURSOR_POINTER_SOURCE }] : []),
   ];
-  const selected = candidates.filter((candidate) => candidate.wanted);
+  const entries: AgentEntry[] = [...pointers, { relativePath: AGENTS_PATH, source: agentsSource }];
+  await Promise.all(entries.map((entry) => assertSafeDestination(targetRoot, entry.relativePath)));
   await Promise.all(
-    selected.map((candidate) => assertSafeDestination(targetRoot, candidate.relativePath)),
-  );
-  const entries: AgentEntry[] = await Promise.all(
-    selected.map(async (candidate) => ({
-      relativePath: candidate.relativePath,
-      source: await candidate.source(),
-    })),
+    pointers.map((pointer) => assertRefreshablePointer(targetRoot, pointer.relativePath)),
   );
+  const legacyEntries = await recognizeLegacyEntries(targetRoot);
+  const boundCheckout = await bindCheckout(targetRoot, options.projectId);
 
   const writtenFiles = boundCheckout === undefined ? [] : [boundCheckout];
   for (const entry of entries) {
@@ -315,7 +261,10 @@ export async function initProject(
       writtenFiles.push(entry.relativePath);
     }
   }
-  const removedLegacyFiles = await removeLegacyEntryPoints(targetRoot);
+  for (const entry of legacyEntries) {
+    await removeLegacyEntry(targetRoot, entry);
+  }
+  const removedFiles = legacyEntries.map((entry) => entry.file);
   const dependencyReady = await hasSdkDependency(targetRoot);
   const files = [
     ...entries.map((entry) => entry.relativePath),
@@ -328,10 +277,10 @@ export async function initProject(
     targetDirectory: targetRoot,
     files,
     writtenFiles,
+    removedFiles,
     sdkVersion: SDK_VERSION,
-    skillDigest,
     dependencyReady,
-    output: formatInitOutput(targetRoot, files, writtenFiles, removedLegacyFiles),
+    output: formatInitOutput(targetRoot, files, writtenFiles, removedFiles),
     ...(warning === undefined ? {} : { warning }),
   };
 }
@@ -339,23 +288,29 @@ export async function initProject(
 export async function readAgentSkillStalenessWarning(
   targetDirectory: string,
 ): Promise<string | undefined> {
-  const currentDigest = await computeBundledSkillDigest();
-  const staleDigests = new Set<string>();
-  const generatedVersions = new Set<string>();
-  for (const relativePath of [...AGENT_ENTRY_PATHS, ...LEGACY_ENTRY_PATHS]) {
+  const outdated: string[] = [];
+  const versions = new Set<string>();
+  const record = (relativePath: string, source: string) => {
+    outdated.push(relativePath);
+    const version = VERSION_PATTERN.exec(source)?.[1];
+    if (version !== undefined) versions.add(version);
+  };
+  for (const { file } of LEGACY_ENTRIES) {
+    const source = await readOptionalFile(join(targetDirectory, file));
+    if (source !== undefined && isGenerated(source)) record(file, source);
+  }
+  for (const relativePath of MANAGED_PATHS) {
     const source = await readOptionalFile(join(targetDirectory, relativePath));
     if (source === undefined) continue;
-    const recordedDigest = DIGEST_PATTERN.exec(source)?.[1];
-    if (recordedDigest !== undefined && recordedDigest !== currentDigest) {
-      staleDigests.add(recordedDigest.slice(0, 12));
-      const recordedVersion = VERSION_PATTERN.exec(source)?.[1];
-      if (recordedVersion !== undefined) generatedVersions.add(recordedVersion);
+    const version = VERSION_PATTERN.exec(source)?.[1];
+    if (source.includes(LEGACY_BLOCK.begin) || (version !== undefined && version !== SDK_VERSION)) {
+      record(relativePath, source);
     }
   }
-  if (staleDigests.size === 0) return undefined;
-  const versions =
-    generatedVersions.size === 0
-      ? "an earlier build"
-      : [...generatedVersions].toSorted().join(", ");
-  return `Warning: Agent instructions generated by ${SDK_PACKAGE_NAME} ${versions} do not match the installed ${SDK_VERSION} skill content (${[...staleDigests].toSorted().join(", ")} -> ${currentDigest.slice(0, 12)}). Re-run \`toloka init\`.`;
+  if (outdated.length === 0) return undefined;
+  const generatedBy =
+    versions.size === 0
+      ? `an earlier ${SDK_PACKAGE_NAME} build`
+      : `${SDK_PACKAGE_NAME} ${[...versions].toSorted().join(", ")}`;
+  return `Warning: Agent instructions generated by ${generatedBy} are out of date (${outdated.join(", ")}). The installed ${SDK_VERSION} manages one Agent Bootstrap in ${AGENTS_PATH} plus pointer files. Re-run \`toloka init\`.`;
 }

package/src/cli/models.ts

@@ -0,0 +1,188 @@
+import { assert } from "es-toolkit";
+
+import type { BaseModel, BaseModelId, Model, ModelVersion, PotatoClient } from "../client";
+
+type ModelApi = Pick<PotatoClient, "baseModels" | "models">;
+type ModelIo = { readonly stdout: (text: string) => void };
+type TableRow = readonly string[];
+
+const BASE_MODEL_IDS = [
+  "qwen3-4b",
+  "qwen3-8b",
+  "qwen3-32b",
+  "qwen3-235b",
+] satisfies readonly BaseModelId[];
+
+const formatTable = (rows: readonly TableRow[]): string => {
+  const widths = rows.reduce<number[]>(
+    (current, row) => row.map((cell, index) => Math.max(current[index] ?? 0, cell.length)),
+    [],
+  );
+  return rows
+    .map((row) =>
+      row
+        .map((cell, index) => cell.padEnd(widths[index] ?? cell.length))
+        .join("  ")
+        .trimEnd(),
+    )
+    .join("\n");
+};
+
+const writeOutput = (io: ModelIo, json: boolean, value: unknown, formatted: string): void => {
+  io.stdout(json ? JSON.stringify(value, null, 2) : formatted);
+};
+
+const formatBaseModel = (model: BaseModel): string =>
+  formatTable([
+    ["ID", model.id],
+    ["Name", model.displayName],
+    ["Provider", model.provider],
+    ["Upstream model", model.upstreamModel],
+    ["Upstream revision", model.upstreamRevision],
+  ]);
+
+const formatModel = (model: Model): string =>
+  formatTable([
+    ["ID", model.id],
+    ["Project", model.projectId],
+    ["Name", model.name],
+    ["Base model", model.baseModelId],
+    ["Description", model.description ?? "-"],
+    ["Archived at", model.archivedAt ?? "-"],
+    ["Created at", model.createdAt],
+    ["Updated at", model.updatedAt],
+  ]);
+
+export const parseBaseModelId = (value: string): BaseModelId => {
+  const modelId = BASE_MODEL_IDS.find((candidate) => candidate === value);
+  assert(modelId, `Unknown base model ${value}.`);
+  return modelId;
+};
+
+const resolveModel = async (
+  client: ModelApi,
+  projectId: string,
+  nameOrId: string,
+): Promise<Model> => {
+  if (nameOrId.startsWith("mdl.")) return client.models.get({ projectId, modelId: nameOrId });
+  const matches: Model[] = [];
+  for await (const model of client.models.listAll({ projectId, limit: 100 })) {
+    if (model.name === nameOrId) matches.push(model);
+  }
+  assert(matches.length === 1, `Model ${nameOrId} was not found or is ambiguous.`);
+  return matches[0]!;
+};
+
+export const listBaseModels = async (
+  client: ModelApi,
+  input: { json: boolean },
+  io: ModelIo,
+): Promise<void> => {
+  const models = await client.baseModels.list();
+  writeOutput(
+    io,
+    input.json,
+    models,
+    models.length === 0
+      ? "No base models found."
+      : formatTable([
+          ["ID", "NAME", "PROVIDER", "UPSTREAM MODEL"],
+          ...models.map((model) => [
+            model.id,
+            model.displayName,
+            model.provider,
+            model.upstreamModel,
+          ]),
+        ]),
+  );
+};
+
+export const getBaseModel = async (
+  client: ModelApi,
+  input: { id: BaseModelId; json: boolean },
+  io: ModelIo,
+): Promise<void> => {
+  const model = await client.baseModels.get({ id: input.id });
+  writeOutput(io, input.json, model, formatBaseModel(model));
+};
+
+export const listModels = async (
+  client: ModelApi,
+  input: { projectId: string; json: boolean },
+  io: ModelIo,
+): Promise<void> => {
+  const page = await client.models.listPage({ projectId: input.projectId, limit: 100, offset: 0 });
+  writeOutput(
+    io,
+    input.json,
+    page.models,
+    page.models.length === 0
+      ? "No models found."
+      : formatTable([
+          ["ID", "NAME", "BASE MODEL"],
+          ...page.models.map((model) => [model.id, model.name, model.baseModelId]),
+        ]),
+  );
+};
+
+export const getModel = async (
+  client: ModelApi,
+  input: { projectId: string; nameOrId: string; json: boolean },
+  io: ModelIo,
+): Promise<void> => {
+  const model = await resolveModel(client, input.projectId, input.nameOrId);
+  writeOutput(io, input.json, model, formatModel(model));
+};
+
+export const listModelVersions = async (
+  client: ModelApi,
+  input: { projectId: string; nameOrId: string; json: boolean },
+  io: ModelIo,
+): Promise<void> => {
+  const model = await resolveModel(client, input.projectId, input.nameOrId);
+  const versions: ModelVersion[] = [];
+  for await (const version of client.models.listAllVersions({
+    projectId: input.projectId,
+    modelId: model.id,
+    limit: 100,
+  })) {
+    versions.push(version);
+  }
+  writeOutput(
+    io,
+    input.json,
+    versions,
+    versions.length === 0
+      ? "No Model Versions found."
+      : formatTable([
+          ["VERSION", "ID", "CREATED AT"],
+          ...versions.map((version) => [version.version, version.id, version.createdAt]),
+        ]),
+  );
+};
+
+export const createModel = async (
+  client: ModelApi,
+  input: {
+    projectId: string;
+    name: string;
+    description?: string;
+    baseModelId: BaseModelId;
+    json: boolean;
+  },
+  io: ModelIo,
+): Promise<void> => {
+  const { json, ...body } = input;
+  const model = await client.models.create(body);
+  writeOutput(io, json, model, formatModel(model));
+};
+
+export const archiveModel = async (
+  client: ModelApi,
+  input: { projectId: string; nameOrId: string; json: boolean },
+  io: ModelIo,
+): Promise<void> => {
+  const model = await resolveModel(client, input.projectId, input.nameOrId);
+  const archived = await client.models.archive({ projectId: input.projectId, modelId: model.id });
+  writeOutput(io, input.json, archived, `Archived Model ${archived.id}.`);
+};