flostep 0.1.0

package/AGENTS.md

@@ -0,0 +1,105 @@
+# Using Flostep from an agent
+
+Run `npx flostep init` at the root of your repository to write the block below into your agent's instruction files (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules`). Or paste it into your agent's context yourself — a system prompt, for instance — to let it build and share diagrams with a Bash tool alone.
+
+---
+
+## Flostep CLI
+
+Flostep makes diagrams people can **step through** one interaction at a time, share by link, or embed. Use it when the user wants a walkable, shareable diagram of how something works — a request crossing services, an approval chain, a customer journey. Not for class, ER, state or Gantt diagrams, and it does not emit markup to paste into a file.
+
+Run `npx flostep` (Node 20+). Authenticated via `FLOSTEP_TOKEN`, or `flostep login` for a browser flow.
+
+### Format
+
+One step per line, in the order it happens:
+
+```
+Frontend -> API: POST /login
+API -> Database: check credentials
+Database -> API: user record
+API -> Frontend: returns JWT
+```
+
+Components are created the first time they are named — reuse a name to reference the same box, and give genuinely different components different names. The `: description` is optional. Point a component at itself for internal work. Participants can be people, teams, or systems, not only software.
+
+Limits: 40 components, 120 steps. Run `flostep syntax` for the authoritative grammar.
+
+### Building a diagram
+
+Write the whole flow at once — atomic, and one call instead of eight. **Pipe it in; do not create files** in the user's repository unless they asked for a diagram that lives there:
+
+```bash
+npx flostep create --title "Checkout" --share <<'EOF'
+Customer -> API: POST /checkout
+API -> Payments: charge card
+API -> Customer: order confirmed
+EOF
+# ✓ Created #42 Checkout
+# https://flostep.dev/s/rEFdW8GSDwQ      <- give the user this
+```
+
+`--share` returns the public link in the same call. Add `--json` for a parseable result.
+
+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
+```
+
+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
+```
+
+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
+```
+
+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"
+```
+
+### Folders
+
+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 list --folder "Payments" --json
+```
+
+`flostep folder rename` and `flostep folder delete` exist too — ask before either; a delete un-files every diagram in it for the whole team, and needs `--yes` without a terminal.
+
+### 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
+```
+
+### Rules
+
+- **Read before you write.** `create`, `update`, `step` and `node` all replace the whole diagram; `show` first so you don't discard steps.
+- **Changes made since you read are protected.** `step` and `node` are refused if the diagram changed after they read it; for `update`, pass the `version` from `show --json` as `--if-version`. On a refusal, `show` again and redo your change on the current steps — never retry the same write.
+- **Don't leave files behind.** No command writes to disk. Redirect `show` yourself if the user asks for the steps in a file.
+- **Never invent a diagram id.** Get it from `list`, `create`, or the user.
+- **Exit codes**: `0` success, `1` error, `2` usage. Errors go to stderr with the reason.
+- **There is no `node add` and no `--type`.** The format cannot express an unconnected component or an explicit type — types are inferred from the name. Add a component by naming it in a step.
+- **Notes, positions and hand-drawn curves are not in the text format** and are dropped by any write. Say so if the user has them.
+- Ask before `delete`. It needs `--yes` when there's no terminal, and it cannot be undone.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flostep
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# flostep
+
+Build, update and share [Flostep](https://flostep.dev) diagrams from the terminal, from CI, or from a coding agent.
+
+Flostep turns ordered interactions into a diagram people can **step through** — one hop at a time, shared by link or embedded in a doc. This CLI builds one from a pipe and hands back the link, writing nothing to disk.
+
+```bash
+npx flostep create --title "Checkout" --share < flow.txt
+```
+
+No install needed. Requires Node 20 or newer.
+
+## Quick start
+
+```bash
+npx flostep login                        # approve in a browser
+
+npx flostep create --title "Checkout" --share <<'EOF'
+Customer -> API: POST /checkout
+API -> Payments: charge card
+API -> Customer: order confirmed
+EOF
+# ✓ Created #42 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
+```
+
+## The format
+
+One step per line, in the order it happens:
+
+```
+Customer -> API: POST /checkout
+API -> Payments: charge card
+Payments -> API: authorized
+API -> Customer: order confirmed
+```
+
+Components are created the first time they are named, so reusing a name references the same box. The `: description` is optional. Point a component at itself for internal work.
+
+Participants don't have to be software — a refund escalating from a customer to support to finance models exactly as well as a request crossing three services.
+
+Run `flostep syntax` for the authoritative version, fetched from the server.
+
+## Commands
+
+| Command | |
+| --- | --- |
+| `flostep login` | sign in from a browser (`--token` to paste a key instead) |
+| `flostep logout` | forget the stored credentials |
+| `flostep whoami` | which account and workspace a key writes to |
+| `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) |
+| `flostep create` | create from stdin, writing no files (`--share` for a link) |
+| `flostep update <id>` | replace a diagram's steps from stdin (`--if-version` to refuse if it changed) |
+| `flostep share <id>` | public link on/off (`--embed` for an iframe) |
+| `flostep open <id>` | open the editor in a browser |
+| `flostep delete <id>` | delete a diagram |
+| `flostep folder list\|create\|rename\|delete` | manage the workspace's folders |
+| `flostep move <id> <folder>` | file a diagram in a folder (`--none` to take it out) |
+| `flostep step add\|rm\|list` | edit individual steps |
+| `flostep node rename\|list` | rename or list components |
+| `flostep syntax` | print the step grammar |
+
+Every command takes `--json`. Exit codes are **0** success, **1** error, **2** usage.
+
+`flostep --help --json` prints the whole command and flag surface as JSON, derived from the command definitions themselves — useful for tooling, and what the hosted docs are tested against.
+
+Ids come from `flostep list` or from `create`. Nothing is resolved from a file path — diagrams live in your account, not in a checkout.
+
+## In CI
+
+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
+  env:
+    FLOSTEP_TOKEN: ${{ secrets.FLOSTEP_TOKEN }}
+```
+
+Keeping the steps in a file and piping them in is up to you — the CLI tracks nothing on disk. Exit codes make the step fail loudly: **1** on an error, **2** on a usage mistake.
+
+## Environment
+
+| | |
+| --- | --- |
+| `FLOSTEP_TOKEN` | API key. Takes precedence over a stored login. |
+| `NO_COLOR` | Disable colour. Colour is off automatically when not a TTY. |
+
+Credentials are stored at `~/.config/flostep/config.json`, mode `0600`.
+
+## For coding agents
+
+The CLI is designed to be driven by an agent with a Bash tool — no MCP client or per-tool config required. `--json` on every read command, errors on stderr, deterministic exit codes, and `flostep --help` is self-contained.
+
+To make an agent working in your repository find it on its own, run this at the repo root:
+
+```bash
+npx flostep init
+```
+
+It writes the block from [AGENTS.md](AGENTS.md) into every agent instruction file the repo already has — `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/flostep.mdc` — or creates `AGENTS.md` if there are none. The block sits between marker comments, so re-running it after an upgrade updates it in place and leaves the rest of the file alone. It lists the files and asks before writing when run in a terminal (`--yes` skips that); in CI or with `--json` it just writes. `--file <path>` picks the file yourself; `--print` writes it to stdout for a system prompt.
+
+## License
+
+MIT

package/bin/flostep.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin shim: everything real is in src/, so this file never needs changing and
+// the exit code is set in exactly one place.
+import { run } from "../src/cli.js";
+
+process.exitCode = await run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "flostep",
+  "version": "0.1.0",
+  "description": "Build, update and share Flostep diagrams from the terminal, from CI, or from a coding agent.",
+  "type": "module",
+  "bin": {
+    "flostep": "bin/flostep.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "flostep",
+    "diagram",
+    "sequence-diagram",
+    "architecture",
+    "diagrams-as-code",
+    "cli"
+  ],
+  "license": "MIT",
+  "homepage": "https://flostep.dev/docs",
+  "bugs": {
+    "email": "support@flostep.dev"
+  },
+  "author": "Flostep <support@flostep.dev>"
+}

