flostep 0.1.0

package/src/source.js

@@ -0,0 +1,63 @@
+// Deciding whether what arrived on stdin is a diagram, before it is sent.
+//
+// `create` and `update` used to hand anything to the server and let a 422 come
+// back. That is a slow no, and the text has already left the machine by the
+// time something objects — which matters when the pipe was `cat .env` rather
+// than a flow.
+//
+// The checks here are deliberately weaker than the server's. This is the third
+// copy of the grammar (see code.js), so anything ambiguous goes to the server
+// and lets it decide; only input with no steps at all is refused outright.
+
+import { CliError } from "./errors.js";
+import { parseSteps, componentsOf, MAX_STEPS, MAX_COMPONENTS } from "./code.js";
+
+// What the parser made of the text: the counts `create` prints, and everything
+// it skipped — the tell for a pipe carrying prose rather than steps.
+export function summarize(code) {
+  const steps = parseSteps(code);
+  const stepLines = new Set(steps.map((s) => s.lineIndex));
+
+  const ignored = [];
+  code.split("\n").forEach((raw, index) => {
+    const line = raw.trim();
+    if (!line || line.startsWith("#") || line.startsWith("%%") || stepLines.has(index)) return;
+    ignored.push({ line: index + 1, text: line });
+  });
+
+  return { steps: steps.length, components: componentsOf(code), ignored };
+}
+
+// Limits mirrored from the server, so oversized input fails here instead of as
+// a 422 after the upload.
+export function diagramFromStdin(raw) {
+  const code = raw.replace(/\r\n/g, "\n").trim();
+  const summary = summarize(code);
+
+  if (summary.steps === 0) {
+    const first = code.split("\n").find((line) => line.trim()) ?? "";
+    throw new CliError("What arrived on stdin has no steps — it doesn't look like a diagram.", {
+      hint: `Line 1: ${first.slice(0, 60)}\n  Steps look like \`Frontend -> API: POST /login\` — run \`flostep syntax\` for the format.`
+    });
+  }
+
+  if (summary.steps > MAX_STEPS) {
+    throw new CliError(`That is ${summary.steps} steps, past the limit of ${MAX_STEPS}.`);
+  }
+
+  if (summary.components.length > MAX_COMPONENTS) {
+    throw new CliError(
+      `That is ${summary.components.length} components, past the limit of ${MAX_COMPONENTS}.`,
+      { hint: "Reusing an existing name references the same box — different spellings make different ones." }
+    );
+  }
+
+  return { code, summary };
+}
+
+// "4 steps, 3 components" — printed on success, because input that parsed into
+// something absurd ($obj -> method();) is only obvious when counted.
+export function describe(summary) {
+  const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+  return `${plural(summary.steps, "step")}, ${plural(summary.components.length, "component")}`;
+}

package/src/stdin.js

@@ -0,0 +1,29 @@
+// Reading steps from a pipe.
+//
+// This is what makes the CLI usable without touching the filesystem at all: an
+// agent asked to "explain this flow" wants a link, not an untracked file in
+// someone else's checkout. Nothing here writes to disk — redirect `show` if you
+// want the steps in a file.
+
+import { CliError } from "./errors.js";
+
+export async function readStdin({ what }) {
+  // A TTY means nothing was piped in — the user typed the command and is now
+  // 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\`.`
+    });
+  }
+
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const text = Buffer.concat(chunks).toString("utf8").trim();
+
+  if (!text) {
+    throw new CliError("Nothing arrived on stdin.", {
+      hint: "Steps look like `Frontend -> API: POST /login` — run `flostep syntax` for the format."
+    });
+  }
+  return text;
+}

package/src/target.js

@@ -0,0 +1,30 @@
+// Turning "15" 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
+// 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";
+
+// A bare positive integer. Ids come from `flostep list`, from `create`, or
+// from the user — never from a guess.
+export function looksLikeId(ref) {
+  return /^[1-9][0-9]*$/.test(String(ref).trim());
+}
+
+export function resolveTarget(ref) {
+  if (!ref) {
+    throw new CliError("Which diagram? Pass an id.", {
+      hint: "Run `flostep list` to see ids."
+    });
+  }
+
+  if (!looksLikeId(ref)) {
+    throw new CliError(`"${ref}" is not a diagram id.`, {
+      hint: "Ids are numbers — run `flostep list` to see them."
+    });
+  }
+
+  return { id: Number(ref) };
+}

package/src/version.js

@@ -0,0 +1,17 @@
+// The version, read once from package.json, and the User-Agent built from it.
+//
+// Every request identifies the client and its version. Without that the server
+// can't tell CLI traffic from any other API key, can't count who is on which
+// release, and can never turn away a version with a known bug — and a version
+// published without the header stays anonymous for as long as anyone runs it,
+// which is why it went in before the first publish rather than after.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export const VERSION = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")).version;
+
+export const USER_AGENT = `flostep-cli/${VERSION} node/${process.versions.node} ${process.platform}`;