flostep 0.1.0

package/src/cli.js

@@ -0,0 +1,264 @@
+// Argument parsing and dispatch.
+//
+// Commands are loaded on demand rather than imported up front, because `npx
+// flostep` pays module-load cost on every single invocation and most runs touch
+// exactly one command.
+
+import { parseArgs } from "node:util";
+
+import { CliError, UsageError } from "./errors.js";
+import { Api } from "./api.js";
+import { resolveHost, resolveToken } from "./config.js";
+import { out, note, fail, dim, bold, cyan } from "./output.js";
+import { VERSION } from "./version.js";
+
+// Order is the order `--help` lists them, which is roughly the order someone
+// meets them rather than alphabetical.
+const COMMANDS = {
+  login: () => import("./commands/login.js"),
+  logout: () => import("./commands/logout.js"),
+  whoami: () => import("./commands/whoami.js"),
+  init: () => import("./commands/init.js"),
+  list: () => import("./commands/list.js"),
+  show: () => import("./commands/show.js"),
+  create: () => import("./commands/create.js"),
+  update: () => import("./commands/update.js"),
+  share: () => import("./commands/share.js"),
+  open: () => import("./commands/open.js"),
+  delete: () => import("./commands/delete.js"),
+  folder: () => import("./commands/folder.js"),
+  move: () => import("./commands/move.js"),
+  step: () => import("./commands/step.js"),
+  node: () => import("./commands/node.js"),
+  syntax: () => import("./commands/syntax.js")
+};
+
+const GLOBAL_OPTIONS = {
+  json: { type: "boolean", default: false },
+  help: { type: "boolean", short: "h", default: false },
+  version: { type: "boolean", short: "v", default: false }
+};
+
+
+async function load(name) {
+  const mod = await COMMANDS[name]();
+  return mod.default;
+}
+
+// The tool's own description of its surface, built from the very objects
+// `main` dispatches — so it cannot disagree with what the CLI actually accepts.
+//
+// This exists to be checked against prose. The reference lives in a *different*
+// repository, where no test can see these files; `flostep --help --json` is
+// what lets that repo assert its page still covers every command and flag.
+export async function surface() {
+  const commands = [];
+
+  for (const name of Object.keys(COMMANDS)) {
+    const command = await load(name);
+    const options = Object.entries(command.options ?? {}).flatMap(([flag, spec]) =>
+      spec.short ? [ `--${flag}`, `-${spec.short}` ] : [ `--${flag}` ]
+    );
+
+    commands.push({
+      name,
+      summary: SUMMARIES[name],
+      usage: [].concat(command.usage),
+      options
+    });
+  }
+
+  return {
+    version: VERSION,
+    global_options: Object.entries(GLOBAL_OPTIONS).flatMap(([flag, spec]) =>
+      spec.short ? [ `--${flag}`, `-${spec.short}` ] : [ `--${flag}` ]
+    ),
+    commands
+  };
+}
+
+function topLevelHelp() {
+  out(`${bold("flostep")} — build, update and share Flostep diagrams from the terminal.`);
+  out();
+  out(bold("USAGE"));
+  out("  flostep <command> [options]");
+  out();
+  out(bold("COMMANDS"));
+  const width = Math.max(...Object.keys(COMMANDS).map((n) => n.length));
+  for (const name of Object.keys(COMMANDS)) {
+    out(`  ${name.padEnd(width)}  ${SUMMARIES[name]}`);
+  }
+  out();
+  out(bold("GLOBAL OPTIONS"));
+  out("  --json           machine-readable output");
+  out("  -h, --help       show help for a command");
+  out("  -v, --version    print the version");
+  out();
+  out(bold("GETTING STARTED"));
+  out(`  ${cyan("flostep login")}                          sign in from a browser`);
+  out(`  ${cyan("flostep create --title X --share")}       from stdin, no files, returns a link`);
+  out(`  ${cyan("flostep show 42 | flostep update 42")}    read it, change it, write it back`);
+  out(`  ${cyan("flostep init")}                           teach this repo's coding agent to use flostep`);
+  out();
+  out(dim("Steps are written one per line: `From -> To: what happens`."));
+  out(dim("Run `flostep syntax` for the full grammar, straight from the server."));
+  out();
+  out(dim("In CI, set FLOSTEP_TOKEN to a key from https://flostep.dev/api_keys."));
+}
+
+// Duplicated here rather than loaded from every command module, because
+// printing the command list would otherwise import every one of them and
+// undo the lazy loading above.
+const SUMMARIES = {
+  login: "sign in to Flostep from this machine",
+  logout: "forget the stored credentials",
+  whoami: "show the account and workspace a key writes to",
+  init: "tell this repo's coding agent how to use flostep",
+  list: "list the diagrams in the workspace",
+  show: "print a diagram as steps",
+  create: "create a diagram from stdin, writing no files",
+  update: "replace a diagram's steps from stdin",
+  share: "turn the public link on (or off) and print it",
+  open: "open a diagram in the browser",
+  delete: "delete a diagram",
+  folder: "list, create, rename or delete folders",
+  move: "file a diagram in a folder, or take it out",
+  step: "add, remove or list steps on a diagram",
+  node: "rename or list the components in a diagram",
+  syntax: "print the step grammar"
+};
+
+function commandHelp(command) {
+  out(`${bold(`flostep ${command.name}`)} — ${SUMMARIES[command.name]}`);
+  out();
+  out(bold("USAGE"));
+  for (const line of [].concat(command.usage)) out(`  ${line}`);
+
+  if (command.details) {
+    out();
+    for (const line of [].concat(command.details)) out(`  ${line}`);
+  }
+
+  if (command.optionHelp) {
+    out();
+    out(bold("OPTIONS"));
+    for (const [flag, description] of command.optionHelp) {
+      out(`  ${flag.padEnd(22)} ${description}`);
+    }
+  }
+
+  if (command.examples) {
+    out();
+    out(bold("EXAMPLES"));
+    for (const [example, description] of command.examples) {
+      out(`  ${cyan(example)}`);
+      if (description) out(`    ${dim(description)}`);
+    }
+  }
+}
+
+export async function main(argv) {
+  const [name, ...rest] = argv;
+
+  const wantsJson = argv.includes("--json");
+
+  if (!name || name === "help") {
+    // --help is not an error; asking for it should exit 0 so a wrapper script
+    // can call it without tripping `set -e`.
+    if (!name && (argv.includes("--version") || argv.includes("-v"))) {
+      out(VERSION);
+      return 0;
+    }
+    if (wantsJson) {
+      out(JSON.stringify(await surface(), null, 2));
+      return 0;
+    }
+    topLevelHelp();
+    return 0;
+  }
+
+  if (name === "--version" || name === "-v") {
+    out(VERSION);
+    return 0;
+  }
+
+  if (name === "--help" || name === "-h") {
+    if (wantsJson) {
+      out(JSON.stringify(await surface(), null, 2));
+      return 0;
+    }
+    topLevelHelp();
+    return 0;
+  }
+
+  if (!Object.hasOwn(COMMANDS, name)) {
+    throw new UsageError(`Unknown command "${name}".`, {
+      usage: "Run `flostep --help` to see the available commands."
+    });
+  }
+
+  const command = await load(name);
+
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: rest,
+      options: { ...GLOBAL_OPTIONS, ...(command.options ?? {}) },
+      allowPositionals: true,
+      // Unknown flags are a usage error, not something to pass through — a
+      // silently ignored --tittle would push under the wrong title and look
+      // like it worked.
+      strict: true
+    });
+  } catch (cause) {
+    throw new UsageError(cause.message, { usage: [].concat(command.usage).join("\n") });
+  }
+
+  if (parsed.values.help) {
+    commandHelp(command);
+    return 0;
+  }
+
+  const { token } = resolveToken();
+  const ctx = {
+    json: parsed.values.json,
+    token,
+    // Built lazily by the command, because `login` needs a host with no token
+    // and `logout` needs neither.
+    api() {
+      return new Api({ host: resolveHost(), token });
+    }
+  };
+
+  return (await command.run({ positionals: parsed.positionals, values: parsed.values, ctx })) ?? 0;
+}
+
+export async function run(argv) {
+  try {
+    return await main(argv);
+  } catch (error) {
+    if (error instanceof UsageError) {
+      fail(error.message);
+      if (error.usage) {
+        note();
+        note(`Usage: ${error.usage}`);
+      }
+      return error.exitCode;
+    }
+
+    if (error instanceof CliError) {
+      fail(error.message, error.hint);
+      return error.exitCode;
+    }
+
+    // Anything else is a bug in this tool rather than a problem with the
+    // request, and the stack is the only part of it worth reporting. Printed
+    // without asking: a flag to reveal it only helps the people who already
+    // know the flag, and everyone else reports "it crashed" with nothing
+    // attached. The frame lines are dimmed so the message still reads first.
+    fail(error.message || String(error));
+    for (const line of (error.stack ?? "").split("\n").slice(1)) note(dim(line));
+    note(dim("  This is a bug in flostep. Send the above to support@flostep.dev."));
+    return 1;
+  }
+}

