@xevy/cli 0.1.9 → 0.1.10

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.
Files changed (3) hide show
  1. package/README.md +46 -18
  2. package/bin/xevy.mjs +257 -39
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -41,16 +41,16 @@ npm install -g @xevy/cli
41
41
  xevy setup
42
42
  ```
43
43
 
44
- This walks you through everything:
44
+ Choose exactly what to configure, or press Enter to install everything:
45
45
 
46
- 1. Installs the **pi agent** if it isn't already on your PATH.
47
- 2. Installs the Xevy extensions (see [`xevy setup`](#xevy-setup) for details).
48
- 3. Installs the Xevy **SDLC skills and MCP server** for Cursor, Claude Code, and Codex by default (via `@xevy/skills`). Pass repeatable `--agent <name>` flags to target any other agent supported by the underlying installers.
49
- 4. Asks for your **API key**. When prompted, open the link it prints — it takes you
50
- straight to **Settings → Profile → API keys** at
51
- <https://xevy.ai/settings?section=profile&tab=api> — click **Create key**, copy the
52
- key, and paste it back into the terminal. Your key is saved to
53
- `~/.config/xevy/credentials` and never printed again.
46
+ - **Credentials** — store or replace the API key in `~/.config/xevy/credentials`.
47
+ - **Pi** — install pi and its Xevy extensions.
48
+ - **Skills** — install Xevy SDLC skills for selected coding agents.
49
+ - **MCP** — configure Xevy MCP for selected coding agents.
50
+
51
+ Codex uses a local API-key bridge, so it does not depend on expiring OAuth
52
+ refresh state. Claude Code, Cursor, and other remote clients continue to use
53
+ OAuth.
54
54
 
55
55
  ### 5. Start working
56
56
 
@@ -78,20 +78,40 @@ npm update -g @xevy/cli # or re-run: npm install -g @xevy/cli
78
78
 
79
79
  ## `xevy setup`
80
80
 
81
- 1. Installs the **pi agent** if it isn't already on your PATH.
82
- 2. Installs the Xevy extensions:
81
+ `xevy setup` presents a component selector. Press Enter for all components, or
82
+ choose any combination of credentials, Pi, skills, and MCP. The matching
83
+ non-interactive flags are:
84
+
85
+ ```bash
86
+ xevy setup --credentials
87
+ xevy setup --pi
88
+ xevy setup --skills --agent cursor
89
+ xevy setup --mcp --agent codex
90
+ xevy setup --component skills --component mcp --agent claude-code
91
+ xevy setup --all --yes
92
+ ```
93
+
94
+ For a first non-interactive install, provide the key through
95
+ `XEVY_API_KEY=xevy_pk_… xevy setup --all --yes`; the value is stored without
96
+ being printed.
97
+
98
+ The components perform these actions:
99
+
100
+ 1. **Pi** installs the agent if needed and installs the Xevy extensions:
83
101
  - **`xevy-core.ts`** (shared UI + setup/context), **`xevy-model.ts`** (the
84
102
  `xevy/*` models), and **`xevy-mcp.ts`** (the MCP→pi tool bridge) into pi's
85
103
  **global** dir `~/.pi/agent/extensions/`, so they load in *every* pi session.
86
104
  - **`xevy.ts`** (tools + workflow commands) into **`~/.xevy/extensions/`**.
87
- 3. Asks for your **API key** (reuses an already-saved one if present) and prints a
105
+ 2. **Credentials** asks for your API key (reuses an already-saved one if present) and prints a
88
106
  **direct link to the API-keys tab** to generate one, then stores it in
89
107
  `~/.config/xevy/credentials` (mode `600`, never printed).
90
- 4. Installs the Xevy **SDLC skills and MCP server configuration** for Cursor,
91
- Claude Code, and Codex by default (delegates to `@xevy/skills`). pi keeps its
108
+ 3. **Skills/MCP** installs the Xevy SDLC skills and/or MCP server configuration
109
+ for Cursor, Claude Code, and Codex by default (delegates to `@xevy/skills`). Pi keeps its
92
110
  extension-backed MCP connection, so the coding-agent configuration does not
93
- conflict with pi. An integration hiccup only warns; it never aborts the setup
94
- that already succeeded.
111
+ conflict with Pi.
112
+
113
+ If Pi or Codex MCP is selected without an existing API key, setup automatically
114
+ adds the credentials component before making changes.
95
115
 
96
116
  The API-keys link opens **Settings → Profile → API keys** directly:
97
117
  `https://xevy.ai/settings?section=profile&tab=api`.
@@ -122,6 +142,13 @@ xevy "summarise this repo" # forwards the prompt to pi
122
142
  ```
123
143
  --base <url> Xevy host (default: XEVY_BASE or https://xevy.ai)
124
144
  -a, --agent <name> Coding-agent target (repeatable; default: cursor, claude-code, codex)
145
+ -c, --component setup component: credentials, pi, skills, or mcp (repeatable)
146
+ --credentials setup credentials only (composable with other component flags)
147
+ --pi setup Pi only
148
+ --skills setup skills only
149
+ --mcp setup MCP only
150
+ --all setup every component
151
+ -y, --yes non-interactive; defaults to all components and agents
125
152
  -v, --version Print the CLI version
126
153
  -h, --help Show help
127
154
  ```
@@ -133,8 +160,9 @@ Code, and Codex** by default. Target any identifier supported by
133
160
  [`skills`](https://github.com/vercel-labs/skills#supported-agents) and `add-mcp` with
134
161
  repeatable flags, for example `xevy setup -a windsurf -a codex`.
135
162
 
136
- After installation, complete OAuth in each client. For Codex, run
137
- `codex mcp login xevy` and restart the session. In Claude Code, run `/mcp` and
163
+ Codex is configured with a stable local stdio bridge that reads the revocable API
164
+ key from `~/.config/xevy/credentials`; restart Codex or open a new session after
165
+ setup. It does not require `codex mcp login xevy`. In Claude Code, run `/mcp` and
138
166
  authenticate `xevy`. In Cursor, use Settings → MCP → `xevy` → Connect. Other
139
167
  clients expose an equivalent MCP connect/OAuth action.
140
168
 
package/bin/xevy.mjs CHANGED
@@ -2,10 +2,8 @@
2
2
  /**
3
3
  * @xevy/cli — the `xevy` command.
4
4
  *
5
- * xevy setup Install the pi agent (if missing); install the Xevy extensions
6
- * (core + model + MCP globally, xevy.ts into ~/.xevy/extensions);
7
- * install the Xevy SDLC skills + MCP for coding agents (via
8
- * @xevy/skills); and store your API key.
5
+ * xevy setup Choose and configure credentials, pi extensions, agent skills,
6
+ * and MCP integrations independently.
9
7
  * xevy update Refresh the pi extensions + coding-agent integration.
10
8
  * xevy check Report skill updates or missing coding-agent targets.
11
9
  * xevy Open pi with the Xevy extensions.
@@ -25,6 +23,8 @@ const here = path.dirname(fileURLToPath(import.meta.url));
25
23
  const pkgRoot = path.resolve(here, "..");
26
24
 
27
25
  const DEFAULT_BASE = "https://xevy.ai";
26
+ const DEFAULT_AGENTS = ["cursor", "claude-code", "codex"];
27
+ const SETUP_COMPONENTS = ["credentials", "pi", "skills", "mcp"];
28
28
  const isWindows = process.platform === "win32";
29
29
 
30
30
  const PI_PACKAGE = "@mariozechner/pi-coding-agent";
@@ -70,11 +70,24 @@ function die(msg) {
70
70
  process.exit(1);
71
71
  }
72
72
 
73
+ function validateBaseUrl(base) {
74
+ let parsed;
75
+ try {
76
+ parsed = new URL(base);
77
+ } catch {
78
+ die(`Invalid Xevy base URL: ${base}`);
79
+ }
80
+ const local = ["localhost", "127.0.0.1", "::1"].includes(parsed.hostname);
81
+ if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) {
82
+ die("The Xevy base URL must use HTTPS (HTTP is allowed only for localhost).");
83
+ }
84
+ }
85
+
73
86
  function usage() {
74
87
  console.log(`Xevy CLI
75
88
 
76
89
  xevy Open pi with the Xevy extensions in ~/.xevy/extensions
77
- xevy setup [--base u] Install pi + extensions + coding-agent skills/MCP, store your API key
90
+ xevy setup [options] Choose credentials, pi, skills, and MCP setup
78
91
  xevy update [--base u] Refresh the pi extensions + coding-agent skills/MCP
79
92
  xevy check [--base u] Report skill updates or missing coding-agent targets
80
93
 
@@ -82,11 +95,21 @@ Options:
82
95
  --base <url> Xevy host (default: XEVY_BASE or ${DEFAULT_BASE})
83
96
  -a, --agent <name> Target any supported coding agent (repeatable)
84
97
  Default: cursor, claude-code, codex
98
+ -c, --component <name> setup: credentials, pi, skills, or mcp (repeatable)
99
+ --credentials setup: store or replace the Xevy API key
100
+ --pi setup: install pi and the Xevy pi extensions
101
+ --skills setup: install Xevy agent skills
102
+ --mcp setup: configure Xevy MCP
103
+ --all setup: select every component
104
+ -y, --yes Non-interactive; defaults to all components and agents
85
105
  -v, --version Print the CLI version
86
106
  -h, --help Show this help
87
107
 
88
108
  Examples:
89
- npx @xevy/cli setup
109
+ npx @xevy/cli setup # interactive selector
110
+ npx @xevy/cli setup --component mcp -a codex
111
+ npx @xevy/cli setup --credentials --mcp -a codex
112
+ npx @xevy/cli setup --all -y
90
113
  npx @xevy/cli update
91
114
  npx @xevy/cli
92
115
 
@@ -108,7 +131,16 @@ function parseArgv(argv) {
108
131
 
109
132
  if (first === "setup" || first === "update" || first === "check") {
110
133
  const command = args.shift();
111
- const opts = { command, base, agents: [], piArgs: [] };
134
+ const opts = {
135
+ command,
136
+ base,
137
+ agents: [],
138
+ agentsExplicit: false,
139
+ components: [],
140
+ componentsExplicit: false,
141
+ yes: false,
142
+ piArgs: [],
143
+ };
112
144
  while (args.length > 0) {
113
145
  const a = args.shift();
114
146
  if (a === "--base") {
@@ -121,10 +153,38 @@ function parseArgv(argv) {
121
153
  const v = args.shift();
122
154
  if (!v) die("Missing value for --agent");
123
155
  if (!opts.agents.includes(v)) opts.agents.push(v);
156
+ opts.agentsExplicit = true;
157
+ continue;
158
+ }
159
+ if (a === "-y" || a === "--yes") {
160
+ opts.yes = true;
161
+ continue;
162
+ }
163
+ if (a === "--all") {
164
+ if (command !== "setup") die("`--all` is only supported by `xevy setup`.");
165
+ opts.components = [...SETUP_COMPONENTS];
166
+ opts.componentsExplicit = true;
167
+ continue;
168
+ }
169
+ if (a === "-c" || a === "--component") {
170
+ if (command !== "setup") {
171
+ die("`--component` is only supported by `xevy setup`.");
172
+ }
173
+ const v = args.shift();
174
+ if (!v) die("Missing value for --component");
175
+ addSetupComponent(opts, v);
176
+ continue;
177
+ }
178
+ if (["--credentials", "--pi", "--skills", "--mcp"].includes(a)) {
179
+ if (command !== "setup") {
180
+ die(`\`${a}\` is only supported by \`xevy setup\`.`);
181
+ }
182
+ addSetupComponent(opts, a.slice(2));
124
183
  continue;
125
184
  }
126
185
  die(`Unknown option for \`xevy ${command}\`: ${a}. Try \`xevy --help\`.`);
127
186
  }
187
+ validateBaseUrl(opts.base);
128
188
  return opts;
129
189
  }
130
190
 
@@ -132,6 +192,17 @@ function parseArgv(argv) {
132
192
  return { command: "open", base, piArgs: args };
133
193
  }
134
194
 
195
+ function addSetupComponent(opts, component) {
196
+ const normalized = String(component).trim().toLowerCase();
197
+ if (!SETUP_COMPONENTS.includes(normalized)) {
198
+ die(
199
+ `Unknown setup component '${component}'. Choose: ${SETUP_COMPONENTS.join(", ")}.`,
200
+ );
201
+ }
202
+ if (!opts.components.includes(normalized)) opts.components.push(normalized);
203
+ opts.componentsExplicit = true;
204
+ }
205
+
135
206
  function run(cmd, args, { label } = {}) {
136
207
  const title = label || [cmd, ...args].join(" ");
137
208
  console.log(`→ ${title}`);
@@ -253,6 +324,32 @@ function readStoredToken() {
253
324
  return null;
254
325
  }
255
326
 
327
+ function readEnvironmentToken() {
328
+ const token = String(process.env.XEVY_API_KEY || "").trim();
329
+ return token.startsWith(API_KEY_PREFIX) ? token : null;
330
+ }
331
+
332
+ async function validateApiKey(base, token) {
333
+ let response;
334
+ try {
335
+ response = await fetch(`${base}/api/auth/me`, {
336
+ headers: { Authorization: `Bearer ${token}` },
337
+ signal: AbortSignal.timeout(10_000),
338
+ });
339
+ } catch (error) {
340
+ die(
341
+ `Could not validate the Xevy API key: ${
342
+ error instanceof Error ? error.message : String(error)
343
+ }`,
344
+ );
345
+ }
346
+ if (response.status === 401 || response.status === 403) return false;
347
+ if (!response.ok) {
348
+ die(`Could not validate the Xevy API key (HTTP ${response.status}).`);
349
+ }
350
+ return true;
351
+ }
352
+
256
353
  function isYes(answer, defaultYes = true) {
257
354
  const a = String(answer || "").trim().toLowerCase();
258
355
  if (!a) return defaultYes;
@@ -271,6 +368,62 @@ async function promptNewApiKey(base) {
271
368
  return token;
272
369
  }
273
370
 
371
+ function parseNumberedSelection(answer, choices, label) {
372
+ const selected = [];
373
+ const values = String(answer || "")
374
+ .toLowerCase()
375
+ .split(/[,\s]+/)
376
+ .filter(Boolean);
377
+ for (const value of values) {
378
+ const numeric = Number.parseInt(value, 10);
379
+ const choice =
380
+ Number.isInteger(numeric) && String(numeric) === value
381
+ ? choices[numeric - 1]
382
+ : choices.find((candidate) => candidate === value);
383
+ if (!choice) {
384
+ die(`Unknown ${label} '${value}'. Choose from: ${choices.join(", ")}.`);
385
+ }
386
+ if (!selected.includes(choice)) selected.push(choice);
387
+ }
388
+ return selected;
389
+ }
390
+
391
+ async function resolveSetupComponents(opts) {
392
+ if (opts.componentsExplicit) return [...opts.components];
393
+ if (opts.yes || !process.stdin.isTTY) return [...SETUP_COMPONENTS];
394
+
395
+ console.log("What would you like to set up?");
396
+ console.log(" 1. Credentials Store or replace your Xevy API key");
397
+ console.log(" 2. Pi Install pi and the Xevy pi extensions");
398
+ console.log(" 3. Skills Install Xevy skills for coding agents");
399
+ console.log(" 4. MCP Configure Xevy MCP for coding agents");
400
+ const answer = await promptLine(
401
+ "Choose numbers or names, comma-separated [Enter = all]: ",
402
+ );
403
+ return answer
404
+ ? parseNumberedSelection(answer, SETUP_COMPONENTS, "component")
405
+ : [...SETUP_COMPONENTS];
406
+ }
407
+
408
+ async function resolveSetupAgents(opts, components) {
409
+ if (!components.some((component) => component === "skills" || component === "mcp")) {
410
+ return [];
411
+ }
412
+ if (opts.agentsExplicit) return [...opts.agents];
413
+ if (opts.yes || !process.stdin.isTTY) return [...DEFAULT_AGENTS];
414
+
415
+ console.log("\nWhich coding agents should be configured?");
416
+ console.log(" 1. Cursor");
417
+ console.log(" 2. Claude Code");
418
+ console.log(" 3. Codex");
419
+ const answer = await promptLine(
420
+ "Choose numbers or names, comma-separated [Enter = all]: ",
421
+ );
422
+ return answer
423
+ ? parseNumberedSelection(answer, DEFAULT_AGENTS, "agent")
424
+ : [...DEFAULT_AGENTS];
425
+ }
426
+
274
427
  // Download all four Xevy pi extensions to their install dirs. Shared by `setup`
275
428
  // and `update` so the two never drift.
276
429
  // • xevy-core.ts → pi's GLOBAL extensions dir (shared base: ask_question
@@ -291,44 +444,109 @@ async function downloadAllExtensions(base) {
291
444
  }
292
445
 
293
446
  async function setup(opts) {
294
- console.log("Setting up Xevy for pi\n");
447
+ console.log("Setting up Xevy\n");
295
448
 
296
- // 1. Ensure pi is installed (installs it if missing).
297
- ensurePi();
449
+ try {
450
+ const components = await resolveSetupComponents(opts);
451
+ const agents = await resolveSetupAgents(opts, components);
452
+ const needsApiKey =
453
+ components.includes("pi") ||
454
+ (components.includes("mcp") && agents.includes("codex"));
455
+ const existing = readStoredToken();
456
+ const existingIsValid =
457
+ existing && (needsApiKey || components.includes("credentials"))
458
+ ? await validateApiKey(opts.base, existing)
459
+ : Boolean(existing);
460
+
461
+ if (
462
+ needsApiKey &&
463
+ !existingIsValid &&
464
+ !components.includes("credentials")
465
+ ) {
466
+ components.unshift("credentials");
467
+ console.log(
468
+ "→ Added credentials because Pi and the Codex MCP bridge require a Xevy API key.",
469
+ );
470
+ }
298
471
 
299
- // 2. Extensions (core + model + MCP globally, xevy.ts into ~/.xevy).
300
- await downloadAllExtensions(opts.base);
472
+ if (components.includes("credentials")) {
473
+ let token;
474
+ if (existing && !existingIsValid) {
475
+ console.log("→ The stored Xevy API key is no longer valid for this host.");
476
+ }
477
+ if (existingIsValid && opts.yes) {
478
+ token = existing;
479
+ } else if (!existingIsValid && opts.yes) {
480
+ token = readEnvironmentToken();
481
+ if (!token) {
482
+ die(
483
+ "Non-interactive credential setup needs a valid XEVY_API_KEY.",
484
+ );
485
+ }
486
+ } else if (existingIsValid) {
487
+ const reuse = await promptLine(
488
+ `An API key is already saved (…${existing.slice(-4)}). Reuse it? [Y/n]: `,
489
+ );
490
+ token = isYes(reuse) ? existing : await promptNewApiKey(opts.base);
491
+ } else {
492
+ token = await promptNewApiKey(opts.base);
493
+ }
494
+ if (!(await validateApiKey(opts.base, token))) {
495
+ die(
496
+ `That API key was rejected by ${opts.base}. Create a new key and rerun the credentials component.`,
497
+ );
498
+ }
499
+ writeCredentials(opts.base, token);
500
+ console.log(`✓ API key stored at ${CREDENTIALS_FILE} (key not shown).`);
501
+ }
301
502
 
302
- // 3. API key — reuse the saved one if present, otherwise ask for a new one.
303
- const existing = readStoredToken();
304
- let token;
305
- if (existing) {
306
- const reuse = await promptLine(`An API key is already saved (…${existing.slice(-4)}). Reuse it? [Y/n]: `);
307
- token = isYes(reuse) ? existing : await promptNewApiKey(opts.base);
308
- } else {
309
- token = await promptNewApiKey(opts.base);
310
- }
311
- closePrompts();
312
- writeCredentials(opts.base, token);
313
- console.log(`✓ API key stored at ${CREDENTIALS_FILE} (key not shown).`);
503
+ if (components.includes("pi")) {
504
+ ensurePi();
505
+ await downloadAllExtensions(opts.base);
506
+ }
314
507
 
315
- // 4. Portable coding-agent integration. With no explicit -a flags, the
316
- // @xevy/skills package applies its cursor + claude-code + codex defaults.
317
- const agentIntegrationOk = installAgentIntegration(opts.base, opts.agents, "install");
508
+ let agentIntegrationOk = true;
509
+ const installsSkills = components.includes("skills");
510
+ const installsMcp = components.includes("mcp");
511
+ if (installsSkills || installsMcp) {
512
+ const packageCommand =
513
+ installsSkills && installsMcp
514
+ ? "install"
515
+ : installsSkills
516
+ ? "skills"
517
+ : "mcp";
518
+ agentIntegrationOk = installAgentIntegration(
519
+ opts.base,
520
+ agents,
521
+ packageCommand,
522
+ );
523
+ }
318
524
 
319
- console.log("\n✓ Setup complete.");
320
- console.log(" • Xevy models (xevy/auto, xevy/fast, …) + MCP tools are available in any pi session — no /login needed.");
321
- console.log(
322
- agentIntegrationOk
323
- ? ` • Coding-agent skills + MCP configured for ${configuredAgentLabel(opts.agents)}.`
324
- : " • Coding-agent integration NOT configured — run `xevy update` to retry.",
325
- );
326
- if (agentIntegrationOk) {
327
- console.log(" • Complete MCP OAuth in each configured client using the instructions above.");
525
+ console.log("\n✓ Selected setup complete.");
526
+ if (components.includes("pi")) {
527
+ console.log(
528
+ " • Xevy models and MCP tools are available in pi; run `xevy` to open it.",
529
+ );
530
+ }
531
+ if (installsSkills || installsMcp) {
532
+ console.log(
533
+ agentIntegrationOk
534
+ ? ` • ${[
535
+ installsSkills ? "skills" : "",
536
+ installsMcp ? "MCP" : "",
537
+ ]
538
+ .filter(Boolean)
539
+ .join(" + ")} configured for ${configuredAgentLabel(agents)}.`
540
+ : " • Coding-agent integration was not configured; rerun the selected component to retry.",
541
+ );
542
+ }
543
+ console.log(` • Components: ${components.join(", ")}`);
544
+ console.log(" • Keep current with `xevy check` / `xevy update`.");
545
+ if (opts.base !== DEFAULT_BASE) console.log(` • Host: ${opts.base}`);
546
+ if (!agentIntegrationOk) process.exitCode = 1;
547
+ } finally {
548
+ closePrompts();
328
549
  }
329
- console.log(" • Run `xevy` to open pi with the Xevy tools + models loaded.");
330
- console.log(" • Keep current with `xevy check` / `xevy update`.");
331
- if (opts.base !== DEFAULT_BASE) console.log(` • Host: ${opts.base}`);
332
550
  }
333
551
 
334
552
  // `xevy update` — refresh the pi extensions and portable coding-agent
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@xevy/cli",
3
- "version": "0.1.9",
4
- "description": "Xevy CLI — `xevy setup` installs pi, Xevy extensions, and coding-agent skills + MCP, then stores your API key; `xevy update`/`xevy check` keep them current; `xevy` opens pi with it.",
3
+ "version": "0.1.10",
4
+ "description": "Xevy CLI — modular setup for credentials, pi, coding-agent skills, and MCP; update/check keep integrations current; xevy opens pi.",
5
5
  "type": "module",
6
6
  "keywords": [
7
7
  "xevy",