@ishlabs/cli 0.8.1

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2025 Ish Labs. All rights reserved.
+
+This software is the proprietary property of Ish Labs and is provided under the
+terms of the Ish Labs Terms of Service (https://ishlabs.io/terms). Unauthorized
+copying, modification, distribution, or use of this software, in whole or in
+part, is strictly prohibited without prior written consent from Ish Labs.

package/README.md

@@ -0,0 +1,69 @@
+# ish
+
+CLI tool to expose your localhost to [Ish](https://ishlabs.io) for simulation testing.
+
+## Install
+
+### Quick install (recommended)
+
+**macOS / Linux:**
+```bash
+curl -fsSL https://ishlabs.io/install.sh | sh
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://ishlabs.io/install.ps1 | iex
+```
+
+### npm (all platforms)
+
+```bash
+npm install -g @ishlabs/cli
+```
+
+### Homebrew (macOS / Linux)
+
+```bash
+brew tap ishlabs/tap
+brew install ish
+```
+
+## Usage
+
+```bash
+ish connect <port>
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-t, --token <token>` | Auth token (or set `ISH_TOKEN` env var, or enter interactively) |
+| `--api-url <url>` | Backend API URL (default: `https://api.ishlabs.io` or `ISH_API_URL` env var) |
+| `--version` | Show version |
+
+### Token Configuration
+
+The CLI resolves your auth token in this order:
+
+1. `--token` CLI argument
+2. `ISH_TOKEN` environment variable
+3. Saved token from `ish login` (stored in `~/.ish/config.json`)
+
+## Examples
+
+```bash
+# Expose port 3000
+ish connect 3000
+
+# With explicit token
+ish connect 3000 --token YOUR_TOKEN
+
+# Using environment variable
+ISH_TOKEN=YOUR_TOKEN ish connect 8080
+```
+
+## License
+
+Copyright (c) 2025 Ish Labs. All rights reserved. See [LICENSE](LICENSE).

package/dist/auth.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Browser-based authentication via the Ish frontend plugin auth flow.
+ * Uses the existing /auth/plugin + /api/plugin/auth/poll infrastructure.
+ */
+export declare function getAppUrl(): string;
+export declare function getSupabaseUrl(): string;
+export declare function getSupabaseAnonKey(): string;
+export declare function decodeJwtExp(token: string): number;
+export declare function isTokenExpired(token: string, bufferSeconds?: number): boolean;
+export declare function login(appUrl?: string): Promise<{
+    accessToken: string;
+    refreshToken: string;
+}>;
+export declare function refreshTokens(refreshToken: string, supabaseUrl?: string, anonKey?: string): Promise<{
+    accessToken: string;
+    refreshToken: string;
+}>;

package/dist/auth.js

@@ -0,0 +1,102 @@
+/**
+ * Browser-based authentication via the Ish frontend plugin auth flow.
+ * Uses the existing /auth/plugin + /api/plugin/auth/poll infrastructure.
+ */
+import * as crypto from "node:crypto";
+import { execFile } from "node:child_process";
+const POLL_INTERVAL = 2_000;
+const LOGIN_TIMEOUT = 5 * 60 * 1000; // 5 minutes (matches server-side token TTL)
+const DEFAULT_APP_URL = "https://app.ishlabs.io";
+const DEFAULT_SUPABASE_URL = "https://hngymyxdyamokpbeakps.supabase.co";
+const DEFAULT_SUPABASE_ANON_KEY = "sb_publishable_JlS-HfwNyDqLNbrfbrkUlw_PSdZJdo2";
+export function getAppUrl() {
+    return process.env.ISH_APP_URL ?? DEFAULT_APP_URL;
+}
+export function getSupabaseUrl() {
+    return process.env.ISH_SUPABASE_URL ?? DEFAULT_SUPABASE_URL;
+}
+export function getSupabaseAnonKey() {
+    return process.env.ISH_SUPABASE_ANON_KEY ?? DEFAULT_SUPABASE_ANON_KEY;
+}
+// --- Browser open ---
+function openBrowser(url) {
+    if (process.platform === "win32") {
+        execFile("cmd", ["/c", "start", "", url]);
+    }
+    else if (process.platform === "darwin") {
+        execFile("open", [url]);
+    }
+    else {
+        execFile("xdg-open", [url]);
+    }
+}
+// --- JWT decode ---
+export function decodeJwtExp(token) {
+    try {
+        const payload = token.split(".")[1];
+        const decoded = JSON.parse(Buffer.from(payload, "base64url").toString());
+        return decoded.exp;
+    }
+    catch {
+        return 0;
+    }
+}
+export function isTokenExpired(token, bufferSeconds = 300) {
+    const exp = decodeJwtExp(token);
+    if (!exp)
+        return true;
+    return Date.now() / 1000 >= exp - bufferSeconds;
+}
+// --- Login via browser polling ---
+export async function login(appUrl) {
+    const url = appUrl ?? getAppUrl();
+    const state = crypto.randomBytes(32).toString("hex");
+    const loginUrl = `${url}/auth/plugin?state=${state}`;
+    console.log("Opening browser to sign in...");
+    console.log(`If the browser doesn't open, visit:\n  ${loginUrl}\n`);
+    openBrowser(loginUrl);
+    console.log("Waiting for authentication...");
+    const deadline = Date.now() + LOGIN_TIMEOUT;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL));
+        try {
+            const resp = await fetch(`${url}/api/plugin/auth/poll?state=${state}`, {
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (resp.status === 200) {
+                const data = await resp.json();
+                if (data.status === "complete" && data.access_token && data.refresh_token) {
+                    return { accessToken: data.access_token, refreshToken: data.refresh_token };
+                }
+            }
+            // 202 = pending, keep polling
+        }
+        catch {
+            // Network error, keep polling
+        }
+    }
+    throw new Error("Login timed out. Please try again.");
+}
+// --- Token refresh ---
+export async function refreshTokens(refreshToken, supabaseUrl, anonKey) {
+    const url = supabaseUrl ?? getSupabaseUrl();
+    const key = anonKey ?? getSupabaseAnonKey();
+    const resp = await fetch(`${url}/auth/v1/token?grant_type=refresh_token`, {
+        method: "POST",
+        headers: {
+            apikey: key,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ refresh_token: refreshToken }),
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!resp.ok) {
+        const body = await resp.text().catch(() => "");
+        throw new Error(`Token refresh failed (HTTP ${resp.status}): ${body}`);
+    }
+    const data = await resp.json();
+    if (!data.access_token || !data.refresh_token) {
+        throw new Error("Token refresh response missing required fields");
+    }
+    return { accessToken: data.access_token, refreshToken: data.refresh_token };
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,5 @@
+/**
+ * ish config — Manage simulation configs.
+ */
+import type { Command } from "commander";
+export declare function registerConfigCommands(program: Command): void;

package/dist/commands/config.js

@@ -0,0 +1,82 @@
+/**
+ * ish config — Manage simulation configs.
+ */
+import { withClient, readJsonFileOrStdin } from "../lib/command-helpers.js";
+import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
+import { output, formatConfigList } from "../lib/output.js";
+export function registerConfigCommands(program) {
+    const config = program
+        .command("config")
+        .description("Manage simulation configs");
+    config
+        .command("list")
+        .description("List all simulation configs")
+        .addHelpText("after", "\nExamples:\n  $ ish config list\n  $ ish config list --json")
+        .action(async (_opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get("/dev/simulation-configs");
+            formatConfigList(data, globals.json);
+        });
+    });
+    config
+        .command("create")
+        .description("Create a simulation config")
+        .requiredOption("--file <path>", "JSON file with config data")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = await readJsonFileOrStdin(opts.file);
+            const data = await client.post("/dev/simulation-configs", body);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.config, String(result.id));
+            output(result, globals.json);
+        });
+    });
+    config
+        .command("get")
+        .description("Get simulation config details")
+        .argument("<id>", "Config ID")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get(`/dev/simulation-configs/${resolveId(id)}`);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.config, String(result.id));
+            output(result, globals.json);
+        });
+    });
+    config
+        .command("schema")
+        .description("Get simulation config schema with defaults")
+        .action(async (_opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get("/dev/simulation-configs/schema");
+            output(data, globals.json);
+        });
+    });
+    config
+        .command("update")
+        .description("Update a simulation config")
+        .argument("<id>", "Config ID")
+        .requiredOption("--file <path>", "JSON file with update data")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = await readJsonFileOrStdin(opts.file);
+            const data = await client.put(`/dev/simulation-configs/${resolveId(id)}`, body);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.config, String(result.id));
+            output(result, globals.json);
+        });
+    });
+    config
+        .command("delete")
+        .description("Delete a simulation config")
+        .argument("<id>", "Config ID")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            await client.del(`/dev/simulation-configs/${resolveId(id)}`);
+            output({ message: "Config deleted" }, globals.json);
+        });
+    });
+}

