xkat-cli 1.1.0 → 1.1.2

package/README.md

@@ -1,40 +1,65 @@
 # xKat (Local Terminal Bridge)
 
-xKat Agent는 브라우저 기반의 코딩 학습 플랫폼과 사용자의 로컬 환경을 안전하게 연결해주는 브릿지 도구입니다.
+xKat Agent is a bridge tool that securely connects a browser-based coding
+learning platform to your local environment.
 
-## 주요 기능
+## Features
 
-- **로컬 SSH 브릿지**: 브라우저의 웹 IDE 터미널을 로컬 셸에 직접 연결하여 실습 성능을 극대화합니다.
-    - **실시간 파일 동기화**: 로컬 작업 디렉토리의 파일 변경(VFS)을 감지하여 웹 대시보드와 즉시 동기화합니다.
-    - **보안 중심 설계**: 127.0.0.1 루프백 바인딩, Origin 검사, SSH 기반 인증을 통해 안전한 로컬 제어를 보장합니다.
+- **Zero-install local shell bridge**: Connects the web IDE terminal in your
+  browser directly to your local shell. A single `npx xkat up` spawns a native
+  shell (PTY) with your current user permissions — no extra install or setup.
+- **Real-time file sync**: Watches file changes (VFS) in your local working
+  directory and syncs them with the web dashboard instantly.
+- **Security-first design**: Binds to the 127.0.0.1 loopback and verifies the
+  request Origin to keep local control safe.
+- **(Optional) SSH mode**: If you provide credentials (user/password), it can
+  connect to a local SSH server instead. The default is the zero-install
+  direct shell.
 
-## 시작하기
+## Getting started
 
-NPM을 통해 별도의 설치 없이 즉시 실행할 수 있습니다.
+Run instantly via npm without a separate install:
 
 ```bash
 npx xkat up
 ```
 
-또는 전역 설치를 원할 경우:
+Or install globally:
 
 ```bash
-npm install -g xkat
+npm install -g xkat-cli
 xkat up
 ```
 
-## 시스템 요구 사항
+## System requirements
 
-- **OpenSSH Server**: 로컬 환경에 SSH 서버가 활성화되어 있어야 합니다.
-- **Node.js**: 16.x 이상의 버전이 필요합니다.
+- **Node.js**: 16.x or newer.
+- **OpenSSH Server (optional)**: Not needed for the default zero-install shell
+  mode. Only required when using the SSH credentials mode.
 
-## 보안 가이드라인
+## Security guidelines
 
-xKat Agent는 보안을 위해 다음과 같은 장치를 마련하고 있습니다:
-1. **Localhost Only**: 포트 10022는 오직 로컬호스트에서만 접근 가능합니다.
-2. **Origin Verification**: 공식 서비스 도메인에서 온 연결요청만 수락합니다.
-3. **Audit Log**: 모든 접속 시도와 파일 변경 이벤트는 타임스탬프와 함께 로컬로그에 기록됩니다.
+xKat Agent includes the following safeguards:
 
-## 라이선스
+1. **Localhost only**: Port 10022 is reachable only from localhost.
+2. **Origin verification**: Only connection requests from the official service
+   domains are accepted.
+3. **Audit log**: Every connection attempt and file-change event is recorded
+   locally with a timestamp.
+
+## Releasing (maintainers)
+
+See `docs/xkat-agent/deployment-pipeline.md` and
+`.github/workflows/release-agent.yml` for the release pipeline. Summary:
+
+```bash
+cd apps/xkat-agent
+npm version patch --no-git-tag-version
+git add package.json && git commit -m "chore(agent): release vX.Y.Z"
+git tag agent-v$(node -p "require('./package.json').version")
+git push origin main --tags
+```
+
+## License
 
 MIT License

package/bin/xkat-cli.js

@@ -2,8 +2,9 @@
 
 /**
  * xkat-cli.js
- * NPM에서 유저가 'xkat' 명령어를 입력하면 실행되는 경량 래퍼(Wrapper)입니다.
- * 유일한 역할: postinstall에서 다운받아둔 Rust 바이너리를 찾아서 실행권한을 넘기는 것.
+ * A lightweight wrapper invoked when the user runs the `xkat` command from npm.
+ * Its only job: locate the Rust binary downloaded during postinstall and hand
+ * over execution to it.
  */
 const { spawnSync } = require('child_process');
 const path = require('path');
