workq-mcp 0.1.8 → 0.1.9

package/lib/natural-git.mjs

@@ -1073,7 +1073,233 @@ function regionsForRoute(file, route) {
   return genericRouteRegions(file);
 }
 
-function screenReadmeDoc(file, route, regions) {
+const INTERNAL_FEATURE_DEFINITIONS = [
+  {
+    slug: "repository-natural-analysis",
+    title: "레포 코드 자연어 분석 내부 기능",
+    purpose: "사용자가 연결한 코드 레포를 읽고 URL 화면, 화면 영역, 검증 근거 중심의 natural-spec repo 초안을 만든다.",
+    match: [/repo-natural-spec/i, /generateNaturalSpecFromRepository/i, /generateNaturalGitDocs/i, /workq_import_natural_git_specs/i],
+    used_by_routes: ["/v2"],
+    related_regions: ["project-repo-registration", "natural-spec-repo"],
+    triggers: ["사용자가 레포 코드 자연어 분석을 요청한다.", "로컬 MCP CLI가 `workq natural-git` 업로드를 실행한다."],
+    outcomes: ["화면/영역 중심 Markdown 명세가 생성된다.", "코드 파일별 상세 구현은 `_evidence`로 분리된다."],
+    failure_impact: ["새 프로젝트의 초기 기능명세가 비어 있거나 코드 중심 문서로 잘못 보일 수 있다."],
+    verification: ["생성 결과에 `natural-git/screens/` 문서와 `_evidence` 문서가 함께 존재하는지 확인한다."]
+  },
+  {
+    slug: "natural-spec-repo-sync",
+    title: "자연어 git 저장소 동기화 내부 기능",
+    purpose: "웹에서 편집한 자연어 명세 draft, commit, merge 상태를 natural-spec repo 기준 상태와 맞춘다.",
+    match: [/spec-git/i, /natural-spec-repo/i, /stageNaturalSpecDocs/i, /commitNaturalSpec/i, /readNaturalSpecDocs/i],
+    used_by_routes: ["/v2"],
+    related_regions: ["natural-spec-repo", "natural-spec-editor", "commit-merge-agent-queue"],
+    triggers: ["사용자가 자연어 명세를 저장한다.", "사용자가 자연어 커밋, 머지, 롤백을 실행한다."],
+    outcomes: ["draft와 HEAD commit 상태가 구분된다.", "승인된 자연어 커밋만 Agent 큐 기준이 된다."],
+    failure_impact: ["화면에 보이는 명세와 Agent가 기준으로 읽는 명세가 달라질 수 있다."],
+    verification: ["draft 저장, commit, merge 이후 같은 프로젝트의 문서 상태와 commit id가 유지되는지 확인한다."]
+  },
+  {
+    slug: "report-triage-and-classification",
+    title: "리포트 판단 · 분류 내부 기능",
+    purpose: "사용자가 올린 버그, 개선, 기획문의, 개발문의를 승인된 자연어 명세와 비교해 bug, 기획부재, 충돌, 결정 필요로 구분한다.",
+    match: [/triage/i, /classification/i, /classify/i, /analyze-report/i, /mini.ai/i, /report/i],
+    used_by_routes: ["/", "/v2"],
+    related_regions: ["report-intake", "triage-and-spec-map", "decision-needed-mcp"],
+    triggers: ["사용자가 리포트를 제출한다.", "사용자가 기존 리포트를 다시 분석한다."],
+    outcomes: ["판단 결과와 근거 명세가 사용자에게 표시된다.", "승인이 필요한 항목은 자동 개발 큐로 넘어가지 않는다."],
+    failure_impact: ["버그가 아닌 기획부재를 버그로 고치거나, 실제 버그를 문의로 놓칠 수 있다."],
+    verification: ["명세가 있는 동작 차이는 bug 후보로, 명세가 없는 기대 동작은 기획부재/결정 필요로 표시되는지 확인한다."]
+  },
+  {
+    slug: "desktop-agent-mcp-queue",
+    title: "데스크톱 Agent MCP 큐 내부 기능",
+    purpose: "승인된 자연어 커밋이나 결정 사항을 로컬 Codex/Claude가 가져갈 작업 패킷으로 만들고 완료 결과를 다시 받는다.",
+    match: [/workq_list_tasks/i, /workq_get_work_packet/i, /workq_finish_task/i, /agent_task/i, /queued_for_agent/i, /MCP/i],
+    used_by_routes: ["/", "/v2"],
+    related_regions: ["agent-queue-and-mcp", "decision-needed-mcp", "existing-workq-queue", "commit-merge-agent-queue"],
+    triggers: ["사용자가 승인된 작업을 Agent 큐로 보낸다.", "로컬 Agent가 MCP로 다음 작업을 조회한다.", "로컬 Agent가 완료 결과를 제출한다."],
+    outcomes: ["작업 패킷에 프로젝트, 레포, 명세 근거, 완료 절차가 포함된다.", "완료 시 검증 결과와 명세 변경 근거가 Work Q에 남는다."],
+    failure_impact: ["로컬 Agent가 잘못된 프로젝트를 고치거나, 완료 작업이 큐에 남을 수 있다."],
+    verification: ["MCP 작업 조회, work packet 수신, finish task 호출 후 큐 상태가 완료로 바뀌는지 확인한다."]
+  },
+  {
+    slug: "project-context-binding",
+    title: "프로젝트 · 로컬 레포 바인딩 내부 기능",
+    purpose: "웹의 프로젝트 키와 로컬 데스크톱의 실제 git 레포 정보를 대조해 엉뚱한 레포를 고치지 않도록 한다.",
+    match: [/connect_local_project/i, /local.*project/i, /repository_owner/i, /local_path/i, /git remote/i, /project_key/i],
+    used_by_routes: ["/", "/v2"],
+    related_regions: ["project-context", "project-repo-registration", "project-status-summary"],
+    triggers: ["사용자가 프로젝트를 등록한다.", "로컬 MCP가 현재 git root, remote, branch를 Work Q에 연결한다."],
+    outcomes: ["프로젝트 키, repo owner/name, local path, branch가 같은 대상인지 확인된다."],
+    failure_impact: ["여러 프로젝트를 사용할 때 다른 레포의 리포트나 작업을 처리할 수 있다."],
+    verification: ["웹 프로젝트 정보와 MCP가 제출한 git root, remote, branch가 일치하지 않으면 연결 미검증 상태가 되는지 확인한다."]
+  }
+];
+
+function isUserFacingNavigationFile(file) {
+  if (isTestFile(file) || isApiOrServerFile(file) || isCliEntryFile(file)) return false;
+  return [".tsx", ".jsx", ".html", ".ts", ".js"].includes(file.extension);
+}
+
+function routeLiteralForSearch(route) {
+  return route.url_pattern.replace(/\[(.+?)\]/g, "");
+}
+
+function hasVisibleNavigationToRoute(route, routeFile, sourceFiles) {
+  if (route.url_pattern === "/" || route.url_pattern === "<product-overview>") return true;
+  const literal = routeLiteralForSearch(route);
+  if (!literal || literal === "/") return true;
+  const escaped = literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const navigationPatterns = [
+    new RegExp(`href\\s*=\\s*[{]?["'\`]${escaped}["'\`]`, "i"),
+    new RegExp(`router\\.push\\(\\s*["'\`]${escaped}`, "i"),
+    new RegExp(`navigate\\(\\s*["'\`]${escaped}`, "i"),
+    new RegExp(`location\\.href\\s*=\\s*["'\`]${escaped}`, "i")
+  ];
+  return sourceFiles.some((file) => {
+    if (file.path === routeFile.path || !isUserFacingNavigationFile(file)) return false;
+    return navigationPatterns.some((pattern) => pattern.test(file.content));
+  });
+}
+
+function routeEntriesForSourceFiles(sourceFiles) {
+  return sourceFiles.flatMap((file) => {
+    const route = routeInfoForFile(file);
+    if (!route) return [];
+    const regions = regionsForRoute(file, route);
+    return [
+      {
+        file,
+        route,
+        regions,
+        entryless: !hasVisibleNavigationToRoute(route, file, sourceFiles)
+      }
+    ];
+  });
+}
+
+function matchingInternalSourcePaths(sourceFiles, definition) {
+  return unique(
+    sourceFiles
+      .filter((file) => !isTestFile(file))
+      .filter((file) => {
+        const haystack = `${file.path}\n${file.content}`;
+        return definition.match.some((pattern) => pattern.test(haystack));
+      })
+      .map((file) => file.path),
+    10
+  );
+}
+
+function detectInternalFeatures(sourceFiles, entries) {
+  const availableRoutes = new Set(entries.map((entry) => entry.route.url_pattern));
+  const fallbackRoute = entries[0]?.route.url_pattern;
+  return INTERNAL_FEATURE_DEFINITIONS.flatMap((definition) => {
+    const sourcePaths = matchingInternalSourcePaths(sourceFiles, definition);
+    if (!sourcePaths.length) return [];
+    const usedByRoutes = definition.used_by_routes.filter((route) => availableRoutes.has(route));
+    const resolvedRoutes = usedByRoutes.length ? usedByRoutes : fallbackRoute ? [fallbackRoute] : [];
+    return [
+      {
+        slug: definition.slug,
+        title: definition.title,
+        purpose: definition.purpose,
+        used_by_routes: resolvedRoutes,
+        related_regions: definition.related_regions,
+        triggers: definition.triggers,
+        outcomes: definition.outcomes,
+        failure_impact: definition.failure_impact,
+        verification: definition.verification,
+        source_paths: sourcePaths,
+        shared: resolvedRoutes.length > 1
+      }
+    ];
+  });
+}
+
+function internalFeaturesForRoute(features, route) {
+  return features.filter((feature) => feature.used_by_routes.includes(route.url_pattern));
+}
+
+function internalFeaturesForRegion(features, region) {
+  return features.filter((feature) => feature.related_regions.includes(region.slug));
+}
+
+function internalFeatureDocPath(feature, entries) {
+  if (feature.shared || feature.used_by_routes.length !== 1) return `natural-git/shared-internals/${feature.slug}.md`;
+  const entry = entries.find((item) => item.route.url_pattern === feature.used_by_routes[0]);
+  return `${entry?.route.directory ?? "natural-git/shared-internals"}/internals/${feature.slug}.md`;
+}
+
+function internalFeatureDoc(feature, entries) {
+  return {
+    path: internalFeatureDocPath(feature, entries),
+    title: feature.title,
+    content: [
+      `# ${feature.title}`,
+      NATURAL_SPEC_FORMAT_COMMENT,
+      "",
+      "## 성격",
+      "이 문서는 화면에 직접 보이는 버튼이나 카드가 아니라, 화면 기능을 가능하게 하는 내부/백그라운드 기능 명세다.",
+      "",
+      "## 목적",
+      feature.purpose,
+      "",
+      "## 사용 화면",
+      ...feature.used_by_routes.map((route) => {
+        const entry = entries.find((item) => item.route.url_pattern === route);
+        return `- ${route}: ${entry ? `${entry.route.directory}/README.md` : "연결된 화면 명세"}`;
+      }),
+      "",
+      "## 연결된 화면 영역",
+      ...feature.related_regions.map((region) => `- ${region}`),
+      "",
+      "## 트리거",
+      ...feature.triggers.map((item) => `- ${item}`),
+      "",
+      "## 결과",
+      ...feature.outcomes.map((item) => `- ${item}`),
+      "",
+      "## 실패 시 사용자 영향",
+      ...feature.failure_impact.map((item) => `- ${item}`),
+      "",
+      "## 검증 방법",
+      ...feature.verification.map((item) => `- ${item}`),
+      "",
+      "## 구현 근거",
+      ...feature.source_paths.map((sourcePath) => `- ${sourceEvidencePath({ path: sourcePath })}`)
+    ].join("\n")
+  };
+}
+
+function entrylessScreenDoc(entry) {
+  const slug = slugSegment(entry.route.url_pattern.replace(/^\//, "") || "root");
+  return {
+    path: `natural-git/entryless-screens/${slug}.md`,
+    title: `진입점 없는 화면: ${entry.route.url_pattern}`,
+    content: [
+      `# 진입점 없는 화면: ${entry.route.url_pattern}`,
+      NATURAL_SPEC_FORMAT_COMMENT,
+      "",
+      "## 의미",
+      "이 URL은 화면 파일과 기능명세가 있지만, 다른 사용자 화면에서 명확한 버튼이나 링크 진입점을 발견하지 못했다.",
+      "",
+      "## 기준 화면 명세",
+      `- ${entry.route.directory}/README.md`,
+      "",
+      "## 운영 원칙",
+      "- 직접 URL, 관리자 전용, 실험용, MCP/Agent 전용 화면일 수 있다.",
+      "- 사용자가 일반 화면에서 접근해야 하는 기능이면 별도 메뉴, 버튼, 링크를 추가해야 한다.",
+      "- 진입점이 없는 상태 자체가 제품 의도인지 오너가 확인해야 한다.",
+      "",
+      "## 검증 방법",
+      "- 이 화면으로 이동하는 실제 사용자 진입점이 있는지 확인한다.",
+      "- 진입점이 의도적으로 없다면 이유를 이 문서 또는 화면 README에 기록한다."
+    ].join("\n")
+  };
+}
+
+function screenReadmeDoc(file, route, regions, internals, entries) {
   const isWorkQDashboard = isWorkQDashboardPage(file);
   const isWorkQV2 = route.url_pattern === "/v2" && file.path === "src/app/v2/page.tsx";
   const title = isWorkQDashboard ? "Work Q 대시보드 화면 명세" : isWorkQV2 ? "Work Q v2 대시보드 화면 명세" : route.title;
@@ -1098,9 +1324,15 @@ function screenReadmeDoc(file, route, regions) {
       "## 화면 영역",
       ...regions.map((region) => `- ${region.title}: ${region.purpose}`),
       "",
+      "## 관련 내부 기능",
+      ...(internals.length
+        ? internals.map((feature) => `- ${feature.title}: ${feature.purpose} (${internalFeatureDocPath(feature, entries)})`)
+        : ["- 이 화면에 연결된 내부/백그라운드 기능이 아직 발견되지 않았다."]),
+      "",
       "## 핵심 원칙",
       "- URL 패턴을 최상위 화면 명세로 삼는다.",
       "- 화면 안의 사용자 인식 영역을 region 명세로 나눈다.",
+      "- 화면에 보이지 않지만 이 화면 기능을 가능하게 하는 백그라운드 동작은 관련 내부 기능으로 연결한다.",
       "- 코드 파일 경로는 사용자 기능명세 제목으로 쓰지 않고 evidence로 분리한다.",
       "- 페이지네이션, 게시물 번호, 상세 id처럼 값만 바뀌는 URL은 하나의 URL 패턴으로 추상화한다.",
       "",
@@ -1110,7 +1342,7 @@ function screenReadmeDoc(file, route, regions) {
   };
 }
 
-function screenRulesDoc(route, regions) {
+function screenRulesDoc(route, regions, internals) {
   return {
     path: `${route.directory}/rules.md`,
     title: `${route.url_pattern} 화면 규칙`,
@@ -1125,12 +1357,23 @@ function screenRulesDoc(route, regions) {
       "- 코드에서 관찰된 구현만으로 제품 의도를 단정하지 않는다.",
       "",
       "## 영역별 핵심 규칙",
-      ...regions.flatMap((region) => [`### ${region.title}`, ...region.rules.map((rule) => `- ${rule}`), ""])
+      ...regions.flatMap((region) => [`### ${region.title}`, ...region.rules.map((rule) => `- ${rule}`), ""]),
+      ...(internals.length
+        ? [
+            "## 관련 내부 기능 판단 기준",
+            ...internals.flatMap((feature) => [
+              `### ${feature.title}`,
+              `- 이 내부 기능은 ${feature.used_by_routes.join(", ")} 화면의 기능을 지원한다.`,
+              ...feature.failure_impact.map((item) => `- 실패 영향: ${item}`),
+              ""
+            ])
+          ]
+        : [])
     ].join("\n")
   };
 }
 
-function screenVerificationDoc(route, regions) {
+function screenVerificationDoc(route, regions, internals) {
   return {
     path: `${route.directory}/verification.md`,
     title: `${route.url_pattern} 화면 검증`,
@@ -1144,12 +1387,19 @@ function screenVerificationDoc(route, regions) {
       "- Agent 완료 전에는 관련 영역의 verification 항목을 확인하고 Work Q 완료 기록에 남긴다.",
       "",
       "## 영역별 검증",
-      ...regions.flatMap((region) => [`### ${region.title}`, ...region.verification.map((item) => `- ${item}`), ""])
+      ...regions.flatMap((region) => [`### ${region.title}`, ...region.verification.map((item) => `- ${item}`), ""]),
+      ...(internals.length
+        ? [
+            "## 관련 내부 기능 검증",
+            ...internals.flatMap((feature) => [`### ${feature.title}`, ...feature.verification.map((item) => `- ${item}`), ""])
+          ]
+        : [])
     ].join("\n")
   };
 }
 
-function regionDoc(route, region) {
+function regionDoc(route, region, internals, entries) {
+  const relatedInternals = internalFeaturesForRegion(internals, region);
   return {
     path: `${route.directory}/regions/${region.slug}.md`,
     title: region.title,
@@ -1169,6 +1419,13 @@ function regionDoc(route, region) {
       "## 핵심 규칙",
       ...region.rules.map((item) => `- ${item}`),
       "",
+      ...(relatedInternals.length
+        ? [
+            "## 관련 내부 기능",
+            ...relatedInternals.map((feature) => `- ${feature.title}: ${internalFeatureDocPath(feature, entries)}`),
+            ""
+          ]
+        : []),
       "## 검증 방법",
       ...region.verification.map((item) => `- ${item}`)
     ].join("\n")
@@ -1230,25 +1487,32 @@ function fallbackRegions(sourceFiles) {
 }
 
 function routeScreenDocs(sourceFiles) {
-  const docs = sourceFiles.flatMap((file) => {
-    const route = routeInfoForFile(file);
-    if (!route) return [];
-    const regions = regionsForRoute(file, route);
+  const entries = routeEntriesForSourceFiles(sourceFiles);
+  const detectedInternals = detectInternalFeatures(sourceFiles, entries);
+  const docs = entries.flatMap((entry) => {
+    const internals = internalFeaturesForRoute(detectedInternals, entry.route);
     return [
-      screenReadmeDoc(file, route, regions),
-      screenRulesDoc(route, regions),
-      screenVerificationDoc(route, regions),
-      ...regions.map((region) => regionDoc(route, region))
+      screenReadmeDoc(entry.file, entry.route, entry.regions, internals, entries),
+      screenRulesDoc(entry.route, entry.regions, internals),
+      screenVerificationDoc(entry.route, entry.regions, internals),
+      ...entry.regions.map((region) => regionDoc(entry.route, region, internals, entries))
     ];
   });
-  if (docs.length || !sourceFiles.length) return docs;
+  if (docs.length || !sourceFiles.length) {
+    return [...docs, ...detectedInternals.map((feature) => internalFeatureDoc(feature, entries)), ...entries.filter((entry) => entry.entryless).map((entry) => entrylessScreenDoc(entry))];
+  }
   const route = fallbackRouteInfo();
   const regions = fallbackRegions(sourceFiles);
+  const fallbackEntry = { file: sourceFiles[0], route, regions, entryless: false };
+  const entriesWithFallback = [fallbackEntry];
+  const internals = detectInternalFeatures(sourceFiles, entriesWithFallback);
+  const routeInternals = internalFeaturesForRoute(internals, route);
   return [
-    screenReadmeDoc(sourceFiles[0], route, regions),
-    screenRulesDoc(route, regions),
-    screenVerificationDoc(route, regions),
-    ...regions.map((region) => regionDoc(route, region))
+    screenReadmeDoc(sourceFiles[0], route, regions, routeInternals, entriesWithFallback),
+    screenRulesDoc(route, regions, routeInternals),
+    screenVerificationDoc(route, regions, routeInternals),
+    ...regions.map((region) => regionDoc(route, region, routeInternals, entriesWithFallback)),
+    ...internals.map((feature) => internalFeatureDoc(feature, entriesWithFallback))
   ];
 }
 
@@ -1275,13 +1539,18 @@ function overviewDoc({ projectKey, projectName, repository, root, sourceFiles })
     "## 디렉토리 구조",
     "- `natural-git/screens/`: URL 패턴별 최상위 화면 명세",
     "- `natural-git/screens/<url>/regions/`: 화면 안의 사용자 인식 영역 명세",
+    "- `natural-git/screens/<url>/internals/`: 특정 화면 기능을 가능하게 하는 내부/백그라운드 기능 명세",
     "- `natural-git/screens/<url>/components/`: 여러 화면에서 재사용되는 컴포넌트 명세",
     "- `natural-git/screens/<url>/dialogs/`: 모달, 팝업, 드로어 상태 명세",
+    "- `natural-git/shared-internals/`: 여러 화면에서 같이 쓰는 내부/백그라운드 기능 명세",
+    "- `natural-git/entryless-screens/`: 화면은 있지만 메뉴나 버튼 진입점이 명확하지 않은 URL 명세",
     "- `natural-git/verification/`: 기능이 실제로 동작하는지 확인하는 검증 시나리오 명세",
     "- `natural-git/_evidence/`: 코드 파일, 설정, 테스트의 구현 근거. 기본 사용자 명세가 아니라 traceability 근거다.",
     "",
     "## 운영 규칙",
     "- 자연어 문서는 URL 화면과 사용자 인식 영역 중심으로 작성한다.",
+    "- 화면에 보이지 않는 동기화, 분류, 큐, 임베딩, 백그라운드 작업은 그 기능을 사용하는 화면에 관련 내부 기능으로 연결한다.",
+    "- 여러 화면에서 쓰는 내부 기능은 `shared-internals`에 두고, 어느 화면에서도 진입점이 없는 화면은 `entryless-screens`에 기록한다.",
     "- 코드 파일 문서는 사용자 기능명세가 아니라 `_evidence` 아래 구현 근거로 보존한다.",
     "- 코드의 현재 동작이 곧 제품 의도라는 뜻은 아니다.",
     "- 오너가 자연어 커밋으로 승인한 내용만 다음 코드 변경의 기준이 된다.",

package/package.json

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