package/src/code.js

@@ -0,0 +1,151 @@
+// The step grammar, and the edits the granular commands make to it.
+//
+// This mirrors app/services/flow_parser.rb in the Flostep repo — same arrow
+// pattern, same comment guard, same first-spelling-wins component identity.
+// That repo already carries two independent parsers for this grammar and a
+// warning to keep them in step; this is the third. Run `flostep syntax` to see
+// the server's own description of it, which is served rather than copied for
+// exactly this reason.
+//
+// Every edit is line-wise on purpose. Re-emitting from a parsed model would
+// silently drop anything that isn't a step — blank lines and the `#` comments
+// people write in their own files — and these commands are meant to change one
+// step, not to reformat someone's file.
+
+import { CliError } from "./errors.js";
+
+// Kept identical to FlowParser::ARROW_RE and COMMENT_RE.
+const ARROW_RE = /^(.+?)\s*-{1,2}>{1,2}\s*(.+?)\s*(?::\s*(.*))?$/;
+const COMMENT_RE = /^(#|%%)/;
+
+// Readability ceilings, mirrored from FlowParser so an oversized edit fails
+// here with a clear message instead of as a 422 after a round trip.
+export const MAX_COMPONENTS = 40;
+export const MAX_STEPS = 120;
+
+function parseLine(raw) {
+  const t = raw.trim();
+  if (!t || COMMENT_RE.test(t)) return null;
+
+  const m = t.match(ARROW_RE);
+  if (!m) return null;
+
+  const from = m[1].trim();
+  const to = m[2].trim();
+  if (!from || !to) return null;
+
+  return { from, to, label: (m[3] ?? "").trim() };
+}
+
+export function formatStep({ from, to, label }) {
+  return label ? `${from} -> ${to}: ${label}` : `${from} -> ${to}`;
+}
+
+// Steps in order, each carrying the line it came from so edits can target it.
+export function parseSteps(code) {
+  const steps = [];
+  code.split("\n").forEach((raw, lineIndex) => {
+    const step = parseLine(raw);
+    if (step) steps.push({ ...step, lineIndex });
+  });
+  return steps;
+}
+
+// First appearance wins, matching how both server-side parsers create
+// components — so this order is the order lifelines appear in sequence view.
+export function componentsOf(code) {
+  const seen = new Map();
+  for (const { from, to } of parseSteps(code)) {
+    for (const name of [from, to]) {
+      const key = name.toLowerCase();
+      if (!seen.has(key)) seen.set(key, name);
+    }
+  }
+  return [...seen.values()];
+}
+
+export function isStep(text) {
+  return parseLine(text) !== null;
+}
+
+// `at` is a 1-based step position to insert before; omitted means append.
+export function addStep(code, text, { at } = {}) {
+  const step = parseLine(text);
+  if (!step) {
+    throw new CliError(`Not a step: "${text.trim()}".`, {
+      hint: 'Expected "From -> To: what happens" — run `flostep syntax` for the format.'
+    });
+  }
+
+  const steps = parseSteps(code);
+  if (steps.length + 1 > MAX_STEPS) {
+    throw new CliError(`That would make ${steps.length + 1} steps, past the limit of ${MAX_STEPS}.`);
+  }
+
+  const lines = code.split("\n");
+  const line = formatStep(step);
+
+  if (at === undefined) {
+    // Trailing blank lines are common in a file that ends with a newline;
+    // appending after them would leave a gap.
+    while (lines.length && lines[lines.length - 1].trim() === "") lines.pop();
+    lines.push(line);
+    return lines.join("\n");
+  }
+
+  if (!Number.isInteger(at) || at < 1 || at > steps.length + 1) {
+    throw new CliError(`--at must be between 1 and ${steps.length + 1}.`);
+  }
+
+  const insertAt = at === steps.length + 1 ? lines.length : steps[at - 1].lineIndex;
+  lines.splice(insertAt, 0, line);
+  return lines.join("\n");
+}
+
+// `n` counts steps, not lines — it matches the numbers `step list` prints and
+// the badges on the canvas.
+export function removeStep(code, n) {
+  const steps = parseSteps(code);
+  if (!Number.isInteger(n) || n < 1 || n > steps.length) {
+    throw new CliError(
+      steps.length === 0
+        ? "That diagram has no steps to remove."
+        : `No step ${n}. This diagram has ${steps.length}.`,
+      { hint: steps.length === 0 ? undefined : "Run `flostep step list <id>` to see the numbers." }
+    );
+  }
+
+  const lines = code.split("\n");
+  lines.splice(steps[n - 1].lineIndex, 1);
+  return lines.join("\n");
+}
+
+// Components are identified by lowercased name, so a rename has to match the
+// same way — otherwise renaming "api" would leave "API" behind as a second box.
+export function renameComponent(code, oldName, newName) {
+  const key = oldName.trim().toLowerCase();
+  const replacement = newName.trim();
+  if (!replacement) throw new CliError("The new name can't be empty.");
+
+  const known = componentsOf(code).map((c) => c.toLowerCase());
+  if (!known.includes(key)) {
+    throw new CliError(`No component named "${oldName}".`, {
+      hint: `This diagram has: ${componentsOf(code).join(", ") || "none"}.`
+    });
+  }
+
+  let changed = 0;
+  const lines = code.split("\n").map((raw) => {
+    const step = parseLine(raw);
+    if (!step) return raw;
+
+    const from = step.from.toLowerCase() === key ? replacement : step.from;
+    const to = step.to.toLowerCase() === key ? replacement : step.to;
+    if (from === step.from && to === step.to) return raw;
+
+    changed += 1;
+    return formatStep({ from, to, label: step.label });
+  });
+
+  return { code: lines.join("\n"), changed };
+}

package/src/commands/create.js

@@ -0,0 +1,55 @@
+// `flostep create` — a diagram from a pipe, touching no files.
+//
+// The whole write path. Steps arrive on a pipe and the diagram lives in the
+// account — nothing is written to disk, so there is no file in someone else's
+// checkout to keep in sync.
+
+import { readStdin } from "../stdin.js";
+import { out, ok, json, dim } from "../output.js";
+import { diagramFromStdin, describe } from "../source.js";
+
+export default {
+  name: "create",
+  usage: [
+    'flostep create [--title <title>] [--share]',
+    'flostep show 42 | flostep create --title "Copy"'
+  ],
+  details: [
+    "Reads steps from stdin and creates a diagram. Writes no files.",
+    "Keep the id it prints — `update`, `share` and the rest take it."
+  ],
+  options: {
+    title: { type: "string" },
+    share: { type: "boolean", default: false }
+  },
+  optionHelp: [
+    ["--title <title>", "diagram title (default: Untitled)"],
+    ["--share", "turn on the public link and print it, in the same call"]
+  ],
+  examples: [
+    ['flostep create --title "Checkout" --share < flow.txt', "one call, returns a link"],
+    ['printf "A -> B: x\\n" | flostep create', "from any command that emits steps"]
+  ],
+
+  async run({ values, ctx }) {
+    const input = await readStdin({ what: "`flostep create < flow.txt`, or a heredoc" });
+    // Checked here so a pipe carrying the wrong thing fails before it is sent.
+    const { code, summary } = diagramFromStdin(input);
+    const api = ctx.api();
+
+    const diagram = await api.createDiagram({ title: values.title, code });
+    // Sharing in the same call because "make me a diagram and send me the link"
+    // is one intention, and an agent paying two round trips for it will
+    // sometimes forget the second.
+    const shared = values.share ? await api.shareDiagram(diagram.id) : null;
+
+    if (ctx.json) {
+      json({ ...diagram, ...(shared ? { share_url: shared.share_url, embed_url: shared.embed_url } : {}) });
+      return 0;
+    }
+
+    ok(`Created #${diagram.id} ${dim(`${diagram.title} — ${describe(summary)}`)}`);
+    out(shared ? shared.share_url : diagram.url);
+    return 0;
+  }
+};

package/src/commands/delete.js

@@ -0,0 +1,59 @@
+import { createInterface } from "node:readline/promises";
+
+import { CliError } from "../errors.js";
+import { ok, note, json, dim, bold } from "../output.js";
+import { resolveTarget } from "../target.js";
+
+export default {
+  name: "delete",
+  usage: "flostep delete <id> [--yes]",
+  details: [
+    "Deletes the diagram and any comments on it. This cannot be undone."
+  ],
+  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"]
+  ],
+
+  async run({ positionals, values, ctx }) {
+    const target = resolveTarget(positionals[0]);
+    const api = ctx.api();
+    const diagram = await api.getDiagram(target.id);
+
+    if (!values.yes) {
+      // Non-interactive and unconfirmed is refused rather than assumed either
+      // way: assuming yes deletes someone's work from a script that stalled,
+      // assuming no makes the command silently useless in CI.
+      if (!process.stdin.isTTY) {
+        throw new CliError("Refusing to delete without confirmation.", {
+          hint: "Pass --yes when running without a terminal."
+        });
+      }
+
+      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(`Delete ${bold(diagram.title)} (#${diagram.id})? This cannot be undone. [y/N] `)
+        .catch(() => null);
+      rl.close();
+
+      if (answer == null || !/^y(es)?$/i.test(answer.trim())) {
+        note(dim("Nothing deleted."));
+        return 0;
+      }
+    }
+
+    await api.deleteDiagram(target.id);
+
+    if (ctx.json) {
+      json({ id: diagram.id, title: diagram.title, deleted: true });
+      return 0;
+    }
+
+    ok(`Deleted #${diagram.id} ${dim(diagram.title)}`);
+    return 0;
+  }
+};

