sprag-cli 3.40.0

package/src/commands/seed.js

@@ -0,0 +1,105 @@
+/**
+ * Subcommand: seed — register the bundled starter rules, one answer at a time.
+ *
+ *   claude-token-saver seed                          # what is still pending
+ *   claude-token-saver seed accept <id> --global     # register one rule
+ *   claude-token-saver seed accept <id> --project    # ... into this project only
+ *   claude-token-saver seed accept all --global      # when the user says "all of them"
+ *   claude-token-saver seed skip <id> | skip all     # never offer it again
+ *   claude-token-saver seed reset                    # make every preset pending again
+ *
+ * Scope is explicit on purpose, exactly as `harness promote` requires it: the
+ * hook environment is non-TTY, so the model has to ask the user and pass the
+ * flag rather than let a default decide where a rule lands.
+ */
+
+export async function run({ args, hasFlag }) {
+  const sub = args[1];
+  const seed = await import('../seed-rules.js');
+  const { userLanguage } = await import('../config.js');
+  const { findProjectRoot } = await import('../harness.js');
+  const lang = userLanguage();
+  const ko = lang === 'ko';
+  const root = findProjectRoot();
+
+  const scopeFlag = () => (hasFlag('--global') ? 'global' : hasFlag('--project') ? 'project' : null);
+
+  if (sub === 'reset') {
+    const n = seed.resetSeeds();
+    console.log(ko
+      ? `기록된 응답 ${n}건을 지웠습니다 — 프리셋 전체가 다시 제안 대상이 됩니다.`
+      : `Cleared ${n} recorded answer(s) — every preset is pending again.`);
+    return;
+  }
+
+  if (sub === 'accept' || sub === 'skip') {
+    const ids = args.slice(2).filter((a) => !a.startsWith('-'));
+    if (ids.length === 0) {
+      console.error(ko
+        ? 'id를 지정하십시오 (목록: claude-token-saver seed). 전체는 `all`.'
+        : 'Pass an id (list them with `claude-token-saver seed`), or `all`.');
+      process.exit(1);
+    }
+    const pending = seed.pendingSeeds({ lang, root });
+    const targets = ids.includes('all') ? pending.map((s) => s.id) : ids;
+
+    if (sub === 'skip') {
+      for (const id of targets) {
+        const r = seed.skipSeed(id, { lang, root });
+        console.log(r
+          ? (ko ? `건너뜀: ${id}` : `skipped: ${id}`)
+          : (ko ? `대기 중인 프리셋이 아닙니다: ${id}` : `not a pending preset: ${id}`));
+      }
+      return;
+    }
+
+    const scope = scopeFlag();
+    if (!scope) {
+      console.error(ko
+        ? '적용 범위를 명시하십시오 (사용자에게 먼저 확인): --global 또는 --project'
+        : 'Scope required (confirm it with the user first): --global or --project');
+      process.exit(1);
+    }
+    for (const id of targets) {
+      const r = await seed.acceptSeed(id, { scope, root, lang });
+      if (!r) {
+        console.log(ko ? `대기 중인 프리셋이 아닙니다: ${id}` : `not a pending preset: ${id}`);
+        continue;
+      }
+      console.log(ko
+        ? `✅ 등록: ${id} [${scope === 'global' ? '전체 프로젝트' : '이 프로젝트'}]`
+        : `✅ registered: ${id} [${scope}]`);
+      console.log(`   ${r.rule}`);
+      for (const p of r.paths || (r.path ? [r.path] : [])) console.log(`   → ${p}`);
+    }
+    return;
+  }
+
+  // Default: status. Lists what is pending and what was already answered, so a
+  // user who said no can see that they did and reverse it with `reset`.
+  const pending = seed.pendingSeeds({ lang, root });
+  const { decided } = seed.loadSeedState();
+  const answered = Object.entries(decided);
+  console.log(ko
+    ? `seed — 동봉 프리셋 중 대기 ${pending.length}건, 응답 완료 ${answered.length}건`
+    : `seed — ${pending.length} preset(s) pending, ${answered.length} already answered`);
+  for (const s of pending) {
+    const head = s.kind === 'model'
+      ? `[${s.id}] ${s.tier} · "${s.label}" → ${s.agent}`
+      : `[${s.id}] ${ko ? '랫쳇 룰' : 'ratchet rule'}`;
+    console.log(`  ${head}`);
+    console.log(`      ${s.ruleText}`);
+  }
+  if (answered.length > 0) {
+    console.log(ko ? '  응답 기록:' : '  answered:');
+    for (const [id, d] of answered) {
+      console.log(`    ${id}: ${d.action}${d.scope ? ` (${d.scope})` : ''} — ${d.at}`);
+    }
+  }
+  if (pending.length > 0) {
+    console.log('');
+    console.log(ko
+      ? '등록: claude-token-saver seed accept <id> --global|--project   ·   거절: seed skip <id>'
+      : 'register: claude-token-saver seed accept <id> --global|--project   ·   decline: seed skip <id>');
+  }
+}

