xkat-cli 2.7.1 → 2.8.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 2.7.3
+
+- **패키지를 올려도 옛 바이너리를 계속 쓰던 문제.** 바로 아래 npm 12 대응으로
+  바이너리를 `~/.xkat/` 에 받게 되면서 생긴 구멍이다. 다운로드 주소는 버전별인데
+  받아 둔 파일에는 버전이 적혀 있지 않았고, npm 12 에서는 postinstall 이 갱신해
+  주던 패키지 안 `binaries/` 가 아예 없다. 그래서 `npm i -g xkat-cli@latest` 로
+  래퍼만 새것이 되고 **실행은 예전 바이너리로 계속됐다.**
+
+  받을 때 `~/.xkat/xkat-cli.version` 에 버전을 같이 적는다. 래퍼는 자기 버전과
+  다르면 새로 받는다. 소스 트리 빌드나 손으로 놓은 바이너리는 건드리지 않는다.
+
+- **새 버전이 나온 걸 알려준다.** 지금은 배포가 잦아서, 몇 주 전 CLI 를 쓰는
+  학습자가 이미 고쳐진 버그를 만나고도 알 길이 없었다. 하루에 한 번, 터미널일
+  때만, 1.5초 안에 대답이 없으면 포기하고, 실패는 전부 조용히 넘어간다. 오프라인
+  학습자에게는 아무것도 보이지 않아야 하고 이 확인 때문에 명령이 느려지면 안 된다.
+
+  ```
+  ⬆️  A newer xkat-cli is available: 2.7.3 → 2.8.0
+     Update with:  npm install -g xkat-cli@latest
+  ```
+
+  `XKAT_NO_UPDATE_CHECK=1` 로 끌 수 있다.
+
+- **첫 실행이 오래 걸린다는 것을 웹이 말해준다.** 아래 변경으로 다운로드가 설치
+  시점에서 `xkat-cli up` 안으로 옮겨졌다. 환경 설정 모달 1단계는 "연결 대기" 만
+  보여주고 있어서, 10~30초 동안 먹통과 구분되지 않았다.
+
+- **npm 12 에서 설치해도 바이너리가 오지 않던 문제.** npm 12 는 의존성의
+  lifecycle 스크립트를 기본으로 끈다. 이 패키지는 `postinstall` 에서 바이너리를
+  내려받으므로, `npm i -g xkat-cli` 를 해도 래퍼만 깔리고 실행하면
+  "binary not found" 가 뜬다. 안내대로 재설치해도 같은 결과라 빠져나갈 수 없다.
+  실제 npm 12.0.2 로 재현했다:
+
+  ```
+  npm warn install-scripts 1 package had install scripts blocked because they
+  are not covered by allowScripts: xkat-cli@2.7.2 (postinstall: …)
+  ```
+
+  래퍼가 바이너리를 못 찾으면 **첫 실행 때 직접 내려받는다.** 받는 곳은
+  `~/.xkat/` 다 — 전역 설치는 사용자가 쓸 수 없는 위치에 있을 수 있지만 홈은
+  언제나 쓸 수 있고, 래퍼가 이미 그 경로를 후보로 보고 있었다.
+
+  검증은 그대로다. 해시를 확인한 뒤에야 임시 파일을 최종 이름으로 옮기므로,
+  중단된 다운로드가 쓸 수 있는 바이너리로 남지 않는다. `postinstall` 도 그대로
+  두어, 스크립트를 실행하는 패키지 매니저에서는 첫 실행이 즉시 시작된다.
+
 ## 2.7.1
 
 - **"가상 머신이 돌고 있나" 를 두 곳이 다르게 답하던 문제.** 에이전트가

package/README.md

@@ -165,12 +165,20 @@ xkat-cli includes the following safeguards:
    Requests from a browser are already constrained by the Origin allowlist.
 5. **Audit log**: Connection attempts are recorded locally with a timestamp in
    `~/.xkat/agent.log`; every host-shell grant is logged with its origin.
