workq-mcp 0.1.0 → 0.1.2

package/README.md

@@ -11,7 +11,7 @@ npm install -g workq-mcp
 ## Binaries
 
 - `workq-mcp`: stdio MCP bridge that forwards JSON-RPC to `https://work-q.nado.ai.kr/api/mcp`.
-- `workq`: helper CLI for one-time local repository connection.
+- `workq`: helper CLI for one-time local repository connection and repository bootstrap.
 
 ## Environment
 
@@ -41,6 +41,58 @@ git rev-parse HEAD
 
 Then it calls `workq_connect_local_project`.
 
+By default, `workq connect` also reads local product docs, package scripts, routes, API/server files, tests, deployment config, and known integration folders. It then calls:
+
+- `workq_update_project_context`
+- `workq_connect_local_project`
+- `workq_update_product_map`
+
+This creates or updates the Work Q project context and an initial Product State Map from the local repository. Use `--no-bootstrap` only when you want to connect repository identity without updating the feature map.
+
+```bash
+workq connect --project-key WORKQ --no-bootstrap
+workq bootstrap --project-key WORKQ
+```
+
+The bootstrap analyzer records observed code evidence, but unknown product intent remains `input_required` or `decision_needed`; it must not be treated as an approved bug-fix target until the owner decides.
+
+## Import Natural-Git Specs
+
+Work Q v2 cannot make the hosted web server read a desktop path like
+`/Users/jin/code/lotto`. Generate the natural-language git documents on the
+desktop and upload them through MCP:
+
+```bash
+cd /Users/jin/code/lotto
+workq natural-git --project-key LOTTO
+```
+
+This command reads the local repository, creates `natural-git/README.md`,
+`natural-git/code-index.md`, and one `natural-git/code/*.md` document per
+code/config file, then imports those docs into the Work Q v2 natural-spec repo.
+After that, open Work Q v2 and run `자연어 커밋 -> 명세 머지 -> 커밋 승인·Agent 큐`.
+Work Q creates a queued MCP work packet from the accepted natural commit. Your
+desktop Codex/Claude agent should claim that task, update the local repository,
+run checks, create any PR/deploy from the local environment, and close the loop
+with `workq_finish_task`.
+
+For clean bootstrap verification, delete exactly one project with an explicit confirmation key:
+
+```bash
+workq reset --project-key WORKQ --confirm-project-key WORKQ
+```
+
+## Standard Completion Protocol
+
+When a desktop agent finishes a Work Q task, it must close the loop in Work Q before saying the work is done.
+
+1. Claim the task with `workq_claim_task`.
+2. Post progress with `workq_post_progress` while reproducing, patching, and testing.
+3. Finish completed work with `workq_finish_task`.
+4. Include the returned `completion_receipt` in the final response.
+
+`workq_finish_task` requires `test_summary`, `remaining_risk`, and at least one of `changed_node_keys` or `verified_node_keys`. If the task cannot be completed, use `workq_request_decision` or `workq_post_result` with `failed`/`decision_needed` instead of leaving the task in progress.
+
 ## Codex MCP Registration
 
 Example:

package/bin/workq.mjs

@@ -3,6 +3,8 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
+import { analyzeRepository } from "../lib/analyze-repo.mjs";
+import { generateNaturalGitDocs } from "../lib/natural-git.mjs";
 
 const DEFAULT_ENDPOINT = "https://work-q.nado.ai.kr/api/mcp";
 
@@ -10,7 +12,10 @@ function usage() {
   process.stdout.write(`Work Q CLI
 
 Usage:
-  workq connect --project-key <KEY> [--device-label <LABEL>]
+  workq connect --project-key <KEY> [--device-label <LABEL>] [--node-display-language ko|en]
+  workq bootstrap --project-key <KEY> [--node-display-language ko|en]
+  workq natural-git --project-key <KEY>
+  workq reset --project-key <KEY> --confirm-project-key <KEY>
   workq mcp
 
 Environment:
@@ -20,6 +25,11 @@ Environment:
 
 Examples:
   workq connect --project-key WORKQ
+  workq connect --project-key WORKQ --node-display-language ko
+  workq connect --project-key WORKQ --no-bootstrap
+  workq bootstrap --project-key WORKQ
+  workq natural-git --project-key LOTTO
+  workq reset --project-key WORKQ --confirm-project-key WORKQ
   WORKQ_MCP_TOKEN_FILE=~/.codex/workq-mcp-token workq connect --project-key WORKQ
 `);
 }
