@haposoft/cafekit 0.11.11 → 0.12.0

package/bin/install.js

@@ -37,6 +37,7 @@ const { checkVersions } = require('./lib/version-check');
 const { ensureGitignore } = require('./phases/root-config');
 const { runPostInstall } = require('./phases/post-install');
 const { setupSkillDeps } = require('./phases/skills-setup');
+const { setupRtk } = require('./phases/setup-rtk');
 const { printSummary } = require('./phases/summary');
 
 /** Install a single platform: payload + runtime + metadata, under one spinner. */
@@ -91,6 +92,8 @@ Options:
   -u, --upgrade, -f, --force   Alias of --force-overwrite
   --with-skills-deps   Install skill dependencies (Python venv + pip, npm,
                        Chromium/Playwright). Otherwise prompted interactively.
+  --with-rtk           Install the rtk token-saver (binary + Claude Code hook).
+                       Otherwise prompted interactively.
   -y, --yes            Non-interactive: skip prompts, use defaults (CI)
   -h, --help           Show this help
   -v, --version        Print version
@@ -166,6 +169,7 @@ async function main() {
     ensureGitignore(ctx);
     await runPostInstall(ctx);
     await setupSkillDeps(ctx);
+    await setupRtk(ctx);
     printSummary(ctx);
 
     if (!ctx.dryRun) backup.prune(3);

package/bin/lib/context.js

@@ -185,7 +185,8 @@ function parseInstallerArgs(argv) {
     forceOverwrite: false,
     dryRun: false,
     yes: false,
-    withSkillsDeps: false
+    withSkillsDeps: false,
+    withRtk: false
   };
 
   for (let i = 2; i < argv.length; i++) {
@@ -199,6 +200,8 @@ function parseInstallerArgs(argv) {
       args.yes = true;
     } else if (arg === '--with-skills-deps') {
       args.withSkillsDeps = true;
+    } else if (arg === '--with-rtk') {
+      args.withRtk = true;
     } else if (arg === '--lang') {
       args.lang = argv[++i];
     } else if (arg.startsWith('--lang=')) {

package/bin/lib/i18n.js

@@ -59,6 +59,17 @@ const MESSAGES = {
     // Skills / deps setup
     skillDepsConfirm:      'Install skill dependencies? (Python venv, pip, npm, Chromium — takes a few minutes)',
     skillsSkipped:         'Skill dependencies skipped.\n  Run later: npx @haposoft/cafekit --with-skills-deps',
+
+    // rtk token-saver setup
+    rtkConfirm:            'Install the rtk token-saver? (compacts git/grep/ls/build/test output for Claude Code Bash commands)',
+    rtkInstalling:         'Installing rtk via {method}',
+    rtkInstalled:          'rtk installed',
+    rtkInstallFailed:      'Could not install rtk — skipping (non-fatal). Install manually later: https://github.com/rtk-ai/rtk',
+    rtkInitFailed:         'rtk init -g failed: {reason} — hook not registered (non-fatal)',
+    rtkNeedsJq:            'rtk hook needs jq to run. Install jq, then the hook activates automatically.',
+    rtkFailed:             'rtk setup error: {reason} — skipped (non-fatal)',
+    rtkSkipped:            'rtk token-saver skipped.\n  Run later: npx @haposoft/cafekit --with-rtk',
+    rtkSummary:            'rtk token-saver: hook registered for Claude Code Bash commands',
     venvCreating:          'Setting up Python environment',
     venvReady:             'Python environment ready',
     venvFailed:            'Could not create Python environment — check your Python 3 installation.',
@@ -165,6 +176,17 @@ const MESSAGES = {
 
     skillDepsConfirm:      'スキルの依存関係をインストールしますか？（Python venv、pip、npm、Chromium — 数分かかります）',
     skillsSkipped:         'スキルの依存関係をスキップしました。\n  後で実行: npx @haposoft/cafekit --with-skills-deps',
+
+    // rtk token-saver setup
+    rtkConfirm:            'rtk トークンセーバーをインストールしますか？（Claude Code の Bash コマンドの git/grep/ls/build/test 出力を圧縮します）',
+    rtkInstalling:         '{method} で rtk をインストール中',
+    rtkInstalled:          'rtk をインストールしました',
+    rtkInstallFailed:      'rtk をインストールできませんでした — スキップします（致命的ではありません）。後で手動でインストール: https://github.com/rtk-ai/rtk',
+    rtkInitFailed:         'rtk init -g が失敗しました: {reason} — フックは未登録です（致命的ではありません）',
+    rtkNeedsJq:            'rtk フックの実行には jq が必要です。jq をインストールするとフックが自動的に有効になります。',
+    rtkFailed:             'rtk セットアップエラー: {reason} — スキップしました（致命的ではありません）',
+    rtkSkipped:            'rtk トークンセーバーをスキップしました。\n  後で実行: npx @haposoft/cafekit --with-rtk',
+    rtkSummary:            'rtk トークンセーバー: Claude Code の Bash コマンド用にフックを登録しました',
     venvCreating:          'Python 環境を準備しています',
     venvReady:             'Python 環境の準備ができました',
     venvFailed:            'Python 環境を作成できませんでした — Python 3 のインストールを確認してください。',
@@ -268,6 +290,17 @@ const MESSAGES = {
 
     skillDepsConfirm:      'Cài dependencies cho skill ngay? (Python venv, pip, npm, Chromium — mất vài phút)',
     skillsSkipped:         'Đã bỏ qua dependencies skill.\n  Cài sau bằng lệnh: npx @haposoft/cafekit --with-skills-deps',
+
+    // rtk token-saver setup
+    rtkConfirm:            'Cài rtk token-saver? (rút gọn output git/grep/ls/build/test cho các lệnh Bash của Claude Code)',
+    rtkInstalling:         'Đang cài rtk qua {method}',
+    rtkInstalled:          'Đã cài rtk',
+    rtkInstallFailed:      'Không thể cài rtk — bỏ qua (không nghiêm trọng). Cài thủ công sau: https://github.com/rtk-ai/rtk',
+    rtkInitFailed:         'rtk init -g thất bại: {reason} — hook chưa được đăng ký (không nghiêm trọng)',
+    rtkNeedsJq:            'Hook của rtk cần jq để chạy. Cài jq thì hook sẽ tự kích hoạt.',
+    rtkFailed:             'Lỗi cài rtk: {reason} — đã bỏ qua (không nghiêm trọng)',
+    rtkSkipped:            'Đã bỏ qua rtk token-saver.\n  Cài sau bằng lệnh: npx @haposoft/cafekit --with-rtk',
+    rtkSummary:            'rtk token-saver: đã đăng ký hook cho các lệnh Bash của Claude Code',
     venvCreating:          'Đang thiết lập môi trường Python',
     venvReady:             'Môi trường Python đã sẵn sàng',
     venvFailed:            'Không thể tạo môi trường Python — hãy kiểm tra cài đặt Python 3.',

package/bin/lib/rtk-run.js

@@ -0,0 +1,28 @@
+/**
+ * Local captured-spawnSync helper for the rtk install phase.
+ *
+ * Why local: `lib/skill-deps.js` does not export a `run(cmd, args)` helper
+ * (it uses `runAsync` internally and never re-exports it). The rtk phase
+ * needs a synchronous, captured spawnSync (R2.2, R4.2) that returns
+ * `{ ok, status, stdout, stderr }` — same shape as `skill-deps.runAsync` but
+ * blocking. KISS: one 20-line module, no dependency on `lib/skill-deps.js`
+ * (which is skill-domain and not a generic command runner).
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {object} [opts] — passed through to spawnSync (e.g. { timeout })
+ * @returns {{ ok: boolean, status: number|null, stdout: string, stderr: string }}
+ */
+const { spawnSync } = require('child_process');
+
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
+  return {
+    ok: !r.error && r.status === 0,
+    status: r.status,
+    stdout: r.stdout || '',
+    stderr: r.stderr || ''
+  };
+}
+
+module.exports = { run };

package/bin/phases/setup-rtk.js

@@ -0,0 +1,159 @@
+/**
+ * setup-rtk — opt-in install of the rtk token-saver and its Claude Code hook.
+ *
+ * Phase order (per specs/rtk-installer-integration/design.md):
+ *   shouldRunRtk → ensureRtkBinary → `rtk init -g` → jq precheck → manifest
+ *
+ * R1-01 wired the consent gate (`shouldRunRtk`) and a thin `setupRtk` wrapper.
+ * R2-01 adds the orchestrator: `ensureRtkBinary` (detect/install), the
+ * `rtk init -g` hook registration, the `jq` precheck, and the manifest write.
+ *
+ * Non-fatal invariant (R2.7, R4.1): the entire `setupRtk` body is wrapped in
+ * try/catch. Any throw / non-zero exit / timeout is logged as a warning via
+ * `ctx.t('rtkFailed')` (with `{reason}` interpolation) and the cafekit
+ * install continues with its existing exit code. Mirrors the non-fatal
+ * contract of `phases/skills-setup.js`.
+ *
+ * Idempotency (R2.1, R2.6): re-runs see `hasCmd('rtk')` short-circuit the
+ * binary install path and re-invoke `rtk init -g` (rtk's own command handles
+ * its hook idempotency). The in-memory `ctx.rtkSetupRan` flag records that
+ * setup executed, so downstream consumers (R3-01 summary line) can read it.
+ *
+ * Cross-OS install (validated 2026-06-15): best-effort order
+ *   (1) official prebuilt install script (pinned source)
+ *   (2) `cargo install rtk` when `hasCmd('cargo')`
+ *   (3) skip + warn
+ * covers macOS/Linux dev machines (cargo fall-through) and CI (skip+warn).
+ *
+ * No timeout for `cargo install rtk` (validated 2026-06-15): user accepted
+ * default `spawnSync` timeout; non-fatal guarantee holds via try/catch.
+ */
+
+const dep = require('../lib/skill-deps');
+const rtkRun = require('../lib/rtk-run');
+const { hasCmd } = dep;
+const { run } = rtkRun;
+
+const RTK_INIT_TIMEOUT_MS = 30_000;       // `rtk init -g` is a fast global-hook write
+const RTK_PREBUILT_TIMEOUT_MS = 120_000;  // prebuilt install: curl download + sh pipe; slow networks need headroom
+const RTK_PREBUILT_INSTALL_URL =
+  'https://raw.githubusercontent.com/rtk-ai/rtk/main/install.sh';
+
+/**
+ * Detect rtk binary, installing it if absent. Pure function over `ctx`.
+ *
+ * @param {object} ctx
+ * @returns {'present'|'installed'|'absent'}
+ */
+function ensureRtkBinary(ctx) {
+  if (hasCmd('rtk')) return 'present';
+  return installRtkBinary(ctx) ? 'installed' : 'absent';
+}
+
+/**
+ * Best-effort rtk install. Tries the official prebuilt install script first
+ * (R5.2: surface source), then falls back to `cargo install rtk` if cargo is
+ * available, otherwise returns false (R2.3 non-fatal skip).
+ *
+ * @param {object} ctx
+ * @returns {boolean} true on success, false on failure or no method available
+ */
+function installRtkBinary(ctx) {
+  // Method 1: official prebuilt install script (pinned URL).
+  ctx.ui.info(ctx.t('rtkInstalling', { method: `prebuilt script (${RTK_PREBUILT_INSTALL_URL})` }));
+  const prebuilt = run('sh', ['-c', `curl -fsSL ${RTK_PREBUILT_INSTALL_URL} | sh`], {
+    timeout: RTK_PREBUILT_TIMEOUT_MS
+  });
+  if (prebuilt.ok) return true;
+
+  // Method 2: `cargo install rtk` if cargo is on PATH.
+  if (hasCmd('cargo')) {
+    ctx.ui.info(ctx.t('rtkInstalling', { method: 'cargo install rtk' }));
+    const cargo = run('cargo', ['install', 'rtk']);
+    if (cargo.ok) return true;
+  }
+
+  // No method succeeded.
+  return false;
+}
+
+/**
+ * Phase entrypoint. R2-01 wires the full install + hook + manifest pipeline.
+ * The consent gate is delegated to `shouldRunRtk(ctx)` (R1-01).
+ *
+ * @param {object} ctx
+ * @returns {Promise<object>} the same ctx
+ */
+async function setupRtk(ctx) {
+  if (!(await shouldRunRtk(ctx))) {
+    // Dry-run: enumerate the action set that would have run (validated 2026-06-15).
+    if (ctx.dryRun) {
+      ctx.ui.info(
+        '[dry-run] rtk setup skipped (would: detect rtk binary, install if missing via prebuilt/cargo, run rtk init -g, check jq)'
+      );
+    } else {
+      ctx.ui.info(ctx.t('rtkSkipped'));
+    }
+    return ctx;
+  }
+
+  try {
+    // Step 1: ensure the binary is on PATH (R2.1, R2.2, R2.3).
+    const state = ensureRtkBinary(ctx);
+    if (state === 'absent') {
+      ctx.ui.warn(ctx.t('rtkInstallFailed'));
+      return ctx;
+    }
+    if (state === 'installed') {
+      ctx.ui.info(ctx.t('rtkInstalled'));
+    }
+
+    // Step 2: register rtk's official Claude Code hook via `rtk init -g` (R2.4).
+    const init = run('rtk', ['init', '-g'], { timeout: RTK_INIT_TIMEOUT_MS });
+    if (!init.ok) {
+      ctx.ui.warn(ctx.t('rtkInitFailed', { reason: init.stderr || `exit ${init.status}` }));
+      return ctx;
+    }
+
+    // Step 3: `jq` precheck (R2.5). Warn if missing; do not fail.
+    if (!hasCmd('jq')) {
+      ctx.ui.warn(ctx.t('rtkNeedsJq'));
+    }
+
+    // Step 4: record the action (R2.6, idempotency). In-memory flag — re-runs
+    // observe `hasCmd('rtk')` short-circuit and re-invoke `rtk init -g`,
+    // which is itself idempotent. R3-01 reads this flag for the summary line.
+    ctx.rtkSetupRan = true;
+    return ctx;
+  } catch (err) {
+    // Non-fatal boundary: any unexpected throw becomes a warning, the
+    // installer continues (R2.7, R4.1).
+    ctx.ui.warn(ctx.t('rtkFailed', { reason: (err && err.message) || String(err) }));
+    return ctx;
+  }
+}
+
+/**
+ * Decision matrix for whether the rtk setup phase should run. R1-01.
+ *
+ *   1. --dry-run                          → false (R1.4)
+ *   2. ctx.options.withRtk === true       → true  (R1.1)
+ *   3. !ctx.interactive                   → false (R1.3)
+ *   4. interactive confirm resolves true  → true  (R1.2)
+ *   5. interactive confirm resolves false → false (R1.2)
+ *
+ * @param {object} ctx
+ * @returns {Promise<boolean>}
+ */
+async function shouldRunRtk(ctx) {
+  if (ctx.dryRun) return false;
+  if (ctx.options.withRtk) return true;
+  if (!ctx.interactive) return false;
+  const yes = await ctx.ui.confirm(
+    { message: ctx.t('rtkConfirm'), initialValue: false },
+    false
+  );
+  return yes === true;
+}
+
+module.exports = { shouldRunRtk, setupRtk, ensureRtkBinary, installRtkBinary };

package/bin/phases/summary.js

@@ -55,6 +55,10 @@ function printSummary(ctx) {
   for (const key of platforms) {
     lines.push(key === 'claude' ? t('nsClaude') : t('nsOpencode'));
   }
+  // rtk token-saver result (set by phases/setup-rtk.js when setup completed).
+  if (ctx.rtkSetupRan) {
+    lines.push(t('rtkSummary'));
+  }
   const keySkills = skillsNeedingKeys(platforms);
   if (keySkills.length > 0) {
     lines.push(t('nsKeys', { skills: keySkills.join(', ') }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.11.11",
+  "version": "0.12.0",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",