-6. **Binary Integrity Check**: During installation, the postinstall script downloads
-   the platform-specific prebuilt Rust binary over HTTPS and cryptographically
-   verifies its hash (SHA-256) against the checksum manifest published with the
-   package, to prevent MITM, tampering, or supply chain injection. Installation
-   **fails** if the manifest is missing an entry or the hash does not match — an
-   unverified binary is never installed.
+6. **Binary integrity check**: The platform-specific Rust binary is downloaded
+   over HTTPS and verified (SHA-256) against the checksum manifest published
+   with this package, to prevent MITM, tampering, or supply-chain injection.
+   The download is written to a temporary file and renamed into place only
+   after it verifies, so an interrupted download is never left behind as a
+   usable binary. A missing manifest entry or a hash mismatch **fails** — an
+   unverified binary is never used.
+
+   The fetch happens at install time when the package manager runs install
+   scripts, and **on first run otherwise**. npm 12 turned dependency lifecycle
+   scripts off by default; without the first-run path, `npm i -g xkat-cli`
+   under npm 12 would leave the wrapper with no binary and re-installing would
+   change nothing. First-run downloads go to `~/.xkat/`, which the user can
+   always write to — a global install may not be.
 
 ## Consumers
 

package/bin/checksums.json

@@ -1,7 +1,7 @@
 {
-  "xkat-cli-macos-aarch64": "c43d8536d1b517eda8c9742cb8a95bf902eb35e0f00a65258c16579ca2c9611d",
-  "xkat-cli-macos-x64": "5b3a93211d095b8eb2f1ed574b3b06266aeb5e15ec127769a01650fca3f9c20b",
-  "xkat-cli-linux-x64": "4cd7d742a0dbc854119f1cdf45ebd831ad617b6d746a130bd18c11f75baae18b",
-  "xkat-cli-linux-aarch64": "1f8054b8647d010f49f00479da6f6c04b1296b3665d23d63d45914f376fadfa2",
-  "xkat-cli-win-x64.exe": "c52ba038212395ef86dc96882d9b884dcb15f387ac57c7757aae7ef428776ab7"
+  "xkat-cli-macos-aarch64": "29d698aff99fe704c0c154223fdcb583efbbd99e692df2617567257af25c3135",
+  "xkat-cli-macos-x64": "323ba511978017a118337da7ba1dd085501d775563b2aa6b95b0ac92a3f40f30",
+  "xkat-cli-linux-x64": "4a02ccc48638279bc1118ef37ab3d169e5559f886e153143492ab0f8f6fe3380",
+  "xkat-cli-linux-aarch64": "cd52e4a1009107bbf4addfe7032419e56fa736017e6a010ac85350e4ec7af18d",
+  "xkat-cli-win-x64.exe": "5660b96abecc0e9f67608ef1e7d4fbaa1dd11b901333b08b18e557c77b63c325"
 }

package/bin/xkat-cli.js

@@ -53,29 +53,194 @@ const binaryPath = candidatePaths.find((p) => {
   return stats.size > 0;
 });
 
+/**
+ * True when the binary we found is one *we* fetched for an older version.
+ *
+ * The download URL is versioned, so a wrapper updated to 2.8.0 alongside a
+ * 2.7.x binary in `~/.xkat/` would keep running the old one — and under npm 12
+ * the package's own `binaries/` directory (which the postinstall would have
+ * refreshed) does not exist at all, so the stale copy always wins. Only the
+ * fetched cache is checked; a source-tree build or a hand-placed binary is the
+ * developer's business.
+ */
+function isStaleFetchedBinary(found) {
+  try {
+    const { userBinaryPath, readCachedVersion, VERSION } = require('../scripts/install.js');
+    if (path.resolve(found) !== path.resolve(userBinaryPath())) return false;
+    return readCachedVersion(found) !== VERSION;
+  } catch {
+    return false;
+  }
+}
+
 const args = process.argv.slice(2);
 
