@figs-so/cli 0.1.7 → 0.1.8

package/README.md

@@ -33,6 +33,6 @@ The full, always-current guide + `agent.json` schema is served at **`<endpoint>/
 | `figs version` | print version + check for updates |
 | `figs help [<command>]` | usage (bare `figs` shows it too) |
 
-Global: `-h` / `--help` on any command (or `figs help <command>`), `-v` / `--version` for the version. Unknown commands exit non-zero.
+Global: `-h` / `--help` on any command (or `figs help <command>`), `-v` / `--version` for the version. Unknown commands **and unknown flags** exit non-zero (no silent no-ops). Flags accept `--name value` or `--name=value`. Network calls time out after 30s.
 
 Override the endpoint with `FIGS_ENDPOINT` (e.g. `http://localhost:3000` for local dev).

package/figs.mjs

@@ -16,7 +16,9 @@
  *
  * Designed to be driven by an agent: non-interactive, clear output, `--json`
  * on read commands, `-h`/`--help`/`help` everywhere, and errors that say what to
- * do next. Bare `figs` prints help; unknown commands exit non-zero.
+ * do next. Bare `figs` prints help; unknown commands AND unknown flags exit
+ * non-zero (no silent no-ops). Flags accept `--name value` or `--name=value`.
+ * Network calls time out (30s) instead of hanging the agent.
  *
  * Auth is the *user* (a token, configured once per machine). Identity is the
  * *agent* — a UUID generated by `init`, stored in the committed, non-secret
@@ -35,7 +37,7 @@ import { homedir } from "node:os"
 import { join } from "node:path"
 import { randomUUID } from "node:crypto"
 
-const VERSION = "0.1.7"
+const VERSION = "0.1.8"
 // Going-forward default; override with FIGS_ENDPOINT or .figs/config.json endpoint
 // (e.g. FIGS_ENDPOINT=http://localhost:3000 for local dev).
 const DEFAULT_ENDPOINT = "https://app.figs.so"
@@ -47,34 +49,67 @@ const cmd = process.argv[2] ?? "help"
 const JSON_OUT = process.argv.includes("--json")
 const WANTS_HELP = process.argv.slice(2).some((a) => a === "-h" || a === "--help")
 
-/** Command registry — single source for dispatch + `figs help`. */
+/**
+ * Command registry — single source for dispatch, `figs help`, and per-command
+ * flag validation. `flags` lists the flags a command accepts (beyond the global
+ * `-h`/`--help`); an unrecognized flag is rejected rather than silently ignored.
+ */
 const COMMANDS = {
-  status: { args: "[--json]", desc: "show login / workspace / agent state" },
+  status: {
+    args: "[--json]",
+    flags: ["--json"],
+    desc: "show login / workspace / agent state",
+    eg: "figs status --json",
+  },
   login: {
     args: "[<token>]",
+    flags: [],
     desc: "log in — browser device-flow, or save a pasted token",
     more: [
       "no arg → device flow: a human approves in a browser (you never see the token).",
       "<token> → save a token you already have to ~/.figs/credentials.json.",
     ],
+    eg: "figs login",
+  },
+  logout: { args: "", flags: [], desc: "remove the locally-saved token (~/.figs/credentials.json)" },
+  workspaces: {
+    args: "[--json]",
+    flags: ["--json"],
+    desc: "list your workspaces (read-only; shows the slug)",
+    eg: "figs workspaces",
   },
-  logout: { args: "", desc: "remove the locally-saved token (~/.figs/credentials.json)" },
-  workspaces: { args: "[--json]", desc: "list your workspaces (read-only; shows the slug)" },
   init: {
     args: "--workspace <slug-or-id> [--endpoint <url>]",
+    flags: ["--workspace", "--endpoint"],
     desc: "set up .figs/ here (identity UUID + config + pointer GUIDE.md)",
     more: [
       "--workspace takes a slug (resolved to its UUID) or a raw UUID — get it from `figs workspaces`.",
     ],
+    eg: "figs init --workspace acme-corp",
   },
-  doctor: { args: "", desc: "validate .figs/ against the live contract before pushing" },
+  doctor: { args: "", flags: ["--json"], desc: "validate .figs/ against the live contract before pushing" },
   push: {
     args: "",
+    flags: [],
     desc: "publish .figs/ — spine to /api/ingest, artifacts to /api/artifacts",
     more: ["Idempotent (records fold by id). Exits non-zero if an artifact upload is rejected."],
+    eg: "figs push",
   },
-  version: { args: "", desc: "print the CLI version and check for updates" },
-  help: { args: "[<command>]", desc: "show this help, or detailed help for one command" },
+  version: { args: "", flags: [], desc: "print the CLI version and check for updates" },
+  help: { args: "[<command>]", flags: [], desc: "show this help, or detailed help for one command" },
+}
+
+/** Reject unknown flags for a command (don't silently ignore an agent's typo). */
+function checkFlags(name) {
+  const allowed = new Set([...(COMMANDS[name].flags ?? []), "-h", "--help"])
+  for (const tok of process.argv.slice(3)) {
+    if (tok.startsWith("-") && tok !== "-" && tok !== "--") {
+      const f = tok.split("=")[0]
+      if (!allowed.has(f)) {
+        die(`unknown flag "${f}" for \`figs ${name}\` — run \`figs ${name} --help\``)
+      }
+    }
+  }
 }
 
 function die(msg) {
@@ -84,9 +119,14 @@ function die(msg) {
 function readJson(path, fallback) {
   return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : fallback
 }
+/** Read a flag value — supports both `--name value` and `--name=value`. */
 function flag(name) {
-  const i = process.argv.indexOf(name)
-  return i >= 0 ? process.argv[i + 1] : undefined
+  const args = process.argv.slice(2)
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === name) return args[i + 1]
+    if (args[i].startsWith(`${name}=`)) return args[i].slice(name.length + 1)
+  }
+  return undefined
 }
 function getToken() {
   return process.env.FIGS_TOKEN || readJson(globalCreds, {}).token
@@ -98,12 +138,28 @@ function resolveEndpoint() {
     "",
   )
 }
