@xevy/cli 0.1.18 → 0.1.19

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
@@ -57,7 +57,8 @@ OAuth.
57
57
  ```bash
58
58
  xevy # open an interactive pi session with Xevy loaded
59
59
  xevy "summarise this repo" # or send a one-off prompt
60
- xevy dev VI22-07 # attach to a task's remote Dev Session
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
62
  ```
62
63
 
63
64
  That's it — you're set up. The sections below are reference for when you need more detail.
@@ -140,13 +141,13 @@ xevy "summarise this repo" # forwards the prompt to pi
140
141
 
141
142
  ## `xevy dev`
142
143
 
143
- Connect an interactive terminal to the coding agent attached to a task's remote
144
- Dev Session:
144
+ Connect an interactive terminal to a task or personal remote Dev Session:
145
145
 
146
146
  ```bash
147
- xevy dev VI22-07
148
- xevy dev cb49c02e-66d8-4475-95a8-6f3930643ec8
149
- xevy dev VI22-07 --base https://xevy.example.com
147
+ xevy dev task/VI22-07
148
+ xevy dev task/cb49c02e-66d8-4475-95a8-6f3930643ec8
149
+ xevy dev xevy/xevyai
150
+ xevy dev xevy/xevyai --base https://xevy.example.com
150
151
  ```
151
152
 
152
153
  The command stays attached across normal Pi exits and transient terminal
@@ -154,12 +155,13 @@ disconnects. After Pi exits, it waits three seconds before restarting and shows
154
155
  a `Ctrl+C` detach hint; press `Ctrl+]` while attached to leave the Dev Session
155
156
  running immediately.
156
157
 
157
- The CLI resolves an exact task ID or task code, attaches to its existing Dev
158
- Session, or starts one from a linked repository. It then renders Pi's native TUI
159
- from the isolated remote workspace: normal composer, thinking, tools, history,
160
- keyboard shortcuts, and session resume all behave like Pi on a local machine.
161
- When several accessible tasks share a code, or a project has several linked
162
- repositories, the CLI presents a numbered selector first.
158
+ The CLI grammar is explicit: `task/<task-id-or-code>` selects a task session,
159
+ while `<workspace>/<project>` selects your default personal project session.
160
+ Bare task IDs, aliases, and scope-guessing are intentionally unsupported. After
161
+ the target is resolved, the CLI renders Pi's native TUI from the isolated remote
162
+ workspace: normal composer, thinking, tools, history, keyboard shortcuts, and
163
+ session resume all behave like Pi on a local machine. A multi-repository project
164
+ asks for its runtime repository only on first start.
163
165
 
164
166
  `xevy dev` is only a terminal transport. Pi, Git credentials, the repository,
165
167
  and Docker remain on the server. Press `Ctrl+]` to detach without stopping Pi;
@@ -18,6 +18,27 @@ const TERMINAL_RECONNECT_MAX_DELAY_MS = 5_000;
18
18
  const TERMINAL_RESTART_GRACE_MS = 3_000;
19
19
  const TERMINAL_STABLE_RUNTIME_MS = 10_000;
20
20
  const TERMINAL_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
21
+ const DEV_TARGET_SEGMENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
22
+
23
+ function parseDevTarget(value) {
24
+ const reference = String(value || "").trim();
25
+ const segments = reference.split("/");
26
+ const usage = "Use `task/<task-id-or-code>` or `<workspace>/<project>`.";
27
+ if (segments.length !== 2 || segments.some((segment) => !segment)) {
28
+ throw new Error(`Invalid Dev Session target '${reference}'. ${usage}`);
29
+ }
30
+ if (segments.some((segment) => !DEV_TARGET_SEGMENT_PATTERN.test(segment))) {
31
+ throw new Error(`Invalid Dev Session target '${reference}'. Identifiers may use letters, numbers, '.', '_', and '-'.`);
32
+ }
33
+ if (segments[0] === "task") {
34
+ return { kind: "task", taskReference: segments[1] };
35
+ }
36
+ return {
37
+ kind: "personal",
38
+ workspaceIdentifier: segments[0],
39
+ projectIdentifier: segments[1],
40
+ };
41
+ }
21
42
 
