helloloop 0.1.1 → 0.1.2

package/src/analyze_prompt.mjs

@@ -0,0 +1,75 @@
+import { formatList } from "./common.mjs";
+import {
+  hasCustomProjectConstraints,
+  listMandatoryGuardrails,
+  resolveProjectConstraints,
+} from "./guardrails.mjs";
+
+function section(title, content) {
+  if (!content || !String(content).trim()) {
+    return "";
+  }
+  return `## ${title}\n${String(content).trim()}\n`;
+}
+
+function listSection(title, items) {
+  if (!Array.isArray(items) || !items.length) {
+    return "";
+  }
+  return section(title, formatList(items));
+}
+
+function renderDocPackets(docPackets) {
+  return docPackets.map((packet) => [
+    `### 文档：${packet.path}`,
+    packet.truncated ? "（已截断）" : "",
+    "",
+    packet.content,
+  ].filter(Boolean).join("\n")).join("\n\n");
+}
+
+export function buildAnalysisPrompt({
+  repoRoot,
+  docsEntries,
+  docPackets,
+  existingStateText = "",
+  existingBacklogText = "",
+  existingProjectConstraints = [],
+}) {
+  const mandatoryGuardrails = listMandatoryGuardrails();
+  const effectiveConstraints = resolveProjectConstraints(existingProjectConstraints);
+  const usingFallbackConstraints = !hasCustomProjectConstraints(existingProjectConstraints);
+
+  return [
+    "你要为一个本地代码仓库做“接续开发分析”。",
+    "目标不是直接改代码，而是判断当前已经做到哪里，并生成后续可执行 backlog。",
+    "",
+    "必须遵守以下原则：",
+    "1. 代码是事实源，开发文档是目标源。",
+    "2. 判断“已完成 / 部分完成 / 未完成”时，以仓库当前真实代码、测试、目录结构为准，不能盲信文档。",
+    "3. 生成的任务必须颗粒度足够，能直接进入开发，不允许输出“继续开发”这类空泛任务。",
+    "4. 只关注当前目标仓库，不要把其他仓库的任务混进来；如果文档覆盖多仓库，只提取当前仓库相关任务。",
+    "5. 如果某项工作依赖其他仓库或外部输入，允许输出 `blocked` 任务，但必须明确阻塞原因。",
+    "",
+    section("目标仓库", `- 路径：${repoRoot.replaceAll("\\", "/")}`),
+    section("开发文档入口", docsEntries.map((item) => `- ${item}`).join("\n")),
+    existingStateText ? section("已有状态摘要", existingStateText) : "",
+    listSection("内建安全底线", mandatoryGuardrails),
+    listSection(usingFallbackConstraints ? "默认工程约束（文档未明确时也必须遵守）" : "已有项目约束", effectiveConstraints),
+    existingBacklogText ? section("已有 backlog（供参考，可重组）", existingBacklogText) : "",
+    section("文档内容摘录", renderDocPackets(docPackets)),
+    section("输出要求", [
+      "1. 严格输出 JSON，不要带 Markdown 代码块。",
+      "2. `summary.currentState` 要清晰描述当前仓库真实进度。",
+      "3. `summary.implemented` 写已确认完成的关键能力。",
+      "4. `summary.remaining` 写尚未完成的关键缺口。",
+      "5. `summary.nextAction` 写最合理的下一步。",
+      "6. `tasks` 总数控制在 4 到 12 个之间，优先覆盖真正剩余工作。",
+      "7. 每个任务必须包含：id、title、status、priority、risk、goal、docs、paths、acceptance。",
+      "8. `status` 只能是 `done`、`pending`、`blocked`，不要输出 `in_progress` 或 `failed`。",
+      "9. `docs` 必须引用本次文档入口中的相关路径；`paths` 必须写当前仓库内的实际目录或文件模式。",
+      "10. `acceptance` 必须可验证，不要写空话。",
+      "11. `constraints` 只写从项目文档或现有项目配置中提炼出的项目特有约束；不要重复内建安全底线。",
+    ].join("\n")),
+  ].filter(Boolean).join("\n");
+}

