claude-controller 0.1.0

package/lib/jobs.sh

@@ -0,0 +1,333 @@
+#!/usr/bin/env bash
+# ============================================================
+# 백그라운드 작업(Job) 관리 모듈
+# Session ID 기반으로 작업의 상태, 결과를 추적합니다.
+# PID는 내부 프로세스 관리 전용으로만 사용합니다.
+# ============================================================
+
+# ── 안전한 .meta 파일 파서 ─────────────────────────────────
+# source 대신 grep+sed로 필드를 추출하여 쉘 인젝션을 방지한다.
+_get_meta_field() {
+  local file="$1" key="$2"
+  [[ -f "$file" ]] || return 1
+  grep "^${key}=" "$file" 2>/dev/null | head -1 | sed "s/^${key}=//" | sed "s/^['\"]//;s/['\"]$//"
+}
+
+# .meta 파일의 모든 필드를 로컬 변수로 로드 (source 대체)
+# usage: _load_meta "$meta_file"  →  JOB_ID, STATUS, PID, PROMPT, ... 변수 설정
+_load_meta() {
+  local file="$1"
+  JOB_ID=$(_get_meta_field "$file" "JOB_ID")
+  STATUS=$(_get_meta_field "$file" "STATUS")
+  PID=$(_get_meta_field "$file" "PID")
+  PROMPT=$(_get_meta_field "$file" "PROMPT")
+  CREATED_AT=$(_get_meta_field "$file" "CREATED_AT")
+  SESSION_ID=$(_get_meta_field "$file" "SESSION_ID")
+  UUID=$(_get_meta_field "$file" "UUID")
+  CWD=$(_get_meta_field "$file" "CWD")
+  WORKTREE=$(_get_meta_field "$file" "WORKTREE")
+  REPO=$(_get_meta_field "$file" "REPO")
+}
+
+# 디스크 기반 Job 카운터 (서브쉘에서도 안전하게 동작)
+_JOB_COUNTER_FILE="${LOGS_DIR}/.job_counter"
+
+# 카운터를 원자적으로 증가시키고 새 값을 stdout에 출력
+_next_job_id() {
+  local lockfile="${_JOB_COUNTER_FILE}.lock"
+  local waited=0
+  # 스핀락 + stale lock 감지: 500회(≈5초) 대기 후 강제 해제
+  while ! mkdir "$lockfile" 2>/dev/null; do
+    sleep 0.01
+    (( waited++ )) || true
+    if [[ $waited -gt 500 ]]; then
+      rmdir "$lockfile" 2>/dev/null || rm -rf "$lockfile" 2>/dev/null || true
+      waited=0
+    fi
+  done
+  local current=0
+  [[ -f "$_JOB_COUNTER_FILE" ]] && current=$(cat "$_JOB_COUNTER_FILE")
+  local next=$(( current + 1 ))
+  echo "$next" > "$_JOB_COUNTER_FILE"
+  rmdir "$lockfile" 2>/dev/null || true
+  echo "$next"
+}
+
+# ── Job 생성 등록 ──────────────────────────────────────────
+# usage: job_register <prompt_text>
+# stdout: job_id
+job_register() {
+  local prompt="$1"
+  local job_id
+  job_id=$(_next_job_id)
+  local ts
+  ts=$(date '+%Y-%m-%d %H:%M:%S')
+
+  local meta_file="${LOGS_DIR}/job_${job_id}.meta"
+  # 프롬프트 내의 특수문자를 이스케이프하여 안전하게 저장
+  local safe_prompt
+  safe_prompt=$(printf '%s' "$prompt" | head -c 500 | sed "s/'/'\\\\''/g")
+  cat > "$meta_file" <<EOF
+JOB_ID=${job_id}
+STATUS=running
+PID=
+PROMPT='${safe_prompt}'
+CREATED_AT='${ts}'
+SESSION_ID=
+EOF
+  echo "$job_id"
+}
+
+# ── 원자적 meta 필드 갱신 (temp → rename) ─────────────────
+_meta_set_field() {
+  local meta_file="$1" key="$2" value="$3"
+  [[ -f "$meta_file" ]] || return 1
+  local tmp_file="${meta_file}.tmp.$$"
+  sed "s/^${key}=.*/${key}=${value}/" "$meta_file" > "$tmp_file" && \
+    mv -f "$tmp_file" "$meta_file"
+}
+
+# ── PID / 세션 ID 갱신 ────────────────────────────────────
+job_set_pid() {
+  local job_id="$1" pid="$2"
+  local meta_file="${LOGS_DIR}/job_${job_id}.meta"
+  _meta_set_field "$meta_file" "PID" "$pid"
+}
+
+job_set_session() {
+  local job_id="$1" session_id="$2"
+  local meta_file="${LOGS_DIR}/job_${job_id}.meta"
+  _meta_set_field "$meta_file" "SESSION_ID" "$session_id"
+}
+
+# ── 상태 변경 ──────────────────────────────────────────────
+job_mark_done() {
+  local job_id="$1"
+  local meta_file="${LOGS_DIR}/job_${job_id}.meta"
+  _meta_set_field "$meta_file" "STATUS" "done"
+}
+
+job_mark_failed() {
+  local job_id="$1"
+  local meta_file="${LOGS_DIR}/job_${job_id}.meta"
+  _meta_set_field "$meta_file" "STATUS" "failed"
+}
+
+# ── 상태 조회 ──────────────────────────────────────────────
+job_status() {
+  local job_id="$1"
+  local meta_file="${LOGS_DIR}/job_${job_id}.meta"
+  if [[ -f "$meta_file" ]]; then
+    local STATUS="" PID=""
+    STATUS=$(_get_meta_field "$meta_file" "STATUS")
+    PID=$(_get_meta_field "$meta_file" "PID")
+    # PID가 아직 살아있는지 확인 (내부 전용)
+    if [[ "$STATUS" == "running" && -n "$PID" ]]; then
+      if ! kill -0 "$PID" 2>/dev/null; then
+        job_mark_done "$job_id"
+        STATUS="done"
+      fi
+    fi
+    echo "$STATUS"
+  else
+    echo "not_found"
+  fi
+}
+
+# ── Session ID로 Job 찾기 ────────────────────────────────
+# session_id로 가장 최신 job_id를 반환한다.
+job_find_by_session() {
+  local target_sid="$1"
+  local best_jid=0 found_jid=""
+  for meta_file in "${LOGS_DIR}"/job_*.meta; do
+    [[ -f "$meta_file" ]] || continue
+    local sid
+    sid=$(_get_meta_field "$meta_file" "SESSION_ID")
+    if [[ "$sid" == "$target_sid" ]]; then
+      local jid
+      jid=$(_get_meta_field "$meta_file" "JOB_ID")
+      if [[ "$jid" -gt "$best_jid" ]] 2>/dev/null; then
+        best_jid="$jid"
+        found_jid="$jid"
+      fi
+    fi
+  done
+  if [[ -n "$found_jid" ]]; then
+    echo "$found_jid"
+    return 0
+  fi
+  return 1
+}
+
+# ── 실행 중인 Job의 Session ID 조기 추출 ────────────────
+# stream-json 출력 파일에서 session_id를 탐색하여 meta에 캐싱한다.
+job_get_session_id() {
+  local job_id="$1"
+  local meta_file="${LOGS_DIR}/job_${job_id}.meta"
+
+  # meta 파일에서 먼저 확인
+  local sid
+  sid=$(_get_meta_field "$meta_file" "SESSION_ID")
+  if [[ -n "$sid" ]]; then
+    echo "$sid"
+    return 0
+  fi
+
+  # stream 출력에서 조기 추출 시도
+  local out_file="${LOGS_DIR}/job_${job_id}.out"
+  if [[ -f "$out_file" ]]; then
+    sid=$(grep -m1 '"session_id"' "$out_file" 2>/dev/null | head -1 | jq -r '.session_id // empty' 2>/dev/null)
+    if [[ -n "$sid" ]]; then
+      job_set_session "$job_id" "$sid"
+      echo "$sid"
+      return 0
+    fi
+  fi
+  return 1
+}
+
+# ── 전체 작업 목록 ─────────────────────────────────────────
+jobs_list() {
+  local meta_files=("${LOGS_DIR}"/job_*.meta)
+  if [[ ! -f "${meta_files[0]}" ]]; then
+    echo "  (백그라운드 작업 없음)"
+    return
+  fi
+
+  printf "  %-4s  %-9s  %-10s  %-19s  %s\n" "ID" "STATUS" "SESSION" "CREATED" "PROMPT"
+  printf "  %-4s  %-9s  %-10s  %-19s  %s\n" "----" "---------" "----------" "-------------------" "--------------------"
+
+  # 최근 작업이 위로 오도록 JOB_ID 내림차순 정렬
+  local sorted_files
+  IFS=$'\n' sorted_files=($(
+    for f in "${meta_files[@]}"; do
+      [[ -f "$f" ]] || continue
+      local num="${f##*job_}"
+      num="${num%.meta}"
+      echo "${num} ${f}"
+    done | sort -t' ' -k1 -rn | cut -d' ' -f2-
+  ))
+  unset IFS
+
+  for meta_file in "${sorted_files[@]}"; do
+    [[ -f "$meta_file" ]] || continue
+    (
+      local JOB_ID="" STATUS="" PID="" PROMPT="" CREATED_AT="" SESSION_ID=""
+      _load_meta "$meta_file"
+      # 프로세스 생존 확인 (내부 전용)
+      if [[ "$STATUS" == "running" && -n "$PID" ]]; then
+        if ! kill -0 "$PID" 2>/dev/null; then
+          STATUS="done"
+        fi
+      fi
+      # Session ID가 없으면 stream에서 조기 추출 시도
+      if [[ -z "$SESSION_ID" ]]; then
+        SESSION_ID=$(job_get_session_id "$JOB_ID" 2>/dev/null) || true
+      fi
+      local short_sid="${SESSION_ID:0:8}"
+      [[ ${#SESSION_ID} -gt 8 ]] && short_sid="${short_sid}.."
+      local short_prompt="${PROMPT:0:40}"
+      [[ ${#PROMPT} -gt 40 ]] && short_prompt="${short_prompt}..."
+      printf "  %-4s  %-9s  %-10s  %-19s  %s\n" \
+        "$JOB_ID" "$STATUS" "${short_sid:-"-"}" "$CREATED_AT" "$short_prompt"
+    )
+  done
+}
+
+# ── 작업 결과 보기 ─────────────────────────────────────────
+job_result() {
+  local job_id="$1"
+  local out_file="${LOGS_DIR}/job_${job_id}.out"
+  local meta_file="${LOGS_DIR}/job_${job_id}.meta"
+
+  if [[ ! -f "$meta_file" ]]; then
+    echo "  [오류] Job #${job_id}를 찾을 수 없습니다."
+    return 1
+  fi
+
+  local status
+  status=$(job_status "$job_id")
+
+  if [[ "$status" == "running" ]]; then
+    echo "  [진행 중] Job #${job_id}가 아직 실행 중입니다..."
+    return 0
+  fi
+
+  if [[ -f "$out_file" ]]; then
+    # JSON 출력에서 result 텍스트만 추출 시도
+    local result_text
+    result_text=$(jq -r '.result // empty' "$out_file" 2>/dev/null)
+    if [[ -n "$result_text" ]]; then
+      echo "$result_text"
+    else
+      cat "$out_file"
+    fi
+  else
+    echo "  [오류] Job #${job_id}의 출력 파일이 없습니다."
+    return 1
+  fi
+}
+
+# ── 작업의 세션 ID 가져오기 ────────────────────────────────
+job_session_id() {
+  local job_id="$1"
+  local out_file="${LOGS_DIR}/job_${job_id}.out"
+  if [[ -f "$out_file" ]]; then
+    jq -r '.session_id // empty' "$out_file" 2>/dev/null
+  fi
+}
+
+# ── 작업 강제 종료 ─────────────────────────────────────────
+# job_id 또는 session_id로 호출 가능.
+# session_id(UUID 형태)가 입력되면 자동으로 job_id로 변환한다.
+job_kill() {
+  local identifier="$1"
+  local job_id="$identifier"
+
+  # UUID 형태(하이픈 포함 36자)이면 session_id로 간주
+  if [[ "$identifier" =~ ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ ]]; then
+    job_id=$(job_find_by_session "$identifier")
+    if [[ -z "$job_id" ]]; then
+      echo "  [오류] Session ID '${identifier:0:8}...'에 해당하는 작업을 찾을 수 없습니다."
+      return 1
+    fi
+  fi
+
+  local meta_file="${LOGS_DIR}/job_${job_id}.meta"
+
+  if [[ ! -f "$meta_file" ]]; then
+    echo "  [오류] Job #${job_id}를 찾을 수 없습니다."
+    return 1
+  fi
+
+  local STATUS="" PID="" SESSION_ID=""
+  _load_meta "$meta_file"
+  local sid_label="${SESSION_ID:+${SESSION_ID:0:8}..}"
+
+  if [[ "$STATUS" != "running" ]]; then
+    echo "  Job #${job_id}${sid_label:+ (session: $sid_label)}는 이미 종료되었습니다. (status: $STATUS)"
+    return 0
+  fi
+
+  if [[ -n "$PID" ]] && kill -0 "$PID" 2>/dev/null; then
+    kill "$PID" 2>/dev/null
+    sleep 0.5
+    kill -0 "$PID" 2>/dev/null && kill -9 "$PID" 2>/dev/null
+    job_mark_failed "$job_id"
+    echo "  Job #${job_id}${sid_label:+ (session: $sid_label)} 종료됨."
+  else
+    job_mark_done "$job_id"
+    echo "  Job #${job_id}${sid_label:+ (session: $sid_label)}는 이미 종료된 프로세스입니다."
+  fi
+}
+
+# ── 로그 파일 정리 ─────────────────────────────────────────
+jobs_clean() {
+  local count=0
+  for f in "${LOGS_DIR}"/job_*.meta "${LOGS_DIR}"/job_*.out "${LOGS_DIR}"/job_*.ext_id; do
+    if [[ -f "$f" ]]; then rm -f "$f"; (( count++ )) || true; fi
+  done
+  # 카운터 초기화
+  echo "0" > "$_JOB_COUNTER_FILE"
+  echo "  ${count}개의 작업 파일 정리 완료."
+}

package/lib/session.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# ============================================================
+# 세션 관리 모듈
+# claude -p 의 세션 ID 를 추적하여 대화를 이어갈 수 있게 합니다.
+# ============================================================
+
+# 현재 활성 세션 ID (가장 최근 포그라운드 실행의 세션)
+_CURRENT_SESSION_ID=""
+
+# ── 세션 저장 ──────────────────────────────────────────────
+session_save() {
+  local session_id="$1"
+  local prompt="$2"
+  local ts
+  ts=$(date '+%Y-%m-%d %H:%M:%S')
+
+  if [[ -n "$session_id" ]]; then
+    _CURRENT_SESSION_ID="$session_id"
+    echo "${ts}|${session_id}|${prompt:0:200}" >> "${SESSIONS_DIR}/history.log"
+  fi
+}
+
+# ── 현재 세션 ID 반환 ─────────────────────────────────────
+session_current() {
+  echo "$_CURRENT_SESSION_ID"
+}
+
+# ── 세션 목록 보기 ─────────────────────────────────────────
+session_list() {
+  local history_file="${SESSIONS_DIR}/history.log"
+  if [[ ! -f "$history_file" ]]; then
+    echo "  (세션 기록 없음)"
+    return
+  fi
+
+  printf "  %-19s  %-40s  %s\n" "TIME" "SESSION_ID" "PROMPT"
+  printf "  %-19s  %-40s  %s\n" "-------------------" "----------------------------------------" "--------------------"
+
+  tail -20 "$history_file" | while IFS='|' read -r ts sid prompt; do
+    local short_prompt="${prompt:0:40}"
+    [[ ${#prompt} -gt 40 ]] && short_prompt="${short_prompt}..."
+    printf "  %-19s  %-40s  %s\n" "$ts" "$sid" "$short_prompt"
+  done
+}
+
+# ── 특정 세션으로 전환 ─────────────────────────────────────
+session_switch() {
+  local session_id="$1"
+  if [[ -n "$session_id" ]]; then
+    _CURRENT_SESSION_ID="$session_id"
+    echo "  세션 전환됨: $session_id"
+  else
+    echo "  [오류] 세션 ID를 지정해주세요."
+  fi
+}
+
+# ── claude -p 에 세션 관련 플래그 생성 ─────────────────────
+# --continue: 가장 최근 대화 이어가기
+# --resume <id>: 특정 세션 이어가기
+session_build_flags() {
+  local mode="$1"  # "continue" | "resume" | ""
+  local flags=()
+
+  case "$mode" in
+    continue)
+      flags+=(--continue)
+      ;;
+    resume)
+      if [[ -n "$_CURRENT_SESSION_ID" ]]; then
+        flags+=(--resume "$_CURRENT_SESSION_ID")
+      else
+        echo "  [경고] 이어갈 세션이 없습니다. 새 세션으로 실행합니다." >&2
+      fi
+      ;;
+  esac
+
+  echo "${flags[@]+"${flags[@]}"}"
+}

package/lib/worktree.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# ============================================================
+# Git Worktree 관리 모듈
+# 각 작업을 독립된 git worktree에서 실행하여 격리성을 보장합니다.
+# ============================================================
+
+# ── worktree 생성 ──────────────────────────────────────────
+# usage: worktree_create <job_id> [repo_path]
+# stdout: worktree 경로
+worktree_create() {
+  local job_id="$1"
+  local repo="${2:-$TARGET_REPO}"
+
+  if [[ -z "$repo" ]]; then
+    echo "[오류] TARGET_REPO가 설정되지 않았습니다." >&2
+    return 1
+  fi
+
+  if [[ ! -d "$repo/.git" ]]; then
+    echo "[오류] git 저장소가 아닙니다: $repo" >&2
+    return 1
+  fi
+
+  mkdir -p "$WORKTREES_DIR"
+
+  local branch="controller/job-${job_id}"
+  local wt_path="${WORKTREES_DIR}/${branch//\//_}"
+
+  # 기존 브랜치/워크트리 정리
+  git -C "$repo" worktree remove "$wt_path" --force 2>/dev/null || true
+  git -C "$repo" branch -D "$branch" 2>/dev/null || true
+
+  # base branch에서 새 워크트리 생성
+  local base="${BASE_BRANCH:-main}"
+  git -C "$repo" fetch origin "$base" 2>/dev/null || true
+
+  if git -C "$repo" worktree add "$wt_path" -b "$branch" "origin/${base}" 2>/dev/null; then
+    echo "$wt_path"
+    return 0
+  fi
+
+  # fallback: 로컬 base branch
+  if git -C "$repo" worktree add "$wt_path" -b "$branch" "$base" 2>/dev/null; then
+    echo "$wt_path"
+    return 0
+  fi
+
+  echo "[오류] 워크트리 생성 실패: $wt_path" >&2
+  return 1
+}
+
+# ── worktree 삭제 ──────────────────────────────────────────
+# usage: worktree_remove <job_id> [repo_path]
+worktree_remove() {
+  local job_id="$1"
+  local repo="${2:-$TARGET_REPO}"
+
+  if [[ -z "$repo" ]]; then
+    return 1
+  fi
+
+  local branch="controller/job-${job_id}"
+  local wt_path="${WORKTREES_DIR}/${branch//\//_}"
+
+  if [[ -d "$wt_path" ]]; then
+    git -C "$repo" worktree remove "$wt_path" --force 2>/dev/null || true
+  fi
+
+  git -C "$repo" branch -D "$branch" 2>/dev/null || true
+}
+
+# ── 작업의 worktree 경로 조회 ─────────────────────────────
+# usage: worktree_path_for_job <job_id>
+worktree_path_for_job() {
+  local job_id="$1"
+  local meta_file="${LOGS_DIR}/job_${job_id}.meta"
+
+  if [[ -f "$meta_file" ]]; then
+    local WORKTREE=""
+    WORKTREE=$(_get_meta_field "$meta_file" "WORKTREE")
+    echo "${WORKTREE:-}"
+  fi
+}
+
+# ── 전체 worktree 목록 ─────────────────────────────────────
+worktree_list() {
+  local repo="${1:-$TARGET_REPO}"
+
+  if [[ -z "$repo" || ! -d "$repo/.git" ]]; then
+    echo "  (TARGET_REPO 미설정 또는 git 저장소 아님)"
+    return
+  fi
+
+  git -C "$repo" worktree list 2>/dev/null | while read -r line; do
+    echo "  $line"
+  done
+}
+
+# ── 모든 controller worktree 정리 ──────────────────────────
+worktree_clean_all() {
+  local repo="${1:-$TARGET_REPO}"
+
+  if [[ -z "$repo" ]]; then
+    echo "  [오류] TARGET_REPO 미설정"
+    return 1
+  fi
+
+  local count=0
+  for meta_file in "${LOGS_DIR}"/job_*.meta; do
+    [[ -f "$meta_file" ]] || continue
+    local JOB_ID="" WORKTREE=""
+    JOB_ID=$(_get_meta_field "$meta_file" "JOB_ID")
+    WORKTREE=$(_get_meta_field "$meta_file" "WORKTREE")
+    if [[ -n "$WORKTREE" && -d "$WORKTREE" ]]; then
+      worktree_remove "$JOB_ID" "$repo"
+      (( count++ )) || true
+    fi
+  done
+
+  git -C "$repo" worktree prune 2>/dev/null || true
+  echo "  ${count}개 워크트리 정리 완료."
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "claude-controller",
+  "version": "0.1.0",
+  "description": "Claude Code headless daemon controller — FIFO-based async task dispatch, Git Worktree isolation, auto-checkpointing, and a web dashboard",
+  "license": "MIT",
+  "author": "choiwon",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "headless",
+    "controller",
+    "orchestration",
+    "daemon",
+    "worktree",
+    "checkpoint"
+  ],
+  "bin": {
+    "claude-controller": "./bin/controller",
+    "claude-send": "./bin/send",
+    "claude-start": "./bin/start",
+    "claude-sh": "./bin/claude-sh"
+  },
+  "files": [
+    "bin/controller",
+    "bin/send",
+    "bin/start",
+    "bin/claude-sh",
+    "bin/app-launcher.sh",
+    "bin/native-app.py",
+    "lib/",
+    "service/controller.sh",
+    "web/*.py",
+    "web/static/index.html",
+    "web/static/app.js",
+    "web/static/styles.css",
+    "config.sh",
+    "README.md",
+    "LICENSE",
+    "postinstall.sh"
+  ],
+  "scripts": {
+    "postinstall": "bash postinstall.sh",
+    "start": "bash bin/start",
+    "server": "python3 bin/native-app.py",
+    "service:start": "bash bin/controller start",
+    "service:stop": "bash bin/controller stop",
+    "service:status": "bash bin/controller status",
+    "send": "bash bin/send"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}

package/postinstall.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# ============================================================
+# postinstall — npm install 후 런타임 디렉토리 및 권한 설정
+# ============================================================
+set -euo pipefail
+
+CONTROLLER_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# 런타임 디렉토리 생성 (패키지에 포함되지 않는 것들)
+for dir in logs sessions data queue worktrees uploads certs; do
+  mkdir -p "${CONTROLLER_DIR}/${dir}"
+done
+
+# bin 스크립트에 실행 권한 부여
+chmod +x "${CONTROLLER_DIR}/bin/"* 2>/dev/null || true
+chmod +x "${CONTROLLER_DIR}/service/"*.sh 2>/dev/null || true
+
+echo ""
+echo "  claude-controller 설치 완료!"
+echo ""
+echo "  사용법:"
+echo "    claude-controller start     서비스 시작"
+echo "    claude-controller stop      서비스 중지"
+echo "    claude-controller status    상태 확인"
+echo "    claude-send \"프롬프트\"       작업 전송"
+echo "    claude-start                서비스 + TUI 실행"
+echo ""
+echo "  웹 대시보드:"
+echo "    npm run server              웹 서버 시작 (localhost:8420)"
+echo ""