npm - @ishlabs/cli - Versions diffs - 0.17.7 → 0.19.0 - Mend

@ishlabs/cli 0.17.7 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (64) hide show

package/README.md +54 -54
package/dist/commands/ask.d.ts +4 -4
package/dist/commands/ask.js +66 -66
package/dist/commands/chat.js +10 -10
package/dist/commands/config.js +1 -1
package/dist/commands/docs.js +1 -1
package/dist/commands/iteration.js +57 -57
package/dist/commands/mcp.d.ts +23 -0
package/dist/commands/mcp.js +676 -0
package/dist/commands/person.d.ts +5 -0
package/dist/commands/{profile.js → person.js} +197 -162
package/dist/commands/source.d.ts +6 -2
package/dist/commands/source.js +35 -30
package/dist/commands/study-analyze.d.ts +1 -1
package/dist/commands/study-analyze.js +3 -3
package/dist/commands/study-participant.d.ts +8 -0
package/dist/commands/{study-tester.js → study-participant.js} +50 -50
package/dist/commands/study-run.d.ts +6 -6
package/dist/commands/study-run.js +341 -290
package/dist/commands/study.js +106 -72
package/dist/commands/workspace.js +13 -13
package/dist/connect.js +5 -5
package/dist/index.js +6 -4
package/dist/lib/accessibility-profile.d.ts +1 -1
package/dist/lib/accessibility-profile.js +1 -1
package/dist/lib/alias-hydrate.js +4 -4
package/dist/lib/alias-store.d.ts +5 -5
package/dist/lib/alias-store.js +8 -8
package/dist/lib/api-client.d.ts +1 -1
package/dist/lib/api-client.js +1 -1
package/dist/lib/billing.d.ts +11 -11
package/dist/lib/billing.js +16 -16
package/dist/lib/chat-endpoint-templates.js +1 -1
package/dist/lib/command-helpers.d.ts +18 -18
package/dist/lib/command-helpers.js +49 -37
package/dist/lib/docs.js +570 -387
package/dist/lib/enums.d.ts +2 -2
package/dist/lib/enums.js +2 -2
package/dist/lib/local-sim/browser.d.ts +1 -1
package/dist/lib/local-sim/browser.js +1 -1
package/dist/lib/local-sim/debug-report.d.ts +2 -2
package/dist/lib/local-sim/debug-report.js +3 -3
package/dist/lib/local-sim/loop.d.ts +5 -5
package/dist/lib/local-sim/loop.js +38 -38
package/dist/lib/local-sim/types.d.ts +12 -12
package/dist/lib/mcp-clients.d.ts +51 -0
package/dist/lib/mcp-clients.js +175 -0
package/dist/lib/modality.d.ts +10 -10
package/dist/lib/modality.js +46 -46
package/dist/lib/output.d.ts +16 -15
package/dist/lib/output.js +291 -226
package/dist/lib/profile-sources.d.ts +64 -16
package/dist/lib/profile-sources.js +91 -30
package/dist/lib/skill-content.js +216 -168
package/dist/lib/study-events.d.ts +3 -3
package/dist/lib/study-events.js +1 -1
package/dist/lib/study-inputs.d.ts +11 -1
package/dist/lib/study-inputs.js +68 -17
package/dist/lib/study-participants.d.ts +32 -0
package/dist/lib/study-participants.js +12 -0
package/dist/lib/types.d.ts +104 -34
package/package.json +1 -1
package/dist/commands/profile.d.ts +0 -5
package/dist/commands/study-tester.d.ts +0 -8

package/dist/lib/enums.d.ts CHANGED Viewed

