flostep 0.1.1 → 0.1.3

package/AGENTS.md

@@ -48,6 +48,12 @@ npx flostep share 42            # prints the public link
 npx flostep share 42 --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
+```
+
 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
@@ -100,6 +106,7 @@ npx flostep whoami --json       # which workspace you're writing to
 - **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.
+- **Every command takes `--json`**, and `flostep help <command>` lists its flags — look them up rather than guess.
 - **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/README.md

@@ -59,7 +59,7 @@ Run `flostep syntax` for the authoritative version, fetched from the server.
 | `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 share <id>` | public link on/off (`--embed` for an iframe, `--markdown` for a README image) |
 | `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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flostep",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Build, update and share Flostep diagrams from the terminal, from CI, or from a coding agent.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -39,12 +39,22 @@ const GLOBAL_OPTIONS = {
   version: { type: "boolean", short: "v", default: false }
 };
 
+const GLOBAL_OPTION_HELP = [
+  ["--json", "machine-readable output"],
+  ["-h, --help", "show this help"]
+];
+
 
 async function load(name) {
   const mod = await COMMANDS[name]();
   return mod.default;
 }
 
+// Continuation lines line up under the first, after "Usage: ".
+function usageText(command) {
+  return [].concat(command.usage).join("\n       ");
+}
+
 // 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.
 //
@@ -95,10 +105,18 @@ function topLevelHelp() {
   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`);
+  // Each line has to run exactly as printed — `create` with nothing piped in
+  // only errors, so its example carries a step.
+  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 init", "teach this repo's coding agent to use flostep"]
+  ];
+  const starterWidth = Math.max(...starters.map(([command]) => command.length));
+  for (const [command, what] of starters) {
+    out(`  ${cyan(command.padEnd(starterWidth))}  ${what}`);
+  }
   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."));
@@ -139,12 +157,13 @@ function commandHelp(command) {
     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}`);
