@ishlabs/cli 0.17.7 → 0.19.0

package/dist/commands/source.d.ts

@@ -1,10 +1,14 @@
 /**
- * ish source — Upload and inspect audience-generation sources.
+ * ish source — Upload and inspect participant attachments used as generation inputs.
  *
- * Sources (transcripts, audio, images, PDFs) are inputs to `ish profile
+ * Attachments (transcripts, audio, images, PDFs) are inputs to `ish person
  * generate`. For one-shot generation, `profile generate --source <path>`
  * auto-uploads. Use these commands to upload once and reuse across multiple
  * generation runs, or to inspect processing status.
+ *
+ * The public CLI command name `source` is preserved for compatibility with
+ * existing scripts and agents; internally we call the unified
+ * /people/attachments/* endpoint family (see ADR-0034).
  */
 import type { Command } from "commander";
 export declare function registerSourceCommands(program: Command): void;

package/dist/commands/source.js

@@ -1,42 +1,47 @@
 /**
- * ish source — Upload and inspect audience-generation sources.
+ * ish source — Upload and inspect participant attachments used as generation inputs.
  *
- * Sources (transcripts, audio, images, PDFs) are inputs to `ish profile
+ * Attachments (transcripts, audio, images, PDFs) are inputs to `ish person
  * generate`. For one-shot generation, `profile generate --source <path>`
  * auto-uploads. Use these commands to upload once and reuse across multiple
  * generation runs, or to inspect processing status.
+ *
+ * The public CLI command name `source` is preserved for compatibility with
+ * existing scripts and agents; internally we call the unified
+ * /people/attachments/* endpoint family (see ADR-0034).
  */
 import { withClient, resolveWorkspace } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { normalizeEnumValue } from "../lib/enums.js";
-import { formatAudienceSource, output } from "../lib/output.js";
-import { inferSourceKind, uploadAndProcessSource, } from "../lib/profile-sources.js";
+import { formatAttachment, output } from "../lib/output.js";
+import { inferAttachmentKind, uploadAndProcessAttachment, } from "../lib/profile-sources.js";
 const VALID_KINDS = ["text_file", "audio", "image"];
 export function registerSourceCommands(program) {
     const source = program
         .command("source")
-        .description("Upload and inspect audience-generation sources (transcripts, audio, images)")
+        .description("Upload and inspect participant attachments used as generation inputs (transcripts, audio, images)")
         .addHelpText("after", `
-A source is an input to \`ish profile generate\` — transcript, audio, image, or PDF. Use
-\`source upload\` when you want to reuse the same source across multiple generation runs;
-otherwise pass a local path directly to \`profile generate --source\` and it auto-uploads.
+A source — internally a participant attachment — is an input to \`ish person generate\`:
+transcript, audio, image, or PDF. Use \`source upload\` when you want to reuse the
+same attachment across multiple generation runs; otherwise pass a local path directly
+to \`profile generate --source\` and it auto-uploads.
 
 Concept pages: ish docs get-page concepts/source
                 ish docs get-page concepts/profile`);
     source
         .command("upload")
-        .description("Upload a file as an audience source and wait for processing")
+        .description("Upload a file as a participant attachment and wait for processing")
         .argument("<file>", "Local file path (transcript, audio, image, PDF, etc.)")
         .option("--workspace <id>", "Workspace (product) ID; falls back to active workspace")
-        .option("--kind <kind>", "Source kind: text_file | audio | image (auto-detected if omitted; hyphen/underscore variants accepted)")
-        .option("--description <text>", "Context note attached to the source (max 500 chars)")
-        .option("--diarize", "Apply speaker diarization to audio sources (silently ignored for text/image)")
+        .option("--kind <kind>", "Attachment kind: text_file | audio | image (auto-detected if omitted; hyphen/underscore variants accepted)")
+        .option("--description <text>", "Context note attached to the file (max 500 chars)")
+        .option("--diarize", "Accepted for backward compat; audio diarization is the worker default and the flag is ignored.")
         .option("--no-wait", "Don't poll until terminal status — return after confirm")
         .option("--timeout <seconds>", "Poll timeout in seconds (default 300)", "300")
         .addHelpText("after", `
 Examples:
   $ ish source upload ./transcript.txt
-  $ ish source upload ./call.mp3 --diarize --description "Q3 churn interview"
+  $ ish source upload ./call.mp3 --description "Q3 churn interview"
   $ ish source upload ./screenshot.png --kind image --no-wait`)
         .action(async (file, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
@@ -50,10 +55,10 @@ Examples:
                 kind = normalized;
             }
             else {
-                kind = inferSourceKind(file);
+                kind = inferAttachmentKind(file);
             }
             const timeoutMs = Math.max(1, parseInt(opts.timeout, 10)) * 1000;
-            const src = await uploadAndProcessSource(client, {
+            const attachment = await uploadAndProcessAttachment(client, {
                 productId,
                 filePath: file,
                 kind,
@@ -63,39 +68,39 @@ Examples:
                 timeoutMs,
                 quiet: globals.quiet,
             });
-            formatAudienceSource(src, globals.json);
+            formatAttachment(attachment, globals.json);
         });
     });
     source
         .command("get")
