@figs-so/cli 0.1.3 → 0.1.5

package/figs.mjs

@@ -31,7 +31,7 @@ import { homedir } from "node:os"
 import { join } from "node:path"
 import { randomUUID } from "node:crypto"
 
-const VERSION = "0.1.3"
+const VERSION = "0.1.5"
 // 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"
@@ -197,6 +197,10 @@ 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")
@@ -207,6 +211,7 @@ 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 +234,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 +261,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 +298,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 +366,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 +382,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 +457,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 +473,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 +494,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 +508,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.5",
   "description": "Figs CLI — publish your AI agent's state to Figs (figs.so). Run by the agent.",
   "type": "module",
   "bin": {