@test-lab-ai/cli 0.2.13 → 0.2.15

package/AGENTS.md

@@ -4,7 +4,7 @@ This guide is for an AI coding agent (Claude Code, Codex, Cursor, etc.) asked to
 move a user's existing tests into test-lab.ai. You do the format translation; the
 `testlab` CLI handles auth and upload.
 
-**Quickest reference: run `testlab examples`** — it prints the exact JSON shape
+**Quickest reference: run `testlab examples`** - it prints the exact JSON shape
 for every resource (credentials, labels, data fixtures, plans, pre-steps).
 
 ## Install (zero-dependency)
@@ -121,7 +121,7 @@ in prompts. A fixture is `{ key, label?, fields: [...] }`; each field is either
 ```
 
 Generators include `internet.email`, `person.firstName`, `person.fullName`,
-`string.uuid`, `number.int`, `company.name`, … — run `testlab examples` for the
+`string.uuid`, `number.int`, `company.name`, ... - run `testlab examples` for the
 full list. Reference: `{{data.newUser.email}}`. Keys: start with a letter,
 letters/digits/underscores, max 50 chars.
 
@@ -146,4 +146,4 @@ testlab import ./tests
   dashboard afterward if the user needs them.
 - Prefer calling the CLI over hand-rolling HTTP. If you must call the API
   directly, it is documented at https://test-lab.ai/docs/api/test-plans and uses
-  the same `Authorization: Bearer tl_…` key.
+  the same `Authorization: Bearer tl_...` key.

package/README.md

@@ -26,8 +26,8 @@ export TESTLAB_API_KEY=tl_xxxxx
 # or:  testlab login --key tl_xxxxx
 ```
 
-Create a key at **Settings → API Keys**. A key belongs to one account, so it's
-the import target — to import into an organization account, create the key with
+Create a key at **Settings -> API Keys**. A key belongs to one account, so it's
+the import target - to import into an organization account, create the key with
 that org selected.
 
 ## Commands
@@ -52,8 +52,8 @@ reference and is written so an AI agent can read it and build a valid import.
 ## Import format
 
 `testlab import` reads a JSON file (or a directory of `*.json`). A file can be a
