flostep 0.1.0

package/src/commands/init.js

@@ -0,0 +1,106 @@
+// `flostep init` — make a repository's coding agent aware of flostep.
+//
+// The alternative is asking people to copy a block out of AGENTS.md, which is
+// the step that gets skipped. Needs no login: it writes a text file.
+
+import { createInterface } from "node:readline/promises";
+import { relative, resolve } from "node:path";
+
+import { out, ok, warn, note, dim, bold, json } from "../output.js";
+import { agentBlock, projectRoot, detectTargets, planBlock, commitPlan } from "../instructions.js";
+
+const DONE = {
+  created: "Created",
+  appended: "Added flostep to",
+  updated: "Updated",
+  unchanged: "Already up to date:"
+};
+
+const PENDING = {
+  created: "create",
+  appended: "append to",
+  updated: "update the flostep block in"
+};
+
+export default {
+  name: "init",
+  usage: "flostep init [--file <path>] [--print] [--yes]",
+  details: [
+    "Writes the flostep instructions into the agent instruction files at the repo root,",
+    "so a coding agent working there finds the CLI on its own.",
+    "",
+    "Updates every file that already exists — AGENTS.md, CLAUDE.md, and .cursor/rules/",
+    "(as flostep.mdc) — or creates AGENTS.md when there are none. The block sits between",
+    "marker comments: re-running replaces it, and nothing else in the file is touched.",
+    "",
+    "Asks before writing when run in a terminal. Without one, or with --json, it writes."
+  ],
+  options: {
+    file: { type: "string" },
+    print: { type: "boolean", default: false },
+    yes: { type: "boolean", short: "y", default: false }
+  },
+  optionHelp: [
+    ["--file <path>", "write to this file instead of detecting one"],
+    ["--print", "print the block to stdout and write nothing"],
+    ["-y, --yes", "skip the confirmation prompt"]
+  ],
+  examples: [
+    ["npx flostep init", "in the root of the repository"],
+    ["flostep init --file docs/agents.md"],
+    ["flostep init --print >> system-prompt.md", "for a prompt that isn't a file in a repo"]
+  ],
+
+  async run({ values, ctx }) {
+    const block = agentBlock();
+
+    if (values.print) {
+      out(block);
+      return 0;
+    }
+
+    const root = projectRoot();
+    const targets = values.file ? [ resolve(values.file) ] : detectTargets(root);
+    const display = (path) => relative(root, path) || path;
+    const plans = targets.map((path) => planBlock(path, block));
+    const changes = plans.filter(({ contents }) => contents != null);
+
+    // Unlike `delete`, a missing terminal means go ahead rather than refuse:
+    // the change is additive, lives in version control, and re-running undoes
+    // nothing a person would miss. Refusing would make it useless in scripts.
+    const interactive = process.stdin.isTTY && !ctx.json && !values.yes;
+
+    if (interactive && changes.length > 0) {
+      note(`This will ${bold("write to your repository")}:`);
+      for (const { path, action } of changes) note(`  ${dim("•")} ${PENDING[action]} ${display(path)}`);
+
+      const rl = createInterface({ input: process.stdin, output: process.stderr });
+      // Ctrl-D rejects the question. That's someone backing out, not a bug, so
+      // it gets the same answer as "n" rather than a stack-trace hint.
+      const answer = await rl.question("Continue? [Y/n] ").catch(() => null);
+      rl.close();
+
+      if (answer == null || !/^(y(es)?)?$/i.test(answer.trim())) {
+        note(dim("Nothing written."));
+        return 0;
+      }
+    }
+
+    for (const plan of changes) commitPlan(plan);
+
+    if (ctx.json) {
+      json({ files: plans.map(({ path, action }) => ({ path: display(path), action })) });
+      return 0;
+    }
+
+    for (const { path, action } of plans) {
+      if (action === "skipped") {
+        warn(`Skipped ${display(path)} — it already has a "## Flostep CLI" section, pasted by hand.`);
+        note(dim("  Delete that section and re-run to have init manage it from now on."));
+      } else {
+        ok(`${DONE[action]} ${display(path)}`);
+      }
+    }
+    return 0;
+  }
+};

