flostep 0.1.3 → 0.1.5

package/AGENTS.md

@@ -35,7 +35,7 @@ Customer -> API: POST /checkout
 API -> Payments: charge card
 API -> Customer: order confirmed
 EOF
-# ✓ Created #42 Checkout
+# ✓ Created #Xk3p9QvA2wE Checkout
 # https://flostep.dev/s/rEFdW8GSDwQ      <- give the user this
 ```
 
@@ -44,36 +44,36 @@ EOF
 For a diagram that already exists, share it on its own:
 
 ```bash
-npx flostep share 42            # prints the public link
-npx flostep share 42 --embed    # iframe URL, for a docs page
+npx flostep share Xk3p9QvA2wE          # prints the public link
+npx flostep share Xk3p9QvA2wE --embed  # iframe URL, for a docs page
 ```
 
 GitHub strips iframes, so for a README, an ADR or a PR description print a markdown image that links to the diagram instead (paid plans; on a free one the command fails and gives you the plain link):
 
 ```bash
-npx flostep share 42 --markdown   # an image that follows the diagram as it changes
+npx flostep share Xk3p9QvA2wE --markdown  # an image that follows the diagram as it changes
 ```
 
 If the user keeps the steps in a file in their repo, pipe the file in and let them keep the file — the CLI tracks nothing on disk:
 
 ```bash
-npx flostep update 42 < docs/checkout.flostep
+npx flostep update Xk3p9QvA2wE < docs/checkout.flostep
 ```
 
 To rewrite an existing diagram, read it, transform it, pipe it back:
 
 ```bash
-npx flostep show 42 | sed 's/Redis/Session Cache/' | npx flostep update 42
+npx flostep show Xk3p9QvA2wE | sed 's/Redis/Session Cache/' | npx flostep update Xk3p9QvA2wE
 ```
 
 Or change one step at a time when you have no local file:
 
 ```bash
-npx flostep show 42                              # read it first
-npx flostep step add 42 "API -> Cache: read session"
-npx flostep step add 42 "Client -> API: retry" --at 3
-npx flostep step rm 42 5
-npx flostep node rename 42 "Redis" "Session Cache"
+npx flostep show Xk3p9QvA2wE  # read it first
+npx flostep step add Xk3p9QvA2wE "API -> Cache: read session"
+npx flostep step add Xk3p9QvA2wE "Client -> API: retry" --at 3
+npx flostep step rm Xk3p9QvA2wE 5
+npx flostep node rename Xk3p9QvA2wE "Redis" "Session Cache"
 ```
 
 ### Folders
@@ -81,9 +81,9 @@ npx flostep node rename 42 "Redis" "Session Cache"
 Folders are shared by a team and addressed by name. File a diagram only when the user asks you to organise it:
 
 ```bash
-npx flostep folder list --json            # names and diagram counts
-npx flostep folder create "Payments"      # returns the folder if it already exists
-npx flostep move 42 "Payments"            # file it; --none takes it out
+npx flostep folder list --json           # names and diagram counts
+npx flostep folder create "Payments"     # returns the folder if it already exists
+npx flostep move Xk3p9QvA2wE "Payments"  # file it; --none takes it out
 npx flostep list --folder "Payments" --json
 ```
 
@@ -92,11 +92,11 @@ npx flostep list --folder "Payments" --json
 ### Reading
 
 ```bash