-        .description("Get an audience source's current status")
-        .argument("<id>", "Source ID or alias")
-        .addHelpText("after", "\nExamples:\n  $ ish source get tps-3a4")
+        .description("Get a participant attachment's current status")
+        .argument("<id>", "Attachment ID or alias")
+        .addHelpText("after", "\nExamples:\n  $ ish source get ps-3a4")
         .action(async (id, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            const src = await client.get(`/tester-profiles/sources/${resolveId(id)}`);
-            formatAudienceSource(src, globals.json);
+            const attachment = await client.get(`/people/attachments/${resolveId(id)}`);
+            formatAttachment(attachment, globals.json);
         });
     });
     source
         .command("delete")
-        .description("Delete an audience source plus its uploaded file")
-        .argument("<id>", "Source ID or alias")
+        .description("Delete a participant attachment plus its uploaded file")
+        .argument("<id>", "Attachment ID or alias")
         .addHelpText("after", `
-Removes both the database row and the underlying uploaded file. Profiles
-already generated from this source remain in place — they don't reference
-the source after generation.
+The backend ref-counts attachment deletes: the file row + storage object are
+removed only when no profile mappings remain. Profiles already generated from
+this attachment keep their seed mapping until they themselves are deleted.
 
 Examples:
-  $ ish source delete tps-3a4`)
+  $ ish source delete ps-3a4`)
         .action(async (id, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const rid = resolveId(id);
-            await client.del(`/tester-profiles/sources/${rid}`);
+            await client.del(`/people/attachments/${rid}`);
             output({
                 id: rid,
-                alias: tagAlias(ALIAS_PREFIX.testerProfileSource, rid),
-                message: "Source deleted",
+                alias: tagAlias(ALIAS_PREFIX.personSource, rid),
+                message: "Attachment deleted",
             }, globals.json, { writePath: true });
         });
     });

package/dist/commands/study-analyze.d.ts

@@ -19,7 +19,7 @@ export interface KeyInsight {
     title: string;
     description: string;
     category: "friction" | "confusion" | "blocker" | "observation" | "positive";
-    tester_count: number;
+    participant_count: number;
     iteration_labels: string[];
     is_discarded: boolean;
     interaction_ids: string[];

package/dist/commands/study-analyze.js

@@ -51,12 +51,12 @@ async function pollAnalysisUntilDone(client, opts) {
     }
 }
 function formatKeyInsightsTable(insights) {
-    printTable(["#", "CATEGORY", "TESTERS", "TITLE"], insights
+    printTable(["#", "CATEGORY", "PARTICIPANTS", "TITLE"], insights
         .filter((i) => !i.is_discarded)
         .map((i) => [
         String(i.sequence),
         i.category,
-        String(i.tester_count),
+        String(i.participant_count),
         i.title,
     ]));
 }
@@ -95,7 +95,7 @@ Examples:
 
 Prerequisites (enforced server-side):
   - Study modality is one of: interactive, video, audio, text, image, document
-  - At least 5 testers with completed interactions
+  - At least 5 participants with completed interactions
 
 Read prior runs:
   $ ish study insights <study-id>`)

