@cookiyai/cookiy-cli 0.0.0-stage → 1.22.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cookiy AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @cookiyai/cookiy-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line client for Cookiy AI — run user research, quant surveys, and recruit participants from your terminal.
+
+## Install
+
+```bash
+# Install once (requires Node.js 18+)
+npm install -g @cookiyai/cookiy-cli
+
+# Upgrade
+npm update -g @cookiyai/cookiy-cli
+```
+
+The commands remain `cookiy` and `cookiy-cli`.
+
+If you previously installed the unscoped package, migrate with:
+
+```bash
+npm uninstall -g cookiy-cli
+npm install -g @cookiyai/cookiy-cli
+```
+
+For CI and automated tests, set `COOKIY_SKIP_UPDATE_CHECK=1` to disable background update checks and update-cache writes.
+
+## Output and request conventions
+
+- Successful V1 responses print `data` to stdout. Standard API errors print the server's `error` to stderr and exit nonzero. HTTP 401 errors additionally receive a top-level `login_url`; precedence is server top-level `login_url`, server `details.login_url`, then the CLI-derived configured-server URL. The server's `details` value is unchanged.
+- Other V1 runtime errors print JSON `{code,message,details?}` to stderr: `HTTP_<status>` for nonstandard HTTP errors, `NETWORK_ERROR` for connection failures, `REQUEST_TIMEOUT` for HTTP timeouts, and `CLI_ERROR` for unexpected exceptions. A nonstandard 401 uses `UNAUTHORIZED` with the same login hint. Local token/argument errors and help/save-token messages keep their existing text format; stderr is not universally JSON.
+- `study guide update --json` accepts both nested JSON (`'{"meta":{"sample_size":8}}'`) and dotted keys (`'{"meta.sample_size":8}'`). Dotted keys are expanded before the REST request is sent.
+- Guide updates use `--base-revision` for optimistic concurrency. The deprecated `--idempotency-key` remains optional for compatibility; the current server ignores it and does not return a receipt. After a timeout or revision conflict, get the latest guide before deciding whether another edit is needed.
+- Synthetic interviews accept `--persona` and the deprecated `--plain-text` alias. Both send the REST `persona` field; `--persona` takes precedence if both are supplied.
+- `study create` waits for the discussion guide and returns the ready canonical guide, so `study guide wait` is not supported.
+- `study report wait --study-id <id> [--timeout-ms <n>]` polls the Study activity every 15 seconds, with the final sleep capped by the remaining wait budget and followed by one last Activity request. Each HTTP request keeps the normal RPC timeout. `report_generation_in_progress` keeps waiting; `report_ready` prints the share-link response; `report_failed`, `report_not_requested`, missing states, and unknown states fail immediately. All wait failures print JSON to stderr and exit nonzero. A `WAIT_TIMEOUT` error includes the latest complete Study activity in `details`, so a calling workflow can inspect it and retry.
+- Early pipe closure (for example `| head`) is silent and preserves the command's exit status. Other output-write failures print a text diagnostic when stderr is usable and exit nonzero.
+- `quant raw-response` reads the server's JSON response and prints its `csv` field to stdout, with the CLI's usual trailing newline (also for empty CSV). Save it with `cookiy quant raw-response --survey-id 12345 > responses.csv`.

package/dist/index.js