package/src/commands/folder.js

@@ -0,0 +1,141 @@
+// `flostep folder` — the folders a workspace files its diagrams in.
+//
+// Folders are addressed by name, not id, as they are over MCP: names are what
+// people say ("put it in Payments") and they are unique per workspace ignoring
+// case. `flostep move` files a diagram into one; `flostep list --folder` reads
+// one back.
+
+import { createInterface } from "node:readline/promises";
+
+import { CliError, UsageError } from "../errors.js";
+import { out, ok, note, json, table, dim, bold } from "../output.js";
+
+const SUBCOMMANDS = ["list", "create", "rename", "delete"];
+
+export default {
+  name: "folder",
+  usage: [
+    "flostep folder list [--json]",
+    'flostep folder create "<name>"',
+    'flostep folder rename "<old>" "<new>"',
+    'flostep folder delete "<name>" [--yes]'
+  ],
+  details: [
+    "Folders are shared by everyone in a team, and named case-insensitively.",
+    "Creating a folder that already exists returns it rather than failing.",
+    "Deleting a folder keeps its diagrams; they become uncategorized."
+  ],
+  options: { yes: { type: "boolean", short: "y", default: false } },
+  optionHelp: [["-y, --yes", "delete without the confirmation prompt"]],
+  examples: [
+    ["flostep folder list"],
+    ['flostep folder create "Payments"'],
+    ['flostep folder rename "Payments" "Billing"'],
+    ['flostep folder delete "Billing" --yes', "for scripts and agents"]
+  ],
+
+  async run({ positionals, values, ctx }) {
+    const [subcommand, ...args] = positionals;
+
+    if (!SUBCOMMANDS.includes(subcommand)) {
+      throw new UsageError(
+        subcommand ? `Unknown subcommand "folder ${subcommand}".` : "Which action? list, create, rename or delete.",
+        { usage: this.usage.join("\n       ") }
+      );
+    }
+
+    const api = ctx.api();
+
+    if (subcommand === "list") {
+      const { folders, uncategorized } = await api.listFolders();
+
+      if (ctx.json) {
+        json({ folders, uncategorized });
+        return 0;
+      }
+      if (folders.length === 0) {
+        out(dim("No folders yet. Create one with `flostep folder create <name>`."));
+        return 0;
+      }
+      table(folders, [
+        ["NAME", (f) => f.name],
+        ["DIAGRAMS", (f) => f.diagrams, "right"]
+      ]);
+      out(dim(`${uncategorized} uncategorized`));
+      return 0;
+    }
+
+    if (subcommand === "create") {
+      const [name] = args;
+      if (!name?.trim()) {
+        throw new UsageError("Name the folder.", { usage: 'flostep folder create "<name>"' });
+      }
+
+      const folder = await api.createFolder(name);
+      if (ctx.json) {
+        json(folder);
+        return 0;
+      }
+      if (folder.created) ok(`Created folder ${bold(folder.name)}`);
+      else ok(`Folder ${bold(folder.name)} already exists ${dim(`(${folder.diagrams} diagrams)`)}`);
+      return 0;
+    }
+
+    if (subcommand === "rename") {
+      const [oldName, newName] = args;
+      if (!oldName || !newName?.trim()) {
+        throw new UsageError("Rename needs both the old and the new name.", {
+          usage: 'flostep folder rename "<old>" "<new>"'
+        });
+      }
+
+      const folder = await api.findFolder(oldName);
+      const renamed = await api.renameFolder(folder.id, newName);
+      if (ctx.json) {
+        json(renamed);
+        return 0;
+      }
+      ok(`Renamed folder ${dim(folder.name)} → ${bold(renamed.name)}`);
+      return 0;
+    }
+
+    // delete
+    const [name] = args;
+    if (!name) {
+      throw new UsageError("Which folder?", { usage: 'flostep folder delete "<name>" [--yes]' });
+    }
+    const folder = await api.findFolder(name);
+
+    if (!values.yes) {
+      // Same rule as `flostep delete`: unconfirmed without a terminal is refused
+      // rather than assumed either way. A folder delete un-files a whole team's
+      // diagrams at once, which is not something to do on a stalled script's behalf.
+      if (!process.stdin.isTTY) {
+        throw new CliError("Refusing to delete without confirmation.", {
+          hint: "Pass --yes when running without a terminal."
+        });
+      }
+
+      const rl = createInterface({ input: process.stdin, output: process.stderr });
+      const count = `${folder.diagrams} ${folder.diagrams === 1 ? "diagram" : "diagrams"}`;
+      const answer = await rl
+        .question(`Delete folder ${bold(folder.name)}? Its ${count} will become uncategorized. [y/N] `)
+        .catch(() => null);
+      rl.close();
+
+      if (answer == null || !/^y(es)?$/i.test(answer.trim())) {
+        note(dim("Nothing deleted."));
+        return 0;
+      }
+    }
+
+    const result = await api.deleteFolder(folder.id);
+    if (ctx.json) {
+      json(result);
+      return 0;
+    }
+    const unfiled = result.diagrams_unfiled;
+    ok(`Deleted folder ${bold(folder.name)} ${dim(`(${unfiled} ${unfiled === 1 ? "diagram" : "diagrams"} now uncategorized)`)}`);
+    return 0;
+  }
+};