-    }
+  // The global flags are listed on every command, because every command
+  // honours them — a usage line that mentions --json on some commands and not
+  // others reads as though the rest don't take it.
+  out();
+  out(bold("OPTIONS"));
+  for (const [flag, description] of [ ...(command.optionHelp ?? []), ...GLOBAL_OPTION_HELP ]) {
+    out(`  ${flag.padEnd(22)} ${description}`);
   }
 
   if (command.examples) {
@@ -162,6 +181,14 @@ export async function main(argv) {
 
   const wantsJson = argv.includes("--json");
 
+  // `flostep help create` is the form people try first, so it means the same
+  // as `flostep create --help`.
+  if (name === "help" && rest[0] && !rest[0].startsWith("-")) {
+    if (!Object.hasOwn(COMMANDS, rest[0])) throw unknownCommand(rest[0]);
+    commandHelp(await load(rest[0]));
+    return 0;
+  }
+
   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`.
@@ -191,11 +218,7 @@ export async function main(argv) {
     return 0;
   }
 
-  if (!Object.hasOwn(COMMANDS, name)) {
-    throw new UsageError(`Unknown command "${name}".`, {
-      usage: "Run `flostep --help` to see the available commands."
-    });
-  }
+  if (!Object.hasOwn(COMMANDS, name)) throw unknownCommand(name);
 
   const command = await load(name);
 
@@ -211,7 +234,7 @@ export async function main(argv) {
       strict: true
     });
   } catch (cause) {
-    throw new UsageError(cause.message, { usage: [].concat(command.usage).join("\n") });
+    throw new UsageError(parseErrorMessage(cause), { usage: usageText(command) });
   }
 
   if (parsed.values.help) {
@@ -219,6 +242,12 @@ export async function main(argv) {
     return 0;
   }
 
+  // Honoured after a command too, as --help is, rather than parsed and ignored.
+  if (parsed.values.version) {
+    out(VERSION);
+    return 0;
+  }
+
   const { token, source: tokenSource } = resolveToken();
   const ctx = {
     json: parsed.values.json,
@@ -230,7 +259,31 @@ export async function main(argv) {
     }
   };
 
-  return (await command.run({ positionals: parsed.positionals, values: parsed.values, ctx })) ?? 0;
+  try {
+    return (await command.run({ positionals: parsed.positionals, values: parsed.values, ctx })) ?? 0;
+  } catch (error) {
+    // Shared helpers like resolveTarget don't know which command called them;
+    // this does, so their usage errors still end with the right usage line.
+    if (error instanceof UsageError && !error.usage) error.usage = usageText(command);
+    throw error;
+  }
+}
+
+function unknownCommand(name) {
+  return new UsageError(`Unknown command "${name}".`, {
+    hint: "Run `flostep --help` to see the available commands."
+  });
+}
+
+// Node's own wording for a mistyped flag goes on to explain how to pass a
+// positional that starts with "-", which is never what someone typing --tittle
+// meant. Everything else it says is clear enough to keep.
+function parseErrorMessage(cause) {
+  if (cause.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
+    const flag = cause.message.match(/'([^']+)'/)?.[1];
+    if (flag) return `Unknown option ${flag}.`;
+  }
+  return cause.message;
 }
 
 export async function run(argv) {
@@ -238,7 +291,7 @@ export async function run(argv) {
     return await main(argv);
   } catch (error) {
     if (error instanceof UsageError) {
-      fail(error.message);
+      fail(error.message, error.hint);
       if (error.usage) {
         note();
         note(`Usage: ${error.usage}`);

package/src/commands/create.js

@@ -11,7 +11,7 @@ import { diagramFromStdin, describe } from "../source.js";
 export default {
   name: "create",
   usage: [
-    'flostep create [--title <title>] [--share]',
+    'flostep create [--title <title>] [--share] < steps.txt',
     'flostep show 42 | flostep create --title "Copy"'
   ],
   details: [

package/src/commands/folder.js

@@ -15,7 +15,7 @@ const SUBCOMMANDS = ["list", "create", "rename", "delete"];
 export default {
   name: "folder",
   usage: [
-    "flostep folder list [--json]",
+    "flostep folder list",
     'flostep folder create "<name>"',
     'flostep folder rename "<old>" "<new>"',
     'flostep folder delete "<name>" [--yes]'

package/src/commands/init.js

@@ -46,7 +46,7 @@ export default {
     ["-y, --yes", "skip the confirmation prompt"]
   ],
   examples: [
-    ["npx flostep init", "in the root of the repository"],
+    ["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"]
   ],

package/src/commands/list.js

@@ -2,7 +2,7 @@ import { out, table, json, relativeTime, dim } from "../output.js";
 
 export default {
   name: "list",
-  usage: "flostep list [--folder <name>] [--json]",
+  usage: "flostep list [--folder <name>]",
   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."
@@ -39,7 +39,7 @@ export default {
 
     if (diagrams.length === 0) {
       out(dim(folder === undefined
-        ? "No diagrams yet. Create one with `flostep create --title X --share`."
+        ? "No diagrams yet. Create one with `echo 'A -> B: hello' | flostep create --title X --share`."
         : "No diagrams in that folder."));
       return 0;
     }

package/src/commands/login.js

@@ -13,7 +13,7 @@ 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 { note, json, box, banner, fields, startSpinner, dim, bold, cyan, green } from "../output.js";
 import { Api } from "../api.js";
 import { openBrowser } from "../browser.js";
 
@@ -46,6 +46,8 @@ export default {
   async run({ values, ctx }) {
     const host = resolveHost();
 
+    if (!ctx.json) banner();
+
     if (values.token) return storeToken({ host, token: values.token.trim(), ctx });
 
     const api = ctx.api();
@@ -151,8 +153,8 @@ async function storeToken({ host, token, expiresAt, ctx }) {
     ...(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."));
+  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;
 }
 

package/src/commands/node.js

@@ -21,7 +21,7 @@ export default {
   name: "node",
   usage: [
     'flostep node rename <id> "<old>" "<new>"',
-    "flostep node list <id> [--json]"
+    "flostep node list <id>"
   ],
   details: [
     "Components are identified by name, case-insensitively, so a rename changes",

package/src/commands/open.js

@@ -1,4 +1,4 @@
-import { out, ok, note, dim } from "../output.js";
+import { out, ok, note, json, dim } from "../output.js";
 import { openBrowser } from "../browser.js";
 import { resolveTarget } from "../target.js";
 
@@ -8,7 +8,7 @@ export default {
   details: ["Opens the diagram in the editor in your default browser."],
   examples: [
     ["flostep open 15"],
-    ["flostep open 42"]
+    ["flostep open 15 --json", "the url, and whether a browser started"]
   ],
 
   async run({ positionals, ctx }) {
@@ -17,7 +17,14 @@ export default {
 
     // 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)) {
+    const opened = await openBrowser(diagram.url);
+
+    if (ctx.json) {
+      json({ id: diagram.id, title: diagram.title, url: diagram.url, opened });
+      return 0;
+    }
+
+    if (opened) {
       ok(`Opening ${diagram.title}`);
       out(diagram.url);
     } else {

package/src/commands/share.js

@@ -1,24 +1,56 @@
 import { out, ok, json, dim } from "../output.js";
 import { resolveTarget } from "../target.js";
+import { CliError, UsageError } from "../errors.js";
+
+// --off on a line of its own, because it takes neither of the others.
+const USAGE = [
+  "flostep share <id> [--embed | --markdown]",
+  "flostep share <id> --off"
+];
+
+// Square brackets would end the alt text early, so the title gives them up.
+function markdown(title, imageUrl, linkUrl) {
+  const alt = String(title ?? "").replace(/[\[\]\s]+/g, " ").trim() || "Diagram";
+  return `[![${alt}](${imageUrl})](${linkUrl})`;
+}
+
+// The server decides what a plan includes and says so with a null; the CLI
+// never restates the plan rules. A missing key is a different thing — a server
+// from before the feature — and saying "upgrade" there would be wrong.
+function need(value, what, shareUrl) {
+  if (value === undefined) {
+    throw new CliError(`This Flostep server doesn't offer ${what} yet.`);
+  }
+  if (value === null) {
+    throw new CliError(`${what[0].toUpperCase()}${what.slice(1)} need a paid plan.`, {
+      hint: `The diagram is shared, and the link works on every plan: ${shareUrl}`
+    });
+  }
+  return value;
+}
 
 export default {
   name: "share",
-  usage: "flostep share <id> [--off] [--embed]",
+  usage: USAGE,
   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."
+    "The link is read-only and needs no account; viewers can step through the flow.",
+    "GitHub strips iframes, so for a README, an ADR or a PR use --markdown: an image of the diagram that links to the walkthrough."
   ],
   options: {
     off: { type: "boolean", default: false },
-    embed: { type: "boolean", default: false }
+    embed: { type: "boolean", default: false },
+    markdown: { 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"]
+    ["--embed", "print the iframe URL instead of the page URL"],
+    ["--markdown", "print a markdown image that links to the diagram (paid plans)"]
   ],
   examples: [
     ["flostep share 15"],
-    ["flostep share 42 --embed", "for a README or Confluence page"],
+    ["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"]
   ],
 
@@ -26,22 +58,40 @@ export default {
     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 && (values.embed || values.markdown)) {
+      throw new UsageError("--off takes no other flag.", { usage: USAGE.join("\n       ") });
     }
+    if (values.embed && values.markdown) {
+      throw new UsageError("Use --embed or --markdown, not both.", { usage: USAGE.join("\n       ") });
+    }
+
+    const result = values.off ? await api.unshareDiagram(id) : await api.shareDiagram(id);
 
     if (values.off) {
+      if (ctx.json) {
+        json(result);
+        return 0;
+      }
       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;
     }
 
+    // Checked before anything is printed, --json included: what was asked for
+    // either exists or the command fails, in both registers.
+    if (values.markdown) need(result.image_url, "image embeds", result.share_url);
+
+    const snippet = values.markdown ? markdown(result.title, result.image_url, result.share_url) : null;
+
+    if (ctx.json) {
+      json(snippet ? { ...result, markdown: snippet } : result);
+      return 0;
+    }
+
     ok(`Sharing #${result.id} ${dim(result.title)}`);
-    out(values.embed ? result.embed_url : result.share_url);
+    if (snippet) out(snippet);
+    else out(values.embed ? result.embed_url : result.share_url);
     return 0;
   }
 };

