@ishlabs/cli 0.8.1 → 0.8.3

package/dist/lib/skill-content.js

@@ -0,0 +1,462 @@
+/**
+ * Agent Skill content for the `ish` CLI.
+ *
+ * Shipped inline as TypeScript constants so the same content is available
+ * in both `tsc`-compiled npm installs and `bun build --compile` single
+ * binaries (which don't bundle markdown files outside of TS imports).
+ *
+ * Spec: https://agentskills.io/specification (April 2026).
+ *
+ * Distribution model: `ish init` materialises this content as a real
+ * directory tree at the path the user picks. Native consumers:
+ *   - Claude Code           .claude/skills/ish/
+ *   - Codex / Cursor /      .agents/skills/ish/
+ *     Cline / Roo Code
+ */
+import pkg from "../../package.json" with { type: "json" };
+const VERSION = pkg.version;
+/**
+ * SKILL.md description is the primary trigger mechanism — it's the only
+ * field always loaded into agent context (the body is loaded on match).
+ *
+ * Anthropic's authoring guidance: skills under-trigger by default; pack
+ * the description with verbs the user is likely to say plus the noun
+ * "ish". Hard cap is 1024 chars. Front-load the use case.
+ */
+const SKILL_DESCRIPTION = "Use this skill whenever the user mentions ish, a study, a tester profile, " +
+    "a simulation run, an \"ask\", an audience, or wants to dispatch tests against AI testers. " +
+    "Wraps the `ish` CLI for managing studies, asks, iterations, tester profiles, and simulation " +
+    "runs against the Ish platform. Always start by running `ish docs overview` to load the " +
+    "domain model, then `ish docs list` and `ish docs get-page <slug>` for specifics. Prefer " +
+    "this skill over guessing flags from `ish --help`.";
+const SKILL_BODY = `# ish
+
+A CLI for the Ish platform — run user-research studies and quick "ask"
+reactions against AI tester audiences. The CLI is the agent surface;
+this skill teaches you how to use it without re-reading its docs every
+time.
+
+## When to invoke this skill
+
+The user mentioned any of: \`ish\`, a study, a tester profile,
+a tester source, a simulation run, an iteration, an "ask", an audience,
+or wants to dispatch tests against AI testers. Also invoke if the user
+asks to "run a study", "generate testers", "compare variants", "test a
+prototype with users", or similar.
+
+## First step, every time: load the mental model
+
+Before producing any \`ish\` command, run:
+
+\`\`\`bash
+ish docs overview
+\`\`\`
+
+This prints a one-page mental model (workspace → study | ask → testers
+→ results) and lists every concept page available offline. The model is
+non-obvious — *do not* skip this step the first time the user asks for
+anything ish-related in a session.
+
+If you need detail on a specific concept:
+
+\`\`\`bash
+ish docs list                          # every page available
+ish docs get-page concepts/study       # one page, full markdown
+ish docs get-page concepts/run-verbs   # study run vs ask run
+ish docs search "<keyword>"            # ranked hits with snippets
+\`\`\`
+
+The pages \`ish docs\` exposes are the source of truth — newer than this
+skill file. **Trust \`ish docs\` over anything in this skill if they
+conflict.**
+
+## Quick orientation (one-screen)
+
+\`\`\`
+Workspace (= product)
+├── Tester Profiles (tp-…)   reusable audience personas
+│     └── Sources (tps-…)    transcripts/audio/images that seed generation
+├── Study (s-…)              persistent research artifact
+│     ├── modality           interactive | text | video | audio | image | document
+│     ├── assignments        tasks the tester does
+│     ├── questionnaire      questions the tester answers
+│     └── Iterations (i-…)   one configured run; carries the URL or media
+│           └── Testers (t-…) instance of a profile in this iteration
+└── Ask (a-…)                lightweight reaction artifact
+      └── Rounds             unit of execution; audience fixed at ask creation
+\`\`\`
+
+Two run verbs:
+- \`ish study run\` — dispatches simulations on the latest iteration of a study.
+- \`ish ask run\`  — appends a round to an ask (or \`--new\` to create one).
+
+Use **study** when the tester must *do* something on a real surface;
+use **ask** for quick reactions to text/image variants.
+
+## High-frequency commands
+
+\`\`\`bash
+# Auth & active selection (saved to ~/.ish/config.json)
+ish login
+ish workspace use w-6ec
+ish study use s-b2c
+ish ask use a-6ec
+
+# Inspect
+ish workspace list
+ish study list
+ish iteration list --study s-b2c
+ish ask list
+
+# Define / configure
+ish study create --name "..." --modality interactive --assignment "..." --question "..."
+ish iteration create --url https://example.com
+ish profile generate --description "..." --count 5
+
+# Run
+ish study run --sample 5 --country SE --wait
+ish ask run --new --name "..." --prompt "..." --variant text:"A" --variant text:"B" --sample 30 --wants-pick --wait
+
+# Results
+ish study results
+ish ask results a-6ec --round 1
+
+# Read offline docs
+ish docs overview
+ish docs get-page <slug>
+ish docs search <query>
+\`\`\`
+
+## Common workflows (worked examples)
+
+See \`references/workflows.md\` in this skill for end-to-end transcripts:
+- First study from zero (auth → workspace → audience → study → iteration → run → results)
+- Quick A/B ask with image variants
+- Generating profiles from a transcript or audio source
+- Targeting a gated URL (basic auth, session cookie, login form)
+- Re-running a study with a fresh audience
+
+## Output handling
+
+- Every command supports \`--json\`. JSON mode is **auto-enabled when
+  stdout is piped**, so an agent rarely needs \`--json\` explicitly.
+- \`--fields a,b,c\` strips JSON output to the listed fields (saves
+  tokens). \`--verbose\` adds full UUIDs and timestamps.
+- Exit codes carry meaning: 0 success, 2 usage/validation,
+  3 auth, 4 not-found, 5 transient. See
+  \`ish docs get-page reference/json-mode\`.
+- Aliases (\`s-…\`, \`a-…\`, \`tp-…\`, \`i-…\`, \`t-…\`, \`tps-…\`, \`w-…\`)
+  are accepted anywhere a UUID is. See
+  \`ish docs get-page reference/aliases\`.
+
+## Common pitfalls (don't do these)
+
+1. **Don't paste flags from memory.** The CLI evolves; flags change.
+   Run \`ish <command> --help\` to confirm before constructing a command.
+2. **Don't run \`ish study run\` before an iteration exists** — create
+   one first via \`ish iteration create --url …\` (or \`--content-url …\`
+   for media studies). The error message tells you this, but the round
+   trip wastes time.
+3. **Don't pass \`--profile\` together with demographic filters** — they
+   are mutually exclusive. Either explicit IDs or
+   \`--country\`/\`--gender\`/\`--min-age\`/\`--max-age\` + \`--sample\`.
+4. **Don't change audience between rounds of an ask.** It's fixed at
+   ask creation. Use \`ish ask add-testers\` to *extend* it; you can't
+   replace it.
+5. **Don't try to put credentials in the URL** for gated study URLs.
+   Configure them once on the workspace via
+   \`ish workspace site-access …\` (basic-auth, cookie, login).
+   See \`ish docs get-page concepts/site-access\`.
+6. **Don't commit \`~/.ish/config.json\`** — it stores tokens and active
+   workspace/study/ask selections. It lives in \`$HOME\`, not the repo.
+
+## Authentication
+
+\`ish login\` opens a browser and saves tokens to \`~/.ish/config.json\`.
+The CLI also accepts \`--token <token>\` or \`ISH_TOKEN\` env var. If a
+command exits with code 3 ("auth"), tell the user to re-run \`ish login\`.
+
+## When ish is the wrong tool
+
+If the user wants to *write code* against the Ish API directly, point
+them at the API docs at https://ishlabs.io — this CLI is for
+orchestration, not as an API client library.
+
+---
+
+**Skill version:** ${VERSION}
+**Skill source of truth:** \`ish docs\` (offline, ships with the binary)
+`;
+const WORKFLOWS_MD = `# ish workflows — worked examples
+
+Each workflow below is a complete transcript an agent can adapt. Run
+\`ish docs overview\` first if you haven't already this session.
+
+## 1. First study from zero
+
+Goal: from a fresh install to a finished interactive study with 3
+testers and one question.
+
+\`\`\`bash
+# 1. Authenticate (browser flow, saves tokens to ~/.ish/config.json)
+ish login
+
+# 2. Create + select a workspace
+ish workspace create --name "Demo" --base-url https://example.com
+ish workspace use w-…
+
+# 3. Generate a small audience
+ish profile generate \\
+    --description "Tech-savvy millennials in the US who use mobile banking" \\
+    --count 3
+
+# 4. Define the study
+ish study create --name "Onboarding UX" --modality interactive \\
+    --assignment "Sign up:Complete the signup flow" \\
+    --question "How easy was it?"
+ish study use s-…
+
+# 5. Configure an iteration with the URL under test
+ish iteration create --url https://example.com
+
+# 6. Run, blocking until done
+ish study run --all --wait
+
+# 7. Read results
+ish study results --json | jq .
+\`\`\`
+
+## 2. Quick A/B ask with image variants
+
+Goal: ship 30 simulated reactions to two hero images, with a "which do
+you prefer" question.
+
+\`\`\`bash
+ish ask run --new --name "hero shots" \\
+    --prompt "Which feels more premium?" \\
+    --variant image:./hero-a.png::label=A \\
+    --variant image:./hero-b.png::label=B \\
+    --sample 30 --wants-pick --wait
+
+ish ask results --json | jq .
+\`\`\`
+
+Add a follow-up round with no audience change:
+
+\`\`\`bash
+ish ask run --prompt "Which one would you click on?" \\
+    --variant image:./hero-a.png::label=A \\
+    --variant image:./hero-b.png::label=B \\
+    --wait
+\`\`\`
+
+## 3. Generate profiles from a real source
+
+Goal: turn a customer interview transcript into a 4-profile audience.
+
+\`\`\`bash
+# Inline — auto-uploads the file:
+ish profile generate --source ./interviews/sarah.txt --count 4
+
+# Or upload once and reuse the source alias:
+ish source upload ./call.mp3 --diarize
+# → tps-3a4 (status: processed)
+ish profile generate --source tps-3a4 --propose-count
+# → { proposed_count: 4, rationale: "..." }
+ish profile generate --source tps-3a4 --count 4
+\`\`\`
+
+## 4. Target a gated URL (Vercel preview / staging gate / login form)
+
+Configure credentials once on the workspace; testers reuse them.
+
+\`\`\`bash
+# Show what's configured:
+ish workspace site-access status
+
+# HTTP basic auth:
+ish workspace site-access basic-auth --username alice --password hunter2
+
+# Session cookie (Vercel preview, Lovable, etc.):
+ish workspace site-access cookie --name session --value abc123
+
+# Login form (typed by the tester into the page):
+ish workspace site-access login --username demo --password demo
+\`\`\`
+
+Keep secrets out of shell history by passing \`-\` for \`--password\` /
+\`--value\` and piping from stdin:
+
+\`\`\`bash
+printf %s "$STAGING_PW" | ish workspace site-access basic-auth \\
+    --username alice --password -
+\`\`\`
+
+## 5. Re-run a study with a fresh audience
+
+Goal: same study, same iteration, but compare audiences.
+
+\`\`\`bash
+# First run — Swedish 35-50:
+ish study run --country SE --min-age 35 --max-age 50 --sample 5 --wait
+
+# Second run — every female profile in the workspace, same iteration:
+ish study run --gender female --all --wait
+\`\`\`
+
+If you don't pass any audience flags, \`ish study run\` reuses the
+iteration's existing testers — useful for re-running after fixing the
+target page.
+
+## 6. Localhost target (dev environment)
+
+Expose a port via a Cloudflare tunnel; \`ish connect\` prints the public
+URL the study iteration can point at. \`connect\` is foreground and
+long-running — keep it open in a separate terminal (or background it).
+
+\`\`\`bash
+# Terminal A — keep open:
+ish connect 3000
+# stdout: Tunnel URL: https://<random>.trycloudflare.com → http://localhost:3000
+
+# Terminal B — use the URL:
+ish iteration create --url https://<random>.trycloudflare.com
+ish study run --sample 3 --wait
+\`\`\`
+
+For agents/scripts, run \`connect\` in the background with \`--json\` and
+read the URL from stdout (one JSON line per state change):
+
+\`\`\`bash
+ish connect 3000 --json > /tmp/ish-tunnel.log &
+sleep 3
+URL=$(jq -r 'select(.status=="connected") | .tunnel_url' /tmp/ish-tunnel.log | head -1)
+ish iteration create --url "$URL"
+\`\`\`
+
+## Tips for chaining commands as an agent
+
+- Capture aliases from JSON: \`ITER=$(ish iteration create --url … --json | jq -r .alias)\`
+- After \`ish study run --json\`, the testers you just dispatched are at
+  \`.tester_aliases[]\` (and \`.tester_ids[]\` for UUIDs). Pass these to
+  \`ish study poll/wait/cancel <tester_id>\`.
+- Use \`--fields\` to keep JSON tight: \`ish study list --fields alias,name,status\`
+- Always pass \`--wait\` (or \`ish study wait\`) before reading
+  \`ish study results\` — without it you may read partial data.
+- For \`ask\` write-paths (update/archive/wait/add-questions/add-testers),
+  default JSON is compact (changed fields + alias). Pass \`--verbose\` for
+  the full Ask payload.
+- For \`profile generate --json\`, \`simulation_config\` is trimmed by
+  default (~9× smaller). Pass \`--include-simulation-config\` to include it.
+`;
+const COMMANDS_MD = `# ish commands — quick index
+
+This file is intentionally thin. The authoritative, always-current
+reference is \`ish docs\` (built into the binary) and per-command
+\`--help\`. Use this index only for orientation — when in doubt, run:
+
+\`\`\`bash
+ish docs list
+ish <command> --help
+\`\`\`
+
+## Top-level groups
+
+| Group       | Purpose                                         | Concept page                |
+|-------------|-------------------------------------------------|-----------------------------|
+| \`workspace\` | Top-level container (= product)                 | concepts/workspace          |
+| \`study\`     | Persistent research artifact                    | concepts/study              |
+| \`iteration\` | One configured run of a study (URL or media)    | concepts/iteration          |
+| \`ask\`       | Lightweight reaction artifact                   | concepts/ask                |
+| \`profile\`   | Tester profiles + audience generation           | concepts/profile            |
+| \`source\`    | Upload sources for profile generation           | concepts/source             |
+| \`config\`    | Simulation configs (model, timing, retries)     | (run \`ish config --help\`)   |
+| \`docs\`      | Offline docs for agents                         | (run \`ish docs --help\`)     |
+| \`init\`      | Drop this skill into a Claude Code / Codex /    | (run \`ish init --help\`)     |
+|             | Cursor / Cline / Roo project                    |                             |
+| \`login\`     | Browser-based auth                              | —                           |
+| \`logout\`    | Clear saved credentials                         | —                           |
+| \`connect\`   | Cloudflare tunnel exposing localhost            | —                           |
+| \`upgrade\`   | Self-update                                     | —                           |
+
+## Discovering flags safely
+
+Don't construct \`ish\` commands from memory for anything beyond the
+high-frequency examples. Run:
+
+\`\`\`bash
+ish <group> --help              # group-level summary + concept primer
+ish <group> <verb> --help       # exact flags for the verb
+\`\`\`
+
+Every group's \`--help\` ends with a "Concept pages" footer pointing at
+the right \`ish docs get-page <slug>\` to read deep context.
+
+## Aliases
+
+Short prefixed IDs (e.g. \`s-b2c\`, \`tp-795\`, \`a-6ec\`, \`i-d4e\`,
+\`t-a17\`, \`tps-3a4\`, \`w-6ec\`, \`c-c3c\`) are accepted anywhere a UUID
+is expected. Full UUIDs always work too. See
+\`ish docs get-page reference/aliases\`.
+
+## Output flags (global)
+
+| Flag             | Effect                                                   |
+|------------------|----------------------------------------------------------|
+| \`--json\`         | JSON output (auto-on when stdout is piped)               |
+| \`--fields a,b\`   | Keep only listed fields in JSON                          |
+| \`--verbose\`      | Include UUIDs + timestamps in JSON                       |
+| \`-q, --quiet\`    | Suppress progress messages on stderr                     |
+| \`-t, --token\`    | Auth token (else ISH_TOKEN env, else \`ish login\` saved)  |
+| \`--api-url\`      | Override backend (default https://api.ishlabs.io)        |
+
+## Exit codes
+
+\`0\` ok · \`1\` general · \`2\` usage/validation · \`3\` auth ·
+\`4\` not-found · \`5\` transient (retryable). See
+\`ish docs get-page reference/json-mode\`.
+`;
+/**
+ * Build the SKILL.md frontmatter + body. Version is stamped from the
+ * package.json at build time so users can see drift between the skill
+ * they installed and the CLI they're running.
+ */
+function buildSkillMd() {
+    const frontmatter = [
+        "---",
+        "name: ish",
+        `description: ${JSON.stringify(SKILL_DESCRIPTION)}`,
+        "license: SEE LICENSE IN LICENSE",
+        "metadata:",
+        "  author: ish",
+        `  version: ${JSON.stringify(VERSION)}`,
+        "allowed-tools: Bash(ish:*)",
+        "---",
+        "",
+    ].join("\n");
+    return frontmatter + SKILL_BODY;
+}
+/** Returns every file that makes up the bundled skill, in stable order. */
+export function buildSkillFiles() {
+    return [
+        { relativePath: "SKILL.md", contents: buildSkillMd() },
+        { relativePath: "references/workflows.md", contents: WORKFLOWS_MD },
+        { relativePath: "references/commands.md", contents: COMMANDS_MD },
+    ];
+}
+/** Convenience: just the SKILL.md content (for `ish init --stdout`). */
+export function getSkillMd() {
+    return buildSkillMd();
+}
+export const SKILL_TARGETS = [
+    {
+        key: "claude",
+        path: ".claude/skills/ish",
+        consumers: ["Claude Code", "Cursor (back-compat)"],
+    },
+    {
+        key: "agents",
+        path: ".agents/skills/ish",
+        consumers: ["Codex", "Cursor", "Cline", "Roo Code"],
+    },
+];

