@test-lab-ai/cli 0.2.2 → 0.2.6

package/AGENTS.md

@@ -23,12 +23,12 @@ npx @test-lab-ai/cli --help
    - Put the explicit, fully-qualified URL in the `prompt` (imported plans have
      no project, so there is no base URL to inherit).
    - Replace any secret (passwords, tokens, test-account logins) with a
-     `{{credentials.NAME}}` placeholder, and collect the real values into the
+     `{{credentials.<key>}}` placeholder, and collect the real values into the
      top-level `credentials` array.
    - Write clear pass/fail expectations into the prompt ("Confirm the dashboard
      loads", "Expect an order-confirmation page with an order number").
    - For generated/randomized data (a unique email per run, a random name),
-     define a **data fixture** and reference it as `{{data.FIXTURE.FIELD}}`
+     define a **data fixture** and reference it as `{{data.<fixture>.<field>}}`
      (see below).
    - If the user's repo has a test-lab plan skill/format, prefer it.
 3. **Write** the plans to a JSON file (or a directory of `*.json`).
@@ -43,7 +43,7 @@ Authentication: the user runs `testlab login` once (browser), or you set
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
 | `name` | string | yes | Max 200 chars |
-| `prompt` | string | yes | The test in natural language, with explicit URL(s) and `{{credentials.X}}`. Max 32 KB |
+| `prompt` | string | yes | The test in natural language, with explicit URL(s) and `{{credentials.<key>}}`. Max 32 KB |
 | `ref` | string | no | A handle unique within this import, used only to wire pre-steps (see below) |
 | `testType` | `"quickTest"` \| `"deepTest"` | no | Quick is a fast smoke; deep is more thorough |
 | `agentType` | string | no | `functional` (default), `accessibility`, `uiux`, `exploratory`, `performance`, `security` |
@@ -96,7 +96,7 @@ that matches no plan are rejected before anything is written.
 ## Credentials
 
 Put real secret values in the top-level `credentials` array; reference them in
-prompts (and cookie/header values) as `{{credentials.KEY}}`. Keys start with a
+prompts (and cookie/header values) as `{{credentials.<key>}}`. Keys start with a
 letter and use letters/numbers/underscores only. The CLI upserts credentials
 before creating plans, and values are stored encrypted (never echoed back).
 

package/README.md

@@ -37,9 +37,11 @@ testlab whoami                          Show the authenticated account
 testlab import <path> [--dry-run]        Import a file or directory of *.json
 testlab plans list                      List your test plans
 testlab plans create -f plan.json        Create one plan from JSON
-testlab credentials set KEY --value V     Set a credential   ({{credentials.KEY}})
+testlab credentials set <key> --value <value>     Set a credential ({{credentials.<key>}})
+testlab credentials list                 List credential keys (values never shown)
+testlab labels list                      List your labels
 testlab data list                        List your data fixtures
-testlab data create -f fixture.json      Create a data fixture ({{data.KEY.FIELD}})
+testlab data create -f fixture.json      Create a data fixture ({{data.<fixture>.<field>}})
 testlab examples                         Full JSON reference for every resource
 ```
 
@@ -96,29 +98,37 @@ 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).
+- `{{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)
+## Install the test-lab-plan skill (Claude Code, Codex, Cursor)
 
-The companion skill that *writes* test-lab plans — so an AI agent can design a
-plan, then this CLI imports it:
+The companion skill that *writes* test-lab plans, so an AI agent can design a
+plan and this CLI imports it:
 
 ```bash
-testlab skills install            # into ./.claude/skills (this project)
-testlab skills install --global   # into ~/.claude/skills (all projects)
+testlab skills install                  # auto-detects the agent(s) you use
+testlab skills install --agent codex    # Codex -> .agents/skills
+testlab skills install --agent cursor   # Cursor -> .cursor/rules/test-lab-plan.mdc
+testlab skills install --agent all      # all three
 ```
 
-Restart Claude Code to load it. It installs from the public skills mirror, so
-you always get the latest version. (Targets Claude Code's `.claude/skills/` layout.)
+With no `--agent`, it detects which agents you use (the agent running the command,
+plus the `.claude` / `.agents` / `.cursor` folders in your project) and installs for
+each, defaulting to Claude Code if none are found.
+
+Add `--global` for Claude Code or Codex (installs under your home directory);
+Cursor user rules are set in Cursor's Settings. Restart your agent to load it.
+It installs from the public [`Test-Lab-ai/skills`](https://github.com/Test-Lab-ai/skills)
+mirror, so you always get the latest version.
 
 ## 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 →
 convert each into the plan/fixture JSON above (explicit URL in the prompt,
-secrets as `{{credentials.X}}`, generated data as `{{data.X.Y}}`) →
+secrets as `{{credentials.<key>}}`, generated data as `{{data.<fixture>.<field>}}`) →
 `testlab import`.
 
 ## Under the hood
@@ -126,3 +136,7 @@ secrets as `{{credentials.X}}`, generated data as `{{data.X.Y}}`) →
 Every command is a thin wrapper over the public
 [Import API](https://test-lab.ai/docs/api/test-plans); an agent can call that
 directly instead of shelling out to the CLI.
+
+The CLI checks npm for a newer version about once a day and prints a one-line
+notice when you're behind. Set `NO_UPDATE_NOTIFIER=1` to silence it (it's also
+auto-suppressed in CI and non-interactive output).

package/bin/testlab.mjs

@@ -9,7 +9,7 @@
  *   testlab plans list                      List the account's test plans
  *   testlab plans create -f plan.json       Create one plan from a JSON file
  *   testlab plans create --name N --prompt P
- *   testlab credentials set KEY --value V    Upsert an account credential ({{credentials.KEY}})
+ *   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
@@ -23,7 +23,8 @@ import { apiFetch } from "../lib/api.mjs"
 import { loadImportFile, runImport } from "../lib/import.mjs"
 import { browserLogin } from "../lib/login.mjs"
 import { EXAMPLES_TEXT } from "../lib/examples.mjs"
-import { TESTLAB_SKILLS, resolveSkillsDir, installSkill } from "../lib/skills.mjs"
+import { TESTLAB_SKILLS, AGENTS, detectAgents, installSkill } from "../lib/skills.mjs"
+import { checkForUpdate, currentVersion } from "../lib/update-check.mjs"
 
 const log = (...a) => console.log(...a)
 function errExit(msg) {
@@ -40,18 +41,22 @@ Usage:
                                             (credentials, labels, fixtures, plans)
   testlab plans list                       List your test plans
   testlab plans create -f plan.json        Create one plan from JSON
-  testlab credentials set KEY --value V     Set a credential   ({{credentials.KEY}})
+  testlab credentials set <key> --value <value>     Set a credential ({{credentials.<key>}})
+  testlab credentials list                 List credential keys (values never shown)
+  testlab labels list                      List your labels
   testlab data list                        List your data fixtures
-  testlab data create -f fixture.json      Create a data fixture ({{data.KEY.FIELD}})
+  testlab data create -f fixture.json      Create a data fixture ({{data.<fixture>.<field>}})
   testlab examples                         Print the full JSON reference for every
                                            resource (designed for AI agents)
-  testlab skills install [--global]        Install the test-lab-plan skill into Claude Code
+  testlab skills install [--agent ...]     Install the test-lab-plan skill (auto-detects
+                                           Claude/Codex/Cursor; --agent claude|codex|cursor|all)
 
 Options:
   --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
+  --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`
 
@@ -69,7 +74,8 @@ function parse() {
       stdin: { type: "boolean" },
       force: { type: "boolean" },
       global: { type: "boolean" },
-      dir: { type: "string" },
+      agent: { type: "string" },
+      version: { type: "boolean", short: "v" },
       help: { type: "boolean", short: "h" },
     },
   })
@@ -195,6 +201,36 @@ async function cmdCredentialsSet(flags, args) {
   log(`✓ Set credential ${key}`)
 }
 
+async function cmdCredentialsList(flags) {
+  const { apiKey, apiUrl } = requireAuth(flags)
+  const r = await apiFetch(apiUrl, apiKey, "GET", "/api/v1/credentials")
+  if (!r.ok) errExit(`${r.status}: ${r.json?.error || ""}`)
+  const creds = r.json?.credentials || []
+  if (creds.length === 0) {
+    log("No credentials yet.")
+    return
+  }
+  // Keys only; the API never returns credential values.
+  for (const c of creds) log(`  ${c.key}`)
+  log(`\n${creds.length} credential(s)`)
+}
+
+async function cmdLabelsList(flags) {
+  const { apiKey, apiUrl } = requireAuth(flags)
+  const r = await apiFetch(apiUrl, apiKey, "GET", "/api/v1/labels")
+  if (!r.ok) errExit(`${r.status}: ${r.json?.error || ""}`)
+  const labels = r.json?.labels || []
+  if (labels.length === 0) {
+    log("No labels yet.")
+    return
+  }
+  for (const l of labels) {
+    const n = l.test_plan_count
+    log(`  ${l.name}${n != null ? `  (${n} plan${n === 1 ? "" : "s"})` : ""}`)
+  }
+  log(`\n${labels.length} label(s)`)
+}
+
 async function cmdImport(flags, args) {
   const target = args[1]
   if (!target) errExit("usage: testlab import <path> [--dry-run]")
@@ -254,22 +290,46 @@ function cmdExamples() {
 
 async function cmdSkillsInstall(flags, args) {
   const requested = args[2] ? [args[2]] : TESTLAB_SKILLS
-  const targetDir = resolveSkillsDir({ global: flags.global, dir: flags.dir })
-  for (const name of requested) {
-    try {
-      const res = await installSkill(name, targetDir)
-      log(`✓ Installed ${res.name} (${res.count} file${res.count === 1 ? "" : "s"}) → ${res.dir}`)
-    } catch (e) {
-      errExit(`failed to install ${name}: ${e.message}`)
+
+  // --agent wins (a single agent, a comma list, or "all"); otherwise auto-detect
+  // from the running agent + the project's agent dirs, falling back to Claude.
+  let targets
+  if (flags.agent) {
+    const v = String(flags.agent).toLowerCase()
+    targets = v === "all" ? AGENTS : v.split(",").map((s) => s.trim()).filter(Boolean)
+  } else {
+    targets = detectAgents()
+    if (targets.length === 0) {
+      targets = ["claude"]
+      log("No agent detected; defaulting to Claude Code. Use --agent claude|codex|cursor|all to choose.")
+    } else {
+      log(`Detected: ${targets.join(", ")}  (override with --agent, add --global for your home dir)`)
+    }
+  }
+  const bad = targets.filter((a) => !AGENTS.includes(a))
+  if (bad.length) errExit(`unknown agent(s): ${bad.join(", ")}. Use ${AGENTS.join(", ")}, or all.`)
+
+  let installed = 0
+  for (const agent of targets) {
+    for (const name of requested) {
+      try {
+        const res = await installSkill(name, agent, { global: flags.global })
+        installed++
+        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}`)
+        else errExit(`failed to install ${name} for ${agent}: ${e.message}`)
+      }
     }
   }