package/src/commands/step.js

@@ -19,7 +19,7 @@ export default {
   usage: [
     'flostep step add <id> "From -> To: what happens" [--at <n>]',
     "flostep step rm <id> <n>",
-    "flostep step list <id> [--json]"
+    "flostep step list <id>"
   ],
   details: [
     "Steps are numbered from 1, matching the badges on the canvas.",
@@ -77,7 +77,7 @@ export default {
 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"'
+      usage: 'flostep step add <id> "From -> To: what happens" [--at <n>]'
     });
   }
 
@@ -85,7 +85,7 @@ function applyAdd({ code, text, at }) {
   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>" });
+      throw new UsageError("--at takes a step number.", { usage: 'flostep step add <id> "From -> To: what happens" --at <n>' });
     }
   }
 

package/src/commands/syntax.js

@@ -1,4 +1,4 @@
-import { out } from "../output.js";
+import { out, json } from "../output.js";
 
 export default {
   name: "syntax",
@@ -11,7 +11,8 @@ export default {
 
   async run({ ctx }) {
     const { syntax } = await ctx.api().syntax();
-    out(syntax);
+    if (ctx.json) json({ syntax });
+    else out(syntax);
     return 0;
   }
 };

package/src/commands/update.js

@@ -13,7 +13,7 @@ import { diagramFromStdin, describe } from "../source.js";
 export default {
   name: "update",
   usage: [
-    "flostep update <id> [--title <title>] [--if-version <n>]",
+    "flostep update <id> [--title <title>] [--if-version <n>] < steps.txt",
     "flostep show 42 | flostep update 42"
   ],
   details: [

package/src/commands/whoami.js

@@ -7,7 +7,7 @@ export default {
   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."
+    "belongs to the team. This is how you check which workspace you're writing to."
   ],
   examples: [
     ["flostep whoami"],

package/src/errors.js

@@ -17,10 +17,11 @@ export class CliError extends Error {
 }
 
 export class UsageError extends Error {
-  constructor(message, { usage } = {}) {
+  constructor(message, { usage, hint } = {}) {
     super(message);
     this.name = "UsageError";
     this.exitCode = 2;
     this.usage = usage;
+    this.hint = hint;
   }
 }

package/src/output.js

@@ -118,6 +118,24 @@ export function box(lines, { indent = "  " } = {}) {
   note(`${indent}${dim("╰" + bar + "╯")}`);
 }
 
+// The wordmark, shown once at the top of a login. Skipped when stderr is not a
+// TTY — in a CI log it is noise — and when the terminal is too
+// narrow, where it would wrap into an unreadable mess.
+const WORDMARK = [
+  "█▀▀ █   █▀█ █▀ ▀█▀ █▀▀ █▀█",
+  "█▀  █▄▄ █▄█ ▄█  █  ██▄ █▀▀"
+];
+
+export function banner({ indent = "  " } = {}) {
+  if (!process.stderr.isTTY) return;
+
+  const width = indent.length + Math.max(...WORDMARK.map((line) => line.length));
+  if ((process.stderr.columns ?? 80) < width) return;
+
+  note();
+  for (const line of WORDMARK) note(`${indent}${cyan(line)}`);
+}
+
 // 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));

package/src/stdin.js

@@ -12,7 +12,7 @@ export async function readStdin({ what }) {
   // staring at a cursor with no idea the process is waiting on them.
   if (process.stdin.isTTY) {
     throw new CliError(`No steps on stdin.`, {
-      hint: `Pipe them in — ${what} — or redirect a file into it: \`flostep create < flow.txt\`.`
+      hint: `Pipe them in, or redirect a file: ${what}.`
     });
   }
 

package/src/target.js

@@ -5,7 +5,7 @@
 // a pipe and write nothing to disk, so there is no local file to name and
 // nothing to keep in sync.
 
-import { CliError } from "./errors.js";
+import { UsageError } from "./errors.js";
 
 // A bare positive integer. Ids come from `flostep list`, from `create`, or
 // from the user — never from a guess.
@@ -13,15 +13,18 @@ export function looksLikeId(ref) {
   return /^[1-9][0-9]*$/.test(String(ref).trim());
 }
 
+// Usage errors, not CliErrors: a missing or malformed id is the caller getting
+// the command wrong, and exits 2 like any other. cli.js fills in the usage line
+// of whichever command was running.
 export function resolveTarget(ref) {
   if (!ref) {
-    throw new CliError("Which diagram? Pass an id.", {
+    throw new UsageError("Which diagram? Pass an id.", {
       hint: "Run `flostep list` to see ids."
     });
   }
 
   if (!looksLikeId(ref)) {
-    throw new CliError(`"${ref}" is not a diagram id.`, {
+    throw new UsageError(`"${ref}" is not a diagram id.`, {
       hint: "Ids are numbers — run `flostep list` to see them."
     });
   }