@ishlabs/cli 0.12.2 → 0.14.0

package/dist/lib/accessibility-profile.js

@@ -0,0 +1,136 @@
+/**
+ * Client-side validator for the AccessibilityProfile v1.0 JSONB shape on
+ * TesterProfile.accessibility_profile. Mirrors
+ * `ish-mcp/spec/accessibility-profile-schema.v1.json` (additionalProperties:
+ * false at every level except `extensions`). An empty object `{}` is the
+ * canonical default. When non-empty, `version` is required and must be
+ * `"1.0"`.
+ *
+ * Surfacing validation here is cheaper than a server round-trip and gives
+ * agents the same exit-2 error contract they get for other CLI inputs.
+ */
+const SPEC_URL = "https://ishlabs.io/spec/accessibility-profile-schema.v1.json";
+const TEXT_SIZE = new Set(["default", "large", "xl", "xxl"]);
+const CONTRAST_PREFERENCE = new Set(["default", "more", "less"]);
+const COLOR_SCHEME = new Set(["no_preference", "light", "dark"]);
+const COLOR_FILTER = new Set([
+    "none",
+    "deuteranopia",
+    "protanopia",
+    "tritanopia",
+    "grayscale",
+]);
+const VISUAL_BOOLEANS = new Set([
+    "reduce_transparency",
+    "forced_colors",
+    "inverted_colors",
+    "uses_screen_reader",
+    "uses_magnifier",
+    "dyslexia_friendly_font",
+]);
+const VISUAL_STRINGS = {
+    text_size: TEXT_SIZE,
+    contrast_preference: CONTRAST_PREFERENCE,
+    color_scheme: COLOR_SCHEME,
+    color_filter: COLOR_FILTER,
+};
+const AUDITORY_BOOLEANS = new Set([
+    "captions_required",
+    "audio_descriptions_required",
+    "mono_audio",
+    "visual_alerts_required",
+    "uses_hearing_aid",
+]);
+const MOTOR_BOOLEANS = new Set([
+    "uses_switch_control",
+    "uses_voice_control",
+    "uses_eye_tracking",
+    "needs_larger_tap_targets",
+    "extended_interaction_timeouts",
+    "avoid_hover_interactions",
+    "sticky_keys",
+]);
+const COGNITIVE_BOOLEANS = new Set([
+    "reduce_motion",
+    "simple_language_preferred",
+    "extra_reading_time",
+    "avoid_flashing",
+    "predictable_navigation",
+]);
+const DATA_BOOLEANS = new Set(["reduce_data"]);
+const TOP_LEVEL_KEYS = new Set([
+    "version",
+    "visual",
+    "auditory",
+    "motor",
+    "cognitive",
+    "data",
+    "assistive_tech",
+    "notes",
+    "extensions",
+]);
+function err(path, msg) {
+    return new Error(`Invalid --accessibility-profile at ${path}: ${msg}. See ${SPEC_URL}.`);
+}
+function checkGroup(group, path, bools, strs = {}) {
+    if (group === undefined || group === null)
+        return;
+    if (typeof group !== "object" || Array.isArray(group)) {
+        throw err(path, "must be an object");
+    }
+    for (const [key, value] of Object.entries(group)) {
+        if (bools.has(key)) {
+            if (typeof value !== "boolean")
+                throw err(`${path}.${key}`, "must be a boolean");
+            continue;
+        }
+        if (key in strs) {
+            const allowed = strs[key];
+            if (typeof value !== "string" || !allowed.has(value)) {
+                throw err(`${path}.${key}`, `must be one of ${[...allowed].join(", ")}`);
+            }
+            continue;
+        }
+        throw err(`${path}.${key}`, "unknown property");
+    }
+}
+export function validateAccessibilityProfile(raw) {
+    if (raw === undefined || raw === null) {
+        throw err("$", "must be a JSON object");
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        throw err("$", "must be a JSON object");
+    }
+    const obj = raw;
+    const keys = Object.keys(obj);
+    if (keys.length === 0)
+        return {};
+    for (const key of keys) {
+        if (!TOP_LEVEL_KEYS.has(key)) {
+            throw err(`$.${key}`, "unknown property");
+        }
+    }
+    if (obj.version !== "1.0") {
+        throw err("$.version", 'is required and must be "1.0" when the object is non-empty');
+    }
+    checkGroup(obj.visual, "$.visual", VISUAL_BOOLEANS, VISUAL_STRINGS);
+    checkGroup(obj.auditory, "$.auditory", AUDITORY_BOOLEANS);
+    checkGroup(obj.motor, "$.motor", MOTOR_BOOLEANS);
+    checkGroup(obj.cognitive, "$.cognitive", COGNITIVE_BOOLEANS);
+    checkGroup(obj.data, "$.data", DATA_BOOLEANS);
+    if (obj.assistive_tech !== undefined) {
+        if (!Array.isArray(obj.assistive_tech)
+            || !obj.assistive_tech.every((v) => typeof v === "string")) {
+            throw err("$.assistive_tech", "must be an array of strings");
+        }
+    }
+    if (obj.notes !== undefined && typeof obj.notes !== "string") {
+        throw err("$.notes", "must be a string");
+    }
+    if (obj.extensions !== undefined) {
+        if (typeof obj.extensions !== "object" || obj.extensions === null || Array.isArray(obj.extensions)) {
+            throw err("$.extensions", "must be an object");
+        }
+    }
+    return obj;
+}

