@figs-so/cli 0.1.3 → 0.1.6

package/README.md

@@ -25,6 +25,7 @@ The full, always-current guide + `agent.json` schema is served at **`<endpoint>/
 |---|---|
 | `figs status [--json]` | login / workspace / agent state |
 | `figs login` | device-flow browser approve (or `figs login <token>`) |
+| `figs logout` | remove the locally-saved token (`~/.figs/credentials.json`) |
 | `figs workspaces [--json]` | list your workspaces (read-only; create one in the web app) |
 | `figs init --workspace <slug-or-id>` | resolve the workspace, generate identity UUID + config + pointer GUIDE.md |
 | `figs doctor` | validate `.figs/` against the contract |

package/figs.mjs

@@ -5,6 +5,7 @@
  *   figs status                         show login / workspace / agent state    [--json]
  *   figs login                          browser approve (device flow) — agent never sees the token
  *   figs login <token>                  fallback: save a token you pasted (~/.figs/credentials.json)
+ *   figs logout                         remove the locally-saved token (~/.figs/credentials.json)
  *   figs workspaces                     list the user's workspaces               [--json]
  *   figs init --workspace <slug-or-id> [--endpoint <url>]
  *                                         create .figs/config.json + GUIDE.md (generates a stable agent id)
@@ -25,13 +26,14 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  rmSync,
   writeFileSync,
 } from "node:fs"
 import { homedir } from "node:os"
 import { join } from "node:path"
 import { randomUUID } from "node:crypto"
 
-const VERSION = "0.1.3"
+const VERSION = "0.1.6"
 // 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"
@@ -143,6 +145,7 @@ async function checkVersion({ force = false, hardFail = false } = {}) {
 }
 
 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()
@@ -153,7 +156,7 @@ else if (cmd === "version" || cmd === "--version") {
   await checkVersion({ force: true })
 } else {
   die(
-    `unknown command "${cmd}" — try: status, login, workspaces, init, doctor, push`,
+    `unknown command "${cmd}" — try: status, login, logout, workspaces, init, doctor, push`,
   )
 }
 
@@ -197,16 +200,48 @@ async function login(token) {
     }
     if (status === "denied") die("authorization denied")
     if (status === "expired") die("code expired — run `figs login` again")
+    if (status === "already_claimed") {
+      die("this login was already completed (on another run) — run `figs status` to check; re-run `figs login` if no token was saved")
+    }
+    if (status === "not_found") die("login code not found — run `figs login` again")
     // pending → keep polling
   }
   die("timed out waiting for approval — run `figs login` again")
 }
 
+/**
+ * `figs logout` — remove the locally-saved token (`~/.figs/credentials.json`).
+ * This only clears *this machine's* copy; the token still exists server-side
+ * until you revoke it in Settings. A token supplied via the FIGS_TOKEN env var
+ * can't be removed here (unset the env var to fully log out).
+ */
+function logout() {
+  if (existsSync(globalCreds)) {
+    try {
+      rmSync(globalCreds)
+    } catch (e) {
+      die(`could not remove ${globalCreds}: ${e?.message || e}`)
+    }
+    console.log("figs: ✓ logged out — removed ~/.figs/credentials.json")
+  } else {
+    console.log("figs: not logged in — no ~/.figs/credentials.json to remove")
+  }
+  if (process.env.FIGS_TOKEN) {
+    console.warn(
+      "figs: ! FIGS_TOKEN is still set in your environment — `unset FIGS_TOKEN` to fully log out",
+    )
+  }
+  console.log(
+    `        the token still exists server-side — revoke it at ${resolveEndpoint()}/settings`,
+  )
+}
+
 /** Show where setup stands — login, workspace, charter. Drives the agent's next step. */
 async function status() {
   const token = getToken()
   const cfg = readJson(join(repoDir, "config.json"), null)
   const hasAgent = existsSync(join(repoDir, "agent.json"))
+  const hasContract = existsSync(join(repoDir, "CONTRACT.md"))
   const endpoint = resolveEndpoint()
 
   let loggedIn = false
@@ -229,6 +264,7 @@ async function status() {
           workspaces: list?.map((w) => ({ id: w.id, name: w.name, role: w.role })),
           config: cfg ? { workspaceId: cfg.workspaceId, agentId: cfg.agentId } : null,
           agentJson: hasAgent,
+          contractMd: hasContract,
         },
         null,
         2,
@@ -255,7 +291,13 @@ async function status() {
       ? cfg.workspaceId
       : "not initialized — run `figs init --workspace <id>`",
   )
-  row("agent.json", hasAgent ? "present" : "missing — author .figs/agent.json")
+  row("agent.json", hasAgent ? "present (identity)" : "missing — author .figs/agent.json")
+  row(
+    "contract",
+    hasContract
+      ? "present (activity) — follow it"
+      : "none yet — Activity is optional, agree it with your user",
+  )
   row("endpoint", endpoint)
   row("cli", VERSION)
 }
@@ -286,31 +328,30 @@ function isUuid(s) {
 }
 
 /**
- * The local `.figs/GUIDE.md` is a thin, endpoint-relative pointer — the full,
- * always-current guide + `agent.json` schema is served at `${endpoint}/llms.txt`
- * (one source, no frozen copy to drift). Just enough here to act.
+ * The local `.figs/GUIDE.md` is a thin orientation breadcrumb (safe to
+ * regenerate) — the full, always-current guide + schema is served at
+ * `${endpoint}/llms.txt`, and the agent's own standing agreement lives in the
+ * precious, agent-authored `.figs/CONTRACT.md` (which `init` never touches).
  */
 function guideStub(endpoint) {
-  return `<!-- Written by \`figs init\`. Full, always-current guide + schema: ${endpoint}/llms.txt -->
-# Figs — quickstart for this agent
-
-You are an AI employee. **Figs** is the read-only window your manager uses to see what you're
-responsible for, what you've done, and what you need from them. You publish to it; it never
-writes back into this repo.
+  return `<!-- Written by \`figs init\` (safe to regenerate). Orientation only — the full
+     guide lives at the URL below; your own contract lives in CONTRACT.md. -->
+# Figs — this folder
 
-**Full guide + \`agent.json\` schema → ${endpoint}/llms.txt** — read this before authoring your charter.
+This repo publishes to **Figs** (your manager's read-only window into what you do).
 
-Lifecycle:
-  1. \`figs login\`                    a human approves in a browser — the token is theirs, never yours.
-  2. \`figs init --workspace <slug>\`  done — wrote config.json (your identity UUID) + this file.
-  3. author \`.figs/agent.json\`       derive it from this repo's CLAUDE.md / MEMORY.md, then \`figs doctor\`.
-  4. \`figs push\`                     you now appear in the org chart, self-described.
+- **Full guide + schema → ${endpoint}/llms.txt** — read this first.
+- **Your contract → ./CONTRACT.md** — what you publish / hold back (you + your user author it).
+- **Identity → config.json** (committed) · **charter → agent.json** (you write).
 
-Every run (wire this into your run loop, not a one-off):
-  append a line to runs.jsonl · record blockers in asks.jsonl · copy reports into artifacts/ · \`figs push\`.
+**Where are you?** You may be reading this at any time — don't assume you're starting fresh. Run
+\`figs status\` and check \`.figs/\` before acting:
+  • not set up yet → author \`.figs/agent.json\`, then \`figs doctor\` && \`figs push\` to appear (Identity).
+  • CONTRACT.md present → follow it; keep publishing what it says.
+  • no CONTRACT.md yet → agree with your user what work to surface (Activity) — see ${endpoint}/llms.txt.
 
-Commit config.json + agent.json (identity + charter). runs.jsonl / asks.jsonl / artifacts/ are a
-transient outbox — gitignored, aggregated remotely. The sync is one-way and never deletes on the server.
+Commit config.json + agent.json + CONTRACT.md + this file. runs.jsonl / asks.jsonl / artifacts/
+are a gitignored outbox. The token is the human's job — never generate one yourself.
 `
 }
 