-  log(`\nRestart Claude Code (start a new session) to load the skill.`)
+  if (installed > 0) log(`\nRestart your agent (start a new session) to load the skill.`)
 }
 
 function cmdSkillsList() {
   log(`Available test-lab skills:`)
   for (const s of TESTLAB_SKILLS) log(`  ${s}`)
-  log(`\nInstall with: testlab skills install [name] [--global]`)
+  log(`\nInstall with: testlab skills install [name] [--agent ${AGENTS.join("|")}|all]`)
 }
 
 async function main() {
@@ -282,6 +342,13 @@ async function main() {
   const flags = parsed.values
   const args = parsed.positionals
 
+  checkForUpdate() // best-effort "update available" notice (cached, non-blocking)
+
+  if (flags.version || args[0] === "version") {
+    log(currentVersion() || "unknown")
+    return
+  }
+
   if (flags.help || args.length === 0 || args[0] === "help") {
     log(HELP)
     return
@@ -298,7 +365,11 @@ async function main() {
       return errExit("usage: testlab plans <list|create>")
     case "credentials":
       if (args[1] === "set") return cmdCredentialsSet(flags, args)
-      return errExit("usage: testlab credentials set <key> --value <v>")
+      if (args[1] === "list") return cmdCredentialsList(flags)
+      return errExit("usage: testlab credentials <set|list>")
+    case "labels":
+      if (args[1] === "list") return cmdLabelsList(flags)
+      return errExit("usage: testlab labels list")
     case "data":
       if (args[1] === "list") return cmdDataList(flags)
       if (args[1] === "create") return cmdDataCreate(flags)

package/lib/examples.mjs

@@ -10,12 +10,12 @@ All resources are scoped to the API key's account. Auth: a tl_… key via
 ═══════════════════════════════════════════════════════════════════════════
 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)
+  {{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, …)
 
 ═══════════════════════════════════════════════════════════════════════════
-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"):
@@ -31,7 +31,7 @@ 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.KEY.FIELD}}
+3) DATA FIXTURE  — reusable generated test data behind {{data.<fixture>.<field>}}
 ═══════════════════════════════════════════════════════════════════════════
 Command:  testlab data create -f fixture.json
 JSON (under "fixtures"):

package/lib/skills.mjs

@@ -1,11 +1,19 @@
 /**
- * Install test-lab skills (e.g. test-lab-plan) into a local agent's skills
- * directory by fetching them from the public Test-Lab-ai/skills mirror.
+ * Install test-lab skills (e.g. test-lab-plan) into a local AI coding agent by
+ * fetching them from the public Test-Lab-ai/skills mirror. The mirror is the
+ * single source of truth, so this always installs the latest published skill.
  *
- * Zero-dep: global fetch + node:fs. Targets Claude Code's
- * .claude/skills/<name>/ layout — project dir by default, ~/.claude with
- * --global, or an explicit --dir. The mirror is the single source of truth,
- * so this always installs the latest published skill.
+ * 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
+ *            global *file*; user rules live in Settings)
+ *
+ * claude + codex use the identical SKILL.md folder format, so they share the
+ * write path (only the base dir differs). cursor uses a single .mdc rule file
+ * with its own frontmatter, so we convert SKILL.md on the way out.
+ *
+ * Zero-dep: global fetch + node:fs.
  */
 import fs from "node:fs"
 import os from "node:os"
@@ -13,19 +21,55 @@ import path from "node:path"
 
 const MIRROR = "Test-Lab-ai/skills"
 const MIRROR_BRANCH = "main"
+const UA = { "User-Agent": "test-lab-cli" }
 
 // Skills published by test-lab. Add new skill directory names here.
 export const TESTLAB_SKILLS = ["test-lab-plan"]
 
-export function resolveSkillsDir({ global, dir } = {}) {
-  if (dir) return path.resolve(dir)
-  if (global) return path.join(os.homedir(), ".claude", "skills")
-  return path.join(process.cwd(), ".claude", "skills")
+// Agents this CLI can install into.
+export const AGENTS = ["claude", "codex", "cursor"]
+
+/**
+ * Best-effort detection of which agent(s) to install for when --agent is
+ * omitted. Combines two signals:
+ *   (a) env markers of the agent running this command (CLAUDECODE is reliable;
+ *       Codex/Cursor only expose sandbox-conditional vars, so absence means
+ *       "unknown", never "no"), and
+ *   (b) agent config dirs already present in the project.
+ * Returns a de-duplicated list (possibly empty).
+ */
+export function detectAgents() {
+  const env = process.env
+  const cwd = process.cwd()
+  const found = new Set()
+  if (env.CLAUDECODE) found.add("claude")
+  if (env.CODEX_SANDBOX) found.add("codex")
+  if (env.CURSOR_AGENT || env.CURSOR_TRACE_ID || env.CURSOR_SANDBOX) found.add("cursor")
+  if (fs.existsSync(path.join(cwd, ".claude"))) found.add("claude")
+  if (fs.existsSync(path.join(cwd, ".agents"))) found.add("codex")
+  if (fs.existsSync(path.join(cwd, ".cursor"))) found.add("cursor")
+  return [...found]
 }
 
-const UA = { "User-Agent": "test-lab-cli" }
+/** Resolve the install target (base dir + format) for one agent. */
+export function agentTarget(agent, { global } = {}) {
+  const home = os.homedir()
+  const cwd = process.cwd()
+  switch (agent) {
+    case "claude":
+      return { kind: "skill-dir", base: global ? path.join(home, ".claude", "skills") : path.join(cwd, ".claude", "skills") }
+    case "codex":
+      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).")
+      }
+      return { kind: "cursor-rule", base: path.join(cwd, ".cursor", "rules") }
+    default:
+      throw new Error(`unknown agent "${agent}" (use ${AGENTS.join(", ")}, or all)`)
+  }
+}
 
