cue-ai 0.9.0 → 0.9.2

package/resources/skills/skills/tools/portless/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: portless
+description: Named .localhost HTTPS URLs for local dev instead of port numbers. Use when the user says "portless", "https on localhost", "named dev URL", "stop using port 3000", or runs multiple dev servers (Next.js, Vite, Medusa) that collide on ports. Prefer it for Medusa shop local dev.
+allowed-tools: Bash(portless:*), Bash(npm:*)
+category: tools
+tags: [tools, local-dev, https, proxy, dev-server, medusa, monorepo]
+requires_mcps: []
+metadata:
+  version: 1.0.0
+  homepage: https://github.com/vercel-labs/portless
+---
+
+# portless: named .localhost URLs for local dev
+
+Run dev servers behind stable `https://<name>.localhost` URLs instead of memorizing port numbers. portless starts a local HTTPS proxy, assigns each app an ephemeral port via `PORT`, and routes a clean URL to it. HTTP/2 + a trusted local CA come on by default, so no browser warnings and no port collisions when several servers run at once.
+
+Pre-1.0 (current 0.13.x): the state-dir format can change between releases, so re-run `portless trust` after upgrades if certs stop working.
+
+## When to activate
+
+- User wants `https://myapp.localhost` instead of `http://localhost:3000`.
+- Two or more dev servers fight over ports (admin + storefront, web + api).
+- A Medusa shop needs local URLs for both the backend and the storefront.
+- User asks for HTTPS/HTTP-2 on localhost without manual mkcert setup.
+- A monorepo (pnpm/turbo) needs one URL per workspace package.
+
+## Prerequisites
+
+Install once, globally (recommended so every project shares one proxy + CA):
+
+```bash
+npm install -g portless
+portless --version          # -> portless 0.13.x
+```
+
+First run generates a local CA, trusts it, and binds port 443 (auto-elevates with `sudo` on macOS/Linux). To skip HTTPS use `--no-tls`.
+
+## Step 1: run a single app
+
+Infer the name from `package.json`/git root and run the `dev` script through the proxy:
+
+```bash
+portless run next dev
+# -> https://myapp.localhost
+```
+
+Or name it explicitly:
+
+```bash
+portless myapp next dev
+# -> https://myapp.localhost
+```
+
+Bare `portless` (no args) runs the `dev` script and infers the name:
+
+```bash
+portless            # -> runs "dev", https://<project>.localhost
+```
+
+## Step 2: wire it into package.json
+
+Put the proxy in the script once so it works for everyone:
+
+```jsonc
+{ "scripts": { "dev": "portless run next dev" } }
+```
+
+With a `portless.json` you can keep the script clean and run `portless` to route it:
+
+```jsonc
+// portless.json
+{ "name": "myapp" }
+```
+
+```bash
+portless            # runs "dev", https://myapp.localhost
+PORTLESS=0 pnpm dev # bypass the proxy, use the default port
+```
+
+## Step 3: subdomains and monorepos
+
+Organize services under subdomains:
+
+```bash
+portless api.myapp pnpm start    # -> https://api.myapp.localhost
+portless docs.myapp next dev     # -> https://docs.myapp.localhost
+```
+
+One `portless.json` at the repo root covers every workspace package (pnpm/npm/yarn/bun). The `apps` map is only for name overrides:
+
+```jsonc
+{
+  "apps": {
+    "apps/web": { "name": "myapp" },
+    "apps/api": { "name": "api.myapp" }
+  }
+}
+```
+
+```bash
+portless                  # from repo root: start every package with a "dev" script
+cd apps/web && portless   # start just one
+```
+
+## Step 4: Medusa shop local dev (preferred)
+
+For `medusa-shops/<shop>`, route both halves through portless so admin and storefront stop colliding on ports:
+
+```bash
+# backend (Medusa serves admin on the injected PORT)
+portless admin.myshop medusa develop   # -> https://admin.myshop.localhost
+
+# storefront
+portless myshop pnpm dev               # -> https://myshop.localhost
+```
+
+Next.js storefronts must allow the dev origin:
+
+```js
+// next.config.js
+module.exports = { allowedDevOrigins: ["myshop.localhost", "*.myshop.localhost"] }
+```
+
+If the storefront proxies `/api` to the backend, set `changeOrigin: true` or portless returns `508 Loop Detected` (it rewrites the `Host` header back to the proxy). See Rules.
+
+Related: the `medusa-local-dev` skill runs many shops on a fixed-port registry (`.dev-ports.yaml`) with the `medusa-dev` helper for lifecycle (start/stop/tail). portless is the preferred URL layer on top: keep `medusa-dev` for process management, or pass `portless --app-port <registry-port>` to give each shop a clean `https://<shop>.localhost` instead of a bare port.
+
+## Step 5: git worktrees
+
+`portless run` auto-detects linked worktrees and prepends the branch as a subdomain, so each worktree gets its own URL with zero config:
+
+```bash
+# main checkout
+portless run next dev               # -> https://myapp.localhost
+# worktree on branch "fix-ui"
+portless run next dev               # -> https://fix-ui.myapp.localhost
+```
+
+## Commands reference
+
+```bash
+portless list                 # show active routes (local + tailnet)
+portless alias <name> <port>  # static route, e.g. point a name at a Docker port
+portless trust                # (re)add the local CA to the system trust store
+portless prune                # kill orphaned dev servers from crashed sessions
+portless hosts sync           # add routes to /etc/hosts (fixes Safari)
+portless clean                # remove state, CA trust entry, and hosts block
+
+portless proxy start          # start the HTTPS proxy (port 443, daemon)
+portless proxy start --no-tls # plain HTTP on port 80
+portless proxy start -p 1355  # custom port, no sudo
+portless proxy stop
+
+portless service install      # start the proxy at OS startup (survives reboot)
+portless service status
+portless service uninstall
+```
+
+Useful flags: `--no-tls`, `--tld test` (use `.test`, IANA-reserved), `--wildcard` (unregistered subdomains fall back to parent), `--app-port <n>` (fixed port), `--tailscale` / `--funnel` (share over tailnet/public), `--force` (take over a route).
+
+## Examples
+
+**User:** "my next storefront and medusa admin both want port 3000, fix it"
+→ `npm i -g portless`, then `portless admin.shop medusa develop` and `portless shop pnpm dev`. Two clean HTTPS URLs, no port clash. Add `allowedDevOrigins` to `next.config.js`.
+
+**User:** "give me https on localhost without mkcert"
+→ `portless run next dev`. First run trusts a local CA automatically; the app is at `https://<project>.localhost` with HTTP/2.
+
+**User:** "Safari can't reach myapp.localhost"
+→ `portless hosts sync` (Safari uses the system resolver, which may not handle `.localhost` subdomains).
+
+**User:** "spin up every app in this pnpm monorepo"
+→ from the repo root, `portless`. It discovers workspace packages and starts each one's `dev` script under `<package>.<project>.localhost`.
+
+**User:** "I keep getting 508 Loop Detected"
+→ the frontend proxies to another portless app without rewriting `Host`. Set `changeOrigin: true` (Vite/webpack) so portless routes to the target app, not back to itself.
+
+## Rules
+
+- **Prefer portless in Medusa shops.** Backend (`admin.<shop>.localhost`) and storefront (`<shop>.localhost`) collide on ports otherwise; named URLs remove the juggling and match the deployed `admin.<shop>.hu` shape. WHY: it mirrors prod hostnames and lets both run together.
+- **Install globally for shared state.** One global install means one proxy and one CA across projects. Per-project installs can run different pre-1.0 versions whose state formats diverge, which breaks trust. WHY: avoids re-trusting per repo.
+- **Rewrite the Host header on app-to-app proxies** (`changeOrigin: true`). WHY: without it portless loops the request back to the caller and answers `508 Loop Detected`.
+- **Add storefront origins to `allowedDevOrigins`.** WHY: frameworks reject cross-origin dev requests from the new `.localhost` host otherwise.
+- **CI / non-interactive: portless exits with an error instead of prompting.** Use `PORTLESS=0` to bypass the proxy in scripts that should hit the raw port. WHY: task runners (turbo, CI) must fail fast, not hang on a TTY prompt.
+- **Avoid `.local` and `.dev` TLDs.** `.local` clashes with mDNS/Bonjour; `.dev` is HSTS-forced by Google. Use the default `.localhost` or `--tld test`. WHY: collision and forced-HTTPS surprises.
+- **`run get alias hosts list trust clean prune proxy service` are reserved** subcommands and cannot be app names. Use `portless run <cmd>` or `portless --name <name> <cmd>` to force one.