@@ -0,0 +1,810 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/config.ts
+import os from "os";
+import path from "path";
+var VERSION = "1.22.1";
+var DEFAULT_SERVER_URL = "https://s-api.cookiy.ai";
+var API_RPC_TIMEOUT = parseInt(
+  process.env.COOKIY_API_RPC_TIMEOUT || "600",
+  10
+);
+var runtime = {
+  tokenPath: process.env.COOKIY_CREDENTIALS || path.join(os.homedir(), ".cookiy", "token.txt"),
+  accessToken: ""
+};
+function resolveServerBase() {
+  return process.env.COOKIY_SERVER_URL || DEFAULT_SERVER_URL;
+}
+function resolveLoginUrl() {
+  return `${resolveServerBase()}/oauth/cli/start`;
+}
+
+// src/auth.ts
+import fs from "fs";
+import path2 from "path";
+
+// src/util.ts
+var CliError = class extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "CliError";
+  }
+  code;
+  details;
+};
+function writeFully(stream, text) {
+  const output = text.endsWith("\n") ? text : `${text}
+`;
+  return new Promise((resolve, reject) => {
+    stream.once("error", reject);
+    stream.write(output, (error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      stream.removeListener("error", reject);
+      resolve();
+    });
+  });
+}
+async function exitWithOutput(options) {
+  try {
+    if (options.stdout !== void 0) {
+      await writeFully(process.stdout, options.stdout);
+    }
+    if (options.stderr !== void 0) {
+      await writeFully(process.stderr, options.stderr);
+    }
+  } catch (error) {
+    if (error?.code === "EPIPE") {
+      process.exit(options.code);
+    }
+    if (!process.stderr.destroyed) {
+      try {
+        await writeFully(process.stderr, `Failed to write output: ${error instanceof Error ? error.message : String(error)}`);
+      } catch {
+      }
+    }
+    process.exit(options.code === 0 ? 1 : options.code);
+  }
+  process.exit(options.code);
+}
+function die(msg, code = 1) {
+  console.error(msg);
+  process.exit(code);
+}
+function dieNoAccess(_detail) {
+  die(`Access denied \u2014 token is missing or expired.
+Sign in:  ${resolveLoginUrl()}`);
+}
+function parseIntOption(name) {
+  return (val) => {
+    if (!/^-?\d+$/.test(val)) die(`--${name} requires an integer, got: ${val}`);
+    return parseInt(val, 10);
+  };
+}
+function parseJsonArrayOption(name) {
+  return (val) => {
+    let parsed;
+    try {
+      parsed = JSON.parse(val);
+    } catch {
+      die(`--${name} requires a JSON array, got: ${val}`);
+    }
+    if (!Array.isArray(parsed)) die(`--${name} requires a JSON array, got: ${val}`);
+    return parsed;
+  };
+}
+function parseJsonObjectOption(name) {
+  return (val) => {
+    let parsed;
+    try {
+      parsed = JSON.parse(val);
+    } catch {
+      die(`--${name} requires a JSON object, got: ${val}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      die(`--${name} requires a JSON object, got: ${val}`);
+    }
+    return parsed;
+  };
+}
+function mergeRawJson(payload, rawJson, name = "json") {
+  if (!rawJson) return payload;
+  try {
+    const extra = JSON.parse(rawJson);
+    if (typeof extra !== "object" || extra === null || Array.isArray(extra)) {
+      die(`--${name} requires a JSON object`);
+    }
+    return { ...payload, ...extra };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    die(`Invalid --${name} value: ${msg}`);
+  }
+}
+
+// src/auth.ts
+function loadCredentials() {
+  if (!fs.existsSync(runtime.tokenPath)) dieNoAccess();
+  runtime.accessToken = fs.readFileSync(runtime.tokenPath, "utf8").replace(/\r?\n/g, "").trim();
+  if (!runtime.accessToken) dieNoAccess();
+}
+async function runSaveToken(input) {
+  const raw = input.trim();
+  if (!raw) die("Usage: cookiy save-token <access_token_or_json>");
+  let at = "";
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed.access_token) at = parsed.access_token;
+  } catch {
+    at = raw;
+  }
+  if (!at) die("Could not find access_token in input.");
+  try {
+    const dir = path2.dirname(runtime.tokenPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(runtime.tokenPath, at, { mode: 384 });
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    die(`[save-token] failed to write ${runtime.tokenPath}: ${msg}`);
+  }
+  console.error(`Token saved to ${runtime.tokenPath}`);
+}
+
+// src/update-check.ts
+import fs2 from "fs";
+import path3 from "path";
+import os2 from "os";
+import { spawn } from "child_process";
+var CACHE_FILE = path3.join(os2.homedir(), ".cookiy", "update-check");
+var INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var PROBE_SCRIPT = `
+const https = require('https');
+const { spawn } = require('child_process');
+const current = ${JSON.stringify(VERSION)};
+function gt(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const ai = pa[i] || 0, bi = pb[i] || 0;
+    if (ai > bi) return true;
+    if (ai < bi) return false;
+  }
+  return false;
+}
+const req = https.get(
+  'https://registry.npmjs.org/@cookiyai%2Fcookiy-cli/latest',
+  { timeout: 3000, headers: { Accept: 'application/json' } },
+  (res) => {
+    let body = '';
+    res.on('data', (c) => (body += c));
+    res.on('end', () => {
+      try {
+        const latest = JSON.parse(body).version;
+        if (typeof latest !== 'string' || !gt(latest, current)) return;
+        const child = spawn(
+          'npm',
+          ['install', '-g', '--silent', '--no-audit', '--no-fund', '@cookiyai/cookiy-cli@' + latest],
+          { detached: true, stdio: 'ignore', windowsHide: true },
+        );
+        child.unref();
+      } catch (_) {}
+    });
+  },
+);
+req.on('error', () => {});
+req.on('timeout', () => req.destroy());
+`;
+function scheduleBackgroundUpdate() {
+  if (process.env.COOKIY_SKIP_UPDATE_CHECK === "1") return;
+  try {
+    const now = Date.now();
+    if (fs2.existsSync(CACHE_FILE)) {
+      const last = parseInt(fs2.readFileSync(CACHE_FILE, "utf8"), 10) || 0;
+      if (now - last < INTERVAL_MS) return;
+    }
+    fs2.mkdirSync(path3.dirname(CACHE_FILE), { recursive: true });
+    fs2.writeFileSync(CACHE_FILE, String(now));
+    const child = spawn(process.execPath, ["-e", PROBE_SCRIPT], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true
+    });
+    child.unref();
+  } catch {
+  }
+}
+
+// src/v1Client.ts
+var V1RequestError = class extends Error {
+  constructor(status, message, body, details) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.details = details;
+    this.name = "V1RequestError";
+  }
+  status;
+  body;
+  details;
+};
+var MAX_BODY_LEN = 500;
+function truncate(s) {
+  if (s.length <= MAX_BODY_LEN) return s;
+  const dropped = s.length - MAX_BODY_LEN;
+  return `${s.slice(0, MAX_BODY_LEN)}
+\u2026 (truncated, ${dropped} more chars)`;
+}
+function summarizeHtml(s) {
+  const title = s.match(/<title[^>]*>\s*([^<]+?)\s*<\/title>/i)?.[1];
+  const h1 = s.match(/<h1[^>]*>\s*([^<]+?)\s*<\/h1>/i)?.[1];
+  const summary = (title ?? h1)?.trim();
+  if (summary) return `(HTML body) ${summary}`;
+  return `(HTML body, ${s.length} chars suppressed)`;
+}
+function formatBody(parsed, text) {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  if (parsed && typeof parsed === "object") {
+    return truncate(JSON.stringify(parsed, null, 2));
+  }
+  if (/^\s*<(!doctype|html\b|head\b|body\b)/i.test(trimmed)) {
+    return summarizeHtml(trimmed);
+  }
+  return truncate(trimmed);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolveErrorLoginUrl(error) {
+  if (typeof error.login_url === "string") return error.login_url;
+  if (isRecord(error.details) && typeof error.details.login_url === "string") {
+    return error.details.login_url;
+  }
+  return resolveLoginUrl();
+}
+function unwrapSuccessResponse(value) {
+  return isRecord(value) && value.ok === true && Object.hasOwn(value, "data") ? value.data : value;
+}
+function extractApiError(value) {
+  return isRecord(value) && value.ok === false && Object.hasOwn(value, "error") ? value.error : void 0;
+}
+function buildUrl(path4, query) {
+  const base = resolveServerBase().replace(/\/$/, "");
+  const rel = path4.startsWith("/") ? path4 : `/${path4}`;
+  const url = new URL(`${base}/api${rel}`);
+  if (query) {
+    for (const [k, v] of Object.entries(query)) {
+      if (v === void 0 || v === null) continue;
+      url.searchParams.set(k, String(v));
+    }
+  }
+  return url.toString();
+}
+async function request(method, path4, opts) {
+  const url = buildUrl(path4, opts?.query);
+  const controller = new AbortController();
+  let timedOut = false;
+  const timeoutId = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, API_RPC_TIMEOUT * 1e3);
+  try {
+    const headers = {
+      Accept: "application/json",
+      Authorization: `Bearer ${runtime.accessToken}`
+    };
+    if (opts?.body !== void 0) headers["Content-Type"] = "application/json";
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: opts?.body !== void 0 ? JSON.stringify(opts.body) : void 0,
+      signal: controller.signal
+    });
+    const text = await res.text();
+    let parsed = void 0;
+    if (text.trim()) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+    if (res.status < 200 || res.status >= 300) {
+      const bodyDisplay = formatBody(parsed, text);
+      const serverMessage = parsed && typeof parsed === "object" ? parsed.message : void 0;
+      const head = `[HTTP ${res.status}]`;
+      const msg = serverMessage ? `${head} ${String(serverMessage)}` : head;
+      throw new V1RequestError(res.status, msg, parsed, bodyDisplay ?? void 0);
+    }
+    return unwrapSuccessResponse(parsed);
+  } catch (e) {
+    if (e instanceof V1RequestError) throw e;
+    if (timedOut) {
+      throw new CliError("REQUEST_TIMEOUT", `[timeout ${API_RPC_TIMEOUT}s]`);
+    }
+    const err = e;
+    const reason = err?.cause?.code ?? err?.cause?.message ?? err?.message ?? String(e);
+    throw new CliError("NETWORK_ERROR", `[fetch error] ${reason}`);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+var v1 = {
+  get: (path4, query) => request("GET", path4, { query }),
+  post: (path4, body) => request("POST", path4, { body }),
+  patch: (path4, body) => request("PATCH", path4, { body }),
+  delete: (path4) => request("DELETE", path4)
+};
+async function runV1(fn) {
+  try {
+    const result = await fn();
+    return exitWithOutput({
+      code: 0,
+      stdout: result === void 0 ? void 0 : typeof result === "string" ? result : JSON.stringify(result, null, 2)
+    });
+  } catch (e) {
+    let error;
+    if (e instanceof V1RequestError) {
+      error = extractApiError(e.body);
+      if (error === void 0) {
+        error = e.status === 401 ? {
+          code: "UNAUTHORIZED",
+          message: "Access denied \u2014 token is missing or expired."
+        } : { code: `HTTP_${e.status}`, message: e.message, details: e.details };
+      }
+      if (e.status === 401 && isRecord(error)) {
+        error = { ...error, login_url: resolveErrorLoginUrl(error) };
+      }
+    } else if (e instanceof CliError) {
+      error = { code: e.code, message: e.message, details: e.details };
+    } else {
+      error = { code: "CLI_ERROR", message: e instanceof Error ? e.message : String(e) };
+    }
+    return exitWithOutput({
+      code: 1,
+      stderr: JSON.stringify(error, null, 2)
+    });
+  }
+}
+
+// src/commands/study.ts
+var REPORT_POLL_INTERVAL_MS = 15e3;
+function expandDottedKeys(input, result = /* @__PURE__ */ Object.create(null), prefix = "") {
+  for (const [key, value] of Object.entries(input)) {
+    const patchPath = prefix ? `${prefix}.${key}` : key;
+    const parts = key.split(".");
+    let cursor = result;
+    for (const part of parts.slice(0, -1)) {
+      if (cursor[part] === null || typeof cursor[part] !== "object" || Array.isArray(cursor[part])) {
+        if (Object.hasOwn(cursor, part)) die(`Conflicting patch path: ${patchPath}`);
+        cursor[part] = /* @__PURE__ */ Object.create(null);
+      }
+      cursor = cursor[part];
+    }
+    const lastPart = parts.at(-1);
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      if (cursor[lastPart] === null || typeof cursor[lastPart] !== "object" || Array.isArray(cursor[lastPart])) {
+        if (Object.hasOwn(cursor, lastPart)) die(`Conflicting patch path: ${patchPath}`);
+        cursor[lastPart] = /* @__PURE__ */ Object.create(null);
+      }
+      expandDottedKeys(
+        value,
+        cursor[lastPart],
+        patchPath
+      );
+    } else {
+      if (Object.hasOwn(cursor, lastPart)) die(`Conflicting patch path: ${patchPath}`);
+      cursor[lastPart] = value;
+    }
+  }
+  return result;
+}
+async function waitForReport(studyId, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    const activity = await v1.get(`/v1/studies/${studyId}/activity`);
+    const report = activity?.sources?.report ?? {};
+    const status = typeof report.status === "string" ? report.status : "";
+    if (status === "report_ready") {
+      return v1.post(`/v1/studies/${studyId}/report/share-link`, {});
+    }
+    if (status === "report_failed") {
+      throw new CliError(
+        "GENERATION_FAILED",
+        "Report generation failed",
+        report
+      );
+    }
+    if (status === "report_not_requested") {
+      throw new CliError(
+        "REPORT_NOT_REQUESTED",
+        "Report generation has not been requested",
+        report
+      );
+    }
+    if (status !== "report_generation_in_progress") {
+      throw new CliError(
+        "UNEXPECTED_STATUS",
+        `Unexpected report status: ${status || "(missing)"}`,
+        report
+      );
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      throw new CliError("WAIT_TIMEOUT", `Timed out after ${timeoutMs}ms`, activity);
+    }
+    const sleepMs = Math.min(REPORT_POLL_INTERVAL_MS, remaining);
+    await new Promise((resolve) => setTimeout(resolve, sleepMs));
+  }
+}
+function registerStudy(program2) {
+  const study = program2.command("study").description("Studies: list, create, status, guide, interview, report, upload");
+  study.command("list").description("list studies").option("--limit <n>", "max items", parseIntOption("limit")).option("--cursor <s>", "pagination cursor").action(async (opts) => {
+    const query = {};
+    if (opts.limit !== void 0) query.limit = opts.limit;
+    if (opts.cursor) query.cursor = opts.cursor;
+    await runV1(() => v1.get("/v1/studies", query));
+  });
+  study.command("status").description("study record and activity").requiredOption("--study-id <uuid>", "study id").action(async (opts) => {
+    await runV1(
+      () => v1.get(`/v1/studies/${encodeURIComponent(opts.studyId)}/activity`)
+    );
+  });
+  study.command("create").description("create study from natural language").requiredOption("--query <s>", "natural-language brief").option("--thinking <s>", "thinking / scratch notes").option(
+    "--attachments <json-array>",
+    `JSON array, e.g. '[{"s3_key":"..."}]'`,
+    parseJsonArrayOption("attachments")
+  ).option("--json <obj>", "extra JSON fields merged into request").action(
+    async (opts) => {
+      let payload = { query: opts.query };
+      if (opts.thinking !== void 0) payload.thinking = opts.thinking;
+      if (opts.attachments !== void 0) payload.attachments = opts.attachments;
+      payload = mergeRawJson(payload, opts.json);
+      await runV1(() => v1.post("/v1/studies", payload));
+    }
+  );
+  study.command("upload").description("attach media (image upload)").requiredOption("--content-type <s>", "MIME content type").option("--image-data <s>", "base64 image data").option("--image-url <s>", "image url").action(
+    async (opts) => {
+      if (!opts.imageData && !opts.imageUrl) {
+        die("study upload requires --image-data or --image-url");
+      }
+      const body = { content_type: opts.contentType };
+      if (opts.imageData) body.image_data = opts.imageData;
+      if (opts.imageUrl) body.image_url = opts.imageUrl;
+      await runV1(() => v1.post("/v1/studies/media/upload", body));
+    }
+  );
+  const guide = study.command("guide").description("discussion guide: get | update");
+  guide.command("get").description("get discussion guide").requiredOption("--study-id <uuid>", "study id").action(async (opts) => {
+    await runV1(
+      () => v1.get(
+        `/v1/studies/${encodeURIComponent(opts.studyId)}/discussion-guide`
+      )
+    );
+  });
+  guide.command("update").description("apply patch to discussion guide").requiredOption("--study-id <uuid>", "study id").requiredOption("--base-revision <s>", "base revision").option("--idempotency-key <s>", "legacy compatibility only; guide updates use base revision").option("--change-message <s>", "change message").requiredOption(
+    "--json <patch>",
+    "patch JSON object (required)",
+    parseJsonObjectOption("json")
+  ).action(
+    async (opts) => {
+      const body = {
+        base_revision: opts.baseRevision,
+        patch: expandDottedKeys(opts.json)
+      };
+      if (opts.idempotencyKey !== void 0)
+        body.idempotency_key = opts.idempotencyKey;
+      if (opts.changeMessage !== void 0)
+        body.change_message = opts.changeMessage;
+      await runV1(
+        () => v1.patch(
+          `/v1/studies/${encodeURIComponent(opts.studyId)}/discussion-guide`,
+          body
+        )
+      );
+    }
+  );
+  const interview = study.command("interview").description("interviews: list | playback");
+  interview.command("list").description("list interviews (includes synthetic)").requiredOption("--study-id <uuid>", "study id").option("--cursor <s>", "pagination cursor").action(async (opts) => {
+    const query = { include_simulation: "true" };
+    if (opts.cursor) query.cursor = opts.cursor;
+    await runV1(
+      () => v1.get(
+        `/v1/studies/${encodeURIComponent(opts.studyId)}/interviews`,
+        query
+      )
+    );
+  });
+  const playback = interview.command("playback").description("interview playback: url | content");
+  playback.command("url").description("playback recording URL (all interviews if --interview-id omitted)").requiredOption("--study-id <uuid>", "study id").option("--interview-id <uuid>", "specific interview (omit to fetch all)").action(
+    async (opts) => {
+      const query = { view: "url" };
+      if (opts.interviewId) query.interview_id = opts.interviewId;
+      await runV1(
+        () => v1.get(
+          `/v1/studies/${encodeURIComponent(opts.studyId)}/interviews/playback`,
+          query
+        )
+      );
+    }
+  );
+  playback.command("content").description("playback transcript content (all interviews if --interview-id omitted)").requiredOption("--study-id <uuid>", "study id").option("--interview-id <uuid>", "specific interview (omit to fetch all)").action(
+    async (opts) => {
+      const query = { view: "transcript" };
+      if (opts.interviewId) query.interview_id = opts.interviewId;
+      await runV1(
+        () => v1.get(
+          `/v1/studies/${encodeURIComponent(opts.studyId)}/interviews/playback`,
+          query
+        )
+      );
+    }
+  );
+  const synthetic = study.command("run-synthetic-user").description("synthetic user interviews");
+  synthetic.command("start").description("start synthetic interviews").requiredOption("--study-id <uuid>", "study id").option(
+    "--persona-count <n>",
+    "number of personas",
+    parseIntOption("persona-count")
+  ).option("--persona <s>", "persona / profile description").option("--plain-text <s>", "deprecated alias for --persona").action(
+    async (opts) => {
+      const body = {};
+      if (opts.personaCount !== void 0) body.persona_count = opts.personaCount;
+      const persona = opts.persona ?? opts.plainText;
+      if (persona !== void 0) body.persona = persona;
+      await runV1(
+        () => v1.post(
+          `/v1/studies/${encodeURIComponent(opts.studyId)}/fake-interview`,
+          body
+        )
+      );
+    }
+  );
+  const report = study.command("report").description("study report: generate | content | link | wait");
+  report.command("generate").description("generate report").requiredOption("--study-id <uuid>", "study id").option("--skip-synthetic-interview", "skip synthetic interview step", false).action(
+    async (opts) => {
+      const body = {};
+      if (opts.skipSyntheticInterview) body.skip_synthetic_interview = true;
+      await runV1(
+        () => v1.post(
+          `/v1/studies/${encodeURIComponent(opts.studyId)}/report/generate`,
+          body
+        )
+      );
+    }
+  );
+  report.command("content").description("report content JSON").requiredOption("--study-id <uuid>", "study id").action(async (opts) => {
+    await runV1(
+      () => v1.get(
+        `/v1/studies/${encodeURIComponent(opts.studyId)}/report/content`
+      )
+    );
+  });
+  report.command("link").description("report share link").requiredOption("--study-id <uuid>", "study id").action(async (opts) => {
+    await runV1(
+      () => v1.post(
+        `/v1/studies/${encodeURIComponent(opts.studyId)}/report/share-link`,
+        {}
+      )
+    );
+  });
+  report.command("wait").description("wait for report generation, then print its share link").requiredOption("--study-id <uuid>", "study id").option(
+    "--timeout-ms <n>",
+    "polling timeout in ms (default 300000)",
+    parseIntOption("timeout-ms"),
+    3e5
+  ).action(async (opts) => {
+    if (opts.timeoutMs <= 0) {
+      die("--timeout-ms requires a positive integer");
+    }
+    await runV1(
+      () => waitForReport(encodeURIComponent(opts.studyId), opts.timeoutMs)
+    );
+  });
+}
+
+// src/commands/quant.ts
+function registerQuant(program2) {
+  const quant = program2.command("quant").description(
+    "Quantitative surveys: list, create, get, update, status, report, raw-response"
+  );
+  quant.command("list").description("list surveys visible to operator").action(async () => {
+    await runV1(() => v1.get("/v1/quant/surveys"));
+  });
+  quant.command("create").description("create survey (multi-language)").requiredOption(
+    "--json <obj>",
+    "JSON object: survey_title, languages[], groups[], quotas[], ...",
+    parseJsonObjectOption("json")
+  ).action(async (opts) => {
+    await runV1(() => v1.post("/v1/quant/surveys", opts.json));
+  });
+  quant.command("get").description("survey detail").requiredOption("--survey-id <id>", "numeric sid").option("--language <lang>", "language code").action(async (opts) => {
+    const query = {};
+    if (opts.language) query.language = opts.language;
+    await runV1(
+      () => v1.get(`/v1/quant/surveys/${encodeURIComponent(opts.surveyId)}`, query)
+    );
+  });
+  quant.command("update").description("patch survey").requiredOption("--survey-id <id>", "numeric sid").requiredOption(
+    "--json <obj>",
+    "JSON object with survey/groups/questions/quotas_*",
+    parseJsonObjectOption("json")
+  ).action(
+    async (opts) => {
+      await runV1(
+        () => v1.patch(
+          `/v1/quant/surveys/${encodeURIComponent(opts.surveyId)}`,
+          opts.json
+        )
+      );
+    }
+  );
+  quant.command("status").description("combined survey + recruit status").requiredOption("--survey-id <id>", "numeric sid").action(async (opts) => {
+    await runV1(
+      () => v1.get(
+        `/v1/quant/surveys/${encodeURIComponent(opts.surveyId)}/status`
+      )
+    );
+  });
+  quant.command("report").description("survey report (structured JSON + raw)").requiredOption("--survey-id <id>", "numeric sid").action(async (opts) => {
+    await runV1(
+      () => v1.get(
+        `/v1/quant/surveys/${encodeURIComponent(opts.surveyId)}/report`
+      )
+    );
+  });
+  quant.command("raw-response").description("raw survey responses as CSV").requiredOption("--survey-id <id>", "numeric sid").option("--include-incomplete", "include incomplete responses", false).action(
+    async (opts) => {
+      const query = {
+        only_completed: !opts.includeIncomplete
+      };
+      await runV1(async () => {
+        const result = await v1.get(
+          `/v1/quant/surveys/${encodeURIComponent(opts.surveyId)}/raw-responses`,
+          query
+        );
+        if (typeof result !== "object" || result === null || !("csv" in result) || typeof result.csv !== "string") {
+          throw new CliError("INVALID_RESPONSE", "Quant raw-response must contain a string csv field.");
+        }
+        return result.csv;
+      });
+    }
+  );
+}
+
+// src/commands/recruit.ts
+function registerRecruit(program2) {
+  const recruit = program2.command("recruit").description("Participant recruitment (auto-detects qualitative vs quant)");
+  recruit.command("start").description("launch recruitment (or incrementally add participants)").option("--study-id <uuid>", "study id (required for interview studies)").option(
+    "--survey-public-url <url>",
+    "public survey URL (auto-selects quant mode)"
+  ).option("--confirmation-token <s>", "step-2 confirmation token").option("--plain-text <s>", "audience description / free-text brief").option(
+    "--incremental-participants <n>",
+    "add N participants on top of existing",
+    parseIntOption("incremental-participants")
+  ).action(
+    async (opts) => {
+      if (!opts.confirmationToken && !opts.plainText) {
+        die("recruit start: --plain-text is required");
+      }
+      const isStudyBased = !!opts.studyId;
+      const isQuantOnly = !isStudyBased && !!opts.surveyPublicUrl;
+      if (!isStudyBased && !isQuantOnly) {
+        die(
+          "recruit start: either --study-id or --survey-public-url is required"
+        );
+      }
+      const body = { force_reconfigure: true };
+      if (opts.confirmationToken) body.confirmation_token = opts.confirmationToken;
+      if (opts.plainText !== void 0) body.plain_text = opts.plainText;
+      if (opts.incrementalParticipants !== void 0) {
+        body.incremental_participants = opts.incrementalParticipants;
+      }
+      const step = opts.confirmationToken ? "confirm" : "preview";
+      let path4;
+      if (isStudyBased) {
+        path4 = `/v1/studies/${encodeURIComponent(opts.studyId)}/recruit/${step}`;
+      } else {
+        body.survey_public_url = opts.surveyPublicUrl;
+        path4 = `/v1/quant/recruit/${step}`;
+      }
+      await runV1(() => v1.post(path4, body));
+    }
+  );
+}
+
+// src/commands/billing.ts
+function registerBilling(program2) {
+  const billing = program2.command("billing").description("Billing: balance, checkout, price-table, transactions");
+  billing.command("balance").description("one-line balance summary").action(async () => {
+    await runV1(() => v1.get("/v1/billing/balance"));
+  });
+  billing.command("checkout").description("create Stripe checkout session").requiredOption(
+    "--amount-usd-cents <n>",
+    "USD cents (min 100). Internally mapped to amount_cents.",
+    parseIntOption("amount-usd-cents")
+  ).action(async (opts) => {
+    await runV1(
+      () => v1.post("/v1/billing/cash-credit/checkout", {
+        amount_cents: opts.amountUsdCents
+      })
+    );
+  });
+  billing.command("price-table").description("current pricing table").action(async () => {
+    await runV1(() => v1.get("/v1/billing/price-table"));
+  });
+  billing.command("transactions").description("wallet ledger").option("--limit <n>", "max items", parseIntOption("limit")).option("--cursor <iso8601>", "pagination cursor").option("--study-id <uuid>", "filter by study").option("--survey-id <id>", "filter by survey sid (sent as string)").action(
+    async (opts) => {
+      const query = {};
+      if (opts.limit !== void 0) query.limit = opts.limit;
+      if (opts.cursor) query.cursor = opts.cursor;
+      if (opts.studyId) query.study_id = opts.studyId;
+      if (opts.surveyId !== void 0) query.survey_id = String(opts.surveyId);
+      await runV1(() => v1.get("/v1/billing/transactions", query));
+    }
+  );
+}
+
+// src/commands/user.ts
+function registerUser(program2) {
+  const user = program2.command("user").description("User: info");
+  user.command("info").description("current user API metadata").action(async () => {
+    await runV1(() => v1.get("/v1/user/info"));
+  });
+}
+
+// src/index.ts
+scheduleBackgroundUpdate();
+var program = new Command();
+program.helpCommand(false);
+program.name("cookiy").description(
+  "Cookiy CLI - command-line client for Cookiy AI, end-to-end user research at scale."
+).version(VERSION, "-v, --version", "Output the version number").option("--token <path>", "Token file path (default ~/.cookiy/token.txt)").showHelpAfterError('(run "cookiy --help" for usage)').addHelpText(
+  "after",
+  `
+Examples:
+  $ cookiy save-token eyJhbGciOi...
+  $ cookiy study list --limit 10
+  $ cookiy study create --query "..."
+  $ cookiy study report generate --study-id 123
+  $ cookiy quant list
+  $ cookiy user info
+  $ cookiy billing transactions --limit 50
+
+Sign in:  https://s-api.cookiy.ai/oauth/cli/start`
+);
+program.hook("preAction", (_thisCmd, actionCmd) => {
+  const g = program.opts();
+  if (g.token) runtime.tokenPath = g.token;
+  if (actionCmd.name() === "save-token") return;
+  loadCredentials();
+});
+program.command("save-token").description("Validate and save an access token (from browser sign-in)").argument(
+  "<token_or_json>",
+  "raw access_token string or JSON with access_token field"
+).action(async (input) => {
+  const g = program.opts();
+  if (g.token) runtime.tokenPath = g.token;
+  await runSaveToken(input);
+});
+registerStudy(program);
+registerQuant(program);
+registerRecruit(program);
+registerBilling(program);
+registerUser(program);
+function disableHelpCommand(cmd) {
+  cmd.helpCommand(false);
+  for (const sub of cmd.commands) disableHelpCommand(sub);
+}
+disableHelpCommand(program);
+program.parseAsync(process.argv).catch((e) => {
+  const msg = e instanceof Error ? e.message : String(e);
+  console.error(msg);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@cookiyai/cookiy-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.22.1",
+  "description": "Cookiy AI CLI — end-to-end user research from your terminal: AI interviews, synthetic users, quant surveys, participant recruitment.",
+  "keywords": [
+    "cookiy",
+    "cli",
+    "user-research",
+    "ux-research",
+    "interview",
+    "survey",
+    "synthetic-user",
+    "ai",
+    "agent",
+    "ai-agent",
+    "claude",
+    "claude-code",
+    "cursor",
+    "codex",
+    "openclaw",
+    "windsurf",
+    "manus",
+    "cline"
+  ],
+  "homepage": "https://cookiy.ai",
+  "bugs": {
+    "url": "https://github.com/cookiy-ai/cookiy-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cookiy-ai/cookiy-cli.git"
+  },
+  "license": "MIT",
+  "author": "Cookiy AI <info@cookiy.com>",
+  "type": "module",
+  "bin": {
+    "cookiy": "dist/index.js",
+    "cookiy-cli": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "test": "npm run build && vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.5"
+  }
+}