package/src/commands/list.js

@@ -0,0 +1,56 @@
+import { out, table, json, relativeTime, dim } from "../output.js";
+
+export default {
+  name: "list",
+  usage: "flostep list [--folder <name>] [--json]",
+  details: [
+    "Every diagram in the workspace the key belongs to, most recently updated first.",
+    "--folder narrows it to one folder; `--folder uncategorized` to diagrams in none."
+  ],
+  options: { folder: { type: "string" } },
+  optionHelp: [["--folder <name>", "only diagrams in this folder, or `uncategorized`"]],
+  examples: [
+    ["flostep list"],
+    ['flostep list --folder "Payments"'],
+    ["flostep list --json", "ids and urls, for scripts and agents"]
+  ],
+
+  async run({ values, ctx }) {
+    const api = ctx.api();
+    let folder;
+    if (values.folder !== undefined) {
+      // A real folder called "uncategorized" wins over the keyword, as it does
+      // over MCP — it's the one the person could only mean.
+      const wanted = values.folder.trim();
+      if (wanted.toLowerCase() === "uncategorized") {
+        const { folders } = await api.listFolders();
+        folder = folders.find((f) => f.name.toLowerCase() === "uncategorized")?.id ?? "uncategorized";
+      } else {
+        folder = (await api.findFolder(wanted)).id;
+      }
+    }
+
+    const diagrams = await api.listDiagrams({ folder });
+
+    if (ctx.json) {
+      json(diagrams);
+      return 0;
+    }
+
+    if (diagrams.length === 0) {
+      out(dim(folder === undefined
+        ? "No diagrams yet. Create one with `flostep create --title X --share`."
+        : "No diagrams in that folder."));
+      return 0;
+    }
+
+    table(diagrams, [
+      ["ID", (d) => d.id, "right"],
+      ["TITLE", (d) => d.title],
+      ["FOLDER", (d) => d.folder ?? ""],
+      ["UPDATED", (d) => relativeTime(d.updated_at)],
+      ["URL", (d) => d.url]
+    ]);
+    return 0;
+  }
+};

package/src/commands/login.js