22
43
  export function parseCredentialsText(source) {
23
44
  const values = {};
@@ -55,11 +76,11 @@ export function normalizeBaseUrl(value) {
55
76
 
56
77
  export function parseDevCommandArgs(argv) {
57
78
  const args = [...argv];
58
- let taskReference = "";
79
+ let targetReference = "";
59
80
  let base = null;
60
81
  while (args.length > 0) {
61
82
  const argument = args.shift();
62
- if (argument === "-h" || argument === "--help") return { help: true, taskReference: "", base: null };
83
+ if (argument === "-h" || argument === "--help") return { help: true, target: null, base: null };
63
84
  if (argument === "--base") {
64
85
  const value = args.shift();
65
86
  if (!value) throw new Error("Missing value for --base");
@@ -67,11 +88,13 @@ export function parseDevCommandArgs(argv) {
67
88
  continue;
68
89
  }
69
90
  if (argument.startsWith("-")) throw new Error(`Unknown option for \`xevy dev\`: ${argument}.`);
70
- if (taskReference) throw new Error("`xevy dev` accepts one task ID or task code.");
71
- taskReference = argument;
91
+ if (targetReference) throw new Error("`xevy dev` accepts one Dev Session target.");
92
+ targetReference = argument;
93
+ }
94
+ if (!targetReference) {
95
+ throw new Error("Usage: xevy dev <task/<task-id-or-code>|workspace/project> [--base <url>]");
72
96
  }
73
- if (!taskReference) throw new Error("Usage: xevy dev <task-id-or-code> [--base <url>]");
74
- return { help: false, taskReference, base };
97
+ return { help: false, target: parseDevTarget(targetReference), base };
75
98
  }
76
99
 
77
100
  export function resolveDevConnection({
@@ -600,12 +623,17 @@ export function createTerminalStatus({ output, writeLine, animate }) {
600
623
  };
601
624
  }
602
625
 
603
- function sessionSummary(task, session, base, writeLine) {
604
- const url = devSessionLaunchUrl(base, task);
626
+ function sessionSummary(context, session, base, writeLine) {
627
+ const task = context.kind === "task" ? context.task : null;
628
+ const url = task
629
+ ? devSessionLaunchUrl(base, task)
630
+ : new URL(`/agent?session=${encodeURIComponent(session.id)}`, `${normalizeBaseUrl(base)}/`).toString();
605
631
  writeLine("\nDev Session");
606
- writeLine(` Task ${formatTask(task)}`);
607
- writeLine(` Site ${url || "not available yet"}`);
608
- writeLine(` Branch ${session.config?.branch || "unknown"}`);
632
+ if (task) writeLine(` Task ${formatTask(task)}`);
633
+ else writeLine(` Project ${context.workspace.identifier}/${context.project.identifier} · Personal`);
634
+ writeLine(` Workbench ${url || "not available yet"}`);
635
+ writeLine(` Preview ${session.config?.runtimeMode === "none" || !session.hostname ? "none (workspace only)" : `https://${session.hostname}`}`);
636
+ writeLine(` Branch ${session.branch || session.config?.branch || "unknown"}`);
609
637
  writeLine(` Status ${session.status}`);
610
638
  writeLine(` Expires ${session.expiresAt || "server-managed"}`);
611
639
  writeLine("\nNative Pi terminal · press Ctrl+] to detach and leave it running\n");
@@ -799,11 +827,11 @@ async function attachNativeTerminalPersistently({
799
827
  }
800
828
  }
801
829
 
802
- function commandHelp(writeLine) {
830
+ function commandHelp(writeLine, hasWebPreview = true) {
803
831
  writeLine("Commands:");
804
832
  writeLine(" /status Refresh session status");
805
833
  writeLine(" /logs Show the latest Dev Session logs");
806
- writeLine(" /open Open a fresh one-use Dev Session URL");
834
+ if (hasWebPreview) writeLine(" /open Open a fresh one-use Dev Session URL");
807
835
  writeLine(" /finish Save the task branch and stop");
808
836
  writeLine(" /stop Stop the Dev Session without finishing");
809
837
  writeLine(" /detach Leave it running and exit this CLI");
@@ -849,8 +877,10 @@ export async function runDevSession(options) {
849
877
  if (!token.startsWith("xevy_pk_")) {
850
878
  throw new Error("A Xevy API key is required. Run `xevy setup --credentials` first.");
851
879
  }
852
- const taskReference = String(options.taskReference || "").trim();
853
- if (!taskReference) throw new Error("Usage: xevy dev <task-id-or-code> [--base <url>]");
880
+ const target = options.target;
881
+ if (!target || !["task", "personal"].includes(target.kind)) {
882
+ throw new Error("Usage: xevy dev <task/<task-id-or-code>|workspace/project> [--base <url>]");
883
+ }
854
884
 
855
885
  const fetchImpl = options.fetchImpl || globalThis.fetch;
856
886
  if (typeof fetchImpl !== "function") throw new Error("This Node.js version does not provide fetch.");
@@ -919,54 +949,104 @@ export async function runDevSession(options) {
919
949
 
920
950
  let heartbeat = null;
921
951
  let task;
952
+ let context;
922
953
  let session;
954
+ let sessionPath;
923
955
  try {
924
- // Validate both host and key before resolving any task context.
956
+ // Validate both host and key before resolving any session context.
925
957
  await api.request("/api/profile", { signal: detachController.signal });
926
- const search = await api.request("/api/tasks/search", {
927
- method: "POST",
928
- body: { taskIdentifier: taskReference },
929
- signal: detachController.signal,
930
- });
931
- const tasks = search?.tasks || [];
932
- if (tasks.length === 0) throw new Error(`No accessible task matches '${taskReference}'.`);
933
- task = await selectOne({
934
- items: tasks,
935
- label: "tasks",
936
- describe: formatTask,
937
- interactive,
938
- ask,
939
- writeLine,
940
- });
941
-
942
- const sessionPath = `/api/projects/${encodeURIComponent(task.workspaceIdentifier)}/${encodeURIComponent(task.projectIdentifier)}/tasks/${encodeURIComponent(task.id)}/live-session`;
943
- const current = await api.request(`${sessionPath}/`, { signal: detachController.signal });
944
- session = current?.session || null;
945
- if (!session) {
946
- const repositoryResult = await api.request(`${sessionPath}/repositories`, { signal: detachController.signal });
947
- const repositories = repositoryResult?.repos || [];
948
- if (repositories.length === 0) {
949
- throw new Error("No linked repository is configured for this project.");
950
- }
951
- const repository = await selectOne({
952
- items: repositories,
953
- label: "repositories",
954
- describe: (item) => `${item.displayName || item.role}${item.defaultBranch ? ` · ${item.defaultBranch}` : ""}`,
955
- interactive,
956
- ask,
957
- writeLine,
958
- });
959
- writeLine(`Starting Dev Session with ${repository.displayName || repository.role}…`);
960
- const started = await api.request(`${sessionPath}/`, {
958
+ if (target.kind === "task") {
959
+ const search = await api.request("/api/tasks/search", {
961
960
  method: "POST",
962
- body: { runtimeRepositoryId: repository.id },
961
+ body: { taskIdentifier: target.taskReference },
963
962
  signal: detachController.signal,
964
- timeoutMs: 60_000,
965
963
  });
966
- session = started?.session;
967
- if (!session) throw new Error("Xevy accepted the request but returned no Dev Session.");
964
+ const tasks = search?.tasks || [];
965
+ if (tasks.length === 0) throw new Error(`No accessible task matches '${target.taskReference}'.`);
966
+ if (tasks.length > 1) {
967
+ throw new Error(`More than one task matches '${target.taskReference}'. Use the task UUID after 'task/'.`);
968
+ }
969
+ task = tasks[0];
970
+ context = { kind: "task", task };
971
+ sessionPath = `/api/projects/${encodeURIComponent(task.workspaceIdentifier)}/${encodeURIComponent(task.projectIdentifier)}/tasks/${encodeURIComponent(task.id)}/live-session`;
972
+ const current = await api.request(`${sessionPath}/`, { signal: detachController.signal });
973
+ session = current?.session || null;
974
+ if (!session) {
975
+ const repositoryResult = await api.request(`${sessionPath}/repositories`, { signal: detachController.signal });
976
+ const repositories = repositoryResult?.repos || [];
977
+ if (repositories.length === 0) {
978
+ throw new Error("No linked repository is configured for this project.");
979
+ }
980
+ const repository = await selectOne({
981
+ items: repositories,
982
+ label: "repositories",
983
+ describe: (item) => `${item.displayName || item.role}${item.defaultBranch ? ` · ${item.defaultBranch}` : ""}`,
984
+ interactive,
985
+ ask,
986
+ writeLine,
987
+ });
988
+ writeLine(`Starting Dev Session with ${repository.displayName || repository.role}…`);
989
+ const started = await api.request(`${sessionPath}/`, {
990
+ method: "POST",
991
+ body: { runtimeRepositoryId: repository.id },
992
+ signal: detachController.signal,
993
+ timeoutMs: 60_000,
994
+ });
995
+ session = started?.session;
996
+ if (!session) throw new Error("Xevy accepted the request but returned no Dev Session.");
997
+ } else {
998
+ writeLine("Attaching to the existing Dev Session…");
999
+ }
968
1000
  } else {
969
- writeLine("Attaching to the existing Dev Session…");
1001
+ const workspaceResult = await api.request("/api/workspaces", { signal: detachController.signal });
1002
+ const workspace = (workspaceResult?.workspaces || [])
1003
+ .find((item) => item.identifier === target.workspaceIdentifier);
1004
+ const project = workspace?.projects?.find((item) => item.identifier === target.projectIdentifier);
1005
+ if (!workspace || !project) {
1006
+ throw new Error(`No accessible project matches '${target.workspaceIdentifier}/${target.projectIdentifier}'.`);
1007
+ }
1008
+ context = { kind: "personal", workspace, project };
1009
+ const candidates = await api.request(
1010
+ `/api/agent/dev-session-candidates?projectId=${encodeURIComponent(project.id)}`,
1011
+ { signal: detachController.signal },
1012
+ );
1013
+ const existingSessionId = candidates?.personal?.existingSessionId || null;
1014
+ if (existingSessionId) {
1015
+ sessionPath = `/api/agent/dev-sessions/${encodeURIComponent(existingSessionId)}`;
1016
+ const current = await api.request(sessionPath, { signal: detachController.signal });
1017
+ session = current?.session || null;
1018
+ if (session) writeLine("Attaching to your existing personal Dev Session…");
1019
+ }
1020
+ if (!session) {
1021
+ const repositories = candidates?.repositories || [];
1022
+ if (repositories.length === 0) {
1023
+ throw new Error(candidates?.personal?.blocker || "No linked repository is configured for this project.");
1024
+ }
1025
+ const repository = await selectOne({
1026
+ items: repositories,
1027
+ label: "repositories",
1028
+ describe: (item) => `${item.displayName || item.role}${item.defaultBranch ? ` · ${item.defaultBranch}` : ""}`,
1029
+ interactive,
1030
+ ask,
1031
+ writeLine,
1032
+ });
1033
+ writeLine(`Starting personal Dev Session with ${repository.displayName || repository.role}…`);
1034
+ const started = await api.request("/api/agent/dev-sessions", {
1035
+ method: "POST",
1036
+ body: {
1037
+ target: {
1038
+ kind: "personal",
1039
+ projectId: project.id,
1040
+ runtimeRepositoryId: repository.id,
1041
+ },
1042
+ },
1043
+ signal: detachController.signal,
1044
+ timeoutMs: 60_000,
1045
+ });
1046
+ session = started?.session;
1047
+ if (!session?.id) throw new Error("Xevy accepted the request but returned no Dev Session.");
1048
+ sessionPath = `/api/agent/dev-sessions/${encodeURIComponent(session.id)}`;
1049
+ }
970
1050
  }
971
1051
 
972
1052
  let heartbeatFailures = 0;
@@ -996,7 +1076,7 @@ export async function runDevSession(options) {
996
1076
  sleep,
997
1077
  signal: detachController.signal,
998
1078
  });
999
- sessionSummary(task, session, base, writeLine);
1079
+ sessionSummary(context, session, base, writeLine);
1000
1080
 
1001
1081
  const nativeTerminal = options.nativeTerminal
1002
1082
  ?? (input === process.stdin && output === process.stdout);
@@ -1014,7 +1094,12 @@ export async function runDevSession(options) {
1014
1094
  animateStatus: options.animateStatus,
1015
1095
  });
1016
1096
  detached = true;
1017
- return { task, session, detached: true };
1097
+ return { task, project: context.kind === "personal" ? context.project : null, session, detached: true };
1098
+ }
1099
+
1100
+ if (context.kind === "personal") {
1101
+ writeLine("Attached successfully. Rerun in an interactive terminal to open Pi.");
1102
+ return { task: null, project: context.project, session, detached: true };
1018
1103
  }
1019
1104
 
1020
1105
  const renderState = {
@@ -1044,7 +1129,7 @@ export async function runDevSession(options) {
1044
1129
 
1045
1130
  if (!interactive) {
1046
1131
  writeLine("Attached successfully. Rerun in an interactive terminal to prompt the agent.");
1047
- return { task, session, detached: true };
1132
+ return { task, project: null, session, detached: true };
1048
1133
  }
1049
1134
 
1050
1135
  while (!detached) {
@@ -1052,7 +1137,7 @@ export async function runDevSession(options) {
1052
1137
  if (detached) break;
1053
1138
  if (!prompt) continue;
1054
1139
  if (prompt === "/help") {
1055
- commandHelp(writeLine);
1140
+ commandHelp(writeLine, session.config?.runtimeMode !== "none" && Boolean(session.hostname));
1056
1141
  continue;
1057
1142
  }
1058
1143
  if (prompt === "/detach") {
@@ -1063,7 +1148,7 @@ export async function runDevSession(options) {
1063
1148
  const result = await api.request(`${sessionPath}/`, { signal: detachController.signal });
1064
1149
  if (!result?.session) throw new Error("No active Dev Session remains for this task.");
1065
1150
  session = result.session;
1066
- sessionSummary(task, session, base, writeLine);
1151
+ sessionSummary(context, session, base, writeLine);
1067
1152
  continue;
1068
1153
  }
1069
1154
  if (prompt === "/logs") {
@@ -1073,6 +1158,10 @@ export async function runDevSession(options) {
1073
1158
  continue;
1074
1159
  }
1075
1160
  if (prompt === "/open") {
1161
+ if (session.config?.runtimeMode === "none" || !session.hostname) {
1162
+ writeLine("This Dev Session has no web runtime or live preview.");
1163
+ continue;
1164
+ }
1076
1165
  await launchBrowser({ api, sessionPath, platform, spawnImpl, writeLaunchLine });
1077
1166
  continue;
1078
1167
  }
@@ -1161,10 +1250,15 @@ export async function runDevSession(options) {
1161
1250
  writeLine(`Agent turn failed: ${completed.errorMessage || "unknown error"}`);
1162
1251
  }
1163
1252
  }
1164
- return { task, session, detached: true };
1253
+ return { task, project: null, session, detached: true };
1165
1254
  } catch (error) {
1166
1255
  if (detached && /detached/i.test(error instanceof Error ? error.message : String(error))) {
1167
- return { task, session, detached: true };
1256
+ return {
1257
+ task,
1258
+ project: context?.kind === "personal" ? context.project : null,
1259
+ session,
1260
+ detached: true,
1261
+ };
1168
1262
  }
1169
1263
  throw new Error(redactSensitive(error instanceof Error ? error.message : String(error), secrets));
1170
1264
  } finally {
package/bin/xevy.mjs CHANGED
@@ -96,7 +96,7 @@ function usage() {
96
96
  xevy setup [options] Choose credentials, pi, skills, and MCP setup
97
97
  xevy update [--base u] Refresh the pi extensions + coding-agent skills/MCP
98
98
  xevy check [--base u] Report skill updates or missing coding-agent targets
99
- xevy dev <task> Attach to a remote task Dev Session
99
+ xevy dev <target> Attach to a remote task or personal Dev Session
100
100
 
101
101
  Options:
102
102
  --base <url> Xevy host (default: XEVY_BASE or ${DEFAULT_BASE})
@@ -118,7 +118,8 @@ Examples:
118
118
  npx @xevy/cli setup --credentials --mcp -a codex
119
119
  npx @xevy/cli setup --all -y
120
120
  npx @xevy/cli update
121
- npx @xevy/cli dev VI22-07
121
+ npx @xevy/cli dev task/VI22-07
122
+ npx @xevy/cli dev xevy/xevyai
122
123
  npx @xevy/cli
123
124
 
124
125
  Install globally to drop the npx prefix:
@@ -130,11 +131,12 @@ Install globally to drop the npx prefix:
130
131
  function devUsage() {
131
132
  console.log(`Xevy Dev Session
132
133
 
133
- xevy dev <task-id-or-code> [--base <url>]
134
+ xevy dev task/<task-id-or-code> [--base <url>]
135
+ xevy dev <workspace>/<project> [--base <url>]
134
136
 
135
- Connects this terminal to the task's remote Dev Session. The command attaches
136
- to an existing session or starts one from a linked repository, then opens Pi's
137
- native interactive terminal inside the isolated remote workspace.
137
+ Connects this terminal to a remote Dev Session. The reserved task/ prefix
138
+ selects task work; a workspace/project target starts or resumes your personal
139
+ project session. Pi runs inside the isolated remote workspace.
138
140
 
139
141
  Terminal control:
140
142
  Ctrl+] Detach without stopping Pi or the Dev Session
@@ -159,7 +161,7 @@ function parseArgv(argv) {
159
161
  try {
160
162
  const parsed = parseDevCommandArgs(args);
161
163
  if (parsed.help) return { command: "dev-help" };
162
- return { command: "dev", taskReference: parsed.taskReference, base: parsed.base };
164
+ return { command: "dev", target: parsed.target, base: parsed.base };
163
165
  } catch (error) {
164
166
  die(error instanceof Error ? error.message : String(error));
165
167
  }
@@ -663,7 +665,7 @@ async function dev(opts) {
663
665
  await runDevSession({
664
666
  base,
665
667
  token,
666
- taskReference: opts.taskReference,
668
+ target: opts.target,
667
669
  });
668
670
  }
669
671
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xevy/cli",
3
- "version": "0.1.18",
3
+ "version": "0.1.19",
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": [