@ishlabs/cli 0.23.1 → 0.24.1

package/dist/lib/billing.js

@@ -2,41 +2,90 @@
  * 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.
+ * Source of truth: `ish-backend/app/billing/rates.py` (`MODALITY_RATES`,
+ * `compute_step_cost`, `compute_chat_cost`, `ASK_PER_RESPONSE_CREDITS`,
+ * `PAIR_CHAT_SIDE_MULTIPLIER`). These numbers MUST match that module — when a
+ * multiplier changes there, update this file in the same commit, otherwise the
+ * CLI will mislead agents. The backend prices through one `price_run` dispatcher
+ * shared by `POST /billing/estimate` and the real preflight reservation, so the
+ * preview here is calibrated to the actual charge as long as the rates agree.
  *
- * Today every modality uses the same shape: `max(1, round(steps / 10))`
- * per principal (per participant for media/interactive, per conversation for
- * chat, ×2 for participant-pair). Asks bill flat 1 credit per successful
- * participant response. These are intentionally per-run estimates; long-term
- * we'll fetch `GET /billing/rates` and parameterise modalities — see
- * `reference/credits` docs page.
+ * Each modality has its own per-step rate (interactive costs the most —
+ * screenshot + vision per step; text-only the least). The per-principal cost is
+ * `max(1, round(steps * per_step_credits))`, per participant for step-based
+ * modalities and per conversation (×2 in pair mode) for chat. Asks bill a flat
+ * credit per successful participant response (an upper bound — refusals/errors
+ * don't bill). Clients that need authoritative live rates can fetch them from
+ * `GET /billing/rates`; this offline mirror is for the pre-dispatch preview.
  */
-/** Mirror of `app/media/billing.py::media_credit_cost`. */
-export function mediaCreditCost(steps) {
+/**
+ * Per-step credit multiplier per modality. Mirror of
+ * `app/billing/rates.py::MODALITY_RATES` (the `per_step_credits` field).
+ */
+const PER_STEP_CREDITS = {
+    interactive: 1.0,
+    video: 0.5,
+    audio: 0.3,
+    image: 0.2,
+    text: 0.1,
+    document: 0.3,
+    chat: 0.2,
+};
+/** Mirror of `app/billing/rates.py::ASK_PER_RESPONSE_CREDITS`. */
+const ASK_PER_RESPONSE_CREDITS = 1;
+/** Mirror of `app/billing/rates.py::PAIR_CHAT_SIDE_MULTIPLIER`. */
+const PAIR_CHAT_SIDE_MULTIPLIER = 2;
+/**
+ * Round half-to-even ("banker's rounding") to match Python's built-in
+ * `round()`, which the backend uses. `Math.round` rounds half *up*, so for
+ * costs that land on a .5 boundary (e.g. video at rate 0.5 with an odd step
+ * count: 5 × 0.5 = 2.5) it would over-quote by one credit vs the real charge.
+ * Replicating banker's rounding keeps the preview byte-for-byte with the
+ * backend's `compute_step_cost` / `compute_chat_cost`.
+ */
+function bankersRound(value) {
+    const floor = Math.floor(value);
+    const diff = value - floor;
+    if (diff < 0.5)
+        return floor;
+    if (diff > 0.5)
+        return floor + 1;
+    // Exactly .5 — round to the nearest even integer.
+    return floor % 2 === 0 ? floor : floor + 1;
+}
+/**
+ * Per-principal step-based cost for one participant running `steps` interactions
+ * on a study of `modality`. Mirror of `app/billing/rates.py::compute_step_cost`.
+ */
+export function stepCreditCost(modality, steps) {
     if (!Number.isFinite(steps) || steps <= 0)
         return 1;
-    return Math.max(1, Math.round(steps / 10));
+    return Math.max(1, bankersRound(steps * PER_STEP_CREDITS[modality]));
 }
-/** Mirror of `app/chat/billing.py::chat_credit_cost`. */
-export function chatCreditCost(turns) {
+/**
+ * Per-conversation chat cost. Mirror of `app/billing/rates.py::compute_chat_cost`
+ * — `max(1, round(turns * chat_rate))`, doubled in pair mode (both sides bill
+ * per turn).
+ */
+export function chatCreditCost(turns, isPair = false) {
     if (!Number.isFinite(turns) || turns <= 0)
-        return 1;
-    return Math.max(1, Math.round(turns / 10));
+        return isPair ? PAIR_CHAT_SIDE_MULTIPLIER : 1;
+    const perSide = Math.max(1, bankersRound(turns * PER_STEP_CREDITS.chat));
+    return isPair ? perSide * PAIR_CHAT_SIDE_MULTIPLIER : perSide;
 }
 /**
- * Media/interactive run: 1 credit-cost-per-participant × participant count. Modality
- * doesn't currently affect the rate (interactive == text == video at the
- * billing layer) — kept as a parameter for forward compatibility.
+ * Step-based run (interactive / text / image / video / audio / document):
+ * per-participant cost × participant count. The per-step rate is modality-
+ * specific (see `PER_STEP_CREDITS`).
  */
 export function estimateMediaRun(args) {
-    const perParticipant = mediaCreditCost(args.maxInteractions);
+    const perParticipant = stepCreditCost(args.modality, args.maxInteractions);
     const total = Math.max(0, args.participantCount) * perParticipant;
+    const rate = PER_STEP_CREDITS[args.modality];
     return {
         upper_bound: total,
         formula: "media_per_participant",
-        breakdown: `${args.participantCount} participant(s) × max(1, round(${args.maxInteractions} steps / 10)) = ${args.participantCount} × ${perParticipant} = ${total}`,
+        breakdown: `${args.participantCount} participant(s) × max(1, round(${args.maxInteractions} steps × ${rate})) = ${args.participantCount} × ${perParticipant} = ${total}`,
         unit: "credits",
     };
 }
@@ -47,18 +96,19 @@ export function estimateChatSolo(args) {
     return {
         upper_bound: total,
         formula: "chat_solo",
-        breakdown: `${args.participantCount} participant(s) × max(1, round(${args.maxTurns} turns / 10)) = ${args.participantCount} × ${perParticipant} = ${total}`,
+        breakdown: `${args.participantCount} participant(s) × max(1, round(${args.maxTurns} turns × ${PER_STEP_CREDITS.chat})) = ${args.participantCount} × ${perParticipant} = ${total}`,
         unit: "credits",
     };
 }
 /** Participant-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;
+    const perConversation = chatCreditCost(args.maxTurns, true);
+    const perSide = perConversation / PAIR_CHAT_SIDE_MULTIPLIER;
+    const total = Math.max(0, args.conversationCount) * perConversation;
     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}`,
+        breakdown: `${args.conversationCount} conv × max(1, round(${args.maxTurns} turns × ${PER_STEP_CREDITS.chat})) × ${PAIR_CHAT_SIDE_MULTIPLIER} sides = ${args.conversationCount} × ${perSide} × ${PAIR_CHAT_SIDE_MULTIPLIER} = ${total}`,
         unit: "credits",
     };
 }
@@ -67,11 +117,11 @@ export function estimateChatPair(args) {
  * for completed responses; the upper bound assumes everyone completes).
  */
 export function estimateAskRound(args) {
-    const total = Math.max(0, args.participantCount);
+    const total = Math.max(0, args.participantCount) * ASK_PER_RESPONSE_CREDITS;
     return {
         upper_bound: total,
         formula: "ask_per_response",
-        breakdown: `${args.participantCount} participant(s) × 1 credit/response = ${total} (upper bound; only successful responses bill)`,
+        breakdown: `${args.participantCount} participant(s) × ${ASK_PER_RESPONSE_CREDITS} credit/response = ${total} (upper bound; only successful responses bill)`,
         unit: "credits",
     };
 }

package/dist/lib/command-helpers.js

@@ -657,14 +657,38 @@ function noActiveContextError(message, errorCode, suggestions) {
     err.suggestions = suggestions;
     return err;
 }
+/**
+ * Reject an explicitly-supplied-but-empty context flag (`--study ""`,
+ * `--workspace "   "`). Distinct from the flag being *omitted*
+ * (`explicit === undefined`), which legitimately falls through to env →
+ * active-config. An empty/whitespace value is a usage error: it would
+ * otherwise be falsy and silently resolve to the active context, attaching
+ * work to the wrong entity. Maps to exit 2 via the ValidationError name.
+ */
+function rejectEmptyContextFlag(explicit, flag, noun) {
+    if (!explicit.trim()) {
+        const err = new Error(`${flag} was given an empty value. Pass a ${noun} id/alias, or omit it to use the active ${noun}.`);
+        err.name = "ValidationError";
+        throw err;
+    }
+}
 export function resolveWorkspace(explicit) {
-    if (explicit)
+    if (explicit !== undefined) {
+        rejectEmptyContextFlag(explicit, "--workspace", "workspace");
         return resolveId(explicit);
+    }
     // Fall back to the program-root --workspace cached by applyGlobals — covers
     // `ish --workspace W study list` where the subcommand action doesn't see the
-    // flag in its local opts.
-    if (_activeWorkspace)
+    // flag in its local opts. The GLOBAL --workspace shadows the subcommand's
+    // local one, so an empty `--workspace ""` arrives HERE (as `_activeWorkspace
+    // === ""`), never via `explicit`. computeGlobals preserves the empty-vs-
+    // omitted distinction (`""` when passed empty, `undefined` when omitted), so
+    // apply the same empty-value guard as `explicit` above — otherwise
+    // `--workspace ""` silently falls through to env/saved config (exit 0).
+    if (_activeWorkspace !== undefined) {
+        rejectEmptyContextFlag(_activeWorkspace, "--workspace", "workspace");
         return resolveId(_activeWorkspace);
+    }
     const env = process.env.ISH_WORKSPACE;
     if (env)
         return resolveId(env);
@@ -677,8 +701,10 @@ export function resolveWorkspace(explicit) {
     ]);
 }
 export function resolveStudy(explicit) {
-    if (explicit)
+    if (explicit !== undefined) {
+        rejectEmptyContextFlag(explicit, "--study", "study");
         return resolveId(explicit);
+    }
     const env = process.env.ISH_STUDY;
     if (env)
         return resolveId(env);
@@ -691,8 +717,10 @@ export function resolveStudy(explicit) {
     ]);
 }
 export function resolveAsk(explicit) {
-    if (explicit)
+    if (explicit !== undefined) {
+        rejectEmptyContextFlag(explicit, "--ask", "ask");
         return resolveId(explicit);
+    }
     const env = process.env.ISH_ASK;
     if (env)
         return resolveId(env);

package/dist/lib/docs.js

@@ -98,10 +98,20 @@ ish workspace list
 ish workspace create --name "My product" --base-url https://example.com
 ish workspace use w-6ec        # set as active
 ish workspace get              # show the active workspace
+ish workspace update w-6ec --logo https://logo.clearbit.com/acme.com  # brand logo
 ish workspace info             # usage counters + plan caps (see below)
 ish workspace site-access status
 \`\`\`
 
+## Branding a workspace (\`--logo\`)
+
+\`ish workspace update <id> --logo <url>\` sets a brand logo from an
+external image URL. The logo shows on the workspace and — importantly —
+on **shared study links** (\`ish study share\`), so a prospect opening the
+public link sees the demo branded with their own logo. There is no
+\`--logo\` on \`workspace create\`; create first, then update. See
+\`concepts/sharing\`.
+
 ## Checking usage before destructive calls
 
 \`ish workspace info\` shows usage counters so an agent can branch on
@@ -217,6 +227,15 @@ its iterations. Think: a study is the recipe; an iteration is one batch.
 iteration A inline in the same call. Useful when you have a single
 test artifact and don't need to A/B iterations:
 
+For text + media, the inline iteration A can also carry
+\`--segmentation-json\` (+ \`--content-config-json\`) and the text
+email-styling flags (\`--content-html\`, \`--sender-name\`,
+\`--sender-email\`, \`--featured-image-url\`). So a single-iteration
+**segmented** study is one \`study create\` call — you do NOT need a
+second \`iteration create\` (which would leave an empty A plus a
+redundant B). Reach for \`iteration create\` only when you genuinely
+want a 2nd iteration to A/B.
+
 | Modality        | Inline content flag                                  |
 |-----------------|------------------------------------------------------|
 | \`interactive\` | \`--url <url>\` (\`--screen-format desktop\` is the default; pass \`mobile_portrait\` for mobile) |
@@ -402,6 +421,14 @@ Each segment can carry a human-readable **label** ("Intro", "Pricing
 section", "Call to action") that surfaces in the participant UI and in
 results.
 
+**Segments are semantic sections, not paragraphs.** Group related
+paragraphs into a few coherent sections — a 16-paragraph article is
+usually 3–6 sections (e.g. "Lede", "The argument", "Counterpoints",
+"Conclusion"), not 16. \`paragraph_start\`/\`paragraph_end\` only mark
+where a section begins and ends; the unit you are choosing is the
+*section*. The CLI errors on a missing label and warns when you emit one
+section per paragraph.
+
 Segments live inside the iteration's \`segmentation\` field — there is
 no separate segments resource. Three discriminated shapes:
 
@@ -431,6 +458,11 @@ no separate segments resource. Three discriminated shapes:
   }
   \`\`\`
 
+  The three sections above each group several paragraphs (greeting +
+  context, the body, the call to action) — semantic grouping, not one
+  section per paragraph. Adjust the ranges to your content's logical
+  structure.
+
 - **page_based** (document): pages are auto-derived from the document.
   No additional fields.
 
@@ -888,12 +920,16 @@ Two flags, mutually exclusive:
 # --question is repeatable. Defaults to type=text, timing=after.
 ish study create … --question "How easy was it?" --question "Anything confusing?"
 
-# Richer types from a JSON manifest:
-ish study create … --questionnaire ./questionnaire.json
+# Richer types via --questionnaire. Three interchangeable input forms — no
+# temp file required (mirrors how --assignments takes inline JSON):
+ish study create … --questionnaire '[{"question":"How easy?","type":"slider","min":0,"max":10}]'   # inline JSON
+ish study create … --questionnaire @/tmp/questionnaire.json                                         # @file
+ish study create … --questionnaire ./questionnaire.json                                             # bare path
 \`\`\`
 
-\`questionnaire.json\` is an array of question objects in the shape above.
-The same shape is accepted by \`ish ask add-questions … --questions …\`.
+The payload is always an array of question objects in the shape above
+(inline JSON must start with \`[\`; an \`@\`-prefixed or bare value is read
+from disk). The same three input forms are accepted by \`ish ask … --questions\`.
 
 The \`type\` field is hyphenated for the multi-word values (\`single-choice\`,
 \`multiple-choice\`). The CLI normalises the underscored variants
@@ -2130,11 +2166,27 @@ The CLI guarantees these contracts so agents can chain safely:
   \`--fields\` set, you can identify the affected resource. Default
   write-path JSON is compact (\`{id, alias, name, updated_at,
   ...changed_fields}\`); pass \`--verbose\` for the full server payload.
+- **Write-path echoes keep collection arrays even when empty.** On a
+  create/update echo (e.g. \`study create\`/\`study update\`), entity
+  collections like \`assignments\`, \`interview_questions\`, and
+  \`iterations\` are always present — \`[]\` when the resource has none,
+  not dropped. So the echo reflects exactly what was persisted: an empty
+  \`assignments\` means the study genuinely has no assignment and will
+  fail at run with "Study has no assignments" — you don't need a second
+  \`--verbose\` (or \`study get\`) call to tell "zero persisted" from
+  "stripped by lean mode." (Read-path \`list\` responses still drop empty
+  per-item arrays as noise; this guarantee is write-path only.)
 - **\`person generate\` returns \`{job: {id, status, person_ids},
   profiles: [...]}\`** in \`--json\` mode. Each profile is the
   lean \`person\` shape (pass \`--verbose\` for the full record,
   including \`simulation_config\`) with its evidence-grounded
   \`scenarios\` attached; pass \`--no-scenarios\` to omit them.
+- **\`study share\` returns \`{id, token, share_url, expires_at,
+  created_at}\`** in \`--json\` mode (full envelope, not lean-stripped).
+  \`share_url\` is the public no-login URL — use it verbatim. In human
+  mode \`share_url\` goes to stdout, context to stderr. \`study share
+  --list\` returns rows of \`{token, study, expires_at, is_revoked}\`
+  (no \`share_url\` — only create returns it). See \`concepts/sharing\`.
 - **\`<entity> get\` accepts multiple IDs.** \`person get\`, \`study get\`,
   \`iteration get\`, and \`ask get\` all take \`<ids...>\` — pass two or
   more aliases (space- or comma-separated) and the response is a
@@ -2835,10 +2887,16 @@ script or agent session.
 
 ### \`ish login\` is idempotent
 
-When you already have a valid saved token, \`ish login\` short-circuits
-with a friendly "Already logged in" message and **does not** open a new
-browser tab or register a fresh OAuth client. Use \`--force\` (or \`-f\`)
-to bypass the guard — typical reason is switching accounts.
+When you already have a saved token that is **both unexpired and still
+accepted by the API**, \`ish login\` short-circuits with a friendly
+"Already logged in" message and **does not** open a new browser tab or
+register a fresh OAuth client. If the saved token is unexpired but the
+server rejects it — a revoked session, a rotated signing key, or a token
+minted against the wrong Supabase project (e.g. a dev-issued token while
+calling the prod api) — the guard falls through and re-runs the browser
+flow instead of falsely reporting "Already logged in". Use \`--force\`
+(or \`-f\`) to bypass the guard unconditionally — typical reason is
+switching accounts.
 
 \`\`\`bash
 ish login              # no-op when already authenticated
@@ -4187,6 +4245,74 @@ overridden URL.
 
 - \`reference/json-mode\` — display vs capture vs chain output rules.
 `;
+const CONCEPT_SHARE = `# concept: sharing study results
+
+A **share link** is a public, no-login URL to one study's results. Anyone
+with the link opens it in a browser — no ish account — and sees the study's
+summary, key insights, participant journeys, interactive frames, and segment
+breakdowns (read-only). This is how you hand a study to someone outside your
+workspace: a prospect, a stakeholder, a teammate without a seat.
+
+- Created via: \`ish study share [id]\` (defaults to the active study).
+- Revoked via: \`ish study unshare <token>\`.
+- The link host is the **web app frontend**, not the API host. The backend
+  returns the fully-formed \`share_url\` — print/use it verbatim. Do NOT
+  hand-build the URL from the API host or app URL; they differ.
+
+## Create a link
+
+\`\`\`
+ish study share                      # share the active study
+ish study share s-b2c                # share a specific study
+ish study share s-b2c --expires 30   # auto-expire 30 days from now
+ish study share s-b2c --json         # { token, share_url, expires_at, created_at, id }
+\`\`\`
+
+Human mode prints the \`share_url\` to **stdout** (it's the deliverable — a
+URL to paste into an email) and the token / expiry / revoke hint to stderr.
+JSON mode returns the full create envelope:
+
+\`\`\`json
+{
+  "id": "…",
+  "token": "Hk9_…",            // opaque url-safe token, NOT an alias
+  "share_url": "https://<frontend>/share/study/Hk9_…",
+  "expires_at": null,           // null = never expires
+  "created_at": "…"
+}
+\`\`\`
+
+## List and revoke
+
+\`\`\`
+ish study share --list               # every share link you created (all studies)
+ish study unshare Hk9_…              # revoke by raw token; URL stops working immediately
+ish study unshare Hk9_… --yes        # skip the confirmation (required in --json / non-TTY)
+\`\`\`
+
+The \`--list\` rows carry \`token\`, \`study\` (aliased), \`expires_at\`,
+\`is_revoked\`. The full \`share_url\` only comes back from \`share\` (create) —
+list responses do not reconstruct it. \`study unshare\` takes the **raw token**,
+never a study ID or alias.
+
+## What a good shareable study looks like
+
+The viewer is only as good as the run behind it. Before sharing, make sure:
+- The study has **run** with enough participants (\`ish study run … --wait\`;
+  analysis needs ≥5 completed participants) and no broken simulations.
+- An **analysis** has been generated so the summary + key insights render
+  (\`ish study analyze --wait\` → \`ish study insights\`).
+- For media studies, every **segment is labelled** (see \`concepts/iteration\`).
+- The workspace has a **logo** if you want the link branded
+  (\`ish workspace update <id> --logo <url>\`).
+
+## Related
+
+- \`concepts/study\` — the artifact a link points at.
+- \`concepts/workspace\` — \`--logo\` branding shown on the shared link.
+- \`concepts/active-context\` — \`ish study share\` defaults to the active study.
+- \`reference/json-mode\` — the \`{ token, share_url, … }\` envelope.
+`;
 const PAGES = [
     {
         slug: "overview",
@@ -4284,6 +4410,12 @@ const PAGES = [
         description: "Saved workspace/study/ask state and how to inspect it (ish status).",
         body: CONCEPT_ACTIVE_CONTEXT,
     },
+    {
+        slug: "concepts/sharing",
+        title: "concept: sharing study results",
+        description: "Public no-login share links for a study: study share / study unshare / --list, --expires, token vs URL, branding with workspace --logo.",
+        body: CONCEPT_SHARE,
+    },
     {
         slug: "reference/aliases",
         title: "reference: aliases",

package/dist/lib/modality.d.ts

@@ -7,7 +7,16 @@
  * and the call sites (`study run`, `iteration update`, ...) pick up the
  * change for free.
  */
-export type Modality = "interactive" | "video" | "audio" | "text" | "image" | "document" | "chat";
+/** All study modalities. Matches the backend `Modality` enum value set. */
+export declare const MODALITIES: readonly ["interactive", "video", "audio", "text", "image", "document", "chat"];
+export type Modality = typeof MODALITIES[number];
+/**
+ * Coerce a raw study-modality string to a known `Modality`, defaulting to
+ * `"interactive"` for unknown/empty values — the same default the CLI uses
+ * elsewhere (`study.modality || "interactive"`) and the highest-cost rate, so
+ * an unrecognised modality errs toward over-estimating rather than under.
+ */
+export declare function toModality(raw: string | undefined): Modality;
 /** True for the media-bucket modalities that share batch + content semantics. */
 export declare function isMediaModality(modality: string | undefined): boolean;
 /** True for chat modality. Wrapped as a helper so callers don't sprinkle string literals. */

package/dist/lib/modality.js

@@ -9,6 +9,27 @@
  */
 import { normalizeEnumValue } from "./enums.js";
 import { MEDIA_MODALITIES } from "./types.js";
+/** All study modalities. Matches the backend `Modality` enum value set. */
+export const MODALITIES = [
+    "interactive",
+    "video",
+    "audio",
+    "text",
+    "image",
+    "document",
+    "chat",
+];
+/**
+ * Coerce a raw study-modality string to a known `Modality`, defaulting to
+ * `"interactive"` for unknown/empty values — the same default the CLI uses
+ * elsewhere (`study.modality || "interactive"`) and the highest-cost rate, so
+ * an unrecognised modality errs toward over-estimating rather than under.
+ */
+export function toModality(raw) {
+    return MODALITIES.includes(raw ?? "")
+        ? raw
+        : "interactive";
+}
 /** True for the media-bucket modalities that share batch + content semantics. */
 export function isMediaModality(modality) {
     return !!modality && MEDIA_MODALITIES.includes(modality);

package/dist/lib/output.js

@@ -196,7 +196,14 @@ function leanJson(data, keepIds = false) {
         // Recurse into objects/arrays
         if (typeof value === "object") {
             const cleaned = leanJson(value, keepIds);
-            if (cleaned !== undefined && !(Array.isArray(cleaned) && cleaned.length === 0)) {
+            // Read paths drop empty arrays as noise. Write-path echoes (keepIds)
+            // must NOT: an empty `assignments`/`interview_questions` is the
+            // "zero persisted" signal the create/update echo exists to surface —
+            // a study with no assignments fails at run with "Study has no
+            // assignments". Dropping it made the echo indistinguishable from a
+            // lean-strip, which is why agents were told not to trust it.
+            const dropEmptyArray = !keepIds && Array.isArray(cleaned) && cleaned.length === 0;
+            if (cleaned !== undefined && !dropEmptyArray) {
                 result[key] = cleaned;
             }
             continue;

package/dist/lib/reverse-proxy.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Local reverse proxy: fan one inbound port out to multiple localhost services
+ * by path prefix. Wired into `ish connect` so a single cloudflared tunnel can
+ * serve a frontend + backend + extras under one origin (no CORS / cookie
+ * cross-origin pain in the cloud browser).
+ */
+export type Route = {
+    prefix: string;
+    target: string;
+};
+export interface ReverseProxyHandle {
+    port: number;
+    close: () => Promise<void>;
+}
+export interface StartReverseProxyOptions {
+    primaryPort: number;
+    routes: Route[];
+}
+export declare function startReverseProxy(opts: StartReverseProxyOptions): Promise<ReverseProxyHandle>;

package/dist/lib/reverse-proxy.js

@@ -0,0 +1,87 @@
+/**
+ * Local reverse proxy: fan one inbound port out to multiple localhost services
+ * by path prefix. Wired into `ish connect` so a single cloudflared tunnel can
+ * serve a frontend + backend + extras under one origin (no CORS / cookie
+ * cross-origin pain in the cloud browser).
+ */
+import http from "node:http";
+import httpProxy from "http-proxy";
+function resolveRoute(url, sortedRoutes, fallback) {
+    const path = url ?? "/";
+    for (const route of sortedRoutes) {
+        // Match the prefix at a segment boundary so `/api` doesn't catch `/apiary`.
+        if (path === route.prefix || path.startsWith(route.prefix + "/") || path.startsWith(route.prefix + "?")) {
+            return route.target;
+        }
+    }
+    return fallback;
+}
+export function startReverseProxy(opts) {
+    return new Promise((resolve, reject) => {
+        const primaryTarget = `http://127.0.0.1:${opts.primaryPort}`;
+        // Longest prefix wins: a request to `/api/v1/x` with routes
+        // `[/api, /api/v1]` should land on `/api/v1`.
+        const sortedRoutes = [...opts.routes]
+            .map((r) => ({ prefix: r.prefix, target: r.target }))
+            .sort((a, b) => b.prefix.length - a.prefix.length);
+        const proxy = httpProxy.createProxyServer({
+            xfwd: true,
+            ws: true,
+            // Preserve the full original path — http-proxy does this by default when
+            // we pass `target` without `prependPath`/`ignorePath`. Setting changeOrigin
+            // false keeps the Host header pointing at the upstream's address.
+            changeOrigin: false,
+        });
+        proxy.on("error", (err, _req, res) => {
+            // `res` can be either an HTTP response or a raw socket (WS upgrade path).
+            if (res && "writeHead" in res && typeof res.writeHead === "function") {
+                const httpRes = res;
+                if (!httpRes.headersSent) {
+                    httpRes.writeHead(502, { "Content-Type": "text/plain; charset=utf-8" });
+                }
+                httpRes.end(`Bad gateway: upstream not reachable (${err.message})`);
+            }
+            else if (res && "destroy" in res && typeof res.destroy === "function") {
+                res.destroy();
+            }
+        });
+        // Track open sockets so close() can force-destroy them — mirrors the
+        // shutdown discipline in src/auth.ts. server.close() alone waits for
+        // keep-alive sockets to drain, which hangs the CLI on SIGINT.
+        const sockets = new Set();
+        const server = http.createServer((req, res) => {
+            const target = resolveRoute(req.url, sortedRoutes, primaryTarget);
+            proxy.web(req, res, { target });
+        });
+        server.on("upgrade", (req, socket, head) => {
+            const target = resolveRoute(req.url, sortedRoutes, primaryTarget);
+            proxy.ws(req, socket, head, { target });
+        });
+        server.on("connection", (socket) => {
+            sockets.add(socket);
+            socket.on("close", () => sockets.delete(socket));
+        });
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (!addr || typeof addr === "string") {
+                reject(new Error("Failed to bind reverse proxy"));
+                return;
+            }
+            resolve({
+                port: addr.port,
+                close: () => new Promise((resolveClose) => {
+                    // Stop accepting new connections, then force-destroy anything still
+                    // open. closeAllConnections + the manual socket sweep is what makes
+                    // shutdown reliable on macOS (see auth.ts comment).
+                    server.close(() => resolveClose());
+                    server.closeAllConnections?.();
+                    for (const socket of sockets)
+                        socket.destroy();
+                    sockets.clear();
+                    proxy.close();
+                }),
+            });
+        });
+    });
+}

package/dist/lib/reverse-proxy.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Smoke test for the reverse-proxy module. Spins up two mock HTTP servers,
+ * routes through the proxy, and asserts paths land on the right upstream
+ * with the full path preserved. Also verifies a raw WebSocket upgrade
+ * routes via the prefix rules.
+ *
+ * Compiled to dist/lib/reverse-proxy.test.js and runnable with:
+ *   node --test dist/lib/reverse-proxy.test.js
+ */
+export {};