flostep 0.1.0

package/src/commands/step.js

@@ -0,0 +1,129 @@
+// `flostep step` — edit one step of an existing diagram without a local file.
+//
+// This is the shape an agent works in: it has a diagram id and one thing to
+// change, not a checkout. Everything here is read-modify-write over the same
+// two endpoints `show` and `update` use — GET the code, transform the text, PUT it back —
+// so there is no second way for a diagram to be written and nothing new to keep
+// in sync on the server.
+
+
+import { UsageError } from "../errors.js";
+import { out, ok, table, json, dim } from "../output.js";
+import { resolveTarget } from "../target.js";
+import { addStep, removeStep, parseSteps, formatStep } from "../code.js";
+
+const SUBCOMMANDS = ["add", "rm", "list"];
+
+export default {
+  name: "step",
+  usage: [
+    'flostep step add <id> "From -> To: what happens" [--at <n>]',
+    "flostep step rm <id> <n>",
+    "flostep step list <id> [--json]"
+  ],
+  details: [
+    "Steps are numbered from 1, matching the badges on the canvas.",
+    "Components are created by being named, so `step add` is also how a box appears."
+  ],
+  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"]
+  ],
+
+  async run({ positionals, values, ctx }) {
+    const [subcommand, ref, ...rest] = positionals;
+
+    if (!SUBCOMMANDS.includes(subcommand)) {
+      throw new UsageError(
+        subcommand ? `Unknown subcommand "step ${subcommand}".` : "Which action? add, rm or list.",
+        { usage: this.usage.join("\n       ") }
+      );
+    }
+
+    const target = resolveTarget(ref);
+    const api = ctx.api();
+    const diagram = await api.getDiagram(target.id);
+
+    if (subcommand === "list") return list({ diagram, ctx });
+
+    const updated =
+      subcommand === "add"
+        ? applyAdd({ code: diagram.code, text: rest.join(" "), at: values.at })
+        : applyRemove({ code: diagram.code, n: rest[0] });
+
+    // The version from the read above, so a change made in between (in the
+    // browser, by a teammate, by another agent) is refused rather than erased.
+    await api.updateDiagram(target.id, { code: updated, version: diagram.version });
+
+    if (ctx.json) {
+      json({ id: diagram.id, title: diagram.title, code: updated, steps: parseSteps(updated).length });
+      return 0;
+    }
+
+    const count = parseSteps(updated).length;
+    ok(
+      subcommand === "add"
+        ? `Added step to #${diagram.id} ${dim(`(${count} steps)`)}`
+        : `Removed step ${rest[0]} from #${diagram.id} ${dim(`(${count} steps)`)}`
+    );
+    return 0;
+  }
+};
+
+function applyAdd({ code, text, at }) {
+  if (!text.trim()) {
+    throw new UsageError('What step? Pass it in quotes: "From -> To: what happens".', {
+      usage: 'flostep step add <id> "From -> To: what happens"'
+    });
+  }
+
+  let position;
+  if (at !== undefined) {
+    position = Number(at);
+    if (!Number.isInteger(position)) {
+      throw new UsageError("--at takes a step number.", { usage: "flostep step add <id> <step> --at <n>" });
+    }
+  }
+
+  // code.js raises plain Errors with sentences already written for a reader;
+  // cli.js prints them and exits 1.
+  return addStep(code, text, { at: position });
+}
+
+function applyRemove({ code, n }) {
+  const index = Number(n);
+  if (!Number.isInteger(index)) {
+    throw new UsageError("Which step? Pass its number — see `flostep step list`.", {
+      usage: "flostep step rm <id> <n>"
+    });
+  }
+  return removeStep(code, index);
+}
+
+
+function list({ diagram, ctx }) {
+  const steps = parseSteps(diagram.code);
+
+  if (ctx.json) {
+    json(steps.map(({ from, to, label }, i) => ({ n: i + 1, from, to, label })));
+    return 0;
+  }
+
+  if (steps.length === 0) {
+    out(dim("No steps yet."));
+    return 0;
+  }
+
+  table(
+    steps.map((step, i) => ({ ...step, n: i + 1 })),
+    [
+      ["#", (s) => s.n, "right"],
+      ["STEP", (s) => formatStep(s)]
+    ]
+  );
+  return 0;
+}

package/src/commands/syntax.js