+const REQUEST_TIMEOUT_MS = 30000
+/** `fetch` with a hard timeout so a hung server never stalls the agent. */
+async function fetchT(url, opts = {}) {
+  const ctrl = new AbortController()
+  const t = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS)
+  try {
+    return await fetch(url, { ...opts, signal: ctrl.signal })
+  } finally {
+    clearTimeout(t)
+  }
+}
+/** Human reason for a thrown fetch error (timeout vs. network). */
+function netReason(e) {
+  if (e?.name === "AbortError") return `timed out after ${REQUEST_TIMEOUT_MS / 1000}s`
+  return e?.cause?.code || e?.code || e?.message || "network error"
+}
 /** Low-level request — returns { ok, status, data }, never throws/exits. */
 async function request(method, path, body, token = getToken()) {
   const base = resolveEndpoint()
   let res
   try {
-    res = await fetch(`${base}${path}`, {
+    res = await fetchT(`${base}${path}`, {
       method,
       headers: {
         "content-type": "application/json",
@@ -112,12 +168,8 @@ async function request(method, path, body, token = getToken()) {
       body: body ? JSON.stringify(body) : undefined,
     })
   } catch (e) {
-    // Network error (unreachable host, DNS, timeout) — degrade, don't crash.
-    return {
-      ok: false,
-      status: 0,
-      data: { error: `cannot reach ${base} (${e?.cause?.code || e?.code || e?.message || "network error"})` },
-    }
+    // Unreachable host / DNS / timeout — degrade, don't crash.
+    return { ok: false, status: 0, data: { error: `cannot reach ${base} (${netReason(e)})` } }
   }
   const text = await res.text()
   let data
@@ -136,12 +188,20 @@ async function api(method, path, body) {
   return r.data
 }
 
+/**
+ * Compare two semver strings → -1 | 0 | 1, or **null** if either is unparseable.
+ * Returning null (rather than guessing) lets the caller skip the check instead of
+ * failing closed on a malformed server-provided version — a bad `min` must never
+ * lock an agent out of pushing.
+ */
 function cmpSemver(a, b) {
-  const pa = String(a).split(".").map(Number)
-  const pb = String(b).split(".").map(Number)
+  const pa = String(a).split(".").map((n) => parseInt(n, 10))
+  const pb = String(b).split(".").map((n) => parseInt(n, 10))
   for (let i = 0; i < 3; i++) {
-    const d = (pa[i] || 0) - (pb[i] || 0)
-    if (d) return d < 0 ? -1 : 1
+    const x = pa[i] ?? 0
+    const y = pb[i] ?? 0
+    if (Number.isNaN(x) || Number.isNaN(y)) return null
+    if (x !== y) return x < y ? -1 : 1
   }
   return 0
 }
@@ -168,11 +228,12 @@ async function checkVersion({ force = false, hardFail = false } = {}) {
   }
   const min = info?.cli?.min
   const latest = info?.cli?.latest
-  if (min && cmpSemver(VERSION, min) < 0) {
+  // cmpSemver returns null on an unparseable version → skip (never fail closed).
+  if (min && cmpSemver(VERSION, min) === -1) {
     const msg = `figs CLI ${VERSION} is below the minimum ${min} — upgrade: npx @figs-so/cli@latest`
     if (hardFail) die(msg)
     console.warn(`figs: ! ${msg}`)
-  } else if (latest && cmpSemver(VERSION, latest) < 0) {
+  } else if (latest && cmpSemver(VERSION, latest) === -1) {
     console.warn(`figs: a newer CLI is available (${latest}) — npx @figs-so/cli@latest`)
   }
 }
@@ -189,6 +250,7 @@ function printHelp(name) {
     console.log(`Usage: figs ${name}${c.args ? " " + c.args : ""}\n`)
     console.log(`  ${c.desc}`)
     if (c.more) for (const line of c.more) console.log(`  ${line}`)
+    if (c.eg) console.log(`\n  e.g.  ${c.eg}`)
     return
   }
   console.log("figs — publish your AI agent's state to Figs (https://figs.so)\n")
@@ -212,14 +274,16 @@ else if (cmd === "version" || cmd === "--version" || cmd === "-v" || cmd === "-V
   console.log(VERSION)
   await checkVersion({ force: true })
 } else if (WANTS_HELP) printHelp(cmd)
-else if (cmd === "login") await login(process.argv[3])
-else if (cmd === "logout") logout()
-else if (cmd === "status") await status()
-else if (cmd === "workspaces") await workspaces()
-else if (cmd === "init") await init()
-else if (cmd === "doctor") await doctor()
-else if (cmd === "push") await push()
-else {
+else if (COMMANDS[cmd]) {
+  checkFlags(cmd) // reject unknown flags before running
+  if (cmd === "login") await login(process.argv[3])
+  else if (cmd === "logout") logout()
+  else if (cmd === "status") await status()
+  else if (cmd === "workspaces") await workspaces()
+  else if (cmd === "init") await init()
+  else if (cmd === "doctor") await doctor()
+  else if (cmd === "push") await push()
+} else {
   console.error(`figs: unknown command "${cmd}" — run \`figs help\` for usage`)
   process.exit(1)
 }
@@ -532,11 +596,16 @@ async function push() {
   const asks = foldById(readJsonl("asks.jsonl"))
 
   const base = endpoint.replace(/\/+$/, "")
-  const res = await fetch(`${base}/api/ingest`, {
-    method: "POST",
-    headers: { "content-type": "application/json", "x-figs-token": token },
-    body: JSON.stringify({ workspaceId: config.workspaceId, agent, runs, asks }),
-  })
+  let res
+  try {
+    res = await fetchT(`${base}/api/ingest`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-figs-token": token },
+      body: JSON.stringify({ workspaceId: config.workspaceId, agent, runs, asks }),
+    })
+  } catch (e) {
+    die(`push failed — cannot reach ${base} (${netReason(e)})`)
+  }
   const text = await res.text()
   if (!res.ok) die(`push failed (${res.status}): ${text}`)
   console.log(
@@ -577,16 +646,23 @@ async function pushArtifacts(base, token, config, runs, asks) {
       continue
     }
     const content = readFileSync(p).toString("base64")
-    const res = await fetch(`${base}/api/artifacts/upload`, {
-      method: "POST",
-      headers: { "content-type": "application/json", "x-figs-token": token },
-      body: JSON.stringify({
-        workspaceId: config.workspaceId,
-        agentId: config.agentId,
-        name,
-        content,
-      }),
-    })
+    let res
+    try {
+      res = await fetchT(`${base}/api/artifacts/upload`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-figs-token": token },
+        body: JSON.stringify({
+          workspaceId: config.workspaceId,
+          agentId: config.agentId,
+          name,
+          content,
+        }),
+      })
+    } catch (e) {
+      console.error(`figs: ✗ artifact upload failed ${name}: ${netReason(e)}`)
+      failed++
+      continue
+    }
     if (!res.ok) {
       const t = await res.text().catch(() => "")
       const hint =
@@ -614,10 +690,19 @@ async function pushArtifacts(base, token, config, runs, asks) {
 function readJsonl(name) {
   const p = join(repoDir, name)
   if (!existsSync(p)) return []
-  return readFileSync(p, "utf8")
+  const out = []
+  readFileSync(p, "utf8")
     .split("\n")
-    .filter((l) => l.trim())
-    .map((l) => JSON.parse(l))
+    .forEach((line, i) => {
+      const s = line.trim()
+      if (!s) return
+      try {
+        out.push(JSON.parse(s))
+      } catch {
+        die(`malformed JSON in .figs/${name} line ${i + 1}: ${s.slice(0, 80)}`)
+      }
+    })
+  return out
 }
 
 /** Fold append-only records by id — latest line wins. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figs-so/cli",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Figs CLI — publish your AI agent's state to Figs (figs.so). Run by the agent.",
   "type": "module",
   "bin": {