@@ -355,7 +396,7 @@ async function init() {
     writeFileSync(
       giPath,
       [
-        "# Figs — commit config.json + agent.json (identity + charter).",
+        "# Figs — commit config.json + agent.json + CONTRACT.md + GUIDE.md.",
         "# Activity is a transient outbox: emitted per run, aggregated remotely.",
         "runs.jsonl",
         "asks.jsonl",
@@ -371,8 +412,9 @@ async function init() {
     `figs: ✓ .figs/config.json + .gitignore + GUIDE.md written (agentId ${agentId})`,
   )
   console.log(
-    `        read .figs/GUIDE.md (full guide: ${endpoint}/llms.txt), author .figs/agent.json, then \`figs doctor\`.`,
+    `        Phase 1: author .figs/agent.json (your charter), then \`figs doctor\` && \`figs push\` to appear.`,
   )
+  console.log(`        Full guide: ${endpoint}/llms.txt`)
 }
 
 /** Validate the local .figs/ payload against the contract — no write. */
@@ -445,8 +487,10 @@ async function push() {
  * The spine ingest is JSON-only; artifacts go to a separate endpoint that stores
  * them content-addressed (an unchanged file is skipped server-side). Content is
  * sent base64-encoded so any type — html, markdown, text, json, images — survives.
- * Files larger than ~3 MB are rejected by the server; compress images if needed.
- * Missing files are warned, not fatal.
+ * A **server rejection** (auth/size/etc.) is fatal: it prints ✗ and exits non-zero
+ * so the agent never believes a report published when it didn't (esp. the ~3 MB
+ * cap → 413). A **missing local file** is only a warning — that's the agent
+ * referencing an artifact it didn't actually produce, not a publish failure.
  */
 async function pushArtifacts(base, token, config, runs, asks) {
   const refNames = (asks ?? []).flatMap((a) =>
@@ -459,10 +503,13 @@ async function pushArtifacts(base, token, config, runs, asks) {
 
   let uploaded = 0
   let unchanged = 0
+  let missing = 0
+  let failed = 0
   for (const name of names) {
     const p = join(repoDir, "artifacts", name)
     if (!existsSync(p)) {
       console.warn(`figs: ! artifact missing, skipped: artifacts/${name}`)
+      missing++
       continue
     }
     const content = readFileSync(p).toString("base64")
@@ -477,8 +524,13 @@ async function pushArtifacts(base, token, config, runs, asks) {
       }),
     })
     if (!res.ok) {
-      const t = await res.text()
-      console.warn(`figs: ! artifact upload failed (${res.status}) ${name}: ${t}`)
+      const t = await res.text().catch(() => "")
+      const hint =
+        res.status === 413 ? " — too large (>3 MB); compress or split it" : ""
+      console.error(
+        `figs: ✗ artifact upload failed (${res.status}) ${name}${hint}${t ? `: ${t}` : ""}`,
+      )
+      failed++
       continue
     }
     const body = await res.json().catch(() => ({}))
@@ -486,8 +538,13 @@ async function pushArtifacts(base, token, config, runs, asks) {
     else uploaded++
   }
   console.log(
-    `figs: ✓ artifacts — ${uploaded} uploaded, ${unchanged} unchanged`,
+    `figs: ${failed ? "✗" : "✓"} artifacts — ${uploaded} uploaded, ${unchanged} unchanged` +
+      (missing ? `, ${missing} missing` : "") +
+      (failed ? `, ${failed} failed` : ""),
   )
+  // The spine already landed; signal a non-zero exit so an agent's run loop can
+  // catch that an artifact the manager needs to read did not publish.
+  if (failed) process.exit(1)
 }
 
 function readJsonl(name) {

package/package.json

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