@@ -114,6 +124,27 @@ async function connect(args) {
   const commitSha = git(["rev-parse", "HEAD"]);
   const remote = parseRemote(gitRemoteUrl);
   const deviceLabel = typeof args["device-label"] === "string" ? args["device-label"].trim() : `${os.hostname()} local`;
+  const shouldBootstrap = args.bootstrap !== false && args["no-bootstrap"] !== true;
+  const nodeDisplayLanguage = args["node-display-language"] || args.node_display_language || "";
+
+  let bootstrapResult = null;
+  let effectiveNodeDisplayLanguage = nodeDisplayLanguage;
+  if (shouldBootstrap) {
+    bootstrapResult = analyzeRepository({
+      localPath,
+      projectKey,
+      remote,
+      branch: gitBranch,
+      commitSha,
+      nodeDisplayLanguage
+    });
+    effectiveNodeDisplayLanguage = nodeDisplayLanguage || bootstrapResult.analysis.language;
+
+    await callMcp("workq_update_project_context", {
+      ...bootstrapResult.projectContext,
+      node_display_language: effectiveNodeDisplayLanguage
+    });
+  }
 
   const result = await callMcp("workq_connect_local_project", {
     project_key: projectKey,
@@ -123,9 +154,20 @@ async function connect(args) {
     repository_owner: remote.owner,
     repository_repo: remote.repo,
     git_branch: gitBranch,
-    commit_sha: commitSha
+    commit_sha: commitSha,
+    node_display_language: effectiveNodeDisplayLanguage
   });
 
+  let productMapResult = null;
+  if (shouldBootstrap && bootstrapResult) {
+    productMapResult = await callMcp("workq_update_product_map", {
+      project_key: projectKey,
+      summary: bootstrapResult.productMap.summary,
+      nodes: bootstrapResult.productMap.nodes,
+      edges: bootstrapResult.productMap.edges
+    });
+  }
+
   process.stdout.write(`Connected Work Q local repository binding.
 project_key: ${result.service.project_key}
 binding_id: ${result.binding.id}
@@ -133,6 +175,124 @@ status: ${result.binding.status}
 repo: ${result.binding.repository_full_name}
 local_path: ${result.binding.local_path}
 branch: ${result.binding.git_branch ?? ""}
+bootstrap: ${shouldBootstrap ? "updated project context and product map" : "skipped"}
+${productMapResult ? `product_map_nodes: ${productMapResult.productMap?.nodes?.length ?? productMapResult.changedNodes?.length ?? 0}
+product_map_edges: ${productMapResult.productMap?.edges?.length ?? productMapResult.changedEdges?.length ?? 0}
+analysis_files: ${bootstrapResult.analysis.file_count}
+analysis_docs: ${bootstrapResult.analysis.doc_files.join(", ") || "none"}
+` : ""}
+`);
+}
+
+async function bootstrap(args) {
+  const projectKey = required(args["project-key"] || args.project_key, "--project-key");
+  const localPath = git(["rev-parse", "--show-toplevel"]);
+  const gitRemoteUrl = git(["remote", "get-url", "origin"]);
+  const gitBranch = git(["branch", "--show-current"]);
+  const commitSha = git(["rev-parse", "HEAD"]);
+  const remote = parseRemote(gitRemoteUrl);
+  const nodeDisplayLanguage = args["node-display-language"] || args.node_display_language || "";
+  const result = analyzeRepository({
+    localPath,
+    projectKey,
+    remote,
+    branch: gitBranch,
+    commitSha,
+    nodeDisplayLanguage
+  });
+  const effectiveNodeDisplayLanguage = nodeDisplayLanguage || result.analysis.language;
+
+  await callMcp("workq_update_project_context", {
+    ...result.projectContext,
+    node_display_language: effectiveNodeDisplayLanguage
+  });
+  const productMap = await callMcp("workq_update_product_map", {
+    project_key: projectKey,
+    summary: result.productMap.summary,
+    nodes: result.productMap.nodes,
+    edges: result.productMap.edges
+  });
+
+  process.stdout.write(`Bootstrapped Work Q project from local repository.
+project_key: ${projectKey}
+repo: ${remote.owner}/${remote.repo}
+local_path: ${localPath}
+branch: ${gitBranch}
+nodes: ${productMap.productMap?.nodes?.length ?? result.productMap.nodes.length}
+edges: ${productMap.productMap?.edges?.length ?? result.productMap.edges.length}
+analysis_files: ${result.analysis.file_count}
+analysis_docs: ${result.analysis.doc_files.join(", ") || "none"}
+`);
+}
+
+async function naturalGit(args) {
+  const projectKey = required(args["project-key"] || args.project_key, "--project-key");
+  const localPath = git(["rev-parse", "--show-toplevel"]);
+  const gitRemoteUrl = git(["remote", "get-url", "origin"]);
+  const gitBranch = git(["branch", "--show-current"]);
+  const commitSha = git(["rev-parse", "HEAD"]);
+  const remote = parseRemote(gitRemoteUrl);
+  const projectName = typeof args["project-name"] === "string" ? args["project-name"].trim() : projectKey;
+
+  await callMcp("workq_update_project_context", {
+    project_key: projectKey,
+    project_name: projectName,
+    local_path_hint: localPath,
+    repository_owner: remote.owner,
+    repository_repo: remote.repo,
+    default_branch: gitBranch || "main",
+    branch_prefix: "workq-v2/",
+    project_notes: `Natural-git import from ${localPath} at ${commitSha}.`
+  });
+
+  await callMcp("workq_connect_local_project", {
+    project_key: projectKey,
+    device_label: typeof args["device-label"] === "string" ? args["device-label"].trim() : `${os.hostname()} local`,
+    local_path: localPath,
+    git_remote_url: gitRemoteUrl,
+    repository_owner: remote.owner,
+    repository_repo: remote.repo,
+    git_branch: gitBranch,
+    commit_sha: commitSha
+  });
+
+  const generated = generateNaturalGitDocs({
+    localPath,
+    projectKey,
+    projectName,
+    repository: remote
+  });
+
+  const imported = await callMcp("workq_import_natural_git_specs", {
+    project_key: projectKey,
+    local_path: generated.root,
+    files_scanned: generated.files_scanned,
+    code_files: generated.code_files,
+    docs: generated.docs
+  });
+
+  process.stdout.write(`Imported natural-language git specs into Work Q.
+project_key: ${imported.service.project_key}
+repo: ${remote.owner}/${remote.repo}
+local_path: ${generated.root}
+files_scanned: ${generated.files_scanned}
+code_files: ${generated.code_files}
+natural_git_docs: ${generated.docs.length}
+next_step: Open Work Q v2, confirm natural-spec repo docs, then run 자연어 커밋 -> 명세 머지 -> 커밋 승인·Agent 큐. The desktop agent should claim the queued task and finish it with workq_finish_task.
+`);
+}
+
+async function reset(args) {
+  const projectKey = required(args["project-key"] || args.project_key, "--project-key");
+  const confirmProjectKey = required(args["confirm-project-key"] || args.confirm_project_key, "--confirm-project-key");
+  const result = await callMcp("workq_reset_project", {
+    project_key: projectKey,
+    confirm_project_key: confirmProjectKey
+  });
+  process.stdout.write(`Reset Work Q project.
+project_key: ${result.project_key ?? projectKey}
+deleted: ${Boolean(result.deleted)}
+service_id: ${result.service_id ?? ""}
 `);
 }
 
@@ -147,6 +307,18 @@ async function main() {
     await connect(args);
     return;
   }
+  if (command === "bootstrap") {
+    await bootstrap(args);
+    return;
+  }
+  if (command === "natural-git") {
+    await naturalGit(args);
+    return;
+  }
+  if (command === "reset") {
+    await reset(args);
+    return;
+  }
   if (command === "mcp") {
     await import("./workq-mcp.mjs");
     return;