@xevy/skills 0.1.18

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 (37) hide show
  1. package/.claude-plugin/plugin.json +23 -0
  2. package/README.md +133 -0
  3. package/bin/cli.mjs +387 -0
  4. package/bin/version.mjs +120 -0
  5. package/bin/xevy-creds.mjs +81 -0
  6. package/bin/xevy-link-repo.mjs +47 -0
  7. package/bin/xevy-sync-env.mjs +102 -0
  8. package/package.json +33 -0
  9. package/skills/analyze/SKILL.md +26 -0
  10. package/skills/analyze-here/SKILL.md +30 -0
  11. package/skills/create-document/SKILL.md +32 -0
  12. package/skills/create-report/SKILL.md +169 -0
  13. package/skills/create-report/examples.md +134 -0
  14. package/skills/create-xevy-task/SKILL.md +68 -0
  15. package/skills/deploy/SKILL.md +25 -0
  16. package/skills/execute/SKILL.md +29 -0
  17. package/skills/execute-here/SKILL.md +35 -0
  18. package/skills/fix/SKILL.md +26 -0
  19. package/skills/fix-here/SKILL.md +23 -0
  20. package/skills/generate-image/SKILL.md +31 -0
  21. package/skills/investigate/SKILL.md +218 -0
  22. package/skills/investigate/examples.md +170 -0
  23. package/skills/manage-documents/SKILL.md +39 -0
  24. package/skills/mark-ready/SKILL.md +29 -0
  25. package/skills/merge/SKILL.md +24 -0
  26. package/skills/merge-here/SKILL.md +22 -0
  27. package/skills/move-to-qa/SKILL.md +21 -0
  28. package/skills/move-to-qa-here/SKILL.md +21 -0
  29. package/skills/plan/SKILL.md +24 -0
  30. package/skills/plan-here/SKILL.md +26 -0
  31. package/skills/xevy-design/SKILL.md +103 -0
  32. package/skills/xevy-design/reference/craft.md +69 -0
  33. package/skills/xevy-design/reference/critique.md +33 -0
  34. package/skills/xevy-design/reference/polish.md +25 -0
  35. package/skills/xevy-design/reference/setup.md +82 -0
  36. package/skills/xevy-design/reference/shape.md +40 -0
  37. package/skills/xevy-setup/SKILL.md +56 -0
