@devmarketplacenpm/devmp 0.1.1-beta.5

package/lib/status.js

@@ -0,0 +1,249 @@
+"use strict";
+
+const os = require("os");
+const {
+  color,
+  fmt,
+  box,
+  formatNumber,
+  formatDate,
+} = require("./ui");
+const { getTokenBalance, refreshSession } = require("./api");
+const { sessionPath } = require("./session");
+const { getGitInfo } = require("./git");
+
+// CLI_UX_FLOW.md requires the opening screen to answer five questions at a
+// glance: am I signed in, which environment, do I have tokens, what can I do,
+// and what is the next fix if something is wrong. Both `devmp status` and the
+// interactive shell render from this one collector so they can never drift.
+
+/**
+ * Gather account + quota state. Never throws: an unreachable API or an expired
+ * session is a *state to display*, not an error to crash the shell with.
+ */
+async function collectStatus({ session, rootDir } = {}) {
+  const result = {
+    signedIn: Boolean(session && session.accessToken),
+    account: session?.user?.email || null,
+    apiBaseUrl: session?.apiBaseUrl || null,
+    balance: null,
+    reachable: null,
+    authFailed: false,
+    error: null,
+    git: null,
+    session,
+  };
+
+  if (rootDir) {
+    result.git = await getGitInfo(rootDir).catch(() => null);
+  }
+  if (!result.signedIn) return result;
+
+  try {
+    result.balance = await getTokenBalance(session);
+    result.reachable = true;
+    return result;
+  } catch (error) {
+    if (error?.status === 401 || error?.status === 403) {
+      // One silent refresh before declaring the session dead — the access
+      // token expiring is routine, not something to bother the user with.
+      const refreshed = await refreshSession(session).catch(() => null);
+      if (refreshed) {
+        result.session = refreshed;
+        try {
+          result.balance = await getTokenBalance(refreshed);
+          result.reachable = true;
+          return result;
+        } catch (retryError) {
+          result.error = retryError?.message || String(retryError);
+        }
+      }
+      result.reachable = true;
+      result.authFailed = error.status === 401;
+      if (error.status === 403) result.balance = { provisioned: false };
+      return result;
+    }
+    result.reachable = false;
+    result.error = error?.message || String(error);
+    return result;
+  }
+}
+
+function tokenSummary(info) {
+  if (!info.signedIn) return color.dim("—");
+  if (info.reachable === false) return color.yellow("API unavailable");
+  if (info.authFailed) return color.yellow("session expired");
+  const balance = info.balance;
+  if (!balance) return color.dim("unknown");
+  if (!balance.provisioned) return color.yellow("not provisioned");
+  const used = Math.max(0, (balance.monthlyLimit || 0) - (balance.balance || 0));
+  return `${color.bold(formatNumber(balance.balance))} left ${color.dim(
+    `/ ${formatNumber(used)} used`
+  )}`;
+}
+
+/**
+ * Rate-limit headroom, shown only when it is worth knowing. At full headroom
+ * the line is noise; as it runs down it becomes the explanation for a refusal
+ * the user is about to hit.
+ */
+function limitSummary(info) {
+  const limits = info.balance?.limits;
+  if (!limits) return null;
+  const parts = [];
+  for (const [name, rule] of Object.entries(limits)) {
+    if (!rule || typeof rule.remaining !== "number") continue;
+    if (rule.remaining === rule.limit) continue;
+    const label = `${rule.remaining}/${rule.limit} ${name}s left this hour`;
+    parts.push(rule.remaining === 0 ? color.yellow(label) : color.dim(label));
+  }
+  return parts.length ? parts.join(color.dim(" · ")) : null;
+}
+
+/**
+ * The one-line "what do I do next" hint, driven by whatever is most broken.
+ * Inside the shell the fix is a slash command; outside it is a real command,
+ * so the hint has to know where it is being shown.
+ */
+function nextStep(info, { inShell = false } = {}) {
+  const login = inShell ? "/login" : "`devmp login`";
+  const doctor = inShell ? "/doctor" : "`devmp doctor`";
+  if (!info.signedIn) return `Run ${login} to connect your account`;
+  if (info.reachable === false) return `Run ${doctor} — the API is unreachable`;
+  if (info.authFailed) return `Run ${login} — your session expired`;
+  if (info.balance && !info.balance.provisioned) {
+    return "Ask an admin for a token grant";
+  }
+  if (info.balance && info.balance.balance <= 0) {
+    return "You are out of tokens for this month";
+  }
+  return inShell ? "Type a task, or /help for commands" : "Run `devmp` to start";
+}
+
+/**
+ * Name the environment from the API URL actually in use. Falls back to the
+ * requested env only when there is no URL to judge by.
+ */
+function describeEnv(apiBaseUrl, requestedEnv) {
+  if (!apiBaseUrl) return requestedEnv || null;
+  let host;
+  try {
+    host = new URL(apiBaseUrl).hostname;
+  } catch {
+    return requestedEnv || null;
+  }
+  const isLocal =
+    host === "localhost" || host === "127.0.0.1" || host.endsWith(".local");
+  const actual = isLocal ? "local" : "production";
+  if (requestedEnv && requestedEnv !== actual) {
+    // Flag the divergence rather than quietly reporting the wrong one.
+    return `${actual} ${color.dim("· from saved session, not this invocation")}`;
+  }
+  return actual;
+}
+
+function statusHeadline(info) {
+  if (!info.signedIn) return color.yellow("Signed out");
+  if (info.reachable === false) return color.yellow("Signed in, API unreachable");
+  if (info.authFailed) return color.yellow("Session expired");
+  if (info.balance && !info.balance.provisioned) {
+    return color.yellow("Needs access provisioning");
+  }
+  if (info.balance && info.balance.balance <= 0) return color.yellow("No tokens left");
+  return color.green("Ready");
+}
+
+/** The opening card. Returns lines; the caller decides where they go. */
+function renderStatusCard(info, { rootDir, env, inShell = false } = {}) {
+  const rows = [
+    fmt.pair("Status", statusHeadline(info)),
+    fmt.pair("Account", info.account || color.dim("not signed in")),
+    fmt.pair("Tokens", tokenSummary(info)),
+  ];
+  if (info.balance?.provisioned && info.balance.resetsAt) {
+    rows.push(fmt.pair("Resets", formatDate(info.balance.resetsAt)));
+  }
+  const limits = limitSummary(info);
+  if (limits) rows.push(fmt.pair("Limits", limits));
+  // The flag says which environment was *requested*; the session keeps talking
+  // to whatever backend it was created against. Reporting the flag while the
+  // API line shows localhost is how you get "Env production" over a local API.
+  const effectiveEnv = describeEnv(info.apiBaseUrl, env);
+  if (effectiveEnv) rows.push(fmt.pair("Env", effectiveEnv));
+  rows.push(fmt.pair("API", color.dim(info.apiBaseUrl || "—")));
+  if (rootDir) {
+    const home = os.homedir();
+    const shown = rootDir.startsWith(home)
+      ? `~${rootDir.slice(home.length)}`
+      : rootDir;
+    rows.push(fmt.pair("Workspace", shown));
+  }
+  if (info.git?.isRepo) {
+    rows.push(
+      fmt.pair(
+        "Git",
+        `${info.git.branch} ${color.dim(`· ${info.git.changed} changed`)}`
+      )
+    );
+  }
+  rows.push(fmt.pair("Next", color.dim(nextStep(info, { inShell }))));
+  return box(rows, { title: fmt.banner() });
+}
+
+/** Detailed `/doctor` output: what is configured and what actually works. */
+async function renderDoctor({ config, session, rootDir, inShell = false }) {
+  const login = inShell ? "/login" : "`devmp login`";
+  const lines = [];
+  lines.push(...fmt.section("Doctor"));
+  // The saved session's URL wins over the flag when no target was named this
+  // invocation, so report where we will actually go — the status card already
+  // does this, and a doctor that disagrees with it is worse than no doctor.
+  const apiBaseUrl = session?.apiBaseUrl || config?.apiBaseUrl || null;
+  lines.push(
+    fmt.line("Environment", describeEnv(apiBaseUrl, config?.env) || "unknown"),
+  );
+  lines.push(fmt.line("API", apiBaseUrl || "—"));
+  lines.push(fmt.line("Frontend", config?.frontendBaseUrl || "—"));
+  lines.push(fmt.line("Auth file", sessionPath()));
+  lines.push(fmt.line("Node", process.version));
+  lines.push(fmt.line("Workspace", rootDir || process.cwd()));
+
+  if (typeof WebSocket !== "function") {
+    lines.push(
+      fmt.fail("This Node build has no global WebSocket — Node 22+ is required.")
+    );
+  }
+
+  if (!session) {
+    lines.push(fmt.warn(`Not signed in. Run ${login}.`));
+    return lines;
+  }
+
+  const info = await collectStatus({ session });
+  if (info.reachable === false) {
+    lines.push(fmt.fail(`API unreachable — ${info.error || "no response"}.`));
+    lines.push(
+      color.dim("  Start the backend, or pass --local / --api-base-url.")
+    );
+    return lines;
+  }
+  if (info.authFailed) {
+    lines.push(fmt.fail(`Authentication failed. Run ${login}.`));
+    return lines;
+  }
+  if (info.balance && !info.balance.provisioned) {
+    lines.push(fmt.warn("Signed in, but agent access is not provisioned."));
+    return lines;
+  }
+  lines.push(fmt.success("Authenticated API access works."));
+  return lines;
+}
+
+module.exports = {
+  collectStatus,
+  renderStatusCard,
+  renderDoctor,
+  tokenSummary,
+  nextStep,
+  statusHeadline,
+};