package/dist/commands/iteration.d.ts

@@ -0,0 +1,5 @@
+/**
+ * ish iteration — Manage iterations (usually created via `simulation run`).
+ */
+import type { Command } from "commander";
+export declare function registerIterationCommands(program: Command): void;

package/dist/commands/iteration.js

@@ -0,0 +1,134 @@
+/**
+ * ish iteration — Manage iterations (usually created via `simulation run`).
+ */
+import { withClient, resolveStudy } from "../lib/command-helpers.js";
+import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
+import { output, formatIterationList } from "../lib/output.js";
+export function registerIterationCommands(program) {
+    const iteration = program
+        .command("iteration")
+        .description("Manage iterations (usually created via `simulation run`)");
+    iteration
+        .command("list")
+        .description("List iterations for a study")
+        .option("--study <id>", "Study ID")
+        .addHelpText("after", "\nExamples:\n  $ ish iteration list --study <id>\n  $ ish iteration list --study <id> --json")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get(`/studies/${resolveStudy(opts.study)}/iterations`);
+            formatIterationList(data, globals.json);
+        });
+    });
+    iteration
+        .command("create")
+        .description("Create a new iteration (low-level)")
+        .option("--study <id>", "Study ID")
+        .requiredOption("--name <name>", "Iteration name")
+        .option("--description <description>", "Iteration description")
+        .option("--details-json <json>", "Iteration details as JSON string")
+        .addHelpText("after", `
+Examples:
+  # Interactive:
+  $ ish iteration create --study S --name "v1" \\
+    --details-json '{"type":"interactive","platform":"browser","url":"https://example.com","screen_format":"desktop"}'
+
+  # Text/email:
+  $ ish iteration create --study S --name "v1" \\
+    --details-json '{"type":"text","content_text":"Your email content here","title":"Newsletter"}'
+
+  # Video:
+  $ ish iteration create --study S --name "v1" \\
+    --details-json '{"type":"video","content_url":"https://cdn.example.com/video.mp4","mime_type":"video/mp4"}'
+
+  # Image:
+  $ ish iteration create --study S --name "v1" \\
+    --details-json '{"type":"image","image_urls":["https://cdn.example.com/a.png","https://cdn.example.com/b.png"]}'
+
+  # Document (PDF):
+  $ ish iteration create --study S --name "v1" \\
+    --details-json '{"type":"document","content_url":"https://cdn.example.com/report.pdf","mime_type":"application/pdf"}'
+
+  Note: For local file uploads, use \`ish simulation run\` which automatically
+  uploads files and resolves URLs (e.g. --content-url ./video.mp4).`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = {
+                name: opts.name,
+                ...(opts.description !== undefined && { description: opts.description }),
+                ...(opts.detailsJson && { details: (() => { try {
+                        return JSON.parse(opts.detailsJson);
+                    }
+                    catch {
+                        throw new Error("Invalid --details-json: expected valid JSON string");
+                    } })() }),
+            };
+            const data = await client.post(`/studies/${resolveStudy(opts.study)}/iterations`, body);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.iteration, String(result.id));
+            output(result, globals.json);
+        });
+    });
+    iteration
+        .command("get")
+        .description("Get iteration details")
+        .argument("<id>", "Iteration ID")
+        .addHelpText("after", "\nExamples:\n  $ ish iteration get <id>\n  $ ish iteration get <id> --json")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get(`/iterations/${resolveId(id)}`);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.iteration, String(result.id));
+            output(result, globals.json);
+        });
+    });
+    iteration
+        .command("update")
+        .description("Update an iteration")
+        .argument("<id>", "Iteration ID")
+        .option("--name <name>", "Iteration name")
+        .option("--description <description>", "Iteration description")
+        .option("--details-json <json>", "Iteration details as JSON string")
+        .option("--label <label>", "Iteration label (uppercase letters)")
+        .addHelpText("after", "\nExamples:\n  $ ish iteration update <id> --name \"v2\"\n  $ ish iteration update <id> --label B --json")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = {};
+            if (opts.name !== undefined)
+                body.name = opts.name;
+            if (opts.description !== undefined)
+                body.description = opts.description;
+            if (opts.detailsJson !== undefined) {
+                try {
+                    body.details = JSON.parse(opts.detailsJson);
+                }
+                catch {
+                    throw new Error("Invalid --details-json: expected valid JSON string");
+                }
+            }
+            if (opts.label !== undefined)
+                body.label = opts.label;
+            if (Object.keys(body).length === 0) {
+                console.error("No update flags provided. Run `ish iteration update --help` for options.");
+                return;
+            }
+            const data = await client.put(`/iterations/${resolveId(id)}`, body);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.iteration, String(result.id));
+            output(result, globals.json);
+        });
+    });
+    iteration
+        .command("delete")
+        .description("Delete an iteration")
+        .argument("<id>", "Iteration ID")
+        .addHelpText("after", "\nExamples:\n  $ ish iteration delete <id>")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            await client.del(`/iterations/${resolveId(id)}`);
+            output({ message: "Iteration deleted" }, globals.json);
+        });
+    });
+}

package/dist/commands/simulation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ish simulation — Run, monitor, and cancel simulations.
+ *
+ * Primary command: `ish simulation run` — orchestrates the full flow:
+ *   1. Creates iteration (if not provided)
+ *   2. Creates testers from profiles
+ *   3. Starts simulations (interactive or media, based on study modality)
+ */
+import type { Command } from "commander";
+export declare function registerSimulationCommands(program: Command): void;