flostep 0.1.2 → 0.1.4

package/AGENTS.md

@@ -35,7 +35,7 @@ Customer -> API: POST /checkout
 API -> Payments: charge card
 API -> Customer: order confirmed
 EOF
-# ✓ Created #42 Checkout
+# ✓ Created #Xk3p9QvA2wE Checkout
 # https://flostep.dev/s/rEFdW8GSDwQ      <- give the user this
 ```
 
@@ -44,36 +44,36 @@ EOF
 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
+npx flostep share Xk3p9QvA2wE          # prints the public link
+npx flostep share Xk3p9QvA2wE --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
+npx flostep share Xk3p9QvA2wE --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
-npx flostep update 42 < docs/checkout.flostep
+npx flostep update Xk3p9QvA2wE < 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
+npx flostep show Xk3p9QvA2wE | sed 's/Redis/Session Cache/' | npx flostep update Xk3p9QvA2wE
 ```
 
 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"
+npx flostep show Xk3p9QvA2wE  # read it first
+npx flostep step add Xk3p9QvA2wE "API -> Cache: read session"
+npx flostep step add Xk3p9QvA2wE "Client -> API: retry" --at 3
+npx flostep step rm Xk3p9QvA2wE 5
+npx flostep node rename Xk3p9QvA2wE "Redis" "Session Cache"
 ```
 
 ### Folders
@@ -81,9 +81,9 @@ npx flostep node rename 42 "Redis" "Session Cache"
 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 folder list --json           # names and diagram counts
+npx flostep folder create "Payments"     # returns the folder if it already exists
+npx flostep move Xk3p9QvA2wE "Payments"  # file it; --none takes it out
 npx flostep list --folder "Payments" --json
 ```
 
@@ -92,11 +92,11 @@ npx flostep list --folder "Payments" --json
 ### 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
+npx flostep list --json                   # ids, titles, urls
+npx flostep show Xk3p9QvA2wE              # the steps, plain text
+npx flostep step list Xk3p9QvA2wE --json  # numbered steps
+npx flostep node list Xk3p9QvA2wE --json  # components, first-appearance order
+npx flostep whoami --json                 # which workspace you're writing to
 ```
 
 ### Rules

package/README.md

@@ -20,14 +20,14 @@ Customer -> API: POST /checkout
 API -> Payments: charge card
 API -> Customer: order confirmed
 EOF
-# ✓ Created #42 Checkout
+# ✓ Created #Xk3p9QvA2wE 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
+npx flostep show Xk3p9QvA2wE | sed 's/Payments/Stripe/' | npx flostep update Xk3p9QvA2wE
 ```
 
 ## The format
@@ -79,7 +79,7 @@ Ids come from `flostep list` or from `create`. Nothing is resolved from a file p
 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
+- run: npx flostep update Xk3p9QvA2wE < docs/checkout.flostep
   env:
     FLOSTEP_TOKEN: ${{ secrets.FLOSTEP_TOKEN }}
 ```

package/package.json

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

package/src/cli.js

@@ -110,7 +110,7 @@ function topLevelHelp() {
   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 show Xk3p9QvA2wE | flostep update Xk3p9QvA2wE", "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));

package/src/commands/create.js

@@ -12,7 +12,7 @@ export default {
   name: "create",
   usage: [
     'flostep create [--title <title>] [--share] < steps.txt',
-    'flostep show 42 | flostep create --title "Copy"'
+    'flostep show Xk3p9QvA2wE | flostep create --title "Copy"'
   ],
   details: [
     "Reads steps from stdin and creates a diagram. Writes no files.",

package/src/commands/delete.js

@@ -13,8 +13,8 @@ export default {
   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"]
+    ["flostep delete Xk3p9QvA2wE"],
+    ["flostep delete Xk3p9QvA2wE --yes", "for scripts and agents"]
   ],
 
   async run({ positionals, values, ctx }) {

package/src/commands/list.js

@@ -45,7 +45,7 @@ export default {
     }
 
     table(diagrams, [
-      ["ID", (d) => d.id, "right"],
+      ["ID", (d) => d.id],
       ["TITLE", (d) => d.title],
       ["FOLDER", (d) => d.folder ?? ""],
       ["UPDATED", (d) => relativeTime(d.updated_at)],

package/src/commands/move.js

@@ -17,8 +17,8 @@ export default {
   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"]
+    ['flostep move Xk3p9QvA2wE "Payments"'],
+    ["flostep move Xk3p9QvA2wE --none"]
   ],
 
   async run({ positionals, values, ctx }) {

package/src/commands/node.js

@@ -7,7 +7,7 @@
 // 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"`.
+// To add a component, name it in a step: `flostep step add Xk3p9QvA2wE "API -> Redis: read"`.
 
 
 import { UsageError } from "../errors.js";
@@ -29,9 +29,9 @@ export default {
     "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"]