package/resources/skills/skills/xbot/operate/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: operate
+description: >-
+  Use when the user wants to run, drive, or supervise the x-growth-bot (the
+  X / Twitter growth bot in ~/Documents/x-growth-bot) from inside Claude Code.
+  Triggers: "start the bot", "stop the bot", "bot status", "is the loop
+  running", "pause the bot", "resume the bot", "draft a reply", "send a DM",
+  "run a dry cycle", "show pending replies", "what's the bot doing", "check
+  caps", "engage candidates", "growth report". Routes every action to the
+  right surface: the `xbot` MCP tools, the `./botctl` wrapper, or
+  `python -m xbot.cli`, and enforces the loop-vs-MCP write-safety rule.
+triggers:
+  - start the bot
+  - stop the bot
+  - bot status
+  - pause the bot
+  - resume the bot
+  - draft a reply
+  - send a DM
+  - run a dry cycle
+  - show pending replies
+  - growth report
+allowed-tools:
+  - Bash(./botctl:*)
+  - Bash(.venv/bin/python:*)
+  - Bash(claude:*)
+  - Bash(cat:*)
+  - Bash(ls:*)
+  - Bash(tail:*)
+  - Read
+requires_mcps:
+  - xbot
+tags: [xbot, twitter, x, growth, social, bot, operate, mcp]
+domain: social
+category: operate
+---
+
+## What this skill does
+
+Operates the **x-growth-bot** (an autonomous X / Twitter growth bot at
+`~/Documents/x-growth-bot`) from a Claude Code session. It picks the correct
+control surface for each request and keeps live actions safe when the
+background loop is running.
+
+The bot has three control surfaces, all already built:
+
+| Surface | How | Best for |
+| --- | --- | --- |
+| `xbot` **MCP** | MCP tools (`xbot_status`, `xbot_reply`, …) | reads, control, drafting and posting from inside this chat |
+| `./botctl` | Bash wrapper | starting/stopping the loop, operator board, quick status |
+| `xbot.cli` | `.venv/bin/python -m xbot.cli <cmd>` | full surface (`preflight`, `propose`, `commit`, `loop`) |
+
+The MCP and the loop are **separate processes sharing the same on-disk state
+with no lock**. The one hard rule below exists because of that.
+
+## Prerequisites
+
+The bot lives at `~/Documents/x-growth-bot` and ships its own tooling. No global
+install is needed beyond what the repo already provides:
+
+- `./botctl` and `.venv/bin/python -m xbot.cli` come from the repo (the venv is
+  created on setup). Run them from the repo root so state files resolve.
+- The `xbot` MCP server is registered with `claude mcp add xbot --scope local --
+  bash ~/Documents/x-growth-bot/run-mcp.sh`. Newly added tools appear after a
+  Claude Code restart.
+
+## When to activate
+
+- "start / stop / restart the bot", "is the loop alive", "bot status"
+- "pause the bot" / "resume the bot" (emergency circuit)
+- "draft a reply to this tweet", "send a DM", "show pending replies"
+- "run a dry cycle so I can watch it think"
+- "show today's caps / growth / attribution / report"
+- "what did the bot skip and why" (audit log)
+
+## The one hard rule (loop vs MCP writes)
+
+The live `loop` daemon and the `xbot` MCP each build their own session on the
+same account and share caps / history / circuit files with **no cross-process
+lock**. Reads and control via MCP are always safe. For **live writes** via MCP
+(`xbot_reply`, `xbot_dm`, `xbot_like`, `xbot_retweet`, `xbot_follow`,
+`xbot_cycle` with `dry_run=False`):
+
+1. Check the loop first: `./botctl status`
+2. If it is alive, pause or stop it before the live write:
+   `./botctl pause "manual MCP session"` (or `./botctl stop`)
+3. Do the live write.
+4. Resume: `./botctl resume` (or `./botctl start`).
+
+Skipping this risks double-counted caps or two processes posting at once, which
+is exactly the ban-risk the circuit guards against.
+
+## Step 1: Orient before acting
+
+Always read state before any write. From inside this chat, prefer the MCP:
+
+- `xbot_status`: account health, remaining caps, pacing window (read-only)
+- `xbot_control`: circuit state + per-action caps + pending + growth in one call
+- `xbot_plan`: one-shot operator context (status + persona + candidates)
+
+From a shell:
+
+```bash
+cd ~/Documents/x-growth-bot
+./botctl status      # is the loop alive? pid + next-cycle heartbeat
+./botctl board       # one-shot operator board
+```
+
+If the MCP tools are not visible in this session, see "Tools missing?" below.
+
+## Step 2: Pick the surface for the request
+
+**Reads / dashboards (always safe, no loop interaction):**
+
+| Want | MCP tool | CLI fallback |
+| --- | --- | --- |
+| Account health + caps | `xbot_status` | `xbot.cli status` |
+| Operator board | `xbot_control` | `xbot.cli control` |
+| Growth dashboard | `xbot_report` | `xbot.cli report` |
+| Follower delta | `xbot_followers` | `xbot.cli followers` |
+| Follow-back attribution | `xbot_attribution` | `xbot.cli attribution` |
+| Engage candidates | `xbot_candidates` | `xbot.cli discover` |
+| Brain judgement of candidates | `xbot_think` | `xbot.cli think` |
+| Why it skipped | `xbot_log` | `xbot.cli log` |
+| Parked replies | `xbot_pending` | `xbot.cli pending` |
+| Inbound DMs | `xbot_inbox` | n/a |
+
+**Control (safe, no posting):**
+
+- Pause: `xbot_pause("reason", hours=6)` or `./botctl pause "reason"`
+- Resume: `xbot_resume()` or `./botctl resume`
+- Read/set a knob: `xbot_config("actions.reply.daily_cap")` (omit value to read)
+
+**Loop lifecycle (shell only):**
+
+```bash
+./botctl start          # LIVE engagement loop, detached, pid-managed
+./botctl start --dry    # DRY-RUN loop (no live actions) to watch it think
+./botctl stop
+./botctl restart
+```
+
+**Live writes (apply the hard rule above first):**
+
+- Post a reply: `xbot_reply(...)`: runs every guard (trust gate, caps, circuit)
+- Send a DM: `xbot_dm(...)`: answer inbound by passing the inbound id
+- Like / retweet / follow: `xbot_like`, `xbot_retweet`, `xbot_follow`
+  (each defaults to `dry_run=True`; pass `dry_run=False` to act)
+- One full cycle: `xbot_cycle(dry_run=True)` first, then `dry_run=False`
+
+## Step 3: Draft, gate, then post
+
+Never post raw. The bot has a trust gate; use it.
+
+1. Draft the reply text yourself (read `xbot_persona` for the voice + rules).
+2. Second-opinion it: `xbot_trust_check(tweet_text, draft)` runs the
+   adversarial skeptic panel.
+3. Only on a pass, call `xbot_reply(...)` (after the loop-safety rule).
+
+For DMs, `xbot_dm_plan` gives the one-shot context (caps + circuit + inbox)
+before you draft.
+
+## Step 4: Verify the action landed
+
+After a write, confirm with a read:
+
+- `xbot_status`: caps decremented as expected
+- `xbot_log`: the action appears in the audit log
+- `./botctl status`: loop heartbeat unchanged if you paused/resumed cleanly
+
+## First live run
+
+Before the first `--live` run, run the offline go/no-go check:
+
+```bash
+cd ~/Documents/x-growth-bot
+.venv/bin/python -m xbot.cli preflight
+```
+
+## Tools missing?
+
+Newly-added MCP tools need a **Claude Code session restart** to appear.
+`claude mcp get xbot` showing `✓ Connected` only means the server handshakes,
+not that this session has the tools. If `xbot_*` tools are not callable, fall
+back to `./botctl` / `xbot.cli` in Bash for this session and restart for the
+MCP next time.
+
+## What this skill does NOT do
+
+- Does not write tweet/reply/DM copy for you. You draft; the bot gates and posts.
+- Does not edit the bot's source (`src/xbot/`). Use a coding profile for that.
+- Does not bypass caps, the circuit, or the trust gate. If an action is blocked,
+  surface the reason; do not work around the guard.
+- Does not manage X login / cookies. Auth recovery is a separate concern.
+
+## Examples
+
+<example>
+User: is the bot running and how are we doing today?
+Action: Call `xbot_control` (or `./botctl board`) for circuit + caps + growth in
+one shot, then `xbot_status` if more cap detail is needed. Report loop liveness,
+remaining caps, and follower delta. No writes.
+</example>
+
+<example>
+User: pause the bot, I think it's being too aggressive
+Action: `xbot_pause("operator: too aggressive", hours=6)` (or
+`./botctl pause "too aggressive"`). Confirm with `xbot_control` that the circuit
+is open. Tell the user how to resume.
+</example>
+
+<example>
+User: draft a reply to this tweet and post it
+Action: Read `xbot_persona`. Draft the reply. Run `xbot_trust_check(tweet, draft)`.
+If it passes: run `./botctl status`; if the loop is live, `./botctl pause` first,
+then `xbot_reply(...)`, then `./botctl resume`. Verify with `xbot_log`.
+</example>
+
+<example>
+User: run a dry cycle so I can see what it would do
+Action: `xbot_cycle(dry_run=True)` (no loop interaction needed for a dry run).
+Summarize the candidates it judged and the actions it would have taken.
+</example>
+
+<example>
+User: show me the replies waiting for my approval
+Action: `xbot_pending` (or `xbot.cli pending`). List each parked reply with its
+target so the user can approve. Read-only.
+</example>

