sprag-cli 3.40.0

package/src/commands/doc2md.js

@@ -0,0 +1,166 @@
+/**
+ * Subcommand: doc2md — convert attached documents to Markdown before the
+ * model reads them.
+ *
+ *   claude-token-saver doc2md              # status
+ *   claude-token-saver doc2md on|off       # register / remove the Read hook
+ *   claude-token-saver doc2md <file>       # convert one file by hand
+ *   claude-token-saver doc2md --clean      # drop every cached conversion
+ *   claude-token-saver doc2md --hook       # PreToolUse entry point
+ */
+
+import { createRequire } from 'node:module';
+import { readdirSync, rmSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Whether the Read hook is actually in settings.json.
+ *
+ * Status output that reports only the converter is misleading: a working
+ * converter with no hook, and a hook with no converter, both add up to
+ * "nothing happens", and the user has no way to tell which half is missing.
+ */
+function hookRegistered() {
+  try {
+    const { homedir } = require('node:os');
+    const settings = JSON.parse(
+      require('node:fs').readFileSync(join(homedir(), '.claude', 'settings.json'), 'utf8'),
+    );
+    return (settings?.hooks?.PreToolUse || []).some((m) =>
+      (m.hooks || []).some((h) => typeof h.command === 'string' && h.command.includes('doc2md --hook')),
+    );
+  } catch {
+    return false;
+  }
+}
+
+export async function run({ args, hasFlag }) {
+  const doc2md = require('../doc2md.cjs');
+  const sub = args[1];
+
+  // Hook path first and cheap: this runs on every Read of a matching file, so
+  // nothing above it may cost a syscall.
+  if (hasFlag?.('--hook') || sub === '--hook') {
+    const { readStdinJson } = await import('../stdin-payload.js');
+    const payload = readStdinJson();
+    if (!payload) return;
+    let out = null;
+    try {
+      out = doc2md.formatHookOutput(doc2md.decideForRead(payload) || doc2md.decideForWrite(payload));
+    } catch {
+      // A converter that throws must not take the Read down with it. Printing
+      // nothing leaves Claude Code to run the tool call exactly as before.
+      return;
+    }
+    if (out) console.log(out);
+    return;
+  }
+
+  if (sub === 'install-converter') {
+    const res = doc2md.installConverter({ onProgress: (m) => console.log(`  ${m}`) });
+    if (res.ok) {
+      console.log(`✓ converter ready: ${res.python}`);
+    } else {
+      console.error(`✗ ${res.reason}: ${res.detail}`);
+      process.exitCode = 1;
+    }
+    // The .fig parser is a separate, Node-side install. A markitdown failure
+    // above must not block it — the two formats fail independently.
+    const fig2md = require('../fig2md.cjs');
+    const { userDataDir } = await import('../paths.js');
+    const figRes = fig2md.installFigParser(userDataDir(), { onProgress: (m) => console.log(`  ${m}`) });
+    if (figRes.ok) {
+      console.log('✓ .fig parser ready (openfig-core)');
+    } else {
+      console.error(`✗ .fig parser: ${figRes.reason}: ${figRes.detail || ''}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  // UserPromptSubmit entry point. Separate from `--hook` because the two speak
+  // different protocols: PreToolUse answers with a permission decision, this
+  // one answers with plain text that becomes context the model can act on.
+  if (hasFlag?.('--hook-prompt') || sub === '--hook-prompt') {
+    const { readStdinJson } = await import('../stdin-payload.js');
+    const payload = readStdinJson();
+    if (!payload) return;
+    const { userLanguage } = await import('../config.js');
+    try {
+      const context = doc2md.contextForPrompt(payload, { lang: userLanguage() });
+      if (context) console.log(context);
+    } catch {
+      // Never break a prompt over a conversion. Silence leaves the session
+      // exactly as it would have been without this feature.
+    }
+    return;
+  }
+
+  if (sub === 'on') {
+    const { installDoc2mdHook } = await import('../installer.js');
+    const res = installDoc2mdHook();
+    console.log(res.action === 'skipped'
+      ? `✗ ${res.reason}`
+      : `✓ Read hook ${res.action} (${res.path})`);
+    // A registered hook with no converter behind it does nothing at all, and
+    // says nothing about it either, which reads as a broken feature. Offer the
+    // one command that closes the gap right where the gap is visible.
+    const python = doc2md.findInterpreter();
+    console.log(python
+      ? `  converter: markitdown via ${python}`
+      : `  converter: missing — run \`${doc2md.INSTALL_HINT}\` or the hook will do nothing`);
+    return;
+  }
+
+  if (sub === 'off') {
+    const { removeDoc2mdHook } = await import('../installer.js');
+    const res = removeDoc2mdHook();
+    console.log(res.action === 'skipped' ? `✗ ${res.reason}` : `✓ Read hook ${res.action}`);
+    return;
+  }
+
+  if (hasFlag?.('--clean') || sub === '--clean') {
+    const dir = doc2md.cacheDir();
+    let removed = 0;
+    if (existsSync(dir)) {
+      for (const name of readdirSync(dir)) {
+        rmSync(join(dir, name), { force: true });
+        removed += 1;
+      }
+    }
+    console.log(`✓ removed ${removed} cached file(s) from ${dir}`);
+    return;
+  }
+
+  // A path: convert it now and print where the result landed. This is the
+  // diagnostic path — it reports the refusal reason instead of swallowing it,
+  // which is how you find out that markitdown is missing rather than guessing.
+  if (sub && !sub.startsWith('-')) {
+    const result = doc2md.convert(sub);
+    if (result.ok) {
+      console.log(`✓ ${result.cached ? 'cached' : 'converted'}: ${result.cacheFile}`);
+      if (result.meta?.note) console.log(`  ${result.meta.note}`);
+      if (result.meta?.clipped) console.log('  결과가 상한을 넘어 뒷부분을 잘랐습니다.');
+      console.log(`  ${statSync(result.cacheFile).size} bytes`);
+      return;
+    }
+    console.error(`✗ ${result.reason}${result.detail ? `: ${result.detail}` : ''}`);
+    if (result.reason === 'no-markitdown') console.error(`  ${doc2md.INSTALL_HINT}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const python = doc2md.findInterpreter();
+  const dir = doc2md.cacheDir();
+  const cached = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.md')).length : 0;
+  console.log('doc2md — attached documents are converted to Markdown before the model reads them.');
+  console.log(`  formats:   ${doc2md.TARGET_EXTENSIONS.join(' ')}`);
+  console.log(`  converter: ${python ? `markitdown via ${python}` : `not installed — ${doc2md.INSTALL_HINT}`}`);
+  console.log(`  cache:     ${dir} (${cached} file(s))`);
+  console.log(`  hook:      ${hookRegistered() ? 'registered on Read' : 'not registered'}`);
+  console.log('');
+  if (!python) console.log(`Install the converter: ${doc2md.INSTALL_HINT}`);
+  console.log('Enable with: claude-token-saver doc2md on');
+}

package/src/commands/feedback.js

@@ -0,0 +1,132 @@
+/**
+ * Subcommand: feedback — submit a bug report or feature request from the
+ * terminal (or from a Claude Code session) without opening a browser.
+ *
+ *   claude-token-saver feedback "statusline이 IntelliJ에서 깨져요"
+ *   claude-token-saver feedback --title "cache chip" "5m TTL 칩이 안 사라짐"
+ *
+ * Why this exists: GitHub issues require a logged-in browser session, and
+ * corporate networks often block github.com entirely. This command tries
+ * three transports in order and reports which one carried the message:
+ *
+ *   1. `gh` CLI, if installed and authenticated — files a real GitHub issue.
+ *   2. Anonymous Google Form POST — no login, no GitHub access needed.
+ *      (Only when the form endpoint below is configured for this build.)
+ *   3. Local fallback — saves the report to a Markdown file and prints a
+ *      prefilled GitHub new-issue URL to use from an unblocked machine.
+ *
+ * Metadata (tool version, OS, Node version) is attached automatically so a
+ * report is diagnosable without a follow-up round trip.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import os from 'node:os';
+import { debug } from '../debug.js';
+
+const REPO = 'rootstudioyaml/claude-token-saver';
+const ISSUES_URL = `https://github.com/${REPO}/issues`;
+
+// Anonymous submission endpoint (Google Form). A Google Form's formResponse
+// URL accepts unauthenticated POSTs, which is exactly the property a
+// login-free, GitHub-blocked-network path needs. Responses land in the
+// maintainer's "claude-token-saver 피드백 (Feedback)" form (published
+// 2026-09-13, responder access: anyone with the link).
+//   id      — the /d/e/<id>/ segment of the form URL
+//   message — entry.NNNN field id of the message question
+//   meta    — entry.NNNN field id of the metadata question
+const FORM = {
+  id: '1FAIpQLScISjU8_t9y8xfp-X3jvLV6_RcSjQIJ4aydATC8NazkxcJbgg',
+  message: 'entry.79517542',
+  meta: 'entry.112678638',
+};
+
+function metadata(version) {
+  return [
+    `version: ${version}`,
+    `os: ${process.platform} ${os.release()}`,
+    `node: ${process.version}`,
+  ].join('\n');
+}
+
+function tryGhCli(title, body) {
+  try {
+    const auth = spawnSync('gh', ['auth', 'status'], { encoding: 'utf8', timeout: 10_000 });
+    if (auth.status !== 0) return null;
+    const res = spawnSync('gh', ['issue', 'create', '-R', REPO, '--title', title, '--body', body],
+      { encoding: 'utf8', timeout: 30_000 });
+    if (res.status !== 0) { debug('feedback:gh', res.stderr); return null; }
+    const url = String(res.stdout).trim().split('\n').pop();
+    return { transport: 'gh', url };
+  } catch (e) { debug('feedback:gh', e); return null; }
+}
+
+async function tryForm(title, body, meta) {
+  if (!FORM) return null;
+  try {
+    const params = new URLSearchParams();
+    params.set(FORM.message, `${title}\n\n${body}`);
+    params.set(FORM.meta, meta);
+    const res = await fetch(`https://docs.google.com/forms/d/e/${FORM.id}/formResponse`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: params.toString(),
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) { debug('feedback:form', `HTTP ${res.status}`); return null; }
+    return { transport: 'form' };
+  } catch (e) { debug('feedback:form', e); return null; }
+}
+
+function saveLocal(title, body, dataDir) {
+  const dir = join(dataDir, 'feedback');
+  mkdirSync(dir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const file = join(dir, `${stamp}.md`);
+  writeFileSync(file, `# ${title}\n\n${body}\n`);
+  const prefilled = `${ISSUES_URL}/new?title=${encodeURIComponent(title)}&body=${encodeURIComponent(body)}`;
+  return { transport: 'local', file, prefilled };
+}
+
+export async function run({ args, getArg, version, dataDir }) {
+  // --anonymous skips the gh transport: for people whose gh CLI is signed in
+  // with an account they do not want attached to the report.
+  const anonymous = args.includes('--anonymous');
+  const rest = args.slice(1).filter((a, i, all) => {
+    if (a === '--title') return false;
+    if (all[i - 1] === '--title') return false;
+    return !a.startsWith('--');
+  });
+  const message = rest.join(' ').trim();
+  const explicitTitle = getArg('--title');
+
+  if (!message) {
+    console.log('usage: claude-token-saver feedback [--title "<제목>"] "<내용>"');
+    console.log(`       (GitHub에서 직접 제보: ${ISSUES_URL})`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const title = explicitTitle || (message.length > 60 ? `${message.slice(0, 57)}...` : message);
+  const meta = metadata(version);
+  const body = `${message}\n\n---\n${meta}`;
+
+  const viaGh = anonymous ? null : tryGhCli(title, body);
+  if (viaGh) {
+    console.log(`feedback: GitHub 이슈로 등록했습니다 — ${viaGh.url}`);
+    return;
+  }
+
+  const viaForm = await tryForm(title, message, meta);
+  if (viaForm) {
+    console.log('feedback: 제출했습니다. 감사합니다. (익명 제출이라 답변 추적은 GitHub 이슈에서만 가능합니다)');
+    console.log(`          공개 트래커: ${ISSUES_URL}`);
+    return;
+  }
+
+  const local = saveLocal(title, body, dataDir);
+  console.log(`feedback: 온라인 제출 경로가 없어 로컬에 저장했습니다: ${local.file}`);
+  console.log('          GitHub 접근이 가능한 환경에서 아래 주소를 열면 내용이 채워진 이슈 작성 화면이 나옵니다:');
+  console.log(`          ${local.prefilled}`);
+}

package/src/commands/handoff.js

@@ -0,0 +1,33 @@
+/**
+ * Subcommand: handoff — write a HANDOFF-YYYY-MM-DD-HHMM.md template in cwd
+ * capturing git status + the latest cap snapshot, so a fresh Claude Code
+ * session can pick up where this one stopped. Pairs with the cap-warn chip:
+ * when statusline shows 🚨 5H 90%+, run this to back up state before the cap
+ * hits.
+ *   claude-token-saver handoff             # write to cwd
+ *   claude-token-saver handoff --cwd PATH  # custom directory
+ */
+
+import { readStdinJson, extractCaps } from '../stdin-payload.js';
+import { debug } from '../debug.js';
+
+export async function run({ getArg }) {
+    const { writeHandoff } = await import('../handoff.js');
+    const { recordHandoff } = await import('../history.js');
+    const cwd = getArg('--cwd') || process.cwd();
+    // Cap data only flows in via stdin (Claude Code statusline contract).
+    // Direct CLI invocations won't have it — that's fine, the template will
+    // note the gap.
+    const stdinJson = readStdinJson();
+    const caps = extractCaps(stdinJson);
+    const { path, git } = writeHandoff({ cwd, caps });
+    try { recordHandoff(path); } catch (e) { debug('handoff:record', e); }
+    console.log(`Handoff written: ${path}`);
+    if (git) {
+      console.log(`  git: ${git.branch}${git.head ? ` @ ${git.head}` : ''}${git.status ? ' (dirty)' : ' (clean)'}`);
+    }
+    console.log('');
+    console.log('Fill in the empty sections, then start a new Claude Code session with:');
+    console.log('  Read the most recent HANDOFF-*.md in this directory and continue the work.');
+    return;
+}