therookie 0.4.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rolling Mango Corp. (주식회사 롤링망고)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# therookie
+
+**the Rookie** — the AI new hire that remembers what you teach it. A CLI that connects a personal AI memory ("the Rookie") to AI tools like Claude and Codex. It remembers your company, projects, context, and preferences across sessions.
+
+- Homepage: https://therookie.kr
+- Guide: https://therookie.kr/guide
+- Maintained by: Rolling Mango Corp.
+
+## Install
+
+```sh
+npm i -g therookie
+```
+
+Two steps to connect after install:
+
+```sh
+rookie init     # Register Skill & Hook (attaches the Rookie to your AI tools)
+rookie login    # Link your Rookie account in the browser (issues a PAT)
+```
+
+`rookie login` opens your browser. Log in, click **"Allow"**, and you're done. From then on, every time you start a Claude Code or Codex session, the Rookie shows up automatically with its memory.
+
+## What gets installed
+
+- CLI: npm global path (`npm root -g`)
+- Skill & Hook: `~/.claude/` (Claude Code), `~/.codex/` (Codex) — these power the "shows up every session" behavior
+- Shared hook runtime & config: `~/.rookie/`
+
+Nothing is installed system-wide — everything lives under your home directory. Hooks you registered yourself are preserved and distinguished by a `__rookie_managed` marker.
+
+## Access scope
+
+The **"Allow"** in `rookie login` grants permission to read and write **your own Rookie account memory** — nothing else. It does not touch your local filesystem or anyone else's account. What you teach it is stored only in your account.
+
+Sensitive data (API keys, passwords, PII, `.env` contents, etc.) is filtered out at the code level before it ever reaches storage.
+
+## Update & remove
+
+```sh
+npm i -g therookie@latest   # update
+npm rm -g therookie         # remove (your ~/.rookie account config is preserved)
+```
+
+To also clean up hooks and the Skill, run `rookie unlink` first.
+
+## Requirements
+
+- Node.js 20+
+- Zero dependencies (Node built-in modules only)
+
+## Commands
+
+```
+rookie init      First install — deploy Skill & Hook
+rookie login     Connect your account via browser approval
+rookie link      Register the current project with the Rookie
+rookie doctor    Check install & connection status
+rookie update    Sync templates
+rookie unlink    Remove hooks & Skill
+```
+
+Run `rookie help` for the full command list.