-npx flostep list --json         # ids, titles, urls
-npx flostep show 42             # the steps, plain text
-npx flostep step list 42 --json # numbered steps
-npx flostep node list 42 --json # components, first-appearance order
-npx flostep whoami --json       # which workspace you're writing to
+npx flostep list --json                   # ids, titles, urls
+npx flostep show Xk3p9QvA2wE              # the steps, plain text
+npx flostep step list Xk3p9QvA2wE --json  # numbered steps
+npx flostep node list Xk3p9QvA2wE --json  # components, first-appearance order
+npx flostep whoami --json                 # which workspace you're writing to
 ```
 
 ### Rules

package/README.md

@@ -20,14 +20,14 @@ Customer -> API: POST /checkout
 API -> Payments: charge card
 API -> Customer: order confirmed
 EOF
-# ✓ Created #42 Checkout
+# ✓ Created #Xk3p9QvA2wE Checkout
 # https://flostep.dev/s/rEFdW8GSDwQ
 ```
 
 That wrote nothing to disk, and the id it printed is what every other command takes:
 
 ```bash
-npx flostep show 42 | sed 's/Payments/Stripe/' | npx flostep update 42
+npx flostep show Xk3p9QvA2wE | sed 's/Payments/Stripe/' | npx flostep update Xk3p9QvA2wE
 ```
 
 ## The format
@@ -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) |
@@ -79,7 +79,7 @@ Ids come from `flostep list` or from `create`. Nothing is resolved from a file p
 There is no browser in CI, so the device flow doesn't apply. Create a key at [flostep.dev/api_keys](https://flostep.dev/api_keys) — leave its expiry as **Never**, since a key that lapses takes the pipeline down on a date nobody chose — and set it as `FLOSTEP_TOKEN`.
 
 ```yaml
-- run: npx flostep update 42 < docs/checkout.flostep
+- run: npx flostep update Xk3p9QvA2wE < docs/checkout.flostep
   env:
     FLOSTEP_TOKEN: ${{ secrets.FLOSTEP_TOKEN }}
 ```
@@ -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.3",
+  "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/cli.js