@@ -0,0 +1,166 @@
+// `flostep login` — OAuth 2.0 device authorization grant (RFC 8628).
+//
+// The device grant rather than a localhost redirect, because this CLI is
+// expected to run over SSH and inside containers, where a browser on the user's
+// machine cannot reach a listener on the CLI's. Printing a code that works from
+// any device is the only shape that survives that.
+//
+// It does not cover CI, and is not meant to: an Action has no browser. There,
+// FLOSTEP_TOKEN holds a key minted on the website, and it takes precedence over
+// anything stored here.
+
+import { hostname } from "node:os";
+
+import { CliError } from "../errors.js";
+import { readConfig, writeConfig, resolveHost } from "../config.js";
+import { note, json, box, fields, startSpinner, dim, bold, cyan, green } from "../output.js";
+import { Api } from "../api.js";
+import { openBrowser } from "../browser.js";
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export default {
+  name: "login",
+  usage: [
+    "flostep login",
+    "flostep login --token <fls_...>"
+  ],
+  details: [
+    "Prints a short code, opens the browser, and waits while you approve it.",
+    "The key it creates is listed on your API keys page and can be revoked there."
+  ],
+  options: {
+    token: { type: "string" },
+    "no-browser": { type: "boolean", default: false }
+  },
+  optionHelp: [
+    ["--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_TOKEN=fls_… flostep list", "CI needs no login at all — set the env var"]
+  ],
+
+  async run({ values, ctx }) {
+    const host = resolveHost();
+
+    if (values.token) return storeToken({ host, token: values.token.trim(), ctx });
+
+    const api = ctx.api();
+    const grant = await api.requestDeviceCode(hostname());
+
+    note();
+    box([ `Your code:  ${bold(cyan(grant.user_code))}` ]);
+    note();
+
+    const opened = values["no-browser"] ? false : await openBrowser(grant.verification_uri_complete);
+    note(
+      opened
+        ? `  Opening ${dim(grant.verification_uri)} — approve the code there.`
+        : `  Open ${cyan(grant.verification_uri)} and enter it.`
+    );
+    note();
+
+    // Stopped on every path out, or the terminal is left with no cursor.
+    const stopSpinner = startSpinner("Waiting for approval…");
+    let token;
+    try {
+      token = await poll({ api, grant });
+    } finally {
+      stopSpinner();
+    }
+
+    return storeToken({ host, token: token.token, expiresAt: token.expires_at, ctx });
+  }
+};
+
+async function poll({ api, grant }) {
+  // The server tells us how fast to poll and for how long. Honouring both is
+  // what keeps this from being rate-limited into failing on a slow approval.
+  let interval = (grant.interval ?? 5) * 1000;
+  const deadline = Date.now() + (grant.expires_in ?? 600) * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(interval);
+    const body = await api.pollDeviceToken(grant.device_code);
+
+    if (body.token) return body;
+
+    switch (body.error) {
+      case "authorization_pending":
+        break;
+      case "slow_down":
+        // The RFC's own back-pressure. Backing off additively rather than
+        // resetting keeps a slow server from being hammered for ten minutes.
+        interval += 5000;
+        break;
+      case "access_denied":
+        throw new CliError("The request was denied in the browser.", {
+          hint: "Run `flostep login` again if that wasn't you."
+        });
+      case "expired_token":
+        throw new CliError("The code expired before it was approved.", {
+          hint: "Run `flostep login` again for a fresh one."
+        });
+      default:
+        throw new CliError(body.error_description || body.error || "Login failed.");
+    }
+  }
+
+  throw new CliError("Timed out waiting for approval.", {
+    hint: "Run `flostep login` again."
+  });
+}
+
+async function storeToken({ host, token, expiresAt, ctx }) {
+  if (!token.startsWith("fls_")) {
+    throw new CliError("That doesn't look like a Flostep API key (they start with `fls_`).");
+  }
+
+  // The host is stored alongside the token because they belong together — a key
+  // from a self-hosted instance is meaningless against flostep.dev, and storing
+  // only the token would silently send it to the wrong place.
+  writeConfig({ ...readConfig(), host, token });
+
+  // Built here rather than through ctx.api(), which captured the token as it
+  // was *before* this login — for `--token` that is null, so this would
+  // authenticate as nobody and pass.
+  //
+  // Called on every path, not just the pasted-key one: it verifies the token
+  // (a revoked key would otherwise report a successful login and fail on the
+  // next command, pointing the blame at that command), and it is where the
+  // workspace comes from. A key acts on a workspace, not a person, so "which
+  // library did I just point this terminal at?" is the question worth
+  // answering here — especially on a team, where it may not be your own.
+  const me = await new Api({ host, token }).me();
+
+  if (ctx.json) {
+    json({ email: me.email, workspace: me.workspace, host, expires_at: expiresAt ?? null });
+    return 0;
+  }
+
+  note();
+  note(`  ${green("✓")} ${bold("Connected")}`);
+  note();
+  fields([
+    [ "Account", me.email ],
+    [ "Workspace", `${me.workspace.name}${me.workspace.team ? dim("  (team)") : ""}` ],
+    [ "Plan", me.workspace.plan ],
+    ...(expiresAt ? [ [ "Expires", formatExpiry(expiresAt) ] ] : [])
+  ]);
+  note();
+  note(dim(`  Next:  ${cyan('flostep create --title "My flow" --share')}`));
+  note(dim("         steps on stdin, no files — or `flostep --help` for the rest."));
+  return 0;
+}
+
+// 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
+// their session lasts. `undefined` keeps their locale's ordering; naming the
+// month is what removes the ambiguity.
+function formatExpiry(iso) {
+  return new Date(iso).toLocaleDateString(undefined, { day: "numeric", month: "short", year: "numeric" });
+}

package/src/commands/logout.js