package/bin/rookie.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js'
+run(process.argv.slice(2)).catch((err) => {
+  console.error('[rookie] error:', err.message)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "therookie",
+  "version": "0.4.3",
+  "description": "the Rookie — the AI new hire that remembers what you teach it. A CLI that connects a personal AI memory to AI tools like Claude and Codex.",
+  "license": "MIT",
+  "keywords": [
+    "ai",
+    "memory",
+    "claude",
+    "claude-code",
+    "codex",
+    "mcp",
+    "rookie",
+    "the-rookie"
+  ],
+  "homepage": "https://therookie.kr",
+  "bugs": {
+    "url": "https://therookie.kr"
+  },
+  "bin": {
+    "rookie": "bin/rookie.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "version.json",
+    "!**/*.test.js",
+    "!**/*.test.mjs",
+    "!**/*.test.ts",
+    "!**/*.test.sh"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api.js

@@ -0,0 +1,67 @@
+export async function apiGet(endpoint, token, path, opts = {}) {
+  // opts.timeoutMs — AbortController 로 fetch 를 바운드한다. hook(SessionStart) 안에서 도는 호출은
+  // 네트워크 지연 시 무한 대기하면 hook timeout(Codex 15s)을 터뜨리므로 반드시 타임아웃을 준다.
+  const { timeoutMs } = opts
+  let signal
+  let timer
+  if (timeoutMs) {
+    const ac = new AbortController()
+    signal = ac.signal
+    timer = setTimeout(() => ac.abort(), timeoutMs)
+  }
+  try {
+    const res = await fetch(`${endpoint}${path}`, {
+      headers: { Authorization: `Bearer ${token}` },
+      signal,
+    })
+    if (!res.ok) {
+      const body = await res.text()
+      throw new Error(`GET ${path} failed: ${res.status} ${body}`)
+    }
+    return res.json()
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}
+
+export async function apiPost(endpoint, token, path, body, opts = {}) {
+  // opts.headers — 추가 헤더 병합 (B5: link 의 x-rookie-surface 등). 기존 호출자 무영향.
+  const res = await fetch(`${endpoint}${path}`, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      ...(opts.headers || {}),
+    },
+    body: JSON.stringify(body),
+  })
+  if (!res.ok) {
+    const text = await res.text()
+    throw new Error(`POST ${path} failed: ${res.status} ${text}`)
+  }
+  return res.json()
+}
+
+export async function apiPostNoAuth(endpoint, path, body) {
+  const res = await fetch(`${endpoint}${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+  if (!res.ok) {
+    const text = await res.text()
+    throw new Error(`POST ${path} failed: ${res.status} ${text}`)
+  }
+  return res.json()
+}
+
+// 폴링 전용: 비2xx 도 throw 하지 않고 {ok,status,body} 반환.
+export async function apiPostNoAuthRaw(endpoint, path, body) {
+  const res = await fetch(`${endpoint}${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+  const json = await res.json().catch(() => ({}))
+  return { ok: res.ok, status: res.status, body: json }
+}

package/src/cli.js

@@ -0,0 +1,139 @@
+import { runInit } from './commands/init.js'
+import { runLogin } from './commands/login.js'
+import { runLink } from './commands/link.js'
+import { runStatus } from './commands/status.js'
+import { runUnlink } from './commands/unlink.js'
+import { runDoctor } from './commands/doctor.js'
+import { runSave } from './commands/save.js'
+import { runToken } from './commands/token.js'
+import { runUpdate } from './commands/update.js'
+import { runSweepRecovery } from './commands/sweep-recovery.js'
+import { runCodexSetup } from './commands/codex-setup.js'
+import { runScanSpecs } from './commands/scan-specs.js'
+import { runClusterTodos } from './commands/cluster-todos.js'
+import { runDoneScan } from './commands/done-scan.js'
+import { runContextDiet } from './commands/context-diet.js'
+import { runOrphanExtract } from './commands/orphan-extract.js'
+
+const HELP = `rookie — the Rookie Skill/Hook 설치 관리자
+
+사용:
+  rookie init [--local] [--force] [--yes] [--deep-scan]
+  rookie login [--local]
+  rookie update [--force]
+  rookie link [--local]
+  rookie save [--file <body.json>]   # 또는 stdin
+  rookie status
+  rookie doctor [--deep-scan] [--dead-letters]
+  rookie unlink [--local | --global]
+  rookie token list | revoke <id> | rotate
+  rookie sweep-recovery [--force]
+  rookie codex-setup [--yes]
+  rookie done-scan [--force]
+  rookie context-diet [--json] [--force]
+  rookie orphan-extract [--batch=5]
+
+옵션:
+  --local       프로젝트 로컬 스코프 — login 은 토큰도 <dir>/.rookie/config.json 에 저장(전역 무변경)
+  --force       경고 무시, 재설치/덮어쓰기
+  --yes         비대화형 자동 승인
+  --deep-scan   홈 디렉토리에서 로컬 Skill 전수 스캔
+
+명령:
+  init             첫 설치. 비밀번호 입력 받아 PAT 발급 + Skill/Hook 배포.
+  login            브라우저 승인으로 PAT 발급(비밀번호 입력 없음). 권장 인증 경로.
+                   ⚠ 다계정 운영 규칙(B6): 테스트 계정은 반드시 login --local 로 해당 디렉토리에만 binding.
+                   전역 login 으로 다른 계정 전환 시 확인 게이트가 뜬다(비대화형은 --yes 필요).
+  update           templates 동기화 전용. PAT 재발급 안 함. CI/자동화 친화.
+  save             기억 저장(batch-mutate). **cwd·git remote·hostname 을 CLI 가 자동 주입**하므로
+                   호출자는 본문(working_cards/evidence/self_rules/verifications)만 주면 된다.
+                   전역 fact 는 본문에 project_id:null 을 명시한다(생략은 거부됨 — 조용한 누수 차단).
+  sweep-recovery   비정상 종료 세션 사후 복구 sweep (하루 1회, --force 로 강제 실행).
+  codex-setup      Codex config.toml 에 SessionStart hook 등록(동의 기반). 자동 회상 주입.
+  scan-specs       현재 프로젝트 spec 의 후속 섹션을 대시보드 proposal 로 동기화(하루 1회, --force 강제).
+  cluster-todos    미분류 todo 를 임베딩 유사도로 묶어 트랙 후보 proposal 생성(하루 1회, --force 강제).
+  done-scan        doing task 를 최근 커밋과 경로 강매칭해 완료 후보를 세션 시작 시 surface(하루 1회, --force 강제).
+  context-diet     세션 주입 컨텍스트 비대 감지(5항목 proxy 측정). hook 이 주1회 권고 블록 주입, --force 는 usage 재스캔.
+  orphan-extract   비정상 종료 세션 tail 추출 초안 생성(오래된 순, 기본 5건). 저장·완료 marker 는 세션 LLM/사용자 판단.
+`
+
+export async function run(argv) {
+  const [cmd, ...rest] = argv
+  const flags = parseFlags(rest)
+  switch (cmd) {
+    case 'init': return runInit(flags)
+    case 'login': return runLogin(flags)
+    case 'update': return runUpdate(flags)
+    case 'link': return runLink(flags)
+    case 'save': return runSave(flags)
+    case 'status': return runStatus(flags)
+    case 'unlink': return runUnlink(flags)
+    case 'doctor': return runDoctor(flags)
+    case 'sweep-recovery': return runSweepRecovery(flags)
+    case 'codex-setup': return runCodexSetup(flags)
+    case 'scan-specs': return runScanSpecs(flags)
+    case 'cluster-todos': return runClusterTodos(flags)
+    case 'done-scan': {
+      // done-scan 은 SessionStart hook 안에서 돈다. 네트워크 타임아웃(apiGet 4s) 외에도 git·node startup 등
+      // 예기치 못한 hang 이 hook timeout(Codex 15s)을 터뜨리지 않도록 프로세스 하드 워치독(6s)을 건다.
+      // unref 라 정상 완료 시엔 대기 없이 종료되고, 무언가 hang 하면 6s 에 best-effort 종료(후보 미출력).
+      const _watchdog = setTimeout(() => process.exit(0), 6000)
+      if (typeof _watchdog.unref === 'function') _watchdog.unref()
+      return runDoneScan(flags)
+    }
+    case 'context-diet': {
+      // done-scan 과 동일 사유 — SessionStart hook 안에서 돌 수 있어 하드 워치독.
+      // transcript 스캔은 lib 내부 time budget(10s)이 1차 방어, 워치독 15s 는 최후 방어선.
+      const _dietWatchdog = setTimeout(() => process.exit(0), 15000)
+      if (typeof _dietWatchdog.unref === 'function') _dietWatchdog.unref()
+      return runContextDiet(flags)
+    }
+    case 'orphan-extract': return runOrphanExtract(flags)
+    case 'token': return runToken(flags)
+    case 'help':
+    case '--help':
+    case undefined:
+      console.log(HELP)
+      return
+    default:
+      console.error(`Unknown command: ${cmd}`)
+      console.log(HELP)
+      process.exit(2)
+  }
+}
+
+// 값을 받는 플래그. 이 목록만 공백형(`--file body.json`)에서 다음 토큰을 값으로 소비한다.
+// 나머지(force·yes·batch 등)는 boolean 유지 — batch 는 orphan-extract 가 positional 폴백에 의존.
+const VALUE_FLAGS = new Set([
+  'file',
+  'endpoint',
+  'project-id',
+  'projectId',
+  'repo-path',
+  'repo-url',
+])
+
+export function parseFlags(args) {
+  const out = { positional: [] }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=')
+      if (eq !== -1) {
+        out[a.slice(2, eq)] = a.slice(eq + 1)
+        continue
+      }
+      const key = a.slice(2)
+      const next = args[i + 1]
+      if (VALUE_FLAGS.has(key) && next !== undefined && !next.startsWith('--')) {
+        out[key] = next
+        i++
+      } else {
+        out[key] = true
+      }
+    } else {
+      out.positional.push(a)
+    }
+  }
+  return out
+}

package/src/commands/cluster-todos.js

@@ -0,0 +1,74 @@
+import { execSync } from 'node:child_process'
+import { statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { loadConfig } from '../config.js'
+import { apiGet, apiPost } from '../api.js'
+
+const THROTTLE_MS = 24 * 60 * 60 * 1000
+
+function markerPath(projectId) {
+  return join(homedir(), '.rookie', `cluster-todos-${projectId}.last`)
+}
+function throttled(projectId) {
+  try {
+    return Date.now() - statSync(markerPath(projectId)).mtimeMs < THROTTLE_MS
+  } catch {
+    return false
+  }
+}
+function touchMarker(projectId) {
+  try {
+    writeFileSync(markerPath(projectId), String(Date.now()))
+  } catch {
+    /* best-effort */
+  }
+}
+
+export async function runClusterTodos(flags) {
+  const cfg = loadConfig()
+  if (!cfg) {
+    console.error('✗ 먼저 `rookie init` 을 실행하세요.')
+    process.exit(1)
+  }
+  const repoPath = process.cwd()
+  let repoUrl = ''
+  try {
+    repoUrl = execSync('git remote get-url origin', { stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim()
+  } catch {
+    /* git repo 아님 */
+  }
+
+  const q = `repo_url=${encodeURIComponent(repoUrl)}&repo_path=${encodeURIComponent(repoPath)}`
+  let ctx
+  try {
+    ctx = await apiGet(cfg.endpoint, cfg.token, `/api/rookie/context?${q}`)
+  } catch (e) {
+    console.error(`✗ context 조회 실패: ${e.message}`)
+    return
+  }
+  const project = ctx && ctx.current_project
+  if (!project || !project.id) {
+    console.log('이 프로젝트는 미link — cluster 생략')
+    return
+  }
+  if (!flags.force && throttled(project.id)) return
+
+  try {
+    const r = await apiPost(cfg.endpoint, cfg.token, '/api/rookie/todo-clusters/scan', {
+      project_id: project.id,
+    })
+    touchMarker(project.id)
+    if (r && r.ok) {
+      console.log(
+        `[cluster-todos] created ${r.created}, bumped ${r.bumped}, rejected ${r.rejected_same}, stale ${r.stale_swept}, singletons ${r.skipped_singletons}`
+      )
+    } else if (r && r.error) {
+      console.log(`[cluster-todos] skip — ${r.error}`)
+    }
+  } catch (e) {
+    console.error(`✗ cluster scan 전송 실패: ${e.message}`)
+  }
+}

package/src/commands/codex-setup.js

@@ -0,0 +1,36 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { existsSync } from 'node:fs'
+import { confirm } from '../prompt.js'
+import { loadConfig } from '../config.js'
+import { applyCodexSetup } from '../lib/deploy-artifacts.js'
+
+// Codex config.toml 에 더루키 SessionStart hook 을 동의 기반으로 등록한다(managed 블록만).
+// 명시적 Codex-only 재설정 진입점 — 내부 write 는 applyCodexSetup(3층 adapter) 공유(spec §4 item 6).
+export async function runCodexSetup(flags) {
+  const cfg = loadConfig()
+  if (!cfg?.token) {
+    console.error('✗ 먼저 `rookie login` 으로 연결하세요.')
+    process.exit(1)
+  }
+  const hookScript = join(homedir(), '.rookie', 'bin', 'session-start.sh')
+  if (!existsSync(hookScript)) {
+    console.error(`✗ hook 스크립트가 없습니다(${hookScript}). \`rookie login\` 또는 \`rookie update\` 를 먼저 실행하세요.`)
+    process.exit(1)
+  }
+  const configPath = join(homedir(), '.codex', 'config.toml')
+
+  console.log('\nCodex 설정 파일에 더루키 SessionStart hook 을 등록합니다:')
+  console.log(`  ${configPath}`)
+  console.log('  → Codex 세션 시작 시 차차 컨텍스트가 자동 주입됩니다(managed 블록만 추가, 기존 설정 보존).')
+  if (!flags.yes && !(await confirm('진행할까요?', { defaultYes: true }))) {
+    console.log('취소했습니다.')
+    return
+  }
+  const r = applyCodexSetup({ home: homedir() })
+  if (r.error === 'malformed_marker') {
+    console.error('✗ Codex config 의 더루키 marker 가 손상됐습니다(begin 만 있고 end 없음). 사용자 설정 보호를 위해 중단합니다 — config.toml 의 managed 블록을 수동 점검하세요.')
+    process.exit(1)
+  }
+  console.log('✓ 등록 완료. 새 Codex 세션부터 자동 적용됩니다.')
+}

package/src/commands/context-diet.js

@@ -0,0 +1,80 @@
+import { writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { computeReport, throttleMarkerPath, THRESHOLDS } from '../lib/context-diet.js'
+
+// spec 2026-07-10-context-diet-design.md §2.1 — 측정 5항목 + 임계 판정.
+// 주1회 throttle 은 hook(session-start.sh) 이 marker 나이로 검사하고, 여기선
+// 판정이 성공적으로 끝난 뒤에만 marker 를 기록한다(실패 세션 미기록 → 다음 재시도, codex 2차 P2).
+export async function runContextDiet(flags) {
+  const home = homedir()
+  const report = computeReport({
+    cwd: process.cwd(),
+    home,
+    usageMode: flags.force ? 'force-scan' : 'cache-or-scan',
+  })
+
+  if (report.ok) {
+    try {
+      writeFileSync(throttleMarkerPath(home), String(Date.now()))
+    } catch {
+      /* best-effort — 미기록이면 중복 권고 (누락보다 낫다, §4) */
+    }
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(report))
+    return
+  }
+
+  console.log('== 컨텍스트 다이어트 (설치 자산 proxy — 실제 주입 토큰과 다를 수 있음) ==')
+  printHuman(report)
+  if (!report.ok) process.exitCode = 1
+}
+
+function fmtNum(n) {
+  return typeof n === 'number' ? n.toLocaleString('en-US') : '?'
+}
+
+export function printHuman(report, log = console.log) {
+  const it = report.items
+  const line = (flag, text) => log(`${flag} ${text}`)
+  const mark = (item) => (item.exceeded ? '⚠️' : '✓')
+
+  if (it.claude_md_project)
+    line(
+      mark(it.claude_md_project),
+      `claude_md_project: ${fmtNum(it.claude_md_project.chars)}자 / ${fmtNum(it.claude_md_project.lines)}줄 (임계 ${fmtNum(THRESHOLDS.claude_md_project)})${it.claude_md_project.snoozed ? ' [snooze]' : ''}`
+    )
+  else line('✗', 'claude_md_project: 측정 실패')
+
+  if (it.claude_md_total)
+    line(
+      mark(it.claude_md_total),
+      `claude_md_total: ${fmtNum(it.claude_md_total.chars)}자 / ${it.claude_md_total.files}파일 (@import 포함, 임계 ${fmtNum(THRESHOLDS.claude_md_total)})${it.claude_md_total.snoozed ? ' [snooze]' : ''}`
+    )
+  else line('✗', 'claude_md_total: 측정 실패')
+
+  if (it.skills_agents_desc) {
+    line(
+      mark(it.skills_agents_desc),
+      `skills_agents_desc: ${fmtNum(it.skills_agents_desc.chars)}자 / ${it.skills_agents_desc.count}개 자산 (임계 ${fmtNum(THRESHOLDS.skills_agents_desc)})${it.skills_agents_desc.snoozed ? ' [snooze]' : ''}`
+    )
+    if (it.skills_agents_desc.parse_errors > 0)
+      log(`   frontmatter parse_error ${it.skills_agents_desc.parse_errors}건 (측정 제외분 있음)`)
+  } else line('✗', 'skills_agents_desc: 측정 실패')
+
+  if (it.rookie_self)
+    line(
+      mark(it.rookie_self),
+      `rookie_self: SKILL.md ${fmtNum(it.rookie_self.skill_chars)}자 (임계 ${fmtNum(THRESHOLDS.rookie_self_skill)}) / 주입 ${it.rookie_self.injected_chars == null ? '미기록' : fmtNum(it.rookie_self.injected_chars) + '자'}${it.rookie_self.injection_stale ? ' (stale — 판정 제외)' : ` (임계 ${fmtNum(THRESHOLDS.rookie_self_injected)})`}${it.rookie_self.snoozed ? ' [snooze]' : ''}`
+    )
+  else line('✗', 'rookie_self: 측정 실패')
+
+  if (it.unused_skills) {
+    line(
+      mark(it.unused_skills),
+      `unused_skills: ${it.unused_skills.count}개 ${it.unused_skills.window_days}일간 0회 (임계 ≥${THRESHOLDS.unused_skills_min})${it.unused_skills.usage_partial ? ' [partial 스캔 — 판정 제외]' : ''}${it.unused_skills.usage_cached ? ' [캐시]' : ''}${it.unused_skills.snoozed ? ' [snooze]' : ''}`
+    )
+    for (const name of it.unused_skills.names) log(`   - ${name}`)
+  } else line('✗', 'unused_skills: 측정 실패 (usage 캐시 없음이면 rookie context-diet --force)')
+}