package/src/api.js

@@ -0,0 +1,197 @@
+// The HTTP client. Zero dependencies — Node's own fetch is enough.
+//
+// The server's error strings are already written for people ("Free plan limit
+// of 3 diagrams reached. Delete one, or upgrade…"), so this deliberately passes
+// them through rather than re-wording them. Restating them here would mean two
+// copies of the same sentence drifting apart across a repo boundary, which is
+// the exact problem `flostep syntax` exists to avoid.
+
+import { CliError } from "./errors.js";
+import { USER_AGENT } from "./version.js";
+
+const TIMEOUT_MS = 30_000;
+
+// A ceiling on how many pages `listDiagrams` will follow — 5,000 diagrams at the
+// server's 100 a page. Far past any real library; it exists so a server that
+// misreports its total can't keep the loop going forever.
+const MAX_PAGES = 50;
+
+export class Api {
+  constructor({ host, token }) {
+    this.host = host;
+    this.token = token;
+  }
+
+  async request(method, path, body) {
+    return (await this.#send(method, path, body)).payload;
+  }
+
+  async #send(method, path, body) {
+    const headers = { Accept: "application/json", "User-Agent": USER_AGENT };
+    if (this.token) headers.Authorization = `Bearer ${this.token}`;
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+
+    let response;
+    try {
+      response = await fetch(`${this.host}${path}`, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(TIMEOUT_MS)
+      });
+    } catch (cause) {
+      // A refused connection and a wrong host look identical from here, and the
+      // host is the thing worth naming — it is usually a stale FLOSTEP_API_URL.
+      throw new CliError(`Could not reach ${this.host}.`, {
+        hint: cause?.name === "TimeoutError"
+          ? "The request timed out after 30s."
+          : "Check your connection."
+      });
+    }
+
+    // 204 has no body, and neither does anything that failed to serialise.
+    const text = await response.text();
+    let payload = null;
+    if (text) {
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        payload = null;
+      }
+    }
+
+    if (!response.ok) throw this.#toError(response, payload, path);
+    return { payload, response };
+  }
+
+  #toError(response, payload, path) {
+    const message = payload?.error;
+
+    if (response.status === 401) {
+      // The server distinguishes expired from invalid, and that distinction is
+      // the whole reason it does: "log in again" and "you copied it wrong" are
+      // different fixes. Passing its sentence through keeps them distinct.
+      return new CliError(message || "Not authenticated.", {
+        hint: this.token ? "Run `flostep login` to sign in again." : "Run `flostep login` first."
+      });
+    }
+
+    if (response.status >= 500) {
+      return new CliError(`Flostep returned ${response.status}.`, {
+        hint: "This is a problem on the server's side — try again shortly."
+      });
+    }
+
+    // The server's sentence says what happened; this says what to do. Not
+    // retried: the change was computed from a copy that is now out of date, so
+    // replaying it would be the very overwrite the check exists to stop.
+    if (response.status === 409) {
+      return new CliError(message || "The diagram changed since it was read.", {
+        hint: "Run `flostep show <id>` to see the current steps, then make your change again."
+      });
+    }
+
+    // The server says "Not Found", which is true and useless: it names neither
+    // what was missing nor where it looked. An id from another workspace — or
+    // from a local server, when the CLI is pointed at the public one — is the
+    // usual cause, and the host is the part that makes that obvious.
+    if (response.status === 404) {
+      const diagram = path.match(/\/diagrams\/(\d+)/)?.[1];
+      const folder = /\/folders\//.test(path);
+      const what = diagram ? `Diagram #${diagram}` : folder ? "That folder" : "That";
+      return new CliError(`${what} isn't on ${this.host}.`, {
+        hint: diagram
+          ? "Run `flostep list` to see the ids in this workspace."
+          : "Run `flostep folder list` to see what's there."
+      });
+    }
+
+    // 402 (subscription lapsed), 403 (plan limit) and 422 (bad steps) all
+    // arrive with a sentence written for the person reading it.
+    return new CliError(message || `Request failed (${response.status}).`);
+  }
+
+  get(path) { return this.request("GET", path); }
+  post(path, body) { return this.request("POST", path, body ?? {}); }
+  put(path, body) { return this.request("PUT", path, body ?? {}); }
+  del(path) { return this.request("DELETE", path); }
+
+  // --- diagrams ---------------------------------------------------------
+
+  // Every diagram, following the server's pages. The list used to be one
+  // request capped at 100 with nothing to say it had been cut, so a diagram
+  // past that simply didn't exist as far as an agent could tell.
+  async listDiagrams({ folder } = {}) {
+    const diagrams = [];
+
+    for (let page = 1; page <= MAX_PAGES; page++) {
+      const query = new URLSearchParams({ page: String(page) });
+      if (folder !== undefined) query.set("folder", String(folder));
+
+      const { payload, response } = await this.#send("GET", `/api/v1/diagrams?${query}`);
+      diagrams.push(...payload);
+
+      // A server from before paging sends no total and ignores `page` — asking
+      // for page 2 would return page 1 again — so no header means stop here.
+      const total = Number(response.headers.get("x-total-count"));
+      if (!response.headers.has("x-total-count") || payload.length === 0 || diagrams.length >= total) break;
+    }
+
+    return diagrams;
+  }
+  getDiagram(id) { return this.get(`/api/v1/diagrams/${encodeURIComponent(id)}`); }
+  createDiagram({ title, code }) { return this.post("/api/v1/diagrams", { title, code }); }
+  updateDiagram(id, body) { return this.put(`/api/v1/diagrams/${encodeURIComponent(id)}`, body); }
+  deleteDiagram(id) { return this.del(`/api/v1/diagrams/${encodeURIComponent(id)}`); }
+  shareDiagram(id) { return this.post(`/api/v1/diagrams/${encodeURIComponent(id)}/share`); }
+  unshareDiagram(id) { return this.del(`/api/v1/diagrams/${encodeURIComponent(id)}/share`); }
+  moveDiagram(id, folderId) {
+    return this.put(`/api/v1/diagrams/${encodeURIComponent(id)}/folder`, { folder_id: folderId });
+  }
+
+  // --- folders ----------------------------------------------------------
+
+  listFolders() { return this.get("/api/v1/folders"); }
+  createFolder(name) { return this.post("/api/v1/folders", { name }); }
+  renameFolder(id, name) { return this.put(`/api/v1/folders/${encodeURIComponent(id)}`, { name }); }
+  deleteFolder(id) { return this.del(`/api/v1/folders/${encodeURIComponent(id)}`); }
+
+  // Folders are addressed by name — it's what people say, and names are unique
+  // per workspace ignoring case — so the id the endpoints want is looked up
+  // here. An unknown name is an error naming the real folders, never an
+  // implicit create: that turns a misspelt "Paymnets" into a near-duplicate.
+  async findFolder(name) {
+    const { folders } = await this.listFolders();
+    const wanted = String(name).trim().toLowerCase();
+    const folder = folders.find((f) => f.name.toLowerCase() === wanted);
+    if (folder) return folder;
+
+    throw new CliError(`No folder named "${String(name).trim()}".`, {
+      hint: folders.length
+        ? `Existing folders: ${folders.map((f) => f.name).join(", ")}. Create one with \`flostep folder create\`.`
+        : "This workspace has no folders yet. Create one with `flostep folder create <name>`."
+    });
+  }
+
+  me() { return this.get("/api/v1/me"); }
+  syntax() { return this.get("/api/v1/syntax"); }
+
+  // --- device flow ------------------------------------------------------
+
+  requestDeviceCode(clientName) {
+    return this.post("/api/v1/device/code", { client_name: clientName });
+  }
+
+  // Polling is expected to fail most of the time — `authorization_pending` is
+  // the normal case — so this returns the payload instead of throwing, and the
+  // caller drives the state machine.
+  async pollDeviceToken(deviceCode) {
+    const response = await fetch(`${this.host}/api/v1/device/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json", "User-Agent": USER_AGENT },
+      body: JSON.stringify({ device_code: deviceCode }),
+      signal: AbortSignal.timeout(TIMEOUT_MS)
+    });
+    return response.json();
+  }
+}

package/src/browser.js

@@ -0,0 +1,46 @@
+// Opening a URL in the user's browser, best-effort.
+//
+// ⚠️ `spawn` does not throw when the opener is missing. It returns a child that
+// emits 'error' on a later tick, and with no listener that is an uncaught
+// exception — so the try/catch this used to sit in never fired, and `flostep
+// login` died with ENOENT on exactly the machines the device grant exists for
+// (a container, an SSH box, a minimal Linux image with no xdg-open), mid-spinner
+// and with the cursor still hidden. The fix is to listen for both outcomes and
+// resolve on whichever comes first: 'spawn' means the opener started, 'error'
+// means it never did.
+//
+// It never rejects. Every caller has already printed the URL or is about to,
+// so failing to open a browser is a fallback, not an error.
+
+import { spawn } from "node:child_process";
+
+// No shell anywhere. Windows used to go through `start` with `shell: true`,
+// where cmd.exe reads `&` in a URL as a command separator and treats the first
+// quoted argument as a window title. rundll32's URL handler takes the URL as a
+// plain argument.
+function opener(url) {
+  if (process.platform === "darwin") return ["open", [url]];
+  if (process.platform === "win32") return ["rundll32", ["url.dll,FileProtocolHandler", url]];
+  return ["xdg-open", [url]];
+}
+
+export function openBrowser(url) {
+  const [command, args] = opener(url);
+
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, args, { stdio: "ignore", detached: true });
+    } catch {
+      // Synchronous failures exist too (a malformed argument, EACCES on some
+      // platforms), so this stays alongside the listener rather than instead of it.
+      resolve(false);
+      return;
+    }
+    child.once("error", () => resolve(false));
+    child.once("spawn", () => {
+      child.unref();
+      resolve(true);
+    });
+  });
+}