@@ -38,11 +39,11 @@ 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');
+  console.error('   Try reinstalling: npm install -g xkat-cli');
   process.exit(1);
 }
 
-// Rust 바이너리에 모든 argv를 그대로 토스
+// Forward all argv straight to the Rust binary
 const result = spawnSync(binaryPath, process.argv.slice(2), {
   stdio: 'inherit',
   env: process.env,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xkat-cli",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "xKat Local Terminal Agent - Bridge between Web IDE and Local Shell",
   "main": "bin/xkat-cli.js",
   "bin": {
@@ -20,7 +20,6 @@
   },
   "keywords": [
     "xkat",
-    "codingkat",
     "terminal",
     "ssh",
     "bridge",

package/scripts/install.js

@@ -1,14 +1,16 @@
 /**
- * install.js — postinstall 스크립트
- * npm install 직후 자동 실행되며, 유저의 OS/아키텍처에 맞는
- * 미리 빌드된 Rust 바이너리를 GitHub Releases(또는 R2)에서 다운로드합니다.
+ * install.js — postinstall script
+ * Runs automatically right after `npm install`. Downloads the prebuilt Rust
+ * binary matching the user's OS/architecture from GitHub Releases (or R2).
  */
 const os = require('os');
 const fs = require('fs');
 const path = require('path');
 const https = require('https');
 
-const VERSION = '1.1.0';
+// Version is the single source of truth from package.json, so a release bump
+// (npm version patch) automatically points install at the matching R2 folder.
+const VERSION = require('../package.json').version;
 const BASE_URL = `https://dl.xkat.space/v${VERSION}`;
 
 function getPlatformTarget() {
@@ -30,23 +32,23 @@ 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');
+    console.log(`⚠️  xkat-agent: unsupported platform (${os.platform()}-${os.arch()})`);
+    console.log('   Build manually: cd apps/xkat-agent && cargo build --release');
     return;
   }
 
   const binDir = path.join(__dirname, '..', 'binaries');
   const destPath = path.join(binDir, target);
 
-  // 이미 다운로드 되어 있으면 스킵
+  // Skip if already downloaded
   if (fs.existsSync(destPath)) {
-    console.log(`✅ xkat-agent 바이너리가 이미 존재합니다: ${target}`);
+    console.log(`✅ xkat-agent binary already present: ${target}`);
     return;
   }
 
-  console.log(`📥 xkat-agent 다운로드 중... (${target})`);
+  console.log(`📥 Downloading xkat-agent... (${target})`);
 
-  // binaries 디렉토리 생성
+  // Create the binaries directory
   if (!fs.existsSync(binDir)) {
     fs.mkdirSync(binDir, { recursive: true });
   }
@@ -55,14 +57,14 @@ async function main() {
 
   try {
     await downloadFile(url, destPath);
-    // 실행 권한 부여 (Unix 환경에서만)
+    // Grant execute permission (Unix only)
     if (os.platform() !== 'win32') {
       fs.chmodSync(destPath, 0o755);
     }
-    console.log(`✅ 설치 완료! 실행: xkat up`);
+    console.log(`✅ Installed! Run: xkat up`);
   } catch (err) {
-    console.log(`⚠️  바이너리 다운로드 실패: ${err.message}`);
-    console.log('   로컬에서 직접 빌드하려면: cd apps/xkat-agent && cargo build --release');
+    console.log(`⚠️  Binary download failed: ${err.message}`);
+    console.log('   To build locally: cd apps/xkat-agent && cargo build --release');
   }
 }
 
@@ -70,7 +72,7 @@ function downloadFile(url, dest) {
   return new Promise((resolve, reject) => {
     const file = fs.createWriteStream(dest);
     https.get(url, (response) => {
-      // GitHub Releases는 302 리다이렉트를 씀
+      // GitHub Releases use 302 redirects
       if (response.statusCode === 302 || response.statusCode === 301) {
         https.get(response.headers.location, (redirected) => {
           redirected.pipe(file);