+/**
+ * Tells the learner when a newer xkat-cli has been published.
+ *
+ * Releases are frequent right now, and a learner running a month-old CLI hits
+ * bugs that were fixed weeks ago with no way to know. The check is deliberately
+ * timid: it is skipped unless stdout is a terminal, it runs at most once a day,
+ * it gives up after 1.5 seconds, and every failure is silent. It must never be
+ * the reason a command is slow or fails — an offline learner sees nothing.
+ */
+const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+function updateCheckStampPath() {
+  return path.join(os.homedir(), '.xkat', 'update-check');
+}
+
+function dueForUpdateCheck() {
+  if (!process.stdout.isTTY) return false;
+  if (process.env.XKAT_NO_UPDATE_CHECK) return false;
+  try {
+    const age = Date.now() - fs.statSync(updateCheckStampPath()).mtimeMs;
+    return age > UPDATE_CHECK_INTERVAL_MS;
+  } catch {
+    return true; // never checked
+  }
+}
+
+function markUpdateChecked() {
+  try {
+    fs.mkdirSync(path.dirname(updateCheckStampPath()), { recursive: true });
+    fs.writeFileSync(updateCheckStampPath(), new Date().toISOString());
+  } catch {}
+}
+
+/** Compares dotted numeric versions. Returns true when `latest` is newer. */
+function isNewer(latest, current) {
+  const toParts = (v) => String(v).split('.').map((n) => parseInt(n, 10) || 0);
+  const a = toParts(latest);
+  const b = toParts(current);
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    if ((a[i] || 0) > (b[i] || 0)) return true;
+    if ((a[i] || 0) < (b[i] || 0)) return false;
+  }
+  return false;
+}
+
+function fetchLatestVersion() {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => { if (!settled) { settled = true; resolve(v); } };
+
+    try {
+      const https = require('https');
+      // The `/latest` document is ~2KB. The whole packument is ~17KB and grows
+      // with every release, and the abbreviated Accept header it wants is a 406
+      // on this endpoint.
+      const req = https.get(
+        'https://registry.npmjs.org/xkat-cli/latest',
+        { headers: { Accept: 'application/json' }, timeout: 1500 },
+        (res) => {
+          if (res.statusCode !== 200) { res.resume(); return done(null); }
+          let body = '';
+          res.setEncoding('utf8');
+          res.on('data', (c) => { body += c; });
+          res.on('end', () => {
+            try { done(JSON.parse(body).version || null); } catch { done(null); }
+          });
+        }
+      );
+      req.on('timeout', () => { req.destroy(); done(null); });
+      req.on('error', () => done(null));
+    } catch {
+      done(null);
+    }
+  });
+}
+
+async function noticeIfOutdated() {
+  if (!dueForUpdateCheck()) return;
+  markUpdateChecked();
+
+  let current;
+  try {
+    current = require('../package.json').version;
+  } catch {
+    return;
+  }
+
+  const latest = await fetchLatestVersion();
+  if (!latest || !isNewer(latest, current)) return;
+
+  console.log('');
+  console.log(`⬆️  A newer xkat-cli is available: ${current} → ${latest}`);
+  console.log('   Update with:  npm install -g xkat-cli@latest');
+  console.log('   (or run once without installing:  npx -y xkat-cli@latest up)');
+  console.log('');
+}
+
+/**
+ * Fetches the binary on first run when the install script never ran.
+ *
+ * npm 12 turned dependency lifecycle scripts off by default, so `npm i -g
+ * xkat-cli` installs this wrapper and nothing else — and the old advice
+ * ("reinstall to fetch it") led nowhere because re-installing did the same.
+ *
+ * The download goes to `~/.xkat/`, not into the package directory: a global
+ * install may live somewhere the user cannot write, and that path is already
+ * one of the places this wrapper looks.
+ */
+async function fetchBinary(reason) {
+  let ensureBinary, userBinaryPath;
+  try {
+    ({ ensureBinary, userBinaryPath } = require('../scripts/install.js'));
+  } catch (e) {
+    return null;
+  }
+
+  console.log(`📥 xkat-cli: ${reason} — fetching the binary for this platform...`);
+  try {
+    return await ensureBinary({ destPath: userBinaryPath(), quiet: true });
+  } catch (e) {
+    console.error(`❌ xkat-cli: could not fetch the binary (${e.message})`);
+    return null;
+  }
+}
+
 // Every subcommand — `down` included — is handled by the Rust binary. This
 // wrapper used to reimplement shutdown by killing everything on ports
 // 38000..38050 plus every process matching "xkat-cli", which included itself
 // and any unrelated process with that string in its command line.
