kenso 0.0.0-stage → 0.1.7

package/docs/studio.md

@@ -0,0 +1,113 @@
+# Studio (beta)
+
+Studio templates are the pages, docs and other assets Kenso builds for each account or lead. The `kenso studio` commands let you edit a template as a folder of files on your machine, check it, preview it, and fill it for many accounts or leads at once. They are beta: they need the `studio` feature flag on your workspace. Help and `kenso describe` hide them until your workspace has it; `--all-commands` shows them.
+
+| Command | What it does |
+|---|---|
+| `studio pull <templateId> --dir <dir>` | Write a template version's files to a folder |
+| `studio push <templateId> --dir <dir>` | Save the folder's files to the template's draft and print the validation |
+| `studio validate <templateId> --dir <dir>` | Validate the folder against the template without saving |
+| `studio preview <templateId>` | Render a version for up to 3 accounts and print the preview links |
+| `studio fill <templateId>` | Fill the template for many accounts or campaign leads, estimate first |
+
+Find template ids with the generated commands:
+
+```bash
+kenso asset-templates list
+```
+
+## Edit a template locally
+
+```bash
+kenso studio pull 12 --dir ./my-template
+kenso studio validate 12 --dir ./my-template
+kenso studio push 12 --dir ./my-template
+kenso studio preview 12 --dir ./my-template --account-ids 501,502
+kenso studio push 12 --dir ./my-template --publish
+```
+
+### pull
+
+`pull` writes every file of the version under `--dir`: text files from the answer, binaries downloaded from signed links and checked against their SHA-256. It overwrites files with the same path and leaves other files in the folder alone. It checks every path before it writes anything, and refuses one that would land outside `--dir` (`unsafe_path`).
+
+`--template-version` picks the version: `draft`, `latest` (the latest published) or a version id. The default is the draft, else the latest published version. (The flag is not `--version`, which prints the CLI version.)
+
+```bash
+kenso studio pull 12 --dir ./v3 --template-version 345
+kenso studio pull 12 --dir ./my-template --dry-run
+```
+
+It prints `{templateId, versionId, files, dir}`. `--dry-run` lists the paths and writes nothing.
+
+### push
+
+`push` reads `--dir`, skipping dotfiles, dot folders and `node_modules`.
+
+- A text file (valid UTF-8, no NUL byte, under 1 MB) goes inline.
+- Any other file is uploaded through a signed upload URL first, 4 at a time, up to 5 MB each. A larger file is refused before any call.
+- One push then saves the files into the draft and prints `{templateId, versionId, versionNumber, validation, changed, deleted}`.
+
+Files that are in the draft but not in the folder stay, unless you pass `--delete-missing`. `--message` describes the change (default "Pushed with the Kenso CLI"). With `--publish`, the new version is published when validation passes, and the output adds `published`.
+
+```bash
+kenso studio push 12 --dir ./my-template --message "New hero copy"
+kenso studio push 12 --dir ./my-template --delete-missing --publish
+kenso studio push 12 --dir ./my-template --dry-run
+```
+
+When validation finds errors, the draft is still saved: the result prints, then the error `validation_failed` (exit 2) with the first problem as its `hint`. When publishing fails after a good push, the push result still prints and the error says which version was saved. `--dry-run` lists what would be sent and calls nothing.
+
+### validate
+
+`validate` reads the folder the same way and checks the files laid over the draft, as a push would, without saving them. Binaries are uploaded so they can be checked. `--delete-missing` validates exactly the folder's files. It prints the validation and exits 2 when there are errors.
+
+### preview
+
+`preview` renders a saved version, not your local files: the draft, else the latest published version, or `--version-id`. It takes up to a minute per account.
+
+```bash
+kenso studio preview 12
+kenso studio preview 12 --account-ids 501,502,503 --mode render
+kenso studio preview 12 --sample samples/acme.json
+kenso studio preview 12 --mode interact --interact @steps.json
+```
+
+- `--account-ids` takes up to 3 ids. Without it, Kenso picks the 3 most recently touched accounts, else the template's samples.
+- `--mode` is `render` (default) or `interact`. `--interact` takes the click, type and wait steps as JSON, `@file` or `-` (up to 20).
+- With `--dir`, the CLI compares your folder to the version it renders and warns on stderr when they differ, naming the push command to run first.
+
+The output lists each preview's link, screenshots, console errors and link issues.
+
+## Fill a template for many accounts or leads
+
+`fill` creates pages for a list of accounts, or for the leads of a campaign. A fill is charged per page, so it always prices the work first.
+
+```bash
+kenso studio fill 12 --accounts accounts.txt
+kenso studio fill 12 --accounts accounts.csv --column accountId --yes --wait
+kenso studio fill 12 --campaign 345 --contacts leads.csv --yes
+```
+
+- **Ids** come from `--accounts <file>`, or from `--contacts <file>` with `--campaign <id>`; `-` reads stdin. A file holds one id per line, or a CSV or JSONL with an id column (`--column`, else `id`, else `contactId`). Repeated ids are filled once.
+- **Without `--yes`** (or with `--estimate`) it prints the estimate and the apply command, and creates nothing. For a campaign, the estimate counts one page per lead; Kenso builds one page per company, so it is an upper bound.
+- **With `--yes`** it creates one fill run per 500 ids, one after another.
+- **With `--wait`** it follows each run every 5 seconds until it completes, fails or is cancelled. Without it, follow a run with `kenso asset-runs get --run-id <id>`.
+
+The summary lists `runs: [{runId, state, rows}]`, and `results.csv` has one line per id with its page id and state.
+
+**The same fill never runs twice.** Rebuilding a page charges again, so when you rerun a fill with the same file (the same bytes) and the same flags:
+
+- an unfinished fill continues where it stopped;
+- a finished fill where every id succeeded answers from that run and changes nothing;
+- anything else is refused with `already_filled` (exit 7). To retry only the ids that failed, take them from the earlier run's `results.csv` into a new file and fill that file.
+
+The guard compares the file and the flags, not the ids: the same ids in another file, or in another order, are filled and charged again. Keep one ids file per fill, and check `kenso runs list` before you fill ids from a new file.
+
+## Other Studio commands
+
+Everything else (create a template, list versions, restore a version, datasets, publish) is a generated command under `asset-templates`, `asset-runs` and `asset-template-datasets`:
+
+```bash
+kenso asset-templates --help --all-commands
+kenso describe asset-templates
+```

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "kenso",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.7",
+  "description": "The Kenso CLI: bulk lead, CRM and Studio work for people and coding agents",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "kenso": "dist/kenso.js"
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "skill/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@11.15.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ken-Technology/ken-backend.git",
+    "directory": "cli"
+  },
+  "homepage": "https://ken.so/cli",
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:contract": "vitest run test/contract.test.ts --passWithNoTests",
+    "check:startup": "node scripts/check-startup.mjs",
+    "check:package": "node scripts/check-package.mjs"
+  },
+  "devDependencies": {
+    "@types/jmespath": "0.15.2",
+    "@types/node": "22.20.5",
+    "csv-parse": "7.0.3",
+    "csv-stringify": "6.9.0",
+    "esbuild": "0.28.2",
+    "eslint": "10.12.0",
+    "jmespath": "0.16.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.71.1",
+    "vitest": "5.0.3"
+  },
+  "gitHead": "8ed729698e19d049751bf644c41dc81170648392"
+}