package/src/analyzer.mjs

@@ -0,0 +1,208 @@
+import path from "node:path";
+
+import { summarizeBacklog, selectNextTask } from "./backlog.mjs";
+import { nowIso, writeJson, writeText, readTextIfExists } from "./common.mjs";
+import { loadPolicy, loadProjectConfig, scaffoldIfMissing, writeStateMarkdown, writeStatus } from "./config.mjs";
+import { createContext } from "./context.mjs";
+import { discoverWorkspace } from "./discovery.mjs";
+import { readDocumentPackets } from "./doc_loader.mjs";
+import { runCodexTask } from "./process.mjs";
+import { buildAnalysisPrompt } from "./analyze_prompt.mjs";
+
+function renderAnalysisState(context, backlog, analysis) {
+  const summary = summarizeBacklog(backlog);
+  const nextTask = selectNextTask(backlog);
+
+  return [
+    "## 当前状态",
+    `- backlog 文件：${path.relative(context.repoRoot, context.backlogFile).replaceAll("\\", "/")}`,
+    `- 总任务数：${summary.total}`,
+    `- 已完成：${summary.done}`,
+    `- 待处理：${summary.pending}`,
+    `- 进行中：${summary.inProgress}`,
+    `- 失败：${summary.failed}`,
+    `- 阻塞：${summary.blocked}`,
+    `- 当前任务：${nextTask ? nextTask.title : "无"}`,
+    `- 最近结果：${analysis.summary.currentState}`,
+    `- 下一建议：${analysis.summary.nextAction}`,
+  ].join("\n");
+}
+
+function sanitizeTask(task) {
+  return {
+    id: String(task.id || "").trim(),
+    title: String(task.title || "").trim(),
+    status: ["done", "blocked"].includes(String(task.status || "")) ? String(task.status) : "pending",
+    priority: ["P0", "P1", "P2", "P3"].includes(String(task.priority || "")) ? String(task.priority) : "P2",
+    risk: ["medium", "high", "critical"].includes(String(task.risk || "")) ? String(task.risk) : "low",
+    goal: String(task.goal || "").trim(),
+    docs: Array.isArray(task.docs) ? task.docs.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    paths: Array.isArray(task.paths) ? task.paths.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    acceptance: Array.isArray(task.acceptance) ? task.acceptance.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    dependsOn: Array.isArray(task.dependsOn) ? task.dependsOn.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    verify: Array.isArray(task.verify) ? task.verify.map((item) => String(item || "").trim()).filter(Boolean) : [],
+  };
+}
+
+function normalizeAnalysisPayload(payload, docsEntries) {
+  const tasks = Array.isArray(payload.tasks)
+    ? payload.tasks.map((task) => sanitizeTask(task)).filter((task) => (
+      task.id && task.title && task.goal && task.acceptance.length
+    ))
+    : [];
+
+  if (!tasks.length) {
+    throw new Error("Codex 分析结果无效：未生成可用任务。");
+  }
+
+  return {
+    project: String(payload.project || "").trim() || "helloloop-project",
+    summary: {
+      currentState: String(payload?.summary?.currentState || "").trim() || "已完成接续分析。",
+      implemented: Array.isArray(payload?.summary?.implemented) ? payload.summary.implemented.map((item) => String(item || "").trim()).filter(Boolean) : [],
+      remaining: Array.isArray(payload?.summary?.remaining) ? payload.summary.remaining.map((item) => String(item || "").trim()).filter(Boolean) : [],
+      nextAction: String(payload?.summary?.nextAction || "").trim() || "查看下一任务。",
+    },
+    constraints: Array.isArray(payload.constraints)
+      ? payload.constraints.map((item) => String(item || "").trim()).filter(Boolean)
+      : [],
+    tasks,
+    requiredDocs: docsEntries,
+  };
+}
+
+function buildAnalysisSummaryText(context, analysis, backlog) {
+  const summary = summarizeBacklog(backlog);
+  const nextTask = selectNextTask(backlog);
+
+  return [
+    "HelloLoop 已完成接续分析。",
+    `项目仓库：${context.repoRoot}`,
+    `开发文档：${analysis.requiredDocs.join(", ")}`,
+    "",
+    "当前进度：",
+    analysis.summary.currentState,
+    "",
+    `任务统计：done ${summary.done} / pending ${summary.pending} / blocked ${summary.blocked}`,
+    nextTask ? `下一任务：${nextTask.title}` : "下一任务：暂无可执行任务",
+    "",
+    "下一步建议：",
+    `- npx helloloop next`,
+    `- npx helloloop run-once`,
+  ].join("\n");
+}
+
+export async function analyzeWorkspace(options = {}) {
+  const discovery = discoverWorkspace({
+    cwd: options.cwd,
+    inputPath: options.inputPath,
+    repoRoot: options.repoRoot,
+    docsPath: options.docsPath,
+    configDirName: options.configDirName,
+  });
+
+  if (!discovery.ok) {
+    return {
+      ok: false,
+      code: discovery.code,
+      summary: discovery.message,
+    };
+  }
+
+  const context = createContext({
+    repoRoot: discovery.repoRoot,
+    configDirName: options.configDirName,
+  });
+  scaffoldIfMissing(context);
+
+  const existingProjectConfig = loadProjectConfig(context);
+  const existingStateText = readTextIfExists(context.stateFile, "");
+  const existingBacklogText = readTextIfExists(context.backlogFile, "");
+  const docPackets = readDocumentPackets(context.repoRoot, discovery.docsEntries, {
+    maxCharsPerFile: 18000,
+    maxTotalChars: 90000,
+  });
+
+  const prompt = buildAnalysisPrompt({
+    repoRoot: context.repoRoot,
+    docsEntries: discovery.docsEntries,
+    docPackets,
+    existingStateText,
+    existingBacklogText,
+    existingProjectConstraints: existingProjectConfig.constraints,
+  });
+
+  const runDir = path.join(context.runsDir, `${nowIso().replaceAll(":", "-").replaceAll(".", "-")}-analysis`);
+  const policy = loadPolicy(context);
+  const schemaFile = path.join(context.templatesDir, "analysis-output.schema.json");
+  const codexResult = await runCodexTask({
+    context,
+    prompt,
+    runDir,
+    model: policy.codex.model,
+    executable: policy.codex.executable,
+    sandbox: policy.codex.sandbox,
+    dangerouslyBypassSandbox: policy.codex.dangerouslyBypassSandbox,
+    outputSchemaFile: schemaFile,
+    outputPrefix: "analysis",
+    jsonOutput: false,
+    skipGitRepoCheck: true,
+  });
+
+  if (!codexResult.ok) {
+    return {
+      ok: false,
+      code: "analysis_failed",
+      summary: codexResult.stderr || codexResult.stdout || "Codex 接续分析失败。",
+    };
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(codexResult.finalMessage);
+  } catch (error) {
+    return {
+      ok: false,
+      code: "invalid_analysis_json",
+      summary: `Codex 分析结果无法解析为 JSON：${String(error?.message || error || "")}`,
+    };
+  }
+
+  const analysis = normalizeAnalysisPayload(payload, discovery.docsEntries);
+  const backlog = {
+    version: 1,
+    project: analysis.project,
+    updatedAt: nowIso(),
+    tasks: analysis.tasks,
+  };
+
+  const projectConfig = {
+    requiredDocs: analysis.requiredDocs,
+    constraints: analysis.constraints.length ? analysis.constraints : existingProjectConfig.constraints,
+    planner: existingProjectConfig.planner,
+  };
+
+  writeJson(context.backlogFile, backlog);
+  writeJson(context.projectFile, projectConfig);
+  writeStateMarkdown(context, renderAnalysisState(context, backlog, analysis));
+  writeStatus(context, {
+    ok: true,
+    stage: "analyzed",
+    taskId: null,
+    taskTitle: "",
+    runDir,
+    summary: summarizeBacklog(backlog),
+    message: analysis.summary.currentState,
+  });
+  writeText(path.join(runDir, "analysis-summary.txt"), buildAnalysisSummaryText(context, analysis, backlog));
+
+  return {
+    ok: true,
+    code: "analyzed",
+    context,
+    runDir,
+    analysis,
+    backlog,
+    summary: buildAnalysisSummaryText(context, analysis, backlog),
+  };
+}