@@ -0,0 +1,17 @@
+import { out } from "../output.js";
+
+export default {
+  name: "syntax",
+  usage: "flostep syntax",
+  details: [
+    "Prints the step grammar, fetched from the server rather than hard-coded here,",
+    "so it can't drift from what the parser actually accepts."
+  ],
+  examples: [["flostep syntax", "the format `create`, `update` and `step add` expect"]],
+
+  async run({ ctx }) {
+    const { syntax } = await ctx.api().syntax();
+    out(syntax);
+    return 0;
+  }
+};

package/src/commands/update.js

@@ -0,0 +1,71 @@
+// `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
+
+import { readStdin } from "../stdin.js";
+import { UsageError } from "../errors.js";
+import { out, ok, json, dim } from "../output.js";
+import { resolveTarget } from "../target.js";
+import { parseSteps } from "../code.js";
+import { diagramFromStdin, describe } from "../source.js";
+
+export default {
+  name: "update",
+  usage: [
+    "flostep update <id> [--title <title>] [--if-version <n>]",
+    "flostep show 42 | flostep update 42"
+  ],
+  details: [
+    "Reads steps from stdin and replaces every step in the diagram.",
+    "Read it first — this discards whatever was there.",
+    "Pass the `version` from `flostep show <id> --json` as --if-version, and the",
+    "write is refused if anyone changed the diagram since you read it."
+  ],
+  options: {
+    title: { type: "string" },
+    "if-version": { type: "string" }
+  },
+  optionHelp: [
+    ["--title <title>", "also rename the diagram"],
+    ["--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"]
+  ],
+
+  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 { code, summary } = diagramFromStdin(input);
+
+    const body = { code };
+    if (values.title) body.title = values.title;
+    if (version !== undefined) body.version = version;
+    const diagram = await ctx.api().updateDiagram(id, body);
+
+    if (ctx.json) {
+      json({ ...diagram, steps: parseSteps(code).length });
+      return 0;
+    }
+
+    ok(`Updated #${diagram.id} ${dim(`(${describe(summary)})`)}`);
+    out(diagram.url);
+    return 0;
+  }
+};
+
+// Checked before stdin is read, so a typo fails as usage (exit 2) without
+// consuming the pipe.
+function parseVersion(raw) {
+  if (raw === undefined) return undefined;
+  if (!/^(0|[1-9][0-9]*)$/.test(raw.trim())) {
+    throw new UsageError("--if-version takes the number from `flostep show <id> --json`.", {
+      usage: "flostep update <id> --if-version <n>"
+    });
+  }
+  return Number(raw);
+}

package/src/commands/whoami.js