package/src/commands/uninstall.js

@@ -0,0 +1,42 @@
+/**
+ * Subcommand: uninstall — take the integration back out of ~/.claude.
+ *
+ *   claude-token-saver uninstall           # hooks, statusline, skill
+ *   claude-token-saver uninstall --purge   # the above plus recorded state
+ *
+ * Recorded savings are kept by default. Someone removing an integration is
+ * usually not asking to throw away the ledger that says what it saved, and
+ * that data cannot be reconstructed once the transcripts age out.
+ */
+
+export async function run({ hasFlag, args = [] }) {
+  const { uninstallAll } = await import('../installer.js');
+  const { userLanguage } = await import('../config.js');
+  const lang = userLanguage();
+  const purge = hasFlag('--purge') || args.includes('--purge');
+
+  const r = uninstallAll({ purge });
+
+  if (r.action === 'skipped') {
+    console.error(lang === 'ko'
+      ? `✗ ${r.path} 를 읽지 못해 아무것도 지우지 않았습니다: ${r.reason}`
+      : `✗ nothing removed — ${r.path} could not be read: ${r.reason}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (r.removed.length === 0) {
+    console.log(lang === 'ko' ? '설치된 항목이 없습니다.' : 'Nothing was installed.');
+  } else {
+    console.log(lang === 'ko' ? `✓ 제거했습니다 (${r.path}):` : `✓ removed (${r.path}):`);
+    for (const item of r.removed) console.log(`  - ${item}`);
+  }
+  for (const item of r.kept) {
+    console.log(lang === 'ko' ? `  유지: ${item}` : `  kept: ${item}`);
+  }
+  if (!purge) {
+    console.log(lang === 'ko'
+      ? '  기록된 절감액과 설정까지 지우려면 `claude-token-saver uninstall --purge` 를 실행하십시오.'
+      : '  To remove recorded savings and settings too: `claude-token-saver uninstall --purge`.');
+  }
+}

package/src/commands/update-check.js

@@ -0,0 +1,77 @@
+/**
+ * Subcommand: update-check — everything around "is a newer version out".
+ *
+ *   claude-token-saver update-check              # print the cached answer
+ *   claude-token-saver update-check --refresh    # ask the registry now
+ *   claude-token-saver update-check --refresh --quiet
+ *                                                # what the detached background child runs
+ *   claude-token-saver update-check --dismiss    # stop offering this version at session start
+ *
+ * The statusline never calls the --refresh path directly; it spawns this
+ * command detached so the render itself stays offline and instant.
+ */
+
+export async function run({ hasFlag, version }) {
+  const {
+    updateStatus,
+    refreshUpdateState,
+    dismissUpdate,
+    upgradeCommand,
+    updateCheckDisabled,
+    updateStatePath,
+  } = await import('../update-check.js');
+  const { userLanguage } = await import('../config.js');
+  const lang = userLanguage();
+  const quiet = hasFlag('--quiet');
+
+  if (hasFlag('--refresh')) {
+    const res = await refreshUpdateState(version);
+    if (quiet) return;
+    if (!res.ok) {
+      console.error(lang === 'ko'
+        ? `최신 버전을 확인하지 못했습니다: ${res.error}`
+        : `Could not reach the registry: ${res.error}`);
+      process.exit(1);
+    }
+  }
+
+  if (hasFlag('--dismiss')) {
+    const s = updateStatus(version);
+    if (s.latest) dismissUpdate(s.latest);
+    console.log(lang === 'ko'
+      ? `${s.latest || '최신'} 버전 안내를 끕니다. 그 다음 버전이 나오면 다시 안내합니다.`
+      : `Muted the ${s.latest || 'latest'} notice. The next release after it will ask again.`);
+    return;
+  }
+
+  if (updateCheckDisabled()) {
+    console.log(lang === 'ko'
+      ? `현재 버전 v${version} — 업데이트 확인이 환경 변수로 꺼져 있습니다 (CTS_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER).`
+      : `v${version} — update checks are disabled by env var (CTS_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER).`);
+    return;
+  }
+
+  const s = updateStatus(version);
+  if (s.available) {
+    console.log(lang === 'ko'
+      ? `새 버전이 있습니다: v${version} → ${s.latest}`
+      : `Update available: v${version} → ${s.latest}`);
+    console.log(lang === 'ko'
+      ? `업그레이드: ${upgradeCommand()}   (또는 claude-token-saver upgrade)`
+      : `Upgrade with: ${upgradeCommand()}   (or: claude-token-saver upgrade)`);
+    if (s.dismissed) {
+      console.log(lang === 'ko'
+        ? '이 버전은 사용자가 한 번 넘긴 상태라, 세션 시작 시에는 다시 묻지 않습니다.'
+        : 'This version was dismissed, so the session-start offer stays quiet for it.');
+    }
+    return;
+  }
+  console.log(lang === 'ko'
+    ? `최신 버전을 쓰고 있습니다 (v${version}).`
+    : `Up to date (v${version}).`);
+  if (!s.latest) {
+    console.log(lang === 'ko'
+      ? `아직 확인된 기록이 없습니다. 지금 확인하려면: claude-token-saver update-check --refresh (기록 파일: ${updateStatePath()})`
+      : `No check has completed yet. Run: claude-token-saver update-check --refresh (state: ${updateStatePath()})`);
+  }
+}

package/src/commands/upgrade.js

@@ -0,0 +1,68 @@
+/**
+ * Subcommand: upgrade — install the latest release with the package manager
+ * that put this copy on disk.
+ *
+ *   claude-token-saver upgrade          # refresh the check, then install
+ *   claude-token-saver upgrade --print  # show the command, run nothing
+ *
+ * This is the command the model runs after the user says yes to the
+ * session-start offer, so it prints the exact command it is about to execute
+ * before executing it: an install that writes outside the project should never
+ * be a black box.
+ */
+
+import { spawn } from 'node:child_process';
+
+function runCommand(cmd) {
+  return new Promise((resolve) => {
+    // Shell form: the upgrade command is a fixed string we composed ourselves
+    // (no user input reaches it), and `npm install -g` needs the user's PATH
+    // resolution to find the same npm that installed us.
+    const child = spawn(cmd, { shell: true, stdio: 'inherit' });
+    child.on('close', (code) => resolve(code === null ? 1 : code));
+    child.on('error', () => resolve(1));
+  });
+}
+
+export async function run({ hasFlag, version }) {
+  const { updateStatus, refreshUpdateState, upgradeCommand } = await import('../update-check.js');
+  const { userLanguage } = await import('../config.js');
+  const lang = userLanguage();
+  const cmd = upgradeCommand();
+
+  if (hasFlag('--print')) {
+    console.log(cmd);
+    return;
+  }
+
+  // Refresh first so the "already latest" answer is trustworthy rather than up
+  // to 24h stale — an upgrade is a deliberate, interactive action, so one
+  // network round trip is fine here.
+  await refreshUpdateState(version);
+  const s = updateStatus(version);
+  if (!s.available) {
+    console.log(lang === 'ko'
+      ? `이미 최신 버전입니다 (v${version}). 설치할 것이 없습니다.`
+      : `Already on the latest version (v${version}). Nothing to install.`);
+    return;
+  }
+
+  console.log(lang === 'ko'
+    ? `v${version} → ${s.latest} 로 업그레이드합니다.`
+    : `Upgrading v${version} → ${s.latest}.`);
+  console.log(`$ ${cmd}`);
+  const code = await runCommand(cmd);
+  if (code !== 0) {
+    console.error(lang === 'ko'
+      ? `업그레이드 명령이 종료 코드 ${code}로 실패했습니다. 위 출력을 확인하고, 권한 문제라면 sudo 없이 설치되는 전역 경로인지 점검하십시오.`
+      : `Upgrade command failed with exit code ${code}. Check the output above; if it is a permissions error, verify your global install prefix.`);
+    process.exit(code);
+  }
+  // The freshly installed copy is a different file on disk, so this process
+  // still reports the old version. Refresh the cache against the new latest so
+  // the statusline chip clears on the next render instead of lingering.
+  await refreshUpdateState(s.latest);
+  console.log(lang === 'ko'
+    ? `설치가 끝났습니다. 새 셸에서 claude-token-saver --version 으로 ${s.latest} 인지 확인하십시오.`
+    : `Done. In a fresh shell, run claude-token-saver --version to confirm ${s.latest}.`);
+}

package/src/compact-window.js

@@ -0,0 +1,205 @@
+/**
+ * compact-window — auto-compact window audit for 1M-context sessions.
+ *
+ * Claude Code compacts when context usage approaches
+ * `min(settings.autoCompactWindow, model max context)`. On a 1M window the
+ * default lets a session grow past 800k before compaction ever fires, so every
+ * later request re-bills a context most sessions never needed. Pinning
+ * `autoCompactWindow` somewhere in 400k–700k keeps 2–3.5x the headroom of a
+ * 200k session for the genuinely large ones while capping the runaway tail.
+ *
+ * The recommendation is a range, not a number: 400k is the floor where the
+ * saving is worth the extra compactions, and in practice long sessions often
+ * want more room than that. Anything at or below 700k is left alone — only an
+ * unset window, or one above 700k, is a real config defect.
+ *
+ * 200k sessions are exempt by design: their window is already <= 200k, so the
+ * setting changes nothing and a warning would be pure noise.
+ *
+ * Sources, highest precedence first (mirrors Claude Code's own resolution):
+ *   1. env CLAUDE_CODE_AUTO_COMPACT_WINDOW  ("200000" | "200k" | "200")
+ *   2. <root>/.claude/settings.local.json
+ *   3. <root>/.claude/settings.json
+ *   4. ~/.claude/settings.json
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { debug } from './debug.js';
+
+// Claude Code clamps autoCompactWindow to [100k, 1M] (settings schema:
+// `.int().min(1e5).max(1e6)`), so anything outside that range is not a value
+// the app would honor.
+export const MIN_WINDOW = 100_000;
+export const MAX_WINDOW = 1_000_000;
+// Recommended band. Warn only outside it on the high side (or when unset) —
+// a window below RECOMMENDED_MIN is a deliberate, more aggressive choice and
+// costs nothing, so it stays silent.
+export const RECOMMENDED_MIN = 400_000;
+export const RECOMMENDED_MAX = 700_000;
+// What `compact-window set` writes when no --value is given: middle of the band.
+export const RECOMMENDED_WINDOW = 500_000;
+
+// A model id whose context is the 1M variant. Claude Code spells it as a
+// suffix on the model id (`claude-opus-5[1m]`); the beta header form
+// (`context-1m`) shows up in SDK/env configs.
+const ONE_M_RE = /\[1m\]|context-1m|1m-context/i;
+
+export function userSettingsPath() {
+  return join(homedir(), '.claude', 'settings.json');
+}
+
+export function projectSettingsPaths(root) {
+  return [
+    join(root, '.claude', 'settings.local.json'),
+    join(root, '.claude', 'settings.json'),
+  ];
+}
+
+function readJson(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (e) {
+    debug('compact-window:read', e);
+    return null; // malformed settings — treat as "nothing configured"
+  }
+}
+
+/**
+ * Parse the value forms Claude Code accepts for a window size: a plain token
+ * count, a `200k`/`1M` shorthand, or the bare-hundreds shorthand (`200` = 200k)
+ * its /config parser documents. Returns null when unparseable.
+ */
+export function parseWindow(raw) {
+  if (typeof raw === 'number') return Number.isFinite(raw) ? Math.round(raw) : null;
+  if (typeof raw !== 'string') return null;
+  const s = raw.trim().toLowerCase();
+  const m = s.match(/^(\d+(?:\.\d+)?)\s*([km]?)$/);
+  if (!m) return null;
+  const n = parseFloat(m[1]);
+  if (!Number.isFinite(n)) return null;
+  if (m[2] === 'k') return Math.round(n * 1_000);
+  if (m[2] === 'm') return Math.round(n * 1_000_000);
+  // Bare number: below the legal minimum it can only be the `200` = 200k form.
+  return n < MIN_WINDOW ? Math.round(n * 1_000) : Math.round(n);
+}
+
+/**
+ * The model id this project would launch with. Same precedence as the settings
+ * lookup, with ANTHROPIC_MODEL on top (Claude Code reads it as an override).
+ */
+export function resolveModelId(root) {
+  if (process.env.ANTHROPIC_MODEL) return { model: process.env.ANTHROPIC_MODEL, source: 'env' };
+  for (const p of projectSettingsPaths(root)) {
+    const j = readJson(p);
+    if (j && typeof j.model === 'string') return { model: j.model, source: 'project', path: p };
+  }
+  const g = readJson(userSettingsPath());
+  if (g && typeof g.model === 'string') return { model: g.model, source: 'global', path: userSettingsPath() };
+  return { model: null, source: null };
+}
+
+export function isOneMillionModel(model) {
+  return typeof model === 'string' && ONE_M_RE.test(model);
+}
+
+/** Effective autoCompactWindow, with the source that won. */
+export function effectiveWindow(root) {
+  const env = process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW;
+  if (env) {
+    const v = parseWindow(env);
+    if (v !== null) return { value: v, source: 'env' };
+  }
+  for (const p of projectSettingsPaths(root)) {
+    const j = readJson(p);
+    const v = j ? parseWindow(j.autoCompactWindow) : null;
+    if (v !== null) return { value: v, source: 'project', path: p };
+  }
+  const gp = userSettingsPath();
+  const g = readJson(gp);
+  const gv = g ? parseWindow(g.autoCompactWindow) : null;
+  if (gv !== null) return { value: gv, source: 'global', path: gp };
+  return { value: null, source: null };
+}
+
+/**
+ * Full audit result. `ok` is true when there is nothing to warn about — either
+ * the session is not on a 1M model (exempt), or the window is already pinned at
+ * or below the top of the recommended band (700k).
+ *
+ * `reason` names why it is not ok: 'unset' (no autoCompactWindow anywhere) or
+ * 'too-large' (set, but above 700k — still lets context run away).
+ */
+export function compactWindowStatus({ root = process.cwd() } = {}) {
+  const { model, source: modelSource } = resolveModelId(root);
+  const is1m = isOneMillionModel(model);
+  const win = effectiveWindow(root);
+  const base = {
+    model,
+    modelSource,
+    is1m,
+    window: win.value,
+    windowSource: win.source,
+    windowPath: win.path || null,
+    recommended: RECOMMENDED_WINDOW,
+    recommendedMin: RECOMMENDED_MIN,
+    recommendedMax: RECOMMENDED_MAX,
+  };
+  if (!is1m) return { ...base, ok: true, reason: 'not-1m' };
+  if (win.value === null) return { ...base, ok: false, reason: 'unset' };
+  if (win.value > RECOMMENDED_MAX) return { ...base, ok: false, reason: 'too-large' };
+  return { ...base, ok: true, reason: 'configured' };
+}
+
+/**
+ * Statusline chip text, or null when there is nothing to say. Kept to the same
+ * short shape as the other 🅷⚠ warnings so the line stays single-width.
+ */
+export function compactWindowWarningForStatusline(root = process.cwd(), cfg = null) {
+  if (cfg && cfg.compactWindow && cfg.compactWindow.enabled === false) return null;
+  try {
+    const s = compactWindowStatus({ root });
+    return s.ok ? null : 'compact-window?';
+  } catch (e) {
+    debug('compact-window:statusline', e);
+    return null;
+  }
+}
+
+/**
+ * Write `autoCompactWindow` into a settings.json, preserving every other key.
+ * Scope 'global' → ~/.claude/settings.json, 'project' → <root>/.claude/settings.json.
+ * A `.bak` is written first whenever the file already exists.
+ *
+ * Returns { path, scope, value, previous, backup }.
+ */
+export function setAutoCompactWindow({ root = process.cwd(), scope = 'global', value = RECOMMENDED_WINDOW } = {}) {
+  const v = parseWindow(value);
+  if (v === null || v < MIN_WINDOW || v > MAX_WINDOW) {
+    return { ok: false, error: `Invalid window: ${value} (expected ${MIN_WINDOW}–${MAX_WINDOW} tokens, e.g. 400000 or 400k)` };
+  }
+  const path = scope === 'global' ? userSettingsPath() : join(root, '.claude', 'settings.json');
+  let json = {};
+  let backup = null;
+  if (existsSync(path)) {
+    const raw = readFileSync(path, 'utf8');
+    try {
+      json = JSON.parse(raw);
+    } catch (e) {
+      debug('compact-window:parse', e);
+      // Refuse to overwrite a file we cannot parse — silently replacing a
+      // malformed settings.json would drop every other setting in it.
+      return { ok: false, error: `${path} is not valid JSON — fix it first (nothing was written).` };
+    }
+    backup = `${path}.bak`;
+    writeFileSync(backup, raw);
+  } else {
+    mkdirSync(dirname(path), { recursive: true });
+  }
+  const previous = parseWindow(json.autoCompactWindow);
+  json.autoCompactWindow = v;
+  writeFileSync(path, JSON.stringify(json, null, 2) + '\n');
+  return { ok: true, path, scope, value: v, previous, backup };
+}