package/dist/lib/study-inputs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Parsers and loaders for `ish study create/update` assignment & question
+ * flags. Mirrors the loose validation style of `src/lib/ask-questions.ts`.
+ */
+import type { Assignment, InterviewQuestion } from "./types.js";
+/**
+ * Parse `"Name:Instructions"`. Splits on the first `:`, so colons inside
+ * the instructions text are preserved.
+ */
+export declare function parseAssignment(value: string): Assignment;
+/**
+ * Read a JSON file containing an array of `{name, instructions}` entries.
+ */
+export declare function loadAssignmentsFile(filePath: string): Assignment[];
+/**
+ * Parse a plain question text into a default text-typed, after-timed
+ * `InterviewQuestion`. Anything more complex (slider, likert, choice,
+ * timing=before) goes through `--questionnaire <file.json>`.
+ */
+export declare function parseQuestion(value: string): InterviewQuestion;

package/dist/lib/study-inputs.js

@@ -0,0 +1,72 @@
+/**
+ * Parsers and loaders for `ish study create/update` assignment & question
+ * flags. Mirrors the loose validation style of `src/lib/ask-questions.ts`.
+ */
+import { readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+/**
+ * Parse `"Name:Instructions"`. Splits on the first `:`, so colons inside
+ * the instructions text are preserved.
+ */
+export function parseAssignment(value) {
+    const idx = value.indexOf(":");
+    if (idx < 0) {
+        throw new Error(`Invalid --assignment "${value}". Use "Name:Instructions" (e.g. --assignment "Sign up:Complete the signup flow").`);
+    }
+    const name = value.slice(0, idx).trim();
+    const instructions = value.slice(idx + 1).trim();
+    if (!name) {
+        throw new Error(`Invalid --assignment "${value}": name is empty.`);
+    }
+    if (!instructions) {
+        throw new Error(`Invalid --assignment "${value}": instructions are empty.`);
+    }
+    return { name, instructions };
+}
+/**
+ * Read a JSON file containing an array of `{name, instructions}` entries.
+ */
+export function loadAssignmentsFile(filePath) {
+    let raw;
+    try {
+        raw = readFileSync(resolvePath(filePath), "utf-8");
+    }
+    catch {
+        throw new Error(`Cannot read assignments file: ${filePath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid JSON in assignments file: ${filePath}`);
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new Error(`Assignments file must be a non-empty JSON array: ${filePath}`);
+    }
+    for (let i = 0; i < parsed.length; i++) {
+        const a = parsed[i];
+        if (!a || typeof a !== "object") {
+            throw new Error(`assignments[${i}] must be an object with name + instructions.`);
+        }
+        if (typeof a.name !== "string" || !a.name.trim()) {
+            throw new Error(`assignments[${i}].name must be a non-empty string.`);
+        }
+        if (typeof a.instructions !== "string" || !a.instructions.trim()) {
+            throw new Error(`assignments[${i}].instructions must be a non-empty string.`);
+        }
+    }
+    return parsed;
+}
+/**
+ * Parse a plain question text into a default text-typed, after-timed
+ * `InterviewQuestion`. Anything more complex (slider, likert, choice,
+ * timing=before) goes through `--questionnaire <file.json>`.
+ */
+export function parseQuestion(value) {
+    const text = value.trim();
+    if (!text) {
+        throw new Error(`Invalid --question "": question text is empty.`);
+    }
+    return { question: text, type: "text", timing: "after" };
+}