@xevy/cli 0.1.23 → 0.1.24

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
@@ -58,7 +58,10 @@ OAuth.
58
58
  xevy # open an interactive pi session with Xevy loaded
59
59
  xevy "summarise this repo" # or send a one-off prompt
60
60
  xevy dev task/VI22-07 # attach to a task's remote Dev Session
61
- xevy dev xevy/xevyai # start or resume your personal project session
61
+ xevy dev xevy/xevyai # select a running project workspace
62
+ xevy dev xevy/xevyai --new # create another workspace
63
+ xevy dev session/<uuid> # open one exact session
64
+ xevy dev session/<uuid> --rename "Checkout fix" # change its display name
62
65
  ```
63
66
 
64
67
  That's it — you're set up. The sections below are reference for when you need more detail.
@@ -148,12 +151,14 @@ xevy "summarise this repo" # forwards the prompt to pi
148
151
 
149
152
  ## `xevy dev`
150
153
 
151
- Connect an interactive terminal to a task or personal remote Dev Session:
154
+ Connect an interactive terminal to a task-linked or task-free remote Dev Session:
152
155
 
153
156
  ```bash
154
157
  xevy dev task/VI22-07
155
158
  xevy dev task/cb49c02e-66d8-4475-95a8-6f3930643ec8
156
- xevy dev xevy/xevyai
159
+ xevy dev xevy/xevyai --new
160
+ xevy dev xevy/xevyai --request-key <uuid>
161
+ xevy dev session/<uuid> --rename "Checkout fix"
157
162
  xevy dev xevy/xevyai --base https://xevy.example.com
