helloloop 0.1.1 → 0.1.2

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];
+}

package/src/install.mjs

@@ -10,6 +10,7 @@ const __dirname = path.dirname(__filename);
 
 export const runtimeBundleEntries = [
   ".codex-plugin",
+  "LICENSE",
   "README.md",
   "bin",
   "package.json",
@@ -73,8 +74,6 @@ function updateMarketplace(marketplaceFile) {
     category: "Coding",
   };
 
-  marketplace.plugins = marketplace.plugins.filter((plugin) => plugin?.name !== "autoloop");
-
   const existingIndex = marketplace.plugins.findIndex((plugin) => plugin?.name === "helloloop");
   if (existingIndex >= 0) {
     marketplace.plugins.splice(existingIndex, 1, nextEntry);
@@ -90,7 +89,6 @@ export function installPluginBundle(options = {}) {
   const resolvedCodexHome = resolveCodexHome(options.codexHome);
   const targetPluginsRoot = path.join(resolvedCodexHome, "plugins");
   const targetPluginRoot = path.join(targetPluginsRoot, "helloloop");
-  const legacyPluginRoot = path.join(targetPluginsRoot, "autoloop");
   const marketplaceFile = path.join(resolvedCodexHome, ".agents", "plugins", "marketplace.json");
   const manifestFile = path.join(bundleRoot, ".codex-plugin", "plugin.json");
 
@@ -107,10 +105,6 @@ export function installPluginBundle(options = {}) {
     fs.rmSync(targetPluginRoot, { recursive: true, force: true });
   }
 
-  if (fileExists(legacyPluginRoot)) {
-    fs.rmSync(legacyPluginRoot, { recursive: true, force: true });
-  }
-
   ensureDir(targetPluginsRoot);
   ensureDir(targetPluginRoot);
   copyBundleEntries(bundleRoot, targetPluginRoot);

package/src/process.mjs

@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
-import { spawn, spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 
 import { ensureDir, nowIso, tailText, writeText } from "./common.mjs";
+import { resolveCodexInvocation, resolveVerifyShellInvocation } from "./shell_invocation.mjs";
 
 function runChild(command, args, options = {}) {
   return new Promise((resolve) => {
@@ -51,130 +52,6 @@ function runChild(command, args, options = {}) {
   });
 }
 
-function quoteForCmd(value) {
-  const normalized = String(value ?? "");
-  if (!normalized.length) {
-    return "\"\"";
-  }
-  if (!/[\s"&<>|^]/.test(normalized)) {
-    return normalized;
-  }
-  return `"${normalized.replace(/"/g, "\"\"")}"`;
-}
-
-function buildCmdCommandLine(executable, args) {
-  return [quoteForCmd(executable), ...args.map((item) => quoteForCmd(item))].join(" ");
-}
-
-function hasCommand(command, platform = process.platform) {
-  if (platform === "win32") {
-    const result = spawnSync("where.exe", [command], {
-      encoding: "utf8",
-      shell: false,
-    });
-    return result.status === 0;
-  }
-
-  const result = spawnSync("sh", ["-lc", `command -v ${command}`], {
-    encoding: "utf8",
-    shell: false,
-  });
-  return result.status === 0;
-}
-
-export function resolveVerifyShellInvocation(options = {}) {
-  const platform = options.platform || process.platform;
-  const commandExists = options.commandExists || ((command) => hasCommand(command, platform));
-
-  if (platform === "win32") {
-    if (commandExists("pwsh")) {
-      return {
-        command: "pwsh",
-        argsPrefix: ["-NoLogo", "-NoProfile", "-Command"],
-        shell: false,
-      };
-    }
-
-    if (commandExists("powershell")) {
-      return {
-        command: "powershell",
-        argsPrefix: ["-NoLogo", "-NoProfile", "-Command"],
-        shell: false,
-      };
-    }
-
-    return {
-      command: "cmd.exe",
-      argsPrefix: ["/d", "/s", "/c"],
-      shell: false,
-    };
-  }
-
-  return {
-    command: "sh",
-    argsPrefix: ["-lc"],
-    shell: false,
-  };
-}
-
-function resolveCodexExecutable(explicitExecutable = "") {
-  if (explicitExecutable) {
-    return explicitExecutable;
-  }
-
-  if (process.platform !== "win32") {
-    return "codex";
-  }
-
-  const candidates = ["codex.cmd", "codex", "codex.ps1"];
-  for (const candidate of candidates) {
-    const result = spawnSync("where.exe", [candidate], {
-      encoding: "utf8",
-      shell: false,
-    });
-    if (result.status !== 0) {
-      continue;
-    }
-
-    const firstLine = String(result.stdout || "")
-      .split(/\r?\n/)
-      .map((line) => line.trim())
-      .find(Boolean);
-    if (firstLine) {
-      return firstLine;
-    }
-  }
-
-  return "codex";
-}
-
-function resolveCodexInvocation(explicitExecutable = "") {
-  const executable = resolveCodexExecutable(explicitExecutable);
-
-  if (process.platform === "win32" && /\.ps1$/i.test(executable)) {
-    return {
-      command: "pwsh",
-      argsPrefix: ["-NoLogo", "-NoProfile", "-File", executable],
-      shell: false,
-    };
-  }
-
-  if (process.platform === "win32" && /\.(cmd|bat)$/i.test(executable)) {
-    return {
-      command: "cmd.exe",
-      argsPrefix: ["/d", "/s", "/c"],
-      executable,
-      shell: false,
-    };
-  }
-
-  return {
-    command: executable,
-    argsPrefix: [],
-    shell: false,
-  };
-}
-
 function writeCodexRunArtifacts(runDir, prefix, result, finalMessage) {
   writeText(path.join(runDir, `${prefix}-stdout.log`), result.stdout);
   writeText(path.join(runDir, `${prefix}-stderr.log`), result.stderr);
@@ -205,7 +82,7 @@ export async function runCodexTask({
   ensureDir(runDir);
 
   const lastMessageFile = path.join(runDir, `${outputPrefix}-last-message.txt`);
-  const invocation = resolveCodexInvocation(executable);
+  const invocation = resolveCodexInvocation({ explicitExecutable: executable });
   const codexArgs = ["exec", "-C", context.repoRoot];
 
   if (model) {
@@ -230,9 +107,19 @@ export async function runCodexTask({
   }
   codexArgs.push("-o", lastMessageFile, "-");
 
-  const args = invocation.executable
-    ? [...invocation.argsPrefix, buildCmdCommandLine(invocation.executable, codexArgs)]
-    : [...invocation.argsPrefix, ...codexArgs];
+  if (invocation.error) {
+    const result = {
+      ok: false,
+      code: 1,
+      stdout: "",
+      stderr: invocation.error,
+    };
+    writeText(path.join(runDir, `${outputPrefix}-prompt.md`), prompt);
+    writeCodexRunArtifacts(runDir, outputPrefix, result, "");
+    return { ...result, finalMessage: "" };
+  }
+
+  const args = [...invocation.argsPrefix, ...codexArgs];
 
   const result = await runChild(invocation.command, args, {
     cwd: context.repoRoot,
@@ -266,6 +153,21 @@ export async function runCodexExec({ context, prompt, runDir, policy }) {
 
 export async function runShellCommand(context, commandLine, runDir, index) {
   const shellInvocation = resolveVerifyShellInvocation();
+  if (shellInvocation.error) {
+    const result = {
+      command: commandLine,
+      ok: false,
+      code: 1,
+      stdout: "",
+      stderr: shellInvocation.error,
+    };
+    const prefix = String(index + 1).padStart(2, "0");
+    writeText(path.join(runDir, `${prefix}-verify-command.txt`), commandLine);
+    writeText(path.join(runDir, `${prefix}-verify-stdout.log`), result.stdout);
+    writeText(path.join(runDir, `${prefix}-verify-stderr.log`), result.stderr);
+    return result;
+  }
+
   const result = await runChild(shellInvocation.command, [
     ...shellInvocation.argsPrefix,
     commandLine,