relayax-cli 0.3.51 → 0.3.53

package/dist/commands/create.js

@@ -8,6 +8,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
 const ai_tools_js_1 = require("../lib/ai-tools.js");
+const step_tracker_js_1 = require("../lib/step-tracker.js");
 const command_adapter_js_1 = require("../lib/command-adapter.js");
 const init_js_1 = require("./init.js");
 const slug_js_1 = require("../lib/slug.js");
@@ -33,6 +34,7 @@ function registerCreate(program) {
         .option('--project <dir>', '프로젝트 루트 경로 (기본: cwd, 환경변수: RELAY_PROJECT_PATH)')
         .action(async (name, opts) => {
         const json = program.opts().json ?? false;
+        (0, step_tracker_js_1.trackCommand)('create');
         const projectPath = (0, paths_js_1.resolveProjectPath)(opts.project);
         const relayDir = path_1.default.join(projectPath, '.relay');
         const relayYamlPath = path_1.default.join(relayDir, 'relay.yaml');

package/dist/commands/feedback.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerFeedback(program: Command): void;

package/dist/commands/feedback.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFeedback = registerFeedback;
+const config_js_1 = require("../lib/config.js");
+const device_hash_js_1 = require("../lib/device-hash.js");
+function registerFeedback(program) {
+    program
+        .command('feedback <message>')
+        .description('피드백을 전송합니다')
+        .action(async (message) => {
+        const json = program.opts().json ?? false;
+        const deviceHash = (0, device_hash_js_1.getDeviceHash)();
+        // 설치된 에이전트 slug 목록
+        const installed = (0, config_js_1.loadInstalled)();
+        const installedAgents = Object.keys(installed);
+        // 로그인 사용자 정보 (optional)
+        let userId;
+        let username;
+        const token = await (0, config_js_1.getValidToken)();
+        if (token) {
+            try {
+                const res = await fetch(`${config_js_1.API_URL}/api/auth/me`, {
+                    headers: { Authorization: `Bearer ${token}` },
+                    signal: AbortSignal.timeout(5000),
+                });
+                if (res.ok) {
+                    const me = (await res.json());
+                    userId = me.id;
+                    username = me.username;
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        try {
+            const res = await fetch(`${config_js_1.API_URL}/api/feedback`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    message,
+                    user_id: userId ?? null,
+                    username: username ?? null,
+                    device_hash: deviceHash,
+                    installed_agents: installedAgents.length > 0 ? installedAgents : null,
+                }),
+                signal: AbortSignal.timeout(10000),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => '');
+                throw new Error(`서버 응답 오류 (${res.status}): ${body}`);
+            }
+            if (json) {
+                console.log(JSON.stringify({ status: 'ok', message: '피드백이 전송되었습니다' }));
+            }
+            else {
+                console.log('\x1b[32m✓ 피드백이 전송되었습니다. 감사합니다!\x1b[0m');
+            }
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            if (json) {
+                console.error(JSON.stringify({ error: 'FEEDBACK_FAILED', message: errMsg }));
+            }
+            else {
+                console.error(`\x1b[31m피드백 전송 실패: ${errMsg}\x1b[0m`);
+            }
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/install.js

@@ -13,6 +13,8 @@ const slug_js_1 = require("../lib/slug.js");
 const preamble_js_1 = require("../lib/preamble.js");
 const init_js_1 = require("./init.js");
 const paths_js_1 = require("../lib/paths.js");
+const error_report_js_1 = require("../lib/error-report.js");
+const step_tracker_js_1 = require("../lib/step-tracker.js");
 function registerInstall(program) {
     program
         .command('install <slug>')
@@ -30,6 +32,7 @@ function registerInstall(program) {
             }
             (0, init_js_1.installGlobalUserCommands)();
         }
+        (0, step_tracker_js_1.trackCommand)('install', { slug: slugInput });
         try {
             // Resolve scoped slug and fetch agent metadata
             let agent;
@@ -258,6 +261,7 @@ function registerInstall(program) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
+            (0, error_report_js_1.reportCliError)('install', 'INSTALL_FAILED', message);
             console.error(JSON.stringify({ error: 'INSTALL_FAILED', message, fix: message }));
             process.exit(1);
         }

package/dist/commands/join.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.joinOrg = joinOrg;
 exports.registerJoin = registerJoin;
 const config_js_1 = require("../lib/config.js");
+const step_tracker_js_1 = require("../lib/step-tracker.js");
 const init_js_1 = require("./init.js");
 async function joinOrg(orgSlug, code) {
     const token = await (0, config_js_1.getValidToken)();
@@ -36,6 +37,7 @@ function registerJoin(program) {
         .requiredOption('--code <code>', '초대 코드 (UUID)')
         .action(async (slug, opts) => {
         const json = program.opts().json ?? false;
+        (0, step_tracker_js_1.trackCommand)('join', { slug });
         if (!(0, init_js_1.hasGlobalUserCommands)()) {
             if (!json) {
                 console.error('\x1b[33m⚠ relay init이 실행되지 않았습니다. 먼저 relay init을 실행하세요.\x1b[0m');

package/dist/commands/login.js

@@ -8,6 +8,8 @@ exports.registerLogin = registerLogin;
 const http_1 = __importDefault(require("http"));
 const child_process_1 = require("child_process");
 const config_js_1 = require("../lib/config.js");
+const error_report_js_1 = require("../lib/error-report.js");
+const step_tracker_js_1 = require("../lib/step-tracker.js");
 function openBrowser(url) {
     const platform = process.platform;
     try {
@@ -183,6 +185,7 @@ function registerLogin(program) {
         .action(async (opts) => {
         const json = program.opts().json ?? false;
         (0, config_js_1.ensureGlobalRelayDir)();
+        (0, step_tracker_js_1.trackCommand)('login');
         let accessToken = opts.token;
         let refreshToken;
         let expiresAt;
@@ -196,6 +199,7 @@ function registerLogin(program) {
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : '로그인 실패';
+                (0, error_report_js_1.reportCliError)('login', 'LOGIN_FAILED', msg);
                 if (json) {
                     console.error(JSON.stringify({ error: 'LOGIN_FAILED', message: msg, fix: opts.device ? '다시 시도하세요.' : 'relay login --device를 시도하세요.' }));
                 }

package/dist/commands/ping.js

@@ -31,10 +31,8 @@ function registerPing(program) {
         const entry = local[slug] ?? global[slug];
         const version = entry?.version;
         const agentId = entry?.agent_id;
-        // Fire-and-forget ping (agent_id 기반, 없으면 skip)
-        if (agentId) {
-            await (0, api_js_1.sendUsagePing)(agentId, slug, version);
-        }
+        // Fire-and-forget ping (agent_id 없어도 slug fallback으로 전송)
+        await (0, api_js_1.sendUsagePing)(agentId ?? null, slug, version);
         if (!opts.quiet) {
             console.log(`RELAY_READY: ${slug}`);
         }

package/dist/commands/publish.js

@@ -15,6 +15,8 @@ const config_js_1 = require("../lib/config.js");
 const preamble_js_1 = require("../lib/preamble.js");
 const version_check_js_1 = require("../lib/version-check.js");
 const paths_js_1 = require("../lib/paths.js");
+const error_report_js_1 = require("../lib/error-report.js");
+const step_tracker_js_1 = require("../lib/step-tracker.js");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const cliPkg = require('../../package.json');
 const VALID_DIRS = ['skills', 'agents', 'rules', 'commands', 'bin'];
@@ -173,7 +175,7 @@ function detectAgentDetails(agentDir, requires) {
  * 에이전트 진입점 커맨드(commands/{author}-{name}.md)를 생성한다.
  * root SKILL.md를 대체하여 에이전트의 얼굴 역할을 한다.
  */
-function generateEntryCommand(config, commands, skills, scopedSlug) {
+function generateEntryCommand(config, commands, skills, scopedSlug, agentDir) {
     const lines = [];
     // Frontmatter
     lines.push('---');
@@ -181,7 +183,7 @@ function generateEntryCommand(config, commands, skills, scopedSlug) {
     lines.push('---');
     lines.push('');
     // Preamble
-    lines.push((0, preamble_js_1.generatePreamble)(scopedSlug));
+    lines.push((0, preamble_js_1.generatePreamble)(scopedSlug, agentDir));
     lines.push('');
     // Agent header
     lines.push(`## ${config.name}`);
@@ -294,6 +296,7 @@ function registerPublish(program) {
         const relayDir = path_1.default.join(agentDir, '.relay');
         const relayYamlPath = path_1.default.join(relayDir, 'relay.yaml');
         const isTTY = Boolean(process.stdin.isTTY) && !json;
+        (0, step_tracker_js_1.trackCommand)('publish', { slug: undefined });
         // CLI update check before publish
         if (isTTY) {
             const cliUpdate = await (0, version_check_js_1.checkCliVersion)(true);
@@ -308,6 +311,7 @@ function registerPublish(program) {
                         default: true,
                     });
                     if (!shouldContinue) {
+                        (0, error_report_js_1.reportCliError)('publish', 'CANCELLED_CLI_UPDATE', `current:${cliUpdate.current} latest:${cliUpdate.latest}`);
                         console.error('\n배포를 취소했습니다. CLI를 업데이트한 후 다시 시도하세요.');
                         process.exit(0);
                     }
@@ -321,6 +325,7 @@ function registerPublish(program) {
         // Check .relay/relay.yaml exists
         if (!fs_1.default.existsSync(relayYamlPath)) {
             if (!isTTY) {
+                (0, error_report_js_1.reportCliError)('publish', 'NOT_INITIALIZED', 'relay.yaml missing');
                 console.error(JSON.stringify({
                     error: 'NOT_INITIALIZED',
                     message: '.relay/relay.yaml이 없습니다. 먼저 `relay create`를 실행하세요.',
@@ -385,6 +390,7 @@ function registerPublish(program) {
         const yamlContent = fs_1.default.readFileSync(relayYamlPath, 'utf-8');
         const config = parseRelayYaml(yamlContent);
         if (!config.slug || !config.name || !config.description) {
+            (0, error_report_js_1.reportCliError)('publish', 'INVALID_CONFIG', 'missing name/slug/description');
             console.error(JSON.stringify({
                 error: 'INVALID_CONFIG',
                 message: 'relay.yaml에 name, slug, description이 필요합니다.',
@@ -430,6 +436,7 @@ function registerPublish(program) {
             return fs_1.default.readdirSync(dirPath).filter((f) => !f.startsWith('.')).length > 0;
         });
         if (!hasDirs) {
+            (0, error_report_js_1.reportCliError)('publish', 'EMPTY_PACKAGE', 'no content dirs found');
             console.error(JSON.stringify({
                 error: 'EMPTY_PACKAGE',
                 message: '.relay/ 안에 skills/, agents/, rules/, commands/ 중 하나 이상에 파일이 있어야 합니다.',
@@ -440,6 +447,7 @@ function registerPublish(program) {
         // Get token (checked before tarball creation)
         const token = opts.token ?? process.env.RELAY_TOKEN ?? await (0, config_js_1.getValidToken)();
         if (!token) {
+            (0, error_report_js_1.reportCliError)('publish', 'NO_TOKEN', 'auth required');
             console.error(JSON.stringify({
                 error: 'NO_TOKEN',
                 message: '인증이 필요합니다. `relay login`을 먼저 실행하세요.',
@@ -472,6 +480,7 @@ function registerPublish(program) {
                     else {
                         console.error(`Organization '${opts.space}'를 찾을 수 없습니다.`);
                     }
+                    (0, error_report_js_1.reportCliError)('publish', 'INVALID_ORG', `org:${opts.space}`);
                     process.exit(1);
                 }
             }
@@ -507,6 +516,7 @@ function registerPublish(program) {
             }
             else if (orgs.length > 1 && json) {
                 // --json 모드 + 여러 Org: 에이전트가 선택할 수 있도록 에러 반환
+                (0, error_report_js_1.reportCliError)('publish', 'MISSING_ORG', 'multiple orgs, none selected');
                 console.error(JSON.stringify({
                     error: 'MISSING_ORG',
                     message: '배포할 Organization을 선택하세요.',
@@ -555,6 +565,7 @@ function registerPublish(program) {
                 console.error(`  → relay.yaml에 visibility: ${config.visibility} 저장됨\n`);
             }
             else {
+                (0, error_report_js_1.reportCliError)('publish', 'MISSING_VISIBILITY', 'visibility not set in relay.yaml');
                 console.error(JSON.stringify({
                     error: 'MISSING_VISIBILITY',
                     message: 'relay.yaml에 visibility를 설정해주세요.',
@@ -648,7 +659,7 @@ function registerPublish(program) {
         // Generate bin/relay-preamble.sh (self-contained tracking + update check)
         (0, preamble_js_1.generatePreambleBin)(relayDir, config.slug, config_js_1.API_URL);
         // Generate entry command (commands/{author}-{name}.md)
-        const entryContent = generateEntryCommand(config, detectedCommands, detectedSkills, config.slug);
+        const entryContent = generateEntryCommand(config, detectedCommands, detectedSkills, config.slug, relayDir);
         const commandsDir = path_1.default.join(relayDir, 'commands');
         if (!fs_1.default.existsSync(commandsDir)) {
             fs_1.default.mkdirSync(commandsDir, { recursive: true });
@@ -671,7 +682,7 @@ function registerPublish(program) {
                     const entryFile = path_1.default.join(relayDir, 'commands', serverSlug.replace('/', '-') + '.md');
                     if (fs_1.default.existsSync(entryFile)) {
                         const { injectPreamble } = await import('../lib/preamble.js');
-                        injectPreamble(entryFile, result.slug);
+                        injectPreamble(entryFile, result.slug, relayDir);
                     }
                 }
             }
@@ -716,6 +727,7 @@ function registerPublish(program) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
+            (0, error_report_js_1.reportCliError)('publish', 'PUBLISH_FAILED', message);
             console.error(JSON.stringify({ error: 'PUBLISH_FAILED', message, fix: message }));
             process.exit(1);
         }

package/dist/commands/search.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerSearch = registerSearch;
 const api_js_1 = require("../lib/api.js");
+const step_tracker_js_1 = require("../lib/step-tracker.js");
 function formatTable(results) {
     if (results.length === 0)
         return '검색 결과가 없습니다.';
@@ -31,6 +32,7 @@ function registerSearch(program) {
         .option('--space <space>', '특정 Space 내에서 검색')
         .action(async (keyword, opts) => {
         const json = program.opts().json ?? false;
+        (0, step_tracker_js_1.trackCommand)('search', { slug: keyword });
         try {
             const results = await (0, api_js_1.searchAgents)(keyword, opts.tag);
             if (json) {

package/dist/index.js

@@ -25,6 +25,7 @@ const access_js_1 = require("./commands/access.js");
 const grant_js_1 = require("./commands/grant.js");
 const versions_js_1 = require("./commands/versions.js");
 const diff_js_1 = require("./commands/diff.js");
+const feedback_js_1 = require("./commands/feedback.js");
 const server_js_1 = require("./mcp/server.js");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const pkg = require('../package.json');
@@ -57,6 +58,7 @@ program
 (0, grant_js_1.registerGrant)(program);
 (0, versions_js_1.registerVersions)(program);
 (0, diff_js_1.registerDiff)(program);
+(0, feedback_js_1.registerFeedback)(program);
 program
     .command('mcp')
     .description('MCP 서버 모드로 실행합니다 (stdio transport)')

package/dist/lib/api.d.ts

@@ -20,5 +20,5 @@ export interface ResolvedSlug {
     full: string;
 }
 export declare function resolveSlugFromServer(name: string): Promise<ResolvedSlug[]>;
-export declare function sendUsagePing(agentId: string, slug: string, version?: string): Promise<void>;
+export declare function sendUsagePing(agentId: string | null, slug: string, version?: string): Promise<void>;
 export declare function followBuilder(username: string): Promise<void>;

package/dist/lib/api.js

@@ -94,7 +94,9 @@ async function sendUsagePing(agentId, slug, version) {
     const deviceHash = createHash('sha256')
         .update(`${hostname()}:${userInfo().username}`)
         .digest('hex');
-    const url = `${config_js_1.API_URL}/api/agents/${agentId}/ping`;
+    // agentId(UUID)가 있으면 UUID 경로, 없으면 slug name으로 fallback
+    const pathParam = agentId || slug.replace(/^@/, '').split('/').pop() || slug;
+    const url = `${config_js_1.API_URL}/api/agents/${pathParam}/ping`;
     const payload = { device_hash: deviceHash, slug };
     if (version)
         payload.installed_version = version;
@@ -106,6 +108,7 @@ async function sendUsagePing(agentId, slug, version) {
         method: 'POST',
         headers,
         body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(5000),
     }).catch(() => {
         // fire-and-forget: ignore errors
     });

package/dist/lib/command-adapter.js

@@ -37,6 +37,7 @@ const ENV_PREAMBLE = `## 환경 감지
 | \`relay uninstall <slug>\` | \`relay_uninstall\` tool 호출 |
 | \`relay package --init\` | \`relay_scan\` tool 호출 |
 | \`relay publish\` | \`relay_publish\` tool 호출 |
+| \`relay login\` | \`relay_login\` tool 호출 |
 
 **중요**: 이후 지시에서 \`relay <명령어>\`로 표기된 것은 판별된 환경에 따라 변환하여 실행하세요.
 

package/dist/lib/error-report.d.ts

@@ -0,0 +1,5 @@
+/**
+ * CLI 에러를 서버에 fire-and-forget으로 리포트한다.
+ * 실패해도 사용자에게 표시하지 않는다.
+ */
+export declare function reportCliError(command: string, errorCode: string, errorMessage: string): void;

package/dist/lib/error-report.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportCliError = reportCliError;
+const config_js_1 = require("./config.js");
+const device_hash_js_1 = require("./device-hash.js");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const pkg = require('../../package.json');
+/**
+ * CLI 에러를 서버에 fire-and-forget으로 리포트한다.
+ * 실패해도 사용자에게 표시하지 않는다.
+ */
+function reportCliError(command, errorCode, errorMessage) {
+    const deviceHash = (0, device_hash_js_1.getDeviceHash)();
+    fetch(`${config_js_1.API_URL}/api/analytics/cli-errors`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            device_hash: deviceHash,
+            command,
+            error_code: errorCode,
+            error_message: errorMessage.slice(0, 200),
+            cli_version: pkg.version,
+        }),
+        signal: AbortSignal.timeout(5000),
+    }).catch(() => {
+        // fire-and-forget
+    });
+}

package/dist/lib/preamble.d.ts

@@ -5,9 +5,9 @@
 export declare function generatePreambleScript(slug: string, apiUrl: string): string;
 /**
  * SKILL.md / command에 삽입할 preamble 마크다운.
- * 단순히 relay ping을 호출한다.
+ * agentDir: 설치된 에이전트의 절대 경로 (install 시점에 결정)
  */
-export declare function generatePreamble(slug: string): string;
+export declare function generatePreamble(slug: string, agentDir: string): string;
 /**
  * agentDir에 bin/relay-preamble.sh를 생성한다.
  */
@@ -15,7 +15,7 @@ export declare function generatePreambleBin(agentDir: string, slug: string, apiU
 /**
  * frontmatter(---...---) 뒤에 preamble을 삽입한다.
  */
-export declare function injectPreamble(filePath: string, slug: string): void;
+export declare function injectPreamble(filePath: string, slug: string, agentDir: string): void;
 /**
  * 에이전트의 사용자 진입점 파일에 preamble을 주입한다.
  */

package/dist/lib/preamble.js

@@ -25,19 +25,29 @@ function generatePreambleScript(slug, apiUrl) {
 # relay-preamble.sh — auto-generated by relay publish
 set +e
 
-DEVICE_HASH=$(echo "$HOSTNAME:$USER" | shasum -a 256 | cut -d' ' -f1)
+# Device hash (shasum → sha256sum → openssl fallback)
+_RAW="$(hostname):$(whoami)"
+if command -v shasum &>/dev/null; then
+  DEVICE_HASH=$(printf '%s' "$_RAW" | shasum -a 256 | cut -d' ' -f1)
+elif command -v sha256sum &>/dev/null; then
+  DEVICE_HASH=$(printf '%s' "$_RAW" | sha256sum | cut -d' ' -f1)
+elif command -v openssl &>/dev/null; then
+  DEVICE_HASH=$(printf '%s' "$_RAW" | openssl dgst -sha256 | awk '{print $NF}')
+else
+  DEVICE_HASH="unknown"
+fi
 
 # Usage ping
 if command -v relay &>/dev/null; then
   relay ping "${slug}" --quiet 2>/dev/null &
-else
-  curl -sf -X POST "${apiUrl}/api/agents/${agentSlug}/ping" \\
+elif command -v curl &>/dev/null; then
+  curl -sf --max-time 5 -X POST "${apiUrl}/api/agents/${agentSlug}/ping" \\
     -H "Content-Type: application/json" \\
-    -d "{\\"device_hash\\":\\"$DEVICE_HASH\\"}" \\
+    -d "{\\"device_hash\\":\\"$DEVICE_HASH\\",\\"slug\\":\\"${slug}\\"}" \\
     2>/dev/null &
 fi
 
-# Update check
+# Update check (already 24h cached by relay CLI)
 if command -v relay &>/dev/null; then
   _UPD=$(relay check-update "${slug}" --quiet 2>/dev/null || true)
   [ -n "$_UPD" ] && echo "$_UPD" || true
@@ -48,17 +58,19 @@ echo "RELAY_READY: ${slug}"
 }
 /**
  * SKILL.md / command에 삽입할 preamble 마크다운.
- * 단순히 relay ping을 호출한다.
+ * agentDir: 설치된 에이전트의 절대 경로 (install 시점에 결정)
  */
-function generatePreamble(slug) {
-    const agentPath = slug.startsWith('@') ? slug.slice(1) : slug;
+function generatePreamble(slug, agentDir) {
+    const scriptPath = path_1.default.join(agentDir, 'bin', 'relay-preamble.sh');
     return `${PREAMBLE_START}
 ## Preamble (run first)
 
 \`\`\`bash
-bash "$HOME/.relay/agents/${agentPath}/bin/relay-preamble.sh" 2>/dev/null || true
+[ -f "${scriptPath}" ] && bash "${scriptPath}" 2>/dev/null || true
 \`\`\`
 
+If the bash command above fails or the file is not found (sandbox/MCP environment), use the \`relay_check_update\` MCP tool instead: \`relay_check_update(slug: "${slug}")\`
+
 If output shows \`CLI_UPGRADE_AVAILABLE <old> <new>\`: tell user "relay v{new} available. Run: npm update -g relayax-cli"
 If output shows \`AGENT_UPGRADE_AVAILABLE\`: tell user "${slug} v{new} available (by @{author}). Run: relay update ${slug}"
 ${PREAMBLE_END}`;
@@ -78,9 +90,9 @@ function generatePreambleBin(agentDir, slug, apiUrl) {
 /**
  * frontmatter(---...---) 뒤에 preamble을 삽입한다.
  */
-function injectPreamble(filePath, slug) {
+function injectPreamble(filePath, slug, agentDir) {
     const content = fs_1.default.readFileSync(filePath, 'utf-8');
-    const preamble = generatePreamble(slug);
+    const preamble = generatePreamble(slug, agentDir);
     // 기존 preamble 제거
     let cleaned = content;
     const startIdx = cleaned.indexOf(PREAMBLE_START);
@@ -122,7 +134,7 @@ function injectPreambleToAgent(agentDir, slug) {
                 else if (entry.name === 'SKILL.md') {
                     const content = fs_1.default.readFileSync(fullPath, 'utf-8');
                     if (/user-invocable:\s*true/i.test(content)) {
-                        injectPreamble(fullPath, slug);
+                        injectPreamble(fullPath, slug, agentDir);
                         count++;
                     }
                 }
@@ -136,7 +148,7 @@ function injectPreambleToAgent(agentDir, slug) {
         for (const entry of fs_1.default.readdirSync(commandsDir, { withFileTypes: true })) {
             if (!entry.isFile() || !entry.name.endsWith('.md'))
                 continue;
-            injectPreamble(path_1.default.join(commandsDir, entry.name), slug);
+            injectPreamble(path_1.default.join(commandsDir, entry.name), slug, agentDir);
             count++;
         }
     }

package/dist/lib/step-tracker.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CLI 명령 실행을 서버에 기록한다 (fire-and-forget).
+ * device_hash 기준으로 사용자 여정(login → create → publish)을 추적.
+ */
+export declare function trackCommand(command: string, opts?: {
+    slug?: string;
+    success?: boolean;
+}): void;

package/dist/lib/step-tracker.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackCommand = trackCommand;
+const config_js_1 = require("./config.js");
+const device_hash_js_1 = require("./device-hash.js");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const pkg = require('../../package.json');
+/**
+ * CLI 명령 실행을 서버에 기록한다 (fire-and-forget).
+ * device_hash 기준으로 사용자 여정(login → create → publish)을 추적.
+ */
+function trackCommand(command, opts) {
+    const deviceHash = (0, device_hash_js_1.getDeviceHash)();
+    fetch(`${config_js_1.API_URL}/api/analytics/cli-commands`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            device_hash: deviceHash,
+            command,
+            slug: opts?.slug ?? null,
+            success: opts?.success ?? true,
+            cli_version: pkg.version,
+        }),
+        signal: AbortSignal.timeout(5000),
+    }).catch(() => {
+        // fire-and-forget
+    });
+}

package/dist/mcp/server.js

@@ -173,15 +173,33 @@ function createMcpServer() {
                     project,
                 })] };
     });
-    server.tool('relay_check_update', 'CLI 및 에이전트 업데이트를 확인합니다', {}, async () => {
-        const { checkCliVersion, checkAllAgents } = await import('../lib/version-check.js');
+    server.tool('relay_check_update', 'CLI 및 에이전트 업데이트를 확인합니다. slug 지정 시 해당 에이전트만 체크하며 사용 현황도 기록합니다 (preamble 대체).', {
+        slug: zod_1.z.string().optional().describe('특정 에이전트 slug (예: @owner/name). 생략하면 전체 체크'),
+    }, async ({ slug: slugInput }) => {
+        const { checkCliVersion, checkAgentVersion, checkAllAgents } = await import('../lib/version-check.js');
+        // slug가 지정되면 해당 에이전트의 usage ping도 함께 전송
+        if (slugInput) {
+            const local = (0, config_js_1.loadInstalled)();
+            const global = (0, config_js_1.loadGlobalInstalled)();
+            const entry = local[slugInput] ?? global[slugInput];
+            const agentId = entry?.agent_id ?? null;
+            const version = entry?.version;
+            (0, api_js_1.sendUsagePing)(agentId, slugInput, version);
+        }
         const cliUpdate = await checkCliVersion(true);
-        const agentUpdates = await checkAllAgents(true);
         const updates = [];
         if (cliUpdate)
             updates.push({ type: 'cli', current: cliUpdate.current, latest: cliUpdate.latest });
-        for (const u of agentUpdates)
-            updates.push({ type: 'agent', slug: u.slug, current: u.current, latest: u.latest });
+        if (slugInput) {
+            const agentUpdate = await checkAgentVersion(slugInput, true);
+            if (agentUpdate)
+                updates.push({ type: 'agent', slug: agentUpdate.slug, current: agentUpdate.current, latest: agentUpdate.latest });
+        }
+        else {
+            const agentUpdates = await checkAllAgents(true);
+            for (const u of agentUpdates)
+                updates.push({ type: 'agent', slug: u.slug, current: u.current, latest: u.latest });
+        }
         if (updates.length === 0) {
             return { content: [jsonText({ status: 'up_to_date', message: '모두 최신 버전입니다.', cli_version: pkg.version })] };
         }
@@ -230,6 +248,8 @@ function createMcpServer() {
             }
             const cfg = js_yaml_1.default.load(fs_1.default.readFileSync(relayYaml, 'utf-8'));
             const { createTarball, publishToApi } = await import('../commands/publish.js');
+            // Generate bin/relay-preamble.sh (CLI publish와 동일하게)
+            (0, preamble_js_1.generatePreambleBin)(relayDir, cfg.slug, config_js_1.API_URL);
             const tarPath = await createTarball(relayDir);
             try {
                 const metadata = {
@@ -254,6 +274,61 @@ function createMcpServer() {
             return { content: [jsonText({ error: String(err) })], isError: true };
         }
     });
+    // ═══ relay_login — device code 로그인 ═══
+    server.tool('relay_login', 'Device Code 방식으로 로그인합니다. URL과 코드를 사용자에게 보여주고, 승인을 기다립니다.', {}, async () => {
+        try {
+            // 이미 로그인되어 있는지 확인
+            const existingToken = await (0, config_js_1.getValidToken)();
+            if (existingToken) {
+                const username = await resolveUsername(existingToken);
+                return { content: [jsonText({ status: 'already_authenticated', username })] };
+            }
+            // Device code 발급
+            const res = await fetch(`${config_js_1.API_URL}/api/auth/device/request`, { method: 'POST' });
+            if (!res.ok)
+                throw new Error('Device code 발급에 실패했습니다');
+            const { device_code, user_code, verification_url, expires_in } = await res.json();
+            // 브라우저 열기 시도
+            try {
+                const { execSync } = await import('child_process');
+                if (process.platform === 'darwin')
+                    execSync(`open "${verification_url}?user_code=${user_code}"`, { stdio: 'ignore' });
+                else if (process.platform === 'win32')
+                    execSync(`start "" "${verification_url}?user_code=${user_code}"`, { stdio: 'ignore' });
+                else
+                    execSync(`xdg-open "${verification_url}?user_code=${user_code}"`, { stdio: 'ignore' });
+            }
+            catch { /* 브라우저 열기 실패 — 사용자가 직접 열어야 함 */ }
+            // Polling (최대 expires_in 초, 5초 간격)
+            const deadline = Date.now() + expires_in * 1000;
+            while (Date.now() < deadline) {
+                await new Promise((r) => setTimeout(r, 5000));
+                const pollRes = await fetch(`${config_js_1.API_URL}/api/auth/device/poll`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ device_code }),
+                });
+                if (!pollRes.ok)
+                    continue;
+                const data = await pollRes.json();
+                if (data.status === 'approved' && data.token) {
+                    const { saveTokenData, ensureGlobalRelayDir } = await import('../lib/config.js');
+                    ensureGlobalRelayDir();
+                    saveTokenData({
+                        access_token: data.token,
+                        refresh_token: data.refresh_token,
+                        expires_at: data.expires_at ? Number(data.expires_at) : undefined,
+                    });
+                    const username = await resolveUsername(data.token);
+                    return { content: [jsonText({ status: 'ok', message: '로그인 완료', username })] };
+                }
+            }
+            return { content: [jsonText({ status: 'timeout', verification_url, user_code, message: `브라우저에서 ${verification_url} 을 열고 코드 ${user_code} 를 입력해주세요.` })], isError: true };
+        }
+        catch (err) {
+            return { content: [jsonText({ error: String(err) })], isError: true };
+        }
+    });
     // ═══ relay_init — slash command 설치 ═══
     server.tool('relay_init', 'relay slash command를 설치합니다 (/relay-install, /relay-publish 등)', {}, async () => {
         try {

package/dist/prompts/_setup-cli.md

@@ -1,30 +1,37 @@
-## Step 1. Relay CLI 준비
+## Step 1. Relay CLI 준비 및 업데이트
 
 ### 환경 A (터미널)
 
+CLI가 설치되어 있지 않다면:
+
 ```bash
 npm install -g relayax-cli
 relay init
 ```
 
-이미 설치되어 있다면 최신 버전으로 업데이트합니다:
+이미 설치되어 있다면 **반드시 최신 버전으로 업데이트**합니다:
 
 ```bash
 npm update -g relayax-cli
 relay init
 ```
 
+`relay init`은 slash command를 설치/업데이트합니다. 업데이트 후 반드시 실행하세요.
+
 Node.js가 없는 경우:
 - macOS: `brew install node`
 - Windows: `winget install OpenJS.NodeJS.LTS`
 - Linux: `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash && source ~/.bashrc && nvm install --lts`
 
-### 환경 B (샌드박스)
+### 환경 B (MCP)
 
-설치 없이 `npx`로 실행합니다. 이후 모든 `relay` 명령어를 `npx relayax-cli`로 대체하세요.
+**Step 1-1. 버전 확인**: `relay_check_update` tool을 반드시 호출하세요.
+- `status: "up_to_date"` → 최신 버전. Step 1-2로.
+- `status: "updates_available"` → 사용자에게 업데이트 안내:
+  > CLI 업데이트가 있습니다. 터미널에서 `npm update -g relayax-cli`를 실행해주세요.
 
-```bash
-npx relayax-cli --version
-```
+  사용자가 업데이트 완료 후 Claude를 재시작하면 최신 MCP 서버가 적용됩니다.
 
-정상 출력되면 준비 완료입니다.
+**Step 1-2. slash command 설치**: `relay_init` tool을 반드시 호출하세요.
+- `/relay-install`, `/relay-publish` 등 slash command가 설치/업데이트됩니다.
+- 이미 최신이면 자동으로 건너뜁니다.

package/dist/prompts/_setup-environment.md

@@ -58,7 +58,8 @@ cat ~/Library/Application\ Support/Claude/claude_desktop_config.json 2>/dev/null
 | "relay status" | `relay status` | `relay_status` tool 호출 |
 | "relay install X" | `relay install X` | `relay_install` tool 호출 (`slug: "X"`) |
 | "relay publish" | `relay publish` | `relay_publish` tool 호출 |
-| "relay login" | `relay login` | 사용자에게 터미널에서 `npx relayax-cli login --device` 안내 |
+| "relay login" | `relay login` | `relay_login` tool 호출 |
 | "relay scan" | `relay package --init` | `relay_scan` tool 호출 |
+| "relay check-update X" | `relay check-update X` | `relay_check_update` tool 호출 (`slug: "X"`) |
 
 처음 판별한 환경을 이후 계속 사용합니다.

package/dist/prompts/_setup-login.md

@@ -1,13 +1,13 @@
 ## Step 2. 로그인
 
-**중요: 로그인은 반드시 터미널(bash)에서 CLI 명령어로 수행합니다. 브라우저에서 직접 relayax.com에 접속하거나 웹 로그인 페이지를 여는 것은 올바른 방법이 아닙니다.**
+**중요: 브라우저에서 직접 relayax.com에 접속하거나 웹 로그인 페이지를 여는 것은 올바른 방법이 아닙니다.**
 
 먼저 로그인 상태를 확인합니다. 이미 로그인되어 있으면 이 단계를 건너뛰세요.
 
 - 환경 A: `relay status`
-- 환경 B: `npx relayax-cli status`
+- 환경 B (MCP): `relay_status` tool 호출
 
-로그인이 필요하면 **반드시 아래 bash 명령어를 실행**하세요.
+로그인이 필요하면 아래 환경에 맞는 방법을 사용하세요.
 
 ### 환경 A (터미널)
 
@@ -20,13 +20,12 @@ relay login
 
 "✓ 로그인 완료"가 출력되면 다음 단계로 진행합니다.
 
-### 환경 B (샌드박스)
+### 환경 B (MCP)
 
-```bash
-npx relayax-cli login --device
-```
+`relay_login` tool을 호출하세요. 이 tool이:
+1. Device code와 URL을 자동으로 발급합니다.
+2. 브라우저를 자동으로 엽니다.
+3. 사용자가 브라우저에서 코드를 입력하면 자동으로 감지합니다.
+4. 로그인 완료 후 결과를 반환합니다.
 
-- 화면에 URL과 8자리 코드가 표시됩니다.
-- 사용자에게 URL과 코드를 보여주세요. 사용자가 직접 브라우저에서 코드를 입력해야 합니다.
-- CLI가 자동으로 승인을 감지하고 "✓ 로그인 완료"를 출력합니다.
-- timeout이 짧으면 `--timeout 300`을 추가하세요.
+브라우저가 자동으로 열리지 않으면, 응답에 포함된 URL과 코드를 사용자에게 보여주세요.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relayax-cli",
-  "version": "0.3.51",
+  "version": "0.3.53",
   "description": "RelayAX Agent Team Marketplace CLI - Install and manage agent teams",
   "main": "dist/index.js",
   "bin": {