package/skill/kenso-cli/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: kenso-cli
+description: Use the Kenso CLI (kenso) for bulk lead, CRM and Studio work in a Kenso workspace from files - import, update, remove, pause or tag leads in campaigns, import accounts and people, fill Studio templates, or call any Kenso API operation from the shell. Prefer it over the Kenso MCP for anything over about 50 records.
+---
+
+# Kenso CLI
+
+`kenso` does bulk work in Kenso from files and prints JSON. Use it instead of the Kenso MCP when the work starts from a file or touches more than about 50 records: the rows stay on disk, and you read a short summary.
+
+## Install and auth
+
+```bash
+npm i -g kenso
+kenso doctor
+```
+
+Needs Node 22+. Auth, in order of precedence:
+
+- `KENSO_API_KEY` in the environment (plus `KENSO_WORKSPACE_ID` when the key reaches several workspaces). Nothing else to do.
+- Or a saved key. The key is never a flag value; pipe it in. The person creates it in app.ken.so at Settings > Integrations > API keys.
+
+```bash
+echo $KEY | kenso auth login --with-key
+kenso workspace list --q acme
+kenso workspace use 1234
+kenso auth status
+```
+
+Never print, echo to the conversation, or write the key into a file in the repo. `kenso auth login` alone is browser login: it may answer `browser_login_unavailable`; then use `--with-key`. If it works, it prints a link: ask the person to open it.
+
+## Golden rules
+
+1. **stdout is data, stderr is everything else.** Piped output is JSON: one object, NDJSON for lists, one JSON summary for a batch. Errors are one JSON line on stderr: `{"error":{"code","message","field","hint","next","httpStatus","requestId"}}`.
+2. **Plan, then apply.** A batch command (import, update, remove, tag, `--each`) only plans without `--yes`: run it with `--dry-run`, read the plan, then run the exact command in its `next` (the same command with `--yes`). Never pass both. A single `kenso <resource> <action>` write and `kenso api` send at once: run it with `--dry-run` to see the request, then without it.
+3. **Pass files, not rows.** Never paste a CSV or a list of records into the conversation or a command line. Write a file and pass `--file path` (or `--ids path`).
+4. **Read the summary, then failures only.** If `failed`, `notFound` and `invalid` are 0, you are done. Otherwise read only the problem rows: `grep -E '^[0-9]+,(failed|not_found|invalid),' <results> | head -50`, or `invalidRows`. Do not read the whole results file.
+5. **Follow `next`.** An error with a known fix carries the exact command to run in `next`, and what to change in `hint`.
+6. **Branch on the exit code:**
+
+| Exit | Meaning | Do |
+|---|---|---|
+| 0 | OK (skipped rows are not failures) | Report the summary |
+| 1 | Unexpected error | Rerun with `--verbose`, report |
+| 2 | Usage or validation error | Fix the flags or the file (see `field`, `hint`) |
+| 3 | No key, bad key, or 401/403 | Ask for a key or a permission; do not retry |
+| 4 | Not found | Check the id |
+| 5 | Some rows failed, not found or invalid | Read the failed rows only, fix, resend those |
+| 6 | Rate limited, or a lead limit (`limit_reached`) stopped the run | Wait, or ask the person to raise the limit, then rerun |
+| 7 | Conflict, or another process holds the run | Read `message`; run a `next` with `--force` only after the person agrees |
+| 8 | Server error after retries | Wait a minute, rerun the same command |
+| 130 | Interrupted | Run the `next`: `kenso runs resume <runId>` |
+
+## Leads: import
+
+```bash
+kenso contacts import --template
+kenso contacts import --campaign 812 --file leads.csv --dry-run
+kenso contacts import --campaign 812 --file leads.csv --yes
+```
+
+- CSV with a header row, or JSONL. Known columns: `email`, `firstName`, `lastName`, `title`, `linkedInUrl`, `companyName`, `companyDomain` (common header spellings are matched). Every other column becomes a custom variable in snake_case (`Pain Point` fills `{{pain_point}}`).
+- Rename or drop columns: `--map '{"Pain": "customVariables.pain_point", "Notes": null}'`.
+- Blank cells are never sent; the literal `null` clears a custom variable.
+- The dry run checks every row locally (`invalid_email`, `missing_first_name`, `duplicate_in_file` ...), shows the column `mapping` and the credit estimate. Check the mapping before you apply.
+- Row statuses: `created`, `updated`, `skipped` (with `reason`: `duplicate`, `blocklisted`, `already_contacted` ...), `failed`, `invalid`. `notSendable` counts saved leads that cannot be emailed yet.
+- Up to 100,000 rows without per-row results: add `--server-import`.
+
+## Leads: update and cleanup
+
+```bash
+kenso contacts update --file edits.csv --match id --dry-run
+kenso contacts update --file edits.csv --match email --campaign 812 --yes
+kenso contacts remove --ids ids.txt --dry-run
+kenso contacts remove --where '{"campaignIds": [812], "q": "acme"}' --yes
+kenso contacts restore --run r_ab3dxk2q --yes
+kenso contacts pause --ids ids.txt --yes
+kenso contacts resume --ids ids.txt --yes
+kenso contacts tag --tag 31 --ids ids.txt --yes
+kenso contacts export --campaign 812 --out contacts.csv
+```
+
+- `update`: match by an `id`/`contactId` column, or by email within `--campaign`. A missing column or blank cell leaves a field unchanged; `null` clears it.
+- `--ids` takes one id per line, or a CSV/JSONL with an `id` column, or `-` for stdin. Get ids with `kenso contacts list --campaign-id 812 --all -o ids > ids.txt`.
+- Removing more than 1,000 needs `--confirm <count>` (the dry run's `next` has it). The remove summary has `undo`: keep it.
+
+## Runs and resume
+
+Every batch run has an id (`r_...`) and a folder with `results.csv` (one line per input row: `row,status,id,reason,error`), `invalid.csv`, `plan.json` and `run.json`. The summary prints their absolute paths.
+
+- Rerunning the same command on the same file continues an unfinished run (`"resumed":true`) or, when every row already succeeded, answers `"changed":0` and sends no writes. Writes match existing records, so a resend never duplicates.
+- `kenso runs list`, `kenso runs show <runId>`, `kenso runs resume <runId>`.
+- `--concurrency` (1-16, default 4) works on `contacts update`, `remove`, `restore`, `pause`, `resume`, `tag`, `untag`, `people import`, `accounts import` and `--each`. `contacts import` sends one chunk at a time per campaign and has no such flag. 429s and transient 5xx are retried for you. Do not add your own retry loop.
+
+## CRM and Studio (beta)
+
+Need the `accounts` or `studio` flag. Same plan-then-apply rules.
+
+```bash
+kenso accounts import --file accounts.csv --dry-run
+kenso people import --file people.csv --dry-run
+kenso studio pull 12 --dir ./tpl
+kenso studio push 12 --dir ./tpl
+kenso studio fill 12 --accounts ids.txt
+```
+
+`accounts import` charges research per created account: show the person the estimate first. `studio fill` charges per page and refuses to rerun a fill of the same file with the same flags (exit 7), but the same ids in another file are charged again. Read `kenso docs crm` and `kenso docs studio` before using them.
+
+## Workflows in plain steps (beta)
+
+Needs the `workflows` and `workflows_plain` flags. Your own model writes the workflow from the person's words, in plain steps or as custom JSON/code; Kenso only runs it, so writing costs no Kenso AI credits.
+
+```bash
+kenso workflows brief > brief.json
+kenso workflows brief --types ai.qualify@1,logic.filter@1 --include stepTypes
+kenso workflows create --data @create.json --dry-run
+kenso workflows validate --workflow-id 42
+kenso workflow-builder test --workflow-id 42 --data @test.json
+kenso workflows publish --workflow-id 42
+```
+
+- Start with `brief`: `authoring` (how plain steps become engine steps), `stepTypes`, `triggers`, `examples` and `workspace` (campaigns, Slack, secret names). `--workflow-id` returns the current definition to change; save it with `kenso workflows update --workflow-id 42 --data @update.json` and its `baseVersion`.
+- `create.json` is `{"definition": {...}}`, the definition with its `plain` block. Fix every issue `validate` names, test on one record (`{"record": {"type": "person", "id": 123}}`), then publish.
+- Never write a secret's value into a definition or the conversation: reference `{{secrets.NAME}}` and ask the person to add it in app.ken.so at Settings > Integrations > Secrets.
+
+## Everything else
+
+Every API operation is a command: `kenso <resource> <action>` (`kenso campaigns list`, `kenso tags create --name VIP`). A write like that runs at once, without `--yes`: check it with `--dry-run` first. Look commands up instead of guessing flags:
+
+```bash
+kenso describe
+kenso describe campaigns
+kenso describe campaigns update
+kenso campaigns update --help
+```
+
+- Lists print one page; `--all` streams every page, `--limit` and `--cursor` page by hand. `--fields a,b` and `--query '<JMESPath>'` shape output without `jq`.
+- Many records: `--each file.csv` runs a generated command once per row (row keys are flag or API names), with results and resume. It needs `--yes` or `--dry-run` unless it is a GET.
+- Beta commands are hidden from help until the workspace has the flag; `--all-commands` shows them.
+- Raw route: `kenso api GET /v1/me`, `kenso api POST /v1/tags --data @tag.json`. Writes through `kenso api` run without `--yes`, so be sure first.
+- MCP-only tools (such as skills): `kenso mcp tools`, `kenso mcp call skills --operation list`.
+- Offline docs: `kenso docs`, `kenso docs leads`.