relayax-cli 0.2.39 → 0.2.41

package/dist/commands/access.d.ts

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

package/dist/commands/access.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAccess = registerAccess;
+const commander_1 = require("commander");
+const config_js_1 = require("../lib/config.js");
+async function claimAccess(slug, code) {
+    const token = await (0, config_js_1.getValidToken)();
+    if (!token) {
+        throw new Error('LOGIN_REQUIRED');
+    }
+    const res = await fetch(`${config_js_1.API_URL}/api/teams/${slug}/claim-access`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ code }),
+        signal: AbortSignal.timeout(10000),
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        const errCode = body.error ?? String(res.status);
+        switch (errCode) {
+            case 'INVALID_LINK':
+                throw new Error('초대 링크가 유효하지 않거나 만료되었습니다.');
+            case 'NOT_FOUND':
+                throw new Error('팀을 찾을 수 없습니다.');
+            case 'UNAUTHORIZED':
+                throw new Error('LOGIN_REQUIRED');
+            default:
+                throw new Error(body.message ?? `접근 권한 요청 실패 (${res.status})`);
+        }
+    }
+    return body;
+}
+function registerAccess(program) {
+    program
+        .command('access <slug>')
+        .description('초대 코드로 팀에 접근 권한을 얻고 바로 설치합니다')
+        .requiredOption('--code <code>', '팀 초대 코드')
+        .action(async (slug, opts) => {
+        const json = program.opts().json ?? false;
+        try {
+            const result = await claimAccess(slug, opts.code);
+            if (!result.success || !result.team) {
+                throw new Error('서버 응답이 올바르지 않습니다.');
+            }
+            const teamSlug = result.team.slug;
+            if (json) {
+                console.log(JSON.stringify({ status: 'ok', team: result.team }));
+            }
+            else {
+                console.log(`\x1b[32m접근 권한이 부여되었습니다: ${result.team.name}\x1b[0m`);
+                console.log(`\x1b[33m팀을 설치합니다: relay install ${teamSlug}\x1b[0m\n`);
+            }
+            // Automatically install the team
+            const { registerInstall } = await import('./install.js');
+            const subProgram = new commander_1.Command();
+            subProgram.option('--json', '구조화된 JSON 출력');
+            if (json)
+                subProgram.setOptionValue('json', true);
+            registerInstall(subProgram);
+            await subProgram.parseAsync(['node', 'relay', 'install', teamSlug]);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (message === 'LOGIN_REQUIRED') {
+                if (json) {
+                    console.error(JSON.stringify({
+                        error: 'LOGIN_REQUIRED',
+                        message: '로그인이 필요합니다. relay login을 먼저 실행하세요.',
+                        fix: 'relay login 실행 후 재시도하세요.',
+                    }));
+                }
+                else {
+                    console.error('\x1b[31m오류: 로그인이 필요합니다.\x1b[0m');
+                    console.error('  relay login을 먼저 실행하세요.');
+                }
+                process.exit(1);
+            }
+            if (json) {
+                console.error(JSON.stringify({ error: 'ACCESS_FAILED', message, fix: '접근 링크 코드를 확인하거나 팀 제작자에게 문의하세요.' }));
+            }
+            else {
+                console.error(`\x1b[31m오류: ${message}\x1b[0m`);
+            }
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/create.js

@@ -24,7 +24,10 @@ function registerCreate(program) {
     program
         .command('create <name>')
         .description('새 에이전트 팀 프로젝트를 생성합니다')
-        .action(async (name) => {
+        .option('--description <desc>', '팀 설명')
+        .option('--tags <tags>', '태그 (쉼표 구분)')
+        .option('--visibility <visibility>', '공개 범위 (public, gated, private)')
+        .action(async (name, opts) => {
         const json = program.opts().json ?? false;
         const projectPath = process.cwd();
         const relayDir = path_1.default.join(projectPath, '.relay');
@@ -33,7 +36,7 @@ function registerCreate(program) {
         // 1. .relay/relay.yaml 이미 존재하면 에러
         if (fs_1.default.existsSync(relayYamlPath)) {
             if (json) {
-                console.error(JSON.stringify({ error: 'ALREADY_EXISTS', message: '.relay/relay.yaml이 이미 존재합니다.' }));
+                console.error(JSON.stringify({ error: 'ALREADY_EXISTS', message: '.relay/relay.yaml이 이미 존재합니다.', fix: '기존 .relay/relay.yaml을 확인하세요. 새로 시작하려면 삭제 후 재시도.' }));
             }
             else {
                 console.error('.relay/relay.yaml이 이미 존재합니다. 기존 팀 프로젝트에서는 `relay init`을 사용하세요.');
@@ -42,28 +45,73 @@ function registerCreate(program) {
         }
         // 2. 메타데이터 수집
         const defaultSlug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
-        let description = '';
-        let tags = [];
-        let visibility = 'public';
-        if (isTTY) {
+        let description = opts.description ?? '';
+        let tags = opts.tags ? opts.tags.split(',').map((t) => t.trim()).filter(Boolean) : [];
+        let visibility = opts.visibility ?? 'public';
+        if (json) {
+            // --json 모드: 필수 값 부족 시 에러 반환 (프롬프트 없음)
+            if (!opts.description) {
+                console.error(JSON.stringify({
+                    error: 'MISSING_FIELD',
+                    message: '팀 설명이 필요합니다.',
+                    fix: `relay create ${name} --description <설명> --json`,
+                    field: 'description',
+                }));
+                process.exit(1);
+            }
+            if (!opts.visibility) {
+                console.error(JSON.stringify({
+                    error: 'MISSING_VISIBILITY',
+                    message: '공개 범위를 선택하세요.',
+                    fix: `relay create ${name} --description "${description}" --visibility <visibility> --json`,
+                    options: [
+                        { value: 'public', label: '공개 — 누구나 설치' },
+                        { value: 'gated', label: '링크 공유 — 접근 링크가 있는 사람만' },
+                        { value: 'private', label: '비공개 — Space 멤버만' },
+                    ],
+                }));
+                process.exit(1);
+            }
+            if (!['public', 'gated', 'private'].includes(opts.visibility)) {
+                console.error(JSON.stringify({
+                    error: 'INVALID_FIELD',
+                    message: `유효하지 않은 visibility 값: ${opts.visibility}`,
+                    fix: `visibility는 public, gated, private 중 하나여야 합니다.`,
+                    options: [
+                        { value: 'public', label: '공개' },
+                        { value: 'gated', label: '링크 공유' },
+                        { value: 'private', label: '비공개' },
+                    ],
+                }));
+                process.exit(1);
+            }
+        }
+        else if (isTTY) {
             const { input: promptInput, select: promptSelect } = await import('@inquirer/prompts');
             console.log(`\n  \x1b[33m⚡\x1b[0m \x1b[1mrelay create\x1b[0m — 새 팀 프로젝트\n`);
-            description = await promptInput({
-                message: '팀 설명:',
-                validate: (v) => v.trim().length > 0 ? true : '설명을 입력해주세요.',
-            });
-            const tagsRaw = await promptInput({
-                message: '태그 (쉼표로 구분, 선택):',
-                default: '',
-            });
-            tags = tagsRaw.split(',').map((t) => t.trim()).filter(Boolean);
-            visibility = await promptSelect({
-                message: '공개 범위:',
-                choices: [
-                    { name: '공개', value: 'public' },
-                    { name: '비공개 (Space 멤버만)', value: 'private' },
-                ],
-            });
+            if (!description) {
+                description = await promptInput({
+                    message: '팀 설명:',
+                    validate: (v) => v.trim().length > 0 ? true : '설명을 입력해주세요.',
+                });
+            }
+            if (!opts.tags) {
+                const tagsRaw = await promptInput({
+                    message: '태그 (쉼표로 구분, 선택):',
+                    default: '',
+                });
+                tags = tagsRaw.split(',').map((t) => t.trim()).filter(Boolean);
+            }
+            if (!opts.visibility) {
+                visibility = await promptSelect({
+                    message: '공개 범위:',
+                    choices: [
+                        { name: '공개', value: 'public' },
+                        { name: '링크 공유 (접근 링크 필요)', value: 'gated' },
+                        { name: '비공개 (Space 멤버만)', value: 'private' },
+                    ],
+                });
+            }
         }
         // 3. .relay/relay.yaml 생성
         fs_1.default.mkdirSync(relayDir, { recursive: true });

package/dist/commands/follow.js

@@ -15,7 +15,7 @@ function registerFollow(program) {
         if (!token) {
             const msg = '로그인이 필요합니다. `relay login`을 먼저 실행하세요.';
             if (json) {
-                console.log(JSON.stringify({ error: 'NO_TOKEN', message: msg }));
+                console.log(JSON.stringify({ error: 'NO_TOKEN', message: msg, fix: 'relay login 실행 후 재시도하세요.' }));
             }
             else {
                 console.error(msg);
@@ -34,7 +34,7 @@ function registerFollow(program) {
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             if (json) {
-                console.log(JSON.stringify({ error: 'FOLLOW_FAILED', message }));
+                console.log(JSON.stringify({ error: 'FOLLOW_FAILED', message, fix: 'username을 확인하거나 잠시 후 재시도하세요.' }));
             }
             else {
                 console.error(`팔로우 실패: ${message}`);

package/dist/commands/init.js

@@ -121,16 +121,31 @@ function registerInit(program) {
     program
         .command('init')
         .description('에이전트 CLI에 relay 슬래시 커맨드를 설치합니다')
-        .option('--tools <tools>', '설치할 에이전트 CLI 지정 (all 또는 쉼표 구분)')
+        .option('--tools <tools>', '설치할 에이전트 CLI 지정 (쉼표 구분)')
+        .option('--all', '감지된 모든 에이전트 CLI에 설치')
         .option('--auto', '대화형 프롬프트 없이 자동으로 모든 감지된 CLI에 설치')
         .action(async (opts) => {
         const json = program.opts().json ?? false;
-        // auto mode: --auto flag, --json flag, or stdin is not a TTY
-        const autoMode = opts.auto === true || json || !process.stdin.isTTY;
+        // auto mode: --auto flag, --all flag, or stdin is not a TTY (but NOT --json alone)
+        const autoMode = opts.auto === true || opts.all === true || !process.stdin.isTTY;
         const projectPath = process.cwd();
         const detected = (0, ai_tools_js_1.detectAgentCLIs)(projectPath);
         const detectedIds = new Set(detected.map((t) => t.value));
         const isBuilder = isTeamProject(projectPath);
+        // ── 0. --json 모드에서 --tools/--all 없으면 MISSING_TOOLS 에러 ──
+        if (json && !opts.tools && !opts.all && !opts.auto) {
+            const detectedOptions = detected.map((t) => ({ value: t.value, label: t.name }));
+            if (detectedOptions.length === 0) {
+                detectedOptions.push(...ai_tools_js_1.AI_TOOLS.slice(0, 5).map((t) => ({ value: t.value, label: t.name })));
+            }
+            console.error(JSON.stringify({
+                error: 'MISSING_TOOLS',
+                message: '설치할 에이전트 CLI를 선택하세요.',
+                fix: `relay init --tools <도구1,도구2> --json 또는 relay init --all --json`,
+                options: detectedOptions,
+            }));
+            process.exit(1);
+        }
         // ── 1. 글로벌 User 커맨드 설치 ──
         let globalStatus = 'already';
         let globalTools = [];

package/dist/commands/install.js

@@ -15,18 +15,21 @@ const preamble_js_1 = require("../lib/preamble.js");
 const join_js_1 = require("./join.js");
 const init_js_1 = require("./init.js");
 /**
- * slugInput이 "@spaces/{spaceSlug}/{teamSlug}" 형식이면 파싱해 반환.
+ * slugInput이 "@spaces/{spaceSlug}/{teamSlug}" 또는 "@{spaceSlug}/{teamSlug}" 형식이면 파싱해 반환.
  * 아니면 null.
  */
 function parseSpaceTarget(slugInput) {
-    const m = slugInput.match(/^@spaces\/([a-z0-9][a-z0-9-]*)\/([a-z0-9][a-z0-9-]*)$/);
-    if (!m)
-        return null;
-    return {
-        spaceSlug: m[1],
-        rawTeamSlug: m[2],
-        teamSlug: `@${m[1]}/${m[2]}`,
-    };
+    // @spaces/{spaceSlug}/{teamSlug} 형식 (기존)
+    const m1 = slugInput.match(/^@spaces\/([a-z0-9][a-z0-9-]*)\/([a-z0-9][a-z0-9-]*)$/);
+    if (m1) {
+        return { spaceSlug: m1[1], rawTeamSlug: m1[2], teamSlug: `@${m1[1]}/${m1[2]}` };
+    }
+    // @{spaceSlug}/{teamSlug} 형식 (신규)
+    const m2 = slugInput.match(/^@([a-z0-9][a-z0-9-]*)\/([a-z0-9][a-z0-9-]*)$/);
+    if (m2) {
+        return { spaceSlug: m2[1], rawTeamSlug: m2[2], teamSlug: `@${m2[1]}/${m2[2]}` };
+    }
+    return null;
 }
 function registerInstall(program) {
     program
@@ -69,20 +72,29 @@ function registerInstall(program) {
             let team;
             let slug;
             let parsed;
+            // Whether the spaceTarget was matched via the ambiguous @{slug}/{team} pattern
+            // (i.e. NOT the explicit @spaces/... prefix). Used for 404 fallback below.
+            const isAmbiguousSpaceTarget = spaceTarget !== null && !slugInput.startsWith('@spaces/');
             if (spaceTarget) {
                 // Space 팀: POST /api/spaces/{spaceSlug}/teams/{teamSlug}/install
                 // This verifies membership, increments install count, and returns metadata.
+                let usedSpacePath = true;
                 try {
                     team = await (0, api_js_1.installSpaceTeam)(spaceTarget.spaceSlug, spaceTarget.rawTeamSlug);
                 }
                 catch (fetchErr) {
                     const fetchMsg = fetchErr instanceof Error ? fetchErr.message : String(fetchErr);
-                    if (fetchMsg.includes('403')) {
+                    if (fetchMsg.includes('404') && isAmbiguousSpaceTarget) {
+                        // Space not found — @{owner}/{team} is actually a normal registry slug, fall back
+                        usedSpacePath = false;
+                    }
+                    else if (fetchMsg.includes('403')) {
                         if (json) {
                             console.error(JSON.stringify({
                                 error: 'SPACE_ONLY',
                                 message: '이 팀은 Space 멤버만 설치 가능합니다.',
                                 spaceSlug: spaceTarget.spaceSlug,
+                                fix: `relay join ${spaceTarget.spaceSlug} --code <초대코드>로 Space에 가입한 후 재시도하세요.`,
                             }));
                         }
                         else {
@@ -91,11 +103,22 @@ function registerInstall(program) {
                         }
                         process.exit(1);
                     }
-                    throw fetchErr;
+                    else {
+                        throw fetchErr;
+                    }
+                }
+                if (!usedSpacePath) {
+                    // Fallback: treat as normal registry install
+                    parsed = await (0, slug_js_1.resolveSlug)(slugInput);
+                    slug = parsed.full;
+                    team = await (0, api_js_1.fetchTeamInfo)(slug);
+                }
+                else {
+                    // slug from server is "@spaces/{spaceSlug}/{teamSlug}" — derive local path parts
+                    // team is guaranteed assigned by installSpaceTeam above (usedSpacePath === true)
+                    parsed = { owner: spaceTarget.spaceSlug, name: spaceTarget.rawTeamSlug, full: team.slug };
+                    slug = team.slug;
                 }
-                // slug from server is "@spaces/{spaceSlug}/{teamSlug}" — derive local path parts
-                parsed = { owner: spaceTarget.spaceSlug, name: spaceTarget.rawTeamSlug, full: team.slug };
-                slug = team.slug;
             }
             else {
                 // Normal registry install
@@ -107,15 +130,44 @@ function registerInstall(program) {
                 catch (fetchErr) {
                     const fetchMsg = fetchErr instanceof Error ? fetchErr.message : String(fetchErr);
                     if (fetchMsg.includes('403')) {
-                        // Parse join_policy and membership_status from error body if available
+                        // Parse error body for join_policy, membership_status, visibility, purchase_info
                         let joinPolicy;
                         let membershipStatus;
+                        let errorVisibility;
+                        let purchaseInfo;
                         try {
                             const errBody = JSON.parse(fetchMsg.replace(/^.*?(\{)/, '{'));
                             joinPolicy = typeof errBody.join_policy === 'string' ? errBody.join_policy : undefined;
                             membershipStatus = typeof errBody.membership_status === 'string' ? errBody.membership_status : undefined;
+                            errorVisibility = typeof errBody.visibility === 'string' ? errBody.visibility : undefined;
+                            if (errBody.purchase_info && typeof errBody.purchase_info === 'object') {
+                                purchaseInfo = errBody.purchase_info;
+                            }
                         }
                         catch { /* ignore parse errors */ }
+                        // Gated team: show purchase info + relay access hint
+                        if (errorVisibility === 'gated' || purchaseInfo) {
+                            if (json) {
+                                console.error(JSON.stringify({
+                                    error: 'GATED_ACCESS_REQUIRED',
+                                    message: '이 팀은 접근 권한이 필요합니다.',
+                                    slug,
+                                    purchase_info: purchaseInfo ?? null,
+                                    fix: '접근 링크 코드가 있으면: relay access <slug> --code <코드>',
+                                }));
+                            }
+                            else {
+                                console.error('\x1b[31m🔒 이 팀은 접근 권한이 필요합니다.\x1b[0m');
+                                if (purchaseInfo?.message) {
+                                    console.error(`\n  \x1b[36m${purchaseInfo.message}\x1b[0m`);
+                                }
+                                if (purchaseInfo?.url) {
+                                    console.error(`  \x1b[36m${purchaseInfo.url}\x1b[0m`);
+                                }
+                                console.error(`\n\x1b[33m접근 링크 코드가 있으면: relay access ${slugInput} --code <코드>\x1b[0m`);
+                            }
+                            process.exit(1);
+                        }
                         if (joinPolicy === 'auto') {
                             // Auto-join the Space then retry install
                             if (!json) {
@@ -132,7 +184,7 @@ function registerInstall(program) {
                             catch (joinErr) {
                                 const joinMsg = joinErr instanceof Error ? joinErr.message : String(joinErr);
                                 if (json) {
-                                    console.error(JSON.stringify({ error: 'JOIN_FAILED', message: joinMsg, slug }));
+                                    console.error(JSON.stringify({ error: 'JOIN_FAILED', message: joinMsg, slug, fix: 'Space slug와 초대 코드를 확인 후 재시도하세요.' }));
                                 }
                                 else {
                                     console.error(`\x1b[31mSpace 가입 실패: ${joinMsg}\x1b[0m`);
@@ -145,9 +197,10 @@ function registerInstall(program) {
                             if (json) {
                                 console.error(JSON.stringify({
                                     error: 'APPROVAL_REQUIRED',
-                                    message: `가입 신청이 필요합니다. \`relay join @${spaceSlug}\`로 가입하세요.`,
+                                    message: `가입 신청이 필요합니다.`,
                                     slug,
                                     spaceSlug,
+                                    fix: `relay join @${spaceSlug} --code <초대코드>로 Space에 가입한 후 재시도하세요. 초대 코드는 Space 관리자에게 요청하세요.`,
                                 }));
                             }
                             else {
@@ -162,6 +215,7 @@ function registerInstall(program) {
                                     error: 'NO_ACCESS',
                                     message: '이 팀에 대한 접근 권한이 없습니다.',
                                     slug,
+                                    fix: '이 팀의 접근 링크 코드가 있으면 `relay access ' + slugInput + ' --code <코드>`로 접근 권한을 얻으세요. 없으면 팀 제작자에게 문의하세요.',
                                 }));
                             }
                             else {
@@ -175,6 +229,7 @@ function registerInstall(program) {
                                     error: 'SPACE_ONLY',
                                     message: '이 팀은 Space 멤버만 설치 가능합니다.',
                                     slug,
+                                    fix: 'Space 관리자에게 초대 코드를 요청한 후 `relay join <space-slug> --code <코드>`로 가입하세요.',
                                 }));
                             }
                             else {
@@ -189,6 +244,8 @@ function registerInstall(program) {
                     }
                 }
             }
+            if (!team)
+                throw new Error('팀 정보를 가져오지 못했습니다.');
             const teamDir = path_1.default.join(projectPath, '.relay', 'teams', parsed.owner, parsed.name);
             // 2. Visibility check + auto-login
             const visibility = team.visibility ?? 'public';
@@ -210,6 +267,7 @@ function registerInstall(program) {
                                 visibility,
                                 slug,
                                 message: '이 팀은 로그인이 필요합니다. relay login을 먼저 실행하세요.',
+                                fix: 'relay login 실행 후 재시도하세요.',
                             }));
                         }
                         else {
@@ -219,8 +277,30 @@ function registerInstall(program) {
                     }
                 }
             }
-            // 3. Download package
-            const tarPath = await (0, storage_js_1.downloadPackage)(team.package_url, tempDir);
+            // 3. Download package (retry once if signed URL expired)
+            let tarPath;
+            try {
+                tarPath = await (0, storage_js_1.downloadPackage)(team.package_url, tempDir);
+            }
+            catch (dlErr) {
+                const dlMsg = dlErr instanceof Error ? dlErr.message : String(dlErr);
+                if (dlMsg.includes('403') || dlMsg.includes('expired')) {
+                    // Signed URL expired — re-fetch team info for new URL and retry
+                    if (!json) {
+                        console.error('\x1b[33m⚙ 다운로드 URL 만료, 재시도 중...\x1b[0m');
+                    }
+                    if (spaceTarget) {
+                        team = await (0, api_js_1.installSpaceTeam)(spaceTarget.spaceSlug, spaceTarget.rawTeamSlug);
+                    }
+                    else {
+                        team = await (0, api_js_1.fetchTeamInfo)(slug);
+                    }
+                    tarPath = await (0, storage_js_1.downloadPackage)(team.package_url, tempDir);
+                }
+                else {
+                    throw dlErr;
+                }
+            }
             // 4. Extract to .relay/teams/<slug>/
             if (fs_1.default.existsSync(teamDir)) {
                 fs_1.default.rmSync(teamDir, { recursive: true, force: true });
@@ -326,7 +406,7 @@ function registerInstall(program) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            console.error(JSON.stringify({ error: 'INSTALL_FAILED', message }));
+            console.error(JSON.stringify({ error: 'INSTALL_FAILED', message, fix: message }));
             process.exit(1);
         }
         finally {

package/dist/commands/join.js

@@ -57,7 +57,7 @@ function registerJoin(program) {
                 console.error('\x1b[33m⚠ relay init이 실행되지 않았습니다. 먼저 relay init을 실행하세요.\x1b[0m');
             }
             else {
-                console.error(JSON.stringify({ error: 'NOT_INITIALIZED', message: 'relay init을 먼저 실행하세요.' }));
+                console.error(JSON.stringify({ error: 'NOT_INITIALIZED', message: 'relay init을 먼저 실행하세요.', fix: 'relay init 실행하세요.' }));
             }
             process.exit(1);
         }
@@ -92,7 +92,8 @@ function registerJoin(program) {
                                 const desc = t.description ? `  \x1b[90m— ${t.description}\x1b[0m` : '';
                                 console.log(`  \x1b[36m•\x1b[0m \x1b[1m${t.slug}\x1b[0m${desc}`);
                             }
-                            console.log(`\n\x1b[33m💡 설치: relay install @spaces/${slug}/<팀슬러그>\x1b[0m`);
+                            console.log(`\n\x1b[33m💡 전체 설치: relay install @spaces/${slug}/<팀슬러그>\x1b[0m`);
+                            console.log(`\x1b[33m💡 가이드 URL 공유: https://relayax.com/api/spaces/${slug}/guide.md\x1b[0m`);
                         }
                     }
                 }
@@ -117,6 +118,7 @@ function registerJoin(program) {
                     console.error(JSON.stringify({
                         error: 'LOGIN_REQUIRED',
                         message: '로그인이 필요합니다. relay login 을 먼저 실행하세요.',
+                        fix: 'relay login 실행 후 재시도하세요.',
                     }));
                 }
                 else {
@@ -126,7 +128,7 @@ function registerJoin(program) {
                 process.exit(1);
             }
             if (json) {
-                console.error(JSON.stringify({ error: 'JOIN_FAILED', message }));
+                console.error(JSON.stringify({ error: 'JOIN_FAILED', message, fix: 'Space slug와 초대 코드를 확인 후 재시도하세요.' }));
             }
             else {
                 console.error(`\x1b[31m오류: ${message}\x1b[0m`);

package/dist/commands/list.js

@@ -29,7 +29,7 @@ function registerList(program) {
             const token = await (0, config_js_1.getValidToken)();
             if (!token) {
                 if (json) {
-                    console.error(JSON.stringify({ error: 'LOGIN_REQUIRED', message: '로그인이 필요합니다. relay login을 먼저 실행하세요.' }));
+                    console.error(JSON.stringify({ error: 'LOGIN_REQUIRED', message: '로그인이 필요합니다. relay login을 먼저 실행하세요.', fix: 'relay login 실행 후 재시도하세요.' }));
                 }
                 else {
                     console.error('\x1b[31m오류: 로그인이 필요합니다.\x1b[0m');
@@ -59,7 +59,7 @@ function registerList(program) {
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
                 if (json) {
-                    console.error(JSON.stringify({ error: 'FETCH_FAILED', message }));
+                    console.error(JSON.stringify({ error: 'FETCH_FAILED', message, fix: '네트워크 연결을 확인하거나 잠시 후 재시도하세요.' }));
                 }
                 else {
                     console.error(`\x1b[31m오류: ${message}\x1b[0m`);

package/dist/commands/login.js

@@ -148,7 +148,7 @@ function registerLogin(program) {
             catch (err) {
                 const msg = err instanceof Error ? err.message : '로그인 실패';
                 if (json) {
-                    console.error(JSON.stringify({ error: 'LOGIN_FAILED', message: msg }));
+                    console.error(JSON.stringify({ error: 'LOGIN_FAILED', message: msg, fix: '브라우저에서 로그인을 완료하고 relay login을 재시도하세요.' }));
                 }
                 else {
                     console.error(`\x1b[31m오류: ${msg}\x1b[0m`);

package/dist/commands/package.d.ts

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