@@ -110,7 +110,7 @@ function topLevelHelp() {
   const starters = [
     ["flostep login", "sign in from a browser"],
     ['echo "A -> B: hello" | flostep create --share', "steps on stdin, returns a link"],
-    ["flostep show 42 | flostep update 42", "read it, change it, write it back"],
+    ["flostep show Xk3p9QvA2wE | flostep update Xk3p9QvA2wE", "read it, change it, write it back"],
     ["flostep init", "teach this repo's coding agent to use flostep"]
   ];
   const starterWidth = Math.max(...starters.map(([command]) => command.length));

package/src/commands/create.js

@@ -12,7 +12,7 @@ export default {
   name: "create",
   usage: [
     'flostep create [--title <title>] [--share] < steps.txt',
-    'flostep show 42 | flostep create --title "Copy"'
+    'flostep show Xk3p9QvA2wE | flostep create --title "Copy"'
   ],
   details: [
     "Reads steps from stdin and creates a diagram. Writes no files.",

package/src/commands/delete.js

@@ -13,8 +13,8 @@ export default {
   options: { yes: { type: "boolean", short: "y", default: false } },
   optionHelp: [["-y, --yes", "skip the confirmation prompt"]],
   examples: [
-    ["flostep delete 15"],
-    ["flostep delete 15 --yes", "for scripts and agents"]
+    ["flostep delete Xk3p9QvA2wE"],
+    ["flostep delete Xk3p9QvA2wE --yes", "for scripts and agents"]
   ],
 
   async run({ positionals, values, ctx }) {

package/src/commands/list.js

@@ -38,14 +38,17 @@ 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;
     }
 
     table(diagrams, [
-      ["ID", (d) => d.id, "right"],
+      ["ID", (d) => d.id],
       ["TITLE", (d) => d.title],
       ["FOLDER", (d) => d.folder ?? ""],
       ["UPDATED", (d) => relativeTime(d.updated_at)],

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/move.js

@@ -17,8 +17,8 @@ export default {
   options: { none: { type: "boolean", default: false } },
   optionHelp: [["--none", "take the diagram out of its folder (uncategorized)"]],
   examples: [
-    ['flostep move 42 "Payments"'],
-    ["flostep move 42 --none"]
+    ['flostep move Xk3p9QvA2wE "Payments"'],
+    ["flostep move Xk3p9QvA2wE --none"]
   ],
 
   async run({ positionals, values, ctx }) {

package/src/commands/node.js

@@ -7,7 +7,7 @@
 // way to express a type — the server infers that from the name. A `--type cache`
 // flag would be discarded on the next write, which is worse than not offering it.
 //
-// To add a component, name it in a step: `flostep step add 15 "API -> Redis: read"`.
+// To add a component, name it in a step: `flostep step add Xk3p9QvA2wE "API -> Redis: read"`.
 
 
 import { UsageError } from "../errors.js";
@@ -29,9 +29,9 @@ export default {
     "Types (service, database, person…) are inferred from the name by the server."
   ],
   examples: [
-    ["flostep node list 15"],
-    ['flostep node rename 15 "Redis" "Session Cache"'],
-    ["flostep node list 15 --json", "components in first-appearance order"]
+    ["flostep node list Xk3p9QvA2wE"],
+    ['flostep node rename Xk3p9QvA2wE "Redis" "Session Cache"'],
+    ["flostep node list Xk3p9QvA2wE --json", "components in first-appearance order"]
   ],
 
   async run({ positionals, ctx }) {

package/src/commands/open.js

@@ -7,8 +7,8 @@ export default {
   usage: "flostep open <id>",
   details: ["Opens the diagram in the editor in your default browser."],
   examples: [
-    ["flostep open 15"],
-    ["flostep open 15 --json", "the url, and whether a browser started"]
+    ["flostep open Xk3p9QvA2wE"],
+    ["flostep open Xk3p9QvA2wE --json", "the url, and whether a browser started"]
   ],
 
   async run({ positionals, ctx }) {

package/src/commands/share.js

@@ -48,10 +48,10 @@ export default {
     ["--markdown", "print a markdown image that links to the diagram (paid plans)"]
   ],
   examples: [
-    ["flostep share 15"],
-    ["flostep share 42 --embed", "for a docs page or Confluence"],
-    ["flostep share 42 --markdown", "for a GitHub README; follows the diagram"],
-    ["flostep share 15 --off"]
+    ["flostep share Xk3p9QvA2wE"],
+    ["flostep share Xk3p9QvA2wE --embed", "for a docs page or Confluence"],
+    ["flostep share Xk3p9QvA2wE --markdown", "for a GitHub README; follows the diagram"],
+    ["flostep share Xk3p9QvA2wE --off"]
   ],
 
   async run({ positionals, values, ctx }) {

package/src/commands/show.js

@@ -6,12 +6,12 @@ export default {
   usage: "flostep show <id>",
   details: [
     "Prints the diagram as steps, and nothing else, so it pipes cleanly:",
-    "  flostep show 15 > docs/checkout.flostep"
+    "  flostep show Xk3p9QvA2wE > docs/checkout.flostep"
   ],
   examples: [
-    ["flostep show 15"],
-    ["flostep show 42 > docs/checkout.flostep", "redirect it yourself if you want a file"],
-    ["flostep show 15 --json", "with the title and url alongside the code"]
+    ["flostep show Xk3p9QvA2wE"],
+    ["flostep show Xk3p9QvA2wE > docs/checkout.flostep", "redirect it yourself if you want a file"],
+    ["flostep show Xk3p9QvA2wE --json", "with the title and url alongside the code"]
   ],
 
   async run({ positionals, ctx }) {

package/src/commands/step.js

@@ -28,10 +28,10 @@ export default {
   options: { at: { type: "string" } },
   optionHelp: [["--at <n>", "insert before step n instead of appending"]],
   examples: [
-    ['flostep step add 15 "API -> Cache: read session"'],
-    ['flostep step add 15 "Client -> API: retry" --at 3'],
-    ["flostep step list 15 --json"],
-    ["flostep step rm 15 4"]
+    ['flostep step add Xk3p9QvA2wE "API -> Cache: read session"'],
+    ['flostep step add Xk3p9QvA2wE "Client -> API: retry" --at 3'],
+    ["flostep step list Xk3p9QvA2wE --json"],
+    ["flostep step rm Xk3p9QvA2wE 4"]
   ],
 
   async run({ positionals, values, ctx }) {

package/src/commands/update.js

@@ -1,7 +1,7 @@
 // `flostep update` — replace a diagram's steps from a pipe.
 //
 // The counterpart to `create`, and the composable half of the tool:
-//   flostep show 42 | sed 's/Redis/Session Cache/' | flostep update 42
+//   flostep show Xk3p9QvA2wE | sed 's/Redis/Session Cache/' | flostep update Xk3p9QvA2wE
 
 import { readStdin } from "../stdin.js";
 import { UsageError } from "../errors.js";
@@ -14,7 +14,7 @@ export default {
   name: "update",
   usage: [
     "flostep update <id> [--title <title>] [--if-version <n>] < steps.txt",
-    "flostep show 42 | flostep update 42"
+    "flostep show Xk3p9QvA2wE | flostep update Xk3p9QvA2wE"
   ],
   details: [
     "Reads steps from stdin and replaces every step in the diagram.",
@@ -31,15 +31,15 @@ export default {
     ["--if-version <n>", "only write if the diagram is still at this version"]
   ],
   examples: [
-    ["flostep show 42 | sed 's/Redis/Cache/' | flostep update 42"],
-    ["flostep update 42 < revised.txt"],
-    ["flostep update 42 --if-version 7 < revised.txt", "refused if it changed since version 7"]
+    ["flostep show Xk3p9QvA2wE | sed 's/Redis/Cache/' | flostep update Xk3p9QvA2wE"],
+    ["flostep update Xk3p9QvA2wE < revised.txt"],
+    ["flostep update Xk3p9QvA2wE --if-version 7 < revised.txt", "refused if it changed since version 7"]
   ],
 
   async run({ positionals, values, ctx }) {
     const { id } = resolveTarget(positionals[0]);
     const version = parseVersion(values["if-version"]);
-    const input = await readStdin({ what: "`flostep update 42 < flow.txt`" });
+    const input = await readStdin({ what: "`flostep update Xk3p9QvA2wE < flow.txt`" });
     const { code, summary } = diagramFromStdin(input);
 
     const body = { code };

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`

package/src/target.js

@@ -1,4 +1,4 @@
-// Turning "15" into a diagram id.
+// Turning "Xk3_p9QvA2w" into a diagram id.
 //
 // Every command that acts on one diagram takes an id, and only an id. Diagrams
 // live in the account, not in a checkout: `create` and `update` read steps from
@@ -7,10 +7,13 @@
 
 import { UsageError } from "./errors.js";
 
-// A bare positive integer. Ids come from `flostep list`, from `create`, or
-// from the user — never from a guess.
+// Any URL-safe token. Ids are random strings now; the integers servers used to
+// hand out still resolve, so they pass too. This deliberately doesn't pin the
+// server's exact format — when ids were checked as digits-only, changing the
+// format would have broken every installed CLI. A wrong id is the server's 404
+// to report; what this catches is a title passed where the id goes.
 export function looksLikeId(ref) {
-  return /^[1-9][0-9]*$/.test(String(ref).trim());
+  return /^[A-Za-z0-9_-]+$/.test(String(ref).trim());
 }
 
 // Usage errors, not CliErrors: a missing or malformed id is the caller getting
@@ -25,9 +28,9 @@ export function resolveTarget(ref) {
 
   if (!looksLikeId(ref)) {
     throw new UsageError(`"${ref}" is not a diagram id.`, {
-      hint: "Ids are numbers — run `flostep list` to see them."
+      hint: "Pass the ID column from `flostep list`, not the title."
     });
   }
 
-  return { id: Number(ref) };
+  return { id: String(ref).trim() };
 }