package/src/commands/_index.ts

@@ -382,10 +382,18 @@ export const COMMANDS = {
     summary: "Boot the local read-only dashboard server (JSON endpoints; React UI in next turn)",
     load: () => import("./dashboard"),
   },
+  dash: {
+    summary: "Query + drive the running dashboard's API (status/profiles/profile/add-mcp/kill/...)",
+    load: () => import("./dash"),
+  },
   mcp: {
     summary: "Expose cue data over MCP (stdio JSON-RPC) so Claude can query it as tool calls",
     load: () => import("./mcp"),
   },
+  mem: {
+    summary: "Inspect/manage per-profile claude-mem stores (status / path / ports / seed)",
+    load: () => import("./mem"),
+  },
 } as const satisfies Record<string, Command>;
 
 export type CommandName = keyof typeof COMMANDS;

package/src/commands/ai-score.e2e.test.ts

@@ -8,6 +8,11 @@ import { join } from "node:path";
 
 const CUE_BIN = join(import.meta.dir, "../index.ts");
 
+// Skip when a child `bun` can't be spawned (some sandboxes / odd PATH setups);
+// these tests shell out to `bun run` and would otherwise hard-fail the suite
+// with "Executable not found in $PATH: bun". CI installs bun via setup-bun.
+const BUN_SPAWNABLE = spawnSync("bun", ["--version"], { encoding: "utf8" }).status === 0;
+
 function cue(args: string[]): { status: number; stdout: string; stderr: string } {
   const res = spawnSync("bun", ["run", CUE_BIN, ...args], {
     encoding: "utf8",
@@ -16,11 +21,13 @@ function cue(args: string[]): { status: number; stdout: string; stderr: string }
   return { status: res.status ?? 1, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
 }
 
-describe("cue ai", () => {
-  test("matches python-api for python/fastapi description", () => {
+describe.skipIf(!BUN_SPAWNABLE)("cue ai", () => {
+  test("matches python for python/fastapi description", () => {
     const res = cue(["ai", "python fastapi sqlalchemy"]);
     expect(res.status).toBe(0);
-    expect(res.stdout).toContain("python-api");
+    expect(res.stdout).toContain("python");
+    // Guard against the phantom name returning (it's a substring of "python")
+    expect(res.stdout).not.toContain("python-api");
   });
 
   test("matches rust for rust/cargo description", () => {
@@ -66,7 +73,7 @@ describe("cue ai", () => {
   });
 });
 
-describe("cue score", () => {
+describe.skipIf(!BUN_SPAWNABLE)("cue score", () => {
   test("scores a specific profile", () => {
     const res = cue(["score", "--profile", "core"]);
     expect(res.status).toBe(0);

package/src/commands/ai.ts

@@ -10,12 +10,11 @@
  *   cue ai "rust cli tool"
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 
-import { listProfiles } from "../lib/profile-loader";
 
 const REPO_ROOT = process.env.CUE_REPO_ROOT ?? process.env.SOUL_REPO_ROOT ?? resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const PROFILES_DIR = join(REPO_ROOT, "profiles");
@@ -28,11 +27,11 @@ interface MatchedProfile {
 }
 
 // Keywords → profile mapping
-const PROFILE_KEYWORDS: Record<string, string[]> = {
+export const PROFILE_KEYWORDS: Record<string, string[]> = {
   "nextjs": ["next", "nextjs", "next.js", "vercel", "app router", "server components", "react ssr"],
   "frontend": ["react", "vue", "svelte", "frontend", "ui", "tailwind", "vite", "css", "component"],
   "backend": ["api", "express", "fastify", "hono", "webhook", "rest", "graphql", "node server", "prisma", "drizzle"],
-  "python-api": ["python", "fastapi", "django", "flask", "sqlalchemy", "alembic", "uvicorn", "pytest", "pip"],
+  "python": ["python", "fastapi", "django", "flask", "sqlalchemy", "alembic", "uvicorn", "pytest", "pip"],
   "rust": ["rust", "cargo", "tokio", "async rust", "cli tool", "systems", "wasm"],
   "go-api": ["go", "golang", "gin", "echo", "chi", "gorm", "goroutine"],
   "medusa-dev": ["medusa", "ecommerce", "storefront", "shop", "cart", "checkout"],

package/src/commands/auto-detect.ts

@@ -4,7 +4,7 @@
 
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { detectProfile, detectProfileV2 } from "../lib/auto-detect";
+import { detectProfile, } from "../lib/auto-detect";
 import { scanProject } from "../lib/project-scanner";
 
 export async function run(args: string[]): Promise<number> {

package/src/commands/cli.test.ts

@@ -180,8 +180,7 @@ describe("cue cli (top-level)", () => {
 
   test("unknown subcommand exits 1", async () => {
     const orig = process.stderr.write.bind(process.stderr);
-    let err = "";
-    (process.stderr as any).write = (c: string | Uint8Array) => { err += String(c); return true; };
+    (process.stderr as any).write = () => true;
     try {
       const exit = await cliRun(["nonsense"]);
       expect(exit).toBe(1);

package/src/commands/cli.ts

@@ -15,7 +15,7 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir, platform } from "node:os";

package/src/commands/cloud.ts

@@ -156,7 +156,7 @@ async function cmdPush(args: string[]): Promise<number> {
     }
 
     process.stderr.write(`⚠️  Push failed (${res.status}): ${await res.text()}\n`);
-  } catch (err) {
+  } catch {
     process.stderr.write(`⚠️  Cloud API not reachable. Profile saved locally only.\n`);
     process.stderr.write(`   Will sync when API is live. Run \`cue push ${profileName}\` again later.\n`);
   }

package/src/commands/current.ts

@@ -14,10 +14,7 @@ import { join } from "node:path";
 
 import { resolveProfileForCwd } from "../lib/cwd-resolver";
 import { loadProfile } from "../lib/profile-loader";
-
-function configDir(): string {
-  return process.env.XDG_CONFIG_HOME ? join(process.env.XDG_CONFIG_HOME, "cue") : join(homedir(), ".config", "cue");
-}
+import { configDir } from "../lib/config-paths";
 
 interface InspectResult {
   profile: string;

package/src/commands/dash.test.ts

@@ -0,0 +1,110 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createServer, type Server } from "node:http";
+
+import { parseDashArgs, dashUrl, dashFetch, ROUTES } from "./dash";
+
+describe("parseDashArgs", () => {
+  const savedPort = process.env.CUE_DASH_PORT;
+  const savedHost = process.env.CUE_DASH_HOST;
+  beforeAll(() => { delete process.env.CUE_DASH_PORT; delete process.env.CUE_DASH_HOST; });
+  afterAll(() => {
+    if (savedPort === undefined) delete process.env.CUE_DASH_PORT; else process.env.CUE_DASH_PORT = savedPort;
+    if (savedHost === undefined) delete process.env.CUE_DASH_HOST; else process.env.CUE_DASH_HOST = savedHost;
+  });
+
+  test("defaults are 127.0.0.1:7891", () => {
+    const a = parseDashArgs(["status"]);
+    expect(a).toMatchObject({ sub: "status", host: "127.0.0.1", port: 7891, json: false });
+  });
+
+  test("first non-flag is the subcommand; the rest are positionals", () => {
+    const a = parseDashArgs(["profile", "browser", "extra"]);
+    expect(a.sub).toBe("profile");
+    expect(a.rest).toEqual(["browser", "extra"]);
+  });
+
+  test("flags parse and don't leak into positionals", () => {
+    const a = parseDashArgs(["kill", "123", "--port", "9000", "--host", "0.0.0.0", "--json", "--sigkill"]);
+    expect(a).toMatchObject({ sub: "kill", rest: ["123"], port: 9000, host: "0.0.0.0", json: true, sigkill: true });
+  });
+
+  test("--as captures the merge target name", () => {
+    expect(parseDashArgs(["merge-save", "a", "b", "--as", "ab"]).as).toBe("ab");
+  });
+
+  test("env overrides the default host/port", () => {
+    process.env.CUE_DASH_PORT = "5555";
+    process.env.CUE_DASH_HOST = "example.test";
+    const a = parseDashArgs(["status"]);
+    expect(a.port).toBe(5555);
+    expect(a.host).toBe("example.test");
+    delete process.env.CUE_DASH_PORT; delete process.env.CUE_DASH_HOST;
+  });
+
+  test("invalid port is ignored", () => {
+    expect(parseDashArgs(["status", "--port", "garbage"]).port).toBe(7891);
+    expect(parseDashArgs(["status", "--port", "99999"]).port).toBe(7891);
+  });
+});
+
+describe("dashUrl", () => {
+  test("builds the /api/v1 path with no query", () => {
+    expect(dashUrl("127.0.0.1", 7891, "/status")).toBe("http://127.0.0.1:7891/api/v1/status");
+  });
+  test("appends a query string", () => {
+    expect(dashUrl("h", 1, "/profile-detail", { profile: "a b" })).toBe("http://h:1/api/v1/profile-detail?profile=a+b");
+  });
+});
+
+describe("ROUTES.build", () => {
+  const base = parseDashArgs([]);
+  test("profile → GET profile-detail with the name query", () => {
+    const r = ROUTES.profile!.build({ ...base, rest: ["browser"] });
+    expect(r).toEqual({ path: "/profile-detail", query: { profile: "browser" } });
+  });
+  test("add-mcp → POST mcps/add with {profile,id}", () => {
+    const r = ROUTES["add-mcp"]!.build({ ...base, rest: ["frontend", "playwright"] });
+    expect(r).toEqual({ path: "/mcps/add", method: "POST", body: { profile: "frontend", id: "playwright" } });
+  });
+  test("kill → POST sessions/kill, SIGKILL only when --sigkill", () => {
+    expect(ROUTES.kill!.build({ ...base, rest: ["42"] }).body).toEqual({ pid: 42, signal: "SIGTERM" });
+    expect(ROUTES.kill!.build({ ...base, rest: ["42"], sigkill: true }).body).toEqual({ pid: 42, signal: "SIGKILL" });
+  });
+  test("merge-save carries names + --as target", () => {
+    expect(ROUTES["merge-save"]!.build({ ...base, rest: ["a", "b"], as: "ab" }).body).toEqual({ names: ["a", "b"], name: "ab" });
+  });
+  test("mutating routes are flagged", () => {
+    expect(ROUTES["add-mcp"]!.mutating).toBe(true);
+    expect(ROUTES.status!.mutating).toBeUndefined();
+  });
+});
+
+describe("dashFetch (stub server)", () => {
+  let server: Server;
+  let port = 0;
+  beforeAll(async () => {
+    server = createServer((req, res) => {
+      const url = req.url ?? "";
+      res.setHeader("content-type", "application/json");
+      if (url.startsWith("/api/v1/ok")) { res.end(JSON.stringify({ ok: true, data: { hello: "world" } })); return; }
+      if (url.startsWith("/api/v1/bad")) { res.statusCode = 400; res.end(JSON.stringify({ ok: false, error: "missing-profile" })); return; }
+      res.end("not json");
+    });
+    await new Promise<void>((r) => server.listen(0, "127.0.0.1", () => r()));
+    port = (server.address() as { port: number }).port;
+  });
+  afterAll(() => { server.close(); });
+
+  test("unwraps the {ok,data} envelope", async () => {
+    expect(await dashFetch({ host: "127.0.0.1", port }, "/ok")).toEqual({ hello: "world" });
+  });
+  test("throws the server's error message on {ok:false}", async () => {
+    await expect(dashFetch({ host: "127.0.0.1", port }, "/bad")).rejects.toThrow("missing-profile");
+  });
+  test("throws a clear message on non-JSON", async () => {
+    await expect(dashFetch({ host: "127.0.0.1", port }, "/other")).rejects.toThrow(/non-JSON/);
+  });
+  test("refused connection points at `cue dashboard`", async () => {
+    await expect(dashFetch({ host: "127.0.0.1", port: 1 }, "/ok")).rejects.toThrow(/cue dashboard/);
+  });
+});