@tuzi-ince/hi-loop 0.4.3 → 0.6.0

package/src/mcp-server.js

@@ -4,6 +4,7 @@
  * ⚠️ stdout 은 MCP 프로토콜 채널이다. 로그는 반드시 stderr 로만 낸다 (FR-4.2).
  */
 import { runLoop } from './loop.js';
+import { runDocSync } from './docsync.js';
 import { loadState, saveState, statePathFor, summarizeState, resetState } from './state.js';
 import { applyAnswer, formatAsk } from './ask.js';
 import { rollbackTo } from './checkpoint.js';
@@ -15,22 +16,32 @@ const log = (line) => process.stderr.write(`[hi-loop-mcp] ${line}\n`);
 const text = (t) => ({ content: [{ type: 'text', text: t }] });
 const fail = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
 
-/**
- * MCP 경로의 기본 작업 디렉터리.
- *
- * CLI 는 `process.cwd()` 만 본다 — 터미널에서 cd 한 곳이 곧 사용자의 명시 의도이기 때문이다.
- * 그러나 MCP 는 호스트(클로드코드/커서)가 서버를 띄우는 경로이고, "어느 프로젝트인가"의
- * 정답은 호스트가 주입하는 `CLAUDE_PROJECT_DIR` 다. 서버 프로세스의 cwd 가 프로젝트 루트와
- * 다른 호스트에서도 올바른 루트를 잡으려면 이 env 를 먼저 본다. 호출자가 cwd 를 명시하면
- * 그것이 최우선이다(각 핸들러의 인자가 이 기본값을 덮는다).
- */
+// MCP 경로의 기본 cwd: 호스트가 주입하는 CLAUDE_PROJECT_DIR 가 "어느 프로젝트인가"의 정답이다
+// (서버 cwd 가 프로젝트 루트와 다를 수 있으므로). 호출자가 cwd 를 명시하면 그것이 최우선.
 const defaultCwd = () => process.env.CLAUDE_PROJECT_DIR || process.cwd();
 