158
163
  ```
159
164
 
@@ -163,7 +168,7 @@ a `Ctrl+C` detach hint; press `Ctrl+]` while attached to leave the Dev Session
163
168
  running immediately.
164
169
 
165
170
  The CLI grammar is explicit: `task/<task-id-or-code>` selects a task session,
166
- while `<workspace>/<project>` selects your default personal project session.
171
+ while `<workspace>/<project>` selects your default task-free project workspace.
167
172
  Bare task IDs, aliases, and scope-guessing are intentionally unsupported. After
168
173
  the target is resolved, the CLI renders Pi's native TUI from the isolated remote
169
174
  workspace: normal composer, thinking, tools, history, keyboard shortcuts, and
@@ -233,3 +238,5 @@ See the [`@xevy/skills` README](../xevy-skills/README.md) for the full command l
233
238
  per-agent flags, and manual install steps.
234
239
 
235
240
  Docs: <https://xevy.ai/docs/mcp>
241
+
242
+ New workspaces open the editor and terminal first. Start repository runtimes when you need a preview. Each new task-free session has a separate branch. The CLI prints a request UUID before creation; repeat it with `--request-key` if the response is lost.
@@ -1,3 +1,4 @@
1
+ import { randomUUID } from "node:crypto";
1
2
  import { spawn } from "node:child_process";
2
3
  import readline from "node:readline";
3
4
  import WebSocket from "ws";
@@ -21,13 +22,17 @@ const DEV_TARGET_SEGMENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
21
22
  function parseDevTarget(value) {
22
23
  const reference = String(value || "").trim();
23
24
  const segments = reference.split("/");
24
- const usage = "Use `task/<task-id-or-code>` or `<workspace>/<project>`.";
25
+ const usage = "Use `session/<session-id>`, `task/<task-id-or-code>` or `<workspace>/<project>`.";
25
26
  if (segments.length !== 2 || segments.some((segment) => !segment)) {
26
27
  throw new Error(`Invalid Dev Session target '${reference}'. ${usage}`);
27
28
  }
28
29
  if (segments.some((segment) => !DEV_TARGET_SEGMENT_PATTERN.test(segment))) {
29
30
  throw new Error(`Invalid Dev Session target '${reference}'. Identifiers may use letters, numbers, '.', '_', and '-'.`);
30
31
  }
32
+ if (segments[0] === "session") {
33
+ if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(segments[1])) throw new Error("Use a session UUID after session/.");
34
+ return { kind: "session", sessionId: segments[1] };
35
+ }
31
36
  if (segments[0] === "task") {
32
37
  return { kind: "task", taskReference: segments[1] };
33
38
  }
@@ -76,9 +81,25 @@ export function parseDevCommandArgs(argv) {
76
81
  const args = [...argv];
77
82
  let targetReference = "";
78
83
  let base = null;
84
+ let newSession = false;
85
+ let requestKey;
86
+ let rename;
79
87
  while (args.length > 0) {
80
88
  const argument = args.shift();
81
89
  if (argument === "-h" || argument === "--help") return { help: true, target: null, base: null };
90
+ if (argument === "--new") { newSession = true; continue; }
91
+ if (argument === "--request-key" || argument === "--rename") {
92
+ const value = args.shift();
93
+ if (!value) throw new Error(`Missing value for ${argument}`);
94
+ if (argument === "--request-key") {
95
+ if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(value)) throw new Error("--request-key must be a UUID.");
96
+ requestKey = value; newSession = true;
97
+ } else {
98
+ rename = value.trim();
99
+ if (!rename || rename.length > 80 || /\p{Cc}/u.test(rename)) throw new Error("--rename needs a single-line name of 1–80 characters.");
100
+ }
101
+ continue;
102
+ }
82
103
  if (argument === "--base") {
83
104
  const value = args.shift();
84
105
  if (!value) throw new Error("Missing value for --base");
@@ -92,7 +113,10 @@ export function parseDevCommandArgs(argv) {
92
113
  if (!targetReference) {
93
114
  throw new Error("Usage: xevy dev <task/<task-id-or-code>|workspace/project> [--base <url>]");
94
115
  }
95
- return { help: false, target: parseDevTarget(targetReference), base };
116
+ const target = parseDevTarget(targetReference);
117
+ if (newSession && target.kind !== "personal") throw new Error("--new and --request-key apply to workspace/project targets.");
118
+ if (rename && target.kind !== "session") throw new Error("--rename requires session/<session-id>.");
119
+ return { help: false, target, base, ...(newSession ? { newSession } : {}), ...(requestKey ? { requestKey } : {}), ...(rename ? { rename } : {}) };
96
120
  }
97
121
 
98
122
  export function resolveDevConnection({
@@ -626,13 +650,18 @@ function sessionSummary(context, session, base, writeLine) {
626
650
  const url = task
627
651
  ? devSessionLaunchUrl(base, task)
628
652
  : new URL(`/agent?session=${encodeURIComponent(session.id)}`, `${normalizeBaseUrl(base)}/`).toString();
629
- writeLine("\nDev Session");
653
+ writeLine(`\nDev Session${session.title ? ` · ${session.title}` : ""}`);
630
654
  if (task) writeLine(` Task ${formatTask(task)}`);
631
- else writeLine(` Project ${context.workspace.identifier}/${context.project.identifier} · Personal`);
655
+ else writeLine(` Project ${context.workspace.identifier}/${context.project.identifier}`);
632
656
  writeLine(` Workbench ${url || "not available yet"}`);
633
- writeLine(` Preview ${session.config?.runtimeMode === "none" || !session.hostname ? "none (workspace only)" : `https://${session.hostname}`}`);
657
+ const health = session.runtimeHealth || session.config?.runtimeHealth;
658
+ const preview = health?.status === "stopped" ? "stopped · start a runtime in the workbench"
659
+ : health && health.status !== "ready" ? health.status
660
+ : session.config?.runtimeMode === "none" || !session.hostname ? "none (workspace only)" : `https://${session.hostname}`;
661
+ writeLine(` Preview ${preview}`);
634
662
  writeLine(` Branch ${session.branch || session.config?.branch || "unknown"}`);
635
663
  writeLine(` Status ${session.status}`);
664
+ if (session.runtimeHealth) writeLine(` Runtime ${session.runtimeHealth.status}${session.runtimeHealth.error ? ` · ${session.runtimeHealth.error.message}` : ""}`);
636
665
  writeLine(` Expires ${session.expiresAt || "server-managed"}`);
637
666
  writeLine("\nXevy terminal · press Ctrl+] to detach and leave it running\n");
638
667
  }
