@figs-so/cli 0.1.6 → 0.1.8

package/README.md

@@ -31,5 +31,8 @@ The full, always-current guide + `agent.json` schema is served at **`<endpoint>/
 | `figs doctor` | validate `.figs/` against the contract |
 | `figs push` | one-way publish of `.figs/` |
 | `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 **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

@@ -12,9 +12,13 @@
  *   figs doctor                         validate .figs/ against the contract before pushing
  *   figs push                           one-way push the .figs/ spine to the ingest endpoint
  *   figs version                        print the CLI version (and check for updates)
+ *   figs help [<command>]               usage; `-h`/`--help` on any command, `-v` for version
  *
  * Designed to be driven by an agent: non-interactive, clear output, `--json`
- * on read commands, and errors that say what to do next.
+ * on read commands, `-h`/`--help`/`help` everywhere, and errors that say what to
+ * 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
@@ -33,7 +37,7 @@ import { homedir } from "node:os"
 import { join } from "node:path"
 import { randomUUID } from "node:crypto"
 
-const VERSION = "0.1.6"
+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"
@@ -41,8 +45,72 @@ const DEFAULT_ENDPOINT = "https://app.figs.so"
 const repoDir = join(process.cwd(), ".figs")
 const globalDir = join(homedir(), ".figs")
 const globalCreds = join(globalDir, "credentials.json")
-const cmd = process.argv[2] ?? "status"
+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`, 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]",
+    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",
+  },
+  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: "", 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: "", 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) {
   console.error(`figs: ${msg}`)
@@ -51,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
@@ -65,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",
@@ -79,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
@@ -103,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
 }
@@ -135,29 +228,64 @@ 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`)
   }
 }
 
-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 if (cmd === "version" || cmd === "--version") {
+/** `figs help [cmd]` — top-level usage, or one command's detail. */
+function printHelp(name) {
+  const pad = 36
+  if (name && name !== "-h" && name !== "--help") {
+    const c = COMMANDS[name]
+    if (!c) {
+      console.log(`figs: no such command "${name}"\n`)
+      return printHelp()
+    }
+    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")
+  console.log("Usage: figs <command> [options]\n")
+  console.log("Commands:")
+  for (const [n, c] of Object.entries(COMMANDS)) {
+    console.log(`  ${`${n} ${c.args}`.trim().padEnd(pad)} ${c.desc}`)
+  }
+  console.log("\nGlobal flags:")
+  console.log(`  ${"-h, --help".padEnd(pad)} show help (or \`figs help <command>\`)`)
+  console.log(`  ${"-v, --version".padEnd(pad)} print the CLI version`)
+  console.log("\nEnvironment:")
+  console.log(`  ${"FIGS_ENDPOINT".padEnd(pad)} override the API endpoint (e.g. http://localhost:3000)`)
+  console.log(`  ${"FIGS_TOKEN".padEnd(pad)} use this token instead of ~/.figs/credentials.json`)
+  console.log(`\nEndpoint: ${resolveEndpoint()}`)
+  console.log(`Guide:    ${resolveEndpoint()}/llms.txt`)
+}
+
+if (cmd === "help" || cmd === "-h" || cmd === "--help") printHelp(process.argv[3])
+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 (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 {
-  die(
-    `unknown command "${cmd}" — try: status, login, logout, workspaces, init, doctor, push`,
-  )
+  console.error(`figs: unknown command "${cmd}" — run \`figs help\` for usage`)
+  process.exit(1)
 }
 
 function sleep(ms) {
@@ -468,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(
@@ -513,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 =
@@ -550,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.6",
+  "version": "0.1.8",
   "description": "Figs CLI — publish your AI agent's state to Figs (figs.so). Run by the agent.",
   "type": "module",
   "bin": {