-single plan, an array of plans, or a **bundle** with any of these sections —
-created in order: credentials → labels → fixtures → plans:
+single plan, an array of plans, or a **bundle** with any of these sections - 
+created in order: credentials -> labels -> fixtures -> plans:
 
 ```jsonc
 {
@@ -98,9 +98,9 @@ in the file doesn't matter. Re-running is safe for credentials/labels/fixtures
 
 ## Reference syntax (inside a plan prompt)
 
-- `{{credentials.<key>}}` — a stored secret (never shown to the AI model).
-- `{{data.<fixture>.<field>}}` — a value from a data fixture (generated test data).
-- `{{run.shortId}}` — a unique per-run id (for unique emails, names, etc.).
+- `{{credentials.<key>}}` - a stored secret (never shown to the AI model).
+- `{{data.<fixture>.<field>}}` - a value from a data fixture (generated test data).
+- `{{run.shortId}}` - a unique per-run id (for unique emails, names, etc.).
 
 ## Install the test-lab-plan skill (Claude Code, Codex, Cursor)
 
@@ -148,9 +148,9 @@ Import tests you already have:
 ## For AI agents
 
 Run **`testlab examples`** for the complete JSON reference, or read `AGENTS.md`
-(shipped inside this package). The workflow: read the user's existing tests →
+(shipped inside this package). The workflow: read the user's existing tests -> 
 convert each into the plan/fixture JSON above (explicit URL in the prompt,
-secrets as `{{credentials.<key>}}`, generated data as `{{data.<fixture>.<field>}}`) →
+secrets as `{{credentials.<key>}}`, generated data as `{{data.<fixture>.<field>}}`) -> 
 `testlab import`.
 
 ## Under the hood

package/bin/testlab.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 /**
- * testlab — import existing test plans into test-lab.ai (driveable by a human,
+ * testlab - import existing test plans into test-lab.ai (driveable by a human,
  * a CI job, or an AI agent).
  *
  * Commands:
- *   testlab login [--key tl_…]              Authenticate (browser flow, or paste/flag a key)
+ *   testlab login [--key tl_...]              Authenticate (browser flow, or paste/flag a key)
  *   testlab whoami                          Show the authenticated account
  *   testlab plans list                      List the account's test plans
  *   testlab plans create -f plan.json       Create one plan from a JSON file
@@ -12,8 +12,8 @@
  *   testlab credentials set <key> --value <value>    Upsert an account credential ({{credentials.<key>}})
  *   testlab import <path> [--dry-run]        Import a plan file or a directory of *.json
  *
- * Auth:  --key  → $TESTLAB_API_KEY → ~/.test-lab/config.json
- * API:   --api-url → $TESTLAB_API_URL → https://www.test-lab.ai
+ * Auth:  --key -> $TESTLAB_API_KEY -> ~/.test-lab/config.json
+ * API:   https://www.test-lab.ai (fixed)
  */
 import { parseArgs } from "node:util"
 import fs from "node:fs"
@@ -32,10 +32,10 @@ function errExit(msg) {
   process.exit(1)
 }
 
-const HELP = `testlab — import test plans (and their data) into test-lab.ai
+const HELP = `testlab - import test plans (and their data) into test-lab.ai
 
 Usage:
-  testlab login [--key tl_…]               Authenticate (browser, or paste/flag a key)
+  testlab login [--key tl_...]               Authenticate (browser, or paste/flag a key)
   testlab whoami                           Show the authenticated account
   testlab import <path> [--dry-run]         Import a file or directory of *.json
                                             (credentials, labels, fixtures, plans)
@@ -49,6 +49,8 @@ Usage:
   testlab data create -f fixture.json      Create a data fixture ({{data.<fixture>.<field>}})
   testlab scripts upload <file> --plan <id>  Upload a local Playwright script for a plan
                                            (skips paid AI generation; --device optional)
+  testlab scripts get <id> [--out <file>]  Download a plan's active script to fix + re-upload
+                                           (prints to stdout, or writes --out <file>; --device optional)
   testlab examples                         Print the full JSON reference for every
                                            resource (designed for AI agents)
   testlab skills install [--agent ...]     Install the test-lab skills (test-lab-plan +
@@ -57,21 +59,20 @@ Usage:
   testlab skills update                    Refresh installed skills (also auto-runs after a CLI upgrade)
 
 Options:
-  --key <tl_…>      API key (else $TESTLAB_API_KEY or ~/.test-lab/config.json)
+  --key <tl_...>      API key (else $TESTLAB_API_KEY or ~/.test-lab/config.json)
   --stdin           Read the value (key/credential) from stdin
   --force           (login) re-authenticate even if a stored key still works
   --dry-run         (import) validate + print plan order without writing
   --project <id|name>  (import/plans) assign plans to a project, or "none" for account-level
   --version, -v     Print the installed CLI version
 
-Get a key at https://test-lab.ai/admin/settings/api-keys · run \`testlab examples\` for JSON shapes`
+Get a key at https://test-lab.ai/admin/settings/api-keys / run \`testlab examples\` for JSON shapes`
 
 function parse() {
   return parseArgs({
     allowPositionals: true,
     options: {
       key: { type: "string" },
-      "api-url": { type: "string" },
       value: { type: "string" },
       file: { type: "string", short: "f" },
       name: { type: "string" },
@@ -84,6 +85,7 @@ function parse() {
       project: { type: "string" },
       plan: { type: "string" },
       device: { type: "string" },
+      out: { type: "string", short: "o" },
       version: { type: "boolean", short: "v" },
       help: { type: "boolean", short: "h" },
     },
@@ -151,7 +153,6 @@ async function cmdLogin(flags) {
 
   const cfg = loadConfig()
   cfg.apiKey = apiKey
-  cfg.apiUrl = apiUrl
   const path = saveConfig(cfg)
   log(`✓ Authenticated${who?.email ? ` as ${who.email}` : ""}. Credentials saved to ${path}`)
 }
@@ -159,7 +160,7 @@ async function cmdLogin(flags) {
 async function cmdWhoami(flags) {
   const { apiKey, apiUrl } = requireAuth(flags)
   // The two requests are independent (apiFetch never throws), so fire
-  // them together — whoami is interactive and the serial form doubled
+  // them together - whoami is interactive and the serial form doubled
   // its wall-clock. Identity endpoint shipped after the CLI's first
   // release: older servers 404 on /me and we just skip those lines.
   const [r, me] = await Promise.all([
@@ -284,7 +285,7 @@ async function resolveProjectId(apiUrl, apiKey, flags) {
   }
   if (!process.stdin.isTTY) {
     errExit(
-      `You have ${projects.length} projects — pick one with --project <id|name> (or --project none):\n` +
+      `You have ${projects.length} projects - pick one with --project <id|name> (or --project none):\n` +
         projects.map((p) => `  ${p.id}  ${p.name}`).join("\n")
     )
   }
@@ -341,7 +342,7 @@ async function cmdDataList(flags) {
   }
   for (const fx of fixtures) {
     const fields = (fx.fields || []).map((f) => f.key).join(", ")
-    log(`  ${fx.key}${fx.label ? `  (${fx.label})` : ""}${fields ? `  — ${fields}` : ""}`)
+    log(`  ${fx.key}${fx.label ? `  (${fx.label})` : ""}${fields ? ` - ${fields}` : ""}`)
   }
   log(`\n${fixtures.length} fixture(s)`)
 }
@@ -370,10 +371,19 @@ async function cmdDataCreate(flags) {
 // paid AI generation. The server validates it (allow-list + intent review),
 // wraps it in the trusted harness, and stores it as the plan's saved script.
 // On rejection the per-line issues are printed so an agent can self-correct.
+// Strict positive-integer plan id from a CLI arg/flag. parseInt is too lenient
+// ("12abc" -> 12, "12.9" -> 12), which would silently fetch/replace the WRONG
+// plan; require all-digits and > 0 so a typo errors instead.
+function parsePlanIdArg(raw) {
+  if (typeof raw !== "string" || !/^\d+$/.test(raw.trim())) return NaN
+  const n = parseInt(raw.trim(), 10)
+  return n > 0 ? n : NaN
+}
+
 async function cmdScriptsUpload(flags, args) {
   const file = args[2]
   if (!file) errExit("usage: testlab scripts upload <file.spec.ts> --plan <planId> [--device <device>]")
-  const planId = flags.plan ? parseInt(flags.plan, 10) : NaN
+  const planId = parsePlanIdArg(flags.plan)
   if (!Number.isInteger(planId)) errExit("--plan <planId> is required (the numeric test-plan id; see `testlab plans list`)")
   const { apiKey, apiUrl } = requireAuth(flags)
 
@@ -388,7 +398,9 @@ async function cmdScriptsUpload(flags, args) {
   // plan's first configured device. Hardcoding "Desktop Chrome" here would 400
   // on any plan whose device isn't Desktop Chrome (the server validates it).
   const device = flags.device
-  const r = await apiFetch(apiUrl, apiKey, "POST", "/api/v1/scripts/upload", { script, planId, device })
+  // Idempotent on the server (saved_scripts upsert ON CONFLICT), so a transient
+  // 5xx is safe to retry - a successful retry overwrites, it never duplicates.
+  const r = await apiFetch(apiUrl, apiKey, "POST", "/api/v1/scripts/upload", { script, planId, device }, { retries: 3 })
 
   // 422 = the script was understood but rejected (allow-list or intent review).
   // Print the structured issues so a human or agent can fix and retry.
@@ -404,16 +416,67 @@ async function cmdScriptsUpload(flags, args) {
     log(`✗ Script rejected by security review: ${r.json.reason}`)
     process.exit(1)
   }
-  if (!r.ok) errExit(`${r.status}: ${r.json?.error || "upload failed"}`)
+  if (!r.ok) {
+    // A 5xx (or network error) survived the retries - almost always a transient
+    // server blip, not a rejected script. Tell the user it's safe to re-run:
+    // the upload is idempotent, so a retry can't create a duplicate. (A genuinely
+    // bad script comes back as 422 and is handled above, never here.)
+    if (r.status === 0 || r.status >= 500) {
+      errExit(
+        `${r.status || "network"}: ${r.json?.error || "upload failed"}\n` +
+          `  This is usually a transient server error, not a rejected script. ` +
+          `Re-run the same command - the upload is idempotent, so it won't create a duplicate.`,
+      )
+    }
+    errExit(`${r.status}: ${r.json?.error || "upload failed"}`)
+  }
 
   const steps = r.json?.stepCount
   // Show the device the SERVER resolved (it defaults an omitted device to the
   // plan's first), not the CLI-local flag which is undefined when --device is omitted.
   const resolvedDevice = r.json?.device || device || "the plan's default device"
-  log(`✓ Uploaded ${file} → plan #${planId} (${steps != null ? `${steps} step${steps === 1 ? "" : "s"}, ` : ""}${resolvedDevice})`)
+  log(`✓ Uploaded ${file} -> plan #${planId} (${steps != null ? `${steps} step${steps === 1 ? "" : "s"}, ` : ""}${resolvedDevice})`)
   log(`  This plan now runs your script instead of AI generation.`)
 }
 
+async function cmdScriptsGet(flags, args) {
+  const planId = parsePlanIdArg(args[2] ?? flags.plan)
+  if (!Number.isInteger(planId)) {
+    errExit("usage: testlab scripts get <planId> [--device <device>] [--out <file>]")
+  }
+  const { apiKey, apiUrl } = requireAuth(flags)
+
+  const qs = new URLSearchParams({ planId: String(planId) })
+  if (flags.device) qs.set("device", String(flags.device))
+  const r = await apiFetch(apiUrl, apiKey, "GET", `/api/v1/scripts?${qs.toString()}`)
+
+  // 404 carries a human message (no script / wrong device); surface it verbatim.
+  if (!r.ok) errExit(`${r.status}: ${r.json?.error || "failed to fetch script"}`)
+  const script = r.json?.script
+  if (typeof script !== "string") errExit("server returned no script")
+
+  const device = r.json?.device || flags.device || "the plan's default device"
+  const steps = r.json?.stepCount
+  const source = r.json?.source
+  const meta = `${steps != null ? `${steps} step${steps === 1 ? "" : "s"}, ` : ""}${device}${source ? `, ${source}` : ""}`
+  const withNl = script.endsWith("\n") ? script : script + "\n"
+
+  if (flags.out) {
+    try {
+      fs.writeFileSync(flags.out, withNl, "utf8")
+    } catch (e) {
+      errExit(`could not write ${flags.out}: ${e.message}`)
+    }
+    log(`✓ Saved plan #${planId} script -> ${flags.out} (${meta})`)
+    log(`  Edit it, then re-upload: testlab scripts upload ${flags.out} --plan ${planId}${flags.device ? ` --device "${flags.device}"` : ""}`)
+  } else {
+    // Status line to stderr so a plain `> file` redirect captures only the
+    // script (pipeable), while the human still sees what they fetched.
+    process.stderr.write(`# plan #${planId} script (${meta})\n`)
+    process.stdout.write(withNl)
+  }
+}
+
 function cmdExamples() {
   log(EXAMPLES_TEXT)
 }
@@ -445,7 +508,7 @@ async function cmdSkillsInstall(flags, args) {
       try {
         const res = await installSkill(name, agent, { global: flags.global })
         installed++
-        log(`✓ ${res.name} → ${agent}: ${res.dest}`)
+        log(`✓ ${res.name} -> ${agent}: ${res.dest}`)
       } catch (e) {
         // When installing for several agents, one failing (e.g. cursor + --global) must not abort the rest.
         if (targets.length > 1) log(`  skipped ${agent}: ${e.message}`)
@@ -463,7 +526,7 @@ function cmdSkillsList() {
 }
 
 // Install EVERY current skill at every location where any test-lab skill is
-// already present — refreshing existing copies AND adding skills shipped since
+// already present - refreshing existing copies AND adding skills shipped since
 // the user last installed, so an update delivers the latest skill SET (not just
 // fresher copies of the old set). `installedSkillTargets()` is the union of
 // (agent, scope) homes; a brand-new skill has no install locations of its own
@@ -498,7 +561,7 @@ async function cmdSkillsUpdate() {
   for (const r of results) {
     const where = `${r.agent}${r.global ? " (global)" : ""}`
     if (!r.ok) log(`  ✗ ${r.name} (${where}): ${r.error}`)
-    else log(`${r.isNew ? "+ installed" : "✓ refreshed"} ${r.name} → ${where}: ${r.dest}`)
+    else log(`${r.isNew ? "+ installed" : "✓ refreshed"} ${r.name} -> ${where}: ${r.dest}`)
   }
   const ok = results.filter((r) => r.ok)
   const added = ok.filter((r) => r.isNew).length
@@ -509,7 +572,7 @@ async function cmdSkillsUpdate() {
 }
 
 // After a CLI upgrade, refresh installed skills in place AND add any newly
-// shipped ones — runs once per version bump (best effort). Skipped in CI / when
+// shipped ones - runs once per version bump (best effort). Skipped in CI / when
 // NO_UPDATE_NOTIFIER is set.
 async function maybeRefreshSkillsOnUpgrade() {
   if (process.env.CI || process.env.NO_UPDATE_NOTIFIER) return
@@ -520,7 +583,7 @@ async function maybeRefreshSkillsOnUpgrade() {
   try {
     ok = (await refreshInstalledSkills()).filter((r) => r.ok)
   } catch {
-    return // best effort — never break the actual command
+    return // best effort - never break the actual command
   }
   if (ok.length === 0) return
   const added = ok.filter((r) => r.isNew).length
@@ -528,7 +591,7 @@ async function maybeRefreshSkillsOnUpgrade() {
   const bits = []
   if (refreshed) bits.push(`refreshed ${refreshed}`)
   if (added) bits.push(`installed ${added} new`)
-  process.stderr.write(`↻ CLI upgraded ${prev} → ${ver}; ${bits.join(", ")} skill location(s).\n`)
+  process.stderr.write(`↻ CLI upgraded ${prev} -> ${ver}; ${bits.join(", ")} skill location(s).\n`)
 }
 
 async function main() {
@@ -580,7 +643,8 @@ async function main() {
       return errExit("usage: testlab data <list|create>")
     case "scripts":
       if (args[1] === "upload") return cmdScriptsUpload(flags, args)
-      return errExit("usage: testlab scripts upload <file.spec.ts> --plan <planId> [--device <device>]")
+      if (args[1] === "get") return cmdScriptsGet(flags, args)
+      return errExit("usage: testlab scripts <upload <file> --plan <id> | get <id> [--out <file>]>")
     case "examples":
       return cmdExamples()
     case "skills":

package/lib/api.mjs

@@ -1,31 +1,72 @@
 /**
  * Tiny fetch wrapper for the test-lab public API. Uses global fetch (Node 18+).
- * Returns { ok, status, json } — json is the parsed body (or { raw } on non-JSON).
+ * Returns { ok, status, json } - json is the parsed body (or { raw } on non-JSON).
+ *
+ * Transient resilience: a 5xx or a network error is retried with linear backoff.
+ * Retries are SAFE only for idempotent calls, so they default ON for GET and OFF
+ * for writes - a write opts in explicitly via `opts.retries` (used by the
+ * idempotent script upload, which the server upserts ON CONFLICT). This is what
+ * stops a momentary empty-body 500 (a Worker hiccup or an edge rate-limit that
+ * short-circuits before the app's JSON error handler) from surfacing as a hard
+ * "500: upload failed" when a one-second retry would have gone through.
  */
-export async function apiFetch(apiUrl, apiKey, method, pathname, body) {
+export async function apiFetch(apiUrl, apiKey, method, pathname, body, opts = {}) {
+  const retries = Number.isInteger(opts.retries) ? opts.retries : method === "GET" ? 2 : 0
+  const backoffMs = Number.isInteger(opts.backoffMs) ? opts.backoffMs : 800
+
   const headers = {}
   if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`
   if (body !== undefined) headers["Content-Type"] = "application/json"
 
-  let res
-  try {
-    res = await fetch(`${apiUrl}${pathname}`, {
-      method,
-      headers,
-      body: body !== undefined ? JSON.stringify(body) : undefined,
-    })
-  } catch (e) {
-    return { ok: false, status: 0, json: { error: `network error: ${e.message}` } }
-  }
-
-  const text = await res.text()
-  let json = null
-  if (text) {
+  for (let attempt = 0; ; attempt++) {
+    let res
     try {
-      json = JSON.parse(text)
-    } catch {
-      json = { raw: text }
+      res = await fetch(`${apiUrl}${pathname}`, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      })
+    } catch (e) {
+      if (attempt < retries) {
+        await sleep(backoffMs * (attempt + 1))
+        continue
+      }
+      return { ok: false, status: 0, json: { error: `network error: ${e.message}` } }
+    }
+
+    // 5xx = transient (Worker error / edge rate-limit). Retry while budget remains.
+    if (res.status >= 500 && attempt < retries) {
+      await sleep(backoffMs * (attempt + 1))
+      continue
+    }
+
+    const text = await res.text()
+    let json = null
+    if (text) {
+      try {
+        json = JSON.parse(text)
+      } catch {
+        json = { raw: text }
+      }
+    }
+
+    // A failed response with no usable error body (the empty-body 5xx case) would
+    // otherwise reach the caller as `json: null` and print a blank reason.
+    // Synthesize an actionable message keyed off the status instead.
+    if (!res.ok && (!json || (!json.error && !json.issues && !json.reason))) {
+      json = {
+        ...(json || {}),
+        error:
+          res.status >= 500
+            ? `server error (HTTP ${res.status}) with no response body - usually transient`
+            : `request failed (HTTP ${res.status})`,
+      }
     }
+
+    return { ok: res.ok, status: res.status, json }
   }
-  return { ok: res.ok, status: res.status, json }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
 }

package/lib/config.mjs

@@ -1,9 +1,8 @@
 /**
  * Config + auth resolution for the testlab CLI.
  *
- * Resolution order (first hit wins):
- *   API key:  --key flag  →  $TESTLAB_API_KEY  →  ~/.test-lab/config.json
- *   API base: --api-url    →  $TESTLAB_API_URL   →  config  →  https://www.test-lab.ai
+ *   API key:  --key flag -> $TESTLAB_API_KEY -> ~/.test-lab/config.json
+ *   API base: always https://www.test-lab.ai (not configurable)
  */
 import fs from "node:fs"
 import os from "node:os"
@@ -36,8 +35,8 @@ export function saveConfig(cfg) {
 export function resolveAuth(flags) {
   const cfg = loadConfig()
   const apiKey = flags.key || process.env.TESTLAB_API_KEY || cfg.apiKey || null
-  const apiUrl = (
-    flags["api-url"] || process.env.TESTLAB_API_URL || cfg.apiUrl || DEFAULT_API_URL
-  ).replace(/\/+$/, "")
-  return { apiKey, apiUrl }
+  // API base is fixed to production. It used to be overridable via --api-url /
+  // TESTLAB_API_URL / a stored config value; that was removed so an API key is
+  // never sent to an arbitrary host.
+  return { apiKey, apiUrl: DEFAULT_API_URL }
 }

package/lib/examples.mjs

@@ -2,9 +2,9 @@
 // Written for an AI agent: every resource's exact JSON shape, the command that
 // creates it, the reference syntax, and the combined import-bundle format.
 
-export const EXAMPLES_TEXT = `testlab — resource reference (for humans and AI agents)
+export const EXAMPLES_TEXT = `testlab - resource reference (for humans and AI agents)
 
-All resources are scoped to the API key's account. Auth: a tl_… key via
+All resources are scoped to the API key's account. Auth: a tl_... key via
 \`testlab login\`, the TESTLAB_API_KEY env var, or --key.
 
 ═══════════════════════════════════════════════════════════════════════════
@@ -12,10 +12,10 @@ REFERENCE SYNTAX (use these inside a plan prompt, and in cookie/header values)
 ═══════════════════════════════════════════════════════════════════════════
   {{credentials.<key>}}        a stored secret (never shown to the AI/model)
   {{data.<fixture>.<field>}}     a value from a data fixture (generated test data)
-  {{run.shortId}}            a unique per-run id (for unique emails, names, …)
+  {{run.shortId}}            a unique per-run id (for unique emails, names, ...)
 
 ═══════════════════════════════════════════════════════════════════════════
-1) CREDENTIAL  — a secret behind {{credentials.<key>}}
+1) CREDENTIAL - a secret behind {{credentials.<key>}}
 ═══════════════════════════════════════════════════════════════════════════
 Command:  testlab credentials set email --value qa@example.com
 JSON (inside an import bundle, under "credentials"):
@@ -24,14 +24,14 @@ Rules: key starts with a letter; letters/digits/underscores; <=50 chars.
        value <= 1000 chars; stored encrypted, never returned.
 
 ═══════════════════════════════════════════════════════════════════════════
-2) LABEL  — a tag for grouping plans (auto-created when a plan references it)
+2) LABEL - a tag for grouping plans (auto-created when a plan references it)
 ═══════════════════════════════════════════════════════════════════════════
 JSON (under "labels"):  "smoke"          (just the name)
 Plans can also list labels by name and they're created on the fly:
   "labels": ["smoke", "auth"]
 
 ═══════════════════════════════════════════════════════════════════════════
-3) DATA FIXTURE  — reusable generated test data behind {{data.<fixture>.<field>}}
+3) DATA FIXTURE - reusable generated test data behind {{data.<fixture>.<field>}}
 ═══════════════════════════════════════════════════════════════════════════
 Command:  testlab data create -f fixture.json
 JSON (under "fixtures"):
@@ -59,7 +59,7 @@ Rules: fixture/field keys start with a letter; letters/digits/underscores;
 Reference it in a prompt as {{data.newUser.email}}.
 
 ═══════════════════════════════════════════════════════════════════════════
-4) TEST PLAN  — a natural-language test (the URL lives IN the prompt)
+4) TEST PLAN - a natural-language test (the URL lives IN the prompt)
 ═══════════════════════════════════════════════════════════════════════════
 Command:  testlab plans create -f plan.json
 JSON (under "plans"):
@@ -84,17 +84,17 @@ Rules: name <=200 chars; prompt <=32KB; <=25 labels; <=25 preSteps.
 Projects: omit projectId to import account-level. Run "testlab projects list" for ids; "testlab import --project <id|name>" (or --project none) sets it for the whole import, and is auto-picked when you have exactly one.
 
 ═══════════════════════════════════════════════════════════════════════════
-IMPORT BUNDLE  — create everything at once:  testlab import ./bundle.json
+IMPORT BUNDLE - create everything at once:  testlab import ./bundle.json
 ═══════════════════════════════════════════════════════════════════════════
 A file (or a directory of *.json) may contain any of these sections. The CLI
-creates them in order: credentials → labels → fixtures → plans, and topo-sorts
+creates them in order: credentials -> labels -> fixtures -> plans, and topo-sorts
 plans so pre-step dependencies (by "ref") are created first.
   {
     "credentials": [ { "key": "password", "value": "hunter2" } ],
     "labels": ["smoke"],
     "fixtures": [ { "key": "newUser", "fields": [ { "key": "email", "mode": "dynamic", "generator": "internet.email" } ] } ],
     "plans": [
-      { "ref": "signup", "name": "Sign up", "prompt": "Go to https://app.example.com/signup, register with {{data.newUser.email}} …" },
+      { "ref": "signup", "name": "Sign up", "prompt": "Go to https://app.example.com/signup, register with {{data.newUser.email}} ..." },
       { "name": "Onboard", "prompt": "Complete onboarding.", "preSteps": [ { "ref": "signup" } ] }
     ]
   }

package/lib/import.mjs

@@ -1,5 +1,5 @@
 /**
- * Import orchestration: load files, then create resources in dependency order —
+ * Import orchestration: load files, then create resources in dependency order - 
  * credentials, labels, data fixtures, then plans (topo-sorted by pre-step deps,
  * wiring intra-batch pre-steps to the ids returned along the way).
  */
@@ -67,7 +67,7 @@ export function loadImportFile(target) {
   return { credentials, labels, fixtures, plans }
 }
 
-/** Resolve a plan's preSteps for the API: intra-batch refs → concrete ids. */
+/** Resolve a plan's preSteps for the API: intra-batch refs -> concrete ids. */
 export function normalizePreSteps(preSteps, refToId) {
   if (!Array.isArray(preSteps) || preSteps.length === 0) return undefined
   return preSteps.map((ps) => {
@@ -112,7 +112,7 @@ export async function runImport({
 
   if (dryRun) {
     log(
-      `Dry run — ${credentials.length} credential(s), ${labels.length} label(s), ${fixtures.length} fixture(s), ${plans.length} plan(s).`
+      `Dry run - ${credentials.length} credential(s), ${labels.length} label(s), ${fixtures.length} fixture(s), ${plans.length} plan(s).`
     )
     if (plans.length) {
       log(`Plan creation order:`)
@@ -137,7 +137,7 @@ export async function runImport({
     return r
   }
 
-  // 1. Credentials (sequential — each rewrites the shared encrypted blob).
+  // 1. Credentials (sequential - each rewrites the shared encrypted blob).
   for (const c of credentials) {
     if (!c || typeof c.key !== "string") {
       log(`  ✗ credential: missing key`)
@@ -172,7 +172,7 @@ export async function runImport({
     })
   }
 
-  // 4. Plans, in topo order, wiring intra-batch pre-steps by ref → created id.
+  // 4. Plans, in topo order, wiring intra-batch pre-steps by ref -> created id.
   const refToId = new Map()
   let plansCreated = 0
   let plansFailed = 0

package/lib/login.mjs

@@ -1,13 +1,13 @@
 /**
- * Browser device-login. Reuses test-lab's existing one-time-code → API-key
+ * Browser device-login. Reuses test-lab's existing one-time-code -> API-key
  * handshake (the same pattern the Chrome extension uses):
  *
  *   1. CLI starts a localhost callback server + opens the browser to
- *      <api>/cli/authorize?state=…&port=…
+ *      <api>/cli/authorize?state=...&port=...
  *   2. The signed-in user approves; the page redirects to
- *      http://127.0.0.1:<port>/callback?code=…&state=…
+ *      http://127.0.0.1:<port>/callback?code=...&state=...
  *   3. CLI verifies `state`, then exchanges the one-time code for a full-scope
- *      API key at POST /api/v1/cli/token (direct HTTPS — the secret never rides
+ *      API key at POST /api/v1/cli/token (direct HTTPS - the secret never rides
  *      in the browser redirect).
  *
  * If the server doesn't support the flow (older deployment) the caller falls
@@ -87,7 +87,7 @@ export function browserLogin(apiUrl, { timeoutMs = 600000 } = {}) {
       const { port } = server.address()
       const authUrl = `${apiUrl}/cli/authorize?state=${state}&port=${port}`
       console.log(`Opening your browser to authorize the CLI:\n  ${authUrl}\n`)
-      console.log(`Waiting for you to approve in the browser (up to 10 minutes)…\n`)
+      console.log(`Waiting for you to approve in the browser (up to 10 minutes)...\n`)
       openBrowser(authUrl)
     })
   })

package/lib/skills.mjs

@@ -10,9 +10,9 @@
  * stays as the browsable, open-source view; it is no longer fetched at runtime.
  *
  * Each agent has its own convention (verified against current docs):
- *   claude → .claude/skills/<name>/SKILL.md   (project) | ~/.claude/skills  (--global)
- *   codex  → .agents/skills/<name>/SKILL.md   (project) | ~/.agents/skills  (--global)
- *   cursor → .cursor/rules/<name>.mdc         (project only — Cursor has no
+ *   claude -> .claude/skills/<name>/SKILL.md   (project) | ~/.claude/skills  (--global)
+ *   codex -> .agents/skills/<name>/SKILL.md   (project) | ~/.agents/skills  (--global)
+ *   cursor -> .cursor/rules/<name>.mdc         (project only - Cursor has no
  *            global *file*; user rules live in Settings)
  *
  * claude + codex share the SKILL.md folder format (only the base dir differs);
@@ -54,8 +54,8 @@ export function detectAgents() {
 }
 
 /**
- * Where skill `name` is already installed — project (cwd) and global locations
- * across all agents — filtered to the paths that actually exist. Used to
+ * Where skill `name` is already installed - project (cwd) and global locations
+ * across all agents - filtered to the paths that actually exist. Used to
  * refresh installed skills (on `skills update` and after a CLI upgrade).
  */
 export function installedSkillLocations(name) {
@@ -74,7 +74,7 @@ export function installedSkillLocations(name) {
  * The distinct (agent, scope) locations where AT LEAST ONE test-lab skill is
  * currently installed. `skills update` and the on-upgrade refresh install EVERY
  * current skill at each of these, so a skill added in a later CLI release lands
- * wherever the user already keeps test-lab skills — not just fresher copies of
+ * wherever the user already keeps test-lab skills - not just fresher copies of
  * the skills that happened to be installed before.
  */
 export function installedSkillTargets() {
@@ -98,7 +98,7 @@ export function agentTarget(agent, { global } = {}) {
       return { kind: "skill-dir", base: global ? path.join(home, ".agents", "skills") : path.join(cwd, ".agents", "skills") }
     case "cursor":
       if (global) {
-        throw new Error("Cursor has no global rules file — add user rules in Cursor Settings → Rules, or install per-project (omit --global).")
+        throw new Error("Cursor has no global rules file - add user rules in Cursor Settings -> Rules, or install per-project (omit --global).")
       }
       return { kind: "cursor-rule", base: path.join(cwd, ".cursor", "rules") }
     default:

package/lib/toposort.mjs

@@ -55,7 +55,7 @@ export function topoSortPlans(plans) {
     }
   }
 
-  // Kahn's algorithm (iterative — no recursion depth concerns).
+  // Kahn's algorithm (iterative - no recursion depth concerns).
   const queue = []
   for (let i = 0; i < n; i++) if (indegree[i] === 0) queue.push(i)
   const order = []

package/lib/update-check.mjs

@@ -39,7 +39,7 @@ export function isNewer(a, b) {
 /** The notice string for (current, latest), or null if no update / bad input. */
 export function updateNotice(current, latest) {
   if (!current || !latest || !isNewer(latest, current)) return null
-  return `\n  ⚡ Update available: ${current} → ${latest}\n     npm i -g ${PKG}@latest\n`
+  return `\n  ⚡ Update available: ${current} -> ${latest}\n     npm i -g ${PKG}@latest\n`
 }
 
 function readCache() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@test-lab-ai/cli",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Import existing test plans into test-lab.ai from the command line (or an AI agent).",
   "type": "module",
   "bin": {

package/skills/test-lab-script/SKILL.md

@@ -32,18 +32,21 @@ This also means the script runs in a **restricted environment**: Playwright and
 
 Follow these in order.
 
-### 1. Confirm the target plan exists and is reachable
+### 1. Design the test as a plan prompt first (with test-lab-plan)
 
-An upload attaches to an **existing** plan by numeric id. Before writing anything:
+The plan's English **prompt is the spec; your script is one implementation of it.** Design the spec before you write a line of Playwright — that is what keeps the script honest and reviewable, and it is the fallback the platform runs if the script is ever cleared. Skipping this is how you end up with a script glued to a throwaway prompt that describes something else.
 
-- `testlab whoami` – confirm the CLI is authenticated. If not, the user runs `testlab login` once or sets `TESTLAB_API_KEY`. If `testlab` is not found, use `npx @test-lab-ai/cli` instead.
-- `testlab plans list` – find the plan id to upload to. The plan must already have a target URL (from its prompt or its project), because the script runs against that origin.
+- **No plan yet?** Use the **test-lab-plan** skill to design it: one user journey, an explicit start URL, and a numbered `Verify that:` block of observable acceptance criteria. Create it (dashboard or `testlab import`), then attach your script.
+- **Plan already exists?** Read its prompt — that *is* your spec. If the prompt is vague, wrong, or describes a different flow, fix it with test-lab-plan **before** writing the script. Never encode behaviour in the script that the prompt doesn't claim.
 
-If there is no suitable plan yet, create one first (in the dashboard, or with the **test-lab-plan** skill + `testlab import`). The plan's English prompt stops driving runs the moment a script is uploaded: your script replaces AI generation for that plan and device.
+Keep the prompt a clean user-journey spec: **no setup, auth, or implementation detail in the prose** — logged-in state, injected cookies, environment config, "no login needed", framework internals: none of it belongs there. Setup lives in the plan's pre-step / project environment, not the prompt body (test-lab-plan enforces this). Your script then *implements* that spec: one `test("Step N: …")` per prompt action, and an `expect` for each numbered acceptance criterion.
 
-### 2. Know the flow and its checks
+### 2. Confirm the plan is reachable and read the real UI
 
-Same discipline as a good test plan: one user journey, explicit start, observable assertions. If you are in the target site's repo, read the relevant component / route so your locators and assertions match real DOM text and real success states, not guesses. If you are not in the repo, pull a snapshot with WebFetch or ask the user for the key screens. Anchor every `expect` to something real.
+- `testlab whoami` – confirm the CLI is authenticated. If not, the user runs `testlab login` once or sets `TESTLAB_API_KEY`. If `testlab` is not found, use `npx @test-lab-ai/cli` instead.
+- `testlab plans list` – find the plan id to upload to. The plan must already have a target URL (from its prompt or its project), because the script runs against that origin. Uploading a script replaces AI generation for that plan + device, so from then on the prompt's job is to be the spec you implemented and the fallback — keep the two in sync.
+- **Read the real UI before asserting.** If you are in the target site's repo, read the relevant component / route so your locators and assertions match real DOM text and real success states, not guesses. If you are not in the repo, pull a snapshot with WebFetch or ask the user for the key screens. Anchor every `expect` to something real **and to a criterion in the prompt.**
+- **Fixing a script the plan already runs?** Download the live one with `testlab scripts get <id> [--device] [--out <file>]` (works for uploaded *and* generated scripts) instead of guessing at it, then edit and re-upload. That is the full fetch → fix → `scripts upload` loop, no dashboard needed.
 
 ### 3. Write the steps against `sharedPage`
 
@@ -140,6 +143,7 @@ The complete lists and the per-rule fixes are in `references/playwright-api.md`.
 7. **No Node / browser / network globals** (`process`, `fs`, `fetch`, `window`, `request`, …) and **no `page.evaluate`/`route`**. If you reached for one, rewrite the step to use the page.
 8. **No computed member keys or prototype access** (`x[expr]`, `.constructor`, `.__proto__`).
 9. **The plan id is right** (`testlab plans list`) and the plan has a target URL.
+10. **The script implements the plan's prompt.** Every prompt action maps to a `test("Step N: …")`, and every numbered acceptance criterion maps to an `expect`. The prompt itself reads as a clean user journey — no setup/auth/implementation detail leaked into the prose (that belongs in the plan's pre-step / environment). If the prompt and the script disagree, fix the prompt with test-lab-plan first.
 
 If any item fails, fix it before uploading – it will be rejected server-side anyway, and fixing first saves a round-trip.
 
@@ -157,7 +161,9 @@ If any item fails, fix it before uploading – it will be rejected server-side a
 
 ## Relationship to test-lab-plan
 
-- **test-lab-plan** – describe a flow in English; the AI generates and maintains the Playwright. Best when you want low effort or don't have a script.
-- **test-lab-script** (this skill) – you own the Playwright; upload it verbatim. Best when you already have a script, need exact control, or want to save generation credits.
+These **compose; they are not either/or.** test-lab-plan designs the spec (the plan's prompt); test-lab-script implements it (the Playwright). Even when you will hand-write the script, start with test-lab-plan so the spec is a clean, reviewable user journey and the script has a concrete contract to satisfy — see Workflow step 1.
+
+- **test-lab-plan** – describe a flow in English; the AI generates and maintains the Playwright. Best when you want low effort, or as the spec step before you write your own script.
+- **test-lab-script** (this skill) – you own the Playwright and upload it verbatim to implement that spec. Best when you need exact control, already have a script, or want to save generation credits.
 
 An uploaded script can still be refined later with AI from the dashboard (it is tagged as uploaded vs generated). `testlab examples` is the canonical, always-current reference for fixture shapes and resource formats.