@@ -0,0 +1,39 @@
+import { resolveToken } from "../config.js";
+import { CliError } from "../errors.js";
+import { out, json, dim, bold } from "../output.js";
+
+export default {
+  name: "whoami",
+  usage: "flostep whoami",
+  details: [
+    "A key belongs to you but acts on the whole workspace — anything it creates",
+    "belongs to the team. This is how you check which library you're writing to."
+  ],
+  examples: [
+    ["flostep whoami"],
+    ["flostep whoami --json", "for scripts and agents"]
+  ],
+
+  async run({ ctx }) {
+    const { token, source } = resolveToken();
+    if (!token) throw new CliError("Not logged in.", { hint: "Run `flostep login` first." });
+
+    const me = await ctx.api().me();
+
+    if (ctx.json) {
+      json({ ...me, credential_source: source });
+      return 0;
+    }
+
+    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("Diagrams")}   ${
+        me.diagrams_remaining === null ? "unlimited" : `${me.diagrams_remaining} remaining on this plan`
+      }`
+    );
+    out(dim(`Authenticated from ${source === "FLOSTEP_TOKEN" ? "$FLOSTEP_TOKEN" : "the stored login"}.`));
+    return 0;
+  }
+};

package/src/config.js

@@ -0,0 +1,67 @@
+// Where the CLI remembers who you are between runs.
+//
+// The environment always wins over the file. That ordering is what lets one
+// machine be logged in as a person and still run a CI-shaped command against a
+// service token without logging out first — and it is the only path that works
+// in CI, where there is no browser to complete a device flow.
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdirSync, readFileSync, writeFileSync, rmSync, existsSync } from "node:fs";
+
+export const DEFAULT_HOST = "https://flostep.dev";
+
+// XDG first, so anyone who has moved their config directory is respected;
+// ~/.config is the fallback rather than ~/.flostep because a dotfile per tool
+// in the home directory is what XDG exists to stop.
+function configDir() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(base, "flostep");
+}
+
+export function configPath() {
+  return join(configDir(), "config.json");
+}
+
+export function readConfig() {
+  try {
+    return JSON.parse(readFileSync(configPath(), "utf8"));
+  } catch {
+    // Missing is the normal case before the first login, and unreadable or
+    // corrupt is recovered by logging in again — neither is worth an error the
+    // user has to act on.
+    return {};
+  }
+}
+
+export function writeConfig(config) {
+  mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+  // The file holds a bearer token with full workspace read/write, so it is
+  // written 0600 rather than left at the umask default. mode: on writeFileSync
+  // only applies when the file is created, so chmod-on-every-write is deliberate
+  // — an existing file created before this rule still gets tightened.
+  writeFileSync(configPath(), JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+}
+
+export function clearConfig() {
+  if (existsSync(configPath())) rmSync(configPath());
+}
+
+// FLOSTEP_TOKEN wins. In CI it is the only credential there is.
+export function resolveToken() {
+  const fromEnv = process.env.FLOSTEP_TOKEN?.trim();
+  if (fromEnv) return { token: fromEnv, source: "FLOSTEP_TOKEN" };
+
+  const { token } = readConfig();
+  return token ? { token, source: "config" } : { token: null, source: null };
+}
+
+// FLOSTEP_API_URL is deliberately undocumented: there is one Flostep server,
+// and the variable exists for developing against a local one and for the
+// tests. The stored host is next, so a login against localhost keeps working
+// for the rest of that session without the variable set.
+export function resolveHost() {
+  const host = process.env.FLOSTEP_API_URL || readConfig().host || DEFAULT_HOST;
+
+  return host.replace(/\/+$/, "");
+}

package/src/errors.js

@@ -0,0 +1,26 @@
+// Two failure kinds, because they mean different things to whoever is reading.
+//
+// A UsageError is the caller getting the command wrong — it prints the usage
+// line and exits 2. A CliError is the command being right and the world being
+// wrong (no network, no permission, diagram not found) — it prints the message
+// and exits 1. Scripts and agents branch on that difference; a single exit code
+// for both would make "I typo'd the flag" indistinguishable from "the diagram
+// is gone".
+
+export class CliError extends Error {
+  constructor(message, { hint } = {}) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = 1;
+    this.hint = hint;
+  }
+}
+
+export class UsageError extends Error {
+  constructor(message, { usage } = {}) {
+    super(message);
+    this.name = "UsageError";
+    this.exitCode = 2;
+    this.usage = usage;
+  }
+}

package/src/instructions.js

@@ -0,0 +1,121 @@
+// Writing the AGENTS.md block into someone else's repository.
+//
+// The block is the half of AGENTS.md below its `---` rule, read from the file
+// this package ships, so `flostep init` and the copy-paste instructions can't
+// drift apart.
+//
+// It goes between marker comments. Re-running `init` after an upgrade replaces
+// what is between them and nothing else — the file around it is the user's, and
+// appending a second copy on every run would be worse than doing nothing.
+
+import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BEGIN = "<!-- flostep:begin — managed by `npx flostep init`; re-run it to update -->";
+const END = "<!-- flostep:end -->";
+const MANAGED = /<!-- flostep:begin[^>]*-->[\s\S]*?<!-- flostep:end -->/;
+
+// What a hand-pasted copy of the block looks like. Its presence without the
+// markers means someone already did this by hand, and adding a second copy
+// would leave the agent reading the instructions twice.
+const PASTED = /^## Flostep CLI\s*$/m;
+
+const CURSOR_FRONTMATTER = [
+  "---",
+  "description: Flostep CLI — build, update and share step-through diagrams of how something works",
+  "alwaysApply: false",
+  "---",
+  ""
+].join("\n");
+
+export function agentBlock(source = join(dirname(fileURLToPath(import.meta.url)), "..", "AGENTS.md")) {
+  const text = readFileSync(source, "utf8").replace(/\r\n/g, "\n");
+  const rule = text.search(/^---$/m);
+  if (rule === -1) throw new Error(`${source} has no \`---\` separating the preamble from the block.`);
+  return text.slice(rule + 3).trim();
+}
+
+// Same walk as the manifest: the repo root if there is one, otherwise where the
+// command was run.
+export function projectRoot(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  for (;;) {
+    if (existsSync(join(dir, ".git"))) return dir;
+
+    const parent = dirname(dir);
+    if (parent === dir) return resolve(startDir);
+    dir = parent;
+  }
+}
+
+const isFile = (path) => existsSync(path) && statSync(path).isFile();
+const isDir = (path) => existsSync(path) && statSync(path).isDirectory();
+
+// Every instruction file the repo already has, because a team using both Claude
+// Code and Cursor wants flostep discoverable from both. AGENTS.md is the
+// fallback when there are none — it's the one read by the most tools.
+export function detectTargets(root) {
+  const agents = join(root, "AGENTS.md");
+  const claude = join(root, "CLAUDE.md");
+  const cursorRules = join(root, ".cursor", "rules");
+
+  const targets = [];
+  if (isFile(agents)) targets.push(agents);
+
+  // A CLAUDE.md that imports AGENTS.md already sees the block; writing it into
+  // both would put it in the context twice.
+  if (isFile(claude) && !(isFile(agents) && /^\s*@AGENTS\.md\b/m.test(readFileSync(claude, "utf8")))) {
+    targets.push(claude);
+  }
+
+  if (isDir(cursorRules)) targets.push(join(cursorRules, "flostep.mdc"));
+
+  return targets.length > 0 ? targets : [ agents ];
+}
+
+// Pure, so every case is testable without touching disk. Returns the new
+// contents and what happened; `contents` is null when nothing should be written.
+export function applyBlock(existing, block, { cursor = false } = {}) {
+  const eol = existing?.includes("\r\n") ? "\r\n" : "\n";
+  const managed = `${BEGIN}\n${block}\n${END}`.replace(/\n/g, eol);
+
+  if (existing == null) {
+    const prefix = cursor ? CURSOR_FRONTMATTER : "";
+    return { action: "created", contents: `${prefix}${managed}\n` };
+  }
+
+  if (MANAGED.test(existing)) {
+    // A function replacement, so a `$` in the block isn't read as a pattern.
+    const contents = existing.replace(MANAGED, () => managed);
+    return contents === existing
+      ? { action: "unchanged", contents: null }
+      : { action: "updated", contents };
+  }
+
+  if (PASTED.test(existing)) return { action: "skipped", contents: null };
+
+  // One blank line between the user's content and the block, however their
+  // file happened to end.
+  const separator =
+    existing.trim() === "" ? "" : existing.endsWith(eol + eol) ? "" : existing.endsWith(eol) ? eol : eol + eol;
+  return { action: "appended", contents: `${existing}${separator}${managed}${eol}` };
+}
+
+// Split from writing so `init` can show what it's about to change and ask first.
+export function planBlock(path, block) {
+  const existing = isFile(path) ? readFileSync(path, "utf8") : null;
+  return { path, ...applyBlock(existing, block, { cursor: path.endsWith(".mdc") }) };
+}
+
+export function commitPlan({ path, contents }) {
+  if (contents == null) return;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, contents);
+}
+
+export function writeBlock(path, block) {
+  const plan = planBlock(path, block);
+  commitPlan(plan);
+  return plan.action;
+}