+    ["flostep node list Xk3p9QvA2wE"],
+    ['flostep node rename Xk3p9QvA2wE "Redis" "Session Cache"'],
+    ["flostep node list Xk3p9QvA2wE --json", "components in first-appearance order"]
   ],
 
   async run({ positionals, ctx }) {

package/src/commands/open.js

@@ -7,8 +7,8 @@ export default {
   usage: "flostep open <id>",
   details: ["Opens the diagram in the editor in your default browser."],
   examples: [
-    ["flostep open 15"],
-    ["flostep open 15 --json", "the url, and whether a browser started"]
+    ["flostep open Xk3p9QvA2wE"],
+    ["flostep open Xk3p9QvA2wE --json", "the url, and whether a browser started"]
   ],
 
   async run({ positionals, ctx }) {

package/src/commands/share.js

@@ -48,10 +48,10 @@ export default {
     ["--markdown", "print a markdown image that links to the diagram (paid plans)"]
   ],
   examples: [
-    ["flostep share 15"],
-    ["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"]
+    ["flostep share Xk3p9QvA2wE"],
+    ["flostep share Xk3p9QvA2wE --embed", "for a docs page or Confluence"],
+    ["flostep share Xk3p9QvA2wE --markdown", "for a GitHub README; follows the diagram"],
+    ["flostep share Xk3p9QvA2wE --off"]
   ],
 
   async run({ positionals, values, ctx }) {

package/src/commands/show.js

@@ -6,12 +6,12 @@ export default {
   usage: "flostep show <id>",
   details: [
     "Prints the diagram as steps, and nothing else, so it pipes cleanly:",
-    "  flostep show 15 > docs/checkout.flostep"
+    "  flostep show Xk3p9QvA2wE > 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"]
+    ["flostep show Xk3p9QvA2wE"],
+    ["flostep show Xk3p9QvA2wE > docs/checkout.flostep", "redirect it yourself if you want a file"],
+    ["flostep show Xk3p9QvA2wE --json", "with the title and url alongside the code"]
   ],
 
   async run({ positionals, ctx }) {

package/src/commands/step.js

@@ -28,10 +28,10 @@ export default {
   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"]
+    ['flostep step add Xk3p9QvA2wE "API -> Cache: read session"'],
+    ['flostep step add Xk3p9QvA2wE "Client -> API: retry" --at 3'],
+    ["flostep step list Xk3p9QvA2wE --json"],
+    ["flostep step rm Xk3p9QvA2wE 4"]
   ],
 
   async run({ positionals, values, ctx }) {

package/src/commands/update.js

@@ -1,7 +1,7 @@
 // `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
+//   flostep show Xk3p9QvA2wE | sed 's/Redis/Session Cache/' | flostep update Xk3p9QvA2wE
 
 import { readStdin } from "../stdin.js";
 import { UsageError } from "../errors.js";
@@ -14,7 +14,7 @@ export default {
   name: "update",
   usage: [
     "flostep update <id> [--title <title>] [--if-version <n>] < steps.txt",
-    "flostep show 42 | flostep update 42"
+    "flostep show Xk3p9QvA2wE | flostep update Xk3p9QvA2wE"
   ],
   details: [
     "Reads steps from stdin and replaces every step in the diagram.",
@@ -31,15 +31,15 @@ export default {
     ["--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"]
+    ["flostep show Xk3p9QvA2wE | sed 's/Redis/Cache/' | flostep update Xk3p9QvA2wE"],
+    ["flostep update Xk3p9QvA2wE < revised.txt"],
+    ["flostep update Xk3p9QvA2wE --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 input = await readStdin({ what: "`flostep update Xk3p9QvA2wE < flow.txt`" });
     const { code, summary } = diagramFromStdin(input);
 
     const body = { code };

package/src/config.js

@@ -9,8 +9,7 @@ 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";
-export const DEFAULT_HOST = "http://localhost:3000";
+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

package/src/target.js

@@ -1,4 +1,4 @@
-// Turning "15" into a diagram id.
+// Turning "Xk3_p9QvA2w" into a diagram id.
 //
 // Every command that acts on one diagram takes an id, and only an id. Diagrams
 // live in the account, not in a checkout: `create` and `update` read steps from
@@ -7,10 +7,13 @@
 
 import { UsageError } from "./errors.js";
 
-// A bare positive integer. Ids come from `flostep list`, from `create`, or
-// from the user — never from a guess.
+// Any URL-safe token. Ids are random strings now; the integers servers used to
+// hand out still resolve, so they pass too. This deliberately doesn't pin the
+// server's exact format — when ids were checked as digits-only, changing the
+// format would have broken every installed CLI. A wrong id is the server's 404
+// to report; what this catches is a title passed where the id goes.
 export function looksLikeId(ref) {
-  return /^[1-9][0-9]*$/.test(String(ref).trim());
+  return /^[A-Za-z0-9_-]+$/.test(String(ref).trim());
 }
 
 // Usage errors, not CliErrors: a missing or malformed id is the caller getting
@@ -25,9 +28,9 @@ export function resolveTarget(ref) {
 
   if (!looksLikeId(ref)) {
     throw new UsageError(`"${ref}" is not a diagram id.`, {
-      hint: "Ids are numbers — run `flostep list` to see them."
+      hint: "Pass the ID column from `flostep list`, not the title."
     });
   }
 
-  return { id: Number(ref) };
+  return { id: String(ref).trim() };
 }