@@ -0,0 +1,23 @@
1
+ {
2
+ "name": "xevy",
3
+ "displayName": "Xevy",
4
+ "description": "Native /xevy:* SDLC workflow commands driven through the Xevy MCP server. Cloud (server Web Agent) by default; '-here' variants run locally in this Claude Code session. Claude reviews and corrects the result after every action.",
5
+ "version": "0.1.18",
6
+ "author": {
7
+ "name": "Xevy"
8
+ },
9
+ "homepage": "https://xevy.ai",
10
+ "keywords": [
11
+ "xevy",
12
+ "sdlc",
13
+ "mcp",
14
+ "deploy",
15
+ "tasks"
16
+ ],
17
+ "mcpServers": {
18
+ "xevy": {
19
+ "type": "http",
20
+ "url": "${XEVY_BASE:-https://xevy.ai}/mcp"
21
+ }
22
+ }
23
+ }
package/README.md ADDED
@@ -0,0 +1,133 @@
1
+ # @xevy/skills
2
+
3
+ Install **Xevy SDLC agent skills** and the **Xevy MCP server** for Cursor, Claude Code, and [50+ other agents](https://github.com/vercel-labs/skills#supported-agents) with one command.
4
+
5
+ This package wraps:
6
+
7
+ - [`npx skills`](https://github.com/vercel-labs/skills) — copies skills into `.cursor/skills/`, `.claude/skills/`, etc.
8
+ - [`npx add-mcp`](https://github.com/neondatabase/add-mcp) — writes `.cursor/mcp.json`, `.mcp.json`, and other agent MCP configs
9
+
10
+ The skill files under [`skills/`](skills/) are the source of truth — edit them there directly.
11
+
12
+ ## Quick start
13
+
14
+ Installs are **global by default** — skills land in user scope (`~/.agents/skills`, or `~/.cursor/skills`, `~/.claude/skills`, …) and MCP is written to the agent's global config. No per-repo files are created unless you opt out.
15
+
16
+ Run from anywhere:
17
+
18
+ ```bash
19
+ npx @xevy/skills # global by default
20
+ ```
21
+
22
+ Install into the **current project/repo** instead (writes `.cursor/skills/`, `.mcp.json`, etc. into the repo):
23
+
24
+ ```bash
25
+ npx @xevy/skills --project # or: --local / --no-global
26
+ ```
27
+
28
+ Non-interactive (CI / team bootstrap):
29
+
30
+ ```bash
31
+ npx @xevy/skills -y # global by default
32
+ npx @xevy/skills --project -y # into this repo
33
+ ```
34
+
35
+ Cursor only:
36
+
37
+ ```bash
38
+ npx @xevy/skills -a cursor -y
39
+ ```
40
+
41
+ Custom host (self-hosted Xevy):
42
+
43
+ ```bash
44
+ XEVY_BASE=https://xevy.vyte.dev npx @xevy/skills -y
45
+ ```
46
+
47
+ Then:
48
+
49
+ 1. **OAuth** — In Cursor: Settings → MCP → `xevy` → connect. In Claude Code: browser sign-in on first MCP use.
50
+ 2. **Setup** — Ask your agent to run the **Xevy setup** skill (or follow its steps) to link the repo and sync deploy config.
51
+
52
+ ## Commands
53
+
54
+ | Command | What it does |
55
+ |--------|----------------|
56
+ | `npx @xevy/skills` | Install all skills + MCP (default) |
57
+ | `npx @xevy/skills check` | Compare installed vs latest (reads `.xevy/skills-package.json`) |
58
+ | `npx @xevy/skills update -y` | Reinstall skills (+ MCP) when outdated |
59
+ | `npx @xevy/skills skills` | Skills only |
60
+ | `npx @xevy/skills mcp` | MCP only |
61
+ | `npx @xevy/skills sync-env --workspace … --project …` | Upload missing `.env` keys (REST API key required) |
62
+ | `npx @xevy/skills link-repo --workspace … --project … --remote …` | Link `origin` to project (REST API key required) |
63
+
64
+ ### Options
65
+
66
+ | Flag | Description |
67
+ |------|-------------|
68
+ | `-g, --global` | **(default)** User-global install (`~/.cursor/skills`, `~/.cursor/mcp.json`, …) |
69
+ | `--project`, `--local`, `--no-global` | Install into the current project/repo instead of globally (opt-out) |
70
+ | `-a, --agent` | Agent id (repeatable): `cursor`, `claude-code`, `codex`, … |
71
+ | `-s, --skill` | Install specific skills only (passed to `npx skills`) |
72
+ | `-y, --yes` | Skip prompts |
73
+ | `--copy` | Copy skills instead of symlinking |
74
+ | `--base <url>` | Xevy origin (default `https://xevy.ai`) |
75
+
76
+ ### Install skills manually (without this CLI)
77
+
78
+ ```bash
79
+ npx skills add vytedev/xevy.ai/src/packages/xevy-skills -a cursor -y
80
+ # or from npm extract path after install:
81
+ npx skills add ./node_modules/@xevy/skills -y
82
+ ```
83
+
84
+ ### Install MCP manually
85
+
86
+ ```bash
87
+ npx add-mcp https://xevy.ai/mcp -n xevy -a cursor -a claude-code -y
88
+ ```
89
+
90
+ ## Included skills
91
+
92
+ | Skill | Purpose |
93
+ |-------|---------|
94
+ | `setup` | Link repo, `.xevy/project.json`, deploy defaults, env sync |
95
+ | `analyze` / `analyze-here` | Task analysis (cloud / local) |
96
+ | `plan` / `plan-here` | Planning + review |
97
+ | `execute` / `execute-here` | Build, PR, preview |
98
+ | `fix` / `fix-here` | Rework after review |
99
+ | `merge` / `merge-here` | Merge workflow |
100
+ | `move-to-qa` / `move-to-qa-here` | QA handoff |
101
+ | `deploy` | Coolify preview/main |
102
+ | `investigate` | Diagnose with ephemeral scripts (.env; no secrets) |
103
+ | `create-xevy-task` | Capture session work into a task |
104
+
105
+ ## Security
106
+
107
+ - **MCP** uses OAuth in supported clients — no API key in the MCP URL.
108
+ - **REST helpers** (`sync-env`, `link-repo`) read `~/.config/xevy/credentials` or `XEVY_API_KEY`.
109
+ - Env values are never printed; sync-env only reports key names.
110
+
111
+ ## Publish
112
+
113
+ From the monolith root (requires `NPM_TOKEN` in `.env`):
114
+
115
+ ```bash
116
+ npm run bump:agent-packages # patch bump all aligned versions
117
+ npm run bump:agent-packages 0.1.15 # explicit semver
118
+ npm run release:agent-packages # sync + publish plugin + skills
119
+ ```
120
+
121
+ Version manifest for clients: `GET /api/agent-packages` on your Xevy host.
122
+
123
+ ## Auto-update
124
+
125
+ - **MCP tools** — always current on the server after deploy (no client reinstall for new tools).
126
+ - **Skills** — run `npx @xevy/skills update -y` (or `check` first). The CLI writes `.xevy/skills-package.json` on install/update.
127
+ - **Self-hosted** — add `--manifest` to prefer `{XEVY_BASE}/api/agent-packages` before npm registry.
128
+
129
+ ## Related
130
+
131
+ - One-command setup: `npx @xevy/cli setup` (`@xevy/cli`)
132
+ - MCP docs: https://xevy.ai/docs/mcp
133
+ - Claude Code setup guide: https://xevy.ai/claude
package/bin/cli.mjs ADDED
@@ -0,0 +1,387 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * @xevy/skills — install Xevy skills (npx skills) + MCP (npx add-mcp).
4
+ *
5
+ * Usage:
6
+ * npx @xevy/skills # install skills + MCP (default)
7
+ * npx @xevy/skills check # compare installed vs latest
8
+ * npx @xevy/skills update # reinstall when outdated
9
+ * npx @xevy/skills skills # skills only
10
+ * npx @xevy/skills mcp # MCP only
11
+ */
12
+ import { spawnSync } from "node:child_process";
13
+ import path from "node:path";
14
+ import { fileURLToPath } from "node:url";
15
+ import {
16
+ compareSemver,
17
+ fetchAgentPackagesManifest,
18
+ fetchNpmLatestVersion,
19
+ readInstalledStamp,
20
+ readPackageVersion,
21
+ stampPath,
22
+ writeInstalledStamp,
23
+ } from "./version.mjs";
24
+
25
+ const here = path.dirname(fileURLToPath(import.meta.url));
26
+ const pkgRoot = path.resolve(here, "..");
27
+
28
+ const DEFAULT_BASE = "https://xevy.ai";
29
+ const DEFAULT_AGENTS = ["cursor", "claude-code"];
30
+
31
+ function usage() {
32
+ console.log(`Xevy skills + MCP installer
33
+
34
+ npx @xevy/skills [install] [options] Install all skills + MCP (default)
35
+ npx @xevy/skills check [options] Show installed vs latest version
36
+ npx @xevy/skills update [options] Update skills (+ MCP) when outdated
37
+ npx @xevy/skills skills [options] Skills only (via npx skills)
38
+ npx @xevy/skills mcp [options] MCP only (via npx add-mcp)
39
+ npx @xevy/skills sync-env … Sync missing .env keys (API key)
40
+ npx @xevy/skills link-repo … Link git remote to project (API key)
41
+
42
+ Options:
43
+ -g, --global (default) Install to user-global scope (~/.agents + global MCP)
44
+ --project, --local Install to the current project/repo instead of global (opt-out)
45
+ -a, --agent <name> Target agent (repeatable). Default: cursor, claude-code
46
+ -y, --yes Non-interactive
47
+ --base <url> Xevy host (default: XEVY_BASE or ${DEFAULT_BASE})
48
+ --manifest Prefer ${DEFAULT_BASE}/api/agent-packages for version check
49
+ --copy Copy skill files instead of symlinking (npx skills --copy)
50
+ --skills-only update: refresh skills only (skip MCP reconfigure)
51
+ -h, --help Show help
52
+
53
+ Examples:
54
+ npx @xevy/skills -y # (global by default)
55
+ npx @xevy/skills --project -y # install into this repo instead of globally
56
+ npx @xevy/skills check
57
+ npx @xevy/skills update -y
58
+ npx @xevy/skills -a cursor -y
59
+ XEVY_BASE=https://xevy.vyte.dev npx @xevy/skills update --manifest -y
60
+ `);
61
+ }
62
+
63
+ function parseArgv(argv) {
64
+ const opts = {
65
+ command: "install",
66
+ global: true,
67
+ yes: false,
68
+ copy: false,
69
+ manifest: false,
70
+ skillsOnly: false,
71
+ agents: [],
72
+ skills: [],
73
+ base: process.env.XEVY_BASE?.replace(/\/$/, "") || DEFAULT_BASE,
74
+ rest: [],
75
+ };
76
+
77
+ const args = [...argv];
78
+ if (args.length === 0 || args[0] === "install") {
79
+ if (args[0] === "install") args.shift();
80
+ } else if (!args[0].startsWith("-")) {
81
+ const cmd = args.shift();
82
+ if (
83
+ [
84
+ "install",
85
+ "check",
86
+ "update",
87
+ "skills",
88
+ "mcp",
89
+ "sync-env",
90
+ "link-repo",
91
+ "help",
92
+ ].includes(cmd)
93
+ ) {
94
+ opts.command = cmd;
95
+ } else {
96
+ opts.rest = [cmd, ...args];
97
+ return opts;
98
+ }
99
+ }
100
+
101
+ while (args.length > 0) {
102
+ const a = args.shift();
103
+ if (a === "-h" || a === "--help") {
104
+ opts.command = "help";
105
+ return opts;
106
+ }
107
+ if (a === "--project" || a === "--local" || a === "--no-global") {
108
+ opts.global = false;
109
+ continue;
110
+ }
111
+ if (a === "-g" || a === "--global") {
112
+ opts.global = true;
113
+ continue;
114
+ }
115
+ if (a === "-y" || a === "--yes") {
116
+ opts.yes = true;
117
+ continue;
118
+ }
119
+ if (a === "--copy") {
120
+ opts.copy = true;
121
+ continue;
122
+ }
123
+ if (a === "--manifest") {
124
+ opts.manifest = true;
125
+ continue;
126
+ }
127
+ if (a === "--skills-only") {
128
+ opts.skillsOnly = true;
129
+ continue;
130
+ }
131
+ if (a === "-a" || a === "--agent") {
132
+ const v = args.shift();
133
+ if (!v) die("Missing value for --agent");
134
+ opts.agents.push(v);
135
+ continue;
136
+ }
137
+ if (a === "-s" || a === "--skill") {
138
+ const v = args.shift();
139
+ if (!v) die("Missing value for --skill");
140
+ opts.skills.push(v);
141
+ continue;
142
+ }
143
+ if (a === "--base") {
144
+ const v = args.shift();
145
+ if (!v) die("Missing value for --base");
146
+ opts.base = v.replace(/\/$/, "");
147
+ continue;
148
+ }
149
+ opts.rest.push(a);
150
+ }
151
+
152
+ if (opts.agents.length === 0) opts.agents = [...DEFAULT_AGENTS];
153
+ return opts;
154
+ }
155
+
156
+ function die(msg) {
157
+ console.error(`✗ ${msg}`);
158
+ process.exit(1);
159
+ }
160
+
161
+ const isWindows = process.platform === "win32";
162
+
163
+ function quoteArg(a) {
164
+ return /[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a;
165
+ }
166
+
167
+ function run(cmd, args, { label } = {}) {
168
+ const title = label || [cmd, ...args].join(" ");
169
+ console.log(`→ ${title}`);
170
+ const command = isWindows && cmd === "npx" ? "npx.cmd" : cmd;
171
+ const finalArgs = isWindows ? args.map(quoteArg) : args;
172
+ const r = spawnSync(command, finalArgs, { stdio: "inherit", shell: isWindows, env: process.env });
173
+ if (r.error) die(r.error.message);
174
+ if (r.status !== 0) die(`Command failed (${r.status}): ${title}`);
175
+ return r;
176
+ }
177
+
178
+ function installSkills(opts, skillsRoot = pkgRoot) {
179
+ const skillArgs = ["--yes", "skills", "add", skillsRoot];
180
+ if (opts.global) skillArgs.push("-g");
181
+ if (opts.yes) skillArgs.push("-y");
182
+ if (opts.copy) skillArgs.push("--copy");
183
+ for (const a of opts.agents) skillArgs.push("-a", a);
184
+ if (opts.skills.length > 0) {
185
+ for (const s of opts.skills) skillArgs.push("-s", s);
186
+ } else {
187
+ skillArgs.push("-s", "*");
188
+ }
189
+ run("npx", skillArgs, { label: "npx skills add (Xevy skills)" });
190
+ }
191
+
192
+ function installMcp(opts) {
193
+ const mcpUrl = `${opts.base}/mcp`;
194
+ const mcpArgs = ["--yes", "add-mcp", mcpUrl, "-n", "xevy"];
195
+ if (opts.global) mcpArgs.push("-g");
196
+ if (opts.yes) mcpArgs.push("-y");
197
+ for (const a of opts.agents) mcpArgs.push("-a", a);
198
+ run("npx", mcpArgs, { label: `npx add-mcp ${mcpUrl}` });
199
+ }
200
+
201
+ function recordInstallStamp(opts, version) {
202
+ writeInstalledStamp(
203
+ process.cwd(),
204
+ {
205
+ version,
206
+ installedAt: new Date().toISOString(),
207
+ agents: opts.agents,
208
+ },
209
+ { global: opts.global },
210
+ );
211
+ }
212
+
213
+ async function resolveLatestVersion(opts) {
214
+ const bundled = readPackageVersion();
215
+ let latest = bundled;
216
+ let source = "bundled";
217
+
218
+ if (opts.manifest) {
219
+ try {
220
+ const manifest = await fetchAgentPackagesManifest(opts.base);
221
+ if (manifest?.skills?.version) {
222
+ latest = String(manifest.skills.version);
223
+ source = "manifest";
224
+ }
225
+ } catch (error) {
226
+ console.warn(`⚠ Could not read ${opts.base}/api/agent-packages (${error.message})`);
227
+ }
228
+ }
229
+
230
+ try {
231
+ const npmLatest = await fetchNpmLatestVersion();
232
+ if (source === "bundled" || compareSemver(npmLatest, latest) >= 0) {
233
+ latest = npmLatest;
234
+ source = "npm";
235
+ }
236
+ } catch (error) {
237
+ if (source === "bundled") {
238
+ throw new Error(`Could not resolve latest version (${error.message})`);
239
+ }
240
+ }
241
+
242
+ return { latest, source, bundled };
243
+ }
244
+
245
+ async function maybeReexecLatestCli(opts) {
246
+ const bundled = readPackageVersion();
247
+ let npmLatest;
248
+ try {
249
+ npmLatest = await fetchNpmLatestVersion();
250
+ } catch {
251
+ return false;
252
+ }
253
+ if (compareSemver(npmLatest, bundled) <= 0) return false;
254
+
255
+ console.log(`→ Installer ${bundled} is older than npm ${npmLatest}; re-running with @latest…`);
256
+ const forwardArgs = ["--yes", `@xevy/skills@${npmLatest}`, opts.command];
257
+ if (opts.global) forwardArgs.push("-g");
258
+ if (opts.yes) forwardArgs.push("-y");
259
+ if (opts.copy) forwardArgs.push("--copy");
260
+ if (opts.manifest) forwardArgs.push("--manifest");
261
+ if (opts.skillsOnly) forwardArgs.push("--skills-only");
262
+ if (opts.base !== DEFAULT_BASE) forwardArgs.push("--base", opts.base);
263
+ for (const a of opts.agents) forwardArgs.push("-a", a);
264
+ for (const s of opts.skills) forwardArgs.push("-s", s);
265
+ forwardArgs.push(...opts.rest);
266
+
267
+ run("npx", forwardArgs, { label: `npx @xevy/skills@${npmLatest} ${opts.command}` });
268
+ process.exit(0);
269
+ }
270
+
271
+ async function runCheck(opts) {
272
+ const stamp = readInstalledStamp(process.cwd(), { global: opts.global });
273
+ const { latest, source } = await resolveLatestVersion(opts);
274
+ const installed = stamp?.version ?? null;
275
+ const cliVersion = readPackageVersion();
276
+ const scope = opts.global ? "global" : "project";
277
+
278
+ console.log(`Xevy skills package`);
279
+ console.log(` CLI version: ${cliVersion}`);
280
+ console.log(` Scope: ${scope}`);
281
+ console.log(` Installed: ${installed ?? "(not recorded — run install or update)"}`);
282
+ console.log(` Latest (${source}): ${latest}`);
283
+
284
+ if (!installed) {
285
+ console.log(`\n⚠ No install stamp at ${stampPath(process.cwd(), { global: opts.global })}`);
286
+ console.log(" Run: npx @xevy/skills -y");
287
+ process.exit(1);
288
+ }
289
+
290
+ if (compareSemver(latest, installed) > 0) {
291
+ console.log(`\n↻ Update available: ${installed} → ${latest}`);
292
+ console.log(" Run: npx @xevy/skills update -y");
293
+ process.exit(2);
294
+ }
295
+
296
+ console.log("\n✓ Xevy skills are up to date.");
297
+ }
298
+
299
+ async function runUpdate(opts) {
300
+ await maybeReexecLatestCli(opts);
301
+
302
+ const stamp = readInstalledStamp(process.cwd(), { global: opts.global });
303
+ const { latest } = await resolveLatestVersion(opts);
304
+ const installed = stamp?.version ?? null;
305
+
306
+ if (installed && compareSemver(latest, installed) <= 0) {
307
+ console.log(`✓ Xevy skills already at ${installed}`);
308
+ if (!opts.skillsOnly) {
309
+ installMcp(opts);
310
+ }
311
+ recordInstallStamp(opts, installed);
312
+ return;
313
+ }
314
+
315
+ if (installed) {
316
+ console.log(`↻ Updating Xevy skills ${installed} → ${latest}…`);
317
+ } else {
318
+ console.log(`→ Installing Xevy skills@${latest}…`);
319
+ }
320
+
321
+ installSkills(opts);
322
+ if (!opts.skillsOnly) {
323
+ installMcp(opts);
324
+ }
325
+ recordInstallStamp(opts, latest);
326
+ console.log(`\n✓ Xevy skills updated to ${latest}.`);
327
+ }
328
+
329
+ function forwardHelper(script, rest) {
330
+ const scriptPath = path.join(pkgRoot, "bin", script);
331
+ const r = spawnSync(process.execPath, [scriptPath, ...rest], {
332
+ stdio: "inherit",
333
+ env: process.env,
334
+ });
335
+ process.exit(r.status ?? 1);
336
+ }
337
+
338
+ async function main() {
339
+ const opts = parseArgv(process.argv.slice(2));
340
+
341
+ if (opts.command === "help") {
342
+ usage();
343
+ process.exit(0);
344
+ }
345
+
346
+ if (opts.command === "sync-env") {
347
+ forwardHelper("xevy-sync-env.mjs", opts.rest);
348
+ }
349
+ if (opts.command === "link-repo") {
350
+ forwardHelper("xevy-link-repo.mjs", opts.rest);
351
+ }
352
+
353
+ if (opts.command === "check") {
354
+ await runCheck(opts);
355
+ return;
356
+ }
357
+
358
+ if (opts.command === "update") {
359
+ await runUpdate(opts);
360
+ return;
361
+ }
362
+
363
+ if (opts.command === "skills" || opts.command === "install") {
364
+ installSkills(opts);
365
+ recordInstallStamp(opts, readPackageVersion());
366
+ }
367
+
368
+ if (opts.command === "mcp" || opts.command === "install") {
369
+ installMcp(opts);
370
+ }
371
+
372
+ if (opts.command === "install") {
373
+ console.log("\n✓ Xevy skills + MCP installed.");
374
+ console.log(" • Complete OAuth in your agent (Cursor: Settings → MCP).");
375
+ console.log(" • Run the setup skill in your repo (ask the agent to use the Xevy setup skill).");
376
+ console.log(` • Docs: ${opts.base}/docs/mcp`);
377
+ console.log(" • Later: npx @xevy/skills update -y");
378
+ } else if (opts.command === "skills") {
379
+ console.log("\n✓ Xevy skills installed.");
380
+ } else if (opts.command === "mcp") {
381
+ console.log("\n✓ Xevy MCP configured.");
382
+ }
383
+ }
384
+
385
+ main().catch((error) => {
386
+ die(error instanceof Error ? error.message : String(error));
387
+ });
@@ -0,0 +1,120 @@
1
+ /**
2
+ * Semver + install stamp helpers for @xevy/skills check/update.
3
+ */
4
+ import fs from "node:fs";
5
+ import os from "node:os";
6
+ import path from "node:path";
7
+ import { fileURLToPath } from "node:url";
8
+
9
+ const here = path.dirname(fileURLToPath(import.meta.url));
10
+ export const pkgRoot = path.resolve(here, "..");
11
+ export const STAMP_REL = ".xevy/skills-package.json";
12
+ export const PACKAGE_NAME = "@xevy/skills";
13
+
14
+ /** Directory holding the stamp for a global (user-scope) install. */
15
+ export function globalStampDir() {
16
+ const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
17
+ return path.join(base, "xevy");
18
+ }
19
+
20
+ export function readPackageVersion() {
21
+ const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, "package.json"), "utf-8"));
22
+ return String(pkg.version || "0.0.0");
23
+ }
24
+
25
+ function normalizeVersionParts(version) {
26
+ return version
27
+ .split(".")
28
+ .map((part) => {
29
+ const trimmed = part.trim();
30
+ if (!trimmed) return 0;
31
+ return /^\d+$/.test(trimmed) ? Number(trimmed) : trimmed.toLowerCase();
32
+ });
33
+ }
34
+
35
+ /** @returns {-1|0|1} */
36
+ export function compareSemver(left, right) {
37
+ const leftParts = normalizeVersionParts(left);
38
+ const rightParts = normalizeVersionParts(right);
39
+ const maxLength = Math.max(leftParts.length, rightParts.length);
40
+
41
+ for (let index = 0; index < maxLength; index += 1) {
42
+ const leftPart = leftParts[index] ?? 0;
43
+ const rightPart = rightParts[index] ?? 0;
44
+
45
+ if (typeof leftPart === "number" && typeof rightPart === "number") {
46
+ if (leftPart > rightPart) return 1;
47
+ if (leftPart < rightPart) return -1;
48
+ continue;
49
+ }
50
+
51
+ const leftText = String(leftPart);
52
+ const rightText = String(rightPart);
53
+ if (leftText > rightText) return 1;
54
+ if (leftText < rightText) return -1;
55
+ }
56
+
57
+ return 0;
58
+ }
59
+
60
+ /**
61
+ * Where the install stamp lives. A global install writes it to the user config
62
+ * dir so `check`/`update` find it from any repo; a project install keeps it in
63
+ * the repo's .xevy/. The stamp scope must match the install scope.
64
+ */
65
+ export function stampPath(cwd = process.cwd(), { global = false } = {}) {
66
+ if (global) return path.join(globalStampDir(), "skills-package.json");
67
+ return path.join(cwd, STAMP_REL);
68
+ }
69
+
70
+ /** @returns {{ version: string, installedAt: string, agents?: string[] } | null} */
71
+ export function readInstalledStamp(cwd = process.cwd(), { global = false } = {}) {
72
+ const p = stampPath(cwd, { global });
73
+ if (!fs.existsSync(p)) return null;
74
+ try {
75
+ return JSON.parse(fs.readFileSync(p, "utf-8"));
76
+ } catch {
77
+ return null;
78
+ }
79
+ }
80
+
81
+ export function writeInstalledStamp(cwd, data, { global = false } = {}) {
82
+ const p = stampPath(cwd, { global });
83
+ fs.mkdirSync(path.dirname(p), { recursive: true });
84
+ fs.writeFileSync(
85
+ p,
86
+ `${JSON.stringify(
87
+ {
88
+ package: PACKAGE_NAME,
89
+ version: data.version,
90
+ installedAt: data.installedAt || new Date().toISOString(),
91
+ agents: data.agents,
92
+ },
93
+ null,
94
+ 2,
95
+ )}\n`,
96
+ );
97
+ }
98
+
99
+ export async function fetchNpmLatestVersion(packageName = PACKAGE_NAME) {
100
+ const url = `https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`;
101
+ const response = await fetch(url, { headers: { accept: "application/json" } });
102
+ if (!response.ok) {
103
+ throw new Error(`npm registry HTTP ${response.status}`);
104
+ }
105
+ const data = await response.json();
106
+ const version = data?.version;
107
+ if (!version) throw new Error("npm registry returned no version");
108
+ return String(version);
109
+ }
110
+
111
+ export async function fetchAgentPackagesManifest(baseUrl) {
112
+ const normalized = baseUrl.replace(/\/$/, "");
113
+ const response = await fetch(`${normalized}/api/agent-packages`, {
114
+ headers: { accept: "application/json" },
115
+ });
116
+ if (!response.ok) {
117
+ throw new Error(`agent-packages HTTP ${response.status}`);
118
+ }
119
+ return response.json();
120
+ }