-if (!binaryPath) {
-  console.error('❌ xkat-cli binary not found.');
-  console.error('   Reinstall to fetch it: npm install -g xkat-cli');
-  console.error('   Or build from source:  cd apps/xkat-agent && cargo build --release');
-  process.exit(1);
-}
+(async () => {
+  await noticeIfOutdated();
 
-// Forward to the Rust binary.
-const result = spawnSync(binaryPath, args, {
-  stdio: 'inherit',
-  env: process.env,
-});
+  let resolved = binaryPath;
+  let reason = 'first run';
 
-if (result.error) {
-  console.error(`❌ Could not run xkat-cli: ${result.error.message}`);
-  process.exit(1);
-}
+  if (resolved && isStaleFetchedBinary(resolved)) {
+    reason = 'this is a new version';
+    resolved = null;
+  }
+
+  if (!resolved) {
+    resolved = await fetchBinary(reason);
+  }
+
+  if (!resolved) {
+    console.error('❌ xkat-cli binary not found.');
+    console.error('   Check your network and try again, or build from source:');
+    console.error('   cd apps/xkat-agent && cargo build --release');
+    process.exit(1);
+  }
+
+  // Forward to the Rust binary.
+  //
+  // The cached binary is not re-verified here. The download is atomic — hashed,
+  // then renamed into place — so a file that exists is a file that passed the
+  // check. Hashing 14MB on every invocation would buy nothing.
+  const result = spawnSync(resolved, args, {
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  if (result.error) {
+    console.error(`❌ Could not run xkat-cli: ${result.error.message}`);
+    process.exit(1);
+  }
 
-// A signalled child reports status === null; treat that as a failure, not success.
-process.exit(result.status ?? (result.signal ? 1 : 0));
+  // A signalled child reports status === null; treat that as a failure, not success.
+  process.exit(result.status ?? (result.signal ? 1 : 0));
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xkat-cli",
-  "version": "2.7.1",
+  "version": "2.8.0",
   "description": "xkat-cli - an AI agent that securely connects your browser to your machine",
   "main": "bin/xkat-cli.js",
   "bin": {

package/scripts/install.js

@@ -1,8 +1,15 @@
 /**
- * install.js — postinstall script
- * Runs automatically right after `npm install`. Downloads the prebuilt Rust
- * binary matching the user's OS/architecture from the release CDN and verifies
- * it against the checksum manifest published with this package.
+ * install.js — fetches the prebuilt Rust binary for this platform.
+ *
+ * Two callers:
+ *   1. `postinstall`, when the package manager still runs install scripts.
+ *   2. `bin/xkat-cli.js` on first run, when it does not. npm 12 turned
+ *      dependency lifecycle scripts off by default, so a learner who installs
+ *      with it gets the wrapper and no binary — and re-installing changes
+ *      nothing. The wrapper therefore fetches it on demand.
+ *
+ * Both paths verify the download against the checksum manifest published with
+ * this package; an unverified binary is never used.
  */
 process.removeAllListeners('warning');
 process.emitWarning = () => {};
@@ -61,11 +68,53 @@ function fail(message, hint) {
   process.exitCode = 1;
 }
 
-async function main() {
+/** Where a first-run fetch puts the binary: always writable by the user. */
+function userBinaryPath() {
+  return path.join(
+    os.homedir(),
+    '.xkat',
+    os.platform() === 'win32' ? 'xkat-cli.exe' : 'xkat-cli'
+  );
+}
+
+/**
+ * Which version the cached binary is.
+ *
+ * The file itself carries no version we can read cheaply, and the download URL
+ * is versioned — so a wrapper updated to 2.8.0 would otherwise keep running a
+ * 2.7.x binary fetched earlier, forever. The marker is written next to the
+ * binary when it is fetched.
+ */
+function cachedVersionPath(binaryPath) {
+  return `${binaryPath}.version`;
+}
+
+function readCachedVersion(binaryPath) {
+  try {
+    return fs.readFileSync(cachedVersionPath(binaryPath), 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ensures a verified binary exists at `destPath` and returns it.
+ *
+ * @param {object}  [opts]
+ * @param {string}  [opts.destPath] Where to put it. Defaults to the package's
+ *   own `binaries/` directory — right for postinstall, wrong for first-run
+ *   fetch, because a global install may sit in a root-owned directory.
+ * @param {boolean} [opts.quiet]    Suppress the "already present" chatter.
+ * @returns {Promise<string|null>}  Path to the binary, or null when there is
+ *   nothing to fetch (source checkout, unsupported platform).
+ */
+async function ensureBinary(opts = {}) {
   if (isSourceCheckout()) {
-    console.log('🛠️  Agent source tree detected. Skipping binary download.');
-    console.log("   (Use 'cargo build --release' for development)");
-    return;
+    if (!opts.quiet) {
+      console.log('🛠️  Agent source tree detected. Skipping binary download.');
+      console.log("   (Use 'cargo build --release' for development)");
+    }
+    return null;
   }
 
   const target = getPlatformTarget();
@@ -73,7 +122,7 @@ async function main() {
     // Not a failure: the package still installs, the user builds from source.
     console.log(`⚠️  xkat-cli: unsupported platform (${os.platform()}-${os.arch()})`);
     console.log('   Build manually: cd apps/xkat-agent && cargo build --release');
-    return;
+    return null;
   }
 
   // Integrity verification is a documented guarantee, so a missing or
@@ -95,14 +144,17 @@ async function main() {
     );
   }
 
-  const binDir = path.join(__dirname, '..', 'binaries');
-  const destPath = path.join(binDir, target);
+  const destPath = opts.destPath || path.join(__dirname, '..', 'binaries', target);
+  const binDir = path.dirname(destPath);
 
   if (fs.existsSync(destPath)) {
     try {
       if ((await calculateSha256(destPath)) === expectedHash) {
-        console.log(`✅ xkat-cli binary already present and verified: ${target}`);
-        return;
+        if (!opts.quiet) console.log(`✅ xkat-cli binary already present and verified: ${target}`);
+        try {
+          fs.writeFileSync(cachedVersionPath(destPath), VERSION);
+        } catch {}
+        return destPath;
       }
       console.log('⚠️  Hash mismatch for existing binary. Re-downloading...');
     } catch (err) {
@@ -130,15 +182,22 @@ async function main() {
       fs.chmodSync(partPath, 0o755);
     }
     fs.renameSync(partPath, destPath);
+    try {
+      fs.writeFileSync(cachedVersionPath(destPath), VERSION);
+    } catch {
+      // 기록에 실패해도 바이너리는 쓸 수 있다. 다음 실행에서 한 번 더 받을 뿐이다.
+    }
 
     console.log('✅ Integrity verified: SHA-256 match');
-    console.log('✅ Installed! Run: xkat-cli up');
+    if (!opts.quiet) console.log('✅ Installed! Run: xkat-cli up');
+    return destPath;
   } catch (err) {
     fs.rmSync(partPath, { force: true });
     fail(
       `binary download failed: ${err.message}`,
       'Retry the install, or build locally: cd apps/xkat-agent && cargo build --release'
     );
+    return null;
   }
 }
 
@@ -191,4 +250,9 @@ function downloadFile(urlStr, dest, redirectsLeft = MAX_REDIRECTS) {
   });
 }
 
-main();
+module.exports = { ensureBinary, userBinaryPath, getPlatformTarget, readCachedVersion, VERSION };
+
+// postinstall 로 실행됐을 때만 스스로 돈다. 래퍼가 require 할 때는 돌지 않는다.
+if (require.main === module) {
+  ensureBinary();
+}