package/src/cli.mjs

@@ -3,14 +3,36 @@ import { spawnSync } from "node:child_process";
 
 import { createContext } from "./context.mjs";
 import { fileExists } from "./common.mjs";
+import { analyzeWorkspace } from "./analyzer.mjs";
 import { scaffoldIfMissing } from "./config.mjs";
+import { resolveRepoRoot } from "./discovery.mjs";
 import { installPluginBundle } from "./install.mjs";
 import { runLoop, runOnce, renderStatusText } from "./runner.mjs";
 
 const REPO_ROOT_PLACEHOLDER = "<REPO_ROOT>";
+const DOCS_PATH_PLACEHOLDER = "<DOCS_PATH>";
+const KNOWN_COMMANDS = new Set([
+  "analyze",
+  "install",
+  "init",
+  "status",
+  "next",
+  "run-once",
+  "run-loop",
+  "doctor",
+  "help",
+  "--help",
+  "-h",
+]);
 
 function parseArgs(argv) {
-  const [command = "status", ...rest] = argv;
+  const [first = "", ...restArgs] = argv;
+  const command = !first
+    ? "analyze"
+    : (KNOWN_COMMANDS.has(first) ? first : "analyze");
+  const rest = !first
+    ? []
+    : (KNOWN_COMMANDS.has(first) ? restArgs : argv);
   const options = {
     requiredDocs: [],
     constraints: [],
@@ -26,10 +48,12 @@ function parseArgs(argv) {
     else if (arg === "--max-attempts") { options.maxAttempts = Number(rest[index + 1]); index += 1; }
     else if (arg === "--max-strategies") { options.maxStrategies = Number(rest[index + 1]); index += 1; }
     else if (arg === "--repo") { options.repoRoot = rest[index + 1]; index += 1; }
+    else if (arg === "--docs") { options.docsPath = rest[index + 1]; index += 1; }
     else if (arg === "--codex-home") { options.codexHome = rest[index + 1]; index += 1; }
     else if (arg === "--config-dir") { options.configDirName = rest[index + 1]; index += 1; }
     else if (arg === "--required-doc") { options.requiredDocs.push(rest[index + 1]); index += 1; }
     else if (arg === "--constraint") { options.constraints.push(rest[index + 1]); index += 1; }
+    else if (!options.inputPath) { options.inputPath = arg; }
     else {
       throw new Error(`未知参数：${arg}`);
     }
@@ -40,9 +64,10 @@ function parseArgs(argv) {
 
 function helpText() {
   return [
-    "用法：helloloop <command> [options]",
+    "用法：helloloop [command] [path] [options]",
     "",
     "命令：",
+    "  analyze               自动发现仓库与开发文档，分析当前进度并生成/刷新 .helloloop（默认）",
     "  install               安装插件到 Codex Home（适合 npx / npm bin 分发）",
     "  init                  初始化 .helloloop 配置",
     "  status                查看 backlog 与下一任务",
@@ -53,7 +78,8 @@ function helpText() {
     "",
     "选项：",
     "  --codex-home <dir>    Codex Home，install 默认使用 ~/.codex",
-    "  --repo <dir>          目标仓库根目录，默认当前目录",
+    "  --repo <dir>          高级选项：显式指定项目仓库根目录",
+    "  --docs <dir|file>     高级选项：显式指定开发文档目录或文件",
     "  --config-dir <dir>    配置目录，默认 .helloloop",
     "  --dry-run             只生成提示与预览，不真正调用 codex",
     "  --task-id <id>        指定任务 id",
@@ -73,8 +99,9 @@ function printHelp() {
 function renderFollowupExamples() {
   return [
     "下一步示例：",
-    `npx helloloop doctor --repo ${REPO_ROOT_PLACEHOLDER}`,
-    `如已全局安装，也可直接运行：helloloop doctor --repo ${REPO_ROOT_PLACEHOLDER}`,
+    `npx helloloop`,
+    `npx helloloop next`,
+    `如需显式补充路径：npx helloloop --repo ${REPO_ROOT_PLACEHOLDER} --docs ${DOCS_PATH_PLACEHOLDER}`,
   ].join("\n");
 }
 
@@ -159,6 +186,23 @@ async function runDoctor(context) {
   }
 }
 
+function resolveContextFromOptions(options) {
+  const resolvedRepo = resolveRepoRoot({
+    cwd: process.cwd(),
+    repoRoot: options.repoRoot,
+    inputPath: options.inputPath,
+  });
+
+  if (!resolvedRepo.ok) {
+    throw new Error(resolvedRepo.message);
+  }
+
+  return createContext({
+    repoRoot: resolvedRepo.repoRoot,
+    configDirName: options.configDirName,
+  });
+}
+
 export async function runCli(argv) {
   const { command, options } = parseArgs(argv);
 
@@ -167,12 +211,11 @@ export async function runCli(argv) {
     return;
   }
 
-  const context = createContext({
-    repoRoot: options.repoRoot,
-    configDirName: options.configDirName,
-  });
-
   if (command === "install") {
+    const context = createContext({
+      repoRoot: options.repoRoot,
+      configDirName: options.configDirName,
+    });
     const result = installPluginBundle({
       bundleRoot: context.bundleRoot,
       codexHome: options.codexHome,
@@ -185,6 +228,27 @@ export async function runCli(argv) {
     return;
   }
 
+  if (command === "analyze") {
+    const result = await analyzeWorkspace({
+      cwd: process.cwd(),
+      inputPath: options.inputPath,
+      repoRoot: options.repoRoot,
+      docsPath: options.docsPath,
+      configDirName: options.configDirName,
+    });
+
+    if (!result.ok) {
+      console.error(result.summary);
+      process.exitCode = 1;
+      return;
+    }
+
+    console.log(result.summary);
+    return;
+  }
+
+  const context = resolveContextFromOptions(options);
+
   if (command === "init") {
     const created = scaffoldIfMissing(context);
     if (!created.length) {

package/src/discovery.mjs

@@ -0,0 +1,155 @@
+import path from "node:path";
+
+import { expandDocumentEntries } from "./doc_loader.mjs";
+import {
+  classifyExplicitPath,
+  findRepoRootFromPath,
+  looksLikeProjectRoot,
+  normalizeForRepo,
+  pathExists,
+  resolveAbsolute,
+} from "./discovery_paths.mjs";
+import {
+  inferDocsForRepo,
+  inferRepoFromDocs,
+  renderMissingDocsMessage,
+  renderMissingRepoMessage,
+} from "./discovery_inference.mjs";
+
+export { findRepoRootFromPath } from "./discovery_paths.mjs";
+
+export function discoverWorkspace(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const configDirName = options.configDirName || ".helloloop";
+  const explicitRepoRoot = options.repoRoot ? resolveAbsolute(options.repoRoot, cwd) : "";
+  const explicitDocsPath = options.docsPath ? resolveAbsolute(options.docsPath, cwd) : "";
+  const explicitInputPath = options.inputPath ? resolveAbsolute(options.inputPath, cwd) : "";
+
+  if (explicitRepoRoot && !pathExists(explicitRepoRoot)) {
+    return { ok: false, code: "missing_repo_path", message: `项目路径不存在：${explicitRepoRoot}` };
+  }
+  if (explicitDocsPath && !pathExists(explicitDocsPath)) {
+    return { ok: false, code: "missing_docs_path", message: `开发文档路径不存在：${explicitDocsPath}` };
+  }
+
+  let repoRoot = explicitRepoRoot;
+  let docsEntries = explicitDocsPath ? [explicitDocsPath] : [];
+  let docCandidates = [];
+  let repoCandidates = [];
+
+  if (!repoRoot && !docsEntries.length) {
+    const classified = classifyExplicitPath(explicitInputPath);
+    if (classified.kind === "missing") {
+      return { ok: false, code: "missing_input_path", message: `路径不存在：${classified.absolutePath}` };
+    }
+    if (classified.kind === "docs") {
+      docsEntries = [classified.absolutePath];
+    }
+    if (classified.kind === "repo") {
+      repoRoot = classified.absolutePath;
+    }
+  }
+
+  if (!repoRoot && !docsEntries.length) {
+    const cwdRepoRoot = findRepoRootFromPath(cwd);
+    if (cwdRepoRoot) {
+      repoRoot = cwdRepoRoot;
+    } else if (classifyExplicitPath(cwd).kind === "docs") {
+      docsEntries = [cwd];
+    } else if (looksLikeProjectRoot(cwd)) {
+      repoRoot = cwd;
+    }
+  }
+
+  if (!repoRoot && docsEntries.length) {
+    const inferred = inferRepoFromDocs(docsEntries, cwd);
+    repoRoot = inferred.repoRoot;
+    repoCandidates = inferred.candidates;
+  }
+
+  if (!repoRoot) {
+    return {
+      ok: false,
+      code: "missing_repo",
+      message: renderMissingRepoMessage(docsEntries, repoCandidates),
+    };
+  }
+
+  repoRoot = findRepoRootFromPath(repoRoot) || repoRoot;
+  docsEntries = docsEntries.map((entry) => normalizeForRepo(repoRoot, entry));
+
+  if (!docsEntries.length) {
+    const inferred = inferDocsForRepo(repoRoot, cwd, configDirName);
+    docsEntries = inferred.docsEntries;
+    docCandidates = inferred.candidates;
+  }
+
+  if (!docsEntries.length) {
+    return {
+      ok: false,
+      code: "missing_docs",
+      repoRoot,
+      message: renderMissingDocsMessage(repoRoot),
+      candidates: docCandidates,
+    };
+  }
+
+  const resolvedDocs = expandDocumentEntries(repoRoot, docsEntries);
+  if (!resolvedDocs.length) {
+    return {
+      ok: false,
+      code: "invalid_docs",
+      repoRoot,
+      message: renderMissingDocsMessage(repoRoot),
+    };
+  }
+
+  return {
+    ok: true,
+    repoRoot,
+    docsEntries,
+    resolvedDocs,
+  };
+}
+
+export function resolveRepoRoot(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const explicitRepoRoot = options.repoRoot ? resolveAbsolute(options.repoRoot, cwd) : "";
+  const explicitInputPath = options.inputPath ? resolveAbsolute(options.inputPath, cwd) : "";
+
+  if (explicitRepoRoot) {
+    if (!pathExists(explicitRepoRoot)) {
+      return { ok: false, message: `项目路径不存在：${explicitRepoRoot}` };
+    }
+    return { ok: true, repoRoot: findRepoRootFromPath(explicitRepoRoot) || explicitRepoRoot };
+  }
+
+  const classified = classifyExplicitPath(explicitInputPath);
+  if (classified.kind === "missing") {
+    return { ok: false, message: `路径不存在：${classified.absolutePath}` };
+  }
+  if (classified.kind === "repo") {
+    return { ok: true, repoRoot: findRepoRootFromPath(classified.absolutePath) || classified.absolutePath };
+  }
+  if (classified.kind === "docs") {
+    const inferred = inferRepoFromDocs([classified.absolutePath], cwd);
+    if (inferred.repoRoot) {
+      return { ok: true, repoRoot: inferred.repoRoot };
+    }
+    return { ok: false, message: renderMissingRepoMessage([classified.absolutePath], inferred.candidates) };
+  }
+
+  const repoRoot = findRepoRootFromPath(cwd);
+  if (repoRoot) {
+    return { ok: true, repoRoot };
+  }
+
+  if (looksLikeProjectRoot(cwd)) {
+    return { ok: true, repoRoot: cwd };
+  }
+
+  return {
+    ok: false,
+    message: "当前目录不是项目仓库。请切到项目目录，或传入一个项目路径/开发文档路径。",
+  };
+}