package/src/output.js

@@ -0,0 +1,170 @@
+// Printing, in two registers: one for a person at a terminal, one for whatever
+// is parsing this.
+//
+// Everything an agent or a script needs goes to stdout as JSON under --json;
+// everything a person needs goes to stdout as text. Errors and progress always
+// go to stderr, so `flostep show 15 > flow.flostep` writes only the diagram
+// even while the command is chattering about what it's doing.
+
+const useColor =
+  process.stdout.isTTY &&
+  !process.env.NO_COLOR &&
+  process.env.TERM !== "dumb";
+
+// Written as an escape rather than a literal control byte, so the source
+// stays greppable and survives anything that strips them.
+const ESC = "\u001b";
+const wrap = (code) => (text) => (useColor ? `${ESC}[${code}m${text}${ESC}[0m` : text);
+
+export const dim = wrap("2");
+export const bold = wrap("1");
+export const green = wrap("32");
+export const red = wrap("31");
+export const cyan = wrap("36");
+export const yellow = wrap("33");
+
+// `flostep show 42 | head -5` closes the pipe while the CLI is still writing,
+// and Node turns that into an unhandled 'error' event — a stack trace and a
+// non-zero exit for what is a completely ordinary shell idiom. Every tool that
+// can be piped has to say this; the shell convention is to stop quietly.
+for (const stream of [ process.stdout, process.stderr ]) {
+  stream.on("error", (error) => {
+    if (error.code === "EPIPE") process.exit(0);
+    throw error;
+  });
+}
+
+export function out(line = "") {
+  process.stdout.write(`${line}\n`);
+}
+
+// Progress and status go to stderr so that piping stdout gives you only the
+// payload — `flostep show 15 > flow.flostep` must not capture "✓ Fetched".
+export function note(line = "") {
+  process.stderr.write(`${line}\n`);
+}
+
+export function ok(message) {
+  note(`${green("✓")} ${message}`);
+}
+
+export function warn(message) {
+  note(`${yellow("!")} ${message}`);
+}
+
+export function fail(message, hint) {
+  note(`${red("✗")} ${message}`);
+  if (hint) note(`  ${dim(hint)}`);
+}
+
+export function json(value) {
+  out(JSON.stringify(value, null, 2));
+}
+
+// Columns are [header, accessor, align?]. Widths are measured, so a long title
+// doesn't push the rest out of true.
+export function table(rows, columns) {
+  if (rows.length === 0) return;
+
+  const cells = rows.map((row) => columns.map(([, get]) => String(get(row) ?? "")));
+  const widths = columns.map(([header], i) =>
+    Math.max(header.length, ...cells.map((row) => row[i].length))
+  );
+
+  const render = (values, style = (s) => s) =>
+    out(
+      values
+        .map((value, i) =>
+          style(columns[i][2] === "right" ? value.padStart(widths[i]) : value.padEnd(widths[i]))
+        )
+        .join("  ")
+        .trimEnd()
+    );
+
+  render(columns.map(([header]) => header), dim);
+  cells.forEach((row) => render(row));
+}
+
+// Full timestamps are noise in a table; no timestamp at all is useless. This is
+// coarse on purpose — the question a list answers is "which did I touch last?"
+export function relativeTime(iso) {
+  if (!iso) return "";
+
+  const seconds = Math.floor((Date.now() - new Date(iso).getTime()) / 1000);
+  if (seconds < 60) return "just now";
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`;
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ago`;
+  return `${Math.floor(seconds / 86400)}d ago`;
+}
+
+// Width ignoring colour codes, so a styled string still measures as what the
+// eye sees. Everything that aligns or boxes text has to go through this.
+function visibleLength(text) {
+  return text.replace(/\u001b\[[0-9;]*m/g, "").length;
+}
+
+// A rounded box, drawn to stderr. Used for the one thing in a login someone has
+// to read off the screen and retype — a code buried in a paragraph gets
+// mistyped, and the box is what makes it findable at a glance.
+export function box(lines, { indent = "  " } = {}) {
+  const width = Math.max(...lines.map(visibleLength)) + 4;
+  const bar = "─".repeat(width);
+
+  note(`${indent}${dim("╭" + bar + "╮")}`);
+  for (const line of lines) {
+    const padding = " ".repeat(width - visibleLength(line) - 4);
+    note(`${indent}${dim("│")}  ${line}${padding}  ${dim("│")}`);
+  }
+  note(`${indent}${dim("╰" + bar + "╯")}`);
+}
+
+// Label/value rows, aligned. Same idea as `table` but for a single record.
+export function fields(rows, { indent = "    " } = {}) {
+  const width = Math.max(...rows.map(([label]) => label.length));
+  for (const [label, value] of rows) {
+    note(`${indent}${dim(label.padEnd(width))}  ${value}`);
+  }
+}
+
+// A braille spinner, and the reason it exists: polling a device grant takes as
+// long as someone takes to reach their browser, and a static line for 30
+// seconds reads as a hang.
+//
+// Silent when stderr is not a TTY — in CI the frames would land as thousands of
+// lines of escape codes in the log. The cursor is hidden while it runs, so the
+// stop function has to be reachable on every path out, including Ctrl-C.
+const SPINNER_FRAMES = [ "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏" ];
+
+export function startSpinner(text) {
+  if (!process.stderr.isTTY) {
+    note(`  ${text}`);
+    return () => {};
+  }
+
+  let frame = 0;
+  const render = () => {
+    process.stderr.write(`\r  ${cyan(SPINNER_FRAMES[frame++ % SPINNER_FRAMES.length])} ${dim(text)}`);
+  };
+
+  process.stderr.write("\u001b[?25l");
+  render();
+  const timer = setInterval(render, 80);
+
+  let stopped = false;
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(timer);
+    process.stderr.write("\r\u001b[2K\u001b[?25h");
+    process.off("SIGINT", onInterrupt);
+  };
+
+  // Without this, Ctrl-C during a login leaves the terminal with no cursor.
+  function onInterrupt() {
+    stop();
+    process.exit(130);
+  }
+  process.once("SIGINT", onInterrupt);
+
+  return stop;
+}