helloloop 0.1.1 → 0.2.0

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: "当前目录不是项目仓库。请切到项目目录，或传入一个项目路径/开发文档路径。",
+  };
+}

package/src/discovery_inference.mjs

@@ -0,0 +1,220 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { readJson } from "./common.mjs";
+import { expandDocumentEntries } from "./doc_loader.mjs";
+import {
+  findRepoRootFromPath,
+  isDocFile,
+  isDocsDirectory,
+  looksLikeProjectRoot,
+  normalizeForRepo,
+  pathExists,
+  resolveAbsolute,
+  uniquePaths,
+} from "./discovery_paths.mjs";
+
+function loadExistingRequiredDocs(repoRoot, configDirName) {
+  const projectFile = path.join(repoRoot, configDirName, "project.json");
+  if (!pathExists(projectFile)) {
+    return [];
+  }
+
+  const projectConfig = readJson(projectFile);
+  const entries = Array.isArray(projectConfig.requiredDocs) ? projectConfig.requiredDocs : [];
+  const resolved = expandDocumentEntries(repoRoot, entries);
+  return resolved.length ? entries : [];
+}
+
+function readDocPreview(docEntries, cwd) {
+  let remaining = 24000;
+  const snippets = [];
+
+  for (const entry of docEntries) {
+    const expanded = expandDocumentEntries(cwd, [entry]);
+    for (const file of expanded) {
+      if (remaining <= 0) {
+        return snippets.join("\n");
+      }
+
+      const content = fs.readFileSync(file.absolutePath, "utf8");
+      const slice = content.slice(0, Math.min(content.length, remaining));
+      snippets.push(slice);
+      remaining -= slice.length;
+    }
+  }
+
+  return snippets.join("\n");
+}
+
+function normalizePathHint(rawValue) {
+  const trimmed = String(rawValue || "").trim().replace(/^["'`(<\[]+|[>"'`)\].,;:]+$/g, "");
+  if (/^\/[A-Za-z]:[\\/]/.test(trimmed)) {
+    return trimmed.slice(1);
+  }
+  return trimmed;
+}
+
+function extractPathHintsFromText(text) {
+  const hints = new Set();
+  const normalizedText = String(text || "");
+  const windowsMatches = normalizedText.match(/\/?[A-Za-z]:[\\/][^\s"'`<>()\]]+/g) || [];
+  const posixMatches = normalizedText.match(/(?:^|[\s("'`])\/[^\s"'`<>()\]]+/g) || [];
+
+  for (const rawMatch of [...windowsMatches, ...posixMatches]) {
+    const normalized = normalizePathHint(rawMatch);
+    if (normalized) {
+      hints.add(normalized);
+    }
+  }
+
+  return [...hints];
+}
+
+function extractRepoNameHintsFromText(text) {
+  const hints = new Set();
+  const matches = String(text || "").match(/`([A-Za-z0-9._-]{3,})`/g) || [];
+
+  for (const match of matches) {
+    const value = match.slice(1, -1);
+    if (/^(docs?|src|tests?|readme|sqlite|wal|sqlcipher)$/i.test(value)) {
+      continue;
+    }
+    hints.add(value.toLowerCase());
+  }
+
+  return [...hints];
+}
+
+function listNearbyProjectCandidates(searchRoot) {
+  if (!pathExists(searchRoot) || !fs.statSync(searchRoot).isDirectory()) {
+    return [];
+  }
+
+  return fs.readdirSync(searchRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(searchRoot, entry.name))
+    .filter((directoryPath) => looksLikeProjectRoot(directoryPath));
+}
+
+export function inferRepoFromDocs(docEntries, cwd) {
+  const expandedFiles = expandDocumentEntries(cwd, docEntries);
+  const absoluteEntries = expandedFiles.map((item) => item.absolutePath);
+
+  for (const absolutePath of absoluteEntries) {
+    const repoRoot = findRepoRootFromPath(absolutePath);
+    if (repoRoot) {
+      return {
+        repoRoot,
+        candidates: [repoRoot],
+        source: "ancestor",
+      };
+    }
+  }
+
+  const previewText = readDocPreview(docEntries, cwd);
+  const pathHintCandidates = extractPathHintsFromText(previewText)
+    .map((item) => resolveAbsolute(item, cwd))
+    .filter((candidate) => pathExists(candidate))
+    .map((candidate) => (fs.statSync(candidate).isDirectory() ? candidate : path.dirname(candidate)))
+    .map((candidate) => findRepoRootFromPath(candidate) || (looksLikeProjectRoot(candidate) ? candidate : ""))
+    .filter(Boolean);
+
+  const uniquePathCandidates = uniquePaths(pathHintCandidates);
+  if (uniquePathCandidates.length === 1) {
+    return {
+      repoRoot: uniquePathCandidates[0],
+      candidates: uniquePathCandidates,
+      source: "doc_path_hint",
+    };
+  }
+
+  const repoNameHints = extractRepoNameHintsFromText(previewText);
+  const searchRoots = uniquePaths(
+    absoluteEntries.flatMap((absolutePath) => {
+      const directory = fs.statSync(absolutePath).isDirectory()
+        ? absolutePath
+        : path.dirname(absolutePath);
+      const parent = path.dirname(directory);
+      return [directory, parent, path.dirname(parent)];
+    }),
+  );
+  const nearbyCandidates = uniquePaths(
+    searchRoots.flatMap((searchRoot) => listNearbyProjectCandidates(searchRoot)),
+  );
+  const namedCandidates = nearbyCandidates.filter((directoryPath) => (
+    repoNameHints.includes(path.basename(directoryPath).toLowerCase())
+  ));
+
+  if (namedCandidates.length === 1) {
+    return {
+      repoRoot: namedCandidates[0],
+      candidates: namedCandidates,
+      source: "doc_repo_name_hint",
+    };
+  }
+
+  return {
+    repoRoot: "",
+    candidates: uniquePaths([...uniquePathCandidates, ...namedCandidates]),
+    source: "",
+  };
+}
+
+export function inferDocsForRepo(repoRoot, cwd, configDirName) {
+  const existingRequiredDocs = loadExistingRequiredDocs(repoRoot, configDirName);
+  if (existingRequiredDocs.length) {
+    return {
+      docsEntries: existingRequiredDocs,
+      source: "existing_state",
+      candidates: existingRequiredDocs,
+    };
+  }
+
+  const cwdIsDocSource = pathExists(cwd) && (isDocFile(cwd) || isDocsDirectory(cwd));
+  if (cwdIsDocSource) {
+    return {
+      docsEntries: [normalizeForRepo(repoRoot, cwd)],
+      source: "cwd",
+      candidates: [cwd],
+    };
+  }
+
+  const repoDocsCandidates = uniquePaths([
+    path.join(repoRoot, "docs"),
+    path.join(repoRoot, "Docs"),
+  ].filter((candidate) => isDocsDirectory(candidate)));
+
+  if (repoDocsCandidates.length === 1) {
+    return {
+      docsEntries: [normalizeForRepo(repoRoot, repoDocsCandidates[0])],
+      source: "repo_docs",
+      candidates: repoDocsCandidates,
+    };
+  }
+
+  return {
+    docsEntries: [],
+    source: "",
+    candidates: repoDocsCandidates,
+  };
+}
+
+export function renderMissingRepoMessage(docEntries, candidates) {
+  return [
+    "无法自动确定要开发的项目仓库路径。",
+    docEntries.length ? `已找到开发文档：${docEntries.join(", ")}` : "",
+    candidates.length > 1 ? `本地发现多个候选项目：${candidates.map((item) => path.basename(item)).join(", ")}` : "",
+    "请补充项目仓库路径后重试，例如：",
+    "npx helloloop --repo <PROJECT_ROOT>",
+  ].filter(Boolean).join("\n");
+}
+
+export function renderMissingDocsMessage(repoRoot) {
+  return [
+    "无法自动确定开发文档位置。",
+    `已找到项目仓库：${repoRoot}`,
+    "请补充开发文档路径后重试，例如：",
+    "npx helloloop --docs <DOCS_PATH>",
+  ].join("\n");
+}

package/src/discovery_paths.mjs

@@ -0,0 +1,166 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { fileExists } from "./common.mjs";
+
+const DOC_FILE_SUFFIX = new Set([
+  ".md",
+  ".markdown",
+  ".mdx",
+  ".txt",
+  ".rst",
+  ".adoc",
+]);
+
+const DOC_DIR_NAMES = new Set([
+  "docs",
+  "doc",
+  "documentation",
+]);
+
+const PROJECT_MARKERS = [
+  ".git",
+  "package.json",
+  "pyproject.toml",
+  "Cargo.toml",
+  "go.mod",
+  "pom.xml",
+  "composer.json",
+];
+
+const PROJECT_DIR_MARKERS = [
+  "src",
+  "app",
+  "apps",
+  "packages",
+  "tests",
+];
+
+function directoryContainsDocs(directoryPath) {
+  if (!pathExists(directoryPath) || !fs.statSync(directoryPath).isDirectory()) {
+    return false;
+  }
+
+  const entries = fs.readdirSync(directoryPath, { withFileTypes: true });
+  return entries.some((entry) => (
+    entry.isFile() && DOC_FILE_SUFFIX.has(path.extname(entry.name).toLowerCase())
+  ));
+}
+
+function walkUpDirectories(startPath) {
+  const directories = [];
+  let current = fs.statSync(startPath).isDirectory()
+    ? startPath
+    : path.dirname(startPath);
+
+  while (true) {
+    directories.push(current);
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+
+  return directories;
+}
+
+export function resolveAbsolute(rawPath, cwd) {
+  return path.isAbsolute(rawPath)
+    ? path.resolve(rawPath)
+    : path.resolve(cwd, rawPath);
+}
+
+export function pathExists(targetPath) {
+  return fileExists(targetPath);
+}
+
+export function isDocFile(targetPath) {
+  return pathExists(targetPath)
+    && fs.statSync(targetPath).isFile()
+    && DOC_FILE_SUFFIX.has(path.extname(targetPath).toLowerCase());
+}
+
+export function looksLikeProjectRoot(directoryPath) {
+  if (!pathExists(directoryPath) || !fs.statSync(directoryPath).isDirectory()) {
+    return false;
+  }
+
+  if (PROJECT_MARKERS.some((name) => pathExists(path.join(directoryPath, name)))) {
+    return true;
+  }
+
+  return PROJECT_DIR_MARKERS.some((name) => pathExists(path.join(directoryPath, name)));
+}
+
+export function isDocsDirectory(directoryPath) {
+  if (!pathExists(directoryPath) || !fs.statSync(directoryPath).isDirectory()) {
+    return false;
+  }
+
+  const baseName = path.basename(directoryPath).toLowerCase();
+  if (DOC_DIR_NAMES.has(baseName)) {
+    return true;
+  }
+
+  return directoryContainsDocs(directoryPath) && !looksLikeProjectRoot(directoryPath);
+}
+
+export function findRepoRootFromPath(startPath) {
+  if (!pathExists(startPath)) {
+    return "";
+  }
+
+  for (const directory of walkUpDirectories(startPath)) {
+    if (pathExists(path.join(directory, ".git"))) {
+      return directory;
+    }
+  }
+
+  if (fs.statSync(startPath).isDirectory() && looksLikeProjectRoot(startPath)) {
+    return startPath;
+  }
+
+  return "";
+}
+
+export function normalizeForRepo(repoRoot, targetPath) {
+  const relative = path.relative(repoRoot, targetPath);
+  if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
+    return relative.replaceAll("\\", "/");
+  }
+
+  return targetPath.replaceAll("\\", "/");
+}
+
+export function uniquePaths(items) {
+  const seen = new Set();
+  return items.filter((item) => {
+    const key = path.resolve(item).toLowerCase();
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+}
+
+export function classifyExplicitPath(inputPath) {
+  if (!inputPath) {
+    return { kind: "", absolutePath: "" };
+  }
+
+  if (!pathExists(inputPath)) {
+    return { kind: "missing", absolutePath: inputPath };
+  }
+
+  if (isDocFile(inputPath) || isDocsDirectory(inputPath)) {
+    return { kind: "docs", absolutePath: inputPath };
+  }
+
+  if (fs.statSync(inputPath).isDirectory()) {
+    return { kind: "repo", absolutePath: inputPath };
+  }
+
+  return { kind: "unsupported", absolutePath: inputPath };
+}

package/src/guardrails.mjs

@@ -0,0 +1,59 @@
+function normalizeRule(rule) {
+  return String(rule || "").trim();
+}
+
+function uniqueRules(items) {
+  const result = [];
+  const seen = new Set();
+
+  for (const item of items || []) {
+    const normalized = normalizeRule(item);
+    if (!normalized) {
+      continue;
+    }
+
+    const key = normalized.toLowerCase();
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    result.push(normalized);
+  }
+
+  return result;
+}
+
+const mandatoryGuardrails = [
+  "所有 shell 操作优先使用结构化命令与参数，避免字符串拼接命令。",
+  "涉及路径的 shell 操作必须正确引用路径，避免空格、中文、特殊字符造成路径逃逸。",
+  "涉及多路径或多子命令时必须拆成多次独立执行，禁止把多个路径操作拼接进单条命令。",
+  "Windows 环境禁止使用 cmd /c、cmd.exe、Start-Process cmd 或任何 cmd 嵌套命令；只允许 pwsh、bash（如 Git Bash）或 powershell 这类安全 shell。",
+  "涉及删除、移动、覆盖等危险文件操作前，必须先确认目标路径位于当前仓库或用户明确允许的目录内。",
+  "禁止执行 EHRB 高风险命令或其等价危险操作，例如 rm -rf /、git reset --hard、DROP DATABASE、FLUSHALL 等。",
+  "不得把密钥、令牌、.env、PII、真实绝对隐私路径写入代码、日志、文档和最终输出。",
+  "目标实现必须兼容 Windows、macOS、Linux，禁止硬编码平台专属路径分隔符或 shell 语法。",
+];
+
+const defaultProjectConstraints = [
+  "代码是事实源；文档与代码冲突时，以当前代码、测试和真实目录结构为准。",
+  "产出必须达到专业级水准：架构清晰、实现完整、表达专业，不接受“能用就行”的交付。",
+  "所有文件修改必须使用当前环境提供的安全编辑方式，例如 apply_patch，而不是危险的原地批量命令。",
+  "不得通过压缩代码、删除必要空行、缩短命名来规避体积控制；单文件超过 400 行后按职责拆分。",
+  "不添加不必要的抽象层；仅为复杂逻辑添加必要注释，新增公共函数补简洁说明。",
+  "完成前必须主动运行验证；失败后先分析根因，再修复并重跑。",
+  "不允许静默失败、静默降级、静默回退；遇到阻塞必须明确说明原因。",
+];
+
+export function listMandatoryGuardrails() {
+  return [...mandatoryGuardrails];
+}
+
+export function hasCustomProjectConstraints(items = []) {
+  return uniqueRules(items).length > 0;
+}
+
+export function resolveProjectConstraints(items = []) {
+  const customRules = uniqueRules(items);
+  return customRules.length ? customRules : [...defaultProjectConstraints];
+}