package/dist/lib/alias-store.d.ts

@@ -18,6 +18,7 @@ export declare const ALIAS_PREFIX: {
     readonly ask: "a";
     readonly askRound: "r";
     readonly chatEndpoint: "ep";
+    readonly chatConfig: "cc";
 };
 /**
  * Save aliases for a list of IDs under the given prefix.

package/dist/lib/alias-store.js

@@ -21,6 +21,7 @@ export const ALIAS_PREFIX = {
     ask: "a",
     askRound: "r",
     chatEndpoint: "ep",
+    chatConfig: "cc",
 };
 /** Format a number with zero-padding (minimum 2 digits). */
 function padNum(n) {

package/dist/lib/ask-questions.js

@@ -7,6 +7,7 @@
  */
 import { readFileSync } from "node:fs";
 import { resolve as resolvePath } from "node:path";
+import { normalizeEnumValue, QUESTION_TYPES } from "./enums.js";
 export function loadQuestionsManifest(filePath) {
     let raw;
     try {
@@ -30,6 +31,14 @@ export function loadQuestionsManifest(filePath) {
         if (!q || typeof q !== "object" || typeof q.question !== "string" || !q.question.trim()) {
             throw new Error(`questions[${i}].question must be a non-empty string.`);
         }
+        // Fold underscored variants (`single_choice`) back to the canonical
+        // hyphenated form (`single-choice`). Unknown types pass through untouched
+        // so the backend remains the source of truth for shape validation.
+        if (typeof q.type === "string") {
+            const canonical = normalizeEnumValue(q.type, QUESTION_TYPES);
+            if (canonical !== null)
+                q.type = canonical;
+        }
     }
     return parsed;
 }

package/dist/lib/billing.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Credit cost estimators — mirror the backend's billing formulas so the CLI
+ * can surface a pre-dispatch estimate without a network round-trip.
+ *
+ * The numbers here MUST match `ish-backend/app/{media,chat}/billing.py`
+ * and `app/billing/service.py`. If the backend formula changes, update
+ * this file in the same commit, otherwise the CLI will mislead agents.
+ *
+ * Today every modality uses the same shape: `max(1, round(steps / 10))`
+ * per principal (per tester for media/interactive, per conversation for
+ * chat, ×2 for tester-pair). Asks bill flat 1 credit per successful
+ * tester response. These are intentionally per-run estimates; long-term
+ * we'll fetch `GET /billing/rates` and parameterise modalities — see
+ * `reference/credits` docs page.
+ */
+export interface CreditEstimate {
+    /** Upper bound (no early termination). Never claims exactness. */
+    upper_bound: number;
+    /** Stable identifier so agents can branch on shape if the formula evolves. */
+    formula: "media_per_tester" | "chat_solo" | "chat_pair" | "ask_per_response";
+    /** Human-readable breakdown so agents can explain the number to users. */
+    breakdown: string;
+    /** Always "credits" today; reserved for future-proofing (e.g. millicredits). */
+    unit: "credits";
+}
+/** Mirror of `app/media/billing.py::media_credit_cost`. */
+export declare function mediaCreditCost(steps: number): number;
+/** Mirror of `app/chat/billing.py::chat_credit_cost`. */
+export declare function chatCreditCost(turns: number): number;
+/**
+ * Media/interactive run: 1 credit-cost-per-tester × tester count. Modality
+ * doesn't currently affect the rate (interactive == text == video at the
+ * billing layer) — kept as a parameter for forward compatibility.
+ */
+export declare function estimateMediaRun(args: {
+    testerCount: number;
+    maxInteractions: number;
+}): CreditEstimate;
+/** Solo chat (single tester, external chatbot). */
+export declare function estimateChatSolo(args: {
+    testerCount: number;
+    maxTurns: number;
+}): CreditEstimate;
+/** Tester-pair chat: each turn bills both sides, so cost doubles. */
+export declare function estimateChatPair(args: {
+    conversationCount: number;
+    maxTurns: number;
+}): CreditEstimate;
+/**
+ * Ask round: flat 1 credit per successful tester response (charged only
+ * for completed responses; the upper bound assumes everyone completes).
+ */
+export declare function estimateAskRound(args: {
+    testerCount: number;
+}): CreditEstimate;

package/dist/lib/billing.js

@@ -0,0 +1,77 @@
+/**
+ * Credit cost estimators — mirror the backend's billing formulas so the CLI
+ * can surface a pre-dispatch estimate without a network round-trip.
+ *
+ * The numbers here MUST match `ish-backend/app/{media,chat}/billing.py`
+ * and `app/billing/service.py`. If the backend formula changes, update
+ * this file in the same commit, otherwise the CLI will mislead agents.
+ *
+ * Today every modality uses the same shape: `max(1, round(steps / 10))`
+ * per principal (per tester for media/interactive, per conversation for
+ * chat, ×2 for tester-pair). Asks bill flat 1 credit per successful
+ * tester response. These are intentionally per-run estimates; long-term
+ * we'll fetch `GET /billing/rates` and parameterise modalities — see
+ * `reference/credits` docs page.
+ */
+/** Mirror of `app/media/billing.py::media_credit_cost`. */
+export function mediaCreditCost(steps) {
+    if (!Number.isFinite(steps) || steps <= 0)
+        return 1;
+    return Math.max(1, Math.round(steps / 10));
+}
+/** Mirror of `app/chat/billing.py::chat_credit_cost`. */
+export function chatCreditCost(turns) {
+    if (!Number.isFinite(turns) || turns <= 0)
+        return 1;
+    return Math.max(1, Math.round(turns / 10));
+}
+/**
+ * Media/interactive run: 1 credit-cost-per-tester × tester count. Modality
+ * doesn't currently affect the rate (interactive == text == video at the
+ * billing layer) — kept as a parameter for forward compatibility.
+ */
+export function estimateMediaRun(args) {
+    const perTester = mediaCreditCost(args.maxInteractions);
+    const total = Math.max(0, args.testerCount) * perTester;
+    return {
+        upper_bound: total,
+        formula: "media_per_tester",
+        breakdown: `${args.testerCount} tester(s) × max(1, round(${args.maxInteractions} steps / 10)) = ${args.testerCount} × ${perTester} = ${total}`,
+        unit: "credits",
+    };
+}
+/** Solo chat (single tester, external chatbot). */
+export function estimateChatSolo(args) {
+    const perTester = chatCreditCost(args.maxTurns);
+    const total = Math.max(0, args.testerCount) * perTester;
+    return {
+        upper_bound: total,
+        formula: "chat_solo",
+        breakdown: `${args.testerCount} tester(s) × max(1, round(${args.maxTurns} turns / 10)) = ${args.testerCount} × ${perTester} = ${total}`,
+        unit: "credits",
+    };
+}
+/** Tester-pair chat: each turn bills both sides, so cost doubles. */
+export function estimateChatPair(args) {
+    const perSide = chatCreditCost(args.maxTurns);
+    const total = Math.max(0, args.conversationCount) * perSide * 2;
+    return {
+        upper_bound: total,
+        formula: "chat_pair",
+        breakdown: `${args.conversationCount} conv × max(1, round(${args.maxTurns} turns / 10)) × 2 sides = ${args.conversationCount} × ${perSide} × 2 = ${total}`,
+        unit: "credits",
+    };
+}
+/**
+ * Ask round: flat 1 credit per successful tester response (charged only
+ * for completed responses; the upper bound assumes everyone completes).
+ */
+export function estimateAskRound(args) {
+    const total = Math.max(0, args.testerCount);
+    return {
+        upper_bound: total,
+        formula: "ask_per_response",
+        breakdown: `${args.testerCount} tester(s) × 1 credit/response = ${total} (upper bound; only successful responses bill)`,
+        unit: "credits",
+    };
+}

package/dist/lib/command-helpers.d.ts

@@ -129,6 +129,12 @@ export declare function resolveAsk(explicit?: string): string;
  * endpoint persisted by `ish chat endpoint use`. Throws when none are set.
  */
 export declare function resolveChatEndpoint(positional?: string, flag?: string): string;
+/**
+ * Resolve a chat configuration id from a positional arg or `--config` flag.
+ * Configurations don't have an "active" notion (unlike endpoints), so this
+ * helper only resolves explicit input — there is no fallback.
+ */
+export declare function resolveChatConfig(positional?: string, flag?: string): string;
 /** Commander option-collector for repeatable flags (e.g. `--variant text:"..."` repeated). */
 export declare function collectRepeatable(value: string, prev?: string[]): string[];
 /**

package/dist/lib/command-helpers.js

@@ -598,6 +598,18 @@ export function resolveChatEndpoint(positional, flag) {
         return config.chat_endpoint;
     throw new Error('No chat endpoint set. Use `ish chat endpoint use <id>`, pass the endpoint id, or set --endpoint.');
 }
+/**
+ * Resolve a chat configuration id from a positional arg or `--config` flag.
+ * Configurations don't have an "active" notion (unlike endpoints), so this
+ * helper only resolves explicit input — there is no fallback.
+ */
+export function resolveChatConfig(positional, flag) {
+    if (positional)
+        return resolveId(positional);
+    if (flag)
+        return resolveId(flag);
+    throw new Error("Pass a chat configuration alias / UUID (positional argument or --config <id>).");
+}
 /** Commander option-collector for repeatable flags (e.g. `--variant text:"..."` repeated). */
 export function collectRepeatable(value, prev = []) {
     return prev.concat([value]);