xkat-cli 1.1.0

package/README.md

@@ -0,0 +1,40 @@
+# xKat (Local Terminal Bridge)
+
+xKat Agent는 브라우저 기반의 코딩 학습 플랫폼과 사용자의 로컬 환경을 안전하게 연결해주는 브릿지 도구입니다.
+
+## 주요 기능
+
+- **로컬 SSH 브릿지**: 브라우저의 웹 IDE 터미널을 로컬 셸에 직접 연결하여 실습 성능을 극대화합니다.
+    - **실시간 파일 동기화**: 로컬 작업 디렉토리의 파일 변경(VFS)을 감지하여 웹 대시보드와 즉시 동기화합니다.
+    - **보안 중심 설계**: 127.0.0.1 루프백 바인딩, Origin 검사, SSH 기반 인증을 통해 안전한 로컬 제어를 보장합니다.
+
+## 시작하기
+
+NPM을 통해 별도의 설치 없이 즉시 실행할 수 있습니다.
+
+```bash
+npx xkat up
+```
+
+또는 전역 설치를 원할 경우:
+
+```bash
+npm install -g xkat
+xkat up
+```
+
+## 시스템 요구 사항
+
+- **OpenSSH Server**: 로컬 환경에 SSH 서버가 활성화되어 있어야 합니다.
+- **Node.js**: 16.x 이상의 버전이 필요합니다.
+
+## 보안 가이드라인
+
+xKat Agent는 보안을 위해 다음과 같은 장치를 마련하고 있습니다:
+1. **Localhost Only**: 포트 10022는 오직 로컬호스트에서만 접근 가능합니다.
+2. **Origin Verification**: 공식 서비스 도메인에서 온 연결요청만 수락합니다.
+3. **Audit Log**: 모든 접속 시도와 파일 변경 이벤트는 타임스탬프와 함께 로컬로그에 기록됩니다.
+
+## 라이선스
+
+MIT License

package/bin/xkat-cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+/**
+ * xkat-cli.js
+ * NPM에서 유저가 'xkat' 명령어를 입력하면 실행되는 경량 래퍼(Wrapper)입니다.
+ * 유일한 역할: postinstall에서 다운받아둔 Rust 바이너리를 찾아서 실행권한을 넘기는 것.
+ */
+const { spawnSync } = require('child_process');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+function getBinaryName() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  const map = {
+    'darwin-arm64':  'xkat-agent-macos-aarch64',
+    'darwin-x64':    'xkat-agent-macos-x64',
+    'linux-x64':     'xkat-agent-linux-x64',
+    'linux-arm64':   'xkat-agent-linux-aarch64',
+    'win32-x64':     'xkat-agent-win-x64.exe',
+  };
+
+  const key = `${platform}-${arch}`;
+  const binary = map[key];
+
+  if (!binary) {
+    console.error(`❌ Unsupported platform: ${key}`);
+    console.error('   Supported: macOS (arm64/x64), Linux (x64/arm64), Windows (x64)');
+    process.exit(1);
+  }
+
+  return binary;
+}
+
+const binaryPath = path.join(__dirname, '..', 'binaries', getBinaryName());
+
+if (!fs.existsSync(binaryPath)) {
+  console.error('❌ xkat-agent binary not found.');
+  console.error('   Try reinstalling: npm install -g xkat-agent');
+  process.exit(1);
+}
+
+// Rust 바이너리에 모든 argv를 그대로 토스
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+process.exit(result.status || 0);

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "xkat-cli",
+  "version": "1.1.0",
+  "description": "xKat Local Terminal Agent - Bridge between Web IDE and Local Shell",
+  "main": "bin/xkat-cli.js",
+  "bin": {
+    "xkat": "bin/xkat-cli.js"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node ./scripts/install.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/somilab/xkat-agent.git"
+  },
+  "keywords": [
+    "xkat",
+    "codingkat",
+    "terminal",
+    "ssh",
+    "bridge",
+    "agent"
+  ],
+  "author": "SomiLab <contact@somilab.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/somilab/xkat-agent/issues"
+  },
+  "homepage": "https://xkat.space"
+}

package/scripts/install.js

@@ -0,0 +1,89 @@
+/**
+ * install.js — postinstall 스크립트
+ * npm install 직후 자동 실행되며, 유저의 OS/아키텍처에 맞는
+ * 미리 빌드된 Rust 바이너리를 GitHub Releases(또는 R2)에서 다운로드합니다.
+ */
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+const VERSION = '1.1.0';
+const BASE_URL = `https://dl.xkat.space/v${VERSION}`;
+
+function getPlatformTarget() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  const map = {
+    'darwin-arm64':  'xkat-agent-macos-aarch64',
+    'darwin-x64':    'xkat-agent-macos-x64',
+    'linux-x64':     'xkat-agent-linux-x64',
+    'linux-arm64':   'xkat-agent-linux-aarch64',
+    'win32-x64':     'xkat-agent-win-x64.exe',
+  };
+
+  return map[`${platform}-${arch}`] || null;
+}
+
+async function main() {
+  const target = getPlatformTarget();
+
+  if (!target) {
+    console.log(`⚠️  xkat-agent: 지원하지 않는 플랫폼입니다 (${os.platform()}-${os.arch()})`);
+    console.log('   수동 빌드: cd apps/xkat-agent && cargo build --release');
+    return;
+  }
+
+  const binDir = path.join(__dirname, '..', 'binaries');
+  const destPath = path.join(binDir, target);
+
+  // 이미 다운로드 되어 있으면 스킵
+  if (fs.existsSync(destPath)) {
+    console.log(`✅ xkat-agent 바이너리가 이미 존재합니다: ${target}`);
+    return;
+  }
+
+  console.log(`📥 xkat-agent 다운로드 중... (${target})`);
+
+  // binaries 디렉토리 생성
+  if (!fs.existsSync(binDir)) {
+    fs.mkdirSync(binDir, { recursive: true });
+  }
+
+  const url = `${BASE_URL}/${target}`;
+
+  try {
+    await downloadFile(url, destPath);
+    // 실행 권한 부여 (Unix 환경에서만)
+    if (os.platform() !== 'win32') {
+      fs.chmodSync(destPath, 0o755);
+    }
+    console.log(`✅ 설치 완료! 실행: xkat up`);
+  } catch (err) {
+    console.log(`⚠️  바이너리 다운로드 실패: ${err.message}`);
+    console.log('   로컬에서 직접 빌드하려면: cd apps/xkat-agent && cargo build --release');
+  }
+}
+
+function downloadFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(dest);
+    https.get(url, (response) => {
+      // GitHub Releases는 302 리다이렉트를 씀
+      if (response.statusCode === 302 || response.statusCode === 301) {
+        https.get(response.headers.location, (redirected) => {
+          redirected.pipe(file);
+          file.on('finish', () => { file.close(); resolve(); });
+        }).on('error', reject);
+      } else if (response.statusCode === 200) {
+        response.pipe(file);
+        file.on('finish', () => { file.close(); resolve(); });
+      } else {
+        reject(new Error(`HTTP ${response.statusCode}`));
+      }
+    }).on('error', reject);
+  });
+}
+
+main();