@xevy/cli 0.1.15 → 0.1.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -149,6 +149,11 @@ xevy dev cb49c02e-66d8-4475-95a8-6f3930643ec8
149
149
  xevy dev VI22-07 --base https://xevy.example.com
150
150
  ```
151
151
 
152
+ The command stays attached across normal Pi exits and transient terminal
153
+ disconnects. It shows startup/restart status while the remote terminal is being
154
+ prepared; press `Ctrl+]` to detach intentionally and leave the Dev Session
155
+ running.
156
+
152
157
  The CLI resolves an exact task ID or task code, attaches to its existing Dev
153
158
  Session, or starts one from a linked repository. It then renders Pi's native TUI
154
159
  from the isolated remote workspace: normal composer, thinking, tools, history,
@@ -13,6 +13,10 @@ const HEARTBEAT_INTERVAL_MS = 60_000;
13
13
  const SESSION_POLL_INTERVAL_MS = 2_000;
14
14
  const SESSION_START_TIMEOUT_MS = 10 * 60_000;
15
15
  const EXECUTION_RECONNECT_LIMIT = 8;
16
+ const TERMINAL_RECONNECT_LIMIT = 8;
17
+ const TERMINAL_RECONNECT_MAX_DELAY_MS = 5_000;
18
+ const TERMINAL_STABLE_RUNTIME_MS = 10_000;
19
+ const TERMINAL_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
16
20
 
17
21
  export function parseCredentialsText(source) {
18
22
  const values = {};
@@ -240,13 +244,12 @@ export function createApiClient({ base, token, fetchImpl, registerController, se
240
244
  return { request };
241
245
  }
242
246
 
243
- function canonicalSessionUrl(hostname) {
244
- if (!hostname) return null;
245
- const candidate = /^https?:\/\//i.test(hostname) ? hostname : `https://${hostname}`;
246
- const parsed = new URL(candidate);
247
- const local = ["localhost", "127.0.0.1", "::1"].includes(parsed.hostname);
248
- if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) return null;
249
- return parsed.toString().replace(/\/$/, "");
247
+ export function devSessionLaunchUrl(base, task) {
248
+ const origin = normalizeBaseUrl(base);
249
+ return new URL(
250
+ `/${encodeURIComponent(task.workspaceIdentifier)}/${encodeURIComponent(task.projectIdentifier)}/task/${encodeURIComponent(task.id)}/dev-session/open`,
251
+ `${origin}/`,
252
+ ).toString();
250
253
  }
251
254
 