-// List the blob paths under skills/<name>/ in the mirror's tree.
 async function listSkillFiles(name) {
   const r = await fetch(
     `https://api.github.com/repos/${MIRROR}/git/trees/${MIRROR_BRANCH}?recursive=1`,
@@ -39,23 +83,47 @@ async function listSkillFiles(name) {
     .map((e) => e.path)
 }
 
-/** Fetch every file of one skill from the mirror and write it under targetDir/<name>/. */
-export async function installSkill(name, targetDir) {
+async function fetchText(p) {
+  const r = await fetch(`https://raw.githubusercontent.com/${MIRROR}/${MIRROR_BRANCH}/${p}`, { headers: UA })
+  if (!r.ok) throw new Error(`could not fetch ${p} (${r.status})`)
+  return r.text()
+}
+
+/** Convert a Claude SKILL.md into a Cursor .mdc rule (Agent Requested mode). */
+function toCursorRule(skillMd) {
+  const m = skillMd.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/)
+  const frontmatter = m ? m[1] : ""
+  const body = (m ? m[2] : skillMd).trim()
+  const descMatch = frontmatter.match(/^description:\s*(.+)$/m)
+  const description = descMatch ? descMatch[1].trim() : "Write test-lab.ai test plans"
+  // alwaysApply:false + a description => Cursor pulls it in when relevant.
+  return `---\ndescription: ${description}\nalwaysApply: false\n---\n\n${body}\n`
+}
+
+/** Install one skill for one agent. Returns { name, agent, count, dest }. */
+export async function installSkill(name, agent, opts = {}) {
+  const { kind, base } = agentTarget(agent, opts)
   const files = await listSkillFiles(name)
   if (files.length === 0) throw new Error(`skill "${name}" not found in ${MIRROR}`)
   const prefix = `skills/${name}/`
+
+  if (kind === "cursor-rule") {
+    const skillPath = files.find((p) => p.endsWith("/SKILL.md"))
+    if (!skillPath) throw new Error(`skill "${name}" has no SKILL.md`)
+    const dest = path.join(base, `${name}.mdc`)
+    fs.mkdirSync(base, { recursive: true })
+    fs.writeFileSync(dest, toCursorRule(await fetchText(skillPath)))
+    return { name, agent, count: 1, dest }
+  }
+
+  // skill-dir: claude + codex (identical SKILL.md folder layout).
   let count = 0
   for (const p of files) {
     const rel = p.slice(prefix.length)
-    const raw = await fetch(`https://raw.githubusercontent.com/${MIRROR}/${MIRROR_BRANCH}/${p}`, {
-      headers: UA,
-    })
-    if (!raw.ok) throw new Error(`could not fetch ${p} (${raw.status})`)
-    const body = await raw.text()
-    const dest = path.join(targetDir, name, rel)
+    const dest = path.join(base, name, rel)
     fs.mkdirSync(path.dirname(dest), { recursive: true })
-    fs.writeFileSync(dest, body)
+    fs.writeFileSync(dest, await fetchText(p))
     count++
   }
-  return { name, count, dir: path.join(targetDir, name) }
+  return { name, agent, count, dest: path.join(base, name) }
 }

package/lib/update-check.mjs

@@ -0,0 +1,85 @@
+/**
+ * Best-effort "update available" notice.
+ *
+ * Design constraints: never block, slow, or break a command. It reads a cached
+ * latest-version (checked against the npm registry at most once/day), prints a
+ * one-line notice to STDERR when the running version is behind, and kicks off a
+ * background refresh for next time. Any failure (offline, slow/forbidden
+ * registry) is swallowed. Suppressed when stderr isn't a TTY (pipes / CI /
+ * agents) or NO_UPDATE_NOTIFIER / CI is set, so it never pollutes scripted output.
+ */
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+const PKG = "@test-lab-ai/cli"
+const REGISTRY = "https://registry.npmjs.org/@test-lab-ai%2Fcli"
+const CACHE = path.join(os.homedir(), ".test-lab", "update-check.json")
+const DAY = 24 * 60 * 60 * 1000
+
+export function currentVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version
+  } catch {
+    return null
+  }
+}
+
+/** Numeric major.minor.patch compare (pre-release tags ignored). true if a > b. */
+export function isNewer(a, b) {
+  const parts = (v) => String(v || "0").split("-")[0].split(".").map((n) => parseInt(n, 10) || 0)
+  const x = parts(a)
+  const y = parts(b)
+  for (let i = 0; i < 3; i++) {
+    if ((x[i] || 0) !== (y[i] || 0)) return (x[i] || 0) > (y[i] || 0)
+  }
+  return false
+}
+
+/** 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`
+}
+
+function readCache() {
+  try {
+    return JSON.parse(fs.readFileSync(CACHE, "utf8"))
+  } catch {
+    return {}
+  }
+}
+
+function writeCache(obj) {
+  try {
+    fs.mkdirSync(path.dirname(CACHE), { recursive: true })
+    fs.writeFileSync(CACHE, JSON.stringify(obj))
+  } catch {
+    /* best effort */
+  }
+}
+
+export function checkForUpdate() {
+  if (!process.stderr.isTTY || process.env.NO_UPDATE_NOTIFIER || process.env.CI) return
+  const current = currentVersion()
+  if (!current) return
+
+  const cache = readCache()
+
+  // Notify from the last-known latest (this run); refresh updates next run.
+  const notice = updateNotice(current, cache.latest)
+  if (notice) process.stderr.write(notice + "\n")
+
+  if (!cache.lastCheck || Date.now() - cache.lastCheck > DAY) {
+    const ctrl = new AbortController()
+    const timer = setTimeout(() => ctrl.abort(), 2000)
+    fetch(REGISTRY, { signal: ctrl.signal, headers: { Accept: "application/vnd.npm.install-v1+json" } })
+      .then((r) => (r.ok ? r.json() : null))
+      .then((j) => {
+        const latest = j && j["dist-tags"] && j["dist-tags"].latest
+        if (latest) writeCache({ lastCheck: Date.now(), latest })
+      })
+      .catch(() => {})
+      .finally(() => clearTimeout(timer))
+  }
+}

package/package.json

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