@@ -835,6 +864,8 @@ function commandHelp(writeLine, hasWebPreview = true) {
835
864
  writeLine("Commands:");
836
865
  writeLine(" /status Refresh session status");
837
866
  writeLine(" /logs Show the latest Dev Session logs");
867
+ writeLine(" /merge-main Merge current main into the workspace");
868
+ if (hasWebPreview) writeLine(" /retry Retry preview setup in the current workspace");
838
869
  if (hasWebPreview) writeLine(" /open Open a fresh one-use Dev Session URL");
839
870
  writeLine(" /finish Save the task branch and stop");
840
871
  writeLine(" /stop Stop the Dev Session without finishing");
@@ -882,7 +913,7 @@ export async function runDevSession(options) {
882
913
  throw new Error("A Xevy API key is required. Run `xevy setup --credentials` first.");
883
914
  }
884
915
  const target = options.target;
885
- if (!target || !["task", "personal"].includes(target.kind)) {
916
+ if (!target || !["task", "personal", "session"].includes(target.kind)) {
886
917
  throw new Error("Usage: xevy dev <task/<task-id-or-code>|workspace/project> [--base <url>]");
887
918
  }
888
919
 
@@ -959,7 +990,24 @@ export async function runDevSession(options) {
959
990
  try {
960
991
  // Validate both host and key before resolving any session context.
961
992
  await api.request("/api/profile", { signal: detachController.signal });
962
- if (target.kind === "task") {
993
+ if (target.kind === "session") {
994
+ sessionPath = `/api/agent/dev-sessions/${encodeURIComponent(target.sessionId)}`;
995
+ const current = await api.request(sessionPath, { signal: detachController.signal });
996
+ session = current?.session;
997
+ if (!session) throw new Error("Dev Session not found.");
998
+ if (options.rename) {
999
+ const updated = await api.request(sessionPath, { method: "PATCH", body: { name: options.rename }, signal: detachController.signal });
1000
+ session = updated?.session || session;
1001
+ writeLine("Dev Session renamed.");
1002
+ }
1003
+ if (session.task) {
1004
+ task = { ...session.task, workspaceIdentifier: session.workspace.identifier, projectIdentifier: session.project.identifier };
1005
+ context = { kind: "task", task };
1006
+ } else {
1007
+ context = { kind: "personal", workspace: session.workspace, project: session.project };
1008
+ }
1009
+ writeLine(`Opening ${session.title || "Dev Session"}…`);
1010
+ } else if (target.kind === "task") {
963
1011
  const search = await api.request("/api/tasks/search", {
964
1012
  method: "POST",
965
1013
  body: { taskIdentifier: target.taskReference },
@@ -1014,12 +1062,15 @@ export async function runDevSession(options) {
1014
1062
  `/api/agent/dev-session-candidates?projectId=${encodeURIComponent(project.id)}`,
1015
1063
  { signal: detachController.signal },
1016
1064
  );
1017
- const existingSessionId = candidates?.personal?.existingSessionId || null;
1065
+ const running = candidates?.personal?.existingSessions?.length ? candidates.personal.existingSessions
1066
+ : candidates?.personal?.existingSessionId ? [{ id: candidates.personal.existingSessionId, title: "Running workspace" }] : [];
1067
+ const choice = options.newSession ? null : await selectOne({ items: running, label: "sessions", describe: (item) => `${item.title} · ${item.id}`, interactive, ask, writeLine });
1068
+ const existingSessionId = choice?.id || null;
1018
1069
  if (existingSessionId) {
1019
1070
  sessionPath = `/api/agent/dev-sessions/${encodeURIComponent(existingSessionId)}`;
1020
1071
  const current = await api.request(sessionPath, { signal: detachController.signal });
1021
1072
  session = current?.session || null;
1022
- if (session) writeLine("Attaching to your existing personal Dev Session…");
1073
+ if (session) writeLine("Opening your running Dev Session…");
1023
1074
  }
1024
1075
  if (!session) {
1025
1076
  const repositories = candidates?.repositories || [];
@@ -1034,12 +1085,15 @@ export async function runDevSession(options) {
1034
1085
  ask,
1035
1086
  writeLine,
1036
1087
  });
1037
- writeLine(`Starting personal Dev Session with ${repository.displayName || repository.role}…`);
1088
+ writeLine(`Starting new Dev Session with ${repository.displayName || repository.role}…`);
1089
+ const requestKey = options.requestKey || randomUUID();
1090
+ writeLine(`New request ${requestKey} · retry safely with --request-key ${requestKey}`);
1038
1091
  const started = await api.request("/api/agent/dev-sessions", {
1039
1092
  method: "POST",
1040
1093
  body: {
1041
1094
  target: {
1042
1095
  kind: "personal",
1096
+ requestKey,
1043
1097
  projectId: project.id,
1044
1098
  runtimeRepositoryId: repository.id,
1045
1099
  },
@@ -1087,7 +1141,7 @@ export async function runDevSession(options) {
1087
1141
  if (interactive && nativeTerminal) {
1088
1142
  const reattachTarget = context.kind === "task"
1089
1143
  ? `task/${task.taskCode || task.id}`
1090
- : `${context.workspace.identifier}/${context.project.identifier}`;
1144
+ : `session/${session.id}`;
1091
1145
  await attachNativeTerminalOnce({
1092
1146
  api,
1093
1147
  base,
@@ -1165,6 +1219,18 @@ export async function runDevSession(options) {
1165
1219
  if (!(logs?.lines || []).length) writeLine("No Dev Session logs yet.");
1166
1220
  continue;
1167
1221
  }
1222
+ if (prompt === "/merge-main") {
1223
+ const result = await api.request(`/api/agent/dev-sessions/${encodeURIComponent(session.id)}/merge-main`, { method: "POST", body: {}, timeoutMs: 220_000, signal: detachController.signal });
1224
+ for (const repo of result.repositories || []) writeLine(`${repo.dir}: ${repo.status} · ${repo.baseBranch}@${repo.baseSha}${repo.message ? ` · ${repo.message}` : ""}`);
1225
+ if (result.session) session = { ...session, status: result.session.state, runtimeHealth: result.session.runtimeHealth };
1226
+ continue;
1227
+ }
1228
+ if (prompt === "/retry") {
1229
+ const result = await api.request(`/api/agent/dev-sessions/${encodeURIComponent(session.id)}/retry-runtime`, { method: "POST", body: {}, signal: detachController.signal });
1230
+ session = result.session;
1231
+ writeLine("Preview retry started in the current workspace. Use /status or /logs to follow it.");
1232
+ continue;
1233
+ }
1168
1234
  if (prompt === "/open") {
1169
1235
  if (session.config?.runtimeMode === "none" || !session.hostname) {
1170
1236
  writeLine("This Dev Session has no web runtime or live preview.");
package/bin/xevy.mjs CHANGED
@@ -98,7 +98,7 @@ function usage() {
98
98
  xevy setup [options] Choose credentials, pi, skills, and MCP setup
99
99
  xevy update [--base u] Refresh the pi extensions + coding-agent skills/MCP
100
100
  xevy check [--base u] Report skill updates or missing coding-agent targets
101
- xevy dev <target> Attach to a remote task or personal Dev Session
101
+ xevy dev <target> Attach to a remote task or task-free Dev Session
102
102
 
103
103
  Options:
104
104
  --base <url> Xevy host (default: XEVY_BASE or ${DEFAULT_BASE})
@@ -134,11 +134,13 @@ function devUsage() {
134
134
  console.log(`Xevy Dev Session
135
135
 
136
136
  xevy dev task/<task-id-or-code> [--base <url>]
137
- xevy dev <workspace>/<project> [--base <url>]
137
+ xevy dev <workspace>/<project> [--new] [--request-key <uuid>] [--base <url>]
138
+ xevy dev session/<session-id> [--rename <name>] [--base <url>]
138
139
 
139
140
  Connects this terminal to a remote Dev Session. The reserved task/ prefix
140
- selects task work; a workspace/project target starts or resumes your personal
141
- project session. Xevy runs inside the isolated remote workspace.
141
+ selects task work; workspace/project selects a running workspace. Use --new
142
+ for another session, and reuse --request-key after a failed create. A session/
143
+ target opens one exact workspace and --rename changes its display name. Xevy runs inside the isolated remote workspace.
142
144
 
143
145
  Terminal control:
144
146
  Ctrl+] Detach without stopping Xevy or the Dev Session
@@ -163,7 +165,7 @@ function parseArgv(argv) {
163
165
  try {
164
166
  const parsed = parseDevCommandArgs(args);
165
167
  if (parsed.help) return { command: "dev-help" };
166
- return { command: "dev", target: parsed.target, base: parsed.base };
168
+ return { command: "dev", ...parsed };
167
169
  } catch (error) {
168
170
  die(error instanceof Error ? error.message : String(error));
169
171
  }
@@ -748,6 +750,9 @@ async function dev(opts) {
748
750
  base,
749
751
  token,
750
752
  target: opts.target,
753
+ newSession: opts.newSession,
754
+ requestKey: opts.requestKey,
755
+ rename: opts.rename,
751
756
  });
752
757
  }
753
758
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xevy/cli",
3
- "version": "0.1.23",
3
+ "version": "0.1.24",
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": [