252
255
  function formatTask(task) {
@@ -538,8 +541,66 @@ async function waitForReady({ api, sessionPath, initialSession, writeLine, sleep
538
541
  return session;
539
542
  }
540
543
 
541
- function sessionSummary(task, session, writeLine) {
542
- const url = canonicalSessionUrl(session.hostname);
544
+ /** A deliberately restrained terminal status indicator. It animates only on
545
+ * the real interactive stdout; redirected output, CI, and tests receive stable
546
+ * newline-delimited status messages. */
547
+ export function createTerminalStatus({ output, writeLine, animate }) {
548
+ const shouldAnimate = animate ?? Boolean(
549
+ output === process.stdout
550
+ && output.isTTY
551
+ && !process.env.CI
552
+ && process.env.TERM !== "dumb",
553
+ );
554
+ let label = "";
555
+ let previousStaticLabel = "";
556
+ let frame = 0;
557
+ let timer = null;
558
+ let painted = false;
559
+
560
+ const render = () => {
561
+ if (!label) return;
562
+ painted = true;
563
+ output.write(`\r\x1b[2K${TERMINAL_SPINNER_FRAMES[frame % TERMINAL_SPINNER_FRAMES.length]} ${label}`);
564
+ frame += 1;
565
+ };
566
+ const clear = () => {
567
+ if (timer) clearInterval(timer);
568
+ timer = null;
569
+ if (painted) output.write("\r\x1b[2K");
570
+ painted = false;
571
+ };
572
+
573
+ return {
574
+ update(nextLabel) {
575
+ label = String(nextLabel || "");
576
+ if (!label) return;
577
+ if (!shouldAnimate) {
578
+ if (label !== previousStaticLabel) writeLine(label);
579
+ previousStaticLabel = label;
580
+ return;
581
+ }
582
+ if (!timer) {
583
+ render();
584
+ timer = setInterval(render, 80);
585
+ timer.unref?.();
586
+ }
587
+ },
588
+ succeed(finalLabel) {
589
+ clear();
590
+ label = "";
591
+ previousStaticLabel = "";
592
+ if (finalLabel) writeLine(`✓ ${finalLabel}`);
593
+ },
594
+ stop() {
595
+ clear();
596
+ label = "";
597
+ previousStaticLabel = "";
598
+ },
599
+ };
600
+ }
601
+
602
+ function sessionSummary(task, session, base, writeLine) {
603
+ const url = devSessionLaunchUrl(base, task);
543
604
  writeLine("\nDev Session");
544
605
  writeLine(` Task ${formatTask(task)}`);
545
606
  writeLine(` Site ${url || "not available yet"}`);
@@ -549,13 +610,22 @@ function sessionSummary(task, session, writeLine) {
549
610
  writeLine("\nNative Pi terminal · press Ctrl+] to detach and leave it running\n");
550
611
  }
551
612
 
552
- async function attachNativeTerminal({ api, base, sessionPath, input, output, signal, WebSocketImpl = WebSocket }) {
613
+ async function attachNativeTerminal({
614
+ api,
615
+ base,
616
+ sessionPath,
617
+ input,
618
+ output,
619
+ signal,
620
+ onReady,
621
+ WebSocketImpl = WebSocket,
622
+ }) {
553
623
  const ticket = await api.request(`${sessionPath}/terminal-ticket`, { method: "POST", body: {}, signal });
554
624
  if (!ticket?.ticket || !ticket?.terminalPath) throw new Error("Xevy did not return a terminal ticket.");
555
625
  const url = new URL(ticket.terminalPath, `${base}/`);
556
626
  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
557
627
 
558
- await new Promise((resolve, reject) => {
628
+ return new Promise((resolve, reject) => {
559
629
  const socket = new WebSocketImpl(url, {
560
630
  headers: { "X-Xevy-Terminal-Ticket": ticket.ticket },
561
631
  maxPayload: 2 * 1024 * 1024,
@@ -563,12 +633,16 @@ async function attachNativeTerminal({ api, base, sessionPath, input, output, sig
563
633
  let ready = false;
564
634
  let settled = false;
565
635
  let rawEnabled = false;
636
+ let detachedByUser = false;
637
+ const connectedAt = Date.now();
638
+ const pendingOutput = [];
566
639
  const onAbort = () => {
640
+ detachedByUser = true;
567
641
  if (socket.readyState === WebSocketImpl.OPEN) socket.close(1000, "client_detach");
568
642
  else socket.terminate?.();
569
- finish(new Error("Detached."));
643
+ finish(null, { reason: "detached", code: 1000, durationMs: Date.now() - connectedAt });
570
644
  };
571
- const finish = (error) => {
645
+ const finish = (error, result) => {
572
646
  if (settled) return;
573
647
  settled = true;
574
648
  input.off("data", onInput);
@@ -576,7 +650,7 @@ async function attachNativeTerminal({ api, base, sessionPath, input, output, sig
576
650
  signal?.removeEventListener("abort", onAbort);
577
651
  if (rawEnabled && typeof input.setRawMode === "function") input.setRawMode(false);
578
652
  if (error) reject(error);
579
- else resolve();
653
+ else resolve(result);
580
654
  };
581
655
  const sendResize = () => {
582
656
  if (socket.readyState !== WebSocketImpl.OPEN) return;
@@ -591,12 +665,13 @@ async function attachNativeTerminal({ api, base, sessionPath, input, output, sig
591
665
  const value = Buffer.from(chunk);
592
666
  const detachAt = value.indexOf(0x1d);
593
667
  if (detachAt >= 0) {
668
+ detachedByUser = true;
594
669
  if (detachAt > 0 && socket.readyState === WebSocketImpl.OPEN) {
595
670
  socket.send(value.subarray(0, detachAt), { binary: true });
596
671
  }
597
672
  output.write("\r\nDetached. Pi and the Dev Session are still running.\r\n");
598
673
  socket.close(1000, "client_detach");
599
- finish();
674
+ finish(null, { reason: "detached", code: 1000, durationMs: Date.now() - connectedAt });
600
675
  return;
601
676
  }
602
677
  if (socket.readyState === WebSocketImpl.OPEN) socket.send(value, { binary: true });
@@ -610,13 +685,17 @@ async function attachNativeTerminal({ api, base, sessionPath, input, output, sig
610
685
 
611
686
  socket.on("message", (data, isBinary) => {
612
687
  if (isBinary) {
613
- output.write(Buffer.from(data));
688
+ const chunk = Buffer.from(data);
689
+ if (ready) output.write(chunk);
690
+ else pendingOutput.push(chunk);
614
691
  return;
615
692
  }
616
693
  let control;
617
694
  try { control = JSON.parse(data.toString()); } catch { return; }
618
695
  if (control.type === "ready" && !ready) {
619
696
  ready = true;
697
+ onReady?.();
698
+ for (const chunk of pendingOutput.splice(0)) output.write(chunk);
620
699
  if (typeof input.setRawMode === "function") {
621
700
  input.setRawMode(true);
622
701
  rawEnabled = true;
@@ -635,12 +714,85 @@ async function attachNativeTerminal({ api, base, sessionPath, input, output, sig
635
714
  socket.once("error", (error) => finish(new Error(`Dev Session terminal connection failed: ${error.message}`)));
636
715
  socket.once("close", (code) => {
637
716
  if (!ready && !settled) finish(new Error(`Dev Session terminal closed before it was ready (code ${code}).`));
638
- else if (ready && code !== 1000 && !settled) finish(new Error("Dev Session terminal connection was lost. Rerun `xevy dev` to reattach."));
639
- else finish();
717
+ else if (!settled) finish(null, {
718
+ reason: detachedByUser ? "detached" : code === 1000 ? "terminal-exit" : "transport-lost",
719
+ code,
720
+ durationMs: Date.now() - connectedAt,
721
+ });
640
722
  });
641
723
  });
642
724
  }
643
725
 
726
+ async function attachNativeTerminalPersistently({
727
+ api,
728
+ base,
729
+ sessionPath,
730
+ input,
731
+ output,
732
+ signal,
733
+ sleep,
734
+ writeLine,
735
+ WebSocketImpl,
736
+ animateStatus,
737
+ }) {
738
+ const status = createTerminalStatus({ output, writeLine, animate: animateStatus });
739
+ let reconnecting = false;
740
+ let consecutiveFailures = 0;
741
+ try {
742
+ while (!signal?.aborted) {
743
+ status.update(reconnecting ? "Restarting remote Pi terminal…" : "Starting remote Pi terminal…");
744
+ try {
745
+ const result = await attachNativeTerminal({
746
+ api,
747
+ base,
748
+ sessionPath,
749
+ input,
750
+ output,
751
+ signal,
752
+ onReady: () => status.succeed(reconnecting ? "Pi terminal restarted" : "Pi terminal ready"),
753
+ WebSocketImpl,
754
+ });
755
+ if (result?.reason === "detached") return;
756
+ reconnecting = true;
757
+ consecutiveFailures = result?.durationMs >= TERMINAL_STABLE_RUNTIME_MS
758
+ ? 0
759
+ : consecutiveFailures + 1;
760
+ status.update(result?.reason === "transport-lost"
761
+ ? "Terminal connection lost · reconnecting…"
762
+ : "Pi exited · restarting terminal…");
763
+ } catch (error) {
764
+ if (signal?.aborted) throw error;
765
+ if (error instanceof DevSessionApiError && ![409, 502, 503, 504].includes(error.status)) throw error;
766
+ reconnecting = true;
767
+ consecutiveFailures += 1;
768
+ status.update("Terminal is not ready yet · retrying…");
769
+ }
770
+
771
+ if (consecutiveFailures >= TERMINAL_RECONNECT_LIMIT) {
772
+ throw new Error("The remote Pi terminal repeatedly exited before stabilizing. The Dev Session remains active; check its logs and rerun `xevy dev` after correcting the startup error.");
773
+ }
774
+ await sleep(
775
+ Math.min(500 * 2 ** Math.max(0, consecutiveFailures - 1), TERMINAL_RECONNECT_MAX_DELAY_MS),
776
+ signal,
777
+ );
778
+ let current = null;
779
+ try {
780
+ current = await api.request(`${sessionPath}/`, { signal });
781
+ } catch (error) {
782
+ if (signal?.aborted) throw error;
783
+ if (error instanceof DevSessionApiError && [401, 403, 404].includes(error.status)) throw error;
784
+ status.update("Session status unavailable · retrying terminal…");
785
+ }
786
+ if (current && !current.session) throw new Error("The Dev Session disappeared while reconnecting the terminal.");
787
+ if (current?.session && SESSION_TERMINAL_STATUSES.has(current.session.status)) {
788
+ throw new Error(current.session.error || `Dev Session ${current.session.status}.`);
789
+ }
790
+ }
791
+ } finally {
792
+ status.stop();
793
+ }
794
+ }
795
+
644
796
  function commandHelp(writeLine) {
645
797
  writeLine("Commands:");
646
798
  writeLine(" /status Refresh session status");
@@ -838,19 +990,22 @@ export async function runDevSession(options) {
838
990
  sleep,
839
991
  signal: detachController.signal,
840
992
  });
841
- sessionSummary(task, session, writeLine);
993
+ sessionSummary(task, session, base, writeLine);
842
994
 
843
995
  const nativeTerminal = options.nativeTerminal
844
996
  ?? (input === process.stdin && output === process.stdout);
845
997
  if (interactive && nativeTerminal) {
846
- await attachNativeTerminal({
998
+ await attachNativeTerminalPersistently({
847
999
  api,
848
1000
  base,
849
1001
  sessionPath,
850
1002
  input,
851
1003
  output,
852
1004
  signal: detachController.signal,
1005
+ sleep,
1006
+ writeLine,
853
1007
  WebSocketImpl: options.webSocketImpl || WebSocket,
1008
+ animateStatus: options.animateStatus,
854
1009
  });
855
1010
  detached = true;
856
1011
  return { task, session, detached: true };
@@ -902,7 +1057,7 @@ export async function runDevSession(options) {
902
1057
  const result = await api.request(`${sessionPath}/`, { signal: detachController.signal });
903
1058
  if (!result?.session) throw new Error("No active Dev Session remains for this task.");
904
1059
  session = result.session;
905
- sessionSummary(task, session, writeLine);
1060
+ sessionSummary(task, session, base, writeLine);
906
1061
  continue;
907
1062
  }
908
1063
  if (prompt === "/logs") {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xevy/cli",
3
- "version": "0.1.15",
3
+ "version": "0.1.17",
4
4
  "description": "Xevy CLI — connect to remote Dev Sessions, configure credentials, pi, coding-agent skills, and MCP, and keep integrations current.",
5
5
  "type": "module",
6
6
  "keywords": [