package/dist/commands/study-participant.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ish study participant — Inspect and manage participants (low-level; usually
+ * created via `ish study run`).
+ *
+ * Default action: `ish study participant <id>` shows participant details and results.
+ */
+import type { Command } from "commander";
+export declare function attachStudyParticipantCommands(study: Command): void;

package/dist/commands/{study-tester.js → study-participant.js}

@@ -1,12 +1,12 @@
 /**
- * ish study tester — Inspect and manage testers (low-level; usually
+ * ish study participant — Inspect and manage participants (low-level; usually
  * created via `ish study run`).
  *
- * Default action: `ish study tester <id>` shows tester details and results.
+ * Default action: `ish study participant <id>` shows participant details and results.
  */
 import { withClient, readJsonFileOrStdin, resolveWorkspace } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
-import { formatTesterDetail, buildTesterSummary, output } from "../lib/output.js";
+import { formatParticipantDetail, buildParticipantSummary, output } from "../lib/output.js";
 /** Pick the latest iteration on a study (highest order_index, falling back to last). */
 async function latestIterationForStudy(client, studyId) {
     const study = await client.get(`/studies/${studyId}`);
@@ -18,12 +18,12 @@ async function latestIterationForStudy(client, studyId) {
     return sorted[0].id;
 }
 /**
- * Walk a parsed JSON body and resolve any alias-shaped strings (tp-..., i-..., s-...)
+ * Walk a parsed JSON body and resolve any alias-shaped strings (p-..., i-..., s-...)
  * appearing in well-known id fields. Pure client-side: avoids a backend round-trip
  * when the body uses local aliases that the backend wouldn't recognise.
  */
-const ALIAS_FIELDS = new Set(["tester_profile_id", "iteration_id", "study_id"]);
-const ALIAS_RE = /^(tp|i|s)-[0-9a-f]{3,}$/i;
+const ALIAS_FIELDS = new Set(["person_id", "iteration_id", "study_id"]);
+const ALIAS_RE = /^(p|i|s)-[0-9a-f]{3,}$/i;
 function prewalkAliases(value) {
     if (Array.isArray(value)) {
         return value.map(prewalkAliases);
@@ -47,20 +47,20 @@ function prewalkAliases(value) {
     }
     return value;
 }
-export function attachStudyTesterCommands(study) {
-    const tester = study
-        .command("tester")
-        .description("Inspect or manage testers (low-level; usually created via `study run`)")
-        .argument("[id]", "Tester ID — pass directly to view tester details and results")
-        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the tester)")
+export function attachStudyParticipantCommands(study) {
+    const participant = study
+        .command("participant")
+        .description("Inspect or manage participants (low-level; usually created via `study run`)")
+        .argument("[id]", "Participant ID — pass directly to view participant details and results")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the participant)")
         .option("--summary", "Lean projection: alias + status + sentiment + comment + error_message. Drops the action timeline / interactions array.")
         .addHelpText("after", `
 Examples:
-  $ ish study tester t-d4e                       # show tester details
-  $ ish study tester t-d4e --summary --json      # headline only (sentiment + comment)
-  $ ish study tester create --iteration <id> --profile <id>
-  $ ish study tester batch-create --iteration <id> --file testers.json
-  $ ish study tester delete t-d4e
+  $ ish study participant pt-d4e                       # show participant details
+  $ ish study participant pt-d4e --summary --json      # headline only (sentiment + comment)
+  $ ish study participant create --iteration <id> --person <id>
+  $ ish study participant batch-create --iteration <id> --file participants.json
+  $ ish study participant delete pt-d4e
 
 Tips:
   Use \`--get <path>\` to grab one value (e.g. \`--get sentiment\`),
@@ -72,27 +72,27 @@ Tips:
         await withClient(cmd, async (client, globals) => {
             if (opts.workspace)
                 resolveWorkspace(opts.workspace);
-            const data = await client.get(`/testers/${resolveId(id)}`);
+            const data = await client.get(`/participants/${resolveId(id)}`);
             const result = data;
             if (result.id)
-                result.alias = tagAlias(ALIAS_PREFIX.tester, String(result.id));
+                result.alias = tagAlias(ALIAS_PREFIX.participant, String(result.id));
             if (opts.summary) {
-                output(buildTesterSummary(result), globals.json, { preProjected: true });
+                output(buildParticipantSummary(result), globals.json, { preProjected: true });
                 return;
             }
-            formatTesterDetail(result, globals.json);
+            formatParticipantDetail(result, globals.json);
         });
     });
-    tester
+    participant
         .command("create")
-        .description("Create a tester (low-level)")
+        .description("Create a participant (low-level)")
         .option("--iteration <id>", "Iteration ID (or use --study to pick the latest iteration on a study)")
         .option("--study <id>", "Study ID; resolves to the latest iteration on that study (alternative to --iteration)")
-        .requiredOption("--profile <id>", "Tester profile ID")
+        .requiredOption("--person <id>", "Participant profile ID")
         .option("--language <lang>", "Language code (e.g. en, sv)")
         .option("--platform <platform>", "Platform (browser, android, figma, code)")
-        .option("--tester-type <type>", "Tester type (ai, human)", "ai")
-        .addHelpText("after", "\nExamples:\n  $ ish study tester create --iteration <id> --profile <id>\n  $ ish study tester create --study s-XXX --profile tp-XXX\n  $ ish study tester create --iteration <id> --profile <id> --platform android --json")
+        .option("--participant-type <type>", "Participant type (ai, human)", "ai")
+        .addHelpText("after", "\nExamples:\n  $ ish study participant create --iteration <id> --person <id>\n  $ ish study participant create --study s-XXX --person p-XXX\n  $ ish study participant create --iteration <id> --person <id> --platform android --json")
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             if (!opts.iteration && !opts.study) {
@@ -105,63 +105,63 @@ Tips:
                 ? resolveId(opts.iteration)
                 : await latestIterationForStudy(client, resolveId(opts.study));
             const body = {
-                tester_profile_id: resolveId(opts.profile),
-                tester_type: opts.testerType,
+                person_id: resolveId(opts.person),
+                participant_type: opts.participantType,
                 ...(opts.language && { language: opts.language }),
                 ...(opts.platform && { platform: opts.platform }),
             };
-            const data = await client.post(`/iterations/${iterationId}/testers`, body);
+            const data = await client.post(`/iterations/${iterationId}/participants`, body);
             const result = data;
             if (result.id)
-                result.alias = tagAlias(ALIAS_PREFIX.tester, String(result.id));
+                result.alias = tagAlias(ALIAS_PREFIX.participant, String(result.id));
             output(result, globals.json);
         });
     });
-    tester
+    participant
         .command("batch-create")
-        .description("Create multiple testers (low-level)")
+        .description("Create multiple participants (low-level)")
         .requiredOption("--iteration <id>", "Iteration ID")
-        .option("--file <path>", "JSON file with testers array (alternative to --profiles)")
-        .option("--profiles <ids>", "Comma-separated profile IDs/aliases; shortcut for --file with one tester per profile (mutually exclusive with --file)")
-        .addHelpText("after", "\nExamples:\n  $ ish study tester batch-create --iteration <id> --file testers.json\n  $ ish study tester batch-create --iteration <id> --profiles tp-eba,tp-289,tp-913\n\n  Expected JSON: [{ \"tester_profile_id\": \"<id>\", \"platform\": \"browser\" }, ...]\n  Profile-id strings inside --file (tester_profile_id, iteration_id, study_id) are resolved client-side via the local alias store before submitting.")
+        .option("--file <path>", "JSON file with participants array (alternative to --persons)")
+        .option("--persons <ids>", "Comma-separated profile IDs/aliases; shortcut for --file with one participant per profile (mutually exclusive with --file)")
+        .addHelpText("after", "\nExamples:\n  $ ish study participant batch-create --iteration <id> --file participants.json\n  $ ish study participant batch-create --iteration <id> --persons p-eba,p-289,p-913\n\n  Expected JSON: [{ \"person_id\": \"<id>\", \"platform\": \"browser\" }, ...]\n  Profile-id strings inside --file (person_id, iteration_id, study_id) are resolved client-side via the local alias store before submitting.")
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            if (!opts.file && !opts.profiles) {
-                throw new Error("Provide --file <path> or --profiles <ids>.");
+            if (!opts.file && !opts.persons) {
+                throw new Error("Provide --file <path> or --persons <ids>.");
             }
-            if (opts.file && opts.profiles) {
-                throw new Error("Pass either --file or --profiles, not both.");
+            if (opts.file && opts.persons) {
+                throw new Error("Pass either --file or --persons, not both.");
             }
             const iterationId = resolveId(opts.iteration);
             let body;
-            if (opts.profiles) {
-                const ids = opts.profiles
+            if (opts.persons) {
+                const ids = opts.persons
                     .split(",")
                     .map((s) => s.trim())
                     .filter(Boolean)
                     .map((s) => resolveId(s));
                 if (ids.length === 0) {
-                    throw new Error("--profiles must contain at least one profile id/alias.");
+                    throw new Error("--persons must contain at least one profile id/alias.");
                 }
-                body = { testers: ids.map((pid) => ({ tester_profile_id: pid, tester_type: "ai" })) };
+                body = { participants: ids.map((pid) => ({ person_id: pid, participant_type: "ai" })) };
             }
             else {
                 const parsed = await readJsonFileOrStdin(opts.file);
                 body = prewalkAliases(parsed);
             }
-            const data = await client.post(`/iterations/${iterationId}/testers/batch`, body);
+            const data = await client.post(`/iterations/${iterationId}/participants/batch`, body);
             output(data, globals.json);
         });
     });
-    tester
+    participant
         .command("delete")
-        .description("Delete a tester")
-        .argument("<id>", "Tester ID")
-        .addHelpText("after", "\nExamples:\n  $ ish study tester delete <id>")
+        .description("Delete a participant")
+        .argument("<id>", "Participant ID")
+        .addHelpText("after", "\nExamples:\n  $ ish study participant delete <id>")
         .action(async (id, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            await client.del(`/testers/${resolveId(id)}`);
-            output({ message: "Tester deleted" }, globals.json);
+            await client.del(`/participants/${resolveId(id)}`);
+            output({ message: "Participant deleted" }, globals.json);
         });
     });
 }

package/dist/commands/study-run.d.ts

@@ -1,7 +1,7 @@
 /**
  * ish study run — Run, monitor, and cancel simulations of a study.
  *
- * `ish study run` creates testers for the latest (or specified) iteration
+ * `ish study run` creates participants for the latest (or specified) iteration
  * and dispatches simulations. Iterations are created separately via
  * `ish iteration create`, which carries the URL/content details.
  *
@@ -13,7 +13,7 @@ import type { Command } from "commander";
  * produce a structured envelope (`error_code: "wait_timeout"`, exit 5
  * transient) distinct from the generic timeout/network/server errors
  * that the api-client wrapper produces. Carries the in-flight progress
- * (testers done / total) so `study wait` always emits final state JSON
+ * (participants done / total) so `study wait` always emits final state JSON
  * even when it bails on the timer.
  */
 export declare class WaitTimeoutError extends Error {
@@ -24,7 +24,7 @@ export declare class WaitTimeoutError extends Error {
         done: number;
         total: number;
         pending: number;
-        rows: TesterStatusRow[];
+        rows: ParticipantStatusRow[];
     };
     readonly error_code = "wait_timeout";
     readonly retryable = true;
@@ -35,13 +35,13 @@ export declare class WaitTimeoutError extends Error {
         done: number;
         total: number;
         pending: number;
-        rows: TesterStatusRow[];
+        rows: ParticipantStatusRow[];
     });
 }
-interface TesterStatusRow {
+interface ParticipantStatusRow {
     id: string;
     status: string;
-    tester_name: string;
+    participant_name: string;
     interaction_count: number;
     error_message?: string;
 }