@@ -0,0 +1,30 @@
+import { clearConfig, resolveToken } from "../config.js";
+import { ok, note, dim, json } from "../output.js";
+
+export default {
+  name: "logout",
+  usage: "flostep logout",
+  details: [
+    "Removes the stored credentials from this machine.",
+    "The key itself keeps working until you revoke it on the API keys page."
+  ],
+  examples: [["flostep logout"]],
+
+  async run({ ctx }) {
+    const { source } = resolveToken();
+    clearConfig();
+
+    if (ctx.json) {
+      json({ logged_out: true });
+      return 0;
+    }
+
+    ok("Logged out.");
+    // Silently doing nothing would be indistinguishable from success, and the
+    // next command would still be authenticated — which reads as a bug.
+    if (source === "FLOSTEP_TOKEN") {
+      note(dim("  FLOSTEP_TOKEN is still set in this environment, so commands remain authenticated."));
+    }
+    return 0;
+  }
+};

package/src/commands/move.js

@@ -0,0 +1,48 @@
+// `flostep move` — file a diagram in a folder, or take it out of one.
+//
+// Moving never changes the diagram, so it works on read-only diagrams too and
+// leaves any local file alone.
+
+import { UsageError } from "../errors.js";
+import { ok, json, dim, bold } from "../output.js";
+import { resolveTarget } from "../target.js";
+
+export default {
+  name: "move",
+  usage: [
+    'flostep move <id> "<folder>"',
+    "flostep move <id> --none"
+  ],
+  details: ["The folder must already exist — see `flostep folder list`, or `flostep folder create`."],
+  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"]
+  ],
+
+  async run({ positionals, values, ctx }) {
+    const [ref, folderName] = positionals;
+
+    if (!ref || (!folderName && !values.none) || (folderName && values.none)) {
+      throw new UsageError("Pass a diagram and either a folder name or --none.", {
+        usage: this.usage.join("\n       ")
+      });
+    }
+
+    const target = resolveTarget(ref);
+    const api = ctx.api();
+    const folder = values.none ? null : await api.findFolder(folderName);
+    const moved = await api.moveDiagram(target.id, folder?.id ?? null);
+
+    if (ctx.json) {
+      json(moved);
+      return 0;
+    }
+
+    ok(moved.folder
+      ? `Moved #${moved.id} ${dim(moved.title)} to ${bold(moved.folder)}`
+      : `Moved #${moved.id} ${dim(moved.title)} out of its folder`);
+    return 0;
+  }
+};

package/src/commands/node.js

@@ -0,0 +1,87 @@
+// `flostep node` — the components in a diagram.
+//
+// Deliberately only rename and list. There is no `node add` and no `--type`,
+// and that is a property of the format rather than an omission: the text
+// grammar has no way to express a component with no connections (it is written
+// as a side of a step, so an unconnected one cannot be written at all), and no
+// 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"`.
+
+
+import { UsageError } from "../errors.js";
+import { out, ok, json, dim } from "../output.js";
+import { resolveTarget } from "../target.js";
+import { componentsOf, renameComponent } from "../code.js";
+
+const SUBCOMMANDS = ["rename", "list"];
+
+export default {
+  name: "node",
+  usage: [
+    'flostep node rename <id> "<old>" "<new>"',
+    "flostep node list <id> [--json]"
+  ],
+  details: [
+    "Components are identified by name, case-insensitively, so a rename changes",
+    "every step that mentions them. To add one, name it in a new step.",
+    "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"]
+  ],
+
+  async run({ positionals, ctx }) {
+    const [subcommand, ref, ...rest] = positionals;
+
+    if (!SUBCOMMANDS.includes(subcommand)) {
+      throw new UsageError(
+        subcommand ? `Unknown subcommand "node ${subcommand}".` : "Which action? rename 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") {
+      const components = componentsOf(diagram.code);
+
+      if (ctx.json) {
+        json(components.map((name, i) => ({ n: i + 1, name })));
+        return 0;
+      }
+      if (components.length === 0) {
+        out(dim("No components yet."));
+        return 0;
+      }
+      // First-appearance order, which is the order the server creates them and
+      // therefore the left-to-right order of lifelines in sequence view.
+      components.forEach((name) => out(name));
+      return 0;
+    }
+
+    const [oldName, newName] = rest;
+    if (!oldName || !newName) {
+      throw new UsageError("Rename needs both the old and the new name.", {
+        usage: 'flostep node rename <id> "<old>" "<new>"'
+      });
+    }
+
+    const { code, changed } = renameComponent(diagram.code, oldName, newName);
+    // As in `step`: only if nothing changed since the read above.
+    await api.updateDiagram(target.id, { code, version: diagram.version });
+
+    if (ctx.json) {
+      json({ id: diagram.id, from: oldName, to: newName, steps_changed: changed, code });
+      return 0;
+    }
+
+    ok(`Renamed ${dim(oldName)} → ${newName} ${dim(`(${changed} ${changed === 1 ? "step" : "steps"})`)}`);
+    return 0;
+  }
+};