+// MCP progress: 로그 라인마다 진행 알림 전송(progressToken 준 경우만; 없으면 stderr 로만).
+function makeProgressLogger(extra) {
+  const token = extra?._meta?.progressToken;
+  let ticks = 0;
+  return (line) => {
+    log(line);
+    if (token != null && typeof extra?.sendNotification === 'function') {
+      extra
+        .sendNotification({
+          method: 'notifications/progress',
+          params: { progressToken: token, progress: (ticks += 1), message: String(line).replace(/^\[hi-loop[^\]]*\]\s*/, '').slice(0, 200) },
+        })
+        .catch(() => {});
+    }
+  };
+}
+
 /** 도구 구현 (SDK 없이도 단위 테스트 가능하도록 분리) */
 export const tools = {
   hiloop_run: {
     description:
-      '목표(goal)를 받아 PLAN→DO→CHECK→HEAL 자가 치유 루프를 실행한다. spec/테스트를 먼저 만들고, 테스트가 통과할 때까지 최대 maxLoops회 반복한다. full=true 면 발굴·설계리뷰·코드리뷰까지 도는 전체 라이프사이클로 실행한다. ship/watch 를 주면 배포와 헬스체크까지 진행한다.',
+      '목표(goal)를 받아 PLAN→DO→CHECK→HEAL 자가 치유 루프를 실행한다. spec/테스트를 먼저 만들고, 테스트가 통과할 때까지 최대 maxLoops회 반복한다. full=true 면 발굴·설계리뷰·코드리뷰까지 도는 전체 라이프사이클로 실행한다. ship/watch 를 주면 배포와 헬스체크까지 진행한다. step=true 면 매 단위 작업 후 제어를 돌려줘(status:continue) LLM 이 진행을 보이며 이어 호출한다 — 대화형·긴 작업 권장.',
     handler: async ({
       goal,
       testCommand = 'npm test',
@@ -40,6 +51,7 @@ export const tools = {
       ship,
       watch,
       stopAfter,
+      step,
       spec,
       reconcile,
       reconcileSpec,
@@ -48,26 +60,10 @@ export const tools = {
       cwd = defaultCwd(),
     }, extra) => {
       if (!goal) return fail('goal 은 필수입니다.');
-      // 루프를 돌리기 전에 에이전트가 실행 가능한지 확인한다 — 미설치/실행불가면
-      // 회차를 태우지 않고 여기서 행동지침을 돌려준다(호스트 LLM 이 사용자에게 전달).
+      // 루프 전에 에이전트 실행 가능 여부 확인 — 미설치/불가면 회차를 안 태우고 행동지침을 돌려준다.
       const pre = await preflightAgent();
       if (!pre.ok) return fail(pre.message);
-      // MCP progress: 루프 로그가 나올 때마다 클라이언트에 진행 알림을 보낸다. 이게 없으면
-      // 긴 루프(e2e 등)가 조용히 유휴 타임아웃(기본 30분)에 걸려 클라이언트 호출만 끊긴다.
-      // 클라이언트가 progressToken 을 준 경우에만 보낸다(안 주면 조용히 stderr 로만 로그).
-      const progressToken = extra?._meta?.progressToken;
-      let ticks = 0;
-      const runLogger = (line) => {
-        log(line);
-        if (progressToken != null && typeof extra?.sendNotification === 'function') {
-          extra
-            .sendNotification({
-              method: 'notifications/progress',
-              params: { progressToken, progress: (ticks += 1), message: String(line).replace(/^\[hi-loop[^\]]*\]\s*/, '').slice(0, 200) },
-            })
-            .catch(() => {}); // 알림 실패는 루프에 영향 없음
-        }
-      };
+      const runLogger = makeProgressLogger(extra);
       const result = await runLoop({
         goal,
         testCommand,
@@ -77,26 +73,31 @@ export const tools = {
         shipCommand: ship || null,
         watchCommand: watch || null,
         stopAfter: stopAfter ? String(stopAfter).toUpperCase() : null,
+        step: Boolean(step),
         specPath: spec || null,
         reconcile: reconcile === undefined ? null : Boolean(reconcile),
         reconcileSpec: reconcileSpec || null,
-        // 조건부 검사(--check/--when 의 MCP 노출): 주면 testCommand 대신 이 배열이 판정 기준이 된다.
-        // when 글롭에 맞는 파일이 바뀐 회차에만 그 검사를 돌린다(UI 변경 회차에만 e2e 등).
+        // 조건부 검사(MCP 노출): 주면 testCommand 대신 이 배열이 기준. when 글롭에 맞는 파일이 바뀐 회차만.
         checks: Array.isArray(checks) && checks.length ? checks : null,
         onFail: onFail || 'heal',
         cwd,
         logger: runLogger,
       });
 
-      // 사람이 골라야 하는 지점에서 멈췄다. 호스트 LLM 이 이 질문을 사용자에게 그대로
-      // 제시하고 hiloop_answer 로 답을 돌려주면 재개된다 — MCP 의 단일 요청/응답
-      // 제약과 충돌하지 않는 유일한 방법이다.
+      // 사람이 골라야 하는 지점에서 멈췄다. 질문을 사용자에게 제시하고 hiloop_answer 로 답하면 재개.
       if (result.status === 'awaiting') {
         return text(
           `⏸ 사용자의 선택이 필요합니다. 아래 질문을 그대로 사용자에게 제시하고, 답을 받아 hiloop_answer 를 호출하세요.\n\n${formatAsk(result.ask)}\n\n(hiloop_answer 인자: choice="${(result.ask.options ?? []).map((o) => o.key).join('" 또는 "')}", 필요하면 note)`,
         );
       }
 
+      // FR-24 스텝 모드: 한 단위만 돌고 돌아왔다. 진행을 알리고 같은 goal 로 재호출해 이어간다.
+      if (result.status === 'continue') {
+        return text(
+          `⏭ 스텝 완료 (${result.phase ?? result.next}) — ${result.iterations}회차까지 진행. 아직 미완이니 같은 goal 로 hiloop_run(step:true)을 다시 호출해 이어가세요.\n\n${summarizeState(result.state)}`,
+        );
+      }
+
       const head =
         result.status === 'passed' ? '✅ 통과' : result.status === 'stopped' ? `⏹ ${result.stoppedAt} 까지 진행 후 정지` : '❌ 실패';
       // 통과 시 Gaps 를 붙인다 — 에이전트가 도구로 이 결과를 받을 때 false green 을
@@ -161,6 +162,20 @@ export const tools = {
       return text(report.lines.join('\n'));
     },
   },
+  hiloop_docsync: {
+    description:
+      '소스 변경(git diff)을 읽어 관련 문서(README·docs/*, docs/DESIGN.md 제외)를 소스에 맞춰 갱신하는 단발 패스. 테스트 루프가 아니라 짧게 끝난다(진행 알림 지원). 문서 외 파일이 바뀌면 stray 로 보고한다. 소스 변경 후 문서↔소스 일치를 맞출 때 쓴다.',
+    handler: async ({ cwd = defaultCwd() } = {}, extra) => {
+      const pre = await preflightAgent();
+      if (!pre.ok) return fail(pre.message);
+      const res = await runDocSync({ cwd, logger: makeProgressLogger(extra) });
+      if (!res.ok) return fail(res.reason);
+      const head = res.changed.length ? `✅ 문서 ${res.changed.length}개 갱신` : `· ${res.note || '갱신할 문서 변경 없음'}`;
+      const list = res.changed.length ? `\n갱신: ${res.changed.join(', ')}` : '';
+      const stray = res.stray?.length ? `\n⚠️ 문서 외 파일 변경(검토 요망): ${res.stray.join(', ')}` : '';
+      return text(`${head}${list}${stray}${res.note ? `\n\n${res.note}` : ''}`);
+    },
+  },
 };
 
 /** 예외를 isError 응답으로 감싼다 (FR-4.4). extra(progress·signal)를 핸들러에 그대로 넘긴다. */
@@ -206,39 +221,17 @@ export async function startMcpServer({ version = '0.1.0' } = {}) {
         goal: z.string().describe('달성할 요구사항'),
         testCommand: z.string().optional().describe('검증 명령 (기본 "npm test")'),
         maxLoops: z.number().int().min(1).max(50).optional().describe('최대 루프 횟수 (기본 10)'),
-        onFail: z
-          .enum(['heal', 'ask', 'stop'])
-          .optional()
-          .describe('CHECK 실패/불능 시 처리. heal(기본)=maxLoops 안에서 자동 치유 / ask=사람에게 재시도·종료를 물음(awaiting 반환 → hiloop_answer 로 답하고 재호출) / stop=즉시 종료. 대화형에선 ask 권장'),
+        onFail: z.enum(['heal', 'ask', 'stop']).optional().describe('CHECK 실패/불능 시. heal(기본)=maxLoops 안 자동 치유 / ask=사람에게 재시도·종료를 물음(awaiting→hiloop_answer 로 답하고 재호출) / stop=즉시 종료. 대화형엔 ask 권장'),
+        step: z.boolean().optional().describe('스텝 모드. 매 단위 작업(BUILD 회차·각 stage) 후 status:"continue" 로 돌려준다 — 진행이 콘솔에 보이고 콜당 시간이 짧아 타임아웃이 없다. "⏭ 스텝 완료" 응답이 오면 같은 goal 로 다시 호출해 이어간다(✅/❌/⏸ 까지). 대화형·긴 작업에 권장'),
         verifySpec: z.boolean().optional().describe('통과 시 별도 검증자로 스펙 대비 구현을 심판 (하향 전용, 비용 증가)'),
         full: z.boolean().optional().describe('전체 라이프사이클(발굴·설계리뷰·코드리뷰)까지 실행 (비용 증가)'),
         ship: z.string().optional().describe('배포 명령. 주면 테스트 통과 후 실행하고 exit code 로 판정한다 (실행 전 사용자 확인)'),
         watch: z.string().optional().describe('배포 후 헬스체크 명령. 일정 시간 연속 통과해야 성공이다'),
-        stopAfter: z
-          .enum(['DISCOVER', 'PLAN', 'BUILD', 'CODE_REVIEW', 'SHIP', 'WATCH'])
-          .optional()
-          .describe('이 단계까지만 진행하고 멈춘다'),
-        spec: z
-          .string()
-          .optional()
-          .describe('스펙 오라클을 이 파일로 고정한다(예: docs/DESIGN.md). 사람이 관리하는 표준 문서를 여러 요청이 공유하는 오라클로 삼아 문서↔소스 drift 를 막는다. 이미 내용이 있으면 PLAN 이 덮어쓰지 않는다.'),
-        reconcile: z
-          .boolean()
-          .optional()
-          .describe('문서 정합 게이트. 기존 표준 문서와 이 요청이 모순되면 조용히 포크하지 않고 사람에게 묻는다(고정/분기/중단). full=true 또는 reconcileSpec 지정 시 자동 켜짐.'),
-        reconcileSpec: z
-          .string()
-          .optional()
-          .describe('정합 게이트가 대조할 표준 문서 경로(기본 docs/DESIGN.md). 예: docs/DESIGN.md. 지정하면 게이트가 켜진다.'),
-        checks: z
-          .array(z.object({ cmd: z.string(), when: z.string().optional() }))
-          .optional()
-          .describe(
-            '조건부 판정 검사. 주면 testCommand 대신 이 배열이 판정 기준이 된다(첫 항목에 기본 테스트를 넣을 것). ' +
-              'when 글롭(예: "src/**/*.tsx")이 있으면 그 경로가 바뀐 회차에만 그 검사를 돌린다 — ' +
-              '"UI 를 고친 회차에만 e2e" 를 엔진이 강제하는 용도. e2e 는 셸 명령이어야 한다(예: {cmd:"npx playwright test", when:"src/**/*.tsx"}). ' +
-              'short-circuit 하지 않아 유닛이 깨져도 e2e 결과를 같은 회차에 함께 본다.',
-          ),
+        stopAfter: z.enum(['DISCOVER', 'PLAN', 'BUILD', 'CODE_REVIEW', 'SHIP', 'WATCH']).optional().describe('이 단계까지만 진행하고 멈춘다'),
+        spec: z.string().optional().describe('스펙 오라클을 이 파일로 고정(예: docs/DESIGN.md). 사람이 관리하는 표준 문서를 여러 요청이 공유하는 오라클로 삼아 drift 를 막는다. 내용이 있으면 PLAN 이 덮어쓰지 않는다.'),
+        reconcile: z.boolean().optional().describe('문서 정합 게이트. 기존 표준 문서와 이 요청이 모순되면 포크 전에 사람에게 묻는다(고정/분기/중단). full=true 또는 reconcileSpec 지정 시 자동 켜짐.'),
+        reconcileSpec: z.string().optional().describe('정합 게이트가 대조할 표준 문서 경로(기본 docs/DESIGN.md). 지정하면 게이트가 켜진다.'),
+        checks: z.array(z.object({ cmd: z.string(), when: z.string().optional() })).optional().describe('조건부 판정 검사. 주면 testCommand 대신 이 배열이 기준(첫 항목에 기본 테스트). when 글롭(예: "src/**/*.tsx")이 있으면 그 경로가 바뀐 회차에만 그 검사를 돌린다 — "UI 고친 회차에만 e2e" 를 엔진이 강제. e2e 는 셸 명령(예: {cmd:"npx playwright test", when:"src/**/*.tsx"}). short-circuit 안 함.'),
         cwd: cwdSchema,
       },
     },
@@ -294,6 +287,12 @@ export async function startMcpServer({ version = '0.1.0' } = {}) {
     wrap(tools.hiloop_setup.handler),
   );
 
+  server.registerTool(
+    'hiloop_docsync',
+    { description: tools.hiloop_docsync.description, inputSchema: { cwd: cwdSchema } },
+    wrap(tools.hiloop_docsync.handler),
+  );
+
   await server.connect(new StdioServerTransport());
   log('stdio 전송으로 MCP 서버가 기동했습니다.');
   return server;

package/src/outcome.js

@@ -72,5 +72,19 @@ export function makeOutcome({ getState, setState, statePath, cwd, logger, notify
     return { status: 'awaiting', iterations: state.iteration, state: saved, ask: state.ask };
   };
 
-  return { finish, stopResult, pauseResult, setState };
+  /**
+   * 스텝 모드(FR-24) — 한 단위 작업을 끝내고 제어를 호출자(LLM)에게 돌려준다. 실패가 아니다.
+   * 상태는 그대로 저장되어 다음 hiloop_run 호출이 resume 경로로 정확히 이어간다.
+   * 통과 판정을 여기서 하지 않으므로 checkVerdictBinding(false green 게이트)을 우회하지 않는다
+   * — 진짜 통과는 여전히 finish('passed') 한 곳만 지난다.
+   */
+  const stepResult = ({ next, phase } = {}) => {
+    const state = getState();
+    state.status = 'stepping';
+    const saved = saveState(statePath, state);
+    logger(`[hi-loop] ⏭ 한 스텝 진행 (${phase ?? saved.phase ?? saved.stage}). 이어가려면 hiloop_run 을 다시 호출하세요.`);
+    return { status: 'continue', iterations: saved.iteration, state: saved, next: next ?? saved.stage, phase: phase ?? saved.phase };
+  };
+
+  return { finish, stopResult, pauseResult, stepResult, setState };
 }

package/src/prompts.js

@@ -268,3 +268,30 @@ ${truncate(String(diffText ?? '(변경 없음)'), 10000)}
 ## 출력 (반드시 이 JSON 한 줄로만)
 {"verdict": "pass" 또는 "reject", "findings": [{"severity": "high|medium|low", "text": "무엇이 어떤 입력에서 어떻게 깨지는가"}]}`;
 }
+
+/**
+ * DOC-SYNC (FR-25). 소스 변경(diff)을 문서에 반영하는 단발 패스. 테스트 루프가 아니다.
+ * 사람이 관리하는 표준 문서(docs/DESIGN.md)는 오라클이라 **절대 건드리지 않는다**.
+ * 소스에 없는 내용을 지어내면 그게 곧 환각이므로, diff 로 확인되는 것만 반영한다.
+ */
+export function docSyncPrompt({ diffText, docTargets } = {}) {
+  const targets = Array.isArray(docTargets) ? docTargets : [];
+  return `지금은 DOC-SYNC 단계다. 아래 **소스 변경(git diff)**을 읽고, 그 변경에 맞춰 **문서만** 갱신하라.
+
+## 소스 변경 (git diff)
+\`\`\`diff
+${truncate(String(diffText ?? '(변경 없음)'), 12000)}
+\`\`\`
+
+## 갱신 대상 문서 (이 파일들만 수정)
+${targets.length ? targets.map((p) => `- ${p}`).join('\n') : '- README.md\n- docs/*.md (docs/DESIGN.md 제외)'}
+
+## 규칙
+- **문서만 고쳐라.** 소스 코드·테스트(\`src/\`, \`bin/\`, \`tests/\`, \`*.js\`)는 절대 건드리지 마라.
+- **\`docs/DESIGN.md\`(및 소문자 design.md)는 절대 수정하지 마라** — 사람이 관리하는 표준 오라클이다.
+- diff 로 **확인되는 변경만** 반영하라(새 플래그·인자·동작·API·기본값). diff 에 없는 내용을 지어내지 마라.
+- 새 기능이면 해당 문서 관례대로 반영하라(예: SPEC 의 FR 번호 규칙, README 의 사용법·표, guide 의 절).
+- 변경이 문서와 무관하면(내부 리팩터 등) 아무것도 바꾸지 말고 그 사실을 밝혀라.
+
+작업을 마치면 **어떤 문서의 무엇을 왜 고쳤는지** 5줄 이내로 요약해 출력하라.`;
+}

package/src/runners.js

@@ -74,13 +74,15 @@ export function buildAgentArgs({ prompt, sessionId, extraArgs = [], permissionMo
  */
 export function makeAgentRunner({
   command = process.env.HILOOP_AGENT_CMD || 'claude',
+  provider = process.env.HILOOP_AGENT_PROVIDER,
   extraArgs = (process.env.HILOOP_AGENT_ARGS || '').split(' ').filter(Boolean),
   permissionMode = process.env.HILOOP_PERMISSION_MODE || DEFAULT_PERMISSION_MODE,
   timeoutMs = envMs('HILOOP_AGENT_TIMEOUT_MS', 30 * 60 * 1000),
 } = {}) {
+  const adapter = getAgentAdapter(provider);
   return ({ prompt, sessionId, cwd }) =>
     new Promise((resolve, reject) => {
-      const args = buildAgentArgs({ prompt, sessionId, extraArgs, permissionMode });
+      const args = adapter.buildArgs({ prompt, sessionId, extraArgs, permissionMode });
 
       const child = spawn(command, args, { cwd, env: process.env });
       let stdout = '';
@@ -133,3 +135,29 @@ export function parseAgentOutput(stdout, fallbackSessionId = null) {
     return { text: stdout, sessionId: fallbackSessionId, costUsd: 0 };
   }
 }
+
+/**
+ * 에이전트 프로바이더 어댑터 (FR-23): claude 외의 CLI 도 루프의 일꾼으로 쓰게,
+ * 인자 구성과 출력 파싱을 프로바이더별로 분리한다. HILOOP_AGENT_PROVIDER 로 고른다.
+ *  - claude(기본): `-p <prompt> --output-format json [--resume sid] [--permission-mode]`,
+ *    result/session_id/total_cost_usd 를 파싱 — 세션 재개·비용 집계 모두 지원.
+ *  - generic: 프롬프트를 마지막 위치인자로 넘기고 stdout 을 그대로 텍스트로 본다.
+ *    세션 재개·비용 집계는 없다(매 호출이 새 세션). opencode 등 단순 CLI 용 최소 계약.
+ *    예: HILOOP_AGENT_CMD=opencode, HILOOP_AGENT_ARGS=run → `opencode run "<prompt>"`.
+ */
+export const AGENT_ADAPTERS = {
+  claude: { buildArgs: buildAgentArgs, parseOutput: parseAgentOutput },
+  generic: {
+    buildArgs: ({ prompt, extraArgs = [] }) => [...extraArgs, prompt],
+    parseOutput: (stdout, fallbackSessionId = null) => ({
+      text: String(stdout),
+      sessionId: fallbackSessionId,
+      costUsd: 0,
+    }),
+  },
+};
+
+/** 이름이 없거나 모르는 값이면 claude 로 조용히 되돌린다(기본 경로 보존). */
+export function getAgentAdapter(name = process.env.HILOOP_AGENT_PROVIDER) {
+  return AGENT_ADAPTERS[String(name || 'claude').toLowerCase()] || AGENT_ADAPTERS.claude;
+}