flostep 0.1.4 → 0.1.5

package/README.md

@@ -51,9 +51,9 @@ Run `flostep syntax` for the authoritative version, fetched from the server.
 
 | Command | |
 | --- | --- |
-| `flostep login` | sign in from a browser (`--token` to paste a key instead) |
+| `flostep login` | sign in from a browser (`--read-only` for a key that can't change anything, `--token` to paste a key instead) |
 | `flostep logout` | forget the stored credentials |
-| `flostep whoami` | which account and workspace a key writes to |
+| `flostep whoami` | which account and workspace a key writes to, and whether it can write |
 | `flostep init` | add the agent instructions to AGENTS.md / CLAUDE.md / `.cursor/rules` |
 | `flostep list` | the diagrams in the workspace (`--folder` to narrow) |
 | `flostep show <id>` | print a diagram as steps (pipeable) |
@@ -90,7 +90,7 @@ Keeping the steps in a file and piping them in is up to you — the CLI tracks n
 
 | | |
 | --- | --- |
-| `FLOSTEP_TOKEN` | API key. Takes precedence over a stored login. |
+| `FLOSTEP_TOKEN` | API key. Takes precedence over a stored login. For a job that only reads, create a **Read only** key on the API keys page. |
 | `NO_COLOR` | Disable colour. Colour is off automatically when not a TTY. |
 
 Credentials are stored at `~/.config/flostep/config.json`, mode `0600`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flostep",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Build, update and share Flostep diagrams from the terminal, from CI, or from a coding agent.",
   "type": "module",
   "bin": {

package/src/api.js

@@ -21,6 +21,7 @@ export class Api {
     this.host = host;
     this.token = token;
     this.tokenSource = tokenSource;
+    this.keyAccess = null;
   }
 
   async request(method, path, body) {
@@ -50,6 +51,11 @@ export class Api {
       });
     }
 
+    // What the server says this key may do ("read" or "write"), from every
+    // authenticated response. Null against a server from before access levels,
+    // where every key could write — callers treat null as "don't know".
+    if (response.headers.has("x-key-access")) this.keyAccess = response.headers.get("x-key-access");
+
     // 204 has no body, and neither does anything that failed to serialise.
     const text = await response.text();
     let payload = null;
@@ -186,8 +192,10 @@ export class Api {
 
   // --- device flow ------------------------------------------------------
 
-  requestDeviceCode(clientName) {
-    return this.post("/api/v1/device/code", { client_name: clientName });
+  // `access: "read"` asks for a read-only key. Omitted otherwise, rather than
+  // sent as "write", so the request is byte-for-byte what older CLIs sent.
+  requestDeviceCode(clientName, { access } = {}) {
+    return this.post("/api/v1/device/code", { client_name: clientName, ...(access ? { access } : {}) });
   }
 
   // Polling is expected to fail most of the time — `authorization_pending` is

package/src/commands/list.js

@@ -38,9 +38,12 @@ export default {
     }
 
     if (diagrams.length === 0) {
-      out(dim(folder === undefined
-        ? "No diagrams yet. Create one with `echo 'A -> B: hello' | flostep create --title X --share`."
-        : "No diagrams in that folder."));
+      // The create hint is the obvious next step, except for a read-only key,
+      // which the server would refuse — so that key is told why instead.
+      const emptyLibrary = api.keyAccess === "read"
+        ? "No diagrams yet. This key is read-only, so it can't create one — use a read & write key."
+        : "No diagrams yet. Create one with `echo 'A -> B: hello' | flostep create --title X --share`.";
+      out(dim(folder === undefined ? emptyLibrary : "No diagrams in that folder."));
       return 0;
     }
 

package/src/commands/login.js

@@ -11,7 +11,7 @@
 
 import { hostname } from "node:os";
 
-import { CliError } from "../errors.js";
+import { CliError, UsageError } from "../errors.js";
 import { readConfig, writeConfig, resolveHost } from "../config.js";
 import { note, json, box, banner, fields, startSpinner, dim, bold, cyan, green } from "../output.js";
 import { Api } from "../api.js";
@@ -23,6 +23,7 @@ export default {
   name: "login",
   usage: [
     "flostep login",
+    "flostep login --read-only",
     "flostep login --token <fls_...>"
   ],
   details: [
@@ -31,15 +32,18 @@ export default {
   ],
   options: {
     token: { type: "string" },
-    "no-browser": { type: "boolean", default: false }
+    "no-browser": { type: "boolean", default: false },
+    "read-only": { type: "boolean", default: false }
   },
   optionHelp: [
+    ["--read-only", "ask for a key that can read diagrams but not change, delete or share them"],
     ["--token <fls_...>", "store a key you already have instead of opening a browser"],
     ["--no-browser", "print the URL rather than opening it"]
   ],
   examples: [
     ["flostep login", "approve in a browser on any device"],
     ["flostep login --no-browser", "for SSH sessions where nothing can open"],
+    ["flostep login --read-only", "for a machine that should only look"],
     ["FLOSTEP_TOKEN=fls_… flostep list", "CI needs no login at all — set the env var"]
   ],
 
@@ -48,10 +52,20 @@ export default {
 
     if (!ctx.json) banner();
 
+    // A pasted key already has whatever access it was created with; there is
+    // nothing this flag could change about it, and silently ignoring it would
+    // leave someone believing a write key was read-only.
+    if (values.token && values["read-only"]) {
+      throw new UsageError("--read-only applies to the browser login, not to a pasted key.", {
+        hint: "A key keeps the access it was created with — create a read-only one on the API keys page."
+      });
+    }
+
     if (values.token) return storeToken({ host, token: values.token.trim(), ctx });
 
+    const readOnly = values["read-only"];
     const api = ctx.api();
-    const grant = await api.requestDeviceCode(hostname());
+    const grant = await api.requestDeviceCode(hostname(), readOnly ? { access: "read" } : {});
 
     note();
     box([ `Your code:  ${bold(cyan(grant.user_code))}` ]);
@@ -74,6 +88,16 @@ export default {
       stopSpinner();
     }
 
+    // A server from before access levels ignores the request and mints a write
+    // key. Storing it would leave a credential that can change everything on a
+    // machine its owner asked to keep read-only, so it is refused instead — the
+    // key exists, though, and only the website can revoke it.
+    if (readOnly && token.access !== "read") {
+      throw new CliError("This Flostep server doesn't support read-only keys, so the key it created can write.", {
+        hint: `It was not saved. Revoke it on your API keys page (${host}/api-keys).`
+      });
+    }
+
     return storeToken({ host, token: token.token, expiresAt: token.expires_at, ctx });
   }
 };
@@ -139,7 +163,7 @@ async function storeToken({ host, token, expiresAt, ctx }) {
   const me = await new Api({ host, token }).me();
 
   if (ctx.json) {
-    json({ email: me.email, workspace: me.workspace, host, expires_at: expiresAt ?? null });
+    json({ email: me.email, workspace: me.workspace, access: me.access ?? null, host, expires_at: expiresAt ?? null });
     return 0;
   }
 
@@ -149,15 +173,35 @@ async function storeToken({ host, token, expiresAt, ctx }) {
   fields([
     [ "Account", me.email ],
     [ "Workspace", `${me.workspace.name}${me.workspace.team ? dim("  (team)") : ""}` ],
-    [ "Plan", me.workspace.plan ],
+    [ "Plan", formatPlan(me.workspace) ],
+    ...(me.access ? [ [ "Access", formatAccess(me.access) ] ] : []),
     ...(expiresAt ? [ [ "Expires", formatExpiry(expiresAt) ] ] : [])
   ]);
   note();
-  note(dim(`  Next:  ${cyan('echo "A -> B: hello" | flostep create --title "My flow" --share')}`));
-  note(dim("         steps go in on stdin, one per line — `flostep --help` for the rest."));
+  // The usual next step creates a diagram, which a read-only key would refuse.
+  if (me.access === "read") {
+    note(dim(`  Next:  ${cyan("flostep list")}`));
+    note(dim("         this key can read diagrams but not change them — `flostep --help` for the rest."));
+  } else {
+    note(dim(`  Next:  ${cyan('echo "A -> B: hello" | flostep create --title "My flow" --share')}`));
+    note(dim("         steps go in on stdin, one per line — `flostep --help` for the rest."));
+  }
   return 0;
 }
 
+// "team", or "team (complimentary until 10 Oct 2027)" while a comp is what's
+// paying for it — the billing page calls it Complimentary and states the end,
+// and a terminal saying only "team" would make that end a surprise.
+export function formatPlan(workspace) {
+  return workspace.comped_until
+    ? `${workspace.plan} (complimentary until ${formatExpiry(workspace.comped_until)})`
+    : workspace.plan;
+}
+
+export function formatAccess(access) {
+  return access === "read" ? "Read only" : "Read & write";
+}
+
 // A named month rather than toLocaleDateString()'s default, which renders
 // "28/11/2026" — unreadable without knowing whether the locale puts the day or
 // the month first, and this line is the one thing a person reads about how long

package/src/commands/whoami.js

@@ -1,6 +1,7 @@
 import { resolveToken } from "../config.js";
 import { CliError } from "../errors.js";
 import { out, json, dim, bold } from "../output.js";
+import { formatAccess, formatPlan } from "./login.js";
 
 export default {
   name: "whoami",
@@ -27,7 +28,9 @@ export default {
 
     out(`${bold(me.email)}${me.name && me.name !== me.email ? dim(`  (${me.name})`) : ""}`);
     out(`${dim("Workspace")}  ${me.workspace.name}${me.workspace.team ? dim("  (team)") : ""}`);
-    out(`${dim("Plan")}       ${me.workspace.plan}`);
+    out(`${dim("Plan")}       ${formatPlan(me.workspace)}`);
+    // Absent from servers before access levels, where every key could write.
+    if (me.access) out(`${dim("Access")}     ${formatAccess(me.access)}`);
     out(
       `${dim("Diagrams")}   ${
         me.diagrams_remaining === null ? "unlimited" : `${me.diagrams_remaining} remaining on this plan`