package/lib/tty/ansi.js

@@ -0,0 +1,171 @@
+"use strict";
+
+// Terminal measurement primitives. Everything above this layer reasons in
+// "display columns", never in string length — a styled or emoji-bearing line is
+// nothing like `str.length` wide, and the live-region renderer has to know
+// exactly how many rows it painted in order to erase them again.
+
+const ANSI_GLOBAL = /\x1b\[[0-9;]*[a-zA-Z]/g;
+const ANSI_EXACT = /^\x1b\[[0-9;]*[a-zA-Z]$/;
+
+const cursor = {
+  up: (n) => (n > 0 ? `\x1b[${n}A` : ""),
+  down: (n) => (n > 0 ? `\x1b[${n}B` : ""),
+  right: (n) => (n > 0 ? `\x1b[${n}C` : ""),
+  toColumn0: "\r",
+  hide: "\x1b[?25l",
+  show: "\x1b[?25h",
+  // Erase from the cursor to the end of the screen.
+  eraseDown: "\x1b[0J",
+};
+
+function stripAnsi(value) {
+  return String(value).replace(ANSI_GLOBAL, "");
+}
+
+function isAnsi(token) {
+  return ANSI_EXACT.test(token);
+}
+
+// Code points that occupy two columns in a monospace terminal: CJK, Hangul and
+// the emoji planes. Zero-width joiners, variation selectors and combining marks
+// occupy none; everything else is one.
+function codePointWidth(cp) {
+  if (cp === 0x200d) return 0;
+  if (cp >= 0xfe00 && cp <= 0xfe0f) return 0;
+  if (cp >= 0x0300 && cp <= 0x036f) return 0;
+  if (
+    (cp >= 0x1100 && cp <= 0x115f) ||
+    (cp >= 0x2e80 && cp <= 0xa4cf) ||
+    (cp >= 0xac00 && cp <= 0xd7a3) ||
+    (cp >= 0xf900 && cp <= 0xfaff) ||
+    (cp >= 0xfe30 && cp <= 0xfe6f) ||
+    (cp >= 0xff00 && cp <= 0xff60) ||
+    (cp >= 0xffe0 && cp <= 0xffe6) ||
+    (cp >= 0x1f300 && cp <= 0x1f64f) ||
+    (cp >= 0x1f680 && cp <= 0x1f6ff) ||
+    (cp >= 0x1f900 && cp <= 0x1f9ff) ||
+    (cp >= 0x20000 && cp <= 0x3fffd)
+  ) {
+    return 2;
+  }
+  return 1;
+}
+
+/** Display columns a string occupies once styling is removed. */
+function displayWidth(value) {
+  const plain = stripAnsi(value);
+  let width = 0;
+  for (const char of plain) {
+    const cp = char.codePointAt(0);
+    if (cp === 0x09) {
+      width += 2;
+      continue;
+    }
+    if (cp < 0x20 || (cp >= 0x7f && cp < 0xa0)) continue;
+    width += codePointWidth(cp);
+  }
+  return width;
+}
+
+/**
+ * How many terminal rows one logical line consumes at `columns` wide. An empty
+ * line still occupies a row; a line that exactly fills the width does not spill
+ * into a second one.
+ */
+function rowsFor(value, columns) {
+  const width = displayWidth(value);
+  if (width === 0) return 1;
+  return Math.max(1, Math.ceil(width / Math.max(1, columns)));
+}
+
+function totalRows(lines, columns) {
+  let rows = 0;
+  for (const item of lines) rows += rowsFor(item, columns);
+  return rows;
+}
+
+/**
+ * Hard-wrap a styled string at `columns`, keeping ANSI sequences attached to
+ * the segment they style and never counting them against the budget. Splits on
+ * word boundaries where it can and mid-word when a single token is too long.
+ */
+function wrap(value, columns) {
+  const limit = Math.max(1, columns);
+  if (displayWidth(value) <= limit) return [value];
+
+  const out = [];
+  let line = "";
+  let lineWidth = 0;
+
+  const pushLine = () => {
+    out.push(line);
+    line = "";
+    lineWidth = 0;
+  };
+
+  // Break a token wider than the whole terminal into column-sized chunks and
+  // return whatever tail still fits on a fresh row.
+  const chunkOversized = (token) => {
+    let rest = token;
+    while (displayWidth(rest) > limit) {
+      let taken = "";
+      let takenWidth = 0;
+      for (const char of rest) {
+        const charWidth = displayWidth(char);
+        if (takenWidth + charWidth > limit) break;
+        taken += char;
+        takenWidth += charWidth;
+      }
+      // A single glyph wider than the terminal would otherwise loop forever.
+      if (!taken) return rest;
+      out.push(taken);
+      rest = rest.slice(taken.length);
+    }
+    return rest;
+  };
+
+  // Split into tokens that are either a whole ANSI sequence or a run of text,
+  // so we can measure text while carrying styling through untouched.
+  const tokens = String(value).split(/(\x1b\[[0-9;]*[a-zA-Z]|\s+)/);
+  for (const token of tokens) {
+    if (!token) continue;
+
+    if (isAnsi(token)) {
+      line += token;
+      continue;
+    }
+
+    const width = displayWidth(token);
+    if (lineWidth + width <= limit) {
+      line += token;
+      lineWidth += width;
+      continue;
+    }
+
+    // Whitespace at a wrap point is absorbed rather than starting a blank row.
+    if (/^\s+$/.test(token)) {
+      if (lineWidth > 0) pushLine();
+      continue;
+    }
+
+    if (lineWidth > 0) pushLine();
+
+    const tail = width > limit ? chunkOversized(token) : token;
+    line = tail;
+    lineWidth = displayWidth(tail);
+  }
+
+  if (line || out.length === 0) out.push(line);
+  return out;
+}
+
+module.exports = {
+  cursor,
+  stripAnsi,
+  isAnsi,
+  displayWidth,
+  rowsFor,
+  totalRows,
+  wrap,
+};