workq-mcp 0.1.2 → 0.1.4

package/lib/natural-git.mjs

@@ -205,11 +205,7 @@ function extractDataModelFacts(file) {
   const facts = [];
   const schemaMatch = file.content.match(/new\s+mongoose\.Schema\s*\(\s*\{([\s\S]*?)\}\s*\)/m);
   if (schemaMatch) {
-    const fields = [];
-    for (const match of schemaMatch[1].matchAll(/^\s*([A-Za-z_$][\w$]*)\s*:\s*([^,\n]+)/gm)) {
-      fields.push(`${match[1]}(${compact(match[2], 80)})`);
-    }
-    facts.push(fields.length ? `이 파일은 데이터 모델 스키마를 정의하며 필드는 ${fields.join(", ")} 이다.` : "이 파일은 데이터 모델 스키마를 정의한다.");
+    facts.push("서비스가 저장하고 조회하는 데이터 구조와 값의 종류를 정의한다.");
   }
   if (file.path === "package.json") {
     const packageDoc = packageJsonDoc(file.content).split(/\r?\n/).filter((line) => line.startsWith("- `") || line.startsWith("- 패키지 이름"));
@@ -218,45 +214,80 @@ function extractDataModelFacts(file) {
   return facts;
 }
 
+function isEnvironmentConfigFile(file) {
+  const normalized = file.path.toLowerCase();
+  const basename = path.basename(normalized);
+  return (
+    /(^|\/)(env|environment)\.[cm]?[jt]sx?$/.test(normalized) ||
+    /(^|\/)(env|environment)\.(mjs|cjs|js|ts)$/.test(normalized) ||
+    /(^|\/)(lib|config)\/env\.[cm]?[jt]sx?$/.test(normalized) ||
+    /(^|\/)(lib|config)\/environment\.[cm]?[jt]sx?$/.test(normalized) ||
+    /^(env|environment)\./.test(basename)
+  );
+}
+
+function isCliEntryFile(file) {
+  return (
+    /^#!\/usr\/bin\/env\s+node/m.test(file.content) ||
+    /\bprocess\.argv\b/.test(file.content) ||
+    /\bUsage:\s*[\r\n]/.test(file.content) ||
+    /\bworkq\s+(connect|bootstrap|natural-git|reset|mcp)\b/.test(file.content)
+  );
+}
+
+function extractCliFacts(file) {
+  if (!isCliEntryFile(file)) return [];
+  const facts = [];
+  if (/\bworkq\s+connect\b/.test(file.content)) facts.push("사용자는 터미널에서 현재 로컬 git 저장소를 Work Q 프로젝트에 연결한다.");
+  if (/\bworkq\s+bootstrap\b/.test(file.content)) facts.push("사용자는 현재 저장소를 분석해 프로젝트 컨텍스트와 기능 지도를 Work Q에 초기 등록한다.");
+  if (/\bworkq\s+natural-git\b/.test(file.content)) facts.push("사용자는 현재 저장소의 구현을 기능 중심 자연어 명세로 변환해 Work Q natural-spec repo에 업로드한다.");
+  if (/\bworkq\s+reset\b/.test(file.content)) facts.push("사용자는 프로젝트 키를 다시 확인한 뒤 Work Q에 저장된 프로젝트 데이터를 초기화한다.");
+  if (/\bworkq\s+mcp\b/.test(file.content)) facts.push("사용자는 데스크톱 AI 클라이언트가 연결할 수 있는 Work Q MCP bridge를 실행한다.");
+  if (/git\s*\(\s*\[\s*["']rev-parse["']|git\s+rev-parse/.test(file.content)) facts.push("명령 실행 시 현재 저장소의 로컬 경로, 현재 브랜치, 현재 커밋을 읽어 Work Q에 전달한다.");
+  if (/remote["']?,\s*["']get-url|git\s+remote\s+get-url/.test(file.content)) facts.push("명령 실행 시 원격 GitHub 저장소 주소를 읽어 프로젝트의 소유자와 저장소 이름을 구분한다.");
+  if (/WORKQ_MCP_TOKEN|WORKQ_MCP_TOKEN_FILE/.test(file.content)) facts.push("MCP 인증 토큰은 환경 변수 또는 토큰 파일에서 읽어 Work Q API 호출에 사용한다.");
+  if (/WORKQ_MCP_URL/.test(file.content)) facts.push("Work Q MCP API 주소는 환경 변수로 바꿀 수 있고, 없으면 기본 운영 endpoint를 사용한다.");
+  return unique(facts, 14);
+}
+
+function extractCliRules(file) {
+  if (!isCliEntryFile(file)) return [];
+  const rules = [];
+  if (/--project-key/.test(file.content)) rules.push("프로젝트 식별값은 연결, 초기 분석, 자연어 명세 업로드, 초기화 명령에서 필수 입력이다.");
+  if (/--confirm-project-key/.test(file.content)) rules.push("프로젝트 초기화는 실수를 막기 위해 같은 프로젝트 식별값을 확인값으로 한 번 더 요구한다.");
+  if (/Only github\.com remotes are supported|github\.com/.test(file.content)) rules.push("원격 저장소는 GitHub 주소만 지원한다.");
+  if (/WORKQ_MCP_TOKEN_FILE|\.workq\/mcp-token/.test(file.content)) rules.push("직접 토큰이 없으면 지정된 토큰 파일을 읽고, 기본 토큰 파일 경로를 사용한다.");
+  if (/throw new Error/.test(file.content)) rules.push("필수 입력이나 연결 정보가 없으면 조용히 진행하지 않고 사용자에게 오류를 알린다.");
+  return unique(rules, 10);
+}
+
 function extractEnvironmentFacts(file) {
+  if (!isEnvironmentConfigFile(file)) return [];
   const envVars = unique(
     Array.from(file.content.matchAll(/process\.env(?:\.([A-Za-z_][A-Za-z0-9_]*)|\[["'`]([^"'`]+)["'`]\])/g)).map((match) => match[1] || match[2]),
     18
   );
   const facts = [];
   if (!envVars.length && !/get(DataDir|DbDir|WorkDir|AppUrl)|isMcpConfigured|getMiniAiConfig|isGithubCrudConfigured|requireEnv/.test(file.content)) return facts;
-  if (envVars.length) facts.push(`환경 변수 ${envVars.map((item) => `\`${item}\``).join(", ")} 값을 읽어 런타임 설정을 결정한다.`);
-  if (/getDataDir|getDbDir|getWorkDir/.test(file.content)) facts.push("데이터 저장 위치, SQLite DB 위치, 작업 파일 위치를 환경 변수와 기본값으로 분리한다.");
-  if (/getAppUrl/.test(file.content)) facts.push("앱 외부 URL은 환경 변수로 지정하고, 없으면 로컬 개발 URL을 기본값으로 사용한다.");
-  if (/isMcpConfigured|WORKQ_MCP_TOKEN/.test(file.content)) facts.push("MCP 토큰 설정 여부를 판단해 로컬 에이전트 연결 가능 상태를 구분한다.");
-  if (/getMiniAiConfig|isMiniAiConfigured|WORKQ_MINI_AI/.test(file.content)) facts.push("Mini AI endpoint, model, API key 설정을 하나의 구성값으로 묶어 triage 사용 가능 여부를 판단한다.");
-  if (/isGithubCrudConfigured|WORKQ_GITHUB_TOKEN/.test(file.content)) facts.push("GitHub CRUD token 존재 여부로 GitHub 작업 자동화 가능성을 판단한다.");
+  if (envVars.length) facts.push("데이터 저장 위치, 외부 접속 주소, 에이전트 연결, AI 분류, GitHub 자동화, 테스트 모드 같은 런타임 설정을 외부 설정값으로 결정한다.");
+  if (/getDataDir|getDbDir|getWorkDir/.test(file.content)) facts.push("서비스 데이터, 내부 데이터베이스, 작업 파일이 저장될 위치를 외부 설정과 기본값으로 분리한다.");
+  if (/getAppUrl/.test(file.content)) facts.push("앱 외부 접속 주소는 배포 환경에서 지정하고, 없으면 로컬 개발 주소를 기본값으로 사용한다.");
+  if (/isMcpConfigured|WORKQ_MCP_TOKEN/.test(file.content)) facts.push("MCP 인증 정보가 설정되어 있는지 확인해 로컬 에이전트 연결 가능 상태를 구분한다.");
+  if (/getMiniAiConfig|isMiniAiConfigured|WORKQ_MINI_AI/.test(file.content)) facts.push("AI 분류 서버 주소, 사용할 모델, 인증 정보를 하나의 설정으로 묶어 자동 분류 가능 여부를 판단한다.");
+  if (/isGithubCrudConfigured|WORKQ_GITHUB_TOKEN/.test(file.content)) facts.push("GitHub 자동화 인증 정보가 있으면 코드 변경 자동화 기능을 사용할 수 있는 상태로 판단한다.");
   if (/requireEnv/.test(file.content)) facts.push("필수 환경 변수가 없으면 조용히 진행하지 않고 명시적인 설정 오류를 발생시킨다.");
   return unique(facts, 10);
 }
 
 function extractFunctionalFacts(file, structure) {
   const facts = [];
+  facts.push(...extractCliFacts(file));
   const environmentFacts = extractEnvironmentFacts(file);
   const visibleTexts = extractVisibleTexts(file);
-  const conditionSummaries = structure.conditions
-    .map((item) => item.expression ?? item.signature ?? "")
-    .filter((item) => item && item.length <= 180 && !/[<>]/.test(item))
-    .slice(0, 10);
   facts.push(...environmentFacts);
   if (visibleTexts.length) facts.push(`사용자에게 보이는 주요 문구는 ${visibleTexts.map((item) => `"${item}"`).join(", ")} 이다.`);
-  if (structure.events.length) {
-    facts.push(`사용자 이벤트는 ${structure.events.map((item) => `${item.target}의 ${item.event}`).join(", ")} 흐름을 처리한다.`);
-  }
-  if (!environmentFacts.length && structure.functions.length) {
-    facts.push(`내부 동작 단위는 ${structure.functions.slice(0, 8).map((item) => `${item.name}()`).join(", ")} 등이며, 세부 구현 근거는 코드 근거 섹션에서 추적한다.`);
-  }
-  if (structure.routes.length) {
-    facts.push(`네트워크/라우트 흐름은 ${structure.routes.slice(0, 8).map((item) => `${item.kind} ${item.expression}`).join(", ")} 로 연결된다.`);
-  }
-  if (!environmentFacts.length && conditionSummaries.length) {
-    facts.push(`분기와 반복은 ${conditionSummaries.join("; ")} 조건을 기준으로 동작한다.`);
-  }
+  if (structure.events.length) facts.push("사용자 조작에 반응해 화면 상태나 결과 표시를 갱신한다.");
+  if (structure.routes.length) facts.push("HTTP 요청을 받아 서비스 상태 조회, 저장, 갱신 같은 서버 기능을 처리한다.");
   if (/\bfor\s*\(\s*let\s+([A-Za-z_$][\w$]*)\s*=\s*(\d+)\s*;\s*\1\s*<=\s*(\d+)/.test(file.content)) {
     const loop = file.content.match(/\bfor\s*\(\s*let\s+([A-Za-z_$][\w$]*)\s*=\s*(\d+)\s*;\s*\1\s*<=\s*(\d+)/);
     facts.push(`반복문은 ${loop[2]}부터 ${loop[3]}까지의 선택지 또는 결과 행을 자동 생성한다.`);
@@ -269,6 +300,18 @@ function extractFunctionalFacts(file, structure) {
 
 function buildVerificationFacts(file, structure) {
   const facts = [];
+  if (isCliEntryFile(file)) {
+    facts.push("각 CLI 명령이 필수 입력을 요구하고 누락 시 명확한 오류를 보여주는지 확인한다.");
+    facts.push("로컬 git 저장소 정보와 Work Q 프로젝트 정보가 의도한 프로젝트에만 연결되는지 확인한다.");
+    facts.push("자연어 명세 업로드 명령이 기능 중심 문서를 만들고 Work Q에 정상 반영하는지 확인한다.");
+    return facts;
+  }
+  if (isEnvironmentConfigFile(file)) {
+    facts.push("외부 설정값이 있을 때 해당 값이 우선 적용되는지 확인한다.");
+    facts.push("외부 설정값이 없을 때 기본값이나 명확한 설정 오류가 의도대로 동작하는지 확인한다.");
+    facts.push("에이전트 연결, AI 분류, GitHub 자동화 가능 상태가 설정 유무에 따라 올바르게 구분되는지 확인한다.");
+    return facts;
+  }
   if (extractVisibleTexts(file).length) facts.push("화면에 노출되는 문구와 버튼이 의도한 사용자 흐름을 설명하는지 확인한다.");
   if (structure.events.length) facts.push("사용자 이벤트 실행 후 화면 상태와 데이터가 기대값으로 바뀌는지 확인한다.");
   if (structure.conditions.length) facts.push("반복/조건의 경계값과 예외 흐름을 테스트한다.");
@@ -277,15 +320,6 @@ function buildVerificationFacts(file, structure) {
   return facts;
 }
 
-function sourceEvidenceFacts(file, structure) {
-  const evidence = [];
-  if (structure.functions.length) evidence.push(`함수/메서드: ${structure.functions.slice(0, 12).map((item) => `${item.name}(${item.line}행)`).join(", ")}`);
-  if (structure.variables.length) evidence.push(`주요 값: ${structure.variables.slice(0, 12).map((item) => `${item.name}(${item.line}행)`).join(", ")}`);
-  if (structure.events.length) evidence.push(`이벤트: ${structure.events.slice(0, 12).map((item) => `${item.event}(${item.line}행)`).join(", ")}`);
-  if (structure.selectors.length) evidence.push(`스타일 선택자: ${structure.selectors.slice(0, 12).join(", ")}`);
-  return evidence;
-}
-
 function extractStructure(lines) {
   const functions = [];
   const variables = [];
@@ -339,6 +373,8 @@ function sourceFileToDoc(file) {
   const purpose =
     file.path === "package.json"
       ? "패키지 이름, 실행 스크립트, 의존성, Node 런타임 조건을 정의한다."
+      : isCliEntryFile(file)
+        ? "터미널 명령으로 Work Q 프로젝트 연결, 초기 분석, 자연어 명세 업로드, 프로젝트 초기화, MCP bridge 실행을 수행한다."
       : extractEnvironmentFacts(file).length
         ? "런타임 환경 변수와 기본값을 해석해 저장소, URL, MCP, Mini AI, GitHub 연결 상태를 결정한다."
       : file.extension === ".css"
@@ -352,26 +388,37 @@ function sourceFileToDoc(file) {
   const functionalFacts = extractFunctionalFacts(file, structure);
   const designFacts = extractDesignFacts(file);
   const verificationFacts = buildVerificationFacts(file, structure);
-  const evidenceFacts = sourceEvidenceFacts(file, structure);
+  const cliRules = extractCliRules(file);
+  const environmentFacts = extractEnvironmentFacts(file);
   const coreRules = unique(
     [
       ...dataModelFacts,
-      ...extractEnvironmentFacts(file),
-      ...functionalFacts.filter((item) => /반복문|선택 상태|자동 생성|결과 영역|라우트|네트워크|분기/.test(item))
+      ...cliRules,
+      ...environmentFacts,
+      ...(cliRules.length ? [] : functionalFacts.filter((item) => /반복문|선택 상태|자동 생성|결과 영역|HTTP 요청|필수|초기화|GitHub|토큰/.test(item)))
     ],
     12
   );
+  const titleText = extractVisibleTexts(file)[0];
+  const title = isCliEntryFile(file)
+    ? "Work Q CLI 기능명세"
+    : file.path === "package.json"
+      ? "프로젝트 실행 환경 기능명세"
+      : titleText && file.extension === ".html"
+        ? `${titleText} 기능명세`
+        : extractEnvironmentFacts(file).length
+          ? "런타임 환경 설정 기능명세"
+          : dataModelFacts.length
+            ? "데이터 모델 기능명세"
+            : file.extension === ".css"
+              ? "화면 디자인 기능명세"
+              : `${file.path} 기능명세`;
   return [
-    `# ${file.path}`,
+    `# ${title}`,
     NATURAL_SPEC_FORMAT_COMMENT,
     "",
     "## 기능 중심 자연어 명세",
-    `이 파일은 ${file.language} 파일이며, 제품 관점에서는 ${purpose}`,
-    "",
-    "## 파일 정보",
-    `- 원본 경로: \`${file.path}\``,
-    `- 언어/형식: ${file.language}`,
-    `- 총 라인 수: ${file.lines.length}`,
+    `제품 관점에서 이 기능은 ${purpose}`,
     "",
     functionalFacts.length ? "## 사용자 기능과 동작" : "",
     ...functionalFacts.map((item) => `- ${item}`),
@@ -385,12 +432,9 @@ function sourceFileToDoc(file) {
     dataModelFacts.length && file.path !== "package.json" ? "## 데이터와 상태" : "",
     ...(file.path !== "package.json" ? dataModelFacts.map((item) => `- ${item}`) : []),
     "",
-    evidenceFacts.length ? "## 코드 근거" : "",
-    ...evidenceFacts.map((item) => `- ${item}`),
-    "",
     "## 검증 관점",
     ...verificationFacts.map((item) => `- ${item}`),
-    "- 제품 의도와 코드가 다를 수 있으므로, 코드에서 관찰된 동작은 승인된 제품 의도가 아니라 검증 근거로 취급한다.",
+    "- 이 문서는 현재 구현에서 관찰한 기능 초안이며, 오너가 승인한 뒤 기준 명세가 된다.",
     "- 리포트 분류 시 이 문서는 기능 존재, 화면 동작, 입력/출력, 핵심 규칙의 근거로 사용한다."
   ].filter((line, index, array) => line || array[index - 1]).join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workq-mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Work Q MCP stdio bridge and local repository connection CLI.",
   "type": "module",
   "bin": {