package/src/commands/open.js

@@ -0,0 +1,29 @@
+import { out, ok, note, dim } from "../output.js";
+import { openBrowser } from "../browser.js";
+import { resolveTarget } from "../target.js";
+
+export default {
+  name: "open",
+  usage: "flostep open <id>",
+  details: ["Opens the diagram in the editor in your default browser."],
+  examples: [
+    ["flostep open 15"],
+    ["flostep open 42"]
+  ],
+
+  async run({ positionals, ctx }) {
+    const { id } = resolveTarget(positionals[0]);
+    const diagram = await ctx.api().getDiagram(id);
+
+    // Awaited: whether a browser actually started is only known a tick later,
+    // and headless is a normal place to run this — the URL is the useful half.
+    if (await openBrowser(diagram.url)) {
+      ok(`Opening ${diagram.title}`);
+      out(diagram.url);
+    } else {
+      out(diagram.url);
+      note(dim("(couldn't open a browser here — the URL is above)"));
+    }
+    return 0;
+  }
+};

package/src/commands/share.js

@@ -0,0 +1,47 @@
+import { out, ok, json, dim } from "../output.js";
+import { resolveTarget } from "../target.js";
+
+export default {
+  name: "share",
+  usage: "flostep share <id> [--off] [--embed]",
+  details: [
+    "Turns on the public link and prints it — the natural last step after `create` or `update`.",
+    "The link is read-only and needs no account; viewers can step through the flow."
+  ],
+  options: {
+    off: { type: "boolean", default: false },
+    embed: { type: "boolean", default: false }
+  },
+  optionHelp: [
+    ["--off", "stop sharing (the URL is kept, so re-sharing restores it)"],
+    ["--embed", "print the iframe URL instead of the page URL"]
+  ],
+  examples: [
+    ["flostep share 15"],
+    ["flostep share 42 --embed", "for a README or Confluence page"],
+    ["flostep share 15 --off"]
+  ],
+
+  async run({ positionals, values, ctx }) {
+    const { id } = resolveTarget(positionals[0]);
+    const api = ctx.api();
+
+    const result = values.off ? await api.unshareDiagram(id) : await api.shareDiagram(id);
+
+    if (ctx.json) {
+      json(result);
+      return 0;
+    }
+
+    if (values.off) {
+      ok(`Sharing off for #${result.id} ${dim(result.title)}`);
+      // Worth saying: people expect "unshare" to burn the URL, and it doesn't.
+      out(dim("The link is kept — sharing again restores the same URL."));
+      return 0;
+    }
+
+    ok(`Sharing #${result.id} ${dim(result.title)}`);
+    out(values.embed ? result.embed_url : result.share_url);
+    return 0;
+  }
+};

package/src/commands/show.js

@@ -0,0 +1,30 @@
+import { out, json } from "../output.js";
+import { resolveTarget } from "../target.js";
+
+export default {
+  name: "show",
+  usage: "flostep show <id>",
+  details: [
+    "Prints the diagram as steps, and nothing else, so it pipes cleanly:",
+    "  flostep show 15 > 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"]
+  ],
+
+  async run({ positionals, ctx }) {
+    const { id } = resolveTarget(positionals[0]);
+    const diagram = await ctx.api().getDiagram(id);
+
+    if (ctx.json) {
+      json(diagram);
+      return 0;
+    }
+
+    // No trailing decoration — this is the pipeable one.
+    out(diagram.code);
+    return 0;
+  }
+};