@toloka-platform/sdk 0.1.0-preview.3

package/skills/references/workflow-and-cli.md

@@ -0,0 +1,257 @@
+# Workflow and CLI recipes
+
+Use this file after the primary skill has selected the source-first workflow. Keep platform changes behind `toloka`; use the public authoring helpers only in TypeScript source.
+
+## Find the source root
+
+Expect this shape:
+
+```text
+<source-root>/
+  toloka.json
+  pipelines/
+    <pipeline-name>/
+      pipeline.ts
+      fields.ts
+      nodes/
+```
+
+Only `pipeline.ts` is structurally required. It must default-export the value returned by `definePipeline`. The CLI recursively loads `pipelines/**/pipeline.ts`; split fields and nodes into imported modules when that makes the source easier to change.
+
+Treat the three layers differently:
+
+- TypeScript files are desired state. Read and edit them.
+- `toloka.json` is CLI-managed identity state. Read it for orientation; let import and apply write it.
+- Dataset rows and secret values are operational data. Keep them outside committed source.
+
+## Initialize the source root
+
+Install the SDK in the project, then initialize the directory before selecting a platform project:
+
+```sh
+bun add --dev @toloka-platform/sdk
+toloka init
+```
+
+`init` does not require a selected project. It checks that `@toloka-platform/sdk` is declared in `dependencies` or `devDependencies`, then writes a Claude skill for `.claude/`, a Cursor rule when `.cursor/rules/` exists, and a marked block in an existing `AGENTS.md`; with no agent configuration, it creates the Claude skill and `AGENTS.md`. If a project is already selected through `--project-id`, `TOLOKA_PROJECT_ID` / `POTATO_PROJECT_ID`, `toloka.json`, or the machine registry, it also writes `toloka.json` when missing.
+
+The generated entry points contain the core read, edit, validate, plan, and apply loop and point back to the fuller references in this package. Every `toloka` command except `init` compares the recorded skill-content digest with the installed SDK and warns on stderr when they differ. The warning never blocks the command; re-run `toloka init` to refresh the pointers.
+
+## Store credentials once
+
+```sh
+toloka login
+```
+
+It explains where to generate an API key — `console.toloka.ai` → Company → API Keys → Generate API Key
+— reads the key without echoing it, verifies it by listing one project, and only then saves the
+credentials file with mode `0600`. Nothing is written when the key does not authenticate.
+
+Most later commands read that file, so `--api-key` becomes optional. For networked commands that do
+not mutate the machine project registry, key precedence is flag, then `POTATO_API_KEY`, then the
+stored file; CI can use an environment variable without running login. Non-interactive callers can
+skip the login prompt with `toloka login --api-key <key>`. The base URL defaults to the platform.
+
+```sh
+toloka auth-status     # or toloka whoami
+toloka logout
+```
+
+`auth-status` reports which platform and key are in effect and where each came from, masks the key
+unless you pass `--show-token`, and exits non-zero when the platform is unreachable — use it to check a
+setup rather than guessing. `logout` deletes the stored file; it does not revoke the key.
+
+## Configure the CLI
+
+Provide the API key and base URL on networked workflows through `POTATO_API_KEY` and
+`POTATO_BASE_URL`, or with `--api-key` and `--base-url`. The registry-mutating commands
+`toloka project add`, `toloka project switch`, `toloka project remove`, and `toloka project create`
+require `toloka login` first because they read and write the credentials file. When flags or
+`POTATO_*` variables are also present, they must identify the same stored key and platform. Resolve
+project ID in this order: `--project-id`, `TOLOKA_PROJECT_ID`, `POTATO_PROJECT_ID`, `toloka.json`,
+then the machine registry `current`.
+
+Anonymous command telemetry is on by default (`sdk_cli_command_completed` / `sdk_cli_command_failed`). Set `TOLOKA_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable it. CI is off unless `TOLOKA_TELEMETRY=1`.
+
+All commands accept `--source-root <directory>`. Prefer running from the source root so paths and diffs stay obvious. `init` does not walk up: it binds the working directory or `--source-root` only.
+
+The real command surface is:
+
+```text
+toloka login
+toloka logout
+toloka auth-status
+toloka project list
+toloka project add [alias] [projectId]
+toloka project switch <alias>
+toloka project current
+toloka project remove <alias>
+toloka project create [alias] [--name <name>] [--team-id <id>]
+toloka init
+toloka import [projectId]
+toloka validate
+toloka plan
+toloka apply
+toloka status
+toloka secret set <name> [--from-env <variable>]
+toloka dataset list
+toloka dataset fields <name>
+toloka dataset load <name> --out <file> [--limit <n>] [--timeout <ms>]
+toloka dataset upload <name> <file>
+toloka pipeline list
+toloka pipeline run [name] [--wait] [--timeout <ms>]
+toloka pipeline status [name]
+toloka pipeline runs [name] [--limit <n>]
+toloka pipeline cost [name] [--item-limit <n>]
+toloka pipeline results <runId> [--limit <n>] [--failed]
+toloka pipeline cancel <runId>
+```
+
+Select the platform project with `toloka project add` or `toloka project create` before `import`, `plan`, or `apply`. `init` may run first, and `import` uses the selected project when the id is omitted.
+
+`toloka pipeline cost [name] [--item-limit <n>]` forecasts what a run of a live pipeline would bill. It does not start a run and does not change the graph. Name the live pipeline or id; a TTY may pick among several. The typed client equivalent is `client.pipelines.estimateCost({ pipelineId, itemLimit? })`.
+
+## Adopt an existing live project
+
+1. Run `toloka init` in the intended source root if the agent entry points are not installed yet.
+2. Run `toloka project add <alias> <projectId>`.
+3. Run `toloka import`.
+4. Inspect `toloka.json` and every generated `pipelines/**/pipeline.ts` dependency before editing.
+5. Preserve generated constructor `id` options. They bind imported source to the existing graph; never copy them to unrelated declarations or invent replacements.
+6. Make the smallest source change, validate offline, plan, apply, and plan again.
+
+Import refuses an existing `pipelines/` directory. Pass `--force` to replace it with the live graph as TypeScript. Never use `--force` as a harmless refresh over uncommitted source work.
+
+## Author against a project from scratch
+
+1. Run `toloka init` in the intended source root if the agent entry points are not installed yet.
+2. Run `toloka project create <alias>` or `toloka project add <alias> <projectId>`.
+3. Create `pipelines/<name>/pipeline.ts` and its imported modules.
+4. Default-export `definePipeline({ dataset, fields, nodes, connections })`.
+5. Run `toloka validate`.
+6. Run `toloka plan`.
+7. Resolve missing secrets and immutable-field conflicts.
+8. Run `toloka apply`.
+9. Require a final `toloka plan` to print `No changes.`
+
+On first apply, the CLI creates each missing named dataset, adds fields required by the authored graphs, creates each missing pipeline, attaches its dataset, and records the resolved IDs. Two pipelines that name the same dataset contribute the union of their required fields.
+
+## Validate against the platform
+
+Run the project typecheck first. Then validate every bound pipeline:
+
+```sh
+bunx tsc --noEmit
+toloka validate
+```
+
+`toloka validate` posts each authored graph to the platform. It reports spec errors, warnings, and the latest matching check jobs. It does not write the graph. A pipeline that is not on the platform yet is skipped until `toloka apply` creates it.
+
+The authored API still supplies extra local safety:
+
+- `definePipeline` rejects duplicate declared field or node IDs.
+- It rejects a node that references a `field()` value absent from `fields`.
+- It rejects a `connect()` endpoint whose node is absent from `nodes`.
+- Typed ports prevent reversing input and output handles.
+
+These checks do not replace `toloka validate`. Plan compares source with live resources but does not submit the desired graph for acceptance. Apply is where the backend can reject graph-wide references, layout identity, or concurrent-version assumptions.
+
+## Read and apply a plan
+
+Treat every plan line as evidence of what apply will attempt.
+
+- Confirm additions and changes match the request.
+- Stop on an unexpected removal. Apply refuses to delete tracked pipelines or datasets merely because their source entry disappeared.
+- Stop on a dataset field marked changed. Existing field schemas cannot be rewritten.
+- Set every secret listed as missing before apply.
+- If imported source contains live IDs, preserve them while editing around them.
+
+Apply preserves existing live layout and the root's live item filter. Do not add either to authored source. For graph replacement, apply reads the live graph version and sends it as `expectedVersion`; never put a version in source or state yourself.
+
+## Add dataset rows
+
+Declare the fields in source, then upload rows:
+
+```sh
+toloka dataset upload <dataset> <file>
+```
+
+The input file is JSONL: each non-empty line must parse as one JSON object. The dataset does not have to exist yet: when a pipeline in source binds it, upload creates it and declares that pipeline's columns, so rows land in real columns rather than in the raw `uploaded` blob. Upload refuses when no pipeline in source declares a name because it would have no column names to map onto. An id-shaped argument is never created; upload fails when that dataset id does not exist in the project. Upload appends items; apply never uploads, replaces, or deletes rows. Duplicate live names must be addressed by id.
+
+If a later upload fails with a schema-incompatibility error, inspect the inferred schema from the first successful upload:
+
+```sh
+toloka dataset fields <dataset>
+```
+
+That prints `field()` declarations for the top-level inferred columns. Copy them into source when you want authored fields to match the stored inference. It does not write source or mutate the dataset.
+
+Keep item files outside the source tree or gitignored. Never embed sample or production rows in `pipeline.ts` to make reconciliation create them.
+
+Pull live rows with `toloka dataset load <name> --out <file> [--limit <n>]`. `--limit` slices after the export downloads; omit it only for the whole table.
+
+## Run a pipeline and report results
+
+A run needs a deployed pipeline, so apply before starting one.
+
+```sh
+toloka pipeline run <name> --wait --timeout 900000
+toloka pipeline runs <name> --limit 10
+toloka pipeline status <name>
+toloka pipeline results <runId> --limit 50
+toloka pipeline results <runId> --failed
+toloka pipeline cancel <runId>
+```
+
+Read the exit code, not just the text. `toloka pipeline run --wait` exits `0` when the run reaches a successful terminal state, `1` when it reaches a failed one, and `2` when the wait window elapses while the run is still going. Without `--wait` the command returns as soon as the run is accepted, and exit `0` means "accepted", not "succeeded".
+
+Never treat a started run as a finished one. There is no background watcher: nothing will report back later. But bound every wait — a queue no one is working stays in progress indefinitely, and an unbounded poll loop ends with the agent killed and no report written. Pick a window, and when it closes report the observed counts and states along with the fact that the run had not finished. Poll in the foreground and deliver that report before you finish: there is no later turn, so promising to report once a window closes loses the observation entirely.
+
+`toloka pipeline runs` lists ids and timestamps. `toloka pipeline status` reports the latest run. `toloka status` (no prefix) is project health. When a listing is capped it says so; report the cap rather than presenting a page as the whole picture.
+
+A failed item carries an error, so `toloka pipeline results <runId> --failed` is the fastest path to why a run failed. Report counts and states from that output rather than inferring them from the run having started.
+
+## Work on more than one project
+
+`toloka.json` records exactly one `projectId`, so one checkout targets one project. To drive a second project from the same source — a copy for another customer, or a staging and a production instance — do not overwrite the state file in place. Use a separate checkout, or pass `--project-id` explicitly and keep the state files apart. Overwriting the recorded id silently repoints every later `plan` and `apply` at the wrong project.
+
+Create a second live project with `toloka project create <alias>` or register an existing one with `toloka project add <alias> <projectId>`. After a copy, prove the original is untouched by planning against it and seeing no changes.
+
+## Set a secret
+
+Reference a secret name from a code node's `envVars`, then provide its value separately:
+
+```sh
+toloka secret set API_TOKEN --from-env API_TOKEN
+toloka plan
+toloka apply
+```
+
+Without `--from-env`, `toloka secret set <name>` reads the value from stdin. Never place the value in TypeScript, `toloka.json`, a command-line argument, or a committed upload file.
+
+## Recover safely
+
+### Field schema conflict
+
+Do not rename the live field in place, delete it, or retry apply. Keep the existing field untouched and either:
+
+1. declare a differently named `field()` with the new schema and migrate downstream node references, or
+2. change `definePipeline({ dataset })` to a new dataset name.
+
+Plan again and inspect the full rebind or new-column diff before applying.
+
+### Missing secret
+
+Use the exact name reported by plan. Set it with `toloka secret set`, rerun plan, and apply only when no secret is marked missing.
+
+### Stale graph version
+
+A 409 means live graph state changed after apply read it. Run plan again, compare the new live diff with the source, incorporate intentional live changes into source when required, and apply once more. Never add `expectedVersion` to source and never loop retries.
+
+### Server 400 after a clean validate
+
+Read the returned path and reason. Check connection endpoints, duplicate or unknown IDs preserved from imported source, field references, and any accidentally authored layout. Fix source, rerun `toloka validate`, plan, and apply. Do not bypass reconciliation with a raw API call.
+
+## Use the shipped example
+
+Read [the face image collection pipeline](../../examples/face-image-collection/pipeline.ts), its `fields.ts`, and its `nodes/` modules for a real composition of `field`, `root`, `generation`, `code`, `connect`, and `definePipeline`. Copy its source organization, not its task-specific settings.