@@ -3,7 +3,7 @@
  *
  * Agents (and humans) reach for hyphen-style values on the command line —
  * `--screen-format mobile-portrait`, `--kind text-file`, `--chat-mode
- * tester-pair` — even when the canonical backend value is underscored (or
+ * participant-pair` — even when the canonical backend value is underscored (or
  * vice versa for the ask-question `type` field, which is hyphenated). Rather
  * than fail with a 422, each parse site funnels the raw value through
  * `normalizeEnumValue` and gets back the canonical form (or `null` for a
@@ -32,7 +32,7 @@ export type ScreenFormat = typeof SCREEN_FORMATS[number];
 export declare const QUESTION_TYPES: readonly ["text", "slider", "likert", "single-choice", "multiple-choice", "number"];
 export type QuestionType = typeof QUESTION_TYPES[number];
 /**
- * TesterProfile structured enums (profile-enums.v1.json). Values are
+ * Person structured enums (profile-enums.v1.json). Values are
  * snake_case and match the spec byte-for-byte; agents pass them verbatim
  * via CLI flags.
  */

package/dist/lib/enums.js CHANGED Viewed

@@ -3,7 +3,7 @@
  *
  * Agents (and humans) reach for hyphen-style values on the command line —
  * `--screen-format mobile-portrait`, `--kind text-file`, `--chat-mode
- * tester-pair` — even when the canonical backend value is underscored (or
+ * participant-pair` — even when the canonical backend value is underscored (or
  * vice versa for the ask-question `type` field, which is hyphenated). Rather
  * than fail with a 422, each parse site funnels the raw value through
  * `normalizeEnumValue` and gets back the canonical form (or `null` for a
@@ -46,7 +46,7 @@ export const QUESTION_TYPES = [
     "number",
 ];
 /**
- * TesterProfile structured enums (profile-enums.v1.json). Values are
+ * Person structured enums (profile-enums.v1.json). Values are
  * snake_case and match the spec byte-for-byte; agents pass them verbatim
  * via CLI flags.
  */

package/dist/lib/local-sim/browser.d.ts CHANGED Viewed

@@ -23,7 +23,7 @@ export declare function launchSharedBrowser(opts: LocalSimBrowserOptions): Promi
  */
 export declare function createTab(browser: Browser, opts: LocalSimBrowserOptions): Promise<BrowserSession>;
 /**
- * Launch a standalone browser session (single tester, owns the browser).
+ * Launch a standalone browser session (single participant, owns the browser).
  */
 export declare function launchBrowser(opts: LocalSimBrowserOptions): Promise<BrowserSession>;
 export interface ObservationData {

package/dist/lib/local-sim/browser.js CHANGED Viewed

@@ -76,7 +76,7 @@ export async function createTab(browser, opts) {
     return { browser, context, page };
 }
 /**
- * Launch a standalone browser session (single tester, owns the browser).
+ * Launch a standalone browser session (single participant, owns the browser).
  */
 export async function launchBrowser(opts) {
     const browser = await launchSharedBrowser(opts);

package/dist/lib/local-sim/debug-report.d.ts CHANGED Viewed

@@ -7,8 +7,8 @@
 import type { DebugStep } from "./loop.js";
 export type { DebugStep };
 export interface DebugReportMeta {
-    testerId: string;
-    testerName: string;
+    participantId: string;
+    participantName: string;
     url: string;
     screenFormat: string;
     finalStatus: string;

package/dist/lib/local-sim/debug-report.js CHANGED Viewed

@@ -28,7 +28,7 @@ export function generateDebugReport(steps, meta) {
     const dir = join(homedir(), ".ish", "debug");
     mkdirSync(dir, { recursive: true });
     const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
-    const shortId = meta.testerId.slice(0, 12);
+    const shortId = meta.participantId.slice(0, 12);
     const fileName = `sim-${shortId}-${ts}.html`;
     const filePath = join(dir, fileName);
     const totalSteps = steps.length;
@@ -119,7 +119,7 @@ export function generateDebugReport(steps, meta) {
 <html lang="en">
 <head>
 <meta charset="utf-8"/>
-<title>Local Sim Debug — ${escapeHtml(meta.testerName)}</title>
+<title>Local Sim Debug — ${escapeHtml(meta.participantName)}</title>
 <style>
   * { box-sizing: border-box; margin: 0; padding: 0; }
   body { background: #1a1a2e; color: #e0e0e0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, monospace; padding: 20px; }
@@ -169,7 +169,7 @@ export function generateDebugReport(steps, meta) {
   <div class="header">
     <h1>Local Sim Debug Report</h1>
     <div class="header-meta">
-      <span><strong>Tester:</strong> ${escapeHtml(meta.testerName)} (${escapeHtml(meta.testerId.slice(0, 12))})</span>
+      <span><strong>Participant:</strong> ${escapeHtml(meta.participantName)} (${escapeHtml(meta.participantId.slice(0, 12))})</span>
       <span><strong>URL:</strong> ${escapeHtml(meta.url)}</span>
       <span><strong>Format:</strong> ${escapeHtml(meta.screenFormat)}</span>
       <span><strong>Status:</strong> <span class="badge" style="background:${meta.finalStatus === "completed" ? "#4caf50" : meta.finalStatus === "failed" ? "#f44336" : "#ff9800"}">${escapeHtml(meta.finalStatus)}</span></span>

package/dist/lib/local-sim/loop.d.ts CHANGED Viewed

@@ -2,7 +2,7 @@
  * Local simulation loop orchestrator.
  *
  * Runs the observe → reason (remote) → act (local) loop for each
- * tester against a local Playwright browser.
+ * participant against a local Playwright browser.
  */
 import type { ApiClient } from "../api-client.js";
 export interface DebugStep {
@@ -39,8 +39,8 @@ export interface LocalSimRunOptions {
     workspaceId: string;
     studyId: string;
     iterationId: string;
-    testerIds: string[];
-    testerNames: Map<string, string>;
+    participantIds: string[];
+    participantNames: Map<string, string>;
     url?: string;
     screenFormat?: "desktop" | "mobile_portrait";
     locale?: string;
@@ -54,7 +54,7 @@ export interface LocalSimRunOptions {
     parallel?: number;
 }
 /**
- * Run local simulations — parallel when multiple testers, sequential by default.
- * Use --parallel <n> to control concurrency (default: number of testers).
+ * Run local simulations — parallel when multiple participants, sequential by default.
+ * Use --parallel <n> to control concurrency (default: number of participants).
  */
 export declare function runLocalSimulations(client: ApiClient, opts: LocalSimRunOptions): Promise<void>;

package/dist/lib/local-sim/loop.js CHANGED Viewed

@@ -2,7 +2,7 @@
  * Local simulation loop orchestrator.
  *
  * Runs the observe → reason (remote) → act (local) loop for each
- * tester against a local Playwright browser.
+ * participant against a local Playwright browser.
  */
 import { launchBrowser, launchSharedBrowser, createTab, captureObservation, takeScreenshot, takeScreenshotJpeg, navigateWithRetry, closeBrowser } from "./browser.js";
 import { uploadScreenshot } from "./upload.js";
@@ -71,8 +71,8 @@ const SENTIMENT_ICONS = {
     Frustrated: "!", Confused: "?", Delighted: "*",
 };
 /**
- * Run local simulations — parallel when multiple testers, sequential by default.
- * Use --parallel <n> to control concurrency (default: number of testers).
+ * Run local simulations — parallel when multiple participants, sequential by default.
+ * Use --parallel <n> to control concurrency (default: number of participants).
  */
 export async function runLocalSimulations(client, opts) {
     const log = (msg) => { if (!opts.quiet || opts.debug)
@@ -89,29 +89,29 @@ export async function runLocalSimulations(client, opts) {
         log("\nCancelling after current step...");
     };
     process.on("SIGINT", onSigint);
-    const concurrency = opts.parallel ?? opts.testerIds.length;
+    const concurrency = opts.parallel ?? opts.participantIds.length;
     try {
-        if (concurrency <= 1 || opts.testerIds.length <= 1) {
-            // Sequential execution — each tester owns its own browser
-            for (const testerId of opts.testerIds) {
+        if (concurrency <= 1 || opts.participantIds.length <= 1) {
+            // Sequential execution — each participant owns its own browser
+            for (const participantId of opts.participantIds) {
                 if (cancelled)
                     break;
-                const testerName = opts.testerNames.get(testerId) ?? testerId;
-                log(`\nStarting local simulation for ${testerName}...`);
+                const participantName = opts.participantNames.get(participantId) ?? participantId;
+                log(`\nStarting local simulation for ${participantName}...`);
                 try {
-                    const testerLog = (msg) => log(`[${testerName}] ${msg}`);
-                    await runSingleSimulation(client, testerId, testerName, opts, testerLog, () => cancelled);
-                    log(`Completed: ${testerName}`);
+                    const participantLog = (msg) => log(`[${participantName}] ${msg}`);
+                    await runSingleSimulation(client, participantId, participantName, opts, participantLog, () => cancelled);
+                    log(`Completed: ${participantName}`);
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
-                    log(`Failed: ${testerName} — ${msg}`);
+                    log(`Failed: ${participantName} — ${msg}`);
                 }
             }
         }
         else {
-            // Parallel execution — shared browser, one tab per tester
-            log(`\nRunning ${opts.testerIds.length} simulations in parallel (concurrency: ${concurrency})...`);
+            // Parallel execution — shared browser, one tab per participant
+            log(`\nRunning ${opts.participantIds.length} simulations in parallel (concurrency: ${concurrency})...`);
             const sharedBrowserOpts = {
                 headed: opts.headed,
                 slowMo: opts.slowMo,
@@ -123,23 +123,23 @@ export async function runLocalSimulations(client, opts) {
             const sharedBrowser = await launchSharedBrowser(sharedBrowserOpts);
             try {
                 const batches = [];
-                for (let i = 0; i < opts.testerIds.length; i += concurrency) {
-                    batches.push(opts.testerIds.slice(i, i + concurrency));
+                for (let i = 0; i < opts.participantIds.length; i += concurrency) {
+                    batches.push(opts.participantIds.slice(i, i + concurrency));
                 }
                 for (const batch of batches) {
                     if (cancelled)
                         break;
-                    const promises = batch.map(async (testerId) => {
-                        const testerName = opts.testerNames.get(testerId) ?? testerId;
-                        const testerLog = (msg) => log(`[${testerName}] ${msg}`);
-                        testerLog("Starting...");
+                    const promises = batch.map(async (participantId) => {
+                        const participantName = opts.participantNames.get(participantId) ?? participantId;
+                        const participantLog = (msg) => log(`[${participantName}] ${msg}`);
+                        participantLog("Starting...");
                         try {
-                            await runSingleSimulation(client, testerId, testerName, opts, testerLog, () => cancelled, sharedBrowser);
-                            testerLog("Completed");
+                            await runSingleSimulation(client, participantId, participantName, opts, participantLog, () => cancelled, sharedBrowser);
+                            participantLog("Completed");
                         }
                         catch (err) {
                             const msg = err instanceof Error ? err.message : String(err);
-                            testerLog(`Failed — ${msg}`);
+                            participantLog(`Failed — ${msg}`);
                         }
                     });
                     await Promise.allSettled(promises);
@@ -154,10 +154,10 @@ export async function runLocalSimulations(client, opts) {
         process.off("SIGINT", onSigint);
     }
 }
-async function runSingleSimulation(client, testerId, testerName, opts, log, isCancelled, sharedBrowser) {
+async function runSingleSimulation(client, participantId, participantName, opts, log, isCancelled, sharedBrowser) {
     // Step 1: Initialize session
     const initResponse = await client.localSimInit({
-        tester_id: testerId,
+        participant_id: participantId,
         study_id: opts.studyId,
         product_id: opts.workspaceId,
         iteration_id: opts.iterationId,
@@ -172,12 +172,12 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
     const locale = opts.locale ?? iterDetails?.locale;
     // Cache session state for per-step requests
     const session = {
-        tester_id: initResponse.tester_id,
+        participant_id: initResponse.participant_id,
         study_id: initResponse.study_id,
         product_id: initResponse.product_id,
         assignments: initResponse.assignments,
-        tester_background: initResponse.tester_background,
-        tester_language: initResponse.tester_language,
+        participant_background: initResponse.participant_background,
+        participant_language: initResponse.participant_language,
         context_values: initResponse.context_values,
         max_interactions: initResponse.max_interactions,
         agent_model: initResponse.agent_model,
@@ -251,7 +251,7 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
                 let stepResponse;
                 try {
                     const stepReqBody = {
-                        tester_id: session.tester_id,
+                        participant_id: session.participant_id,
                         product_id: session.product_id,
                         assignment_name: assignment.name,
                         assignment_instructions: assignment.instructions,
@@ -263,8 +263,8 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
                         interaction_count: step,
                         history,
                         forwards,
-                        tester_background: session.tester_background,
-                        tester_language: session.tester_language,
+                        participant_background: session.participant_background,
+                        participant_language: session.participant_language,
                         context_values: stepContextValues,
                         agent_model: session.agent_model,
                         dom_model: session.dom_model,
@@ -279,7 +279,7 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
                     await page.waitForTimeout(2000);
                     try {
                         const stepReqBody = {
-                            tester_id: session.tester_id,
+                            participant_id: session.participant_id,
                             product_id: session.product_id,
                             assignment_name: assignment.name,
                             assignment_instructions: assignment.instructions,
@@ -291,8 +291,8 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
                             interaction_count: step,
                             history,
                             forwards,
-                            tester_background: session.tester_background,
-                            tester_language: session.tester_language,
+                            participant_background: session.participant_background,
+                            participant_language: session.participant_language,
                             context_values: stepContextValues,
                             agent_model: session.agent_model,
                             dom_model: session.dom_model,
@@ -516,8 +516,8 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
             try {
                 const { generateDebugReport } = await import("./debug-report.js");
                 generateDebugReport(debugSteps, {
-                    testerId: session.tester_id,
-                    testerName,
+                    participantId: session.participant_id,
+                    participantName,
                     url: navigationUrl,
                     screenFormat,
                     finalStatus,
@@ -531,7 +531,7 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
         }
         try {
             await client.localSimRecord({
-                tester_id: session.tester_id,
+                participant_id: session.participant_id,
                 product_id: session.product_id,
                 interactions,
                 final_status: finalStatus,

package/dist/lib/local-sim/types.d.ts CHANGED Viewed

@@ -6,7 +6,7 @@
  * receives actions with node_ids, resolves elements locally via CDP.
  */
 export interface LocalSimInitRequest {
-    tester_id: string;
+    participant_id: string;
     study_id: string;
     product_id: string;
     iteration_id: string;
@@ -18,12 +18,12 @@ export interface IterationDetails {
     locale?: string;
 }
 export interface LocalSimInitResponse {
-    tester_id: string;
+    participant_id: string;
     study_id: string;
     product_id: string;
     assignments: LocalSimAssignment[];
-    tester_background: Record<string, unknown> | null;
-    tester_language: string | null;
+    participant_background: Record<string, unknown> | null;
+    participant_language: string | null;
     config: Record<string, unknown>;
     context_values: ContextValue[];
     max_interactions: number;
@@ -64,7 +64,7 @@ export interface LocalTabInfo {
     opener_id: string | null;
 }
 export interface LocalSimStepRequest {
-    tester_id: string;
+    participant_id: string;
     product_id: string;
     assignment_name: string;
     assignment_instructions: string;
@@ -76,8 +76,8 @@ export interface LocalSimStepRequest {
     interaction_count: number;
     history: HistoryEntry[];
     forwards: ForwardEntry[];
-    tester_background: Record<string, unknown> | null;
-    tester_language: string | null;
+    participant_background: Record<string, unknown> | null;
+    participant_language: string | null;
     context_values: ContextValue[];
     agent_model: string | null;
     dom_model: string | null;
@@ -190,14 +190,14 @@ export interface AssignmentStatusUpdate {
     step_count: number;
 }
 export interface LocalSimRecordRequest {
-    tester_id: string;
+    participant_id: string;
     product_id: string;
     interactions: RecordInteraction[];
     final_status: string;
     assignment_statuses: AssignmentStatusUpdate[];
 }
 export interface LocalSimRecordResponse {
-    tester_id: string;
+    participant_id: string;
     interactions_created: number;
     credits_consumed: number;
 }
@@ -233,12 +233,12 @@ export interface TreeData {
  * Avoids DB lookups on the backend hot path.
  */
 export interface SessionState {
-    tester_id: string;
+    participant_id: string;
     study_id: string;
     product_id: string;
     assignments: LocalSimAssignment[];
-    tester_background: Record<string, unknown> | null;
-    tester_language: string | null;
+    participant_background: Record<string, unknown> | null;
+    participant_language: string | null;
     context_values: ContextValue[];
     max_interactions: number;
     agent_model: string;

package/dist/lib/mcp-clients.d.ts ADDED Viewed

@@ -0,0 +1,51 @@
+/**
+ * MCP client targets — the five clients `ish mcp add` knows how to wire.
+ *
+ * Mirrors the SkillTargetSpec shape in `skill-content.ts` (a per-client
+ * table with config-path resolver + detection predicate). Each entry
+ * captures the surface required to round-trip the client's config file:
+ *
+ *   - `configPath()`   — absolute path to the client's MCP config (per-OS).
+ *   - `detect()`       — does the per-client config directory exist?
+ *                        Accepts false-negatives on never-launched apps;
+ *                        we'd rather skip than write into a bogus dir.
+ *   - `serverKey`      — which top-level object holds servers in this
+ *                        client's config (`mcpServers` for most;
+ *                        `servers` for VS Code).
+ *   - `renderServer()` — the per-client server-block shape (the actual
+ *                        JSON value placed under `<serverKey>.<name>`).
+ *
+ * Server URL is sourced from `ISH_MCP_URL` (env override) or the public
+ * `https://mcp.ishlabs.io/mcp` default. Honors `--dev` indirectly: callers
+ * can flip the env var before invoking; the hosted MCP server handles
+ * OAuth on first connect so we never embed credentials in client files.
+ */
+/** Public default. Override with `ISH_MCP_URL` (used by `--dev` workflows). */
+export declare const ISH_MCP_URL: string;
+/** Server name placed under `<serverKey>` in each client config. */
+export declare const ISH_SERVER_NAME = "ish";
+export type McpClientKey = "cursor" | "vscode" | "claude-code" | "claude-desktop" | "windsurf";
+export type McpServerKey = "mcpServers" | "servers";
+export interface McpClientSpec {
+    key: McpClientKey;
+    displayName: string;
+    /** Top-level object that holds MCP servers in this client's config. */
+    serverKey: McpServerKey;
+    /** Absolute path to this client's MCP config file (per-OS). */
+    configPath: () => string;
+    /** Cheap detection: does the per-client config dir exist on disk? */
+    detect: () => boolean;
+    /** Per-client server-block shape (the value at `<serverKey>.<name>`). */
+    renderServer: (url: string) => Record<string, unknown>;
+    /** True when this client can't be wired on the current OS. */
+    unsupportedOnThisOs?: boolean;
+}
+/**
+ * Per-client targets. Order matters only for human output (listed in this
+ * order in `mcp list` and `mcp add` dry-run plans).
+ */
+export declare const MCP_CLIENT_TARGETS: McpClientSpec[];
+/** Lookup by key (returns undefined for unknown keys). */
+export declare function getClientSpec(key: string): McpClientSpec | undefined;
+/** Convenience: every valid client key, for usage-error messages. */
+export declare function allClientKeys(): McpClientKey[];

package/dist/lib/mcp-clients.js ADDED Viewed

@@ -0,0 +1,175 @@
+/**
+ * MCP client targets — the five clients `ish mcp add` knows how to wire.
+ *
+ * Mirrors the SkillTargetSpec shape in `skill-content.ts` (a per-client
+ * table with config-path resolver + detection predicate). Each entry
+ * captures the surface required to round-trip the client's config file:
+ *
+ *   - `configPath()`   — absolute path to the client's MCP config (per-OS).
+ *   - `detect()`       — does the per-client config directory exist?
+ *                        Accepts false-negatives on never-launched apps;
+ *                        we'd rather skip than write into a bogus dir.
+ *   - `serverKey`      — which top-level object holds servers in this
+ *                        client's config (`mcpServers` for most;
+ *                        `servers` for VS Code).
+ *   - `renderServer()` — the per-client server-block shape (the actual
+ *                        JSON value placed under `<serverKey>.<name>`).
+ *
+ * Server URL is sourced from `ISH_MCP_URL` (env override) or the public
+ * `https://mcp.ishlabs.io/mcp` default. Honors `--dev` indirectly: callers
+ * can flip the env var before invoking; the hosted MCP server handles
+ * OAuth on first connect so we never embed credentials in client files.
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+import * as fs from "node:fs";
+/** Public default. Override with `ISH_MCP_URL` (used by `--dev` workflows). */
+export const ISH_MCP_URL = process.env.ISH_MCP_URL ?? "https://mcp.ishlabs.io/mcp";
+/** Server name placed under `<serverKey>` in each client config. */
+export const ISH_SERVER_NAME = "ish";
+function homedir() {
+    return os.homedir();
+}
+function appData() {
+    return process.env.APPDATA ?? path.join(homedir(), "AppData", "Roaming");
+}
+function dirExists(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+// --- Cursor ---------------------------------------------------------------
+//
+// Cross-platform: `~/.cursor/mcp.json`.
+function cursorConfigPath() {
+    return path.join(homedir(), ".cursor", "mcp.json");
+}
+// --- VS Code --------------------------------------------------------------
+//
+//   macOS:   ~/Library/Application Support/Code/User/mcp.json
+//   Linux:   ~/.config/Code/User/mcp.json
+//   Windows: %APPDATA%\Code\User\mcp.json
+function vscodeConfigDir() {
+    const plat = os.platform();
+    if (plat === "darwin") {
+        return path.join(homedir(), "Library", "Application Support", "Code", "User");
+    }
+    if (plat === "win32") {
+        return path.join(appData(), "Code", "User");
+    }
+    return path.join(homedir(), ".config", "Code", "User");
+}
+function vscodeConfigPath() {
+    return path.join(vscodeConfigDir(), "mcp.json");
+}
+// --- Claude Code (user-scope) --------------------------------------------
+//
+// `~/.claude.json` is Claude Code's user-scope MCP config. (`--scope project`
+// writes `.mcp.json` in the project root — we don't drive that here.)
+function claudeCodeConfigPath() {
+    return path.join(homedir(), ".claude.json");
+}
+// --- Claude Desktop ------------------------------------------------------
+//
+//   macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
+//   Windows: %APPDATA%\Claude\claude_desktop_config.json
+//   Linux:   not supported by Anthropic at the time of writing.
+function claudeDesktopConfigDir() {
+    const plat = os.platform();
+    if (plat === "darwin") {
+        return path.join(homedir(), "Library", "Application Support", "Claude");
+    }
+    if (plat === "win32") {
+        return path.join(appData(), "Claude");
+    }
+    // Linux: no official desktop release. Report a sentinel path; the spec
+    // also flips `unsupportedOnThisOs` so callers can skip without writing
+    // a config under a dir Claude Desktop won't ever read.
+    return path.join(homedir(), ".config", "Claude");
+}
+function claudeDesktopConfigPath() {
+    return path.join(claudeDesktopConfigDir(), "claude_desktop_config.json");
+}
+// --- Windsurf -------------------------------------------------------------
+//
+// `~/.codeium/windsurf/mcp_config.json` — same on every platform.
+function windsurfConfigPath() {
+    return path.join(homedir(), ".codeium", "windsurf", "mcp_config.json");
+}
+/**
+ * Per-client targets. Order matters only for human output (listed in this
+ * order in `mcp list` and `mcp add` dry-run plans).
+ */
+export const MCP_CLIENT_TARGETS = [
+    {
+        key: "cursor",
+        displayName: "Cursor",
+        serverKey: "mcpServers",
+        configPath: cursorConfigPath,
+        detect: () => dirExists(path.join(homedir(), ".cursor")),
+        renderServer: (url) => ({ url }),
+    },
+    {
+        key: "vscode",
+        displayName: "VS Code",
+        serverKey: "servers",
+        configPath: vscodeConfigPath,
+        detect: () => dirExists(vscodeConfigDir()),
+        renderServer: (url) => ({ type: "http", url }),
+    },
+    {
+        key: "claude-code",
+        displayName: "Claude Code",
+        serverKey: "mcpServers",
+        configPath: claudeCodeConfigPath,
+        // Claude Code's user-scope config is a single file at `~/.claude.json`.
+        // Detect by file existence (rather than dir existence) so users who
+        // have only ever installed Claude Code via npm — and never created a
+        // `~/.claude/` dir — still get the entry surfaced.
+        detect: () => {
+            try {
+                return fs.existsSync(claudeCodeConfigPath()) || dirExists(path.join(homedir(), ".claude"));
+            }
+            catch {
+                return false;
+            }
+        },
+        renderServer: (url) => ({ type: "http", url }),
+    },
+    {
+        key: "claude-desktop",
+        displayName: "Claude Desktop",
+        serverKey: "mcpServers",
+        configPath: claudeDesktopConfigPath,
+        detect: () => {
+            // No Linux release yet — surface as undetected on linux to keep the
+            // `--all` sweep honest. Users can still target it explicitly via
+            // `--client claude-desktop` if they have a config dir there.
+            if (os.platform() === "linux")
+                return false;
+            return dirExists(claudeDesktopConfigDir());
+        },
+        renderServer: (url) => ({ type: "http", url }),
+        unsupportedOnThisOs: os.platform() === "linux",
+    },
+    {
+        key: "windsurf",
+        displayName: "Windsurf",
+        serverKey: "mcpServers",
+        configPath: windsurfConfigPath,
+        detect: () => dirExists(path.join(homedir(), ".codeium", "windsurf"))
+            || dirExists(path.join(homedir(), ".codeium")),
+        renderServer: (url) => ({ serverUrl: url }),
+    },
+];
+/** Lookup by key (returns undefined for unknown keys). */
+export function getClientSpec(key) {
+    return MCP_CLIENT_TARGETS.find((c) => c.key === key);
+}
+/** Convenience: every valid client key, for usage-error messages. */
+export function allClientKeys() {
+    return MCP_CLIENT_TARGETS.map((c) => c.key);
+}

package/dist/lib/modality.d.ts CHANGED Viewed

@@ -29,11 +29,11 @@ export declare function describeRequiredContentFlag(modality: string, chatMode?:
  * the read helpers below fall back to that legacy shape and treat it as
  * `external_chatbot`.
  */
-declare const CHAT_MODES: readonly ["external_chatbot", "tester_pair"];
+declare const CHAT_MODES: readonly ["external_chatbot", "participant_pair"];
 export type ChatMode = typeof CHAT_MODES[number];
 /**
- * Normalise user-supplied `--chat-mode` values. Accepts both `tester_pair`
- * (canonical) and `tester-pair` (hyphenated — matches CLI flag convention
+ * Normalise user-supplied `--chat-mode` values. Accepts both `participant_pair`
+ * (canonical) and `participant-pair` (hyphenated — matches CLI flag convention
  * elsewhere in `ish`); same for `external-chatbot`. Returns `null` for
  * anything unrecognised so callers can throw a clean ValidationError.
  */
@@ -50,14 +50,14 @@ export declare function readExternalChatbotEndpoint(details: unknown): {
     chatbot_endpoint_id?: string;
 };
 /**
- * Extract the tester-pair payload from chat details. Returns `undefined` if
- * `mode_details.mode !== "tester_pair"`. Does not validate equal lengths or
+ * Extract the participant-pair payload from chat details. Returns `undefined` if
+ * `mode_details.mode !== "participant_pair"`. Does not validate equal lengths or
  * non-empty scenarios — that's the caller's job (see `iterationHasContent`
  * and `validateIterationDetails`).
  */
-export declare function readTesterPairConfig(details: unknown): {
-    audience_a: string[];
-    audience_b: string[];
+export declare function readParticipantPairConfig(details: unknown): {
+    group_a: string[];
+    group_b: string[];
     scenario_a: string;
     scenario_b: string;
     initiator_side: "a" | "b";
@@ -65,8 +65,8 @@ export declare function readTesterPairConfig(details: unknown): {
     role_criteria_b?: Record<string, unknown>;
 } | undefined;
 /**
- * RoleCriteria — persona-first filter that resolves a tester-profile pool
- * for one side of a tester_pair iteration. Mirrors the backend Pydantic
+ * RoleCriteria — persona-first filter that resolves a person pool
+ * for one side of a participant_pair iteration. Mirrors the backend Pydantic
  * shape in `app/api/models/iterations.py:RoleCriteria` (swift-charm plan).
  * All fields optional; an empty object is treated as "no filter".
  */